treeloom 0.0.0-stage → 2.1.0

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;

package/dist/events/functions/fullRemoveEventListener.js

@@ -0,0 +1,37 @@
+"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 removeEventListener_1 = __importDefault(require("./removeEventListener"));
+/**
+ * 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.
+ */
+const fullRemoveEventListener = (eventName, listener, name, customArgs, options, item) => {
+  const listenerName = name ?? listener.name;
+  return (0, removeEventListener_1.default)(eventName, listenerName, customArgs, options, item);
+};
+exports.default = fullRemoveEventListener;

package/dist/events/functions/fullRemoveEventListener.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 removeEventListener_1=__importDefault(require("./removeEventListener")),fullRemoveEventListener=(e,t,r,n,o,u)=>{const s=r??t.name;return(0,removeEventListener_1.default)(e,s,n,o,u)};exports.default=fullRemoveEventListener;

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

@@ -0,0 +1,12 @@
+import type { ListenerOptions } from '../types';
+/** The options which will be used, and a flag remembering whether the browser understands an options object. */
+type ListenerOptionsSupport = {
+    (options?: ListenerOptions | null): ListenerOptions | null;
+    supportsOptions?: boolean;
+};
+/**
+ * Provide compatibility for using the options parameter of addEventListener
+ * @param options - An object or boolean with the listener options
+ */
+declare const listenerOptions: ListenerOptionsSupport;
+export default listenerOptions;

package/dist/events/functions/listenerOptions.js

@@ -0,0 +1,31 @@
+"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
+});
+/**
+ * Provide compatibility for using the options parameter of addEventListener
+ * @param options - An object or boolean with the listener options
+ */
+const listenerOptions = options => {
+  if (typeof listenerOptions.supportsOptions === 'undefined') {
+    // Check if supportsOptions has been defined. This is a compatibility checking flag.
+    listenerOptions.supportsOptions = true;
+    try {
+      // If it is possible to use OptionsObject, then set our flag to true
+      window.addEventListener('test', null, {
+        capture: false,
+        once: false,
+        passive: false
+      });
+    } catch (err) {
+      // When using an OptionsObjects fails, it is only possible to pass the boolean UseCapture as the option
+      listenerOptions.supportsOptions = false;
+    }
+  }
+  return typeof options === 'object' && listenerOptions.supportsOptions ? options : false;
+};
+exports.default = listenerOptions;

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

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const listenerOptions=t=>{if(void 0===listenerOptions.supportsOptions){listenerOptions.supportsOptions=!0;try{window.addEventListener("test",null,{capture:!1,once:!1,passive:!1})}catch(t){listenerOptions.supportsOptions=!1}}return!("object"!=typeof t||!listenerOptions.supportsOptions)&&t};exports.default=listenerOptions;

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

@@ -0,0 +1,10 @@
+import type { DomItem } from '../../domItem/types';
+import type { EventHandler, ListenerFunction } from '../types';
+/**
+ * Prepare a listener to be used before assigning to an element.
+ * @param listener
+ * @param item
+ * @param args
+ */
+declare const makeEventHandler: (listener: ListenerFunction, item: DomItem, ...args: unknown[]) => EventHandler;
+export default makeEventHandler;

package/dist/events/functions/makeEventHandler.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/. */
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+/**
+ * Prepare a listener to be used before assigning to an element.
+ * @param listener
+ * @param item
+ * @param args
+ */
+const makeEventHandler = (listener, item, ...args) => {
+  return event => {
+    if (!event || event.immediatePropagationStopped) {
+      return event;
+    }
+    return listener(event, item, ...args);
+  };
+};
+exports.default = makeEventHandler;

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

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const makeEventHandler=(e,t,...a)=>o=>!o||o.immediatePropagationStopped?o:e(o,t,...a);exports.default=makeEventHandler;

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

@@ -0,0 +1,11 @@
+import type { ForwardEventsFunction, ListenerFunction } from '../types';
+/**
+ * Build the listener function used in render-only mode: instead of running real logic locally, it packages the
+ * event as a plain envelope (the id of the item it fired on, the event type, the registered listener name, any
+ * custom args, and any live target state - see captureTargetState) and hands it to the injected transport
+ * function. See retrieveListener.
+ * @param listenerName - The registered name this forwarder stands in for.
+ * @param transport - Where the envelope is sent (set on the root item with setForwardEvents).
+ */
+declare const makeForwardingListener: (listenerName: string, transport: ForwardEventsFunction) => ListenerFunction;
+export default makeForwardingListener;

package/dist/events/functions/makeForwardingListener.js

