@ng-forge/dynamic-forms 0.3.1 → 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 { ValidationError as ValidationError$1, FieldContext, TreeValidationResult, FieldTree, 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, ResourceRef, Injector, WritableSignal, InjectionToken, Type, OnDestroy, InputSignal, Provider, EnvironmentProviders, PipeTransform } 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]>;
@@ -299,19 +300,151 @@ type IncludedKeys = 'label' | 'className' | 'hidden' | 'tabIndex';
 type FieldComponent<T extends FieldDef<unknown, FieldMeta>> = Prettify<WithInputSignals<Pick<T, IncludedKeys>>>;
 
 /**
- * Re-export Angular's ValidationError for consistency
- * This replaces our custom ValidationError interface
+ * Field signal context - the "nervous system" of the dynamic form.
+ * Provided via FIELD_SIGNAL_CONTEXT injection token.
+ *
+ * Gives mappers and components access to form state, values, and configuration.
+ * Container fields (Group, Array) create scoped contexts with nested forms.
+ *
+ * The `form` property uses Angular's FieldTree which includes Subfields<TModel>
+ * for type-safe child field access via bracket notation when TModel is a Record.
+ *
+ * Note: Form-level configuration (defaultValidationMessages, formOptions, defaultProps)
+ * is provided via dedicated injection tokens (DEFAULT_VALIDATION_MESSAGES, FORM_OPTIONS,
+ * DEFAULT_PROPS) at the DynamicForm level and inherited by all children.
  */
