@overdoser/react-toolkit 0.0.1 → 0.0.3

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.