Merge pull request #497 from atomiks/event-utils

[FEATURE] Event listener utils

snippets/off.md

@@ -0,0 +1,16 @@
+### off
+
+Removes an event listener from an element.
+
+Use `EventTarget.removeEventListener()` to remove an event listener from an element. 
+Omit the fourth argument `opts` to use `false` or specify it based on the options used when the event listener was added.
+
+```js
+const off = (el, evt, fn, opts = false) => el.removeEventListener(evt, fn, opts);
+```
+
+```js
+const fn = () => console.log('!');
+document.body.addEventListener('click', fn);
+off(document.body, 'click', fn); // no longer logs '!' upon clicking on the page
+```

snippets/on.md

@@ -0,0 +1,22 @@
+### on
+
+Adds an event listener to an element with the ability to use event delegation.
+
+Use `EventTarget.addEventListener()` to add an event listener to an element. If there is a `target` property supplied to the options object, ensure the event target matches the target specified and then invoke the callback by supplying the correct `this` context.
+Returns a reference to the custom delegator function, in order to be possible to use with [`off`](#off).
+Omit `opts` to default to non-delegation behavior and event bubbling.
+
+```js
+const on = (el, evt, fn, opts = {}) => {
+  const delegatorFn = e => e.target.matches(opts.target) && fn.call(e.target, e);
+  el.addEventListener(evt, opts.target ? delegatorFn : fn, opts.options || false);
+  if (opts.target) return delegatorFn;
+};
+```
+
+```js
+const fn = () => console.log('!');
+on(document.body, 'click', fn); // logs '!' upon clicking the body
+on(document.body, 'click', fn, { target: 'p' }); // logs '!' upon clicking a `p` element child of the body
+on(document.body, 'click', fn, { options: true }); // use capturing instead of bubbling
+```

tag_database

@@ -101,8 +101,10 @@ negate:logic,function
 nthElement:array
 objectFromPairs:object,array
 objectToPairs:object,array
+off:browser,event
+on:browser,event
 once:function
-onUserInputChange:browser,advanced
+onUserInputChange:browser,event,advanced
 orderBy:object,array
 palindrome:string
 percentile:math