Initial Commit

packages/testkit/testing/testing-dom/src/queries/queries.md

@@ -0,0 +1,64 @@
+# queries
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+The `queries` module re-exports the `@testing-library/react` query primitives — `screen`, `within`, `byRole`, `byLabelText`, `byPlaceholderText`, `byText`, `byDisplayValue`, `byAltText`, `byTitle`, `byTestId` — under one canonical import path so every package in the project reaches for the same API without individually depending on `@testing-library/react`. Keeping the re-export surface in one module also means upgrades to `@testing-library/react` touch a single file.
+
+## Features
+
+- Curated re-exports of every stable `@testing-library/react` query
+- `screen` and `within` helpers included for scoped queries
+- Types preserved — TS jumps straight to `@testing-library/react`'s definitions
+- Zero runtime overhead — pure re-export
+
+## Usage: Basic Example
+
+```tsx
+import { render, screen } from "@suaveplan/testing-dom";
+
+render(<button>save</button>);
+expect(screen.getByRole("button", { name: "save" })).toBeInTheDocument();
+```
+
+## Usage: Advanced Example
+
+```tsx
+import { render, screen, within } from "@suaveplan/testing-dom";
+
+render(
+    <form aria-label="login">
+        <input aria-label="email" />
+        <input aria-label="password" type="password" />
+        <button type="submit">sign in</button>
+    </form>
+);
+
+const form = screen.getByRole("form", { name: "login" });
+const scoped = within(form);
+expect(scoped.getByLabelText("email")).toBeInTheDocument();
+expect(scoped.getByRole("button", { name: "sign in" })).toBeEnabled();
+```
+
+## API Reference
+
+### Re-exported symbols
+
+- `screen` — global query root
+- `within(container)` — scoped queries
+- `getByRole` / `queryByRole` / `findByRole` — role-based
+- `getByLabelText` / `queryByLabelText` / `findByLabelText`
+- `getByPlaceholderText` / …
+- `getByText` / …
+- `getByDisplayValue` / …
+- `getByAltText` / …
+- `getByTitle` / …
+- `getByTestId` / …
+
+All retain their upstream type signatures.
+
+## Implementation Notes
+
+Rule #4 in `CLAUDE.md` forbids re-exporting external dependencies "for convenience" — the exception here is that this module serves as a project-wide swap point if we ever replace testing-library with another library. Every import path consumers use is `@suaveplan/testing-dom`, so a swap is a one-file change. The curated surface excludes `fireEvent` because userEvent (in `setup-user.ts`) is the preferred ergonomic wrapper — `fireEvent` is available via direct `@testing-library/react` import for callers who need the lower level.