treeloom 0.0.0-stage → 2.0.0

package/dist/events/functions/addEventListener.js

@@ -0,0 +1,54 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const createEventListener_1 = __importDefault(require("../objects/createEventListener"));
+/**
+ * Create an EventListener descriptor and push it onto a DomItem's eventListeners for the given event name.
+ * Does not attach anything to the real element - see {@link bindListeners} or {@link fullAddEventListener} for that.
+ *
+ * item is the last parameter (instead of customArgs/options having literal defaults) so this can be curried and
+ * piped directly - see {@link fullAddEventListener} for an example.
+ *
+ * Prefer calling this through {@link fullAddEventListener} with a registered name (see {@link registerListener}).
+ * Passing a raw function directly here works, but logs a console warning - see {@link EventListener}'s
+ * listenerFunc property for what that discretionary path gives up.
+ * @param eventName - The name of the trigger event (e.g. 'click').
+ * @param listenerFunction - Preferably a name registered via
+ * {@link registerListener}; a raw listener function is also accepted, at the caller's discretion.
+ * @param customArgs - Additional args passed through to the listener when called.
+ * @param options - Options to be used when the listener is attached
+ * to the element.
+ * @param item - The DomItem which will receive the event listener.
+ * @returns The same DomItem, with the new EventListener descriptor appended.
+ */
+const addEventListener = (eventName, listenerFunction, customArgs, options, item) => {
+  customArgs = customArgs ?? null;
+  options = options ?? false;
+  if (typeof listenerFunction === 'function') {
+    console.warn(`addEventListener: attaching a raw function directly for "${eventName}" instead of a name registered via ` + 'registerListener. This works, but the listener will not be discoverable via eventActions, cannot be ' + 'shared by name across DomItems, and will be silently dropped by domItemToJson (JSON.stringify omits ' + 'function values). Prefer fullAddEventListener with a name unless this one-off behavior is intentional.');
+  }
+  if (typeof item.eventListeners === 'undefined') {
+    item.eventListeners = {};
+  }
+  if (typeof item.eventListeners[eventName] === 'undefined') {
+    item.eventListeners[eventName] = [];
+  }
+  // check if the listener already exists and don't add if it does
+  item.eventListeners[eventName].push((0, createEventListener_1.default)({
+    listenerFunc: listenerFunction,
+    listenerArgs: customArgs,
+    listenerOptions: options
+  }));
+  return item;
+};
+exports.default = addEventListener;

package/dist/events/functions/addEventListener.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const createEventListener_1=__importDefault(require("../objects/createEventListener")),addEventListener=(e,t,n,s,i)=>(n=n??null,s=s??!1,"function"==typeof t&&console.warn(`addEventListener: attaching a raw function directly for "${e}" instead of a name registered via registerListener. This works, but the listener will not be discoverable via eventActions, cannot be shared by name across DomItems, and will be silently dropped by domItemToJson (JSON.stringify omits function values). Prefer fullAddEventListener with a name unless this one-off behavior is intentional.`),void 0===i.eventListeners&&(i.eventListeners={}),void 0===i.eventListeners[e]&&(i.eventListeners[e]=[]),i.eventListeners[e].push((0,createEventListener_1.default)({listenerFunc:t,listenerArgs:n,listenerOptions:s})),i);exports.default=addEventListener;

package/dist/events/functions/applyActiveListeners.d.ts

@@ -0,0 +1,9 @@
+import type { DomItem } from '../../domItem/types';
+import type { EventName } from '../types';
+/**
+ * Apply each active event listener for event type to the DOM Item's element.
+ * @param eventName
+ * @param item
+ */
+declare const applyActiveListeners: (eventName: EventName, item: DomItem) => DomItem;
+export default applyActiveListeners;

package/dist/events/functions/applyActiveListeners.js

