@ng-forge/dynamic-forms 0.4.0 → 0.5.1

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

@@ -1,21 +1,24 @@
 import * as i0 from '@angular/core';
-import { isSignal, computed, runInInjectionContext, InjectionToken, inject, signal, Injectable, untracked, input, linkedSignal, ChangeDetectionStrategy, Component, DestroyRef, Injector, model, afterNextRender, makeEnvironmentProviders, Pipe } from '@angular/core';
+import { isSignal, computed, runInInjectionContext, InjectionToken, inject, signal, Injectable, untracked, Injector, isDevMode, isWritableSignal, DestroyRef, input, linkedSignal, ChangeDetectionStrategy, Component, model, afterNextRender, makeEnvironmentProviders, Pipe } from '@angular/core';
 import { NgComponentOutlet } from '@angular/common';
-import { submit, email, min, max, minLength, maxLength, pattern, required, validate, validateAsync, validateHttp, disabled, readonly, hidden, applyEach, applyWhenValue, applyWhen, apply, schema, validateTree, form, provideSignalFormsConfig } from '@angular/forms/signals';
+import { submit, email, min, max, minLength, maxLength, pattern, required, validate, validateAsync, validateHttp, disabled, readonly, hidden, applyEach, applyWhenValue, applyWhen, apply, schema, validateStandardSchema, validateTree, form, provideSignalFormsConfig } from '@angular/forms/signals';
 import { toObservable, toSignal, takeUntilDestroyed, outputFromObservable } from '@angular/core/rxjs-interop';
-import { defer, combineLatest, from, map, catchError, of, pipe, switchMap, forkJoin, scan, isObservable, firstValueFrom, EMPTY, Subject, filter } from 'rxjs';
+import { defer, combineLatest, from, map, catchError, of, pipe, switchMap, forkJoin, scan, isObservable, firstValueFrom, EMPTY, debounceTime, distinctUntilChanged, startWith, tap, Subject, filter, combineLatestWith, auditTime, exhaustMap, scheduled, queueScheduler, pairwise, merge, timer } from 'rxjs';
+import { isStandardSchemaMarker } from '@ng-forge/dynamic-forms/schema';
 import { scan as scan$1, map as map$1, filter as filter$1, take, switchMap as switchMap$1, shareReplay } from 'rxjs/operators';
 import { explicitEffect } from 'ngxtension/explicit-effect';
 import { NG_STATUS_CLASSES } from '@angular/forms/signals/compat';
 
 /**
  * Type guard to check if a value is an array of Signals.
+ * @internal
  */
 function isSignalArray(value) {
     return Array.isArray(value) && value.every((item) => isSignal(item));
 }
 /**
- * Type guard to check if a value is an object of Signals (record).
+ * Type guard to check if a value is a record (object) of Signals.
+ * @internal
  */
 function isSignalRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value) && Object.values(value).every((item) => isSignal(item));
@@ -297,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);
         }
@@ -345,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);
     };
 }
 /**
@@ -395,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:
@@ -409,6 +417,133 @@ function createSubmissionHandler(options) {
  * Native JavaScript utility functions to replace lodash-es
  * These are simple implementations for common object manipulation patterns
  */
