ngx-json-render 0.8.2 → 0.9.1

package/README.md

@@ -250,6 +250,38 @@ export class Page {
 }
 ```
 
+### Defaults for the whole app
+
+A chat renders a spec in every message, and binding the same registry and handlers on each one gets old. `provideJsonRender` sets them once:
+
+```ts
+bootstrapApplication(App, {
+  providers: [
+    provideJsonRender(() => {
+      const orders = inject(OrderService); // the function form runs in an injection context
+      return {
+        registry,
+        catalog,
+        handlers: { cancelOrder: (params) => orders.cancel(params['id']) },
+      };
+    }),
+  ],
+});
+```
+
+```html
+<json-render [spec]="m.spec" />
+```
+
+Every option input can be provided: `registry`, `fallback`, `validate`, `renderLimits`, `catalog`, `handlers`, `onAction`, `navigate`, `validationFunctions`, `functions` and `directives`. Per-instance inputs (`spec`, `loading`, `state`, `store`) cannot. The rules:
+
+- An input bound on the element wins over the provided value. One left `null` or `undefined` falls through to it.
+- `handlers`, `functions`, `validationFunctions` and `directives` merge by name instead, the element's entry winning a name both define. A chat can provide app-wide handlers and still add one for a single message.
+- Everything else replaces. A `registry` belongs to its catalog, so two are never mixed behind your back; to combine them, spread them yourself (`{ ...registry, ...extraRegistry }`).
+- It works in application, route and component `providers`. A provider below another extends it by the same rules.
+
+With no registry bound and none provided, the renderer throws, naming both ways to supply one.
+
 ## Streaming a UI from an LLM
 
 Specs stream as JSONL patch lines (RFC 6902). Render partial specs as they arrive — the renderer tolerates missing elements while `loading` is true:
@@ -273,6 +305,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:
@@ -357,15 +423,16 @@ import { JsonRenderer, injectChatUI } from 'ngx-json-render';
     @for (m of chat.messages(); track m.id) {
       <p>{{ m.text }}</p>
       @if (m.spec) {
-        <json-render [spec]="m.spec" [registry]="registry" />
+        <json-render [spec]="m.spec" />
       }
     }
     <button (click)="chat.send('show me revenue for the quarter')">Ask</button>
   `,
 })
 export class ChatPage {
+  // The registry comes from provideJsonRender({ registry }) in the app's
+  // providers: see "Defaults for the whole app".
   readonly chat = injectChatUI({ api: '/api/chat' });
-  readonly registry = registry;
 }
 ```
 
@@ -744,6 +811,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`.
@@ -900,7 +998,26 @@ rather than the one holding session, entitlement or billing state.
 **A spec chooses the navigation target.** `onSuccess: { navigate }` passes its
 string to the `navigate` callback you provide, verbatim. Treat it as untrusted:
 match it against known routes, and never hand it to `window.location` or
-`router.navigateByUrl` unchecked.
+`router.navigateByUrl` unchecked. `ngx-json-render/router` does the checking
+for an app on the Angular `Router`:
+
+```ts
+import { injectRouterNavigate } from 'ngx-json-render/router';
+
+provideJsonRender(() => ({
+  registry,
+  navigate: injectRouterNavigate({ allow: ['/thanks', /^\/orders\/\d+$/] }),
+}));
+```
+
+It passes a path to `router.navigateByUrl` only when `allow` lets it through
+(strings match the path exactly, before any `?` or `#`; a `RegExp` is tested
+against it; a function decides). `allow` is required, because only the app
+knows which of its routes a generated UI may open. Whatever `allow` says, a
+path that does not start with a single `/` is refused: no other origin, no
+`javascript:` or other scheme, no relative path, no backslash or control
+character. A refused path, or a navigation the router rejects, is reported
+with `console.warn` and goes nowhere.
 
 **A spec cannot render forever.** Two elements naming each other as children,
 or one naming itself, would recurse until the tab died. The renderer refuses to
