treeloom 0.0.0-stage → 2.1.0

package/dist/events/objects/options/numberToOptions.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/. */
+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"));
+/**
+ * Take an integer representation of the listener options and convert them to the listener options object.
+ * @param optionsTemplate
+ * @param binaryOptions
+ */
+const numberToOptions = (optionsTemplate, binaryOptions) => si_funciona_1.default.mapObject(optionsTemplate, flag => !!(binaryOptions & flag));
+exports.default = numberToOptions;

package/dist/events/objects/options/numberToOptions.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")),numberToOptions=(e,t)=>si_funciona_1.default.mapObject(e,e=>!!(t&e));exports.default=numberToOptions;

package/dist/events/objects/options/optionsToNumber.d.ts

@@ -0,0 +1,9 @@
+import type { ListenerOptions, OptionsTemplate } from '../../types';
+/**
+ * Take the given options and convert them (using binary) to an integer. Given listener options, each one is assigned a
+ * bitwise position. The resulting binary number represents any possible combination of the available flags set.
+ * @param optionsTemplate
+ * @param listenerOptions
+ */
+declare const optionsToNumber: (optionsTemplate: OptionsTemplate, listenerOptions?: ListenerOptions | null) => number;
+export default optionsToNumber;

package/dist/events/objects/options/optionsToNumber.js

@@ -0,0 +1,27 @@
+"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"));
+/**
+ * Take the given options and convert them (using binary) to an integer. Given listener options, each one is assigned a
+ * bitwise position. The resulting binary number represents any possible combination of the available flags set.
+ * @param optionsTemplate
+ * @param listenerOptions
+ */
+const optionsToNumber = (optionsTemplate, listenerOptions) => {
+  if (!listenerOptions) {
+    return 0;
+  }
+  return si_funciona_1.default.reduceObject(optionsTemplate, (binaryOptions, flag, name) => listenerOptions[name] ? binaryOptions | flag : binaryOptions, 0);
+};
+exports.default = optionsToNumber;

package/dist/events/objects/options/optionsToNumber.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")),optionsToNumber=(e,t)=>t?si_funciona_1.default.reduceObject(e,(e,o,u)=>t[u]?e|o:e,0):0;exports.default=optionsToNumber;

package/dist/events/objects/options.d.ts

@@ -0,0 +1,6 @@
+declare const _default: {
+    getListenerOptions: () => import("../types").OptionsTemplate;
+    numberToOptions: (optionsTemplate: import("../types").OptionsTemplate, binaryOptions: number) => import("../types").OptionsObject;
+    optionsToNumber: (optionsTemplate: import("../types").OptionsTemplate, listenerOptions?: import("../types").ListenerOptions | null) => number;
+};
+export default _default;

package/dist/events/objects/options.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/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+/**
+ * Be able to use Flags (Options) in a well-formed way.
+ */
+const getListenerOptions_1 = __importDefault(require("./options/getListenerOptions"));
+const numberToOptions_1 = __importDefault(require("./options/numberToOptions"));
+const optionsToNumber_1 = __importDefault(require("./options/optionsToNumber"));
+exports.default = {
+  getListenerOptions: getListenerOptions_1.default,
+  numberToOptions: numberToOptions_1.default,
+  optionsToNumber: optionsToNumber_1.default
+};

package/dist/events/objects/options.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 getListenerOptions_1=__importDefault(require("./options/getListenerOptions")),numberToOptions_1=__importDefault(require("./options/numberToOptions")),optionsToNumber_1=__importDefault(require("./options/optionsToNumber"));exports.default={getListenerOptions:getListenerOptions_1.default,numberToOptions:numberToOptions_1.default,optionsToNumber:optionsToNumber_1.default};

package/dist/events/types.d.ts

