ngx-json-render 0.5.0 → 0.5.1

package/README.md

@@ -594,6 +594,18 @@ const bound = injectBoundProp<string>(() => ctx.props().value, () => ctx.binding
 
 Share one store across renderers (or drive it from your own state management) by passing a core `StateStore` — `createStateStore()`, or `createStoreAdapter()` over Redux/NgRx/etc. — via the `store` input. `createStoreSetState(store)` adapts a whole-state updater to fine-grained path writes.
 
+### What a state write re-renders
+
+A write reaches only the components whose resolved props actually changed. Writing `/user/name` re-runs the template of the text that shows it, not the rest of the tree. So `ctx.props()` and `ctx.element()` are the signals to read: a template that reads anything else, such as a mutable object or `Date.now()`, is no longer refreshed by unrelated writes.
+
+"Changed" is decided per prop value:
+
+- Primitives compare by value.
+- 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.
+
 ### 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

@@ -1091,6 +1091,32 @@ function repeatsItself(path) {
     }
     return false;
 }
+/**
+ * Whether two objects hold the same values under the same keys.
+ *
+ * `objectsByIdentity` decides what the same object or array reference means.
+ * The internal store copies every path it writes and never touches a snapshot
+ * it has handed out, so there the same reference is the same content. An
+ * external store may write into its snapshot in place, so there only
+ * primitives can be trusted to compare equal, and any object value counts as
+ * changed.
+ */
+function sameValues(a, b, objectsByIdentity) {
+    const keys = Object.keys(a);
+    if (keys.length !== Object.keys(b).length)
+        return false;
+    for (const key of keys) {
+        if (!Object.hasOwn(b, key))
+            return false;
+        const value = a[key];
+        if (!Object.is(value, b[key]))
+            return false;
+        if (!objectsByIdentity && typeof value === 'object' && value !== null) {
+            return false;
+        }
+    }
+    return true;
+}
 /** The chain from the root down to `path`, as a line a human can follow. */
 function describePath(path) {
     const keys = [];
@@ -1138,7 +1164,22 @@ class JrElement {
             return true;
         return evaluateVisibility(el.visible, this.resolutionCtx());
     }, ...(ngDevMode ? [{ debugName: "visible" }] : /* istanbul ignore next */ []));
-    /** The element with all prop expressions resolved. */
+    /**
+     * The element with all prop expressions resolved.
+     *
+     * 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.
+     *
+     * 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.
+     */
     resolvedElement = computed(() => {
         const el = this.rawElement();
         if (!el)
@@ -1147,14 +1188,24 @@ class JrElement {
             ...el,
             props: resolveElementProps(el.props ?? {}, this.resolutionCtx()),
         };
-    }, ...(ngDevMode ? [{ debugName: "resolvedElement" }] : /* istanbul ignore next */ []));
+    }, { ...(ngDevMode ? { debugName: "resolvedElement" } : /* istanbul ignore next */ {}), equal: (a, b) => {
+            if (a === b)
+                return true;
+            if (!a || !b || untracked(this.bindings))
+                return false;
+            const { props: aProps, ...aRest } = a;
+            const { props: bProps, ...bRest } = b;
+            // Everything but props is the spec element itself, never state.
+            return (sameValues(aRest, bRest, true) &&
+                sameValues(aProps, bProps, !untracked(this.root.store)));
+        } });
     /** Two-way binding paths ($bindState / $bindItem) by prop name. */
     bindings = computed(() => {
         const el = this.rawElement();
         return el
             ? resolveBindings(el.props ?? {}, this.resolutionCtx())
             : undefined;
-    }, ...(ngDevMode ? [{ debugName: "bindings" }] : /* istanbul ignore next */ []));
+    }, { ...(ngDevMode ? { debugName: "bindings" } : /* istanbul ignore next */ {}), equal: (a, b) => a === b || (!!a && !!b && sameValues(a, b, true)) });
     entry = computed(() => {
         const el = this.rawElement();
         return el ? this.root.resolveEntry(el.type) : undefined;