ngx-json-render 0.7.7 → 0.7.8

package/README.md

@@ -686,14 +686,18 @@ A write reaches only the components whose resolved props actually changed. Writi
 - Objects and arrays compare by reference with the built-in store, which copies every path it writes.
 - With an external `store`, objects and arrays always count as changed, because such a store may write into its snapshot in place.
 
-Elements with a `$bindState` or `$bindItem` prop still re-run on every write. Their DOM can hold the user's input before state does, and the note below depends on them getting the chance to put it right.
+Elements with a `$bindState` or `$bindItem` prop also re-run on every write that touches their bound path — the path itself, a container above it, or a path inside it — even when the value comes back to what it was. Their DOM can hold the user's input before state does, and the note below depends on them getting the chance to put it right. Writes anywhere else reach them like any other element.
 
-Before any of that, a write only makes the elements that can read its path resolve their props at all. The renderer works the paths out from each element's spec — `$state`, `$item`, `$template` placeholders, both branches of a `$cond`, `$computed` arguments and `visible` conditions — so a write to `/user/name` leaves the todo list alone, and its `$computed` functions don't run. A `$computed` function should therefore depend only on its arguments: one that also reads the clock or a variable outside the spec is no longer called again by unrelated writes.
+Before any of that, a write only makes the elements that can read its path resolve their props at all. The renderer works the paths out from each element's spec — `$state`, `$item`, `$template` placeholders, both branches of a `$cond`, `$computed` arguments, `visible` conditions, and the paths `$bindState` and `$bindItem` write back to — so a write to `/user/name` leaves the todo list alone, and its `$computed` functions don't run. A `$computed` function should therefore depend only on its arguments: one that also reads the clock or a variable outside the spec is no longer called again by unrelated writes.
 
-Some elements keep resolving on every write, because their reads can't be known from the spec: those using a directive (its `resolve` gets the whole state), those with a two-way binding, and any prop with a `$`-key the renderer doesn't recognise.
+Some elements keep resolving on every write, because their reads can't be known from the spec: those using a directive (its `resolve` gets the whole state) and any prop with a `$`-key the renderer doesn't recognise.
 
 In dev mode each element that skipped a write resolves anyway, against the whole state, and the console warns once if that gives anything other than what it shows. The warning means a `$computed` function reads more than its arguments, or the renderer missed a read, which is a bug worth reporting. The element itself is left as production would leave it. The check calls the element's `$computed` functions again, so in dev mode they still run on every write.
 
+### What a new spec re-renders
+
+A spec element is compared by content, not by identity. A streamed patch shares every element it did not touch, but a spec can also arrive as all-new objects — a whole-spec part, a host that fetches the spec again, `buildSpecFromParts` replaying a message — and then only the elements whose content changed resolve and re-render. The same goes for `spec.state` in uncontrolled mode: only leaves whose content changed are written to the store, so handing over the same spec again keeps what the user has changed since, including edits inside an array.
+
 ### A note on inputs
 
 If a catalog component renders `<input [value]="ctx.props().value">`, remember that one-way bindings do not re-assert the DOM when the bound value returns to its previously applied value while the user typed in between (e.g. `pushState` + `clearStatePath`). Sync imperatively instead — see `InputComponent` in the demo app for the pattern.

package/fesm2022/ngx-json-render.mjs

@@ -92,6 +92,37 @@ function isPlainObject(value) {
         Object.getPrototypeOf(value) === Object.prototype);
 }
 
