treeloom 0.0.0-stage → 2.0.0

package/dist/domItem/tree/getItemByPath.d.ts

@@ -0,0 +1,10 @@
+import type { DomItem, ItemPath } from '../types';
+/**
+ * Resolve a path (as built by getItemPath) back to the item it points at, starting from the root. Throws when the
+ * path no longer matches the tree's current shape - exactly like a stale reference to a real DOM element would, a
+ * path is only valid for as long as the tree it was built from keeps the same shape.
+ * @param root - The item the path is relative to (usually documentItem).
+ * @param path - The path to resolve, as returned by getItemPath.
+ */
+declare const getItemByPath: (root: DomItem, path: ItemPath) => DomItem;
+export default getItemByPath;

package/dist/domItem/tree/getItemByPath.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
+});
+/**
+ * Resolve a path (as built by getItemPath) back to the item it points at, starting from the root. Throws when the
+ * path no longer matches the tree's current shape - exactly like a stale reference to a real DOM element would, a
+ * path is only valid for as long as the tree it was built from keeps the same shape.
+ * @param root - The item the path is relative to (usually documentItem).
+ * @param path - The path to resolve, as returned by getItemPath.
+ */
+const getItemByPath = (root, path) => path.reduce((item, index) => {
+  const child = item.children[index];
+  if (!child) {
+    throw new Error(`No item at index ${index} of path [${path.join(', ')}] - the tree may have changed shape since this path was built.`);
+  }
+  return child;
+}, root);
+exports.default = getItemByPath;

package/dist/domItem/tree/getItemByPath.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const getItemByPath=(e,t)=>t.reduce((e,r)=>{const a=e.children[r];if(!a)throw new Error(`No item at index ${r} of path [${t.join(", ")}] - the tree may have changed shape since this path was built.`);return a},e);exports.default=getItemByPath;

package/dist/domItem/tree/getItemPath.d.ts

@@ -0,0 +1,9 @@
+import type { DomItem, ItemPath } from '../types';
+/**
+ * The path from the root to an item: the index of the item among its parent's children, at each level from the top
+ * down. An empty array means the item is the root itself.
+ * WARNING: This is a recursive function.
+ * @param item - The DomItem to find the path of.
+ */
+declare const getItemPath: (item: DomItem) => ItemPath;
+export default getItemPath;

package/dist/domItem/tree/getItemPath.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/. */
+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"));
+/**
+ * The path from the root to an item: the index of the item among its parent's children, at each level from the top
+ * down. An empty array means the item is the root itself.
+ * WARNING: This is a recursive function.
+ * @param item - The DomItem to find the path of.
+ */
+const getItemPath = item => {
+  if (item.parentItem === null) {
+    throw new Error('Detached child, missing parentItem reference. Use empty object if this is the root item.');
+  }
+  if (si_funciona_1.default.emptyObject(item.parentItem)) {
+    return [];
+  }
+  const parent = item.parentItem;
+  return [...getItemPath(parent), parent.children.indexOf(item)];
+};
+exports.default = getItemPath;

package/dist/domItem/tree/getItemPath.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")),getItemPath=e=>{if(null===e.parentItem)throw new Error("Detached child, missing parentItem reference. Use empty object if this is the root item.");if(si_funciona_1.default.emptyObject(e.parentItem))return[];const t=e.parentItem;return[...getItemPath(t),t.children.indexOf(e)]};exports.default=getItemPath;

package/dist/domItem/tree/getTopParentItem.d.ts

@@ -0,0 +1,8 @@
+import type { DomItem, DomItemRoot } from '../types';
+/**
+ * Get the upper parentItem for the provided child. (usually this is a documentItem reference)
+ * WARNING: This is a recursive function.
+ * @param item - The DomItem which we want the highest parent item of
+ */
+declare const getTopParentItem: (item: DomItem) => DomItemRoot;
+export default getTopParentItem;

package/dist/domItem/tree/getTopParentItem.js

