|
1 | | -const Behavior = require("receptor/behavior"); |
| 1 | +/** |
| 2 | + * Callback handler for component setup and teardown events. |
| 3 | + * |
| 4 | + * @typedef {(target?: HTMLElement) => any} BehaviorLifecycle |
| 5 | + */ |
2 | 6 |
|
3 | 7 | /** |
4 | | - * @name sequence |
5 | | - * @param {...Function} seq an array of functions |
6 | | - * @return { closure } callHooks |
| 8 | + * Options object for initializing a component's behavior and including additional properties in |
| 9 | + * the public interface of each initialized component. |
| 10 | + * |
| 11 | + * @typedef {Record<string, any> & { init?: BehaviorLifecycle, teardown?: BehaviorLifecycle }} BehaviorProps |
| 12 | + */ |
| 13 | + |
| 14 | +/** |
| 15 | + * Component initializer. |
| 16 | + * |
| 17 | + * @typedef {BehaviorProps & { |
| 18 | + * on: BehaviorLifecycle, |
| 19 | + * off: BehaviorLifecycle, |
| 20 | + * add: BehaviorLifecycle, |
| 21 | + * remove: BehaviorLifecycle, |
| 22 | + * }} Behavior |
| 23 | + */ |
| 24 | + |
| 25 | +/** |
| 26 | + * Event callback handler. |
| 27 | + * |
| 28 | + * @typedef {( |
| 29 | + * this: HTMLElement, |
| 30 | + * event: K extends keyof HTMLElementEventMap ? HTMLElementEventMap[K] : Event |
| 31 | + * ) => any} EventHandler |
| 32 | + * @template {string} K Event name(s) |
| 33 | + */ |
| 34 | + |
| 35 | +/** |
| 36 | + * Callback or object of selector-scoped callbacks. |
| 37 | + * |
| 38 | + * @typedef {EventHandler<K> | Record<string, EventHandler<K>>} EventHandlerOrSelectorMap |
| 39 | + * @template {string} K Event name(s) |
7 | 40 | */ |
8 | | -// We use a named function here because we want it to inherit its lexical scope |
9 | | -// from the behavior props object, not from the module |
10 | | -const sequence = (...seq) => |
11 | | - function callHooks(target = document.body) { |
12 | | - seq.forEach((method) => { |
13 | | - if (typeof this[method] === "function") { |
14 | | - this[method].call(this, target); |
15 | | - } |
16 | | - }); |
17 | | - }; |
18 | 41 |
|
19 | 42 | /** |
20 | | - * @name behavior |
21 | | - * @param {object} events |
22 | | - * @param {object?} props |
23 | | - * @return {receptor.behavior} |
| 43 | + * Object of component event handlers, where each event handler may be a callback function or an |
| 44 | + * object of selector-scoped callbacks. |
| 45 | + * |
| 46 | + * @typedef {Record<K, EventHandlerOrSelectorMap<K>>} Events |
| 47 | + * @template {string} K Event name(s) |
24 | 48 | */ |
25 | | -module.exports = (events, props) => |
26 | | - Behavior(events, { |
27 | | - on: sequence("init", "add"), |
28 | | - off: sequence("teardown", "remove"), |
29 | | - ...props, |
30 | | - }); |
| 49 | + |
| 50 | +/** |
| 51 | + * @param {Events<K>} events Object of component event handlers, where each event handler may be a |
| 52 | + * callback function or an object of selector-scoped callbacks. |
| 53 | + * @param {Partial<BehaviorProps>} props Additional properties to include in public interface of |
| 54 | + * each initialized component. |
| 55 | + * @template {string} K Event name(s) |
| 56 | + * |
| 57 | + * @return {Behavior} Component initializer. |
| 58 | + */ |
| 59 | + |
| 60 | +module.exports = (events, props) => { |
| 61 | + // Normalize event handlers to an array of arguments to be passed to either `addEventListener` or |
| 62 | + // `removeEventListener` during component initialization. |
| 63 | + const listeners = Object.entries(events).flatMap(([eventTypes, handlers]) => |
| 64 | + // Each event handler can be defined for one or more space-separated event names. |
| 65 | + eventTypes.split(" ").map( |
| 66 | + (eventType) => |
| 67 | + // Generate arguments of `[add/remove]EventListener` as [eventType, callback] |
| 68 | + /** @type {[keyof HTMLElementEventMap, EventHandler<any>]} */ ([ |
| 69 | + eventType, |
| 70 | + // Event handlers can be defined as a callback or object of selector-scoped callbacks. To |
| 71 | + // normalize as a function, create a function from a given object to perform the scoping |
| 72 | + // logic. |
| 73 | + typeof handlers === "function" |
| 74 | + ? handlers |
| 75 | + : (event) => |
| 76 | + // When a handler is defined as an object, event handling should terminate if any of |
| 77 | + // the scoped callbacks return `false`. This is accomplished by iterating over the |
| 78 | + // object's values as an array and using `Array#some` to abort at the first `false` |
| 79 | + // return value. |
| 80 | + Object.entries(handlers).some(([selector, handler]) => { |
| 81 | + // Since this event is attached at an ancestor and is handled using event |
| 82 | + // delegation, ensure that the actual event target is within the scoped selector. |
| 83 | + const target = event.target && event.target.closest(selector); |
| 84 | + return target && handler.call(target, event) === false; |
| 85 | + }), |
| 86 | + ]), |
| 87 | + ), |
| 88 | + ); |
| 89 | + |
| 90 | + /** |
| 91 | + * Initialize components within the given target, defaulting to the document body. |
| 92 | + * |
| 93 | + * @param {Element} target Ancestor element in which to initialized components. |
| 94 | + */ |
| 95 | + const on = (target = document.body) => { |
| 96 | + if (props && props.init) { |
| 97 | + props.init(target); |
| 98 | + } |
| 99 | + |
| 100 | + listeners.forEach((args) => target.addEventListener(...args)); |
| 101 | + }; |
| 102 | + |
| 103 | + /** |
| 104 | + * Remove component behaviors within the given target, defaulting to the document body. |
| 105 | + * |
| 106 | + * @param {Element} target Ancestor element in which to remove component behaviors. |
| 107 | + */ |
| 108 | + const off = (target = document.body) => { |
| 109 | + if (props && props.teardown) { |
| 110 | + props.teardown(target); |
| 111 | + } |
| 112 | + |
| 113 | + listeners.forEach((args) => target.removeEventListener(...args)); |
| 114 | + }; |
| 115 | + |
| 116 | + return { on, add: on, off, remove: off, ...props }; |
| 117 | +}; |
0 commit comments