@ng-forge/dynamic-forms 0.5.2 → 0.6.0

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

@@ -251,6 +251,30 @@ interface FieldDef<TProps, TMeta extends FieldMeta = FieldMeta> {
      * ```
      */
     tabIndex?: number | undefined;
+    /**
+     * Whether to exclude this field's value from submission output when hidden.
+     *
+     * Overrides both the global `withValueExclusionDefaults()` and form-level `FormOptions` settings.
+     *
+     * @default undefined (uses form-level or global setting)
+     */
+    excludeValueIfHidden?: boolean;
+    /**
+     * Whether to exclude this field's value from submission output when disabled.
+     *
+     * Overrides both the global `withValueExclusionDefaults()` and form-level `FormOptions` settings.
+     *
+     * @default undefined (uses form-level or global setting)
+     */
+    excludeValueIfDisabled?: boolean;
+    /**
+     * Whether to exclude this field's value from submission output when readonly.
+     *
+     * Overrides both the global `withValueExclusionDefaults()` and form-level `FormOptions` settings.
+     *
+     * @default undefined (uses form-level or global setting)
+     */
+    excludeValueIfReadonly?: boolean;
     /**
      * Column sizing configuration for responsive grid layout.
      *
@@ -447,6 +471,249 @@ interface ResolvedField {
     inputs: Signal<Record<string, unknown>>;
 }
 
+/**
+ * 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 HttpRequestConfig {
+    /** URL to send the request to */
+    url: string;
+    /** HTTP method. Defaults to 'GET' */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /**
+     * 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'
+     * ```
+     */
+    params?: Record<string, string>;
+    /**
+     * Query parameters appended to the URL.
+     * Values are expressions evaluated by ExpressionParser against the current EvaluationContext.
+     */
+    queryParams?: Record<string, string>;
+    /** Request body (for POST/PUT/PATCH) */
+    body?: Record<string, unknown>;
+    /**
+     * 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).
+     */
+    evaluateBodyExpressions?: boolean;
+    /** HTTP headers to include in the request */
+    headers?: Record<string, string>;
+}
+
+/**
+ * Comparison operators for field value and form value conditions.
+ *
+ * @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.
+ *
+ * @public
+ */
+interface FieldValueCondition {
+    type: 'fieldValue';
+    /** Path to the field whose value to compare */
+    fieldPath: string;
+    /** Comparison operator */
+    operator: ComparisonOperator;
+    /** Value to compare against */
+    value?: unknown;
+}
+/**
+ * Condition that compares the entire form value against an expected value.
+ *
+ * @deprecated Use `FieldValueCondition` for specific field checks, or
+ * `JavascriptCondition` with an expression for complex form-level comparisons.
+ * Will be removed in a future minor version.
+ *
+ * @public
+ */
+interface FormValueCondition {
+    type: 'formValue';
+    /** Comparison operator */
+    operator: ComparisonOperator;
+    /** Value to compare against */
+    value?: unknown;
+}
+/**
+ * Condition that invokes a registered custom function by name (new API).
+ *
+ * Register functions via `customFnConfig.customFunctions`.
+ *
+ * @internal
+ */
+interface CustomConditionNew {
+    type: 'custom';
+    /** Name of the registered custom function to invoke */
+    functionName: string;
+}
+/**
+ * @deprecated Use `CustomCondition` with `functionName` instead.
+ * The `expression` field was misnamed — it holds a function registry key, not a JS expression.
+ * Will be removed in a future minor version.
+ *
+ * @internal
+ */
+interface CustomConditionDeprecated {
+    type: 'custom';
+    /**
+     * @deprecated Use `functionName` instead. Will be removed in a future minor version.
+     */
+    expression: string;
+}
+/**
+ * Condition that invokes a registered custom function by name.
+ *
+ * Use `functionName` (new API). The `expression` field is deprecated.
+ * Register functions via `customFnConfig.customFunctions`.
+ *
+ * @public
+ */
+type CustomCondition = CustomConditionNew | CustomConditionDeprecated;
+/**
+ * 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;
+    /**
+     * 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`
+     */
+    responseExpression?: string;
+    /**
+     * 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
+     */
+    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
+     */
+    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;
+    /**
+     * 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
+     */
+    pendingValue?: boolean;
+    /**
+     * Debounce ms for re-evaluation.
+     * @default 300
+     */
+    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 | FormValueCondition | 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';
+    /**
+     * Condition that determines when this container is hidden.
+     * Can be a boolean or a conditional expression evaluated against form values.
+     */
+    condition: ConditionalExpression | boolean;
+}
+
 /**
  * Row field interface for creating horizontal layouts
  * This is a special field type that contains other definitions arranged horizontally
@@ -467,6 +734,11 @@ interface RowField<TFields extends readonly RowAllowedChildren[] = readonly RowA
     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
@@ -491,6 +763,11 @@ interface GroupField<TFields extends readonly GroupAllowedChildren[] = readonly
     readonly label?: never;
     /** Groups do not support meta - they have no native form element **/
     readonly meta?: never;
+    /**
+     * Logic configurations for conditional group visibility.
+     * Only 'hidden' type logic is supported for groups.
+     */
+    readonly logic?: ContainerLogicConfig[];
 }
 /**
  * Type guard for GroupField with proper type narrowing
@@ -559,13 +836,13 @@ interface HiddenField<TValue extends HiddenValue = HiddenValue> extends FieldDef
  * 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;
+type PageAllowedChildren = LeafFieldTypes | RowField | GroupField | ArrayField | SimplifiedArrayField;
 /**
  * Fields that are allowed as children of Row fields
  * Rows can contain: groups, arrays, and leaf fields (but NOT pages, other rows, or hidden fields)
  * Hidden fields are excluded because rows are for horizontal layouts and hidden fields don't render
  */
-type RowAllowedChildren = Exclude<LeafFieldTypes, HiddenField> | GroupField | ArrayField;
+type RowAllowedChildren = Exclude<LeafFieldTypes, HiddenField> | GroupField | ArrayField | SimplifiedArrayField;
 /**
  * Fields that are allowed as children of Group fields
  * Groups can contain: rows and leaf fields (but NOT pages or other groups)
@@ -582,7 +859,7 @@ type ArrayAllowedChildren = LeafFieldTypes | RowField | GroupField;
  * 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$1 = readonly ArrayAllowedChildren[];
+type ArrayItemTemplate = readonly ArrayAllowedChildren[];
 /**
  * An array item definition can be either:
  * - A single field (ArrayAllowedChildren) for PRIMITIVE array items - extracts field value directly
@@ -593,7 +870,7 @@ type ArrayItemTemplate$1 = readonly ArrayAllowedChildren[];
  * - Object arrays: `[{ name: 'Alice', email: '...' }]`
  * - Heterogeneous arrays: `[{ value: 'x' }, 'y']` (mixed primitives and objects)
  */
-type ArrayItemDefinition = ArrayAllowedChildren | ArrayItemTemplate$1;
+type ArrayItemDefinition = ArrayAllowedChildren | ArrayItemTemplate;
 /**
  * Array field interface for creating dynamic field collections that map to array values.
  *
@@ -669,6 +946,21 @@ interface ArrayField<TFields extends readonly ArrayItemDefinition[] = readonly A
     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.
@@ -676,36 +968,103 @@ interface ArrayField<TFields extends readonly ArrayItemDefinition[] = readonly A
  * Fields can contain either single FieldDefs (primitive items) or arrays of FieldDefs (object items).
  */
 declare function isArrayField(field: FieldDef<any>): field is ArrayField;
