@describe-me/react 0.5.4 → 0.6.0

package/README.md

@@ -14,7 +14,7 @@ story, and each step is a frame you can scrub through. Stories cannot rot,
 because they are tests. If one drifts from the component, CI goes red.
 
 Status: prototype. React 18 and 19, Vitest 4 and 5 in browser mode or jsdom,
-static snapshots.
+recorded frames and Live in the viewer.
 
 ## Which package do I need
 
@@ -52,15 +52,19 @@ Drop-in `render` functions that record a frame after mount and after every
 `rerender`, and read the component's name and props for the docs. It is the
 only React-specific code in describe-me.
 
-| Entry point                                                                                                        | Wraps                    | For                 |
-| ------------------------------------------------------------------------------------------------------------------ | ------------------------ | ------------------- |
-| [`@describe-me/react`](https://grzehub.github.io/describe-me/api.html#entry-react)                                 | `vitest-browser-react`   | Vitest browser mode |
-| [`@describe-me/react/testing-library`](https://grzehub.github.io/describe-me/api.html#entry-react-testing-library) | `@testing-library/react` | jsdom               |
-
-Each entry point re-exports its test library with the recording functions
-swapped in. With the `describeMe()` plugin you never import them yourself: it
-redirects your `render` imports, those in your own `test-utils` included.
-Install the test library your tests use. Both are optional peers.
+| Entry point                                                                                                                  | Wraps                                | For                 |
+| ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------- |
+| [`@describe-me/react`](https://grzehub.github.io/describe-me/api.html#entry-react)                                           | `vitest-browser-react`               | Vitest browser mode |
+| [`@describe-me/react/testing-library`](https://grzehub.github.io/describe-me/api.html#entry-react-testing-library)           | `@testing-library/react`             | jsdom               |
+| [`@describe-me/react/live`](https://grzehub.github.io/describe-me/api.html#entry-react-live)                                 | stands in for `vitest-browser-react` | the live preview    |
+| [`@describe-me/react/live-testing-library`](https://grzehub.github.io/describe-me/api.html#entry-react-live-testing-library) | `@testing-library/react`             | the live preview    |
+
+The first two entry points re-export their test library with the recording
+functions swapped in. With the `describeMe()` plugin you never import them
+yourself: it redirects your `render` imports, those in your own `test-utils`
+included. It redirects them to the live entry points only in the live preview,
+so tests never import those. Install the test library your tests use. Both are
+optional peers.
 
 ## License
 

package/dist/empty-live-result.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+import type { LiveMountOptions } from './mount-live.js';
+/** What the live render returns while it has nothing to mount. */
+export interface EmptyLiveResult {
+    container: Element | DocumentFragment;
+    baseElement: Element;
+    rerender(ui: ReactNode): unknown;
+    unmount(): void;
+    asFragment(): DocumentFragment;
+    debug(): void;
+}
+/**
+ * The result of a live render that had nothing to mount yet. Its `rerender`
+ * renders again into the same container, so the component mounts at the
+ * test's rerender.
+ */
+export declare function emptyLiveResult(options: LiveMountOptions, render: (ui: ReactNode, options: LiveMountOptions) => unknown): EmptyLiveResult;

package/dist/empty-live-result.js

@@ -0,0 +1,18 @@
+/**
+ * The result of a live render that had nothing to mount yet. Its `rerender`
+ * renders again into the same container, so the component mounts at the
+ * test's rerender.
+ */
+export function emptyLiveResult(options, render) {
+    const baseElement = options.baseElement ?? document.body;
+    const container = options.container ?? baseElement.appendChild(document.createElement('div'));
+    const next = { ...options, baseElement, container };
+    return {
+        container,
+        baseElement,
+        rerender: (ui) => render(ui, next),
+        unmount: () => undefined,
+        asFragment: () => document.createDocumentFragment(),
+        debug: () => undefined,
+    };
+}

package/dist/is-empty-live-ui.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether a test rendered nothing yet: `null`, `undefined`, a boolean, `''`,
+ * or a fragment whose children are all empty. The live render then waits for
+ * the test's `rerender`.
+ */
+export declare function isEmptyLiveUi(ui: unknown): boolean;

package/dist/is-empty-live-ui.js

@@ -0,0 +1,18 @@
+import { Fragment, isValidElement } from 'react';
+/**
+ * Whether a test rendered nothing yet: `null`, `undefined`, a boolean, `''`,
+ * or a fragment whose children are all empty. The live render then waits for
+ * the test's `rerender`.
+ */
+export function isEmptyLiveUi(ui) {
+    if (ui === null || ui === undefined || typeof ui === 'boolean' || ui === '') {
+        return true;
+    }
+    if (Array.isArray(ui)) {
+        return ui.every((child) => isEmptyLiveUi(child));
+    }
+    if (!isValidElement(ui) || ui.type !== Fragment) {
+        return false;
+    }
+    return isEmptyLiveUi(ui.props.children);
+}

package/dist/live-cleanup.d.ts

@@ -0,0 +1,2 @@
+/** Stands in for `cleanup` on the live page, where the component stays mounted. */
+export declare function liveCleanup(): void;

package/dist/live-cleanup.js

@@ -0,0 +1,2 @@
+/** Stands in for `cleanup` on the live page, where the component stays mounted. */
+export function liveCleanup() { }

package/dist/live-render-hook-testing-library.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Stands in for Testing Library's `renderHook` on the live page. A hook shows
+ * nothing, so it stops the test and the page reports `no-render`.
+ */
+export declare function liveRenderHookTestingLibrary(): never;

package/dist/live-render-hook-testing-library.js

@@ -0,0 +1,8 @@
+import { liveStop } from '@describe-me/core/live';
+/**
+ * Stands in for Testing Library's `renderHook` on the live page. A hook shows
+ * nothing, so it stops the test and the page reports `no-render`.
+ */
+export function liveRenderHookTestingLibrary() {
+    throw liveStop();
+}

package/dist/live-render-hook.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Stands in for `renderHook` from vitest-browser-react on the live page. A
+ * hook shows nothing, so it stops the test and the page reports `no-render`.
+ */
+export declare function liveRenderHook(): Promise<never>;

package/dist/live-render-hook.js

@@ -0,0 +1,8 @@
+import { liveStop } from '@describe-me/core/live';
+/**
+ * Stands in for `renderHook` from vitest-browser-react on the live page. A
+ * hook shows nothing, so it stops the test and the page reports `no-render`.
+ */
+export function liveRenderHook() {
+    return Promise.reject(liveStop());
+}

package/dist/live-render-testing-library.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+import { type LiveMountOptions } from './mount-live.js';
+/**
+ * Stands in for Testing Library's `render` on the live page. It mounts the
+ * component and throws the stop signal, so the test ends at its first
+ * render. For an empty UI it waits for the test's `rerender`.
+ */
+export declare function liveRenderTestingLibrary(ui: ReactNode, options?: LiveMountOptions): unknown;

package/dist/live-render-testing-library.js

@@ -0,0 +1,18 @@
+import { within } from '@testing-library/react';
+import { liveStop } from '@describe-me/core/live';
+import { emptyLiveResult } from './empty-live-result.js';
+import { isEmptyLiveUi } from './is-empty-live-ui.js';
+import { mountLive } from './mount-live.js';
+/**
+ * Stands in for Testing Library's `render` on the live page. It mounts the
+ * component and throws the stop signal, so the test ends at its first
+ * render. For an empty UI it waits for the test's `rerender`.
+ */
+export function liveRenderTestingLibrary(ui, options = {}) {
+    if (isEmptyLiveUi(ui)) {
+        const result = emptyLiveResult(options, liveRenderTestingLibrary);
+        return { ...within(result.baseElement), ...result };
+    }
+    mountLive(ui, options);
+    throw liveStop();
+}

package/dist/live-render.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+import { type LiveMountOptions } from './mount-live.js';
+/**
+ * Stands in for `render` from vitest-browser-react on the live page. It
+ * mounts the component and rejects with the stop signal, so the test ends at
+ * its first render. For an empty UI it waits for the test's `rerender`.
+ */
+export declare function liveRender(ui: ReactNode, options?: LiveMountOptions): Promise<unknown>;

package/dist/live-render.js

@@ -0,0 +1,27 @@
+import { liveInert, liveStop } from '@describe-me/core/live';
+import { emptyLiveResult } from './empty-live-result.js';
+import { isEmptyLiveUi } from './is-empty-live-ui.js';
+import { mountLive } from './mount-live.js';
+/** The rest of a vitest-browser-react screen, such as its locators, is inert. Its `then` too. */
+function withInertRest(result) {
+    return new Proxy(result, {
+        get(target, key, receiver) {
+            if (key in target) {
+                return Reflect.get(target, key, receiver);
+            }
+            return Reflect.get(liveInert(), key);
+        },
+    });
+}
+/**
+ * Stands in for `render` from vitest-browser-react on the live page. It
+ * mounts the component and rejects with the stop signal, so the test ends at
+ * its first render. For an empty UI it waits for the test's `rerender`.
+ */
+export function liveRender(ui, options = {}) {
+    if (isEmptyLiveUi(ui)) {
+        return Promise.resolve(withInertRest(emptyLiveResult(options, liveRender)));
+    }
+    mountLive(ui, options);
+    return Promise.reject(liveStop());
+}

package/dist/live-testing-library.d.ts

@@ -0,0 +1,4 @@
+export * from '@testing-library/react';
+export { liveCleanup as cleanup } from './live-cleanup.js';
+export { liveRenderTestingLibrary as render } from './live-render-testing-library.js';
+export { liveRenderHookTestingLibrary as renderHook } from './live-render-hook-testing-library.js';

package/dist/live-testing-library.js

@@ -0,0 +1,6 @@
+// Stands in for @testing-library/react on the live preview page, with `render`,
+// `renderHook` and `cleanup` swapped. Not for import in tests.
+export * from '@testing-library/react';
+export { liveCleanup as cleanup } from './live-cleanup.js';
+export { liveRenderTestingLibrary as render } from './live-render-testing-library.js';
+export { liveRenderHookTestingLibrary as renderHook } from './live-render-hook-testing-library.js';

package/dist/live.d.ts

@@ -0,0 +1,3 @@
+export { liveCleanup as cleanup } from './live-cleanup.js';
+export { liveRender as render } from './live-render.js';
+export { liveRenderHook as renderHook } from './live-render-hook.js';

package/dist/live.js

@@ -0,0 +1,4 @@
+// Stands in for vitest-browser-react on the live preview page. Not for import in tests.
+export { liveCleanup as cleanup } from './live-cleanup.js';
+export { liveRender as render } from './live-render.js';
+export { liveRenderHook as renderHook } from './live-render-hook.js';

package/dist/mount-live.d.ts

@@ -0,0 +1,17 @@
+import { type ComponentType, type ReactNode } from 'react';
+import { type RootOptions } from 'react-dom/client';
+/** The render options, of either flavour, that the live mount reads. */
+export interface LiveMountOptions {
+    container?: Element | DocumentFragment;
+    baseElement?: Element;
+    wrapper?: ComponentType<{
+        children?: ReactNode;
+    }>;
+    createRootOptions?: RootOptions;
+}
+/**
+ * Mounts what a test rendered, in its wrapper, with `createRoot` as Testing
+ * Library does, and reports the page as mounted. A page that has a status
+ * already mounts nothing. Either way the caller then stops the test.
+ */
+export declare function mountLive(ui: ReactNode, options?: LiveMountOptions): void;

package/dist/mount-live.js

@@ -0,0 +1,24 @@
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { liveStatus, reportLiveStatus } from '@describe-me/core/live';
+import { nameLiveMocks } from './name-live-mocks.js';
+/**
+ * Mounts what a test rendered, in its wrapper, with `createRoot` as Testing
+ * Library does, and reports the page as mounted. A page that has a status
+ * already mounts nothing. Either way the caller then stops the test.
+ */
+export function mountLive(ui, options = {}) {
+    if (liveStatus() !== null) {
+        return;
+    }
+    nameLiveMocks(ui);
+    // Testing Library's own `beforeAll` turns it on, but the live component
+    // runs outside `act()`, where React would warn about every update.
+    const scope = globalThis;
+    scope.IS_REACT_ACT_ENVIRONMENT = false;
+    const baseElement = options.baseElement ?? document.body;
+    const container = options.container ?? baseElement.appendChild(document.createElement('div'));
+    const element = options.wrapper === undefined ? ui : createElement(options.wrapper, null, ui);
+    createRoot(container, options.createRootOptions).render(element);
+    reportLiveStatus('mounted');
+}

package/dist/name-live-mocks.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Names every unnamed mock in what a test rendered after the prop it is
+ * passed as, so a click shows as `onSelect("Rename")`. Walks element props,
+ * children and arrays, a few levels deep.
+ */
+export declare function nameLiveMocks(node: unknown, depth?: number): void;

package/dist/name-live-mocks.js

@@ -0,0 +1,42 @@
+import { isValidElement } from 'react';
+const MAX_DEPTH = 5;
+/** The name Vitest gives a mock that was never named. */
+const UNNAMED = 'vi.fn()';
+/** Duck typed, so it needs nothing from Vitest. */
+function isUnnamedMock(value) {
+    if (typeof value !== 'function') {
+        return false;
+    }
+    const mock = value;
+    return (mock._isMockFunction === true &&
+        typeof mock.getMockName === 'function' &&
+        typeof mock.mockName === 'function' &&
+        mock.getMockName() === UNNAMED);
+}
+/**
+ * Names every unnamed mock in what a test rendered after the prop it is
+ * passed as, so a click shows as `onSelect("Rename")`. Walks element props,
+ * children and arrays, a few levels deep.
+ */
+export function nameLiveMocks(node, depth = 0) {
+    if (depth > MAX_DEPTH) {
+        return;
+    }
+    if (Array.isArray(node)) {
+        for (const item of node) {
+            nameLiveMocks(item, depth + 1);
+        }
+        return;
+    }
+    if (!isValidElement(node)) {
+        return;
+    }
+    for (const [prop, value] of Object.entries(node.props)) {
+        if (isUnnamedMock(value)) {
+            value.mockName(prop);
+        }
+        else {
+            nameLiveMocks(value, depth + 1);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/react",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Living component documentation from your Vitest tests: the React adapter of describe-me",
   "keywords": [
     "vitest",
@@ -37,6 +37,14 @@
     "./testing-library": {
       "types": "./dist/testing-library.d.ts",
       "default": "./dist/testing-library.js"
+    },
+    "./live": {
+      "types": "./dist/live.d.ts",
+      "default": "./dist/live.js"
+    },
+    "./live-testing-library": {
+      "types": "./dist/live-testing-library.d.ts",
+      "default": "./dist/live-testing-library.js"
     }
   },
   "files": [
@@ -48,13 +56,14 @@
     "./dist/render-testing-library.js"
   ],
   "dependencies": {
-    "@describe-me/core": "^0.5.4"
+    "@describe-me/core": "^0.6.0"
   },
   "peerDependencies": {
     "@testing-library/react": "^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
     "vitest-browser-react": "^2.0.0",
-    "@describe-me/vitest": "^0.5.4"
+    "@describe-me/vitest": "^0.6.0"
   },
   "peerDependenciesMeta": {
     "@testing-library/react": {
@@ -73,7 +82,7 @@
     "react-dom": "^19.3.0",
     "vitest": "^5.0.1",
     "vitest-browser-react": "^2.3.0",
-    "@describe-me/vitest": "^0.5.4"
+    "@describe-me/vitest": "^0.6.0"
   },
   "scripts": {
     "build": "rimraf dist && tsc -p tsconfig.json"