@ng-forge/dynamic-forms-ionic 0.3.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-forge/dynamic-forms-ionic",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Ionic integration for @ng-forge/dynamic-forms. Pre-built Ionic form components for mobile and desktop.",
   "type": "module",
   "license": "MIT",
@@ -24,16 +24,16 @@
     "form-builder",
     "ng-forge"
   ],
-  "sideEffects": false,
+  "sideEffects": true,
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "peerDependencies": {
-    "@angular/common": ">=21.0.7",
-    "@angular/core": ">=21.0.7",
-    "@angular/forms": ">=21.0.7",
+    "@angular/common": "~21.1.0",
+    "@angular/core": "~21.1.0",
+    "@angular/forms": "~21.1.0",
     "@ionic/angular": ">=7.0.0",
-    "@ng-forge/dynamic-forms": "~0.3.0",
+    "@ng-forge/dynamic-forms": "~0.4.0",
     "rxjs": ">=7.0.0"
   },
   "dependencies": {

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

@@ -1,4 +1,4 @@
-import { FormEvent, FieldDef, LogicConfig, FieldComponent, DynamicText, FormEventConstructor, ArrayItemContext, CheckedFieldComponent, FieldMeta, ValidationMessages, ValueFieldComponent, ValueType, FieldOption, FieldTypeDefinition } from '@ng-forge/dynamic-forms';
+import { FormEvent, FieldDef, LogicConfig, 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 _angular_core from '@angular/core';
@@ -114,6 +114,7 @@ interface IonicCheckboxProps {
     justify?: 'start' | 'end' | 'space-between';
     color?: 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger';
     indeterminate?: boolean;
+    hint?: DynamicText;
 }
 type IonicCheckboxField = CheckboxField<IonicCheckboxProps>;
 type IonicCheckboxComponent = CheckedFieldComponent<IonicCheckboxField>;
@@ -135,11 +136,15 @@ declare class IonicCheckboxFieldComponent implements IonicCheckboxComponent {
     readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
     constructor();
     /** Base ID for error elements */
-    readonly errorId: _angular_core.Signal<string>;
+    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) */
-    readonly isAriaInvalid: _angular_core.Signal<boolean>;
+    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
     /** Whether the field has a required validator */
-    readonly isRequired: _angular_core.Signal<boolean>;
+    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>;
 }
@@ -156,6 +161,7 @@ interface IonicDatepickerProps extends DatepickerProps {
     cancelText?: string;
     size?: 'cover' | 'fixed';
     color?: 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger';
+    hint?: DynamicText;
 }
 type IonicDatepickerField = DatepickerField<IonicDatepickerProps>;
 type IonicDatepickerComponent = ValueFieldComponent<IonicDatepickerField>;
@@ -181,11 +187,15 @@ declare class IonicDatepickerFieldComponent implements IonicDatepickerComponent
     readonly isModalOpen: _angular_core.WritableSignal<boolean>;
     constructor();
     /** Base ID for error elements */
-    readonly errorId: _angular_core.Signal<string>;
+    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) */
-    readonly isAriaInvalid: _angular_core.Signal<boolean>;
+    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
     /** Whether the field has a required validator */
-    readonly isRequired: _angular_core.Signal<boolean>;
+    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;
@@ -200,7 +210,7 @@ interface IonicInputProps extends InputProps {
     shape?: 'round';
     labelPlacement?: 'start' | 'end' | 'fixed' | 'stacked' | 'floating';
     color?: 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger' | 'light' | 'medium' | 'dark';
-    helperText?: DynamicText;
+    hint?: DynamicText;
     errorText?: DynamicText;
     counter?: boolean;
     maxlength?: number;
@@ -232,33 +242,38 @@ declare class IonicInputFieldComponent implements IonicInputComponent {
     readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
     constructor();
     /** Base ID for error elements */
-    readonly errorId: _angular_core.Signal<string>;
+    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) */
-    readonly isAriaInvalid: _angular_core.Signal<boolean>;
+    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
     /** Whether the field has a required validator */
-    readonly isRequired: _angular_core.Signal<boolean>;
+    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>;
 }
 
