@zubra/runtime 5.8.0 → 5.9.1

package/README.md

@@ -46,7 +46,7 @@ including values, recompute counts, the order watchers are notified, the order `
 
 ### Deliberate differences from the reference polyfill
 
-Each one only affects programs that break a rule the proposal states, so correct programs
+The first three only affect programs that break a rule the proposal states, so correct programs
 behave the same on both. All are tested in `test/signal.test.js`.
 
 1. **Reads and writes inside `watched`/`unwatched` hooks throw.** The proposal says hooks run
@@ -57,6 +57,12 @@ behave the same on both. All are tested in `test/signal.test.js`.
    keeps throwing it after the notification is over.
 3. **`new Signal.Computed(x)` requires a function** (TypeError), instead of failing on first read.
 
+One difference is visible to correct programs: **`Watcher.getPending()` isn't in watch order.**
+The watcher keeps the computeds it watches as they're marked dirty, instead of scanning everything
+it watches, so `getPending()` costs O(pending), not O(watched), and lists them roughly in the order
+they were marked. The proposal doesn't state an order (the reference's is the watch order); the
+computeds, and how many times each is listed, are the same. Also tested in `test/signal.test.js`.
+
 ## Effects
 
 ```js

package/dist/production/effect.js

@@ -9,6 +9,11 @@
 //   scope(fn)         an ownership root: effects created inside belong to it
 //   flush() / tick()  apply pending re-runs now / await them
 //
+// Disposal: effect()'s dispose function and every scope are also disposables
+// (`[Symbol.dispose]`), so `using` and `DisposableStack` can own them where the browser has
+// Explicit Resource Management. Nothing here depends on it. Pausing is not disposal: a paused
+// scope resumes; only dispose() (or Symbol.dispose) ends one.
+//
 // Ownership: an effect created while another effect (or a scope) is running belongs to it. When
 // the owner re-runs or is disposed, everything it owns is disposed first, so nothing outlives
 // the code that created it.
@@ -27,7 +32,13 @@ let owner = null;          // the Effect or Scope currently running
 let nextId = 0;
 let scheduled = null;      // promise for the pending microtask flush
 let flushing = false;
