ngx-json-render 0.3.0 → 0.5.0

package/fesm2022/ngx-json-render.mjs

@@ -1,7 +1,7 @@
 import { NgComponentOutlet } from '@angular/common';
 import * as i0 from '@angular/core';
 import { signal, Injectable, inject, computed, untracked, effect, isDevMode, DestroyRef, InjectionToken, input, output, viewChild, afterNextRender, ChangeDetectionStrategy, Component, Injector, forwardRef } from '@angular/core';
-import { createStateStore, getByPath, runValidation, resolveAction, nextActionDispatchId, notifyActionDispatch, notifyActionSettle, executeAction, isDevtoolsActive, subscribeDevtoolsActive, evaluateVisibility, resolveElementProps, resolveBindings, resolveActionParam, autoFixSpec, validateSpec, formatSpecIssues, createDirectiveRegistry, resolveRepeatStatePath, resolveRepeatItemStatePath, removeByPath, addByPath, setByPath, SPEC_DATA_PART_TYPE, nestedToFlat, createMixedStreamParser, defineSchema } from '@json-render/core';
+import { createStateStore, getByPath, runValidation, resolveAction, nextActionDispatchId, notifyActionDispatch, notifyActionSettle, executeAction, isDevtoolsActive, subscribeDevtoolsActive, evaluateVisibility, resolveElementProps, resolveBindings, resolveActionParam, autoFixSpec, validateSpec, createDirectiveRegistry, resolveRepeatStatePath, resolveRepeatItemStatePath, removeByPath, addByPath, setByPath, SPEC_DATA_PART_TYPE, nestedToFlat, createMixedStreamParser, defineSchema } from '@json-render/core';
 export { autoFixSpec, createStateStore, formatSpecIssues, nestedToFlat, validateSpec } from '@json-render/core';
 import { flattenToPointers } from '@json-render/core/store-utils';
 
@@ -18,6 +18,11 @@ class JsonRenderRootContext {
     registry = EMPTY;
     loading = signal(false, ...(ngDevMode ? [{ debugName: "loading" }] : /* istanbul ignore next */ []));
     fallback = EMPTY;
+    /**
+     * Caps on what the spec may cost the browser. Read as the tree renders, so
+     * they apply whatever `validate` is set to.
+     */
+    limits = EMPTY;
     /** External store (controlled mode). */
     store = EMPTY;
     /** Initial state (uncontrolled mode); falls back to `spec.state`. */
@@ -977,6 +982,16 @@ const ELEMENT_KEY = new InjectionToken('ngx-json-render ELEMENT_KEY');
  * `repeat` block.
  */
 const REPEAT_SCOPE = new InjectionToken('ngx-json-render REPEAT_SCOPE');
+/**
+ * This element's position in the render tree. Provided by `<jr-element>` for
+ * everything it renders below itself, so each element can see its own depth
+ * and its own ancestry.
+ *
+ * @internal Not part of the public API: it exists so the renderer can refuse
+ * to draw an element that is its own ancestor, and to enforce
+ * `renderLimits.maxDepth`.
+ */
+const RENDER_PATH = new InjectionToken('ngx-json-render RENDER_PATH');
 /**
  * Inject the render context inside a catalog component.
  *
@@ -1037,6 +1052,53 @@ function reportActionError(error) {
         return;
     console.error(error);
 }
+/**
+ * Whether `inner` reads strictly deeper into state than `outer` — the state
+ * path of one repeat item nested inside another's.
+ *
+ * `null` is the world outside any repeat, so stepping into one is always
+ * progress. Below that it is a prefix test on the resolved path, and the
+ * trailing separator is what keeps `/tree/10` from counting as a step inside
+ * `/tree/1`.
+ */
+function descendsInto(outer, inner) {
+    if (inner === null)
+        return false;
+    if (outer === null)
+        return true;
+    return inner.startsWith(`${outer}/`);
+}
+/**
+ * Whether this element renders itself again without getting anywhere — the
+ * one arrangement that cannot terminate.
+ *
+ * An element reaching itself is not by itself a defect. It is how a tree gets
+ * drawn — a comment thread, a file browser, a nested menu — where each pass
+ * repeats over a path relative to the item it is already inside and so reads
+ * one level further into the data. That ends when the data does.
+ *
+ * What separates the two is whether the repeat descended. Compare against the
+ * nearest occurrence above: `/tree/0` then `/tree/0/children/1` is a tree
+ * walking down, while `/items/0` then `/items/1` is a spec repeating over a
+ * fixed array inside itself, and `/items/0` twice is one with no repeat
+ * between the passes at all. Only the first can run out.
+ */
+function repeatsItself(path) {
+    for (let step = path.parent; step !== null; step = step.parent) {
+        if (step.key !== path.key)
+            continue;
+        return !descendsInto(step.scopePath, path.scopePath);
+    }
+    return false;
+}
+/** The chain from the root down to `path`, as a line a human can follow. */
+function describePath(path) {
+    const keys = [];
+    for (let step = path; step !== null; step = step.parent) {
+        keys.push(step.key);
+    }
+    return keys.reverse().join(' \u2192 ');
+}
 /**
  * Renders a single spec element: evaluates visibility, resolves prop
  * expressions against the state model, wires event/watch bindings, and
@@ -1050,6 +1112,7 @@ class JrElement {
     state = inject(JsonRenderStateService);
     actions = inject(JsonRenderActionsService);
     repeatScope = inject(REPEAT_SCOPE, { optional: true });
+    parentPath = inject(RENDER_PATH, { optional: true });
     devtoolsActive = injectDevtoolsActive();
     /** The raw (unresolved) element from the spec. */
     rawElement = computed(() => this.root.spec()?.elements?.[this.elementKey()], ...(ngDevMode ? [{ debugName: "rawElement" }] : /* istanbul ignore next */ []));
@@ -1098,6 +1161,39 @@ class JrElement {
     }, ...(ngDevMode ? [{ debugName: "entry" }] : /* istanbul ignore next */ []));
     component = computed(() => this.entry()?.component ?? null, ...(ngDevMode ? [{ debugName: "component" }] : /* istanbul ignore next */ []));
     devtoolsKey = computed(() => this.devtoolsActive() ? this.elementKey() : null, ...(ngDevMode ? [{ debugName: "devtoolsKey" }] : /* istanbul ignore next */ []));
