@overdoser/react-toolkit 0.0.2 → 0.0.4

package/components/inputs/Radio/Radio.d.ts

@@ -1,16 +1,31 @@
 import { ComponentPropsWithRef, ReactNode, CSSProperties } from 'react';
 export interface RadioGroupProps {
+    /** Shared `name` attribute applied to every `Radio` child via context. */
     name: string;
+    /** Controlled selected value. */
     value?: string;
+    /** Fires with the newly selected value. */
     onChange?: (value: string) => void;
     className?: string;
     style?: CSSProperties;
     children: ReactNode;
     id?: string;
+    /** Accessible label. Use this OR `aria-labelledby`. */
     'aria-label'?: string;
     'aria-labelledby'?: string;
+    /** Marks the group as required (`aria-required`). */
     required?: boolean;
 }
+/**
+ * Manages selection state and `name` attribute for a group of `<Radio>`s via context.
+ * Inside a `<RadioGroup>`, `Radio` does not need its own `name`/`checked`/`onChange`.
+ *
+ * @example
+ * <RadioGroup name="plan" value={plan} onChange={setPlan} aria-label="Plan">
+ *   <Radio value="free" label="Free" />
+ *   <Radio value="pro" label="Pro" />
+ * </RadioGroup>
+ */
 export declare const RadioGroup: {
     ({ name, value, onChange, className, style, children, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, required, }: RadioGroupProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
@@ -21,8 +36,15 @@ export interface RadioClasses {
     label: string;
 }
 export interface RadioProps extends Omit<ComponentPropsWithRef<'input'>, 'type'> {
+    /** Visible label rendered next to the radio. */
     label?: ReactNode;
+    /** Value of this option. Required (used to identify the radio in the group). */
     value: string;
+    /** Override class names on internal elements. */
     classes?: Partial<RadioClasses>;
 }
+/**
+ * A single radio option. Inside a `<RadioGroup>`, `name`/`checked`/`onChange`
+ * come from group context — do not pass them manually.
+ */
 export declare const Radio: import('react').ForwardRefExoticComponent<Omit<RadioProps, "ref"> & import('react').RefAttributes<HTMLInputElement>>;

package/components/inputs/Select/Select.d.ts

@@ -1,8 +1,12 @@
 import { ComponentPropsWithRef } from 'react';
 export interface SelectOption {
+    /** Value sent through `onValueChange` / form. */
     value: string;
+    /** Plain-text label (used for filter matching and the trigger text). */
     label: string;
+    /** Optional rich rendered content shown in the menu in place of `label`. */
     content?: React.ReactNode;
+    /** Non-interactive when true. */
     disabled?: boolean;
 }
 export interface SelectClasses {
@@ -16,18 +20,41 @@ export interface SelectClasses {
     chipRemove: string;
 }
 export interface SelectProps extends Omit<ComponentPropsWithRef<'select'>, 'onChange' | 'value'> {
+    /** Toolkit size scale (independent of the native `size` HTML attribute). @default 'md' */
     inputSize?: 'sm' | 'md' | 'lg';
+    /** Apply error styling. @default false */
     error?: boolean;
+    /** Options. When omitted in native mode, `children` is used instead. */
     options?: SelectOption[];
+    /** Placeholder shown when no value is selected. @default 'Select...' */
     placeholder?: string;
+    /** Override class names on internal elements. */
     classes?: Partial<SelectClasses>;
+    /** Replaces the native `<select>` with a filterable dropdown. @default false */
     searchable?: boolean;
+    /** Placeholder for the search input (searchable mode). @default 'Search...' */
     searchPlaceholder?: string;
+    /** Native + searchable mode change event (synthetic in searchable mode). */
     onChange?: (e: React.ChangeEvent<HTMLSelectElement>) => void;
+    /** Single-mode value-only callback. */
     onValueChange?: (value: string) => void;
+    /** `string` for single mode, `string[]` for multi mode. */
     value?: string | string[];
+    /** Enable multi-select with chip rendering and search. @default false */
     multiple?: boolean;
+    /** Multi-mode callback. */
     onValuesChange?: (values: string[]) => void;
+    /** Clear the search query after each toggle in multi mode. @default true */
     clearSearchOnSelect?: boolean;
 }
+/**
+ * Three internal modes, picked automatically:
+ * - **Native** (default): wraps `<select>`. Use `onChange` or pass options as `children`.
+ * - **Searchable**: set `searchable`. Custom dropdown with text filter.
+ * - **Multi**: set `multiple`. Chip-based multi-select with text filter.
+ *
+ * @example Native: <Select options={[{ value: 'a', label: 'A' }]} onValueChange={setValue} />
+ * @example Searchable: <Select searchable options={users} value={id} onValueChange={setId} />
+ * @example Multi: <Select multiple options={tags} value={selected} onValuesChange={setSelected} />
+ */
 export declare const Select: import('react').ForwardRefExoticComponent<Omit<SelectProps, "ref"> & import('react').RefAttributes<HTMLSelectElement>>;

package/components/inputs/Textarea/Textarea.d.ts

@@ -1,8 +1,17 @@
 import { ComponentPropsWithRef } from 'react';
 export interface TextareaProps extends ComponentPropsWithRef<'textarea'> {
+    /** Toolkit size scale. @default 'md' */
     inputSize?: 'sm' | 'md' | 'lg';
+    /** Apply error styling. @default false */
     error?: boolean;
+    /** User resize handle direction. Ignored when `autoExpand` is true. @default 'vertical' */
     resize?: 'none' | 'vertical' | 'horizontal' | 'both';
+    /** Auto-grow height to fit content. Suppresses `resize` while active. @default true */
     autoExpand?: boolean;
 }
+/**
+ * Themed textarea with optional auto-expanding height.
+ *
+ * @example <Textarea placeholder="Bio" rows={3} autoExpand />
+ */
 export declare const Textarea: import('react').ForwardRefExoticComponent<Omit<TextareaProps, "ref"> & import('react').RefAttributes<HTMLTextAreaElement>>;

package/index.d.ts

@@ -1,3 +1,17 @@
+/**
+ * @overdoser/react-toolkit
+ *
+ * Themeable React component library with SCSS modules.
+ *
+ * AI assistants: see `llms.txt` and `AGENTS.md` at the package root for an
+ * exhaustive component reference, recipes, and integration rules. A
+ * machine-readable spec is available in `manifest.json`.
+ *
+ * Setup: `import '@overdoser/react-toolkit/theme.css';` once at the app entry.
+ * Theme via `--crk-*` CSS custom properties on `:root`.
+ *
+ * @packageDocumentation
+ */
 export { Button } from './components/Button';
 export type { ButtonProps, ButtonClasses } from './components/Button';
 export { Link } from './components/Link';

package/llms.txt

@@ -0,0 +1,478 @@
+# @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>` — 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'`. Toolkit size scale; independent of the native HTML `size` attribute.
+- `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'`. Toolkit size scale.
+- `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);
+```
+
+## Conventions worth knowing
+
+1. **Inputs use `inputSize`** for the toolkit size scale. The native `size` HTML attribute is independent.
+2. **`Typography` `color`** accepts only the preset tokens; for arbitrary colors use `style` or `className`.
+3. **`Dropdown` has two modes:** with `options` + `value` + `onChange` it acts as a select input (the `trigger` prop is unused). Without `options`, pass `trigger` and `<DropdownItem>` children.
+4. **`Popover` content** goes through the `content` prop.
+5. **`Modal` content** lives in `Modal.Header`, `Modal.Body`, and `Modal.Footer` — these compound components own the spacing and aria wiring.
+6. **`FormField` clones its single child** to inject `value`/`onChange`/`id`/`name`/`error`/aria. Pass exactly one input element and let `FormField` wire it.
+7. **Server-side `Table`:** providing `onSort` puts the table in controlled mode — the consumer is responsible for sorting and slicing `data` server-side.
+8. **Theme stylesheet** is imported separately: `'@overdoser/react-toolkit/theme.css'`. Without it, components render unstyled.