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

package/fesm2022/{ng-forge-dynamic-forms-ng-forge-dynamic-forms-DWPPLOrV.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';
@@ -139,6 +139,32 @@ const FIELD_SIGNAL_CONTEXT = new InjectionToken('FIELD_SIGNAL_CONTEXT', {
  * ```
  */
 const ARRAY_CONTEXT = new InjectionToken('ARRAY_CONTEXT');
+/**
+ * Injection token for providing group ancestry to mappers and components.
+ *
+ * Re-provided in two places:
+ * 1. `GroupFieldComponent` provides a context whose `groupPath()` is the
+ *    parent path extended by its own key (e.g. `'address'` or `'user.address'`).
+ * 2. `createArrayItemInjector` provides a sentinel with an empty `groupPath`,
+ *    resetting the chain at array boundaries — descendants of an array item
+ *    that re-enter a group compose paths INSIDE the array item, matching the
+ *    property-derivation collector's keying.
+ *
+ * `mapFieldToInputs` reads this to scope DOM IDs and override-store keys so
+ * the same leaf key can appear in different groups without colliding (#401).
+ *
+ * Inject with `{ optional: true }` because top-level fields with no group
+ * ancestor (and no enclosing array) won't have the token provided. The token
+ * IS present for fields inside an array even when no inner group exists — the
+ * array-boundary sentinel makes injection succeed with an empty `groupPath`.
+ */
+// No factory: GROUP_CONTEXT is optional-by-design — `GroupFieldComponent` and
+// `createArrayItemInjector` re-provide it where it makes sense, and consumers
+// inject with `{ optional: true }` to handle the top-level case. Mirrors the
+// ARRAY_CONTEXT pattern. Adding a throwing factory here fires even when
+// injected optionally (Angular still evaluates the tree-shakable factory
+// before honoring `optional`), so non-group fields would crash on every render.
+const GROUP_CONTEXT = new InjectionToken('GROUP_CONTEXT');
 /**
  * Injection token for form-level default props.
  *
@@ -226,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];
 }
 
 /**
@@ -481,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
@@ -723,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.
@@ -743,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
@@ -768,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
@@ -813,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'];
@@ -2748,16 +2766,25 @@ function evaluateCondition(expression, context) {
         case 'javascript':
             return evaluateJavaScriptExpression(expression, context);
         case 'custom': {
-            const customFn = context.customFunctions?.[expression.functionName];
+            // Read both keys via cast — the XOR type narrows to `never` when both
+            // would be truthy, but JSON-loaded configs can produce that state at
+            // runtime. We accept it here, warn, and let inline win.
+            const bothSet = expression;
+            const inlineFn = bothSet.fn;
+            const registeredName = bothSet.functionName;
+            if (inlineFn && registeredName) {
+                context.logger.warn('Both "fn" and "functionName" are set on custom condition. Inline "fn" takes precedence; "functionName" is ignored.');
+            }
+            const customFn = inlineFn ?? (registeredName ? context.customFunctions?.[registeredName] : undefined);
             if (!customFn) {
-                context.logger.error('Custom function not found:', expression.functionName);
+                context.logger.error('Custom function not found:', registeredName);
                 return false;
             }
             try {
                 return !!customFn(context);
             }
             catch (error) {
-                context.logger.error('Error executing custom function:', expression.functionName, error);
+                context.logger.error('Error executing custom function:', registeredName ?? '<inline>', error);
                 return false;
             }
         }
@@ -2766,7 +2793,7 @@ function evaluateCondition(expression, context) {
         case 'or':
             return evaluateOrCondition(expression, context);
         case 'http':
-            context.logger.warn('[Dynamic Forms] HTTP conditions are resolved asynchronously via createHttpConditionLogicFunction(). ' +
+            context.logger.warn('HTTP conditions are resolved asynchronously via createHttpConditionLogicFunction(). ' +
                 'When used inside and/or composites, the HTTP result is not available synchronously. Returning false.');
             return false;
         case 'async':
@@ -4145,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-B9v_1shD.mjs').then(m => m.default)], () => [import('./ng-forge-dynamic-forms-page-field.component-B9v_1shD.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-B9v_1shD.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) {
@@ -4579,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();
     /**
@@ -4628,7 +4734,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImpor
  * Use this guard when you need type-safe access to `FunctionHttpValidatorConfig` properties.
  */
 function isFunctionHttpValidator(config) {
-    return 'functionName' in config && !!config.functionName;
+    const c = config;
+    return typeof c.functionName === 'string' || (c.fn !== null && typeof c.fn === 'object');
 }
 
 /**
@@ -4824,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,
@@ -5047,11 +5152,18 @@ function createAsyncConditionLogicFunction(condition) {
     const cacheService = inject(AsyncConditionFunctionCacheService);
     const pendingValue = condition.pendingValue ?? false;
     const debounceMs = condition.debounceMs ?? 300;
-    // Check function cache
-    const cacheKey = stableStringify(condition);
-    const cached = cacheService.asyncConditionFunctionCache.get(cacheKey);
-    if (cached) {
-        return cached;
+    if (condition.asyncFn && condition.asyncFunctionName) {
+        logger.warn('Both "asyncFn" and "asyncFunctionName" are set on async condition. Inline "asyncFn" takes precedence; "asyncFunctionName" is ignored.');
+    }
+    // Skip cross-condition caching when an inline function is used: stableStringify
+    // cannot distinguish two different inline functions, which would cause cache hits
+    // to wrongly reuse a LogicFn closing over a different function reference.
+    const cacheKey = condition.asyncFn ? undefined : stableStringify(condition);
+    if (cacheKey !== undefined) {
+        const cached = cacheService.asyncConditionFunctionCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
     }
     // Each condition needs its own per-field signal store.
     const perFunctionSignalStore = new Map();
@@ -5076,8 +5188,10 @@ function createAsyncConditionLogicFunction(condition) {
                 const asyncResource = rxResource({
                     params: () => debouncedTrigger() ?? undefined,
                     stream: ({ params: triggerKey }) => {
-                        // Look up the async function at call time (fresh reference)
-                        const asyncFn = functionRegistry.getAsyncConditionFunction(condition.asyncFunctionName);
+                        // Inline `asyncFn` wins; otherwise look up the registered function at call time
+                        // (fresh reference, in case the registry was updated after LogicFn creation).
+                        const asyncFn = condition.asyncFn ??
+                            (condition.asyncFunctionName ? functionRegistry.getAsyncConditionFunction(condition.asyncFunctionName) : undefined);
                         if (!asyncFn) {
                             logger.warn(`Async Condition - function '${condition.asyncFunctionName}' not found. ` +
                                 `Register it in customFnConfig.asyncConditions.`);
@@ -5129,7 +5243,9 @@ function createAsyncConditionLogicFunction(condition) {
         });
         return resultResource.value();
     };
-    cacheService.asyncConditionFunctionCache.set(cacheKey, fn);
+    if (cacheKey !== undefined) {
+        cacheService.asyncConditionFunctionCache.set(cacheKey, fn);
+    }
     return fn;
 }
 
@@ -5764,12 +5880,12 @@ function applyCustomValidator(config, fieldPath) {
     if (config.expression) {
         validatorFn = createExpressionValidator(config);
     }
-    else if (config.functionName) {
+    else if (config.fn || config.functionName) {
         validatorFn = createFunctionValidator(config);
     }
     else {
         const logger = inject(DynamicFormLogger);
-        logger.warn('Custom validator must have either "expression" or "functionName"');
+        logger.warn('Custom validator must have one of "expression", "functionName", or "fn"');
         return;
     }
     const whenLogic = createConditionalLogic(config.when);
@@ -5781,6 +5897,13 @@ function applyCustomValidator(config, fieldPath) {
 }
 function createFunctionValidator(config) {
     const logger = inject(DynamicFormLogger);
+    if (config.fn && config.functionName) {
+        logger.warn('Both "fn" and "functionName" are set on custom validator. Inline "fn" takes precedence; "functionName" is ignored.');
+    }
+    if (config.fn) {
+        const inlineFn = config.fn;
+        return (ctx) => inlineFn(ctx, config.params);
+    }
     const functionName = config.functionName;
     if (!functionName) {
         logger.warn('Custom validator missing functionName');
@@ -5841,10 +5964,24 @@ function createExpressionValidator(config) {
  * - onError: Optional handler for resource errors
  */
 function applyAsyncValidator(config, fieldPath) {
-    const registry = inject(FunctionRegistryService);
-    const validatorConfig = registry.getAsyncValidator(config.functionName);
-    if (!validatorConfig) {
-        throw new DynamicFormError(`Async validator "${config.functionName}" not found. Register it with customFnConfig.asyncValidators.`);
+    if (config.fn && config.functionName) {
+        const logger = inject(DynamicFormLogger);
+        logger.warn('Both "fn" and "functionName" are set on async validator. Inline "fn" takes precedence; "functionName" is ignored.');
+    }
+    let validatorConfig;
+    if (config.fn) {
+        validatorConfig = config.fn;
+    }
+    else if (config.functionName) {
+        const registry = inject(FunctionRegistryService);
+        validatorConfig = registry.getAsyncValidator(config.functionName);
+        if (!validatorConfig) {
+            throw new DynamicFormError(`Async validator "${config.functionName}" not found. Register it with customFnConfig.asyncValidators.`);
+        }
+    }
+    else {
+        // XOR type rejects this at compile time; JSON-loaded configs can still reach here at runtime.
+        throw new DynamicFormError('Async validator requires one of "functionName" or "fn".');
     }
     const whenLogic = createConditionalLogic(config.when);
     const asyncOptions = {
@@ -5866,10 +6003,16 @@ function applyAsyncValidator(config, fieldPath) {
 function applyUnifiedHttpValidator(config, fieldPath) {
     if (isFunctionHttpValidator(config)) {
         applyFunctionHttpValidator(config, fieldPath);
+        return;
     }
-    else {
-        applyDeclarativeHttpValidator(config, fieldPath);
+    // Declarative path requires both `http` and `responseMapping` — reject early
+    // for JSON-loaded configs that have neither side fully populated. The
+    // discriminated union forbids this at compile time.
+    const declarative = config;
+    if (!declarative.http || !declarative.responseMapping) {
+        throw new DynamicFormError('HTTP validator requires one of "functionName" / "fn" (function-based) or "http" + "responseMapping" (declarative).');
     }
+    applyDeclarativeHttpValidator(config, fieldPath);
 }
 /**
  * Apply function-based HTTP validator to field path using Angular's public validateHttp() API.
@@ -5880,10 +6023,24 @@ function applyUnifiedHttpValidator(config, fieldPath) {
  * - onError: Optional handler for HTTP errors
  */
 function applyFunctionHttpValidator(config, fieldPath) {
-    const registry = inject(FunctionRegistryService);
-    const httpValidatorConfig = registry.getHttpValidator(config.functionName);
-    if (!httpValidatorConfig) {
-        throw new DynamicFormError(`HTTP validator "${config.functionName}" not found. Register it with customFnConfig.httpValidators.`);
+    if (config.fn && config.functionName) {
+        const logger = inject(DynamicFormLogger);
+        logger.warn('Both "fn" and "functionName" are set on HTTP validator. Inline "fn" takes precedence; "functionName" is ignored.');
+    }
+    let httpValidatorConfig;
+    if (config.fn) {
+        httpValidatorConfig = config.fn;
+    }
+    else if (config.functionName) {
+        const registry = inject(FunctionRegistryService);
+        httpValidatorConfig = registry.getHttpValidator(config.functionName);
+        if (!httpValidatorConfig) {
+            throw new DynamicFormError(`HTTP validator "${config.functionName}" not found. Register it with customFnConfig.httpValidators.`);
+        }
+    }
+    else {
+        // XOR type rejects this at compile time; JSON-loaded configs can still reach here at runtime.
+        throw new DynamicFormError('HTTP validator requires one of "functionName" or "fn".');
     }
     const whenLogic = createConditionalLogic(config.when);
     const httpOptions = {
@@ -8467,22 +8624,31 @@ const PLACEHOLDER_INDEX = '$';
 /**
  * Builds a property override store key for a field.
  *
- * For non-array fields, the key is just the field's key.
- * For array item fields, the key includes the array path and either a concrete
- * index (e.g., `contacts.0.email`) or the `$` placeholder (e.g., `contacts.$.email`).
+ * For non-array fields, the key is the dot-joined group ancestors plus the
+ * field's leaf key (e.g., `address.street` for `street` inside `address`).
+ * For array item fields, the key includes the array path, either a concrete
+ * index or the `$` placeholder, and any group ancestors INSIDE the array
+ * item (e.g., `contacts.0.email`, `contacts.$.email`, or
+ * `contacts.0.profile.email` for a group nested under each contact).
+ *
+ * `groupPath` matches the form-value path of nested groups (collector resets
+ * it at array boundaries — see `property-derivation-collector.ts`), so the
+ * resulting key always mirrors the field's location in `formValue`.
  *
  * @param arrayKey - The array field key (e.g., 'contacts'), or undefined for non-array fields
  * @param index - The array item index, `PLACEHOLDER_INDEX` for the wildcard format, or undefined for non-array fields
  * @param fieldKey - The leaf field key (e.g., 'email')
- * @returns The store key (e.g., 'email', 'contacts.0.email', or 'contacts.$.email')
+ * @param groupPath - Dot-joined group ancestors scoped to the current array item (or top-level), or undefined when not inside any group
+ * @returns The store key (e.g., 'email', 'address.street', 'contacts.0.email', 'contacts.$.profile.email')
  *
  * @public
  */
-function buildPropertyOverrideKey(arrayKey, index, fieldKey) {
+function buildPropertyOverrideKey(arrayKey, index, fieldKey, groupPath) {
+    const leafScope = groupPath ? `${groupPath}.${fieldKey}` : fieldKey;
     if (arrayKey != null && index != null) {
-        return `${arrayKey}.${index}.${fieldKey}`;
+        return `${arrayKey}.${index}.${leafScope}`;
     }
-    return fieldKey;
+    return leafScope;
 }
 
 /**
@@ -8563,6 +8729,25 @@ function applyIndexSuffix(inputs, index) {
         key: `${key}_${index}`,
     };
 }
+/**
+ * Prefixes the key with the underscored group ancestor path so that the same
+ * leaf key inside different groups produces distinct DOM IDs (issue #401).
+ * Form-schema keys remain clean — only the rendered `key` input is rewritten.
+ *
+ * Dots in the group path become underscores, then the original leaf key is
+ * appended: `(groupPath='user.address', inputs.key='street')` →
+ * `inputs.key = 'user_address_street'`.
+ */
+function applyGroupPrefix(inputs, groupPath) {
+    const key = inputs['key'];
+    if (typeof key !== 'string' || groupPath.length === 0) {
+        return inputs;
+    }
+    return {
+        ...inputs,
+        key: `${groupPath.replace(/\./g, '_')}_${key}`,
+    };
+}
 /**
  * Main field mapper function that uses the field registry to get the appropriate mapper
  * based on the field's type property.
@@ -8599,6 +8784,10 @@ function mapFieldToInputs(fieldDef, fieldRegistry) {
     // Check if we're inside an array item context - if so, we need to suffix keys
     // Optional because ARRAY_CONTEXT is only provided inside array item injectors
     const arrayContext = inject(ARRAY_CONTEXT, { optional: true });
+    // Check if we're inside a group context - if so, prefix the key with the group path
+    // so overlapping leaf keys across groups produce distinct DOM IDs (issue #401).
+    // Optional because GROUP_CONTEXT is only provided by GroupFieldComponent.
+    const groupContext = inject(GROUP_CONTEXT, { optional: true });
     // Inject the property override store for property derivation overrides
     // Always available — provided at the DynamicForm component level via provideDynamicFormDI
     const store = inject(PROPERTY_OVERRIDE_STORE);
@@ -8609,6 +8798,7 @@ function mapFieldToInputs(fieldDef, fieldRegistry) {
     // Check that arrayContext exists and has a valid index signal (guards against mock injectors)
     const indexSignal = arrayContext?.index;
     const hasArrayContext = indexSignal !== undefined && isSignal(indexSignal);
+    const hasGroupContext = groupContext != null;
     // Fast-path check for property overrides: only fields whose definition declares
     // a property-derivation enter the computed() wrapper. We inspect the FieldDef
     // directly rather than asking the store, because the store's registration
@@ -8617,7 +8807,7 @@ function mapFieldToInputs(fieldDef, fieldRegistry) {
     // collector apply the same inclusion rule, so the answers always agree.
     const hasOverrides = fieldHasPropertyDerivations(fieldDef);
     // Fast path: no transformations needed
-    if (!hasPropsForwarding && !hasArrayContext && !hasOverrides) {
+    if (!hasPropsForwarding && !hasArrayContext && !hasGroupContext && !hasOverrides) {
         return mapperResult;
     }
     // Wrap in computed to apply transformations
@@ -8627,18 +8817,34 @@ function mapFieldToInputs(fieldDef, fieldRegistry) {
         if (hasPropsForwarding) {
             inputs = mergeForwardedPropsToMeta(inputs, propsToMeta);
         }
+        // Apply group prefix BEFORE array suffix so the resulting key reads as
+        // `{groupPath}_{key}_{index}` (e.g. `address_street_0`) — matching the
+        // form-value path order: group → leaf → array index.
+        if (hasGroupContext) {
+            // Non-null after the hasGroupContext guard.
+            inputs = applyGroupPrefix(inputs, groupContext.groupPath());
+        }
         // Apply index suffix for array items
         if (hasArrayContext) {
             const index = indexSignal();
             inputs = applyIndexSuffix(inputs, index);
         }
-        // Apply property overrides from the store (AFTER all static transformations)
+        // Apply property overrides from the store (AFTER all static transformations).
+        //
+        // INVARIANT: the store key MUST be built from `fieldDef.key` + the group/array
+        // ancestry (via buildPropertyOverrideKey) — NEVER from the DOM-scoped
+        // `inputs['key']` produced by applyGroupPrefix/applyIndexSuffix above. The
+        // collector (property-derivation-collector.ts) registers using the same
+        // shape; if these drift, overrides silently miss their target.
         if (hasOverrides) {
-            // Build the store key inside computed() so index signal read establishes reactive dependency
-            // Safe to access arrayContext/indexSignal directly — hasArrayContext already confirmed they exist
+            // Build inside computed() so the index/group signals establish reactive deps.
+            // GROUP_CONTEXT resets at array boundaries (see create-array-item-injector.ts),
+            // so groupPath() represents ancestors inside the current array item (or
+            // top-level groups when not in an array) — matching the collector.
+            const groupPath = hasGroupContext ? groupContext.groupPath() : undefined;
             const key = hasArrayContext
-                ? buildPropertyOverrideKey(arrayContext.arrayKey, indexSignal(), fieldDef.key)
-                : fieldDef.key;
+                ? buildPropertyOverrideKey(arrayContext.arrayKey, indexSignal(), fieldDef.key, groupPath || undefined)
+                : buildPropertyOverrideKey(undefined, undefined, fieldDef.key, groupPath || undefined);
             const overrides = store.getOverrides(key)();
             inputs = applyPropertyOverrides(inputs, overrides);
         }
@@ -8657,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.
@@ -8693,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
@@ -8729,6 +8970,7 @@ function resolveFieldSync(fieldDef, context) {
         injector: context.injector,
         inputs,
         renderReady: createRenderReadySignal(inputs, definition),
+        hidden: createHiddenSignal(inputs),
     };
 }
 /**
@@ -8755,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
@@ -9079,15 +9322,32 @@ function injectFieldRegistry() {
  * Collects all field keys, types, and validates regex patterns from a field tree
  * by recursively traversing containers (page, row, group, array).
  *
- * @param collectKeys - Whether to add field keys to data.keys for duplicate detection.
- *   Set to false when inside an array container: array item fields share template keys
- *   across items by design (e.g. every item has 'name', 'email'), so they must not
- *   participate in global duplicate-key checking.
+ * Keys are scoped by their group ancestors (e.g. `address.city` instead of `city`),
+ * so the same leaf key can appear inside different groups without conflict. Page and
+ * row containers do not contribute to the path because they flatten their children
+ * into the parent scope. Array items are excluded entirely from key collection
+ * because they share template keys across items by design.
+ *
+ * Fields whose registered `valueHandling` is anything other than `include` (e.g.
+ * buttons with `exclude`, page/row with `flatten`) are not collected: they don't
+ * bind to a form-value path, so duplicate-key uniqueness isn't meaningful for them.
+ *
+ * @param collectKeys - When false, the entire subtree skips key collection (used
+ *   when descending into an array container).
  */
-function collectFieldData(fields, data, collectKeys = true) {
+function collectFieldData(fields, data, registry, pathPrefix, collectKeys = true) {
     for (const field of fields) {
-        if (collectKeys && field.key) {
-            data.keys.push(field.key);
+        // Defensively skip only known non-include modes — unexpected/missing
+        // valueHandling defaults back to participating in duplicate detection so a
+        // mis-registered field type doesn't silently drop from collision checks.
+        const valueHandling = field.type ? getFieldValueHandling(field.type, registry) : 'include';
+        const participatesInValue = valueHandling !== 'exclude' && valueHandling !== 'flatten';
+        if (collectKeys && field.key && participatesInValue) {
+            const scopedKey = pathPrefix ? `${pathPrefix}.${field.key}` : field.key;
+            data.keys.push(scopedKey);
+            // Project to the DOM-ID format (dots → underscores) so we can detect
+            // collisions like top-level `'foo_bar'` vs group `'foo'` + leaf `'bar'`.
+            data.domIds.push(scopedKey.replace(/\./g, '_'));
         }
         if (field.type) {
             data.types.add(field.type);
@@ -9107,13 +9367,16 @@ function collectFieldData(fields, data, collectKeys = true) {
             // Array item fields share template keys across items by design — stop collecting keys
             // once inside an array. Types and regex patterns are still validated.
             const childCollectKeys = collectKeys && field.type !== 'array';
+            // Only group containers extend the scoping path — page/row flatten into the parent
+            // scope, and array items use dynamic indices that aren't statically knowable.
+            const childPrefix = isGroupField(field) && field.key ? (pathPrefix ? `${pathPrefix}.${field.key}` : field.key) : pathPrefix;
             const children = normalizeFieldsArray(field.fields);
             for (const child of children) {
                 if (Array.isArray(child)) {
-                    collectFieldData(child, data, childCollectKeys);
+                    collectFieldData(child, data, registry, childPrefix, childCollectKeys);
                 }
                 else {
-                    collectFieldData([child], data, childCollectKeys);
+                    collectFieldData([child], data, registry, childPrefix, childCollectKeys);
                 }
             }
         }
@@ -9149,7 +9412,38 @@ function validateNoDuplicateKeys(allKeys) {
         const duplicateList = Array.from(duplicates)
             .map((k) => `'${k}'`)
             .join(', ');
-        throw new DynamicFormError(`Duplicate field keys detected: ${duplicateList}. Each field key must be unique within a form config.`);
+        throw new DynamicFormError(`Duplicate field keys detected: ${duplicateList}. Field keys must be unique within their group scope (the same key may appear inside different groups).`);
+    }
+}
+/**
+ * Validates that the underscore-projected DOM-ID namespace has no collisions.
+ *
+ * DOM IDs are built by underscore-joining the group ancestor path with the
+ * leaf key (e.g. `address_street`). Two scoped paths can land on the same
+ * DOM ID even when their form-value paths differ — e.g. a top-level key
+ * `'foo_bar'` and a leaf `'bar'` inside group `'foo'` both render as
+ * `id="foo_bar"`. The form-value-path check accepts this (paths are
+ * `'foo_bar'` vs `'foo.bar'` — distinct) but the rendered DOM would have
+ * duplicate IDs, breaking aria associations and CSS selectors.
+ *
+ * @throws {DynamicFormError} When two scoped paths project to the same DOM ID
+ */
+function validateNoDomIdCollisions(domIds) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const id of domIds) {
+        if (seen.has(id)) {
+            duplicates.add(id);
+        }
+        seen.add(id);
+    }
+    if (duplicates.size > 0) {
+        const duplicateList = Array.from(duplicates)
+            .map((k) => `'${k}'`)
+            .join(', ');
+        throw new DynamicFormError(`DOM id collision detected for: ${duplicateList}. Group-nested keys are joined with '_' to form DOM ids ` +
+            `(e.g. group 'foo' + leaf 'bar' renders as id='foo_bar'). A separate top-level key like 'foo_bar' or a different ` +
+            `group/leaf pair that underscores to the same string will produce duplicate ids. Rename one of the colliding keys.`);
     }
 }
 /**
@@ -9187,11 +9481,13 @@ function validateFieldTypesRegistered(allTypes, registry, logger) {
 function validateFormConfig(fields, registry, logger) {
     const data = {
         keys: [],
+        domIds: [],
         types: new Set(),
         regexErrors: [],
     };
-    collectFieldData(fields, data);
+    collectFieldData(fields, data, registry, '');
     validateNoDuplicateKeys(data.keys);
+    validateNoDomIdCollisions(data.domIds);
     validateFieldTypesRegistered(data.types, registry, logger);
     if (data.regexErrors.length > 0) {
         throw new DynamicFormError(data.regexErrors.length === 1
@@ -9893,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);
@@ -10519,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.
@@ -11036,15 +11350,18 @@ function computeValueFromEntry(entry, evalContext, options) {
     if (entry.expression) {
         return ExpressionParser.evaluate(entry.expression, evalContext);
     }
-    if (entry.functionName) {
-        const fn = options.derivationFunctions?.[entry.functionName];
+    if (entry.fn || entry.functionName) {
+        if (entry.fn && entry.functionName) {
+            evalContext.logger.warn(`Both "fn" and "functionName" are set on derivation for '${options.subject}'. Inline "fn" takes precedence; "functionName" is ignored.`);
+        }
+        const fn = entry.fn ?? (entry.functionName ? options.derivationFunctions?.[entry.functionName] : undefined);
         if (!fn) {
             const kind = options.functionKind ?? 'Derivation function';
             throw new DynamicFormError(`${kind} '${entry.functionName}' not found in customFnConfig.derivations`);
         }
         return fn(evalContext);
     }
-    throw new DynamicFormError(`Derivation for ${options.subject} has no value source. Specify 'value', 'expression', or 'functionName'.`);
+    throw new DynamicFormError(`Derivation for ${options.subject} has no value source. Specify 'value', 'expression', 'functionName', or 'fn'.`);
 }
 
 /**
@@ -11447,7 +11764,7 @@ function getEntriesForChangedFields$1(entries, changedFields) {
 function tryApplyDerivation(entry, context, chainContext) {
     const { derivationLogger } = context;
     // HTTP and async entries are processed asynchronously in their own streams — skip in sync loop
-    if (entry.http || entry.asyncFunctionName) {
+    if (entry.http || entry.asyncFunctionName || entry.asyncFn) {
         return { applied: false, fieldKey: entry.fieldKey };
     }
     // Check if this is an array field derivation (has '$' placeholder)
@@ -11754,9 +12071,11 @@ function formatDerivationError(entry, phase, message) {
         ? `expression: "${entry.expression.substring(0, 50)}${entry.expression.length > 50 ? '...' : ''}"`
         : entry.functionName
             ? `function: "${entry.functionName}"`
-            : entry.value !== undefined
-                ? 'static value'
-                : 'unknown source';
+            : entry.fn
+                ? 'inline fn'
+                : entry.value !== undefined
+                    ? 'static value'
+                    : 'unknown source';
     return `${ERROR_PREFIX$1} Failed to ${phase} derivation (field: ${entry.fieldKey}, ${source}): ${message}`;
 }
 /**
@@ -11825,7 +12144,7 @@ function shouldSkipForUserOverride(entry, resolvedFieldKey, context, chainContex
 function applyDerivationsForTrigger(collection, trigger, context, changedFields) {
     // Filter entries by trigger type, excluding HTTP and async entries (processed in async streams)
     const filteredEntries = collection.entries.filter((entry) => {
-        if (entry.http || entry.asyncFunctionName)
+        if (entry.http || entry.asyncFunctionName || entry.asyncFn)
             return false;
         if (trigger === 'onChange') {
             return !entry.trigger || entry.trigger === 'onChange';
@@ -11994,7 +12313,7 @@ function topologicalSort(entries) {
  * Combines:
  * - Explicit `dependsOn` (when provided, it takes precedence over auto-detection)
  * - Expression-detected dependencies (only used when `dependsOn` is empty)
- * - `'*'` wildcard for `functionName` (only when `dependsOn` is empty)
+ * - `'*'` wildcard for `functionName` / inline `fn` (only when `dependsOn` is empty)
  * - Condition expression dependencies (always included)
  *
  * @internal
@@ -12008,7 +12327,9 @@ function extractDependenciesFromConfig(config) {
         if (config.expression) {
             extractStringDependencies(config.expression).forEach((dep) => deps.add(dep));
         }
-        if (config.functionName) {
+        // Inline `fn` mirrors `functionName` semantics: without explicit dependsOn,
+        // assume the function may depend on anything in the form.
+        if (config.functionName || config.fn) {
             deps.add('*');
         }
     }
@@ -12018,6 +12339,32 @@ function extractDependenciesFromConfig(config) {
     return Array.from(deps);
 }
 
+/**
+ * Reads the optional inline `fn` property off a derivation config.
+ *
+ * `fn` only appears on the function-mode branch of the discriminated union, so
+ * call sites that need to copy it through unconditionally must widen via cast.
+ * This helper centralises the cast and keeps it read-only — no widening, no
+ * mutation. Returns `undefined` for any non-function-mode variant.
+ *
+ * @internal
+ */
+function extractInlineFn(config) {
+    return config.fn;
+}
+/**
+ * Reads the optional inline `asyncFn` property off a derivation config.
+ *
+ * Same rationale as {@link extractInlineFn}: `asyncFn` only appears on the
+ * `source: 'asyncFunction'` branch, so collectors that copy it through need a
+ * cast. Read-only access, no widening.
+ *
+ * @internal
+ */
+function extractInlineAsyncFn(config) {
+    return config.asyncFn;
+}
+
 /**
  * Recursively walks a field-definition tree, invoking `visitor` for each field.
  *
@@ -12360,9 +12707,11 @@ function createLogicEntry(fieldKey, config, context) {
         value: config.value,
         expression: config.expression,
         functionName: config.functionName,
+        fn: extractInlineFn(config),
         http: config.http,
         responseExpression: config.responseExpression,
         asyncFunctionName: config.asyncFunctionName,
+        asyncFn: extractInlineAsyncFn(config),
         trigger,
         debounceMs,
         isShorthand: false,
@@ -12911,9 +13260,16 @@ function createAsyncDerivationStream(entry, formValue$, context) {
             `Array async derivations will be supported in a future release.`);
         return EMPTY;
     }
-    if (!entry.asyncFunctionName) {
+    if (!entry.asyncFunctionName && !entry.asyncFn) {
+        context.logger.warn(`${LOG_PREFIX} Derivation for '${entry.fieldKey}' has neither "asyncFunctionName" nor "asyncFn". ` +
+            `One of the two is required for source: 'asyncFunction'.`);
         return EMPTY;
     }
+    if (entry.asyncFn && entry.asyncFunctionName) {
+        context.logger.warn(`${LOG_PREFIX} Both "asyncFn" and "asyncFunctionName" are set on derivation for '${entry.fieldKey}'. ` +
+            `Inline "asyncFn" takes precedence; "asyncFunctionName" is ignored.`);
+    }
+    const inlineAsyncFn = entry.asyncFn;
     const asyncFunctionName = entry.asyncFunctionName;
     const debounceMs = entry.debounceMs ?? DEFAULT_ASYNC_DEBOUNCE_MS;
     // startWith(null) → pairwise() causes all fields to appear "changed" on the
@@ -12959,8 +13315,8 @@ function createAsyncDerivationStream(entry, formValue$, context) {
             const customFunctions = context.customFunctions?.();
             const asyncDerivationFunctions = context.asyncDerivationFunctions?.();
             const externalData = context.externalData?.();
-            // Look up the async function
-            const asyncFn = asyncDerivationFunctions?.[asyncFunctionName];
+            // Inline `asyncFn` wins; otherwise look up the registered function.
+            const asyncFn = inlineAsyncFn ?? (asyncFunctionName ? asyncDerivationFunctions?.[asyncFunctionName] : undefined);
             if (!asyncFn) {
                 context.logger.warn(`${LOG_PREFIX} Async derivation function '${asyncFunctionName}' not found for field '${entry.fieldKey}'. ` +
                     `Register it in customFnConfig.asyncDerivations.`);
@@ -13388,7 +13744,7 @@ class DerivationOrchestrator {
         toObservable(this.derivationCollection, { injector: this.injector })
             .pipe(takeUntilDestroyed(this.destroyRef))
             .subscribe((collection) => {
-            const asyncEntries = collection?.entries.filter((entry) => entry.asyncFunctionName) ?? [];
+            const asyncEntries = collection?.entries.filter((entry) => entry.asyncFunctionName || entry.asyncFn) ?? [];
             if (asyncEntries.length === 0) {
                 this.teardownAsyncFunctionStreams();
                 this.lastAsyncEntryKeys = null;
@@ -13435,9 +13791,14 @@ class DerivationOrchestrator {
      * Used for smart teardown comparison.
      */
     computeAsyncEntryKeys(entries) {
+        // For inline `asyncFn` entries we tag the key with the field path (the real
+        // identity, since derivations are self-targeting) rather than the array
+        // index. Index-based tagging churned identities whenever topologicalSort
+        // reordered entries, causing unnecessary teardown + re-subscribe.
         return new Set(entries.map((entry) => {
             const config = {
                 asyncFunctionName: entry.asyncFunctionName,
+                asyncFnId: entry.asyncFn ? `inline:${entry.fieldKey}` : undefined,
                 dependsOn: entry.dependsOn,
                 debounceMs: entry.debounceMs,
                 stopOnUserOverride: entry.stopOnUserOverride,
@@ -13486,10 +13847,11 @@ function warnAboutWildcardDependencies$1(logger, entries, fieldCount) {
     // HTTP and async entries require explicit dependsOn (validated at collection time)
     const implicitWildcards = wildcardEntries.filter((entry) => !entry.http &&
         !entry.asyncFunctionName &&
-        entry.functionName &&
+        !entry.asyncFn &&
+        (entry.functionName || entry.fn) &&
         (!entry.originalConfig?.dependsOn || entry.originalConfig.dependsOn.length === 0));
     if (implicitWildcards.length > 0) {
-        const derivationDescs = implicitWildcards.map((e) => `${e.fieldKey} (${e.functionName})`);
+        const derivationDescs = implicitWildcards.map((e) => `${e.fieldKey} (${e.functionName ?? '<inline fn>'})`);
         logger.warn('Derivation: custom functions without explicit dependsOn detected. ' +
             `These run on EVERY form change, which may impact performance (form has ${fieldCount} fields). ` +
             'Consider specifying explicit dependsOn arrays for better performance.', derivationDescs);
@@ -13972,8 +14334,16 @@ function collectPropertyDerivations(fields, logger, tracker) {
     const entries = [];
     const context = { logger, tracker };
     traverseFieldsWithContext(fields, context, (field, ctx) => collectFromField(field, entries, ctx), {
-        onArrayChild: (_, field) => ({ arrayPath: field.key }),
-        // Group and layout containers do not affect property-derivation paths.
+        // Array boundary: each item is its own model root. Reset groupPath so
+        // ancestor groups OUTSIDE the array don't bleed into per-item keys.
+        onArrayChild: (_, field) => ({ arrayPath: field.key, groupPath: undefined }),
+        onGroupChild: (parent, field) => {
+            // Keyless groups (rare) act like layout containers — pass through.
+            if (!field.key)
+                return {};
+            return { groupPath: parent.groupPath ? `${parent.groupPath}.${field.key}` : field.key };
+        },
+        // Layout containers (page, row, container) leave context unchanged.
     });
     return { entries };
 }
@@ -14005,7 +14375,7 @@ function collectFromField(field, entries, context) {
  * @internal
  */
 function createPropertyDerivationEntryFromDerivation(fieldKey, config, context) {
-    const effectiveFieldKey = buildPropertyOverrideKey(context.arrayPath, context.arrayPath ? PLACEHOLDER_INDEX : undefined, fieldKey);
+    const effectiveFieldKey = buildPropertyOverrideKey(context.arrayPath, context.arrayPath ? PLACEHOLDER_INDEX : undefined, fieldKey, context.groupPath);
     const dependsOn = extractDependenciesFromConfig(config);
     const condition = config.condition ?? true;
     const trigger = config.trigger ?? 'onChange';
@@ -14018,6 +14388,7 @@ function createPropertyDerivationEntryFromDerivation(fieldKey, config, context)
         value: config.value,
         expression: config.expression,
         functionName: config.functionName,
+        fn: extractInlineFn(config),
         trigger,
         debounceMs,
         debugName: config.debugName,
@@ -14172,10 +14543,10 @@ const PROPERTY_DERIVATION_ORCHESTRATOR = new InjectionToken('PROPERTY_DERIVATION
 // ─────────────────────────────────────────────────────────────────────────────
 function warnAboutWildcardDependencies(logger, entries, fieldCount) {
     const implicitWildcards = entries.filter((entry) => entry.dependsOn.includes('*') &&
-        entry.functionName &&
+        (entry.functionName || entry.fn) &&
         (!entry.originalConfig?.dependsOn || entry.originalConfig.dependsOn.length === 0));
     if (implicitWildcards.length > 0) {
-        const derivationDescs = implicitWildcards.map((e) => `${e.fieldKey}.${e.targetProperty} (${e.functionName})`);
+        const derivationDescs = implicitWildcards.map((e) => `${e.fieldKey}.${e.targetProperty} (${e.functionName ?? '<inline fn>'})`);
         logger.warn('PropertyDerivation: custom functions without explicit dependsOn detected. ' +
             `These run on EVERY form change, which may impact performance (form has ${fieldCount} fields). ` +
             'Consider specifying explicit dependsOn arrays for better performance.', derivationDescs);
@@ -14205,6 +14576,7 @@ function coreProviders() {
             deps: [FormStateManager],
         },
         FieldContextRegistryService,
+        ArrayItemRegistryService,
         {
             provide: DEFAULT_PROPS,
             useFactory: (stateManager) => computed(() => stateManager.activeConfig()?.defaultProps),
@@ -14645,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 {
@@ -14665,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 {
@@ -15248,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 = {
@@ -15268,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-CMhqFGJZ.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-BhYFIDA1.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-DbWes42V.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-B9v_1shD.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-B4LnTnIA.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-text-field.component-Bo4zNJXY.mjs'),
         mapper: textFieldMapper,
         valueHandling: 'exclude',
         ...DISPLAY_FIELD_TYPES_BASE,
@@ -15304,15 +15698,16 @@ const BUILT_IN_FIELDS = [
     },
     {
         name: 'container',
-        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-CMhqFGJZ.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-htvP_o95.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-css-wrapper.component-BOdw40ZF.mjs'),
     },
     {
         wrapperName: 'row',
@@ -16386,5 +16781,5 @@ function extractErrorParams(error) {
  * Generated bundle index. Do not edit.
  */
 
-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, DEFAULT_VALIDATION_MESSAGES 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, 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-DWPPLOrV.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