Move docs/ package mirror into document-navigator plugin
Relocate the ~6k-file docs tree from the repo root into plugins/document-navigator/docs/ so the plugin is self-contained and portable. docs/superpowers/ (specs and plans) stays at the repo root. Moved via cp+rm rather than git mv because directory rename() fails with EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the identical-content files at commit time. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,60 @@
|
||||
# render-component
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
## Purpose
|
||||
|
||||
`renderComponent` wraps `@testing-library/react`'s `render` with two project-wide defaults: (1) it calls `cleanup()` before mounting so orphaned trees from a previous test never pollute the current test's query space, and (2) it throws `TestingDomError("TESTING_DOM.RENDER.FAILED")` on any underlying failure so callers always see a typed error with structured context.
|
||||
|
||||
## Features
|
||||
|
||||
- Automatic pre-mount `cleanup()` — no stray DOM from prior tests
|
||||
- Typed failure mode via `TestingDomError`
|
||||
- Thin wrapper — returns the same `RenderResult` as upstream
|
||||
- Accepts the full `RenderOptions` surface (`container`, `baseElement`, `hydrate`, `wrapper`)
|
||||
|
||||
## Usage: Basic Example
|
||||
|
||||
```tsx
|
||||
import { renderComponent } from "@suaveplan/testing-dom";
|
||||
|
||||
const { getByRole } = renderComponent(<button>save</button>);
|
||||
expect(getByRole("button", { name: "save" })).toBeInTheDocument();
|
||||
```
|
||||
|
||||
## Usage: Advanced Example
|
||||
|
||||
```tsx
|
||||
import { renderComponent, TestingDomError, TESTING_DOM_CODES } from "@suaveplan/testing-dom";
|
||||
import { MyProvider } from "./MyProvider";
|
||||
|
||||
const Wrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
|
||||
<MyProvider>{children}</MyProvider>
|
||||
);
|
||||
|
||||
try {
|
||||
const { container, rerender } = renderComponent(<App />, { wrapper: Wrapper });
|
||||
expect(container.firstChild).toHaveTextContent("Hello");
|
||||
rerender(<App locale="fr" />);
|
||||
expect(container.firstChild).toHaveTextContent("Bonjour");
|
||||
} catch (err) {
|
||||
if (err instanceof TestingDomError && err.code === TESTING_DOM_CODES.RENDER_FAILED) {
|
||||
console.error("render failed:", err.cause);
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### `renderComponent(ui, options?): RenderResult`
|
||||
|
||||
- `ui` — React element or functional component
|
||||
- `options` — passed through to upstream `render` (full `RenderOptions` surface)
|
||||
- Returns the upstream `RenderResult` unchanged
|
||||
- Throws `TestingDomError("TESTING_DOM.RENDER.FAILED")` on any underlying failure, preserving `cause`
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
Calling `cleanup()` BEFORE mount (rather than after) is deliberate — it means a test file that forgot to register `afterEach(cleanup)` still gets isolated trees between tests. It also avoids the subtle afterEach-ordering issue where a cleanup hook might fire before the test's expectations if another `afterEach` throws. Catching and rethrowing as `TestingDomError` normalises the error surface for downstream code; the underlying testing-library error lives on `err.cause` for debugging.
|
||||
Reference in New Issue
Block a user