-
-interface ConditionalExpression {
-    /** Expression type */
-    type: 'fieldValue' | 'formValue' | 'custom' | 'javascript' | 'and' | 'or';
-    /** Field path for fieldValue type */
-    fieldPath?: string;
-    /** Comparison operator */
-    operator?: 'equals' | 'notEquals' | 'greater' | 'less' | 'greaterOrEqual' | 'lessOrEqual' | 'contains' | 'startsWith' | 'endsWith' | 'matches';
-    /** Value to compare against */
-    value?: unknown;
-    /** JavaScript expression for custom logic */
-    expression?: string;
-    /** Array of sub-conditions for 'and' and 'or' types */
-    conditions?: ConditionalExpression[];
+/**
+ * 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>;
 }
-
 /**
- * Logic configuration for page fields.
- * Pages only support the 'hidden' logic type since they are layout containers,
- * not form controls (they can't be readonly, disabled, or required).
+ * 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 PageLogicConfig {
-    /** Only 'hidden' is supported for pages */
-    type: 'hidden';
+interface SimplifiedArrayField extends FieldDef<never> {
+    type: 'array';
     /**
-     * Condition that determines when this page is hidden.
-     * Can be a boolean or a conditional expression evaluated against form values.
+     * 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)
      */
-    condition: ConditionalExpression | boolean;
+    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;
+    /** Simplified arrays do not support meta */
+    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;
+    /** Mutually exclusive with `template` — use `fields` for the full API instead */
+    readonly fields?: never;
 }
+/**
+ * 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;
+
 /**
  * Page field interface for creating top-level page layouts
  * This is a special field type that contains other field definitions
@@ -749,7 +1108,7 @@ interface PageField<TFields extends readonly PageAllowedChildren[] = PageAllowed
      * }
      * ```
      */
-    readonly logic?: PageLogicConfig[];
+    readonly logic?: ContainerLogicConfig[];
 }
 /**
  * Type guard for PageField with proper type narrowing
@@ -916,19 +1275,52 @@ interface DebouncedStateLogicConfig extends BaseStateLogicConfig {
  */
 type StateLogicConfig = ImmediateStateLogicConfig | DebouncedStateLogicConfig;
 /**
- * Base configuration for value derivation logic.
- *
- * All derivations target the field they are defined on (self-targeting).
- * This simplifies configuration by removing the need for `targetField` -
- * derivation logic is placed on the field that should receive the computed value.
+ * Shared fields that appear on all derivation logic config variants.
  *
  * @internal
  */
-interface BaseDerivationLogicConfig {
+interface SharedDerivationFields {
     /**
      * Logic type identifier for value derivation.
      */
     type: 'derivation';
+    /**
+     * 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'
+     *   }]
+     * }
+     * ```
+     */
+    targetProperty?: string;
     /**
      * Optional name for this derivation for debugging purposes.
      *
@@ -976,74 +1368,199 @@ interface BaseDerivationLogicConfig {
      */
     condition?: ConditionalExpression | boolean;
     /**
-     * Static value to set on this field.
+     * When true, the derivation stops running after the user manually
+     * edits the target field.
      *
-     * Use when the derived value is a constant.
-     * Mutually exclusive with `expression` and `functionName`.
+     * 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
-     * value: '+1'           // String
-     * value: 100            // Number
-     * value: true           // Boolean
-     * value: { code: 'US' } // Object
+     * // 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
+     *   }]
+     * }
      * ```
      */
-    value?: unknown;
+    stopOnUserOverride?: boolean;
     /**
-     * JavaScript expression to evaluate for the derived value.
+     * 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.
      *
-     * 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.
-     * Mutually exclusive with `value` and `functionName`.
+     * 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
-     * expression: 'formValue.quantity * formValue.unitPrice'
-     * expression: 'formValue.firstName + " " + formValue.lastName'
-     * expression: 'formValue.price * (1 - formValue.discount / 100)'
+     * {
+     *   key: 'phonePrefix',
+     *   logic: [{
+     *     type: 'derivation',
+     *     value: '+1',
+     *     condition: { type: 'fieldValue', fieldPath: 'country', operator: 'equals', value: 'USA' },
+     *     stopOnUserOverride: true,
+     *     reEngageOnDependencyChange: true,
+     *     dependsOn: ['country']
+     *   }]
+     * }
      * ```
      */
-    expression?: string;
+    reEngageOnDependencyChange?: boolean;
+}
+/**
+ * Trigger variants for derivation timing.
+ * @internal
+ */
+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';
     /**
-     * Name of a registered custom derivation function.
+     * HTTP request configuration for server-driven derivations.
      *
-     * The function receives the evaluation context and returns the derived value.
-     * Register functions in `customFnConfig.derivations`.
-     * Mutually exclusive with `value` and `expression`.
+     * 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
-     * functionName: 'getCurrencyForCountry'
-     * functionName: 'calculateTax'
-     * functionName: 'formatPhoneNumber'
+     * {
+     *   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'],
+     *   }]
+     * }
      * ```
      */
-    functionName?: string;
+    http: HttpRequestConfig;
+    /**
+     * Explicit field dependencies. Required for HTTP derivations to prevent
+     * wildcard triggering on every keystroke.
+     */
+    dependsOn: string[];
     /**
-     * Explicit field dependencies for derivations.
+     * Expression to extract the derived value from the HTTP response.
      *
-     * When using `functionName`, you can optionally specify which fields
-     * the function depends on. This enables more efficient re-evaluation
-     * by only triggering when specific dependencies change.
+     * Evaluated via `ExpressionParser` with `{ response }` as the evaluation scope.
      *
-     * If not provided with `functionName`, defaults to all fields ('*').
-     * For `expression`, dependencies are automatically extracted from the expression.
-     * For `value`, no dependencies are needed (static value).
+     * @example
+     * ```typescript
+     * responseExpression: 'response.rate'
+     * responseExpression: 'response.data.suggestedPrice'
+     * ```
+     */
+    responseExpression: string;
+    value?: never;
+    expression?: never;
+    functionName?: never;
+    asyncFunctionName?: never;
+}
+/**
+ * Base for async function derivations. `source: 'asyncFunction'` is required.
+ * TypeScript enforces `dependsOn` at the type level.
+ *
+ * @internal
+ */
+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
-     * // Only re-evaluate when country changes
      * {
-     *   key: 'currency',
+     *   key: 'suggestedPrice',
      *   logic: [{
      *     type: 'derivation',
-     *     functionName: 'getCurrencyForCountry',
-     *     dependsOn: ['country']
+     *     source: 'asyncFunction',
+     *     asyncFunctionName: 'fetchSuggestedPrice',
+     *     dependsOn: ['productId', 'quantity'],
      *   }]
      * }
+     * ```
+     */
+    asyncFunctionName: string;
+    /**
+     * Explicit field dependencies. Required for async derivations to prevent
+     * wildcard triggering on every form change.
+     */
+    dependsOn: string[];
+    value?: never;
+    expression?: never;
+    functionName?: never;
+    http?: never;
+    responseExpression?: never;
+}
+/**
+ * Base for expression derivations.
+ *
+ * @internal
+ */
+interface ExpressionDerivationBase extends SharedDerivationFields {
+    source?: never;
+    /**
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * expression: 'formValue.quantity * formValue.unitPrice'
+     * expression: 'formValue.firstName + " " + formValue.lastName'
+     * expression: 'formValue.price * (1 - formValue.discount / 100)'
+     * ```
+     */
+    expression: string;
+    /**
+     * Explicit field dependencies for expressions.
+     *
+     * For `expression`, dependencies are automatically extracted from the expression.
+     * Provide `dependsOn` to override automatic detection for complex expressions.
+     *
+     * @example
+     * ```typescript
      * // Override automatic detection for complex expressions
      * {
      *   key: 'total',
@@ -1056,41 +1573,144 @@ interface BaseDerivationLogicConfig {
      * ```
      */
     dependsOn?: string[];
