@ng-forge/dynamic-forms 0.5.0 → 0.5.1

package/fesm2022/{ng-forge-dynamic-forms-ng-forge-dynamic-forms-WGww2nXx.mjs → ng-forge-dynamic-forms-ng-forge-dynamic-forms-BWFdMPyw.mjs}

@@ -300,7 +300,7 @@ function resolveField(fieldDef, context) {
             inputs,
         };
     }), catchError((error) => {
-        // Only handle errors if component hasn't been destroyed
+        // Only call onError if component is not destroyed to avoid accessing cleaned-up state
         if (!context.destroyRef.destroyed) {
             context.onError?.(fieldDef, error);
         }
@@ -348,19 +348,22 @@ function createFieldResolutionPipe(getContext) {
  * Wraps a submission action to handle both Promise and Observable returns.
  * Converts Observables to Promises for compatibility with Angular Signal Forms' submit().
  *
+ * The return type uses `void` to match Angular Signal Forms' expected action signature.
+ * The actual result from the action is preserved but typed as void since Angular's
+ * submit() function handles the result internally.
+ *
  * @param action - The submission action function
  * @returns A wrapped function that always returns a Promise
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Form tree type is dynamic, action signatures vary
 function wrapSubmissionAction(action) {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    return (formTree) => {
+    return async (formTree) => {
         const result = action(formTree);
         // If the action returns an Observable, convert it to a Promise
         if (isObservable(result)) {
-            return firstValueFrom(result);
+            await firstValueFrom(result);
+            return;
         }
-        return result;
+        await Promise.resolve(result);
     };
 }
 /**
@@ -398,6 +401,8 @@ function createSubmissionHandler(options) {
         if (!submissionConfig?.action) {
             return EMPTY;
         }
+        // Type assertion needed: submission.action accepts the form tree but its signature
+        // is defined broadly in FormConfig. The actual runtime type is FieldTree<TModel>.
         const wrappedAction = wrapSubmissionAction(submissionConfig.action);
         // Use Angular Signal Forms' native submit() function
         // This automatically:
@@ -837,6 +842,36 @@ const DEFAULT_VALIDATION_MESSAGES = new InjectionToken('DEFAULT_VALIDATION_MESSA
  * ```
  */
 const FORM_OPTIONS = new InjectionToken('FORM_OPTIONS');
+/**
+ * Injection token for external data signals.
+ *
+ * External data provides a way to inject application state into form expressions.
+ * Each property in the record is a Signal that gets unwrapped and made available
+ * in the `EvaluationContext` under `externalData`.
+ *
+ * Like DEFAULT_PROPS, this token is provided ONCE at the DynamicForm level
+ * and inherited by all children via Angular's hierarchical injector.
+ *
+ * The token provides a Signal containing the external data record, which itself
+ * contains Signals. This allows the form to react to changes in which external
+ * data is available (outer Signal) and to changes in the external data values
+ * (inner Signals).
+ *
+ * @example
+ * ```typescript
+ * // In FieldContextRegistryService
+ * const externalDataSignal = inject(EXTERNAL_DATA, { optional: true });
+ *
+ * // When creating evaluation context:
+ * const externalDataRecord = externalDataSignal?.();
+ * const resolvedExternalData = externalDataRecord
+ *   ? Object.fromEntries(
+ *       Object.entries(externalDataRecord).map(([k, v]) => [k, v()])
+ *     )
+ *   : {};
+ * ```
+ */
+const EXTERNAL_DATA = new InjectionToken('EXTERNAL_DATA');
 
 /**
  * Base error class for all Dynamic Forms errors.
@@ -1179,7 +1214,7 @@ class RootFormRegistryService {
                 }
             }
             catch {
-                // Ignore errors when reading form value
+                // Ignore errors when reading form value - can happen during initialization
             }
         }
         return {};
@@ -1243,6 +1278,7 @@ function isChildFieldContext(context) {
 class FieldContextRegistryService {
     rootFormRegistry = inject(RootFormRegistryService);
     logger = inject(DynamicFormLogger);
+    externalDataSignal = inject(EXTERNAL_DATA, { optional: true });
     /**
      * Creates an evaluation context for a field by combining:
      * - The field's current value
@@ -1277,6 +1313,7 @@ class FieldContextRegistryService {
             formValue,
             fieldPath,
             customFunctions: customFunctions || {},
+            externalData: this.resolveExternalData(false),
             logger: this.logger,
         };
     }
@@ -1295,6 +1332,24 @@ class FieldContextRegistryService {
         // For root fields or when key is not available
         return '';
     }
+    /**
+     * Resolves external data signals to their current values.
+     *
+     * @param reactive - If true, reads signals reactively (creates dependencies).
+     *                   If false, reads signals with untracked() (no dependencies).
+     * @returns Record of resolved external data values, or undefined if no external data.
+     */
+    resolveExternalData(reactive) {
+        const externalDataRecord = reactive ? this.externalDataSignal?.() : untracked(() => this.externalDataSignal?.());
+        if (!externalDataRecord) {
+            return undefined;
+        }
+        const resolved = {};
+        for (const [key, signal] of Object.entries(externalDataRecord)) {
+            resolved[key] = reactive ? signal() : untracked(() => signal());
+        }
+        return resolved;
+    }
     /**
      * Creates a REACTIVE evaluation context for logic functions.
      *
@@ -1323,6 +1378,7 @@ class FieldContextRegistryService {
             formValue,
             fieldPath,
             customFunctions: customFunctions || {},
+            externalData: this.resolveExternalData(true),
             logger: this.logger,
         };
     }
@@ -1347,6 +1403,7 @@ class FieldContextRegistryService {
             formValue,
             fieldPath,
             customFunctions: customFunctions || {},
+            externalData: this.resolveExternalData(true),
             logger: this.logger,
         };
     }
@@ -2714,14 +2771,18 @@ function evaluateCondition(expression, context) {
     }
 }
 function evaluateFieldValueCondition(expression, context) {
-    if (!expression.fieldPath || !expression.operator)
+    if (!expression.fieldPath || !expression.operator) {
+        context.logger.debug('Invalid fieldValue condition config: missing fieldPath or operator', expression);
         return false;
+    }
     const fieldValue = getNestedValue(context.formValue, expression.fieldPath);
     return compareValues(fieldValue, expression.value, expression.operator);
 }
 function evaluateFormValueCondition(expression, context) {
-    if (!expression.operator)
+    if (!expression.operator) {
+        context.logger.debug('Invalid formValue condition config: missing operator', expression);
         return false;
+    }
     return compareValues(context.formValue, expression.value, expression.operator);
 }
 function evaluateJavaScriptExpression(expression, context) {
@@ -3463,9 +3524,7 @@ function createFunctionValidator(config) {
     const registry = inject(FunctionRegistryService);
     const validatorFn = registry.getValidator(functionName);
     if (!validatorFn) {
-        logger.warn(`Custom validator "${functionName}" not found in registry. ` +
-            `Ensure it's registered using customFnConfig.validators or check the function name for typos.`);
-        return () => null;
+        throw new DynamicFormError(`Custom validator "${functionName}" not found. Register it with customFnConfig.validators.`);
     }
     return (ctx) => validatorFn(ctx, config.params);
 }
@@ -3517,13 +3576,10 @@ function createExpressionValidator(config) {
  * - onError: Optional handler for resource errors
  */
 function applyAsyncValidator(config, fieldPath) {
-    const logger = inject(DynamicFormLogger);
     const registry = inject(FunctionRegistryService);
     const validatorConfig = registry.getAsyncValidator(config.functionName);
     if (!validatorConfig) {
-        logger.warn(`Async validator "${config.functionName}" not found in registry. ` +
-            `Ensure it's registered using customFnConfig.asyncValidators or check the function name for typos.`);
-        return;
+        throw new DynamicFormError(`Async validator "${config.functionName}" not found. Register it with customFnConfig.asyncValidators.`);
     }
     const whenLogic = createConditionalLogic(config.when);
     const asyncOptions = {
@@ -3547,13 +3603,10 @@ function applyAsyncValidator(config, fieldPath) {
  * - onError: Optional handler for HTTP errors
  */
 function applyHttpValidator(config, fieldPath) {
-    const logger = inject(DynamicFormLogger);
     const registry = inject(FunctionRegistryService);
     const httpValidatorConfig = registry.getHttpValidator(config.functionName);
     if (!httpValidatorConfig) {
-        logger.warn(`HTTP validator "${config.functionName}" not found in registry. ` +
-            `Ensure it's registered using customFnConfig.httpValidators or check the function name for typos.`);
-        return;
+        throw new DynamicFormError(`HTTP validator "${config.functionName}" not found. Register it with customFnConfig.httpValidators.`);
     }
     const whenLogic = createConditionalLogic(config.when);
     const httpOptions = {
@@ -4275,9 +4328,9 @@ function hasChildFields(field) {
     return 'fields' in field && field.fields != null;
 }
 /** Container field type names */
-const CONTAINER_TYPES = new Set(['page', 'row', 'group', 'array']);
+const CONTAINER_TYPES$1 = new Set(['page', 'row', 'group', 'array']);
 function isContainerField(field) {
-    return CONTAINER_TYPES.has(field.type);
+    return CONTAINER_TYPES$1.has(field.type);
 }
 /**
  * Type guard to check if a field is a leaf field (value or display field)
@@ -4366,8 +4419,27 @@ function createFormLevelSchema(formLevelSchema) {
 }
 
 const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/**
+ * Gets a FieldTree by key, supporting nested paths with dot notation.
+ *
+ * @example
+ * getFieldTreeByKey(ctx, 'address.street') // Returns FieldTree for nested 'street' field
+ */
 function getFieldTreeByKey(ctx, key) {
-    return ctx.fieldTree[key];
+    // Simple case - no nesting
+    if (!key.includes('.')) {
+        return ctx.fieldTree[key];
+    }
+    // Nested path - traverse through the structure
+    const parts = key.split('.');
+    let current = ctx.fieldTree;
+    for (const part of parts) {
+        if (!current || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
 }
 /**
  * Creates an Angular signal forms schema from field definitions
@@ -4539,6 +4611,7 @@ function evaluateCustomCrossFieldValidator(config, evaluationContext, sourceFiel
     // Validation failed - create error targeting the source field
     const targetField = getFieldTreeByKey(ctx, sourceFieldKey);
     if (!targetField) {
+        evaluationContext.logger.warn(`Cross-field validator references non-existent field "${sourceFieldKey}"`);
         return null;
     }
     const errorObj = {
@@ -4551,8 +4624,8 @@ function evaluateCustomCrossFieldValidator(config, evaluationContext, sourceFiel
             try {
                 errorObj[key] = ExpressionParser.evaluate(expression, evaluationContext);
             }
-            catch {
-                // Ignore evaluation errors for params
+            catch (error) {
+                evaluationContext.logger.warn(`Failed to evaluate error param expression "${key}": ${expression}`, error);
             }
         }
     }
@@ -4586,6 +4659,7 @@ function evaluateBuiltInCrossFieldValidator(config, evaluationContext, sourceFie
     // Validation failed - create error targeting the source field
     const targetField = getFieldTreeByKey(ctx, sourceFieldKey);
     if (!targetField) {
+        logger.warn(`Cross-field validator references non-existent field "${sourceFieldKey}"`);
         return null;
     }
     return {
@@ -4686,6 +4760,54 @@ function fieldsToDefaultValues(fields, registry) {
     return defaultValues;
 }
 
+/**
+ * Injection token for globally enabling form value emission on events.
+ *
+ * When set to `true`, all events dispatched through the EventBus will include
+ * the current form value in the `formValue` property.
+ *
+ * This token is configured via `withEventFormValue()` feature function.
+ * Per-form overrides can be set via `options.emitFormValueOnEvents` in the form config.
+ *
+ * @internal
+ */
+const EMIT_FORM_VALUE_ON_EVENTS = new InjectionToken('EMIT_FORM_VALUE_ON_EVENTS', {
+    providedIn: 'root',
+    factory: () => false,
+});
+
+/**
+ * Safely attempts to inject a dependency using an InjectionToken.
+ * Returns the default value if called outside an injection context.
+ */
+function safeInjectToken(token, defaultValue) {
+    try {
+        return inject(token, { optional: true }) ?? defaultValue;
+    }
+    catch {
+        return defaultValue;
+    }
+}
+/**
+ * Safely attempts to inject a service class.
+ * Returns the default value if called outside an injection context.
+ */
+function safeInjectClass(token, defaultValue) {
+    try {
+        return inject(token, { optional: true }) ?? defaultValue;
+    }
+    catch {
+        return defaultValue;
+    }
+}
+/**
+ * Creates a copy of an event with an additional formValue property.
+ * Preserves the event's prototype chain so instanceof checks still work.
+ */
+function attachFormValue(event, formValue) {
+    const prototype = Object.getPrototypeOf(event);
+    return Object.assign(Object.create(prototype), event, { formValue });
+}
 /**
  * Event bus service for form-wide event communication.
  *
@@ -4720,6 +4842,9 @@ function fieldsToDefaultValues(fields, registry) {
  */
 class EventBus {
     pipeline$ = new Subject();
+    globalEmitFormValue = safeInjectToken(EMIT_FORM_VALUE_ON_EVENTS, false);
+    rootFormRegistry = safeInjectClass(RootFormRegistryService, null);
+    formOptions = safeInjectToken(FORM_OPTIONS, null);
     events$ = this.pipeline$.asObservable();
     /**
      * Dispatches an event to all subscribers.
@@ -4727,6 +4852,10 @@ class EventBus {
      * Creates an instance of the provided event constructor and broadcasts it
      * through the event pipeline to all active subscribers.
      *
+     * If `withEventFormValue()` is enabled globally or `options.emitFormValueOnEvents`
+     * is set to `true` in the form config, the current form value will be attached
+     * to the event's `formValue` property.
+     *
      * @param eventConstructor - Constructor function for the event to dispatch
      *
      * @example
@@ -4740,7 +4869,28 @@ class EventBus {
      */
     // TypeScript limitation: Must use ConstructorParameters which relies on `any` in FormEventConstructor
     dispatch(eventConstructor, ...args) {
-        this.pipeline$.next(new eventConstructor(...args));
+        const event = new eventConstructor(...args);
+        if (this.shouldEmitFormValue()) {
+            const formValue = this.rootFormRegistry?.getFormValue();
+            // Only attach if form value exists and has at least one field.
+            // Empty objects {} are not attached - use hasFormValue() to check.
+            if (formValue && Object.keys(formValue).length > 0) {
+                this.pipeline$.next(attachFormValue(event, formValue));
+                return;
+            }
+        }
+        this.pipeline$.next(event);
+    }
+    /**
+     * Determines whether form value should be attached to events.
+     *
+     * Precedence rules:
+     * 1. Per-form setting (if defined) takes precedence
+     * 2. Falls back to global setting
+     */
+    shouldEmitFormValue() {
+        const formLevelSetting = this.formOptions?.()?.emitFormValueOnEvents;
+        return formLevelSetting ?? this.globalEmitFormValue;
     }
     /**
      * Subscribes to form events with type-safe filtering.
@@ -5313,7 +5463,14 @@ function convertBuiltInToCustomValidator(config) {
             validationExpression = `fieldValue == null || (typeof fieldValue !== 'string' && !Array.isArray(fieldValue)) || fieldValue.length <= (${expression})`;
             break;
         case 'pattern':
-            validationExpression = `fieldValue == null || new RegExp(${expression}).test(fieldValue)`;
+            // Validate regex pattern before injection to prevent runtime errors
+            try {
+                new RegExp(expression);
+            }
+            catch {
+                throw new Error(`Invalid regex pattern in cross-field validator: ${expression}`);
+            }
+            validationExpression = `fieldValue == null || new RegExp(${JSON.stringify(expression)}).test(fieldValue)`;
             break;
         default:
             throw new Error(`Cannot convert ${config.type} validator to custom validator`);
@@ -5454,61 +5611,6 @@ function isValidFormConfiguration(fields) {
     return FormModeValidator.validateFormConfiguration(fields).isValid;
 }
 
-/**
- * Centralized constants for the derivation system.
- *
- * These constants configure the behavior of derivation processing,
- * caching, and path handling. Centralizing them enables:
- * - Easy configuration changes
- * - Consistent values across all derivation modules
- * - Clear documentation of magic numbers
- *
- * @module
- */
-/**
- * Maximum number of derivation iterations before stopping to prevent infinite loops.
- *
- * The value of 10 is chosen based on:
- * - Most derivation chains are 2-3 levels deep (A→B→C)
- * - Complex forms with conditional cascades rarely exceed 5-6 levels
- * - 10 provides headroom for bidirectional sync patterns (A↔B) which may need
- *   2 iterations per pair to stabilize
- * - Higher values delay detection of actual infinite loops
- * - Lower values risk false positives on legitimate deep chains
- *
- * If you hit this limit legitimately, consider:
- * 1. Restructuring derivations to reduce chain depth
- * 2. Using explicit `dependsOn` to control evaluation order
- * 3. Breaking complex derivations into computed signals outside the form
- */
-const MAX_DERIVATION_ITERATIONS = 10;
-/**
- * Placeholder string for array index in derivation paths.
- *
- * Used in paths like `items.$.quantity` to represent "each item in the array".
- * The `$` is resolved to actual indices at runtime during array derivation processing.
- */
-const ARRAY_PLACEHOLDER = '.$.';
-/**
- * Maximum size of the expression AST cache.
- *
- * Expressions are parsed into Abstract Syntax Trees (AST) once and cached
- * to avoid re-parsing on each evaluation. The cache uses LRU eviction.
- *
- * 1000 entries handles:
- * - Large forms with many derivation expressions
- * - Multiple form instances with different expressions
- * - Memory efficiency (AST nodes are relatively small)
- */
-const MAX_AST_CACHE_SIZE = 1000;
-/**
- * Delimiter used to create unique derivation keys from source and target field keys.
- *
- * Uses null character (\x00) which is extremely unlikely to appear in field names,
- * avoiding collision issues that could occur with common delimiters like ':'.
- */
-const DERIVATION_KEY_DELIMITER = '\x00';
-
 /**
  * Creates an empty derivation collection.
  *
@@ -5535,32 +5637,31 @@ function createDerivationChainContext() {
 /**
  * Creates a unique key for a derivation entry.
  *
- * Uses a null character delimiter to avoid collision with field names
- * that might contain common delimiters like ':'.
+ * Since derivations are self-targeting, the key is simply the field key.
+ * This function exists for semantic clarity and to provide a single point
+ * of change if the key format needs to be extended in the future.
  *
- * @param sourceKey - The source field key
- * @param targetKey - The target field key
+ * Note: For array derivations, callers must resolve placeholders
+ * (e.g., 'items.$.lineTotal' -> 'items.0.lineTotal') before calling this.
+ *
+ * @param fieldKey - The field key (with array index already resolved)
  * @returns Unique key for the derivation
  *
  * @internal
  */
-function createDerivationKey(sourceKey, targetKey) {
-    return `${sourceKey}${DERIVATION_KEY_DELIMITER}${targetKey}`;
+function createDerivationKey(fieldKey) {
+    return fieldKey;
 }
 /**
- * Parses a derivation key back into source and target field keys.
+ * Parses a derivation key back into field key.
  *
  * @param key - The derivation key to parse
- * @returns Object containing source and target field keys
+ * @returns Object containing the field key
  *
  * @internal
  */
 function parseDerivationKey(key) {
-    const delimiterIndex = key.indexOf(DERIVATION_KEY_DELIMITER);
-    return {
-        sourceKey: key.substring(0, delimiterIndex),
-        targetKey: key.substring(delimiterIndex + DERIVATION_KEY_DELIMITER.length),
-    };
+    return { fieldKey: key };
 }
 
 /**
@@ -5691,9 +5792,12 @@ function extractArrayPath(path) {
     return parseArrayPath(path).arrayPath;
 }
 /**
- * Splits a dot-separated path into segments.
+ * Splits a path into segments, supporting both dot notation and bracket notation.
  *
- * Handles both dot notation and bracket notation for array indices.
+ * Handles:
+ * - Dot notation: `parent.child.grandchild`
+ * - Bracket notation: `items[0].quantity`
+ * - Mixed notation: `items[0].address.city`
  *
  * @param path - The path to split
  * @returns Array of path segments
@@ -5705,6 +5809,12 @@ function extractArrayPath(path) {
  *
  * splitPath('items.0.quantity')
  * // ['items', '0', 'quantity']
+ *
+ * splitPath('items[0].quantity')
+ * // ['items', '0', 'quantity']
+ *
+ * splitPath('a[0][1].b')
+ * // ['a', '0', '1', 'b']
  * ```
  *
  * @public
@@ -5712,7 +5822,12 @@ function extractArrayPath(path) {
 function splitPath(path) {
     if (!path)
         return [];
-    return path.split('.');
+    // Convert bracket notation [n] to .n, then split by dots
+    // Filter out empty segments from leading/trailing/consecutive dots
+    return path
+        .replace(/\[(\d+)\]/g, '.$1')
+        .split('.')
+        .filter(Boolean);
 }
 /**
  * Joins path segments into a dot-separated path.
@@ -5912,8 +6027,7 @@ class DerivationLookup {
     // Track the entries array reference to auto-invalidate on change
     _cachedEntriesRef;
     // Cached lookup maps (built lazily on first access)
-    _byTarget;
-    _bySource;
+    _byField;
     _byDependency;
     _byArrayPath;
     _wildcardEntries;
@@ -5933,18 +6047,12 @@ class DerivationLookup {
         return currentEntries;
     }
     /**
-     * Map of target field key to entries that modify it.
+     * Map of field key to entries that target it.
+     * Since derivations are self-targeting, this maps field keys to their derivations.
      * Used for quick lookup when processing derivations.
      */
-    get byTarget() {
-        return (this._byTarget ??= this.buildByTargetMap());
-    }
-    /**
-     * Map of source field key to entries defined on it.
-     * Used for finding derivations when a field's value changes.
-     */
-    get bySource() {
-        return (this._bySource ??= this.buildBySourceMap());
+    get byField() {
+        return (this._byField ??= this.buildByFieldMap());
     }
     /**
      * Map of dependency field key to entries that depend on it.
@@ -6039,8 +6147,7 @@ class DerivationLookup {
      * Invalidates cached maps. Call this when entries change.
      */
     invalidateCache() {
-        this._byTarget = undefined;
-        this._bySource = undefined;
+        this._byField = undefined;
         this._byDependency = undefined;
         this._byArrayPath = undefined;
         this._wildcardEntries = undefined;
@@ -6050,21 +6157,12 @@ class DerivationLookup {
     // ─────────────────────────────────────────────────────────────────
     // Private builders
     // ─────────────────────────────────────────────────────────────────
-    buildByTargetMap() {
-        const map = new Map();
-        for (const entry of this.entries) {
-            const targetEntries = map.get(entry.targetFieldKey) ?? [];
-            targetEntries.push(entry);
-            map.set(entry.targetFieldKey, targetEntries);
-        }
-        return map;
-    }
-    buildBySourceMap() {
+    buildByFieldMap() {
         const map = new Map();
         for (const entry of this.entries) {
-            const sourceEntries = map.get(entry.sourceFieldKey) ?? [];
-            sourceEntries.push(entry);
-            map.set(entry.sourceFieldKey, sourceEntries);
+            const fieldEntries = map.get(entry.fieldKey) ?? [];
+            fieldEntries.push(entry);
+            map.set(entry.fieldKey, fieldEntries);
         }
         return map;
     }
@@ -6084,8 +6182,8 @@ class DerivationLookup {
     buildByArrayPathMap() {
         const map = new Map();
         for (const entry of this.entries) {
-            if (isArrayPlaceholderPath(entry.targetFieldKey)) {
-                const arrayPath = extractArrayPath(entry.targetFieldKey);
+            if (isArrayPlaceholderPath(entry.fieldKey)) {
+                const arrayPath = extractArrayPath(entry.fieldKey);
                 if (arrayPath) {
                     const arrayEntries = map.get(arrayPath) ?? [];
                     arrayEntries.push(entry);
@@ -6158,22 +6256,22 @@ function topologicalSort(entries) {
         graph.set(entry, new Set());
         inDegree.set(entry, 0);
     }
-    // Pre-build index: target field -> entries that produce it
+    // Pre-build index: field key -> entries that produce/target it
     // This enables O(1) lookup instead of O(n) scanning
-    const producersByTarget = new Map();
+    const derivationsByField = new Map();
     for (const entry of entries) {
-        // Index by exact target field
-        const producers = producersByTarget.get(entry.targetFieldKey) ?? [];
-        producers.push(entry);
-        producersByTarget.set(entry.targetFieldKey, producers);
+        // Index by exact field key
+        const fieldEntries = derivationsByField.get(entry.fieldKey) ?? [];
+        fieldEntries.push(entry);
+        derivationsByField.set(entry.fieldKey, fieldEntries);
         // Also index array field relative paths for array derivations
         // If entry targets 'items.$.lineTotal', index under 'lineTotal' too
-        if (entry.targetFieldKey.includes('.$.')) {
-            const relativePath = entry.targetFieldKey.split('.$.')[1];
+        if (entry.fieldKey.includes('.$.')) {
+            const relativePath = entry.fieldKey.split('.$.')[1];
             if (relativePath) {
-                const relativeProducers = producersByTarget.get(relativePath) ?? [];
-                relativeProducers.push(entry);
-                producersByTarget.set(relativePath, relativeProducers);
+                const relativeEntries = derivationsByField.get(relativePath) ?? [];
+                relativeEntries.push(entry);
+                derivationsByField.set(relativePath, relativeEntries);
             }
         }
     }
@@ -6185,14 +6283,15 @@ function topologicalSort(entries) {
         }
     }
     // Build edges using pre-computed index
-    // For each entry B, find all entries A whose target is in B's dependencies
+    // For each entry B, find all entries A whose field is in B's dependencies
+    // If B depends on field X, and A produces X, then A must run before B
     for (const entryB of entries) {
         for (const dep of entryB.dependsOn) {
             // Skip wildcards here - handled separately below
             if (dep === '*')
                 continue;
-            // O(1) lookup: find all producers of this dependency
-            const producers = producersByTarget.get(dep);
+            // O(1) lookup: find all derivations that produce this dependency
+            const producers = derivationsByField.get(dep);
             if (producers) {
                 for (const entryA of producers) {
                     const entryAEdges = graph.get(entryA);
@@ -6329,7 +6428,7 @@ function collectFromField(field, entries, context) {
     const validationField = field;
     // Collect shorthand derivation property
     if (validationField.derivation) {
-        const entry = createShorthandEntry(fieldKey, validationField.derivation);
+        const entry = createShorthandEntry(fieldKey, validationField.derivation, context);
         entries.push(entry);
     }
     // Collect logic array derivations
@@ -6346,16 +6445,17 @@ function collectFromField(field, entries, context) {
  * Creates a derivation entry from the shorthand `derivation` property.
  *
  * Shorthand derivations:
- * - Always target the same field they're defined on
+ * - Target the same field they're defined on (self-targeting)
  * - Always apply (condition defaults to true)
  * - Always trigger on change
  *
  * @internal
  */
-function createShorthandEntry(fieldKey, expression) {
+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;
     return {
-        sourceFieldKey: fieldKey,
-        targetFieldKey: fieldKey,
+        fieldKey: effectiveFieldKey,
         dependsOn: extractStringDependencies(expression),
         condition: true,
         expression,
@@ -6366,16 +6466,21 @@ function createShorthandEntry(fieldKey, expression) {
 /**
  * Creates a derivation entry from a full `DerivationLogicConfig`.
  *
+ * All derivations are self-targeting: the derivation is defined on and targets
+ * the same field (fieldKey). For array fields, the context is used to build
+ * the array placeholder path.
+ *
  * Handles:
  * - Condition extraction and dependency analysis
- * - Relative path resolution for array fields
+ * - Array field context for placeholder paths
  * - Multiple value source types (static, expression, function)
  * - Trigger and debounce configuration
  *
  * @internal
  */
 function createLogicEntry(fieldKey, config, context) {
-    const targetFieldKey = resolveTargetFieldKey(config.targetField, fieldKey, context);
+    // Build the effective field key, including array path if in array context
+    const effectiveFieldKey = context.arrayPath ? `${context.arrayPath}.$.${fieldKey}` : fieldKey;
     const dependsOn = extractDependencies(config);
     const condition = config.condition ?? true;
     const trigger = config.trigger ?? 'onChange';
@@ -6383,8 +6488,7 @@ function createLogicEntry(fieldKey, config, context) {
     // The type system ensures debounceMs is only present when trigger is 'debounced'
     const debounceMs = trigger === 'debounced' ? config.debounceMs : undefined;
     return {
-        sourceFieldKey: fieldKey,
-        targetFieldKey,
+        fieldKey: effectiveFieldKey,
         dependsOn,
         condition,
         value: config.value,
@@ -6397,46 +6501,6 @@ function createLogicEntry(fieldKey, config, context) {
         debugName: config.debugName,
     };
 }
-/**
- * Resolves a target field key, handling relative paths for array fields.
- *
- * Relative paths start with '$.' and reference siblings at the same array index.
- *
- * @param targetField - The target field specification from config
- * @param sourceFieldKey - The source field key
- * @param context - Current collection context with array path info
- * @returns Resolved target field key
- *
- * @example
- * ```typescript
- * // Absolute path - returned as-is
- * resolveTargetFieldKey('phonePrefix', 'country', {})
- * // Returns: 'phonePrefix'
- *
- * // Relative path in array context
- * resolveTargetFieldKey('$.lineTotal', 'items[0].quantity', { arrayPath: 'items' })
- * // Returns: 'items.$.lineTotal'
- * ```
- *
- * @internal
- */
-function resolveTargetFieldKey(targetField, _sourceFieldKey, context) {
-    // Check for relative path indicator
-    if (targetField.startsWith('$.')) {
-        // Extract the relative field name (after '$.')
-        const relativePath = targetField.substring(2);
-        if (context.arrayPath) {
-            // Replace '$' with the array path for pattern matching
-            return `${context.arrayPath}.$.${relativePath}`;
-        }
-        // Not in array context - keep relative path as-is.
-        // This indicates a configuration error (relative path used outside array).
-        // The runtime applicator will handle this gracefully.
-        return targetField;
-    }
-    // Absolute path - return as-is
-    return targetField;
-}
 /**
  * Extracts all field dependencies from a derivation config.
  *
@@ -6516,11 +6580,15 @@ function detectCycles(collection) {
     return result;
 }
 /**
- * Detects bidirectional derivation pairs (A→B and B→A).
+ * Detects bidirectional derivation pairs (A↔B patterns).
  *
  * These patterns are allowed because they stabilize via equality checks.
  * Example: USD/EUR conversion where both fields derive from each other.
  *
+ * A bidirectional pair exists when:
+ * - Field A derives its value from field B (A depends on B)
+ * - Field B derives its value from field A (B depends on A)
+ *
  * ## Floating-Point Precision Note
  *
  * Bidirectional derivations stabilize via equality checks using exact IEEE 754
@@ -6536,36 +6604,35 @@ function detectCycles(collection) {
  *
  * @example
  * ```typescript
- * // Safe - uses rounding to avoid oscillation
- * logic: [
- *   {
- *     type: 'derivation',
- *     targetField: 'eur',
- *     expression: 'Math.round(formValue.usd * 0.92 * 100) / 100'
- *   }
- * ]
+ * // Bidirectional currency conversion
+ * { key: 'amountUSD', derivation: 'formValue.amountEUR * 1.1' }
+ * { key: 'amountEUR', derivation: 'formValue.amountUSD / 1.1' }
  * ```
  *
  * @internal
  */
 function detectBidirectionalPairs(collection) {
     const pairs = new Set();
-    const edgeSet = new Set();
-    // Build set of all source→target edges
+    // Build a map of fieldKey -> dependencies (other fields this derivation reads from)
+    const dependencyMap = new Map();
     for (const entry of collection.entries) {
-        if (entry.sourceFieldKey !== entry.targetFieldKey) {
-            edgeSet.add(`${entry.sourceFieldKey}→${entry.targetFieldKey}`);
+        const deps = dependencyMap.get(entry.fieldKey) ?? new Set();
+        for (const dep of entry.dependsOn) {
+            if (dep !== '*' && dep !== entry.fieldKey) {
+                deps.add(dep);
+            }
         }
+        dependencyMap.set(entry.fieldKey, deps);
     }
-    // Find bidirectional pairs (A→B exists AND B→A exists)
-    for (const entry of collection.entries) {
-        const reverseEdge = `${entry.targetFieldKey}→${entry.sourceFieldKey}`;
-        if (edgeSet.has(reverseEdge)) {
-            // Normalize pair key (alphabetically sorted)
-            const pairKey = entry.sourceFieldKey < entry.targetFieldKey
-                ? `${entry.sourceFieldKey}↔${entry.targetFieldKey}`
-                : `${entry.targetFieldKey}↔${entry.sourceFieldKey}`;
-            pairs.add(pairKey);
+    // Find bidirectional pairs: A depends on B AND B depends on A
+    for (const [fieldA, depsA] of dependencyMap) {
+        for (const fieldB of depsA) {
+            const depsB = dependencyMap.get(fieldB);
+            if (depsB?.has(fieldA)) {
+                // Normalize pair key (alphabetically sorted)
+                const pairKey = fieldA < fieldB ? `${fieldA}↔${fieldB}` : `${fieldB}↔${fieldA}`;
+                pairs.add(pairKey);
+            }
         }
     }
     return pairs;
@@ -6594,8 +6661,9 @@ function isBidirectionalCycle(cyclePath, bidirectionalPairs) {
  * Creates nodes for each field involved in derivations and
  * edges representing the derivation dependencies.
  *
- * Edge direction: sourceField -> targetField
- * (source triggers derivation that modifies target)
+ * Edge direction is based on dependencies:
+ * - If field A's derivation depends on field B, then B -> A (changing B triggers A)
+ * - A cycle exists if: A -> B -> C -> A (circular dependency chain)
  *
  * @internal
  */
@@ -6615,32 +6683,19 @@ function buildDependencyGraph(collection) {
         return node;
     };
     for (const entry of collection.entries) {
-        const sourceNode = ensureNode(entry.sourceFieldKey);
-        const targetNode = ensureNode(entry.targetFieldKey);
-        // For cycle detection, we care about the data flow:
-        // When sourceField changes -> targetField gets updated
-        // So the edge is: sourceField -> targetField
-        //
-        // A cycle exists if: A -> B -> A
-        // (A triggers B, B triggers A)
-        // For self-referential derivations (where source === target), don't add source->target edge.
-        // This includes:
-        // 1. Shorthand derivations (field.derivation = 'expression')
-        // 2. Self-transform derivations (logic: [{ targetField: 'self', ... }])
-        // These are legitimate patterns for computed fields and value transformations,
-        // not actual cycles. The real dependencies come from the expression (tracked in dependsOn).
-        const isSelfReferential = entry.sourceFieldKey === entry.targetFieldKey;
-        if (!isSelfReferential) {
-            // The target depends on the source for its value
-            targetNode.dependsOn.add(entry.sourceFieldKey);
-            sourceNode.dependedOnBy.add(entry.targetFieldKey);
-        }
-        // Also track dependencies from the derivation expression/condition
+        const fieldNode = ensureNode(entry.fieldKey);
+        // Track dependencies from the derivation expression/condition.
+        // For cycle detection, edges go from dependency -> field:
+        // If field A depends on field B, then when B changes, A gets updated.
+        // A cycle exists when there's a circular chain of such dependencies.
         for (const dep of entry.dependsOn) {
-            if (dep !== '*' && dep !== entry.targetFieldKey) {
+            // Skip wildcard dependencies and self-references
+            if (dep !== '*' && dep !== entry.fieldKey) {
                 const depNode = ensureNode(dep);
-                targetNode.dependsOn.add(dep);
-                depNode.dependedOnBy.add(entry.targetFieldKey);
+                // The field depends on 'dep'
+                fieldNode.dependsOn.add(dep);
+                // 'dep' is depended on by the field
+                depNode.dependedOnBy.add(entry.fieldKey);
             }
         }
     }
@@ -6788,6 +6843,61 @@ function validateNoCycles(collection, logger) {
     }
 }
 
+/**
+ * Centralized constants for the derivation system.
+ *
+ * These constants configure the behavior of derivation processing,
+ * caching, and path handling. Centralizing them enables:
+ * - Easy configuration changes
+ * - Consistent values across all derivation modules
+ * - Clear documentation of magic numbers
+ *
+ * @module
+ */
+/**
+ * Maximum number of derivation iterations before stopping to prevent infinite loops.
+ *
+ * The value of 10 is chosen based on:
+ * - Most derivation chains are 2-3 levels deep (A→B→C)
+ * - Complex forms with conditional cascades rarely exceed 5-6 levels
+ * - 10 provides headroom for bidirectional sync patterns (A↔B) which may need
+ *   2 iterations per pair to stabilize
+ * - Higher values delay detection of actual infinite loops
+ * - Lower values risk false positives on legitimate deep chains
+ *
+ * If you hit this limit legitimately, consider:
+ * 1. Restructuring derivations to reduce chain depth
+ * 2. Using explicit `dependsOn` to control evaluation order
+ * 3. Breaking complex derivations into computed signals outside the form
+ */
+const MAX_DERIVATION_ITERATIONS = 10;
+/**
+ * Placeholder string for array index in derivation paths.
+ *
+ * Used in paths like `items.$.quantity` to represent "each item in the array".
+ * The `$` is resolved to actual indices at runtime during array derivation processing.
+ */
+const ARRAY_PLACEHOLDER = '.$.';
+/**
+ * Maximum size of the expression AST cache.
+ *
+ * Expressions are parsed into Abstract Syntax Trees (AST) once and cached
+ * to avoid re-parsing on each evaluation. The cache uses LRU eviction.
+ *
+ * 1000 entries handles:
+ * - Large forms with many derivation expressions
+ * - Multiple form instances with different expressions
+ * - Memory efficiency (AST nodes are relatively small)
+ */
+const MAX_AST_CACHE_SIZE = 1000;
+/**
+ * Delimiter used to create unique derivation keys from source and target field keys.
+ *
+ * Uses null character (\x00) which is extremely unlikely to appear in field names,
+ * avoiding collision issues that could occur with common delimiters like ':'.
+ */
+const DERIVATION_KEY_DELIMITER = '\x00';
+
 /**
  * Applies all pending derivations from a collection.
  *
@@ -6904,9 +7014,9 @@ function getEntriesForChangedFields(entries, changedFields) {
  * ```typescript
  * // Two derivations for conditional value with cleanup:
  * // When country is USA, set phonePrefix to '+1'
- * { condition: { field: 'country', operator: '==', value: 'USA' }, targetField: 'phonePrefix', value: '+1' }
+ * { key: 'phonePrefix', logic: [{ type: 'derivation', condition: { field: 'country', operator: '==', value: 'USA' }, value: '+1' }] }
  * // When country is NOT USA, clear phonePrefix
- * { condition: { field: 'country', operator: '!=', value: 'USA' }, targetField: 'phonePrefix', value: '' }
+ * { key: 'phonePrefix', logic: [{ type: 'derivation', condition: { field: 'country', operator: '!=', value: 'USA' }, value: '' }] }
  * ```
  *
  * @internal
@@ -6914,20 +7024,19 @@ function getEntriesForChangedFields(entries, changedFields) {
 function tryApplyDerivation(entry, context, chainContext) {
     const { derivationLogger } = context;
     // Check if this is an array field derivation (has '$' placeholder)
-    if (isArrayPlaceholderPath(entry.targetFieldKey)) {
+    if (isArrayPlaceholderPath(entry.fieldKey)) {
         return tryApplyArrayDerivation(entry, context, chainContext);
     }
-    const derivationKey = createDerivationKey(entry.sourceFieldKey, entry.targetFieldKey);
+    const derivationKey = createDerivationKey(entry.fieldKey);
     // Check if already applied in this cycle
     if (chainContext.appliedDerivations.has(derivationKey)) {
         derivationLogger.evaluation({
             debugName: entry.debugName,
-            sourceFieldKey: entry.sourceFieldKey,
-            targetFieldKey: entry.targetFieldKey,
+            fieldKey: entry.fieldKey,
             result: 'skipped',
             skipReason: 'already-applied',
         });
-        return { applied: false, targetFieldKey: entry.targetFieldKey };
+        return { applied: false, fieldKey: entry.fieldKey };
     }
     // Create evaluation context
     const formValue = untracked(() => context.formValue());
@@ -6936,12 +7045,11 @@ function tryApplyDerivation(entry, context, chainContext) {
     if (!evaluateDerivationCondition(entry.condition, evalContext)) {
         derivationLogger.evaluation({
             debugName: entry.debugName,
-            sourceFieldKey: entry.sourceFieldKey,
-            targetFieldKey: entry.targetFieldKey,
+            fieldKey: entry.fieldKey,
             result: 'skipped',
             skipReason: 'condition-false',
         });
-        return { applied: false, targetFieldKey: entry.targetFieldKey };
+        return { applied: false, fieldKey: entry.fieldKey };
     }
     // Compute derived value
     let newValue;
@@ -6953,14 +7061,13 @@ function tryApplyDerivation(entry, context, chainContext) {
         context.logger.error(formatDerivationError(entry, 'compute', errorMessage));
         derivationLogger.evaluation({
             debugName: entry.debugName,
-            sourceFieldKey: entry.sourceFieldKey,
-            targetFieldKey: entry.targetFieldKey,
+            fieldKey: entry.fieldKey,
             result: 'error',
             error: errorMessage,
         });
         return {
             applied: false,
-            targetFieldKey: entry.targetFieldKey,
+            fieldKey: entry.fieldKey,
             error: errorMessage,
         };
     }
@@ -6969,46 +7076,43 @@ function tryApplyDerivation(entry, context, chainContext) {
     // equality for numbers. Bidirectional derivations with floating-point math
     // may oscillate due to rounding errors. Use explicit rounding in expressions
     // or integer arithmetic to avoid this issue.
-    const currentValue = getNestedValue(formValue, entry.targetFieldKey);
+    const currentValue = getNestedValue(formValue, entry.fieldKey);
     if (isEqual(currentValue, newValue)) {
         derivationLogger.evaluation({
             debugName: entry.debugName,
-            sourceFieldKey: entry.sourceFieldKey,
-            targetFieldKey: entry.targetFieldKey,
+            fieldKey: entry.fieldKey,
             result: 'skipped',
             skipReason: 'value-unchanged',
         });
-        return { applied: false, targetFieldKey: entry.targetFieldKey };
+        return { applied: false, fieldKey: entry.fieldKey };
     }
     // Apply the value
     try {
-        const wasApplied = applyValueToForm(entry.targetFieldKey, newValue, context.rootForm, context.logger, context.warningTracker);
+        const wasApplied = applyValueToForm(entry.fieldKey, newValue, context.rootForm, context.logger, context.warningTracker);
         if (wasApplied) {
             chainContext.appliedDerivations.add(derivationKey);
             derivationLogger.evaluation({
                 debugName: entry.debugName,
-                sourceFieldKey: entry.sourceFieldKey,
-                targetFieldKey: entry.targetFieldKey,
+                fieldKey: entry.fieldKey,
                 result: 'applied',
                 previousValue: currentValue,
                 newValue,
             });
-            return { applied: true, targetFieldKey: entry.targetFieldKey, newValue };
+            return { applied: true, fieldKey: entry.fieldKey, newValue };
         }
         else {
             // Field not found - this is a warning, not an error
             // The warning was already logged by warnMissingField
             derivationLogger.evaluation({
                 debugName: entry.debugName,
-                sourceFieldKey: entry.sourceFieldKey,
-                targetFieldKey: entry.targetFieldKey,
+                fieldKey: entry.fieldKey,
                 result: 'skipped',
                 skipReason: 'target-not-found',
             });
             return {
                 applied: false,
-                targetFieldKey: entry.targetFieldKey,
-                warning: `Target field '${entry.targetFieldKey}' not found`,
+                fieldKey: entry.fieldKey,
+                warning: `Field '${entry.fieldKey}' not found`,
             };
         }
     }
@@ -7017,14 +7121,13 @@ function tryApplyDerivation(entry, context, chainContext) {
         context.logger.error(formatDerivationError(entry, 'apply', errorMessage));
         derivationLogger.evaluation({
             debugName: entry.debugName,
-            sourceFieldKey: entry.sourceFieldKey,
-            targetFieldKey: entry.targetFieldKey,
+            fieldKey: entry.fieldKey,
             result: 'error',
             error: errorMessage,
         });
         return {
             applied: false,
-            targetFieldKey: entry.targetFieldKey,
+            fieldKey: entry.fieldKey,
             error: errorMessage,
         };
     }
@@ -7039,22 +7142,22 @@ function tryApplyDerivation(entry, context, chainContext) {
  */
 function tryApplyArrayDerivation(entry, context, chainContext) {
     const formValue = untracked(() => context.formValue());
-    // Parse the target path using path utilities
-    const pathInfo = parseArrayPath(entry.targetFieldKey);
+    // Parse the field path using path utilities
+    const pathInfo = parseArrayPath(entry.fieldKey);
     if (!pathInfo.isArrayPath) {
-        return { applied: false, targetFieldKey: entry.targetFieldKey, error: 'Invalid array derivation path' };
+        return { applied: false, fieldKey: entry.fieldKey, error: 'Invalid array derivation path' };
     }
     const { arrayPath } = pathInfo;
     // Get the array from form values
     const arrayValue = getNestedValue(formValue, arrayPath);
     if (!Array.isArray(arrayValue)) {
-        return { applied: false, targetFieldKey: entry.targetFieldKey };
+        return { applied: false, fieldKey: entry.fieldKey };
     }
     let appliedAny = false;
     // Process each array item
     for (let i = 0; i < arrayValue.length; i++) {
-        const resolvedTargetPath = resolveArrayPath(entry.targetFieldKey, i);
-        const derivationKey = createDerivationKey(entry.sourceFieldKey, resolvedTargetPath);
+        const resolvedPath = resolveArrayPath(entry.fieldKey, i);
+        const derivationKey = createDerivationKey(resolvedPath);
         // Skip if already applied in this cycle
         if (chainContext.appliedDerivations.has(derivationKey)) {
             continue;
@@ -7077,13 +7180,13 @@ function tryApplyArrayDerivation(entry, context, chainContext) {
             continue;
         }
         // Check if value actually changed
-        const currentValue = getNestedValue(formValue, resolvedTargetPath);
+        const currentValue = getNestedValue(formValue, resolvedPath);
         if (isEqual(currentValue, newValue)) {
             continue;
         }
         // Apply the value
         try {
-            applyValueToForm(resolvedTargetPath, newValue, context.rootForm, context.logger, context.warningTracker);
+            applyValueToForm(resolvedPath, newValue, context.rootForm, context.logger, context.warningTracker);
             chainContext.appliedDerivations.add(derivationKey);
             appliedAny = true;
         }
@@ -7092,7 +7195,7 @@ function tryApplyArrayDerivation(entry, context, chainContext) {
             context.logger.error(formatDerivationError(entry, 'apply', `[index ${i}] ${errorMessage}`));
         }
     }
-    return { applied: appliedAny, targetFieldKey: entry.targetFieldKey };
+    return { applied: appliedAny, fieldKey: entry.fieldKey };
 }
 /**
  * Creates an evaluation context for derivation processing.
@@ -7100,12 +7203,13 @@ function tryApplyArrayDerivation(entry, context, chainContext) {
  * @internal
  */
 function createEvaluationContext(entry, formValue, context) {
-    const fieldValue = getNestedValue(formValue, entry.sourceFieldKey);
+    const fieldValue = getNestedValue(formValue, entry.fieldKey);
     return {
         fieldValue,
         formValue,
-        fieldPath: entry.sourceFieldKey,
+        fieldPath: entry.fieldKey,
         customFunctions: context.customFunctions,
+        externalData: context.externalData,
         logger: context.logger,
     };
 }
@@ -7126,6 +7230,7 @@ function createArrayItemEvaluationContext(entry, arrayItem, rootFormValue, itemI
         formValue: arrayItem,
         fieldPath: `${arrayPath}.${itemIndex}`,
         customFunctions: context.customFunctions,
+        externalData: context.externalData,
         logger: context.logger,
         // Provide access to root form value for cross-scope references
         rootFormValue,
@@ -7167,7 +7272,7 @@ function computeDerivedValue(entry, evalContext, applicatorContext) {
         return fn(evalContext);
     }
     // No value source specified
-    throw new Error(`Derivation for ${entry.targetFieldKey} has no value source. ` + `Specify 'value', 'expression', or 'functionName'.`);
+    throw new Error(`Derivation for ${entry.fieldKey} has no value source. ` + `Specify 'value', 'expression', or 'functionName'.`);
 }
 /**
  * Applies a value to the form at the specified path.
@@ -7225,7 +7330,7 @@ function formatDerivationError(entry, phase, message) {
             : entry.value !== undefined
                 ? 'static value'
                 : 'unknown source';
-    return `${ERROR_PREFIX} Failed to ${phase} derivation (${entry.sourceFieldKey} → ${entry.targetFieldKey}, ${source}): ${message}`;
+    return `${ERROR_PREFIX} Failed to ${phase} derivation (field: ${entry.fieldKey}, ${source}): ${message}`;
 }
 /**
  * Sets a field value using the Angular Signal Forms pattern.
@@ -7413,12 +7518,11 @@ function logMaxIterationsReached(result, trigger, logger) {
 function logDerivationEvaluation(entry, logger, config) {
     if (!shouldLog(config, 'verbose'))
         return;
-    const name = entry.debugName ? `"${entry.debugName}"` : `${entry.sourceFieldKey} -> ${entry.targetFieldKey}`;
+    const name = entry.debugName ? `"${entry.debugName}"` : entry.fieldKey;
     switch (entry.result) {
         case 'applied':
             logger.debug(`${LOG_PREFIX} -> Applied: ${name}`, {
-                source: entry.sourceFieldKey,
-                target: entry.targetFieldKey,
+                field: entry.fieldKey,
                 previousValue: entry.previousValue,
                 newValue: entry.newValue,
                 ...(entry.durationMs !== undefined && { durationMs: entry.durationMs }),
@@ -7426,15 +7530,13 @@ function logDerivationEvaluation(entry, logger, config) {
             break;
         case 'skipped':
             logger.debug(`${LOG_PREFIX} -> Skipped: ${name} (${formatSkipReason(entry.skipReason)})`, {
-                source: entry.sourceFieldKey,
-                target: entry.targetFieldKey,
+                field: entry.fieldKey,
                 reason: entry.skipReason,
             });
             break;
         case 'error':
             logger.debug(`${LOG_PREFIX} -> Error: ${name}`, {
-                source: entry.sourceFieldKey,
-                target: entry.targetFieldKey,
+                field: entry.fieldKey,
                 error: entry.error,
             });
             break;
@@ -7518,12 +7620,11 @@ class ActiveDerivationLogger {
     evaluation(entry) {
         if (!shouldLog(this.config, 'verbose'))
             return;
-        const name = entry.debugName ? `"${entry.debugName}"` : `${entry.sourceFieldKey} -> ${entry.targetFieldKey}`;
+        const name = entry.debugName ? `"${entry.debugName}"` : entry.fieldKey;
         switch (entry.result) {
             case 'applied':
                 this.logger.debug(`Derivation - Applied ${name}`, {
-                    source: entry.sourceFieldKey,
-                    target: entry.targetFieldKey,
+                    field: entry.fieldKey,
                     previousValue: entry.previousValue,
                     newValue: entry.newValue,
                     ...(entry.durationMs !== undefined && { durationMs: entry.durationMs }),
@@ -7531,15 +7632,13 @@ class ActiveDerivationLogger {
                 break;
             case 'skipped':
                 this.logger.debug(`Derivation - Skipped ${name} (${this.formatSkipReason(entry.skipReason)})`, {
-                    source: entry.sourceFieldKey,
-                    target: entry.targetFieldKey,
+                    field: entry.fieldKey,
                     reason: entry.skipReason,
                 });
                 break;
             case 'error':
                 this.logger.debug(`Derivation - Error ${name}`, {
-                    source: entry.sourceFieldKey,
-                    target: entry.targetFieldKey,
+                    field: entry.fieldKey,
                     error: entry.error,
                 });
                 break;
@@ -7652,6 +7751,7 @@ class DerivationOrchestrator {
     warningTracker = inject(DERIVATION_WARNING_TRACKER);
     functionRegistry = inject(FunctionRegistryService);
     formOptions = inject(FORM_OPTIONS);
+    externalDataSignal = inject(EXTERNAL_DATA, { optional: true });
     /**
      * Computed signal containing the collected and validated derivations.
      * Returns null if no derivations are defined.
@@ -7696,7 +7796,9 @@ class DerivationOrchestrator {
             // Without this, exhaustMap would block indefinitely.
             return scheduled([null], queueScheduler);
         }), takeUntilDestroyed(this.destroyRef))
-            .subscribe();
+            .subscribe({
+            error: (err) => this.logger.error('Derivation onChange stream error', err),
+        });
     }
     setupDebouncedStream() {
         toObservable(this.config.formValue, { injector: this.injector })
@@ -7727,7 +7829,9 @@ class DerivationOrchestrator {
             const periodStreams = debouncePeriods.map((debounceMs) => this.createPeriodStream(debounceMs, collection, formAccessor, changedFields));
             return merge(...periodStreams);
         }), takeUntilDestroyed(this.destroyRef))
-            .subscribe();
+            .subscribe({
+            error: (err) => this.logger.error('Derivation debounced stream error', err),
+        });
     }
     createPeriodStream(debounceMs, collection, formAccessor, changedFields) {
         const additionalWait = Math.max(0, debounceMs - DEFAULT_DEBOUNCE_MS);
@@ -7750,6 +7854,7 @@ class DerivationOrchestrator {
             rootForm: formAccessor,
             derivationFunctions: this.functionRegistry.getDerivationFunctions(),
             customFunctions: this.functionRegistry.getCustomFunctions(),
+            externalData: this.resolveExternalData(),
             logger: this.logger,
             warningTracker: this.warningTracker,
             derivationLogger: untracked(() => this.config.derivationLogger()),
@@ -7777,6 +7882,7 @@ class DerivationOrchestrator {
             rootForm: formAccessor,
             derivationFunctions: this.functionRegistry.getDerivationFunctions(),
             customFunctions: this.functionRegistry.getCustomFunctions(),
+            externalData: this.resolveExternalData(),
             logger: this.logger,
             warningTracker: this.warningTracker,
             derivationLogger: untracked(() => this.config.derivationLogger()),
@@ -7810,12 +7916,36 @@ class DerivationOrchestrator {
         // Find implicit wildcards (custom functions without explicit dependsOn)
         const implicitWildcards = wildcardEntries.filter((entry) => entry.functionName && (!entry.originalConfig?.dependsOn || entry.originalConfig.dependsOn.length === 0));
         if (implicitWildcards.length > 0) {
-            const derivationDescs = implicitWildcards.map((e) => `${e.sourceFieldKey} -> ${e.targetFieldKey} (${e.functionName})`);
+            const derivationDescs = implicitWildcards.map((e) => `${e.fieldKey} (${e.functionName})`);
             this.logger.warn('[Derivation] Derivations using custom functions without explicit dependsOn detected. ' +
                 `These run on EVERY form change, which may impact performance (form has ${fieldCount} fields). ` +
                 'Consider specifying explicit dependsOn arrays for better performance.', derivationDescs);
         }
     }
+    /**
+     * 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.externalDataSignal?.());
+        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.
@@ -8336,9 +8466,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-CrO9WTDw.mjs').then(m => m.default)], () => [import('./ng-forge-dynamic-forms-page-field.component-CrO9WTDw.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-RN1hmG69.mjs').then(m => m.default)], () => [import('./ng-forge-dynamic-forms-page-field.component-RN1hmG69.mjs').then(m => m.default)]] });
 }
-i0.ɵɵngDeclareClassMetadataAsync({ minVersion: "18.0.0", version: "21.1.0", ngImport: i0, type: PageOrchestratorComponent, resolveDeferredDeps: () => [import('./ng-forge-dynamic-forms-page-field.component-CrO9WTDw.mjs').then(m => m.default)], resolveMetadata: PageFieldComponent => ({ decorators: [{
+i0.ɵɵngDeclareClassMetadataAsync({ minVersion: "18.0.0", version: "21.1.0", ngImport: i0, type: PageOrchestratorComponent, resolveDeferredDeps: () => [import('./ng-forge-dynamic-forms-page-field.component-RN1hmG69.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) {
@@ -8768,10 +8898,21 @@ class DynamicForm {
     /** Emits when form dirty state changes. */
     dirtyChange = outputFromObservable(toObservable(this.dirty));
     /**
-     * Emits form values when submitted (via SubmitEvent).
+     * Emits form values when submitted (via SubmitEvent) and form is valid.
+     *
+     * **Important:** This output only emits when the form is valid. If you need to
+     * handle submit events regardless of validity, use the `(events)` output and
+     * filter for `'submit'` events.
+     *
      * Note: Does not emit when `submission.action` is configured - use one or the other.
      */
-    submitted = outputFromObservable(this.eventBus.on('submit').pipe(switchMap(() => {
+    submitted = outputFromObservable(this.eventBus.on('submit').pipe(filter(() => {
+        if (!this.valid()) {
+            this.logger.debug('Form submitted while invalid, not emitting to (submitted) output');
+            return false;
+        }
+        return true;
+    }), switchMap(() => {
         const submissionConfig = this.config().submission;
         if (submissionConfig?.action) {
             this.logger.warn('Both `submission.action` and `(submitted)` output are configured. ' +
@@ -8779,7 +8920,8 @@ class DynamicForm {
                 'Use either `submission.action` OR `(submitted)`, not both.');
             return EMPTY;
         }
-        return of(this.value());
+        // Form is valid here, cast to TModel (no longer Partial)
+        return of(this.formValue());
     })));
     /** Emits when form is reset to default values. */
     reset = outputFromObservable(this.eventBus.on('form-reset'));
@@ -8896,7 +9038,9 @@ class DynamicForm {
             formSignal: this.form,
         })
             .pipe(takeUntilDestroyed())
-            .subscribe();
+            .subscribe({
+            error: (err) => this.logger.error('Submission handler error', err),
+        });
     }
     registerValidatorsFromConfig({ customFnConfig, schemas }) {
         if (schemas) {
@@ -8987,6 +9131,11 @@ class DynamicForm {
                 useFactory: (form) => form.effectiveFormOptions,
                 deps: [DynamicForm],
             },
+            {
+                provide: EXTERNAL_DATA,
+                useFactory: (form) => computed(() => form.config().externalData),
+                deps: [DynamicForm],
+            },
             { provide: DERIVATION_WARNING_TRACKER, useFactory: createDerivationWarningTracker },
             {
                 provide: DERIVATION_ORCHESTRATOR,
@@ -9035,6 +9184,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.0", ngImpor
                             useFactory: (form) => form.effectiveFormOptions,
                             deps: [DynamicForm],
                         },
+                        {
+                            provide: EXTERNAL_DATA,
+                            useFactory: (form) => computed(() => form.config().externalData),
+                            deps: [DynamicForm],
+                        },
                         { provide: DERIVATION_WARNING_TRACKER, useFactory: createDerivationWarningTracker },
                         {
                             provide: DERIVATION_ORCHESTRATOR,
@@ -9225,13 +9379,13 @@ const BUILT_IN_FIELDS = [
     },
     {
         name: 'page',
-        loadComponent: () => import('./ng-forge-dynamic-forms-page-field.component-CrO9WTDw.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-page-field.component-RN1hmG69.mjs'),
         mapper: pageFieldMapper,
         valueHandling: 'flatten',
     },
     {
         name: 'text',
-        loadComponent: () => import('./ng-forge-dynamic-forms-text-field.component-BcFx_kOz.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-text-field.component-DIVyioMX.mjs'),
         mapper: textFieldMapper,
         valueHandling: 'exclude',
     },
@@ -9335,6 +9489,79 @@ function provideDynamicForm(...items) {
     ]);
 }
 
+/**
+ * Enables automatic form value attachment to all events dispatched through the EventBus.
+ *
+ * When this feature is enabled, events dispatched via `eventBus.dispatch()` will include
+ * the current form value in the `formValue` property. This is useful for event handlers
+ * that need access to the complete form state at the time of the event.
+ *
+ * @example Global opt-in
+ * ```typescript
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withEventFormValue()
+ * )
+ * ```
+ *
+ * @example Consumer usage
+ * ```typescript
+ * eventBus.on<SubmitEvent>('submit').subscribe(event => {
+ *   if (hasFormValue(event)) {
+ *     console.log('Form value:', event.formValue);
+ *   }
+ * });
+ * ```
+ *
+ * @example Per-form disable (when globally enabled)
+ * ```typescript
+ * const config: FormConfig = {
+ *   fields: [...],
+ *   options: { emitFormValueOnEvents: false }
+ * };
+ * ```
+ *
+ * @remarks
+ * **Precedence rules:**
+ * 1. Per-form `false` - Disables for this form, regardless of global setting
+ * 2. Per-form `true` - Enables for this form, regardless of global setting
+ * 3. Per-form `undefined` - Uses global setting
+ * 4. Global `withEventFormValue()` - Enables globally
+ * 5. No global feature - Disabled globally (default)
+ *
+ * @returns A DynamicFormFeature that enables form value attachment to events
+ *
+ * @public
+ */
+function withEventFormValue() {
+    return createFeature('event-form-value', [{ provide: EMIT_FORM_VALUE_ON_EVENTS, useValue: true }]);
+}
+
+/**
+ * Type guard to check if a form event has a form value attached.
+ *
+ * Use this to safely access the `formValue` property on events when
+ * `withEventFormValue()` is enabled globally or `options.emitFormValueOnEvents`
+ * is set to `true` in the form config.
+ *
+ * @example
+ * ```typescript
+ * eventBus.on<SubmitEvent>('submit').subscribe(event => {
+ *   if (hasFormValue(event)) {
+ *     console.log('Form value:', event.formValue);
+ *   }
+ * });
+ * ```
+ *
+ * @param event - The form event to check
+ * @returns `true` if the event has a form value attached, narrowing the type
+ *
+ * @public
+ */
+function hasFormValue(event) {
+    return 'formValue' in event && event.formValue !== undefined;
+}
+
 /**
  * No-op logger for when no logger is provided.
  * Used as fallback in button logic evaluation to avoid breaking downstream packages.
@@ -9646,6 +9873,176 @@ function formConfig(config) {
     return config;
 }
 
+/**
+ * Container field types that do NOT support labels or most logic
+ */
+const CONTAINER_TYPES = ['group', 'row', 'array'];
+/**
+ * Field types that support options at the field level
+ */
+const OPTION_FIELD_TYPES = ['select', 'radio', 'multi-checkbox'];
+/**
+ * Field type that uses minValue/maxValue instead of min/max in props
+ */
+const SLIDER_TYPE = 'slider';
+/**
+ * Hidden field type - no logic, no validators, no label
+ */
+const HIDDEN_TYPE = 'hidden';
+/**
+ * Page field type - only supports hidden logic
+ */
+const PAGE_TYPE = 'page';
+/**
+ * Creates a typed field configuration with helpful error messages for common mistakes.
+ *
+ * This helper function provides early validation and clear error messages
+ * for common configuration pitfalls that would otherwise cause runtime errors.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const nameField = createField('input', {
+ *   key: 'name',
+ *   label: 'Name',
+ *   value: ''
+ * });
+ *
+ * // With validation
+ * const emailField = createField('input', {
+ *   key: 'email',
+ *   label: 'Email',
+ *   required: true,
+ *   email: true,
+ *   props: { type: 'email' }
+ * });
+ *
+ * // Select with options (at field level)
+ * const countryField = createField('select', {
+ *   key: 'country',
+ *   label: 'Country',
+ *   options: [{ label: 'USA', value: 'us' }]
+ * });
+ *
+ * // Slider with minValue/maxValue (at field level)
+ * const ratingField = createField('slider', {
+ *   key: 'rating',
+ *   label: 'Rating',
+ *   minValue: 1,
+ *   maxValue: 10,
+ *   step: 1,
+ *   value: 5
+ * });
+ * ```
+ *
+ * @param type - The field type (e.g., 'input', 'select', 'group')
+ * @param config - The field configuration (excluding the 'type' property)
+ * @returns A properly typed field configuration
+ * @throws DynamicFormError if the configuration contains common mistakes
+ */
+function createField(type, config) {
+    const configWithProps = config;
+    // Validate key is present
+    if (!configWithProps['key']) {
+        throw new DynamicFormError(`createField('${type}'): 'key' property is required`);
+    }
+    // Container validation: no label allowed
+    if (CONTAINER_TYPES.includes(type)) {
+        if ('label' in configWithProps && configWithProps['label'] !== undefined) {
+            throw new DynamicFormError(`createField('${type}'): Container fields (${CONTAINER_TYPES.join(', ')}) do NOT support 'label'. ` +
+                `Labels go on the child fields inside the container.`);
+        }
+    }
+    // Container validation: no logic allowed (except page with hidden)
+    if (CONTAINER_TYPES.includes(type)) {
+        if ('logic' in configWithProps && configWithProps['logic'] !== undefined) {
+            throw new DynamicFormError(`createField('${type}'): Container fields (${CONTAINER_TYPES.join(', ')}) do NOT support 'logic'. ` +
+                `Apply logic to child fields instead, or use 'page' containers which support 'hidden' logic only.`);
+        }
+    }
+    // Page validation: only hidden logic allowed
+    if (type === PAGE_TYPE && 'logic' in configWithProps) {
+        const logic = configWithProps['logic'];
+        if (Array.isArray(logic)) {
+            const nonHiddenLogic = logic.filter((l) => l.type !== 'hidden');
+            if (nonHiddenLogic.length > 0) {
+                throw new DynamicFormError(`createField('page'): Pages only support 'hidden' logic type. ` +
+                    `Found unsupported logic types: ${nonHiddenLogic.map((l) => l.type).join(', ')}. ` +
+                    `For other logic types, apply them to child fields instead.`);
+            }
+        }
+    }
+    // Options placement validation
+    if (OPTION_FIELD_TYPES.includes(type)) {
+        const props = configWithProps['props'];
+        if (props && 'options' in props) {
+            throw new DynamicFormError(`createField('${type}'): 'options' must be at FIELD level, NOT inside 'props'. ` +
+                `Move 'options' from props to the field root: { type: '${type}', key: '...', options: [...] }`);
+        }
+    }
+    // Slider props validation
+    if (type === SLIDER_TYPE) {
+        const props = configWithProps['props'];
+        if (props) {
+            if ('min' in props || 'max' in props) {
+                throw new DynamicFormError(`createField('slider'): Use 'minValue' and 'maxValue' at FIELD level, NOT 'min'/'max' in props. ` +
+                    `Example: { type: 'slider', key: '...', minValue: 0, maxValue: 100, step: 1 }`);
+            }
+            if ('step' in props) {
+                throw new DynamicFormError(`createField('slider'): Use 'step' at FIELD level, NOT in props. ` +
+                    `Example: { type: 'slider', key: '...', minValue: 0, maxValue: 100, step: 1 }`);
+            }
+        }
+    }
+    // Hidden field validation
+    if (type === HIDDEN_TYPE) {
+        if ('logic' in configWithProps && configWithProps['logic'] !== undefined) {
+            throw new DynamicFormError(`createField('hidden'): Hidden fields do NOT support 'logic'. ` + `Hidden fields are purely for passing values through the form.`);
+        }
+        if ('validators' in configWithProps && configWithProps['validators'] !== undefined) {
+            throw new DynamicFormError(`createField('hidden'): Hidden fields do NOT support 'validators'. ` +
+                `Hidden fields are purely for passing values through the form.`);
+        }
+        if ('required' in configWithProps && configWithProps['required']) {
+            throw new DynamicFormError(`createField('hidden'): Hidden fields do NOT support 'required' validation. ` +
+                `Hidden fields are purely for passing values through the form.`);
+        }
+        if ('label' in configWithProps && configWithProps['label'] !== undefined) {
+            throw new DynamicFormError(`createField('hidden'): Hidden fields do NOT support 'label'. ` +
+                `Hidden fields are not rendered and have no visual representation.`);
+        }
+    }
+    // Array field validation
+    if (type === 'array') {
+        if ('template' in configWithProps) {
+            throw new DynamicFormError(`createField('array'): Use 'fields' (NOT 'template') to define the array item structure. ` +
+                `Example: { type: 'array', key: '...', fields: [{ type: 'group', key: 'item', fields: [...] }] }`);
+        }
+        if ('minItems' in configWithProps || 'maxItems' in configWithProps) {
+            throw new DynamicFormError(`createField('array'): 'minItems' and 'maxItems' properties are NOT supported. ` +
+                `Use custom validation if you need to enforce array length constraints.`);
+        }
+    }
+    // Generic button validation
+    if (type === 'button') {
+        if (!('event' in configWithProps) || configWithProps['event'] === undefined) {
+            throw new DynamicFormError(`createField('button'): Generic buttons REQUIRE the 'event' property with a FormEventConstructor. ` +
+                `For common actions, use 'submit', 'next', or 'previous' instead which don't require event configuration. ` +
+                `Example: { type: 'submit', key: 'submit', label: 'Submit' }`);
+        }
+    }
+    return { type, ...config };
+}
+/**
+ * Shorthand alias for createField
+ *
+ * @example
+ * ```typescript
+ * const nameField = field('input', { key: 'name', label: 'Name', value: '' });
+ * ```
+ */
+const field = createField;
+
 /**
  * Converts DynamicText (string | Observable | Signal) to Observable<string>
  * Unifies all three types into a consistent Observable stream
@@ -10392,49 +10789,65 @@ class ArrayFieldComponent {
                 this.resolvedItemsSignal.set([]);
                 break;
             case 'initial':
-                this.resolveAllItems(fieldTrees, updateId);
+                void this.resolveAllItems(fieldTrees, updateId);
                 break;
             case 'append':
-                this.appendItems(fieldTrees, operation.startIndex, operation.endIndex, updateId);
+                void this.appendItems(fieldTrees, operation.startIndex, operation.endIndex, updateId);
                 break;
             case 'pop':
                 this.resolvedItemsSignal.set(resolvedItems.slice(0, operation.newLength));
                 break;
             case 'recreate':
                 this.resolvedItemsSignal.set([]);
-                this.resolveAllItems(fieldTrees, updateId);
+                void this.resolveAllItems(fieldTrees, updateId);
                 break;
             case 'none':
                 break;
         }
     }
-    resolveAllItems(fieldTrees, updateId) {
+    async resolveAllItems(fieldTrees, updateId) {
         if (fieldTrees.length === 0) {
             this.resolvedItemsSignal.set([]);
             return;
         }
-        const itemObservables = fieldTrees.map((fieldTree, i) => this.createResolveItemObservable(fieldTree, i));
-        forkJoin(itemObservables)
-            .pipe(takeUntilDestroyed(this.destroyRef), map((items) => items.filter((item) => item !== undefined)))
-            .subscribe((newItems) => {
+        // Wrap each item observable to catch individual errors
+        const safeItemObservables = fieldTrees.map((fieldTree, i) => this.createResolveItemObservable(fieldTree, i).pipe(catchError((error) => {
+            this.logger.error(`Failed to resolve array item at index ${i}:`, error);
+            return of(undefined);
+        })));
+        try {
+            const items = await firstValueFrom(forkJoin(safeItemObservables).pipe(map((items) => items.filter((item) => item !== undefined))));
             if (updateId === this.updateVersion()) {
-                this.resolvedItemsSignal.set(newItems);
+                this.resolvedItemsSignal.set(items);
                 emitComponentInitialized(this.eventBus, 'array', this.field().key, this.parentInjector);
             }
-        });
+        }
+        catch (err) {
+            this.logger.error('Failed to resolve array items:', err);
+            this.resolvedItemsSignal.set([]);
+        }
     }
-    appendItems(fieldTrees, startIndex, endIndex, updateId) {
+    async appendItems(fieldTrees, startIndex, endIndex, updateId) {
         const itemsToResolve = fieldTrees.slice(startIndex, endIndex);
         if (itemsToResolve.length === 0)
             return;
-        const itemObservables = itemsToResolve.map((fieldTree, i) => this.createResolveItemObservable(fieldTree, startIndex + i));
-        forkJoin(itemObservables)
-            .pipe(takeUntilDestroyed(this.destroyRef), map((items) => items.filter((item) => item !== undefined)))
-            .subscribe((newItems) => {
+        // Wrap each item observable to catch individual errors
+        const safeItemObservables = itemsToResolve.map((fieldTree, i) => {
+            const index = startIndex + i;
+            return this.createResolveItemObservable(fieldTree, index).pipe(catchError((error) => {
+                this.logger.error(`Failed to resolve array item at index ${index}:`, error);
+                return of(undefined);
+            }));
+        });
+        try {
+            const newItems = await firstValueFrom(forkJoin(safeItemObservables).pipe(map((items) => items.filter((item) => item !== undefined))));
             if (updateId === this.updateVersion()) {
                 this.resolvedItemsSignal.update((current) => [...current, ...newItems]);
             }
-        });
+        }
+        catch (err) {
+            this.logger.error('Failed to append array items:', err);
+        }
     }
     createResolveItemObservable(fieldTree, index) {
         const template = this.fieldTemplate();
@@ -10466,9 +10879,11 @@ class ArrayFieldComponent {
         const insertIndex = index !== undefined ? Math.min(index, currentArray.length) : currentArray.length;
         const rawValue = getFieldDefaultValue(fieldTemplate, this.rawFieldRegistry());
         const valueHandling = getFieldValueHandling(fieldTemplate.type, this.rawFieldRegistry());
-        // For fields with 'include' value handling (bare fields like input, checkbox, etc.),
-        // wrap the value in an object using the field's key since arrays contain objects
-        const value = valueHandling === 'include' && fieldTemplate.key ? { [fieldTemplate.key]: rawValue } : rawValue;
+        const templateType = fieldTemplate.type;
+        // Container fields (group, row) already have their own structure, so use rawValue as-is.
+        // For value fields with 'include' handling, wrap in an object using the field's key.
+        const isContainer = templateType === 'group' || templateType === 'row';
+        const value = isContainer ? rawValue : valueHandling === 'include' && fieldTemplate.key ? { [fieldTemplate.key]: rawValue } : rawValue;
         const newArray = [...currentArray];
         newArray.splice(insertIndex, 0, value);
         // Update the parent form with the new array value
@@ -10656,5 +11071,5 @@ function extractErrorParams(error) {
  * Generated bundle index. Do not edit.
  */
 
-export { applyValidator as $, AddArrayItemEvent as A, DynamicFormError as B, ConsoleLogger as C, DynamicFormLogger as D, EventBus as E, FormClearEvent as F, baseFieldMapper as G, buildBaseInputs as H, arrayFieldMapper as I, groupFieldMapper as J, pageFieldMapper as K, rowFieldMapper as L, textFieldMapper as M, NoopLogger as N, FIELD_REGISTRY as O, PageChangeEvent as P, ARRAY_CONTEXT as Q, RemoveArrayItemEvent as R, SubmitEvent as S, DEFAULT_PROPS as T, DEFAULT_VALIDATION_MESSAGES as U, FIELD_SIGNAL_CONTEXT as V, FORM_OPTIONS as W, dynamicTextToObservable as X, ArrayFieldComponent as Y, GroupFieldComponent as Z, RowFieldComponent as _, DynamicTextPipe as a, applyValidators as a0, getArrayLength as a1, resolveTokens as a2, BUILT_IN_FIELDS as a3, isEqual as a4, omit as a5, interpolateParams as a6, applyMetaToElement as a7, RootFormRegistryService as a8, DynamicForm as b, createFieldResolutionPipe as c, derivedFromDeferred as d, emitComponentInitialized as e, isFormStateCondition as f, resolveNextButtonDisabled as g, isCheckedField as h, injectFieldRegistry as i, isValueField as j, isRowField as k, isArrayField as l, isContainerField as m, isDisplayOnlyField as n, isGroupField as o, provideDynamicForm as p, isLeafField as q, resolveSubmitButtonDisabled as r, isPageField as s, isValueBearingField as t, FormResetEvent as u, validatePageNesting as v, withLoggerConfig as w, NextPageEvent as x, PreviousPageEvent as y, formConfig as z };
-//# sourceMappingURL=ng-forge-dynamic-forms-ng-forge-dynamic-forms-WGww2nXx.mjs.map
+export { dynamicTextToObservable as $, AddArrayItemEvent as A, PreviousPageEvent as B, ConsoleLogger as C, DynamicFormLogger as D, EventBus as E, FormClearEvent as F, createField as G, field as H, formConfig as I, DynamicFormError as J, baseFieldMapper as K, buildBaseInputs as L, arrayFieldMapper as M, NoopLogger as N, groupFieldMapper as O, PageChangeEvent as P, pageFieldMapper as Q, RemoveArrayItemEvent as R, SubmitEvent as S, rowFieldMapper as T, textFieldMapper as U, FIELD_REGISTRY as V, ARRAY_CONTEXT as W, DEFAULT_PROPS as X, DEFAULT_VALIDATION_MESSAGES as Y, FIELD_SIGNAL_CONTEXT as Z, FORM_OPTIONS as _, DynamicTextPipe as a, ArrayFieldComponent as a0, GroupFieldComponent as a1, RowFieldComponent as a2, applyValidator as a3, applyValidators as a4, getArrayLength as a5, resolveTokens as a6, BUILT_IN_FIELDS as a7, isEqual as a8, omit as a9, interpolateParams as aa, applyMetaToElement as ab, RootFormRegistryService as ac, DynamicForm as b, createFieldResolutionPipe as c, derivedFromDeferred as d, emitComponentInitialized as e, withEventFormValue as f, isFormStateCondition as g, hasFormValue as h, injectFieldRegistry as i, resolveNextButtonDisabled as j, isCheckedField as k, isValueField as l, isRowField as m, isArrayField as n, isContainerField as o, provideDynamicForm as p, isDisplayOnlyField as q, resolveSubmitButtonDisabled as r, isGroupField as s, isLeafField as t, isPageField as u, validatePageNesting as v, withLoggerConfig as w, isValueBearingField as x, FormResetEvent as y, NextPageEvent as z };
+//# sourceMappingURL=ng-forge-dynamic-forms-ng-forge-dynamic-forms-BWFdMPyw.mjs.map