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

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

@@ -1,13 +1,155 @@
 import * as rxjs from 'rxjs';
 import { Observable } from 'rxjs';
 import * as _angular_core from '@angular/core';
-import { Signal, ResourceRef, Type, ViewContainerRef, InjectionToken, Injector, WritableSignal, EnvironmentInjector, Provider, EnvironmentProviders, Resource, PipeTransform } from '@angular/core';
+import { Signal, Type, ResourceRef, ViewContainerRef, InjectionToken, Injector, WritableSignal, EnvironmentInjector, Provider, EnvironmentProviders, TemplateRef, Resource, PipeTransform } from '@angular/core';
 import * as _ng_forge_dynamic_forms from '@ng-forge/dynamic-forms';
 import * as _angular_forms_signals from '@angular/forms/signals';
 import { FieldContext, TreeValidationResult, ValidationError as ValidationError$1, FieldTree, SchemaPath, SchemaPathTree } from '@angular/forms/signals';
 import { FormSchema } from '@ng-forge/dynamic-forms/schema';
 import * as _angular_forms from '@angular/forms';
 
+type DynamicText = string | Observable<string> | Signal<string>;
+
+/**
+ * Generic reactive value — a static value, an Angular Signal, or an RxJS Observable.
+ *
+ * Generalises {@link DynamicText} for arbitrary value types. Used by
+ * cross-cutting properties that need to react to form state without forcing
+ * every consumer to deal with reactivity (e.g., `hidden` / `disabled` on
+ * addons).
+ *
+ * @example
+ * ```typescript
+ * const a: DynamicValue<boolean> = true;
+ * const b: DynamicValue<boolean> = signal(false);
+ * const c: DynamicValue<boolean> = isValid$;
+ * ```
+ */
+type DynamicValue<T> = T | Signal<T> | Observable<T>;
+
+/**
+ * Universal addon slot names supported by every adapter.
+ *
+ * Adapters render `prefix` to the leading edge of a field and `suffix` to
+ * the trailing edge (mirrored in RTL). Additional slots may be contributed
+ * via {@link DynamicFormAddonSlotRegistry} module augmentation.
+ */
+type CommonAddonSlot = 'prefix' | 'suffix';
+/**
+ * Module-augmentable registry of adapter-specific addon slot names.
+ *
+ * Adapters that expose slots beyond the universal `prefix` / `suffix` (e.g.,
+ * an "error overlay" slot specific to one design system) declare them here.
+ *
+ * @example
+ * ```typescript
+ * declare module '@ng-forge/dynamic-forms' {
+ *   interface DynamicFormAddonSlotRegistry {
+ *     'mat-error-overlay': true;
+ *   }
+ * }
+ * ```
+ */
+interface DynamicFormAddonSlotRegistry {
+}
+/**
+ * Union of every valid addon slot — universal slots plus any registered via
+ * {@link DynamicFormAddonSlotRegistry} module augmentation.
+ */
+type AddonSlot = CommonAddonSlot | keyof DynamicFormAddonSlotRegistry;
+
+/**
+ * Base shape every addon kind extends.
+ *
+ * Public contract:
+ * - `slot` chooses where the addon renders (prefix / suffix / adapter-specific).
+ * - `hidden` / `disabled` are reactive — re-evaluated when their underlying
+ *   signals or observables emit.
+ * - Multiple addons in the same slot render in array order, left-to-right
+ *   within the slot (LTR; mirrored in RTL).
+ *
+ * Note: `meta` is intentionally absent — adapters declare addon-specific
+ * fields via module augmentation rather than an untyped escape hatch.
+ */
+interface BaseAddon<TSlot extends AddonSlot = AddonSlot> {
+    /** Slot to render this addon in. */
+    readonly slot: TSlot;
+    /** CSS class applied to the addon host element. */
+    readonly className?: string;
+    /** Reactive visibility — when `true`, the addon is removed from layout. */
+    readonly hidden?: DynamicValue<boolean>;
+    /** Reactive disabled state — primarily relevant for interactive kinds. */
+    readonly disabled?: DynamicValue<boolean>;
+}
+/**
+ * Module-augmentable registry of addon kinds.
+ *
+ * Each key is the kind discriminant; each value is the addon's full shape
+ * (extending {@link BaseAddon}). Core ships `text`, `template`, and
+ * `component`; adapters add their own (e.g., `prime-icon`, `prime-button`).
+ *
+ * @example
+ * ```typescript
+ * declare module '@ng-forge/dynamic-forms' {
+ *   interface DynamicFormAddonRegistry {
+ *     'prime-icon': PrimeIconAddon;
+ *     'prime-button': PrimeButtonAddon;
+ *   }
+ * }
+ * ```
+ */
+interface DynamicFormAddonRegistry {
+    text: TextAddon;
+    template: TemplateAddon;
+    component: ComponentAddon;
+}
+/**
+ * Union of every registered addon shape.
+ */
+type AnyAddon = DynamicFormAddonRegistry[keyof DynamicFormAddonRegistry];
+/**
+ * Renders text content inline.
+ *
+ * `text` is `DynamicText`, supporting plain strings, observables, and
+ * signals — so values like `'$'`, `'.com'`, or interpolated counters
+ * (`'42/100'`) all work uniformly.
+ */
+interface TextAddon extends BaseAddon {
+    readonly kind: 'text';
+    readonly text: DynamicText;
+}
+/**
+ * Renders a named `<ng-template>` projected into the host `<df-dynamic-form>`.
+ *
+ * JSON-safe — backends ship the key, FE supplies the template definition.
+ * Use the `templateAddon(ref)` helper for rename-safe authoring in code.
+ */
+interface TemplateAddon extends BaseAddon {
+    readonly kind: 'template';
+    readonly templateKey: string;
+}
+/**
+ * Renders an arbitrary Angular component as the addon body.
+ *
+ * The loader returns either a component class directly or a module with a
+ * `default` export. For non-default exports, unwrap with `.then(m => m.X)`:
+ *
+ * ```ts
+ * { kind: 'component', component: () => import('./my').then(m => m.MyComponent) }
+ * ```
+ *
+ * @codeOnly The `component` loader is a function and cannot survive
+ * `JSON.stringify`/`parse`. The lenient validator drops this kind when the
+ * config originated from JSON (set via `sanitizeFormConfig({ source: 'json' })`).
+ */
+interface ComponentAddon extends BaseAddon {
+    readonly kind: 'component';
+    readonly component: () => Promise<Type<unknown> | {
+        default: Type<unknown>;
+    }>;
+    readonly inputs?: Record<string, unknown>;
+}
+
 type WithInputSignals<T> = {
     readonly [K in keyof T]-?: Signal<T[K]>;
 };
@@ -725,19 +867,32 @@ type Widen<T, D extends number = 5> = [D] extends [never] ? T : T extends string
     -readonly [K in keyof T]: Widen<T[K], Depth[D]>;
 } : T;
 /**
- * Infer value type based on field type and props.
- * - Slider fields: always number
- * - Input fields with props.type: 'number': number
- * - Other fields: widen the literal value type
+ * Resolves the "underlying" non-null value type for a field, based on its `type`
+ * discriminator and (where it matters) its `value` literal. Used when we need a
+ * base type independent of whether the literal happens to be `null` — i.e., when
+ * computing the nullable widening for `value: null, nullable: true`.
  */
-type InferValueType<T, V> = T extends {
+type ResolveBaseValueType<T, V> = T extends {
     type: 'slider';
 } ? number : T extends {
     type: 'input';
     props: {
         type: 'number';
     };
-} ? number : Widen<V>;
+} ? number : T extends {
+    type: 'checkbox' | 'toggle';
+} ? boolean : [V] extends [null] ? string : Widen<V>;
+/**
+ * Infer value type based on field type, value literal, and the `nullable` flag.
+ * - Slider fields: always number
+ * - Input fields with props.type: 'number': number
+ * - Checkbox / toggle fields: always boolean
+ * - Other fields: widen the literal value type (default to string when value is null)
+ * - When `nullable: true` is declared, widens the result to `T | null`.
+ */
+type InferValueType<T, V> = T extends {
+    nullable: true;
+} ? ResolveBaseValueType<T, V> | null : ResolveBaseValueType<T, V>;
 /**
  * Make type optional if field is not required.
  * Hidden fields are never optional since they require a value property.
@@ -749,9 +904,11 @@ type MaybeOptional<T, V> = T extends {
 } ? V : V | undefined;
 /**
  * Infers the value type from a single template field (for primitive arrays).
- * Mirrors InferValueType logic: slider → number, input[number] → number, else string.
+ * Mirrors InferValueType logic: slider → number, input[number] → number,
+ * checkbox/toggle → boolean, else widen `value` (string fallback). Widens to
+ * `T | null` when `nullable: true` is declared on the template field.
  */
-type InferSingleTemplateValue<T, D extends number> = T extends {
+type InferSingleTemplateValueBase<T, D extends number> = T extends {
     type: 'slider';
 } ? number : T extends {
     type: 'input';
@@ -762,7 +919,10 @@ type InferSingleTemplateValue<T, D extends number> = T extends {
     type: 'checkbox' | 'toggle';
 } ? boolean : T extends {
     value: infer V;
-} ? Widen<V, Depth[D]> : string;
+} ? [V] extends [null] ? string : Widen<V, Depth[D]> : string;
+type InferSingleTemplateValue<T, D extends number> = T extends {
+    nullable: true;
+} ? InferSingleTemplateValueBase<T, D> | null : InferSingleTemplateValueBase<T, D>;
 /**
  * Infers the value type for an array field.
  * Handles four cases:
@@ -810,7 +970,9 @@ type ProcessField<T, D extends number = 5> = [D] extends [never] ? Record<string
 } : never : T extends {
     key: infer K;
 } ? K extends string ? {
-    [P in K]: MaybeOptional<T, string>;
+    [P in K]: MaybeOptional<T, T extends {
+        nullable: true;
+    } ? string | null : string>;
 } : never : never;
 /**
  * Internal helper with depth tracking
@@ -2098,8 +2260,6 @@ interface SchemaDefinition {
     subSchemas?: SchemaApplicationConfig[];
 }
 
-type DynamicText = string | Observable<string> | Signal<string>;
-
 /**
  * Re-export Angular's ValidationError for consistency
  * This replaces our custom ValidationError interface
@@ -4195,6 +4355,24 @@ interface FieldDef<TProps, TMeta extends FieldMeta = FieldMeta> {
      * and any field-level `wrappers`.
      */
     skipDefaultWrappers?: boolean;
+    /**
+     * Addons rendered inside this field's slots (typically `prefix` / `suffix`).
+     *
+     * Each addon declares its kind, slot, and kind-specific configuration.
+     * Whether a field type accepts addons — and which slots / kinds — is
+     * declared at registration via `FieldTypeDefinition.addons`. Field types
+     * without that registration ("Tier 3", e.g., toggle, radio) drop any
+     * `addons` value with a lenient warning at config init.
+     *
+     * @example
+     * ```typescript
+     * addons: [
+     *   { slot: 'prefix', kind: 'prime-icon', icon: 'search' },
+     *   { slot: 'suffix', kind: 'prime-button', preset: 'clear', ariaLabel: 'Clear' },
+     * ]
+     * ```
+     */
+    addons?: ReadonlyArray<AnyAddon>;
 }
 type IncludedKeys = 'label' | 'className' | 'hidden' | 'tabIndex';
 /**
@@ -4289,6 +4467,103 @@ interface GroupContext {
  */
 type MapperFn<T extends FieldDef<unknown>> = (input: T) => Signal<Record<string, unknown>>;
 
+/**
+ * Minimal JSON Schema fragment used by the MCP server to surface an addon
+ * kind's shape to AI form generators. Covers the common subset
+ * (`type`/`properties`/`required`/`enum`/etc.) without pulling in a full JSON
+ * Schema dependency. Extra keys are allowed via the `[key: string]` index so
+ * vendor-specific annotations (`x-foo`, `markdownDescription`) still typecheck.
+ *
+ * Tooling-only: the runtime addon validator does NOT consult `schema` — it
+ * relies on each kind's `validate?(addon, fieldKey)` callback for shape
+ * enforcement. `schema` exists exclusively so the MCP server (and any other
+ * AI-driven form authoring tool) can describe the kind to a model without
+ * hand-maintaining a parallel registry.
+ */
+interface AddonKindSchema {
+    readonly $ref?: string;
+    readonly $schema?: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly type?: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null' | ReadonlyArray<'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'>;
+    readonly enum?: ReadonlyArray<unknown>;
+    readonly const?: unknown;
+    readonly properties?: Readonly<Record<string, AddonKindSchema>>;
+    readonly required?: ReadonlyArray<string>;
+    readonly additionalProperties?: boolean | AddonKindSchema;
+    readonly items?: AddonKindSchema | ReadonlyArray<AddonKindSchema>;
+    readonly oneOf?: ReadonlyArray<AddonKindSchema>;
+    readonly anyOf?: ReadonlyArray<AddonKindSchema>;
+    readonly allOf?: ReadonlyArray<AddonKindSchema>;
+    readonly not?: AddonKindSchema;
+    readonly default?: unknown;
+    readonly examples?: ReadonlyArray<unknown>;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+    readonly format?: string;
+    /** Vendor extensions and unrecognised keywords pass through untyped. */
+    readonly [key: string]: unknown;
+}
+/**
+ * Optional shape validator a kind ships to enforce its required fields at
+ * runtime. Throws are caught by the validator and converted into lenient
+ * warnings; the offending addon is dropped and the form keeps rendering.
+ */
+type AddonShapeValidator<T extends BaseAddon = BaseAddon> = (addon: T, fieldKey: string) => void;
+/**
+ * Per-kind registration metadata.
+ *
+ * Registered via `withCustomAddon(...)` features (or adapter feature
+ * helpers like `withPrimeNGAddons()`); resolved at render time by
+ * `<df-addon-slot>`.
+ */
+interface AddonKindDefinition<T extends BaseAddon = BaseAddon> {
+    /** Discriminant matching `addon.kind`. */
+    readonly kind: string;
+    /** Lazy loader for the kind's renderer component. */
+    readonly loadComponent: LazyComponentLoader;
+    /** Optional shape validator — throw `DynamicFormError` to drop the addon with a warning. */
+    readonly validate?: AddonShapeValidator<T>;
+    /** Optional JSON Schema fragment for MCP / pre-flight tooling. */
+    readonly schema?: AddonKindSchema;
+    /**
+     * Whether the kind survives `JSON.stringify` / `JSON.parse`. Kinds whose
+     * shape includes a function payload (e.g., the built-in `'component'`
+     * loader, inline `prime-button` `action` handlers) declare `jsonSafe: false`
+     * so the validator drops them when the config was loaded from a JSON
+     * source (`sanitizeFormConfig(config, { source: 'json' })`). Defaults to
+     * `true` — kinds are JSON-safe unless explicitly opted out.
+     */
+    readonly jsonSafe?: boolean;
+}
+/**
+ * Per-field-type addon-support metadata declared at field registration.
+ *
+ * Source of truth for the runtime validator: which slots are valid for a
+ * field type, which kinds are accepted (optional whitelist).
+ *
+ * Field types that do not declare `addons` on their `FieldTypeDefinition`
+ * are treated as Tier 3 — addons configured on such fields are dropped
+ * with a warning at config init.
+ */
+interface FieldAddonSupport {
+    /** Slots a field of this type accepts. */
+    readonly slots: readonly AddonSlot[];
+    /** Optional whitelist of allowed addon kinds. Omitted = any registered kind. */
+    readonly allowedKinds?: readonly string[];
+}
+/**
+ * Global registry of addon kinds.
+ *
+ * Populated by `withCustomAddon(...)` features and adapter feature helpers
+ * (e.g., `withPrimeNGAddons()`). Read by `<df-addon-slot>` to resolve a
+ * kind discriminant to its renderer component.
+ */
+declare const ADDON_KIND_REGISTRY: InjectionToken<Map<string, AddonKindDefinition<BaseAddon<AddonSlot>>>>;
+
 /**
  * Defines how a field type handles form values and data collection.
  *
@@ -4382,6 +4657,23 @@ interface FieldTypeDefinition<T extends FieldDef<any> = any> {
     scope?: FieldScope | FieldScope[];
     /** Mapped component inputs that must exist before the renderer instantiates the component */
     renderReadyWhen?: readonly RenderReadyInput[];