-interface IonicMultiCheckboxProps<T> {
+interface IonicMultiCheckboxProps {
     labelPlacement?: 'start' | 'end' | 'fixed' | 'stacked';
     justify?: 'start' | 'end' | 'space-between';
     color?: 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger';
+    hint?: DynamicText;
 }
-type IonicMultiCheckboxField<T> = MultiCheckboxField<T, IonicMultiCheckboxProps<T>>;
-type IonicMultiCheckboxComponent<T> = ValueFieldComponent<IonicMultiCheckboxField<T>>;
+type IonicMultiCheckboxField<T> = MultiCheckboxField<T, IonicMultiCheckboxProps>;
+type IonicMultiCheckboxComponent = ValueFieldComponent<IonicMultiCheckboxField<ValueType>>;
 
-declare class IonicMultiCheckboxFieldComponent<T extends ValueType> implements IonicMultiCheckboxComponent<T> {
+declare class IonicMultiCheckboxFieldComponent implements IonicMultiCheckboxComponent {
     private readonly elementRef;
-    readonly field: _angular_core.InputSignal<FieldTree<T[]>>;
+    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>;
-    readonly options: _angular_core.InputSignal<FieldOption<T>[]>;
-    readonly props: _angular_core.InputSignal<IonicMultiCheckboxProps<T> | undefined>;
+    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>;
@@ -266,37 +281,44 @@ declare class IonicMultiCheckboxFieldComponent<T extends ValueType> implements I
     readonly showErrors: _angular_core.Signal<boolean>;
     readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
     /** Base ID for error elements */
-    readonly errorId: _angular_core.Signal<string>;
+    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) */
-    readonly isAriaInvalid: _angular_core.Signal<boolean>;
+    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
     /** Whether the field has a required validator */
-    readonly isRequired: _angular_core.Signal<boolean>;
-    valueViewModel: _angular_core.WritableSignal<FieldOption<T>[]>;
+    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<T>, checked: boolean): void;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<IonicMultiCheckboxFieldComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicMultiCheckboxFieldComponent<any>, "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>;
+    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>;
 }
 
