@ng-forge/dynamic-forms 0.9.0-next.9 → 0.10.0-next.1

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

@@ -1,7 +1,9 @@
-import { FormEvent, FieldDef, FormEventConstructor, StateLogicConfig, BaseCheckedField, BaseValueField, FieldMeta, FieldOption, ValidationMessages, ArrayAllowedChildren, NonFieldLogicConfig, NextPageEvent, PreviousPageEvent, FieldWithValidation } from '@ng-forge/dynamic-forms';
-export { NonFieldLogicConfig, NonFieldLogicContext, NonFieldLogicType, isEqual, resolveNonFieldDisabled, resolveNonFieldHidden } from '@ng-forge/dynamic-forms';
-import { Signal, Injector, ElementRef } from '@angular/core';
-import { FieldTree } from '@angular/forms/signals';
+import { FormEvent, FieldDef, FormEventConstructor, StateLogicConfig, BaseCheckedField, FieldMeta, BaseValueField, FieldOption, ArrayAllowedChildren, NonFieldLogicConfig, NextPageEvent, PreviousPageEvent, FieldWithValidation, ValidationMessages, DynamicText, ArrayItemContext, AnyAddon, BaseAddon, AddonActionHandler, DynamicValue, WrapperFieldInputs, AddonActionContext, EventBus } from '@ng-forge/dynamic-forms';
+export { FieldWrapper, InferWrapperRegistry, NonFieldLogicConfig, NonFieldLogicContext, NonFieldLogicType, WrapperFieldInputs, WrapperRegistration, WrapperTypeDefinition, WrappersBundle, createWrappers, isEqual, isWrappersBundle, resolveNonFieldDisabled, resolveNonFieldHidden, wrapperProps } from '@ng-forge/dynamic-forms';
+import * as i0 from '@angular/core';
+import { Signal, Injector, ElementRef, InjectionToken, Provider, WritableSignal, Type } from '@angular/core';
+import { FieldTree, SchemaPath } from '@angular/forms/signals';
+import { ComponentFixture } from '@angular/core/testing';
 
 /**
  * Event arguments that can contain static values or tokens to be resolved at runtime.
@@ -38,7 +40,7 @@ interface ButtonField<TProps, TEvent extends FormEvent> extends FieldDef<TProps>
     logic?: StateLogicConfig[];
 }
 
-interface CheckboxField<TProps> extends BaseCheckedField<TProps> {
+interface CheckboxField<TProps, TNullable extends boolean = boolean> extends BaseCheckedField<TProps, FieldMeta, TNullable> {
     type: 'checkbox';
 }
 
@@ -390,7 +392,7 @@ interface TextareaField<TProps = TextareaProps, TNullable extends boolean = bool
     maxLength?: number | undefined;
 }
 
-interface ToggleField<TProps> extends BaseCheckedField<TProps> {
+interface ToggleField<TProps, TNullable extends boolean = boolean> extends BaseCheckedField<TProps, FieldMeta, TNullable> {
     type: 'toggle';
 }
 
@@ -435,10 +437,9 @@ declare function resolveValueFieldContext(): ValueFieldContext;
  * @param fieldDef The value field definition
  * @param ctx The resolved value field context
  * @param defaultProps Default props from the form configuration (may be undefined if not configured)
- * @param defaultValidationMessages Default validation messages from the form configuration (may be undefined if not configured)
  * @returns Record of input names to values
  */
-declare function buildValueFieldInputs<TProps, TValue = unknown>(fieldDef: BaseValueField<TProps, TValue, FieldMeta, boolean>, ctx: ValueFieldContext, defaultProps?: Record<string, unknown>, defaultValidationMessages?: ValidationMessages): Record<string, unknown>;
+declare function buildValueFieldInputs<TProps, TValue = unknown>(fieldDef: BaseValueField<TProps, TValue, FieldMeta, boolean>, ctx: ValueFieldContext, defaultProps?: Record<string, unknown>): Record<string, unknown>;
 /**
  * Maps a value field definition to component inputs.
  *
@@ -470,7 +471,7 @@ declare function valueFieldMapper<TProps = unknown, TValue = unknown>(fieldDef:
  * @param fieldDef The checkbox field definition
  * @returns Signal containing Record of input names to values for ngComponentOutlet
  */
-declare function checkboxFieldMapper(fieldDef: BaseCheckedField<unknown>): Signal<Record<string, unknown>>;
+declare function checkboxFieldMapper(fieldDef: BaseCheckedField<unknown, FieldMeta, boolean>): Signal<Record<string, unknown>>;
 
 /**
  * Maps a datepicker field to component inputs.
@@ -789,5 +790,580 @@ interface MetaTrackingOptions {
  */
 declare function setupMetaTracking(elementRef: ElementRef<HTMLElement>, meta: Signal<FieldMeta | undefined>, options?: MetaTrackingOptions): void;
 