@@ -0,0 +1,29 @@
+"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"));
+/**
+ * Get the upper parentItem for the provided child. (usually this is a documentItem reference)
+ * WARNING: This is a recursive function.
+ * @param item - The DomItem which we want the highest parent item of
+ */
+const getTopParentItem = item => {
+  if (item.parentItem === null) {
+    if (item.nodeName === '#document') {
+      throw new Error('Root parent item must be an empty object, null reference found.');
+    }
+    throw new Error('Detached child, missing parentItem reference. Use empty object if this is the root item.');
+  }
+  return si_funciona_1.default.emptyObject(item.parentItem) ? item : getTopParentItem(item.parentItem);
+};
+exports.default = getTopParentItem;

package/dist/domItem/tree/getTopParentItem.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")),getTopParentItem=e=>{if(null===e.parentItem){if("#document"===e.nodeName)throw new Error("Root parent item must be an empty object, null reference found.");throw new Error("Detached child, missing parentItem reference. Use empty object if this is the root item.")}return si_funciona_1.default.emptyObject(e.parentItem)?e:getTopParentItem(e.parentItem)};exports.default=getTopParentItem;

package/dist/domItem/tree/insertChild.d.ts

@@ -0,0 +1,11 @@
+import type { DomItem } from '../types';
+/**
+ * Insert a child into a parent's children list at a given position (like appendChild, but positioned). Appending is
+ * insertChild at the end: `appendChild(parent, child)` is `insertChild(parent, child, parent.children.length)`.
+ * @param parent - The parent that will receive the child.
+ * @param child - The new child to attach to the parent.
+ * @param index - Where in parent's children the child goes; out of range clamps to the nearest end, so 0 is always
+ * the front and a large index is always the back (matching Array.prototype.splice).
+ */
+declare const insertChild: (parent: DomItem, child: DomItem, index: number) => DomItem;
+export default insertChild;

package/dist/domItem/tree/insertChild.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
+});
+/**
+ * Insert a child into a parent's children list at a given position (like appendChild, but positioned). Appending is
+ * insertChild at the end: `appendChild(parent, child)` is `insertChild(parent, child, parent.children.length)`.
+ * @param parent - The parent that will receive the child.
+ * @param child - The new child to attach to the parent.
+ * @param index - Where in parent's children the child goes; out of range clamps to the nearest end, so 0 is always
+ * the front and a large index is always the back (matching Array.prototype.splice).
+ */
+const insertChild = (parent, child, index) => {
+  parent.children.splice(index, 0, child);
+  child.parentItem = parent;
+  return parent;
+};
+exports.default = insertChild;

package/dist/domItem/tree/insertChild.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const insertChild=(e,t,r)=>(e.children.splice(r,0,t),t.parentItem=e,e);exports.default=insertChild;

package/dist/domItem/tree/itemIdIndex.d.ts

@@ -0,0 +1,43 @@
+import type { DomItem, DomItemRoot } from '../types';
+export declare const generateItemId: () => number;
+/**
+ * Register an item (and, recursively, its whole subtree) in its own root's id index, so getItemById can find
+ * it. Call once a subtree's relationship to its parent is settled - see renderHtml, which is the one place
+ * that happens for a freshly-attached subtree. Does nothing when item is not under a real root yet (or ever).
+ *
+ * Repairs two ways an item can reach this point without the id createCoreItem is supposed to have already
+ * stamped on it, rather than requiring every consumer to avoid either:
+ * - No id at all (`typeof item.id !== 'number'`): a raw plain config object merged directly onto an
+ *   already-rendered tree (si-funciona's mergeObjectsMutable, by reference, "as is", when the two sides'
+ *   shapes do not line up index-for-index - see updatePlayerStats.ts) never passed through createCoreItem at
+ *   all, so it has no id (or parentItem, or has map) whatsoever.
+ * - A collision (the id is already registered to a *different* item within this same root): a generic "build
+ *   one item, then replicate it N times" helper (si-funciona's buildArray, cloning rather than constructing
+ *   fresh - the shape matrix-dom's own buildMatrix uses for a grid's rows/columns/tiles) copies whatever id
+ *   the one template already carries into every copy right along with everything else, with no way for
+ *   treeloom to know that happened before registration.
+ *
+ * Catching both here, at the one real choke point every attached item passes through, protects against these
+ * patterns (and any other generic cloning or raw merging this codebase does not yet know about) without
+ * needing every consumer to avoid them. A real reuse of someone else's id (rather than two different items
+ * both starting unassigned) is not realistically distinguishable from the collision case, so the same repair
+ * applies regardless of cause - the alternative (leaving it in place) silently breaks resolution for one of
+ * the two items, which is worse than quietly handing the second one a fresh id.
+ * @param item - The subtree to register, root item included.
+ */
+export declare const registerItemIds: (item: DomItem) => void;
+/**
+ * Remove an item (and, recursively, its whole subtree) from its own root's id index - the reverse of
+ * registerItemIds. Call before the item is actually detached, while its parentItem chain still resolves and
+ * its own subtree is still intact to walk.
+ * @param item - The subtree to unregister, root item included.
+ */
+export declare const unregisterItemIds: (item: DomItem) => void;
+/**
+ * Resolve an id (as captured off a DomItem's own id) back to the item it refers to, within root's own tree.
+ * Throws when the id isn't registered against this root - the same "stale reference" contract getItemByPath
+ * already has: a silent wrong-answer resolution is worse than a loud failure.
+ * @param root - The tree to resolve the id against.
+ * @param id - The id to resolve, as read directly off a DomItem's own id property.
+ */
+export declare const getItemById: (root: DomItemRoot, id: number) => DomItem;