-interface IonicRadioProps<T> {
+interface IonicRadioProps {
     labelPlacement?: 'start' | 'end' | 'fixed' | 'stacked';
     justify?: 'start' | 'end' | 'space-between';
     color?: 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger';
-    compareWith?: (o1: T, o2: T) => boolean;
+    compareWith?: (o1: ValueType, o2: ValueType) => boolean;
+    hint?: DynamicText;
 }
-type IonicRadioField<T> = RadioField<T, IonicRadioProps<T>>;
-type IonicRadioComponent<T> = ValueFieldComponent<IonicRadioField<T>>;
+type IonicRadioField<T> = RadioField<T, IonicRadioProps>;
+type IonicRadioComponent = ValueFieldComponent<IonicRadioField<ValueType>>;
 
-declare class IonicRadioFieldComponent<T> implements IonicRadioComponent<T> {
+declare class IonicRadioFieldComponent implements IonicRadioComponent {
     private readonly elementRef;
-    readonly field: _angular_core.InputSignal<FieldTree<T>>;
+    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>;
-    readonly options: _angular_core.InputSignal<FieldOption<T>[]>;
-    readonly props: _angular_core.InputSignal<IonicRadioProps<T> | undefined>;
+    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>;
@@ -306,16 +328,20 @@ declare class IonicRadioFieldComponent<T> implements IonicRadioComponent<T> {
     defaultCompare: (value1: any, value2: any) => boolean;
     constructor();
     /** Base ID for error elements */
-    readonly errorId: _angular_core.Signal<string>;
+    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) */
-    readonly isAriaInvalid: _angular_core.Signal<boolean>;
+    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
     /** Whether the field has a required validator */
-    readonly isRequired: _angular_core.Signal<boolean>;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<IonicRadioFieldComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicRadioFieldComponent<any>, "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>;
+    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>;
 }
 
-interface IonicSelectProps<T> extends SelectProps {
+interface IonicSelectProps extends SelectProps {
     multiple?: boolean;
     interface?: 'action-sheet' | 'popover' | 'alert';
     interfaceOptions?: unknown;
@@ -326,21 +352,22 @@ interface IonicSelectProps<T> extends SelectProps {
     shape?: 'round';
     labelPlacement?: 'start' | 'end' | 'fixed' | 'stacked' | 'floating';
     color?: 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger';
-    compareWith?: (o1: T, o2: T) => boolean;
+    compareWith?: (o1: ValueType, o2: ValueType) => boolean;
+    hint?: DynamicText;
 }
-type IonicSelectField<T> = SelectField<T, IonicSelectProps<T>>;
-type IonicSelectComponent<T> = ValueFieldComponent<IonicSelectField<T>>;
+type IonicSelectField<T> = SelectField<T, IonicSelectProps>;
+type IonicSelectComponent = ValueFieldComponent<IonicSelectField<ValueType>>;
 
-declare class IonicSelectFieldComponent<T> implements IonicSelectComponent<T> {
+declare class IonicSelectFieldComponent implements IonicSelectComponent {
     private readonly elementRef;
-    readonly field: _angular_core.InputSignal<FieldTree<T>>;
+    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>;
-    readonly options: _angular_core.InputSignal<FieldOption<T>[]>;
-    readonly props: _angular_core.InputSignal<IonicSelectProps<T> | undefined>;
+    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>;
@@ -350,13 +377,17 @@ declare class IonicSelectFieldComponent<T> implements IonicSelectComponent<T> {
     readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
     defaultCompare: (value1: any, value2: any) => boolean;
     /** Base ID for error elements */
-    readonly errorId: _angular_core.Signal<string>;
+    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) */
-    readonly isAriaInvalid: _angular_core.Signal<boolean>;
+    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
     /** Whether the field has a required validator */
-    readonly isRequired: _angular_core.Signal<boolean>;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<IonicSelectFieldComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IonicSelectFieldComponent<any>, "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>;
+    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>;
 }
 
 interface IonicSliderProps {
@@ -370,6 +401,7 @@ interface IonicSliderProps {
     snaps?: boolean;
     color?: 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger';
     labelPlacement?: 'start' | 'end' | 'fixed' | 'stacked';
+    hint?: DynamicText;
 }
 type IonicSliderField = SliderField<IonicSliderProps>;
 type IonicSliderComponent = ValueFieldComponent<IonicSliderField>;
@@ -392,11 +424,15 @@ declare class IonicSliderFieldComponent implements IonicSliderComponent {
     readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
     protected defaultPinFormatter: (value: number) => string;
     /** Base ID for error elements */
-    readonly errorId: _angular_core.Signal<string>;
+    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) */
-    readonly isAriaInvalid: _angular_core.Signal<boolean>;
+    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
     /** Whether the field has a required validator */
-    readonly isRequired: _angular_core.Signal<boolean>;
+    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; }; "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>;
 }
@@ -409,7 +445,7 @@ interface IonicTextareaProps extends TextareaProps {
     fill?: 'solid' | 'outline';
     shape?: 'round';
     labelPlacement?: 'start' | 'end' | 'fixed' | 'stacked' | 'floating';
-    helperText?: DynamicText;
+    hint?: DynamicText;
     errorText?: DynamicText;
     color?: 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger' | 'light' | 'medium' | 'dark';
 }
@@ -433,11 +469,15 @@ declare class IonicTextareaFieldComponent implements IonicTextareaComponent {
     readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
     constructor();
     /** Base ID for error elements */
-    readonly errorId: _angular_core.Signal<string>;
+    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) */
-    readonly isAriaInvalid: _angular_core.Signal<boolean>;
+    protected readonly ariaInvalid: _angular_core.Signal<boolean>;
     /** Whether the field has a required validator */
-    readonly isRequired: _angular_core.Signal<boolean>;
+    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>;
 }
@@ -447,6 +487,7 @@ interface IonicToggleProps {
     justify?: 'start' | 'end' | 'space-between';
     color?: 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger';
     enableOnOffLabels?: boolean;
+    hint?: DynamicText;
 }
 type IonicToggleField = ToggleField<IonicToggleProps>;
 type IonicToggleComponent = CheckedFieldComponent<IonicToggleField>;
@@ -468,7 +509,11 @@ declare class IonicToggleFieldComponent implements IonicToggleComponent {
     readonly showErrors: _angular_core.Signal<boolean>;
     readonly errorsToDisplay: _angular_core.Signal<_ng_forge_dynamic_forms_integration.ResolvedError[]>;
     /** Base ID for error elements */
-    readonly errorId: _angular_core.Signal<string>;
+    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>;
 }
@@ -481,8 +526,24 @@ declare const IONIC_FIELD_TYPES: FieldTypeDefinition[];
 
 /**
  * Configuration options for Ionic form fields.
- * These settings will be applied as defaults to all Ionic form fields
- * unless overridden by individual field props.
+ *
+ * These settings can be applied at two levels:
+ * - **Library-level**: Via `withIonicFields({ ... })` - applies to all forms
+ * - **Form-level**: Via `defaultProps` in form config - applies to a specific form
+ *
+ * The cascade hierarchy is: Library-level → Form-level → Field-level
+ *
+ * @example
+ * ```typescript
+ * // Library-level (in app config)
+ * provideDynamicForms(withIonicFields({ fill: 'outline', labelPlacement: 'floating' }))
+ *
+ * // Form-level (in form config)
+ * const config: IonicFormConfig = {
+ *   defaultProps: { color: 'tertiary' },
+ *   fields: [...]
+ * };
+ * ```
  */
 interface IonicConfig {
     /**
@@ -573,6 +634,52 @@ declare const IonicField: {
 };
 type IonicFieldType = (typeof IonicField)[keyof typeof IonicField];
 
+/**
+ * Ionic-specific props that can be set at form level and cascade to all fields.
+ *
+ * This is the same type as `IonicConfig` used in `withIonicFields()`.
+ * Using a single type ensures consistency between library-level and form-level configuration.
+ *
+ * The cascade hierarchy is: Library-level → Form-level → Field-level
+ *
+ * @example
+ * ```typescript
+ * const config: IonicFormConfig = {
+ *   defaultProps: {
+ *     fill: 'outline',
+ *     labelPlacement: 'floating',
+ *     color: 'tertiary',
+ *   },
+ *   fields: [
+ *     { type: 'ionic-input', key: 'name', label: 'Name' },
+ *   ],
+ * };
+ * ```
+ */
+type IonicFormProps = IonicConfig;
+/**
+ * Ionic-specific FormConfig with type-safe defaultProps.
+ *
+ * Use this type alias when defining form configurations with Ionic components
+ * to get IDE autocomplete and type checking for `defaultProps`.
+ *
+ * @example
+ * ```typescript
+ * const formConfig: IonicFormConfig = {
+ *   defaultProps: {
+ *     fill: 'outline',
+ *     labelPlacement: 'floating',
+ *     color: 'primary',
+ *   },
+ *   fields: [
+ *     { type: 'ionic-input', key: 'name', label: 'Name' },  // Uses form defaultProps
+ *     { type: 'ionic-input', key: 'email', props: { fill: 'solid' } },  // Override
+ *   ],
+ * };
+ * ```
+ */
+type IonicFormConfig<TFields extends NarrowFields | RegisteredFieldTypes[] = RegisteredFieldTypes[], TValue = InferFormValue<TFields extends readonly RegisteredFieldTypes[] ? TFields : RegisteredFieldTypes[]>> = FormConfig<TFields, TValue, IonicFormProps>;
+
 /**
  * Module augmentation for @ng-forge/dynamic-form
  * This file augments the FieldRegistryLeaves interface to include
@@ -666,4 +773,4 @@ declare module '@ng-forge/dynamic-forms' {
 }
 
 export { IONIC_CONFIG, IONIC_FIELD_TYPES, IonicButtonFieldComponent, IonicCheckboxFieldComponent, IonicDatepickerFieldComponent, IonicField, IonicInputFieldComponent, IonicMultiCheckboxFieldComponent, IonicRadioFieldComponent, IonicSelectFieldComponent, IonicSliderFieldComponent, IonicTextareaFieldComponent, IonicToggleFieldComponent, withIonicFields };
-export type { AddArrayItemButtonField, IonicButtonField, IonicButtonProps, IonicCheckboxComponent, IonicCheckboxField, IonicCheckboxProps, IonicConfig, IonicDatepickerComponent, IonicDatepickerField, IonicDatepickerProps, IonicFieldType, IonicInputComponent, IonicInputField, IonicInputProps, IonicMultiCheckboxComponent, IonicMultiCheckboxField, IonicMultiCheckboxProps, IonicNextButtonField, IonicPreviousButtonField, IonicRadioComponent, IonicRadioField, IonicRadioProps, IonicSelectComponent, IonicSelectField, IonicSelectProps, IonicSliderComponent, IonicSliderField, IonicSliderProps, IonicSubmitButtonField, IonicTextareaComponent, IonicTextareaField, IonicTextareaProps, IonicToggleComponent, IonicToggleField, IonicToggleProps, RemoveArrayItemButtonField };
+export type { AddArrayItemButtonField, 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, RemoveArrayItemButtonField };