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

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

@@ -16,8 +16,6 @@ type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
 
-type DynamicText = string | Observable<string> | Signal<string>;
-
 /**
  * Interface for dynamic forms logger implementations.
  * Allows custom logging integrations (Sentry, DataDog, etc.)
@@ -589,214 +587,31 @@ interface ContainerLogicConfig {
 }
 
 /**
- * An array item template is an array of allowed children that defines one OBJECT array item's fields.
- * Used for object arrays where each item is `{ key1: value1, key2: value2, ... }`.
- */
-type ArrayItemTemplate = readonly ArrayAllowedChildren[];
-/**
- * An array item definition can be either:
- * - A single field (ArrayAllowedChildren) for PRIMITIVE array items - extracts field value directly
- * - An array of fields (ArrayItemTemplate) for OBJECT array items - merges fields into object
- *
- * This allows support for:
- * - Primitive arrays: `['tag1', 'tag2']`
- * - Object arrays: `[{ name: 'Alice', email: '...' }]`
- * - Heterogeneous arrays: `[{ value: 'x' }, 'y']` (mixed primitives and objects)
- */
-type ArrayItemDefinition = ArrayAllowedChildren | ArrayItemTemplate;
-/**
- * Array field interface for creating dynamic field collections that map to array values.
- *
- * Key concepts:
- * - The outer `fields` array defines INITIAL ITEMS (each element is one array item to render)
- * - Each element can be either:
- *   - A single FieldDef (primitive item) - the field's value is extracted directly
- *   - An array of FieldDefs (object item) - fields are merged into an object
- * - Items can have different field configurations (heterogeneous arrays supported)
- * - Empty `fields: []` means no initial items - user adds via buttons with explicit templates
- * - Initial values are declared via `value` property on each field definition
- *
- * @example
- * // Primitive array: ['angular', 'typescript']
- * {
- *   key: 'tags',
- *   type: 'array',
- *   fields: [
- *     { key: 'tag', type: 'input', value: 'angular' },      // Single field = primitive
- *     { key: 'tag', type: 'input', value: 'typescript' },
- *   ]
- * }
- *
- * @example
- * // Object array: [{ name: 'Alice', email: '...' }]
- * {
- *   key: 'contacts',
- *   type: 'array',
- *   fields: [
- *     [                                                      // Array = object
- *       { key: 'name', type: 'input', value: 'Alice' },
- *       { key: 'email', type: 'input', value: 'alice@example.com' }
- *     ],
- *   ]
- * }
- *
- * @example
- * // Heterogeneous array: [{ label: 'Structured' }, 'Simple']
- * {
- *   key: 'items',
- *   type: 'array',
- *   fields: [
- *     [{ key: 'label', type: 'input', value: 'Structured' }],  // Object item
- *     { key: 'value', type: 'input', value: 'Simple' },        // Primitive item
- *   ]
- * }
- *
- * @example
- * // Empty array (add items via buttons)
- * {
- *   key: 'tags',
- *   type: 'array',
- *   fields: []  // No initial items - user adds via button with template
- * }
- *
- * Nesting constraints: Arrays can contain rows, leaf fields, or groups (for object arrays),
- * but NOT pages or other arrays. Runtime validation enforces these rules.
+ * Row field interface for creating horizontal layouts.
+ * A row is a synthetic field type that resolves to a Container at runtime,
+ * with a synthesized `{ type: 'row' }` wrapper applied for layout. The row
+ * itself does not hold a value — its children flatten into the parent form.
  *
- * Note: Arrays are container fields and do not support `meta` since they have no native form element.
+ * Note: Rows do not support `meta` since they have no native form element.
  */