package/dist/domItem/tree/itemIdIndex.js

@@ -0,0 +1,118 @@
+"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
+});
+exports.getItemById = exports.unregisterItemIds = exports.registerItemIds = exports.generateItemId = void 0;
+const si_funciona_1 = __importDefault(require("si-funciona"));
+const collect_your_stuff_1 = require("collect-your-stuff");
+/** One lookup index per treeloom process: every root's own ids live in their own scope, so two unrelated trees
+ * (the server's real tree and a client's independently-built one) never collide even though both number their
+ * items starting from the same small integers. */
+const itemsById = new collect_your_stuff_1.ScopedCollection();
+/** The next id to assign - a plain, process-local monotonic counter (not a UUID: cheaper to generate/compare/
+ * serialize, and uniqueness only ever needs to hold within one process, since nothing resolves an id against a
+ * different root than the one it came from). Exported for createCoreItem's own first stamp and for this
+ * module's own collision repair below - kept here, not there, since this module must never import back from
+ * createCoreItem (which already imports this one, via removeChild - see unregisterItemIds's own caller). */
+let nextItemId = 0;
+const generateItemId = () => nextItemId++;
+exports.generateItemId = generateItemId;
+/**
+ * The real root above item, or null when item's own parentItem chain never reaches one. That covers two
+ * different, both legitimate cases: an item rendered into some arbitrary, never-rooted container (see
+ * renderHtml's own tests - not one forwarding could ever target, so it is not an error for it to have no
+ * id-index entry), and an item that was never completed as a real DomItem at all - a raw plain config object
+ * merged directly onto an already-rendered tree (si-funciona's mergeObjectsMutable, by reference, "as is",
+ * when the two sides' shapes do not line up index-for-index - see updatePlayerStats.ts) carries no parentItem
+ * property whatsoever, `undefined` rather than this codebase's own usual `null` for "detached". Unlike
+ * getTopParentItem, this never throws: it is used purely to decide whether registration applies, not to
+ * assert that a real root exists.
+ * @param item
+ */
+const tryGetRoot = item => {
+  let current = item;
+  while (current.parentItem != null) {
+    if (si_funciona_1.default.emptyObject(current.parentItem)) {
+      return current;
+    }
+    current = current.parentItem;
+  }
+  return null;
+};
+/**
+ * Register an item (and, recursively, its whole subtree) in its own root's id index, so getItemById can find
+ * it. Call once a subtree's relationship to its parent is settled - see renderHtml, which is the one place
+ * that happens for a freshly-attached subtree. Does nothing when item is not under a real root yet (or ever).
+ *
+ * Repairs two ways an item can reach this point without the id createCoreItem is supposed to have already
+ * stamped on it, rather than requiring every consumer to avoid either:
+ * - No id at all (`typeof item.id !== 'number'`): a raw plain config object merged directly onto an
+ *   already-rendered tree (si-funciona's mergeObjectsMutable, by reference, "as is", when the two sides'
+ *   shapes do not line up index-for-index - see updatePlayerStats.ts) never passed through createCoreItem at
+ *   all, so it has no id (or parentItem, or has map) whatsoever.
+ * - A collision (the id is already registered to a *different* item within this same root): a generic "build
+ *   one item, then replicate it N times" helper (si-funciona's buildArray, cloning rather than constructing
+ *   fresh - the shape matrix-dom's own buildMatrix uses for a grid's rows/columns/tiles) copies whatever id
+ *   the one template already carries into every copy right along with everything else, with no way for
+ *   treeloom to know that happened before registration.
+ *
+ * Catching both here, at the one real choke point every attached item passes through, protects against these
+ * patterns (and any other generic cloning or raw merging this codebase does not yet know about) without
+ * needing every consumer to avoid them. A real reuse of someone else's id (rather than two different items
+ * both starting unassigned) is not realistically distinguishable from the collision case, so the same repair
+ * applies regardless of cause - the alternative (leaving it in place) silently breaks resolution for one of
+ * the two items, which is worse than quietly handing the second one a fresh id.
+ * @param item - The subtree to register, root item included.
+ */
+const registerItemIds = item => {
+  const root = tryGetRoot(item);
+  if (!root) {
+    return;
+  }
+  const alreadyThere = typeof item.id === 'number' ? itemsById.get(root, item.id) : undefined;
+  if (typeof item.id !== 'number' || alreadyThere && alreadyThere !== item) {
+    item.id = (0, exports.generateItemId)();
+  }
+  itemsById.set(root, item.id, item);
+  (item.children || []).forEach(exports.registerItemIds);
+};
+exports.registerItemIds = registerItemIds;
+/**
+ * Remove an item (and, recursively, its whole subtree) from its own root's id index - the reverse of
+ * registerItemIds. Call before the item is actually detached, while its parentItem chain still resolves and
+ * its own subtree is still intact to walk.
+ * @param item - The subtree to unregister, root item included.
+ */
+const unregisterItemIds = item => {
+  const root = tryGetRoot(item);
+  if (!root) {
+    return;
+  }
+  itemsById.delete(root, item.id);
+  (item.children || []).forEach(exports.unregisterItemIds);
+};
+exports.unregisterItemIds = unregisterItemIds;
+/**
+ * Resolve an id (as captured off a DomItem's own id) back to the item it refers to, within root's own tree.
+ * Throws when the id isn't registered against this root - the same "stale reference" contract getItemByPath
+ * already has: a silent wrong-answer resolution is worse than a loud failure.
+ * @param root - The tree to resolve the id against.
+ * @param id - The id to resolve, as read directly off a DomItem's own id property.
+ */
+const getItemById = (root, id) => {
+  const item = itemsById.get(root, id);
+  if (!item) {
+    throw new Error(`No item with id ${id} in this tree - it may have been removed, or never belonged to it.`);
+  }
+  return item;
+};
+exports.getItemById = getItemById;

