@describe-me/react 0.5.3 → 0.6.0

package/README.md

@@ -1,54 +1,71 @@
 # @describe-me/react
 
-The React adapter for [describe-me](https://github.com/grzehub/describe-me):
-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. This is the
-only React-specific code in the project.
+**Your tests are your stories.** The React adapter of describe-me: living
+component documentation generated from the Vitest tests you already have.
 
-| entry point                          | wraps                    | for                      |
-| ------------------------------------ | ------------------------ | ------------------------ |
-| `@describe-me/react`                 | `vitest-browser-react`   | Vitest browser mode      |
-| `@describe-me/react/testing-library` | `@testing-library/react` | jsdom and other DOM envs |
+**[Read the docs](https://grzehub.github.io/describe-me/)** · open the viewer
+of the [browser-mode example](https://grzehub.github.io/describe-me/examples/react-browser/)
+or the [jsdom example](https://grzehub.github.io/describe-me/examples/react-jsdom/)
+· [Limitations](https://grzehub.github.io/describe-me/limitations.html)
 
-Both test libraries are optional peers: install the one your tests use.
+describe-me captures the DOM after each step of a test and shows the result as
+a browsable catalog. `describe` blocks become the sidebar, each `it` is a
+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.
 
-## Install
+Status: prototype. React 18 and 19, Vitest 4 and 5 in browser mode or jsdom,
+recorded frames and Live in the viewer.
+
+## Which package do I need
+
+| Package               | What it is                                   | Install it              |
+| --------------------- | -------------------------------------------- | ----------------------- |
+| `describe-me`         | the viewer and the `describe-me` CLI         | yes                     |
+| `@describe-me/vitest` | the Vitest plugin, setup files and reporter  | yes                     |
+| `@describe-me/react`  | `render` functions that record frames (this) | yes                     |
+| `@describe-me/core`   | the recorder and the manifest types          | no, the others bring it |
+
+## Quick start
 
 ```sh
-pnpm add -D @describe-me/react
+pnpm add -D describe-me @describe-me/vitest @describe-me/react
 ```
 
-All describe-me packages must be on the same version
-([One version for all packages](https://grzehub.github.io/describe-me/installation.html#lockstep)).
+```ts
+// vitest.config.ts
+import { describeMe } from '@describe-me/vitest/plugin'
 
-## Usage
+export default defineConfig({
+  plugins: [react(), describeMe()],
+  test: { environment: 'jsdom' }, // or your browser-mode settings
+})
+```
 
-Each entry point re-exports everything its test library offers, with the
-recording functions swapped in, so switching an existing test is one import.
-`@describe-me/react` swaps `render`. The Testing Library entry swaps `render`,
-`fireEvent` and `cleanup`: every `fireEvent` call records a frame, and
-`cleanup` takes the closing frame before it unmounts. When the render frame is
-taken follows the plugin's
-[`renderFrame`](https://grzehub.github.io/describe-me/configuration.html#render-frame)
-option.
+Run your tests, then `describe-me dev` opens the viewer.
+[Getting started](https://grzehub.github.io/describe-me/getting-started.html)
+walks through both environments. Keep all describe-me packages on one version
+([why](https://grzehub.github.io/describe-me/installation.html#lockstep)).
 
-```tsx
-import { render, step } from '@describe-me/react'
+## This package
 
-const screen = await render(<Counter initial={1} />)
-await step('increment', () => screen.getByRole('button', { name: 'add' }).click())
-```
+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.
 
-```tsx
-import { render } from '@describe-me/react/testing-library'
+| 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    |
 
-// Synchronous, exactly like the original.
-const { getByRole } = render(<Counter initial={1} />)
-```
+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.
 
-With `@describe-me/vitest`'s `describeMe()` plugin you do not even need that:
-the plugin redirects `vitest-browser-react` or `@testing-library/react` imports
-to the matching entry point, including imports made from your own
-`test-utils` wrapper, so tests record frames unchanged.
+## License
 
-See the [docs](https://grzehub.github.io/describe-me/) for the full picture.
+MIT

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,13 +1,15 @@
 {
   "name": "@describe-me/react",
-  "version": "0.5.3",
-  "description": "React adapter for describe-me: drop-in render functions that record frames",
+  "version": "0.6.0",
+  "description": "Living component documentation from your Vitest tests: the React adapter of describe-me",
   "keywords": [
     "vitest",
+    "react",
     "storybook",
+    "storybook alternative",
     "component documentation",
-    "visual testing",
-    "react",
+    "living documentation",
+    "jsdom",
     "testing"
   ],
   "license": "MIT",
@@ -35,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": [
@@ -46,13 +56,14 @@
     "./dist/render-testing-library.js"
   ],
   "dependencies": {
-    "@describe-me/core": "^0.5.3"
+    "@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.3"
+    "@describe-me/vitest": "^0.6.0"
   },
   "peerDependenciesMeta": {
     "@testing-library/react": {
@@ -71,7 +82,7 @@
     "react-dom": "^19.3.0",
     "vitest": "^5.0.1",
     "vitest-browser-react": "^2.3.0",
-    "@describe-me/vitest": "^0.5.3"
+    "@describe-me/vitest": "^0.6.0"
   },
   "scripts": {
     "build": "rimraf dist && tsc -p tsconfig.json"