@ng-forge/dynamic-forms 0.5.1 → 0.5.2

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

@@ -1,11 +1,11 @@
 import * as rxjs from 'rxjs';
 import { Observable } from 'rxjs';
+import * as _angular_core from '@angular/core';
+import { Signal, Injector, WritableSignal, InjectionToken, Type, ResourceRef, Provider, EnvironmentProviders, PipeTransform } from '@angular/core';
 import * as _angular_forms_signals from '@angular/forms/signals';
 import { FieldTree, FieldContext, ValidationError as ValidationError$1, TreeValidationResult, SchemaPath, SchemaPathTree } from '@angular/forms/signals';
 import * as _angular_forms from '@angular/forms';
 import * as _ng_forge_dynamic_forms from '@ng-forge/dynamic-forms';
-import * as _angular_core from '@angular/core';
-import { Signal, Injector, WritableSignal, InjectionToken, Type, ResourceRef, OnDestroy, InputSignal, Provider, EnvironmentProviders, PipeTransform } from '@angular/core';
 import { FormSchema } from '@ng-forge/dynamic-forms/schema';
 
 type WithInputSignals<T> = {
@@ -578,51 +578,91 @@ type GroupAllowedChildren = LeafFieldTypes | RowField;
  */
 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[];
+/**
+ * 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$1;
 /**
  * Array field interface for creating dynamic field collections that map to array values.
  *
  * Key concepts:
- * - The `fields` array defines the TEMPLATE (single field definition), not instances
- * - Array items are created/removed dynamically at runtime via event bus
- * - For primitive arrays: Use a leaf field as template → `['value1', 'value2']`
- * - For object arrays: Use a group field as template → `[{key1: val1}, {key2: val2}]`
+ * - 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 (flat values)
+ * // Primitive array: ['angular', 'typescript']
  * {
  *   key: 'tags',
  *   type: 'array',
- *   fields: [{ key: 'tag', type: 'input' }]
+ *   fields: [
+ *     { key: 'tag', type: 'input', value: 'angular' },      // Single field = primitive
+ *     { key: 'tag', type: 'input', value: 'typescript' },
+ *   ]
  * }
- * // Creates: { tags: ['tag1', 'tag2', 'tag3'] }
  *
  * @example
- * // Object array (nested groups)
+ * // Object array: [{ name: 'Alice', email: '...' }]
  * {
  *   key: 'contacts',
  *   type: 'array',
- *   fields: [{
- *     type: 'group',
- *     fields: [
- *       { key: 'name', type: 'input' },
- *       { key: 'email', type: 'input' }
- *     ]
- *   }]
+ *   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
  * }
- * // Creates: { contacts: [{name: '', email: ''}, {name: '', email: ''}] }
  *
  * 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 ArrayAllowedChildren[] = readonly ArrayAllowedChildren[]> extends FieldDef<never> {
+interface ArrayField<TFields extends readonly ArrayItemDefinition[] = readonly ArrayItemDefinition[]> extends FieldDef<never> {
     type: 'array';
     /**
-     * Template field definition(s) that will be cloned for each array item.
-     * Typically contains a single field definition:
-     * - For flat arrays: A leaf field (input, select, checkbox, etc.)
-     * - For object arrays: A group field containing multiple child fields
+     * 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 **/
@@ -631,7 +671,9 @@ interface ArrayField<TFields extends readonly ArrayAllowedChildren[] = readonly
     readonly meta?: never;
 }
 /**
- * Type guard for ArrayField with proper type narrowing
+ * 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;
 
@@ -1110,15 +1152,196 @@ interface DebouncedDerivationLogicConfig extends BaseDerivationLogicConfig {
  * @public
  */
 type DerivationLogicConfig = OnChangeDerivationLogicConfig | DebouncedDerivationLogicConfig;
+/**
+ * Base configuration for property derivation logic.
+ *
+ * Property derivations compute values for field properties (like `minDate`, `options`,
+ * `label`, `placeholder`) based on form values and external data. Unlike value derivations
+ * which set the field's value, property derivations update component input properties.
+ *
+ * All property derivations are self-targeting: the logic is placed on the field whose
+ * property should be derived.
+ *
+ * @internal
+ */
+interface BasePropertyDerivationLogicConfig {
+    /**
+     * Logic type identifier for property derivation.
+     */
+    type: 'propertyDerivation';
+    /**
+     * The target property to set on the field component.
+     *
+     * **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 a `DynamicFormError`
+     * at runtime. This is an architectural constraint of the override merging strategy.
+     *
+     * Supported formats:
+     * - Simple: `'minDate'`, `'options'`, `'label'`, `'placeholder'`
+     * - Nested (1 dot): `'props.appearance'`, `'meta.autocomplete'`
+     *
+     * **Note:** There is no compile-time validation that the property name matches
+     * an actual input on the field component. Typos will silently write to the
+     * override store with no visible effect. A dev-mode warning is emitted when
+     * the override key doesn't match any existing input property.
+     *
+     * @example
+     * ```typescript
+     * targetProperty: 'minDate'           // ✅ Simple property
+     * targetProperty: 'options'           // ✅ Simple property
+     * targetProperty: 'props.appearance'  // ✅ Single-nested property
+     * targetProperty: 'a.b.c'            // ❌ Throws DynamicFormError (too deep)
+     * ```
+     */
+    targetProperty: string;
+    /**
+     * Optional name for this derivation for debugging purposes.
+     *
+     * When provided, this name appears in property derivation debug logs.
+     */
+    debugName?: string;
+    /**
+     * Condition that determines when this property derivation applies.
+     *
+     * Defaults to `true` (always apply).
+     *
+     * Note: FormStateCondition is not supported for property derivations.
+     */
+    condition?: ConditionalExpression | boolean;
+    /**
+     * Static value to set on the target property.
+     *
+     * Mutually exclusive with `expression` and `functionName`.
+     */
+    value?: unknown;
+    /**
+     * JavaScript expression to evaluate for the derived property value.
+     *
+     * Has access to `formValue` object containing all form values.
+     * For array fields, `formValue` is scoped to the current array item.
+     *
+     * Mutually exclusive with `value` and `functionName`.
+     *
+     * @example
+     * ```typescript
+     * expression: 'formValue.startDate'
+     * expression: 'formValue.quantity > 10 ? "bulk" : "standard"'
+     * ```
+     */
+    expression?: string;
+    /**
+     * Name of a registered custom property derivation function.
+     *
+     * Register functions in `customFnConfig.propertyDerivations`.
+     * Mutually exclusive with `value` and `expression`.
+     */
+    functionName?: string;
+    /**
+     * Explicit field dependencies for property derivations.
+     *
+     * When using `functionName`, you can optionally specify which fields
+     * the function depends on. If not provided with `functionName`, defaults
+     * to all fields ('*').
+     * For `expression`, dependencies are automatically extracted.
+     * For `value`, no dependencies are needed (static value).
+     */
+    dependsOn?: string[];
+}
+/**
+ * Property derivation that evaluates immediately on change (default).
+ *
+ * @internal
+ */
+interface OnChangePropertyDerivationLogicConfig extends BasePropertyDerivationLogicConfig {
+    /**
+     * Trigger for immediate evaluation.
+     * @default 'onChange'
+     */
+    trigger?: 'onChange';
+    /** Not allowed for onChange trigger */
+    debounceMs?: never;
+}
+/**
+ * Property derivation that evaluates after a debounce period.
+ *
+ * @internal
+ */
+interface DebouncedPropertyDerivationLogicConfig extends BasePropertyDerivationLogicConfig {
+    /**
+     * Trigger for debounced evaluation.
+     */
+    trigger: 'debounced';
+    /**
+     * Debounce duration in milliseconds.
+     * @default 500
+     */
+    debounceMs?: number;
+}
+/**
+ * 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'
+ *   }]
+ * }
+ *
+ * // 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'
+ *     }
+ *   }]
+ * }
+ * ```
+ *
+ * @public
+ */
+type PropertyDerivationLogicConfig = OnChangePropertyDerivationLogicConfig | DebouncedPropertyDerivationLogicConfig;
 /**
  * Union type for all logic configurations.
  *
  * - `StateLogicConfig`: For field state changes (hidden, readonly, disabled, required)
  * - `DerivationLogicConfig`: For value derivation
+ * - `PropertyDerivationLogicConfig`: For property derivation
  *
  * @public
  */
-type LogicConfig = StateLogicConfig | DerivationLogicConfig;
+type LogicConfig = StateLogicConfig | DerivationLogicConfig | PropertyDerivationLogicConfig;
 /**
  * Log level for derivation debug output.
  *
@@ -1138,6 +1361,237 @@ type DerivationLogLevel = 'none' | 'summary' | 'verbose';
  * @public
  */
 declare function isFormStateCondition(condition: StateLogicConfig['condition'] | DerivationLogicConfig['condition']): condition is FormStateCondition;