@@ -0,0 +1,52 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const si_funciona_1 = __importDefault(require("si-funciona"));
+const getListenerOptions_1 = __importDefault(require("../objects/options/getListenerOptions"));
+const numberToOptions_1 = __importDefault(require("../objects/options/numberToOptions"));
+const assignListener_1 = __importDefault(require("./assignListener"));
+const createEventProxy_1 = __importDefault(require("../objects/createEventProxy"));
+/**
+ * Apply each active event listener for event type to the DOM Item's element.
+ * @param eventName
+ * @param item
+ */
+const applyActiveListeners = (eventName, item) => {
+  const listenerOptions = (0, getListenerOptions_1.default)();
+  const eventOptions = si_funciona_1.default.dotGet(item, `activeListeners.${eventName}`);
+  if (eventOptions === null) {
+    return item;
+  }
+  si_funciona_1.default.objectKeys(eventOptions).forEach(binaryOptions => {
+    const optionsToUse = (0, numberToOptions_1.default)(listenerOptions, parseInt(binaryOptions));
+    const usesSignal = !!optionsToUse.signal;
+    if (!usesSignal) {
+      // Abort signal must be undefined if it is not required.
+      delete optionsToUse.signal;
+    }
+    ;
+    item.activeListeners[eventName][Number(binaryOptions)].forEach(eventResponder => {
+      if (eventResponder.assignedHandler) {
+        // already attached to the element
+        return;
+      }
+      const finalOptions = usesSignal ? Object.assign({}, optionsToUse, {
+        signal: eventResponder.abort.signal
+      }) : optionsToUse;
+      eventResponder.assignedHandler = e => eventResponder.handler((0, createEventProxy_1.default)(e, item));
+      (0, assignListener_1.default)(eventName, item.element, eventResponder.assignedHandler, finalOptions);
+    });
+  });
+  return item;
+};
+exports.default = applyActiveListeners;

package/dist/events/functions/applyActiveListeners.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const si_funciona_1=__importDefault(require("si-funciona")),getListenerOptions_1=__importDefault(require("../objects/options/getListenerOptions")),numberToOptions_1=__importDefault(require("../objects/options/numberToOptions")),assignListener_1=__importDefault(require("./assignListener")),createEventProxy_1=__importDefault(require("../objects/createEventProxy")),applyActiveListeners=(e,t)=>{const n=(0,getListenerOptions_1.default)(),s=si_funciona_1.default.dotGet(t,`activeListeners.${e}`);return null===s||si_funciona_1.default.objectKeys(s).forEach(s=>{const i=(0,numberToOptions_1.default)(n,parseInt(s)),r=!!i.signal;r||delete i.signal,t.activeListeners[e][Number(s)].forEach(n=>{if(n.assignedHandler)return;const s=r?Object.assign({},i,{signal:n.abort.signal}):i;n.assignedHandler=e=>n.handler((0,createEventProxy_1.default)(e,t)),(0,assignListener_1.default)(e,t.element,n.assignedHandler,s)})}),t};exports.default=applyActiveListeners;

package/dist/events/functions/assignListener.d.ts

@@ -0,0 +1,12 @@
+import type { EventHandler, ListenerOptions, ListenerTarget } from '../types';
+/**
+ * Provide compatibility for assigning listeners.
+ * @param trigger - The name of the event which will trigger the listenerFunction on the element. (keyof HTMLElementEventMap)
+ * @param elem - An element to append the listener onto
+ * @param fn - The function which will be invoked when the
+ * event is triggered
+ * @param options - Additional options to how the event will be
+ * fired
+ */
+declare const assignListener: (trigger: string, elem: ListenerTarget, fn: EventHandler, options?: ListenerOptions) => EventHandler;
+export default assignListener;

package/dist/events/functions/assignListener.js

