@wildmason/aegis 1.5.4 → 1.5.5

package/dist/types/wildmason-aegis.d.ts

@@ -2,6 +2,7 @@ import * as _angular_core from '@angular/core';
 import { ElementRef, AfterViewInit, TemplateRef, OnDestroy } from '@angular/core';
 import { ConnectedPosition } from '@angular/cdk/overlay';
 import { ControlValueAccessor } from '@angular/forms';
+import * as rxjs from 'rxjs';
 
 /**
  * WmModal — Lightweight modal backdrop with Escape key and click-outside dismissal.
@@ -425,6 +426,210 @@ declare class PageHeader {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<PageHeader, "wm-page-header", never, { "flavourText": { "alias": "flavourText"; "required": true; "isSignal": true; }; "title": { "alias": "title"; "required": true; "isSignal": true; }; "subtitle": { "alias": "subtitle"; "required": false; "isSignal": true; }; "badgeLabel": { "alias": "badgeLabel"; "required": false; "isSignal": true; }; }, {}, never, ["[icon]", "[back]", "*"], true, never>;
 }
 
+interface ComboboxOption {
+    /** Emitted on selection. Can be string, number, or object. */
+    value: unknown;
+    /** Displayed text in the trigger and dropdown. */
+    label: string;
+    /** Optional. Greys out and prevents selection. */
+    disabled?: boolean;
+}
+
+/**
+ * Segment of an option label, split by filter-query matches.
+ * `match: true` means this segment matched the query and should be bolded.
+ */
+interface LabelSegment {
+    text: string;
+    match: boolean;
+}
+/**
+ * Internal sub-component that renders the virtual-scrolled option list
+ * inside the WmCombobox's CDK overlay. NOT exported from Aegis.
+ */
+declare class ComboboxPanel {
+    /** Filtered options to display. */
+    readonly options: _angular_core.InputSignal<ComboboxOption[]>;
+    /** Index of the keyboard-highlighted option (-1 = none). */
+    readonly highlightIndex: _angular_core.InputSignal<number>;
+    /** Values currently selected (for checkmark display). */
+    readonly selectedValues: _angular_core.InputSignal<Set<unknown>>;
+    /** Whether the parent is multi-select. */
+    readonly multiple: _angular_core.InputSignal<boolean>;
+    /** Pixel height per row. */
+    readonly itemHeight: _angular_core.InputSignal<number>;
+    /** Max panel height in pixels. */
+    readonly maxHeight: _angular_core.InputSignal<number>;
+    /** Current filter text — used for match highlighting in labels. */
+    readonly filterQuery: _angular_core.InputSignal<string>;
+    /** Show spinner when async filter is pending. */
+    readonly loading: _angular_core.InputSignal<boolean>;
+    /** Shown in empty state when freeform input is enabled. */
+    readonly freeformHint: _angular_core.InputSignal<string>;
+    /** Emitted on mousedown (not click) to prevent focus steal. */
+    readonly optionClicked: _angular_core.OutputEmitterRef<{
+        option: ComboboxOption;
+        index: number;
+    }>;
+    private viewport?;
+    /** Unique instance ID for generating DOM IDs. */
+    private readonly instanceId;
+    /** The DOM ID of the listbox element — used by parent for aria-controls. */
+    readonly listboxId: string;
+    /** Computed viewport height: min of (options * itemHeight) and maxHeight. */
+    protected readonly viewportHeight: _angular_core.Signal<number>;
+    /** Whether to show the empty state. */
+    protected readonly showEmpty: _angular_core.Signal<boolean>;
+    /** Text for the empty state. */
+    protected readonly emptyText: _angular_core.Signal<string>;
+    /**
+     * Precomputed label segments for each option, split by the current filter query.
+     * Recomputes whenever options or filterQuery changes.
+     */
+    protected readonly segmentedLabels: _angular_core.Signal<LabelSegment[][]>;
+    /** Map from option value to a stable key for DOM IDs. */
+    private optionKeyMap;
+    private nextObjectIndex;
+    constructor();
+    /** Returns a stable DOM ID for the option at the given index. */
+    optionIdAt(index: number): string;
+    /** Handle mousedown on an option — emits event and prevents default. */
+    protected onOptionMousedown(event: MouseEvent, option: ComboboxOption, index: number): void;
+    /** Check whether a value is currently selected. */
+    protected isSelected(value: unknown): boolean;
+    /** Get label segments for the option at the given virtual-scroll index. */
+    protected segmentsAt(index: number): LabelSegment[];
+    /**
+     * Returns a stable string key for an option value.
+     * Strings/numbers use the value directly. Objects use a monotonic index.
+     */
+    private keyFor;
+    /**
+     * Split a label into segments where the query matches (case-insensitive).
+     * Returns an array of { text, match } segments.
+     */
+    private splitLabel;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ComboboxPanel, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ComboboxPanel, "wm-combobox-panel", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "highlightIndex": { "alias": "highlightIndex"; "required": false; "isSignal": true; }; "selectedValues": { "alias": "selectedValues"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "itemHeight": { "alias": "itemHeight"; "required": false; "isSignal": true; }; "maxHeight": { "alias": "maxHeight"; "required": false; "isSignal": true; }; "filterQuery": { "alias": "filterQuery"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "freeformHint": { "alias": "freeformHint"; "required": false; "isSignal": true; }; }, { "optionClicked": "optionClicked"; }, never, never, true, never>;
+}
+
+/**
+ * WmCombobox — Accessible combobox with filtering, single/multi-select,
+ * freeform entry, chips, and virtual-scrolled panel.
+ *
+ * Built on Angular CDK Overlay and the WAI-ARIA APG combobox pattern.
+ * DOM focus ALWAYS stays on the input; assistive tech focus moves via
+ * `aria-activedescendant`.
+ *
+ * Implements ControlValueAccessor for both template-driven and reactive forms.
+ *
+ * Usage:
+ *   <!-- Single-select -->
+ *   <wm-combobox [options]="opts" [(value)]="selected" />
+ *
+ *   <!-- Multi-select with chips -->
+ *   <wm-combobox [options]="opts" [(values)]="selectedIds" [multiple]="true" />
+ *
+ *   <!-- Async filter -->
+ *   <wm-combobox [options]="opts" [filterFn]="searchApi" />
+ *
+ *   <!-- Reactive form -->
+ *   <wm-combobox formControlName="tag" [options]="tags" />
+ */
+declare class WmCombobox implements ControlValueAccessor, OnDestroy {
+    /** Full option list (before filtering). */
+    readonly options: _angular_core.InputSignal<ComboboxOption[]>;
+    /** Selected value (single-select). Two-way bindable. */
+    readonly value: _angular_core.ModelSignal<unknown>;
+    /** Selected values (multi-select). Two-way bindable. */
+    readonly values: _angular_core.ModelSignal<unknown[]>;
+    /** Enable multi-select mode with chips. */
+    readonly multiple: _angular_core.InputSignal<boolean>;
+    /** Allow typed text to be accepted as a freeform value. */
+    readonly allowFreeform: _angular_core.InputSignal<boolean>;
+    /** Placeholder text for the input. */
+    readonly placeholder: _angular_core.InputSignal<string>;
+    /** Disable the combobox. */
+    readonly disabled: _angular_core.InputSignal<boolean>;
+    /** Custom async filter function. Overrides default substring matching. */
+    readonly filterFn: _angular_core.InputSignal<(query: string) => rxjs.Observable<ComboboxOption[]>>;
+    /** Pixel height of each option row. */
+    readonly itemHeight: _angular_core.InputSignal<number>;
+    /** Max panel height in pixels. */
+    readonly maxPanelHeight: _angular_core.InputSignal<number>;
+    /** Emitted when the input text changes. */
+    readonly query: _angular_core.OutputEmitterRef<string>;
+    /** Emitted when the panel opens. */
+    readonly opened: _angular_core.OutputEmitterRef<void>;
+    /** Emitted when the panel closes. */
+    readonly closed: _angular_core.OutputEmitterRef<void>;
+    protected readonly inputRef: _angular_core.Signal<ElementRef<HTMLInputElement>>;
+    protected readonly panel: _angular_core.Signal<ComboboxPanel>;
+    protected readonly isOpen: _angular_core.WritableSignal<boolean>;
+    protected readonly inputText: _angular_core.WritableSignal<string>;
+    protected readonly highlightIndex: _angular_core.WritableSignal<number>;
+    protected readonly asyncLoading: _angular_core.WritableSignal<boolean>;
+    protected readonly asyncResults: _angular_core.WritableSignal<ComboboxOption[]>;
+    /** Text the input had when the panel opened — restored on Escape. */
+    private savedText;
+    private readonly hostEl;
+    private onChangeFn;
+    protected onTouchedFn: () => void;
+    private readonly filterSubject;
+    private filterSub;
+    protected readonly liveText: _angular_core.WritableSignal<string>;
+    private liveTimer;
+    /** Set of currently selected values for the panel. */
+    protected readonly selectedValues: _angular_core.Signal<Set<unknown>>;
+    /** Filtered options shown in the panel. */
+    protected readonly filteredOptions: _angular_core.Signal<ComboboxOption[]>;
+    /** Chips for multi-select mode. */
+    protected readonly chips: _angular_core.Signal<{
+        value: unknown;
+        label: string;
+    }[]>;
+    /** The aria-activedescendant value. */
+    protected readonly activeDescendant: _angular_core.Signal<string>;
+    /** The listbox ID from the panel (for aria-controls). */
+    protected readonly panelListboxId: _angular_core.Signal<string>;
+    /** Freeform hint for empty state. */
+    protected readonly freeformHint: _angular_core.Signal<string>;
+    /** Overlay width tracks host element width. */
+    protected get overlayWidth(): number;
+    /** Overlay positions: below-first with above-fallback. */
+    protected readonly positions: ConnectedPosition[];
+    constructor();
+    ngOnDestroy(): void;
+    writeValue(value: unknown): void;
+    registerOnChange(fn: (v: unknown) => void): void;
+    registerOnTouched(fn: () => void): void;
+    protected open(highlightFirst?: boolean, highlightLast?: boolean): void;
+    protected close(restoreText?: boolean): void;
+    protected onInput(event: Event): void;
+    protected onBlur(): void;
+    protected onTriggerClick(): void;
+    protected onKeydown(event: KeyboardEvent): void;
+    protected onOptionClicked(event: {
+        option: ComboboxOption;
+        index: number;
+    }): void;
+    private selectOption;
+    protected removeChip(chipValue: unknown): void;
+    private removeChipByIndex;
+    private acceptFreeform;
+    private highlightFirst;
+    private highlightLast;
+    /**
+     * Find the next enabled option in the given direction.
+     * Returns -1 if wrapping past the end/start (clears highlight).
+     */
+    private nextEnabled;
+    /** Sync input text to the currently selected option label (single-select). */
+    private syncInputToSelection;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WmCombobox, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WmCombobox, "wm-combobox", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "values": { "alias": "values"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "allowFreeform": { "alias": "allowFreeform"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "filterFn": { "alias": "filterFn"; "required": false; "isSignal": true; }; "itemHeight": { "alias": "itemHeight"; "required": false; "isSignal": true; }; "maxPanelHeight": { "alias": "maxPanelHeight"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "values": "valuesChange"; "query": "query"; "opened": "opened"; "closed": "closed"; }, never, never, true, never>;
+}
+
 type ToastType = 'success' | 'error' | 'info' | 'progress';
 interface Toast {
     id: number;
@@ -541,5 +746,5 @@ declare class WmLicenseDialog {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WmLicenseDialog, "wm-license-dialog", never, { "visible": { "alias": "visible"; "required": true; "isSignal": true; }; }, { "dismiss": "dismiss"; }, never, never, true, never>;
 }
 
-export { Checkbox, GhostField, NumberInput, PageHeader, Toggle, WmAutoFocus, WmButton, WmDialog, WmLicenseDialog, WmLicenseNudge, WmLicenseService, WmModal, WmPopover, WmSelect, WmTab, WmTabs, WmToastContainer, WmToastService };
-export type { ButtonSize, ButtonVariant, DialogSize, LicenseStatus, SelectOption, Toast, ToastType };
+export { Checkbox, GhostField, NumberInput, PageHeader, Toggle, WmAutoFocus, WmButton, WmCombobox, WmDialog, WmLicenseDialog, WmLicenseNudge, WmLicenseService, WmModal, WmPopover, WmSelect, WmTab, WmTabs, WmToastContainer, WmToastService };
+export type { ButtonSize, ButtonVariant, ComboboxOption, DialogSize, LicenseStatus, SelectOption, Toast, ToastType };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildmason/aegis",
-  "version": "1.5.4",
+  "version": "1.5.5",
   "description": "Aegis design system — CSS tokens and Angular component library",
   "scripts": {
     "build": "ng-packagr -p ng-package.json",