ngx-json-render 0.5.1 → 0.7.0

package/README.md

@@ -239,7 +239,7 @@ 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.
+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 +372,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:
@@ -606,6 +617,12 @@ A write reaches only the components whose resolved props actually changed. Writi
 
 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.
@@ -748,10 +765,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