@@ -0,0 +1,39 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const listenerOptions_1 = __importDefault(require("./listenerOptions"));
+/**
+ * Provide compatibility for assigning listeners.
+ * @param trigger - The name of the event which will trigger the listenerFunction on the element. (keyof HTMLElementEventMap)
+ * @param elem - An element to append the listener onto
+ * @param fn - The function which will be invoked when the
+ * event is triggered
+ * @param options - Additional options to how the event will be
+ * fired
+ */
+const assignListener = (trigger, elem, fn, options = false) => {
+  // Attaching a listener may be done differently based on the browser support
+  if (elem.addEventListener) {
+    // Latest support is provided from addEventListener with the options parameter varying slightly
+    elem.addEventListener(trigger, fn, (0, listenerOptions_1.default)(options));
+  } else if (elem.attachEvent) {
+    // Older browsers, especially Internet Explorer
+    elem.attachEvent(`on${trigger}`, fn);
+  } else {
+    // General support for adding a new function onto the element which can be called to trigger the function
+    ;
+    elem[`on${trigger}`] = fn;
+  }
+  return fn;
+};
+exports.default = assignListener;

package/dist/events/functions/assignListener.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const listenerOptions_1=__importDefault(require("./listenerOptions")),assignListener=(e,t,n,s=!1)=>(t.addEventListener?t.addEventListener(e,n,(0,listenerOptions_1.default)(s)):t.attachEvent?t.attachEvent(`on${e}`,n):t[`on${e}`]=n,n);exports.default=assignListener;

package/dist/events/functions/bindAllListeners.d.ts

@@ -0,0 +1,10 @@
+import type { DomItem } from '../../domItem/types';
+/**
+ * Based on the eventListeners property of the provided item, bind the listeners to the associated element property
+ * for each item in the domEvents.DomItem structure.
+ * WARNING: This is a recursive function.
+ * @param item - The DomItem with an associated HTMLElement to have a listener
+ * assigned
+ */
+declare const bindAllListeners: (item: DomItem) => DomItem;
+export default bindAllListeners;

package/dist/events/functions/bindAllListeners.js

@@ -0,0 +1,28 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const bindListeners_1 = __importDefault(require("./bindListeners"));
+/**
+ * Based on the eventListeners property of the provided item, bind the listeners to the associated element property
+ * for each item in the domEvents.DomItem structure.
+ * WARNING: This is a recursive function.
+ * @param item - The DomItem with an associated HTMLElement to have a listener
+ * assigned
+ */
+const bindAllListeners = item => {
+  for (const child of item.children) {
+    bindAllListeners(child);
+  }
+  return (0, bindListeners_1.default)(item);
+};
+exports.default = bindAllListeners;

package/dist/events/functions/bindAllListeners.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const bindListeners_1=__importDefault(require("./bindListeners")),bindAllListeners=e=>{for(const t of e.children)bindAllListeners(t);return(0,bindListeners_1.default)(e)};exports.default=bindAllListeners;

package/dist/events/functions/bindElementListeners.d.ts

@@ -0,0 +1,7 @@
+import type { DomItem } from '../../domItem/types';
+/**
+ * Receive a DomItem with eventListeners and apply the event listeners onto the Dom element.
+ * @param item - The DomItem which has eventListeners to apply to its element
+ */
+declare const bindElementListeners: (item: DomItem) => DomItem;
+export default bindElementListeners;

package/dist/events/functions/bindElementListeners.js

@@ -0,0 +1,34 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const activateListener_1 = __importDefault(require("./activateListener"));
+const applyActiveListeners_1 = __importDefault(require("./applyActiveListeners"));
+/**
+ * Receive a DomItem with eventListeners and apply the event listeners onto the Dom element.
+ * @param item - The DomItem which has eventListeners to apply to its element
+ */
+const bindElementListeners = item => {
+  for (const eventName in item.eventListeners) {
+    const listeners = item.eventListeners[eventName];
+    listeners.forEach(eventAttributes => {
+      if (eventAttributes.listenerActive) {
+        return;
+      }
+      item = (0, activateListener_1.default)(eventName, eventAttributes, item);
+      eventAttributes.listenerActive = true;
+    });
+    item = (0, applyActiveListeners_1.default)(eventName, item);
+  }
+  return item;
+};
+exports.default = bindElementListeners;

