@ng-forge/dynamic-forms-ionic 0.9.0-next.8 → 0.9.0

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

@@ -1,9 +1,10 @@
-import { FormEvent, NextPageEvent, PreviousPageEvent, AppendArrayItemEvent, ArrayAllowedChildren, PrependArrayItemEvent, InsertArrayItemEvent, RemoveAtIndexEvent, PopArrayItemEvent, ShiftArrayItemEvent, FieldComponent, DynamicText, FormEventConstructor, ArrayItemContext, CheckedFieldComponent, FieldMeta, ValidationMessages, ValueFieldComponent, ValueType, FieldOption, FieldTypeDefinition, NarrowFields, RegisteredFieldTypes, InferFormValue, FormConfig } from '@ng-forge/dynamic-forms';
-import * as _ng_forge_dynamic_forms_integration from '@ng-forge/dynamic-forms/integration';
-import { ButtonField, EventArgs, CheckboxField, DatepickerField, DatepickerProps, InputMeta, InputField, InputProps, MultiCheckboxField, RadioField, SelectField, SelectProps, SliderField, TextareaField, TextareaProps, TextareaMeta, ToggleField } from '@ng-forge/dynamic-forms/integration';
+import * as _ng_forge_dynamic_forms from '@ng-forge/dynamic-forms';
+import { FormEvent, NextPageEvent, PreviousPageEvent, AppendArrayItemEvent, ArrayAllowedChildren, PrependArrayItemEvent, InsertArrayItemEvent, RemoveAtIndexEvent, PopArrayItemEvent, ShiftArrayItemEvent, DynamicText, CheckedFieldComponent, ValueFieldComponent, BaseAddon, DynamicValue, AddonActionPreset, RegisteredActionRef, AddonActionHandler, TextAddon, TemplateAddon, WrapperFieldInputs, ValueType, FieldOption, FieldTypeDefinition, NarrowFields, RegisteredFieldTypes, InferFormValue, FormConfig } from '@ng-forge/dynamic-forms';
+import * as i1 from '@ng-forge/dynamic-forms/integration';
+import { ButtonField, CheckboxField, DatepickerField, DatepickerProps, InputField, InputProps, MultiCheckboxField, RadioField, SelectField, SelectProps, SliderField, TextareaField, TextareaProps, ToggleField } from '@ng-forge/dynamic-forms/integration';
 import * as _angular_core from '@angular/core';
-import { InjectionToken, Provider } from '@angular/core';
-import { FieldTree } from '@angular/forms/signals';
+import { InjectionToken, Provider, WritableSignal } from '@angular/core';
+import * as _ng_forge_dynamic_forms_ionic from '@ng-forge/dynamic-forms-ionic';
 
 interface IonicButtonProps {
     expand?: 'full' | 'block';
@@ -15,7 +16,6 @@ interface IonicButtonProps {
     type?: 'button' | 'submit' | 'reset';
 }
 type IonicButtonField<TEvent extends FormEvent> = ButtonField<IonicButtonProps, TEvent>;
-type IonicButtonComponent<TEvent extends FormEvent> = FieldComponent<IonicButtonField<TEvent>>;
 /**
  * Specific button field types with preconfigured events
  */
@@ -112,32 +112,14 @@ type ShiftArrayItemButtonField = Omit<IonicButtonField<ShiftArrayItemEvent>, 'ev
     arrayKey: string;
 };
 
