Emit close reason with awesomplete-close events

Emit a reason when firing `awesomplete-close` events to provide
transparency to attached event listeners regarding the circumstance in
which the close was triggered. Reasons include `blur`, `esc`, `submit`,
`select`, and `nomatches`.

Closes #16897

8 files changed, 32 insertions, 16 deletions

diff --git a/awesomplete.js b/awesomplete.js
index 627f195..48c9e4b 100644
--- a/awesomplete.js
+++ b/awesomplete.js
@@ -55,7 +55,7 @@ var _ = function (input, o) {
 
 	$.bind(this.input, {
 		"input": this.evaluate.bind(this),
-		"blur": this.close.bind(this),
+		"blur": this.close.bind(this, { reason: 'blur' }),
 		"keydown": function(evt) {
 			var c = evt.keyCode;
 
@@ -67,7 +67,7 @@ var _ = function (input, o) {
 					me.select();
 				}
 				else if (c === 27) { // Esc
-					me.close();
+					me.close({ reason: 'esc' });
 				}
 				else if (c === 38 || c === 40) { // Down/Up arrow
 					evt.preventDefault();
@@ -77,7 +77,7 @@ var _ = function (input, o) {
 		}
 	});
 
-	$.bind(this.input.form, {"submit": this.close.bind(this)});
+	$.bind(this.input.form, {"submit": this.close.bind(this, { reason: 'submit' })});
 
 	$.bind(this.ul, {"mousedown": function(evt) {
 		var li = evt.target;
@@ -146,7 +146,7 @@ _.prototype = {
 		return !this.ul.hasAttribute("hidden");
 	},
 
-	close: function () {
+	close: function (o) {
 		if (!this.opened) {
 			return;
 		}
@@ -154,7 +154,7 @@ _.prototype = {
 		this.ul.setAttribute("hidden", "");
 		this.index = -1;
 
-		$.fire(this.input, "awesomplete-close");
+		$.fire(this.input, "awesomplete-close", o || {});
 	},
 
 	open: function () {
@@ -216,7 +216,7 @@ _.prototype = {
 
 			if (allowed) {
 				this.replace(suggestion);
-				this.close();
+				this.close({ reason: 'select' });
 				$.fire(this.input, "awesomplete-selectcomplete", {
 					text: suggestion
 				});
@@ -248,13 +248,13 @@ _.prototype = {
 				});
 
 			if (this.ul.children.length === 0) {
-				this.close();
+				this.close({ reason: 'nomatches' });
 			} else {
 				this.open();
 			}
 		}
 		else {
-			this.close();
+			this.close({ reason: 'nomatches' });
 		}
 	}
 };
diff --git a/index.html b/index.html
index 39bf74f..7bc53d0 100644
--- a/index.html
+++ b/index.html
@@ -312,7 +312,7 @@ We can also <strong>generate list items based on user's input</strong>. See E-ma
 			</tr>
 			<tr>
 				<td><code>awesomplete-close</code></td>
-				<td>The popup just closed.</td>
+				<td>The popup just closed. Callback will be passed an object with a <code>reason</code> property that indicates why the event was fired. Reasons include <code>"blur"</code>, <code>"esc"</code>, <code>"submit"</code>, <code>"select"</code>, and <code>"nomatches"</code>.</td>
 				<td>No</td>
 			</tr>
 			<tr>
diff --git a/test/api/closeSpec.js b/test/api/closeSpec.js
index 65228ff..a39687c 100644
--- a/test/api/closeSpec.js
+++ b/test/api/closeSpec.js
@@ -24,7 +24,9 @@ describe("awesomplete.close", function () {
 		var handler = $.spyOnEvent(this.subject.input, "awesomplete-close");
 		this.subject.close();
 
-		expect(handler).toHaveBeenCalled();
+		expect(handler).toHaveBeenCalledWith(
+			jasmine.any(document.createEvent('HTMLEvents').constructor)
+		);
 	});
 
 	it("returns early if already closed", function () {
diff --git a/test/api/evaluateSpec.js b/test/api/evaluateSpec.js
index 011835e..95d1c6d 100644
--- a/test/api/evaluateSpec.js
+++ b/test/api/evaluateSpec.js
@@ -15,7 +15,9 @@ describe("awesomplete.evaluate", function () {
 			spyOn(this.subject, "close");
 			this.subject.evaluate();
 
-			expect(this.subject.close).toHaveBeenCalled();
+			expect(this.subject.close).toHaveBeenCalledWith({
+				reason: 'nomatches'
+			});
 		});
 	});
 
@@ -28,7 +30,9 @@ describe("awesomplete.evaluate", function () {
 			spyOn(this.subject, "close");
 			this.subject.evaluate();
 
-			expect(this.subject.close).toHaveBeenCalled();
+			expect(this.subject.close).toHaveBeenCalledWith({
+				reason: 'nomatches'
+			});
 		});
 	});
 
diff --git a/test/api/selectSpec.js b/test/api/selectSpec.js
index f972142..4224301 100644
--- a/test/api/selectSpec.js
+++ b/test/api/selectSpec.js
@@ -66,7 +66,9 @@ describe("awesomplete.select", function () {
 				spyOn(this.subject, "close");
 				this.subject.select(this.selectArgument);
 
-				expect(this.subject.close).toHaveBeenCalled();
+				expect(this.subject.close).toHaveBeenCalledWith({
+					reason: 'select'
+				});
 			});
 
 			it("fires awesomplete-selectcomplete event", function () {
diff --git a/test/events/blurSpec.js b/test/events/blurSpec.js
index 2572179..cf5b7be 100644
--- a/test/events/blurSpec.js
+++ b/test/events/blurSpec.js
@@ -7,6 +7,9 @@ describe("blur event", function () {
 	it("closes completer", function () {
 		spyOn(Awesomplete.prototype, "close");
 		$.fire(this.subject.input, "blur");
-		expect(Awesomplete.prototype.close).toHaveBeenCalled();
+		expect(Awesomplete.prototype.close).toHaveBeenCalledWith(
+			{ reason: 'blur' },
+			jasmine.any(document.createEvent('HTMLEvents').constructor)
+		);
 	});
 });
diff --git a/test/events/keydownSpec.js b/test/events/keydownSpec.js
index 559d437..c34941b 100644
--- a/test/events/keydownSpec.js
+++ b/test/events/keydownSpec.js
@@ -23,7 +23,9 @@ describe("keydown event", function () {
 		spyOn(this.subject, "close");
 		$.keydown(this.subject.input, $.k.ESC);
 
-		expect(this.subject.close).toHaveBeenCalled();
+		expect(this.subject.close).toHaveBeenCalledWith({
+			reason: 'esc'
+		});
 	});
 
 	it("supports down arrow", function () {
diff --git a/test/events/submitSpec.js b/test/events/submitSpec.js
index c51a5cf..619ec82 100644
--- a/test/events/submitSpec.js
+++ b/test/events/submitSpec.js
@@ -9,6 +9,9 @@ describe("form submit event", function () {
 		// prevent full page reload in Firefox, which causes tests to stop running
 		$.on(this.subject.input.form, "submit", function (evt) { evt.preventDefault() });
 		$.fire(this.subject.input.form, "submit");
-		expect(Awesomplete.prototype.close).toHaveBeenCalled();
+		expect(Awesomplete.prototype.close).toHaveBeenCalledWith(
+			{ reason: 'submit' },
+			jasmine.any(document.createEvent('HTMLEvents').constructor)
+		);
 	});
 });