@truenas/ui-components 0.3.20 → 0.3.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truenas/ui-components",
-  "version": "0.3.20",
+  "version": "0.3.21",
   "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 { Signal, InjectionToken, Renderer2, OnDestroy, ElementRef, AfterViewInit, OnInit, TemplateRef, AfterContentInit, Provider, ChangeDetectorRef, PipeTransform, ViewContainerRef, AfterViewChecked, ComponentRef } from '@angular/core';
+import { Signal, InjectionToken, Renderer2, OnDestroy, ElementRef, AfterViewInit, OnInit, TemplateRef, AfterContentInit, Provider, ChangeDetectorRef, TrackByFunction, OnChanges, DoCheck, SimpleChanges, PipeTransform, ViewContainerRef, AfterViewChecked, ComponentRef } from '@angular/core';
 import { ControlValueAccessor, NgControl, AbstractControl } from '@angular/forms';
 import { ComponentHarness, BaseHarnessFilters, HarnessPredicate, TestKey, HarnessLoader } from '@angular/cdk/testing';
 import { SafeHtml, SafeResourceUrl, DomSanitizer } from '@angular/platform-browser';
@@ -7,10 +7,11 @@ import { ComponentFixture } from '@angular/core/testing';
 import * as _truenas_ui_components from '@truenas/ui-components';
 import { SelectionModel, DataSource } from '@angular/cdk/collections';
 import * as rxjs from 'rxjs';
-import { Observable } from 'rxjs';
+import { Observable, BehaviorSubject } from 'rxjs';
 import * as i1 from '@angular/cdk/tree';
-import { CdkTree, FlatTreeControl, CdkTreeNode, CdkNestedTreeNode } from '@angular/cdk/tree';
+import { CdkTree, FlatTreeControl, CdkTreeNode, CdkNestedTreeNode, CdkTreeNodeOutletContext, CdkTreeNodeDef } from '@angular/cdk/tree';
 export { FlatTreeControl } from '@angular/cdk/tree';
+import { CdkVirtualScrollViewport } from '@angular/cdk/scrolling';
 import { Overlay } from '@angular/cdk/overlay';
 import { DialogRef, DialogConfig } from '@angular/cdk/dialog';
 import { ComponentType } from '@angular/cdk/portal';
@@ -210,6 +211,19 @@ interface TnSelectOptionGroup<T = unknown> {
     options: TnSelectOption<T>[];
     disabled?: boolean;
 }
+/**
+ * A keyboard-navigable row in the open dropdown. Either the synthetic
+ * "select all" action (multiple mode with `showSelectAll`) or a real option.
+ * Both carry the stable DOM `id` used for `aria-activedescendant`.
+ */
+type TnSelectNavEntry<T> = {
+    kind: 'select-all';
+    id: string;
+} | {
+    kind: 'option';
+    option: TnSelectOption<T>;
+    id: string;
+};
 declare class TnSelectComponent<T = unknown> implements ControlValueAccessor, OnDestroy {
     options: _angular_core.InputSignal<TnSelectOption<T>[]>;
     optionGroups: _angular_core.InputSignal<TnSelectOptionGroup<T>[]>;
@@ -239,6 +253,16 @@ declare class TnSelectComponent<T = unknown> implements ControlValueAccessor, On
     /** Label of the empty option rendered when `allowEmpty` is set. */
     emptyLabel: _angular_core.InputSignal<string>;
     disabled: _angular_core.InputSignal<boolean>;
+    /**
+     * When `true` (multiple mode only), renders a "select all" row at the top of
+     * the dropdown that toggles every selectable (non-disabled) option on/off in
+     * one click. Mirrors webui ix-select's `[showSelectAll]`. Ignored in single
+     * mode. Its checkbox reflects the aggregate state: checked when all are
+     * selected, indeterminate when only some are.
+     */
+    showSelectAll: _angular_core.InputSignal<boolean>;
+    /** Label of the select-all row rendered when `showSelectAll` is set. */
+    selectAllLabel: _angular_core.InputSignal<string>;
     testId: _angular_core.InputSignal<TnTestIdValue>;
     /** Test-id base, falling back to the bound control name when `testId` is unset. */
     protected resolvedTestId: _angular_core.Signal<TnTestIdValue>;
@@ -310,10 +334,7 @@ declare class TnSelectComponent<T = unknown> implements ControlValueAccessor, On
      * 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;
-    }[]>;
+    navigableOptions: _angular_core.Signal<TnSelectNavEntry<T>[]>;
     /** 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. */