-const effectOf = new WeakMap();
+const EFFECT = Symbol('effect');
+
+/**
+ * `Symbol.dispose`, or, where the engine doesn't have it yet, the symbol TypeScript's downlevel
+ * `using` and the polyfills look up (`Symbol.for('Symbol.dispose')`).
+ */
+export const DISPOSE = Symbol.dispose ?? Symbol.for('Symbol.dispose');
 
 
 const watcher = new Signal.subtle.Watcher(() => {
@@ -74,15 +85,18 @@ function report(error) {
 class Owner {
   constructor(parent) {
     this.parent = parent;
-    this.children = new Set();
+    this.children = null;     // created on first child: most effects have none
     this.disposed = false;
     this.paused = false;
-    parent?.children.add(this);
+    if (parent) (parent.children ??= new Set()).add(this);
   }
 
   disposeChildren() {
+    const children = this.children;
+    if (children === null || children.size === 0) return;
+    this.children = null;
     batch(() => {
-      for (const child of [...this.children]) child.dispose();
+      for (const child of children) { child.parent = null; child.dispose(); }
     });
   }
 
@@ -90,13 +104,17 @@ class Owner {
     if (this.disposed) return;
     this.disposed = true;
     this.disposeChildren();
-    this.parent?.children.delete(this);
+    this.parent?.children?.delete(this);
+  }
+
+  [DISPOSE]() {
+    this.dispose();
   }
 
   pause() {
     if (this.paused || this.disposed) return;
     this.paused = true;
-    batch(() => {
+    if (this.children) batch(() => {
       for (const child of [...this.children]) child.pause();
     });
   }
@@ -106,7 +124,7 @@ class Owner {
     this.paused = false;
     // Children may be replaced while their parent resumes, so iterate a snapshot and skip
     // anything that was disposed along the way.
-    for (const child of [...this.children]) if (!child.disposed) child.resume();
+    if (this.children) for (const child of [...this.children]) if (!child.disposed) child.resume();
   }
 }
 
@@ -127,7 +145,7 @@ class Effect extends Owner {
         owner = previous;
       }
     });
-    effectOf.set(this.computed, this);
+    this.computed[EFFECT] = this;
     watcher.watch(this.computed);
   }
 
@@ -162,7 +180,7 @@ class Effect extends Owner {
     this.paused = false;
     watchAgain(this.computed);
     try { this.run(); } catch (error) { report(error); }
-    for (const child of [...this.children]) if (!child.disposed) child.resume();
+    if (this.children) for (const child of [...this.children]) if (!child.disposed) child.resume();
   }
 }
 
@@ -183,7 +201,9 @@ class Scope extends Owner {
 export function effect(fn) {
   const e = new Effect(fn, owner);
   e.run(); // if this throws, the effect stays registered and re-runs when its dependencies change
-  return () => e.dispose();
+  const dispose = () => e.dispose();
+  dispose[DISPOSE] = dispose;
+  return dispose;
 }
 
 /**
@@ -222,7 +242,7 @@ export function flush() {
         report(new Error('zubra: effects keep re-triggering each other; stopped after 100 rounds'));
         return;
       }
-      const effects = pending.map((computed) => effectOf.get(computed)).sort((a, b) => a.id - b.id);
+      const effects = pending.map((computed) => computed[EFFECT]).sort((a, b) => a.id - b.id);
       for (const e of effects) {
         if (e.disposed || e.paused) continue;
         try { e.run(); } catch (error) { report(error); }

package/dist/production/element.js

@@ -196,12 +196,13 @@ export function emit(name) {
 
 /**
  * An id unique to this element and call, for `id`/`for`/`aria-*` attributes. Stable for the
- * element's life; based on the host's own `id` when it has one, so it can be made to match
- * server-rendered markup.
+ * element's life. Based on the host's own `id` when it has one, else on the base the server
+ * rendered it with (`data-zb-id`), so the ids in server-rendered markup stay as they are.
  */
 export function id() {
   const component = hooks('id');
-  const base = component.host.id || `${component.host.localName}-${component.instance}`;
+  const host = component.host;
+  const base = host.id || host.getAttribute('data-zb-id') || `${host.localName}-${component.instance}`;
   return `${base}-${++component.ids}`;
 }
 
@@ -335,7 +336,18 @@ export function provide(context, value) {
  * key as `context`.
  */
 export function inject(context, fallback = context?.defaultValue) {
-  const host = hooks('inject').host;
+  const component = hooks('inject');
+  const host = component.host;
+  // The value the server rendered with (`data-zb-inject`, by call number) is where it starts,
+  // so hydrating doesn't show the default until the provider answers.
+  const number = (component.injects = (component.injects ?? 0) + 1);
+  const rendered = host.getAttribute('data-zb-inject');
+  if (rendered) {
+    try {
+      const values = JSON.parse(rendered);
+      if (Object.hasOwn(values, number)) fallback = values[number];
+    } catch { /* not ours: keep the default */ }
+  }
   const value = new Signal.State(fallback);
   let unsubscribe = null;
   let answered = false;
@@ -528,6 +540,25 @@ function blueprint(source, parent = null) {
   return content;
 }
 
+// For a blueprint with no custom elements: a copy owned by this document, made once, which rows
+// clone. Its clones need no adopting when they're inserted, and nothing in it has to upgrade.
+const imported = new WeakMap();
+const upgrades = (content) =>
+  [...content.querySelectorAll('*')].some((element) => element.localName.includes('-') || element.hasAttribute('is'));
+
+/** A fresh copy of `block`'s template for `parent`, ready for its parts to be found and bound. */
+function freshCopy(block, parent) {
+  const content = blueprint(block, parent);
+  let copy = imported.get(content);
+  if (copy === undefined) {
+    // importNode: custom elements inside upgrade now, so their properties exist before parts
+    // bind (a plain clone stays in the template's inert document).
+    copy = upgrades(content) ? null : document.importNode(content, true);
+    imported.set(content, copy);
+  }
+  return copy === null ? document.importNode(content, true) : copy.cloneNode(true);
+}
+
 function clearBetween(open, close) {
   while (open.nextSibling && open.nextSibling !== close) open.nextSibling.remove();
 }
@@ -546,8 +577,27 @@ function departBetween(open, close, motion) {
 }
 
 /** Remove everything between `open` and `close` in one operation. */
+const nativeTextContent = typeof Node !== 'undefined' ? Object.getOwnPropertyDescriptor(Node.prototype, 'textContent').set : undefined;
 function deleteBetween(open, close) {
   if (open.nextSibling === close) return;
+  // The region is everything its parent holds but blank text (a list's own <tbody> or <ul>):
+  // emptying the parent and putting the markers and that text back is several times cheaper than
+  // deleting a range's contents.
+  const parent = open.parentNode;
+  const before = [];
+  const after = [];
+  const blank = (node) => node.nodeType === TEXT && node.data.trim() === '';
+  let edge = open.previousSibling;
+  while (edge && blank(edge) && before.length < 4) { before.unshift(edge); edge = edge.previousSibling; }
+  if (parent && !edge) {
+    edge = close.nextSibling;
+    while (edge && blank(edge) && after.length < 4) { after.push(edge); edge = edge.nextSibling; }
+    if (!edge) {
+      nativeTextContent.call(parent, '');
+      for (const node of [...before, open, close, ...after]) Node.prototype.insertBefore.call(parent, node, null);
+      return;
+    }
+  }
   const range = document.createRange();
   range.setStartAfter(open);
   range.setEndBefore(close);
@@ -569,10 +619,8 @@ function mountBlock(block, args, open, close, hydrating, context) {
   clearBetween(open, close);
   // Find and bind the parts in the fragment, then insert it: child components inside see
   // their props from the start, and can't move slotted nodes before they're found.
-  // importNode, not cloneNode: defined custom elements upgrade now, so their properties exist
-  // before parts bind (a clone stays in the template's inert document).
   const parent = parentOf(close);
-  const fragment = document.importNode(blueprint(block, parent), true);
+  const fragment = freshCopy(block, parent);
   fragmentParents.set(fragment, parent);
   const fresh = locate(childRange(fragment), parts);
   parts.forEach((part, index) => bind(part, fresh[index], false, context));
@@ -700,7 +748,12 @@ function bind(part, node, hydrating, context) {
   if (part.text) {
     effect(() => {
       const text = part.text();
-      if (node.textContent !== text) node.textContent = text;
+      // A lone Text child is compared and written in place (`.data`): reading `textContent`
+      // walks the subtree, and setting it replaces the Text node.
+      const child = node.firstChild;
+      if (child !== null && child === node.lastChild && child.nodeType === TEXT) {
+        if (child.data !== text) child.data = text;
+      } else if (node.textContent !== text) node.textContent = text;
     });
   } else if (part.anchor) {
     effect(() => {
@@ -1258,19 +1311,27 @@ function bindEach(part, open, hydrating, context) {
   const rowsOwner = scope();
   let rows = [];
 
+  // A row is the nodes from `open` to `close`. Rows the server rendered keep the markers it put
+  // around them. A row made here is its block's own nodes, from first to last, with no markers:
+  // what a block's nodes are at the top never changes after it's bound (a region inside one keeps
+  // its own markers), so the first and last stay the row's ends. Only an empty block needs one.
   const createRow = (value, index, key, rowOpen, rowClose, hydrateRow) => {
-    if (!rowOpen) {
-      // A new row is assembled in a fragment, then placed.
-      rowOpen = document.createComment('[');
-      rowClose = document.createComment(']');
-      const fragment = new DocumentFragment();
-      fragmentParents.set(fragment, parentOf(open));
-      fragment.append(rowOpen, rowClose);
-    }
     const item = new Signal.State(value);
     const position = new Signal.State(index);
-    const owner = rowsOwner.run(() => scope(() => mountBlock(part.block, [item, position], rowOpen, rowClose, hydrateRow, context)));
-    return { key, item, position, open: rowOpen, close: rowClose, owner };
+    if (rowOpen) {
+      const owner = rowsOwner.run(() => scope(() => mountBlock(part.block, [item, position], rowOpen, rowClose, hydrateRow, context)));
+      return { key, item, position, open: rowOpen, close: rowClose, owner };
+    }
+    const parent = parentOf(open);
+    const fragment = freshCopy(part.block, parent);
+    fragmentParents.set(fragment, parent);
+    const owner = rowsOwner.run(() => scope(() => {
+      const parts = part.block.parts(item, position);
+      const nodes = locate(childRange(fragment), parts);
+      parts.forEach((each, at) => bind(each, nodes[at], false, context));
+    }));
+    if (!fragment.firstChild) fragment.append(document.createComment(''));
+    return { key, item, position, open: fragment.firstChild, close: fragment.lastChild, owner };
   };
   const nodesOf = (row) => {
     const nodes = [];
@@ -1374,6 +1435,7 @@ function bindEach(part, open, hydrating, context) {
       }
       // `animate`: the rows that stay glide from where they were (@zubra/runtime/motion).
       const reorder = () => {
+        const was = new Map(rows.map((row, index) => [row, index]));
         const next = list.map((value, index) => {
           const row = byKey.get(keys[index]);
           if (!row) return createRow(value, index, keys[index]);
@@ -1383,17 +1445,14 @@ function bindEach(part, open, hydrating, context) {
           return row;
         });
         batch(() => { for (const row of byKey.values()) removeRow(row); });
-        // Text between rows, and rows on their way out, aren't rows to place against.
-        const skip = (node) => node && (node.nodeType === TEXT || part.animate?.isLeaving(node));
-        let at = open.nextSibling;
-        while (skip(at)) at = at.nextSibling;
-        for (const row of next) {
-          if (row.open === at) {
-            at = row.close.nextSibling;
-            while (skip(at)) at = at.nextSibling;
-            continue;
-          }
-          placeRow(row, at ?? close);
+        // The longest run of rows still in their old order stays put; every other row (and every
+        // new one) goes before the row after it, from the end. A swap moves two rows, not the
+        // rows between them.
+        const stay = inOrder(next.map((row) => was.get(row) ?? -1));
+        let before = close;
+        for (let index = next.length - 1; index >= 0; index--) {
+          if (!stay.has(index)) placeRow(next[index], before);
+          before = next[index].open;
         }
         rows = next;
       };
@@ -1403,6 +1462,31 @@ function bindEach(part, open, hydrating, context) {
   });
 }
 
+/**
+ * The indexes of a longest strictly increasing run in `sequence` (negative entries never count):
+ * for a keyed list, which rows are already in order and needn't move. O(n log n).
+ */
+function inOrder(sequence) {
+  const tails = []; // tails[length - 1]: the index ending the best run of that length so far
+  const previous = new Array(sequence.length);
+  for (let index = 0; index < sequence.length; index++) {
+    const value = sequence[index];
+    if (value < 0) continue;
+    let low = 0;
+    let high = tails.length;
+    while (low < high) {
+      const middle = (low + high) >> 1;
+      if (sequence[tails[middle]] < value) low = middle + 1;
+      else high = middle;
+    }
+    previous[index] = low > 0 ? tails[low - 1] : -1;
+    tails[low] = index;
+  }
+  const kept = new Set();
+  for (let index = tails.length ? tails[tails.length - 1] : -1; index >= 0; index = previous[index]) kept.add(index);
+  return kept;
+}
+
 const hasContent = (root) =>
   [...root.childNodes].some((node) => node.nodeType !== TEXT || node.data.trim() !== '');
 

package/dist/production/resource.js

@@ -9,8 +9,10 @@
 // `AbortSignal` it was given, and so does the element's removal; a result that arrives after a
 // newer run started is dropped, so the value is always the latest request's. While a new run is
 // pending the previous value stays (`loading` is true), so the UI doesn't flash empty.
+// `dispose()` (or `using`, through `Symbol.dispose`) stops it early: the run in flight is
+// aborted and nothing re-runs it. Otherwise it lives as long as the scope that created it.
 import { Signal } from './signal.js';
-import { effect } from './effect.js';
+import { DISPOSE, effect } from './effect.js';
 
 const { untrack } = Signal.subtle;
 
@@ -30,7 +32,7 @@ export function resource(fetcher, { initial } = {}) {
   const version = new Signal.State(0);
   let current = null; // the latest run's promise
 
-  effect(() => {
+  const stop = effect(() => {
     version.get();
     const controller = new AbortController();
     let result;
@@ -72,5 +74,7 @@ export function resource(fetcher, { initial } = {}) {
     get loading() { return status.get() === 'pending'; },
     refresh() { version.set(untrack(() => version.get()) + 1); },
     then(resolve, reject) { return current.then(resolve, reject); },
+    dispose: stop,
+    [DISPOSE]: stop,
   };
 }