+    value?: never;
+    functionName?: never;
+    http?: never;
+    asyncFunctionName?: never;
+    responseExpression?: never;
 }
 /**
- * Derivation logic that evaluates immediately on change (default).
+ * Base for value derivations.
  *
  * @internal
  */
-interface OnChangeDerivationLogicConfig extends BaseDerivationLogicConfig {
+interface ValueDerivationBase extends SharedDerivationFields {
+    source?: never;
     /**
-     * Trigger for immediate evaluation.
-     * @default 'onChange'
+     * 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
+     * ```
      */
-    trigger?: 'onChange';
-    /** Not allowed for onChange trigger */
-    debounceMs?: never;
+    value: unknown;
+    /**
+     * Explicit field dependencies for value derivations.
+     *
+     * For `value` (static), no dependencies are needed.
+     * Provide `dependsOn` to conditionally re-evaluate when specific fields change.
+     */
+    dependsOn?: string[];
+    expression?: never;
+    functionName?: never;
+    http?: never;
+    asyncFunctionName?: never;
+    responseExpression?: never;
 }
 /**
- * Derivation logic that evaluates after a debounce period.
- *
- * Use this for self-transforms (lowercase, trim, format) to avoid
- * interrupting the user while they're actively typing.
+ * Base for custom sync function derivations.
  *
  * @internal
  */
-interface DebouncedDerivationLogicConfig extends BaseDerivationLogicConfig {
+interface FunctionDerivationBase extends SharedDerivationFields {
+    source?: never;
     /**
-     * Trigger for debounced evaluation.
-     * Evaluates after the value has stabilized for the debounce duration.
+     * 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: 'debounced';
+    functionName: string;
     /**
-     * Debounce duration in milliseconds.
-     * @default 500
+     * 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']
+     *   }]
+     * }
+     * ```
      */
-    debounceMs?: number;
+    dependsOn?: string[];
+    value?: never;
+    expression?: never;
+    http?: never;
+    asyncFunctionName?: never;
+    responseExpression?: never;
 }
+/**
+ * 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.
  *
@@ -1151,7 +1771,7 @@ interface DebouncedDerivationLogicConfig extends BaseDerivationLogicConfig {
  *
  * @public
  */
-type DerivationLogicConfig = OnChangeDerivationLogicConfig | DebouncedDerivationLogicConfig;
+type DerivationLogicConfig = OnChangeHttpDerivationLogicConfig | DebouncedHttpDerivationLogicConfig | OnChangeAsyncFunctionDerivationLogicConfig | DebouncedAsyncFunctionDerivationLogicConfig | OnChangeExpressionDerivationLogicConfig | DebouncedExpressionDerivationLogicConfig | OnChangeValueDerivationLogicConfig | DebouncedValueDerivationLogicConfig | OnChangeFunctionDerivationLogicConfig | DebouncedFunctionDerivationLogicConfig;
 /**
  * Base configuration for property derivation logic.
  *
@@ -1280,55 +1900,20 @@ interface DebouncedPropertyDerivationLogicConfig extends BasePropertyDerivationL
 /**
  * Configuration for property derivation logic.
  *
- * Enables reactive derivation of field properties (like `minDate`, `options`,
- * `label`, `placeholder`) based on form values and external data.
- *
- * Property derivations are self-targeting: the logic is placed on the field
- * whose property should be derived.
- *
- * @example
- * ```typescript
- * // Derive endDate's minDate from startDate value
- * {
- *   key: 'endDate',
- *   type: 'datepicker',
- *   logic: [{
- *     type: 'propertyDerivation',
- *     targetProperty: 'minDate',
- *     expression: 'formValue.startDate'
- *   }]
- * }
+ * @deprecated Use `DerivationLogicConfig` with `targetProperty` instead.
+ * The unified `type: 'derivation'` with `targetProperty` provides the same
+ * functionality with a simpler API surface.
  *
- * // Derive options from another field's value
- * {
- *   key: 'city',
- *   type: 'select',
- *   logic: [{
- *     type: 'propertyDerivation',
- *     targetProperty: 'options',
- *     functionName: 'getCitiesForCountry',
- *     dependsOn: ['country']
- *   }]
- * }
- *
- * // Derive label conditionally
- * {
- *   key: 'phone',
- *   type: 'input',
- *   logic: [{
- *     type: 'propertyDerivation',
- *     targetProperty: 'label',
- *     value: 'Mobile Phone',
- *     condition: {
- *       type: 'fieldValue',
- *       fieldPath: 'contactType',
- *       operator: 'equals',
- *       value: 'mobile'
- *     }
- *   }]
- * }
+ * ```typescript
+ * // Before (deprecated)
+ * { type: 'propertyDerivation', targetProperty: 'minDate', expression: '...' }
+ *
+ * // After (preferred)
+ * { type: 'derivation', targetProperty: 'minDate', expression: '...' }
  * ```
  *
+ * Will be removed in a future minor version.
+ *
  * @public
  */
 type PropertyDerivationLogicConfig = OnChangePropertyDerivationLogicConfig | DebouncedPropertyDerivationLogicConfig;
@@ -1364,6 +1949,9 @@ declare function isFormStateCondition(condition: StateLogicConfig['condition'] |
 /**
  * Type guard to check if a logic config is a PropertyDerivationLogicConfig.
  *
+ * @deprecated Use `isDerivationLogicConfig(config) && hasTargetProperty(config)` instead.
+ * Will be removed in a future minor version.
+ *
  * @param config - The logic config to check
  * @returns true if the config is for property derivation
  *
@@ -1516,78 +2104,59 @@ declare function resolveSubmitButtonDisabled(ctx: ButtonLogicContext): Signal<bo
  */
 declare function resolveNextButtonDisabled(ctx: ButtonLogicContext): Signal<boolean>;
 /**
- * Resolves the hidden state for non-form-bound elements (buttons, text fields, etc.).
+ * Evaluates the hidden state for non-form-bound elements synchronously.
  *
- * This is a generalized function that can be used by any field mapper (buttons, text fields,
- * or any non-form-bound elements) to evaluate hidden logic. It's particularly useful for
- * elements that don't have a FieldTree but still need conditional visibility.
+ * This is a pure function (no signal allocation) that can be called directly inside
+ * an existing `computed()` block without creating ephemeral signal allocations.
  *
  * The hidden state is determined by (in order of precedence):
  * 1. Explicit `hidden: true` on the field definition
  * 2. Field-level `logic` array with `type: 'hidden'` conditions
  *
  * @param ctx - The context containing form, logic array, and explicit hidden state
- * @returns A computed signal that returns true when the element should be hidden
+ * @returns true when the element should be hidden
  *
- * @example
- * ```typescript
- * // In an array button mapper
- * const hiddenSignal = resolveNonFieldHidden({
- *   form: rootFormRegistry.getRootForm()!,
- *   fieldLogic: buttonField.logic,
- *   explicitValue: buttonField.hidden,
- *   formValue: rootFormRegistry.getFormValue(),
- * });
+ * @public
+ */
+declare function evaluateNonFieldHidden(ctx: NonFieldLogicContext): boolean;
+/**
+ * Resolves the hidden state for non-form-bound elements as a reactive signal.
  *
- * return computed(() => ({
- *   ...baseInputs,
- *   hidden: hiddenSignal(),
- * }));
- * ```
+ * Wraps {@link evaluateNonFieldHidden} in a `computed()` for use cases where a standalone
+ * signal is needed. When calling from inside an existing `computed()`, prefer
+ * {@link evaluateNonFieldHidden} directly to avoid ephemeral signal allocation.
  *
- * @example
- * ```typescript
- * // In a text field mapper
- * const hiddenSignal = resolveNonFieldHidden({
- *   form: rootFormRegistry.getRootForm()!,
- *   fieldLogic: textField.logic,
- *   explicitValue: textField.hidden,
- *   formValue: rootFormRegistry.getFormValue(),
- * });
- * ```
+ * @param ctx - The context containing form, logic array, and explicit hidden state
+ * @returns A computed signal that returns true when the element should be hidden
  *
  * @public
  */
 declare function resolveNonFieldHidden(ctx: NonFieldLogicContext): Signal<boolean>;
 /**
- * Resolves the disabled state for non-form-bound elements (buttons, text fields, etc.).
+ * Evaluates the disabled state for non-form-bound elements synchronously.
  *
- * This is a generalized function that can be used by any field mapper to evaluate
- * disabled logic. It handles elements that don't have form-level disabled defaults
- * (unlike submit/next buttons which have form-level config).
+ * This is a pure function (no signal allocation) that can be called directly inside
+ * an existing `computed()` block without creating ephemeral signal allocations.
  *
  * The disabled state is determined by (in order of precedence):
  * 1. Explicit `disabled: true` on the field definition
  * 2. Field-level `logic` array with `type: 'disabled'` conditions
  *
  * @param ctx - The context containing form, logic array, and explicit disabled state
- * @returns A computed signal that returns true when the element should be disabled
+ * @returns true when the element should be disabled
  *
- * @example
- * ```typescript
- * // In an array button mapper
- * const disabledSignal = resolveNonFieldDisabled({
- *   form: rootFormRegistry.getRootForm()!,
- *   fieldLogic: buttonField.logic,
- *   explicitValue: buttonField.disabled,
- *   formValue: rootFormRegistry.getFormValue(),
- * });
+ * @public
+ */
+declare function evaluateNonFieldDisabled(ctx: NonFieldLogicContext): boolean;
+/**
+ * Resolves the disabled state for non-form-bound elements as a reactive signal.
  *
- * return computed(() => ({
- *   ...baseInputs,
- *   disabled: disabledSignal(),
- * }));
- * ```
+ * Wraps {@link evaluateNonFieldDisabled} in a `computed()` for use cases where a standalone
+ * signal is needed. When calling from inside an existing `computed()`, prefer
+ * {@link evaluateNonFieldDisabled} directly to avoid ephemeral signal allocation.
+ *
+ * @param ctx - The context containing form, logic array, and explicit disabled state
+ * @returns A computed signal that returns true when the element should be disabled
  *
  * @public
  */
@@ -1633,7 +2202,7 @@ interface FieldRegistryContainers {
     page: PageField;
     row: RowField;
     group: GroupField;
-    array: ArrayField;
+    array: ArrayField | SimplifiedArrayField;
 }
 /**
  * Leaf fields registry - augment this interface to add custom leaf fields
@@ -1748,18 +2317,28 @@ type UnionToIntersection<U> = (U extends U ? (k: U) => void : never) extends (k:
  */
 type Depth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
 /**
- * Widens literal types to their primitive equivalents.
+ * Widens literal types to their primitive equivalents, recursively for objects and arrays.
  * This prevents `as const` from over-narrowing types like `''` to literal `''` instead of `string`.
  *
+ * Depth-limited to prevent slow type checking on deeply nested `as const` objects.
+ * Falls back to `T` (unwidened) when depth is exhausted.
+ *
+ * Note: For object types, `readonly` modifiers are intentionally stripped (`-readonly`)
+ * so that inferred form value types have mutable properties. This is by design since
+ * `as const` adds `readonly` to all properties, but form values should be mutable.
+ *
  * @example
  * ```typescript
  * type A = Widen<''>; // string
  * type B = Widen<false>; // boolean
  * type C = Widen<42>; // number
  * type D = Widen<string[]>; // string[]
+ * type E = Widen<{ name: 'Jane' }>; // { name: string }
  * ```
  */
-type Widen<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
+type Widen<T, D extends number = 5> = [D] extends [never] ? T : T extends string ? string : T extends number ? number : T extends boolean ? boolean : T extends readonly (infer U)[] ? Widen<U, Depth[D]>[] : T extends Record<string, unknown> ? {
+    -readonly [K in keyof T]: Widen<T[K], Depth[D]>;
+} : T;
 /**
  * Infer value type based on field type and props.
  * - Slider fields: always number
@@ -1783,6 +2362,21 @@ type MaybeOptional<T, V> = T extends {
 } ? V : T extends {
     required: true;
 } ? V : V | undefined;
+/**
+ * Infers the value type for an array field.
+ * Handles three cases:
+ * 1. Simplified array with template + value → infer item type from value
+ * 2. Simplified array with template only → unknown[]
+ * 3. Full-API array with fields → infer from children
+ */
+type InferArrayValue<T, D extends number> = T extends {
+    template: unknown;
+    value: readonly (infer Item)[];
+} ? Widen<Item>[] : T extends {
+    template: unknown;
+} ? unknown[] : T extends {
+    fields: infer F;
+} ? F extends RegisteredFieldTypes[] ? InferFormValueWithDepth<F, Depth[D]>[] : unknown[] : unknown[];
 /**
  * Process a single field and determine its contribution to the form value type
  */
@@ -1800,11 +2394,8 @@ type ProcessField<T, D extends number = 5> = [D] extends [never] ? Record<string
 } : never : T extends {
     type: 'array';
     key: infer K;
-    fields: infer F;
-} ? K extends string ? F extends RegisteredFieldTypes[] ? {
-    [P in K]: InferFormValueWithDepth<F, Depth[D]>[];
-} : {
-    [P in K]: unknown[];
+} ? K extends string ? {
+    [P in K]: InferArrayValue<T, D>;
 } : never : T extends {
     type: 'text';
 } ? never : T extends {
@@ -1857,6 +2448,31 @@ 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 }`. Truthy = valid (no error).
+     *
+     * NOTE: This is the OPPOSITE of the function-based HttpCustomValidator.onSuccess
+     * convention, which maps successful HTTP responses to validation errors.
+     * Here, truthy means "validation passed".
+     */
+    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
  */
@@ -1908,34 +2524,80 @@ interface CustomValidatorConfig extends BaseValidatorConfig {
     errorParams?: Record<string, string>;
 }
 /**
- * Async custom validator configuration using Angular's validateAsync API
- * Returns Observable<ValidationError | ValidationError[] | null>
+ * Async custom validator configuration using Angular's validateAsync API.
+ * Returns Observable<ValidationError | ValidationError[] | null>.
+ *
+ * Accepts both `'async'` (preferred) and `'customAsync'` (deprecated) type literals.
  */
 interface AsyncValidatorConfig extends BaseValidatorConfig {
-    /** Validator type identifier */
-    type: 'customAsync';
+    /**
+     * Validator type identifier.
+     *
+     * Use `'async'` for new code. `'customAsync'` is accepted for backward compatibility
+     * but emits a deprecation warning in dev mode.
+     */
+    type: 'async' | 'customAsync';
     /** Name of registered async validator function */
     functionName: string;
     /** Optional parameters to pass to validator function */
     params?: Record<string, unknown>;
 }
 /**
- * HTTP validator configuration using Angular's validateHttp API
- * Provides optimized HTTP validation with automatic request cancellation
+ * Function-based HTTP validator configuration — requires a registered function.
+ *
+ * Uses Angular's `validateHttp` API. The function is registered via
+ * `customFnConfig.httpValidators`.
+ *
+ * Discriminated from `DeclarativeHttpValidatorConfig` by the presence of `functionName`.
+ *
+ * Accepts both `'http'` (preferred) and `'customHttp'` (deprecated) type literals.
+ *
+ * @deprecated Prefer `DeclarativeHttpValidatorConfig` (`type: 'http'` with `http` + `responseMapping`)
+ * for fully JSON-serializable validation. Use this form only when function registration is required.
  */
-interface HttpValidatorConfig extends BaseValidatorConfig {
-    /** Validator type identifier */
-    type: 'customHttp';
+interface FunctionHttpValidatorConfig extends BaseValidatorConfig {
+    /**
+     * Validator type identifier.
+     *
+     * Use `'http'` for new code. `'customHttp'` is accepted for backward compatibility
+     * but emits a deprecation warning in dev mode.
+     */
+    type: 'http' | 'customHttp';
     /** Name of registered HTTP validator configuration */
     functionName: string;
     /** Optional parameters to pass to HTTP validator */
     params?: Record<string, unknown>;
 }
 /**
- * Configuration for signal forms validator functions that can be serialized from API
- * Discriminated union type for type-safe validator configuration
+ * @deprecated Use `FunctionHttpValidatorConfig` instead. Will be removed in a future minor version.
+ */
+type HttpValidatorConfig = FunctionHttpValidatorConfig;
+/**
+ * Declarative HTTP validator configuration — fully JSON-serializable, no function registration required.
+ *
+ * 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 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.
+ *
+ * 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 | HttpValidatorConfig;
+type ValidatorConfig = BuiltInValidatorConfig | CustomValidatorConfig | AsyncValidatorConfig | FunctionHttpValidatorConfig | DeclarativeHttpValidatorConfig;
 
 /**
  * Configuration for applying predefined schemas
@@ -2231,6 +2893,76 @@ interface HttpCustomValidator<TValue = unknown, TResult = unknown> {
     readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError$1 | ValidationError$1[] | null;
 }
 
+/**
+ * Tracks deprecated API usages that have already been warned about to prevent log spam.
+ * Scoped to a single form instance via DI.
+ *
+ * This follows the same pattern as DerivationWarningTracker — DI-scoped rather than
+ * module-scoped to avoid SSR issues where state would be shared across requests.
+ *
+ * @public
+ */
+interface DeprecationWarningTracker {
+    /** Set of deprecation keys we've already warned about */
+    warnedKeys: Set<string>;
+}
+
+/**
+ * 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`).
+ *
+ * @public
+ */
+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;
+}
+/**
+ * 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>;
+/**
+ * Field state context for the current field being evaluated.
+ *
+ * Used as `fieldState` in evaluation contexts.
+ *
+ * @public
+ */
+type FieldStateContext = FieldStateInfo;
+
 interface EvaluationContext<TValue = unknown> {
     /** Current field value */
     fieldValue: TValue;
@@ -2302,6 +3034,43 @@ interface EvaluationContext<TValue = unknown> {
      * ```
      */
     externalData?: Record<string, unknown>;
+    /**
+     * DI-scoped tracker for deprecation warnings.
+     * Used by the condition evaluator to deduplicate deprecation warnings.
+     */
+    deprecationTracker?: DeprecationWarningTracker;
+    /**
+     * 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;
 }
@@ -2347,6 +3116,43 @@ interface EvaluationContext<TValue = unknown> {
  */
 type CustomFunction = (context: EvaluationContext) => 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
+ * ```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 = (context: EvaluationContext) => 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
+ * ```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 AsyncConditionFunction = (context: EvaluationContext) => Promise<boolean> | Observable<boolean>;
+
 /**
  * Re-export Angular's ValidationError for consistency
  * This replaces our custom ValidationError interface
@@ -2853,6 +3659,9 @@ interface CustomFnConfig {
      */
     derivations?: Record<string, CustomFunction>;
     /**
+     * @deprecated Register functions under `derivations` instead. Use `type: 'derivation'`
+     * with `targetProperty` in field logic configs. Will be removed in a future minor version.
+     *
      * Custom property derivation functions for reactive property updates.
      *
      * These functions compute derived values for field properties (like `minDate`,
@@ -2892,6 +3701,60 @@ interface CustomFnConfig {
      * ```
      */
     propertyDerivations?: Record<string, CustomFunction>;
+    /**
+     * Async derivation functions for asynchronous value derivation logic.
+     *
+     * These functions perform asynchronous operations (service calls, complex pipelines)
+     * and return the derived value via a Promise or Observable. They are called when a
+     * `DerivationLogicConfig` references them by `asyncFunctionName`.
+     *
+     * Async derivation functions:
+     * - Receive an `EvaluationContext` with access to `formValue`
+     * - Return a Promise or Observable of the value to set on the target field
+     * - Handle their own I/O (no HttpClient provided — use injected services)
+     * - Require explicit `dependsOn` to avoid triggering on every form change
+     *
+     * @example
+     * ```typescript
+     * asyncDerivations: {
+     *   fetchSuggestedPrice: async (context) => {
+     *     const response = await fetch(`/api/price?product=${context.formValue.productId}`);
+     *     const data = await response.json();
+     *     return data.suggestedPrice;
+     *   },
+     *   lookupAddress: (context) => {
+     *     return addressService.lookup(context.formValue.zipCode).pipe(
+     *       map(result => result.formattedAddress)
+     *     );
+     *   },
+     * }
+     * ```
+     */
+    asyncDerivations?: Record<string, AsyncDerivationFunction>;
+    /**
+     * Async condition functions for asynchronous field state logic.
+     *
+     * These functions perform asynchronous operations and return a boolean
+     * indicating whether the condition is met. They are referenced by
+     * `asyncFunctionName` in `AsyncCondition` expressions.
+     *
+     * Async condition functions:
+     * - Receive an `EvaluationContext` with access to `formValue`
+     * - Return a Promise or Observable of boolean
+     * - Handle their own I/O (use injected services)
+     *
+     * @example
+     * ```typescript
+     * asyncConditions: {
+     *   checkPermission: async (context) => {
+     *     const response = await fetch(`/api/permissions?role=${context.formValue.role}`);
+     *     const data = await response.json();
+     *     return data.canEdit;
+     *   },
+     * }
+     * ```
+     */
+    asyncConditions?: Record<string, AsyncConditionFunction>;
     /**
      * Custom validators using Angular's public FieldContext API
      *
@@ -3009,6 +3872,10 @@ interface CustomFnConfig {
      */
     asyncValidators?: Record<string, AsyncCustomValidator>;
     /**
+     * @deprecated Prefer declarative HTTP validators using `type: 'http'` with `http` + `responseMapping`
+     * in the validators array. Function-based HTTP validators now also use `type: 'http'` with `functionName`.
+     * Will be removed in a future minor version.
+     *
      * HTTP validators using Angular's validateHttp() API
      *
      * Angular's validateHttp provides HTTP validation with automatic request
@@ -3150,6 +4017,33 @@ interface FormOptions {
      * ```
      */
     nextButton?: NextButtonOptions;
+    /**
+     * Whether to exclude values of hidden fields from submission output.
+     *
+     * Overrides the global `withValueExclusionDefaults()` setting for this form.
+     * Can be further overridden per-field on individual `FieldDef` entries.
+     *
+     * @default undefined (uses global setting)
+     */
+    excludeValueIfHidden?: boolean;
+    /**
+     * Whether to exclude values of disabled fields from submission output.
+     *
+     * Overrides the global `withValueExclusionDefaults()` setting for this form.
+     * Can be further overridden per-field on individual `FieldDef` entries.
+     *
+     * @default undefined (uses global setting)
+     */
+    excludeValueIfDisabled?: boolean;
+    /**
+     * Whether to exclude values of readonly fields from submission output.
+     *
+     * Overrides the global `withValueExclusionDefaults()` setting for this form.
+     * Can be further overridden per-field on individual `FieldDef` entries.
+     *
+     * @default undefined (uses global setting)
+     */
+    excludeValueIfReadonly?: boolean;
     /**
      * Whether to attach the current form value to all events dispatched through the EventBus.
      *
@@ -3454,6 +4348,9 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
         maxDerivationIterations?: number;
         submitButton?: _ng_forge_dynamic_forms.SubmitButtonOptions;
         nextButton?: _ng_forge_dynamic_forms.NextButtonOptions;
+        excludeValueIfHidden?: boolean;
+        excludeValueIfDisabled?: boolean;
+        excludeValueIfReadonly?: boolean;
         emitFormValueOnEvents?: boolean;
     }>;
     /** Field signal context for injection into child components */
@@ -3860,6 +4757,100 @@ declare class NoopLogger implements Logger {
  */
 declare function withEventFormValue(): DynamicFormFeature<'event-form-value'>;
 
+/**
+ * Configuration for excluding field values from form submission output
+ * based on their reactive state (hidden, disabled, readonly).
+ *
+ * Supports a 3-tier configuration hierarchy: Field > Form > Global.
+ * The most specific level wins for each property.
+ *
+ * @public
+ */
+interface ValueExclusionConfig {
+    /**
+     * Whether to exclude the value of hidden fields from submission output.
+     *
+     * When `true`, fields whose `hidden()` state is `true` will have their
+     * values omitted from the submitted form value.
+     *
+     * @remarks
+     * This does NOT affect HiddenField (`type: 'hidden'`) — those fields
+     * store values without UI and their `hidden()` state is always `false`.
+     */
+    readonly excludeValueIfHidden?: boolean;
+    /**
+     * Whether to exclude the value of disabled fields from submission output.
+     *
+     * When `true`, fields whose `disabled()` state is `true` will have their
+     * values omitted from the submitted form value.
+     */
+    readonly excludeValueIfDisabled?: boolean;
+    /**
+     * Whether to exclude the value of readonly fields from submission output.
+     *
+     * When `true`, fields whose `readonly()` state is `true` will have their
+     * values omitted from the submitted form value.
+     */
+    readonly excludeValueIfReadonly?: boolean;
+}
+/**
+ * Fully resolved exclusion config with all properties required.
+ * Produced by the 3-tier resolution: `field ?? form ?? global`.
+ *
+ * @public
+ */
+type ResolvedValueExclusionConfig = Required<ValueExclusionConfig>;
+
+/**
+ * Configures global value exclusion defaults for form submission output.
+ *
+ * Value exclusion is **enabled by default** — field values are excluded from the
+ * `(submitted)` output based on their reactive state. Use this feature to
+ * override those defaults. This does NOT affect two-way binding (`value` model /
+ * `entity`) — fields retain their values internally.
+ *
+ * @example Default behavior (all exclusions enabled)
+ * ```typescript
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withValueExclusionDefaults()
+ * )
+ * ```
+ *
+ * @example Disable specific exclusions
+ * ```typescript
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withValueExclusionDefaults({ excludeValueIfReadonly: false })
+ * )
+ * ```
+ *
+ * @example Disable all exclusions (restore pre-v1 behavior)
+ * ```typescript
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withValueExclusionDefaults({
+ *     excludeValueIfHidden: false,
+ *     excludeValueIfDisabled: false,
+ *     excludeValueIfReadonly: false,
+ *   })
+ * )
+ * ```
+ *
+ * @remarks
+ * **Precedence rules:**
+ * 1. Per-field `excludeValueIf*` on `FieldDef` — wins for that field
+ * 2. Per-form `excludeValueIf*` on `FormOptions` — wins for all fields in that form
+ * 3. Global `withValueExclusionDefaults()` — baseline default
+ * 4. No global feature — uses token default (all enabled)
+ *
+ * @param config - Partial override of exclusion rules. Unspecified properties default to `true`.
+ * @returns A DynamicFormFeature that configures value exclusion defaults
+ *
+ * @public
+ */
+declare function withValueExclusionDefaults(config?: Partial<ValueExclusionConfig>): DynamicFormFeature<'value-exclusion'>;
+
 interface FieldOption<T = unknown> {
     label: DynamicText;
     value: T;
@@ -4060,7 +5051,7 @@ interface BaseValueField<TProps, TValue, TMeta extends FieldMeta = FieldMeta> ex
     required?: boolean;
 }
 declare function isValueField<TProps, TMeta extends FieldMeta = FieldMeta>(field: FieldDef<TProps, TMeta>): field is BaseValueField<TProps, ValueType, TMeta>;
-type ExcludedKeys$1 = 'type' | 'conditionals' | 'value' | 'valueType' | 'disabled' | 'readonly' | 'hidden' | 'col' | 'minValue' | 'maxValue' | 'step' | 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern' | 'validators' | 'logic' | 'derivation' | 'schemas';
+type ExcludedKeys$1 = 'type' | 'conditionals' | 'value' | 'valueType' | 'disabled' | 'readonly' | 'hidden' | 'col' | 'minValue' | 'maxValue' | 'step' | 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern' | 'validators' | 'logic' | 'derivation' | 'schemas' | 'excludeValueIfHidden' | 'excludeValueIfDisabled' | 'excludeValueIfReadonly';
 type ValueFieldComponent<T extends BaseValueField<Record<string, unknown> | unknown, unknown>> = Prettify<WithInputSignals<Omit<T, ExcludedKeys$1>>>;
 
 interface BaseCheckedField<TProps, TMeta extends FieldMeta = FieldMeta> extends FieldDef<TProps, TMeta>, FieldWithValidation {
@@ -4073,7 +5064,7 @@ interface BaseCheckedField<TProps, TMeta extends FieldMeta = FieldMeta> extends
     required?: boolean;
 }
 declare function isCheckedField<TProps, TMeta extends FieldMeta = FieldMeta>(field: FieldDef<TProps, TMeta>): field is BaseCheckedField<TProps, TMeta>;
-type ExcludedKeys = 'type' | 'conditionals' | 'value' | 'disabled' | 'readonly' | 'hidden' | 'col' | keyof FieldWithValidation;
+type ExcludedKeys = 'type' | 'conditionals' | 'value' | 'disabled' | 'readonly' | 'hidden' | 'col' | keyof FieldWithValidation | 'excludeValueIfHidden' | 'excludeValueIfDisabled' | 'excludeValueIfReadonly';
 type CheckedFieldComponent<T extends BaseCheckedField<Record<string, unknown> | unknown>> = Prettify<WithInputSignals<Omit<T, ExcludedKeys>>>;
 
 declare function applyValidator(config: ValidatorConfig, fieldPath: SchemaPath<any> | SchemaPathTree<any>): void;
@@ -4092,20 +5083,12 @@ declare class PreviousPageEvent implements FormEvent {
 }
 
 /**
- * Template type for OBJECT array items: array of field configurations.
- * Each field's value is merged into the item object.
- */
-type ArrayItemTemplate = ArrayAllowedChildren[];
-/**
- * Template type for array items that can be either:
- * - A single field (ArrayAllowedChildren) for PRIMITIVE items - extracts field value directly
- * - An array of fields (ArrayItemTemplate) for OBJECT items - merges fields into object
- *
- * Examples:
- * - Primitive: `{ key: 'tag', type: 'input', value: 'angular' }` → 'angular'
- * - Object: `[{ key: 'name', type: 'input' }, { key: 'email', type: 'input' }]` → { name: '', email: '' }
+ * Template type for array items used in events.
+ * Canonical definition lives in {@link ArrayItemDefinition} — this alias
+ * preserves the events-specific naming convention.
  */
-type ArrayItemDefinitionTemplate = ArrayAllowedChildren | ArrayItemTemplate;
+type ArrayItemDefinitionTemplate = ArrayItemDefinition;
+
 /**
  * Event dispatched to append a new item at the END of an array field.
  *
@@ -4759,6 +5742,8 @@ declare function baseFieldMapper(fieldDef: FieldDef<unknown>): Signal<Record<str
  * Row components are layout containers that don't change the form shape.
  * The row component will inject FIELD_SIGNAL_CONTEXT directly.
  *
+ * Supports hidden state resolution via `logic` array or static `hidden` property.
+ *
  * @param fieldDef The row field definition
  * @returns Signal containing Record of input names to values for ngComponentOutlet
  */
@@ -4771,6 +5756,8 @@ declare function rowFieldMapper(fieldDef: RowField): Signal<Record<string, unkno
  * The group component will inject the parent FIELD_SIGNAL_CONTEXT and create
  * a scoped child injector for its nested fields.
  *
+ * Supports hidden state resolution via `logic` array or static `hidden` property.
+ *
  * @param fieldDef The group field definition
  * @returns Signal containing Record of input names to values for ngComponentOutlet
  */
@@ -4783,6 +5770,8 @@ declare function groupFieldMapper(fieldDef: GroupField): Signal<Record<string, u
  * The array component will inject the parent FIELD_SIGNAL_CONTEXT and create
  * a scoped child injector for its array item fields.
  *
+ * Supports hidden state resolution via `logic` array or static `hidden` property.
+ *
  * @param fieldDef The array field definition
  * @returns Signal containing Record of input names to values for ngComponentOutlet
  */
@@ -4794,6 +5783,10 @@ declare function arrayFieldMapper(fieldDef: ArrayField): Signal<Record<string, u
  * Page fields are layout containers that don't modify the form context.
  * The page component will inject FIELD_SIGNAL_CONTEXT directly.
  *
+ * Note: Unlike other container mappers (group, row, array), the page mapper does NOT
+ * resolve hidden logic here. Page visibility is managed by the {@link PageOrchestratorComponent}
+ * which evaluates `ContainerLogicConfig` conditions and controls the `isVisible` input.
+ *
  * @param fieldDef The page field definition
  * @returns Signal containing Record of input names to values for ngComponentOutlet
  */
@@ -4906,6 +5899,7 @@ declare class RowFieldComponent {
     field: _angular_core.InputSignal<RowField<readonly _ng_forge_dynamic_forms.RowAllowedChildren[]>>;
     key: _angular_core.InputSignal<string>;
     className: _angular_core.InputSignal<string | undefined>;
+    hidden: _angular_core.InputSignal<boolean>;
     readonly hostClasses: _angular_core.Signal<string>;
     readonly disabled: _angular_core.Signal<boolean>;
     private readonly rawFieldRegistry;
@@ -4914,7 +5908,7 @@ declare class RowFieldComponent {
     constructor();
     private setupEffects;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<RowFieldComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<RowFieldComponent, "div[row-field]", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<RowFieldComponent, "div[row-field]", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "hidden": { "alias": "hidden"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**
@@ -4935,6 +5929,7 @@ declare class GroupFieldComponent<TModel extends Record<string, unknown> = Recor
     field: _angular_core.InputSignal<GroupField<readonly _ng_forge_dynamic_forms.GroupAllowedChildren[]>>;
     key: _angular_core.InputSignal<string>;
     className: _angular_core.InputSignal<string | undefined>;
+    hidden: _angular_core.InputSignal<boolean>;
     readonly hostClasses: _angular_core.Signal<string>;
     private readonly rawFieldRegistry;
     private readonly formSetup;
@@ -4964,7 +5959,7 @@ declare class GroupFieldComponent<TModel extends Record<string, unknown> = Recor
     constructor();
     private setupEffects;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<GroupFieldComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<GroupFieldComponent<any>, "fieldset[group-field]", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; }, { "validityChange": "validityChange"; "dirtyChange": "dirtyChange"; "submitted": "submitted"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<GroupFieldComponent<any>, "fieldset[group-field]", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "hidden": { "alias": "hidden"; "required": false; "isSignal": true; }; }, { "validityChange": "validityChange"; "dirtyChange": "dirtyChange"; "submitted": "submitted"; }, never, never, true, never>;
 }
 
 /**
@@ -5011,14 +6006,40 @@ declare class ArrayFieldComponent<TModel extends Record<string, unknown> = Recor
     field: _angular_core.InputSignal<ArrayField<readonly ArrayItemDefinition[]>>;
     key: _angular_core.InputSignal<string>;
     className: _angular_core.InputSignal<string | undefined>;
+    hidden: _angular_core.InputSignal<boolean>;
     readonly hostClasses: _angular_core.Signal<string>;
     private readonly rawFieldRegistry;
+    /**
+     * Gets the auto-remove button FieldDef from normalization metadata.
+     * Set by simplified array normalization for primitive arrays with remove buttons.
+     * The button is rendered alongside each item without wrapping in a row,
+     * preserving flat primitive form values.
+     */
+    private readonly autoRemoveButton;
+    /**
+     * For primitive array items, the key of the value field template (e.g., 'value').
+     * Used to wrap the FormControl in the item context so getFieldTree(key) works.
+     * Returns undefined for object arrays (FormGroup items have natural child navigation).
+     *
+     * Detection order:
+     * 1. Normalization metadata (for simplified arrays — always available at normalization time)
+     * 2. Existing item definitions (non-empty full-API arrays)
+     * 3. Dynamically discovered key from handleAddFromEvent (empty full-API arrays)
+     *
+     * Uses linkedSignal: recomputes when field() changes, supports manual set()
+     * for the dynamic discovery case.
+     */
+    private readonly primitiveFieldKey;
     /**
      * Gets the item templates (field definitions) for the array.
      * Each element can be either:
      * - A single FieldDef (primitive item) - normalized to [FieldDef]
      * - An array of FieldDefs (object item) - used as-is
      *
+     * When auto-remove is configured, the remove button is appended to each item's
+     * template list for rendering. This is purely visual — the form schema uses the
+     * original primitive item definition (single FieldDef → FormControl → flat value).
+     *
      * Returns normalized templates where all items are arrays for consistent handling.
      */
     private readonly itemTemplates;
@@ -5032,6 +6053,14 @@ declare class ArrayFieldComponent<TModel extends Record<string, unknown> = Recor
     private readonly itemPositionMap;
     /** Read-only view of resolved items for template consumption. */
     readonly resolvedItems: _angular_core.Signal<ResolvedArrayItem[]>;
+    /**
+     * Caches the result of appending the auto-remove button to template arrays.
+     * Keyed by template array reference — cache hits occur during recreate/resolution
+     * operations where stored template references are reused. Add operations via
+     * handleAddFromEvent always create a fresh `[...template]` copy (line ~277),
+     * so each add is a cache miss by design (the spread is needed for mutability).
+     */
+    private readonly autoRemoveCache;
     constructor();
     private setupEffects;
     private setupEventHandlers;
@@ -5056,6 +6085,18 @@ declare class ArrayFieldComponent<TModel extends Record<string, unknown> = Recor
      * 3. Return undefined (item cannot be resolved without a template)
      */
     private createResolveItemObservable;
+    /**
+     * Appends the auto-remove button to a templates array for rendering.
+     * The button is added for visual rendering only — it doesn't affect the form schema.
+     * Original templates are stored in templateRegistry WITHOUT the remove button,
+     * so this method is called during resolution to add it dynamically.
+     *
+     * Uses a WeakMap cache keyed by template array reference. Cache hits occur
+     * during recreate/resolution paths where stored templates are reused.
+     * Add operations always pass a fresh `[...template]` copy, so they miss
+     * the cache intentionally (the copy is needed for mutable item construction).
+     */
+    private withAutoRemove;
     /**
      * Handles remove operations from events (pop, shift, removeAt).
      * Updates resolvedItems FIRST, then form value - this ensures differential
@@ -5064,7 +6105,7 @@ declare class ArrayFieldComponent<TModel extends Record<string, unknown> = Recor
      */
     private removeItem;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ArrayFieldComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ArrayFieldComponent<any>, "array-field", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ArrayFieldComponent<any>, "array-field", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "hidden": { "alias": "hidden"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**
@@ -5150,5 +6191,5 @@ declare class RootFormRegistryService {
     constructor(formValue: Signal<Record<string, unknown>>, rootForm: Signal<FieldTree<Record<string, unknown>> | undefined>);
 }
 
-export { ARRAY_CONTEXT, AppendArrayItemEvent, ArrayFieldComponent, BUILT_IN_FIELDS, ConsoleLogger, DEFAULT_PROPS, DEFAULT_VALIDATION_MESSAGES, DynamicForm, DynamicFormError, DynamicFormLogger, DynamicTextPipe, EventBus, FIELD_REGISTRY, FIELD_SIGNAL_CONTEXT, FORM_OPTIONS, FormClearEvent, FormResetEvent, GroupFieldComponent, InsertArrayItemEvent, NextPageEvent, NoopLogger, PageChangeEvent, PopArrayItemEvent, PrependArrayItemEvent, PreviousPageEvent, RemoveAtIndexEvent, RootFormRegistryService, RowFieldComponent, ShiftArrayItemEvent, SubmitEvent, applyMetaToElement, applyValidator, applyValidators, arrayEvent, arrayFieldMapper, baseFieldMapper, buildBaseInputs, createField, dynamicTextToObservable, field, formConfig, getArrayLength, groupFieldMapper, hasFormValue, interpolateParams, isArrayField, isCheckedField, isContainerField, isDisplayOnlyField, isEqual, isFormStateCondition, isGroupField, isLeafField, isPageField, isPropertyDerivationLogicConfig, isRowField, isValueBearingField, isValueField, omit, pageFieldMapper, provideDynamicForm, resolveNextButtonDisabled, resolveNonFieldDisabled, resolveNonFieldHidden, resolveSubmitButtonDisabled, resolveTokens, rowFieldMapper, textFieldMapper, withEventFormValue, withLoggerConfig };
-export type { ArrayAllowedChildren, ArrayContext, ArrayField, ArrayFieldTree, ArrayItemContext, ArrayItemDefinitionTemplate, ArrayItemTemplate, AsyncCustomValidator, AsyncValidatorConfig, AvailableFieldTypes, BaseCheckedField, BaseValidatorConfig, BaseValueField, BuiltInValidatorConfig, ButtonLogicContext, CheckedFieldComponent, ConditionalExpression, ContainerFieldTypes, CustomFnConfig, CustomValidator, CustomValidatorConfig, DynamicFormFieldRegistry, DynamicText, EvaluationContext, ExtractField, ExtractFieldDefs, ExtractFormValue, FieldComponent, FieldDef, FieldMeta, FieldOption, FieldPathAccess, FieldRegistryContainers, FieldRegistryLeaves, FieldSignalContext, FieldTypeDefinition, FieldWithValidation, FormConfig, FormEvent, FormEventConstructor, FormMode, FormModeDetectionResult, FormOptions, FormStateCondition, GroupAllowedChildren, GroupField, HttpCustomValidator, HttpResourceRequest, HttpValidatorConfig, InferFormValue$1 as InferFormValue, LeafFieldTypes, Logger, LogicConfig, MapperFn, NarrowField, NarrowFields, NextButtonOptions, NonFieldLogicConfig, NonFieldLogicContext, NonFieldLogicType, PageAllowedChildren, PageField, Prettify, PropertyDerivationLogicConfig, RegisteredFieldTypes, RowAllowedChildren, RowField, SchemaApplicationConfig, SchemaDefinition, StateLogicConfig, SubmissionActionResult, SubmissionConfig, SubmitButtonOptions, TextElementType, TextField, TextProps, TokenContext, ValidationError, ValidationMessages, ValidatorConfig, ValueFieldComponent, ValueHandlingMode, ValueType, WithInputSignals };
+export { ARRAY_CONTEXT, AppendArrayItemEvent, ArrayFieldComponent, BUILT_IN_FIELDS, ConsoleLogger, DEFAULT_PROPS, DEFAULT_VALIDATION_MESSAGES, DynamicForm, DynamicFormError, DynamicFormLogger, DynamicTextPipe, EventBus, FIELD_REGISTRY, FIELD_SIGNAL_CONTEXT, FORM_OPTIONS, FormClearEvent, FormResetEvent, GroupFieldComponent, InsertArrayItemEvent, NextPageEvent, NoopLogger, PageChangeEvent, PopArrayItemEvent, PrependArrayItemEvent, PreviousPageEvent, RemoveAtIndexEvent, RootFormRegistryService, RowFieldComponent, ShiftArrayItemEvent, SubmitEvent, applyMetaToElement, applyValidator, applyValidators, arrayEvent, arrayFieldMapper, baseFieldMapper, buildBaseInputs, createField, dynamicTextToObservable, evaluateNonFieldDisabled, evaluateNonFieldHidden, field, formConfig, getArrayLength, groupFieldMapper, hasFormValue, interpolateParams, isArrayField, isCheckedField, isContainerField, isDisplayOnlyField, isEqual, isFormStateCondition, isGroupField, isLeafField, isPageField, isPropertyDerivationLogicConfig, isRowField, isSimplifiedArrayField, isValueBearingField, isValueField, omit, pageFieldMapper, provideDynamicForm, resolveNextButtonDisabled, resolveNonFieldDisabled, resolveNonFieldHidden, resolveSubmitButtonDisabled, resolveTokens, rowFieldMapper, textFieldMapper, withEventFormValue, withLoggerConfig, withValueExclusionDefaults };
+export type { ArrayAllowedChildren, ArrayButtonConfig, ArrayContext, ArrayField, ArrayFieldTree, ArrayItemContext, ArrayItemDefinitionTemplate, ArrayItemTemplate, AsyncCondition, AsyncConditionFunction, AsyncCustomValidator, AsyncDerivationFunction, AsyncValidatorConfig, AvailableFieldTypes, BaseCheckedField, BaseValidatorConfig, BaseValueField, BuiltInValidatorConfig, ButtonLogicContext, CheckedFieldComponent, ConditionalExpression, ContainerFieldTypes, CustomFnConfig, CustomValidator, CustomValidatorConfig, DeclarativeHttpValidatorConfig, DynamicFormFieldRegistry, DynamicText, EvaluationContext, ExtractField, ExtractFieldDefs, ExtractFormValue, FieldComponent, FieldDef, FieldMeta, FieldOption, FieldPathAccess, FieldRegistryContainers, FieldRegistryLeaves, FieldSignalContext, FieldStateContext, FieldStateInfo, FieldTypeDefinition, FieldWithValidation, FormConfig, FormEvent, FormEventConstructor, FormFieldStateMap, FormMode, FormModeDetectionResult, FormOptions, FormStateCondition, GroupAllowedChildren, GroupField, HttpCondition, HttpCustomValidator, HttpRequestConfig, HttpResourceRequest, HttpValidationResponseMapping, HttpValidatorConfig, InferFormValue$1 as InferFormValue, LeafFieldTypes, Logger, LogicConfig, MapperFn, NarrowField, NarrowFields, NextButtonOptions, NonFieldLogicConfig, NonFieldLogicContext, NonFieldLogicType, PageAllowedChildren, PageField, Prettify, PropertyDerivationLogicConfig, RegisteredFieldTypes, ResolvedValueExclusionConfig, RowAllowedChildren, RowField, SchemaApplicationConfig, SchemaDefinition, SimplifiedArrayField, StateLogicConfig, SubmissionActionResult, SubmissionConfig, SubmitButtonOptions, TextElementType, TextField, TextProps, TokenContext, ValidationError, ValidationMessages, ValidatorConfig, ValueExclusionConfig, ValueFieldComponent, ValueHandlingMode, ValueType, WithInputSignals };