twd-js 1.7.1 → 1.7.3

package/dist/initializers/initSidebar.d.ts

@@ -0,0 +1,29 @@
+import { TWDTheme } from '../ui/utils/theme';
+interface Options {
+    Component: React.ReactNode;
+    createRoot: (el: HTMLElement) => {
+        render: (el: React.ReactNode) => void;
+    };
+    /**
+     * Optional theme customization
+     * Users can override default theme values by passing a partial theme object
+     */
+    theme?: Partial<TWDTheme>;
+}
+/**
+ * Initialize the TWD sidebar.
+ * @param options - Options for initializing the sidebar.
+ * @example
+ * ```ts
+ * import { initSidebar } from 'twd-js';
+ *
+ * // Initialize the sidebar (e.g., in your main app file)
+ * initSidebar({
+ *   Component: <TWDSidebar open={true} position="left" />,
+ *   createRoot,
+ *   theme: { primary: '#ff0000', background: '#ffffff' }
+ * });
+ * ```
+ */
+export declare const initSidebar: (options: Options) => void;
+export {};

package/dist/initializers/initTests.d.ts

@@ -0,0 +1,36 @@
+import { TWDTheme } from '../ui/utils/theme';
+/**
+ * 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'),
+ * };
+ * ```
+ */
+type TestModule = Record<string, () => Promise<unknown>>;
+/**
+ * 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>;
+export {};

package/dist/mock-sw.js

@@ -1,4 +1,4 @@
-(function(){var d=t=>{try{return new RegExp(t),!0}catch{return!1}},f=new Set(["js","mjs","cjs","ts","tsx","jsx","mts","cts","css","scss","sass","less","styl","html","htm","xml","xhtml","vue","svelte","json","yaml","yml","toml","csv","txt","md","mdx","pdf","doc","docx","png","jpg","jpeg","gif","svg","webp","ico","bmp","avif","woff","woff2","ttf","eot","otf","mp3","mp4","webm","ogg","wav","zip","tar","gz","rar","map"]),c=t=>{const s=t.split("?")[0].match(/\.([a-zA-Z0-9]+)$/);return s?f.has(s[1].toLowerCase()):!1},h=(t,s)=>{const i=t.indexOf(s);if(i===-1)return!1;const e=i+s.length,a=t[e];if(a===void 0)return!0;const n=t.indexOf("?");return n!==-1&&e>n?!0:"?#&".includes(a)};function m(t,s,i){return i.find(e=>{const a=e.method.toLowerCase()===t.toLowerCase();if(e.urlRegex&&d(e.url)){const l=new RegExp(e.url);return a&&l.test(s)}if(c(e.url))return a&&s.includes(e.url);const n=e.url===s||h(s,e.url);return a&&n&&!c(s)})}function p(t,s,i,e){t.forEach(a=>a.postMessage({type:"EXECUTED",alias:s.alias,request:i,hitCount:e}))}var y=(t,s,i)=>{const e=![204,205,304].includes(s),a=e?JSON.stringify(t):null;return new Response(a,{status:s,headers:e?i||{"Content-Type":"application/json"}:i||{}})},u="1.7.1",r=[],o={},g=async t=>{const{method:s}=t.request,i=t.request.url,e=m(s,i,r);e&&(console.log("[TWD] Mock hit:",e.alias,s,i),t.respondWith((async()=>{let a=null;const n=t.request.headers.get("content-type")||"application/json";if(n.includes("application/json"))try{a=await t.request.clone().json()}catch{}else if(n.includes("form"))try{const l=await t.request.clone().formData();a={},l.forEach((x,E)=>{a[E]=x})}catch{}else if(n.includes("text"))try{a=await t.request.clone().text()}catch{}else if(n.includes("octet-stream"))try{a=await t.request.clone().arrayBuffer()}catch{}else if(n.includes("image"))try{a=await t.request.clone().blob()}catch{}else try{a=await t.request.clone().text()}catch{}return o[e.alias]||(o[e.alias]=0),o[e.alias]++,p(await self.clients.matchAll(),e,a,o[e.alias]),e.delay&&e.delay>0&&await new Promise(l=>setTimeout(l,e.delay)),y(e.response,e.status??200,e.responseHeaders)})()))},w=t=>{t!=="1.7.1"&&console.warn(`[TWD] ⚠️ Version mismatch detected:
+(function(){var d=t=>{try{return new RegExp(t),!0}catch{return!1}},f=new Set(["js","mjs","cjs","ts","tsx","jsx","mts","cts","css","scss","sass","less","styl","html","htm","xml","xhtml","vue","svelte","json","yaml","yml","toml","csv","txt","md","mdx","pdf","doc","docx","png","jpg","jpeg","gif","svg","webp","ico","bmp","avif","woff","woff2","ttf","eot","otf","mp3","mp4","webm","ogg","wav","zip","tar","gz","rar","map"]),c=t=>{const s=t.split("?")[0].match(/\.([a-zA-Z0-9]+)$/);return s?f.has(s[1].toLowerCase()):!1},h=(t,s)=>{const i=t.indexOf(s);if(i===-1)return!1;const e=i+s.length,a=t[e];if(a===void 0)return!0;const n=t.indexOf("?");return n!==-1&&e>n?!0:"?#&".includes(a)};function m(t,s,i){return i.find(e=>{const a=e.method.toLowerCase()===t.toLowerCase();if(e.urlRegex&&d(e.url)){const l=new RegExp(e.url);return a&&l.test(s)}if(c(e.url))return a&&s.includes(e.url);const n=e.url===s||h(s,e.url);return a&&n&&!c(s)})}function p(t,s,i,e){t.forEach(a=>a.postMessage({type:"EXECUTED",alias:s.alias,request:i,hitCount:e}))}var y=(t,s,i)=>{const e=![204,205,304].includes(s),a=e?JSON.stringify(t):null;return new Response(a,{status:s,headers:e?i||{"Content-Type":"application/json"}:i||{}})},u="1.7.3",r=[],o={},g=async t=>{const{method:s}=t.request,i=t.request.url,e=m(s,i,r);e&&(console.log("[TWD] Mock hit:",e.alias,s,i),t.respondWith((async()=>{let a=null;const n=t.request.headers.get("content-type")||"application/json";if(n.includes("application/json"))try{a=await t.request.clone().json()}catch{}else if(n.includes("form"))try{const l=await t.request.clone().formData();a={},l.forEach((x,E)=>{a[E]=x})}catch{}else if(n.includes("text"))try{a=await t.request.clone().text()}catch{}else if(n.includes("octet-stream"))try{a=await t.request.clone().arrayBuffer()}catch{}else if(n.includes("image"))try{a=await t.request.clone().blob()}catch{}else try{a=await t.request.clone().text()}catch{}return o[e.alias]||(o[e.alias]=0),o[e.alias]++,p(await self.clients.matchAll(),e,a,o[e.alias]),e.delay&&e.delay>0&&await new Promise(l=>setTimeout(l,e.delay)),y(e.response,e.status??200,e.responseHeaders)})()))},w=t=>{t!=="1.7.3"&&console.warn(`[TWD] ⚠️ Version mismatch detected:
 Client version: ${t}
 Service Worker version: ${u}
 

package/dist/plugin/removeMockServiceWorker.d.ts

@@ -0,0 +1,18 @@
+import { Plugin } from 'vite';
+/**
+ * Vite plugin to remove the mock service worker file from the build output.
+ * This is useful for production builds where you don't want the mock service worker to be included.
+ *
+ * @example
+ * ```ts
+ * import { removeMockServiceWorker } from 'twd-js';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     // ... other plugins
+ *     removeMockServiceWorker()
+ *   ]
+ * });
+ * ```
+ */
+export declare function removeMockServiceWorker(): Plugin;

