@ng-forge/dynamic-forms 0.4.0 → 0.5.0

package/types/ng-forge-dynamic-forms.d.ts

@@ -1,11 +1,12 @@
 import * as rxjs from 'rxjs';
 import { Observable } from 'rxjs';
-import * as _angular_forms from '@angular/forms';
 import * as _angular_forms_signals from '@angular/forms/signals';
-import { FieldTree, FieldContext, ValidationError as ValidationError$1, TreeValidationResult, Schema, SchemaPath, SchemaPathTree } from '@angular/forms/signals';
+import { FieldTree, FieldContext, ValidationError as ValidationError$1, TreeValidationResult, SchemaPath, SchemaPathTree } from '@angular/forms/signals';
+import * as _angular_forms from '@angular/forms';
 import * as _ng_forge_dynamic_forms from '@ng-forge/dynamic-forms';
 import * as _angular_core from '@angular/core';
 import { Signal, Injector, WritableSignal, InjectionToken, Type, ResourceRef, OnDestroy, InputSignal, Provider, EnvironmentProviders, PipeTransform } from '@angular/core';
+import { FormSchema } from '@ng-forge/dynamic-forms/schema';
 
 type WithInputSignals<T> = {
     readonly [K in keyof T]-?: Signal<T[K]>;
@@ -752,7 +753,86 @@ type FormStateCondition =
 /** True when fields on the current page are invalid (for paged forms) */
  | 'pageInvalid';
 /**
- * Configuration for conditional field logic.
+ * Logic type for controlling field state (hidden, readonly, disabled, required).
+ *
+ * @public
+ */
+type StateLogicType = 'hidden' | 'readonly' | 'disabled' | 'required';
+/**
+ * Base configuration for conditional field state logic.
+ *
+ * @internal
+ */
+interface BaseStateLogicConfig {
+    /**
+     * Logic type identifier for field state.
+     *
+     * - `hidden`: Hide the field from view (still participates in form state)
+     * - `readonly`: Make the field read-only
+     * - `disabled`: Disable user interaction
+     * - `required`: Make the field required
+     */
+    type: StateLogicType;
+    /**
+     * Condition that determines when this logic applies.
+     *
+     * Can be:
+     * - `boolean`: Static value (always applies or never applies)
+     * - `ConditionalExpression`: Expression evaluated against field/form values
+     * - `FormStateCondition`: Special form/page state check (for buttons)
+     *
+     * @example
+     * ```typescript
+     * // Static condition
+     * condition: true
+     *
+     * // Field value condition
+     * condition: {
+     *   type: 'fieldValue',
+     *   fieldPath: 'status',
+     *   operator: 'equals',
+     *   value: 'locked'
+     * }
+     *
+     * // Form state condition (for buttons)
+     * condition: 'formSubmitting'
+     * ```
+     */
+    condition: ConditionalExpression | boolean | FormStateCondition;
+}
+/**
+ * State logic that evaluates immediately on change (default).
+ *
+ * @internal
+ */
+interface ImmediateStateLogicConfig extends BaseStateLogicConfig {
+    /**
+     * Trigger for immediate evaluation.
+     * @default 'onChange'
+     */
+    trigger?: 'onChange';
+    /** Not allowed for onChange trigger */
+    debounceMs?: never;
+}
+/**
+ * State logic that evaluates after a debounce period.
+ *
+ * @internal
+ */
+interface DebouncedStateLogicConfig extends BaseStateLogicConfig {
+    /**
+     * Trigger for debounced evaluation.
+     * Evaluates after the value has stabilized for the debounce duration.
+     */
+    trigger: 'debounced';
+    /**
+     * Debounce duration in milliseconds.
+     * @default 500
+     */
+    debounceMs?: number;
+}
+/**
+ * Configuration for conditional field state logic.
  *
  * Defines how field behavior changes based on conditions.
  * Supports hiding, disabling, making readonly, or requiring fields
@@ -776,47 +856,278 @@ type FormStateCondition =
  *   type: 'disabled',
  *   condition: 'formSubmitting'
  * }
+ *
+ * // Debounced visibility (avoids flicker during rapid typing)
+ * {
+ *   type: 'hidden',
+ *   trigger: 'debounced',
+ *   debounceMs: 300,
+ *   condition: {
+ *     type: 'fieldValue',
+ *     fieldPath: 'search',
+ *     operator: 'isEmpty'
+ *   }
+ * }
  * ```
  *
  * @public
  */
-interface LogicConfig {
+type StateLogicConfig = ImmediateStateLogicConfig | DebouncedStateLogicConfig;
+/**
+ * Base configuration for value derivation logic.
+ *
+ * @internal
+ */
+interface BaseDerivationLogicConfig {
+    /**
+     * Logic type identifier for value derivation.
+     */
+    type: 'derivation';
     /**
-     * Logic type identifier.
+     * Optional name for this derivation for debugging purposes.
      *
-     * - `hidden`: Hide the field from view (still participates in form state)
-     * - `readonly`: Make the field read-only
-     * - `disabled`: Disable user interaction
-     * - `required`: Make the field required
+     * When provided, this name appears in derivation debug logs,
+     * making it easier to identify specific derivations in complex forms.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   type: 'derivation',
+     *   debugName: 'Calculate line total',
+     *   targetField: '$.lineTotal',
+     *   expression: 'formValue.quantity * formValue.unitPrice'
+     * }
+     * ```
      */
-    type: 'hidden' | 'readonly' | 'disabled' | 'required';
+    debugName?: string;
     /**
-     * Condition that determines when this logic applies.
+     * The field whose value will be modified.
+     *
+     * Can be:
+     * - Absolute path: 'fieldName' or 'nested.field.path'
+     * - Relative path for arrays: '$.siblingField' (same index as source)
+     *
+     * @example
+     * ```typescript
+     * targetField: 'phonePrefix'           // Absolute path
+     * targetField: 'address.country'       // Nested path
+     * targetField: '$.lineTotal'           // Relative path (array sibling)
+     * ```
+     */
+    targetField: string;
+    /**
+     * Condition that determines when this derivation applies.
      *
      * Can be:
      * - `boolean`: Static value (always applies or never applies)
      * - `ConditionalExpression`: Expression evaluated against field/form values
-     * - `FormStateCondition`: Special form/page state check (for buttons)
+     *
+     * Defaults to `true` (always apply).
+     *
+     * Note: FormStateCondition is not supported for derivations.
      *
      * @example
      * ```typescript
-     * // Static condition
+     * // Always compute (default)
      * condition: true
      *
-     * // Field value condition
+     * // Conditional derivation
      * condition: {
      *   type: 'fieldValue',
-     *   fieldPath: 'status',
+     *   fieldPath: 'country',
      *   operator: 'equals',
-     *   value: 'locked'
+     *   value: 'USA'
      * }
+     * ```
+     */
+    condition?: ConditionalExpression | boolean;
+    /**
+     * Static value to set on the target field.
      *
-     * // Form state condition (for buttons)
-     * condition: 'formSubmitting'
+     * Use when the derived value is a constant.
+     * Mutually exclusive with `expression` and `functionName`.
+     *
+     * @example
+     * ```typescript
+     * value: '+1'           // String
+     * value: 100            // Number
+     * value: true           // Boolean
+     * value: { code: 'US' } // Object
      * ```
      */
-    condition: ConditionalExpression | boolean | FormStateCondition;
+    value?: unknown;
+    /**
+     * JavaScript expression to evaluate for the derived value.
+     *
+     * Has access to `formValue` object containing all form values.
+     * Uses the same secure AST-based parser as other expressions.
+     * Mutually exclusive with `value` and `functionName`.
+     *
+     * @example
+     * ```typescript
+     * expression: 'formValue.quantity * formValue.unitPrice'
+     * expression: 'formValue.firstName + " " + formValue.lastName'
+     * expression: 'formValue.price * (1 - formValue.discount / 100)'
+     * ```
+     */
+    expression?: string;
+    /**
+     * Name of a registered custom derivation function.
+     *
+     * The function receives the evaluation context and returns the derived value.
+     * Register functions in `customFnConfig.derivations`.
+     * Mutually exclusive with `value` and `expression`.
+     *
+     * @example
+     * ```typescript
+     * functionName: 'getCurrencyForCountry'
+     * functionName: 'calculateTax'
+     * functionName: 'formatPhoneNumber'
+     * ```
+     */
+    functionName?: string;
+    /**
+     * Explicit field dependencies for derivations.
+     *
+     * When using `functionName`, you can optionally specify which fields
+     * the function depends on. This enables more efficient re-evaluation
+     * by only triggering when specific dependencies change.
+     *
+     * If not provided with `functionName`, defaults to all fields ('*').
+     * For `expression`, dependencies are automatically extracted from the expression.
+     * For `value`, no dependencies are needed (static value).
+     *
+     * @example
+     * ```typescript
+     * // Only re-evaluate when country changes
+     * {
+     *   type: 'derivation',
+     *   targetField: 'currency',
+     *   functionName: 'getCurrencyForCountry',
+     *   dependsOn: ['country']
+     * }
+     *
+     * // Override automatic detection for complex expressions
+     * {
+     *   type: 'derivation',
+     *   targetField: 'total',
+     *   expression: 'calculateTotal(formValue)',
+     *   dependsOn: ['quantity', 'unitPrice', 'discount']
+     * }
+     * ```
+     */
+    dependsOn?: string[];
+}
+/**
+ * Derivation logic that evaluates immediately on change (default).
+ *
+ * @internal
+ */
+interface OnChangeDerivationLogicConfig extends BaseDerivationLogicConfig {
+    /**
+     * Trigger for immediate evaluation.
+     * @default 'onChange'
+     */
+    trigger?: 'onChange';
+    /** Not allowed for onChange trigger */
+    debounceMs?: never;
+}
+/**
+ * Derivation logic that evaluates after a debounce period.
+ *
+ * Use this for self-transforms (lowercase, trim, format) to avoid
+ * interrupting the user while they're actively typing.
+ *
+ * @internal
+ */
+interface DebouncedDerivationLogicConfig extends BaseDerivationLogicConfig {
+    /**
+     * Trigger for debounced evaluation.
+     * Evaluates after the value has stabilized for the debounce duration.
+     */
+    trigger: 'debounced';
+    /**
+     * Debounce duration in milliseconds.
+     * @default 500
+     */
+    debounceMs?: number;
 }
+/**
+ * Configuration for value derivation logic.
+ *
+ * Enables programmatic value derivation based on conditions.
+ * When the condition is met, the target field's value is set
+ * using a static value, expression, or custom function.
+ *
+ * @example
+ * ```typescript
+ * // Set phone prefix based on country selection
+ * {
+ *   type: 'derivation',
+ *   targetField: 'phonePrefix',
+ *   value: '+1',
+ *   condition: {
+ *     type: 'fieldValue',
+ *     fieldPath: 'country',
+ *     operator: 'equals',
+ *     value: 'USA'
+ *   }
+ * }
+ *
+ * // Compute total from quantity and price
+ * {
+ *   type: 'derivation',
+ *   targetField: 'total',
+ *   expression: 'formValue.quantity * formValue.unitPrice'
+ * }
+ *
+ * // Use custom function for complex logic
+ * {
+ *   type: 'derivation',
+ *   targetField: 'currency',
+ *   functionName: 'getCurrencyForCountry'
+ * }
+ *
+ * // Self-transform with debounced trigger
+ * // (applies after user stops typing)
+ * {
+ *   type: 'derivation',
+ *   targetField: 'email',
+ *   expression: 'formValue.email.toLowerCase()',
+ *   trigger: 'debounced',
+ *   debounceMs: 500
+ * }
+ *
+ * // Relative path for array items
+ * {
+ *   type: 'derivation',
+ *   targetField: '$.lineTotal',  // Same array index as source field
+ *   expression: 'formValue.quantity * formValue.unitPrice'
+ * }
+ * ```
+ *
+ * @public
+ */
+type DerivationLogicConfig = OnChangeDerivationLogicConfig | DebouncedDerivationLogicConfig;
+/**
+ * Union type for all logic configurations.
+ *
+ * - `StateLogicConfig`: For field state changes (hidden, readonly, disabled, required)
+ * - `DerivationLogicConfig`: For value derivation
+ *
+ * @public
+ */
+type LogicConfig = StateLogicConfig | DerivationLogicConfig;
+/**
+ * Log level for derivation debug output.
+ *
+ * - 'none': No debug logging
+ * - 'summary': Log cycle completion with counts (default in dev mode)
+ * - 'verbose': Log individual derivation evaluations with details
+ *
+ * @public
+ */
+type DerivationLogLevel = 'none' | 'summary' | 'verbose';
 /**
  * Type guard to check if a condition is a FormStateCondition.
  *
@@ -825,7 +1136,7 @@ interface LogicConfig {
  *
  * @public
  */
-declare function isFormStateCondition(condition: LogicConfig['condition']): condition is FormStateCondition;
+declare function isFormStateCondition(condition: StateLogicConfig['condition'] | DerivationLogicConfig['condition']): condition is FormStateCondition;
 
 /**
  * Text element type for rendering different HTML text elements
@@ -1024,11 +1335,17 @@ type ProcessField<T, D extends number = 5> = [D] extends [never] ? Record<string
     [P in K]: Record<string, unknown>;
 } : never : T extends {
     type: 'text';
+} ? never : T extends {
+    type: 'submit' | 'button';
 } ? never : T extends {
     key: infer K;
     value: infer V;
 } ? K extends string ? {
     [P in K]: MaybeOptional<T, InferValueType<T, V>>;
+} : never : T extends {
+    key: infer K;
+} ? K extends string ? {
+    [P in K]: MaybeOptional<T, string>;
 } : never : never;
 /**
  * Internal helper with depth tracking
@@ -1472,7 +1789,13 @@ interface Logger {
 interface EvaluationContext<TValue = unknown> {
     /** Current field value */
     fieldValue: TValue;
-    /** Complete form value */
+    /**
+     * Form value for the current evaluation scope.
+     *
+     * For regular (non-array) derivations, this contains the complete form value.
+     * For array item derivations, this is scoped to the current array item.
+     * Use `rootFormValue` to access the complete form when inside an array context.
+     */
     formValue: Record<string, unknown>;
     /** Field path for relative references */
     fieldPath: string;
@@ -1480,6 +1803,38 @@ interface EvaluationContext<TValue = unknown> {
     customFunctions?: Record<string, (context: EvaluationContext) => unknown>;
     /** Logger for diagnostic output */
     logger: Logger;
+    /**
+     * Root form value when inside an array context.
+     *
+     * This provides access to values outside the current array item.
+     * When a derivation targets an array item field (e.g., `items.$.lineTotal`),
+     * `formValue` is scoped to the current array item, while `rootFormValue`
+     * provides access to the entire form value including fields outside the array.
+     *
+     * @example
+     * ```typescript
+     * // In an array item derivation (e.g., lineItems.$.lineTotal):
+     * {
+     *   type: 'derivation',
+     *   targetField: '$.lineTotal',
+     *   // formValue = current array item { quantity: 2, unitPrice: 50 }
+     *   // rootFormValue = entire form { globalDiscount: 0.1, lineItems: [...] }
+     *   expression: 'formValue.quantity * formValue.unitPrice * (1 - rootFormValue.globalDiscount)'
+     * }
+     * ```
+     *
+     * For non-array derivations, `rootFormValue` is not set and `formValue`
+     * contains the entire form value.
+     */
+    rootFormValue?: Record<string, unknown>;
+    /**
+     * Current array index when inside an array derivation.
+     */
+    arrayIndex?: number;
+    /**
+     * Path to the array field when inside an array derivation.
+     */
+    arrayPath?: string;
     /** Allow additional properties for flexible expression evaluation */
     [key: string]: unknown;
 }
@@ -1697,7 +2052,7 @@ interface SubmissionConfig<TValue = unknown> {
  *
  * @public
  */
-interface FormConfig<TFields extends NarrowFields | RegisteredFieldTypes[] = RegisteredFieldTypes[], TValue = InferFormValue$1<TFields extends readonly RegisteredFieldTypes[] ? TFields : RegisteredFieldTypes[]>, TProps extends object = Record<string, unknown>> {
+interface FormConfig<TFields extends NarrowFields | RegisteredFieldTypes[] = RegisteredFieldTypes[], TValue = InferFormValue$1<TFields extends readonly RegisteredFieldTypes[] ? TFields : RegisteredFieldTypes[]>, TProps extends object = Record<string, unknown>, TSchemaValue = unknown> {
     /**
      * Array of field definitions that define the form structure.
      *
@@ -1716,19 +2071,32 @@ interface FormConfig<TFields extends NarrowFields | RegisteredFieldTypes[] = Reg
      */
     fields: TFields;
     /**
-     * Optional form-level validation schema.
+     * Optional form-level validation schema using Standard Schema spec.
      *
      * Provides additional validation beyond field-level validation.
+     * Supports Zod, Valibot, ArkType, and other Standard Schema compliant libraries.
      * Useful for cross-field validation rules.
      *
      * @example
      * ```typescript
-     * schema: {
-     *   passwordConfirm: validators.equals('password')
-     * }
+     * import { z } from 'zod';
+     * 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 formConfig = {
+     *   fields: [...],
+     *   schema: standardSchema(PasswordSchema),
+     * } as const satisfies FormConfig;
      * ```
      */
-    schema?: Schema<TValue>;
+    schema?: FormSchema<TSchemaValue>;
     /**
      * Global form configuration options.
      *
@@ -1851,6 +2219,14 @@ interface FormConfig<TFields extends NarrowFields | RegisteredFieldTypes[] = Reg
  *       currency: 'USD'
  *     }).format(context.value)
  *   },
+ *   derivations: {
+ *     getCurrencyForCountry: (context) => {
+ *       const countryToCurrency: Record<string, string> = {
+ *         'USA': 'USD', 'Germany': 'EUR', 'UK': 'GBP'
+ *       };
+ *       return countryToCurrency[context.formValue.country as string] ?? 'USD';
+ *     }
+ *   },
  *   simpleValidators: {
  *     noSpaces: (value) => {
  *       return typeof value === 'string' && value.includes(' ')
@@ -1893,6 +2269,73 @@ interface CustomFnConfig {
      * ```
      */
     customFunctions?: Record<string, CustomFunction>;
+    /**
+     * Custom derivation functions for value derivation logic.
+     *
+     * These functions compute derived values and are called when a
+     * `DerivationLogicConfig` references them by `functionName`.
+     *
+     * Derivation functions:
+     * - Receive an `EvaluationContext` with access to `formValue`
+     * - Return the value to set on the target field
+     * - Are called reactively when dependencies change
+     *
+     * Use derivation functions for complex mappings or logic that
+     * can't be easily expressed as a JavaScript expression.
+     *
+     * @example
+     * ```typescript
+     * derivations: {
+     *   // Country to currency mapping
+     *   getCurrencyForCountry: (context) => {
+     *     const countryToCurrency: Record<string, string> = {
+     *       'USA': 'USD',
+     *       'Germany': 'EUR',
+     *       'France': 'EUR',
+     *       'UK': 'GBP',
+     *       'Japan': 'JPY'
+     *     };
+     *     return countryToCurrency[context.formValue.country as string] ?? 'USD';
+     *   },
+     *
+     *   // Complex tax calculation
+     *   calculateTax: (context) => {
+     *     const subtotal = context.formValue.subtotal as number ?? 0;
+     *     const state = context.formValue.state as string;
+     *     const taxRates: Record<string, number> = {
+     *       'CA': 0.0725, 'NY': 0.08, 'TX': 0.0625
+     *     };
+     *     return subtotal * (taxRates[state] ?? 0);
+     *   },
+     *
+     *   // Format phone number
+     *   formatPhoneNumber: (context) => {
+     *     const phone = context.fieldValue as string ?? '';
+     *     const digits = phone.replace(/\D/g, '');
+     *     if (digits.length === 10) {
+     *       return `(${digits.slice(0,3)}) ${digits.slice(3,6)}-${digits.slice(6)}`;
+     *     }
+     *     return phone;
+     *   }
+     * }
+     * ```
+     *
+     * Field configuration using a derivation function:
+     * ```typescript
+     * {
+     *   key: 'country',
+     *   type: 'select',
+     *   logic: [
+     *     {
+     *       type: 'derivation',
+     *       targetField: 'currency',
+     *       functionName: 'getCurrencyForCountry'
+     *     }
+     *   ]
+     * }
+     * ```
+     */
+    derivations?: Record<string, CustomFunction>;
     /**
      * Custom validators using Angular's public FieldContext API
      *
@@ -2104,6 +2547,19 @@ interface FormOptions {
      * @value false
      */
     disabled?: boolean;
+    /**
+     * Maximum number of iterations for derivation chain processing.
+     *
+     * Derivations can trigger other derivations (e.g., A → B → C).
+     * This limit prevents infinite loops in case of circular dependencies
+     * that weren't caught at build time.
+     *
+     * Increase this value if you have legitimate deep derivation chains
+     * (more than 10 levels deep).
+     *
+     * @default 10
+     */
+    maxDerivationIterations?: number;
     /**
      * Default disabled behavior for submit buttons.
      *
@@ -2238,6 +2694,109 @@ type FieldPathAccess<TValue> = {
     [K in keyof TValue]: SchemaPath<TValue[K]> | SchemaPathTree<TValue[K]>;
 };
 
+/**
+ * Result of processing all pending derivations.
+ *
+ * @public
+ */
+interface DerivationProcessingResult {
+    /** Number of derivations successfully applied */
+    appliedCount: number;
+    /** Number of derivations skipped (condition not met or value unchanged) */
+    skippedCount: number;
+    /** Number of derivations that failed with errors */
+    errorCount: number;
+    /**
+     * Number of derivations that encountered warnings (e.g., missing target field).
+     *
+     * These are not counted as errors because they may be intentional (conditional fields)
+     * but indicate potential configuration issues if unexpected.
+     */
+    warnCount: number;
+    /** Total iterations performed */
+    iterations: number;
+    /** Whether max iterations was reached (potential loop) */
+    maxIterationsReached: boolean;
+}
+
+/**
+ * Information about a single derivation evaluation for logging.
+ *
+ * @public
+ */
+interface DerivationLogEntry {
+    /** Debug name if provided in the derivation config */
+    debugName?: string;
+    /** Source field key where the derivation is defined */
+    sourceFieldKey: string;
+    /** Target field key that will be modified */
+    targetFieldKey: string;
+    /** Result of the derivation evaluation */
+    result: 'applied' | 'skipped' | 'error';
+    /** Reason for skipping (if result is 'skipped') */
+    skipReason?: 'condition-false' | 'value-unchanged' | 'already-applied' | 'target-not-found';
+    /** The new value that was set (if result is 'applied') */
+    newValue?: unknown;
+    /** The previous value before the derivation (if result is 'applied') */
+    previousValue?: unknown;
+    /** Error message (if result is 'error') */
+    error?: string;
+    /** Duration in milliseconds (optional, for performance tracking) */
+    durationMs?: number;
+}
+
+/**
+ * Service interface for derivation logging.
+ *
+ * Provides methods to log derivation processing events at different verbosity levels.
+ * Use `DERIVATION_LOGGER` injection token to get an instance.
+ *
+ * @public
+ */
+interface DerivationLogger {
+    /**
+     * Logs the start of a derivation processing cycle.
+     * Only logs when config level is 'verbose'.
+     */
+    cycleStart(trigger: 'onChange' | 'debounced', entryCount: number): void;
+    /**
+     * Logs the start of a derivation iteration within a cycle.
+     * Only logs when config level is 'verbose'.
+     */
+    iteration(iterationNumber: number): void;
+    /**
+     * Logs a single derivation evaluation result.
+     * Only logs when config level is 'verbose'.
+     */
+    evaluation(entry: DerivationLogEntry): void;
+    /**
+     * Logs a summary of derivation processing results.
+     * Logs when config level is 'summary' or 'verbose' and something interesting happened.
+     */
+    summary(result: DerivationProcessingResult, trigger: 'onChange' | 'debounced'): void;
+    /**
+     * Logs when max iterations are reached (always logged as warning).
+     */
+    maxIterationsReached(result: DerivationProcessingResult, trigger: 'onChange' | 'debounced'): void;
+}
+
+/**
+ * Minimal configuration for creating a DerivationOrchestrator.
+ * Only includes form-specific signals that cannot be injected.
+ *
+ * @internal
+ */
+interface DerivationOrchestratorConfig {
+    /** Signal containing the flattened schema fields */
+    schemaFields: Signal<FieldDef<unknown>[] | undefined>;
+    /** Signal containing the current form value */
+    formValue: Signal<Record<string, unknown>>;
+    /** Signal containing the form accessor */
+    form: Signal<FieldTree<unknown>>;
+    /** Signal containing the derivation logger */
+    derivationLogger: Signal<DerivationLogger>;
+}
+
 /**
  * Base interface for all form events in the dynamic form system.
  *
@@ -2397,6 +2956,7 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
     private readonly functionRegistry;
     private readonly schemaRegistry;
     private readonly logger;
+    private readonly derivationLogConfig;
     /** Form configuration defining the structure, validation, and behavior. */
     config: InputSignal<FormConfig<TFields>>;
     /** Runtime form options that override config options when provided. */
@@ -2413,9 +2973,17 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
     readonly pageFieldDefinitions: Signal<PageField<_ng_forge_dynamic_forms.PageAllowedChildren[]>[]>;
     readonly effectiveFormOptions: Signal<{
         disabled?: boolean;
+        maxDerivationIterations?: number;
         submitButton?: _ng_forge_dynamic_forms.SubmitButtonOptions;
         nextButton?: _ng_forge_dynamic_forms.NextButtonOptions;
     }>;
+    /**
+     * 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.
+     */
+    private readonly derivationLogger;
     readonly fieldSignalContext: Signal<FieldSignalContext<TModel>>;
     /**
      * Injector for field components with FIELD_SIGNAL_CONTEXT.
@@ -2424,7 +2992,7 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
     private readonly fieldInjector;
     readonly defaultValues: _angular_core.WritableSignal<TModel>;
     private readonly entity;
-    readonly form: Signal<_angular_forms_signals.FieldTree<TModel, string | number>>;
+    readonly form: Signal<FieldTree<TModel, string | number>>;
     private readonly componentId;
     private readonly totalComponentsCount;
     private readonly fieldsSource;
@@ -2450,6 +3018,13 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
     readonly disabled: Signal<boolean>;
     /** Whether the form is currently submitting. */
     readonly submitting: Signal<boolean>;
+    /**
+     * Configuration for the derivation orchestrator.
+     * Bundles the form-specific signals needed by the orchestrator.
+     *
+     * @internal Used by DERIVATION_ORCHESTRATOR provider.
+     */
+    readonly derivationOrchestratorConfig: DerivationOrchestratorConfig;
     readonly initialized$: rxjs.Observable<boolean>;
     /** Emits when form validity changes. */
     readonly validityChange: _angular_core.OutputRef<boolean>;
@@ -2650,20 +3225,55 @@ type ExtractFormValue<T> = T extends {
  */
 declare const BUILT_IN_FIELDS: FieldTypeDefinition[];
 
+/**
+ * Configuration options for the logger feature.
+ *
+ * @public
+ */
+interface LoggerConfigOptions {
+    /**
+     * Whether general logging is enabled.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Derivation logging level.
+     *
+     * - `'none'`: No derivation debug logging (default)
+     * - `'summary'`: Log cycle completion with counts
+     * - `'verbose'`: Log individual derivation evaluations with details
+     *
+     * @default 'none'
+     */
+    derivations?: DerivationLogLevel;
+}
 /**
  * Configure logging for dynamic forms.
  *
- * By default, logging is enabled (ConsoleLogger). Use this feature to disable logging
- * or configure it conditionally.
+ * By default, general logging is enabled (ConsoleLogger) and derivation
+ * logging is disabled ('none'). Use this feature to enable derivation debugging.
  *
  * @example
  * ```typescript
- * // Disable logging
+ * // 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(),
@@ -2671,10 +3281,12 @@ declare const BUILT_IN_FIELDS: FieldTypeDefinition[];
  * )
  * ```
  *
- * @param enabled - Whether logging is enabled. Can be a boolean or a function that returns a boolean. Defaults to true.
+ * @param config - Boolean to enable/disable logging, a function returning boolean, or a config object
  * @returns A DynamicFormFeature that configures logging
+ *
+ * @public
  */
-declare function withLoggerConfig(enabled?: boolean | (() => boolean)): DynamicFormFeature<'logger'>;
+declare function withLoggerConfig(config?: boolean | (() => boolean) | LoggerConfigOptions): DynamicFormFeature<'logger'>;
 
 /**
  * Injection token for the dynamic forms logger.
@@ -2925,6 +3537,43 @@ interface FieldWithValidation {
     readonly validators?: ValidatorConfig[];
     readonly validationMessages?: ValidationMessages;
     readonly logic?: LogicConfig[];
+    /**
+     * Shorthand for simple computed/derived fields.
+     *
+     * The expression is evaluated whenever its dependencies change,
+     * and the result is set as this field's value.
+     *
+     * Has access to `formValue` object containing all form values.
+     * Uses the same secure AST-based parser as other expressions.
+     *
+     * For conditional derivations or derivations targeting other fields,
+     * use the full `logic` array with `{ type: 'derivation', ... }`.
+     *
+     * @example
+     * ```typescript
+     * // Compute total from quantity and price
+     * {
+     *   key: 'total',
+     *   type: 'number',
+     *   derivation: 'formValue.quantity * formValue.unitPrice'
+     * }
+     *
+     * // Concatenate names
+     * {
+     *   key: 'fullName',
+     *   type: 'input',
+     *   derivation: 'formValue.firstName + " " + formValue.lastName'
+     * }
+     *
+     * // Calculate discounted price
+     * {
+     *   key: 'discountedPrice',
+     *   type: 'number',
+     *   derivation: 'formValue.price * (1 - formValue.discountPercent / 100)'
+     * }
+     * ```
+     */
+    readonly derivation?: string;
     readonly schemas?: SchemaApplicationConfig[];
 }
 
@@ -2943,7 +3592,7 @@ interface BaseValueField<TProps, TValue, TMeta extends FieldMeta = FieldMeta> ex
     required?: boolean;
 }
 declare function isValueField<TProps, TMeta extends FieldMeta = FieldMeta>(field: FieldDef<TProps, TMeta>): field is BaseValueField<TProps, ValueType, TMeta>;
-type ExcludedKeys$1 = 'type' | 'conditionals' | 'value' | 'valueType' | 'disabled' | 'readonly' | 'hidden' | 'col' | 'minValue' | 'maxValue' | 'step' | 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern' | 'validators' | 'logic' | 'schemas';
+type ExcludedKeys$1 = 'type' | 'conditionals' | 'value' | 'valueType' | 'disabled' | 'readonly' | 'hidden' | 'col' | 'minValue' | 'maxValue' | 'step' | 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern' | 'validators' | 'logic' | 'derivation' | 'schemas';
 type ValueFieldComponent<T extends BaseValueField<Record<string, unknown> | unknown, unknown>> = Prettify<WithInputSignals<Omit<T, ExcludedKeys$1>>>;
 
 interface BaseCheckedField<TProps, TMeta extends FieldMeta = FieldMeta> extends FieldDef<TProps, TMeta>, FieldWithValidation {
@@ -3168,6 +3817,62 @@ interface ArrayItemContext {
     formValue?: unknown;
 }
 
+/**
+ * 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;
+ * ```
+ */
+declare function formConfig<const TFields extends NarrowFields, TProps extends object = Record<string, unknown>>(config: Omit<FormConfig<TFields, InferFormValue$1<TFields>, TProps>, 'schema'> & {
+    schema?: FormSchema<InferFormValue$1<TFields>>;
+}): FormConfig<TFields, InferFormValue$1<TFields>, TProps>;
+
 /**
  * Base error class for all Dynamic Forms errors.
  *
@@ -3476,6 +4181,32 @@ declare function getArrayLength<T>(arrayFieldTree: ArrayFieldTree<T>): number;
  * 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
+ * ```
+ */
+declare function isEqual(a: unknown, b: unknown): boolean;
 /**
  * Creates a new object without the specified keys
  * Native replacement for lodash omit()
@@ -3598,5 +4329,5 @@ declare class RootFormRegistryService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<RootFormRegistryService>;
 }
 
-export { ARRAY_CONTEXT, AddArrayItemEvent, ArrayFieldComponent, BUILT_IN_FIELDS, ConsoleLogger, DEFAULT_PROPS, DEFAULT_VALIDATION_MESSAGES, DynamicForm, DynamicFormError, DynamicFormLogger, DynamicTextPipe, EventBus, FIELD_REGISTRY, FIELD_SIGNAL_CONTEXT, FORM_OPTIONS, FormClearEvent, FormResetEvent, GroupFieldComponent, NextPageEvent, NoopLogger, PageChangeEvent, PreviousPageEvent, RemoveArrayItemEvent, RootFormRegistryService, RowFieldComponent, SubmitEvent, applyMetaToElement, applyValidator, applyValidators, arrayFieldMapper, baseFieldMapper, buildBaseInputs, dynamicTextToObservable, getArrayLength, groupFieldMapper, interpolateParams, isArrayField, isCheckedField, isContainerField, isDisplayOnlyField, isFormStateCondition, isGroupField, isLeafField, isPageField, isRowField, isValueBearingField, isValueField, omit, pageFieldMapper, provideDynamicForm, resolveNextButtonDisabled, resolveSubmitButtonDisabled, resolveTokens, rowFieldMapper, textFieldMapper, withLoggerConfig };
+export { ARRAY_CONTEXT, AddArrayItemEvent, ArrayFieldComponent, BUILT_IN_FIELDS, ConsoleLogger, DEFAULT_PROPS, DEFAULT_VALIDATION_MESSAGES, DynamicForm, DynamicFormError, DynamicFormLogger, DynamicTextPipe, EventBus, FIELD_REGISTRY, FIELD_SIGNAL_CONTEXT, FORM_OPTIONS, FormClearEvent, FormResetEvent, GroupFieldComponent, NextPageEvent, NoopLogger, PageChangeEvent, PreviousPageEvent, RemoveArrayItemEvent, RootFormRegistryService, RowFieldComponent, SubmitEvent, applyMetaToElement, applyValidator, applyValidators, arrayFieldMapper, baseFieldMapper, buildBaseInputs, dynamicTextToObservable, formConfig, getArrayLength, groupFieldMapper, interpolateParams, isArrayField, isCheckedField, isContainerField, isDisplayOnlyField, isEqual, isFormStateCondition, isGroupField, isLeafField, isPageField, isRowField, isValueBearingField, isValueField, omit, pageFieldMapper, provideDynamicForm, resolveNextButtonDisabled, resolveSubmitButtonDisabled, resolveTokens, rowFieldMapper, textFieldMapper, withLoggerConfig };
 export type { ArrayAllowedChildren, ArrayContext, ArrayField, ArrayFieldTree, ArrayItemContext, AsyncCustomValidator, AsyncValidatorConfig, AvailableFieldTypes, BaseCheckedField, BaseValidatorConfig, BaseValueField, BuiltInValidatorConfig, ButtonLogicContext, CheckedFieldComponent, ConditionalExpression, ContainerFieldTypes, CustomFnConfig, CustomValidator, CustomValidatorConfig, DynamicFormFieldRegistry, DynamicText, EvaluationContext, ExtractField, ExtractFieldDefs, ExtractFormValue, FieldComponent, FieldDef, FieldMeta, FieldOption, FieldPathAccess, FieldRegistryContainers, FieldRegistryLeaves, FieldSignalContext, FieldTypeDefinition, FieldWithValidation, FormConfig, FormEvent, FormEventConstructor, FormMode, FormModeDetectionResult, FormOptions, FormStateCondition, GroupAllowedChildren, GroupField, HttpCustomValidator, HttpResourceRequest, HttpValidatorConfig, InferFormValue$1 as InferFormValue, LeafFieldTypes, Logger, LogicConfig, MapperFn, NarrowField, NarrowFields, NextButtonOptions, PageAllowedChildren, PageField, Prettify, RegisteredFieldTypes, RowAllowedChildren, RowField, SchemaApplicationConfig, SchemaDefinition, SubmissionActionResult, SubmissionConfig, SubmitButtonOptions, TextElementType, TextField, TextProps, TokenContext, ValidationError, ValidationMessages, ValidatorConfig, ValueFieldComponent, ValueHandlingMode, ValueType, WithInputSignals };