+/**
+ * Performs a deep equality comparison between two values.
+ *
+ * Handles:
+ * - Primitives (including NaN via Object.is)
+ * - Dates (by timestamp)
+ * - Arrays (deep element comparison)
+ * - Plain objects (deep property comparison)
+ * - RegExp (by source and flags)
+ * - Map and Set (by entries)
+ * - Circular references (via WeakMap tracking)
+ *
+ * @param a - First value
+ * @param b - Second value
+ * @returns true if values are deeply equal
+ *
+ * @example
+ * ```typescript
+ * isEqual({ a: 1 }, { a: 1 }); // true
+ * isEqual([1, 2], [1, 2]); // true
+ * isEqual({ a: 1 }, { a: 2 }); // false
+ * isEqual(new Date('2024-01-01'), new Date('2024-01-01')); // true
+ * isEqual(/abc/gi, /abc/gi); // true
+ * ```
+ */
+function isEqual(a, b) {
+    return isEqualInternal(a, b, new WeakMap(), new WeakMap());
+}
+/**
+ * Internal implementation with circular reference tracking.
+ * @internal
+ */
+function isEqualInternal(a, b, seenA, seenB) {
+    // Same reference or both null/undefined
+    if (a === b)
+        return true;
+    // Handle NaN (NaN === NaN is false, but we want it to be equal)
+    if (typeof a === 'number' && typeof b === 'number') {
+        return Object.is(a, b);
+    }
+    // One is null/undefined but not both
+    if (a == null || b == null)
+        return false;
+    // Different types
+    if (typeof a !== typeof b)
+        return false;
+    // Non-object primitives (strings, booleans, symbols, bigints)
+    if (typeof a !== 'object') {
+        return Object.is(a, b);
+    }
+    // At this point, both a and b are objects (typeof a === 'object')
+    const objA = a;
+    const objB = b;
+    // Check for circular references
+    if (seenA.has(objA) || seenB.has(objB)) {
+        // If we've seen these objects before, check if they were paired together
+        return seenA.get(objA) === objB && seenB.get(objB) === objA;
+    }
+    // Mark these objects as seen (paired together)
+    seenA.set(objA, objB);
+    seenB.set(objB, objA);
+    // Different constructors means different types (e.g., Date vs Object)
+    if (objA.constructor !== objB.constructor)
+        return false;
+    // Handle dates
+    if (a instanceof Date && b instanceof Date) {
+        return a.getTime() === b.getTime();
+    }
+    // Handle RegExp
+    if (a instanceof RegExp && b instanceof RegExp) {
+        return a.source === b.source && a.flags === b.flags;
+    }
+    // Handle Map
+    if (a instanceof Map && b instanceof Map) {
+        if (a.size !== b.size)
+            return false;
+        for (const [key, value] of a) {
+            if (!b.has(key) || !isEqualInternal(value, b.get(key), seenA, seenB)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    // Handle Set
+    if (a instanceof Set && b instanceof Set) {
+        if (a.size !== b.size)
+            return false;
+        for (const value of a) {
+            if (!b.has(value)) {
+                // For non-primitive values in Sets, we need deep comparison
+                // This is O(n^2) but Sets rarely contain objects
+                if (typeof value === 'object' && value !== null) {
+                    let found = false;
+                    for (const bValue of b) {
+                        if (typeof bValue === 'object' && bValue !== null && isEqualInternal(value, bValue, seenA, seenB)) {
+                            found = true;
+                            break;
+                        }
+                    }
+                    if (!found)
+                        return false;
+                }
+                else {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    // Handle arrays
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((item, index) => isEqualInternal(item, b[index], seenA, seenB));
+    }
+    // Handle plain objects
+    const recordA = a;
+    const recordB = b;
+    // Get both string and symbol keys
+    const keysA = [...Object.keys(recordA), ...Object.getOwnPropertySymbols(recordA)];
+    const keysB = [...Object.keys(recordB), ...Object.getOwnPropertySymbols(recordB)];
+    if (keysA.length !== keysB.length)
+        return false;
+    // Create a Set for O(1) lookup
+    const keySetB = new Set(keysB);
+    return keysA.every((key) => keySetB.has(key) && isEqualInternal(recordA[key], recordB[key], seenA, seenB));
+}
 /**
  * Creates a new object without the specified keys
  * Native replacement for lodash omit()
@@ -516,54 +651,6 @@ function memoize(fn, resolverOrOptions) {
         return result;
     });
 }
-/**
- * Performs a deep equality comparison between two values
- * Native replacement for lodash isEqual()
- *
- * @param a - First value
- * @param b - Second value
- * @returns true if values are deeply equal
- *
- * @example
- * ```typescript
- * isEqual({ a: 1 }, { a: 1 }); // true
- * isEqual([1, 2], [1, 2]); // true
- * isEqual({ a: 1 }, { a: 2 }); // false
- * ```
- */
-function isEqual(a, b) {
-    // Same reference or both null/undefined
-    if (a === b)
-        return true;
-    // One is null/undefined but not both
-    if (a == null || b == null)
-        return false;
-    // Different types
-    if (typeof a !== typeof b)
-        return false;
-    // Handle dates
-    if (a instanceof Date && b instanceof Date) {
-        return a.getTime() === b.getTime();
-    }
-    // Handle arrays
-    if (Array.isArray(a) && Array.isArray(b)) {
-        if (a.length !== b.length)
-            return false;
-        return a.every((item, index) => isEqual(item, b[index]));
-    }
-    // Handle objects
-    if (typeof a === 'object' && typeof b === 'object') {
-        const objA = a;
-        const objB = b;
-        const keysA = Object.keys(objA);
-        const keysB = Object.keys(objB);
-        if (keysA.length !== keysB.length)
-            return false;
-        return keysA.every((key) => keysB.includes(key) && isEqual(objA[key], objB[key]));
-    }
-    // Primitives - use Object.is to handle NaN correctly (NaN === NaN is false, but Object.is(NaN, NaN) is true)
-    return Object.is(a, b);
-}
 /**
  * Normalizes a fields collection to an array.
  * Handles both array format and object format (keyed by field key).
@@ -574,6 +661,52 @@ function isEqual(a, b) {
 function normalizeFieldsArray(fields) {
     return Array.isArray(fields) ? [...fields] : Object.values(fields);
 }
+/**
+ * Gets the keys that differ between two objects.
+ *
+ * Compares top-level keys and returns those whose values are different.
+ * Uses deep equality comparison for nested values.
+ *
+ * @param previous - Previous object state
+ * @param current - Current object state
+ * @returns Set of keys that have different values
+ *
+ * @example
+ * ```typescript
+ * const prev = { a: 1, b: 2, c: 3 };
+ * const curr = { a: 1, b: 5, d: 4 };
+ * getChangedKeys(prev, curr); // Set { 'b', 'c', 'd' }
+ * ```
+ */
+function getChangedKeys(previous, current) {
+    const changedKeys = new Set();
+    // Handle null/undefined cases
+    if (!previous && !current)
+        return changedKeys;
+    if (!previous) {
+        return new Set(Object.keys(current ?? {}));
+    }
+    if (!current) {
+        return new Set(Object.keys(previous));
+    }
+    // Collect all keys from both objects
+    const allKeys = new Set([...Object.keys(previous), ...Object.keys(current)]);
+    // Check each key for differences
+    for (const key of allKeys) {
+        const prevValue = previous[key];
+        const currValue = current[key];
+        // Key added or removed
+        if (!(key in previous) || !(key in current)) {
+            changedKeys.add(key);
+            continue;
+        }
+        // Value changed
+        if (!isEqual(prevValue, currValue)) {
+            changedKeys.add(key);
+        }
+    }
+    return changedKeys;
+}
 
 /**
  * Injection token for providing field signal context to mappers and components.
@@ -709,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.
@@ -1051,7 +1214,7 @@ class RootFormRegistryService {
                 }
             }
             catch {
-                // Ignore errors when reading form value
+                // Ignore errors when reading form value - can happen during initialization
             }
         }
         return {};
@@ -1115,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
@@ -1149,6 +1313,7 @@ class FieldContextRegistryService {
             formValue,
             fieldPath,
             customFunctions: customFunctions || {},
+            externalData: this.resolveExternalData(false),
             logger: this.logger,
         };
     }
@@ -1167,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.
      *
@@ -1195,6 +1378,7 @@ class FieldContextRegistryService {
             formValue,
             fieldPath,
             customFunctions: customFunctions || {},
+            externalData: this.resolveExternalData(true),
             logger: this.logger,
         };
     }
@@ -1219,6 +1403,7 @@ class FieldContextRegistryService {
             formValue,
             fieldPath,
             customFunctions: customFunctions || {},
+            externalData: this.resolveExternalData(true),
             logger: this.logger,
         };
     }
@@ -1286,6 +1471,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.0", ngImpor
 class FunctionRegistryService {
     customFunctions = new Map();
     customFunctionScopes = new Map();
+    derivationFunctions = new Map();
     validators = new Map();
     asyncValidators = new Map();
     httpValidators = new Map();
@@ -1344,6 +1530,56 @@ class FunctionRegistryService {
         this.customFunctions.clear();
         this.customFunctionScopes.clear();
     }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Derivation Functions
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Register a derivation function for value derivation logic.
+     *
+     * Derivation functions compute derived values and are called when a
+     * `DerivationLogicConfig` references them by `functionName`.
+     *
+     * @param name - Unique identifier for the function
+     * @param fn - Function that receives EvaluationContext and returns the derived value
+     *
+     * @example
+     * ```typescript
+     * registry.registerDerivationFunction('getCurrencyForCountry', (ctx) => {
+     *   const countryToCurrency = { 'USA': 'USD', 'Germany': 'EUR', 'UK': 'GBP' };
+     *   return countryToCurrency[ctx.formValue.country] ?? 'USD';
+     * });
+     * ```
+     */
+    registerDerivationFunction(name, fn) {
+        this.derivationFunctions.set(name, fn);
+    }
+    /**
+     * Get a derivation function by name
+     */
+    getDerivationFunction(name) {
+        return this.derivationFunctions.get(name);
+    }
+    /**
+     * Get all derivation functions as an object
+     */
+    getDerivationFunctions() {
+        return Object.fromEntries(this.derivationFunctions);
+    }
+    /**
+     * Set derivation functions from a config object.
+     * Only updates functions if their references have changed.
+     *
+     * @param derivations - Object mapping function names to derivation functions
+     */
+    setDerivationFunctions(derivations) {
+        this.setRegistryIfChanged(this.derivationFunctions, derivations);
+    }
+    /**
+     * Clear all derivation functions
+     */
+    clearDerivationFunctions() {
+        this.derivationFunctions.clear();
+    }
     /**
      * Register a custom validator using Angular's public FieldContext API
      *
@@ -1561,6 +1797,7 @@ class FunctionRegistryService {
      */
     clearAll() {
         this.clearCustomFunctions();
+        this.clearDerivationFunctions();
         this.clearValidators();
         this.clearAsyncValidators();
         this.clearHttpValidators();
@@ -2404,7 +2641,7 @@ class Evaluator {
 /**
  * Maximum cache size to prevent memory issues
  */
-const MAX_AST_CACHE_SIZE = 1000;
+const MAX_AST_CACHE_SIZE$1 = 1000;
 /**
  * LRU Cache implementation for AST nodes
  * Tracks access order to evict least-recently-used entries
@@ -2449,7 +2686,7 @@ class LRUCache {
 /**
  * Cache for parsed AST nodes to improve performance
  */
-const astCache = new LRUCache(MAX_AST_CACHE_SIZE);
+const astCache = new LRUCache(MAX_AST_CACHE_SIZE$1);
 /**
  * Secure expression parser that uses AST-based evaluation instead of eval() or new Function()
  *
@@ -2506,7 +2743,7 @@ class ExpressionParser {
     static getCacheStats() {
         return {
             size: astCache.size,
-            maxSize: MAX_AST_CACHE_SIZE,
+            maxSize: MAX_AST_CACHE_SIZE$1,
         };
     }
 }
@@ -2534,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) {
@@ -2674,6 +2915,105 @@ function createLogicFunction(expression) {
     contextCache.set(cacheKey, fn);
     return fn;
 }
+/**
+ * Cache for debounced logic functions.
+ * Keyed by injection context similar to logicFunctionCache, but includes debounceMs in the key.
+ */
+const debouncedLogicFunctionCache = new WeakMap();
+/**
+ * Gets or creates the cache map for debounced functions in a specific injection context.
+ */
+function getDebouncedContextCache(ctx) {
+    let outerCache = debouncedLogicFunctionCache.get(ctx.functionRegistry);
+    if (!outerCache) {
+        outerCache = new WeakMap();
+        debouncedLogicFunctionCache.set(ctx.functionRegistry, outerCache);
+    }
+    let innerCache = outerCache.get(ctx.fieldContextRegistry);
+    if (!innerCache) {
+        innerCache = new Map();
+        outerCache.set(ctx.fieldContextRegistry, innerCache);
+    }
+    return innerCache;
+}
+/**
+ * Store for debounced signals per field context.
+ * Uses WeakMap with FieldContext objects as keys to automatically clean up
+ * when the context is garbage collected.
+ */
+const debouncedSignalStore = new WeakMap();
+/**
+ * Gets or creates the debounced signal store for a function registry.
+ */
+function getDebouncedSignalStore(functionRegistry) {
+    let store = debouncedSignalStore.get(functionRegistry);
+    if (!store) {
+        store = new WeakMap();
+        debouncedSignalStore.set(functionRegistry, store);
+    }
+    return store;
+}
+/**
+ * Create a debounced logic function from a conditional expression.
+ *
+ * This function wraps the condition evaluation in a debounce mechanism,
+ * so state changes only take effect after the specified delay.
+ * Useful for avoiding UI flicker during rapid typing.
+ *
+ * @param expression The conditional expression to evaluate
+ * @param debounceMs The debounce duration in milliseconds
+ * @returns A LogicFn that evaluates the condition with debouncing
+ */
+function createDebouncedLogicFunction(expression, debounceMs) {
+    // Inject services during factory creation, not during execution
+    const functionRegistry = inject(FunctionRegistryService);
+    const fieldContextRegistry = inject(FieldContextRegistryService);
+    const injector = inject(Injector);
+    // Get cache for this injection context
+    const contextCache = getDebouncedContextCache({ functionRegistry, fieldContextRegistry });
+    // Generate cache key including debounceMs
+    const cacheKey = `${serializeExpression(expression)}:${debounceMs}`;
+    // Check cache first
+    const cached = contextCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    // Get or create the signal store for this context
+    const signalStore = getDebouncedSignalStore(functionRegistry);
+    const fn = (ctx) => {
+        // Create a unique key using the context object itself as identifier
+        // Since FieldContext doesn't have a path property, we use a WeakMap approach
+        // by storing the debounced signal directly on the context
+        const contextKey = ctx;
+        let signalPair = signalStore.get(contextKey);
+        if (!signalPair) {
+            // Create a signal to hold the immediate evaluation result
+            const immediateValue = signal(false, ...(ngDevMode ? [{ debugName: "immediateValue" }] : []));
+            // Create a debounced signal using RxJS
+            const immediateValue$ = toObservable(immediateValue, { injector }).pipe(debounceTime(debounceMs), distinctUntilChanged(), startWith(false));
+            const debouncedValue = toSignal(immediateValue$, { injector, initialValue: false });
+            signalPair = { immediateValue, debouncedValue };
+            signalStore.set(contextKey, signalPair);
+        }
+        // Create REACTIVE evaluation context for logic functions
+        const evaluationContext = fieldContextRegistry.createReactiveEvaluationContext(ctx, functionRegistry.getCustomFunctions());
+        // Evaluate the condition and update the immediate signal
+        const result = evaluateCondition(expression, evaluationContext);
+        // Update immediate value (this triggers the debounce chain)
+        // signalPair is guaranteed to exist here due to the initialization above
+        const { immediateValue, debouncedValue } = signalPair;
+        untracked(() => {
+            if (immediateValue() !== result) {
+                immediateValue.set(result);
+            }
+        });
+        // Return the debounced value
+        return debouncedValue() ?? false;
+    };
+    // Cache the function
+    contextCache.set(cacheKey, fn);
+    return fn;
+}
 
 /**
  * Cache for memoized dynamic value functions, keyed by service instance.
@@ -2721,6 +3061,36 @@ function createDynamicValueFunction(expression) {
     return fn;
 }
 
+/**
+ * Creates the default derivation log configuration.
+ *
+ * Defaults to 'none' (silent). Users can enable logging via `withLoggerConfig`.
+ *
+ * @returns Default DerivationLogConfig
+ *
+ * @public
+ */
+function createDefaultDerivationLogConfig() {
+    return {
+        level: 'none',
+    };
+}
+/**
+ * Checks if logging should occur at the specified level.
+ *
+ * @param config - Current log configuration
+ * @param minLevel - Minimum level required for logging
+ * @returns True if logging should occur
+ *
+ * @public
+ */
+function shouldLog(config, minLevel) {
+    if (config.level === 'none')
+        return false;
+    if (minLevel === 'summary')
+        return config.level === 'summary' || config.level === 'verbose';
+    return config.level === 'verbose';
+}
 /**
  * Type guard to check if a condition is a FormStateCondition.
  *
@@ -2732,6 +3102,28 @@ function createDynamicValueFunction(expression) {
 function isFormStateCondition(condition) {
     return typeof condition === 'string' && ['formInvalid', 'formSubmitting', 'pageInvalid'].includes(condition);
 }
+/**
+ * Type guard to check if a logic config is a StateLogicConfig.
+ *
+ * @param config - The logic config to check
+ * @returns true if the config is for field state logic
+ *
+ * @public
+ */
+function isStateLogicConfig(config) {
+    return config.type === 'hidden' || config.type === 'readonly' || config.type === 'disabled' || config.type === 'required';
+}
+/**
+ * Type guard to check if a logic config is a DerivationLogicConfig.
+ *
+ * @param config - The logic config to check
+ * @returns true if the config is for value derivation
+ *
+ * @public
+ */
+function isDerivationLogicConfig(config) {
+    return config.type === 'derivation';
+}
 
 /**
  * Regular expression to detect formValue property access in expressions.
@@ -2740,10 +3132,19 @@ function isFormStateCondition(condition) {
 const FORM_VALUE_ACCESS_PATTERN = /\bformValue\s*(?:\.|\[)/;
 /**
  * Regular expressions to extract field paths from formValue expressions.
+ *
+ * Enhanced to capture full nested paths including dot notation chains:
+ * - formValue.fieldName → captures 'fieldName'
+ * - formValue.parent.child.grandchild → captures 'parent.child.grandchild'
+ * - formValue['field-name'] → captures 'field-name'
+ * - formValue["field.with.dots"] → captures 'field.with.dots'
+ *
+ * Note: Computed property access (formValue[variableName]) is NOT supported
+ * and must use explicit dependsOn configuration.
  */
-const FORM_VALUE_DOT_PATTERN = /\bformValue\.(\w+)/g;
-const FORM_VALUE_BRACKET_SINGLE_PATTERN = /\bformValue\s*\[\s*'(\w+)'\s*\]/g;
-const FORM_VALUE_BRACKET_DOUBLE_PATTERN = /\bformValue\s*\[\s*"(\w+)"\s*\]/g;
+const FORM_VALUE_DOT_PATTERN = /\bformValue\.([\w.]+)/g;
+const FORM_VALUE_BRACKET_SINGLE_PATTERN = /\bformValue\s*\[\s*'([\w.-]+)'\s*\]/g;
+const FORM_VALUE_BRACKET_DOUBLE_PATTERN = /\bformValue\s*\[\s*"([\w.-]+)"\s*\]/g;
 /**
  * Detects if a ConditionalExpression references other fields (cross-field).
  *
@@ -2851,22 +3252,45 @@ function extractStringDependencies(expression) {
     extractFromExpressionString(expression, deps);
     return Array.from(deps);
 }
-/** Internal helper that populates a Set with dependencies from an expression string. */
+/**
+ * Internal helper that populates a Set with dependencies from an expression string.
+ *
+ * Extracts both root fields and full nested paths for precise dependency tracking:
+ * - 'formValue.parent.child' → adds 'parent' (root) and 'parent.child' (full path)
+ * - 'formValue.simple' → adds 'simple'
+ */
 function extractFromExpressionString(expression, deps) {
-    // Extract from dot notation: formValue.fieldName
+    // Extract from dot notation: formValue.fieldName or formValue.parent.child.grandchild
     const dotMatches = expression.matchAll(FORM_VALUE_DOT_PATTERN);
     for (const match of dotMatches) {
-        deps.add(match[1]);
+        const fullPath = match[1];
+        // Always add the root field (first segment) as the primary dependency
+        const rootField = fullPath.split('.')[0];
+        deps.add(rootField);
+        // Also add the full path for more precise dependency tracking if nested
+        if (fullPath.includes('.')) {
+            deps.add(fullPath);
+        }
     }
     // Extract from bracket notation with single quotes: formValue['fieldName']
     const bracketSingleMatches = expression.matchAll(FORM_VALUE_BRACKET_SINGLE_PATTERN);
     for (const match of bracketSingleMatches) {
-        deps.add(match[1]);
+        const fullPath = match[1];
+        const rootField = fullPath.split('.')[0];
+        deps.add(rootField);
+        if (fullPath.includes('.')) {
+            deps.add(fullPath);
+        }
     }
     // Extract from bracket notation with double quotes: formValue["fieldName"]
     const bracketDoubleMatches = expression.matchAll(FORM_VALUE_BRACKET_DOUBLE_PATTERN);
     for (const match of bracketDoubleMatches) {
-        deps.add(match[1]);
+        const fullPath = match[1];
+        const rootField = fullPath.split('.')[0];
+        deps.add(rootField);
+        if (fullPath.includes('.')) {
+            deps.add(fullPath);
+        }
     }
 }
 // ============================================================================
@@ -2919,14 +3343,34 @@ function hasCrossFieldWhenCondition(config, context) {
 // ============================================================================
 // Logic Detection
 // ============================================================================
+/**
+ * Detects if a StateLogicConfig has a cross-field condition.
+ *
+ * Note: This function only handles state logic (hidden, readonly, disabled, required).
+ * Derivation logic is handled separately by the derivation system.
+ *
+ * @param config The state logic configuration to check
+ * @param context Optional context providing function scope lookup
+ * @returns true if the logic condition references other fields
+ */
+function isCrossFieldStateLogic(config, context) {
+    return isCrossFieldExpression(config.condition, context);
+}
 /**
  * Detects if a LogicConfig has a cross-field condition.
  *
  * @param config The logic configuration to check
  * @param context Optional context providing function scope lookup
  * @returns true if the logic condition references other fields
+ *
+ * @deprecated Use `isCrossFieldStateLogic` for state logic configs.
+ *             Derivation logic is handled by the derivation system.
  */
 function isCrossFieldLogic(config, context) {
+    // Only check state logic configs
+    if (!isStateLogicConfig(config)) {
+        return false;
+    }
     return isCrossFieldExpression(config.condition, context);
 }
 // ============================================================================
@@ -3080,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);
 }
@@ -3134,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 = {
@@ -3164,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 = {
@@ -3189,13 +3625,111 @@ function applyValidators(configs, fieldPath) {
     configs.forEach((config) => applyValidator(config, fieldPath));
 }
 
-function applyLogic(config, fieldPath) {
-    const path = fieldPath;
+/**
+ * Default debounce duration in milliseconds.
+ */
+const DEFAULT_DEBOUNCE_MS = 500;
+/**
+ * Creates a debounced effect that triggers a callback after a signal's value
+ * has stabilized for the specified duration.
+ *
+ * Uses Angular's `toObservable` and `toSignal` with RxJS `debounceTime` for proper debouncing.
+ * This approach is cleaner than manual setTimeout management and integrates
+ * well with Angular's signal-based reactivity.
+ *
+ * @param source - The source signal to watch for changes
+ * @param callback - Function to call with the debounced value
+ * @param options - Configuration options
+ * @param options.ms - Debounce duration in milliseconds (default: 500)
+ * @param options.injector - Angular injector for the effect context
+ *
+ * @returns A signal that emits the debounced value (can be ignored if only side effects are needed)
+ *
+ * @example
+ * ```typescript
+ * // In a component or service
+ * const searchInput = signal('');
+ *
+ * createDebouncedEffect(
+ *   searchInput,
+ *   (value) => console.log('Debounced search:', value),
+ *   { ms: 300, injector: this.injector }
+ * );
+ * ```
+ *
+ * @public
+ */
+function createDebouncedEffect(source, callback, options) {
+    const { ms = DEFAULT_DEBOUNCE_MS, injector } = options;
+    const source$ = toObservable(source, { injector }).pipe(debounceTime(ms), distinctUntilChanged(), tap((value) => callback(value)));
+    return toSignal(source$, { injector });
+}
+/**
+ * Creates a debounced signal that emits values from the source signal
+ * only after the value has stabilized for the specified duration.
+ *
+ * Unlike `createDebouncedEffect`, this doesn't execute a side effect callback.
+ * Use this when you just need a debounced version of a signal.
+ *
+ * @param source - The source signal to debounce
+ * @param options - Configuration options
+ * @param options.ms - Debounce duration in milliseconds (default: 500)
+ * @param options.injector - Angular injector for the effect context
+ *
+ * @returns A signal that emits the debounced value
+ *
+ * @example
+ * ```typescript
+ * const input = signal('');
+ * const debouncedInput = createDebouncedSignal(input, { ms: 300, injector });
+ *
+ * effect(() => {
+ *   console.log('Debounced value:', debouncedInput());
+ * });
+ * ```
+ *
+ * @public
+ */
+function createDebouncedSignal(source, options) {
+    const { ms = DEFAULT_DEBOUNCE_MS, injector } = options;
+    const source$ = toObservable(source, { injector }).pipe(debounceTime(ms), distinctUntilChanged());
+    return toSignal(source$, { injector });
+}
+
+/**
+ * Extracts the trigger from a StateLogicConfig, handling the discriminated union.
+ */
+function getConfigTrigger(config) {
+    if (!isStateLogicConfig(config)) {
+        return 'onChange';
+    }
+    return config.trigger ?? 'onChange';
+}
+/**
+ * Extracts debounceMs from a StateLogicConfig if trigger is 'debounced'.
+ */
+function getConfigDebounceMs(config) {
+    if (!isStateLogicConfig(config)) {
+        return undefined;
+    }
+    // Type narrowing: debounceMs only exists when trigger is 'debounced'
+    if (config.trigger === 'debounced') {
+        return config.debounceMs;
+    }
+    return undefined;
+}
+function applyLogic(config, fieldPath) {
+    const path = fieldPath;
+    const trigger = getConfigTrigger(config);
+    const debounceMs = getConfigDebounceMs(config) ?? DEFAULT_DEBOUNCE_MS;
     if (typeof config.condition === 'boolean') {
         applyLogicFn(config.type, path, () => config.condition);
         return;
     }
-    const logicFn = createLogicFunction(config.condition);
+    // Create appropriate logic function based on trigger
+    const logicFn = trigger === 'debounced'
+        ? createDebouncedLogicFunction(config.condition, debounceMs)
+        : createLogicFunction(config.condition);
     applyLogicFn(config.type, path, logicFn);
 }
 function applyLogicFn(type, path, logicFn) {
@@ -3794,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)
@@ -3821,9 +4355,91 @@ function isDisplayOnlyField(field) {
     return field.type === 'text' || isContainerField(field);
 }
 
+/**
+ * Applies a form-level schema validation to a schema path.
+ * Supports both Standard Schema (Zod, Valibot, ArkType) and raw Angular schema callbacks.
+ *
+ * This is a helper function used internally by `createSchemaFromFields`
+ * to apply form-level validation after field-level validation.
+ *
+ * @typeParam TModel - The form value type
+ * @param path - The schema path to validate (from Angular's schema callback)
+ * @param formLevelSchema - Form-level schema (Standard Schema marker or Angular callback)
+ *
+ * @remarks
+ * Type assertions are required due to Angular's complex generic constraints:
+ * - `validateStandardSchema` uses `IgnoreUnknownProperties<TSchema>` to accommodate Zod's strict types
+ * - `SchemaPathTree` includes `SchemaPath` via conditional types that TypeScript can't narrow
+ * These assertions are safe because the path originates from Angular's schema() function.
+ *
+ * @internal
+ */
+function applyFormLevelSchema(path, formLevelSchema) {
+    if (isStandardSchemaMarker(formLevelSchema)) {
+        // Standard Schema (Zod, Valibot, ArkType, etc.)
+        // Cast via Parameters: validateStandardSchema's IgnoreUnknownProperties<TSchema> creates type incompatibility
+        // that TypeScript cannot resolve. The cast is safe as path comes from Angular's schema() callback.
+        validateStandardSchema(path, formLevelSchema.schema);
+    }
+    else if (typeof formLevelSchema === 'function') {
+        // Angular schema callback - execute directly with the path
+        // Cast via Function: AngularSchemaCallback expects intersection type SchemaPath & SchemaPathTree.
+        // SchemaPathTree structurally includes SchemaPath, so this is safe at runtime.
+        formLevelSchema(path);
+    }
+}
+/**
+ * Creates a schema from only form-level schema (when no field-level schema exists).
+ *
+ * Use this when the form has fields without validation rules but still
+ * needs form-level validation via a Standard Schema.
+ *
+ * @typeParam TModel - The form value type
+ * @param formLevelSchema - Form-level Standard Schema
+ * @returns Schema that applies form-level validation
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { standardSchema } from '@ng-forge/dynamic-forms/schema';
+ *
+ * const FormSchema = z.object({
+ *   email: z.string().email(),
+ *   password: z.string().min(8),
+ * });
+ *
+ * // Create schema from form-level schema only
+ * const formSchema = createFormLevelSchema(standardSchema(FormSchema));
+ * ```
+ */
+function createFormLevelSchema(formLevelSchema) {
+    return schema((path) => {
+        applyFormLevelSchema(path, 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
@@ -3837,13 +4453,18 @@ function getFieldTreeByKey(ctx, key) {
  *
  * @param fields Field definitions to create schema from
  * @param registry Field type registry
- * @param crossFieldValidators Optional array of collected cross-field validators
+ * @param optionsOrValidators Optional configuration object or array of cross-field validators (for backwards compatibility)
  */
-function createSchemaFromFields(fields, registry, crossFieldValidators) {
+function createSchemaFromFields(fields, registry, optionsOrValidators) {
     // Inject services for cross-field validation
     // These will be available because createSchemaFromFields is called within runInInjectionContext
     const functionRegistry = inject(FunctionRegistryService);
     const logger = inject(DynamicFormLogger);
+    // Normalize options - support both old array signature and new options object
+    const options = Array.isArray(optionsOrValidators)
+        ? { crossFieldValidators: optionsOrValidators }
+        : (optionsOrValidators ?? {});
+    const { crossFieldValidators, formLevelSchema } = options;
     return schema((path) => {
         for (const fieldDef of fields) {
             const valueHandling = getFieldValueHandling(fieldDef.type, registry);
@@ -3877,6 +4498,10 @@ function createSchemaFromFields(fields, registry, crossFieldValidators) {
         if (crossFieldValidators && crossFieldValidators.length > 0) {
             applyCrossFieldTreeValidator(path, crossFieldValidators, functionRegistry, logger);
         }
+        // Apply form-level Standard Schema validation
+        if (formLevelSchema) {
+            applyFormLevelSchema(path, formLevelSchema);
+        }
     });
 }
 /**
@@ -3986,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 = {
@@ -3998,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);
             }
         }
     }
@@ -4033,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 {
@@ -4133,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.
  *
@@ -4167,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.
@@ -4174,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
@@ -4187,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.
@@ -4617,19 +5320,19 @@ function createEmptyCollection() {
 /** Traverses field definitions and collects cross-field entries (validators, logic, schemas). */
 function collectCrossFieldEntries(fields) {
     const collection = createEmptyCollection();
-    traverseFields(fields, collection);
+    traverseFields$1(fields, collection);
     return collection;
 }
-function traverseFields(fields, collection) {
+function traverseFields$1(fields, collection) {
     for (const field of fields) {
-        collectFromField(field, collection);
+        collectFromField$1(field, collection);
         // Recursively process container fields (page, row, group, array)
         if (hasChildFields(field)) {
-            traverseFields(normalizeFieldsArray(field.fields), collection);
+            traverseFields$1(normalizeFieldsArray(field.fields), collection);
         }
     }
 }
-function collectFromField(field, collection) {
+function collectFromField$1(field, collection) {
     const fieldKey = field.key;
     if (!fieldKey)
         return;
@@ -4700,9 +5403,19 @@ function tryCreateValidatorEntry(fieldKey, config) {
     }
     return null;
 }
-/** Returns a logic entry if cross-field, null otherwise. */
+/**
+ * Returns a logic entry if cross-field state logic, null otherwise.
+ *
+ * Note: Derivation logic is handled separately by the derivation system
+ * and is not collected here.
+ */
 function tryCreateLogicEntry(fieldKey, config) {
-    if (!isCrossFieldLogic(config)) {
+    // Only process state logic (hidden, readonly, disabled, required)
+    // Derivation logic is handled by the derivation collector
+    if (!isStateLogicConfig(config)) {
+        return null;
+    }
+    if (!isCrossFieldStateLogic(config)) {
         return null;
     }
     const condition = config.condition;
@@ -4710,7 +5423,7 @@ function tryCreateLogicEntry(fieldKey, config) {
         sourceFieldKey: fieldKey,
         logicType: config.type,
         condition,
-        config,
+        config: config,
         dependsOn: extractExpressionDependencies(condition),
         category: 'logic',
     };
@@ -4750,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`);
@@ -4891,144 +5611,2510 @@ function isValidFormConfiguration(fields) {
     return FormModeValidator.validateFormConfiguration(fields).isValid;
 }
 
-class NextPageEvent {
-    type = 'next-page';
-}
-
-class PageChangeEvent {
-    currentPageIndex;
-    totalPages;
-    previousPageIndex;
-    type = 'page-change';
-    constructor(
-    /** The current page index (0-based) */
-    currentPageIndex, 
-    /** Total number of pages */
-    totalPages, 
-    /** Previous page index (0-based), undefined if first navigation */
-    previousPageIndex) {
-        this.currentPageIndex = currentPageIndex;
-        this.totalPages = totalPages;
-        this.previousPageIndex = previousPageIndex;
-    }
+/**
+ * Creates an empty derivation collection.
+ *
+ * @returns Empty collection ready for population
+ *
+ * @internal
+ */
+function createEmptyDerivationCollection() {
+    return { entries: [] };
 }
-
-class PreviousPageEvent {
-    type = 'previous-page';
+/**
+ * Creates a new derivation chain context for tracking applied derivations.
+ *
+ * @returns Fresh context for a new derivation cycle
+ *
+ * @internal
+ */
+function createDerivationChainContext() {
+    return {
+        appliedDerivations: new Set(),
+        iteration: 0,
+    };
 }
-
 /**
- * Event dispatched to add a new item to an array field.
+ * Creates a unique key for a derivation entry.
  *
- * This event is used to dynamically add items to array fields at runtime.
- * The array field component listens for this event and adds a new item
- * based on the provided field template, or uses the array's own template if not provided.
+ * 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.
  *
- * @example
- * ```typescript
- * // Add item using array's own template
- * eventBus.dispatch(AddArrayItemEvent, 'contacts');
+ * Note: For array derivations, callers must resolve placeholders
+ * (e.g., 'items.$.lineTotal' -> 'items.0.lineTotal') before calling this.
  *
- * // Add item with explicit field template
- * const fieldTemplate = { key: 'email', type: 'input' };
- * eventBus.dispatch(AddArrayItemEvent, 'contacts', fieldTemplate);
+ * @param fieldKey - The field key (with array index already resolved)
+ * @returns Unique key for the derivation
  *
- * // Add item at specific index
- * eventBus.dispatch(AddArrayItemEvent, 'contacts', fieldTemplate, 2);
- * ```
+ * @internal
  */
-class AddArrayItemEvent {
-    arrayKey;
-    field;
-    index;
-    type = 'add-array-item';
-    constructor(
-    /** The key of the array field to add an item to */
-    arrayKey, 
-    /**
-     * Optional field template definition to render for the new array item.
-     * If not provided, the array field component will use its own template.
-     */
-    field, 
-    /** Optional index where to insert the item (defaults to end of array) */
-    index) {
-        this.arrayKey = arrayKey;
-        this.field = field;
-        this.index = index;
-    }
+function createDerivationKey(fieldKey) {
+    return fieldKey;
+}
+/**
+ * Parses a derivation key back into field key.
+ *
+ * @param key - The derivation key to parse
+ * @returns Object containing the field key
+ *
+ * @internal
+ */
+function parseDerivationKey(key) {
+    return { fieldKey: key };
 }
 
 /**
- * Event dispatched to remove an item from an array field.
+ * Injection token for the collected derivation entries.
  *
- * This event is used to dynamically remove items from array fields at runtime.
- * The array field component listens for this event and removes the item
- * at the specified index.
+ * Provided at form level, contains the topologically sorted entries
+ * after validation. This is the "core data" that other derivation
+ * components consume.
  *
  * @example
  * ```typescript
- * // Remove item at index 1 from 'contacts' array
- * eventBus.dispatch(RemoveArrayItemEvent, 'contacts', 1);
+ * // In a component or service
+ * private readonly entries = inject(DERIVATION_ENTRIES);
  *
- * // Remove last item
- * eventBus.dispatch(RemoveArrayItemEvent, 'contacts');
+ * // Access the current entries
+ * const currentEntries = this.entries();
  * ```
  */
-class RemoveArrayItemEvent {
-    arrayKey;
-    index;
-    type = 'remove-array-item';
-    constructor(
-    /** The key of the array field to remove an item from */
-    arrayKey, 
-    /** Index of the item to remove (defaults to last item) */
-    index) {
-        this.arrayKey = arrayKey;
-        this.index = index;
-    }
-}
+const DERIVATION_ENTRIES = new InjectionToken('DerivationEntries');
 
 /**
- * Event dispatched when the form should be reset to its default values.
+ * Utilities for parsing and manipulating field paths in dynamic forms.
  *
- * This event instructs the dynamic form component to restore all field values
- * to their initial default values as defined in the form configuration.
+ * Field paths follow these formats:
+ * - Simple: "fieldName"
+ * - Nested: "parent.child.grandchild"
+ * - Array indexed: "items.0.quantity" or "items[0].quantity"
+ * - Array placeholder: "items.$.quantity" ($ = any index)
  *
- * @example
- * ```typescript
- * // Dispatch from a button component
- * eventBus.dispatch(FormResetEvent);
- * ```
+ * @module path-utils
+ */
+/**
+ * Parses an array derivation path into its components.
+ *
+ * Array paths use the `$` placeholder to represent "any index".
+ * Format: "arrayPath.$.relativePath"
+ *
+ * @param path - The path to parse (e.g., "items.$.quantity")
+ * @returns Parsed path info with arrayPath and relativePath
  *
  * @example
  * ```typescript
- * // Listen for reset events
- * eventBus.on<FormResetEvent>('form-reset').subscribe(() => {
- *   console.log('Form was reset to defaults');
- * });
+ * parseArrayPath('items.$.quantity')
+ * // { arrayPath: 'items', relativePath: 'quantity', isArrayPath: true }
+ *
+ * parseArrayPath('orders.lineItems.$.total')
+ * // { arrayPath: 'orders.lineItems', relativePath: 'total', isArrayPath: true }
+ *
+ * parseArrayPath('simpleField')
+ * // { arrayPath: '', relativePath: '', isArrayPath: false }
  * ```
+ *
+ * @public
  */
-class FormResetEvent {
-    type = 'form-reset';
+function parseArrayPath(path) {
+    const ARRAY_PLACEHOLDER = '.$.';
+    const placeholderIndex = path.indexOf(ARRAY_PLACEHOLDER);
+    if (placeholderIndex === -1) {
+        return {
+            arrayPath: '',
+            relativePath: '',
+            isArrayPath: false,
+        };
+    }
+    return {
+        arrayPath: path.substring(0, placeholderIndex),
+        relativePath: path.substring(placeholderIndex + ARRAY_PLACEHOLDER.length),
+        isArrayPath: true,
+    };
 }
-
 /**
- * Event dispatched when the form should be cleared.
+ * Resolves an array placeholder path to a concrete indexed path.
  *
- * This event instructs the dynamic form component to clear all field values,
- * resetting them to empty/undefined state regardless of their default values.
+ * @param path - The path with $ placeholder (e.g., "items.$.quantity")
+ * @param index - The array index to substitute
+ * @returns Resolved path with index (e.g., "items.0.quantity")
  *
  * @example
  * ```typescript
- * // Dispatch from a button component
- * eventBus.dispatch(FormClearEvent);
+ * resolveArrayPath('items.$.quantity', 2)
+ * // 'items.2.quantity'
+ *
+ * resolveArrayPath('orders.lineItems.$.total', 0)
+ * // 'orders.lineItems.0.total'
  * ```
  *
- * @example
- * ```typescript
- * // Listen for clear events
- * eventBus.on<FormClearEvent>('form-clear').subscribe(() => {
- *   console.log('Form was cleared');
+ * @public
+ */
+function resolveArrayPath(path, index) {
+    const info = parseArrayPath(path);
+    if (!info.isArrayPath) {
+        return path;
+    }
+    return `${info.arrayPath}.${index}.${info.relativePath}`;
+}
+/**
+ * Checks if a path contains an array placeholder.
+ *
+ * @param path - The path to check
+ * @returns True if the path contains .$.
+ *
+ * @public
+ */
+function isArrayPlaceholderPath(path) {
+    return path.includes('.$.');
+}
+/**
+ * Extracts the array path from a path that may contain an array placeholder.
+ *
+ * @param path - The path to extract from
+ * @returns The array path, or empty string if not an array path
+ *
+ * @example
+ * ```typescript
+ * extractArrayPath('items.$.quantity')
+ * // 'items'
+ *
+ * extractArrayPath('orders.lineItems.$.total')
+ * // 'orders.lineItems'
+ *
+ * extractArrayPath('simpleField')
+ * // ''
+ * ```
+ *
+ * @public
+ */
+function extractArrayPath(path) {
+    return parseArrayPath(path).arrayPath;
+}
+/**
+ * Splits a path into segments, supporting both dot notation and bracket notation.
+ *
+ * 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
+ *
+ * @example
+ * ```typescript
+ * splitPath('parent.child.grandchild')
+ * // ['parent', 'child', 'grandchild']
+ *
+ * splitPath('items.0.quantity')
+ * // ['items', '0', 'quantity']
+ *
+ * splitPath('items[0].quantity')
+ * // ['items', '0', 'quantity']
+ *
+ * splitPath('a[0][1].b')
+ * // ['a', '0', '1', 'b']
+ * ```
+ *
+ * @public
+ */
+function splitPath(path) {
+    if (!path)
+        return [];
+    // 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.
+ *
+ * @param segments - The path segments to join
+ * @returns Joined path string
+ *
+ * @public
+ */
+function joinPath(segments) {
+    return segments.join('.');
+}
+/**
+ * Gets the parent path from a nested path.
+ *
+ * @param path - The path to get parent from
+ * @returns The parent path, or empty string if no parent
+ *
+ * @example
+ * ```typescript
+ * getParentPath('parent.child.grandchild')
+ * // 'parent.child'
+ *
+ * getParentPath('topLevel')
+ * // ''
+ * ```
+ *
+ * @public
+ */
+function getParentPath(path) {
+    const segments = splitPath(path);
+    if (segments.length <= 1)
+        return '';
+    return joinPath(segments.slice(0, -1));
+}
+/**
+ * Gets the last segment (leaf) from a path.
+ *
+ * @param path - The path to get leaf from
+ * @returns The last segment
+ *
+ * @example
+ * ```typescript
+ * getLeafPath('parent.child.grandchild')
+ * // 'grandchild'
+ *
+ * getLeafPath('topLevel')
+ * // 'topLevel'
+ * ```
+ *
+ * @public
+ */
+function getLeafPath(path) {
+    const segments = splitPath(path);
+    return segments[segments.length - 1] ?? '';
+}
+/**
+ * Parses a path that may contain multiple array placeholders.
+ *
+ * This supports deeply nested array structures like `orders.$.items.$.quantity`
+ * where multiple levels of arrays need to be traversed.
+ *
+ * @param path - Path with zero or more $ placeholders
+ * @returns Parsed path information
+ *
+ * @example
+ * ```typescript
+ * parseMultiArrayPath('orders.$.items.$.quantity')
+ * // {
+ * //   isArrayPath: true,
+ * //   placeholderCount: 2,
+ * //   segments: ['orders', 'items', 'quantity'],
+ * //   placeholderPositions: [1, 3]
+ * // }
+ *
+ * parseMultiArrayPath('items.$.name')
+ * // {
+ * //   isArrayPath: true,
+ * //   placeholderCount: 1,
+ * //   segments: ['items', 'name'],
+ * //   placeholderPositions: [1]
+ * // }
+ *
+ * parseMultiArrayPath('simpleField')
+ * // {
+ * //   isArrayPath: false,
+ * //   placeholderCount: 0,
+ * //   segments: ['simpleField'],
+ * //   placeholderPositions: []
+ * // }
+ * ```
+ *
+ * @public
+ */
+function parseMultiArrayPath(path) {
+    const parts = path.split('.');
+    const segments = [];
+    const placeholderPositions = [];
+    for (let i = 0; i < parts.length; i++) {
+        if (parts[i] === '$') {
+            placeholderPositions.push(i);
+        }
+        else {
+            segments.push(parts[i]);
+        }
+    }
+    return {
+        isArrayPath: placeholderPositions.length > 0,
+        placeholderCount: placeholderPositions.length,
+        segments,
+        placeholderPositions,
+    };
+}
+/**
+ * Resolves a path with multiple array placeholders using provided indices.
+ *
+ * Each `$` placeholder is replaced with the corresponding index from the
+ * indices array, in order.
+ *
+ * @param path - Path with $ placeholders (e.g., 'orders.$.items.$.quantity')
+ * @param indices - Array of indices to substitute (e.g., [0, 2])
+ * @returns Resolved path (e.g., 'orders.0.items.2.quantity')
+ *
+ * @throws Error if number of indices doesn't match number of placeholders
+ *
+ * @example
+ * ```typescript
+ * resolveMultiArrayPath('orders.$.items.$.quantity', [0, 2])
+ * // 'orders.0.items.2.quantity'
+ *
+ * resolveMultiArrayPath('items.$.name', [5])
+ * // 'items.5.name'
+ * ```
+ *
+ * @public
+ */
+function resolveMultiArrayPath(path, indices) {
+    const parts = path.split('.');
+    let indexPointer = 0;
+    const resolved = parts.map((part) => {
+        if (part === '$') {
+            if (indexPointer >= indices.length) {
+                throw new Error(`Not enough indices provided for path '${path}'. ` +
+                    `Expected ${parts.filter((p) => p === '$').length} indices, got ${indices.length}.`);
+            }
+            return String(indices[indexPointer++]);
+        }
+        return part;
+    });
+    if (indexPointer < indices.length) {
+        throw new Error(`Too many indices provided for path '${path}'. ` + `Expected ${indexPointer} indices, got ${indices.length}.`);
+    }
+    return resolved.join('.');
+}
+/**
+ * Counts the number of array placeholders in a path.
+ *
+ * @param path - The path to analyze
+ * @returns Number of $ placeholders in the path
+ *
+ * @example
+ * ```typescript
+ * countArrayPlaceholders('orders.$.items.$.quantity')
+ * // 2
+ *
+ * countArrayPlaceholders('items.$.name')
+ * // 1
+ *
+ * countArrayPlaceholders('simpleField')
+ * // 0
+ * ```
+ *
+ * @public
+ */
+function countArrayPlaceholders(path) {
+    return path.split('.').filter((part) => part === '$').length;
+}
+
+/**
+ * Provides lazy-computed lookup maps for derivation entries.
+ *
+ * Instead of pre-computing all lookup maps at collection time (which caused
+ * hidden mutation and bloated the DerivationCollection god object), this class
+ * computes maps lazily on first access and caches them.
+ *
+ * @example
+ * ```typescript
+ * const lookup = inject(DerivationLookup);
+ *
+ * // Lazy-computed on first access
+ * const entriesForQuantity = lookup.byDependency.get('quantity');
+ * const onChangeEntries = lookup.getOnChangeEntries();
+ * ```
+ */
+class DerivationLookup {
+    entriesSignal = inject(DERIVATION_ENTRIES);
+    // Track the entries array reference to auto-invalidate on change
+    _cachedEntriesRef;
+    // Cached lookup maps (built lazily on first access)
+    _byField;
+    _byDependency;
+    _byArrayPath;
+    _wildcardEntries;
+    _onChangeEntries;
+    _debouncedEntriesByMs;
+    /**
+     * Current derivation entries (from signal).
+     * Auto-invalidates cache if entries reference changed.
+     */
+    get entries() {
+        const currentEntries = this.entriesSignal();
+        // Auto-invalidate if entries reference changed (schema was updated)
+        if (this._cachedEntriesRef !== currentEntries) {
+            this.invalidateCache();
+            this._cachedEntriesRef = currentEntries;
+        }
+        return currentEntries;
+    }
+    /**
+     * 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 byField() {
+        return (this._byField ??= this.buildByFieldMap());
+    }
+    /**
+     * Map of dependency field key to entries that depend on it.
+     * Used for efficient O(1) lookup when filtering by changed fields.
+     */
+    get byDependency() {
+        return (this._byDependency ??= this.buildByDependencyMap());
+    }
+    /**
+     * Map of array path to entries that derive array item values.
+     * Used for O(1) lookup when an array field changes.
+     */
+    get byArrayPath() {
+        return (this._byArrayPath ??= this.buildByArrayPathMap());
+    }
+    /**
+     * Entries that have wildcard (*) dependency.
+     * These entries depend on all form values and must always be considered.
+     */
+    get wildcardEntries() {
+        return (this._wildcardEntries ??= this.buildWildcardEntries());
+    }
+    /**
+     * Gets entries that should be processed based on changed fields.
+     *
+     * Handles nested path matching: if 'address' changed, entries depending on
+     * 'address.city' will also be included (parent change implies child changed).
+     *
+     * Uses O(k) lookup via indexed maps for exact matches, plus O(d) scan for
+     * nested dependencies, where k = changed fields, d = unique dependencies.
+     */
+    getEntriesForChangedFields(changedFields) {
+        const entrySet = new Set();
+        // Add entries triggered by each changed field via byDependency map
+        for (const fieldKey of changedFields) {
+            const entries = this.byDependency.get(fieldKey);
+            if (entries) {
+                for (const entry of entries) {
+                    entrySet.add(entry);
+                }
+            }
+            // Check if this changed field is an array path - O(1) lookup
+            const arrayEntries = this.byArrayPath.get(fieldKey);
+            if (arrayEntries) {
+                for (const entry of arrayEntries) {
+                    entrySet.add(entry);
+                }
+            }
+            // Handle nested dependencies: if 'address' changed, include entries
+            // that depend on 'address.city', 'address.street', etc.
+            // This is O(d) where d = number of unique dependency keys in the map.
+            const fieldKeyPrefix = fieldKey + '.';
+            for (const [depKey, depEntries] of this.byDependency) {
+                if (depKey.startsWith(fieldKeyPrefix)) {
+                    for (const entry of depEntries) {
+                        entrySet.add(entry);
+                    }
+                }
+            }
+        }
+        // Add all wildcard entries - O(w) where w = number of wildcard entries
+        for (const entry of this.wildcardEntries) {
+            entrySet.add(entry);
+        }
+        return Array.from(entrySet);
+    }
+    /**
+     * Gets entries with trigger 'onChange' (or no trigger, which defaults to onChange).
+     */
+    getOnChangeEntries() {
+        return (this._onChangeEntries ??= this.entries.filter((e) => e.trigger !== 'debounced'));
+    }
+    /**
+     * Gets entries with trigger 'debounced' for a specific debounce period.
+     */
+    getDebouncedEntries(debounceMs) {
+        if (!this._debouncedEntriesByMs) {
+            this._debouncedEntriesByMs = this.buildDebouncedEntriesMap();
+        }
+        return this._debouncedEntriesByMs.get(debounceMs) ?? [];
+    }
+    /**
+     * Gets all unique debounce periods that have entries.
+     */
+    getDebouncePeriods() {
+        if (!this._debouncedEntriesByMs) {
+            this._debouncedEntriesByMs = this.buildDebouncedEntriesMap();
+        }
+        return Array.from(this._debouncedEntriesByMs.keys());
+    }
+    /**
+     * Invalidates cached maps. Call this when entries change.
+     */
+    invalidateCache() {
+        this._byField = undefined;
+        this._byDependency = undefined;
+        this._byArrayPath = undefined;
+        this._wildcardEntries = undefined;
+        this._onChangeEntries = undefined;
+        this._debouncedEntriesByMs = undefined;
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Private builders
+    // ─────────────────────────────────────────────────────────────────
+    buildByFieldMap() {
+        const map = new Map();
+        for (const entry of this.entries) {
+            const fieldEntries = map.get(entry.fieldKey) ?? [];
+            fieldEntries.push(entry);
+            map.set(entry.fieldKey, fieldEntries);
+        }
+        return map;
+    }
+    buildByDependencyMap() {
+        const map = new Map();
+        for (const entry of this.entries) {
+            for (const dep of entry.dependsOn) {
+                if (dep !== '*') {
+                    const depEntries = map.get(dep) ?? [];
+                    depEntries.push(entry);
+                    map.set(dep, depEntries);
+                }
+            }
+        }
+        return map;
+    }
+    buildByArrayPathMap() {
+        const map = new Map();
+        for (const entry of this.entries) {
+            if (isArrayPlaceholderPath(entry.fieldKey)) {
+                const arrayPath = extractArrayPath(entry.fieldKey);
+                if (arrayPath) {
+                    const arrayEntries = map.get(arrayPath) ?? [];
+                    arrayEntries.push(entry);
+                    map.set(arrayPath, arrayEntries);
+                }
+            }
+        }
+        return map;
+    }
+    buildWildcardEntries() {
+        return this.entries.filter((entry) => entry.dependsOn.includes('*'));
+    }
+    buildDebouncedEntriesMap() {
+        const map = new Map();
+        for (const entry of this.entries) {
+            if (entry.trigger === 'debounced') {
+                const ms = entry.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+                const group = map.get(ms) ?? [];
+                group.push(entry);
+                map.set(ms, group);
+            }
+        }
+        return map;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: DerivationLookup, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: DerivationLookup });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.0", ngImport: i0, type: DerivationLookup, decorators: [{
+            type: Injectable
+        }] });
+
+/**
+ * Sorts derivation entries in topological order based on their dependencies.
+ *
+ * This ensures that derivations are processed in the correct order:
+ * if derivation B depends on field A, and derivation A->A' modifies A,
+ * then A->A' is processed before B.
+ *
+ * Uses Kahn's algorithm for topological sorting, which also provides
+ * natural handling of entries with no dependencies (they come first).
+ *
+ * @param entries - The derivation entries to sort
+ * @returns A new array of entries in topological order
+ *
+ * @example
+ * ```typescript
+ * // Given derivations:
+ * // 1. quantity -> lineTotal (depends on quantity, unitPrice)
+ * // 2. unitPrice -> lineTotal (depends on quantity, unitPrice)
+ * // 3. lineTotal -> grandTotal (depends on lineTotal)
+ * //
+ * // Topological sort ensures lineTotal is computed before grandTotal
+ * const sorted = topologicalSort(entries);
+ * // Result: [1, 2, 3] - derivations that produce lineTotal come before
+ * // those that consume it
+ * ```
+ *
+ * @public
+ */
+function topologicalSort(entries) {
+    if (entries.length <= 1) {
+        return [...entries];
+    }
+    // Build adjacency list and in-degree count
+    // An edge A -> B exists if B depends on the target of A
+    const graph = new Map();
+    const inDegree = new Map();
+    // Initialize
+    for (const entry of entries) {
+        graph.set(entry, new Set());
+        inDegree.set(entry, 0);
+    }
+    // Pre-build index: field key -> entries that produce/target it
+    // This enables O(1) lookup instead of O(n) scanning
+    const derivationsByField = new Map();
+    for (const entry of entries) {
+        // 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.fieldKey.includes('.$.')) {
+            const relativePath = entry.fieldKey.split('.$.')[1];
+            if (relativePath) {
+                const relativeEntries = derivationsByField.get(relativePath) ?? [];
+                relativeEntries.push(entry);
+                derivationsByField.set(relativePath, relativeEntries);
+            }
+        }
+    }
+    // Collect entries with wildcard dependencies (need special handling)
+    const wildcardDependents = [];
+    for (const entry of entries) {
+        if (entry.dependsOn.includes('*')) {
+            wildcardDependents.push(entry);
+        }
+    }
+    // Build edges using pre-computed index
+    // 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 derivations that produce this dependency
+            const producers = derivationsByField.get(dep);
+            if (producers) {
+                for (const entryA of producers) {
+                    const entryAEdges = graph.get(entryA);
+                    if (entryA !== entryB && entryAEdges && !entryAEdges.has(entryB)) {
+                        entryAEdges.add(entryB);
+                        inDegree.set(entryB, (inDegree.get(entryB) ?? 0) + 1);
+                    }
+                }
+            }
+        }
+    }
+    // Handle wildcard dependencies: they depend on ALL producers
+    for (const entryB of wildcardDependents) {
+        for (const entryA of entries) {
+            const entryAEdges = graph.get(entryA);
+            if (entryA !== entryB && entryAEdges && !entryAEdges.has(entryB)) {
+                entryAEdges.add(entryB);
+                inDegree.set(entryB, (inDegree.get(entryB) ?? 0) + 1);
+            }
+        }
+    }
+    // Kahn's algorithm: process nodes with in-degree 0
+    const queue = [];
+    const sorted = [];
+    // Start with entries that have no dependencies on other derivation outputs
+    for (const entry of entries) {
+        if (inDegree.get(entry) === 0) {
+            queue.push(entry);
+        }
+    }
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current)
+            break; // TypeScript guard (shouldn't happen due to while condition)
+        sorted.push(current);
+        // Reduce in-degree for all neighbors
+        const neighbors = graph.get(current) ?? new Set();
+        for (const neighbor of neighbors) {
+            const newDegree = (inDegree.get(neighbor) ?? 0) - 1;
+            inDegree.set(neighbor, newDegree);
+            if (newDegree === 0) {
+                queue.push(neighbor);
+            }
+        }
+    }
+    // If we couldn't sort all entries, there's a cycle
+    // (but cycles should be caught by cycle-detector, so this is defensive)
+    if (sorted.length !== entries.length) {
+        // Return original order for entries in cycles
+        const sortedSet = new Set(sorted);
+        for (const entry of entries) {
+            if (!sortedSet.has(entry)) {
+                sorted.push(entry);
+            }
+        }
+    }
+    return sorted;
+}
+
+/**
+ * Collects all derivation entries from field definitions.
+ *
+ * This function traverses the field definition tree and extracts:
+ * - Shorthand `derivation` properties on fields
+ * - Full `logic` array entries with `type: 'derivation'`
+ *
+ * The collected entries include dependency information for cycle detection
+ * and reactive evaluation. Entries are sorted topologically so derivations
+ * are processed in dependency order.
+ *
+ * Lookup maps (byTarget, byDependency, etc.) are NOT built here - they are
+ * computed lazily via {@link DerivationLookup} to avoid hidden mutation
+ * and reduce the size of the returned collection.
+ *
+ * @param fields - Array of field definitions to traverse
+ * @returns Collection containing sorted derivation entries
+ *
+ * @example
+ * ```typescript
+ * const fields = [
+ *   { key: 'quantity', type: 'number' },
+ *   { key: 'unitPrice', type: 'number' },
+ *   {
+ *     key: 'total',
+ *     type: 'number',
+ *     derivation: 'formValue.quantity * formValue.unitPrice',
+ *   },
+ * ];
+ *
+ * const collection = collectDerivations(fields);
+ * // collection.entries has 1 entry for the 'total' field derivation
+ * ```
+ *
+ * @public
+ */
+function collectDerivations(fields) {
+    const entries = [];
+    const context = {};
+    traverseFields(fields, entries, context);
+    // 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.
+    const sortedEntries = topologicalSort(entries);
+    return { entries: sortedEntries };
+}
+/**
+ * Recursively traverses field definitions to collect 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 };
+            // Update array path context if this is an array field
+            if (field.type === 'array') {
+                childContext.arrayPath = field.key;
+            }
+            traverseFields(normalizeFieldsArray(field.fields), entries, childContext);
+        }
+    }
+}
+/**
+ * Collects derivation entries from a single field.
+ *
+ * @internal
+ */
+function collectFromField(field, entries, context) {
+    const fieldKey = field.key;
+    if (!fieldKey)
+        return;
+    const validationField = field;
+    // Collect shorthand derivation property
+    if (validationField.derivation) {
+        const entry = createShorthandEntry(fieldKey, validationField.derivation, context);
+        entries.push(entry);
+    }
+    // Collect logic array derivations
+    if (validationField.logic) {
+        for (const logicConfig of validationField.logic) {
+            if (isDerivationLogicConfig(logicConfig)) {
+                const entry = createLogicEntry(fieldKey, logicConfig, context);
+                entries.push(entry);
+            }
+        }
+    }
+}
+/**
+ * Creates a derivation entry from the shorthand `derivation` property.
+ *
+ * Shorthand derivations:
+ * - 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, context) {
+    // Build the effective field key, including array path if in array context
+    const effectiveFieldKey = context.arrayPath ? `${context.arrayPath}.$.${fieldKey}` : fieldKey;
+    return {
+        fieldKey: effectiveFieldKey,
+        dependsOn: extractStringDependencies(expression),
+        condition: true,
+        expression,
+        trigger: 'onChange',
+        isShorthand: true,
+    };
+}
+/**
+ * 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
+ * - Array field context for placeholder paths
+ * - Multiple value source types (static, expression, function)
+ * - Trigger and debounce configuration
+ *
+ * @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 dependsOn = extractDependencies(config);
+    const condition = config.condition ?? true;
+    const trigger = config.trigger ?? 'onChange';
+    // Extract debounceMs from debounced configs
+    // The type system ensures debounceMs is only present when trigger is 'debounced'
+    const debounceMs = trigger === 'debounced' ? config.debounceMs : undefined;
+    return {
+        fieldKey: effectiveFieldKey,
+        dependsOn,
+        condition,
+        value: config.value,
+        expression: config.expression,
+        functionName: config.functionName,
+        trigger,
+        debounceMs,
+        isShorthand: false,
+        originalConfig: config,
+        debugName: config.debugName,
+    };
+}
+/**
+ * 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(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.
+ *
+ * Uses Kahn's algorithm variant with DFS to detect cycles.
+ * Bidirectional sync patterns (A→B→A) are allowed because they stabilize
+ * via the equality check at runtime.
+ *
+ * @param collection - The collected derivation entries
+ * @returns Result indicating whether a cycle exists and details if found
+ *
+ * @example
+ * ```typescript
+ * const collection = collectDerivations(fields);
+ * const result = detectCycles(collection);
+ *
+ * if (result.hasCycle) {
+ *   console.error(`Cycle detected: ${result.cyclePath?.join(' -> ')}`);
+ *   throw new Error(result.errorMessage);
+ * }
+ * ```
+ *
+ * @public
+ */
+function detectCycles(collection) {
+    // Build directed graph from derivation entries
+    const graph = buildDependencyGraph(collection);
+    // No entries means no cycles
+    if (graph.size === 0) {
+        return { hasCycle: false };
+    }
+    // Build bidirectional pairs set for cycle exemption
+    const bidirectionalPairs = detectBidirectionalPairs(collection);
+    // Run DFS to detect cycles
+    const result = detectCyclesWithDFS(graph, bidirectionalPairs);
+    // Include bidirectional pairs in result for warnings
+    if (bidirectionalPairs.size > 0) {
+        result.bidirectionalPairs = Array.from(bidirectionalPairs);
+    }
+    return result;
+}
+/**
+ * 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
+ * comparison with no tolerance. This means:
+ *
+ * - **Integer math**: Safe (e.g., `A = B * 2`, `B = A / 2` where A is even)
+ * - **Floating-point math**: May oscillate due to rounding errors
+ *
+ * For currency conversions or other floating-point operations, consider:
+ * 1. Rounding values in your expression (e.g., `Math.round(value * 100) / 100`)
+ * 2. Using integer cents instead of decimal dollars
+ * 3. Using one-way derivation instead of bidirectional
+ *
+ * @example
+ * ```typescript
+ * // 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();
+    // Build a map of fieldKey -> dependencies (other fields this derivation reads from)
+    const dependencyMap = new Map();
+    for (const entry of collection.entries) {
+        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 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;
+}
+/**
+ * Checks if a cycle path represents a bidirectional pair.
+ *
+ * @internal
+ */
+function isBidirectionalCycle(cyclePath, bidirectionalPairs) {
+    // Bidirectional cycles are exactly: [A, B, A] (length 3 with first=last)
+    if (cyclePath.length !== 3) {
+        return false;
+    }
+    const [first, second, third] = cyclePath;
+    if (first !== third) {
+        return false;
+    }
+    // Check if this pair is in our bidirectional set
+    const pairKey = first < second ? `${first}↔${second}` : `${second}↔${first}`;
+    return bidirectionalPairs.has(pairKey);
+}
+/**
+ * Builds a dependency graph from derivation entries.
+ *
+ * Creates nodes for each field involved in derivations and
+ * edges representing the derivation dependencies.
+ *
+ * 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
+ */
+function buildDependencyGraph(collection) {
+    const graph = new Map();
+    // Helper to ensure a node exists
+    const ensureNode = (fieldKey) => {
+        let node = graph.get(fieldKey);
+        if (!node) {
+            node = {
+                fieldKey,
+                dependsOn: new Set(),
+                dependedOnBy: new Set(),
+            };
+            graph.set(fieldKey, node);
+        }
+        return node;
+    };
+    for (const entry of collection.entries) {
+        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) {
+            // Skip wildcard dependencies and self-references
+            if (dep !== '*' && dep !== entry.fieldKey) {
+                const depNode = ensureNode(dep);
+                // The field depends on 'dep'
+                fieldNode.dependsOn.add(dep);
+                // 'dep' is depended on by the field
+                depNode.dependedOnBy.add(entry.fieldKey);
+            }
+        }
+    }
+    return graph;
+}
+/**
+ * Detects cycles using depth-first search.
+ *
+ * Uses three-color marking:
+ * - Unvisited (white): Not yet processed
+ * - InProgress (gray): Currently in the DFS stack
+ * - Completed (black): Fully processed
+ *
+ * A cycle is detected when we visit a node that's InProgress,
+ * unless it's a bidirectional sync pattern (allowed).
+ *
+ * @internal
+ */
+function detectCyclesWithDFS(graph, bidirectionalPairs) {
+    const visitState = new Map();
+    const parent = new Map();
+    // Initialize all nodes as unvisited
+    for (const fieldKey of graph.keys()) {
+        visitState.set(fieldKey, 0 /* VisitState.Unvisited */);
+    }
+    // Process each unvisited node
+    for (const fieldKey of graph.keys()) {
+        if (visitState.get(fieldKey) === 0 /* VisitState.Unvisited */) {
+            const cycleResult = dfsVisit(fieldKey, graph, visitState, parent, [], bidirectionalPairs);
+            if (cycleResult) {
+                return cycleResult;
+            }
+        }
+    }
+    return { hasCycle: false };
+}
+/**
+ * DFS visit function that detects back edges (cycles).
+ *
+ * @internal
+ */
+function dfsVisit(fieldKey, graph, visitState, parent, path, bidirectionalPairs) {
+    visitState.set(fieldKey, 1 /* VisitState.InProgress */);
+    path.push(fieldKey);
+    const node = graph.get(fieldKey);
+    if (!node) {
+        visitState.set(fieldKey, 2 /* VisitState.Completed */);
+        path.pop();
+        return null;
+    }
+    // Check all nodes that this field's changes would trigger
+    for (const targetFieldKey of node.dependedOnBy) {
+        const targetState = visitState.get(targetFieldKey);
+        if (targetState === 1 /* VisitState.InProgress */) {
+            // Back edge found - potential cycle
+            const cyclePath = extractCyclePath(path, targetFieldKey);
+            // Allow bidirectional sync patterns (A→B→A)
+            // These stabilize via equality checks at runtime
+            if (isBidirectionalCycle(cyclePath, bidirectionalPairs)) {
+                // Continue DFS without reporting this as a cycle
+                continue;
+            }
+            return {
+                hasCycle: true,
+                cyclePath,
+                errorMessage: formatCycleError(cyclePath),
+            };
+        }
+        if (targetState === 0 /* VisitState.Unvisited */) {
+            parent.set(targetFieldKey, fieldKey);
+            const result = dfsVisit(targetFieldKey, graph, visitState, parent, path, bidirectionalPairs);
+            if (result) {
+                return result;
+            }
+        }
+    }
+    visitState.set(fieldKey, 2 /* VisitState.Completed */);
+    path.pop();
+    return null;
+}
+/**
+ * Extracts the cycle path from the DFS path.
+ *
+ * @internal
+ */
+function extractCyclePath(path, cycleStart) {
+    const cycleStartIndex = path.indexOf(cycleStart);
+    if (cycleStartIndex === -1) {
+        // Shouldn't happen, but handle gracefully
+        return [...path, cycleStart];
+    }
+    // Extract from cycle start to current position, then back to start
+    const cyclePath = path.slice(cycleStartIndex);
+    cyclePath.push(cycleStart); // Close the cycle
+    return cyclePath;
+}
+/**
+ * Formats a human-readable error message for a detected cycle.
+ *
+ * @internal
+ */
+function formatCycleError(cyclePath) {
+    const pathStr = cyclePath.join(' -> ');
+    return (`Derivation cycle detected: ${pathStr}\n` +
+        `This would cause an infinite loop at runtime. ` +
+        `Remove one of the derivations to break the cycle.`);
+}
+/**
+ * Validates a derivation collection and throws if cycles are detected.
+ *
+ * This is the main entry point for cycle validation during form initialization.
+ * Should be called after collecting derivations and before setting up effects.
+ *
+ * In dev mode, logs a warning when bidirectional derivation pairs are detected.
+ * These patterns are allowed but may oscillate with floating-point values.
+ *
+ * @param collection - The collected derivation entries to validate
+ * @param logger - Optional logger for dev-mode warnings
+ * @throws Error if a cycle is detected, with details about the cycle
+ *
+ * @example
+ * ```typescript
+ * const collection = collectDerivations(fields);
+ *
+ * // This will throw if cycles exist
+ * validateNoCycles(collection, logger);
+ *
+ * // Safe to set up derivation effects now
+ * setupDerivationEffects(collection);
+ * ```
+ *
+ * @public
+ */
+function validateNoCycles(collection, logger) {
+    const result = detectCycles(collection);
+    if (result.hasCycle) {
+        throw new Error(result.errorMessage);
+    }
+    // Warn about bidirectional patterns in dev mode
+    if (isDevMode() && result.bidirectionalPairs && result.bidirectionalPairs.length > 0 && logger) {
+        logger.warn('[Derivation] Bidirectional derivation patterns detected. ' +
+            'These patterns stabilize via equality checks, but may oscillate with floating-point values ' +
+            '(e.g., currency conversions with rounding). ' +
+            'Consider adding tolerance-based comparisons for numeric values.', result.bidirectionalPairs);
+    }
+}
+
+/**
+ * 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.
+ *
+ * This function processes derivations in order, evaluating conditions
+ * and computing values. It handles loop prevention through:
+ * 1. Chain tracking (prevents same derivation from running twice in one cycle)
+ * 2. Value equality checks (skips if target already has computed value)
+ * 3. Max iteration limit (safety fallback)
+ *
+ * @param collection - The collected derivation entries
+ * @param context - Context for applying derivations
+ * @param changedFields - Set of field keys that changed (for filtering)
+ * @returns Result of the derivation processing
+ *
+ * @example
+ * ```typescript
+ * const result = applyDerivations(collection, {
+ *   formValue: formValueSignal,
+ *   rootForm: form(),
+ *   derivationFunctions: customFnConfig?.derivations,
+ *   logger: inject(DynamicFormLogger),
+ * });
+ *
+ * if (result.maxIterationsReached) {
+ *   console.warn('Possible derivation loop detected');
+ * }
+ * ```
+ *
+ * @public
+ */
+function applyDerivations(collection, context, changedFields) {
+    const chainContext = createDerivationChainContext();
+    const { derivationLogger } = context;
+    const maxIterations = context.maxIterations ?? MAX_DERIVATION_ITERATIONS;
+    let appliedCount = 0;
+    let skippedCount = 0;
+    let errorCount = 0;
+    let warnCount = 0;
+    // Filter entries based on changed fields
+    const entriesToProcess = changedFields ? getEntriesForChangedFields(collection.entries, changedFields) : collection.entries;
+    // Log cycle start in verbose mode
+    derivationLogger.cycleStart('onChange', entriesToProcess.length);
+    // Process derivations iteratively until no more changes
+    let hasChanges = true;
+    while (hasChanges && chainContext.iteration < maxIterations) {
+        chainContext.iteration++;
+        hasChanges = false;
+        // Log iteration in verbose mode
+        derivationLogger.iteration(chainContext.iteration);
+        for (const entry of entriesToProcess) {
+            const result = tryApplyDerivation(entry, context, chainContext);
+            if (result.applied) {
+                appliedCount++;
+                hasChanges = true;
+            }
+            else if (result.error) {
+                errorCount++;
+            }
+            else if (result.warning) {
+                warnCount++;
+                skippedCount++;
+            }
+            else {
+                skippedCount++;
+            }
+        }
+    }
+    // Build result
+    const processingResult = {
+        appliedCount,
+        skippedCount,
+        errorCount,
+        warnCount,
+        iterations: chainContext.iteration,
+        maxIterationsReached: chainContext.iteration >= maxIterations,
+    };
+    if (processingResult.maxIterationsReached) {
+        derivationLogger.maxIterationsReached(processingResult, 'onChange');
+    }
+    // Log summary
+    derivationLogger.summary(processingResult, 'onChange');
+    return processingResult;
+}
+/**
+ * Gets entries that should be processed based on changed fields.
+ *
+ * Filters entries by checking if any of their dependencies are in the changed fields set.
+ * Also includes all wildcard (*) entries since they depend on any form change.
+ *
+ * Note: For optimal O(k) performance where k = changed fields count, use
+ * DerivationLookup.getEntriesForChangedFields() which uses pre-built indexes.
+ *
+ * @internal
+ */
+function getEntriesForChangedFields(entries, changedFields) {
+    return entries.filter((entry) => {
+        // Wildcard entries are always included
+        if (entry.dependsOn.includes('*')) {
+            return true;
+        }
+        // Check if any dependency is in changed fields
+        return entry.dependsOn.some((dep) => changedFields.has(dep));
+    });
+}
+/**
+ * Attempts to apply a single derivation.
+ *
+ * **Important:** When a derivation's condition evaluates to `false`, the previously
+ * derived value is NOT automatically cleared. If you need to reset a field when a
+ * condition becomes false, use a separate derivation with an inverted condition
+ * that sets the desired fallback value.
+ *
+ * @example
+ * ```typescript
+ * // Two derivations for conditional value with cleanup:
+ * // When country is USA, set phonePrefix to '+1'
+ * { key: 'phonePrefix', logic: [{ type: 'derivation', condition: { field: 'country', operator: '==', value: 'USA' }, value: '+1' }] }
+ * // When country is NOT USA, clear phonePrefix
+ * { key: 'phonePrefix', logic: [{ type: 'derivation', condition: { field: 'country', operator: '!=', value: 'USA' }, value: '' }] }
+ * ```
+ *
+ * @internal
+ */
+function tryApplyDerivation(entry, context, chainContext) {
+    const { derivationLogger } = context;
+    // Check if this is an array field derivation (has '$' placeholder)
+    if (isArrayPlaceholderPath(entry.fieldKey)) {
+        return tryApplyArrayDerivation(entry, context, chainContext);
+    }
+    const derivationKey = createDerivationKey(entry.fieldKey);
+    // Check if already applied in this cycle
+    if (chainContext.appliedDerivations.has(derivationKey)) {
+        derivationLogger.evaluation({
+            debugName: entry.debugName,
+            fieldKey: entry.fieldKey,
+            result: 'skipped',
+            skipReason: 'already-applied',
+        });
+        return { applied: false, fieldKey: entry.fieldKey };
+    }
+    // Create evaluation context
+    const formValue = untracked(() => context.formValue());
+    const evalContext = createEvaluationContext(entry, formValue, context);
+    // Evaluate condition
+    if (!evaluateDerivationCondition(entry.condition, evalContext)) {
+        derivationLogger.evaluation({
+            debugName: entry.debugName,
+            fieldKey: entry.fieldKey,
+            result: 'skipped',
+            skipReason: 'condition-false',
+        });
+        return { applied: false, fieldKey: entry.fieldKey };
+    }
+    // Compute derived value
+    let newValue;
+    try {
+        newValue = computeDerivedValue(entry, evalContext, context);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        context.logger.error(formatDerivationError(entry, 'compute', errorMessage));
+        derivationLogger.evaluation({
+            debugName: entry.debugName,
+            fieldKey: entry.fieldKey,
+            result: 'error',
+            error: errorMessage,
+        });
+        return {
+            applied: false,
+            fieldKey: entry.fieldKey,
+            error: errorMessage,
+        };
+    }
+    // Check if value actually changed using exact equality.
+    // Note: This uses isEqual which performs deep comparison with exact IEEE 754
+    // 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.fieldKey);
+    if (isEqual(currentValue, newValue)) {
+        derivationLogger.evaluation({
+            debugName: entry.debugName,
+            fieldKey: entry.fieldKey,
+            result: 'skipped',
+            skipReason: 'value-unchanged',
+        });
+        return { applied: false, fieldKey: entry.fieldKey };
+    }
+    // Apply the value
+    try {
+        const wasApplied = applyValueToForm(entry.fieldKey, newValue, context.rootForm, context.logger, context.warningTracker);
+        if (wasApplied) {
+            chainContext.appliedDerivations.add(derivationKey);
+            derivationLogger.evaluation({
+                debugName: entry.debugName,
+                fieldKey: entry.fieldKey,
+                result: 'applied',
+                previousValue: currentValue,
+                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,
+                fieldKey: entry.fieldKey,
+                result: 'skipped',
+                skipReason: 'target-not-found',
+            });
+            return {
+                applied: false,
+                fieldKey: entry.fieldKey,
+                warning: `Field '${entry.fieldKey}' not found`,
+            };
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        context.logger.error(formatDerivationError(entry, 'apply', errorMessage));
+        derivationLogger.evaluation({
+            debugName: entry.debugName,
+            fieldKey: entry.fieldKey,
+            result: 'error',
+            error: errorMessage,
+        });
+        return {
+            applied: false,
+            fieldKey: entry.fieldKey,
+            error: errorMessage,
+        };
+    }
+}
+/**
+ * Handles array field derivations with '$' placeholder.
+ *
+ * Iterates over all array items and applies the derivation for each,
+ * resolving '$' to the actual index and creating scoped evaluation contexts.
+ *
+ * @internal
+ */
+function tryApplyArrayDerivation(entry, context, chainContext) {
+    const formValue = untracked(() => context.formValue());
+    // Parse the field path using path utilities
+    const pathInfo = parseArrayPath(entry.fieldKey);
+    if (!pathInfo.isArrayPath) {
+        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, fieldKey: entry.fieldKey };
+    }
+    let appliedAny = false;
+    // Process each array item
+    for (let i = 0; i < arrayValue.length; i++) {
+        const resolvedPath = resolveArrayPath(entry.fieldKey, i);
+        const derivationKey = createDerivationKey(resolvedPath);
+        // Skip if already applied in this cycle
+        if (chainContext.appliedDerivations.has(derivationKey)) {
+            continue;
+        }
+        // Create evaluation context scoped to this array item
+        const arrayItem = arrayValue[i];
+        const evalContext = createArrayItemEvaluationContext(entry, arrayItem, formValue, i, arrayPath, context);
+        // Evaluate condition
+        if (!evaluateDerivationCondition(entry.condition, evalContext)) {
+            continue;
+        }
+        // Compute derived value
+        let newValue;
+        try {
+            newValue = computeDerivedValue(entry, evalContext, context);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            context.logger.error(formatDerivationError(entry, 'compute', `[index ${i}] ${errorMessage}`));
+            continue;
+        }
+        // Check if value actually changed
+        const currentValue = getNestedValue(formValue, resolvedPath);
+        if (isEqual(currentValue, newValue)) {
+            continue;
+        }
+        // Apply the value
+        try {
+            applyValueToForm(resolvedPath, newValue, context.rootForm, context.logger, context.warningTracker);
+            chainContext.appliedDerivations.add(derivationKey);
+            appliedAny = true;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            context.logger.error(formatDerivationError(entry, 'apply', `[index ${i}] ${errorMessage}`));
+        }
+    }
+    return { applied: appliedAny, fieldKey: entry.fieldKey };
+}
+/**
+ * Creates an evaluation context for derivation processing.
+ *
+ * @internal
+ */
+function createEvaluationContext(entry, formValue, context) {
+    const fieldValue = getNestedValue(formValue, entry.fieldKey);
+    return {
+        fieldValue,
+        formValue,
+        fieldPath: entry.fieldKey,
+        customFunctions: context.customFunctions,
+        externalData: context.externalData,
+        logger: context.logger,
+    };
+}
+/**
+ * Creates an evaluation context scoped to a specific array item.
+ *
+ * For array derivations, `formValue` in the expression should reference
+ * the current array item's values, not the root form values.
+ *
+ * @internal
+ */
+function createArrayItemEvaluationContext(entry, arrayItem, rootFormValue, itemIndex, arrayPath, context) {
+    // For array item expressions, formValue should be the array item
+    // This allows expressions like 'formValue.quantity * formValue.unitPrice'
+    // to work within the context of each array item
+    return {
+        fieldValue: arrayItem,
+        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,
+        arrayIndex: itemIndex,
+        arrayPath,
+    };
+}
+/**
+ * Evaluates the derivation condition.
+ *
+ * @internal
+ */
+function evaluateDerivationCondition(condition, context) {
+    if (typeof condition === 'boolean') {
+        return condition;
+    }
+    return evaluateCondition(condition, context);
+}
+/**
+ * Computes the derived value based on the entry configuration.
+ *
+ * @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'.`);
+}
+/**
+ * Applies a value to the form at the specified path.
+ *
+ * Uses bracket notation to access child FieldTrees, following the same pattern
+ * as group-field and array-field components. Fields are accessed as signals
+ * and their value is set via the `.value.set()` method.
+ *
+ * Handles nested paths and array paths with '$' placeholder.
+ *
+ * @internal
+ */
+function applyValueToForm(targetPath, value, rootForm, logger, warningTracker) {
+    // Handle simple top-level fields
+    if (!targetPath.includes('.')) {
+        return setFieldValue(rootForm, targetPath, value, logger, warningTracker);
+    }
+    // Handle nested paths (e.g., 'address.city' or 'items.$.quantity')
+    const parts = targetPath.split('.');
+    let current = rootForm;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        // Handle array index placeholder '$'
+        if (part === '$') {
+            // This case should be resolved at collection time
+            // If we still have '$', we need to skip for now
+            return false;
+        }
+        // Navigate to the next level using bracket notation
+        const next = current[part];
+        if (next === undefined || next === null) {
+            warnMissingField(targetPath, logger, warningTracker);
+            return false; // Path doesn't exist
+        }
+        current = next;
+    }
+    // Set the final value
+    const finalPart = parts[parts.length - 1];
+    return setFieldValue(current, finalPart, value, logger, warningTracker);
+}
+/**
+ * Error message prefix for derivation-related errors.
+ * @internal
+ */
+const ERROR_PREFIX = '[Derivation]';
+/**
+ * Creates a standardized error message for derivation errors.
+ * @internal
+ */
+function formatDerivationError(entry, phase, message) {
+    const source = entry.expression
+        ? `expression: "${entry.expression.substring(0, 50)}${entry.expression.length > 50 ? '...' : ''}"`
+        : entry.functionName
+            ? `function: "${entry.functionName}"`
+            : entry.value !== undefined
+                ? 'static value'
+                : 'unknown source';
+    return `${ERROR_PREFIX} Failed to ${phase} derivation (field: ${entry.fieldKey}, ${source}): ${message}`;
+}
+/**
+ * Sets a field value using the Angular Signal Forms pattern.
+ *
+ * Accesses the child field via bracket notation, drills down to find
+ * the WritableSignal, and uses isWritableSignal for type-safe signal detection.
+ *
+ * Angular Signal Forms structure:
+ * - form[key] is a callable function (field accessor)
+ * - form[key]() returns the field instance with { value: WritableSignal<T> }
+ * - form[key]().value.set(newValue) sets the value
+ *
+ * @returns true if the value was successfully set, false if field not found
+ *
+ * @internal
+ */
+function setFieldValue(parent, fieldKey, value, logger, warningTracker) {
+    // Access child field via bracket notation (same pattern as group-field/array-field)
+    const fieldAccessor = parent[fieldKey];
+    if (fieldAccessor === undefined || fieldAccessor === null) {
+        warnMissingField(fieldKey, logger, warningTracker);
+        return false;
+    }
+    // Angular Signal Forms: field accessor is a callable function
+    if (typeof fieldAccessor !== 'function') {
+        warnMissingField(fieldKey, logger, warningTracker);
+        return false;
+    }
+    // Call the accessor to get the field instance
+    const fieldInstance = fieldAccessor();
+    if (!fieldInstance || typeof fieldInstance !== 'object' || !('value' in fieldInstance)) {
+        warnMissingField(fieldKey, logger, warningTracker);
+        return false;
+    }
+    // Get the value signal and verify it's a WritableSignal
+    const valueSignal = fieldInstance.value;
+    if (isWritableSignal(valueSignal)) {
+        valueSignal.set(value);
+        return true;
+    }
+    else {
+        warnMissingField(fieldKey, logger, warningTracker);
+        return false;
+    }
+}
+/**
+ * Logs a warning for a missing target field (once per field per form instance).
+ *
+ * Uses the provided warning tracker to avoid log spam. If no tracker is provided,
+ * the warning will be logged every time.
+ *
+ * @internal
+ */
+function warnMissingField(fieldKey, logger, warningTracker) {
+    // If tracker is provided, check if we've already warned about this field
+    if (warningTracker) {
+        if (warningTracker.warnedFields.has(fieldKey)) {
+            return;
+        }
+        warningTracker.warnedFields.add(fieldKey);
+    }
+    logger?.warn(`${ERROR_PREFIX} Target field '${fieldKey}' not found in form. ` +
+        `Ensure the field is defined in your form configuration. ` +
+        `This warning is shown once per field.`);
+}
+/**
+ * Processes derivations for a specific trigger type.
+ *
+ * Filters entries by trigger type and applies them.
+ *
+ * @param collection - The collected derivation entries
+ * @param trigger - The trigger type to filter by
+ * @param context - Context for applying derivations
+ * @param changedFields - Set of field keys that changed (for filtering)
+ * @returns Result of the derivation processing
+ *
+ * @public
+ */
+function applyDerivationsForTrigger(collection, trigger, context, changedFields) {
+    // Filter entries by trigger type
+    const filteredEntries = collection.entries.filter((entry) => {
+        if (trigger === 'onChange') {
+            return !entry.trigger || entry.trigger === 'onChange';
+        }
+        return entry.trigger === trigger;
+    });
+    // Create a minimal collection with filtered entries
+    const filteredCollection = {
+        entries: filteredEntries,
+    };
+    return applyDerivations(filteredCollection, context, changedFields);
+}
+/**
+ * Gets all debounced derivation entries from a collection.
+ *
+ * Use this to extract debounced entries for separate processing with debounce timers.
+ *
+ * @param collection - The collected derivation entries
+ * @returns Array of debounced derivation entries
+ *
+ * @public
+ */
+function getDebouncedDerivationEntries(collection) {
+    return collection.entries.filter((entry) => entry.trigger === 'debounced');
+}
+
+/**
+ * Injection token for the derivation warning tracker.
+ * Provided at form component level for instance-scoped tracking.
+ *
+ * @public
+ */
+const DERIVATION_WARNING_TRACKER = new InjectionToken('DerivationWarningTracker', {
+    providedIn: null,
+    factory: () => ({ warnedFields: new Set() }),
+});
+/**
+ * Creates a fresh warning tracker instance.
+ *
+ * @returns A new DerivationWarningTracker with an empty warnedFields Set
+ *
+ * @public
+ */
+function createDerivationWarningTracker() {
+    return { warnedFields: new Set() };
+}
+
+/**
+ * Prefix for derivation debug log messages.
+ * @internal
+ */
+const LOG_PREFIX = '[Derivation]';
+/**
+ * Logs a summary of derivation processing results.
+ *
+ * Only logs when:
+ * - Config level is 'summary' or 'verbose'
+ * - At least one derivation was applied or an error occurred
+ *
+ * @param result - The derivation processing result
+ * @param trigger - The trigger type ('onChange' or 'debounced')
+ * @param logger - Logger instance
+ * @param config - Debug logging configuration
+ *
+ * @public
+ */
+function logDerivationSummary(result, trigger, logger, config) {
+    if (!shouldLog(config, 'summary'))
+        return;
+    // Only log if something interesting happened
+    if (result.appliedCount === 0 && result.errorCount === 0)
+        return;
+    logger.debug(`${LOG_PREFIX} Cycle complete (${trigger})`, {
+        applied: result.appliedCount,
+        skipped: result.skippedCount,
+        errors: result.errorCount,
+        iterations: result.iterations,
+    });
+}
+/**
+ * Logs when max iterations are reached (always logged as warning).
+ *
+ * @param result - The derivation processing result
+ * @param trigger - The trigger type
+ * @param logger - Logger instance
+ *
+ * @public
+ */
+function logMaxIterationsReached(result, trigger, logger) {
+    logger.warn(`${LOG_PREFIX} Processing reached max iterations (${trigger}). ` +
+        `This may indicate a loop in derivation logic. ` +
+        `Applied: ${result.appliedCount}, Skipped: ${result.skippedCount}, Errors: ${result.errorCount}`);
+}
+/**
+ * Logs a verbose entry for a single derivation evaluation.
+ *
+ * Only logs when config level is 'verbose'.
+ *
+ * @param entry - The derivation log entry with evaluation details
+ * @param logger - Logger instance
+ * @param config - Debug logging configuration
+ *
+ * @internal
+ */
+function logDerivationEvaluation(entry, logger, config) {
+    if (!shouldLog(config, 'verbose'))
+        return;
+    const name = entry.debugName ? `"${entry.debugName}"` : entry.fieldKey;
+    switch (entry.result) {
+        case 'applied':
+            logger.debug(`${LOG_PREFIX} -> Applied: ${name}`, {
+                field: entry.fieldKey,
+                previousValue: entry.previousValue,
+                newValue: entry.newValue,
+                ...(entry.durationMs !== undefined && { durationMs: entry.durationMs }),
+            });
+            break;
+        case 'skipped':
+            logger.debug(`${LOG_PREFIX} -> Skipped: ${name} (${formatSkipReason(entry.skipReason)})`, {
+                field: entry.fieldKey,
+                reason: entry.skipReason,
+            });
+            break;
+        case 'error':
+            logger.debug(`${LOG_PREFIX} -> Error: ${name}`, {
+                field: entry.fieldKey,
+                error: entry.error,
+            });
+            break;
+    }
+}
+/**
+ * Formats the skip reason for human-readable output.
+ *
+ * @internal
+ */
+function formatSkipReason(reason) {
+    switch (reason) {
+        case 'condition-false':
+            return 'condition not met';
+        case 'value-unchanged':
+            return 'value unchanged';
+        case 'already-applied':
+            return 'already applied this cycle';
+        default:
+            return 'unknown';
+    }
+}
+/**
+ * Logs the start of a derivation processing cycle.
+ *
+ * Only logs when config level is 'verbose'.
+ *
+ * @param trigger - The trigger type ('onChange' or 'debounced')
+ * @param entryCount - Number of derivations to process in this cycle
+ * @param logger - Logger instance
+ * @param config - Debug logging configuration
+ *
+ * @internal
+ */
+function logDerivationCycleStart(trigger, entryCount, logger, config) {
+    if (!shouldLog(config, 'verbose'))
+        return;
+    logger.debug(`${LOG_PREFIX} Starting cycle (${trigger}) with ${entryCount} derivation(s)`);
+}
+/**
+ * Logs the start of a derivation iteration within a cycle.
+ *
+ * Only logs when config level is 'verbose'.
+ *
+ * @param iteration - Current iteration number (1-based)
+ * @param logger - Logger instance
+ * @param config - Debug logging configuration
+ *
+ * @internal
+ */
+function logDerivationIteration(iteration, logger, config) {
+    if (!shouldLog(config, 'verbose'))
+        return;
+    logger.debug(`${LOG_PREFIX} Iteration ${iteration}`);
+}
+
+/**
+ * Active implementation of DerivationLogger that performs actual logging.
+ *
+ * @internal
+ */
+class ActiveDerivationLogger {
+    logger;
+    config = createDefaultDerivationLogConfig();
+    /**
+     * Updates the log configuration.
+     */
+    setConfig(config) {
+        this.config = config;
+    }
+    cycleStart(trigger, entryCount) {
+        if (!shouldLog(this.config, 'verbose'))
+            return;
+        this.logger.debug(`Derivation - Starting cycle (${trigger}) with ${entryCount} derivation(s)`);
+    }
+    iteration(iterationNumber) {
+        if (!shouldLog(this.config, 'verbose'))
+            return;
+        this.logger.debug(`Derivation - Iteration ${iterationNumber}`);
+    }
+    evaluation(entry) {
+        if (!shouldLog(this.config, 'verbose'))
+            return;
+        const name = entry.debugName ? `"${entry.debugName}"` : entry.fieldKey;
+        switch (entry.result) {
+            case 'applied':
+                this.logger.debug(`Derivation - Applied ${name}`, {
+                    field: entry.fieldKey,
+                    previousValue: entry.previousValue,
+                    newValue: entry.newValue,
+                    ...(entry.durationMs !== undefined && { durationMs: entry.durationMs }),
+                });
+                break;
+            case 'skipped':
+                this.logger.debug(`Derivation - Skipped ${name} (${this.formatSkipReason(entry.skipReason)})`, {
+                    field: entry.fieldKey,
+                    reason: entry.skipReason,
+                });
+                break;
+            case 'error':
+                this.logger.debug(`Derivation - Error ${name}`, {
+                    field: entry.fieldKey,
+                    error: entry.error,
+                });
+                break;
+        }
+    }
+    summary(result, trigger) {
+        if (!shouldLog(this.config, 'summary'))
+            return;
+        // Only log if something interesting happened
+        if (result.appliedCount === 0 && result.errorCount === 0)
+            return;
+        this.logger.debug(`Derivation - Cycle complete (${trigger})`, {
+            applied: result.appliedCount,
+            skipped: result.skippedCount,
+            errors: result.errorCount,
+            iterations: result.iterations,
+        });
+    }
+    maxIterationsReached(result, trigger) {
+        this.logger.warn(`Derivation - Max iterations reached (${trigger}). ` +
+            `This may indicate a loop in derivation logic. ` +
+            `Applied: ${result.appliedCount}, Skipped: ${result.skippedCount}, Errors: ${result.errorCount}`);
+    }
+    formatSkipReason(reason) {
+        switch (reason) {
+            case 'condition-false':
+                return 'condition not met';
+            case 'value-unchanged':
+                return 'value unchanged';
+            case 'already-applied':
+                return 'already applied this cycle';
+            default:
+                return 'unknown';
+        }
+    }
+}
+/**
+ * No-op implementation of DerivationLogger.
+ * All methods are empty - no logging overhead when disabled.
+ *
+ * @internal
+ */
+class NoopDerivationLogger {
+    cycleStart() {
+        /* no-op */
+    }
+    iteration() {
+        /* no-op */
+    }
+    evaluation() {
+        /* no-op */
+    }
+    summary() {
+        /* no-op */
+    }
+    maxIterationsReached() {
+        /* no-op */
+    }
+}
+/** Singleton no-op instance to avoid creating new objects */
+const NOOP_INSTANCE = new NoopDerivationLogger();
+/**
+ * Injection token for the derivation logger service.
+ *
+ * @public
+ */
+const DERIVATION_LOGGER = new InjectionToken('DerivationLogger');
+/**
+ * Factory function to create a DerivationLogger.
+ *
+ * Returns a no-op implementation if config level is 'none',
+ * otherwise returns an active logger with the given config.
+ *
+ * @param config - The derivation log configuration
+ * @param logger - The underlying logger instance
+ * @returns A DerivationLogger instance
+ *
+ * @public
+ */
+function createDerivationLogger(config, logger) {
+    const effectiveConfig = config ?? createDefaultDerivationLogConfig();
+    // Return no-op if logging is completely disabled
+    if (effectiveConfig.level === 'none') {
+        return NOOP_INSTANCE;
+    }
+    // Create active logger with config
+    const service = new ActiveDerivationLogger();
+    service.logger = logger;
+    service.setConfig(effectiveConfig);
+    return service;
+}
+
+/**
+ * Orchestrates derivation processing for a dynamic form.
+ *
+ * Uses RxJS streams for reactive derivation processing:
+ * - `exhaustMap` prevents re-entry during onChange derivation application
+ * - `pairwise` tracks value changes without mutable state
+ * - `takeUntilDestroyed` handles automatic cleanup
+ *
+ * Injects common services directly, requiring only form-specific signals in config.
+ *
+ * @public
+ */
+class DerivationOrchestrator {
+    config;
+    injector = inject(Injector);
+    destroyRef = inject(DestroyRef);
+    logger = inject(DynamicFormLogger);
+    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.
+     */
+    derivationCollection;
+    constructor(config) {
+        this.config = config;
+        this.derivationCollection = computed(() => {
+            const fields = config.schemaFields();
+            if (!fields || fields.length === 0) {
+                return null;
+            }
+            const collection = collectDerivations(fields);
+            if (collection.entries.length === 0) {
+                return null;
+            }
+            validateNoCycles(collection, this.logger);
+            this.warnAboutWildcardDependencies(collection.entries, fields.length);
+            return collection;
+        }, ...(ngDevMode ? [{ debugName: "derivationCollection" }] : []));
+        this.setupOnChangeStream();
+        this.setupDebouncedStream();
+    }
+    setupOnChangeStream() {
+        const collection$ = toObservable(this.derivationCollection, { injector: this.injector });
+        const formValue$ = toObservable(this.config.formValue, { injector: this.injector });
+        const form$ = toObservable(this.config.form, { injector: this.injector });
+        collection$
+            .pipe(filter((collection) => collection !== null), combineLatestWith(formValue$, form$), 
+        // auditTime(0): Batch synchronous emissions from Angular's change detection.
+        // When a single user action triggers multiple signal updates, this ensures
+        // we only process derivations once after all updates complete (microtask timing).
+        auditTime(0), 
+        // exhaustMap: Prevents re-entry while processing derivations.
+        // If form value changes DURING derivation processing (from our own setValue calls),
+        // we ignore those emissions and complete the current cycle first.
+        // switchMap would cancel mid-processing, causing incomplete derivation chains.
+        exhaustMap(([collection, , formAccessor]) => {
+            this.applyOnChangeDerivations(collection, formAccessor);
+            // scheduled with queueScheduler: Ensures the observable completes
+            // in the next microtask, allowing exhaustMap to accept new emissions.
+            // Without this, exhaustMap would block indefinitely.
+            return scheduled([null], queueScheduler);
+        }), takeUntilDestroyed(this.destroyRef))
+            .subscribe({
+            error: (err) => this.logger.error('Derivation onChange stream error', err),
+        });
+    }
+    setupDebouncedStream() {
+        toObservable(this.config.formValue, { injector: this.injector })
+            .pipe(
+        // debounceTime: Wait for value to stabilize before detecting changes.
+        // Uses DEFAULT_DEBOUNCE_MS as the minimum debounce period.
+        debounceTime(DEFAULT_DEBOUNCE_MS), 
+        // startWith + pairwise: Track previous and current values to detect changes.
+        // startWith(null) ensures pairwise has an initial value to pair with.
+        startWith(null), pairwise(), filter((pair) => pair[1] !== null), map(([previous, current]) => ({
+            current,
+            changedFields: getChangedKeys(previous, current),
+        })), filter(({ changedFields }) => changedFields.size > 0), 
+        // switchMap: For debounced derivations, it's OK to cancel pending work
+        // if new changes come in - we want the latest debounced values.
+        // (Unlike onChange which uses exhaustMap to prevent cancellation)
+        switchMap(({ changedFields }) => {
+            const collection = untracked(() => this.derivationCollection());
+            const formAccessor = untracked(() => this.config.form());
+            if (!collection || !formAccessor)
+                return of(null);
+            // Get unique debounce periods from entries with trigger 'debounced'
+            const debouncePeriods = this.getDebouncePeriods(collection.entries);
+            if (debouncePeriods.length === 0)
+                return of(null);
+            // merge: Process multiple debounce periods concurrently.
+            // Each period stream handles its own timing independently.
+            const periodStreams = debouncePeriods.map((debounceMs) => this.createPeriodStream(debounceMs, collection, formAccessor, changedFields));
+            return merge(...periodStreams);
+        }), takeUntilDestroyed(this.destroyRef))
+            .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);
+        if (additionalWait === 0) {
+            return of(null).pipe(map(() => {
+                this.applyDebouncedEntriesForPeriod(debounceMs, collection, formAccessor, changedFields);
+            }));
+        }
+        return timer(additionalWait).pipe(map(() => {
+            const currentCollection = untracked(() => this.derivationCollection());
+            const currentFormAccessor = untracked(() => this.config.form());
+            if (currentCollection && currentFormAccessor) {
+                this.applyDebouncedEntriesForPeriod(debounceMs, currentCollection, currentFormAccessor, changedFields);
+            }
+        }));
+    }
+    applyOnChangeDerivations(collection, formAccessor) {
+        const applicatorContext = {
+            formValue: this.config.formValue,
+            rootForm: formAccessor,
+            derivationFunctions: this.functionRegistry.getDerivationFunctions(),
+            customFunctions: this.functionRegistry.getCustomFunctions(),
+            externalData: this.resolveExternalData(),
+            logger: this.logger,
+            warningTracker: this.warningTracker,
+            derivationLogger: untracked(() => this.config.derivationLogger()),
+            maxIterations: untracked(() => this.formOptions()?.maxDerivationIterations),
+        };
+        const result = applyDerivationsForTrigger(collection, 'onChange', applicatorContext);
+        if (result.maxIterationsReached) {
+            this.logger.warn(`Derivation processing reached max iterations. ` +
+                `This may indicate a loop in derivation logic that wasn't caught at build time. ` +
+                `Applied: ${result.appliedCount}, Skipped: ${result.skippedCount}, Errors: ${result.errorCount}`);
+        }
+    }
+    applyDebouncedEntriesForPeriod(debounceMs, collection, formAccessor, changedFields) {
+        // Filter entries to just those with the specific debounce period
+        const debouncedEntries = collection.entries.filter((entry) => entry.trigger === 'debounced' && (entry.debounceMs ?? DEFAULT_DEBOUNCE_MS) === debounceMs);
+        if (debouncedEntries.length === 0) {
+            return;
+        }
+        // Create a minimal collection with filtered entries
+        const filteredCollection = {
+            entries: debouncedEntries,
+        };
+        const applicatorContext = {
+            formValue: this.config.formValue,
+            rootForm: formAccessor,
+            derivationFunctions: this.functionRegistry.getDerivationFunctions(),
+            customFunctions: this.functionRegistry.getCustomFunctions(),
+            externalData: this.resolveExternalData(),
+            logger: this.logger,
+            warningTracker: this.warningTracker,
+            derivationLogger: untracked(() => this.config.derivationLogger()),
+            maxIterations: untracked(() => this.formOptions()?.maxDerivationIterations),
+        };
+        const result = applyDerivationsForTrigger(filteredCollection, 'debounced', applicatorContext, changedFields);
+        if (result.maxIterationsReached) {
+            this.logger.warn(`Debounced derivation processing reached max iterations (${debounceMs}ms). ` +
+                `Applied: ${result.appliedCount}, Skipped: ${result.skippedCount}, Errors: ${result.errorCount}`);
+        }
+    }
+    /**
+     * 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);
+    }
+    warnAboutWildcardDependencies(entries, fieldCount) {
+        if (!isDevMode())
+            return;
+        // Find entries with wildcard dependency
+        const wildcardEntries = entries.filter((entry) => entry.dependsOn.includes('*'));
+        if (wildcardEntries.length === 0)
+            return;
+        // 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.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.
+ * Must be called within an injection context.
+ *
+ * @param config - Form-specific signals configuration
+ * @returns The created DerivationOrchestrator
+ *
+ * @public
+ */
+function createDerivationOrchestrator(config) {
+    return new DerivationOrchestrator(config);
+}
+/**
+ * Injection token for the DerivationOrchestrator.
+ *
+ * @public
+ */
+const DERIVATION_ORCHESTRATOR = new InjectionToken('DERIVATION_ORCHESTRATOR');
+/**
+ * Injects the DerivationOrchestrator from the current injection context.
+ *
+ * @returns The DerivationOrchestrator instance
+ * @throws Error if called outside of an injection context or if orchestrator is not provided
+ *
+ * @public
+ */
+function injectDerivationOrchestrator() {
+    return inject(DERIVATION_ORCHESTRATOR);
+}
+
+class NextPageEvent {
+    type = 'next-page';
+}
+
+class PageChangeEvent {
+    currentPageIndex;
+    totalPages;
+    previousPageIndex;
+    type = 'page-change';
+    constructor(
+    /** The current page index (0-based) */
+    currentPageIndex, 
+    /** Total number of pages */
+    totalPages, 
+    /** Previous page index (0-based), undefined if first navigation */
+    previousPageIndex) {
+        this.currentPageIndex = currentPageIndex;
+        this.totalPages = totalPages;
+        this.previousPageIndex = previousPageIndex;
+    }
+}
+
+class PreviousPageEvent {
+    type = 'previous-page';
+}
+
+/**
+ * Event dispatched to add a new item to an array field.
+ *
+ * This event is used to dynamically add items to array fields at runtime.
+ * The array field component listens for this event and adds a new item
+ * based on the provided field template, or uses the array's own template if not provided.
+ *
+ * @example
+ * ```typescript
+ * // Add item using array's own template
+ * eventBus.dispatch(AddArrayItemEvent, 'contacts');
+ *
+ * // Add item with explicit field template
+ * const fieldTemplate = { key: 'email', type: 'input' };
+ * eventBus.dispatch(AddArrayItemEvent, 'contacts', fieldTemplate);
+ *
+ * // Add item at specific index
+ * eventBus.dispatch(AddArrayItemEvent, 'contacts', fieldTemplate, 2);
+ * ```
+ */
+class AddArrayItemEvent {
+    arrayKey;
+    field;
+    index;
+    type = 'add-array-item';
+    constructor(
+    /** The key of the array field to add an item to */
+    arrayKey, 
+    /**
+     * Optional field template definition to render for the new array item.
+     * If not provided, the array field component will use its own template.
+     */
+    field, 
+    /** Optional index where to insert the item (defaults to end of array) */
+    index) {
+        this.arrayKey = arrayKey;
+        this.field = field;
+        this.index = index;
+    }
+}
+
+/**
+ * Event dispatched to remove an item from an array field.
+ *
+ * This event is used to dynamically remove items from array fields at runtime.
+ * The array field component listens for this event and removes the item
+ * at the specified index.
+ *
+ * @example
+ * ```typescript
+ * // Remove item at index 1 from 'contacts' array
+ * eventBus.dispatch(RemoveArrayItemEvent, 'contacts', 1);
+ *
+ * // Remove last item
+ * eventBus.dispatch(RemoveArrayItemEvent, 'contacts');
+ * ```
+ */
+class RemoveArrayItemEvent {
+    arrayKey;
+    index;
+    type = 'remove-array-item';
+    constructor(
+    /** The key of the array field to remove an item from */
+    arrayKey, 
+    /** Index of the item to remove (defaults to last item) */
+    index) {
+        this.arrayKey = arrayKey;
+        this.index = index;
+    }
+}
+
+/**
+ * Event dispatched when the form should be reset to its default values.
+ *
+ * This event instructs the dynamic form component to restore all field values
+ * to their initial default values as defined in the form configuration.
+ *
+ * @example
+ * ```typescript
+ * // Dispatch from a button component
+ * eventBus.dispatch(FormResetEvent);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Listen for reset events
+ * eventBus.on<FormResetEvent>('form-reset').subscribe(() => {
+ *   console.log('Form was reset to defaults');
+ * });
+ * ```
+ */
+class FormResetEvent {
+    type = 'form-reset';
+}
+
+/**
+ * Event dispatched when the form should be cleared.
+ *
+ * This event instructs the dynamic form component to clear all field values,
+ * resetting them to empty/undefined state regardless of their default values.
+ *
+ * @example
+ * ```typescript
+ * // Dispatch from a button component
+ * eventBus.dispatch(FormClearEvent);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Listen for clear events
+ * eventBus.on<FormClearEvent>('form-clear').subscribe(() => {
+ *   console.log('Form was cleared');
  * });
  * ```
  */
@@ -5380,47 +8466,177 @@ 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-Bt6blv9I.mjs').then(m => m.default)], () => [import('./ng-forge-dynamic-forms-page-field.component-Bt6blv9I.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-Bt6blv9I.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) {
-      @if (i === state().currentPageIndex || i === state().currentPageIndex + 1 || i === state().currentPageIndex - 1) {
-        <!-- Current and adjacent pages (±1): render immediately for flicker-free navigation -->
-        @defer (on immediate) {
-          <section
-            page-field
-            [field]="pageField"
-            [key]="pageField.key"
-            [pageIndex]="i"
-            [isVisible]="i === state().currentPageIndex"
-          ></section>
-        } @placeholder {
-          <div class="df-page-placeholder" [attr.data-page-index]="i" [attr.data-page-key]="pageField.key"></div>
-        }
-      } @else {
-        <!-- Distant pages: defer until browser is idle for memory savings -->
-        @defer (on idle) {
-          <section page-field [field]="pageField" [key]="pageField.key" [pageIndex]="i" [isVisible]="false"></section>
-        } @placeholder {
-          <div class="df-page-placeholder" [attr.data-page-index]="i" [attr.data-page-key]="pageField.key"></div>
-        }
-      }
+  `, 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-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) {
+      @if (i === state().currentPageIndex || i === state().currentPageIndex + 1 || i === state().currentPageIndex - 1) {
+        <!-- Current and adjacent pages (±1): render immediately for flicker-free navigation -->
+        @defer (on immediate) {
+          <section
+            page-field
+            [field]="pageField"
+            [key]="pageField.key"
+            [pageIndex]="i"
+            [isVisible]="i === state().currentPageIndex"
+          ></section>
+        } @placeholder {
+          <div class="df-page-placeholder" [attr.data-page-index]="i" [attr.data-page-key]="pageField.key"></div>
+        }
+      } @else {
+        <!-- Distant pages: defer until browser is idle for memory savings -->
+        @defer (on idle) {
+          <section page-field [field]="pageField" [key]="pageField.key" [pageIndex]="i" [isVisible]="false"></section>
+        } @placeholder {
+          <div class="df-page-placeholder" [attr.data-page-index]="i" [attr.data-page-key]="pageField.key"></div>
+        }
+      }
+    }
+  `, host: {
+                            class: 'df-page-orchestrator',
+                            '[attr.data-current-page]': 'state().currentPageIndex',
+                            '[attr.data-total-pages]': 'state().totalPages',
+                        }, providers: [
+                            {
+                                provide: FIELD_SIGNAL_CONTEXT,
+                                useFactory: (orchestrator) => orchestrator.extendedFieldSignalContext(),
+                                deps: [PageOrchestratorComponent],
+                            },
+                        ], changeDetection: ChangeDetectionStrategy.OnPush, styles: [":host{display:block;position:relative;width:100%}\n"] }]
+            }], ctorParameters: () => [], propDecorators: { pageFields: [{ type: i0.Input, args: [{ isSignal: true, alias: "pageFields", required: true }] }], form: [{ type: i0.Input, args: [{ isSignal: true, alias: "form", required: true }] }], fieldSignalContext: [{ type: i0.Input, args: [{ isSignal: true, alias: "fieldSignalContext", required: true }] }] } }) });
+
+/**
+ * Type guard to check if a value is a DynamicFormFeature
+ */
+function isDynamicFormFeature(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'ɵkind' in value &&
+        typeof value.ɵkind === 'string' &&
+        'ɵproviders' in value &&
+        Array.isArray(value.ɵproviders));
+}
+/**
+ * Helper to create a feature with proper typing
+ */
+function createFeature(kind, providers) {
+    return {
+        ɵkind: kind,
+        ɵproviders: providers,
+    };
+}
+
+/**
+ * Console-based logger implementation.
+ */
+class ConsoleLogger {
+    prefix = '[Dynamic Forms]';
+    debug(message, ...args) {
+        console.debug(this.prefix, message, ...args);
+    }
+    info(message, ...args) {
+        console.info(this.prefix, message, ...args);
+    }
+    warn(message, ...args) {
+        console.warn(this.prefix, message, ...args);
+    }
+    error(message, ...args) {
+        console.error(this.prefix, message, ...args);
+    }
+}
+
+/**
+ * No-operation logger implementation.
+ * All methods are no-ops - used in production by default.
+ */
+class NoopLogger {
+    debug() {
+        // Intentionally empty
+    }
+    info() {
+        // Intentionally empty
+    }
+    warn() {
+        // Intentionally empty
+    }
+    error() {
+        // Intentionally empty
+    }
+}
+
+/**
+ * Injection token for derivation logging configuration.
+ *
+ * @internal
+ */
+const DERIVATION_LOG_CONFIG = new InjectionToken('DERIVATION_LOG_CONFIG', {
+    providedIn: 'root',
+    factory: createDefaultDerivationLogConfig,
+});
+/**
+ * Configure logging for dynamic forms.
+ *
+ * By default, general logging is enabled (ConsoleLogger) and derivation
+ * logging is disabled ('none'). Use this feature to enable derivation debugging.
+ *
+ * @example
+ * ```typescript
+ * // Disable all logging
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withLoggerConfig(false)
+ * )
+ *
+ * // Enable verbose derivation logging
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withLoggerConfig({ derivations: 'verbose' })
+ * )
+ *
+ * // Disable derivation logging but keep general logging
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withLoggerConfig({ derivations: 'none' })
+ * )
+ *
+ * // Conditional logging (e.g., only in dev mode)
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withLoggerConfig(() => isDevMode())
+ * )
+ * ```
+ *
+ * @param config - Boolean to enable/disable logging, a function returning boolean, or a config object
+ * @returns A DynamicFormFeature that configures logging
+ *
+ * @public
+ */
+function withLoggerConfig(config = true) {
+    // Handle boolean or function
+    if (typeof config === 'boolean' || typeof config === 'function') {
+        const isEnabled = typeof config === 'function' ? config() : config;
+        const logger = isEnabled ? new ConsoleLogger() : new NoopLogger();
+        return createFeature('logger', [{ provide: DynamicFormLogger, useValue: logger }]);
+    }
+    // Handle config object
+    const isEnabled = config.enabled !== false;
+    const logger = isEnabled ? new ConsoleLogger() : new NoopLogger();
+    const providers = [{ provide: DynamicFormLogger, useValue: logger }];
+    // Add derivation log config if specified
+    if (config.derivations !== undefined) {
+        providers.push({
+            provide: DERIVATION_LOG_CONFIG,
+            useValue: { level: config.derivations },
+        });
     }
-  `, host: {
-                            class: 'df-page-orchestrator',
-                            '[attr.data-current-page]': 'state().currentPageIndex',
-                            '[attr.data-total-pages]': 'state().totalPages',
-                        }, providers: [
-                            {
-                                provide: FIELD_SIGNAL_CONTEXT,
-                                useFactory: (orchestrator) => orchestrator.extendedFieldSignalContext(),
-                                deps: [PageOrchestratorComponent],
-                            },
-                        ], changeDetection: ChangeDetectionStrategy.OnPush, styles: [":host{display:block;position:relative;width:100%}\n"] }]
-            }], ctorParameters: () => [], propDecorators: { pageFields: [{ type: i0.Input, args: [{ isSignal: true, alias: "pageFields", required: true }] }], form: [{ type: i0.Input, args: [{ isSignal: true, alias: "form", required: true }] }], fieldSignalContext: [{ type: i0.Input, args: [{ isSignal: true, alias: "fieldSignalContext", required: true }] }] } }) });
+    return createFeature('logger', providers);
+}
 
+function derivationOrchestratorFactoryWrapper(dynamicForm) {
+    return createDerivationOrchestrator(dynamicForm.derivationOrchestratorConfig);
+}
 /**
  * Dynamic form component that renders a complete form based on configuration.
  *
@@ -5452,6 +8668,7 @@ class DynamicForm {
     functionRegistry = inject(FunctionRegistryService);
     schemaRegistry = inject(SchemaRegistryService);
     logger = inject(DynamicFormLogger);
+    derivationLogConfig = inject(DERIVATION_LOG_CONFIG);
     // ─────────────────────────────────────────────────────────────────────────────
     // Inputs
     // ─────────────────────────────────────────────────────────────────────────────
@@ -5542,6 +8759,15 @@ class DynamicForm {
         const inputOptions = this.formOptions();
         return { ...configOptions, ...inputOptions };
     }, ...(ngDevMode ? [{ debugName: "effectiveFormOptions" }] : []));
+    /**
+     * Computed derivation logger based on injected config.
+     *
+     * Uses factory pattern to return no-op logger when logging is disabled,
+     * avoiding any logging overhead in production.
+     */
+    derivationLogger = computed(() => {
+        return createDerivationLogger(this.derivationLogConfig, this.logger);
+    }, ...(ngDevMode ? [{ debugName: "derivationLogger" }] : []));
     fieldSignalContext = computed(() => ({
         injector: this.injector,
         value: this.value,
@@ -5577,12 +8803,27 @@ class DynamicForm {
     form = computed(() => {
         return runInInjectionContext(this.injector, () => {
             const setup = this.formSetup();
+            const config = this.config();
             let formInstance;
             untracked(() => this.rootFormRegistry.registerFormValueSignal(this.entity));
-            if (setup.schemaFields && setup.schemaFields.length > 0) {
+            const hasFields = setup.schemaFields && setup.schemaFields.length > 0;
+            const hasFormSchema = config.schema !== undefined;
+            if (hasFields) {
                 const crossFieldCollection = collectCrossFieldEntries(setup.schemaFields);
-                const schema = createSchemaFromFields(setup.schemaFields, setup.registry, crossFieldCollection.validators);
-                formInstance = untracked(() => form(this.entity, schema));
+                // Create schema with both field-level and form-level validation
+                // Type assertion needed due to complex generic type inference between TModel and InferFormValue
+                const combinedSchema = createSchemaFromFields(setup.schemaFields, setup.registry, {
+                    crossFieldValidators: crossFieldCollection.validators,
+                    formLevelSchema: config.schema,
+                });
+                formInstance = untracked(() => form(this.entity, combinedSchema));
+            }
+            else if (hasFormSchema) {
+                // Only form-level schema (no fields with validation)
+                // Non-null assertion safe: hasFormSchema guarantees config.schema is defined
+                // Type assertion needed due to generic type inference
+                const formSchema = createFormLevelSchema(config.schema);
+                formInstance = untracked(() => form(this.entity, formSchema));
             }
             else {
                 formInstance = untracked(() => form(this.entity));
@@ -5628,6 +8869,18 @@ class DynamicForm {
     }, ...(ngDevMode ? [{ debugName: "disabled" }] : []));
     /** Whether the form is currently submitting. */
     submitting = computed(() => this.form()().submitting(), ...(ngDevMode ? [{ debugName: "submitting" }] : []));
+    /**
+     * Configuration for the derivation orchestrator.
+     * Bundles the form-specific signals needed by the orchestrator.
+     *
+     * @internal Used by DERIVATION_ORCHESTRATOR provider.
+     */
+    derivationOrchestratorConfig = {
+        schemaFields: computed(() => this.formSetup().schemaFields),
+        formValue: this.formValue,
+        form: computed(() => this.form()),
+        derivationLogger: this.derivationLogger,
+    };
     // ─────────────────────────────────────────────────────────────────────────────
     // Initialization
     // ─────────────────────────────────────────────────────────────────────────────
@@ -5645,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. ' +
@@ -5656,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'));
@@ -5707,6 +8972,11 @@ class DynamicForm {
     constructor() {
         this.setupEffects();
         this.setupEventHandlers();
+        // Lazily inject the derivation orchestrator to avoid circular dependency.
+        // The orchestrator's constructor sets up RxJS subscriptions that process derivations.
+        afterNextRender(() => {
+            this.injector.get(DERIVATION_ORCHESTRATOR);
+        });
     }
     /**
      * Handles native form submission triggered by:
@@ -5768,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) {
@@ -5784,6 +9056,10 @@ class DynamicForm {
                 this.functionRegistry.registerCustomFunction(name, fn);
             });
         }
+        // Register derivation functions (stored separately for use by derivation applicator)
+        if (customFnConfig.derivations) {
+            this.functionRegistry.setDerivationFunctions(customFnConfig.derivations);
+        }
         this.functionRegistry.setValidators(customFnConfig.validators);
         this.functionRegistry.setAsyncValidators(customFnConfig.asyncValidators);
         this.functionRegistry.setHttpValidators(customFnConfig.httpValidators);
@@ -5855,6 +9131,17 @@ 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,
+                useFactory: derivationOrchestratorFactoryWrapper,
+                deps: [DynamicForm],
+            },
         ], ngImport: i0, template: `
     @if (formModeDetection().mode === 'paged') {
       <div page-orchestrator [pageFields]="pageFieldDefinitions()" [form]="form()" [fieldSignalContext]="fieldSignalContext()"></div>
@@ -5897,6 +9184,17 @@ 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,
+                            useFactory: derivationOrchestratorFactoryWrapper,
+                            deps: [DynamicForm],
+                        },
                     ], host: {
                         class: 'df-dynamic-form df-form',
                         novalidate: '', // Disable browser validation - Angular Signal Forms handles validation
@@ -6081,13 +9379,13 @@ const BUILT_IN_FIELDS = [
     },
     {
         name: 'page',
-        loadComponent: () => import('./ng-forge-dynamic-forms-page-field.component-Bt6blv9I.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-DKCx7Z_U.mjs'),
+        loadComponent: () => import('./ng-forge-dynamic-forms-text-field.component-DIVyioMX.mjs'),
         mapper: textFieldMapper,
         valueHandling: 'exclude',
     },
@@ -6098,46 +9396,6 @@ const BUILT_IN_FIELDS = [
     },
 ];
 
-/**
- * Type guard to check if a value is a DynamicFormFeature
- */
-function isDynamicFormFeature(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        'ɵkind' in value &&
-        typeof value.ɵkind === 'string' &&
-        'ɵproviders' in value &&
-        Array.isArray(value.ɵproviders));
-}
-/**
- * Helper to create a feature with proper typing
- */
-function createFeature(kind, providers) {
-    return {
-        ɵkind: kind,
-        ɵproviders: providers,
-    };
-}
-
-/**
- * Console-based logger implementation.
- */
-class ConsoleLogger {
-    prefix = '[Dynamic Forms]';
-    debug(message, ...args) {
-        console.debug(this.prefix, message, ...args);
-    }
-    info(message, ...args) {
-        console.info(this.prefix, message, ...args);
-    }
-    warn(message, ...args) {
-        console.warn(this.prefix, message, ...args);
-    }
-    error(message, ...args) {
-        console.error(this.prefix, message, ...args);
-    }
-}
-
 /**
  * Provider function to configure the dynamic form system with field types and options.
  *
@@ -6232,52 +9490,76 @@ function provideDynamicForm(...items) {
 }
 
 /**
- * No-operation logger implementation.
- * All methods are no-ops - used in production by default.
+ * 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
  */
-class NoopLogger {
-    debug() {
-        // Intentionally empty
-    }
-    info() {
-        // Intentionally empty
-    }
-    warn() {
-        // Intentionally empty
-    }
-    error() {
-        // Intentionally empty
-    }
+function withEventFormValue() {
+    return createFeature('event-form-value', [{ provide: EMIT_FORM_VALUE_ON_EVENTS, useValue: true }]);
 }
 
 /**
- * Configure logging for dynamic forms.
+ * Type guard to check if a form event has a form value attached.
  *
- * By default, logging is enabled (ConsoleLogger). Use this feature to disable logging
- * or configure it conditionally.
+ * 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
- * // Disable logging
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withLoggerConfig(false)
- * )
- *
- * // Conditional logging (e.g., only in dev mode)
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withLoggerConfig(() => isDevMode())
- * )
+ * eventBus.on<SubmitEvent>('submit').subscribe(event => {
+ *   if (hasFormValue(event)) {
+ *     console.log('Form value:', event.formValue);
+ *   }
+ * });
  * ```
  *
- * @param enabled - Whether logging is enabled. Can be a boolean or a function that returns a boolean. Defaults to true.
- * @returns A DynamicFormFeature that configures logging
+ * @param event - The form event to check
+ * @returns `true` if the event has a form value attached, narrowing the type
+ *
+ * @public
  */
-function withLoggerConfig(enabled = true) {
-    const isEnabled = typeof enabled === 'function' ? enabled() : enabled;
-    const logger = isEnabled ? new ConsoleLogger() : new NoopLogger();
-    return createFeature('logger', [{ provide: DynamicFormLogger, useValue: logger }]);
+function hasFormValue(event) {
+    return 'formValue' in event && event.formValue !== undefined;
 }
 
 /**
@@ -6535,6 +9817,232 @@ function resolveTokens(args, context) {
     });
 }
 
+/**
+ * Type-safe form config builder that ensures schema matches field structure.
+ *
+ * This helper function provides type safety when using form-level schemas by
+ * automatically inferring the form value type from fields and constraining
+ * the schema type parameter accordingly.
+ *
+ * **When to use:**
+ * - When you have a form-level `schema` and want type safety between fields and schema
+ * - When you prefer function syntax over `as const satisfies FormConfig`
+ *
+ * **Note:** This is optional. Users who don't need schema type safety can
+ * continue using `as const satisfies FormConfig` directly.
+ *
+ * @typeParam TFields - The field definitions array (narrowed via `as const`)
+ * @typeParam TProps - Optional form-level default props type
+ *
+ * @param config - The form configuration object
+ * @returns The same configuration with proper type inference
+ *
+ * @example Basic usage with Zod schema
+ * ```typescript
+ * import { z } from 'zod';
+ * import { formConfig } from '@ng-forge/dynamic-forms';
+ * import { standardSchema } from '@ng-forge/dynamic-forms/schema';
+ *
+ * const passwordSchema = z.object({
+ *   password: z.string().min(8),
+ *   confirmPassword: z.string(),
+ * }).refine(
+ *   (data) => data.password === data.confirmPassword,
+ *   { message: 'Passwords must match', path: ['confirmPassword'] }
+ * );
+ *
+ * const config = formConfig({
+ *   schema: standardSchema(passwordSchema),
+ *   fields: [
+ *     { key: 'password', type: 'input', label: 'Password', required: true, props: { type: 'password' } },
+ *     { key: 'confirmPassword', type: 'input', label: 'Confirm', required: true, props: { type: 'password' } },
+ *     { key: 'submit', type: 'submit', label: 'Register' },
+ *   ] as const,
+ * });
+ * ```
+ *
+ * @example Equivalent without helper
+ * ```typescript
+ * const config = {
+ *   schema: standardSchema(passwordSchema),
+ *   fields: [...],
+ * } as const satisfies FormConfig;
+ * ```
+ */
+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
@@ -7281,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();
@@ -7355,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
@@ -7535,10 +11061,6 @@ function extractErrorParams(error) {
  * - Field mappers (valueFieldMapper, checkboxFieldMapper, etc.)
  * - Error utilities (createResolvedErrorsSignal, shouldShowErrors)
  *
- * ## Testing API
- * Import from '@ng-forge/dynamic-forms/testing' for:
- * - Test utilities and harnesses
- * - Form config builders for testing
  */
 // ============================================================
 // PUBLIC API - For end users
@@ -7549,5 +11071,5 @@ function extractErrorParams(error) {
  * Generated bundle index. Do not edit.
  */
 
-export { applyValidators as $, AddArrayItemEvent as A, baseFieldMapper as B, ConsoleLogger as C, DynamicFormLogger as D, EventBus as E, FormClearEvent as F, buildBaseInputs as G, arrayFieldMapper as H, groupFieldMapper as I, pageFieldMapper as J, rowFieldMapper as K, textFieldMapper as L, FIELD_REGISTRY as M, NoopLogger as N, ARRAY_CONTEXT as O, PageChangeEvent as P, DEFAULT_PROPS as Q, RemoveArrayItemEvent as R, SubmitEvent as S, DEFAULT_VALIDATION_MESSAGES as T, FIELD_SIGNAL_CONTEXT as U, FORM_OPTIONS as V, dynamicTextToObservable as W, ArrayFieldComponent as X, GroupFieldComponent as Y, RowFieldComponent as Z, applyValidator as _, DynamicTextPipe as a, getArrayLength as a0, resolveTokens as a1, BUILT_IN_FIELDS as a2, omit as a3, interpolateParams as a4, applyMetaToElement as a5, RootFormRegistryService as a6, 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, DynamicFormError as z };
-//# sourceMappingURL=ng-forge-dynamic-forms-ng-forge-dynamic-forms-DHxoGouT.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