-interface ArrayField<TFields extends readonly ArrayItemDefinition[] = readonly ArrayItemDefinition[]> extends FieldDef<never> {
-    type: 'array';
-    /**
-     * Array of item definitions. Each element defines one array item:
-     * - Single FieldDef = primitive item (field's value is extracted directly)
-     * - Array of FieldDefs = object item (fields are merged into an object)
-     * - Empty array `[]` = no initial items (add via buttons with explicit templates)
-     * - Items can have different configurations (heterogeneous arrays supported)
-     * - Initial values are set via `value` property on each field definition
-     */
+interface RowField<TFields extends readonly RowAllowedChildren[] = readonly RowAllowedChildren[]> extends FieldDef<never> {
+    type: 'row';
+    /** Child definitions to render within this row */
     readonly fields: TFields;
-    /** Array fields do not have a label property **/
-    readonly label?: never;
-    /** Arrays do not support meta - they have no native form element **/
-    readonly meta?: never;
-    /**
-     * Logic configurations for conditional array visibility.
-     * Only 'hidden' type logic is supported for arrays.
-     */
-    readonly logic?: ContainerLogicConfig[];
-    /**
-     * Minimum number of items required in the array.
-     * Validation fails if the array has fewer items than this value.
-     */
-    readonly minLength?: number;
-    /**
-     * Maximum number of items allowed in the array.
-     * Validation fails if the array has more items than this value.
-     */
-    readonly maxLength?: number;
-}
-/**
- * Type guard for ArrayField with proper type narrowing.
- * Validates that the field is an array type with a fields property that is an array.
- * Fields can contain either single FieldDefs (primitive items) or arrays of FieldDefs (object items).
- */
-declare function isArrayField(field: FieldDef<any>): field is ArrayField;
-/**
- * Configuration for auto-generated add/remove buttons in simplified array fields.
- */
-interface ArrayButtonConfig {
-    /** Custom label for the button */
-    readonly label?: string;
-    /** Additional properties passed to the button component */
-    readonly props?: Record<string, unknown>;
-}
-/**
- * Simplified array field interface for common use cases.
- *
- * Instead of manually specifying each item in `fields`, provide a `template` that defines
- * the structure of a single item, and a `value` array with initial data.
- * The library auto-generates add/remove buttons.
- *
- * Discriminant: `template` presence → simplified API; `Array.isArray(template)` → object vs primitive.
- *
- * @example
- * // Primitive array: ['angular', 'typescript']
- * {
- *   key: 'tags',
- *   type: 'array',
- *   template: { key: 'value', type: 'input', label: 'Tag', required: true },
- *   value: ['angular', 'typescript']
- * }
- *
- * @example
- * // Object array: [{ name: 'Jane', phone: '555' }]
- * {
- *   key: 'contacts',
- *   type: 'array',
- *   template: [
- *     { key: 'name', type: 'input', label: 'Contact Name', required: true },
- *     { key: 'phone', type: 'input', label: 'Phone Number' },
- *   ],
- *   value: [{ name: 'Jane', phone: '555' }]
- * }
- *
- * @example
- * // Button customization / opt-out
- * {
- *   key: 'tags',
- *   type: 'array',
- *   template: { key: 'value', type: 'input', label: 'Tag' },
- *   addButton: { label: 'Add Tag', props: { color: 'primary' } },
- *   removeButton: false
- * }
- */
-interface SimplifiedArrayField extends FieldDef<never> {
-    type: 'array';
-    /**
-     * Template defining the structure of a single array item.
-     * - Single field (ArrayAllowedChildren) → primitive array (each item is a single value)
-     * - Array of fields (readonly ArrayAllowedChildren[]) → object array (each item is an object)
-     */
-    readonly 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 */
+    /** Row fields do not have a label property **/
     readonly label?: never;
-    /** Simplified arrays do not support meta */
+    /** Rows 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.
+     * Logic configurations for conditional row visibility.
+     * Only 'hidden' type logic is supported for rows.
      */
     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).
+ * Type guard for RowField with proper type narrowing
  */
-declare function isSimplifiedArrayField(field: FieldDef<any>): field is SimplifiedArrayField;
+declare function isRowField(field: FieldDef<any>): field is RowField;
 
 /**
  * Group field interface for creating logical field groupings that map to object values
@@ -828,67 +643,15 @@ interface GroupField<TFields extends readonly GroupAllowedChildren[] = readonly
 declare function isGroupField(field: FieldDef<any>): field is GroupField;
 
 /**
- * Scalar types supported by hidden fields.
- * These are the primitive value types that can be stored.
- */
-type HiddenScalar = string | number | boolean;
-/**
- * All value types supported by hidden fields.
- * Supports both scalar values and arrays of scalars for storing
- * multiple IDs or similar data.
- */
-type HiddenValue = HiddenScalar | HiddenScalar[];
-/**
- * Hidden field definition for storing values without rendering UI.
- *
- * Hidden fields participate in the form schema and contribute to form values,
- * but do not render any visible component. They are useful for:
- * - Storing IDs when updating existing records
- * - Persisting metadata that shouldn't be user-editable
- * - Tracking computed values that need to be submitted
- *
- * Unlike the `hidden` property on other fields (which hides a rendered field),
- * this field type renders nothing at all - it's a componentless field.
+ * Page field interface for creating top-level page layouts
+ * This is a special field type that contains other field definitions
+ * The page itself doesn't have a value - it's a layout container like row
+ * Pages can only be used at the top level and cannot be nested
+ * This is a programmatic field type only - users cannot customize this field type
  *
- * @example
- * ```typescript
- * // Store a record ID for updates
- * const idField: HiddenField<string> = {
- *   type: 'hidden',
- *   key: 'id',
- *   value: '550e8400-e29b-41d4-a716-446655440000',
- * };
- *
- * // Store multiple tag IDs
- * const tagIdsField: HiddenField<number[]> = {
- *   type: 'hidden',
- *   key: 'tagIds',
- *   value: [1, 2, 3],
- * };
- * ```
- *
- * @typeParam TValue - The type of value stored (must be HiddenValue compatible)
- */
-interface HiddenField<TValue extends HiddenValue = HiddenValue> extends FieldDef<never> {
-    /** Discriminant for hidden field type */
-    type: 'hidden';
-    /**
-     * The value to store in the form.
-     * This is required - a hidden field without a value serves no purpose.
-     */
-    value: TValue;
-}
-
-/**
- * Page field interface for creating top-level page layouts
- * This is a special field type that contains other field definitions
- * The page itself doesn't have a value - it's a layout container like row
- * Pages can only be used at the top level and cannot be nested
- * This is a programmatic field type only - users cannot customize this field type
- *
- * TypeScript cannot enforce field nesting rules due to circular dependency limitations.
- * For documentation: Pages should contain rows, groups, and leaf fields, but NOT other pages.
- * Runtime validation enforces these rules.
+ * TypeScript cannot enforce field nesting rules due to circular dependency limitations.
+ * For documentation: Pages should contain rows, groups, and leaf fields, but NOT other pages.
+ * Runtime validation enforces these rules.
  *
  * Note: Pages are container fields and do not support `meta` since they have no native form element.
  */
@@ -2335,6 +2098,8 @@ interface SchemaDefinition {
     subSchemas?: SchemaApplicationConfig[];
 }
 
+type DynamicText = string | Observable<string> | Signal<string>;
+
 /**
  * Re-export Angular's ValidationError for consistency
  * This replaces our custom ValidationError interface
@@ -2420,7 +2185,6 @@ type SubmissionActionResult = Promise<TreeValidationResult> | Observable<TreeVal
  * @typeParam TValue - The form value type
  *
  * @public
- * @experimental
  */
 interface SubmissionConfig<TValue = unknown> {
     /**
@@ -3433,6 +3197,58 @@ interface TextField extends FieldDef<TextProps> {
     readonly logic?: NonFieldLogicConfig[];
 }
 
+/**
+ * Scalar types supported by hidden fields.
+ * These are the primitive value types that can be stored.
+ */
+type HiddenScalar = string | number | boolean;
+/**
+ * All value types supported by hidden fields.
+ * Supports both scalar values and arrays of scalars for storing
+ * multiple IDs or similar data.
+ */
+type HiddenValue = HiddenScalar | HiddenScalar[];
+/**
+ * Hidden field definition for storing values without rendering UI.
+ *
+ * Hidden fields participate in the form schema and contribute to form values,
+ * but do not render any visible component. They are useful for:
+ * - Storing IDs when updating existing records
+ * - Persisting metadata that shouldn't be user-editable
+ * - Tracking computed values that need to be submitted
+ *
+ * Unlike the `hidden` property on other fields (which hides a rendered field),
+ * this field type renders nothing at all - it's a componentless field.
+ *
+ * @example
+ * ```typescript
+ * // Store a record ID for updates
+ * const idField: HiddenField<string> = {
+ *   type: 'hidden',
+ *   key: 'id',
+ *   value: '550e8400-e29b-41d4-a716-446655440000',
+ * };
+ *
+ * // Store multiple tag IDs
+ * const tagIdsField: HiddenField<number[]> = {
+ *   type: 'hidden',
+ *   key: 'tagIds',
+ *   value: [1, 2, 3],
+ * };
+ * ```
+ *
+ * @typeParam TValue - The type of value stored (must be HiddenValue compatible)
+ */
+interface HiddenField<TValue extends HiddenValue = HiddenValue> extends FieldDef<never> {
+    /** Discriminant for hidden field type */
+    type: 'hidden';
+    /**
+     * The value to store in the form.
+     * This is required - a hidden field without a value serves no purpose.
+     */
+    value: TValue;
+}
+
 /**
  * Configuration for the built-in 'css' wrapper type.
  *
@@ -3472,6 +3288,118 @@ interface RowWrapper {
     readonly type: 'row';
 }
 
+/**
+ * Resolves a wrapper type name to its registered config interface.
+ *
+ * When `TWrappers` is a specific registered key (e.g., `'css'`), resolves to
+ * the full config type from `FieldRegistryWrappers` (e.g., `CssWrapper`),
+ * providing type-safe access to wrapper-specific properties like `cssClasses`.
+ *
+ * When `TWrappers` is the full `RegisteredWrapperTypes` union, distributes
+ * to produce a discriminated union of all registered wrapper configs.
+ *
+ * @example
+ * ```typescript
+ * // Resolves to CssWrapper — cssClasses is typed
+ * type CssConfig = WrapperConfig<'css'>;
+ *
+ * // Union of all registered wrapper configs
+ * type AnyConfig = WrapperConfig;
+ * ```
+ */
+type WrapperConfig<TWrappers extends RegisteredWrapperTypes = RegisteredWrapperTypes> = TWrappers extends keyof FieldRegistryWrappers ? FieldRegistryWrappers[TWrappers] : {
+    readonly type: TWrappers;
+};
+/**
+ * Signature of a lazy component loader — either a direct component class or
+ * an ES module whose `default` export is the component. Shared by field and
+ * wrapper registrations so the `loadComponent: () => import('./x.component')`
+ * idiom types cleanly in both places.
+ */
+type LazyComponentLoader<T = unknown> = () => Promise<Type<T> | {
+    default: Type<T>;
+}>;
+/**
+ * Configuration interface for registering wrapper types.
+ *
+ * Defines how a wrapper component is loaded and identified. Wrapper components
+ * provide visual decoration around field content (sections, headers, styling)
+ * without affecting the form data structure.
+ *
+ * @example
+ * ```typescript
+ * const SectionWrapper: WrapperTypeDefinition = {
+ *   name: 'section',
+ *   loadComponent: () => import('./section-wrapper.component').then(m => m.SectionWrapperComponent),
+ * };
+ * ```
+ */
+interface WrapperTypeDefinition<T extends WrapperConfig = WrapperConfig> {
+    /** Unique identifier for the wrapper type (also serves as discriminant from FieldTypeDefinition) */
+    wrapperName: string;
+    /** Wrapper definition type marker (internal use) */
+    _wrapper?: T;
+    /**
+     * Function to load the wrapper component (supports lazy loading).
+     * Returns a Promise that resolves to the component class or module with default export.
+     */
+    loadComponent: LazyComponentLoader;
+    /**
+     * Field types this wrapper should auto-apply to.
+     *
+     * When a field's `type` matches any entry, the wrapper is injected into that
+     * field's effective wrapper chain at the lowest priority (can be overridden
+     * by `FormConfig.defaultWrappers` or the field-level `wrappers` array, and
+     * fully cleared with `wrappers: null`).
+     */
+    types?: readonly string[];
+}
+/**
+ * Type guard for WrapperTypeDefinition.
+ *
+ * Discriminates via `wrapperName` — field types use `name`, wrapper types use `wrapperName`.
+ */
+declare function isWrapperTypeDefinition(value: unknown): value is WrapperTypeDefinition;
+/**
+ * Contract that wrapper components must satisfy.
+ *
+ * Each wrapper exposes a `#fieldComponent` ViewContainerRef where the inner
+ * content (next wrapper, or the field) is rendered imperatively. Config
+ * properties (minus `type`) are set on the component via `setInput`; a
+ * wrapper opts into a key by declaring a matching `input()`, and unknown
+ * keys are silently dropped. Wrappers may additionally declare a
+ * `fieldInputs` input for the wrapped field's mapper outputs (see
+ * `WrapperFieldInputs` for when that's undefined).
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <dbx-section [header]="header() ?? ''">
+ *       <ng-container #fieldComponent></ng-container>
+ *     </dbx-section>
+ *   `,
+ * })
+ * export class SectionWrapperComponent implements FieldWrapper {
+ *   readonly fieldComponent = viewChild.required('fieldComponent', { read: ViewContainerRef });
+ *   readonly header = input<string>();
+ *   readonly fieldInputs = input<WrapperFieldInputs>();
+ * }
+ * ```
+ */
+interface FieldWrapper {
+    /** ViewContainerRef slot where inner content is rendered */
+    readonly fieldComponent: Signal<ViewContainerRef>;
+}
+/**
+ * Injection token for the wrapper type registry.
+ *
+ * Provides access to the map of registered wrapper types. The registry is
+ * populated via `provideDynamicForm()` and used by `ContainerFieldComponent` to
+ * resolve wrapper types to their component implementations.
+ */
+declare const WRAPPER_REGISTRY: InjectionToken<Map<string, WrapperTypeDefinition<RowWrapper | _ng_forge_dynamic_forms.CssWrapper>>>;
+
 /**
  * Container field interface for wrapping child fields with UI chrome.
  *
@@ -3522,36 +3450,281 @@ interface RowWrapper {
  * };
  * ```
  */
-interface ContainerField<TFields extends readonly ContainerAllowedChildren[] = readonly ContainerAllowedChildren[], TWrapperConfigs extends readonly WrapperConfig[] = readonly WrapperConfig[]> extends FieldDef<never> {
-    type: 'container';
-    /** Child definitions to render within this container */
-    readonly fields: TFields;
+interface ContainerField<TFields extends readonly ContainerAllowedChildren[] = readonly ContainerAllowedChildren[], TWrapperConfigs extends readonly WrapperConfig[] = readonly WrapperConfig[]> extends FieldDef<never> {
+    type: 'container';
+    /** Child definitions to render within this container */
+    readonly fields: TFields;
+    /**
+     * Wrapper components to chain around the children.
+     * Applied outermost-first: the first wrapper in the array is the outermost.
+     * Each wrapper component receives the subsequent wrapper (or children) inside
+     * its `#fieldComponent` ViewContainerRef slot.
+     */
+    readonly wrappers: TWrapperConfigs;
+    /** Container fields do not have a label property */
+    readonly label?: never;
+    /** Containers do not support meta — they have no native form element */
+    readonly meta?: never;
+    /**
+     * Logic configurations for conditional container visibility.
+     * Only 'hidden' type logic is supported for containers.
+     */
+    readonly logic?: ContainerLogicConfig[];
+}
+/**
+ * Type guard for ContainerField with proper type narrowing.
+ *
+ * `wrappers` is part of the type but optional in practice — many configs use
+ * containers purely as flex/layout wrappers without any wrapper components.
+ * Match on `type === 'container'` and the `fields` shape only, mirroring
+ * `isPageField` / `isRowField`.
+ */
+declare function isContainerTypedField(field: FieldDef<any>): field is ContainerField;
+
+/**
+ * Type constraints for field nesting rules
+ * These ensure that container fields can only contain valid child field types
+ *
+ * Note: We explicitly list types instead of using Exclude to avoid circular dependencies
+ */
+/**
+ * Fields that are allowed as children of Page fields
+ * Pages can contain: rows, groups, arrays, and leaf fields (but NOT other pages)
+ */
+type PageAllowedChildren = LeafFieldTypes | RowField | GroupField | ArrayField | SimplifiedArrayField | ContainerField;
+/**
+ * Fields that are allowed as children of Group fields
+ * Groups can contain: rows and leaf fields (but NOT pages or other groups)
+ */
+type GroupAllowedChildren = LeafFieldTypes | RowField | ContainerField;
+/**
+ * Fields that are allowed as children of Array fields
+ * Arrays can contain: rows, groups, and leaf fields (but NOT pages or other arrays)
+ * Groups are used for creating object arrays where each array item is an object
+ */
+type ArrayAllowedChildren = LeafFieldTypes | RowField | GroupField | ContainerField;
+/**
+ * Fields that are allowed as children of Container fields.
+ * Containers are pure layout primitives that flatten their children into the
+ * parent form, so most registered field types may appear inside — including
+ * hidden fields and other containers — but NOT pages.
+ */
+type ContainerAllowedChildren = LeafFieldTypes | RowField | GroupField | ArrayField | SimplifiedArrayField | ContainerField;
+/**
+ * Row is a synthetic field type that resolves to a Container at runtime, so
+ * it accepts the same children as a Container.
+ */
+type RowAllowedChildren = ContainerAllowedChildren;
+
+/**
+ * An array item template is an array of allowed children that defines one OBJECT array item's fields.
+ * Used for object arrays where each item is `{ key1: value1, key2: value2, ... }`.
+ */
+type ArrayItemTemplate = readonly ArrayAllowedChildren[];
+/**
+ * An array item definition can be either:
+ * - A single field (ArrayAllowedChildren) for PRIMITIVE array items - extracts field value directly
+ * - An array of fields (ArrayItemTemplate) for OBJECT array items - merges fields into object
+ *
+ * This allows support for:
+ * - Primitive arrays: `['tag1', 'tag2']`
+ * - Object arrays: `[{ name: 'Alice', email: '...' }]`
+ * - Heterogeneous arrays: `[{ value: 'x' }, 'y']` (mixed primitives and objects)
+ */
+type ArrayItemDefinition = ArrayAllowedChildren | ArrayItemTemplate;
+/**
+ * Array field interface for creating dynamic field collections that map to array values.
+ *
+ * Key concepts:
+ * - The outer `fields` array defines INITIAL ITEMS (each element is one array item to render)
+ * - Each element can be either:
+ *   - A single FieldDef (primitive item) - the field's value is extracted directly
+ *   - An array of FieldDefs (object item) - fields are merged into an object
+ * - Items can have different field configurations (heterogeneous arrays supported)
+ * - Empty `fields: []` means no initial items - user adds via buttons with explicit templates
+ * - Initial values are declared via `value` property on each field definition
+ *
+ * @example
+ * // Primitive array: ['angular', 'typescript']
+ * {
+ *   key: 'tags',
+ *   type: 'array',
+ *   fields: [
+ *     { key: 'tag', type: 'input', value: 'angular' },      // Single field = primitive
+ *     { key: 'tag', type: 'input', value: 'typescript' },
+ *   ]
+ * }
+ *
+ * @example
+ * // Object array: [{ name: 'Alice', email: '...' }]
+ * {
+ *   key: 'contacts',
+ *   type: 'array',
+ *   fields: [
+ *     [                                                      // Array = object
+ *       { key: 'name', type: 'input', value: 'Alice' },
+ *       { key: 'email', type: 'input', value: 'alice@example.com' }
+ *     ],
+ *   ]
+ * }
+ *
+ * @example
+ * // Heterogeneous array: [{ label: 'Structured' }, 'Simple']
+ * {
+ *   key: 'items',
+ *   type: 'array',
+ *   fields: [
+ *     [{ key: 'label', type: 'input', value: 'Structured' }],  // Object item
+ *     { key: 'value', type: 'input', value: 'Simple' },        // Primitive item
+ *   ]
+ * }
+ *
+ * @example
+ * // Empty array (add items via buttons)
+ * {
+ *   key: 'tags',
+ *   type: 'array',
+ *   fields: []  // No initial items - user adds via button with template
+ * }
+ *
+ * Nesting constraints: Arrays can contain rows, leaf fields, or groups (for object arrays),
+ * but NOT pages or other arrays. Runtime validation enforces these rules.
+ *
+ * Note: Arrays are container fields and do not support `meta` since they have no native form element.
+ */
+interface ArrayField<TFields extends readonly ArrayItemDefinition[] = readonly ArrayItemDefinition[]> extends FieldDef<never> {
+    type: 'array';
+    /**
+     * Array of item definitions. Each element defines one array item:
+     * - Single FieldDef = primitive item (field's value is extracted directly)
+     * - Array of FieldDefs = object item (fields are merged into an object)
+     * - Empty array `[]` = no initial items (add via buttons with explicit templates)
+     * - Items can have different configurations (heterogeneous arrays supported)
+     * - Initial values are set via `value` property on each field definition
+     */
+    readonly fields: TFields;
+    /** Array fields do not have a label property **/
+    readonly label?: never;
+    /** Arrays do not support meta - they have no native form element **/
+    readonly meta?: never;
+    /**
+     * Logic configurations for conditional array visibility.
+     * Only 'hidden' type logic is supported for arrays.
+     */
+    readonly logic?: ContainerLogicConfig[];
+    /**
+     * Minimum number of items required in the array.
+     * Validation fails if the array has fewer items than this value.
+     */
+    readonly minLength?: number;
+    /**
+     * Maximum number of items allowed in the array.
+     * Validation fails if the array has more items than this value.
+     */
+    readonly maxLength?: number;
+}
+/**
+ * Type guard for ArrayField with proper type narrowing.
+ * Validates that the field is an array type with a fields property that is an array.
+ * Fields can contain either single FieldDefs (primitive items) or arrays of FieldDefs (object items).
+ */
+declare function isArrayField(field: FieldDef<any>): field is ArrayField;
+/**
+ * Configuration for auto-generated add/remove buttons in simplified array fields.
+ */
+interface ArrayButtonConfig {
+    /** Custom label for the button */
+    readonly label?: string;
+    /** Additional properties passed to the button component */
+    readonly props?: Record<string, unknown>;
+}
+/**
+ * Simplified array field interface for common use cases.
+ *
+ * Instead of manually specifying each item in `fields`, provide a `template` that defines
+ * the structure of a single item, and a `value` array with initial data.
+ * The library auto-generates add/remove buttons.
+ *
+ * Discriminant: `template` presence → simplified API; `Array.isArray(template)` → object vs primitive.
+ *
+ * @example
+ * // Primitive array: ['angular', 'typescript']
+ * {
+ *   key: 'tags',
+ *   type: 'array',
+ *   template: { key: 'value', type: 'input', label: 'Tag', required: true },
+ *   value: ['angular', 'typescript']
+ * }
+ *
+ * @example
+ * // Object array: [{ name: 'Jane', phone: '555' }]
+ * {
+ *   key: 'contacts',
+ *   type: 'array',
+ *   template: [
+ *     { key: 'name', type: 'input', label: 'Contact Name', required: true },
+ *     { key: 'phone', type: 'input', label: 'Phone Number' },
+ *   ],
+ *   value: [{ name: 'Jane', phone: '555' }]
+ * }
+ *
+ * @example
+ * // Button customization / opt-out
+ * {
+ *   key: 'tags',
+ *   type: 'array',
+ *   template: { key: 'value', type: 'input', label: 'Tag' },
+ *   addButton: { label: 'Add Tag', props: { color: 'primary' } },
+ *   removeButton: false
+ * }
+ */
+interface SimplifiedArrayField extends FieldDef<never> {
+    type: 'array';
     /**
-     * Wrapper components to chain around the children.
-     * Applied outermost-first: the first wrapper in the array is the outermost.
-     * Each wrapper component receives the subsequent wrapper (or children) inside
-     * its `#fieldComponent` ViewContainerRef slot.
+     * Template defining the structure of a single array item.
+     * - Single field (ArrayAllowedChildren) → primitive array (each item is a single value)
+     * - Array of fields (readonly ArrayAllowedChildren[]) → object array (each item is an object)
      */
-    readonly wrappers: TWrapperConfigs;
-    /** Container fields do not have a label property */
+    readonly template: ArrayAllowedChildren | readonly ArrayAllowedChildren[];
+    /** Initial values for the array. Each element creates one array item. */
+    readonly value?: readonly unknown[];
+    /**
+     * Configuration for the auto-generated "Add" button, or `false` to disable it.
+     * Defaults to a button with label "Add".
+     */
+    readonly addButton?: ArrayButtonConfig | false;
+    /**
+     * Configuration for the auto-generated "Remove" button on each item, or `false` to disable it.
+     * Defaults to a button with label "Remove".
+     */
+    readonly removeButton?: ArrayButtonConfig | false;
+    /** Simplified arrays do not support the label property */
     readonly label?: never;
-    /** Containers do not support meta — they have no native form element */
+    /** Simplified arrays do not support meta */
     readonly meta?: never;
     /**
-     * Logic configurations for conditional container visibility.
-     * Only 'hidden' type logic is supported for containers.
+     * Logic configurations for conditional array visibility.
+     * Only 'hidden' type logic is supported for arrays.
      */
     readonly logic?: ContainerLogicConfig[];
+    /**
+     * Minimum number of items required in the array.
+     * Validation fails if the array has fewer items than this value.
+     */
+    readonly minLength?: number;
+    /**
+     * Maximum number of items allowed in the array.
+     * Validation fails if the array has more items than this value.
+     */
+    readonly maxLength?: number;
+    /** Mutually exclusive with `template` — use `fields` for the full API instead */
+    readonly fields?: never;
 }
 /**
- * Type guard for ContainerField with proper type narrowing.
- *
- * `wrappers` is part of the type but optional in practice — many configs use
- * containers purely as flex/layout wrappers without any wrapper components.
- * Match on `type === 'container'` and the `fields` shape only, mirroring
- * `isPageField` / `isRowField`.
+ * Type guard for SimplifiedArrayField.
+ * Checks for `type: 'array'` with a `template` property (discriminant from full ArrayField).
  */
-declare function isContainerTypedField(field: FieldDef<any>): field is ContainerField;
+declare function isSimplifiedArrayField(field: FieldDef<any>): field is SimplifiedArrayField;
 
 /**
  * Container fields registry - augment this interface to add custom container fields
@@ -3701,180 +3874,6 @@ type NarrowField<T> = T extends {
  */
 type NarrowFields = readonly NarrowField<RegisteredFieldTypes>[];
 
-/**
- * Type constraints for field nesting rules
- * These ensure that container fields can only contain valid child field types
- *
- * Note: We explicitly list types instead of using Exclude to avoid circular dependencies
- */
-/**
- * Fields that are allowed as children of Page fields
- * Pages can contain: rows, groups, arrays, and leaf fields (but NOT other pages)
- */
-type PageAllowedChildren = LeafFieldTypes | RowField | GroupField | ArrayField | SimplifiedArrayField | ContainerField;
-/**
- * Fields that are allowed as children of Group fields
- * Groups can contain: rows and leaf fields (but NOT pages or other groups)
- */
-type GroupAllowedChildren = LeafFieldTypes | RowField | ContainerField;
-/**
- * Fields that are allowed as children of Array fields
- * Arrays can contain: rows, groups, and leaf fields (but NOT pages or other arrays)
- * Groups are used for creating object arrays where each array item is an object
- */
-type ArrayAllowedChildren = LeafFieldTypes | RowField | GroupField | ContainerField;
-/**
- * Fields that are allowed as children of Container fields.
- * Containers are pure layout primitives that flatten their children into the
- * parent form, so most registered field types may appear inside — including
- * hidden fields and other containers — but NOT pages.
- */
-type ContainerAllowedChildren = LeafFieldTypes | RowField | GroupField | ArrayField | SimplifiedArrayField | ContainerField;
-/**
- * Row is a synthetic field type that resolves to a Container at runtime, so
- * it accepts the same children as a Container.
- */
-type RowAllowedChildren = ContainerAllowedChildren;
-
-/**
- * Row field interface for creating horizontal layouts.
- * A row is a synthetic field type that resolves to a Container at runtime,
- * with a synthesized `{ type: 'row' }` wrapper applied for layout. The row
- * itself does not hold a value — its children flatten into the parent form.
- *
- * Note: Rows do not support `meta` since they have no native form element.
- */
-interface RowField<TFields extends readonly RowAllowedChildren[] = readonly RowAllowedChildren[]> extends FieldDef<never> {
-    type: 'row';
-    /** Child definitions to render within this row */
-    readonly fields: TFields;
-    /** Row fields do not have a label property **/
-    readonly label?: never;
-    /** Rows do not support meta - they have no native form element **/
-    readonly meta?: never;
-    /**
-     * Logic configurations for conditional row visibility.
-     * Only 'hidden' type logic is supported for rows.
-     */
-    readonly logic?: ContainerLogicConfig[];
-}
-/**
- * Type guard for RowField with proper type narrowing
- */
-declare function isRowField(field: FieldDef<any>): field is RowField;
-
-/**
- * Resolves a wrapper type name to its registered config interface.
- *
- * When `TWrappers` is a specific registered key (e.g., `'css'`), resolves to
- * the full config type from `FieldRegistryWrappers` (e.g., `CssWrapper`),
- * providing type-safe access to wrapper-specific properties like `cssClasses`.
- *
- * When `TWrappers` is the full `RegisteredWrapperTypes` union, distributes
- * to produce a discriminated union of all registered wrapper configs.
- *
- * @example
- * ```typescript
- * // Resolves to CssWrapper — cssClasses is typed
- * type CssConfig = WrapperConfig<'css'>;
- *
- * // Union of all registered wrapper configs
- * type AnyConfig = WrapperConfig;
- * ```
- */
-type WrapperConfig<TWrappers extends RegisteredWrapperTypes = RegisteredWrapperTypes> = TWrappers extends keyof FieldRegistryWrappers ? FieldRegistryWrappers[TWrappers] : {
-    readonly type: TWrappers;
-};
-/**
- * Signature of a lazy component loader — either a direct component class or
- * an ES module whose `default` export is the component. Shared by field and
- * wrapper registrations so the `loadComponent: () => import('./x.component')`
- * idiom types cleanly in both places.
- */
-type LazyComponentLoader<T = unknown> = () => Promise<Type<T> | {
-    default: Type<T>;
-}>;
-/**
- * Configuration interface for registering wrapper types.
- *
- * Defines how a wrapper component is loaded and identified. Wrapper components
- * provide visual decoration around field content (sections, headers, styling)
- * without affecting the form data structure.
- *
- * @example
- * ```typescript
- * const SectionWrapper: WrapperTypeDefinition = {
- *   name: 'section',
- *   loadComponent: () => import('./section-wrapper.component').then(m => m.SectionWrapperComponent),
- * };
- * ```
- */
-interface WrapperTypeDefinition<T extends WrapperConfig = WrapperConfig> {
-    /** Unique identifier for the wrapper type (also serves as discriminant from FieldTypeDefinition) */
-    wrapperName: string;
-    /** Wrapper definition type marker (internal use) */
-    _wrapper?: T;
-    /**
-     * Function to load the wrapper component (supports lazy loading).
-     * Returns a Promise that resolves to the component class or module with default export.
-     */
-    loadComponent: LazyComponentLoader;
-    /**
-     * Field types this wrapper should auto-apply to.
-     *
-     * When a field's `type` matches any entry, the wrapper is injected into that
-     * field's effective wrapper chain at the lowest priority (can be overridden
-     * by `FormConfig.defaultWrappers` or the field-level `wrappers` array, and
-     * fully cleared with `wrappers: null`).
-     */
-    types?: readonly string[];
-}
-/**
- * Type guard for WrapperTypeDefinition.
- *
- * Discriminates via `wrapperName` — field types use `name`, wrapper types use `wrapperName`.
- */
-declare function isWrapperTypeDefinition(value: unknown): value is WrapperTypeDefinition;
-/**
- * Contract that wrapper components must satisfy.
- *
- * Each wrapper exposes a `#fieldComponent` ViewContainerRef where the inner
- * content (next wrapper, or the field) is rendered imperatively. Config
- * properties (minus `type`) are set on the component via `setInput`; a
- * wrapper opts into a key by declaring a matching `input()`, and unknown
- * keys are silently dropped. Wrappers may additionally declare a
- * `fieldInputs` input for the wrapped field's mapper outputs (see
- * `WrapperFieldInputs` for when that's undefined).
- *
- * @example
- * ```typescript
- * @Component({
- *   template: `
- *     <dbx-section [header]="header() ?? ''">
- *       <ng-container #fieldComponent></ng-container>
- *     </dbx-section>
- *   `,
- * })
- * export class SectionWrapperComponent implements FieldWrapper {
- *   readonly fieldComponent = viewChild.required('fieldComponent', { read: ViewContainerRef });
- *   readonly header = input<string>();
- *   readonly fieldInputs = input<WrapperFieldInputs>();
- * }
- * ```
- */
-interface FieldWrapper {
-    /** ViewContainerRef slot where inner content is rendered */
-    readonly fieldComponent: Signal<ViewContainerRef>;
-}
-/**
- * Injection token for the wrapper type registry.
- *
- * Provides access to the map of registered wrapper types. The registry is
- * populated via `provideDynamicForm()` and used by `ContainerFieldComponent` to
- * resolve wrapper types to their component implementations.
- */
-declare const WRAPPER_REGISTRY: InjectionToken<Map<string, WrapperTypeDefinition<RowWrapper | _ng_forge_dynamic_forms.CssWrapper>>>;
-
 /**
  * Base interface for native HTML attributes that can be passed to form field elements.
  *
@@ -3974,18 +3973,26 @@ interface FieldDef<TProps, TMeta extends FieldMeta = FieldMeta> {
     /**
      * Field type identifier for component selection.
      *
-     * Determines which component will be rendered for this field.
-     * Must match a registered field type name in the field registry.
+     * Determines which component will be rendered for this field. Names
+     * registered through module augmentation of `DynamicFormFieldRegistry`
+     * are surfaced as IDE autocomplete suggestions via `RegisteredFieldTypes`;
+     * the `(string & {})` branch keeps arbitrary custom identifiers accepted
+     * as an escape hatch for fields that haven't been augmented into the
+     * registry.
      *
      * @example
      * ```typescript
-     * type: 'input'     // Text input field
-     * type: 'select'    // Dropdown selection
-     * type: 'checkbox'  // Boolean checkbox
-     * type: 'group'     // Field group container
+     * type: 'input'     // Text input field (registered)
+     * type: 'select'    // Dropdown selection (registered)
+     * type: 'checkbox'  // Boolean checkbox  (registered)
+     * type: 'group'     // Field group container (registered)
+     * type: 'my-custom' // Unregistered — still accepted, no autocomplete
      * ```
+     *
+     * Wrapper types are intentionally excluded — wrappers are configured through
+     * `wrappers` / `withFormWrappers()` rather than via the field-type discriminant.
      */
-    type: string;
+    type: RegisteredFieldTypes['type'] | (string & {});
     /**
      * Human-readable field label displayed to users.
      *
@@ -4374,7 +4381,7 @@ interface FieldTypeDefinition<T extends FieldDef<any> = any> {
     /** Semantic scope for tooling to discover interchangeable field alternatives */
     scope?: FieldScope | FieldScope[];
     /** Mapped component inputs that must exist before the renderer instantiates the component */
-    renderReadyWhen?: RenderReadyInput[];
+    renderReadyWhen?: readonly RenderReadyInput[];
 }
 /**
  * Injection token for the global field type registry.
@@ -4403,6 +4410,15 @@ interface ResolvedField {
     injector: Injector;
     inputs: Signal<Record<string, unknown>>;
     renderReady: Signal<boolean>;
+    /**
+     * Whether the field is currently hidden. Sourced from the FieldTree's
+     * `state.hidden()` for value-bearing fields (set by Angular Signal Forms in
+     * response to `hidden(path, …)` calls), or from the mapper's explicit
+     * `hidden` input for non-value fields (button, text, container, …). Consumers
+     * must `@if (!field.hidden())` around `*dfFieldOutlet` so hidden fields are
+     * removed from the DOM — Angular Signal Forms warns (NG01916) otherwise.
+     */
+    hidden: Signal<boolean>;
 }
 
 /**
@@ -6495,8 +6511,6 @@ declare function applyMetaToElement(element: Element, meta: FieldMeta | undefine
  * );
  * // user.value() keeps the old user data during loading transitions
  * ```
- *
- * @experimental Uses Angular's experimental resource composition APIs.
  */
 declare function withPreviousValue<T>(input: Resource<T>): Resource<T>;
 
@@ -6615,6 +6629,12 @@ interface ResolvedArrayItemField {
     inputs: Signal<Record<string, unknown>>;
     /** Whether required mapped inputs are available for safe component instantiation. */
     renderReady: Signal<boolean>;
+    /**
+     * Whether the array-item field is currently hidden — mirrors `ResolvedField.hidden`
+     * so the same `@if (!field.hidden())` template gate works for top-level and
+     * array-item fields.
+     */
+    hidden: Signal<boolean>;
 }
 /**
  * Resolved array item ready for declarative rendering with ngComponentOutlet.
@@ -6645,7 +6665,9 @@ declare class ArrayFieldComponent<TModel extends Record<string, unknown> = Recor
     protected readonly environmentInjector: EnvironmentInjector;
     private readonly eventBus;
     private readonly logger;
-    private readonly templateRegistry;
+    private readonly arrayItemRegistry;
+    private readonly slot;
+    /** Bound id-generator reference threaded to `resolveArrayItem` so callsites stay terse. */
     private readonly generateItemId;
     field: _angular_core.InputSignal<ArrayField<readonly ArrayItemDefinition[]>>;
     key: _angular_core.InputSignal<string>;
@@ -6710,9 +6732,7 @@ declare class ArrayFieldComponent<TModel extends Record<string, unknown> = Recor
     private readonly itemTemplates;
     private readonly arrayFieldTrees;
     private readonly resolvedItemsSignal;
-    private readonly updateVersion;
-    private readonly pendingInitializationCycle;
-    private readonly settledInitializationCycle;
+    private readonly fsm;
     /**
      * Map of item IDs to their current positions. O(1) lookup vs O(n) indexOf().
      * Used by child linkedSignals to reactively track their position in the array.