ngx-json-render 0.1.4 → 0.2.1

package/README.md

@@ -8,7 +8,7 @@ Built on `@json-render/core` (the same spec format, expressions, state store, ac
 
 This is an Angular **adapter over the official core**, not a second implementation of it — `@json-render/core` is a peer dependency, and the spec your model emits is the same one the React, Vue, Solid and Svelte renderers consume. A catalog and a spec written here move to another framework unchanged.
 
-**[Live demo](https://shteynu.github.io/ngx-json-render/)** — interactive spec (bindings, repeat, confirm, watch) and a replayable SpecStream showing progressive rendering ([source](https://github.com/shteynu/ngx-json-render/tree/main/projects/demo)) — or [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/shteynu/ngx-json-render)
+**[Live demo](https://shteynu.github.io/ngx-json-render/)** — interactive spec (bindings, repeat, confirm, watch), a SpecStream rendering progressively that you can stop mid-generation, and a chat where prose and UI patches arrive in one reply; both streaming tabs replay a recording, or call a real model on your own key ([source](https://github.com/shteynu/ngx-json-render/tree/main/projects/demo)) — or [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/shteynu/ngx-json-render)
 
 ![A SpecStream of RFC 6902 patches rendering progressively into an Angular dashboard](https://raw.githubusercontent.com/shteynu/ngx-json-render/main/docs/streaming.gif)
 
@@ -135,6 +135,9 @@ import { injectUIStream } from 'ngx-json-render';
   template: `
     <json-render [spec]="ui.spec()" [registry]="registry" [loading]="ui.isStreaming()" />
     <button (click)="ui.send('A dashboard for weekly sales')">Generate</button>
+    @if (ui.isStreaming()) {
+      <button (click)="ui.stop()">Stop</button>
+    }
   `,
   imports: [JsonRenderer],
 })
@@ -175,10 +178,48 @@ 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.
 
+### Supplying the transport
+
+By default the request goes through the global `fetch`. Pass your own to add
+auth headers, route through your app's HTTP layer, or replay a recorded
+generation in a test — it is called with the endpoint and a request carrying
+the JSON body and the abort signal, and must resolve to a `Response` whose
+`body` streams the JSONL:
+
+```ts
+readonly ui = injectUIStream({
+  api: '/api/generate',
+  fetch: (url, init) =>
+    fetch(url, { ...init, headers: { ...init?.headers, Authorization: token } }),
+});
+```
+
+`injectChatUI` takes the same option.
+
+### Stopping, clearing and refining
+
+`stop()` ends the generation in flight and keeps what has already rendered —
+the user changed their mind, so it is not an error and `error` stays null.
+`clear()` stops it too and then resets `spec`, `error`, `usage` and `rawLines`;
+without the stop the request still running would put its spec back on its very
+next patch. Both are no-ops when nothing is streaming, and `injectChatUI` has
+the same pair.
+
+To refine a generated UI instead of starting over, hand `send` the spec to
+build on. It is sent to the endpoint as `currentSpec` and the streamed patches
+apply on top of it:
+
+```ts
+ui.send('make the chart a bar chart', { previousSpec: ui.spec()! });
+```
+
+The second argument also carries `context`, forwarded to the endpoint as-is:
+`ui.send(prompt, { context: { locale }, previousSpec })`.
+
 Also available:
 
-- `injectChatUI({ api })` — chat + GenUI: the endpoint takes `{ messages }` and streams prose mixed with ` ```spec ` fenced JSONL; each assistant message carries `text` and/or a `spec`.
-- `applyPatch(spec, patch)` — immutably apply one RFC 6902 patch to a spec.
+- `injectChatUI({ api, fetch? })` — chat + GenUI: the endpoint takes `{ messages }` and streams prose mixed with ` ```spec ` fenced JSONL; each assistant message carries `text` and/or a `spec`.
+- `applyPatch(spec, patch)` — immutably apply one RFC 6902 patch to a spec, sharing every subtree the patch did not touch. Both hooks and `buildSpecFromParts` apply through it, so the same stream produces the same spec whichever one you reach for. One deliberate deviation from the RFC: a failing `test` op is a no-op rather than an abort, because these patches come off a model's output and dropping a bad line beats killing the generation.
 - `buildSpecFromParts` / `getTextFromParts` / `jsonRenderMessage` — derive specs from AI SDK `message.parts`.
 - `catalog.prompt()` / `buildUserPrompt` (from `@json-render/core`) — generate the system/user prompts for your catalog.
 
@@ -186,22 +227,22 @@ Also available:
 
 Full parity with the baseline json-render contract:
 
-| Feature | Example |
-| --- | --- |
-| Dynamic props | `{ "$state": "/user/name" }` |
-| Two-way binding | `{ "$bindState": "/form/email" }`, `{ "$bindItem": "done" }` |
-| Conditionals | `{ "$cond": {...}, "$then": ..., "$else": ... }` |
-| Templates | `{ "$template": "Hello, ${/user/name}" }` |
-| Computed / directives | `{ "$computed": "fmtDate", "args": {...} }`, custom `$`-directives |
-| Visibility | `"visible": { "$state": "/count", "gte": 5 }` (incl. `$and`/`$or`, `$item`, `$index`) |
-| Events → actions | `"on": { "press": { "action": "...", "params": {...}, "confirm": {...}, "onSuccess": ..., "onError": ... } }` |
-| Built-in actions | `setState`, `pushState` (with `$id`), `removeState`, `push`/`pop`, `validateForm` |
-| Repeat | `"repeat": { "statePath": "/todos", "key": "id" }`, nested via `{ "$item": "..." }` |
-| Watch | `"watch": { "/country": { "action": "loadCities" } }` |
-| Slots | `"slots": { "header": ["title-el"] }` + `<jr-children slot="header" />` |
-| Validation | field checks via `ValidationConfig`, `validateForm`, `injectFieldValidation` |
-| Confirm dialogs | built-in `<jr-confirm-dialog>` (auto-rendered) |
-| Devtools hooks | action observer + `data-jr-key` picker attributes |
+| Feature               | Example                                                                                                       |
+| --------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Dynamic props         | `{ "$state": "/user/name" }`                                                                                  |
+| Two-way binding       | `{ "$bindState": "/form/email" }`, `{ "$bindItem": "done" }`                                                  |
+| Conditionals          | `{ "$cond": {...}, "$then": ..., "$else": ... }`                                                              |
+| Templates             | `{ "$template": "Hello, ${/user/name}" }`                                                                     |
+| Computed / directives | `{ "$computed": "fmtDate", "args": {...} }`, custom `$`-directives                                            |
+| Visibility            | `"visible": { "$state": "/count", "gte": 5 }` (incl. `$and`/`$or`, `$item`, `$index`)                         |
+| Events → actions      | `"on": { "press": { "action": "...", "params": {...}, "confirm": {...}, "onSuccess": ..., "onError": ... } }` |
+| Built-in actions      | `setState`, `pushState` (with `$id`), `removeState`, `push`/`pop`, `validateForm`                             |
+| Repeat                | `"repeat": { "statePath": "/todos", "key": "id" }`, nested via `{ "$item": "..." }`                           |
+| Watch                 | `"watch": { "/country": { "action": "loadCities" } }`                                                         |
+| Slots                 | `"slots": { "header": ["title-el"] }` + `<jr-children slot="header" />`                                       |
+| Validation            | field checks via `ValidationConfig`, `validateForm`, `injectFieldValidation`                                  |
+| Confirm dialogs       | built-in `<jr-confirm-dialog>` (auto-rendered)                                                                |
+| Devtools hooks        | action observer + `data-jr-key` picker attributes                                                             |
 
 ## State
 
@@ -250,7 +291,7 @@ rest.
 and `onSuccess.set` all take a `statePath` straight from the spec, so a
 generated UI can write anywhere in the state model it is rendered against —
 and `push`/`pop` write `/currentScreen` and `/navStack`. In controlled mode
-this is *your* store. Give the renderer a store scoped to the generated view
+this is _your_ store. Give the renderer a store scoped to the generated view
 rather than the one holding session, entitlement or billing state.
 
 **A spec chooses the navigation target.** `onSuccess: { navigate }` passes its
@@ -265,7 +306,7 @@ one.
 
 **`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
-action binding *inside the spec* (`on.press.confirm`) — so the same party that
+action binding _inside the spec_ (`on.press.confirm`) — so the same party that
 chose the action also chose whether to ask. Real authorization belongs in the
 handler, on the server.
 
@@ -281,20 +322,20 @@ Everything from `@json-render/core` (types, `createStateStore`, `nestedToFlat`,
 
 ## Renderer inputs
 
-| Input | Type | Purpose |
-| --- | --- | --- |
-| `spec` | `Spec \| null` | The UI spec (may be partial while streaming) |
-| `registry` | `ComponentRegistry` | Catalog type → Angular component |
-| `loading` | `boolean` | Suppress missing-element warnings while streaming |
-| `fallback` | `Type<unknown>` | Component for unknown types |
-| `state` | `StateModel` | Initial state (uncontrolled; defaults to `spec.state`) |
-| `store` | `StateStore` | External store (controlled mode) |
-| `handlers` | `Record<string, ActionHandler>` | Action handlers |
-| `onAction` | `(name, params) => unknown` | Catch-all action handler |
-| `navigate` | `(path) => void` | Used by `onSuccess: { navigate }` |
-| `validationFunctions` | `Record<string, ValidationFunction>` | Custom validation |
-| `functions` | `Record<string, ComputedFunction>` | `$computed` functions |
-| `directives` | `DirectiveDefinition[]` | Custom `$`-prefixed expressions |
+| Input                 | Type                                 | Purpose                                                |
+| --------------------- | ------------------------------------ | ------------------------------------------------------ |
+| `spec`                | `Spec \| null`                       | The UI spec (may be partial while streaming)           |
+| `registry`            | `ComponentRegistry`                  | Catalog type → Angular component                       |
+| `loading`             | `boolean`                            | Suppress missing-element warnings while streaming      |
+| `fallback`            | `Type<unknown>`                      | Component for unknown types                            |
+| `state`               | `StateModel`                         | Initial state (uncontrolled; defaults to `spec.state`) |
+| `store`               | `StateStore`                         | External store (controlled mode)                       |
+| `handlers`            | `Record<string, ActionHandler>`      | Action handlers                                        |
+| `onAction`            | `(name, params) => unknown`          | Catch-all action handler                               |
+| `navigate`            | `(path) => void`                     | Used by `onSuccess: { navigate }`                      |
+| `validationFunctions` | `Record<string, ValidationFunction>` | Custom validation                                      |
+| `functions`           | `Record<string, ComputedFunction>`   | `$computed` functions                                  |
+| `directives`          | `DirectiveDefinition[]`              | Custom `$`-prefixed expressions                        |
 
 Output: `(stateChange)` — batched `{ path, value }[]` in uncontrolled mode.