ngx-json-render 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-json-render",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Angular renderer for json-render — stream AI-generated JSON specs into real Angular components with signals.",
   "keywords": [
     "angular",

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

@@ -1,5 +1,5 @@
 import * as _json_render_core from '@json-render/core';
-import { ResolvedAction, ActionHandler, ActionBinding, Spec, SpecIssue, Catalog, InferCatalogActions, InferActionParams, StateModel, InferCatalogComponents, UIElement, StateStore, ValidationFunction, ComputedFunction, DirectiveDefinition, ActionConfirm, DirectiveRegistry, ValidationResult, ValidationConfig, JsonPatch, FlatElement } 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, JsonPatch, Spec, SpecIssue, StateModel, StateStore, UIElement, VisibilityCondition, autoFixSpec, createStateStore, formatSpecIssues, nestedToFlat, validateSpec } from '@json-render/core';
 import * as zod from 'zod';
 import * as zod_v4_core from 'zod/v4/core';
@@ -69,6 +69,93 @@ declare function injectAction(binding: ActionBinding): {
     isLoading: Signal<boolean>;
 };
 
+/**
+ * Caps on what a spec is allowed to cost the browser.
+ *
+ * A spec is attacker-shaped input: whatever produced one chose its own size,
+ * its own nesting and — through `repeat` — its own array lengths. These are
+ * the three of those the renderer can enforce for you.
+ *
+ * Every field is opt-in and unset means unlimited. There are no defaults
+ * because no single number is right for every catalog, and a default would
+ * change what an existing app renders the moment it upgraded.
+ *
+ * Limits are enforced whenever they are set, whatever `validate` is: a number
+ * the app chose is a control, not advice. What "enforced" means differs by
+ * limit, because the limits differ in kind — see each field.
+ *
+ * @example
+ * ```html
+ * <json-render
+ *   [spec]="spec()"
+ *   [registry]="registry"
+ *   [renderLimits]="{ maxElements: 500, maxDepth: 16, maxRepeatItems: 200 }"
+ * />
+ * ```
+ */
+interface RenderLimits {
+    /**
+     * Most elements a spec may contain. A spec over the cap does not render at
+     * all: element count is a property of the whole spec, and there is no
+     * meaningful "first 500 elements" of a graph.
+     */
+    readonly maxElements?: number;
+    /**
+     * Deepest the render tree may nest, counting the root as 1. An element
+     * below the cap does not render, and neither does anything under it; what
+     * fits still renders. Reported as an error, so `validate="strict"` refuses
+     * the spec outright rather than truncating it.
+     *
+     * A capped element does not act either — its `watch` stays unwired, so it
+     * cannot dispatch actions from behind the cap.
+     */
+    readonly maxDepth?: number;
+    /**
+     * Most items one `repeat` may expand. The surplus items do not render.
+     *
+     * Enforced at render time only: `repeat` iterates a live state array, so no
+     * amount of inspecting the spec can predict how long it will be. Nested
+     * repeats multiply, so this is a per-repeat cap, not a total.
+     */
+    readonly maxRepeatItems?: number;
+}
+/**
+ * Issue codes this package reports, widening core's set with the ones only a
+ * renderer can find.
+ *
+ * - `cycle` — an element renders itself against the same data, which cannot
+ *   terminate. A tree that recurses into its items is not this.
+ * - `too_deep` / `too_many_elements` — a {@link RenderLimits} cap was passed.
+ * - `unknown_component` — a `type` the catalog does not define.
+ * - `invalid_props` — the catalog's own schema rejected part of the spec.
+ */
+type SpecCheckIssueCode = SpecIssue['code'] | 'cycle' | 'too_deep' | 'too_many_elements' | 'unknown_component' | 'invalid_props';
+/**
+ * A problem found in a spec. Core's {@link SpecIssue} widened with the codes
+ * above, so a {@link SpecIssue} is always one of these.
+ */
+interface SpecCheckIssue {
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly elementKey?: string;
+    readonly code: SpecCheckIssueCode;
+}
+/**
+ * The part of a json-render `Catalog` the check needs.
+ *
+ * Structural on purpose: a real catalog satisfies it, and the renderer stays
+ * free of any dependency on the schema library behind `validate`.
+ */
+interface SpecCatalog {
+    /** Component type names the catalog defines. */
+    readonly componentNames: readonly string[];
+    /** Check a spec against the catalog's own schema. */
+    validate(spec: unknown): {
+        readonly success: boolean;
+        readonly error?: unknown;
+    };
+}
+
 /**
  * How much a spec has to be trusted.
  *
@@ -77,8 +164,24 @@ declare function injectAction(binding: ActionBinding): {
  * - `warn` — check the spec, apply the lossless fixes, report what is left,
  *   render it anyway.
  * - `strict` — the same check, but an error means the spec does not render.
+ *
+ * This governs *reporting* and strict refusal. {@link RenderLimits} are a
+ * separate axis: a limit the app set is enforced in every mode, including
+ * `off`.
  */
 type SpecValidationMode = 'off' | 'warn' | 'strict';