@@ -948,6 +1065,8 @@ Components: `JsonRenderer` (`<json-render>`), `JrChildren`, `JrConfirmDialog`, `
 
 Injectables/helpers: `injectRenderContext`, `injectElementKey`, `injectRepeatScope`, `injectStateStore`, `injectStateValue`, `injectStateBinding`, `injectBoundProp`, `injectActions`, `injectAction`, `injectValidation`, `injectFieldValidation`, `injectUIStream`, `injectChatUI`, `injectDevtoolsActive`, `injectConfirmContext`, `jsonRenderMessage`, `isActionCancelled`, `checkSpec`.
 
+App-wide defaults: `provideJsonRender`, the `JSON_RENDER_CONFIG` token it fills, and the type `JsonRenderConfig`.
+
 Tokens: `JR_CONFIRM_DIALOG` (replace the confirmation dialog), `JR_CONFIRM_LABELS` (its two words), `CONFIRM_CONTEXT`, `RENDER_CONTEXT`, `REPEAT_SCOPE`.
 
 Spec checking: `checkSpec`, `formatSpecCheckIssues`, and the types
@@ -966,6 +1085,8 @@ Schema alone (`ngx-json-render/schema`): `schema`, `AngularSchema`, `AngularSpec
 
 MCP Apps (`ngx-json-render/mcp`): `injectJsonRenderApp`, `parseSpecFromToolResult`, `messageText`, and the types `JsonRenderApp`, `JsonRenderAppOptions`. Needs the optional peers `@modelcontextprotocol/ext-apps` and `@modelcontextprotocol/sdk`.
 
+Router (`ngx-json-render/router`): `injectRouterNavigate`, and the type `RouterNavigateOptions`. Needs the optional peer `@angular/router`, which an Angular app on the router already has.
+
 Devtools (`ngx-json-render/devtools`): `JsonRenderDevtools` (`<json-render-devtools>`), and the types `DevtoolsEvent`, `PanelPosition`. Needs the optional peer `@json-render/devtools`.
 
 Testing (`ngx-json-render/testing`): `renderSpec`, `renderComponent`, `recordedTransport`, `specStream`, `usageLine`.
