ng-hub-ui-forms 22.1.2 → 22.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-hub-ui-forms",
-  "version": "22.1.2",
+  "version": "22.3.0",
   "license": "MIT",
   "description": "Accessible, signal-based form fields for Angular (input, textarea, slider, select, datepicker) with automatic error display for controls, FormGroups and FormArrays. Reactive Forms today, Signal Forms ready. Part of the ng-hub-ui family.",
   "author": "Carlos Morcillo <carlos.morcillo@me.com> (https://www.carlosmorcillo.com)",

package/src/lib/styles/_tokens.scss

@@ -70,6 +70,18 @@
 	--hub-input-group-addon-color: var(--hub-sys-text-muted, #6c757d);
 	--hub-input-group-addon-border-color: var(--hub-input-border-color);
 
+	// Input · affix (projected leading/trailing content, e.g. a <hub-icon>)
+	--hub-input-icon-color: var(--hub-sys-text-muted, #6c757d);
+	--hub-input-icon-size: var(--hub-ref-font-size-base, 1rem);
+	--hub-input-affix-inset: var(--hub-input-padding-x);
+	--hub-input-affix-gap: var(--hub-ref-space-2, 0.5rem);
+
+	// Input · clear button ([clearable]) — glyph is a swappable mask
+	--hub-input-clear-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='black' d='M4.646 4.646a.5.5 0 0 1 .708 0L8 7.293l2.646-2.647a.5.5 0 0 1 .708.708L8.707 8l2.647 2.646a.5.5 0 0 1-.708.708L8 8.707l-2.646 2.647a.5.5 0 0 1-.708-.708L7.293 8 4.646 5.354a.5.5 0 0 1 0-.708'/%3E%3C/svg%3E");
+	--hub-input-clear-size: var(--hub-ref-font-size-base, 1rem);
+	--hub-input-clear-color: var(--hub-sys-text-muted, #6c757d);
+	--hub-input-clear-hover-color: var(--hub-sys-color-danger, #dc3545);
+
 	// Input · counter format (−/+)
 	--hub-input-counter-button-bg: var(--hub-sys-surface-elevated, #f8f9fa);
 	--hub-input-counter-button-color: var(--hub-sys-text-primary, #212529);

package/types/ng-hub-ui-forms.d.ts

@@ -1,5 +1,5 @@
 import * as _angular_core from '@angular/core';
-import { OnInit, AfterContentInit, OnDestroy, TemplateRef, ElementRef, InjectionToken, EnvironmentProviders, PipeTransform, NgZone } from '@angular/core';
+import { OnInit, AfterContentInit, OnDestroy, TemplateRef, ElementRef, InjectionToken, EnvironmentProviders, PipeTransform, NgZone, ViewContainerRef } from '@angular/core';
 import { NgControl, ControlContainer, ControlValueAccessor, ValidationErrors, AbstractControl, ValidatorFn } from '@angular/forms';
 import { Subject, OperatorFunction } from 'rxjs';
 import * as ng_hub_ui_forms from 'ng-hub-ui-forms';
@@ -383,6 +383,44 @@ declare enum HubInputFormats {
     File = "file"
 }
 
+/**
+ * Projects content into the **inline-start** affix area of a `<hub-input>` (left in
+ * LTR, right in RTL). Use it for a leading icon — a `<hub-icon>`, currency symbol,
+ * inline `<svg>` or even a small button.
+ *
+ * The input automatically reserves inline padding so its text never overlaps the
+ * affix, and themes a projected `<hub-icon>` with its `--hub-input-icon-*` tokens.
+ *
+ * ```html
+ * <hub-input placeholder="Search…">
+ *   <hub-icon hubInputPrefix name="fa:solid:magnifying-glass" />
+ * </hub-input>
+ * ```
+ */
+declare class HubInputPrefixDirective {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubInputPrefixDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<HubInputPrefixDirective, "[hubInputPrefix]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Projects content into the **inline-end** affix area of a `<hub-input>` (right in
+ * LTR, left in RTL). Use it for a trailing icon or a unit label. For a clear
+ * button, prefer the built-in `[clearable]` input instead of projecting one.
+ *
+ * The input automatically reserves inline padding so its text never overlaps the
+ * affix, and themes a projected `<hub-icon>` with its `--hub-input-icon-*` tokens.
+ *
+ * ```html
+ * <hub-input>
+ *   <hub-icon hubInputSuffix name="fa:solid:circle-info" />
+ * </hub-input>
+ * ```
+ */
+declare class HubInputSuffixDirective {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubInputSuffixDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<HubInputSuffixDirective, "[hubInputSuffix]", never, {}, {}, never, never, true, never>;
+}
+
 /** Value held by a `<hub-input>` across its supported formats. */
 type HubInputValue = number | string | boolean | File | FileList | null;
 /**
@@ -437,6 +475,23 @@ declare class HubInputComponent extends HubFieldControl {
     readonly prepend: _angular_core.InputSignal<string | string[]>;
     /** Text shown after the control as an input-group addon (text-like formats). */
     readonly append: _angular_core.InputSignal<string | string[]>;
+    /** Projected inline-start affix (`[hubInputPrefix]`) — e.g. a `<hub-icon>`, when present. */
+    protected readonly prefixDir: _angular_core.Signal<HubInputPrefixDirective | undefined>;
+    /** Projected inline-end affix (`[hubInputSuffix]`) — e.g. a `<hub-icon>`, when present. */
+    protected readonly suffixDir: _angular_core.Signal<HubInputSuffixDirective | undefined>;
+    /**
+     * When true, a clear (✕) button is rendered inside the field once it holds a
+     * value; activating it resets the control. The glyph comes from the
+     * `--hub-input-clear-icon` CSS token, so it can be restyled without touching
+     * the template.
+     */
+    readonly clearable: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether the internal clear button should be shown right now. */
+    protected readonly showClear: _angular_core.Signal<boolean>;
+    /** Whether an inline-start affix (projected prefix) is present. */
+    protected readonly hasPrefix: _angular_core.Signal<boolean>;
+    /** Whether an inline-end affix (projected suffix or the clear button) is present. */
+    protected readonly hasSuffix: _angular_core.Signal<boolean>;
     /** Extra CSS classes applied to the host element. */
     readonly classlist: _angular_core.InputSignal<string>;
     /**
@@ -455,6 +510,16 @@ declare class HubInputComponent extends HubFieldControl {
     readonly valueChange: _angular_core.OutputEmitterRef<HubInputValue>;
     /** Emits the current value when Enter is pressed. */
     readonly enter: _angular_core.OutputEmitterRef<HubInputValue>;
+    /** Debounce in milliseconds before {@link search} fires. `0` emits on every keystroke. */
+    readonly debounceTime: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * Debounced typeahead event: emits the current term (stringified) `debounceTime`
+     * ms after the user stops typing. Wire it to drive search / autocomplete without
+     * rolling your own debounce. Text-like formats only; `valueChange` stays synchronous.
+     */
+    readonly search: _angular_core.OutputEmitterRef<string>;
+    /** Clears any pending debounce timer when the component is destroyed. */
+    private readonly _searchCleanup;
     /** Accepted file types (file format), e.g. `image/*,.pdf`. */
     readonly accept: _angular_core.InputSignal<string>;
     /** Whether multiple files can be selected (file format). */
@@ -465,6 +530,8 @@ declare class HubInputComponent extends HubFieldControl {
     protected readonly fileInput: _angular_core.Signal<ElementRef<HTMLInputElement> | undefined>;
     /** Whether the current format renders a checkable control (checkbox / switch). */
     protected readonly isCheckable: _angular_core.Signal<boolean>;
+    /** Whether the current format renders a typeable text-like control (drives the `search` event). */
+    protected readonly isTextLike: _angular_core.Signal<boolean>;
     /** Display label for the selected file(s). */
     protected readonly fileLabel: _angular_core.Signal<string>;
     /** Normalized list of prepend addons. */
@@ -497,10 +564,12 @@ declare class HubInputComponent extends HubFieldControl {
      * @param event - The native `change` event of the file input.
      */
     protected setFileValue(event: Event): void;
+    /** Resets a text-like control to empty via the internal clear button. */
+    protected clear(): void;
     /** Clears the selected file(s). */
     protected clearFile(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubInputComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HubInputComponent, "hub-input", never, { "type": { "alias": "type"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "labelType": { "alias": "labelType"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "formText": { "alias": "formText"; "required": false; "isSignal": true; }; "formTextType": { "alias": "formTextType"; "required": false; "isSignal": true; }; "prepend": { "alias": "prepend"; "required": false; "isSignal": true; }; "append": { "alias": "append"; "required": false; "isSignal": true; }; "classlist": { "alias": "classlist"; "required": false; "isSignal": true; }; "mask": { "alias": "mask"; "required": false; "isSignal": true; }; "unmaskValue": { "alias": "unmaskValue"; "required": false; "isSignal": true; }; "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "buttonLabel": { "alias": "buttonLabel"; "required": false; "isSignal": true; }; }, { "labelType": "labelTypeChange"; "placeholder": "placeholderChange"; "min": "minChange"; "max": "maxChange"; "valueChange": "valueChange"; "enter": "enter"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HubInputComponent, "hub-input", never, { "type": { "alias": "type"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "labelType": { "alias": "labelType"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "formText": { "alias": "formText"; "required": false; "isSignal": true; }; "formTextType": { "alias": "formTextType"; "required": false; "isSignal": true; }; "prepend": { "alias": "prepend"; "required": false; "isSignal": true; }; "append": { "alias": "append"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "classlist": { "alias": "classlist"; "required": false; "isSignal": true; }; "mask": { "alias": "mask"; "required": false; "isSignal": true; }; "unmaskValue": { "alias": "unmaskValue"; "required": false; "isSignal": true; }; "debounceTime": { "alias": "debounceTime"; "required": false; "isSignal": true; }; "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "buttonLabel": { "alias": "buttonLabel"; "required": false; "isSignal": true; }; }, { "labelType": "labelTypeChange"; "placeholder": "placeholderChange"; "min": "minChange"; "max": "maxChange"; "valueChange": "valueChange"; "enter": "enter"; "search": "search"; }, ["prefixDir", "suffixDir"], ["[hubInputPrefix]", "[hubInputSuffix]"], true, never>;
 }
 
 /** Character set accepted by the OTP field. */
@@ -1478,5 +1547,52 @@ declare function isMaskActive(mask: string | null | undefined): boolean;
  */
 declare function applyMask(value: string | null | undefined, mask: string): HubMaskResult;
 
-export { FormTextTypes, HUB_FORMS_CONFIG, HubAutoresizeDirective, HubDatepickerComponent, HubFieldControl, HubFieldsetComponent, HubFormComponent, HubFormControl, HubFormTextDirective, HubGroupControl, HubInputComponent, HubInputFormats, HubInvertColorPipe, HubJoinButLastPipe, HubLabelTypes, HubLegendComponent, HubLegendDirective, HubMapPipe, HubOtpInputComponent, HubSafeUrlPipe, HubSelectComponent, HubSelectFormats, HubSliderComponent, HubSnakeUpperPipe, HubTextareaComponent, HubUcfirstPipe, HubValidationErrorDirective, NgClearButtonTemplateDirective, NgFooterTemplateDirective, NgHeaderTemplateDirective, NgLabelTemplateDirective, NgLoadingSpinnerTemplateDirective, NgLoadingTextTemplateDirective, NgMultiLabelTemplateDirective, NgNotFoundTemplateDirective, NgOptgroupTemplateDirective, NgOptionComponent, NgOptionTemplateDirective, NgSelectConfig, NgTagTemplateDirective, NgTypeToSearchTemplateDirective, applyMask, areEqual, camelToSnakeUpper, controlHasMinOrMaxValidator, defaultHubDatepickerConfig, defaultHubDatepickerLabels, defaultHubFormsConfig, defaultInvalidFeedback, get, getActiveElement, getMinOrMaxValueFromValidator, hubAreEqual, isDefined, isMaskActive, isString, joinButLast, provideHubForms, runInZone, uuid };
-export type { FormTextType, HubDateRange, HubDateValue, HubDatepickerConfig, HubDatepickerLabels, HubDatepickerMode, HubFormsConfig, HubGroupErrorTrigger, HubInputFormat, HubLabelType, HubMaskResult, HubOtpMode, HubSelectFormat, HubSliderValue };
+/** A `{ value, label }` option for select-kind controls. */
+interface HubFormControlOption {
+    value: unknown;
+    label: string;
+}
+/**
+ * Framework-neutral description of a primitive control to render dynamically.
+ *
+ * The shape mirrors (structurally) the contract other ng-hub-ui libraries expose
+ * for optional control hosting (e.g. `ng-hub-ui-paginable`'s table), so this
+ * adapter can be wired into them without either package importing the other.
+ */
+interface HubFormControlConfig {
+    kind: 'input' | 'select';
+    value: unknown;
+    type?: string;
+    placeholder?: string;
+    ariaLabel?: string;
+    cssClass?: string;
+    options?: ReadonlyArray<HubFormControlOption>;
+    onValueChange: (value: unknown) => void;
+}
+/** Live handle to a control created by {@link hubFormControlAdapter}. */
+interface HubFormControlHandle {
+    /** Pushes a new value into the control (external updates). */
+    setValue(value: unknown): void;
+    /** Destroys the control and releases its resources. */
+    destroy(): void;
+}
+/** Adapter that renders primitive controls with the ng-hub-ui-forms components. */
+interface HubFormControlAdapter {
+    create(container: ViewContainerRef, config: HubFormControlConfig): HubFormControlHandle;
+}
+/**
+ * Ready-made {@link HubFormControlAdapter} backed by `HubInputComponent` /
+ * `HubSelectComponent`.
+ *
+ * Wire it into any ng-hub-ui primitive that exposes an optional form-controls
+ * token, e.g. `provideHubPaginableFormControls(hubFormControlAdapter)`. The host
+ * library keeps **zero hard dependency** on `ng-hub-ui-forms`; only an app that
+ * opts in pulls these components.
+ *
+ * Requires `provideHubForms()` (or the default config) to be available in the
+ * environment so the field components can resolve their configuration.
+ */
+declare const hubFormControlAdapter: HubFormControlAdapter;
+
+export { FormTextTypes, HUB_FORMS_CONFIG, HubAutoresizeDirective, HubDatepickerComponent, HubFieldControl, HubFieldsetComponent, HubFormComponent, HubFormControl, HubFormTextDirective, HubGroupControl, HubInputComponent, HubInputFormats, HubInputPrefixDirective, HubInputSuffixDirective, HubInvertColorPipe, HubJoinButLastPipe, HubLabelTypes, HubLegendComponent, HubLegendDirective, HubMapPipe, HubOtpInputComponent, HubSafeUrlPipe, HubSelectComponent, HubSelectFormats, HubSliderComponent, HubSnakeUpperPipe, HubTextareaComponent, HubUcfirstPipe, HubValidationErrorDirective, NgClearButtonTemplateDirective, NgFooterTemplateDirective, NgHeaderTemplateDirective, NgLabelTemplateDirective, NgLoadingSpinnerTemplateDirective, NgLoadingTextTemplateDirective, NgMultiLabelTemplateDirective, NgNotFoundTemplateDirective, NgOptgroupTemplateDirective, NgOptionComponent, NgOptionTemplateDirective, NgSelectConfig, NgTagTemplateDirective, NgTypeToSearchTemplateDirective, applyMask, areEqual, camelToSnakeUpper, controlHasMinOrMaxValidator, defaultHubDatepickerConfig, defaultHubDatepickerLabels, defaultHubFormsConfig, defaultInvalidFeedback, get, getActiveElement, getMinOrMaxValueFromValidator, hubAreEqual, hubFormControlAdapter, isDefined, isMaskActive, isString, joinButLast, provideHubForms, runInZone, uuid };
+export type { FormTextType, HubDateRange, HubDateValue, HubDatepickerConfig, HubDatepickerLabels, HubDatepickerMode, HubFormControlAdapter, HubFormControlConfig, HubFormControlHandle, HubFormControlOption, HubFormsConfig, HubGroupErrorTrigger, HubInputFormat, HubLabelType, HubMaskResult, HubOtpMode, HubSelectFormat, HubSliderValue };