-declare class IonicButtonFieldComponent<TEvent extends FormEvent> implements IonicButtonComponent<TEvent> {
-    private readonly eventBus;
-    private readonly arrayContext;
-    readonly key: _angular_core.InputSignal<string>;
-    readonly label: _angular_core.InputSignal<DynamicText>;
-    readonly disabled: _angular_core.InputSignal<boolean>;
-    readonly hidden: _angular_core.InputSignal<boolean>;
-    readonly tabIndex: _angular_core.InputSignal<number | undefined>;
-    readonly className: _angular_core.InputSignal<string>;
-    /** Event to dispatch on click. Optional for submit buttons (native form submit handles it). */
-    readonly event: _angular_core.InputSignal<FormEventConstructor<TEvent> | undefined>;
-    readonly eventArgs: _angular_core.InputSignal<EventArgs | undefined>;
+declare class IonicButtonFieldComponent<TEvent extends FormEvent> {
+    protected readonly action: i1.NgForgeAction<TEvent>;
     readonly props: _angular_core.InputSignal<IonicButtonProps | undefined>;
-    readonly eventContext: _angular_core.InputSignal<ArrayItemContext | undefined>;
-    /** Resolved button type - defaults to 'button' if not specified in props */
     readonly buttonType: _angular_core.Signal<"button" | "submit" | "reset">;
     readonly buttonTestId: _angular_core.Signal<string>;
-    /**
-     * Handle button click.
-     * - For submit buttons (type="submit"): do nothing, native form submit handles it
-     * - For other buttons: dispatch the configured event via EventBus
-     */
     onClick(): void;
-    private dispatchEvent;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<IonicButtonFieldComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicButtonFieldComponent<any>, "df-ion-button", never, { "key": { "alias": "key"; "required": true; "isSignal": true; }; "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; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "event": { "alias": "event"; "required": false; "isSignal": true; }; "eventArgs": { "alias": "eventArgs"; "required": false; "isSignal": true; }; "props": { "alias": "props"; "required": false; "isSignal": true; }; "eventContext": { "alias": "eventContext"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicButtonFieldComponent<any>, "df-ion-button", never, { "props": { "alias": "props"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.NgForgeActionHost; inputs: {}; outputs: {}; }]>;
 }
 
 interface IonicCheckboxProps {
@@ -148,36 +130,14 @@ interface IonicCheckboxProps {
     hint?: DynamicText;
 }
 type IonicCheckboxField = CheckboxField<IonicCheckboxProps>;
+/** @deprecated Scheduled for removal in v1. Use `injectNgForgeField<T>()` for typed access to a field component's directive instance. */
 type IonicCheckboxComponent = CheckedFieldComponent<IonicCheckboxField>;
 
-declare class IonicCheckboxFieldComponent implements IonicCheckboxComponent {
-    private readonly elementRef;
-    readonly field: _angular_core.InputSignal<FieldTree<boolean>>;
-    readonly key: _angular_core.InputSignal<string>;
-    readonly label: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly placeholder: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly className: _angular_core.InputSignal<string>;
-    readonly tabIndex: _angular_core.InputSignal<number | undefined>;
+declare class IonicCheckboxFieldComponent {
+    protected readonly ngf: i1.TypedNgForgeField<boolean>;
     readonly props: _angular_core.InputSignal<IonicCheckboxProps | undefined>;
-    readonly meta: _angular_core.InputSignal<FieldMeta | undefined>;
-    readonly validationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    readonly defaultValidationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    readonly resolvedErrors: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
-    readonly showErrors: _angular_core.Signal<boolean>;
-    readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
-    constructor();
-    /** Base ID for error elements */
-    protected readonly errorId: _angular_core.Signal<string>;
-    /** Unique ID for the helper text element */
-    protected readonly hintId: _angular_core.Signal<string>;
-    /** Whether the field is currently in an invalid state (invalid AND touched) */
-    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
-    /** Whether the field has a required validator */
-    protected readonly ariaRequired: _angular_core.Signal<true | null>;
-    /** aria-describedby linking to hint OR error elements (mutually exclusive) */
-    protected readonly ariaDescribedBy: _angular_core.Signal<string | null>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<IonicCheckboxFieldComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicCheckboxFieldComponent, "df-ion-checkbox", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "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; }; "defaultValidationMessages": { "alias": "defaultValidationMessages"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicCheckboxFieldComponent, "df-ion-checkbox", never, { "props": { "alias": "props"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.NgForgeFieldHost; inputs: {}; outputs: {}; }]>;
 }
 
 interface IonicDatepickerProps extends DatepickerProps {
@@ -195,45 +155,162 @@ interface IonicDatepickerProps extends DatepickerProps {
     hint?: DynamicText;
 }
 type IonicDatepickerField = DatepickerField<IonicDatepickerProps>;
+/** @deprecated Scheduled for removal in v1. Use `injectNgForgeField<T>()` for typed access to a field component's directive instance. */
 type IonicDatepickerComponent = ValueFieldComponent<IonicDatepickerField>;
 
-declare class IonicDatepickerFieldComponent implements IonicDatepickerComponent {
-    private readonly elementRef;
-    readonly field: _angular_core.InputSignal<FieldTree<Date | null>>;
-    readonly key: _angular_core.InputSignal<string>;
-    readonly label: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly placeholder: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly className: _angular_core.InputSignal<string>;
-    readonly tabIndex: _angular_core.InputSignal<number | undefined>;
+declare class IonicDatepickerFieldComponent {
+    protected readonly ngf: i1.TypedNgForgeField<Date | null>;
     readonly minDate: _angular_core.InputSignal<Date | null>;
     readonly maxDate: _angular_core.InputSignal<Date | null>;
     readonly startAt: _angular_core.InputSignal<Date | null>;
     readonly props: _angular_core.InputSignal<IonicDatepickerProps | undefined>;
-    readonly meta: _angular_core.InputSignal<InputMeta | undefined>;
-    readonly validationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    readonly defaultValidationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    readonly resolvedErrors: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
-    readonly showErrors: _angular_core.Signal<boolean>;
-    readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
     readonly isModalOpen: _angular_core.WritableSignal<boolean>;
-    constructor();
-    /** Base ID for error elements */
-    protected readonly errorId: _angular_core.Signal<string>;
-    /** Unique ID for the helper text element */
-    protected readonly hintId: _angular_core.Signal<string>;
-    /** Whether the field is currently in an invalid state (invalid AND touched) */
-    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
-    /** Whether the field has a required validator */
-    protected readonly ariaRequired: _angular_core.Signal<true | null>;
-    /** aria-describedby linking to hint OR error elements (mutually exclusive) */
-    protected readonly ariaDescribedBy: _angular_core.Signal<string | null>;
     openModal(): void;
     closeModal(): void;
     onDateChange(event: CustomEvent): void;
     dateToIsoString(date: Date | null | undefined): string | undefined;
     formatDisplayDate(date: Date | null | undefined): string;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<IonicDatepickerFieldComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicDatepickerFieldComponent, "df-ion-datepicker", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "tabIndex": { "alias": "tabIndex"; "required": false; "isSignal": true; }; "minDate": { "alias": "minDate"; "required": false; "isSignal": true; }; "maxDate": { "alias": "maxDate"; "required": false; "isSignal": true; }; "startAt": { "alias": "startAt"; "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; }; "defaultValidationMessages": { "alias": "defaultValidationMessages"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicDatepickerFieldComponent, "df-ion-datepicker", never, { "minDate": { "alias": "minDate"; "required": false; "isSignal": true; }; "maxDate": { "alias": "maxDate"; "required": false; "isSignal": true; }; "startAt": { "alias": "startAt"; "required": false; "isSignal": true; }; "props": { "alias": "props"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.NgForgeFieldHost; inputs: {}; outputs: {}; }]>;
+}
+
+/**
+ * Decorative icon addon for Ion fields.
+ *
+ * Renders `<ion-icon name="{icon}">` (Ionons). The `icon` string is the
+ * Ionons name — e.g., `'search-outline'` produces
+ * `<ion-icon name="search-outline">`.
+ *
+ * Add `ariaLabel` for icons that convey meaning; leave it omitted for
+ * purely decorative icons (will be `aria-hidden="true"`).
+ */
+interface IonIconAddon extends BaseAddon {
+    readonly kind: 'ion-icon';
+    /** Ionons name (e.g., `'search-outline'`, `'close-outline'`). */
+    readonly icon: string;
+    /** Accessible label for icons that convey meaning. */
+    readonly ariaLabel?: DynamicText;
+}
+/**
+ * Ionic-supported button colour palette.
+ */
+type IonButtonColor = 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger' | 'light' | 'medium' | 'dark';
+/**
+ * Ionic-supported button fill variants.
+ */
+type IonButtonFill = 'clear' | 'outline' | 'solid' | 'default';
+/**
+ * Common shape of every `ion-button` addon — properties that don't
+ * participate in either XOR axis.
+ */
+interface IonButtonBase extends BaseAddon {
+    readonly kind: 'ion-button';
+    /** Ion button colour. */
+    readonly color?: IonButtonColor;
+    /** Ion button fill style. */
+    readonly fill?: IonButtonFill;
+    /** Reactive loading state — renders an `<ion-spinner>` when truthy. */
+    readonly loading?: DynamicValue<boolean>;
+}
+/**
+ * Click axis — XOR enforced at type level so configurations that combine
+ * two click handlers (e.g., `preset` AND `actionRef`) are rejected by
+ * TypeScript. The four shapes:
+ *
+ * - `Preset`    — built-in preset action.
+ * - `ActionRef` — typed reference to a handler registered via `provideAddonActions(...)`.
+ * - `Action`    — inline handler (code-only; dropped from JSON-derived configs).
+ * - `None`      — decorative button with no handler.
+ *
+ * Runtime XOR validation stays as defence-in-depth for JSON-source configs
+ * that bypass the type checker.
+ */
+type IonButtonClickPreset = {
+    /** Built-in preset action (e.g., `'clear'`, `'toggle-password-visibility'`). JSON-safe. */
+    readonly preset: AddonActionPreset;
+    readonly actionRef?: never;
+    readonly action?: never;
+};
+/**
+ * Value type for the `actionRef` slot. When no actions have been registered
+ * via `provideAddonActions(...)`, `RegisteredActionRef` resolves to `never` —
+ * which would make this variant uninhabitable and break `addon.actionRef`
+ * narrowing in the renderer. Fall back to `string` so the variant stays
+ * usable; once the user augments `DynamicFormActionRegistry`, autocomplete
+ * tightens to the registered keys.
+ */
+type IonButtonActionRef = [RegisteredActionRef] extends [never] ? string : RegisteredActionRef;
+type IonButtonClickActionRef = {
+    readonly preset?: never;
+    /** Reference to a handler registered via `provideAddonActions(...)`. JSON-safe. */
+    readonly actionRef: IonButtonActionRef;
+    readonly action?: never;
+};
+type IonButtonClickAction = {
+    readonly preset?: never;
+    readonly actionRef?: never;
+    /** Inline handler — code-only; dropped from JSON-derived configs. Matches the generic `AddonActionHandler` shape used by `provideAddonActions(...)`. */
+    readonly action: AddonActionHandler;
+};
+type IonButtonClickNone = {
+    readonly preset?: never;
+    readonly actionRef?: never;
+    readonly action?: never;
+};
+type IonButtonClick = IonButtonClickPreset | IonButtonClickActionRef | IonButtonClickAction | IonButtonClickNone;
+/**
+ * Content axis — XOR enforced at type level so an icon-only button is
+ * forced to declare `ariaLabel`. The three shapes:
+ *
+ * - `IconOnly`   — just `icon`; `ariaLabel` is REQUIRED
+ * - `Labeled`    — `label` set; `icon` and `ariaLabel` optional
+ * - `Decorative` — neither icon nor label (e.g., custom-rendered child)
+ *
+ * Combining keys is rejected by TypeScript — `icon: 'x'` without either
+ * `label` or `ariaLabel` doesn't satisfy any branch.
+ */
+type IonButtonContentIconOnly = {
+    readonly icon: string;
+    readonly label?: never;
+    /** REQUIRED: icon-only buttons must carry an accessible label. */
+    readonly ariaLabel: DynamicText;
+};
+type IonButtonContentLabeled = {
+    readonly icon?: string;
+    readonly label: DynamicText;
+    readonly ariaLabel?: DynamicText;
+};
+type IonButtonContentDecorative = {
+    readonly icon?: never;
+    readonly label?: never;
+    readonly ariaLabel?: DynamicText;
+};
+type IonButtonContent = IonButtonContentIconOnly | IonButtonContentLabeled | IonButtonContentDecorative;
+/**
+ * Interactive button addon for Ion fields.
+ *
+ * Renders `<ion-button>` with optional icon (via `<ion-icon>`), label,
+ * colour / fill variants, and a reactive loading state (rendered as
+ * `<ion-spinner>`).
+ *
+ * Type-level guarantees:
+ *
+ * - **Content axis (XOR):** `IconOnly` (icon + required ariaLabel) |
+ *   `Labeled` (label, icon optional) | `Decorative` (neither). The IDE
+ *   rejects icon-only configs that omit `ariaLabel`.
+ * - **Click axis (XOR):** exactly one of `preset` / `actionRef` / `action`,
+ *   or none. Combining two is rejected by TypeScript at the call site;
+ *   the runtime validator still drops the addon with a clear warning when
+ *   JSON-source configs slip a multi-set past the type checker.
+ */
+type IonButtonAddon = IonButtonBase & IonButtonContent & IonButtonClick;
+/** Union of all Ion-shipped addon kinds. */
+type IonAddon = IonIconAddon | IonButtonAddon;
+declare module '@ng-forge/dynamic-forms' {
+    interface DynamicFormAddonRegistry {
+        'ion-icon': IonIconAddon;
+        'ion-button': IonButtonAddon;
+    }
 }
 
 interface IonicInputProps extends InputProps {
@@ -246,42 +323,78 @@ interface IonicInputProps extends InputProps {
     counter?: boolean;
     clearInput?: boolean;
 }
-type IonicInputField = InputField<IonicInputProps>;
+/**
+ * Module-augmentable seam for adding custom addon kinds to `ion-input` at
+ * the type level. Pair with `withCustomAddon(...)` for the runtime side:
+ *
+ * ```ts
+ * declare module '@ng-forge/dynamic-forms-ionic' {
+ *   interface IonAddonExtensions {
+ *     'my-rating': MyRatingAddon;
+ *   }
+ * }
+ * ```
+ *
+ * Empty by default — the extension lookup resolves to `never` and contributes
+ * nothing to the union.
+ */
+interface IonAddonExtensions {
+}
+type IonAddonExtension = IonAddonExtensions[keyof IonAddonExtensions];
+/**
+ * Addon kinds accepted by `ion-input`.
+ *
+ * Ionic-specific kinds (`ion-icon`, `ion-button`) plus the universal `text`
+ * and `template` kinds. `component` is permitted at runtime via the broader
+ * `BaseAddon` union (and dropped in JSON-derived configs by the validator)
+ * but excluded here so the IDE narrows tightly to declarative shapes.
+ *
+ * To extend with custom kinds, augment `IonAddonExtensions`.
+ */
+type IonInputAddon = IonIconAddon | IonButtonAddon | TextAddon | TemplateAddon | IonAddonExtension;
+type IonicInputField = InputField<IonicInputProps> & {
+    addons?: ReadonlyArray<IonInputAddon>;
+};
+/** @deprecated Scheduled for removal in v1. Use `injectNgForgeField<T>()` for typed access to a field component's directive instance. */
 type IonicInputComponent = ValueFieldComponent<IonicInputField>;
 
-declare class IonicInputFieldComponent implements IonicInputComponent {
+declare class IonicInputFieldComponent {
     private readonly elementRef;
     private ionicConfig;
-    readonly field: _angular_core.InputSignal<FieldTree<string>>;
-    readonly key: _angular_core.InputSignal<string>;
-    readonly label: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly placeholder: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly className: _angular_core.InputSignal<string>;
-    readonly tabIndex: _angular_core.InputSignal<number | undefined>;
+    protected readonly ngf: i1.TypedNgForgeField<string>;
+    protected readonly ngfa: i1.TypedNgForgeAddons<IonInputAddon>;
     readonly props: _angular_core.InputSignal<IonicInputProps | undefined>;
-    readonly meta: _angular_core.InputSignal<InputMeta | undefined>;
-    readonly validationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    readonly defaultValidationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    readonly effectiveFill: _angular_core.Signal<"outline" | "solid">;
-    readonly effectiveShape: _angular_core.Signal<"round" | undefined>;
-    readonly effectiveLabelPlacement: _angular_core.Signal<"start" | "end" | "fixed" | "stacked" | "floating">;
-    readonly effectiveColor: _angular_core.Signal<"primary" | "secondary" | "tertiary" | "success" | "warning" | "danger" | "light" | "medium" | "dark" | undefined>;
-    readonly resolvedErrors: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
-    readonly showErrors: _angular_core.Signal<boolean>;
-    readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
+    /**
+     * Wrapper-style host bag pushed by `DfFieldOutlet`. Declared at the
+     * component level so `setInputIfDeclared` (which uses
+     * `reflectComponentType`) can write it.
+     */
+    readonly fieldInputs: _angular_core.InputSignal<WrapperFieldInputs | undefined>;
+    /** Per-instance type override populated by `toggle-password-visibility` preset. */
+    private readonly typeOverride;
+    protected readonly fill: _angular_core.Signal<"outline" | "solid">;
+    protected readonly shape: _angular_core.Signal<"round" | undefined>;
+    /** Default 'stacked' (label above the input) for adapter parity with Material /
+     *  Bootstrap / PrimeNG. Consumers can opt into Ionic's native inline 'start'
+     *  or 'fixed' via props.labelPlacement or the IONIC_CONFIG token. */
+    protected readonly labelPlacement: _angular_core.Signal<"start" | "end" | "fixed" | "stacked" | "floating">;
+    protected readonly color: _angular_core.Signal<"primary" | "secondary" | "tertiary" | "success" | "warning" | "danger" | "light" | "medium" | "dark" | undefined>;
+    /** Override (set by `toggle-password-visibility` preset) wins over `props().type`. */
+    protected readonly type: _angular_core.Signal<string>;
+    /** Per-kind split: ion-button addons render inline via the attribute-
+     *  selector inline component (so the slotted element is a native
+     *  <ion-button> Ionic can style); everything else (icon/text/template/
+     *  component kinds) goes through the universal <df-addon-slot> dispatcher
+     *  wrapped in <span slot="start|end"> for safe shadow-DOM projection. */
+    protected readonly buttonPrefixAddons: _angular_core.Signal<_ng_forge_dynamic_forms_ionic.IonButtonAddon[]>;
+    protected readonly buttonSuffixAddons: _angular_core.Signal<_ng_forge_dynamic_forms_ionic.IonButtonAddon[]>;
+    protected readonly decorativePrefixAddons: _angular_core.Signal<(_ng_forge_dynamic_forms.TextAddon | _ng_forge_dynamic_forms.TemplateAddon | _ng_forge_dynamic_forms_ionic.IonIconAddon)[]>;
+    protected readonly decorativeSuffixAddons: _angular_core.Signal<(_ng_forge_dynamic_forms.TextAddon | _ng_forge_dynamic_forms.TemplateAddon | _ng_forge_dynamic_forms_ionic.IonIconAddon)[]>;
+    /** Set when the component is destroyed — guards async aria-describedby sync against teardown. */
+    private destroyed;
     constructor();
-    /** Base ID for error elements */
-    protected readonly errorId: _angular_core.Signal<string>;
-    /** Unique ID for the helper text element */
-    protected readonly hintId: _angular_core.Signal<string>;
-    /** Whether the field is currently in an invalid state (invalid AND touched) */
-    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
-    /** Whether the field has a required validator */
-    protected readonly ariaRequired: _angular_core.Signal<true | null>;
-    /** aria-describedby linking to hint OR error elements (mutually exclusive) */
-    protected readonly ariaDescribedBy: _angular_core.Signal<string | null>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<IonicInputFieldComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicInputFieldComponent, "df-ion-input", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "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; }; "defaultValidationMessages": { "alias": "defaultValidationMessages"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicInputFieldComponent, "df-ion-input", never, { "props": { "alias": "props"; "required": false; "isSignal": true; }; "fieldInputs": { "alias": "fieldInputs"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.NgForgeFieldHost; inputs: {}; outputs: {}; }, { directive: typeof i1.NgForgeAddons; inputs: {}; outputs: {}; }]>;
 }
 
 interface IonicMultiCheckboxProps {
@@ -291,41 +404,20 @@ interface IonicMultiCheckboxProps {
     hint?: DynamicText;
 }
 type IonicMultiCheckboxField<T> = MultiCheckboxField<T, IonicMultiCheckboxProps>;
+/** @deprecated Scheduled for removal in v1. Use `injectNgForgeField<T>()` for typed access to a field component's directive instance. */
 type IonicMultiCheckboxComponent = ValueFieldComponent<IonicMultiCheckboxField<ValueType>>;
 
-declare class IonicMultiCheckboxFieldComponent implements IonicMultiCheckboxComponent {
-    private readonly elementRef;
-    readonly field: _angular_core.InputSignal<FieldTree<ValueType[]>>;
-    readonly key: _angular_core.InputSignal<string>;
-    readonly label: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly placeholder: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly className: _angular_core.InputSignal<string>;
-    readonly tabIndex: _angular_core.InputSignal<number | undefined>;
+declare class IonicMultiCheckboxFieldComponent {
+    protected readonly ngf: i1.TypedNgForgeField<ValueType[]>;
     readonly options: _angular_core.InputSignal<FieldOption<ValueType>[]>;
     readonly props: _angular_core.InputSignal<IonicMultiCheckboxProps | undefined>;
-    readonly meta: _angular_core.InputSignal<FieldMeta | undefined>;
-    readonly validationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    readonly defaultValidationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    readonly resolvedErrors: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
-    readonly showErrors: _angular_core.Signal<boolean>;
-    readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
-    /** Base ID for error elements */
-    protected readonly errorId: _angular_core.Signal<string>;
-    /** Unique ID for the helper text element */
-    protected readonly hintId: _angular_core.Signal<string>;
-    /** Whether the field is currently in an invalid state (invalid AND touched) */
-    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
-    /** Whether the field has a required validator */
-    protected readonly ariaRequired: _angular_core.Signal<true | null>;
-    /** aria-describedby linking to hint OR error elements (mutually exclusive) */
-    protected readonly ariaDescribedBy: _angular_core.Signal<string | null>;
     valueViewModel: _angular_core.WritableSignal<FieldOption<ValueType>[]>;
     /** Computed map of checked option values for O(1) lookup in template */
     readonly checkedValuesMap: _angular_core.Signal<Record<string, boolean>>;
     constructor();
     onCheckboxChange(option: FieldOption<ValueType>, checked: boolean): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<IonicMultiCheckboxFieldComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicMultiCheckboxFieldComponent, "df-ion-multi-checkbox", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "tabIndex": { "alias": "tabIndex"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "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; }; "defaultValidationMessages": { "alias": "defaultValidationMessages"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicMultiCheckboxFieldComponent, "df-ion-multi-checkbox", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "props": { "alias": "props"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.NgForgeFieldHost; inputs: {}; outputs: {}; }]>;
 }
 
 interface IonicRadioProps {
@@ -336,38 +428,16 @@ interface IonicRadioProps {
     hint?: DynamicText;
 }
 type IonicRadioField<T> = RadioField<T, IonicRadioProps>;
+/** @deprecated Scheduled for removal in v1. Use `injectNgForgeField<T>()` for typed access to a field component's directive instance. */
 type IonicRadioComponent = ValueFieldComponent<IonicRadioField<ValueType>>;
 
-declare class IonicRadioFieldComponent implements IonicRadioComponent {
-    private readonly elementRef;
-    readonly field: _angular_core.InputSignal<FieldTree<ValueType>>;
-    readonly key: _angular_core.InputSignal<string>;
-    readonly label: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly placeholder: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly className: _angular_core.InputSignal<string>;
-    readonly tabIndex: _angular_core.InputSignal<number | undefined>;
+declare class IonicRadioFieldComponent {
+    protected readonly ngf: i1.TypedNgForgeField<ValueType>;
     readonly options: _angular_core.InputSignal<FieldOption<ValueType>[]>;
     readonly props: _angular_core.InputSignal<IonicRadioProps | undefined>;
-    readonly meta: _angular_core.InputSignal<FieldMeta | undefined>;
-    readonly validationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    readonly defaultValidationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    readonly resolvedErrors: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
-    readonly showErrors: _angular_core.Signal<boolean>;
-    readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
     defaultCompare: (value1: any, value2: any) => boolean;
-    constructor();
-    /** Base ID for error elements */
-    protected readonly errorId: _angular_core.Signal<string>;
-    /** Unique ID for the helper text element */
-    protected readonly hintId: _angular_core.Signal<string>;
-    /** Whether the field is currently in an invalid state (invalid AND touched) */
-    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
-    /** Whether the field has a required validator */
-    protected readonly ariaRequired: _angular_core.Signal<true | null>;
-    /** aria-describedby linking to hint OR error elements (mutually exclusive) */
-    protected readonly ariaDescribedBy: _angular_core.Signal<string | null>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<IonicRadioFieldComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicRadioFieldComponent, "df-ion-radio", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "tabIndex": { "alias": "tabIndex"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "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; }; "defaultValidationMessages": { "alias": "defaultValidationMessages"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicRadioFieldComponent, "df-ion-radio", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "props": { "alias": "props"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.NgForgeFieldHost; inputs: {}; outputs: {}; }]>;
 }
 
 interface IonicSelectProps extends SelectProps {
@@ -384,38 +454,16 @@ interface IonicSelectProps extends SelectProps {
     hint?: DynamicText;
 }
 type IonicSelectField<T> = SelectField<T, IonicSelectProps>;
+/** @deprecated Scheduled for removal in v1. Use `injectNgForgeField<T>()` for typed access to a field component's directive instance. */
 type IonicSelectComponent = ValueFieldComponent<IonicSelectField<ValueType>>;
 
-declare class IonicSelectFieldComponent implements IonicSelectComponent {
-    private readonly elementRef;
-    readonly field: _angular_core.InputSignal<FieldTree<ValueType>>;
-    readonly key: _angular_core.InputSignal<string>;
-    readonly label: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly placeholder: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly className: _angular_core.InputSignal<string>;
-    readonly tabIndex: _angular_core.InputSignal<number | undefined>;
+declare class IonicSelectFieldComponent {
+    protected readonly ngf: i1.TypedNgForgeField<ValueType>;
     readonly options: _angular_core.InputSignal<FieldOption<ValueType>[]>;
     readonly props: _angular_core.InputSignal<IonicSelectProps | undefined>;
-    readonly meta: _angular_core.InputSignal<FieldMeta | undefined>;
-    readonly validationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    readonly defaultValidationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    constructor();
-    readonly resolvedErrors: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
-    readonly showErrors: _angular_core.Signal<boolean>;
-    readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
     defaultCompare: (value1: any, value2: any) => boolean;
-    /** Base ID for error elements */
-    protected readonly errorId: _angular_core.Signal<string>;
-    /** Unique ID for the helper text element */
-    protected readonly hintId: _angular_core.Signal<string>;
-    /** Whether the field is currently in an invalid state (invalid AND touched) */
-    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
-    /** Whether the field has a required validator */
-    protected readonly ariaRequired: _angular_core.Signal<true | null>;
-    /** aria-describedby linking to hint OR error elements (mutually exclusive) */
-    protected readonly ariaDescribedBy: _angular_core.Signal<string | null>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<IonicSelectFieldComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicSelectFieldComponent, "df-ion-select", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "tabIndex": { "alias": "tabIndex"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "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; }; "defaultValidationMessages": { "alias": "defaultValidationMessages"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicSelectFieldComponent, "df-ion-select", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "props": { "alias": "props"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.NgForgeFieldHost; inputs: {}; outputs: {}; }]>;
 }
 
 interface IonicSliderProps {
@@ -444,38 +492,16 @@ interface IonicSliderProps {
     hint?: DynamicText;
 }
 type IonicSliderField = SliderField<IonicSliderProps>;
+/** @deprecated Scheduled for removal in v1. Use `injectNgForgeField<T>()` for typed access to a field component's directive instance. */
 type IonicSliderComponent = ValueFieldComponent<IonicSliderField>;
 
-declare class IonicSliderFieldComponent implements IonicSliderComponent {
-    private readonly elementRef;
-    readonly field: _angular_core.InputSignal<FieldTree<number>>;
-    readonly key: _angular_core.InputSignal<string>;
-    readonly label: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly placeholder: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly className: _angular_core.InputSignal<string>;
-    readonly tabIndex: _angular_core.InputSignal<number | undefined>;
+declare class IonicSliderFieldComponent {
+    protected readonly ngf: i1.TypedNgForgeField<number>;
     readonly step: _angular_core.InputSignal<number | undefined>;
     readonly props: _angular_core.InputSignal<IonicSliderProps | undefined>;
-    readonly meta: _angular_core.InputSignal<FieldMeta | undefined>;
-    readonly validationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    readonly defaultValidationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    constructor();
-    readonly resolvedErrors: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
-    readonly showErrors: _angular_core.Signal<boolean>;
-    readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
     protected defaultPinFormatter: (value: number) => string;
-    /** Base ID for error elements */
-    protected readonly errorId: _angular_core.Signal<string>;
-    /** Unique ID for the helper text element */
-    protected readonly hintId: _angular_core.Signal<string>;
-    /** Whether the field is currently in an invalid state (invalid AND touched) */
-    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
-    /** Whether the field has a required validator */
-    protected readonly ariaRequired: _angular_core.Signal<true | null>;
-    /** aria-describedby linking to hint OR error elements (mutually exclusive) */
-    protected readonly ariaDescribedBy: _angular_core.Signal<string | null>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<IonicSliderFieldComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicSliderFieldComponent, "df-ion-slider", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "tabIndex": { "alias": "tabIndex"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "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; }; "defaultValidationMessages": { "alias": "defaultValidationMessages"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicSliderFieldComponent, "df-ion-slider", never, { "step": { "alias": "step"; "required": false; "isSignal": true; }; "props": { "alias": "props"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.NgForgeFieldHost; inputs: {}; outputs: {}; }, { directive: typeof i1.NgForgeHostControl; inputs: {}; outputs: {}; }]>;
 }
 
 interface IonicTextareaProps extends TextareaProps {
@@ -489,36 +515,16 @@ interface IonicTextareaProps extends TextareaProps {
     color?: 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger' | 'light' | 'medium' | 'dark';
 }
 type IonicTextareaField = TextareaField<IonicTextareaProps>;
+/** @deprecated Scheduled for removal in v1. Use `injectNgForgeField<T>()` for typed access to a field component's directive instance. */
 type IonicTextareaComponent = ValueFieldComponent<IonicTextareaField>;
 
-declare class IonicTextareaFieldComponent implements IonicTextareaComponent {
+declare class IonicTextareaFieldComponent {
     private readonly elementRef;
-    readonly field: _angular_core.InputSignal<FieldTree<string>>;
-    readonly key: _angular_core.InputSignal<string>;
-    readonly label: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly placeholder: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly className: _angular_core.InputSignal<string>;
-    readonly tabIndex: _angular_core.InputSignal<number | undefined>;
+    protected readonly ngf: i1.TypedNgForgeField<string>;
     readonly props: _angular_core.InputSignal<IonicTextareaProps | undefined>;
-    readonly meta: _angular_core.InputSignal<TextareaMeta | undefined>;
-    readonly validationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    readonly defaultValidationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    readonly resolvedErrors: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
-    readonly showErrors: _angular_core.Signal<boolean>;
-    readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
     constructor();
-    /** Base ID for error elements */
-    protected readonly errorId: _angular_core.Signal<string>;
-    /** Unique ID for the helper text element */
-    protected readonly hintId: _angular_core.Signal<string>;
-    /** Whether the field is currently in an invalid state (invalid AND touched) */
-    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
-    /** Whether the field has a required validator */
-    protected readonly ariaRequired: _angular_core.Signal<true | null>;
-    /** aria-describedby linking to hint OR error elements (mutually exclusive) */
-    protected readonly ariaDescribedBy: _angular_core.Signal<string | null>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<IonicTextareaFieldComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicTextareaFieldComponent, "df-ion-textarea", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "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; }; "defaultValidationMessages": { "alias": "defaultValidationMessages"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicTextareaFieldComponent, "df-ion-textarea", never, { "props": { "alias": "props"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.NgForgeFieldHost; inputs: {}; outputs: {}; }]>;
 }
 
 interface IonicToggleProps {
@@ -529,32 +535,14 @@ interface IonicToggleProps {
     hint?: DynamicText;
 }
 type IonicToggleField = ToggleField<IonicToggleProps>;
+/** @deprecated Scheduled for removal in v1. Use `injectNgForgeField<T>()` for typed access to a field component's directive instance. */
 type IonicToggleComponent = CheckedFieldComponent<IonicToggleField>;
 
-declare class IonicToggleFieldComponent implements IonicToggleComponent {
-    private readonly elementRef;
-    readonly field: _angular_core.InputSignal<FieldTree<boolean>>;
-    readonly key: _angular_core.InputSignal<string>;
-    readonly label: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly placeholder: _angular_core.InputSignal<DynamicText | undefined>;
-    readonly className: _angular_core.InputSignal<string>;
-    readonly tabIndex: _angular_core.InputSignal<number | undefined>;
+declare class IonicToggleFieldComponent {
+    protected readonly ngf: i1.TypedNgForgeField<boolean>;
     readonly props: _angular_core.InputSignal<IonicToggleProps | undefined>;
-    readonly meta: _angular_core.InputSignal<FieldMeta | undefined>;
-    readonly validationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    readonly defaultValidationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
-    constructor();
-    readonly resolvedErrors: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
-    readonly showErrors: _angular_core.Signal<boolean>;
-    readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
-    /** Base ID for error elements */
-    protected readonly errorId: _angular_core.Signal<string>;
-    /** Unique ID for the helper text element */
-    protected readonly hintId: _angular_core.Signal<string>;
-    /** aria-describedby linking to hint OR error elements (mutually exclusive) */
-    protected readonly ariaDescribedBy: _angular_core.Signal<string | null>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<IonicToggleFieldComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicToggleFieldComponent, "df-ion-toggle", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "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; }; "defaultValidationMessages": { "alias": "defaultValidationMessages"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicToggleFieldComponent, "df-ion-toggle", never, { "props": { "alias": "props"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.NgForgeFieldHost; inputs: {}; outputs: {}; }]>;
 }
 
 /**
@@ -761,19 +749,30 @@ type IonicConfigFeature = {
     ɵkind: 'ionic-config';
     ɵproviders: Provider[];
 };
-type IonicFieldsWithConfig = [...IonicFieldTypes, IonicConfigFeature];
 /**
- * Configure dynamic forms with Ionic field types.
- * Provides all Ionic field types for use with provideDynamicForm.
+ * Default `withIonicFields()` shape — field defs + the auto-included
+ * addons feature so `ion-icon` / `ion-button` work out of the box.
+ */
+type IonicFieldsWithAddons = [...IonicFieldTypes, IonicAddonsFeature];
+type IonicFieldsWithConfig = [...IonicFieldTypes, IonicAddonsFeature, IonicConfigFeature];
+/**
+ * Provides Ionic field type definitions for the dynamic form system,
+ * with Ionic-shipped addon kinds (`ion-icon`, `ion-button`) auto-included
+ * so addons work out of the box.
+ *
+ * If you want field types WITHOUT addons (rare), pass them through
+ * `provideDynamicForm` directly and skip this helper. If you want addons
+ * WITHOUT the field types (also rare — e.g., adding addons to a form that
+ * uses custom fields), call `withIonicAddons()` standalone.
  *
  * @param config - Optional global configuration for Ionic form fields
  *
  * @example
  * ```typescript
- * // Application-level setup
+ * // Application-level setup — addons (ion-icon, ion-button) ship in automatically
  * import { ApplicationConfig } from '@angular/core';
- * import { provideDynamicForm } from '@ng-forge/dynamic-form';
- * import { withIonicFields } from '@ng-forge/dynamic-form-ionic';
+ * import { provideDynamicForm } from '@ng-forge/dynamic-forms';
+ * import { withIonicFields } from '@ng-forge/dynamic-forms-ionic';
  *
  * export const appConfig: ApplicationConfig = {
  *   providers: [
@@ -797,11 +796,105 @@ type IonicFieldsWithConfig = [...IonicFieldTypes, IonicConfigFeature];
  * };
  * ```
  *
- * @returns Array of field type definitions and optionally a config feature
+ * @returns Tuple of field type definitions, the addons feature, and
+ *   optionally a config feature.
  */
-declare function withIonicFields(): IonicFieldTypes;
+declare function withIonicFields(): IonicFieldsWithAddons;
 declare function withIonicFields(config: IonicConfig): IonicFieldsWithConfig;
-declare function withIonicFields(config: IonicConfig | undefined): IonicFieldTypes | IonicFieldsWithConfig;
+declare function withIonicFields(config: IonicConfig | undefined): IonicFieldsWithAddons | IonicFieldsWithConfig;
+/**
+ * Feature kind discriminant for the Ionic addons feature. Matches core's
+ * `'addons'` kind so providers flow through the standard addon-kind pipeline
+ * in `provideDynamicForm`.
+ */
+type IonicAddonsFeature = {
+    ɵkind: 'addons';
+    ɵproviders: Provider[];
+};
+/**
+ * Register Ionic-shipped addon kinds (`ion-icon`, `ion-button`) standalone.
+ *
+ * **Most users don't need this** — `withIonicFields()` auto-includes
+ * these kinds. Call `withIonicAddons()` directly only when you want
+ * Ionic addon kinds without the Ionic field types (e.g., a custom
+ * field set that wants to render `ion-icon` prefixes), or when you're
+ * stitching addons through a different DI scope.
+ *
+ * @example
+ * ```typescript
+ * // Custom field types + Ionic addon kinds.
+ * provideDynamicForm(
+ *   ...myCustomFields(),
+ *   withIonicAddons(),
+ * );
+ * ```
+ *
+ * Adapter authors who need to override a kind with a customised renderer
+ * should call `withCustomAddon(...)` directly instead.
+ */
+declare function withIonicAddons(): IonicAddonsFeature;
+
+/**
+ * Renderer for the `ion-button` addon kind.
+ *
+ * Wraps Ionic's `<ion-button>`. Click dispatch (preset / actionRef /
+ * action precedence, multi-set warning, `disabled` / `loading`
+ * resolution) lives on `NgForgeAddonAction`; this component focuses on
+ * the visual layer. While `action.loading()`, an `<ion-spinner>` is
+ * rendered in place of the icon and the button is disabled.
+ */
+declare class IonButtonAddonComponent {
+    protected readonly action: i1.TypedNgForgeAddonAction<IonButtonAddon>;
+    /** Re-exposed for template binding — same signal stored on the directive. */
+    protected readonly addon: _angular_core.Signal<IonButtonAddon>;
+    protected readonly label: _angular_core.Signal<_ng_forge_dynamic_forms.DynamicText | undefined>;
+    protected readonly ariaLabel: _angular_core.Signal<_ng_forge_dynamic_forms.DynamicText | undefined>;
+    protected readonly icon: _angular_core.Signal<string | undefined>;
+    /** Default color is undefined so the button inherits the theme's text color
+     *  (Ionic's `medium` would force low-contrast grey, which fails WCAG on dark
+     *  surfaces). Consumers can still set `color: 'primary' | 'success' | ...`
+     *  explicitly when they want adapter-styled coloring. */
+    protected readonly color: _angular_core.Signal<("primary" | "secondary" | "tertiary" | "success" | "warning" | "danger" | "light" | "medium" | "dark") | undefined>;
+    protected readonly fill: _angular_core.Signal<"clear" | "outline" | "solid" | "default">;
+    /** Icon-only when there is an icon but no label — drives the `slot` choice.
+     *  Truthy check on `label` mirrors Material's heuristic; empty-string label
+     *  is treated as "no label" so the button doesn't render an invisible text
+     *  slot beside the icon. */
+    protected readonly iconOnly: _angular_core.Signal<boolean>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<IonButtonAddonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonButtonAddonComponent, "df-ion-button-addon", never, {}, {}, never, never, true, [{ directive: typeof i1.NgForgeAddonAction; inputs: {}; outputs: {}; }]>;
+}
+
+/**
+ * Renderer for the `ion-icon` addon kind.
+ *
+ * Outputs `<ion-icon [name]="icon">`. The host is set `aria-hidden="true"`
+ * by default; if the addon supplies an `ariaLabel`, it is applied so the
+ * icon is announced by screen readers.
+ */
+declare class IonIconAddonComponent {
+    readonly addon: _angular_core.InputSignal<IonIconAddon>;
+    /** Accepted for contract uniformity — `NgComponentOutlet` setInput is strict; every kind must declare it. */
+    readonly fieldInputs: _angular_core.InputSignal<WrapperFieldInputs | undefined>;
+    protected readonly iconName: _angular_core.Signal<string>;
+    protected readonly ariaLabel: _angular_core.Signal<_ng_forge_dynamic_forms.DynamicText | undefined>;
+    protected readonly hasAriaLabel: _angular_core.Signal<boolean>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<IonIconAddonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonIconAddonComponent, "df-ion-icon-addon", never, { "addon": { "alias": "addon"; "required": true; "isSignal": true; }; "fieldInputs": { "alias": "fieldInputs"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Per-field writable signal that overrides the input's `type` attribute.
+ *
+ * Provided at the `ion-input` field component level. The button addon's
+ * `'toggle-password-visibility'` preset writes to it; the field component
+ * reads it to compute its effective `type`.
+ *
+ * Optional from a button's perspective — when the button is hosted inside a
+ * field that doesn't provide this token (e.g., textarea or a future
+ * non-input field), the toggle preset is a no-op.
+ */
+declare const IONIC_INPUT_TYPE_OVERRIDE: InjectionToken<WritableSignal<string | undefined>>;
 
-export { IONIC_CONFIG, IONIC_FIELD_TYPES, IonicButtonFieldComponent, IonicCheckboxFieldComponent, IonicDatepickerFieldComponent, IonicField, IonicInputFieldComponent, IonicMultiCheckboxFieldComponent, IonicRadioFieldComponent, IonicSelectFieldComponent, IonicSliderFieldComponent, IonicTextareaFieldComponent, IonicToggleFieldComponent, withIonicFields };
-export type { AddArrayItemButtonField, InsertArrayItemButtonField, IonicButtonField, IonicButtonProps, IonicCheckboxComponent, IonicCheckboxField, IonicCheckboxProps, IonicConfig, IonicDatepickerComponent, IonicDatepickerField, IonicDatepickerProps, IonicFieldType, IonicFormConfig, IonicFormProps, IonicInputComponent, IonicInputField, IonicInputProps, IonicMultiCheckboxComponent, IonicMultiCheckboxField, IonicMultiCheckboxProps, IonicNextButtonField, IonicPreviousButtonField, IonicRadioComponent, IonicRadioField, IonicRadioProps, IonicSelectComponent, IonicSelectField, IonicSelectProps, IonicSliderComponent, IonicSliderField, IonicSliderProps, IonicSubmitButtonField, IonicTextareaComponent, IonicTextareaField, IonicTextareaProps, IonicToggleComponent, IonicToggleField, IonicToggleProps, PopArrayItemButtonField, PrependArrayItemButtonField, RemoveArrayItemButtonField, ShiftArrayItemButtonField };
+export { IONIC_CONFIG, IONIC_FIELD_TYPES, IONIC_INPUT_TYPE_OVERRIDE, IonButtonAddonComponent, IonIconAddonComponent, IonicButtonFieldComponent, IonicCheckboxFieldComponent, IonicDatepickerFieldComponent, IonicField, IonicInputFieldComponent, IonicMultiCheckboxFieldComponent, IonicRadioFieldComponent, IonicSelectFieldComponent, IonicSliderFieldComponent, IonicTextareaFieldComponent, IonicToggleFieldComponent, withIonicAddons, withIonicFields };
+export type { AddArrayItemButtonField, InsertArrayItemButtonField, IonAddon, IonAddonExtensions, IonButtonAddon, IonIconAddon, IonInputAddon, IonicButtonField, IonicButtonProps, IonicCheckboxComponent, IonicCheckboxField, IonicCheckboxProps, IonicConfig, IonicDatepickerComponent, IonicDatepickerField, IonicDatepickerProps, IonicFieldType, IonicFormConfig, IonicFormProps, IonicInputComponent, IonicInputField, IonicInputProps, IonicMultiCheckboxComponent, IonicMultiCheckboxField, IonicMultiCheckboxProps, IonicNextButtonField, IonicPreviousButtonField, IonicRadioComponent, IonicRadioField, IonicRadioProps, IonicSelectComponent, IonicSelectField, IonicSelectProps, IonicSliderComponent, IonicSliderField, IonicSliderProps, IonicSubmitButtonField, IonicTextareaComponent, IonicTextareaField, IonicTextareaProps, IonicToggleComponent, IonicToggleField, IonicToggleProps, PopArrayItemButtonField, PrependArrayItemButtonField, RemoveArrayItemButtonField, ShiftArrayItemButtonField };