+/** Everything {@link checkSpec} needs beyond the spec and the mode. */
+interface SpecCheckOptions {
+    /** Caps on the spec's size, enforced whatever the mode. */
+    readonly limits?: RenderLimits | null;
+    /**
+     * The catalog the spec was generated for. Given one, the check also reports
+     * component types the catalog does not define and props its own schema
+     * rejects — the half of "is this spec renderable" that structure alone
+     * cannot answer.
+     */
+    readonly catalog?: SpecCatalog | null;
+}
 /** What {@link checkSpec} found, and the spec that should render. */
 interface SpecCheck {
     /**
@@ -86,23 +189,41 @@ interface SpecCheck {
      * untouched when validation is off.
      */
     readonly spec: Spec | null;
-    /** Structural issues left after the fixes. */
-    readonly issues: readonly SpecIssue[];
+    /** Structural, limit and catalog issues left after the fixes. */
+    readonly issues: readonly SpecCheckIssue[];
     /** Descriptions of the fixes that were applied. */
     readonly fixes: readonly string[];
     /** Whether an issue of `error` severity survived. */
     readonly hasErrors: boolean;
+    /**
+     * Whether the spec is refused outright, in every mode, for breaching an
+     * enforced limit. Distinct from {@link hasErrors}, which only stops a spec
+     * under `strict`.
+     */
+    readonly blocked: boolean;
 }
 /**
- * Check a spec the way `validate` asks for.
+ * Check a spec the way `validate` and `renderLimits` ask for.
  *
  * Only lossless fixes are applied — `visible`, `on` and `repeat` that a model
  * put inside `props`, which the renderer would otherwise ignore, moved back
  * where they belong. The lossy ones prune content, and core's own guidance is
  * to re-prompt rather than accept that; a renderer that silently deleted
  * elements would be the worse failure.
+ *
+ * Note what is *not* here: cycles are broken as the tree renders, whatever
+ * this returns, because a spec that never stops rendering is a crash rather
+ * than an opinion about quality. This reports them so an app can see them.
  */
-declare function checkSpec(spec: Spec | null, mode: SpecValidationMode): SpecCheck;
+declare function checkSpec(spec: Spec | null, mode: SpecValidationMode, options?: SpecCheckOptions): SpecCheck;
+/**
+ * Render issues as one indented block, errors and warnings alike.
+ *
+ * Core's `formatSpecIssues` drops warnings and only accepts core's own issue
+ * codes, so it cannot describe what this package reports. Use this instead
+ * when showing `issues()` to a developer.
+ */
+declare function formatSpecCheckIssues(issues: readonly SpecCheckIssue[]): string;
 
 /**
  * State setter function for updating application state.
@@ -341,6 +462,27 @@ declare class JsonRenderer {
      * arriving is expected to reference children that have not streamed in yet.
      */
     readonly validate: _angular_core.InputSignal<SpecValidationMode>;
