@truenas/ui-components 0.3.22 → 0.3.24

package/package.json

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

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

@@ -5,11 +5,11 @@ 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';
 import { ComponentFixture } from '@angular/core/testing';
-import { SelectionModel, DataSource } from '@angular/cdk/collections';
+import { SelectionModel, DataSource, CollectionViewer } from '@angular/cdk/collections';
 import * as rxjs from 'rxjs';
 import { Observable, BehaviorSubject } from 'rxjs';
 import * as i1 from '@angular/cdk/tree';
-import { CdkTree, FlatTreeControl, CdkTreeNode, CdkNestedTreeNode, CdkTreeNodeOutletContext, CdkTreeNodeDef } from '@angular/cdk/tree';
+import { CdkTree, 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';
@@ -119,6 +119,31 @@ declare function composeTestId(type: string | null | undefined, value: TnTestIdV
  */
 declare function controlTestId(testId: Signal<TnTestIdValue>): Signal<TnTestIdValue>;
 
+/**
+ * Minimal structural shape of a dropdown option for test-id derivation.
+ * Satisfied by `TnSelectOption` / `TnAutocompleteOption` (and any future
+ * option-like shape) without coupling the test-id module to component types.
+ */
+interface TnOptionTestIdSource {
+    label: string;
+    value?: unknown;
+}
+/**
+ * Derive the test-id segments for a dropdown option row, consumed by
+ * `[tnTestId]` with `tnTestIdType="option"`. The component's resolved base
+ * (explicit `testId`, else the bound control name) scopes a per-option
+ * discriminator so ids stay unique across instances: base `user` + option
+ * value `jane-doe` → `option-user-jane-doe`; with no base → `option-jane-doe`.
+ *
+ * The discriminator comes from `extractor` when provided (a component's
+ * `optionTestIdKey` input), else the option's primitive `value`, else its
+ * `label`. Shared by `tn-select` and `tn-autocomplete` so the derivation
+ * rules can't drift between dropdown components; synthetic rows with fixed
+ * discriminators (e.g. select's `allowEmpty` option) are handled by the
+ * caller before delegating here.
+ */
+declare function optionTestId<O extends TnOptionTestIdSource>(base: TnTestIdValue, option: O, extractor?: (option: O) => string | number | null | undefined): (string | number | null | undefined)[];
+
 /**
  * Test-id attribute names supported by the library.
  *
@@ -357,11 +382,8 @@ declare class TnSelectComponent<T = unknown> implements ControlValueAccessor, On
     isOptionFocused(option: TnSelectOption<T>): boolean;
     /**
      * Test-id segments for an option row, consumed by `[tnTestId]` with
-     * `tnTestIdType="option"`. The select's resolved base (explicit `testId`, else
-     * the bound control name) scopes each option so ids stay unique across selects:
-     * base `quick-filters` + option value `ssd` → `option-quick-filters-ssd`; with
-     * no base → `option-ssd`. The discriminator comes from `optionTestIdKey` when
-     * provided, else the option's primitive `value`, else its `label`.
+     * `tnTestIdType="option"` — see {@link optionTestId} for the derivation
+     * rules (shared with `tn-autocomplete`).
      */
     protected optionTestIdParts(option: TnSelectOption<T>): (string | number | null | undefined)[];
     private onChange;
@@ -571,6 +593,20 @@ declare class TnAutocompleteComponent<T = unknown> implements ControlValueAccess
     ariaLabel: _angular_core.InputSignal<string | undefined>;
     /** Test ID attribute */
     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>;
+    /**
+     * Optional extractor for the per-option test-id discriminator. Defaults to
+     * the option's `value` (when a string/number) or its `label`. Provide this
+     * when option values are objects, or to pick a more stable/unique key —
+     * mirrors `tn-select`'s input of the same name.
+     *
+     * @example
+     * ```html
+     * <tn-autocomplete testId="user" [optionTestIdKey]="(o) => o.value.id" ... />
+     * ```
+     */
+    optionTestIdKey: _angular_core.InputSignal<((option: TnAutocompleteOption<T>) => string | number | null | undefined) | undefined>;
     /**
      * ARIA wiring from an enclosing `tn-form-field` (label, error/hint,
      * invalid, required). All-null when standalone or when `ariaLabel` overrides.
@@ -664,6 +700,21 @@ declare class TnAutocompleteComponent<T = unknown> implements ControlValueAccess
      * cursor (which is conveyed via `aria-activedescendant`).
      */
     protected isOptionSelected(option: TnAutocompleteOption<T>): boolean;
+    /**
+     * Test-id segments for an option row, consumed by `[tnTestId]` with
+     * `tnTestIdType="option"` — see {@link optionTestId} for the derivation
+     * rules (shared with `tn-select`).
+     */
+    protected optionTestIdParts(option: TnAutocompleteOption<T>): (string | number | null | undefined)[];
+    /**
+     * Test-id segments for the loading / no-results status rows, consumed by
+     * `[tnTestId]` with `tnTestIdType="autocomplete"` so they nest under the
+     * input's own id: base `user` → `autocomplete-user-loading` /
+     * `autocomplete-user-no-results` (unscoped `autocomplete-loading` /
+     * `autocomplete-no-results` with no base). Mirrors webui's ix-combobox,
+     * which stamps its status option so automation can assert on those states.
+     */
+    protected statusTestIdParts(status: 'loading' | 'no-results'): (string | number | null | undefined)[];
     /**
      * Index of the committed value's option in the visible list, or -1 when
      * nothing is committed or the match is absent/disabled. Used to seed the
@@ -713,7 +764,7 @@ declare class TnAutocompleteComponent<T = unknown> implements ControlValueAccess
     private detachOverlay;
     private scrollToHighlighted;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnAutocompleteComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnAutocompleteComponent<any>, "tn-autocomplete", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "requireSelection": { "alias": "requireSelection"; "required": false; "isSignal": true; }; "allowCustomValue": { "alias": "allowCustomValue"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "loadingText": { "alias": "loadingText"; "required": false; "isSignal": true; }; "filterFn": { "alias": "filterFn"; "required": false; "isSignal": true; }; "noResultsText": { "alias": "noResultsText"; "required": false; "isSignal": true; }; "maxResults": { "alias": "maxResults"; "required": false; "isSignal": true; }; "panelMaxHeight": { "alias": "panelMaxHeight"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; }, { "optionSelected": "optionSelected"; "searchChange": "searchChange"; "loadMore": "loadMore"; "opened": "opened"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnAutocompleteComponent<any>, "tn-autocomplete", never, { "options": { "alias": "options"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "requireSelection": { "alias": "requireSelection"; "required": false; "isSignal": true; }; "allowCustomValue": { "alias": "allowCustomValue"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "loadingText": { "alias": "loadingText"; "required": false; "isSignal": true; }; "filterFn": { "alias": "filterFn"; "required": false; "isSignal": true; }; "noResultsText": { "alias": "noResultsText"; "required": false; "isSignal": true; }; "maxResults": { "alias": "maxResults"; "required": false; "isSignal": true; }; "panelMaxHeight": { "alias": "panelMaxHeight"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "testId": { "alias": "testId"; "required": false; "isSignal": true; }; "optionTestIdKey": { "alias": "optionTestIdKey"; "required": false; "isSignal": true; }; }, { "optionSelected": "optionSelected"; "searchChange": "searchChange"; "loadMore": "loadMore"; "opened": "opened"; }, never, never, true, never>;
 }
 
 /**
@@ -6393,6 +6444,52 @@ declare class TnTablePagerHarness extends ComponentHarness {
 interface TnTablePagerHarnessFilters extends BaseHarnessFilters {
 }
 
+/**
+ * Interface for tree expansion state management.
+ * This interface replaces the deprecated TreeControl from @angular/cdk/tree.
+ *
+ * It provides the same methods as the deprecated TreeControl interface
+ * without directly referencing the deprecated type.
+ *
+ * Both FlatTreeControl and NestedTreeControl implement all these methods,
+ * so this interface maintains full compatibility with existing code.
+ */
+interface TnTreeExpansion<T, K = T> {
+    /** The saved tree nodes data for `expandAll` action. */
+    dataNodes: T[];
+    /** The expansion model */
+    expansionModel: SelectionModel<K>;
+    /** Whether the data node is expanded or collapsed. Return true if it's expanded. */
+    isExpanded(dataNode: T): boolean;
+    /** Get all descendants of a data node */
+    getDescendants(dataNode: T): T[];
+    /** Expand or collapse data node */
+    toggle(dataNode: T): void;
+    /** Expand one data node */
+    expand(dataNode: T): void;
+    /** Collapse one data node */
+    collapse(dataNode: T): void;
+    /** Expand all the dataNodes in the tree */
+    expandAll(): void;
+    /** Collapse all the dataNodes in the tree */
+    collapseAll(): void;
+    /** Toggle a data node by expand/collapse it and all its descendants */
+    toggleDescendants(dataNode: T): void;
+    /** Expand a data node and all its descendants */
+    expandDescendants(dataNode: T): void;
+    /** Collapse a data node and all its descendants */
+    collapseDescendants(dataNode: T): void;
+    /** Get depth of a given data node, return the level number. This is for flat tree node. */
+    readonly getLevel: (dataNode: T) => number;
+    /**
+     * Whether the data node is expandable. Returns true if expandable.
+     * This is for flat tree node.
+     */
+    readonly isExpandable: (dataNode: T) => boolean;
+    /** Gets a stream that emits whenever the given data node's children change. */
+    readonly getChildren: (dataNode: T) => Observable<T[]> | T[] | undefined | null;
+}
+
 /** Flat node with expandable and level information */
 interface TnFlatTreeNode<T = unknown> {
     data: T;
@@ -6413,18 +6510,36 @@ declare class TnTreeFlattener<T, F> {
 }
 /**
  * Data source for flat tree.
+ *
+ * Optionally supports client-side filtering and sorting: set `filterPredicate`
+ * (and call `filter(query)`) and/or `sortComparer`. Both are opt-in; when unset
+ * the datasource behaves exactly as before.
  */
 declare class TnTreeFlatDataSource<T, F> extends DataSource<F> {
     private _treeControl;
     private _treeFlattener;
+    /** When set, `filter(query)` re-renders the tree from `filterPredicate(data, query)`. */
+    filterPredicate?: (data: T[], query: string) => T[];
+    /** When set, incoming `data` is sorted (top level) before flattening. */
+    sortComparer?: (a: T, b: T) => number;
     private _flattenedData;
     private _expandedData;
     private _data;
-    constructor(_treeControl: FlatTreeControl<F>, _treeFlattener: TnTreeFlattener<T, F>);
+    private _filteredData;
+    private filterValue;
+    private readonly filterChanged$;
+    private readonly disconnect$;
+    constructor(_treeControl: TnTreeExpansion<F>, _treeFlattener: TnTreeFlattener<T, F>);
     get data(): T[];
     set data(value: T[]);
+    /** The currently filtered (unflattened) data; equals `data` until `filter()` is used. */
+    get filteredData(): T[];
     connect(): Observable<F[]>;
     disconnect(): void;
+    /** Filters the tree using `filterPredicate` (debounced). No-op until `filterPredicate` is set. */
+    filter(query: string): void;
+    private flattenData;
+    private detectFilterChanges;
     private _getExpandedNodesWithLevel;
 }
 declare class TnTreeComponent<T, K = T> extends CdkTree<T, K> {
@@ -6446,6 +6561,20 @@ declare class TnTreeNodeComponent<T, K = T> extends CdkTreeNode<T, K> {
 }
 
 declare class TnNestedTreeNodeComponent<T, K = T> extends CdkNestedTreeNode<T, K> {
+    /**
+     * Accessible label for the built-in toggle button. Pass a translated string;
+     * defaults to the previous hardcoded value.
+     */
+    readonly toggleAriaLabel: _angular_core.InputSignal<string>;
+    /** Semantic test-id base applied to the built-in toggle button (`button-` prefixed). */
+    readonly toggleTestId: _angular_core.InputSignal<TnTestIdValue>;
+    /**
+     * Suppresses the built-in toggle button (and its alignment spacer) so the
+     * consumer can render a fully custom toggle in the projected content.
+     */
+    readonly hideToggle: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    private readonly changeDetectorRef;
+    private destroyed;
     constructor();
     /** The tree node's level in the tree */
     get level(): number;
@@ -6453,8 +6582,24 @@ declare class TnNestedTreeNodeComponent<T, K = T> extends CdkNestedTreeNode<T, K
     get isExpandable(): boolean;
     /** Whether the tree node is expanded */
     get isExpanded(): boolean;
+    /**
+     * CDK inserts child node views synchronously from `ngAfterContentInit`, i.e.
+     * mid-change-detection. Because the outlet here lives in PROJECTED content
+     * whose view container has already been traversed for the current pass, the
+     * new views would miss their first check and trip dev-mode NG0100. Defer the
+     * insertion to a microtask so the views are created outside change detection
+     * and get a normal first check on the pass that `markForCheck` schedules.
+     */
+    protected updateChildrenNodes(children?: T[]): void;
+    /**
+     * Toggles the node; with the Alt key held, toggles the node together with all
+     * of its descendants. Replaces `cdkTreeNodeToggle` on the built-in button so
+     * the Alt behavior is deterministic (a stacked template listener would run in
+     * an unspecified order relative to the CDK toggle's own click handler).
+     */
+    protected toggleNode(event: Event): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnNestedTreeNodeComponent<any, any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnNestedTreeNodeComponent<any, any>, "tn-nested-tree-node", ["tnNestedTreeNode"], {}, {}, never, ["*", "[slot=children]"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnNestedTreeNodeComponent<any, any>, "tn-nested-tree-node", ["tnNestedTreeNode"], { "toggleAriaLabel": { "alias": "toggleAriaLabel"; "required": false; "isSignal": true; }; "toggleTestId": { "alias": "toggleTestId"; "required": false; "isSignal": true; }; "hideToggle": { "alias": "hideToggle"; "required": false; "isSignal": true; }; }, {}, never, ["*", "[slot=children]"], true, [{ directive: typeof TnTestIdDirective; inputs: { "tnTestId": "testId"; }; outputs: {}; }]>;
 }
 
 declare class TnTreeNodeOutletDirective {
@@ -6462,6 +6607,228 @@ declare class TnTreeNodeOutletDirective {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TnTreeNodeOutletDirective, "[tnTreeNodeOutlet]", never, {}, {}, never, never, true, [{ directive: typeof i1.CdkTreeNodeOutlet; inputs: {}; outputs: {}; }]>;
 }
 
+/**
+ * Data source for nested trees (`tn-nested-tree-node`).
+ *
+ * Optionally supports client-side filtering and sorting: set `filterPredicate`
+ * (and call `filter(query)`) and/or `sortComparer` (applied recursively through
+ * `children`). Both are opt-in.
+ */
+declare class TnNestedTreeDataSource<T extends {
+    children?: T[];
+}> extends DataSource<T> {
+    /** When set, `filter(query)` re-renders the tree from `filterPredicate(data, query)`. */
+    filterPredicate?: (data: T[], query: string) => T[];
+    /** When set, incoming `data` is sorted recursively before rendering. */
+    sortComparer?: (a: T, b: T) => number;
+    private filterValue;
+    private readonly filterChanged$;
+    private readonly _data;
+    private readonly _filteredData;
+    private readonly disconnect$;
+    get data(): T[];
+    set data(value: T[]);
+    constructor(initialData?: T[]);
+    connect(collectionViewer: CollectionViewer): Observable<T[]>;
+    disconnect(): void;
+    /** Filters the tree using `filterPredicate` (debounced). No-op until `filterPredicate` is set. */
+    filter(query: string): void;
+    private detectFilterChanges;
+    private sort;
+}
+
+/**
+ * Factory functions for creating tree controls without triggering deprecation warnings
+ * in consuming code.
+ *
+ * ## Why we still use deprecated TreeControl classes
+ *
+ * Angular CDK deprecated TreeControl, FlatTreeControl, and NestedTreeControl in v19,
+ * with plans to remove them in v21. However, a complete replacement API has not been
+ * provided yet.
+ *
+ * ### The Problem with Current Migration Path
+ *
+ * The deprecation message suggests using `levelAccessor` or `childrenAccessor` on CdkTree,
+ * but these are only for describing your data structure - they don't provide:
+ *
+ * 1. **Programmatic access to expansion state** - CdkTree's `_expansionModel` is private
+ * 2. **Access to data nodes** - Needed for operations like `expandAll()`
+ * 3. **Helper methods** - Like `getDescendants()`, `isExpandable()`, `getLevel()`
+ * 4. **External expansion control** - Data sources need to react to expansion changes
+ *
+ * ### Our Solution: Centralized Technical Debt
+ *
+ * This file encapsulates ALL usage of deprecated TreeControl classes:
+ *
+ * - Consumers work with the `TnTreeExpansion` interface (not deprecated)
+ * - When Angular provides a proper replacement API, only this file changes and the
+ *   `TnTreeExpansion` interface stays stable, making the migration transparent
+ *
+ * @see https://github.com/angular/components/issues/29856 - GitHub issue discussing the migration gap
+ */
+/** Optional configuration for flat tree control */
+interface FlatTreeControlOptions<T, K> {
+    trackBy?: (dataNode: T) => K;
+}
+/** Optional configuration for nested tree control */
+interface NestedTreeControlOptions<T, K> {
+    isExpandable?: (dataNode: T) => boolean;
+    trackBy?: (dataNode: T) => K;
+}
+/**
+ * Creates a flat tree control for managing expansion state of flat tree structures.
+ *
+ * @param getLevel - Function that returns the level/depth of a node
+ * @param isExpandable - Function that returns whether a node can be expanded
+ * @param options - Optional configuration including trackBy function
+ * @returns TnTreeExpansion instance for managing tree state
+ *
+ * @example
+ * ```ts
+ * const treeControl = createFlatTreeControl<DatasetDetails, string>(
+ *   (dataset) => (dataset?.name?.split('/')?.length || 0) - 1,
+ *   (dataset) => Number(dataset?.children?.length) > 0,
+ *   { trackBy: (dataset) => dataset.id }
+ * );
+ * ```
+ */
+declare function createFlatTreeControl<T, K = T>(getLevel: (dataNode: T) => number, isExpandable: (dataNode: T) => boolean, options?: FlatTreeControlOptions<T, K>): TnTreeExpansion<T, K>;
+/**
+ * Creates a nested tree control for managing expansion state of nested tree structures.
+ *
+ * @param getChildren - Function that returns the children of a node
+ * @param options - Optional configuration including isExpandable and trackBy functions
+ * @returns TnTreeExpansion instance for managing tree state
+ *
+ * @example
+ * ```ts
+ * const treeControl = createNestedTreeControl<VDevNode, string>(
+ *   (vdev) => vdev.children,
+ *   { trackBy: (vdev) => vdev.guid }
+ * );
+ * ```
+ */
+declare function createNestedTreeControl<T, K = T>(getChildren: (dataNode: T) => Observable<T[]> | T[] | undefined | null, options?: NestedTreeControlOptions<T, K>): TnTreeExpansion<T, K>;
+
+/** Filters for finding `TnTreeNodeHarness` instances. */
+interface TnTreeNodeHarnessFilters extends BaseHarnessFilters {
+    /** Only find nodes whose text matches the given value. */
+    text?: string | RegExp;
+    /** Only find nodes whose expansion state matches. */
+    expanded?: boolean;
+    /** Only find nodes at the given 0-based level (root nodes are 0). */
+    level?: number;
+}
+/** Filters for finding `TnTreeHarness` instances. */
+type TnTreeHarnessFilters = BaseHarnessFilters;
+/**
+ * Harness for interacting with a single `tn-tree-node` or `tn-nested-tree-node`.
+ *
+ * Levels are 0-based (root nodes are level 0), matching the values consumers pass
+ * to tree controls — the DOM's 1-based `aria-level` is converted internally.
+ */
+declare class TnTreeNodeHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** The built-in nested-node toggle button (absent on flat nodes, leaves, and `hideToggle` nodes). */
+    private readonly nestedToggle;
+    /** The flat node's row, which acts as its toggle surface. */
+    private readonly flatRow;
+    /**
+     * Gets a `HarnessPredicate` that can be used to search for a tree node 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?: TnTreeNodeHarnessFilters): HarnessPredicate<TnTreeNodeHarness>;
+    /**
+     * Gets the node's own text, excluding any descendant tree nodes and the
+     * built-in toggle button.
+     *
+     * @returns Promise resolving to the node's text.
+     */
+    getText(): Promise<string>;
+    /**
+     * Gets the node's 0-based level (root nodes are 0).
+     *
+     * @returns Promise resolving to the level.
+     */
+    getLevel(): Promise<number>;
+    /**
+     * Whether the node is expandable (advertises `aria-expanded`).
+     *
+     * @returns Promise resolving to true if the node is expandable.
+     */
+    isExpandable(): Promise<boolean>;
+    /**
+     * Whether an expandable node is currently expanded.
+     *
+     * @returns Promise resolving to true if `aria-expanded="true"`.
+     */
+    isExpanded(): Promise<boolean>;
+    /**
+     * Toggles the node's expansion by clicking its toggle surface — the built-in
+     * toggle button on a nested node, or the row itself on a flat node. Throws for
+     * nested nodes rendered with `hideToggle` (interact with the custom toggle
+     * directly in that case).
+     */
+    toggle(): Promise<void>;
+    /**
+     * Toggles the node together with all of its descendants (Alt+click on the
+     * built-in nested-node toggle).
+     */
+    toggleWithDescendants(): Promise<void>;
+    /**
+     * Expands the node if it is expandable and currently collapsed.
+     */
+    expand(): Promise<void>;
+    /**
+     * Collapses the node if it is currently expanded.
+     */
+    collapse(): Promise<void>;
+    private getToggle;
+}
+/**
+ * Harness for interacting with `tn-tree` in tests.
+ *
+ * @example
+ * ```typescript
+ * const tree = await loader.getHarness(TnTreeHarness);
+ * const roots = await tree.getNodes({ level: 0 });
+ * await roots[0].expand();
+ * expect(await tree.getNodeTexts()).toContain('child');
+ * ```
+ */
+declare class TnTreeHarness extends ComponentHarness {
+    static hostSelector: string;
+    /**
+     * Gets a `HarnessPredicate` that can be used to search for a 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?: TnTreeHarnessFilters): HarnessPredicate<TnTreeHarness>;
+    /**
+     * Gets the harnesses for the tree's nodes (all levels, in document order).
+     *
+     * Note: nested trees render collapsed subtrees into the DOM (hidden via CSS),
+     * so nodes under a collapsed parent are still returned — filter by `level` or
+     * check the parent's `isExpanded()` when visibility matters.
+     *
+     * @param filter Optional filter to narrow the nodes.
+     * @returns Promise resolving to the matching node harnesses.
+     */
+    getNodes(filter?: TnTreeNodeHarnessFilters): Promise<TnTreeNodeHarness[]>;
+    /**
+     * Gets the text of every node currently rendered, in document order.
+     *
+     * @returns Promise resolving to an array of node texts.
+     */
+    getNodeTexts(): Promise<string[]>;
+}
+
 /**
  * A single flattened tree node prepared for virtual-scroll rendering.
  *
@@ -9359,5 +9726,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_CONTEXT, 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, injectTnFormFieldAria, 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, TnFormFieldAriaBindings, TnFormFieldContext, TnFormFieldErrorMessage, TnFormFieldErrorMessages, TnFormFieldErrorResolver, TnMenuItem, TnSelectOption, TnSelectOptionGroup, TnSelectionChange, TnSortEvent, TnTableDataProvider, TnTableDataSource, TnTableHarnessFilters, TnTablePagerHarnessFilters, TnTablePagerLabels, TnTablePagination, TnTestAttrName, TnTestIdValue, TnThemeDefinition, TnToastCall, TnToastConfig, TnTreeVirtualNodeData, TnTreeVirtualScrollViewHarnessFilters, 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_CONTEXT, 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, TnNestedTreeDataSource, 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, TnTreeHarness, TnTreeNodeComponent, TnTreeNodeHarness, TnTreeNodeOutletDirective, TnTreeVirtualScrollNodeOutletDirective, TnTreeVirtualScrollViewComponent, TnTreeVirtualScrollViewHarness, TruncatePathPipe, WindowsModifierKeys, WindowsShortcuts, composeTestId, controlTestId, createFlatTreeControl, createLucideLibrary, createNestedTreeControl, createShortcut, defaultSpriteBasePath, defaultSpriteConfigPath, defaultTreeItemSize, formatSize, injectTnFormFieldAria, kebabTestSegment, labelMarkupToHtml, labelMarkupToText, libIconMarker, optionTestId, 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, FlatTreeControlOptions, FormFieldHarnessFilters, FormSectionHarnessFilters, IconButtonHarnessFilters, IconHarnessFilters, IconLibrary, IconLibraryType, IconResult, IconSize, IconSource, IconTestingMockOverrides, InputHarnessFilters, KeyCombination, LabelMarkupSegment, LabelMarkupSegmentType, LabelType, LucideIconOptions, MenuHarnessFilters, MockIconRegistry, MockSpriteLoader, NestedTreeControlOptions, 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, TnFormFieldAriaBindings, TnFormFieldContext, TnFormFieldErrorMessage, TnFormFieldErrorMessages, TnFormFieldErrorResolver, TnMenuItem, TnOptionTestIdSource, TnSelectOption, TnSelectOptionGroup, TnSelectionChange, TnSortEvent, TnTableDataProvider, TnTableDataSource, TnTableHarnessFilters, TnTablePagerHarnessFilters, TnTablePagerLabels, TnTablePagination, TnTestAttrName, TnTestIdValue, TnThemeDefinition, TnToastCall, TnToastConfig, TnTreeExpansion, TnTreeHarnessFilters, TnTreeNodeHarnessFilters, TnTreeVirtualNodeData, TnTreeVirtualScrollViewHarnessFilters, TooltipPosition, YearCell };