ng-hub-ui-forms 22.40.0 → 22.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-hub-ui-forms",
-  "version": "22.40.0",
+  "version": "22.41.0",
   "license": "MIT",
   "description": "Accessible, signal-based form fields for Angular (input, textarea, slider, segmented, select, datepicker, file input with drag & drop and upload progress) 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 Fernández <carlos.morcillo@me.com> (https://www.carlosmorcillo.com)",

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

@@ -1805,6 +1805,22 @@ declare class HubSelectComponent extends HubFieldControl {
      * one sync away from disappearing. See {@link placeholder}.
      */
     protected readonly _ngSelectConfig: NgSelectConfig;
+    /**
+     * The engine behind the field, kept only so the list can be worked from outside.
+     *
+     * A select that something else opens — a grid cell that turns into an editor, a row that turns
+     * into a form — is created after the reader's click has already been spent, so there is no
+     * gesture left for it to answer. Without a way in, reaching the field takes one click and
+     * seeing the list takes another.
+     */
+    private readonly _engine;
+    /**
+     * Honours {@link autoOpen} once, after the first render.
+     *
+     * Not an effect: the intent is a one-off at birth, and an effect would re-open the list every
+     * time the flag or the items changed underneath the reader.
+     */
+    private readonly _openOnArrival;
     protected readonly _labelTypes: typeof HubLabelTypes;
     protected readonly _selectFormats: typeof HubSelectFormats;
     protected readonly _value: _angular_core.WritableSignal<any>;
@@ -1951,6 +1967,24 @@ declare class HubSelectComponent extends HubFieldControl {
     readonly loading: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Whether the control is read-only. */
     readonly readonly: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Opens the list as soon as the field appears.
+     *
+     * For a field that something else has already opened for the reader: a spreadsheet cell that
+     * becomes an editor, a row that becomes a form. The click that got them there has been spent by
+     * the time the field exists, so without this reaching the field costs one click and seeing the
+     * list costs another. A field with nothing to offer opens all the same and says so, which is
+     * what it would do had the reader opened it by hand.
+     */
+    readonly autoOpen: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * A search term the field starts with.
+     *
+     * For the same case as {@link autoOpen}, one keystroke earlier: the character that opened the
+     * field belongs in its search box, or the reader has to type it a second time. Applied once,
+     * on arrival, and only when the field is searchable.
+     */
+    readonly initialSearchTerm: _angular_core.InputSignal<string | null>;
     /**
      * Text shown when no items match. Left undefined so the engine falls back to the app's
      * `NgSelectConfig`, which is where a translated build sets it once for every select.
@@ -2105,8 +2139,25 @@ declare class HubSelectComponent extends HubFieldControl {
      * @param item - The item to toggle.
      */
     protected toggleItem(item: any): void;
+    /**
+     * Opens the list.
+     *
+     * Refused while the field is disabled, while it is already open, and while there is nothing to
+     * choose from, so calling it the moment the field appears is safe whatever state it is in.
+     */
+    open(): void;
+    /** Closes the list, keeping whatever was chosen. */
+    close(): void;
+    /** Puts the keyboard in the field without opening the list. */
+    focus(): void;
+    /**
+     * Narrows the list by a term, as typing into the search box would.
+     *
+     * @param term - What to search for; an empty string clears the search.
+     */
+    search(term: string): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubSelectComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HubSelectComponent, "hub-select", never, { "prepend": { "alias": "prepend"; "required": false; "isSignal": true; }; "append": { "alias": "append"; "required": false; "isSignal": true; }; "format": { "alias": "format"; "required": false; "isSignal": true; }; "vertical": { "alias": "vertical"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": false; "isSignal": true; }; "bindLabel": { "alias": "bindLabel"; "required": false; "isSignal": true; }; "bindValue": { "alias": "bindValue"; "required": false; "isSignal": true; }; "groupBy": { "alias": "groupBy"; "required": false; "isSignal": true; }; "searchFn": { "alias": "searchFn"; "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; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "searchable": { "alias": "searchable"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "closeOnSelect": { "alias": "closeOnSelect"; "required": false; "isSignal": true; }; "clearSearchOnAdd": { "alias": "clearSearchOnAdd"; "required": false; "isSignal": true; }; "fixedPlaceholder": { "alias": "fixedPlaceholder"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "notFoundText": { "alias": "notFoundText"; "required": false; "isSignal": true; }; "appendTo": { "alias": "appendTo"; "required": false; "isSignal": true; }; "addTag": { "alias": "addTag"; "required": false; "isSignal": true; }; "addTagText": { "alias": "addTagText"; "required": false; "isSignal": true; }; "minTermLength": { "alias": "minTermLength"; "required": false; "isSignal": true; }; "typeahead": { "alias": "typeahead"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; "classlist": { "alias": "classlist"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; "change": "change"; "onFocus": "onFocus"; "onBlur": "onBlur"; "onOpen": "onOpen"; "onClose": "onClose"; "onClear": "onClear"; "onSearch": "onSearch"; "onAdd": "onAdd"; "onRemove": "onRemove"; "scroll": "scroll"; "scrollToEnd": "scrollToEnd"; }, ["_hubOptionTpl", "_ngOptionTpl", "_hubOptgroupTpl", "_ngOptgroupTpl", "_hubLabelTpl", "_ngLabelTpl", "_hubMultiLabelTpl", "_ngMultiLabelTpl", "_hubHeaderTpl", "_ngHeaderTpl", "_hubFooterTpl", "_ngFooterTpl", "_hubNotFoundTpl", "_ngNotFoundTpl", "_hubTypeToSearchTpl", "_ngTypeToSearchTpl", "_hubLoadingTextTpl", "_ngLoadingTextTpl", "_hubLoadingSpinnerTpl", "_ngLoadingSpinnerTpl", "_hubTagTpl", "_ngTagTpl", "_hubClearButtonTpl", "_ngClearButtonTpl", "_legacySuffixTpl", "_prependTpl", "_genericAppendTpl"], ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HubSelectComponent, "hub-select", never, { "prepend": { "alias": "prepend"; "required": false; "isSignal": true; }; "append": { "alias": "append"; "required": false; "isSignal": true; }; "format": { "alias": "format"; "required": false; "isSignal": true; }; "vertical": { "alias": "vertical"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": false; "isSignal": true; }; "bindLabel": { "alias": "bindLabel"; "required": false; "isSignal": true; }; "bindValue": { "alias": "bindValue"; "required": false; "isSignal": true; }; "groupBy": { "alias": "groupBy"; "required": false; "isSignal": true; }; "searchFn": { "alias": "searchFn"; "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; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "searchable": { "alias": "searchable"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "closeOnSelect": { "alias": "closeOnSelect"; "required": false; "isSignal": true; }; "clearSearchOnAdd": { "alias": "clearSearchOnAdd"; "required": false; "isSignal": true; }; "fixedPlaceholder": { "alias": "fixedPlaceholder"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "autoOpen": { "alias": "autoOpen"; "required": false; "isSignal": true; }; "initialSearchTerm": { "alias": "initialSearchTerm"; "required": false; "isSignal": true; }; "notFoundText": { "alias": "notFoundText"; "required": false; "isSignal": true; }; "appendTo": { "alias": "appendTo"; "required": false; "isSignal": true; }; "addTag": { "alias": "addTag"; "required": false; "isSignal": true; }; "addTagText": { "alias": "addTagText"; "required": false; "isSignal": true; }; "minTermLength": { "alias": "minTermLength"; "required": false; "isSignal": true; }; "typeahead": { "alias": "typeahead"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; "classlist": { "alias": "classlist"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; "change": "change"; "onFocus": "onFocus"; "onBlur": "onBlur"; "onOpen": "onOpen"; "onClose": "onClose"; "onClear": "onClear"; "onSearch": "onSearch"; "onAdd": "onAdd"; "onRemove": "onRemove"; "scroll": "scroll"; "scrollToEnd": "scrollToEnd"; }, ["_hubOptionTpl", "_ngOptionTpl", "_hubOptgroupTpl", "_ngOptgroupTpl", "_hubLabelTpl", "_ngLabelTpl", "_hubMultiLabelTpl", "_ngMultiLabelTpl", "_hubHeaderTpl", "_ngHeaderTpl", "_hubFooterTpl", "_ngFooterTpl", "_hubNotFoundTpl", "_ngNotFoundTpl", "_hubTypeToSearchTpl", "_ngTypeToSearchTpl", "_hubLoadingTextTpl", "_ngLoadingTextTpl", "_hubLoadingSpinnerTpl", "_ngLoadingSpinnerTpl", "_hubTagTpl", "_ngTagTpl", "_hubClearButtonTpl", "_ngClearButtonTpl", "_legacySuffixTpl", "_prependTpl", "_genericAppendTpl"], ["*"], true, never>;
 }
 
 /** A calendar cell enriched with its selection / range / disabled / focus state. */
@@ -4004,6 +4055,25 @@ interface HubFormControlConfig {
     ariaLabel?: string;
     cssClass?: string;
     options?: ReadonlyArray<HubFormControlOption>;
+    /**
+     * Whether a select offers a search box. Off unless asked for.
+     *
+     * A control built into somebody else's chrome is usually a short list in a tight space — a
+     * table's rows-per-page, a filter — where a search box is noise. A cell of a spreadsheet is
+     * the other case, and a long list there is the whole reason for wiring an adapter at all.
+     */
+    searchable?: boolean;
+    /** Whether it offers to clear itself. On unless the host says otherwise, as the field does. */
+    clearable?: boolean;
+    /**
+     * Whether a select opens as it appears, and on what term.
+     *
+     * For a control that something else has already opened for the reader: a cell that becomes an
+     * editor, a row that becomes a form. Their gesture has been spent by the time the control
+     * exists, and the character they typed belongs in its search box.
+     */
+    autoOpen?: boolean;
+    searchTerm?: string;
     onValueChange: (value: unknown) => void;
 }
 /** Live handle to a control created by {@link hubFormControlAdapter}. */