package/dist/plugin/twdHmr.d.ts

@@ -0,0 +1,45 @@
+import { Plugin } from 'vite';
+/**
+ * Options for the TWD HMR plugin.
+ */
+export interface TwdHmrOptions {
+    /**
+     * Pattern to match test files. Defaults to `.twd.test.ts`.
+     * Can be a string (checked with `endsWith`) or a function that returns a boolean.
+     * @default ".twd.test.ts"
+     */
+    testFilePattern?: string | ((file: string) => boolean);
+}
+/**
+ * Vite plugin to handle HMR for TWD test files.
+ * When a TWD test file is updated, it forces a full page reload to prevent
+ * duplicate test entries that occur when HMR reloads test modules.
+ *
+ * This plugin only runs in development mode (serve) and does not affect Vitest test runs.
+ *
+ * @param options - Configuration options for the plugin
+ * @example
+ * ```ts
+ * import { twdHmr } from 'twd-js/vite-plugin';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     // ... other plugins
+ *     twdHmr() // Uses default pattern: .twd.test.ts
+ *   ]
+ * });
+ * ```
+ * @example
+ * ```ts
+ * // Custom pattern
+ * twdHmr({ testFilePattern: '.twd.test.tsx' })
+ * ```
+ * @example
+ * ```ts
+ * // Custom function
+ * twdHmr({
+ *   testFilePattern: (file) => file.includes('.twd.test.')
+ * })
+ * ```
+ */
+export declare function twdHmr(options?: TwdHmrOptions): Plugin;

