@describe-me/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grzegorz Łotysz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# @describe-me/react
+
+The React adapter for [describe-me](https://github.com/grzehub/describe-me): a
+drop-in `render` for `vitest-browser-react` that records a frame after mount and
+after every `rerender`, and reads the component's name and props for the docs.
+This is the only React-specific code in the project.
+
+## Install
+
+```sh
+pnpm add -D @describe-me/react
+```
+
+## Usage
+
+The package re-exports everything `vitest-browser-react` offers, with `render`
+swapped for the recording one, so switching an existing test is one import.
+
+```tsx
+import { render, step } from '@describe-me/react'
+
+const screen = await render(<Counter initial={1} />)
+await step('increment', () => screen.getByRole('button', { name: 'add' }).click())
+```
+
+With `@describe-me/vitest`'s `describeMe()` plugin you do not even need that:
+the plugin redirects `vitest-browser-react` imports to this adapter, so tests
+record frames unchanged.
+
+See the [root README](https://github.com/grzehub/describe-me#readme) for the
+full picture.

package/dist/describe-element.d.ts

@@ -0,0 +1,4 @@
+import type { ReactElement } from 'react';
+import { type ComponentInfo } from '@describe-me/core';
+/** Pull the component name and JSON-safe props out of a React element. */
+export declare function describeElement(ui: ReactElement): ComponentInfo;

package/dist/describe-element.js

@@ -0,0 +1,12 @@
+import { serializeValue } from '@describe-me/core';
+/** Pull the component name and JSON-safe props out of a React element. */
+export function describeElement(ui) {
+    const type = ui.type;
+    const name = typeof type === 'string'
+        ? type
+        : (type?.displayName ??
+            type?.name ??
+            'Anonymous');
+    const props = serializeValue(ui.props ?? {});
+    return { name, props };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from 'vitest-browser-react';
+export { step } from '@describe-me/core';
+export { render } from './render.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+// Everything vitest-browser-react offers, with `render` swapped for the recording one.
+export * from 'vitest-browser-react';
+export { step } from '@describe-me/core';
+export { render } from './render.js';

package/dist/label-for.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentInfo } from '@describe-me/core';
+/** A JSX-looking one-liner for a frame label, e.g. `<Counter initial=1 />`. */
+export declare function labelFor(info: ComponentInfo): string;

package/dist/label-for.js

@@ -0,0 +1,9 @@
+/** A JSX-looking one-liner for a frame label, e.g. `<Counter initial=1 />`. */
+export function labelFor(info) {
+    const shown = Object.entries(info.props)
+        .filter(([key, value]) => key !== 'children' &&
+        (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'))
+        .slice(0, 3)
+        .map(([key, value]) => (value === true ? key : `${key}=${JSON.stringify(value)}`));
+    return `<${info.name}${shown.length ? ' ' + shown.join(' ') : ''} />`;
+}

package/dist/render.d.ts

@@ -0,0 +1,11 @@
+import { render as baseRender } from 'vitest-browser-react';
+import { type ReactElement } from 'react';
+type BaseRender = typeof baseRender;
+type RenderOptions = Parameters<BaseRender>[1];
+type Screen = Awaited<ReturnType<BaseRender>>;
+/**
+ * Drop-in for `render` from vitest-browser-react. Records a frame after mount
+ * and after every `rerender`.
+ */
+export declare function render(ui: ReactElement, options?: RenderOptions): Promise<Screen>;
+export {};

package/dist/render.js

@@ -0,0 +1,27 @@
+import { render as baseRender } from 'vitest-browser-react';
+import { isValidElement } from 'react';
+import { recorder } from '@describe-me/core';
+import { describeElement } from './describe-element.js';
+import { labelFor } from './label-for.js';
+/**
+ * Drop-in for `render` from vitest-browser-react. Records a frame after mount
+ * and after every `rerender`.
+ */
+export async function render(ui, options) {
+    const screen = await baseRender(ui, options);
+    if (isValidElement(ui)) {
+        const info = describeElement(ui);
+        recorder.setComponent(info);
+        await recorder.capture('render', labelFor(info), { props: info.props });
+    }
+    const originalRerender = screen.rerender.bind(screen);
+    screen.rerender = (async (next) => {
+        const result = await originalRerender(next);
+        if (isValidElement(next)) {
+            const info = describeElement(next);
+            await recorder.capture('render', `rerender ${labelFor(info)}`, { props: info.props });
+        }
+        return result;
+    });
+    return screen;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@describe-me/react",
+  "version": "0.1.0",
+  "description": "React adapter for describe-me: a drop-in render that records frames",
+  "keywords": [
+    "vitest",
+    "storybook",
+    "component documentation",
+    "visual testing",
+    "react",
+    "testing"
+  ],
+  "license": "MIT",
+  "author": "Grzegorz Łotysz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/grzehub/describe-me.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://grzehub.github.io/describe-me/",
+  "bugs": "https://github.com/grzehub/describe-me/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@describe-me/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "vitest-browser-react": ">=2"
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "react": "^19.3.0",
+    "vitest-browser-react": "^2.3.0",
+    "vitest": "^5.0.1"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.json"
+  }
+}