@overdoser/react-toolkit 0.0.2 → 0.0.3

package/AGENTS.md

@@ -0,0 +1,109 @@
+# AGENTS.md — @overdoser/react-toolkit
+
+Guidance for AI coding assistants integrating this library into a consumer project. Drop the relevant rules into your own project's AGENTS.md / CLAUDE.md / Cursor rules / Copilot instructions.
+
+For exhaustive component reference (every prop, every variant, every signature), see `llms.txt` in this package. For machine-readable structured data, see `manifest.json`.
+
+## Setup checklist
+
+1. Install:
+   ```bash
+   npm install @overdoser/react-toolkit
+   ```
+2. Install the optional peer **only if** you'll use `Form`/`FormField`:
+   ```bash
+   npm install react-hook-form
+   ```
+3. Import the theme stylesheet **once** at the app entry point:
+   ```ts
+   import '@overdoser/react-toolkit/theme.css';
+   ```
+   Without this, components render unstyled.
+
+## Import rules
+
+- Always import from the package root: `import { Button } from '@overdoser/react-toolkit'`. Do **not** reach into subpaths (`@overdoser/react-toolkit/dist/...`) — they're not part of the public API.
+- The only valid stylesheet subpath is `@overdoser/react-toolkit/theme.css`.
+
+## Hard rules (don't violate)
+
+1. **Don't ship raw `<button>`, `<input>`, `<select>`, `<textarea>`, `<a>` for UI affordances.** Use the toolkit's `Button`, `Input`, `Select`, `Textarea`, `Link` so styling and a11y come for free.
+2. **Inside `<Form>`, every focusable input must be wrapped in `<FormField>`.** Don't manually wire `value`/`onChange`/`name` on the inner input — `FormField` clones the child to inject them.
+3. **`<Modal>` content must be wrapped in `Modal.Header`, `Modal.Body`, `Modal.Footer`.** Raw children may render but they bypass focus targeting and styling.
+4. **Use `inputSize`, not `size`,** on `Input`/`Select`/`Textarea`. The native `size` attribute is preserved separately.
+5. **`Form`'s prop is `form`, not `formMethods`.** Pass the result of `useForm()`.
+6. **`Button` uses `loadingStyle`** (`'dots' | 'shimmer' | 'border'`), not `loadingType`.
+7. **`Typography` `color`** is an enum (`default | muted | primary | danger | success`), not a free-form string. The native HTML `color` attribute is omitted.
+8. **`Popover` content goes in the `content` prop**, not as children. `children` is typed `never`.
+9. **Server-side `Table`:** if you provide `onSort`, the table will not sort or paginate `data` itself. Your backend must return the page already sorted and sliced. Pass `pagination.totalRows` for the paginator to compute pages.
+10. **Theming is via CSS custom properties** (`--crk-*`) on `:root`. Don't override styles by hand-writing CSS that targets internal class names — those are hashed and unstable. Use the `classes` prop where finer control is needed.
+
+## Decision flow
+
+- **Need a select?**
+  - Few options, native UX OK → `<Select options={...} />`.
+  - Many options, want a search filter → `<Select searchable options={...} />`.
+  - Multi-pick with chips → `<Select multiple options={...} onValuesChange={...} />`.
+  - You want it to look like a "menu trigger" instead of a form input → `<Dropdown options={...} value={...} onChange={...} />` (select-mode dropdown).
+
+- **Need a menu (Edit / Delete / Archive)?** → `<Dropdown trigger={...}>` with `<DropdownItem>` children.
+
+- **Need a tooltip / hover card / contextual panel?** → `<Popover trigger={...} content={...} />`.
+
+- **Need a confirm prompt or a full dialog?** → `<Modal>` with `Modal.Header`/`Body`/`Footer`. Always provide either `aria-label` or use a `Modal.Header` (it's auto-wired as `aria-labelledby`).
+
+- **Need a data table?** → `<Table>`.
+  - All data in memory → don't pass `onSort`; pass `pagination` (without `totalRows`) for client-side paging.
+  - Data from a server → pass `sortConfig` + `onSort`, and `pagination` with `totalRows`.
+
+- **Multi-step / wizard form?** Use one `useForm()` per step OR a single `<Form>` wrapping all steps with conditional rendering. The toolkit doesn't ship a stepper.
+
+## Common shapes (copy-paste)
+
+### Wire a Select inside a Form
+```tsx
+<FormField name="role" label="Role">
+  <Select options={[
+    { value: 'admin', label: 'Admin' },
+    { value: 'member', label: 'Member' },
+  ]} />
+</FormField>
+```
+`FormField` bridges `onChange` → `onValueChange` automatically; just pass `options`.
+
+### Wire a Checkbox inside a Form
+```tsx
+<FormField name="acceptTerms">
+  <Checkbox label="I accept the terms" />
+</FormField>
+```
+`FormField` bridges the boolean form value to `checked`.
+
+### Wire a RadioGroup inside a Form
+```tsx
+<FormField name="plan" label="Plan">
+  <RadioGroup name="plan" aria-label="Plan">
+    <Radio value="free" label="Free" />
+    <Radio value="pro" label="Pro" />
+  </RadioGroup>
+</FormField>
+```
+
+## Recipes
+
+Full copy-paste-able files live alongside this doc. Each is one self-contained file that you can drop into a project. Adjust types/imports for your codebase.
+
+- [recipes/login-form.tsx](./recipes/login-form.tsx) — Form + Input + Button with validation rules.
+- [recipes/paginated-table.tsx](./recipes/paginated-table.tsx) — Client-side sortable + paginated table.
+- [recipes/server-side-table.tsx](./recipes/server-side-table.tsx) — Server-driven sort & pagination.
+- [recipes/confirm-modal.tsx](./recipes/confirm-modal.tsx) — Reusable destructive-action confirm dialog.
+- [recipes/searchable-multi-select.tsx](./recipes/searchable-multi-select.tsx) — Multi-select with search and form integration.
+- [recipes/dropdown-menu.tsx](./recipes/dropdown-menu.tsx) — Row action menu with `Dropdown` + `DropdownItem`.
+
+## Anti-patterns to refuse
+
+- "Wrap every component in a custom `Card` div for spacing" — spacing comes from the consumer's layout. Don't pollute toolkit components with wrapper divs.
+- "Inline-style every component instead of using `classes` / `className`" — use `classes` for targeted overrides; reserve `style` for one-off layout tweaks.
+- "Pass `loading` and `disabled` together on `Button`" — `loading` already implies disabled. Doubling up is harmless but redundant.
+- "Mock `react-hook-form` to make `Form` work in tests" — use a real `useForm()` in your test wrappers; the toolkit's `FormField` reads context.
+- "Manually call `e.preventDefault()` on `Form` submit" — `Form` already wraps `onSubmit` in `form.handleSubmit`. Just return data.

package/llms.txt

@@ -0,0 +1,480 @@
+# @overdoser/react-toolkit — LLM reference
+
+A flat, exhaustive component reference for AI coding assistants. Every component, every prop, every allowed string-literal value, with a minimal copy-paste example. If something isn't here, it isn't in the public API.
+
+Package: `@overdoser/react-toolkit`
+Peer deps: `react ^18 || ^19`, `react-dom ^18 || ^19`, optional `react-hook-form ^7` (only needed for `Form`/`FormField`).
+
+## Setup
+
+```ts
+// Theme stylesheet — import once at the app entry.
+import '@overdoser/react-toolkit/theme.css';
+```
+
+Override CSS custom properties on `:root` to theme:
+```css
+:root {
+  --crk-color-primary: #3b82f6;
+  --crk-color-danger: #ef4444;
+  --crk-font-family: 'Inter', sans-serif;
+}
+```
+
+All components forward `className` and `style`. Most also accept a `classes` object to override internal element classNames (see `*Classes` types per component).
+
+## Components
+
+### Button
+Import: `import { Button } from '@overdoser/react-toolkit'`
+Element: `<button>` (forwards ref, accepts all native button props).
+
+Props:
+- `variant?: 'primary' | 'secondary' | 'danger' | 'ghost'` — default `'primary'`
+- `size?: 'sm' | 'md' | 'lg'` — default `'md'`
+- `loading?: boolean` — default `false`. When `true`, button is disabled and `aria-busy`.
+- `loadingStyle?: 'dots' | 'shimmer' | 'border'` — default `'dots'`. Only used when `loading` is true.
+- `fullWidth?: boolean` — default `false`
+- `classes?: Partial<ButtonClasses>` where `ButtonClasses = { root, content, shimmer, dots, dot }`
+
+Example:
+```tsx
+<Button variant="danger" size="lg" loading loadingStyle="shimmer" onClick={onDelete}>
+  Delete
+</Button>
+```
+
+### Link
+Import: `import { Link } from '@overdoser/react-toolkit'`
+Element: `<a>` (forwards ref, accepts all native anchor props).
+
+Props:
+- `variant?: 'default' | 'muted' | 'danger'` — default `'default'`
+- `external?: boolean` — default `false`. When `true`, sets `target="_blank" rel="noopener noreferrer"` and adds a visually-hidden " (opens in a new tab)" suffix.
+
+Example:
+```tsx
+<Link href="https://example.com" external>Docs</Link>
+```
+
+### Typography
+Import: `import { Typography } from '@overdoser/react-toolkit'`
+Element: dynamic — renders the tag named by `variant`.
+
+Props:
+- `variant?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'label'` — default `'p'`
+- `weight?: 'normal' | 'medium' | 'semibold' | 'bold'`
+- `color?: 'default' | 'muted' | 'primary' | 'danger' | 'success'` — note: native HTML `color` attr is intentionally omitted in favor of these presets.
+- `align?: 'left' | 'center' | 'right'`
+- `truncate?: boolean` — single-line ellipsis truncation.
+
+Example:
+```tsx
+<Typography variant="h2" weight="bold" color="primary">Heading</Typography>
+```
+
+### List / ListItem
+Import: `import { List, ListItem } from '@overdoser/react-toolkit'`
+Element: `<ul>` or `<ol>` depending on `variant`; `ListItem` renders `<li>`.
+
+`ListProps`:
+- `variant?: 'unordered' | 'ordered' | 'none'` — default `'unordered'`. `'none'` removes bullets.
+- `spacing?: 'sm' | 'md' | 'lg'` — default `'md'`
+
+`ListItemProps`: native `<li>` props only.
+
+Example:
+```tsx
+<List variant="ordered" spacing="lg">
+  <ListItem>First</ListItem>
+  <ListItem>Second</ListItem>
+</List>
+```
+
+### Table
+Import: `import { Table, useTableSort, type ColumnDef, type SortConfig } from '@overdoser/react-toolkit'`
+Generic: `Table<T extends Record<string, unknown>>`.
+
+Props:
+- `data: T[]`
+- `columns: ColumnDef<T>[]` — see `ColumnDef` below.
+- `sortConfig?: SortConfig[]` — controlled sort. Provide together with `onSort` for server-side sorting.
+- `onSort?: (config: SortConfig[]) => void` — when provided, table is in **controlled** mode: it does NOT sort `data` internally and does NOT slice for pagination (server is assumed to handle both).
+- `multiSort?: boolean` — default `true`. Ctrl/Cmd+click a sortable header to add/cycle a secondary sort.
+- `striped?: boolean` — default `false`
+- `hoverable?: boolean` — default `false`
+- `compact?: boolean` — default `false`
+- `rowKey?: keyof T & string` — column key to use as React key; falls back to row index.
+- `emptyMessage?: ReactNode` — default `'No data'`
+- `pagination?: PaginationConfig` — see below. When omitted, all rows render.
+- `classes?: Partial<TableClasses>` where `TableClasses = { wrapper, root, headerCell, row, cell, emptyCell, paginator, pageButton }`
+
+`ColumnDef<T>`:
+- `key: keyof T & string` — required.
+- `header: ReactNode` — required.
+- `sortable?: boolean`
+- `render?: (value: T[keyof T], row: T, index: number) => ReactNode`
+- `width?: string | number`
+- `align?: 'left' | 'center' | 'right'`
+
+`SortConfig`:
+- `key: string`
+- `direction: 'asc' | 'desc'`
+
+`PaginationConfig`:
+- `page: number` — 1-based.
+- `pageSize: number`
+- `totalRows?: number` — required for server-side mode; for client-side, defaults to `data.length`.
+- `pageSizeOptions?: number[]` — default `[10, 25, 50, 100]`. Pass `[n]` to hide the page-size select.
+- `onPageChange: (page: number, pageSize: number) => void`
+
+Sort cycle on a sortable header click: `none → asc → desc → none`.
+
+Client-side example:
+```tsx
+const columns: ColumnDef<User>[] = [
+  { key: 'name', header: 'Name', sortable: true },
+  { key: 'email', header: 'Email' },
+];
+<Table data={users} columns={columns} striped hoverable rowKey="id" />
+```
+
+With pagination (client-side):
+```tsx
+const [page, setPage] = useState(1);
+const [pageSize, setPageSize] = useState(10);
+<Table
+  data={users}
+  columns={columns}
+  pagination={{ page, pageSize, onPageChange: (p, s) => { setPage(p); setPageSize(s); } }}
+/>
+```
+
+Server-side (controlled) example:
+```tsx
+<Table
+  data={pageRows}
+  columns={columns}
+  sortConfig={sort}
+  onSort={setSort}
+  pagination={{ page, pageSize, totalRows, onPageChange }}
+/>
+```
+
+### `useTableSort` (hook)
+Import: `import { useTableSort } from '@overdoser/react-toolkit'`
+Signature: `useTableSort<T>(data: T[], initialSort?: SortConfig[])`
+Returns:
+- `sortedData: T[]`
+- `sortConfig: SortConfig[]`
+- `requestSort(key): void` — single-column; cycles asc → desc → cleared.
+- `requestMultiSort(key): void` — adds/toggles in multi-sort.
+- `resetSort(): void`
+
+Use this only if you want to manage sort state outside `<Table>`; `<Table>` already does this internally when `onSort` is not supplied.
+
+### Dropdown / DropdownItem
+Import: `import { Dropdown, DropdownItem } from '@overdoser/react-toolkit'`
+
+Two distinct usage modes — pick one:
+
+**Mode A — menu of arbitrary items:** pass `trigger` + `<DropdownItem>` children. The trigger button toggles a menu; clicking outside or pressing Escape closes it.
+
+**Mode B — selectable form input:** pass `options` + `value` + `onChange`. The `trigger` prop is ignored; the selected option's label appears in the trigger.
+
+`DropdownProps`:
+- `trigger?: ReactNode` — required for Mode A; ignored in Mode B.
+- `children?: ReactNode` — `<DropdownItem>` elements (Mode A).
+- `options?: { value: string; label: ReactNode; disabled?: boolean }[]` — switches to Mode B.
+- `value?: string` — Mode B selected value.
+- `onChange?: (value: string) => void` — Mode B select callback.
+- `placeholder?: ReactNode` — default `'Select...'` (Mode B).
+- `align?: 'left' | 'right'` — default `'left'`. Menu alignment relative to trigger.
+- `error?: boolean` — default `false`
+- `fullWidth?: boolean` — default `true`
+- `id?: string`
+- `onOpen?: () => void`
+- `onClose?: () => void`
+- `classes?: Partial<DropdownClasses>` where `DropdownClasses = { root, trigger, triggerLabel, chevron, menu, item }`
+
+`DropdownItemProps`: native `<button>` props plus `disabled?: boolean`.
+
+Mode A example:
+```tsx
+<Dropdown trigger={<>Menu ▾</>}>
+  <DropdownItem onClick={onEdit}>Edit</DropdownItem>
+  <DropdownItem onClick={onDelete}>Delete</DropdownItem>
+</Dropdown>
+```
+
+Mode B example:
+```tsx
+<Dropdown
+  options={[{ value: 'a', label: 'Option A' }, { value: 'b', label: 'Option B' }]}
+  value={value}
+  onChange={setValue}
+  placeholder="Pick one"
+/>
+```
+
+### Popover
+Import: `import { Popover } from '@overdoser/react-toolkit'`
+
+Props:
+- `trigger: ReactNode` — required. Wrapped in an internal `<button>`.
+- `content: ReactNode` — required. Rendered inside an `[role="dialog"]` panel when open.
+- `position?: 'top' | 'bottom' | 'left' | 'right'` — default `'bottom'`
+- `open?: boolean` — controlled.
+- `onOpenChange?: (open: boolean) => void`
+- `classes?: Partial<PopoverClasses>` where `PopoverClasses = { root, trigger, popover }`
+
+Closes on outside click and Escape. Auto-focuses the first focusable child of `content` (or the dialog itself).
+
+`children` is intentionally typed as `never` — pass via `content`.
+
+Example:
+```tsx
+<Popover trigger="Help" content={<p>Some help text</p>} position="right" />
+```
+
+### Modal
+Import: `import { Modal } from '@overdoser/react-toolkit'`
+
+Compound component: `Modal.Header`, `Modal.Body`, `Modal.Footer`. Renders into a portal at `document.body`.
+
+`ModalProps`:
+- `open: boolean` — required.
+- `onClose: () => void` — required.
+- `closeOnBackdrop?: boolean` — default `true`
+- `closeOnEscape?: boolean` — default `true`
+- `size?: 'sm' | 'md' | 'lg' | 'fullscreen'` — default `'md'`
+- `aria-label?: string` — use this OR `aria-labelledby`. If neither is provided, the `Modal.Header` content is auto-wired as the `aria-labelledby` target.
+- `aria-labelledby?: string`
+- `classes?: Partial<ModalClasses>` where `ModalClasses = { backdrop, modal, header, closeButton, body, footer }`
+
+Locks body scroll while open; traps focus; restores focus to previously-focused element on close.
+
+`Modal.Header` props:
+- `children: ReactNode` — required.
+- `onClose?: () => void` — when provided, renders an "×" close button.
+
+`Modal.Body`, `Modal.Footer`: just `children`, `className`, `style`.
+
+Example:
+```tsx
+<Modal open={open} onClose={() => setOpen(false)} size="md">
+  <Modal.Header onClose={() => setOpen(false)}>Confirm</Modal.Header>
+  <Modal.Body>Are you sure?</Modal.Body>
+  <Modal.Footer>
+    <Button variant="ghost" onClick={() => setOpen(false)}>Cancel</Button>
+    <Button variant="danger" onClick={confirm}>Delete</Button>
+  </Modal.Footer>
+</Modal>
+```
+
+### Form / FormField / FormRow
+Requires `react-hook-form` peer dependency.
+
+Imports: `import { Form, FormField, FormRow } from '@overdoser/react-toolkit'`
+
+`Form<T>` props:
+- `form: UseFormReturn<T>` — **the prop name is `form`, not `formMethods`**. Pass the result of `useForm()`.
+- `onSubmit: SubmitHandler<T>` — passed through `form.handleSubmit`.
+- `errors?: ReactNode[]` — top-of-form error list (rendered above children with `role="alert"`).
+
+`FormField` props:
+- `name: string` — required. Becomes the field id.
+- `label?: ReactNode`
+- `helperText?: ReactNode`
+- `required?: boolean` — adds a "*" indicator next to the label.
+- `rules?: Record<string, unknown>` — react-hook-form rules.
+- `children: ReactElement` — exactly one child input. The child does NOT need `value`/`onChange`/`name` — `FormField` injects them via `cloneElement`.
+- `classes?: Partial<FormFieldClasses>` where `FormFieldClasses = { field, label, error, helperText }`
+
+`FormField` injects bridges so these inputs work without manual wiring:
+- `Input`, `Textarea`, `Select`, `Dropdown` (Mode B), `Checkbox`, `Radio`/`RadioGroup`
+- For `Select` (multi/searchable) / `Dropdown` (Mode B): bridges `onChange` → `onValueChange`/`onValuesChange`.
+- For `Checkbox`: bridges `value` → `checked` when value is boolean.
+
+`FormRow` props: `children`, `className`, `style`. Wraps fields in a horizontal flex row.
+
+Example:
+```tsx
+import { useForm } from 'react-hook-form';
+import { Form, FormField, FormRow, Input, Button } from '@overdoser/react-toolkit';
+
+function LoginForm() {
+  const form = useForm<{ email: string; password: string }>();
+  return (
+    <Form form={form} onSubmit={(values) => console.log(values)}>
+      <FormField name="email" label="Email" required rules={{ required: 'Email is required' }}>
+        <Input type="email" />
+      </FormField>
+      <FormField name="password" label="Password" required rules={{ required: true, minLength: { value: 8, message: 'Min 8 chars' } }}>
+        <Input type="password" />
+      </FormField>
+      <Button type="submit">Sign in</Button>
+    </Form>
+  );
+}
+```
+
+### Input
+Import: `import { Input } from '@overdoser/react-toolkit'`
+Element: `<input>` (forwards ref). Native `prefix` attribute is omitted in favor of the prop below.
+
+Props:
+- `inputSize?: 'sm' | 'md' | 'lg'` — default `'md'`. **Note**: it is `inputSize`, NOT `size` — the native HTML `size` attribute is preserved separately.
+- `error?: boolean` — default `false`
+- `prefix?: ReactNode` — content rendered inside the input wrapper, before the field.
+- `suffix?: ReactNode` — same, after the field.
+- `classes?: Partial<InputClasses>` where `InputClasses = { root, wrapper, prefix, suffix }`
+
+Example:
+```tsx
+<Input type="email" inputSize="lg" prefix="@" placeholder="username" />
+```
+
+### Select
+Import: `import { Select } from '@overdoser/react-toolkit'`
+
+Three internal modes, picked automatically:
+1. **Native** (default) — wraps `<select>`.
+2. **Searchable** — set `searchable`. Custom dropdown with text filter.
+3. **Multi** — set `multiple`. Chip-based multi-select with text filter.
+
+Props:
+- `inputSize?: 'sm' | 'md' | 'lg'` — default `'md'`. (Same naming convention as `Input`.)
+- `error?: boolean`
+- `options?: { value: string; label: string; content?: ReactNode; disabled?: boolean }[]`
+- `placeholder?: string` — default `'Select...'` for searchable/multi.
+- `searchable?: boolean`
+- `searchPlaceholder?: string` — default `'Search...'`
+- `multiple?: boolean`
+- `value?: string | string[]` — string for single, string[] for multi.
+- `onChange?: (e: ChangeEvent<HTMLSelectElement>) => void` — fires for native + searchable (synthetic for searchable).
+- `onValueChange?: (value: string) => void` — single-mode value-only callback.
+- `onValuesChange?: (values: string[]) => void` — multi-mode callback.
+- `clearSearchOnSelect?: boolean` — default `true`. Multi-mode only.
+- `classes?: Partial<SelectClasses>` where `SelectClasses = { wrapper, root, arrow, search, menu, item, chip, chipRemove }`
+
+Searchable example:
+```tsx
+<Select
+  searchable
+  options={users.map(u => ({ value: u.id, label: u.name }))}
+  value={userId}
+  onValueChange={setUserId}
+/>
+```
+
+Multi example:
+```tsx
+<Select
+  multiple
+  options={tags}
+  value={selected}
+  onValuesChange={setSelected}
+  placeholder="Pick tags"
+/>
+```
+
+### Checkbox
+Import: `import { Checkbox } from '@overdoser/react-toolkit'`
+Element: `<input type="checkbox">` wrapped in a `<label>` (forwards ref to the input).
+
+Props (extends native input props):
+- `label?: ReactNode`
+- `indeterminate?: boolean` — default `false`. Sets the DOM `indeterminate` property; visually distinct.
+- `classes?: Partial<CheckboxClasses>` where `CheckboxClasses = { root, input, label }`
+
+Example:
+```tsx
+<Checkbox label="Remember me" checked={remember} onChange={(e) => setRemember(e.target.checked)} />
+```
+
+### Radio / RadioGroup
+Import: `import { Radio, RadioGroup } from '@overdoser/react-toolkit'`
+
+`RadioGroup` props:
+- `name: string` — required. Becomes the `name` attribute on every `Radio` inside.
+- `value?: string` — controlled selected value.
+- `onChange?: (value: string) => void`
+- `id?: string`
+- `aria-label?` / `aria-labelledby?`
+- `required?: boolean`
+
+`Radio` props (extends native input props minus `type`):
+- `value: string` — required.
+- `label?: ReactNode`
+- `classes?: Partial<RadioClasses>` where `RadioClasses = { root, input, label }`
+
+Inside a `RadioGroup`, individual `Radio` components do NOT need their own `name`/`checked`/`onChange` — the group provides them via context.
+
+Example:
+```tsx
+<RadioGroup name="plan" value={plan} onChange={setPlan} aria-label="Plan">
+  <Radio value="free" label="Free" />
+  <Radio value="pro" label="Pro" />
+</RadioGroup>
+```
+
+### Textarea
+Import: `import { Textarea } from '@overdoser/react-toolkit'`
+Element: `<textarea>` (forwards ref).
+
+Props:
+- `inputSize?: 'sm' | 'md' | 'lg'` — default `'md'`
+- `error?: boolean`
+- `resize?: 'none' | 'vertical' | 'horizontal' | 'both'` — default `'vertical'`. Ignored when `autoExpand` is true.
+- `autoExpand?: boolean` — default `true`. Auto-grows height to fit content; `resize` is suppressed.
+
+Example:
+```tsx
+<Textarea placeholder="Bio" rows={3} autoExpand />
+```
+
+## Hooks
+
+### useClickOutside
+Import: `import { useClickOutside } from '@overdoser/react-toolkit'`
+Signature: `useClickOutside(ref: RefObject<HTMLElement | null>, handler: () => void, enabled?: boolean): void`
+
+Calls `handler` on mousedown outside `ref.current`. Pass `enabled = false` to pause the listener (e.g., when a menu is closed) without unmounting.
+
+```tsx
+useClickOutside(ref, close, isOpen);
+```
+
+### useFocusTrap
+Import: `import { useFocusTrap } from '@overdoser/react-toolkit'`
+Signature: `useFocusTrap(ref: RefObject<HTMLElement | null>, active: boolean): void`
+
+Traps Tab / Shift+Tab inside `ref.current` while `active`. Focuses the first focusable child on activation; restores prior focus on deactivation.
+
+```tsx
+useFocusTrap(dialogRef, isOpen);
+```
+
+### useKeyboard
+Import: `import { useKeyboard } from '@overdoser/react-toolkit'`
+Signature: `useKeyboard(handlers: Record<string, (e: KeyboardEvent) => void>, active?: boolean): void`
+
+Binds global keydown listeners keyed by `KeyboardEvent.key`. `active` defaults to `true`.
+
+```tsx
+useKeyboard({ Escape: () => close(), Enter: () => confirm() }, isOpen);
+```
+
+## Common gotchas (LLM-relevant)
+
+1. **`Form` prop is `form`, not `formMethods`.** Older docs may show `formMethods`.
+2. **`Button` prop is `loadingStyle`, not `loadingType`.**
+3. **`Input` / `Select` / `Textarea` size prop is `inputSize`** — the native `size` attribute still works as itself.
+4. **`Typography` does not accept a free-form `color` string** — only the listed presets. The native `color` attr is omitted.
+5. **`Dropdown` is dual-mode.** If you pass `options`, the `trigger` prop is ignored and it behaves like a select. If you don't, you must pass `trigger` and `<DropdownItem>` children.
+6. **`Popover.children` is typed `never`** — content goes through the `content` prop.
+7. **`Modal` requires `Modal.Header`/`Body`/`Footer`** — don't put raw markup inside `<Modal>`.
+8. **`FormField` clones its single child** to inject `value`/`onChange`/`id`/`name`/`error`/aria. Never put more than one element inside, never wire those props on the child manually inside a form.
+9. **Server-side `Table`:** when `onSort` is provided, the table won't sort or paginate `data` itself — your server must.
+10. **Theme stylesheet is a separate import**: `'@overdoser/react-toolkit/theme.css'`. Without it, components render unstyled.

package/manifest.json

@@ -0,0 +1,362 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "@overdoser/react-toolkit",
+  "version": "0.0.2",
+  "description": "Machine-readable manifest of components, props, allowed values, and hooks. Generated for tooling and AI assistants.",
+  "themeCssImport": "@overdoser/react-toolkit/theme.css",
+  "peerDependencies": {
+    "required": ["react", "react-dom"],
+    "optional": ["react-hook-form"]
+  },
+  "components": {
+    "Button": {
+      "import": "import { Button } from '@overdoser/react-toolkit'",
+      "element": "button",
+      "extendsNativeProps": "button",
+      "forwardsRef": true,
+      "props": {
+        "variant": { "type": "enum", "values": ["primary", "secondary", "danger", "ghost"], "default": "primary" },
+        "size": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" },
+        "loading": { "type": "boolean", "default": false, "notes": "Disables the button and sets aria-busy." },
+        "loadingStyle": { "type": "enum", "values": ["dots", "shimmer", "border"], "default": "dots", "notes": "Only used when loading=true." },
+        "fullWidth": { "type": "boolean", "default": false },
+        "classes": { "type": "Partial<ButtonClasses>", "shape": ["root", "content", "shimmer", "dots", "dot"] }
+      }
+    },
+    "Link": {
+      "import": "import { Link } from '@overdoser/react-toolkit'",
+      "element": "a",
+      "extendsNativeProps": "a",
+      "forwardsRef": true,
+      "props": {
+        "variant": { "type": "enum", "values": ["default", "muted", "danger"], "default": "default" },
+        "external": { "type": "boolean", "default": false, "notes": "Adds target=_blank, rel=noopener noreferrer, and an sr-only 'opens in a new tab' suffix." }
+      }
+    },
+    "Typography": {
+      "import": "import { Typography } from '@overdoser/react-toolkit'",
+      "element": "dynamic (variant)",
+      "extendsNativeProps": "p (without color)",
+      "forwardsRef": true,
+      "props": {
+        "variant": { "type": "enum", "values": ["h1", "h2", "h3", "h4", "h5", "h6", "p", "span", "label"], "default": "p" },
+        "weight": { "type": "enum", "values": ["normal", "medium", "semibold", "bold"] },
+        "color": { "type": "enum", "values": ["default", "muted", "primary", "danger", "success"], "notes": "Native color attribute is omitted in favor of these presets." },
+        "align": { "type": "enum", "values": ["left", "center", "right"] },
+        "truncate": { "type": "boolean", "default": false }
+      }
+    },
+    "List": {
+      "import": "import { List } from '@overdoser/react-toolkit'",
+      "element": "ul or ol",
+      "extendsNativeProps": "ul",
+      "forwardsRef": true,
+      "props": {
+        "variant": { "type": "enum", "values": ["unordered", "ordered", "none"], "default": "unordered" },
+        "spacing": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" }
+      }
+    },
+    "ListItem": {
+      "import": "import { ListItem } from '@overdoser/react-toolkit'",
+      "element": "li",
+      "extendsNativeProps": "li",
+      "forwardsRef": true,
+      "props": {}
+    },
+    "Table": {
+      "import": "import { Table, type ColumnDef, type SortConfig } from '@overdoser/react-toolkit'",
+      "element": "table (inside wrapper div)",
+      "generic": "T extends Record<string, unknown>",
+      "props": {
+        "data": { "type": "T[]", "required": true },
+        "columns": { "type": "ColumnDef<T>[]", "required": true },
+        "sortConfig": { "type": "SortConfig[]", "notes": "Controlled sort. Provide with onSort for server-side mode." },
+        "onSort": { "type": "(config: SortConfig[]) => void", "notes": "When set, Table is fully controlled — does not sort or paginate data internally." },
+        "multiSort": { "type": "boolean", "default": true, "notes": "Ctrl/Cmd+click a sortable header to add a secondary sort." },
+        "striped": { "type": "boolean", "default": false },
+        "hoverable": { "type": "boolean", "default": false },
+        "compact": { "type": "boolean", "default": false },
+        "rowKey": { "type": "keyof T & string" },
+        "emptyMessage": { "type": "ReactNode", "default": "No data" },
+        "pagination": { "type": "PaginationConfig" },
+        "classes": { "type": "Partial<TableClasses>", "shape": ["wrapper", "root", "headerCell", "row", "cell", "emptyCell", "paginator", "pageButton"] }
+      },
+      "subTypes": {
+        "ColumnDef<T>": {
+          "key": { "type": "keyof T & string", "required": true },
+          "header": { "type": "ReactNode", "required": true },
+          "sortable": { "type": "boolean" },
+          "render": { "type": "(value, row, index) => ReactNode" },
+          "width": { "type": "string | number" },
+          "align": { "type": "enum", "values": ["left", "center", "right"] }
+        },
+        "SortConfig": {
+          "key": { "type": "string", "required": true },
+          "direction": { "type": "enum", "values": ["asc", "desc"], "required": true }
+        },
+        "PaginationConfig": {
+          "page": { "type": "number", "required": true, "notes": "1-based" },
+          "pageSize": { "type": "number", "required": true },
+          "totalRows": { "type": "number", "notes": "Required for server-side mode; defaults to data.length client-side." },
+          "pageSizeOptions": { "type": "number[]", "default": [10, 25, 50, 100] },
+          "onPageChange": { "type": "(page: number, pageSize: number) => void", "required": true }
+        }
+      },
+      "behavior": {
+        "sortCycle": "none → asc → desc → none",
+        "controlledMode": "Activated when onSort is provided. Table renders data as-is and does not slice for pagination."
+      }
+    },
+    "Dropdown": {
+      "import": "import { Dropdown, DropdownItem } from '@overdoser/react-toolkit'",
+      "element": "div",
+      "modes": {
+        "menu": "Pass `trigger` plus <DropdownItem> children.",
+        "select": "Pass `options` + `value` + `onChange`. Trigger label shows the selected option."
+      },
+      "props": {
+        "trigger": { "type": "ReactNode", "notes": "Required for menu mode; ignored when `options` is provided." },
+        "options": { "type": "{ value: string; label: ReactNode; disabled?: boolean }[]" },
+        "value": { "type": "string", "notes": "Select-mode controlled value." },
+        "onChange": { "type": "(value: string) => void", "notes": "Select-mode callback." },
+        "placeholder": { "type": "ReactNode", "default": "Select..." },
+        "align": { "type": "enum", "values": ["left", "right"], "default": "left" },
+        "error": { "type": "boolean", "default": false },
+        "fullWidth": { "type": "boolean", "default": true },
+        "id": { "type": "string" },
+        "onOpen": { "type": "() => void" },
+        "onClose": { "type": "() => void" },
+        "classes": { "type": "Partial<DropdownClasses>", "shape": ["root", "trigger", "triggerLabel", "chevron", "menu", "item"] }
+      }
+    },
+    "DropdownItem": {
+      "import": "import { DropdownItem } from '@overdoser/react-toolkit'",
+      "element": "button",
+      "extendsNativeProps": "button",
+      "forwardsRef": true,
+      "props": {
+        "disabled": { "type": "boolean", "default": false }
+      }
+    },
+    "Popover": {
+      "import": "import { Popover } from '@overdoser/react-toolkit'",
+      "element": "div",
+      "props": {
+        "trigger": { "type": "ReactNode", "required": true },
+        "content": { "type": "ReactNode", "required": true },
+        "position": { "type": "enum", "values": ["top", "bottom", "left", "right"], "default": "bottom" },
+        "open": { "type": "boolean", "notes": "Controlled mode." },
+        "onOpenChange": { "type": "(open: boolean) => void" },
+        "classes": { "type": "Partial<PopoverClasses>", "shape": ["root", "trigger", "popover"] }
+      },
+      "behavior": {
+        "closesOn": ["outside click", "Escape"],
+        "childrenTyped": "never — pass via `content` prop"
+      }
+    },
+    "Modal": {
+      "import": "import { Modal } from '@overdoser/react-toolkit'",
+      "element": "div (portal at document.body)",
+      "compoundComponents": ["Modal.Header", "Modal.Body", "Modal.Footer"],
+      "props": {
+        "open": { "type": "boolean", "required": true },
+        "onClose": { "type": "() => void", "required": true },
+        "closeOnBackdrop": { "type": "boolean", "default": true },
+        "closeOnEscape": { "type": "boolean", "default": true },
+        "size": { "type": "enum", "values": ["sm", "md", "lg", "fullscreen"], "default": "md" },
+        "aria-label": { "type": "string" },
+        "aria-labelledby": { "type": "string" },
+        "classes": { "type": "Partial<ModalClasses>", "shape": ["backdrop", "modal", "header", "closeButton", "body", "footer"] }
+      },
+      "subComponents": {
+        "Modal.Header": {
+          "props": {
+            "children": { "type": "ReactNode", "required": true },
+            "onClose": { "type": "() => void", "notes": "When set, renders an × close button." }
+          }
+        },
+        "Modal.Body": { "props": { "children": { "type": "ReactNode", "required": true } } },
+        "Modal.Footer": { "props": { "children": { "type": "ReactNode", "required": true } } }
+      },
+      "behavior": ["body scroll lock", "focus trap", "restores prior focus on close"]
+    },
+    "Form": {
+      "import": "import { Form } from '@overdoser/react-toolkit'",
+      "requires": "react-hook-form",
+      "generic": "T extends FieldValues",
+      "props": {
+        "form": { "type": "UseFormReturn<T>", "required": true, "notes": "The result of useForm(). NOTE: prop is `form`, not `formMethods`." },
+        "onSubmit": { "type": "SubmitHandler<T>", "required": true },
+        "errors": { "type": "ReactNode[]", "notes": "Top-of-form errors rendered above children with role=alert." }
+      }
+    },
+    "FormField": {
+      "import": "import { FormField } from '@overdoser/react-toolkit'",
+      "requires": "react-hook-form (must be inside <Form>)",
+      "props": {
+        "name": { "type": "string", "required": true },
+        "label": { "type": "ReactNode" },
+        "helperText": { "type": "ReactNode" },
+        "required": { "type": "boolean", "notes": "Adds a * indicator next to the label." },
+        "rules": { "type": "Record<string, unknown>", "notes": "Passed to react-hook-form's useController." },
+        "children": { "type": "ReactElement", "required": true, "notes": "Exactly one input element. FormField clones it to inject value/onChange/id/name/error/aria-*." },
+        "classes": { "type": "Partial<FormFieldClasses>", "shape": ["field", "label", "error", "helperText"] }
+      },
+      "behavior": {
+        "supportedChildren": ["Input", "Textarea", "Select", "Dropdown (select-mode)", "Checkbox", "Radio", "RadioGroup"],
+        "bridges": {
+          "onValueChange": "Bridged to react-hook-form onChange (Select single, Dropdown).",
+          "onValuesChange": "Bridged to react-hook-form onChange (Select multi).",
+          "checked": "Auto-set from value when value is boolean (Checkbox)."
+        }
+      }
+    },
+    "FormRow": {
+      "import": "import { FormRow } from '@overdoser/react-toolkit'",
+      "props": { "children": { "type": "ReactNode", "required": true } }
+    },
+    "Input": {
+      "import": "import { Input } from '@overdoser/react-toolkit'",
+      "element": "input",
+      "extendsNativeProps": "input (without prefix)",
+      "forwardsRef": true,
+      "props": {
+        "inputSize": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md", "notes": "Named `inputSize` so the native `size` attribute is preserved." },
+        "error": { "type": "boolean", "default": false },
+        "prefix": { "type": "ReactNode" },
+        "suffix": { "type": "ReactNode" },
+        "classes": { "type": "Partial<InputClasses>", "shape": ["root", "wrapper", "prefix", "suffix"] }
+      }
+    },
+    "Select": {
+      "import": "import { Select } from '@overdoser/react-toolkit'",
+      "element": "select (or custom for searchable/multi)",
+      "extendsNativeProps": "select (without value/onChange)",
+      "forwardsRef": true,
+      "modes": {
+        "native": "Default — wraps a native <select>.",
+        "searchable": "When `searchable=true`. Custom dropdown with text filter.",
+        "multi": "When `multiple=true`. Chip-based multi with text filter."
+      },
+      "props": {
+        "inputSize": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" },
+        "error": { "type": "boolean", "default": false },
+        "options": { "type": "{ value: string; label: string; content?: ReactNode; disabled?: boolean }[]" },
+        "placeholder": { "type": "string", "default": "Select..." },
+        "searchable": { "type": "boolean", "default": false },
+        "searchPlaceholder": { "type": "string", "default": "Search..." },
+        "multiple": { "type": "boolean", "default": false },
+        "value": { "type": "string | string[]", "notes": "string for single-mode, string[] for multi." },
+        "onChange": { "type": "(e: ChangeEvent<HTMLSelectElement>) => void", "notes": "Native + searchable (synthetic for searchable)." },
+        "onValueChange": { "type": "(value: string) => void", "notes": "Single-mode value-only callback." },
+        "onValuesChange": { "type": "(values: string[]) => void", "notes": "Multi-mode callback." },
+        "clearSearchOnSelect": { "type": "boolean", "default": true, "notes": "Multi-mode only." },
+        "classes": { "type": "Partial<SelectClasses>", "shape": ["wrapper", "root", "arrow", "search", "menu", "item", "chip", "chipRemove"] }
+      }
+    },
+    "Checkbox": {
+      "import": "import { Checkbox } from '@overdoser/react-toolkit'",
+      "element": "input[type=checkbox] inside label",
+      "extendsNativeProps": "input",
+      "forwardsRef": true,
+      "props": {
+        "label": { "type": "ReactNode" },
+        "indeterminate": { "type": "boolean", "default": false },
+        "classes": { "type": "Partial<CheckboxClasses>", "shape": ["root", "input", "label"] }
+      }
+    },
+    "Radio": {
+      "import": "import { Radio } from '@overdoser/react-toolkit'",
+      "element": "input[type=radio] inside label",
+      "extendsNativeProps": "input (without type)",
+      "forwardsRef": true,
+      "props": {
+        "value": { "type": "string", "required": true },
+        "label": { "type": "ReactNode" },
+        "classes": { "type": "Partial<RadioClasses>", "shape": ["root", "input", "label"] }
+      },
+      "behavior": "Inside a <RadioGroup>, name/checked/onChange come from context — do not pass them on Radio."
+    },
+    "RadioGroup": {
+      "import": "import { RadioGroup } from '@overdoser/react-toolkit'",
+      "element": "div[role=radiogroup]",
+      "props": {
+        "name": { "type": "string", "required": true },
+        "value": { "type": "string", "notes": "Controlled selected value." },
+        "onChange": { "type": "(value: string) => void" },
+        "id": { "type": "string" },
+        "aria-label": { "type": "string" },
+        "aria-labelledby": { "type": "string" },
+        "required": { "type": "boolean" }
+      }
+    },
+    "Textarea": {
+      "import": "import { Textarea } from '@overdoser/react-toolkit'",
+      "element": "textarea",
+      "extendsNativeProps": "textarea",
+      "forwardsRef": true,
+      "props": {
+        "inputSize": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" },
+        "error": { "type": "boolean", "default": false },
+        "resize": { "type": "enum", "values": ["none", "vertical", "horizontal", "both"], "default": "vertical", "notes": "Ignored when autoExpand=true." },
+        "autoExpand": { "type": "boolean", "default": true, "notes": "When true, auto-grows height to fit content." }
+      }
+    }
+  },
+  "hooks": {
+    "useClickOutside": {
+      "import": "import { useClickOutside } from '@overdoser/react-toolkit'",
+      "signature": "useClickOutside(ref: RefObject<HTMLElement | null>, handler: () => void, enabled?: boolean): void",
+      "params": {
+        "ref": "Element to monitor.",
+        "handler": "Called on mousedown outside the ref element.",
+        "enabled": "Pause the listener without unmounting (default true)."
+      }
+    },
+    "useFocusTrap": {
+      "import": "import { useFocusTrap } from '@overdoser/react-toolkit'",
+      "signature": "useFocusTrap(ref: RefObject<HTMLElement | null>, active: boolean): void",
+      "behavior": "Cycles Tab / Shift+Tab inside ref. Restores prior focus on deactivation."
+    },
+    "useKeyboard": {
+      "import": "import { useKeyboard } from '@overdoser/react-toolkit'",
+      "signature": "useKeyboard(handlers: Record<string, (e: KeyboardEvent) => void>, active?: boolean): void",
+      "params": {
+        "handlers": "Map keyed by KeyboardEvent.key (e.g., 'Escape', 'Enter').",
+        "active": "Default true. Pass false to disable without unmounting."
+      }
+    },
+    "useTableSort": {
+      "import": "import { useTableSort } from '@overdoser/react-toolkit'",
+      "signature": "useTableSort<T>(data: T[], initialSort?: SortConfig[])",
+      "returns": {
+        "sortedData": "T[]",
+        "sortConfig": "SortConfig[]",
+        "requestSort": "(key) => void — single-column; cycles asc → desc → cleared.",
+        "requestMultiSort": "(key) => void — adds/toggles a column in multi-sort.",
+        "resetSort": "() => void"
+      },
+      "notes": "Only needed if you want to manage sort state outside <Table>."
+    }
+  },
+  "gotchas": [
+    "Form prop is `form`, not `formMethods`.",
+    "Button prop is `loadingStyle`, not `loadingType`.",
+    "Input/Select/Textarea size prop is `inputSize`, not `size` — native size attribute is preserved.",
+    "Typography color is restricted to enum presets; native `color` HTML attribute is omitted.",
+    "Dropdown is dual-mode: `options` triggers select-mode and `trigger` is ignored.",
+    "Popover.children is typed `never` — content goes through the `content` prop.",
+    "Modal contents must be wrapped in Modal.Header/Body/Footer.",
+    "FormField clones a single child element to inject form props — don't wire value/onChange manually.",
+    "Server-side Table mode (onSort provided) means Table renders data verbatim — no internal sort or pagination slicing.",
+    "Theme stylesheet must be imported separately: '@overdoser/react-toolkit/theme.css'."
+  ],
+  "recipes": [
+    "recipes/login-form.tsx",
+    "recipes/paginated-table.tsx",
+    "recipes/server-side-table.tsx",
+    "recipes/confirm-modal.tsx",
+    "recipes/searchable-multi-select.tsx",
+    "recipes/dropdown-menu.tsx"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overdoser/react-toolkit",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "main": "./index.js",
   "module": "./index.mjs",

package/recipes/confirm-modal.tsx

@@ -0,0 +1,63 @@
+import { useState } from 'react';
+import { Modal, Button, Typography } from '@overdoser/react-toolkit';
+
+interface ConfirmModalProps {
+  open: boolean;
+  title: string;
+  message: React.ReactNode;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  destructive?: boolean;
+  onConfirm: () => void | Promise<void>;
+  onClose: () => void;
+}
+
+export function ConfirmModal({
+  open,
+  title,
+  message,
+  confirmLabel = 'Confirm',
+  cancelLabel = 'Cancel',
+  destructive = false,
+  onConfirm,
+  onClose,
+}: ConfirmModalProps) {
+  const [busy, setBusy] = useState(false);
+
+  const handleConfirm = async () => {
+    setBusy(true);
+    try {
+      await onConfirm();
+      onClose();
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <Modal open={open} onClose={onClose} size="sm" closeOnBackdrop={!busy} closeOnEscape={!busy}>
+      <Modal.Header onClose={busy ? undefined : onClose}>
+        <Typography variant="h3" weight="semibold">
+          {title}
+        </Typography>
+      </Modal.Header>
+      <Modal.Body>
+        <Typography variant="p" color="muted">
+          {message}
+        </Typography>
+      </Modal.Body>
+      <Modal.Footer>
+        <Button variant="ghost" onClick={onClose} disabled={busy}>
+          {cancelLabel}
+        </Button>
+        <Button
+          variant={destructive ? 'danger' : 'primary'}
+          onClick={handleConfirm}
+          loading={busy}
+        >
+          {confirmLabel}
+        </Button>
+      </Modal.Footer>
+    </Modal>
+  );
+}

package/recipes/dropdown-menu.tsx

@@ -0,0 +1,36 @@
+import { Dropdown, DropdownItem } from '@overdoser/react-toolkit';
+
+interface RowActionsProps {
+  rowId: string;
+  onEdit: (id: string) => void;
+  onArchive: (id: string) => void;
+  onDelete: (id: string) => void;
+  canDelete?: boolean;
+}
+
+export function RowActions({
+  rowId,
+  onEdit,
+  onArchive,
+  onDelete,
+  canDelete = true,
+}: RowActionsProps) {
+  return (
+    <Dropdown
+      align="right"
+      fullWidth={false}
+      trigger={
+        <span aria-label="Row actions">
+          {/* Replace with an icon component from your codebase */}
+          ⋯
+        </span>
+      }
+    >
+      <DropdownItem onClick={() => onEdit(rowId)}>Edit</DropdownItem>
+      <DropdownItem onClick={() => onArchive(rowId)}>Archive</DropdownItem>
+      <DropdownItem disabled={!canDelete} onClick={() => onDelete(rowId)}>
+        Delete
+      </DropdownItem>
+    </Dropdown>
+  );
+}

package/recipes/login-form.tsx

@@ -0,0 +1,51 @@
+import { useForm } from 'react-hook-form';
+import { Form, FormField, Input, Button } from '@overdoser/react-toolkit';
+
+interface LoginFields {
+  email: string;
+  password: string;
+}
+
+export function LoginForm({ onLogin }: { onLogin: (values: LoginFields) => Promise<void> }) {
+  const form = useForm<LoginFields>({
+    defaultValues: { email: '', password: '' },
+    mode: 'onTouched',
+  });
+
+  return (
+    <Form
+      form={form}
+      onSubmit={async (values) => {
+        await onLogin(values);
+      }}
+    >
+      <FormField
+        name="email"
+        label="Email"
+        required
+        rules={{
+          required: 'Email is required',
+          pattern: { value: /^\S+@\S+\.\S+$/, message: 'Enter a valid email' },
+        }}
+      >
+        <Input type="email" autoComplete="email" />
+      </FormField>
+
+      <FormField
+        name="password"
+        label="Password"
+        required
+        rules={{
+          required: 'Password is required',
+          minLength: { value: 8, message: 'Min 8 characters' },
+        }}
+      >
+        <Input type="password" autoComplete="current-password" />
+      </FormField>
+
+      <Button type="submit" variant="primary" loading={form.formState.isSubmitting} fullWidth>
+        Sign in
+      </Button>
+    </Form>
+  );
+}

package/recipes/paginated-table.tsx

@@ -0,0 +1,48 @@
+import { useState } from 'react';
+import { Table, type ColumnDef } from '@overdoser/react-toolkit';
+
+interface User extends Record<string, unknown> {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'member';
+  lastSeen: string;
+}
+
+const columns: ColumnDef<User>[] = [
+  { key: 'name', header: 'Name', sortable: true },
+  { key: 'email', header: 'Email', sortable: true },
+  { key: 'role', header: 'Role', sortable: true, width: 120 },
+  {
+    key: 'lastSeen',
+    header: 'Last seen',
+    sortable: true,
+    align: 'right',
+    width: 160,
+    render: (value) => new Date(value as string).toLocaleString(),
+  },
+];
+
+export function PaginatedTable({ users }: { users: User[] }) {
+  const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(10);
+
+  return (
+    <Table
+      data={users}
+      columns={columns}
+      rowKey="id"
+      striped
+      hoverable
+      pagination={{
+        page,
+        pageSize,
+        onPageChange: (nextPage, nextPageSize) => {
+          setPage(nextPage);
+          setPageSize(nextPageSize);
+        },
+      }}
+      emptyMessage="No users yet."
+    />
+  );
+}

package/recipes/searchable-multi-select.tsx

@@ -0,0 +1,42 @@
+import { useForm } from 'react-hook-form';
+import { Form, FormField, Select, Button } from '@overdoser/react-toolkit';
+
+interface TagFormValues {
+  tags: string[];
+}
+
+const TAG_OPTIONS = [
+  { value: 'react', label: 'React' },
+  { value: 'typescript', label: 'TypeScript' },
+  { value: 'rust', label: 'Rust' },
+  { value: 'go', label: 'Go' },
+  { value: 'python', label: 'Python' },
+  { value: 'css', label: 'CSS' },
+  { value: 'graphql', label: 'GraphQL' },
+];
+
+export function TagPicker({ onSave }: { onSave: (tags: string[]) => Promise<void> }) {
+  const form = useForm<TagFormValues>({ defaultValues: { tags: [] } });
+
+  return (
+    <Form
+      form={form}
+      onSubmit={async ({ tags }) => {
+        await onSave(tags);
+      }}
+    >
+      <FormField
+        name="tags"
+        label="Tags"
+        helperText="Pick all that apply"
+        rules={{ validate: (v: string[]) => v.length > 0 || 'Pick at least one tag' }}
+      >
+        <Select multiple options={TAG_OPTIONS} placeholder="Choose tags…" />
+      </FormField>
+
+      <Button type="submit" loading={form.formState.isSubmitting}>
+        Save tags
+      </Button>
+    </Form>
+  );
+}

package/recipes/server-side-table.tsx

@@ -0,0 +1,92 @@
+import { useEffect, useState } from 'react';
+import { Table, type ColumnDef, type SortConfig } from '@overdoser/react-toolkit';
+
+interface Order extends Record<string, unknown> {
+  id: string;
+  customer: string;
+  total: number;
+  status: 'pending' | 'paid' | 'refunded';
+  createdAt: string;
+}
+
+interface FetchArgs {
+  page: number;
+  pageSize: number;
+  sort: SortConfig[];
+}
+
+interface FetchResult {
+  rows: Order[];
+  totalRows: number;
+}
+
+const columns: ColumnDef<Order>[] = [
+  { key: 'id', header: 'Order #', sortable: true, width: 120 },
+  { key: 'customer', header: 'Customer', sortable: true },
+  {
+    key: 'total',
+    header: 'Total',
+    sortable: true,
+    align: 'right',
+    width: 120,
+    render: (value) =>
+      new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(value as number),
+  },
+  { key: 'status', header: 'Status', sortable: true, width: 120 },
+  {
+    key: 'createdAt',
+    header: 'Created',
+    sortable: true,
+    align: 'right',
+    width: 180,
+    render: (value) => new Date(value as string).toLocaleString(),
+  },
+];
+
+export function ServerSideOrdersTable({
+  fetchPage,
+}: {
+  fetchPage: (args: FetchArgs) => Promise<FetchResult>;
+}) {
+  const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(25);
+  const [sort, setSort] = useState<SortConfig[]>([{ key: 'createdAt', direction: 'desc' }]);
+  const [rows, setRows] = useState<Order[]>([]);
+  const [totalRows, setTotalRows] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    fetchPage({ page, pageSize, sort }).then((result) => {
+      if (!cancelled) {
+        setRows(result.rows);
+        setTotalRows(result.totalRows);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [page, pageSize, sort, fetchPage]);
+
+  return (
+    <Table
+      data={rows}
+      columns={columns}
+      rowKey="id"
+      sortConfig={sort}
+      onSort={(next) => {
+        setSort(next);
+        setPage(1);
+      }}
+      hoverable
+      pagination={{
+        page,
+        pageSize,
+        totalRows,
+        onPageChange: (nextPage, nextPageSize) => {
+          setPage(nextPage);
+          setPageSize(nextPageSize);
+        },
+      }}
+    />
+  );
+}