@dreamtree-org/twreact-ui 2.0.4 → 2.0.5

package/mcp/catalog.snapshot.json

@@ -4844,7 +4844,13 @@
             "prop": "messages",
             "type": "`object`",
             "default": "",
-            "description": "Override announcement text: `instructions`, `grabbed`, `moved`, `dropped`, `cancelled`"
+            "description": "Override announcement text: `instructions`, `grabbed`, `moved`, `dropped`, `cancelled`; inside a `SortableGroup` also `groupInstructions`, `movedToList`, `droppedInList`, `refused`"
+          },
+          {
+            "prop": "id",
+            "type": "`string`",
+            "default": "",
+            "description": "DOM id of the list. Inside a [`SortableGroup`](SortableGroup.md) it is also the list's `listId`, and is required for the list to join the group"
           },
           {
             "prop": "className",
@@ -4861,6 +4867,48 @@
         ],
         "examples": "### Basic\n\n```jsx\nconst [tasks, setTasks] = useState(initialTasks);\n\n<Sortable\n  aria-label=\"Backlog\"\n  items={tasks}\n  onReorder={(next) => setTasks(next)}\n  getItemLabel={(t) => t.title}\n  renderItem={(t) => <div className=\"rounded-md border p-3\">{t.title}</div>}\n/>\n```\n\n### Drag handle + buttons\n\n```jsx\n<Sortable\n  handle\n  aria-label=\"Backlog\"\n  items={tasks}\n  onReorder={(next, { from, to }) => saveOrder(next)}\n  renderItem={(t, { handleProps, moveUp, moveDown }) => (\n    <div className=\"flex items-center gap-2\">\n      <span {...handleProps} aria-hidden=\"true\"><GripVertical /></span>\n      <span className=\"flex-1\">{t.title}</span>\n      <Button size=\"sm\" variant=\"ghost\" onClick={moveUp} aria-label={`Move ${t.title} up`}>↑</Button>\n      <Button size=\"sm\" variant=\"ghost\" onClick={moveDown} aria-label={`Move ${t.title} down`}>↓</Button>\n    </div>\n  )}\n/>\n```"
       },
+      {
+        "name": "SortableGroup",
+        "group": "utility",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "Connects several [`Sortable`](Sortable.md) lists so items can **move between lists** — by pointer drag, or by keyboard (pick an item up, then use the cross-axis arrow keys). A `canDrop` predicate is asked *before* a target is shown as droppable, so a move the domain would refuse never looks like it succeeded. Built for boards (drag a card between columns) and backlogs (drag a task into a sprint).",
+        "props": [
+          {
+            "prop": "onMove",
+            "type": "`function`",
+            "default": "",
+            "description": "`({ item, from: { listId, index }, to: { listId, index } }) => void`, called once when an item is dropped in another list (and `canDrop` allowed it). Remove the item from `from.listId` and insert it into `to.listId` at `to.index`."
+          },
+          {
+            "prop": "canDrop",
+            "type": "`function`",
+            "default": "",
+            "description": "`(item, target: { listId, index }, from: { listId, index }) => boolean`. Asked whenever the carried item targets another list. Return `true` to allow; a refused target is marked and announced as not droppable and dropping there does nothing. Omit to allow every list. Not consulted for reordering inside one list."
+          },
+          {
+            "prop": "children",
+            "type": "`ReactNode`",
+            "default": "",
+            "description": "Your layout, containing the `<Sortable id=\"…\">` lists (at any depth)."
+          },
+          {
+            "prop": "className",
+            "type": "`string`",
+            "default": "",
+            "description": "Classes for the wrapper `<div>` (merged with `cn`), e.g. `\"grid grid-cols-3 gap-4\"`."
+          },
+          {
+            "prop": "...rest",
+            "type": "`HTMLAttributes<HTMLDivElement>`",
+            "default": "",
+            "description": "Forwarded to the wrapper `<div>`; `ref` points at it."
+          }
+        ],
+        "examples": "### Board\n\n```jsx\nconst [board, setBoard] = useState({ todo: [...], review: [...], done: [...] });\n\nfunction moveCard(board, { from, to }) {\n  const next = { ...board, [from.listId]: board[from.listId].slice() };\n  const [card] = next[from.listId].splice(from.index, 1);\n  if (to.listId !== from.listId) next[to.listId] = board[to.listId].slice();\n  next[to.listId].splice(to.index, 0, card);\n  return next;\n}\n\n<SortableGroup\n  className=\"grid grid-cols-3 gap-4\"\n  onMove={(move) => setBoard((b) => moveCard(b, move))}\n  // Server-computed transitions: \"done\" only accepts cards from \"review\".\n  canDrop={(card, target, from) => target.listId !== 'done' || from.listId === 'review'}\n>\n  {[['todo', 'To do'], ['review', 'Review'], ['done', 'Done']].map(([id, name]) => (\n    <section key={id}>\n      <h3>{name}</h3>\n      <Sortable\n        id={id}\n        aria-label={name}\n        className=\"min-h-24\"\n        items={board[id]}\n        onReorder={(next) => setBoard((b) => ({ ...b, [id]: next }))}\n        getItemLabel={(t) => t.title}\n        renderItem={(t) => <div className=\"rounded-md border border-line bg-surface p-3\">{t.title}</div>}\n      />\n    </section>\n  ))}\n</SortableGroup>\n```\n\nGive the lists a minimum size (`min-h-24` above) so an empty list still has an area to drop on.\n\n### Confirm before committing\n\n`onMove` fires once, on drop, so a transition that needs extra input can open a prompt first and only update state on confirm — the card never jumps to the new column and back.\n\n```jsx\n<SortableGroup onMove={(move) => (needsComment(move) ? openCommentPrompt(move) : apply(move))} />\n```"
+      },
       {
         "name": "PullToRefresh",
         "group": "utility",
@@ -6167,6 +6215,176 @@
         ],
         "examples": "### In a stat card\n\n```jsx\nconst weekly = [{ week: 'W1', signups: 12 }, { week: 'W2', signups: 18 }, { week: 'W3', signups: 15 }, { week: 'W4', signups: 27 }];\n\n<Sparkline data={weekly} index=\"week\" category=\"signups\" color=\"success\" title=\"Signups, last 4 weeks\" />\n```\n\n### Area with tooltip\n\n```jsx\n<Sparkline data={weekly} index=\"week\" category=\"signups\" type=\"area\" showTooltip height={56} />\n```"
       },