-export { addArrayItemButtonMapper, buildArrayButtonEventContext, buildValueFieldInputs, buttonFieldMapper, checkboxFieldMapper, createResolvedErrorsSignal, datepickerFieldMapper, insertArrayItemButtonMapper, nextButtonFieldMapper, optionsFieldMapper, popArrayItemButtonMapper, prependArrayItemButtonMapper, previousButtonFieldMapper, removeArrayItemButtonMapper, resolveArrayButtonContext, resolveArrayButtonEventArgs, resolveValueFieldContext, setupMetaTracking, shiftArrayItemButtonMapper, shouldShowErrors, submitButtonFieldMapper, valueFieldMapper };
-export type { ArrayButtonContext, ArrayButtonEventContext, Autocapitalize, AutocompleteValue, BaseArrayAddButtonField, BaseArrayRemoveButtonField, BaseInsertArrayItemButtonField, BaseNavigationButtonField, ButtonField, CheckboxField, DatepickerField, DatepickerProps, EnterKeyHint, EventArg, EventArgs, FieldWithOptions, HtmlInputType, InferInputValue, InputField, InputMeta, InputMode, InputProps, InputType, InputTypeToValueType, MetaTrackingOptions, MultiCheckboxField, NumericInputType, RadioField, ResolvedError, SelectField, SelectProps, SliderField, StringInputType, TextareaField, TextareaMeta, TextareaProps, TextareaWrap, ToggleField, ValueFieldContext };
+/**
+ * Creates a signal that computes the aria-describedby value based on errors and hint state.
+ * Errors take precedence over hints - when errors are displayed, the hint is hidden.
+ * Only the first error is displayed (single error ID, not indexed).
+ *
+ * @param errorsToDisplay Signal containing the array of errors currently being displayed
+ * @param errorId Signal containing the ID for the error element (single error only)
+ * @param hintId Signal containing the ID for the hint element
+ * @param hasHint Function that returns true if a hint is configured
+ * @returns Signal containing the aria-describedby value or null
+ */
+declare function createAriaDescribedBySignal(errorsToDisplay: Signal<ResolvedError[]>, errorId: Signal<string>, hintId: Signal<string>, hasHint: () => boolean): Signal<string | null>;
+
+/**
+ * Base directive composed into every ng-forge component via `hostDirectives`.
+ * Owns the universal identity inputs (`key`, `className`) and the host
+ * bindings that every field shape — value-bearing, action, future container —
+ * shares: `[id]`, `[attr.data-testid]`, `[class]`.
+ *
+ * Shape-specific add-ons (`NgForgeField` for value fields, `NgForgeAction`
+ * for actions) inject this directive and read `key()` / `className()` from
+ * it. Source-of-truth concerns like `hidden` / `disabled` live on the add-on
+ * because they vary by shape (value fields derive from `field()()`; actions
+ * receive direct inputs).
+ *
+ * Selectorless — usage is exclusively via `hostDirectives`. Prefer the
+ * `NG_FORGE_FIELD` / `NG_FORGE_ACTION` presets rather than composing Shell
+ * directly.
+ */
+declare class NgForgeFieldShell {
+    readonly key: i0.InputSignal<string>;
+    readonly className: i0.InputSignal<string>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgForgeFieldShell, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgForgeFieldShell, never, never, { "key": { "alias": "key"; "required": true; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/** Input names forwarded onto `NgForgeFieldShell` via `hostDirectives`. */
+declare const NG_FORGE_FIELD_SHELL_INPUTS: readonly ["key", "className"];
+
+/**
+ * Value-bearing add-on directive — composed alongside `NgForgeFieldShell` via
+ * the `NG_FORGE_FIELD` preset. Owns the value/validation/aria plumbing every
+ * value-bearing field needs.
+ *
+ * The Shell owns universal identity (`key`, `className`, `[id]`,
+ * `[attr.data-testid]`, `[class]`); this directive injects Shell and adds
+ * field-driven bindings (`[attr.hidden]`, `[attr.aria-disabled]`), the
+ * standard value-field inputs (`field`, `label`, `placeholder`, `tabIndex`,
+ * `props`, `meta`, `validationMessages`), the derived error/aria signals,
+ * and the meta-tracking claim contract.
+ *
+ * @example
+ * ```ts
+ * \@Component({
+ *   hostDirectives: NG_FORGE_FIELD,
+ *   imports: [NgForgeControl, FormField],
+ *   template: `
+ *     <label [for]="ngf.key() + '-input'">{{ ngf.label() | dynamicText | async }}</label>
+ *     <input ngForgeControl [id]="ngf.key() + '-input'" [formField]="ngf.field()" />
+ *     @if (ngf.errorsToDisplay()[0]; as e) {
+ *       <span [id]="ngf.errorId()">{{ e.message }}</span>
+ *     }
+ *   `,
+ * })
+ * export class MyInputField {
+ *   protected readonly ngf = injectNgForgeField<string>();
+ * }
+ * ```
+ *
+ * Selectorless — usage is exclusively via `hostDirectives`. Prefer the
+ * `NG_FORGE_FIELD` preset over composing this directive manually.
+ */
+declare class NgForgeField {
+    private readonly shell;
+    /** Shell-owned key, re-exported as plain `Signal<string>` so it doesn't get flagged by the host-directive input-lockstep assertion. */
+    readonly key: Signal<string>;
+    /** Shell-owned className, re-exported as plain `Signal<string>` for the same reason. */
+    readonly className: Signal<string>;
+    readonly field: i0.InputSignal<FieldTree<unknown>>;
+    readonly label: i0.InputSignal<DynamicText | undefined>;
+    readonly placeholder: i0.InputSignal<DynamicText | undefined>;
+    readonly tabIndex: i0.InputSignal<number | undefined>;
+    readonly props: i0.InputSignal<unknown>;
+    readonly meta: i0.InputSignal<FieldMeta | undefined>;
+    readonly validationMessages: i0.InputSignal<ValidationMessages | undefined>;
+    private readonly defaultValidationMessages;
+    readonly errors: Signal<ResolvedError[]>;
+    readonly showErrors: Signal<boolean>;
+    readonly errorsToDisplay: Signal<ResolvedError[]>;
+    readonly errorId: Signal<string>;
+    readonly hintId: Signal<string>;
+    readonly ariaInvalid: Signal<boolean>;
+    readonly ariaRequired: Signal<true | null>;
+    readonly ariaDescribedBy: Signal<string | null>;
+    private readonly _claimed;
+    /** @internal Marker directives + ambient sub-components call this on construction. */
+    markClaimed(): void;
+    private readonly logger;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgForgeField, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgForgeField, never, never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "tabIndex": { "alias": "tabIndex"; "required": false; "isSignal": true; }; "props": { "alias": "props"; "required": false; "isSignal": true; }; "meta": { "alias": "meta"; "required": false; "isSignal": true; }; "validationMessages": { "alias": "validationMessages"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/**
+ * Inputs forwarded onto `NgForgeField` via `hostDirectives`. Excludes
+ * `key` / `className` (forwarded to `NgForgeFieldShell` separately via
+ * `NG_FORGE_FIELD_SHELL_INPUTS`). Most consumers shouldn't reference this
+ * directly — use the `NG_FORGE_FIELD` preset.
+ */
+declare const NG_FORGE_VALUE_FIELD_INPUTS: readonly ["field", "label", "placeholder", "tabIndex", "props", "meta", "validationMessages"];
+/**
+ * `NgForgeField` typed for a specific value type. The directive itself stores
+ * `field` as `Signal<FieldTree<unknown>>` because Angular's `hostDirectives`
+ * doesn't propagate generics — `injectNgForgeField<T>()` narrows it at the
+ * inject site so consumers don't have to declare a separate cast computed.
+ */
+type TypedNgForgeField<T> = Omit<NgForgeField, 'field'> & {
+    readonly field: Signal<FieldTree<T>>;
+};
+/**
+ * Typed wrapper around `inject(NgForgeField)`. The generic narrows the
+ * `field` signal to `Signal<FieldTree<T>>` for the calling component's value
+ * type. The cast is unchecked — the runtime contract is that mappers only
+ * forward a `field` whose value type matches the field-type definition.
+ *
+ * @example
+ * ```ts
+ * protected readonly ngf = injectNgForgeField<string>();
+ * // ngf.field() is Signal<FieldTree<string>>; ngf.errors() etc. unchanged
+ * ```
+ */
+declare function injectNgForgeField<T = unknown>(): TypedNgForgeField<T>;
+
+/**
+ * Action add-on directive — composed alongside `NgForgeFieldShell` via the
+ * `NG_FORGE_ACTION` preset. Owns the inputs + dispatch logic every button /
+ * action component needs (label, disabled, event, eventArgs, …) plus the
+ * `[attr.hidden]` / `[attr.aria-disabled]` host bindings driven by its own
+ * inputs (no field tree).
+ *
+ * Components call `action.dispatch()` from their click handler; this
+ * directive resolves any `eventArgs` tokens via the optional `ARRAY_CONTEXT`
+ * and dispatches the configured `event` through the `EventBus`.
+ *
+ * @example
+ * ```ts
+ * \@Component({
+ *   hostDirectives: NG_FORGE_ACTION,
+ *   template: `<button (click)="action.dispatch()" [disabled]="action.disabled()">{{ action.label() }}</button>`,
+ * })
+ * export class MyButton {
+ *   protected readonly action = inject(NgForgeAction);
+ * }
+ * ```
+ *
+ * Selectorless — usage is exclusively via `hostDirectives`. Prefer the
+ * `NG_FORGE_ACTION` preset over composing this directive manually.
+ */
+declare class NgForgeAction<TEvent extends FormEvent = FormEvent> {
+    private readonly shell;
+    readonly key: Signal<string>;
+    readonly className: Signal<string>;
+    readonly label: i0.InputSignal<DynamicText>;
+    readonly disabled: i0.InputSignal<boolean>;
+    readonly hidden: i0.InputSignal<boolean>;
+    readonly tabIndex: i0.InputSignal<number | undefined>;
+    readonly event: i0.InputSignal<FormEventConstructor<TEvent> | undefined>;
+    readonly eventArgs: i0.InputSignal<EventArgs | undefined>;
+    readonly eventContext: i0.InputSignal<ArrayItemContext | undefined>;
+    readonly props: i0.InputSignal<unknown>;
+    private readonly eventBus;
+    private readonly arrayContext;
+    /**
+     * Dispatch the configured event through the EventBus. Resolves `eventArgs`
+     * tokens (`$key`, `$index`, `$arrayKey`, `formValue`, …) against the
+     * ambient array context if present, falling back to a static `eventContext`
+     * input or the field's own `key` otherwise. No-op when `event` is unset
+     * (e.g. submit buttons handled by the native form lifecycle).
+     */
+    dispatch(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgForgeAction<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgForgeAction<any>, never, never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "hidden": { "alias": "hidden"; "required": false; "isSignal": true; }; "tabIndex": { "alias": "tabIndex"; "required": false; "isSignal": true; }; "event": { "alias": "event"; "required": false; "isSignal": true; }; "eventArgs": { "alias": "eventArgs"; "required": false; "isSignal": true; }; "eventContext": { "alias": "eventContext"; "required": false; "isSignal": true; }; "props": { "alias": "props"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/**
+ * Inputs forwarded onto `NgForgeAction` via `hostDirectives`. Excludes
+ * `key` / `className` (forwarded to `NgForgeFieldShell` separately via
+ * `NG_FORGE_FIELD_SHELL_INPUTS`). Most consumers shouldn't reference this
+ * directly — use the `NG_FORGE_ACTION` preset.
+ */
+declare const NG_FORGE_ACTION_INPUTS: readonly ["label", "disabled", "hidden", "tabIndex", "event", "eventArgs", "eventContext", "props"];
+/**
+ * Typed wrapper around `inject(NgForgeAction)`. The generic narrows the
+ * `event` input to a specific FormEvent subclass.
+ *
+ * @example
+ * ```ts
+ * protected readonly action = injectNgForgeAction<SubmitEvent>();
+ * ```
+ */
+declare function injectNgForgeAction<TEvent extends FormEvent = FormEvent>(): NgForgeAction<TEvent>;
+
+/**
+ * Universal addon-array plumbing: signal-cached `hidden` resolution and
+ * slot bucketing. Used internally by the `NgForgeAddons` host wrapper —
+ * consumers should compose `NgForgeAddons` directly and inject the
+ * directive instance via `injectNgForgeAddons<TAddon>()`.
+ */
+declare class NgForgeAddonsBase {
+    /** Capture the host's injector so `toSignal` (inside `resolveDynamicValue`) ties to the host's `DestroyRef`. */
+    private readonly hostInjector;
+    /** Addon array mapped from `FieldDef.addons` by `buildBaseInputs`. */
+    readonly addons: i0.InputSignal<readonly AnyAddon[] | undefined>;
+    /**
+     * Per-addon `hidden` signal cache. Built via `explicitEffect` rather
+     * than `computed` because `toSignal` (inside `resolveDynamicValue` for
+     * Observable inputs) is disallowed in reactive contexts (NG0602).
+     */
+    private readonly _hiddenSignalCache;
+    readonly hiddenSignalCache: Signal<ReadonlyMap<AnyAddon, Signal<boolean>>>;
+    readonly visibleAddons: Signal<ReadonlyArray<AnyAddon>>;
+    readonly hasAddons: Signal<boolean>;
+    readonly prefixAddons: Signal<ReadonlyArray<AnyAddon>>;
+    readonly suffixAddons: Signal<ReadonlyArray<AnyAddon>>;
+    /**
+     * Visible addons grouped by their `slot` string. Convenience view for
+     * adapters with non-universal slots (e.g., Ionic `start` / `end`).
+     */
+    readonly addonsBySlot: Signal<ReadonlyMap<string, ReadonlyArray<AnyAddon>>>;
+    /** Secondary index keyed by `hidden` value identity. Catches the common case
+     *  where a FormConfig re-emit produces structurally-different-but-content-
+     *  identical addon objects — without this, every re-emit would spawn a new
+     *  `toSignal` subscription for each addon's hidden axis. */
+    private readonly _hiddenByValue;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgForgeAddonsBase, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgForgeAddonsBase, never, never, { "addons": { "alias": "addons"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/** Forwarded onto `NgForgeAddonsBase` via the `NgForgeAddons` wrapper. */
+declare const NG_FORGE_ADDONS_INPUTS: readonly ["addons"];
+/**
+ * Host wrapper for `NgForgeAddonsBase`. Consumers compose this directly:
+ *
+ * ```ts
+ * \@Component({
+ *   hostDirectives: [NgForgeFieldHost, NgForgeAddons],
+ *   template: `
+ *     @if (ngfa.hasAddons()) {
+ *       <p-inputgroup>
+ *         @for (a of ngfa.prefixAddons(); track $index) {
+ *           <df-addon-slot [addon]="a" [hidden]="ngfa.hiddenSignalCache().get(a)" />
+ *         }
+ *         <input ngForgeControl ... />
+ *       </p-inputgroup>
+ *     }
+ *   `,
+ * })
+ * export class MyInputField {
+ *   protected readonly ngfa = injectNgForgeAddons<MyInputAddon>();
+ * }
+ * ```
+ *
+ * The wrapper exists so `hostDirectives: [NgForgeAddons]` resolves
+ * cross-package — same constraint that drives `NgForgeFieldHost`.
+ */
+declare class NgForgeAddons {
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgForgeAddons, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgForgeAddons, never, never, {}, {}, never, never, true, [{ directive: typeof NgForgeAddonsBase; inputs: { "addons": "addons"; }; outputs: {}; }]>;
+}
+/** Narrowed view of `NgForgeAddonsBase` returned by `injectNgForgeAddons<TAddon>()`. */
+type TypedNgForgeAddons<TAddon extends AnyAddon = AnyAddon> = Omit<NgForgeAddonsBase, 'addons' | 'visibleAddons' | 'prefixAddons' | 'suffixAddons'> & {
+    readonly addons: Signal<ReadonlyArray<TAddon> | undefined>;
+    readonly visibleAddons: Signal<ReadonlyArray<TAddon>>;
+    readonly prefixAddons: Signal<ReadonlyArray<TAddon>>;
+    readonly suffixAddons: Signal<ReadonlyArray<TAddon>>;
+};
+/**
+ * Typed inject helper. Always resolves to the underlying
+ * `NgForgeAddonsBase` instance — the wrapper class has no instance
+ * fields of its own.
+ */
+declare function injectNgForgeAddons<TAddon extends AnyAddon = AnyAddon>(): TypedNgForgeAddons<TAddon>;
+
+/**
+ * Permissive shape the directive reads from `addon()`. Adapter-specific
+ * addon types (e.g., `PrimeButtonAddon`) narrow this at the inject site via
+ * `injectNgForgeAddonAction<T>()`.
+ */
+interface ActionAddonShape extends BaseAddon {
+    readonly preset?: string;
+    readonly actionRef?: string;
+    readonly action?: AddonActionHandler;
+    readonly disabled?: DynamicValue<boolean>;
+    readonly loading?: DynamicValue<boolean>;
+}
+/**
+ * Universal click-dispatch plumbing for action-style addons (icon buttons,
+ * labelled buttons, etc.): `disabled` / `loading` resolution from
+ * `DynamicValue<boolean>`, action context construction, and the
+ * `preset / actionRef / action` precedence dispatcher.
+ *
+ * Adapter button kinds (e.g., `prime-button`) compose `NgForgeAddonAction`
+ * and read state via `injectNgForgeAddonAction<TAddon>()`. Preset semantics
+ * are adapter-specific — register an `ADDON_PRESET_HANDLER` at the host
+ * field scope to receive preset dispatches.
+ */
+declare class NgForgeAddonActionBase {
+    private readonly actionRegistry;
+    private readonly presetHandler;
+    private readonly logger;
+    private readonly hostInjector;
+    readonly addon: i0.InputSignal<ActionAddonShape>;
+    readonly fieldInputs: i0.InputSignal<WrapperFieldInputs | undefined>;
+    /**
+     * Per-value caches for `disabled` / `loading` signal resolution. Keyed by
+     * the `DynamicValue` identity so a single `toSignal` subscription is
+     * shared across addon-reference swaps that pass the same Observable.
+     * Mirrors `NgForgeAddonsBase._hiddenByValue` — `resolveDynamicValue`
+     * cannot run inside `computed`/`linkedSignal.computation` because
+     * `toSignal` throws in reactive contexts (NG0602), and re-running it on
+     * every recomputation would leak subscriptions on each cycle.
+     */
+    private readonly _disabledByValue;
+    private readonly _loadingByValue;
+    private readonly _resolvedDisabled;
+    private readonly _resolvedLoading;
+    readonly disabled: Signal<boolean>;
+    readonly loading: Signal<boolean>;
+    constructor();
+    private _resolveAxis;
+    /**
+     * Resolve the click handler from the addon's three-axis click variant and
+     * invoke it. Precedence on multi-set: `preset > actionRef > action`. The
+     * validator drops multi-set configs at config-init time; this is
+     * defence-in-depth + a logged warning so the misconfiguration is loud.
+     */
+    dispatch(): void;
+    /**
+     * Build an `AddonActionContext` for handlers from the wrapper-style
+     * `fieldInputs` bag. Returns the field-bound variant when a host field
+     * is reachable, or the orphan variant otherwise.
+     *
+     * Resolution order for `setValue`:
+     * 1. `inputs.setValue` from the forwarded bag (preferred — populated by
+     *    `buildFieldInputs` in `DfFieldOutlet`).
+     * 2. Fallback reconstructed from `inputs.field` itself: although
+     *    `ReadonlyFieldTree.value` is type-narrowed to `Signal<T>`, the
+     *    underlying runtime object is the same `WritableSignal<T>` created
+     *    by Signal Forms (the read-only wrapping is type-level only, see
+     *    `toReadonlyFieldTree`). Casting back at the writer boundary
+     *    produces a working setValue for ANY field depth — top-level OR
+     *    nested under groups. This avoids the previous FSC-key navigation
+     *    that broke for grouped fields, where `inputs.key` is DOM-mangled
+     *    (`'user_address_street'`) and `fsc.form[key]` returns undefined.
+     *
+     * The orphan variant fires only when the bag carries no field tree at
+     * all — genuine "rendered outside a field" scenario.
+     */
+    buildActionContext(): AddonActionContext;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgForgeAddonActionBase, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgForgeAddonActionBase, never, never, { "addon": { "alias": "addon"; "required": true; "isSignal": true; }; "fieldInputs": { "alias": "fieldInputs"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/** Forwarded onto `NgForgeAddonActionBase` via the `NgForgeAddonAction` wrapper. */
+declare const NG_FORGE_ADDON_ACTION_INPUTS: readonly ["addon", "fieldInputs"];
+/**
+ * Host wrapper for `NgForgeAddonActionBase`. Consumers compose this directly:
+ *
+ * ```ts
+ * \@Component({
+ *   hostDirectives: [NgForgeAddonAction],
+ *   template: `
+ *     <p-button [loading]="action.loading()" [disabled]="action.disabled()"
+ *               (onClick)="action.dispatch()" />
+ *   `,
+ * })
+ * export class MyButtonAddon {
+ *   protected readonly action = injectNgForgeAddonAction<MyButtonAddon>();
+ * }
+ * ```
+ */
+declare class NgForgeAddonAction {
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgForgeAddonAction, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgForgeAddonAction, never, never, {}, {}, never, never, true, [{ directive: typeof NgForgeAddonActionBase; inputs: { "addon": "addon"; "fieldInputs": "fieldInputs"; }; outputs: {}; }]>;
+}
+/** Narrowed view of `NgForgeAddonActionBase` returned by `injectNgForgeAddonAction<T>()`. */
+type TypedNgForgeAddonAction<TAddon extends ActionAddonShape = ActionAddonShape> = Omit<NgForgeAddonActionBase, 'addon'> & {
+    readonly addon: Signal<TAddon>;
+};
+declare function injectNgForgeAddonAction<TAddon extends ActionAddonShape = ActionAddonShape>(): TypedNgForgeAddonAction<TAddon>;
+
+/**
+ * Adapter-supplied resolver for `preset` addon actions (e.g., `'clear'`,
+ * `'toggle-password-visibility'`). The universal click-dispatch directive
+ * (`NgForgeAddonAction`) delegates to this when an addon configures a
+ * `preset`; the adapter wires concrete preset semantics in its own
+ * provider scope.
+ *
+ * `NgForgeAddonAction` injects this with `{ optional: true }`. Addons that
+ * configure a preset on an adapter that hasn't registered a handler get a
+ * lenient warning at click time.
+ */
+interface AddonPresetHandler {
+    run(preset: string, ctx: AddonActionContext): void | Promise<void>;
+}
+declare const ADDON_PRESET_HANDLER: InjectionToken<AddonPresetHandler>;
+
+/**
+ * Marker directive applied to the canonical control element of an
+ * `NgForgeField`-using component. Forwards the field's `meta` AND
+ * parent-derived aria signals (`aria-invalid`, `aria-required`,
+ * `aria-describedby`) onto a target element.
+ *
+ * By default attributes land on the directive's own host. For wrapped
+ * controls (e.g. `<mat-checkbox>`, `<p-toggleSwitch>`) where the canonical
+ * native input is rendered as a descendant inside the wrapper, pass a CSS
+ * selector through the input alias — the directive caches the resolved
+ * descendant set and re-resolves only when the selector changes.
+ *
+ * @example Bare native control
+ * ```html
+ * <input ngForgeControl [formField]="ngf.field()" />
+ * ```
+ *
+ * @example Wrapped control with inner native input
+ * ```html
+ * <mat-checkbox ngForgeControl="input[type='checkbox']" [formField]="ngf.field()">
+ *   {{ ngf.label() }}
+ * </mat-checkbox>
+ * ```
+ *
+ * @example Dynamic option list (radios rendered in @for)
+ * ```html
+ * @for (option of options(); track option.value) {
+ *   <input type="radio" ngForgeControl [value]="option.value" />
+ * }
+ * ```
+ *
+ * Each `@for` iteration creates its own directive instance; Angular's
+ * structural lifecycle handles add/remove naturally.
+ */
+declare class NgForgeControl {
+    readonly target: i0.InputSignal<string | undefined>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgForgeControl, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgForgeControl, "[ngForgeControl]", never, { "target": { "alias": "ngForgeControl"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/**
+ * Selectorless companion directive for shadow-DOM-encapsulated components
+ * (PrimeNG `p-select`, Ionic web components, etc.) where no light-DOM child
+ * is the canonical control. Added to the component's `hostDirectives` so the
+ * field's `meta` + parent aria land on the component's own host element.
+ *
+ * For split parent/control components (e.g. `df-prime-select` rendering
+ * `df-prime-select-control` internally), place `NgForgeHostControl` on the
+ * INNER control component's `hostDirectives` — the inner element is the
+ * canonical control, and the marker's `inject(NgForgeField)` walks up the
+ * element-injector tree to find the parent's directive instance.
+ *
+ * @example
+ * ```ts
+ * \@Component({
+ *   hostDirectives: [
+ *     { directive: NgForgeField, inputs: [...NG_FORGE_FIELD_INPUTS] },
+ *     NgForgeHostControl,
+ *   ],
+ *   template: `...`,
+ * })
+ * export class IonicInputField { ... }
+ * ```
+ */
+declare class NgForgeHostControl {
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgForgeHostControl, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgForgeHostControl, never, never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Value-bearing field host wrapper. Composes `NgForgeFieldShell` (universal
+ * identity) with `NgForgeField` (value + validation + aria + meta-tracking)
+ * in a single host-directive entry, so consumer components compose just one
+ * directive instead of two.
+ *
+ * Why a directive instead of a `const` preset: cross-package partial
+ * compilation can't resolve a const reference inside `hostDirectives:`, so
+ * an exported const array doesn't work for library consumers. A wrapper
+ * directive's own `hostDirectives` IS a literal at compile time (in this
+ * file), so it works everywhere.
+ *
+ * Authoring shape for adapter components:
+ * ```ts
+ * \@Component({
+ *   hostDirectives: [NgForgeFieldHost],
+ *   ...
+ * })
+ * export class MyInputField {
+ *   protected readonly ngf = injectNgForgeField<string>();
+ * }
+ * ```
+ *
+ * Pattern reference: Taiga UI uses the same wrapper-directive technique
+ * for the same reason. See https://www.angularspace.com/host-directives-decomposition-unleashed/
+ */
+declare class NgForgeFieldHost {
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgForgeFieldHost, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgForgeFieldHost, never, never, {}, {}, never, never, true, [{ directive: typeof NgForgeFieldShell; inputs: { "key": "key"; "className": "className"; }; outputs: {}; }, { directive: typeof NgForgeField; inputs: { "field": "field"; "label": "label"; "placeholder": "placeholder"; "tabIndex": "tabIndex"; "props": "props"; "meta": "meta"; "validationMessages": "validationMessages"; }; outputs: {}; }]>;
+}
+/**
+ * Action / button host wrapper. Composes `NgForgeFieldShell` with
+ * `NgForgeAction` (event dispatch + aria-disabled) for button-shaped
+ * components.
+ *
+ * Authoring shape:
+ * ```ts
+ * \@Component({
+ *   hostDirectives: [NgForgeActionHost],
+ *   ...
+ * })
+ * export class MyButton {
+ *   protected readonly action = injectNgForgeAction();
+ * }
+ * ```
+ */
+declare class NgForgeActionHost {
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgForgeActionHost, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgForgeActionHost, never, never, {}, {}, never, never, true, [{ directive: typeof NgForgeFieldShell; inputs: { "key": "key"; "className": "className"; }; outputs: {}; }, { directive: typeof NgForgeAction; inputs: { "label": "label"; "disabled": "disabled"; "hidden": "hidden"; "tabIndex": "tabIndex"; "event": "event"; "eventArgs": "eventArgs"; "eventContext": "eventContext"; "props": "props"; }; outputs: {}; }]>;
+}
+
+interface CreateNgForgeFieldFixtureOptions<TValue = unknown> {
+    /** Field key. Becomes the only property on the wrapping form. */
+    readonly key: string;
+    /** Initial value for the field. */
+    readonly value?: TValue;
+    /** Optional schema callback that receives the field's `SchemaPath`. Use it to attach validators (`required`, `minLength`, etc.). */
+    readonly schema?: (fieldPath: SchemaPath<TValue>) => void;
+    /** Mark the field as touched after creation (useful for invalid-state assertions). */
+    readonly touched?: boolean;
+    /** Extra inputs to set on the component before `detectChanges()`. */
+    readonly inputs?: Record<string, unknown>;
+    /** Extra TestBed providers. */
+    readonly providers?: readonly Provider[];
+}
+interface NgForgeFieldFixture<C, TValue = unknown> {
+    readonly fixture: ComponentFixture<C>;
+    readonly field: FieldTree<TValue>;
+    readonly rootValue: WritableSignal<Record<string, TValue>>;
+}
+/**
+ * Builds a `ComponentFixture` for an `NgForgeField`-composing component with
+ * `field` + `key` bound BEFORE `detectChanges()` — sidesteps the NG0950 that
+ * Shell's required `key` and Field's required `field` would otherwise throw.
+ *
+ * The caller drives `detectChanges()` themselves (so they can `setInput`
+ * additional component-specific props in between).
+ */
+declare function createNgForgeFieldFixture<C, TValue = unknown>(component: Type<C>, options: CreateNgForgeFieldFixtureOptions<TValue>): NgForgeFieldFixture<C, TValue>;
+interface CreateNgForgeActionFixtureOptions<TEvent extends FormEvent = FormEvent> {
+    readonly key: string;
+    readonly label: DynamicText;
+    readonly event?: FormEventConstructor<TEvent>;
+    readonly eventArgs?: EventArgs;
+    readonly disabled?: boolean;
+    readonly hidden?: boolean;
+    readonly inputs?: Record<string, unknown>;
+    readonly providers?: readonly Provider[];
+}
+interface NgForgeActionFixture<C> {
+    readonly fixture: ComponentFixture<C>;
+    readonly eventBus: EventBus;
+}
+/**
+ * Builds a `ComponentFixture` for an `NgForgeAction`-composing component with
+ * `key` + `label` bound and `EventBus` provided. The caller calls
+ * `detectChanges()`; the harness handles the NG0950-avoidance bindings.
+ */
+declare function createNgForgeActionFixture<C, TEvent extends FormEvent = FormEvent>(component: Type<C>, options: CreateNgForgeActionFixtureOptions<TEvent>): NgForgeActionFixture<C>;
+/** Provider for `DEFAULT_VALIDATION_MESSAGES` in field tests — supply the default-messages map and the directive resolves it from DI. */
+declare function provideTestValidationMessages(messages: ValidationMessages): Provider;
+
+export { ADDON_PRESET_HANDLER, NG_FORGE_ACTION_INPUTS, NG_FORGE_ADDONS_INPUTS, NG_FORGE_ADDON_ACTION_INPUTS, NG_FORGE_FIELD_SHELL_INPUTS, NG_FORGE_VALUE_FIELD_INPUTS, NgForgeAction, NgForgeActionHost, NgForgeAddonAction, NgForgeAddonActionBase, NgForgeAddons, NgForgeAddonsBase, NgForgeControl, NgForgeField, NgForgeFieldHost, NgForgeFieldShell, NgForgeHostControl, addArrayItemButtonMapper, buildArrayButtonEventContext, buildValueFieldInputs, buttonFieldMapper, checkboxFieldMapper, createAriaDescribedBySignal, createNgForgeActionFixture, createNgForgeFieldFixture, createResolvedErrorsSignal, datepickerFieldMapper, injectNgForgeAction, injectNgForgeAddonAction, injectNgForgeAddons, injectNgForgeField, insertArrayItemButtonMapper, nextButtonFieldMapper, optionsFieldMapper, popArrayItemButtonMapper, prependArrayItemButtonMapper, previousButtonFieldMapper, provideTestValidationMessages, removeArrayItemButtonMapper, resolveArrayButtonContext, resolveArrayButtonEventArgs, resolveValueFieldContext, setupMetaTracking, shiftArrayItemButtonMapper, shouldShowErrors, submitButtonFieldMapper, valueFieldMapper };
+export type { AddonPresetHandler, ArrayButtonContext, ArrayButtonEventContext, Autocapitalize, AutocompleteValue, BaseArrayAddButtonField, BaseArrayRemoveButtonField, BaseInsertArrayItemButtonField, BaseNavigationButtonField, ButtonField, CheckboxField, CreateNgForgeActionFixtureOptions, CreateNgForgeFieldFixtureOptions, DatepickerField, DatepickerProps, EnterKeyHint, EventArg, EventArgs, FieldWithOptions, HtmlInputType, InferInputValue, InputField, InputMeta, InputMode, InputProps, InputType, InputTypeToValueType, MetaTrackingOptions, MultiCheckboxField, NgForgeActionFixture, NgForgeFieldFixture, NumericInputType, RadioField, ResolvedError, SelectField, SelectProps, SliderField, StringInputType, TextareaField, TextareaMeta, TextareaProps, TextareaWrap, ToggleField, TypedNgForgeAddonAction, TypedNgForgeAddons, TypedNgForgeField, ValueFieldContext };