ngx-json-render 0.8.2 → 0.9.0

package/README.md

@@ -273,6 +273,40 @@ export class GeneratePage {
 }
 ```
 
+### Placeholders while props stream
+
+An element can arrive before its props do: a Card with no `title` yet, a Text
+with no `content`. By default the component mounts anyway and renders what it
+has. Pass the `catalog` and the renderer waits instead: while `loading` is
+true, an element whose props do not pass its component's schema shows its
+registry entry's `fallback`, or nothing, and the component mounts once they
+do.
+
+```ts
+export const { registry } = defineRegistry(catalog, {
+  components: {
+    Card: { component: CardComponent, fallback: CardSkeleton },
+    Text: TextComponent, // nothing on screen until `content` arrives
+  },
+});
+```
+
+```html
+<json-render [spec]="ui.spec()" [registry]="registry" [catalog]="catalog" [loading]="ui.isStreaming()" />
+```
+
+- The fallback gets the same render context as the component: it can read
+  the props that have arrived, and a `<jr-children />` in it lays out the
+  children that have.
+- Props are checked as the spec writes them. `{ "$state": "/title" }` counts
+  as arrived, whatever it resolves to.
+- Once an element's component has mounted it stays, even if a later patch
+  takes a prop away again.
+- When `loading` turns false every element mounts, valid or not; reporting
+  what is wrong with the finished spec is `validate`'s job.
+- Without a `catalog`, or for a type the catalog has no props schema for,
+  nothing is held back.
+
 ### The server side
 
 `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:
@@ -744,6 +778,37 @@ value it derives updates when that state does.
 `projects/ngx-json-render/src/lib/directives.spec.ts` renders every one of
 them through the renderer, which is what keeps this paragraph honest.
 
+### Switching language
+
+Where a spec's text comes from decides how it follows a language switch.
+
+**Keys, translated on the client.** A spec that says
+`{ "$t": "greeting", "params": { "name": { "$state": "/name" } } }` instead of
+the words themselves switches in place. Derive `directives` from your locale
+signal, and every prop re-resolves when it changes, with no new spec and
+nothing remounted:
+
+```ts
+readonly locale = signal('en');
+readonly directives = computed(() => [
+  ...standardDirectives,
+  createI18nDirective({ locale: this.locale(), messages }),
+]);
+```
+
+`$format` takes a `locale` the same way, for numbers, currency and dates.
+
+**Words, written by the model.** Most generated UIs are this kind: the model
+writes "Save" or "Сохранить" straight into the props. Tell it the language
+through `context` (`ui.send(prompt, { context: { locale } })`) and say what to
+do with it in your server's prompt. Text already on screen stays in the
+language it was written in; switching means asking again, and
+`previousSpec` keeps the layout while the model rewrites the words.
+
+Text inside your catalog components is your app's own i18n, as it would be
+anywhere else. The confirm dialog's two default words are `JR_CONFIRM_LABELS`
+(see [Confirmation dialogs](#confirmation-dialogs)).
+
 ## State
 
 Each `<json-render>` owns a state store (JSON Pointer addressed). Seeding order: `store` input (controlled) → `state` input → `spec.state`.
@@ -982,7 +1047,7 @@ Everything from `@json-render/core` (types, `createStateStore`, `nestedToFlat`,
 | `fallback`            | `Type<unknown>`                      | Component for unknown types                             |
 | `validate`            | `'off' \| 'warn' \| 'strict'`        | Check the settled spec's structure (default `'off'`)    |
 | `renderLimits`        | `RenderLimits`                       | Cap elements, depth and repeat expansion (default none) |
-| `catalog`             | `Catalog`                            | Also check types and props against the catalog          |
+| `catalog`             | `Catalog`                            | Check types and props; hold back half-streamed props    |
 | `state`               | `StateModel`                         | Initial state (uncontrolled; defaults to `spec.state`)  |
 | `store`               | `StateStore`                         | External store (controlled mode)                        |
 | `handlers`            | `Record<string, ActionHandler>`      | Action handlers                                         |