+      {
+        "name": "ScatterChart",
+        "group": "charts",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/charts",
+        "peerDependencies": [
+          "recharts"
+        ],
+        "hasDoc": true,
+        "description": "Themed, responsive scatter chart: two continuous (numeric) axes, one point per row, optionally grouped into coloured series. Same data-first API, token colours, accessible data-table fallback, empty state and reduced-motion support as the other charts. Wraps `recharts` (optional peer, `/charts` entry point).",
+        "props": [
+          {
+            "prop": "data",
+            "type": "`object[]`",
+            "default": "",
+            "description": "**Required.** Rows to plot, one point per row. Rows whose `x` or `y` is not a finite number are skipped; if none are left, `emptyState` renders."
+          },
+          {
+            "prop": "x",
+            "type": "`string`",
+            "default": "",
+            "description": "**Required.** Key of the numeric x value in each row, e.g. `\"health\"`."
+          },
+          {
+            "prop": "y",
+            "type": "`string`",
+            "default": "",
+            "description": "**Required.** Key of the numeric y value in each row, e.g. `\"variance\"`."
+          },
+          {
+            "prop": "index",
+            "type": "`string`",
+            "default": "",
+            "description": "Key of the entity name per point (e.g. `\"project\"`). Used as the tooltip heading and the hidden table's row header."
+          },
+          {
+            "prop": "category",
+            "type": "`string`",
+            "default": "",
+            "description": "Key that groups points into series: one colour and legend entry per distinct value, in first-seen order. Without it all points are one series."
+          },
+          {
+            "prop": "colors",
+            "type": "`ChartColor[]`",
+            "default": "primary, success, warning, error, info, secondary, gray",
+            "description": "Series colours by position (cycled), matched to the `category` values in first-seen order. A token (`\"primary\"`, `\"success-600\"`) resolves to the `--dt-*` CSS variable and follows the theme and dark mode; any other string is used as a CSS colour."
+          },
+          {
+            "prop": "valueFormatter",
+            "type": "`(value: number) => string`",
+            "default": "toLocaleString",
+            "description": "Formats y values on the axis, in the tooltip and in the hidden data table."
+          },
+          {
+            "prop": "xAxisFormatter",
+            "type": "`(value: number) => string`",
+            "default": "toLocaleString",
+            "description": "Formats x values on the axis, in the tooltip and in the hidden data table."
+          },
+          {
+            "prop": "xAxisLabel",
+            "type": "`string`",
+            "default": "",
+            "description": "Axis title under the x-axis. Also names the x column in the tooltip and table (falls back to `x`)."
+          },
+          {
+            "prop": "yAxisLabel",
+            "type": "`string`",
+            "default": "",
+            "description": "Axis title beside the y-axis. Also names the y column in the tooltip and table (falls back to `y`)."
+          },
+          {
+            "prop": "showLegend",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "Legend of the `category` series below the chart (real DOM text). Not drawn without `category`."
+          },
+          {
+            "prop": "showXAxis",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "Show the x-axis."
+          },
+          {
+            "prop": "showYAxis",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "Show the y-axis."
+          },
+          {
+            "prop": "showGrid",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "Dashed grid lines (`--dt-line`)."
+          },
+          {
+            "prop": "yAxisWidth",
+            "type": "`number`",
+            "default": "48 (36 when the chart is narrower than 400 px)",
+            "description": "Width reserved for y-axis labels, px. When set, it is used at every width."
+          },
+          {
+            "prop": "height",
+            "type": "`number` or `string`",
+            "default": "300",
+            "description": "Chart height (px number or any CSS length). The width is always 100% of the parent (responsive)."
+          },
+          {
+            "prop": "aspectRatio",
+            "type": "`number`",
+            "default": "",
+            "description": "Width / height ratio, e.g. `16 / 9`. When provided it replaces `height`; the empty state uses it too."
+          },
+          {
+            "prop": "title",
+            "type": "`string`",
+            "default": "",
+            "description": "Accessible name: `aria-label` of the `role=\"img\"` region and caption of the hidden table. Falls back to `aria-label`, then `\"Scatter chart\"`."
+          },
+          {
+            "prop": "description",
+            "type": "`string`",
+            "default": "",
+            "description": "Longer text alternative (the takeaway), linked with `aria-describedby`."
+          },
+          {
+            "prop": "emptyState",
+            "type": "`ReactNode`",
+            "default": "\"No data to display\"",
+            "description": "Shown (as `role=\"status\"`) instead of the chart when there is no plottable row."
+          },
+          {
+            "prop": "accessibleTable",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "Repeat the points in a visually-hidden `<table>` (columns: `index`, `category`, x, y — the first two only when set)."
+          },
+          {
+            "prop": "animate",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "Animate on mount / data change. Always off when the user prefers reduced motion."
+          },
+          {
+            "prop": "showTooltip",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "Tooltip on hover (themed, dark-mode aware): the `index` value (or series) as the heading, then the series and the formatted x and y."
+          },
+          {
+            "prop": "className",
+            "type": "`string`",
+            "default": "",
+            "description": "Extra classes for the root `<div>` (merged with `cn`)."
+          },
+          {
+            "prop": "ref",
+            "type": "`Ref<HTMLDivElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<div>`."
+          },
+          {
+            "prop": "...rest",
+            "type": "`HTMLAttributes<HTMLDivElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<div>` (`id`, `data-*`, `aria-*`, handlers)."
+          }
+        ],
+        "examples": "### Basic\n\n```jsx\nconst projects = [\n  { project: 'Atlas', health: 82, variance: -4 },\n  { project: 'Borealis', health: 45, variance: 18 },\n  { project: 'Cygnus', health: 67, variance: 6 },\n];\n\n<ScatterChart\n  data={projects}\n  x=\"health\"\n  y=\"variance\"\n  index=\"project\"\n  xAxisLabel=\"Health score\"\n  yAxisLabel=\"Budget variance\"\n  valueFormatter={(v) => `${v}%`}\n  title=\"Project health vs budget variance\"\n  description=\"Projects with lower health scores are running over budget.\"\n/>\n```\n\n### Grouped series\n\n```jsx\n<ScatterChart\n  data={projects}\n  x=\"health\"\n  y=\"variance\"\n  index=\"project\"\n  category=\"department\"\n  colors={['primary', 'warning', 'success']}\n  title=\"Project health by department\"\n/>\n```"
+      },
       {
         "name": "RichTextEditor",
         "group": "rich-text",
@@ -6490,7 +6708,7 @@
       "rich-text"
     ],
     "counts": {
-      "components": 67,
+      "components": 69,
       "hooks": 4,
       "utils": 3,
       "store": 1
@@ -6543,6 +6761,7 @@
     "Rate": "# Rate\n\nStar (or custom icon) rating input/display. Controlled via `value` or uncontrolled via `defaultValue`. Supports hover preview and optional read-only. Stars use token classes (`text-warning-400` active, `text-gray-200` inactive); the inline `activeColor` / `inactiveColor` overrides were removed in 2.0.0 ([migration](MIGRATION-2.0.md#rate-activecolor-and-inactivecolor)).\n\n## Import\n\n```jsx\nimport { Rate } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `count` | `number` | `5` | Number of stars. |\n| `value` | `number` | — | Controlled value (0 to count). |\n| `defaultValue` | `number` | `0` | Uncontrolled initial value. |\n| `readOnly` | `boolean` | `false` | Read-only (no onChange). |\n| `icon` | `ReactNode` | `<StarOutline />` | Icon for inactive star. |\n| `toggledIcon` | `ReactNode` | `<StarFilled />` | Icon for active star. |\n| `size` | `number` | `20` | Icon size in px. |\n| `onChange` | `(value: number) => void` | — | Called when value changes. |\n| `onClick` | `(value: number) => void` | — | Called on star click. |\n| `text` | `ReactNode` | — | Optional text (e.g. label) next to stars. |\n| `className` | `string` | `\"\"` | Wrapper CSS classes. |\n| `id` | `string` | — | Wrapper id. |\n| `name` | `string` | — | Form field name. |\n\n## Accessibility & interaction\n\n- Rendered as a `radiogroup` of star `radio`s. Only the star equal to the\n  current value has `aria-checked=\"true\"`.\n- **Roving tabindex:** the group is one tab stop — the selected star, or the\n  first star when the value is `0`.\n- **Keyboard:** `ArrowRight` / `ArrowUp` and `ArrowLeft` / `ArrowDown` move\n  focus to the next / previous star **and** select it (calling `onChange`,\n  clamped to 1…`count`); `Home` / `End` jump to the first / last star;\n  `Enter` / `Space` commit the focused star (calling `onChange` and `onClick`).\n- **Hover preview** is shown for mouse/pen pointers only and clears on pointer\n  leave; touch taps never leave a stuck preview.\n- **Touch drag:** on touch screens, slide a finger across the stars — the\n  highlighted value follows the finger (pointer capture keeps tracking it\n  even off the stars; sliding past either end clamps to 1 or `count`) and is\n  committed once, on release (`onChange` and `onClick` fire then, and focus\n  moves to that star). A tap without sliding still selects via click.\n  `pointercancel` drops the preview. The group uses `touch-action: pan-y`,\n  so vertical page scrolling still works over it.\n- Each star grows to a 44×44 px hit area on coarse (touch) pointers.\n- `readOnly` removes the stars from the tab order.\n\n## Example\n\n```jsx\nconst [rating, setRating] = useState(0);\n<Rate value={rating} onChange={setRating} count={5} />\n<Rate defaultValue={3} readOnly />\n```\n\n[← Component overview](README.md)\n",
     "RichTextEditor": "# RichTextEditor\n\nWYSIWYG rich-text field built on Tiptap (StarterKit): bold, italic, strike, inline code, headings, lists, quotes, links and undo/redo, with a keyboard-accessible toolbar and the same `label` / `error` / `helperText` wiring as `Input`. Lives on the `/rich-text` entry point so Tiptap is an optional peer dependency.\n\n## Install\n\n```bash\nnpm install @tiptap/react @tiptap/pm @tiptap/starter-kit\n# TypeScript + React 18: keep the React type packages on your React major\nnpm install -D @types/react@18 @types/react-dom@18\n```\n\n## Import\n\n```jsx\nimport { RichTextEditor } from '@dreamtree-org/twreact-ui/rich-text';\n```\n\nNever import it from the root `@dreamtree-org/twreact-ui` — it is not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `string` or `JSONContent` | — | Controlled content: an HTML string (or Tiptap JSON). An external change replaces the content without calling `onChange`. |\n| `defaultValue` | `string` or `JSONContent` | — | Uncontrolled initial content. |\n| `onChange` | `(value, editor) => void` | — | Called on every edit with HTML (or Tiptap JSON when `outputFormat=\"json\"`) and the Tiptap editor. |\n| `outputFormat` | `\"html\"` or `\"json\"` | `\"html\"` | What `onChange` receives. |\n| `label` | `ReactNode` | — | Visible label; names the editor through `aria-labelledby`. Clicking it focuses the editor. |\n| `error` | `ReactNode` | — | Error message: red border, `aria-invalid`, icon + text linked with `aria-describedby`. |\n| `helperText` | `ReactNode` | — | Hint below the field, linked with `aria-describedby` (shown together with `error`). |\n| `placeholder` | `string` | — | Shown while the document is empty; also `aria-placeholder`, and the accessible name when there is no `label` or `aria-label`. |\n| `required` | `boolean` | `false` | Visual `*` and `aria-required`. |\n| `disabled` | `boolean` | `false` | Not editable, dimmed, toolbar buttons disabled, `aria-disabled`. |\n| `readOnly` | `boolean` | `false` | Shows the formatted content, not editable, toolbar hidden, `aria-readonly`. |\n| `toolbar` | `RichTextToolbarItem[]` or `false` | `bold, italic, strike, code, heading2, heading3, bulletList, orderedList, blockquote, link, undo, redo` | Toolbar buttons in order (also available: `heading1`, `codeBlock`), or `false` for none. |\n| `toolbarLabel` | `string` | `\"Formatting\"` | Accessible name of the `role=\"toolbar\"`. |\n| `stickyToolbar` | `boolean`, `number` or `string` | `false` | Keep the toolbar pinned (`sticky`, `z-sticky`) to the top of the scrolling page while long content scrolls. `true` sticks at the top; a number (px) or CSS length sets the offset, e.g. `\"3.5rem\"` below `AppShell`'s sticky top bar. The frame switches from `overflow-hidden` to `overflow-clip` so the toolbar can stick. |\n| `minHeight` | `number` or `string` | `120` | Minimum height of the editable area (px or CSS length). |\n| `maxHeight` | `number` or `string` | — | Height after which the editable area scrolls. |\n| `autoFocus` | `boolean` | `false` | Focus the editor on mount. |\n| `onFocus` | `(event) => void` | — | Editor focus. |\n| `onBlur` | `(event) => void` | — | Editor blur. |\n| `extensions` | `AnyExtension[]` | — | Extra Tiptap extensions, appended after StarterKit. |\n| `editorClassName` | `string` | — | Extra classes for the editable (ProseMirror) element. |\n| `id` | `string` | — | Id of the editable element (auto-generated otherwise). |\n| `className` | `string` | — | Extra classes for the root `<div>` (merged with `cn`). |\n| `ref` | `Ref<RichTextEditorHandle>` | — | Imperative handle: `editor`, `element`, `focus()`, `clear()`, `getHTML()`, `getJSON()`, `setContent(content)`. |\n| ...rest | `HTMLAttributes<HTMLDivElement>` | — | Forwarded to the root `<div>`. |\n\nWorks controlled (`value` + `onChange`) or uncontrolled (`defaultValue`, read with the ref). Controlled is recommended for forms.\n\nThe editor renders on the client after mount (`immediatelyRender: false`), so it is safe in Next.js / SSR; the label, toolbar and placeholder render on the server.\n\n### Security: sanitize the HTML on the server\n\n`onChange` returns whatever HTML the editor holds, and a user can send any HTML to your API without using the editor at all. **Always sanitize rich-text HTML on the server before you store or render it** (for example with DOMPurify / `sanitize-html` and an allow-list of the tags and attributes above). This library ships no sanitizer, and its components never render raw HTML. The link form only accepts `http(s):`, `mailto:`, `tel:`, relative and `#` URLs, but that is a UX guard, not a security boundary.\n\n## Examples\n\n### Controlled\n\n```jsx\nconst [body, setBody] = useState('<p>Hello</p>');\n\n<RichTextEditor\n  label=\"Description\"\n  placeholder=\"Describe the task…\"\n  helperText=\"Markdown shortcuts work: **bold**, # heading, - list.\"\n  value={body}\n  onChange={setBody}\n  maxHeight={320}\n/>\n```\n\n### Compact toolbar with validation\n\n```jsx\n<RichTextEditor label=\"Comment\" required toolbar={['bold', 'italic', 'link']} minHeight={80} error={errors.comment} />\n```\n\n### Uncontrolled + ref\n\n```jsx\nconst editorRef = useRef(null);\n\n<RichTextEditor label=\"Notes\" defaultValue=\"<p>Draft</p>\" ref={editorRef} />\n<Button onClick={() => save(editorRef.current.getHTML())}>Save</Button>\n```\n\n### Sticky toolbar for long documents\n\n```jsx\n// Inside AppShell: stick below its 56px top bar.\n<RichTextEditor label=\"Article\" stickyToolbar=\"3.5rem\" value={body} onChange={setBody} />\n```\n\n### JSON output\n\n```jsx\n<RichTextEditor label=\"Body\" outputFormat=\"json\" onChange={(doc) => setDoc(doc)} />\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Field | The editable element is `role=\"textbox\"` with `aria-multiline=\"true\"`, named by `label` (`aria-labelledby`), else `aria-label`, else `placeholder` |\n| Description | `error` and `helperText` ids (plus any `aria-describedby` you pass) are joined into `aria-describedby`; `aria-invalid`, `aria-required`, `aria-readonly`, `aria-disabled` reflect the props |\n| Toolbar | `role=\"toolbar\"` with `aria-label` and `aria-controls`; one tab stop with roving focus (Left / Right arrows, Home, End); every control is a real `<button>` with `aria-label`, `title` and `aria-keyshortcuts` |\n| Touch | Toolbar buttons are 32px on desktop and grow to 44px on coarse pointers. They cancel `pointerdown` (and `mousedown`), so tapping one keeps the editor selection on iOS and the format applies to the selected text |\n| Toggle state | Mark / block buttons expose `aria-pressed`; Undo / Redo expose `aria-disabled` when nothing can be undone / redone |\n| Keyboard shortcuts | StarterKit defaults: Mod+B, Mod+I, Mod+Shift+S, Mod+E, Mod+Alt+1..3, Mod+Shift+7 / 8, Mod+Shift+B, Mod+Z, Mod+Shift+Z, plus Markdown input rules |\n| Links | The link button opens an inline URL field (Enter applies, Escape cancels and returns focus to the editor); invalid schemes show a `role=\"alert\"` message |\n| Error | Paired with an icon and text, not colour alone |\n| Focus ring | `focus-within:ring-2 ring-primary-500` on the editing area (error ring when invalid); toolbar buttons use `focus-visible:ring-2` |\n| Dark mode | Surface, border and content (headings, quotes, code, links) use `dark:` variants; the toolbar uses the role tokens (`bg-background`, `border-line`, `text-muted`, `text-foreground`) |\n\n[← Component overview](README.md)\n",
     "RoundedTag": "# RoundedTag\n\nTag/chip with optional avatar (image or initials) and optional remove button. Used for labels, selected items, or filters.\n\n## Import\n\n```jsx\nimport { RoundedTag } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `label` | `string` | — | Main label text. |\n| `avatarSrc` | `string` | `null` | Image URL for avatar. |\n| `avatarAlt` | `string` | `\"avatar\"` | Alt for avatar image. |\n| `initials` | `string` | `\"\"` | Initials when no image (e.g. \"AB\"). |\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `\"md\"` | Size. |\n| `onRemove` | `(e?) => void` | `null` | If provided, shows remove button and calls on click. The button is labelled `Remove <label>` (plain `Remove` when `label` is not a string). |\n| `onClick` | `(e?) => void` | `null` | Click handler for the tag. When set, the tag becomes `role=\"button\"`, joins the tab order (`tabIndex=0`), activates on Enter/Space, and shows a focus-visible ring. |\n| `className` | `string` | `\"\"` | Wrapper CSS classes. |\n| `closeClass` | `string` | `\"\"` | Remove button CSS classes. |\n| `ariaLabel` | `string` | — | Optional accessibility label. No default — when omitted, the visible `label` text is the accessible name (previously defaulted to `\"tag\"`, which hid the label from screen readers). |\n| `avatarPosition` | `\"left\"` \\| `\"right\"` | `\"left\"` | Avatar position. |\n| `avatarClassname` | `string` | `\"\"` | Avatar wrapper classes. |\n| `initialClassname` | `string` | `\"\"` | Initials span classes. |\n\nThe tag, its avatar and the remove button have dark-mode tones. A clickable tag shrinks slightly while pressed (off under `prefers-reduced-motion`).\n\n## Example\n\n```jsx\n<RoundedTag label=\"React\" />\n<RoundedTag label=\"John\" initials=\"JD\" onRemove={() => {}} />\n<RoundedTag label=\"With image\" avatarSrc=\"/user.jpg\" size=\"lg\" />\n```\n\n[← Component overview](README.md)\n",
+    "ScatterChart": "# ScatterChart\n\nThemed, responsive scatter chart: two continuous (numeric) axes, one point per row, optionally grouped into coloured series. Same data-first API, token colours, accessible data-table fallback, empty state and reduced-motion support as the other charts. Wraps `recharts` (optional peer, `/charts` entry point).\n\n## Install\n\nCharts live on a separate entry point so apps that don't use them never install or bundle `recharts`:\n\n```bash\nnpm install recharts\n# React 18 apps: also pin react-is to your React major (recharts resolves it as a peer)\nnpm install react-is@18\n```\n\n## Import\n\n```jsx\nimport { ScatterChart } from '@dreamtree-org/twreact-ui/charts';\n```\n\nNever import charts from the root `@dreamtree-org/twreact-ui` — they are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `data` | `object[]` | — | **Required.** Rows to plot, one point per row. Rows whose `x` or `y` is not a finite number are skipped; if none are left, `emptyState` renders. |\n| `x` | `string` | — | **Required.** Key of the numeric x value in each row, e.g. `\"health\"`. |\n| `y` | `string` | — | **Required.** Key of the numeric y value in each row, e.g. `\"variance\"`. |\n| `index` | `string` | — | Key of the entity name per point (e.g. `\"project\"`). Used as the tooltip heading and the hidden table's row header. |\n| `category` | `string` | — | Key that groups points into series: one colour and legend entry per distinct value, in first-seen order. Without it all points are one series. |\n| `colors` | `ChartColor[]` | `primary, success, warning, error, info, secondary, gray` | Series colours by position (cycled), matched to the `category` values in first-seen order. A token (`\"primary\"`, `\"success-600\"`) resolves to the `--dt-*` CSS variable and follows the theme and dark mode; any other string is used as a CSS colour. |\n| `valueFormatter` | `(value: number) => string` | `toLocaleString` | Formats y values on the axis, in the tooltip and in the hidden data table. |\n| `xAxisFormatter` | `(value: number) => string` | `toLocaleString` | Formats x values on the axis, in the tooltip and in the hidden data table. |\n| `xAxisLabel` | `string` | — | Axis title under the x-axis. Also names the x column in the tooltip and table (falls back to `x`). |\n| `yAxisLabel` | `string` | — | Axis title beside the y-axis. Also names the y column in the tooltip and table (falls back to `y`). |\n| `showLegend` | `boolean` | `true` | Legend of the `category` series below the chart (real DOM text). Not drawn without `category`. |\n| `showXAxis` | `boolean` | `true` | Show the x-axis. |\n| `showYAxis` | `boolean` | `true` | Show the y-axis. |\n| `showGrid` | `boolean` | `true` | Dashed grid lines (`--dt-line`). |\n| `yAxisWidth` | `number` | `48` (`36` when the chart is narrower than 400 px) | Width reserved for y-axis labels, px. When set, it is used at every width. |\n| `height` | `number` or `string` | `300` | Chart height (px number or any CSS length). The width is always 100% of the parent (responsive). |\n| `aspectRatio` | `number` | — | Width / height ratio, e.g. `16 / 9`. When provided it replaces `height`; the empty state uses it too. |\n| `title` | `string` | — | Accessible name: `aria-label` of the `role=\"img\"` region and caption of the hidden table. Falls back to `aria-label`, then `\"Scatter chart\"`. |\n| `description` | `string` | — | Longer text alternative (the takeaway), linked with `aria-describedby`. |\n| `emptyState` | `ReactNode` | `\"No data to display\"` | Shown (as `role=\"status\"`) instead of the chart when there is no plottable row. |\n| `accessibleTable` | `boolean` | `true` | Repeat the points in a visually-hidden `<table>` (columns: `index`, `category`, x, y — the first two only when set). |\n| `animate` | `boolean` | `true` | Animate on mount / data change. Always off when the user prefers reduced motion. |\n| `showTooltip` | `boolean` | `true` | Tooltip on hover (themed, dark-mode aware): the `index` value (or series) as the heading, then the series and the formatted x and y. |\n| `className` | `string` | — | Extra classes for the root `<div>` (merged with `cn`). |\n| `ref` | `Ref<HTMLDivElement>` | — | Forwarded to the root `<div>`. |\n| ...rest | `HTMLAttributes<HTMLDivElement>` | — | Forwarded to the root `<div>` (`id`, `data-*`, `aria-*`, handlers). |\n\n## Empty and single-point data\n\n- No rows, or no row with a numeric `x` and `y`, renders `emptyState` in a `role=\"status\"` box with the chart's accessible name.\n- A single point (or several points sharing one x or y value) would collapse that axis onto one value, so the axis is padded by half the value on each side (±1 around zero) and the point sits in the middle of the plot.\n\n## Examples\n\n### Basic\n\n```jsx\nconst projects = [\n  { project: 'Atlas', health: 82, variance: -4 },\n  { project: 'Borealis', health: 45, variance: 18 },\n  { project: 'Cygnus', health: 67, variance: 6 },\n];\n\n<ScatterChart\n  data={projects}\n  x=\"health\"\n  y=\"variance\"\n  index=\"project\"\n  xAxisLabel=\"Health score\"\n  yAxisLabel=\"Budget variance\"\n  valueFormatter={(v) => `${v}%`}\n  title=\"Project health vs budget variance\"\n  description=\"Projects with lower health scores are running over budget.\"\n/>\n```\n\n### Grouped series\n\n```jsx\n<ScatterChart\n  data={projects}\n  x=\"health\"\n  y=\"variance\"\n  index=\"project\"\n  category=\"department\"\n  colors={['primary', 'warning', 'success']}\n  title=\"Project health by department\"\n/>\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Name | The SVG sits in a `role=\"img\"` region named by `title` (falls back to `aria-label`, then \"Scatter chart\") |\n| Description | `description` is rendered visually hidden and linked with `aria-describedby` |\n| Numbers | `accessibleTable` (default on) repeats every plotted point in a visually-hidden `<table>` with a caption, column headers and row headers (`index` when set), formatted with `xAxisFormatter` / `valueFormatter`; recharts' SVG itself has no accessible content |\n| Legend | Real DOM text, not SVG |\n| Motion | Animation is disabled when `prefers-reduced-motion: reduce` is set (and with `animate={false}`) |\n| Colour | Series colours come from the design tokens; pair the chart with the table / description so colour is never the only signal |\n| Dark mode | Axis text (`--dt-muted`), grid (`--dt-line`) and series tokens are re-read when the `dark` class or `data-theme` on `<html>` changes; the tooltip uses the surface / foreground / muted tokens |\n| Empty | No plottable row renders `emptyState` in a `role=\"status\"` box with the same accessible name |\n\n## Server rendering\n\nSafe to render on the server (a Next.js `\"use client\"` page). The first client render matches the server's HTML: token colours stay `rgb(var(--dt-*))` and reduced motion reads as off until hydration finishes, then the live values apply. SVG ids come from `React.useId()` (`dt-chart-…`), not a module counter.\n\n[← Component overview](README.md)\n",
     "SearchField": "# SearchField\n\niOS-style search input: a `type=\"search\"` field with a leading search icon, a clear button, and a **Cancel** text button on phones while the field is focused. Optionally shows results: in a full-height `Sheet` with the field pinned at the top on phones, and in a popover beneath the field elsewhere.\n\n## Import\n\n```jsx\nimport { SearchField } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `string` | — | Controlled value. Pair with `onValueChange` (or `onChange`) |\n| `defaultValue` | `string` | `\"\"` | Uncontrolled initial value |\n| `onValueChange` | `(value: string) => void` | — | Called with the new text on every change: typing, the clear button, Escape and Cancel. Recommended for controlled use |\n| `onChange` | `(event) => void` | — | The input's change event while typing. Clear / Escape / Cancel call it with `{ target: { value: \"\" } }` (same convention as `Input`) |\n| `onSearch` | `(value: string) => void` | — | Called with the current text on Enter (not during IME composition) |\n| `onClear` | `() => void` | — | Called after the clear button (or Escape) empties the field |\n| `onCancel` | `() => void` | — | Called after Cancel clears and blurs the field (and closes the results) |\n| `showCancel` | `boolean` \\| `\"auto\"` | `\"auto\"` | `\"auto\"`: Cancel shows on phones while the field is focused. `true`: always. `false`: never |\n| `cancelLabel` | `string` | `\"Cancel\"` | Cancel button text |\n| `clearLabel` | `string` | `\"Clear search\"` | Accessible name of the clear button |\n| `placeholder` | `string` | `\"Search\"` | Placeholder; also the default accessible name |\n| `results` | `ReactNode` | — | Results content. Passing it (or `renderResults`) turns on the results surface |\n| `renderResults` | `({ value, close }) => ReactNode` | — | Render function for results; `close()` hides them. Return `null` to show nothing (e.g. while `value` is empty) |\n| `resultsOpen` | `boolean` | — | Controlled results visibility. Uncontrolled by default: opens on focus / typing (popover) or on tap / typing (sheet) |\n| `onResultsOpenChange` | `(open: boolean) => void` | — | Called when the results want to open or close |\n| `resultsLabel` | `string` | `\"Search results\"` | Accessible name of the results region and of the results sheet |\n| `presentation` | `\"auto\"` \\| `\"popover\"` \\| `\"sheet\"` | `\"auto\"` | How results present. `\"auto\"`: a sheet on coarse-pointer screens under 640px, a popover elsewhere (popover on the server). Also decides whether `showCancel=\"auto\"` shows Cancel |\n| `disabled` | `boolean` | `false` | Disables the field; no clear or Cancel button |\n| `readOnly` | `boolean` | `false` | Read-only; no clear button |\n| `className` | `string` | — | Classes for the root wrapper (merged with `cn`), e.g. a width |\n| `inputClassName` | `string` | — | Classes for the `<input>` (merged with `cn`) |\n| `aria-label` | `string` | `placeholder` | Accessible name. Omitted when you pass `aria-labelledby` |\n| `...rest` | `InputHTMLAttributes` | — | Forwarded to the `<input>` (`name`, `id`, `autoFocus`, `aria-*`, `data-*`, handlers) |\n\n`ref` points at the `<input>`. The input always has `type=\"search\"`, `enterKeyHint=\"search\"` and `inputMode=\"search\"`, so phones show a **Search** key. The native WebKit clear button is hidden in favour of the component's own.\n\n## Keyboard\n\n| Key | Action |\n|-----|--------|\n| Enter | `onSearch(value)` |\n| Escape | Closes the results popover; with no popover open, clears the text |\n| Escape (sheet) | Closes the results sheet; focus returns to the inline field |\n| Tab | Moves out of the field and closes the popover |\n\n## Touch\n\nThe clear button reaches 44×44px on coarse pointers, and so does the field itself (40px on desktop, 44px on touch). Pressing clear or Cancel does not blur the field first, so the press always lands.\n\n## Results\n\n```jsx\nconst [q, setQ] = useState('');\nconst hits = useSearch(q);\n\n<SearchField\n  value={q}\n  onValueChange={setQ}\n  onSearch={submit}\n  renderResults={({ value, close }) =>\n    value ? (\n      <ul>\n        {hits.map((h) => (\n          <li key={h.id}>\n            <button type=\"button\" onClick={() => { open(h); close(); }}>{h.title}</button>\n          </li>\n        ))}\n      </ul>\n    ) : null\n  }\n/>\n```\n\n- **Desktop / tablet:** results render in a region beneath the field (`z-popover`, `bg-surface`, `border-line`), opened on focus or typing and closed by Escape, a press outside the field, tabbing away, Cancel or `close()`.\n- **Phones:** tapping or typing in the field opens a full-height bottom `Sheet` (`role=\"dialog\"`, named by `resultsLabel`) with a second field pinned at the top and the results scrolling below. That field gets focus and shares the same value; its Cancel button clears, closes the sheet and calls `onCancel`. Escape, the backdrop or a downward drag close it too.\n\nThe results region is plain content: it is not a `combobox` / `listbox`. Put real buttons or links in it.\n\n## Examples\n\n### Plain search\n\n```jsx\n<SearchField placeholder=\"Search invoices\" onSearch={(q) => router.push(`/invoices?q=${q}`)} className=\"max-w-sm\" />\n```\n\n### Always show Cancel (e.g. inside a search screen)\n\n```jsx\n<SearchField showCancel autoFocus onCancel={() => navigate(-1)} />\n```\n\n[← Component overview](README.md)\n",
     "SegmentedControl": "# SegmentedControl\n\niOS-style segmented control for switching a **view or value** (list / board, day / week / month). It is a `role=\"radiogroup\"` with one `role=\"radio\"` per option and a sliding thumb under the selected option. Controlled or uncontrolled. When the choice switches **panels of content**, use `Tabs variant=\"segmented\"` instead: it looks the same but has tab / tabpanel semantics.\n\n## Import\n\n```jsx\nimport { SegmentedControl } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `options` | `Array<{ value, label, icon?, disabled? }>` | `[]` | The segments. `value` is a string or number and must be unique; `label` is a node; `icon` is a node shown before the label (hidden from screen readers); `disabled` skips the option. |\n| `value` | `string` | — | Controlled selected value (a string or number matching an option's `value`). |\n| `defaultValue` | `string` | — | Uncontrolled initial value (string or number). Without `value` or `defaultValue` nothing is selected and the first enabled option is the tab stop. |\n| `onChange` | `(value) => void` | — | Receives the newly selected option's `value` (not a DOM event). Not called when the selected option is clicked again. |\n| `size` | `string` | `\"md\"` | `sm`, `md` or `lg`. Same padding and type scale as `Tabs` segments. Every size grows to 44px tall on coarse pointers (touch screens). |\n| `fullWidth` | `boolean` | `false` | Stretch to the container's width. Segments are equal width either way. |\n| `name` | `string` | — | Submits the selected value with a form through a hidden input. |\n| `disabled` | `boolean` | `false` | Disable the whole group (dimmed, out of the tab order, `aria-disabled` on the root). |\n| `aria-label` | `string` | — | Accessible name of the group. Pass this or `aria-labelledby`. |\n| `aria-labelledby` | `string` | — | Id of a visible label for the group. |\n| `className` | `string` | — | Merged onto the root with `cn`, so your classes win on conflict. |\n\nOther props (`id`, `data-*`, event handlers, …) go to the root `<div role=\"radiogroup\">`, which also receives the forwarded `ref`.\n\n## Behavior\n\n- **Keyboard:** one tab stop (roving tabindex): the selected option, or the first enabled option when nothing is selected. `ArrowLeft` / `ArrowRight` / `ArrowUp` / `ArrowDown` move focus **and select**, skip disabled options and wrap around. `Home` / `End` jump to the first / last enabled option. Under `dir=\"rtl\"` the left and right arrows swap.\n- **Thumb:** the selected background is a thumb measured from the selected option (in a layout effect, re-measured on resize) that slides between options. The slide is off under `prefers-reduced-motion`. Before the first measurement (server render, hidden container) the selected option draws its own background, so nothing flashes.\n- **Styling:** grey track (the `bg-line` role token, which follows dark mode) with a `bg-surface` thumb; the selected label is `text-foreground` and the others are `text-muted`. Options show a `focus-visible` ring and shrink slightly while pressed (off under reduced motion).\n- **Icon-only options:** give the label visually hidden text, e.g. `label: <span className=\"sr-only\">Grid</span>`, so each radio still has a name.\n\n## Example\n\n```jsx\nconst [view, setView] = useState('list');\n\n<SegmentedControl\n  aria-label=\"View\"\n  value={view}\n  onChange={setView}\n  options={[\n    { value: 'list', label: 'List', icon: <List className=\"h-4 w-4\" /> },\n    { value: 'board', label: 'Board' },\n    { value: 'calendar', label: 'Calendar', disabled: true },\n  ]}\n/>\n\n<SegmentedControl aria-label=\"Period\" fullWidth size=\"lg\" defaultValue=\"week\" options={[\n  { value: 'day', label: 'Day' },\n  { value: 'week', label: 'Week' },\n  { value: 'month', label: 'Month' },\n]} />\n```\n\n[← Component overview](README.md)\n",
     "Select": "# Select\n\nSingle or multi-select dropdown with search, grouped options, creatable options, and optional select-all.\n\n> **The open menu portals to `document.body`.** In popover mode the dropdown is\n> rendered through a React portal with `position: fixed`, anchored to the\n> trigger by floating-ui: it flips above when there is no room below, shifts to\n> stay in view, matches the trigger width and caps its height to the space\n> left. It **escapes any ancestor with `overflow: hidden | auto | scroll`**\n> instead of being clipped by it, follows the trigger on scroll/resize while\n> open, and sits on the `popover` z-layer (above dialogs and sheets).\n>\n> **On phones it opens as a bottom sheet.** With the default\n> `presentation=\"auto\"`, small touch screens (`(pointer: coarse) and\n> (max-width: 639px)`) get a bottom [`Sheet`](./Sheet.md) instead:\n>\n> - It is titled by `label`, or by `placeholder` when there is no label.\n> - Search is pinned in the header and is **not** auto-focused, so the\n>   keyboard does not cover the options.\n> - Option rows are 48px, with a check on the selected one.\n> - Multi-select gets a **Done** button; single-select closes on pick.\n> - It keeps `role=\"listbox\"`, `aria-selected` and the same keyboard\n>   navigation.\n>\n> Pass `presentation=\"popover\"` to keep the dropdown everywhere. On coarse\n> pointers the search box is not auto-focused in popover mode either, and the\n> clear and tag-remove controls grow to a 44px touch target.\n\n## Import\n\n```jsx\nimport { Select } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `options` | `Array` | `[]` | `[{ value, label, disabled, group? }]`. With `grouped`: groups `[{ label, options: [...] }]` and/or flat options carrying a `group` key. |\n| `value` | `any` \\| `any[]` | — | Selected value(s); array when `multiSelect` |\n| `onChange` | `function` | — | `(value)` or `(values[])` |\n| `placeholder` | `string` | `\"Select an option...\"` | Placeholder text. While nothing is selected it renders in the muted role colour (`text-muted`, like `Input`'s `::placeholder`) and the trigger carries `data-empty` for app styling; a `className` colour still wins (merged last). |\n| `label` | `string` | — | Visible label. Wired to the trigger (`<label for>` + `aria-labelledby`), so the control's accessible name is the label followed by the current value. |\n| `error` | `string` | — | Error message. Sets `aria-invalid` and replaces `helperText` while shown. |\n| `helperText` | `ReactNode` | — | Hint below the control, linked via `aria-describedby`. Hidden while `error` is shown. |\n| `disabled` | `boolean` | — | Disable select |\n| `required` | `boolean` | — | Required |\n| `multiSelect` | `boolean` | `false` | Allow multiple selection |\n| `searchable` | `boolean` | `false` | Show search input |\n| `grouped` | `boolean` | `false` | Render options in groups. Accepts group objects or flat options with a `group` key; malformed entries are skipped with a console warning instead of crashing. |\n| `allowClear` | `boolean` | `false` | Show the clear button (`aria-label=\"Clear selection\"`) when something is selected. It is a separate button beside the trigger and returns focus to the trigger. Off by default (it was `true` up to 1.3.2): turn it on only when an empty value is valid for the field. |\n| `creatable` | `boolean` | `false` | Allow creating new option when no match |\n| `onCreateOption` | `function` | — | Called when creating option |\n| `onSearch` | `function` | — | Search term callback |\n| `loading` | `boolean` | `false` | Loading state |\n| `selectAllOption` | `boolean` | `true` | Show select all (multi) |\n| `closeOnSelect` | `boolean` | `false` | Close dropdown on select (single) |\n| `maxTagCount` | `number` | `3` | Max tags shown in multi (rest as \"+N\") |\n| `onMenuItemRender` | `function` | — | Custom option render |\n| `renderGroupLabel` | `function` | — | Custom group label |\n| `name` | `string` | — | Form field name |\n| `size` | `string` | `\"md\"` | `sm`, `md` or `lg`. Trigger height: `sm` 32px, `md` 38px (44px on coarse pointers, so it meets the touch-target minimum on phones), `lg` 44px everywhere |\n| `presentation` | `string` | `\"auto\"` | `auto`, `popover` or `sheet`. How the open menu presents. `auto`: a bottom sheet on small touch screens (`(pointer: coarse) and (max-width: 639px)`), an anchored popover elsewhere and on the server. `popover` and `sheet` force one. |\n| `className` | `string` | — | Extra CSS classes |\n\n## Examples\n\n### Basic single select\n\n```jsx\nconst options = [\n  { value: 'a', label: 'Option A' },\n  { value: 'b', label: 'Option B' },\n];\n<Select\n  options={options}\n  value={value}\n  onChange={setValue}\n  placeholder=\"Choose one\"\n/>\n```\n\n### Multi select with search\n\n```jsx\n<Select\n  options={options}\n  value={selected}\n  onChange={setSelected}\n  multiSelect\n  searchable\n  placeholder=\"Choose multiple\"\n/>\n```\n\n### Grouped options\n\n```jsx\nconst grouped = [\n  { label: 'Fruits', options: [{ value: 'apple', label: 'Apple' }, { value: 'banana', label: 'Banana' }] },\n  { label: 'Veggies', options: [{ value: 'carrot', label: 'Carrot' }] },\n];\n<Select options={grouped} grouped value={value} onChange={setValue} />\n```\n\n### Grouped from a flat list (`group` key)\n\n`grouped` also accepts the flat shape most APIs return. Options are bucketed by\n`group` in first-seen order; options without a `group` render first-seen in an\nunlabelled bucket (no header). Malformed entries (`null`, a group whose\n`options` is not an array, …) are ignored with a one-time `console.warn` — the\ncomponent never throws on bad input.\n\n```jsx\nconst connections = [\n  { value: 'gh', label: 'GitHub', group: 'Code' },\n  { value: 'sl', label: 'Slack', group: 'Chat' },\n  { value: 'gl', label: 'GitLab', group: 'Code' },\n];\n<Select grouped options={connections} value={value} onChange={setValue} />\n```\n\n### Label, helper text and accessibility\n\n```jsx\n<Select\n  label=\"Role\"\n  helperText=\"Controls what this person can see.\"\n  options={roles}\n  value={role}\n  onChange={setRole}\n/>\n// getByRole('button', { name: /^Role/ }) — the trigger is a button with\n// aria-haspopup=\"listbox\"; the open listbox is labelled by the same label.\n```\n\nPass `id` to control the trigger's id (the label's `for` follows it); otherwise\none is generated with `useId`.\n\n### Keyboard\n\nThe trigger is a button that opens a listbox (the WAI-ARIA collapsible\nlistbox pattern). Every control in the popup is a real, focusable element:\n\n- **Trigger:** Enter / Space opens the menu. Opening moves focus to the search\n  box (`searchable`) or to the listbox.\n- **In the menu:** ↑ / ↓ move the active option (wrapping), Home / End jump to\n  the first / last (in the listbox, not the search box), Enter selects, Space\n  toggles the active option in the listbox (`multiSelect`), Escape closes. Tab\n  closes and continues the tab order from the trigger.\n- Only the rows on screen are walked: search-filtered, with collapsed groups\n  skipped. The active option is exposed with `aria-activedescendant` on the\n  listbox (and the search box) and scrolled into view. Options carry\n  `role=\"option\"`, `aria-selected` and `aria-disabled`.\n- Single selection, Escape and the clear button return focus to the trigger.\n- With `creatable`, Enter in the search box with no active option creates the\n  typed value (same as clicking **Add \"…\"**).\n- **Buttons:** the clear \"X\" (`Clear selection`), the group toggle\n  (`Collapse <group>` / `Expand <group>`, with `aria-expanded`), select-all\n  (`Select all` / `Deselect all`) and the creatable row are all\n  `<button type=\"button\">`. None of them is nested inside the trigger.\n\nWhen a value is selected the component renders two buttons (trigger and clear),\nso name the trigger in tests: `getByRole('button', { name: /^Role/ })`.\n\n### Helper text and errors\n\n`helperText` renders a muted line below the control and is linked to it via\n`aria-describedby`, so screen readers announce it with the field. **While\n`error` is set, the error message replaces the helper text** (only one line is\nshown, and `aria-describedby` points at the error). This rule is the same on\nevery field-like component: `Input`, `Select`, `DatePicker`, `DateRangePicker`\nand `Form` fields.\n\n[← Component overview](README.md)\n",
@@ -6550,7 +6769,8 @@
     "Sidebar": "# Sidebar\n\nCollapsible side navigation with optional nested items, logo, and user block. Supports desktop collapsed state and mobile drawer. The content renders **once**: from `md` up it is a sticky in-flow column, below `md` the same tree is an off-canvas drawer. Tooltips show when collapsed; optional `drawerPosition` for mobile. The panel uses the semantic `bg-surface` / `border-line` / `text-foreground` tokens (section labels use `text-muted`), so it follows dark mode.\n\nEvery item — parent or child — renders as an `<a>`. Items with `href` are real links, so Ctrl/Cmd-click, Shift-click and middle-click open them in a new tab or window (the sidebar does not intercept those clicks). Items without `href` render as `<a role=\"button\">` and stay keyboard-operable (Enter / Space).\n\n## Import\n\n```jsx\nimport { Sidebar } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `items` | `Array` | `[]` | Nav items: `{ id, label, icon, href?, target?, rel?, children?, onClick?, active?, disabled?, badge?, badgeLabel?, group? }`. `children` = nested items. |\n| `collapsed` | `boolean` | `false` | Desktop collapsed state (icon-only). |\n| `collapsible` | `boolean` | `true` | `false` removes the md+ collapse / expand toggle, for apps that never collapse the sidebar. The phone drawer keeps its 44px **Close navigation** button. |\n| `onToggle` | `() => void` | — | Toggle collapse (e.g. chevron click). |\n| `className` | `string` | — | Classes for the sidebar container inside the `<aside>` (the element `ref` points to). Applies to both the column and the drawer. |\n| `containerClassName` | `string` | — | Classes for the outer desktop sticky wrapper (default `sticky top-0 h-[100dvh]`; `display: contents` below `md`), merged with `tailwind-merge` — e.g. `\"h-full static\"` to size it from its parent. |\n| `stickyOffset` | `number` \\| `string` | — | Height of a top bar above the sidebar (number = px, or any CSS length such as `\"4rem\"`). The desktop sidebar sticks at that offset and its height becomes `calc(100dvh - offset)`, so a footer / user block stays on screen. Omit for the default full-viewport `100dvh`. |\n| `expandedIds` | `string[]` | — | Controlled open groups (parent item ids). |\n| `defaultExpandedIds` | `string[]` | `[]` | Initially open groups (uncontrolled). |\n| `onExpandedChange` | `(ids: string[]) => void` | — | Called with the next open ids when a group is opened/closed (and, when controlled, to request opening the active item's ancestors). |\n| `logo` | `ReactNode` | — | Logo at top. |\n| `footer` | `ReactNode` \\| `({ collapsed, isMobile, closeMobile }) => ReactNode` | — | Pinned region at the bottom, above the user block (e.g. Settings / Help). The function form lets it adapt to the collapsed rail and close the mobile drawer on click. |\n| `user` | `object` | — | User block at bottom: `{ name, email, avatar? }`. |\n| `onUserClick` | `(user) => void` | — | When set, the user block is a real `<button type=\"button\">` (Enter/Space work natively). Without it the block is static content. |\n| `drawerPosition` | `\"left\"` \\| `\"right\"` | `\"left\"` | Mobile drawer side. |\n| `isMobileOpen` | `boolean` | — | Controlled mobile open. |\n| `setIsMobileOpen` | `(open: boolean) => void` | — | Set mobile open (when controlled). |\n| `showCollapsedTooltips` | `boolean` | `true` | Show tooltips when collapsed. |\n| `swipeable` | `boolean` | `true` | Phones: swipe in from the screen edge (20px, the `drawerPosition` side) to open the drawer, and swipe the open drawer back toward its edge to close it. Needs `setIsMobileOpen`. `false` turns both gestures off. |\n| `tooltipOptions` | `object` | — | Options for internal Tooltip. |\n| `linkAs` | `ElementType` | `\"a\"` | Element used for items with `href` — pass Next.js `Link` (or a React Router wrapper that maps `href` to `to`) for client-side navigation. Receives `href`, `target`, `rel`, `className`, `onClick` and ARIA props. |\n\n## Item shape\n\n- `id`: string (required for expand/active).\n- `label`: string.\n- `icon`: ReactNode.\n- `children`: optional array of same shape (nested items).\n- `href`: optional URL. The item renders as a link (`linkAs`, default `<a>`) and gets `aria-current=\"page\"` when active.\n- `target` / `rel`: optional anchor attributes; `rel` defaults to `\"noopener noreferrer\"` when `target=\"_blank\"`.\n- `onClick`: optional handler, called with the item on a plain click of a leaf. Not called for Ctrl/Cmd/Shift/Alt-clicks on links — those are left to the browser.\n- `active`: optional boolean for current page.\n- `disabled`: optional boolean; the item is dimmed, has no `href`, is skipped in the tab order and ignores clicks.\n- `badge`: optional `string | number` — a pill after the label; when collapsed, a compact badge on the icon. `0`, `\"\"`, `null` and `undefined` render nothing.\n- `badgeLabel`: optional string — accessible text for the badge (e.g. `\"3 unread\"`); the visible value is then hidden from screen readers. Collapsed items are named `\"<label>, <badgeLabel ?? badge>\"`.\n- `group`: optional string (top-level items only) — items sharing a `group` render under that section heading, in order of first appearance (same convention as `AppShell`'s `nav[].group`). Ungrouped items render without a heading. When collapsed, headings become dividers (the name stays available to screen readers via `role=\"group\"` + `aria-labelledby`).\n\n## Expansion\n\n- **The group holding the current page is open on load.** Every ancestor of an item with `active: true` (at any depth) is opened on mount and whenever the active item changes; a parent that is itself `active` opens too. Groups the user opened stay open, and the user can still close the active group.\n- **Uncontrolled** (default): `defaultExpandedIds` seeds the open groups; `onExpandedChange(ids)` reports user changes.\n- **Controlled**: pass `expandedIds` + `onExpandedChange`. Sidebar never changes the open set itself; when the active item's ancestors are missing it calls `onExpandedChange` with them added (on mount and when the active item changes).\n\n```jsx\nconst [expandedIds, setExpandedIds] = useState(() => JSON.parse(localStorage.navOpen ?? '[]'));\n<Sidebar items={items} expandedIds={expandedIds} onExpandedChange={(ids) => {\n  setExpandedIds(ids);\n  localStorage.navOpen = JSON.stringify(ids);\n}} />\n```\n\n## Mobile drawer\n\nBelow `md` (`(min-width: 768px)` does not match) the sidebar is a drawer (`<aside role=\"dialog\" aria-modal=\"true\" aria-label=\"Navigation\">`) driven by `isMobileOpen` / `setIsMobileOpen`. While closed it is `inert` and `aria-hidden`, so its links are out of the tab order and the accessibility tree. While open: focus moves into the drawer (its first *rendered* focusable — elements hidden with `display:none` / `visibility:hidden`, on themselves or an ancestor, are skipped), Tab / Shift+Tab are trapped inside it (between its first and last rendered focusables), **Escape** calls `setIsMobileOpen(false)`, and on close focus returns to the element that had it before (e.g. your menu button). Body scroll is locked while open (ref-counted and shared with `Dialog` / `Drawer`, so closing the drawer under a stacked dialog keeps the page locked); while CSS hides the drawer at `md`+, Tab is not trapped. Only the top-most overlay reacts to Escape. The slide is disabled under `prefers-reduced-motion`.\n\nFrom `md` up the same `<aside>` is a plain column: no `role=\"dialog\"`, never `inert`, no focus trap and no scroll lock, even if `isMobileOpen` is still `true`. On the server (and while hydrating) the sidebar renders as the column; on a phone it switches to the closed drawer right after hydration. The drawer is never collapsed — `collapsed` only affects the column — and its header button reads **Close navigation** and calls `setIsMobileOpen(false)` (also with `collapsible={false}`, which only removes the column's collapse toggle).\n\nThe drawer is `h-dvh`, padded with `pt-safe` / `pb-safe` and the safe area on its outer edge (`pl-safe` left, `pr-safe` right; add `viewport-fit=cover` to your viewport meta). It stacks with the z-layer tokens: the backdrop on `z-overlay`, the drawer on `z-modal` (no inline `zIndex`). The collapse / close button is 44×44px.\n\n### Swipe gestures\n\nWith `swipeable` (default) and `setIsMobileOpen`:\n\n- **Swipe to close.** Drag the open drawer toward its edge; it follows the finger and closes past 80px or on a flick (faster than 0.5 px/ms). Shorter drags spring back. The drawer is `touch-pan-y`, so vertical scrolling of a long nav stays native.\n- **Edge swipe to open.** A horizontal touch swipe that starts within 20px of the screen edge (left, or right for `drawerPosition=\"right\"`) pulls the drawer in and opens it past 56px or on a flick. The listeners sit on `window`, so nothing covers the page edge and taps there still reach your content. Vertical swipes are ignored.\n\n## Height / top bar\n\nBy default the desktop sidebar is `sticky top-0` and `100dvh` tall. Under a fixed/sticky top bar pass its height:\n\n```jsx\n<header className=\"sticky top-0 h-16\">…</header>\n<div className=\"flex\">\n  <Sidebar items={items} stickyOffset={64} footer={<HelpLink />} />\n  <main className=\"flex-1\">…</main>\n</div>\n```\n\nOr size it from a container with `containerClassName=\"static h-full\"` (the parent must have a height).\n\n## Click behavior\n\n| Item | Plain click | Ctrl/Cmd/Shift-click or middle-click |\n|------|-------------|--------------------------------------|\n| Leaf with `href` | Navigates; calls `onClick`; closes the mobile drawer | Browser opens a new tab/window; sidebar does nothing |\n| Parent with `href` | Navigates and expands its group (a second click keeps it open) | Browser opens a new tab/window; group is not toggled |\n| Parent chevron (with `href`) | Toggles the group without navigating | — |\n| Item without `href` | Leaf: calls `onClick`. Parent: toggles its group | Same as plain click |\n\nParents expose `aria-expanded` and `aria-controls`.\n\n## Sections, badges and footer\n\n```jsx\n<Sidebar\n  linkAs={Link}\n  items={[\n    { id: 'home', label: 'Home', href: '/', icon: <Home /> },\n    { id: 'inbox', label: 'Inbox', href: '/inbox', group: 'Work', badge: 12, badgeLabel: '12 unread', icon: <Mail /> },\n    { id: 'billing', label: 'Billing', group: 'Finance', icon: <Receipt />, children: [\n      { id: 'invoices', label: 'Invoices', href: '/billing/invoices', active: true }, // \"Billing\" opens on load\n    ]},\n  ]}\n  footer={({ collapsed, closeMobile }) => (\n    <Link href=\"/settings\" onClick={closeMobile} aria-label={collapsed ? 'Settings' : undefined}>\n      <Settings />{!collapsed && 'Settings'}\n    </Link>\n  )}\n/>\n```\n\n## Example\n\n```jsx\nconst [collapsed, setCollapsed] = useState(false);\n<Sidebar\n  items={[\n    { id: 'dash', label: 'Dashboard', icon: <Home /> },\n    { id: 'settings', label: 'Settings', icon: <Settings />, children: [\n      { id: 'profile', label: 'Profile' },\n      { id: 'security', label: 'Security' },\n    ]},\n  ]}\n  collapsed={collapsed}\n  onToggle={() => setCollapsed(!collapsed)}\n  logo={<Logo />}\n  user={{ name: 'Jane', avatar: '/jane.jpg' }}\n/>\n```\n\n### Links (Next.js)\n\n```jsx\nimport Link from 'next/link';\n\n<Sidebar\n  linkAs={Link}\n  items={[\n    { id: 'home', label: 'Home', href: '/', icon: <Home />, active: pathname === '/' },\n    { id: 'settings', label: 'Settings', href: '/settings', icon: <Settings />, children: [\n      { id: 'profile', label: 'Profile', href: '/settings/profile' },\n      { id: 'security', label: 'Security', href: '/settings/security' },\n    ]},\n    { id: 'docs', label: 'Docs', href: 'https://example.com/docs', target: '_blank' },\n  ]}\n/>\n```\n\n[← Component overview](README.md)\n",
     "Skeleton": "# Skeleton\n\nPlaceholder blocks for loading states. Renders shimmer bars (or circles) when `active` is true; otherwise renders `children`. Items use the `bg-gray-200` token class (`dark:bg-gray-700`), so brands and dark mode apply.\n\n## Import\n\n```jsx\nimport { Skeleton } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `count` | `number` | `1` | Number of skeleton items. |\n| `circle` | `boolean` | `false` | Render items as circles. |\n| `height` | `number` \\| `string` | `16` | Height in px or CSS unit (e.g. `\"2rem\"`). |\n| `width` | `number` \\| `string` | — | Width; default 100% (column) or height (inline/circle). |\n| `rounded` | `boolean` | `true` | Rounded corners (when not circle). |\n| `animated` | `boolean` | `true` | Shimmer animation (`animate-shimmer`, a Tailwind keyframe, so no `<style>` tag is injected). The highlight is soft white in light mode and a faint 10% white in dark mode, so no bright streak shows. Under `prefers-reduced-motion` the bone is static and plain. |\n| `active` | `boolean` | `true` | If true show skeletons; if false render children. |\n| `gap` | `string` | `\"8px\"` | Spacing between items. |\n| `inline` | `boolean` | `false` | Layout items in a row. |\n| `className` | `string` | `\"\"` | Wrapper CSS classes. |\n| `style` | `object` | `{}` | Wrapper inline style. |\n| `children` | `ReactNode` | `null` | Rendered when `active` is false. |\n\n## Examples\n\n```jsx\n<Skeleton />\n<Skeleton count={3} height={20} gap=\"12px\" />\n<Skeleton circle height={40} />\n<Skeleton active={loading} count={2}>\n  <RealContent />\n</Skeleton>\n```\n\n[← Component overview](README.md)\n",
     "Slider": "# Slider\n\nHorizontal slider for a single value or a range (two thumbs). Pass a number for one thumb, a `[low, high]` array for a range. Keyboard, pointer (mouse, touch, pen) and form submission (hidden inputs) are built in. For a min/max **price** picker with text inputs and presets, `PriceRangePicker` remains available.\n\n## Import\n\n```jsx\nimport { Slider } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `number or [number, number]` | — | Controlled value; an array makes it a range slider |\n| `defaultValue` | `number or [number, number]` | `min` | Uncontrolled initial value |\n| `onChange` | `function` | — | `(value) => void` on every change (drag or key) |\n| `onChangeEnd` | `function` | — | `(value) => void` when a drag ends or a key press commits |\n| `min` | `number` | `0` | Minimum |\n| `max` | `number` | `100` | Maximum |\n| `step` | `number` | `1` | Step; decimals are supported |\n| `largeStep` | `number` | — | PageUp/PageDown increment (default: a tenth of the range) |\n| `disabled` | `boolean` | `false` | Disable interaction |\n| `label` | `ReactNode` | — | Visible label; names a single thumb |\n| `showValue` | `boolean` | `false` | Show the formatted value next to the label |\n| `showBubble` | `boolean` | `true` | Show a value bubble (formatted with `formatValue`) above the thumb while it is dragged; hidden otherwise |\n| `formatValue` | `function` | `String` | `(number) => string`; used for display and `aria-valuetext` |\n| `thumbLabels` | `[string, string]` | `[\"Minimum\", \"Maximum\"]` | Accessible names of the two range thumbs |\n| `name` | `string` | — | Emits hidden inputs: `name`, or `name[0]` and `name[1]` for a range |\n| `className` | `string` | — | Extra classes for the root (merged with `cn`) |\n| `...rest` | `HTMLAttributes` | — | Forwarded to the root; `ref` points at it. `aria-label` names the thumb when there is no `label` |\n\nRange thumbs never cross: the low thumb stops at the high value and vice versa.\n\n## Examples\n\n### Single value\n\n```jsx\n<Slider label=\"Volume\" defaultValue={40} showValue />\n```\n\n### Range (controlled)\n\n```jsx\nconst [budget, setBudget] = useState([2000, 8000]);\n\n<Slider\n  label=\"Budget\"\n  min={0}\n  max={10000}\n  step={500}\n  value={budget}\n  onChange={setBudget}\n  showValue\n  formatValue={(v) => `₹${v.toLocaleString('en-IN')}`}\n/>\n```\n\n## Accessibility & keyboard\n\nOn coarse pointers (touch screens) the track row is 44px tall and each thumb has a 44×44 hit area; the visual size is unchanged. Thumbs use a `focus-visible` ring.\n\n| Key | Action |\n|-----|--------|\n| `ArrowRight` / `ArrowUp` | Increase by `step` |\n| `ArrowLeft` / `ArrowDown` | Decrease by `step` |\n| `PageUp` / `PageDown` | Increase / decrease by `largeStep` |\n| `Home` / `End` | Minimum / maximum (for a range thumb: up to the other thumb) |\n\nEach thumb is `role=\"slider\"` with `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext` and `aria-orientation=\"horizontal\"`; range thumbs report the other thumb as their bound. Disabled thumbs are `aria-disabled` and removed from the tab order. Thumbs have the standard focus ring; the track and fill use `dark:` variants.\n\n[← Component overview](README.md)\n",
-    "Sortable": "# Sortable\n\nReorderable list with **pointer drag** (mouse, touch, pen — no extra dependency) **and keyboard reordering** announced through a live region. Replaces hand-rolled Move up / Move down buttons; `moveUp` / `moveDown` are still handed to `renderItem` if you want them as a visible fallback.\n\n## Import\n\n```jsx\nimport { Sortable } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `items` | `array` | `[]` | Items in their current order |\n| `onReorder` | `function` | — | `(newItems, { from, to }) => void` after a drop; set your state to `newItems` |\n| `renderItem` | `function` | — | `(item, state) => ReactNode`; `state` = `{ index, originalIndex, isDragging, isGrabbed, handleProps, moveUp, moveDown }`. Defaults to the item label |\n| `getKey` | `function` | `item.id or item.key or index` | Stable key per item |\n| `getItemLabel` | `function` | `label, title, name or the string itself` | Text used in screen-reader announcements |\n| `disabled` | `boolean` | `false` | Turn reordering off |\n| `handle` | `boolean` | `false` | Drag only from the element you spread `handleProps` on. The handle has `touch-none`, so a touch drag on it starts immediately; without a handle, touch drags start after a long-press |\n| `orientation` | `string` | `\"vertical\"` | `vertical` or `horizontal` (arrow keys and drop detection follow it) |\n| `as` | `string` | `\"ul\"` | `ul`, `ol` or `div` (a `div` list gets `role=\"list\"` / `listitem`) |\n| `itemClassName` | `string` | — | Classes for every item wrapper |\n| `messages` | `object` | — | Override announcement text: `instructions`, `grabbed`, `moved`, `dropped`, `cancelled` |\n| `className` | `string` | — | Extra classes for the list (merged with `cn`) |\n| `...rest` | `HTMLAttributes` | — | Forwarded to the list (`aria-label`, `data-*`, …); `ref` points at it |\n\n`Sortable` is controlled: it previews the move while dragging/carrying and calls `onReorder` once on drop. It never mutates `items`.\n\n## Examples\n\n### Basic\n\n```jsx\nconst [tasks, setTasks] = useState(initialTasks);\n\n<Sortable\n  aria-label=\"Backlog\"\n  items={tasks}\n  onReorder={(next) => setTasks(next)}\n  getItemLabel={(t) => t.title}\n  renderItem={(t) => <div className=\"rounded-md border p-3\">{t.title}</div>}\n/>\n```\n\n### Drag handle + buttons\n\n```jsx\n<Sortable\n  handle\n  aria-label=\"Backlog\"\n  items={tasks}\n  onReorder={(next, { from, to }) => saveOrder(next)}\n  renderItem={(t, { handleProps, moveUp, moveDown }) => (\n    <div className=\"flex items-center gap-2\">\n      <span {...handleProps} aria-hidden=\"true\"><GripVertical /></span>\n      <span className=\"flex-1\">{t.title}</span>\n      <Button size=\"sm\" variant=\"ghost\" onClick={moveUp} aria-label={`Move ${t.title} up`}>↑</Button>\n      <Button size=\"sm\" variant=\"ghost\" onClick={moveDown} aria-label={`Move ${t.title} down`}>↓</Button>\n    </div>\n  )}\n/>\n```\n\n## Accessibility & keyboard\n\n| Key (focus on an item) | Action |\n|------------------------|--------|\n| `Space` / `Enter` | Pick the item up; press again to drop it |\n| `ArrowUp` / `ArrowDown` (vertical) or `ArrowLeft` / `ArrowRight` (horizontal) | Move the carried item |\n| `Escape` | Cancel and restore the original order |\n\nEvery item is focusable (`tabIndex=0`), has `aria-roledescription=\"sortable item\"` and is described by visually hidden instructions. Each pick-up, move, drop and cancel is announced in an `aria-live=\"assertive\"` status region (\"Bravo moved to position 1 of 3.\"). Keys pressed inside interactive children (buttons, inputs) are ignored, and focus stays on the carried item. Moving focus out of the list while carrying cancels the move. Pointer drags start after a 4px threshold so clicks inside items still work.\n\n## Touch & scrolling\n\n- Items without a handle do **not** set `touch-action: none`, so swiping over the list scrolls the page as usual.\n- On touch (`pointerType === \"touch\"`), a whole-item drag starts after a **250 ms long-press**. If the finger moves more than **8 px** before that, it is treated as a scroll and no drag starts. Once the drag is live, native scrolling is suppressed until the finger lifts. Mouse and pen keep the 4 px threshold.\n- While dragging within **40 px** of the edge of the nearest scrollable ancestor (or the viewport when there is none), that container auto-scrolls along the list's axis, faster closer to the edge.\n- Keyboard reordering is unchanged.\n\n[← Component overview](README.md)\n",
+    "Sortable": "# Sortable\n\nReorderable list with **pointer drag** (mouse, touch, pen — no extra dependency) **and keyboard reordering** announced through a live region. Replaces hand-rolled Move up / Move down buttons; `moveUp` / `moveDown` are still handed to `renderItem` if you want them as a visible fallback.\n\n## Import\n\n```jsx\nimport { Sortable } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `items` | `array` | `[]` | Items in their current order |\n| `onReorder` | `function` | — | `(newItems, { from, to }) => void` after a drop; set your state to `newItems` |\n| `renderItem` | `function` | — | `(item, state) => ReactNode`; `state` = `{ index, originalIndex, isDragging, isGrabbed, handleProps, moveUp, moveDown }`. Defaults to the item label |\n| `getKey` | `function` | `item.id or item.key or index` | Stable key per item |\n| `getItemLabel` | `function` | `label, title, name or the string itself` | Text used in screen-reader announcements |\n| `disabled` | `boolean` | `false` | Turn reordering off |\n| `handle` | `boolean` | `false` | Drag only from the element you spread `handleProps` on. The handle has `touch-none`, so a touch drag on it starts immediately; without a handle, touch drags start after a long-press |\n| `orientation` | `string` | `\"vertical\"` | `vertical` or `horizontal` (arrow keys and drop detection follow it) |\n| `as` | `string` | `\"ul\"` | `ul`, `ol` or `div` (a `div` list gets `role=\"list\"` / `listitem`) |\n| `itemClassName` | `string` | — | Classes for every item wrapper |\n| `messages` | `object` | — | Override announcement text: `instructions`, `grabbed`, `moved`, `dropped`, `cancelled`; inside a `SortableGroup` also `groupInstructions`, `movedToList`, `droppedInList`, `refused` |\n| `id` | `string` | — | DOM id of the list. Inside a [`SortableGroup`](SortableGroup.md) it is also the list's `listId`, and is required for the list to join the group |\n| `className` | `string` | — | Extra classes for the list (merged with `cn`) |\n| `...rest` | `HTMLAttributes` | — | Forwarded to the list (`aria-label`, `data-*`, …); `ref` points at it |\n\n`Sortable` is controlled: it previews the move while dragging/carrying and calls `onReorder` once on drop. It never mutates `items`.\n\n## Moving between lists\n\nWrap several lists in a [`SortableGroup`](SortableGroup.md) and give each an `id` to move items between them (pointer, or the cross-axis arrow keys while an item is picked up). The group's `onMove({ item, from: { listId, index }, to: { listId, index } })` fires on a cross-list drop, and its `canDrop(item, target, from)` rejects a target before the drop — a refused list is marked and announced as not droppable and dropping there does nothing. Reordering inside one list still calls `onReorder`. Without a group, `Sortable` behaves exactly as described here.\n\n```jsx\n<SortableGroup onMove={moveCard} canDrop={(card, target) => allowed(card, target.listId)} className=\"grid grid-cols-3 gap-4\">\n  <Sortable id=\"todo\" aria-label=\"To do\" items={board.todo} onReorder={...} className=\"min-h-24\" />\n  <Sortable id=\"done\" aria-label=\"Done\" items={board.done} onReorder={...} className=\"min-h-24\" />\n</SortableGroup>\n```\n\n## Examples\n\n### Basic\n\n```jsx\nconst [tasks, setTasks] = useState(initialTasks);\n\n<Sortable\n  aria-label=\"Backlog\"\n  items={tasks}\n  onReorder={(next) => setTasks(next)}\n  getItemLabel={(t) => t.title}\n  renderItem={(t) => <div className=\"rounded-md border p-3\">{t.title}</div>}\n/>\n```\n\n### Drag handle + buttons\n\n```jsx\n<Sortable\n  handle\n  aria-label=\"Backlog\"\n  items={tasks}\n  onReorder={(next, { from, to }) => saveOrder(next)}\n  renderItem={(t, { handleProps, moveUp, moveDown }) => (\n    <div className=\"flex items-center gap-2\">\n      <span {...handleProps} aria-hidden=\"true\"><GripVertical /></span>\n      <span className=\"flex-1\">{t.title}</span>\n      <Button size=\"sm\" variant=\"ghost\" onClick={moveUp} aria-label={`Move ${t.title} up`}>↑</Button>\n      <Button size=\"sm\" variant=\"ghost\" onClick={moveDown} aria-label={`Move ${t.title} down`}>↓</Button>\n    </div>\n  )}\n/>\n```\n\n## Accessibility & keyboard\n\n| Key (focus on an item) | Action |\n|------------------------|--------|\n| `Space` / `Enter` | Pick the item up; press again to drop it |\n| `ArrowUp` / `ArrowDown` (vertical) or `ArrowLeft` / `ArrowRight` (horizontal) | Move the carried item |\n| `Escape` | Cancel and restore the original order |\n\nEvery item is focusable (`tabIndex=0`), has `aria-roledescription=\"sortable item\"` and is described by visually hidden instructions. Each pick-up, move, drop and cancel is announced in an `aria-live=\"assertive\"` status region (\"Bravo moved to position 1 of 3.\"). Keys pressed inside interactive children (buttons, inputs) are ignored, and focus stays on the carried item. Moving focus out of the list while carrying cancels the move. Pointer drags start after a 4px threshold so clicks inside items still work.\n\n## Touch & scrolling\n\n- Items without a handle do **not** set `touch-action: none`, so swiping over the list scrolls the page as usual.\n- On touch (`pointerType === \"touch\"`), a whole-item drag starts after a **250 ms long-press**. If the finger moves more than **8 px** before that, it is treated as a scroll and no drag starts. Once the drag is live, native scrolling is suppressed until the finger lifts. Mouse and pen keep the 4 px threshold.\n- While dragging within **40 px** of the edge of the nearest scrollable ancestor (or the viewport when there is none), that container auto-scrolls along the list's axis, faster closer to the edge.\n- Keyboard reordering is unchanged.\n\n[← Component overview](README.md)\n",
+    "SortableGroup": "# SortableGroup\n\nConnects several [`Sortable`](Sortable.md) lists so items can **move between lists** — by pointer drag, or by keyboard (pick an item up, then use the cross-axis arrow keys). A `canDrop` predicate is asked *before* a target is shown as droppable, so a move the domain would refuse never looks like it succeeded. Built for boards (drag a card between columns) and backlogs (drag a task into a sprint).\n\n## Import\n\n```jsx\nimport { Sortable, SortableGroup } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `onMove` | `function` | — | `({ item, from: { listId, index }, to: { listId, index } }) => void`, called once when an item is dropped in another list (and `canDrop` allowed it). Remove the item from `from.listId` and insert it into `to.listId` at `to.index`. |\n| `canDrop` | `function` | — | `(item, target: { listId, index }, from: { listId, index }) => boolean`. Asked whenever the carried item targets another list. Return `true` to allow; a refused target is marked and announced as not droppable and dropping there does nothing. Omit to allow every list. Not consulted for reordering inside one list. |\n| `children` | `ReactNode` | — | Your layout, containing the `<Sortable id=\"…\">` lists (at any depth). |\n| `className` | `string` | — | Classes for the wrapper `<div>` (merged with `cn`), e.g. `\"grid grid-cols-3 gap-4\"`. |\n| `...rest` | `HTMLAttributes<HTMLDivElement>` | — | Forwarded to the wrapper `<div>`; `ref` points at it. |\n\nEach `Sortable` inside the group needs an **`id`** — it is the `listId` in `onMove` / `canDrop` (and is still set as the list's DOM `id`). A `Sortable` without an `id` stays a standalone list. Reordering inside a list still calls that list's own `onReorder`; only cross-list moves call `onMove`.\n\nThe group is controlled, like `Sortable`: nothing changes until you update your state in `onMove`.\n\n## Examples\n\n### Board\n\n```jsx\nconst [board, setBoard] = useState({ todo: [...], review: [...], done: [...] });\n\nfunction moveCard(board, { from, to }) {\n  const next = { ...board, [from.listId]: board[from.listId].slice() };\n  const [card] = next[from.listId].splice(from.index, 1);\n  if (to.listId !== from.listId) next[to.listId] = board[to.listId].slice();\n  next[to.listId].splice(to.index, 0, card);\n  return next;\n}\n\n<SortableGroup\n  className=\"grid grid-cols-3 gap-4\"\n  onMove={(move) => setBoard((b) => moveCard(b, move))}\n  // Server-computed transitions: \"done\" only accepts cards from \"review\".\n  canDrop={(card, target, from) => target.listId !== 'done' || from.listId === 'review'}\n>\n  {[['todo', 'To do'], ['review', 'Review'], ['done', 'Done']].map(([id, name]) => (\n    <section key={id}>\n      <h3>{name}</h3>\n      <Sortable\n        id={id}\n        aria-label={name}\n        className=\"min-h-24\"\n        items={board[id]}\n        onReorder={(next) => setBoard((b) => ({ ...b, [id]: next }))}\n        getItemLabel={(t) => t.title}\n        renderItem={(t) => <div className=\"rounded-md border border-line bg-surface p-3\">{t.title}</div>}\n      />\n    </section>\n  ))}\n</SortableGroup>\n```\n\nGive the lists a minimum size (`min-h-24` above) so an empty list still has an area to drop on.\n\n### Confirm before committing\n\n`onMove` fires once, on drop, so a transition that needs extra input can open a prompt first and only update state on confirm — the card never jumps to the new column and back.\n\n```jsx\n<SortableGroup onMove={(move) => (needsComment(move) ? openCommentPrompt(move) : apply(move))} />\n```\n\n## Pointer\n\n- Drag an item over another list of the group: that list shows a dashed placeholder where the item would land (`data-drop-target=\"allowed\"` on the list, `data-sortable-placeholder=\"allowed\"` on the placeholder). The source list keeps its order and the dragged item is dimmed.\n- If `canDrop` refuses the target, the list and placeholder are marked `refused` (the placeholder is drawn in the error colour with `cursor-not-allowed`) and the dragged item gets `data-leaving=\"refused\"`. Releasing there drops nothing: the item stays where it was and neither `onMove` nor `onReorder` is called.\n- Move back over the source list to reorder within it as usual. Touch long-press, handles and auto-scroll work as in `Sortable`.\n\n## Keyboard\n\n| Key (an item picked up with `Space` / `Enter`) | Action |\n|------------------------------------------------|--------|\n| `ArrowLeft` / `ArrowRight` (vertical lists) or `ArrowUp` / `ArrowDown` (horizontal lists) | Carry the item to the previous / next list of the group, in document order. Back in its own list, it returns to its original position |\n| `ArrowUp` / `ArrowDown` (vertical) or `ArrowLeft` / `ArrowRight` (horizontal) | Move it within the current list, including a target list |\n| `Space` / `Enter` | Drop. On a refused target nothing is dropped and the item stays picked up, so you can carry it on |\n| `Escape` | Cancel; nothing moves |\n\nEach step is announced through the source list's live region: \"Alpha moved to Doing, position 2 of 3.\", \"Alpha cannot be dropped in Done.\", \"Alpha dropped in Doing at position 2 of 3.\". List names come from the list's `aria-label` (falling back to its `id`). Grouped lists append a sentence about the cross-list keys to their visually hidden instructions. After a keyboard drop, focus follows the item into its new list. All texts can be changed with the `Sortable` `messages` prop (`groupInstructions`, `movedToList`, `droppedInList`, `refused`).\n\n[← Component overview](README.md)\n",
     "Sparkline": "# Sparkline\n\nA word-sized trend line (or area) with no axes, grid or legend — for stat cards and table cells. Still accessible: it is a named `role=\"img\"` with a hidden data table. Wraps `recharts` (optional peer, `/charts` entry point).\n\n## Install\n\nCharts live on a separate entry point so apps that don't use them never install or bundle `recharts`:\n\n```bash\nnpm install recharts\n# React 18 apps: also pin react-is to your React major (recharts resolves it as a peer)\nnpm install react-is@18\n```\n\n## Import\n\n```jsx\nimport { Sparkline } from '@dreamtree-org/twreact-ui/charts';\n```\n\nNever import charts from the root `@dreamtree-org/twreact-ui` — they are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `data` | `object[]` | — | **Required.** Rows to plot. An empty array renders `emptyState`. |\n| `category` | `string` | `\"value\"` | Key of the plotted value in each row. |\n| `index` | `string` | — | Optional key of a label per row (tooltip label and hidden-table row header). |\n| `color` | `ChartColor` | `\"primary\"` | Line colour token (`\"success\"`, `\"error-400\"`, …). |\n| `type` | `\"line\"` or `\"area\"` | `\"line\"` | Draw a line or a filled area. |\n| `valueFormatter` | `(value: number) => string` | `toLocaleString` | Formats values in the tooltip, value axis and hidden data table. |\n| `height` | `number` or `string` | `40` | Chart height (px number or any CSS length). The width is always 100% of the parent (responsive). |\n| `title` | `string` | — | Accessible name: `aria-label` of the `role=\"img\"` region and caption of the hidden table. Falls back to `aria-label`, then `\"Sparkline\"`. |\n| `description` | `string` | — | Longer text alternative (the takeaway), linked with `aria-describedby`. |\n| `emptyState` | `ReactNode` | `\"No data\"` | Shown (as `role=\"status\"`) instead of the chart when `data` is empty. |\n| `accessibleTable` | `boolean` | `true` | Repeat the numbers in a visually-hidden `<table>` for screen-reader users. |\n| `animate` | `boolean` | `false` | Animate on mount / data change. Always off when the user prefers reduced motion. |\n| `showTooltip` | `boolean` | `false` | Hover tooltip (themed, dark-mode aware). |\n| `className` | `string` | — | Extra classes for the root `<div>` (merged with `cn`). |\n| `ref` | `Ref<HTMLDivElement>` | — | Forwarded to the root `<div>`. |\n| ...rest | `HTMLAttributes<HTMLDivElement>` | — | Forwarded to the root `<div>` (`id`, `data-*`, `aria-*`, handlers). |\n\n## Examples\n\n### In a stat card\n\n```jsx\nconst weekly = [{ week: 'W1', signups: 12 }, { week: 'W2', signups: 18 }, { week: 'W3', signups: 15 }, { week: 'W4', signups: 27 }];\n\n<Sparkline data={weekly} index=\"week\" category=\"signups\" color=\"success\" title=\"Signups, last 4 weeks\" />\n```\n\n### Area with tooltip\n\n```jsx\n<Sparkline data={weekly} index=\"week\" category=\"signups\" type=\"area\" showTooltip height={56} />\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Name | The SVG sits in a `role=\"img\"` region named by `title` (falls back to `aria-label`, then a generic name such as \"Sparkline\") |\n| Description | `description` is rendered visually hidden and linked with `aria-describedby` |\n| Numbers | `accessibleTable` (default on) repeats the data in a visually-hidden `<table>` with a caption, column headers and row headers, formatted with `valueFormatter`; recharts' SVG itself has no accessible content |\n| Legend | Real DOM text, not SVG |\n| Motion | Animation is disabled when `prefers-reduced-motion: reduce` is set (and with `animate={false}`) |\n| Colour | Series colours come from the design tokens; pair the chart with the table / description so colour is never the only signal |\n| Dark mode | Axis text (`--dt-muted`), grid (`--dt-line`) and series tokens are re-read when the `dark` class or `data-theme` on `<html>` changes; tooltip and legend use `dark:` variants |\n| Empty | An empty `data` array renders `emptyState` in a `role=\"status\"` box with the same accessible name |\n\n## Server rendering\n\nSafe to render on the server (a Next.js `\"use client\"` page). The first client render matches the server's HTML: token colours stay `rgb(var(--dt-*))` and reduced motion reads as off until hydration finishes, then the live values apply. SVG ids come from `React.useId()` (`dt-chart-…`), not a module counter.\n\n[← Component overview](README.md)\n",
     "SpeechToText": "# SpeechToText\n\nVoice-to-text using the Web Speech API. Headless by default — render a custom\ncontrol via `renderButton`, or drive it imperatively through the ref. The\nbuilt-in fallback button is `className`-extensible and forwards arbitrary props.\n\n## Import\n\n```jsx\nimport { SpeechToText } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `lang` | `string` | `\"en-US\"` | Recognition language |\n| `continuous` | `boolean` | `true` | Keep listening until stopped (forced `false` on mobile) |\n| `interimResults` | `boolean` | `true` | Return interim results |\n| `onSpeechComplete` | `function` | — | Final transcript chunk callback `(text) => void` |\n| `onSpeaking` | `function` | — | Interim transcript callback `(text) => void` |\n| `onError` | `function` | — | Fatal error callback `(Error) => void`. Routine events (`no-speech`, `aborted`) are **not** surfaced |\n| `onStart` | `function` | — | Start callback |\n| `onStop` | `function` | — | Stop callback |\n| `renderButton` | `function` | — | Custom control render-prop (see signature below) |\n| `autoStart` | `boolean` | `false` | Start on mount (once, after support is detected) |\n| `disabled` | `boolean` | `false` | Disable |\n| `resetOnStart` | `boolean` | `false` | Clear the accumulated transcript when a new session starts |\n| `className` | `string` | — | Merged (via `cn`) onto the default button |\n| `...rest` | — | — | Forwarded to the default `<button>` |\n\nThe default button is keyboard-accessible (`aria-pressed`, `aria-label`) and\ntoken-driven. When `renderButton` is supplied, `className`/`...rest` are not\napplied (you own the rendered control).\n\n## `renderButton` signature\n\n```js\nrenderButton({ isListening, isHearing, isSupported, error, start, stop, toggle, disabled })\n```\n\n`isHearing` is `true` while the engine reports speech (between `speechstart` and `speechend`, or once results arrive); it resets when listening stops.\n\n## Listening feedback\n\nWhile listening, the default button shows a pulsing ring behind the mic icon and three small level bars after the label. The bars rest until speech is heard, then animate. There is no audio-level API without `getUserMedia` (which this component does not request), so the bars show *whether* speech is detected, not its volume. Under `prefers-reduced-motion` the pulse becomes a static ring and the bars stop animating. The button also has a `focus-visible` ring, press feedback, a 44 px minimum height on touch screens, and dark-mode colours; it exposes `data-listening` / `data-hearing` attributes for styling.\n\n## Ref methods\n\n`start()`, `stop()`, `toggle()`, `isListening()`, `isSupported()`,\n`getTranscript()`, `clearTranscript()`, `getError()`.\n\n## Example\n\n```jsx\nconst [transcript, setTranscript] = useState('');\n<SpeechToText\n  onSpeechComplete={(chunk) => setTranscript((t) => `${t} ${chunk}`.trim())}\n  onError={(e) => console.error(e)}\n/>\n<div>Transcript: {transcript}</div>\n```\n\n[← Component overview](README.md)\n",
     "StatCard": "# StatCard\n\nPage-level block: a KPI tile with an icon, a label, a big tabular number and an optional change vs a previous period. Extracted from PracticePro `components/ui/StatCard.tsx`.\n\n## Import\n\n```jsx\nimport { StatCard } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `label` | `ReactNode` | — | What the number counts |\n| `value` | `ReactNode` | — | The figure |\n| `icon` | `ReactNode` | — | Lucide icon shown in a tinted chip |\n| `tone` | `primary` \\| `secondary` \\| `success` \\| `warning` \\| `error` \\| `info` | `\"primary\"` | Chip colour (light tint in light mode, a deep translucent tint with a lighter icon in dark mode) |\n| `change` | `{ value: number; period?: string; unit?: '%' \\| ''; goodWhenUp?: boolean }` | — | Change indicator; `goodWhenUp: false` makes a rise red. Drawn in `success-700` / `error-700` (at least 4.5:1 on white), `-400` in dark mode |\n| `loading` | `boolean` | `false` | Shows a skeleton instead of the value |\n| `className` | `string` | — | Extra CSS classes |\n\n## Example\n\n```jsx\n<StatCard label=\"Due this week\" value={18} tone=\"primary\" icon={<CalendarDays className=\"h-6 w-6\" />} />\n<StatCard label=\"Overdue\" value={3} tone=\"error\" change={{ value: 2, unit: '', period: 'vs last week', goodWhenUp: false }} />\n```\n\n[← Component overview](README.md)\n",
@@ -6569,5 +6789,5 @@
     "useApi": "# useApi\n\nThin axios wrapper hook. Sends requests by URL (`fetchData`) or by key from an `apiMap` (`fetchApi` / `fetchApiWith`) and tracks `data`, `error`, `loading` and `lastRequest`. It is not a cache/dedup layer — bring React Query or SWR for that.\n\n## Import\n\n```jsx\nimport { useApi } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\nOptions object passed to `useApi(options)`.\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `BASE_URL` | `string` | `null` | axios `baseURL` |\n| `DEFAULT_HEADERS` | `object` | `{}` | Headers sent with every request |\n| `apiMap` | `Record<string, (...args) => { url, method, headers?, data? }>` | `{}` | Named request builders. Entries may take any number of positional arguments |\n| `createRequestInstance` | `function` | `axios.create` | `(baseURL, defaultHeaders) => AxiosInstance` |\n| `sendRequest` | `function` | — | `(instance, method, url, data, headers) => Promise<AxiosResponse>`; GET/HEAD/DELETE send no body |\n| `onUnauthorized` | `(error, request: { apiKey?, url, method }) => void` | — | Called once per failing request that `isUnauthorized` matches, before the promise rejects. The promise still rejects with the original error. `apiKey` is the `apiMap` key for `fetchApi` / `fetchApiWith` and `undefined` for `fetchData`; `method` is upper-cased. If the handler throws, the throw is logged with `console.error` and the request still rejects with its own error |\n| `isUnauthorized` | `(error) => boolean` | `error?.response?.status === 401` | Which errors trigger `onUnauthorized` |\n\n## Returns\n\n| Field | Type | Description |\n|------|------|-------------|\n| `data` | `any` | Last successful `response.data` |\n| `error` | `Error \\| null` | Last error |\n| `loading` | `boolean` | True while a request with `needLoading` is in flight |\n| `lastRequest` | `string \\| null` | Key of the last `fetchApi` / `fetchApiWith` call |\n| `fetchData(url, method, data?, headers?, { needLoading? })` | `Promise` | Send a request directly |\n| `fetchApi(apiKey, data?, needLoading = true)` | `Promise` | Call `apiMap[apiKey](data)` — **exactly one argument** — and send the result |\n| `fetchApiWith(apiKey, args = [], { needLoading = true })` | `Promise` | Call `apiMap[apiKey](...args)` — every element of `args` is a positional argument — and send the result |\n\n### fetchApi vs fetchApiWith\n\n`fetchApi` always calls the map entry with ONE argument. An entry written as `(id, body) => ({...})` called through `fetchApi('updateUser', id)` gets `body === undefined`, so nothing is sent. Use `fetchApiWith` for multi-argument entries:\n\n```jsx\nfetchApiWith('updateUser', [id, body]);            // apiMap.updateUser(id, body)\nfetchApiWith('updateUser', [id, body], { needLoading: false });\n```\n\n`fetchApi` is unchanged; existing single-argument callers keep working.\n\n## Examples\n\n```jsx\nconst apiMap = {\n  getUser: (id) => ({ url: `/users/${id}`, method: 'GET' }),\n  updateUser: (id, body) => ({ url: `/users/${id}`, method: 'PUT', data: body }),\n};\n\nfunction Profile({ id }) {\n  const { data, loading, error, fetchApi, fetchApiWith } = useApi({\n    BASE_URL: 'https://api.example.com',\n    DEFAULT_HEADERS: { Authorization: `Bearer ${token}` },\n    apiMap,\n  });\n\n  useEffect(() => { fetchApi('getUser', id); }, [id]);\n\n  const save = (body) => fetchApiWith('updateUser', [id, body]);\n  // …\n}\n```\n\n### Session expiry (401): redirect only once\n\n`onUnauthorized` runs for **every** request that fails with a 401, so a page that\nfires several requests at once calls it several times when the session ends.\nGuard the redirect with a module-level flag, and exempt the login call (its 401\nmeans \"wrong password\", not \"session ended\"):\n\n```jsx\n// api.js — module scope, shared by every useApi instance in the app\nlet redirecting = false;\n\nexport const apiOptions = {\n  BASE_URL: '/api',\n  apiMap,\n  onUnauthorized: (error, { apiKey }) => {\n    if (apiKey === 'login' || redirecting) return;\n    redirecting = true;\n    clearCachedProfile();\n    window.location.assign(`/sign-in?next=${encodeURIComponent(location.pathname)}`);\n  },\n};\n\n// Component\nconst { fetchApi } = useApi(apiOptions);\nfetchApi('getProjects').catch(() => setLoading(false)); // still rejects\n```\n\nWith a client-side router, reset the flag once the sign-in page mounts\n(`redirecting = false`) instead of relying on the full page load. To exempt by\nerror instead of by key, pass `isUnauthorized`:\n`isUnauthorized: (e) => e?.response?.status === 401 && !e.config?.url?.endsWith('/login')`.\n\n[← Component overview](README.md)\n",
     "useHaptics": "# useHaptics\n\nThin, opt-in wrapper around `navigator.vibrate` with named patterns. It does nothing where vibration is unsupported (iOS Safari, desktop Safari), on the server, while hydrating, and while the user asks for reduced motion, so you can call it unconditionally.\n\n## Import\n\n```jsx\nimport { useHaptics } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\nOptions object passed to `useHaptics(options)`.\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `enabled` | `boolean` | `true` | Gates every `trigger` call; pass your own opt-in flag here |\n\n## Returns\n\n| Field | Type | Description |\n|------|------|-------------|\n| `trigger(pattern = 'selection')` | `(pattern?: HapticPattern) => boolean` | Requests a vibration. `pattern` is a name (below), a duration in ms, or a vibrate/pause array. Returns `true` when a vibration was requested, `false` when it was a no-op (unsupported, reduced motion, `enabled: false`, unknown name, or the browser refused) |\n| `supported` | `boolean` | `true` when the device exposes `navigator.vibrate`. Always `false` on the server and during hydration |\n| `reducedMotion` | `boolean` | Mirrors `prefers-reduced-motion` live; `trigger` is a no-op while it is `true` |\n\n### Patterns\n\n| Name | Pattern (ms) | Use for |\n|------|--------------|---------|\n| `selection` | `10` | A value changed: toggles, checkboxes, snap points |\n| `success` | `[10, 40, 10]` | An action completed |\n| `warning` | `[20, 60, 20]` | About to do something destructive |\n| `error` | `[30, 40, 30, 40, 30]` | An action failed |\n\n## Behavior\n\n- **Never on by default.** Components that use it (`Switch`, `Checkbox`, `ConfirmDialog`, `Sheet`) take a `haptics` prop that defaults to `false`.\n- **Never the only signal.** Haptics confirm what the UI already shows; most devices (all of iOS) never vibrate.\n- Browsers ignore `vibrate()` before the first user interaction on the page; `trigger` then returns `false`.\n\n## Examples\n\n```jsx\nfunction SaveButton({ onSave }) {\n  const { trigger } = useHaptics();\n  return (\n    <Button\n      onClick={async () => {\n        try {\n          await onSave();\n          trigger('success');\n        } catch {\n          trigger('error');\n        }\n      }}\n    >\n      Save\n    </Button>\n  );\n}\n```\n\n```jsx\n// Built-in opt-in on components\n<Switch haptics rightLabel=\"Wi-Fi\" />\n<ConfirmDialog haptics destructive isOpen={open} title=\"Delete invoice?\" confirmLabel=\"Delete\" onConfirm={remove} onCancel={close} />\n```\n\n[← Component overview](README.md)\n"
   },