+    /**
+     * 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.
+     */
+    path = computed(() => {
+        const parent = this.parentPath?.() ?? null;
+        return {
+            key: this.elementKey(),
+            depth: (parent?.depth ?? 0) + 1,
+            scopePath: this.repeatScope?.basePath() ?? null,
+            parent,
+        };
+    }, ...(ngDevMode ? [{ debugName: "path" }] : /* istanbul ignore next */ []));
+    /**
+     * 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.
+     */
+    refusal = computed(() => {
+        const path = this.path();
+        if (repeatsItself(path))
+            return 'cycle';
+        const maxDepth = this.root.limits()?.maxDepth;
+        if (maxDepth !== undefined && path.depth > maxDepth)
+            return 'depth';
+        return null;
+    }, ...(ngDevMode ? [{ debugName: "refusal" }] : /* istanbul ignore next */ []));
     renderCtx = {
         element: this.resolvedElement,
         props: computed(() => this.resolvedElement()?.props ?? {}),
@@ -1119,10 +1215,28 @@ class JrElement {
         providers: [
             { provide: RENDER_CONTEXT, useValue: this.renderCtx },
             { provide: ELEMENT_KEY, useValue: this.elementKey },
+            { provide: RENDER_PATH, useValue: this.path },
         ],
         parent: inject(Injector),
     });
     constructor() {
+        // Warn (once) when this element is refused. Both reasons are silent
+        // failures on screen — something the spec asked for is missing — so
+        // neither should be silent in the console.
+        let warnedRefusal = false;
+        effect(() => {
+            const reason = this.refusal();
+            if (!reason || warnedRefusal)
+                return;
+            warnedRefusal = true;
+            const path = untracked(this.path);
+            if (reason === 'cycle') {
+                console.warn(`[ngx-json-render] Cycle in the spec: ${describePath(path)}. "${path.key}" renders itself again without reading any deeper into state${path.scopePath === null ? '' : ` (still at "${path.scopePath}")`}, so it never ends. It is not rendered again; everything above it still is. A tree that recurses needs a repeat with a relative statePath, like {"$item": "children"}.`);
+            }
+            else {
+                console.warn(`[ngx-json-render] renderLimits.maxDepth (${untracked(this.root.limits)?.maxDepth}) reached at ${describePath(path)}. "${path.key}" and anything below it do not render.`);
+            }
+        });
         // Warn (once per type) about unknown component types.
         const warnedTypes = new Set();
         effect(() => {
@@ -1155,6 +1269,14 @@ class JrElement {
         });
         // Watch effect: fire actions when watched state paths change.
         effect((onCleanup) => {
+            // A refused element does not act, not just draw nothing. `watch` is the
+            // one thing an element does without being on screen, so leaving it wired
+            // would let the element past `maxDepth` — or the one that closes a cycle
+            // — keep dispatching actions from behind a cap that was supposed to have
+            // stopped it. Reading the signal here also unwires it if the refusal
+            // arrives later, when the limits change.
+            if (this.refusal())
+                return;
             const watchConfig = this.rawElement()?.watch;
             if (!watchConfig)
                 return;
@@ -1168,21 +1290,8 @@ class JrElement {
                         if (!changedPaths.has(path))
                             continue;
                         const binding = watchConfig[path];
-                        if (!binding)
-                            continue;
-                        const bindings = Array.isArray(binding) ? binding : [binding];
-                        for (const b of bindings) {
-                            if (!b.params) {
-                                await this.actions.execute(b);
-                                continue;
-                            }
-                            const liveCtx = this.liveResolutionCtx();
-                            const resolved = {};
-                            for (const [key, val] of Object.entries(b.params)) {
-                                resolved[key] = resolveActionParam(val, liveCtx);
-                            }
-                            await this.actions.execute({ ...b, params: resolved });
-                        }
+                        if (binding)
+                            await this.dispatch(binding);
                     }
                 })().catch(reportActionError);
             });