+    /**
+     * Caps on what the spec may cost the browser: `maxElements`, `maxDepth` and
+     * `maxRepeatItems`. Unset by default, and each field is independently
+     * optional.
+     *
+     * Unlike `validate`, these are enforced in every mode — a number the app
+     * chose is a control, not a report. A spec over `maxElements` renders
+     * nothing; `maxDepth` and `maxRepeatItems` truncate where they are hit.
+     * They apply while `loading` too: a partial spec is a subset of the
+     * finished one, so a cap can only ever fire early, never falsely.
+     */
+    readonly renderLimits: _angular_core.InputSignal<RenderLimits | null>;
+    /**
+     * The catalog the spec was generated for. Given one, `validate` also checks
+     * what structure alone cannot: that every `type` is a component the catalog
+     * defines, and that the props match its schema.
+     *
+     * Only read when `validate` is on, and — like the rest of the check —
+     * skipped while `loading`.
+     */
+    readonly catalog: _angular_core.InputSignal<SpecCatalog | null>;
     /**
      * Initial state model (uncontrolled mode). Defaults to `spec.state`.
      * Ignored when `store` is provided.
@@ -390,7 +532,7 @@ declare class JsonRenderer {
      */
     protected readonly confirmInjector: _angular_core.Signal<_angular_core.DestroyableInjector | 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; }; "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": 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>;
 }
 
 /**
@@ -424,6 +566,16 @@ declare class JrChildren {
         key?: string;
     } | undefined>;
     private readonly repeatBasePath;
+    /** Every item the repeat's state array holds, before any cap. */
+    private readonly allRepeatItems;
+    /**
+     * The items this repeat actually renders.
+     *
+     * `repeat` iterates a state array the spec may itself have supplied, which
+     * is the one place a spec sizes the render tree out of data rather than out
+     * of its own structure — so the cap has to be applied here, as it expands,
+     * rather than anywhere a spec can be inspected up front.
+     */
     protected readonly repeatItems: _angular_core.Signal<unknown[]>;
     constructor();
     protected itemPath(index: number): string;