+    /**
+     * Declares which addon slots this field accepts and (optionally) the
+     * subset of kinds allowed.
+     *
+     * Source of truth for the runtime addon validator. Field types that
+     * omit this property are treated as Tier 3 — any `addons` configured
+     * on such a field are dropped with a warning at config init.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   name: 'prime-input',
+     *   addons: { slots: ['prefix', 'suffix'] },
+     * }
+     * ```
+     */
+    addons?: FieldAddonSupport;
 }
 /**
  * Injection token for the global field type registry.
@@ -4626,12 +4918,22 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
     formOptions: _angular_core.InputSignal<FormOptions | undefined>;
     /** Form values for two-way data binding. */
     value: _angular_core.ModelSignal<Partial<TModel> | undefined>;
+    /**
+     * How lenient the addon validator is on `config.fields[...].addons`.
+     * `'inline'` (default) keeps everything; `'json'` drops code-only kinds
+     * with a warning. Read at form init and on every config swap — change
+     * `source` AND the config to force re-validation mid-flight.
+     */
+    source: _angular_core.InputSignal<"json" | "inline">;
     private destroyRef;
     private injector;
     protected environmentInjector: EnvironmentInjector;
     private eventBus;
     private logger;
     private dispatcher;
+    private templateRegistry;
+    /** All `<ng-template dfTemplate="...">` instances projected into this form. */
+    private readonly _projectedTemplates;
     /** State manager that owns all form state. Initialized via connectDeps() to guarantee
      * FORM_STATE_DEPS is populated before FormStateManager is injected. */
     private readonly stateManager;
@@ -4745,7 +5047,7 @@ declare class DynamicForm<TFields extends RegisteredFieldTypes[] = RegisteredFie
     private connectDeps;
     private setupEventHandlers;
     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>;