-type ValidationError = ValidationError$1;
-interface ValidationMessages {
-    required?: DynamicText;
-    email?: DynamicText;
-    min?: DynamicText;
-    max?: DynamicText;
-    minLength?: DynamicText;
-    maxLength?: DynamicText;
-    pattern?: DynamicText;
-    [key: string]: DynamicText | undefined;
+interface FieldSignalContext<TModel extends Record<string, unknown> = Record<string, unknown>> {
+    injector: Injector;
+    value: WritableSignal<Partial<TModel> | undefined>;
+    defaultValues: () => TModel;
+    form: FieldTree<TModel>;
+    /** Current page validity signal for paged forms. Used by next button to determine disabled state. */
+    currentPageValid?: Signal<boolean>;
+}
+/**
+ * Array context for fields rendered within arrays.
+ * Provides position and parent array information for components inside array fields.
+ */
+interface ArrayContext {
+    /** The key of the parent array field. */
+    arrayKey: string;
+    /**
+     * The index of this item within the array.
+     * Uses linkedSignal to automatically update when items are added/removed,
+     * allowing index-dependent logic to react without component recreation.
+     */
+    index: Signal<number>;
+    /** The current form value for token resolution. */
+    formValue: unknown;
+    /** The array field definition. */
+    field: FieldDef<unknown>;
+}
+/**
+ * Mapper function that converts a field definition to component inputs.
+ *
+ * Mappers run within an injection context and can inject FIELD_SIGNAL_CONTEXT.
+ * Returns a Signal to enable reactive updates when dependencies change.
+ */
+type MapperFn<T extends FieldDef<unknown>> = (input: T) => Signal<Record<string, unknown>>;
+
+/**
+ * Defines how a field type handles form values and data collection.
+ *
+ * - 'include': Field contributes to form values (default for input fields)
+ * - 'exclude': Field is excluded from form values (for display/layout fields)
+ * - 'flatten': Field's children are flattened to parent level (for container fields)
+ */
+type ValueHandlingMode = 'include' | 'exclude' | 'flatten';
+/**
+ * Configuration interface for registering custom field types.
+ *
+ * Defines how a field type should be handled by the dynamic form system,
+ * including its component loading strategy and field-to-component mapping logic.
+ * Supports both eager-loaded and lazy-loaded components.
+ *
+ * @typeParam T - The field definition type this field type handles
+ *
+ * @example
+ * ```typescript
+ * const CustomInputType: FieldTypeDefinition<InputFieldDef> = {
+ *   name: 'custom-input',
+ *   loadComponent: () => import('./custom-input.component').then(m => m.CustomInputComponent),
+ *   mapper: customInputMapper
+ * };
+ *
+ * // Register with providers
+ * provideDynamicForm(CustomInputType)
+ * ```
+ */
+interface FieldTypeDefinition<T extends FieldDef<any> = any> {
+    /** Unique identifier for the field type */
+    name: string;
+    /** Field definition type marker (internal use) */
+    _fieldDef?: T;
+    /**
+     * Function to load the component (supports lazy loading).
+     * Returns a Promise that resolves to the component class or module with default export.
+     *
+     * Optional - omit for componentless fields (e.g., hidden fields) that only
+     * contribute to form values without rendering any UI.
+     */
+    loadComponent?: () => Promise<any>;
+    /**
+     * Mapper function that converts field definition to component bindings.
+     *
+     * Optional - omit for componentless fields (like hidden fields) that don't need
+     * input mapping. When omitted for componentless fields (no loadComponent), an empty
+     * signal is returned. When omitted for regular fields with a component, falls back
+     * to baseFieldMapper.
+     */
+    mapper?: MapperFn<T>;
+    /** How this field type handles form values and data collection (defaults to 'include') */
+    valueHandling?: ValueHandlingMode;
+    /**
+     * List of prop keys to forward to the meta object.
+     *
+     * Some props (like `type` for inputs, `rows`/`cols` for textareas) are actually
+     * native HTML attributes. Specifying them here causes them to be merged into
+     * the meta object before being passed to the component, ensuring they're applied
+     * via the meta tracking mechanism.
+     *
+     * Note: Meta values always take precedence over forwarded props.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   name: 'input',
+     *   propsToMeta: ['type'],
+     *   // ...
+     * }
+     * ```
+     */
+    propsToMeta?: string[];
+}
+/**
+ * Injection token for the global field type registry.
+ *
+ * Provides access to the map of registered field types throughout the application.
+ * The registry is populated by the provideDynamicForm function and used by
+ * field rendering components to resolve field types to their implementations.
+ *
+ * @example
+ * ```typescript
+ * constructor(@Inject(FIELD_REGISTRY) private registry: Map<string, FieldTypeDefinition>) {
+ *   const inputType = registry.get('input');
+ * }
+ * ```
+ */
+declare const FIELD_REGISTRY: InjectionToken<Map<string, FieldTypeDefinition<any>>>;
+
+/**
+ * Resolved field ready for rendering with ngComponentOutlet.
+ */
+interface ResolvedField {
+    key: string;
+    component: Type<unknown>;
+    injector: Injector;
+    inputs: Signal<Record<string, unknown>>;
 }
 
 /**
@@ -620,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
@@ -644,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.
  *
@@ -693,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
@@ -892,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
@@ -1340,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;
@@ -1348,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;
 }
@@ -1393,6 +1880,22 @@ interface EvaluationContext<TValue = unknown> {
  */
 type CustomFunction = (context: EvaluationContext) => unknown;
 
+/**
+ * Re-export Angular's ValidationError for consistency
+ * This replaces our custom ValidationError interface
+ */
+type ValidationError = ValidationError$1;
+interface ValidationMessages {
+    required?: DynamicText;
+    email?: DynamicText;
+    min?: DynamicText;
+    max?: DynamicText;
+    minLength?: DynamicText;
+    maxLength?: DynamicText;
+    pattern?: DynamicText;
+    [key: string]: DynamicText | undefined;
+}
+
 /**
  * The result type for submission actions.
  * Can be either a Promise or an Observable.
@@ -1545,10 +2048,11 @@ interface SubmissionConfig<TValue = unknown> {
  *
  * @typeParam TFields - Array of registered field types available for this form
  * @typeParam TValue - The strongly-typed interface for form values
+ * @typeParam TProps - The type for form-level default props (library-specific)
  *
  * @public
  */
-interface FormConfig<TFields extends NarrowFields | RegisteredFieldTypes[] = RegisteredFieldTypes[], TValue = InferFormValue$1<TFields extends readonly RegisteredFieldTypes[] ? TFields : RegisteredFieldTypes[]>> {
+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.
      *
@@ -1567,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.
      *
@@ -1659,6 +2176,32 @@ interface FormConfig<TFields extends NarrowFields | RegisteredFieldTypes[] = Reg
      * ```
      */
     submission?: SubmissionConfig<TValue>;
+    /**
+     * Default props applied to all fields in the form.
+     *
+     * These props serve as defaults that can be overridden at the field level.
+     * Useful for setting consistent styling across the entire form (e.g., appearance,
+     * size, or other UI library-specific props).
+     *
+     * The cascade order is: Library config → Form defaultProps → Field props
+     * Each level can override the previous one.
+     *
+     * @example
+     * ```typescript
+     * // Material example
+     * const config: MatFormConfig = {
+     *   defaultProps: {
+     *     appearance: 'outline',
+     *     subscriptSizing: 'dynamic',
+     *   },
+     *   fields: [
+     *     { type: 'input', key: 'name', label: 'Name' },  // Uses defaultProps
+     *     { type: 'input', key: 'email', props: { appearance: 'fill' } },  // Override
+     *   ],
+     * };
+     * ```
+     */
+    defaultProps?: TProps;
 }
 /**
  * Signal forms adapter configuration for advanced form behavior.
@@ -1676,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(' ')
@@ -1718,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
      *
@@ -1930,226 +2548,92 @@ interface FormOptions {
      */
     disabled?: boolean;
     /**
-     * Default disabled behavior for submit buttons.
+     * Maximum number of iterations for derivation chain processing.
      *
-     * Controls when submit buttons are automatically disabled.
-     * Can be overridden per-button via the `logic` array on individual button fields.
+     * 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.
      *
-     * @example
-     * ```typescript
-     * options: {
-     *   submitButton: {
-     *     disableWhenInvalid: true,      // Disable when form is invalid
-     *     disableWhileSubmitting: true,  // Disable during submission
-     *   }
-     * }
-     * ```
+     * Increase this value if you have legitimate deep derivation chains
+     * (more than 10 levels deep).
+     *
+     * @default 10
      */
-    submitButton?: SubmitButtonOptions;
+    maxDerivationIterations?: number;
     /**
-     * Default disabled behavior for next page buttons.
+     * Default disabled behavior for submit buttons.
      *
-     * Controls when next page buttons are automatically disabled in paged forms.
+     * Controls when submit buttons are automatically disabled.
      * Can be overridden per-button via the `logic` array on individual button fields.
      *
      * @example
      * ```typescript
      * options: {
-     *   nextButton: {
-     *     disableWhenPageInvalid: true,  // Disable when current page is invalid
+     *   submitButton: {
+     *     disableWhenInvalid: true,      // Disable when form is invalid
      *     disableWhileSubmitting: true,  // Disable during submission
      *   }
      * }
      * ```
      */
-    nextButton?: NextButtonOptions;
-}
-/**
- * Options for controlling submit button disabled behavior.
- *
- * @public
- */
-interface SubmitButtonOptions {
-    /**
-     * Disable submit button when the form is invalid.
-     *
-     * @default true
-     */
-    disableWhenInvalid?: boolean;
-    /**
-     * Disable submit button while the form is submitting.
-     *
-     * Requires `submission.action` to be configured for automatic detection.
-     *
-     * @default true
-     */
-    disableWhileSubmitting?: boolean;
-}
-/**
- * Options for controlling next page button disabled behavior.
- *
- * @public
- */
-interface NextButtonOptions {
-    /**
-     * Disable next button when the current page has invalid fields.
-     *
-     * @default true
-     */
-    disableWhenPageInvalid?: boolean;
-    /**
-     * Disable next button while the form is submitting.
-     *
-     * @default true
-     */
-    disableWhileSubmitting?: boolean;
-}
-
-/**
- * Field signal context - the "nervous system" of the dynamic form.
- * Provided via FIELD_SIGNAL_CONTEXT injection token.
- *
- * Gives mappers and components access to form state, values, and configuration.
- * Container fields (Group, Array) create scoped contexts with nested forms.
- *
- * The `form` property uses Angular's FieldTree which includes Subfields<TModel>
- * for type-safe child field access via bracket notation when TModel is a Record.
- */
-interface FieldSignalContext<TModel extends Record<string, unknown> = Record<string, unknown>> {
-    injector: Injector;
-    value: WritableSignal<Partial<TModel> | undefined>;
-    defaultValues: () => TModel;
-    form: FieldTree<TModel>;
-    defaultValidationMessages?: ValidationMessages;
-    /** Form-level options used by button mappers to determine disabled state defaults. */
-    formOptions?: FormOptions;
-    /** Current page validity signal for paged forms. Used by next button to determine disabled state. */
-    currentPageValid?: Signal<boolean>;
-}
-/**
- * Array context for fields rendered within arrays.
- * Provides position and parent array information for components inside array fields.
- */
-interface ArrayContext {
-    /** The key of the parent array field. */
-    arrayKey: string;
-    /**
-     * The index of this item within the array.
-     * Uses linkedSignal to automatically update when items are added/removed,
-     * allowing index-dependent logic to react without component recreation.
-     */
-    index: Signal<number>;
-    /** The current form value for token resolution. */
-    formValue: unknown;
-    /** The array field definition. */
-    field: FieldDef<unknown>;
-}
-/**
- * Mapper function that converts a field definition to component inputs.
- *
- * Mappers run within an injection context and can inject FIELD_SIGNAL_CONTEXT.
- * Returns a Signal to enable reactive updates when dependencies change.
- */
-type MapperFn<T extends FieldDef<unknown>> = (input: T) => Signal<Record<string, unknown>>;
-
-/**
- * Defines how a field type handles form values and data collection.
- *
- * - 'include': Field contributes to form values (default for input fields)
- * - 'exclude': Field is excluded from form values (for display/layout fields)
- * - 'flatten': Field's children are flattened to parent level (for container fields)
- */
-type ValueHandlingMode = 'include' | 'exclude' | 'flatten';
-/**
- * Configuration interface for registering custom field types.
- *
- * Defines how a field type should be handled by the dynamic form system,
- * including its component loading strategy and field-to-component mapping logic.
- * Supports both eager-loaded and lazy-loaded components.
- *
- * @typeParam T - The field definition type this field type handles
- *
- * @example
- * ```typescript
- * const CustomInputType: FieldTypeDefinition<InputFieldDef> = {
- *   name: 'custom-input',
- *   loadComponent: () => import('./custom-input.component').then(m => m.CustomInputComponent),
- *   mapper: customInputMapper
- * };
- *
- * // Register with providers
- * provideDynamicForm(CustomInputType)
- * ```
- */
-interface FieldTypeDefinition<T extends FieldDef<any> = any> {
-    /** Unique identifier for the field type */
-    name: string;
-    /** Field definition type marker (internal use) */
-    _fieldDef?: T;
-    /**
-     * Function to load the component (supports lazy loading).
-     * Returns a Promise that resolves to the component class or module with default export.
-     *
-     * Optional - omit for componentless fields (e.g., hidden fields) that only
-     * contribute to form values without rendering any UI.
-     */
-    loadComponent?: () => Promise<any>;
-    /**
-     * Mapper function that converts field definition to component bindings.
-     *
-     * Optional - omit for componentless fields (like hidden fields) that don't need
-     * input mapping. When omitted for componentless fields (no loadComponent), an empty
-     * signal is returned. When omitted for regular fields with a component, falls back
-     * to baseFieldMapper.
-     */
-    mapper?: MapperFn<T>;
-    /** How this field type handles form values and data collection (defaults to 'include') */
-    valueHandling?: ValueHandlingMode;
+    submitButton?: SubmitButtonOptions;
     /**
-     * List of prop keys to forward to the meta object.
-     *
-     * Some props (like `type` for inputs, `rows`/`cols` for textareas) are actually
-     * native HTML attributes. Specifying them here causes them to be merged into
-     * the meta object before being passed to the component, ensuring they're applied
-     * via the meta tracking mechanism.
+     * Default disabled behavior for next page buttons.
      *
-     * Note: Meta values always take precedence over forwarded props.
+     * Controls when next page buttons are automatically disabled in paged forms.
+     * Can be overridden per-button via the `logic` array on individual button fields.
      *
      * @example
      * ```typescript
-     * {
-     *   name: 'input',
-     *   propsToMeta: ['type'],
-     *   // ...
+     * options: {
+     *   nextButton: {
+     *     disableWhenPageInvalid: true,  // Disable when current page is invalid
+     *     disableWhileSubmitting: true,  // Disable during submission
+     *   }
      * }
      * ```
      */
-    propsToMeta?: string[];
+    nextButton?: NextButtonOptions;
 }
 /**
- * Injection token for the global field type registry.
- *
- * Provides access to the map of registered field types throughout the application.
- * The registry is populated by the provideDynamicForm function and used by
- * field rendering components to resolve field types to their implementations.
+ * Options for controlling submit button disabled behavior.
  *
- * @example
- * ```typescript
- * constructor(@Inject(FIELD_REGISTRY) private registry: Map<string, FieldTypeDefinition>) {
- *   const inputType = registry.get('input');
- * }
- * ```
+ * @public
  */
-declare const FIELD_REGISTRY: InjectionToken<Map<string, FieldTypeDefinition<any>>>;
-
+interface SubmitButtonOptions {
+    /**
+     * Disable submit button when the form is invalid.
+     *
+     * @default true
+     */
+    disableWhenInvalid?: boolean;
+    /**
+     * Disable submit button while the form is submitting.
+     *
+     * Requires `submission.action` to be configured for automatic detection.
+     *
+     * @default true
+     */
+    disableWhileSubmitting?: boolean;
+}
 /**
- * Resolved field ready for rendering with ngComponentOutlet.
+ * Options for controlling next page button disabled behavior.
+ *
+ * @public
  */
-interface ResolvedField {
-    key: string;
-    component: Type<unknown>;
-    injector: Injector;
-    inputs: Signal<Record<string, unknown>>;
+interface NextButtonOptions {
+    /**
+     * Disable next button when the current page has invalid fields.
+     *
+     * @default true
+     */
+    disableWhenPageInvalid?: boolean;
+    /**
+     * Disable next button while the form is submitting.
+     *
+     * @default true
+     */
+    disableWhileSubmitting?: boolean;
 }
 
 /**
@@ -2210,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.
  *
@@ -2369,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. */
@@ -2385,14 +2973,26 @@ 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.
+     * Other form-level tokens (DEFAULT_PROPS, etc.) are provided at component level.
+     */
     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;
@@ -2418,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>;
@@ -2618,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(),
@@ -2639,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.
@@ -2731,6 +3375,82 @@ declare const FIELD_SIGNAL_CONTEXT: InjectionToken<FieldSignalContext<Record<str
  * ```
  */
 declare const ARRAY_CONTEXT: InjectionToken<ArrayContext>;
+/**
+ * Injection token for form-level default props.
+ *
+ * Default props are form-wide property defaults that are merged with field-level props.
+ * Field props take precedence over default props.
+ *
+ * Unlike FIELD_SIGNAL_CONTEXT which is re-provided by container components (Group, Array),
+ * DEFAULT_PROPS is provided ONCE at the DynamicForm level and inherited by all children
+ * via Angular's hierarchical injector.
+ *
+ * The token provides a Signal to enable reactivity - when config changes, mappers
+ * that read the signal inside their computed() will automatically update.
+ *
+ * @example
+ * ```typescript
+ * // In a mapper function
+ * const defaultPropsSignal = inject(DEFAULT_PROPS);
+ *
+ * return computed(() => {
+ *   const defaultProps = defaultPropsSignal?.();  // Read inside computed for reactivity
+ *   const baseInputs = buildBaseInputs(fieldDef, defaultProps);
+ *   // ...
+ * });
+ * ```
+ */
+declare const DEFAULT_PROPS: InjectionToken<Signal<Record<string, unknown> | undefined>>;
+/**
+ * Injection token for form-level default validation messages.
+ *
+ * Default validation messages act as fallbacks when fields have validation
+ * errors but no field-level `validationMessages` defined.
+ *
+ * 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 to enable reactivity - when config changes, mappers
+ * that read the signal inside their computed() will automatically update.
+ *
+ * @example
+ * ```typescript
+ * // In a mapper or component
+ * const defaultMessagesSignal = inject(DEFAULT_VALIDATION_MESSAGES);
+ *
+ * return computed(() => {
+ *   const defaultMessages = defaultMessagesSignal?.();  // Read inside computed for reactivity
+ *   const message = defaultMessages?.required ?? 'Field is required';
+ *   // ...
+ * });
+ * ```
+ */
+declare const DEFAULT_VALIDATION_MESSAGES: InjectionToken<Signal<ValidationMessages | undefined>>;
+/**
+ * Injection token for form-level options.
+ *
+ * Form options control form-wide behavior including button disabled states.
+ * Used by button mappers to determine default disabled behavior.
+ *
+ * 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 to enable reactivity - when config changes, mappers
+ * that read the signal inside their computed() will automatically update.
+ *
+ * @example
+ * ```typescript
+ * // In a button mapper
+ * const formOptionsSignal = inject(FORM_OPTIONS);
+ *
+ * return computed(() => {
+ *   const formOptions = formOptionsSignal?.();  // Read inside computed for reactivity
+ *   const disableWhenInvalid = formOptions?.submitButton?.disableWhenInvalid ?? true;
+ *   // ...
+ * });
+ * ```
+ */
+declare const FORM_OPTIONS: InjectionToken<Signal<FormOptions | undefined>>;
 
 /**
  * Context for resolving button disabled state.
@@ -2817,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[];
 }
 
@@ -2835,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 {
@@ -3060,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.
  *
@@ -3079,9 +3892,10 @@ declare class DynamicFormError extends Error {
  * Used by mappers to build the inputs record.
  *
  * @param fieldDef The field definition to extract properties from
+ * @param defaultProps Optional form-level default props to merge with field props
  * @returns Record of input names to values
  */
-declare function buildBaseInputs(fieldDef: FieldDef<unknown>): Record<string, unknown>;
+declare function buildBaseInputs(fieldDef: FieldDef<unknown>, defaultProps?: Record<string, unknown>): Record<string, unknown>;
 /**
  * Base field mapper that extracts common field properties into component inputs.
  *
@@ -3367,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()
@@ -3396,5 +4236,98 @@ declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): O
  */
 declare function interpolateParams(message: string, error: ValidationError): string;
 
-export { ARRAY_CONTEXT, AddArrayItemEvent, ArrayFieldComponent, BUILT_IN_FIELDS, ConsoleLogger, DynamicForm, DynamicFormError, DynamicFormLogger, DynamicTextPipe, EventBus, FIELD_REGISTRY, FIELD_SIGNAL_CONTEXT, FormClearEvent, FormResetEvent, GroupFieldComponent, NextPageEvent, NoopLogger, PageChangeEvent, PreviousPageEvent, RemoveArrayItemEvent, 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 };
+/**
+ * Registry service that maintains references to root form fields.
+ * This provides a type-safe way to access root form values from child fields
+ * without relying on internal Angular Forms API navigation.
+ *
+ * This service should be provided at the component level to ensure proper
+ * isolation between different form instances.
+ *
+ * IMPORTANT: This registry supports two registration patterns:
+ * 1. registerFormValueSignal() - Register the SOURCE signal BEFORE form creation
+ *    This allows logic functions to read form values during schema evaluation.
+ * 2. registerRootForm() - Register the FieldTree AFTER form creation
+ *    This provides access to the full form structure.
+ *
+ * For cross-field logic to work correctly, registerFormValueSignal() should be
+ * called BEFORE the form() call.
+ */
+declare class RootFormRegistryService {
+    private readonly _rootForms;
+    private readonly _formValueSignals;
+    private readonly formContexts;
+    /**
+     * Registers the form value signal BEFORE form creation.
+     *
+     * This is the recommended pattern for cross-field logic:
+     * 1. Create the formValue signal
+     * 2. Register it with registerFormValueSignal()
+     * 3. Create the form with form(formValue, schema(...))
+     *
+     * This allows logic functions to access form values during schema evaluation.
+     */
+    registerFormValueSignal(valueSignal: Signal<Record<string, unknown>>, formId?: string): void;
+    /**
+     * Gets the registered form value signal by id.
+     *
+     * This allows direct access to the source signal, which can be read
+     * reactively to get form values.
+     */
+    getFormValueSignal(formId?: string): Signal<Record<string, unknown>> | undefined;
+    /**
+     * Registers a root form field with an optional identifier.
+     * If no id is provided, uses 'default' as the key.
+     *
+     * This triggers reactive updates for any computed signals that
+     * depend on getRootForm().
+     */
+    registerRootForm(rootField: FieldTree<unknown>, formId?: string): void;
+    /**
+     * Gets a registered root form field by id.
+     *
+     * IMPORTANT: This method reads from a signal, which means any computed
+     * signal that calls this method will automatically re-evaluate when
+     * the form is registered or updated.
+     */
+    getRootForm(formId?: string): FieldTree<unknown> | undefined;
+    /**
+     * Gets the form value, preferring the direct signal if available.
+     *
+     * This method tries in order:
+     * 1. Form value signal (if registered) - reads directly from source signal
+     * 2. Root form's .value() (if registered) - reads from FieldTree
+     * 3. Returns empty object if nothing is registered
+     *
+     * Reading from signals creates reactive dependencies, so computeds will
+     * re-evaluate when form values change.
+     */
+    getFormValue(formId?: string): Record<string, unknown>;
+    /**
+     * Registers form context (field paths and metadata) for a specific form.
+     * This can be used to store additional context information.
+     */
+    registerFormContext(context: Record<string, unknown>, formId?: string): void;
+    /**
+     * Gets form context by id.
+     */
+    getFormContext(formId?: string): Record<string, unknown>;
+    /**
+     * Unregisters a form and its context.
+     * This should be called when a form component is destroyed to prevent memory leaks.
+     */
+    unregisterForm(formId?: string): void;
+    /**
+     * Gets all registered form IDs.
+     */
+    getRegisteredFormIds(): string[];
+    /**
+     * Clears all registered forms. Useful for testing.
+     */
+    clear(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<RootFormRegistryService, never>;
+    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, 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 };