@@ -445,6 +597,7 @@ declare class JrElement {
     private readonly state;
     private readonly actions;
     private readonly repeatScope;
+    private readonly parentPath;
     private readonly devtoolsActive;
     /** The raw (unresolved) element from the spec. */
     readonly rawElement: Signal<UIElement<string, Record<string, unknown>> | undefined>;
@@ -458,6 +611,23 @@ declare class JrElement {
     private readonly entry;
     protected readonly component: Signal<_angular_core.Type<unknown> | null>;
     protected readonly devtoolsKey: Signal<string | null>;
+    /**
+     * Where this element sits in the tree. Passed down to everything it renders
+     * below itself, which is what lets each element see its own ancestry
+     * without the renderer holding a registry of who is drawing what.
+     */
+    private readonly path;
+    /**
+     * Why this element is not drawn, or null when it is.
+     *
+     * The cycle half is unconditional — not something `validate` turns on. An
+     * element that renders itself without reading any deeper renders forever,
+     * and a spec that never stops rendering takes the tab with it; refusing to
+     * draw the repetition is the only outcome that leaves anything on screen.
+     * It costs one walk up a chain of parents, bounded by `maxDepth` where one
+     * is set and by the spec's own nesting where it is not.
+     */
+    protected readonly refusal: Signal<"cycle" | "depth" | null>;
     private readonly renderCtx;
     protected readonly outletInjector: _angular_core.DestroyableInjector;
     constructor();
@@ -646,6 +816,11 @@ declare class JsonRenderRootContext {
     registry: Signal<ComponentRegistry | undefined>;
     loading: Signal<boolean>;
     fallback: Signal<Type<unknown> | RegistryEntry | null | undefined>;
+    /**
+     * Caps on what the spec may cost the browser. Read as the tree renders, so
+     * they apply whatever `validate` is set to.
+     */
+    limits: Signal<RenderLimits | null | undefined>;
     /** External store (controlled mode). */
     store: Signal<StateStore | null | undefined>;
     /** Initial state (uncontrolled mode); falls back to `spec.state`. */
@@ -901,6 +1076,18 @@ interface UIStreamOptions {
      * spec there does not persist a broken one.
      */
     validate?: SpecValidationMode;
+    /**
+     * Caps on what the finished spec may cost the browser. Enforced whatever
+     * `validate` is: a spec over `maxElements` fails the generation rather than
+     * reaching `onComplete`.
+     */
+    renderLimits?: RenderLimits | null;
+    /**
+     * The catalog the spec was generated for. Given one, `validate` also checks
+     * every element `type` against the catalog and the props against its
+     * schema — the half a structural check cannot see.
+     */
+    catalog?: SpecCatalog | null;
     /**
      * Transport, defaulting to the global `fetch`.
      *
@@ -928,10 +1115,12 @@ interface UIStreamReturn {
     /** Raw JSONL lines received from the stream (JSON patch lines) */
     readonly rawLines: Signal<string[]>;
     /**
-     * Structural issues in the finished spec. Empty until a generation
-     * completes, and always empty while `validate` is off.
+     * What the check found in the finished spec — structure, catalog and
+     * limits alike. Empty until a generation completes; empty while `validate`
+     * is off unless a `renderLimits` cap was passed, since those are enforced
+     * in every mode.
      */
-    readonly issues: Signal<readonly SpecIssue[]>;
+    readonly issues: Signal<readonly SpecCheckIssue[]>;
     /** Send a prompt to generate UI */
     send: (prompt: string, options?: UIStreamSendOptions) => Promise<void>;
     /**
@@ -998,6 +1187,18 @@ interface ChatUIOptions {
      * reply that produced a spec.
      */
     validate?: SpecValidationMode;
+    /**
+     * Caps on what the finished spec may cost the browser. Enforced whatever
+     * `validate` is: a spec over `maxElements` fails the generation rather than
+     * reaching `onComplete`.
+     */
+    renderLimits?: RenderLimits | null;
+    /**
+     * The catalog the spec was generated for. Given one, `validate` also checks
+     * every element `type` against the catalog and the props against its
+     * schema — the half a structural check cannot see.
+     */
+    catalog?: SpecCatalog | null;
 }
 /**
  * Return type for {@link injectChatUI}.
@@ -1010,10 +1211,12 @@ interface ChatUIReturn {
     /** Error from the last request, if any */
     readonly error: Signal<Error | null>;
     /**
-     * Structural issues in the spec of the last completed reply. Empty until a
-     * reply completes, and always empty while `validate` is off.
+     * What the check found in the last completed reply's spec — structure,
+     * catalog and limits alike. Empty until a reply completes; empty while
+     * `validate` is off unless a `renderLimits` cap was passed, since those are
+     * enforced in every mode.
      */
-    readonly issues: Signal<readonly SpecIssue[]>;
+    readonly issues: Signal<readonly SpecCheckIssue[]>;
     /** Send a user message */
     send: (text: string) => Promise<void>;
     /**
@@ -1110,5 +1313,5 @@ type AngularSpec<TCatalog> = typeof schema extends {
  */
 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, getTextFromParts, injectAction, injectActions, injectBoundProp, injectChatUI, injectConfirmContext, injectDevtoolsActive, injectElementKey, injectFieldValidation, injectRenderContext, injectRepeatScope, injectStateBinding, injectStateStore, injectStateValue, injectUIStream, injectValidation, isActionCancelled, jsonRenderMessage, schema };
-export type { ActionFn, Actions, AngularSchema, AngularSpec, CatalogHasActions, ChatMessage, ChatUIOptions, ChatUIReturn, ComponentRegistry, Components, ConfirmContext, ConfirmLabels, DataPart, DefineRegistryResult, EventHandle, FieldValidationState, PendingConfirmation, RegistryEntry, RenderContext, RepeatScope, SetState, SpecCheck, SpecValidationMode, StateChange, TokenUsage, UIStreamOptions, UIStreamReturn, UIStreamSendOptions };
+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, schema };
+export type { ActionFn, Actions, AngularSchema, AngularSpec, 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, TokenUsage, UIStreamOptions, UIStreamReturn, UIStreamSendOptions };