+/**
+ * Type guard to check if a logic config is a PropertyDerivationLogicConfig.
+ *
+ * @param config - The logic config to check
+ * @returns true if the config is for property derivation
+ *
+ * @public
+ */
+declare function isPropertyDerivationLogicConfig(config: LogicConfig): config is PropertyDerivationLogicConfig;
+
+/**
+ * Interface for dynamic forms logger implementations.
+ * Allows custom logging integrations (Sentry, DataDog, etc.)
+ */
+interface Logger {
+    /**
+     * Log a debug message.
+     * Use for detailed diagnostic information during development.
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * Log an info message.
+     * Use for general operational information.
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Log a warning message.
+     * Use for potentially problematic situations that don't prevent operation.
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log an error message.
+     * Use for error conditions that may affect functionality.
+     */
+    error(message: string, ...args: unknown[]): void;
+}
+
+/**
+ * Context for resolving button disabled state.
+ *
+ * @public
+ */
+interface ButtonLogicContext {
+    /** The form's FieldTree instance (supports both string and number keys for array indices) */
+    form: FieldTree<unknown, string | number>;
+    /** Form-level options */
+    formOptions?: FormOptions;
+    /** Field-level logic array (if provided) */
+    fieldLogic?: LogicConfig[];
+    /** Explicit disabled state from field definition */
+    explicitlyDisabled?: boolean;
+    /** Current page validity signal (for paged forms) */
+    currentPageValid?: Signal<boolean>;
+    /** Current form value for evaluating conditional expressions */
+    formValue?: unknown;
+    /** Optional logger for diagnostic output. Falls back to no-op logger if not provided. */
+    logger?: Logger;
+}
+/**
+ * Allowed logic types for non-form-bound elements (buttons, text fields, etc.).
+ * These elements only support hidden and disabled states - not readonly or required
+ * since they don't participate in form validation.
+ *
+ * @public
+ */
+type NonFieldLogicType = 'hidden' | 'disabled';
+/**
+ * Logic config restricted to types valid for non-form-bound elements.
+ * This is a subset of LogicConfig that only includes hidden and disabled types.
+ *
+ * @public
+ */
+type NonFieldLogicConfig = LogicConfig & {
+    type: NonFieldLogicType;
+};
+/**
+ * Context for resolving state (hidden/disabled) for non-form-bound elements.
+ *
+ * This is a generalized context that can be used by any field mapper (buttons, text fields,
+ * or any non-form-bound elements) to evaluate logic from a `logic` array.
+ *
+ * Note: While this context accepts the full `LogicConfig[]` for flexibility, the resolver
+ * functions only process hidden and disabled types. Other logic types (readonly, required,
+ * derivation) are ignored for non-form-bound elements.
+ *
+ * @public
+ */
+interface NonFieldLogicContext {
+    /** The form's FieldTree instance (supports both string and number keys for array indices) */
+    form: FieldTree<unknown, string | number>;
+    /**
+     * Field-level logic array containing conditions.
+     * Accepts full LogicConfig[] for compatibility, but only hidden and disabled types are processed.
+     */
+    fieldLogic?: LogicConfig[];
+    /** Explicit state from field definition (e.g., `hidden: true` or `disabled: true`) */
+    explicitValue?: boolean;
+    /** Current form value for evaluating conditional expressions */
+    formValue?: unknown;
+    /** Optional logger for diagnostic output. Falls back to no-op logger if not provided. */
+    logger?: Logger;
+}
+/**
+ * Resolves the disabled state for a submit button.
+ *
+ * The disabled state is determined by (in order of precedence):
+ * 1. Explicit `disabled: true` on the field definition
+ * 2. Field-level `logic` array (if present, overrides form-level defaults)
+ * 3. Form-level `options.submitButton` defaults
+ *
+ * @param ctx - The button logic context
+ * @returns A computed signal that returns true when the button should be disabled
+ *
+ * @example
+ * ```typescript
+ * const disabled = resolveSubmitButtonDisabled({
+ *   form: formInstance,
+ *   formOptions: config.options,
+ *   fieldLogic: buttonField.logic,
+ *   explicitlyDisabled: buttonField.disabled,
+ * });
+ *
+ * // Use in template
+ * <button [disabled]="disabled()">Submit</button>
+ * ```
+ *
+ * @public
+ */
+declare function resolveSubmitButtonDisabled(ctx: ButtonLogicContext): Signal<boolean>;
+/**
+ * Resolves the disabled state for a next page button.
+ *
+ * The disabled state is determined by (in order of precedence):
+ * 1. Explicit `disabled: true` on the field definition
+ * 2. Field-level `logic` array (if present, overrides form-level defaults)
+ * 3. Form-level `options.nextButton` defaults
+ *
+ * @param ctx - The button logic context
+ * @returns A computed signal that returns true when the button should be disabled
+ *
+ * @example
+ * ```typescript
+ * const disabled = resolveNextButtonDisabled({
+ *   form: formInstance,
+ *   formOptions: config.options,
+ *   fieldLogic: buttonField.logic,
+ *   explicitlyDisabled: buttonField.disabled,
+ *   currentPageValid: pageOrchestrator.currentPageValid,
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function resolveNextButtonDisabled(ctx: ButtonLogicContext): Signal<boolean>;
+/**
+ * Resolves the hidden state for non-form-bound elements (buttons, text fields, etc.).
+ *
+ * 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.
+ *
+ * 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
+ *
+ * @example
+ * ```typescript
+ * // In an array button mapper
+ * const hiddenSignal = resolveNonFieldHidden({
+ *   form: rootFormRegistry.getRootForm()!,
+ *   fieldLogic: buttonField.logic,
+ *   explicitValue: buttonField.hidden,
+ *   formValue: rootFormRegistry.getFormValue(),
+ * });
+ *
+ * return computed(() => ({
+ *   ...baseInputs,
+ *   hidden: hiddenSignal(),
+ * }));
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In a text field mapper
+ * const hiddenSignal = resolveNonFieldHidden({
+ *   form: rootFormRegistry.getRootForm()!,
+ *   fieldLogic: textField.logic,
+ *   explicitValue: textField.hidden,
+ *   formValue: rootFormRegistry.getFormValue(),
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function resolveNonFieldHidden(ctx: NonFieldLogicContext): Signal<boolean>;
+/**
+ * Resolves the disabled state for non-form-bound elements (buttons, text fields, etc.).
+ *
+ * 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).
+ *
+ * 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
+ *
+ * @example
+ * ```typescript
+ * // In an array button mapper
+ * const disabledSignal = resolveNonFieldDisabled({
+ *   form: rootFormRegistry.getRootForm()!,
+ *   fieldLogic: buttonField.logic,
+ *   explicitValue: buttonField.disabled,
+ *   formValue: rootFormRegistry.getFormValue(),
+ * });
+ *
+ * return computed(() => ({
+ *   ...baseInputs,
+ *   disabled: disabledSignal(),
+ * }));
+ * ```
+ *
+ * @public
+ */
+declare function resolveNonFieldDisabled(ctx: NonFieldLogicContext): Signal<boolean>;
 
 /**
  * Text element type for rendering different HTML text elements
@@ -1155,8 +1609,12 @@ type TextProps = {
  */
 interface TextField extends FieldDef<TextProps> {
     type: 'text';
-    /** Logic rules for conditional visibility (hidden, readonly, disabled) */
-    readonly logic?: LogicConfig[];
+    /**
+     * Logic rules for conditional visibility.
+     * Text fields only support 'hidden' logic type since they are display-only
+     * and don't participate in form validation (no disabled/readonly/required).
+     */
+    readonly logic?: NonFieldLogicConfig[];
 }
 
 /**
@@ -1773,33 +2231,6 @@ interface HttpCustomValidator<TValue = unknown, TResult = unknown> {
     readonly onError?: (error: unknown, ctx: FieldContext<TValue>) => ValidationError$1 | ValidationError$1[] | null;
 }
 
-/**
- * Interface for dynamic forms logger implementations.
- * Allows custom logging integrations (Sentry, DataDog, etc.)
- */
-interface Logger {
-    /**
-     * Log a debug message.
-     * Use for detailed diagnostic information during development.
-     */
-    debug(message: string, ...args: unknown[]): void;
-    /**
-     * Log an info message.
-     * Use for general operational information.
-     */
-    info(message: string, ...args: unknown[]): void;
-    /**
-     * Log a warning message.
-     * Use for potentially problematic situations that don't prevent operation.
-     */
-    warn(message: string, ...args: unknown[]): void;
-    /**
-     * Log an error message.
-     * Use for error conditions that may affect functionality.
-     */
-    error(message: string, ...args: unknown[]): void;
-}
-
 interface EvaluationContext<TValue = unknown> {
     /** Current field value */
     fieldValue: TValue;
@@ -2421,6 +2852,46 @@ interface CustomFnConfig {
      * ```
      */
     derivations?: Record<string, CustomFunction>;
+    /**
+     * Custom property derivation functions for reactive property updates.
+     *
+     * These functions compute derived values for field properties (like `minDate`,
+     * `options`, `label`, `placeholder`) and are called when a
+     * `PropertyDerivationLogicConfig` references them by `functionName`.
+     *
+     * Property derivation functions:
+     * - Receive an `EvaluationContext` with access to `formValue`
+     * - Return the value to set on the target property
+     * - Are called reactively when dependencies change
+     *
+     * @example
+     * ```typescript
+     * propertyDerivations: {
+     *   getCitiesForCountry: (context) => {
+     *     const countryCities: Record<string, Array<{ label: string; value: string }>> = {
+     *       'USA': [{ label: 'New York', value: 'ny' }, { label: 'LA', value: 'la' }],
+     *       'Germany': [{ label: 'Berlin', value: 'berlin' }, { label: 'Munich', value: 'munich' }],
+     *     };
+     *     return countryCities[context.formValue.country as string] ?? [];
+     *   },
+     * }
+     * ```
+     *
+     * Field configuration using a property derivation function:
+     * ```typescript
+     * {
+     *   key: 'city',
+     *   type: 'select',
+     *   logic: [{
+     *     type: 'propertyDerivation',
+     *     targetProperty: 'options',
+     *     functionName: 'getCitiesForCountry',
+     *     dependsOn: ['country']
+     *   }]
+     * }
+     * ```
+     */
+    propertyDerivations?: Record<string, CustomFunction>;
     /**
      * Custom validators using Angular's public FieldContext API
      *
@@ -2767,146 +3238,14 @@ interface FormModeDetectionResult {
 }
 
 /**
- * Type guard to check if a field is a container field (page, row, group, or array)
- * Container fields have a 'fields' property and don't contribute values directly.
- * This overload works with RegisteredFieldTypes for full type narrowing.
- */
-declare function isContainerField(field: RegisteredFieldTypes): field is ContainerFieldTypes;
-/**
- * Type guard to check if a field is a container field (page, row, group, or array).
- * This overload works with any FieldDef for looser type checking.
- */
-declare function isContainerField(field: FieldDef<unknown>): boolean;
-/**
- * Type guard to check if a field is a leaf field (value or display field)
- * Leaf fields don't have children and either contribute values or display content
- */
-declare function isLeafField(field: RegisteredFieldTypes): field is LeafFieldTypes;
-/**
- * Type guard to check if a field has a value property (value-bearing field)
- * These fields contribute to the form value output
- * Note: Using `unknown` in the Extract condition to match any value type
- */
-declare function isValueBearingField(field: RegisteredFieldTypes): field is Extract<RegisteredFieldTypes, {
-    value: unknown;
-}>;
-/**
- * Type guard to check if a field is excluded from form values (display-only field)
- * Currently this includes text fields and any other fields without a value property
- */
-declare function isDisplayOnlyField(field: RegisteredFieldTypes): boolean;
-
-/**
- * Helper types for creating type-safe field configurations with proper nesting constraints
- */
-
-/**
- * Type helper for accessing nested field paths safely
- * This allows accessing child paths while maintaining some type safety
- */
-type FieldPathAccess<TValue> = {
-    [K in keyof TValue]: SchemaPath<TValue[K]> | SchemaPathTree<TValue[K]>;
-};
-
-/**
- * Result of processing all pending derivations.
- *
- * @public
- */
-interface DerivationProcessingResult {
-    /** Number of derivations successfully applied */
-    appliedCount: number;
-    /** Number of derivations skipped (condition not met or value unchanged) */
-    skippedCount: number;
-    /** Number of derivations that failed with errors */
-    errorCount: number;
-    /**
-     * Number of derivations that encountered warnings (e.g., missing target field).
-     *
-     * These are not counted as errors because they may be intentional (conditional fields)
-     * but indicate potential configuration issues if unexpected.
-     */
-    warnCount: number;
-    /** Total iterations performed */
-    iterations: number;
-    /** Whether max iterations was reached (potential loop) */
-    maxIterationsReached: boolean;
-}
-
-/**
- * Information about a single derivation evaluation for logging.
+ * Error from async field component loading.
  *
  * @public
  */
-interface DerivationLogEntry {
-    /** Debug name if provided in the derivation config */
-    debugName?: string;
-    /** Field key where the derivation is defined and targets */
-    fieldKey: string;
-    /** Result of the derivation evaluation */
-    result: 'applied' | 'skipped' | 'error';
-    /** Reason for skipping (if result is 'skipped') */
-    skipReason?: 'condition-false' | 'value-unchanged' | 'already-applied' | 'target-not-found';
-    /** The new value that was set (if result is 'applied') */
-    newValue?: unknown;
-    /** The previous value before the derivation (if result is 'applied') */
-    previousValue?: unknown;
-    /** Error message (if result is 'error') */
-    error?: string;
-    /** Duration in milliseconds (optional, for performance tracking) */
-    durationMs?: number;
-}
-
-/**
- * Service interface for derivation logging.
- *
- * Provides methods to log derivation processing events at different verbosity levels.
- * Use `DERIVATION_LOGGER` injection token to get an instance.
- *
- * @public
- */
-interface DerivationLogger {
-    /**
-     * Logs the start of a derivation processing cycle.
-     * Only logs when config level is 'verbose'.
-     */
-    cycleStart(trigger: 'onChange' | 'debounced', entryCount: number): void;
-    /**
-     * Logs the start of a derivation iteration within a cycle.
-     * Only logs when config level is 'verbose'.
-     */
-    iteration(iterationNumber: number): void;
-    /**
-     * Logs a single derivation evaluation result.
-     * Only logs when config level is 'verbose'.
-     */
-    evaluation(entry: DerivationLogEntry): void;
-    /**
-     * Logs a summary of derivation processing results.
-     * Logs when config level is 'summary' or 'verbose' and something interesting happened.
-     */
-    summary(result: DerivationProcessingResult, trigger: 'onChange' | 'debounced'): void;
-    /**
-     * Logs when max iterations are reached (always logged as warning).
-     */
-    maxIterationsReached(result: DerivationProcessingResult, trigger: 'onChange' | 'debounced'): void;
-}
-
-/**
- * Minimal configuration for creating a DerivationOrchestrator.
- * Only includes form-specific signals that cannot be injected.
- *
- * @internal
- */
-interface DerivationOrchestratorConfig {
-    /** Signal containing the flattened schema fields */
-    schemaFields: Signal<FieldDef<unknown>[] | undefined>;
-    /** Signal containing the current form value */
-    formValue: Signal<Record<string, unknown>>;
-    /** Signal containing the form accessor */
-    form: Signal<FieldTree<unknown>>;
-    /** Signal containing the derivation logger */
-    derivationLogger: Signal<DerivationLogger>;
+interface FieldLoadingError {
+    readonly fieldType: string;
+    readonly fieldKey: string;
+    readonly error: Error;
 }
 
 /**
@@ -3072,108 +3411,85 @@ declare class PageNavigationStateChangeEvent implements FormEvent {
 }
 
 /**
- * Dynamic form component that renders a complete form based on configuration.
- *
- * This is the main entry point for the dynamic form system. It handles form state management,
- * validation, field rendering, and event coordination using Angular's signal-based reactive forms.
- *
- * @typeParam TFields - Array of registered field types available for this form
- * @typeParam TModel - The strongly-typed interface for form values
+ * Dynamic form component — renders a form based on configuration.
+ * Delegates state management to `FormStateManager`.
  *
  * @example
  *```html
- * <form
- *  [dynamic-form]="formConfig"
- *  [(value)]="formData"
- *  (submitted)="handleSubmit($event)"
- *  (validityChange)="handleValidityChange($event)">
- * </form>
+ * <form [dynamic-form]="formConfig" [(value)]="formData" (submitted)="handleSubmit($event)"></form>
  * ```
  */
-declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFieldTypes[], TModel extends Record<string, unknown> = InferFormValue$1<TFields> & Record<string, unknown>> implements OnDestroy {
-    private readonly destroyRef;
-    private readonly fieldRegistry;
-    private readonly injector;
-    private readonly eventBus;
-    private readonly rootFormRegistry;
-    private readonly functionRegistry;
-    private readonly schemaRegistry;
-    private readonly logger;
-    private readonly derivationLogConfig;
+declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFieldTypes[], TModel extends Record<string, unknown> = InferFormValue$1<TFields> & Record<string, unknown>> {
     /** Form configuration defining the structure, validation, and behavior. */
-    config: InputSignal<FormConfig<TFields>>;
+    config: _angular_core.InputSignal<FormConfig<TFields, InferFormValue$1<TFields extends readonly RegisteredFieldTypes[] ? TFields : RegisteredFieldTypes[]>, Record<string, unknown>, unknown>>;
     /** Runtime form options that override config options when provided. */
-    formOptions: InputSignal<FormOptions | undefined>;
+    formOptions: _angular_core.InputSignal<FormOptions | undefined>;
     /** Form values for two-way data binding. */
     value: _angular_core.ModelSignal<Partial<TModel> | undefined>;
-    private readonly memoizedFlattenFields;
-    private readonly memoizedFlattenFieldsForRendering;
-    private readonly memoizedKeyBy;
-    private readonly memoizedDefaultValues;
-    private readonly rawFieldRegistry;
-    readonly formModeDetection: Signal<FormModeDetectionResult>;
-    private readonly formSetup;
-    readonly pageFieldDefinitions: Signal<PageField<_ng_forge_dynamic_forms.PageAllowedChildren[]>[]>;
-    readonly effectiveFormOptions: Signal<{
+    private destroyRef;
+    private injector;
+    private eventBus;
+    private logger;
+    /**
+     * Connect input signals to the shared deps holder BEFORE injecting FormStateManager.
+     * Field initializers run in declaration order, so this runs after inputs are created
+     * but before stateManager is injected. FormStateManager reads from these signals
+     * in computeds/effects, which are all lazy and evaluated after construction.
+     */
+    private readonly _connectStateDeps;
+    /** State manager that owns all form state. */
+    private stateManager;
+    private componentId;
+    /** The currently active config used for form rendering */
+    activeConfig: Signal<FormConfig<TFields, InferFormValue$1<TFields extends readonly RegisteredFieldTypes[] ? TFields : RegisteredFieldTypes[]>, Record<string, unknown>, unknown> | undefined>;
+    /** Current render phase: 'render' = showing form, 'teardown' = hiding old components */
+    renderPhase: Signal<"teardown" | "render">;
+    /** Computed form mode detection with validation */
+    formModeDetection: Signal<_ng_forge_dynamic_forms.FormModeDetectionResult>;
+    /** Page field definitions for paged forms */
+    pageFieldDefinitions: Signal<_ng_forge_dynamic_forms.PageField<_ng_forge_dynamic_forms.PageAllowedChildren[]>[]>;
+    /** Effective form options (merged from config and input) */
+    effectiveFormOptions: Signal<{
         disabled?: boolean;
         maxDerivationIterations?: number;
         submitButton?: _ng_forge_dynamic_forms.SubmitButtonOptions;
         nextButton?: _ng_forge_dynamic_forms.NextButtonOptions;
         emitFormValueOnEvents?: boolean;
     }>;
-    /**
-     * Computed derivation logger based on injected config.
-     *
-     * Uses factory pattern to return no-op logger when logging is disabled,
-     * avoiding any logging overhead in production.
-     */
-    private readonly derivationLogger;
-    readonly fieldSignalContext: Signal<FieldSignalContext<TModel>>;
-    /**
-     * Injector for field components with FIELD_SIGNAL_CONTEXT.
-     * Other form-level tokens (DEFAULT_PROPS, etc.) are provided at component level.
-     */
-    private readonly fieldInjector;
-    readonly defaultValues: _angular_core.WritableSignal<TModel>;
-    private readonly entity;
-    readonly form: Signal<FieldTree<TModel, string | number>>;
-    private readonly componentId;
-    private readonly totalComponentsCount;
-    private readonly fieldsSource;
-    /** Collects errors from async field component loading for error boundary patterns. */
-    readonly fieldLoadingErrors: _angular_core.WritableSignal<{
-        fieldType: string;
-        fieldKey: string;
-        error: Error;
-    }[]>;
-    /** Current form values (reactive). */
-    readonly formValue: Signal<TModel | (TModel extends infer T ? T extends TModel ? T extends _angular_forms.AbstractControl<unknown, infer TValue extends unknown, any> ? TValue : never : never : never)>;
-    /** Whether the form is currently valid. */
-    readonly valid: Signal<boolean>;
-    /** Whether the form is currently invalid. */
-    readonly invalid: Signal<boolean>;
-    /** Whether any form field has been modified. */
-    readonly dirty: Signal<boolean>;
-    /** Whether any form field has been touched (blurred). */
-    readonly touched: Signal<boolean>;
-    /** Current validation errors from all fields. */
-    readonly errors: Signal<_angular_forms_signals.ValidationError.WithField[]>;
-    /** Whether the form is disabled (from options or form state). */
-    readonly disabled: Signal<boolean>;
-    /** Whether the form is currently submitting. */
-    readonly submitting: Signal<boolean>;
-    /**
-     * Configuration for the derivation orchestrator.
-     * Bundles the form-specific signals needed by the orchestrator.
-     *
-     * @internal Used by DERIVATION_ORCHESTRATOR provider.
-     */
-    readonly derivationOrchestratorConfig: DerivationOrchestratorConfig;
-    readonly initialized$: rxjs.Observable<boolean>;
+    /** Field signal context for injection into child components */
+    fieldSignalContext: Signal<_ng_forge_dynamic_forms.FieldSignalContext<TModel>>;
+    /** Default values computed from field definitions */
+    defaultValues: WritableSignal<TModel>;
+    /** The Angular Signal Form instance */
+    form: Signal<FieldTree<TModel, string | number>>;
+    /** Current form values (reactive) */
+    formValue: Signal<TModel | (TModel extends infer T ? T extends TModel ? T extends _angular_forms.AbstractControl<unknown, infer TValue extends unknown, any> ? TValue : never : never : never)>;
+    /** Whether the form is currently valid */
+    valid: Signal<boolean>;
+    /** Whether the form is currently invalid */
+    invalid: Signal<boolean>;
+    /** Whether any form field has been modified */
+    dirty: Signal<boolean>;
+    /** Whether any form field has been touched (blurred) */
+    touched: Signal<boolean>;
+    /** Current validation errors from all fields */
+    errors: Signal<_angular_forms_signals.ValidationError.WithField[]>;
+    /** Whether the form is disabled (from options or form state) */
+    disabled: Signal<boolean>;
+    /** Whether the form is currently submitting */
+    submitting: Signal<boolean>;
+    /** Collects errors from async field component loading for error boundary patterns */
+    fieldLoadingErrors: WritableSignal<FieldLoadingError[]>;
+    /** Whether to render the form template */
+    shouldRender: Signal<boolean>;
+    /** Resolved fields ready for rendering */
+    protected resolvedFields: Signal<ResolvedField[]>;
+    private totalComponentsCount;
+    initialized$: rxjs.Observable<boolean>;
     /** Emits when form validity changes. */
-    readonly validityChange: _angular_core.OutputRef<boolean>;
+    validityChange: _angular_core.OutputRef<boolean>;
     /** Emits when form dirty state changes. */
-    readonly dirtyChange: _angular_core.OutputRef<boolean>;
+    dirtyChange: _angular_core.OutputRef<boolean>;
     /**
      * Emits form values when submitted (via SubmitEvent) and form is valid.
      *
@@ -3183,23 +3499,22 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
      *
      * Note: Does not emit when `submission.action` is configured - use one or the other.
      */
-    readonly submitted: _angular_core.OutputRef<TModel>;
+    submitted: _angular_core.OutputRef<Partial<TModel>>;
     /** Emits when form is reset to default values. */
-    readonly reset: _angular_core.OutputRef<FormResetEvent>;
+    reset: _angular_core.OutputRef<FormResetEvent>;
     /** Emits when form is cleared to empty state. */
-    readonly cleared: _angular_core.OutputRef<FormClearEvent>;
+    cleared: _angular_core.OutputRef<FormClearEvent>;
     /** Emits all form events for custom event handling. */
-    readonly events: _angular_core.OutputRef<_ng_forge_dynamic_forms.FormEvent>;
+    events: _angular_core.OutputRef<_ng_forge_dynamic_forms.FormEvent>;
     /**
      * Emits when all form components are initialized and ready for interaction.
      * Useful for E2E testing to ensure the form is fully rendered before interaction.
      */
-    readonly initialized: _angular_core.OutputRef<boolean>;
+    initialized: _angular_core.OutputRef<boolean>;
     /** Emits when the current page changes in paged forms. */
-    readonly onPageChange: _angular_core.OutputRef<PageChangeEvent>;
+    onPageChange: _angular_core.OutputRef<PageChangeEvent>;
     /** Emits when page navigation state changes (canGoNext, canGoPrevious, etc.). */
-    readonly onPageNavigationStateChange: _angular_core.OutputRef<PageNavigationStateChangeEvent>;
-    protected readonly resolvedFields: Signal<ResolvedField[]>;
+    onPageNavigationStateChange: _angular_core.OutputRef<PageNavigationStateChangeEvent>;
     constructor();
     /**
      * Handles native form submission triggered by:
@@ -3215,12 +3530,6 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
     protected onNativeSubmit(event: Event): void;
     private setupEffects;
     private setupEventHandlers;
-    private registerValidatorsFromConfig;
-    private createFormSetupFromConfig;
-    private createEmptyFormSetup;
-    private onFormReset;
-    private onFormClear;
-    ngOnDestroy(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DynamicForm<any, any>, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<DynamicForm<any, any>, "form[dynamic-form]", never, { "config": { "alias": "dynamic-form"; "required": true; "isSignal": true; }; "formOptions": { "alias": "formOptions"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "validityChange": "validityChange"; "dirtyChange": "dirtyChange"; "submitted": "submitted"; "reset": "reset"; "cleared": "cleared"; "events": "events"; "initialized": "initialized"; "onPageChange": "onPageChange"; "onPageNavigationStateChange": "onPageNavigationStateChange"; }, never, never, true, never>;
 }
@@ -3239,6 +3548,48 @@ interface DynamicFormFeature<TKind extends string = string> {
     ɵproviders: Provider[];
 }
 
+/**
+ * Type guard to check if a field is a container field (page, row, group, or array)
+ * Container fields have a 'fields' property and don't contribute values directly.
+ * This overload works with RegisteredFieldTypes for full type narrowing.
+ */
+declare function isContainerField(field: RegisteredFieldTypes): field is ContainerFieldTypes;
+/**
+ * Type guard to check if a field is a container field (page, row, group, or array).
+ * This overload works with any FieldDef for looser type checking.
+ */
+declare function isContainerField(field: FieldDef<unknown>): boolean;
+/**
+ * Type guard to check if a field is a leaf field (value or display field)
+ * Leaf fields don't have children and either contribute values or display content
+ */
+declare function isLeafField(field: RegisteredFieldTypes): field is LeafFieldTypes;
+/**
+ * Type guard to check if a field has a value property (value-bearing field)
+ * These fields contribute to the form value output
+ * Note: Using `unknown` in the Extract condition to match any value type
+ */
+declare function isValueBearingField(field: RegisteredFieldTypes): field is Extract<RegisteredFieldTypes, {
+    value: unknown;
+}>;
+/**
+ * Type guard to check if a field is excluded from form values (display-only field)
+ * Currently this includes text fields and any other fields without a value property
+ */
+declare function isDisplayOnlyField(field: RegisteredFieldTypes): boolean;
+
+/**
+ * Helper types for creating type-safe field configurations with proper nesting constraints
+ */
+
+/**
+ * Type helper for accessing nested field paths safely
+ * This allows accessing child paths while maintaining some type safety
+ */
+type FieldPathAccess<TValue> = {
+    [K in keyof TValue]: SchemaPath<TValue[K]> | SchemaPathTree<TValue[K]>;
+};
+
 /**
  * Extract FieldDef type from FieldTypeDefinition
  */
@@ -3643,80 +3994,6 @@ declare const DEFAULT_VALIDATION_MESSAGES: InjectionToken<Signal<ValidationMessa
  */
 declare const FORM_OPTIONS: InjectionToken<Signal<FormOptions | undefined>>;
 
-/**
- * Context for resolving button disabled state.
- *
- * @public
- */
-interface ButtonLogicContext {
-    /** The form's FieldTree instance (supports both string and number keys for array indices) */
-    form: FieldTree<unknown, string | number>;
-    /** Form-level options */
-    formOptions?: FormOptions;
-    /** Field-level logic array (if provided) */
-    fieldLogic?: LogicConfig[];
-    /** Explicit disabled state from field definition */
-    explicitlyDisabled?: boolean;
-    /** Current page validity signal (for paged forms) */
-    currentPageValid?: Signal<boolean>;
-    /** Current form value for evaluating conditional expressions */
-    formValue?: unknown;
-    /** Optional logger for diagnostic output. Falls back to no-op logger if not provided. */
-    logger?: Logger;
-}
-/**
- * Resolves the disabled state for a submit button.
- *
- * The disabled state is determined by (in order of precedence):
- * 1. Explicit `disabled: true` on the field definition
- * 2. Field-level `logic` array (if present, overrides form-level defaults)
- * 3. Form-level `options.submitButton` defaults
- *
- * @param ctx - The button logic context
- * @returns A computed signal that returns true when the button should be disabled
- *
- * @example
- * ```typescript
- * const disabled = resolveSubmitButtonDisabled({
- *   form: formInstance,
- *   formOptions: config.options,
- *   fieldLogic: buttonField.logic,
- *   explicitlyDisabled: buttonField.disabled,
- * });
- *
- * // Use in template
- * <button [disabled]="disabled()">Submit</button>
- * ```
- *
- * @public
- */
-declare function resolveSubmitButtonDisabled(ctx: ButtonLogicContext): Signal<boolean>;
-/**
- * Resolves the disabled state for a next page button.
- *
- * The disabled state is determined by (in order of precedence):
- * 1. Explicit `disabled: true` on the field definition
- * 2. Field-level `logic` array (if present, overrides form-level defaults)
- * 3. Form-level `options.nextButton` defaults
- *
- * @param ctx - The button logic context
- * @returns A computed signal that returns true when the button should be disabled
- *
- * @example
- * ```typescript
- * const disabled = resolveNextButtonDisabled({
- *   form: formInstance,
- *   formOptions: config.options,
- *   fieldLogic: buttonField.logic,
- *   explicitlyDisabled: buttonField.disabled,
- *   currentPageValid: pageOrchestrator.currentPageValid,
- * });
- * ```
- *
- * @public
- */
-declare function resolveNextButtonDisabled(ctx: ButtonLogicContext): Signal<boolean>;
-
 interface FieldWithValidation {
     readonly required?: boolean;
     readonly email?: boolean;
@@ -3815,77 +4092,375 @@ declare class PreviousPageEvent implements FormEvent {
 }
 
 /**
- * Event dispatched to add a new item to an array field.
+ * 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: '' }
+ */
+type ArrayItemDefinitionTemplate = ArrayAllowedChildren | ArrayItemTemplate;
+/**
+ * Event dispatched to append a new item at the END of an array field.
+ *
+ * This is the most common array operation - adding items to the end.
+ * For other positions, use {@link PrependArrayItemEvent} or {@link InsertArrayItemEvent}.
+ *
+ * @example
+ * ```typescript
+ * // Object item: append { name, email } object
+ * eventBus.dispatch(arrayEvent('contacts').append([
+ *   { key: 'name', type: 'input', label: 'Name' },
+ *   { key: 'email', type: 'input', label: 'Email' }
+ * ]));
+ *
+ * // Primitive item: append single value
+ * eventBus.dispatch(arrayEvent('tags').append(
+ *   { key: 'tag', type: 'input', label: 'Tag' }
+ * ));
+ * ```
+ *
+ * @typeParam TTemplate - The type of the template (single field or array of fields)
+ */
+declare class AppendArrayItemEvent<TTemplate extends ArrayItemDefinitionTemplate = ArrayItemDefinitionTemplate> implements FormEvent {
+    /** The key of the array field to append an item to */
+    readonly arrayKey: string;
+    /**
+     * Template for the new array item. REQUIRED.
+     * - Single field (FieldDef): Creates a primitive item (field's value is extracted directly)
+     * - Array of fields (FieldDef[]): Creates an object item (fields merged into object)
+     */
+    readonly template: TTemplate;
+    readonly type: "append-array-item";
+    constructor(
+    /** The key of the array field to append an item to */
+    arrayKey: string, 
+    /**
+     * Template for the new array item. REQUIRED.
+     * - Single field (FieldDef): Creates a primitive item (field's value is extracted directly)
+     * - Array of fields (FieldDef[]): Creates an object item (fields merged into object)
+     */
+    template: TTemplate);
+}
+
+/**
+ * Event dispatched to prepend a new item at the BEGINNING of an array field.
  *
- * This event is used to dynamically add items to array fields at runtime.
- * The array field component listens for this event and adds a new item
- * based on the provided field template, or uses the array's own template if not provided.
+ * Use this when new items should appear at the start of the list.
+ * For appending to the end, use {@link AppendArrayItemEvent}.
  *
  * @example
  * ```typescript
- * // Add item using array's own template
- * eventBus.dispatch(AddArrayItemEvent, 'contacts');
+ * // Object item: prepend { name } object
+ * eventBus.dispatch(arrayEvent('contacts').prepend([
+ *   { key: 'name', type: 'input', label: 'Name' }
+ * ]));
+ *
+ * // Primitive item: prepend single value
+ * eventBus.dispatch(arrayEvent('tags').prepend(
+ *   { key: 'tag', type: 'input', label: 'Tag' }
+ * ));
+ * ```
+ *
+ * @typeParam TTemplate - The type of the template (single field or array of fields)
+ */
+declare class PrependArrayItemEvent<TTemplate extends ArrayItemDefinitionTemplate = ArrayItemDefinitionTemplate> implements FormEvent {
+    /** The key of the array field to prepend an item to */
+    readonly arrayKey: string;
+    /**
+     * Template for the new array item. REQUIRED.
+     * - Single field (FieldDef): Creates a primitive item (field's value is extracted directly)
+     * - Array of fields (FieldDef[]): Creates an object item (fields merged into object)
+     */
+    readonly template: TTemplate;
+    readonly type: "prepend-array-item";
+    constructor(
+    /** The key of the array field to prepend an item to */
+    arrayKey: string, 
+    /**
+     * Template for the new array item. REQUIRED.
+     * - Single field (FieldDef): Creates a primitive item (field's value is extracted directly)
+     * - Array of fields (FieldDef[]): Creates an object item (fields merged into object)
+     */
+    template: TTemplate);
+}
+
+/**
+ * Event dispatched to insert a new item at a SPECIFIC INDEX in an array field.
  *
- * // Add item with explicit field template
- * const fieldTemplate = { key: 'email', type: 'input' };
- * eventBus.dispatch(AddArrayItemEvent, 'contacts', fieldTemplate);
+ * Use this when you need precise control over where the new item appears.
+ * For simpler operations, use {@link AppendArrayItemEvent} or {@link PrependArrayItemEvent}.
  *
- * // Add item at specific index
- * eventBus.dispatch(AddArrayItemEvent, 'contacts', fieldTemplate, 2);
+ * @example
+ * ```typescript
+ * // Object item: insert { name } object at index 2
+ * eventBus.dispatch(arrayEvent('contacts').insertAt(2, [
+ *   { key: 'name', type: 'input', label: 'Name' }
+ * ]));
+ *
+ * // Primitive item: insert single value at index 2
+ * eventBus.dispatch(arrayEvent('tags').insertAt(2,
+ *   { key: 'tag', type: 'input', label: 'Tag' }
+ * ));
  * ```
+ *
+ * @typeParam TTemplate - The type of the template (single field or array of fields)
  */
-declare class AddArrayItemEvent implements FormEvent {
-    /** The key of the array field to add an item to */
+declare class InsertArrayItemEvent<TTemplate extends ArrayItemDefinitionTemplate = ArrayItemDefinitionTemplate> implements FormEvent {
+    /** The key of the array field to insert an item into */
     readonly arrayKey: string;
+    /** The index at which to insert the new item */
+    readonly index: number;
     /**
-     * Optional field template definition to render for the new array item.
-     * If not provided, the array field component will use its own template.
+     * Template for the new array item. REQUIRED.
+     * - Single field (FieldDef): Creates a primitive item (field's value is extracted directly)
+     * - Array of fields (FieldDef[]): Creates an object item (fields merged into object)
      */
-    readonly field?: ArrayAllowedChildren | undefined;
-    /** Optional index where to insert the item (defaults to end of array) */
-    readonly index?: number | undefined;
-    readonly type: "add-array-item";
+    readonly template: TTemplate;
+    readonly type: "insert-array-item";
     constructor(
-    /** The key of the array field to add an item to */
+    /** The key of the array field to insert an item into */
     arrayKey: string, 
+    /** The index at which to insert the new item */
+    index: number, 
     /**
-     * Optional field template definition to render for the new array item.
-     * If not provided, the array field component will use its own template.
+     * Template for the new array item. REQUIRED.
+     * - Single field (FieldDef): Creates a primitive item (field's value is extracted directly)
+     * - Array of fields (FieldDef[]): Creates an object item (fields merged into object)
      */
-    field?: ArrayAllowedChildren | undefined, 
-    /** Optional index where to insert the item (defaults to end of array) */
-    index?: number | undefined);
+    template: TTemplate);
+}
+
+/**
+ * Event dispatched to remove the LAST item from an array field.
+ *
+ * Equivalent to JavaScript's `Array.pop()` - removes from the end.
+ * For removing from the beginning, use {@link ShiftArrayItemEvent}.
+ * For removing at a specific index, use {@link RemoveAtIndexEvent}.
+ *
+ * @example
+ * ```typescript
+ * // Use the builder API (recommended)
+ * eventBus.dispatch(arrayEvent('contacts').pop());
+ *
+ * // Or instantiate directly
+ * eventBus.dispatch(new PopArrayItemEvent('contacts'));
+ * ```
+ */
+declare class PopArrayItemEvent implements FormEvent {
+    /** The key of the array field to remove the last item from */
+    readonly arrayKey: string;
+    readonly type: "pop-array-item";
+    constructor(
+    /** The key of the array field to remove the last item from */
+    arrayKey: string);
+}
+
+/**
+ * Event dispatched to remove the FIRST item from an array field.
+ *
+ * Equivalent to JavaScript's `Array.shift()` - removes from the beginning.
+ * For removing from the end, use {@link PopArrayItemEvent}.
+ * For removing at a specific index, use {@link RemoveAtIndexEvent}.
+ *
+ * @example
+ * ```typescript
+ * // Use the builder API (recommended)
+ * eventBus.dispatch(arrayEvent('contacts').shift());
+ *
+ * // Or instantiate directly
+ * eventBus.dispatch(new ShiftArrayItemEvent('contacts'));
+ * ```
+ */
+declare class ShiftArrayItemEvent implements FormEvent {
+    /** The key of the array field to remove the first item from */
+    readonly arrayKey: string;
+    readonly type: "shift-array-item";
+    constructor(
+    /** The key of the array field to remove the first item from */
+    arrayKey: string);
 }
 
 /**
- * Event dispatched to remove an item from an array field.
+ * Event dispatched to remove an item at a SPECIFIC INDEX from an array field.
  *
- * This event is used to dynamically remove items from array fields at runtime.
- * The array field component listens for this event and removes the item
- * at the specified index.
+ * Use this when you need precise control over which item to remove.
+ * For simpler operations, use {@link PopArrayItemEvent} or {@link ShiftArrayItemEvent}.
  *
  * @example
  * ```typescript
- * // Remove item at index 1 from 'contacts' array
- * eventBus.dispatch(RemoveArrayItemEvent, 'contacts', 1);
+ * // Use the builder API (recommended)
+ * eventBus.dispatch(arrayEvent('contacts').removeAt(2));
  *
- * // Remove last item
- * eventBus.dispatch(RemoveArrayItemEvent, 'contacts');
+ * // Or instantiate directly
+ * eventBus.dispatch(new RemoveAtIndexEvent('contacts', 2));
  * ```
  */
-declare class RemoveArrayItemEvent implements FormEvent {
+declare class RemoveAtIndexEvent implements FormEvent {
     /** The key of the array field to remove an item from */
     readonly arrayKey: string;
-    /** Index of the item to remove (defaults to last item) */
-    readonly index?: number | undefined;
-    readonly type: "remove-array-item";
+    /** The index of the item to remove */
+    readonly index: number;
+    readonly type: "remove-at-index";
     constructor(
     /** The key of the array field to remove an item from */
     arrayKey: string, 
-    /** Index of the item to remove (defaults to last item) */
-    index?: number | undefined);
+    /** The index of the item to remove */
+    index: number);
 }
 
+/**
+ * Builder for array manipulation events.
+ *
+ * Provides a fluent, discoverable API for array operations.
+ * Type `arrayEvent('key').` in your IDE to see all available operations.
+ *
+ * **BREAKING CHANGE**: Template is now required for add operations.
+ *
+ * Supports both primitive and object array items:
+ * - Primitive: Pass a single field definition → extracts field value directly
+ * - Object: Pass an array of field definitions → merges fields into object
+ *
+ * @example
+ * ```typescript
+ * import { arrayEvent } from '@ng-forge/dynamic-forms';
+ *
+ * // Object item: append { name, email } object
+ * eventBus.dispatch(arrayEvent('contacts').append([
+ *   { key: 'name', type: 'input', label: 'Name' },
+ *   { key: 'email', type: 'input', label: 'Email' }
+ * ]));
+ *
+ * // Primitive item: append single value
+ * eventBus.dispatch(arrayEvent('tags').append(
+ *   { key: 'tag', type: 'input', label: 'Tag' }
+ * ));
+ *
+ * // Removing items (no template needed)
+ * eventBus.dispatch(arrayEvent('contacts').pop());      // Remove last
+ * eventBus.dispatch(arrayEvent('contacts').shift());    // Remove first
+ * eventBus.dispatch(arrayEvent('contacts').removeAt(2)); // Remove at index
+ * ```
+ *
+ * @param arrayKey - The key of the array field to operate on
+ * @returns An object with methods for all 6 array operations
+ */
+declare function arrayEvent(arrayKey: string): {
+    /**
+     * Append a new item at the END of the array.
+     * This is the most common operation for adding items.
+     *
+     * @param template - Template for the new item (REQUIRED)
+     *   - Single field: Creates a primitive item (field's value is extracted directly)
+     *   - Array of fields: Creates an object item (fields merged into object)
+     * @returns An AppendArrayItemEvent to dispatch
+     *
+     * @example
+     * ```typescript
+     * // Object item
+     * eventBus.dispatch(arrayEvent('contacts').append([
+     *   { key: 'name', type: 'input', label: 'Name' }
+     * ]));
+     *
+     * // Primitive item
+     * eventBus.dispatch(arrayEvent('tags').append(
+     *   { key: 'tag', type: 'input', label: 'Tag' }
+     * ));
+     * ```
+     */
+    append: <T extends ArrayItemDefinitionTemplate>(template: T) => AppendArrayItemEvent<T>;
+    /**
+     * Prepend a new item at the BEGINNING of the array.
+     * Use when new items should appear at the start.
+     *
+     * @param template - Template for the new item (REQUIRED)
+     *   - Single field: Creates a primitive item (field's value is extracted directly)
+     *   - Array of fields: Creates an object item (fields merged into object)
+     * @returns A PrependArrayItemEvent to dispatch
+     *
+     * @example
+     * ```typescript
+     * // Object item
+     * eventBus.dispatch(arrayEvent('contacts').prepend([
+     *   { key: 'name', type: 'input', label: 'Name' }
+     * ]));
+     *
+     * // Primitive item
+     * eventBus.dispatch(arrayEvent('tags').prepend(
+     *   { key: 'tag', type: 'input', label: 'Tag' }
+     * ));
+     * ```
+     */
+    prepend: <T extends ArrayItemDefinitionTemplate>(template: T) => PrependArrayItemEvent<T>;
+    /**
+     * Insert a new item at a SPECIFIC INDEX in the array.
+     * Use when you need precise control over item placement.
+     *
+     * @param index - The position at which to insert the new item
+     * @param template - Template for the new item (REQUIRED)
+     *   - Single field: Creates a primitive item (field's value is extracted directly)
+     *   - Array of fields: Creates an object item (fields merged into object)
+     * @returns An InsertArrayItemEvent to dispatch
+     *
+     * @example
+     * ```typescript
+     * // Object item at index 2
+     * eventBus.dispatch(arrayEvent('contacts').insertAt(2, [
+     *   { key: 'name', type: 'input', label: 'Name' }
+     * ]));
+     *
+     * // Primitive item at index 2
+     * eventBus.dispatch(arrayEvent('tags').insertAt(2,
+     *   { key: 'tag', type: 'input', label: 'Tag' }
+     * ));
+     * ```
+     */
+    insertAt: <T extends ArrayItemDefinitionTemplate>(index: number, template: T) => InsertArrayItemEvent<T>;
+    /**
+     * Remove the LAST item from the array.
+     * Equivalent to JavaScript's `Array.pop()`.
+     *
+     * @returns A PopArrayItemEvent to dispatch
+     *
+     * @example
+     * ```typescript
+     * eventBus.dispatch(arrayEvent('contacts').pop());
+     * ```
+     */
+    pop: () => PopArrayItemEvent;
+    /**
+     * Remove the FIRST item from the array.
+     * Equivalent to JavaScript's `Array.shift()`.
+     *
+     * @returns A ShiftArrayItemEvent to dispatch
+     *
+     * @example
+     * ```typescript
+     * eventBus.dispatch(arrayEvent('contacts').shift());
+     * ```
+     */
+    shift: () => ShiftArrayItemEvent;
+    /**
+     * Remove an item at a SPECIFIC INDEX from the array.
+     * Use when you need to remove a specific item by position.
+     *
+     * @param index - The position of the item to remove
+     * @returns A RemoveAtIndexEvent to dispatch
+     *
+     * @example
+     * ```typescript
+     * eventBus.dispatch(arrayEvent('contacts').removeAt(2));
+     * ```
+     */
+    removeAt: (index: number) => RemoveAtIndexEvent;
+};
+
 /**
  * Event bus service for form-wide event communication.
  *
@@ -3984,6 +4559,8 @@ interface TokenContext {
     arrayKey?: string;
     /** Current form value for complex indexing */
     formValue?: unknown;
+    /** Template for array item creation */
+    template?: unknown;
 }
 /**
  * Resolves special tokens in event arguments to their actual values
@@ -3992,6 +4569,7 @@ interface TokenContext {
  * - $key: The current field key
  * - $index: The array index (if inside an array field)
  * - $arrayKey: The parent array field key (if inside an array field)
+ * - $template: The template for array item creation
  * - formValue: Reference to the current form value for indexing
  *
  * @param args - Array of arguments that may contain tokens
@@ -4005,6 +4583,10 @@ interface TokenContext {
  * @example
  * resolveTokens(['$key', 'static'], { key: 'myField' })
  * // Returns: ['myField', 'static']
+ *
+ * @example
+ * resolveTokens(['$arrayKey', '$template'], { arrayKey: 'contacts', template: [{ key: 'name', type: 'input' }] })
+ * // Returns: ['contacts', [{ key: 'name', type: 'input' }]]
  */
 declare function resolveTokens(args: readonly (string | number | boolean | null | undefined)[], context: TokenContext): (string | number | boolean | null | undefined | unknown)[];
 
@@ -4221,8 +4803,14 @@ declare function pageFieldMapper(fieldDef: PageField): Signal<Record<string, unk
  * Maps a text field definition to component inputs.
  *
  * Text fields are display-only fields that don't participate in the form schema.
- * This mapper handles the `logic` configuration by creating reactive signals
- * that evaluate conditions using the form value from RootFormRegistryService.
+ * This mapper handles the `logic` configuration by using the non-field-hidden resolver
+ * to evaluate conditions against the form value from RootFormRegistryService.
+ *
+ * Hidden state is resolved using the non-field-hidden resolver which considers:
+ * 1. Explicit `hidden: true` on the field definition
+ * 2. Field-level `logic` array with `type: 'hidden'` conditions
+ *
+ * Note: Text fields don't support disabled logic since they are display-only.
  *
  * @param fieldDef The text field definition
  * @returns Signal containing Record of input names to values for ngComponentOutlet
@@ -4343,9 +4931,7 @@ declare class GroupFieldComponent<TModel extends Record<string, unknown> = Recor
     private readonly injector;
     private readonly eventBus;
     private readonly logger;
-    private readonly memoizedFlattenFields;
-    private readonly memoizedKeyBy;
-    private readonly memoizedDefaultValues;
+    private readonly fieldProcessors;
     field: _angular_core.InputSignal<GroupField<readonly _ng_forge_dynamic_forms.GroupAllowedChildren[]>>;
     key: _angular_core.InputSignal<string>;
     className: _angular_core.InputSignal<string | undefined>;
@@ -4353,6 +4939,11 @@ declare class GroupFieldComponent<TModel extends Record<string, unknown> = Recor
     private readonly rawFieldRegistry;
     private readonly formSetup;
     readonly defaultValues: _angular_core.WritableSignal<Record<string, unknown>>;
+    /**
+     * Entity computed from parent value, group key, and defaults.
+     * Uses deep equality check to prevent unnecessary updates when
+     * object spread creates new references with identical values.
+     */
     private readonly entity;
     private readonly form;
     readonly formValue: _angular_core.Signal<{}>;
@@ -4363,6 +4954,7 @@ declare class GroupFieldComponent<TModel extends Record<string, unknown> = Recor
     readonly errors: _angular_core.Signal<_angular_forms_signals.ValidationError.WithField[]>;
     readonly disabled: _angular_core.Signal<boolean>;
     private readonly nestedFieldTree;
+    private readonly groupFieldSignalContext;
     private readonly groupInjector;
     readonly validityChange: _angular_core.OutputRef<boolean>;
     readonly dirtyChange: _angular_core.OutputRef<boolean>;
@@ -4376,13 +4968,9 @@ declare class GroupFieldComponent<TModel extends Record<string, unknown> = Recor
 }
 
 /**
- * Resolved array item ready for declarative rendering with ngComponentOutlet.
- * Each item has a stable unique ID and a linkedSignal-based index that
- * automatically updates when items are added/removed.
+ * A single field within a resolved array item.
  */
-interface ResolvedArrayItem {
-    /** Unique identifier for this item (stable across position changes). */
-    id: string;
+interface ResolvedArrayItemField {
     /** The loaded component type. */
     component: Type<unknown>;
     /** Injector providing ARRAY_CONTEXT and FIELD_SIGNAL_CONTEXT. */
@@ -4390,13 +4978,26 @@ interface ResolvedArrayItem {
     /** Inputs signal for ngComponentOutlet - evaluated in template for reactivity. */
     inputs: Signal<Record<string, unknown>>;
 }
+/**
+ * Resolved array item ready for declarative rendering with ngComponentOutlet.
+ * Each item has a stable unique ID and a linkedSignal-based index that
+ * automatically updates when items are added/removed.
+ * Supports multiple fields per array item (e.g., name + email without a wrapper).
+ */
+interface ResolvedArrayItem {
+    /** Unique identifier for this item (stable across position changes). */
+    id: string;
+    /** All fields to render for this array item. */
+    fields: ResolvedArrayItemField[];
+}
 
 /**
  * Container component for rendering dynamic arrays of fields.
  *
- * Supports add/remove operations via AddArrayItemEvent and RemoveArrayItemEvent.
+ * Supports add/remove operations via the arrayEvent() builder API.
  * Uses differential updates to optimize rendering - only recreates items when necessary.
  * Each item gets a scoped injector with ARRAY_CONTEXT for position-aware operations.
+ * Supports multiple sibling fields per array item (e.g., name + email without a wrapper).
  */
 declare class ArrayFieldComponent<TModel extends Record<string, unknown> = Record<string, unknown>> {
     private readonly destroyRef;
@@ -4405,25 +5006,62 @@ declare class ArrayFieldComponent<TModel extends Record<string, unknown> = Recor
     private readonly parentInjector;
     private readonly eventBus;
     private readonly logger;
-    field: _angular_core.InputSignal<ArrayField<readonly _ng_forge_dynamic_forms.ArrayAllowedChildren[]>>;
+    private readonly templateRegistry;
+    private readonly generateItemId;
+    field: _angular_core.InputSignal<ArrayField<readonly ArrayItemDefinition[]>>;
     key: _angular_core.InputSignal<string>;
     className: _angular_core.InputSignal<string | undefined>;
     readonly hostClasses: _angular_core.Signal<string>;
     private readonly rawFieldRegistry;
-    private readonly fieldTemplate;
+    /**
+     * 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
+     *
+     * Returns normalized templates where all items are arrays for consistent handling.
+     */
+    private readonly itemTemplates;
     private readonly arrayFieldTrees;
     private readonly resolvedItemsSignal;
     private readonly updateVersion;
-    private readonly itemOrderSignal;
-    readonly resolvedItems: _angular_core.WritableSignal<ResolvedArrayItem[]>;
+    /**
+     * 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.
+     */
+    private readonly itemPositionMap;
+    /** Read-only view of resolved items for template consumption. */
+    readonly resolvedItems: _angular_core.Signal<ResolvedArrayItem[]>;
     constructor();
     private setupEffects;
     private setupEventHandlers;
+    /**
+     * Handles add operations from events (append, prepend, insert).
+     * Creates resolved items FIRST, then updates form value.
+     * This ensures prepend/insert work correctly - differential update sees "none"
+     * because resolved items count already matches the new array length.
+     *
+     * Supports both primitive (single FieldDef) and object (FieldDef[]) templates.
+     */
+    private handleAddFromEvent;
     private performDifferentialUpdate;
     private resolveAllItems;
     private appendItems;
+    /**
+     * Creates an observable that resolves a single array item.
+     *
+     * Template resolution order:
+     * 1. Use overrideTemplate if provided (from recreate with stored templates)
+     * 2. Use itemTemplates[index] if within defined templates range
+     * 3. Return undefined (item cannot be resolved without a template)
+     */
     private createResolveItemObservable;
-    private addItem;
+    /**
+     * Handles remove operations from events (pop, shift, removeAt).
+     * Updates resolvedItems FIRST, then form value - this ensures differential
+     * update sees "none" (lengths match) and avoids unnecessary recreates.
+     * Remaining items' linkedSignal indices auto-update via itemPositionMap.
+     */
     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>;
@@ -4501,97 +5139,16 @@ declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): O
 declare function interpolateParams(message: string, error: ValidationError): string;
 
 /**
- * Registry service that maintains references to root form fields.
- * This provides a type-safe way to access root form values from child fields
- * without relying on internal Angular Forms API navigation.
- *
- * This service should be provided at the component level to ensure proper
- * isolation between different form instances.
+ * Registry service that provides access to the root form and its values.
  *
- * IMPORTANT: This registry supports two registration patterns:
- * 1. registerFormValueSignal() - Register the SOURCE signal BEFORE form creation
- *    This allows logic functions to read form values during schema evaluation.
- * 2. registerRootForm() - Register the FieldTree AFTER form creation
- *    This provides access to the full form structure.
- *
- * For cross-field logic to work correctly, registerFormValueSignal() should be
- * called BEFORE the form() call.
+ * Constructed via factory in `provideDynamicFormDI` with signals from
+ * `FormStateManager` — no DI injection, no Maps, no lifecycle.
  */
 declare class RootFormRegistryService {
-    private readonly _rootForms;
-    private readonly _formValueSignals;
-    private readonly formContexts;
-    /**
-     * Registers the form value signal BEFORE form creation.
-     *
-     * This is the recommended pattern for cross-field logic:
-     * 1. Create the formValue signal
-     * 2. Register it with registerFormValueSignal()
-     * 3. Create the form with form(formValue, schema(...))
-     *
-     * This allows logic functions to access form values during schema evaluation.
-     */
-    registerFormValueSignal(valueSignal: Signal<Record<string, unknown>>, formId?: string): void;
-    /**
-     * Gets the registered form value signal by id.
-     *
-     * This allows direct access to the source signal, which can be read
-     * reactively to get form values.
-     */
-    getFormValueSignal(formId?: string): Signal<Record<string, unknown>> | undefined;
-    /**
-     * Registers a root form field with an optional identifier.
-     * If no id is provided, uses 'default' as the key.
-     *
-     * This triggers reactive updates for any computed signals that
-     * depend on getRootForm().
-     */
-    registerRootForm(rootField: FieldTree<unknown>, formId?: string): void;
-    /**
-     * Gets a registered root form field by id.
-     *
-     * IMPORTANT: This method reads from a signal, which means any computed
-     * signal that calls this method will automatically re-evaluate when
-     * the form is registered or updated.
-     */
-    getRootForm(formId?: string): FieldTree<unknown> | undefined;
-    /**
-     * Gets the form value, preferring the direct signal if available.
-     *
-     * This method tries in order:
-     * 1. Form value signal (if registered) - reads directly from source signal
-     * 2. Root form's .value() (if registered) - reads from FieldTree
-     * 3. Returns empty object if nothing is registered
-     *
-     * Reading from signals creates reactive dependencies, so computeds will
-     * re-evaluate when form values change.
-     */
-    getFormValue(formId?: string): Record<string, unknown>;
-    /**
-     * Registers form context (field paths and metadata) for a specific form.
-     * This can be used to store additional context information.
-     */
-    registerFormContext(context: Record<string, unknown>, formId?: string): void;
-    /**
-     * Gets form context by id.
-     */
-    getFormContext(formId?: string): Record<string, unknown>;
-    /**
-     * Unregisters a form and its context.
-     * This should be called when a form component is destroyed to prevent memory leaks.
-     */
-    unregisterForm(formId?: string): void;
-    /**
-     * Gets all registered form IDs.
-     */
-    getRegisteredFormIds(): string[];
-    /**
-     * Clears all registered forms. Useful for testing.
-     */
-    clear(): void;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<RootFormRegistryService, never>;
-    static ɵprov: _angular_core.ɵɵInjectableDeclaration<RootFormRegistryService>;
+    readonly formValue: Signal<Record<string, unknown>>;
+    readonly rootForm: Signal<FieldTree<Record<string, unknown>> | undefined>;
+    constructor(formValue: Signal<Record<string, unknown>>, rootForm: Signal<FieldTree<Record<string, unknown>> | undefined>);
 }
 
-export { ARRAY_CONTEXT, AddArrayItemEvent, ArrayFieldComponent, BUILT_IN_FIELDS, ConsoleLogger, DEFAULT_PROPS, DEFAULT_VALIDATION_MESSAGES, DynamicForm, DynamicFormError, DynamicFormLogger, DynamicTextPipe, EventBus, FIELD_REGISTRY, FIELD_SIGNAL_CONTEXT, FORM_OPTIONS, FormClearEvent, FormResetEvent, GroupFieldComponent, NextPageEvent, NoopLogger, PageChangeEvent, PreviousPageEvent, RemoveArrayItemEvent, RootFormRegistryService, RowFieldComponent, SubmitEvent, applyMetaToElement, applyValidator, applyValidators, arrayFieldMapper, baseFieldMapper, buildBaseInputs, createField, dynamicTextToObservable, field, formConfig, getArrayLength, groupFieldMapper, hasFormValue, interpolateParams, isArrayField, isCheckedField, isContainerField, isDisplayOnlyField, isEqual, isFormStateCondition, isGroupField, isLeafField, isPageField, isRowField, isValueBearingField, isValueField, omit, pageFieldMapper, provideDynamicForm, resolveNextButtonDisabled, resolveSubmitButtonDisabled, resolveTokens, rowFieldMapper, textFieldMapper, withEventFormValue, withLoggerConfig };
-export type { ArrayAllowedChildren, ArrayContext, ArrayField, ArrayFieldTree, ArrayItemContext, AsyncCustomValidator, AsyncValidatorConfig, AvailableFieldTypes, BaseCheckedField, BaseValidatorConfig, BaseValueField, BuiltInValidatorConfig, ButtonLogicContext, CheckedFieldComponent, ConditionalExpression, ContainerFieldTypes, CustomFnConfig, CustomValidator, CustomValidatorConfig, DynamicFormFieldRegistry, DynamicText, EvaluationContext, ExtractField, ExtractFieldDefs, ExtractFormValue, FieldComponent, FieldDef, FieldMeta, FieldOption, FieldPathAccess, FieldRegistryContainers, FieldRegistryLeaves, FieldSignalContext, FieldTypeDefinition, FieldWithValidation, FormConfig, FormEvent, FormEventConstructor, FormMode, FormModeDetectionResult, FormOptions, FormStateCondition, GroupAllowedChildren, GroupField, HttpCustomValidator, HttpResourceRequest, HttpValidatorConfig, InferFormValue$1 as InferFormValue, LeafFieldTypes, Logger, LogicConfig, MapperFn, NarrowField, NarrowFields, NextButtonOptions, PageAllowedChildren, PageField, Prettify, RegisteredFieldTypes, RowAllowedChildren, RowField, SchemaApplicationConfig, SchemaDefinition, SubmissionActionResult, SubmissionConfig, SubmitButtonOptions, TextElementType, TextField, TextProps, TokenContext, ValidationError, ValidationMessages, ValidatorConfig, ValueFieldComponent, ValueHandlingMode, ValueType, WithInputSignals };
+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 };