ngx-json-render 0.6.0 → 0.7.1

package/README.md

@@ -215,7 +215,7 @@ export class GeneratePage {
 `injectUIStream` POSTs `{ prompt, context, currentSpec }` to your endpoint and expects the response body to be SpecStream JSONL — one RFC 6902 patch per line. Any server that can stream text works; with the [AI SDK](https://ai-sdk.dev) it's a few lines — `catalog.prompt()` teaches the model your component vocabulary and the patch protocol:
 
 ```ts
-// server.ts — Express shown; any Node server works the same way
+// server.ts — Express shown (plain Node needs one extra import, see below)
 import express from 'express';
 import { streamText } from 'ai';
 import { anthropic } from '@ai-sdk/anthropic';
@@ -239,7 +239,9 @@ app.post('/api/generate', async (req, res) => {
 });
 ```
 
-The patches apply to the `spec` signal as each line arrives, so the UI assembles on screen while the model is still generating — exactly what the [demo's Streaming tab](https://shteynu.github.io/ngx-json-render/) replays. Prefer structured output? `catalog.jsonSchema()` exports a JSON Schema for `streamObject`/tool calls, and `catalog.validate(spec)` checks a finished spec against the catalog.
+`catalog.ts` imports `schema` from `ngx-json-render`, and that entry point also loads Angular and the renderer's components, which are published partially compiled. In an Angular SSR app (`ng new --ssr`) the Angular CLI finishes compiling them when it builds the server, so the route above goes into its `server.ts` unchanged and works both under `ng serve` and from the built server. On Angular 20 and 21, add `"prebundle": { "exclude": ["zod"] }` to the `serve` options in `angular.json` first: their Vite 7 dev server can't transform zod for the server (`Cannot split a chunk that has already been edited`) and answers every page and API route with a 500. A Node server the Angular CLI doesn't build, run with `node` or `tsx`, fails on that import with `'@angular/compiler' is not available` — make `import '@angular/compiler';` its first import.
+
+The patches apply to the `spec` signal as each line arrives, so the UI assembles on screen while the model is still generating — exactly what the [demo's Streaming tab](https://shteynu.github.io/ngx-json-render/) replays. Prefer structured output? `catalog.jsonSchema()` exports a JSON Schema for `streamObject`/tool calls, and `checkSpec(spec, 'strict', { catalog })` checks a finished spec against the catalog, props included — see [Checking what the model produced](#checking-what-the-model-produced) for why that and not `catalog.validate(spec)` alone.
 
 ### Chat + GenUI
 
@@ -372,12 +374,23 @@ is a patch that has not arrived yet, not a defect, so nothing is reported and
 `strict` keeps rendering; the hooks check once, when the generation completes.
 
 Pass the catalog too, and the same check covers what structure alone cannot
-see — every `type` is one the catalog defines, and the props match its schema:
+see — every `type` is one the catalog defines, and each element's props match
+its component's schema:
 
 ```html
 <json-render [spec]="spec()" [registry]="registry" [catalog]="catalog" validate="strict" />
 ```
 
+A prop written as an expression — `{"$state": …}`, `{"$bindState": …}`,
+`{"$template": …}`, a directive — is not checked: it has no value until render
+time. The catalog's spec schema also holds every element to the grammar, which
+wants a `children` array even on a leaf.
+
+The props check is this package's own. Core's `catalog.validate(spec)` gives an
+element's props its component's schema only when the catalog has exactly one
+component; with more, it checks element shapes and `type` names but not a
+single prop.
+
 ### Capping what a spec may cost
 
 `validate` describes a spec. `renderLimits` constrains it:
@@ -754,10 +767,13 @@ not generate should set all three. See
 [Capping what a spec may cost](#capping-what-a-spec-may-cost).
 
 **A spec can name components you never built.** `validate` with a `catalog`
-reports every `type` the catalog does not define and every prop its schema
-rejects; `strict` refuses such a spec outright. Without a catalog the renderer
-only warns and draws nothing in that element's place, which degrades well but
-tells you nothing until you read the console.
+reports every `type` the catalog does not define and every prop its component's
+schema rejects; `strict` refuses such a spec outright. A prop bound to an
+expression (`$state`, `$bindState`, `$template`, …) is not among them — its value
+only exists at render time — so a component should not count on such a prop
+having the type its schema declares. Without a catalog the renderer only warns
+and draws nothing in that element's place, which degrades well but tells you
+nothing until you read the console.
 
 **`confirm` is a UX affordance, not a security control.** It routes an action
 through the confirmation dialog before the handler runs, but it is set on the

package/fesm2022/ngx-json-render.mjs

@@ -1898,63 +1898,219 @@ function depthIssue(depth, limit) {
     };
 }
 /**
- * Check a spec against a catalog: the component types it names, and then the
- * catalog's own schema.
+ * Check a spec against a catalog: the component types it names, then the
+ * catalog's spec schema, then each element's props against its own
+ * component's schema.
  *
- * The schema pass is skipped while a type is unknown. A catalog schema keys
- * its element shapes off `type`, so one name it does not recognise turns into
- * a pile of prop errors describing a component that was never the point.
+ * The props need that pass of their own. Core builds one schema for the whole
+ * spec, and it gives an element's props a component's schema only when the
+ * catalog has exactly one component; with more, every element's props are an
+ * open record, whatever its `type`. So `catalog.validate` holds an element to
+ * its shape — `children`, a `type` from the catalog — and not to its props.
+ *
+ * Whatever that schema did say about the props of an element checked here is
+ * dropped: with a one-component catalog it would be reported twice, and it
+ * judges expressions this pass knows to leave alone.
+ *
+ * The schema passes are skipped while a type is unknown. That is an error on
+ * its own, and the spec schema would only restate it as a `type` outside the
+ * ones it accepts.
  */
 function catalogIssues(spec, catalog) {
-    const issues = [];
+    const elements = Object.entries(spec.elements ?? {});
     const known = new Set(catalog.componentNames);
-    for (const [key, element] of Object.entries(spec.elements ?? {})) {
+    const unknown = [];
+    for (const [key, element] of elements) {
         if (known.has(element.type))
             continue;
-        issues.push({
+        unknown.push({
             severity: 'error',
             code: 'unknown_component',
             elementKey: key,
             message: `Element "${key}" has type "${element.type}", which this catalog does not define. Nothing renders for it.`,
         });
     }
-    if (issues.length > 0)
-        return issues;
-    const result = catalog.validate(spec);
+    if (unknown.length > 0)
+        return unknown;
+    const schemas = new Map();
+    for (const [key, element] of elements) {
+        const schema = propsSchemaOf(catalog.data, element.type);
+        if (schema)
+            schemas.set(key, schema);
+    }
+    const found = specSchemaIssues(spec, catalog).filter(({ path }) => !(path[0] === 'elements' &&
+        typeof path[1] === 'string' &&
+        schemas.has(path[1]) &&
+        path[2] === 'props'));
+    for (const [key, element] of elements) {
+        const room = MAX_REPORTED_PROP_ISSUES - found.length;
+        if (room <= 0)
+            break;
+        const schema = schemas.get(key);
+        if (schema)
+            found.push(...propsIssues(key, element, schema, room));
+    }
+    return found.slice(0, MAX_REPORTED_PROP_ISSUES).map(toSpecCheckIssue);
+}
+/**
+ * The props schema a catalog declares for a component type, if it declares
+ * one that can be called.
+ */
+function propsSchemaOf(data, type) {
+    const components = data
+        ?.components;
+    if (typeof components !== 'object' ||
+        components === null ||
+        !Object.hasOwn(components, type)) {
+        return undefined;
+    }
+    const props = components[type]?.props;
+    return typeof props
+        ?.safeParse === 'function'
+        ? props
+        : undefined;
+}
+/** What the catalog's spec schema reported, with paths rooted at the spec. */
+function specSchemaIssues(spec, catalog) {
+    try {
+        const result = catalog.validate(spec);
+        return result.success ? [] : readIssues(result.error);
+    }
+    catch (error) {
+        return [{ path: [], message: threwMessage('the catalog schema', error) }];
+    }
+}
+/**
+ * What an element's component schema says about its props, leaving out what
+ * it says about expressions, with paths rooted at the spec.
+ *
+ * A schema that throws counts as a rejection, not a crash. Real ones do:
+ * `ValidationConfigSchema`, which every Material input's `validation` prop
+ * uses, recurses through `enabled` and overflows the stack a thousand
+ * `$and`s deep.
+ */
+function propsIssues(key, element, schema, room) {
+    const at = ['elements', key, 'props'];
+    let result;
+    try {
+        result = schema.safeParse(element.props);
+    }
+    catch (error) {
+        return [
+            {
+                path: at,
+                message: threwMessage(`the "${element.type}" schema`, error),
+            },
+        ];
+    }
     if (result.success)
-        return issues;
-    return propIssues(result.error);
+        return [];
+    const issues = [];
+    for (const { path, message } of readIssues(result.error)) {
+        if (issues.length >= room)
+            break;
+        if (reachesExpression(element.props, path))
+            continue;
+        issues.push({ path: [...at, ...path], message });
+    }
+    return issues;
+}
+/**
+ * Whether a props issue is about an expression: it sits on one, inside one,
+ * or on a value holding one.
+ *
+ * `{"$state": "/title"}` where the schema wants a string is not a defect.
+ * Core resolves every such value before the component sees it, so the schema
+ * would be judging something that never renders. Any `$`-prefixed key counts
+ * — directive names must start with `$`, and so would an expression added to
+ * core later. A value merely holding one is left alone too, since a union or
+ * a refinement over it ran on the unresolved value.
+ *
+ * The props object itself is not an expression: core resolves the values
+ * inside it, never the object.
+ */
+function reachesExpression(props, path) {
+    let value = props;
+    for (const segment of path) {
+        if (typeof value !== 'object' || value === null)
+            return false;
+        value = value[segment];
+        if (isExpression(value))
+            return true;
+    }
+    return holdsExpression(value);
+}
+/** A value core resolves at render time — or will, once it knows the key. */
+function isExpression(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.keys(value).some((key) => key.startsWith('$')));
 }
 /**
- * Turn whatever the catalog's schema reported into issues.
+ * Whether anything nested inside `value` is an expression.
+ *
+ * Iterative, and it remembers what it has seen, for the same reason as
+ * {@link analyseSpecGraph}: props are as attacker-shaped as the rest of the
+ * spec, and a check that overflowed or looped on them would be a second way
+ * to crash.
+ */
+function holdsExpression(value) {
+    const pending = [value];
+    const seen = new Set();
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (typeof current !== 'object' || current === null)
+            continue;
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        for (const child of Object.values(current)) {
+            if (isExpression(child))
+                return true;
+            pending.push(child);
+        }
+    }
+    return false;
+}
+/**
+ * Read what a schema reported.
  *
  * Read defensively rather than typed against the schema library: the shape
  * below (`issues`, each with `path` and `message`) is what every version of
  * it has produced, and a renderer that threw while explaining a bad spec
  * would be the worse failure.
  */
-function propIssues(error) {
+function readIssues(error) {
     const raw = error?.issues;
     if (!Array.isArray(raw))
         return [];
-    return raw.slice(0, MAX_REPORTED_PROP_ISSUES).map((entry) => {
+    return raw.map((entry) => {
         const item = entry;
-        const path = Array.isArray(item.path) ? item.path : [];
-        const message = typeof item.message === 'string' ? item.message : 'is not valid';
-        // Paths are rooted at the spec, so `elements.<key>.props.<prop>` names the
-        // element in its second segment.
-        const elementKey = path[0] === 'elements' && typeof path[1] === 'string'
-            ? path[1]
-            : undefined;
-        const where = path.length > 0 ? path.join('.') : 'spec';
+        const path = item?.path;
+        const message = item?.message;
         return {
-            severity: 'error',
-            code: 'invalid_props',
-            ...(elementKey === undefined ? {} : { elementKey }),
-            message: `${where}: ${message}`,
+            path: Array.isArray(path) ? path : [],
+            message: typeof message === 'string' ? message : 'is not valid',
         };
     });
 }
+function threwMessage(schema, error) {
+    const reason = error instanceof Error ? ` (${error.name}: ${error.message})` : '';
+    return `${schema} threw instead of answering${reason}, so this counts as rejected`;
+}
+function toSpecCheckIssue({ path, message }) {
+    // Paths are rooted at the spec, so `elements.<key>.props.<prop>` names the
+    // element in its second segment.
+    const elementKey = path[0] === 'elements' && typeof path[1] === 'string' ? path[1] : undefined;
+    const where = path.length > 0 ? path.map(String).join('.') : 'spec';
+    return {
+        severity: 'error',
+        code: 'invalid_props',
+        ...(elementKey === undefined ? {} : { elementKey }),
+        message: `${where}: ${message}`,
+    };
+}
 
 const CLEAN = {
     spec: null,
@@ -2139,7 +2295,11 @@ 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`.