package/dist/domItem/tree/itemIdIndex.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0}),exports.getItemById=exports.unregisterItemIds=exports.registerItemIds=exports.generateItemId=void 0;const si_funciona_1=__importDefault(require("si-funciona")),collect_your_stuff_1=require("collect-your-stuff"),itemsById=new collect_your_stuff_1.ScopedCollection;let nextItemId=0;const generateItemId=()=>nextItemId++;exports.generateItemId=generateItemId;const tryGetRoot=e=>{let t=e;for(;null!=t.parentItem;){if(si_funciona_1.default.emptyObject(t.parentItem))return t;t=t.parentItem}return null},registerItemIds=e=>{const t=tryGetRoot(e);if(!t)return;const r="number"==typeof e.id?itemsById.get(t,e.id):void 0;("number"!=typeof e.id||r&&r!==e)&&(e.id=(0,exports.generateItemId)()),itemsById.set(t,e.id,e),(e.children||[]).forEach(exports.registerItemIds)};exports.registerItemIds=registerItemIds;const unregisterItemIds=e=>{const t=tryGetRoot(e);t&&(itemsById.delete(t,e.id),(e.children||[]).forEach(exports.unregisterItemIds))};exports.unregisterItemIds=unregisterItemIds;const getItemById=(e,t)=>{const r=itemsById.get(e,t);if(!r)throw new Error(`No item with id ${t} in this tree - it may have been removed, or never belonged to it.`);return r};exports.getItemById=getItemById;

package/dist/domItem/tree/removeChild.d.ts