@@ -0,0 +1,87 @@
+import type { DomItem } from '../domItem/types';
+/** The name of a DOM event: click, submit, keydown, ... */
+export type EventName = string;
+/** The old boolean form of the options argument of addEventListener. */
+export type UseCapture = boolean;
+/** The listener options which treeloom understands (each one is a flag, see {@link OptionsTemplate}). */
+export type OptionsObject = {
+    /** Events of this type are dispatched to the listener before any other target beneath it. */
+    capture?: boolean;
+    /** The listener is removed after it has been invoked once. */
+    once?: boolean;
+    /** The listener will never call preventDefault(). */
+    passive?: boolean;
+    /** The listener is removed when the AbortSignal's abort() is called. */
+    signal?: boolean | AbortSignal;
+};
+/** The options given with a listener: an options object, or just the useCapture boolean. */
+export type ListenerOptions = OptionsObject | UseCapture;
+/** An Event which also remembers whether stopImmediatePropagation() was called on it, and carries the DomItems
+ * target/currentTarget correspond to. */
+export type EventProxy = Event & {
+    immediatePropagationStopped: boolean;
+    /** The DomItem whose element matches the real event's target, searched for within currentDomItemTarget's own
+     * subtree (an event's target is always itself or a descendant of the item a listener is attached to - that is
+     * what bubbling means). Null when none is found. */
+    domItemTarget: DomItem | null;
+    /** The DomItem the listener is attached to (the real event's currentTarget). */
+    currentDomItemTarget: DomItem;
+};
+/**
+ * A function which handles an event on a DomItem. It receives the event, the DomItem which owns the listener and any
+ * listenerArgs. (The extra arguments are whatever the listener needs, so they can only be typed by the listener.)
+ */
+export type ListenerFunction = (event: EventProxy | Event, target: DomItem, ...args: any[]) => unknown;
+/** A listenerFunction wrapped so it skips events which stopped propagating, ready to be attached to an element. */
+export type EventHandler = (event?: EventProxy | Event | null) => unknown;
+/** The description of one listener on a DomItem: what to call, with what, and how. */
+export type ListenerDescriptor = {
+    /** Prefer a string name registered with registerListener: it survives being converted to json. */
+    listenerFunc: string | ListenerFunction;
+    /** Additional arguments for the listener function. */
+    listenerArgs?: object | null;
+    listenerOptions?: ListenerOptions;
+    /** Whether this listener has been applied to the element. */
+    listenerActive?: boolean;
+    /** Set while the listener is active: the responder which attaches it to the element and can detach it again. */
+    activeResponder?: EventResponder | null;
+};
+/** All the listeners of one event type. */
+export type EventListeners = ListenerDescriptor[];
+/** What a forwarded event is packaged as in render-only mode. See retrieveListener, makeForwardingListener. */
+export type ForwardedEvent = {
+    /** The id of the item the event fired on (domItemTarget, falling back to the item the listener is attached
+     * to when no domItemTarget was found) - read directly off that item's own id, not computed. Resolution is a
+     * lookup (getItemById) rather than a tree walk, so it still finds the right item even if the receiving end's
+     * own tree does not match the sending end's shape exactly (see getItemById vs the position-based
+     * getItemPath/getItemByPath this replaced). */
+    itemId: number;
+    /** The type of event which fired (event.type). */
+    eventType: EventName;
+    /** The registered name of the listener which would have run locally. */
+    listenerFunc: string;
+    /** The custom args the listener was registered with. */
+    data: unknown[];
+    /** Live state read directly off the real event's target when present - a listener which reads e.g.
+     * (event.target as HTMLInputElement).checked needs this replayed onto the real target on the receiving end
+     * (see receiveForwardedEvent), since the two ends' elements are otherwise independent objects. */
+    targetState?: {
+        checked?: boolean;
+        value?: string;
+    };
+};
+/** Where a forwarded event's envelope is sent, in render-only mode. Set on the root item with setForwardEvents. */
+export type ForwardEventsFunction = (envelope: ForwardedEvent) => unknown;
+/** An event handler and the way to detach it again: the handler as attached, and an optional AbortController. */
+export type EventResponder = {
+    handler: EventHandler;
+    abort: AbortController | null;
+    /** The exact function reference passed to the element's addEventListener, needed to remove it again. */
+    assignedHandler: EventHandler | null;
+};
+/** Bit flags for each of the listener options. */
+export type OptionsTemplate = Record<string, number>;
+/** What treeloom needs from an element to attach a listener, including the very old ways of doing it. */
+export type ListenerTarget = EventTarget & {
+    attachEvent?: (eventName: string, handler: EventHandler) => void;
+};

package/dist/events/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/events/types.min.js

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

