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

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

@@ -1,8 +1,9 @@
-import { FormEvent, NextPageEvent, PreviousPageEvent, AppendArrayItemEvent, ArrayAllowedChildren, PrependArrayItemEvent, InsertArrayItemEvent, RemoveAtIndexEvent, PopArrayItemEvent, ShiftArrayItemEvent, DynamicText, CheckedFieldComponent, ValueFieldComponent, ValueType, FieldOption, FieldTypeDefinition, NarrowFields, RegisteredFieldTypes, InferFormValue, FormConfig } from '@ng-forge/dynamic-forms';
+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 _ng_forge_dynamic_forms_integration 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 { InjectionToken, Provider, WritableSignal } from '@angular/core';
 
 interface BsButtonProps {
     variant?: 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'light' | 'dark' | 'link';
@@ -168,6 +169,119 @@ declare class BsDatepickerFieldComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<BsDatepickerFieldComponent, "df-bs-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 Bootstrap fields.
+ *
+ * Renders `<i class="bi bi-{icon}">` (Bootstrap Icons). The `icon` string is the
+ * bare suffix — e.g., `'search'` produces `<i class="bi bi-search">`.
+ *
+ * Add `ariaLabel` for icons that convey meaning (search, error, success);
+ * leave it omitted for purely decorative icons (will be `aria-hidden="true"`).
+ */
+interface BsIconAddon extends BaseAddon {
+    readonly kind: 'bs-icon';
+    /** Bootstrap Icons name without the `bi-` prefix (e.g., `'search'`, `'x'`). */
+    readonly icon: string;
+    /** Accessible label for icons that convey meaning. */
+    readonly ariaLabel?: DynamicText;
+}
+/**
+ * Common shape of every `bs-button` addon — properties that don't
+ * participate in either XOR axis.
+ */
+interface BsButtonBase extends BaseAddon {
+    readonly kind: 'bs-button';
+    /** Bootstrap button variant (mapped to `btn-outline-{severity}`). */
+    readonly severity?: 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'light' | 'dark';
+    /** Reactive loading state — swaps the button content for a spinner. */
+    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.
+ */
+type BsButtonClickPreset = {
+    /** 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. Fall back to `string` so the
+ * variant stays usable; once the user augments `DynamicFormActionRegistry`,
+ * autocomplete tightens to the registered keys.
+ */
+type BsButtonActionRef = [RegisteredActionRef] extends [never] ? string : RegisteredActionRef;
+type BsButtonClickActionRef = {
+    readonly preset?: never;
+    /** Reference to a handler registered via `provideAddonActions(...)`. JSON-safe. */
+    readonly actionRef: BsButtonActionRef;
+    readonly action?: never;
+};
+type BsButtonClickAction = {
+    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 BsButtonClickNone = {
+    readonly preset?: never;
+    readonly actionRef?: never;
+    readonly action?: never;
+};
+type BsButtonClick = BsButtonClickPreset | BsButtonClickActionRef | BsButtonClickAction | BsButtonClickNone;
+/**
+ * Content axis — XOR enforced at type level so an icon-only button is
+ * forced to declare `ariaLabel`.
+ */
+type BsButtonContentIconOnly = {
+    readonly icon: string;
+    readonly label?: never;
+    /** REQUIRED: icon-only buttons must carry an accessible label. */
+    readonly ariaLabel: DynamicText;
+};
+type BsButtonContentLabeled = {
+    readonly icon?: string;
+    readonly label: DynamicText;
+    readonly ariaLabel?: DynamicText;
+};
+type BsButtonContentDecorative = {
+    readonly icon?: never;
+    readonly label?: never;
+    readonly ariaLabel?: DynamicText;
+};
+type BsButtonContent = BsButtonContentIconOnly | BsButtonContentLabeled | BsButtonContentDecorative;
+/**
+ * Interactive button addon for Bootstrap fields.
+ *
+ * Renders `<button class="btn btn-outline-{severity}">` with optional icon,
+ * label, severity, and reactive loading state.
+ *
+ * Type-level guarantees:
+ *
+ * - **Content axis (XOR):** `IconOnly` (icon + required ariaLabel) |
+ *   `Labeled` (label, icon optional) | `Decorative` (neither).
+ * - **Click axis (XOR):** exactly one of `preset` / `actionRef` / `action`,
+ *   or none.
+ */
+type BsButtonAddon = BsButtonBase & BsButtonContent & BsButtonClick;
+/** Union of all Bootstrap-shipped addon kinds. */
+type BsAddon = BsIconAddon | BsButtonAddon;
+declare module '@ng-forge/dynamic-forms' {
+    interface DynamicFormAddonRegistry {
+        'bs-icon': BsIconAddon;
+        'bs-button': BsButtonAddon;
+    }
+}
+
 interface BsInputProps extends InputProps {
     size?: 'sm' | 'lg';
     floatingLabel?: boolean;
@@ -177,18 +291,60 @@ interface BsInputProps extends InputProps {
     plaintext?: boolean;
     type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url';
 }
-type BsInputField = InputField<BsInputProps>;
+/**
+ * Module-augmentable seam for adding custom addon kinds to `bs-input` at
+ * the type level. Pair with `withCustomAddon(...)` for the runtime side:
+ *
+ * ```ts
+ * declare module '@ng-forge/dynamic-forms-bootstrap' {
+ *   interface BsAddonExtensions {
+ *     'my-rating': MyRatingAddon;
+ *   }
+ * }
+ * ```
+ *
+ * Empty by default — the extension lookup resolves to `never` and contributes
+ * nothing to the union.
+ */
+interface BsAddonExtensions {
+}
+type BsAddonExtension = BsAddonExtensions[keyof BsAddonExtensions];
+/**
+ * Addon kinds accepted by `bs-input`.
+ *
+ * Bootstrap-specific kinds (`bs-icon`, `bs-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 `BsAddonExtensions`.
+ */
+type BsInputAddon = BsIconAddon | BsButtonAddon | TextAddon | TemplateAddon | BsAddonExtension;
+type BsInputField = InputField<BsInputProps> & {
+    addons?: ReadonlyArray<BsInputAddon>;
+};
 /** @deprecated Scheduled for removal in v1. Use `injectNgForgeField<T>()` for typed access to a field component's directive instance. */
 type BsInputComponent = ValueFieldComponent<BsInputField>;
 
 declare class BsInputFieldComponent {
     private bootstrapConfig;
     protected readonly ngf: _ng_forge_dynamic_forms_integration.TypedNgForgeField<string>;
+    protected readonly ngfa: _ng_forge_dynamic_forms_integration.TypedNgForgeAddons<BsInputAddon>;
     readonly props: _angular_core.InputSignal<BsInputProps | 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 size: _angular_core.Signal<"sm" | "lg" | undefined>;
     readonly floatingLabel: _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<BsInputFieldComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<BsInputFieldComponent, "df-bs-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<BsInputFieldComponent, "df-bs-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 BsMultiCheckboxProps {
@@ -516,19 +672,28 @@ type BootstrapConfigFeature = {
     ɵkind: 'bootstrap-config';
     ɵproviders: Provider[];
 };
-type BootstrapFieldsWithConfig = [...BootstrapFieldTypes, BootstrapConfigFeature];
 /**
- * Provides Bootstrap field types for the dynamic form system.
- * Use with provideDynamicForm(...withBootstrapFields())
+ * Default `withBootstrapFields()` shape — field defs + the auto-included
+ * addons feature so `bs-icon` / `bs-button` work out of the box.
+ */
+type BootstrapFieldsWithAddons = [...BootstrapFieldTypes, BootstrapAddonsFeature];
+type BootstrapFieldsWithConfig = [...BootstrapFieldTypes, BootstrapAddonsFeature, BootstrapConfigFeature];
+/**
+ * Provides Bootstrap field type definitions for the dynamic form system,
+ * with Bootstrap-shipped addon kinds (`bs-icon`, `bs-button`) auto-included
+ * so addons work out of the box.
+ *
+ * If you want addons WITHOUT the field types (rare — e.g., adding addons to
+ * a form that uses custom fields), call `withBootstrapAddons()` standalone.
  *
  * @param config - Optional global configuration for Bootstrap form fields
  *
  * @example
  * ```typescript
- * // Application-level setup
+ * // Application-level setup — addons (bs-icon, bs-button) ship in automatically
  * import { ApplicationConfig } from '@angular/core';
- * import { provideDynamicForm } from '@ng-forge/dynamic-form';
- * import { withBootstrapFields } from '@ng-forge/dynamic-form-bootstrap';
+ * import { provideDynamicForm } from '@ng-forge/dynamic-forms';
+ * import { withBootstrapFields } from '@ng-forge/dynamic-forms-bootstrap';
  *
  * export const appConfig: ApplicationConfig = {
  *   providers: [
@@ -552,11 +717,94 @@ type BootstrapFieldsWithConfig = [...BootstrapFieldTypes, BootstrapConfigFeature
  * };
  * ```
  *
- * @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 withBootstrapFields(): BootstrapFieldTypes;
+declare function withBootstrapFields(): BootstrapFieldsWithAddons;
 declare function withBootstrapFields(config: BootstrapConfig): BootstrapFieldsWithConfig;
-declare function withBootstrapFields(config: BootstrapConfig | undefined): BootstrapFieldTypes | BootstrapFieldsWithConfig;
+declare function withBootstrapFields(config: BootstrapConfig | undefined): BootstrapFieldsWithAddons | BootstrapFieldsWithConfig;
+/**
+ * Feature kind discriminant for the Bootstrap addons feature. Matches core's
+ * `'addons'` kind so providers flow through the standard addon-kind pipeline
+ * in `provideDynamicForm`.
+ */
+type BootstrapAddonsFeature = {
+    ɵkind: 'addons';
+    ɵproviders: Provider[];
+};
+/**
+ * Register Bootstrap-shipped addon kinds (`bs-icon`, `bs-button`) standalone.
+ *
+ * **Most users don't need this** — `withBootstrapFields()` auto-includes
+ * these kinds. Call `withBootstrapAddons()` directly only when you want
+ * Bootstrap addon kinds without the Bootstrap field types (e.g., a custom
+ * field set that wants to render `bs-icon` prefixes), or when you're
+ * stitching addons through a different DI scope.
+ *
+ * @example
+ * ```typescript
+ * // Custom field types + Bootstrap addon kinds.
+ * provideDynamicForm(
+ *   ...myCustomFields(),
+ *   withBootstrapAddons(),
+ * );
+ * ```
+ *
+ * Adapter authors who need to override a kind with a customised renderer
+ * should call `withCustomAddon(...)` directly instead.
+ */
+declare function withBootstrapAddons(): BootstrapAddonsFeature;
+
+/**
+ * Renderer for the `bs-icon` addon kind.
+ *
+ * Outputs `<i class="bi bi-{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 BsIconAddonComponent {
+    readonly addon: _angular_core.InputSignal<BsIconAddon>;
+    /** Accepted for contract uniformity — `NgComponentOutlet` setInput is strict; every kind must declare it. */
+    readonly fieldInputs: _angular_core.InputSignal<WrapperFieldInputs | undefined>;
+    protected readonly iconClass: _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<BsIconAddonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<BsIconAddonComponent, "df-bs-icon-addon", never, { "addon": { "alias": "addon"; "required": true; "isSignal": true; }; "fieldInputs": { "alias": "fieldInputs"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Renderer for the `bs-button` addon kind.
+ *
+ * Renders a Bootstrap `btn-outline-{severity}` button. Click dispatch
+ * (preset / actionRef / action precedence, multi-set warning, `disabled` /
+ * `loading` resolution) lives on `NgForgeAddonAction`; this component
+ * focuses on the visual layer.
+ */
+declare class BsButtonAddonComponent {
+    protected readonly action: _ng_forge_dynamic_forms_integration.TypedNgForgeAddonAction<BsButtonAddon>;
+    /** Re-exposed for template binding — same signal stored on the directive. */
+    protected readonly addon: _angular_core.Signal<BsButtonAddon>;
+    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 iconClass: _angular_core.Signal<string>;
+    protected readonly buttonClass: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<BsButtonAddonComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<BsButtonAddonComponent, "df-bs-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 `bs-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 BS_INPUT_TYPE_OVERRIDE: InjectionToken<WritableSignal<string | undefined>>;
 
-export { BOOTSTRAP_CONFIG, BOOTSTRAP_FIELD_TYPES, BsButtonFieldComponent, BsCheckboxFieldComponent, BsDatepickerFieldComponent, BsField, BsInputFieldComponent, BsMultiCheckboxFieldComponent, BsRadioFieldComponent, BsSelectFieldComponent, BsSliderFieldComponent, BsTextareaFieldComponent, BsToggleFieldComponent, withBootstrapFields };
-export type { AddArrayItemButtonField, BootstrapConfig, BsButtonField, BsButtonProps, BsCheckboxComponent, BsCheckboxField, BsCheckboxProps, BsDatepickerComponent, BsDatepickerField, BsDatepickerProps, BsFieldType, BsFormConfig, BsFormProps, BsInputComponent, BsInputField, BsInputProps, BsMultiCheckboxComponent, BsMultiCheckboxField, BsMultiCheckboxProps, BsNextButtonField, BsPreviousButtonField, BsRadioComponent, BsRadioField, BsRadioProps, BsSelectComponent, BsSelectField, BsSelectProps, BsSliderComponent, BsSliderField, BsSliderProps, BsSubmitButtonField, BsTextareaComponent, BsTextareaField, BsTextareaProps, BsToggleComponent, BsToggleField, BsToggleProps, InsertArrayItemButtonField, PopArrayItemButtonField, PrependArrayItemButtonField, RemoveArrayItemButtonField, ShiftArrayItemButtonField };
+export { BOOTSTRAP_CONFIG, BOOTSTRAP_FIELD_TYPES, BS_INPUT_TYPE_OVERRIDE, BsButtonAddonComponent, BsButtonFieldComponent, BsCheckboxFieldComponent, BsDatepickerFieldComponent, BsField, BsIconAddonComponent, BsInputFieldComponent, BsMultiCheckboxFieldComponent, BsRadioFieldComponent, BsSelectFieldComponent, BsSliderFieldComponent, BsTextareaFieldComponent, BsToggleFieldComponent, withBootstrapAddons, withBootstrapFields };
+export type { AddArrayItemButtonField, BootstrapConfig, BsAddon, BsAddonExtensions, BsButtonAddon, BsButtonField, BsButtonProps, BsCheckboxComponent, BsCheckboxField, BsCheckboxProps, BsDatepickerComponent, BsDatepickerField, BsDatepickerProps, BsFieldType, BsFormConfig, BsFormProps, BsIconAddon, BsInputAddon, BsInputComponent, BsInputField, BsInputProps, BsMultiCheckboxComponent, BsMultiCheckboxField, BsMultiCheckboxProps, BsNextButtonField, BsPreviousButtonField, BsRadioComponent, BsRadioField, BsRadioProps, BsSelectComponent, BsSelectField, BsSelectProps, BsSliderComponent, BsSliderField, BsSliderProps, BsSubmitButtonField, BsTextareaComponent, BsTextareaField, BsTextareaProps, BsToggleComponent, BsToggleField, BsToggleProps, InsertArrayItemButtonField, PopArrayItemButtonField, PrependArrayItemButtonField, RemoveArrayItemButtonField, ShiftArrayItemButtonField };