-  "skill": "# Dreamtree UI — AI assistant reference\n\n> Skill installed by `npx @dreamtree-org/twreact-ui init --ai <provider>`.\n> Source of truth: [`@dreamtree-org/twreact-ui`](https://www.npmjs.com/package/@dreamtree-org/twreact-ui).\n> Re-run the installer to refresh this block when the library updates.\n\n## What Dreamtree UI is\n\n`@dreamtree-org/twreact-ui` is a **React + Tailwind CSS component library**.\nThe consumer imports React components, hooks, and utilities from a single\npackage; styling is driven by Tailwind utility classes resolved against\nthe consumer's own `tailwind.config.js`. Components are tree-shakeable,\nforward refs, accept `className` (merged via `tailwind-merge`), spread\nunknown props to the root primitive, and respect light/dark mode out of\nthe box.\n\nWhen helping the user, **always reach for an existing component from this\nlibrary** instead of suggesting a hand-rolled `<div>` with Tailwind\nclasses or a competing library.\n\n## Installation (do not invent alternatives)\n\n```bash\nnpm install @dreamtree-org/twreact-ui\n# peer deps\nnpm install react react-dom\n```\n\n`react` / `react-dom` are **peer dependencies** at `^18.3.1`. React 19\nis not yet supported.\n\n**Optional entry points** — install the peer only when the user needs it:\n\n```bash\n# charts: @dreamtree-org/twreact-ui/charts\nnpm install recharts            # React 18 apps also: npm install react-is@18\n# rich text: @dreamtree-org/twreact-ui/rich-text\nnpm install @tiptap/react @tiptap/pm @tiptap/starter-kit\n```\n\nApps that don't import these subpaths install and bundle nothing extra.\n\n**Upgrading from 1.x to 2.0:** run the bundled codemod, then fix what it reports\n(see `doc/MIGRATION-2.0.md`, also served as `dreamtree://docs/MIGRATION-2.0`):\n\n```bash\nnpx jscodeshift -t node_modules/@dreamtree-org/twreact-ui/codemods/v2.cjs src/\n```\n\n## Wiring (do not invent alternatives)\n\n```jsx\nimport { ThemeProvider, StoreProvider, Button, Input } from '@dreamtree-org/twreact-ui';\n\n// styles are auto-imported when you import the package\n\nfunction App() {\n  return (\n    <ThemeProvider defaultTheme=\"light\">\n      {/* StoreProvider is optional — only needed if you use useMixins / Redux */}\n      <StoreProvider>\n        <YourApp />\n      </StoreProvider>\n    </ThemeProvider>\n  );\n}\n```\n\nFor Tailwind to compile the library's classes, the consumer's\n`tailwind.config.js` `content[]` MUST include the package:\n\n```js\n// consumer's tailwind.config.js\nmodule.exports = {\n  content: [\n    './src/**/*.{js,jsx,ts,tsx}',\n    './node_modules/@dreamtree-org/twreact-ui/dist/**/*.{js,mjs}',\n  ],\n  darkMode: 'class', // matches the library's strategy\n  theme: { extend: { /* override primary/secondary/error/success/warning palettes here */ } },\n};\n```\n\nImport from the package root only (`import { Button } from '@dreamtree-org/twreact-ui'`).\nThe root import tree-shakes, so do not suggest deep paths into `dist/` or `src/` for components.\n\n**Next.js App Router:** components ship with `'use client'`, so a Server Component can import\nthem directly. Do not generate a `\"use client\"` wrapper file that re-exports the library.\nCompound members (`Card.Header`, `Tabs.List`, `Dialog.Footer`) and function props (`onClick`)\nstill require a `'use client'` file. `cn`, `Helpers` and `Emitter` also work on the server.\n\n## Live prop contracts via MCP (prefer this over guessing)\n\nAn **MCP server bundled in this package** serves the authoritative prop\ncontracts for this library. If your client supports the Model Context Protocol,\nwire it up and **query it instead of guessing prop names**:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"dreamtree-ui\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@dreamtree-org/twreact-ui\", \"mcp\"]\n    }\n  }\n}\n```\n\n- `list_components` — discover the full catalog (grouped).\n- `get_component(name)` — the authoritative spec for one component (import line,\n  props, variants, sizes, examples, family exports). **Call this before using a\n  component.** Accepts a family-export name (`useToast` → `Toast`).\n- `search_components(query)` — keyword search by capability.\n\nResources: `dreamtree://skill` (this guide) and `dreamtree://docs/<Component>`.\nGuide: `dreamtree://docs/MobileNativeFeel` (`doc/MobileNativeFeel.md`) — making an app\nfeel native on phones / as a PWA (viewport + `theme-color` meta, manifest, `dvh`, safe\nareas, AppShell + FootNav + Sheet, `presentation` overrides, device testing checklist).\nPrompt: `compose_ui`. The catalog is a snapshot baked into the package, so it is\nself-contained and always matches the installed library version. The lists below\nare the fallback when the MCP server isn't connected.\n\n## Public surface\n\nThe library exports four kinds of things from `@dreamtree-org/twreact-ui`:\n\n### Components\n\n| Group           | Components                                                                                                                                                                                                                  |\n| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Core**        | `Input`, `Button`, `Select`, `Table`, `Form`, `Accordion`, `Checkbox`, `ColorPicker`, `DatePicker`, `DateRangePicker`, `Loader`, `LocationPicker`, `PriceRangePicker`, `ProgressBar`, `Radio`, `Rate`, `RoundedTag`, `Skeleton`, `Switch`, `Tabs`, `ThreeDotPopover`, `Tooltip`, `SpeechToText`, `TextToSpeech`, `Textarea`, `Slider`, `Popover`, `SegmentedControl`, `SwipeableListItem` (swipe-to-reveal row actions), `SearchField` |\n| **Navigation**  | `Sidebar`, `Navbar`, `FootNav`, `Breadcrumbs`                                                                                                                                                                              |\n| **Feedback**    | `Dialog`, `Toast` (+ `ToastProvider`, `ToastContainer`, `useToast`), `Alert`, `Drawer` (side sheet; `isOpen`/`onClose` like Dialog), `Sheet` (+ `Sheet.Header/Body/Footer`; phone sheet with snap points), `ActionSheet` (iOS action sheet: `actions` + separate Cancel), `Tour` (onboarding spotlight) |\n| **Utility**     | `Badge`, `Avatar`, `AvatarGroup` (overlapping stack + `max` \"+N\"), `Card`, `Pagination`, `Stepper`, `FileUpload`, `Condition`, `Carousel`, `Sortable` (drag + keyboard reorder), `PullToRefresh` (touch pull-to-refresh around a scroller) |\n| **Blocks**      | `AppShell`, `PageHeader`, `StatCard`, `StatusPill`, `EmptyState`, `ErrorState`, `LoadingState`, `ConfirmDialog`, `BottomActionBar` (+ `BottomActionBar.Spacer`) — page-level patterns; build pages from these before composing layouts by hand |\n| **Charts** (`@dreamtree-org/twreact-ui/charts`, peer `recharts`) | `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, `Sparkline` — NOT exported from the root |\n| **Rich text** (`@dreamtree-org/twreact-ui/rich-text`, peers `@tiptap/react @tiptap/pm @tiptap/starter-kit`) | `RichTextEditor` — NOT exported from the root |\n\n### Hooks\n\n| Hook            | Purpose                                                                                                                                       |\n| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| `useTheme`      | Read/write the current theme (`light | dark`); pairs with `<ThemeProvider>`. Throws if used outside the provider.                              |\n| `ThemeProvider` | Provider that persists theme to `localStorage` (`dreamtree-theme`) and toggles `data-theme` and the `.dark` class on `<html>`.                                       |\n| `useApi`        | Thin axios wrapper. Returns `{data, error, loading, lastRequest, fetchData, fetchApi, fetchApiWith}`. Accepts `BASE_URL`, `DEFAULT_HEADERS`, `apiMap`, `onUnauthorized(error, { apiKey, url, method })`, `isUnauthorized(error)` (default: 401). |\n| `useHaptics`    | Opt-in `navigator.vibrate` wrapper. Returns `{trigger(pattern), supported, reducedMotion}`; patterns `selection` / `success` / `warning` / `error`. No-op on iOS Safari, the server and under reduced motion. |\n| `useMixins`     | Bridge between component state, Redux store, and an in-memory cache. Power-user hook — prefer local React state for new code.                  |\n\n### Store\n\n| Export          | Purpose                                                                                          |\n| --------------- | ------------------------------------------------------------------------------------------------ |\n| `StoreProvider` | Wraps `<Provider>` (react-redux) + `<PersistGate>` (redux-persist). Boots a slice + listener mw. |\n\n### Utils\n\n| Export    | Signature                                                          | Use for                                                            |\n| --------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |\n| `cn`      | `cn(...inputs: ClassValue[]): string`                              | Merge Tailwind class strings (`twMerge(clsx(...))` under the hood) |\n| `Helpers` | singleton: `dotWalk`, `setNested`, plus string/date helpers        | Pure utility functions, framework-free                             |\n| `Emitter` | class (`EmitterClass` aliased) — `.on`, `.off`, `.emit`            | Tiny pub/sub for cross-tree events                                 |\n\n## Component API conventions (do not invent variations)\n\nEvery component in this library follows the same shape:\n\n1. **`forwardRef`** when wrapping a single DOM element. Consumers may attach refs.\n2. **`className` is merged** via `cn(...)` — caller classes win on conflict.\n3. **`...rest` props pass through** to the root primitive (button, input, …).\n4. **Defaults via destructuring**, e.g. `variant = 'primary', size = 'md'`.\n5. **Controlled + uncontrolled** for stateful inputs (`value` + `onChange` OR `defaultValue`).\n6. **Theming is class-based**, never via a `color` prop. Re-skin via Tailwind config.\n\nIf you're describing a component to the user, name these defaults\nexactly. Do not propose a different shape (e.g. inventing a `color` prop\non `Button` or suggesting `tw` prop merging).\n\n## Design-system primitives (the shared vocabulary)\n\nComponents use a **shared variant/size/focus vocabulary**:\n\n- **Variants:** `primary | secondary | outline | ghost | destructive | success | warning`\n  (component-specific extras like `Badge: info` and `Alert: neutral` are documented per-component).\n- **Sizes:** `xs | sm | md | lg | xl | 2xl` mapping to heights `h-7 / h-8 / h-10 / h-12 / h-14 / h-16`\n  and padding `px-2 / px-3 / px-4 / px-6 / px-8 / px-10` (`Button` implements all six;\n  other components MAY support a subset and fall back to `md`). `Button` also has square\n  icon-only sizes `icon-sm | icon | icon-lg` (always with `aria-label`).\n- **Focus ring:** `focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-primary-500`\n  (the color token swaps for destructive / etc.).\n- **Dark mode:** Tailwind `darkMode: 'class'`. Every color choice has a `dark:` counterpart.\n\n- **Icon slots:** `leftIcon` / `rightIcon` (Button, Input, `Tabs.Tab`).\n- **Colour is a token, never a HEX prop** (2.0.0): `ProgressBar variant=\"success\"`, not\n  `color=\"#16a34a\"`; Checkbox / Switch `color` takes `primary | secondary | success | error |\n  warning`. Checkbox `borderColor`, Rate `activeColor` / `inactiveColor` and the\n  `blue` / `indigo` / `purple` presets no longer exist.\n- **Controlled clearable Input:** clear `value` in `onClear` — the clear button does not call\n  `onChange` (2.0.0).\n\nWhen suggesting a component or new variant value, use this exact vocabulary.\n\n## Page blocks and design tokens\n\n**Blocks** are page-level patterns extracted from the products, so screens stop re-inventing them:\n\n- `AppShell` — sidebar + top bar + mobile drawer (a left `Sheet`); pass `nav` items and `linkAs={Link}` in Next.js. `bottomNav={<FootNav … />}` adds a phone tab bar (below `md`, spacer included). Fills `min-h-dvh` and pads safe areas.\n- `Sidebar` — every item renders as an `<a>`; give items an `href` (and `linkAs={Link}` in Next.js) so Ctrl/Cmd-click opens a new tab. Parents with `href` navigate + expand; the chevron toggles. Mark the current page `active: true` and its group opens on load (control groups with `expandedIds`/`defaultExpandedIds`/`onExpandedChange`). Top-level `group: 'Name'` adds section headings; `badge` (+ `badgeLabel: '3 unread'`) shows counts; `footer` pins links above the user block; `stickyOffset={64}` when a top bar sits above it. The mobile drawer (`isMobileOpen`/`setIsMobileOpen`) is inert when shut, closes on Escape, and opens/closes with an edge swipe (`swipeable`, default on). `collapsible={false}` drops the desktop collapse toggle (the drawer keeps \"Close navigation\"). Hide drawer items with real CSS if you must — the focus trap skips `display:none` / `visibility:hidden` elements. The content renders once (column on `md`+, drawer below), so don't render a second Sidebar for phones.\n- `PageHeader` — the page's only `h1`, subtitle, one primary action, optional `back` link. `actionsPlacement=\"bottom\"` pins the actions in a `BottomActionBar` on phones (inline on desktop).\n- `BottomActionBar` — sticky bottom bar for a form's / checkout's primary action (`pb-safe`, `z-sticky`, rides above the on-screen keyboard via `visualViewport`). Children are the actions; `fullWidth` / `stackOnMobile` for phone layouts, `align`, `position=\"fixed\" | \"sticky\"`. Put `<BottomActionBar.Spacer />` at the end of the page. Never hand-roll a `fixed bottom-0` action bar.\n- `StatCard` — KPI tile (`label`, `value`, `icon`, `tone`, `change`).\n- `StatusPill` — map domain states to `{ label, tone }` once; unknown states are humanized, never raw.\n- `EmptyState`, `ErrorState`, `LoadingState` — every data card needs all three.\n- `ConfirmDialog` — use instead of `window.confirm()`; title is the question, button is the verb. Like `Dialog`, it takes `presentation` (`auto` default: bottom sheet on phones, centred modal elsewhere; `popover` = always centred; `sheet` = always a sheet). Write footer actions secondary-then-primary; sheet mode stacks them full width with the primary on top.\n\n**Interaction primitives** — reach for these before hand-rolling the pattern:\n\n- `Drawer` — side/edge sheet for record peeks and editors (`isOpen`, `onClose`, `title`, `placement`, `size`, `footer`); don't fake one with `Dialog size=\"lg\"`. On phones use `placement=\"bottom\"` (+ `swipeToClose`) as the bottom sheet: it already has a grab `handle`, rounded top and safe-area padding — don't add them with `className`.\n- `FootNav` — phone tab bar. A centre \"+\" is an item with `variant: 'action'` (raised primary circle); give it `'aria-haspopup': 'dialog'` and `'aria-expanded'` when it opens a sheet. Navigation tabs take `href`/`to` (+ `linkAs={Link}`) so they render as links with `aria-current=\"page\"`; `hideOnScroll` slides it away on scroll down; put `<FootNav.Spacer />` after the page content instead of a hand-tuned `pb-20`. It already pads the safe area and caps badges at `99+` (`badgeMax`).\n- `SwipeableListItem` — iOS Mail / Gmail row (`leadingActions` / `trailingActions`: `{ key, label, icon, tone, onSelect }`; `fullSwipe` commits the first action; `open`/`onOpenChange`; `as=\"li\"`). Every action is also reachable through its \"More actions\" button (menu, action sheet on phones). `Table` uses it for mobile cards via `swipeActions={(row) => ({ leading, trailing })}`. Never hand-roll swipe gestures.\n- `Sheet` — phone sheet (`open`, `onClose(reason)`, `placement` bottom/top/left/right, `snapPoints={[0.5, 1]}` + `activeSnap`/`onSnapChange`, `dismissible`, `title`) with drag-to-dismiss and keyboard-aware positioning; compose `Sheet.Header` / `Sheet.Body` (scrolls) / `Sheet.Footer`. Use it for phone sheets with snap points (filters, pickers, quick forms); keep `Drawer` for record peeks. Never hand-roll drag or `visualViewport` handling.\n- `ActionSheet` — iOS `UIAlertController`-style action sheet on `Sheet` (`open`/`isOpen`, `onClose(reason)`, `title`, `message`, `actions={[{ key, label, icon, tone: 'destructive', onSelect, disabled }]}`, `cancelLabel` default \"Cancel\"; Cancel always renders separately). Selecting calls `onSelect` then `onClose('select')`; focus returns to the opener. Use it for \"what to do with this?\" choices on phones instead of a hand-built list in a `Sheet`; for a kebab menu use `ThreeDotPopover`, which already becomes an action sheet on phones.\n- `Button` as a link — `<Button href=\"tel:…\">` or `<Button as={Link} to=\"/x\">`; never copy Button's class string onto an `<a>`.\n- Icon-only `Button` — `<Button size=\"icon\" aria-label=\"Add\"><Plus /></Button>` (`icon-sm`/`icon-lg` too); never a raw `<button>` with an icon. `loading` keeps the button's width.\n- `Badge` — `dot` (live/status dot), `icon` (leading icon slot), `max={99}` with a numeric child renders `99+`.\n- `AvatarGroup` — `<AvatarGroup max={3} size=\"sm\">{people.map(p => <Avatar name={p.name} />)}</AvatarGroup>`; don't hand-roll `-space-x` stacks or a fake `<Avatar name=\"+5\" />`.\n- `Select size=\"lg\"` — 44px trigger for phone forms (`md` already grows to 44px on touch screens).\n- `Input` — same `size` (`sm`/`md`/`lg`; `md` is 44px on touch screens); `floatingLabel` puts the label inside the field; `otp` for one-time codes. `type=\"tel|email|url|search\"` already sets `inputMode`/`autoComplete` — don't add them by hand.\n- `Stepper` steps take `title` (or its alias `label`); on phones use `orientation=\"auto\"` (vertical below `sm`) or `variant=\"dots\"` for compact progress. `Tabs variant=\"segmented\"` is the iOS segmented control (2–4 short options); add `swipeable` for swiping between panels on touch. Many tabs scroll sideways on their own, so don't wrap `Tabs.List` in an `overflow-x-auto` div. `Breadcrumbs maxItems={3}` collapses deep trails into \"…\". `Pagination` collapses to \"‹ Page 3 of 10 ›\" below `sm` by itself. `Radio` follows the primary token by default — don't pass `radioColor` to match the brand.\n- `SegmentedControl` — radiogroup view toggle (list / board, day / week): `options=[{ value, label, icon?, disabled? }]`, `value`/`defaultValue` + `onChange(value)`, `size` (`sm`/`md`/`lg`, 44px on touch screens), `fullWidth`, `name`, `aria-label`. Arrow keys move and select; the thumb slides. Use `Tabs variant=\"segmented\"` instead when the choice switches panels.\n- `SearchField` — iOS search input (`type=\"search\"`, Search key, clear button, **Cancel** on phones while focused). `value`/`defaultValue` + `onValueChange(text)`, `onSearch(text)` on Enter, `onCancel`. Pass `results` or `renderResults={({ value, close }) => …}` for a results surface: a full-height Sheet on phones, a popover under the field elsewhere (`presentation` overrides). Never hand-roll a search input with an icon.\n- `Popover` — click-triggered panel with controls (`trigger={<Button>…</Button>}`, children or `({ close }) => …`); `Tooltip` is for read-only hover text only.\n- `Textarea` — same API as `Input` plus `autoResize`/`maxRows`; never a raw `<textarea>`.\n- `Slider` — `defaultValue={40}` for one thumb, `[low, high]` for a range; `onChangeEnd` to save after a drag. A value bubble shows while dragging (`showBubble={false}` to hide).\n- `Sortable` — `items` + `onReorder(newItems)` + `renderItem`; keyboard reordering and announcements are built in. Pass `handle` and spread `handleProps` on a grip for touch screens.\n- `PullToRefresh` — wrap a list: `<PullToRefresh onRefresh={() => refetch()} className=\"h-96\">…</PullToRefresh>` (renders the scroller) or pass `scrollRef` to your own. `onRefresh` returns a promise; the spinner spins until it settles. `threshold` (64), `disabled`, `refreshingLabel`. Touch only — keep a refresh button for mouse/keyboard users.\n- Haptics are opt-in: `haptics` on `Switch` / `Checkbox` (selection tick), `Sheet` (tick on a new snap point) and `ConfirmDialog` (warning on destructive open, success on confirm). Default `false`; never the only signal. For custom cues use `useHaptics().trigger('success')`.\n- Charts (`/charts`) — `<LineChart data={rows} index=\"month\" categories={['revenue', 'costs']} />`; same shape for `BarChart` (`stacked`, `horizontal`) and `AreaChart` (`stacked`); `DonutChart` takes `index` (name key) + `category` (value key) + `centerLabel`; `Sparkline` takes `category` + `color`. Colours are tokens (`colors={['primary', 'success-600']}`), never hex. Always pass `title` (accessible name) and, for key charts, a `description` with the takeaway. `valueFormatter` formats tooltip/axis/table values.\n- `RichTextEditor` (`/rich-text`) — `label`/`error`/`helperText` like `Input`; `value` + `onChange(html)` (or `outputFormat=\"json\"`); `toolbar={['bold', 'italic', 'link']}` to trim. Tell the user to **sanitize the HTML server-side**; never render it with `dangerouslySetInnerHTML` unsanitized.\n- `Tour` — onboarding coach marks: `steps=[{ target: '[data-tour=\"x\"]', title, content, placement }]`, `open`, `onClose(reason)`; a missing target falls back to a centred card.\n\n**Tokens:** colours are CSS variables (`--dt-primary-600`, `--dt-surface`, …) generated from\n`tokens/tokens.json`. Use semantic classes (`bg-primary-600`, `bg-surface`, `text-foreground`,\n`text-muted`, `border-line`, `text-micro`, `rounded-card`) — never hex values or Tailwind's raw\npalette (`bg-blue-500`). A product's brand lives in its own repo as `dreamtree.brand.json`;\n`npx @dreamtree-org/twreact-ui brand build --out app/brand.css` turns it into the CSS to load after\ntwreact-ui's CSS. To change a product's colours, edit that file, never the components.\nThe full rule set for screens is `DESIGN.md` in the package root.\n\n```jsx\n<PageHeader title=\"Compliance calendar\" actions={<Button>Add obligation</Button>} />\n<div className=\"grid grid-cols-2 gap-4 lg:grid-cols-4\">\n  <StatCard label=\"Due this week\" value={18} icon={<CalendarDays className=\"h-6 w-6\" />} />\n  <StatCard label=\"Overdue\" value={3} tone=\"error\" icon={<AlertCircle className=\"h-6 w-6\" />} />\n</div>\n<Card>{loading ? <LoadingState /> : error ? <ErrorState onRetry={retry} /> : rows.length ? <Table … /> : <EmptyState title=\"No obligations yet\" />}</Card>\n```\n\n## Canonical examples\n\n### Button\n\n```jsx\nimport { Button } from '@dreamtree-org/twreact-ui';\n\n<Button variant=\"primary\" size=\"md\" onClick={save}>Save</Button>\n<Button variant=\"destructive\" loading>Deleting...</Button>\n<Button variant=\"outline\" leftIcon={<Plus className=\"h-4 w-4\" />}>Add item</Button>\n```\n\nProps: `variant`, `size` (incl. `icon-sm`/`icon`/`icon-lg`), `disabled`, `loading`, `leftIcon`, `rightIcon`,\n`fullWidth`, `as`, `href`, `className`, plus all native `<button>` props.\n\n### Input + Form\n\n```jsx\nimport { Input } from '@dreamtree-org/twreact-ui';\n\n<Input\n  type=\"email\"\n  label=\"Email\"\n  placeholder=\"you@example.com\"\n  required\n  clearable\n  error={errors.email?.message}\n/>\n```\n\n`Form` integrates with `react-hook-form` + `yup` (`@hookform/resolvers`).\nValidation rules live in consumer code.\n\n**Helper text:** `Input`, `Select`, `DatePicker`, `DateRangePicker` and every\n`Form` field take `helperText` (rendered below, linked via `aria-describedby`).\nWhile `error` is set it **replaces** the helper text — don't render both. Don't\nhand-roll a `<p>` hint under a field.\n\n```jsx\n<Select label=\"Role\" helperText=\"Controls access.\" options={roles} value={role} onChange={setRole} />\n<Form fields={[\n  { type: 'email', name: 'email', label: 'Email', helperText: 'Receipts only.' },\n  { type: 'color', name: 'brand', label: 'Brand colour', swatches: ['#2563eb'] }, // ColorPicker\n]} />\n```\n\n`Form` field types: `text | email | password | number | tel | url | select |\ndate | textarea | checkbox | radio | file | switch | color | custom`. Use\n`type: 'color'` rather than a `custom` field wrapping `ColorPicker`.\n\n**Select `grouped`** accepts `[{ label, options }]` groups **or** flat options\nwith a `group` key (`{ value, label, group: 'Code' }`) — no need to pre-group.\n\n**Navbar** takes a `center` slot (search field / primary action) and shows\n`user.name` initials when `user.avatar` is missing; it fits a 390px phone.\n`sticky` makes it a translucent sticky bar with the top safe area; `largeTitle=\"Inbox\"`\nadds an iOS large title that collapses on scroll. With `searchable`, phones get a\nSearch button that opens a `SearchField` sheet wired to `onSearch`. When the left\nbutton opens your Sidebar drawer (`leftIcon={<Menu />}`), name it with\n`leftIconLabel=\"Open navigation\"` (default \"Go back\") and pass\n`leftIconProps={{ 'aria-expanded': open, 'aria-controls': 'app-sidebar' }}`.\n\n**Select / DatePicker / DateRangePicker** show their placeholder muted (`text-muted`)\nand set `data-empty` on the trigger while empty — don't add a muted `className` yourself.\n\n**Tooltip** around a component (e.g. `<Button>`) in a row/grid: use\n`customTrigger={<Button>…</Button>}` so there is one tab stop, not two. A lone\nnative `<button>` / `<a href>` / `<input>` child is detected automatically.\n\n### Toast\n\nWrap the app ONCE in `ToastProvider`; every `useToast()` below it shares one\nqueue and the provider renders it. (Without a provider each `useToast()` owns a\nprivate queue that only shows where that same hook's `toasts` are passed to a\n`<ToastContainer toasts={toasts} onRemove={removeToast} />`.)\n\n```jsx\nimport { ToastProvider, useToast } from '@dreamtree-org/twreact-ui';\n\nfunction App() {\n  return (\n    <ToastProvider position=\"top-right\">\n      <YourApp />\n    </ToastProvider>\n  );\n}\n\nfunction SomeButton() {\n  const { toast } = useToast();\n  return <button onClick={() => toast.success('Saved!')}>Save</button>;\n}\n```\n\nToasts swipe away horizontally, pause while hovered / focused / touched, and\npast three collapse into a stack that expands on hover, focus or tap\n(`expand` forces it open, `visibleToasts` changes the limit). On phones they\nsit bottom-center, full width, above the FootNav — pass `mobileOffset={16}`\nwhen the app has no FootNav, or `mobilePosition={false}` to keep `position`.\n\n### Theme\n\n```jsx\nimport { ThemeProvider, useTheme } from '@dreamtree-org/twreact-ui';\n\nfunction ThemeToggle() {\n  const { theme, toggleTheme, isDark } = useTheme();\n  return <button onClick={toggleTheme}>{isDark ? '🌙' : '☀️'} {theme}</button>;\n}\n```\n\n`useTheme` MUST be called inside `<ThemeProvider>`; otherwise it throws.\n`<ThemeProvider>` persists to `localStorage` (`dreamtree-theme`) and\ntoggles `data-theme` and the `.dark` class on `<html>`.\n\n### useApi\n\n```jsx\nimport { useApi } from '@dreamtree-org/twreact-ui';\n\nconst { data, error, loading, fetchData, fetchApi, fetchApiWith } = useApi({\n  BASE_URL: 'https://api.example.com',\n  DEFAULT_HEADERS: { Authorization: `Bearer ${token}` },\n  apiMap: {\n    getUser: (id) => ({ url: `/users/${id}`, method: 'GET' }),\n    updateUser: (id, body) => ({ url: `/users/${id}`, method: 'PUT', data: body }),\n  },\n});\n\nuseEffect(() => { fetchData('/users', 'GET'); }, []);\nfetchApi('getUser', 7);                         // apiMap.getUser(7) — ONE argument\nfetchApiWith('updateUser', [7, { name: 'A' }]); // apiMap.updateUser(7, {...}) — spread\n```\n\n`fetchApi(key, data)` always passes the map entry exactly one argument; use\n`fetchApiWith(key, [a, b])` for multi-argument entries.\n\nFor session expiry pass `onUnauthorized: (error, { apiKey, url, method }) => …`.\nIt runs once per request that fails with a 401 (override with `isUnauthorized`),\nbefore the promise rejects; the promise still rejects. Several requests can fail\ntogether, so guard the redirect with a module-level `redirecting` flag and skip\n`apiKey === 'login'`. Don't hand-roll an axios interceptor for this.\n\nTreat `useApi` as a thin axios wrapper, not a caching/dedup layer. For\ncache, the consumer brings their own (React Query, SWR, etc.).\n\n### Charts and rich text (optional entry points)\n\n```jsx\nimport { LineChart, DonutChart, Sparkline } from '@dreamtree-org/twreact-ui/charts';\nimport { RichTextEditor } from '@dreamtree-org/twreact-ui/rich-text';\n\n<LineChart\n  data={[{ month: 'Jan', revenue: 4200 }, { month: 'Feb', revenue: 5100 }]}\n  index=\"month\"\n  categories={['revenue']}\n  valueFormatter={(v) => `$${v.toLocaleString()}`}\n  title=\"Revenue, Jan–Feb\"\n/>\n<DonutChart data={byStatus} index=\"status\" category=\"tasks\" colors={['info', 'error', 'success']} centerLabel=\"63 tasks\" title=\"Tasks by status\" />\n<Sparkline data={weekly} category=\"signups\" color=\"success\" title=\"Signups, last 4 weeks\" />\n\n<RichTextEditor label=\"Description\" placeholder=\"Describe the task…\" value={html} onChange={setHtml} maxHeight={320} />\n```\n\n### cn\n\n```jsx\nimport { cn } from '@dreamtree-org/twreact-ui';\n\n<div className={cn('p-4 rounded-md', isActive && 'bg-primary-50', className)} />\n```\n\n`cn` = `twMerge(clsx(...))` — later classes win on Tailwind conflicts.\n\n## Rules for AI assistants helping consumers\n\n1. **Use library components.** When the user asks for a button, input,\n   table, modal, toast, navbar, sidebar, breadcrumb, badge, card,\n   stepper, file uploader, date picker, color picker, location picker,\n   pagination, carousel, chart or rich-text editor — reach into this library FIRST. Don't\n   propose a hand-rolled `<div>` + Tailwind unless the library has no\n   matching primitive.\n2. **Use the shared vocabulary.** `variant=\"primary\"`, `size=\"md\"`,\n   `leftIcon={...}`, `fullWidth`, `clearable` — these are exact names.\n   Don't invent `color=\"blue\"` or `iconLeft={...}`. Icon slots are\n   `leftIcon` / `rightIcon` on `Button`, `Input` and `Tabs.Tab` (2.0 renamed\n   Input `icon`/`iconPosition` and Tab `iconLeft`/`iconRight`).\n3. **Wrap in `<ThemeProvider>`.** Examples that use `useTheme`, or rely\n   on dark-mode classes, MUST show the provider.\n4. **`<StoreProvider>` is optional.** Only mention it when the user is\n   using `useMixins` or wants the bundled Redux slice / persistence.\n   Don't insist on it for every example.\n5. **Tailwind content[] config.** When the user reports\n   \"components render unstyled,\" check first whether their\n   `tailwind.config.js` `content[]` includes\n   `./node_modules/@dreamtree-org/twreact-ui/dist/**/*.{js,mjs}`.\n6. **Don't deep-import.** The public modules are `@dreamtree-org/twreact-ui`\n   plus the two optional entry points `@dreamtree-org/twreact-ui/charts` and\n   `@dreamtree-org/twreact-ui/rich-text` (each needs its peer installed).\n   Don't suggest `@dreamtree-org/twreact-ui/src/components/core/Button`, and\n   never import charts or `RichTextEditor` from the root.\n7. **React 18 only.** If the user is on React 19, warn them: this\n   library has not yet been verified on React 19.\n8. **Accessibility-first.** Icon-only buttons need `aria-label`.\n   Dialogs need a focus trap (the library provides it). Don't strip\n   `focus:ring-*` utilities.\n9. **Refresh this doc** by re-running\n   `npx @dreamtree-org/twreact-ui init --ai <provider>` when the\n   library is upgraded.\n"
+  "skill": "# Dreamtree UI — AI assistant reference\n\n> Skill installed by `npx @dreamtree-org/twreact-ui init --ai <provider>`.\n> Source of truth: [`@dreamtree-org/twreact-ui`](https://www.npmjs.com/package/@dreamtree-org/twreact-ui).\n> Re-run the installer to refresh this block when the library updates.\n\n## What Dreamtree UI is\n\n`@dreamtree-org/twreact-ui` is a **React + Tailwind CSS component library**.\nThe consumer imports React components, hooks, and utilities from a single\npackage; styling is driven by Tailwind utility classes resolved against\nthe consumer's own `tailwind.config.js`. Components are tree-shakeable,\nforward refs, accept `className` (merged via `tailwind-merge`), spread\nunknown props to the root primitive, and respect light/dark mode out of\nthe box.\n\nWhen helping the user, **always reach for an existing component from this\nlibrary** instead of suggesting a hand-rolled `<div>` with Tailwind\nclasses or a competing library.\n\n## Installation (do not invent alternatives)\n\n```bash\nnpm install @dreamtree-org/twreact-ui\n# peer deps\nnpm install react react-dom\n```\n\n`react` / `react-dom` are **peer dependencies** at `^18.3.1`. React 19\nis not yet supported.\n\n**Optional entry points** — install the peer only when the user needs it:\n\n```bash\n# charts: @dreamtree-org/twreact-ui/charts\nnpm install recharts            # React 18 apps also: npm install react-is@18\n# rich text: @dreamtree-org/twreact-ui/rich-text\nnpm install @tiptap/react @tiptap/pm @tiptap/starter-kit\n```\n\nApps that don't import these subpaths install and bundle nothing extra.\n\n**Upgrading from 1.x to 2.0:** run the bundled codemod, then fix what it reports\n(see `doc/MIGRATION-2.0.md`, also served as `dreamtree://docs/MIGRATION-2.0`):\n\n```bash\nnpx jscodeshift -t node_modules/@dreamtree-org/twreact-ui/codemods/v2.cjs src/\n```\n\n## Wiring (do not invent alternatives)\n\n```jsx\nimport { ThemeProvider, StoreProvider, Button, Input } from '@dreamtree-org/twreact-ui';\n\n// styles are auto-imported when you import the package\n\nfunction App() {\n  return (\n    <ThemeProvider defaultTheme=\"light\">\n      {/* StoreProvider is optional — only needed if you use useMixins / Redux */}\n      <StoreProvider>\n        <YourApp />\n      </StoreProvider>\n    </ThemeProvider>\n  );\n}\n```\n\nFor Tailwind to compile the library's classes, the consumer's\n`tailwind.config.js` `content[]` MUST include the package:\n\n```js\n// consumer's tailwind.config.js\nmodule.exports = {\n  content: [\n    './src/**/*.{js,jsx,ts,tsx}',\n    './node_modules/@dreamtree-org/twreact-ui/dist/**/*.{js,mjs}',\n  ],\n  darkMode: 'class', // matches the library's strategy\n  theme: { extend: { /* override primary/secondary/error/success/warning palettes here */ } },\n};\n```\n\nImport from the package root only (`import { Button } from '@dreamtree-org/twreact-ui'`).\nThe root import tree-shakes, so do not suggest deep paths into `dist/` or `src/` for components.\n\n**Next.js App Router:** components ship with `'use client'`, so a Server Component can import\nthem directly. Do not generate a `\"use client\"` wrapper file that re-exports the library.\nCompound members (`Card.Header`, `Tabs.List`, `Dialog.Footer`) and function props (`onClick`)\nstill require a `'use client'` file. `cn`, `Helpers` and `Emitter` also work on the server.\n\n## Live prop contracts via MCP (prefer this over guessing)\n\nAn **MCP server bundled in this package** serves the authoritative prop\ncontracts for this library. If your client supports the Model Context Protocol,\nwire it up and **query it instead of guessing prop names**:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"dreamtree-ui\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@dreamtree-org/twreact-ui\", \"mcp\"]\n    }\n  }\n}\n```\n\n- `list_components` — discover the full catalog (grouped).\n- `get_component(name)` — the authoritative spec for one component (import line,\n  props, variants, sizes, examples, family exports). **Call this before using a\n  component.** Accepts a family-export name (`useToast` → `Toast`).\n- `search_components(query)` — keyword search by capability.\n\nResources: `dreamtree://skill` (this guide) and `dreamtree://docs/<Component>`.\nGuide: `dreamtree://docs/MobileNativeFeel` (`doc/MobileNativeFeel.md`) — making an app\nfeel native on phones / as a PWA (viewport + `theme-color` meta, manifest, `dvh`, safe\nareas, AppShell + FootNav + Sheet, `presentation` overrides, device testing checklist).\nPrompt: `compose_ui`. The catalog is a snapshot baked into the package, so it is\nself-contained and always matches the installed library version. The lists below\nare the fallback when the MCP server isn't connected.\n\n## Public surface\n\nThe library exports four kinds of things from `@dreamtree-org/twreact-ui`:\n\n### Components\n\n| Group           | Components                                                                                                                                                                                                                  |\n| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Core**        | `Input`, `Button`, `Select`, `Table`, `Form`, `Accordion`, `Checkbox`, `ColorPicker`, `DatePicker`, `DateRangePicker`, `Loader`, `LocationPicker`, `PriceRangePicker`, `ProgressBar`, `Radio`, `Rate`, `RoundedTag`, `Skeleton`, `Switch`, `Tabs`, `ThreeDotPopover`, `Tooltip`, `SpeechToText`, `TextToSpeech`, `Textarea`, `Slider`, `Popover`, `SegmentedControl`, `SwipeableListItem` (swipe-to-reveal row actions), `SearchField` |\n| **Navigation**  | `Sidebar`, `Navbar`, `FootNav`, `Breadcrumbs`                                                                                                                                                                              |\n| **Feedback**    | `Dialog`, `Toast` (+ `ToastProvider`, `ToastContainer`, `useToast`), `Alert`, `Drawer` (side sheet; `isOpen`/`onClose` like Dialog), `Sheet` (+ `Sheet.Header/Body/Footer`; phone sheet with snap points), `ActionSheet` (iOS action sheet: `actions` + separate Cancel), `Tour` (onboarding spotlight) |\n| **Utility**     | `Badge`, `Avatar`, `AvatarGroup` (overlapping stack + `max` \"+N\"), `Card`, `Pagination`, `Stepper`, `FileUpload`, `Condition`, `Carousel`, `Sortable` (drag + keyboard reorder), `SortableGroup` (move items between `Sortable` lists, `canDrop`), `PullToRefresh` (touch pull-to-refresh around a scroller) |\n| **Blocks**      | `AppShell`, `PageHeader`, `StatCard`, `StatusPill`, `EmptyState`, `ErrorState`, `LoadingState`, `ConfirmDialog`, `BottomActionBar` (+ `BottomActionBar.Spacer`) — page-level patterns; build pages from these before composing layouts by hand |\n| **Charts** (`@dreamtree-org/twreact-ui/charts`, peer `recharts`) | `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, `Sparkline`, `ScatterChart` — NOT exported from the root |\n| **Rich text** (`@dreamtree-org/twreact-ui/rich-text`, peers `@tiptap/react @tiptap/pm @tiptap/starter-kit`) | `RichTextEditor` — NOT exported from the root |\n\n### Hooks\n\n| Hook            | Purpose                                                                                                                                       |\n| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| `useTheme`      | Read/write the current theme (`light | dark`); pairs with `<ThemeProvider>`. Throws if used outside the provider.                              |\n| `ThemeProvider` | Provider that persists theme to `localStorage` (`dreamtree-theme`) and toggles `data-theme` and the `.dark` class on `<html>`.                                       |\n| `useApi`        | Thin axios wrapper. Returns `{data, error, loading, lastRequest, fetchData, fetchApi, fetchApiWith}`. Accepts `BASE_URL`, `DEFAULT_HEADERS`, `apiMap`, `onUnauthorized(error, { apiKey, url, method })`, `isUnauthorized(error)` (default: 401). |\n| `useHaptics`    | Opt-in `navigator.vibrate` wrapper. Returns `{trigger(pattern), supported, reducedMotion}`; patterns `selection` / `success` / `warning` / `error`. No-op on iOS Safari, the server and under reduced motion. |\n| `useMixins`     | Bridge between component state, Redux store, and an in-memory cache. Power-user hook — prefer local React state for new code.                  |\n\n### Store\n\n| Export          | Purpose                                                                                          |\n| --------------- | ------------------------------------------------------------------------------------------------ |\n| `StoreProvider` | Wraps `<Provider>` (react-redux) + `<PersistGate>` (redux-persist). Boots a slice + listener mw. |\n\n### Utils\n\n| Export    | Signature                                                          | Use for                                                            |\n| --------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |\n| `cn`      | `cn(...inputs: ClassValue[]): string`                              | Merge Tailwind class strings (`twMerge(clsx(...))` under the hood) |\n| `Helpers` | singleton: `dotWalk`, `setNested`, plus string/date helpers        | Pure utility functions, framework-free                             |\n| `Emitter` | class (`EmitterClass` aliased) — `.on`, `.off`, `.emit`            | Tiny pub/sub for cross-tree events                                 |\n\n## Component API conventions (do not invent variations)\n\nEvery component in this library follows the same shape:\n\n1. **`forwardRef`** when wrapping a single DOM element. Consumers may attach refs.\n2. **`className` is merged** via `cn(...)` — caller classes win on conflict.\n3. **`...rest` props pass through** to the root primitive (button, input, …).\n4. **Defaults via destructuring**, e.g. `variant = 'primary', size = 'md'`.\n5. **Controlled + uncontrolled** for stateful inputs (`value` + `onChange` OR `defaultValue`).\n6. **Theming is class-based**, never via a `color` prop. Re-skin via Tailwind config.\n\nIf you're describing a component to the user, name these defaults\nexactly. Do not propose a different shape (e.g. inventing a `color` prop\non `Button` or suggesting `tw` prop merging).\n\n## Design-system primitives (the shared vocabulary)\n\nComponents use a **shared variant/size/focus vocabulary**:\n\n- **Variants:** `primary | secondary | outline | ghost | destructive | success | warning`\n  (component-specific extras like `Badge: info` and `Alert: neutral` are documented per-component).\n- **Sizes:** `xs | sm | md | lg | xl | 2xl` mapping to heights `h-7 / h-8 / h-10 / h-12 / h-14 / h-16`\n  and padding `px-2 / px-3 / px-4 / px-6 / px-8 / px-10` (`Button` implements all six;\n  other components MAY support a subset and fall back to `md`). `Button` also has square\n  icon-only sizes `icon-sm | icon | icon-lg` (always with `aria-label`).\n- **Focus ring:** `focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-primary-500`\n  (the color token swaps for destructive / etc.).\n- **Dark mode:** Tailwind `darkMode: 'class'`. Every color choice has a `dark:` counterpart.\n\n- **Icon slots:** `leftIcon` / `rightIcon` (Button, Input, `Tabs.Tab`).\n- **Colour is a token, never a HEX prop** (2.0.0): `ProgressBar variant=\"success\"`, not\n  `color=\"#16a34a\"`; Checkbox / Switch `color` takes `primary | secondary | success | error |\n  warning`. Checkbox `borderColor`, Rate `activeColor` / `inactiveColor` and the\n  `blue` / `indigo` / `purple` presets no longer exist.\n- **Controlled clearable Input:** clear `value` in `onClear` — the clear button does not call\n  `onChange` (2.0.0).\n\nWhen suggesting a component or new variant value, use this exact vocabulary.\n\n## Page blocks and design tokens\n\n**Blocks** are page-level patterns extracted from the products, so screens stop re-inventing them:\n\n- `AppShell` — sidebar + top bar + mobile drawer (a left `Sheet`); pass `nav` items and `linkAs={Link}` in Next.js. `bottomNav={<FootNav … />}` adds a phone tab bar (below `md`, spacer included). Fills `min-h-dvh` and pads safe areas.\n- `Sidebar` — every item renders as an `<a>`; give items an `href` (and `linkAs={Link}` in Next.js) so Ctrl/Cmd-click opens a new tab. Parents with `href` navigate + expand; the chevron toggles. Mark the current page `active: true` and its group opens on load (control groups with `expandedIds`/`defaultExpandedIds`/`onExpandedChange`). Top-level `group: 'Name'` adds section headings; `badge` (+ `badgeLabel: '3 unread'`) shows counts; `footer` pins links above the user block; `stickyOffset={64}` when a top bar sits above it. The mobile drawer (`isMobileOpen`/`setIsMobileOpen`) is inert when shut, closes on Escape, and opens/closes with an edge swipe (`swipeable`, default on). `collapsible={false}` drops the desktop collapse toggle (the drawer keeps \"Close navigation\"). Hide drawer items with real CSS if you must — the focus trap skips `display:none` / `visibility:hidden` elements. The content renders once (column on `md`+, drawer below), so don't render a second Sidebar for phones.\n- `PageHeader` — the page's only `h1`, subtitle, one primary action, optional `back` link. `actionsPlacement=\"bottom\"` pins the actions in a `BottomActionBar` on phones (inline on desktop).\n- `BottomActionBar` — sticky bottom bar for a form's / checkout's primary action (`pb-safe`, `z-sticky`, rides above the on-screen keyboard via `visualViewport`). Children are the actions; `fullWidth` / `stackOnMobile` for phone layouts, `align`, `position=\"fixed\" | \"sticky\"`. Put `<BottomActionBar.Spacer />` at the end of the page. Never hand-roll a `fixed bottom-0` action bar.\n- `StatCard` — KPI tile (`label`, `value`, `icon`, `tone`, `change`).\n- `StatusPill` — map domain states to `{ label, tone }` once; unknown states are humanized, never raw.\n- `EmptyState`, `ErrorState`, `LoadingState` — every data card needs all three.\n- `ConfirmDialog` — use instead of `window.confirm()`; title is the question, button is the verb. Like `Dialog`, it takes `presentation` (`auto` default: bottom sheet on phones, centred modal elsewhere; `popover` = always centred; `sheet` = always a sheet). Write footer actions secondary-then-primary; sheet mode stacks them full width with the primary on top.\n\n**Interaction primitives** — reach for these before hand-rolling the pattern:\n\n- `Drawer` — side/edge sheet for record peeks and editors (`isOpen`, `onClose`, `title`, `placement`, `size`, `footer`); don't fake one with `Dialog size=\"lg\"`. On phones use `placement=\"bottom\"` (+ `swipeToClose`) as the bottom sheet: it already has a grab `handle`, rounded top and safe-area padding — don't add them with `className`.\n- `FootNav` — phone tab bar. A centre \"+\" is an item with `variant: 'action'` (raised primary circle); give it `'aria-haspopup': 'dialog'` and `'aria-expanded'` when it opens a sheet. Navigation tabs take `href`/`to` (+ `linkAs={Link}`) so they render as links with `aria-current=\"page\"`; `hideOnScroll` slides it away on scroll down; put `<FootNav.Spacer />` after the page content instead of a hand-tuned `pb-20`. It already pads the safe area and caps badges at `99+` (`badgeMax`).\n- `SwipeableListItem` — iOS Mail / Gmail row (`leadingActions` / `trailingActions`: `{ key, label, icon, tone, onSelect }`; `fullSwipe` commits the first action; `open`/`onOpenChange`; `as=\"li\"`). Every action is also reachable through its \"More actions\" button (menu, action sheet on phones). `Table` uses it for mobile cards via `swipeActions={(row) => ({ leading, trailing })}`. Never hand-roll swipe gestures.\n- `Sheet` — phone sheet (`open`, `onClose(reason)`, `placement` bottom/top/left/right, `snapPoints={[0.5, 1]}` + `activeSnap`/`onSnapChange`, `dismissible`, `title`) with drag-to-dismiss and keyboard-aware positioning; compose `Sheet.Header` / `Sheet.Body` (scrolls) / `Sheet.Footer`. Use it for phone sheets with snap points (filters, pickers, quick forms); keep `Drawer` for record peeks. Never hand-roll drag or `visualViewport` handling.\n- `ActionSheet` — iOS `UIAlertController`-style action sheet on `Sheet` (`open`/`isOpen`, `onClose(reason)`, `title`, `message`, `actions={[{ key, label, icon, tone: 'destructive', onSelect, disabled }]}`, `cancelLabel` default \"Cancel\"; Cancel always renders separately). Selecting calls `onSelect` then `onClose('select')`; focus returns to the opener. Use it for \"what to do with this?\" choices on phones instead of a hand-built list in a `Sheet`; for a kebab menu use `ThreeDotPopover`, which already becomes an action sheet on phones.\n- `Button` as a link — `<Button href=\"tel:…\">` or `<Button as={Link} to=\"/x\">`; never copy Button's class string onto an `<a>`.\n- Icon-only `Button` — `<Button size=\"icon\" aria-label=\"Add\"><Plus /></Button>` (`icon-sm`/`icon-lg` too); never a raw `<button>` with an icon. `loading` keeps the button's width.\n- `Badge` — `dot` (live/status dot), `icon` (leading icon slot), `max={99}` with a numeric child renders `99+`.\n- `AvatarGroup` — `<AvatarGroup max={3} size=\"sm\">{people.map(p => <Avatar name={p.name} />)}</AvatarGroup>`; don't hand-roll `-space-x` stacks or a fake `<Avatar name=\"+5\" />`.\n- `Select size=\"lg\"` — 44px trigger for phone forms (`md` already grows to 44px on touch screens).\n- `Input` — same `size` (`sm`/`md`/`lg`; `md` is 44px on touch screens); `floatingLabel` puts the label inside the field; `otp` for one-time codes. `type=\"tel|email|url|search\"` already sets `inputMode`/`autoComplete` — don't add them by hand.\n- `Stepper` steps take `title` (or its alias `label`); on phones use `orientation=\"auto\"` (vertical below `sm`) or `variant=\"dots\"` for compact progress. `Tabs variant=\"segmented\"` is the iOS segmented control (2–4 short options); add `swipeable` for swiping between panels on touch. Many tabs scroll sideways on their own, so don't wrap `Tabs.List` in an `overflow-x-auto` div. `Breadcrumbs maxItems={3}` collapses deep trails into \"…\". `Pagination` collapses to \"‹ Page 3 of 10 ›\" below `sm` by itself. `Radio` follows the primary token by default — don't pass `radioColor` to match the brand.\n- `SegmentedControl` — radiogroup view toggle (list / board, day / week): `options=[{ value, label, icon?, disabled? }]`, `value`/`defaultValue` + `onChange(value)`, `size` (`sm`/`md`/`lg`, 44px on touch screens), `fullWidth`, `name`, `aria-label`. Arrow keys move and select; the thumb slides. Use `Tabs variant=\"segmented\"` instead when the choice switches panels.\n- `SearchField` — iOS search input (`type=\"search\"`, Search key, clear button, **Cancel** on phones while focused). `value`/`defaultValue` + `onValueChange(text)`, `onSearch(text)` on Enter, `onCancel`. Pass `results` or `renderResults={({ value, close }) => …}` for a results surface: a full-height Sheet on phones, a popover under the field elsewhere (`presentation` overrides). Never hand-roll a search input with an icon.\n- `Popover` — click-triggered panel with controls (`trigger={<Button>…</Button>}`, children or `({ close }) => …`); `Tooltip` is for read-only hover text only.\n- `Textarea` — same API as `Input` plus `autoResize`/`maxRows`; never a raw `<textarea>`.\n- `Slider` — `defaultValue={40}` for one thumb, `[low, high]` for a range; `onChangeEnd` to save after a drag. A value bubble shows while dragging (`showBubble={false}` to hide).\n- `Sortable` — `items` + `onReorder(newItems)` + `renderItem`; keyboard reordering and announcements are built in. Pass `handle` and spread `handleProps` on a grip for touch screens.\n- `SortableGroup` — for boards / backlog → sprint: wrap the lists, give each `Sortable` an `id` (+ `aria-label`, used in announcements) and handle `onMove({ item, from: { listId, index }, to: { listId, index } })`; pass `canDrop(item, target, from)` (e.g. from a server transition list) so refused columns are marked and announced before the drop instead of reverting after it. Within-list reorders still call each list's `onReorder`. Give lists a `min-h-*` so empty ones can be dropped on.\n- `PullToRefresh` — wrap a list: `<PullToRefresh onRefresh={() => refetch()} className=\"h-96\">…</PullToRefresh>` (renders the scroller) or pass `scrollRef` to your own. `onRefresh` returns a promise; the spinner spins until it settles. `threshold` (64), `disabled`, `refreshingLabel`. Touch only — keep a refresh button for mouse/keyboard users.\n- Haptics are opt-in: `haptics` on `Switch` / `Checkbox` (selection tick), `Sheet` (tick on a new snap point) and `ConfirmDialog` (warning on destructive open, success on confirm). Default `false`; never the only signal. For custom cues use `useHaptics().trigger('success')`.\n- Charts (`/charts`) — `<LineChart data={rows} index=\"month\" categories={['revenue', 'costs']} />`; same shape for `BarChart` (`stacked`, `horizontal`) and `AreaChart` (`stacked`); `DonutChart` takes `index` (name key) + `category` (value key) + `centerLabel`; `Sparkline` takes `category` + `color`; `ScatterChart` takes `x` + `y` (numeric keys) plus optional `index` (entity name) and `category` (series), e.g. `<ScatterChart data={projects} x=\"health\" y=\"variance\" index=\"project\" category=\"department\" />`. Colours are tokens (`colors={['primary', 'success-600']}`), never hex. Always pass `title` (accessible name) and, for key charts, a `description` with the takeaway. `valueFormatter` formats tooltip/axis/table values.\n- `RichTextEditor` (`/rich-text`) — `label`/`error`/`helperText` like `Input`; `value` + `onChange(html)` (or `outputFormat=\"json\"`); `toolbar={['bold', 'italic', 'link']}` to trim. Tell the user to **sanitize the HTML server-side**; never render it with `dangerouslySetInnerHTML` unsanitized.\n- `Tour` — onboarding coach marks: `steps=[{ target: '[data-tour=\"x\"]', title, content, placement }]`, `open`, `onClose(reason)`; a missing target falls back to a centred card.\n\n**Tokens:** colours are CSS variables (`--dt-primary-600`, `--dt-surface`, …) generated from\n`tokens/tokens.json`. Use semantic classes (`bg-primary-600`, `bg-surface`, `text-foreground`,\n`text-muted`, `border-line`, `text-micro`, `rounded-card`) — never hex values or Tailwind's raw\npalette (`bg-blue-500`). A product's brand lives in its own repo as `dreamtree.brand.json`;\n`npx @dreamtree-org/twreact-ui brand build --out app/brand.css` turns it into the CSS to load after\ntwreact-ui's CSS. To change a product's colours, edit that file, never the components.\nThe full rule set for screens is `DESIGN.md` in the package root.\n\n```jsx\n<PageHeader title=\"Compliance calendar\" actions={<Button>Add obligation</Button>} />\n<div className=\"grid grid-cols-2 gap-4 lg:grid-cols-4\">\n  <StatCard label=\"Due this week\" value={18} icon={<CalendarDays className=\"h-6 w-6\" />} />\n  <StatCard label=\"Overdue\" value={3} tone=\"error\" icon={<AlertCircle className=\"h-6 w-6\" />} />\n</div>\n<Card>{loading ? <LoadingState /> : error ? <ErrorState onRetry={retry} /> : rows.length ? <Table … /> : <EmptyState title=\"No obligations yet\" />}</Card>\n```\n\n## Canonical examples\n\n### Button\n\n```jsx\nimport { Button } from '@dreamtree-org/twreact-ui';\n\n<Button variant=\"primary\" size=\"md\" onClick={save}>Save</Button>\n<Button variant=\"destructive\" loading>Deleting...</Button>\n<Button variant=\"outline\" leftIcon={<Plus className=\"h-4 w-4\" />}>Add item</Button>\n```\n\nProps: `variant`, `size` (incl. `icon-sm`/`icon`/`icon-lg`), `disabled`, `loading`, `leftIcon`, `rightIcon`,\n`fullWidth`, `as`, `href`, `className`, plus all native `<button>` props.\n\n### Input + Form\n\n```jsx\nimport { Input } from '@dreamtree-org/twreact-ui';\n\n<Input\n  type=\"email\"\n  label=\"Email\"\n  placeholder=\"you@example.com\"\n  required\n  clearable\n  error={errors.email?.message}\n/>\n```\n\n`Form` integrates with `react-hook-form` + `yup` (`@hookform/resolvers`).\nValidation rules live in consumer code.\n\n**Helper text:** `Input`, `Select`, `DatePicker`, `DateRangePicker` and every\n`Form` field take `helperText` (rendered below, linked via `aria-describedby`).\nWhile `error` is set it **replaces** the helper text — don't render both. Don't\nhand-roll a `<p>` hint under a field.\n\n```jsx\n<Select label=\"Role\" helperText=\"Controls access.\" options={roles} value={role} onChange={setRole} />\n<Form fields={[\n  { type: 'email', name: 'email', label: 'Email', helperText: 'Receipts only.' },\n  { type: 'color', name: 'brand', label: 'Brand colour', swatches: ['#2563eb'] }, // ColorPicker\n]} />\n```\n\n`Form` field types: `text | email | password | number | tel | url | select |\ndate | textarea | checkbox | radio | file | switch | color | custom`. Use\n`type: 'color'` rather than a `custom` field wrapping `ColorPicker`.\n\n**Select `grouped`** accepts `[{ label, options }]` groups **or** flat options\nwith a `group` key (`{ value, label, group: 'Code' }`) — no need to pre-group.\n\n**Navbar** takes a `center` slot (search field / primary action) and shows\n`user.name` initials when `user.avatar` is missing; it fits a 390px phone.\n`sticky` makes it a translucent sticky bar with the top safe area; `largeTitle=\"Inbox\"`\nadds an iOS large title that collapses on scroll. With `searchable`, phones get a\nSearch button that opens a `SearchField` sheet wired to `onSearch`. When the left\nbutton opens your Sidebar drawer (`leftIcon={<Menu />}`), name it with\n`leftIconLabel=\"Open navigation\"` (default \"Go back\") and pass\n`leftIconProps={{ 'aria-expanded': open, 'aria-controls': 'app-sidebar' }}`.\n\n**Select / DatePicker / DateRangePicker** show their placeholder muted (`text-muted`)\nand set `data-empty` on the trigger while empty — don't add a muted `className` yourself.\n\n**Tooltip** around a component (e.g. `<Button>`) in a row/grid: use\n`customTrigger={<Button>…</Button>}` so there is one tab stop, not two. A lone\nnative `<button>` / `<a href>` / `<input>` child is detected automatically.\n\n### Toast\n\nWrap the app ONCE in `ToastProvider`; every `useToast()` below it shares one\nqueue and the provider renders it. (Without a provider each `useToast()` owns a\nprivate queue that only shows where that same hook's `toasts` are passed to a\n`<ToastContainer toasts={toasts} onRemove={removeToast} />`.)\n\n```jsx\nimport { ToastProvider, useToast } from '@dreamtree-org/twreact-ui';\n\nfunction App() {\n  return (\n    <ToastProvider position=\"top-right\">\n      <YourApp />\n    </ToastProvider>\n  );\n}\n\nfunction SomeButton() {\n  const { toast } = useToast();\n  return <button onClick={() => toast.success('Saved!')}>Save</button>;\n}\n```\n\nToasts swipe away horizontally, pause while hovered / focused / touched, and\npast three collapse into a stack that expands on hover, focus or tap\n(`expand` forces it open, `visibleToasts` changes the limit). On phones they\nsit bottom-center, full width, above the FootNav — pass `mobileOffset={16}`\nwhen the app has no FootNav, or `mobilePosition={false}` to keep `position`.\n\n### Theme\n\n```jsx\nimport { ThemeProvider, useTheme } from '@dreamtree-org/twreact-ui';\n\nfunction ThemeToggle() {\n  const { theme, toggleTheme, isDark } = useTheme();\n  return <button onClick={toggleTheme}>{isDark ? '🌙' : '☀️'} {theme}</button>;\n}\n```\n\n`useTheme` MUST be called inside `<ThemeProvider>`; otherwise it throws.\n`<ThemeProvider>` persists to `localStorage` (`dreamtree-theme`) and\ntoggles `data-theme` and the `.dark` class on `<html>`.\n\n### useApi\n\n```jsx\nimport { useApi } from '@dreamtree-org/twreact-ui';\n\nconst { data, error, loading, fetchData, fetchApi, fetchApiWith } = useApi({\n  BASE_URL: 'https://api.example.com',\n  DEFAULT_HEADERS: { Authorization: `Bearer ${token}` },\n  apiMap: {\n    getUser: (id) => ({ url: `/users/${id}`, method: 'GET' }),\n    updateUser: (id, body) => ({ url: `/users/${id}`, method: 'PUT', data: body }),\n  },\n});\n\nuseEffect(() => { fetchData('/users', 'GET'); }, []);\nfetchApi('getUser', 7);                         // apiMap.getUser(7) — ONE argument\nfetchApiWith('updateUser', [7, { name: 'A' }]); // apiMap.updateUser(7, {...}) — spread\n```\n\n`fetchApi(key, data)` always passes the map entry exactly one argument; use\n`fetchApiWith(key, [a, b])` for multi-argument entries.\n\nFor session expiry pass `onUnauthorized: (error, { apiKey, url, method }) => …`.\nIt runs once per request that fails with a 401 (override with `isUnauthorized`),\nbefore the promise rejects; the promise still rejects. Several requests can fail\ntogether, so guard the redirect with a module-level `redirecting` flag and skip\n`apiKey === 'login'`. Don't hand-roll an axios interceptor for this.\n\nTreat `useApi` as a thin axios wrapper, not a caching/dedup layer. For\ncache, the consumer brings their own (React Query, SWR, etc.).\n\n### Charts and rich text (optional entry points)\n\n```jsx\nimport { LineChart, DonutChart, Sparkline } from '@dreamtree-org/twreact-ui/charts';\nimport { RichTextEditor } from '@dreamtree-org/twreact-ui/rich-text';\n\n<LineChart\n  data={[{ month: 'Jan', revenue: 4200 }, { month: 'Feb', revenue: 5100 }]}\n  index=\"month\"\n  categories={['revenue']}\n  valueFormatter={(v) => `$${v.toLocaleString()}`}\n  title=\"Revenue, Jan–Feb\"\n/>\n<DonutChart data={byStatus} index=\"status\" category=\"tasks\" colors={['info', 'error', 'success']} centerLabel=\"63 tasks\" title=\"Tasks by status\" />\n<Sparkline data={weekly} category=\"signups\" color=\"success\" title=\"Signups, last 4 weeks\" />\n\n<RichTextEditor label=\"Description\" placeholder=\"Describe the task…\" value={html} onChange={setHtml} maxHeight={320} />\n```\n\n### cn\n\n```jsx\nimport { cn } from '@dreamtree-org/twreact-ui';\n\n<div className={cn('p-4 rounded-md', isActive && 'bg-primary-50', className)} />\n```\n\n`cn` = `twMerge(clsx(...))` — later classes win on Tailwind conflicts.\n\n## Rules for AI assistants helping consumers\n\n1. **Use library components.** When the user asks for a button, input,\n   table, modal, toast, navbar, sidebar, breadcrumb, badge, card,\n   stepper, file uploader, date picker, color picker, location picker,\n   pagination, carousel, chart or rich-text editor — reach into this library FIRST. Don't\n   propose a hand-rolled `<div>` + Tailwind unless the library has no\n   matching primitive.\n2. **Use the shared vocabulary.** `variant=\"primary\"`, `size=\"md\"`,\n   `leftIcon={...}`, `fullWidth`, `clearable` — these are exact names.\n   Don't invent `color=\"blue\"` or `iconLeft={...}`. Icon slots are\n   `leftIcon` / `rightIcon` on `Button`, `Input` and `Tabs.Tab` (2.0 renamed\n   Input `icon`/`iconPosition` and Tab `iconLeft`/`iconRight`).\n3. **Wrap in `<ThemeProvider>`.** Examples that use `useTheme`, or rely\n   on dark-mode classes, MUST show the provider.\n4. **`<StoreProvider>` is optional.** Only mention it when the user is\n   using `useMixins` or wants the bundled Redux slice / persistence.\n   Don't insist on it for every example.\n5. **Tailwind content[] config.** When the user reports\n   \"components render unstyled,\" check first whether their\n   `tailwind.config.js` `content[]` includes\n   `./node_modules/@dreamtree-org/twreact-ui/dist/**/*.{js,mjs}`.\n6. **Don't deep-import.** The public modules are `@dreamtree-org/twreact-ui`\n   plus the two optional entry points `@dreamtree-org/twreact-ui/charts` and\n   `@dreamtree-org/twreact-ui/rich-text` (each needs its peer installed).\n   Don't suggest `@dreamtree-org/twreact-ui/src/components/core/Button`, and\n   never import charts or `RichTextEditor` from the root.\n7. **React 18 only.** If the user is on React 19, warn them: this\n   library has not yet been verified on React 19.\n8. **Accessibility-first.** Icon-only buttons need `aria-label`.\n   Dialogs need a focus trap (the library provides it). Don't strip\n   `focus:ring-*` utilities.\n9. **Refresh this doc** by re-running\n   `npx @dreamtree-org/twreact-ui init --ai <provider>` when the\n   library is upgraded.\n"
 }