package/dist/inflate/index.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    jsonToDomItem: (jsonString: string) => import("../domItem/types").DomItem;
+};
+export default _default;

package/dist/inflate/index.js

@@ -0,0 +1,17 @@
+"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 jsonToDomItem_1 = __importDefault(require("./jsonToDomItem"));
+exports.default = {
+  jsonToDomItem: jsonToDomItem_1.default
+};

package/dist/inflate/index.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 jsonToDomItem_1=__importDefault(require("./jsonToDomItem"));exports.default={jsonToDomItem:jsonToDomItem_1.default};

package/dist/inflate/jsonToDomItem.d.ts

@@ -0,0 +1,7 @@
+import type { DomItem } from '../domItem/types';
+/**
+ * Convert DOM Item to JSON string.
+ * @param jsonString
+ */
+declare const jsonToDomItem: (jsonString: string) => DomItem;
+export default jsonToDomItem;

package/dist/inflate/jsonToDomItem.js

@@ -0,0 +1,30 @@
+"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 setParentItemReferences_1 = __importDefault(require("../domItem/tree/setParentItemReferences"));
+const addDomItemProperties_1 = __importDefault(require("../domItem/objects/addDomItemProperties"));
+/**
+ * Convert DOM Item to JSON string.
+ * @param jsonString
+ */
+const jsonToDomItem = jsonString => {
+  const parsedJson = (0, setParentItemReferences_1.default)((0, addDomItemProperties_1.default)(JSON.parse(jsonString)));
+  if (parsedJson.nodeName === '#document') {
+    const root = parsedJson;
+    root.element = document;
+    root.head = root.children[0];
+    root.body = root.children[1];
+  }
+  return parsedJson;
+};
+exports.default = jsonToDomItem;

package/dist/inflate/jsonToDomItem.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 setParentItemReferences_1=__importDefault(require("../domItem/tree/setParentItemReferences")),addDomItemProperties_1=__importDefault(require("../domItem/objects/addDomItemProperties")),jsonToDomItem=e=>{const t=(0,setParentItemReferences_1.default)((0,addDomItemProperties_1.default)(JSON.parse(e)));if("#document"===t.nodeName){const e=t;e.element=document,e.head=e.children[0],e.body=e.children[1]}return t};exports.default=jsonToDomItem;

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+declare const treeloom: any;
+export = treeloom;

package/dist/main.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/. */
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+/**
+ * All of the JSON DOM system functions for building and syncing a Virtual DOM (DomItem tree) to the real HTML DOM.
+ */
+const index_1 = __importDefault(require("./events/index"));
+const index_2 = __importDefault(require("./domItem/index"));
+const documentItem_1 = require("./domItem/objects/documentItem");
+const index_3 = __importDefault(require("./inflate/index"));
+const index_4 = __importDefault(require("./deflate/index"));
+const index_5 = __importDefault(require("./render/index"));
+const index_6 = __importDefault(require("./sync/index"));
+const index_7 = __importDefault(require("./diff/index"));
+// documentItem is a getter (see withDocumentItem), so loading treeloom never touches a real document
+const treeloom = (0, documentItem_1.withDocumentItem)(Object.assign({}, index_1.default, index_2.default, index_3.default, index_4.default, index_5.default, index_6.default, index_7.default));
+module.exports = treeloom;

package/dist/main.min.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};const index_1=__importDefault(require("./events/index")),index_2=__importDefault(require("./domItem/index")),documentItem_1=require("./domItem/objects/documentItem"),index_3=__importDefault(require("./inflate/index")),index_4=__importDefault(require("./deflate/index")),index_5=__importDefault(require("./render/index")),index_6=__importDefault(require("./sync/index")),index_7=__importDefault(require("./diff/index")),treeloom=(0,documentItem_1.withDocumentItem)(Object.assign({},index_1.default,index_2.default,index_3.default,index_4.default,index_5.default,index_6.default,index_7.default));module.exports=treeloom;

package/dist/render/generateElement.d.ts

@@ -0,0 +1,7 @@
+import type { DomItem } from '../domItem/types';
+/**
+ * Create an HTML element based on the provided attributes and return the element as an Object.
+ * @param domItem - The DomItem requiring matching HTML element property
+ */
+declare const generateElement: (domItem: DomItem) => DomItem;
+export default generateElement;

