ng-hub-ui-forms 22.2.0 → 22.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-hub-ui-forms",
-  "version": "22.2.0",
+  "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

@@ -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. */
@@ -1525,5 +1594,5 @@ interface HubFormControlAdapter {
  */
 declare const hubFormControlAdapter: HubFormControlAdapter;
 
-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, hubFormControlAdapter, isDefined, isMaskActive, isString, joinButLast, provideHubForms, runInZone, uuid };
+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 };