@assure-one/design-system 1.30.0 → 1.32.0

package/dist/testing/index.d.cts

@@ -0,0 +1,253 @@
+/**
+ * Jest configuration wrapper that loads the real design system (ADR-014).
+ *
+ * Jest's CommonJS runtime cannot load the package as published:
+ *   1. the `exports` map only has an `import` condition, so the bare specifier
+ *      does not resolve ("Cannot find module");
+ *   2. the build is ESM, and `next/jest` (like plain Jest) skips `node_modules`
+ *      when transforming;
+ *   3. jsdom lacks APIs the Radix-based components call.
+ * `withAssureDesignSystem` fixes all three on the final config, so it works on
+ * top of `next/jest` (which only lets callers append ignore patterns).
+ *
+ * Runs in Node (inside a Jest config). No Node built-ins are imported, so the
+ * rest of the entry stays safe to load in a browser test runner.
+ */
+/** The subset of a Jest config the wrapper reads or writes. @experimental */
+interface JestConfigLike {
+    /** Jest `rootDir`; passed through unchanged. */
+    rootDir?: string;
+    /** Jest `moduleNameMapper`; the package's own mappings are placed first. */
+    moduleNameMapper?: Record<string, string | string[]>;
+    /** Jest `transformIgnorePatterns`; each entry gets an exemption for the package build. */
+    transformIgnorePatterns?: string[];
+    /** Jest `setupFiles`; the shim setup file is prepended. */
+    setupFiles?: string[];
+    /** Any other Jest option; passed through unchanged. */
+    [key: string]: unknown;
+}
+/**
+ * A Jest config value: an object, or a (possibly async) function returning
+ * one, as `next/jest` produces.
+ *
+ * @experimental
+ */
+type JestConfigInput<T extends JestConfigLike = JestConfigLike> = T | (() => T | Promise<T>);
+/** Options for `withAssureDesignSystem`. @experimental */
+interface AssureJestOptions {
+    /**
+     * Add the jsdom shims (`installDomPolyfills`) to `setupFiles`. Default `true`.
+     * They are installed only where the environment lacks them.
+     */
+    polyfills?: boolean;
+}
+/** Signature of `withAssureDesignSystem`. @experimental */
+type WithAssureDesignSystem = <T extends JestConfigLike>(config: JestConfigInput<T>, options?: AssureJestOptions) => () => Promise<T & JestConfigLike>;
+/**
+ * Wrap a Jest config so the real `@assure-one/design-system` loads in tests.
+ *
+ * ```ts
+ * // jest.config.ts
+ * import nextJest from "next/jest.js";
+ * import { withAssureDesignSystem } from "@assure-one/design-system/testing";
+ *
+ * const createJestConfig = nextJest({ dir: "./" });
+ * export default withAssureDesignSystem(createJestConfig({ testEnvironment: "jsdom" }));
+ * ```
+ *
+ * The returned async function resolves `config` and then:
+ * - maps `@assure-one/design-system` and `/tokens` to the built files, and
+ *   `/styles.css` to an empty module. These mappings come before the app's
+ *   own, so they take precedence over a stub mapping;
+ * - exempts the package's build output from every `transformIgnorePatterns`
+ *   entry, so the app's transformer compiles the ESM build;
+ * - prepends the jsdom shim setup file to `setupFiles` (unless
+ *   `polyfills: false`).
+ *
+ * @experimental
+ */
+declare const withAssureDesignSystem: WithAssureDesignSystem;
+
+/**
+ * jsdom gaps that the design system's Radix-based components run into.
+ *
+ * Each shim is installed only when the environment lacks the API, so an app's
+ * own setup (or a newer jsdom) always wins. Nothing is observed or measured:
+ * the shims exist so components mount and respond to keyboard and pointer
+ * events instead of throwing. One entry is a guard rather than a shim
+ * (`topLayerSelectors`, see below).
+ */
+/** Names of the shims `installDomPolyfills` can install. @experimental */
+type DomPolyfill = "ResizeObserver" | "matchMedia" | "PointerEvent" | "hasPointerCapture" | "setPointerCapture" | "releasePointerCapture" | "scrollIntoView" | "DOMRect" | "topLayerSelectors";
+/** Options for `installDomPolyfills`. @experimental */
+interface DomPolyfillOptions {
+    /**
+     * Answer for `window.matchMedia(query).matches` when the shim is installed.
+     * Default: every query is `false` (no reduced motion, no dark scheme, and
+     * `min-width` queries do not match).
+     */
+    matchMedia?: (query: string) => boolean;
+}
+/**
+ * Install the jsdom shims the design system needs and return the names of the
+ * ones that were missing. Safe to call more than once and outside a DOM
+ * environment (it then does nothing).
+ *
+ * @experimental
+ */
+declare function installDomPolyfills(options?: DomPolyfillOptions): DomPolyfill[];
+
+/**
+ * Records the toasts that a real `ToastProvider` shows, including ones that
+ * have already been dismissed, so tests can assert on them. It replaces
+ * hand-written test-only exports such as `recordedToasts`/`resetToasts`
+ * (ADR-014).
+ *
+ * The recorder reads the rendered toast region. Toast markup is internal to
+ * this package; the mapping below is kept in step with `toast.tsx` by this
+ * package's tests, so consumers never depend on it.
+ */
+/**
+ * Variant of a recorded toast. `"custom"` is a toast rendered from `content`,
+ * whose variant is not shown.
+ *
+ * @experimental
+ */
+type RecordedToastVariant = "default" | "success" | "destructive" | "warning" | "info" | "loading" | "custom";
+/** A toast as the user saw it, captured by `createToastRecorder`. @experimental */
+interface RecordedToast {
+    /** Title text ("" when the toast has none). */
+    readonly title: string;
+    /** Description text ("" when the toast has none). */
+    readonly description: string;
+    /** Visual variant, read from the rendered toast. */
+    readonly variant: RecordedToastVariant;
+    /** Live-region role: `alert` for destructive toasts, `status` for the rest, `group` for `content` toasts. */
+    readonly role: "status" | "alert" | "group";
+    /** Label of the action button, or `null`. */
+    readonly action: string | null;
+    /** Title, description and action label, space-separated; for `content` toasts, all their text. */
+    readonly text: string;
+    /** `true` while the toast is on screen. */
+    readonly open: boolean;
+}
+/** Handle returned by `createToastRecorder`. @experimental */
+interface ToastRecorder {
+    /** Every toast shown since the recorder started (or since `clear()`), oldest first. Updates to a visible toast are reflected. */
+    readonly toasts: readonly RecordedToast[];
+    /** The toasts currently on screen. */
+    readonly visible: readonly RecordedToast[];
+    /** The most recently shown toast. */
+    last(): RecordedToast | undefined;
+    /** The first recorded toast whose title, description or text matches. */
+    find(match: string | RegExp): RecordedToast | undefined;
+    /** Forget everything recorded so far. */
+    clear(): void;
+    /** Stop recording. Recorded toasts stay readable. */
+    stop(): void;
+}
+/** Options for `createToastRecorder`. @experimental */
+interface ToastRecorderOptions {
+    /** Where to watch. Default `document.body` (toasts render in a fixed region there). */
+    root?: Node;
+}
+/**
+ * Start recording toasts shown by a `ToastProvider`.
+ *
+ * ```ts
+ * const toasts = createToastRecorder();
+ * await user.click(screen.getByRole("button", { name: "Save" }));
+ * expect(toasts.last()).toMatchObject({ title: "Saved", variant: "success" });
+ * toasts.stop();
+ * ```
+ *
+ * Create it before the action under test. Toasts that auto-dismiss stay in
+ * `toasts` with `open: false`.
+ *
+ * @experimental
+ */
+declare function createToastRecorder(options?: ToastRecorderOptions): ToastRecorder;
+
+/**
+ * Anything that can find an element by role and accessible name, such as
+ * Testing Library's `screen` or `within(container)`.
+ *
+ * @experimental
+ */
+interface RoleQueries {
+    /** Return the single element with this role (and accessible name), or throw. */
+    getByRole(role: string, options?: {
+        name?: string | RegExp;
+    }): HTMLElement;
+}
+/** Text matcher: exact text (after trimming and collapsing whitespace) or a pattern. @experimental */
+type TextMatch = string | RegExp;
+/** Options for `selectOption` and `openMenu`. @experimental */
+interface InteractionOptions {
+    /** How many render passes to wait for the popup to appear or close. Default 20. */
+    maxFlushes?: number;
+}
+/**
+ * Open a design-system `Select` and choose an option by its visible text.
+ *
+ * ```ts
+ * await selectOption(screen, "Tax year", "2025");      // trigger found by role "combobox" and name
+ * await selectOption(screen.getByRole("combobox"), /2025/);
+ * ```
+ *
+ * The trigger is opened with the keyboard, the option is chosen with Enter,
+ * and the helper waits for the list to close. It throws when the trigger or
+ * option is disabled, or when no option matches (the error lists the options).
+ *
+ * @experimental
+ */
+declare function selectOption(trigger: HTMLElement, option: TextMatch, options?: InteractionOptions): Promise<void>;
+/**
+ * Open the `Select` whose combobox trigger has the accessible name `label`
+ * (found through `queries`, for example Testing Library's `screen`) and choose
+ * `option`. See the other overload for details.
+ *
+ * @experimental
+ */
+declare function selectOption(queries: RoleQueries, label: TextMatch, option: TextMatch, options?: InteractionOptions): Promise<void>;
+/**
+ * An open design-system menu, returned by `openMenu`.
+ *
+ * @experimental
+ */
+interface MenuHandle {
+    /** The element with role `menu`. */
+    readonly element: HTMLElement;
+    /** Every item (`menuitem`, `menuitemcheckbox`, `menuitemradio`) currently in the menu. */
+    items(): HTMLElement[];
+    /** The item whose text matches; throws with the list of items otherwise. */
+    getItem(name: TextMatch): HTMLElement;
+    /**
+     * Activate an item with Enter, then wait for the menu to close. A menu that
+     * stays open (its `onSelect` called `preventDefault()`) is not an error.
+     */
+    select(name: TextMatch): Promise<void>;
+    /** Close the menu with Escape. */
+    close(): Promise<void>;
+}
+/**
+ * Open a design-system `DropdownMenu` from its trigger and return a handle to
+ * the menu.
+ *
+ * ```ts
+ * const menu = await openMenu(screen, "Actions");      // trigger found by role "button" and name
+ * await menu.select("Archive");
+ * ```
+ *
+ * @experimental
+ */
+declare function openMenu(trigger: HTMLElement, options?: InteractionOptions): Promise<MenuHandle>;
+/**
+ * Open the `DropdownMenu` whose trigger button has the accessible name `name`
+ * (found through `queries`, for example Testing Library's `screen`).
+ *
+ * @experimental
+ */
+declare function openMenu(queries: RoleQueries, name: TextMatch, options?: InteractionOptions): Promise<MenuHandle>;
+
+export { type AssureJestOptions, type DomPolyfill, type DomPolyfillOptions, type InteractionOptions, type JestConfigInput, type JestConfigLike, type MenuHandle, type RecordedToast, type RecordedToastVariant, type RoleQueries, type TextMatch, type ToastRecorder, type ToastRecorderOptions, type WithAssureDesignSystem, createToastRecorder, installDomPolyfills, openMenu, selectOption, withAssureDesignSystem };

