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

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

@@ -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.
  *
@@ -324,8 +350,7 @@ function getDeclaredInputs(componentType) {
  * avoiding the reflection scan on each call is meaningful under heavy typing.
  */
 function setInputIfDeclared(ref, inputName, value) {
-    const declared = getDeclaredInputs(ref.componentType);
-    if (declared.has(inputName)) {
+    if (getDeclaredInputs(ref.componentType).has(inputName)) {
         ref.setInput(inputName, value);
     }
 }
@@ -545,6 +570,9 @@ function createWrapperChainController(opts) {
     const state = createStateSignal(opts);
     const mounted = { value: null };
     let refs = [];
+    // INVARIANT: toObservable schedules emissions as microtasks, so `renderInnermost`
+    // runs outside any parent CD pass. Don't swap for sync signal wiring without
+    // restoring df-field-outlet's detectChanges — NG0950 would re-surface.
     buildEmissionStream(state, deps)
         .pipe(takeUntilDestroyed(deps.destroyRef))
         .subscribe((emission) => {
@@ -841,6 +869,8 @@ class DfFieldOutlet {
                     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());
             },
         });
@@ -904,12 +934,12 @@ class DfFieldOutlet {
         }
     }
     pushRawInputs(ref, rawInputs) {
-        // Ref-identity dedupe per key — mappers must emit immutable snapshots.
+        // 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;
-            setInputIfDeclared(ref, key, value);
+            ref.setInput(key, value);
         }
         this.lastPushedInputs = rawInputs;
     }
@@ -2744,16 +2774,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;
             }
         }
