@ng-forge/dynamic-forms-ionic 0.10.0-next.1 → 0.10.0-next.3

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

@@ -16,9 +16,7 @@ interface IonicButtonProps {
     type?: 'button' | 'submit' | 'reset';
 }
 type IonicButtonField<TEvent extends FormEvent> = ButtonField<IonicButtonProps, TEvent>;
-/**
- * Specific button field types with preconfigured events
- */
+/** Specific button field types with preconfigured events */
 /** Submit button field - automatically disabled when form is invalid */
 type IonicSubmitButtonField = Omit<IonicButtonField<SubmitEvent>, 'event' | 'type' | 'eventArgs'> & {
     type: 'submit';
@@ -72,9 +70,7 @@ type InsertArrayItemButtonField = Omit<IonicButtonField<InsertArrayItemEvent>, '
      * When inside an array, this is automatically determined from context.
      */
     arrayKey?: string;
-    /**
-     * The index at which to insert the new item.
-     */
+    /** The index at which to insert the new item. */
     index: number;
     /**
      * Template for the new array item. REQUIRED.
@@ -174,16 +170,7 @@ declare class IonicDatepickerFieldComponent {
     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"`).
- */
+/** Decorative icon addon for Ion fields. */
 interface IonIconAddon extends BaseAddon {
     readonly kind: 'ion-icon';
     /** Ionons name (e.g., `'search-outline'`, `'close-outline'`). */
@@ -191,13 +178,9 @@ interface IonIconAddon extends BaseAddon {
     /** Accessible label for icons that convey meaning. */
     readonly ariaLabel?: DynamicText;
 }
-/**
- * Ionic-supported button colour palette.
- */
+/** Ionic-supported button colour palette. */
 type IonButtonColor = 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger' | 'light' | 'medium' | 'dark';
-/**
- * Ionic-supported button fill variants.
- */
+/** Ionic-supported button fill variants. */
 type IonButtonFill = 'clear' | 'outline' | 'solid' | 'default';
 /**
  * Common shape of every `ion-button` addon — properties that don't
@@ -216,14 +199,6 @@ interface IonButtonBase extends BaseAddon {
  * 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. */
@@ -261,13 +236,6 @@ type IonButtonClick = IonButtonClickPreset | IonButtonClickActionRef | IonButton
 /**
  * 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;
@@ -286,23 +254,7 @@ type IonButtonContentDecorative = {
     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.
- */
+/** Interactive button addon for Ion fields. */
 type IonButtonAddon = IonButtonBase & IonButtonContent & IonButtonClick;
 /** Union of all Ion-shipped addon kinds. */
 type IonAddon = IonIconAddon | IonButtonAddon;
@@ -326,31 +278,11 @@ interface IonicInputProps extends InputProps {
 /**
  * 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`.
- */
+/** Addon kinds accepted by `ion-input`. */
 type IonInputAddon = IonIconAddon | IonButtonAddon | TextAddon | TemplateAddon | IonAddonExtension;
 type IonicInputField = InputField<IonicInputProps> & {
     addons?: ReadonlyArray<IonInputAddon>;
@@ -374,9 +306,7 @@ declare class IonicInputFieldComponent {
     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. */
+    /**  Bootstrap / PrimeNG. Consumers can opt into Ionic's native inline 'start' */
     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`. */
@@ -551,65 +481,53 @@ declare class IonicToggleFieldComponent {
  */
 declare const IONIC_FIELD_TYPES: FieldTypeDefinition[];
 
-/**
- * Configuration options for Ionic form fields.
- *
- * 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: [...]
- * };
- * ```
- */
+/** Configuration options for Ionic form fields. */
 interface IonicConfig {
     /**
      * Default fill style for form inputs
+     *
      * @default 'solid'
      */
     fill?: 'solid' | 'outline';
     /**
      * Default shape for form controls
+     *
      * @default undefined
      */
     shape?: 'round';
     /**
      * Default label placement for form inputs
+     *
      * @default 'start'
      */
     labelPlacement?: 'start' | 'end' | 'fixed' | 'stacked' | 'floating';
     /**
      * Default color theme for form controls
+     *
      * @default 'primary'
      */
     color?: 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger' | 'light' | 'medium' | 'dark';
     /**
      * Default size for buttons
+     *
      * @default 'default'
      */
     size?: 'small' | 'default' | 'large';
     /**
      * Default expand behavior for buttons
+     *
      * @default undefined
      */
     expand?: 'full' | 'block';
     /**
      * Default fill style for buttons (overrides general fill if set)
+     *
      * @default 'solid'
      */
     buttonFill?: 'clear' | 'outline' | 'solid' | 'default';
     /**
      * Whether buttons should be strong (bold) by default
+     *
      * @default false
      */
     strong?: boolean;
@@ -618,23 +536,6 @@ interface IonicConfig {
 /**
  * Injection token for Ionic form configuration.
  * Use this to provide global configuration for Ionic form fields.
- *
- * @example
- * ```typescript
- * import { provideDynamicForm } from '@ng-forge/dynamic-forms';
- * import { withIonicFields } from '@ng-forge/dynamic-forms-ionic';
- *
- * export const appConfig: ApplicationConfig = {
- *   providers: [
- *     provideDynamicForm(
- *       ...withIonicFields({
- *         fill: 'outline',
- *         labelPlacement: 'floating'
- *       })
- *     )
- *   ]
- * };
- * ```
  */
 declare const IONIC_CONFIG: InjectionToken<IonicConfig>;
 
@@ -665,50 +566,9 @@ 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' },
- *   ],
- * };
- * ```
- */
+/** Ionic-specific props that can be set at form level and cascade to all fields. */
 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
- *   ],
- * };
- * ```
- */
+/** Ionic-specific FormConfig with type-safe defaultProps. */
 type IonicFormConfig<TFields extends NarrowFields | RegisteredFieldTypes[] = RegisteredFieldTypes[], TValue = InferFormValue<TFields extends readonly RegisteredFieldTypes[] ? TFields : RegisteredFieldTypes[]>> = FormConfig<TFields, TValue, IonicFormProps>;
 
 /**
@@ -741,9 +601,7 @@ declare module '@ng-forge/dynamic-forms' {
     }
 }
 
-/**
- * Field type definitions for Ionic components.
- */
+/** Field type definitions for Ionic components. */
 type IonicFieldTypes = FieldTypeDefinition[];
 type IonicConfigFeature = {
     ɵkind: 'ionic-config';
@@ -760,42 +618,7 @@ type IonicFieldsWithConfig = [...IonicFieldTypes, IonicAddonsFeature, IonicConfi
  * 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 — addons (ion-icon, ion-button) ship in automatically
- * import { ApplicationConfig } from '@angular/core';
- * import { provideDynamicForm } from '@ng-forge/dynamic-forms';
- * import { withIonicFields } from '@ng-forge/dynamic-forms-ionic';
- *
- * export const appConfig: ApplicationConfig = {
- *   providers: [
- *     provideDynamicForm(...withIonicFields())
- *   ]
- * };
- * ```
- *
- * @example
- * ```typescript
- * // With global configuration
- * export const appConfig: ApplicationConfig = {
- *   providers: [
- *     provideDynamicForm(
- *       ...withIonicFields({
- *         fill: 'outline',
- *         labelPlacement: 'floating'
- *       })
- *     )
- *   ]
- * };
- * ```
- *
  * @returns Tuple of field type definitions, the addons feature, and
  *   optionally a config feature.
  */
@@ -811,38 +634,10 @@ 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.
- */
+/** Register Ionic-shipped addon kinds (`ion-icon`, `ion-button`) standalone. */
 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.
- */
+/** Renderer for the `ion-button` addon kind. */
 declare class IonButtonAddonComponent {
     protected readonly action: i1.TypedNgForgeAddonAction<IonButtonAddon>;
     /** Re-exposed for template binding — same signal stored on the directive. */
@@ -865,13 +660,7 @@ declare class IonButtonAddonComponent {
     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.
- */
+/** Renderer for the `ion-icon` addon kind. */
 declare class IonIconAddonComponent {
     readonly addon: _angular_core.InputSignal<IonIconAddon>;
     /** Accepted for contract uniformity — `NgComponentOutlet` setInput is strict; every kind must declare it. */
@@ -883,17 +672,7 @@ declare class IonIconAddonComponent {
     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.
- */
+/** Per-field writable signal that overrides the input's `type` attribute. */
 declare const IONIC_INPUT_TYPE_OVERRIDE: InjectionToken<WritableSignal<string | undefined>>;
 
 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 };