@@ -0,0 +1,8 @@
+import type { DomItem } from '../types';
+/**
+ * Reverse of appendHtml, remove a DomItem and have the associated element removed.
+ * @param parent - The parent of the items
+ * @param child - The DomItem with HTMLElement to be removed
+ */
+declare const removeChild: (parent: DomItem, child: DomItem) => DomItem[];
+export default removeChild;

package/dist/domItem/tree/removeChild.js

@@ -0,0 +1,21 @@
+"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("./itemIdIndex");
+/**
+ * Reverse of appendHtml, remove a DomItem and have the associated element removed.
+ * @param parent - The parent of the items
+ * @param child - The DomItem with HTMLElement to be removed
+ */
+const removeChild = (parent, child) => {
+  // Before detaching: child's own parentItem chain (still pointing at parent) is what resolves its root.
+  (0, itemIdIndex_1.unregisterItemIds)(child);
+  parent.element.removeChild(child.element);
+  return parent.children.splice(parent.children.indexOf(child), 1);
+};
+exports.default = removeChild;

package/dist/domItem/tree/removeChild.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const itemIdIndex_1=require("./itemIdIndex"),removeChild=(e,d)=>((0,itemIdIndex_1.unregisterItemIds)(d),e.element.removeChild(d.element),e.children.splice(e.children.indexOf(d),1));exports.default=removeChild;

package/dist/domItem/tree/setParentItemReferences.d.ts

@@ -0,0 +1,7 @@
+import type { DomItem } from '../types';
+/**
+ * For each child of this item, set the parentItem references.
+ * @param item - The DomItem to have parent references applied.
+ */
+declare const setParentItemReferences: (item: DomItem) => DomItem;
+export default setParentItemReferences;

package/dist/domItem/tree/setParentItemReferences.js

@@ -0,0 +1,24 @@
+"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
+});
+/**
+ * For each child of this item, set the parentItem references.
+ * @param item - The DomItem to have parent references applied.
+ */
+const setParentItemReferences = item => {
+  if (!item.children || !item.children.length) {
+    item.children = [];
+    return item;
+  }
+  item.children.forEach(child => {
+    child.parentItem = item;
+    setParentItemReferences(child);
+  });
+  return item;
+};
+exports.default = setParentItemReferences;

package/dist/domItem/tree/setParentItemReferences.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const setParentItemReferences=e=>e.children&&e.children.length?(e.children.forEach(t=>{t.parentItem=e,setParentItemReferences(t)}),e):(e.children=[],e);exports.default=setParentItemReferences;

package/dist/domItem/types.d.ts

