ngx-json-render 0.5.0 → 0.6.0

package/README.md

@@ -594,6 +594,24 @@ 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.
+
+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.
+
+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.
+
+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.
+
 ### 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

@@ -1,7 +1,7 @@
 import { NgComponentOutlet } from '@angular/common';
 import * as i0 from '@angular/core';
 import { signal, Injectable, inject, computed, untracked, effect, isDevMode, DestroyRef, InjectionToken, input, output, viewChild, afterNextRender, ChangeDetectionStrategy, Component, Injector, forwardRef } from '@angular/core';
-import { createStateStore, getByPath, runValidation, resolveAction, nextActionDispatchId, notifyActionDispatch, notifyActionSettle, executeAction, isDevtoolsActive, subscribeDevtoolsActive, evaluateVisibility, resolveElementProps, resolveBindings, resolveActionParam, autoFixSpec, validateSpec, createDirectiveRegistry, resolveRepeatStatePath, resolveRepeatItemStatePath, removeByPath, addByPath, setByPath, SPEC_DATA_PART_TYPE, nestedToFlat, createMixedStreamParser, defineSchema } from '@json-render/core';
+import { createStateStore, getByPath, runValidation, resolveAction, nextActionDispatchId, notifyActionDispatch, notifyActionSettle, executeAction, isDevtoolsActive, subscribeDevtoolsActive, resolveRepeatStatePath, evaluateVisibility, resolveElementProps, resolveBindings, resolveActionParam, autoFixSpec, validateSpec, createDirectiveRegistry, resolveRepeatItemStatePath, removeByPath, addByPath, setByPath, SPEC_DATA_PART_TYPE, nestedToFlat, createMixedStreamParser, defineSchema } from '@json-render/core';
 export { autoFixSpec, createStateStore, formatSpecIssues, nestedToFlat, validateSpec } from '@json-render/core';
 import { flattenToPointers } from '@json-render/core/store-utils';
 
@@ -967,6 +967,169 @@ function injectDevtoolsActive() {
     return active.asReadonly();
 }
 