@@ -0,0 +1,46 @@
+"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/. */
+require("core-js/modules/es.array.includes.js");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+/** Form-control elements whose state a listener might read directly off the event target. */
+const FORM_CONTROL_TAGS = ['INPUT', 'SELECT', 'TEXTAREA'];
+/**
+ * Whatever live state a listener commonly reads directly off the real event's target - a checkbox's checked, an
+ * input's value - captured here since the receiving end's corresponding element is otherwise an independent object
+ * with no way to know what the user actually set. Omitted for anything that is not a form control (every element
+ * has a non-undefined value or checked is not a safe enough check on its own - a plain button also has a value,
+ * defaulting to '', and any input has checked defaulting to false even when it is not a checkbox).
+ * @param target
+ */
+const captureTargetState = target => {
+  const element = target;
+  if (!element || !FORM_CONTROL_TAGS.includes(element.tagName)) {
+    return undefined;
+  }
+  return element.type === 'checkbox' || element.type === 'radio' ? {
+    checked: element.checked
+  } : {
+    value: element.value
+  };
+};
+/**
+ * Build the listener function used in render-only mode: instead of running real logic locally, it packages the
+ * event as a plain envelope (the id of the item it fired on, the event type, the registered listener name, any
+ * custom args, and any live target state - see captureTargetState) and hands it to the injected transport
+ * function. See retrieveListener.
+ * @param listenerName - The registered name this forwarder stands in for.
+ * @param transport - Where the envelope is sent (set on the root item with setForwardEvents).
+ */
+const makeForwardingListener = (listenerName, transport) => (event, item, ...args) => transport({
+  itemId: (event.domItemTarget ?? item).id,
+  eventType: event.type,
+  listenerFunc: listenerName,
+  data: args,
+  targetState: captureTargetState(event.target)
+});
+exports.default = makeForwardingListener;

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

@@ -0,0 +1 @@
+"use strict";require("core-js/modules/es.array.includes.js"),Object.defineProperty(exports,"__esModule",{value:!0});const FORM_CONTROL_TAGS=["INPUT","SELECT","TEXTAREA"],captureTargetState=e=>{const t=e;if(t&&FORM_CONTROL_TAGS.includes(t.tagName))return"checkbox"===t.type||"radio"===t.type?{checked:t.checked}:{value:t.value}},makeForwardingListener=(e,t)=>(r,a,...c)=>t({itemId:(r.domItemTarget??a).id,eventType:r.type,listenerFunc:e,data:c,targetState:captureTargetState(r.target)});exports.default=makeForwardingListener;

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

@@ -0,0 +1,23 @@
+import type { DomItem, DomItemRoot } from '../../domItem/types';
+import type { ForwardedEvent } from '../types';
+/**
+ * Decides whether a resolved, incoming envelope may actually be dispatched. See receiveForwardedEvent's own
+ * validator parameter - an id only makes resolution correct, not authorized, so anything that needs to check
+ * who an id actually belongs to (not just that it resolves to a real item) plugs in here.
+ */
+export type ForwardedEventValidator = (resolvedItem: DomItem, envelope: ForwardedEvent) => boolean;
+/**
+ * The receiving end of makeForwardingListener's envelope: resolve the item it was built for, replay any live target
+ * state it carried onto that item's real element (see captureTargetState in makeForwardingListener), then dispatch
+ * a real event of the same type on it. The resolved item's own, already-bound listener runs exactly as it would for
+ * a genuine local event - nothing here needs to know what that listener does.
+ * @param root - The tree to resolve the envelope's itemId against. Its listeners must be the real ones (not
+ * itself set up with setForwardEvents), or this would just forward the event again instead of running it.
+ * @param envelope - As produced by makeForwardingListener on the sending end.
+ * @param validator - Optional: when given and it returns false for the resolved item, the event is never
+ * dispatched. Resolving by id is correct (it finds the right item even if this root's own tree shape differs
+ * from the sender's), but not authorized on its own - a validator is the one place to plug an ownership check
+ * in, instead of every caller re-deriving "resolve first, then check, then dispatch" by hand.
+ */
+declare const receiveForwardedEvent: (root: DomItemRoot, envelope: ForwardedEvent, validator?: ForwardedEventValidator) => void;
+export default receiveForwardedEvent;

package/dist/events/functions/receiveForwardedEvent.js