+/**
+ * Whether two values hold the same JSON content.
+ *
+ * For telling a value that arrived as a new object from one that changed — a
+ * spec element, or a leaf of `spec.state`, when the host hands over a spec
+ * built from fresh objects. Plain objects and arrays are compared by what
+ * they hold; anything else only by identity, which data parsed from JSON
+ * never needs. A container reached twice on the way down counts as
+ * different: JSON cannot refer to itself, and treating such a value as
+ * changed is what the renderer did before it compared anything.
+ */
+function sameJson(a, b, seen = new Set()) {
+    if (Object.is(a, b))
+        return true;
+    if (!isPlainContainer(a) || !isPlainContainer(b))
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b) || seen.has(a))
+        return false;
+    seen.add(a);
+    const keys = Object.keys(a);
+    if (keys.length !== Object.keys(b).length)
+        return false;
+    return keys.every((key) => Object.hasOwn(b, key) && sameJson(a[key], b[key], seen));
+}
+function isPlainContainer(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return (Array.isArray(value) || prototype === Object.prototype || prototype === null);
+}
+
 /**
  * The state store of a `<json-render>` subtree.
  *
@@ -151,7 +182,10 @@ class JsonRenderStateService {
         });
         // Uncontrolled mode: when the (resolved) initial state changes — e.g.
         // `spec.state` grows while streaming — diff it against the previous
-        // initial state and apply only the changed leaves to the store.
+        // initial state and apply only the changed leaves to the store. Leaves
+        // compare by content: arrays are leaves, and a spec handed over again as
+        // new objects would otherwise write every array back, over whatever the
+        // user has since changed inside it.
         let prevFlat = {};
         effect(() => {
             if (this.root.store())
@@ -166,7 +200,7 @@ class JsonRenderStateService {
             ]);
             const updates = {};
             for (const key of allKeys) {
-                if (prevFlat[key] !== nextFlat[key]) {
+                if (!sameJson(prevFlat[key], nextFlat[key])) {
                     updates[key] = key in nextFlat ? nextFlat[key] : undefined;
                 }
             }
@@ -1085,8 +1119,6 @@ function injectDevtoolsActive() {
  *
  * - a registered directive, whose `resolve` receives the whole context and may
  *   read any path at all;
- * - a `$bindState` or `$bindItem` prop — the renderer keeps two-way bound
- *   elements resolving on every write, see `JrElement.resolvedElement`;
  * - a `$`-prefixed key it doesn't recognise, which is what an expression added
  *   to core after this was written would look like;
  * - a read of the whole state (`''` or `'/'`), and a condition it can't parse.
@@ -1123,10 +1155,13 @@ class StateReader {
             return this.item(value['$item']);
         if ('$index' in value && value['$index'] === true)
             return true;
-        if (typeof value['$bindState'] === 'string')
-            return false;
-        if (typeof value['$bindItem'] === 'string')
-            return false;
+        // A two-way binding reads the path it writes back to.
+        if (typeof value['$bindState'] === 'string') {
+            return this.state(value['$bindState']);
+        }
+        if (typeof value['$bindItem'] === 'string') {
+            return this.boundItem(value['$bindItem']);
+        }
         if ('$cond' in value && '$then' in value && '$else' in value) {
             return (this.condition(value['$cond']) &&
                 this.value(value['$then']) &&
@@ -1220,6 +1255,17 @@ class StateReader {
         this.paths.add(path);
         return true;
     }
+    /**
+     * A `$bindItem`, joined the way core joins it — which is not quite how it
+     * joins an `$item` read. Outside a repeat it resolves to nothing.
+     */
+    boundItem(itemPath) {
+        if (this.repeatBasePath === undefined)
+            return true;
+        return this.state(itemPath === ''
+            ? this.repeatBasePath
+            : `${this.repeatBasePath}/${itemPath}`);
+    }
     /**
      * A read of the repeat item, as the state path it sits at. The item value
      * reaches the element on its own, but only as the same object when an
@@ -1422,6 +1468,15 @@ function sameContent(a, b, seen = new Set()) {
     return keys.every((key) => Object.hasOwn(b, key) &&
         sameContent(a[key], b[key], seen));
 }
+/**
+ * Whether a state write at `written` can change the value at `bound`: the
+ * same path, a container above it, or a path inside it.
+ */
+function touches(written, bound) {
+    return (written === bound ||
+        bound.startsWith(`${written}/`) ||
+        written.startsWith(`${bound}/`));
+}
 /** Element keys already warned about by the check on skipped writes. */
 const warnedSkippedWrites = new Set();
 const EMPTY_READS = new Set();