package/dist/proxies/domMessage.d.ts

@@ -0,0 +1 @@
+export declare function domMessage(prefix: string, prop: PropertyKey, args: any[]): string;

package/dist/proxies/eventsMessage.d.ts

@@ -0,0 +1 @@
+export declare function eventsMessage(prefix: string, prop: PropertyKey, args: any[]): string;

package/dist/proxies/screenDom.d.ts

@@ -0,0 +1,45 @@
+import { screen, configure } from '@testing-library/dom';
+type ScreenDom = typeof screen;
+/**
+ * Set the app root selector used by screenDom queries. Package-internal —
+ * wired through `initTWD({ rootSelector })`. Not re-exported from `src/index.ts`.
+ */
+export declare const setRootSelector: (selector: string) => void;
+/**
+ * Reset screenDom module state. Only use in tests.
+ * @internal
+ */
+export declare const resetScreenDomState: () => void;
+/**
+ * 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;
+export declare const configureScreenDom: typeof configure;
+export {};

package/dist/proxies/userEvent.d.ts

@@ -0,0 +1,4 @@
+import { default as userEventLib } from '@testing-library/user-event';
+type UserEvent = typeof userEventLib;
+export declare const userEvent: UserEvent;
+export {};

package/dist/runner-ci.d.ts

@@ -1,28 +1,12 @@
-export declare const executeTests: () => Promise<{
-    handlers: Handler[];
-    testStatus: TestResult[];
-}>;
-
-declare interface Handler {
-    id: string;
-    name: string;
-    parent?: string;
-    handler: () => void | Promise<void>;
-    children?: string[];
-    type: 'suite' | 'test';
-    status?: 'idle' | 'pass' | 'fail' | 'skip' | 'running';
-    logs: string[];
-    depth: number;
-    only?: boolean;
-    skip?: boolean;
-}
-
-export declare const reportResults: (handlers: Handler[], testResults: TestResult[]) => void;
-
-declare interface TestResult {
-    id: string;
-    status: 'pass' | 'fail' | 'skip';
-    error?: string;
-}
-
-export { }
+import { Handler } from './runner';
+interface TestResult {
+    id: string;
+    status: 'pass' | 'fail' | 'skip';
+    error?: string;
+}
+export declare const reportResults: (handlers: Handler[], testResults: TestResult[]) => void;
+export declare const executeTests: () => Promise<{
+    handlers: Handler[];
+    testStatus: TestResult[];
+}>;
+export {};

package/dist/runner.d.ts

@@ -1,63 +1,52 @@
-export declare const afterEach: (fn: HookFn) => void;
-
-export declare const beforeEach: (fn: HookFn) => void;
-
-export declare const clearTests: () => void;
-
-export declare const describe: {
-    (name: string, handler: () => void): void;
-    only(name: string, handler: () => void): void;
-    skip(name: string, handler: () => void): void;
-};
-
-export declare interface Handler {
-    id: string;
-    name: string;
-    parent?: string;
-    handler: () => void | Promise<void>;
-    children?: string[];
-    type: 'suite' | 'test';
-    status?: 'idle' | 'pass' | 'fail' | 'skip' | 'running';
-    logs: string[];
-    depth: number;
-    only?: boolean;
-    skip?: boolean;
-}
-
-export declare const handlers: Map<string, Handler>;
-
-declare type HookFn = () => void | Promise<void>;
-
-export declare const it: {
-    (name: string, handler: () => void | Promise<void>): void;
-    only(name: string, handler: () => void | Promise<void>): void;
-    skip(name: string, handler?: () => void | Promise<void>): void;
-};
-
-export declare interface RunnerEvents {
-    onStart: (test: Handler) => void;
-    onPass: (test: Handler, retryAttempt?: number) => void;
-    onFail: (test: Handler, error: Error) => void;
-    onSkip: (test: Handler) => void;
-    onSuiteStart?: (suite: Handler) => void;
-    onSuiteEnd?: (suite: Handler) => void;
-}
-
-export declare class TestRunner {
-    private events;
-    private retryCount;
-    constructor(events: RunnerEvents, options?: TestRunnerOptions);
-    runAll(): Promise<Map<string, Handler>>;
-    runSingle(id: string): Promise<void>;
-    runByIds(ids: string[]): Promise<Map<string, Handler>>;
-    private runSuiteByIds;
-    private hasDescendantInSet;
-    private runSuite;
-    private runTest;
-}
-
-export declare interface TestRunnerOptions {
-    retryCount?: number;
-}
-
-export { }
+export interface Handler {
+    id: string;
+    name: string;
+    parent?: string;
+    handler: () => void | Promise<void>;
+    children?: string[];
+    type: 'suite' | 'test';
+    status?: 'idle' | 'pass' | 'fail' | 'skip' | 'running';
+    logs: string[];
+    depth: number;
+    only?: boolean;
+    skip?: boolean;
+}
+type HookFn = () => void | Promise<void>;
+export declare const handlers: Map<string, Handler>;
+export declare const describe: {
+    (name: string, handler: () => void): void;
+    only(name: string, handler: () => void): void;
+    skip(name: string, handler: () => void): void;
+};
+export declare const it: {
+    (name: string, handler: () => void | Promise<void>): void;
+    only(name: string, handler: () => void | Promise<void>): void;
+    skip(name: string, handler?: () => void | Promise<void>): void;
+};
+export declare const beforeEach: (fn: HookFn) => void;
+export declare const afterEach: (fn: HookFn) => void;
+export declare const clearTests: () => void;
+export interface RunnerEvents {
+    onStart: (test: Handler) => void;
+    onPass: (test: Handler, retryAttempt?: number) => void;
+    onFail: (test: Handler, error: Error) => void;
+    onSkip: (test: Handler) => void;
+    onSuiteStart?: (suite: Handler) => void;
+    onSuiteEnd?: (suite: Handler) => void;
+}
+export interface TestRunnerOptions {
+    retryCount?: number;
+}
+export declare class TestRunner {
+    private events;
+    private retryCount;
+    constructor(events: RunnerEvents, options?: TestRunnerOptions);
+    runAll(): Promise<Map<string, Handler>>;
+    runSingle(id: string): Promise<void>;
+    runByIds(ids: string[]): Promise<Map<string, Handler>>;
+    private runSuiteByIds;
+    private hasDescendantInSet;
+    private runSuite;
+    private runTest;
+}
+export {};

package/dist/twd-types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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");
+ */
+export type AssertionName = 'have.text' | 'contain.text' | 'be.empty' | 'have.attr' | 'have.value' | 'be.disabled' | 'be.enabled' | 'be.checked' | 'be.selected' | 'be.focused' | 'be.visible' | 'be.hidden' | 'have.class';
+/**
+ * Negatable assertion names (e.g., 'not.have.text').
+ */
+export type Negatable<T extends string> = T | `not.${T}`;
+/**
+ * All assertion names, including negated ones.
+ */
+export type AnyAssertion = Negatable<AssertionName>;
+/**
+ * Argument types for each assertion.
+ */
+export 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': [];
+    'be.hidden': [];
+    'have.class': [className: string];
+};
+/**
+ * Maps assertion name to its argument tuple.
+ */
+export type ArgsFor<A extends AnyAssertion> = A extends `not.${infer Base extends AssertionName}` ? AssertionArgs[Base] : A extends AssertionName ? AssertionArgs[A] : never;
+/**
+ * Overloads for the `should` function, for best IntelliSense.
+ *
+ * @example
+ * twd.should("have.text", "Hello");
+ * twd.should("be.empty");
+ * twd.should("have.class", "active");
+ */
+export 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: 'be.hidden'): TWDElemAPI;
+    (name: 'not.be.hidden'): TWDElemAPI;
+    (name: 'have.class', className: string): TWDElemAPI;
+    (name: 'not.have.class', className: string): TWDElemAPI;
+};
+/**
+ * The main API returned by `twd.get()`.
+ *
+ * @example
+ * ```ts
+ * const btn = await twd.get("button");
+ * btn.should("have.text", "Clicked").click();
+ *
+ * ```
+ *
+ */
+export 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;
+}
+/**
+ * Options for `twd.waitFor()`.
+ */
+export 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;
+}