package/dist/events/functions/bindElementListeners.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const activateListener_1=__importDefault(require("./activateListener")),applyActiveListeners_1=__importDefault(require("./applyActiveListeners")),bindElementListeners=e=>{for(const t in e.eventListeners){e.eventListeners[t].forEach(i=>{i.listenerActive||(e=(0,activateListener_1.default)(t,i,e),i.listenerActive=!0)}),e=(0,applyActiveListeners_1.default)(t,e)}return e};exports.default=bindElementListeners;

package/dist/events/functions/bindListeners.d.ts

@@ -0,0 +1,9 @@
+import type { DomItem } from '../../domItem/types';
+/**
+ * Based on the eventListeners property of the provided item, bind the
+ * listeners to the associated element property for the provided domEvents.DomItem.
+ * @param item - The DomItem which may have eventListeners to apply to its
+ * element
+ */
+declare const bindListeners: (item: DomItem) => DomItem;
+export default bindListeners;

package/dist/events/functions/bindListeners.js

@@ -0,0 +1,23 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const bindElementListeners_1 = __importDefault(require("./bindElementListeners"));
+const si_funciona_1 = __importDefault(require("si-funciona"));
+/**
+ * Based on the eventListeners property of the provided item, bind the
+ * listeners to the associated element property for the provided domEvents.DomItem.
+ * @param item - The DomItem which may have eventListeners to apply to its
+ * element
+ */
+const bindListeners = item => !si_funciona_1.default.emptyObject(item.eventListeners) && item.element ? (0, bindElementListeners_1.default)(item) : item;
+exports.default = bindListeners;

package/dist/events/functions/bindListeners.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const bindElementListeners_1=__importDefault(require("./bindElementListeners")),si_funciona_1=__importDefault(require("si-funciona")),bindListeners=e=>!si_funciona_1.default.emptyObject(e.eventListeners)&&e.element?(0,bindElementListeners_1.default)(e):e;exports.default=bindListeners;

package/dist/events/functions/deactivateListener.d.ts

@@ -0,0 +1,13 @@
+import type { DomItem } from '../../domItem/types';
+import type { EventName, ListenerDescriptor } from '../types';
+/**
+ * Deactivate a single listener: detach it from the element (if it was actually attached) and remove it from
+ * activeListeners, without disturbing any other listener sharing the same options bucket.
+ * @param eventName - The name of the trigger event the listener was activated under.
+ * @param eventListener - The EventListener descriptor to deactivate, as found via
+ * {@link findEventListener} or returned from {@link activateListener}.
+ * @param item - The DomItem the listener is attached to.
+ * @returns The same DomItem, with this listener detached and marked inactive.
+ */
+declare const deactivateListener: (eventName: EventName, eventListener: ListenerDescriptor, item: DomItem) => DomItem;
+export default deactivateListener;

package/dist/events/functions/deactivateListener.js

