twd-js 1.7.2 → 1.7.3

package/dist/index.d.ts

@@ -1,664 +1,8 @@
-import { configure } from '@testing-library/dom';
-import { default as default_2 } from '@testing-library/user-event';
-import { expect } from 'chai';
-import { JSX } from 'react/jsx-runtime';
-import { screen as screen_2 } from '@testing-library/dom';
-
-/**
- * All assertion names, including negated ones.
- */
-declare type AnyAssertion = Negatable_2<AssertionName>;
-
-/**
- * All assertion names, including negated ones.
- */
-declare type AnyURLAssertion = Negatable<URLAssertionName>;
-
-/**
- * Maps assertion name to its argument tuple.
- */
-declare type ArgsFor<A extends AnyAssertion> = A extends `not.${infer Base extends AssertionName}` ? AssertionArgs[Base] : A extends AssertionName ? AssertionArgs[A] : never;
-
-/**
- * Argument types for each assertion.
- */
-declare type AssertionArgs = {
-    "have.text": [expected: string];
-    "contain.text": [expected: string];
-    "be.empty": [];
-    "have.attr": [attr: string, value: string];
-    "have.value": [value: string];
-    "be.disabled": [];
-    "be.enabled": [];
-    "be.checked": [];
-    "be.selected": [];
-    "be.focused": [];
-    "be.visible": [];
-    "have.class": [className: string];
-};
-
-/**
- * Types and interfaces for the TWD testing library.
- *
- * @module twd-types
- */
-/**
- * All supported assertion names for the `should` function.
- *
- * @example
- * api.should("have.text", "Hello");
- * api.should("be.empty");
- */
-declare type AssertionName = "have.text" | "contain.text" | "be.empty" | "have.attr" | "have.value" | "be.disabled" | "be.enabled" | "be.checked" | "be.selected" | "be.focused" | "be.visible" | "have.class";
-
-export declare const configureScreenDom: typeof configure;
-
-export declare const defaultTheme: TWDTheme;
-
-export { expect }
-
-/**
- * Initialize Vite test loading.
- * @param testModules - The test modules to load.
- * @param component - The React component to render the sidebar.
- * @param createRoot - Function to create a React root.
- * @param theme - Optional theme customization
- * @example
- * ```ts
- * if (import.meta.env.DEV) {
- *   const testModules = import.meta.glob("./example.twd.test.ts");
- *   const { initTests, TWDSidebar } = await import('twd-js');
- *   await initTests(testModules, <TWDSidebar open={true} position="left" />, createRoot, {
- *     primary: '#ff0000',
- *     background: '#ffffff'
- *   });
- * }
- * ```
- */
-export declare const initTests: (testModules: TestModule, Component: React.ReactNode, createRoot: (el: HTMLElement) => {
-    render: (el: React.ReactNode) => void;
-}, theme?: Partial<TWDTheme>) => Promise<void>;
-
-/**
- * Injects theme CSS variables into the document
- * This should be called once when the sidebar is initialized
- */
-export declare function injectTheme(theme?: Partial<TWDTheme>): void;
-
-/**
- * Negatable assertion names (e.g., 'not.have.text').
- */
-declare type Negatable<T extends string> = T | `not.${T}`;
-
-/**
- * Negatable assertion names (e.g., 'not.have.text').
- */
-declare type Negatable_2<T extends string> = T | `not.${T}`;
-
-declare interface Options {
-    /** HTTP method to match (e.g. `"GET"`, `"POST"`). */
-    method: string;
-    /** URL string or RegExp to match against the request URL. */
-    url: string | RegExp;
-    /** The mocked response body returned to the client. */
-    response: unknown;
-    /** HTTP status code for the mocked response (default: `200`). */
-    status?: number;
-    /** Headers to include in the mocked response. */
-    responseHeaders?: Record<string, string>;
-    /** Whether the `url` field should be treated as a regex pattern. */
-    urlRegex?: boolean;
-    /** Delay in milliseconds before returning the mocked response. */
-    delay?: number;
-}
-
-declare type Rule = {
-    /** HTTP method to match (e.g. `"GET"`, `"POST"`). */
-    method: string;
-    /** URL string or RegExp to match against the request URL. */
-    url: string | RegExp;
-    /** The mocked response body returned to the client. */
-    response: unknown;
-    /** Unique identifier for this mock rule, used with `waitForRequest`. */
-    alias: string;
-    /** Whether this rule has been matched by an actual request. Set automatically by the service worker. */
-    executed?: boolean;
-    /**
-     * The parsed request body sent by the client.
-     * For JSON requests this is the parsed object, for form data an object of key/value pairs, for text a string.
-     * Access fields directly: `rule.request.email`, **not** `rule.request.body.email`.
-     */
-    request?: any;
-    /** HTTP status code for the mocked response (default: `200`). */
-    status?: number;
-    /** Headers to include in the mocked response. */
-    responseHeaders?: Record<string, string>;
-    /** Whether the `url` field should be treated as a regex pattern. */
-    urlRegex?: boolean;
-    /** Delay in milliseconds before returning the mocked response. */
-    delay?: number;
-    /** Number of times this rule has been matched. Updated automatically by the service worker. */
-    hitCount?: number;
-};
-
-declare type ScreenDom = typeof screen_2;
-
-/**
- * screenDom - Scoped queries that exclude the TWD sidebar
- *
- * Searches only within the main app container (typically #root).
- * Use this for most queries to avoid matching elements in the sidebar.
- *
- * Note: This will NOT find portal-rendered elements (modals, dialogs) that are
- * rendered outside the root container. For portals, use `screenDomGlobal` instead.
- */
-export declare const screenDom: ScreenDom;
-
-/**
- * screenDomGlobal - Global queries that search the entire document.body
- *
- * Searches all elements in document.body, including portal-rendered elements
- * (modals, dialogs, tooltips, etc.).
- *
- * ⚠️ WARNING: This may also match elements inside the TWD sidebar if your selectors
- * are not specific enough. Use more specific queries (e.g., getByRole with name)
- * to avoid matching sidebar elements.
- *
- * Use this when:
- * - Querying portal-rendered elements (modals, dialogs)
- * - You need to search outside the root container
- *
- * Example:
- * ```ts
- * // For a modal rendered via portal
- * const modal = screenDomGlobal.getByRole('dialog', { name: 'Confirm' });
- * ```
- */
-export declare const screenDomGlobal: ScreenDom;
-
-/**
- * Overloads for the `should` function, for best IntelliSense.
- *
- * @example
- * twd.should("have.text", "Hello");
- * twd.should("be.empty");
- * twd.should("have.class", "active");
- */
-declare type ShouldFn = {
-    (name: "have.text", expected: string): TWDElemAPI;
-    (name: "not.have.text", expected: string): TWDElemAPI;
-    (name: "contain.text", expected: string): TWDElemAPI;
-    (name: "not.contain.text", expected: string): TWDElemAPI;
-    (name: "be.empty"): TWDElemAPI;
-    (name: "not.be.empty"): TWDElemAPI;
-    (name: "have.attr", attr: string, value: string): TWDElemAPI;
-    (name: "not.have.attr", attr: string, value: string): TWDElemAPI;
-    (name: "have.value", value: string): TWDElemAPI;
-    (name: "not.have.value", value: string): TWDElemAPI;
-    (name: "be.disabled"): TWDElemAPI;
-    (name: "not.be.disabled"): TWDElemAPI;
-    (name: "be.enabled"): TWDElemAPI;
-    (name: "not.be.enabled"): TWDElemAPI;
-    (name: "be.checked"): TWDElemAPI;
-    (name: "not.be.checked"): TWDElemAPI;
-    (name: "be.selected"): TWDElemAPI;
-    (name: "not.be.selected"): TWDElemAPI;
-    (name: "be.focused"): TWDElemAPI;
-    (name: "not.be.focused"): TWDElemAPI;
-    (name: "be.visible"): TWDElemAPI;
-    (name: "not.be.visible"): TWDElemAPI;
-    (name: "have.class", className: string): TWDElemAPI;
-    (name: "not.have.class", className: string): TWDElemAPI;
-};
-
-/**
- * A record of test module paths to their loader functions.
- * Each function returns a promise that resolves when the module is loaded.
- * This is typically used with Vite's `import.meta.glob` to dynamically import test modules.
- * @example
- * ```ts
- * const testModules = {
- *   './test1.twd.test.ts': () => import('./test1.twd.test.ts'),
- *   './test2.twd.test.ts': () => import('./test2.twd.test.ts'),
- * };
- * ```
- */
-declare type TestModule = Record<string, () => Promise<unknown>>;
-
-/**
- * Mini Cypress-style helpers for DOM testing.
- * @namespace twd
- */
-export declare const twd: TWDAPI;
-
-declare interface TWDAPI {
-    /**
-     * Finds an element by selector and returns the TWD API for it.
-     * @param selector CSS selector
-     * @returns {Promise<TWDElemAPI>} The TWD API for the element
-     *
-     * @example
-     * ```ts
-     * const btn = await twd.get("button");
-     *
-     * ```
-     *
-     */
-    get: (selector: string) => Promise<TWDElemAPI>;
-    /**
-     * Sets the value of an input element and dispatches an input event. We recommend using this only for range, color, time inputs.
-     * @param el The input element
-     * @param value The value to set
-     *
-     * @example
-     * ```ts
-     * const input = await twd.get("input[type='time']");
-     * twd.setInputValue(input.el, "13:30");
-     *
-     * ```
-     */
-    setInputValue: (el: Element, value: string) => void;
-    /**
-     * Finds multiple elements by selector and returns an array of TWD APIs for them.
-     * @param selector CSS selector
-     * @returns {Promise<TWDElemAPI[]>} Array of TWD APIs for the elements
-     *
-     * @example
-     * ```ts
-     * const items = await twd.getAll(".item");
-     * items.at(0).should("be.visible");
-     * items.at(1).should("contain.text", "Hello");
-     * expect(items).to.have.length(3);
-     * ```
-     */
-    getAll: (selector: string) => Promise<TWDElemAPI[]>;
-    /**
-     * Simulates visiting a URL (SPA navigation).
-     * @param url The URL to visit
-     * @param [reload] Whether to force a reload even if already on the URL (optional)
-     *
-     * @example
-     * ```ts
-     * twd.visit("/contact");
-     * // visit with reload
-     * twd.visit("/contact", true);
-     * ```
-     */
-    visit: (url: string, reload?: boolean) => Promise<void>;
-    /**
-     * Mock a network request.
-     *
-     * @param alias Identifier for the mock rule. Useful for `waitForRequest()`.
-     * @param options Options to configure the mock:
-     *  - `method`: HTTP method ("GET", "POST", …)
-     *  - `url`: URL string or RegExp to match
-     *  - `response`: Body of the mocked response
-     *  - `status`: (optional) HTTP status code (default: 200)
-     *  - `responseHeaders`: (optional) Response headers
-     *  - `delay`: (optional) Delay in ms before returning the response
-     *
-     * @example
-     * ```ts
-     * mockRequest("getUser", {
-     *   method: "GET",
-     *   url: /\/api\/user\/\d+/,
-     *   response: { id: 1, name: "Kevin" },
-     *   status: 200,
-     *   responseHeaders: { "x-mock": "true" }
-     * });
-     * ```
-     */
-    mockRequest: (alias: string, options: Options) => Promise<void>;
-    /**
-     * Wait for a mocked request to be made.
-     * @param alias The alias of the mock rule to wait for
-     * @param retries The number of retries to make
-     * @param retryDelay The delay between retries
-     * @return The matched rule (with body if applicable)
-     *
-     * @example
-     * ```ts
-     * const rule = await twd.waitForRequest("aliasId");
-     * console.log(rule.body);
-     * const rule = await twd.waitForRequest("aliasId", 5, 100);
-     * console.log(rule.body);
-     *
-     * ```
-     */
-    waitForRequest: (alias: string, retries?: number, retryDelay?: number) => Promise<Rule>;
-    /**
-     * wait for a list of mocked requests to be made.
-     * @param aliases The aliases of the mock rules to wait for
-     * @returns The matched rules (with body if applicable)
-     * @example
-     * ```ts
-     * const rules = await waitForRequests(["getUser", "postComment"]);
-     * ```
-     */
-    waitForRequests: (aliases: string[]) => Promise<Rule[]>;
-    /**
-     * URL-related assertions.
-     *
-     * @example
-     * ```ts
-     * twd.url().should("eq", "http://localhost:3000/contact");
-     * twd.url().should("contain.url", "/contact");
-     *
-     * ```
-     */
-    url: () => URLCommandAPI;
-    /**
-     * Initializes request mocking (registers the service worker).
-     * @param [path] service worker absolute path (optional)
-     *
-     * @example
-     * ```ts
-     * await twd.initRequestMocking();
-     * // init with custom service worker path
-     * await twd.initRequestMocking('/test-path/mock-sw.js');
-     * ```
-     */
-    initRequestMocking: (path?: string) => Promise<void>;
-    /**
-     * Clears all request mock rules.
-     *
-     * @example
-     * ```ts
-     * twd.clearRequestMockRules();
-     *
-     * ```
-     */
-    clearRequestMockRules: () => void;
-    /**
-     * Gets all current request mock rules.
-     *
-     * @example
-     * ```ts
-     * const rules = twd.getRequestMockRules();
-     * console.log(rules);
-     * ```
-     */
-    getRequestMockRules: () => Rule[];
-    /**
-     * Gets the number of times a specific mock rule was hit.
-     * @param alias The alias of the mock rule
-     * @returns The number of times the rule was matched
-     *
-     * @example
-     * ```ts
-     * const count = twd.getRequestCount("getUser");
-     * expect(count).to.equal(2);
-     * ```
-     */
-    getRequestCount: (alias: string) => number;
-    /**
-     * Gets a snapshot of all mock rule hit counts.
-     * @returns An object mapping rule aliases to their hit counts
-     *
-     * @example
-     * ```ts
-     * const counts = twd.getRequestCounts();
-     * expect(counts).to.deep.equal({ getUser: 2, listPosts: 1 });
-     * ```
-     */
-    getRequestCounts: () => Record<string, number>;
-    /**
-     * Waits for a specified time.
-     * @param time Time in milliseconds to wait
-     * @returns A promise that resolves after the specified time
-     * @example
-     * ```ts
-     * await twd.wait(500); // wait for 500ms
-     * ```
-     */
-    wait: (time: number) => Promise<void>;
-    /**
-     * Retries a callback until it stops throwing or the timeout expires.
-     * Use this instead of `twd.wait(ms)` to wait for conditions rather than fixed delays.
-     *
-     * @param callback Function to retry — can be sync or async. Should throw if the condition is not yet met.
-     * @param options Optional timeout, interval, and message settings
-     * @returns A promise that resolves with the callback's return value when it succeeds
-     *
-     * @example
-     * ```ts
-     * // Wait for an analytics event and return it
-     * const event = await twd.waitFor(() => {
-     *   const ev = findEvent("purchase");
-     *   expect(ev).to.exist;
-     *   return ev;
-     * }, { message: "purchase event to fire" });
-     *
-     * // Wait for an element (single expression)
-     * const heading = await twd.waitFor(() => screenDom.getByRole("heading", { name: /checkout/i }));
-     *
-     * // Fire-and-forget (void) — still works as before
-     * await twd.waitFor(() => {
-     *   expect(submitButton.disabled).to.be.false;
-     * });
-     * ```
-     */
-    waitFor: <T>(callback: () => T | Promise<T>, options?: WaitForOptions) => Promise<T>;
-    /**
-     * Asserts something about the element.
-     * @param el The element to assert on
-     * @param name The name of the assertion.
-     * @param args Arguments for the assertion.
-     * @returns The same API for chaining.
-     * @example
-     * ```ts
-     * const button = await twd.get("button");
-     * const text = screenDom.getByText("Hello");
-     * twd.should(button.el, "have.text", "Hello");
-     * twd.should(text, "be.empty");
-     * twd.should(button.el, "have.class", "active");
-     * ```
-     */
-    should: (el: Element, name: AnyAssertion, ...args: ArgsFor<AnyAssertion>) => void;
-    /**
-     * Mock a component.
-     * @param name The name of the component to mock
-     * @param component The component to mock
-     * @returns The mocked component
-     * @example
-     * ```ts
-     * twd.mockComponent("Button", Button);
-     * ```
-     */
-    mockComponent: (name: string, component: React.ComponentType<any>) => void;
-    /**
-     * Clears all component mocks.
-     *
-     * @example
-     * ```ts
-     * twd.clearComponentMocks();
-     * ```
-     */
-    clearComponentMocks: () => void;
-    /**
-     * Asserts that an element does not exist in the DOM.
-     * @param selector CSS selector of the element to check
-     * @returns A promise that resolves if the element does not exist, or rejects if it does
-     *
-     * @example
-     * ```ts
-     * await twd.notExists(".non-existent");
-     * ```
-     */
-    notExists: (selector: string) => Promise<void>;
-    /**
-     * Simulates a viewport size by constraining body dimensions, overriding
-     * `window.innerWidth`/`window.innerHeight` and `window.matchMedia()`, and
-     * rewriting CSS `@media` rules to match the simulated dimensions.
-     * Call with no arguments to reset to the original viewport.
-     *
-     * @param width Viewport width in pixels
-     * @param height Viewport height in pixels (optional — omit to leave height unconstrained)
-     *
-     * @example
-     * ```ts
-     * twd.viewport(375, 667); // mobile
-     * twd.viewport(768);      // tablet width, height unconstrained
-     * twd.viewport();          // reset
-     * ```
-     */
-    viewport: (width?: number, height?: number) => void;
-    /**
-     * Resets the viewport to its original size (undoes a previous `twd.viewport()` call).
-     *
-     * @example
-     * ```ts
-     * twd.resetViewport();
-     * ```
-     */
-    resetViewport: () => void;
-}
-
-/**
- * The main API returned by `twd.get()`.
- *
- * @example
- * ```ts
- * const btn = await twd.get("button");
- * btn.should("have.text", "Clicked").click();
- *
- * ```
- *
- */
-declare interface TWDElemAPI {
-    /** The underlying DOM element. */
-    el: Element;
-    /**
-     * Asserts something about the element.
-     * @param name The name of the assertion.
-     * @param args Arguments for the assertion.
-     * @returns The same API for chaining.
-     *
-     * @example
-     * ```ts
-     * const btn = await twd.get("button");
-     * btn.should("have.text", "Click me").should("not.be.disabled");
-     *
-     * ```
-     *
-     */
-    should: ShouldFn;
-}
-
-export declare const TWDSidebar: ({ open, position, search }: TWDSidebarProps) => JSX.Element;
-
-declare interface TWDSidebarProps {
-    /**
-     * Whether the sidebar is open by default
-     */
-    open: boolean;
-    /**
-     * Sidebar position
-     * - left: Sidebar on the left side (default)
-     * - right: Sidebar on the right side
-     *
-     * @default "left"
-     */
-    position?: "left" | "right";
-    /**
-     * Whether to show the search/filter input
-     */
-    search?: boolean;
-}
-
-/**
- * TWD Theme Configuration
- *
- * This file defines CSS variables that can be customized by users
- * to personalize their TWD UI experience.
- *
- * Users can override these variables by setting them in their CSS:
- *
- * ```css
- * :root {
- *   --twd-primary: #2563eb;
- *   --twd-background: #1e293b;
- *    ... other variables
- * }
- *
- */
-export declare interface TWDTheme {
-    primary: string;
-    background: string;
-    backgroundSecondary: string;
-    border: string;
-    borderLight: string;
-    text: string;
-    textSecondary: string;
-    textMuted: string;
-    describeBg: string;
-    describeText: string;
-    describeBorder: string;
-    success: string;
-    successBg: string;
-    error: string;
-    errorBg: string;
-    warning: string;
-    warningBg: string;
-    skip: string;
-    skipBg: string;
-    buttonPrimary: string;
-    buttonPrimaryText: string;
-    buttonSecondary: string;
-    buttonSecondaryText: string;
-    buttonBorder: string;
-    spacingXs: string;
-    spacingSm: string;
-    spacingMd: string;
-    spacingLg: string;
-    spacingXl: string;
-    fontSizeXs: string;
-    fontSizeSm: string;
-    fontSizeMd: string;
-    fontSizeLg: string;
-    fontWeightNormal: string;
-    fontWeightMedium: string;
-    fontWeightBold: string;
-    sidebarWidth: string;
-    borderRadius: string;
-    borderRadiusLg: string;
-    shadow: string;
-    shadowSm: string;
-    zIndexSidebar: string;
-    zIndexSticky: string;
-    animationDuration: string;
-    iconColor: string;
-    iconColorSecondary: string;
-}
-
-/**
- * All supported assertion names for the `should` function in url command
- *
- * @example
- * twd.url().should("contain.url", "/new-page");
- * twd.url().should("eq", "http://localhost:3000/new-page");
- */
-declare type URLAssertionName = "eq" | "contain.url";
-
-declare type URLCommandAPI = {
-    location: Location;
-    should: (name: AnyURLAssertion, value: string, retries?: number) => Promise<string>;
-};
-
-declare type UserEvent = typeof default_2;
-
-export declare const userEvent: UserEvent;
-
-/**
- * Options for `twd.waitFor()`.
- */
-declare interface WaitForOptions {
-    /** Max time to wait in ms. Default: 2000 */
-    timeout?: number;
-    /** Poll interval in ms. Default: 50 */
-    interval?: number;
-    /** Context message included in timeout errors */
-    message?: string;
-}
-
-export { }
+export { twd } from './twd';
+export { TWDSidebar } from './ui/TWDSidebar';
+export { initTests } from './initializers/initTests';
+export { expect } from 'chai';
+export { userEvent } from './proxies/userEvent';
+export { screenDom, screenDomGlobal, configureScreenDom } from './proxies/screenDom';
+export type { TWDTheme } from './ui/utils/theme';
+export { defaultTheme, injectTheme } from './ui/utils/theme';