@@ -383,6 +404,39 @@ declare class TnSelectComponent<T = unknown> implements ControlValueAccessor, On
     protected displayText: _angular_core.Signal<string>;
     private findOptionByValue;
     protected hasAnyOptions: _angular_core.Signal<boolean>;
+    /**
+     * Values of every selectable (non-disabled) option, across ungrouped options
+     * and enabled groups. This is the set the select-all row operates on —
+     * disabled options and options in disabled groups are excluded because they
+     * can't be toggled individually either.
+     *
+     * Values are deduped with `compareValues` so a value that appears both
+     * ungrouped and inside a group isn't pushed twice — that would make
+     * select-all diverge from `toggleOption()`, which never produces duplicates.
+     */
+    protected selectableValues: _angular_core.Signal<T[]>;
+    /** Whether the select-all row is shown (multiple mode, opted in, with options). */
+    protected showSelectAllRow: _angular_core.Signal<boolean>;
+    /** Stable DOM id of the select-all row, for aria-activedescendant. */
+    protected selectAllId: _angular_core.Signal<string>;
+    /** True when every selectable option is currently selected. */
+    protected allSelected: _angular_core.Signal<boolean>;
+    /** True when some — but not all — selectable options are selected. */
+    protected selectAllIndeterminate: _angular_core.Signal<boolean>;
+    /** Test-id segments for the select-all row; mirrors ix-select's `[name, 'select-all']`. */
+    protected selectAllTestIdParts(): (string | number | null | undefined)[];
+    /**
+     * Toggles every selectable option: clears them all when they're all already
+     * selected, otherwise selects them all. Preserves the multi-select "open"
+     * behaviour — the dropdown stays open so the user can keep adjusting.
+     *
+     * Disabled-but-selected values (e.g. a disabled option pre-selected via
+     * `writeValue`) are preserved on both paths: the user can't toggle those
+     * rows individually, so select-all must not silently discard them either.
+     */
+    protected toggleSelectAll(): void;
+    /** Whether the select-all row is the keyboard-highlighted item. */
+    protected isSelectAllFocused(): boolean;
     /** One-shot guard so the object-compare warning fires at most once per instance. */
     private warnedAboutObjectCompare;
     /**
@@ -422,7 +476,7 @@ declare class TnSelectComponent<T = unknown> implements ControlValueAccessor, On
     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>;
+    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; }; "showSelectAll": { "alias": "showSelectAll"; "required": false; "isSignal": true; }; "selectAllLabel": { "alias": "selectAllLabel"; "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>;
 }
 
 /**
@@ -5031,6 +5085,27 @@ declare class TnSelectHarness extends ComponentHarness {
      * ```
      */
     getOptions(): Promise<string[]>;