@@ -1458,8 +1513,17 @@ class JrElement {
     repeatScope = inject(REPEAT_SCOPE, { optional: true });
     parentPath = inject(RENDER_PATH, { optional: true });
     devtoolsActive = injectDevtoolsActive();
-    /** The raw (unresolved) element from the spec. */
-    rawElement = computed(() => this.root.spec()?.elements?.[this.elementKey()], ...(ngDevMode ? [{ debugName: "rawElement" }] : /* istanbul ignore next */ []));
+    /**
+     * The raw (unresolved) element from the spec.
+     *
+     * Compared by content, not identity. A streamed patch shares every element
+     * it did not touch, and the identity check settles those at once; but a
+     * spec can also arrive as all-new objects — a whole-spec part, a host that
+     * fetches it again, `buildSpecFromParts` replaying a message — and then an
+     * element whose content is unchanged would resolve, and every container
+     * with a fresh `children` array re-render, for nothing.
+     */
+    rawElement = computed(() => this.root.spec()?.elements?.[this.elementKey()], { ...(ngDevMode ? { debugName: "rawElement" } : /* istanbul ignore next */ {}), equal: (a, b) => sameJson(a, b) });
     /**
      * The state paths this element's expressions can read, or null when the
      * spec doesn't say — see {@link collectStateReads} for when that is.
@@ -1543,40 +1607,55 @@ class JrElement {
         return evaluateVisibility(el.visible, this.resolutionCtx());
     }, ...(ngDevMode ? [{ debugName: "visible" }] : /* istanbul ignore next */ []));
     /**
-     * The element with all prop expressions resolved.
+     * How many state writes have touched a path this element is two-way bound
+     * to. See {@link resolution} for why those writes count on their own.
+     */
+    boundWrites = signal(0, ...(ngDevMode ? [{ debugName: "boundWrites" }] : /* istanbul ignore next */ []));
+    /**
+     * The element with all prop expressions resolved, and the bound writes it
+     * was resolved after.
      *
-     * Resolving builds a new props object on every state write, whatever the
-     * write touched. Handing that on as a change would re-run every catalog
-     * template in the tree for one keystroke, so a result that holds the same
-     * values as the last one counts as unchanged and keeps the old object.
+     * Resolving builds a new props object every time, so a result that holds
+     * the same values as the last one counts as unchanged and keeps the old
+     * object; otherwise one keystroke would re-run every catalog template that
+     * happened to resolve.
      *
-     * Two-way bound elements are the exception, and keep treating every
-     * resolution as a change. Their component writes the user's input into the
-     * DOM before it reaches state, so the DOM can differ from a prop whose
-     * value never did: typing and a `clearStatePath` in the same turn take
-     * the prop from '' through 'milk' back to '' with nobody reading 'milk'.
-     * The README tells catalog authors to sync such inputs with an effect on
-     * props, and that effect only gets to put the DOM right if it runs.
+     * A write to a path the element is bound to always counts, though. Its
+     * component writes the user's input into the DOM before it reaches state,
+     * so the DOM can differ from a prop whose value never did: typing and a
+     * `clearStatePath` in the same turn take the prop from '' through 'milk'
+     * back to '' with nobody reading 'milk'. The README tells catalog authors
+     * to sync such inputs with an effect on props, and that effect only gets to
+     * put the DOM right if it runs. Writes anywhere else compare by value, like
+     * any element's.
      */
-    resolvedElement = computed(() => {
+    resolution = computed(() => {
+        const boundWrites = this.boundWrites();
         const el = this.rawElement();
         if (!el)
-            return undefined;
+            return { element: undefined, boundWrites };
         return {
-            ...el,
-            props: resolveElementProps(el.props ?? {}, this.resolutionCtx()),
+            element: {
+                ...el,
+                props: resolveElementProps(el.props ?? {}, this.resolutionCtx()),
+            },
+            boundWrites,
         };
-    }, { ...(ngDevMode ? { debugName: "resolvedElement" } : /* istanbul ignore next */ {}), equal: (a, b) => {
-            if (a === b)
+    }, { ...(ngDevMode ? { debugName: "resolution" } : /* istanbul ignore next */ {}), equal: (a, b) => {
+            if (a.boundWrites !== b.boundWrites)
+                return false;
+            if (a.element === b.element)
                 return true;
-            if (!a || !b || untracked(this.bindings))
+            if (!a.element || !b.element)
                 return false;
-            const { props: aProps, ...aRest } = a;
-            const { props: bProps, ...bRest } = b;
+            const { props: aProps, ...aRest } = a.element;
+            const { props: bProps, ...bRest } = b.element;
             // Everything but props is the spec element itself, never state.
             return (sameValues(aRest, bRest, true) &&
                 sameValues(aProps, bProps, !untracked(this.root.store)));
         } });
+    /** The element with all prop expressions resolved. */
+    resolvedElement = computed(() => this.resolution().element, ...(ngDevMode ? [{ debugName: "resolvedElement" }] : /* istanbul ignore next */ []));
     /** Two-way binding paths ($bindState / $bindItem) by prop name. */
     bindings = computed(() => {
         const el = this.rawElement();
@@ -1687,6 +1766,21 @@ class JrElement {
                 });
             });
         }
+        // Count the writes that touch a path this element is bound to. Only an
+        // element with bindings listens, and it reads them when a write arrives,
+        // so a binding that moves (a repeat item that shifts) is followed without
+        // subscribing again.
+        effect((onCleanup) => {
+            if (!this.bindings())
+                return;
+            const unsubscribe = this.state.subscribeChanges((changes) => {
+                const paths = Object.values(untracked(this.bindings) ?? {});
+                if (changes.some((change) => paths.some((path) => touches(change.path, path)))) {
+                    this.boundWrites.update((count) => count + 1);
+                }
+            });
+            onCleanup(unsubscribe);
+        });
         // Warn (once per type) about unknown component types.
         const warnedTypes = new Set();
         effect(() => {