# 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.