+    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; }; "source": { "alias": "source"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "validityChange": "validityChange"; "dirtyChange": "dirtyChange"; "submitted": "submitted"; "reset": "reset"; "cleared": "cleared"; "events": "events"; "initialized": "initialized"; "onPageChange": "onPageChange"; "onPageNavigationStateChange": "onPageNavigationStateChange"; }, ["_projectedTemplates"], never, true, never>;
 }
 
 declare class EventBus {
@@ -4920,178 +5222,99 @@ interface DynamicFormFeature<TKind extends string = string> {
     ɵproviders: Provider[];
 }
 
-interface FieldOption<T = unknown> {
-    label: DynamicText;
-    value: T;
-    disabled?: boolean;
-    [key: string]: unknown;
-}
-
 /**
- * Injection token for form-level default wrappers.
- *
- * Provides a Signal of the `defaultWrappers` array from FormConfig. Consumed by
- * `DfFieldOutlet` / `ContainerFieldComponent` to merge into each field's
- * effective wrapper chain (lowest priority after auto-associations, higher
- * than field-level `wrappers`).
+ * User-facing wrapper registration shape used with `createWrappers(...)`.
  *
- * Provided once at the DynamicForm level and inherited via Angular's
- * hierarchical injector.
+ * Extends `WrapperTypeDefinition` with an optional `props` field that
+ * carries the wrapper's config type (via `wrapperProps`) for later
+ * inference by `InferWrapperRegistry`.
  */
-declare const DEFAULT_WRAPPERS: InjectionToken<Signal<readonly WrapperConfig[] | undefined>>;
+interface WrapperRegistration<TName extends string = string, TConfig = unknown> {
+    /** Unique identifier for the wrapper type */
+    readonly wrapperName: TName;
+    /** Lazy-loader for the wrapper component */
+    readonly loadComponent: LazyComponentLoader;
+    /** Field types this wrapper auto-applies to (merged lowest-priority during wrapper resolution) */
+    readonly types?: readonly string[];
+    /**
+     * Type carrier only — runtime value is always `undefined`.
+     * Use `wrapperProps<YourConfig>()` to thread the config type.
+     */
+    readonly props?: TConfig;
+}
 /**
- * Injection token for providing field signal context to mappers and components.
- *
- * The field signal context is the "nervous system" of the dynamic form library,
- * providing access to:
- * - The form instance and structure
- * - Current form values (as signals)
- * - Default values
- * - Validation messages
- * - The injector for creating components
+ * Branded bundle returned by `createWrappers(...)`.
  *
- * This token is provided by the DynamicForm component and can be scoped
- * for nested forms (Groups, Arrays) via child injectors.
+ * Carries:
+ * - `ɵkind: 'wrappers'` — discriminant recognised by `provideDynamicForm(...)`
+ * - `ɵregistrations` — the original registrations (type-level use for `InferWrapperRegistry`)
+ * - `ɵdefinitions` — the `WrapperTypeDefinition[]` extracted for `WRAPPER_REGISTRY`
+ */
+interface WrappersBundle<T extends readonly WrapperRegistration[] = readonly WrapperRegistration[]> {
+    readonly ɵkind: 'wrappers';
+    readonly ɵregistrations: T;
+    readonly ɵdefinitions: readonly WrapperTypeDefinition[];
+}
+/**
+ * Bundle wrapper registrations into a single object that can be passed to
+ * `provideDynamicForm(...)`.
  *
  * @example
  * ```typescript
- * // In a mapper function
- * export function mapValueField(fieldDef: BaseValueField<any, any>): Binding[] {
- *   const context = inject(FIELD_SIGNAL_CONTEXT);
- *   const form = context.form();
- *   // ... use context
- * }
+ * const appWrappers = createWrappers(
+ *   {
+ *     wrapperName: 'section',
+ *     loadComponent: () => import('./section-wrapper'),
+ *     props: wrapperProps<SectionWrapper>(),
+ *   },
+ *   {
+ *     wrapperName: 'highlight',
+ *     loadComponent: () => import('./highlight-wrapper'),
+ *     types: ['input', 'select'],
+ *     props: wrapperProps<HighlightWrapper>(),
+ *   },
+ * );
  *
- * // In a component
- * export class MyFieldComponent {
- *   private context = inject(FIELD_SIGNAL_CONTEXT);
+ * declare module '@ng-forge/dynamic-forms' {
+ *   interface FieldRegistryWrappers extends InferWrapperRegistry<typeof appWrappers> {}
  * }
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideDynamicForm(appWrappers)],
+ * });
  * ```
  */
-declare const FIELD_SIGNAL_CONTEXT: InjectionToken<FieldSignalContext<Record<string, unknown>>>;
+declare function createWrappers<const T extends readonly WrapperRegistration[]>(...registrations: T): WrappersBundle<T>;
+/** Type guard for a `WrappersBundle`. */
+declare function isWrappersBundle(value: unknown): value is WrappersBundle;
 /**
- * Injection token for providing array context metadata to mappers and components.
- *
- * This token is optionally provided by ArrayFieldComponent when creating injectors
- * for array items. It contains metadata about the array item's position and parent.
+ * Derive the `FieldRegistryWrappers` augmentation shape from a wrapper bundle.
  *
- * Mappers can inject this token with {optional: true} to access array context:
+ * Maps each registration's `wrapperName` to its `props` type (the config carried
+ * by `wrapperProps<T>()`). If a registration has no `props`, falls back to the
+ * minimal discriminant shape `{ readonly type: wrapperName }`.
  *
  * @example
  * ```typescript
- * // In a mapper function
- * export function buttonMapper(fieldDef: FieldDef<any>): Binding[] {
- *   const arrayContext = inject(ARRAY_CONTEXT, { optional: true });
- *   if (arrayContext) {
- *     // Use arrayContext.index, arrayContext.arrayKey, etc.
- *   }
+ * declare module '@ng-forge/dynamic-forms' {
+ *   interface FieldRegistryWrappers extends InferWrapperRegistry<typeof appWrappers> {}
  * }
  * ```
  */
-declare const ARRAY_CONTEXT: InjectionToken<ArrayContext>;
+type InferWrapperRegistry<T> = T extends WrappersBundle<infer R> ? {
+    [Reg in R[number] as Reg['wrapperName']]: Reg extends {
+        props: infer P;
+    } ? Exclude<P, undefined> : {
+        readonly type: Reg['wrapperName'];
+    };
+} : never;
+
 /**
- * Injection token for providing group ancestry to mappers and components.
- *
- * Re-provided in two places:
- * 1. `GroupFieldComponent` provides a context whose `groupPath()` is the
- *    parent path extended by its own key (e.g. `'address'` or `'user.address'`).
- * 2. `createArrayItemInjector` provides a sentinel with an empty `groupPath`,
- *    resetting the chain at array boundaries — descendants of an array item
- *    that re-enter a group compose paths INSIDE the array item, matching the
- *    property-derivation collector's keying.
- *
- * `mapFieldToInputs` reads this to scope DOM IDs and override-store keys so
- * the same leaf key can appear in different groups without colliding (#401).
- *
- * Inject with `{ optional: true }` because top-level fields with no group
- * ancestor (and no enclosing array) won't have the token provided. The token
- * IS present for fields inside an array even when no inner group exists — the
- * array-boundary sentinel makes injection succeed with an empty `groupPath`.
+ * 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 const GROUP_CONTEXT: InjectionToken<GroupContext>;
-/**
- * Injection token for form-level default props.
- *
- * Default props are form-wide property defaults that are merged with field-level props.
- * Field props take precedence over default props.
- *
- * Unlike FIELD_SIGNAL_CONTEXT which is re-provided by container components (Group, Array),
- * DEFAULT_PROPS is provided ONCE at the DynamicForm level and inherited by all children
- * via Angular's hierarchical injector.
- *
- * The token provides a Signal to enable reactivity - when config changes, mappers
- * that read the signal inside their computed() will automatically update.
- *
- * @example
- * ```typescript
- * // In a mapper function
- * const defaultPropsSignal = inject(DEFAULT_PROPS);
- *
- * return computed(() => {
- *   const defaultProps = defaultPropsSignal?.();  // Read inside computed for reactivity
- *   const baseInputs = buildBaseInputs(fieldDef, defaultProps);
- *   // ...
- * });
- * ```
- */
-declare const DEFAULT_PROPS: InjectionToken<Signal<Record<string, unknown> | undefined>>;
-/**
- * Injection token for form-level default validation messages.
- *
- * Default validation messages act as fallbacks when fields have validation
- * errors but no field-level `validationMessages` defined.
- *
- * Like DEFAULT_PROPS, this token is provided ONCE at the DynamicForm level
- * and inherited by all children via Angular's hierarchical injector.
- *
- * The token provides a Signal to enable reactivity - when config changes, mappers
- * that read the signal inside their computed() will automatically update.
- *
- * @example
- * ```typescript
- * // In a mapper or component
- * const defaultMessagesSignal = inject(DEFAULT_VALIDATION_MESSAGES);
- *
- * return computed(() => {
- *   const defaultMessages = defaultMessagesSignal?.();  // Read inside computed for reactivity
- *   const message = defaultMessages?.required ?? 'Field is required';
- *   // ...
- * });
- * ```
- */
-declare const DEFAULT_VALIDATION_MESSAGES: InjectionToken<Signal<ValidationMessages | undefined>>;
-/**
- * Injection token for form-level options.
- *
- * Form options control form-wide behavior including button disabled states.
- * Used by button mappers to determine default disabled behavior.
- *
- * Like DEFAULT_PROPS, this token is provided ONCE at the DynamicForm level
- * and inherited by all children via Angular's hierarchical injector.
- *
- * The token provides a Signal to enable reactivity - when config changes, mappers
- * that read the signal inside their computed() will automatically update.
- *
- * @example
- * ```typescript
- * // In a button mapper
- * const formOptionsSignal = inject(FORM_OPTIONS);
- *
- * return computed(() => {
- *   const formOptions = formOptionsSignal?.();  // Read inside computed for reactivity
- *   const disableWhenInvalid = formOptions?.submitButton?.disableWhenInvalid ?? true;
- *   // ...
- * });
- * ```
- */
-declare const FORM_OPTIONS: InjectionToken<Signal<FormOptions | undefined>>;
-
-/**
- * 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;
+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.
@@ -5128,93 +5351,6 @@ type FieldPathAccess<TValue> = {
     [K in keyof TValue]: SchemaPath<TValue[K]> | SchemaPathTree<TValue[K]>;
 };
 
-/**
- * User-facing wrapper registration shape used with `createWrappers(...)`.
- *
- * Extends `WrapperTypeDefinition` with an optional `props` field that
- * carries the wrapper's config type (via `wrapperProps`) for later
- * inference by `InferWrapperRegistry`.
- */
-interface WrapperRegistration<TName extends string = string, TConfig = unknown> {
-    /** Unique identifier for the wrapper type */
-    readonly wrapperName: TName;
-    /** Lazy-loader for the wrapper component */
-    readonly loadComponent: LazyComponentLoader;
-    /** Field types this wrapper auto-applies to (merged lowest-priority during wrapper resolution) */
-    readonly types?: readonly string[];
-    /**
-     * Type carrier only — runtime value is always `undefined`.
-     * Use `wrapperProps<YourConfig>()` to thread the config type.
-     */
-    readonly props?: TConfig;
-}
-/**
- * Branded bundle returned by `createWrappers(...)`.
- *
- * Carries:
- * - `ɵkind: 'wrappers'` — discriminant recognised by `provideDynamicForm(...)`
- * - `ɵregistrations` — the original registrations (type-level use for `InferWrapperRegistry`)
- * - `ɵdefinitions` — the `WrapperTypeDefinition[]` extracted for `WRAPPER_REGISTRY`
- */
-interface WrappersBundle<T extends readonly WrapperRegistration[] = readonly WrapperRegistration[]> {
-    readonly ɵkind: 'wrappers';
-    readonly ɵregistrations: T;
-    readonly ɵdefinitions: readonly WrapperTypeDefinition[];
-}
-/**
- * Bundle wrapper registrations into a single object that can be passed to
- * `provideDynamicForm(...)`.
- *
- * @example
- * ```typescript
- * const appWrappers = createWrappers(
- *   {
- *     wrapperName: 'section',
- *     loadComponent: () => import('./section-wrapper'),
- *     props: wrapperProps<SectionWrapper>(),
- *   },
- *   {
- *     wrapperName: 'highlight',
- *     loadComponent: () => import('./highlight-wrapper'),
- *     types: ['input', 'select'],
- *     props: wrapperProps<HighlightWrapper>(),
- *   },
- * );
- *
- * declare module '@ng-forge/dynamic-forms' {
- *   interface FieldRegistryWrappers extends InferWrapperRegistry<typeof appWrappers> {}
- * }
- *
- * bootstrapApplication(AppComponent, {
- *   providers: [provideDynamicForm(appWrappers)],
- * });
- * ```
- */
-declare function createWrappers<const T extends readonly WrapperRegistration[]>(...registrations: T): WrappersBundle<T>;
-/** Type guard for a `WrappersBundle`. */
-declare function isWrappersBundle(value: unknown): value is WrappersBundle;
-/**
- * Derive the `FieldRegistryWrappers` augmentation shape from a wrapper bundle.
- *
- * Maps each registration's `wrapperName` to its `props` type (the config carried
- * by `wrapperProps<T>()`). If a registration has no `props`, falls back to the
- * minimal discriminant shape `{ readonly type: wrapperName }`.
- *
- * @example
- * ```typescript
- * declare module '@ng-forge/dynamic-forms' {
- *   interface FieldRegistryWrappers extends InferWrapperRegistry<typeof appWrappers> {}
- * }
- * ```
- */
-type InferWrapperRegistry<T> = T extends WrappersBundle<infer R> ? {
-    [Reg in R[number] as Reg['wrapperName']]: Reg extends {
-        props: infer P;
-    } ? Exclude<P, undefined> : {
-        readonly type: Reg['wrapperName'];
-    };
-} : never;
-
 /**
  * Extract FieldDef type from FieldTypeDefinition
  */
@@ -5307,336 +5443,1425 @@ type ExtractFormValue<T> = T extends {
 } ? V : never;
 
 /**
- * Built-in field types provided by the dynamic form library.
+ * Type representing a FieldTree for an array.
+ * Extends FieldTree to add numeric indexing for accessing item FieldTrees.
+ */
+type ArrayFieldTree<T> = FieldTree<T[]> & {
+    readonly [index: number]: FieldTree<T> | undefined;
+};
+/**
+ * Get the length of an array FieldTree.
+ */
+declare function getArrayLength<T>(arrayFieldTree: ArrayFieldTree<T>): number;
+/**
+ * Read-only view of a single field's observable state.
  *
- * Each field type is validated at compile time using satisfies, ensuring
- * type safety of the mapper function while allowing the array to be typed
- * as FieldTypeDefinition[] for consumer flexibility.
+ * Whitelisted read signals copied from Angular Signal Forms' `FieldState` so wrappers
+ * can observe a field without being able to mutate it. New write-capable members
+ * added in future Angular versions are excluded by default (the `Pick` list stays
+ * the source of truth).
+ *
+ * `value` is narrowed from `WritableSignal<TValue>` to `Signal<TValue>` so consumers
+ * cannot write through it.
  */
-declare const BUILT_IN_FIELDS: FieldTypeDefinition[];
+interface ReadonlyFieldTree<TValue = unknown> {
+    readonly value: Signal<TValue>;
+    readonly valid: Signal<boolean>;
+    readonly invalid: Signal<boolean>;
+    readonly touched: Signal<boolean>;
+    readonly dirty: Signal<boolean>;
+    readonly required: Signal<boolean>;
+    readonly disabled: Signal<boolean>;
+    readonly hidden: Signal<boolean>;
+    readonly errors: Signal<readonly unknown[]>;
+}
+/**
+ * Build a `ReadonlyFieldTree` by extracting the whitelisted read signals from a
+ * Signal Forms `FieldTree`. Returns a fresh plain object — no casting, no proxying,
+ * so consumers only see the narrow surface and Angular's `WritableSignal` capability
+ * on `value` is hidden.
+ */
+declare function toReadonlyFieldTree<TValue>(field: FieldTree<TValue>): ReadonlyFieldTree<TValue>;
+/**
+ * Write a value into a FieldTree's underlying signal. Signal Forms stores
+ * `FieldState.value` as a `WritableSignal`; this helper centralises the cast
+ * and warns if that contract ever changes (vs a silent no-op).
+ */
+declare function writeToFieldValue<T>(value: Signal<T>, next: T, logger?: {
+    warn: (msg: string) => void;
+}): boolean;
 
 /**
- * Configuration options for the logger feature.
- *
- * @public
+ * Fields every addon-action context carries, regardless of whether the
+ * addon is bound to a host field or rendered orphaned.
  */
-interface LoggerConfigOptions {
+interface AddonActionContextBase<TValue> {
     /**
-     * Whether general logging is enabled.
-     *
-     * @default true
+     * Identity of the host field this addon is attached to. Empty strings
+     * indicate the addon is rendered outside an active field context (rare).
+     * Use {@link isFieldBoundContext} or the `form !== null` check to
+     * narrow before relying on field identity.
      */
-    enabled?: boolean;
+    readonly field: {
+        readonly key: string;
+        readonly type: string;
+    };
     /**
-     * Derivation logging level.
-     *
-     * - `'none'`: No derivation debug logging (default)
-     * - `'summary'`: Log cycle completion with counts
-     * - `'verbose'`: Log individual derivation evaluations with details
-     *
-     * @default 'none'
+     * Current value of the host field at the time the action fires.
+     * `undefined` when the host field has no value yet (initial render before
+     * defaultValue resolution) or when the addon is rendered outside a field.
      */
-    derivations?: DerivationLogLevel;
+    readonly value: TValue | undefined;
 }
 /**
- * Configure logging for dynamic forms.
+ * Field-bound variant — the addon is attached to a real field and has a
+ * working value-writer. The common case for `pi-button` / `mat-button` /
+ * `bs-button` / `ion-button` inside an adapter input field.
  *
- * By default, general logging is enabled (ConsoleLogger) and derivation
- * logging is disabled ('none'). Use this feature to enable derivation debugging.
+ * `setValue` is non-optional here; the optional chain (`ctx.setValue?.()`)
+ * is unnecessary noise once you've narrowed via {@link isFieldBoundContext}.
+ */
+interface FieldBoundAddonActionContext<TValue = unknown> extends AddonActionContextBase<TValue> {
+    /** Read-only view of the host field's tree — same view wrappers receive. */
+    readonly form: ReadonlyFieldTree<TValue>;
+    /** Push a new value into the host field. */
+    readonly setValue: (next: TValue) => void;
+}
+/**
+ * Orphan variant — the addon is rendered outside any field component (rare;
+ * happens when consumers compose `<df-addon-slot>` directly without a host
+ * field). No writer is reachable; reading `value` may also yield `undefined`.
+ */
+interface OrphanAddonActionContext<TValue = unknown> extends AddonActionContextBase<TValue> {
+    readonly form: null;
+    /** Always absent in the orphan variant — distinguishes the union members. */
+    readonly setValue?: undefined;
+}
+/**
+ * Context handed to inline addon actions and registered handler functions.
+ *
+ * Discriminated by `form`: field-bound contexts have a non-null `form` and a
+ * required `setValue`; orphan contexts have `form: null` and no `setValue`.
+ * Use {@link isFieldBoundContext} when the handler needs to write back.
  *
  * @example
  * ```typescript
- * // Disable all logging
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withLoggerConfig(false)
- * )
+ * provideAddonActions({
+ *   submit: (ctx) => {
+ *     if (!isFieldBoundContext(ctx)) return;
+ *     // ctx.setValue is now `(next: TValue) => void` — no optional chain.
+ *     myService.send(ctx.field.key, ctx.value, ctx.setValue);
+ *   },
+ * });
+ * ```
+ */
+type AddonActionContext<TValue = unknown> = FieldBoundAddonActionContext<TValue> | OrphanAddonActionContext<TValue>;
+/** Type guard narrowing {@link AddonActionContext} to its field-bound variant. */
+declare function isFieldBoundContext<TValue>(ctx: AddonActionContext<TValue>): ctx is FieldBoundAddonActionContext<TValue>;
+/**
+ * Built-in preset actions shared across adapters.
  *
- * // Enable verbose derivation logging
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withLoggerConfig({ derivations: 'verbose' })
- * )
+ * Adapter kinds that accept a `preset` field render the corresponding
+ * behaviour:
  *
- * // Disable derivation logging but keep general logging
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withLoggerConfig({ derivations: 'none' })
- * )
+ * - `'clear'`: empties the field value.
+ * - `'reset'`: restores the field's configured default value (resolved
+ *   from the form's `defaultValues` map at click time); falls back to
+ *   empty when no default is reachable.
+ * - `'paste'`: reads from the system clipboard and writes the result.
+ * - `'copy'`: writes the field's current value to the system clipboard.
+ * - `'toggle-password-visibility'`: flips a host input's `type` between
+ *   `password` and `text` (requires the host field to provide a type
+ *   override token, e.g., `PRIME_INPUT_TYPE_OVERRIDE`).
+ *
+ * Form submission is intentionally NOT exposed as a button-addon preset —
+ * use the dedicated `'submit'` field type instead.
+ */
+type CommonAddonActionPreset = 'clear' | 'reset' | 'paste' | 'copy' | 'toggle-password-visibility';
+/**
+ * Module-augmentable registry of adapter-specific preset names.
+ *
+ * Adapters add their canonical actions (e.g., Material's
+ * `'mat-datepicker-open'`) without forking the `AddonActionPreset` union.
+ *
+ * @example
+ * ```typescript
+ * declare module '@ng-forge/dynamic-forms' {
+ *   interface DynamicFormAddonActionPresetRegistry {
+ *     'mat-datepicker-open': true;
+ *   }
+ * }
+ * ```
+ */
+interface DynamicFormAddonActionPresetRegistry {
+}
+/**
+ * Union of every preset name an addon may reference — universal presets
+ * plus any contributed via {@link DynamicFormAddonActionPresetRegistry}.
+ *
+ * The `(string & {})` escape hatch keeps autocomplete on the known +
+ * augmented presets while accepting arbitrary strings for one-off adapter
+ * presets that don't warrant a module-augmentation. The runtime preset
+ * runner already handles unknown names gracefully via its `default:` arm
+ * (logs a warning, no throw). Mirrors `FieldDef.type`'s
+ * `RegisteredFieldTypes['type'] | (string & {})` shape.
+ */
+type AddonActionPreset = CommonAddonActionPreset | keyof DynamicFormAddonActionPresetRegistry | (string & {});
+/**
+ * Module-augmentable registry of user-defined named action handlers.
+ *
+ * Users register handlers once at bootstrap with `provideAddonActions({...})`
+ * and reference them from JSON-driven configs via `actionRef: 'handlerName'`.
+ *
+ * @example
+ * ```typescript
+ * declare module '@ng-forge/dynamic-forms' {
+ *   interface DynamicFormActionRegistry {
+ *     openProfile: true;
+ *     runWorkflow: true;
+ *   }
+ * }
+ * ```
+ */
+interface DynamicFormActionRegistry {
+}
+/**
+ * Typed string handle to a registered action handler. The empty registry
+ * resolves to `never`; augmenting `DynamicFormActionRegistry` populates the
+ * union and unlocks autocomplete.
+ */
+type RegisteredActionRef = keyof DynamicFormActionRegistry;
+
+/**
+ * Map of named `TemplateRef`s collected by `<df-dynamic-form>` from
+ * `<ng-template dfTemplate="...">` children projected into its content.
+ * The directive selector is `dfTemplate` (see `DfTemplate`); the input
+ * value is the name addons reference via `templateKey`.
+ *
+ * The `template` addon kind looks up its `templateKey` in this map at
+ * render time. Exposed as a `Signal` so projections can be added or
+ * removed reactively (e.g., when the host conditionally projects).
+ *
+ * Provided at the form-component level (not root) so multiple
+ * `<df-dynamic-form>` instances on the same page have independent
+ * template scopes.
+ */
+declare const DF_FIELD_TEMPLATES: InjectionToken<Signal<ReadonlyMap<string, TemplateRef<unknown>>>>;
+
+interface FieldOption<T = unknown> {
+    label: DynamicText;
+    value: T;
+    disabled?: boolean;
+    [key: string]: unknown;
+}
+
+/**
+ * Injection token for form-level default wrappers.
+ *
+ * Provides a Signal of the `defaultWrappers` array from FormConfig. Consumed by
+ * `DfFieldOutlet` / `ContainerFieldComponent` to merge into each field's
+ * effective wrapper chain (lowest priority after auto-associations, higher
+ * than field-level `wrappers`).
+ *
+ * Provided once at the DynamicForm level and inherited via Angular's
+ * hierarchical injector.
+ */
+declare const DEFAULT_WRAPPERS: InjectionToken<Signal<readonly WrapperConfig[] | undefined>>;
+/**
+ * Injection token for providing field signal context to mappers and components.
+ *
+ * The field signal context is the "nervous system" of the dynamic form library,
+ * providing access to:
+ * - The form instance and structure
+ * - Current form values (as signals)
+ * - Default values
+ * - Validation messages
+ * - The injector for creating components
+ *
+ * This token is provided by the DynamicForm component and can be scoped
+ * for nested forms (Groups, Arrays) via child injectors.
+ *
+ * @example
+ * ```typescript
+ * // In a mapper function — prefer the helper for required access (descriptive error).
+ * export function mapValueField(fieldDef: BaseValueField<any, any>): Binding[] {
+ *   const context = injectFieldSignalContext();
+ *   const form = context.form();
+ *   // ... use context
+ * }
+ *
+ * // Optional access — token directly, returns null if not provided.
+ * const ctx = inject(FIELD_SIGNAL_CONTEXT, { optional: true });
+ * if (ctx) {
+ *   // ...
+ * }
+ * ```
+ */
+declare const FIELD_SIGNAL_CONTEXT: InjectionToken<FieldSignalContext<Record<string, unknown>>>;
+/**
+ * Throwing accessor for {@link FIELD_SIGNAL_CONTEXT}.
+ *
+ * Use when the consumer requires the context — group/array containers and
+ * mappers that depend on form structure. Throws a descriptive
+ * `DynamicFormError` instead of Angular's generic `NullInjectorError` when
+ * the token isn't provided.
+ *
+ * Consumers that may legitimately run outside a `DynamicForm` should keep
+ * using `inject(FIELD_SIGNAL_CONTEXT, { optional: true })`.
+ */
+declare function injectFieldSignalContext<TModel extends Record<string, unknown> = Record<string, unknown>>(): FieldSignalContext<TModel>;
+/**
+ * Injection token for providing array context metadata to mappers and components.
+ *
+ * This token is optionally provided by ArrayFieldComponent when creating injectors
+ * for array items. It contains metadata about the array item's position and parent.
+ *
+ * Mappers can inject this token with {optional: true} to access array context:
+ *
+ * @example
+ * ```typescript
+ * // In a mapper function
+ * export function buttonMapper(fieldDef: FieldDef<any>): Binding[] {
+ *   const arrayContext = inject(ARRAY_CONTEXT, { optional: true });
+ *   if (arrayContext) {
+ *     // Use arrayContext.index, arrayContext.arrayKey, etc.
+ *   }
+ * }
+ * ```
+ */
+declare const ARRAY_CONTEXT: InjectionToken<ArrayContext>;
+/**
+ * Injection token for providing group ancestry to mappers and components.
+ *
+ * Re-provided in two places:
+ * 1. `GroupFieldComponent` provides a context whose `groupPath()` is the
+ *    parent path extended by its own key (e.g. `'address'` or `'user.address'`).
+ * 2. `createArrayItemInjector` provides a sentinel with an empty `groupPath`,
+ *    resetting the chain at array boundaries — descendants of an array item
+ *    that re-enter a group compose paths INSIDE the array item, matching the
+ *    property-derivation collector's keying.
+ *
+ * `mapFieldToInputs` reads this to scope DOM IDs and override-store keys so
+ * the same leaf key can appear in different groups without colliding (#401).
+ *
+ * Inject with `{ optional: true }` because top-level fields with no group
+ * ancestor (and no enclosing array) won't have the token provided. The token
+ * IS present for fields inside an array even when no inner group exists — the
+ * array-boundary sentinel makes injection succeed with an empty `groupPath`.
+ */
+declare const GROUP_CONTEXT: InjectionToken<GroupContext>;
+/**
+ * Injection token for form-level default props.
+ *
+ * Default props are form-wide property defaults that are merged with field-level props.
+ * Field props take precedence over default props.
+ *
+ * Unlike FIELD_SIGNAL_CONTEXT which is re-provided by container components (Group, Array),
+ * DEFAULT_PROPS is provided ONCE at the DynamicForm level and inherited by all children
+ * via Angular's hierarchical injector.
+ *
+ * The token provides a Signal to enable reactivity - when config changes, mappers
+ * that read the signal inside their computed() will automatically update.
+ *
+ * @example
+ * ```typescript
+ * // In a mapper function
+ * const defaultPropsSignal = inject(DEFAULT_PROPS);
+ *
+ * return computed(() => {
+ *   const defaultProps = defaultPropsSignal?.();  // Read inside computed for reactivity
+ *   const baseInputs = buildBaseInputs(fieldDef, defaultProps);
+ *   // ...
+ * });
+ * ```
+ */
+declare const DEFAULT_PROPS: InjectionToken<Signal<Record<string, unknown> | undefined>>;
+/**
+ * Injection token for form-level default validation messages.
+ *
+ * Default validation messages act as fallbacks when fields have validation
+ * errors but no field-level `validationMessages` defined.
+ *
+ * Like DEFAULT_PROPS, this token is provided ONCE at the DynamicForm level
+ * and inherited by all children via Angular's hierarchical injector.
+ *
+ * The token provides a Signal to enable reactivity - when config changes, mappers
+ * that read the signal inside their computed() will automatically update.
+ *
+ * @example
+ * ```typescript
+ * // In a mapper or component
+ * const defaultMessagesSignal = inject(DEFAULT_VALIDATION_MESSAGES);
+ *
+ * return computed(() => {
+ *   const defaultMessages = defaultMessagesSignal?.();  // Read inside computed for reactivity
+ *   const message = defaultMessages?.required ?? 'Field is required';
+ *   // ...
+ * });
+ * ```
+ */
+declare const DEFAULT_VALIDATION_MESSAGES: InjectionToken<Signal<ValidationMessages | undefined>>;
+/**
+ * Injection token for form-level options.
+ *
+ * Form options control form-wide behavior including button disabled states.
+ * Used by button mappers to determine default disabled behavior.
+ *
+ * Like DEFAULT_PROPS, this token is provided ONCE at the DynamicForm level
+ * and inherited by all children via Angular's hierarchical injector.
+ *
+ * The token provides a Signal to enable reactivity - when config changes, mappers
+ * that read the signal inside their computed() will automatically update.
+ *
+ * @example
+ * ```typescript
+ * // In a button mapper
+ * const formOptionsSignal = inject(FORM_OPTIONS);
+ *
+ * return computed(() => {
+ *   const formOptions = formOptionsSignal?.();  // Read inside computed for reactivity
+ *   const disableWhenInvalid = formOptions?.submitButton?.disableWhenInvalid ?? true;
+ *   // ...
+ * });
+ * ```
+ */
+declare const FORM_OPTIONS: InjectionToken<Signal<FormOptions | undefined>>;
+
+/**
+ * Built-in field types provided by the dynamic form library.
+ *
+ * Each field type is validated at compile time using satisfies, ensuring
+ * type safety of the mapper function while allowing the array to be typed
+ * as FieldTypeDefinition[] for consumer flexibility.
+ */
+declare const BUILT_IN_FIELDS: FieldTypeDefinition[];
+
+/**
+ * Configuration options for the logger feature.
+ *
+ * @public
+ */
+interface LoggerConfigOptions {
+    /**
+     * Whether general logging is enabled.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Derivation logging level.
+     *
+     * - `'none'`: No derivation debug logging (default)
+     * - `'summary'`: Log cycle completion with counts
+     * - `'verbose'`: Log individual derivation evaluations with details
+     *
+     * @default 'none'
+     */
+    derivations?: DerivationLogLevel;
+}
+/**
+ * Configure logging for dynamic forms.
+ *
+ * By default, general logging is enabled (ConsoleLogger) and derivation
+ * logging is disabled ('none'). Use this feature to enable derivation debugging.
+ *
+ * @example
+ * ```typescript
+ * // Disable all logging
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withLoggerConfig(false)
+ * )
+ *
+ * // Enable verbose derivation logging
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withLoggerConfig({ derivations: 'verbose' })
+ * )
+ *
+ * // Disable derivation logging but keep general logging
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withLoggerConfig({ derivations: 'none' })
+ * )
  *
  * // Conditional logging (e.g., only in dev mode)
  * provideDynamicForm(
  *   ...withMaterialFields(),
- *   withLoggerConfig(() => isDevMode())
+ *   withLoggerConfig(() => isDevMode())
+ * )
+ * ```
+ *
+ * @param config - Boolean to enable/disable logging, a function returning boolean, or a config object
+ * @returns A DynamicFormFeature that configures logging
+ *
+ * @public
+ */
+declare function withLoggerConfig(config?: boolean | (() => boolean) | LoggerConfigOptions): DynamicFormFeature<'logger'>;
+
+/**
+ * Injection token for the dynamic forms logger.
+ *
+ * Provided by provideDynamicForm() with ConsoleLogger as default.
+ * Override with withLoggerConfig(false) to disable logging.
+ */
+declare const DynamicFormLogger: InjectionToken<Logger>;
+
+/**
+ * Console-based logger implementation.
+ */
+declare class ConsoleLogger implements Logger {
+    private readonly prefix;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+
+/**
+ * No-operation logger implementation.
+ * All methods are no-ops - used in production by default.
+ */
+declare class NoopLogger implements Logger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+}
+
+/**
+ * Enables automatic form value attachment to all events dispatched through the EventBus.
+ *
+ * When this feature is enabled, events dispatched via `eventBus.dispatch()` will include
+ * the current form value in the `formValue` property. This is useful for event handlers
+ * that need access to the complete form state at the time of the event.
+ *
+ * @example Global opt-in
+ * ```typescript
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withEventFormValue()
+ * )
+ * ```
+ *
+ * @example Consumer usage
+ * ```typescript
+ * eventBus.on<SubmitEvent>('submit').subscribe(event => {
+ *   if (hasFormValue(event)) {
+ *     console.log('Form value:', event.formValue);
+ *   }
+ * });
+ * ```
+ *
+ * @example Per-form disable (when globally enabled)
+ * ```typescript
+ * const config: FormConfig = {
+ *   fields: [...],
+ *   options: { emitFormValueOnEvents: false }
+ * };
+ * ```
+ *
+ * @remarks
+ * **Precedence rules:**
+ * 1. Per-form `false` - Disables for this form, regardless of global setting
+ * 2. Per-form `true` - Enables for this form, regardless of global setting
+ * 3. Per-form `undefined` - Uses global setting
+ * 4. Global `withEventFormValue()` - Enables globally
+ * 5. No global feature - Disabled globally (default)
+ *
+ * @returns A DynamicFormFeature that enables form value attachment to events
+ *
+ * @public
+ */
+declare function withEventFormValue(): DynamicFormFeature<'event-form-value'>;
+
+/**
+ * Configuration for excluding field values from form submission output
+ * based on their reactive state (hidden, disabled, readonly).
+ *
+ * Supports a 3-tier configuration hierarchy: Field > Form > Global.
+ * The most specific level wins for each property.
+ *
+ * @public
+ */
+interface ValueExclusionConfig {
+    /**
+     * Whether to exclude the value of hidden fields from submission output.
+     *
+     * When `true`, fields whose `hidden()` state is `true` will have their
+     * values omitted from the submitted form value.
+     *
+     * @remarks
+     * This does NOT affect HiddenField (`type: 'hidden'`) — those fields
+     * store values without UI and their `hidden()` state is always `false`.
+     */
+    readonly excludeValueIfHidden?: boolean;
+    /**
+     * Whether to exclude the value of disabled fields from submission output.
+     *
+     * When `true`, fields whose `disabled()` state is `true` will have their
+     * values omitted from the submitted form value.
+     */
+    readonly excludeValueIfDisabled?: boolean;
+    /**
+     * Whether to exclude the value of readonly fields from submission output.
+     *
+     * When `true`, fields whose `readonly()` state is `true` will have their
+     * values omitted from the submitted form value.
+     */
+    readonly excludeValueIfReadonly?: boolean;
+}
+/**
+ * Fully resolved exclusion config with all properties required.
+ * Produced by the 3-tier resolution: `field ?? form ?? global`.
+ *
+ * @public
+ */
+type ResolvedValueExclusionConfig = Required<ValueExclusionConfig>;
+
+/**
+ * Configures global value exclusion defaults for form submission output.
+ *
+ * Value exclusion is **enabled by default** — field values are excluded from the
+ * `(submitted)` output based on their reactive state. Use this feature to
+ * override those defaults. This does NOT affect two-way binding (`value` model /
+ * `entity`) — fields retain their values internally.
+ *
+ * @example Default behavior (all exclusions enabled)
+ * ```typescript
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withValueExclusionDefaults()
+ * )
+ * ```
+ *
+ * @example Disable specific exclusions
+ * ```typescript
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withValueExclusionDefaults({ excludeValueIfReadonly: false })
+ * )
+ * ```
+ *
+ * @example Disable all exclusions (restore pre-v1 behavior)
+ * ```typescript
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withValueExclusionDefaults({
+ *     excludeValueIfHidden: false,
+ *     excludeValueIfDisabled: false,
+ *     excludeValueIfReadonly: false,
+ *   })
+ * )
+ * ```
+ *
+ * @remarks
+ * **Precedence rules:**
+ * 1. Per-field `excludeValueIf*` on `FieldDef` — wins for that field
+ * 2. Per-form `excludeValueIf*` on `FormOptions` — wins for all fields in that form
+ * 3. Global `withValueExclusionDefaults()` — baseline default
+ * 4. No global feature — uses token default (all enabled)
+ *
+ * @param config - Partial override of exclusion rules. Unspecified properties default to `true`.
+ * @returns A DynamicFormFeature that configures value exclusion defaults
+ *
+ * @public
+ */
+declare function withValueExclusionDefaults(config?: Partial<ValueExclusionConfig>): DynamicFormFeature<'value-exclusion'>;
+
+/**
+ * Configuration for when validation runs based on a field's reactive state.
+ *
+ * Currently controls whether hidden fields are validated. Resolved through a
+ * tree-aware hierarchy: per-field overrides inherit down to descendants, with
+ * per-form `FormOptions` and global `withValidationExecutionDefaults()` providing
+ * the root inherited value.
+ *
+ * @public
+ */
+interface ValidationExecutionConfig {
+    /**
+     * Whether validators run while a field is hidden (statically, via `hidden`
+     * logic, or because any ancestor is hidden).
+     *
+     * When `false`, all validators on a hidden field are skipped — the field is
+     * effectively inert until shown. State logic (hidden/disabled/readonly) and
+     * value derivations continue to apply.
+     */
+    readonly validateWhenHidden?: boolean;
+}
+/**
+ * Fully resolved validation execution config — every property defined.
+ *
+ * @public
+ */
+type ResolvedValidationExecutionConfig = Required<ValidationExecutionConfig>;
+
+/**
+ * Configures global validation execution defaults — when validators should run
+ * relative to a field's reactive state.
+ *
+ * By default, validators are **skipped** for hidden fields (`validateWhenHidden: false`),
+ * matching what most users expect: a hidden field is inert. Use this feature to
+ * restore the legacy behavior where hidden fields still validate.
+ *
+ * @example Default behavior — no feature needed
+ * ```typescript
+ * provideDynamicForm(...withMaterialFields())
+ * // hidden fields skip validation
+ * ```
+ *
+ * @example Restore legacy validation-on-hidden behavior
+ * ```typescript
+ * provideDynamicForm(
+ *   ...withMaterialFields(),
+ *   withValidationExecutionDefaults({ validateWhenHidden: true })
  * )
  * ```
  *
- * @param config - Boolean to enable/disable logging, a function returning boolean, or a config object
- * @returns A DynamicFormFeature that configures logging
+ * @remarks
+ * **Precedence rules:**
+ * 1. Per-field `FieldDef.validateWhenHidden` — wins for that field; inherits down to descendants
+ *    that don't override.
+ * 2. Per-form `FormOptions.validateWhenHidden` — root inherited value for the form.
+ * 3. Global `withValidationExecutionDefaults()` — fallback when no form/field setting.
+ * 4. No feature configured — uses token default (`validateWhenHidden: false`).
+ *
+ * @param config - Partial override. Unspecified properties keep their defaults.
+ * @returns A `DynamicFormFeature` that configures validation execution defaults.
  *
  * @public
  */
-declare function withLoggerConfig(config?: boolean | (() => boolean) | LoggerConfigOptions): DynamicFormFeature<'logger'>;
+declare function withValidationExecutionDefaults(config?: Partial<ValidationExecutionConfig>): DynamicFormFeature<'validation-execution'>;
 
 /**
- * Injection token for the dynamic forms logger.
+ * Opt into Angular Signal Forms' legacy `.ng-touched` / `.ng-invalid` /
+ * `.ng-dirty` / `.ng-pristine` / `.ng-untouched` / `.ng-pending` /
+ * `.ng-valid` CSS classes on form-bound elements.
  *
- * Provided by provideDynamicForm() with ConsoleLogger as default.
- * Override with withLoggerConfig(false) to disable logging.
+ * Wires Angular's `@angular/forms/signals/compat` `NG_STATUS_CLASSES` strategy
+ * via `provideSignalFormsConfig`. Without this feature the modern Signal Forms
+ * class strategy is active, which omits the legacy `ng-*` classes.
+ *
+ * @example Opt in once at the application root
+ * ```typescript
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideDynamicForm(
+ *       ...withMaterialFields(),
+ *       withLegacyStatusClasses()
+ *     )
+ *   ]
+ * });
+ * ```
+ *
+ * @returns A DynamicFormFeature that enables the legacy `ng-*` class strategy
+ *
+ * @public
  */
-declare const DynamicFormLogger: InjectionToken<Logger>;
+declare function withLegacyStatusClasses(): DynamicFormFeature<'legacy-status-classes'>;
 
 /**
- * Console-based logger implementation.
+ * Zero-cost type carrier used in wrapper registrations.
+ *
+ * Returns `undefined` at runtime but is typed as `T`, so TypeScript can
+ * thread a wrapper's config type through `createWrappers(...)` into the
+ * `InferWrapperRegistry<typeof ...>` utility without requiring users to
+ * hand-write the augmentation shape.
+ *
+ * @example
+ * ```typescript
+ * const wrappers = createWrappers(
+ *   {
+ *     wrapperName: 'section',
+ *     loadComponent: () => import('./section-wrapper'),
+ *     props: wrapperProps<SectionWrapper>(),
+ *   },
+ * );
+ *
+ * declare module '@ng-forge/dynamic-forms' {
+ *   interface FieldRegistryWrappers extends InferWrapperRegistry<typeof wrappers> {}
+ * }
+ * ```
  */
-declare class ConsoleLogger implements Logger {
-    private readonly prefix;
-    debug(message: string, ...args: unknown[]): void;
-    info(message: string, ...args: unknown[]): void;
-    warn(message: string, ...args: unknown[]): void;
-    error(message: string, ...args: unknown[]): void;
-}
+declare function wrapperProps<T>(): T;
 
 /**
- * No-operation logger implementation.
- * All methods are no-ops - used in production by default.
+ * Input shape passed to a wrapper component via the `fieldInputs` input.
+ *
+ * Carries the wrapped field's mapper outputs plus an optional `field`
+ * read-only view. Wrappers reached through a container path (which has
+ * no FieldTree of its own) receive `fieldInputs === undefined`, so any
+ * wrapper that reads `fieldInputs.field` must guard for it.
+ *
+ * Mappers must emit new rawInputs objects per tick rather than mutating
+ * the previous one — this bag is a shallow spread, so mutations to shared
+ * nested values leak to downstream wrappers.
  */
-declare class NoopLogger implements Logger {
-    debug(): void;
-    info(): void;
-    warn(): void;
-    error(): void;
+interface WrapperFieldInputs {
+    readonly key: string;
+    /** Field-type discriminant (mirrors `FieldDef.type`) — useful for kind-aware addons. */
+    readonly type?: string;
+    readonly label?: string;
+    readonly placeholder?: string;
+    readonly className?: string;
+    readonly props?: Record<string, unknown>;
+    readonly validationMessages?: Record<string, string>;
+    readonly defaultValidationMessages?: Record<string, string>;
+    readonly field?: ReadonlyFieldTree;
+    /**
+     * Write a value into the wrapped field's tree. Provided by `buildFieldInputs`
+     * when a `FieldTree` is present. Addons (e.g., `prime-button` presets) use this
+     * to mutate the host field; wrappers should treat the field as read-only.
+     */
+    readonly setValue?: (next: unknown) => void;
+    readonly [key: string]: unknown;
 }
 
 /**
- * Enables automatic form value attachment to all events dispatched through the EventBus.
+ * Dispatcher component that renders an addon by looking up its `kind` in
+ * `ADDON_KIND_REGISTRY` and instantiating the registered component.
  *
- * When this feature is enabled, events dispatched via `eventBus.dispatch()` will include
- * the current form value in the `formValue` property. This is useful for event handlers
- * that need access to the complete form state at the time of the event.
+ * Used by every adapter's field component to render slot content:
  *
- * @example Global opt-in
- * ```typescript
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withEventFormValue()
- * )
+ * ```html
+ * \@for (a of addonsAt('prefix'); track $index) {
+ *   <df-addon-slot [addon]="a" />
+ * }
  * ```
  *
- * @example Consumer usage
- * ```typescript
- * eventBus.on<SubmitEvent>('submit').subscribe(event => {
- *   if (hasFormValue(event)) {
- *     console.log('Form value:', event.formValue);
- *   }
- * });
+ * Behaviour:
+ * - Resolves and caches the kind's component asynchronously on first render.
+ * - Forwards the `slot` HTML attribute on the host so Ionic shadow-DOM
+ *   projection works (`<ion-input>` projects children with `slot="start"`
+ *   into its native start slot).
+ * - Honours the addon's reactive `hidden` flag — when `true`, the host is
+ *   `display: none` so it occupies no layout but stays in DOM (cheaper than
+ *   tearing down the component).
+ * - Forwards `className` to the host element.
+ * - ARIA semantics are owned by individual kind components — decorative
+ *   kinds (icons, text) set `aria-hidden="true"` on themselves; interactive
+ *   kinds (buttons) handle their own `aria-label`.
+ *
+ * If the kind cannot be resolved (registry miss, load failure), the
+ * dispatcher logs a warning and renders nothing — never throws. The
+ * runtime addon validator should have caught unknown kinds at config init,
+ * but this provides a defence-in-depth fallback for misconfigured registries.
+ */
+declare class DfAddonSlot {
+    private readonly registry;
+    private readonly logger;
+    private readonly hostInjector;
+    readonly addon: _angular_core.InputSignal<AnyAddon>;
+    /**
+     * Optional read-only view of the host field's mapped inputs — same shape
+     * wrappers receive (`field?: ReadonlyFieldTree`, `key`, `props`, etc.).
+     * Forwarded to kind components so they can read field state without
+     * re-injecting `FIELD_SIGNAL_CONTEXT` and rebuilding context themselves.
+     *
+     * `undefined` when the addon is rendered outside a field (rare).
+     */
+    readonly fieldInputs: _angular_core.InputSignal<WrapperFieldInputs | undefined>;
+    /**
+     * Pre-resolved `hidden` signal supplied by the host field. When provided,
+     * the dispatcher reads this instead of re-resolving `addon.hidden` —
+     * lets the host (e.g., `prime-input`) share a single subscription per
+     * Observable-typed `hidden` between its own visibility filter and the
+     * slot's `[style.display]` binding.
+     */
+    readonly hidden: _angular_core.InputSignal<Signal<boolean> | undefined>;
+    /** `slot` HTML attribute forwarded to host — needed for Ionic shadow projection. */
+    protected readonly slotAttr: Signal<_ng_forge_dynamic_forms.AddonSlot>;
+    protected readonly className: Signal<string | null>;
+    /**
+     * Locally-resolved `hidden` signal — always reflects `addon.hidden`
+     * regardless of whether the host supplied a pre-resolved signal.
+     * Populated via `explicitEffect` so `resolveDynamicValue` (which may call
+     * `toSignal` for Observable-typed values) does NOT run inside a reactive
+     * context (NG0602). The WeakMap caches per `hidden`-value identity, so
+     * swapping `addon` inputs that share the same Observable reuses the
+     * subscription instead of leaking a fresh one per swap.
+     *
+     * Resolved unconditionally (not gated on host `hidden()` presence) so a
+     * transition from `host hidden = Signal` → `undefined` doesn't expose a
+     * brief window where neither value is current — the upstream effect
+     * re-runs eventually, but the computed read can happen in between.
+     */
+    private readonly _hiddenByValue;
+    private readonly _resolvedHidden;
+    /**
+     * `hidden` resolved from `DynamicValue<boolean>` to a flat `Signal<boolean>`.
+     * Prefers the host-supplied signal when present (avoids duplicate `toSignal`
+     * subscriptions for Observable-typed `hidden`); falls back to the locally-
+     * resolved signal, which is always populated by the addon-tracking effect.
+     */
+    protected readonly isHidden: Signal<boolean>;
+    /**
+     * Latest async-loaded `{ kind, component }` pair. Tagging the result with
+     * its kind lets `resolvedComponent` filter stale loads structurally — no
+     * monotonic token needed. When `addon.kind` changes mid-load, the prior
+     * load still completes and writes here, but the computed ignores it
+     * because the recorded kind no longer matches the current one.
+     */
+    private readonly asyncLoaded;
+    /**
+     * Resolved kind component — composed declaratively from two sources of
+     * truth: the registry's synchronous cache (warm hits, e.g., a second
+     * `<df-addon-slot>` for an already-loaded kind) and the kind-tagged async
+     * loader result. Reading `addon().kind` first makes the computed react to
+     * addon swaps and naturally invalidate stale async-load results.
+     */
+    protected readonly resolvedComponent: Signal<Type<unknown> | undefined>;
+    /** Inputs passed to the kind component — addon plus the wrapper-style host bag. */
+    protected readonly kindInputs: Signal<{
+        addon: AnyAddon;
+        fieldInputs: WrapperFieldInputs | undefined;
+    }>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<DfAddonSlot, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DfAddonSlot, "df-addon-slot", never, { "addon": { "alias": "addon"; "required": true; "isSignal": true; }; "fieldInputs": { "alias": "fieldInputs"; "required": false; "isSignal": true; }; "hidden": { "alias": "hidden"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Marks an `<ng-template>` projected into `<df-dynamic-form>` content as
+ * available to template addons by name.
+ *
+ * The host form collects all `DfTemplate` instances via `contentChildren`
+ * and exposes them through {@link DF_FIELD_TEMPLATES}, where the template
+ * addon kind looks them up by `templateKey` at render time.
+ *
+ * @example
+ * ```html
+ * <df-dynamic-form [config]="config">
+ *   <ng-template dfTemplate="searchIcon" let-field>
+ *     <my-icon [field]="field" />
+ *   </ng-template>
+ * </df-dynamic-form>
  * ```
  *
- * @example Per-form disable (when globally enabled)
- * ```typescript
- * const config: FormConfig = {
- *   fields: [...],
- *   options: { emitFormValueOnEvents: false }
- * };
+ * In the field config:
+ * ```ts
+ * { slot: 'prefix', kind: 'template', templateKey: 'searchIcon' }
  * ```
+ */
+declare class DfTemplate {
+    /** Name this template registers under — referenced from `TemplateAddon.templateKey`. */
+    readonly dfTemplate: _angular_core.InputSignal<string>;
+    /** The wrapped template, captured for registration and `NgTemplateOutlet` rendering. */
+    readonly templateRef: TemplateRef<unknown>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<DfTemplate, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<DfTemplate, "ng-template[dfTemplate]", ["dfTemplate"], { "dfTemplate": { "alias": "dfTemplate"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Renderer for the universal `text` addon kind.
  *
- * @remarks
- * **Precedence rules:**
- * 1. Per-form `false` - Disables for this form, regardless of global setting
- * 2. Per-form `true` - Enables for this form, regardless of global setting
- * 3. Per-form `undefined` - Uses global setting
- * 4. Global `withEventFormValue()` - Enables globally
- * 5. No global feature - Disabled globally (default)
+ * Renders the addon's `text` (a `DynamicText`) inside a span. Decorative —
+ * sets `aria-hidden="true"` on the host so screen readers skip it; users
+ * who need announcement should use a `*-button` kind with `ariaLabel` instead.
+ */
+declare class TextAddonComponent {
+    readonly addon: _angular_core.InputSignal<TextAddon>;
+    /** Accepted for contract uniformity — `NgComponentOutlet` setInput is strict; every kind must declare it. */
+    readonly fieldInputs: _angular_core.InputSignal<WrapperFieldInputs | undefined>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TextAddonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TextAddonComponent, "df-text-addon", never, { "addon": { "alias": "addon"; "required": true; "isSignal": true; }; "fieldInputs": { "alias": "fieldInputs"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Renderer for the universal `template` addon kind.
  *
- * @returns A DynamicFormFeature that enables form value attachment to events
+ * Resolves the addon's `templateKey` against {@link DF_FIELD_TEMPLATES}
+ * (populated by `<df-dynamic-form>` from `<ng-template dfTemplate="...">`
+ * children) and renders via `NgTemplateOutlet`. The wrapper-style host bag
+ * (`fieldInputs`) is forwarded as the template's implicit context — author
+ * the template as `<ng-template dfTemplate="..." let-fi>{{ fi.key }}</ng-template>`.
  *
- * @public
+ * If the key is unresolved, logs a warning and renders nothing — keeps the
+ * form alive when a backend references a template the FE has not registered.
  */
-declare function withEventFormValue(): DynamicFormFeature<'event-form-value'>;
+declare class TemplateAddonComponent {
+    private readonly templates;
+    private readonly logger;
+    readonly addon: _angular_core.InputSignal<TemplateAddon>;
+    /** Forwarded by `df-addon-slot`; surfaced to the template as its implicit `$implicit` context. */
+    readonly fieldInputs: _angular_core.InputSignal<WrapperFieldInputs | undefined>;
+    protected readonly template: _angular_core.Signal<_angular_core.TemplateRef<unknown> | null>;
+    /** Implicit context payload — template authors bind via `let-fi`. */
+    protected readonly outletContext: _angular_core.Signal<{
+        $implicit: WrapperFieldInputs | undefined;
+    }>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TemplateAddonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TemplateAddonComponent, "df-template-addon", never, { "addon": { "alias": "addon"; "required": true; "isSignal": true; }; "fieldInputs": { "alias": "fieldInputs"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
 
 /**
- * Configuration for excluding field values from form submission output
- * based on their reactive state (hidden, disabled, readonly).
+ * Renderer for the universal `component` addon kind.
  *
- * Supports a 3-tier configuration hierarchy: Field > Form > Global.
- * The most specific level wins for each property.
+ * Loads the user-supplied component lazily (`addon.component()`) and renders
+ * it via `NgComponentOutlet` with `addon.inputs` forwarded as input bindings.
+ * The wrapper-style `fieldInputs` bag is not propagated — user components
+ * receive only what `addon.inputs` declares. Authors that need field state
+ * should switch to the `template` kind or build a wrapper.
  *
- * @public
+ * @codeOnly The `component` loader is a function; this kind is dropped in
+ * lenient validation when the config originated from JSON.
  */
-interface ValueExclusionConfig {
+declare class ComponentAddonComponent {
+    private readonly logger;
+    readonly addon: _angular_core.InputSignal<ComponentAddon>;
+    /** Accepted for contract uniformity — `NgComponentOutlet` setInput is strict; every kind must declare it. */
+    readonly fieldInputs: _angular_core.InputSignal<WrapperFieldInputs | undefined>;
+    protected readonly inputs: _angular_core.Signal<Record<string, unknown>>;
+    /**
+     * Latest async-loaded `{ addon, component }` pair. Tagging the result with
+     * its source addon lets `resolvedComponent` filter stale loads structurally
+     * — same kind-tagging pattern `DfAddonSlot` uses. When `addon` swaps
+     * mid-load, the prior loader still completes and writes here, but the
+     * computed ignores it because the recorded addon no longer matches the
+     * current one.
+     */
+    private readonly asyncLoaded;
+    protected readonly resolvedComponent: _angular_core.Signal<Type<unknown> | undefined>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ComponentAddonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ComponentAddonComponent, "df-component-addon", never, { "addon": { "alias": "addon"; "required": true; "isSignal": true; }; "fieldInputs": { "alias": "fieldInputs"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Optional collaborators a preset may need beyond the base context. Passed
+ * by the button kind component which has access to its own DI scope.
+ *
+ * Adapter input components fill in the collaborators their preset semantics
+ * require:
+ * - `mat-input` / `bs-input` / `prime-input` / `ion-input` populate
+ *   `typeOverride` + `fieldValueSetter` + `fieldDefaultValueGetter` +
+ *   `baselineType` from their own DI scope.
+ * - Addons rendered outside any input field receive `{ logger }` only and
+ *   the input-specific presets warn-and-no-op.
+ */
+interface PresetCollaborators {
+    /** Per-field input-type override signal — populated only inside an input field. */
+    readonly typeOverride?: WritableSignal<string | undefined>;
+    /** Writer that pushes a value into the host field's tree. */
+    readonly fieldValueSetter?: (next: unknown) => void;
     /**
-     * Whether to exclude the value of hidden fields from submission output.
-     *
-     * When `true`, fields whose `hidden()` state is `true` will have their
-     * values omitted from the submitted form value.
-     *
-     * @remarks
-     * This does NOT affect HiddenField (`type: 'hidden'`) — those fields
-     * store values without UI and their `hidden()` state is always `false`.
+     * Read the host field's configured default value (from the form's
+     * `defaultValues` map keyed by `field.key`). Used by the `'reset'`
+     * preset; absent when the addon is rendered outside an active field
+     * context, in which case `'reset'` falls back to clearing.
      */
-    readonly excludeValueIfHidden?: boolean;
+    readonly fieldDefaultValueGetter?: () => unknown;
     /**
-     * Whether to exclude the value of disabled fields from submission output.
-     *
-     * When `true`, fields whose `disabled()` state is `true` will have their
-     * values omitted from the submitted form value.
+     * Baseline configured input type (from `props().type`), read at preset-run
+     * time. Used by `toggle-password-visibility` to refuse to corrupt
+     * `'email'`/`'number'`/etc. inputs into `'password'` when no override is
+     * yet set.
      */
-    readonly excludeValueIfDisabled?: boolean;
+    readonly baselineType?: () => string | undefined;
     /**
-     * Whether to exclude the value of readonly fields from submission output.
+     * Logger for warnings about presets that can't be fulfilled in this context.
      *
-     * When `true`, fields whose `readonly()` state is `true` will have their
-     * values omitted from the submitted form value.
+     * Passed via collaborators (rather than injected) because `runPresetAction`
+     * is a DI-free pure function shared across adapters — each adapter's
+     * `ADDON_PRESET_HANDLER` factory injects `DynamicFormLogger` itself and
+     * forwards it here. The `[Dynamic Forms]` prefix comes from
+     * `ConsoleLogger`'s implementation, so the final console line is identical
+     * to one logged directly via `inject(DynamicFormLogger)`.
      */
-    readonly excludeValueIfReadonly?: boolean;
+    readonly logger: Logger;
+}
+/**
+ * Apply a built-in preset action against the addon's host field. Shared
+ * across all adapters — each adapter's `ADDON_PRESET_HANDLER` provider
+ * delegates here.
+ *
+ * Presets that require adapter-specific UI mechanics (clipboard, type
+ * override) are best-effort — they no-op with a warning when the necessary
+ * collaborator isn't available (e.g., toggle-password-visibility outside an
+ * input field).
+ *
+ * @param adapterLabel Used in warnings — `'Material'` / `'Bootstrap'` / etc.
+ * @param fieldLabel   Used in warnings — `'mat-input'` / `'bs-input'` / etc.
+ */
+declare function runPresetAction(preset: AddonActionPreset, ctx: AddonActionContext, collaborators: PresetCollaborators, adapterLabel: string, fieldLabel: string): Promise<void>;
+
+/**
+ * Cache for resolved addon-kind components.
+ *
+ * Provided per-form by `provideDynamicFormDI()` so two `<df-dynamic-form>`
+ * instances with conflicting `loadComponent` factories for the same kind
+ * never share a stale entry. Has no `providedIn: 'root'` factory — the
+ * registry consumer is always inside a form scope, and a root fallback
+ * would only hide misconfiguration (an SSR cross-request hit if a future
+ * code path forgot to provide it locally).
+ *
+ * Mirrors `COMPONENT_CACHE` (field types) and `WRAPPER_COMPONENT_CACHE`
+ * (wrappers).
+ *
+ * @internal
+ */
+declare const ADDON_KIND_COMPONENT_CACHE: InjectionToken<Map<string, Type<unknown>>>;
+/**
+ * Public shape returned by {@link injectAddonKindRegistry}. Pinned explicitly
+ * so the API extractor doesn't churn between versions when the inner factory
+ * gets refactored.
+ */
+interface AddonKindRegistryRef {
+    getKind(kind: string): AddonKindDefinition | undefined;
+    hasKind(kind: string): boolean;
+    getKindNames(): string[];
+    loadKindComponent(kind: string): Promise<Type<unknown>>;
+    getLoadedKindComponent(kind: string): Type<unknown> | undefined;
+    readonly raw: ReadonlyMap<string, AddonKindDefinition>;
 }
 /**
- * Fully resolved exclusion config with all properties required.
- * Produced by the 3-tier resolution: `field ?? form ?? global`.
+ * Injection function for accessing the addon kind registry.
+ *
+ * Usage parallels {@link injectFieldRegistry}: lookup, lazy load, cache.
+ * Must be called within an injection context.
+ *
+ * @example
+ * ```typescript
+ * const addonKinds = injectAddonKindRegistry();
+ * const Component = await addonKinds.loadKindComponent('prime-icon');
+ * ```
+ */
+declare function injectAddonKindRegistry(): AddonKindRegistryRef;
+
+/**
+ * One entry per field type that declares addon support.
  *
- * @public
+ * `name` is the field-type discriminant; `slots` and `allowedKinds` mirror
+ * the `FieldTypeDefinition.addons` registration.
  */
-type ResolvedValueExclusionConfig = Required<ValueExclusionConfig>;
-
+interface FieldAddonSupportEntry {
+    readonly name: string;
+    readonly slots: FieldAddonSupport['slots'];
+    readonly allowedKinds: FieldAddonSupport['allowedKinds'];
+}
 /**
- * Configures global value exclusion defaults for form submission output.
+ * Walk `FIELD_REGISTRY` and return every field type that opted into addons
+ * (i.e., declared `addons` on its `FieldTypeDefinition`).
  *
- * Value exclusion is **enabled by default** — field values are excluded from the
- * `(submitted)` output based on their reactive state. Use this feature to
- * override those defaults. This does NOT affect two-way binding (`value` model /
- * `entity`) — fields retain their values internally.
+ * Useful for tooling — admin UIs surfacing "which fields can carry addons?",
+ * docs generators, MCP server cross-checks. Field types without an `addons`
+ * registration ("Tier 3" — toggle, checkbox, radio, slider) are excluded.
  *
- * @example Default behavior (all exclusions enabled)
+ * Must be called within an injection context.
+ *
+ * @example
  * ```typescript
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withValueExclusionDefaults()
- * )
+ * @Component({ ... })
+ * class FormBuilder {
+ *   protected readonly addonable = injectFieldsSupportingAddons();
+ *
+ *   constructor() {
+ *     // -> [{ name: 'prime-input', slots: ['prefix', 'suffix'], allowedKinds: [...] }, ...]
+ *   }
+ * }
  * ```
+ */
+declare function injectFieldsSupportingAddons(): FieldAddonSupportEntry[];
+
+/**
+ * Normalises a {@link DynamicValue} into a `Signal<T>`.
  *
- * @example Disable specific exclusions
+ * Accepts a static value, a `Signal<T>`, or an `Observable<T>`. The result
+ * is a `Signal<T>` that reactively reflects the current value, suitable
+ * for direct use in Angular templates.
+ *
+ * Static values yield a `computed` that always returns the same constant —
+ * preferable to wrapping in `signal()` because the computed never causes
+ * change-detection invalidation.
+ *
+ * Pass an `injector` when calling outside an Angular injection context
+ * (e.g., from inside a `computed`). `toSignal` needs a `DestroyRef` to
+ * unsubscribe — without an injector it falls back to `inject(DestroyRef)`,
+ * which throws when called outside injection context.
+ *
+ * @example
  * ```typescript
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withValueExclusionDefaults({ excludeValueIfReadonly: false })
- * )
+ * const isHidden = resolveDynamicValue(addon().hidden, false);
+ * // template: \@if (isHidden()) { ... }
  * ```
+ */
+declare function resolveDynamicValue<T>(value: DynamicValue<T> | undefined, fallback: T, injector?: Injector): Signal<T>;
+
+/**
+ * Register a custom addon kind with the form.
  *
- * @example Disable all exclusions (restore pre-v1 behavior)
+ * The provided definition is added to `ADDON_KIND_REGISTRY` at form
+ * initialisation, alongside the built-in `text` / `template` / `component`
+ * kinds and any kinds contributed by adapter feature helpers
+ * (`withPrimeNGAddons()` etc.).
+ *
+ * @example
  * ```typescript
  * provideDynamicForm(
  *   ...withMaterialFields(),
- *   withValueExclusionDefaults({
- *     excludeValueIfHidden: false,
- *     excludeValueIfDisabled: false,
- *     excludeValueIfReadonly: false,
- *   })
- * )
+ *   withCustomAddon({
+ *     kind: 'lucide-icon',
+ *     // Match how field types register: a default-exported component lets
+ *     // `loadComponent` return the import promise directly.
+ *     loadComponent: () => import('./lucide-icon-addon.component'),
+ *     validate: (addon) => {
+ *       if (typeof addon.icon !== 'string') {
+ *         throw new Error('lucide-icon: icon string is required');
+ *       }
+ *     },
+ *   }),
+ * );
  * ```
  *
- * @remarks
- * **Precedence rules:**
- * 1. Per-field `excludeValueIf*` on `FieldDef` — wins for that field
- * 2. Per-form `excludeValueIf*` on `FormOptions` — wins for all fields in that form
- * 3. Global `withValueExclusionDefaults()` — baseline default
- * 4. No global feature — uses token default (all enabled)
- *
- * @param config - Partial override of exclusion rules. Unspecified properties default to `true`.
- * @returns A DynamicFormFeature that configures value exclusion defaults
- *
- * @public
+ * Multiple `withCustomAddon(...)` calls are supported; later registrations
+ * for the same kind override earlier ones (with a warning logged).
  */
-declare function withValueExclusionDefaults(config?: Partial<ValueExclusionConfig>): DynamicFormFeature<'value-exclusion'>;
+declare function withCustomAddon<T extends BaseAddon>(definition: AddonKindDefinition<T>): DynamicFormFeature<'addons'>;
 
 /**
- * Configuration for when validation runs based on a field's reactive state.
- *
- * Currently controls whether hidden fields are validated. Resolved through a
- * tree-aware hierarchy: per-field overrides inherit down to descendants, with
- * per-form `FormOptions` and global `withValidationExecutionDefaults()` providing
- * the root inherited value.
+ * Handler signature for user-registered addon actions.
  *
- * @public
+ * Backends reference handlers by name via `actionRef: 'name'` on button-style
+ * addons; the dispatcher invokes the registered function with the addon's
+ * action context.
  */
-interface ValidationExecutionConfig {
-    /**
-     * Whether validators run while a field is hidden (statically, via `hidden`
-     * logic, or because any ancestor is hidden).
-     *
-     * When `false`, all validators on a hidden field are skipped — the field is
-     * effectively inert until shown. State logic (hidden/disabled/readonly) and
-     * value derivations continue to apply.
-     */
-    readonly validateWhenHidden?: boolean;
-}
+type AddonActionHandler<TValue = unknown> = (ctx: AddonActionContext<TValue>) => void;
 /**
- * Fully resolved validation execution config — every property defined.
+ * Multi-provider token populated by `provideAddonActions({...})` calls.
+ * `ADDON_ACTION_REGISTRY` aggregates these into a single name → handler map.
  *
- * @public
+ * @internal
  */
-type ResolvedValidationExecutionConfig = Required<ValidationExecutionConfig>;
+declare const ADDON_ACTION_HANDLERS: InjectionToken<readonly Record<string, AddonActionHandler<unknown>>[]>;
+/**
+ * Form-scoped name → handler map. Read by adapter button kinds at click
+ * time for `actionRef: 'name'` lookups. Provided at form scope (not root)
+ * because `ADDON_ACTION_HANDLERS` is form-scoped via `provideAddonActions`.
+ */
+declare const ADDON_ACTION_REGISTRY: InjectionToken<ReadonlyMap<string, AddonActionHandler<unknown>>>;
 
 /**
- * Configures global validation execution defaults — when validators should run
- * relative to a field's reactive state.
+ * Typed feature returned by {@link provideAddonActions}. Carries the
+ * registered handler keys as a phantom type so consumers can derive the
+ * `DynamicFormActionRegistry` augmentation in one line instead of hand-typing
+ * every key.
  *
- * By default, validators are **skipped** for hidden fields (`validateWhenHidden: false`),
- * matching what most users expect: a hidden field is inert. Use this feature to
- * restore the legacy behavior where hidden fields still validate.
+ * Phantom field is `__handlerKeys` (the leading underscores signal "internal,
+ * type-only — not for runtime access").
+ */
+type AddonActionsFeature<K extends string = string> = DynamicFormFeature<'addon-actions'> & {
+    /** @internal Phantom field carrying the registered keys; never read at runtime. */
+    readonly __handlerKeys?: K;
+};
+/**
+ * Register named action handlers reachable via JSON-driven addon configs.
  *
- * @example Default behavior — no feature needed
- * ```typescript
- * provideDynamicForm(...withMaterialFields())
- * // hidden fields skip validation
- * ```
+ * Once registered, a backend can ship
+ * `{ kind: 'prime-button', actionRef: 'openProfile' }` and the FE will invoke
+ * the corresponding handler at click time.
+ *
+ * Define handlers once and augment the registry from the same object:
  *
- * @example Restore legacy validation-on-hidden behavior
  * ```typescript
- * provideDynamicForm(
- *   ...withMaterialFields(),
- *   withValidationExecutionDefaults({ validateWhenHidden: true })
- * )
+ * export const appActions = provideAddonActions({
+ *   openProfile: (ctx) => modalService.open(ProfileModal, { data: ctx.value }),
+ *   runWorkflow: (ctx) => workflowService.run(ctx.field.key, ctx.value),
+ * });
+ *
+ * declare module '@ng-forge/dynamic-forms' {
+ *   // Pulls the keys straight off `appActions` — no manual list to keep in sync.
+ *   interface DynamicFormActionRegistry extends Record<NonNullable<typeof appActions['__handlerKeys']>, true> {}
+ * }
+ *
+ * // Then in your bootstrap:
+ * provideDynamicForm(...withPrimeNGFields(), appActions);
  * ```
  *
- * @remarks
- * **Precedence rules:**
- * 1. Per-field `FieldDef.validateWhenHidden` — wins for that field; inherits down to descendants
- *    that don't override.
- * 2. Per-form `FormOptions.validateWhenHidden` — root inherited value for the form.
- * 3. Global `withValidationExecutionDefaults()` — fallback when no form/field setting.
- * 4. No feature configured — uses token default (`validateWhenHidden: false`).
+ * Multiple `provideAddonActions(...)` calls are merged; later names override
+ * earlier ones for the same key.
+ */
+declare function provideAddonActions<const H extends Record<string, AddonActionHandler>>(handlers: H): AddonActionsFeature<keyof H & string>;
+
+/**
+ * Multi-provider token used by `withCustomAddon(...)` features to contribute
+ * addon kind definitions. `provideDynamicForm` aggregates all values into
+ * the form-scoped `ADDON_KIND_REGISTRY` map.
  *
- * @param config - Partial override. Unspecified properties keep their defaults.
- * @returns A `DynamicFormFeature` that configures validation execution defaults.
+ * @internal
+ */
+declare const ADDON_KIND_DEFINITIONS: InjectionToken<readonly AddonKindDefinition<_ng_forge_dynamic_forms.BaseAddon<_ng_forge_dynamic_forms.AddonSlot>>[]>;
+
+/**
+ * Reason an addon was dropped during validation.
  *
- * @public
+ * Each variant carries its own context fields so log messages can be both
+ * actionable (registered kinds enumerated, fix suggestion present) and
+ * machine-readable (admin UIs surfacing per-error guidance).
  */
-declare function withValidationExecutionDefaults(config?: Partial<ValidationExecutionConfig>): DynamicFormFeature<'validation-execution'>;
+type AddonWarning = {
+    type: 'unknown-field-type';
+    fieldKey: string;
+    fieldType: string;
+} | {
+    type: 'field-type-no-addon-support';
+    fieldKey: string;
+    fieldType: string;
+} | {
+    type: 'unknown-slot';
+    fieldKey: string;
+    fieldType: string;
+    slot: string;
+    allowedSlots: readonly string[];
+} | {
+    type: 'unknown-kind';
+    fieldKey: string;
+    kind: string;
+    registeredKinds: readonly string[];
+} | {
+    type: 'kind-not-allowed';
+    fieldKey: string;
+    fieldType: string;
+    kind: string;
+    allowedKinds: readonly string[];
+} | {
+    type: 'shape-violation';
+    fieldKey: string;
+    kind: string;
+    reason: string;
+} | {
+    type: 'code-only-kind-in-json';
+    fieldKey: string;
+    kind: string;
+} | {
+    type: 'code-only-action-in-json';
+    fieldKey: string;
+    reason: string;
+};
+/**
+ * Render an `AddonWarning` to a developer-friendly message.
+ *
+ * Returns the bare message — the `[Dynamic Forms]` prefix is added by the
+ * library's logger (`ConsoleLogger`) and by `DynamicFormError`. Pass the
+ * result of this function directly into `logger.warn(...)` to get the
+ * standard prefixed line; use `logAddonWarnings()` for direct
+ * `console.warn` output (which prefixes manually).
+ *
+ * Messages are designed to be actionable: they enumerate the relevant set
+ * (registered kinds, allowed slots) and suggest a likely fix.
+ */
+declare function formatAddonWarning(w: AddonWarning): string;
 
 /**
- * Zero-cost type carrier used in wrapper registrations.
+ * Walk a field's addons; return the survivors plus a list of warnings for
+ * anything dropped.
  *
- * Returns `undefined` at runtime but is typed as `T`, so TypeScript can
- * thread a wrapper's config type through `createWrappers(...)` into the
- * `InferWrapperRegistry<typeof ...>` utility without requiring users to
- * hand-write the augmentation shape.
+ * Pure: receives the registries as arguments (so the function is reusable
+ * outside Angular's DI — tests, server-side validation, etc.).
+ *
+ * @param field        The field to validate.
+ * @param fieldRegistry Snapshot of `FIELD_REGISTRY` map.
+ * @param kindRegistry  Snapshot of `ADDON_KIND_REGISTRY` map.
+ * @param source       Whether the config originated from JSON (lenient drop
+ *                      of code-only kinds) or inline TypeScript.
+ */
+declare function validateFieldAddons(field: FieldDef<unknown>, fieldRegistry: ReadonlyMap<string, FieldTypeDefinition>, kindRegistry: ReadonlyMap<string, AddonKindDefinition>, source: 'json' | 'inline'): {
+    addons: AnyAddon[];
+    warnings: AddonWarning[];
+};
+/**
+ * Recursively walk a field tree, validating each field's addons. Returns a
+ * sanitized copy of the input field array plus accumulated warnings.
+ */
+declare function walkAndValidateAddons(fields: readonly FieldDef<unknown>[], fieldRegistry: ReadonlyMap<string, FieldTypeDefinition>, kindRegistry: ReadonlyMap<string, AddonKindDefinition>, source: 'json' | 'inline'): {
+    fields: FieldDef<unknown>[];
+    warnings: AddonWarning[];
+};
+
+/**
+ * Options accepted by {@link sanitizeFormConfig}.
+ */
+interface SanitizeFormConfigOptions {
+    /**
+     * Whether the config originated from JSON (server-driven) or inline
+     * TypeScript code.
+     *
+     * - `'inline'` (default): keeps everything; assumes the config is
+     *   authored in code and code-only constructs (inline `action`
+     *   functions, `component` kind) are intentional. The default avoids
+     *   silently stripping inline behaviour during in-process authoring.
+     * - `'json'`: drops code-only addon kinds (`component`, inline
+     *   `action: function`) with a warning, since they cannot survive
+     *   serialization. Use this when sanitising configs received from a
+     *   backend / form-builder UI.
+     */
+    source?: 'json' | 'inline';
+}
+/**
+ * Result of a `sanitizeFormConfig` call.
+ */
+interface SanitizedFormConfig {
+    /** Sanitized config — invalid addons stripped from the field tree. */
+    sanitized: FormConfig;
+    /** Structured list of every addon that was dropped, and why. */
+    warnings: readonly AddonWarning[];
+}
+/**
+ * Walk a `FormConfig`, validate every field's addons against the active
+ * `FIELD_REGISTRY` and `ADDON_KIND_REGISTRY`, and return a sanitized copy
+ * plus a list of dropped-addon warnings.
+ *
+ * Distinct from the INTERNAL `validateFormConfig` in
+ * `utils/config-validation/config-validator.ts` (which throws on
+ * structural errors like duplicate keys / unknown field types). This
+ * helper is the PUBLIC, lenient addon-shape pass — renamed to
+ * `sanitizeFormConfig` to avoid the name collision.
+ *
+ * Lenient by design: invalid addons are dropped (with warnings) rather than
+ * thrown. The form keeps rendering even when the backend ships an addon the
+ * FE doesn't understand.
+ *
+ * `<df-dynamic-form>` already runs this internally at form init — calling
+ * the public helper AND passing the original config to the form will
+ * double-emit warnings. Use this entry point only when you need the
+ * sanitized config or warning list outside the form (e.g., admin-UI
+ * diagnostics, build-time lints).
+ *
+ * Must be called within an Angular injection context — typically inside
+ * an admin-UI component or a `runInInjectionContext()` block on the server.
  *
  * @example
  * ```typescript
- * const wrappers = createWrappers(
- *   {
- *     wrapperName: 'section',
- *     loadComponent: () => import('./section-wrapper'),
- *     props: wrapperProps<SectionWrapper>(),
- *   },
- * );
- *
- * declare module '@ng-forge/dynamic-forms' {
- *   interface FieldRegistryWrappers extends InferWrapperRegistry<typeof wrappers> {}
+ * @Component({ ... })
+ * class AdminFormBuilder {
+ *   private readonly check = (cfg: FormConfig) => {
+ *     const { sanitized, warnings } = sanitizeFormConfig(cfg, { source: 'json' });
+ *     if (warnings.length > 0) {
+ *       this.diagnostics.set(warnings);
+ *     }
+ *     return sanitized;
+ *   };
  * }
  * ```
  */
-declare function wrapperProps<T>(): T;
+declare function sanitizeFormConfig(config: FormConfig, options?: SanitizeFormConfigOptions): SanitizedFormConfig;
+/**
+ * Default warning sink. Pass a `DynamicFormLogger` to route through the
+ * form's configured logger (respects `NoopLogger` opt-out); omit it to
+ * fall back to `console.warn` for build-time / admin-UI use cases that
+ * run outside an Angular injection context.
+ */
+declare function logAddonWarnings(warnings: readonly AddonWarning[], logger?: Logger): void;
+/**
+ * DI-free variant of {@link sanitizeFormConfig} for tooling that lives
+ * outside Angular's injector — build-time linters, MCP-side checks, CLI
+ * scripts.
+ *
+ * Caller passes the registries explicitly; the result has the same shape
+ * as the DI-bound version.
+ */
+declare function sanitizeFormConfigPure(config: FormConfig, fieldRegistry: ReadonlyMap<string, FieldTypeDefinition>, kindRegistry: ReadonlyMap<string, AddonKindDefinition>, options?: SanitizeFormConfigOptions): SanitizedFormConfig;
 
 interface FieldWithValidation {
     readonly required?: boolean;
@@ -5722,21 +6947,35 @@ interface BaseValueField<TProps, TValue, TMeta extends FieldMeta = FieldMeta, TN
     nullable?: TNullable;
 }
 declare function isValueField<TProps, TMeta extends FieldMeta = FieldMeta>(field: FieldDef<TProps, TMeta>): field is BaseValueField<TProps, ValueType, TMeta, boolean>;
-type ExcludedKeys$1 = 'type' | 'conditionals' | 'value' | 'valueType' | 'nullable' | 'disabled' | 'readonly' | 'hidden' | 'col' | 'minValue' | 'maxValue' | 'step' | 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern' | 'validators' | 'logic' | 'derivation' | 'schemas' | 'excludeValueIfHidden' | 'excludeValueIfDisabled' | 'excludeValueIfReadonly' | 'validateWhenHidden' | 'wrappers' | 'skipAutoWrappers' | 'skipDefaultWrappers';
+type ExcludedKeys$1 = 'type' | 'conditionals' | 'value' | 'valueType' | 'nullable' | 'disabled' | 'readonly' | 'hidden' | 'col' | 'minValue' | 'maxValue' | 'step' | 'required' | 'email' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern' | 'validators' | 'logic' | 'derivation' | 'schemas' | 'excludeValueIfHidden' | 'excludeValueIfDisabled' | 'excludeValueIfReadonly' | 'validateWhenHidden' | 'wrappers' | 'skipAutoWrappers' | 'skipDefaultWrappers' | 'addons';
 type ValueFieldComponent<T extends BaseValueField<Record<string, unknown> | unknown, unknown, FieldMeta, boolean>> = Prettify<WithInputSignals<Omit<T, ExcludedKeys$1>>>;
 
-interface BaseCheckedField<TProps, TMeta extends FieldMeta = FieldMeta> extends FieldDef<TProps, TMeta>, FieldWithValidation {
-    value?: boolean;
+interface BaseCheckedField<TProps, TMeta extends FieldMeta = FieldMeta, TNullable extends boolean = false> extends FieldDef<TProps, TMeta>, FieldWithValidation {
+    value?: TNullable extends true ? boolean | null : boolean;
     /**
      * Placeholder text displayed when the field is empty.
      * Supports static strings, Observables, and Signals for dynamic content.
      */
     placeholder?: DynamicText;
     required?: boolean;
+    /**
+     * Whether the field accepts `null` as a valid value.
+     *
+     * When `true`, `value` may be `null` and an omitted `value` resolves to `null`
+     * (rather than the type-specific empty default of `false`). Orthogonal to `required`.
+     *
+     * The data model is decoupled from the UI: a null value is a legitimate
+     * "undecided" state at the storage / OpenAPI layer. Whether the rendered
+     * checkbox shows an indeterminate visual is controlled separately via
+     * `props.indeterminate` and is not driven by this flag.
+     *
+     * @default false
+     */
+    nullable?: TNullable;
 }
-declare function isCheckedField<TProps, TMeta extends FieldMeta = FieldMeta>(field: FieldDef<TProps, TMeta>): field is BaseCheckedField<TProps, TMeta>;
-type ExcludedKeys = 'type' | 'conditionals' | 'value' | 'disabled' | 'readonly' | 'hidden' | 'col' | keyof FieldWithValidation | 'excludeValueIfHidden' | 'excludeValueIfDisabled' | 'excludeValueIfReadonly' | 'validateWhenHidden' | 'wrappers' | 'skipAutoWrappers' | 'skipDefaultWrappers';
-type CheckedFieldComponent<T extends BaseCheckedField<Record<string, unknown> | unknown>> = Prettify<WithInputSignals<Omit<T, ExcludedKeys>>>;
+declare function isCheckedField<TProps, TMeta extends FieldMeta = FieldMeta>(field: FieldDef<TProps, TMeta>): field is BaseCheckedField<TProps, TMeta, boolean>;
+type ExcludedKeys = 'type' | 'conditionals' | 'value' | 'nullable' | 'disabled' | 'readonly' | 'hidden' | 'col' | keyof FieldWithValidation | 'excludeValueIfHidden' | 'excludeValueIfDisabled' | 'excludeValueIfReadonly' | 'validateWhenHidden' | 'wrappers' | 'skipAutoWrappers' | 'skipDefaultWrappers' | 'addons';
+type CheckedFieldComponent<T extends BaseCheckedField<Record<string, unknown> | unknown, FieldMeta, boolean>> = Prettify<WithInputSignals<Omit<T, ExcludedKeys>>>;
 
 declare function applyValidator(config: ValidatorConfig, fieldPath: SchemaPath<any> | SchemaPathTree<any>): void;
 declare function applyValidators(configs: ValidatorConfig[], fieldPath: SchemaPath<any> | SchemaPathTree<any>): void;
@@ -6852,71 +8091,6 @@ declare class ContainerFieldComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ContainerFieldComponent, "div[container-field]", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "hidden": { "alias": "hidden"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-/**
- * Type representing a FieldTree for an array.
- * Extends FieldTree to add numeric indexing for accessing item FieldTrees.
- */
-type ArrayFieldTree<T> = FieldTree<T[]> & {
-    readonly [index: number]: FieldTree<T> | undefined;
-};
-/**
- * Get the length of an array FieldTree.
- */
-declare function getArrayLength<T>(arrayFieldTree: ArrayFieldTree<T>): number;
-/**
- * Read-only view of a single field's observable state.
- *
- * Whitelisted read signals copied from Angular Signal Forms' `FieldState` so wrappers
- * can observe a field without being able to mutate it. New write-capable members
- * added in future Angular versions are excluded by default (the `Pick` list stays
- * the source of truth).
- *
- * `value` is narrowed from `WritableSignal<TValue>` to `Signal<TValue>` so consumers
- * cannot write through it.
- */
-interface ReadonlyFieldTree<TValue = unknown> {
-    readonly value: Signal<TValue>;
-    readonly valid: Signal<boolean>;
-    readonly invalid: Signal<boolean>;
-    readonly touched: Signal<boolean>;
-    readonly dirty: Signal<boolean>;
-    readonly required: Signal<boolean>;
-    readonly disabled: Signal<boolean>;
-    readonly hidden: Signal<boolean>;
-    readonly errors: Signal<readonly unknown[]>;
-}
-/**
- * Build a `ReadonlyFieldTree` by extracting the whitelisted read signals from a
- * Signal Forms `FieldTree`. Returns a fresh plain object — no casting, no proxying,
- * so consumers only see the narrow surface and Angular's `WritableSignal` capability
- * on `value` is hidden.
- */
-declare function toReadonlyFieldTree<TValue>(field: FieldTree<TValue>): ReadonlyFieldTree<TValue>;
-
-/**
- * Input shape passed to a wrapper component via the `fieldInputs` input.
- *
- * Carries the wrapped field's mapper outputs plus an optional `field`
- * read-only view. Wrappers reached through a container path (which has
- * no FieldTree of its own) receive `fieldInputs === undefined`, so any
- * wrapper that reads `fieldInputs.field` must guard for it.
- *
- * Mappers must emit new rawInputs objects per tick rather than mutating
- * the previous one — this bag is a shallow spread, so mutations to shared
- * nested values leak to downstream wrappers.
- */
-interface WrapperFieldInputs {
-    readonly key: string;
-    readonly label?: string;
-    readonly placeholder?: string;
-    readonly className?: string;
-    readonly props?: Record<string, unknown>;
-    readonly validationMessages?: Record<string, string>;
-    readonly defaultValidationMessages?: Record<string, string>;
-    readonly field?: ReadonlyFieldTree;
-    readonly [key: string]: unknown;
-}
-
 /**
  * Native JavaScript utility functions to replace lodash-es
  * These are simple implementations for common object manipulation patterns
@@ -6995,5 +8169,5 @@ declare class RootFormRegistryService {
  */
 declare const INITIALIZATION_TIMEOUT_MS: InjectionToken<number>;
 
-export { ARRAY_CONTEXT, AppendArrayItemEvent, ArrayFieldComponent, BUILT_IN_FIELDS, ConsoleLogger, ContainerFieldComponent, DEFAULT_PROPS, DEFAULT_VALIDATION_MESSAGES, DEFAULT_WRAPPERS, DynamicForm, DynamicFormError, DynamicFormLogger, DynamicTextPipe, EventBus, EventDispatcher, FIELD_REGISTRY, FIELD_SIGNAL_CONTEXT, FORM_OPTIONS, FormClearEvent, FormResetEvent, GROUP_CONTEXT, GroupFieldComponent, INITIALIZATION_TIMEOUT_MS, InsertArrayItemEvent, MoveArrayItemEvent, NextPageEvent, NoopLogger, PageChangeEvent, PopArrayItemEvent, PrependArrayItemEvent, PreviousPageEvent, RemoveAtIndexEvent, RootFormRegistryService, ShiftArrayItemEvent, SubmitEvent, WRAPPER_REGISTRY, applyMetaToElement, applyValidator, applyValidators, arrayEvent, arrayFieldMapper, baseFieldMapper, buildBaseInputs, containerFieldMapper, createField, createWrappers, dynamicTextToObservable, evaluateNonFieldDisabled, evaluateNonFieldHidden, field, formConfig, getArrayLength, groupFieldMapper, hasFormValue, interpolateParams, isArrayField, isCheckedField, isContainerField, isContainerTypedField, isDisplayOnlyField, isEqual, isFormStateCondition, isGroupField, isLeafField, isPageField, isRowField, isSimplifiedArrayField, isValueBearingField, isValueField, isWrapperTypeDefinition, isWrappersBundle, omit, pageFieldMapper, provideDynamicForm, resolveNextButtonDisabled, resolveNonFieldDisabled, resolveNonFieldHidden, resolveSubmitButtonDisabled, resolveTokens, rowFieldMapper, textFieldMapper, toReadonlyFieldTree, withEventFormValue, withLoggerConfig, withPreviousValue, withValidationExecutionDefaults, withValueExclusionDefaults, wrapperProps };
-export type { ArrayAllowedChildren, ArrayButtonConfig, ArrayContext, ArrayField, ArrayFieldTree, ArrayItemContext, ArrayItemDefinitionTemplate, ArrayItemTemplate, AsyncCondition, AsyncConditionFunction, AsyncCustomValidator, AsyncDerivationFunction, AsyncValidatorConfig, AvailableFieldTypes, BaseCheckedField, BaseValidatorConfig, BaseValueField, BuiltInValidatorConfig, ButtonLogicContext, CheckedFieldComponent, ConditionalExpression, ContainerAllowedChildren, ContainerField, ContainerFieldTypes, CssWrapper, CustomFnConfig, CustomFunction, CustomValidator, CustomValidatorConfig, DeclarativeHttpValidatorConfig, DynamicFormFieldRegistry, DynamicText, EvaluationContext, ExtractField, ExtractFieldDefs, ExtractFormValue, FieldComponent, FieldDef, FieldMeta, FieldOption, FieldPathAccess, FieldRegistryContainers, FieldRegistryLeaves, FieldRegistryWrappers, FieldScope, FieldSignalContext, FieldStateContext, FieldStateInfo, FieldTypeDefinition, FieldWithValidation, FieldWrapper, FormConfig, FormEvent, FormEventConstructor, FormFieldStateMap, FormMode, FormModeDetectionResult, FormOptions, FormStateCondition, GroupAllowedChildren, GroupField, HttpCondition, HttpCustomValidator, HttpRequestConfig, HttpResourceRequest, HttpValidationResponseMapping, InferFormValue$1 as InferFormValue, InferWrapperRegistry, LeafFieldTypes, Logger, LogicConfig, MapperFn, NarrowField, NarrowFields, NextButtonOptions, NonFieldLogicConfig, NonFieldLogicContext, NonFieldLogicType, PageAllowedChildren, PageField, Prettify, ReadonlyFieldTree, RegisteredFieldTypes, ResolvedValidationExecutionConfig, ResolvedValueExclusionConfig, RowAllowedChildren, RowField, SchemaApplicationConfig, SchemaDefinition, SimplifiedArrayField, StateLogicConfig, SubmissionActionResult, SubmissionConfig, SubmitButtonOptions, TextElementType, TextField, TextProps, TokenContext, ValidationError, ValidationExecutionConfig, ValidationMessages, ValidatorConfig, ValueExclusionConfig, ValueFieldComponent, ValueHandlingMode, ValueType, WithInputSignals, WrapperConfig, WrapperFieldInputs, WrapperRegistration, WrapperTypeDefinition, WrappersBundle };
+export { ADDON_ACTION_HANDLERS, ADDON_ACTION_REGISTRY, ADDON_KIND_COMPONENT_CACHE, ADDON_KIND_DEFINITIONS, ADDON_KIND_REGISTRY, ARRAY_CONTEXT, AppendArrayItemEvent, ArrayFieldComponent, BUILT_IN_FIELDS, ComponentAddonComponent, ConsoleLogger, ContainerFieldComponent, DEFAULT_PROPS, DEFAULT_VALIDATION_MESSAGES, DEFAULT_WRAPPERS, DF_FIELD_TEMPLATES, DfAddonSlot, DfTemplate, DynamicForm, DynamicFormError, DynamicFormLogger, DynamicTextPipe, EventBus, EventDispatcher, FIELD_REGISTRY, FIELD_SIGNAL_CONTEXT, FORM_OPTIONS, FormClearEvent, FormResetEvent, GROUP_CONTEXT, GroupFieldComponent, INITIALIZATION_TIMEOUT_MS, InsertArrayItemEvent, MoveArrayItemEvent, NextPageEvent, NoopLogger, PageChangeEvent, PopArrayItemEvent, PrependArrayItemEvent, PreviousPageEvent, RemoveAtIndexEvent, RootFormRegistryService, ShiftArrayItemEvent, SubmitEvent, TemplateAddonComponent, TextAddonComponent, WRAPPER_REGISTRY, applyMetaToElement, applyValidator, applyValidators, arrayEvent, arrayFieldMapper, baseFieldMapper, buildBaseInputs, containerFieldMapper, createField, createWrappers, dynamicTextToObservable, evaluateNonFieldDisabled, evaluateNonFieldHidden, field, formConfig, formatAddonWarning, getArrayLength, groupFieldMapper, hasFormValue, injectAddonKindRegistry, injectFieldSignalContext, injectFieldsSupportingAddons, interpolateParams, isArrayField, isCheckedField, isContainerField, isContainerTypedField, isDisplayOnlyField, isEqual, isFieldBoundContext, isFormStateCondition, isGroupField, isLeafField, isPageField, isRowField, isSimplifiedArrayField, isValueBearingField, isValueField, isWrapperTypeDefinition, isWrappersBundle, logAddonWarnings, omit, pageFieldMapper, provideAddonActions, provideDynamicForm, resolveDynamicValue, resolveNextButtonDisabled, resolveNonFieldDisabled, resolveNonFieldHidden, resolveSubmitButtonDisabled, resolveTokens, rowFieldMapper, runPresetAction, sanitizeFormConfig, sanitizeFormConfigPure, textFieldMapper, toReadonlyFieldTree, validateFieldAddons, walkAndValidateAddons, withCustomAddon, withEventFormValue, withLegacyStatusClasses, withLoggerConfig, withPreviousValue, withValidationExecutionDefaults, withValueExclusionDefaults, wrapperProps, writeToFieldValue };
+export type { AddonActionContext, AddonActionHandler, AddonActionPreset, AddonActionsFeature, AddonKindDefinition, AddonKindSchema, AddonShapeValidator, AddonSlot, AddonWarning, AnyAddon, ArrayAllowedChildren, ArrayButtonConfig, ArrayContext, ArrayField, ArrayFieldTree, ArrayItemContext, ArrayItemDefinitionTemplate, ArrayItemTemplate, AsyncCondition, AsyncConditionFunction, AsyncCustomValidator, AsyncDerivationFunction, AsyncValidatorConfig, AvailableFieldTypes, BaseAddon, BaseCheckedField, BaseValidatorConfig, BaseValueField, BuiltInValidatorConfig, ButtonLogicContext, CheckedFieldComponent, CommonAddonActionPreset, CommonAddonSlot, ComponentAddon, ConditionalExpression, ContainerAllowedChildren, ContainerField, ContainerFieldTypes, CssWrapper, CustomFnConfig, CustomFunction, CustomValidator, CustomValidatorConfig, DeclarativeHttpValidatorConfig, DynamicFormActionRegistry, DynamicFormAddonActionPresetRegistry, DynamicFormAddonRegistry, DynamicFormAddonSlotRegistry, DynamicFormFieldRegistry, DynamicText, DynamicValue, EvaluationContext, ExtractField, ExtractFieldDefs, ExtractFormValue, FieldAddonSupport, FieldAddonSupportEntry, FieldBoundAddonActionContext, FieldComponent, FieldDef, FieldMeta, FieldOption, FieldPathAccess, FieldRegistryContainers, FieldRegistryLeaves, FieldRegistryWrappers, FieldScope, FieldSignalContext, FieldStateContext, FieldStateInfo, FieldTypeDefinition, FieldWithValidation, FieldWrapper, FormConfig, FormEvent, FormEventConstructor, FormFieldStateMap, FormMode, FormModeDetectionResult, FormOptions, FormStateCondition, GroupAllowedChildren, GroupField, HttpCondition, HttpCustomValidator, HttpRequestConfig, HttpResourceRequest, HttpValidationResponseMapping, InferFormValue$1 as InferFormValue, InferWrapperRegistry, LeafFieldTypes, Logger, LogicConfig, MapperFn, NarrowField, NarrowFields, NextButtonOptions, NonFieldLogicConfig, NonFieldLogicContext, NonFieldLogicType, OrphanAddonActionContext, PageAllowedChildren, PageField, PresetCollaborators, Prettify, ReadonlyFieldTree, RegisteredActionRef, RegisteredFieldTypes, ResolvedValidationExecutionConfig, ResolvedValueExclusionConfig, RowAllowedChildren, RowField, SanitizeFormConfigOptions, SanitizedFormConfig, SchemaApplicationConfig, SchemaDefinition, SimplifiedArrayField, StateLogicConfig, SubmissionActionResult, SubmissionConfig, SubmitButtonOptions, TemplateAddon, TextAddon, TextElementType, TextField, TextProps, TokenContext, ValidationError, ValidationExecutionConfig, ValidationMessages, ValidatorConfig, ValueExclusionConfig, ValueFieldComponent, ValueHandlingMode, ValueType, WithInputSignals, WrapperConfig, WrapperFieldInputs, WrapperRegistration, WrapperTypeDefinition, WrappersBundle };