@truenas/ui-components 0.1.22 → 0.1.24

package/package.json

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

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

@@ -1,8 +1,8 @@
 import * as _angular_core from '@angular/core';
 import { ElementRef, AfterViewInit, OnDestroy, AfterContentInit, TemplateRef, Provider, ChangeDetectorRef, PipeTransform, OnInit, ViewContainerRef, AfterViewChecked } from '@angular/core';
+import { ControlValueAccessor, NgControl } from '@angular/forms';
 import { ComponentHarness, BaseHarnessFilters, HarnessPredicate, HarnessLoader } from '@angular/cdk/testing';
 import { SafeHtml, SafeResourceUrl, DomSanitizer } from '@angular/platform-browser';
-import { ControlValueAccessor, NgControl } from '@angular/forms';
 import { DataSource } from '@angular/cdk/collections';
 import * as i1 from '@angular/cdk/tree';
 import { CdkTree, FlatTreeControl, CdkTreeNode, CdkNestedTreeNode } from '@angular/cdk/tree';
@@ -13,6 +13,246 @@ import { DialogConfig, DialogRef } from '@angular/cdk/dialog';
 import { ComponentType } from '@angular/cdk/portal';
 import { ComponentFixture } from '@angular/core/testing';
 
+declare class TnAutocompleteComponent<T = unknown> implements ControlValueAccessor {
+    private readonly elementRef;
+    /** 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>;
+    /** Placeholder text for the input */
+    placeholder: _angular_core.InputSignal<string>;
+    /** Whether the input is disabled */
+    disabled: _angular_core.InputSignal<boolean>;
+    /** Require the user to select from the dropdown — reverts on blur if no match */
+    requireSelection: _angular_core.InputSignal<boolean>;
+    /** Custom filter function. Defaults to case-insensitive includes on displayWith text */
+    filterFn: _angular_core.InputSignal<((option: T, searchTerm: string) => boolean) | undefined>;
+    /** Text shown when no options match the search */
+    noResultsText: _angular_core.InputSignal<string>;
+    /** Maximum number of options to render */
+    maxResults: _angular_core.InputSignal<number>;
+    /** Test ID attribute */
+    testId: _angular_core.InputSignal<string>;
+    /** Emits when an option is selected */
+    optionSelected: _angular_core.OutputEmitterRef<T>;
+    /** Reference to the input element */
+    inputEl: _angular_core.Signal<ElementRef<HTMLInputElement> | undefined>;
+    /** Current search term typed by the user */
+    protected searchTerm: _angular_core.WritableSignal<string>;
+    /** Whether the dropdown is open */
+    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 */
+    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[]>;
+    /** Whether there are any results to show */
+    protected hasResults: _angular_core.Signal<boolean>;
+    private onChange;
+    private onTouched;
+    constructor();
+    writeValue(value: T | null): void;
+    registerOnChange(fn: (value: T | null) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    onInput(event: Event): void;
+    onFocus(): void;
+    onBlur(): void;
+    onOptionClick(option: T): void;
+    onKeydown(event: KeyboardEvent): void;
+    private selectOption;
+    private close;
+    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; }; "filterFn": { "alias": "filterFn"; "required": false; "isSignal": true; }; "noResultsText": { "alias": "noResultsText"; "required": false; "isSignal": true; }; "maxResults": { "alias": "maxResults"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; }, { "optionSelected": "optionSelected"; }, never, never, true, never>;
+}
+
+/**
+ * Harness for interacting with tn-autocomplete in tests.
+ * Provides methods for querying state, typing search text, and selecting options.
+ *
+ * @example
+ * ```typescript
+ * // Find and select an option
+ * const ac = await loader.getHarness(TnAutocompleteHarness);
+ * await ac.selectOption('United States');
+ *
+ * // Type to filter, then read options
+ * await ac.setInputValue('Can');
+ * const options = await ac.getOptions();
+ * expect(options).toEqual(['Canada']);
+ *
+ * // Filter by placeholder
+ * const countryAc = await loader.getHarness(
+ *   TnAutocompleteHarness.with({ placeholder: 'Search countries...' })
+ * );
+ * ```
+ */
+declare class TnAutocompleteHarness extends ComponentHarness {
+    /**
+     * The selector for the host element of a `TnAutocompleteComponent` instance.
+     */
+    static hostSelector: string;
+    private _input;
+    /**
+     * Gets a `HarnessPredicate` that can be used to search for an autocomplete
+     * with specific attributes.
+     *
+     * @param options Options for filtering which autocomplete instances are considered a match.
+     * @returns A `HarnessPredicate` configured with the given options.
+     *
+     * @example
+     * ```typescript
+     * // Find by exact placeholder
+     * const ac = await loader.getHarness(
+     *   TnAutocompleteHarness.with({ placeholder: 'Search countries...' })
+     * );
+     * ```
+     */
+    static with(options?: AutocompleteHarnessFilters): HarnessPredicate<TnAutocompleteHarness>;
+    /**
+     * Gets the current value of the input field.
+     *
+     * @returns Promise resolving to the input value.
+     *
+     * @example
+     * ```typescript
+     * const ac = await loader.getHarness(TnAutocompleteHarness);
+     * await ac.selectOption('Canada');
+     * expect(await ac.getInputValue()).toBe('Canada');
+     * ```
+     */
+    getInputValue(): Promise<string>;
+    /**
+     * Sets the value of the input by clearing and typing.
+     * This triggers filtering of the dropdown options.
+     *
+     * @param value The text to type into the input.
+     *
+     * @example
+     * ```typescript
+     * const ac = await loader.getHarness(TnAutocompleteHarness);
+     * await ac.setInputValue('Can');
+     * const options = await ac.getOptions();
+     * expect(options).toEqual(['Canada']);
+     * ```
+     */
+    setInputValue(value: string): Promise<void>;
+    /**
+     * Gets the placeholder text of the input.
+     *
+     * @returns Promise resolving to the placeholder string, or null.
+     *
+     * @example
+     * ```typescript
+     * const ac = await loader.getHarness(TnAutocompleteHarness);
+     * expect(await ac.getPlaceholder()).toBe('Type to search...');
+     * ```
+     */
+    getPlaceholder(): Promise<string | null>;
+    /**
+     * Checks whether the dropdown is currently open.
+     *
+     * @returns Promise resolving to true if the dropdown is visible.
+     *
+     * @example
+     * ```typescript
+     * const ac = await loader.getHarness(TnAutocompleteHarness);
+     * expect(await ac.isOpen()).toBe(false);
+     * await ac.focus();
+     * expect(await ac.isOpen()).toBe(true);
+     * ```
+     */
+    isOpen(): Promise<boolean>;
+    /**
+     * Checks whether the autocomplete input is disabled.
+     *
+     * @returns Promise resolving to true if the input is disabled.
+     *
+     * @example
+     * ```typescript
+     * const ac = await loader.getHarness(TnAutocompleteHarness);
+     * expect(await ac.isDisabled()).toBe(false);
+     * ```
+     */
+    isDisabled(): Promise<boolean>;
+    /**
+     * Gets the labels of all visible options in the dropdown.
+     * Opens the dropdown via focus if not already open.
+     *
+     * @returns Promise resolving to an array of option label strings.
+     *
+     * @example
+     * ```typescript
+     * const ac = await loader.getHarness(TnAutocompleteHarness);
+     * await ac.setInputValue('C');
+     * const options = await ac.getOptions();
+     * expect(options).toContain('Canada');
+     * ```
+     */
+    getOptions(): Promise<string[]>;
+    /**
+     * Selects an option by its label text. Opens the dropdown via focus if needed.
+     *
+     * @param filter The text to match against option labels. Supports string or RegExp.
+     * @returns Promise that resolves when the option has been selected.
+     * @throws Error if no matching option is found.
+     *
+     * @example
+     * ```typescript
+     * const ac = await loader.getHarness(TnAutocompleteHarness);
+     *
+     * // Select by exact text
+     * await ac.selectOption('Canada');
+     *
+     * // Select by regex
+     * await ac.selectOption(/united/i);
+     * ```
+     */
+    selectOption(filter: string | RegExp): Promise<void>;
+    /**
+     * Focuses the autocomplete input, which opens the dropdown.
+     *
+     * @returns Promise that resolves when the input is focused.
+     *
+     * @example
+     * ```typescript
+     * const ac = await loader.getHarness(TnAutocompleteHarness);
+     * await ac.focus();
+     * expect(await ac.isOpen()).toBe(true);
+     * ```
+     */
+    focus(): Promise<void>;
+    /**
+     * Blurs the autocomplete input, which closes the dropdown.
+     *
+     * @returns Promise that resolves when the input is blurred.
+     *
+     * @example
+     * ```typescript
+     * const ac = await loader.getHarness(TnAutocompleteHarness);
+     * await ac.focus();
+     * await ac.blur();
+     * expect(await ac.isOpen()).toBe(false);
+     * ```
+     */
+    blur(): Promise<void>;
+}
+/**
+ * A set of criteria that can be used to filter a list of `TnAutocompleteHarness` instances.
+ */
+interface AutocompleteHarnessFilters extends BaseHarnessFilters {
+    /** Filters by placeholder text. */
+    placeholder?: string;
+}
+
 declare enum DiskType {
     Hdd = "HDD",
     Ssd = "SSD"
@@ -4023,7 +4263,8 @@ interface TnThemeDefinition {
  *
  * Features:
  * - Signal-based reactive theme state
- * - LocalStorage persistence (key: 'tn-theme')
+ * - OS color scheme detection (prefers-color-scheme)
+ * - LocalStorage persistence for explicit user choices (key: 'tn-theme')
  * - Automatic CSS class application to document root
  * - SSR-safe (checks for browser platform)
  *
@@ -4043,9 +4284,12 @@ interface TnThemeDefinition {
  *     // Get current theme (signal)
  *     const currentTheme = this.themeService.currentTheme();
  *
- *     // Set theme using enum (recommended)
+ *     // Set theme using enum (recommended) — persists to localStorage
  *     this.themeService.setTheme(TnTheme.Blue);
  *
+ *     // Clear user preference and follow OS theme
+ *     this.themeService.clearPreference();
+ *
  *     // React to theme changes
  *     effect(() => {
  *       console.log('Theme changed to:', this.themeService.currentTheme()?.label);
@@ -4057,10 +4301,24 @@ interface TnThemeDefinition {
 declare class TnThemeService {
     private readonly platformId;
     private readonly isBrowser;
+    private readonly destroyRef;
     /**
      * Internal signal holding the current theme enum value
      */
     private readonly currentThemeSignal;
+    /**
+     * Whether the user has explicitly selected a theme (vs OS-detected default).
+     * When true, theme is persisted to localStorage and OS changes are ignored.
+     */
+    private readonly userSelected;
+    /**
+     * Reference to the prefers-color-scheme media query for cleanup
+     */
+    private colorSchemeQuery;
+    /**
+     * Bound listener reference for cleanup
+     */
+    private readonly colorSchemeListener;
     /**
      * Computed signal that returns the full theme definition for the current theme
      */
@@ -4069,6 +4327,10 @@ declare class TnThemeService {
      * Computed signal that returns the current theme's CSS class name
      */
     readonly currentThemeClass: _angular_core.Signal<string>;
+    /**
+     * Whether the current theme is based on OS preference (no explicit user choice)
+     */
+    readonly isUsingSystemTheme: _angular_core.Signal<boolean>;
     /**
      * All available theme definitions in the library (readonly array)
      */
@@ -4076,7 +4338,8 @@ declare class TnThemeService {
     constructor();
     /**
      * Set the current theme.
-     * Updates the signal, which triggers effects to apply CSS and save to localStorage.
+     * Marks this as an explicit user choice, persists to localStorage,
+     * and stops following OS color scheme changes.
      *
      * @param theme - The theme to set (use TnTheme enum)
      * @returns true if theme was found and set, false otherwise
@@ -4092,17 +4355,30 @@ declare class TnThemeService {
      */
     getCurrentTheme(): TnTheme;
     /**
-     * Reset theme to default
+     * Reset theme to default by clearing user preference and reverting to OS detection.
      */
     resetToDefault(): void;
+    /**
+     * Clear user preference and revert to OS-based theme detection.
+     * Removes the stored theme from localStorage and follows the OS color scheme.
+     */
+    clearPreference(): void;
     /**
      * Check if a theme exists
      */
     hasTheme(theme: TnTheme): boolean;
     /**
-     * Initialize theme from localStorage or use default
+     * Initialize theme from localStorage or OS color scheme preference
      */
     private initializeTheme;
+    /**
+     * Detect OS color scheme preference and apply corresponding theme
+     */
+    private applySystemTheme;
+    /**
+     * Listen for OS color scheme changes and apply them when no user preference is set
+     */
+    private listenForColorSchemeChanges;
     /**
      * Apply theme CSS class to document root.
      * Removes all other theme classes first to avoid conflicts.
@@ -4125,6 +4401,10 @@ declare class TnThemeService {
  * Default theme used when no theme is set
  */
 declare const DEFAULT_THEME = TnTheme.Dark;
+/**
+ * Light theme used when OS preference is light
+ */
+declare const LIGHT_THEME = TnTheme.Blue;
 /**
  * localStorage key for storing the current theme name
  */
@@ -4139,5 +4419,5 @@ declare const TN_THEME_DEFINITIONS: readonly TnThemeDefinition[];
  */
 declare const THEME_MAP: Map<TnTheme, TnThemeDefinition>;
 
-export { CommonShortcuts, DEFAULT_THEME, DiskIconComponent, DiskType, FileSizePipe, InputType, LinuxModifierKeys, LinuxShortcuts, ModifierKeys, QuickShortcuts, ShortcutBuilder, StripMntPrefixPipe, THEME_MAP, THEME_STORAGE_KEY, TN_THEME_DEFINITIONS, TnBannerActionDirective, TnBannerComponent, TnBannerHarness, TnBrandedSpinnerComponent, TnButtonComponent, TnButtonHarness, TnButtonToggleComponent, TnButtonToggleGroupComponent, TnCalendarComponent, TnCalendarHeaderComponent, TnCardComponent, TnCellDefDirective, TnCheckboxComponent, TnChipComponent, TnConfirmDialogComponent, TnDateInputComponent, TnDateRangeInputComponent, TnDialog, TnDialogHarness, TnDialogShellComponent, TnDialogTesting, TnDividerComponent, TnDividerDirective, TnEmptyComponent, TnEmptyHarness, TnExpansionPanelComponent, TnFilePickerComponent, TnFilePickerPopupComponent, TnFormFieldComponent, 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, TnMenuTriggerDirective, TnMonthViewComponent, TnMultiYearViewComponent, TnNestedTreeNodeComponent, TnParticleProgressBarComponent, TnProgressBarComponent, TnRadioComponent, TnSelectComponent, TnSelectHarness, TnSelectionListComponent, TnSidePanelActionDirective, TnSidePanelComponent, TnSidePanelHarness, TnSidePanelHeaderActionDirective, TnSlideToggleComponent, TnSliderComponent, TnSliderThumbDirective, TnSliderWithLabelDirective, TnSpinnerComponent, TnSpriteLoaderService, TnStepComponent, TnStepperComponent, TnTabComponent, TnTabHarness, TnTabPanelComponent, TnTabPanelHarness, TnTableColumnDirective, TnTableComponent, TnTabsComponent, TnTabsHarness, TnTheme, TnThemeService, TnTimeInputComponent, TnTooltipComponent, TnTooltipDirective, TnTreeComponent, TnTreeFlatDataSource, TnTreeFlattener, TnTreeNodeComponent, TnTreeNodeOutletDirective, TruncatePathPipe, WindowsModifierKeys, WindowsShortcuts, createLucideLibrary, createShortcut, defaultSpriteBasePath, defaultSpriteConfigPath, libIconMarker, registerLucideIcons, setupLucideIntegration, tnIconMarker };
-export type { BannerHarnessFilters, ButtonHarnessFilters, CalendarCell, ChipColor, CreateFolderEvent, DateRange, DialogHarnessFilters, EmptyHarnessFilters, FilePickerCallbacks, FilePickerError, FilePickerMode, FileSystemItem, IconButtonHarnessFilters, IconHarnessFilters, IconLibrary, IconLibraryType, IconResult, IconSize, IconSource, IconTestingMockOverrides, InputHarnessFilters, KeyCombination, LabelType, LucideIconOptions, MockIconRegistry, MockSpriteLoader, PathSegment, PlatformType, ProgressBarMode, ResolvedIcon, SelectHarnessFilters, ShortcutHandler, SidePanelHarnessFilters, SlideToggleColor, SpinnerMode, SpriteConfig, TabChangeEvent, TabHarnessFilters, TabPanelHarnessFilters, TabsHarnessFilters, TnBannerType, TnButtonToggleType, TnCardAction, TnCardControl, TnCardFooterLink, TnCardHeaderStatus, TnConfirmDialogData, TnDialogDefaults, TnDialogOpenTarget, TnEmptySize, TnFlatTreeNode, TnMenuItem, TnSelectOption, TnSelectOptionGroup, TnSelectionChange, TnTableDataSource, TnThemeDefinition, TooltipPosition, YearCell };
+export { CommonShortcuts, DEFAULT_THEME, DiskIconComponent, DiskType, FileSizePipe, InputType, LIGHT_THEME, LinuxModifierKeys, LinuxShortcuts, ModifierKeys, QuickShortcuts, ShortcutBuilder, StripMntPrefixPipe, THEME_MAP, THEME_STORAGE_KEY, TN_THEME_DEFINITIONS, TnAutocompleteComponent, TnAutocompleteHarness, TnBannerActionDirective, TnBannerComponent, TnBannerHarness, TnBrandedSpinnerComponent, TnButtonComponent, TnButtonHarness, TnButtonToggleComponent, TnButtonToggleGroupComponent, TnCalendarComponent, TnCalendarHeaderComponent, TnCardComponent, TnCellDefDirective, TnCheckboxComponent, TnChipComponent, TnConfirmDialogComponent, TnDateInputComponent, TnDateRangeInputComponent, TnDialog, TnDialogHarness, TnDialogShellComponent, TnDialogTesting, TnDividerComponent, TnDividerDirective, TnEmptyComponent, TnEmptyHarness, TnExpansionPanelComponent, TnFilePickerComponent, TnFilePickerPopupComponent, TnFormFieldComponent, 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, TnMenuTriggerDirective, TnMonthViewComponent, TnMultiYearViewComponent, TnNestedTreeNodeComponent, TnParticleProgressBarComponent, TnProgressBarComponent, TnRadioComponent, TnSelectComponent, TnSelectHarness, TnSelectionListComponent, TnSidePanelActionDirective, TnSidePanelComponent, TnSidePanelHarness, TnSidePanelHeaderActionDirective, TnSlideToggleComponent, TnSliderComponent, TnSliderThumbDirective, TnSliderWithLabelDirective, TnSpinnerComponent, TnSpriteLoaderService, TnStepComponent, TnStepperComponent, TnTabComponent, TnTabHarness, TnTabPanelComponent, TnTabPanelHarness, TnTableColumnDirective, TnTableComponent, TnTabsComponent, TnTabsHarness, TnTheme, TnThemeService, TnTimeInputComponent, TnTooltipComponent, TnTooltipDirective, TnTreeComponent, TnTreeFlatDataSource, TnTreeFlattener, TnTreeNodeComponent, TnTreeNodeOutletDirective, TruncatePathPipe, WindowsModifierKeys, WindowsShortcuts, createLucideLibrary, createShortcut, defaultSpriteBasePath, defaultSpriteConfigPath, libIconMarker, registerLucideIcons, setupLucideIntegration, tnIconMarker };
+export type { AutocompleteHarnessFilters, BannerHarnessFilters, ButtonHarnessFilters, CalendarCell, ChipColor, CreateFolderEvent, DateRange, DialogHarnessFilters, EmptyHarnessFilters, FilePickerCallbacks, FilePickerError, FilePickerMode, FileSystemItem, IconButtonHarnessFilters, IconHarnessFilters, IconLibrary, IconLibraryType, IconResult, IconSize, IconSource, IconTestingMockOverrides, InputHarnessFilters, KeyCombination, LabelType, LucideIconOptions, MockIconRegistry, MockSpriteLoader, PathSegment, PlatformType, ProgressBarMode, ResolvedIcon, SelectHarnessFilters, ShortcutHandler, SidePanelHarnessFilters, SlideToggleColor, SpinnerMode, SpriteConfig, TabChangeEvent, TabHarnessFilters, TabPanelHarnessFilters, TabsHarnessFilters, TnBannerType, TnButtonToggleType, TnCardAction, TnCardControl, TnCardFooterLink, TnCardHeaderStatus, TnConfirmDialogData, TnDialogDefaults, TnDialogOpenTarget, TnEmptySize, TnFlatTreeNode, TnMenuItem, TnSelectOption, TnSelectOptionGroup, TnSelectionChange, TnTableDataSource, TnThemeDefinition, TooltipPosition, YearCell };