@ng-forge/dynamic-forms 0.8.0-next.4 → 0.8.0-next.5

package/fesm2022/{ng-forge-dynamic-forms-ng-forge-dynamic-forms-BdMxsqmk.mjs → ng-forge-dynamic-forms-ng-forge-dynamic-forms-Bw9Bt0Ev.mjs}

@@ -1318,13 +1318,11 @@ function setupInitializationTracking(options) {
 }
 
 /**
- * Type guard to check if a field is a hidden field.
- *
- * @param field - The field to check
- * @returns True if the field is a HiddenField
+ * Type guard for RowField with proper type narrowing
  */
-function isHiddenField(field) {
-    return field.type === 'hidden';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Type guard must accept any field type
+function isRowField(field) {
+    return field.type === 'row' && 'fields' in field && Array.isArray(field.fields);
 }
 
 /**
@@ -1336,41 +1334,20 @@ function isGroupField(field) {
 }
 
 /**
- * Type guard for RowField with proper type narrowing
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Type guard must accept any field type
-function isRowField(field) {
-    return field.type === 'row' && 'fields' in field && Array.isArray(field.fields);
-}
-/**
- * Validates that a row field doesn't contain hidden fields.
- * Hidden fields are not allowed in rows because rows are for horizontal layouts,
- * and hidden fields don't render anything.
+ * Type guard for ContainerField with proper type narrowing.
  *
- * @param rowField The row field to validate
- * @returns true if valid (no hidden fields), false otherwise
- */
-function validateRowNesting(rowField) {
-    return !hasHiddenFields(rowField.fields);
-}
-/**
- * Recursively checks if fields contain any hidden fields
- * @param fields Array of field definitions to check
- * @returns true if hidden fields found, false otherwise
+ * `wrappers` is part of the type but optional in practice — many configs use
+ * containers purely as flex/layout wrappers without any wrapper components.
+ * Match on `type === 'container'` and the `fields` shape only, mirroring
+ * `isPageField` / `isRowField`.
  */
-function hasHiddenFields(fields) {
-    for (const field of fields) {
-        if (isHiddenField(field)) {
-            return true;
-        }
-        // Check group fields for nested hidden fields
-        if (isGroupField(field)) {
-            if (hasHiddenFields(field.fields)) {
-                return true;
-            }
-        }
-    }
-    return false;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Type guard must accept any field type
+function isContainerTypedField(field) {
+    return (field.type === 'container' &&
+        'wrappers' in field &&
+        'fields' in field &&
+        Array.isArray(field.wrappers) &&
+        Array.isArray(field.fields));
 }
 
 /**
@@ -1391,7 +1368,9 @@ function validatePageNesting(pageField) {
  * Type guard to check if a field is a container with fields property
  */
 function isContainerWithFields$1(field) {
-    return (isRowField(field) || isGroupField(field)) && 'fields' in field && Array.isArray(field.fields);
+    return ((isRowField(field) || isGroupField(field) || isContainerTypedField(field)) &&
+        'fields' in field &&
+        Array.isArray(field.fields));
 }
 /**
  * Recursively checks if fields contain any nested page fields
@@ -1431,14 +1410,6 @@ function isSimplifiedArrayField(field) {
     return field.type === 'array' && 'template' in field;
 }
 
-/**
- * Type guard for ContainerField with proper type narrowing
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Type guard must accept any field type
-function isContainerTypedField(field) {
-    return field.type === 'container' && 'fields' in field && 'wrappers' in field;
-}
-
 /**
  * Type guard to check if a field definition has child fields.
  * This is a looser check that works with FieldDef<unknown> without requiring RegisteredFieldTypes.
@@ -4170,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-C5rUo80O.mjs').then(m => m.default)], () => [import('./ng-forge-dynamic-forms-page-field.component-C5rUo80O.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-XtyjFlJi.mjs').then(m => m.default)], () => [import('./ng-forge-dynamic-forms-page-field.component-XtyjFlJi.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-C5rUo80O.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-XtyjFlJi.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) {
@@ -4558,7 +4529,7 @@ function hasAnyPageFields(fields) {
             return true;
         }
         // Check nested fields in container types
-        if (isContainerWithFields(field) && (field.type === 'row' || field.type === 'group')) {
+        if (!isPageField(field) && isContainerWithFields(field)) {
             if (hasAnyPageFields(field.fields)) {
                 return true;
             }
@@ -4581,7 +4552,7 @@ function hasNestedPageFields(fields) {
             }
         }
         // Check other container types for nested pages
-        if (isContainerWithFields(field) && (field.type === 'row' || field.type === 'group')) {
+        if (!isPageField(field) && isContainerWithFields(field)) {
             if (hasNestedPageFields(field.fields)) {
                 return true;
             }
@@ -6318,12 +6289,22 @@ function mapFieldToForm(fieldDef, fieldPath) {
 }
 /**
  * Maps children of a container field (page, row, group) to the form schema.
+ *
+ * Layout containers (page/row/container) flatten into `parentPath` and are
+ * recursed through without consuming a key — same contract as `mapFieldToForm`'s
+ * top-level layout branch, so any depth of layout-container nesting reaches its
+ * leaf descendants. Group/array fields consume their key and look up their own
+ * child path on `parentPath`.
  */
 function mapContainerChildren(fields, parentPath) {
     if (!fields)
         return;
     const pathRecord = parentPath;
     for (const field of fields) {
+        if (isPageField(field) || isRowField(field) || isContainerTypedField(field)) {
+            mapContainerChildren(field.fields, parentPath);
+            continue;
+        }
         if (!field.key)
             continue;
         const childPath = pathRecord[field.key];
@@ -6419,9 +6400,21 @@ function mapArrayFieldToForm(arrayField, fieldPath) {
         maxLength(fieldPath, arrayField.maxLength);
     }
     // Fields can be either FieldDef (primitive) or FieldDef[] (object)
-    const itemDefinitions = arrayField.fields;
-    // Empty array is valid - items will be added via buttons with their own templates
-    // Create a minimal schema that just accepts any value
+    let itemDefinitions = arrayField.fields;
+    // Simplified arrays initialized without `value` have empty `fields`; their
+    // item shape only lives in Symbol metadata. Fall back to that template so
+    // validators and logic declared inside it still apply when items are
+    // materialized from a programmatically-set form value.
+    if (!itemDefinitions || itemDefinitions.length === 0) {
+        const metadataTemplate = getNormalizedArrayMetadata(arrayField)?.template;
+        if (metadataTemplate) {
+            itemDefinitions = [
+                Array.isArray(metadataTemplate) ? [...metadataTemplate] : metadataTemplate,
+            ];
+        }
+    }
+    // Empty array with no template metadata - items will be added via buttons with
+    // their own templates. Create a minimal schema that just accepts any value.
     if (!itemDefinitions || itemDefinitions.length === 0) {
         const emptyItemSchema = schema(() => {
             // No fields to map - items will be added dynamically via buttons
@@ -6433,14 +6426,22 @@ function mapArrayFieldToForm(arrayField, fieldPath) {
     let hasPrimitiveItems = false;
     const allObjectFields = [];
     for (const itemDef of itemDefinitions) {
-        if (!Array.isArray(itemDef)) {
-            // Primitive item: single FieldDef
-            hasPrimitiveItems = true;
-        }
-        else {
+        if (Array.isArray(itemDef)) {
             // Object item: collect fields for superset schema
             collectFieldsFromObjectItem(itemDef, allObjectFields);
         }
+        else if (isPageField(itemDef) ||
+            isRowField(itemDef) ||
+            isContainerTypedField(itemDef)) {
+            // Layout container as a single-template item: its descendants describe
+            // the item's object shape. Hand it to the object-item collector wrapped
+            // as a 1-element array so the structured-item mapping path runs.
+            collectFieldsFromObjectItem([itemDef], allObjectFields);
+        }
+        else {
+            // Primitive item: single FieldDef
+            hasPrimitiveItems = true;
+        }
     }
     // For pure primitive arrays, use a simple schema
     if (hasPrimitiveItems && allObjectFields.length === 0) {
@@ -6580,7 +6581,7 @@ function getFieldDefaultValue(field, registry) {
     if (valueHandling === 'exclude') {
         return undefined;
     }
-    // Flatten fields (row/page) return flattened object of children's values
+    // Flatten fields (row/page/container) return flattened object of children's values
     // This is used by array fields to get the template structure
     // Note: fieldsToDefaultValues will skip these at top-level since they have keys and return objects
     if (valueHandling === 'flatten' && 'fields' in field && field.fields) {
@@ -6588,11 +6589,18 @@ function getFieldDefaultValue(field, registry) {
         // Collect only fields that contribute values (exclude buttons, text, etc.)
         const flattenedValues = {};
         for (const childField of childFields) {
-            if ('key' in childField && childField.key) {
-                const childValue = getFieldDefaultValue(childField, registry);
-                if (childValue !== undefined) {
-                    flattenedValues[childField.key] = childValue;
-                }
+            const childValueHandling = getFieldValueHandling(childField.type, registry);
+            if (childValueHandling === 'exclude')
+                continue;
+            const childValue = getFieldDefaultValue(childField, registry);
+            if (childValue === undefined)
+                continue;
+            if (childValueHandling === 'flatten' && childValue && typeof childValue === 'object' && !Array.isArray(childValue)) {
+                // Nested flatten field — its value is already flat; spread it up.
+                Object.assign(flattenedValues, childValue);
+            }
+            else if ('key' in childField && childField.key) {
+                flattenedValues[childField.key] = childValue;
             }
         }
         // Return flattened object if there are any values, otherwise undefined
@@ -6607,20 +6615,17 @@ function getFieldDefaultValue(field, registry) {
         const groupDefaults = {};
         for (const childField of fields) {
             const childValueHandling = getFieldValueHandling(childField.type, registry);
-            // Flatten row/page fields into the group (they are presentational containers)
-            if (childValueHandling === 'flatten' && 'fields' in childField && childField.fields) {
-                const nestedFields = childField.fields;
-                for (const nestedField of nestedFields) {
-                    if ('key' in nestedField && nestedField.key) {
-                        const nestedValue = getFieldDefaultValue(nestedField, registry);
-                        if (nestedValue !== undefined) {
-                            groupDefaults[nestedField.key] = nestedValue;
-                        }
-                    }
+            if (childValueHandling === 'exclude')
+                continue;
+            const childValue = getFieldDefaultValue(childField, registry);
+            if (childValueHandling === 'flatten') {
+                // Flatten container/row/page values into the group (they are presentational containers).
+                // The recursive call already returns a flat object — spread it directly.
+                if (childValue && typeof childValue === 'object' && !Array.isArray(childValue)) {
+                    Object.assign(groupDefaults, childValue);
                 }
             }
             else if ('key' in childField && childField.key) {
-                const childValue = getFieldDefaultValue(childField, registry);
                 if (childValue !== undefined) {
                     groupDefaults[childField.key] = childValue;
                 }
@@ -7438,10 +7443,10 @@ function createEmptyCollection() {
 /** Traverses field definitions and collects cross-field entries (validators, logic, schemas). */
 function collectCrossFieldEntries(fields) {
     const collection = createEmptyCollection();
-    traverseFields$2(fields, collection, '');
+    traverseFields(fields, collection, '');
     return collection;
 }
-function traverseFields$2(fields, collection, pathPrefix) {
+function traverseFields(fields, collection, pathPrefix) {
     for (const field of fields) {
         collectFromField$2(field, collection, pathPrefix);
         // Recursively process container fields (page, row, group, array)
@@ -7453,7 +7458,7 @@ function traverseFields$2(fields, collection, pathPrefix) {
             // be built for them.
             const groupKey = isGroupField(field) ? field.key : undefined;
             const childPrefix = groupKey ? (pathPrefix ? `${pathPrefix}.${groupKey}` : groupKey) : pathPrefix;
-            traverseFields$2(normalizeFieldsArray(field.fields), collection, childPrefix);
+            traverseFields(normalizeFieldsArray(field.fields), collection, childPrefix);
         }
     }
 }
@@ -8168,6 +8173,29 @@ function buildPropertyOverrideKey(arrayKey, index, fieldKey) {
     return fieldKey;
 }
 
+/**
+ * Returns true if the field has any property-derivation logic entries
+ * (type: 'derivation' with a non-empty targetProperty). Mirrors the inclusion
+ * rule used by `collectPropertyDerivations`, so the mapper and orchestrator
+ * agree on which fields participate in property overrides — without depending
+ * on whether the orchestrator's registration effect has run yet (which it
+ * hasn't on the resolveFieldSync path with a warm COMPONENT_CACHE).
+ */
+function fieldHasPropertyDerivations(fieldDef) {
+    // Match the collector's keyless guard (property-derivation-collector.ts):
+    // keyless fields are never registered in the store, so the mapper must skip
+    // them too — otherwise getOverrides() would be called with an undefined key.
+    if (!fieldDef.key)
+        return false;
+    const logic = fieldDef.logic;
+    if (!logic || logic.length === 0)
+        return false;
+    for (const entry of logic) {
+        if (isDerivationLogicConfig(entry) && hasTargetProperty(entry))
+            return true;
+    }
+    return false;
+}
 /**
  * Merges forwarded props into meta, with meta taking precedence.
  *
@@ -8269,11 +8297,13 @@ 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);
-    // Fast-path check for property overrides: only fields with registered derivations
-    // enter the computed() wrapper for overrides. hasField() is a non-reactive Map.has() — O(1).
-    // Uses PLACEHOLDER_INDEX to produce the wildcard format (e.g., 'items.$.endDate') matching
-    // what the collector/orchestrator registers. The computed block below uses a concrete index instead.
-    const hasOverrides = store?.hasField(buildPropertyOverrideKey(arrayContext?.arrayKey, arrayContext ? PLACEHOLDER_INDEX : undefined, fieldDef.key)) ?? false;
+    // 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
+    // effect may not have fired yet when the mapper runs in the resolveFieldSync
+    // path (warm COMPONENT_CACHE). Both the mapper and the orchestrator's
+    // collector apply the same inclusion rule, so the answers always agree.
+    const hasOverrides = fieldHasPropertyDerivations(fieldDef);
     // Fast path: no transformations needed
     if (!hasPropsForwarding && !hasArrayContext && !hasOverrides) {
         return mapperResult;
@@ -8427,8 +8457,7 @@ function createFieldResolutionPipe(getContext) {
  * Comprehensive form configuration validator that checks:
  * 1. Form mode consistency (paged vs non-paged)
  * 2. Page nesting rules
- * 3. Row nesting rules (no hidden fields in rows)
- * 4. Field placement constraints
+ * 3. Field placement constraints
  */
 class FormModeValidator {
     /**
@@ -8495,57 +8524,6 @@ class FormModeValidator {
                 }
             }
         }
-        // Warn about hidden fields in rows (they work but don't render, which may be confusing)
-        const rowWarnings = this.collectRowHiddenFieldWarnings(fields);
-        warnings.push(...rowWarnings);
-        return warnings;
-    }
-    /**
-     * Recursively collects warnings for hidden fields inside rows
-     * @param fields The form field definitions to check
-     * @param path Current path for warning messages
-     * @returns Array of warning messages
-     */
-    static collectRowHiddenFieldWarnings(fields, path = '') {
-        if (!fields) {
-            return [];
-        }
-        const warnings = [];
-        for (let i = 0; i < fields.length; i++) {
-            const field = fields[i];
-            const fieldPath = path ? `${path}.fields[${i}]` : `fields[${i}]`;
-            const fieldKey = field.key || 'unknown';
-            if (isRowField(field)) {
-                if (!validateRowNesting(field)) {
-                    warnings.push(`Row field at ${fieldPath} (key: "${fieldKey}") contains hidden fields. ` +
-                        `Hidden fields in rows don't render anything - consider placing them outside the row.`);
-                }
-                // Continue checking nested rows within the row's children
-                warnings.push(...this.collectRowHiddenFieldWarnings(field.fields, fieldPath));
-            }
-            else if (isPageField(field)) {
-                // Check rows within pages
-                warnings.push(...this.collectRowHiddenFieldWarnings(field.fields, fieldPath));
-            }
-            else if (isGroupField(field)) {
-                // Check rows within groups
-                warnings.push(...this.collectRowHiddenFieldWarnings(field.fields, fieldPath));
-            }
-            else if (isSimplifiedArrayField(field)) {
-                // Simplified arrays are normalized later; check template fields if present
-                const templateFields = Array.isArray(field.template) ? [...field.template] : [field.template];
-                warnings.push(...this.collectRowHiddenFieldWarnings(templateFields, fieldPath));
-            }
-            else if (isArrayField(field)) {
-                // Check rows within array templates — items may be single FieldDef (primitive) or FieldDef[] (object)
-                const itemTemplates = field.fields;
-                for (let j = 0; j < itemTemplates.length; j++) {
-                    const itemFields = itemTemplates[j];
-                    const fieldsArray = Array.isArray(itemFields) ? [...itemFields] : [itemFields];
-                    warnings.push(...this.collectRowHiddenFieldWarnings(fieldsArray, `${fieldPath}.fields[${j}]`));
-                }
-            }
-        }
         return warnings;
     }
 }
@@ -10532,6 +10510,33 @@ function parseDerivationKey(key) {
     return { fieldKey: key };
 }
 
+/**
+ * Single dispatch over `value` / `expression` / `functionName` shared by both
+ * the value-derivation and property-derivation applicators.
+ *
+ * Throws {@link DynamicFormError} on missing function or missing value source
+ * so both pipelines surface the library's standard error type.
+ *
+ * @internal
+ */
+function computeValueFromEntry(entry, evalContext, options) {
+    if (entry.value !== undefined) {
+        return entry.value;
+    }
+    if (entry.expression) {
+        return ExpressionParser.evaluate(entry.expression, evalContext);
+    }
+    if (entry.functionName) {
+        const fn = options.derivationFunctions?.[entry.functionName];
+        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'.`);
+}
+
 /**
  * Centralized constants for the derivation system.
  *
@@ -11101,10 +11106,15 @@ function createEvaluationContext$1(entry, formValue, context, chainContext) {
     // Create field state snapshot for this specific field (non-reactive)
     const fieldAccessor = context.rootForm[entry.fieldKey];
     const fieldState = fieldAccessor ? readFieldStateInfo(fieldAccessor, false) : undefined;
+    // Parent group value: the absolute path with the trailing field segment
+    // dropped. `undefined` when the field is at form root.
+    const parentPath = getParentPathInScope(entry.fieldKey);
+    const groupValue = parentPath ? getNestedValue(formValue, parentPath) : undefined;
     return {
         fieldValue,
         formValue,
         fieldPath: entry.fieldKey,
+        groupValue,
         customFunctions: context.customFunctions,
         externalData: context.externalData,
         logger: context.logger,
@@ -11112,6 +11122,25 @@ function createEvaluationContext$1(entry, formValue, context, chainContext) {
         formFieldState: chainContext.formFieldState,
     };
 }
+/**
+ * Returns the path to the parent of the given field path, expressed in the
+ * scope appropriate for the entry. Drops the last `.`-delimited segment.
+ * Returns `undefined` when the field has no parent in scope (e.g., a
+ * single-segment root key, or `'items.$.x'` inside the array-item scope
+ * where `x` is a direct child of the item).
+ *
+ * For non-array entries: `'address.state'` → `'address'`, `'state'` → undefined.
+ * For array entries inside `createEvaluationContext` (root scope): unused —
+ * `createArrayItemEvaluationContext` handles the array-scope case.
+ *
+ * @internal
+ */
+function getParentPathInScope(fieldKey) {
+    const lastDot = fieldKey.lastIndexOf('.');
+    if (lastDot <= 0)
+        return undefined;
+    return fieldKey.slice(0, lastDot);
+}
 /**
  * Creates an evaluation context scoped to a specific array item.
  *
@@ -11143,10 +11172,23 @@ function createArrayItemEvaluationContext$1(entry, arrayItem, rootFormValue, ite
             }
         }
     }
+    // groupValue inside an array item:
+    // - Field directly under the array item (no inner group): the array item
+    //   itself is the "nearest parent group".
+    // - Field inside an inner group within the item: the inner group's value.
+    // The relative path within the item is everything after `'.$.'`.
+    const relativePath = pathInfo.isArrayPath ? (pathInfo.relativePath ?? '') : '';
+    const innerParentPath = relativePath.includes('.') ? relativePath.slice(0, relativePath.lastIndexOf('.')) : '';
+    const groupValue = innerParentPath ? getNestedValue(arrayItem, innerParentPath) : arrayItem;
+    // Resolve fieldValue to the leaf value addressed by the entry's relative path
+    // within the array item. Without this, $self / fieldValue derivations inside
+    // arrays receive the whole array item instead of the field's own value.
+    const fieldValue = relativePath ? getNestedValue(arrayItem, relativePath) : arrayItem;
     return {
-        fieldValue: arrayItem,
+        fieldValue,
         formValue: arrayItem,
-        fieldPath: `${arrayPath}.${itemIndex}`,
+        fieldPath: relativePath ? `${arrayPath}.${itemIndex}.${relativePath}` : `${arrayPath}.${itemIndex}`,
+        groupValue,
         customFunctions: context.customFunctions,
         externalData: context.externalData,
         logger: context.logger,
@@ -11175,24 +11217,10 @@ function evaluateDerivationCondition(condition, context) {
  * @internal
  */
 function computeDerivedValue(entry, evalContext, applicatorContext) {
-    // Static value
-    if (entry.value !== undefined) {
-        return entry.value;
-    }
-    // Expression
-    if (entry.expression) {
-        return ExpressionParser.evaluate(entry.expression, evalContext);
-    }
-    // Custom function
-    if (entry.functionName) {
-        const fn = applicatorContext.derivationFunctions?.[entry.functionName];
-        if (!fn) {
-            throw new Error(`Derivation function '${entry.functionName}' not found in customFnConfig.derivations`);
-        }
-        return fn(evalContext);
-    }
-    // No value source specified
-    throw new Error(`Derivation for ${entry.fieldKey} has no value source. ` + `Specify 'value', 'expression', or 'functionName'.`);
+    return computeValueFromEntry(entry, evalContext, {
+        derivationFunctions: applicatorContext.derivationFunctions,
+        subject: entry.fieldKey,
+    });
 }
 /**
  * Error message prefix for derivation-related errors.
@@ -11442,6 +11470,134 @@ function topologicalSort(entries) {
     return sorted;
 }
 
+/**
+ * Extracts the union of field dependencies declared by a derivation config.
+ *
+ * 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)
+ * - Condition expression dependencies (always included)
+ *
+ * @internal
+ */
+function extractDependenciesFromConfig(config) {
+    const deps = new Set();
+    if (config.dependsOn && config.dependsOn.length > 0) {
+        config.dependsOn.forEach((dep) => deps.add(dep));
+    }
+    else {
+        if (config.expression) {
+            extractStringDependencies(config.expression).forEach((dep) => deps.add(dep));
+        }
+        if (config.functionName) {
+            deps.add('*');
+        }
+    }
+    if (config.condition && config.condition !== true) {
+        extractExpressionDependencies(config.condition).forEach((dep) => deps.add(dep));
+    }
+    return Array.from(deps);
+}
+
+/**
+ * Recursively walks a field-definition tree, invoking `visitor` for each field.
+ *
+ * Owns the subtleties shared across derivation collectors:
+ * - Detects container fields via `hasChildFields`.
+ * - Falls back to the simplified-array Symbol-metadata template when an array
+ *   field has empty `fields` (the case for arrays initialized without a
+ *   starting `value` — only the metadata template carries their item shape).
+ * - Flattens primitive (FieldDef) and object (FieldDef[]) array items into a
+ *   single child list before recursing.
+ *
+ * Callers customize per-boundary context via {@link FieldTraversalHooks}: e.g.,
+ * the value-derivation collector tracks an array path AND a group path (with
+ * the group path reset at array boundaries), while the property-derivation
+ * collector tracks only the array path.
+ *
+ * @internal
+ */
+function traverseFieldsWithContext(fields, context, visitor, hooks) {
+    for (const field of fields) {
+        visitor(field, context);
+        if (!hasChildFields(field))
+            continue;
+        if (field.type === 'array') {
+            const childContext = mergeContext(context, hooks?.onArrayChild?.(context, field));
+            const arrayChildren = collectArrayChildren(field);
+            traverseFieldsWithContext(arrayChildren, childContext, visitor, hooks);
+            continue;
+        }
+        const overrides = field.type === 'group' ? hooks?.onGroupChild?.(context, field) : hooks?.onLayoutChild?.(context, field);
+        const childContext = mergeContext(context, overrides);
+        traverseFieldsWithContext(normalizeFieldsArray(field.fields), childContext, visitor, hooks);
+    }
+}
+/**
+ * Returns the flattened list of children for an array field, falling back
+ * to the Symbol metadata template when `fields` is empty.
+ *
+ * Caller must ensure `field` is a container (passes `hasChildFields`); this
+ * function reads `field.fields` directly and would error otherwise.
+ *
+ * @internal
+ */
+function collectArrayChildren(field) {
+    let arrayItems = normalizeFieldsArray(field.fields);
+    if (arrayItems.length === 0) {
+        const metadataTemplate = getNormalizedArrayMetadata(field)?.template;
+        if (metadataTemplate) {
+            arrayItems = [
+                Array.isArray(metadataTemplate) ? [...metadataTemplate] : metadataTemplate,
+            ];
+        }
+    }
+    const flattened = [];
+    for (const item of arrayItems) {
+        if (Array.isArray(item)) {
+            flattened.push(...item);
+        }
+        else {
+            flattened.push(item);
+        }
+    }
+    return flattened;
+}
+/** @internal */
+function mergeContext(base, overrides) {
+    return overrides ? { ...base, ...overrides } : { ...base };
+}
+
+/**
+ * Token in `dependsOn` arrays that resolves to the current field's own
+ * absolute path at collection time. Useful for self-derivations on fields
+ * nested under groups, where the absolute path depends on ancestor keys
+ * the config author may not know (e.g. factory-built field shapes).
+ *
+ * @public
+ */
+const SELF_DEPENDENCY_TOKEN = '$self';
+/**
+ * Token in `dependsOn` arrays that resolves to the absolute path of the
+ * field's nearest parent container (group or array) at collection time.
+ *
+ * Useful when a derivation should fire whenever any sibling under the
+ * same parent container changes (e.g. "compute when anything in the
+ * address group is edited") without enumerating each sibling explicitly.
+ *
+ * Resolution rules:
+ * - Inside group(s) only: resolves to the dotted ancestor group path
+ *   (e.g. `'address'` or `'org.address'`).
+ * - Inside an array (no group between): resolves to the array key
+ *   (e.g. `'items'`). Fires whenever any item changes.
+ * - Inside group(s) inside an array: resolves to the array placeholder
+ *   form including the inner groups (e.g. `'items.$.address'`).
+ * - At form root: throws `DynamicFormError` (no parent to target).
+ *
+ * @public
+ */
+const GROUP_DEPENDENCY_TOKEN = '$group';
 /**
  * Collects all derivation entries from field definitions.
  *
@@ -11479,8 +11635,21 @@ function topologicalSort(entries) {
  */
 function collectDerivations(fields) {
     const entries = [];
-    const context = {};
-    traverseFields$1(fields, entries, context);
+    traverseFieldsWithContext(fields, {}, (field, context) => collectFromField$1(field, entries, context), {
+        // Array boundary: the array placeholder path takes over and any
+        // ancestor groupPath is reset for descendants (entries inside
+        // array items use `arrayPath.$.fieldKey` form).
+        onArrayChild: (_, field) => ({ arrayPath: field.key, groupPath: undefined }),
+        onGroupChild: (parent, field) => {
+            // Group establishes a model boundary; descend with the field's
+            // key appended to the ancestor groupPath. Groups without a key
+            // (rare) act like layout containers — leave context unchanged.
+            if (!field.key)
+                return {};
+            return { groupPath: parent.groupPath ? `${parent.groupPath}.${field.key}` : field.key };
+        },
+        // Layout containers (page, row, container) leave context unchanged.
+    });
     // Sort entries in topological order for efficient processing.
     // This ensures derivations are processed in dependency order,
     // reducing the number of iterations needed in the applicator.
@@ -11488,40 +11657,83 @@ function collectDerivations(fields) {
     return { entries: sortedEntries };
 }
 /**
- * Recursively traverses field definitions to collect derivations.
+ * Builds the absolute field path for a derivation entry from the field's
+ * key and the current collection context.
+ *
+ * - Inside an array AND inside one or more groups (groups nested under
+ *   the array item): combines both as `${arrayPath}.$.${groupPath}.${fieldKey}`.
+ * - Inside an array only: returns `${arrayPath}.$.${fieldKey}`.
+ * - Inside one or more groups: returns `${groupPath}.${fieldKey}`.
+ * - Otherwise returns `fieldKey` unchanged.
+ *
+ * `groupPath` is reset when entering an array (each array item is its own
+ * model root); ancestor groups OUTSIDE the array are not part of the
+ * entry path. Groups INSIDE the array are tracked via `groupPath` and
+ * combined here.
  *
  * @internal
  */
-function traverseFields$1(fields, entries, context) {
-    for (const field of fields) {
-        collectFromField$1(field, entries, context);
-        // Recursively process container fields (page, row, group, array)
-        if (hasChildFields(field)) {
-            const childContext = { ...context };
-            // Update array path context if this is an array field
-            if (field.type === 'array') {
-                childContext.arrayPath = field.key;
-                // Array fields have items that can be either FieldDef (primitive) or FieldDef[] (object).
-                // Normalize all items to arrays and flatten for traversal.
-                const arrayItems = normalizeFieldsArray(field.fields);
-                const normalizedChildren = [];
-                for (const item of arrayItems) {
-                    if (Array.isArray(item)) {
-                        // Object item: FieldDef[] - add each field
-                        normalizedChildren.push(...item);
-                    }
-                    else {
-                        // Primitive item: single FieldDef - add directly
-                        normalizedChildren.push(item);
-                    }
-                }
-                traverseFields$1(normalizedChildren, entries, childContext);
-            }
-            else {
-                traverseFields$1(normalizeFieldsArray(field.fields), entries, childContext);
+function buildEffectiveFieldKey(fieldKey, context) {
+    if (context.arrayPath && context.groupPath) {
+        return `${context.arrayPath}.$.${context.groupPath}.${fieldKey}`;
+    }
+    if (context.arrayPath) {
+        return `${context.arrayPath}.$.${fieldKey}`;
+    }
+    if (context.groupPath) {
+        return `${context.groupPath}.${fieldKey}`;
+    }
+    return fieldKey;
+}
+/**
+ * Resolves the absolute path of the field's nearest parent container
+ * (group or array). Returns `undefined` when the field is at the form
+ * root with no parent container.
+ *
+ * @internal
+ */
+function buildNearestGroupPath(context) {
+    if (context.arrayPath && context.groupPath) {
+        return `${context.arrayPath}.$.${context.groupPath}`;
+    }
+    return context.arrayPath ?? context.groupPath;
+}
+/**
+ * Substitutes special tokens in a `dependsOn` array with their resolved
+ * absolute paths. Currently supports:
+ *
+ * - `SELF_DEPENDENCY_TOKEN` ('$self') → the field's own absolute path
+ * - `'$self.X'` → the field's own path joined with `.X` (e.g. for object-valued
+ *   fields where you want to depend on a sub-property)
+ * - `GROUP_DEPENDENCY_TOKEN` ('$group') → the field's nearest parent
+ *   container path; throws if the field has no parent group/array.
+ * - `'$group.sibling'` → the parent path joined with `.sibling`, useful to
+ *   target a specific sibling without naming the parent group key.
+ *
+ * Non-token strings are passed through unchanged.
+ *
+ * @internal
+ */
+function resolveTokenDependencies(deps, effectiveFieldKey, context) {
+    return deps.map((dep) => {
+        if (dep === SELF_DEPENDENCY_TOKEN) {
+            return effectiveFieldKey;
+        }
+        if (dep.startsWith(`${SELF_DEPENDENCY_TOKEN}.`)) {
+            return effectiveFieldKey + dep.slice(SELF_DEPENDENCY_TOKEN.length);
+        }
+        if (dep === GROUP_DEPENDENCY_TOKEN || dep.startsWith(`${GROUP_DEPENDENCY_TOKEN}.`)) {
+            const groupPath = buildNearestGroupPath(context);
+            if (!groupPath) {
+                throw new DynamicFormError(`Derivation for '${effectiveFieldKey}' uses '${dep}' but the field has no parent group or array. ` +
+                    `'${GROUP_DEPENDENCY_TOKEN}' is only valid for fields nested inside a group or array container.`);
             }
+            if (dep === GROUP_DEPENDENCY_TOKEN)
+                return groupPath;
+            return groupPath + dep.slice(GROUP_DEPENDENCY_TOKEN.length);
         }
-    }
+        return dep;
+    });
 }
 /**
  * Collects derivation entries from a single field.
@@ -11561,8 +11773,7 @@ function collectFromField$1(field, entries, context) {
  * @internal
  */
 function createShorthandEntry(fieldKey, expression, context) {
-    // Build the effective field key, including array path if in array context
-    const effectiveFieldKey = context.arrayPath ? `${context.arrayPath}.$.${fieldKey}` : fieldKey;
+    const effectiveFieldKey = buildEffectiveFieldKey(fieldKey, context);
     return {
         fieldKey: effectiveFieldKey,
         dependsOn: extractStringDependencies(expression),
@@ -11588,11 +11799,16 @@ function createShorthandEntry(fieldKey, expression, context) {
  * @internal
  */
 function createLogicEntry(fieldKey, config, context) {
-    // Build the effective field key, including array path if in array context
-    const effectiveFieldKey = context.arrayPath ? `${context.arrayPath}.$.${fieldKey}` : fieldKey;
+    const effectiveFieldKey = buildEffectiveFieldKey(fieldKey, context);
     // Runtime guards for HTTP and async derivations.
     // Mutual exclusivity and required fields are now enforced by TypeScript (via `source` discriminant).
     // The wildcard and empty-array checks below are not expressible in the type system.
+    //
+    // Note: `$group` / `$group.X` tokens are intentionally allowed for HTTP and async sources even
+    // though they resolve to the parent path and therefore fire on any sibling change inside that
+    // group/array. Unlike `*`, the token is structurally scoped (collection throws if the field has
+    // no parent container) and an explicit opt-in. Consumers that want to bound request frequency
+    // can use `trigger: 'debounced'` here, or rely on debouncing inside their async function.
     if (config.source === 'http') {
         if (config.dependsOn.length === 0) {
             throw new DynamicFormError(`HTTP derivation for '${effectiveFieldKey}' requires explicit 'dependsOn'. ` +
@@ -11613,7 +11829,7 @@ function createLogicEntry(fieldKey, config, context) {
                 `Wildcards would trigger async functions on every form change. Specify explicit field dependencies instead.`);
         }
     }
-    const dependsOn = extractDependencies$1(config);
+    const dependsOn = resolveTokenDependencies(extractDependenciesFromConfig(config), effectiveFieldKey, context);
     const condition = config.condition ?? true;
     const trigger = config.trigger ?? 'onChange';
     // Extract debounceMs from debounced configs
@@ -11638,43 +11854,6 @@ function createLogicEntry(fieldKey, config, context) {
         reEngageOnDependencyChange: config.reEngageOnDependencyChange,
     };
 }
-/**
- * Extracts all field dependencies from a derivation config.
- *
- * Combines dependencies from:
- * - Explicit `dependsOn` array (if provided, takes precedence)
- * - Condition expression
- * - Value expression
- * - Function name (defaults to '*' if no explicit dependsOn)
- *
- * @internal
- */
-function extractDependencies$1(config) {
-    const deps = new Set();
-    // If explicit dependsOn is provided, use it as the primary source
-    // This allows users to override automatic detection and control
-    // when derivations are triggered
-    if (config.dependsOn && config.dependsOn.length > 0) {
-        config.dependsOn.forEach((dep) => deps.add(dep));
-    }
-    else {
-        // Extract from expression (automatic dependency detection)
-        if (config.expression) {
-            const exprDeps = extractStringDependencies(config.expression);
-            exprDeps.forEach((dep) => deps.add(dep));
-        }
-        // Custom functions assume full form access if no explicit dependsOn
-        if (config.functionName) {
-            deps.add('*');
-        }
-    }
-    // Always extract from condition (these are additional runtime guards)
-    if (config.condition && config.condition !== true) {
-        const conditionDeps = extractExpressionDependencies(config.condition);
-        conditionDeps.forEach((dep) => deps.add(dep));
-    }
-    return Array.from(deps);
-}
 
 /**
  * Detects cycles in the derivation dependency graph.
@@ -12361,6 +12540,58 @@ function createAsyncDerivationStream(entry, formValue$, context) {
     }));
 }
 
+/**
+ * Returns the unique set of debounce periods declared by `entries` whose
+ * `trigger === 'debounced'`. Entries without an explicit `debounceMs` use
+ * {@link DEFAULT_DEBOUNCE_MS}.
+ *
+ * @internal
+ */
+function getDebouncePeriods(entries) {
+    const periods = new Set();
+    for (const entry of entries) {
+        if (entry.trigger === 'debounced') {
+            periods.add(entry.debounceMs ?? DEFAULT_DEBOUNCE_MS);
+        }
+    }
+    return Array.from(periods);
+}
+/**
+ * Filters `entries` down to those whose `trigger === 'debounced'` and whose
+ * effective `debounceMs` (defaulting to {@link DEFAULT_DEBOUNCE_MS}) equals `period`.
+ *
+ * @internal
+ */
+function filterEntriesByDebouncePeriod(entries, period) {
+    return entries.filter((entry) => entry.trigger === 'debounced' && (entry.debounceMs ?? DEFAULT_DEBOUNCE_MS) === period);
+}
+
+/**
+ * Resolves a record of external-data signals to their current values without
+ * establishing reactive dependencies.
+ *
+ * The orchestrators read external data per derivation cycle; using `untracked`
+ * here ensures the orchestrator's own computed/effect graph isn't tied to the
+ * external-data signal identities.
+ *
+ * @internal
+ */
+function resolveExternalData(externalDataSignal) {
+    const externalDataRecord = untracked(() => externalDataSignal?.());
+    if (!externalDataRecord)
+        return undefined;
+    const resolved = {};
+    for (const [key, value] of Object.entries(externalDataRecord)) {
+        if (isSignal(value)) {
+            resolved[key] = untracked(() => value());
+        }
+        else {
+            resolved[key] = value;
+        }
+    }
+    return resolved;
+}
+
 /**
  * Orchestrates derivation processing for a dynamic form.
  *
@@ -12477,7 +12708,7 @@ class DerivationOrchestrator {
             if (!collection || !formAccessor)
                 return of(null);
             // Get unique debounce periods from entries with trigger 'debounced'
-            const debouncePeriods = this.getDebouncePeriods(collection.entries);
+            const debouncePeriods = getDebouncePeriods(collection.entries);
             if (debouncePeriods.length === 0)
                 return of(null);
             // merge: Process multiple debounce periods concurrently.
@@ -12510,7 +12741,7 @@ class DerivationOrchestrator {
             rootForm: formAccessor,
             derivationFunctions: this.functionRegistry.getDerivationFunctions(),
             customFunctions: this.functionRegistry.getCustomFunctions(),
-            externalData: this.resolveExternalData(),
+            externalData: resolveExternalData(this.config.externalData),
             logger: this.logger,
             warningTracker: this.warningTracker,
             derivationLogger: untracked(() => this.config.derivationLogger()),
@@ -12538,7 +12769,7 @@ class DerivationOrchestrator {
             rootForm: formAccessor,
             derivationFunctions: this.functionRegistry.getDerivationFunctions(),
             customFunctions: this.functionRegistry.getCustomFunctions(),
-            externalData: this.resolveExternalData(),
+            externalData: resolveExternalData(this.config.externalData),
             logger: this.logger,
             warningTracker: this.warningTracker,
             derivationLogger: untracked(() => this.config.derivationLogger()),
@@ -12588,7 +12819,7 @@ class DerivationOrchestrator {
                     logger: this.logger,
                     derivationLogger: this.config.derivationLogger,
                     customFunctions: () => this.functionRegistry.getCustomFunctions(),
-                    externalData: () => this.resolveExternalData(),
+                    externalData: () => resolveExternalData(this.config.externalData),
                     warningTracker: this.warningTracker,
                     guard$: this.streamGuard.guard$,
                 };
@@ -12662,7 +12893,7 @@ class DerivationOrchestrator {
                     derivationLogger: this.config.derivationLogger,
                     customFunctions: () => this.functionRegistry.getCustomFunctions(),
                     asyncDerivationFunctions: () => this.functionRegistry.getAsyncDerivationFunctions(),
-                    externalData: () => this.resolveExternalData(),
+                    externalData: () => resolveExternalData(this.config.externalData),
                     warningTracker: this.warningTracker,
                 };
                 const stream = createAsyncDerivationStream(entry, formValue$, context).pipe(takeUntilDestroyed(this.destroyRef));
@@ -12697,42 +12928,6 @@ class DerivationOrchestrator {
             return `${entry.fieldKey}:${JSON.stringify(config, Object.keys(config).sort())}`;
         }));
     }
-    /**
-     * Gets all unique debounce periods from entries with trigger 'debounced'.
-     */
-    getDebouncePeriods(entries) {
-        const periods = new Set();
-        for (const entry of entries) {
-            if (entry.trigger === 'debounced') {
-                periods.add(entry.debounceMs ?? DEFAULT_DEBOUNCE_MS);
-            }
-        }
-        return Array.from(periods);
-    }
-    /**
-     * Resolves external data signals to their current values without creating dependencies.
-     *
-     * Uses `untracked()` to read signals without establishing reactive dependencies,
-     * which is important for derivations that shouldn't re-trigger on every external data change.
-     *
-     * @returns Record of resolved external data values, or undefined if no external data.
-     */
-    resolveExternalData() {
-        const externalDataRecord = untracked(() => this.config.externalData?.());
-        if (!externalDataRecord) {
-            return undefined;
-        }
-        const resolved = {};
-        for (const [key, signal] of Object.entries(externalDataRecord)) {
-            if (isSignal(signal)) {
-                resolved[key] = untracked(() => signal());
-            }
-            else {
-                resolved[key] = signal;
-            }
-        }
-        return resolved;
-    }
 }
 /**
  * Creates a DerivationOrchestrator for a dynamic form.
@@ -13219,24 +13414,11 @@ function evaluatePropertyCondition(condition, context) {
  * @internal
  */
 function computePropertyValue(entry, evalContext, applicatorContext) {
-    // Static value
-    if (entry.value !== undefined) {
-        return entry.value;
-    }
-    // Expression
-    if (entry.expression) {
-        return ExpressionParser.evaluate(entry.expression, evalContext);
-    }
-    // Custom function
-    if (entry.functionName) {
-        const fn = applicatorContext.derivationFunctions?.[entry.functionName];
-        if (!fn) {
-            throw new DynamicFormError(`Property derivation function '${entry.functionName}' not found in customFnConfig.derivations`);
-        }
-        return fn(evalContext);
-    }
-    throw new DynamicFormError(`Property derivation for ${entry.fieldKey}.${entry.targetProperty} has no value source. ` +
-        `Specify 'value', 'expression', or 'functionName'.`);
+    return computeValueFromEntry(entry, evalContext, {
+        derivationFunctions: applicatorContext.derivationFunctions,
+        subject: `${entry.fieldKey}.${entry.targetProperty}`,
+        functionKind: 'Property derivation function',
+    });
 }
 
 /**
@@ -13256,40 +13438,12 @@ function computePropertyValue(entry, evalContext, applicatorContext) {
 function collectPropertyDerivations(fields, logger, tracker) {
     const entries = [];
     const context = { logger, tracker };
-    traverseFields(fields, entries, context);
+    traverseFieldsWithContext(fields, context, (field, ctx) => collectFromField(field, entries, ctx), {
+        onArrayChild: (_, field) => ({ arrayPath: field.key }),
+        // Group and layout containers do not affect property-derivation paths.
+    });
     return { entries };
 }
-/**
- * Recursively traverses field definitions to collect property derivations.
- *
- * @internal
- */
-function traverseFields(fields, entries, context) {
-    for (const field of fields) {
-        collectFromField(field, entries, context);
-        // Recursively process container fields (page, row, group, array)
-        if (hasChildFields(field)) {
-            const childContext = { ...context };
-            if (field.type === 'array') {
-                childContext.arrayPath = field.key;
-                const arrayItems = normalizeFieldsArray(field.fields);
-                const normalizedChildren = [];
-                for (const item of arrayItems) {
-                    if (Array.isArray(item)) {
-                        normalizedChildren.push(...item);
-                    }
-                    else {
-                        normalizedChildren.push(item);
-                    }
-                }
-                traverseFields(normalizedChildren, entries, childContext);
-            }
-            else {
-                traverseFields(normalizeFieldsArray(field.fields), entries, childContext);
-            }
-        }
-    }
-}
 /**
  * Collects property derivation entries from a single field.
  *
@@ -13319,7 +13473,7 @@ function collectFromField(field, entries, context) {
  */
 function createPropertyDerivationEntryFromDerivation(fieldKey, config, context) {
     const effectiveFieldKey = buildPropertyOverrideKey(context.arrayPath, context.arrayPath ? PLACEHOLDER_INDEX : undefined, fieldKey);
-    const dependsOn = extractDependencies(config);
+    const dependsOn = extractDependenciesFromConfig(config);
     const condition = config.condition ?? true;
     const trigger = config.trigger ?? 'onChange';
     const debounceMs = trigger === 'debounced' ? config.debounceMs : undefined;
@@ -13337,32 +13491,6 @@ function createPropertyDerivationEntryFromDerivation(fieldKey, config, context)
         originalConfig: config,
     };
 }
-/**
- * Extracts all field dependencies from a property derivation config.
- *
- * @internal
- */
-function extractDependencies(config) {
-    const deps = new Set();
-    if (config.dependsOn && config.dependsOn.length > 0) {
-        config.dependsOn.forEach((dep) => deps.add(dep));
-    }
-    else {
-        if (config.expression) {
-            const exprDeps = extractStringDependencies(config.expression);
-            exprDeps.forEach((dep) => deps.add(dep));
-        }
-        if (config.functionName) {
-            deps.add('*');
-        }
-    }
-    // Always extract from condition
-    if (config.condition && config.condition !== true) {
-        const conditionDeps = extractExpressionDependencies(config.condition);
-        conditionDeps.forEach((dep) => deps.add(dep));
-    }
-    return Array.from(deps);
-}
 
 /**
  * Orchestrates property derivation processing for a dynamic form.
@@ -13440,7 +13568,7 @@ class PropertyDerivationOrchestrator {
             const collection = untracked(() => this.propertyDerivationCollection());
             if (!collection)
                 return of(null);
-            const debouncePeriods = this.getDebouncePeriods(collection.entries);
+            const debouncePeriods = getDebouncePeriods(collection.entries);
             if (debouncePeriods.length === 0)
                 return of(null);
             const periodStreams = debouncePeriods.map((debounceMs) => this.createPeriodStream(debounceMs, collection, changedFields));
@@ -13465,7 +13593,7 @@ class PropertyDerivationOrchestrator {
             store: this.config.store,
             derivationFunctions: this.functionRegistry.getDerivationFunctions(),
             customFunctions: this.functionRegistry.getCustomFunctions(),
-            externalData: this.resolveExternalData(),
+            externalData: resolveExternalData(this.config.externalData),
             logger: this.logger,
             warningTracker: this.warningTracker,
         };
@@ -13481,45 +13609,12 @@ class PropertyDerivationOrchestrator {
             store: this.config.store,
             derivationFunctions: this.functionRegistry.getDerivationFunctions(),
             customFunctions: this.functionRegistry.getCustomFunctions(),
-            externalData: this.resolveExternalData(),
+            externalData: resolveExternalData(this.config.externalData),
             logger: this.logger,
             warningTracker: this.warningTracker,
         };
         applyPropertyDerivationsForTrigger(filteredCollection, 'debounced', applicatorContext, changedFields);
     }
-    getDebouncePeriods(entries) {
-        const periods = new Set();
-        for (const entry of entries) {
-            if (entry.trigger === 'debounced') {
-                periods.add(entry.debounceMs ?? DEFAULT_DEBOUNCE_MS);
-            }
-        }
-        return Array.from(periods);
-    }
-    /**
-     * Resolves external data signals to their current values.
-     *
-     * Called on every onChange and debounced application. Each call iterates all
-     * external data entries and resolves signals via untracked(). For forms with
-     * many external data entries, this could be optimized by caching the resolved
-     * record and only invalidating when external data signal values change.
-     * In practice, external data entries are few, so the linear scan is acceptable.
-     */
-    resolveExternalData() {
-        const externalDataRecord = untracked(() => this.config.externalData?.());
-        if (!externalDataRecord)
-            return undefined;
-        const resolved = {};
-        for (const [key, signalValue] of Object.entries(externalDataRecord)) {
-            if (isSignal(signalValue)) {
-                resolved[key] = untracked(() => signalValue());
-            }
-            else {
-                resolved[key] = signalValue;
-            }
-        }
-        return resolved;
-    }
 }
 /**
  * Creates a PropertyDerivationOrchestrator for a dynamic form.
@@ -14491,7 +14586,10 @@ function rowFieldMapper(fieldDef) {
         // Rebuilt each emission so logic-driven updates to fieldDef (e.g. `disabled`)
         // flow through. Shallow spread is safe while RowField has no nested
         // mutable props; add a deep-clone if that stops being true.
-        const containerField = { ...fieldDef, wrappers: ROW_WRAPPERS };
+        // `type` is rewritten to 'container' because `row` is a synthetic field
+        // type — the runtime renders it as a ContainerField with a synthesized
+        // `{ type: 'row' }` wrapper.
+        const containerField = { ...fieldDef, type: 'container', wrappers: ROW_WRAPPERS };
         const inputs = {
             key: fieldDef.key,
             field: containerField,
@@ -14637,31 +14735,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-DQ_OQLtx.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-ByKgY4-b.mjs'),
         mapper: rowFieldMapper,
         valueHandling: 'flatten',
     },
     {
         name: 'group',
-        loadComponent: () => import('./ng-forge-dynamic-forms-group-field.component-BdLdSEHj.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-group-field.component-clrQsUyY.mjs'),
         mapper: groupFieldMapper,
         valueHandling: 'include',
     },
     {
         name: 'array',
-        loadComponent: () => import('./ng-forge-dynamic-forms-array-field.component-CJ_OclbR.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-array-field.component-DWhbvZUO.mjs'),
         mapper: arrayFieldMapper,
         valueHandling: 'include',
     },
     {
         name: 'page',
-        loadComponent: () => import('./ng-forge-dynamic-forms-page-field.component-C5rUo80O.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-page-field.component-XtyjFlJi.mjs'),
         mapper: pageFieldMapper,
         valueHandling: 'flatten',
     },
     {
         name: 'text',
-        loadComponent: () => import('./ng-forge-dynamic-forms-text-field.component-lvuyTM1r.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-text-field.component-CJsRWH2r.mjs'),
         mapper: textFieldMapper,
         valueHandling: 'exclude',
         ...DISPLAY_FIELD_TYPES_BASE,
@@ -14673,7 +14771,7 @@ const BUILT_IN_FIELDS = [
     },
     {
         name: 'container',
-        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-DQ_OQLtx.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-container-field.component-ByKgY4-b.mjs'),
         mapper: containerFieldMapper,
         valueHandling: 'flatten',
     },
@@ -14681,7 +14779,7 @@ const BUILT_IN_FIELDS = [
 const BUILT_IN_WRAPPERS = [
     {
         wrapperName: 'css',
-        loadComponent: () => import('./ng-forge-dynamic-forms-css-wrapper.component-2fdmbtL7.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-css-wrapper.component-ClFdxZV4.mjs'),
     },
     {
         wrapperName: 'row',
@@ -15714,4 +15812,4 @@ function extractErrorParams(error) {
  */
 
 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-BdMxsqmk.mjs.map
+//# sourceMappingURL=ng-forge-dynamic-forms-ng-forge-dynamic-forms-Bw9Bt0Ev.mjs.map