@@ -0,0 +1,58 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const si_funciona_1 = __importDefault(require("si-funciona"));
+const getListenerOptions_1 = __importDefault(require("../objects/options/getListenerOptions"));
+const optionsToNumber_1 = __importDefault(require("../objects/options/optionsToNumber"));
+const numberToOptions_1 = __importDefault(require("../objects/options/numberToOptions"));
+const unassignListener_1 = __importDefault(require("./unassignListener"));
+/**
+ * Deactivate a single listener: detach it from the element (if it was actually attached) and remove it from
+ * activeListeners, without disturbing any other listener sharing the same options bucket.
+ * @param eventName - The name of the trigger event the listener was activated under.
+ * @param eventListener - The EventListener descriptor to deactivate, as found via
+ * {@link findEventListener} or returned from {@link activateListener}.
+ * @param item - The DomItem the listener is attached to.
+ * @returns The same DomItem, with this listener detached and marked inactive.
+ */
+const deactivateListener = (eventName, eventListener, item) => {
+  const eventOptions = si_funciona_1.default.dotGet(item, `activeListeners.${eventName}`);
+  if (eventOptions === null || !eventListener.activeResponder) {
+    return item;
+  }
+  const listenerOptions = (0, getListenerOptions_1.default)();
+  const optionIdentifier = (0, optionsToNumber_1.default)(listenerOptions, eventListener.listenerOptions);
+  const active = item.activeListeners;
+  const bucket = active[eventName][optionIdentifier];
+  if (!bucket) {
+    return item;
+  }
+  if (eventListener.activeResponder.assignedHandler) {
+    const optionsToUse = (0, numberToOptions_1.default)(listenerOptions, optionIdentifier);
+    const finalOptions = optionsToUse.signal ? Object.assign({}, optionsToUse, {
+      signal: eventListener.activeResponder.abort.signal
+    }) : (delete optionsToUse.signal, optionsToUse);
+    (0, unassignListener_1.default)(eventName, item.element, eventListener.activeResponder.assignedHandler, finalOptions);
+  }
+  const responderIndex = bucket.indexOf(eventListener.activeResponder);
+  if (responderIndex > -1) {
+    bucket.splice(responderIndex, 1);
+  }
+  if (bucket.length === 0) {
+    delete active[eventName][optionIdentifier];
+  }
+  eventListener.activeResponder = null;
+  eventListener.listenerActive = false;
+  return item;
+};
+exports.default = deactivateListener;

package/dist/events/functions/deactivateListener.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const si_funciona_1=__importDefault(require("si-funciona")),getListenerOptions_1=__importDefault(require("../objects/options/getListenerOptions")),optionsToNumber_1=__importDefault(require("../objects/options/optionsToNumber")),numberToOptions_1=__importDefault(require("../objects/options/numberToOptions")),unassignListener_1=__importDefault(require("./unassignListener")),deactivateListener=(e,t,i)=>{if(null===si_funciona_1.default.dotGet(i,`activeListeners.${e}`)||!t.activeResponder)return i;const n=(0,getListenerOptions_1.default)(),s=(0,optionsToNumber_1.default)(n,t.listenerOptions),r=i.activeListeners,o=r[e][s];if(!o)return i;if(t.activeResponder.assignedHandler){const r=(0,numberToOptions_1.default)(n,s),o=r.signal?Object.assign({},r,{signal:t.activeResponder.abort.signal}):(delete r.signal,r);(0,unassignListener_1.default)(e,i.element,t.activeResponder.assignedHandler,o)}const a=o.indexOf(t.activeResponder);return a>-1&&o.splice(a,1),0===o.length&&delete r[e][s],t.activeResponder=null,t.listenerActive=!1,i};exports.default=deactivateListener;

package/dist/events/functions/deactivateListeners.d.ts

@@ -0,0 +1,7 @@
+import type { DomItem } from '../../domItem/types';
+/**
+ * Set all the listeners for this DOMItem to be inactive.
+ * @param item - The DomItem which will have its eventListeners updated.
+ */
+declare const deactivateListeners: (item: DomItem) => DomItem;
+export default deactivateListeners;

package/dist/events/functions/deactivateListeners.js

@@ -0,0 +1,22 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+/**
+ * Set all the listeners for this DOMItem to be inactive.
+ * @param item - The DomItem which will have its eventListeners updated.
+ */
+const deactivateListeners = item => {
+  for (const eventName in item.eventListeners) {
+    item.eventListeners[eventName].forEach(eventListener => {
+      eventListener.listenerActive = false;
+    });
+  }
+  delete item.activeListeners;
+  return item;
+};
+exports.default = deactivateListeners;