@@ -0,0 +1,40 @@
+"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
+});
+const itemIdIndex_1 = require("../../domItem/tree/itemIdIndex");
+/**
+ * The receiving end of makeForwardingListener's envelope: resolve the item it was built for, replay any live target
+ * state it carried onto that item's real element (see captureTargetState in makeForwardingListener), then dispatch
+ * a real event of the same type on it. The resolved item's own, already-bound listener runs exactly as it would for
+ * a genuine local event - nothing here needs to know what that listener does.
+ * @param root - The tree to resolve the envelope's itemId against. Its listeners must be the real ones (not
+ * itself set up with setForwardEvents), or this would just forward the event again instead of running it.
+ * @param envelope - As produced by makeForwardingListener on the sending end.
+ * @param validator - Optional: when given and it returns false for the resolved item, the event is never
+ * dispatched. Resolving by id is correct (it finds the right item even if this root's own tree shape differs
+ * from the sender's), but not authorized on its own - a validator is the one place to plug an ownership check
+ * in, instead of every caller re-deriving "resolve first, then check, then dispatch" by hand.
+ */
+const receiveForwardedEvent = (root, envelope, validator) => {
+  const resolvedItem = (0, itemIdIndex_1.getItemById)(root, envelope.itemId);
+  if (validator && !validator(resolvedItem, envelope)) {
+    return;
+  }
+  const element = resolvedItem.element;
+  if (!element) {
+    throw new Error('The resolved item has no element to dispatch the event on.');
+  }
+  if (envelope.targetState) {
+    Object.assign(element, envelope.targetState);
+  }
+  element.dispatchEvent(new Event(envelope.eventType, {
+    bubbles: true,
+    cancelable: true
+  }));
+};
+exports.default = receiveForwardedEvent;

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

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const itemIdIndex_1=require("../../domItem/tree/itemIdIndex"),receiveForwardedEvent=(e,t,r)=>{const n=(0,itemIdIndex_1.getItemById)(e,t.itemId);if(r&&!r(n,t))return;const d=n.element;if(!d)throw new Error("The resolved item has no element to dispatch the event on.");t.targetState&&Object.assign(d,t.targetState),d.dispatchEvent(new Event(t.eventType,{bubbles:!0,cancelable:!0}))};exports.default=receiveForwardedEvent;

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

@@ -0,0 +1,11 @@
+import type { DomItemRoot } from '../../domItem/types';
+import type { ListenerFunction } from '../types';
+/**
+ * Register a single listener function as part of the root domEvents.DomItem.
+ * @param listener - Provide a function which will be called
+ * when a Dom event is triggered.
+ * @param name - The name of the listener to be used.
+ * @param parent - The parent DomItem which is DomItemRoot which stores eventListeners property.
+ */
+declare const registerListener: (listener: ListenerFunction, name?: string, parent?: DomItemRoot) => Record<string, ListenerFunction>;
+export default registerListener;

package/dist/events/functions/registerListener.js

@@ -0,0 +1,25 @@
+"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 documentItem_1 = __importDefault(require("../../domItem/objects/documentItem"));
+/**
+ * Register a single listener function as part of the root domEvents.DomItem.
+ * @param listener - Provide a function which will be called
+ * when a Dom event is triggered.
+ * @param name - The name of the listener to be used.
+ * @param parent - The parent DomItem which is DomItemRoot which stores eventListeners property.
+ */
+const registerListener = (listener, name = listener.name, parent = (0, documentItem_1.default)()) => Object.assign(parent.eventActions, {
+  [name]: listener
+});
+exports.default = registerListener;

package/dist/events/functions/registerListener.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 documentItem_1=__importDefault(require("../../domItem/objects/documentItem")),registerListener=(e,t=e.name,r=(0,documentItem_1.default)())=>Object.assign(r.eventActions,{[t]:e});exports.default=registerListener;

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

@@ -0,0 +1,10 @@
+import type { DomItemRoot } from '../../domItem/types';
+import type { ListenerFunction } from '../types';
+/**
+ * Register multiple listeners from an array of functions.
+ * @param listeners - An array of functions to be
+ * used as the registered event listeners.
+ * @param parent - The parent DomItem which is DomItemRoot which has eventActions property.
+ */
+declare const registerListeners: (listeners: ListenerFunction[] | Record<string, ListenerFunction>, parent?: DomItemRoot) => DomItemRoot;
+export default registerListeners;

package/dist/events/functions/registerListeners.js

@@ -0,0 +1,26 @@
+"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 documentItem_1 = __importDefault(require("../../domItem/objects/documentItem"));
+/**
+ * Register multiple listeners from an array of functions.
+ * @param listeners - An array of functions to be
+ * used as the registered event listeners.
+ * @param parent - The parent DomItem which is DomItemRoot which has eventActions property.
+ */
+const registerListeners = (listeners, parent = (0, documentItem_1.default)()) => {
+  si_funciona_1.default.mergeObjectsMutable(parent.eventActions, listeners);
+  return parent;
+};
+exports.default = registerListeners;