@@ -1208,12 +1317,17 @@ class JrElement {
         this.emitEvent(eventName).catch(reportActionError);
     }
     async emitEvent(eventName) {
-        const el = untracked(this.rawElement);
-        const binding = el?.on?.[eventName];
-        if (!binding)
-            return;
-        const actionBindings = Array.isArray(binding) ? binding : [binding];
-        for (const b of actionBindings) {
+        const binding = untracked(this.rawElement)?.on?.[eventName];
+        if (binding)
+            await this.dispatch(binding);
+    }
+    /**
+     * Run an `on` or `watch` binding's actions in order. Params are resolved
+     * per action, just before it runs, so a `$state` read in a later action of
+     * the chain sees what an earlier one wrote.
+     */
+    async dispatch(binding) {
+        for (const b of Array.isArray(binding) ? binding : [binding]) {
             if (!b.params) {
                 await this.actions.execute(b);
                 continue;
@@ -1241,7 +1355,7 @@ class JrElement {
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: JrElement, deps: [], target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.22", type: JrElement, isStandalone: true, selector: "jr-element", inputs: { elementKey: { classPropertyName: "elementKey", publicName: "elementKey", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0, template: `
-    @if (rawElement() && visible() && component()) {
+    @if (!refusal() && rawElement() && visible() && component()) {
       @if (devtoolsKey(); as dk) {
         <span [attr.data-jr-key]="dk" style="display: contents">
           <ng-container *ngComponentOutlet="component(); injector: outletInjector" />
@@ -1255,7 +1369,7 @@ class JrElement {
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: JrElement, decorators: [{
             type: Component,
             args: [{ selector: 'jr-element', changeDetection: ChangeDetectionStrategy.OnPush, imports: [NgComponentOutlet], template: `
-    @if (rawElement() && visible() && component()) {
+    @if (!refusal() && rawElement() && visible() && component()) {
       @if (devtoolsKey(); as dk) {
         <span [attr.data-jr-key]="dk" style="display: contents">
           <ng-container *ngComponentOutlet="component(); injector: outletInjector" />
@@ -1267,53 +1381,325 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImpo
   `, styles: [":host{display:contents}\n"] }]
         }], ctorParameters: () => [], propDecorators: { elementKey: [{ type: i0.Input, args: [{ isSignal: true, alias: "elementKey", required: true }] }] } });
 
+/**
+ * A hostile spec can fail the catalog's schema in as many places as it has
+ * properties. Report enough to act on and stop; the spec is refused either
+ * way, and a console full of them helps nobody.
+ */
+const MAX_REPORTED_PROP_ISSUES = 20;
+/**
+ * Whether this element's `repeat` descends into the item it is already inside,
+ * rather than re-reading a fixed path in state.
+ *
+ * A relative statePath — `{"$item": "children"}` — resolves against the
+ * enclosing item, so each pass reads one level further into the data and the
+ * recursion ends where the data does. A plain string is absolute: every pass
+ * reads the same array, and a spec that re-enters itself through one never
+ * terminates.
+ */
+function descendsIntoItems(element) {
+    const repeat = element.repeat;
+    return repeat !== undefined && typeof repeat.statePath !== 'string';
+}
+/** Every key an element renders below itself: `children` plus every slot. */
+function childKeysOf(element) {
+    const slots = element.slots;
+    if (!slots)
+        return element.children ?? [];
+    const fromSlots = Object.values(slots).flat();
+    return element.children ? [...element.children, ...fromSlots] : fromSlots;
+}
+/**
+ * Walk the element graph once for depth and cycles.
+ *
+ * Iterative on purpose. A recursive walk would blow the stack on exactly the
+ * specs this exists to catch, which would make the guard a second way to
+ * crash rather than the fix for the first.
+ *
+ * Depth is measured from `spec.root`, because that is what renders. Cycles
+ * are swept for across every element, including the ones no parent reaches:
+ * an unreachable cycle is still a defect, and one edit away from a reachable
+ * one.
+ *
+ * Not every element that reaches itself is a defect, though. Drawing a tree —
+ * a comment thread, a file browser, a nested menu — means an element that
+ * repeats over a relative path and renders itself for each item, and that ends
+ * when the data does. A back edge is only reported when nothing along it
+ * descends into the data, which is the case that cannot end.
+ *
+ * `depthBelow` is memoised per element, so a shared subtree costs one visit
+ * instead of one per path into it — without that, a spec whose elements each
+ * name the next two is exponential to check. The memo makes the reported
+ * depth a lower bound once a cycle has been cut, since which edge closes the
+ * cycle depends on the order the walk reached it. The cycle is reported as an
+ * error of its own, which is the finding worth acting on.
+ */
+function analyseSpecGraph(spec) {
+    const elements = spec.elements ?? {};
+    const cycles = new Set();
+    const depthBelow = new Map();
+    const onPath = new Set();
+    const walkFrom = (start) => {
+        const first = elements[start];
+        if (!first || depthBelow.has(start))
+            return;
+        const stack = [
+            { key: start, kids: childKeysOf(first), next: 0, deepest: 0 },
+        ];
+        onPath.add(start);
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            if (frame.next < frame.kids.length) {
+                const childKey = frame.kids[frame.next++];
+                const memo = depthBelow.get(childKey);
+                if (memo !== undefined) {
+                    frame.deepest = Math.max(frame.deepest, memo);
+                    continue;
+                }
+                // A child that closes the cycle is not followed — that is what keeps
+                // this walk finite — and not counted towards depth either.
+                if (onPath.has(childKey)) {
+                    const from = stack.findIndex((frame) => frame.key === childKey);
+                    const descends = stack
+                        .slice(from)
+                        .some((frame) => descendsIntoItems(elements[frame.key]));
+                    if (!descends)
+                        cycles.add(childKey);
+                    continue;
+                }
+                const child = elements[childKey];
+                // A child the spec never defined is validateSpec's finding, not ours.
+                if (!child)
+                    continue;
+                onPath.add(childKey);
+                stack.push({
+                    key: childKey,
+                    kids: childKeysOf(child),
+                    next: 0,
+                    deepest: 0,
+                });
+                continue;
+            }
+            stack.pop();
+            onPath.delete(frame.key);
+            const depth = frame.deepest + 1;
+            depthBelow.set(frame.key, depth);
+            const parent = stack[stack.length - 1];
+            if (parent)
+                parent.deepest = Math.max(parent.deepest, depth);
+        }
+    };
+    if (spec.root)
+        walkFrom(spec.root);
+    const depth = (spec.root ? depthBelow.get(spec.root) : undefined) ?? 0;
+    for (const key of Object.keys(elements))
+        walkFrom(key);
+    return { depth, cycles: [...cycles] };
+}
+/** Report a cycle, naming the element that is its own descendant. */
+function cycleIssue(key) {
+    return {
+        severity: 'error',
+        code: 'cycle',
+        elementKey: key,
+        message: `Element "${key}" renders itself against the same data, which never terminates. The cycle is broken where it closes — the repeated element does not render a second time — but the spec cannot be drawn as written. A tree that recurses needs a repeat with a relative statePath, like {"$item": "children"}.`,
+    };
+}
+/** Report a breached element-count cap. */
+function elementCountIssue(count, limit) {
+    return {
+        severity: 'error',
+        code: 'too_many_elements',
+        message: `Spec has ${count} elements, over the limit of ${limit}. Nothing is rendered: renderLimits.maxElements is a cap on the whole spec.`,
+    };
+}
+/** Report a breached depth cap. */
+function depthIssue(depth, limit) {
+    return {
+        severity: 'error',
+        code: 'too_deep',
+        message: `Spec nests ${depth} levels deep, over the limit of ${limit}. Elements below level ${limit} do not render.`,
+    };
+}
+/**
+ * Check a spec against a catalog: the component types it names, and then the
+ * catalog's own schema.
+ *
+ * The schema pass is skipped while a type is unknown. A catalog schema keys
+ * its element shapes off `type`, so one name it does not recognise turns into
+ * a pile of prop errors describing a component that was never the point.
+ */
+function catalogIssues(spec, catalog) {
+    const issues = [];
+    const known = new Set(catalog.componentNames);
+    for (const [key, element] of Object.entries(spec.elements ?? {})) {
+        if (known.has(element.type))
+            continue;
+        issues.push({
+            severity: 'error',
+            code: 'unknown_component',
+            elementKey: key,
+            message: `Element "${key}" has type "${element.type}", which this catalog does not define. Nothing renders for it.`,
+        });
+    }
+    if (issues.length > 0)
+        return issues;
+    const result = catalog.validate(spec);
+    if (result.success)
+        return issues;
+    return propIssues(result.error);
+}
+/**
+ * Turn whatever the catalog's schema reported into issues.
+ *
+ * Read defensively rather than typed against the schema library: the shape
+ * below (`issues`, each with `path` and `message`) is what every version of
+ * it has produced, and a renderer that threw while explaining a bad spec
+ * would be the worse failure.
+ */
+function propIssues(error) {
+    const raw = error?.issues;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.slice(0, MAX_REPORTED_PROP_ISSUES).map((entry) => {
+        const item = entry;
+        const path = Array.isArray(item.path) ? item.path : [];
+        const message = typeof item.message === 'string' ? item.message : 'is not valid';
+        // Paths are rooted at the spec, so `elements.<key>.props.<prop>` names the
+        // element in its second segment.
+        const elementKey = path[0] === 'elements' && typeof path[1] === 'string'
+            ? path[1]
+            : undefined;
+        const where = path.length > 0 ? path.join('.') : 'spec';
+        return {
+            severity: 'error',
+            code: 'invalid_props',
+            ...(elementKey === undefined ? {} : { elementKey }),
+            message: `${where}: ${message}`,
+        };
+    });
+}
+
 const CLEAN = {
     spec: null,
     issues: [],
     fixes: [],
     hasErrors: false,
+    blocked: false,
 };
 /**
- * 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.
  */
-function checkSpec(spec, mode) {
+function checkSpec(spec, mode, options = {}) {
     if (!spec)
         return CLEAN;
-    if (mode === 'off') {
-        return { spec, issues: [], fixes: [], hasErrors: false };
+    const limits = options.limits ?? null;
+    const wantsStructure = mode !== 'off';
+    // `maxRepeatItems` caps a live state array, which no amount of reading the
+    // spec can predict — it is enforced as the repeat expands, not here.
+    const maxElements = limits?.maxElements;
+    const maxDepth = limits?.maxDepth;
+    if (!wantsStructure && maxElements === undefined && maxDepth === undefined) {
+        return { spec, issues: [], fixes: [], hasErrors: false, blocked: false };
+    }
+    // The order below is the point of this function, not an accident of it.
+    //
+    // Core's `validateSpec` walks the element tree by recursion, so the specs
+    // that most need a limit are the ones that would overflow the stack proving
+    // they exceed it. Each cheap, non-recursive cap therefore runs first and can
+    // stop the expensive check from being attempted at all: count, then depth —
+    // measured by a walk of our own that uses an explicit stack — and only then
+    // the structural pass.
+    //
+    // `autoFixSpec` only relocates fields inside `props` and never touches
+    // `children` or `slots`, so measuring the graph before fixing it measures
+    // the same graph.
+    if (maxElements !== undefined) {
+        const count = Object.keys(spec.elements ?? {}).length;
+        if (count > maxElements) {
+            const issue = elementCountIssue(count, maxElements);
+            return {
+                spec,
+                issues: [issue],
+                fixes: [],
+                hasErrors: true,
+                blocked: true,
+            };
+        }
+    }
+    const issues = [];
+    let tooDeep = false;
+    if (wantsStructure || maxDepth !== undefined) {
+        const graph = analyseSpecGraph(spec);
+        if (maxDepth !== undefined && graph.depth > maxDepth) {
+            tooDeep = true;
+            issues.push(depthIssue(graph.depth, maxDepth));
+        }
+        if (wantsStructure) {
+            for (const key of graph.cycles)
+                issues.push(cycleIssue(key));
+        }
+    }
+    // A spec past its depth cap is not handed to the recursive checks. The cap
+    // is the finding worth having, and it renders truncated either way.
+    const fixed = wantsStructure && !tooDeep
+        ? autoFixSpec(spec, { lossy: false })
+        : { spec, fixes: [] };
+    if (wantsStructure && !tooDeep) {
+        issues.push(...validateSpec(fixed.spec).issues);
+        if (options.catalog) {
+            issues.push(...catalogIssues(fixed.spec, options.catalog));
+        }
     }
-    const fixed = autoFixSpec(spec, { lossy: false });
-    const { issues } = validateSpec(fixed.spec);
     return {
         spec: fixed.spec,
         issues,
         fixes: fixed.fixes,
         hasErrors: issues.some((issue) => issue.severity === 'error'),
+        blocked: false,
     };
 }
+/**
+ * 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.
+ */
+function formatSpecCheckIssues(issues) {
+    return issues
+        .map((issue) => `  ${issue.severity === 'error' ? 'error  ' : 'warning'} ${issue.elementKey ? `[${issue.elementKey}] ` : ''}${issue.message}`)
+        .join('\n');
+}
 /**
  * Report a check to the console: fixes as information, issues at the severity
- * the mode gives them. `strict` refuses to render, so its errors are reported
- * as errors; under `warn` the spec still renders and the same finding is a
+ * the outcome gives them. A spec that will not render — refused by a limit,
+ * or by `strict` — is reported as an error, because something the developer
+ * asked for is now missing from the screen; one that renders anyway is a
  * warning.
  */
 function reportSpecCheck(check, mode) {
-    if (mode === 'off')
-        return;
     if (check.fixes.length > 0) {
         console.info(`[ngx-json-render] Fixed ${check.fixes.length} spec issue(s) before rendering:\n` +
             check.fixes.map((fix) => `  - ${fix}`).join('\n'));
     }
     if (check.issues.length === 0)
         return;
-    const report = `[ngx-json-render] Spec validation:\n${formatSpecIssues([...check.issues])}`;
-    if (mode === 'strict' && check.hasErrors) {
+    const report = `[ngx-json-render] Spec validation:\n${formatSpecCheckIssues(check.issues)}`;
+    if (check.blocked) {
+        console.error(`${report}\nNothing is rendered: the spec is over a renderLimits cap.`);
+    }
+    else if (mode === 'strict' && check.hasErrors) {
         console.error(`${report}\nNothing is rendered: validate="strict".`);
     }
     else {
@@ -1362,6 +1748,27 @@ class JsonRenderer {
      * arriving is expected to reference children that have not streamed in yet.
      */
     validate = input('off', ...(ngDevMode ? [{ debugName: "validate" }] : /* istanbul ignore next */ []));
+    /**
+     * 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.
+     */
+    renderLimits = input(null, ...(ngDevMode ? [{ debugName: "renderLimits" }] : /* istanbul ignore next */ []));
+    /**
+     * 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`.
+     */
+    catalog = input(null, ...(ngDevMode ? [{ debugName: "catalog" }] : /* istanbul ignore next */ []));
     /**
      * Initial state model (uncontrolled mode). Defaults to `spec.state`.
      * Ignored when `store` is provided.
@@ -1392,7 +1799,10 @@ class JsonRenderer {
      * is forced off: the spec is still arriving, and the missing children it
      * refers to are the normal state of a stream, not a defect.
      */
-    checked = computed(() => checkSpec(this.spec(), this.loading() ? 'off' : this.validate()), ...(ngDevMode ? [{ debugName: "checked" }] : /* istanbul ignore next */ []));
+    checked = computed(() => checkSpec(this.spec(), this.loading() ? 'off' : this.validate(), {
+        limits: this.renderLimits(),
+        catalog: this.catalog(),
+    }), ...(ngDevMode ? [{ debugName: "checked" }] : /* istanbul ignore next */ []));
     constructor() {
         const root = inject(JsonRenderRootContext);
         // The fixed spec, not the input: a `visible` the check moved out of
@@ -1401,6 +1811,7 @@ class JsonRenderer {
         root.registry = this.registry;
         root.loading = this.loading;
         root.fallback = this.fallback;
+        root.limits = this.renderLimits;
         root.store = this.store;
         root.initialState = computed(() => this.state() ?? this.spec()?.state ?? {}, ...(ngDevMode ? [{ debugName: "initialState" }] : /* istanbul ignore next */ []));
         root.handlers = this.handlers;
@@ -1418,11 +1829,23 @@ class JsonRenderer {
         inject(JsonRenderValidationService);
         this.actions = inject(JsonRenderActionsService);
         // Reports once per distinct check rather than once per render: `checked`
-        // only recomputes when the spec, the mode or the loading flag change.
-        effect(() => reportSpecCheck(this.checked(), this.validate()));
+        // only recomputes when the spec, the mode, the limits or the loading flag
+        // change. Silent while loading — a limit can fire on a spec that is still
+        // arriving, and reporting it on every patch would bury the one report
+        // that describes the finished spec.
+        effect(() => {
+            if (this.loading())
+                return;
+            reportSpecCheck(this.checked(), this.validate());
+        });
     }
     rootKey = computed(() => {
         const checked = this.checked();
+        // A spec over an enforced cap does not render in any mode. Whether to
+        // check was the app's decision; once it has made it, honouring the answer
+        // is not also `validate`'s to decide.
+        if (checked.blocked)
+            return null;
         // A spec whose errors survived the fixes does not render under `strict`.
         // Reporting it and drawing half of it anyway is the behaviour the mode
         // exists to refuse.
@@ -1462,7 +1885,7 @@ class JsonRenderer {
         });
     }, ...(ngDevMode ? [{ debugName: "confirmInjector" }] : /* istanbul ignore next */ []));
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: JsonRenderer, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.22", type: JsonRenderer, isStandalone: true, selector: "json-render", inputs: { spec: { classPropertyName: "spec", publicName: "spec", isSignal: true, isRequired: true, transformFunction: null }, registry: { classPropertyName: "registry", publicName: "registry", isSignal: true, isRequired: true, transformFunction: null }, loading: { classPropertyName: "loading", publicName: "loading", isSignal: true, isRequired: false, transformFunction: null }, fallback: { classPropertyName: "fallback", publicName: "fallback", isSignal: true, isRequired: false, transformFunction: null }, validate: { classPropertyName: "validate", publicName: "validate", isSignal: true, isRequired: false, transformFunction: null }, state: { classPropertyName: "state", publicName: "state", isSignal: true, isRequired: false, transformFunction: null }, store: { classPropertyName: "store", publicName: "store", isSignal: true, isRequired: false, transformFunction: null }, handlers: { classPropertyName: "handlers", publicName: "handlers", isSignal: true, isRequired: false, transformFunction: null }, onAction: { classPropertyName: "onAction", publicName: "onAction", isSignal: true, isRequired: false, transformFunction: null }, navigate: { classPropertyName: "navigate", publicName: "navigate", isSignal: true, isRequired: false, transformFunction: null }, validationFunctions: { classPropertyName: "validationFunctions", publicName: "validationFunctions", isSignal: true, isRequired: false, transformFunction: null }, functions: { classPropertyName: "functions", publicName: "functions", isSignal: true, isRequired: false, transformFunction: null }, directives: { classPropertyName: "directives", publicName: "directives", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { stateChange: "stateChange" }, providers: [
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.22", type: JsonRenderer, isStandalone: true, selector: "json-render", inputs: { spec: { classPropertyName: "spec", publicName: "spec", isSignal: true, isRequired: true, transformFunction: null }, registry: { classPropertyName: "registry", publicName: "registry", isSignal: true, isRequired: true, transformFunction: null }, loading: { classPropertyName: "loading", publicName: "loading", isSignal: true, isRequired: false, transformFunction: null }, fallback: { classPropertyName: "fallback", publicName: "fallback", isSignal: true, isRequired: false, transformFunction: null }, validate: { classPropertyName: "validate", publicName: "validate", isSignal: true, isRequired: false, transformFunction: null }, renderLimits: { classPropertyName: "renderLimits", publicName: "renderLimits", isSignal: true, isRequired: false, transformFunction: null }, catalog: { classPropertyName: "catalog", publicName: "catalog", isSignal: true, isRequired: false, transformFunction: null }, state: { classPropertyName: "state", publicName: "state", isSignal: true, isRequired: false, transformFunction: null }, store: { classPropertyName: "store", publicName: "store", isSignal: true, isRequired: false, transformFunction: null }, handlers: { classPropertyName: "handlers", publicName: "handlers", isSignal: true, isRequired: false, transformFunction: null }, onAction: { classPropertyName: "onAction", publicName: "onAction", isSignal: true, isRequired: false, transformFunction: null }, navigate: { classPropertyName: "navigate", publicName: "navigate", isSignal: true, isRequired: false, transformFunction: null }, validationFunctions: { classPropertyName: "validationFunctions", publicName: "validationFunctions", isSignal: true, isRequired: false, transformFunction: null }, functions: { classPropertyName: "functions", publicName: "functions", isSignal: true, isRequired: false, transformFunction: null }, directives: { classPropertyName: "directives", publicName: "directives", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { stateChange: "stateChange" }, providers: [
             JsonRenderRootContext,
             JsonRenderStateService,
             JsonRenderValidationService,
@@ -1511,7 +1934,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImpo
       }
     }
   `, styles: [":host{display:contents}\n"] }]
-        }], ctorParameters: () => [], propDecorators: { spec: [{ type: i0.Input, args: [{ isSignal: true, alias: "spec", required: true }] }], registry: [{ type: i0.Input, args: [{ isSignal: true, alias: "registry", required: true }] }], loading: [{ type: i0.Input, args: [{ isSignal: true, alias: "loading", required: false }] }], fallback: [{ type: i0.Input, args: [{ isSignal: true, alias: "fallback", required: false }] }], validate: [{ type: i0.Input, args: [{ isSignal: true, alias: "validate", required: false }] }], state: [{ type: i0.Input, args: [{ isSignal: true, alias: "state", required: false }] }], store: [{ type: i0.Input, args: [{ isSignal: true, alias: "store", required: false }] }], handlers: [{ type: i0.Input, args: [{ isSignal: true, alias: "handlers", required: false }] }], onAction: [{ type: i0.Input, args: [{ isSignal: true, alias: "onAction", required: false }] }], navigate: [{ type: i0.Input, args: [{ isSignal: true, alias: "navigate", required: false }] }], validationFunctions: [{ type: i0.Input, args: [{ isSignal: true, alias: "validationFunctions", required: false }] }], functions: [{ type: i0.Input, args: [{ isSignal: true, alias: "functions", required: false }] }], directives: [{ type: i0.Input, args: [{ isSignal: true, alias: "directives", required: false }] }], stateChange: [{ type: i0.Output, args: ["stateChange"] }] } });
+        }], ctorParameters: () => [], propDecorators: { spec: [{ type: i0.Input, args: [{ isSignal: true, alias: "spec", required: true }] }], registry: [{ type: i0.Input, args: [{ isSignal: true, alias: "registry", required: true }] }], loading: [{ type: i0.Input, args: [{ isSignal: true, alias: "loading", required: false }] }], fallback: [{ type: i0.Input, args: [{ isSignal: true, alias: "fallback", required: false }] }], validate: [{ type: i0.Input, args: [{ isSignal: true, alias: "validate", required: false }] }], renderLimits: [{ type: i0.Input, args: [{ isSignal: true, alias: "renderLimits", required: false }] }], catalog: [{ type: i0.Input, args: [{ isSignal: true, alias: "catalog", required: false }] }], state: [{ type: i0.Input, args: [{ isSignal: true, alias: "state", required: false }] }], store: [{ type: i0.Input, args: [{ isSignal: true, alias: "store", required: false }] }], handlers: [{ type: i0.Input, args: [{ isSignal: true, alias: "handlers", required: false }] }], onAction: [{ type: i0.Input, args: [{ isSignal: true, alias: "onAction", required: false }] }], navigate: [{ type: i0.Input, args: [{ isSignal: true, alias: "navigate", required: false }] }], validationFunctions: [{ type: i0.Input, args: [{ isSignal: true, alias: "validationFunctions", required: false }] }], functions: [{ type: i0.Input, args: [{ isSignal: true, alias: "functions", required: false }] }], directives: [{ type: i0.Input, args: [{ isSignal: true, alias: "directives", required: false }] }], stateChange: [{ type: i0.Output, args: ["stateChange"] }] } });
 
 /**
  * Provides the repeat scope (item, index, absolute base path) to the elements
@@ -1586,13 +2009,43 @@ class JrChildren {
         }
         return resolved;
     }, ...(ngDevMode ? [{ debugName: "repeatBasePath" }] : /* istanbul ignore next */ []));
-    repeatItems = computed(() => {
+    /** Every item the repeat's state array holds, before any cap. */
+    allRepeatItems = computed(() => {
         const basePath = this.repeatBasePath();
         if (basePath === undefined)
             return [];
         return (getByPath(this.state.state(), basePath) ?? []);
+    }, ...(ngDevMode ? [{ debugName: "allRepeatItems" }] : /* istanbul ignore next */ []));
+    /**
+     * 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.
+     */
+    repeatItems = computed(() => {
+        const items = this.allRepeatItems();
+        const max = this.root.limits()?.maxRepeatItems;
+        return max !== undefined && items.length > max
+            ? items.slice(0, max)
+            : items;
     }, ...(ngDevMode ? [{ debugName: "repeatItems" }] : /* istanbul ignore next */ []));
     constructor() {
+        // Warn (once) when the cap holds items back. Reading the count only after
+        // the two cheap guards keeps the effect from tracking the state array at
+        // all once there is nothing left to say.
+        let warnedRepeatCap = false;
+        effect(() => {
+            const max = this.root.limits()?.maxRepeatItems;
+            if (max === undefined || warnedRepeatCap)
+                return;
+            const total = this.allRepeatItems().length;
+            if (total <= max)
+                return;
+            warnedRepeatCap = true;
+            console.warn(`[ngx-json-render] renderLimits.maxRepeatItems (${max}) reached: "${untracked(this.repeatBasePath)}" holds ${total} items, so ${total - max} of them do not render.`);
+        });
         // Warn (once per key) about children referencing missing elements.
         const warned = new Set();
         effect(() => {
@@ -2238,6 +2691,10 @@ function injectUIStream(options) {
     const rawLines = signal([], ...(ngDevMode ? [{ debugName: "rawLines" }] : /* istanbul ignore next */ []));
     const issues = signal([], ...(ngDevMode ? [{ debugName: "issues" }] : /* istanbul ignore next */ []));
     const validate = options.validate ?? 'off';
+    const checkOptions = {
+        limits: options.renderLimits ?? null,
+        catalog: options.catalog ?? null,
+    };
     const session = createStreamSession();
     inject(DestroyRef).onDestroy(() => session.cancel());
     const stop = () => {
@@ -2292,7 +2749,7 @@ function injectUIStream(options) {
                 signal: gate.signal,
             }, createLineConsumer(handleLine));
             gate.commit(() => {
-                const check = checkSpec(currentSpec, validate);
+                const check = checkSpec(currentSpec, validate, checkOptions);
                 reportSpecCheck(check, validate);
                 if (check.spec) {
                     currentSpec = check.spec;
@@ -2303,8 +2760,11 @@ function injectUIStream(options) {
                 // app's onComplete is where a spec usually gets persisted, and handing
                 // it one that cannot render is the outcome this mode is asked to
                 // prevent. The spec stays put so the app can show or discard it.
-                if (validate === 'strict' && check.hasErrors) {
-                    const invalid = new Error(`Generated spec failed validation:\n${formatSpecIssues([...check.issues])}`);
+                // A limit the app set fails the generation whatever the mode: the
+                // spec it would hand `onComplete` is one the app already said it did
+                // not want rendered.
+                if (check.blocked || (validate === 'strict' && check.hasErrors)) {
+                    const invalid = new Error(`Generated spec failed validation:\n${formatSpecCheckIssues(check.issues)}`);
                     error.set(invalid);
                     options.onError?.(invalid);
                     return;
@@ -2361,6 +2821,10 @@ function injectChatUI(options) {
     const error = signal(null, ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
     const issues = signal([], ...(ngDevMode ? [{ debugName: "issues" }] : /* istanbul ignore next */ []));
     const validate = options.validate ?? 'off';
+    const checkOptions = {
+        limits: options.renderLimits ?? null,
+        catalog: options.catalog ?? null,
+    };
     const session = createStreamSession();
     inject(DestroyRef).onDestroy(() => session.cancel());
     const stop = () => {
@@ -2448,7 +2912,7 @@ function injectChatUI(options) {
             gate.commit(() => {
                 // A reply that only talked has no spec to check, and reporting
                 // "missing root" for a sentence would be nonsense.
-                const check = checkSpec(hasSpec ? currentSpec : null, validate);
+                const check = checkSpec(hasSpec ? currentSpec : null, validate, checkOptions);
                 if (hasSpec) {
                     reportSpecCheck(check, validate);
                     if (check.spec)
@@ -2464,8 +2928,11 @@ function injectChatUI(options) {
                 // The reply keeps the fixed spec, so what renders in the bubble is
                 // what was checked.
                 messages.update((prev) => prev.map((m) => (m.id === assistantId ? finalMessage : m)));
-                if (validate === 'strict' && check.hasErrors) {
-                    const invalid = new Error(`Generated spec failed validation:\n${formatSpecIssues([...check.issues])}`);
+                // A limit the app set fails the generation whatever the mode: the
+                // spec it would hand `onComplete` is one the app already said it did
+                // not want rendered.
+                if (check.blocked || (validate === 'strict' && check.hasErrors)) {
+                    const invalid = new Error(`Generated spec failed validation:\n${formatSpecCheckIssues(check.issues)}`);
                     error.set(invalid);
                     options.onError?.(invalid);
                     return;
@@ -2611,5 +3078,5 @@ const schema = defineSchema((s) => ({
  * Generated bundle index. Do not edit.
  */
 
-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 { 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 };
 //# sourceMappingURL=ngx-json-render.mjs.map