package/dist/render/generateElement.js

@@ -0,0 +1,41 @@
+"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 updateElement_1 = __importDefault(require("./updateElement"));
+/**
+ * Create a new DOM Node based on name and data.
+ * @param nodeName
+ * @param data
+ */
+const makeElementType = (nodeName, data = null, is) => {
+  switch (nodeName) {
+    case '#text':
+      return document.createTextNode(data);
+    case '#comment':
+      return document.createComment(data);
+    default:
+      // A customized built-in element (<button is="fancy-button">) has to be given its name when it is created
+      return is ? document.createElement(nodeName, {
+        is
+      }) : document.createElement(nodeName);
+  }
+};
+/**
+ * Create an HTML element based on the provided attributes and return the element as an Object.
+ * @param domItem - The DomItem requiring matching HTML element property
+ */
+const generateElement = domItem => {
+  domItem.element = makeElementType(domItem.nodeName, domItem.nodeValue, typeof domItem.attributes.is === 'string' ? domItem.attributes.is : undefined);
+  return (0, updateElement_1.default)(domItem);
+};
+exports.default = generateElement;

package/dist/render/generateElement.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 updateElement_1=__importDefault(require("./updateElement")),makeElementType=(e,t=null,n)=>{switch(e){case"#text":return document.createTextNode(t);case"#comment":return document.createComment(t);default:return n?document.createElement(e,{is:n}):document.createElement(e)}},generateElement=e=>(e.element=makeElementType(e.nodeName,e.nodeValue,"string"==typeof e.attributes.is?e.attributes.is:void 0),(0,updateElement_1.default)(e));exports.default=generateElement;

package/dist/render/index.d.ts

@@ -0,0 +1,9 @@
+declare const _default: {
+    generateElement: (domItem: import("../domItem/types").DomItem) => import("../domItem/types").DomItem;
+    reconcile: (existing: import("../domItem/types").DomItem, next: import("../domItem/types").DomItem) => import("../domItem/types").DomItem;
+    renderHtml: (item?: import("../domItem/types").DomItem | null, parent?: import("../domItem/types").DomItem, index?: number) => import("../domItem/types").DomItem;
+    updateChildNodes: (domItem: import("../domItem/types").DomItem) => import("../domItem/types").DomItem;
+    updateElement: (domItem: import("../domItem/types").DomItem) => import("../domItem/types").DomItem;
+    updateElements: (config: import("../domItem/types").DomItem) => import("../domItem/types").DomItem;
+};
+export default _default;

package/dist/render/index.js

@@ -0,0 +1,27 @@
+"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 generateElement_1 = __importDefault(require("./generateElement"));
+const reconcile_1 = __importDefault(require("./reconcile"));
+const renderHtml_1 = __importDefault(require("./renderHtml"));
+const updateChildNodes_1 = __importDefault(require("./updateChildNodes"));
+const updateElement_1 = __importDefault(require("./updateElement"));
+const updateElements_1 = __importDefault(require("./updateElements"));
+exports.default = {
+  generateElement: generateElement_1.default,
+  reconcile: reconcile_1.default,
+  renderHtml: renderHtml_1.default,
+  updateChildNodes: updateChildNodes_1.default,
+  updateElement: updateElement_1.default,
+  updateElements: updateElements_1.default
+};

package/dist/render/index.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 generateElement_1=__importDefault(require("./generateElement")),reconcile_1=__importDefault(require("./reconcile")),renderHtml_1=__importDefault(require("./renderHtml")),updateChildNodes_1=__importDefault(require("./updateChildNodes")),updateElement_1=__importDefault(require("./updateElement")),updateElements_1=__importDefault(require("./updateElements"));exports.default={generateElement:generateElement_1.default,reconcile:reconcile_1.default,renderHtml:renderHtml_1.default,updateChildNodes:updateChildNodes_1.default,updateElement:updateElement_1.default,updateElements:updateElements_1.default};

package/dist/render/reconcile.d.ts

