@truenas/ui-components 0.2.6 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truenas/ui-components",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"

package/types/truenas-ui-components.d.ts

@@ -160,16 +160,249 @@ declare class TnTestIdDirective {
  */
 declare function writeTestId(renderer: Renderer2, element: Element, attrName: string, composed: string): void;
 
+interface TnSelectOption<T = unknown> {
+    value: T;
+    label: string;
+    disabled?: boolean;
+}
+interface TnSelectOptionGroup<T = unknown> {
+    label: string;
+    options: TnSelectOption<T>[];
+    disabled?: boolean;
+}
+declare class TnSelectComponent<T = unknown> implements ControlValueAccessor, OnDestroy {
+    options: _angular_core.InputSignal<TnSelectOption<T>[]>;
+    optionGroups: _angular_core.InputSignal<TnSelectOptionGroup<T>[]>;
+    placeholder: _angular_core.InputSignal<string>;
+    /**
+     * Accessible label for the select trigger. When set, this is used as the
+     * trigger's `aria-label` instead of the visible `placeholder` — useful in
+     * contexts (e.g. a pager's page-size dropdown) where the placeholder text
+     * doesn't accurately describe the field's purpose to screen readers.
+     */
+    ariaLabel: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Message shown inside the dropdown when no options (and no option groups)
+     * are available. Defaults to the English `'No options available'`; consumers
+     * with i18n requirements can pass a translated string.
+     */
+    noOptionsLabel: _angular_core.InputSignal<string>;
+    /**
+     * When `true` (single-select mode only), prepends a synthetic "empty"
+     * option to the dropdown so users can unset a chosen value: picking it
+     * resets the selection to `null`, shows the placeholder again, and emits
+     * `null` via `selectionChange` (and to any bound form control). Mirrors
+     * webui ix-select's `--` option. Ignored when `multiple` is set — there,
+     * values are cleared by toggling them off individually.
+     */
+    allowEmpty: _angular_core.InputSignal<boolean>;
+    /** Label of the empty option rendered when `allowEmpty` is set. */
+    emptyLabel: _angular_core.InputSignal<string>;
+    disabled: _angular_core.InputSignal<boolean>;
+    testId: _angular_core.InputSignal<TnTestIdValue>;
+    multiple: _angular_core.InputSignal<boolean>;
+    /**
+     * Optional extractor for the per-option test-id discriminator. Defaults to
+     * the option's `value` (when a string/number) or its `label`. Provide this
+     * when option values are objects, or to pick a more stable/unique key —
+     * mirrors webui's `[ixTest]="[controlName, option.<field>]"` discriminator.
+     *
+     * @example
+     * ```html
+     * <tn-select testId="user" [optionTestIdKey]="(o) => o.value.id" ... />
+     * ```
+     */
+    optionTestIdKey: _angular_core.InputSignal<((option: TnSelectOption<T>) => string | number | null | undefined) | undefined>;
+    /**
+     * Custom comparator for matching option values against the selected value(s).
+     *
+     * When the option values are objects, **provide this** — the built-in
+     * fallback uses `JSON.stringify`, which is key-order dependent and can
+     * produce false negatives for structurally equal objects. For primitives the
+     * default identity check is fine.
+     *
+     * @example
+     * ```ts
+     * compareWith = (a, b) => a?.id === b?.id;
+     * ```
+     */
+    compareWith: _angular_core.InputSignal<((a: T | null, b: T | null) => boolean) | undefined>;
+    /**
+     * Emits the picked value on each selection in single mode. Emits `null`
+     * when the user picks the `allowEmpty` empty option to clear the field.
+     */
+    selectionChange: _angular_core.OutputEmitterRef<T | null>;
+    /** Emits the full array of selected values after each toggle in multiple mode. */
+    multiSelectionChange: _angular_core.OutputEmitterRef<T[]>;
+    protected isOpen: _angular_core.WritableSignal<boolean>;
+    protected dropdownPosition: _angular_core.WritableSignal<"below" | "above">;
+    protected selectedValue: _angular_core.WritableSignal<T | null>;
+    protected selectedValues: _angular_core.WritableSignal<T[]>;
+    /** Index into `flatOptions` of the keyboard-focused row (-1 when none). */
+    protected focusedIndex: _angular_core.WritableSignal<number>;
+    private formDisabled;
+    private static instanceCounter;
+    private instanceId;
+    /**
+     * Id namespace used by all DOM ids the template emits (dropdown panel,
+     * option rows, group labels). Prefers `testId` when set so tests can target
+     * specific instances; otherwise falls back to a per-instance counter so two
+     * `<tn-select>`s on the same page never collide on `aria-controls`/group ids.
+     */
+    protected idNamespace: _angular_core.Signal<string>;
+    isDisabled: _angular_core.Signal<boolean>;
+    /**
+     * The synthetic clear-selection option (`allowEmpty`, single mode only).
+     * Its value is `null` cast to `T` so it flows through the same selection
+     * path as real options — `selectedValue`/`writeValue` already model "no
+     * selection" as `null`, so picking it clears the field for free.
+     */
+    protected emptyOption: _angular_core.Signal<TnSelectOption<T> | null>;
+    /** Ungrouped options as rendered: the empty option (when enabled) first. */
+    protected displayOptions: _angular_core.Signal<TnSelectOption<T>[]>;
+    /** Whether `option` is the synthetic `allowEmpty` clear option. */
+    protected isEmptyOption(option: TnSelectOption<T>): boolean;
+    /**
+     * Selectable, non-disabled options in display order (regular options first,
+     * then groups). Used by keyboard navigation so we can skip disabled
+     * entries and group headers without a separate filter pass.
+     */
+    navigableOptions: _angular_core.Signal<{
+        option: TnSelectOption<T>;
+        id: string;
+    }[]>;
+    /** Stable DOM id of the currently-highlighted option, for aria-activedescendant. */
+    focusedOptionId: _angular_core.Signal<string | null>;
+    /** Stable DOM id for an option; matches what navigableOptions() assigns. */
+    optionId(option: TnSelectOption<T>): string | null;
+    /** Whether `option` is the keyboard-highlighted item. */
+    isOptionFocused(option: TnSelectOption<T>): boolean;
+    /**
+     * Test-id segments for an option row, consumed by `[tnTestId]` with
+     * `tnTestIdType="option"`. The select's `testId` scopes each option so ids
+     * stay unique across selects: base `quick-filters` + option value `ssd` →
+     * `option-quick-filters-ssd`; with no base → `option-ssd`. The discriminator
+     * comes from `optionTestIdKey` when provided, else the option's primitive
+     * `value`, else its `label`.
+     */
+    protected optionTestIdParts(option: TnSelectOption<T>): (string | number | null | undefined)[];
+    private onChange;
+    private onTouched;
+    private elementRef;
+    private cdr;
+    private overlay;
+    private viewContainerRef;
+    private triggerEl;
+    private dropdownTemplate;
+    private overlayRef?;
+    private overlaySubs;
+    writeValue(value: T | T[] | null): void;
+    registerOnChange(fn: (value: T | T[] | null) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    toggleDropdown(): void;
+    openDropdown(): void;
+    /**
+     * Attach the dropdown panel as a CDK overlay anchored to the trigger.
+     *
+     * Why an overlay (vs. an inline absolutely-positioned panel):
+     *   - Escapes parent `overflow: hidden`/clipping in surrounding layouts.
+     *   - `outsidePointerEvents()` notifies on outside pointerdown WITHOUT
+     *     intercepting the click (no backdrop) — so the user's click reaches
+     *     the underlying target while the select closes silently.
+     *   - Position is recomputed on scroll so the panel stays attached.
+     *   - Width is matched to the trigger so the panel doesn't jump in size.
+     */
+    private attachOverlay;
+    private detachOverlay;
+    ngOnDestroy(): void;
+    /**
+     * Closes the dropdown.
+     *
+     * @param restoreFocus When `true` (the default), returns focus to the
+     *   trigger. Used for explicit closes — Escape, Enter/Space activation,
+     *   option click — where the user is still interacting with the select.
+     *   Pass `false` for click-outside / blur paths so we don't steal focus
+     *   from the element the user actually navigated to.
+     */
+    closeDropdown(restoreFocus?: boolean): void;
+    onOptionClick(option: TnSelectOption<T>, groupDisabled?: boolean): void;
+    selectOption(option: TnSelectOption<T>): void;
+    private toggleOption;
+    isOptionSelected(option: TnSelectOption<T>): boolean;
+    protected displayText: _angular_core.Signal<string>;
+    private findOptionByValue;
+    protected hasAnyOptions: _angular_core.Signal<boolean>;
+    /** One-shot guard so the object-compare warning fires at most once per instance. */
+    private warnedAboutObjectCompare;
+    /**
+     * Compares two option values for equality.
+     *
+     * - Uses `compareWith` when provided (the supported path for object values).
+     * - Falls back to strict identity (`===`) — adequate for primitives.
+     * - For object values WITHOUT `compareWith` we return `false` (no
+     *   structural compare) and emit a one-time warning. The previous
+     *   `JSON.stringify` fallback was key-order sensitive and produced silent
+     *   false-negatives that were hard to diagnose; returning `false` makes the
+     *   misuse loud (selection won't match) and the warning points to the fix.
+     *
+     * The warning is **unconditional** (not gated on `isDevMode()`) so prod
+     * monitoring picks it up — consumers relying on the old stringify fallback
+     * would otherwise see selections silently stop matching after upgrade with
+     * no signal in production logs.
+     */
+    private compareValues;
+    /**
+     * Keyboard navigation for the combobox trigger.
+     *
+     * - **ArrowDown / ArrowUp** opens the dropdown if closed; otherwise moves
+     *   the keyboard-focus highlight (via aria-activedescendant) up/down,
+     *   skipping disabled options and group headers.
+     * - **Home / End** jump to the first / last enabled option.
+     * - **Enter / Space** opens the dropdown if closed; if open and an option
+     *   is highlighted, selects that option (in single mode) or toggles it
+     *   (in multiple mode).
+     * - **Escape** closes the dropdown without changing the selection.
+     *
+     * All navigation keys call `event.preventDefault()` so the page does not
+     * scroll while the user is moving through options.
+     */
+    onKeydown(event: KeyboardEvent): void;
+    private moveFocus;
+    private activateFocusedOption;
+    private scrollFocusedIntoView;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnSelectComponent<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnSelectComponent<any>, "tn-select", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "optionGroups": { "alias": "optionGroups"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "noOptionsLabel": { "alias": "noOptionsLabel"; "required": false; "isSignal": true; }; "allowEmpty": { "alias": "allowEmpty"; "required": false; "isSignal": true; }; "emptyLabel": { "alias": "emptyLabel"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "optionTestIdKey": { "alias": "optionTestIdKey"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; }, { "selectionChange": "selectionChange"; "multiSelectionChange": "multiSelectionChange"; }, never, never, true, never>;
+}
+
+/**
+ * Option shape for `tn-autocomplete` — the `label` is displayed, the `value`
+ * is committed to the form control, and a truthy `disabled` keeps the row
+ * visible but non-selectable (skipped by keyboard nav, click, and text-match
+ * commits). Structurally identical to `TnSelectOption`, so the same data
+ * sources feed both dropdown components.
+ */
+type TnAutocompleteOption<T = unknown> = TnSelectOption<T>;
 declare class TnAutocompleteComponent<T = unknown> implements ControlValueAccessor, OnDestroy {
     private readonly elementRef;
     private readonly overlay;
     private readonly viewContainerRef;
     /** Unique instance ID for ARIA linkage */
     protected readonly uid: string;
-    /** All available options */
-    options: _angular_core.InputSignal<T[]>;
-    /** Transform a value to its display string */
-    displayWith: _angular_core.InputSignal<(value: T) => string>;
+    /**
+     * All available options. The `label` is displayed; the `value` is committed
+     * to the form control. A written value is resolved back to its option's
+     * label for display — falling back to `String(value)` until the matching
+     * option is available, and upgraded once an async option load lands.
+     */
+    options: _angular_core.InputSignal<TnAutocompleteOption<T>[]>;
+    /**
+     * Custom comparator for matching a written control value against option
+     * values during display resolution. Defaults to identity (`===`), which is
+     * right for primitive values; provide this when option values are objects.
+     * Mirrors `tn-select`'s `compareWith`.
+     */
+    compareWith: _angular_core.InputSignal<((a: T | null, b: T | null) => boolean) | undefined>;
     /** Placeholder text for the input */
     placeholder: _angular_core.InputSignal<string>;
     /** Whether the input is disabled */
@@ -191,8 +424,8 @@ declare class TnAutocompleteComponent<T = unknown> implements ControlValueAccess
     loading: _angular_core.InputSignal<boolean>;
     /** Text shown next to the spinner while `loading` is set. */
     loadingText: _angular_core.InputSignal<string>;
-    /** Custom filter function. Defaults to case-insensitive includes on displayWith text */
-    filterFn: _angular_core.InputSignal<((option: T, searchTerm: string) => boolean) | undefined>;
+    /** Custom filter function. Defaults to case-insensitive includes on the option label */
+    filterFn: _angular_core.InputSignal<((option: TnAutocompleteOption<T>, searchTerm: string) => boolean) | undefined>;
     /** Text shown when no options match the search */
     noResultsText: _angular_core.InputSignal<string>;
     /**
@@ -212,8 +445,8 @@ declare class TnAutocompleteComponent<T = unknown> implements ControlValueAccess
     panelMaxHeight: _angular_core.InputSignal<string | number>;
     /** Test ID attribute */
     testId: _angular_core.InputSignal<TnTestIdValue>;
-    /** Emits when an option is selected */
-    optionSelected: _angular_core.OutputEmitterRef<T>;
+    /** Emits the full option (label + value) when one is selected */
+    optionSelected: _angular_core.OutputEmitterRef<TnAutocompleteOption<T>>;
     /**
      * Emits the search term as the user types (not on programmatic writes or
      * option selection). Drive server-side filtering from this: fetch matches
@@ -249,14 +482,14 @@ declare class TnAutocompleteComponent<T = unknown> implements ControlValueAccess
     protected isOpen: _angular_core.WritableSignal<boolean>;
     /** Index of the currently highlighted option for keyboard nav */
     protected highlightedIndex: _angular_core.WritableSignal<number>;
-    /** The currently selected value */
+    /** The currently committed value (an option's `value`, or a custom-typed one) */
     private selectedValue;
     /** CVA disabled state from the form */
     private formDisabled;
     /** Combined disabled state */
     isDisabled: _angular_core.Signal<boolean>;
     /** Filtered and capped options */
-    protected filteredOptions: _angular_core.Signal<T[]>;
+    protected filteredOptions: _angular_core.Signal<TnAutocompleteOption<T>[]>;
     /** Whether there are any results to show */
     protected hasResults: _angular_core.Signal<boolean>;
     private onChange;
@@ -273,6 +506,8 @@ declare class TnAutocompleteComponent<T = unknown> implements ControlValueAccess
     private lastOptionsCount;
     /** Scroll distance (px) from the panel bottom that triggers `loadMore`. */
     private static readonly loadMoreThresholdPx;
+    /** Guards the object-without-compareWith warning so it fires only once. */
+    private warnedAboutObjectCompare;
     constructor();
     ngOnDestroy(): void;
     writeValue(value: T | null): void;
@@ -282,7 +517,7 @@ declare class TnAutocompleteComponent<T = unknown> implements ControlValueAccess
     onInput(event: Event): void;
     onFocus(): void;
     onBlur(): void;
-    onOptionClick(option: T): void;
+    onOptionClick(option: TnAutocompleteOption<T>): void;
     onKeydown(event: KeyboardEvent): void;
     /**
      * `loadMore` normally fires from a scroll event, which never happens when
@@ -292,6 +527,25 @@ declare class TnAutocompleteComponent<T = unknown> implements ControlValueAccess
      */
     private checkUnderfill;
     onPanelScroll(event: Event): void;
+    /**
+     * Whether `option` carries the committed value — drives `aria-selected` so
+     * assistive tech announces the current choice independently of the keyboard
+     * cursor (which is conveyed via `aria-activedescendant`).
+     */
+    protected isOptionSelected(option: TnAutocompleteOption<T>): boolean;
+    /**
+     * Index of the committed value's option in the visible list, or -1 when
+     * nothing is committed or the match is absent/disabled. Used to seed the
+     * keyboard cursor when the panel opens.
+     */
+    private selectedOptionIndex;
+    /**
+     * Next selectable option index from `from` in `direction` (+1 down, -1 up),
+     * skipping disabled rows and wrapping around. `from` of -1 ("nothing
+     * highlighted") lands on the first row going down, the last going up.
+     * Returns -1 when every visible option is disabled.
+     */
+    private nextEnabledIndex;
     /**
      * Commit the current search term as the value (allowCustomValue mode). A
      * display match (case-insensitive, same as the requireSelection path)
@@ -299,6 +553,19 @@ declare class TnAutocompleteComponent<T = unknown> implements ControlValueAccess
      * typing its full text behaves like clicking it.
      */
     private commitCustomValue;
+    /**
+     * Resolves a committed value back to its option's display label, falling
+     * back to the raw value's string until the matching option is available.
+     */
+    private displayValue;
+    /**
+     * Compares option values, honoring `compareWith` when provided. Without one,
+     * falls back to identity (`===`) — which never matches structurally-equal
+     * objects from different references, so display resolution and selection
+     * silently fail. Warn once on that misuse (unconditional, like `tn-select`,
+     * so prod monitoring catches it) and return `false` to make it loud.
+     */
+    private valueMatches;
     private selectOption;
     private open;
     private close;
@@ -315,7 +582,7 @@ declare class TnAutocompleteComponent<T = unknown> implements ControlValueAccess
     private detachOverlay;
     private scrollToHighlighted;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnAutocompleteComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnAutocompleteComponent<any>, "tn-autocomplete", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "displayWith": { "alias": "displayWith"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "requireSelection": { "alias": "requireSelection"; "required": false; "isSignal": true; }; "allowCustomValue": { "alias": "allowCustomValue"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "loadingText": { "alias": "loadingText"; "required": false; "isSignal": true; }; "filterFn": { "alias": "filterFn"; "required": false; "isSignal": true; }; "noResultsText": { "alias": "noResultsText"; "required": false; "isSignal": true; }; "maxResults": { "alias": "maxResults"; "required": false; "isSignal": true; }; "panelMaxHeight": { "alias": "panelMaxHeight"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; }, { "optionSelected": "optionSelected"; "searchChange": "searchChange"; "loadMore": "loadMore"; "opened": "opened"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnAutocompleteComponent<any>, "tn-autocomplete", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "requireSelection": { "alias": "requireSelection"; "required": false; "isSignal": true; }; "allowCustomValue": { "alias": "allowCustomValue"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "loadingText": { "alias": "loadingText"; "required": false; "isSignal": true; }; "filterFn": { "alias": "filterFn"; "required": false; "isSignal": true; }; "noResultsText": { "alias": "noResultsText"; "required": false; "isSignal": true; }; "maxResults": { "alias": "maxResults"; "required": false; "isSignal": true; }; "panelMaxHeight": { "alias": "panelMaxHeight"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; }, { "optionSelected": "optionSelected"; "searchChange": "searchChange"; "loadMore": "loadMore"; "opened": "opened"; }, never, never, true, never>;
 }
 
 /**
@@ -2783,7 +3050,7 @@ declare class TnTabComponent implements AfterContentInit {
     onClick(): void;
     onKeydown(event: KeyboardEvent): void;
     classes: _angular_core.Signal<string>;
-    tabIndex: _angular_core.Signal<0 | -1>;
+    tabIndex: _angular_core.Signal<-1 | 0>;
     hasIcon: _angular_core.Signal<boolean>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnTabComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnTabComponent, "tn-tab", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "iconTemplate": { "alias": "iconTemplate"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; }, { "selected": "selected"; }, ["iconContent"], ["*"], true, never>;
@@ -3214,7 +3481,7 @@ interface TabsHarnessFilters extends BaseHarnessFilters {
  */
 declare class TnMenuTriggerDirective implements OnDestroy {
     menu: _angular_core.InputSignal<TnMenuComponent>;
-    tnMenuPosition: _angular_core.InputSignal<"above" | "below" | "before" | "after">;
+    tnMenuPosition: _angular_core.InputSignal<"below" | "above" | "before" | "after">;
     private overlayRef?;
     private isMenuOpen;
     private itemClickSub?;
@@ -3801,221 +4068,6 @@ interface FormFieldHarnessFilters extends BaseHarnessFilters {
     testId?: string;
 }
 
-interface TnSelectOption<T = unknown> {
-    value: T;
-    label: string;
-    disabled?: boolean;
-}
-interface TnSelectOptionGroup<T = unknown> {
-    label: string;
-    options: TnSelectOption<T>[];
-    disabled?: boolean;
-}
-declare class TnSelectComponent<T = unknown> implements ControlValueAccessor, OnDestroy {
-    options: _angular_core.InputSignal<TnSelectOption<T>[]>;
-    optionGroups: _angular_core.InputSignal<TnSelectOptionGroup<T>[]>;
-    placeholder: _angular_core.InputSignal<string>;
-    /**
-     * Accessible label for the select trigger. When set, this is used as the
-     * trigger's `aria-label` instead of the visible `placeholder` — useful in
-     * contexts (e.g. a pager's page-size dropdown) where the placeholder text
-     * doesn't accurately describe the field's purpose to screen readers.
-     */
-    ariaLabel: _angular_core.InputSignal<string | undefined>;
-    /**
-     * Message shown inside the dropdown when no options (and no option groups)
-     * are available. Defaults to the English `'No options available'`; consumers
-     * with i18n requirements can pass a translated string.
-     */
-    noOptionsLabel: _angular_core.InputSignal<string>;
-    /**
-     * When `true` (single-select mode only), prepends a synthetic "empty"
-     * option to the dropdown so users can unset a chosen value: picking it
-     * resets the selection to `null`, shows the placeholder again, and emits
-     * `null` via `selectionChange` (and to any bound form control). Mirrors
-     * webui ix-select's `--` option. Ignored when `multiple` is set — there,
-     * values are cleared by toggling them off individually.
-     */
-    allowEmpty: _angular_core.InputSignal<boolean>;
-    /** Label of the empty option rendered when `allowEmpty` is set. */
-    emptyLabel: _angular_core.InputSignal<string>;
-    disabled: _angular_core.InputSignal<boolean>;
-    testId: _angular_core.InputSignal<TnTestIdValue>;
-    multiple: _angular_core.InputSignal<boolean>;
-    /**
-     * Optional extractor for the per-option test-id discriminator. Defaults to
-     * the option's `value` (when a string/number) or its `label`. Provide this
-     * when option values are objects, or to pick a more stable/unique key —
-     * mirrors webui's `[ixTest]="[controlName, option.<field>]"` discriminator.
-     *
-     * @example
-     * ```html
-     * <tn-select testId="user" [optionTestIdKey]="(o) => o.value.id" ... />
-     * ```
-     */
-    optionTestIdKey: _angular_core.InputSignal<((option: TnSelectOption<T>) => string | number | null | undefined) | undefined>;
-    /**
-     * Custom comparator for matching option values against the selected value(s).
-     *
-     * When the option values are objects, **provide this** — the built-in
-     * fallback uses `JSON.stringify`, which is key-order dependent and can
-     * produce false negatives for structurally equal objects. For primitives the
-     * default identity check is fine.
-     *
-     * @example
-     * ```ts
-     * compareWith = (a, b) => a?.id === b?.id;
-     * ```
-     */
-    compareWith: _angular_core.InputSignal<((a: T | null, b: T | null) => boolean) | undefined>;
-    /**
-     * Emits the picked value on each selection in single mode. Emits `null`
-     * when the user picks the `allowEmpty` empty option to clear the field.
-     */
-    selectionChange: _angular_core.OutputEmitterRef<T | null>;
-    /** Emits the full array of selected values after each toggle in multiple mode. */
-    multiSelectionChange: _angular_core.OutputEmitterRef<T[]>;
-    protected isOpen: _angular_core.WritableSignal<boolean>;
-    protected dropdownPosition: _angular_core.WritableSignal<"above" | "below">;
-    protected selectedValue: _angular_core.WritableSignal<T | null>;
-    protected selectedValues: _angular_core.WritableSignal<T[]>;
-    /** Index into `flatOptions` of the keyboard-focused row (-1 when none). */
-    protected focusedIndex: _angular_core.WritableSignal<number>;
-    private formDisabled;
-    private static instanceCounter;
-    private instanceId;
-    /**
-     * Id namespace used by all DOM ids the template emits (dropdown panel,
-     * option rows, group labels). Prefers `testId` when set so tests can target
-     * specific instances; otherwise falls back to a per-instance counter so two
-     * `<tn-select>`s on the same page never collide on `aria-controls`/group ids.
-     */
-    protected idNamespace: _angular_core.Signal<string>;
-    isDisabled: _angular_core.Signal<boolean>;
-    /**
-     * The synthetic clear-selection option (`allowEmpty`, single mode only).
-     * Its value is `null` cast to `T` so it flows through the same selection
-     * path as real options — `selectedValue`/`writeValue` already model "no
-     * selection" as `null`, so picking it clears the field for free.
-     */
-    protected emptyOption: _angular_core.Signal<TnSelectOption<T> | null>;
-    /** Ungrouped options as rendered: the empty option (when enabled) first. */
-    protected displayOptions: _angular_core.Signal<TnSelectOption<T>[]>;
-    /** Whether `option` is the synthetic `allowEmpty` clear option. */
-    protected isEmptyOption(option: TnSelectOption<T>): boolean;
-    /**
-     * Selectable, non-disabled options in display order (regular options first,
-     * then groups). Used by keyboard navigation so we can skip disabled
-     * entries and group headers without a separate filter pass.
-     */
-    navigableOptions: _angular_core.Signal<{
-        option: TnSelectOption<T>;
-        id: string;
-    }[]>;
-    /** Stable DOM id of the currently-highlighted option, for aria-activedescendant. */
-    focusedOptionId: _angular_core.Signal<string | null>;
-    /** Stable DOM id for an option; matches what navigableOptions() assigns. */
-    optionId(option: TnSelectOption<T>): string | null;
-    /** Whether `option` is the keyboard-highlighted item. */
-    isOptionFocused(option: TnSelectOption<T>): boolean;
-    /**
-     * Test-id segments for an option row, consumed by `[tnTestId]` with
-     * `tnTestIdType="option"`. The select's `testId` scopes each option so ids
-     * stay unique across selects: base `quick-filters` + option value `ssd` →
-     * `option-quick-filters-ssd`; with no base → `option-ssd`. The discriminator
-     * comes from `optionTestIdKey` when provided, else the option's primitive
-     * `value`, else its `label`.
-     */
-    protected optionTestIdParts(option: TnSelectOption<T>): (string | number | null | undefined)[];
-    private onChange;
-    private onTouched;
-    private elementRef;
-    private cdr;
-    private overlay;
-    private viewContainerRef;
-    private triggerEl;
-    private dropdownTemplate;
-    private overlayRef?;
-    private overlaySubs;
-    writeValue(value: T | T[] | null): void;
-    registerOnChange(fn: (value: T | T[] | null) => void): void;
-    registerOnTouched(fn: () => void): void;
-    setDisabledState(isDisabled: boolean): void;
-    toggleDropdown(): void;
-    openDropdown(): void;
-    /**
-     * Attach the dropdown panel as a CDK overlay anchored to the trigger.
-     *
-     * Why an overlay (vs. an inline absolutely-positioned panel):
-     *   - Escapes parent `overflow: hidden`/clipping in surrounding layouts.
-     *   - `outsidePointerEvents()` notifies on outside pointerdown WITHOUT
-     *     intercepting the click (no backdrop) — so the user's click reaches
-     *     the underlying target while the select closes silently.
-     *   - Position is recomputed on scroll so the panel stays attached.
-     *   - Width is matched to the trigger so the panel doesn't jump in size.
-     */
-    private attachOverlay;
-    private detachOverlay;
-    ngOnDestroy(): void;
-    /**
-     * Closes the dropdown.
-     *
-     * @param restoreFocus When `true` (the default), returns focus to the
-     *   trigger. Used for explicit closes — Escape, Enter/Space activation,
-     *   option click — where the user is still interacting with the select.
-     *   Pass `false` for click-outside / blur paths so we don't steal focus
-     *   from the element the user actually navigated to.
-     */
-    closeDropdown(restoreFocus?: boolean): void;
-    onOptionClick(option: TnSelectOption<T>, groupDisabled?: boolean): void;
-    selectOption(option: TnSelectOption<T>): void;
-    private toggleOption;
-    isOptionSelected(option: TnSelectOption<T>): boolean;
-    protected displayText: _angular_core.Signal<string>;
-    private findOptionByValue;
-    protected hasAnyOptions: _angular_core.Signal<boolean>;
-    /** One-shot guard so the object-compare warning fires at most once per instance. */
-    private warnedAboutObjectCompare;
-    /**
-     * Compares two option values for equality.
-     *
-     * - Uses `compareWith` when provided (the supported path for object values).
-     * - Falls back to strict identity (`===`) — adequate for primitives.
-     * - For object values WITHOUT `compareWith` we return `false` (no
-     *   structural compare) and emit a one-time warning. The previous
-     *   `JSON.stringify` fallback was key-order sensitive and produced silent
-     *   false-negatives that were hard to diagnose; returning `false` makes the
-     *   misuse loud (selection won't match) and the warning points to the fix.
-     *
-     * The warning is **unconditional** (not gated on `isDevMode()`) so prod
-     * monitoring picks it up — consumers relying on the old stringify fallback
-     * would otherwise see selections silently stop matching after upgrade with
-     * no signal in production logs.
-     */
-    private compareValues;
-    /**
-     * Keyboard navigation for the combobox trigger.
-     *
-     * - **ArrowDown / ArrowUp** opens the dropdown if closed; otherwise moves
-     *   the keyboard-focus highlight (via aria-activedescendant) up/down,
-     *   skipping disabled options and group headers.
-     * - **Home / End** jump to the first / last enabled option.
-     * - **Enter / Space** opens the dropdown if closed; if open and an option
-     *   is highlighted, selects that option (in single mode) or toggles it
-     *   (in multiple mode).
-     * - **Escape** closes the dropdown without changing the selection.
-     *
-     * All navigation keys call `event.preventDefault()` so the page does not
-     * scroll while the user is moving through options.
-     */
-    onKeydown(event: KeyboardEvent): void;
-    private moveFocus;
-    private activateFocusedOption;
-    private scrollFocusedIntoView;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnSelectComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnSelectComponent<any>, "tn-select", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "optionGroups": { "alias": "optionGroups"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "noOptionsLabel": { "alias": "noOptionsLabel"; "required": false; "isSignal": true; }; "allowEmpty": { "alias": "allowEmpty"; "required": false; "isSignal": true; }; "emptyLabel": { "alias": "emptyLabel"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "optionTestIdKey": { "alias": "optionTestIdKey"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; }, { "selectionChange": "selectionChange"; "multiSelectionChange": "multiSelectionChange"; }, never, never, true, never>;
-}
-
 /**
  * Harness for interacting with tn-select in tests.
  * Provides methods for querying select state, opening/closing the dropdown,
@@ -7794,4 +7846,4 @@ declare const TN_THEME_DEFINITIONS: readonly TnThemeDefinition[];
 declare const THEME_MAP: Map<TnTheme, TnThemeDefinition>;
 
 export { CommonShortcuts, DEFAULT_THEME, DiskIconComponent, DiskType, FileSizePipe, InputType, LIGHT_THEME, LabelMarkupPipe, LabelTextPipe, LinuxModifierKeys, LinuxShortcuts, ModifierKeys, QuickShortcuts, ShortcutBuilder, StripMntPrefixPipe, THEME_MAP, THEME_STORAGE_KEY, TN_FORM_FIELD_ERRORS, TN_TABLE_PAGER_DEFAULT_LABELS, TN_TABLE_PAGER_LABELS, TN_TEST_ATTR, TN_THEME_DEFINITIONS, TnAutocompleteComponent, TnAutocompleteHarness, TnBannerActionDirective, TnBannerComponent, TnBannerHarness, TnBrandedSpinnerComponent, TnButtonComponent, TnButtonHarness, TnButtonToggleComponent, TnButtonToggleGroupComponent, TnButtonToggleGroupHarness, TnButtonToggleHarness, TnCalendarComponent, TnCalendarHeaderComponent, TnCardComponent, TnCardHeaderDirective, TnCellDefDirective, TnCheckboxComponent, TnCheckboxHarness, TnCheckboxLabelDirective, TnChipComponent, TnConfirmDialogComponent, TnDateInputComponent, TnDateInputHarness, TnDateRangeInputComponent, TnDateRangeInputHarness, TnDetailRowDefDirective, TnDialog, TnDialogHarness, TnDialogShellComponent, TnDialogTesting, TnDividerComponent, TnDividerDirective, TnDrawerComponent, TnDrawerContainerComponent, TnDrawerContainerHarness, TnDrawerContentComponent, TnDrawerHarness, TnEmptyComponent, TnEmptyHarness, TnExpansionPanelComponent, TnExpansionPanelHarness, TnFilePickerComponent, TnFilePickerPopupComponent, TnFormFieldComponent, TnFormFieldHarness, TnHeaderCellDefDirective, TnIconButtonComponent, TnIconButtonHarness, TnIconComponent, TnIconHarness, TnIconRegistryService, TnIconTesting, TnInputComponent, TnInputDirective, TnInputHarness, TnKeyboardShortcutComponent, TnKeyboardShortcutService, TnListAvatarDirective, TnListComponent, TnListIconDirective, TnListItemComponent, TnListItemLineDirective, TnListItemPrimaryDirective, TnListItemSecondaryDirective, TnListItemTitleDirective, TnListItemTrailingDirective, TnListOptionComponent, TnListSubheaderComponent, TnMenuActivateHoverDirective, TnMenuComponent, TnMenuHarness, TnMenuItemComponent, TnMenuTesting, TnMenuTriggerDirective, TnMonthViewComponent, TnMultiYearViewComponent, TnNestedTreeNodeComponent, TnParticleProgressBarComponent, TnProgressBarComponent, TnRadioComponent, TnRadioHarness, TnSelectComponent, TnSelectHarness, TnSelectionListComponent, TnSidePanelActionDirective, TnSidePanelComponent, TnSidePanelHarness, TnSidePanelHeaderActionDirective, TnSlideToggleComponent, TnSlideToggleHarness, TnSliderComponent, TnSliderThumbDirective, TnSliderWithLabelDirective, TnSpinnerComponent, TnSpriteLoaderService, TnStepComponent, TnStepperComponent, TnTabComponent, TnTabHarness, TnTabPanelComponent, TnTabPanelHarness, TnTableColumnDirective, TnTableComponent, TnTableHarness, TnTablePagerComponent, TnTablePagerHarness, TnTabsComponent, TnTabsHarness, TnTestIdDirective, TnTheme, TnThemeService, TnTimeInputComponent, TnToastComponent, TnToastMock, TnToastPosition, TnToastRef, TnToastService, TnToastTesting, TnToastType, TnTooltipComponent, TnTooltipDirective, TnTreeComponent, TnTreeFlatDataSource, TnTreeFlattener, TnTreeNodeComponent, TnTreeNodeOutletDirective, TruncatePathPipe, WindowsModifierKeys, WindowsShortcuts, composeTestId, createLucideLibrary, createShortcut, defaultSpriteBasePath, defaultSpriteConfigPath, formatSize, kebabTestSegment, labelMarkupToHtml, labelMarkupToText, libIconMarker, parseLabelMarkup, parseSize, registerLucideIcons, scopeTestId, setupLucideIntegration, tnIconMarker, writeTestId };
-export type { AutocompleteHarnessFilters, BannerHarnessFilters, ButtonHarnessFilters, ButtonToggleHarnessFilters, CalendarCell, CheckboxHarnessFilters, ChipColor, CreateFolderEvent, DateInputHarnessFilters, DateRange, DateRangeInputHarnessFilters, DialogHarnessFilters, EmptyHarnessFilters, ExpansionPanelHarnessFilters, FilePickerCallbacks, FilePickerError, FilePickerMode, FileSystemItem, FormFieldHarnessFilters, IconButtonHarnessFilters, IconHarnessFilters, IconLibrary, IconLibraryType, IconResult, IconSize, IconSource, IconTestingMockOverrides, InputHarnessFilters, KeyCombination, LabelMarkupSegment, LabelMarkupSegmentType, LabelType, LucideIconOptions, MenuHarnessFilters, MockIconRegistry, MockSpriteLoader, PathSegment, PlatformType, ProgressBarMode, RadioHarnessFilters, ResolvedIcon, SelectHarnessFilters, ShortcutHandler, SidePanelHarnessFilters, SizeStandard, SlideToggleColor, SlideToggleHarnessFilters, SpinnerMode, SpriteConfig, SubscriptSizing, TabChangeEvent, TabHarnessFilters, TabPanelHarnessFilters, TabsHarnessFilters, TnBannerType, TnButtonToggleType, TnCardAction, TnCardControl, TnCardFooterLink, TnCardHeaderStatus, TnConfirmDialogData, TnDialogDefaults, TnDialogOpenTarget, TnDrawerMode, TnDrawerPosition, TnEmptySize, TnFlatTreeNode, TnFormFieldErrorMessage, TnFormFieldErrorMessages, TnFormFieldErrorResolver, TnMenuItem, TnSelectOption, TnSelectOptionGroup, TnSelectionChange, TnSortEvent, TnTableDataProvider, TnTableDataSource, TnTableHarnessFilters, TnTablePagerHarnessFilters, TnTablePagerLabels, TnTablePagination, TnTestAttrName, TnTestIdValue, TnThemeDefinition, TnToastCall, TnToastConfig, TooltipPosition, YearCell };
+export type { AutocompleteHarnessFilters, BannerHarnessFilters, ButtonHarnessFilters, ButtonToggleHarnessFilters, CalendarCell, CheckboxHarnessFilters, ChipColor, CreateFolderEvent, DateInputHarnessFilters, DateRange, DateRangeInputHarnessFilters, DialogHarnessFilters, EmptyHarnessFilters, ExpansionPanelHarnessFilters, FilePickerCallbacks, FilePickerError, FilePickerMode, FileSystemItem, FormFieldHarnessFilters, IconButtonHarnessFilters, IconHarnessFilters, IconLibrary, IconLibraryType, IconResult, IconSize, IconSource, IconTestingMockOverrides, InputHarnessFilters, KeyCombination, LabelMarkupSegment, LabelMarkupSegmentType, LabelType, LucideIconOptions, MenuHarnessFilters, MockIconRegistry, MockSpriteLoader, PathSegment, PlatformType, ProgressBarMode, RadioHarnessFilters, ResolvedIcon, SelectHarnessFilters, ShortcutHandler, SidePanelHarnessFilters, SizeStandard, SlideToggleColor, SlideToggleHarnessFilters, SpinnerMode, SpriteConfig, SubscriptSizing, TabChangeEvent, TabHarnessFilters, TabPanelHarnessFilters, TabsHarnessFilters, TnAutocompleteOption, TnBannerType, TnButtonToggleType, TnCardAction, TnCardControl, TnCardFooterLink, TnCardHeaderStatus, TnConfirmDialogData, TnDialogDefaults, TnDialogOpenTarget, TnDrawerMode, TnDrawerPosition, TnEmptySize, TnFlatTreeNode, TnFormFieldErrorMessage, TnFormFieldErrorMessages, TnFormFieldErrorResolver, TnMenuItem, TnSelectOption, TnSelectOptionGroup, TnSelectionChange, TnSortEvent, TnTableDataProvider, TnTableDataSource, TnTableHarnessFilters, TnTablePagerHarnessFilters, TnTablePagerLabels, TnTablePagination, TnTestAttrName, TnTestIdValue, TnThemeDefinition, TnToastCall, TnToastConfig, TooltipPosition, YearCell };