@@ -977,12 +1098,12 @@ Everything from `@json-render/core` (types, `createStateStore`, `nestedToFlat`,
 | Input                 | Type                                 | Purpose                                                 |
 | --------------------- | ------------------------------------ | ------------------------------------------------------- |
 | `spec`                | `Spec \| null`                       | The UI spec (may be partial while streaming)            |
-| `registry`            | `ComponentRegistry`                  | Catalog type → Angular component                        |
+| `registry`            | `ComponentRegistry`                  | Catalog type → component; required unless provided      |
 | `loading`             | `boolean`                            | Suppress missing-element warnings while streaming       |
 | `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                                         |
@@ -994,6 +1115,8 @@ Everything from `@json-render/core` (types, `createStateStore`, `nestedToFlat`,
 
 Output: `(stateChange)` — batched `{ path, value }[]` in uncontrolled mode.
 
+Every input but `spec`, `loading`, `state` and `store` can come from `provideJsonRender` instead; see [Defaults for the whole app](#defaults-for-the-whole-app).
+
 ## License
 
 Apache-2.0

package/fesm2022/ngx-json-render-router.mjs

@@ -0,0 +1,71 @@
+import { inject } from '@angular/core';
+import { Router } from '@angular/router';
+
+/**
+ * A `navigate` for `<json-render>` that hands a spec's
+ * `onSuccess: { navigate }` path to the Angular `Router`, but only a path
+ * inside the app that `allow` lets through. Anything else is refused with a
+ * warning and goes nowhere.
+ *
+ * Call it in an injection context — in the function form of
+ * `provideJsonRender`, or in a field initializer:
+ *
+ * ```ts
+ * provideJsonRender(() => ({
+ *   registry,
+ *   navigate: injectRouterNavigate({ allow: ['/thanks', /^\/orders\/\d+$/] }),
+ * }));
+ * ```
+ *
+ * Whatever `allow` says, a path is refused unless it starts with a single
+ * `/`: no other origin (`https://…`, `//host`), no scheme (`javascript:…`),
+ * no path relative to wherever the user happens to be. A backslash or a
+ * control character refuses it too, since browsers read `/\host` as
+ * `//host`.
+ */
+function injectRouterNavigate(options) {
+    const router = inject(Router);
+    const allowed = toPredicate(options.allow);
+    return (path) => {
+        if (!isAppPath(path)) {
+            console.warn(`[ngx-json-render] Refused to navigate to ${JSON.stringify(path)}: a spec may only navigate to a path inside the app, starting with a single "/".`);
+            return;
+        }
+        const pathname = path.split(/[?#]/, 1)[0];
+        if (!allowed(pathname)) {
+            console.warn(`[ngx-json-render] Refused to navigate to "${path}": "${pathname}" is not in the allow list given to injectRouterNavigate.`);
+            return;
+        }
+        router.navigateByUrl(path).catch((error) => {
+            console.warn(`[ngx-json-render] Navigation to "${path}" failed.`, error);
+        });
+    };
+}
+function isAppPath(path) {
+    return (typeof path === 'string' &&
+        /^\/(?![/\\])/.test(path) &&
+        !/[\\\u0000-\u001f\u007f]/.test(path));
+}
+function toPredicate(allow) {
+    if (typeof allow === 'function')
+        return allow;
+    return (path) => allow.some((rule) => {
+        if (typeof rule === 'string')
+            return rule === path;
+        // A global or sticky RegExp keeps `lastIndex` between calls; reset it so
+        // one rule answers the same way for the same path every time.
+        rule.lastIndex = 0;
+        return rule.test(path);
+    });
+}
+
+/*
+ * Public API Surface of ngx-json-render/router
+ */
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { injectRouterNavigate };
+//# sourceMappingURL=ngx-json-render-router.mjs.map

package/fesm2022/ngx-json-render-router.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ngx-json-render-router.mjs","sources":["../../../projects/ngx-json-render/router/src/router-navigate.ts","../../../projects/ngx-json-render/router/src/public-api.ts","../../../projects/ngx-json-render/router/src/ngx-json-render-router.ts"],"sourcesContent":["import { inject } from '@angular/core';\nimport { Router } from '@angular/router';\n\n/** Which paths a spec may send the app to. */\nexport interface RouterNavigateOptions {\n  /**\n   * The paths a spec may navigate to. A string must equal the path exactly; a\n   * `RegExp` is tested against it; a function decides on its own. The path is\n   * what comes before any `?` or `#`, so a query string or fragment neither\n   * helps nor hurts a match, and is passed on to the router as written.\n   *\n   * Required: a spec is model output, and the app is what knows which of its\n   * routes a generated UI has any business opening.\n   */\n  readonly allow: readonly (string | RegExp)[] | ((path: string) => boolean);\n}\n\n/**\n * A `navigate` for `<json-render>` that hands a spec's\n * `onSuccess: { navigate }` path to the Angular `Router`, but only a path\n * inside the app that `allow` lets through. Anything else is refused with a\n * warning and goes nowhere.\n *\n * Call it in an injection context — in the function form of\n * `provideJsonRender`, or in a field initializer:\n *\n * ```ts\n * provideJsonRender(() => ({\n *   registry,\n *   navigate: injectRouterNavigate({ allow: ['/thanks', /^\\/orders\\/\\d+$/] }),\n * }));\n * ```\n *\n * Whatever `allow` says, a path is refused unless it starts with a single\n * `/`: no other origin (`https://…`, `//host`), no scheme (`javascript:…`),\n * no path relative to wherever the user happens to be. A backslash or a\n * control character refuses it too, since browsers read `/\\host` as\n * `//host`.\n */\nexport function injectRouterNavigate(\n  options: RouterNavigateOptions,\n): (path: string) => void {\n  const router = inject(Router);\n  const allowed = toPredicate(options.allow);\n  return (path) => {\n    if (!isAppPath(path)) {\n      console.warn(\n        `[ngx-json-render] Refused to navigate to ${JSON.stringify(path)}: a spec may only navigate to a path inside the app, starting with a single \"/\".`,\n      );\n      return;\n    }\n    const pathname = path.split(/[?#]/, 1)[0];\n    if (!allowed(pathname)) {\n      console.warn(\n        `[ngx-json-render] Refused to navigate to \"${path}\": \"${pathname}\" is not in the allow list given to injectRouterNavigate.`,\n      );\n      return;\n    }\n    router.navigateByUrl(path).catch((error: unknown) => {\n      console.warn(`[ngx-json-render] Navigation to \"${path}\" failed.`, error);\n    });\n  };\n}\n\nfunction isAppPath(path: unknown): path is string {\n  return (\n    typeof path === 'string' &&\n    /^\\/(?![/\\\\])/.test(path) &&\n    !/[\\\\\\u0000-\\u001f\\u007f]/.test(path)\n  );\n}\n\nfunction toPredicate(\n  allow: RouterNavigateOptions['allow'],\n): (path: string) => boolean {\n  if (typeof allow === 'function') return allow;\n  return (path) =>\n    allow.some((rule) => {\n      if (typeof rule === 'string') return rule === path;\n      // A global or sticky RegExp keeps `lastIndex` between calls; reset it so\n      // one rule answers the same way for the same path every time.\n      rule.lastIndex = 0;\n      return rule.test(path);\n    });\n}\n","/*\n * Public API Surface of ngx-json-render/router\n */\n\nexport {\n  injectRouterNavigate,\n  type RouterNavigateOptions,\n} from './router-navigate';\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":";;;AAiBA;;;;;;;;;;;;;;;;;;;;;AAqBG;AACG,SAAU,oBAAoB,CAClC,OAA8B,EAAA;AAE9B,IAAA,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC;IAC1C,OAAO,CAAC,IAAI,KAAI;AACd,QAAA,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE;AACpB,YAAA,OAAO,CAAC,IAAI,CACV,CAAA,yCAAA,EAA4C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA,gFAAA,CAAkF,CACnJ;YACD;QACF;AACA,QAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AACzC,QAAA,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE;YACtB,OAAO,CAAC,IAAI,CACV,CAAA,0CAAA,EAA6C,IAAI,CAAA,IAAA,EAAO,QAAQ,CAAA,yDAAA,CAA2D,CAC5H;YACD;QACF;QACA,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,KAAI;YAClD,OAAO,CAAC,IAAI,CAAC,CAAA,iCAAA,EAAoC,IAAI,CAAA,SAAA,CAAW,EAAE,KAAK,CAAC;AAC1E,QAAA,CAAC,CAAC;AACJ,IAAA,CAAC;AACH;AAEA,SAAS,SAAS,CAAC,IAAa,EAAA;AAC9B,IAAA,QACE,OAAO,IAAI,KAAK,QAAQ;AACxB,QAAA,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC;AACzB,QAAA,CAAC,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC;AAEzC;AAEA,SAAS,WAAW,CAClB,KAAqC,EAAA;IAErC,IAAI,OAAO,KAAK,KAAK,UAAU;AAAE,QAAA,OAAO,KAAK;AAC7C,IAAA,OAAO,CAAC,IAAI,KACV,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,KAAI;QAClB,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,KAAK,IAAI;;;AAGlD,QAAA,IAAI,CAAC,SAAS,GAAG,CAAC;AAClB,QAAA,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AACxB,IAAA,CAAC,CAAC;AACN;;ACpFA;;AAEG;;ACFH;;AAEG;;"}