package/dist/events/functions/deactivateListeners.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const deactivateListeners=e=>{for(const t in e.eventListeners)e.eventListeners[t].forEach(e=>{e.listenerActive=!1});return delete e.activeListeners,e};exports.default=deactivateListeners;

package/dist/events/functions/findEventListener.d.ts

@@ -0,0 +1,22 @@
+import type { DomItem } from '../../domItem/types';
+import type { EventName, ListenerDescriptor, ListenerFunction, ListenerOptions } from '../types';
+/**
+ * Search a DOM item's eventListeners for a specific event listener, matched by listener function, custom args, and
+ * whether it listens in the capture phase. Returns its index and the matching descriptor as a tuple.
+ *
+ * As with the DOM's removeEventListener, only the capture flag tells two listeners of the same function apart: once,
+ * passive and signal only change how a listener behaves, not which listener it is.
+ *
+ * item is the last parameter (instead of customArgs/options having literal defaults) so this can be curried and
+ * piped directly - see {@link fullAddEventListener} for an example of the pattern.
+ * @param eventName - The name of the trigger event the listener was registered under.
+ * @param listenerFunction - The listener function to match against.
+ * @param customArgs - The custom args the listener was registered with.
+ * @param options - The options the listener was registered with; only
+ * the capture flag is compared.
+ * @param item - The DomItem whose eventListeners will be searched.
+ * @returns A 2-element [index, matchingListener] tuple. If no match is
+ * found, index is -1 and matchingListener is undefined.
+ */
+declare const findEventListener: (eventName: EventName, listenerFunction: string | ListenerFunction, customArgs: object | null | undefined, options: ListenerOptions | null | undefined, item: DomItem) => [number, ListenerDescriptor | undefined];
+export default findEventListener;

package/dist/events/functions/findEventListener.js

@@ -0,0 +1,61 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const si_funciona_1 = __importDefault(require("si-funciona"));
+const getListenerOptions_1 = __importDefault(require("../objects/options/getListenerOptions"));
+const optionsToNumber_1 = __importDefault(require("../objects/options/optionsToNumber"));
+/**
+ * Whether the options ask for the capture phase.
+ * @private
+ */
+const capturing = options => {
+  const template = (0, getListenerOptions_1.default)();
+  return ((0, optionsToNumber_1.default)(template, options) & template.capture) !== 0;
+};
+/**
+ * Search a DOM item's eventListeners for a specific event listener, matched by listener function, custom args, and
+ * whether it listens in the capture phase. Returns its index and the matching descriptor as a tuple.
+ *
+ * As with the DOM's removeEventListener, only the capture flag tells two listeners of the same function apart: once,
+ * passive and signal only change how a listener behaves, not which listener it is.
+ *
+ * item is the last parameter (instead of customArgs/options having literal defaults) so this can be curried and
+ * piped directly - see {@link fullAddEventListener} for an example of the pattern.
+ * @param eventName - The name of the trigger event the listener was registered under.
+ * @param listenerFunction - The listener function to match against.
+ * @param customArgs - The custom args the listener was registered with.
+ * @param options - The options the listener was registered with; only
+ * the capture flag is compared.
+ * @param item - The DomItem whose eventListeners will be searched.
+ * @returns A 2-element [index, matchingListener] tuple. If no match is
+ * found, index is -1 and matchingListener is undefined.
+ */
+const findEventListener = (eventName, listenerFunction, customArgs, options, item) => {
+  customArgs = customArgs ?? null;
+  if (!si_funciona_1.default.isObject(item.eventListeners)) {
+    return [-1, undefined];
+  }
+  if (typeof item.eventListeners[eventName] === 'undefined') {
+    return [-1, undefined];
+  }
+  const findListener = {
+    listenerFunc: listenerFunction,
+    listenerArgs: si_funciona_1.default.describeObject(customArgs)
+  };
+  const listenerIndex = item.eventListeners[eventName].findIndex(eventListener => {
+    const argDescriptor = si_funciona_1.default.describeObject(eventListener.listenerArgs);
+    return eventListener.listenerFunc === findListener.listenerFunc && si_funciona_1.default.sameDescriptor(findListener.listenerArgs, argDescriptor) && capturing(eventListener.listenerOptions) === capturing(options);
+  });
+  return [listenerIndex, item.eventListeners[eventName][listenerIndex]];
+};
+exports.default = findEventListener;

