ngx-json-render 0.7.7 → 0.8.0

package/fesm2022/ngx-json-render.mjs

@@ -1,8 +1,9 @@
 import { NgComponentOutlet } from '@angular/common';
 import * as i0 from '@angular/core';
 import { signal, Injectable, isDevMode, inject, computed, untracked, effect, DestroyRef, InjectionToken, input, output, viewChild, afterNextRender, ChangeDetectionStrategy, Component, Injector, forwardRef } from '@angular/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';
+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 } from '@json-render/core';
 export { autoFixSpec, createStateStore, formatSpecIssues, nestedToFlat, validateSpec } from '@json-render/core';
+export { schema } from 'ngx-json-render/schema';
 
 const EMPTY = signal(undefined, ...(ngDevMode ? [{ debugName: "EMPTY" }] : /* istanbul ignore next */ []));
 /**
@@ -92,6 +93,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 +183,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 +201,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 +1120,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 +1156,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 +1256,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 +1469,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 +1514,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 +1608,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 +1767,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(() => {
@@ -3622,97 +3717,6 @@ function injectChatUI(options) {
  * - `ui-stream` / `chat-ui` — the two hooks, composed from the above.
  */
 
-/**
- * The schema for ngx-json-render.
- *
- * Defines:
- * - Spec: A flat tree of elements with keys, types, props, and children references
- * - Catalog: Components with props schemas, and optional actions
- *
- * This is the same spec grammar the other json-render renderers use, so
- * catalogs and specs are portable across frameworks.
- */
-const schema = defineSchema((s) => ({
-    // What the AI-generated SPEC looks like
-    spec: s.object({
-        /** Root element key */
-        root: s.string(),
-        /** Flat map of elements by key */
-        elements: s.record(s.object({
-            /** Component type from catalog */
-            type: s.ref('catalog.components'),
-            /** Component props */
-            props: s.propsOf('catalog.components'),
-            /** Child element keys (flat reference) */
-            children: s.array(s.string()),
-            /** Visibility condition */
-            visible: { ...s.any(), ...s.optional() },
-            /** Repeat children from a state array */
-            repeat: { ...s.any(), ...s.optional() },
-        })),
-    }),
-    // What the CATALOG must provide
-    catalog: s.object({
-        /** Component definitions */
-        components: s.map({
-            /** Zod schema for component props */
-            props: s.zod(),
-            /** Slots for this component. Use ['default'] for children, or named slots like ['header', 'footer'] */
-            slots: s.array(s.string()),
-            /** Description for AI generation hints */
-            description: s.string(),
-            /** Example prop values used in prompt examples (auto-generated from Zod schema if omitted) */
-            example: s.any(),
-        }),
-        /** Action definitions (optional) */
-        actions: s.map({
-            /** Zod schema for action params */
-            params: s.zod(),
-            /** Description for AI generation hints */
-            description: s.string(),
-        }),
-    }),
-}), {
-    builtInActions: [
-        {
-            name: 'setState',
-            description: 'Update a value in the state model at the given statePath. Params: { statePath: string, value: any }',
-        },
-        {
-            name: 'pushState',
-            description: 'Append an item to an array in state. Params: { statePath: string, value: any, clearStatePath?: string }. Value can contain {"$state":"/path"} refs and "$id" for auto IDs.',
-        },
-        {
-            name: 'removeState',
-            description: 'Remove an item from an array in state by index. Params: { statePath: string, index: number }',
-        },
-        {
-            name: 'validateForm',
-            description: 'Validate all registered form fields and write the result to state. Params: { statePath?: string }. Defaults to /formValidation. Result: { valid: boolean, errors: Record<string, string[]> }.',
-        },
-        {
-            name: 'submitForm',
-            description: "Validate all registered form fields and, only if every one passes, dispatch another action. Params: { action: string, params?: object, statePath?: string }. Writes the same { valid, errors } result as validateForm. Use this on a form's submit button: it is validateForm and the submit in one binding, and the submit is skipped when the form is invalid.",
-        },
-    ],
-    defaultRules: [
-        // Element integrity
-        "CRITICAL INTEGRITY CHECK: Before outputting ANY element that references children, you MUST have already output (or will output) each child as its own element. If an element has children: ['a', 'b'], then elements 'a' and 'b' MUST exist. A missing child element causes that entire branch of the UI to be invisible.",
-        'SELF-CHECK: After generating all elements, mentally walk the tree from root. Every key in every children array must resolve to a defined element. If you find a gap, output the missing element immediately.',
-        'REQUIRED FIELDS: Every element MUST include a "children" array. Leaf elements (text, badges, inputs, images) use an empty array: "children": []. Omitting "children" fails validation.',
-        // Field placement
-        'CRITICAL: The "visible" field goes on the ELEMENT object, NOT inside "props". Correct: {"type":"<ComponentName>","props":{},"visible":{"$state":"/tab","eq":"home"},"children":[...]}.',
-        'CRITICAL: The "on" field goes on the ELEMENT object, NOT inside "props". Use on.press, on.change, on.submit etc. NEVER put action/actionParams inside props.',
-        // State and data
-        'When the user asks for a UI that displays data (e.g. blog posts, products, users), ALWAYS include a state field with realistic sample data. The state field is a top-level field on the spec (sibling of root/elements).',
-        'When building repeating content backed by a state array (e.g. posts, products, items), use the "repeat" field on a container element. Example: { "type": "<ContainerComponent>", "props": {}, "repeat": { "statePath": "/posts", "key": "id" }, "children": ["post-card"] }. For a nested list stored on the enclosing item, use "repeat": { "statePath": { "$item": "comments" }, "key": "id" }. The $item statePath form is valid only inside another repeat. Inside repeated children, use { "$item": "field" } to read a field from the current item, and { "$index": true } for the current array index. For two-way binding to an item field use { "$bindItem": "completed" }. Do NOT hardcode individual elements for each array item.',
-        // Design quality
-        'Design with visual hierarchy: use container components to group content, heading components for section titles, proper spacing, and status indicators. ONLY use components from the AVAILABLE COMPONENTS list.',
-        'For data-rich UIs, use multi-column layout components if available. For forms and single-column content, use vertical layout components. ONLY use components from the AVAILABLE COMPONENTS list.',
-        'Always include realistic, professional-looking sample data. For blogs include 3-4 posts with varied titles, authors, dates, categories. For products include names, prices, images. Never leave data empty.',
-    ],
-});
-
 /*
  * Public API Surface of ngx-json-render
  */
