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

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

@@ -1,8 +1,9 @@
 import * as _angular_core from '@angular/core';
-import { InjectionToken, Provider } from '@angular/core';
+import { InjectionToken, Provider, WritableSignal } from '@angular/core';
 import * as _ng_forge_dynamic_forms_integration from '@ng-forge/dynamic-forms/integration';
 import { CheckboxField, DatepickerField, DatepickerProps, InputField, InputProps, MultiCheckboxField, RadioField, SelectField, SelectProps, SliderField, ButtonField, TextareaField, TextareaProps, ToggleField } from '@ng-forge/dynamic-forms/integration';
-import { DynamicText, CheckedFieldComponent, ValueFieldComponent, ValueType, FieldOption, FormEvent, NextPageEvent, PreviousPageEvent, AppendArrayItemEvent, ArrayAllowedChildren, PrependArrayItemEvent, InsertArrayItemEvent, RemoveAtIndexEvent, PopArrayItemEvent, ShiftArrayItemEvent, FieldTypeDefinition, NarrowFields, RegisteredFieldTypes, InferFormValue, FormConfig } from '@ng-forge/dynamic-forms';
+import * as _ng_forge_dynamic_forms from '@ng-forge/dynamic-forms';
+import { DynamicText, CheckedFieldComponent, ValueFieldComponent, BaseAddon, DynamicValue, AddonActionPreset, RegisteredActionRef, AddonActionHandler, TextAddon, TemplateAddon, WrapperFieldInputs, ValueType, FieldOption, FormEvent, NextPageEvent, PreviousPageEvent, AppendArrayItemEvent, ArrayAllowedChildren, PrependArrayItemEvent, InsertArrayItemEvent, RemoveAtIndexEvent, PopArrayItemEvent, ShiftArrayItemEvent, FieldTypeDefinition, NarrowFields, RegisteredFieldTypes, InferFormValue, FormConfig } from '@ng-forge/dynamic-forms';
 import { ThemePalette } from '@angular/material/core';
 import * as _angular_material_form_field from '@angular/material/form-field';
 import { MatFormFieldAppearance, SubscriptSizing, FloatLabelType } from '@angular/material/form-field';
@@ -57,6 +58,122 @@ declare class MatDatepickerFieldComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<MatDatepickerFieldComponent, "df-mat-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 _ng_forge_dynamic_forms_integration.NgForgeFieldHost; inputs: {}; outputs: {}; }]>;
 }
 
