ngx-json-render 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-json-render",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Angular renderer for json-render — stream AI-generated JSON specs into real Angular components with signals.",
   "keywords": [
     "angular",

package/types/ngx-json-render.d.ts

@@ -601,10 +601,53 @@ declare class JrElement {
     private readonly devtoolsActive;
     /** The raw (unresolved) element from the spec. */
     readonly rawElement: Signal<UIElement<string, Record<string, unknown>> | undefined>;
+    /**
+     * The state paths this element's expressions can read, or null when the
+     * spec doesn't say — see {@link collectStateReads} for when that is.
+     */
+    private readonly stateReads;
+    /**
+     * 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.
+     */
+    private readonly stateCells;
+    /**
+     * How many times {@link readableState} has taken a snapshot. The dev-mode
+     * check compares it between state writes to tell which ones were skipped.
+     */
+    private snapshotsTaken;
+    /**
+     * 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.
+     */
+    private readonly readableState;
     /** Prop/visibility resolution context (state + repeat scope + extensions). */
     private readonly resolutionCtx;
     protected readonly visible: Signal<boolean>;
-    /** 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.
+     */
     readonly resolvedElement: Signal<UIElement<string, Record<string, unknown>> | undefined>;
     /** Two-way binding paths ($bindState / $bindItem) by prop name. */
     readonly bindings: Signal<Record<string, string> | undefined>;
@@ -631,6 +674,14 @@ declare class JrElement {
     private readonly renderCtx;
     protected readonly outletInjector: _angular_core.DestroyableInjector;
     constructor();
+    /**
+     * 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.
+     */
+    private checkSkippedWrite;
     /**
      * Resolution context with a live state snapshot, so `$state` references in
      * later actions of a chain see mutations from earlier ones.