+    /**
+     * Toggles the select-all row (multiple mode with `showSelectAll`). Opens the
+     * dropdown if needed. Throws when the select-all row isn't present.
+     *
+     * @returns Promise that resolves once the row has been clicked.
+     *
+     * @example
+     * ```typescript
+     * const select = await loader.getHarness(TnSelectHarness);
+     * await select.toggleSelectAll(); // selects every option
+     * await select.toggleSelectAll(); // clears them again
+     * ```
+     */
+    toggleSelectAll(): Promise<void>;
+    /**
+     * Whether the select-all checkbox reads as fully checked (all options
+     * selected). Opens the dropdown if needed. Throws when the row isn't present.
+     *
+     * @returns Promise resolving to true when every option is selected.
+     */
+    isSelectAllChecked(): Promise<boolean>;
 }
 /**
  * A set of criteria that can be used to filter a list of `TnSelectHarness` instances.
@@ -6268,6 +6343,349 @@ declare class TnTreeNodeOutletDirective {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TnTreeNodeOutletDirective, "[tnTreeNodeOutlet]", never, {}, {}, never, never, true, [{ directive: typeof i1.CdkTreeNodeOutlet; inputs: {}; outputs: {}; }]>;
 }
 
+/**
+ * A single flattened tree node prepared for virtual-scroll rendering.
+ *
+ * `TnTreeVirtualScrollViewComponent` intercepts CDK's `renderNodeChanges` and,
+ * instead of letting the CDK tree insert every visible node into its outlet,
+ * wraps each node in this shape so the node can be materialised on demand by the
+ * `cdk-virtual-scroll-viewport` (only rows in view are created in the DOM).
+ */
+interface TnTreeVirtualNodeData<T> {
+    /** The raw data node. */
+    data: T;
+    /** The outlet context (carries `$implicit`, `level`, etc.) for the node template. */
+    context: CdkTreeNodeOutletContext<T>;
+    /** The matched node definition whose template renders this row. */
+    nodeDef: CdkTreeNodeDef<T>;
+    /** 1-based position within the node's SIBLING set (same parent/level), for `aria-posinset`. */
+    posInSet: number;
+    /** Size of the node's SIBLING set (same parent/level), for `aria-setsize`. */
+    setSize: number;
+}
+
+/** Default fixed row height (px) used by the virtual scroll viewport. */
+declare const defaultTreeItemSize = 48;
+/**
+ * A `tn-tree` that renders through a `cdk-virtual-scroll-viewport`, so only the
+ * rows currently in view are materialised in the DOM. Drop-in for large trees
+ * (thousands of nodes) where the plain `tn-tree` would render every node.
+ *
+ * Usage mirrors `tn-tree`: provide a `TnTreeFlatDataSource` + `FlatTreeControl`
+ * and one `*cdkTreeNodeDef` template. Rows are a fixed height (`itemSize`).
+ *
+ * ```html
+ * <tn-tree-virtual-scroll-view [dataSource]="dataSource" [treeControl]="treeControl" [itemSize]="52">
+ *   <tn-tree-node *cdkTreeNodeDef="let node" cdkTreeNodePadding [routerLink]="...">
+ *     {{ node.name }}
+ *   </tn-tree-node>
+ * </tn-tree-virtual-scroll-view>
+ * ```
+ *
+ * Accessibility: rows are exposed with `role="treeitem"` plus `aria-level`,
+ * `aria-posinset` and `aria-setsize` (the latter two relative to the node's
+ * siblings — nodes sharing the same parent/level — per the WAI-ARIA tree
+ * pattern, not the flattened list of all visible rows), and the virtual-scroll
+ * wrappers are marked `role="presentation"` so assistive tech still sees the
+ * items as children of the `role="tree"` host.
+ *
+ * Keyboard: expandable rows are focusable and expand/collapse with Enter/Space (see
+ * {@link onTreeKeydown}), so a keyboard/AT user can operate the `aria-expanded` that
+ * each expandable `treeitem` advertises. Roving arrow-key / Home / End navigation
+ * BETWEEN nodes is NOT supported here, though — because rows are materialised (and
+ * recycled) by the virtual scroll viewport rather than registered with CdkTree's node
+ * outlet, the CDK `TreeKeyManager` has no stable node set to drive. Use Tab to move
+ * between rows, or the non-virtual `tn-tree` when full roving navigation is required.
+ */
+declare class TnTreeVirtualScrollViewComponent<T, K = T> extends CdkTree<T, K> implements AfterViewInit {
+    private destroyRef;
+    private cdr;
+    readonly virtualScrollViewport: _angular_core.Signal<CdkVirtualScrollViewport>;
+    /** Fixed row height in px. Must match the actual rendered node height. */
+    readonly itemSize: _angular_core.InputSignal<number>;
+    /**
+     * Viewport buffer sizes (px). Leave at 0 (the default) to derive them from `itemSize()`
+     * — {@link defaultMinBufferRows} / {@link defaultBufferRows} rows — so the buffers scale
+     * with a custom row height; pass an explicit px value to override. (A fixed px default
+     * would under-buffer a tall `itemSize`, even failing to buffer a single row when
+     * `itemSize > maxBufferPx`.)
+     */
+    readonly minBufferPx: _angular_core.InputSignal<number>;
+    readonly maxBufferPx: _angular_core.InputSignal<number>;
+    /** `minBufferPx` resolved to px, falling back to a row-count default that tracks `itemSize()`. */
+    protected readonly resolvedMinBufferPx: _angular_core.Signal<number>;
+    /** `maxBufferPx` resolved to px, falling back to a row-count default that tracks `itemSize()`. */
+    protected readonly resolvedMaxBufferPx: _angular_core.Signal<number>;
+    /**
+     * When true the viewport scrolls with the window instead of an internal scroll area.
+     * `booleanAttribute` so the bare presence form (`<... scrollWindow>`) coerces to `true`
+     * rather than the empty-string (falsy) an un-transformed input would receive.
+     *
+     * Set once at initialisation — NOT reactive. The scroll listener, presentational roles
+     * and ResizeObserver are wired in `ngAfterViewInit` against the viewport that this input
+     * selected; toggling it later re-renders the viewport but does not re-run that wiring.
+     */
+    readonly scrollWindow: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether to show the floating "scroll to top" button once scrolled down. */
+    readonly showScrollToTop: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Accessible label / tooltip for the scroll-to-top button (i18n is the consumer's job). */
+    readonly scrollToTopLabel: _angular_core.InputSignal<string>;
+    /**
+     * Per-row trackBy over the ORIGINAL data node (not the internal wrapper). Strongly
+     * recommended: without it rows track by index, so the recycling viewport reuses a
+     * detached view for whatever node lands at that index on data changes. Pass a stable
+     * key (e.g. `(_, node) => node.id`) as the stories do.
+     */
+    readonly nodeTrackBy: _angular_core.InputSignal<TrackByFunction<T> | undefined>;
+    /** Emits the viewport's horizontal `scrollLeft` (used to sync a sticky column header). */
+    readonly viewportScrolled: _angular_core.OutputEmitterRef<number>;
+    /**
+     * Emits the observed content size whenever it changes (used to size a sticky header).
+     * `width` is the full rendered content width — including horizontal overflow past the
+     * viewport — which is what a horizontally-synced header needs. `height` is the observed
+     * content wrapper's height: the visible viewport height in internal-scroll mode, but the
+     * FULL content height (row count × `itemSize`) in `scrollWindow` mode, where the wrapper
+     * grows with the document. Consumers wanting the visible viewport height should not rely
+     * on this field in window mode.
+     */
+    readonly viewportResized: _angular_core.OutputEmitterRef<{
+        width: number;
+        height: number;
+    }>;
+    /** Last `scrollLeft` emitted via {@link viewportScrolled}; used to skip redundant emits. */
+    private lastEmittedScrollLeft;
+    protected nodes$: BehaviorSubject<TnTreeVirtualNodeData<T>[]>;
+    protected readonly innerTrackBy: _angular_core.Signal<TrackByFunction<TnTreeVirtualNodeData<T>>>;
+    private renderNodeChanges$;
+    private resizeObserver;
+    private scrollViewportElement;
+    private scrollFrameSubscription;
+    constructor();
+    ngAfterViewInit(): void;
+    ngOnDestroy(): void;
+    /**
+     * Cached visibility of the scroll-to-top button. Recomputed only on scroll (see
+     * {@link onViewportScroll}) rather than read as a getter every change-detection
+     * pass, so `measureScrollOffset` — a layout-forcing read — is not called each cycle.
+     */
+    protected isScrollTopButtonVisible: boolean;
+    scrollToTop(): void;
+    /**
+     * Enter/Space on a focused expandable row toggles its expansion. The virtual viewport
+     * recycles rows so CDK's `TreeKeyManager` can't drive them (see class docs); this keeps
+     * the expand/collapse that each `aria-expanded` row advertises keyboard-operable, via
+     * event delegation on the `role="tree"` host that reuses the row's `cdkTreeNodeToggle`
+     * click handler. Ignored when focus is on an inner control (e.g. a `routerLink` anchor)
+     * so that element keeps its own Enter/Space behaviour.
+     */
+    protected onTreeKeydown(event: KeyboardEvent): void;
+    private updateScrollTopButtonVisibility;
+    renderNodeChanges(data: readonly T[]): void;
+    private getNodeLevel;
+    /**
+     * Compute per-row `aria-posinset` / `aria-setsize` scoped to each node's SIBLINGS
+     * (same parent / same level), as the WAI-ARIA tree pattern requires — not the flat
+     * list of all visible rows. The flat node set is depth-first ordered and each node
+     * carries a level, so siblings at level L are the consecutive level-L nodes bounded
+     * by any shallower node (level < L = a parent boundary); deeper nodes in between are
+     * descendants of an earlier sibling and don't split the group. One pass, tracking the
+     * open sibling group at each level.
+     */
+    private computeAriaPositions;
+    private createNode;
+    private buildVirtualNodes;
+    private listenForNodeChanges;
+    private readonly onViewportScroll;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnTreeVirtualScrollViewComponent<any, any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnTreeVirtualScrollViewComponent<any, any>, "tn-tree-virtual-scroll-view", ["tnTreeVirtualScrollView"], { "itemSize": { "alias": "itemSize"; "required": false; "isSignal": true; }; "minBufferPx": { "alias": "minBufferPx"; "required": false; "isSignal": true; }; "maxBufferPx": { "alias": "maxBufferPx"; "required": false; "isSignal": true; }; "scrollWindow": { "alias": "scrollWindow"; "required": false; "isSignal": true; }; "showScrollToTop": { "alias": "showScrollToTop"; "required": false; "isSignal": true; }; "scrollToTopLabel": { "alias": "scrollToTopLabel"; "required": false; "isSignal": true; }; "nodeTrackBy": { "alias": "nodeTrackBy"; "required": false; "isSignal": true; }; }, { "viewportScrolled": "viewportScrolled"; "viewportResized": "viewportResized"; }, never, never, true, [{ directive: typeof TnTestIdDirective; inputs: { "tnTestId": "testId"; }; outputs: {}; }]>;
+}
+
+/**
+ * Renders a single virtual tree row.
+ *
+ * `cdk-virtual-scroll-viewport` materialises this outlet for each row that scrolls
+ * into view; the outlet instantiates the node's template with its context and
+ * (re)binds `CdkTreeNode.mostRecentTreeNode.data`, so the row behaves exactly as a
+ * node rendered directly by the CDK tree. When the same DOM view is recycled for a
+ * different node (virtual scrolling reuses views), only the context is patched.
+ */
+declare class TnTreeVirtualScrollNodeOutletDirective<T> implements OnChanges, DoCheck {
+    private _viewContainerRef;
+    private _viewRef;
+    readonly data: _angular_core.InputSignal<TnTreeVirtualNodeData<T>>;
+    /**
+     * Re-assert the row's aria position every check. The viewport's recycling view
+     * repeater can swap the underlying DOM view for a different row without our
+     * `ngOnChanges` writing the new `aria-setsize`/`aria-posinset` in a way that
+     * survives the swap, so we reconcile the current element against the current data
+     * on each change-detection pass (two cheap attribute writes) — self-healing.
+     */
+    ngDoCheck(): void;
+    ngOnChanges(changes: SimpleChanges): void;
+    /**
+     * Whether the row must be re-instantiated (vs. patched in place). Every wrapper
+     * carries the same fixed key set (`data`/`context`/`nodeDef`/`posInSet`/`setSize`),
+     * so recreation comes down to whether the raw data node is a different reference —
+     * that is what marks a genuinely different row (a missing wrapper also recreates).
+     */
+    private shouldRecreateView;
+    /**
+     * Reflect posinset/setsize onto the row element so screen readers can announce
+     * "item N of M". Runs on every `ngDoCheck` (the hot CD path), so only write when the
+     * attribute actually differs — skipping the redundant `setAttribute` on the common
+     * pass where nothing changed.
+     */
+    private applyAriaPosition;
+    /**
+     * Make expandable rows keyboard-focusable so a user can Tab to a pool/branch and
+     * expand it with Enter/Space (the host `TnTreeVirtualScrollViewComponent` handles the
+     * key). The virtual viewport recycles a row's view between expandable and leaf nodes,
+     * so this reconciles every check; leaf rows are left to the consumer's own interactive
+     * content (e.g. a `routerLink` anchor). Expandability is read from `aria-expanded`,
+     * which `tn-tree-node` sets only on expandable nodes. Only touch the DOM on change —
+     * this runs on the hot CD path.
+     */
+    private applyKeyboardAffordance;
+    private updateExistingContext;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnTreeVirtualScrollNodeOutletDirective<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TnTreeVirtualScrollNodeOutletDirective<any>, "[tnTreeVirtualScrollNodeOutlet]", never, { "data": { "alias": "data"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Harness for interacting with `tn-tree-virtual-scroll-view` in tests.
+ *
+ * Because the component virtualises its rows, every query below operates over the
+ * currently-MATERIALISED (visible + buffered) rows only — nodes scrolled far out of view
+ * are not in the DOM. Indexes are positions within that visible set, not the full data.
+ *
+ * @example
+ * ```typescript
+ * const tree = await loader.getHarness(TnTreeVirtualScrollViewHarness);
+ * expect(await tree.getRowTexts()).toEqual(['pool', 'other']);
+ *
+ * await tree.expand(0);
+ * expect(await tree.isExpanded(0)).toBe(true);
+ * expect(await tree.getAriaLevel(1)).toBe(2);
+ * ```
+ */
+declare class TnTreeVirtualScrollViewHarness extends ComponentHarness {
+    static hostSelector: string;
+    /**
+     * Gets a `HarnessPredicate` that can be used to search for a virtual-scroll tree
+     * with specific attributes.
+     *
+     * @param options Options for filtering which instances are considered a match.
+     * @returns A `HarnessPredicate` configured with the given options.
+     */
+    static with(options?: TnTreeVirtualScrollViewHarnessFilters): HarnessPredicate<TnTreeVirtualScrollViewHarness>;
+    private readonly rows;
+    private readonly scrollTopButton;
+    /**
+     * Gets the number of currently-materialised tree rows.
+     *
+     * @returns Promise resolving to the visible row count.
+     */
+    getRowCount(): Promise<number>;
+    /**
+     * Gets the text label of every materialised row (the node's text cell only, excluding
+     * the expand chevron glyph).
+     *
+     * @returns Promise resolving to an array of row label strings.
+     */
+    getRowTexts(): Promise<string[]>;
+    /**
+     * Gets the text label of a single materialised row.
+     *
+     * @param index Zero-based index within the visible rows.
+     * @returns Promise resolving to the row's label.
+     */
+    getRowText(index: number): Promise<string>;
+    /**
+     * Gets the 1-based `aria-level` of a row (root nodes are 1).
+     *
+     * @param index Zero-based index within the visible rows.
+     * @returns Promise resolving to the aria-level, or null if unset.
+     */
+    getAriaLevel(index: number): Promise<number | null>;
+    /**
+     * Gets a row's `aria-posinset` — its 1-based position within its SIBLING set.
+     *
+     * @param index Zero-based index within the visible rows.
+     * @returns Promise resolving to the aria-posinset, or null if unset.
+     */
+    getAriaPosInSet(index: number): Promise<number | null>;
+    /**
+     * Gets a row's `aria-setsize` — the size of its SIBLING set.
+     *
+     * @param index Zero-based index within the visible rows.
+     * @returns Promise resolving to the aria-setsize, or null if unset.
+     */
+    getAriaSetSize(index: number): Promise<number | null>;
+    /**
+     * Whether a row is expandable (advertises `aria-expanded`).
+     *
+     * @param index Zero-based index within the visible rows.
+     * @returns Promise resolving to true if the row is expandable.
+     */
+    isExpandable(index: number): Promise<boolean>;
+    /**
+     * Whether an expandable row is currently expanded.
+     *
+     * @param index Zero-based index within the visible rows.
+     * @returns Promise resolving to true if `aria-expanded="true"`.
+     */
+    isExpanded(index: number): Promise<boolean>;
+    /**
+     * Whether a row is keyboard tab-focusable (`tabindex="0"`). Only expandable rows are.
+     *
+     * @param index Zero-based index within the visible rows.
+     * @returns Promise resolving to true if the row is tab-focusable.
+     */
+    isFocusable(index: number): Promise<boolean>;
+    /**
+     * Toggles a row's expansion by clicking its toggle. No-op semantics are the tree's
+     * (clicking a leaf does nothing).
+     *
+     * @param index Zero-based index within the visible rows.
+     */
+    toggle(index: number): Promise<void>;
+    /**
+     * Expands a row if it is expandable and currently collapsed.
+     *
+     * @param index Zero-based index within the visible rows.
+     */
+    expand(index: number): Promise<void>;
+    /**
+     * Collapses a row if it is currently expanded.
+     *
+     * @param index Zero-based index within the visible rows.
+     */
+    collapse(index: number): Promise<void>;
+    /**
+     * Focuses a row and presses a key on it (Enter/Space toggle an expandable row).
+     *
+     * @param index Zero-based index within the visible rows.
+     * @param key Which key to press — Enter or Space.
+     */
+    pressKeyOnRow(index: number, key: 'enter' | 'space'): Promise<void>;
+    /**
+     * Whether the floating scroll-to-top button is currently visible.
+     *
+     * @returns Promise resolving to true if the button is rendered.
+     */
+    isScrollToTopVisible(): Promise<boolean>;
+    /**
+     * Clicks the scroll-to-top button. Throws if it is not currently visible.
+     */
+    clickScrollToTop(): Promise<void>;
+    private getRow;
+    private getRowNumberAttribute;
+}
+/**
+ * Filters for finding `TnTreeVirtualScrollViewHarness` instances.
+ */
+type TnTreeVirtualScrollViewHarnessFilters = BaseHarnessFilters;
+
 declare enum CommonShortcuts {
     NEW = "\u2318N",
     OPEN = "\u2318O",
@@ -8822,5 +9240,5 @@ 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, TnCardFooterActionsDirective, TnCardHeaderActionsDirective, TnCardHeaderDirective, TnCellDefDirective, TnCheckboxComponent, TnCheckboxHarness, TnCheckboxLabelDirective, TnChipComponent, TnChipHarness, TnChipInputComponent, TnChipInputHarness, TnConfirmDialogComponent, TnDateInputComponent, TnDateInputHarness, TnDateRangeInputComponent, TnDateRangeInputHarness, TnDetailRowDefDirective, TnDialog, TnDialogHarness, TnDialogShellComponent, TnDialogTesting, TnDividerComponent, TnDividerDirective, TnDrawerComponent, TnDrawerContainerComponent, TnDrawerContainerHarness, TnDrawerContentComponent, TnDrawerHarness, TnEmptyComponent, TnEmptyHarness, TnExpansionPanelComponent, TnExpansionPanelHarness, TnFileInputComponent, TnFileInputHarness, TnFilePickerComponent, TnFilePickerPopupComponent, TnFormFieldComponent, TnFormFieldHarness, TnFormSectionComponent, TnFormSectionHarness, 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, TnStepperHarness, TnStepperNextDirective, TnStepperPreviousDirective, 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, controlTestId, 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, ChipHarnessFilters, CreateFolderEvent, DateInputHarnessFilters, DateRange, DateRangeInputHarnessFilters, DialogHarnessFilters, EmptyHarnessFilters, ExpansionPanelHarnessFilters, FileInputHarnessFilters, FilePickerCallbacks, FilePickerError, FilePickerMode, FileSystemItem, FormFieldHarnessFilters, FormSectionHarnessFilters, 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, StepperHarnessFilters, SubscriptSizing, TabChangeEvent, TabHarnessFilters, TabPanelHarnessFilters, TabsHarnessFilters, TnAutocompleteOption, TnBannerType, TnButtonToggleType, TnCardAction, TnCardControl, TnCardFooterLink, TnCardHeaderStatus, TnChipInputHarnessFilters, TnChipInputOption, 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 { 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, TnCardFooterActionsDirective, TnCardHeaderActionsDirective, TnCardHeaderDirective, TnCellDefDirective, TnCheckboxComponent, TnCheckboxHarness, TnCheckboxLabelDirective, TnChipComponent, TnChipHarness, TnChipInputComponent, TnChipInputHarness, TnConfirmDialogComponent, TnDateInputComponent, TnDateInputHarness, TnDateRangeInputComponent, TnDateRangeInputHarness, TnDetailRowDefDirective, TnDialog, TnDialogHarness, TnDialogShellComponent, TnDialogTesting, TnDividerComponent, TnDividerDirective, TnDrawerComponent, TnDrawerContainerComponent, TnDrawerContainerHarness, TnDrawerContentComponent, TnDrawerHarness, TnEmptyComponent, TnEmptyHarness, TnExpansionPanelComponent, TnExpansionPanelHarness, TnFileInputComponent, TnFileInputHarness, TnFilePickerComponent, TnFilePickerPopupComponent, TnFormFieldComponent, TnFormFieldHarness, TnFormSectionComponent, TnFormSectionHarness, 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, TnStepperHarness, TnStepperNextDirective, TnStepperPreviousDirective, 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, TnTreeVirtualScrollNodeOutletDirective, TnTreeVirtualScrollViewComponent, TnTreeVirtualScrollViewHarness, TruncatePathPipe, WindowsModifierKeys, WindowsShortcuts, composeTestId, controlTestId, createLucideLibrary, createShortcut, defaultSpriteBasePath, defaultSpriteConfigPath, defaultTreeItemSize, formatSize, kebabTestSegment, labelMarkupToHtml, labelMarkupToText, libIconMarker, parseLabelMarkup, parseSize, registerLucideIcons, scopeTestId, setupLucideIntegration, tnIconMarker, writeTestId };
+export type { AutocompleteHarnessFilters, BannerHarnessFilters, ButtonHarnessFilters, ButtonToggleHarnessFilters, CalendarCell, CheckboxHarnessFilters, ChipColor, ChipHarnessFilters, CreateFolderEvent, DateInputHarnessFilters, DateRange, DateRangeInputHarnessFilters, DialogHarnessFilters, EmptyHarnessFilters, ExpansionPanelHarnessFilters, FileInputHarnessFilters, FilePickerCallbacks, FilePickerError, FilePickerMode, FileSystemItem, FormFieldHarnessFilters, FormSectionHarnessFilters, 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, StepperHarnessFilters, SubscriptSizing, TabChangeEvent, TabHarnessFilters, TabPanelHarnessFilters, TabsHarnessFilters, TnAutocompleteOption, TnBannerType, TnButtonToggleType, TnCardAction, TnCardControl, TnCardFooterLink, TnCardHeaderStatus, TnChipInputHarnessFilters, TnChipInputOption, 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, TnTreeVirtualNodeData, TnTreeVirtualScrollViewHarnessFilters, TooltipPosition, YearCell };