@@ -0,0 +1,131 @@
+import type { EventListeners, EventName, EventResponder, ForwardEventsFunction, ListenerFunction } from '../events/types';
+/** CSS property names (written in camelCase, like element.style) and their values. */
+export type StyleValues = {
+    [property: string]: string;
+};
+/** A value an attribute can have. Objects are only used for the style attribute. */
+export type AttributeValue = string | number | boolean | StyleValues | null | undefined;
+/** All the HTML attributes of an element (className, style, id, innerHTML, data attributes, ...). */
+export type Attributes = {
+    className?: string;
+    style?: StyleValues;
+    /** The native custom element name (a customized built-in): <button is="fancy-button">. */
+    is?: string;
+    [attribute: string]: AttributeValue;
+};
+/** A real node which a DomItem is mirrored onto. */
+export type DomElement = HTMLElement | Text | Comment | Document;
+/** The path from the root to an item: each level's index among its parent's children, top-down. An empty array
+ * means the item is the root itself. See getItemPath, getItemByPath. */
+export type ItemPath = number[];
+/** The parent of the root DomItem is an empty object (a null parent means the item is detached). */
+export type EmptyParent = Record<string, never>;
+/**
+ * The traits an item can have, and the data each one puts on it. treeloom has one - render - and other libraries
+ * add theirs by declaration merging:
+ *
+ *     declare module 'treeloom/dist/domItem/types' {
+ *       interface TraitRegistry { 'matrix.row': { axis: 'y' } }
+ *     }
+ */
+export interface TraitRegistry {
+    /** The item has a place for a real element (it stays null until the item is rendered). */
+    render: RenderProperties;
+}
+/** The name of a trait. */
+export type TraitName = keyof TraitRegistry;
+/** The traits an item has: a map of trait name to true. */
+export type HasMap = {
+    [Trait in TraitName]?: true;
+};
+/** What the render trait puts on an item. */
+export type RenderProperties = {
+    /** The real node this item is mirrored onto, or null while there is none. */
+    element: DomElement | null;
+    /** Generated: the listeners which are attached to the element, by event name. */
+    activeListeners?: Record<EventName, Record<number, EventResponder[]>>;
+};
+type UnionToIntersection<Union> = (Union extends unknown ? (member: Union) => void : never) extends (member: infer All) => void ? All : never;
+/** What an item gains from having all of these traits: they are in its has map, and their data is on it. */
+export type WithTraits<Trait extends TraitName> = {
+    has: {
+        [Name in Trait]: true;
+    };
+} & UnionToIntersection<TraitRegistry[Trait]>;
+/** The properties every item has, whatever traits it carries. */
+export type CoreProperties = {
+    attributes: Attributes;
+    /** All the events to be registered for the element. */
+    eventListeners: Record<EventName, EventListeners>;
+    /** The traits this item has (see TraitRegistry). */
+    has: HasMap;
+    /** Assigned once at creation (see createCoreItem) and never reassigned, including across a clone or a JSON
+     * round-trip: the stable identity getItemById resolves by, independent of the item's current position in
+     * the tree (which a client's own tree may not match exactly - see ForwardedEvent's itemId). */
+    id: number;
+    /** Property names to leave out when converting to json. */
+    jsonExclusions: string[];
+    /** Any document node name: a tag name, #text, #comment or #document. */
+    nodeName: string;
+    /** The text of a text or comment node, null for elements. */
+    nodeValue: string | null;
+    /** Attach a child to this item. */
+    appendChild(child: CoreItem): CoreItem;
+    /** Detach a child from this item (and its element, when it has one). */
+    removeChild(child: CoreItem): CoreItem[];
+};
+/**
+ * The generic item: one node of a tree, with the traits it carries. A back-end item which is never rendered is a
+ * CoreItem; use hasTrait to find out what else it has.
+ */
+export type CoreItem = CoreProperties & {
+    children: CoreItem[];
+    /** The parent item: an empty object for the root, null for an item which is not attached. */
+    parentItem: CoreItem | EmptyParent | null;
+};
+/**
+ * An item with the render trait: the item treeloom mirrors onto a real element (render) and reads back from one
+ * (sync). Its children have the render trait too.
+ */
+export type DomItem = CoreProperties & WithTraits<'render'> & {
+    children: DomItem[];
+    parentItem: DomItem | EmptyParent | null;
+    appendChild(child: DomItem): DomItem;
+    removeChild(child: DomItem): DomItem[];
+};
+/**
+ * What can be given to build an item: any of its properties (the children may be plain configs as well), plus any
+ * custom data. Whatever is left out gets its default.
+ */
+export type DomItemConfig = Partial<Omit<CoreProperties, 'appendChild' | 'removeChild'>> & Partial<RenderProperties> & {
+    children?: DomItemConfig[];
+    parentItem?: CoreItem | EmptyParent | null;
+    [custom: string]: unknown;
+};
+/** The extra properties of the root of a Virtual DOM. */
+export type RootProperties = {
+    /** Registered listener functions, by name. */
+    eventActions: Record<string, ListenerFunction>;
+    /** Set with setForwardEvents to switch into render-only mode: every listener name resolves to a forwarder which
+     * sends this function an envelope instead of running local logic. See retrieveListener. */
+    forwardEvents?: ForwardEventsFunction;
+    head: DomItem;
+    body: DomItem;
+};
+/** The root of a Virtual DOM (the #document): the head and body items and the registered named listeners. */
+export type DomItemRoot = DomItem & RootProperties;
+/** What a trait is at runtime: which properties it puts on an item, and whether they belong in json. */
+export type TraitDefinition = {
+    /** The properties the trait puts on an item. */
+    keys: string[];
+    /** False for properties which only make sense where the item lives (an element): they are left out of json. */
+    serializable?: boolean;
+    /** The data a new item gets when it is given the trait. */
+    defaults?: () => Record<string, unknown>;
+};
+/**
+ * Decides which items below (and including) an item are wanted. It receives the item being tested and everything
+ * gathered so far, and returns the gathered results with the item added if it qualifies.
+ */
+export type ChildTest = (item: DomItem, gatheredResults: DomItem[]) => DomItem[];
+export {};

