treeloom 2.0.0 → 2.1.0

package/README.md

@@ -17,6 +17,8 @@ npm install treeloom
 It is written in TypeScript and ships its types. In a browser, use `browser/treeloom.min.js` (it defines `treeloom`) -
 or, for a build that renders JSON to HTML and forwards fired events elsewhere instead of running local listener
 functions, `browser/treeloomRenderOnly.min.js` (it defines `treeloomRenderOnly`; see `setForwardEvents`).
+The bundles are in the npm package (not in git), so a CDN serves them too, e.g.
+`https://cdn.jsdelivr.net/npm/treeloom@2/browser/treeloom.min.js`.
 
 ## Example
 
@@ -44,6 +46,23 @@ const json = domItemToJson(button)    // a string, without the element and the l
 const copy = jsonToDomItem(json)      // an item again, ready to render
 ```
 
+### Updating from a new version of the tree
+
+When a new version of a tree arrives as a whole (a server sending its state as JSON, say), `reconcile` updates the
+rendered tree to match it instead of rendering everything again. Items are matched by id (otherwise by position and node
+name). Matched items keep their elements, listeners and focus, and only what changed is written to the page.
+
+```js
+const { reconcile } = require('treeloom')
+
+reconcile(button, jsonToDomItem(nextJson)) // same <button> element, only the changed attributes written
+```
+
+Updates compare each item with what treeloom last wrote to its element, not with the element itself, so values the
+browser stores in another form (`#333` as `rgb(51, 51, 51)`) don't count as changes. Changes other scripts make directly
+on an element are left alone; form state the user changes (`value`, `checked`, `selected`) is still put back to the
+item's value, as with a controlled input.
+
 ## Documentation
 
 The reference for every function and type is in [`docs/`](docs/index.html) (open `docs/index.html` in a browser). It is
@@ -52,10 +71,10 @@ generated from the TypeScript source, and each module is a folder of `src/`:
 | Module | What it does |
 | --- | --- |
 | `domItem` | Create items, the traits they carry, and find or change items in the tree |
-| `render` | Mirror the tree onto real elements |
+| `render` | Mirror the tree onto real elements, and update a rendered tree from a new version of it (`reconcile`) |
 | `sync` | Read the real elements back into the tree |
 | `inflate`, `deflate` | Turn a tree into JSON, and JSON back into a tree |
-| `diff` | Work out what differs between an item and its element |
+| `diff` | Work out what differs between an item and what was last written to its element |
 | `events` | Attach listeners to the elements of items |
 
 ## Development

package/browser/treeloom.js

@@ -8438,6 +8438,104 @@ var treeloom = (() => {
     }
   });
 
