ngx-json-render 0.8.2 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-json-render",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Angular renderer for json-render — stream AI-generated JSON specs into real Angular components with signals.",
   "keywords": [
     "angular",
@@ -28,7 +28,8 @@
     "zod": "^4.0.0",
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@json-render/devtools": ">=0.20.0 <0.22.0"
+    "@json-render/devtools": ">=0.20.0 <0.22.0",
+    "@angular/router": ">=19.0.0"
   },
   "peerDependenciesMeta": {
     "@modelcontextprotocol/ext-apps": {
@@ -39,6 +40,9 @@
     },
     "@json-render/devtools": {
       "optional": true
+    },
+    "@angular/router": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -67,6 +71,10 @@
       "types": "./types/ngx-json-render-mcp.d.ts",
       "default": "./fesm2022/ngx-json-render-mcp.mjs"
     },
+    "./router": {
+      "types": "./types/ngx-json-render-router.d.ts",
+      "default": "./fesm2022/ngx-json-render-router.mjs"
+    },
     "./schema": {
       "types": "./types/ngx-json-render-schema.d.ts",
       "default": "./fesm2022/ngx-json-render-schema.mjs"

package/types/ngx-json-render-router.d.ts

@@ -0,0 +1,39 @@
+/** Which paths a spec may send the app to. */
+interface RouterNavigateOptions {
+    /**
+     * The paths a spec may navigate to. A string must equal the path exactly; a
+     * `RegExp` is tested against it; a function decides on its own. The path is
+     * what comes before any `?` or `#`, so a query string or fragment neither
+     * helps nor hurts a match, and is passed on to the router as written.
+     *
+     * Required: a spec is model output, and the app is what knows which of its
+     * routes a generated UI has any business opening.
+     */
+    readonly allow: readonly (string | RegExp)[] | ((path: string) => boolean);
+}
+/**
+ * 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`.
+ */
+declare function injectRouterNavigate(options: RouterNavigateOptions): (path: string) => void;
+
+export { injectRouterNavigate };
+export type { RouterNavigateOptions };

package/types/ngx-json-render.d.ts

@@ -2,7 +2,7 @@ import * as _json_render_core from '@json-render/core';
 import { ResolvedAction, ActionHandler, ActionBinding, SpecIssue, Spec, Catalog, InferCatalogActions, InferActionParams, StateModel, InferCatalogComponents, UIElement, StateStore, ValidationFunction, ComputedFunction, DirectiveDefinition, ActionConfirm, DirectiveRegistry, ValidationResult, ValidationConfig, JsonPatch, FlatElement } from '@json-render/core';
 export { ActionBinding, ActionHandler, InferActionParams, InferCatalogComponents, InferComponentProps, JsonPatch, Spec, SpecIssue, StateModel, StateStore, UIElement, VisibilityCondition, autoFixSpec, createStateStore, formatSpecIssues, nestedToFlat, validateSpec } from '@json-render/core';
 import * as _angular_core from '@angular/core';
-import { Signal, Type, Injector, InjectionToken } from '@angular/core';
+import { Signal, Type, Injector, InjectionToken, Provider } from '@angular/core';
 import * as ngx_json_render from 'ngx-json-render';
 export { AngularSchema, AngularSpec, schema } from 'ngx-json-render/schema';
 
@@ -319,6 +319,14 @@ interface RegistryEntry {
     component: Type<unknown>;
     /** Slot names this component supports (from the catalog definition). */
     slots?: string[];
+    /**
+     * Shown instead of `component` while the spec streams and this element's
+     * props do not yet pass its component's schema in the renderer's
+     * `catalog`. It gets the same render context, so it can read the props
+     * that have arrived and place `<jr-children />`. Without one, the element
+     * renders nothing until it is ready.
+     */
+    fallback?: Type<unknown>;
 }
 /**
  * Registry of component renderers: catalog type name → Angular component
@@ -327,10 +335,11 @@ interface RegistryEntry {
 type ComponentRegistry = Record<string, Type<unknown> | RegistryEntry>;
 /**
  * Registry of all Angular components for a catalog. Keys are checked against
- * the catalog's component names.
+ * the catalog's component names. A value is the component, or the component
+ * with a {@link RegistryEntry.fallback} to show while its props stream in.
  */
 type Components<C extends Catalog> = {
-    [K in keyof InferCatalogComponents<C>]: Type<unknown>;
+    [K in keyof InferCatalogComponents<C>]: Type<unknown> | Pick<RegistryEntry, 'component' | 'fallback'>;
 };
 /**
  * The repeat scope available to elements rendered inside a `repeat` block.
@@ -469,8 +478,11 @@ declare function injectBoundProp<T>(propValue: () => T | undefined, bindingPath:
 declare class JsonRenderer {
     /** The UI spec to render (may be partial while streaming). */
     readonly spec: _angular_core.InputSignal<Spec | null>;
-    /** Component registry mapping catalog type names to Angular components. */
-    readonly registry: _angular_core.InputSignal<ComponentRegistry>;
+    /**
+     * Component registry mapping catalog type names to Angular components.
+     * Required unless a {@link provideJsonRender} above supplies one.
+     */
+    readonly registry: _angular_core.InputSignal<ComponentRegistry | undefined>;
     /** Whether the spec is currently loading/streaming. */
     readonly loading: _angular_core.InputSignal<boolean>;
     /** Fallback component for unknown types. */
@@ -487,7 +499,7 @@ declare class JsonRenderer {
      * The check is skipped while `loading` is true: a spec that is still
      * arriving is expected to reference children that have not streamed in yet.
      */
-    readonly validate: _angular_core.InputSignal<SpecValidationMode>;
+    readonly validate: _angular_core.InputSignal<SpecValidationMode | undefined>;
     /**
      * Caps on what the spec may cost the browser: `maxElements`, `maxDepth` and
      * `maxRepeatItems`. Unset by default, and each field is independently
@@ -509,8 +521,14 @@ declare class JsonRenderer {
      * `$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`.
+     * The check is read only when `validate` is on, and — like the rest of
+     * it — skipped while `loading`.
+     *
+     * While `loading`, the catalog also gates mounting, whatever `validate` is:
+     * an element whose props do not yet pass its component's schema shows its
+     * registry entry's `fallback`, or nothing, instead of a component with half
+     * its props. Once an element has mounted it stays mounted, and when
+     * `loading` ends every element mounts.
      */
     readonly catalog: _angular_core.InputSignal<SpecCatalog | null>;
     /**
@@ -538,6 +556,15 @@ declare class JsonRenderer {
     readonly stateStore: JsonRenderStateService;
     /** The action dispatcher of this renderer. */
     protected readonly actions: JsonRenderActionsService;
+    /**
+     * The nearest {@link provideJsonRender}'s defaults. Every option input
+     * falls through to these when left `null` or `undefined`; see
+     * {@link JsonRenderConfig} for the merge rules.
+     */
+    private readonly config;
+    private readonly mode;
+    private readonly limits;
+    private readonly specCatalog;
     /**
      * The spec as checked, and what the check found. While `loading`, the mode
      * is forced off: the spec is still arriving, and the missing children it
@@ -562,7 +589,7 @@ declare class JsonRenderer {
      */
     protected readonly confirmInjector: _angular_core.Signal<Injector | null>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<JsonRenderer, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<JsonRenderer, "json-render", never, { "spec": { "alias": "spec"; "required": true; "isSignal": true; }; "registry": { "alias": "registry"; "required": true; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "fallback": { "alias": "fallback"; "required": false; "isSignal": true; }; "validate": { "alias": "validate"; "required": false; "isSignal": true; }; "renderLimits": { "alias": "renderLimits"; "required": false; "isSignal": true; }; "catalog": { "alias": "catalog"; "required": false; "isSignal": true; }; "state": { "alias": "state"; "required": false; "isSignal": true; }; "store": { "alias": "store"; "required": false; "isSignal": true; }; "handlers": { "alias": "handlers"; "required": false; "isSignal": true; }; "onAction": { "alias": "onAction"; "required": false; "isSignal": true; }; "navigate": { "alias": "navigate"; "required": false; "isSignal": true; }; "validationFunctions": { "alias": "validationFunctions"; "required": false; "isSignal": true; }; "functions": { "alias": "functions"; "required": false; "isSignal": true; }; "directives": { "alias": "directives"; "required": false; "isSignal": true; }; }, { "stateChange": "stateChange"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<JsonRenderer, "json-render", never, { "spec": { "alias": "spec"; "required": true; "isSignal": true; }; "registry": { "alias": "registry"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "fallback": { "alias": "fallback"; "required": false; "isSignal": true; }; "validate": { "alias": "validate"; "required": false; "isSignal": true; }; "renderLimits": { "alias": "renderLimits"; "required": false; "isSignal": true; }; "catalog": { "alias": "catalog"; "required": false; "isSignal": true; }; "state": { "alias": "state"; "required": false; "isSignal": true; }; "store": { "alias": "store"; "required": false; "isSignal": true; }; "handlers": { "alias": "handlers"; "required": false; "isSignal": true; }; "onAction": { "alias": "onAction"; "required": false; "isSignal": true; }; "navigate": { "alias": "navigate"; "required": false; "isSignal": true; }; "validationFunctions": { "alias": "validationFunctions"; "required": false; "isSignal": true; }; "functions": { "alias": "functions"; "required": false; "isSignal": true; }; "directives": { "alias": "directives"; "required": false; "isSignal": true; }; }, { "stateChange": "stateChange"; }, never, never, true, never>;
 }
 
 /**
@@ -700,6 +727,21 @@ declare class JrElement {
     /** Two-way binding paths ($bindState / $bindItem) by prop name. */
     readonly bindings: Signal<Record<string, string> | undefined>;
     private readonly entry;
+    /** Set once the real component has been shown; see {@link held}. */
+    private mounted;
+    /**
+     * Whether the component waits for its props: the spec is still loading, a
+     * catalog was given, and the props written so far do not pass the
+     * component's schema (see {@link propsArrived}).
+     *
+     * One-way. Once the component has been shown it is never swapped back for
+     * the fallback, even if a later patch takes a prop away again: a component
+     * flickering out mid-stream is worse than one showing a gap. Once latched
+     * this reads no signals, so a mounted element pays nothing for the gate on
+     * later patches — and neither does any element when nothing is loading.
+     */
+    protected readonly held: Signal<boolean>;
+    /** What the outlet shows: the component, or its fallback while held. */
     protected readonly component: Signal<_angular_core.Type<unknown> | null>;
     protected readonly devtoolsKey: Signal<string | null>;
     /**
@@ -858,6 +900,62 @@ declare const JR_CONFIRM_DIALOG: InjectionToken<Type<unknown>>;
 /** Inject the confirmation a replacement dialog component is rendering for. */
 declare function injectConfirmContext(): ConfirmContext;
 
+/**
+ * Renderer defaults for every `<json-render>` below a provider: each field is
+ * the input of the same name.
+ *
+ * An input bound on the element wins over the provided value, and a value
+ * left `null` or `undefined` on the element falls through to it. Named
+ * vocabularies — `handlers`, `functions`, `validationFunctions` and
+ * `directives` — merge by name instead, the element's entry winning a name
+ * both define. Everything else replaces: a `registry` belongs to its catalog,
+ * so two are never mixed behind your back (spread them yourself to combine).
+ */
+interface JsonRenderConfig {
+    registry?: ComponentRegistry;
+    fallback?: Type<unknown> | RegistryEntry | null;
+    validate?: SpecValidationMode;
+    renderLimits?: RenderLimits | null;
+    catalog?: SpecCatalog | null;
+    handlers?: Record<string, ActionHandler>;
+    onAction?: ((name: string, params?: Record<string, unknown>) => unknown) | null;
+    navigate?: ((path: string) => void) | null;
+    validationFunctions?: Record<string, ValidationFunction>;
+    functions?: Record<string, ComputedFunction>;
+    directives?: DirectiveDefinition<any>[];
+}
+/**
+ * The defaults the nearest {@link provideJsonRender} supplies, already merged
+ * with any provider above it.
+ */
+declare const JSON_RENDER_CONFIG: InjectionToken<JsonRenderConfig>;
+/**
+ * Set renderer defaults once instead of on every `<json-render>`:
+ *
+ * ```ts
+ * bootstrapApplication(App, { providers: [provideJsonRender({ registry })] });
+ * ```
+ *
+ * ```html
+ * <json-render [spec]="m.spec" />
+ * ```
+ *
+ * Pass a function to build the defaults with `inject()`, for handlers that
+ * call your services:
+ *
+ * ```ts
+ * provideJsonRender(() => {
+ *   const orders = inject(OrderService);
+ *   return { registry, handlers: { cancelOrder: (p) => orders.cancel(p['id']) } };
+ * });
+ * ```
+ *
+ * Works in application, route and component `providers`. A provider below
+ * another extends it with the same rules an element input does: its own
+ * values replace, its named vocabularies merge.
+ */
+declare function provideJsonRender(config: JsonRenderConfig | (() => JsonRenderConfig)): Provider[];
+
 /**
  * The render context of the element currently being rendered.
  * Provided by the renderer for every catalog component instance.
@@ -926,6 +1024,11 @@ declare class JsonRenderRootContext {
      * they apply whatever `validate` is set to.
      */
     limits: Signal<RenderLimits | null | undefined>;
+    /**
+     * The catalog the spec was generated for. While loading, an element whose
+     * props do not pass its component's schema waits for them.
+     */
+    catalog: Signal<SpecCatalog | null | undefined>;
     /** External store (controlled mode). */
     store: Signal<StateStore | null | undefined>;
     /** Initial state (uncontrolled mode); falls back to `spec.state`. */
@@ -1382,5 +1485,5 @@ declare function injectChatUI(options: ChatUIOptions): ChatUIReturn;
  */
 declare function injectDevtoolsActive(): Signal<boolean>;
 
-export { CONFIRM_CONTEXT, ELEMENT_KEY, JR_CONFIRM_DIALOG, JR_CONFIRM_LABELS, JrChildren, JrConfirmDialog, JrElement, JrRepeatScope, JsonRenderActionsService, JsonRenderRootContext, JsonRenderStateService, JsonRenderValidationService, JsonRenderer, RENDER_CONTEXT, REPEAT_SCOPE, applyPatch, buildSpecFromParts, checkSpec, createStoreSetState, defineRegistry, flatToTree, formatSpecCheckIssues, getTextFromParts, injectAction, injectActions, injectBoundProp, injectChatUI, injectConfirmContext, injectDevtoolsActive, injectElementKey, injectFieldValidation, injectRenderContext, injectRepeatScope, injectStateBinding, injectStateStore, injectStateValue, injectUIStream, injectValidation, isActionCancelled, jsonRenderMessage, ɵregisterStreamObserver };
-export type { ActionFn, Actions, CatalogHasActions, ChatMessage, ChatUIOptions, ChatUIReturn, ComponentRegistry, Components, ConfirmContext, ConfirmLabels, DataPart, DefineRegistryResult, EventHandle, FieldValidationState, PendingConfirmation, RegistryEntry, RenderContext, RenderLimits, RepeatScope, SetState, SpecCatalog, SpecCheck, SpecCheckIssue, SpecCheckIssueCode, SpecCheckOptions, SpecValidationMode, StateChange, StreamObserver, StreamObserverUsage, TokenUsage, UIStreamOptions, UIStreamReturn, UIStreamSendOptions };
+export { CONFIRM_CONTEXT, ELEMENT_KEY, JR_CONFIRM_DIALOG, JR_CONFIRM_LABELS, JSON_RENDER_CONFIG, JrChildren, JrConfirmDialog, JrElement, JrRepeatScope, JsonRenderActionsService, JsonRenderRootContext, JsonRenderStateService, JsonRenderValidationService, JsonRenderer, RENDER_CONTEXT, REPEAT_SCOPE, applyPatch, buildSpecFromParts, checkSpec, createStoreSetState, defineRegistry, flatToTree, formatSpecCheckIssues, getTextFromParts, injectAction, injectActions, injectBoundProp, injectChatUI, injectConfirmContext, injectDevtoolsActive, injectElementKey, injectFieldValidation, injectRenderContext, injectRepeatScope, injectStateBinding, injectStateStore, injectStateValue, injectUIStream, injectValidation, isActionCancelled, jsonRenderMessage, provideJsonRender, ɵregisterStreamObserver };
+export type { ActionFn, Actions, CatalogHasActions, ChatMessage, ChatUIOptions, ChatUIReturn, ComponentRegistry, Components, ConfirmContext, ConfirmLabels, DataPart, DefineRegistryResult, EventHandle, FieldValidationState, JsonRenderConfig, PendingConfirmation, RegistryEntry, RenderContext, RenderLimits, RepeatScope, SetState, SpecCatalog, SpecCheck, SpecCheckIssue, SpecCheckIssueCode, SpecCheckOptions, SpecValidationMode, StateChange, StreamObserver, StreamObserverUsage, TokenUsage, UIStreamOptions, UIStreamReturn, UIStreamSendOptions };