package/dist/events/functions/findEventListener.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const si_funciona_1=__importDefault(require("si-funciona")),getListenerOptions_1=__importDefault(require("../objects/options/getListenerOptions")),optionsToNumber_1=__importDefault(require("../objects/options/optionsToNumber")),capturing=e=>{const t=(0,getListenerOptions_1.default)();return 0!==((0,optionsToNumber_1.default)(t,e)&t.capture)},findEventListener=(e,t,n,i,r)=>{if(n=n??null,!si_funciona_1.default.isObject(r.eventListeners))return[-1,void 0];if(void 0===r.eventListeners[e])return[-1,void 0];const s={listenerFunc:t,listenerArgs:si_funciona_1.default.describeObject(n)},o=r.eventListeners[e].findIndex(e=>{const t=si_funciona_1.default.describeObject(e.listenerArgs);return e.listenerFunc===s.listenerFunc&&si_funciona_1.default.sameDescriptor(s.listenerArgs,t)&&capturing(e.listenerOptions)===capturing(i)});return[o,r.eventListeners[e][o]]};exports.default=findEventListener;

package/dist/events/functions/fullAddEventListener.d.ts

@@ -0,0 +1,20 @@
+import type { DomItem } from '../../domItem/types';
+import type { EventName, ListenerFunction, ListenerOptions } from '../types';
+/**
+ * Register the listener function, attach it as a descriptor on the item, then bind it onto the
+ * real element - the full setup sequence for a single event listener, in order:
+ * 1. {@link registerListener} - store the real function in the root DomItem's eventActions, keyed by name.
+ * 2. {@link addEventListener} - push an EventListener descriptor referencing that name onto item.eventListeners.
+ * 3. {@link bindListeners} - activate and apply any unbound descriptors, attaching them to item.element.
+ *
+ * item is the last parameter (instead of name/customArgs/options having literal defaults) so addEventListener can
+ * be curried directly into the pipe below without an argument-reordering wrapper.
+ * @param eventName - The name of the trigger event (e.g. 'click').
+ * @param listener - The function to be called when the event is triggered.
+ * @param name - The name the listener will be registered under in eventActions.
+ * @param customArgs - Additional args passed through to the listener when called.
+ * @param options - Options to be used when the listener is attached to the element.
+ * @param item - The DomItem which will receive the event listener.
+ */
+declare const fullAddEventListener: (eventName: EventName, listener: ListenerFunction, name: string | null | undefined, customArgs: object | null | undefined, options: ListenerOptions | null | undefined, item: DomItem) => DomItem;
+export default fullAddEventListener;

package/dist/events/functions/fullAddEventListener.js