+/**
+ * The state paths an element's expressions can read, or `null` when that
+ * can't be known from the spec.
+ *
+ * Worked out from the spec alone, before anything resolves, so that an element
+ * can depend on those paths rather than on the whole state. The answer may
+ * name more paths than a given resolution reads — both branches of a `$cond`,
+ * say — but never fewer: a path left out would be a write the element misses,
+ * and it would keep showing the old value with nothing in the console.
+ *
+ * `null` is the safe answer, and it is given whenever the spec holds something
+ * this reader does not model:
+ *
+ * - 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.
+ *
+ * The walk mirrors core's `resolvePropValue` and `evaluateVisibility`, in the
+ * same order, because the order decides which expression an object is.
+ */
+function collectStateReads(element, directives, repeatBasePath) {
+    const reader = new StateReader(directives, repeatBasePath);
+    const understood = reader.condition(element.visible) &&
+        Object.values(element.props ?? {}).every((value) => reader.value(value));
+    return understood ? reader.paths : null;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** Comparison operators a single condition may carry, as core reads them. */
+const COMPARISONS = ['eq', 'neq', 'gt', 'gte', 'lt', 'lte'];
+class StateReader {
+    directives;
+    repeatBasePath;
+    paths = new Set();
+    constructor(directives, repeatBasePath) {
+        this.directives = directives;
+        this.repeatBasePath = repeatBasePath;
+    }
+    /** A prop value. Returns false when it can read state this can't name. */
+    value(value) {
+        if (!isObject(value))
+            return true;
+        if (typeof value['$state'] === 'string')
+            return this.state(value['$state']);
+        if (typeof value['$item'] === 'string')
+            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;
+        if ('$cond' in value && '$then' in value && '$else' in value) {
+            return (this.condition(value['$cond']) &&
+                this.value(value['$then']) &&
+                this.value(value['$else']));
+        }
+        if (typeof value['$computed'] === 'string') {
+            // The function is handed its resolved arguments and nothing else.
+            const args = value['args'];
+            return (!args || Object.values(Object(args)).every((arg) => this.value(arg)));
+        }
+        if (typeof value['$template'] === 'string') {
+            return this.template(value['$template']);
+        }
+        if (Array.isArray(value))
+            return value.every((item) => this.value(item));
+        if (this.directives) {
+            for (const name of this.directives.keys()) {
+                if (name in value)
+                    return false;
+            }
+        }
+        for (const [key, entry] of Object.entries(value)) {
+            if (key.startsWith('$') || !this.value(entry))
+                return false;
+        }
+        return true;
+    }
+    /** A `visible` condition, or the condition of a `$cond`. */
+    condition(condition) {
+        if (condition === undefined || typeof condition === 'boolean')
+            return true;
+        if (Array.isArray(condition)) {
+            return condition.every((single) => this.singleCondition(single));
+        }
+        if (!isObject(condition))
+            return false;
+        for (const group of ['$and', '$or']) {
+            if (group in condition) {
+                const children = condition[group];
+                return (Array.isArray(children) &&
+                    children.every((child) => this.condition(child)));
+            }
+        }
+        return this.singleCondition(condition);
+    }
+    singleCondition(condition) {
+        if (!isObject(condition))
+            return false;
+        let understood;
+        if ('$index' in condition) {
+            understood = true;
+        }
+        else if ('$item' in condition) {
+            const item = condition['$item'];
+            understood = typeof item === 'string' && this.item(item);
+        }
+        else {
+            // Core reads `$state` here without checking it: anything but a string
+            // path reads the whole state.
+            const path = condition['$state'];
+            understood = typeof path === 'string' && this.state(path);
+        }
+        // Core looks only at the first operator present. Reading all of them is
+        // a superset of that.
+        for (const operator of COMPARISONS) {
+            const operand = condition[operator];
+            if (isObject(operand) && typeof operand['$state'] === 'string') {
+                understood = this.state(operand['$state']) && understood;
+            }
+        }
+        return understood;
+    }
+    template(template) {
+        for (const [, placeholder] of template.matchAll(/\$\{([^}]+)\}/g)) {
+            if (placeholder.startsWith('/')) {
+                if (!this.state(placeholder))
+                    return false;
+                continue;
+            }
+            // Core tries the repeat item first and falls back to a state path of
+            // the same name when the item has nothing there.
+            if (!this.item(placeholder) || !this.state(`/${placeholder}`)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    state(path) {
+        if (path === '' || path === '/')
+            return false;
+        this.paths.add(path);
+        return true;
+    }
+    /**
+     * 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
+     * external store edits it in place, so the path is what notices the edit.
+     */
+    item(itemPath) {
+        if (this.repeatBasePath === undefined)
+            return true;
+        const path = resolveRepeatStatePath({ $item: itemPath }, this.repeatBasePath);
+        return path !== undefined && this.state(path);
+    }
+}
+
 /**
  * The render context of the element currently being rendered.
  * Provided by the renderer for every catalog component instance.
@@ -992,6 +1155,15 @@ const REPEAT_SCOPE = new InjectionToken('ngx-json-render REPEAT_SCOPE');
  * `renderLimits.maxDepth`.
  */
 const RENDER_PATH = new InjectionToken('ngx-json-render RENDER_PATH');
+/**
+ * Whether an element that skipped a state write checks that it was right to:
+ * that resolving it against the whole state would not give anything else.
+ * On in dev mode, off in production.
+ *
+ * @internal Not part of the public API. The check calls `$computed`
+ * functions again, so tests that count those calls turn it off.
+ */
+const CHECK_SKIPPED_WRITES = new InjectionToken('ngx-json-render CHECK_SKIPPED_WRITES', { providedIn: 'root', factory: () => isDevMode() });
 /**
  * Inject the render context inside a catalog component.
  *
@@ -1091,6 +1263,75 @@ 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;
+}
+/**
+ * Whether two resolved values hold the same content, however they are built.
+ *
+ * For the dev-mode check on skipped writes, which compares a fresh resolution
+ * with an old one: a `$computed` function returns a new object every time,
+ * so identity says nothing there. What it can't see into — functions, a `Map`,
+ * a class instance — it counts as the same, because a check that warns about
+ * a correct element is worse than one that misses a case.
+ */
+function sameContent(a, b, seen = new Set()) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a === 'function' && typeof b === 'function')
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || !a || !b)
+        return false;
+    if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b))
+        return false;
+    if (a instanceof Date)
+        return a.getTime() === b.getTime();
+    const plain = Array.isArray(a) || Object.getPrototypeOf(a) === Object.prototype;
+    if (!plain || seen.has(a))
+        return true;
+    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) &&
+        sameContent(a[key], b[key], seen));
+}
+/** Element keys already warned about by the check on skipped writes. */
+const warnedSkippedWrites = new Set();
+const EMPTY_READS = new Set();
+function sameReads(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b || a.size !== b.size)
+        return false;
+    for (const path of a)
+        if (!b.has(path))
+            return false;
+    return true;
+}
 /** The chain from the root down to `path`, as a line a human can follow. */
 function describePath(path) {
     const keys = [];
@@ -1116,11 +1357,71 @@ class JrElement {
     devtoolsActive = injectDevtoolsActive();
     /** The raw (unresolved) element from the spec. */
     rawElement = computed(() => this.root.spec()?.elements?.[this.elementKey()], ...(ngDevMode ? [{ debugName: "rawElement" }] : /* istanbul ignore next */ []));
+    /**
+     * The state paths this element's expressions can read, or null when the
+     * spec doesn't say — see {@link collectStateReads} for when that is.
+     */
+    stateReads = computed(() => {
+        const el = this.rawElement();
+        if (!el)
+            return EMPTY_READS;
+        return collectStateReads(el, this.root.directiveRegistry(), this.repeatScope?.basePath());
+    }, { ...(ngDevMode ? { debugName: "stateReads" } : /* istanbul ignore next */ {}), equal: sameReads });
+    /**
+     * One signal per path this element reads, each holding the value at that
+     * path. They are rebuilt only when the paths change, and a cell that stays
+     * keeps its last value, so a path that didn't change is not a change.
+     *
+     * A cell compares like a resolved prop does: primitives by value, objects
+     * by reference with the internal store (which copies every path it writes)
+     * and never equal with an external `store`, which may write into its
+     * snapshot in place.
+     */
+    stateCells = (() => {
+        let cells = new Map();
+        return computed(() => {
+            const reads = this.stateReads();
+            if (reads === null)
+                return null;
+            const next = new Map();
+            for (const path of reads) {
+                next.set(path, cells.get(path) ??
+                    computed(() => getByPath(this.state.state(), path), {
+                        equal: (a, b) => Object.is(a, b) &&
+                            (typeof a !== 'object' ||
+                                a === null ||
+                                !untracked(this.root.store)),
+                    }));
+            }
+            cells = next;
+            return next;
+        });
+    })();
+    /**
+     * How many times {@link readableState} has taken a snapshot. The dev-mode
+     * check compares it between state writes to tell which ones were skipped.
+     */
+    snapshotsTaken = 0;
+    /**
+     * The state to resolve against: the whole snapshot, but only as fresh as
+     * the paths this element reads. A write elsewhere doesn't reach it, so the
+     * element doesn't resolve anything for it. An element whose reads are
+     * unknown follows every write, as all elements did before.
+     */
+    readableState = computed(() => {
+        this.snapshotsTaken++;
+        const cells = this.stateCells();
+        if (cells === null)
+            return this.state.state();
+        for (const cell of cells.values())
+            cell();
+        return untracked(this.state.state);
+    }, { ...(ngDevMode ? { debugName: "readableState" } : /* istanbul ignore next */ {}), equal: () => false });
     /** Prop/visibility resolution context (state + repeat scope + extensions). */
     resolutionCtx = computed(() => {
         const scope = this.repeatScope;
         return {
-            stateModel: this.state.state(),
+            stateModel: this.readableState(),
             ...(scope
                 ? {
                     repeatItem: scope.item(),
@@ -1138,7 +1439,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 +1463,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;
@@ -1237,6 +1563,25 @@ class JrElement {
                 console.warn(`[ngx-json-render] renderLimits.maxDepth (${untracked(this.root.limits)?.maxDepth}) reached at ${describePath(path)}. "${path.key}" and anything below it do not render.`);
             }
         });
+        // Dev mode: after a state write this element skipped, check that it was
+        // right to. Resolving against the whole state has to give what the element
+        // already shows; anything else is a read the spec analysis didn't name.
+        if (inject(CHECK_SKIPPED_WRITES)) {
+            let snapshotsSeen = -1;
+            effect(() => {
+                this.state.state();
+                const shown = this.resolvedElement();
+                const shownVisible = this.visible();
+                const reads = this.stateReads();
+                untracked(() => {
+                    const skipped = this.snapshotsTaken === snapshotsSeen;
+                    snapshotsSeen = this.snapshotsTaken;
+                    if (skipped && shown && reads !== null) {
+                        this.checkSkippedWrite(shown, shownVisible, reads);
+                    }
+                });
+            });
+        }
         // Warn (once per type) about unknown component types.
         const warnedTypes = new Set();
         effect(() => {
@@ -1298,6 +1643,37 @@ class JrElement {
             onCleanup(unsubscribe);
         });
     }
+    /**
+     * Resolve this element against the whole current state and warn, once per
+     * element key, when that differs from what it shows after skipping a write.
+     *
+     * It only reports, and leaves the element as it is: correcting it here would
+     * make dev mode render what production doesn't.
+     */
+    checkSkippedWrite(shown, shownVisible, reads) {
+        const key = this.elementKey();
+        const el = this.rawElement();
+        if (!el || warnedSkippedWrites.has(key))
+            return;
+        const ctx = this.liveResolutionCtx();
+        let props;
+        let visible;
+        try {
+            props = resolveElementProps(el.props ?? {}, ctx);
+            visible = el.visible === undefined || evaluateVisibility(el.visible, ctx);
+        }
+        catch {
+            return;
+        }
+        const differs = Object.keys({ ...props, ...shown.props }).filter((prop) => !sameContent(props[prop], shown.props[prop]));
+        if (visible !== shownVisible)
+            differs.push('visible');
+        if (differs.length === 0)
+            return;
+        warnedSkippedWrites.add(key);
+        const paths = reads.size > 0 ? [...reads].join(', ') : 'no state paths';
+        console.warn(`[ngx-json-render] "${key}" did not resolve again after a state write, but resolving it now changes ${differs.join(', ')}. It resolves only when a state path it reads changes, and it reads ${paths}. Either a $computed function in it depends on something besides its args, or the renderer missed a read — please report the spec at https://github.com/shteynu/ngx-json-render/issues. This check runs in dev mode only.`);
+    }
     /**
      * Resolution context with a live state snapshot, so `$state` references in
      * later actions of a chain see mutations from earlier ones.