@@ -0,0 +1,16 @@
+import type { DomItem } from '../domItem/types';
+/**
+ * Update a rendered tree to match a new version of it (the next tree, such as one inflated from a server's JSON), by
+ * changing only what differs instead of rendering everything again. Children are matched by id, otherwise by
+ * position and node name. A matched item keeps its element, its id and its listeners; it takes the next item's
+ * attributes and data, and its named listeners are made the next item's. Items the next tree doesn't have are removed,
+ * new ones are added, and then only the changed attributes and nodes are written to the page (see updateElement).
+ *
+ * Listeners added as functions (locally, not carried by the next tree) and focus stay where they are, since the
+ * elements do.
+ * @param existing - An item already rendered (it has an element). It stays the same kind of node: next must be one too.
+ * @param next - The tree it should now match. Its items are taken over: don't render it separately.
+ * @returns existing, updated.
+ */
+declare const reconcile: (existing: DomItem, next: DomItem) => DomItem;
+export default reconcile;

package/dist/render/reconcile.js

@@ -0,0 +1,169 @@
+"use strict";
+
+require("core-js/modules/es.array.includes.js");
+require("core-js/modules/es.json.stringify.js");
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+/* 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/. */
+const removeEventListener_1 = __importDefault(require("../events/functions/removeEventListener"));
+const itemIdIndex_1 = require("../domItem/tree/itemIdIndex");
+const updateElements_1 = __importDefault(require("./updateElements"));
+/** What makes an item part of the tree rather than its data: kept on the existing item, never taken from the next.
+ * The id is taken from the next item, so ids stay the ones the next tree (a server's, say) gives its items. */
+const STRUCTURE = new Set(['element', 'parentItem', 'children', 'eventListeners', 'activeListeners']);
+/**
+ * A named listener as plain data, to tell whether two items have the same one. Only named listeners are compared: they
+ * are the ones a tree carries as JSON. A listener given as a function was added locally (keyboard navigation, say)
+ * and is never in the next tree, so it is left alone.
+ * @param listener
+ */
+const listenerKey = listener => typeof listener.listenerFunc === 'string' ? JSON.stringify([listener.listenerFunc, listener.listenerArgs ?? null, listener.listenerOptions ?? null]) : null;
+/**
+ * Make existing's named listeners the next item's: remove the ones the next item doesn't have (detached from the
+ * element), and add the ones it gains (bound when the element is updated). Unchanged ones stay bound as they are.
+ * @param existing
+ * @param next
+ */
+const reconcileListeners = (existing, next) => {
+  const nextListeners = next.eventListeners ?? {};
+  existing.eventListeners = existing.eventListeners ?? {};
+  for (const eventName of Object.keys(existing.eventListeners)) {
+    const wanted = (nextListeners[eventName] ?? []).map(listenerKey);
+    for (const listener of [...existing.eventListeners[eventName]]) {
+      const key = listenerKey(listener);
+      if (key !== null && !wanted.includes(key)) {
+        (0, removeEventListener_1.default)(eventName, listener.listenerFunc, listener.listenerArgs, listener.listenerOptions, existing);
+      }
+    }
+  }
+  for (const eventName of Object.keys(nextListeners)) {
+    const have = (existing.eventListeners[eventName] ?? []).map(listenerKey);
+    for (const listener of nextListeners[eventName]) {
+      const key = listenerKey(listener);
+      if (key !== null && !have.includes(key)) {
+        existing.eventListeners[eventName] = existing.eventListeners[eventName] ?? [];
+        existing.eventListeners[eventName].push({
+          ...listener,
+          listenerActive: false,
+          activeResponder: null
+        });
+      }
+    }
+  }
+};
+/**
+ * Make existing's own data the next item's (its id included): every property but the structure (element, parent,
+ * children, listeners). A property the next item doesn't have is removed, unless it is a function (something added locally).
+ * @param existing
+ * @param next
+ */
+const reconcileData = (existing, next) => {
+  const target = existing;
+  const source = next;
+  for (const key of Object.keys(target)) {
+    if (!STRUCTURE.has(key) && !(key in source) && typeof target[key] !== 'function') {
+      delete target[key];
+    }
+  }
+  for (const key of Object.keys(source)) {
+    if (!STRUCTURE.has(key)) {
+      target[key] = source[key];
+    }
+  }
+};
+/**
+ * Pair each next child with the existing child it updates: the one with the same id, otherwise the one at the same
+ * position when it is the same kind of node and no next child has it by id (an item without an id in the JSON, a
+ * text node say, gets a fresh one when inflated, so its id says nothing about which item it was). Unpaired next
+ * children are new.
+ * @param existing
+ * @param next
+ */
+const pairChildren = (existing, next) => {
+  const byId = new Map();
+  existing.forEach(child => {
+    if (typeof child.id === 'number') {
+      byId.set(child.id, child);
+    }
+  });
+  // An existing child some next child has by id is that one's, never another's by position
+  const claimed = new Set(next.map(child => typeof child.id === 'number' ? byId.get(child.id) : undefined).filter(Boolean));
+  const taken = new Set();
+  return next.map((nextChild, index) => {
+    const sameId = typeof nextChild.id === 'number' ? byId.get(nextChild.id) : undefined;
+    const atPosition = existing[index] && !claimed.has(existing[index]) ? existing[index] : undefined;
+    const candidate = sameId ?? atPosition;
+    if (candidate && !taken.has(candidate) && candidate.nodeName === nextChild.nodeName) {
+      taken.add(candidate);
+      return candidate;
+    }
+    return undefined;
+  });
+};
+/**
+ * Update existing's subtree to match next's, reusing every item (and its element and listeners) that next still has.
+ * Items next no longer has are removed; new ones are added. Elements are not touched here; see reconcile.
+ * @param existing
+ * @param next
+ */
+const reconcileItem = (existing, next) => {
+  reconcileData(existing, next);
+  reconcileListeners(existing, next);
+  const previous = existing.children ?? [];
+  const nextChildren = next.children ?? [];
+  const pairs = pairChildren(previous, nextChildren);
+  const kept = new Set(pairs.filter(Boolean));
+  previous.filter(child => !kept.has(child)).forEach(child => {
+    // Removed (already out of the id index, see reconcile): its element out of the page
+    ;
+    child.element?.remove?.();
+  });
+  existing.children = nextChildren.map((nextChild, index) => {
+    const child = pairs[index];
+    if (child) {
+      reconcileItem(child, nextChild);
+      return child;
+    }
+    // New: taken as it is; its element is generated when the subtree is updated below
+    nextChild.parentItem = existing;
+    return nextChild;
+  });
+  existing.children.forEach(child => {
+    child.parentItem = existing;
+  });
+};
+/**
+ * Update a rendered tree to match a new version of it (the next tree, such as one inflated from a server's JSON), by
+ * changing only what differs instead of rendering everything again. Children are matched by id, otherwise by
+ * position and node name. A matched item keeps its element, its id and its listeners; it takes the next item's
+ * attributes and data, and its named listeners are made the next item's. Items the next tree doesn't have are removed,
+ * new ones are added, and then only the changed attributes and nodes are written to the page (see updateElement).
+ *
+ * Listeners added as functions (locally, not carried by the next tree) and focus stay where they are, since the
+ * elements do.
+ * @param existing - An item already rendered (it has an element). It stays the same kind of node: next must be one too.
+ * @param next - The tree it should now match. Its items are taken over: don't render it separately.
+ * @returns existing, updated.
+ */
+const reconcile = (existing, next) => {
+  // The item updated in place is where the page's content lives (a <main>, a <body>): changing its kind of node would
+  // replace that element with a new one outside the page. Children of another kind are replaced; this one never is.
+  if (existing.nodeName.toLowerCase() !== next.nodeName.toLowerCase()) {
+    throw new Error(`reconcile can't turn a ${existing.nodeName} into a ${next.nodeName}: give it a tree of the same node, or reconcile its parent.`);
+  }
+  // Ids can change (they follow the next tree), so the subtree leaves the id index first and is indexed again after
+  (0, itemIdIndex_1.unregisterItemIds)(existing);
+  reconcileItem(existing, next);
+  (0, itemIdIndex_1.registerItemIds)(existing);
+  // updateElements patches each item's element (only what changed) and puts its children's elements in order
+  return (0, updateElements_1.default)(existing);
+};
+exports.default = reconcile;