package/dist/testing/index.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Jest configuration wrapper that loads the real design system (ADR-014).
+ *
+ * Jest's CommonJS runtime cannot load the package as published:
+ *   1. the `exports` map only has an `import` condition, so the bare specifier
+ *      does not resolve ("Cannot find module");
+ *   2. the build is ESM, and `next/jest` (like plain Jest) skips `node_modules`
+ *      when transforming;
+ *   3. jsdom lacks APIs the Radix-based components call.
+ * `withAssureDesignSystem` fixes all three on the final config, so it works on
+ * top of `next/jest` (which only lets callers append ignore patterns).
+ *
+ * Runs in Node (inside a Jest config). No Node built-ins are imported, so the
+ * rest of the entry stays safe to load in a browser test runner.
+ */
+/** The subset of a Jest config the wrapper reads or writes. @experimental */
+interface JestConfigLike {
+    /** Jest `rootDir`; passed through unchanged. */
+    rootDir?: string;
+    /** Jest `moduleNameMapper`; the package's own mappings are placed first. */
+    moduleNameMapper?: Record<string, string | string[]>;
+    /** Jest `transformIgnorePatterns`; each entry gets an exemption for the package build. */
+    transformIgnorePatterns?: string[];
+    /** Jest `setupFiles`; the shim setup file is prepended. */
+    setupFiles?: string[];
+    /** Any other Jest option; passed through unchanged. */
+    [key: string]: unknown;
+}
+/**
+ * A Jest config value: an object, or a (possibly async) function returning
+ * one, as `next/jest` produces.
+ *
+ * @experimental
+ */
+type JestConfigInput<T extends JestConfigLike = JestConfigLike> = T | (() => T | Promise<T>);
+/** Options for `withAssureDesignSystem`. @experimental */
+interface AssureJestOptions {
+    /**
+     * Add the jsdom shims (`installDomPolyfills`) to `setupFiles`. Default `true`.
+     * They are installed only where the environment lacks them.
+     */
+    polyfills?: boolean;
+}
+/** Signature of `withAssureDesignSystem`. @experimental */
+type WithAssureDesignSystem = <T extends JestConfigLike>(config: JestConfigInput<T>, options?: AssureJestOptions) => () => Promise<T & JestConfigLike>;
+/**
+ * Wrap a Jest config so the real `@assure-one/design-system` loads in tests.
+ *
+ * ```ts
+ * // jest.config.ts
+ * import nextJest from "next/jest.js";
+ * import { withAssureDesignSystem } from "@assure-one/design-system/testing";
+ *
+ * const createJestConfig = nextJest({ dir: "./" });
+ * export default withAssureDesignSystem(createJestConfig({ testEnvironment: "jsdom" }));
+ * ```
+ *
+ * The returned async function resolves `config` and then:
+ * - maps `@assure-one/design-system` and `/tokens` to the built files, and
+ *   `/styles.css` to an empty module. These mappings come before the app's
+ *   own, so they take precedence over a stub mapping;
+ * - exempts the package's build output from every `transformIgnorePatterns`
+ *   entry, so the app's transformer compiles the ESM build;
+ * - prepends the jsdom shim setup file to `setupFiles` (unless
+ *   `polyfills: false`).
+ *
+ * @experimental
+ */
+declare const withAssureDesignSystem: WithAssureDesignSystem;
+
+/**
+ * jsdom gaps that the design system's Radix-based components run into.
+ *
+ * Each shim is installed only when the environment lacks the API, so an app's
+ * own setup (or a newer jsdom) always wins. Nothing is observed or measured:
+ * the shims exist so components mount and respond to keyboard and pointer
+ * events instead of throwing. One entry is a guard rather than a shim
+ * (`topLayerSelectors`, see below).
+ */
+/** Names of the shims `installDomPolyfills` can install. @experimental */
+type DomPolyfill = "ResizeObserver" | "matchMedia" | "PointerEvent" | "hasPointerCapture" | "setPointerCapture" | "releasePointerCapture" | "scrollIntoView" | "DOMRect" | "topLayerSelectors";
+/** Options for `installDomPolyfills`. @experimental */
+interface DomPolyfillOptions {
+    /**
+     * Answer for `window.matchMedia(query).matches` when the shim is installed.
+     * Default: every query is `false` (no reduced motion, no dark scheme, and
+     * `min-width` queries do not match).
+     */
+    matchMedia?: (query: string) => boolean;
+}
+/**
+ * Install the jsdom shims the design system needs and return the names of the
+ * ones that were missing. Safe to call more than once and outside a DOM
+ * environment (it then does nothing).
+ *
+ * @experimental
+ */
+declare function installDomPolyfills(options?: DomPolyfillOptions): DomPolyfill[];
+
+/**
+ * Records the toasts that a real `ToastProvider` shows, including ones that
+ * have already been dismissed, so tests can assert on them. It replaces
+ * hand-written test-only exports such as `recordedToasts`/`resetToasts`
+ * (ADR-014).
+ *
+ * The recorder reads the rendered toast region. Toast markup is internal to
+ * this package; the mapping below is kept in step with `toast.tsx` by this
+ * package's tests, so consumers never depend on it.
+ */
+/**
+ * Variant of a recorded toast. `"custom"` is a toast rendered from `content`,
+ * whose variant is not shown.
+ *
+ * @experimental
+ */
+type RecordedToastVariant = "default" | "success" | "destructive" | "warning" | "info" | "loading" | "custom";
+/** A toast as the user saw it, captured by `createToastRecorder`. @experimental */
+interface RecordedToast {
+    /** Title text ("" when the toast has none). */
+    readonly title: string;
+    /** Description text ("" when the toast has none). */
+    readonly description: string;
+    /** Visual variant, read from the rendered toast. */
+    readonly variant: RecordedToastVariant;
+    /** Live-region role: `alert` for destructive toasts, `status` for the rest, `group` for `content` toasts. */
+    readonly role: "status" | "alert" | "group";
+    /** Label of the action button, or `null`. */
+    readonly action: string | null;
+    /** Title, description and action label, space-separated; for `content` toasts, all their text. */
+    readonly text: string;
+    /** `true` while the toast is on screen. */
+    readonly open: boolean;
+}
+/** Handle returned by `createToastRecorder`. @experimental */
+interface ToastRecorder {
+    /** Every toast shown since the recorder started (or since `clear()`), oldest first. Updates to a visible toast are reflected. */
+    readonly toasts: readonly RecordedToast[];
+    /** The toasts currently on screen. */
+    readonly visible: readonly RecordedToast[];
+    /** The most recently shown toast. */
+    last(): RecordedToast | undefined;
+    /** The first recorded toast whose title, description or text matches. */
+    find(match: string | RegExp): RecordedToast | undefined;
+    /** Forget everything recorded so far. */
+    clear(): void;
+    /** Stop recording. Recorded toasts stay readable. */
+    stop(): void;
+}
+/** Options for `createToastRecorder`. @experimental */
+interface ToastRecorderOptions {
+    /** Where to watch. Default `document.body` (toasts render in a fixed region there). */
+    root?: Node;
+}
+/**
+ * Start recording toasts shown by a `ToastProvider`.
+ *
+ * ```ts
+ * const toasts = createToastRecorder();
+ * await user.click(screen.getByRole("button", { name: "Save" }));
+ * expect(toasts.last()).toMatchObject({ title: "Saved", variant: "success" });
+ * toasts.stop();
+ * ```
+ *
+ * Create it before the action under test. Toasts that auto-dismiss stay in
+ * `toasts` with `open: false`.
+ *
+ * @experimental
+ */
+declare function createToastRecorder(options?: ToastRecorderOptions): ToastRecorder;
+
+/**
+ * Anything that can find an element by role and accessible name, such as
+ * Testing Library's `screen` or `within(container)`.
+ *
+ * @experimental
+ */
+interface RoleQueries {
+    /** Return the single element with this role (and accessible name), or throw. */
+    getByRole(role: string, options?: {
+        name?: string | RegExp;
+    }): HTMLElement;
+}
+/** Text matcher: exact text (after trimming and collapsing whitespace) or a pattern. @experimental */
+type TextMatch = string | RegExp;
+/** Options for `selectOption` and `openMenu`. @experimental */
+interface InteractionOptions {
+    /** How many render passes to wait for the popup to appear or close. Default 20. */
+    maxFlushes?: number;
+}
+/**
+ * Open a design-system `Select` and choose an option by its visible text.
+ *
+ * ```ts
+ * await selectOption(screen, "Tax year", "2025");      // trigger found by role "combobox" and name
+ * await selectOption(screen.getByRole("combobox"), /2025/);
+ * ```
+ *
+ * The trigger is opened with the keyboard, the option is chosen with Enter,
+ * and the helper waits for the list to close. It throws when the trigger or
+ * option is disabled, or when no option matches (the error lists the options).
+ *
+ * @experimental
+ */
+declare function selectOption(trigger: HTMLElement, option: TextMatch, options?: InteractionOptions): Promise<void>;
+/**
+ * Open the `Select` whose combobox trigger has the accessible name `label`
+ * (found through `queries`, for example Testing Library's `screen`) and choose
+ * `option`. See the other overload for details.
+ *
+ * @experimental
+ */
+declare function selectOption(queries: RoleQueries, label: TextMatch, option: TextMatch, options?: InteractionOptions): Promise<void>;
+/**
+ * An open design-system menu, returned by `openMenu`.
+ *
+ * @experimental
+ */
+interface MenuHandle {
+    /** The element with role `menu`. */
+    readonly element: HTMLElement;
+    /** Every item (`menuitem`, `menuitemcheckbox`, `menuitemradio`) currently in the menu. */
+    items(): HTMLElement[];
+    /** The item whose text matches; throws with the list of items otherwise. */
+    getItem(name: TextMatch): HTMLElement;
+    /**
+     * Activate an item with Enter, then wait for the menu to close. A menu that
+     * stays open (its `onSelect` called `preventDefault()`) is not an error.
+     */
+    select(name: TextMatch): Promise<void>;
+    /** Close the menu with Escape. */
+    close(): Promise<void>;
+}
+/**
+ * Open a design-system `DropdownMenu` from its trigger and return a handle to
+ * the menu.
+ *
+ * ```ts
+ * const menu = await openMenu(screen, "Actions");      // trigger found by role "button" and name
+ * await menu.select("Archive");
+ * ```
+ *
+ * @experimental
+ */
+declare function openMenu(trigger: HTMLElement, options?: InteractionOptions): Promise<MenuHandle>;
+/**
+ * Open the `DropdownMenu` whose trigger button has the accessible name `name`
+ * (found through `queries`, for example Testing Library's `screen`).
+ *
+ * @experimental
+ */
+declare function openMenu(queries: RoleQueries, name: TextMatch, options?: InteractionOptions): Promise<MenuHandle>;
+
+export { type AssureJestOptions, type DomPolyfill, type DomPolyfillOptions, type InteractionOptions, type JestConfigInput, type JestConfigLike, type MenuHandle, type RecordedToast, type RecordedToastVariant, type RoleQueries, type TextMatch, type ToastRecorder, type ToastRecorderOptions, type WithAssureDesignSystem, createToastRecorder, installDomPolyfills, openMenu, selectOption, withAssureDesignSystem };