Ability to add options argument to event listener

[bencroker]

This PR adds the ability to add an options (or useCapture) argument to the event listener when using htmx.on().

As per the addEventListener() method spec, the third argument accepts an options object or a useCapture boolean.

Usage:

// Using an object
htmx.on('htmx:afterSwap', () => console.log('Swapped'), { once: true }); 
htmx.on('#my-div', 'htmx:afterSwap', () => console.log('Swapped'), { once: true });

// Using a boolean
htmx.on('htmx:afterSwap', () => console.log('Swapped'), true); 
htmx.on('#my-div', 'htmx:afterSwap', () => console.log('Swapped'), true);

Note to the reviewer: please double check my JSDoc annotations, I think they’re accurate but I’m not 100% sure.

Testing

I added a test that verifies that the options argument is respected.

htmx/test/core/events.js

Lines 80 to 93 in b266104

	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)
	}
	})

Checklist

• I have read the contribution guidelines
• I have targeted this PR against the correct branch (master for website changes, dev for
  source changes)
• This is either a bugfix, a documentation update, or a new feature that has been explicitly
  approved via an issue This is a minor addition to an existing feature, not pre-approved 😬
• I ran the test suite locally (npm run test) and verified that it succeeded

[Telroshan]

JSDoc seems perfectly fine to me!

[Telroshan]

Note that I'll remove the "ready for review" label for now; despite its generic name, we actually use this label just for 1cg, to tag PRs that are ready for his final review, meanwhile you can simply ping me for any update!

Hit me up when you figure out this useCapture test! At first glance, I'd expect the event.target to always equal the element that the event was triggered onto, no matter if useCapture is set, which would explain the test failure here?
I never use useCapture though so I may totally misundertand it!

[bencroker]

Note that I'll remove the "ready for review" label for now; despite its generic name, we actually use this label just for 1cg, to tag PRs that are ready for his final review

Apologies, I hadn’t realised that.

I never use useCapture though so I may totally misundertand it!

I’m just learning about it too, but in doing so I’m realising that there’s little or no value in us testing that the addEventListener() method works as it should, and I can’t come up with a useful test that confirms that we pass a third argument to it. I’m thinking that perhaps this addition doesn’t require a test 😱. What say you?

Note also that the useCapture boolean exists only for backwards compatibility, whereas the options object is the recommended way of passing in a third parameter, so if we must have a test, perhaps the events accept an options argument and the result works as expected test will suffice. See https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#browser_compatibility

[Telroshan]

I hadn’t realised that.

No worries, it isn't written anywhere and has been an implicit convention between us, you couldn't know!

perhaps this addition doesn’t require a test

Well, I agree on this, useCapture is indeed, according to the docs, the old parameter type, that has now been replaced by options which includes a capture property anyway.

As you have a test for once, there's no reason it wouldn't work for the other properties, and I agree that the current test is doing its job; proving that we correctly pass the options to addEventListener, we don't need more than that.

Besides, options isn't IE11 compatible, but as we dropped IE11 support for htmx 2 anyway, there's no need to go beyond reason on older browsers support either.

With that, back to ready for review!

[bencroker]

Merci!

[1cg]

great change ben!