@ng-forge/dynamic-forms 0.9.0-next.10 → 0.9.0-next.12

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

@@ -16,502 +16,631 @@ type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
 
-type DynamicText = string | Observable<string> | Signal<string>;
-
 /**
- * Configuration for an HTTP request used by declarative HTTP validators, derivations, and conditions.
- *
- * All string values in `queryParams` are treated as expressions evaluated by ExpressionParser.
- * When `evaluateBodyExpressions` is true, top-level string values in `body` are also evaluated as expressions (shallow only).
+ * Interface for dynamic forms logger implementations.
+ * Allows custom logging integrations (Sentry, DataDog, etc.)
  */
-interface HttpRequestConfig {
-    /** URL to send the request to */
-    url: string;
-    /** HTTP method. Defaults to 'GET' */
-    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+interface Logger {
     /**
-     * URL path parameters. Keys correspond to `:key` placeholders in the URL.
-     * Values are expressions evaluated by ExpressionParser against the current EvaluationContext.
-     *
-     * @example
-     * ```typescript
-     * {
-     *   url: '/api/users/:userId/orders/:orderId',
-     *   params: { userId: 'formValue.userId', orderId: 'fieldValue' }
-     * }
-     * // With userId=42 and fieldValue='abc' → '/api/users/42/orders/abc'
-     * ```
+     * Log a debug message.
+     * Use for detailed diagnostic information during development.
      */
-    params?: Record<string, string>;
+    debug(message: string, ...args: unknown[]): void;
     /**
-     * Query parameters appended to the URL.
-     * Values are expressions evaluated by ExpressionParser against the current EvaluationContext.
+     * Log an info message.
+     * Use for general operational information.
      */
-    queryParams?: Record<string, string>;
-    /** Request body (for POST/PUT/PATCH) */
-    body?: Record<string, unknown>;
+    info(message: string, ...args: unknown[]): void;
     /**
-     * When true, top-level string values in `body` are treated as expressions
-     * and evaluated by ExpressionParser (shallow only — nested objects are passed through as-is).
+     * Log a warning message.
+     * Use for potentially problematic situations that don't prevent operation.
      */
-    evaluateBodyExpressions?: boolean;
-    /** HTTP headers to include in the request */
-    headers?: Record<string, string>;
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log an error message.
+     * Use for error conditions that may affect functionality.
+     */
+    error(message: string, ...args: unknown[]): void;
 }
 
 /**
- * Comparison operators for field value and form value conditions.
+ * Shared shape for DI-scoped warning trackers that dedupe log output.
  *
- * @public
- */
-type ComparisonOperator = 'equals' | 'notEquals' | 'greater' | 'less' | 'greaterOrEqual' | 'lessOrEqual' | 'contains' | 'startsWith' | 'endsWith' | 'matches';
-/**
- * Condition that compares a specific field's value against an expected value.
+ * Used by both the derivation-warning tracker (keys are field paths) and the
+ * deprecation-warning tracker (keys are deprecation IDs). The property is
+ * generic so the same shape works for any string-keyed warning domain.
  *
- * @public
+ * @internal
  */
-interface FieldValueCondition {
-    type: 'fieldValue';
-    /** Path to the field whose value to compare */
-    fieldPath: string;
-    /** Comparison operator */
-    operator: ComparisonOperator;
-    /** Value to compare against */
-    value?: unknown;
+interface WarningTracker {
+    warnedKeys: Set<string>;
 }
+
 /**
- * Condition that invokes a registered custom function by name.
+ * Represents the state information of a single form field.
  *
- * Register functions via `customFnConfig.customFunctions`.
+ * Used in evaluation contexts to allow expressions and conditions
+ * to reference field state (e.g., `fieldState.touched`, `formFieldState.email.dirty`).
  *
  * @public
  */
-interface CustomCondition {
-    type: 'custom';
-    /** Name of the registered custom function to invoke */
-    functionName: string;
+interface FieldStateInfo {
+    readonly touched: boolean;
+    readonly dirty: boolean;
+    /** Convenience property: equivalent to `!dirty` */
+    readonly pristine: boolean;
+    readonly valid: boolean;
+    readonly invalid: boolean;
+    readonly pending: boolean;
+    /**
+     * Whether the field is currently hidden.
+     *
+     * Note: This is a library-managed property, not a native Angular Signal Forms
+     * property. Returns `false` if the field instance does not expose a `hidden` signal.
+     */
+    readonly hidden: boolean;
+    /**
+     * Whether the field is currently readonly.
+     *
+     * Note: This is a library-managed property, not a native Angular Signal Forms
+     * property. Returns `false` if the field instance does not expose a `readonly` signal.
+     */
+    readonly readonly: boolean;
+    /**
+     * Whether the field is currently disabled.
+     *
+     * Note: This is a library-managed property, not a native Angular Signal Forms
+     * property. Returns `false` if the field instance does not expose a `disabled` signal.
+     */
+    readonly disabled: boolean;
 }
 /**
- * Condition that evaluates a JavaScript expression using the secure AST-based parser.
+ * Map of field keys to their state information.
  *
- * The expression has access to `formValue`, `fieldValue`, `externalData`, etc.
+ * Used as `formFieldState` in evaluation contexts to access
+ * state of any field in the form by key.
  *
  * @public
  */
-interface JavascriptCondition {
-    type: 'javascript';
-    /** JavaScript expression string to evaluate */
-    expression: string;
-}
+type FormFieldStateMap = Record<string, FieldStateInfo | undefined>;
 /**
- * Condition that evaluates based on an HTTP response from a remote server.
- *
- * The HTTP request is resolved reactively — when dependent form values change,
- * the request is re-evaluated (with debouncing). The result is cached per
- * resolved request to avoid redundant network calls.
+ * Field state context for the current field being evaluated.
  *
- * Since `LogicFn` must return `boolean` synchronously, this condition uses
- * a signal-based async resolution pattern internally.
+ * Used as `fieldState` in evaluation contexts.
  *
  * @public
  */
-interface HttpCondition {
-    type: 'http';
-    /** HTTP request configuration */
-    http: HttpRequestConfig;
+type FieldStateContext = FieldStateInfo;
+
+interface EvaluationContext<TValue = unknown, TFormValue extends Record<string, unknown> = any> {
+    /** Current field value */
+    fieldValue: TValue;
     /**
-     * Expression to extract boolean from response (scope: `{ response }`).
-     * e.g. `'response.allowed'`, `'response.permissions.canEdit'`
-     * When omitted, the entire response is coerced to boolean: `!!response`
+     * 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.
      */
-    responseExpression?: string;
+    formValue: TFormValue;
+    /** Field path for relative references */
+    fieldPath: string;
+    /** Custom evaluation functions */
+    customFunctions?: Record<string, (context: EvaluationContext) => unknown>;
+    /** Logger for diagnostic output */
+    logger: Logger;
     /**
-     * Value to return while the HTTP request is in-flight.
+     * Value of the field's nearest parent **group** (or array item, when the
+     * field has no inner group above the array boundary).
      *
-     * Choose based on the logic type and desired UX:
-     * - For `hidden`: `false` = visible while loading, `true` = hidden while loading
-     * - For `disabled`: `false` = enabled while loading, `true` = disabled while loading
-     * - For `required`: `false` = optional while loading, `true` = required while loading
+     * Complements `formValue` and `fieldValue` for derivations on fields nested
+     * inside groups built by factory helpers, where the parent group's key
+     * isn't known at config-authoring time. Mirrors the runtime semantics of
+     * the `'$group'` token used in `dependsOn`.
      *
-     * @default false
-     */
-    pendingValue?: boolean;
-    /** Cache duration in ms for HTTP responses. @default 30000 */
-    cacheDurationMs?: number;
-    /**
-     * Debounce time in milliseconds for re-evaluation when dependent form values change.
-     * @default 300
+     * Resolution at evaluation time:
+     * - Inside a group at form root: the parent group's value object (e.g.,
+     *   for `address.state`, `groupValue === formValue.address`).
+     * - Inside nested groups: the innermost parent group's value object.
+     * - Directly inside an array item (no inner group): the array item itself
+     *   (same shape as `formValue` in array context).
+     * - Inside a group inside an array item: the inner group's value object
+     *   within the current item.
+     * - Field at form root with no parent container: `undefined`.
+     *
+     * @example
+     * ```typescript
+     * // Field 'state' inside group 'address':
+     * deriveStateFromCountry: (ctx) => {
+     *   const country = ctx.groupValue?.country;  // no need to know parent key
+     *   return country === 'usa' ? 'NY' : '';
+     * }
+     * ```
      */
-    debounceMs?: number;
-}
-/**
- * Condition that evaluates based on a registered async function.
- *
- * The function is resolved reactively — when dependent form values change,
- * the function is re-evaluated (with debouncing). The result is cached per
- * evaluation to avoid redundant calls.
- *
- * Since `LogicFn` must return `boolean` synchronously, this condition uses
- * a signal-based async resolution pattern internally.
- *
- * @public
- */
-interface AsyncCondition {
-    type: 'async';
-    /** Name of the registered async condition function */
-    asyncFunctionName: string;
+    groupValue?: unknown;
     /**
-     * Value to return while async resolution is pending.
+     * Root form value when inside an array context.
      *
-     * Choose based on the logic type and desired UX:
-     * - For `hidden`: `false` = visible while loading, `true` = hidden while loading
-     * - For `disabled`: `false` = enabled while loading, `true` = disabled while loading
-     * - For `required`: `false` = optional while loading, `true` = required while loading
+     * 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.
      *
-     * @default false
+     * @example
+     * ```typescript
+     * // In an array item derivation (on the lineTotal field inside lineItems array):
+     * {
+     *   key: 'lineTotal',
+     *   type: 'input',
+     *   // formValue = current array item { quantity: 2, unitPrice: 50 }
+     *   // rootFormValue = entire form { globalDiscount: 0.1, lineItems: [...] }
+     *   derivation: 'formValue.quantity * formValue.unitPrice * (1 - rootFormValue.globalDiscount)'
+     * }
+     * ```
+     *
+     * For non-array derivations, `rootFormValue` is not set and `formValue`
+     * contains the entire form value.
      */
-    pendingValue?: boolean;
+    rootFormValue?: Record<string, unknown>;
     /**
-     * Debounce ms for re-evaluation.
-     * @default 300
+     * Current array index when inside an array derivation.
      */
-    debounceMs?: number;
-}
-/**
- * Logical AND — all sub-conditions must be true.
- *
- * @public
- */
-interface AndCondition {
-    type: 'and';
-    /** Sub-conditions that must all evaluate to true */
-    conditions: ConditionalExpression[];
-}
-/**
- * Logical OR — at least one sub-condition must be true.
- *
- * @public
- */
-interface OrCondition {
-    type: 'or';
-    /** Sub-conditions where at least one must evaluate to true */
-    conditions: ConditionalExpression[];
-}
-/**
- * Discriminated union of all conditional expression types.
- *
- * Each variant only allows the properties relevant to its type,
- * providing compile-time safety against invalid property combinations.
- *
- * @public
- */
-type ConditionalExpression = FieldValueCondition | CustomCondition | JavascriptCondition | HttpCondition | AsyncCondition | AndCondition | OrCondition;
-
-/**
- * Logic configuration for container fields (page, group, row, array).
- * Containers only support the 'hidden' logic type since they are layout containers,
- * not form controls (they can't be readonly, disabled, or required).
- */
-interface ContainerLogicConfig {
-    /** Only 'hidden' is supported for container fields */
-    type: 'hidden';
+    arrayIndex?: number;
     /**
-     * Condition that determines when this container is hidden.
-     * Can be a boolean or a conditional expression evaluated against form values.
+     * Path to the array field when inside an array derivation.
      */
-    condition: ConditionalExpression | boolean;
+    arrayPath?: string;
+    /**
+     * External data signals resolved to their current values.
+     *
+     * This allows forms to reference data from outside the form context
+     * in conditional logic, derivations, and other expressions.
+     *
+     * @example
+     * ```typescript
+     * // In form config:
+     * externalData: {
+     *   userRole: computed(() => this.userService.currentRole()),
+     *   permissions: computed(() => this.authService.permissions()),
+     * }
+     *
+     * // In JavaScript expression:
+     * condition: {
+     *   type: 'javascript',
+     *   expression: "externalData.userRole === 'admin'"
+     * }
+     * ```
+     */
+    externalData?: Record<string, unknown>;
+    /**
+     * DI-scoped tracker for deprecation warnings.
+     * Used by the condition evaluator to deduplicate deprecation warnings.
+     */
+    deprecationTracker?: WarningTracker;
+    /**
+     * State of the current field being evaluated.
+     *
+     * Provides access to field state properties like `touched`, `dirty`, `valid`, etc.
+     * Uses a Proxy for lazy evaluation — properties are only read when accessed.
+     *
+     * @example
+     * ```typescript
+     * // In a JavaScript expression:
+     * condition: {
+     *   type: 'javascript',
+     *   expression: "fieldState.touched && fieldState.dirty"
+     * }
+     * ```
+     */
+    fieldState?: FieldStateContext;
+    /**
+     * State of all fields in the form, keyed by field key.
+     *
+     * Provides access to any field's state properties by key.
+     * Uses a Proxy for lazy evaluation — field state is only read when accessed.
+     *
+     * @example
+     * ```typescript
+     * // In a JavaScript expression:
+     * condition: {
+     *   type: 'javascript',
+     *   expression: "formFieldState.email.dirty && formFieldState.email.valid"
+     * }
+     * ```
+     */
+    formFieldState?: FormFieldStateMap;
+    /** Allow additional properties for flexible expression evaluation */
+    [key: string]: unknown;
 }
 
 /**
- * An array item template is an array of allowed children that defines one OBJECT array item's fields.
- * Used for object arrays where each item is `{ key1: value1, key2: value2, ... }`.
- */
-type ArrayItemTemplate = readonly ArrayAllowedChildren[];
-/**
- * An array item definition can be either:
- * - A single field (ArrayAllowedChildren) for PRIMITIVE array items - extracts field value directly
- * - An array of fields (ArrayItemTemplate) for OBJECT array items - merges fields into object
+ * Custom function signature for conditional expressions
  *
- * This allows support for:
- * - Primitive arrays: `['tag1', 'tag2']`
- * - Object arrays: `[{ name: 'Alice', email: '...' }]`
- * - Heterogeneous arrays: `[{ value: 'x' }, 'y']` (mixed primitives and objects)
- */
-type ArrayItemDefinition = ArrayAllowedChildren | ArrayItemTemplate;
-/**
- * Array field interface for creating dynamic field collections that map to array values.
+ * Custom functions are used for conditional logic in:
+ * - `when` conditions (field visibility, conditional validation)
+ * - `readonly` logic (dynamic readonly state)
+ * - `disabled` logic (dynamic disabled state)
+ * - Dynamic value calculations
  *
- * Key concepts:
- * - The outer `fields` array defines INITIAL ITEMS (each element is one array item to render)
- * - Each element can be either:
- *   - A single FieldDef (primitive item) - the field's value is extracted directly
- *   - An array of FieldDefs (object item) - fields are merged into an object
- * - Items can have different field configurations (heterogeneous arrays supported)
- * - Empty `fields: []` means no initial items - user adds via buttons with explicit templates
- * - Initial values are declared via `value` property on each field definition
+ * Unlike validators, custom functions:
+ * - Return any value (typically boolean for conditions, but could be strings, numbers, etc.)
+ * - Do NOT return ValidationError objects
+ * - Receive EvaluationContext (field values) not FieldContext (field state)
  *
  * @example
- * // Primitive array: ['angular', 'typescript']
+ * ```typescript
+ * // Boolean condition function
+ * const isAdult: CustomFunction = (ctx) => {
+ *   return ctx.age >= 18;
+ * };
+ *
+ * // Used in field configuration:
  * {
- *   key: 'tags',
- *   type: 'array',
- *   fields: [
- *     { key: 'tag', type: 'input', value: 'angular' },      // Single field = primitive
- *     { key: 'tag', type: 'input', value: 'typescript' },
- *   ]
+ *   key: 'alcoholPreference',
+ *   type: 'select',
+ *   when: { function: 'isAdult' }  // Only show if isAdult returns true
  * }
+ * ```
  *
  * @example
- * // Object array: [{ name: 'Alice', email: '...' }]
- * {
- *   key: 'contacts',
- *   type: 'array',
- *   fields: [
- *     [                                                      // Array = object
- *       { key: 'name', type: 'input', value: 'Alice' },
- *       { key: 'email', type: 'input', value: 'alice@example.com' }
- *     ],
- *   ]
- * }
+ * ```typescript
+ * // Calculation function
+ * const calculateDiscount: CustomFunction = (ctx) => {
+ *   const price = ctx.price || 0;
+ *   const isVip = ctx.isVip || false;
+ *   return isVip ? price * 0.8 : price * 0.9;
+ * };
+ * ```
+ */
+type CustomFunction<TFormValue extends Record<string, unknown> = any> = (context: EvaluationContext<unknown, TFormValue>) => unknown;
+
+/**
+ * Async function for derivations — returns any value.
+ *
+ * The function receives the evaluation context and may return a Promise or Observable.
+ * Register functions in `customFnConfig.asyncDerivations`.
  *
  * @example
- * // Heterogeneous array: [{ label: 'Structured' }, 'Simple']
- * {
- *   key: 'items',
- *   type: 'array',
- *   fields: [
- *     [{ key: 'label', type: 'input', value: 'Structured' }],  // Object item
- *     { key: 'value', type: 'input', value: 'Simple' },        // Primitive item
- *   ]
- * }
+ * ```typescript
+ * const fetchPrice: AsyncDerivationFunction = async (context) => {
+ *   const response = await fetch(`/api/price?product=${context.formValue.productId}`);
+ *   const data = await response.json();
+ *   return data.price;
+ * };
+ * ```
+ *
+ * @public
+ */
+type AsyncDerivationFunction<TFormValue extends Record<string, unknown> = any> = (context: EvaluationContext<unknown, TFormValue>) => Promise<unknown> | Observable<unknown>;
+/**
+ * Async function for conditions — returns boolean.
+ *
+ * The function receives the evaluation context and may return a Promise or Observable.
+ * Register functions in `customFnConfig.asyncConditions`.
  *
  * @example
- * // Empty array (add items via buttons)
- * {
- *   key: 'tags',
- *   type: 'array',
- *   fields: []  // No initial items - user adds via button with template
- * }
+ * ```typescript
+ * const checkPermission: AsyncConditionFunction = async (context) => {
+ *   const response = await fetch(`/api/permissions?user=${context.formValue.userId}`);
+ *   const data = await response.json();
+ *   return data.canEdit;
+ * };
+ * ```
  *
- * Nesting constraints: Arrays can contain rows, leaf fields, or groups (for object arrays),
- * but NOT pages or other arrays. Runtime validation enforces these rules.
+ * @public
+ */
+type AsyncConditionFunction<TFormValue extends Record<string, unknown> = any> = (context: EvaluationContext<unknown, TFormValue>) => Promise<boolean> | Observable<boolean>;
+
+/**
+ * Configuration for an HTTP request used by declarative HTTP validators, derivations, and conditions.
  *
- * Note: Arrays are container fields and do not support `meta` since they have no native form element.
+ * All string values in `queryParams` are treated as expressions evaluated by ExpressionParser.
+ * When `evaluateBodyExpressions` is true, top-level string values in `body` are also evaluated as expressions (shallow only).
  */
-interface ArrayField<TFields extends readonly ArrayItemDefinition[] = readonly ArrayItemDefinition[]> extends FieldDef<never> {
-    type: 'array';
+interface HttpRequestConfig {
+    /** URL to send the request to */
+    url: string;
+    /** HTTP method. Defaults to 'GET' */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     /**
-     * Array of item definitions. Each element defines one array item:
-     * - Single FieldDef = primitive item (field's value is extracted directly)
-     * - Array of FieldDefs = object item (fields are merged into an object)
-     * - Empty array `[]` = no initial items (add via buttons with explicit templates)
-     * - Items can have different configurations (heterogeneous arrays supported)
-     * - Initial values are set via `value` property on each field definition
+     * URL path parameters. Keys correspond to `:key` placeholders in the URL.
+     * Values are expressions evaluated by ExpressionParser against the current EvaluationContext.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   url: '/api/users/:userId/orders/:orderId',
+     *   params: { userId: 'formValue.userId', orderId: 'fieldValue' }
+     * }
+     * // With userId=42 and fieldValue='abc' → '/api/users/42/orders/abc'
+     * ```
      */
-    readonly fields: TFields;
-    /** Array fields do not have a label property **/
-    readonly label?: never;
-    /** Arrays do not support meta - they have no native form element **/
-    readonly meta?: never;
+    params?: Record<string, string>;
     /**
-     * Logic configurations for conditional array visibility.
-     * Only 'hidden' type logic is supported for arrays.
+     * Query parameters appended to the URL.
+     * Values are expressions evaluated by ExpressionParser against the current EvaluationContext.
      */
-    readonly logic?: ContainerLogicConfig[];
+    queryParams?: Record<string, string>;
+    /** Request body (for POST/PUT/PATCH) */
+    body?: Record<string, unknown>;
     /**
-     * Minimum number of items required in the array.
-     * Validation fails if the array has fewer items than this value.
-     */
-    readonly minLength?: number;
-    /**
-     * Maximum number of items allowed in the array.
-     * Validation fails if the array has more items than this value.
+     * When true, top-level string values in `body` are treated as expressions
+     * and evaluated by ExpressionParser (shallow only — nested objects are passed through as-is).
      */
-    readonly maxLength?: number;
+    evaluateBodyExpressions?: boolean;
+    /** HTTP headers to include in the request */
+    headers?: Record<string, string>;
 }
+
 /**
- * Type guard for ArrayField with proper type narrowing.
- * Validates that the field is an array type with a fields property that is an array.
- * Fields can contain either single FieldDefs (primitive items) or arrays of FieldDefs (object items).
+ * Comparison operators for field value and form value conditions.
+ *
+ * @public
  */
-declare function isArrayField(field: FieldDef<any>): field is ArrayField;
+type ComparisonOperator = 'equals' | 'notEquals' | 'greater' | 'less' | 'greaterOrEqual' | 'lessOrEqual' | 'contains' | 'startsWith' | 'endsWith' | 'matches';
 /**
- * Configuration for auto-generated add/remove buttons in simplified array fields.
+ * Condition that compares a specific field's value against an expected value.
+ *
+ * @public
  */
-interface ArrayButtonConfig {
-    /** Custom label for the button */
-    readonly label?: string;
-    /** Additional properties passed to the button component */
-    readonly props?: Record<string, unknown>;
+interface FieldValueCondition {
+    type: 'fieldValue';
+    /** Path to the field whose value to compare */
+    fieldPath: string;
+    /** Comparison operator */
+    operator: ComparisonOperator;
+    /** Value to compare against */
+    value?: unknown;
 }
 /**
- * Simplified array field interface for common use cases.
- *
- * Instead of manually specifying each item in `fields`, provide a `template` that defines
- * the structure of a single item, and a `value` array with initial data.
- * The library auto-generates add/remove buttons.
+ * Condition that invokes a custom function.
  *
- * Discriminant: `template` presence → simplified API; `Array.isArray(template)` → object vs primitive.
+ * Two mutually exclusive forms:
+ * - `functionName`: name of a function registered in `customFnConfig.customFunctions`.
+ *   JSON-serializable; suitable for configs loaded from APIs, databases, or OpenAPI.
+ * - `fn`: inline function. NOT JSON-serializable; for code-only configs.
  *
- * @example
- * // Primitive array: ['angular', 'typescript']
- * {
- *   key: 'tags',
- *   type: 'array',
- *   template: { key: 'value', type: 'input', label: 'Tag', required: true },
- *   value: ['angular', 'typescript']
- * }
+ * Exactly one of `functionName` or `fn` must be set.
  *
- * @example
- * // Object array: [{ name: 'Jane', phone: '555' }]
- * {
- *   key: 'contacts',
- *   type: 'array',
- *   template: [
- *     { key: 'name', type: 'input', label: 'Contact Name', required: true },
- *     { key: 'phone', type: 'input', label: 'Phone Number' },
- *   ],
- *   value: [{ name: 'Jane', phone: '555' }]
- * }
+ * Encoded as a strict discriminated union (XOR via `?: never`). `CustomValidatorConfig`
+ * intentionally uses a permissive interface for the same `fn`/`functionName` split
+ * because validators have a third source (`expression`) and the historical interface
+ * was already runtime-checked — the asymmetry is by design, not an oversight.
  *
- * @example
- * // Button customization / opt-out
- * {
- *   key: 'tags',
- *   type: 'array',
- *   template: { key: 'value', type: 'input', label: 'Tag' },
- *   addButton: { label: 'Add Tag', props: { color: 'primary' } },
- *   removeButton: false
- * }
+ * @public
  */
-interface SimplifiedArrayField extends FieldDef<never> {
-    type: 'array';
+type CustomCondition = {
+    type: 'custom';
+    /** Name of the registered custom function to invoke */
+    functionName: string;
+    /** Inline form is forbidden when `functionName` is set */
+    fn?: never;
+} | {
+    type: 'custom';
     /**
-     * Template defining the structure of a single array item.
-     * - Single field (ArrayAllowedChildren) → primitive array (each item is a single value)
-     * - Array of fields (readonly ArrayAllowedChildren[]) → object array (each item is an object)
+     * Inline custom function. Mutually exclusive with `functionName`.
+     *
+     * NOT JSON-serializable — for code-only configs. For configs loaded
+     * from JSON / OpenAPI / databases, use `functionName` to reference
+     * a function registered in `customFnConfig.customFunctions`.
      */
-    readonly template: ArrayAllowedChildren | readonly ArrayAllowedChildren[];
-    /** Initial values for the array. Each element creates one array item. */
-    readonly value?: readonly unknown[];
+    fn: CustomFunction;
+    /** Registered form is forbidden when `fn` is set */
+    functionName?: never;
+};
+/**
+ * Condition that evaluates a JavaScript expression using the secure AST-based parser.
+ *
+ * The expression has access to `formValue`, `fieldValue`, `externalData`, etc.
+ *
+ * @public
+ */
+interface JavascriptCondition {
+    type: 'javascript';
+    /** JavaScript expression string to evaluate */
+    expression: string;
+}
+/**
+ * Condition that evaluates based on an HTTP response from a remote server.
+ *
+ * The HTTP request is resolved reactively — when dependent form values change,
+ * the request is re-evaluated (with debouncing). The result is cached per
+ * resolved request to avoid redundant network calls.
+ *
+ * Since `LogicFn` must return `boolean` synchronously, this condition uses
+ * a signal-based async resolution pattern internally.
+ *
+ * @public
+ */
+interface HttpCondition {
+    type: 'http';
+    /** HTTP request configuration */
+    http: HttpRequestConfig;
     /**
-     * Configuration for the auto-generated "Add" button, or `false` to disable it.
-     * Defaults to a button with label "Add".
+     * Expression to extract boolean from response (scope: `{ response }`).
+     * e.g. `'response.allowed'`, `'response.permissions.canEdit'`
+     * When omitted, the entire response is coerced to boolean: `!!response`
      */
-    readonly addButton?: ArrayButtonConfig | false;
+    responseExpression?: string;
     /**
-     * Configuration for the auto-generated "Remove" button on each item, or `false` to disable it.
-     * Defaults to a button with label "Remove".
+     * Value to return while the HTTP request is in-flight.
+     *
+     * Choose based on the logic type and desired UX:
+     * - For `hidden`: `false` = visible while loading, `true` = hidden while loading
+     * - For `disabled`: `false` = enabled while loading, `true` = disabled while loading
+     * - For `required`: `false` = optional while loading, `true` = required while loading
+     *
+     * @default false
      */
-    readonly removeButton?: ArrayButtonConfig | false;
-    /** Simplified arrays do not support the label property */
-    readonly label?: never;
-    /** Simplified arrays do not support meta */
-    readonly meta?: never;
+    pendingValue?: boolean;
+    /** Cache duration in ms for HTTP responses. @default 30000 */
+    cacheDurationMs?: number;
     /**
-     * Logic configurations for conditional array visibility.
-     * Only 'hidden' type logic is supported for arrays.
+     * Debounce time in milliseconds for re-evaluation when dependent form values change.
+     * @default 300
      */
-    readonly logic?: ContainerLogicConfig[];
+    debounceMs?: number;
+}
+/**
+ * Shared fields for both branches of {@link AsyncCondition}.
+ *
+ * @internal
+ */
+interface AsyncConditionBase {
+    type: 'async';
     /**
-     * Minimum number of items required in the array.
-     * Validation fails if the array has fewer items than this value.
+     * Value to return while async resolution is pending.
+     *
+     * Choose based on the logic type and desired UX:
+     * - For `hidden`: `false` = visible while loading, `true` = hidden while loading
+     * - For `disabled`: `false` = enabled while loading, `true` = disabled while loading
+     * - For `required`: `false` = optional while loading, `true` = required while loading
+     *
+     * @default false
      */
-    readonly minLength?: number;
+    pendingValue?: boolean;
     /**
-     * Maximum number of items allowed in the array.
-     * Validation fails if the array has more items than this value.
+     * Debounce ms for re-evaluation.
+     * @default 300
      */
-    readonly maxLength?: number;
-    /** Mutually exclusive with `template` — use `fields` for the full API instead */
-    readonly fields?: never;
+    debounceMs?: number;
 }
 /**
- * Type guard for SimplifiedArrayField.
- * Checks for `type: 'array'` with a `template` property (discriminant from full ArrayField).
- */
-declare function isSimplifiedArrayField(field: FieldDef<any>): field is SimplifiedArrayField;
-
-/**
- * Group field interface for creating logical field groupings that map to object values
- * Groups create nested form structures where child field values are collected into an object
- * This is a programmatic grouping only - users cannot customize this field type
+ * Condition that resolves asynchronously via a custom function.
  *
- * TypeScript cannot enforce field nesting rules due to circular dependency limitations.
- * For documentation: Groups should contain rows and leaf fields, but NOT pages or other groups.
- * Runtime validation enforces these rules.
+ * Two mutually exclusive forms:
+ * - `asyncFunctionName`: name of a function registered in `customFnConfig.asyncConditions`.
+ *   JSON-serializable; suitable for configs loaded from APIs, databases, or OpenAPI.
+ * - `asyncFn`: inline async function. NOT JSON-serializable; for code-only configs.
  *
- * Note: Groups are container fields and do not support `meta` since they have no native form element.
+ * Exactly one of `asyncFunctionName` or `asyncFn` must be set.
+ *
+ * The function is resolved reactively — when dependent form values change,
+ * the function is re-evaluated (with debouncing). The result is cached per
+ * evaluation to avoid redundant calls.
+ *
+ * Since `LogicFn` must return `boolean` synchronously, this condition uses
+ * a signal-based async resolution pattern internally.
+ *
+ * @public
  */
-interface GroupField<TFields extends readonly GroupAllowedChildren[] = readonly GroupAllowedChildren[]> extends FieldDef<never> {
-    type: 'group';
-    readonly fields: TFields;
-    /** Groups do not have a label property - they are logical containers only **/
-    readonly label?: never;
-    /** Groups do not support meta - they have no native form element **/
-    readonly meta?: never;
+type AsyncCondition = (AsyncConditionBase & {
+    /** Name of the registered async condition function */
+    asyncFunctionName: string;
+    /** Inline form is forbidden when `asyncFunctionName` is set */
+    asyncFn?: never;
+}) | (AsyncConditionBase & {
     /**
-     * Logic configurations for conditional group visibility.
-     * Only 'hidden' type logic is supported for groups.
+     * Inline async condition function. Mutually exclusive with `asyncFunctionName`.
+     *
+     * NOT JSON-serializable — for code-only configs. For configs loaded
+     * from JSON / OpenAPI / databases, use `asyncFunctionName` to reference
+     * a function registered in `customFnConfig.asyncConditions`.
      */
-    readonly logic?: ContainerLogicConfig[];
+    asyncFn: AsyncConditionFunction;
+    /** Registered form is forbidden when `asyncFn` is set */
+    asyncFunctionName?: never;
+});
+/**
+ * Logical AND — all sub-conditions must be true.
+ *
+ * @public
+ */
+interface AndCondition {
+    type: 'and';
+    /** Sub-conditions that must all evaluate to true */
+    conditions: ConditionalExpression[];
 }
 /**
- * Type guard for GroupField with proper type narrowing
+ * Logical OR — at least one sub-condition must be true.
+ *
+ * @public
  */
-declare function isGroupField(field: FieldDef<any>): field is GroupField;
-
+interface OrCondition {
+    type: 'or';
+    /** Sub-conditions where at least one must evaluate to true */
+    conditions: ConditionalExpression[];
+}
 /**
- * Scalar types supported by hidden fields.
- * These are the primitive value types that can be stored.
+ * Discriminated union of all conditional expression types.
+ *
+ * Each variant only allows the properties relevant to its type,
+ * providing compile-time safety against invalid property combinations.
+ *
+ * @public
  */
-type HiddenScalar = string | number | boolean;
+type ConditionalExpression = FieldValueCondition | CustomCondition | JavascriptCondition | HttpCondition | AsyncCondition | AndCondition | OrCondition;
+
 /**
- * All value types supported by hidden fields.
- * Supports both scalar values and arrays of scalars for storing
- * multiple IDs or similar data.
+ * Logic configuration for container fields (page, group, row, array).
+ * Containers only support the 'hidden' logic type since they are layout containers,
+ * not form controls (they can't be readonly, disabled, or required).
  */
-type HiddenValue = HiddenScalar | HiddenScalar[];
+interface ContainerLogicConfig {
+    /** Only 'hidden' is supported for container fields */
+    type: 'hidden';
+    /**
+     * Condition that determines when this container is hidden.
+     * Can be a boolean or a conditional expression evaluated against form values.
+     */
+    condition: ConditionalExpression | boolean;
+}
+
 /**
- * Hidden field definition for storing values without rendering UI.
- *
- * Hidden fields participate in the form schema and contribute to form values,
- * but do not render any visible component. They are useful for:
- * - Storing IDs when updating existing records
- * - Persisting metadata that shouldn't be user-editable
- * - Tracking computed values that need to be submitted
- *
- * Unlike the `hidden` property on other fields (which hides a rendered field),
- * this field type renders nothing at all - it's a componentless field.
+ * Row field interface for creating horizontal layouts.
+ * A row is a synthetic field type that resolves to a Container at runtime,
+ * with a synthesized `{ type: 'row' }` wrapper applied for layout. The row
+ * itself does not hold a value — its children flatten into the parent form.
  *
- * @example
- * ```typescript
- * // Store a record ID for updates
- * const idField: HiddenField<string> = {
- *   type: 'hidden',
- *   key: 'id',
- *   value: '550e8400-e29b-41d4-a716-446655440000',
- * };
+ * Note: Rows do not support `meta` since they have no native form element.
+ */
+interface RowField<TFields extends readonly RowAllowedChildren[] = readonly RowAllowedChildren[]> extends FieldDef<never> {
+    type: 'row';
+    /** Child definitions to render within this row */
+    readonly fields: TFields;
+    /** Row fields do not have a label property **/
+    readonly label?: never;
+    /** Rows do not support meta - they have no native form element **/
+    readonly meta?: never;
+    /**
+     * Logic configurations for conditional row visibility.
+     * Only 'hidden' type logic is supported for rows.
+     */
+    readonly logic?: ContainerLogicConfig[];
+}
+/**
+ * Type guard for RowField with proper type narrowing
+ */
+declare function isRowField(field: FieldDef<any>): field is RowField;
+
+/**
+ * Group field interface for creating logical field groupings that map to object values
+ * Groups create nested form structures where child field values are collected into an object
+ * This is a programmatic grouping only - users cannot customize this field type
  *
- * // Store multiple tag IDs
- * const tagIdsField: HiddenField<number[]> = {
- *   type: 'hidden',
- *   key: 'tagIds',
- *   value: [1, 2, 3],
- * };
- * ```
+ * TypeScript cannot enforce field nesting rules due to circular dependency limitations.
+ * For documentation: Groups should contain rows and leaf fields, but NOT pages or other groups.
+ * Runtime validation enforces these rules.
  *
- * @typeParam TValue - The type of value stored (must be HiddenValue compatible)
+ * Note: Groups are container fields and do not support `meta` since they have no native form element.
  */
-interface HiddenField<TValue extends HiddenValue = HiddenValue> extends FieldDef<never> {
-    /** Discriminant for hidden field type */
-    type: 'hidden';
+interface GroupField<TFields extends readonly GroupAllowedChildren[] = readonly GroupAllowedChildren[]> extends FieldDef<never> {
+    type: 'group';
+    readonly fields: TFields;
+    /** Groups do not have a label property - they are logical containers only **/
+    readonly label?: never;
+    /** Groups do not support meta - they have no native form element **/
+    readonly meta?: never;
     /**
-     * The value to store in the form.
-     * This is required - a hidden field without a value serves no purpose.
+     * Logic configurations for conditional group visibility.
+     * Only 'hidden' type logic is supported for groups.
      */
-    value: TValue;
+    readonly logic?: ContainerLogicConfig[];
 }
+/**
+ * Type guard for GroupField with proper type narrowing
+ */
+declare function isGroupField(field: FieldDef<any>): field is GroupField;
 
 /**
  * Page field interface for creating top-level page layouts
@@ -722,1442 +851,1254 @@ type ExtractFields<T> = T extends {
 type InferFormValue$1<T> = ExtractFields<T> extends readonly RegisteredFieldTypes[] ? InferFormValueWithDepth<ExtractFields<T> extends RegisteredFieldTypes[] ? ExtractFields<T> : [...ExtractFields<T>], 5> : never;
 
 /**
- * Mapping configuration for interpreting HTTP responses as validation results.
- *
- * Expressions in `validWhen` and `errorParams` are evaluated with scope `{ response }` only —
- * they do NOT have access to `formValue`, `fieldValue`, or the full `EvaluationContext`.
- * This is intentional for v1: response mapping is purely about interpreting the HTTP response.
- */
-interface HttpValidationResponseMapping {
-    /**
-     * Expression evaluated with scope `{ response }`. Must evaluate to `true` (strict boolean) to be valid.
-     *
-     * NOTE: This is the OPPOSITE of the function-based HttpCustomValidator.onSuccess
-     * convention, which maps successful HTTP responses to validation errors.
-     * Here, `=== true` means "validation passed". Non-boolean results are treated as invalid and trigger a warning.
-     */
-    validWhen: string;
-    /** Error kind returned when validation fails — maps to field-level `validationMessages` */
-    errorKind: string;
-    /**
-     * Parameters to include in the validation error for message interpolation.
-     * Map of parameter names to expressions evaluated against `{ response }`.
-     */
-    errorParams?: Record<string, string>;
-}
-
-/**
- * Base configuration shared by all validators
- */
-interface BaseValidatorConfig {
-    /** Conditional logic for when validator applies */
-    when?: ConditionalExpression;
-}
-/**
- * Built-in validator configuration (required, email, min, max, etc.)
- */
-interface BuiltInValidatorConfig extends BaseValidatorConfig {
-    /** Validator type identifier */
-    type: 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern';
-    /** Static value for the validator (e.g., min value, pattern) */
-    value?: number | string | RegExp;
-    /** Dynamic value expression that evaluates to validator parameter */
-    expression?: string;
-}
-/**
- * Custom validator configuration using Angular's public FieldContext API
- * Returns ValidationError | ValidationError[] | null synchronously
+ * Custom validator function signature using Angular's public FieldContext API
  *
- * Supports two patterns:
- * 1. Function-based: { type: 'custom', functionName: 'myValidator' }
- * 2. Expression-based: { type: 'custom', expression: 'fieldValue === formValue.password', kind: 'passwordMismatch' }
- */
-interface CustomValidatorConfig extends BaseValidatorConfig {
-    /** Validator type identifier */
-    type: 'custom';
-    /** Name of registered validator function (function-based pattern) */
-    functionName?: string;
-    /** Optional parameters to pass to validator function */
-    params?: Record<string, unknown>;
-    /** JavaScript expression to evaluate (expression-based pattern) */
-    expression?: string;
-    /** Error kind for expression-based validators - links to validationMessages */
-    kind?: string;
-    /**
-     * Parameters to include in error object for message interpolation (expression-based pattern)
-     * Map of parameter names to expressions that will be evaluated in the same context as the validation expression
-     *
-     * @example
-     * errorParams: {
-     *   minValue: 'formValue.minValue',
-     *   maxValue: 'formValue.maxValue'
-     * }
-     * // Allows message template: "Value must be between {{minValue}} and {{maxValue}}"
-     */
-    errorParams?: Record<string, string>;
-}
-/**
- * Async custom validator configuration using Angular's validateAsync API.
- * Returns Observable<ValidationError | ValidationError[] | null>.
+ * Takes FieldContext (full Angular context) and optional params, returns validation error(s) or null.
+ * Provides access to field state, form hierarchy, and other fields for validation logic.
  *
- */
-interface AsyncValidatorConfig extends BaseValidatorConfig {
-    /** Validator type identifier. */
-    type: 'async';
-    /** Name of registered async validator function */
-    functionName: string;
-    /** Optional parameters to pass to validator function */
-    params?: Record<string, unknown>;
-}
-/**
- * Function-based HTTP validator configuration — requires a registered function.
+ * **Use FieldContext public APIs to access:**
+ * - Current field value: `ctx.value()`
+ * - Field state: `ctx.state` (errors, touched, dirty, etc.)
+ * - Other field values: `ctx.valueOf(path)` where path is a FieldPath
+ * - Other field states: `ctx.stateOf(path)`
+ * - Other fields: `ctx.fieldTreeOf(path)`
+ * - Current field tree: `ctx.fieldTree`
  *
- * Uses Angular's `validateHttp` API. The function is registered via
- * `customFnConfig.httpValidators`.
+ * **Return Types:**
+ * - Single error: `{ kind: 'errorKind' }` for field-level validation
+ * - Multiple errors: `[{ kind: 'error1' }, { kind: 'error2' }]` for cross-field validation
+ * - No error: `null` when validation passes
  *
- * Discriminated from `DeclarativeHttpValidatorConfig` by the presence of `functionName`.
+ * **Best Practice - Return Only Error Kind:**
+ * Validators should focus on validation logic, not presentation.
+ * Return just the error `kind` and configure messages at field level for i18n support.
  *
- */
-interface FunctionHttpValidatorConfig extends BaseValidatorConfig {
-    /** Validator type identifier. */
-    type: 'http';
-    /** Name of registered HTTP validator configuration */
-    functionName: string;
-    /** Optional parameters to pass to HTTP validator */
-    params?: Record<string, unknown>;
-}
-/**
- * Declarative HTTP validator configuration — fully JSON-serializable, no function registration required.
+ * @example Single Field Validation
+ * ```typescript
+ * const noSpaces: CustomValidator<string> = (ctx) => {
+ *   const value = ctx.value();
+ *   if (typeof value === 'string' && value.includes(' ')) {
+ *     return { kind: 'noSpaces' };
+ *   }
+ *   return null;
+ * };
  *
- * Uses `HttpRequestConfig` to define the HTTP request and `HttpValidationResponseMapping`
- * to interpret the response as a validation result. Powered by Angular's `validateHttp` API.
+ * // Field configuration
+ * {
+ *   key: 'username',
+ *   validators: [{ type: 'custom', functionName: 'noSpaces' }],
+ *   validationMessages: {
+ *     noSpaces: 'Spaces are not allowed'
+ *   }
+ * }
+ * ```
  *
- * Discriminated from `FunctionHttpValidatorConfig` by the presence of `http` + `responseMapping`
- * (and absence of `functionName`).
- */
-interface DeclarativeHttpValidatorConfig extends BaseValidatorConfig {
-    /** Validator type identifier */
-    type: 'http';
-    /** HTTP request configuration with expression-based query params and body */
-    http: HttpRequestConfig;
-    /** Mapping that interprets the HTTP response as a validation result */
-    responseMapping: HttpValidationResponseMapping;
-}
-/**
- * Configuration for signal forms validator functions that can be serialized from API.
- * Discriminated union type for type-safe validator configuration.
+ * @example Cross-Field Validation with valueOf()
+ * ```typescript
+ * // Compare two fields using public API
+ * const lessThan: CustomValidator<number> = (ctx, params) => {
+ *   const value = ctx.value();
+ *   const compareToPath = params?.field as string;
  *
- * Note: `FunctionHttpValidatorConfig` and `DeclarativeHttpValidatorConfig` both use `type: 'http'`.
- * They are discriminated by property presence: `functionName` → function-based, `http` → declarative.
- * Use `isFunctionHttpValidator()` for type-safe narrowing when `type` alone is insufficient.
- */
-type ValidatorConfig = BuiltInValidatorConfig | CustomValidatorConfig | AsyncValidatorConfig | FunctionHttpValidatorConfig | DeclarativeHttpValidatorConfig;
-
-/**
- * Special form-state conditions for button disabled logic.
+ *   // Use valueOf() to access other field - public API!
+ *   const otherValue = ctx.valueOf(compareToPath as any);
  *
- * These conditions evaluate form or page-level state rather than field values,
- * and are primarily used for controlling button disabled states.
+ *   if (otherValue !== undefined && value >= otherValue) {
+ *     return { kind: 'notLessThan' };
+ *   }
+ *   return null;
+ * };
+ * ```
  *
- * @example
+ * @example Multiple Errors (Cross-Field Validation)
  * ```typescript
- * // Disable submit button when form is invalid or submitting
- * {
- *   key: 'submit',
- *   type: 'submit',
- *   label: 'Submit',
- *   logic: [
- *     { type: 'disabled', condition: 'formInvalid' },
- *     { type: 'disabled', condition: 'formSubmitting' },
- *   ]
- * }
- *
- * // Disable next button when current page is invalid
- * nextButton({
- *   key: 'next',
- *   label: 'Next',
- *   logic: [
- *     { type: 'disabled', condition: 'pageInvalid' },
- *   ]
- * })
+ * const validateDateRange: CustomValidator = (ctx) => {
+ *   const errors: ValidationError[] = [];
+ *
+ *   const startDate = ctx.valueOf('startDate' as any);
+ *   const endDate = ctx.valueOf('endDate' as any);
+ *
+ *   if (!startDate) errors.push({ kind: 'startDateRequired' });
+ *   if (!endDate) errors.push({ kind: 'endDateRequired' });
+ *   if (startDate && endDate && startDate > endDate) {
+ *     errors.push({ kind: 'invalidDateRange' });
+ *   }
+ *
+ *   return errors.length > 0 ? errors : null;
+ * };
  * ```
  *
- * @public
- */
-type FormStateCondition = 
-/** True when form.valid() === false */
-'formInvalid'
-/** True when form.submitting() === true */
- | 'formSubmitting'
-/** True when fields on the current page are invalid (for paged forms) */
- | 'pageInvalid';
-/**
- * Logic type for controlling field state (hidden, readonly, disabled, required).
+ * **Message Resolution Priority:**
+ * 1. Field-level `validationMessages[kind]` (highest priority - per-field customization)
+ * 2. Form-level `defaultValidationMessages[kind]` (fallback for common messages)
+ * 3. **No message configured = Warning logged + error NOT displayed**
  *
- * @public
+ * **Important:** Validator-returned messages are NOT used. All messages MUST be explicitly configured.
+ *
+ * @template TValue The type of value stored in the field being validated
  */
-type StateLogicType = 'hidden' | 'readonly' | 'disabled' | 'required';
+type CustomValidator<TValue = unknown> = (ctx: FieldContext<TValue>, params?: Record<string, unknown>) => ValidationError$1 | ValidationError$1[] | null;
 /**
- * Base configuration for conditional field state logic.
+ * Async custom validator configuration using Angular's resource-based API
  *
- * @internal
+ * Angular's validateAsync uses the resource API for async validation,
+ * which provides better integration with Signal Forms lifecycle management.
+ *
+ * **Structure:**
+ * - `params`: Function that computes params from field context
+ * - `factory`: Function that creates a ResourceRef from params signal
+ * - `onSuccess`: Maps successful resource result to validation errors
+ * - `onError`: Optional handler for resource errors (network failures, etc.)
+ *
+ * **Use Cases:**
+ * - Database lookups via services with resource API
+ * - Complex async business logic with Angular resources
+ * - Any async operation using Angular's resource pattern
+ *
+ * **Note:** For HTTP validation, prefer `HttpCustomValidator` which provides
+ * a simpler API specifically designed for HTTP requests.
+ *
+ * @example Database Lookup with Resource
+ * ```typescript
+ * const checkUsernameAvailable: AsyncCustomValidator<string> = {
+ *   params: (ctx) => ({ username: ctx.value() }),
+ *   factory: (params) => {
+ *     const injector = inject(Injector);
+ *     return resource({
+ *       request: () => params(),
+ *       loader: ({ request }) => {
+ *         if (!request?.username) return null;
+ *         const service = injector.get(UserService);
+ *         return firstValueFrom(service.checkAvailability(request.username));
+ *       }
+ *     });
+ *   },
+ *   onSuccess: (result, ctx) => {
+ *     if (!result) return null;
+ *     return result.available ? null : { kind: 'usernameTaken' };
+ *   },
+ *   onError: (error, ctx) => {
+ *     console.error('Availability check failed:', error);
+ *     return null; // Don't block form on network errors
+ *   }
+ * };
+ * ```
+ *
+ * @template TValue The type of value stored in the field being validated
+ * @template TParams The type of params passed to the resource
+ * @template TResult The type of result returned by the resource
  */
-interface BaseStateLogicConfig {
+interface AsyncCustomValidator<TValue = unknown, TParams = unknown, TResult = unknown> {
     /**
-     * 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
+     * Function that receives field context and returns resource params.
+     * Params will be tracked as a signal and trigger resource reload when changed.
      */
-    type: StateLogicType;
+    readonly params: (ctx: FieldContext<TValue>, config?: Record<string, unknown>) => TParams;
     /**
-     * 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'
-     * ```
+     * Function that creates a ResourceRef from the params signal.
+     * The resource will be automatically managed by Angular's lifecycle.
      */
-    condition: ConditionalExpression | boolean | FormStateCondition;
-}
-/**
- * State logic that evaluates immediately on change (default).
- *
- * @internal
- */
-interface ImmediateStateLogicConfig extends BaseStateLogicConfig {
+    readonly factory: (params: Signal<TParams | undefined>) => ResourceRef<TResult | undefined>;
     /**
-     * Trigger for immediate evaluation.
-     * @default 'onChange'
+     * Optional function to map successful resource result to validation errors.
+     * Return null if validation passes, or ValidationError/ValidationError[] if validation fails.
      */
-    trigger?: 'onChange';
-    /** Not allowed for onChange trigger */
-    debounceMs?: never;
+    readonly onSuccess?: (result: TResult, ctx: FieldContext<TValue>) => TreeValidationResult;
+    /**
+     * Optional error handler for resource errors (network failures, etc.).
+     * Return null to ignore the error, or ValidationError to display it to the user.
+     */
+    readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError$1 | ValidationError$1[] | null;
 }
 /**
- * State logic that evaluates after a debounce period.
- *
- * @internal
+ * HTTP request configuration for validateHttp API
  */
-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;
+interface HttpResourceRequest {
+    url: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    headers?: Record<string, string | string[]>;
 }
 /**
- * Configuration for conditional field state logic.
+ * HTTP-based validator configuration for Angular's validateHttp API
  *
- * Defines how field behavior changes based on conditions.
- * Supports hiding, disabling, making readonly, or requiring fields
- * based on form state or field values.
+ * Angular's validateHttp provides optimized HTTP validation with automatic
+ * request cancellation and integration with the resource API.
  *
- * @example
+ * **Benefits:**
+ * - Automatic request cancellation when field value changes
+ * - Built-in integration with Angular's resource management
+ * - Simpler than AsyncCustomValidator for HTTP use cases
+ *
+ * **Structure:**
+ * - `request`: Function that returns URL string or HttpResourceRequest
+ * - `onSuccess`: REQUIRED - Maps HTTP response to validation errors (inverted logic!)
+ * - `onError`: Optional handler for HTTP errors (network failures, 4xx/5xx)
+ *
+ * **Important:** `onSuccess` uses inverted logic - it maps SUCCESSFUL HTTP responses
+ * to validation errors. For example, if the API returns `{ available: false }`,
+ * your `onSuccess` should return `{ kind: 'usernameTaken' }`.
+ *
+ * @example Username Availability Check (GET)
  * ```typescript
- * // Hide email field when contact method is not email
- * {
- *   type: 'hidden',
- *   condition: {
- *     type: 'fieldValue',
- *     fieldPath: 'contactMethod',
- *     operator: 'notEquals',
- *     value: 'email'
+ * const checkUsername: HttpCustomValidator<string> = {
+ *   request: (ctx) => {
+ *     const username = ctx.value();
+ *     if (!username) return undefined; // Skip validation if empty
+ *     return `/api/users/check-username?username=${encodeURIComponent(username)}`;
+ *   },
+ *   onSuccess: (response, ctx) => {
+ *     // Inverted logic: successful response may indicate validation failure
+ *     return response.available ? null : { kind: 'usernameTaken' };
+ *   },
+ *   onError: (error, ctx) => {
+ *     console.error('Availability check failed:', error);
+ *     return null; // Don't block form on network errors
  *   }
- * }
+ * };
+ * ```
  *
- * // Disable button when form is submitting
- * {
- *   type: 'disabled',
- *   condition: 'formSubmitting'
- * }
+ * @example Address Validation (POST with Body)
+ * ```typescript
+ * const validateAddress: HttpCustomValidator = {
+ *   request: (ctx) => {
+ *     const zipCode = ctx.value();
+ *     if (!zipCode) return undefined;
  *
- * // Debounced visibility (avoids flicker during rapid typing)
- * {
- *   type: 'hidden',
- *   trigger: 'debounced',
- *   debounceMs: 300,
- *   condition: {
- *     type: 'fieldValue',
- *     fieldPath: 'search',
- *     operator: 'isEmpty'
+ *     return {
+ *       url: '/api/validate-address',
+ *       method: 'POST',
+ *       body: {
+ *         street: ctx.valueOf('street' as any),
+ *         city: ctx.valueOf('city' as any),
+ *         zipCode: zipCode
+ *       },
+ *       headers: { 'Content-Type': 'application/json' }
+ *     };
+ *   },
+ *   onSuccess: (response) => {
+ *     return response.valid ? null : { kind: 'invalidAddress' };
  *   }
- * }
+ * };
  * ```
  *
- * @public
+ * @template TValue The type of value stored in the field being validated
+ * @template TResult The type of HTTP response
  */
-type StateLogicConfig = ImmediateStateLogicConfig | DebouncedStateLogicConfig;
-/**
- * Shared fields that appear on all derivation logic config variants.
- *
- * @internal
- */
-interface SharedDerivationFields {
+interface HttpCustomValidator<TValue = unknown, TResult = unknown> {
     /**
-     * Logic type identifier for value derivation.
+     * Function that returns the HTTP request configuration.
+     * Can return:
+     * - `undefined` to skip validation (e.g., if field is empty)
+     * - `string` for simple GET requests (just the URL)
+     * - `HttpResourceRequest` for full control (method, body, headers)
      */
-    type: 'derivation';
+    readonly request: (ctx: FieldContext<TValue>, config?: Record<string, unknown>) => string | HttpResourceRequest | undefined;
     /**
-     * Target property name for property derivation.
-     *
-     * When set, this derivation targets a field property (like `minDate`, `options`,
-     * `label`, `placeholder`) instead of the field's value. The derivation is routed
-     * to the property derivation pipeline.
-     *
-     * When absent, the derivation targets the field's value (default behavior).
-     *
-     * **Depth limit (max 2 levels):** Only simple and single-dot-nested paths are
-     * supported. Paths with 2+ dots (e.g., `'a.b.c'`) will throw at runtime.
+     * REQUIRED function to map successful HTTP response to validation errors.
      *
-     * @example
-     * ```typescript
-     * // Property derivation (new unified API)
-     * {
-     *   key: 'endDate',
-     *   type: 'datepicker',
-     *   logic: [{
-     *     type: 'derivation',
-     *     targetProperty: 'minDate',
-     *     expression: 'formValue.startDate'
-     *   }]
-     * }
+     * **Inverted Logic:** This is called on successful HTTP responses.
+     * Return null if validation passes, or ValidationError/ValidationError[] if validation fails.
      *
-     * // Value derivation (no targetProperty — existing behavior)
-     * {
-     *   key: 'total',
-     *   type: 'input',
-     *   logic: [{
-     *     type: 'derivation',
-     *     expression: 'formValue.quantity * formValue.unitPrice'
-     *   }]
-     * }
-     * ```
+     * Example: API returns `{ available: false }` → return `{ kind: 'usernameTaken' }`
      */
-    targetProperty?: string;
+    readonly onSuccess: (result: TResult, ctx: FieldContext<TValue>) => TreeValidationResult;
     /**
-     * Optional name for this derivation for debugging purposes.
-     *
-     * When provided, this name appears in derivation debug logs,
-     * making it easier to identify specific derivations in complex forms.
+     * Optional error handler for HTTP errors (network failures, 4xx/5xx status codes).
+     * Return null to ignore the error, or ValidationError to display it to the user.
      *
-     * @example
-     * ```typescript
-     * {
-     *   key: 'lineTotal',
-     *   type: 'input',
-     *   logic: [{
-     *     type: 'derivation',
-     *     debugName: 'Calculate line total',
-     *     expression: 'formValue.quantity * formValue.unitPrice'
-     *   }]
-     * }
-     * ```
+     * Common pattern: Log the error and return null to avoid blocking form submission
+     * on network issues.
      */
-    debugName?: string;
+    readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError$1 | ValidationError$1[] | null;
+}
+
+/**
+ * Mapping configuration for interpreting HTTP responses as validation results.
+ *
+ * Expressions in `validWhen` and `errorParams` are evaluated with scope `{ response }` only —
+ * they do NOT have access to `formValue`, `fieldValue`, or the full `EvaluationContext`.
+ * This is intentional for v1: response mapping is purely about interpreting the HTTP response.
+ */
+interface HttpValidationResponseMapping {
     /**
-     * Condition that determines when this derivation applies.
-     *
-     * Can be:
-     * - `boolean`: Static value (always applies or never applies)
-     * - `ConditionalExpression`: Expression evaluated against field/form values
-     *
-     * Defaults to `true` (always apply).
-     *
-     * Note: FormStateCondition is not supported for derivations.
-     *
-     * @example
-     * ```typescript
-     * // Always compute (default)
-     * condition: true
+     * Expression evaluated with scope `{ response }`. Must evaluate to `true` (strict boolean) to be valid.
      *
-     * // Conditional derivation
-     * condition: {
-     *   type: 'fieldValue',
-     *   fieldPath: 'country',
-     *   operator: 'equals',
-     *   value: 'USA'
-     * }
-     * ```
+     * NOTE: This is the OPPOSITE of the function-based HttpCustomValidator.onSuccess
+     * convention, which maps successful HTTP responses to validation errors.
+     * Here, `=== true` means "validation passed". Non-boolean results are treated as invalid and trigger a warning.
      */
-    condition?: ConditionalExpression | boolean;
+    validWhen: string;
+    /** Error kind returned when validation fails — maps to field-level `validationMessages` */
+    errorKind: string;
     /**
-     * When true, the derivation stops running after the user manually
-     * edits the target field.
-     *
-     * This is useful for "smart defaults" — values that should be
-     * auto-filled initially but respected once the user explicitly changes them.
-     *
-     * Uses the field's `dirty()` signal to detect user modification.
-     * Derivations write directly to `value.set()` which does not trigger
-     * `markAsDirty()`, so `dirty === true` reliably indicates a user edit.
-     *
-     * @example
-     * ```typescript
-     * // Auto-fill display name from first + last name, but stop if user edits it
-     * {
-     *   key: 'displayName',
-     *   logic: [{
-     *     type: 'derivation',
-     *     expression: 'formValue.firstName + " " + formValue.lastName',
-     *     stopOnUserOverride: true
-     *   }]
-     * }
-     * ```
+     * Parameters to include in the validation error for message interpolation.
+     * Map of parameter names to expressions evaluated against `{ response }`.
      */
-    stopOnUserOverride?: boolean;
+    errorParams?: Record<string, string>;
+}
+
+/**
+ * Base configuration shared by all validators
+ */
+interface BaseValidatorConfig {
+    /** Conditional logic for when validator applies */
+    when?: ConditionalExpression;
+}
+/**
+ * Built-in validator configuration (required, email, min, max, etc.)
+ */
+interface BuiltInValidatorConfig extends BaseValidatorConfig {
+    /** Validator type identifier */
+    type: 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern';
+    /** Static value for the validator (e.g., min value, pattern) */
+    value?: number | string | RegExp;
+    /** Dynamic value expression that evaluates to validator parameter */
+    expression?: string;
+}
+/**
+ * Custom validator configuration using Angular's public FieldContext API.
+ * Returns ValidationError | ValidationError[] | null synchronously.
+ *
+ * Three authoring forms (mutually exclusive at runtime, not enforced by TypeScript):
+ * 1. Registered function: `{ type: 'custom', functionName: 'myValidator' }`
+ * 2. Inline function (code-only): `{ type: 'custom', fn: (ctx) => ... }`
+ * 3. Expression-based: `{ type: 'custom', expression: 'fieldValue === formValue.password', kind: 'passwordMismatch' }`
+ *
+ * Unlike `AsyncValidatorConfig` and `FunctionHttpValidatorConfig` (strict `fn` ↔
+ * `functionName` XOR via discriminated unions), this surface keeps a permissive
+ * interface — the historical expression-vs-functionName split was already
+ * runtime-checked, so adding `fn` follows the same precedent. The runtime
+ * resolver picks one source and warns if `fn` and `functionName` are both set;
+ * inline `fn` wins.
+ *
+ * `fn` is NOT JSON-serializable — for code-only configs. For configs loaded from
+ * JSON / OpenAPI / databases, prefer `functionName` to reference a function
+ * registered in `customFnConfig.validators`.
+ */
+interface CustomValidatorConfig extends BaseValidatorConfig {
+    /** Validator type identifier */
+    type: 'custom';
+    /** Name of registered validator function (function-based pattern) */
+    functionName?: string;
     /**
-     * When true (and `stopOnUserOverride` is also true), clears the
-     * user-override flag when any dependency of this derivation changes,
-     * allowing the derivation to run again.
-     *
-     * This is useful when a user override should only persist until the
-     * underlying data changes — e.g., when switching countries, the
-     * phone prefix should re-derive even if the user previously edited it.
+     * Inline custom validator (code-only authoring).
+     * Mutually exclusive with `functionName`. NOT JSON-serializable.
+     */
+    fn?: CustomValidator;
+    /** Optional parameters to pass to validator function */
+    params?: Record<string, unknown>;
+    /** JavaScript expression to evaluate (expression-based pattern) */
+    expression?: string;
+    /** Error kind for expression-based validators - links to validationMessages */
+    kind?: string;
+    /**
+     * Parameters to include in error object for message interpolation (expression-based pattern)
+     * Map of parameter names to expressions that will be evaluated in the same context as the validation expression
      *
      * @example
-     * ```typescript
-     * {
-     *   key: 'phonePrefix',
-     *   logic: [{
-     *     type: 'derivation',
-     *     value: '+1',
-     *     condition: { type: 'fieldValue', fieldPath: 'country', operator: 'equals', value: 'USA' },
-     *     stopOnUserOverride: true,
-     *     reEngageOnDependencyChange: true,
-     *     dependsOn: ['country']
-     *   }]
+     * errorParams: {
+     *   minValue: 'formValue.minValue',
+     *   maxValue: 'formValue.maxValue'
      * }
-     * ```
+     * // Allows message template: "Value must be between {{minValue}} and {{maxValue}}"
      */
-    reEngageOnDependencyChange?: boolean;
+    errorParams?: Record<string, string>;
 }
 /**
- * Trigger variants for derivation timing.
+ * Shared fields for both branches of {@link AsyncValidatorConfig}.
+ *
  * @internal
  */
-type ImmediateDerivationTrigger = {
-    trigger?: 'onChange';
-    debounceMs?: never;
-};
-type DebouncedDerivationTrigger = {
-    trigger: 'debounced';
-    debounceMs?: number;
-};
+interface AsyncValidatorConfigShared extends BaseValidatorConfig {
+    /** Validator type identifier. */
+    type: 'async';
+    /** Optional parameters to pass to validator function */
+    params?: Record<string, unknown>;
+}
 /**
- * Base for HTTP derivations. `source: 'http'` is required.
- * TypeScript enforces `dependsOn` and `responseExpression` at the type level.
+ * Async custom validator configuration using Angular's `validateAsync` API.
+ * Returns Observable<ValidationError | ValidationError[] | null>.
  *
- * @internal
+ * Two mutually exclusive authoring forms:
+ * - `functionName`: name of a function registered in `customFnConfig.asyncValidators`.
+ *   JSON-serializable; suitable for configs loaded from APIs, databases, or OpenAPI.
+ * - `fn`: inline async validator. NOT JSON-serializable; for code-only configs.
+ *
+ * Exactly one of `functionName` or `fn` must be set.
  */
-interface HttpDerivationBase extends SharedDerivationFields {
-    /** Identifies this derivation as HTTP-driven. */
-    source: 'http';
+type AsyncValidatorConfig = (AsyncValidatorConfigShared & {
+    /** Name of registered async validator function */
+    functionName: string;
+    /** Inline form is forbidden when `functionName` is set */
+    fn?: never;
+}) | (AsyncValidatorConfigShared & {
     /**
-     * HTTP request configuration for server-driven derivations.
-     *
-     * The request is sent when dependencies change, with automatic
-     * debouncing and cancellation of in-flight requests.
+     * Inline async validator. Mutually exclusive with `functionName`.
      *
-     * Configure debounce via the `trigger: 'debounced'` + `debounceMs` mechanism.
+     * NOT JSON-serializable — for code-only configs. For configs loaded
+     * from JSON / OpenAPI / databases, use `functionName` to reference
+     * a validator registered in `customFnConfig.asyncValidators`.
+     */
+    fn: AsyncCustomValidator;
+    /** Registered form is forbidden when `fn` is set */
+    functionName?: never;
+});
+/**
+ * Shared fields for both branches of {@link FunctionHttpValidatorConfig}.
+ *
+ * @internal
+ */
+interface FunctionHttpValidatorConfigShared extends BaseValidatorConfig {
+    /** Validator type identifier. */
+    type: 'http';
+    /** Optional parameters to pass to HTTP validator */
+    params?: Record<string, unknown>;
+}
+/**
+ * Function-based HTTP validator configuration. Uses Angular's `validateHttp` API.
+ *
+ * Two mutually exclusive authoring forms:
+ * - `functionName`: name of an HTTP validator registered in `customFnConfig.httpValidators`.
+ *   JSON-serializable.
+ * - `fn`: inline HTTP validator. NOT JSON-serializable; for code-only configs.
+ *
+ * Exactly one of `functionName` or `fn` must be set.
+ *
+ * Discriminated from `DeclarativeHttpValidatorConfig` by the presence of `functionName`
+ * or `fn` (and absence of `http` + `responseMapping`).
+ */
+type FunctionHttpValidatorConfig = (FunctionHttpValidatorConfigShared & {
+    /** Name of registered HTTP validator configuration */
+    functionName: string;
+    /** Inline form is forbidden when `functionName` is set */
+    fn?: never;
+}) | (FunctionHttpValidatorConfigShared & {
+    /**
+     * Inline HTTP validator. Mutually exclusive with `functionName`.
      *
-     * @example
-     * ```typescript
-     * {
-     *   key: 'exchangeRate',
-     *   logic: [{
-     *     type: 'derivation',
-     *     source: 'http',
-     *     http: {
-     *       url: '/api/exchange-rate',
-     *       method: 'GET',
-     *       queryParams: {
-     *         from: 'formValue.sourceCurrency',
-     *         to: 'formValue.targetCurrency',
-     *       },
-     *     },
-     *     responseExpression: 'response.rate',
-     *     dependsOn: ['sourceCurrency', 'targetCurrency'],
-     *   }]
-     * }
-     * ```
-     */
-    http: HttpRequestConfig;
-    /**
-     * Explicit field dependencies. Required for HTTP derivations to prevent
-     * wildcard triggering on every keystroke.
-     *
-     * The wildcard token `'*'` is rejected. The structural token `'$group'`
-     * (and `'$group.X'`) is allowed and resolves to the field's parent container
-     * path — be aware this fires whenever any sibling under that group changes,
-     * so the caller owns the request frequency (consider `trigger: 'debounced'`).
-     */
-    dependsOn: string[];
-    /**
-     * Expression to extract the derived value from the HTTP response.
-     *
-     * Evaluated via `ExpressionParser` with `{ response }` as the evaluation scope.
-     *
-     * @example
-     * ```typescript
-     * responseExpression: 'response.rate'
-     * responseExpression: 'response.data.suggestedPrice'
-     * ```
+     * NOT JSON-serializable — for code-only configs. For configs loaded
+     * from JSON / OpenAPI / databases, use `functionName` to reference
+     * an HTTP validator registered in `customFnConfig.httpValidators`.
      */
-    responseExpression: string;
-    value?: never;
-    expression?: never;
+    fn: HttpCustomValidator;
+    /** Registered form is forbidden when `fn` is set */
     functionName?: never;
-    asyncFunctionName?: never;
-}
+});
 /**
- * Base for async function derivations. `source: 'asyncFunction'` is required.
- * TypeScript enforces `dependsOn` at the type level.
+ * Declarative HTTP validator configuration — fully JSON-serializable, no function registration required.
  *
- * @internal
+ * Uses `HttpRequestConfig` to define the HTTP request and `HttpValidationResponseMapping`
+ * to interpret the response as a validation result. Powered by Angular's `validateHttp` API.
+ *
+ * Discriminated from `FunctionHttpValidatorConfig` by the presence of `http` + `responseMapping`
+ * (and absence of `functionName`).
  */
-interface AsyncFunctionDerivationBase extends SharedDerivationFields {
-    /** Identifies this derivation as async-function-driven. */
-    source: 'asyncFunction';
-    /**
-     * Name of a registered async derivation function.
-     *
-     * The function receives the evaluation context and returns a Promise or Observable
-     * of the derived value. Register functions in `customFnConfig.asyncDerivations`.
-     *
-     * @example
-     * ```typescript
-     * {
-     *   key: 'suggestedPrice',
-     *   logic: [{
-     *     type: 'derivation',
-     *     source: 'asyncFunction',
-     *     asyncFunctionName: 'fetchSuggestedPrice',
-     *     dependsOn: ['productId', 'quantity'],
-     *   }]
-     * }
-     * ```
-     */
-    asyncFunctionName: string;
-    /**
-     * Explicit field dependencies. Required for async derivations to prevent
-     * wildcard triggering on every form change.
-     *
-     * The wildcard token `'*'` is rejected. The structural token `'$group'`
-     * (and `'$group.X'`) is allowed and resolves to the field's parent container
-     * path — be aware this fires whenever any sibling under that group changes,
-     * so the caller owns the invocation frequency (handle this via
-     * `trigger: 'debounced'` or via debouncing inside the async function).
-     */
-    dependsOn: string[];
-    value?: never;
-    expression?: never;
-    functionName?: never;
-    http?: never;
-    responseExpression?: never;
+interface DeclarativeHttpValidatorConfig extends BaseValidatorConfig {
+    /** Validator type identifier */
+    type: 'http';
+    /** HTTP request configuration with expression-based query params and body */
+    http: HttpRequestConfig;
+    /** Mapping that interprets the HTTP response as a validation result */
+    responseMapping: HttpValidationResponseMapping;
 }
 /**
- * Base for expression derivations.
+ * Configuration for signal forms validator functions that can be serialized from API.
+ * Discriminated union type for type-safe validator configuration.
+ *
+ * Note: `FunctionHttpValidatorConfig` and `DeclarativeHttpValidatorConfig` both use `type: 'http'`.
+ * They are discriminated by property presence: `functionName` → function-based, `http` → declarative.
+ * Use `isFunctionHttpValidator()` for type-safe narrowing when `type` alone is insufficient.
+ */
+type ValidatorConfig = BuiltInValidatorConfig | CustomValidatorConfig | AsyncValidatorConfig | FunctionHttpValidatorConfig | DeclarativeHttpValidatorConfig;
+
+/**
+ * Special form-state conditions for button disabled logic.
+ *
+ * These conditions evaluate form or page-level state rather than field values,
+ * and are primarily used for controlling button disabled states.
+ *
+ * @example
+ * ```typescript
+ * // Disable submit button when form is invalid or submitting
+ * {
+ *   key: 'submit',
+ *   type: 'submit',
+ *   label: 'Submit',
+ *   logic: [
+ *     { type: 'disabled', condition: 'formInvalid' },
+ *     { type: 'disabled', condition: 'formSubmitting' },
+ *   ]
+ * }
+ *
+ * // Disable next button when current page is invalid
+ * nextButton({
+ *   key: 'next',
+ *   label: 'Next',
+ *   logic: [
+ *     { type: 'disabled', condition: 'pageInvalid' },
+ *   ]
+ * })
+ * ```
+ *
+ * @public
+ */
+type FormStateCondition = 
+/** True when form.valid() === false */
+'formInvalid'
+/** True when form.submitting() === true */
+ | 'formSubmitting'
+/** True when fields on the current page are invalid (for paged forms) */
+ | 'pageInvalid';
+/**
+ * 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 ExpressionDerivationBase extends SharedDerivationFields {
-    source?: never;
+interface BaseStateLogicConfig {
     /**
-     * JavaScript expression to evaluate for the derived value.
-     *
-     * Has access to `formValue` object containing all form values.
-     * For array fields, `formValue` is scoped to the current array item.
-     * Uses the same secure AST-based parser as other expressions.
+     * Logic type identifier for field state.
      *
-     * @example
-     * ```typescript
-     * expression: 'formValue.quantity * formValue.unitPrice'
-     * expression: 'formValue.firstName + " " + formValue.lastName'
-     * expression: 'formValue.price * (1 - formValue.discount / 100)'
-     * ```
+     * - `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
      */
-    expression: string;
+    type: StateLogicType;
     /**
-     * Explicit field dependencies for expressions.
+     * Condition that determines when this logic applies.
      *
-     * For `expression`, dependencies are automatically extracted from the expression.
-     * Provide `dependsOn` to override automatic detection for complex expressions.
+     * 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
-     * // Override automatic detection for complex expressions
-     * {
-     *   key: 'total',
-     *   logic: [{
-     *     type: 'derivation',
-     *     expression: 'calculateTotal(formValue)',
-     *     dependsOn: ['quantity', 'unitPrice', 'discount']
-     *   }]
+     * // Static condition
+     * condition: true
+     *
+     * // Field value condition
+     * condition: {
+     *   type: 'fieldValue',
+     *   fieldPath: 'status',
+     *   operator: 'equals',
+     *   value: 'locked'
      * }
+     *
+     * // Form state condition (for buttons)
+     * condition: 'formSubmitting'
      * ```
      */
-    dependsOn?: string[];
-    value?: never;
-    functionName?: never;
-    http?: never;
-    asyncFunctionName?: never;
-    responseExpression?: never;
+    condition: ConditionalExpression | boolean | FormStateCondition;
 }
 /**
- * Base for value derivations.
+ * State logic that evaluates immediately on change (default).
  *
  * @internal
  */
-interface ValueDerivationBase extends SharedDerivationFields {
-    source?: never;
-    /**
-     * Static value to set on this field.
-     *
-     * Use when the derived value is a constant.
-     *
-     * @example
-     * ```typescript
-     * value: '+1'           // String
-     * value: 100            // Number
-     * value: true           // Boolean
-     * value: { code: 'US' } // Object
-     * ```
-     */
-    value: unknown;
+interface ImmediateStateLogicConfig extends BaseStateLogicConfig {
     /**
-     * Explicit field dependencies for value derivations.
-     *
-     * For `value` (static), no dependencies are needed.
-     * Provide `dependsOn` to conditionally re-evaluate when specific fields change.
+     * Trigger for immediate evaluation.
+     * @default 'onChange'
      */
-    dependsOn?: string[];
-    expression?: never;
-    functionName?: never;
-    http?: never;
-    asyncFunctionName?: never;
-    responseExpression?: never;
+    trigger?: 'onChange';
+    /** Not allowed for onChange trigger */
+    debounceMs?: never;
 }
 /**
- * Base for custom sync function derivations.
+ * State logic that evaluates after a debounce period.
  *
  * @internal
  */
-interface FunctionDerivationBase extends SharedDerivationFields {
-    source?: never;
+interface DebouncedStateLogicConfig extends BaseStateLogicConfig {
     /**
-     * Name of a registered custom derivation function.
-     *
-     * The function receives the evaluation context and returns the derived value.
-     * Register functions in `customFnConfig.derivations`.
-     *
-     * @example
-     * ```typescript
-     * functionName: 'getCurrencyForCountry'
-     * functionName: 'calculateTax'
-     * functionName: 'formatPhoneNumber'
-     * ```
+     * Trigger for debounced evaluation.
+     * Evaluates after the value has stabilized for the debounce duration.
      */
-    functionName: string;
+    trigger: 'debounced';
     /**
-     * Explicit field dependencies for function derivations.
-     *
-     * If not provided, defaults to all fields ('*').
-     * Specify `dependsOn` for better performance when the function only
-     * depends on a subset of fields.
-     *
-     * @example
-     * ```typescript
-     * // Only re-evaluate when country changes
-     * {
-     *   key: 'currency',
-     *   logic: [{
-     *     type: 'derivation',
-     *     functionName: 'getCurrencyForCountry',
-     *     dependsOn: ['country']
-     *   }]
-     * }
-     * ```
+     * Debounce duration in milliseconds.
+     * @default 500
      */
-    dependsOn?: string[];
-    value?: never;
-    expression?: never;
-    http?: never;
-    asyncFunctionName?: never;
-    responseExpression?: never;
+    debounceMs?: number;
 }
 /**
- * HTTP derivation that evaluates immediately on change (default).
- * @internal
- */
-type OnChangeHttpDerivationLogicConfig = HttpDerivationBase & ImmediateDerivationTrigger;
-/**
- * HTTP derivation that evaluates after a debounce period.
- * @internal
- */
-type DebouncedHttpDerivationLogicConfig = HttpDerivationBase & DebouncedDerivationTrigger;
-/**
- * Async function derivation that evaluates immediately on change (default).
- * @internal
- */
-type OnChangeAsyncFunctionDerivationLogicConfig = AsyncFunctionDerivationBase & ImmediateDerivationTrigger;
-/**
- * Async function derivation that evaluates after a debounce period.
- * @internal
- */
-type DebouncedAsyncFunctionDerivationLogicConfig = AsyncFunctionDerivationBase & DebouncedDerivationTrigger;
-/**
- * Expression derivation that evaluates immediately on change (default).
- * @internal
- */
-type OnChangeExpressionDerivationLogicConfig = ExpressionDerivationBase & ImmediateDerivationTrigger;
-/**
- * Expression derivation that evaluates after a debounce period.
- * @internal
- */
-type DebouncedExpressionDerivationLogicConfig = ExpressionDerivationBase & DebouncedDerivationTrigger;
-/**
- * Value derivation that evaluates immediately on change (default).
- * @internal
- */
-type OnChangeValueDerivationLogicConfig = ValueDerivationBase & ImmediateDerivationTrigger;
-/**
- * Value derivation that evaluates after a debounce period.
- * @internal
- */
-type DebouncedValueDerivationLogicConfig = ValueDerivationBase & DebouncedDerivationTrigger;
-/**
- * Function derivation that evaluates immediately on change (default).
- * @internal
- */
-type OnChangeFunctionDerivationLogicConfig = FunctionDerivationBase & ImmediateDerivationTrigger;
-/**
- * Function derivation that evaluates after a debounce period.
- * @internal
- */
-type DebouncedFunctionDerivationLogicConfig = FunctionDerivationBase & DebouncedDerivationTrigger;
-/**
- * Configuration for value derivation logic.
+ * Configuration for conditional field state logic.
  *
- * Enables programmatic value derivation based on conditions.
- * Derivations are self-targeting: the logic is placed on the field
- * that should receive the computed value.
+ * Defines how field behavior changes based on conditions.
+ * Supports hiding, disabling, making readonly, or requiring fields
+ * based on form state or field values.
  *
  * @example
  * ```typescript
- * // Set phone prefix based on country selection
- * {
- *   key: 'phonePrefix',
- *   logic: [{
- *     type: 'derivation',
- *     value: '+1',
- *     condition: {
- *       type: 'fieldValue',
- *       fieldPath: 'country',
- *       operator: 'equals',
- *       value: 'USA'
- *     }
- *   }]
- * }
- *
- * // Compute total from quantity and price
- * {
- *   key: 'total',
- *   derivation: 'formValue.quantity * formValue.unitPrice'
- * }
- *
- * // Use custom function for complex logic
+ * // Hide email field when contact method is not email
  * {
- *   key: 'currency',
- *   logic: [{
- *     type: 'derivation',
- *     functionName: 'getCurrencyForCountry'
- *   }]
+ *   type: 'hidden',
+ *   condition: {
+ *     type: 'fieldValue',
+ *     fieldPath: 'contactMethod',
+ *     operator: 'notEquals',
+ *     value: 'email'
+ *   }
  * }
  *
- * // Self-transform with debounced trigger
- * // (applies after user stops typing)
+ * // Disable button when form is submitting
  * {
- *   key: 'email',
- *   logic: [{
- *     type: 'derivation',
- *     expression: 'formValue.email.toLowerCase()',
- *     trigger: 'debounced',
- *     debounceMs: 500
- *   }]
+ *   type: 'disabled',
+ *   condition: 'formSubmitting'
  * }
  *
- * // Array item derivation (formValue is scoped to current item)
+ * // Debounced visibility (avoids flicker during rapid typing)
  * {
- *   key: 'lineTotal',  // Inside array field
- *   derivation: 'formValue.quantity * formValue.unitPrice'
+ *   type: 'hidden',
+ *   trigger: 'debounced',
+ *   debounceMs: 300,
+ *   condition: {
+ *     type: 'fieldValue',
+ *     fieldPath: 'search',
+ *     operator: 'isEmpty'
+ *   }
  * }
  * ```
  *
  * @public
  */
-type DerivationLogicConfig = OnChangeHttpDerivationLogicConfig | DebouncedHttpDerivationLogicConfig | OnChangeAsyncFunctionDerivationLogicConfig | DebouncedAsyncFunctionDerivationLogicConfig | OnChangeExpressionDerivationLogicConfig | DebouncedExpressionDerivationLogicConfig | OnChangeValueDerivationLogicConfig | DebouncedValueDerivationLogicConfig | OnChangeFunctionDerivationLogicConfig | DebouncedFunctionDerivationLogicConfig;
-/**
- * Union type for all logic configurations.
- *
- * - `StateLogicConfig`: For field state changes (hidden, readonly, disabled, required)
- * - `DerivationLogicConfig`: For value derivation (including property derivation via `targetProperty`)
- *
- * @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 StateLogicConfig = ImmediateStateLogicConfig | DebouncedStateLogicConfig;
 /**
- * Type guard to check if a condition is a FormStateCondition.
- *
- * @param condition - The condition to check
- * @returns true if the condition is a FormStateCondition
+ * Shared fields that appear on all derivation logic config variants.
  *
- * @public
- */
-declare function isFormStateCondition(condition: StateLogicConfig['condition'] | DerivationLogicConfig['condition']): condition is FormStateCondition;
-
-/**
- * Configuration for applying predefined schemas
- */
-interface SchemaApplicationConfig {
-    /** Schema application type */
-    type: 'apply' | 'applyWhen' | 'applyWhenValue' | 'applyEach';
-    /** Schema identifier or inline schema definition */
-    schema: string | SchemaDefinition;
-    /** Condition for conditional application */
-    condition?: ConditionalExpression;
-    /** Type predicate for applyWhenValue */
-    typePredicate?: string;
-}
-/**
- * Reusable schema definition that can be referenced by name
+ * @internal
  */
-interface SchemaDefinition {
-    /** Unique schema identifier */
-    name: string;
-    /** Schema description */
-    description?: string;
-    /** Field path pattern this schema applies to */
-    pathPattern?: string;
-    /** Validators to apply */
-    validators?: ValidatorConfig[];
-    /** Logic rules to apply */
-    logic?: LogicConfig[];
-    /** Nested schema applications */
-    subSchemas?: SchemaApplicationConfig[];
-}
-
-/**
- * Custom validator function signature using Angular's public FieldContext API
- *
- * Takes FieldContext (full Angular context) and optional params, returns validation error(s) or null.
- * Provides access to field state, form hierarchy, and other fields for validation logic.
- *
- * **Use FieldContext public APIs to access:**
- * - Current field value: `ctx.value()`
- * - Field state: `ctx.state` (errors, touched, dirty, etc.)
- * - Other field values: `ctx.valueOf(path)` where path is a FieldPath
- * - Other field states: `ctx.stateOf(path)`
- * - Other fields: `ctx.fieldTreeOf(path)`
- * - Current field tree: `ctx.fieldTree`
- *
- * **Return Types:**
- * - Single error: `{ kind: 'errorKind' }` for field-level validation
- * - Multiple errors: `[{ kind: 'error1' }, { kind: 'error2' }]` for cross-field validation
- * - No error: `null` when validation passes
- *
- * **Best Practice - Return Only Error Kind:**
- * Validators should focus on validation logic, not presentation.
- * Return just the error `kind` and configure messages at field level for i18n support.
- *
- * @example Single Field Validation
- * ```typescript
- * const noSpaces: CustomValidator<string> = (ctx) => {
- *   const value = ctx.value();
- *   if (typeof value === 'string' && value.includes(' ')) {
- *     return { kind: 'noSpaces' };
- *   }
- *   return null;
- * };
- *
- * // Field configuration
- * {
- *   key: 'username',
- *   validators: [{ type: 'custom', functionName: 'noSpaces' }],
- *   validationMessages: {
- *     noSpaces: 'Spaces are not allowed'
- *   }
- * }
- * ```
- *
- * @example Cross-Field Validation with valueOf()
- * ```typescript
- * // Compare two fields using public API
- * const lessThan: CustomValidator<number> = (ctx, params) => {
- *   const value = ctx.value();
- *   const compareToPath = params?.field as string;
- *
- *   // Use valueOf() to access other field - public API!
- *   const otherValue = ctx.valueOf(compareToPath as any);
- *
- *   if (otherValue !== undefined && value >= otherValue) {
- *     return { kind: 'notLessThan' };
- *   }
- *   return null;
- * };
- * ```
- *
- * @example Multiple Errors (Cross-Field Validation)
- * ```typescript
- * const validateDateRange: CustomValidator = (ctx) => {
- *   const errors: ValidationError[] = [];
- *
- *   const startDate = ctx.valueOf('startDate' as any);
- *   const endDate = ctx.valueOf('endDate' as any);
- *
- *   if (!startDate) errors.push({ kind: 'startDateRequired' });
- *   if (!endDate) errors.push({ kind: 'endDateRequired' });
- *   if (startDate && endDate && startDate > endDate) {
- *     errors.push({ kind: 'invalidDateRange' });
- *   }
- *
- *   return errors.length > 0 ? errors : null;
- * };
- * ```
- *
- * **Message Resolution Priority:**
- * 1. Field-level `validationMessages[kind]` (highest priority - per-field customization)
- * 2. Form-level `defaultValidationMessages[kind]` (fallback for common messages)
- * 3. **No message configured = Warning logged + error NOT displayed**
- *
- * **Important:** Validator-returned messages are NOT used. All messages MUST be explicitly configured.
- *
- * @template TValue The type of value stored in the field being validated
- */
-type CustomValidator<TValue = unknown> = (ctx: FieldContext<TValue>, params?: Record<string, unknown>) => ValidationError$1 | ValidationError$1[] | null;
-/**
- * Async custom validator configuration using Angular's resource-based API
- *
- * Angular's validateAsync uses the resource API for async validation,
- * which provides better integration with Signal Forms lifecycle management.
- *
- * **Structure:**
- * - `params`: Function that computes params from field context
- * - `factory`: Function that creates a ResourceRef from params signal
- * - `onSuccess`: Maps successful resource result to validation errors
- * - `onError`: Optional handler for resource errors (network failures, etc.)
- *
- * **Use Cases:**
- * - Database lookups via services with resource API
- * - Complex async business logic with Angular resources
- * - Any async operation using Angular's resource pattern
- *
- * **Note:** For HTTP validation, prefer `HttpCustomValidator` which provides
- * a simpler API specifically designed for HTTP requests.
- *
- * @example Database Lookup with Resource
- * ```typescript
- * const checkUsernameAvailable: AsyncCustomValidator<string> = {
- *   params: (ctx) => ({ username: ctx.value() }),
- *   factory: (params) => {
- *     const injector = inject(Injector);
- *     return resource({
- *       request: () => params(),
- *       loader: ({ request }) => {
- *         if (!request?.username) return null;
- *         const service = injector.get(UserService);
- *         return firstValueFrom(service.checkAvailability(request.username));
- *       }
- *     });
- *   },
- *   onSuccess: (result, ctx) => {
- *     if (!result) return null;
- *     return result.available ? null : { kind: 'usernameTaken' };
- *   },
- *   onError: (error, ctx) => {
- *     console.error('Availability check failed:', error);
- *     return null; // Don't block form on network errors
- *   }
- * };
- * ```
- *
- * @template TValue The type of value stored in the field being validated
- * @template TParams The type of params passed to the resource
- * @template TResult The type of result returned by the resource
- */
-interface AsyncCustomValidator<TValue = unknown, TParams = unknown, TResult = unknown> {
-    /**
-     * Function that receives field context and returns resource params.
-     * Params will be tracked as a signal and trigger resource reload when changed.
-     */
-    readonly params: (ctx: FieldContext<TValue>, config?: Record<string, unknown>) => TParams;
+interface SharedDerivationFields {
     /**
-     * Function that creates a ResourceRef from the params signal.
-     * The resource will be automatically managed by Angular's lifecycle.
+     * Logic type identifier for value derivation.
      */
-    readonly factory: (params: Signal<TParams | undefined>) => ResourceRef<TResult | undefined>;
+    type: 'derivation';
     /**
-     * Optional function to map successful resource result to validation errors.
-     * Return null if validation passes, or ValidationError/ValidationError[] if validation fails.
+     * Target property name for property derivation.
+     *
+     * When set, this derivation targets a field property (like `minDate`, `options`,
+     * `label`, `placeholder`) instead of the field's value. The derivation is routed
+     * to the property derivation pipeline.
+     *
+     * When absent, the derivation targets the field's value (default behavior).
+     *
+     * **Depth limit (max 2 levels):** Only simple and single-dot-nested paths are
+     * supported. Paths with 2+ dots (e.g., `'a.b.c'`) will throw at runtime.
+     *
+     * @example
+     * ```typescript
+     * // Property derivation (new unified API)
+     * {
+     *   key: 'endDate',
+     *   type: 'datepicker',
+     *   logic: [{
+     *     type: 'derivation',
+     *     targetProperty: 'minDate',
+     *     expression: 'formValue.startDate'
+     *   }]
+     * }
+     *
+     * // Value derivation (no targetProperty — existing behavior)
+     * {
+     *   key: 'total',
+     *   type: 'input',
+     *   logic: [{
+     *     type: 'derivation',
+     *     expression: 'formValue.quantity * formValue.unitPrice'
+     *   }]
+     * }
+     * ```
      */
-    readonly onSuccess?: (result: TResult, ctx: FieldContext<TValue>) => TreeValidationResult;
+    targetProperty?: string;
     /**
-     * Optional error handler for resource errors (network failures, etc.).
-     * Return null to ignore the error, or ValidationError to display it to the user.
+     * Optional name for this derivation for debugging purposes.
+     *
+     * When provided, this name appears in derivation debug logs,
+     * making it easier to identify specific derivations in complex forms.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   key: 'lineTotal',
+     *   type: 'input',
+     *   logic: [{
+     *     type: 'derivation',
+     *     debugName: 'Calculate line total',
+     *     expression: 'formValue.quantity * formValue.unitPrice'
+     *   }]
+     * }
+     * ```
      */
-    readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError$1 | ValidationError$1[] | null;
-}
-/**
- * HTTP request configuration for validateHttp API
- */
-interface HttpResourceRequest {
-    url: string;
-    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    body?: unknown;
-    headers?: Record<string, string | string[]>;
-}
-/**
- * HTTP-based validator configuration for Angular's validateHttp API
- *
- * Angular's validateHttp provides optimized HTTP validation with automatic
- * request cancellation and integration with the resource API.
- *
- * **Benefits:**
- * - Automatic request cancellation when field value changes
- * - Built-in integration with Angular's resource management
- * - Simpler than AsyncCustomValidator for HTTP use cases
- *
- * **Structure:**
- * - `request`: Function that returns URL string or HttpResourceRequest
- * - `onSuccess`: REQUIRED - Maps HTTP response to validation errors (inverted logic!)
- * - `onError`: Optional handler for HTTP errors (network failures, 4xx/5xx)
- *
- * **Important:** `onSuccess` uses inverted logic - it maps SUCCESSFUL HTTP responses
- * to validation errors. For example, if the API returns `{ available: false }`,
- * your `onSuccess` should return `{ kind: 'usernameTaken' }`.
- *
- * @example Username Availability Check (GET)
- * ```typescript
- * const checkUsername: HttpCustomValidator<string> = {
- *   request: (ctx) => {
- *     const username = ctx.value();
- *     if (!username) return undefined; // Skip validation if empty
- *     return `/api/users/check-username?username=${encodeURIComponent(username)}`;
- *   },
- *   onSuccess: (response, ctx) => {
- *     // Inverted logic: successful response may indicate validation failure
- *     return response.available ? null : { kind: 'usernameTaken' };
- *   },
- *   onError: (error, ctx) => {
- *     console.error('Availability check failed:', error);
- *     return null; // Don't block form on network errors
- *   }
- * };
- * ```
- *
- * @example Address Validation (POST with Body)
- * ```typescript
- * const validateAddress: HttpCustomValidator = {
- *   request: (ctx) => {
- *     const zipCode = ctx.value();
- *     if (!zipCode) return undefined;
- *
- *     return {
- *       url: '/api/validate-address',
- *       method: 'POST',
- *       body: {
- *         street: ctx.valueOf('street' as any),
- *         city: ctx.valueOf('city' as any),
- *         zipCode: zipCode
- *       },
- *       headers: { 'Content-Type': 'application/json' }
- *     };
- *   },
- *   onSuccess: (response) => {
- *     return response.valid ? null : { kind: 'invalidAddress' };
- *   }
- * };
- * ```
- *
- * @template TValue The type of value stored in the field being validated
- * @template TResult The type of HTTP response
- */
-interface HttpCustomValidator<TValue = unknown, TResult = unknown> {
+    debugName?: string;
     /**
-     * Function that returns the HTTP request configuration.
-     * Can return:
-     * - `undefined` to skip validation (e.g., if field is empty)
-     * - `string` for simple GET requests (just the URL)
-     * - `HttpResourceRequest` for full control (method, body, headers)
+     * Condition that determines when this derivation applies.
+     *
+     * Can be:
+     * - `boolean`: Static value (always applies or never applies)
+     * - `ConditionalExpression`: Expression evaluated against field/form values
+     *
+     * Defaults to `true` (always apply).
+     *
+     * Note: FormStateCondition is not supported for derivations.
+     *
+     * @example
+     * ```typescript
+     * // Always compute (default)
+     * condition: true
+     *
+     * // Conditional derivation
+     * condition: {
+     *   type: 'fieldValue',
+     *   fieldPath: 'country',
+     *   operator: 'equals',
+     *   value: 'USA'
+     * }
+     * ```
      */
-    readonly request: (ctx: FieldContext<TValue>, config?: Record<string, unknown>) => string | HttpResourceRequest | undefined;
+    condition?: ConditionalExpression | boolean;
     /**
-     * REQUIRED function to map successful HTTP response to validation errors.
+     * When true, the derivation stops running after the user manually
+     * edits the target field.
      *
-     * **Inverted Logic:** This is called on successful HTTP responses.
-     * Return null if validation passes, or ValidationError/ValidationError[] if validation fails.
+     * This is useful for "smart defaults" — values that should be
+     * auto-filled initially but respected once the user explicitly changes them.
      *
-     * Example: API returns `{ available: false }` → return `{ kind: 'usernameTaken' }`
+     * Uses the field's `dirty()` signal to detect user modification.
+     * Derivations write directly to `value.set()` which does not trigger
+     * `markAsDirty()`, so `dirty === true` reliably indicates a user edit.
+     *
+     * @example
+     * ```typescript
+     * // Auto-fill display name from first + last name, but stop if user edits it
+     * {
+     *   key: 'displayName',
+     *   logic: [{
+     *     type: 'derivation',
+     *     expression: 'formValue.firstName + " " + formValue.lastName',
+     *     stopOnUserOverride: true
+     *   }]
+     * }
+     * ```
      */
-    readonly onSuccess: (result: TResult, ctx: FieldContext<TValue>) => TreeValidationResult;
+    stopOnUserOverride?: boolean;
     /**
-     * Optional error handler for HTTP errors (network failures, 4xx/5xx status codes).
-     * Return null to ignore the error, or ValidationError to display it to the user.
+     * When true (and `stopOnUserOverride` is also true), clears the
+     * user-override flag when any dependency of this derivation changes,
+     * allowing the derivation to run again.
      *
-     * Common pattern: Log the error and return null to avoid blocking form submission
-     * on network issues.
+     * This is useful when a user override should only persist until the
+     * underlying data changes — e.g., when switching countries, the
+     * phone prefix should re-derive even if the user previously edited it.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   key: 'phonePrefix',
+     *   logic: [{
+     *     type: 'derivation',
+     *     value: '+1',
+     *     condition: { type: 'fieldValue', fieldPath: 'country', operator: 'equals', value: 'USA' },
+     *     stopOnUserOverride: true,
+     *     reEngageOnDependencyChange: true,
+     *     dependsOn: ['country']
+     *   }]
+     * }
+     * ```
      */
-    readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError$1 | ValidationError$1[] | null;
+    reEngageOnDependencyChange?: boolean;
 }
-
 /**
- * Interface for dynamic forms logger implementations.
- * Allows custom logging integrations (Sentry, DataDog, etc.)
+ * Trigger variants for derivation timing.
+ * @internal
  */
-interface Logger {
-    /**
-     * Log a debug message.
-     * Use for detailed diagnostic information during development.
-     */
-    debug(message: string, ...args: unknown[]): void;
+type ImmediateDerivationTrigger = {
+    trigger?: 'onChange';
+    debounceMs?: never;
+};
+type DebouncedDerivationTrigger = {
+    trigger: 'debounced';
+    debounceMs?: number;
+};
+/**
+ * Base for HTTP derivations. `source: 'http'` is required.
+ * TypeScript enforces `dependsOn` and `responseExpression` at the type level.
+ *
+ * @internal
+ */
+interface HttpDerivationBase extends SharedDerivationFields {
+    /** Identifies this derivation as HTTP-driven. */
+    source: 'http';
+    /** Forbidden on HTTP source */
+    fn?: never;
+    /** Forbidden on HTTP source */
+    asyncFn?: never;
     /**
-     * Log an info message.
-     * Use for general operational information.
+     * HTTP request configuration for server-driven derivations.
+     *
+     * The request is sent when dependencies change, with automatic
+     * debouncing and cancellation of in-flight requests.
+     *
+     * Configure debounce via the `trigger: 'debounced'` + `debounceMs` mechanism.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   key: 'exchangeRate',
+     *   logic: [{
+     *     type: 'derivation',
+     *     source: 'http',
+     *     http: {
+     *       url: '/api/exchange-rate',
+     *       method: 'GET',
+     *       queryParams: {
+     *         from: 'formValue.sourceCurrency',
+     *         to: 'formValue.targetCurrency',
+     *       },
+     *     },
+     *     responseExpression: 'response.rate',
+     *     dependsOn: ['sourceCurrency', 'targetCurrency'],
+     *   }]
+     * }
+     * ```
      */
-    info(message: string, ...args: unknown[]): void;
+    http: HttpRequestConfig;
     /**
-     * Log a warning message.
-     * Use for potentially problematic situations that don't prevent operation.
+     * Explicit field dependencies. Required for HTTP derivations to prevent
+     * wildcard triggering on every keystroke.
+     *
+     * The wildcard token `'*'` is rejected. The structural token `'$group'`
+     * (and `'$group.X'`) is allowed and resolves to the field's parent container
+     * path — be aware this fires whenever any sibling under that group changes,
+     * so the caller owns the request frequency (consider `trigger: 'debounced'`).
      */
-    warn(message: string, ...args: unknown[]): void;
+    dependsOn: string[];
     /**
-     * Log an error message.
-     * Use for error conditions that may affect functionality.
+     * Expression to extract the derived value from the HTTP response.
+     *
+     * Evaluated via `ExpressionParser` with `{ response }` as the evaluation scope.
+     *
+     * @example
+     * ```typescript
+     * responseExpression: 'response.rate'
+     * responseExpression: 'response.data.suggestedPrice'
+     * ```
      */
-    error(message: string, ...args: unknown[]): void;
+    responseExpression: string;
+    value?: never;
+    expression?: never;
+    functionName?: never;
+    asyncFunctionName?: never;
 }
-
 /**
- * Shared shape for DI-scoped warning trackers that dedupe log output.
- *
- * Used by both the derivation-warning tracker (keys are field paths) and the
- * deprecation-warning tracker (keys are deprecation IDs). The property is
- * generic so the same shape works for any string-keyed warning domain.
+ * Shared fields for both branches of {@link AsyncFunctionDerivationBase}.
  *
  * @internal
  */
-interface WarningTracker {
-    warnedKeys: Set<string>;
+interface AsyncFunctionDerivationShared extends SharedDerivationFields {
+    /** Identifies this derivation as async-function-driven. */
+    source: 'asyncFunction';
+    /** Forbidden on asyncFunction source */
+    fn?: never;
+    /**
+     * Explicit field dependencies. Required for async derivations to prevent
+     * wildcard triggering on every form change.
+     *
+     * The wildcard token `'*'` is rejected. The structural token `'$group'`
+     * (and `'$group.X'`) is allowed and resolves to the field's parent container
+     * path — be aware this fires whenever any sibling under that group changes,
+     * so the caller owns the invocation frequency (handle this via
+     * `trigger: 'debounced'` or via debouncing inside the async function).
+     */
+    dependsOn: string[];
+    value?: never;
+    expression?: never;
+    functionName?: never;
+    http?: never;
+    responseExpression?: never;
 }
-
 /**
- * Represents the state information of a single form field.
- *
- * Used in evaluation contexts to allow expressions and conditions
- * to reference field state (e.g., `fieldState.touched`, `formFieldState.email.dirty`).
+ * Base for async function derivations. `source: 'asyncFunction'` is required.
+ * TypeScript enforces `dependsOn` at the type level, and `asyncFunctionName` /
+ * `asyncFn` are mutually exclusive (XOR).
  *
- * @public
+ * @internal
  */
-interface FieldStateInfo {
-    readonly touched: boolean;
-    readonly dirty: boolean;
-    /** Convenience property: equivalent to `!dirty` */
-    readonly pristine: boolean;
-    readonly valid: boolean;
-    readonly invalid: boolean;
-    readonly pending: boolean;
+type AsyncFunctionDerivationBase = (AsyncFunctionDerivationShared & {
     /**
-     * Whether the field is currently hidden.
+     * Name of a registered async derivation function.
      *
-     * Note: This is a library-managed property, not a native Angular Signal Forms
-     * property. Returns `false` if the field instance does not expose a `hidden` signal.
-     */
-    readonly hidden: boolean;
-    /**
-     * Whether the field is currently readonly.
+     * The function receives the evaluation context and returns a Promise or Observable
+     * of the derived value. Register functions in `customFnConfig.asyncDerivations`.
      *
-     * Note: This is a library-managed property, not a native Angular Signal Forms
-     * property. Returns `false` if the field instance does not expose a `readonly` signal.
+     * @example
+     * ```typescript
+     * {
+     *   key: 'suggestedPrice',
+     *   logic: [{
+     *     type: 'derivation',
+     *     source: 'asyncFunction',
+     *     asyncFunctionName: 'fetchSuggestedPrice',
+     *     dependsOn: ['productId', 'quantity'],
+     *   }]
+     * }
+     * ```
      */
-    readonly readonly: boolean;
+    asyncFunctionName: string;
+    /** Inline form is forbidden when `asyncFunctionName` is set */
+    asyncFn?: never;
+}) | (AsyncFunctionDerivationShared & {
     /**
-     * Whether the field is currently disabled.
+     * Inline async derivation function. Mutually exclusive with `asyncFunctionName`.
      *
-     * Note: This is a library-managed property, not a native Angular Signal Forms
-     * property. Returns `false` if the field instance does not expose a `disabled` signal.
+     * NOT JSON-serializable — for code-only configs. For configs loaded
+     * from JSON / OpenAPI / databases, use `asyncFunctionName` to reference
+     * a function registered in `customFnConfig.asyncDerivations`.
      */
-    readonly disabled: boolean;
-}
-/**
- * Map of field keys to their state information.
- *
- * Used as `formFieldState` in evaluation contexts to access
- * state of any field in the form by key.
- *
- * @public
- */
-type FormFieldStateMap = Record<string, FieldStateInfo | undefined>;
+    asyncFn: AsyncDerivationFunction;
+    /** Registered form is forbidden when `asyncFn` is set */
+    asyncFunctionName?: never;
+});
 /**
- * Field state context for the current field being evaluated.
- *
- * Used as `fieldState` in evaluation contexts.
+ * Base for expression derivations.
  *
- * @public
+ * @internal
  */
-type FieldStateContext = FieldStateInfo;
-
-interface EvaluationContext<TValue = unknown, TFormValue extends Record<string, unknown> = any> {
-    /** Current field value */
-    fieldValue: TValue;
-    /**
-     * 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: TFormValue;
-    /** Field path for relative references */
-    fieldPath: string;
-    /** Custom evaluation functions */
-    customFunctions?: Record<string, (context: EvaluationContext) => unknown>;
-    /** Logger for diagnostic output */
-    logger: Logger;
+interface ExpressionDerivationBase extends SharedDerivationFields {
+    source?: never;
+    /** Forbidden on expression mode */
+    fn?: never;
+    /** Forbidden on expression mode */
+    asyncFn?: never;
     /**
-     * Value of the field's nearest parent **group** (or array item, when the
-     * field has no inner group above the array boundary).
-     *
-     * Complements `formValue` and `fieldValue` for derivations on fields nested
-     * inside groups built by factory helpers, where the parent group's key
-     * isn't known at config-authoring time. Mirrors the runtime semantics of
-     * the `'$group'` token used in `dependsOn`.
+     * JavaScript expression to evaluate for the derived value.
      *
-     * Resolution at evaluation time:
-     * - Inside a group at form root: the parent group's value object (e.g.,
-     *   for `address.state`, `groupValue === formValue.address`).
-     * - Inside nested groups: the innermost parent group's value object.
-     * - Directly inside an array item (no inner group): the array item itself
-     *   (same shape as `formValue` in array context).
-     * - Inside a group inside an array item: the inner group's value object
-     *   within the current item.
-     * - Field at form root with no parent container: `undefined`.
+     * Has access to `formValue` object containing all form values.
+     * For array fields, `formValue` is scoped to the current array item.
+     * Uses the same secure AST-based parser as other expressions.
      *
      * @example
      * ```typescript
-     * // Field 'state' inside group 'address':
-     * deriveStateFromCountry: (ctx) => {
-     *   const country = ctx.groupValue?.country;  // no need to know parent key
-     *   return country === 'usa' ? 'NY' : '';
-     * }
+     * expression: 'formValue.quantity * formValue.unitPrice'
+     * expression: 'formValue.firstName + " " + formValue.lastName'
+     * expression: 'formValue.price * (1 - formValue.discount / 100)'
      * ```
      */
-    groupValue?: unknown;
+    expression: string;
     /**
-     * Root form value when inside an array context.
+     * Explicit field dependencies for expressions.
      *
-     * 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.
+     * For `expression`, dependencies are automatically extracted from the expression.
+     * Provide `dependsOn` to override automatic detection for complex expressions.
      *
      * @example
      * ```typescript
-     * // In an array item derivation (on the lineTotal field inside lineItems array):
+     * // Override automatic detection for complex expressions
      * {
-     *   key: 'lineTotal',
-     *   type: 'input',
-     *   // formValue = current array item { quantity: 2, unitPrice: 50 }
-     *   // rootFormValue = entire form { globalDiscount: 0.1, lineItems: [...] }
-     *   derivation: 'formValue.quantity * formValue.unitPrice * (1 - rootFormValue.globalDiscount)'
+     *   key: 'total',
+     *   logic: [{
+     *     type: 'derivation',
+     *     expression: 'calculateTotal(formValue)',
+     *     dependsOn: ['quantity', 'unitPrice', 'discount']
+     *   }]
      * }
      * ```
-     *
-     * 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;
+    dependsOn?: string[];
+    value?: never;
+    functionName?: never;
+    http?: never;
+    asyncFunctionName?: never;
+    responseExpression?: never;
+}
+/**
+ * Base for value derivations.
+ *
+ * @internal
+ */
+interface ValueDerivationBase extends SharedDerivationFields {
+    source?: never;
+    /** Forbidden on value mode */
+    fn?: never;
+    /** Forbidden on value mode */
+    asyncFn?: never;
     /**
-     * External data signals resolved to their current values.
+     * Static value to set on this field.
      *
-     * This allows forms to reference data from outside the form context
-     * in conditional logic, derivations, and other expressions.
+     * Use when the derived value is a constant.
      *
      * @example
      * ```typescript
-     * // In form config:
-     * externalData: {
-     *   userRole: computed(() => this.userService.currentRole()),
-     *   permissions: computed(() => this.authService.permissions()),
-     * }
-     *
-     * // In JavaScript expression:
-     * condition: {
-     *   type: 'javascript',
-     *   expression: "externalData.userRole === 'admin'"
-     * }
+     * value: '+1'           // String
+     * value: 100            // Number
+     * value: true           // Boolean
+     * value: { code: 'US' } // Object
      * ```
      */
-    externalData?: Record<string, unknown>;
+    value: unknown;
     /**
-     * DI-scoped tracker for deprecation warnings.
-     * Used by the condition evaluator to deduplicate deprecation warnings.
+     * Explicit field dependencies for value derivations.
+     *
+     * For `value` (static), no dependencies are needed.
+     * Provide `dependsOn` to conditionally re-evaluate when specific fields change.
      */
-    deprecationTracker?: WarningTracker;
+    dependsOn?: string[];
+    expression?: never;
+    functionName?: never;
+    http?: never;
+    asyncFunctionName?: never;
+    responseExpression?: never;
+}
+/**
+ * Shared fields for both branches of {@link FunctionDerivationBase}.
+ *
+ * @internal
+ */
+interface FunctionDerivationShared extends SharedDerivationFields {
+    source?: never;
+    /** Forbidden on function-derivation mode */
+    asyncFn?: never;
     /**
-     * State of the current field being evaluated.
+     * Explicit field dependencies for function derivations.
      *
-     * Provides access to field state properties like `touched`, `dirty`, `valid`, etc.
-     * Uses a Proxy for lazy evaluation — properties are only read when accessed.
+     * If not provided, defaults to all fields ('*').
+     * Specify `dependsOn` for better performance when the function only
+     * depends on a subset of fields.
      *
      * @example
      * ```typescript
-     * // In a JavaScript expression:
-     * condition: {
-     *   type: 'javascript',
-     *   expression: "fieldState.touched && fieldState.dirty"
+     * // Only re-evaluate when country changes
+     * {
+     *   key: 'currency',
+     *   logic: [{
+     *     type: 'derivation',
+     *     functionName: 'getCurrencyForCountry',
+     *     dependsOn: ['country']
+     *   }]
      * }
      * ```
      */
-    fieldState?: FieldStateContext;
+    dependsOn?: string[];
+    value?: never;
+    expression?: never;
+    http?: never;
+    asyncFunctionName?: never;
+    responseExpression?: never;
+}
+/**
+ * Base for custom sync function derivations. `functionName` and `fn` are
+ * mutually exclusive (XOR).
+ *
+ * @internal
+ */
+type FunctionDerivationBase = (FunctionDerivationShared & {
     /**
-     * State of all fields in the form, keyed by field key.
+     * Name of a registered custom derivation function.
      *
-     * Provides access to any field's state properties by key.
-     * Uses a Proxy for lazy evaluation — field state is only read when accessed.
+     * The function receives the evaluation context and returns the derived value.
+     * Register functions in `customFnConfig.derivations`.
      *
      * @example
      * ```typescript
-     * // In a JavaScript expression:
-     * condition: {
-     *   type: 'javascript',
-     *   expression: "formFieldState.email.dirty && formFieldState.email.valid"
-     * }
+     * functionName: 'getCurrencyForCountry'
+     * functionName: 'calculateTax'
+     * functionName: 'formatPhoneNumber'
      * ```
      */
-    formFieldState?: FormFieldStateMap;
-    /** Allow additional properties for flexible expression evaluation */
-    [key: string]: unknown;
-}
-
+    functionName: string;
+    /** Inline form is forbidden when `functionName` is set */
+    fn?: never;
+}) | (FunctionDerivationShared & {
+    /**
+     * Inline custom derivation function. Mutually exclusive with `functionName`.
+     *
+     * NOT JSON-serializable — for code-only configs. For configs loaded
+     * from JSON / OpenAPI / databases, use `functionName` to reference
+     * a function registered in `customFnConfig.derivations`.
+     */
+    fn: CustomFunction;
+    /** Registered form is forbidden when `fn` is set */
+    functionName?: never;
+});
 /**
- * Custom function signature for conditional expressions
+ * HTTP derivation that evaluates immediately on change (default).
+ * @internal
+ */
+type OnChangeHttpDerivationLogicConfig = HttpDerivationBase & ImmediateDerivationTrigger;
+/**
+ * HTTP derivation that evaluates after a debounce period.
+ * @internal
+ */
+type DebouncedHttpDerivationLogicConfig = HttpDerivationBase & DebouncedDerivationTrigger;
+/**
+ * Async function derivation that evaluates immediately on change (default).
+ * @internal
+ */
+type OnChangeAsyncFunctionDerivationLogicConfig = AsyncFunctionDerivationBase & ImmediateDerivationTrigger;
+/**
+ * Async function derivation that evaluates after a debounce period.
+ * @internal
+ */
+type DebouncedAsyncFunctionDerivationLogicConfig = AsyncFunctionDerivationBase & DebouncedDerivationTrigger;
+/**
+ * Expression derivation that evaluates immediately on change (default).
+ * @internal
+ */
+type OnChangeExpressionDerivationLogicConfig = ExpressionDerivationBase & ImmediateDerivationTrigger;
+/**
+ * Expression derivation that evaluates after a debounce period.
+ * @internal
+ */
+type DebouncedExpressionDerivationLogicConfig = ExpressionDerivationBase & DebouncedDerivationTrigger;
+/**
+ * Value derivation that evaluates immediately on change (default).
+ * @internal
+ */
+type OnChangeValueDerivationLogicConfig = ValueDerivationBase & ImmediateDerivationTrigger;
+/**
+ * Value derivation that evaluates after a debounce period.
+ * @internal
+ */
+type DebouncedValueDerivationLogicConfig = ValueDerivationBase & DebouncedDerivationTrigger;
+/**
+ * Function derivation that evaluates immediately on change (default).
+ * @internal
+ */
+type OnChangeFunctionDerivationLogicConfig = FunctionDerivationBase & ImmediateDerivationTrigger;
+/**
+ * Function derivation that evaluates after a debounce period.
+ * @internal
+ */
+type DebouncedFunctionDerivationLogicConfig = FunctionDerivationBase & DebouncedDerivationTrigger;
+/**
+ * Configuration for value derivation logic.
  *
- * Custom functions are used for conditional logic in:
- * - `when` conditions (field visibility, conditional validation)
- * - `readonly` logic (dynamic readonly state)
- * - `disabled` logic (dynamic disabled state)
- * - Dynamic value calculations
+ * Enables programmatic value derivation based on conditions.
+ * Derivations are self-targeting: the logic is placed on the field
+ * that should receive the computed value.
  *
- * Unlike validators, custom functions:
- * - Return any value (typically boolean for conditions, but could be strings, numbers, etc.)
- * - Do NOT return ValidationError objects
- * - Receive EvaluationContext (field values) not FieldContext (field state)
+ * @example
+ * ```typescript
+ * // Set phone prefix based on country selection
+ * {
+ *   key: 'phonePrefix',
+ *   logic: [{
+ *     type: 'derivation',
+ *     value: '+1',
+ *     condition: {
+ *       type: 'fieldValue',
+ *       fieldPath: 'country',
+ *       operator: 'equals',
+ *       value: 'USA'
+ *     }
+ *   }]
+ * }
+ *
+ * // Compute total from quantity and price
+ * {
+ *   key: 'total',
+ *   derivation: 'formValue.quantity * formValue.unitPrice'
+ * }
+ *
+ * // Use custom function for complex logic
+ * {
+ *   key: 'currency',
+ *   logic: [{
+ *     type: 'derivation',
+ *     functionName: 'getCurrencyForCountry'
+ *   }]
+ * }
  *
- * @example
- * ```typescript
- * // Boolean condition function
- * const isAdult: CustomFunction = (ctx) => {
- *   return ctx.age >= 18;
- * };
+ * // Self-transform with debounced trigger
+ * // (applies after user stops typing)
+ * {
+ *   key: 'email',
+ *   logic: [{
+ *     type: 'derivation',
+ *     expression: 'formValue.email.toLowerCase()',
+ *     trigger: 'debounced',
+ *     debounceMs: 500
+ *   }]
+ * }
  *
- * // Used in field configuration:
+ * // Array item derivation (formValue is scoped to current item)
  * {
- *   key: 'alcoholPreference',
- *   type: 'select',
- *   when: { function: 'isAdult' }  // Only show if isAdult returns true
+ *   key: 'lineTotal',  // Inside array field
+ *   derivation: 'formValue.quantity * formValue.unitPrice'
  * }
  * ```
  *
- * @example
- * ```typescript
- * // Calculation function
- * const calculateDiscount: CustomFunction = (ctx) => {
- *   const price = ctx.price || 0;
- *   const isVip = ctx.isVip || false;
- *   return isVip ? price * 0.8 : price * 0.9;
- * };
- * ```
+ * @public
  */
-type CustomFunction<TFormValue extends Record<string, unknown> = any> = (context: EvaluationContext<unknown, TFormValue>) => unknown;
-
+type DerivationLogicConfig = OnChangeHttpDerivationLogicConfig | DebouncedHttpDerivationLogicConfig | OnChangeAsyncFunctionDerivationLogicConfig | DebouncedAsyncFunctionDerivationLogicConfig | OnChangeExpressionDerivationLogicConfig | DebouncedExpressionDerivationLogicConfig | OnChangeValueDerivationLogicConfig | DebouncedValueDerivationLogicConfig | OnChangeFunctionDerivationLogicConfig | DebouncedFunctionDerivationLogicConfig;
 /**
- * Async function for derivations — returns any value.
- *
- * The function receives the evaluation context and may return a Promise or Observable.
- * Register functions in `customFnConfig.asyncDerivations`.
+ * Union type for all logic configurations.
  *
- * @example
- * ```typescript
- * const fetchPrice: AsyncDerivationFunction = async (context) => {
- *   const response = await fetch(`/api/price?product=${context.formValue.productId}`);
- *   const data = await response.json();
- *   return data.price;
- * };
- * ```
+ * - `StateLogicConfig`: For field state changes (hidden, readonly, disabled, required)
+ * - `DerivationLogicConfig`: For value derivation (including property derivation via `targetProperty`)
  *
  * @public
  */
-type AsyncDerivationFunction<TFormValue extends Record<string, unknown> = any> = (context: EvaluationContext<unknown, TFormValue>) => Promise<unknown> | Observable<unknown>;
+type LogicConfig = StateLogicConfig | DerivationLogicConfig;
 /**
- * Async function for conditions — returns boolean.
+ * Log level for derivation debug output.
  *
- * The function receives the evaluation context and may return a Promise or Observable.
- * Register functions in `customFnConfig.asyncConditions`.
+ * - 'none': No debug logging
+ * - 'summary': Log cycle completion with counts (default in dev mode)
+ * - 'verbose': Log individual derivation evaluations with details
  *
- * @example
- * ```typescript
- * const checkPermission: AsyncConditionFunction = async (context) => {
- *   const response = await fetch(`/api/permissions?user=${context.formValue.userId}`);
- *   const data = await response.json();
- *   return data.canEdit;
- * };
- * ```
+ * @public
+ */
+type DerivationLogLevel = 'none' | 'summary' | 'verbose';
+/**
+ * Type guard to check if a condition is a FormStateCondition.
+ *
+ * @param condition - The condition to check
+ * @returns true if the condition is a FormStateCondition
  *
  * @public
  */
-type AsyncConditionFunction<TFormValue extends Record<string, unknown> = any> = (context: EvaluationContext<unknown, TFormValue>) => Promise<boolean> | Observable<boolean>;
+declare function isFormStateCondition(condition: StateLogicConfig['condition'] | DerivationLogicConfig['condition']): condition is FormStateCondition;
+
+/**
+ * Configuration for applying predefined schemas
+ */
+interface SchemaApplicationConfig {
+    /** Schema application type */
+    type: 'apply' | 'applyWhen' | 'applyWhenValue' | 'applyEach';
+    /** Schema identifier or inline schema definition */
+    schema: string | SchemaDefinition;
+    /** Condition for conditional application */
+    condition?: ConditionalExpression;
+    /** Type predicate for applyWhenValue */
+    typePredicate?: string;
+}
+/**
+ * Reusable schema definition that can be referenced by name
+ */
+interface SchemaDefinition {
+    /** Unique schema identifier */
+    name: string;
+    /** Schema description */
+    description?: string;
+    /** Field path pattern this schema applies to */
+    pathPattern?: string;
+    /** Validators to apply */
+    validators?: ValidatorConfig[];
+    /** Logic rules to apply */
+    logic?: LogicConfig[];
+    /** Nested schema applications */
+    subSchemas?: SchemaApplicationConfig[];
+}
+
+type DynamicText = string | Observable<string> | Signal<string>;
 
 /**
  * Re-export Angular's ValidationError for consistency
@@ -2244,7 +2185,6 @@ type SubmissionActionResult = Promise<TreeValidationResult> | Observable<TreeVal
  * @typeParam TValue - The form value type
  *
  * @public
- * @experimental
  */
 interface SubmissionConfig<TValue = unknown> {
     /**
@@ -3257,6 +3197,58 @@ interface TextField extends FieldDef<TextProps> {
     readonly logic?: NonFieldLogicConfig[];
 }
 
+/**
+ * Scalar types supported by hidden fields.
+ * These are the primitive value types that can be stored.
+ */
+type HiddenScalar = string | number | boolean;
+/**
+ * All value types supported by hidden fields.
+ * Supports both scalar values and arrays of scalars for storing
+ * multiple IDs or similar data.
+ */
+type HiddenValue = HiddenScalar | HiddenScalar[];
+/**
+ * Hidden field definition for storing values without rendering UI.
+ *
+ * Hidden fields participate in the form schema and contribute to form values,
+ * but do not render any visible component. They are useful for:
+ * - Storing IDs when updating existing records
+ * - Persisting metadata that shouldn't be user-editable
+ * - Tracking computed values that need to be submitted
+ *
+ * Unlike the `hidden` property on other fields (which hides a rendered field),
+ * this field type renders nothing at all - it's a componentless field.
+ *
+ * @example
+ * ```typescript
+ * // Store a record ID for updates
+ * const idField: HiddenField<string> = {
+ *   type: 'hidden',
+ *   key: 'id',
+ *   value: '550e8400-e29b-41d4-a716-446655440000',
+ * };
+ *
+ * // Store multiple tag IDs
+ * const tagIdsField: HiddenField<number[]> = {
+ *   type: 'hidden',
+ *   key: 'tagIds',
+ *   value: [1, 2, 3],
+ * };
+ * ```
+ *
+ * @typeParam TValue - The type of value stored (must be HiddenValue compatible)
+ */
+interface HiddenField<TValue extends HiddenValue = HiddenValue> extends FieldDef<never> {
+    /** Discriminant for hidden field type */
+    type: 'hidden';
+    /**
+     * The value to store in the form.
+     * This is required - a hidden field without a value serves no purpose.
+     */
+    value: TValue;
+}
+
 /**
  * Configuration for the built-in 'css' wrapper type.
  *
@@ -3284,17 +3276,129 @@ interface CssWrapper {
  * horizontal field arrangement with 12-column sizing utilities (`df-col-1`
  * through `df-col-12`) available to child fields via their own `col` property.
  *
- * Applied automatically by `rowFieldMapper` when a user writes `{ type: 'row' }` —
- * users do not construct this config directly.
+ * Applied automatically by `rowFieldMapper` when a user writes `{ type: 'row' }` —
+ * users do not construct this config directly.
+ *
+ * @example
+ * ```typescript
+ * const wrapper: RowWrapper = { type: 'row' };
+ * ```
+ */
+interface RowWrapper {
+    readonly type: 'row';
+}
+
+/**
+ * Resolves a wrapper type name to its registered config interface.
+ *
+ * When `TWrappers` is a specific registered key (e.g., `'css'`), resolves to
+ * the full config type from `FieldRegistryWrappers` (e.g., `CssWrapper`),
+ * providing type-safe access to wrapper-specific properties like `cssClasses`.
+ *
+ * When `TWrappers` is the full `RegisteredWrapperTypes` union, distributes
+ * to produce a discriminated union of all registered wrapper configs.
+ *
+ * @example
+ * ```typescript
+ * // Resolves to CssWrapper — cssClasses is typed
+ * type CssConfig = WrapperConfig<'css'>;
+ *
+ * // Union of all registered wrapper configs
+ * type AnyConfig = WrapperConfig;
+ * ```
+ */
+type WrapperConfig<TWrappers extends RegisteredWrapperTypes = RegisteredWrapperTypes> = TWrappers extends keyof FieldRegistryWrappers ? FieldRegistryWrappers[TWrappers] : {
+    readonly type: TWrappers;
+};
+/**
+ * Signature of a lazy component loader — either a direct component class or
+ * an ES module whose `default` export is the component. Shared by field and
+ * wrapper registrations so the `loadComponent: () => import('./x.component')`
+ * idiom types cleanly in both places.
+ */
+type LazyComponentLoader<T = unknown> = () => Promise<Type<T> | {
+    default: Type<T>;
+}>;
+/**
+ * Configuration interface for registering wrapper types.
+ *
+ * Defines how a wrapper component is loaded and identified. Wrapper components
+ * provide visual decoration around field content (sections, headers, styling)
+ * without affecting the form data structure.
+ *
+ * @example
+ * ```typescript
+ * const SectionWrapper: WrapperTypeDefinition = {
+ *   name: 'section',
+ *   loadComponent: () => import('./section-wrapper.component').then(m => m.SectionWrapperComponent),
+ * };
+ * ```
+ */
+interface WrapperTypeDefinition<T extends WrapperConfig = WrapperConfig> {
+    /** Unique identifier for the wrapper type (also serves as discriminant from FieldTypeDefinition) */
+    wrapperName: string;
+    /** Wrapper definition type marker (internal use) */
+    _wrapper?: T;
+    /**
+     * Function to load the wrapper component (supports lazy loading).
+     * Returns a Promise that resolves to the component class or module with default export.
+     */
+    loadComponent: LazyComponentLoader;
+    /**
+     * Field types this wrapper should auto-apply to.
+     *
+     * When a field's `type` matches any entry, the wrapper is injected into that
+     * field's effective wrapper chain at the lowest priority (can be overridden
+     * by `FormConfig.defaultWrappers` or the field-level `wrappers` array, and
+     * fully cleared with `wrappers: null`).
+     */
+    types?: readonly string[];
+}
+/**
+ * Type guard for WrapperTypeDefinition.
+ *
+ * Discriminates via `wrapperName` — field types use `name`, wrapper types use `wrapperName`.
+ */
+declare function isWrapperTypeDefinition(value: unknown): value is WrapperTypeDefinition;
+/**
+ * Contract that wrapper components must satisfy.
+ *
+ * Each wrapper exposes a `#fieldComponent` ViewContainerRef where the inner
+ * content (next wrapper, or the field) is rendered imperatively. Config
+ * properties (minus `type`) are set on the component via `setInput`; a
+ * wrapper opts into a key by declaring a matching `input()`, and unknown
+ * keys are silently dropped. Wrappers may additionally declare a
+ * `fieldInputs` input for the wrapped field's mapper outputs (see
+ * `WrapperFieldInputs` for when that's undefined).
  *
  * @example
  * ```typescript
- * const wrapper: RowWrapper = { type: 'row' };
+ * @Component({
+ *   template: `
+ *     <dbx-section [header]="header() ?? ''">
+ *       <ng-container #fieldComponent></ng-container>
+ *     </dbx-section>
+ *   `,
+ * })
+ * export class SectionWrapperComponent implements FieldWrapper {
+ *   readonly fieldComponent = viewChild.required('fieldComponent', { read: ViewContainerRef });
+ *   readonly header = input<string>();
+ *   readonly fieldInputs = input<WrapperFieldInputs>();
+ * }
  * ```
  */
-interface RowWrapper {
-    readonly type: 'row';
+interface FieldWrapper {
+    /** ViewContainerRef slot where inner content is rendered */
+    readonly fieldComponent: Signal<ViewContainerRef>;
 }
+/**
+ * Injection token for the wrapper type registry.
+ *
+ * Provides access to the map of registered wrapper types. The registry is
+ * populated via `provideDynamicForm()` and used by `ContainerFieldComponent` to
+ * resolve wrapper types to their component implementations.
+ */
+declare const WRAPPER_REGISTRY: InjectionToken<Map<string, WrapperTypeDefinition<RowWrapper | _ng_forge_dynamic_forms.CssWrapper>>>;
 
 /**
  * Container field interface for wrapping child fields with UI chrome.
@@ -3346,36 +3450,281 @@ interface RowWrapper {
  * };
  * ```
  */
-interface ContainerField<TFields extends readonly ContainerAllowedChildren[] = readonly ContainerAllowedChildren[], TWrapperConfigs extends readonly WrapperConfig[] = readonly WrapperConfig[]> extends FieldDef<never> {
-    type: 'container';
-    /** Child definitions to render within this container */
-    readonly fields: TFields;
+interface ContainerField<TFields extends readonly ContainerAllowedChildren[] = readonly ContainerAllowedChildren[], TWrapperConfigs extends readonly WrapperConfig[] = readonly WrapperConfig[]> extends FieldDef<never> {
+    type: 'container';
+    /** Child definitions to render within this container */
+    readonly fields: TFields;
+    /**
+     * Wrapper components to chain around the children.
+     * Applied outermost-first: the first wrapper in the array is the outermost.
+     * Each wrapper component receives the subsequent wrapper (or children) inside
+     * its `#fieldComponent` ViewContainerRef slot.
+     */
+    readonly wrappers: TWrapperConfigs;
+    /** Container fields do not have a label property */
+    readonly label?: never;
+    /** Containers do not support meta — they have no native form element */
+    readonly meta?: never;
+    /**
+     * Logic configurations for conditional container visibility.
+     * Only 'hidden' type logic is supported for containers.
+     */
+    readonly logic?: ContainerLogicConfig[];
+}
+/**
+ * Type guard for ContainerField with proper type narrowing.
+ *
+ * `wrappers` is part of the type but optional in practice — many configs use
+ * containers purely as flex/layout wrappers without any wrapper components.
+ * Match on `type === 'container'` and the `fields` shape only, mirroring
+ * `isPageField` / `isRowField`.
+ */
+declare function isContainerTypedField(field: FieldDef<any>): field is ContainerField;
+
+/**
+ * Type constraints for field nesting rules
+ * These ensure that container fields can only contain valid child field types
+ *
+ * Note: We explicitly list types instead of using Exclude to avoid circular dependencies
+ */
+/**
+ * Fields that are allowed as children of Page fields
+ * Pages can contain: rows, groups, arrays, and leaf fields (but NOT other pages)
+ */
+type PageAllowedChildren = LeafFieldTypes | RowField | GroupField | ArrayField | SimplifiedArrayField | ContainerField;
+/**
+ * Fields that are allowed as children of Group fields
+ * Groups can contain: rows and leaf fields (but NOT pages or other groups)
+ */
+type GroupAllowedChildren = LeafFieldTypes | RowField | ContainerField;
+/**
+ * Fields that are allowed as children of Array fields
+ * Arrays can contain: rows, groups, and leaf fields (but NOT pages or other arrays)
+ * Groups are used for creating object arrays where each array item is an object
+ */
+type ArrayAllowedChildren = LeafFieldTypes | RowField | GroupField | ContainerField;
+/**
+ * Fields that are allowed as children of Container fields.
+ * Containers are pure layout primitives that flatten their children into the
+ * parent form, so most registered field types may appear inside — including
+ * hidden fields and other containers — but NOT pages.
+ */
+type ContainerAllowedChildren = LeafFieldTypes | RowField | GroupField | ArrayField | SimplifiedArrayField | ContainerField;
+/**
+ * Row is a synthetic field type that resolves to a Container at runtime, so
+ * it accepts the same children as a Container.
+ */
+type RowAllowedChildren = ContainerAllowedChildren;
+
+/**
+ * An array item template is an array of allowed children that defines one OBJECT array item's fields.
+ * Used for object arrays where each item is `{ key1: value1, key2: value2, ... }`.
+ */
+type ArrayItemTemplate = readonly ArrayAllowedChildren[];
+/**
+ * An array item definition can be either:
+ * - A single field (ArrayAllowedChildren) for PRIMITIVE array items - extracts field value directly
+ * - An array of fields (ArrayItemTemplate) for OBJECT array items - merges fields into object
+ *
+ * This allows support for:
+ * - Primitive arrays: `['tag1', 'tag2']`
+ * - Object arrays: `[{ name: 'Alice', email: '...' }]`
+ * - Heterogeneous arrays: `[{ value: 'x' }, 'y']` (mixed primitives and objects)
+ */
+type ArrayItemDefinition = ArrayAllowedChildren | ArrayItemTemplate;
+/**
+ * Array field interface for creating dynamic field collections that map to array values.
+ *
+ * Key concepts:
+ * - The outer `fields` array defines INITIAL ITEMS (each element is one array item to render)
+ * - Each element can be either:
+ *   - A single FieldDef (primitive item) - the field's value is extracted directly
+ *   - An array of FieldDefs (object item) - fields are merged into an object
+ * - Items can have different field configurations (heterogeneous arrays supported)
+ * - Empty `fields: []` means no initial items - user adds via buttons with explicit templates
+ * - Initial values are declared via `value` property on each field definition
+ *
+ * @example
+ * // Primitive array: ['angular', 'typescript']
+ * {
+ *   key: 'tags',
+ *   type: 'array',
+ *   fields: [
+ *     { key: 'tag', type: 'input', value: 'angular' },      // Single field = primitive
+ *     { key: 'tag', type: 'input', value: 'typescript' },
+ *   ]
+ * }
+ *
+ * @example
+ * // Object array: [{ name: 'Alice', email: '...' }]
+ * {
+ *   key: 'contacts',
+ *   type: 'array',
+ *   fields: [
+ *     [                                                      // Array = object
+ *       { key: 'name', type: 'input', value: 'Alice' },
+ *       { key: 'email', type: 'input', value: 'alice@example.com' }
+ *     ],
+ *   ]
+ * }
+ *
+ * @example
+ * // Heterogeneous array: [{ label: 'Structured' }, 'Simple']
+ * {
+ *   key: 'items',
+ *   type: 'array',
+ *   fields: [
+ *     [{ key: 'label', type: 'input', value: 'Structured' }],  // Object item
+ *     { key: 'value', type: 'input', value: 'Simple' },        // Primitive item
+ *   ]
+ * }
+ *
+ * @example
+ * // Empty array (add items via buttons)
+ * {
+ *   key: 'tags',
+ *   type: 'array',
+ *   fields: []  // No initial items - user adds via button with template
+ * }
+ *
+ * Nesting constraints: Arrays can contain rows, leaf fields, or groups (for object arrays),
+ * but NOT pages or other arrays. Runtime validation enforces these rules.
+ *
+ * Note: Arrays are container fields and do not support `meta` since they have no native form element.
+ */
+interface ArrayField<TFields extends readonly ArrayItemDefinition[] = readonly ArrayItemDefinition[]> extends FieldDef<never> {
+    type: 'array';
+    /**
+     * Array of item definitions. Each element defines one array item:
+     * - Single FieldDef = primitive item (field's value is extracted directly)
+     * - Array of FieldDefs = object item (fields are merged into an object)
+     * - Empty array `[]` = no initial items (add via buttons with explicit templates)
+     * - Items can have different configurations (heterogeneous arrays supported)
+     * - Initial values are set via `value` property on each field definition
+     */
+    readonly fields: TFields;
+    /** Array fields do not have a label property **/
+    readonly label?: never;
+    /** Arrays do not support meta - they have no native form element **/
+    readonly meta?: never;
+    /**
+     * Logic configurations for conditional array visibility.
+     * Only 'hidden' type logic is supported for arrays.
+     */
+    readonly logic?: ContainerLogicConfig[];
+    /**
+     * Minimum number of items required in the array.
+     * Validation fails if the array has fewer items than this value.
+     */
+    readonly minLength?: number;
+    /**
+     * Maximum number of items allowed in the array.
+     * Validation fails if the array has more items than this value.
+     */
+    readonly maxLength?: number;
+}
+/**
+ * Type guard for ArrayField with proper type narrowing.
+ * Validates that the field is an array type with a fields property that is an array.
+ * Fields can contain either single FieldDefs (primitive items) or arrays of FieldDefs (object items).
+ */
+declare function isArrayField(field: FieldDef<any>): field is ArrayField;
+/**
+ * Configuration for auto-generated add/remove buttons in simplified array fields.
+ */
+interface ArrayButtonConfig {
+    /** Custom label for the button */
+    readonly label?: string;
+    /** Additional properties passed to the button component */
+    readonly props?: Record<string, unknown>;
+}
+/**
+ * Simplified array field interface for common use cases.
+ *
+ * Instead of manually specifying each item in `fields`, provide a `template` that defines
+ * the structure of a single item, and a `value` array with initial data.
+ * The library auto-generates add/remove buttons.
+ *
+ * Discriminant: `template` presence → simplified API; `Array.isArray(template)` → object vs primitive.
+ *
+ * @example
+ * // Primitive array: ['angular', 'typescript']
+ * {
+ *   key: 'tags',
+ *   type: 'array',
+ *   template: { key: 'value', type: 'input', label: 'Tag', required: true },
+ *   value: ['angular', 'typescript']
+ * }
+ *
+ * @example
+ * // Object array: [{ name: 'Jane', phone: '555' }]
+ * {
+ *   key: 'contacts',
+ *   type: 'array',
+ *   template: [
+ *     { key: 'name', type: 'input', label: 'Contact Name', required: true },
+ *     { key: 'phone', type: 'input', label: 'Phone Number' },
+ *   ],
+ *   value: [{ name: 'Jane', phone: '555' }]
+ * }
+ *
+ * @example
+ * // Button customization / opt-out
+ * {
+ *   key: 'tags',
+ *   type: 'array',
+ *   template: { key: 'value', type: 'input', label: 'Tag' },
+ *   addButton: { label: 'Add Tag', props: { color: 'primary' } },
+ *   removeButton: false
+ * }
+ */
+interface SimplifiedArrayField extends FieldDef<never> {
+    type: 'array';
     /**
-     * Wrapper components to chain around the children.
-     * Applied outermost-first: the first wrapper in the array is the outermost.
-     * Each wrapper component receives the subsequent wrapper (or children) inside
-     * its `#fieldComponent` ViewContainerRef slot.
+     * Template defining the structure of a single array item.
+     * - Single field (ArrayAllowedChildren) → primitive array (each item is a single value)
+     * - Array of fields (readonly ArrayAllowedChildren[]) → object array (each item is an object)
      */
-    readonly wrappers: TWrapperConfigs;
-    /** Container fields do not have a label property */
+    readonly template: ArrayAllowedChildren | readonly ArrayAllowedChildren[];
+    /** Initial values for the array. Each element creates one array item. */
+    readonly value?: readonly unknown[];
+    /**
+     * Configuration for the auto-generated "Add" button, or `false` to disable it.
+     * Defaults to a button with label "Add".
+     */
+    readonly addButton?: ArrayButtonConfig | false;
+    /**
+     * Configuration for the auto-generated "Remove" button on each item, or `false` to disable it.
+     * Defaults to a button with label "Remove".
+     */
+    readonly removeButton?: ArrayButtonConfig | false;
+    /** Simplified arrays do not support the label property */
     readonly label?: never;
-    /** Containers do not support meta — they have no native form element */
+    /** Simplified arrays do not support meta */
     readonly meta?: never;
     /**
-     * Logic configurations for conditional container visibility.
-     * Only 'hidden' type logic is supported for containers.
+     * Logic configurations for conditional array visibility.
+     * Only 'hidden' type logic is supported for arrays.
      */
     readonly logic?: ContainerLogicConfig[];
+    /**
+     * Minimum number of items required in the array.
+     * Validation fails if the array has fewer items than this value.
+     */
+    readonly minLength?: number;
+    /**
+     * Maximum number of items allowed in the array.
+     * Validation fails if the array has more items than this value.
+     */
+    readonly maxLength?: number;
+    /** Mutually exclusive with `template` — use `fields` for the full API instead */
+    readonly fields?: never;
 }
 /**
- * Type guard for ContainerField with proper type narrowing.
- *
- * `wrappers` is part of the type but optional in practice — many configs use
- * containers purely as flex/layout wrappers without any wrapper components.
- * Match on `type === 'container'` and the `fields` shape only, mirroring
- * `isPageField` / `isRowField`.
+ * Type guard for SimplifiedArrayField.
+ * Checks for `type: 'array'` with a `template` property (discriminant from full ArrayField).
  */
-declare function isContainerTypedField(field: FieldDef<any>): field is ContainerField;
+declare function isSimplifiedArrayField(field: FieldDef<any>): field is SimplifiedArrayField;
 
 /**
  * Container fields registry - augment this interface to add custom container fields
@@ -3525,180 +3874,6 @@ type NarrowField<T> = T extends {
  */
 type NarrowFields = readonly NarrowField<RegisteredFieldTypes>[];
 
-/**
- * Type constraints for field nesting rules
- * These ensure that container fields can only contain valid child field types
- *
- * Note: We explicitly list types instead of using Exclude to avoid circular dependencies
- */
-/**
- * Fields that are allowed as children of Page fields
- * Pages can contain: rows, groups, arrays, and leaf fields (but NOT other pages)
- */
-type PageAllowedChildren = LeafFieldTypes | RowField | GroupField | ArrayField | SimplifiedArrayField | ContainerField;
-/**
- * Fields that are allowed as children of Group fields
- * Groups can contain: rows and leaf fields (but NOT pages or other groups)
- */
-type GroupAllowedChildren = LeafFieldTypes | RowField | ContainerField;
-/**
- * Fields that are allowed as children of Array fields
- * Arrays can contain: rows, groups, and leaf fields (but NOT pages or other arrays)
- * Groups are used for creating object arrays where each array item is an object
- */
-type ArrayAllowedChildren = LeafFieldTypes | RowField | GroupField | ContainerField;
-/**
- * Fields that are allowed as children of Container fields.
- * Containers are pure layout primitives that flatten their children into the
- * parent form, so most registered field types may appear inside — including
- * hidden fields and other containers — but NOT pages.
- */
-type ContainerAllowedChildren = LeafFieldTypes | RowField | GroupField | ArrayField | SimplifiedArrayField | ContainerField;
-/**
- * Row is a synthetic field type that resolves to a Container at runtime, so
- * it accepts the same children as a Container.
- */
-type RowAllowedChildren = ContainerAllowedChildren;
-
-/**
- * Row field interface for creating horizontal layouts.
- * A row is a synthetic field type that resolves to a Container at runtime,
- * with a synthesized `{ type: 'row' }` wrapper applied for layout. The row
- * itself does not hold a value — its children flatten into the parent form.
- *
- * Note: Rows do not support `meta` since they have no native form element.
- */
-interface RowField<TFields extends readonly RowAllowedChildren[] = readonly RowAllowedChildren[]> extends FieldDef<never> {
-    type: 'row';
-    /** Child definitions to render within this row */
-    readonly fields: TFields;
-    /** Row fields do not have a label property **/
-    readonly label?: never;
-    /** Rows do not support meta - they have no native form element **/
-    readonly meta?: never;
-    /**
-     * Logic configurations for conditional row visibility.
-     * Only 'hidden' type logic is supported for rows.
-     */
-    readonly logic?: ContainerLogicConfig[];
-}
-/**
- * Type guard for RowField with proper type narrowing
- */
-declare function isRowField(field: FieldDef<any>): field is RowField;
-
-/**
- * Resolves a wrapper type name to its registered config interface.
- *
- * When `TWrappers` is a specific registered key (e.g., `'css'`), resolves to
- * the full config type from `FieldRegistryWrappers` (e.g., `CssWrapper`),
- * providing type-safe access to wrapper-specific properties like `cssClasses`.
- *
- * When `TWrappers` is the full `RegisteredWrapperTypes` union, distributes
- * to produce a discriminated union of all registered wrapper configs.
- *
- * @example
- * ```typescript
- * // Resolves to CssWrapper — cssClasses is typed
- * type CssConfig = WrapperConfig<'css'>;
- *
- * // Union of all registered wrapper configs
- * type AnyConfig = WrapperConfig;
- * ```
- */
-type WrapperConfig<TWrappers extends RegisteredWrapperTypes = RegisteredWrapperTypes> = TWrappers extends keyof FieldRegistryWrappers ? FieldRegistryWrappers[TWrappers] : {
-    readonly type: TWrappers;
-};
-/**
- * Signature of a lazy component loader — either a direct component class or
- * an ES module whose `default` export is the component. Shared by field and
- * wrapper registrations so the `loadComponent: () => import('./x.component')`
- * idiom types cleanly in both places.
- */
-type LazyComponentLoader<T = unknown> = () => Promise<Type<T> | {
-    default: Type<T>;
-}>;
-/**
- * Configuration interface for registering wrapper types.
- *
- * Defines how a wrapper component is loaded and identified. Wrapper components
- * provide visual decoration around field content (sections, headers, styling)
- * without affecting the form data structure.
- *
- * @example
- * ```typescript
- * const SectionWrapper: WrapperTypeDefinition = {
- *   name: 'section',
- *   loadComponent: () => import('./section-wrapper.component').then(m => m.SectionWrapperComponent),
- * };
- * ```
- */
-interface WrapperTypeDefinition<T extends WrapperConfig = WrapperConfig> {
-    /** Unique identifier for the wrapper type (also serves as discriminant from FieldTypeDefinition) */
-    wrapperName: string;
-    /** Wrapper definition type marker (internal use) */
-    _wrapper?: T;
-    /**
-     * Function to load the wrapper component (supports lazy loading).
-     * Returns a Promise that resolves to the component class or module with default export.
-     */
-    loadComponent: LazyComponentLoader;
-    /**
-     * Field types this wrapper should auto-apply to.
-     *
-     * When a field's `type` matches any entry, the wrapper is injected into that
-     * field's effective wrapper chain at the lowest priority (can be overridden
-     * by `FormConfig.defaultWrappers` or the field-level `wrappers` array, and
-     * fully cleared with `wrappers: null`).
-     */
-    types?: readonly string[];
-}
-/**
- * Type guard for WrapperTypeDefinition.
- *
- * Discriminates via `wrapperName` — field types use `name`, wrapper types use `wrapperName`.
- */
-declare function isWrapperTypeDefinition(value: unknown): value is WrapperTypeDefinition;
-/**
- * Contract that wrapper components must satisfy.
- *
- * Each wrapper exposes a `#fieldComponent` ViewContainerRef where the inner
- * content (next wrapper, or the field) is rendered imperatively. Config
- * properties (minus `type`) are set on the component via `setInput`; a
- * wrapper opts into a key by declaring a matching `input()`, and unknown
- * keys are silently dropped. Wrappers may additionally declare a
- * `fieldInputs` input for the wrapped field's mapper outputs (see
- * `WrapperFieldInputs` for when that's undefined).
- *
- * @example
- * ```typescript
- * @Component({
- *   template: `
- *     <dbx-section [header]="header() ?? ''">
- *       <ng-container #fieldComponent></ng-container>
- *     </dbx-section>
- *   `,
- * })
- * export class SectionWrapperComponent implements FieldWrapper {
- *   readonly fieldComponent = viewChild.required('fieldComponent', { read: ViewContainerRef });
- *   readonly header = input<string>();
- *   readonly fieldInputs = input<WrapperFieldInputs>();
- * }
- * ```
- */
-interface FieldWrapper {
-    /** ViewContainerRef slot where inner content is rendered */
-    readonly fieldComponent: Signal<ViewContainerRef>;
-}
-/**
- * Injection token for the wrapper type registry.
- *
- * Provides access to the map of registered wrapper types. The registry is
- * populated via `provideDynamicForm()` and used by `ContainerFieldComponent` to
- * resolve wrapper types to their component implementations.
- */
-declare const WRAPPER_REGISTRY: InjectionToken<Map<string, WrapperTypeDefinition<RowWrapper | _ng_forge_dynamic_forms.CssWrapper>>>;
-
 /**
  * Base interface for native HTML attributes that can be passed to form field elements.
  *
@@ -3798,18 +3973,26 @@ interface FieldDef<TProps, TMeta extends FieldMeta = FieldMeta> {
     /**
      * Field type identifier for component selection.
      *
-     * Determines which component will be rendered for this field.
-     * Must match a registered field type name in the field registry.
+     * Determines which component will be rendered for this field. Names
+     * registered through module augmentation of `DynamicFormFieldRegistry`
+     * are surfaced as IDE autocomplete suggestions via `RegisteredFieldTypes`;
+     * the `(string & {})` branch keeps arbitrary custom identifiers accepted
+     * as an escape hatch for fields that haven't been augmented into the
+     * registry.
      *
      * @example
      * ```typescript
-     * type: 'input'     // Text input field
-     * type: 'select'    // Dropdown selection
-     * type: 'checkbox'  // Boolean checkbox
-     * type: 'group'     // Field group container
+     * type: 'input'     // Text input field (registered)
+     * type: 'select'    // Dropdown selection (registered)
+     * type: 'checkbox'  // Boolean checkbox  (registered)
+     * type: 'group'     // Field group container (registered)
+     * type: 'my-custom' // Unregistered — still accepted, no autocomplete
      * ```
+     *
+     * Wrapper types are intentionally excluded — wrappers are configured through
+     * `wrappers` / `withFormWrappers()` rather than via the field-type discriminant.
      */
-    type: string;
+    type: RegisteredFieldTypes['type'] | (string & {});
     /**
      * Human-readable field label displayed to users.
      *
@@ -4083,6 +4266,21 @@ interface ArrayContext {
     /** The array field definition. */
     field: FieldDef<unknown>;
 }
+/**
+ * Group context for fields rendered inside `group` containers.
+ *
+ * Carries a reactive dot-separated chain of group ancestors (including the
+ * current group). Used by `mapFieldToInputs` to scope DOM IDs of group
+ * children, so the same leaf key can appear inside different groups without
+ * producing duplicate `id` attributes (issue #401).
+ *
+ * Re-provided by every group's child injector — a nested group reads its
+ * parent's context signal and composes its own path through `computed()`.
+ */
+interface GroupContext {
+    /** Dot-separated path of group ancestors, including the current group's key (e.g. `'address'` or `'user.address'`). */
+    groupPath: Signal<string>;
+}
 /**
  * Mapper function that converts a field definition to component inputs.
  *
@@ -4183,7 +4381,7 @@ interface FieldTypeDefinition<T extends FieldDef<any> = any> {
     /** Semantic scope for tooling to discover interchangeable field alternatives */
     scope?: FieldScope | FieldScope[];
     /** Mapped component inputs that must exist before the renderer instantiates the component */
-    renderReadyWhen?: RenderReadyInput[];
+    renderReadyWhen?: readonly RenderReadyInput[];
 }
 /**
  * Injection token for the global field type registry.
@@ -4212,6 +4410,15 @@ interface ResolvedField {
     injector: Injector;
     inputs: Signal<Record<string, unknown>>;
     renderReady: Signal<boolean>;
+    /**
+     * Whether the field is currently hidden. Sourced from the FieldTree's
+     * `state.hidden()` for value-bearing fields (set by Angular Signal Forms in
+     * response to `hidden(path, …)` calls), or from the mapper's explicit
+     * `hidden` input for non-value fields (button, text, container, …). Consumers
+     * must `@if (!field.hidden())` around `*dfFieldOutlet` so hidden fields are
+     * removed from the DOM — Angular Signal Forms warns (NG01916) otherwise.
+     */
+    hidden: Signal<boolean>;
 }
 
 /**
@@ -4782,6 +4989,26 @@ declare const FIELD_SIGNAL_CONTEXT: InjectionToken<FieldSignalContext<Record<str
  * ```
  */
 declare const ARRAY_CONTEXT: InjectionToken<ArrayContext>;
+/**
+ * Injection token for providing group ancestry to mappers and components.
+ *
+ * Re-provided in two places:
+ * 1. `GroupFieldComponent` provides a context whose `groupPath()` is the
+ *    parent path extended by its own key (e.g. `'address'` or `'user.address'`).
+ * 2. `createArrayItemInjector` provides a sentinel with an empty `groupPath`,
+ *    resetting the chain at array boundaries — descendants of an array item
+ *    that re-enter a group compose paths INSIDE the array item, matching the
+ *    property-derivation collector's keying.
+ *
+ * `mapFieldToInputs` reads this to scope DOM IDs and override-store keys so
+ * the same leaf key can appear in different groups without colliding (#401).
+ *
+ * Inject with `{ optional: true }` because top-level fields with no group
+ * ancestor (and no enclosing array) won't have the token provided. The token
+ * IS present for fields inside an array even when no inner group exists — the
+ * array-boundary sentinel makes injection succeed with an empty `groupPath`.
+ */
+declare const GROUP_CONTEXT: InjectionToken<GroupContext>;
 /**
  * Injection token for form-level default props.
  *
@@ -6284,8 +6511,6 @@ declare function applyMetaToElement(element: Element, meta: FieldMeta | undefine
  * );
  * // user.value() keeps the old user data during loading transitions
  * ```
- *
- * @experimental Uses Angular's experimental resource composition APIs.
  */
 declare function withPreviousValue<T>(input: Resource<T>): Resource<T>;
 
@@ -6336,6 +6561,7 @@ declare class GroupFieldComponent<TModel extends Record<string, unknown> = Recor
     private readonly destroyRef;
     private readonly fieldRegistry;
     private readonly parentFieldSignalContext;
+    private readonly parentGroupContext;
     private readonly injector;
     protected readonly environmentInjector: EnvironmentInjector;
     private readonly eventBus;
@@ -6365,6 +6591,13 @@ declare class GroupFieldComponent<TModel extends Record<string, unknown> = Recor
     readonly disabled: _angular_core.Signal<boolean>;
     private readonly nestedFieldTree;
     private readonly groupFieldSignalContext;
+    /**
+     * Group context propagated to descendants — carries the dot-separated path of
+     * group ancestors so child fields can scope their DOM IDs (issue #401).
+     * Reactive via `computed()`: a nested group composes its path from the parent
+     * context signal + its own key, so the chain stays consistent if either changes.
+     */
+    private readonly groupContext;
     private readonly groupInjector;
     readonly validityChange: _angular_core.OutputRef<boolean>;
     readonly dirtyChange: _angular_core.OutputRef<boolean>;
@@ -6396,6 +6629,12 @@ interface ResolvedArrayItemField {
     inputs: Signal<Record<string, unknown>>;
     /** Whether required mapped inputs are available for safe component instantiation. */
     renderReady: Signal<boolean>;
+    /**
+     * Whether the array-item field is currently hidden — mirrors `ResolvedField.hidden`
+     * so the same `@if (!field.hidden())` template gate works for top-level and
+     * array-item fields.
+     */
+    hidden: Signal<boolean>;
 }
 /**
  * Resolved array item ready for declarative rendering with ngComponentOutlet.
@@ -6426,7 +6665,9 @@ declare class ArrayFieldComponent<TModel extends Record<string, unknown> = Recor
     protected readonly environmentInjector: EnvironmentInjector;
     private readonly eventBus;
     private readonly logger;
-    private readonly templateRegistry;
+    private readonly arrayItemRegistry;
+    private readonly slot;
+    /** Bound id-generator reference threaded to `resolveArrayItem` so callsites stay terse. */
     private readonly generateItemId;
     field: _angular_core.InputSignal<ArrayField<readonly ArrayItemDefinition[]>>;
     key: _angular_core.InputSignal<string>;
@@ -6491,9 +6732,7 @@ declare class ArrayFieldComponent<TModel extends Record<string, unknown> = Recor
     private readonly itemTemplates;
     private readonly arrayFieldTrees;
     private readonly resolvedItemsSignal;
-    private readonly updateVersion;
-    private readonly pendingInitializationCycle;
-    private readonly settledInitializationCycle;
+    private readonly fsm;
     /**
      * Map of item IDs to their current positions. O(1) lookup vs O(n) indexOf().
      * Used by child linkedSignals to reactively track their position in the array.
@@ -6756,5 +6995,5 @@ declare class RootFormRegistryService {
  */
 declare const INITIALIZATION_TIMEOUT_MS: InjectionToken<number>;
 
-export { ARRAY_CONTEXT, AppendArrayItemEvent, ArrayFieldComponent, BUILT_IN_FIELDS, ConsoleLogger, ContainerFieldComponent, DEFAULT_PROPS, DEFAULT_VALIDATION_MESSAGES, DEFAULT_WRAPPERS, DynamicForm, DynamicFormError, DynamicFormLogger, DynamicTextPipe, EventBus, EventDispatcher, FIELD_REGISTRY, FIELD_SIGNAL_CONTEXT, FORM_OPTIONS, FormClearEvent, FormResetEvent, GroupFieldComponent, INITIALIZATION_TIMEOUT_MS, InsertArrayItemEvent, MoveArrayItemEvent, NextPageEvent, NoopLogger, PageChangeEvent, PopArrayItemEvent, PrependArrayItemEvent, PreviousPageEvent, RemoveAtIndexEvent, RootFormRegistryService, ShiftArrayItemEvent, SubmitEvent, WRAPPER_REGISTRY, applyMetaToElement, applyValidator, applyValidators, arrayEvent, arrayFieldMapper, baseFieldMapper, buildBaseInputs, containerFieldMapper, createField, createWrappers, dynamicTextToObservable, evaluateNonFieldDisabled, evaluateNonFieldHidden, field, formConfig, getArrayLength, groupFieldMapper, hasFormValue, interpolateParams, isArrayField, isCheckedField, isContainerField, isContainerTypedField, isDisplayOnlyField, isEqual, isFormStateCondition, isGroupField, isLeafField, isPageField, isRowField, isSimplifiedArrayField, isValueBearingField, isValueField, isWrapperTypeDefinition, isWrappersBundle, omit, pageFieldMapper, provideDynamicForm, resolveNextButtonDisabled, resolveNonFieldDisabled, resolveNonFieldHidden, resolveSubmitButtonDisabled, resolveTokens, rowFieldMapper, textFieldMapper, toReadonlyFieldTree, withEventFormValue, withLoggerConfig, withPreviousValue, withValidationExecutionDefaults, withValueExclusionDefaults, wrapperProps };
-export type { ArrayAllowedChildren, ArrayButtonConfig, ArrayContext, ArrayField, ArrayFieldTree, ArrayItemContext, ArrayItemDefinitionTemplate, ArrayItemTemplate, AsyncCondition, AsyncConditionFunction, AsyncCustomValidator, AsyncDerivationFunction, AsyncValidatorConfig, AvailableFieldTypes, BaseCheckedField, BaseValidatorConfig, BaseValueField, BuiltInValidatorConfig, ButtonLogicContext, CheckedFieldComponent, ConditionalExpression, ContainerAllowedChildren, ContainerField, ContainerFieldTypes, CssWrapper, CustomFnConfig, CustomValidator, CustomValidatorConfig, DeclarativeHttpValidatorConfig, DynamicFormFieldRegistry, DynamicText, EvaluationContext, ExtractField, ExtractFieldDefs, ExtractFormValue, FieldComponent, FieldDef, FieldMeta, FieldOption, FieldPathAccess, FieldRegistryContainers, FieldRegistryLeaves, FieldRegistryWrappers, FieldScope, FieldSignalContext, FieldStateContext, FieldStateInfo, FieldTypeDefinition, FieldWithValidation, FieldWrapper, FormConfig, FormEvent, FormEventConstructor, FormFieldStateMap, FormMode, FormModeDetectionResult, FormOptions, FormStateCondition, GroupAllowedChildren, GroupField, HttpCondition, HttpCustomValidator, HttpRequestConfig, HttpResourceRequest, HttpValidationResponseMapping, InferFormValue$1 as InferFormValue, InferWrapperRegistry, LeafFieldTypes, Logger, LogicConfig, MapperFn, NarrowField, NarrowFields, NextButtonOptions, NonFieldLogicConfig, NonFieldLogicContext, NonFieldLogicType, PageAllowedChildren, PageField, Prettify, ReadonlyFieldTree, RegisteredFieldTypes, ResolvedValidationExecutionConfig, ResolvedValueExclusionConfig, RowAllowedChildren, RowField, SchemaApplicationConfig, SchemaDefinition, SimplifiedArrayField, StateLogicConfig, SubmissionActionResult, SubmissionConfig, SubmitButtonOptions, TextElementType, TextField, TextProps, TokenContext, ValidationError, ValidationExecutionConfig, ValidationMessages, ValidatorConfig, ValueExclusionConfig, ValueFieldComponent, ValueHandlingMode, ValueType, WithInputSignals, WrapperConfig, WrapperFieldInputs, WrapperRegistration, WrapperTypeDefinition, WrappersBundle };
+export { ARRAY_CONTEXT, AppendArrayItemEvent, ArrayFieldComponent, BUILT_IN_FIELDS, ConsoleLogger, ContainerFieldComponent, DEFAULT_PROPS, DEFAULT_VALIDATION_MESSAGES, DEFAULT_WRAPPERS, DynamicForm, DynamicFormError, DynamicFormLogger, DynamicTextPipe, EventBus, EventDispatcher, FIELD_REGISTRY, FIELD_SIGNAL_CONTEXT, FORM_OPTIONS, FormClearEvent, FormResetEvent, GROUP_CONTEXT, GroupFieldComponent, INITIALIZATION_TIMEOUT_MS, InsertArrayItemEvent, MoveArrayItemEvent, NextPageEvent, NoopLogger, PageChangeEvent, PopArrayItemEvent, PrependArrayItemEvent, PreviousPageEvent, RemoveAtIndexEvent, RootFormRegistryService, ShiftArrayItemEvent, SubmitEvent, WRAPPER_REGISTRY, applyMetaToElement, applyValidator, applyValidators, arrayEvent, arrayFieldMapper, baseFieldMapper, buildBaseInputs, containerFieldMapper, createField, createWrappers, dynamicTextToObservable, evaluateNonFieldDisabled, evaluateNonFieldHidden, field, formConfig, getArrayLength, groupFieldMapper, hasFormValue, interpolateParams, isArrayField, isCheckedField, isContainerField, isContainerTypedField, isDisplayOnlyField, isEqual, isFormStateCondition, isGroupField, isLeafField, isPageField, isRowField, isSimplifiedArrayField, isValueBearingField, isValueField, isWrapperTypeDefinition, isWrappersBundle, omit, pageFieldMapper, provideDynamicForm, resolveNextButtonDisabled, resolveNonFieldDisabled, resolveNonFieldHidden, resolveSubmitButtonDisabled, resolveTokens, rowFieldMapper, textFieldMapper, toReadonlyFieldTree, withEventFormValue, withLoggerConfig, withPreviousValue, withValidationExecutionDefaults, withValueExclusionDefaults, wrapperProps };
+export type { ArrayAllowedChildren, ArrayButtonConfig, ArrayContext, ArrayField, ArrayFieldTree, ArrayItemContext, ArrayItemDefinitionTemplate, ArrayItemTemplate, AsyncCondition, AsyncConditionFunction, AsyncCustomValidator, AsyncDerivationFunction, AsyncValidatorConfig, AvailableFieldTypes, BaseCheckedField, BaseValidatorConfig, BaseValueField, BuiltInValidatorConfig, ButtonLogicContext, CheckedFieldComponent, ConditionalExpression, ContainerAllowedChildren, ContainerField, ContainerFieldTypes, CssWrapper, CustomFnConfig, CustomFunction, CustomValidator, CustomValidatorConfig, DeclarativeHttpValidatorConfig, DynamicFormFieldRegistry, DynamicText, EvaluationContext, ExtractField, ExtractFieldDefs, ExtractFormValue, FieldComponent, FieldDef, FieldMeta, FieldOption, FieldPathAccess, FieldRegistryContainers, FieldRegistryLeaves, FieldRegistryWrappers, FieldScope, FieldSignalContext, FieldStateContext, FieldStateInfo, FieldTypeDefinition, FieldWithValidation, FieldWrapper, FormConfig, FormEvent, FormEventConstructor, FormFieldStateMap, FormMode, FormModeDetectionResult, FormOptions, FormStateCondition, GroupAllowedChildren, GroupField, HttpCondition, HttpCustomValidator, HttpRequestConfig, HttpResourceRequest, HttpValidationResponseMapping, InferFormValue$1 as InferFormValue, InferWrapperRegistry, LeafFieldTypes, Logger, LogicConfig, MapperFn, NarrowField, NarrowFields, NextButtonOptions, NonFieldLogicConfig, NonFieldLogicContext, NonFieldLogicType, PageAllowedChildren, PageField, Prettify, ReadonlyFieldTree, RegisteredFieldTypes, ResolvedValidationExecutionConfig, ResolvedValueExclusionConfig, RowAllowedChildren, RowField, SchemaApplicationConfig, SchemaDefinition, SimplifiedArrayField, StateLogicConfig, SubmissionActionResult, SubmissionConfig, SubmitButtonOptions, TextElementType, TextField, TextProps, TokenContext, ValidationError, ValidationExecutionConfig, ValidationMessages, ValidatorConfig, ValueExclusionConfig, ValueFieldComponent, ValueHandlingMode, ValueType, WithInputSignals, WrapperConfig, WrapperFieldInputs, WrapperRegistration, WrapperTypeDefinition, WrappersBundle };