Ability to add options argument to event listener (#2836)

* Update htmx.js

* Update events.js

* Add fallback value

* Use JSDoc syntax

* Document parameter

* Only accept an object

* Revert change

* Add useCapture

* Update htmx.js

* Add `useCapture` test

* Clean up

* Revert addition of test

src/htmx.js

@@ -1236,26 +1236,30 @@ var htmx = (function() {
    * @property {EventTarget} target
    * @property {AnyEventName} event
    * @property {EventListener} listener
+   * @property {Object|boolean} options
    */
 
   /**
    * @param {EventTarget|AnyEventName} arg1
    * @param {AnyEventName|EventListener} arg2
-   * @param {EventListener} [arg3]
+   * @param {EventListener|Object|boolean} [arg3]
+   * @param {Object|boolean} [arg4]
    * @returns {EventArgs}
    */
-  function processEventArgs(arg1, arg2, arg3) {
+  function processEventArgs(arg1, arg2, arg3, arg4) {
     if (isFunction(arg2)) {
       return {
         target: getDocument().body,
         event: asString(arg1),
-        listener: arg2
+        listener: arg2,
+        options: arg3
       }
     } else {
       return {
         target: resolveTarget(arg1),
         event: asString(arg2),
-        listener: arg3
+        listener: arg3,
+        options: arg4
       }
     }
   }
@@ -1267,13 +1271,14 @@ var htmx = (function() {
    *
    * @param {EventTarget|string} arg1 the element to add the listener to | the event name to add the listener for
    * @param {string|EventListener} arg2 the event name to add the listener for | the listener to add
-   * @param {EventListener} [arg3] the listener to add
+   * @param {EventListener|Object|boolean} [arg3] the listener to add | options to add
+   * @param {Object|boolean} [arg4] options to add
    * @returns {EventListener}
    */
-  function addEventListenerImpl(arg1, arg2, arg3) {
+  function addEventListenerImpl(arg1, arg2, arg3, arg4) {
     ready(function() {
-      const eventArgs = processEventArgs(arg1, arg2, arg3)
-      eventArgs.target.addEventListener(eventArgs.event, eventArgs.listener)
+      const eventArgs = processEventArgs(arg1, arg2, arg3, arg4)
+      eventArgs.target.addEventListener(eventArgs.event, eventArgs.listener, eventArgs.options)
     })
     const b = isFunction(arg2)
     return b ? arg2 : arg3

test/core/events.js

@@ -77,6 +77,21 @@ describe('Core htmx Events', function() {
     }
   })
 
+  it('events accept an options argument and the result works as expected', function() {
+    var invoked = 0
+    var handler = htmx.on('custom', function() {
+      invoked = invoked + 1
+    }, { once: true })
+    try {
+      var div = make("<div hx-post='/test'></div>")
+      htmx.trigger(div, 'custom')
+      htmx.trigger(div, 'custom')
+      invoked.should.equal(1)
+    } finally {
+      htmx.off('custom', handler)
+    }
+  })
+
   it('htmx:configRequest allows attribute removal', function() {
     var param = 'foo'
     var handler = htmx.on('htmx:configRequest', function(evt) {

www/content/api.md

@@ -316,12 +316,14 @@ Adds an event listener to an element
 
 * `eventName` - the event name to add the listener for
 * `listener` - the listener to add
+* `options` - an [options](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options) object (or a [useCapture](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#usecapture) boolean) to add to the event listener (optional)
 
 or
 
 * `target` - the element to add the listener to
 * `eventName` - the event name to add the listener for
 * `listener` - the listener to add
+* `options` - an [options](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options) object (or a [useCapture](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#usecapture) boolean) to add to the event listener (optional)
 
 ##### Example
 
@@ -331,6 +333,9 @@ or
 
     // add a click listener to the given div
     var myEventListener = htmx.on("#my-div", "click", function(evt){ console.log(evt); });
+
+    // add a click listener to the given div that should only be invoked once
+    var myEventListener = htmx.on("#my-div", "click", function(evt){ console.log(evt); }, { once: true });
 ```
 
 ### Method - `htmx.onLoad()` {#onLoad}