ngx-json-render 0.9.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-json-render",
-  "version": "0.9.0",
+  "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';
 
@@ -478,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. */
@@ -496,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
@@ -553,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
@@ -577,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>;
 }
 
 /**
@@ -888,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.
@@ -1417,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 };