@akcelik/strct 1.19.0 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akcelik/strct",
-  "version": "1.19.0",
+  "version": "1.22.0",
   "description": "UIStruct — a standalone Angular component library with a tokenised, multi-palette theme system, built for datacenter / infrastructure management UIs.",
   "author": "Serkan Akcelik <serkan.akcelik@gmail.com>",
   "license": "MIT",

package/types/akcelik-strct.d.ts

@@ -2312,47 +2312,202 @@ declare class StrctInputMask implements ControlValueAccessor {
 interface StrctOption {
     value: unknown;
     label: string;
+    /** Grayed out and skipped by keyboard navigation. */
+    disabled?: boolean;
+    /** Options sharing a group label render under one header (combobox). */
+    group?: string;
+    /** Leading icon in the option row (and on the chip in multiple mode). */
+    icon?: StrctIconName;
+    /** Secondary line under the label in the option row (combobox). */
+    description?: string;
+}
+/** A render row of the option list: a group header or an option. */
+interface CbxRow {
+    key: string;
+    header?: string;
+    opt?: StrctOption;
+    /** Flat option index (headers carry none) — drives ids and highlight. */
+    index?: number;
 }
 /**
- * Filterable single-select (autocomplete). CVA-compatible, fully keyboard
- * driven (↑/↓ to move, Enter to pick, Esc to close).
+ * Filterable select (autocomplete). CVA-compatible, fully keyboard driven
+ * (↑/↓ move, Home/End jump, Enter picks, Esc closes) with the shared select
+ * ergonomics: an aligned ✓ lead slot marks the current choice, the typed
+ * match is emphasised in each label, and disabled options gray out and are
+ * skipped.
+ *
  *   <strct-combobox [options]="opts" [(ngModel)]="selected" placeholder="Pick…" />
+ *
+ * Variants: `clearable` adds an × that resets the selection; `multiple`
+ * switches the value to an array and renders the picks as removable chips —
+ * the list stays open while picking and Backspace on an empty query removes
+ * the last chip. Options may carry `group` labels (rendered as headers),
+ * `disabled`, a leading `icon` and a secondary `description` line.
+ * `allowCustomValue` appends a "Use \"…\"" row while typing so the typed
+ * text itself can be committed as a free-form value.
  */
 declare class StrctCombobox implements ControlValueAccessor {
     private readonly host;
+    private readonly inputEl;
     protected readonly listId: string;
-    /** Available options. */
+    /** Available options (`disabled` grays out; `group` renders headers). */
     readonly options: _angular_core.InputSignal<StrctOption[]>;
     /** Placeholder text when empty. */
     readonly placeholder: _angular_core.InputSignal<string>;
     /** Show a skeleton placeholder while options are loading. */
     readonly loading: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Show an × that resets the selection. */
+    readonly clearable: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Multi-select: the value becomes an array and the picks render as
+     * removable chips; the list stays open while picking.
+     */
+    readonly multiple: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Text shown when the filter matches nothing (localizable). */
+    readonly emptyText: _angular_core.InputSignal<string>;
+    /** Accessible label of the × clear button (localizable). */
+    readonly clearLabel: _angular_core.InputSignal<string>;
+    /** Accessible label prefix of a chip's × button (localizable). */
+    readonly removeLabel: _angular_core.InputSignal<string>;
+    /**
+     * Allow committing the typed text itself: while the query has no exact
+     * label match, a "Use \"…\"" row pinned to the list end (Enter or click)
+     * commits the raw text as the value — appended to the array in `multiple`.
+     */
+    readonly allowCustomValue: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Verb prefix of the free-form row (localizable) — renders `Use "query"`. */
+    readonly customText: _angular_core.InputSignal<string>;
     readonly query: _angular_core.WritableSignal<string>;
     readonly value: _angular_core.WritableSignal<unknown>;
+    /** Selection in `multiple` mode. */
+    readonly values: _angular_core.WritableSignal<unknown[]>;
     readonly open: _angular_core.WritableSignal<boolean>;
     readonly activeIndex: _angular_core.WritableSignal<number>;
     readonly isDisabled: _angular_core.WritableSignal<boolean>;
     /** True while the user is typing a filter that hasn't been committed yet. */
     private readonly dirty;
     protected readonly filtered: _angular_core.Signal<StrctOption[]>;
+    /** Flat option list (no headers) — keyboard navigation and ids live here. */
+    protected readonly flat: _angular_core.Signal<StrctOption[]>;
+    /**
+     * The free-form query committable right now (allowCustomValue): a trimmed
+     * dirty query with no exact label match — and, in multiple mode, not
+     * already picked. Rendered as an extra row at index `flat().length`.
+     */
+    protected readonly customRow: _angular_core.Signal<string | null>;
+    /** Navigable row count: options plus the custom row when shown. */
+    protected readonly navCount: _angular_core.Signal<number>;
+    /** Render rows: group headers interleaved with their options. */
+    protected readonly rows: _angular_core.Signal<CbxRow[]>;
+    protected readonly hasSelection: _angular_core.Signal<boolean>;
     private onChange;
     protected onTouched: () => void;
+    protected isSelected(v: unknown): boolean;
+    protected optionOf(v: unknown): StrctOption | undefined;
+    protected labelOf(v: unknown): string;
+    /** The typed match emphasised inside a label (first occurrence). */
+    protected segments(label: string): {
+        pre: string;
+        match: string;
+        post: string;
+    };
+    protected focusInput(): void;
     openList(): void;
     onType(event: Event): void;
     onKeydown(event: KeyboardEvent): void;
     private move;
+    private firstEnabled;
+    private lastEnabled;
+    private scrollActiveIntoView;
     select(opt: StrctOption, event: Event): void;
     private commit;
+    /**
+     * Commit the typed text itself as a free-form value (allowCustomValue).
+     * Multiple mode appends it and keeps picking; single mode takes it and
+     * closes.
+     */
+    protected commitCustom(event?: Event): void;
+    protected removeValue(v: unknown, event?: Event): void;
+    protected clear(event: Event): void;
     protected onDocClick(event: MouseEvent): void;
     private close;
-    private indexOfValue;
+    /** Highlight starts on the selected option — or the first enabled one. */
+    private initialIndex;
     private syncQueryToValue;
     writeValue(value: unknown): void;
     registerOnChange(fn: (value: unknown) => void): void;
     registerOnTouched(fn: () => void): void;
     setDisabledState(isDisabled: boolean): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<StrctCombobox, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StrctCombobox, "strct-combobox", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StrctCombobox, "strct-combobox", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "emptyText": { "alias": "emptyText"; "required": false; "isSignal": true; }; "clearLabel": { "alias": "clearLabel"; "required": false; "isSignal": true; }; "removeLabel": { "alias": "removeLabel"; "required": false; "isSignal": true; }; "allowCustomValue": { "alias": "allowCustomValue"; "required": false; "isSignal": true; }; "customText": { "alias": "customText"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Select-only combobox (APG pattern): a real button trigger wearing the shared
+ * `.strct-control` look, opening a token-styled listbox — so the option list
+ * matches the theme instead of the OS popup a native `<select>` shows.
+ * CVA-compatible; options are non-filterable (reach for `strct-combobox` when
+ * the list needs typing to narrow).
+ *
+ *   <strct-field label="Region">
+ *     <strct-select [options]="regions" [(ngModel)]="region" placeholder="Pick a region" />
+ *   </strct-field>
+ *
+ * Keyboard follows the native select: ArrowDown/Up and Enter/Space open,
+ * arrows move (skipping disabled options), Home/End jump, typing jumps to the
+ * matching label (typeahead), Enter/Space commit, Escape/Tab close without
+ * committing. The selected option carries a leading ✓ and gets the highlight
+ * when reopening — the same select ergonomics as `strct-dropdown-item
+ * [selected]`.
+ */
+declare class StrctSelect implements ControlValueAccessor {
+    private readonly host;
+    protected readonly listId: string;
+    /** Available options (set `disabled: true` on an option to gray it out). */
+    readonly options: _angular_core.InputSignal<StrctOption[]>;
+    /** Muted text shown while no value is selected (localizable). */
+    readonly placeholder: _angular_core.InputSignal<string>;
+    /** Accessible name of the listbox (localizable). */
+    readonly listLabel: _angular_core.InputSignal<string>;
+    /** Text shown when `options` is empty (localizable). */
+    readonly emptyText: _angular_core.InputSignal<string>;
+    /** Static disable flag (forms also drive it via setDisabledState). */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly value: _angular_core.WritableSignal<unknown>;
+    readonly open: _angular_core.WritableSignal<boolean>;
+    readonly activeIndex: _angular_core.WritableSignal<number>;
+    readonly isDisabled: _angular_core.WritableSignal<boolean>;
+    protected readonly selectedOption: _angular_core.Signal<StrctOption | undefined>;
+    /** Typeahead buffer — clears half a second after the last keystroke. */
+    private typed;
+    private typedTimer;
+    private onChange;
+    private onTouched;
+    toggle(): void;
+    openList(): void;
+    close(): void;
+    protected onKeydown(event: KeyboardEvent): void;
+    /**
+     * Native-select typeahead: letters accumulate into a prefix that jumps to
+     * the matching label; repeating one letter cycles its matches instead.
+     */
+    private typeahead;
+    private move;
+    /** Jump to `index`, walking `dir` past disabled options. */
+    private moveTo;
+    protected pick(opt: StrctOption, event: Event): void;
+    private commit;
+    protected onBlur(): void;
+    /** Highlight starts on the selected option — or the first enabled one. */
+    private initialIndex;
+    private scrollActiveIntoView;
+    protected onDocClick(event: MouseEvent): void;
+    writeValue(value: unknown): void;
+    registerOnChange(fn: (value: unknown) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<StrctSelect, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StrctSelect, "strct-select", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "listLabel": { "alias": "listLabel"; "required": false; "isSignal": true; }; "emptyText": { "alias": "emptyText"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 interface DayCell {
@@ -4445,5 +4600,5 @@ declare class StrctReorderItem {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<StrctReorderItem, "[strctReorderItem]", never, {}, {}, never, never, true, never>;
 }
 
-export { STRCT_ICONS, STRCT_ICON_GROUPS, STRCT_ICON_NAMES, STRCT_MASKS, STRCT_PALETTES, STRCT_RAW_ICONS, STRCT_TIME_RANGE_PRESETS, STRCT_WIZARD_DEFAULTS, StrctAccordion, StrctAccordionPanel, StrctAlert, StrctAnnouncer, StrctAvatar, StrctBadge, StrctBreadcrumb, StrctBreadcrumbItem, StrctButton, StrctButtonGroup, StrctBytesPipe, StrctCard, StrctCardBlock, StrctCardFooter, StrctCardHeader, StrctCascadeHost, StrctCascadeNode, StrctCascadeSelect, StrctCellDef, StrctCellStatus, StrctChart, StrctCheckbox, StrctChips, StrctCode, StrctColorPicker, StrctCombobox, StrctCommandPalette, StrctContextMenu, StrctContextMenuTrigger, StrctCopy, StrctDatagrid, StrctDatagridActionBar, StrctDatepicker, StrctDesc, StrctDescriptionList, StrctDiff, StrctDivider, StrctDonut, StrctDrawer, StrctDrawerFooter, StrctDropdown, StrctDropdownDivider, StrctDropdownItem, StrctDropdownTrigger, StrctDurationPipe, StrctEmptyState, StrctField, StrctFile, StrctFilterBar, StrctFlow, StrctFooter, StrctGauge, StrctHeader, StrctHero, StrctHotkeysHelp, StrctHotkeysService, StrctIcon, StrctInput, StrctInputMask, StrctInputOtp, StrctKbd, StrctKnob, StrctLogViewer, StrctLogin, StrctMenuPanel, StrctMenuService, StrctMenubar, StrctMetricTile, StrctModal, StrctNav, StrctNavItem, StrctOverlay, StrctPageHeader, StrctPageHeaderActions, StrctPageHeaderCrumbs, StrctPagination, StrctPassword, StrctProgress, StrctRadio, StrctRadioGroup, StrctRail, StrctRange, StrctRatePipe, StrctRating, StrctReorder, StrctReorderItem, StrctRowDetailDef, StrctSearchbox, StrctSectionMenu, StrctSegmented, StrctShell, StrctShellService, StrctSiPipe, StrctSignpost, StrctSkeleton, StrctSparkline, StrctSpeedDial, StrctSpinner, StrctSplitButton, StrctSplitter, StrctStack, StrctStackItem, StrctStep, StrctSubmenu, StrctTab, StrctTable, StrctTabs, StrctTag, StrctThemeService, StrctThemeSwitcher, StrctTimeRangePicker, StrctTimeline, StrctTimelineItem, StrctToastOutlet, StrctToastService, StrctToggle, StrctTooltip, StrctTour, StrctTransfer, StrctTree, StrctTreeNode, StrctVerticalNav, StrctWatermark, StrctWizard, StrctWizardAside, parseAnsi, provideStrctWizardDefaults, registerStrctIcon, strctComputeDiff, strctFormatBytes, strctFormatDuration, strctFormatRate, strctFormatSi, strctValidationIcon, strctValidationTone };
+export { STRCT_ICONS, STRCT_ICON_GROUPS, STRCT_ICON_NAMES, STRCT_MASKS, STRCT_PALETTES, STRCT_RAW_ICONS, STRCT_TIME_RANGE_PRESETS, STRCT_WIZARD_DEFAULTS, StrctAccordion, StrctAccordionPanel, StrctAlert, StrctAnnouncer, StrctAvatar, StrctBadge, StrctBreadcrumb, StrctBreadcrumbItem, StrctButton, StrctButtonGroup, StrctBytesPipe, StrctCard, StrctCardBlock, StrctCardFooter, StrctCardHeader, StrctCascadeHost, StrctCascadeNode, StrctCascadeSelect, StrctCellDef, StrctCellStatus, StrctChart, StrctCheckbox, StrctChips, StrctCode, StrctColorPicker, StrctCombobox, StrctCommandPalette, StrctContextMenu, StrctContextMenuTrigger, StrctCopy, StrctDatagrid, StrctDatagridActionBar, StrctDatepicker, StrctDesc, StrctDescriptionList, StrctDiff, StrctDivider, StrctDonut, StrctDrawer, StrctDrawerFooter, StrctDropdown, StrctDropdownDivider, StrctDropdownItem, StrctDropdownTrigger, StrctDurationPipe, StrctEmptyState, StrctField, StrctFile, StrctFilterBar, StrctFlow, StrctFooter, StrctGauge, StrctHeader, StrctHero, StrctHotkeysHelp, StrctHotkeysService, StrctIcon, StrctInput, StrctInputMask, StrctInputOtp, StrctKbd, StrctKnob, StrctLogViewer, StrctLogin, StrctMenuPanel, StrctMenuService, StrctMenubar, StrctMetricTile, StrctModal, StrctNav, StrctNavItem, StrctOverlay, StrctPageHeader, StrctPageHeaderActions, StrctPageHeaderCrumbs, StrctPagination, StrctPassword, StrctProgress, StrctRadio, StrctRadioGroup, StrctRail, StrctRange, StrctRatePipe, StrctRating, StrctReorder, StrctReorderItem, StrctRowDetailDef, StrctSearchbox, StrctSectionMenu, StrctSegmented, StrctSelect, StrctShell, StrctShellService, StrctSiPipe, StrctSignpost, StrctSkeleton, StrctSparkline, StrctSpeedDial, StrctSpinner, StrctSplitButton, StrctSplitter, StrctStack, StrctStackItem, StrctStep, StrctSubmenu, StrctTab, StrctTable, StrctTabs, StrctTag, StrctThemeService, StrctThemeSwitcher, StrctTimeRangePicker, StrctTimeline, StrctTimelineItem, StrctToastOutlet, StrctToastService, StrctToggle, StrctTooltip, StrctTour, StrctTransfer, StrctTree, StrctTreeNode, StrctVerticalNav, StrctWatermark, StrctWizard, StrctWizardAside, parseAnsi, provideStrctWizardDefaults, registerStrctIcon, strctComputeDiff, strctFormatBytes, strctFormatDuration, strctFormatRate, strctFormatSi, strctValidationIcon, strctValidationTone };
 export type { StrctAlertType, StrctAvatarSize, StrctAvatarStatus, StrctBadgeStatus, StrctButtonSize, StrctButtonVariant, StrctCascadeOption, StrctCellContext, StrctChartAnnotation, StrctChartColor, StrctChartCurve, StrctChartSeries, StrctChartSlot, StrctChartStatus, StrctChartThreshold, StrctChartType, StrctColumn, StrctCommandItem, StrctDatagridColumn, StrctDatagridColumnState, StrctDatagridFilters, StrctDatagridLabels, StrctDatagridLazyState, StrctDescAlign, StrctDescItem, StrctDiffRow, StrctDonutSegment, StrctDrawerSide, StrctDrawerSize, StrctEmptyVariant, StrctFilterChip, StrctFlowDirection, StrctFlowNode, StrctFlowOrientation, StrctHotkey, StrctIconBadge, StrctIconName, StrctKnobStatus, StrctLogLine, StrctMenuItem, StrctMenuLink, StrctMenuOpenOptions, StrctMenuSection, StrctMenubarItem, StrctMetricStatus, StrctModalSize, StrctMode, StrctOption, StrctOverlayPlacement, StrctPalette, StrctPaletteInfo, StrctProgressStatus, StrctRailItem, StrctRailStatus, StrctReorderEvent, StrctRow, StrctRowId, StrctSegmentedOption, StrctSegmentedSize, StrctSignpostPosition, StrctSpeedDialDirection, StrctSpinnerSize, StrctStatus, StrctTagStatus, StrctThresholds, StrctTimeRange, StrctTimeRangePreset, StrctTimelineState, StrctToast, StrctToastOptions, StrctToastType, StrctTooltipPosition, StrctTourStep, StrctTransferItem, StrctTreeMenuEvent, StrctTreeNodeData, StrctTreeNodeMenuFn, StrctValidationState, StrctValidationStatus, StrctWizardDefaults };