@@ -3722,5 +3726,5 @@ const schema = defineSchema((s) => ({
  * Generated bundle index. Do not edit.
  */
 
-export { CONFIRM_CONTEXT, ELEMENT_KEY, JR_CONFIRM_DIALOG, JR_CONFIRM_LABELS, JrChildren, JrConfirmDialog, JrElement, JrRepeatScope, JsonRenderActionsService, JsonRenderRootContext, JsonRenderStateService, JsonRenderValidationService, JsonRenderer, RENDER_CONTEXT, REPEAT_SCOPE, applyPatch, buildSpecFromParts, checkSpec, createStoreSetState, defineRegistry, flatToTree, formatSpecCheckIssues, getTextFromParts, injectAction, injectActions, injectBoundProp, injectChatUI, injectConfirmContext, injectDevtoolsActive, injectElementKey, injectFieldValidation, injectRenderContext, injectRepeatScope, injectStateBinding, injectStateStore, injectStateValue, injectUIStream, injectValidation, isActionCancelled, jsonRenderMessage, schema };
+export { CONFIRM_CONTEXT, ELEMENT_KEY, JR_CONFIRM_DIALOG, JR_CONFIRM_LABELS, JrChildren, JrConfirmDialog, JrElement, JrRepeatScope, JsonRenderActionsService, JsonRenderRootContext, JsonRenderStateService, JsonRenderValidationService, JsonRenderer, RENDER_CONTEXT, REPEAT_SCOPE, applyPatch, buildSpecFromParts, checkSpec, createStoreSetState, defineRegistry, flatToTree, formatSpecCheckIssues, getTextFromParts, injectAction, injectActions, injectBoundProp, injectChatUI, injectConfirmContext, injectDevtoolsActive, injectElementKey, injectFieldValidation, injectRenderContext, injectRepeatScope, injectStateBinding, injectStateStore, injectStateValue, injectUIStream, injectValidation, isActionCancelled, jsonRenderMessage };
 //# sourceMappingURL=ngx-json-render.mjs.map