package/dist/render/reconcile.min.js

@@ -0,0 +1 @@
+"use strict";require("core-js/modules/es.array.includes.js"),require("core-js/modules/es.json.stringify.js");var __importDefault=function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0});const removeEventListener_1=__importDefault(require("../events/functions/removeEventListener")),itemIdIndex_1=require("../domItem/tree/itemIdIndex"),updateElements_1=__importDefault(require("./updateElements")),STRUCTURE=new Set(["element","parentItem","children","eventListeners","activeListeners"]),listenerKey=e=>"string"==typeof e.listenerFunc?JSON.stringify([e.listenerFunc,e.listenerArgs??null,e.listenerOptions??null]):null,reconcileListeners=(e,t)=>{const n=t.eventListeners??{};e.eventListeners=e.eventListeners??{};for(const t of Object.keys(e.eventListeners)){const r=(n[t]??[]).map(listenerKey);for(const n of[...e.eventListeners[t]]){const s=listenerKey(n);null===s||r.includes(s)||(0,removeEventListener_1.default)(t,n.listenerFunc,n.listenerArgs,n.listenerOptions,e)}}for(const t of Object.keys(n)){const r=(e.eventListeners[t]??[]).map(listenerKey);for(const s of n[t]){const n=listenerKey(s);null===n||r.includes(n)||(e.eventListeners[t]=e.eventListeners[t]??[],e.eventListeners[t].push({...s,listenerActive:!1,activeResponder:null}))}}},reconcileData=(e,t)=>{const n=e,r=t;for(const e of Object.keys(n))STRUCTURE.has(e)||e in r||"function"==typeof n[e]||delete n[e];for(const e of Object.keys(r))STRUCTURE.has(e)||(n[e]=r[e])},pairChildren=(e,t)=>{const n=new Map;e.forEach(e=>{"number"==typeof e.id&&n.set(e.id,e)});const r=new Set(t.map(e=>"number"==typeof e.id?n.get(e.id):void 0).filter(Boolean)),s=new Set;return t.map((t,i)=>{const o="number"==typeof t.id?n.get(t.id):void 0,c=e[i]&&!r.has(e[i])?e[i]:void 0,l=o??c;if(l&&!s.has(l)&&l.nodeName===t.nodeName)return s.add(l),l})},reconcileItem=(e,t)=>{reconcileData(e,t),reconcileListeners(e,t);const n=e.children??[],r=t.children??[],s=pairChildren(n,r),i=new Set(s.filter(Boolean));n.filter(e=>!i.has(e)).forEach(e=>{e.element?.remove?.()}),e.children=r.map((t,n)=>{const r=s[n];return r?(reconcileItem(r,t),r):(t.parentItem=e,t)}),e.children.forEach(t=>{t.parentItem=e})},reconcile=(e,t)=>{if(e.nodeName.toLowerCase()!==t.nodeName.toLowerCase())throw new Error(`reconcile can't turn a ${e.nodeName} into a ${t.nodeName}: give it a tree of the same node, or reconcile its parent.`);return(0,itemIdIndex_1.unregisterItemIds)(e),reconcileItem(e,t),(0,itemIdIndex_1.registerItemIds)(e),(0,updateElements_1.default)(e)};exports.default=reconcile;

package/dist/render/renderHtml.d.ts

@@ -0,0 +1,16 @@
+import type { DomItem } from '../domItem/types';
+/**
+ * This is a shortcut for syncing a Virtual DOM (DomItem tree) item onto the real HTML DOM: builds the real elements
+ * for it and its descendants, inserts them into parent's children (the document body by default), and binds their
+ * associated listeners.
+ * @param item - The DomItem that we want to render the element for
+ * @param parent - Where to insert item, when it does not already have a parent - defaults to the
+ * document body, so passing nothing keeps working exactly as before
+ * @param index - Where in parent's children to put item - defaults to the end (a plain append), so passing nothing
+ * keeps working exactly as before. To insert item among parent's already-rendered content (existing real HTML),
+ * parent's children must already reflect that content first - see {@link updateDomItems}, which captures the real
+ * DOM into items. Skipping that step and inserting anyway will make the next render remove the untracked content,
+ * since it is invisible to parent.children.
+ */
+declare const renderHtml: (item?: DomItem | null, parent?: DomItem, index?: number) => DomItem;
+export default renderHtml;