@ng-forge/dynamic-forms 0.9.0-next.11 → 0.9.0-next.12

package/fesm2022/{ng-forge-dynamic-forms-ng-forge-dynamic-forms-o3rJX4vG.mjs → ng-forge-dynamic-forms-ng-forge-dynamic-forms-BAPGCjUs.mjs}

@@ -1,8 +1,8 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, reflectComponentType, Injector, inject, EnvironmentInjector, DestroyRef, computed, input, ViewContainerRef, signal, Directive, Injectable, isSignal, untracked, linkedSignal, ChangeDetectionStrategy, Component, resourceFromSnapshots, runInInjectionContext, afterNextRender, isWritableSignal, model, makeEnvironmentProviders, Pipe } from '@angular/core';
+import { InjectionToken, reflectComponentType, Injector, inject, EnvironmentInjector, DestroyRef, computed, signal, input, ViewContainerRef, Directive, Injectable, isSignal, untracked, linkedSignal, ChangeDetectionStrategy, Component, resourceFromSnapshots, runInInjectionContext, afterNextRender, isWritableSignal, model, makeEnvironmentProviders, Pipe } from '@angular/core';
 import { explicitEffect } from 'ngxtension/explicit-effect';
-import { of, forkJoin, from, catchError, map, switchMap, isObservable, firstValueFrom, exhaustMap, EMPTY, Subject, filter, TimeoutError, throwError, defer, combineLatest, pipe, debounceTime, distinctUntilChanged, tap, startWith, scan as scan$1, Observable, concatMap, take as take$1, pairwise, takeUntil, combineLatestWith, auditTime, scheduled, queueScheduler, merge, timer } from 'rxjs';
 import { takeUntilDestroyed, toObservable, toSignal, rxResource, outputFromObservable } from '@angular/core/rxjs-interop';
+import { of, forkJoin, from, catchError, map, switchMap, isObservable, firstValueFrom, exhaustMap, EMPTY, Subject, filter, TimeoutError, throwError, defer, combineLatest, pipe, debounceTime, distinctUntilChanged, tap, startWith, scan as scan$1, Observable, concatMap, take as take$1, pairwise, takeUntil, combineLatestWith, auditTime, scheduled, queueScheduler, merge, timer } from 'rxjs';
 import { submit, email, min, max, minLength, maxLength, pattern, required, validate, validateAsync, validateHttp, disabled, readonly, hidden, applyEach, applyWhenValue, applyWhen, apply, schema, validateStandardSchema, validateTree, form, provideSignalFormsConfig } from '@angular/forms/signals';
 import { scan, map as map$1, filter as filter$1, take, switchMap as switchMap$1, timeout, catchError as catchError$1, shareReplay } from 'rxjs/operators';
 import { HttpClient } from '@angular/common/http';
@@ -252,65 +252,57 @@ const FORM_OPTIONS = new InjectionToken('FORM_OPTIONS');
  * and inherited by all children via Angular's hierarchical injector.
  */
 const EXTERNAL_DATA = new InjectionToken('EXTERNAL_DATA');
+
 /**
- * Injection token for array-level template registry.
- *
- * This registry tracks which template was used to create each array item,
- * keyed by the item's unique ID. This is essential for "recreate" operations
- * (e.g., after removing items from the middle) where we need to re-resolve
- * items using their original templates, not a fallback.
- *
- * The token is provided by ArrayFieldComponent at its level and shared
- * across all items in that array. Each nested array gets its own registry.
- *
- * @example
- * ```typescript
- * // In ArrayFieldComponent
- * providers: [
- *   { provide: ARRAY_TEMPLATE_REGISTRY, useValue: new Map() }
- * ]
- *
- * // When adding items
- * const registry = inject(ARRAY_TEMPLATE_REGISTRY);
- * registry.set(itemId, templates);
+ * Injection token for the dynamic forms logger.
  *
- * // During recreate, look up original template
- * const originalTemplate = registry.get(existingItemId);
- * ```
+ * Provided by provideDynamicForm() with ConsoleLogger as default.
+ * Override with withLoggerConfig(false) to disable logging.
  */
-const ARRAY_TEMPLATE_REGISTRY = new InjectionToken('ARRAY_TEMPLATE_REGISTRY');
+const DynamicFormLogger = new InjectionToken('DynamicFormLogger');
+
 /**
- * Injection token for array-level item ID generator.
- *
- * Provides a function that generates unique IDs for array items. Each array
- * component instance gets its own generator (via useFactory), ensuring:
- * - SSR hydration compatibility (server and client generate same IDs for same array)
- * - No global state pollution between form instances
- * - Deterministic IDs within each array's lifecycle
- *
- * The token is provided by ArrayFieldComponent at its level with a factory
- * that creates a fresh counter for each array instance.
- *
- * @example
- * ```typescript
- * // In ArrayFieldComponent
- * providers: [
- *   { provide: ARRAY_ITEM_ID_GENERATOR, useFactory: createArrayItemIdGenerator }
- * ]
- *
- * // Usage
- * const generateId = inject(ARRAY_ITEM_ID_GENERATOR);
- * const itemId = generateId(); // 'item-0', 'item-1', etc.
- * ```
+ * Shared empty chain — returned when no wrappers apply so callers get a
+ * stable reference. Freezing makes accidental mutation observable.
  */
-const ARRAY_ITEM_ID_GENERATOR = new InjectionToken('ARRAY_ITEM_ID_GENERATOR');
+const EMPTY_WRAPPERS = Object.freeze([]);
 /**
- * Factory function that creates a new array item ID generator.
- * Each invocation creates an independent counter starting at 0.
+ * Element-wise identity (`===`) comparator for wrapper chains. Used as the
+ * `equal` option on signal memoisation so reconciled `FieldDef`s with the
+ * same chain don't churn downstream — relies on `WrapperConfig` objects
+ * being stable across ticks, which holds for configs declared in
+ * `FormConfig` / `createWrappers(...)`.
  */