@@ -2762,7 +2801,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':
@@ -4141,9 +4180,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-B_CxX0T-.mjs').then(m => m.default)], () => [import('./ng-forge-dynamic-forms-page-field.component-B_CxX0T-.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-BX4R9GGa.mjs').then(m => m.default)], () => [import('./ng-forge-dynamic-forms-page-field.component-BX4R9GGa.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-B_CxX0T-.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-BX4R9GGa.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) {
@@ -4624,7 +4663,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');
 }
 
 /**
@@ -5043,11 +5083,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();
@@ -5072,8 +5119,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.`);
@@ -5125,7 +5174,9 @@ function createAsyncConditionLogicFunction(condition) {
         });
         return resultResource.value();
     };
-    cacheService.asyncConditionFunctionCache.set(cacheKey, fn);
+    if (cacheKey !== undefined) {
+        cacheService.asyncConditionFunctionCache.set(cacheKey, fn);
+    }
     return fn;
 }
 
@@ -5760,12 +5811,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);
@@ -5777,6 +5828,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');
@@ -5837,10 +5895,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 = {
@@ -5862,10 +5934,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.
@@ -5876,10 +5954,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 = {
@@ -6187,6 +6279,109 @@ function createSchemaFunction(schema) {
     };
 }
 
+/**
+ * Combines the inherited "is any ancestor hidden" check into a single LogicFn.
+ * Returns `undefined` when no ancestor has dynamic hidden logic.
+ *
+ * @internal
+ */
+function combineAncestorHiddenLogics(logics) {
+    if (logics.length === 0)
+        return undefined;
+    if (logics.length === 1)
+        return logics[0];
+    return (ctx) => logics.some((fn) => fn(ctx));
+}
+/**
+ * Returns the `FieldTreeMappingContext` to use **for the field itself** — i.e.
+ * for gating its own validators. Only applies overrides that affect the field
+ * (currently `validateWhenHidden`). The field's own hidden state is NOT folded
+ * into `ancestorAlwaysHidden`/`ancestorHiddenLogics` here — Angular Signal
+ * Forms already exposes that through `ctx.state.hidden()`, which the gate
+ * checks separately.
+ *
+ * Returns the parent context unchanged when the field defines no overrides —
+ * saves an allocation on every leaf in the common case.
+ *
+ * @internal
+ */
+function resolveFieldOwnContext(fieldDef, parentContext) {
+    if (fieldDef.validateWhenHidden === undefined)
+        return parentContext;
+    if (fieldDef.validateWhenHidden === parentContext.validateWhenHidden)
+        return parentContext;
+    return {
+        ...parentContext,
+        validateWhenHidden: fieldDef.validateWhenHidden,
+    };
+}
+/**
+ * Returns the `FieldTreeMappingContext` to use **for the field's descendants**.
+ * Builds on top of `ownContext` by folding in the field's own hidden state so
+ * children can correctly skip validation when this field hides them. Used for
+ * groups, arrays, and layout containers that recurse into children.
+ *
+ * Behavior:
+ * - `hidden: true` (static) → sets `ancestorAlwaysHidden`.
+ * - `logic: [{type: 'hidden', condition: true}]` → sets `ancestorAlwaysHidden`.
+ * - `logic: [{type: 'hidden', condition: false}]` → no effect.
+ * - `logic: [{type: 'hidden', condition: <expr>}]` → appends a reactive
+ *   `LogicFn` to `ancestorHiddenLogics`.
+ *
+ * @internal
+ */
+function resolveDescendantContext(fieldDef, ownContext) {
+    let ancestorAlwaysHidden = ownContext.ancestorAlwaysHidden;
+    let ancestorHiddenLogics = ownContext.ancestorHiddenLogics;
+    let mutated = false;
+    if (fieldDef.hidden === true && !ancestorAlwaysHidden) {
+        ancestorAlwaysHidden = true;
+        mutated = true;
+    }
+    if (fieldDef.logic) {
+        for (const logic of fieldDef.logic) {
+            if (!isStateLogicConfig(logic) || logic.type !== 'hidden')
+                continue;
+            const condition = logic.condition;
+            if (condition === true) {
+                if (!ancestorAlwaysHidden) {
+                    ancestorAlwaysHidden = true;
+                    mutated = true;
+                }
+                continue;
+            }
+            if (condition === false)
+                continue;
+            // FormStateCondition strings ('formInvalid', etc.) are intended for buttons —
+            // they don't make sense as a "field hidden" trigger, so we skip them here.
+            if (typeof condition === 'string')
+                continue;
+            // Dynamic — we need a reactive logic function. createLogicFunction
+            // requires an injection context, which the schema build provides.
+            const fn = createLogicFunction(condition);
+            ancestorHiddenLogics = ancestorHiddenLogics.length === 0 ? [fn] : [...ancestorHiddenLogics, fn];
+            mutated = true;
+        }
+    }
+    if (!mutated)
+        return ownContext;
+    return {
+        validateWhenHidden: ownContext.validateWhenHidden,
+        ancestorAlwaysHidden,
+        ancestorHiddenLogics,
+    };
+}
+
+/**
+ * Default {@link FieldTreeMappingContext} used when no inherited context is provided.
+ * Mirrors the global token defaults so callers that bypass `createSchemaFromFields`
+ * (e.g. nested group forms) still get sensible behavior.
+ */
+const DEFAULT_FIELD_TREE_MAPPING_CONTEXT = {
+    validateWhenHidden: false,
+    ancestorAlwaysHidden: false,
+    ancestorHiddenLogics: [],
+};
 /**
  * Applies string-specific validators to a schema path.
  * This function is properly typed - no casts needed internally.
@@ -6267,25 +6462,42 @@ function getNumberValidationConfig(fieldDef) {
  * which uses RootFormRegistryService.
  *
  * Cross-field validators are skipped at field level and applied at form level via validateTree.
- */
-function mapFieldToForm(fieldDef, fieldPath) {
-    // Layout containers (page, row, container) - flatten children to current level
+ *
+ * @param fieldDef Field definition to map
+ * @param fieldPath Schema path for this field
+ * @param inheritedContext Cascading mapping context from the parent. Field-level
+ *   overrides on `fieldDef` are merged on top and passed down to descendants. Defaults
+ *   to {@link DEFAULT_FIELD_TREE_MAPPING_CONTEXT} when omitted.
+ */
+function mapFieldToForm(fieldDef, fieldPath, inheritedContext = DEFAULT_FIELD_TREE_MAPPING_CONTEXT) {
+    const ownContext = resolveFieldOwnContext(fieldDef, inheritedContext);
+    // Layout containers (page, row, container) - flatten children to current level.
+    // Layout containers have no schema path of their own, so any hidden state on them
+    // must be propagated to descendants through the cascade.
     if (isPageField(fieldDef) || isRowField(fieldDef) || isContainerTypedField(fieldDef)) {
-        mapContainerChildren(fieldDef.fields, fieldPath);
+        const descendantContext = resolveDescendantContext(fieldDef, ownContext);
+        mapContainerChildren(fieldDef.fields, fieldPath, descendantContext);
         return;
     }
-    // Group fields - map children under the group's path
+    // Group fields - map children under the group's path. Groups have a schema path,
+    // so Angular Signal Forms can propagate `hidden(path, ...)` calls to descendants —
+    // but groups don't currently apply their own hidden state, so we still propagate
+    // through the cascade as a belt-and-suspenders fallback.
     if (isGroupField(fieldDef)) {
-        mapContainerChildren(fieldDef.fields, fieldPath);
+        const descendantContext = resolveDescendantContext(fieldDef, ownContext);
+        mapContainerChildren(fieldDef.fields, fieldPath, descendantContext);
         return;
     }
-    // Array fields - use applyEach for item schema
+    // Array fields - use applyEach for item schema.
     if (isArrayField(fieldDef)) {
-        mapArrayFieldToForm(fieldDef, fieldPath);
+        const descendantContext = resolveDescendantContext(fieldDef, ownContext);
+        mapArrayFieldToForm(fieldDef, fieldPath, descendantContext);
         return;
     }
-    // Leaf field - apply validation, logic, and configuration
-    mapLeafField(fieldDef, fieldPath);
+    // Leaf field - apply validation, logic, and configuration. Use the field's OWN
+    // context (no descendant propagation) because the leaf's own hidden state is
+    // already exposed via `ctx.state.hidden()`.
+    mapLeafField(fieldDef, fieldPath, ownContext);
 }
 /**
  * Maps children of a container field (page, row, group) to the form schema.
@@ -6296,50 +6508,100 @@ function mapFieldToForm(fieldDef, fieldPath) {
  * leaf descendants. Group/array fields consume their key and look up their own
  * child path on `parentPath`.
  */
-function mapContainerChildren(fields, parentPath) {
+function mapContainerChildren(fields, parentPath, inheritedContext) {
     if (!fields)
         return;
     const pathRecord = parentPath;
     for (const field of fields) {
         if (isPageField(field) || isRowField(field) || isContainerTypedField(field)) {
-            mapContainerChildren(field.fields, parentPath);
+            // Layout containers can still carry their own cascading overrides that flow
+            // down to their flattened descendants.
+            const layoutOwn = resolveFieldOwnContext(field, inheritedContext);
+            const layoutDescendant = resolveDescendantContext(field, layoutOwn);
+            mapContainerChildren(field.fields, parentPath, layoutDescendant);
             continue;
         }
         if (!field.key)
             continue;
         const childPath = pathRecord[field.key];
         if (childPath) {
-            mapFieldToForm(field, childPath);
+            mapFieldToForm(field, childPath, inheritedContext);
         }
     }
 }
+/**
+ * Returns true for state logic that contributes validation (currently only `required`).
+ * The other state logic types (`hidden`, `disabled`, `readonly`) must always apply,
+ * even on hidden fields, so they're not gated by `validateWhenHidden`.
+ */
+function isValidationStateLogic(config) {
+    return isStateLogicConfig(config) && config.type === 'required';
+}
 /**
  * Maps a leaf field (value-bearing field) to the form schema.
+ *
+ * @param context Resolved cascading context for this field. When
+ *   `context.validateWhenHidden` is `false`, the field's validation block is wrapped
+ *   in `applyWhen` keyed off `!ctx.state.hidden()`.
  */
-function mapLeafField(fieldDef, fieldPath) {
+function mapLeafField(fieldDef, fieldPath, context) {
     const validationField = fieldDef;
     const path = fieldPath;
-    // Apply simple validation rules from field properties
-    applySimpleValidationRules(validationField, path);
-    if (validationField.validators) {
-        for (const config of validationField.validators) {
-            applyValidator(config, fieldPath);
-        }
-    }
-    // Apply logic rules
+    // Always-applied: state logic (hidden/disabled/readonly), schemas, and value derivations.
+    // These must run regardless of hidden state — particularly the `hidden` logic itself,
+    // which establishes the very signal `applyWhen` reads below.
+    applyFieldState(fieldDef, path);
     if (validationField.logic) {
         for (const config of validationField.logic) {
-            applyLogic(config, fieldPath);
+            if (!isValidationStateLogic(config)) {
+                applyLogic(config, fieldPath);
+            }
         }
     }
-    // Apply schemas
     if (validationField.schemas) {
         for (const config of validationField.schemas) {
             applySchema(config, fieldPath);
         }
     }
-    // Apply field state configuration
-    applyFieldState(fieldDef, path);
+    // Validation block — gated by `validateWhenHidden` when hidden.
+    const applyValidation = (validationPath) => {
+        applySimpleValidationRules(validationField, validationPath);
+        if (validationField.validators) {
+            for (const config of validationField.validators) {
+                applyValidator(config, validationPath);
+            }
+        }
+        if (validationField.logic) {
+            for (const config of validationField.logic) {
+                if (isValidationStateLogic(config)) {
+                    applyLogic(config, validationPath);
+                }
+            }
+        }
+    };
+    if (context.validateWhenHidden) {
+        applyValidation(path);
+        return;
+    }
+    // An ancestor is unconditionally hidden — there is no reactive case for the
+    // validators to ever fire, so we simply do not apply them.
+    if (context.ancestorAlwaysHidden) {
+        return;
+    }
+    // applyWhen conditionally applies a sub-schema. The gate combines:
+    // - the field's own `state.hidden()` (set by Angular Signal Forms whenever
+    //   `hidden(path, ...)` was called for this field or any ancestor with a
+    //   path); and
+    // - any ancestor dynamic hidden logic that does NOT live on a schema path
+    //   (layout containers — see field-tree-mapping-context for details).
+    const ancestorHiddenLogic = combineAncestorHiddenLogics(context.ancestorHiddenLogics);
+    applyWhen(path, (ctx) => {
+        if (ctx.state.hidden())
+            return false;
+        if (ancestorHiddenLogic && ancestorHiddenLogic(ctx))
+            return false;
+        return true;
+    }, schema((subPath) => applyValidation(subPath)));
 }
 /**
  * Applies simple validation rules from field properties.
@@ -6388,7 +6650,7 @@ function applyFieldState(fieldDef, path) {
  * - Heterogeneous arrays - mixed primitives and objects
  * - Container templates (row, group, page) that wrap children
  */
-function mapArrayFieldToForm(arrayField, fieldPath) {
+function mapArrayFieldToForm(arrayField, fieldPath, context) {
     if (!isArrayField(arrayField)) {
         return;
     }
@@ -6459,20 +6721,24 @@ function mapArrayFieldToForm(arrayField, fieldPath) {
         for (const templateField of allObjectFields) {
             if (isRowField(templateField) || isPageField(templateField) || isContainerTypedField(templateField)) {
                 // Row/page/container templates flatten their children
-                mapContainerChildren(templateField.fields, itemPath);
+                const layoutOwn = resolveFieldOwnContext(templateField, context);
+                const layoutDescendant = resolveDescendantContext(templateField, layoutOwn);
+                mapContainerChildren(templateField.fields, itemPath, layoutDescendant);
             }
             else if (isGroupField(templateField)) {
                 // Group template - access group's path first
                 const groupKey = templateField.key;
+                const groupOwn = resolveFieldOwnContext(templateField, context);
+                const groupDescendant = resolveDescendantContext(templateField, groupOwn);
                 if (groupKey) {
                     const groupPath = pathRecord[groupKey];
                     if (groupPath) {
-                        mapContainerChildren(templateField.fields, groupPath);
+                        mapContainerChildren(templateField.fields, groupPath, groupDescendant);
                     }
                 }
                 else {
                     // No group key - apply children directly (edge case)
-                    mapContainerChildren(templateField.fields, itemPath);
+                    mapContainerChildren(templateField.fields, itemPath, groupDescendant);
                 }
             }
             else {
@@ -6481,7 +6747,7 @@ function mapArrayFieldToForm(arrayField, fieldPath) {
                 if (fieldKey) {
                     const fieldPathForKey = pathRecord[fieldKey];
                     if (fieldPathForKey) {
-                        mapFieldToForm(templateField, fieldPathForKey);
+                        mapFieldToForm(templateField, fieldPathForKey, context);
                     }
                 }
             }
@@ -6899,6 +7165,103 @@ function mapValues(obj, fn) {
         return acc;
     }, {});
 }
+/**
+ * Deep-merges `value` into `defaults`, producing a new object that contains every
+ * key from `defaults` plus any overrides from `value`. Plain-object values at
+ * matching keys are merged recursively; primitives, dates, and class instances
+ * in `value` replace the corresponding default wholesale.
+ *
+ * Arrays whose lengths match between `defaults` and `value` are merged
+ * positionally: when both `defaults[i]` and `value[i]` are plain objects, they
+ * are deep-merged so partial array-item values don't drop sibling sub-field
+ * keys. When the lengths differ — the runtime add/insert/remove case — the
+ * value array is returned by reference so Signal Forms doesn't see a fresh
+ * array of fresh inner objects on every form-value write (which would rebuild
+ * item bindings and desync the rendered rows from their FieldTrees).
+ *
+ * Used by `FormStateManager.entity` so a partial input value (e.g. a nested
+ * group object missing one of its declared sub-fields, or an array item missing
+ * one of its declared sub-fields) does not orphan the absent sub-field in
+ * Angular Signal Forms' validation graph.
+ *
+ * @example
+ * ```typescript
+ * deepMergeDefaults(
+ *   { a: { line1: '', line2: '', city: '' }, b: 0 },
+ *   { a: { line1: 'X', city: 'Y' }, b: 1 },
+ * );
+ * // { a: { line1: 'X', line2: '', city: 'Y' }, b: 1 }
+ *
+ * deepMergeDefaults(
+ *   { items: [{ checkboxA: false, checkboxB: false }] },
+ *   { items: [{ checkboxA: true }] },
+ * );
+ * // { items: [{ checkboxA: true, checkboxB: false }] }
+ * ```
+ */
+function deepMergeDefaults(defaults, value) {
+    if (value == null)
+        return { ...defaults };
+    const result = { ...defaults };
+    for (const key of Object.keys(value)) {
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+            continue;
+        const incoming = value[key];
+        const existing = result[key];
+        if (isPlainObject(existing) && isPlainObject(incoming)) {
+            result[key] = deepMergeDefaults(existing, incoming);
+        }
+        else if (Array.isArray(existing) && Array.isArray(incoming)) {
+            result[key] = mergeArrayDefaults(existing, incoming);
+        }
+        else {
+            result[key] = incoming;
+        }
+    }
+    return result;
+}
+/**
+ * @internal
+ * Merges a value array into a defaults array element-wise when their lengths
+ * match. When lengths differ — the runtime case: prepend, insert, append,
+ * remove — we return the value array reference as-is so we don't produce
+ * fresh inner object references for items that already have every declared
+ * sub-field key. Replacing references during the linkedSignal source
+ * recompute that runs after Signal Forms wrote the array would otherwise
+ * desync item FieldTrees from the rendered DOM rows.
+ *
+ * When lengths match (the declared/initial-value path the array fix targets)
+ * each `defaults[i]`/`value[i]` pair is deep-merged when both are plain
+ * objects so partial array-item values don't drop sibling sub-field keys.
+ */
+function mergeArrayDefaults(defaults, value) {
+    if (defaults.length !== value.length)
+        return value;
+    // Short-circuit when no element pair would be deep-merged. Returning a fresh
+    // .map() result for primitive arrays (e.g. tags: ['a', 'b']) hands Signal
+    // Forms a new reference on every call and rebuilds item FieldTrees needlessly.
+    if (!value.some((item, i) => isPlainObject(defaults[i]) && isPlainObject(item)))
+        return value;
+    return value.map((item, i) => {
+        const defaultItem = defaults[i];
+        if (isPlainObject(defaultItem) && isPlainObject(item)) {
+            return deepMergeDefaults(defaultItem, item);
+        }
+        return item;
+    });
+}
+/**
+ * @internal
+ * Returns true for objects that should be deep-merged (plain objects produced
+ * by literals or `Object.create(null)`); false for arrays, Dates, RegExps,
+ * Maps, Sets, class instances, and primitives.
+ */
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}
 /**
  * Options for memoize function
  */
@@ -7088,6 +7451,27 @@ function createFormLevelSchema(formLevelSchema) {
     });
 }
 
+/**
+ * Injection token for global validation execution defaults.
+ *
+ * Controls whether validators run on hidden fields. By default, validation is
+ * skipped when a field is hidden (`validateWhenHidden: false`).
+ *
+ * Configured via `withValidationExecutionDefaults()`. Per-form overrides via
+ * `FormOptions.validateWhenHidden`. Per-field overrides via `FieldDef.validateWhenHidden`,
+ * which inherits down the field tree.
+ *
+ * **Resolution order:** Field (with parent inheritance) > Form > Global.
+ *
+ * @internal
+ */
+const VALIDATION_EXECUTION_DEFAULTS = new InjectionToken('VALIDATION_EXECUTION_DEFAULTS', {
+    providedIn: 'root',
+    factory: () => ({
+        validateWhenHidden: false,
+    }),
+});
+
 const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 /**
  * Gets a FieldTree by key, supporting nested paths with dot notation.
@@ -7132,11 +7516,17 @@ function createSchemaFromFields(fields, registry, optionsOrValidators) {
     // These will be available because createSchemaFromFields is called within runInInjectionContext
     const functionRegistry = inject(FunctionRegistryService);
     const logger = inject(DynamicFormLogger);
+    const validationExecutionDefaults = inject(VALIDATION_EXECUTION_DEFAULTS);
     // Normalize options - support both old array signature and new options object
     const options = Array.isArray(optionsOrValidators)
         ? { crossFieldValidators: optionsOrValidators }
         : (optionsOrValidators ?? {});
     const { crossFieldValidators, formLevelSchema } = options;
+    const rootContext = {
+        validateWhenHidden: options.validateWhenHidden ?? validationExecutionDefaults.validateWhenHidden,
+        ancestorAlwaysHidden: false,
+        ancestorHiddenLogics: [],
+    };
     return schema((path) => {
         for (const fieldDef of fields) {
             const valueHandling = getFieldValueHandling(fieldDef.type, registry);
@@ -7146,12 +7536,17 @@ function createSchemaFromFields(fields, registry, optionsOrValidators) {
                 continue;
             }
             if (valueHandling === 'flatten' && hasChildFields(fieldDef)) {
+                // A flatten container can still set its own cascading overrides that flow
+                // down to its children — including its own hidden state which has no
+                // schema path of its own.
+                const flattenedOwn = resolveFieldOwnContext(fieldDef, rootContext);
+                const flattenedContext = resolveDescendantContext(fieldDef, flattenedOwn);
                 for (const childField of normalizeFieldsArray(fieldDef.fields)) {
                     if (!childField.key)
                         continue;
                     const childPath = path[childField.key];
                     if (childPath) {
-                        mapFieldToForm(childField, childPath);
+                        mapFieldToForm(childField, childPath, flattenedContext);
                     }
                 }
                 continue;
@@ -7164,7 +7559,7 @@ function createSchemaFromFields(fields, registry, optionsOrValidators) {
             // Use the new modular form mapping function
             // This will progressively apply validators, logic, and schemas
             // Cross-field logic is handled automatically via RootFormRegistryService
-            mapFieldToForm(fieldDef, fieldPath);
+            mapFieldToForm(fieldDef, fieldPath, rootContext);
         }
         // Apply cross-field validators using validateTree
         if (crossFieldValidators && crossFieldValidators.length > 0) {
@@ -7772,49 +8167,54 @@ function flattenFields(fields, registry, options = {}) {
  * These functions are used by both `FormStateManager` and `GroupFieldComponent`
  * to compute flattened fields, field lookups, and default values from field definitions.
  *
+ * Caches are keyed on the input array's reference identity (via WeakMap) rather than
+ * a derived content key. Different array instances — even ones with the same field
+ * keys/types — must produce fresh results so per-field content changes (e.g. updated
+ * select options) propagate through the form pipeline.
+ *
  * @returns Object containing memoized processing functions
  */
 function createContainerFieldProcessors() {
-    const createFieldsResolver = (preserveRows = false) => (fields, registry) => {
-        let key = '';
-        for (const f of fields) {
-            key += (f.key ?? '') + ':' + (f.type ?? '') + '|';
+    const flattenCache = new WeakMap();
+    const memoizedFlattenFields = (fields, registry) => {
+        const cached = flattenCache.get(fields);
+        if (cached !== undefined) {
+            return cached;
         }
-        return key + registry.size + '|' + preserveRows;
+        const result = flattenFields([...fields], registry);
+        flattenCache.set(fields, result);
+        return result;
+    };
+    const flattenForRenderingCache = new WeakMap();
+    const memoizedFlattenFieldsForRendering = (fields, registry) => {
+        const cached = flattenForRenderingCache.get(fields);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = flattenFields([...fields], registry, { preserveRows: true });
+        flattenForRenderingCache.set(fields, result);
+        return result;
+    };
+    const keyByCache = new WeakMap();
+    const memoizedKeyBy = (fields) => {
+        const cached = keyByCache.get(fields);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = keyBy(fields, 'key');
+        keyByCache.set(fields, result);
+        return result;
+    };
+    const defaultValuesCache = new WeakMap();
+    const memoizedDefaultValues = (fieldsById, registry) => {
+        const cached = defaultValuesCache.get(fieldsById);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = mapValues(fieldsById, (field) => getFieldDefaultValue(field, registry));
+        defaultValuesCache.set(fieldsById, result);
+        return result;
     };
-    const memoizedFlattenFields = memoize((fields, registry) => flattenFields([...fields], registry), {
-        // registry.size is a valid cache key proxy because the field registry is populated
-        // once at bootstrap and never mutated at runtime. If the registry were mutable,
-        // we would need a content-based hash instead.
-        resolver: createFieldsResolver(),
-        maxSize: 10,
-    });
-    const memoizedFlattenFieldsForRendering = memoize((fields, registry) => flattenFields([...fields], registry, { preserveRows: true }), {
-        // registry.size is a valid cache key proxy because the field registry is populated
-        // once at bootstrap and never mutated at runtime. If the registry were mutable,
-        // we would need a content-based hash instead.
-        resolver: createFieldsResolver(true),
-        maxSize: 10,
-    });
-    const memoizedKeyBy = memoize((fields) => keyBy(fields, 'key'), {
-        resolver: (fields) => {
-            let key = '';
-            for (const f of fields) {
-                key += f.key + '|';
-            }
-            return key;
-        },
-        maxSize: 10,
-    });
-    const memoizedDefaultValues = memoize((fieldsById, registry) => mapValues(fieldsById, (field) => getFieldDefaultValue(field, registry)), {
-        // registry.size is a valid cache key proxy because the field registry is populated
-        // once at bootstrap and never mutated at runtime.
-        resolver: (fieldsById, registry) => {
-            const keys = Object.keys(fieldsById).sort();
-            return keys.join('|') + '|' + registry.size;
-        },
-        maxSize: 10,
-    });
     return { memoizedFlattenFields, memoizedFlattenFieldsForRendering, memoizedKeyBy, memoizedDefaultValues };
 }
 /**
@@ -8155,22 +8555,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;
 }
 
 /**
@@ -8251,6 +8660,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.
@@ -8287,6 +8715,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);
@@ -8297,6 +8729,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
@@ -8305,7 +8738,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
@@ -8315,18 +8748,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);
         }
@@ -8423,6 +8872,11 @@ function resolveFieldSync(fieldDef, context) {
  * Reconciles previous and current resolved fields to preserve injector instances
  * for fields that haven't changed type, preventing unnecessary component recreation.
  *
+ * When a field's key, component, and injector all match the previous render but the
+ * underlying `fieldDef` has changed (e.g. updated options/props), the existing
+ * component/injector are preserved while the new `inputs` and `renderReady` signals
+ * are adopted so prop updates flow through to the rendered component.
+ *
  * @param prev - Previous resolved fields array
  * @param curr - Current resolved fields array
  * @returns Reconciled fields with preserved injectors where applicable
@@ -8432,8 +8886,20 @@ function reconcileFields(prev, curr) {
     return curr.map((field) => {
         const existing = prevMap.get(field.key);
         if (existing && existing.component === field.component && existing.injector === field.injector) {
-            // Truly unchanged - preserve object identity for signal stability
-            return existing;
+            if (existing.fieldDef === field.fieldDef) {
+                // Truly unchanged - preserve object identity for signal stability
+                return existing;
+            }
+            // 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.
+            return {
+                ...existing,
+                fieldDef: field.fieldDef,
+                inputs: field.inputs,
+                renderReady: field.renderReady,
+            };
         }
         // New field, type changed, or context changed (new injector) - use new field
         return field;
@@ -8750,15 +9216,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);
@@ -8778,13 +9261,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);
                 }
             }
         }
@@ -8820,7 +9306,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.`);
     }
 }
 /**
@@ -8858,11 +9375,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
@@ -8916,18 +9435,22 @@ function resolveExclusionConfig(global, form, field) {
     };
 }
 /**
- * Determines whether a field's value should be excluded based on its reactive state
+ * Determines whether a field's value should be excluded based on its reactive state,
+ * the field def's static state (for fields whose `state.hidden()` isn't wired — e.g. groups),
  * and the resolved exclusion config.
  */
-function shouldExcludeField(fieldState, config) {
+function shouldExcludeField(field, fieldState, config) {
     const state = fieldState();
-    if (config.excludeValueIfHidden && state.hidden()) {
+    const isHidden = state.hidden() || field.hidden === true;
+    if (config.excludeValueIfHidden && isHidden) {
         return true;
     }
-    if (config.excludeValueIfDisabled && state.disabled()) {
+    const isDisabled = state.disabled() || field.disabled === true;
+    if (config.excludeValueIfDisabled && isDisabled) {
         return true;
     }
-    if (config.excludeValueIfReadonly && state.readonly()) {
+    const isReadonly = state.readonly() || field.readonly === true;
+    if (config.excludeValueIfReadonly && isReadonly) {
         return true;
     }
     return false;
@@ -8959,14 +9482,6 @@ function filterFormValue(rawValue, schemaFields, formTree, registry, globalDefau
         // If the key doesn't exist in the raw value, skip
         if (!(key in rawValue))
             continue;
-        // Try to access the field state from the form tree
-        const fieldState = formTree[key];
-        // If no field state is available (e.g., componentless hidden fields),
-        // include the value as-is since we can't determine reactive state
-        if (!fieldState || typeof fieldState !== 'function') {
-            result[key] = rawValue[key];
-            continue;
-        }
         // Resolve per-field exclusion config
         const fieldExclusion = {
             excludeValueIfHidden: field.excludeValueIfHidden,
@@ -8974,8 +9489,19 @@ function filterFormValue(rawValue, schemaFields, formTree, registry, globalDefau
             excludeValueIfReadonly: field.excludeValueIfReadonly,
         };
         const resolvedConfig = resolveExclusionConfig(globalDefaults, formOptions, fieldExclusion);
+        // Componentless field (no FieldTree) — decide from the static field def alone, then include if not excluded.
+        const fieldState = formTree[key];
+        if (!fieldState || typeof fieldState !== 'function') {
+            const staticallyExcluded = (resolvedConfig.excludeValueIfHidden && field.hidden === true) ||
+                (resolvedConfig.excludeValueIfDisabled && field.disabled === true) ||
+                (resolvedConfig.excludeValueIfReadonly && field.readonly === true);
+            if (!staticallyExcluded) {
+                result[key] = rawValue[key];
+            }
+            continue;
+        }
         // Check if this field should be excluded based on its state
-        if (shouldExcludeField(fieldState, resolvedConfig)) {
+        if (shouldExcludeField(field, fieldState, resolvedConfig)) {
             continue;
         }
         // Handle group fields: recurse into nested structure
@@ -9470,6 +9996,77 @@ const FORM_STATE_DEPS = new InjectionToken('FORM_STATE_DEPS');
 function asFieldTreeRecord(tree) {
     return tree;
 }
+/** All-false baseline for the outward two-way binding filter — see `boundFormValue`. */
+const BOUND_VALUE_EXCLUSION_BASELINE = {
+    excludeValueIfHidden: false,
+    excludeValueIfDisabled: false,
+    excludeValueIfReadonly: false,
+};
+/** True when any of the three exclusion axes is asserted (i.e. the field could be filtered out of the bound model). */
+function isFieldExcluded(axes) {
+    return !!axes && (axes.hidden || axes.disabled || axes.readonly);
+}
+/**
+ * Recursively populates `out` with `dottedPath → exclusion axes` for every keyed field reachable
+ * from `fields`, walking into groups so nested-leaf transitions can be detected. Arrays are
+ * treated as leaves (whole-array filtering only — see value-filter v1 limitation).
+ */
+function collectFieldStateSnapshot(fields, treeRecord, pathParts, out) {
+    for (const field of fields) {
+        const key = field.key;
+        if (!key)
+            continue;
+        const subtree = treeRecord[key];
+        if (!subtree || typeof subtree !== 'function')
+            continue;
+        const state = subtree();
+        const path = [...pathParts, key];
+        out[path.join('.')] = { hidden: state.hidden(), disabled: state.disabled(), readonly: state.readonly() };
+        if (isGroupField(field) && field.fields) {
+            collectFieldStateSnapshot(field.fields, asFieldTreeRecord(subtree), path, out);
+        }
+    }
+}
+/**
+ * Reads a value from a nested object by dotted-path segments. Returns undefined
+ * if any intermediate segment is missing or non-object.
+ */
+function getValueAtPath(source, segments) {
+    let current = source;
+    for (const segment of segments) {
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Whether a value is worth capturing into the saved-hidden-value store. `NaN` (the number-input
+ * default) is excluded — restoring it would re-leak the default into the bound model when the
+ * field becomes visible again, defeating the bug fix.
+ */
+function isRestoreRelevant(value) {
+    return !(typeof value === 'number' && Number.isNaN(value));
+}
+/**
+ * Returns a new object with `value` set at the path described by `segments`.
+ * Intermediate objects are cloned shallowly to preserve immutability of `target`.
+ */
+function setValueAtPath(target, segments, value) {
+    if (segments.length === 0)
+        return target;
+    const [head, ...rest] = segments;
+    const next = { ...target };
+    if (rest.length === 0) {
+        next[head] = value;
+    }
+    else {
+        const child = target[head];
+        const childObj = child !== null && typeof child === 'object' ? child : {};
+        next[head] = setValueAtPath(childObj, rest, value);
+    }
+    return next;
+}
 /**
  * Central service that manages all form state and coordinates the form lifecycle.
  * Single source of truth for lifecycle state, field resolution, form signals, and events.
@@ -9641,6 +10238,29 @@ class FormStateManager {
             return undefined;
         return new Set(schemaFields.map((f) => f.key).filter((key) => key !== undefined));
     }, ...(ngDevMode ? [{ debugName: "validKeys" }] : /* istanbul ignore next */ []));
+    /**
+     * Per-field exclusion-axis state (hidden/disabled/readonly) keyed by dotted path. Drives the
+     * save-on-exclude effect's transition detection. Walks recursively into groups so nested-leaf
+     * transitions are captured. Arrays are treated as leaves (whole-array preservation only).
+     */
+    fieldStateSnapshot = computed(() => {
+        const setup = this.formSetup();
+        if (!setup.schemaFields || setup.schemaFields.length === 0)
+            return {};
+        const snapshot = {};
+        collectFieldStateSnapshot(setup.schemaFields, asFieldTreeRecord(this.form()), [], snapshot);
+        return snapshot;
+    }, ...(ngDevMode ? [{ debugName: "fieldStateSnapshot" }] : /* istanbul ignore next */ []));
+    /**
+     * Captured values for fields actively excluded from the bound model — either via
+     * `excludeValueIfHidden`, `excludeValueIfDisabled`, or `excludeValueIfReadonly`. Restored when
+     * the field becomes re-included (visible/enabled/editable). The save effect only writes here
+     * when the field is being filtered out by `boundFormValue` — fields without explicit opt-in
+     * never enter the store.
+     */
+    excludedValueStore = signal({}, ...(ngDevMode ? [{ debugName: "excludedValueStore" }] : /* istanbul ignore next */ []));
+    /** Tracks per-path exclusion state across save-effect runs to detect newly-excluded fields. */
+    prevFieldStateSnapshot = signal({}, ...(ngDevMode ? [{ debugName: "prevFieldStateSnapshot" }] : /* istanbul ignore next */ []));
     // ─────────────────────────────────────────────────────────────────────────────
     // Computed Signals - Entity & Form
     // ─────────────────────────────────────────────────────────────────────────────
@@ -9664,7 +10284,13 @@ class FormStateManager {
         const inputValue = this.deps.value();
         const defaults = this.defaultValues();
         const keys = this.validKeys();
-        const combined = { ...defaults, ...inputValue };
+        const saved = this.excludedValueStore();
+        // Deep-merge so a partial nested object in `inputValue` (e.g. a group
+        // value missing one of its declared sub-field keys) does not orphan
+        // the absent sub-field in the Signal Forms validation graph.
+        // Layer order: defaults < saved (excluded-field restorations) < inputValue.
+        const withSaved = deepMergeDefaults(defaults, saved);
+        const combined = deepMergeDefaults(withSaved, inputValue);
         if (keys) {
             const filtered = {};
             for (const key of Object.keys(combined)) {
@@ -9694,6 +10320,7 @@ class FormStateManager {
             return createSchemaFromFields(setup.schemaFields, setup.registry, {
                 crossFieldValidators: crossFieldCollection.validators,
                 formLevelSchema: config.schema,
+                validateWhenHidden: this.effectiveFormOptions().validateWhenHidden,
             });
         }
         if (config.schema) {
@@ -9773,6 +10400,35 @@ class FormStateManager {
         const fieldTreeRecord = asFieldTreeRecord(formTree);
         return filterFormValue(rawValue, setup.schemaFields, fieldTreeRecord, setup.registry, this.valueExclusionDefaults, formOptions);
     }, ...(ngDevMode ? [{ debugName: "filteredFormValue" }] : /* istanbul ignore next */ []));
+    /**
+     * Form value used for the outward two-way binding sync.
+     *
+     * Only honors *explicit* form-level and field-level `excludeValueIf*` settings — global
+     * defaults (`VALUE_EXCLUSION_DEFAULTS`) are intentionally ignored here. Rationale:
+     * - Original V1 behavior: the bound model carries all values regardless of visibility.
+     * - Bug fix: when a user explicitly sets `excludeValueIfHidden: true` on a field/form,
+     *   they expect that value to disappear from the bound model when hidden (e.g. NaN for
+     *   number inputs, see issue #394).
+     * - Without explicit opt-in, the bound model keeps the V1 contract.
+     * `filteredFormValue` (above) still applies the full Field > Form > Global hierarchy
+     * for the submission output.
+     */
+    boundFormValue = computed(() => {
+        const rawValue = this.formValue();
+        const setup = this.formSetup();
+        const options = this.effectiveFormOptions();
+        if (!setup.schemaFields || setup.schemaFields.length === 0) {
+            return rawValue;
+        }
+        const formTree = this.form();
+        const formOptions = {
+            excludeValueIfHidden: options.excludeValueIfHidden,
+            excludeValueIfDisabled: options.excludeValueIfDisabled,
+            excludeValueIfReadonly: options.excludeValueIfReadonly,
+        };
+        const fieldTreeRecord = asFieldTreeRecord(formTree);
+        return filterFormValue(rawValue, setup.schemaFields, fieldTreeRecord, setup.registry, BOUND_VALUE_EXCLUSION_BASELINE, formOptions);
+    }, ...(ngDevMode ? [{ debugName: "boundFormValue" }] : /* istanbul ignore next */ []));
     /** Whether the form is currently valid. */
     valid = computed(() => this.formInstance().valid(), ...(ngDevMode ? [{ debugName: "valid" }] : /* istanbul ignore next */ []));
     /** Whether the form is currently invalid. */
@@ -9797,7 +10453,12 @@ class FormStateManager {
     /**
      * Phase-aware field source that coordinates component lifecycle with form updates.
      * Teardown/Applying → intersection of old/new fields; Restoring → all new fields.
-     * Uses key+type equality to avoid spurious emissions during rapid transitions.
+     *
+     * Uses per-field reference equality to suppress spurious emissions when the same
+     * field definitions are returned (e.g. memoized intersections during transitions)
+     * while still triggering re-resolution when the underlying field definition
+     * references change (e.g. a config swap that updates options/props for a
+     * same-keyed field).
      */
     fieldsSource = computed(() => {
         const state = this.machine.state();
@@ -9818,7 +10479,7 @@ class FormStateManager {
                 return true;
             if (a.length !== b.length)
                 return false;
-            return a.every((field, i) => field.key === b[i].key && field.type === b[i].type);
+            return a.every((field, i) => field === b[i]);
         } });
     /**
      * Injector for field components with FIELD_SIGNAL_CONTEXT.
@@ -9984,6 +10645,7 @@ class FormStateManager {
      * Resets the form to default values.
      */
     reset() {
+        this.excludedValueStore.set({});
         const defaults = this.defaultValues();
         this.form()().value.set(defaults);
         this.deps.value.set(defaults);
@@ -9992,6 +10654,7 @@ class FormStateManager {
      * Clears the form to empty state.
      */
     clear() {
+        this.excludedValueStore.set({});
         const emptyValue = {};
         this.form()().value.set(emptyValue);
         this.deps.value.set(emptyValue);
@@ -10016,12 +10679,49 @@ class FormStateManager {
                 this.machine.dispatch({ type: Action.ConfigChange, config });
             }
         });
-        // Outward sync: write entity changes back to deps.value (see entity JSDoc for full explanation).
-        // The isEqual guard prevents infinite ping-pong between this effect and the linkedSignal source.
-        explicitEffect([this.entity], ([currentEntity]) => {
+        // Save-on-exclude: capture entity values for fields that boundFormValue is actively
+        // filtering out via any of the three axes (hidden / disabled / readonly), so they can be
+        // restored when the field becomes re-included. The transition fires once per "no axis
+        // asserted → at least one axis asserted" edge; subsequent axis changes while still excluded
+        // are no-ops. Comparing entity vs bound at the path limits the store to fields that are
+        // actually being filtered — fields without explicit opt-in never enter the store and never
+        // participate in the entity merge. `NaN` values are skipped: they're the number-input default
+        // and would re-leak via the merge once the field becomes re-included.
+        explicitEffect([this.fieldStateSnapshot], ([snapshot]) => {
+            const currentSaved = this.excludedValueStore();
+            const currentEntity = this.entity();
+            const boundValue = this.boundFormValue();
+            const prev = this.prevFieldStateSnapshot();
+            let newSaved = currentSaved;
+            for (const [path, axes] of Object.entries(snapshot)) {
+                if (isFieldExcluded(axes) && !isFieldExcluded(prev[path])) {
+                    const segments = path.split('.');
+                    const inEntity = getValueAtPath(currentEntity, segments);
+                    const inBound = getValueAtPath(boundValue, segments);
+                    if (inEntity !== undefined && inBound === undefined && isRestoreRelevant(inEntity)) {
+                        newSaved = setValueAtPath(newSaved, segments, inEntity);
+                    }
+                }
+            }
+            this.prevFieldStateSnapshot.set({ ...snapshot });
+            if (newSaved !== currentSaved && !isEqual(newSaved, currentSaved)) {
+                this.excludedValueStore.set(newSaved);
+            }
+        });
+        // Schema change resets the saved store + transition tracker so values from a stale schema
+        // can't leak into the new one.
+        explicitEffect([this.formSetup], () => {
+            this.prevFieldStateSnapshot.set({});
+            if (Object.keys(this.excludedValueStore()).length > 0) {
+                this.excludedValueStore.set({});
+            }
+        });
+        // 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.
+        explicitEffect([this.boundFormValue], ([currentBound]) => {
             const currentValue = this.deps.value();
-            if (!isEqual(currentEntity, currentValue)) {
-                this.deps.value.set(currentEntity);
+            if (!isEqual(currentBound, currentValue)) {
+                this.deps.value.set(currentBound);
             }
         });
         explicitEffect([this.formConfigValidation], ([validation]) => {
@@ -10526,15 +11226,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'.`);
 }
 
 /**
@@ -10937,7 +11640,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)
@@ -11244,9 +11947,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}`;
 }
 /**
@@ -11315,7 +12020,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';
@@ -11484,7 +12189,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
@@ -11498,7 +12203,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('*');
         }
     }
@@ -11508,6 +12215,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.
  *
@@ -11850,9 +12583,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,
@@ -12401,9 +13136,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
@@ -12449,8 +13191,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.`);
@@ -12878,7 +13620,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;
@@ -12925,9 +13667,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,
@@ -12976,10 +13723,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);
@@ -13462,8 +14210,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 };
 }
@@ -13495,7 +14251,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';
@@ -13508,6 +14264,7 @@ function createPropertyDerivationEntryFromDerivation(fieldKey, config, context)
         value: config.value,
         expression: config.expression,
         functionName: config.functionName,
+        fn: extractInlineFn(config),
         trigger,
         debounceMs,
         debugName: config.debugName,
@@ -13662,10 +14419,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);
@@ -14758,31 +15515,31 @@ 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-PozYj2JC.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-Pcxg5PQu.mjs'),
         mapper: rowFieldMapper,
         valueHandling: 'flatten',
     },
     {
         name: 'group',
-        loadComponent: () => import('./ng-forge-dynamic-forms-group-field.component-2yRmHAUp.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-group-field.component-fzKwPrQr.mjs'),
         mapper: groupFieldMapper,
         valueHandling: 'include',
     },
     {
         name: 'array',
-        loadComponent: () => import('./ng-forge-dynamic-forms-array-field.component-CWxCWVdz.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-array-field.component-DJ-LiLm_.mjs'),
         mapper: arrayFieldMapper,
         valueHandling: 'include',
     },
     {
         name: 'page',
-        loadComponent: () => import('./ng-forge-dynamic-forms-page-field.component-B_CxX0T-.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-page-field.component-BX4R9GGa.mjs'),
         mapper: pageFieldMapper,
         valueHandling: 'flatten',
     },
     {
         name: 'text',
-        loadComponent: () => import('./ng-forge-dynamic-forms-text-field.component-rJMtKX2X.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-text-field.component-B9SK8Vun.mjs'),
         mapper: textFieldMapper,
         valueHandling: 'exclude',
         ...DISPLAY_FIELD_TYPES_BASE,
@@ -14794,7 +15551,7 @@ const BUILT_IN_FIELDS = [
     },
     {
         name: 'container',
-        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-PozYj2JC.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-Pcxg5PQu.mjs'),
         mapper: containerFieldMapper,
         valueHandling: 'flatten',
     },
@@ -14802,7 +15559,7 @@ const BUILT_IN_FIELDS = [
 const BUILT_IN_WRAPPERS = [
     {
         wrapperName: 'css',
-        loadComponent: () => import('./ng-forge-dynamic-forms-css-wrapper.component-DrtHSaVV.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-css-wrapper.component-CJACCIEK.mjs'),
     },
     {
         wrapperName: 'row',
@@ -15112,6 +15869,48 @@ function withValueExclusionDefaults(config) {
     return createFeature('value-exclusion', [{ provide: VALUE_EXCLUSION_DEFAULTS, useValue: resolved }]);
 }
 
+/**
+ * Configures global validation execution defaults — when validators should run
+ * relative to a field's reactive state.
+ *
+ * By default, validators are **skipped** for hidden fields (`validateWhenHidden: false`),
+ * matching what most users expect: a hidden field is inert. Use this feature to
+ * restore the legacy behavior where hidden fields still validate.
+ *
+ * @example Default behavior — no feature needed
+ * ```typescript
+ * provideDynamicForm(...withMaterialFields())
+ * // hidden fields skip validation
+ * ```
+ *
+ * @example Restore legacy validation-on-hidden behavior
+ * ```typescript
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withValidationExecutionDefaults({ validateWhenHidden: true })
+ * )
+ * ```
+ *
+ * @remarks
+ * **Precedence rules:**
+ * 1. Per-field `FieldDef.validateWhenHidden` — wins for that field; inherits down to descendants
+ *    that don't override.
+ * 2. Per-form `FormOptions.validateWhenHidden` — root inherited value for the form.
+ * 3. Global `withValidationExecutionDefaults()` — fallback when no form/field setting.
+ * 4. No feature configured — uses token default (`validateWhenHidden: false`).
+ *
+ * @param config - Partial override. Unspecified properties keep their defaults.
+ * @returns A `DynamicFormFeature` that configures validation execution defaults.
+ *
+ * @public
+ */
+function withValidationExecutionDefaults(config) {
+    const resolved = {
+        validateWhenHidden: config?.validateWhenHidden ?? false,
+    };
+    return createFeature('validation-execution', [{ provide: VALIDATION_EXECUTION_DEFAULTS, useValue: resolved }]);
+}
+
 /**
  * Zero-cost type carrier used in wrapper registrations.
  *
@@ -15834,5 +16633,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, withValueExclusionDefaults as aL, wrapperProps as aM, 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-Ll4W2Z_n.mjs.map
+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