@ng-forge/dynamic-forms 0.9.0-next.5 → 0.9.0-next.6

package/fesm2022/{ng-forge-dynamic-forms-ng-forge-dynamic-forms-DRYdwQcd.mjs → ng-forge-dynamic-forms-ng-forge-dynamic-forms-QdV2vcCx.mjs}

@@ -4141,9 +4141,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-DBWSe936.mjs').then(m => m.default)], () => [import('./ng-forge-dynamic-forms-page-field.component-DBWSe936.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-BHNVryIq.mjs').then(m => m.default)], () => [import('./ng-forge-dynamic-forms-page-field.component-BHNVryIq.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-DBWSe936.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-BHNVryIq.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) {
@@ -6187,6 +6187,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 +6370,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 +6416,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 +6558,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 +6629,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 +6655,7 @@ function mapArrayFieldToForm(arrayField, fieldPath) {
                 if (fieldKey) {
                     const fieldPathForKey = pathRecord[fieldKey];
                     if (fieldPathForKey) {
-                        mapFieldToForm(templateField, fieldPathForKey);
+                        mapFieldToForm(templateField, fieldPathForKey, context);
                     }
                 }
             }
@@ -7185,6 +7359,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.
@@ -7229,11 +7424,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);
@@ -7243,12 +7444,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;
@@ -7261,7 +7467,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) {
@@ -7869,49 +8075,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 };
 }
 /**
@@ -8520,6 +8731,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
@@ -8529,8 +8745,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;
@@ -9794,6 +10022,7 @@ class FormStateManager {
             return createSchemaFromFields(setup.schemaFields, setup.registry, {
                 crossFieldValidators: crossFieldCollection.validators,
                 formLevelSchema: config.schema,
+                validateWhenHidden: this.effectiveFormOptions().validateWhenHidden,
             });
         }
         if (config.schema) {
@@ -9897,7 +10126,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();
@@ -9918,7 +10152,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.
@@ -14858,31 +15092,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-BMDGh8bN.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-D4Fpr2ri.mjs'),
         mapper: rowFieldMapper,
         valueHandling: 'flatten',
     },
     {
         name: 'group',
-        loadComponent: () => import('./ng-forge-dynamic-forms-group-field.component-BR7nCNmT.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-group-field.component-BxswrhOc.mjs'),
         mapper: groupFieldMapper,
         valueHandling: 'include',
     },
     {
         name: 'array',
-        loadComponent: () => import('./ng-forge-dynamic-forms-array-field.component-DYPTXG9B.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-array-field.component-CltYGHg9.mjs'),
         mapper: arrayFieldMapper,
         valueHandling: 'include',
     },
     {
         name: 'page',
-        loadComponent: () => import('./ng-forge-dynamic-forms-page-field.component-DBWSe936.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-page-field.component-BHNVryIq.mjs'),
         mapper: pageFieldMapper,
         valueHandling: 'flatten',
     },
     {
         name: 'text',
-        loadComponent: () => import('./ng-forge-dynamic-forms-text-field.component-CCGX7m_z.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-text-field.component-Cf1mEKVW.mjs'),
         mapper: textFieldMapper,
         valueHandling: 'exclude',
         ...DISPLAY_FIELD_TYPES_BASE,
@@ -14894,7 +15128,7 @@ const BUILT_IN_FIELDS = [
     },
     {
         name: 'container',
-        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-BMDGh8bN.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-D4Fpr2ri.mjs'),
         mapper: containerFieldMapper,
         valueHandling: 'flatten',
     },
@@ -14902,7 +15136,7 @@ const BUILT_IN_FIELDS = [
 const BUILT_IN_WRAPPERS = [
     {
         wrapperName: 'css',
-        loadComponent: () => import('./ng-forge-dynamic-forms-css-wrapper.component-hRiX9Jmf.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-css-wrapper.component-mdfySFjX.mjs'),
     },
     {
         wrapperName: 'row',
@@ -15212,6 +15446,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.
  *
@@ -15934,5 +16210,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-DRYdwQcd.mjs.map
+export { SubmitEvent as $, ARRAY_CONTEXT as A, BUILT_IN_FIELDS as B, CONTAINER_FIELD_PROCESSORS as C, DynamicFormLogger as D, EventBus as E, FIELD_SIGNAL_CONTEXT as F, DEFAULT_VALIDATION_MESSAGES as G, DynamicForm as H, DynamicFormError as I, EventDispatcher as J, FIELD_REGISTRY as K, FORM_OPTIONS as L, FormClearEvent as M, FormResetEvent as N, INITIALIZATION_TIMEOUT_MS as O, InsertArrayItemEvent as P, MoveArrayItemEvent as Q, RootFormRegistryService as R, NextPageEvent as S, NoopLogger as T, PageChangeEvent as U, PopArrayItemEvent as V, WRAPPER_AUTO_ASSOCIATIONS as W, PrependArrayItemEvent as X, PreviousPageEvent as Y, RemoveAtIndexEvent as Z, ShiftArrayItemEvent as _, DEFAULT_WRAPPERS as a, WRAPPER_REGISTRY as a0, applyMetaToElement as a1, applyValidator as a2, applyValidators as a3, arrayEvent as a4, arrayFieldMapper as a5, baseFieldMapper as a6, buildBaseInputs as a7, containerFieldMapper as a8, createField as a9, resolveNextButtonDisabled as aA, resolveNonFieldDisabled as aB, resolveNonFieldHidden as aC, resolveSubmitButtonDisabled as aD, resolveTokens as aE, rowFieldMapper as aF, textFieldMapper as aG, toReadonlyFieldTree as aH, withEventFormValue as aI, withLoggerConfig as aJ, withPreviousValue as aK, withValidationExecutionDefaults as aL, withValueExclusionDefaults as aM, wrapperProps as aN, createWrappers as aa, evaluateNonFieldDisabled as ab, evaluateNonFieldHidden as ac, field as ad, formConfig as ae, getArrayLength as af, groupFieldMapper as ag, hasFormValue as ah, interpolateParams as ai, isArrayField as aj, isCheckedField as ak, isContainerField as al, isContainerTypedField as am, isDisplayOnlyField as an, isFormStateCondition as ao, isLeafField as ap, isPageField as aq, isRowField as ar, isSimplifiedArrayField as as, isValueBearingField as at, isValueField as au, isWrapperTypeDefinition as av, isWrappersBundle as aw, omit as ax, pageFieldMapper as ay, provideDynamicForm as az, isSameWrapperChain as b, createFieldResolutionPipe as c, derivedFromDeferred as d, createWrapperChainController as e, DfFieldOutlet as f, isEqual as g, createSchemaFromFields as h, injectFieldRegistry as i, createRenderReadySignal as j, ARRAY_TEMPLATE_REGISTRY as k, ARRAY_ITEM_ID_GENERATOR as l, mapFieldToInputs as m, getNormalizedArrayMetadata as n, getFieldValueHandling as o, getFieldDefaultValue as p, isGroupField as q, resolveWrappers as r, createArrayItemIdGenerator as s, ComponentInitializedEvent as t, DynamicTextPipe as u, validatePageNesting as v, dynamicTextToObservable as w, AppendArrayItemEvent as x, ConsoleLogger as y, DEFAULT_PROPS as z };
+//# sourceMappingURL=ng-forge-dynamic-forms-ng-forge-dynamic-forms-QdV2vcCx.mjs.map