ngwr 10.2.1 → 11.1.0

package/fesm2022/ngwr-context-menu-testing.mjs

@@ -0,0 +1,631 @@
+import { ComponentHarness, HarnessPredicate, TestKey, ContentContainerComponentHarness } 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
+ */
+/** How long the waiters poll before giving up, in ms. Generous next to the 500ms hold. */
+const DEFAULT_TIMEOUT = 1000;
+/** How often they re-check, in ms. */
+const POLL_STEP = 10;
+/**
+ * The real `setTimeout`, captured at module load — before a spec can install
+ * fake timers.
+ *
+ * Every delay in this component family is wall-clock: a plain `setTimeout` inside
+ * the directive for the 500ms long-press hold, the 120ms submenu hover and the
+ * 220ms exit animation the pane is held alive through, and a `performance.now()`
+ * comparison for the 200ms window in which outside presses are ignored — no timer
+ * behind that one, just elapsed time. Under zoneless change detection `whenStable()` resolves
+ * without waiting for a macrotask, so the waiters have to let REAL time pass —
+ * reading a faked global instead would mean the sleep never fires at all, and
+ * the harness would hang where it should fail with the message it prepared.
+ */
+const realSetTimeout = globalThis.setTimeout;
+/** Let real time pass, whatever a spec has done to the global clock. */
+function sleep(ms) {
+    return new Promise(resolve => {
+        realSetTimeout(resolve, ms);
+    });
+}
+
+/**
+ * @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 `<wr-context-menu-item>` inside a context menu.
+ *
+ * The selector is the CLASS rather than the element, matching
+ * `.wr-dropdown-item`: it is public API, and it is on the host whichever way the
+ * item was written. A `<wr-context-menu-divider>` is deliberately not one of
+ * these — it announces `role="separator"` rather than `menuitem`, so it is not
+ * something a user can land on and not a member of the item list
+ * (`WrContextMenuHarness.getDividerCount()` counts those).
+ *
+ * An item that owns a `[submenu]` is also the way INTO it: the submenu is a
+ * second overlay pane, a sibling of the root menu rather than a child of the
+ * item, and it is reached through the id the item publishes as `aria-controls`
+ * while it is open. `getSubmenuItems()` answers with these same harnesses, so a
+ * chain of any depth is walked by repeating the call.
+ *
+ * @example
+ * ```ts
+ * const [cut, copy, more] = await menu.getItems();
+ *
+ * expect(await copy.isDisabled()).toBe(true);
+ * await more.openSubmenu();
+ * await more.clickSubmenuItem({ text: 'Duplicate' });
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+class WrContextMenuItemHarness extends ComponentHarness {
+    /** The class the item paints on its host. */
+    static hostSelector = '.wr-context-menu-item';
+    /** Build a predicate that narrows the query. */
+    static with(options = {}) {
+        return new HarnessPredicate(WrContextMenuItemHarness, options)
+            .addOption('text', options.text, (harness, text) => HarnessPredicate.stringMatches(harness.getText(), text))
+            .addOption('disabled', options.disabled, async (harness, disabled) => (await harness.isDisabled()) === disabled)
+            .addOption('hasSubmenu', options.hasSubmenu, async (harness, hasSubmenu) => (await harness.hasSubmenu()) === hasSubmenu);
+    }
+    /**
+     * The item's label, trimmed.
+     *
+     * Read from the label span, not from the host: a registered icon is written in
+     * with `innerHTML`, so an icon carrying a `<title>` would otherwise become
+     * part of the answer.
+     */
+    async getText() {
+        return (await this.locatorFor('.wr-context-menu-item__label')()).text();
+    }
+    /** The role the item announces — `menuitem`. */
+    async getRole() {
+        return (await this.host()).getAttribute('role');
+    }
+    /**
+     * Whether the item refuses activation.
+     *
+     * `aria-disabled`, not the `--disabled` modifier class: both are there, and
+     * this is the one a screen reader is told.
+     */
+    async isDisabled() {
+        return (await (await this.host()).getAttribute('aria-disabled')) === 'true';
+    }
+    /**
+     * Whether the item owns a nested submenu.
+     *
+     * Read from `aria-haspopup`, not from the `--has-submenu` class or the
+     * `[submenu]` input: the input is always BOUND (it takes a
+     * `<wr-context-menu>` reference), so it never reaches the DOM, and the ARIA
+     * property is what announces the item as a drill-down.
+     */
+    async hasSubmenu() {
+        return (await (await this.host()).getAttribute('aria-haspopup')) === 'menu';
+    }
+    /** Whether this item's submenu is showing, per `aria-expanded`. */
+    async isSubmenuOpen() {
+        return (await (await this.host()).getAttribute('aria-expanded')) === 'true';
+    }
+    /** Whether the item shows a leading icon. */
+    async hasIcon() {
+        return (await this.locatorForOptional('.wr-context-menu-item__icon')()) !== null;
+    }
+    /** The leading icon's registered name, or `null` when the item has no icon. */
+    async getIconName() {
+        const icon = await this.locatorForOptional('.wr-context-menu-item__icon')();
+        // `<wr-icon>` reflects the name it was asked for as `data-icon`, whether or not
+        // that name is registered — so this answers what the item MEANT to draw.
+        return icon ? icon.getAttribute('data-icon') : null;
+    }
+    /**
+     * Whether the item holds focus.
+     *
+     * Worth asking, because nothing in this component ever puts it there: unlike
+     * `<wr-dropdown-menu>`, a context menu does not focus its first item on open
+     * and has no arrow-key cursor between items. Focus lands on an item when
+     * something sends it a key — which every keyboard method here does, since the
+     * CDK focuses an element before typing into it.
+     */
+    async isFocused() {
+        return (await this.host()).isFocused();
+    }
+    /**
+     * Click the item. A disabled item throws instead.
+     *
+     * Refusing is the only honest answer. A browser never delivers the click at all:
+     * `pointer-events: none` on the `--disabled` modifier takes the row out of the
+     * hit test. jsdom loads no stylesheets, so a click dispatched here DOES land on
+     * the host, and while the component's own handler refuses it (a disabled item
+     * dismisses nothing), the consumer's `(click)` on that same host is a separate
+     * listener and runs — so the spec would record an activation that cannot happen
+     * in a browser. Assert `isDisabled()` instead.
+     *
+     * Activating a LEAF item dismisses the whole chain, root menu included. An item
+     * that owns a submenu is not a leaf: clicking it does nothing at all (hover or
+     * `openSubmenu()` is how it opens).
+     */
+    async click() {
+        if (await this.isDisabled()) {
+            throw new Error(`WrContextMenuItemHarness.click(): "${await this.getText()}" is disabled, so clicking it would ` +
+                'report behaviour a browser cannot produce — the pointer is stopped by CSS, which jsdom does ' +
+                'not load. Assert isDisabled() instead.');
+        }
+        return (await this.host()).click();
+    }
+    /**
+     * Press Enter on the item — the keyboard equivalent of a click, and the route
+     * a spec should prefer, since it needs no hit test.
+     *
+     * Deliberately does NOT refuse a disabled item the way `click()` does: the
+     * component guards the keyboard path itself, so the key can be sent honestly
+     * and a spec can assert that nothing happened. On an item that owns a submenu
+     * this OPENS the submenu rather than activating the row, which is the APG
+     * behaviour — activating it would close the menu and leave the submenu
+     * unreachable from the keyboard.
+     */
+    async activateByKeyboard() {
+        return (await this.host()).sendKeys(TestKey.ENTER);
+    }
+    /**
+     * Open this item's submenu with the right arrow and wait until it says so.
+     *
+     * The keyboard, not the pointer: it opens with no delay (hover waits out
+     * 120ms — `openSubmenuByHover()` covers that path) and needs no coordinates,
+     * which jsdom could not supply anyway. Sending the key focuses the item first,
+     * exactly as a roving cursor would have.
+     */
+    async openSubmenu(timeout = DEFAULT_TIMEOUT) {
+        await this.assertHasSubmenu('openSubmenu');
+        if (await this.isSubmenuOpen())
+            return;
+        await (await this.host()).sendKeys(TestKey.RIGHT_ARROW);
+        if (await this.isSubmenuOpen())
+            return;
+        if (await this.settled(true, timeout))
+            return;
+        throw new Error(`WrContextMenuItemHarness.openSubmenu(): "${await this.getText()}" did not open its submenu within ` +
+            `${timeout}ms. A disabled item refuses the key outright — check isDisabled().`);
+    }
+    /**
+     * Open this item's submenu by resting the pointer on it, the gesture a mouse
+     * user actually makes, and wait out the hover delay.
+     */
+    async openSubmenuByHover(timeout = DEFAULT_TIMEOUT) {
+        await this.assertHasSubmenu('openSubmenuByHover');
+        if (await this.isSubmenuOpen())
+            return;
+        await (await this.host()).hover();
+        if (await this.settled(true, timeout))
+            return;
+        throw new Error(`WrContextMenuItemHarness.openSubmenuByHover(): "${await this.getText()}" did not open its submenu ` +
+            `within ${timeout}ms. The hover path is a real 120ms timer, so a spec on fake timers has to ` +
+            'advance the clock itself; a disabled item ignores the pointer entirely.');
+    }
+    /** Close this item's submenu with the left arrow. An item without one open is left alone. */
+    async closeSubmenu(timeout = DEFAULT_TIMEOUT) {
+        if (!(await this.isSubmenuOpen()))
+            return;
+        await (await this.host()).sendKeys(TestKey.LEFT_ARROW);
+        if (await this.settled(false, timeout))
+            return;
+        throw new Error(`WrContextMenuItemHarness.closeSubmenu(): "${await this.getText()}" still reports its submenu open ` +
+            `after ${timeout}ms.`);
+    }
+    /**
+     * The items in THIS item's submenu, in DOM order.
+     *
+     * Throws while the submenu is shut, and while the item owns none: both would
+     * otherwise answer with an empty array, which reads like a submenu that
+     * rendered nothing and fails somewhere else entirely.
+     */
+    async getSubmenuItems(filters = {}) {
+        const loader = await this.submenuLoader();
+        return loader.getAllHarnesses(WrContextMenuItemHarness.with(filters));
+    }
+    /** The labels of the items in this item's submenu, in DOM order. */
+    async getSubmenuItemTexts() {
+        const items = await this.getSubmenuItems();
+        return Promise.all(items.map(item => item.getText()));
+    }
+    /**
+     * Open the submenu if it is shut, then click the first item in it matching the
+     * filters.
+     *
+     * Picking a leaf dismisses the whole chain — this item's submenu and the root
+     * menu with it.
+     */
+    async clickSubmenuItem(filters) {
+        await this.openSubmenu();
+        const [item] = await this.getSubmenuItems(filters);
+        if (!item) {
+            const offered = await this.getSubmenuItemTexts();
+            throw new Error(`WrContextMenuItemHarness.clickSubmenuItem(): no item matched ${JSON.stringify(filters)}. ` +
+                `The submenu of "${await this.getText()}" offers: ${offered.join(', ')}.`);
+        }
+        await item.click();
+    }
+    /**
+     * A loader scoped to THIS item's submenu pane.
+     *
+     * Scoped by the published id rather than by `.wr-context-menu`: every pane in
+     * the chain — the root menu and each open submenu — carries that class in one
+     * shared overlay container, so a class query would answer with whichever
+     * opened first.
+     */
+    async submenuLoader() {
+        return this.documentRootLocatorFactory().harnessLoaderFor(`#${await this.submenuId()}`);
+    }
+    /** The id this item publishes as `aria-controls`, which its open submenu carries. */
+    async submenuId() {
+        const id = await (await this.host()).getAttribute('aria-controls');
+        if (!id) {
+            const label = await this.getText();
+            throw new Error(`WrContextMenuItemHarness: "${label}" has no submenu showing. An item publishes aria-controls only ` +
+                'while its submenu is open — call openSubmenu() first, and check that it owns one at all with ' +
+                'hasSubmenu().');
+        }
+        return id;
+    }
+    /** Fail early, and by name, when the item is not a drill-down at all. */
+    async assertHasSubmenu(method) {
+        if (await this.hasSubmenu())
+            return;
+        throw new Error(`WrContextMenuItemHarness.${method}(): "${await this.getText()}" owns no submenu, so there is ` +
+            'nothing to open. An item that does advertises it with aria-haspopup="menu" — hasSubmenu().');
+    }
+    /** Poll until `isSubmenuOpen()` reports `open`, and say whether it did. */
+    async settled(open, timeout) {
+        for (let waited = 0; waited <= timeout; waited += POLL_STEP) {
+            if ((await this.isSubmenuOpen()) === open)
+                return true;
+            await sleep(POLL_STEP);
+            await this.forceStabilize();
+        }
+        return false;
+    }
+}
+
+/**
+ * @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 long to sit still before an outside press is allowed to dismiss the menu.
+ *
+ * The directive ignores outside events for 200ms after opening, because the very
+ * right-click that opened the menu still has its own `mouseup` / `auxclick`
+ * pending — without the window, lifting the finger would shut the menu again.
+ */
+const OUTSIDE_GUARD_MS = 250;
+/**
+ * Test harness for `[wrContextMenu]` — the right-click target, and the menu it
+ * opens.
+ *
+ * The harness matches the TARGET, because that is the only part of a context
+ * menu in the fixture: `<wr-context-menu>` renders nothing of its own (it hands
+ * over an `<ng-template>` and hides its host), and the menu is portalled into the
+ * overlay container, a sibling of the whole app. So every item is read through
+ * the document root, scoped by the `aria-controls` id the target publishes while
+ * its menu is up — which is what keeps two menus on one page from answering with
+ * each other's items, and what keeps a re-opened menu from answering with the one
+ * still playing its exit animation.
+ *
+ * That scoped loader is also this harness's CONTENT loader, so
+ * `menu.getHarness(…)` resolves inside THIS menu: a component the consumer
+ * projected into the menu is reachable without the spec ever touching the
+ * overlay.
+ *
+ * **How it differs from `WrDropdownHarness`, its closest sibling.**
+ *
+ * - The gesture is a real `contextmenu` event, not a click — `open()` sends one,
+ *   and `openByLongPress()` covers the touch path. There is no toggle: a second
+ *   right-click re-opens the menu at the new pointer position.
+ * - Activating an item DISMISSES the menu (a dropdown's stays up), so
+ *   `clickItem()` leaves it closed.
+ * - Submenus are a first-class input here rather than a nested trigger, so they
+ *   are driven from {@link WrContextMenuItemHarness}.
+ * - The menu never takes focus: nothing focuses the first item and there is no
+ *   arrow-key cursor between items, so there is no `getFocusedItemText()` to ask
+ *   — see `WrContextMenuItemHarness.isFocused()`.
+ *
+ * **Timing.** The waits are real: a 500ms `setTimeout` for the long-press hold and
+ * another 220ms one for the exit animation the pane is held alive through, plus the
+ * outside-press window above — that one is a `performance.now()` comparison against
+ * the moment the menu opened rather than a timer, so only wall-clock time gets past
+ * it. The methods that must sit out real time say so; a spec on fake timers should
+ * drive the clock itself and read `isOpen()`.
+ *
+ * @example
+ * ```ts
+ * const menu = await loader.getHarness(WrContextMenuHarness.with({ text: 'Right-click me' }));
+ *
+ * await menu.open();
+ * expect(await menu.getItemTexts()).toEqual(['Cut', 'Copy', 'More']);
+ *
+ * await menu.clickItem({ text: 'Cut' });
+ * expect(await menu.isOpen()).toBe(false);
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+class WrContextMenuHarness extends ContentContainerComponentHarness {
+    /** The directive's host — whatever element the consumer put `[wrContextMenu]` on. */
+    static hostSelector = '.wr-context-menu-host';
+    /** Build a predicate that narrows the query. */
+    static with(options = {}) {
+        return new HarnessPredicate(WrContextMenuHarness, options)
+            .addOption('text', options.text, (harness, text) => HarnessPredicate.stringMatches(harness.getTargetText(), text))
+            .addOption('open', options.open, async (harness, open) => (await harness.isOpen()) === open);
+    }
+    /** The target's own visible text — the content that gets right-clicked. */
+    async getTargetText() {
+        return (await this.host()).text();
+    }
+    /**
+     * Whether this target's menu is showing.
+     *
+     * Read from the target rather than from the overlay, and that is the whole
+     * point: a closed menu's pane stays in the DOM for its exit animation, while
+     * the reference is dropped the instant the close begins. Asking the DOM
+     * "is a menu present" would answer `true` for a quarter of a second after every
+     * dismissal.
+     *
+     * So the answer is only as good as the directive's claim on `aria-controls`:
+     * put `[wrContextMenu]` on an element that publishes one of its own and the two
+     * fight over a single attribute.
+     */
+    async isOpen() {
+        return (await (await this.host()).getAttribute('aria-controls')) !== null;
+    }
+    /** The role the menu announces — `menu`. Throws while no menu is open. */
+    async getMenuRole() {
+        return (await this.menu()).getAttribute('role');
+    }
+    /**
+     * Everything the open menu renders as text, runs of whitespace collapsed.
+     *
+     * Wider than `getItemTexts()` on purpose: `<wr-context-menu>` projects whatever
+     * it is given, so a section heading or any other markup a consumer put between
+     * the items shows up here and in no item harness. Dividers contribute nothing —
+     * they render no text.
+     *
+     * Expect to match a FRAGMENT of this rather than the whole of it: Angular
+     * strips the whitespace between elements at compile time, so the labels run
+     * together (`'Pick oneAppleBanana'`). The collapsing here only tidies newlines
+     * inside a single block of projected text.
+     */
+    async getMenuText() {
+        return (await (await this.menu()).text()).replace(/\s+/g, ' ').trim();
+    }
+    /**
+     * Open the menu by right-clicking the target, the gesture the directive
+     * actually listens for (`contextmenu`, which is also what Shift+F10 sends).
+     *
+     * An already-open menu is left alone — `rightClick()` is the raw gesture if
+     * what you want is the re-open.
+     *
+     * Note for a spec with two targets: a `contextmenu` event anywhere is an
+     * outside pointer event for every OTHER open menu, so this dismisses them on
+     * the way in. `openByLongPress()` is the route that does not.
+     */
+    async open() {
+        if (await this.isOpen())
+            return;
+        await this.rightClick();
+        if (await this.isOpen())
+            return;
+        throw new Error('WrContextMenuHarness.open(): the right-click did not open a menu. The directive answers ' +
+            '`contextmenu` on its own host, so check this is the element you put [wrContextMenu] on. One ' +
+            'deliberate exception: a right-click within 700ms of a long-press open is swallowed, because touch ' +
+            'browsers fire a synthetic contextmenu after the hold.');
+    }
+    /**
+     * Send a `contextmenu` to the target whatever state the menu is in.
+     *
+     * On an open menu this re-opens it at the new pointer position — the previous
+     * pane is dismissed and a fresh one takes its place, which is why the harness
+     * scopes by a per-open id rather than by class: for the length of the exit
+     * animation both are in the container, the dying one first.
+     *
+     * The coordinates the CDK requires are all zeros, and meaningless: jsdom has no
+     * layout. Nothing here needs them — the event is dispatched on the element
+     * itself, no hit test involved.
+     */
+    async rightClick() {
+        return (await this.host()).rightClick(0, 0);
+    }
+    /**
+     * Open the menu with a touch long-press — hold a non-mouse pointer on the
+     * target for 500ms — and wait until it is up.
+     *
+     * Worth its own method rather than an argument to `open()`, for the reason the
+     * dropdown has `openByKeyboard()`: it is the only way to get TWO context menus
+     * open at once. The press emits no `click` / `auxclick` / `contextmenu`, so it
+     * is not an outside press for anyone else's menu, while a right-click is.
+     *
+     * The pointer fields the directive reads are assigned onto a synthetic event:
+     * what matters is a primary pointer that is not a mouse. Movement beyond 10px,
+     * a scroll, or an early lift cancels the hold in the component — none of which
+     * this does.
+     */
+    async openByLongPress(timeout = DEFAULT_TIMEOUT) {
+        if (await this.isOpen())
+            return;
+        const host = await this.host();
+        await host.dispatchEvent('pointerdown', {
+            pointerType: 'touch',
+            isPrimary: true,
+            clientX: 0,
+            clientY: 0,
+            pageX: 0,
+            pageY: 0,
+        });
+        const opened = await this.settled(true, timeout);
+        // The finger comes off once the menu is up — after the hold, so it reads as a
+        // completed long-press rather than the early lift that cancels one.
+        await host.dispatchEvent('pointerup');
+        if (opened)
+            return;
+        throw new Error(`WrContextMenuHarness.openByLongPress(): nothing opened within ${timeout}ms. The hold is a real 500ms ` +
+            'timer, so a spec on fake timers has to advance the clock itself and read isOpen().');
+    }
+    /**
+     * Dismiss the menu with Escape and wait until its pane has left the DOM.
+     *
+     * Escape is delivered by the CDK's keyboard dispatcher to the TOP-MOST overlay,
+     * so with a later menu (or any other overlay) open on top, this one keeps
+     * waiting its turn — that is what the throw below is about. The wait covers the
+     * 220ms exit animation, so a spec can assert afterwards that nothing lingers.
+     */
+    async close(timeout = DEFAULT_TIMEOUT) {
+        if (!(await this.isOpen()))
+            return;
+        // Captured first: the target drops the reference the instant the close starts,
+        // and the wait below still has to know which pane to watch.
+        const id = await this.menuId();
+        await (await this.host()).sendKeys(TestKey.ESCAPE);
+        if (await this.isOpen()) {
+            throw new Error('WrContextMenuHarness.close(): Escape did not dismiss the menu. The CDK keyboard dispatcher ' +
+                'delivers it to the TOP-MOST overlay only, so anything opened after this menu takes it first.');
+        }
+        return this.waitUntilGone(id, 'close', timeout);
+    }
+    /**
+     * Dismiss the menu by pressing outside it, the way a user gets rid of one, and
+     * wait until its pane has left the DOM.
+     *
+     * Sits out real time first: the directive ignores outside events for 200ms after
+     * opening, so the right-click that opened the menu cannot immediately close it
+     * again with its own trailing `auxclick`. The press then lands on the TARGET,
+     * which is outside the pane and therefore counts — the page background is not
+     * something a harness has a handle on. A target that carries a `(click)` of its
+     * own will see it fire, so assert on the dismissal rather than on that handler.
+     */
+    async closeByOutsidePress(timeout = DEFAULT_TIMEOUT) {
+        if (!(await this.isOpen()))
+            return;
+        const id = await this.menuId();
+        await sleep(OUTSIDE_GUARD_MS);
+        await this.forceStabilize();
+        await (await this.host()).click();
+        if (await this.isOpen()) {
+            throw new Error('WrContextMenuHarness.closeByOutsidePress(): the menu is still open. A press inside the pane is ' +
+                'not an outside press, and neither is one that started inside it — this one lands on the target.');
+        }
+        return this.waitUntilGone(id, 'closeByOutsidePress', timeout);
+    }
+    /**
+     * The items in this menu, in DOM order.
+     *
+     * Only this menu's own: an open submenu is a separate pane, so its items are
+     * `WrContextMenuItemHarness.getSubmenuItems()`, not part of this list. Dividers
+     * are not items either.
+     *
+     * Throws while the menu is shut — the items do not exist anywhere until the
+     * portal is attached, and an empty array reads like a menu that rendered
+     * nothing.
+     */
+    async getItems(filters = {}) {
+        return this.getAllHarnesses(WrContextMenuItemHarness.with(filters));
+    }
+    /** The labels of this menu's items, in DOM order. */
+    async getItemTexts() {
+        const items = await this.getItems();
+        return Promise.all(items.map(item => item.getText()));
+    }
+    /**
+     * How many separators this menu shows.
+     *
+     * Counted by `role="separator"` rather than by `.wr-context-menu-divider`, so a
+     * separator the consumer wrote themselves counts too — the role is what tells a
+     * screen reader where one group of items ends. A separator is never a member of
+     * `getItems()`.
+     */
+    async getDividerCount() {
+        const separators = await this.inMenuAll('[role="separator"]');
+        return separators.length;
+    }
+    /**
+     * Open the menu if it is shut, then click the first item matching the filters.
+     *
+     * Picking a leaf DISMISSES the menu — unlike a dropdown, which stays up. The
+     * dismissal is reported at once (the target drops its reference synchronously),
+     * while the pane plays its exit animation for another 220ms.
+     */
+    async clickItem(filters) {
+        await this.open();
+        const [item] = await this.getItems(filters);
+        if (!item) {
+            const offered = await this.getItemTexts();
+            throw new Error(`WrContextMenuHarness.clickItem(): no item matched ${JSON.stringify(filters)}. ` +
+                `The menu offers: ${offered.join(', ')}.`);
+        }
+        await item.click();
+    }
+    /**
+     * A loader scoped to THIS target's menu — the content loader every
+     * `HarnessLoader` method on this class runs through, `getItems()` included.
+     *
+     * Scoped by the published id rather than by `.wr-context-menu`: the overlay
+     * container is shared by every pane on the page, so a bare class query would
+     * answer with whichever menu opened first.
+     */
+    async getRootHarnessLoader() {
+        return this.documentRootLocatorFactory().harnessLoaderFor(`#${await this.menuId()}`);
+    }
+    /** This target's menu element in the overlay. */
+    async menu() {
+        return this.documentRootLocatorFactory().locatorFor(`#${await this.menuId()}`)();
+    }
+    /** Every element inside THIS menu matching the selector. */
+    async inMenuAll(selector) {
+        return this.documentRootLocatorFactory().locatorForAll(`#${await this.menuId()} ${selector}`)();
+    }
+    /** The id the target publishes as `aria-controls`, which its open menu carries. */
+    async menuId() {
+        const id = await (await this.host()).getAttribute('aria-controls');
+        if (!id) {
+            throw new Error('WrContextMenuHarness: no menu is open, so there is nothing inside it to read — call open() ' +
+                'first. The target publishes `aria-controls` only while its menu is up.');
+        }
+        return id;
+    }
+    /** Poll until the pane with this id has been disposed. */
+    async waitUntilGone(id, method, timeout) {
+        const locate = this.documentRootLocatorFactory().locatorForOptional(`#${id}`);
+        for (let waited = 0; waited <= timeout; waited += POLL_STEP) {
+            if ((await locate()) === null)
+                return;
+            await sleep(POLL_STEP);
+            await this.forceStabilize();
+        }
+        throw new Error(`WrContextMenuHarness.${method}(): the menu was still in the DOM ${timeout}ms after it closed. The ` +
+            'directive keeps the pane alive for its 220ms exit animation and disposes it on a real timer, so a ' +
+            'spec on fake timers has to advance the clock itself.');
+    }
+    /** Poll until `isOpen()` reports `open`, and say whether it did. */
+    async settled(open, timeout) {
+        for (let waited = 0; waited <= timeout; waited += POLL_STEP) {
+            if ((await this.isOpen()) === open)
+                return true;
+            await sleep(POLL_STEP);
+            await this.forceStabilize();
+        }
+        return false;
+    }
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { WrContextMenuHarness, WrContextMenuItemHarness };
+//# sourceMappingURL=ngwr-context-menu-testing.mjs.map