+/**
+ * Decorative icon addon for Material fields.
+ *
+ * Renders `<mat-icon>{icon}</mat-icon>` using Material Icons ligatures —
+ * `icon: 'search'` produces `<mat-icon>search</mat-icon>`.
+ *
+ * Add `ariaLabel` for icons that convey meaning (search, error, success);
+ * leave it omitted for purely decorative icons (will be `aria-hidden="true"`).
+ */
+interface MatIconAddon extends BaseAddon {
+    readonly kind: 'mat-icon';
+    /** Material Icons name (ligature, e.g., `'search'`, `'close'`). */
+    readonly icon: string;
+    /** Accessible label for icons that convey meaning. */
+    readonly ariaLabel?: DynamicText;
+}
+/**
+ * Common shape of every `mat-button` addon — properties that don't
+ * participate in either XOR axis.
+ */
+interface MatButtonBase extends BaseAddon {
+    readonly kind: 'mat-button';
+    /** Material button colour variant. */
+    readonly color?: 'primary' | 'accent' | 'warn';
+    /** Reactive loading state — when truthy the button is disabled. */
+    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. Runtime XOR validation stays as defence-in-depth for
+ * JSON-source configs that bypass the type checker.
+ */
+type MatButtonClickPreset = {
+    /** 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 MatButtonActionRef = [RegisteredActionRef] extends [never] ? string : RegisteredActionRef;
+type MatButtonClickActionRef = {
+    readonly preset?: never;
+    /** Reference to a handler registered via `provideAddonActions(...)`. JSON-safe. */
+    readonly actionRef: MatButtonActionRef;
+    readonly action?: never;
+};
+type MatButtonClickAction = {
+    readonly preset?: never;
+    readonly actionRef?: never;
+    /** Inline handler — code-only; dropped from JSON-derived configs. */
+    readonly action: AddonActionHandler;
+};
+type MatButtonClickNone = {
+    readonly preset?: never;
+    readonly actionRef?: never;
+    readonly action?: never;
+};
+type MatButtonClick = MatButtonClickPreset | MatButtonClickActionRef | MatButtonClickAction | MatButtonClickNone;
+/**
+ * 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
+ */
+type MatButtonContentIconOnly = {
+    readonly icon: string;
+    readonly label?: never;
+    /** REQUIRED: icon-only buttons must carry an accessible label. */
+    readonly ariaLabel: DynamicText;
+};
+type MatButtonContentLabeled = {
+    readonly icon?: string;
+    readonly label: DynamicText;
+    readonly ariaLabel?: DynamicText;
+};
+type MatButtonContentDecorative = {
+    readonly icon?: never;
+    readonly label?: never;
+    readonly ariaLabel?: DynamicText;
+};
+type MatButtonContent = MatButtonContentIconOnly | MatButtonContentLabeled | MatButtonContentDecorative;
+/**
+ * Interactive button addon for Material fields.
+ *
+ * Renders `<button mat-icon-button>` (icon-only) or `<button mat-button>`
+ * (labeled). Click dispatch (preset / actionRef / action precedence) lives
+ * on `NgForgeAddonAction`; this addon shape focuses on configuration.
+ *
+ * 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.
+ */
+type MatButtonAddon = MatButtonBase & MatButtonContent & MatButtonClick;
+/** Union of all Material-shipped addon kinds. */
+type MatAddon = MatIconAddon | MatButtonAddon;
+declare module '@ng-forge/dynamic-forms' {
+    interface DynamicFormAddonRegistry {
+        'mat-icon': MatIconAddon;
+        'mat-button': MatButtonAddon;
+    }
+}
+
 interface MatInputProps extends InputProps {
     appearance?: MatFormFieldAppearance;
     disableRipple?: boolean;
@@ -66,20 +183,63 @@ interface MatInputProps extends InputProps {
     type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url';
     hint?: DynamicText;
 }
-type MatInputField = InputField<MatInputProps>;
+/**
+ * Module-augmentable seam for adding custom addon kinds to `mat-input` at
+ * the type level. Pair with `withCustomAddon(...)` for the runtime side:
+ *
+ * ```ts
+ * declare module '@ng-forge/dynamic-forms-material' {
+ *   interface MatAddonExtensions {
+ *     'my-rating': MyRatingAddon;
+ *   }
+ * }
+ * ```
+ *
+ * Empty by default — the extension lookup resolves to `never` and contributes
+ * nothing to the union.
+ */
+interface MatAddonExtensions {
+}
+type MatAddonExtension = MatAddonExtensions[keyof MatAddonExtensions];
+/**
+ * Addon kinds accepted by `mat-input`.
+ *
+ * Material-specific kinds (`mat-icon`, `mat-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 `MatAddonExtensions`.
+ */
+type MatInputAddon = MatIconAddon | MatButtonAddon | TextAddon | TemplateAddon | MatAddonExtension;
+type MatInputField = InputField<MatInputProps> & {
+    addons?: ReadonlyArray<MatInputAddon>;
+};
 /** @deprecated Scheduled for removal in v1. Use `injectNgForgeField<T>()` for typed access to a field component's directive instance. */
 type MatInputComponent = ValueFieldComponent<MatInputField>;
 
 declare class MatInputFieldComponent {
     private materialConfig;
     protected readonly ngf: _ng_forge_dynamic_forms_integration.TypedNgForgeField<string>;
+    protected readonly ngfa: _ng_forge_dynamic_forms_integration.TypedNgForgeAddons<MatInputAddon>;
     readonly props: _angular_core.InputSignal<MatInputProps | undefined>;
+    /**
+     * 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;
     readonly appearance: _angular_core.Signal<_angular_material_form_field.MatFormFieldAppearance>;
     readonly subscriptSizing: _angular_core.Signal<_angular_material_form_field.SubscriptSizing>;
     readonly floatLabel: _angular_core.Signal<_angular_material_form_field.FloatLabelType>;
     readonly hideRequiredMarker: _angular_core.Signal<boolean>;
+    /** Override (set by `toggle-password-visibility` preset) wins over `props().type`. */
+    protected readonly type: _angular_core.Signal<string>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<MatInputFieldComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MatInputFieldComponent, "df-mat-input", never, { "props": { "alias": "props"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof _ng_forge_dynamic_forms_integration.NgForgeFieldHost; inputs: {}; outputs: {}; }]>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MatInputFieldComponent, "df-mat-input", never, { "props": { "alias": "props"; "required": false; "isSignal": true; }; "fieldInputs": { "alias": "fieldInputs"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof _ng_forge_dynamic_forms_integration.NgForgeFieldHost; inputs: {}; outputs: {}; }, { directive: typeof _ng_forge_dynamic_forms_integration.NgForgeAddons; inputs: {}; outputs: {}; }]>;
 }
 
 interface MatMultiCheckboxProps {
@@ -526,19 +686,29 @@ type MaterialConfigFeature = {
     ɵkind: 'material-config';
     ɵproviders: Provider[];
 };
-type MaterialFieldsWithConfig = [...MaterialFieldTypes, MaterialConfigFeature];
 /**
- * Configure dynamic forms with Material Design field types.
- * Provides all Material Design field types for use with provideDynamicForm.
+ * Default `withMaterialFields()` shape — field defs + the auto-included
+ * addons feature so `mat-icon` / `mat-button` work out of the box.
+ */
+type MaterialFieldsWithAddons = [...MaterialFieldTypes, MaterialAddonsFeature];
+type MaterialFieldsWithConfig = [...MaterialFieldTypes, MaterialAddonsFeature, MaterialConfigFeature];
+/**
+ * Configure dynamic forms with Material Design field types, with
+ * Material-shipped addon kinds (`mat-icon`, `mat-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), call `withMaterialAddons()` standalone.
  *
  * @param config - Optional global configuration for Material form fields
  *
  * @example
  * ```typescript
- * // Application-level setup
+ * // Application-level setup — addons (mat-icon, mat-button) ship in automatically
  * import { ApplicationConfig } from '@angular/core';
- * import { provideDynamicForm } from '@ng-forge/dynamic-form';
- * import { withMaterialFields } from '@ng-forge/dynamic-form-material';
+ * import { provideDynamicForm } from '@ng-forge/dynamic-forms';
+ * import { withMaterialFields } from '@ng-forge/dynamic-forms-material';
  *
  * export const appConfig: ApplicationConfig = {
  *   providers: [
@@ -562,11 +732,100 @@ type MaterialFieldsWithConfig = [...MaterialFieldTypes, MaterialConfigFeature];
  * };
  * ```
  *
- * @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 withMaterialFields(): MaterialFieldTypes;
+declare function withMaterialFields(): MaterialFieldsWithAddons;
 declare function withMaterialFields(config: MaterialConfig): MaterialFieldsWithConfig;
-declare function withMaterialFields(config: MaterialConfig | undefined): MaterialFieldTypes | MaterialFieldsWithConfig;
+declare function withMaterialFields(config: MaterialConfig | undefined): MaterialFieldsWithAddons | MaterialFieldsWithConfig;
+/**
+ * Feature kind discriminant for the Material addons feature. Matches core's
+ * `'addons'` kind so providers flow through the standard addon-kind pipeline
+ * in `provideDynamicForm`.
+ */
+type MaterialAddonsFeature = {
+    ɵkind: 'addons';
+    ɵproviders: Provider[];
+};
+/**
+ * Register Material-shipped addon kinds (`mat-icon`, `mat-button`) standalone.
+ *
+ * **Most users don't need this** — `withMaterialFields()` auto-includes
+ * these kinds. Call `withMaterialAddons()` directly only when you want
+ * Material addon kinds without the Material field types (e.g., a custom
+ * field set that wants to render `mat-icon` prefixes), or when you're
+ * stitching addons through a different DI scope.
+ *
+ * @example
+ * ```typescript
+ * // Custom field types + Material addon kinds.
+ * provideDynamicForm(
+ *   ...myCustomFields(),
+ *   withMaterialAddons(),
+ * );
+ * ```
+ *
+ * Adapter authors who need to override a kind with a customised renderer
+ * should call `withCustomAddon(...)` directly instead.
+ */
+declare function withMaterialAddons(): MaterialAddonsFeature;
+
+/**
+ * Renderer for the `mat-icon` addon kind.
+ *
+ * Outputs `<mat-icon>{icon}</mat-icon>` using Material Icons ligatures. 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 MatIconAddonComponent {
+    readonly addon: _angular_core.InputSignal<MatIconAddon>;
+    /** Accepted for contract uniformity — `NgComponentOutlet` setInput is strict; every kind must declare it. */
+    readonly fieldInputs: _angular_core.InputSignal<WrapperFieldInputs | undefined>;
+    protected readonly ariaLabel: _angular_core.Signal<_ng_forge_dynamic_forms.DynamicText | undefined>;
+    protected readonly hasAriaLabel: _angular_core.Signal<boolean>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MatIconAddonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MatIconAddonComponent, "df-mat-icon-addon", never, { "addon": { "alias": "addon"; "required": true; "isSignal": true; }; "fieldInputs": { "alias": "fieldInputs"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Renderer for the `mat-button` addon kind.
+ *
+ * Renders `<button mat-icon-button>` when icon-only (no label), or
+ * `<button mat-button>` when labeled. Click dispatch (preset / actionRef /
+ * action precedence, multi-set warning, `disabled` / `loading` resolution)
+ * lives on `NgForgeAddonAction`; this component focuses on the visual layer.
+ */
+declare class MatButtonAddonComponent {
+    protected readonly action: _ng_forge_dynamic_forms_integration.TypedNgForgeAddonAction<MatButtonAddon>;
+    /** Re-exposed for template binding — same signal stored on the directive. */
+    protected readonly addon: _angular_core.Signal<MatButtonAddon>;
+    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 isIconOnly: _angular_core.Signal<boolean>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MatButtonAddonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MatButtonAddonComponent, "df-mat-button-addon", never, {}, {}, never, never, true, [{ directive: typeof _ng_forge_dynamic_forms_integration.NgForgeAddonAction; inputs: {}; outputs: {}; }]>;
+}
+
+/**
+ * Per-field writable signal that overrides the input's `type` attribute.
+ *
+ * Provided at the `mat-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.
+ *
+ * @example provided per-field:
+ * ```typescript
+ * @Component({
+ *   providers: [{ provide: MAT_INPUT_TYPE_OVERRIDE, useValue: signal(undefined) }],
+ * })
+ * class MatInputFieldComponent { ... }
+ * ```
+ */
+declare const MAT_INPUT_TYPE_OVERRIDE: InjectionToken<WritableSignal<string | undefined>>;
 
-export { MATERIAL_CONFIG, MATERIAL_FIELD_TYPES, MatButtonFieldComponent, MatCheckboxFieldComponent, MatDatepickerFieldComponent, MatField, MatInputFieldComponent, MatMultiCheckboxFieldComponent, MatRadioFieldComponent, MatSelectFieldComponent, MatSliderFieldComponent, MatTextareaFieldComponent, MatToggleFieldComponent, withMaterialFields };
-export type { AddArrayItemButtonField, InsertArrayItemButtonField, MatButtonField, MatButtonProps, MatCheckboxComponent, MatCheckboxField, MatCheckboxProps, MatDatepickerComponent, MatDatepickerField, MatDatepickerProps, MatFieldType, MatFormConfig, MatFormProps, MatInputComponent, MatInputField, MatInputProps, MatMultiCheckboxComponent, MatMultiCheckboxField, MatMultiCheckboxProps, MatNextButtonField, MatPreviousButtonField, MatRadioComponent, MatRadioField, MatRadioProps, MatSelectComponent, MatSelectField, MatSelectProps, MatSliderComponent, MatSliderField, MatSliderProps, MatSubmitButtonField, MatTextareaComponent, MatTextareaField, MatTextareaProps, MatToggleComponent, MatToggleField, MatToggleProps, MaterialConfig, PopArrayItemButtonField, PrependArrayItemButtonField, RemoveArrayItemButtonField, ShiftArrayItemButtonField };
+export { MATERIAL_CONFIG, MATERIAL_FIELD_TYPES, MAT_INPUT_TYPE_OVERRIDE, MatButtonAddonComponent, MatButtonFieldComponent, MatCheckboxFieldComponent, MatDatepickerFieldComponent, MatField, MatIconAddonComponent, MatInputFieldComponent, MatMultiCheckboxFieldComponent, MatRadioFieldComponent, MatSelectFieldComponent, MatSliderFieldComponent, MatTextareaFieldComponent, MatToggleFieldComponent, withMaterialAddons, withMaterialFields };
+export type { AddArrayItemButtonField, InsertArrayItemButtonField, MatAddon, MatAddonExtensions, MatButtonAddon, MatButtonField, MatButtonProps, MatCheckboxComponent, MatCheckboxField, MatCheckboxProps, MatDatepickerComponent, MatDatepickerField, MatDatepickerProps, MatFieldType, MatFormConfig, MatFormProps, MatIconAddon, MatInputAddon, MatInputComponent, MatInputField, MatInputProps, MatMultiCheckboxComponent, MatMultiCheckboxField, MatMultiCheckboxProps, MatNextButtonField, MatPreviousButtonField, MatRadioComponent, MatRadioField, MatRadioProps, MatSelectComponent, MatSelectField, MatSelectProps, MatSliderComponent, MatSliderField, MatSliderProps, MatSubmitButtonField, MatTextareaComponent, MatTextareaField, MatTextareaProps, MatToggleComponent, MatToggleField, MatToggleProps, MaterialConfig, PopArrayItemButtonField, PrependArrayItemButtonField, RemoveArrayItemButtonField, ShiftArrayItemButtonField };