+  // dist/diff/appliedSnapshot.js
+  var require_appliedSnapshot = __commonJS({
+    "dist/diff/appliedSnapshot.js"(exports) {
+      "use strict";
+      init_process();
+      require_es_array_includes();
+      var __importDefault = function(mod) {
+        return mod && mod.__esModule ? mod : {
+          "default": mod
+        };
+      };
+      Object.defineProperty(exports, "__esModule", {
+        value: true
+      });
+      exports.changesFromApplied = exports.forgetApplied = exports.recordApplied = void 0;
+      var si_funciona_1 = __importDefault(require_main());
+      var createChangeList_1 = __importDefault(require_createChangeList());
+      var LIVE_PROPERTIES = ["value", "checked", "selected", "indeterminate"];
+      var snapshots = /* @__PURE__ */ new WeakMap();
+      var canSnapshot = (domItem) => typeof domItem.attributes.style === "undefined" || si_funciona_1.default.isObject(domItem.attributes.style);
+      var classNames = (className) => typeof className === "string" ? className.split(/\s+/).filter(Boolean) : [];
+      var describe = (domItem) => {
+        const snapshot = {
+          attributes: {},
+          classes: [],
+          style: {}
+        };
+        for (const name in domItem.attributes) {
+          const value = domItem.attributes[name];
+          if (name === "className") {
+            snapshot.classes = classNames(value);
+            continue;
+          }
+          if (name === "style") {
+            for (const property in value) {
+              snapshot.style[si_funciona_1.default.kabobCase(property)] = value[property];
+            }
+            continue;
+          }
+          snapshot.attributes[si_funciona_1.default.kabobCase(name)] = value;
+        }
+        return snapshot;
+      };
+      var recordApplied = (domItem) => {
+        if (!domItem.element || domItem.nodeValue !== null || !canSnapshot(domItem)) {
+          return;
+        }
+        snapshots.set(domItem.element, describe(domItem));
+      };
+      exports.recordApplied = recordApplied;
+      var forgetApplied = (element) => {
+        if (element) {
+          snapshots.delete(element);
+        }
+      };
+      exports.forgetApplied = forgetApplied;
+      var changesFromApplied = (domItem, propertyName) => {
+        const previous = domItem.element ? snapshots.get(domItem.element) : void 0;
+        if (!previous || domItem.nodeValue !== null || !canSnapshot(domItem)) {
+          return void 0;
+        }
+        const next = describe(domItem);
+        const changes = (0, createChangeList_1.default)();
+        const element = domItem.element;
+        for (const key in next.attributes) {
+          const live = LIVE_PROPERTIES.includes(key) && key in element;
+          const current = live ? element[key] : previous.attributes[key];
+          const differs = live && typeof current === "string" ? String(next.attributes[key] ?? "") !== current : next.attributes[key] !== current;
+          if (differs) {
+            changes.added[propertyName(key)] = next.attributes[key];
+          }
+        }
+        previous.classes.forEach((name, index) => {
+          if (!next.classes.includes(name)) {
+            changes.removed[`class.${index}`] = name;
+          }
+        });
+        next.classes.forEach((name, index) => {
+          if (!previous.classes.includes(name)) {
+            changes.added[`class.${index}`] = name;
+          }
+        });
+        for (const property in previous.style) {
+          if (!(property in next.style)) {
+            changes.removed[`style.${property}`] = previous.style[property];
+          }
+        }
+        for (const property in next.style) {
+          if (next.style[property] !== previous.style[property]) {
+            changes.added[`style.${property}`] = next.style[property];
+          }
+        }
+        return changes;
+      };
+      exports.changesFromApplied = changesFromApplied;
+    }
+  });
+
   // dist/sync/updateDomItem.js
   var require_updateDomItem = __commonJS({
     "dist/sync/updateDomItem.js"(exports) {
@@ -8453,6 +8551,7 @@ var treeloom = (() => {
       });
       var si_funciona_1 = __importDefault(require_main());
       var elementChanges_1 = __importDefault(require_elementChanges());
+      var appliedSnapshot_1 = require_appliedSnapshot();
       var updateDomItem = (config) => {
         if (!config.element) {
           return config;
@@ -8478,6 +8577,7 @@ var treeloom = (() => {
           }
           si_funciona_1.default.dotSet(config, dotKey, changes.added[dotKey]);
         }
+        (0, appliedSnapshot_1.forgetApplied)(config.element);
         return config;
       };
       exports.default = updateDomItem;
@@ -10539,6 +10639,7 @@ var treeloom = (() => {
       var si_funciona_1 = __importDefault(require_main());
       var elementHasAttribute_1 = __importDefault(require_elementHasAttribute());
       var createChangeList_1 = __importDefault(require_createChangeList());
+      var appliedSnapshot_1 = require_appliedSnapshot();
       var checkAttribute = (element) => (attr, key) => {
         if (typeof attr === "object") {
           const styles = attr;
@@ -10591,6 +10692,16 @@ var treeloom = (() => {
           }
           return changeList;
         }
+        if (!changeList.added.nodeName) {
+          const fromApplied = (0, appliedSnapshot_1.changesFromApplied)(domItem, (kabobKey) => {
+            const name = attributeName(domItem.attributes, kabobKey);
+            const element = domItem.element;
+            return element && name in element && name !== "form" ? name : kabobKey;
+          });
+          if (fromApplied) {
+            return fromApplied;
+          }
+        }
         const domItemAttributes = kabobCaseAttributes(domItem.attributes);
         const diffMap = si_funciona_1.default.mapObject(domItemAttributes, (attr, key) => checkAttribute(domItem.element)(attr, key));
         return si_funciona_1.default.reduceObject(diffMap, (changed, result, key) => {
@@ -10678,31 +10789,24 @@ var treeloom = (() => {
           return domItem;
         }
         const element = domItem.element;
-        const previousChildNodes = Array.from(element.childNodes);
-        domItem.children.map((child, index) => {
-          const existing = previousChildNodes.find((childNode2) => childNode2 === child.element);
-          let childNode = existing ?? child.element;
-          if (!childNode) {
-            childNode = (0, updateElement_1.default)(child).element;
-          }
-          if (!previousChildNodes[index]) {
-            element.appendChild(childNode);
-            return childNode;
-          }
-          if (childNode !== previousChildNodes[index]) {
-            element.replaceChild(childNode, previousChildNodes[index]);
-          }
+        const childNodes = domItem.children.map((child) => {
+          const childNode = child.element ?? (0, updateElement_1.default)(child).element;
+          child.element = childNode;
           return childNode;
-        }).forEach((childNode, index) => {
-          domItem.children[index].element = childNode;
         });
-        if (element.childNodes.length > domItem.children.length) {
-          const maxLength = domItem.children.length;
-          let nodeToRemove = element.childNodes[maxLength];
-          while (nodeToRemove) {
-            element.removeChild(nodeToRemove);
-            nodeToRemove = element.childNodes[maxLength];
+        const wanted = new Set(childNodes);
+        Array.from(element.childNodes).forEach((node) => {
+          if (!wanted.has(node)) {
+            element.removeChild(node);
           }
+        });
+        let following = null;
+        for (let index = childNodes.length - 1; index >= 0; index--) {
+          const childNode = childNodes[index];
+          if (childNode.parentNode !== element || childNode.nextSibling !== following) {
+            element.insertBefore(childNode, following);
+          }
+          following = childNode;
         }
         return domItem;
       };
@@ -10727,6 +10831,7 @@ var treeloom = (() => {
       var bindListeners_1 = __importDefault(require_bindListeners());
       var deactivateListeners_1 = __importDefault(require_deactivateListeners());
       var domItemChanges_1 = __importDefault(require_domItemChanges());
+      var appliedSnapshot_1 = require_appliedSnapshot();
       var si_funciona_1 = __importDefault(require_main());
       var generateElement_1 = __importDefault(require_generateElement());
       var updateChildNodes_1 = __importDefault(require_updateChildNodes());
@@ -10794,6 +10899,7 @@ var treeloom = (() => {
           }
           element.style.setProperty(si_funciona_1.default.kabobCase(si_funciona_1.default.strAfter(dotKey, ".")), value);
         }
+        (0, appliedSnapshot_1.recordApplied)(domItem);
         return (0, bindListeners_1.default)(domItem);
       };
       exports.default = updateElement;
@@ -10864,6 +10970,124 @@ var treeloom = (() => {
     }
   });
 
+  // dist/render/reconcile.js
+  var require_reconcile = __commonJS({
+    "dist/render/reconcile.js"(exports) {
+      "use strict";
+      init_process();
+      require_es_array_includes();
+      require_es_json_stringify();
+      var __importDefault = function(mod) {
+        return mod && mod.__esModule ? mod : {
+          "default": mod
+        };
+      };
+      Object.defineProperty(exports, "__esModule", {
+        value: true
+      });
+      var removeEventListener_1 = __importDefault(require_removeEventListener());
+      var itemIdIndex_1 = require_itemIdIndex();
+      var updateElements_1 = __importDefault(require_updateElements());
+      var STRUCTURE = /* @__PURE__ */ new Set(["element", "parentItem", "children", "eventListeners", "activeListeners"]);
+      var listenerKey = (listener) => typeof listener.listenerFunc === "string" ? JSON.stringify([listener.listenerFunc, listener.listenerArgs ?? null, listener.listenerOptions ?? null]) : null;
+      var 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
+              });
+            }
+          }
+        }
+      };
+      var 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];
+          }
+        }
+      };
+      var pairChildren = (existing, next) => {
+        const byId = /* @__PURE__ */ new Map();
+        existing.forEach((child) => {
+          if (typeof child.id === "number") {
+            byId.set(child.id, child);
+          }
+        });
+        const claimed = new Set(next.map((child) => typeof child.id === "number" ? byId.get(child.id) : void 0).filter(Boolean));
+        const taken = /* @__PURE__ */ new Set();
+        return next.map((nextChild, index) => {
+          const sameId = typeof nextChild.id === "number" ? byId.get(nextChild.id) : void 0;
+          const atPosition = existing[index] && !claimed.has(existing[index]) ? existing[index] : void 0;
+          const candidate = sameId ?? atPosition;
+          if (candidate && !taken.has(candidate) && candidate.nodeName === nextChild.nodeName) {
+            taken.add(candidate);
+            return candidate;
+          }
+          return void 0;
+        });
+      };
+      var 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) => {
+          ;
+          child.element?.remove?.();
+        });
+        existing.children = nextChildren.map((nextChild, index) => {
+          const child = pairs[index];
+          if (child) {
+            reconcileItem(child, nextChild);
+            return child;
+          }
+          nextChild.parentItem = existing;
+          return nextChild;
+        });
+        existing.children.forEach((child) => {
+          child.parentItem = existing;
+        });
+      };
+      var reconcile = (existing, next) => {
+        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.`);
+        }
+        (0, itemIdIndex_1.unregisterItemIds)(existing);
+        reconcileItem(existing, next);
+        (0, itemIdIndex_1.registerItemIds)(existing);
+        return (0, updateElements_1.default)(existing);
+      };
+      exports.default = reconcile;
+    }
+  });
+
   // dist/render/renderHtml.js
   var require_renderHtml = __commonJS({
     "dist/render/renderHtml.js"(exports) {
@@ -10912,12 +11136,14 @@ var treeloom = (() => {
         value: true
       });
       var generateElement_1 = __importDefault(require_generateElement());
+      var reconcile_1 = __importDefault(require_reconcile());
       var renderHtml_1 = __importDefault(require_renderHtml());
       var updateChildNodes_1 = __importDefault(require_updateChildNodes());
       var updateElement_1 = __importDefault(require_updateElement());
       var 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,