ngx-json-render 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-json-render",
-  "version": "0.5.1",
+  "version": "0.7.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

@@ -127,7 +127,8 @@ interface RenderLimits {
  *   terminate. A tree that recurses into its items is not this.
  * - `too_deep` / `too_many_elements` — a {@link RenderLimits} cap was passed.
  * - `unknown_component` — a `type` the catalog does not define.
- * - `invalid_props` — the catalog's own schema rejected part of the spec.
+ * - `invalid_props` — an element's props fail its component's schema, or the
+ *   element fails the catalog's spec schema: a missing `children`, say.
  */
 type SpecCheckIssueCode = SpecIssue['code'] | 'cycle' | 'too_deep' | 'too_many_elements' | 'unknown_component' | 'invalid_props';
 /**
@@ -154,6 +155,19 @@ interface SpecCatalog {
         readonly success: boolean;
         readonly error?: unknown;
     };
+    /**
+     * The definitions the catalog was created from. Where
+     * `data.components[type].props` is a schema — anything with a `safeParse`,
+     * as a Zod schema has — each element's props are checked against its own
+     * component's. Without it, props are checked only as far as `validate`
+     * checks them, which for a catalog of more than one component is not at
+     * all.
+     *
+     * `unknown` rather than that shape, so that a `Catalog` whose generic
+     * arguments were left off — and whose `data` is therefore `unknown` — still
+     * fits.
+     */
+    readonly data?: unknown;
 }
 
 /**
@@ -176,9 +190,10 @@ interface SpecCheckOptions {
     readonly limits?: RenderLimits | null;
     /**
      * The catalog the spec was generated for. Given one, the check also reports
-     * component types the catalog does not define and props its own schema
-     * rejects — the half of "is this spec renderable" that structure alone
-     * cannot answer.
+     * component types the catalog does not define, elements its spec schema
+     * rejects, and props their component's schema rejects — the half of "is
+     * this spec renderable" that structure alone cannot answer. A prop written
+     * as an expression is not judged: it has no value until render time.
      */
     readonly catalog?: SpecCatalog | null;
 }
@@ -477,7 +492,11 @@ declare class JsonRenderer {
     /**
      * The catalog the spec was generated for. Given one, `validate` also checks
      * what structure alone cannot: that every `type` is a component the catalog
-     * defines, and that the props match its schema.
+     * defines, that every element has the shape the catalog's spec schema asks
+     * for — a `children` array, even on a leaf — and that its props match its
+     * component's schema. A prop written as an expression — `$state`,
+     * `$bindState`, `$template`, a directive — has no value until render time,
+     * so it is not checked.
      *
      * Only read when `validate` is on, and — like the rest of the check —
      * skipped while `loading`.
@@ -601,6 +620,34 @@ 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>;
@@ -646,6 +693,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.
@@ -1105,8 +1160,10 @@ interface UIStreamOptions {
     renderLimits?: RenderLimits | null;
     /**
      * The catalog the spec was generated for. Given one, `validate` also checks
-     * every element `type` against the catalog and the props against its
-     * schema — the half a structural check cannot see.
+     * every element `type` against the catalog and each element's props against
+     * its component's schema — the half a structural check cannot see. Props
+     * written as expressions are left alone: they have no value until render
+     * time.
      */
     catalog?: SpecCatalog | null;
     /**
@@ -1216,8 +1273,10 @@ interface ChatUIOptions {
     renderLimits?: RenderLimits | null;
     /**
      * The catalog the spec was generated for. Given one, `validate` also checks
-     * every element `type` against the catalog and the props against its
-     * schema — the half a structural check cannot see.
+     * every element `type` against the catalog and each element's props against
+     * its component's schema — the half a structural check cannot see. Props
+     * written as expressions are left alone: they have no value until render
+     * time.
      */
     catalog?: SpecCatalog | null;
 }