@baseline-ui/test-utils 0.61.0 → 0.63.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import * as _playwright_test from '@playwright/test';
+import * as playwright_test from 'playwright/test';
 import { Page, Locator, FrameLocator } from '@playwright/test';
 import { SinonSpy } from 'sinon';
 
@@ -29,57 +29,57 @@ interface ToBeAccessibleOptions {
     attachmentName?: string;
 }
 
-declare const expect: _playwright_test.Expect<{
-    toBeWithinDelta(this: _playwright_test.ExpectMatcherState, received: number, expected: number, delta: number): {
+declare const expect: playwright_test.Expect<{
+    toBeWithinDelta(this: playwright_test.ExpectMatcherState, received: number, expected: number, delta: number): {
         message: () => string;
         pass: true;
     } | {
         message: () => string;
         pass: false;
     };
-    toBeCalledOnce(this: _playwright_test.ExpectMatcherState, fn: SinonSpy): Promise<{
+    toBeCalledOnce(this: playwright_test.ExpectMatcherState, fn: SinonSpy): Promise<{
         message: () => string;
         pass: true;
     } | {
         message: () => string;
         pass: false;
     }>;
-    toBeCalledTwice(this: _playwright_test.ExpectMatcherState, fn: SinonSpy): Promise<{
+    toBeCalledTwice(this: playwright_test.ExpectMatcherState, fn: SinonSpy): Promise<{
         message: () => string;
         pass: true;
     } | {
         message: () => string;
         pass: false;
     }>;
-    toBeCalledThrice(this: _playwright_test.ExpectMatcherState, fn: SinonSpy): Promise<{
+    toBeCalledThrice(this: playwright_test.ExpectMatcherState, fn: SinonSpy): Promise<{
         message: () => string;
         pass: true;
     } | {
         message: () => string;
         pass: false;
     }>;
-    toBeCalledWith(this: _playwright_test.ExpectMatcherState, fn: SinonSpy, ...args: unknown[]): Promise<{
+    toBeCalledWith(this: playwright_test.ExpectMatcherState, fn: SinonSpy, ...args: unknown[]): Promise<{
         message: () => string;
         pass: true;
     } | {
         message: () => string;
         pass: false;
     }>;
-    toBeCalledWithExactly(this: _playwright_test.ExpectMatcherState, fn: SinonSpy, ...args: unknown[]): Promise<{
+    toBeCalledWithExactly(this: playwright_test.ExpectMatcherState, fn: SinonSpy, ...args: unknown[]): Promise<{
         message: () => string;
         pass: true;
     } | {
         message: () => string;
         pass: false;
     }>;
-    toBeCalled(this: _playwright_test.ExpectMatcherState, fn: SinonSpy): {
+    toBeCalled(this: playwright_test.ExpectMatcherState, fn: SinonSpy): {
         message: () => string;
         pass: true;
     } | {
         message: () => string;
         pass: false;
     };
-    toBeCalledTimes(this: _playwright_test.ExpectMatcherState, fn: SinonSpy, times: number): Promise<{
+    toBeCalledTimes(this: playwright_test.ExpectMatcherState, fn: SinonSpy, times: number): Promise<{
         message: () => string;
         pass: true;
     } | {
@@ -95,7 +95,7 @@ declare const expect: _playwright_test.Expect<{
         message: () => string;
         pass: false;
     }>;
-    toMatchClassTree(this: _playwright_test.ExpectMatcherState, locator: Locator, snapshotName?: string, options?: {
+    toMatchClassTree(this: playwright_test.ExpectMatcherState, locator: Locator, snapshotName?: string, options?: {
         prefix?: string | string[];
         ignoreHashed?: boolean;
     }): Promise<{
@@ -107,4 +107,285 @@ declare const expect: _playwright_test.Expect<{
     }>;
 }>;
 
-export { DEFAULT_CRITICAL_INCOMPLETE_RULES, DEFAULT_DISABLED_RULES, DEFAULT_WCAG_TAGS, type ToBeAccessibleOptions, expect };
+/**
+ * Either a Playwright `Page` or a `FrameLocator` — both expose the same
+ * locator-building API used by the testers. Component-test fixtures typically
+ * provide a `FrameLocator`; full E2E tests provide a `Page`.
+ */
+type Frame = Page | FrameLocator;
+
+/**
+ * Common options accepted by every component tester. Component testers extend
+ * this with their own optional fields (e.g. a custom listbox locator), but
+ * `frame` and `trigger` always behave the same way:
+ *
+ * - `frame` is the {@link Frame} the tester searches inside — typically the
+ *   component-test mount frame, but may be a `Page` for full E2E tests.
+ * - `trigger` is the focusable element that opens/closes the component. Every
+ *   tester provides a sensible default keyed off the component's stable
+ *   `data-testid` (see CONVENTIONS.md). Override it when the consumer renders
+ *   a custom trigger that doesn't carry that test id.
+ */
+interface BaseTesterOptions {
+    frame: Frame;
+    trigger?: Locator;
+}
+/**
+ * Keys recognised by {@link disclosure}'s `open(how)`. The same set covers
+ * Select, Menu, Combobox and DatePicker — disclosure-style components whose
+ * trigger expands a popover. Components that only open via click (e.g. a
+ * Dialog with no keyboard activation other than Enter) can ignore the keyboard
+ * paths and simply call `open("click")`.
+ */
+type DisclosureOpenWith = "click" | "Space" | "Enter" | "ArrowDown" | "ArrowUp";
+
+/**
+ * Options for {@link editorTester}. The Editor has no single disclosure
+ * trigger, so instead of `trigger` it accepts `root` — the `.BaselineUI-Editor`
+ * container every other locator is scoped to. Pass it when more than one
+ * Editor is mounted in the same frame.
+ */
+interface EditorTesterOptions {
+    frame: Frame;
+    /**
+     * The Editor root element. Defaults to `frame.locator(".BaselineUI-Editor")`.
+     */
+    root?: Locator;
+}
+/**
+ * Driver for an `<Editor>` in Playwright component tests. Construct with
+ * {@link editorTester} (or `testers(frame).editor()`).
+ *
+ * Works for both modes of the component: in rich text mode `textbox` resolves
+ * to the contenteditable area, in plain/minimal mode to the `<textarea>` —
+ * both expose `role="textbox"`, so no mode flag is needed. Rich-text-only
+ * surface (toolbar buttons, link popover, mention dropdown, help dialog)
+ * simply won't match when `enableRichText` is off.
+ */
+interface EditorTester {
+    readonly root: Locator;
+    /**
+     * The editing area: the rich text contenteditable or the plain-mode
+     * textarea (both have `role="textbox"`).
+     */
+    readonly textbox: Locator;
+    /**
+     * The rich text placeholder overlay, attached only while the document is
+     * empty. (In plain mode the placeholder is a `<textarea>` attribute —
+     * assert on `textbox` instead.)
+     */
+    readonly placeholder: Locator;
+    readonly toolbar: Locator;
+    readonly boldButton: Locator;
+    readonly italicButton: Locator;
+    readonly underlineButton: Locator;
+    readonly fontColorButton: Locator;
+    readonly backgroundColorButton: Locator;
+    /**
+     * Opens the font color picker popover if it isn't already open.
+     * Idempotent — keys off `aria-expanded` on the trigger.
+     */
+    openFontColorPicker: (how?: DisclosureOpenWith) => Promise<void>;
+    openBackgroundColorPicker: (how?: DisclosureOpenWith) => Promise<void>;
+    readonly addLinkButton: Locator;
+    readonly linkDialog: Locator;
+    readonly linkInput: Locator;
+    readonly linkAddButton: Locator;
+    /** The "Edit Link" button in show mode (caret inside an existing link). */
+    readonly linkEditButton: Locator;
+    readonly linkRemoveButton: Locator;
+    readonly linkCancelButton: Locator;
+    readonly linkSaveButton: Locator;
+    openLinkDialog: (how?: DisclosureOpenWith) => Promise<void>;
+    readonly saveButton: Locator;
+    /** The cancel button (rendered only when `onCancel` is provided). */
+    readonly cancelButton: Locator;
+    /**
+     * The footer mention button (rendered only with rich text +
+     * `mentionableUsers`).
+     */
+    readonly mentionButton: Locator;
+    readonly helpButton: Locator;
+    /** The keyboard shortcuts help dialog (a modal, portalled to the body). */
+    readonly helpDialog: Locator;
+    readonly helpDialogCloseButton: Locator;
+    openHelpDialog: () => Promise<void>;
+    /**
+     * The inline mention combobox input, attached only while a mention flow is
+     * active (after "@" or {@link startMention}).
+     */
+    readonly mentionInput: Locator;
+    /** The mention suggestion listbox (portalled outside the editor root). */
+    readonly mentionListbox: Locator;
+    mentionOption: (name: string | RegExp) => Locator;
+    /**
+     * Starts a mention flow via the footer mention button if one isn't already
+     * active. Idempotent — bails when the mention input is visible.
+     */
+    startMention: () => Promise<void>;
+}
+
+/**
+ * Options for {@link selectTester}. Defaults the trigger to
+ * `frame.getByTestId("select-button")` (the convention for both single- and
+ * multi-select). Pass `trigger` when the Select renders a custom trigger that
+ * doesn't carry that test id.
+ *
+ * `multiple` and `autocomplete` are **orthogonal** flags that mirror the
+ * component shape:
+ *
+ * - `multiple: true` matches `<Select selectionMode="multiple">` and adds the
+ *   `tag`, `removeTagButton`, `selectAllButton`, `clearButton` surface.
+ * - `autocomplete: true` matches `<Select>` wrapped in `<Autocomplete>` and
+ *   adds `searchbox` + `filter()`.
+ *
+ * They can be combined.
+ */
+interface SelectTesterOptions extends BaseTesterOptions {
+    multiple?: boolean;
+    autocomplete?: boolean;
+}
+/**
+ * Driver for a single-select `<Select>` in Playwright component tests.
+ * Construct with {@link selectTester}.
+ */
+interface SelectTester {
+    /** The trigger button. */
+    readonly trigger: Locator;
+    /** The popover listbox. Only attached while the Select is open. */
+    readonly listbox: Locator;
+    /** Locator for a single option by accessible name. */
+    option: (name: string | RegExp) => Locator;
+    /**
+     * Opens the Select if it isn't already open. Idempotent — checks
+     * `aria-expanded` on the trigger and bails if the popover is already shown.
+     *
+     * @param how How to open. Defaults to `"click"`. Key names focus the
+     *   trigger and press the key.
+     */
+    open: (how?: DisclosureOpenWith) => Promise<void>;
+    /** Opens the Select (if needed) and clicks the option matching `name`. */
+    selectOption: (name: string | RegExp) => Promise<void>;
+}
+/**
+ * Multi-select capability mixed in when {@link SelectTesterOptions.multiple}
+ * is `true`. Adds tag chips on the trigger plus the Select All / Clear
+ * buttons inside the popover.
+ */
+interface MultiSelectTester extends SelectTester {
+    /**
+     * The "Select All" action button inside the popover. Located by stable
+     * `data-testid` rather than the translated label. Only present while open.
+     */
+    readonly selectAllButton: Locator;
+    /**
+     * The "Clear" action button inside the popover. Located by stable
+     * `data-testid` rather than the translated label. Only present while open.
+     */
+    readonly clearButton: Locator;
+    /**
+     * Locator for a selected-value tag chip rendered inside the trigger. Tags
+     * are rendered by `TagGroup` as `role="row"`; `name` is matched against
+     * the row's accessible name (string substring or RegExp — useful for the
+     * `+N more` overflow tag).
+     */
+    tag: (name: string | RegExp) => Locator;
+    /**
+     * The remove button on a tag chip identified by `tagName`. Resolved as the
+     * button *inside* the matching row, so the helper does not depend on the
+     * translated "Remove X" label format.
+     */
+    removeTagButton: (tagName: string | RegExp) => Locator;
+}
+/**
+ * Autocomplete capability mixed in when {@link SelectTesterOptions.autocomplete}
+ * is `true`. Adds the popover searchbox.
+ */
+interface AutocompleteTester extends SelectTester {
+    /**
+     * The search input inside the popover. Only attached while the popover is
+     * open.
+     */
+    readonly searchbox: Locator;
+    /**
+     * Types into the searchbox to filter options. Does **not** open the
+     * Select — call `open()` first. Uses `fill` (replaces existing value); to
+     * clear, use `searchbox.clear()`.
+     */
+    filter: (text: string) => Promise<void>;
+}
+/**
+ * Overloaded call signature for {@link selectTester}. The return type narrows
+ * based on the `multiple` and `autocomplete` flags:
+ *
+ * - `select({})` → {@link SelectTester}
+ * - `select({ multiple: true })` → {@link MultiSelectTester}
+ * - `select({ autocomplete: true })` → {@link AutocompleteTester}
+ * - `select({ multiple: true, autocomplete: true })` →
+ *   {@link MultiSelectTester} & {@link AutocompleteTester}
+ *
+ * @example
+ * ```ts
+ * const select = testers(frame).select();
+ * await select.open("Space");
+ * await select.selectOption("Square");
+ *
+ * const multi = testers(frame).select({ multiple: true });
+ * await multi.selectAllButton.click();
+ *
+ * const auto = testers(frame).select({ autocomplete: true });
+ * await auto.open();
+ * await auto.filter("first");
+ * ```
+ */
+interface SelectTesterFactoryFor<O extends {
+    multiple?: boolean;
+    autocomplete?: boolean;
+}> {
+    (options: O & {
+        multiple: true;
+        autocomplete: true;
+    }): MultiSelectTester & AutocompleteTester;
+    (options: O & {
+        multiple: true;
+        autocomplete?: false;
+    }): MultiSelectTester;
+    (options: O & {
+        multiple?: false;
+        autocomplete: true;
+    }): AutocompleteTester;
+    (options?: O): SelectTester;
+}
+
+type BoundSelectOptions = Omit<SelectTesterOptions, "frame">;
+type BoundEditorOptions = Omit<EditorTesterOptions, "frame">;
+/**
+ * The frame-bound tester factory. Methods are flat — one per component — so
+ * IDE autocomplete on `t.` lists the full surface in one place. Variants of a
+ * single component are options on its method (e.g. `t.select({ multiple: true })`),
+ * not separate top-level methods, so the namespace stays component-shaped.
+ *
+ * Each method's overloads mirror its underlying factory with `frame` stripped
+ * (the factory binds it), so the narrowing rules live in exactly one place.
+ */
+interface Testers {
+    select: SelectTesterFactoryFor<BoundSelectOptions>;
+    editor: (options?: BoundEditorOptions) => EditorTester;
+}
+/**
+ * Build a frame-bound tester factory. Construct once per test and pick the
+ * component you need:
+ *
+ * ```ts
+ * const t = testers(frame);
+ * const select = t.select();
+ * const multi  = t.select({ multiple: true, trigger: customTrigger });
+ * const auto   = t.select({ autocomplete: true });
+ * ```
+ *
+ * Each method forwards per-call options to the underlying factory; `frame` is
+ * supplied automatically.
+ */
+declare function testers(frame: Frame): Testers;
+
+export { type AutocompleteTester, DEFAULT_CRITICAL_INCOMPLETE_RULES, DEFAULT_DISABLED_RULES, DEFAULT_WCAG_TAGS, type EditorTester, type Frame, type MultiSelectTester, type SelectTester, type Testers, type ToBeAccessibleOptions, expect, testers };