package/dist/domItem/types.js

@@ -0,0 +1,8 @@
+"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
+});

package/dist/domItem/types.min.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});

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

@@ -0,0 +1,10 @@
+import type { DomItem } from '../../domItem/types';
+import type { EventName, ListenerDescriptor } from '../types';
+/**
+ * Activate listener by pushing it to activeListeners.
+ * @param eventName
+ * @param eventListener
+ * @param item
+ */
+declare const activateListener: (eventName: EventName, eventListener: ListenerDescriptor, item: DomItem) => DomItem;
+export default activateListener;

package/dist/events/functions/activateListener.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 getTopParentItem_1 = __importDefault(require("../../domItem/tree/getTopParentItem"));
+const makeEventHandler_1 = __importDefault(require("./makeEventHandler"));
+const createEventResponder_1 = __importDefault(require("../objects/createEventResponder"));
+const getListenerOptions_1 = __importDefault(require("../objects/options/getListenerOptions"));
+const optionsToNumber_1 = __importDefault(require("../objects/options/optionsToNumber"));
+const retrieveListener_1 = __importDefault(require("./retrieveListener"));
+/**
+ * Activate listener by pushing it to activeListeners.
+ * @param eventName
+ * @param eventListener
+ * @param item
+ */
+const activateListener = (eventName, eventListener, item) => {
+  const listenerOptions = (0, getListenerOptions_1.default)();
+  if (typeof item.activeListeners === 'undefined') {
+    item.activeListeners = {};
+  }
+  if (!(eventName in item.activeListeners)) {
+    item.activeListeners[eventName] = {};
+  }
+  const optionIdentifier = (0, optionsToNumber_1.default)(listenerOptions, eventListener.listenerOptions);
+  if (!(optionIdentifier in item.activeListeners[eventName])) {
+    item.activeListeners[eventName][optionIdentifier] = [];
+  }
+  const listenerFunc = (0, retrieveListener_1.default)(eventListener.listenerFunc, (0, getTopParentItem_1.default)(item));
+  const eventHandler = (0, makeEventHandler_1.default)(listenerFunc, item, eventListener.listenerArgs);
+  const eventResponder = (0, createEventResponder_1.default)(eventHandler, !!(optionIdentifier & listenerOptions.signal));
+  item.activeListeners[eventName][optionIdentifier].push(eventResponder);
+  eventListener.activeResponder = eventResponder;
+  return item;
+};
+exports.default = activateListener;

package/dist/events/functions/activateListener.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 getTopParentItem_1=__importDefault(require("../../domItem/tree/getTopParentItem")),makeEventHandler_1=__importDefault(require("./makeEventHandler")),createEventResponder_1=__importDefault(require("../objects/createEventResponder")),getListenerOptions_1=__importDefault(require("../objects/options/getListenerOptions")),optionsToNumber_1=__importDefault(require("../objects/options/optionsToNumber")),retrieveListener_1=__importDefault(require("./retrieveListener")),activateListener=(e,t,r)=>{const i=(0,getListenerOptions_1.default)();void 0===r.activeListeners&&(r.activeListeners={}),e in r.activeListeners||(r.activeListeners[e]={});const n=(0,optionsToNumber_1.default)(i,t.listenerOptions);n in r.activeListeners[e]||(r.activeListeners[e][n]=[]);const s=(0,retrieveListener_1.default)(t.listenerFunc,(0,getTopParentItem_1.default)(r)),o=(0,makeEventHandler_1.default)(s,r,t.listenerArgs),a=(0,createEventResponder_1.default)(o,!!(n&i.signal));return r.activeListeners[e][n].push(a),t.activeResponder=a,r};exports.default=activateListener;

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

@@ -0,0 +1,23 @@
+import type { DomItem } from '../../domItem/types';
+import type { EventName, ListenerFunction, ListenerOptions } from '../types';
+/**
+ * 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.
+ */
+declare const addEventListener: (eventName: EventName, listenerFunction: string | ListenerFunction, customArgs: object | null | undefined, options: ListenerOptions | null | undefined, item: DomItem) => DomItem;
+export default addEventListener;