-function createArrayItemIdGenerator() {
-    let counter = 0;
-    return () => `item-${counter++}`;
+function isSameWrapperChain(a, b) {
+    if (a === b)
+        return true;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Resolves the wrapper chain for a field.
+ *
+ * Merge order (outermost → innermost): auto-associations, form defaults,
+ * field-level wrappers. `wrappers: null` skips all three; `skipAutoWrappers` /
+ * `skipDefaultWrappers` on the field opt out of individual layers. Fresh
+ * array per call — downstream memoisation is on the consuming computed.
+ */
+function resolveWrappers(field, defaultWrappers, autoAssociations) {
+    if (field.wrappers === null) {
+        return EMPTY_WRAPPERS;
+    }
+    const autoWrappers = field.skipAutoWrappers ? EMPTY_WRAPPERS : (autoAssociations.get(field.type) ?? EMPTY_WRAPPERS);
+    const defaults = field.skipDefaultWrappers ? EMPTY_WRAPPERS : (defaultWrappers ?? EMPTY_WRAPPERS);
+    const fieldLevel = field.wrappers ?? EMPTY_WRAPPERS;
+    if (autoWrappers.length === 0 && defaults.length === 0 && fieldLevel.length === 0) {
+        return EMPTY_WRAPPERS;
+    }
+    return [...autoWrappers, ...defaults, ...fieldLevel];
 }
 
 /**
@@ -507,58 +499,6 @@ class WrapperAwareInjector extends Injector {
     }
 }
 
-/**
- * Injection token for the dynamic forms logger.
- *
- * Provided by provideDynamicForm() with ConsoleLogger as default.
- * Override with withLoggerConfig(false) to disable logging.
- */
-const DynamicFormLogger = new InjectionToken('DynamicFormLogger');
-
-/**
- * Shared empty chain — returned when no wrappers apply so callers get a
- * stable reference. Freezing makes accidental mutation observable.
- */
-const EMPTY_WRAPPERS = Object.freeze([]);
-/**
- * Element-wise identity (`===`) comparator for wrapper chains. Used as the
- * `equal` option on signal memoisation so reconciled `FieldDef`s with the
- * same chain don't churn downstream — relies on `WrapperConfig` objects
- * being stable across ticks, which holds for configs declared in
- * `FormConfig` / `createWrappers(...)`.
- */
-function isSameWrapperChain(a, b) {
-    if (a === b)
-        return true;
-    if (a.length !== b.length)
-        return false;
-    for (let i = 0; i < a.length; i++) {
-        if (a[i] !== b[i])
-            return false;
-    }
-    return true;
-}
-/**
- * Resolves the wrapper chain for a field.
- *
- * Merge order (outermost → innermost): auto-associations, form defaults,
- * field-level wrappers. `wrappers: null` skips all three; `skipAutoWrappers` /
- * `skipDefaultWrappers` on the field opt out of individual layers. Fresh
- * array per call — downstream memoisation is on the consuming computed.
- */
-function resolveWrappers(field, defaultWrappers, autoAssociations) {
-    if (field.wrappers === null) {
-        return EMPTY_WRAPPERS;
-    }
-    const autoWrappers = field.skipAutoWrappers ? EMPTY_WRAPPERS : (autoAssociations.get(field.type) ?? EMPTY_WRAPPERS);
-    const defaults = field.skipDefaultWrappers ? EMPTY_WRAPPERS : (defaultWrappers ?? EMPTY_WRAPPERS);
-    const fieldLevel = field.wrappers ?? EMPTY_WRAPPERS;
-    if (autoWrappers.length === 0 && defaults.length === 0 && fieldLevel.length === 0) {
-        return EMPTY_WRAPPERS;
-    }
-    return [...autoWrappers, ...defaults, ...fieldLevel];
-}
-
 /**
  * Owns the wrapper-chain lifecycle for a field or container: async component
  * loading, switchMap-based cancellation of stale loads, flicker-tolerant
@@ -749,6 +689,155 @@ function toReadonlyFieldTreeCached(cache, field) {
     return view;
 }
 
+const EMPTY_STATE = Object.freeze({ phase: 'empty' });
+/**
+ * Encapsulates the imperative `ViewContainerRef` / `ComponentRef` lifecycle
+ * for the innermost field component. Pulled out of `DfFieldOutlet` so the
+ * directive itself stays declarative — signals + constructor wiring — while
+ * the unavoidable mutable bookkeeping (Angular's view container API is
+ * imperative) lives in one place behind a small, focused surface.
+ *
+ * State is held in a single `signal<FieldSlotState>` discriminated union;
+ * every mutation is an explicit `state.set(...)` transition. No nullable
+ * instance fields, no `undefined`-initialized refs — each phase carries
+ * exactly the data it owns.
+ *
+ * Responsibilities:
+ * - Create the component (or reuse the same-class instance across a rebuild,
+ *   preserving its DOM state, focus, and caret).
+ * - Push mapper inputs via `setInput`, dedup'd per-key so dev-mode NG0303
+ *   warnings for undeclared mapper keys don't replay on every emission.
+ * - Detach cleanly before the outer VCR clears, so same-class reuse can
+ *   re-insert the preserved `hostView`.
+ * - Destroy on directive teardown when the host view is still detached.
+ */
+class FieldComponentSlot {
+    state = signal(EMPTY_STATE, ...(ngDevMode ? [{ debugName: "state" }] : /* istanbul ignore next */ []));
+    /**
+     * Per-key cache for `pushInputs`. Lives outside the lifecycle state machine on
+     * purpose — it's a `setInput`-call optimization that changes on every keystroke,
+     * not a phase transition. Keeping it here means the `state` signal only emits
+     * on real `empty ⇄ mounted ⇄ detached` transitions (≈ once per
+     * mount/destroy cycle), not once per input emission.
+     */
+    lastInputs = null;
+    /** Read-only view of the lifecycle phase. Useful for tests and assertions. */
+    phase = () => this.state().phase;
+    /** Read-only view of the full state. Exposed so tests can assert ref stability. */
+    snapshot = () => this.state();
+    /**
+     * Mount the field component into `slot`. Reuses the existing `ComponentRef`
+     * when its component type matches (preserving DOM/focus/caret across a
+     * wrapper-chain rebuild); otherwise discards the old ref and creates a fresh
+     * one.
+     */
+    mountOrReuse(slot, component, fieldInjector, environmentInjector, rawInputs) {
+        const current = this.state();
+        if (current.phase !== 'empty' && current.ref.componentType === component) {
+            slot.insert(current.ref.hostView);
+            this.lastInputs = null;
+            this.state.set(Object.freeze({ phase: 'mounted', ref: current.ref, slot }));
+            this.pushInputs(rawInputs);
+            if (current.phase === 'detached')
+                this.replayFocus(current.focusSnapshot);
+            return;
+        }
+        // Different component class — destroy the prior ref (if any) and create
+        // a fresh one. The `empty` transition before `createComponent` ensures a
+        // throw inside the factory doesn't leave a dangling ref the next mount
+        // would try to re-insert.
+        if (current.phase !== 'empty')
+            current.ref.destroy();
+        this.lastInputs = null;
+        this.state.set(EMPTY_STATE);
+        const ref = slot.createComponent(component, {
+            environmentInjector,
+            injector: createWrapperAwareInjector(fieldInjector, slot.injector),
+        });
+        this.state.set(Object.freeze({ phase: 'mounted', ref, slot }));
+        this.pushInputs(rawInputs);
+    }
+    /**
+     * Push mapper inputs onto the mounted component. Per-key reference compare
+     * skips `setInput` for unchanged values — necessary in dev mode where
+     * `setInput` on unknown keys logs NG0303 per call (Angular 21 is lenient
+     * at runtime but warns); without the cache, every emission would re-warn
+     * for every undeclared mapper key.
+     *
+     * Updates the `lastInputs` cache (a plain field, not part of `state`) so the
+     * `state` signal doesn't churn its reference on every keystroke.
+     *
+     * `reflectComponentType` does NOT include hostDirective-forwarded inputs
+     * (angular/angular#49734), so a declared-input filter here would skip every
+     * value flowing through `NgForgeFieldShell` / `NgForgeField` /
+     * `NgForgeAction`. Mapper-as-contract is enforced by the `*_INPUTS`
+     * lockstep type assertions, not at runtime here.
+     */
+    pushInputs(rawInputs) {
+        const current = this.state();
+        if (current.phase !== 'mounted')
+            return;
+        const prev = this.lastInputs;
+        if (prev === rawInputs)
+            return;
+        for (const [key, value] of Object.entries(rawInputs)) {
+            if (prev && prev[key] === value)
+                continue;
+            current.ref.setInput(key, value);
+        }
+        this.lastInputs = rawInputs;
+    }
+    /**
+     * Detach the host view from its current slot, capturing focus + caret so the
+     * next `mountOrReuse()` can replay them after re-inserting into the new
+     * slot. A stranded `mounted` state with a bad slot index (re-entrancy during
+     * a partial rebuild) is treated like `empty` to avoid leaks.
+     */
+    detach() {
+        const current = this.state();
+        if (current.phase !== 'mounted')
+            return;
+        const focusSnapshot = this.captureFocus(current.ref);
+        const idx = current.slot.indexOf(current.ref.hostView);
+        if (idx >= 0)
+            current.slot.detach(idx);
+        this.lastInputs = null;
+        this.state.set(Object.freeze({ phase: 'detached', ref: current.ref, focusSnapshot }));
+    }
+    /**
+     * Called on directive teardown. Only destroys when the host view is still
+     * detached — otherwise the outer `vcr.clear()` cascade has already destroyed
+     * it (calling `.destroy()` again would throw).
+     */
+    destroyOnTeardown() {
+        const current = this.state();
+        if (current.phase === 'detached')
+            current.ref.destroy();
+        this.lastInputs = null;
+        this.state.set(EMPTY_STATE);
+    }
+    captureFocus(ref) {
+        const hostEl = ref.location.nativeElement;
+        const active = document.activeElement;
+        if (!(active instanceof HTMLElement) || !hostEl.contains(active))
+            return null;
+        const sel = active;
+        return {
+            element: active,
+            selectionStart: typeof sel.selectionStart === 'number' ? sel.selectionStart : null,
+            selectionEnd: typeof sel.selectionEnd === 'number' ? sel.selectionEnd : null,
+        };
+    }
+    replayFocus(snap) {
+        if (!snap || !snap.element.isConnected)
+            return;
+        snap.element.focus();
+        if (snap.selectionStart !== null && snap.selectionEnd !== null && 'setSelectionRange' in snap.element) {
+            snap.element.setSelectionRange(snap.selectionStart, snap.selectionEnd);
+        }
+    }
+}
+
 /**
  * Structural directive that renders a `ResolvedField` with its effective
  * wrapper chain.
@@ -769,12 +858,16 @@ function toReadonlyFieldTreeCached(cache, field) {
  * includes the field's mapper outputs and a `ReadonlyFieldTree` view of its
  * form state.
  *
- * Rendering is gated by `field.renderReady()` — the directive waits until
- * the mapper produces the required inputs before instantiating the component.
- * Once rendered, a transient `renderReady → false` does *not* tear the chain
- * down; the controller keeps the mounted components alive and ignores the
- * flicker. Only a structural change (wrappers or component class) triggers
- * a rebuild.
+ * Rendering is gated by `field.renderReady() && !field.hidden()` — the
+ * directive waits until the mapper produces the required inputs AND the
+ * field isn't hidden before instantiating the component. Once rendered, a
+ * transient `renderReady → false` does *not* tear the chain down; the
+ * controller keeps the mounted components alive and ignores the flicker.
+ * Only a structural change (wrappers or component class) triggers a rebuild.
+ *
+ * Imperative `ComponentRef` / `ViewContainerRef` lifecycle is encapsulated
+ * in `FieldComponentSlot` — the directive itself is signal definitions
+ * plus three method calls (`mountOrReuse`, `detach`, `destroyOnTeardown`).
  *
  * @example
  * ```html
@@ -794,25 +887,16 @@ class DfFieldOutlet {
     wrapperAutoAssociations = inject(WRAPPER_AUTO_ASSOCIATIONS);
     defaultWrappersSignal = inject(DEFAULT_WRAPPERS, { optional: true });
     readonlyFieldCache = inject(READONLY_FIELD_TREE_CACHE);
-    fieldRef;
-    /**
-     * VCR the `fieldRef`'s host view is currently inserted into (either the outer
-     * VCR when there are no wrappers, or the innermost wrapper's `#fieldComponent`
-     * slot). Tracked so `beforeRebuild` can detach the view before the outer VCR
-     * cascade-destroys it.
-     */
-    fieldSlot;
-    /** Focus + caret captured during detach, replayed after re-insert. */
-    focusSnapshot;
+    /** Encapsulates Angular's imperative ComponentRef / ViewContainerRef lifecycle. */
+    fieldComponent = new FieldComponentSlot();
+    componentIdentity = computed(() => this.dfFieldOutlet().component, ...(ngDevMode ? [{ debugName: "componentIdentity" }] : /* istanbul ignore next */ []));
     /**
-     * Last rawInputs reference pushed to the innermost field. Used to dedupe the
-     * rawInputs effect when the same snapshot was already applied as part of the
-     * initial render — keeps per-keystroke input updates O(changed-keys) instead
-     * of re-walking the whole input bag.
+     * Gate for the wrapper chain controller: true only when required inputs are populated AND the
+     * field isn't hidden. Combining the two prevents an initial-mount race where the chain mounts
+     * during the brief window between `renderReady` flipping true and `hidden()` settling — that
+     * window is exactly where Angular Signal Forms' `[formField]` directive emits NG01916.
      */
-    lastPushedInputs;
-    componentIdentity = computed(() => this.dfFieldOutlet().component, ...(ngDevMode ? [{ debugName: "componentIdentity" }] : /* istanbul ignore next */ []));
-    renderReady = computed(() => this.dfFieldOutlet().renderReady(), ...(ngDevMode ? [{ debugName: "renderReady" }] : /* istanbul ignore next */ []));
+    renderReady = computed(() => this.dfFieldOutlet().renderReady() && !this.dfFieldOutlet().hidden(), ...(ngDevMode ? [{ debugName: "renderReady" }] : /* istanbul ignore next */ []));
     rawInputs = computed(() => this.dfFieldOutlet().inputs(), ...(ngDevMode ? [{ debugName: "rawInputs" }] : /* istanbul ignore next */ []));
     /**
      * Effective wrapper chain. Element-wise identity comparison keeps the signal
@@ -839,109 +923,17 @@ class DfFieldOutlet {
             rebuildKey: this.componentIdentity,
             fieldInputs: this.fieldInputs,
             fieldInjector: this.fieldInjector,
-            beforeRebuild: () => this.detachFieldRef(),
+            beforeRebuild: () => this.fieldComponent.detach(),
             renderInnermost: (slot) => {
                 const resolved = this.dfFieldOutlet();
-                if (this.fieldRef && this.fieldRef.componentType === resolved.component) {
-                    // Same component class — re-insert the preserved hostView. Browser
-                    // loses focus on detach, so we replay the snapshot captured in
-                    // detachFieldRef. Input value persists on the DOM node itself.
-                    slot.insert(this.fieldRef.hostView);
-                    this.fieldSlot = slot;
-                    this.pushRawInputs(this.fieldRef, this.rawInputs());
-                    this.restoreFocusSnapshot();
-                    return;
-                }
-                // Different component class — discard the old ref and create fresh.
-                // Merge field + element injectors so the field can inject ancestor
-                // wrappers AND form-context tokens (ARRAY_CONTEXT etc.).
-                // Clear state before createComponent — if it throws (bad provider,
-                // invalid class) we don't want to leak a reference to a destroyed ref
-                // that the same-component branch would later try to re-insert.
-                this.focusSnapshot = undefined;
-                this.lastPushedInputs = undefined;
-                const previousRef = this.fieldRef;
-                this.fieldRef = undefined;
-                this.fieldSlot = undefined;
-                previousRef?.destroy();
-                this.fieldRef = slot.createComponent(resolved.component, {
-                    environmentInjector: this.fieldEnvInjector(),
-                    injector: createWrapperAwareInjector(resolved.injector, slot.injector),
-                });
-                this.fieldSlot = slot;
-                // setInput dirties the signal synchronously; the next CD pass reads
-                // it. Safe outside CD — see wrapper-chain-controller scheduling.
-                this.pushRawInputs(this.fieldRef, this.rawInputs());
+                this.fieldComponent.mountOrReuse(slot, resolved.component, resolved.injector, this.fieldEnvInjector(), this.rawInputs());
             },
         });
-        // Push rawInputs to the innermost field. Safe mid-rebuild — renderInnermost
-        // re-reads rawInputs synchronously on mount, so skipping here loses nothing.
-        explicitEffect([this.rawInputs], ([rawInputs]) => {
-            if (!this.fieldRef)
-                return;
-            if (this.lastPushedInputs === rawInputs)
-                return;
-            this.pushRawInputs(this.fieldRef, rawInputs);
-        });
-        this.destroyRef.onDestroy(() => {
-            // Only destroy when detached — vcr.clear() cascades otherwise.
-            if (this.fieldRef && !this.fieldSlot)
-                this.fieldRef.destroy();
-            this.fieldRef = undefined;
-            this.fieldSlot = undefined;
-            this.lastPushedInputs = undefined;
-        });
-    }
-    detachFieldRef() {
-        if (!this.fieldRef)
-            return;
-        if (!this.fieldSlot) {
-            // Stranded fieldRef — destroy to prevent a leak.
-            this.fieldRef.destroy();
-            this.fieldRef = undefined;
-            return;
-        }
-        this.captureFocusSnapshot();
-        const idx = this.fieldSlot.indexOf(this.fieldRef.hostView);
-        if (idx >= 0)
-            this.fieldSlot.detach(idx);
-        this.fieldSlot = undefined;
-    }
-    /** Capture active element + selection before the hostView is detached from DOM. */
-    captureFocusSnapshot() {
-        if (!this.fieldRef)
-            return;
-        const hostEl = this.fieldRef.location.nativeElement;
-        const active = document.activeElement;
-        if (!(active instanceof HTMLElement) || !hostEl.contains(active))
-            return;
-        const sel = active;
-        this.focusSnapshot = {
-            element: active,
-            selectionStart: typeof sel.selectionStart === 'number' ? sel.selectionStart : null,
-            selectionEnd: typeof sel.selectionEnd === 'number' ? sel.selectionEnd : null,
-        };
-    }
-    /** Re-apply the pre-detach focus + caret after the hostView is back in the DOM. */
-    restoreFocusSnapshot() {
-        const snap = this.focusSnapshot;
-        this.focusSnapshot = undefined;
-        if (!snap || !snap.element.isConnected)
-            return;
-        snap.element.focus();
-        if (snap.selectionStart !== null && snap.selectionEnd !== null && 'setSelectionRange' in snap.element) {
-            snap.element.setSelectionRange(snap.selectionStart, snap.selectionEnd);
-        }
-    }
-    pushRawInputs(ref, rawInputs) {
-        // setInput is lenient in Angular 21 — unknown keys silently drop (not NG0303). reflectComponentType does NOT include hostDirective forwarded inputs (angular/angular#49734), so a declared-input filter here would skip every value flowing through NgForgeFieldShell / NgForgeField / NgForgeAction. Mapper-as-contract is enforced by the *_INPUTS lockstep type assertions, not at runtime here.
-        const last = this.lastPushedInputs;
-        for (const [key, value] of Object.entries(rawInputs)) {
-            if (last && last[key] === value)
-                continue;
-            ref.setInput(key, value);
-        }
-        this.lastPushedInputs = rawInputs;
+        // Push rawInputs to the innermost field on every change. The slot dedupes per-key, so the
+        // initial render's synchronous push from `renderInnermost` and the effect's first fire
+        // converge cleanly with no double-pushing.
+        explicitEffect([this.rawInputs], ([rawInputs]) => this.fieldComponent.pushInputs(rawInputs));
+        this.destroyRef.onDestroy(() => this.fieldComponent.destroyOnTeardown());
     }
     buildFieldInputs(rawInputs) {
         const fieldTreeCandidate = rawInputs['field'];
@@ -4180,9 +4172,9 @@ class PageOrchestratorComponent {
         }
       }
     }
-  `, isInline: true, styles: [":host{display:block;position:relative;width:100%}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush, deferBlockDependencies: [() => [import('./ng-forge-dynamic-forms-page-field.component-BX4R9GGa.mjs').then(m => m.default)], () => [import('./ng-forge-dynamic-forms-page-field.component-BX4R9GGa.mjs').then(m => m.default)]] });
+  `, isInline: true, styles: [":host{display:block;position:relative;width:100%}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush, deferBlockDependencies: [() => [import('./ng-forge-dynamic-forms-page-field.component-DDzmhJNn.mjs').then(m => m.default)], () => [import('./ng-forge-dynamic-forms-page-field.component-DDzmhJNn.mjs').then(m => m.default)]] });
 }
-i0.ɵɵngDeclareClassMetadataAsync({ minVersion: "18.0.0", version: "21.2.8", ngImport: i0, type: PageOrchestratorComponent, resolveDeferredDeps: () => [import('./ng-forge-dynamic-forms-page-field.component-BX4R9GGa.mjs').then(m => m.default)], resolveMetadata: PageFieldComponent => ({ decorators: [{
+i0.ɵɵngDeclareClassMetadataAsync({ minVersion: "18.0.0", version: "21.2.8", ngImport: i0, type: PageOrchestratorComponent, resolveDeferredDeps: () => [import('./ng-forge-dynamic-forms-page-field.component-DDzmhJNn.mjs').then(m => m.default)], resolveMetadata: PageFieldComponent => ({ decorators: [{
                 type: Component,
                 args: [{ selector: 'div[page-orchestrator]', imports: [PageFieldComponent], template: `
     @for (pageField of pageFields(); track pageField.key; let i = $index) {
@@ -4614,6 +4606,85 @@ function isValidNonPagedForm(fields) {
     return result.mode === 'non-paged' && result.isValid;
 }
 
+function createSlot() {
+    let counter = 0;
+    const templates = new Map();
+    const itemOrder = [];
+    const primitiveFieldKey = signal(undefined, ...(ngDevMode ? [{ debugName: "primitiveFieldKey" }] : /* istanbul ignore next */ []));
+    return {
+        templates,
+        itemOrder,
+        primitiveFieldKey,
+        nextId: () => `item-${counter++}`,
+        setTemplate(itemId, t) {
+            templates.set(itemId, t);
+        },
+        getTemplate(itemId) {
+            return templates.get(itemId);
+        },
+        hasTemplate(itemId) {
+            return templates.has(itemId);
+        },
+        setIdAt(index, itemId) {
+            itemOrder[index] = itemId;
+        },
+        removeAt(index) {
+            const [removed] = itemOrder.splice(index, 1);
+            if (removed !== undefined)
+                templates.delete(removed);
+        },
+        moveItem(fromIndex, toIndex) {
+            const [id] = itemOrder.splice(fromIndex, 1);
+            if (id !== undefined)
+                itemOrder.splice(toIndex, 0, id);
+        },
+        truncate(length) {
+            const removed = itemOrder.splice(length);
+            for (const id of removed)
+                templates.delete(id);
+        },
+        clear() {
+            templates.clear();
+            itemOrder.length = 0;
+            counter = 0;
+            primitiveFieldKey.set(undefined);
+        },
+    };
+}
+/**
+ * Form-scoped registry of per-array durable state. One slot per array path
+ * (e.g. 'members', 'team.members', 'orders.lineItems'). Survives
+ * `ArrayFieldComponent` lifecycle, dies with the `DynamicForm`. Cleared on
+ * schema swap by the `formSetup` effect in `FormStateManager`.
+ *
+ * `ArrayFieldComponent` injects this service and obtains its slot via
+ * `slotFor(arrayPath)` on mount. Replaces the prior per-component
+ * `ARRAY_TEMPLATE_REGISTRY` + `ARRAY_ITEM_ID_GENERATOR` providers.
+ */
+class ArrayItemRegistryService {
+    slots = new Map();
+    /** Get-or-create a slot for the array at the given path. */
+    slotFor(arrayPath) {
+        let slot = this.slots.get(arrayPath);
+        if (!slot) {
+            slot = createSlot();
+            this.slots.set(arrayPath, slot);
+        }
+        return slot;
+    }
+    /** Drop all slots — called from the `formSetup` effect on schema change. */
+    clearAll() {
+        for (const slot of this.slots.values())
+            slot.clear();
+        this.slots.clear();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: ArrayItemRegistryService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: ArrayItemRegistryService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: ArrayItemRegistryService, decorators: [{
+            type: Injectable
+        }] });
+
 class SchemaRegistryService {
     registeredSchemas = new Map();
     /**
@@ -4860,8 +4931,6 @@ class HttpConditionFunctionCacheService {
  * );
  * // user.value() keeps the old user data during loading transitions
  * ```
- *
- * @experimental Uses Angular's experimental resource composition APIs.
  */
 function withPreviousValue(input) {
     const derived = linkedSignal({ ...(ngDevMode ? { debugName: "derived" } : /* istanbul ignore next */ {}), source: input.snapshot,
@@ -8794,6 +8863,40 @@ function createRenderReadySignal(inputs, definition) {
         return requiredInputs.every((inputName) => currentInputs[inputName] !== undefined);
     });
 }
+/**
+ * Reads the current hidden state from mapper inputs. Uniform across all field
+ * types — value-bearing leaves source from the `FieldTree`'s `state.hidden()`
+ * (where Angular Signal Forms cascades `hidden(path, …)`), and non-field outputs
+ * (button/text/containers) source from the mapper's explicit `inputs.hidden`.
+ *
+ * The `@if (!field.hidden())` gate at every `*dfFieldOutlet` consumption site uses
+ * this signal, removing hidden fields from the DOM. That's required to silence
+ * Angular's `NG01916: Field 'X' is hidden but is being rendered` warning — and
+ * is the prescribed pattern from the
+ * [`hidden` API docs](https://angular.dev/api/forms/signals/hidden).
+ *
+ * Container internal state (e.g. an `ArrayFieldComponent`'s items + dynamic
+ * templates + id counter) survives this destroy/recreate via the form-scoped
+ * `ArrayItemRegistryService` keyed by array path.
+ */
+function createHiddenSignal(inputs) {
+    return computed(() => {
+        const currentInputs = inputs();
+        const fieldCandidate = currentInputs['field'];
+        // Value-bearing leaves expose `field` as a callable `FieldTree` whose invocation returns a
+        // `FieldState` with a `hidden` accessor. `isSignal()` doesn't recognise the Proxy-wrapped
+        // FieldTree (no SIGNAL symbol), so we duck-type the shape and call `state.hidden()` directly.
+        if (typeof fieldCandidate === 'function') {
+            const state = fieldCandidate();
+            if (state && typeof state.hidden === 'function') {
+                return state.hidden() === true;
+            }
+        }
+        // Non-value fields (button, text, containers) carry an explicit `hidden` input set by
+        // `applyHiddenLogic` based on the mapper-side evaluation.
+        return currentInputs['hidden'] === true;
+    });
+}
 /**
  * Resolves a single field definition to a ResolvedField using RxJS.
  * Loads the component asynchronously and maps inputs in the injection context.
@@ -8830,6 +8933,7 @@ function resolveField(fieldDef, context) {
             injector: context.injector,
             inputs,
             renderReady: createRenderReadySignal(inputs, definition),
+            hidden: createHiddenSignal(inputs),
         };
     }), catchError((error) => {
         // Only call onError if component is not destroyed to avoid accessing cleaned-up state
@@ -8866,6 +8970,7 @@ function resolveFieldSync(fieldDef, context) {
         injector: context.injector,
         inputs,
         renderReady: createRenderReadySignal(inputs, definition),
+        hidden: createHiddenSignal(inputs),
     };
 }
 /**
@@ -8892,13 +8997,14 @@ function reconcileFields(prev, curr) {
             }
             // Same component instance + injector, but the field definition changed.
             // Preserve component identity (so ngComponentOutlet keeps the same instance)
-            // while swapping in the freshly-mapped inputs/renderReady signals so prop
-            // updates (e.g. select options) reach the component.
+            // while swapping in the freshly-mapped inputs/renderReady/hidden signals
+            // so prop updates (e.g. select options) reach the component.
             return {
                 ...existing,
                 fieldDef: field.fieldDef,
                 inputs: field.inputs,
                 renderReady: field.renderReady,
+                hidden: field.hidden,
             };
         }
         // New field, type changed, or context changed (new injector) - use new field
@@ -10083,6 +10189,12 @@ class FormStateManager {
     eventBus = inject(EventBus);
     functionRegistry = inject(FunctionRegistryService);
     schemaRegistry = inject(SchemaRegistryService);
+    // Optional so unit-test setups that drive FormStateManager directly without provideDynamicFormDI()
+    // (e.g. mocked RootFormRegistryService specs) don't have to manually wire the registry. Real
+    // DynamicForm usage always provides it via coreProviders; if you hit the dev warning below in
+    // your own setup, you're using DynamicForm without provideDynamicFormDI() — fix the providers
+    // chain rather than ignoring it.
+    arrayItemRegistry = inject(ArrayItemRegistryService, { optional: true });
     /** Host component dependencies (config, formOptions, value). */
     deps = (() => {
         const raw = inject(FORM_STATE_DEPS);
@@ -10709,12 +10821,24 @@ class FormStateManager {
             }
         });
         // Schema change resets the saved store + transition tracker so values from a stale schema
-        // can't leak into the new one.
+        // can't leak into the new one. Also drops every per-array slot in the registry so a fresh
+        // schema starts with an empty template/itemOrder/id-counter state.
+        let warnedAboutMissingArrayRegistry = false;
         explicitEffect([this.formSetup], () => {
             this.prevFieldStateSnapshot.set({});
             if (Object.keys(this.excludedValueStore()).length > 0) {
                 this.excludedValueStore.set({});
             }
+            if (this.arrayItemRegistry) {
+                this.arrayItemRegistry.clearAll();
+            }
+            else if (DEV_MODE && !warnedAboutMissingArrayRegistry) {
+                warnedAboutMissingArrayRegistry = true;
+                this.logger.warn('ArrayItemRegistryService was not provided to FormStateManager. ' +
+                    'Array fields will lose dynamically-added item templates across hide/show cycles. ' +
+                    'This usually means DynamicForm was bootstrapped without provideDynamicFormDI() — ' +
+                    'check your providers chain.');
+            }
         });
         // Outward sync uses boundFormValue (honors only explicit excludeValueIf* opt-ins) so
         // global defaults that target submission output don't reshape the host's bound model.
@@ -14452,6 +14576,7 @@ function coreProviders() {
             deps: [FormStateManager],
         },
         FieldContextRegistryService,
+        ArrayItemRegistryService,
         {
             provide: DEFAULT_PROPS,
             useFactory: (stateManager) => computed(() => stateManager.activeConfig()?.defaultProps),
@@ -14892,7 +15017,13 @@ class DynamicForm {
         }
         @case ('non-paged') {
           @for (field of resolvedFields(); track field.key) {
-            <ng-container *dfFieldOutlet="field; environmentInjector: environmentInjector" />
+            <!-- @if + DfFieldOutlet's own renderReady-&-!hidden gate together silence NG01916:
+                 the template @if removes the host from the DOM (Angular's prescribed pattern), and
+                 the directive's gate stops a same-CD-pass mount before [formField] can warn.
+                 Don't dedupe one without the other — see DfFieldOutlet.renderReady. -->
+            @if (!field.hidden()) {
+              <ng-container *dfFieldOutlet="field; environmentInjector: environmentInjector" />
+            }
           }
         }
         @default {
@@ -14912,7 +15043,13 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImpor
         }
         @case ('non-paged') {
           @for (field of resolvedFields(); track field.key) {
-            <ng-container *dfFieldOutlet="field; environmentInjector: environmentInjector" />
+            <!-- @if + DfFieldOutlet's own renderReady-&-!hidden gate together silence NG01916:
+                 the template @if removes the host from the DOM (Angular's prescribed pattern), and
+                 the directive's gate stops a same-CD-pass mount before [formField] can warn.
+                 Don't dedupe one without the other — see DfFieldOutlet.renderReady. -->
+            @if (!field.hidden()) {
+              <ng-container *dfFieldOutlet="field; environmentInjector: environmentInjector" />
+            }
           }
         }
         @default {
@@ -15495,8 +15632,14 @@ function containerFieldMapper(fieldDef) {
  * ```
  */
 /**
- * Base field type definitions for fields that don't use the `field` input.
- * Used by display-only fields like `text` that render immediately without
+ * Base for container field types that consume the mapper-emitted `field` input
+ * (row, group, array, page, container).
+ */
+const CONTAINER_FIELD_TYPES_BASE = {
+    renderReadyWhen: ['field'],
+};
+/**
+ * Base for display-only fields (`text`) that render immediately without
  * waiting for form value integration.
  */
 const DISPLAY_FIELD_TYPES_BASE = {
@@ -15515,31 +15658,35 @@ const BUILT_IN_FIELDS = [
         // `row` is a virtual field type: it maps to ContainerFieldComponent, and
         // the rowFieldMapper injects a `{ type: 'row' }` wrapper so the container
         // renders the flex/grid layout via RowWrapperComponent.
-        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-Pcxg5PQu.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-VHaBk_1l.mjs'),
         mapper: rowFieldMapper,
         valueHandling: 'flatten',
+        ...CONTAINER_FIELD_TYPES_BASE,
     },
     {
         name: 'group',
-        loadComponent: () => import('./ng-forge-dynamic-forms-group-field.component-fzKwPrQr.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-group-field.component-BvTQwoLg.mjs'),
         mapper: groupFieldMapper,
         valueHandling: 'include',
+        ...CONTAINER_FIELD_TYPES_BASE,
     },
     {
         name: 'array',
-        loadComponent: () => import('./ng-forge-dynamic-forms-array-field.component-DJ-LiLm_.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-array-field.component-BgCrTME1.mjs'),
         mapper: arrayFieldMapper,
         valueHandling: 'include',
+        ...CONTAINER_FIELD_TYPES_BASE,
     },
     {
         name: 'page',
-        loadComponent: () => import('./ng-forge-dynamic-forms-page-field.component-BX4R9GGa.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-page-field.component-DDzmhJNn.mjs'),
         mapper: pageFieldMapper,
         valueHandling: 'flatten',
+        ...CONTAINER_FIELD_TYPES_BASE,
     },
     {
         name: 'text',
-        loadComponent: () => import('./ng-forge-dynamic-forms-text-field.component-B9SK8Vun.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-text-field.component-Bo4zNJXY.mjs'),
         mapper: textFieldMapper,
         valueHandling: 'exclude',
         ...DISPLAY_FIELD_TYPES_BASE,
@@ -15551,15 +15698,16 @@ const BUILT_IN_FIELDS = [
     },
     {
         name: 'container',
-        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-Pcxg5PQu.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-VHaBk_1l.mjs'),
         mapper: containerFieldMapper,
         valueHandling: 'flatten',
+        ...CONTAINER_FIELD_TYPES_BASE,
     },
 ];
 const BUILT_IN_WRAPPERS = [
     {
         wrapperName: 'css',
-        loadComponent: () => import('./ng-forge-dynamic-forms-css-wrapper.component-CJACCIEK.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-css-wrapper.component-BOdw40ZF.mjs'),
     },
     {
         wrapperName: 'row',
@@ -16633,5 +16781,5 @@ function extractErrorParams(error) {
  * Generated bundle index. Do not edit.
  */
 
-export { ShiftArrayItemEvent as $, ARRAY_CONTEXT as A, BUILT_IN_FIELDS as B, CONTAINER_FIELD_PROCESSORS as C, DynamicFormLogger as D, EventBus as E, FIELD_SIGNAL_CONTEXT as F, GROUP_CONTEXT as G, DEFAULT_VALIDATION_MESSAGES as H, DynamicForm as I, DynamicFormError as J, EventDispatcher as K, FIELD_REGISTRY as L, FORM_OPTIONS as M, FormClearEvent as N, FormResetEvent as O, INITIALIZATION_TIMEOUT_MS as P, InsertArrayItemEvent as Q, RootFormRegistryService as R, MoveArrayItemEvent as S, NextPageEvent as T, NoopLogger as U, PageChangeEvent as V, WRAPPER_AUTO_ASSOCIATIONS as W, PopArrayItemEvent as X, PrependArrayItemEvent as Y, PreviousPageEvent as Z, RemoveAtIndexEvent as _, DEFAULT_WRAPPERS as a, SubmitEvent as a0, WRAPPER_REGISTRY as a1, applyMetaToElement as a2, applyValidator as a3, applyValidators as a4, arrayEvent as a5, arrayFieldMapper as a6, baseFieldMapper as a7, buildBaseInputs as a8, containerFieldMapper as a9, provideDynamicForm as aA, resolveNextButtonDisabled as aB, resolveNonFieldDisabled as aC, resolveNonFieldHidden as aD, resolveSubmitButtonDisabled as aE, resolveTokens as aF, rowFieldMapper as aG, textFieldMapper as aH, toReadonlyFieldTree as aI, withEventFormValue as aJ, withLoggerConfig as aK, withPreviousValue as aL, withValidationExecutionDefaults as aM, withValueExclusionDefaults as aN, wrapperProps as aO, createField as aa, createWrappers as ab, evaluateNonFieldDisabled as ac, evaluateNonFieldHidden as ad, field as ae, formConfig as af, getArrayLength as ag, groupFieldMapper as ah, hasFormValue as ai, interpolateParams as aj, isArrayField as ak, isCheckedField as al, isContainerField as am, isContainerTypedField as an, isDisplayOnlyField as ao, isFormStateCondition as ap, isLeafField as aq, isPageField as ar, isRowField as as, isSimplifiedArrayField as at, isValueBearingField as au, isValueField as av, isWrapperTypeDefinition as aw, isWrappersBundle as ax, omit as ay, pageFieldMapper as az, isSameWrapperChain as b, createFieldResolutionPipe as c, derivedFromDeferred as d, createWrapperChainController as e, DfFieldOutlet as f, isEqual as g, createSchemaFromFields as h, injectFieldRegistry as i, createRenderReadySignal as j, ARRAY_TEMPLATE_REGISTRY as k, ARRAY_ITEM_ID_GENERATOR as l, mapFieldToInputs as m, getNormalizedArrayMetadata as n, getFieldValueHandling as o, getFieldDefaultValue as p, isGroupField as q, resolveWrappers as r, createArrayItemIdGenerator as s, ComponentInitializedEvent as t, DynamicTextPipe as u, validatePageNesting as v, dynamicTextToObservable as w, AppendArrayItemEvent as x, ConsoleLogger as y, DEFAULT_PROPS as z };
-//# sourceMappingURL=ng-forge-dynamic-forms-ng-forge-dynamic-forms-o3rJX4vG.mjs.map
+export { SubmitEvent as $, ARRAY_CONTEXT as A, BUILT_IN_FIELDS as B, CONTAINER_FIELD_PROCESSORS as C, DynamicFormLogger as D, EventBus as E, FIELD_SIGNAL_CONTEXT as F, GROUP_CONTEXT as G, DynamicForm as H, DynamicFormError as I, EventDispatcher as J, FIELD_REGISTRY as K, FORM_OPTIONS as L, FormClearEvent as M, FormResetEvent as N, INITIALIZATION_TIMEOUT_MS as O, InsertArrayItemEvent as P, MoveArrayItemEvent as Q, RootFormRegistryService as R, NextPageEvent as S, NoopLogger as T, PageChangeEvent as U, PopArrayItemEvent as V, WRAPPER_AUTO_ASSOCIATIONS as W, PrependArrayItemEvent as X, PreviousPageEvent as Y, RemoveAtIndexEvent as Z, ShiftArrayItemEvent as _, DEFAULT_WRAPPERS as a, WRAPPER_REGISTRY as a0, applyMetaToElement as a1, applyValidator as a2, applyValidators as a3, arrayEvent as a4, arrayFieldMapper as a5, baseFieldMapper as a6, buildBaseInputs as a7, containerFieldMapper as a8, createField as a9, resolveNextButtonDisabled as aA, resolveNonFieldDisabled as aB, resolveNonFieldHidden as aC, resolveSubmitButtonDisabled as aD, resolveTokens as aE, rowFieldMapper as aF, textFieldMapper as aG, toReadonlyFieldTree as aH, withEventFormValue as aI, withLoggerConfig as aJ, withPreviousValue as aK, withValidationExecutionDefaults as aL, withValueExclusionDefaults as aM, wrapperProps as aN, createWrappers as aa, evaluateNonFieldDisabled as ab, evaluateNonFieldHidden as ac, field as ad, formConfig as ae, getArrayLength as af, groupFieldMapper as ag, hasFormValue as ah, interpolateParams as ai, isArrayField as aj, isCheckedField as ak, isContainerField as al, isContainerTypedField as am, isDisplayOnlyField as an, isFormStateCondition as ao, isLeafField as ap, isPageField as aq, isRowField as ar, isSimplifiedArrayField as as, isValueBearingField as at, isValueField as au, isWrapperTypeDefinition as av, isWrappersBundle as aw, omit as ax, pageFieldMapper as ay, provideDynamicForm as az, isSameWrapperChain as b, createFieldResolutionPipe as c, derivedFromDeferred as d, createWrapperChainController as e, DfFieldOutlet as f, isEqual as g, createSchemaFromFields as h, injectFieldRegistry as i, createHiddenSignal as j, createRenderReadySignal as k, ArrayItemRegistryService as l, mapFieldToInputs as m, getNormalizedArrayMetadata as n, getFieldValueHandling as o, getFieldDefaultValue as p, isGroupField as q, resolveWrappers as r, ComponentInitializedEvent as s, DynamicTextPipe as t, dynamicTextToObservable as u, validatePageNesting as v, AppendArrayItemEvent as w, ConsoleLogger as x, DEFAULT_PROPS as y, DEFAULT_VALIDATION_MESSAGES as z };
+//# sourceMappingURL=ng-forge-dynamic-forms-ng-forge-dynamic-forms-BAPGCjUs.mjs.map