ngwr 10.2.1 → 11.1.0

package/fesm2022/ngwr-tree-testing.mjs

@@ -0,0 +1,734 @@
+import { ComponentHarness, HarnessPredicate, ContentContainerComponentHarness, TestKey } from '@angular/cdk/testing';
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+/**
+ * Test harness for one node of a `<wr-tree>` — a `role="treeitem"` row.
+ *
+ * Everything about a tree's shape that a screen reader gets lives on these rows:
+ * the list itself is FLAT, with no `role="group"` and no nesting, so `aria-level`,
+ * `aria-posinset` and `aria-setsize` are the only place the hierarchy exists. The
+ * indent is decoration.
+ *
+ * @example
+ * ```ts
+ * const src = await tree.getNode({ label: 'src' });
+ *
+ * await src.expand();
+ * expect(await src.getLevel()).toBe(1);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+class WrTreeNodeHarness extends ComponentHarness {
+    /**
+     * The row, and nothing else the list can hold.
+     *
+     * A windowed tree pads its list with `<li class="wr-tree__spacer" role="presentation">`
+     * at each end, so `li` would hand back up to two "nodes" with no label and no
+     * state. `[role="treeitem"]` selects exactly the same set as this class.
+     */
+    static hostSelector = '.wr-tree__row';
+    /** Build a predicate that narrows the query. */
+    static with(options = {}) {
+        return new HarnessPredicate(WrTreeNodeHarness, options)
+            .addOption('label', options.label, (harness, label) => HarnessPredicate.stringMatches(harness.getLabel(), label))
+            .addOption('selected', options.selected, async (harness, selected) => (await harness.isSelected()) === selected)
+            .addOption('disabled', options.disabled, async (harness, disabled) => (await harness.isDisabled()) === disabled)
+            .addOption('expanded', options.expanded, 
+        // A leaf is not a closed branch: it announces no `aria-expanded` at all, so
+        // it matches neither value rather than answering `false` and turning
+        // `{ expanded: false }` into "every row that is not open".
+        async (harness, expanded) => (await harness.isExpandable()) && (await harness.isExpanded()) === expanded)
+            .addOption('level', options.level, async (harness, level) => (await harness.getLevel()) === level);
+    }
+    /**
+     * The node's label.
+     *
+     * Read from `.wr-tree__label` rather than from the row's text, so the answer stays
+     * the label alone however the row is decorated around it.
+     */
+    async getLabel() {
+        return (await this.locatorFor('.wr-tree__label')()).text();
+    }
+    /** The node's 1-based depth, as the row announces it (`aria-level`). */
+    async getLevel() {
+        return this.announcedNumber('aria-level');
+    }
+    /**
+     * The node's 1-based position within its SIBLING GROUP (`aria-posinset`) — not its
+     * position in the flat list of visible rows.
+     *
+     * `src`'s first child is `posinset` 1 even though it is the second row on screen.
+     * That is what ARIA asks for, and the whole reason the attribute is needed here:
+     * the rendered list cannot express the nesting on its own.
+     */
+    async getPosInSet() {
+        return this.announcedNumber('aria-posinset');
+    }
+    /** How many nodes are in this node's sibling group, itself included (`aria-setsize`). */
+    async getSetSize() {
+        return this.announcedNumber('aria-setsize');
+    }
+    /**
+     * The node's index in the full list of VISIBLE nodes — every rendered row plus the
+     * ones a window left out, in the order the tree would show them.
+     *
+     * It is the index the tree's own keyboard code addresses rows by, and while the
+     * tree is windowed it is the only way to place a row: DOM order then says nothing,
+     * because the rows in the DOM are a slice.
+     */
+    async getIndex() {
+        return this.announcedNumber('data-tree-index');
+    }
+    /**
+     * The row's DOM id, or `null`.
+     *
+     * Only a windowed tree gives its rows ids, because that is the shape where the
+     * list keeps focus and names the cursor row with `aria-activedescendant` — the id
+     * exists to be pointed at.
+     */
+    async getId() {
+        return (await this.host()).getAttribute('id');
+    }
+    /**
+     * Whether the node is a branch — it has children, whether or not they are showing.
+     *
+     * From `aria-expanded`: only a branch carries it, and a branch that does not is
+     * announced as a leaf, so the user never learns there is anything underneath. The
+     * toggle element cannot answer this — a leaf renders a `<span>` with the same
+     * `.wr-tree__toggle` class purely to hold the indent.
+     */
+    async isExpandable() {
+        return (await (await this.host()).getAttribute('aria-expanded')) !== null;
+    }
+    /** Whether the branch is open. A leaf is never expanded. */
+    async isExpanded() {
+        return (await (await this.host()).getAttribute('aria-expanded')) === 'true';
+    }
+    /** Open the branch. Already-open branches are left alone; a leaf throws. */
+    async expand() {
+        if (await this.isExpanded())
+            return;
+        await this.toggleExpand();
+        if (!(await this.isExpanded())) {
+            throw new Error(`WrTreeNodeHarness.expand(): "${await this.getLabel()}" did not open. A disabled node ignores its ` +
+                'own toggle, and so does every node of a disabled tree.');
+        }
+    }
+    /** Close the branch. Already-closed branches are left alone; a leaf throws. */
+    async collapse() {
+        if (!(await this.isExpanded())) {
+            // A closed branch is fine to ask twice; a leaf is a mistake worth naming.
+            await this.toggleElement();
+            return;
+        }
+        await this.toggleExpand();
+        if (await this.isExpanded()) {
+            throw new Error(`WrTreeNodeHarness.collapse(): "${await this.getLabel()}" did not close. A disabled node ignores ` +
+                'its own toggle, and so does every node of a disabled tree.');
+        }
+    }
+    /**
+     * Click the branch's expand toggle.
+     *
+     * Expanding is the TOGGLE's job and not the row's: a click anywhere else in the row
+     * selects instead, which is the one thing a spec driving this by hand tends to get
+     * wrong.
+     */
+    async toggleExpand() {
+        await (await this.toggleElement()).click();
+    }
+    /**
+     * Whether the node is selected.
+     *
+     * From `aria-selected` rather than the `--selected` modifier: both are public, but
+     * the attribute is what a screen reader acts on, and a row that looks selected
+     * without saying so is the bug worth catching.
+     */
+    async isSelected() {
+        return (await (await this.host()).getAttribute('aria-selected')) === 'true';
+    }
+    /**
+     * Whether the tree offers selection at all.
+     *
+     * A `selectionMode="none"` tree announces NO `aria-selected` on its rows, which is
+     * how an unselectable node differs from one that is merely unselected — the two
+     * look identical otherwise.
+     */
+    async isSelectable() {
+        return (await (await this.host()).getAttribute('aria-selected')) !== null;
+    }
+    /**
+     * Whether the node refuses interaction (`aria-disabled`).
+     *
+     * True for EVERY node while the whole tree is disabled, not just for the ones the
+     * data marks — the row announces the effective state, which is the one a user runs
+     * into.
+     */
+    async isDisabled() {
+        return (await (await this.host()).getAttribute('aria-disabled')) === 'true';
+    }
+    /**
+     * Whether the node is where the keyboard cursor sits.
+     *
+     * The two patterns publish the cursor differently, and this covers both: a tree
+     * that renders every row hands the single tab stop to the cursor row (roving
+     * tabindex), while a windowed one keeps focus on the list and marks the row with
+     * the `--active` modifier plus the list's `aria-activedescendant`.
+     * `WrTreeHarness.getActiveNodeLabel()` reads that reference itself.
+     */
+    async isActive() {
+        const host = await this.host();
+        return (await host.getAttribute('tabindex')) === '0' || host.hasClass('wr-tree__row--active');
+    }
+    /**
+     * Whether the row holds real DOM focus.
+     *
+     * Deliberately separate from {@link isActive}: in a windowed tree the two DIVERGE
+     * by design — focus stays on the `role="tree"` list and only the announced cursor
+     * moves — so a spec asserting that a key press moved focus needs to know which of
+     * the two it is asking about.
+     */
+    async isFocused() {
+        return (await this.host()).isFocused();
+    }
+    /**
+     * Click the node — which SELECTS it. A disabled node, and any node of a
+     * `selectionMode="none"` tree, ignores the click.
+     *
+     * In multi mode a plain click REPLACES the selection rather than adding to it (the
+     * component's deliberate choice: one selected node clicked again clears it, and any
+     * other click starts over from that node). {@link ctrlClick} is how a selection is
+     * accumulated.
+     */
+    async click() {
+        return (await this.host()).click();
+    }
+    /**
+     * Ctrl-click the node — ADDS it to the selection, or removes it, in multi mode.
+     *
+     * The component takes Cmd as well as Ctrl; the harness sends Ctrl because a unit
+     * test has no platform. In single mode it behaves exactly like {@link click}.
+     */
+    async ctrlClick() {
+        return (await this.host()).click({ control: true });
+    }
+    /** The branch's toggle button, or a failure that says this row is a leaf. */
+    async toggleElement() {
+        // `button` is load-bearing: a leaf renders a `<span>` with the same
+        // `.wr-tree__toggle` class to hold the indent, and taking that for a control
+        // would report every leaf as a branch that refused to open.
+        const toggle = await this.locatorForOptional('button.wr-tree__toggle')();
+        if (!toggle) {
+            throw new Error(`WrTreeNodeHarness: "${await this.getLabel()}" is a leaf — there is no branch to open or close.`);
+        }
+        return toggle;
+    }
+    /** A numeric attribute every row carries, or a failure that says the row is broken. */
+    async announcedNumber(attribute) {
+        const value = await (await this.host()).getAttribute(attribute);
+        if (value === null) {
+            throw new Error(`WrTreeNodeHarness: this row announces no \`${attribute}\`. Every row of a \`<wr-tree>\` carries ` +
+                'one, so a missing value is a rendering fault rather than a state worth reporting as null.');
+        }
+        return Number.parseInt(value, 10);
+    }
+}
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+/** How many levels {@link WrTreeHarness.expandAll} is willing to walk. */
+const MAX_EXPAND_PASSES = 20;
+/**
+ * Test harness for `<wr-tree>`, with {@link WrTreeNodeHarness} for one row.
+ *
+ * The component has two render shapes and this harness covers both:
+ * - `openOn="inline"` (default) — the rows live in the host, and the tree is always
+ *   showing them.
+ * - `openOn="overlay"` — a `role="combobox"` trigger opens a panel that is a template
+ *   portal in the shared overlay container, a sibling of the whole app. Nothing in it
+ *   is a descendant of the host, so every row is read through the document root,
+ *   SCOPED by the `aria-controls` id the trigger publishes — which is what keeps two
+ *   trees on one page from answering with each other's nodes.
+ *
+ * A tree is data-driven and projects nothing, so the scoped loader exists to point the
+ * node queries at the right shape rather than to reach a consumer's own components: the
+ * inherited `getHarness(…)` resolves wherever THIS tree's rows are, and there is nothing
+ * else in there.
+ *
+ * Two things the harness cannot do, both jsdom rather than the component:
+ * - it never clicks a row by coordinate, and it drives the cursor with the KEYBOARD,
+ *   which is the accessible path anyway. There is no layout in a unit test, so a
+ *   hit test would answer with nothing.
+ * - it offers no SCROLL for a windowed tree. jsdom does remember a `scrollTop` write,
+ *   but it fires no `scroll` event for it, so the tree — which learns its offset from
+ *   that event — would not move until the caller also dispatched one and waited a
+ *   frame: a scroll gesture that only works because the test faked the notification.
+ *   The keyboard moves the window honestly instead — see {@link focusLast}. (jsdom has
+ *   no `Element.scrollTo` at all, which the tree calls while windowed, so a spec for
+ *   that shape has to stub it.)
+ *
+ * @example
+ * ```ts
+ * const tree = await loader.getHarness(WrTreeHarness);
+ *
+ * await (await tree.getNode({ label: 'src' })).expand();
+ * await tree.selectNode({ label: 'main.ts' });
+ *
+ * expect(await tree.getSelectedLabels()).toEqual(['main.ts']);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+class WrTreeHarness extends ContentContainerComponentHarness {
+    static hostSelector = 'wr-tree';
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options = {}) {
+        return new HarnessPredicate(WrTreeHarness, options)
+            .addOption('text', options.text, (harness, text) => HarnessPredicate.stringMatches(harness.triggerTextIfAny(), text))
+            .addOption('nodeLabel', options.nodeLabel, async (harness, label) => {
+            for (const shown of await harness.nodeLabelsIfShowing()) {
+                if (await HarnessPredicate.stringMatches(shown, label))
+                    return true;
+            }
+            return false;
+        })
+            .addOption('disabled', options.disabled, async (harness, disabled) => (await harness.isDisabled()) === disabled)
+            .addOption('open', options.open, async (harness, open) => (await harness.isOpen()) === open);
+    }
+    /** Whether this tree is the combobox shape (`openOn="overlay"`) rather than inline. */
+    async isOverlay() {
+        return (await this.host()).hasClass('wr-tree--combobox');
+    }
+    /**
+     * Whether the rows are showing.
+     *
+     * From the trigger's `aria-expanded` rather than the `--open` modifier: both are
+     * public, but that attribute is the promise the combobox makes to a screen reader.
+     * An inline tree is always open — its rows are part of the host and there is
+     * nothing to open or close.
+     */
+    async isOpen() {
+        if (!(await this.isOverlay()))
+            return true;
+        return (await (await this.trigger()).getAttribute('aria-expanded')) === 'true';
+    }
+    /**
+     * Open the panel. An already-open tree — and every inline one — is left alone.
+     *
+     * Note for a spec with two overlay trees: this clicks, and a click is an outside
+     * pointer event for every other open overlay, so it closes any panel already up.
+     * There is no second gesture to swap in: the trigger is opened by its `click`
+     * handler, and while a real keyboard user reaches that through a `<button>`'s native
+     * activation, a SYNTHETIC Enter / Space never produces a click — so a harness cannot
+     * open a panel any other way.
+     */
+    async open() {
+        if (await this.isOpen())
+            return;
+        await (await this.trigger()).click();
+        if (await this.isOpen())
+            return;
+        throw new Error('WrTreeHarness.open(): the panel did not open. A disabled tree refuses the trigger and closes any ' +
+            'panel that was up, so check `disabled` first.');
+    }
+    /** Close the panel with Escape. An already-closed tree is left alone. */
+    async close() {
+        // Not a no-op for an inline tree: asking to close one means the spec believes it
+        // has a panel, and it does not.
+        const trigger = await this.trigger();
+        if (!(await this.isOpen()))
+            return;
+        // Escape reaches the tree through the CDK's keyboard dispatcher, which hands it to
+        // the top-most overlay — so it does not matter that focus may be on a row inside.
+        await trigger.sendKeys(TestKey.ESCAPE);
+    }
+    /**
+     * Whether the tree refuses interaction.
+     *
+     * The host modifier is the only answer both shapes carry: an inline tree has no
+     * control of its own to mark `disabled`, and a closed overlay tree has no rows to
+     * read `aria-disabled` from. The rows do announce it — see
+     * {@link WrTreeNodeHarness.isDisabled}.
+     */
+    async isDisabled() {
+        return (await this.host()).hasClass('wr-tree--disabled');
+    }
+    /**
+     * Whether the tree takes more than one selected node.
+     *
+     * From the list's `aria-multiselectable`, which is what a screen reader acts on. The
+     * list does not exist while an overlay panel is closed, so the host modifier answers
+     * then — it is only painted in the combobox shape, which is exactly the shape that
+     * can be asked while closed.
+     */
+    async isMultiple() {
+        if (await this.isOpen()) {
+            return (await (await this.list()).getAttribute('aria-multiselectable')) === 'true';
+        }
+        return (await this.host()).hasClass('wr-tree--multi');
+    }
+    /**
+     * How much the tree lets you select.
+     *
+     * `'none'` is not "nothing selected": it is a tree whose rows announce no
+     * `aria-selected` at all, and telling that from `'single'` needs a row — so an empty
+     * tree throws rather than guessing.
+     */
+    async getSelectionMode() {
+        if (await this.isMultiple())
+            return 'multi';
+        const [first] = await this.getNodes();
+        if (!first) {
+            throw new Error('WrTreeHarness.getSelectionMode(): this tree renders no nodes, and single vs none is only visible ' +
+                'on a row — `selectionMode="none"` is the absence of `aria-selected`, so there is nothing to read.');
+        }
+        return (await first.isSelectable()) ? 'single' : 'none';
+    }
+    /**
+     * Whether the list is WINDOWED right now.
+     *
+     * Read from the list's modifier rather than from the input, and that is the point:
+     * `virtualScroll` only takes effect when there is something to window, so an empty
+     * tree renders the plain shape however the input is set.
+     */
+    async isVirtual() {
+        return (await this.list()).hasClass('wr-tree__list--virtual');
+    }
+    /**
+     * The role the list announces — `tree`.
+     *
+     * Worth asking: rendered without it, the rows are a bag of names, identical on
+     * screen and structureless to anyone not looking at it.
+     */
+    async getRole() {
+        return (await this.list()).getAttribute('role');
+    }
+    /**
+     * What the trigger shows as the selection: the chip labels joined by `', '` in multi
+     * mode, the label in single mode, and `''` when nothing is selected (the placeholder
+     * is showing). The `+N more` chip a `maxTagCount` produces is NOT part of it — it is
+     * a count rather than a selection, and {@link getOverflowText} reads it. Inline trees
+     * have no trigger and throw.
+     */
+    async getValueText() {
+        await this.trigger();
+        const chips = await this.getChipLabels();
+        if (chips.length > 0)
+            return chips.join(', ');
+        const value = await this.locatorForOptional('.wr-tree__value')();
+        return value ? value.text() : '';
+    }
+    /** The placeholder, or `null` when a selection is hiding it. */
+    async getPlaceholder() {
+        await this.trigger();
+        const placeholder = await this.locatorForOptional('.wr-tree__placeholder')();
+        return placeholder ? placeholder.text() : null;
+    }
+    /**
+     * The chip labels on the trigger, in order (multi mode).
+     *
+     * The `+N more` overflow chip is not one of them — it is a count, not a selection.
+     * {@link getOverflowText} reads it.
+     */
+    async getChipLabels() {
+        await this.trigger();
+        const labels = await this.locatorForAll('.wr-tree__chip-label')();
+        return Promise.all(labels.map(label => label.text()));
+    }
+    /**
+     * The `+N more` chip's text, or `null` when every selected node has a chip of its
+     * own. Only a `maxTagCount` below the number selected produces one.
+     */
+    async getOverflowText() {
+        await this.trigger();
+        const more = await this.locatorForOptional('.wr-tree__chip--more')();
+        return more ? more.text() : null;
+    }
+    /** Remove one chip by its label. */
+    async removeChip(label) {
+        const labels = await this.getChipLabels();
+        const index = labels.indexOf(label);
+        if (index < 0) {
+            throw new Error(`WrTreeHarness.removeChip(): no chip labelled "${label}". The trigger shows [${labels.join(', ')}] — ` +
+                'a selection past `maxTagCount` has no chip to remove.');
+        }
+        // Label and remove control are emitted once per chip by the same loop, so the two
+        // lists line up by index.
+        const removes = await this.locatorForAll('.wr-tree__chip-remove')();
+        await removes[index].click();
+    }
+    /** Click the clear (×) control on the trigger. */
+    async clear() {
+        await this.trigger();
+        const clear = await this.locatorForOptional('.wr-tree__clear')();
+        if (!clear) {
+            throw new Error('WrTreeHarness.clear(): this trigger has no clear control — `clearable` is off, nothing is ' +
+                'selected, or the tree is disabled.');
+        }
+        await clear.click();
+    }
+    /**
+     * The nodes currently rendered, in the order they are shown.
+     *
+     * A collapsed branch's children are not rendered at all, so this is the VISIBLE
+     * tree — expand first to reach deeper.
+     *
+     * While {@link isVirtual} is true it is narrower still: the list holds only the
+     * window around the scroll offset — padded by a spacer at whichever end has rows
+     * outside it, so a window resting at the top has one and a window in the middle has
+     * two — and this returns the WINDOW, not the dataset. Nothing in the DOM carries a
+     * total —
+     * `aria-setsize` counts a SIBLING GROUP, not the flat list — so the harness cannot
+     * offer one; {@link WrTreeNodeHarness.getIndex} places each row in the full visible
+     * list, and the `[nodes]` data is where the total actually lives.
+     *
+     * Throws while an overlay panel is closed: the rows do not exist anywhere until it
+     * opens, and an empty array reads like a tree that rendered nothing.
+     */
+    async getNodes(filters = {}) {
+        return this.getAllHarnesses(WrTreeNodeHarness.with(filters));
+    }
+    /** The labels of the nodes currently rendered, in order. */
+    async getNodeLabels() {
+        const nodes = await this.getNodes();
+        return Promise.all(nodes.map(node => node.getLabel()));
+    }
+    /** The first node matching the filters, or a failure that says what is showing. */
+    async getNode(filters) {
+        const [node] = await this.getNodes(filters);
+        if (!node) {
+            const showing = await this.getNodeLabels();
+            throw new Error(`WrTreeHarness.getNode(): no node matched ${JSON.stringify(filters)}. The tree is showing ` +
+                `[${showing.join(', ')}] — a node inside a collapsed branch is not rendered at all, and a ` +
+                'windowed tree only renders its window.');
+        }
+        return node;
+    }
+    /**
+     * Open the panel if needed, then select the first node matching the filters.
+     *
+     * `additive` ctrl-clicks instead, which is how a multi-mode selection is built up: a
+     * plain click there REPLACES the selection, by the component's own choice.
+     *
+     * Throws rather than clicking into the void on a disabled node or a
+     * `selectionMode="none"` tree — both ignore the click, and the silence turns into a
+     * confusing failure at the next assertion. Reach for `getNode().click()` when
+     * proving exactly that.
+     */
+    async selectNode(filters, options = {}) {
+        await this.open();
+        const node = await this.getNode(filters);
+        const label = await node.getLabel();
+        if (!(await node.isSelectable())) {
+            throw new Error(`WrTreeHarness.selectNode(): "${label}" announces no selected state, so this tree is in ` +
+                'selectionMode="none" — clicking it cannot select anything.');
+        }
+        if (await node.isDisabled()) {
+            throw new Error(`WrTreeHarness.selectNode(): "${label}" is disabled and the tree ignores the click. A disabled ` +
+                'TREE disables every node — check isDisabled() on the tree too.');
+        }
+        await (options.additive === true ? node.ctrlClick() : node.click());
+    }
+    /**
+     * The labels of the selected nodes, in row order.
+     *
+     * Only among the rows that are RENDERED: a selected node inside a collapsed branch,
+     * or outside a window, is not here. The `[(selected)]` model is the whole set.
+     */
+    async getSelectedLabels() {
+        const nodes = await this.getNodes({ selected: true });
+        return Promise.all(nodes.map(node => node.getLabel()));
+    }
+    /**
+     * Open every branch, level by level — each pass reveals the next one down.
+     *
+     * Refuses on a windowed tree instead of half-doing it: only the window is rendered,
+     * so the branches outside it cannot be reached from the DOM at all. Write the
+     * `[(expanded)]` model there.
+     */
+    async expandAll() {
+        if (await this.isVirtual()) {
+            throw new Error('WrTreeHarness.expandAll(): a windowed tree renders only its window, so this cannot reach the ' +
+                'branches outside it. Set the `[(expanded)]` model instead.');
+        }
+        for (let pass = 0; pass < MAX_EXPAND_PASSES; pass++) {
+            const collapsed = await this.getNodes({ expanded: false });
+            if (collapsed.length === 0)
+                return;
+            for (const node of collapsed)
+                await node.expand();
+        }
+        throw new Error(`WrTreeHarness.expandAll(): still finding closed branches after ${MAX_EXPAND_PASSES} levels — is the ` +
+            'node data recursive?');
+    }
+    /**
+     * The label of the node the keyboard cursor is on, or `null`.
+     *
+     * Read the way the shape publishes it: a windowed tree keeps focus on the list and
+     * names the row with `aria-activedescendant` (which goes `null` while the cursor has
+     * been scrolled out of the window, so the reference never dangles at a row that was
+     * removed), while a plain one hands the single tab stop to the cursor row.
+     */
+    async getActiveNodeLabel() {
+        const nodes = await this.getNodes();
+        if (await this.isVirtual()) {
+            const active = await (await this.list()).getAttribute('aria-activedescendant');
+            if (!active)
+                return null;
+            for (const node of nodes) {
+                if ((await node.getId()) === active)
+                    return node.getLabel();
+            }
+            return null;
+        }
+        for (const node of nodes) {
+            if (await node.isActive())
+                return node.getLabel();
+        }
+        return null;
+    }
+    /** Move the cursor down one row — ArrowDown. Stops at the last row. */
+    async focusNext() {
+        await this.press(TestKey.DOWN_ARROW);
+    }
+    /** Move the cursor up one row — ArrowUp. Stops at the first row. */
+    async focusPrevious() {
+        await this.press(TestKey.UP_ARROW);
+    }
+    /** Move the cursor to the first row — Home. */
+    async focusFirst() {
+        await this.press(TestKey.HOME);
+    }
+    /**
+     * Move the cursor to the last row — End.
+     *
+     * On a windowed tree this also moves the WINDOW: the tree writes its scroll offset
+     * synchronously so the row it is about to point at exists in the same change
+     * detection pass. It is the honest way to reach the far end of a window in a unit
+     * test — jsdom keeps a `scrollTop` write but never fires the `scroll` event the tree
+     * listens for, so a scroll gesture would move the window only for a test that also
+     * dispatched the notification itself.
+     */
+    async focusLast() {
+        await this.press(TestKey.END);
+    }
+    /**
+     * ArrowRight on the cursor row — the APG's one key with two jobs: it OPENS a closed
+     * branch, and on an already-open one it steps into the first child. A leaf ignores
+     * it.
+     *
+     * These two send the PHYSICAL key, because that is what a keyboard has. Under
+     * `dir="rtl"` the tree follows the indent and swaps the pair, so a spec exercising
+     * an RTL tree opens with {@link collapseActive} and closes with this one. The
+     * names describe the LTR job, which is the one worth naming.
+     */
+    async expandActive() {
+        await this.press(TestKey.RIGHT_ARROW);
+    }
+    /**
+     * ArrowLeft on the cursor row — CLOSES an open branch, and on anything else steps
+     * out to the parent row. A root-level leaf ignores it.
+     *
+     * Physical, and mirrored by the component under `dir="rtl"` — see
+     * {@link expandActive}.
+     */
+    async collapseActive() {
+        await this.press(TestKey.LEFT_ARROW);
+    }
+    /**
+     * Select the cursor row from the keyboard — Enter.
+     *
+     * `additive` holds Ctrl, the keyboard twin of {@link WrTreeNodeHarness.ctrlClick}:
+     * in multi mode a plain Enter replaces the selection, Ctrl-Enter adds to it. A
+     * disabled row is skipped by the component, silently — assert the model.
+     */
+    async selectActive(options = {}) {
+        const list = await this.list();
+        if (options.additive === true) {
+            await list.sendKeys({ control: true }, TestKey.ENTER);
+            return;
+        }
+        await list.sendKeys(TestKey.ENTER);
+    }
+    /**
+     * The loader every node query runs through — the host inline, THIS tree's overlay
+     * panel otherwise.
+     *
+     * Scoped by the published panel id rather than by `.wr-tree-panel`: the overlay
+     * container is shared, so a bare class query would answer with whichever tree
+     * happened to open first.
+     */
+    async getRootHarnessLoader() {
+        if (!(await this.isOverlay()))
+            return super.getRootHarnessLoader();
+        return this.documentRootLocatorFactory().harnessLoaderFor(`#${await this.panelId()}`);
+    }
+    /**
+     * Send a key to the `role="tree"` list.
+     *
+     * The list owns the keydown handler in both patterns — the roving-tabindex one
+     * focuses a row, whose event bubbles to exactly here — so this is the honest target
+     * either way, and the one that works when jsdom has left real focus on `<body>`.
+     */
+    async press(key) {
+        await (await this.list()).sendKeys(key);
+    }
+    /**
+     * The `<ul role="tree">` of THIS tree — in the host inline, in this tree's own
+     * overlay panel otherwise.
+     */
+    async list() {
+        if (!(await this.isOverlay()))
+            return this.locatorFor('.wr-tree__list')();
+        return this.documentRootLocatorFactory().locatorFor(`#${await this.panelId()} .wr-tree__list`)();
+    }
+    /** The combobox trigger, or a failure that says this tree renders inline. */
+    async trigger() {
+        const trigger = await this.locatorForOptional('.wr-tree__trigger')();
+        if (!trigger) {
+            throw new Error('WrTreeHarness: this tree renders inline, so it has no trigger, no chips and no panel — its rows ' +
+                'are part of the host. `openOn="overlay"` is the combobox shape.');
+        }
+        return trigger;
+    }
+    /** The id the trigger publishes as `aria-controls`, which its panel carries. */
+    async panelId() {
+        const id = await (await this.trigger()).getAttribute('aria-controls');
+        if (!id) {
+            throw new Error('WrTreeHarness: the trigger publishes no `aria-controls` id, so its panel cannot be told apart ' +
+                "from another tree's.");
+        }
+        if (!(await this.isOpen())) {
+            throw new Error('WrTreeHarness: the panel is closed — call open() first. A closed tree renders no rows.');
+        }
+        return id;
+    }
+    /** The trigger's text for the `text` filter, or `null` for an inline tree (which never matches). */
+    async triggerTextIfAny() {
+        const trigger = await this.locatorForOptional('.wr-tree__trigger')();
+        return trigger ? this.getValueText() : null;
+    }
+    /** The rendered labels for the `nodeLabel` filter — a closed tree matches nothing rather than failing. */
+    async nodeLabelsIfShowing() {
+        if (!(await this.isOpen()))
+            return [];
+        return this.getNodeLabels();
+    }
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { WrTreeHarness, WrTreeNodeHarness };
+//# sourceMappingURL=ngwr-tree-testing.mjs.map