@@ -0,0 +1,45 @@
+"use strict";
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+const curry_1 = __importDefault(require("si-funciona/dist/helpers/functions/curry"));
+const pipe_1 = __importDefault(require("si-funciona/dist/helpers/functions/pipe"));
+const getTopParentItem_1 = __importDefault(require("../../domItem/tree/getTopParentItem"));
+const registerListener_1 = __importDefault(require("./registerListener"));
+const addEventListener_1 = __importDefault(require("./addEventListener"));
+const bindListeners_1 = __importDefault(require("./bindListeners"));
+/**
+ * Register the listener function, attach it as a descriptor on the item, then bind it onto the
+ * real element - the full setup sequence for a single event listener, in order:
+ * 1. {@link registerListener} - store the real function in the root DomItem's eventActions, keyed by name.
+ * 2. {@link addEventListener} - push an EventListener descriptor referencing that name onto item.eventListeners.
+ * 3. {@link bindListeners} - activate and apply any unbound descriptors, attaching them to item.element.
+ *
+ * item is the last parameter (instead of name/customArgs/options having literal defaults) so addEventListener can
+ * be curried directly into the pipe below without an argument-reordering wrapper.
+ * @param eventName - The name of the trigger event (e.g. 'click').
+ * @param listener - The function to be called when the event is triggered.
+ * @param name - The name the listener will be registered under in eventActions.
+ * @param customArgs - Additional args passed through to the listener when called.
+ * @param options - Options to be used when the listener is attached to the element.
+ * @param item - The DomItem which will receive the event listener.
+ */
+const fullAddEventListener = (eventName, listener, name, customArgs, options, item) => {
+  const listenerName = name ?? listener.name;
+  customArgs = customArgs ?? null;
+  options = options ?? false;
+  return (0, pipe_1.default)(currentItem => {
+    (0, registerListener_1.default)(listener, listenerName, (0, getTopParentItem_1.default)(currentItem));
+    return currentItem;
+  }, (0, curry_1.default)(addEventListener_1.default)(eventName, listenerName, customArgs, options), bindListeners_1.default)(item);
+};
+exports.default = fullAddEventListener;

package/dist/events/functions/fullAddEventListener.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const curry_1=__importDefault(require("si-funciona/dist/helpers/functions/curry")),pipe_1=__importDefault(require("si-funciona/dist/helpers/functions/pipe")),getTopParentItem_1=__importDefault(require("../../domItem/tree/getTopParentItem")),registerListener_1=__importDefault(require("./registerListener")),addEventListener_1=__importDefault(require("./addEventListener")),bindListeners_1=__importDefault(require("./bindListeners")),fullAddEventListener=(e,t,r,i,n,u)=>{const s=r??t.name;return i=i??null,n=n??!1,(0,pipe_1.default)(e=>((0,registerListener_1.default)(t,s,(0,getTopParentItem_1.default)(e)),e),(0,curry_1.default)(addEventListener_1.default)(e,s,i,n),bindListeners_1.default)(u)};exports.default=fullAddEventListener;

package/dist/events/functions/fullRemoveEventListener.d.ts

@@ -0,0 +1,22 @@
+import type { DomItem } from '../../domItem/types';
+import type { EventName, ListenerFunction, ListenerOptions } from '../types';
+/**
+ * Find and remove a listener that was registered by name (e.g. via {@link fullAddEventListener}) - the counterpart
+ * to fullAddEventListener. Resolves name the same way fullAddEventListener defaults it, so a caller only needs the
+ * original listener function (not the internal name string it was registered under) to remove it:
+ * 1. Resolve name (defaults to listener.name, same as {@link fullAddEventListener}).
+ * 2. {@link removeEventListener} - find the descriptor by that name, detach it from the element if active, and
+ *    splice it out of item.eventListeners.
+ *
+ * Does not remove the function from the root DomItem's eventActions registry, since that name may still be shared
+ * by other DomItems - see {@link registerListener}.
+ * @param eventName - The name of the trigger event (e.g. 'click').
+ * @param listener - The same function originally passed to fullAddEventListener.
+ * @param name - The name the listener was registered under in eventActions.
+ * @param customArgs - The custom args the listener was registered with.
+ * @param options - The options the listener was registered with.
+ * @param item - The DomItem to remove the listener from.
+ * @returns The same DomItem, with the matching listener removed if one was found.
+ */
+declare const fullRemoveEventListener: (eventName: EventName, listener: ListenerFunction, name: string | null | undefined, customArgs: object | null | undefined, options: ListenerOptions | null | undefined, item: DomItem) => DomItem;
+export default fullRemoveEventListener;