@truenas/ui-components 0.1.59 → 0.1.60

package/package.json

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

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

@@ -1,5 +1,5 @@
 import * as _angular_core from '@angular/core';
-import { ElementRef, OnDestroy, AfterViewInit, AfterContentInit, TemplateRef, Provider, ChangeDetectorRef, OnInit, InjectionToken, Signal, PipeTransform, ViewContainerRef, AfterViewChecked, ComponentRef } from '@angular/core';
+import { ElementRef, OnDestroy, AfterViewInit, TemplateRef, AfterContentInit, Provider, ChangeDetectorRef, OnInit, InjectionToken, Signal, PipeTransform, ViewContainerRef, AfterViewChecked, ComponentRef } 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';
@@ -524,7 +524,7 @@ interface BannerHarnessFilters extends BaseHarnessFilters {
     textContains?: string | RegExp;
 }
 
-declare class TnButtonComponent {
+declare class TnButtonComponent implements AfterViewInit {
     size: string;
     primary: _angular_core.InputSignal<boolean>;
     color: _angular_core.InputSignal<"primary" | "secondary" | "warn" | "default">;
@@ -561,6 +561,9 @@ declare class TnButtonComponent {
     isRouterLink: _angular_core.Signal<boolean>;
     classes: _angular_core.Signal<string[]>;
     handleAnchorClick(event: MouseEvent): void;
+    private hostRef;
+    private innerRef;
+    ngAfterViewInit(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnButtonComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnButtonComponent, "tn-button", never, { "primary": { "alias": "primary"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "backgroundColor": { "alias": "backgroundColor"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; "href": { "alias": "href"; "required": false; "isSignal": true; }; "routerLink": { "alias": "routerLink"; "required": false; "isSignal": true; }; "queryParams": { "alias": "queryParams"; "required": false; "isSignal": true; }; "fragment": { "alias": "fragment"; "required": false; "isSignal": true; }; "target": { "alias": "target"; "required": false; "isSignal": true; }; "rel": { "alias": "rel"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, { "onClick": "onClick"; }, never, never, true, never>;
 }
@@ -714,7 +717,7 @@ declare class TnIconComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnIconComponent, "tn-icon", never, { "name": { "alias": "name"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "tooltip": { "alias": "tooltip"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "library": { "alias": "library"; "required": false; "isSignal": true; }; "fullSize": { "alias": "fullSize"; "required": false; "isSignal": true; }; "customSize": { "alias": "customSize"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-declare class TnIconButtonComponent {
+declare class TnIconButtonComponent implements AfterViewInit {
     disabled: _angular_core.InputSignal<boolean>;
     ariaLabel: _angular_core.InputSignal<string | undefined>;
     /**
@@ -728,8 +731,17 @@ declare class TnIconButtonComponent {
     tooltip: _angular_core.InputSignal<string | undefined>;
     library: _angular_core.InputSignal<IconLibraryType | undefined>;
     onClick: _angular_core.OutputEmitterRef<MouseEvent>;
+    private hostRef;
+    private buttonRef;
     classes: _angular_core.Signal<string[]>;
     effectiveAriaLabel: _angular_core.Signal<string>;
+    /**
+     * Focuses the inner native `<button>`. Exposed as a public method so callers
+     * with a `TnIconButtonComponent` reference (e.g. `@ViewChild`) can focus it
+     * without reaching into the DOM themselves.
+     */
+    focus(options?: FocusOptions): void;
+    ngAfterViewInit(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnIconButtonComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnIconButtonComponent, "tn-icon-button", never, { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "tooltip": { "alias": "tooltip"; "required": false; "isSignal": true; }; "library": { "alias": "library"; "required": false; "isSignal": true; }; }, { "onClick": "onClick"; }, never, never, true, never>;
 }
@@ -1298,6 +1310,68 @@ interface TnCardFooterLink {
     testId?: string;
 }
 
+/**
+ * Projection-based menu item for use inside `<tn-menu>`.
+ *
+ * Two authoring modes:
+ * 1. **Convenience** — set `label` (and optionally `icon`/`shortcut`); the
+ *    default icon + label + shortcut layout renders.
+ * 2. **Custom content** — omit `label`; project arbitrary content via
+ *    `<ng-content>` (badges, two-line layouts, etc.).
+ *
+ * Existing `<tn-menu [items]="...">` consumers don't need this component;
+ * the items-array API continues to work unchanged. Items-array entries and
+ * projected `<tn-menu-item>` children render together inside one `<tn-menu>`,
+ * share keyboard navigation, and look identical.
+ *
+ * **How it works:** the component itself renders nothing visible — it acts as
+ * a configuration declaration. The parent `<tn-menu>` collects projected items
+ * via `contentChildren`, re-renders them inside the CDK overlay alongside
+ * items-array entries (with `cdkMenuItem` for full arrow-key navigation), and
+ * routes clicks back to each item's `itemClick` output.
+ *
+ * **Accessibility:** because items are re-rendered inside the parent's
+ * `CdkMenu`, all keyboard semantics from `@angular/cdk/menu` apply uniformly:
+ * Arrow Up/Down/Home/End to move focus, Enter/Space to activate, Esc to
+ * close, type-ahead search. Disabled items are skipped.
+ *
+ * **Limitation — custom content & keyboard nav:** the projected
+ * `<ng-content>` (custom-content mode) is rendered inside a `<button
+ * cdkMenuItem>` wrapper that owns Enter/Space/Arrow handling. Interactive
+ * elements inside the projection (a nested `<button>`, link, toggle, etc.)
+ * receive clicks but **do not** participate in CDK arrow-key navigation —
+ * the wrapper button is the only keyboard-reachable target. Prefer
+ * display-only content (icons, badges, two-line text); for cases that need
+ * an extra interactive control, build a custom menu host with `cdkMenu`
+ * directly instead of `<tn-menu>`.
+ *
+ * @example
+ * ```html
+ * <tn-menu>
+ *   <tn-menu-item label="JSON" [selected]="format === 'json'"
+ *                 (itemClick)="setFormat('json')" />
+ *   <tn-menu-item label="CSV"  [selected]="format === 'csv'"
+ *                 (itemClick)="setFormat('csv')" />
+ * </tn-menu>
+ * ```
+ */
+declare class TnMenuItemComponent {
+    id: _angular_core.InputSignal<string | undefined>;
+    label: _angular_core.InputSignal<string | undefined>;
+    icon: _angular_core.InputSignal<string | undefined>;
+    iconLibrary: _angular_core.InputSignal<"material" | "mdi" | "custom" | "lucide" | undefined>;
+    shortcut: _angular_core.InputSignal<string | undefined>;
+    disabled: _angular_core.InputSignal<boolean>;
+    selected: _angular_core.InputSignal<boolean>;
+    testId: _angular_core.InputSignal<string | undefined>;
+    itemClick: _angular_core.OutputEmitterRef<MouseEvent>;
+    /** Template capturing whatever the consumer projected as item content. */
+    content: _angular_core.Signal<TemplateRef<unknown>>;
+    resolvedTestId: _angular_core.Signal<string | undefined>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnMenuItemComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnMenuItemComponent, "tn-menu-item", never, { "id": { "alias": "id"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "iconLibrary": { "alias": "iconLibrary"; "required": false; "isSignal": true; }; "shortcut": { "alias": "shortcut"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "selected": { "alias": "selected"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; }, { "itemClick": "itemClick"; }, never, ["*"], true, never>;
+}
+
 /**
  * Activates CDK menu hover-to-open behavior for menus opened via custom overlays.
  *
@@ -1335,7 +1409,7 @@ interface TnMenuItem {
      */
     selected?: boolean;
 }
-declare class TnMenuComponent {
+declare class TnMenuComponent implements OnDestroy {
     items: _angular_core.InputSignal<TnMenuItem[]>;
     contextMenu: _angular_core.InputSignal<boolean>;
     menuItemClick: _angular_core.OutputEmitterRef<TnMenuItem>;
@@ -1344,11 +1418,17 @@ declare class TnMenuComponent {
     menuTemplate: _angular_core.Signal<TemplateRef<unknown>>;
     contextMenuTemplate: _angular_core.Signal<TemplateRef<unknown>>;
     private contextOverlayRef?;
+    private contextBackdropSub?;
     private overlay;
     private viewContainerRef;
     onMenuItemClick(item: TnMenuItem): void;
-    private contentItems;
-    constructor();
+    contentItems: _angular_core.Signal<readonly TnMenuItemComponent[]>;
+    /**
+     * Click handler for projected `<tn-menu-item>` entries. Emits the item's own
+     * `itemClick` output, re-emits a synthetic entry on `menuItemClick` so
+     * trigger-driven menus close uniformly, and closes any open context menu.
+     */
+    onProjectedItemClick(item: TnMenuItemComponent, event: MouseEvent): void;
     hasChildren: _angular_core.Signal<(item: TnMenuItem) => boolean>;
     onMenuOpen(): void;
     onMenuClose(): void;
@@ -1358,10 +1438,11 @@ declare class TnMenuComponent {
     getMenuTemplate(): TemplateRef<unknown> | null;
     openContextMenuAt(x: number, y: number): void;
     private closeContextMenu;
+    ngOnDestroy(): void;
     onContextMenu(event: MouseEvent): void;
     trackByItemId(index: number, item: TnMenuItem): string;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnMenuComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnMenuComponent, "tn-menu", never, { "items": { "alias": "items"; "required": false; "isSignal": true; }; "contextMenu": { "alias": "contextMenu"; "required": false; "isSignal": true; }; }, { "menuItemClick": "menuItemClick"; "menuOpen": "menuOpen"; "menuClose": "menuClose"; }, ["contentItems"], ["*", "tn-menu-item, .tn-menu-separator"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnMenuComponent, "tn-menu", never, { "items": { "alias": "items"; "required": false; "isSignal": true; }; "contextMenu": { "alias": "contextMenu"; "required": false; "isSignal": true; }; }, { "menuItemClick": "menuItemClick"; "menuOpen": "menuOpen"; "menuClose": "menuClose"; }, ["contentItems"], ["*"], true, never>;
 }
 
 declare class TnCardComponent {
@@ -1394,6 +1475,7 @@ declare class TnCardComponent {
     private registerMdiIcons;
     classes: _angular_core.Signal<string[]>;
     hasHeader: _angular_core.Signal<boolean>;
+    hasHeaderRight: _angular_core.Signal<boolean>;
     hasFooter: _angular_core.Signal<boolean>;
     onTitleClick(): void;
     onControlChange(checked: boolean): void;
@@ -2475,71 +2557,48 @@ interface TabsHarnessFilters extends BaseHarnessFilters {
     hasTab?: string | RegExp;
 }
 
-/**
- * Projection-based menu item for use inside `<tn-menu>`.
- *
- * Two authoring modes:
- * 1. **Convenience** — set `label` (and optionally `icon`/`shortcut`); the
- *    default icon + label + shortcut layout renders.
- * 2. **Custom content** — omit `label`; project arbitrary content via
- *    `<ng-content>` (badges, two-line layouts, etc.).
- *
- * Existing `<tn-menu [items]="...">` consumers don't need this component;
- * the items-array API continues to work unchanged. Items-array entries and
- * projected `<tn-menu-item>` children render together inside one `<tn-menu>`.
- *
- * Subscribe to either the projected item's own `itemClick` output (preferred,
- * per-item handlers) or the parent menu's `menuItemClick` (uniform handler).
- * Trigger-driven menus close automatically on projected-item click.
- *
- * **Note on keyboard navigation:** projected items render as `role="menuitem"`
- * buttons but do not participate in `CdkMenu` arrow-key navigation (CdkMenuItem
- * requires its parent `CdkMenu` in the same injector tree, which projection
- * breaks). For menus that depend on arrow-key navigation between options, use
- * the `items` input form. Tab/Shift+Tab and Enter/Space activation still work.
- *
- * @example
- * ```html
- * <tn-menu>
- *   <tn-menu-item label="JSON" [selected]="format === 'json'"
- *                 (itemClick)="setFormat('json')" />
- *   <tn-menu-item label="CSV"  [selected]="format === 'csv'"
- *                 (itemClick)="setFormat('csv')" />
- * </tn-menu>
- * ```
- */
-declare class TnMenuItemComponent {
-    id: _angular_core.InputSignal<string | undefined>;
-    label: _angular_core.InputSignal<string | undefined>;
-    icon: _angular_core.InputSignal<string | undefined>;
-    iconLibrary: _angular_core.InputSignal<"material" | "mdi" | "custom" | "lucide" | undefined>;
-    shortcut: _angular_core.InputSignal<string | undefined>;
-    disabled: _angular_core.InputSignal<boolean>;
-    selected: _angular_core.InputSignal<boolean>;
-    testId: _angular_core.InputSignal<string | undefined>;
-    itemClick: _angular_core.OutputEmitterRef<MouseEvent>;
-    resolvedTestId: _angular_core.Signal<string | undefined>;
-    handleClick(event: MouseEvent): void;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnMenuItemComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnMenuItemComponent, "tn-menu-item", never, { "id": { "alias": "id"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "iconLibrary": { "alias": "iconLibrary"; "required": false; "isSignal": true; }; "shortcut": { "alias": "shortcut"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "selected": { "alias": "selected"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; }, { "itemClick": "itemClick"; }, never, ["*"], true, never>;
-}
-
 /**
  * Directive that attaches a menu to any element.
  * Usage: <button [tnMenuTriggerFor]="menu">Open Menu</button>
  */
-declare class TnMenuTriggerDirective {
+declare class TnMenuTriggerDirective implements OnDestroy {
     menu: _angular_core.InputSignal<TnMenuComponent>;
     tnMenuPosition: _angular_core.InputSignal<"after" | "before" | "above" | "below">;
     private overlayRef?;
     private isMenuOpen;
     private itemClickSub?;
+    /**
+     * RxJS subscriptions for the current overlay's `backdropClick()` and
+     * `keydownEvents()`. Each `openMenu()` creates a fresh overlay (and fresh
+     * subscriptions), so we collect them here and tear them down in `closeMenu`
+     * / `ngOnDestroy` to keep open→close cycles leak-free.
+     */
+    private overlaySubs;
     private elementRef;
     private overlay;
     private viewContainerRef;
     onClick(): void;
+    onArrowDown(event: Event): void;
     openMenu(): void;
     closeMenu(): void;
+    ngOnDestroy(): void;
+    private disposeOverlaySubs;
+    /**
+     * Return focus to the trigger element so keyboard users land somewhere
+     * sensible after the menu closes (Escape, item click, or backdrop click).
+     *
+     * The host might be a custom-element wrapper like `<tn-button>` /
+     * `<tn-icon-button>` whose host element isn't itself focusable — focus
+     * lives on the inner `<button>` or `<a>`. We focus the host if it's
+     * focusable; otherwise we drill into the first focusable descendant.
+     *
+     * Passes `focusVisible: true` (Chrome/Firefox) so the `:focus-visible`
+     * outline reappears on the restored trigger — without it, browsers treat a
+     * programmatic `.focus()` as non-keyboard and skip the focus ring, which
+     * looks to users like focus has been lost. Safari ignores the option and
+     * falls back to its heuristic; that's acceptable.
+     */
+    private restoreFocusToTrigger;
     private getPositions;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnMenuTriggerDirective, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TnMenuTriggerDirective, "[tnMenuTriggerFor]", ["tnMenuTrigger"], { "menu": { "alias": "tnMenuTriggerFor"; "required": true; "isSignal": true; }; "tnMenuPosition": { "alias": "tnMenuPosition"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
@@ -2929,7 +2988,7 @@ interface TnSelectOptionGroup<T = unknown> {
     options: TnSelectOption<T>[];
     disabled?: boolean;
 }
-declare class TnSelectComponent<T = unknown> implements ControlValueAccessor {
+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>;
@@ -2956,6 +3015,11 @@ declare class TnSelectComponent<T = unknown> implements ControlValueAccessor {
      * 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>;
     selectionChange: _angular_core.OutputEmitterRef<T>;
@@ -2968,103 +3032,115 @@ declare class TnSelectComponent<T = unknown> implements ControlValueAccessor {
     /** Index into `flatOptions` of the keyboard-focused row (-1 when none). */
     protected focusedIndex: _angular_core.WritableSignal<number>;
     private formDisabled;
-    private static readonly DROPDOWN_MAX_HEIGHT_VAR;
-    private static readonly DROPDOWN_MAX_HEIGHT_FALLBACK;
-    private readonly fallbackId;
-    protected uniqueId: _angular_core.Signal<string>;
-    isDisabled: _angular_core.Signal<boolean>;
+    private static instanceCounter;
+    private instanceId;
     /**
-     * Flattened option list (ungrouped + grouped, in render order). The keyboard
-     * navigation walks this list — entries from disabled groups are kept but
-     * marked disabled so the cursor skips over them correctly.
+     * 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 flatOptions: _angular_core.Signal<TnSelectOption<T>[]>;
+    protected idNamespace: _angular_core.Signal<string>;
+    isDisabled: _angular_core.Signal<boolean>;
     /**
-     * Starting flat-index of each option group, used by the template to
-     * translate a (group, option) pair into the matching `flatOptions` index.
+     * 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.
      */
-    protected groupOffsets: _angular_core.Signal<number[]>;
-    /** `aria-activedescendant` id for the focused option (or null). */
-    protected activeOptionId: _angular_core.Signal<string | null>;
+    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;
     private onChange;
     private onTouched;
     private elementRef;
     private cdr;
-    protected triggerEl: _angular_core.Signal<ElementRef<HTMLElement> | undefined>;
-    constructor();
+    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;
     /**
-     * Open the dropdown, seed the keyboard cursor on the currently-selected
-     * option (or the first focusable one), and decide whether to flip up.
-     */
-    private openDropdown;
-    /**
-     * Close the dropdown.
+     * Attach the dropdown panel as a CDK overlay anchored to the trigger.
      *
-     * @param restoreFocus When `true` (default), return focus to the trigger so
-     *   keyboard users land somewhere sensible. Pass `false` for click-outside
-     *   so we don't steal focus from the element the user just navigated to.
+     * 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.
      */
-    closeDropdown(options?: {
-        restoreFocus?: boolean;
-    }): void;
-    /** Picks the initial focused-row index when the dropdown opens. */
-    private initialFocusIndex;
-    /**
-     * Decide whether the dropdown should open above or below the trigger.
-     * Opens above when there isn't enough space below the trigger AND there is
-     * more space above — otherwise stays below. Falls back to `'below'` when no
-     * trigger element is found yet.
-     */
-    private computeDropdownPosition;
+    private attachOverlay;
+    private detachOverlay;
+    ngOnDestroy(): void;
     /**
-     * Reads the dropdown's max-height from the CSS custom property set in
-     * select.component.scss. Single source of truth for the flip-up threshold —
-     * if the stylesheet changes, the heuristic follows automatically.
+     * 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.
      */
-    private readDropdownMaxHeight;
+    closeDropdown(restoreFocus?: boolean): void;
     onOptionClick(option: TnSelectOption<T>, groupDisabled?: boolean): void;
     selectOption(option: TnSelectOption<T>): void;
     private toggleOption;
     isOptionSelected(option: TnSelectOption<T>): boolean;
-    /** Build a stable DOM id for the option at `index` for aria-activedescendant. */
-    protected optionId(index: number): string;
     protected displayText: _angular_core.Signal<string>;
     private findOptionByValue;
-    protected anyOptionsPresent: _angular_core.Signal<boolean>;
+    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` if provided,
-     * otherwise identity (`===`). For object values it falls back to
-     * `JSON.stringify`, which is key-order dependent — consumers with object
-     * values should provide `compareWith` to avoid subtle bugs.
+     * 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 handling on the trigger (focus stays on the trigger while the
-     * dropdown is open — options use mousedown-preventDefault to avoid stealing
-     * it). Implements the WAI-ARIA combobox pattern subset we need:
+     * Keyboard navigation for the combobox trigger.
      *
-     * - **Enter / Space**: open closed dropdown, or select the focused row
-     *   (toggle in multi-mode).
-     * - **ArrowDown / ArrowUp**: move the focused row; opens the dropdown first
-     *   if it's closed.
-     * - **Home / End**: jump to first / last focusable row (when open).
-     * - **Escape**: close and restore focus to the trigger.
-     * - **Tab**: close without preventing default so focus moves to the next
-     *   element naturally.
+     * - **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;
-    /** Step the focused row by ±1 (or more), skipping disabled options. */
     private moveFocus;
-    /** Move focus to a specific index, scanning forward/backward to skip disabled. */
-    private moveFocusTo;
-    /** Select (or toggle, in multi-mode) the currently keyboard-focused row. */
-    private selectFocused;
-    /** Scrolls the keyboard-focused option into view if it's outside the dropdown's viewport. */
+    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; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; }, { "selectionChange": "selectionChange"; "multiSelectionChange": "multiSelectionChange"; }, never, never, true, never>;
@@ -3869,8 +3945,49 @@ declare class TnTableComponent<T = unknown> implements OnInit {
     selectable: _angular_core.InputSignal<boolean>;
     expandable: _angular_core.InputSignal<boolean>;
     bordered: _angular_core.InputSignal<boolean>;
+    /**
+     * Marks a single row as "active" — adds the `tn-table__row--active` class
+     * and a left-side indicator bar. Set to `null` (default) to clear.
+     *
+     * **Matched by object identity (`===`)** against the row references in
+     * `dataSource`. Pass the exact reference you got from the data source (e.g.
+     * via the `rowClick` event or a lookup into `dataSource()`), not a
+     * structurally-equal copy — `{ id: 1 } !== { id: 1 }` and the row will not
+     * highlight. This differs from `tn-select`, which supports a `compareWith`
+     * input for object values; the table intentionally does not, because the
+     * common use case (clicking a row to mark it active) already gives the
+     * caller the original reference. If you need structural equality, look up
+     * the row by id in your data source before assigning here.
+     */
+    activeRow: _angular_core.InputSignal<T | null>;
+    /**
+     * Overrides the active-row background color. Accepts any CSS color value
+     * (`#hex`, `rgb()`, `var(--token)`). Defaults to `--tn-bg3` when null.
+     */
+    activeBg: _angular_core.InputSignal<string | null>;
+    /**
+     * Overrides the left-side active-row indicator color. Defaults to
+     * `--tn-primary` when null.
+     */
+    activeIndicator: _angular_core.InputSignal<string | null>;
+    /**
+     * When true, shows a spinner overlay over the table. Existing rows remain
+     * visible (dimmed) so reloads don't cause layout jumps; if there are no rows
+     * yet, the spinner replaces the empty state.
+     */
+    loading: _angular_core.InputSignal<boolean>;
+    /** Accessible label announced while loading. */
+    loadingMessage: _angular_core.InputSignal<string>;
+    /**
+     * When true, rows become keyboard-focusable (tabindex=0) and clicking or
+     * pressing Enter/Space emits `rowClick`. Use this for "click row to view
+     * details" patterns. Independent of `selectable` (checkbox) and `expandable`.
+     */
+    clickable: _angular_core.InputSignal<boolean>;
     sortChange: _angular_core.OutputEmitterRef<TnSortEvent>;
     selectionChange: _angular_core.OutputEmitterRef<T[]>;
+    /** Emits the row when a clickable row is activated (click or Enter/Space). */
+    rowClick: _angular_core.OutputEmitterRef<T>;
     columnDefs: _angular_core.Signal<readonly TnTableColumnDirective[]>;
     detailRowDef: _angular_core.Signal<TnDetailRowDefDirective | undefined>;
     sortColumn: _angular_core.WritableSignal<string>;
@@ -3899,13 +4016,16 @@ declare class TnTableComponent<T = unknown> implements OnInit {
     isSorted(column: string): boolean;
     toggleRowExpansion(row: T): void;
     isRowExpanded(row: T): boolean;
+    isRowActive(row: T): boolean;
+    onRowClick(row: T): void;
+    onRowKeydown(event: KeyboardEvent, row: T): void;
     toggleSelectAll(): void;
     toggleRowSelection(row: T): void;
     isRowSelected(row: T): boolean;
     getColumnDef(columnName: string): TnTableColumnDirective | undefined;
     getCellValue(row: T, column: string): unknown;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnTableComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnTableComponent<any>, "tn-table", never, { "dataSource": { "alias": "dataSource"; "required": false; "isSignal": true; }; "displayedColumns": { "alias": "displayedColumns"; "required": false; "isSignal": true; }; "trackBy": { "alias": "trackBy"; "required": false; "isSignal": true; }; "emptyMessage": { "alias": "emptyMessage"; "required": false; "isSignal": true; }; "emptyIcon": { "alias": "emptyIcon"; "required": false; "isSignal": true; }; "selectable": { "alias": "selectable"; "required": false; "isSignal": true; }; "expandable": { "alias": "expandable"; "required": false; "isSignal": true; }; "bordered": { "alias": "bordered"; "required": false; "isSignal": true; }; }, { "sortChange": "sortChange"; "selectionChange": "selectionChange"; }, ["columnDefs", "detailRowDef"], never, true, [{ directive: typeof TnTestIdDirective; inputs: { "tnTestId": "testId"; }; outputs: {}; }]>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnTableComponent<any>, "tn-table", never, { "dataSource": { "alias": "dataSource"; "required": false; "isSignal": true; }; "displayedColumns": { "alias": "displayedColumns"; "required": false; "isSignal": true; }; "trackBy": { "alias": "trackBy"; "required": false; "isSignal": true; }; "emptyMessage": { "alias": "emptyMessage"; "required": false; "isSignal": true; }; "emptyIcon": { "alias": "emptyIcon"; "required": false; "isSignal": true; }; "selectable": { "alias": "selectable"; "required": false; "isSignal": true; }; "expandable": { "alias": "expandable"; "required": false; "isSignal": true; }; "bordered": { "alias": "bordered"; "required": false; "isSignal": true; }; "activeRow": { "alias": "activeRow"; "required": false; "isSignal": true; }; "activeBg": { "alias": "activeBg"; "required": false; "isSignal": true; }; "activeIndicator": { "alias": "activeIndicator"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "loadingMessage": { "alias": "loadingMessage"; "required": false; "isSignal": true; }; "clickable": { "alias": "clickable"; "required": false; "isSignal": true; }; }, { "sortChange": "sortChange"; "selectionChange": "selectionChange"; "rowClick": "rowClick"; }, ["columnDefs", "detailRowDef"], never, true, [{ directive: typeof TnTestIdDirective; inputs: { "tnTestId": "testId"; }; outputs: {}; }]>;
 }
 
 /**
@@ -4023,6 +4143,44 @@ declare class TnTableHarness extends ComponentHarness {
      * @returns Promise resolving to true if the row has the expanded class.
      */
     isRowExpanded(rowIndex: number): Promise<boolean>;
+    /**
+     * Clicks a row (for tables with `clickable` enabled).
+     *
+     * @param rowIndex Zero-based index of the data row.
+     */
+    clickRow(rowIndex: number): Promise<void>;
+    /**
+     * Sends a keyboard event to a row (Enter/Space activate clickable rows).
+     *
+     * @param rowIndex Zero-based index of the data row.
+     * @param key Which key to press — Enter or Space.
+     */
+    pressKeyOnRow(rowIndex: number, key: 'enter' | 'space'): Promise<void>;
+    /**
+     * Checks if a row is keyboard-focusable (tabindex=0).
+     *
+     * @param rowIndex Zero-based index of the data row.
+     */
+    isRowFocusable(rowIndex: number): Promise<boolean>;
+    /**
+     * Checks whether the table is currently in the loading state.
+     *
+     * @returns Promise resolving to true if the loading overlay is visible.
+     */
+    isLoading(): Promise<boolean>;
+    /**
+     * Checks if a data row is currently marked active.
+     *
+     * @param rowIndex Zero-based index of the data row.
+     * @returns Promise resolving to true if the row has the active class.
+     */
+    isRowActive(rowIndex: number): Promise<boolean>;
+    /**
+     * Gets the index of the currently active row, or null if none is active.
+     *
+     * @returns Promise resolving to the active row index or null.
+     */
+    getActiveRowIndex(): Promise<number | null>;
     /**
      * Gets the text content of an expanded detail row.
      *
@@ -5272,6 +5430,22 @@ declare class TnButtonToggleGroupComponent implements ControlValueAccessor {
     name: _angular_core.InputSignal<string>;
     ariaLabel: _angular_core.InputSignal<string>;
     ariaLabelledby: _angular_core.InputSignal<string>;
+    /**
+     * Overrides the background color of checked toggles in this group. Accepts
+     * any CSS color value (`#hex`, `rgb()`, `var(--token)`, etc.). When null
+     * (default), falls back to `--tn-alt-bg2`.
+     */
+    checkedBg: _angular_core.InputSignal<string | null>;
+    /**
+     * Overrides the text color of checked toggles in this group. Defaults to
+     * `--tn-fg1` when null.
+     */
+    checkedColor: _angular_core.InputSignal<string | null>;
+    /**
+     * Overrides the border color of checked toggles in this group. Defaults to
+     * `--tn-lines` when null.
+     */
+    checkedBorder: _angular_core.InputSignal<string | null>;
     /**
      * Test-id applied to the group root. Rendered under whichever attribute name
      * is configured via `TN_TEST_ATTR` (default `data-testid`).
@@ -5298,7 +5472,7 @@ declare class TnButtonToggleGroupComponent implements ControlValueAccessor {
     private updateTogglesFromValue;
     private updateTogglesFromValues;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnButtonToggleGroupComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnButtonToggleGroupComponent, "tn-button-toggle-group", never, { "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "ariaLabelledby": { "alias": "ariaLabelledby"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; }, { "change": "change"; }, ["buttonToggles"], ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnButtonToggleGroupComponent, "tn-button-toggle-group", never, { "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "ariaLabelledby": { "alias": "ariaLabelledby"; "required": false; "isSignal": true; }; "checkedBg": { "alias": "checkedBg"; "required": false; "isSignal": true; }; "checkedColor": { "alias": "checkedColor"; "required": false; "isSignal": true; }; "checkedBorder": { "alias": "checkedBorder"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; }, { "change": "change"; }, ["buttonToggles"], ["*"], true, never>;
 }
 
 declare class TnButtonToggleComponent implements ControlValueAccessor {