@dreamtree-org/twreact-ui 2.1.1 → 2.2.0

package/mcp/catalog.snapshot.json

@@ -460,7 +460,7 @@
         "importFrom": "@dreamtree-org/twreact-ui",
         "peerDependencies": [],
         "hasDoc": true,
-        "description": "Data table with sorting, filtering, pagination, row selection, expandable details, and responsive mobile card view. The toolbar **Reload** button is tinted `bg-primary-100 text-primary-700` with `dark:bg-primary-900/40 dark:text-primary-300` in dark mode.",
+        "description": "Data table with sorting, filtering, pagination, row selection, expandable details, and responsive mobile card view. The toolbar **Reload** button is tinted `bg-primary-100 text-primary-700` with `dark:bg-primary-900/40 dark:text-primary-300` in dark mode. Column headers, mobile-card labels and filter labels use `text-primary-700` / `dark:text-primary-300`; mobile-card values use `text-primary-900` / `dark:text-foreground`.",
         "props": [
           {
             "prop": "data",
@@ -526,13 +526,13 @@
             "prop": "onSort",
             "type": "`function`",
             "default": "",
-            "description": "Sort callback"
+            "description": "Sort callback `(key, direction)`. Called once per sort, after the state update (not during render), so it may set parent state."
           },
           {
             "prop": "onFilter",
             "type": "`function`",
             "default": "",
-            "description": "Filter callback"
+            "description": "Filter callback `(filters)`. Called once per change, outside render, like `onSort`."
           },
           {
             "prop": "onFetch",
@@ -3697,9 +3697,9 @@
           },
           {
             "prop": "rightMenuContent",
-            "type": "`(props) => ReactNode`",
+            "type": "`ReactNode` | `(props) => ReactNode`",
             "default": "",
-            "description": "Custom right menu. Receives `{ notifications }` and any Navbar `...props` (e.g. `emitter`, `onFetch`). If not provided, default renders notifications dropdown."
+            "description": "Custom right menu. An element is rendered as is; a function receives `{ notifications }` and any Navbar `...props` (e.g. `emitter`, `onFetch`). If omitted or `null`, the default notifications dropdown renders."
           },
           {
             "prop": "onLoginClick",
@@ -7017,6 +7017,876 @@
           }
         ],
         "examples": "### 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```"
+      },
+      {
+        "name": "ScrollStage",
+        "group": "motion",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "A pinned scroll scene: a tall section whose content sticks to the viewport (`sticky top-0 h-screen`) while the user scrolls through `length` viewport heights. Scene progress (0–1) is written to `--dt-p` on the root, so children can animate with CSS, and is also passed to `children(progress)` and `onProgress`. Part of the `/motion` entry point ([overview](Motion.md)).",
+        "props": [
+          {
+            "prop": "length",
+            "type": "`number`",
+            "default": "300",
+            "description": "Scroll distance of the scene in vh on desktop (token `scroll.sceneLength`). Values under 100 are raised to 100"
+          },
+          {
+            "prop": "mobileLength",
+            "type": "`number`",
+            "default": "150",
+            "description": "Scene length in vh below `md` (token `scroll.sceneLengthMobile`)"
+          },
+          {
+            "prop": "pin",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "Pin the content while the scene scrolls. `false` renders it in normal flow"
+          },
+          {
+            "prop": "children",
+            "type": "`ReactNode` | `(progress: ScrollProgress) => ReactNode`",
+            "default": "",
+            "description": "Content, or a function that receives the live progress subscription (`get()` / `subscribe(fn)`). Inside, CSS can read `var(--dt-p, 1)`"
+          },
+          {
+            "prop": "onProgress",
+            "type": "`(progress: number) => void`",
+            "default": "",
+            "description": "Called with the scene progress (0–1) on the frame loop"
+          },
+          {
+            "prop": "contentClassName",
+            "type": "`string`",
+            "default": "",
+            "description": "Classes for the pinned inner box"
+          },
+          {
+            "prop": "as",
+            "type": "`ElementType`",
+            "default": "\"section\"",
+            "description": "Root element"
+          },
+          {
+            "prop": "className",
+            "type": "`string`",
+            "default": "",
+            "description": "Extra classes for the root (merged with `cn`)"
+          },
+          {
+            "prop": "ref",
+            "type": "`Ref<HTMLElement>`",
+            "default": "",
+            "description": "Forwarded to the root element"
+          },
+          {
+            "prop": "...rest",
+            "type": "`HTMLAttributes<HTMLElement>`",
+            "default": "",
+            "description": "Forwarded to the root (`id`, `data-*`, `aria-*`, handlers)"
+          }
+        ],
+        "examples": "### CSS driven by progress\n\n```jsx\n<ScrollStage length={250} className=\"bg-gray-950 text-gray-50\">\n  <div className=\"flex h-full items-center justify-center\">\n    <h2 className=\"text-page-title [opacity:var(--dt-p,1)] [transform:scale(calc(0.6+var(--dt-p,1)*0.4))]\">\n      Grows as you scroll\n    </h2>\n  </div>\n</ScrollStage>\n```\n\n### Progress callback\n\n```jsx\nconst [step, setStep] = useState(0);\n\n<ScrollStage length={300} onProgress={(p) => setStep(Math.min(2, Math.floor(p * 3)))}>\n  <FeatureStep index={step} />\n</ScrollStage>\n```"
+      },
+      {
+        "name": "Reveal",
+        "group": "motion",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "Plays an entrance — fade up, fade, scale, clip, or word by word — when the element scrolls into view. Content already on screen at load is never hidden (no flash and no delay to the largest paint), so only content below the fold animates. Part of the `/motion` entry point ([overview](Motion.md)). To reveal several children in turn, use [RevealGroup](RevealGroup.md).",
+        "props": [
+          {
+            "prop": "effect",
+            "type": "`\"fade-up\"` | `\"fade\"` | `\"scale\"` | `\"clip\"` | `\"split-words\"`",
+            "default": "\"fade-up\"",
+            "description": "Entrance effect. `split-words` needs a string child; otherwise it renders the child unchanged"
+          },
+          {
+            "prop": "delay",
+            "type": "`number`",
+            "default": "0",
+            "description": "Delay before the entrance, in ms"
+          },
+          {
+            "prop": "stagger",
+            "type": "`number`",
+            "default": "40",
+            "description": "Delay between words for `split-words`, in ms"
+          },
+          {
+            "prop": "once",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "Reveal once, or (`false`) hide again whenever the element leaves the viewport"
+          },
+          {
+            "prop": "as",
+            "type": "`ElementType`",
+            "default": "\"div\"",
+            "description": "Root element"
+          },
+          {
+            "prop": "children",
+            "type": "`ReactNode`",
+            "default": "",
+            "description": "Content"
+          },
+          {
+            "prop": "className",
+            "type": "`string`",
+            "default": "",
+            "description": "Extra classes for the root (merged with `cn`)"
+          },
+          {
+            "prop": "ref",
+            "type": "`Ref<HTMLElement>`",
+            "default": "",
+            "description": "Forwarded to the root element"
+          },
+          {
+            "prop": "...rest",
+            "type": "`HTMLAttributes<HTMLElement>`",
+            "default": "",
+            "description": "Forwarded to the root"
+          }
+        ],
+        "examples": "```jsx\n<Reveal>\n  <Card>Below-the-fold content</Card>\n</Reveal>\n\n<Reveal as=\"h2\" effect=\"split-words\" className=\"text-page-title\">\n  Software that tells your story\n</Reveal>\n\n<Reveal effect=\"clip\" delay={150}>\n  <img src=\"/team.jpg\" alt=\"The team\" />\n</Reveal>\n```"
+      },
+      {
+        "name": "RevealGroup",
+        "group": "motion",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "Wraps each child in a [Reveal](Reveal.md) and staggers them: child `i` waits `delay + i * stagger` ms. Use it for card grids and lists that should enter one after another. Part of the `/motion` entry point ([overview](Motion.md)).",
+        "props": [
+          {
+            "prop": "effect",
+            "type": "`\"fade-up\"` | `\"fade\"` | `\"scale\"` | `\"clip\"`",
+            "default": "\"fade-up\"",
+            "description": "Entrance of each child. `\"split-words\"` is treated as `\"fade-up\"`"
+          },
+          {
+            "prop": "delay",
+            "type": "`number`",
+            "default": "0",
+            "description": "Delay before the first child, in ms"
+          },
+          {
+            "prop": "stagger",
+            "type": "`number`",
+            "default": "80",
+            "description": "Delay added per child, in ms"
+          },
+          {
+            "prop": "once",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "Reveal once, or every time a child re-enters the viewport"
+          },
+          {
+            "prop": "as",
+            "type": "`ElementType`",
+            "default": "\"div\"",
+            "description": "Group element"
+          },
+          {
+            "prop": "itemAs",
+            "type": "`ElementType`",
+            "default": "\"div\"",
+            "description": "Element wrapping each child (e.g. `\"li\"` inside `as=\"ul\"`)"
+          },
+          {
+            "prop": "children",
+            "type": "`ReactNode`",
+            "default": "",
+            "description": "The items. `null` / `false` children are skipped and do not take a delay slot"
+          },
+          {
+            "prop": "className",
+            "type": "`string`",
+            "default": "",
+            "description": "Classes for the group element"
+          },
+          {
+            "prop": "ref",
+            "type": "`Ref<HTMLElement>`",
+            "default": "",
+            "description": "Forwarded to the group element"
+          },
+          {
+            "prop": "...rest",
+            "type": "`HTMLAttributes<HTMLElement>`",
+            "default": "",
+            "description": "Forwarded to the group element"
+          }
+        ],
+        "examples": "```jsx\n<RevealGroup as=\"ul\" itemAs=\"li\" stagger={120} className=\"grid gap-4 sm:grid-cols-3\">\n  <Card>Plan</Card>\n  <Card>Design</Card>\n  <Card>Build</Card>\n</RevealGroup>\n```"
+      },
+      {
+        "name": "SmoothScrollProvider",
+        "group": "motion",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "Opt-in smooth (inertial) page scrolling with [Lenis](https://github.com/darkroomengineering/lenis). Lenis is an optional peer dependency that this package never imports: install it and pass the class in. Without it, the page keeps native scrolling, and every motion component works the same either way. Lenis runs on the same frame loop as the other motion components. Read the provider's state with [useSmoothScroll](useSmoothScroll.md). Part of the `/motion` entry point ([overview](Motion.md)).",
+        "props": [
+          {
+            "prop": "lenis",
+            "type": "`new (options?) => LenisLike`",
+            "default": "",
+            "description": "The Lenis class (`import Lenis from 'lenis'`). Without it, native scrolling is used"
+          },
+          {
+            "prop": "options",
+            "type": "`Record<string, unknown>`",
+            "default": "",
+            "description": "Options for `new Lenis({ autoRaf: false, ...options })`, read once per instance (change `enabled` or `lenis` to rebuild)"
+          },
+          {
+            "prop": "enabled",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "Turn smooth scrolling off without removing the provider"
+          },
+          {
+            "prop": "children",
+            "type": "`ReactNode`",
+            "default": "",
+            "description": "The page"
+          }
+        ],
+        "examples": "```jsx\nimport Lenis from 'lenis';\n\nexport default function Landing() {\n  return (\n    <SmoothScrollProvider lenis={Lenis} options={{ lerp: 0.1 }}>\n      <DeviceMorphHero media={media} content={<HeroCopy />} />\n      <StackedCards items={pillars} />\n    </SmoothScrollProvider>\n  );\n}\n```\n\n### Scroll to a section\n\n```jsx\nfunction NavLink({ href, children }) {\n  const { scrollTo } = useSmoothScroll();\n  return <a href={href} onClick={(e) => { e.preventDefault(); scrollTo(href, { offset: -80 }); }}>{children}</a>;\n}\n```"
+      },
+      {
+        "name": "DeviceFrame",
+        "group": "motion",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "A CSS-only device mock-up — phone, tablet, laptop or browser window — around any screen content. Purely presentational: no motion, no images, works anywhere (feature sections, docs, the [DeviceMorphHero](DeviceMorphHero.md)). Part of the `/motion` entry point ([overview](Motion.md)).",
+        "props": [
+          {
+            "prop": "device",
+            "type": "`\"phone\"` | `\"tablet\"` | `\"laptop\"` | `\"browser\"`",
+            "default": "\"phone\"",
+            "description": "Frame style. Widths: phone 220 px (262 px from `md`), tablet 320/440 px, laptop 340/640 px, browser 340/720 px; height follows the device's aspect ratio"
+          },
+          {
+            "prop": "children",
+            "type": "`ReactNode`",
+            "default": "",
+            "description": "Screen content (fills the screen box, which clips it)"
+          },
+          {
+            "prop": "url",
+            "type": "`string`",
+            "default": "",
+            "description": "Address shown in the `browser` frame's bar"
+          },
+          {
+            "prop": "screenClassName",
+            "type": "`string`",
+            "default": "",
+            "description": "Classes for the screen box (default background `bg-surface`)"
+          },
+          {
+            "prop": "className",
+            "type": "`string`",
+            "default": "",
+            "description": "Extra classes for the root `<div>` (merged with `cn`; override the width with a `w-*` class)"
+          },
+          {
+            "prop": "ref",
+            "type": "`Ref<HTMLDivElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<div>`"
+          },
+          {
+            "prop": "...rest",
+            "type": "`HTMLAttributes<HTMLDivElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<div>`"
+          }
+        ],
+        "examples": "```jsx\n<DeviceFrame device=\"phone\">\n  <img src=\"/screens/home.png\" alt=\"The app's home screen\" className=\"h-full w-full object-cover\" />\n</DeviceFrame>\n\n<DeviceFrame device=\"browser\" url=\"dreamtree.in\" className=\"w-full max-w-3xl\">\n  <Dashboard />\n</DeviceFrame>\n```"
+      },
+      {
+        "name": "LogoMarquee",
+        "group": "motion",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "An endless horizontal strip of client logos or names. The list is rendered twice for a seamless loop; the second copy is `aria-hidden`, so screen readers read each item once. It pauses on hover, while focus is inside and while off screen. Part of the `/motion` entry point ([overview](Motion.md)).",
+        "props": [
+          {
+            "prop": "items",
+            "type": "`(string | { src, alt, href? } | ReactNode)[]`",
+            "default": "[]",
+            "description": "**Required.** Names (strings, rendered as muted text), logos (`{ src, alt, href? }`, rendered as an `<img>`, wrapped in a link when `href` is set) or any node"
+          },
+          {
+            "prop": "speed",
+            "type": "`number`",
+            "default": "40",
+            "description": "Scroll speed in px per second. The loop duration is the measured list width ÷ `speed`"
+          },
+          {
+            "prop": "direction",
+            "type": "`\"left\"` | `\"right\"`",
+            "default": "\"left\"",
+            "description": "Direction of the first row"
+          },
+          {
+            "prop": "pauseOnHover",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "Pause while the pointer is over the strip. It always pauses while focus is inside"
+          },
+          {
+            "prop": "fadeEdges",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "Fade the left and right edges with a mask"
+          },
+          {
+            "prop": "rows",
+            "type": "`1` | `2`",
+            "default": "1",
+            "description": "One row, or two rows running in opposite directions"
+          },
+          {
+            "prop": "label",
+            "type": "`string`",
+            "default": "\"Clients\"",
+            "description": "Accessible name of the `role=\"region\"` wrapper"
+          },
+          {
+            "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>`"
+          }
+        ],
+        "examples": "```jsx\n<LogoMarquee items={['Schoo360', 'TradeOS', 'booknbuy', 'BillPro']} />\n\n<LogoMarquee\n  label=\"Our clients\"\n  rows={2}\n  speed={30}\n  items={[\n    { src: '/logos/acme.svg', alt: 'Acme', href: 'https://acme.example' },\n    { src: '/logos/globex.svg', alt: 'Globex' },\n  ]}\n/>\n```"
+      },
+      {
+        "name": "CountUp",
+        "group": "motion",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "A number that counts up from `from` to `value` when it scrolls into view. The server, no-JS readers and reduced-motion users get the real final value, so crawlers never see \"0\". Formats with `Intl.NumberFormat` (Indian grouping by default). Part of the `/motion` entry point ([overview](Motion.md)). For a row of stats, use [StatStrip](StatStrip.md).",
+        "props": [
+          {
+            "prop": "value",
+            "type": "`number`",
+            "default": "",
+            "description": "**Required.** The final number, rendered as-is on the server and under reduced motion"
+          },
+          {
+            "prop": "from",
+            "type": "`number`",
+            "default": "0",
+            "description": "Number the animation starts from"
+          },
+          {
+            "prop": "prefix",
+            "type": "`ReactNode`",
+            "default": "",
+            "description": "Text before the number, e.g. `\"₹\"`"
+          },
+          {
+            "prop": "suffix",
+            "type": "`ReactNode`",
+            "default": "",
+            "description": "Text after the number, e.g. `\"+\"`, `\"%\"`, `\" Cr\"`"
+          },
+          {
+            "prop": "duration",
+            "type": "`number`",
+            "default": "1600",
+            "description": "Animation length in ms (ease-out). `0` disables the animation"
+          },
+          {
+            "prop": "decimals",
+            "type": "`number`",
+            "default": "as many as value has",
+            "description": "Fraction digits"
+          },
+          {
+            "prop": "locale",
+            "type": "`string`",
+            "default": "\"en-IN\"",
+            "description": "`Intl.NumberFormat` locale (`en-IN` groups as 12,50,000)"
+          },
+          {
+            "prop": "format",
+            "type": "`(value: number) => string`",
+            "default": "",
+            "description": "Custom formatter; overrides `locale` and `decimals`"
+          },
+          {
+            "prop": "className",
+            "type": "`string`",
+            "default": "",
+            "description": "Extra classes for the root `<span>` (merged with `cn`; `tabular-nums` is always set)"
+          },
+          {
+            "prop": "ref",
+            "type": "`Ref<HTMLSpanElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<span>`"
+          },
+          {
+            "prop": "...rest",
+            "type": "`HTMLAttributes<HTMLSpanElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<span>`"
+          }
+        ],
+        "examples": "```jsx\n<CountUp value={500} suffix=\"+\" className=\"text-kpi font-semibold\" />\n\n<CountUp value={2500000} prefix=\"₹\" />            {/* ₹25,00,000 */}\n\n<CountUp value={98.5} suffix=\"%\" locale=\"en-US\" />\n\n<CountUp value={50} format={(n) => `${Math.round(n)} Cr`} />\n```"
+      },
+      {
+        "name": "StatStrip",
+        "group": "motion",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "A row of headline numbers that count up on view, as bordered cards or as one band with dividers. Each number is a [CountUp](CountUp.md). Part of the `/motion` entry point ([overview](Motion.md)).",
+        "props": [
+          {
+            "prop": "items",
+            "type": "`{ value: number; label: ReactNode; prefix?: ReactNode; suffix?: ReactNode; decimals?: number; format?: (value: number) => string }[]`",
+            "default": "[]",
+            "description": "**Required.** One entry per stat"
+          },
+          {
+            "prop": "variant",
+            "type": "`\"cards\"` | `\"band\"`",
+            "default": "\"cards\"",
+            "description": "Bordered tiles, or one bordered row with dividers"
+          },
+          {
+            "prop": "duration",
+            "type": "`number`",
+            "default": "1600",
+            "description": "Passed to every CountUp"
+          },
+          {
+            "prop": "locale",
+            "type": "`string`",
+            "default": "\"en-IN\"",
+            "description": "Passed to every CountUp"
+          },
+          {
+            "prop": "className",
+            "type": "`string`",
+            "default": "",
+            "description": "Extra classes for the root `<dl>` (merged with `cn`)"
+          },
+          {
+            "prop": "ref",
+            "type": "`Ref<HTMLDListElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<dl>`"
+          },
+          {
+            "prop": "...rest",
+            "type": "`HTMLAttributes<HTMLDListElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<dl>`"
+          }
+        ],
+        "examples": "```jsx\n<StatStrip\n  items={[\n    { value: 120, suffix: '+', label: 'Projects shipped' },\n    { value: 14, label: 'Years building' },\n    { value: 2500000, prefix: '₹', label: 'Saved for clients' },\n  ]}\n/>\n\n<StatStrip variant=\"band\" items={[{ value: 98.5, suffix: '%', label: 'Uptime' }, { value: 6, label: 'Products' }]} />\n```"
+      },
+      {
+        "name": "StackedCards",
+        "group": "motion",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "Cards that stick one over another as the page scrolls. Each card is `position: sticky` at `stickyTop`; as the next card slides over, the one underneath shrinks (`scaleBack`) and dims (`dimBack`). An alternating tilt makes the stack look hand-placed. Part of the `/motion` entry point ([overview](Motion.md)).",
+        "props": [
+          {
+            "prop": "items",
+            "type": "`StackedCardItem[]`",
+            "default": "[]",
+            "description": "**Required.** `{ id?, kicker?, title, body?, bullets?: ReactNode[], metric?: { value, label }, cta?: ReactNode, media?: { src, alt } \\| ReactNode }` per card"
+          },
+          {
+            "prop": "stickyTop",
+            "type": "`number`",
+            "default": "80",
+            "description": "px from the viewport top where cards stick (token `scroll.stickyTop`; clears a floating nav)"
+          },
+          {
+            "prop": "tilt",
+            "type": "`number`",
+            "default": "1",
+            "description": "Alternating tilt in degrees: card 1 −1×tilt, card 2 +1.5×, card 3 −2×, card 4 +1×, card 5 −1.5×, card 6 +2×, then repeating. `0` disables. Off below `md` and under reduced motion"
+          },
+          {
+            "prop": "scaleBack",
+            "type": "`number`",
+            "default": "0.94",
+            "description": "Scale of a card fully covered by the next one. `1` disables"
+          },
+          {
+            "prop": "dimBack",
+            "type": "`number`",
+            "default": "0.15",
+            "description": "How much a covered card darkens (0–1, via `brightness`). `0` disables"
+          },
+          {
+            "prop": "mediaSide",
+            "type": "`\"alternate\"` | `\"right\"`",
+            "default": "\"alternate\"",
+            "description": "Media on the right of every card, or alternating sides (from `md` up)"
+          },
+          {
+            "prop": "renderItem",
+            "type": "`(item: StackedCardItem, index: number) => ReactNode`",
+            "default": "",
+            "description": "Replaces the default card body (the sticky `<article>` shell stays)"
+          },
+          {
+            "prop": "className",
+            "type": "`string`",
+            "default": "",
+            "description": "Extra classes for the root `<ol>` (merged with `cn`)"
+          },
+          {
+            "prop": "ref",
+            "type": "`Ref<HTMLOListElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<ol>`"
+          },
+          {
+            "prop": "...rest",
+            "type": "`HTMLAttributes<HTMLOListElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<ol>`"
+          }
+        ],
+        "examples": "```jsx\n<StackedCards\n  stickyTop={96}\n  items={[\n    {\n      kicker: '01 · Product',\n      title: 'Product strategy',\n      body: 'We turn a rough idea into a plan you can build, price and sell.',\n      bullets: ['Discovery workshops', 'User research', 'Roadmaps'],\n      metric: { value: '40+', label: 'Products planned' },\n      cta: <Button size=\"sm\">Get a quote</Button>,\n      media: { src: '/img/plan.jpg', alt: 'A planning workshop' },\n    },\n    { kicker: '02 · Design', title: 'Design systems', media: { src: '/img/design.jpg', alt: 'Sketches' } },\n  ]}\n/>\n```\n\n### Custom card body\n\n```jsx\n<StackedCards items={steps} tilt={0} renderItem={(step, i) => <Step number={i + 1} {...step} />} />\n```\n\nLeave space after the list (for example `pb-[50vh]` on the parent) so the last card can scroll fully into place."
+      },
+      {
+        "name": "DeviceMorphHero",
+        "group": "motion",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "A scroll hero in three steps: full-bleed media (video or image) shrinks into a device screen, the device's bezel fades in, then the device slides aside while your copy fades in beside it. Built on [ScrollStage](ScrollStage.md) and [DeviceFrame](DeviceFrame.md). Part of the `/motion` entry point ([overview](Motion.md)).",
+        "props": [
+          {
+            "prop": "media",
+            "type": "`{ video?: string; image?: string; poster?: string; alt?: string }`",
+            "default": "",
+            "description": "**Required.** A muted, looping, inline `video` (with `poster`), or an `image`. `alt` is the text alternative; leave it empty to mark the media decorative"
+          },
+          {
+            "prop": "device",
+            "type": "`\"phone\"` | `\"tablet\"` | `\"laptop\"` | `\"browser\"`",
+            "default": "\"phone\"",
+            "description": "The device the media shrinks into"
+          },
+          {
+            "prop": "length",
+            "type": "`number`",
+            "default": "300",
+            "description": "Scene length in vh on desktop, capped at 400"
+          },
+          {
+            "prop": "mobileLength",
+            "type": "`number`",
+            "default": "150",
+            "description": "Scene length in vh below `md`, capped at 400"
+          },
+          {
+            "prop": "side",
+            "type": "`\"right\"` | `\"left\"`",
+            "default": "\"right\"",
+            "description": "Side the device slides to; the copy takes the other half"
+          },
+          {
+            "prop": "content",
+            "type": "`ReactNode`",
+            "default": "",
+            "description": "Copy that fades in beside the device: logo, headline, CTAs, stats"
+          },
+          {
+            "prop": "scrollHint",
+            "type": "`ReactNode` | `false`",
+            "default": "\"Scroll to explore\"",
+            "description": "Label of a button that skips to the end of the scene; `false` hides it"
+          },
+          {
+            "prop": "className",
+            "type": "`string`",
+            "default": "",
+            "description": "Extra classes for the root `<section>` (merged with `cn`)"
+          },
+          {
+            "prop": "ref",
+            "type": "`Ref<HTMLElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<section>`"
+          },
+          {
+            "prop": "...rest",
+            "type": "`HTMLAttributes<HTMLElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<section>`"
+          }
+        ],
+        "examples": "```jsx\n<DeviceMorphHero\n  media={{ video: '/intro.mp4', poster: '/intro.jpg', alt: 'A tour of the app' }}\n  device=\"phone\"\n  content={\n    <>\n      <h1 className=\"text-page-title\">Software that tells your story.</h1>\n      <Button>Start a project</Button>\n    </>\n  }\n/>\n\n<DeviceMorphHero media={{ image: '/hero.jpg', alt: '' }} device=\"laptop\" side=\"left\" length={250} content={<HeroCopy />} />\n```\n\n### Timeline\n\nProgress through the scene (0–1): **0–45 %** the media shrinks from full-bleed to the screen; **40–60 %** the bezel fades in; **60–90 %** the device slides aside (22 % of the viewport width) and the copy fades in; the rest holds. Below `md` the device rises and shrinks to 62 % instead, and the copy appears in the lower part of the screen (scrolls if taller than 45 % of it).\n\nKeep the hero video short (H.264 or WebM, about 2 MB) and always set a `poster`."
+      },
+      {
+        "name": "BentoExpandGrid",
+        "group": "motion",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "A photo grid whose active tile grows: its column and row tracks widen to `expand`fr while the neighbours shrink. Hover, keyboard focus and — with `trigger=\"click\"` — tap expand a tile, and arrow keys move between tiles, so it never depends on a mouse. Below `md` it becomes a horizontal snap scroller. Part of the `/motion` entry point ([overview](Motion.md)).",
+        "props": [
+          {
+            "prop": "items",
+            "type": "`{ id?, media: { src, alt } | ReactNode, title: ReactNode, tag?: ReactNode, client?: ReactNode, href?: string }[]`",
+            "default": "[]",
+            "description": "**Required.** One tile per item. `href` makes the tile a link"
+          },
+          {
+            "prop": "cols",
+            "type": "`2` | `3` | `4`",
+            "default": "3",
+            "description": "Columns from `md` up; rows follow the item count"
+          },
+          {
+            "prop": "expand",
+            "type": "`number`",
+            "default": "2",
+            "description": "Track size (fr) of the active tile's row and column; the others stay `1fr`"
+          },
+          {
+            "prop": "trigger",
+            "type": "`\"hover\"` | `\"focus\"` | `\"click\"`",
+            "default": "\"hover\"",
+            "description": "`hover`: pointer and keyboard focus expand. `focus`: keyboard focus only. `click`: tiles are toggle buttons (`aria-pressed`)"
+          },
+          {
+            "prop": "label",
+            "type": "`string`",
+            "default": "",
+            "description": "Accessible name of the list"
+          },
+          {
+            "prop": "className",
+            "type": "`string`",
+            "default": "",
+            "description": "Extra classes for the root `<ul>` (merged with `cn`)"
+          },
+          {
+            "prop": "ref",
+            "type": "`Ref<HTMLUListElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<ul>`"
+          },
+          {
+            "prop": "...rest",
+            "type": "`HTMLAttributes<HTMLUListElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<ul>`"
+          }
+        ],
+        "examples": "```jsx\n<BentoExpandGrid\n  label=\"Recent projects\"\n  items={[\n    { title: 'School ERP', tag: 'Web', client: 'Schoo360', media: { src: '/work/erp.jpg', alt: 'School dashboard' }, href: '/work/erp' },\n    { title: 'Retail POS', tag: 'Mobile', client: 'TradeOS', media: { src: '/work/pos.jpg', alt: 'Point-of-sale app' } },\n  ]}\n/>\n\n<BentoExpandGrid items={projects} cols={2} trigger=\"click\" expand={2.5} />\n```"
+      },
+      {
+        "name": "TestimonialSpotlight",
+        "group": "motion",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "Client quotes beside a 3×3 grid of soft tiles: the active client's logo sits in the centre tile and other clients' logos are faded into the corners. Dots select the quote and it can auto-advance. Part of the `/motion` entry point ([overview](Motion.md)).",
+        "props": [
+          {
+            "prop": "items",
+            "type": "`{ id?, quote: ReactNode, name: ReactNode, role?: ReactNode, logo?: { src, alt } | ReactNode }[]`",
+            "default": "[]",
+            "description": "**Required.** One entry per quote. With no items it renders nothing"
+          },
+          {
+            "prop": "autoplay",
+            "type": "`number`",
+            "default": "6000",
+            "description": "Auto-advance interval in ms; `0` disables. Pauses on hover, while focus is inside, while off screen, with the Pause button and under reduced motion"
+          },
+          {
+            "prop": "grid",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "Show the 3×3 logo tile grid"
+          },
+          {
+            "prop": "label",
+            "type": "`string`",
+            "default": "\"Testimonials\"",
+            "description": "Accessible name of the section"
+          },
+          {
+            "prop": "className",
+            "type": "`string`",
+            "default": "",
+            "description": "Extra classes for the root `<section>` (merged with `cn`)"
+          },
+          {
+            "prop": "ref",
+            "type": "`Ref<HTMLElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<section>`"
+          },
+          {
+            "prop": "...rest",
+            "type": "`HTMLAttributes<HTMLElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<section>`"
+          }
+        ],
+        "examples": "```jsx\n<TestimonialSpotlight\n  items={[\n    { quote: 'They shipped our school app in eight weeks.', name: 'Asha Rao', role: 'Principal', logo: { src: '/logos/schoo360.svg', alt: 'Schoo360' } },\n    { quote: 'Billing went from a weekend chore to a button.', name: 'Ravi Kumar', role: 'Founder', logo: { src: '/logos/billpro.svg', alt: 'BillPro' } },\n  ]}\n/>\n\n<TestimonialSpotlight items={quotes} grid={false} autoplay={0} />\n```"
+      },
+      {
+        "name": "PhotoCollage",
+        "group": "motion",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "Overlapping, offset photos with floating stat chips and an optional badge (for example a [RotatingBadge](RotatingBadge.md)). On scroll the photos drift at different depths (parallax), driven by a CSS variable — no re-renders. Part of the `/motion` entry point ([overview](Motion.md)).",
+        "props": [
+          {
+            "prop": "images",
+            "type": "`{ src: string; alt: string }[]`",
+            "default": "[]",
+            "description": "**Required.** 1–4 photos, placed in fixed overlapping slots (extra photos are ignored)"
+          },
+          {
+            "prop": "chips",
+            "type": "`{ value: ReactNode; label: ReactNode }[]`",
+            "default": "[]",
+            "description": "Floating stat chips, up to 2"
+          },
+          {
+            "prop": "parallax",
+            "type": "`number`",
+            "default": "0.15",
+            "description": "Parallax strength (0–1): a photo moves up to ±`parallax` × 120 px × its depth. `0` disables"
+          },
+          {
+            "prop": "badge",
+            "type": "`ReactNode`",
+            "default": "",
+            "description": "A node pinned to the top-right corner"
+          },
+          {
+            "prop": "className",
+            "type": "`string`",
+            "default": "",
+            "description": "Extra classes for the root `<div>` (merged with `cn`; default `max-w-xl`, aspect 5:6)"
+          },
+          {
+            "prop": "ref",
+            "type": "`Ref<HTMLDivElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<div>`"
+          },
+          {
+            "prop": "...rest",
+            "type": "`HTMLAttributes<HTMLDivElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<div>`"
+          }
+        ],
+        "examples": "```jsx\n<PhotoCollage\n  images={[\n    { src: '/img/team.jpg', alt: 'The team at a whiteboard' },\n    { src: '/img/office.jpg', alt: 'Our office' },\n    { src: '/img/desk.jpg', alt: 'A desk with sketches' },\n  ]}\n  chips={[{ value: '2012', label: 'Founded' }, { value: '50+', label: 'People' }]}\n  badge={<RotatingBadge text=\"DREAMTREE • SINCE 2012 • \" className=\"bg-warning-300 text-gray-950\" />}\n/>\n```"
+      },
+      {
+        "name": "RotatingBadge",
+        "group": "motion",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "A circular badge with text set around its edge, slowly turning (SVG `textPath`). The text is spread to fill the circle exactly, so repeat it with separators. Part of the `/motion` entry point ([overview](Motion.md)).",
+        "props": [
+          {
+            "prop": "text",
+            "type": "`string`",
+            "default": "",
+            "description": "**Required.** Text set around the circle, e.g. `\"DREAMTREE • SINCE 2012 • \"`. Also the accessible name"
+          },
+          {
+            "prop": "speed",
+            "type": "`number`",
+            "default": "14",
+            "description": "Seconds per turn"
+          },
+          {
+            "prop": "size",
+            "type": "`number`",
+            "default": "120",
+            "description": "Diameter in px"
+          },
+          {
+            "prop": "icon",
+            "type": "`ReactNode`",
+            "default": "",
+            "description": "Decorative node in the middle"
+          },
+          {
+            "prop": "className",
+            "type": "`string`",
+            "default": "",
+            "description": "Extra classes for the root `<div>` (merged with `cn`). The text uses `currentColor` (default `text-foreground`); add a `bg-*` for a filled disc"
+          },
+          {
+            "prop": "ref",
+            "type": "`Ref<HTMLDivElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<div>`"
+          },
+          {
+            "prop": "...rest",
+            "type": "`HTMLAttributes<HTMLDivElement>`",
+            "default": "",
+            "description": "Forwarded to the root `<div>` (`aria-label` overrides the name)"
+          }
+        ],
+        "examples": "```jsx\n<RotatingBadge text=\"DREAMTREE • SINCE 2012 • \" />\n\n<RotatingBadge\n  text=\"SCROLL • TO • EXPLORE • \"\n  size={140}\n  speed={20}\n  icon={<ArrowDown className=\"h-6 w-6\" />}\n  className=\"bg-primary-600 text-primary-foreground\"\n/>\n```"
       }
     ],
     "hooks": [
@@ -7115,6 +7985,65 @@
           }
         ],
         "examples": "```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)"
+      },
+      {
+        "name": "useScrollProgress",
+        "group": "hook",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "Scroll progress (0–1) of an element, without re-rendering React on every frame. It returns a subscription (`get()` / `subscribe(fn)`), writes the value to the element as a CSS custom property (`--dt-p` by default) and calls `onChange`. Work runs on the shared motion frame loop, and only while the element is near the viewport. The building block of `ScrollStage` and `PhotoCollage`.",
+        "props": [
+          {
+            "prop": "mode",
+            "type": "`'view'` | `'pin'`",
+            "default": "'view'",
+            "description": "`'view'`: 0 when the element's top meets the viewport bottom, 1 when its bottom leaves the viewport top. `'pin'`: 0 when its top meets the viewport top, 1 when its bottom meets the viewport bottom (the span a sticky child stays pinned)"
+          },
+          {
+            "prop": "start",
+            "type": "`number`",
+            "default": "0",
+            "description": "Start of the range (0–1) re-mapped to 0–1"
+          },
+          {
+            "prop": "end",
+            "type": "`number`",
+            "default": "1",
+            "description": "End of the range (0–1) re-mapped to 0–1"
+          },
+          {
+            "prop": "cssVar",
+            "type": "`string`",
+            "default": "'--dt-p'",
+            "description": "CSS custom property written on the element; `''` writes none"
+          },
+          {
+            "prop": "enabled",
+            "type": "`boolean`",
+            "default": "true",
+            "description": "`false` stops tracking and removes the CSS variable (pass `!reducedMotion`)"
+          },
+          {
+            "prop": "onChange",
+            "type": "`(progress: number) => void`",
+            "default": "",
+            "description": "Called with each new value, on the frame loop (not during render)"
+          }
+        ],
+        "examples": "```jsx\nfunction FadeInPanel({ children }) {\n  const ref = React.useRef(null);\n  useScrollProgress(ref, { start: 0, end: 0.4 });\n  // The variable is unset on the server and under reduced motion, so the fallback (1) shows the final state.\n  return <div ref={ref} className=\"[opacity:var(--dt-p,1)]\">{children}</div>;\n}\n```\n\n```jsx\nconst progress = useScrollProgress(ref, { mode: 'pin', onChange: (p) => video.currentTime = p * video.duration });\n```"
+      },
+      {
+        "name": "useSmoothScroll",
+        "group": "hook",
+        "familyExports": [],
+        "importFrom": "@dreamtree-org/twreact-ui/motion",
+        "peerDependencies": [],
+        "hasDoc": true,
+        "description": "Returns `{ lenis, scrollTo }` from the nearest `SmoothScrollProvider`. Outside a provider, or while smooth scroll is off (no `lenis` class, `enabled={false}`, or reduced motion), `lenis` is `null` and `scrollTo` uses native `window.scrollTo` with smooth behaviour.",
+        "props": [],
+        "examples": "```jsx\nfunction BackToTop() {\n  const { scrollTo } = useSmoothScroll();\n  return <Button onClick={() => scrollTo(0)}>Back to top</Button>;\n}\n```\n\n```jsx\nconst { scrollTo } = useSmoothScroll();\nscrollTo('#pricing', { offset: -80 }); // clear an 80px sticky nav\n```\n\n[← Component overview](README.md)"
       }
     ],
     "store": [
@@ -7172,11 +8101,12 @@
       "utility",
       "blocks",
       "charts",
-      "rich-text"
+      "rich-text",
+      "motion"
     ],
     "counts": {
-      "components": 74,
-      "hooks": 4,
+      "components": 88,
+      "hooks": 6,
       "utils": 3,
       "store": 1
     }
@@ -7191,6 +8121,7 @@
     "AvatarGroup": "# AvatarGroup\n\nOverlapping stack of `Avatar`s (assignees, participants, members). Each avatar is ringed in the `surface` colour so it reads as cut out of the one behind it, in light and dark mode. With `max`, extra avatars collapse into a \"+N\" tile.\n\n## Import\n\n```jsx\nimport { Avatar, AvatarGroup } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `children` | `ReactNode` | — | `Avatar` elements. Non-element children (`null`, `false`) are ignored |\n| `max` | `number` | — | Show at most this many avatars, then a \"+N\" overflow tile (`role=\"img\"`, `aria-label=\"N more\"`). Omit to show all |\n| `size` | `string` | `\"md\"` | `xs`, `sm`, `md`, `lg`, `xl`, `2xl`. Passed to every child that doesn't set its own `size`; also sizes the overflow tile and the overlap |\n| `className` | `string` | — | Extra CSS classes on the root (`role=\"group\"`) |\n| ...rest | — | — | Passed to the root `<div>` (e.g. `aria-label=\"Assignees\"`). The ref is forwarded to it |\n\n## Example\n\n```jsx\n<AvatarGroup max={3} size=\"sm\" aria-label=\"Assignees\">\n  <Avatar name=\"Asha Rao\" />\n  <Avatar name=\"Bilal Khan\" src=\"/bilal.jpg\" />\n  <Avatar name=\"Chen Li\" />\n  <Avatar name=\"Divya Nair\" />\n  <Avatar name=\"Esha Patel\" />\n</AvatarGroup>\n{/* Asha, Bilal, Chen, then a \"+2\" tile */}\n```\n\n[← Component overview](README.md)\n",
     "Badge": "# Badge\n\nBadge or pill for counts, labels, and status.\n\n## Import\n\n```jsx\nimport { Badge } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `variant` | `string` | `\"default\"` | `default`, `primary`, `secondary`, `success`, `warning`, `error`, `info`, `outline`. `info` uses the `info` palette (`bg-info-100 text-info-800`). Every variant has dark-mode tones; `outline` has its own text colour (`text-gray-700`, `dark:text-gray-200`) |\n| `size` | `string` | `\"md\"` | `xs`, `sm`, `md`, `lg`, `xl`, `2xl` (unknown values fall back to `md`) |\n| `rounded` | `boolean` | `true` | Rounded pill when true |\n| `dot` | `boolean` | `false` | Leading decorative dot in the current text colour (e.g. a \"Live\" badge) |\n| `icon` | `ReactNode` | — | Leading decorative icon slot (`h-3.5 w-3.5`, `aria-hidden`) |\n| `max` | `number` | — | When `children` is a number above `max`, renders `${max}+` (e.g. `max={99}` shows `99+`). Ignored for non-numeric children |\n| `className` | `string` | — | Extra CSS classes |\n| `children` | `ReactNode` | — | Badge content |\n\n## Example\n\n```jsx\n<Badge>New</Badge>\n<Badge variant=\"success\">Active</Badge>\n<Badge variant=\"error\" size=\"sm\">3</Badge>\n<Badge dot variant=\"success\">Live</Badge>\n<Badge icon={<Star />} variant=\"warning\">Featured</Badge>\n<Badge variant=\"error\" max={99}>{120}</Badge> {/* 99+ */}\n```\n\n[← Component overview](README.md)\n",
     "BarChart": "# BarChart\n\nThemed, responsive bar chart — grouped, stacked or horizontal — with token colours, an accessible data-table fallback and reduced-motion support. 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 { BarChart } 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| `index` | `string` | — | **Required.** Key of the x-axis (category) value in each row, e.g. `\"month\"`. |\n| `categories` | `string[]` | — | **Required.** Keys of the numeric series, one bar per key. |\n| `colors` | `ChartColor[]` | `primary, success, warning, error, info, secondary, gray` | Series colours by position (cycled). 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| `xAxisFormatter` | `(value) => string` | — | Formats category (x-axis) tick labels and the hidden table's row headers. |\n| `showLegend` | `boolean` | `true` | Legend below the chart (real DOM text). |\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 value-axis labels, px. When set, it is used at every width. |\n| `stacked` | `boolean` | `false` | Stack the series in one bar per category. |\n| `horizontal` | `boolean` | `false` | Horizontal bars: categories on the y-axis (every label shown), values on the x-axis. |\n| `valueFormatter` | `(value: number) => string` | `toLocaleString` | Formats values in the tooltip, value axis and hidden data table. |\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`, so the chart scales with its container (handy on phones); 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 `\"Bar 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 `data` is empty. |\n| `accessibleTable` | `boolean` | `true` | Repeat the numbers in a visually-hidden `<table>` for screen-reader users. |\n| `animate` | `boolean` | `true` | Animate on mount / data change. Always off when the user prefers reduced motion. |\n| `showTooltip` | `boolean` | `true` | Tooltip (themed, dark-mode aware): on hover with a mouse; on touch a tap pins it at the tapped point, and a second tap on the chart or a tap outside unpins it. |\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## Small screens\n\n- x-axis ticks keep a wider gap on narrow charts (`minTickGap` 32 px below 360 px wide, 16 px below 640 px, otherwise 8 px), so labels don't collide.\n- The value axis narrows to 36 px below 400 px wide unless you pass `yAxisWidth`.\n- Use `aspectRatio` instead of a fixed `height` to keep the chart proportional to its width.\n\n## Examples\n\n### Grouped\n\n```jsx\nconst data = [\n  { month: 'Jan', revenue: 4200, costs: 2600 },\n  { month: 'Feb', revenue: 5100, costs: 2900 },\n  { month: 'Mar', revenue: 4800, costs: 3100 },\n];\n\n<BarChart data={data} index=\"month\" categories={['revenue', 'costs']} colors={['primary', 'warning']} title=\"Monthly revenue and costs\" />\n```\n\n### Stacked, horizontal\n\n```jsx\n<BarChart data={data} index=\"month\" categories={['revenue', 'costs']} stacked horizontal height={240} title=\"Revenue + costs\" />\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 \"Bar chart\") |\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",
+    "BentoExpandGrid": "# BentoExpandGrid\n\nA photo grid whose active tile grows: its column and row tracks widen to `expand`fr while the neighbours shrink. Hover, keyboard focus and — with `trigger=\"click\"` — tap expand a tile, and arrow keys move between tiles, so it never depends on a mouse. Below `md` it becomes a horizontal snap scroller. Part of the `/motion` entry point ([overview](Motion.md)).\n\n## Install\n\nNothing extra — the `/motion` entry point has no required peer dependency.\n\n## Import\n\n```jsx\nimport { BentoExpandGrid } from '@dreamtree-org/twreact-ui/motion';\n```\n\nNever import it from the root `@dreamtree-org/twreact-ui` — the motion components are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `items` | `{ id?, media: { src, alt } \\| ReactNode, title: ReactNode, tag?: ReactNode, client?: ReactNode, href?: string }[]` | `[]` | **Required.** One tile per item. `href` makes the tile a link |\n| `cols` | `2` \\| `3` \\| `4` | `3` | Columns from `md` up; rows follow the item count |\n| `expand` | `number` | `2` | Track size (fr) of the active tile's row and column; the others stay `1fr` |\n| `trigger` | `\"hover\"` \\| `\"focus\"` \\| `\"click\"` | `\"hover\"` | `hover`: pointer and keyboard focus expand. `focus`: keyboard focus only. `click`: tiles are toggle buttons (`aria-pressed`) |\n| `label` | `string` | — | Accessible name of the list |\n| `className` | `string` | — | Extra classes for the root `<ul>` (merged with `cn`) |\n| `ref` | `Ref<HTMLUListElement>` | — | Forwarded to the root `<ul>` |\n| ...rest | `HTMLAttributes<HTMLUListElement>` | — | Forwarded to the root `<ul>` |\n\nFrom `md` up the grid is `min(80vh, 720px)` tall; override with a `md:h-*` class.\n\n## Examples\n\n```jsx\n<BentoExpandGrid\n  label=\"Recent projects\"\n  items={[\n    { title: 'School ERP', tag: 'Web', client: 'Schoo360', media: { src: '/work/erp.jpg', alt: 'School dashboard' }, href: '/work/erp' },\n    { title: 'Retail POS', tag: 'Mobile', client: 'TradeOS', media: { src: '/work/pos.jpg', alt: 'Point-of-sale app' } },\n  ]}\n/>\n\n<BentoExpandGrid items={projects} cols={2} trigger=\"click\" expand={2.5} />\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Semantics | A `<ul>` (named by `label`) of `<li>` tiles |\n| Tiles | A link when `href` is set, a toggle `<button aria-pressed>` with `trigger=\"click\"`, otherwise a focusable `<div tabindex=\"0\">` |\n| Keyboard | Focus expands a tile (except with `trigger=\"click\"`); ←/→ move one tile, ↑/↓ one row, Home/End jump to the first/last tile |\n| Focus | Visible `focus-visible` ring on every tile |\n| Images | `alt` is required for `{ src, alt }` media; the dark gradient overlay is `aria-hidden` |\n\n## Reduced motion & server rendering\n\nThe server renders the grid with even tracks. Under `prefers-reduced-motion: reduce` tiles still expand, but instantly (no track transition, no image zoom).\n\n[← Component overview](README.md)\n",
     "BottomActionBar": "# BottomActionBar\n\nPage-level block: a bar pinned to the bottom of the screen that holds the page's primary action on forms and checkout pages (\"Save\", \"Place order\", \"Pay now\"). It sits on the `z-sticky` layer, pads the home indicator (`pb-safe`) and the side notches (`px-safe`), and uses role tokens (`bg-surface`, a top `border-line`, a soft upward shadow), so it is dark-mode aware. On phones it **rides above the on-screen keyboard**: it follows `window.visualViewport` (resize and scroll) and lifts itself by the height the keyboard covers. This is SSR-safe: on the server and without `visualViewport` it rests at the bottom.\n\nPut a `<BottomActionBar.Spacer />` at the end of the page content so the last rows aren't hidden behind the bar.\n\n## Import\n\n```jsx\nimport { BottomActionBar } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `children` | `ReactNode` | — | The actions, usually one or two `Button`s. Put the primary action last |\n| `position` | `'fixed' \\| 'sticky'` | `\"fixed\"` | `fixed`: pinned to the bottom of the screen (`fixed inset-x-0 bottom-0`); pair it with `BottomActionBar.Spacer`. `sticky`: `sticky bottom-0` inside its scroll container; it keeps its place in the flow and needs no Spacer |\n| `align` | `'start' \\| 'center' \\| 'end' \\| 'between'` | `\"end\"` | Horizontal alignment of the actions. `between` puts e.g. a total on the left and the action on the right |\n| `fullWidth` | `boolean` | `false` | Below `sm` (phones), the actions share the row's width equally |\n| `stackOnMobile` | `boolean` | `false` | Below `sm`, the actions stack full-width with the last (primary) one on top |\n| `keyboardAware` | `boolean` | `true` | Rise above the on-screen keyboard via `window.visualViewport`. While lifted the bar drops its `pb-safe` pad (the keyboard covers the home indicator) and sets `data-keyboard=\"open\"` |\n| `className` | `string` | — | Extra classes for the bar (merged with `cn`, so yours win) |\n| ...rest | `HTMLAttributes<HTMLDivElement>` | — | Forwarded to the bar (`aria-label`, `role`, `data-*`, …). The ref is forwarded to it |\n\nThe bar also sets `data-position=\"fixed\" | \"sticky\"`. Its content row is centred with `max-w-7xl` and the same horizontal padding as `AppShell`'s `<main>`.\n\n## BottomActionBar.Spacer\n\n`<BottomActionBar.Spacer />` renders an `aria-hidden` block as tall as the fixed bar. The bar measures itself (with `ResizeObserver`) and publishes its height as the CSS variable `--dt-bottom-action-bar-height` on `<html>`; the Spacer reads it, so it matches stacked layouts and the safe area. Before the bar has measured, it falls back to `4.5rem` plus the bottom safe area. Accepts `className` (e.g. `sm:hidden` when the bar only shows on phones), `...rest` and a ref.\n\n## Examples\n\n### Form\n\n```jsx\n<form onSubmit={save}>\n  <Input label=\"Customer name\" />\n  <Input label=\"Amount\" inputMode=\"decimal\" />\n  <BottomActionBar.Spacer />\n  <BottomActionBar fullWidth>\n    <Button variant=\"outline\" onClick={cancel}>Cancel</Button>\n    <Button type=\"submit\">Save payment</Button>\n  </BottomActionBar>\n</form>\n```\n\n### Checkout\n\n```jsx\n<BottomActionBar align=\"between\" aria-label=\"Checkout\">\n  <div>\n    <p className=\"text-xs text-muted\">Total</p>\n    <p className=\"text-lg font-semibold\">₹4,820.00</p>\n  </div>\n  <Button>Pay now</Button>\n</BottomActionBar>\n```\n\n### Stacked on phones\n\n```jsx\n<BottomActionBar stackOnMobile>\n  <Button variant=\"outline\">Save draft</Button>\n  <Button>Send invoice</Button>\n</BottomActionBar>\n```\n\n### Inside a scrolling panel\n\n```jsx\n<div className=\"h-96 overflow-y-auto\">\n  {steps}\n  <BottomActionBar position=\"sticky\">\n    <Button variant=\"outline\">Back</Button>\n    <Button>Continue</Button>\n  </BottomActionBar>\n</div>\n```\n\n`PageHeader` uses this bar for `actionsPlacement=\"bottom\"`.\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Semantics | A plain `<div>`; its actions keep their own roles and DOM order, so Tab order is the visual order (with `stackOnMobile` the primary action is shown on top but stays last in Tab order). Pass `role=\"region\"` + `aria-label` if the bar needs a landmark |\n| Keyboard | The bar lifts above the on-screen keyboard, so the action stays visible and tappable while a field is focused |\n| Touch | Use `Button`s, which are 44px tall on coarse pointers |\n| Motion | The lift animates `bottom` for `duration-fast`; off under `prefers-reduced-motion` |\n| Dark mode | `bg-surface`, `border-line` and `text-foreground` switch with the theme; the shadow deepens via `--dt-shadow-strength` |\n\n[← Component overview](README.md)\n",
     "Breadcrumbs": "# Breadcrumbs\n\nBreadcrumb navigation trail. Optional home link and custom separator.\n\n## Import\n\n```jsx\nimport { Breadcrumbs } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `items` | `Array` | `[]` | `[{ id?, label, href?, icon?, onClick? }]` — `id` is optional; it is the React key when present, otherwise an index-based key is used (no key warning) |\n| `separator` | `ReactNode` | `<ChevronRight />` | Separator between items |\n| `showHome` | `boolean` | `true` | Prepend Home link |\n| `homeIcon` | `ReactNode` | — | Icon for Home |\n| `onHomeClick` | `function` | — | Home click handler |\n| `maxItems` | `number` | — (no collapse) | When the trail (Home included) has more crumbs than this, show the first crumb, an \"…\" button, and the last `maxItems - 1` crumbs. Clicking \"…\" expands the full trail and moves focus to the first revealed crumb. Values below 2 are treated as 2. |\n| `className` | `string` | — | Extra CSS classes |\n\nLong labels truncate with an ellipsis (`max-w-[10rem]`, `sm:max-w-[16rem]`), and the full text stays available as a `title` tooltip when the label is a string. Links underline on hover, show a `focus-visible` ring, and have dark-mode colours. The \"…\" button grows to a 44 px touch target on coarse pointers.\n\n## Example\n\n```jsx\n<Breadcrumbs\n  items={[\n    { id: '1', label: 'Products', href: '/products' },\n    { id: '2', label: 'Category', href: '/products/cat' },\n    { id: '3', label: 'Current Page' },\n  ]}\n  showHome\n/>\n```\n\nCollapsed trail (Home / … / Board / Card):\n\n```jsx\n<Breadcrumbs maxItems={3} items={[\n  { id: 'org', label: 'Org', href: '/o' },\n  { id: 'team', label: 'Team', href: '/o/t' },\n  { id: 'board', label: 'Board', href: '/o/t/b' },\n  { id: 'card', label: 'Card' },\n]} />\n```\n\n[← Component overview](README.md)\n",
     "Button": "# Button\n\nButton with variants, sizes, loading state, and optional left/right icons.\n\n## Import\n\n```jsx\nimport { Button } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `variant` | `string` | `\"primary\"` | `primary`, `secondary`, `outline`, `ghost`, `destructive`, `success`, `warning`, `link`. `link` is a text link: no background, border or padding, underlined on hover, the usual focus ring, and 44px tall on coarse pointers |\n| `tone` | `\"primary\"` \\| `\"secondary\"` \\| `\"success\"` \\| `\"warning\"` \\| `\"error\"` \\| `\"info\"` | `\"primary\"` | Text colour when `variant=\"link\"` (e.g. `error` inside an error-tinted card). Ignored by the other variants |\n| `size` | `string` | `\"md\"` | `xs` (h-7), `sm` (h-8), `md` (h-10), `lg` (h-12), `xl` (h-14), `2xl` (h-16) — every value of the shared `Size` type — plus the square icon-only sizes `icon-sm` (32px), `icon` (40px), `icon-lg` (48px); pair an icon size with `aria-label`. `xs`, `sm`, `icon-sm` and `icon` grow to 44px on coarse pointers (touch) |\n| `disabled` | `boolean` | — | Disable button |\n| `loading` | `boolean` | — | Disable and overlay a centred spinner. The label (and icons) stay in the layout at `opacity-0`, so the button keeps its width and its accessible name; sets `aria-busy=\"true\"` |\n| `leftIcon` | `ReactNode` | — | Icon before children |\n| `rightIcon` | `ReactNode` | — | Icon after children |\n| `fullWidth` | `boolean` | — | Full width |\n| `as` | `ElementType` | `\"button\"` | Render as another element or component with the Button's variants, sizes and focus ring, e.g. `\"a\"` or a router `Link` |\n| `href` | `string` | — | Link target. A bare `href` (no `as`) renders an `<a>` |\n| `className` | `string` | — | Extra CSS classes |\n| ...rest | — | — | Passed to the rendered element (native `<button>` by default; `to`, `target`, `rel` etc. reach a link) |\n\n### As a link\n\n```jsx\n<Button href=\"tel:+919800000000\" variant=\"outline\">Call</Button>\n<Button as=\"a\" href=\"https://wa.me/919800000000\" target=\"_blank\" rel=\"noopener noreferrer\">WhatsApp</Button>\n<Button as={Link} to=\"/move-in\">Move in</Button>\n```\n\nA link can't be `disabled`; with `disabled` or `loading` it gets `aria-disabled=\"true\"`, `tabIndex={-1}`, the disabled styling, and its click is prevented.\n\n### Text link\n\n`variant=\"link\"` looks like an inline link but stays a button, for actions inside a card. Give it an `href` (or `as`) when it really navigates.\n\n```jsx\n<Button variant=\"link\" rightIcon=\"→\" onClick={showPayments}>All payments</Button>\n<Button variant=\"link\" tone=\"error\" rightIcon=\"→\" onClick={scrollToDues}>See who owes</Button>\n<Button variant=\"link\" as={Link} to=\"/settlements\">Open full settlement</Button>\n```\n\nEvery variant has `dark:` colours, and the focus ring offset matches a dark page. Buttons shrink slightly while pressed (`active:scale-[0.97]`, off under `prefers-reduced-motion`).\n\n## Examples\n\n### Basic\n\n```jsx\n<Button variant=\"primary\">Save</Button>\n<Button variant=\"outline\">Cancel</Button>\n```\n\n### Sizes and loading\n\n```jsx\n<Button size=\"xs\">Extra small</Button>\n<Button size=\"sm\">Small</Button>\n<Button size=\"lg\">Large</Button>\n<Button size=\"xl\">Extra large</Button>\n<Button loading>Saving...</Button>\n```\n\n### With icons\n\n```jsx\nimport { Download } from 'lucide-react';\n\n<Button leftIcon={<Download className=\"h-4 w-4\" />}>Download</Button>\n```\n\n### Icon-only\n\n```jsx\nimport { Plus } from 'lucide-react';\n\n<Button size=\"icon\" variant=\"outline\" aria-label=\"Add\"><Plus className=\"h-4 w-4\" /></Button>\n<Button size=\"icon-sm\" variant=\"ghost\" aria-label=\"Add\"><Plus className=\"h-4 w-4\" /></Button>\n```\n\n[← Component overview](README.md)\n",
@@ -7200,8 +8131,11 @@
     "ColorPicker": "# ColorPicker\n\nColor picker with optional swatches, hex input, HSL sliders, and alpha. Value can be hex or rgba string; `onChange` receives normalized `rgba(r,g,b,a)` string.\n\n## Import\n\n```jsx\nimport { ColorPicker } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `string` | — | Controlled value (hex or rgba string). |\n| `defaultValue` | `string` | — | Uncontrolled initial value. |\n| `onChange` | `(rgbaString: string) => void` | — | Called with normalized `rgba(r,g,b,a)` string. |\n| `swatches` | `string[]` | — | Array of hex/rgba strings for preset swatches. |\n| `showAlpha` | `boolean` | `false` | Show the alpha slider (the library `Slider`, labelled \"Alpha\", value shown as a percentage). When off (or when the alpha channel is fully opaque), the displayed hex is the 6-char `#rrggbb` form; the 8-char `#rrggbbff` form is shown only when `showAlpha` is on **and** alpha < 1. |\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `\"md\"` | Picker size. Other `Size` values (`xs`, `xl`, `2xl`) fall back to `md` (they used to crash). |\n| `disabled` | `boolean` | — | Disable the picker. |\n| `className` | `string` | — | Wrapper CSS classes. |\n| `label` | `string` | `\"Pick a color\"` | Label text. Associated with the color value text input (`htmlFor`). |\n| `id` | `string` | auto (`useId`) | Id of the color value text input; the label's `htmlFor` points at it. |\n\n## Example\n\n```jsx\nconst [color, setColor] = useState('#3b82f6');\n<ColorPicker\n  value={color}\n  onChange={setColor}\n  swatches={['#ef4444', '#22c55e', '#3b82f6']}\n  showAlpha\n  label=\"Background\"\n/>\n```\n\n## Notes\n\n- Forwards `ref` to the root wrapper element and spreads unknown props (`...rest`,\n  e.g. `data-*`) onto it. `className` is merged via `cn()` so caller classes win\n  on Tailwind conflicts.\n- The default render (no `showAlpha`) displays the 6-char `#rrggbb` value.\n- The alpha control is the core [`Slider`](Slider.md) (`role=\"slider\"`, keyboard,\n  pointer and touch drag), replacing the old native range input and its fixed\n  144 px label column. When disabled the thumb is `aria-disabled=\"true\"`.\n- The swatch matching the current colour is marked with `aria-pressed=\"true\"`\n  and a `ring-2 ring-primary-500` ring; the others have `aria-pressed=\"false\"`.\n  Swatches sit in a `role=\"group\"` labelled \"Swatches\".\n- Layout stacks on phones: the 220 px minimum width of the value panel applies\n  only from the `sm` breakpoint up. Borders and the text input use the\n  `border-line` / `bg-surface` / `text-foreground` role tokens (dark-mode safe).\n\n[← Component overview](README.md)\n",
     "Condition": "# Condition\n\nRenders `children` when a condition is true, otherwise renders `fallback`. Simple conditional wrapper with no extra DOM when not needed.\n\n## Import\n\n```jsx\nimport { Condition } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `condition` | `boolean` | — | When true, render `children`; when false, render `fallback`. |\n| `children` | `ReactNode` | — | Content when condition is true. |\n| `fallback` | `ReactNode` | `null` | Content when condition is false. |\n\n## Example\n\n```jsx\n<Condition condition={isLoggedIn}>\n  <Dashboard />\n</Condition>\n\n<Condition condition={loading} fallback={<Loader />}>\n  <Content />\n</Condition>\n\n<Condition condition={hasError} fallback={<Alert variant=\"error\">Error</Alert>}>\n  <Data />\n</Condition>\n```\n\n[← Component overview](README.md)\n",
     "ConfirmDialog": "# ConfirmDialog\n\nPage-level block: the confirmation step for delete, remove, archive or cancel — replaces native `confirm()`. The title asks the question, one line says what happens, and the action button is named with the verb. Extracted from firepro `components/ui/confirm-dialog.tsx`.\n\n## Import\n\n```jsx\nimport { ConfirmDialog } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `isOpen` | `boolean` | — | Whether the dialog is open |\n| `title` | `string` | — | The action as a question |\n| `description` | `ReactNode` | — | One line saying what will happen |\n| `confirmLabel` | `string` | — | The verb, e.g. \"Remove\" (never \"OK\") |\n| `cancelLabel` | `string` | `\"Cancel\"` | Cancel button label |\n| `destructive` | `boolean` | `false` | Red confirm button for actions that can't be undone |\n| `loading` | `boolean` | `false` | Busy confirm button; the dialog can't be dismissed |\n| `onConfirm` | `() => void` | — | Called on confirm |\n| `onCancel` | `() => void` | — | Called on cancel, Esc or backdrop click |\n| `presentation` | `string` | `\"auto\"` | `auto`, `popover`, `sheet`. As [Dialog](Dialog.md#presentation): bottom sheet on coarse-pointer phones, centred modal elsewhere |\n| `haptics` | `boolean` | `false` | Opt-in vibration: `warning` once when it opens with `destructive`, `success` when the confirm button is pressed. Cancel stays silent. No-op without `navigator.vibrate` (iOS Safari) and under reduced motion. See [useHaptics](useHaptics.md) |\n\n`ref`, `className` and other props are forwarded to the underlying [Dialog](Dialog.md) panel.\n\n## Layout\n\n- **Centred modal:** the buttons sit in a row on the right from `sm` up and stack below it.\n- **Sheet:** both buttons are full width and stacked. The confirm button is on\n  top and Cancel is below it. In the DOM, and so in Tab order, Cancel comes\n  first, as in the centred layout.\n\n## Example\n\n```jsx\n<ConfirmDialog\n  isOpen={open}\n  title=\"Remove Kiran M from Diwali buyers?\"\n  description=\"They stop receiving this list's campaigns.\"\n  confirmLabel=\"Remove\"\n  destructive\n  onConfirm={remove}\n  onCancel={() => setOpen(false)}\n/>\n\n// Keep the centred modal on phones too:\n<ConfirmDialog\n  presentation=\"popover\"\n  isOpen={open}\n  title=\"Archive this list?\"\n  confirmLabel=\"Archive\"\n  onConfirm={archive}\n  onCancel={() => setOpen(false)}\n/>\n```\n\n[← Component overview](README.md)\n",
+    "CountUp": "# CountUp\n\nA number that counts up from `from` to `value` when it scrolls into view. The server, no-JS readers and reduced-motion users get the real final value, so crawlers never see \"0\". Formats with `Intl.NumberFormat` (Indian grouping by default). Part of the `/motion` entry point ([overview](Motion.md)). For a row of stats, use [StatStrip](StatStrip.md).\n\n## Install\n\nNothing extra — the `/motion` entry point has no required peer dependency.\n\n## Import\n\n```jsx\nimport { CountUp } from '@dreamtree-org/twreact-ui/motion';\n```\n\nNever import it from the root `@dreamtree-org/twreact-ui` — the motion components are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `number` | — | **Required.** The final number, rendered as-is on the server and under reduced motion |\n| `from` | `number` | `0` | Number the animation starts from |\n| `prefix` | `ReactNode` | — | Text before the number, e.g. `\"₹\"` |\n| `suffix` | `ReactNode` | — | Text after the number, e.g. `\"+\"`, `\"%\"`, `\" Cr\"` |\n| `duration` | `number` | `1600` | Animation length in ms (ease-out). `0` disables the animation |\n| `decimals` | `number` | as many as `value` has | Fraction digits |\n| `locale` | `string` | `\"en-IN\"` | `Intl.NumberFormat` locale (`en-IN` groups as 12,50,000) |\n| `format` | `(value: number) => string` | — | Custom formatter; overrides `locale` and `decimals` |\n| `className` | `string` | — | Extra classes for the root `<span>` (merged with `cn`; `tabular-nums` is always set) |\n| `ref` | `Ref<HTMLSpanElement>` | — | Forwarded to the root `<span>` |\n| ...rest | `HTMLAttributes<HTMLSpanElement>` | — | Forwarded to the root `<span>` |\n\n## Examples\n\n```jsx\n<CountUp value={500} suffix=\"+\" className=\"text-kpi font-semibold\" />\n\n<CountUp value={2500000} prefix=\"₹\" />            {/* ₹25,00,000 */}\n\n<CountUp value={98.5} suffix=\"%\" locale=\"en-US\" />\n\n<CountUp value={50} format={(n) => `${Math.round(n)} Cr`} />\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Final value | Screen readers read the final value once, from a visually hidden copy |\n| Animation | The animating digits are `aria-hidden`, so no intermediate numbers are announced |\n| Layout | `tabular-nums` keeps the width steady while counting |\n\n## Reduced motion & server rendering\n\nThe server renders the final formatted value. After hydration, a counter below the fold switches to `from` and counts up once it is 40 % visible; a counter already on screen counts up right away. Under `prefers-reduced-motion: reduce` (or with `duration={0}`) it shows the final value and never animates. On unmount the final value is restored.\n\n[← Component overview](README.md)\n",
     "DatePicker": "# DatePicker\n\nSingle date picker with calendar popup. Accepts `Date` or ISO date string; supports min/max, clear button, and optional portal rendering. The trigger uses the semantic `bg-surface` / `border-line` / `text-foreground` tokens (like the calendar popover), so it follows dark mode.\n\n## Import\n\n```jsx\nimport { DatePicker } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `Date` \\| `string` | — | Selected date (Date or ISO string). |\n| `onChange` | `(date: Date \\| null) => void` | — | Called when date changes. |\n| `placeholder` | `string` | `\"Select date...\"` | Input placeholder. While no date is chosen it renders in the muted role colour (`text-muted`, like `Input`'s `::placeholder`) and the trigger carries `data-empty`; a `className` colour still wins (merged last). |\n| `label` | `string` | — | Label text. Associated with the trigger (`<label for>` + `aria-labelledby`), so the accessible name is the label followed by the displayed value. |\n| `error` | `string` | — | Error message. Sets `aria-invalid`; replaces `helperText` while shown. |\n| `helperText` | `ReactNode` | — | Hint below the trigger, linked via `aria-describedby`. Hidden while `error` is shown. |\n| `disabled` | `boolean` | — | Disable the picker. |\n| `required` | `boolean` | — | Required field. |\n| `minDate` | `Date` | — | Minimum selectable date. |\n| `maxDate` | `Date` | — | Maximum selectable date. |\n| `className` | `string` | — | Wrapper CSS classes. |\n| `weekStartsOn` | `0` \\| `1` | `0` | 0 = Sunday, 1 = Monday. |\n| `portal` | `boolean` | `false` | Render calendar in `document.body`. |\n| `displayFormat` | `string` | `\"MMM dd, yyyy\"` | date-fns format for display. |\n| `locale` | `Locale` | — | date-fns locale. |\n| `showClear` | `boolean` | `true` | Show the clear controls: a \"Clear date\" button overlaid on the field (a sibling `<button>`, keyboard-reachable) when a value is set, plus \"Clear\" in the calendar. |\n| `closeOnSelect` | `boolean` | `true` | Close popup on date select. |\n| `presentation` | `'auto'` \\| `'popover'` \\| `'sheet'` | `'auto'` | How the calendar opens. `auto` uses a bottom `Sheet` on coarse-pointer screens under 640px and an anchored popover elsewhere (popover on the server). Pass `'popover'` to keep the desktop popup everywhere. |\n\n## Presentation\n\n- **Popover** — anchored to the field by the shared floating engine (flips and\n  shifts to stay on screen). Fluid width `min(20rem, 100vw - 2rem)`, so it never\n  overflows a 320px screen. Stacks on the `z-popover` layer.\n- **Sheet** — the calendar opens in a bottom [`Sheet`](Sheet.md) titled with\n  `label` (or \"Select date\"). Day cells are 44px tall, swiping the grid left /\n  right changes month (vertical drags still scroll and drag the sheet), and\n  \"Clear\" / \"Today\" sit in the sticky footer. Backdrop, Escape and drag-down\n  close it.\n\n## Keyboard & accessibility\n\n- The calendar grid uses a **roving tabindex**: exactly one day is tabbable —\n  the last keyboard-focused day, else the selected day, else today (when in the\n  visible month and enabled), else the first enabled day. Opening the popup\n  moves focus to that day.\n- `ArrowLeft` / `ArrowRight` move by one day, `ArrowUp` / `ArrowDown` by one\n  week, `PageUp` / `PageDown` by one month, `Home` / `End` to the start / end of\n  the week. Moving past the month edge switches the visible month. Disabled\n  (out-of-range) days are never focused.\n- `Enter` / `Space` select the focused day; `Escape` closes the popup and\n  returns focus to the field.\n- Previous / next month buttons grow to a 44×44 px touch target on coarse\n  pointers.\n\n## Example\n\n```jsx\nconst [date, setDate] = useState(null);\n<DatePicker\n  value={date}\n  onChange={setDate}\n  placeholder=\"Select date\"\n  minDate={new Date()}\n  label=\"Start date\"\n/>\n```\n\n[← Component overview](README.md)\n",
     "DateRangePicker": "# DateRangePicker\n\nDate range picker: user selects start then end. Value is `{ start: Date, end: Date }`. The popover stays open on outside click / Escape until both are selected (or the user clears); the trigger always toggles it, and closing mid-pick drops the uncommitted start. Supports min/max, clear, preset chips, optional portal, and a phone-native bottom sheet. The trigger and preset chips use the semantic `bg-surface` / `border-line` / `text-foreground` tokens (like the calendar popover), so they follow dark mode.\n\n## Import\n\n```jsx\nimport { DateRangePicker } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `{ start: Date\\|string, end: Date\\|string }` | — | Selected range. |\n| `onChange` | `(range: { start, end } \\| null) => void` | — | Called when range changes. |\n| `placeholder` | `string` | `\"Select date range...\"` | Input placeholder. Until both start and end are committed it renders in the muted role colour (`text-muted`, like `Input`'s `::placeholder`) and the trigger carries `data-empty`; a `className` colour still wins (merged last). |\n| `label` | `string` | — | Label text. Associated with the trigger (`<label for>` + `aria-labelledby`), so the accessible name is the label followed by the displayed value. |\n| `error` | `string` | — | Error message. Sets `aria-invalid`; replaces `helperText` while shown. |\n| `helperText` | `ReactNode` | — | Hint below the trigger, linked via `aria-describedby`. Hidden while `error` is shown. |\n| `disabled` | `boolean` | — | Disable. |\n| `required` | `boolean` | — | Required. |\n| `minDate` | `Date` | — | Minimum selectable date. |\n| `maxDate` | `Date` | — | Maximum selectable date. |\n| `className` | `string` | — | Wrapper CSS classes. |\n| `weekStartsOn` | `0` \\| `1` | `0` | 0 = Sunday, 1 = Monday. |\n| `portal` | `boolean` | `false` | Render popup in document.body. |\n| `displayFormat` | `string` | `\"MMM dd, yyyy\"` | date-fns format for display. |\n| `locale` | `Locale` | — | date-fns locale. |\n| `showClear` | `boolean` | `true` | Show the clear button (`aria-label=\"Clear range\"`) once a date is picked. It sits beside the trigger, not inside it, and is hidden while `disabled`. |\n| `closeOnSelect` | `boolean` | `true` | Close when both dates selected (popover). The sheet always closes on \"Apply\". |\n| `presentation` | `'auto'` \\| `'popover'` \\| `'sheet'` | `'auto'` | How the calendar opens. `auto` uses a bottom `Sheet` on coarse-pointer screens under 640px and an anchored popover elsewhere (popover on the server). Pass `'popover'` to keep the desktop popup everywhere. |\n| `presets` | `{ label: string, range: [Date\\|string, Date\\|string] }[]` | — | Quick-pick chips above the calendar. In the popover a chip commits its range (`onChange`) at once; in the sheet it fills the draft for \"Apply\". The chip matching the current selection has `aria-pressed=\"true\"`. |\n\n## Presentation\n\n- **Popover** — anchored to the field by the shared floating engine (flips and\n  shifts to stay on screen). Fluid width `min(20rem, 100vw - 2rem)`, so it never\n  overflows a 320px screen. Stacks on the `z-popover` layer. Clicking the second\n  date commits the range.\n- **Sheet** — the calendar opens in a bottom [`Sheet`](Sheet.md) titled with\n  `label` (or \"Select date range\"). Day cells are 44px tall and swiping the grid\n  left / right changes month (vertical drags still scroll and drag the sheet).\n  Tap the start, then the end: the days in between are highlighted straight\n  away, no hover needed. Picks are a **draft** until the sticky-footer\n  **Apply** (`onChange({ start, end })`); **Clear** fires `onChange(null)`.\n  Dismissing the sheet (backdrop, Escape, drag down, close button) discards the\n  draft.\n\n## Keyboard & accessibility\n\n- The grid is `role=\"grid\"` (`aria-multiselectable`) with `role=\"row\"` weeks.\n  Each day is a `gridcell` button labelled with its full date (for example\n  \"Friday, 30 October 2026\", formatted with `locale`), `aria-selected` on the\n  start, end and in-range days, and `aria-current=\"date\"` on today.\n- **Roving tabindex**: one day is tabbable — the last focused day, else the\n  range end / start, else today, else the first enabled day. Opening the popover\n  focuses it.\n- `ArrowLeft` / `ArrowRight` move by one day, `ArrowUp` / `ArrowDown` by one\n  week, `PageUp` / `PageDown` by one month, `Home` / `End` to the start / end of\n  the week; crossing the month edge switches the visible month. Disabled days\n  are never focused. `Enter` / `Space` pick the focused day.\n- While picking the end, the range up to the hovered **or keyboard-focused** day\n  is previewed.\n- `Escape` closes the popover (ignored while only a start is picked) and returns\n  focus to the field.\n\n## Example\n\n```jsx\nconst [range, setRange] = useState({ start: null, end: null });\n<DateRangePicker value={range} onChange={setRange} label=\"Period\" />\n```\n\nWith presets:\n\n```jsx\nconst day = 24 * 60 * 60 * 1000;\n<DateRangePicker\n  value={range}\n  onChange={setRange}\n  label=\"Report period\"\n  presets={[\n    { label: 'Last 7 days', range: [new Date(Date.now() - 6 * day), new Date()] },\n    { label: 'Last 30 days', range: [new Date(Date.now() - 29 * day), new Date()] },\n  ]}\n/>\n```\n\n[← Component overview](README.md)\n",
+    "DeviceFrame": "# DeviceFrame\n\nA CSS-only device mock-up — phone, tablet, laptop or browser window — around any screen content. Purely presentational: no motion, no images, works anywhere (feature sections, docs, the [DeviceMorphHero](DeviceMorphHero.md)). Part of the `/motion` entry point ([overview](Motion.md)).\n\n## Install\n\nNothing extra — the `/motion` entry point has no required peer dependency.\n\n## Import\n\n```jsx\nimport { DeviceFrame } from '@dreamtree-org/twreact-ui/motion';\n```\n\nNever import it from the root `@dreamtree-org/twreact-ui` — the motion components are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `device` | `\"phone\"` \\| `\"tablet\"` \\| `\"laptop\"` \\| `\"browser\"` | `\"phone\"` | Frame style. Widths: phone 220 px (262 px from `md`), tablet 320/440 px, laptop 340/640 px, browser 340/720 px; height follows the device's aspect ratio |\n| `children` | `ReactNode` | — | Screen content (fills the screen box, which clips it) |\n| `url` | `string` | — | Address shown in the `browser` frame's bar |\n| `screenClassName` | `string` | — | Classes for the screen box (default background `bg-surface`) |\n| `className` | `string` | — | Extra classes for the root `<div>` (merged with `cn`; override the width with a `w-*` class) |\n| `ref` | `Ref<HTMLDivElement>` | — | Forwarded to the root `<div>` |\n| ...rest | `HTMLAttributes<HTMLDivElement>` | — | Forwarded to the root `<div>` |\n\n## Examples\n\n```jsx\n<DeviceFrame device=\"phone\">\n  <img src=\"/screens/home.png\" alt=\"The app's home screen\" className=\"h-full w-full object-cover\" />\n</DeviceFrame>\n\n<DeviceFrame device=\"browser\" url=\"dreamtree.in\" className=\"w-full max-w-3xl\">\n  <Dashboard />\n</DeviceFrame>\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Bezel | The bezel, notch, buttons, home bar and browser bar dots are `aria-hidden`; only the screen content is exposed |\n| Content | Give screenshots real `alt` text, or `alt=\"\"` if they repeat nearby copy |\n| Colours | Bezel parts use the gray scale; the browser dots use the `error`, `warning` and `success` tokens |\n| Root data | The root carries `data-device=\"<device>\"` |\n\n## Reduced motion & server rendering\n\nStatic markup with no effects: identical on the server, the client and under reduced motion. The bezel parts read `opacity: var(--dt-chrome, 1)`, which `DeviceMorphHero` uses to fade them in.\n\n[← Component overview](README.md)\n",
+    "DeviceMorphHero": "# DeviceMorphHero\n\nA scroll hero in three steps: full-bleed media (video or image) shrinks into a device screen, the device's bezel fades in, then the device slides aside while your copy fades in beside it. Built on [ScrollStage](ScrollStage.md) and [DeviceFrame](DeviceFrame.md). Part of the `/motion` entry point ([overview](Motion.md)).\n\n## Install\n\nNothing extra — the `/motion` entry point has no required peer dependency.\n\n## Import\n\n```jsx\nimport { DeviceMorphHero } from '@dreamtree-org/twreact-ui/motion';\n```\n\nNever import it from the root `@dreamtree-org/twreact-ui` — the motion components are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `media` | `{ video?: string; image?: string; poster?: string; alt?: string }` | — | **Required.** A muted, looping, inline `video` (with `poster`), or an `image`. `alt` is the text alternative; leave it empty to mark the media decorative |\n| `device` | `\"phone\"` \\| `\"tablet\"` \\| `\"laptop\"` \\| `\"browser\"` | `\"phone\"` | The device the media shrinks into |\n| `length` | `number` | `300` | Scene length in vh on desktop, capped at 400 |\n| `mobileLength` | `number` | `150` | Scene length in vh below `md`, capped at 400 |\n| `side` | `\"right\"` \\| `\"left\"` | `\"right\"` | Side the device slides to; the copy takes the other half |\n| `content` | `ReactNode` | — | Copy that fades in beside the device: logo, headline, CTAs, stats |\n| `scrollHint` | `ReactNode` \\| `false` | `\"Scroll to explore\"` | Label of a button that skips to the end of the scene; `false` hides it |\n| `className` | `string` | — | Extra classes for the root `<section>` (merged with `cn`) |\n| `ref` | `Ref<HTMLElement>` | — | Forwarded to the root `<section>` |\n| ...rest | `HTMLAttributes<HTMLElement>` | — | Forwarded to the root `<section>` |\n\n## Examples\n\n```jsx\n<DeviceMorphHero\n  media={{ video: '/intro.mp4', poster: '/intro.jpg', alt: 'A tour of the app' }}\n  device=\"phone\"\n  content={\n    <>\n      <h1 className=\"text-page-title\">Software that tells your story.</h1>\n      <Button>Start a project</Button>\n    </>\n  }\n/>\n\n<DeviceMorphHero media={{ image: '/hero.jpg', alt: '' }} device=\"laptop\" side=\"left\" length={250} content={<HeroCopy />} />\n```\n\n### Timeline\n\nProgress through the scene (0–1): **0–45 %** the media shrinks from full-bleed to the screen; **40–60 %** the bezel fades in; **60–90 %** the device slides aside (22 % of the viewport width) and the copy fades in; the rest holds. Below `md` the device rises and shrinks to 62 % instead, and the copy appears in the lower part of the screen (scrolls if taller than 45 % of it).\n\nKeep the hero video short (H.264 or WebM, about 2 MB) and always set a `poster`.\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Copy | Stays in the accessibility tree while faded out. Tabbing into it (e.g. a CTA) skips the scene to its end, so a focused element is never invisible |\n| Skip | The scroll hint is a real `<button>`; it scrolls to the end of the scene (through Lenis when inside a `SmoothScrollProvider`) |\n| Media | `alt` becomes the video's `aria-label` or the image's `alt`; an empty `alt` hides the video from assistive tech |\n| Video | `muted`, `playsInline`, `loop`, `preload=\"metadata\"`; it plays only while the hero is on screen |\n\n## Reduced motion & server rendering\n\nThe server renders the final layout without pinning: copy and device side by side (`md:grid-cols-2`), the media inside the device screen (`data-dt-hero=\"static\"`). After hydration the morph scene takes over (`data-dt-hero=\"morph\"`). Under `prefers-reduced-motion: reduce` the static layout stays, the video is paused and nothing is pinned.\n\n[← Component overview](README.md)\n",
     "Dialog": "# Dialog\n\nModal dialog with title, body, optional footer, and configurable size. Supports escape key and backdrop click to close when dismissible. On phones it presents as a bottom [Sheet](Sheet.md) by default (`presentation=\"auto\"`).\n\n## Import\n\n```jsx\nimport { Dialog } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `isOpen` | `boolean` | — | Controls visibility |\n| `onClose` | `function` | — | Called when dialog should close |\n| `title` | `string` | — | Dialog title |\n| `children` | `ReactNode` | — | Body content |\n| `size` | `string` | `\"md\"` | `sm`, `md`, `lg`, `xl`, `full` |\n| `dismissible` | `boolean` | `true` | Allow close via backdrop or Escape |\n| `showCloseButton` | `boolean` | `true` | Show X button (44×44px touch target on coarse pointers) |\n| `footer` | `ReactNode` | — | Footer content (e.g. buttons) |\n| `className` | `string` | — | Extra CSS classes |\n| `onOpen` | `function` | — | Called when dialog opens, with `{ dialogRef }` (the panel node) |\n| `presentation` | `string` | `\"auto\"` | `auto`, `popover`, `sheet`. `popover` = the centred modal; `sheet` = a bottom sheet; `auto` = sheet on coarse-pointer screens under 640px, centred modal elsewhere (and on the server) |\n| `ref` | `Ref<HTMLDivElement>` | — | Forwarded to the panel (`role=\"dialog\"`) in both presentations |\n\nAny other props (`data-*`, `aria-*`, …) are spread onto the panel.\n\nThe close (X) button grows to a 44×44px touch target on coarse pointers (`@media (pointer: coarse)`); mouse layouts keep the compact 28px button.\n\n## Presentation\n\n`presentation=\"auto\"` (the default) resolves through the shared\n`(pointer: coarse) and (max-width: 639px)` query: phones get a sheet, desktops\nand tablets get the centred modal. Pass `presentation=\"popover\"` to keep the\ncentred modal everywhere (the pre-1.5 behaviour), or `\"sheet\"` to force a sheet.\nThe panel carries `data-presentation=\"popover\" | \"sheet\"`.\n\n**Centred modal (`popover`)**\n\n- The panel is capped at the viewport height minus a 1rem gutter and the safe\n  areas (`max-h-[calc(100dvh-2rem-env(safe-area-inset-top)-env(safe-area-inset-bottom))]`).\n  Header and footer stay fixed; the body scrolls (`overflow-y-auto overscroll-contain`).\n  Because the body scrolls, an absolutely positioned dropdown you render\n  *inside* the body is clipped. The library's Select, DatePicker and Popover\n  portal their menus, so they are not affected.\n- The backdrop keeps a 1rem gutter plus `env(safe-area-inset-*)` on every side.\n- It animates in (`animate-scale-in` + backdrop `animate-fade-in`) and out\n  (`animate-scale-out` + `animate-fade-out`). It stays mounted for the ~150ms\n  exit (`data-state=\"exiting\"`, pointer events off) and then unmounts. Under\n  `prefers-reduced-motion` there is no animation and it unmounts at once.\n\n**Bottom sheet (`sheet`)**\n\n- Renders the public `Sheet` at `placement=\"bottom\"`, content height, no snap\n  points, with the grab handle. Drag-to-dismiss works only when `dismissible`;\n  a non-dismissible sheet springs back.\n- `title` becomes the sheet title (`aria-labelledby`). With no title,\n  `showCloseButton` still renders a \"Close dialog\" button in a small header row.\n  With a title, the sheet's own close button is used (labelled \"Close sheet\").\n- The body scrolls inside the sheet. `size` does not apply: the sheet is full width.\n- The `footer` stacks its children full width with `flex-col-reverse`. Put the\n  actions in the usual desktop order, secondary first, then primary\n  (`<Cancel/><Save/>`). The primary then shows **on top**, as on iOS, while\n  DOM and Tab order stay secondary → primary, as on desktop.\n- `onClose` is called with no arguments, as in the centred modal.\n\n`Escape`, backdrop click and `dismissible` behave the same in both presentations.\n\n## Examples\n\n### Basic\n\n```jsx\nconst [open, setOpen] = useState(false);\n\n<Button onClick={() => setOpen(true)}>Open</Button>\n<Dialog\n  isOpen={open}\n  onClose={() => setOpen(false)}\n  title=\"Confirm\"\n>\n  Are you sure you want to continue?\n</Dialog>\n```\n\n### Always centred / always a sheet\n\n```jsx\n<Dialog presentation=\"popover\" isOpen={open} onClose={close} title=\"Centred everywhere\">\n  Same centred modal on phones too.\n</Dialog>\n\n<Dialog presentation=\"sheet\" isOpen={open} onClose={close} title=\"Sheet everywhere\">\n  A bottom sheet on desktop too.\n</Dialog>\n```\n\n### With footer\n\n```jsx\n<Dialog\n  isOpen={open}\n  onClose={() => setOpen(false)}\n  title=\"Edit\"\n  footer={\n    <>\n      <Button variant=\"ghost\" onClick={() => setOpen(false)}>Cancel</Button>\n      <Button onClick={handleSave}>Save</Button>\n    </>\n  }\n>\n  <Input label=\"Name\" value={name} onChange={e => setName(e.target.value)} />\n</Dialog>\n```\n\n## Accessibility & keyboard\n\n`Dialog` renders `role=\"dialog\"` + `aria-modal=\"true\"` and backs that promise\nwith real focus management (no extra dependency — a built-in focus trap):\n\n| Behavior | Detail |\n|----------|--------|\n| Focus on open | Focus moves to the first focusable element inside the panel (or the panel itself when there is none). |\n| Focus trap | `Tab` / `Shift`+`Tab` cycle only through focusable elements inside the panel; focus cannot reach the page behind the modal. |\n| Focus restore | On close, focus returns to the element that had it when the dialog opened (typically the trigger). |\n| `Escape` | Closes the dialog when `dismissible` (default); ignored when `dismissible={false}`. |\n| Backdrop click | Closes the dialog when `dismissible`. |\n| Reduced motion | Enter/exit animations are suppressed under `prefers-reduced-motion` (`motion-reduce:animate-none`) and the dialog unmounts immediately on close. |\n| Sheet mode | Same guarantees: focus moves in, `Tab` is trapped, focus is restored, `Escape`/backdrop honour `dismissible`. |\n| Labelling | When `title` is set, the panel is `aria-labelledby` the title heading. The heading id is generated per instance (`useId`), so several dialogs can be open at once without id collisions. |\n| Stacking | Scroll lock is ref-counted and shared with `Drawer`, `Sheet`, `Sidebar`, `Tour`, etc.: closing a Dialog opened over a Drawer keeps the page locked until the last overlay closes. Only the top-most overlay reacts to `Escape`. |\n\n## Theming\n\nThe panel uses role tokens (`bg-surface`, `text-foreground`, `border-line`, `text-muted`), so it follows dark mode and any `--dt-*` variable overrides. The backdrop is `bg-black/50`.\n\n[← Component overview](README.md)\n",
     "DonutChart": "# DonutChart\n\nThemed donut (or pie) chart for part-to-whole data, with a DOM legend, an optional centre label, an accessible data-table fallback and reduced-motion support. 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 { DonutChart } 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| `index` | `string` | `\"name\"` | Key of the slice name in each row. |\n| `category` | `string` | `\"value\"` | Key of the slice value in each row. |\n| `colors` | `ChartColor[]` | `primary, success, warning, error, info, secondary, gray` | Slice colours by row position (cycled); tokens follow the theme and dark mode. |\n| `variant` | `\"donut\"` or `\"pie\"` | `\"donut\"` | `\"pie\"` fills the centre. |\n| `innerRadius` | `number` or `string` | `\"60%\"` | Inner radius of the ring (px or %). Ignored for `variant=\"pie\"`. |\n| `outerRadius` | `number` or `string` | `\"90%\"` | Outer radius (px or %). |\n| `centerLabel` | `ReactNode` | — | Content drawn in the middle of the donut (e.g. the total). Decorative (`aria-hidden`): repeat the figure in `description`. |\n| `showLegend` | `boolean` | `true` | Legend below the chart (real DOM text). |\n| `valueFormatter` | `(value: number) => string` | `toLocaleString` | Formats values in the tooltip, value axis and hidden data table. |\n| `height` | `number` or `string` | `240` | 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 `\"Donut 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 `data` is empty. |\n| `accessibleTable` | `boolean` | `true` | Repeat the numbers in a visually-hidden `<table>` for screen-reader users. |\n| `animate` | `boolean` | `true` | Animate on mount / data change. Always off when the user prefers reduced motion. |\n| `showTooltip` | `boolean` | `true` | 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### Tasks by status\n\n```jsx\nconst status = [\n  { status: 'Open', tasks: 18 },\n  { status: 'Blocked', tasks: 3 },\n  { status: 'Done', tasks: 42 },\n];\n\n<DonutChart\n  data={status}\n  index=\"status\"\n  category=\"tasks\"\n  colors={['info', 'error', 'success']}\n  centerLabel=\"63 tasks\"\n  title=\"Tasks by status\"\n  description=\"63 tasks: 42 done, 18 open, 3 blocked.\"\n/>\n```\n\n### Pie\n\n```jsx\n<DonutChart data={status} index=\"status\" category=\"tasks\" variant=\"pie\" />\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 \"Donut chart\") |\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",
     "Drawer": "# Drawer\n\nSide panel (sheet) that slides over the page from the right, left, top or bottom. Same open/close contract as `Dialog` (`isOpen` + `onClose`), so a `Dialog size=\"lg\"` stand-in can be swapped for a `Drawer` without touching state code. Use it for record peeks, editors and filter panels. The panel and its header/footer dividers use the semantic `bg-surface` / `border-line` / `text-foreground` tokens, so they follow dark mode.\n\nDrawer is built on the same internal core as [`Sheet`](Sheet.md): it slides in from its edge, slides back out before it unmounts, and can be swiped toward its edge to close. For snap points or a close reason, use `Sheet` directly.\n\n## Import\n\n```jsx\nimport { Drawer } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `isOpen` | `boolean` | — | Controls visibility (required) |\n| `onClose` | `function` | — | Called with no arguments on Escape, backdrop click, the close button or a swipe (required) |\n| `title` | `ReactNode` | — | Heading; also labels the dialog (`aria-labelledby`) |\n| `description` | `ReactNode` | — | Sub-heading; wired to `aria-describedby` |\n| `children` | `ReactNode` | — | Body content (scrolls when it overflows) |\n| `placement` | `string` | `\"right\"` | `right`, `left`, `top`, `bottom` |\n| `size` | `string` | `\"md\"` | `sm`, `md`, `lg`, `xl`, `full` — max width for left/right (`max-w-xs` … `max-w-full`); for top/bottom a max height in dynamic viewport units: `30dvh`, `50dvh`, `75dvh`, `90dvh`, `full` = `100dvh` |\n| `dismissible` | `boolean` | `true` | Allow close via Escape and backdrop click |\n| `showCloseButton` | `boolean` | `true` | Show the X button (44×44px touch target on coarse pointers) |\n| `footer` | `ReactNode` | — | Footer content (e.g. buttons), right-aligned |\n| `initialFocusRef` | `RefObject` | — | Element to focus on open (default: first focusable element) |\n| `handle` | `boolean` | `true` for `placement=\"bottom\"`, else `false` | Draws a decorative, `aria-hidden` grab handle (at the bottom edge for `placement=\"top\"`, else at the top) |\n| `swipeToClose` | `boolean` | `false` | Any placement: dragging the handle or header toward the drawer's own edge (down for bottom, up for top, right for right, left for left) past 80px (or half the panel, if smaller), or a quick flick, calls `onClose`. A shorter drag springs back. Ignored when `dismissible` is `false`. The scrolling body never starts a swipe |\n| `className` | `string` | — | Extra classes for the panel (merged with `cn`) |\n| `...rest` | `HTMLAttributes` | — | Forwarded to the panel (`aria-label`, `data-*`, …); `ref` points at the panel |\n\n## Composition\n\n`Drawer.Header`, `Drawer.Body` and `Drawer.Footer` accept `className` and `...rest`. With `swipeToClose`, `Drawer.Header` is a grab zone like the built-in header (your own pointer handlers still run). When `title`, `description` and `footer` are all omitted, `children` fill the panel directly so these parts lay out without double padding (the close button floats top-right). Give the panel a name with `aria-label` or `aria-labelledby` in that mode.\n\n## Examples\n\n### Basic\n\n```jsx\nconst [open, setOpen] = useState(false);\n\n<Button onClick={() => setOpen(true)}>Edit task</Button>\n<Drawer\n  isOpen={open}\n  onClose={() => setOpen(false)}\n  title=\"Edit task\"\n  description=\"Changes are saved when you press Save.\"\n  footer={\n    <>\n      <Button variant=\"outline\" onClick={() => setOpen(false)}>Cancel</Button>\n      <Button onClick={save}>Save</Button>\n    </>\n  }\n>\n  <Input label=\"Title\" value={title} onChange={(e) => setTitle(e.target.value)} />\n</Drawer>\n```\n\n### Bottom sheet (phone)\n\n`placement=\"bottom\"` renders a phone-style sheet: rounded top corners, a grab handle, and bottom padding for the safe area (`env(safe-area-inset-bottom)`, so add `viewport-fit=cover` to your viewport meta). Add `swipeToClose` to let users drag it down to dismiss. Escape, backdrop click and the focus trap work as usual.\n\n```jsx\n<Drawer isOpen={open} onClose={close} title=\"Collect payment\" placement=\"bottom\" size=\"lg\" swipeToClose>\n  …\n</Drawer>\n```\n\n### Composed (task peek)\n\n```jsx\n<Drawer isOpen={open} onClose={close} size=\"lg\" aria-label=\"Task peek\">\n  <Drawer.Header><h2 className=\"text-lg font-semibold\">{task.title}</h2></Drawer.Header>\n  <Drawer.Body>{task.description}</Drawer.Body>\n  <Drawer.Footer><Button onClick={close}>Done</Button></Drawer.Footer>\n</Drawer>\n```\n\n## Accessibility & keyboard\n\n| Behavior | Detail |\n|----------|--------|\n| Role | Panel is `role=\"dialog\"` + `aria-modal=\"true\"`, rendered in a portal on `document.body` |\n| Focus on open | `initialFocusRef`, else the first focusable element, else the panel |\n| Focus trap | `Tab` / `Shift`+`Tab` cycle inside the panel |\n| Focus restore | On close, focus returns to the element that opened it |\n| `Escape` | Closes when `dismissible`; only the top-most overlay reacts (a Popover inside a Drawer closes first) |\n| Scroll lock | Body scroll is locked while open (reference-counted, safe with stacked overlays) |\n| Close button | 28px on desktop; grows to a 44×44px touch target on coarse pointers (`@media (pointer: coarse)`) |\n| Swipe to close | Pointer drag on the handle/header only, toward the drawer's edge; Escape and the close button remain the keyboard path |\n| Motion | Slides in from its edge and back out (about 200ms, `animate-sheet-in/out` for bottom, a transform transition for the other edges); the backdrop fades in and out. The panel stays mounted (with `data-state=\"exiting\"`, no pointer events) until the exit ends |\n| Reduced motion | Under `prefers-reduced-motion` there is no slide or fade, the swipe snap-back is instant and the drawer unmounts as soon as `isOpen` turns false |\n| Keyboard on phones | A bottom drawer moves up above the on-screen keyboard (`visualViewport`) |\n| Dark mode | Panel, borders and text use `dark:` variants |\n\n[← Component overview](README.md)\n",
@@ -7216,12 +8150,15 @@
     "Loader": "# Loader\n\nLoading indicator in three variants: spinner (default), dots, or bar. Configurable size, speed, colors, and optional label text.\n\n## Import\n\n```jsx\nimport { Loader } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` \\| `number` | `\"md\"` | Size: sm=14px, md=20px, lg=36px, or numeric px. |\n| `speed` | `number` | `0.9` | Animation duration in seconds. Applied through the `--dt-loader-speed` CSS custom property on the wrapper. |\n| `thickness` | `number` | `2.5` | Stroke thickness (spinner). |\n| `color` | `string` | `\"currentColor\"` | Main color (spinner/dots/bar). |\n| `secondaryColor` | `string` | — | Track/background color. When omitted, a dark-safe track is used: 8% black in light mode (as before) and 15% white in dark mode. |\n| `variant` | `\"spinner\"` \\| `\"dots\"` \\| `\"bar\"` | `\"spinner\"` | Visual style. |\n| `className` | `string` | `\"\"` | Wrapper CSS classes. |\n| `inline` | `boolean` | `false` | If true, wrapper is inline-flex. |\n| `ariaLabel` | `string` | `\"Loading\"` | Accessibility label. |\n| `text` | `string` | — | Optional label shown next to loader. |\n| `reverse` | `boolean` | `false` | Reverse spinner rotation direction. |\n| `style` | `object` | — | Inline style for wrapper. |\n\n**Animation:** the keyframes ship in the library's Tailwind build (`animate-loader-spin`, `animate-loader-bounce`, `animate-loader-bar`), so no `<style>` tag is injected per instance. Under `prefers-reduced-motion` the spinner slows to one turn every 3 s (it still shows the app is busy), and the dots and bar stop. The spinner is a CSS rotation of the SVG, not SMIL `<animateTransform>`. The indeterminate bar now travels the full width of its track.\n\n## Examples\n\n```jsx\n<Loader />\n<Loader variant=\"dots\" size=\"sm\" />\n<Loader variant=\"bar\" text=\"Loading...\" />\n<Loader size={32} color=\"#2563eb\" />\n```\n\n[← Component overview](README.md)\n",
     "LoadingState": "# LoadingState\n\nPage-level block: a skeleton shaped like the content that will replace it (table rows, cards, KPI tiles or a key–value panel). One `role=\"status\"` region with screen-reader text; no page-level spinners.\n\n## Import\n\n```jsx\nimport { LoadingState } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `variant` | `table` \\| `cards` \\| `stats` \\| `detail` | `\"table\"` | Shape of the skeleton |\n| `rows` | `number` | 5 (4 for stats, 3 for cards) | How many rows or tiles |\n| `label` | `string` | `\"Loading…\"` | Screen-reader text |\n| `className` | `string` | — | Extra CSS classes |\n\nBones use the `bg-line` role token, and card and row borders use `border-line` / `divide-line`, so the skeleton is dark-safe. Bones pulse (`animate-pulse`) and stop under `prefers-reduced-motion`.\n\n## Example\n\n```jsx\n{isLoading ? <LoadingState variant=\"table\" rows={5} label=\"Loading obligations\" /> : <Table … />}\n```\n\n[← Component overview](README.md)\n",
     "LocationPicker": "# LocationPicker\n\nInput for latitude/longitude. User can type `lat, lng` (e.g. `12.34, 56.78`) or click the icon to use browser geolocation. Value is `{ lat, lng }` or `null`. The input uses the semantic `bg-surface` / `border-line` / `text-foreground` tokens, so it follows dark mode.\n\n## Import\n\n```jsx\nimport { LocationPicker } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `{ lat: number, lng: number }` \\| `null` | `null` | Current coordinates. |\n| `onChange` | `(coords: { lat, lng } \\| null) => void` | — | Called when value changes (typed or from geolocation). |\n| `inputProps` | `object` | `{}` | Props spread to the underlying input (e.g. `placeholder`). A supplied `inputProps.onChange` is forwarded **in addition to** (not instead of) the component's coord-parsing handler — both fire. `inputProps.className` is merged via `cn()`. |\n| `className` | `string` | — | Classes merged (via `cn()`) onto the root wrapper. |\n| `icon` | `ReactNode` | default pin SVG | Icon for \"use my location\" button. |\n| `iconProps` | `object` | `{}` | Props for the icon button (e.g. `className`, `onClick`). |\n| `iconPosition` | `\"left\"` \\| `\"right\"` | `\"right\"` | Position of the icon button. |\n| `placeholder` | `string` | `\"lat, lng\"` | Input placeholder. |\n| `fullWidth` | `boolean` | `false` | Stretch the root and input to the container width (drops the input's 200 px minimum). |\n\n## Behavior\n\n- Display format is `lat.toFixed(6), lng.toFixed(6)`.\n- Typing a valid \"lat, lng\" string calls `onChange` with `{ lat, lng }` (e.g.\n  typing `\"1.5, 2.5\"` calls `onChange({ lat: 1.5, lng: 2.5 })`). A\n  consumer-supplied `inputProps.onChange` still fires alongside it.\n- Clearing the input calls `onChange(null)`.\n- Clicking the icon calls `navigator.geolocation.getCurrentPosition` and passes the result to `onChange`. Requires HTTPS in production.\n- **Loading:** while the request is in flight the button shows a spinner (still\n  under `prefers-reduced-motion`), has `aria-busy=\"true\"`, ignores repeat clicks,\n  and a \"Finding your location…\" `role=\"status\"` line appears under the input.\n- **Errors** are shown in the UI as a `role=\"alert\"` line under the input (the\n  input border turns `error`): permission denied, position unavailable, timeout,\n  or geolocation unsupported — each with its own message. A later success clears\n  it. The error is still logged with `console.error` as before. The status / error\n  line is linked to the input and button with `aria-describedby`.\n- The location button grows to a 44×44 px touch target on coarse pointers, has a\n  `focus-visible` ring and press feedback. The input renders at 16 px on touch\n  screens (no iOS zoom) and has dark-mode styles.\n- Forwards `ref` to the underlying `<input>` and spreads unknown props (`...rest`) onto the root wrapper.\n\n## Example\n\n```jsx\nconst [location, setLocation] = useState(null);\n<LocationPicker\n  value={location}\n  onChange={setLocation}\n  placeholder=\"Enter lat, lng or use location\"\n/>\n```\n\n[← Component overview](README.md)\n",
+    "LogoMarquee": "# LogoMarquee\n\nAn endless horizontal strip of client logos or names. The list is rendered twice for a seamless loop; the second copy is `aria-hidden`, so screen readers read each item once. It pauses on hover, while focus is inside and while off screen. Part of the `/motion` entry point ([overview](Motion.md)).\n\n## Install\n\nNothing extra — the `/motion` entry point has no required peer dependency.\n\n## Import\n\n```jsx\nimport { LogoMarquee } from '@dreamtree-org/twreact-ui/motion';\n```\n\nNever import it from the root `@dreamtree-org/twreact-ui` — the motion components are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `items` | `(string \\| { src, alt, href? } \\| ReactNode)[]` | `[]` | **Required.** Names (strings, rendered as muted text), logos (`{ src, alt, href? }`, rendered as an `<img>`, wrapped in a link when `href` is set) or any node |\n| `speed` | `number` | `40` | Scroll speed in px per second. The loop duration is the measured list width ÷ `speed` |\n| `direction` | `\"left\"` \\| `\"right\"` | `\"left\"` | Direction of the first row |\n| `pauseOnHover` | `boolean` | `true` | Pause while the pointer is over the strip. It always pauses while focus is inside |\n| `fadeEdges` | `boolean` | `true` | Fade the left and right edges with a mask |\n| `rows` | `1` \\| `2` | `1` | One row, or two rows running in opposite directions |\n| `label` | `string` | `\"Clients\"` | Accessible name of the `role=\"region\"` wrapper |\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>` |\n\n## Examples\n\n```jsx\n<LogoMarquee items={['Schoo360', 'TradeOS', 'booknbuy', 'BillPro']} />\n\n<LogoMarquee\n  label=\"Our clients\"\n  rows={2}\n  speed={30}\n  items={[\n    { src: '/logos/acme.svg', alt: 'Acme', href: 'https://acme.example' },\n    { src: '/logos/globex.svg', alt: 'Globex' },\n  ]}\n/>\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Region | A `role=\"region\"` named by `label` |\n| Duplicates | The loop copy is `aria-hidden`; its logos are not links, so each link is one tab stop |\n| List | The visible copy is a `<ul role=\"list\">` |\n| Pausing | Pauses on hover (`pauseOnHover`), whenever focus is inside, and while scrolled off screen |\n| Images | Logo `alt` text is required |\n\n## Reduced motion & server rendering\n\nThe server renders both copies with an estimated loop duration (3 s per item, at least 12 s); the client measures the real width. Under `prefers-reduced-motion: reduce` the strip is a static, centred, wrapped row: the animation stops, the copy is hidden and the edge mask is removed. This is pure CSS (`motion-reduce:`), so it applies before hydration too.\n\n[← Component overview](README.md)\n",
     "MIGRATION-2.0": "# Migrating to 2.0\n\n2.0.0 is the one breaking release planned in the [UI/UX and mobile roadmap](../docs/roadmap/uiux-mobile-2026.md) (epic E6). It removes the APIs that 1.x deprecated and renames the icon props that broke the shared `leftIcon` / `rightIcon` vocabulary. Nothing else changes: there are no new peer dependencies, the Tailwind setup is the same, and no default behaviour was flipped.\n\n## Upgrade in three steps\n\n1. Install the new version:\n\n   ```bash\n   npm install @dreamtree-org/twreact-ui@^2.0.0\n   ```\n\n2. Run the codemod over your source folder. It rewrites JSX on components imported from `@dreamtree-org/twreact-ui` and prints the spots it can't fix by itself:\n\n   ```bash\n   npx jscodeshift -t node_modules/@dreamtree-org/twreact-ui/codemods/v2.cjs src/\n   ```\n\n   The codemod parses `.js`, `.jsx`, `.ts` and `.tsx` files (its default parser is `tsx`). Add `--extensions=js,jsx,ts,tsx` if jscodeshift skips your files, `--dry --print` to preview the result, or `--parser=babel` for Flow code.\n\n3. Fix each line the codemod reports (lines that start with `REP`), then type-check. The TypeScript types drop every removed prop, so `tsc` flags any the codemod couldn't see, such as props passed through a spread.\n\n## What the codemod does\n\n| Change | Automated | Manual |\n|---|---|---|\n| [Input `icon` / `iconPosition`](#input-icon--iconposition--lefticon--righticon) | `icon` becomes `leftIcon`, or `rightIcon` with `iconPosition=\"right\"`; a literal `iconPosition` is removed | A non-literal `iconPosition={pos}` is reported |\n| [`Tabs.Tab` `iconLeft` / `iconRight`](#tabstab-iconleft--iconright) | Renamed to `leftIcon` / `rightIcon` | None |\n| [Input clear](#input-clear-no-longer-fires-onchange) | None | A `clearable` Input with `value` but no `onClear` is reported. Add `onClear` |\n| [ProgressBar HEX colours](#progressbar-hex-colour-props) | `color`, `bgColor` and `valueColor` are removed | Reported. Pick a `variant` if the bar wasn't primary |\n| [Checkbox `borderColor`](#checkbox-bordercolor) | Removed | None |\n| [Rate `activeColor` / `inactiveColor`](#rate-activecolor-and-inactivecolor) | Removed | None |\n| [Checkbox / Switch raw presets](#checkbox-and-switch-raw-colour-presets) | None | `color=\"blue\"`, `\"indigo\"` or `\"purple\"` is reported. Pick a token |\n\nThe codemod only sees literal JSX attributes. It doesn't follow props passed through a spread (`<Input {...props} />`), components re-exported from your own wrapper files, or `React.createElement` calls. The TypeScript types and the [removed props table](#removed-props-at-a-glance) cover those cases.\n\n## Renamed props\n\n### Input `icon` / `iconPosition` → `leftIcon` / `rightIcon`\n\nInput used one `icon` slot plus `iconPosition`. It now uses the same two slots as `Button`, so you can also set both at once.\n\n```jsx\n// 1.x\n<Input icon={<Search />} />\n<Input icon={<Mail />} iconPosition=\"right\" />\n\n// 2.0\n<Input leftIcon={<Search />} />\n<Input rightIcon={<Mail />} />\n<Input leftIcon={<IndianRupee />} rightIcon={<Info />} />  // new: both together\n```\n\nThe behaviour is the same as before. `rightIcon` hides while the password toggle or the clear button shows, and `type=\"search\"` still draws its own search icon on the left.\n\n**Codemod:** automated when `iconPosition` is missing, `\"left\"` or `\"right\"`. If `iconPosition` is an expression, the codemod reports it and you choose the slot yourself:\n\n```jsx\n// 1.x\n<Input icon={icon} iconPosition={end ? \"right\" : \"left\"} />\n// 2.0\n<Input leftIcon={end ? undefined : icon} rightIcon={end ? icon : undefined} />\n```\n\n### `Tabs.Tab` `iconLeft` / `iconRight`\n\n```jsx\n// 1.x\n<Tabs.Tab iconLeft={<Home />}>Home</Tabs.Tab>\n// 2.0\n<Tabs.Tab leftIcon={<Home />}>Home</Tabs.Tab>\n```\n\n**Codemod:** fully automated, including `UI.Tabs.Tab` when you use a namespace import.\n\n## Behaviour change\n\n### Input clear no longer fires `onChange`\n\nIn 1.x the clear button of a controlled `Input` called `onChange({ target: { value: \"\" } })`. That fake event had no `type`, no `currentTarget` and no `preventDefault`, so handlers that read anything beyond `target.value` broke. In 2.0 the clear button only calls `onClear`, and a controlled field clears its own `value` there.\n\n```jsx\n// 1.x: worked because clear sent a synthetic onChange\n<Input clearable value={q} onChange={(e) => setQ(e.target.value)} />\n\n// 2.0\n<Input\n  clearable\n  value={q}\n  onChange={(e) => setQ(e.target.value)}\n  onClear={() => setQ(\"\")}\n/>\n```\n\nUncontrolled fields (`defaultValue`, or no value) still clear themselves, and focus still returns to the input. `Form` text fields keep working: `Form` now passes `onClear` itself and resets the react-hook-form value, then calls the field's own `onClear` if you set one. `SearchField` has its own clear and isn't affected.\n\n**Codemod:** reports every `clearable` Input that has a `value` but no `onClear`. Add the handler yourself, because only you know which state to reset.\n\n## Removed props\n\n### ProgressBar HEX colour props\n\n`color`, `bgColor` and `valueColor` took HEX strings and painted the bar inline, which ignored the brand tokens and dark mode. They are gone. Use the new `variant` prop, a token tone for both the fill and the track.\n\n```jsx\n// 1.x\n<ProgressBar value={80} color=\"#16a34a\" bgColor=\"#dcfce7\" />\n// 2.0\n<ProgressBar value={80} variant=\"success\" />\n```\n\n| `variant` | Fill | Track |\n|---|---|---|\n| `primary` (default) | `bg-primary-600` | `bg-primary-100` / `dark:bg-primary-900/40` |\n| `secondary` | `bg-secondary-600` | `bg-secondary-100` / `dark:bg-secondary-900/40` |\n| `success` | `bg-success-600` | `bg-success-100` / `dark:bg-success-900/40` |\n| `warning` | `bg-warning-600` | `bg-warning-100` / `dark:bg-warning-900/40` |\n| `destructive` | `bg-error-600` | `bg-error-100` / `dark:bg-error-900/40` |\n\nThe value text inside the fill is always `text-white`. For a colour that isn't one of these tones, set it on the brand (`tokens/brands/<name>.json`) rather than on one bar.\n\n**Codemod:** removes the three props and reports each ProgressBar it changed, so you can add a `variant`.\n\n### Checkbox `borderColor`\n\nThe box border is always the `border-gray-300` / `dark:border-gray-600` token.\n\n```jsx\n// 1.x\n<Checkbox label=\"Accept\" borderColor=\"#9ca3af\" />\n// 2.0\n<Checkbox label=\"Accept\" />\n```\n\n**Codemod:** removes the prop.\n\n### Rate `activeColor` and `inactiveColor`\n\nStars always use `text-warning-400` (active) and `text-gray-200` (inactive), so a brand file recolours them.\n\n```jsx\n// 1.x\n<Rate value={4} activeColor=\"#ef4444\" inactiveColor=\"#fee2e2\" />\n// 2.0\n<Rate value={4} />\n```\n\n**Codemod:** removes both props.\n\n### Checkbox and Switch raw colour presets\n\nThe `blue`, `indigo` and `purple` presets used the raw Tailwind palette (`bg-blue-600`, …) instead of tokens. They are removed. The token presets remain: `primary`, `secondary`, `success`, `error` and `warning`, plus the aliases `green` (success) and `danger` / `red` (error).\n\n```jsx\n// 1.x\n<Checkbox color=\"indigo\" label=\"Remember me\" />\n<Switch color=\"blue\" />\n// 2.0\n<Checkbox color=\"primary\" label=\"Remember me\" />\n<Switch color=\"primary\" />\n```\n\n**Heads-up:** `color` still accepts any CSS colour string as an inline override, and `blue`, `indigo` and `purple` are CSS colour names. So the old values don't throw an error: they now paint the CSS colour inline (pure `#0000ff` and so on) with no dark-mode tone. Replace them.\n\n**Codemod:** reports every literal `color=\"blue\" | \"indigo\" | \"purple\"` on Checkbox and Switch. It doesn't pick a token for you, because the right tone depends on your brand.\n\n### Internal: `computePosition`\n\nThe internal `computePosition` helper in `src/utils/position.js` was never exported from the package. It was unused after every overlay moved to `useFloatingPosition` (floating-ui). It is deleted. Consumers are only affected if they deep-imported library source files, which isn't supported.\n\n## Removed props at a glance\n\n| Component | 1.x prop | 2.0 |\n|---|---|---|\n| `Input` | `icon` | `leftIcon` / `rightIcon` |\n| `Input` | `iconPosition` | Choose `leftIcon` or `rightIcon` |\n| `Input` | clear → synthetic `onChange` | `onClear` (controlled: clear `value` yourself) |\n| `Tabs.Tab` | `iconLeft` / `iconRight` | `leftIcon` / `rightIcon` |\n| `ProgressBar` | `color`, `bgColor`, `valueColor` (HEX) | `variant` |\n| `Checkbox` | `borderColor` | Removed (token border) |\n| `Checkbox` | `color=\"blue\" \\| \"indigo\" \\| \"purple\"` | A token preset |\n| `Switch` | `color=\"blue\" \\| \"indigo\" \\| \"purple\"` | A token preset |\n| `Rate` | `activeColor`, `inactiveColor` | Removed (token colours) |\n\nA removed prop that is still passed falls through `...rest` to the DOM element, where React logs an \"unknown prop\" warning in development. Treat those warnings as a list of the props left to clean up.\n\n## What did not change\n\n- **No default flips.** No 1.x ticket or changelog entry promised a 2.0 default change, so every default stays as it was. Examples are `presentation=\"auto\"`, `Sidebar swipeable`, `Slider showBubble` and the opt-in `haptics`.\n- **Sizes** already used the shared `xs | sm | md | lg | xl` scale. No size was renamed.\n- **Exports:** no component, hook or util was added, renamed or removed.\n\n[← Component overview](README.md)\n",
     "MobileNativeFeel": "# Mobile native feel and PWA guide\n\nHow to make an app built with `@dreamtree-org/twreact-ui` feel like a native app on phones and when installed as a PWA. The components already handle safe areas, the dynamic viewport, sheets, touch targets and reduced motion. Your app still has to add the page-level parts: the viewport meta, `theme-color`, the web manifest and a few layout rules. This guide covers both, then ends with a checklist for testing on real devices.\n\n## 1. Viewport meta\n\nPut this in your HTML `<head>` (in Next.js, export a `viewport` object from the root layout with the same values):\n\n```html\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1, viewport-fit=cover\">\n```\n\n- `viewport-fit=cover` lets the page draw under the notch and the home indicator, and makes `env(safe-area-inset-*)` return real values. Without it, `pt-safe`, `pb-safe` and the padding inside `AppShell`, `FootNav`, `Sheet` and `BottomActionBar` all resolve to `0`.\n- Don't add `maximum-scale=1` or `user-scalable=no` to stop iOS zooming into focused inputs. That blocks pinch-zoom, which people with low vision need. The library's stylesheet prevents the focus zoom another way (see [Global mobile baseline](#9-global-mobile-baseline)).\n\n## 2. Theme colour per theme\n\n`theme-color` tints the browser toolbar on Android Chrome and the status bar in an installed PWA. Give each colour scheme its own meta tag:\n\n```html\n<meta name=\"theme-color\" content=\"#ffffff\" media=\"(prefers-color-scheme: light)\">\n<meta name=\"theme-color\" content=\"#111827\" media=\"(prefers-color-scheme: dark)\">\n```\n\n`#ffffff` / `#111827` are the default `surface` token (light / dark), which is the colour of the `AppShell` top bar (`bg-surface`). If your brand file changes `surface`, or your top bar uses a different colour, use that colour here.\n\n### Keep it in sync with `ThemeProvider`\n\n`ThemeProvider` stores an explicit `'light'` or `'dark'` choice and writes `data-theme`, the `.dark` class and `color-scheme` on `<html>`. It does not follow the OS setting. So a user can pick dark mode on a phone set to light, and the media-query tags above would then show the wrong toolbar colour. Rewrite the tags whenever the theme changes. Read the colour from the `--dt-surface` token variable (stored as space-separated RGB channels), so the tag also follows a brand file:\n\n```jsx\nimport { useEffect } from 'react';\nimport { ThemeProvider, useTheme } from '@dreamtree-org/twreact-ui';\n\nfunction ThemeColorSync() {\n  const { theme } = useTheme();\n  useEffect(() => {\n    const rgb = getComputedStyle(document.documentElement).getPropertyValue('--dt-surface').trim();\n    if (!rgb) return;\n    document\n      .querySelectorAll('meta[name=\"theme-color\"]')\n      .forEach((meta) => meta.setAttribute('content', `rgb(${rgb})`));\n  }, [theme]);\n  return null;\n}\n\nexport function Root({ children }) {\n  return (\n    <ThemeProvider defaultTheme=\"light\">\n      <ThemeColorSync />\n      {children}\n    </ThemeProvider>\n  );\n}\n```\n\n`useTheme()` throws outside a `ThemeProvider`, so render `ThemeColorSync` inside it. Keep the static tags in the HTML anyway: they give the right colour before JavaScript runs.\n\n## 3. Web manifest\n\nA manifest makes the app installable (\"Add to Home Screen\" / \"Install app\") and opens it without browser UI:\n\n```json\n{\n  \"name\": \"PracticePro\",\n  \"short_name\": \"PracticePro\",\n  \"start_url\": \"/\",\n  \"scope\": \"/\",\n  \"display\": \"standalone\",\n  \"background_color\": \"#f8fafc\",\n  \"theme_color\": \"#ffffff\",\n  \"icons\": [\n    { \"src\": \"/icons/icon-192.png\", \"sizes\": \"192x192\", \"type\": \"image/png\" },\n    { \"src\": \"/icons/icon-512.png\", \"sizes\": \"512x512\", \"type\": \"image/png\" },\n    { \"src\": \"/icons/icon-maskable-512.png\", \"sizes\": \"512x512\", \"type\": \"image/png\", \"purpose\": \"maskable\" }\n  ]\n}\n```\n\n```html\n<link rel=\"manifest\" href=\"/manifest.webmanifest\">\n<link rel=\"apple-touch-icon\" href=\"/icons/apple-touch-icon.png\">\n```\n\n- `display: \"standalone\"` removes the address bar and browser toolbars.\n- `background_color` is the splash screen colour; `#f8fafc` is the default `background` token (the page background), so the splash matches the first frame.\n- The manifest's `theme_color` has no light/dark variants. The `<meta name=\"theme-color\">` tags win once the page loads.\n- iOS uses `apple-touch-icon` for the home-screen icon. To draw the page under the iOS status bar in standalone mode, add `<meta name=\"apple-mobile-web-app-status-bar-style\" content=\"black-translucent\">`. Your top bar then needs `pt-safe`, which `AppShell` already has.\n- Offline support (a service worker) is up to you; the library ships none.\n\n## 4. Styling for standalone mode\n\nInstalled apps have no browser back button or address bar. Use `@media (display-mode: standalone)` for anything that should change:\n\n```css\n/* Show an in-app back button only when there is no browser UI. */\n.app-back-button { display: none; }\n\n@media (display-mode: standalone) {\n  .app-back-button { display: inline-flex; }\n  /* Native apps don't let you select UI chrome by accident. */\n  .app-chrome { user-select: none; -webkit-user-select: none; }\n}\n```\n\nIn Tailwind 3.4 you can write it inline as an arbitrary variant: `hidden [@media(display-mode:standalone)]:inline-flex`. The library has no `standalone:` variant of its own; add one to your config if you use it a lot. In JavaScript, check `window.matchMedia('(display-mode: standalone)').matches` (and `navigator.standalone` on older iOS).\n\n## 5. Use `dvh`, not `100vh`\n\nOn phones, `100vh` is the height with the browser toolbars hidden, so a `h-screen` layout is taller than the visible area and its bottom (often the main action) ends up under the toolbar. Use the dynamic viewport units, which Tailwind 3.4 ships:\n\n| Instead of | Use |\n|------------|-----|\n| `h-screen`, `height: 100vh` | `h-dvh` (`height: 100dvh`) |\n| `min-h-screen` | `min-h-dvh` |\n| `max-h-[80vh]` | `max-h-[80dvh]` |\n\nThe library already uses them: `AppShell` fills `min-h-dvh` (its sidebar is `h-dvh`), side `Sheet`s are `h-dvh`, and `Dialog`, `Drawer`, `Tour` and the toast stack cap their height in `dvh`. If you only need a fixed full-height page and the content must never resize while the toolbar moves, `h-svh` (the smallest viewport) is the steadier choice.\n\n## 6. The app shell recipe: `AppShell` + `FootNav` + `Sheet`\n\n[`AppShell`](AppShell.md) gives you a sidebar on desktop, a top bar with a navigation drawer below `lg`, and a phone tab bar via `bottomNav`. Pass a [`FootNav`](FootNav.md) there: it renders below `md` only, and `AppShell` adds the `FootNav.Spacer` after `<main>` for you. Open quick tasks in a bottom [`Sheet`](Sheet.md) from a FAB item:\n\n```jsx\nimport { useState } from 'react';\nimport { Link } from 'react-router-dom';\nimport { AppShell, FootNav, Sheet, Button, Input } from '@dreamtree-org/twreact-ui';\nimport { Home, CheckSquare, Plus, Inbox } from 'lucide-react';\n\nexport function Layout({ path, children }) {\n  const [adding, setAdding] = useState(false);\n\n  return (\n    <AppShell\n      brand={<span className=\"text-lg font-bold\">PracticePro</span>}\n      nav={[\n        { id: 'home', label: 'Home', href: '/', active: path === '/' },\n        { id: 'tasks', label: 'Tasks', href: '/tasks', active: path === '/tasks' },\n        { id: 'inbox', label: 'Inbox', href: '/inbox', active: path === '/inbox' },\n      ]}\n      linkAs={Link}\n      pageTitle=\"Tasks\"\n      data-sheet-background\n      bottomNav={\n        <FootNav\n          linkAs={Link}\n          hideOnScroll\n          items={[\n            { id: 'home', label: 'Home', icon: <Home />, to: '/', active: path === '/' },\n            { id: 'tasks', label: 'Tasks', icon: <CheckSquare />, to: '/tasks', active: path === '/tasks', badge: 3 },\n            {\n              id: 'add',\n              label: 'Add',\n              icon: <Plus />,\n              variant: 'action',\n              'aria-haspopup': 'dialog',\n              'aria-expanded': adding,\n              onClick: () => setAdding(true),\n            },\n            { id: 'inbox', label: 'Inbox', icon: <Inbox />, to: '/inbox', active: path === '/inbox' },\n          ]}\n        />\n      }\n    >\n      {children}\n\n      <Sheet open={adding} onClose={() => setAdding(false)} title=\"New task\" snapPoints={[0.5, 1]} scaleBackground>\n        <Sheet.Body>\n          <Input label=\"Title\" />\n        </Sheet.Body>\n        <Sheet.Footer>\n          <Button onClick={() => setAdding(false)}>Save</Button>\n        </Sheet.Footer>\n      </Sheet>\n    </AppShell>\n  );\n}\n```\n\n- Keep `bottomNav` to the 3–5 most used destinations; the full `nav` stays in the drawer and the sidebar.\n- `data-sheet-background` goes to the `AppShell` root (it forwards `...rest`), so `scaleBackground` can scale the page behind the sheet, as iOS does. It does nothing under reduced motion.\n- Only render a `FootNav.Spacer` yourself when you use `FootNav` without `AppShell`.\n- For a form's primary action, use [`BottomActionBar`](BottomActionBar.md) (with `<BottomActionBar.Spacer />`) rather than a hand-built `fixed bottom-0` bar: it pads the safe area and rides above the on-screen keyboard.\n- Other native patterns ship as components: [`PullToRefresh`](PullToRefresh.md), [`SwipeableListItem`](SwipeableListItem.md), [`SearchField`](SearchField.md), [`SegmentedControl`](SegmentedControl.md) and [`ActionSheet`](ActionSheet.md).\n\n## 7. Overlays: `presentation` overrides\n\nOn small touch screens (`(pointer: coarse) and (max-width: 639px)`), these components switch to a phone presentation by default (`presentation=\"auto\"`):\n\n| Component | Phone presentation |\n|-----------|--------------------|\n| [`Select`](Select.md), [`DatePicker`](DatePicker.md), [`DateRangePicker`](DateRangePicker.md), [`Popover`](Popover.md), [`SearchField`](SearchField.md) results | Bottom `Sheet` |\n| [`Dialog`](Dialog.md), [`ConfirmDialog`](ConfirmDialog.md) | Bottom `Sheet` instead of the centred modal |\n| [`ThreeDotPopover`](ThreeDotPopover.md), the [`Table`](Table.md) row menu | Action sheet |\n| [`Tour`](Tour.md) | Step card docked at the bottom |\n\nEverywhere else, and on the server and while hydrating, they render the desktop popover or modal. Each takes `presentation=\"auto\" | \"popover\" | \"sheet\"`. Override it only for a reason:\n\n- **Force `popover`** when the content needs the context around it: a small `Popover` next to the control it adjusts, a sort menu that should not cover the list, a `Tour` step that must point at its target, or a `Dialog` that a tablet-sized coarse-pointer screen should keep centred.\n- **Force `sheet`** when the content is long or full of touch controls on every screen size: a filter panel, a long `Select` list, a multi-field quick form.\n- Leave `auto` alone otherwise. The breakpoint matches the one the rest of the library uses, so all overlays switch together.\n\n`Tooltip` has no sheet presentation (it opens on long-press on touch screens); use `Popover` for interactive content.\n\n## 8. Safe areas\n\nWith `viewport-fit=cover` set, the stylesheet's utilities pad for the notch, rounded corners and home indicator:\n\n| Class | Pads |\n|-------|------|\n| `pt-safe`, `pb-safe`, `pl-safe`, `pr-safe` | One edge (`env(safe-area-inset-*)`) |\n| `px-safe` | Left and right |\n| `py-safe` | Top and bottom |\n| `inset-safe` | Sets `top` / `right` / `bottom` / `left` to the insets (for positioned elements) |\n\nAlready padded, so don't add them again: the `AppShell` top bar (`pt-safe px-safe`), sidebar (`pt-safe pb-safe pl-safe`) and content column (`px-safe`); `FootNav` (`pb-safe`); `BottomActionBar` (`pb-safe px-safe`); `Sheet` (bottom: `pb-safe px-safe`, top: `pt-safe px-safe`, sides: `py-safe` plus the outer edge).\n\nAdd them yourself to any edge bar you build: a custom sticky header gets `pt-safe`, a full-bleed bottom element `pb-safe`, and in landscape any full-width row `px-safe`.\n\n## 9. Global mobile baseline\n\nImporting the library's CSS gives every page this baseline (from `src/styles/index.css`):\n\n- **No tap highlight.** `-webkit-tap-highlight-color: transparent` on `:root`; components show their own pressed and `focus-visible` states instead. `text-size-adjust: 100%` stops iOS from enlarging text in landscape.\n- **No zoom on input focus.** On coarse pointers, text `input`s, `select`s and `textarea`s are at least 16px (`font-size: max(16px, 1em) !important`, so it beats `text-sm`). iOS Safari zooms into fields with smaller text. Checkboxes, radios, ranges, colour and file inputs are not affected. Add `dt-keep-font-size` to a field to opt it out.\n- **No rubber-band overscroll.** `body` has `overscroll-behavior-y: none`, so the page doesn't bounce or chain scroll, and the browser's own pull-to-refresh doesn't fight [`PullToRefresh`](PullToRefresh.md). To get the browser's pull-to-refresh back, add `dt-overscroll-auto` to `<html>` or `<body>`.\n- **`color-scheme`** follows the theme (`light` by default, `dark` under `.dark` / `[data-theme=\"dark\"]`), so native scrollbars and form controls match.\n- **Reduced motion.** Under `prefers-reduced-motion: reduce`, animations and transitions are cut to near zero, and components such as `Sheet`, `FootNav` and `Dialog` skip their slides.\n- Touch targets in the components grow to 44px on coarse pointers.\n\n## 10. Haptics are opt-in\n\nNothing vibrates unless you ask. [`useHaptics`](useHaptics.md) wraps `navigator.vibrate` with named patterns (`selection`, `success`, `warning`, `error`), and `Switch`, `Checkbox`, `ConfirmDialog` and `Sheet` take a `haptics` prop that defaults to `false`:\n\n```jsx\n{/* Each alongside its usual props (open, onClose, onConfirm, …) */}\n<Switch haptics rightLabel=\"Notifications\" />\n<ConfirmDialog haptics destructive />\n<Sheet haptics snapPoints={[0.5, 1]} />\n```\n\n- iOS Safari has no vibration API, so haptics never fire on iPhones. Treat them as a bonus on Android, never as the only feedback.\n- Calls are no-ops on the server, while hydrating, under reduced motion and before the user's first interaction.\n- To let users turn haptics off, pass your setting as `useHaptics({ enabled })` or as the components' `haptics` prop.\n\n## 11. Real-device testing checklist\n\nEmulators and desktop responsive mode miss most of these. Test on at least one iPhone (iOS Safari) and one Android phone (Chrome), in the browser and installed to the home screen.\n\n**Safe area**\n- [ ] On a notched iPhone, nothing sits under the notch or the Dynamic Island in portrait, and nothing hides under the rounded corners in landscape.\n- [ ] The `FootNav` labels and `BottomActionBar` buttons sit above the home indicator.\n- [ ] A bottom `Sheet`'s last row isn't covered by the home indicator.\n\n**No zoom on input focus**\n- [ ] Tapping an `Input`, `Select`, `Textarea` or `SearchField` does not zoom the page on iOS Safari.\n- [ ] Pinch-zoom still works (the viewport meta doesn't block it).\n- [ ] With the keyboard open, the `BottomActionBar` and a bottom `Sheet` stay above it.\n\n**Sheet swipe**\n- [ ] Dragging a bottom `Sheet` (handle, header or body scrolled to the top) follows the finger and dismisses past the threshold; a short drag snaps back.\n- [ ] With `snapPoints`, the sheet settles on each snap point.\n- [ ] Scrolling inside `Sheet.Body` scrolls the content, not the page behind it.\n- [ ] The left navigation drawer of `AppShell` closes when dragged left.\n\n**No horizontal scroll at 375px**\n- [ ] At 375px wide (iPhone SE / mini), no page scrolls sideways. Wide tables, long words and fixed-width elements are the usual cause.\n- [ ] Five `FootNav` tabs fit, and long labels truncate.\n\n**Standalone mode**\n- [ ] The app installs from Android Chrome (\"Install app\") and iOS Safari (Share → Add to Home Screen) with the right icon and name.\n- [ ] It opens without browser UI, and the status bar / toolbar colour matches the theme in light and dark (including after switching with `ThemeProvider`).\n- [ ] The splash screen colour matches the first frame.\n- [ ] Every screen has a way back without a browser back button, and links within `scope` stay in the app.\n\n**General**\n- [ ] Pressing a button gives visual feedback with no grey tap flash.\n- [ ] Overlays open as sheets on the phone and as popovers / modals on a desktop browser.\n- [ ] With Reduce Motion on (iOS Settings → Accessibility → Motion; Android Remove animations), sheets and the tab bar appear without sliding.\n\n[← Component overview](README.md)\n",
-    "Navbar": "# Navbar\n\nTop navigation bar with logo, nav items (links or buttons), optional search, notifications dropdown, and login/logout. Uses an **emitter** for notification actions (view, markAsRead, markAsUnread, clearAll, delete). Responsive: left icon and hamburger on mobile; desktop nav and search. You can replace the right area with a custom component via `rightMenuContent`. The bar, search box and dropdown panels use the semantic `bg-surface` / `border-line` / `text-foreground` tokens, so they follow dark mode.\n\n## Import\n\n```jsx\nimport { Navbar } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `emitter` | `object` | **required** | Event emitter for notifications (e.g. `notification:view`, `notification:markAsRead`, etc.). |\n| `logo` | `ReactNode` | — | Logo (e.g. image or link). Truncates on narrow screens. |\n| `center` | `ReactNode` | — | Centre slot (e.g. a search field or primary action) between the logo and the right-hand icons. Rendered in a `min-w-0 flex-1` column so it shrinks first on narrow screens; give its content a fluid width such as `w-full max-w-md`. |\n| `items` | `Array` | `[]` | Nav items: `{ id, label, href?, active?, onClick?(item) }`. If `href` is set, renders `<a>`; else `<button>` with `onClick`. |\n| `user` | `object` | — | `{ name, email, avatar?, menuItems? }`. If set, shows the user menu and a logout button; if omitted, a login button. Without `avatar`, the menu trigger shows `name` initials (via `Avatar`). |\n| `notifications` | `Array` | `[]` | List of notifications for the dropdown. Each: `{ id, title, message?, read? }`. |\n| `searchable` | `boolean` | `false` | Show the search input from `sm` up. Below `sm` a **Search** icon button opens a top `Sheet` holding a [`SearchField`](SearchField.md) instead (same term, same `onSearch`). |\n| `onSearch` | `(term: string) => void` | — | Called with the current term on search form submit (desktop) or Enter in the phone search sheet (the sheet then closes). |\n| `sticky` | `boolean` | `false` | Sticks the bar to the top (`sticky top-0 z-sticky`), pads it with the top safe area (`pt-safe`) and makes it translucent (`bg-surface/80 backdrop-blur` where `backdrop-filter` is supported; opaque `bg-surface` otherwise). |\n| `largeTitle` | `ReactNode` | — | iOS large title: an `<h1>` under the bar that collapses into a compact centred title in the bar once the window scrolls past 44px (and expands again under 8px). Passive scroll listener, SSR-safe (expanded on the server), instant under `prefers-reduced-motion`. |\n| `leftIcon` | `ReactNode` \\| `false` | `<ChevronLeft />` | Icon shown on mobile (e.g. back). Set `false` to hide. |\n| `onLeftIconClick` | `(event) => void` | — | Called when left icon (mobile) is clicked. |\n| `leftIconLabel` | `string` | `\"Go back\"` | Accessible name of the left button. Set it when the button is not \"back\", e.g. `\"Open navigation\"` when it opens a `Sidebar` drawer. |\n| `leftIconProps` | `ButtonHTMLAttributes` | — | Extra props spread onto the left `<button>` — e.g. `{ \"aria-expanded\": open, \"aria-controls\": \"app-sidebar\" }` when it toggles a drawer. `className` merges last; `onClick` runs after `onLeftIconClick`. |\n| `rightMenuContent` | `(props) => ReactNode` | — | Custom right menu. Receives `{ notifications }` and any Navbar `...props` (e.g. `emitter`, `onFetch`). If not provided, default renders notifications dropdown. |\n| `onLoginClick` | `() => void` | — | Called when the login icon button (accessible name \"Sign in\") is clicked. |\n| `onLogoutClick` | `() => void` | — | Called when the logout icon button (accessible name \"Sign out\") or the user-menu **Sign out** item is clicked. |\n| `onFetch` | `({ setNotifications }) => void` | — | Refresh handler for the default notifications dropdown. Called on mount and when `notifications` changes. Consumed by the right menu — it is **not** forwarded onto `<nav>`. |\n| `className` | `string` | — | Wrapper CSS classes. |\n| ...rest | — | — | Only DOM-valid attributes (e.g. `id`, `aria-*`, `data-*`, event handlers) are forwarded to the root `<nav>`. The component's own control props (`isMobileOpen`, `setIsMobileOpen`, `onFetch`, …) are consumed and never leak to the DOM. |\n\n`Navbar` forwards `ref` to its root `<nav>` element.\n\n## Touch targets and labels\n\nIcon buttons (back, search, notifications, sign in/out, menu, user menu) are 36px on desktop and grow to the 44×44px touch target on coarse pointers, with a `focus-visible` ring. Accessible names: **Go back** (the left button; rename it with `leftIconLabel`), **Search**, **Notifications** (or **Notifications, 3 unread**), **Sign in**, **Sign out**, **Open menu** / **Close menu** (with `aria-expanded`) and **User menu**.\n\nThe unread badge grows with its count (`min-w-4` + padding) and caps at **99+**. It is `aria-hidden`; the count is in the bell's name.\n\n## Sticky bar and large title\n\n```jsx\n<Navbar emitter={emitter} logo={<Logo />} sticky largeTitle=\"Invoices\" searchable onSearch={search} />\n```\n\nThe large title collapses with the window scroll, so use it on pages that scroll the document (not an inner scroll container). Add `viewport-fit=cover` to your viewport meta for the safe-area inset.\n\n## Small screens (≤ 390px)\n\nThe header fits a 390px phone: columns use `gap` + `min-w-0` so the logo\ntruncates and the `center` slot shrinks instead of overflowing. Below the `sm`\nbreakpoint the standalone logout icon is hidden and a **Sign out** item appears\nat the bottom of the user menu instead (it calls `onLogoutClick`). With\n`searchable`, the inline search box is replaced by a **Search** button that\nopens the search sheet. From `sm` up the layout is unchanged.\n\n## Centre slot and initials avatar\n\n```jsx\n<Navbar\n  emitter={emitter}\n  logo={<Logo />}\n  center={<Input type=\"search\" placeholder=\"Search tasks...\" className=\"w-full max-w-md\" />}\n  user={{ name: 'Ada Lovelace', email: 'ada@example.com' }} // no avatar → \"AL\"\n/>\n```\n\n## Item shape (items)\n\n- `id`: string or number (key).\n- `label`: string.\n- `href`: optional; if set, item is an `<a href={href}>`.\n- `active`: optional boolean; applies primary styling.\n- `onClick(item)`: optional; used when no `href` (button click).\n\n## Notification shape (notifications)\n\n- `id`: string or number.\n- `title`: string.\n- `message`: optional string.\n- `read`: optional boolean; unread count uses `!n.read`.\n\n## Default notifications dropdown\n\nIf `rightMenuContent` is not provided, the right menu shows a bell icon and dropdown with:\n\n- Unread count badge.\n- \"Clear all\" that clears the list and calls emitter `notification:clearAll`.\n- Per notification: title, message, \"Mark as Read\" / \"Mark as Unread\", \"Delete\" (emitter events).\n- Clicking a notification calls `emitter.emit('notification:view', [n])`.\n\nTo refresh the list from the server, pass `onFetch({ setNotifications })`; the default dropdown uses it on mount and when `notifications` prop changes.\n\n## Example\n\n```jsx\nimport { Navbar } from '@dreamtree-org/twreact-ui';\nimport MyEmitter from './emitter';\n\n<Navbar\n  emitter={MyEmitter}\n  logo={<a href=\"/\"><img src=\"/logo.svg\" alt=\"Home\" /></a>}\n  items={[\n    { id: '1', label: 'Home', href: '/', active: pathname === '/' },\n    { id: '2', label: 'About', href: '/about' },\n    { id: '3', label: 'Settings', onClick: () => openSettings() },\n  ]}\n  user={user}\n  notifications={notifications}\n  searchable\n  onSearch={(term) => doSearch(term)}\n  onLoginClick={() => navigate('/login')}\n  onLogoutClick={logout}\n  onFetch={async ({ setNotifications }) => {\n    const res = await fetch('/api/notifications');\n    const data = await res.json();\n    setNotifications(data.items);\n  }}\n/>\n```\n\n### Left button as the Sidebar menu button\n\n```jsx\nimport { Menu } from 'lucide-react';\n\n<Navbar\n  emitter={MyEmitter}\n  leftIcon={<Menu />}\n  leftIconLabel=\"Open navigation\"\n  leftIconProps={{ 'aria-expanded': drawerOpen, 'aria-controls': 'app-sidebar' }}\n  onLeftIconClick={() => setDrawerOpen(true)}\n/>\n<Sidebar id=\"app-sidebar\" items={items} isMobileOpen={drawerOpen} setIsMobileOpen={setDrawerOpen} />\n```\n\n[← Component overview](README.md)\n",
+    "Motion": "# Motion (`/motion` entry point)\n\nScroll-storytelling components for landing pages: pinned scenes, reveals, a logo marquee, count-up numbers, stacked sticky cards, a device mock-up hero, an expanding photo grid, a testimonial spotlight, a photo collage and a rotating badge. They live on their own entry point, so apps that never import them pay nothing.\n\n## Install\n\nNothing extra. The only optional peer is `lenis`, and only `SmoothScrollProvider` uses it:\n\n```bash\nnpm install lenis   # optional, for SmoothScrollProvider only\n```\n\n## Import\n\n```jsx\nimport { ScrollStage, Reveal, StackedCards, DeviceMorphHero } from '@dreamtree-org/twreact-ui/motion';\n```\n\nNever import them from the root `@dreamtree-org/twreact-ui` — they are not exported there.\n\n| Export | Kind | Doc |\n|--------|------|-----|\n| `useScrollProgress` | Hook: 0–1 scroll progress of an element | [useScrollProgress.md](useScrollProgress.md) |\n| `ScrollStage` | Primitive: pinned scroll scene | [ScrollStage.md](ScrollStage.md) |\n| `Reveal` / `RevealGroup` | Primitive: entrance on scroll-in | [Reveal.md](Reveal.md), [RevealGroup.md](RevealGroup.md) |\n| `DeviceFrame` | Primitive: CSS phone / tablet / laptop / browser mock-up | [DeviceFrame.md](DeviceFrame.md) |\n| `SmoothScrollProvider` / `useSmoothScroll` | Opt-in Lenis smooth scroll | [SmoothScrollProvider.md](SmoothScrollProvider.md), [useSmoothScroll.md](useSmoothScroll.md) |\n| `LogoMarquee` | Section: endless logo strip | [LogoMarquee.md](LogoMarquee.md) |\n| `CountUp` / `StatStrip` | Section: numbers that count up | [CountUp.md](CountUp.md), [StatStrip.md](StatStrip.md) |\n| `StackedCards` | Section: sticky stacking cards | [StackedCards.md](StackedCards.md) |\n| `DeviceMorphHero` | Section: media morphs into a device | [DeviceMorphHero.md](DeviceMorphHero.md) |\n| `BentoExpandGrid` | Section: photo grid whose active tile grows | [BentoExpandGrid.md](BentoExpandGrid.md) |\n| `TestimonialSpotlight` | Section: quotes with a logo tile grid | [TestimonialSpotlight.md](TestimonialSpotlight.md) |\n| `PhotoCollage` / `RotatingBadge` | Section: overlapping photos, circular text badge | [PhotoCollage.md](PhotoCollage.md), [RotatingBadge.md](RotatingBadge.md) |\n\n## How it works\n\n- **One engine.** A single shared `requestAnimationFrame` loop plus a shared `IntersectionObserver` drive every component. Each frame runs all DOM reads first, then all writes. A scene only does work while it is near the viewport, and the loop sleeps when nothing is scrolling.\n- **CSS variables, not re-renders.** Scroll progress is written to the element as `--dt-p` (0–1). CSS maps it to `transform`, `opacity` or `clip-path`, so React does not re-render on every frame. Write CSS with a final-state fallback: `opacity: var(--dt-p, 1)`.\n- **No animation library.** There is no GSAP dependency. Lenis is optional, and you pass its class in (`<SmoothScrollProvider lenis={Lenis}>`), so the package never imports it.\n- **Server rendering.** The server renders every component in its final state: `CountUp` shows the real number, `Reveal` content is visible, and `DeviceMorphHero` shows the device beside the copy. Motion starts after hydration.\n- **Reduced motion.** With `prefers-reduced-motion: reduce`, pinned scenes render in normal flow, counters show the final number, the marquee becomes a static wrapped row, tilt and parallax are off, autoplay stops and Lenis is not started. Each component's doc lists its fallback.\n- **Mobile.** Pinned scenes default to 300 vh on desktop and 150 vh below `md`. The values come from the `scroll` token group in `tokens/tokens.json` (`scroll.sceneLength`, `scroll.sceneLengthMobile`, `scroll.stickyTop` = 80 px).\n- **Styles.** The Tailwind classes these components use are compiled into `dist/index.css` like every other component, including the `animate-dt-marquee` keyframes.\n- **Size budget.** The motion code is held to 12 KB gzipped (minified, with dependencies and modules shared with the root entry left out). `npm run build` checks it, or run `npm run motion:size`.\n\n## Examples\n\n```jsx\nimport Lenis from 'lenis';\nimport {\n  SmoothScrollProvider, DeviceMorphHero, LogoMarquee, StatStrip, StackedCards, Reveal,\n} from '@dreamtree-org/twreact-ui/motion';\n\n<SmoothScrollProvider lenis={Lenis}>\n  <DeviceMorphHero media={{ video: '/intro.mp4', poster: '/intro.jpg', alt: 'Product tour' }} content={<HeroCopy />} />\n  <LogoMarquee items={clients} />\n  <StatStrip items={[{ value: 120, suffix: '+', label: 'Projects' }]} />\n  <Reveal as=\"h2\" effect=\"split-words\">What we do</Reveal>\n  <StackedCards items={pillars} />\n</SmoothScrollProvider>\n```\n\n[← Component overview](README.md)\n",
+    "Navbar": "# Navbar\n\nTop navigation bar with logo, nav items (links or buttons), optional search, notifications dropdown, and login/logout. Uses an **emitter** for notification actions (view, markAsRead, markAsUnread, clearAll, delete). Responsive: left icon and hamburger on mobile; desktop nav and search. You can replace the right area with a custom component via `rightMenuContent`. The bar, search box and dropdown panels use the semantic `bg-surface` / `border-line` / `text-foreground` tokens, so they follow dark mode.\n\n## Import\n\n```jsx\nimport { Navbar } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `emitter` | `object` | **required** | Event emitter for notifications (e.g. `notification:view`, `notification:markAsRead`, etc.). |\n| `logo` | `ReactNode` | — | Logo (e.g. image or link). Truncates on narrow screens. |\n| `center` | `ReactNode` | — | Centre slot (e.g. a search field or primary action) between the logo and the right-hand icons. Rendered in a `min-w-0 flex-1` column so it shrinks first on narrow screens; give its content a fluid width such as `w-full max-w-md`. |\n| `items` | `Array` | `[]` | Nav items: `{ id, label, href?, active?, onClick?(item) }`. If `href` is set, renders `<a>`; else `<button>` with `onClick`. |\n| `user` | `object` | — | `{ name, email, avatar?, menuItems? }`. If set, shows the user menu and a logout button; if omitted, a login button. Without `avatar`, the menu trigger shows `name` initials (via `Avatar`). |\n| `notifications` | `Array` | `[]` | List of notifications for the dropdown. Each: `{ id, title, message?, read? }`. |\n| `searchable` | `boolean` | `false` | Show the search input from `sm` up. Below `sm` a **Search** icon button opens a top `Sheet` holding a [`SearchField`](SearchField.md) instead (same term, same `onSearch`). |\n| `onSearch` | `(term: string) => void` | — | Called with the current term on search form submit (desktop) or Enter in the phone search sheet (the sheet then closes). |\n| `sticky` | `boolean` | `false` | Sticks the bar to the top (`sticky top-0 z-sticky`), pads it with the top safe area (`pt-safe`) and makes it translucent (`bg-surface/80 backdrop-blur` where `backdrop-filter` is supported; opaque `bg-surface` otherwise). |\n| `largeTitle` | `ReactNode` | — | iOS large title: an `<h1>` under the bar that collapses into a compact centred title in the bar once the window scrolls past 44px (and expands again under 8px). Passive scroll listener, SSR-safe (expanded on the server), instant under `prefers-reduced-motion`. |\n| `leftIcon` | `ReactNode` \\| `false` | `<ChevronLeft />` | Icon shown on mobile (e.g. back). Set `false` to hide. |\n| `onLeftIconClick` | `(event) => void` | — | Called when left icon (mobile) is clicked. |\n| `leftIconLabel` | `string` | `\"Go back\"` | Accessible name of the left button. Set it when the button is not \"back\", e.g. `\"Open navigation\"` when it opens a `Sidebar` drawer. |\n| `leftIconProps` | `ButtonHTMLAttributes` | — | Extra props spread onto the left `<button>` — e.g. `{ \"aria-expanded\": open, \"aria-controls\": \"app-sidebar\" }` when it toggles a drawer. `className` merges last; `onClick` runs after `onLeftIconClick`. |\n| `rightMenuContent` | `ReactNode` \\| `(props) => ReactNode` | — | Custom right menu. An element is rendered as is; a function receives `{ notifications }` and any Navbar `...props` (e.g. `emitter`, `onFetch`). If omitted or `null`, the default notifications dropdown renders. |\n| `onLoginClick` | `() => void` | — | Called when the login icon button (accessible name \"Sign in\") is clicked. |\n| `onLogoutClick` | `() => void` | — | Called when the logout icon button (accessible name \"Sign out\") or the user-menu **Sign out** item is clicked. |\n| `onFetch` | `({ setNotifications }) => void` | — | Refresh handler for the default notifications dropdown. Called on mount and when `notifications` changes. Consumed by the right menu — it is **not** forwarded onto `<nav>`. |\n| `className` | `string` | — | Wrapper CSS classes. |\n| ...rest | — | — | Only DOM-valid attributes (e.g. `id`, `aria-*`, `data-*`, event handlers) are forwarded to the root `<nav>`. The component's own control props (`isMobileOpen`, `setIsMobileOpen`, `onFetch`, …) are consumed and never leak to the DOM. |\n\n`Navbar` forwards `ref` to its root `<nav>` element.\n\n## Touch targets and labels\n\nIcon buttons (back, search, notifications, sign in/out, menu, user menu) are 36px on desktop and grow to the 44×44px touch target on coarse pointers, with a `focus-visible` ring. Accessible names: **Go back** (the left button; rename it with `leftIconLabel`), **Search**, **Notifications** (or **Notifications, 3 unread**), **Sign in**, **Sign out**, **Open menu** / **Close menu** (with `aria-expanded`) and **User menu**.\n\nThe unread badge grows with its count (`min-w-4` + padding) and caps at **99+**. It is `aria-hidden`; the count is in the bell's name.\n\n## Sticky bar and large title\n\n```jsx\n<Navbar emitter={emitter} logo={<Logo />} sticky largeTitle=\"Invoices\" searchable onSearch={search} />\n```\n\nThe large title collapses with the window scroll, so use it on pages that scroll the document (not an inner scroll container). Add `viewport-fit=cover` to your viewport meta for the safe-area inset.\n\n## Small screens (≤ 390px)\n\nThe header fits a 390px phone: columns use `gap` + `min-w-0` so the logo\ntruncates and the `center` slot shrinks instead of overflowing. Below the `sm`\nbreakpoint the standalone logout icon is hidden and a **Sign out** item appears\nat the bottom of the user menu instead (it calls `onLogoutClick`). With\n`searchable`, the inline search box is replaced by a **Search** button that\nopens the search sheet. From `sm` up the layout is unchanged.\n\n## Centre slot and initials avatar\n\n```jsx\n<Navbar\n  emitter={emitter}\n  logo={<Logo />}\n  center={<Input type=\"search\" placeholder=\"Search tasks...\" className=\"w-full max-w-md\" />}\n  user={{ name: 'Ada Lovelace', email: 'ada@example.com' }} // no avatar → \"AL\"\n/>\n```\n\n## Item shape (items)\n\n- `id`: string or number (key).\n- `label`: string.\n- `href`: optional; if set, item is an `<a href={href}>`.\n- `active`: optional boolean; applies primary styling.\n- `onClick(item)`: optional; used when no `href` (button click).\n\n## Notification shape (notifications)\n\n- `id`: string or number.\n- `title`: string.\n- `message`: optional string.\n- `read`: optional boolean; unread count uses `!n.read`.\n\n## Default notifications dropdown\n\nIf `rightMenuContent` is not provided, the right menu shows a bell icon and dropdown with:\n\n- Unread count badge.\n- \"Clear all\" that clears the list and calls emitter `notification:clearAll`.\n- Per notification: title, message, \"Mark as Read\" / \"Mark as Unread\", \"Delete\" (emitter events).\n- Clicking a notification calls `emitter.emit('notification:view', [n])`.\n\nTo refresh the list from the server, pass `onFetch({ setNotifications })`; the default dropdown uses it on mount and when `notifications` prop changes.\n\n## Example\n\n```jsx\nimport { Navbar } from '@dreamtree-org/twreact-ui';\nimport MyEmitter from './emitter';\n\n<Navbar\n  emitter={MyEmitter}\n  logo={<a href=\"/\"><img src=\"/logo.svg\" alt=\"Home\" /></a>}\n  items={[\n    { id: '1', label: 'Home', href: '/', active: pathname === '/' },\n    { id: '2', label: 'About', href: '/about' },\n    { id: '3', label: 'Settings', onClick: () => openSettings() },\n  ]}\n  user={user}\n  notifications={notifications}\n  searchable\n  onSearch={(term) => doSearch(term)}\n  onLoginClick={() => navigate('/login')}\n  onLogoutClick={logout}\n  onFetch={async ({ setNotifications }) => {\n    const res = await fetch('/api/notifications');\n    const data = await res.json();\n    setNotifications(data.items);\n  }}\n/>\n```\n\n### Left button as the Sidebar menu button\n\n```jsx\nimport { Menu } from 'lucide-react';\n\n<Navbar\n  emitter={MyEmitter}\n  leftIcon={<Menu />}\n  leftIconLabel=\"Open navigation\"\n  leftIconProps={{ 'aria-expanded': drawerOpen, 'aria-controls': 'app-sidebar' }}\n  onLeftIconClick={() => setDrawerOpen(true)}\n/>\n<Sidebar id=\"app-sidebar\" items={items} isMobileOpen={drawerOpen} setIsMobileOpen={setDrawerOpen} />\n```\n\n[← Component overview](README.md)\n",
     "OptionCard": "# OptionCard\n\nSelectable choice tile for **rich choices**: page templates (with a small wireframe), \"add a block\" pickers, starter kits. Each tile has a title, a description, an optional media slot, an optional badge and a selected state (primary border and ring **plus** a check indicator, so it never relies on colour alone). Wrap tiles in `OptionCardGroup` for a responsive grid with `role=\"radiogroup\"` semantics, or `multiple` for checkbox-group semantics. On its own an `OptionCard` is a toggle button (`aria-pressed`). For short text-only choices use `SegmentedControl` or `Radio` instead.\n\n## Import\n\n```jsx\nimport { OptionCard, OptionCardGroup } from '@dreamtree-org/twreact-ui';\n// OptionCard.Group is the same component as OptionCardGroup.\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `string` | — | The value this tile stands for (a string or number). Required inside an `OptionCardGroup`, where it is compared with the group's `value`; passed to `onSelect` everywhere. |\n| `title` | `ReactNode` | — | Tile heading. Also the tile's accessible name (`aria-labelledby`). |\n| `description` | `ReactNode` | — | Secondary text under the title (`text-muted`). Also the tile's accessible description (`aria-describedby`). |\n| `media` | `ReactNode` | — | Optional visual above the text, e.g. a small wireframe SVG or an image. Clipped to rounded corners. |\n| `badge` | `ReactNode` | — | Optional small pill next to the title, e.g. `\"New\"` or `\"Pro\"`. |\n| `selected` | `boolean` | `false` | Standalone only: whether the tile is pressed (controlled). Ignored inside a group, which derives it from its `value`. |\n| `onSelect` | `(value, event) => void` | — | Called when the tile is activated (click, `Enter` or `Space`), standalone or inside a group. Not called while disabled. |\n| `disabled` | `boolean` | `false` | Dims the tile, sets `aria-disabled`, removes it from the tab order and keyboard navigation, and ignores activation. |\n| `children` | `ReactNode` | — | Extra content rendered below the description. |\n| `className` | `string` | — | Merged onto the tile with `cn`, so your classes win on conflict. |\n\nOther props (`id`, `data-*`, event handlers, …) go to the tile's root `<div>` (`role=\"radio\"`, `\"checkbox\"` or `\"button\"`), which also receives the forwarded `ref`. Your `onClick` / `onKeyDown` run first; call `event.preventDefault()` to stop the tile from selecting.\n\n## OptionCardGroup props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `string \\| string[]` | — | Controlled selection: a single value, or an array of values with `multiple`. |\n| `defaultValue` | `string \\| string[]` | — | Uncontrolled initial selection. Without `value` or `defaultValue` nothing is selected and the first enabled tile is the tab stop. |\n| `onChange` | `(value) => void` | — | Receives the new value (single) or the new array (`multiple`), not a DOM event. In single mode it is not called when the selected tile is activated again. |\n| `multiple` | `boolean` | `false` | Multi-select: the root becomes `role=\"group\"`, tiles become `role=\"checkbox\"`, and `value` is an array. |\n| `columns` | `number` | `3` | `1`–`4`. Always one column on phones; two from `sm`, then `columns` from `lg`. |\n| `label` | `ReactNode` | — | Visible label above the grid, wired up as the group's `aria-labelledby`. |\n| `aria-label` | `string` | — | Accessible name when there is no visible `label`. Pass `label`, `aria-label` or `aria-labelledby`. |\n| `name` | `string` | — | Submits the selection with a form through hidden inputs (one per selected value). |\n| `disabled` | `boolean` | `false` | Disable every tile (dimmed, `aria-disabled` on the root and on each tile). |\n| `className` | `string` | — | Merged onto the root with `cn`. |\n\nOther props go to the root `<div role=\"radiogroup\">` (or `role=\"group\"`), which receives the forwarded `ref`. Tiles connect to their group through React context, so they can sit at any depth inside it.\n\n## Behavior\n\n- **Keyboard (group):** one tab stop (roving tabindex): the last focused tile, else the selected tile, else the first enabled tile. `ArrowRight` / `ArrowDown` and `ArrowLeft` / `ArrowUp` move to the next / previous tile in DOM order, skip disabled tiles and wrap around; `Home` / `End` jump to the first / last enabled tile. Under `dir=\"rtl\"` the left and right arrows swap. In a single-select group the arrows also **select** (standard radio behaviour); in a `multiple` group they only move focus. `Space` / `Enter` select the focused tile (toggle it with `multiple`).\n- **Keyboard (standalone):** the tile is a focusable `role=\"button\"` with `aria-pressed`; `Enter` / `Space` activate it.\n- **Styling:** `bg-surface` tile with a `border-line` border; selected tiles get a primary border, a `ring-1` primary ring, a light primary tint (dark-mode aware) and a filled check indicator in the top-right corner (round for radios, square for checkboxes). Tiles are at least 44px tall, lift on hover, show a `focus-visible` ring and shrink slightly while pressed. Transitions and the press effect are off under `prefers-reduced-motion`.\n- **Media:** decorative wireframes should carry `aria-hidden=\"true\"`; the tile's name comes from `title`.\n\n## Example\n\n```jsx\nconst [template, setTemplate] = useState('classic');\n\n<OptionCardGroup value={template} onChange={setTemplate} columns={3} aria-label=\"Template\">\n  <OptionCard value=\"classic\" title=\"Classic\" description=\"Filters beside the grid\" media={<Sketch />} />\n  <OptionCard value=\"stacked\" title=\"Stacked\" description=\"Filters above the grid\" badge=\"New\" />\n  <OptionCard value=\"minimal\" title=\"Minimal\" description=\"No filters\" disabled />\n</OptionCardGroup>\n\n<OptionCardGroup multiple label=\"Blocks to add\" defaultValue={['hero']} onChange={setBlocks} columns={2}>\n  <OptionCard value=\"hero\" title=\"Hero\" description=\"Large heading with a call to action\" />\n  <OptionCard value=\"faq\" title=\"FAQ\" description=\"Collapsible questions\" />\n</OptionCardGroup>\n\n<OptionCard value=\"starter\" title=\"Starter kit\" description=\"Pages and blocks to begin with\" selected={on} onSelect={() => setOn(!on)} />\n```\n\n[← Component overview](README.md)\n",
     "PageHeader": "# PageHeader\n\nPage-level block: the page title (`h1`), a muted subtitle, the page's actions (one primary action) and an optional back link. Extracted from taskpro `features/shared/PageHeader.jsx`.\n\n## Import\n\n```jsx\nimport { PageHeader } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `title` | `ReactNode` | — | Page title, rendered as the page's only `h1` |\n| `subtitle` | `ReactNode` | — | One line under the title |\n| `actions` | `ReactNode` | — | Buttons on the right; keep one primary action |\n| `actionsPlacement` | `'inline' \\| 'bottom'` | `\"inline\"` | `inline`: actions next to the title. `bottom`: on phones (coarse pointer and ≤639px) the actions are pinned in a [`BottomActionBar`](BottomActionBar.md) (`fullWidth`) at the bottom of the screen; on desktop, and on the server until hydration, they stay inline |\n| `back` | `{ href: string; label: string }` | — | Back link for detail pages. Grows to a 44px touch target on coarse pointers; `focus-visible` ring |\n| `linkAs` | `ElementType` | `\"a\"` | Link element for the back link |\n| `className` | `string` | — | Extra CSS classes (merged with `cn`) |\n| ...rest | `HTMLAttributes<HTMLDivElement>` | — | Forwarded to the root `<div>`; the ref is forwarded to it |\n\n## Example\n\n```jsx\n<PageHeader\n  title=\"Compliance calendar\"\n  subtitle=\"Track deadlines, ownership and filing readiness across clients\"\n  actions={<Button leftIcon={<Plus className=\"h-4 w-4\" />}>Add obligation</Button>}\n/>\n```\n\n### Actions at the bottom on phones\n\n```jsx\n<PageHeader\n  title=\"New invoice\"\n  back={{ href: '/invoices', label: 'Invoices' }}\n  actionsPlacement=\"bottom\"\n  actions={\n    <>\n      <Button variant=\"outline\">Save draft</Button>\n      <Button>Send invoice</Button>\n    </>\n  }\n/>\n{form}\n<BottomActionBar.Spacer className=\"sm:hidden\" />\n```\n\nWith `actionsPlacement=\"bottom\"`, put a `BottomActionBar.Spacer` at the end of the page so the bar doesn't cover the last fields. The actions render once (never duplicated), so ids and test queries stay unique.\n\n[← Component overview](README.md)\n",
     "Pagination": "# Pagination\n\nPage navigation: first, previous, page numbers, next, last. Renders only when `totalPages > 1`. Optional `theme` for styling (e.g. from Table). Page buttons use the semantic `bg-surface` / `border-line` / `text-foreground` tokens, so they follow dark mode.\n\n## Import\n\n```jsx\nimport { Pagination } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `currentPage` | `number` | `1` | Current page (1-based). |\n| `totalPages` | `number` | `1` | Total pages. If ≤ 1, component returns null. |\n| `onPageChange` | `(page: number) => void` | — | Called when user selects a page. |\n| `showFirstLast` | `boolean` | `true` | Show first/last page buttons (and the `...` ellipses). The jump-to-first / jump-to-last button only renders when page 1 / the last page is outside the visible page window, so no page number ever appears twice. |\n| `showPrevNext` | `boolean` | `true` | Show previous/next buttons. |\n| `maxVisiblePages` | `number` | `5` | Max page number buttons to show. |\n| `className` | `string` | — | Nav wrapper CSS classes. |\n| ...rest | — | — | Passed to `<nav>`. |\n\n**Responsive:** below the `sm` breakpoint (640 px) the bar collapses to a compact `‹ Page 3 of 10 ›` layout. Only previous/next and the status text show; the page numbers, jump buttons and ellipses are hidden with CSS (`hidden sm:inline-flex`). From `sm` up the full layout is unchanged. When `showPrevNext={false}`, nothing would drive the compact view, so the full layout shows at every width. Buttons wrap instead of overflowing, grow to a 44 px touch target on coarse pointers, show a `focus-visible` ring, and have dark-mode colours.\n\n## Example\n\n```jsx\n<Pagination\n  currentPage={page}\n  totalPages={Math.ceil(total / pageSize)}\n  onPageChange={setPage}\n  maxVisiblePages={5}\n/>\n```\n\n[← Component overview](README.md)\n",
+    "PhotoCollage": "# PhotoCollage\n\nOverlapping, offset photos with floating stat chips and an optional badge (for example a [RotatingBadge](RotatingBadge.md)). On scroll the photos drift at different depths (parallax), driven by a CSS variable — no re-renders. Part of the `/motion` entry point ([overview](Motion.md)).\n\n## Install\n\nNothing extra — the `/motion` entry point has no required peer dependency.\n\n## Import\n\n```jsx\nimport { PhotoCollage } from '@dreamtree-org/twreact-ui/motion';\n```\n\nNever import it from the root `@dreamtree-org/twreact-ui` — the motion components are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `images` | `{ src: string; alt: string }[]` | `[]` | **Required.** 1–4 photos, placed in fixed overlapping slots (extra photos are ignored) |\n| `chips` | `{ value: ReactNode; label: ReactNode }[]` | `[]` | Floating stat chips, up to 2 |\n| `parallax` | `number` | `0.15` | Parallax strength (0–1): a photo moves up to ±`parallax` × 120 px × its depth. `0` disables |\n| `badge` | `ReactNode` | — | A node pinned to the top-right corner |\n| `className` | `string` | — | Extra classes for the root `<div>` (merged with `cn`; default `max-w-xl`, aspect 5:6) |\n| `ref` | `Ref<HTMLDivElement>` | — | Forwarded to the root `<div>` |\n| ...rest | `HTMLAttributes<HTMLDivElement>` | — | Forwarded to the root `<div>` |\n\n## Examples\n\n```jsx\n<PhotoCollage\n  images={[\n    { src: '/img/team.jpg', alt: 'The team at a whiteboard' },\n    { src: '/img/office.jpg', alt: 'Our office' },\n    { src: '/img/desk.jpg', alt: 'A desk with sketches' },\n  ]}\n  chips={[{ value: '2012', label: 'Founded' }, { value: '50+', label: 'People' }]}\n  badge={<RotatingBadge text=\"DREAMTREE • SINCE 2012 • \" className=\"bg-warning-300 text-gray-950\" />}\n/>\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Images | Each photo is a `<figure>` with an `<img>` using your `alt` (lazy-loaded) |\n| Chips | Plain text, read in DOM order after the photos |\n| Motion | The parallax transform is under `motion-safe:`, so it never applies with `prefers-reduced-motion: reduce` |\n\n## Reduced motion & server rendering\n\nThe server renders the photos in their resting positions (`--dt-p` unset, so the offset is 0). Under `prefers-reduced-motion: reduce`, or with `parallax={0}`, no scroll work runs and the photos stay put.\n\n[← Component overview](README.md)\n",
     "Popover": "# Popover\n\nAnchored, click-triggered panel for **interactive** content — filter forms, share menus, quick editors. Unlike `Tooltip` (hover/focus, read-only text), a Popover takes focus, can hold buttons and inputs, and stays open until dismissed. Positioned in a portal by the shared floating engine (flip to the opposite side, shift to stay in view). On phones it becomes a bottom sheet (see **Presentation**). The panel uses the semantic `bg-surface` / `border-line` / `text-foreground` tokens, so it follows dark mode.\n\n## Import\n\n```jsx\nimport { Popover } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `trigger` | `ReactElement` | — | Element that toggles the popover (required). Gets `aria-haspopup`, `aria-expanded`, `aria-controls` and an `onClick`; its own `onClick` still runs (call `preventDefault()` to stop the toggle). A string is wrapped in a `<button>` |\n| `children` | `ReactNode or function` | — | Panel content, or `({ close }) => ReactNode` |\n| `open` | `boolean` | — | Controlled open state |\n| `defaultOpen` | `boolean` | `false` | Initial state when uncontrolled |\n| `onOpenChange` | `function` | — | `(open) => void`, called on every open/close |\n| `placement` | `string` | `\"bottom-start\"` | `top`, `bottom`, `left`, `right`, each optionally with `-start` or `-end`; flips when there is no room |\n| `offset` | `number` | `8` | Gap in px between trigger and panel |\n| `title` | `ReactNode` | — | Heading inside the panel; labels the dialog |\n| `initialFocusRef` | `RefObject` | — | Element to focus on open (default: first focusable element) |\n| `disabled` | `boolean` | `false` | Disable the trigger |\n| `presentation` | `\"auto\"`, `\"popover\"` or `\"sheet\"` | `\"auto\"` | `auto` shows a bottom [`Sheet`](Sheet.md) on small touch screens (`(pointer: coarse) and (max-width: 639px)`) and the anchored panel elsewhere; `popover` / `sheet` force one. `auto` renders the panel on the server and while hydrating |\n| `id` | `string` | — | Panel id (auto-generated otherwise) |\n| `className` | `string` | — | Extra classes for the panel, or for the sheet panel in sheet mode (merged with `cn`) |\n| `...rest` | `HTMLAttributes` | — | Forwarded to the panel (`aria-label`, `data-*`, …); `ref` points at the panel (the sheet panel in sheet mode). The panel carries `data-presentation=\"popover\"` or `\"sheet\"` |\n\nSupports both modes: **uncontrolled** (`defaultOpen`) for most cases, **controlled** (`open` + `onOpenChange`) when something else must open or close it.\n\n## Examples\n\n### Basic\n\n```jsx\n<Popover trigger={<Button variant=\"outline\">Filters</Button>} title=\"Filter tasks\">\n  {({ close }) => (\n    <div className=\"space-y-3\">\n      <Checkbox label=\"Assigned to me\" />\n      <Button size=\"sm\" onClick={close}>Apply</Button>\n    </div>\n  )}\n</Popover>\n```\n\n### Controlled\n\n```jsx\nconst [open, setOpen] = useState(false);\n\n<Popover open={open} onOpenChange={setOpen} placement=\"top-end\" aria-label=\"Share\" trigger={<Button>Share</Button>}>\n  <p>Anyone with the link can view.</p>\n</Popover>\n```\n\n### Presentation (phones)\n\n```jsx\n// Default: anchored panel on desktop, bottom sheet on phones\n<Popover trigger={<Button>Sort</Button>} title=\"Sort by\">…</Popover>\n\n// Keep the anchored panel everywhere\n<Popover presentation=\"popover\" trigger={<Button>Sort</Button>}>…</Popover>\n```\n\nIn sheet mode the content renders inside `<Sheet.Body>` of a bottom `Sheet`: `title` becomes the sheet title (with its close button), and the sheet adds a grab handle, drag-to-dismiss, a backdrop and the safe-area padding. `open` / `onOpenChange`, the `({ close })` render prop, `initialFocusRef`, `className`, `id` and `ref` work the same way.\n\n## Accessibility & keyboard\n\n| Behavior | Detail |\n|----------|--------|\n| Trigger | `aria-haspopup=\"dialog\"`, `aria-expanded`, `aria-controls` (the panel id while open) |\n| Panel | `role=\"dialog\"` (non-modal), labelled by `title` or your `aria-label` |\n| Focus on open | `initialFocusRef`, else the first focusable element, else the panel |\n| `Escape` | Closes and returns focus to the trigger |\n| Outside click | Closes; focus stays where the user clicked |\n| `Tab` past the last item / `Shift`+`Tab` before the first | Closes and continues from the trigger, as if the panel sat right after it |\n| Reduced motion | Fade-in is disabled under `prefers-reduced-motion` |\n| Dark mode | Panel uses `dark:` variants |\n| Sheet mode | The sheet is a **modal** `role=\"dialog\"` (`aria-modal=\"true\"`): focus is trapped inside, `Escape`, a backdrop tap or a downward drag closes it, and focus returns to the trigger |\n\n[← Component overview](README.md)\n",
     "PriceRangePicker": "# PriceRangePicker\n\nDual-thumb range slider for min/max values (e.g. price or any number). Optional number inputs and preset buttons. Controlled via `value` or uncontrolled via `defaultValue`.\n\n## Import\n\n```jsx\nimport { PriceRangePicker } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `min` | `number` | `0` | Minimum value. |\n| `max` | `number` | `1000` | Maximum value. |\n| `step` | `number` | `1` | Step for thumbs and inputs. |\n| `minGap` | `number` | `5` | Minimum gap between min and max. |\n| `value` | `{ min, max }` \\| `null` | `null` | Controlled value. |\n| `defaultValue` | `{ min, max }` | `{ min: 0, max: 1000 }` | Uncontrolled initial value. |\n| `onChange` | `(value: { min, max }) => void` | `() => {}` | Called on thumb/input change. |\n| `onFinalChange` | `(value: { min, max }) => void` | `() => {}` | Called when a thumb drag ends (mouse, touch or pen), on each thumb key press, and on Enter/blur in the inputs. |\n| `showInputs` | `boolean` | `true` | Show min/max number inputs. |\n| `showTooltips` | `boolean` | `true` | Show a value tooltip above the thumb while dragging. |\n| `disabled` | `boolean` | `false` | Disable the control. |\n| `presets` | `Array<{ id, label, value: { min, max } }>` | `[]` | Preset buttons. |\n| `formatValue` | `(n: number) => string` | `(n) => String(n)` | Format display (e.g. currency). |\n| `className` | `string` | `\"\"` | Container CSS classes. |\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `\"md\"` | Thumb and spacing size. |\n| `colorClass` | `string` | `\"bg-primary-600\"` | Tailwind `bg-*` class for the active track and both thumbs. |\n| `ariaLabel` | `string` | `\"Price range\"` | Accessibility label. |\n\n## Accessibility and touch\n\n- Each thumb is a `role=\"slider\"` (`aria-label` is `\"{ariaLabel} - min\"` / `\"{ariaLabel} - max\"`). Arrow keys step, Page Up/Down move 10% of the range, Home/End jump to the bounds.\n- Pointer drag uses pointer capture: pressing anywhere on the track grabs the nearest thumb, and a release outside the track still ends the drag. Both thumbs work with mouse, touch and pen.\n- On touch screens each thumb has a 44px hit area; the number inputs use `inputMode=\"decimal\"`.\n- Since 1.4: the default colour is the brand `primary` token (was pink), and the component no longer injects a global `<style>` that restyled every `input[type=range]` on the page.\n\n## Example\n\n```jsx\nconst [range, setRange] = useState({ min: 100, max: 500 });\n<PriceRangePicker\n  min={0}\n  max={1000}\n  value={range}\n  onChange={setRange}\n  formatValue={(n) => `$${n}`}\n  presets={[\n    { id: '1', label: 'Under $200', value: { min: 0, max: 200 } },\n  ]}\n/>\n```\n\n[← Component overview](README.md)\n",
     "ProductCard": "# ProductCard\n\nPage-level block: a storefront product tile for listing grids, featured rows and \"similar products\". Cover image (with an optional second image on hover), badges over the image, brand, title, spec line, price with a struck-through compare-at price and a computed discount, an actions slot and an optional compare toggle. Replaces the Card + Badge + Checkbox + Button compositions apps kept hand-rolling (issue #181).\n\nThe whole card is one link: the title is the link, and its `::after` stretches over the card so the image and blank space are clickable too, with no interactive elements nested inside the link. `actions` and the compare checkbox sit above it and stay separately focusable. The focus ring is drawn around the whole card; the hover zoom and image swap are off under `prefers-reduced-motion`.\n\n## Import\n\n```jsx\nimport { ProductCard } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `title` | `ReactNode` | — | Product name; becomes the link when `href` / `to` / `as` is set. Also the default image `alt` when it is a string |\n| `image` | `string` \\| `{ src: string; alt?: string }` | — | Cover image |\n| `images` | `Array<string \\| { src: string; alt?: string }>` | — | More images; with `image` set they follow it, otherwise the first one is the cover. The second image is used by `hover=\"second-image\"` |\n| `imageAlt` | `string` | `title` | `alt` for images given as plain strings |\n| `imageRatio` | `4:3` \\| `1:1` \\| `3:4` | `\"4:3\"` | Aspect ratio of the image area |\n| `hover` | `none` \\| `zoom` \\| `second-image` | `\"none\"` | Image effect on hover; disabled under reduced motion. The second image is decorative (`alt=\"\"`) |\n| `eyebrow` | `ReactNode` | — | Small line above the title, usually the brand |\n| `meta` | `ReactNode` | — | Spec line under the title (size, colour, pack) |\n| `badges` | `ReactNode[]` | — | Overlaid on the image's top-left corner, e.g. `<Badge>` elements |\n| `price` | `number` \\| `string` | — | Selling price. Numbers go through `priceFormatter`; strings (\"From ₹999\") pass through |\n| `compareAtPrice` | `number` \\| `string` | — | Original price, struck through, announced as \"Original price\" to screen readers |\n| `discountLabel` | `ReactNode` | — | Shown after the prices. When omitted and both prices are numbers with `compareAtPrice` higher, it is computed, e.g. `\"26% off\"` |\n| `priceFormatter` | `(value: number) => ReactNode` | INR, `en-IN`, no decimals | Formats numeric prices (`2999` → `₹2,999`, `125000` → `₹1,25,000`) |\n| `layout` | `stack` \\| `row` | `\"stack\"` | `row`: image beside the text on phones, stacked from `sm` up |\n| `href` | `string` | — | Link target; renders the title as an `<a>` |\n| `to` | `string` | — | Router target passed to `as` (e.g. React Router `Link`); without `as` it is used as the `href` |\n| `as` | `ElementType` | `\"a\"` | Link component for the title, like `Button`'s `as` |\n| `actions` | `ReactNode` | — | Buttons under the price (Add to cart, Wishlist), above the stretched link |\n| `selectable` | `boolean` | `false` | Shows a \"Compare\" checkbox on the image |\n| `selected` | `boolean` | — | Controlled compare state; omit for uncontrolled |\n| `onSelectedChange` | `(selected: boolean, event) => void` | — | Called when the compare checkbox is toggled |\n| `placeholder` | `ReactNode` | image-off icon | Shown when there is no image or the cover fails to load |\n| `className` | `string` | — | Extra CSS classes on the card root; other props are forwarded to it |\n\n## Example\n\n```jsx\n<ProductCard\n  title=\"Trail Runner 2\"\n  eyebrow=\"Acme\"\n  meta=\"Size 9 · Ocean blue\"\n  images={['/shoes/tr2-front.jpg', '/shoes/tr2-side.jpg']}\n  hover=\"second-image\"\n  badges={[<Badge key=\"new\" variant=\"primary\" size=\"sm\">New</Badge>]}\n  price={2999}\n  compareAtPrice={4049}\n  as={Link}\n  to=\"/p/trail-runner-2\"\n  actions={<Button size=\"sm\">Add to cart</Button>}\n/>\n\n<ProductCard\n  layout=\"row\"\n  title=\"Road Pacer\"\n  image={{ src: '/shoes/rp.jpg', alt: 'Road Pacer, side view' }}\n  price={3499}\n  href=\"/p/road-pacer\"\n  selectable\n  selected={compare.includes('rp')}\n  onSelectedChange={(on) => toggleCompare('rp', on)}\n/>\n```\n\n[← Component overview](README.md)\n",
@@ -7230,9 +8167,13 @@
     "QuantityStepper": "# QuantityStepper\n\nA **− / value / +** control for cart lines and buy boxes, where `Input type=\"number\"` is awkward on phones. The value is a `role=\"spinbutton\"` with `aria-valuenow` / `aria-valuemin` / `aria-valuemax`; the decrement and increment buttons step it and are disabled at the bounds. Controlled or uncontrolled.\n\n## Import\n\n```jsx\nimport { QuantityStepper } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `number` | — | Controlled value. Values outside `min` / `max` are clamped for display. |\n| `defaultValue` | `number` | `min` | Uncontrolled initial value. Falls back to `min`, or `0` when `min` is not finite. |\n| `onChange` | `(value) => void` | — | Receives the next number (not a DOM event), already clamped to `min` / `max` and rounded to the precision of `step`. Not called when the value would not change. |\n| `min` | `number` | `0` | Lowest value. The decrement button is disabled at `min`. |\n| `max` | `number` | `Infinity` | Highest value, e.g. the stock count. The increment button is disabled at `max`. Without a finite `max`, `aria-valuemax` is omitted and `End` does nothing. |\n| `step` | `number` | `1` | Amount each button press or arrow key moves the value. Decimal steps (`0.5`) do not drift. Non-positive values fall back to `1`. |\n| `size` | `string` | `\"md\"` | `sm`, `md` or `lg` (32 / 40 / 48px tall). The buttons grow to 44 × 44px on coarse pointers (touch screens). |\n| `disabled` | `boolean` | `false` | Dims the control, disables both buttons, removes the spinbutton from the tab order and sets `aria-disabled`. |\n| `loading` | `boolean` | `false` | For a pending server update: shows a spinner in place of the value, disables the buttons, ignores keys and sets `aria-busy`. The spinbutton keeps focus. The spinner stops under `prefers-reduced-motion`. |\n| `label` | `ReactNode` | — | Visible label above the control; it names the spinbutton through `aria-labelledby`. |\n| `hideLabel` | `boolean` | `false` | Keeps `label` for screen readers only (`sr-only`), for tight cart rows. |\n| `formatValue` | `(value) => ReactNode` | — | Renders the displayed value, e.g. `` v => `${v} kg` ``. When it returns a string or number it is also used as `aria-valuetext`. |\n| `decrementLabel` | `string` | `\"Decrease quantity\"` | Accessible name of the − button. |\n| `incrementLabel` | `string` | `\"Increase quantity\"` | Accessible name of the + button. |\n| `name` | `string` | — | Submits the value with a form through a hidden input. |\n| `aria-label` | `string` | — | Accessible name of the spinbutton when there is no `label`. |\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>`, which also receives the forwarded `ref`.\n\n## Behavior\n\n- **Keyboard:** the spinbutton is the single tab stop (the − / + buttons are pointer targets with `tabIndex={-1}`, as in the WAI-ARIA spinbutton pattern). `ArrowUp` / `ArrowDown` step by `step`, `PageUp` / `PageDown` by ten steps, `Home` / `End` jump to `min` / `max`. Every change is clamped to the bounds.\n- **Bounds:** the − button is disabled at `min` and the + button at `max`, so a cart line with `min={1}` cannot reach zero by accident; use a separate remove action for that.\n- **Styling:** a bordered `bg-surface` group with `border-line` dividers, `text-foreground` value in tabular figures, and `hover:bg-line` buttons that turn `text-muted` when disabled. Buttons show a `focus-visible` ring and shrink slightly while pressed (off under reduced motion). All tokens follow dark mode.\n\n## Example\n\n```jsx\nconst [qty, setQty] = useState(1);\n\n<QuantityStepper label=\"Quantity\" value={qty} min={1} max={stock} onChange={setQty} />\n\n<QuantityStepper\n  label=\"Quantity, Ceramic mug\"\n  hideLabel\n  size=\"sm\"\n  value={line.qty}\n  min={1}\n  max={line.stock}\n  loading={line.updating}\n  onChange={(next) => updateLine(line.id, next)}\n/>\n\n<QuantityStepper label=\"Weight\" defaultValue={0.5} min={0.5} max={5} step={0.5} formatValue={(v) => `${v} kg`} />\n```\n\n[← Component overview](README.md)\n",
     "Radio": "# Radio\n\nSingle radio button; use multiple with the same `name` for a group. Controlled via `checked` or uncontrolled via `defaultChecked`.\n\n## Import\n\n```jsx\nimport { Radio } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `id` | `string` | auto | Input id. |\n| `name` | `string` | — | Group name (required for grouping). |\n| `value` | `any` | — | Value when selected. |\n| `checked` | `boolean` | — | Controlled checked. |\n| `defaultChecked` | `boolean` | — | Uncontrolled initial. |\n| `onChange` | `(e: Event) => void` | — | Change handler. |\n| `disabled` | `boolean` | `false` | Disable. |\n| `required` | `boolean` | `false` | Required. |\n| `label` | `string` | — | Label text. |\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `\"md\"` | Size. |\n| `labelPosition` | `\"left\"` \\| `\"right\"` | `\"right\"` | Label side. |\n| `radioColor` | `string` | `\"rgb(var(--dt-primary-600))\"` | Accent colour for the checked dot, as any CSS colour. Defaults to the brand's primary token, so it follows theming; prefer leaving it unset. |\n| `className` | `string` | `\"\"` | Label wrapper classes. |\n| `ariaLabel` | `string` | — | Accessibility label. |\n\n## Behavior\n\n- **Uncontrolled groups** (`defaultChecked`, no `checked`): selecting one radio\n  re-syncs every same-`name` Radio in the same form, so only one dot is ever\n  shown as selected. Give the group a shared `name`.\n- **Focus:** the native input is visually hidden; keyboard focus draws a\n  `focus-visible` ring on the visual circle.\n- The visual circle exposes `data-state=\"checked\" | \"unchecked\"` for styling.\n- **Look:** token surfaces (`bg-surface`, grey ring with a dark counterpart); the\n  ring takes the accent colour when checked and the dot springs in (off under\n  `prefers-reduced-motion`). The whole row is the hit area and is at least 44px\n  tall on coarse pointers.\n\n## Example\n\n```jsx\nconst [choice, setChoice] = useState('a');\n<>\n  <Radio name=\"choice\" value=\"a\" checked={choice === 'a'} onChange={() => setChoice('a')} label=\"Option A\" />\n  <Radio name=\"choice\" value=\"b\" checked={choice === 'b'} onChange={() => setChoice('b')} label=\"Option B\" />\n</>\n```\n\n[← Component overview](README.md)\n",
     "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",
+    "Reveal": "# Reveal\n\nPlays an entrance — fade up, fade, scale, clip, or word by word — when the element scrolls into view. Content already on screen at load is never hidden (no flash and no delay to the largest paint), so only content below the fold animates. Part of the `/motion` entry point ([overview](Motion.md)). To reveal several children in turn, use [RevealGroup](RevealGroup.md).\n\n## Install\n\nNothing extra — the `/motion` entry point has no required peer dependency.\n\n## Import\n\n```jsx\nimport { Reveal } from '@dreamtree-org/twreact-ui/motion';\n```\n\nNever import it from the root `@dreamtree-org/twreact-ui` — the motion components are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `effect` | `\"fade-up\"` \\| `\"fade\"` \\| `\"scale\"` \\| `\"clip\"` \\| `\"split-words\"` | `\"fade-up\"` | Entrance effect. `split-words` needs a string child; otherwise it renders the child unchanged |\n| `delay` | `number` | `0` | Delay before the entrance, in ms |\n| `stagger` | `number` | `40` | Delay between words for `split-words`, in ms |\n| `once` | `boolean` | `true` | Reveal once, or (`false`) hide again whenever the element leaves the viewport |\n| `as` | `ElementType` | `\"div\"` | Root element |\n| `children` | `ReactNode` | — | Content |\n| `className` | `string` | — | Extra classes for the root (merged with `cn`) |\n| `ref` | `Ref<HTMLElement>` | — | Forwarded to the root element |\n| ...rest | `HTMLAttributes<HTMLElement>` | — | Forwarded to the root |\n\n## Examples\n\n```jsx\n<Reveal>\n  <Card>Below-the-fold content</Card>\n</Reveal>\n\n<Reveal as=\"h2\" effect=\"split-words\" className=\"text-page-title\">\n  Software that tells your story\n</Reveal>\n\n<Reveal effect=\"clip\" delay={150}>\n  <img src=\"/team.jpg\" alt=\"The team\" />\n</Reveal>\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Content | Hidden content is only visually hidden with opacity / transform / clip-path; it stays in the accessibility tree |\n| Split words | The full sentence is read once from a visually hidden copy; the per-word spans are `aria-hidden` |\n| State | The root carries `data-reveal=\"static\" \\| \"hidden\" \\| \"shown\"` |\n| Motion | The transition uses `motion-reduce:transition-none` and nothing is hidden under reduced motion |\n\n## Reduced motion & server rendering\n\nThe server renders the content visible (`data-reveal=\"static\"`), so crawlers and no-JS readers see it. After hydration, only elements below the fold are hidden until they scroll in (15 % visible). Under `prefers-reduced-motion: reduce` nothing is hidden.\n\n[← Component overview](README.md)\n",
+    "RevealGroup": "# RevealGroup\n\nWraps each child in a [Reveal](Reveal.md) and staggers them: child `i` waits `delay + i * stagger` ms. Use it for card grids and lists that should enter one after another. Part of the `/motion` entry point ([overview](Motion.md)).\n\n## Install\n\nNothing extra — the `/motion` entry point has no required peer dependency.\n\n## Import\n\n```jsx\nimport { RevealGroup } from '@dreamtree-org/twreact-ui/motion';\n```\n\nNever import it from the root `@dreamtree-org/twreact-ui` — the motion components are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `effect` | `\"fade-up\"` \\| `\"fade\"` \\| `\"scale\"` \\| `\"clip\"` | `\"fade-up\"` | Entrance of each child. `\"split-words\"` is treated as `\"fade-up\"` |\n| `delay` | `number` | `0` | Delay before the first child, in ms |\n| `stagger` | `number` | `80` | Delay added per child, in ms |\n| `once` | `boolean` | `true` | Reveal once, or every time a child re-enters the viewport |\n| `as` | `ElementType` | `\"div\"` | Group element |\n| `itemAs` | `ElementType` | `\"div\"` | Element wrapping each child (e.g. `\"li\"` inside `as=\"ul\"`) |\n| `children` | `ReactNode` | — | The items. `null` / `false` children are skipped and do not take a delay slot |\n| `className` | `string` | — | Classes for the group element |\n| `ref` | `Ref<HTMLElement>` | — | Forwarded to the group element |\n| ...rest | `HTMLAttributes<HTMLElement>` | — | Forwarded to the group element |\n\n## Examples\n\n```jsx\n<RevealGroup as=\"ul\" itemAs=\"li\" stagger={120} className=\"grid gap-4 sm:grid-cols-3\">\n  <Card>Plan</Card>\n  <Card>Design</Card>\n  <Card>Build</Card>\n</RevealGroup>\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Semantics | Use `as=\"ul\"` + `itemAs=\"li\"` for a real list |\n| Content | Same as Reveal: hidden items stay in the accessibility tree; nothing is hidden under reduced motion |\n\n## Reduced motion & server rendering\n\nSame as [Reveal](Reveal.md): the server renders every child visible, only below-the-fold children animate after hydration, and nothing animates under `prefers-reduced-motion: reduce`.\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. The editor box and the toolbar link input use the semantic `bg-surface` / `border-line` / `text-foreground` tokens, so they follow dark mode.\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",
+    "RotatingBadge": "# RotatingBadge\n\nA circular badge with text set around its edge, slowly turning (SVG `textPath`). The text is spread to fill the circle exactly, so repeat it with separators. Part of the `/motion` entry point ([overview](Motion.md)).\n\n## Install\n\nNothing extra — the `/motion` entry point has no required peer dependency.\n\n## Import\n\n```jsx\nimport { RotatingBadge } from '@dreamtree-org/twreact-ui/motion';\n```\n\nNever import it from the root `@dreamtree-org/twreact-ui` — the motion components are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `text` | `string` | — | **Required.** Text set around the circle, e.g. `\"DREAMTREE • SINCE 2012 • \"`. Also the accessible name |\n| `speed` | `number` | `14` | Seconds per turn |\n| `size` | `number` | `120` | Diameter in px |\n| `icon` | `ReactNode` | — | Decorative node in the middle |\n| `className` | `string` | — | Extra classes for the root `<div>` (merged with `cn`). The text uses `currentColor` (default `text-foreground`); add a `bg-*` for a filled disc |\n| `ref` | `Ref<HTMLDivElement>` | — | Forwarded to the root `<div>` |\n| ...rest | `HTMLAttributes<HTMLDivElement>` | — | Forwarded to the root `<div>` (`aria-label` overrides the name) |\n\n## Examples\n\n```jsx\n<RotatingBadge text=\"DREAMTREE • SINCE 2012 • \" />\n\n<RotatingBadge\n  text=\"SCROLL • TO • EXPLORE • \"\n  size={140}\n  speed={20}\n  icon={<ArrowDown className=\"h-6 w-6\" />}\n  className=\"bg-primary-600 text-primary-foreground\"\n/>\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Name | One `role=\"img\"` named by `text` (or your `aria-label`); the SVG and the icon are `aria-hidden` |\n| Motion | The spin uses `motion-reduce:animate-none` |\n\n## Reduced motion & server rendering\n\nPure CSS animation: identical on the server and the client, with an SSR-safe path id from `React.useId()`. Under `prefers-reduced-motion: reduce` it does not turn.\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",
+    "ScrollStage": "# ScrollStage\n\nA pinned scroll scene: a tall section whose content sticks to the viewport (`sticky top-0 h-screen`) while the user scrolls through `length` viewport heights. Scene progress (0–1) is written to `--dt-p` on the root, so children can animate with CSS, and is also passed to `children(progress)` and `onProgress`. Part of the `/motion` entry point ([overview](Motion.md)).\n\n## Install\n\nNothing extra — the `/motion` entry point has no required peer dependency.\n\n## Import\n\n```jsx\nimport { ScrollStage } from '@dreamtree-org/twreact-ui/motion';\n```\n\nNever import it from the root `@dreamtree-org/twreact-ui` — the motion components are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `length` | `number` | `300` | Scroll distance of the scene in vh on desktop (token `scroll.sceneLength`). Values under 100 are raised to 100 |\n| `mobileLength` | `number` | `150` | Scene length in vh below `md` (token `scroll.sceneLengthMobile`) |\n| `pin` | `boolean` | `true` | Pin the content while the scene scrolls. `false` renders it in normal flow |\n| `children` | `ReactNode` \\| `(progress: ScrollProgress) => ReactNode` | — | Content, or a function that receives the live progress subscription (`get()` / `subscribe(fn)`). Inside, CSS can read `var(--dt-p, 1)` |\n| `onProgress` | `(progress: number) => void` | — | Called with the scene progress (0–1) on the frame loop |\n| `contentClassName` | `string` | — | Classes for the pinned inner box |\n| `as` | `ElementType` | `\"section\"` | Root element |\n| `className` | `string` | — | Extra classes for the root (merged with `cn`) |\n| `ref` | `Ref<HTMLElement>` | — | Forwarded to the root element |\n| ...rest | `HTMLAttributes<HTMLElement>` | — | Forwarded to the root (`id`, `data-*`, `aria-*`, handlers) |\n\n## Examples\n\n### CSS driven by progress\n\n```jsx\n<ScrollStage length={250} className=\"bg-gray-950 text-gray-50\">\n  <div className=\"flex h-full items-center justify-center\">\n    <h2 className=\"text-page-title [opacity:var(--dt-p,1)] [transform:scale(calc(0.6+var(--dt-p,1)*0.4))]\">\n      Grows as you scroll\n    </h2>\n  </div>\n</ScrollStage>\n```\n\n### Progress callback\n\n```jsx\nconst [step, setStep] = useState(0);\n\n<ScrollStage length={300} onProgress={(p) => setStep(Math.min(2, Math.floor(p * 3)))}>\n  <FeatureStep index={step} />\n</ScrollStage>\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Semantics | Renders a `<section>` by default; give it an `aria-label` or a heading inside |\n| Content order | The pinned content stays in DOM order, so keyboard and screen-reader order are unchanged |\n| Motion | Under `prefers-reduced-motion: reduce` the scene is not pinned and renders in normal flow |\n\n## Reduced motion & server rendering\n\nThe server renders the pinned layout with `--dt-p` unset, so CSS written with a final-state fallback (`var(--dt-p, 1)`) shows the end of the scene; `children(progress)` gets `progress.get() === 1`. Under reduced motion, or with `pin={false}`, the root gets `data-dt-stage=\"static\"`, no height and no sticky box, and the variable is removed. The root carries `data-dt-stage=\"pinned\"` otherwise.\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. The trigger and the dropdown panel use the semantic `bg-surface` / `border-line` / `text-foreground` tokens (option hover `bg-line/50`, with `dark:` tints for the focused and selected rows), so they follow dark mode.\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",
@@ -7240,17 +8181,21 @@
     "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",
+    "SmoothScrollProvider": "# SmoothScrollProvider\n\nOpt-in smooth (inertial) page scrolling with [Lenis](https://github.com/darkroomengineering/lenis). Lenis is an optional peer dependency that this package never imports: install it and pass the class in. Without it, the page keeps native scrolling, and every motion component works the same either way. Lenis runs on the same frame loop as the other motion components. Read the provider's state with [useSmoothScroll](useSmoothScroll.md). Part of the `/motion` entry point ([overview](Motion.md)).\n\n## Install\n\nOnly if you want smooth scrolling:\n\n```bash\nnpm install lenis\n```\n\n## Import\n\n```jsx\nimport Lenis from 'lenis';\nimport { SmoothScrollProvider } from '@dreamtree-org/twreact-ui/motion';\n```\n\nNever import it from the root `@dreamtree-org/twreact-ui` — the motion components are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `lenis` | `new (options?) => LenisLike` | — | The Lenis class (`import Lenis from 'lenis'`). Without it, native scrolling is used |\n| `options` | `Record<string, unknown>` | — | Options for `new Lenis({ autoRaf: false, ...options })`, read once per instance (change `enabled` or `lenis` to rebuild) |\n| `enabled` | `boolean` | `true` | Turn smooth scrolling off without removing the provider |\n| `children` | `ReactNode` | — | The page |\n\nIt renders no DOM element of its own, so it takes no `className` or `ref`.\n\n## Examples\n\n```jsx\nimport Lenis from 'lenis';\n\nexport default function Landing() {\n  return (\n    <SmoothScrollProvider lenis={Lenis} options={{ lerp: 0.1 }}>\n      <DeviceMorphHero media={media} content={<HeroCopy />} />\n      <StackedCards items={pillars} />\n    </SmoothScrollProvider>\n  );\n}\n```\n\n### Scroll to a section\n\n```jsx\nfunction NavLink({ href, children }) {\n  const { scrollTo } = useSmoothScroll();\n  return <a href={href} onClick={(e) => { e.preventDefault(); scrollTo(href, { offset: -80 }); }}>{children}</a>;\n}\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Opt-in | Off unless you pass `lenis`; native scrolling (keyboard, find-in-page, anchors) is the default |\n| Reduced motion | Never starts Lenis when the user prefers reduced motion |\n| Anchors | Use `scrollTo` from `useSmoothScroll` for in-page links so they go through Lenis when it is active |\n\n## Reduced motion & server rendering\n\nOn the server and during hydration the context is native scrolling (`lenis: null`); Lenis starts after mount. Under `prefers-reduced-motion: reduce`, or with `enabled={false}`, it is never created (and is destroyed if the setting changes). On unmount the instance is destroyed.\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",
+    "StackedCards": "# StackedCards\n\nCards that stick one over another as the page scrolls. Each card is `position: sticky` at `stickyTop`; as the next card slides over, the one underneath shrinks (`scaleBack`) and dims (`dimBack`). An alternating tilt makes the stack look hand-placed. Part of the `/motion` entry point ([overview](Motion.md)).\n\n## Install\n\nNothing extra — the `/motion` entry point has no required peer dependency.\n\n## Import\n\n```jsx\nimport { StackedCards } from '@dreamtree-org/twreact-ui/motion';\n```\n\nNever import it from the root `@dreamtree-org/twreact-ui` — the motion components are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `items` | `StackedCardItem[]` | `[]` | **Required.** `{ id?, kicker?, title, body?, bullets?: ReactNode[], metric?: { value, label }, cta?: ReactNode, media?: { src, alt } \\| ReactNode }` per card |\n| `stickyTop` | `number` | `80` | px from the viewport top where cards stick (token `scroll.stickyTop`; clears a floating nav) |\n| `tilt` | `number` | `1` | Alternating tilt in degrees: card 1 −1×tilt, card 2 +1.5×, card 3 −2×, card 4 +1×, card 5 −1.5×, card 6 +2×, then repeating. `0` disables. Off below `md` and under reduced motion |\n| `scaleBack` | `number` | `0.94` | Scale of a card fully covered by the next one. `1` disables |\n| `dimBack` | `number` | `0.15` | How much a covered card darkens (0–1, via `brightness`). `0` disables |\n| `mediaSide` | `\"alternate\"` \\| `\"right\"` | `\"alternate\"` | Media on the right of every card, or alternating sides (from `md` up) |\n| `renderItem` | `(item: StackedCardItem, index: number) => ReactNode` | — | Replaces the default card body (the sticky `<article>` shell stays) |\n| `className` | `string` | — | Extra classes for the root `<ol>` (merged with `cn`) |\n| `ref` | `Ref<HTMLOListElement>` | — | Forwarded to the root `<ol>` |\n| ...rest | `HTMLAttributes<HTMLOListElement>` | — | Forwarded to the root `<ol>` |\n\n## Examples\n\n```jsx\n<StackedCards\n  stickyTop={96}\n  items={[\n    {\n      kicker: '01 · Product',\n      title: 'Product strategy',\n      body: 'We turn a rough idea into a plan you can build, price and sell.',\n      bullets: ['Discovery workshops', 'User research', 'Roadmaps'],\n      metric: { value: '40+', label: 'Products planned' },\n      cta: <Button size=\"sm\">Get a quote</Button>,\n      media: { src: '/img/plan.jpg', alt: 'A planning workshop' },\n    },\n    { kicker: '02 · Design', title: 'Design systems', media: { src: '/img/design.jpg', alt: 'Sketches' } },\n  ]}\n/>\n```\n\n### Custom card body\n\n```jsx\n<StackedCards items={steps} tilt={0} renderItem={(step, i) => <Step number={i + 1} {...step} />} />\n```\n\nLeave space after the list (for example `pb-[50vh]` on the parent) so the last card can scroll fully into place.\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Semantics | An ordered list (`<ol>`); each card is an `<article>` with an `<h3>` title |\n| Bullets | A `<ul>`; the dots are decorative (`aria-hidden`) |\n| Images | `media` as `{ src, alt }` renders a lazy `<img>` with your `alt` |\n| Motion | Scale, dim and tilt are under `motion-safe:`, so they never apply with `prefers-reduced-motion: reduce` |\n\n## Reduced motion & server rendering\n\nThe server renders every card, sticky, at full size and brightness (the `--dt-scale` / `--dt-dim` variables are unset, so they fall back to 1). The tilt shows from `md` up. Under `prefers-reduced-motion: reduce` the cards still stack (sticky is not motion) but the tilt, scale and dim are off and no scroll work runs.\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| `tinted` | `boolean` | `false` | Draws the whole card in `tone`: `<tone>-50` fill, `<tone>-200` border, `<tone>-800` text (deep translucent tints in dark mode) |\n| `children` | `ReactNode` | — | Footer under the value with the card's spacing: a [`ProgressBar`](ProgressBar.md), a line of text or a `Button variant=\"link\"` |\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<StatCard label=\"Occupancy\" value=\"92%\">\n  <ProgressBar value={44} max={48} size=\"sm\" ariaLabel=\"Beds filled\" />\n  <p className=\"text-muted\">44 of 48 beds filled · 4 free</p>\n</StatCard>\n\n<StatCard label=\"Overdue rent\" value=\"₹18,400\" tone=\"error\" tinted>\n  <Button variant=\"link\" tone=\"error\" rightIcon=\"→\">See who owes</Button>\n</StatCard>\n```\n\n[← Component overview](README.md)\n",
+    "StatStrip": "# StatStrip\n\nA row of headline numbers that count up on view, as bordered cards or as one band with dividers. Each number is a [CountUp](CountUp.md). Part of the `/motion` entry point ([overview](Motion.md)).\n\n## Install\n\nNothing extra — the `/motion` entry point has no required peer dependency.\n\n## Import\n\n```jsx\nimport { StatStrip } from '@dreamtree-org/twreact-ui/motion';\n```\n\nNever import it from the root `@dreamtree-org/twreact-ui` — the motion components are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `items` | `{ value: number; label: ReactNode; prefix?: ReactNode; suffix?: ReactNode; decimals?: number; format?: (value: number) => string }[]` | `[]` | **Required.** One entry per stat |\n| `variant` | `\"cards\"` \\| `\"band\"` | `\"cards\"` | Bordered tiles, or one bordered row with dividers |\n| `duration` | `number` | `1600` | Passed to every CountUp |\n| `locale` | `string` | `\"en-IN\"` | Passed to every CountUp |\n| `className` | `string` | — | Extra classes for the root `<dl>` (merged with `cn`) |\n| `ref` | `Ref<HTMLDListElement>` | — | Forwarded to the root `<dl>` |\n| ...rest | `HTMLAttributes<HTMLDListElement>` | — | Forwarded to the root `<dl>` |\n\nColumns: 2 on phones, then one per item from `sm` up (4 items: 2 at `sm`, 4 at `lg`).\n\n## Examples\n\n```jsx\n<StatStrip\n  items={[\n    { value: 120, suffix: '+', label: 'Projects shipped' },\n    { value: 14, label: 'Years building' },\n    { value: 2500000, prefix: '₹', label: 'Saved for clients' },\n  ]}\n/>\n\n<StatStrip variant=\"band\" items={[{ value: 98.5, suffix: '%', label: 'Uptime' }, { value: 6, label: 'Products' }]} />\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Semantics | A description list: each label is a `<dt>`, each number its `<dd>`. The number is shown above the label visually (`flex-col-reverse`) while the DOM keeps label then value |\n| Numbers | Read once, final value only (see CountUp) |\n\n## Reduced motion & server rendering\n\nThe server renders the real numbers. Under `prefers-reduced-motion: reduce` the numbers do not count. See [CountUp](CountUp.md).\n\n[← Component overview](README.md)\n",
     "StatusPill": "# StatusPill\n\nPage-level block: one status badge for every domain state. Map each state to a tone and a human label once; unknown states are humanized (`in_review` → \"In review\"), never shown raw. Extracted from billpro `components/StatusPill.jsx`.\n\n## Import\n\n```jsx\nimport { StatusPill } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `status` | `string` | — | Domain state to look up in `map` |\n| `map` | `Record<string, { label; tone; icon? }>` | — | State → label and tone (`neutral`, `info`, `success`, `warning`, `danger`, `muted`). `info` renders with the `info` palette (Badge `variant=\"info\"`), not the brand accent |\n| `tone` | `string` | `\"neutral\"` | Tone when not using `map`; also accepts semantic tones |\n| `icon` | `ReactNode` | — | Small leading icon (rendered in Badge's decorative `icon` slot) |\n| `children` | `ReactNode` | — | Label override |\n| `className` | `string` | — | Extra CSS classes |\n\nColours come from `Badge`, so every tone has dark-mode tones too.\n\n## Example\n\n```jsx\nconst OBLIGATION_STATUS = {\n  overdue: { label: 'Overdue', tone: 'danger' },\n  docs_missing: { label: 'Missing documents', tone: 'warning' },\n  ready: { label: 'Ready for review', tone: 'info' },\n  filed: { label: 'Filed', tone: 'success' },\n};\n\n<StatusPill status=\"docs_missing\" map={OBLIGATION_STATUS} />\n<StatusPill tone=\"success\">Filed</StatusPill>\n```\n\n[← Component overview](README.md)\n",
     "Stepper": "# Stepper\n\nHorizontal or vertical step indicator. Each step has circle (with check for completed), optional line, and label. Optional `onStepClick` for clickable steps.\n\n## Import\n\n```jsx\nimport { Stepper } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `steps` | `Array` | `[]` | Each step: `{ id?, title?, label?, description? }`. `title` is the step's text; `label` is accepted as an alias (when both are set, `title` wins). |\n| `currentStep` | `number` | `0` | Zero-based index of current step. |\n| `orientation` | `\"horizontal\"` \\| `\"vertical\"` \\| `\"auto\"` | `\"horizontal\"` | Layout. `\"auto\"` stacks vertically below the `sm` breakpoint (640 px) and lays out horizontally from `sm` up, using CSS only. |\n| `variant` | `\"default\"` \\| `\"dots\"` | `\"default\"` | `\"dots\"` renders compact progress dots: one labelled dot per step, the current step as a wider pill, and no titles or descriptions. Clicks work as with `onStepClick`. Unknown values render the default stepper. |\n| `onStepClick` | `(step, stepIndex) => void` | — | Called when a step is clicked (e.g. for completed/current). |\n| `className` | `string` | — | Nav wrapper CSS classes. |\n| ...rest | — | — | Passed to `<nav>`. The nav defaults to `aria-label=\"Progress\"`; a caller's `aria-label` replaces it. |\n\n## Step status\n\n- **completed**: `stepIndex < currentStep` (check icon, primary color).\n- **current**: `stepIndex === currentStep`.\n- **upcoming**: `stepIndex > currentStep` (gray circle; title and description use the `text-muted` role, 7.5:1 on white).\n\nConnectors flex to fill the space between circles (horizontal) or between steps (vertical), so any number of steps fits its container without overflowing. The connector after a completed step is primary. Step buttons show a `focus-visible` ring, have dark-mode colours, and grow to a 44 px touch target on coarse pointers when they are clickable.\n\nEach step button (and each dot) is named `Step <n>: <title or label>`, with ` (completed)` for completed steps (their circle shows only a check icon).\n\n## Example\n\n```jsx\n<Stepper\n  steps={[\n    { id: '1', label: 'Details' },\n    { id: '2', label: 'Payment' },\n    { id: '3', label: 'Confirm' },\n  ]}\n  currentStep={1}\n  orientation=\"horizontal\"\n  onStepClick={(step, idx) => setStep(idx)}\n/>\n```\n\n[← Component overview](README.md)\n",
     "SwipeableListItem": "# SwipeableListItem\n\nA list row with swipe actions, the iOS Mail / Gmail pattern. Swipe right to reveal the **leading** actions, left to reveal the **trailing** ones; release to snap open or closed, or swipe all the way to commit the first action on that side. Past the actions the row rubber-bands. Every action is also reachable without a gesture through a **More actions** button that opens them as a menu (an action sheet on phones).\n\n## Import\n\n```jsx\nimport { SwipeableListItem } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `leadingActions` | `SwipeAction[]` | `[]` | Revealed by swiping right. The first one sits at the left edge and is the full-swipe action |\n| `trailingActions` | `SwipeAction[]` | `[]` | Revealed by swiping left. The first one sits at the right edge and is the full-swipe action |\n| `fullSwipe` | `boolean` \\| `{ leading?, trailing? }` | `true` | A swipe past `fullSwipeThreshold` commits the first action of that side. Pass an object to allow it on one side only |\n| `fullSwipeThreshold` | `number` | `0.6` | Fraction of the row width a full swipe must travel (and at least 24px past the revealed actions) |\n| `actionWidth` | `number` | `80` | Width in px of each revealed action |\n| `open` | `'leading'` \\| `'trailing'` \\| `null` | — | Controlled open side |\n| `defaultOpen` | `'leading'` \\| `'trailing'` \\| `null` | `null` | Uncontrolled initial open side |\n| `onOpenChange` | `(side) => void` | — | Called with `'leading'`, `'trailing'` or `null` when the row opens or closes |\n| `disabled` | `boolean` | `false` | Turns off the gesture and the More actions button |\n| `moreActions` | `'focus'` \\| `'always'` \\| `false` | `'focus'` | The gesture-free button. `focus`: shown on keyboard focus and mouse hover. `always`: always visible. `false`: removed (only when you provide another way to reach the actions) |\n| `moreActionsLabel` | `string` | `\"More actions\"` | Accessible name of the button and its menu |\n| `menuPresentation` | `'auto'` \\| `'popover'` \\| `'sheet'` | `'auto'` | How the More actions menu opens. `auto` uses an action sheet on small touch screens |\n| `as` | `ElementType` | `\"div\"` | Root element, e.g. `\"li\"` inside a `<ul>` |\n| `contentClassName` | `string` | — | Classes for the sliding content layer (default background `bg-surface`) |\n| `className` | `string` | — | Root classes (merged with `cn`) |\n| `children` | `ReactNode` | — | The row content |\n| `...rest` | `HTMLAttributes` | — | Forwarded to the root; `ref` points at the root |\n\n### `SwipeAction`\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `key` | `string` | Unique key |\n| `label` | `ReactNode` | Visible text (also the menu item text) |\n| `icon` | `ReactNode` \\| `Component` | Shown above the label (`<Trash2 />` or `Trash2`) |\n| `tone` | `string` | `default`, `primary`, `secondary`, `success`, `warning`, `info`, `error` or `destructive`. Sets the action's background; `error` / `destructive` also mark it destructive in the menu |\n| `disabled` | `boolean` | Not selectable |\n| `onSelect` | `({ action, source }) => void` | Runs the action. `source` is `'button'` (a revealed action was tapped), `'full-swipe'` or `'menu'`. The row closes afterwards |\n\n## Behaviour\n\n- **Pointer events**, with `touch-action: pan-y` on the content: a swipe only starts once horizontal movement dominates, so vertical scrolling is never blocked.\n- **Snap**: on release the row opens when dragged past half of its actions (or flicked toward open) and closes otherwise.\n- **Full swipe**: while past the threshold the first action grows to fill the revealed area; releasing there commits it.\n- **Closing**: a tap outside the row, a tap on the open row (which does not activate the row), Escape, or selecting an action.\n- **No ghost clicks**: the click that ends a swipe is swallowed.\n- **Reduced motion**: snapping animates with the motion tokens and is instant under `prefers-reduced-motion`.\n\n## Accessibility\n\n- Actions that are not revealed are `aria-hidden` and out of the tab order; revealed actions are regular buttons.\n- The **More actions** button (`aria-haspopup=\"menu\"`) is in the tab order even when visually hidden (`moreActions=\"focus\"`) and appears on focus. It opens every action as a `role=\"menu\"` (arrow keys, Home/End, typeahead, Escape returns focus) or, on phones, as an action sheet.\n- Escape closes an open row.\n\n## Examples\n\n### Inbox row\n\n```jsx\nimport { Archive, Trash2, Flag, MailOpen } from 'lucide-react';\n\n<ul className=\"divide-y divide-line\">\n  {messages.map((m) => (\n    <SwipeableListItem\n      key={m.id}\n      as=\"li\"\n      leadingActions={[{ key: 'read', label: 'Read', icon: MailOpen, tone: 'primary', onSelect: () => markRead(m) }]}\n      trailingActions={[\n        { key: 'delete', label: 'Delete', icon: Trash2, tone: 'destructive', onSelect: () => remove(m) },\n        { key: 'flag', label: 'Flag', icon: Flag, tone: 'warning', onSelect: () => flag(m) },\n        { key: 'archive', label: 'Archive', icon: Archive, tone: 'success', onSelect: () => archive(m) },\n      ]}\n    >\n      <div className=\"px-4 py-3\">{m.subject}</div>\n    </SwipeableListItem>\n  ))}\n</ul>\n```\n\n### One row open at a time\n\n```jsx\nconst [open, setOpen] = useState(null); // { id, side }\n\n<SwipeableListItem\n  open={open?.id === m.id ? open.side : null}\n  onOpenChange={(side) => setOpen(side ? { id: m.id, side } : null)}\n  trailingActions={actions}\n>\n  …\n</SwipeableListItem>\n```\n\n### In a Table\n\n`Table` builds its mobile cards on this component through the `swipeActions` prop; see [Table](Table.md#mobile-cards-filters-and-swipe-actions).\n\n[← Component overview](README.md)\n",
     "Switch": "# Switch\n\nToggle switch (on/off). Controlled or uncontrolled. Without an `id` prop, the id comes from `React.useId()`, so it is stable across server rendering and hydration.\n\n## Import\n\n```jsx\nimport { Switch } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `checked` | `boolean` | — | Controlled checked |\n| `defaultChecked` | `boolean` | `false` | Uncontrolled default |\n| `onChange` | `(checked: boolean) => void` | — | Receives the new boolean state (not a DOM event) |\n| `disabled` | `boolean` | `false` | Disable |\n| `size` | `string` | `\"md\"` | `sm`, `md`, `lg`. `md` takes the iOS 51×31 size on coarse pointers (touch screens). |\n| `color` | `string` | `\"primary\"` | Token preset (`primary`, `secondary`, `success`, `error`, `warning`; aliases `green`, `danger`, `red`) or a custom CSS colour string. The raw-palette presets `blue`, `indigo`, `purple` were **removed in 2.0.0** ([migration](MIGRATION-2.0.md#checkbox-and-switch-raw-colour-presets)). |\n| `name` | `string` | — | Form name |\n| `topLabel` | `string` | — | Label above |\n| `bottomLabel` | `string` | — | Label below |\n| `leftLabel` | `string` | — | Label left |\n| `rightLabel` | `string` | — | Label right |\n| `haptics` | `boolean` | `false` | Opt-in: a `selection` vibration (10ms) on every toggle (tap, drag or keyboard). No-op without `navigator.vibrate` (iOS Safari) and under reduced motion. See [useHaptics](useHaptics.md) |\n\n## Behavior\n\n- **Tap or drag:** a tap/click toggles; dragging the knob left or right (pointer events) sets off / on, iOS style. A drag toward the current state is a no-op, and a cancelled drag reverts. `Space` / `Enter` toggle from the keyboard.\n- The off track is a visible grey in light and dark mode; colour presets (`primary`, `success`, …) paint the on track.\n- Transitions are `transition-colors` / `transition-transform` and turn off under `prefers-reduced-motion`. Focus shows a `focus-visible` ring.\n\n## Example\n\n```jsx\n<Switch checked={enabled} onChange={checked => setEnabled(checked)} />\n<Switch defaultChecked rightLabel=\"Enable notifications\" />\n```\n\n[← Component overview](README.md)\n",
-    "Table": "# Table\n\nData table with sorting, filtering, pagination, row selection, expandable details, and responsive mobile card view. The toolbar **Reload** button is tinted `bg-primary-100 text-primary-700` with `dark:bg-primary-900/40 dark:text-primary-300` in dark mode.\n\n## Import\n\n```jsx\nimport { Table } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `data` | `Array` | `[]` | Row data (array of objects) |\n| `columns` | `Array` | `[]` | Column definitions `[{ key, label, sortable?, isVisible?, editable?, type?, options?, required?, validate?, onRender?, render?, searchable?, wrap?, hideOnMobile? }]`. `searchable: false` excludes the column from the global search, `wrap: true` lets its cells wrap, `hideOnMobile: true` drops it from the mobile card view. `label` may be text or a node (an aligned or icon header); filter placeholders and validation messages use the label when it is text and the column `key` otherwise. |\n| `interactive` | `boolean` | `false` | Enable interactive mode with inline cell editing (double-click cell), keyboard shortcuts (`Tab`/`Shift+Tab` cell navigation, `Enter` to save modified changes, `Arrows`, `Escape`), primary Save button, outline Clear Changes button, constraint validation before save, and instant new row addition. |\n| `onSave` | `function` | — | Save callback in interactive mode `({ updatedRows, newRows, allData, tableData }) => Promise<allData | { data: allData } | void> | void`. Returning a dataset array or `{ data }`/`{ allData }` updates internal state with returned records. |\n| `onEdit` | `function` | — | Live edit callback fired when a cell value changes or row edit action is clicked `({ rowKey, colKey, newValue, row, action, isNew }) => void` |\n| `sortable` | `boolean` | `true` | Enable column sort. Each sortable header is a real `<button>` inside its `<th>` (Tab to it, Enter / Space to sort) and the `<th>` carries `aria-sort` (`none`, `ascending` or `descending`). |\n| `filterable` | `boolean` | `false` | Show a filter input per column. Client-side, each non-empty filter keeps rows whose value in that column contains the text (case-insensitive); filters combine with each other and with the global search. In `serverSide` mode nothing is filtered locally. |\n| `selectable` | `boolean` | `false` | Row selection checkboxes |\n| `pagination` | `boolean` | `false` | Enable pagination |\n| `pageSize` | `number` | `25` | Rows per page |\n| `onSort` | `function` | — | Sort callback |\n| `onFilter` | `function` | — | Filter callback |\n| `onFetch` | `function` | — | Server-side fetch (setData, setLoading, filters, page, limit, sort) |\n| `onFilterChange` | `function` | — | Filter change callback |\n| `onSelectionChange` | `function` | — | Selected rows callback |\n| `onRowClick` | `function` | — | Row click callback |\n| `hasDetails` | `boolean` or `(row, index) => boolean` | `false` | Expandable row details. Pass a predicate to give only matching rows an expand toggle; non-matching rows render an empty placeholder cell so columns stay aligned. |\n| `DetailsComponent` | `Component` | — | Component for expanded content |\n| `withAction` | `boolean` | `true` | Show actions column |\n| `onAction` | `function` | — | Action menu callback |\n| `actions` | `Array` or `(row, index) => Array` | — | Row actions. Entries are `{ name, label, icon, render?, onClick?, hidden?, disabled?, inline?, tone? }`; `tone: 'destructive'` (or `destructive: true`) styles a menu action in the error tone; `label`, `icon`, `hidden` and `disabled` each accept a value or `(row, index) => value`. `inline: true` renders the action as an icon button in the actions cell instead of inside the kebab menu; the kebab is hidden when no menu actions remain. Entries are merged onto the built-in Edit/Delete/View set by `name` (so `{ name: 'edit', onClick }` keeps the default label and icon, and `{ name: 'delete', hidden: true }` removes a default); unmatched entries are appended. Set `replaceDefaultActions` to opt out. |\n| `actionMenuPresentation` | `string` | `\"auto\"` | One of `auto`, `popover`, `sheet`. How the row kebab menu opens. `popover`: a floating menu portaled to `document.body` that flips/shifts to stay on screen (never clipped by the table's overflow). `sheet`: an iOS-style action sheet from the bottom with a separate Cancel button. `auto` uses the sheet on small touch screens (`(pointer: coarse) and (max-width: 639px)`) and the popover elsewhere. |\n| `replaceDefaultActions` | `boolean` | `false` | Replace the built-in Edit/Delete/View actions entirely instead of patching them by `name`. |\n| `showSerial` | `boolean` | `true` | Show row number column |\n| `cellClass` | `string` \\| `function` | — | Cell className |\n| `rowClass` | `string` \\| `function` | — | Row className |\n| `globalSearch` | `boolean` | `false` | Global search box. Works with or without `filterable`. Client-side, keeps rows where any value outside a `searchable: false` column contains the term (case-insensitive). In `serverSide` mode it only reports `filters.global`. |\n| `limitOptions` | `number[]` | `[10,25,50,100]` | Page size options |\n| `showLimitSelector` | `boolean` | `true` | Show page size selector |\n| `showReloadButton` | `boolean` | `true` | Show reload button. It is named \"Reload\" (`aria-label`) because its text label is hidden below the `sm` breakpoint |\n| `onReload` | `function` | — | Reload click handler |\n| `stripedRows` | `boolean` | `true` | Striped row background |\n| `theme` | `object` | see below | `stripedColors`, `rowHover`, `accentColor`, `menuBg`, `menuItemHover`. Defaults are dark-mode aware: `{ stripedColors: ['bg-surface', 'bg-background'], rowHover: 'bg-background', accentColor: 'bg-background', menuBg: 'bg-surface', menuItemHover: 'hover:bg-background' }`. A `stripedColors` entry may be a Tailwind `bg-*` class (applied as a class) or a CSS colour such as `'#f7fafc'` (applied as an inline background). `rowHover` is a `bg-*` token or a full hover class string. In the pagination controls, the shipped tokens (`bg-background`, `bg-surface`, `bg-gray-50`, `bg-gray-100`, `bg-primary-50`, `bg-primary-100`) map to static `hover:` literals; for any other colour pass the full class (e.g. `'hover:bg-gray-200'`) so your Tailwind build generates it — a bare unknown token is still prefixed with `hover:` at runtime for backward compatibility, but Tailwind can purge such a class. Pagination buttons grow to a 44×44 px touch target on coarse pointers. |\n| `serverSide` | `boolean` | `false` | Server-side pagination/sort/filter |\n| `totalRecords` | `number` | `0` | Total count (serverSide). Drives the page count and the \"start - end of total\" counter; when omitted the counter falls back to the rows received. |\n| `pageNumber` | `number` | — | Controlled page. Client-side, a page past the last one is clamped to the last page once rows exist. |\n| `onPageChange` | `(page: number) => void` | — | Called with the new page number when the user changes page, and when the table clamps a page that no longer exists (client-side). Not called for the reset to page 1 on a filter or page-size change. Consumed by the table — it is **not** forwarded onto the `<table>`. |\n| `responsiveBreakpoint` | `number` | `768` | px breakpoint for mobile cards: card mode while the viewport is narrower than this. Read with an SSR-safe media query (`not all and (min-width: <n>px)`), so client renders pick the right layout on the first render and follow resizes live. |\n| `defaultMobileView` | `boolean` | `false` | Layout used on the server and while hydrating, before the media query can be read. Set `true` on phone-first pages so server-rendered HTML starts as cards. |\n| `mobileFiltersPresentation` | `string` | `\"auto\"` | Card-mode filters (with `filterable` / `globalSearch`). `sheet`: a \"Filters\" button (with an active-filter count) opening a bottom `Sheet`; edits are a draft until **Apply**, **Clear** empties the draft. `inline`: the collapsible inline panel (the previous behaviour, live filtering). `auto` uses the sheet on small touch screens (`(pointer: coarse) and (max-width: 639px)`) and the inline panel elsewhere. |\n| `swipeActions` | `(row, index) => { leading?, trailing? } \\| null` | — | Swipe actions on the mobile cards, built on [`SwipeableListItem`](SwipeableListItem.md). Each side is an array of `{ key, label, icon?, tone?, disabled?, onSelect }`; swipe right for `leading`, left for `trailing`, a full swipe commits the first action of that side. Only one card is open at a time. Every action is also reachable without a gesture through the card's \"Swipe actions\" button. Return `null` (or empty arrays) for rows without swipe actions. |\n| `stickyHeader` | `boolean` \\| `string` \\| `number` | `false` | Keep the desktop header visible while the body scrolls. `true` sticks within the table's own scroll container; a CSS length (`\"24rem\"`) or a number (px) also caps that container's height so the rows scroll under the header. |\n| `paginationPosition` | `'top'` \\| `'bottom'` \\| `'both'` | `'both'` | Which pager renders when `pagination` is on. `'both'` keeps the compact pager in the toolbar and the \"Page N of M\" footer. `'bottom'` drops the toolbar pager but keeps the rest of the toolbar (reload, page size, result count). `'top'` keeps only the toolbar pager (so with `showToolbar={false}` there is no pager). Unknown values fall back to `'both'`. |\n| `showToolbar` | `boolean` | `true` | Show the toolbar above the table (reload, page size, result count, pager header) and the column picker. `false` hides all of it; the pager footer stays, and in `interactive` mode the add-row / Save / Clear controls still render. `globalSearch` is its own opt-in and is unaffected. |\n| `showColumnPicker` | `boolean` | `true` | Show the column-picker button in the header (accessible name \"Choose columns\", with `aria-expanded`). `false` also removes its (otherwise empty) column from every row. |\n| `wrapCells` | `boolean` | `false` | Let cell text wrap instead of staying on one line. A column's own `wrap` overrides it. |\n| `mobileMaxFields` | `number` | — | Cap the fields shown on each mobile card. Applied in column order, after `hideOnMobile` columns are removed. |\n\nOnly DOM-valid attributes in `...rest` (e.g. `id`, `aria-*`, `data-*`) are\nforwarded to the root `<table>`; the table's own control props (`onPageChange`,\n`serverSide`, `pagination`, the `on*` callbacks, …) are consumed and never leak\nto the DOM as unknown attributes.\n\n## Examples\n\n### Basic table\n\n```jsx\nconst columns = [\n  { key: 'name', label: 'Name' },\n  { key: 'email', label: 'Email' },\n];\nconst data = [\n  { id: 1, name: 'Alice', email: 'alice@example.com' },\n  { id: 2, name: 'Bob', email: 'bob@example.com' },\n];\n<Table data={data} columns={columns} />\n```\n\n### With pagination and selection\n\n```jsx\n<Table\n  data={data}\n  columns={columns}\n  pagination\n  pageSize={10}\n  selectable\n  onSelectionChange={(selected) => console.log(selected)}\n/>\n```\n\n### Server-side data\n\n```jsx\n<Table\n  data={data}\n  columns={columns}\n  serverSide\n  pagination\n  totalRecords={total}\n  onFetch={async ({ setData, setLoading, page, limit, sort }) => {\n    setLoading(true);\n    const res = await fetch(`/api/users?page=${page}&limit=${limit}`);\n    const json = await res.json();\n    setData(json.rows);\n    setLoading(false);\n  }}\n/>\n```\n\n### Filtering and page clamping (client-side)\n\nWithout `serverSide`, the table filters the rows itself:\n\n- **Global search** (`globalSearch`) applies on Enter or the search button,\n  with or without `filterable`. Columns with `searchable: false` are skipped.\n- **Column filters** (`filterable`) apply as you type. Each one matches only its\n  own column's raw value (not a `render` output).\n- All matches are case-insensitive \"contains\" tests, and every active filter\n  must match (AND).\n- `onFilter` / `onFilterChange` still receive the whole `filters` object\n  (`{ global?, [columnKey]: text }`) on every change.\n\nWhen the rows shrink (filtering, deleted rows, a new `data` prop) and the\ncurrent page no longer exists, the table shows the last page that does and\ncalls `onPageChange` with it. A parent that drives `pageNumber` can simply\nstore that value, and no `clampPage` helper is needed. The clamp waits while\nthere are no rows, so a page restored from the URL survives until the data\narrives.\n\nWith `serverSide`, none of this runs locally: filters go to `onFetch` /\n`onFilter` / `onFilterChange`, the rows shown are exactly the rows you pass,\nand keeping `pageNumber` within `totalRecords` is up to you.\n\n### Compact, read-only table\n\nHide the chrome for a dashboard card, keep id columns out of the search, let\nlong text wrap, and keep phone cards short.\n\n```jsx\nconst columns = [\n  { key: 'id', label: 'ID', searchable: false, hideOnMobile: true },\n  { key: 'client', label: 'Client' },\n  { key: 'status', label: 'Status' },\n  { key: 'notes', label: 'Notes', wrap: true },\n  { key: 'owner', label: 'Owner' },\n];\n\n<Table\n  data={rows}\n  columns={columns}\n  showToolbar={false}\n  showSerial={false}\n  withAction={false}\n  mobileMaxFields={3}\n/>\n```\n\nOn a phone each card shows Client, Status and Notes. With no serial, selection,\nexpand toggle or actions, the card has no header strip either.\n\n`showToolbar={false}` does not change pagination: with `pagination` on, the pager\nfooter still renders. Hide only the picker with `showColumnPicker={false}`.\n\n### One pager instead of two\n\nWith `pagination` and the toolbar both on, the table shows a compact pager in the\ntoolbar and another under the rows. Keep the toolbar (reload, page size, result\ncount) and drop the top pager with `paginationPosition=\"bottom\"`:\n\n```jsx\n<Table data={rows} columns={columns} pagination paginationPosition=\"bottom\" />\n```\n\n`paginationPosition=\"top\"` does the opposite and keeps only the toolbar pager.\n\n### Conditional row details\n\n`hasDetails` accepts a predicate so only rows that actually have something to\nshow get an expand toggle. Rows that don't qualify still render the (empty)\ntoggle cell, so the columns stay aligned.\n\n```jsx\nconst ErrorDetails = ({ row }) => <pre>{row.stackTrace}</pre>;\n\n<Table\n  data={jobs}\n  columns={columns}\n  hasDetails={(row) => row.status === 'failed'}\n  DetailsComponent={ErrorDetails}\n/>\n```\n\n### Mobile cards, filters and swipe actions\n\nBelow `responsiveBreakpoint` rows render as cards. Card controls (expand\ntoggle, selection checkbox, inline actions, kebab) have 44×44 px hit areas.\nWith `filterable` on a phone, the filters open in a bottom sheet with an\nApply / Clear footer; pass `mobileFiltersPresentation=\"inline\"` to keep the\ninline panel.\n\n```jsx\n<Table\n  data={messages}\n  columns={columns}\n  filterable\n  defaultMobileView            // server-rendered HTML starts as cards\n  swipeActions={(row) => ({\n    leading: [{ key: 'read', label: 'Read', icon: MailOpen, tone: 'primary', onSelect: () => markRead(row) }],\n    trailing: [\n      { key: 'delete', label: 'Delete', icon: Trash2, tone: 'destructive', onSelect: () => remove(row) },\n      { key: 'flag', label: 'Flag', icon: Flag, tone: 'warning', onSelect: () => flag(row) },\n    ],\n  })}\n/>\n```\n\n### Sticky header\n\n```jsx\n<Table data={rows} columns={columns} stickyHeader=\"28rem\" />\n```\n\n### Row action menu\n\nThe kebab button (`aria-haspopup=\"menu\"`) opens the row's menu actions. On\ndesktop it is a `role=\"menu\"` popover: focus moves to the first action,\nArrowUp/ArrowDown (wrapping), Home/End and first-letter typeahead move between\nactions, Escape or Tab closes it and returns focus to the kebab, and a press\noutside or a page scroll closes it (pressing the kebab again closes it too). On phones (`actionMenuPresentation=\"auto\"`,\nthe default) the same actions open as an action sheet: 48px rows in a rounded\ncard, destructive actions in red, and a Cancel button below. Pass\n`actionMenuPresentation=\"popover\"` to keep the desktop menu everywhere.\n\n```jsx\n<Table\n  data={users}\n  columns={columns}\n  actions={[{ name: 'delete', tone: 'destructive' }]}\n  actionMenuPresentation=\"auto\"\n/>\n```\n\n### Conditional and inline actions\n\n`hidden` and `disabled` accept a `(row, index)` predicate, `label` and `icon`\naccept a `(row, index)` producer, and `inline: true` promotes an action out of\nthe kebab menu into the row itself. When no menu actions remain for a row, the\nkebab button is not rendered at all.\n\n```jsx\n<Table\n  data={jobs}\n  columns={columns}\n  replaceDefaultActions\n  actions={[\n    { name: 'view', label: 'View', icon: <Eye size={16} />, inline: true },\n    { name: 'edit', label: 'Edit', icon: <Edit size={16} />,\n      disabled: (row) => row.locked },\n    { name: 'retry', label: (row) => `Retry (${row.tries})`,\n      hidden: (row) => row.status !== 'failed' },\n  ]}\n  onAction={({ action, row }) => handle(action.name, row)}\n/>\n```\n\nFor a large table, wrap a function-valued `actions` in `useCallback` — a fresh\narrow on every render defeats the per-row memoization.\n\n```jsx\nconst actions = useCallback(\n  (row) => (row.role === 'admin' ? adminActions : userActions),\n  []\n);\n```\n\nNote that because `icon` may be a `(row, index) => node` producer, passing a\nbare component reference (`icon: Edit`) calls it rather than rendering it. Pass\nan element instead: `icon: <Edit size={16} />`.\n\n### Patching the default actions\n\nEntries you supply are merged onto the built-in Edit/Delete/View set by `name`,\nso you can swap one handler without restating the rest. Unmatched names are\nappended after the defaults, and `hidden: true` removes a default outright.\n\n```jsx\n<Table\n  data={users}\n  columns={columns}\n  actions={[\n    { name: 'edit', onClick: ({ row }) => edit(row) }, // keeps default label + icon\n    { name: 'delete', hidden: (row) => !row.canDelete },\n    { name: 'invite', label: 'Invite', icon: <Mail size={16} /> }, // appended\n  ]}\n/>\n```\n\nPass `replaceDefaultActions` to skip merging and use only your own set:\n\n```jsx\n<Table\n  data={users}\n  columns={columns}\n  replaceDefaultActions\n  actions={[{ name: 'approve', label: 'Approve' }]}\n/>\n```\n\n### Interactive Table Mode\n\nPass `interactive={true}` to enable inline cell editing (double-click a cell or press standard `'e'` key on a focused active cell to enter edit mode), instant record addition (at top or bottom), keyboard navigation (`Tab`/`Shift+Tab` to move between cells, `Escape` to exit edit mode, `Enter` to save modified changes), and constraint validation before saving.\n\n#### Interactive Props & Options\n\n- `interactive`: `boolean` (default: `false`) — Enables interactive mode.\n- `editKeyBinding`: `string | ((e) => boolean)` (default: `\"e\"`) — Standard key binding to enter cell edit mode on active focused cell.\n- `newRowPosition`: `\"bottom\" | \"top\"` (default: `\"bottom\"`) — Position where empty new rows are inserted (at the bottom or top of table dataset).\n- `addRowRef`: `React.MutableRefObject` — External ref populated with `(position?: \"top\" | \"bottom\") => void` to trigger adding a new row from external buttons.\n- `onInitAddRow`: `(addRowFn: (position?: \"top\" | \"bottom\") => void) => void` — Callback receiving the add-row function on component initialization.\n- `renderAddRowButton`: `({ addRow, newRowPosition }) => ReactNode` — Render prop for rendering a custom external add-row button in the table toolbar.\n\n#### Interactive Usage Example\n\n```jsx\nconst columns = [\n  { key: 'name', label: 'Name', type: 'text', required: true },\n  { key: 'role', label: 'Role', type: 'select', options: ['Admin', 'User'], required: true },\n  { key: 'notes', label: 'Notes', type: 'textarea' },\n];\n\nconst addRowRef = useRef();\n\nreturn (\n  <div>\n    <button onClick={() => addRowRef.current?.(\"top\")}>\n      Add Row at Top\n    </button>\n\n    <Table\n      interactive\n      editKeyBinding=\"e\"\n      newRowPosition=\"top\"\n      addRowRef={addRowRef}\n      columns={columns}\n      data={users}\n      onSave={async ({ updatedRows, newRows, allData }) => {\n        await api.saveUsers({ updatedRows, newRows });\n      }}\n    />\n  </div>\n);\n```\n\n[← Component overview](README.md)\n",
+    "Table": "# Table\n\nData table with sorting, filtering, pagination, row selection, expandable details, and responsive mobile card view. The toolbar **Reload** button is tinted `bg-primary-100 text-primary-700` with `dark:bg-primary-900/40 dark:text-primary-300` in dark mode. Column headers, mobile-card labels and filter labels use `text-primary-700` / `dark:text-primary-300`; mobile-card values use `text-primary-900` / `dark:text-foreground`.\n\n## Import\n\n```jsx\nimport { Table } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `data` | `Array` | `[]` | Row data (array of objects) |\n| `columns` | `Array` | `[]` | Column definitions `[{ key, label, sortable?, isVisible?, editable?, type?, options?, required?, validate?, onRender?, render?, searchable?, wrap?, hideOnMobile? }]`. `searchable: false` excludes the column from the global search, `wrap: true` lets its cells wrap, `hideOnMobile: true` drops it from the mobile card view. `label` may be text or a node (an aligned or icon header); filter placeholders and validation messages use the label when it is text and the column `key` otherwise. |\n| `interactive` | `boolean` | `false` | Enable interactive mode with inline cell editing (double-click cell), keyboard shortcuts (`Tab`/`Shift+Tab` cell navigation, `Enter` to save modified changes, `Arrows`, `Escape`), primary Save button, outline Clear Changes button, constraint validation before save, and instant new row addition. |\n| `onSave` | `function` | — | Save callback in interactive mode `({ updatedRows, newRows, allData, tableData }) => Promise<allData | { data: allData } | void> | void`. Returning a dataset array or `{ data }`/`{ allData }` updates internal state with returned records. |\n| `onEdit` | `function` | — | Live edit callback fired when a cell value changes or row edit action is clicked `({ rowKey, colKey, newValue, row, action, isNew }) => void` |\n| `sortable` | `boolean` | `true` | Enable column sort. Each sortable header is a real `<button>` inside its `<th>` (Tab to it, Enter / Space to sort) and the `<th>` carries `aria-sort` (`none`, `ascending` or `descending`). |\n| `filterable` | `boolean` | `false` | Show a filter input per column. Client-side, each non-empty filter keeps rows whose value in that column contains the text (case-insensitive); filters combine with each other and with the global search. In `serverSide` mode nothing is filtered locally. |\n| `selectable` | `boolean` | `false` | Row selection checkboxes |\n| `pagination` | `boolean` | `false` | Enable pagination |\n| `pageSize` | `number` | `25` | Rows per page |\n| `onSort` | `function` | — | Sort callback `(key, direction)`. Called once per sort, after the state update (not during render), so it may set parent state. |\n| `onFilter` | `function` | — | Filter callback `(filters)`. Called once per change, outside render, like `onSort`. |\n| `onFetch` | `function` | — | Server-side fetch (setData, setLoading, filters, page, limit, sort) |\n| `onFilterChange` | `function` | — | Filter change callback |\n| `onSelectionChange` | `function` | — | Selected rows callback |\n| `onRowClick` | `function` | — | Row click callback |\n| `hasDetails` | `boolean` or `(row, index) => boolean` | `false` | Expandable row details. Pass a predicate to give only matching rows an expand toggle; non-matching rows render an empty placeholder cell so columns stay aligned. |\n| `DetailsComponent` | `Component` | — | Component for expanded content |\n| `withAction` | `boolean` | `true` | Show actions column |\n| `onAction` | `function` | — | Action menu callback |\n| `actions` | `Array` or `(row, index) => Array` | — | Row actions. Entries are `{ name, label, icon, render?, onClick?, hidden?, disabled?, inline?, tone? }`; `tone: 'destructive'` (or `destructive: true`) styles a menu action in the error tone; `label`, `icon`, `hidden` and `disabled` each accept a value or `(row, index) => value`. `inline: true` renders the action as an icon button in the actions cell instead of inside the kebab menu; the kebab is hidden when no menu actions remain. Entries are merged onto the built-in Edit/Delete/View set by `name` (so `{ name: 'edit', onClick }` keeps the default label and icon, and `{ name: 'delete', hidden: true }` removes a default); unmatched entries are appended. Set `replaceDefaultActions` to opt out. |\n| `actionMenuPresentation` | `string` | `\"auto\"` | One of `auto`, `popover`, `sheet`. How the row kebab menu opens. `popover`: a floating menu portaled to `document.body` that flips/shifts to stay on screen (never clipped by the table's overflow). `sheet`: an iOS-style action sheet from the bottom with a separate Cancel button. `auto` uses the sheet on small touch screens (`(pointer: coarse) and (max-width: 639px)`) and the popover elsewhere. |\n| `replaceDefaultActions` | `boolean` | `false` | Replace the built-in Edit/Delete/View actions entirely instead of patching them by `name`. |\n| `showSerial` | `boolean` | `true` | Show row number column |\n| `cellClass` | `string` \\| `function` | — | Cell className |\n| `rowClass` | `string` \\| `function` | — | Row className |\n| `globalSearch` | `boolean` | `false` | Global search box. Works with or without `filterable`. Client-side, keeps rows where any value outside a `searchable: false` column contains the term (case-insensitive). In `serverSide` mode it only reports `filters.global`. |\n| `limitOptions` | `number[]` | `[10,25,50,100]` | Page size options |\n| `showLimitSelector` | `boolean` | `true` | Show page size selector |\n| `showReloadButton` | `boolean` | `true` | Show reload button. It is named \"Reload\" (`aria-label`) because its text label is hidden below the `sm` breakpoint |\n| `onReload` | `function` | — | Reload click handler |\n| `stripedRows` | `boolean` | `true` | Striped row background |\n| `theme` | `object` | see below | `stripedColors`, `rowHover`, `accentColor`, `menuBg`, `menuItemHover`. Defaults are dark-mode aware: `{ stripedColors: ['bg-surface', 'bg-background'], rowHover: 'bg-background', accentColor: 'bg-background', menuBg: 'bg-surface', menuItemHover: 'hover:bg-background' }`. A `stripedColors` entry may be a Tailwind `bg-*` class (applied as a class) or a CSS colour such as `'#f7fafc'` (applied as an inline background). `rowHover` is a `bg-*` token or a full hover class string. In the pagination controls, the shipped tokens (`bg-background`, `bg-surface`, `bg-gray-50`, `bg-gray-100`, `bg-primary-50`, `bg-primary-100`) map to static `hover:` literals; for any other colour pass the full class (e.g. `'hover:bg-gray-200'`) so your Tailwind build generates it — a bare unknown token is still prefixed with `hover:` at runtime for backward compatibility, but Tailwind can purge such a class. Pagination buttons grow to a 44×44 px touch target on coarse pointers. |\n| `serverSide` | `boolean` | `false` | Server-side pagination/sort/filter |\n| `totalRecords` | `number` | `0` | Total count (serverSide). Drives the page count and the \"start - end of total\" counter; when omitted the counter falls back to the rows received. |\n| `pageNumber` | `number` | — | Controlled page. Client-side, a page past the last one is clamped to the last page once rows exist. |\n| `onPageChange` | `(page: number) => void` | — | Called with the new page number when the user changes page, and when the table clamps a page that no longer exists (client-side). Not called for the reset to page 1 on a filter or page-size change. Consumed by the table — it is **not** forwarded onto the `<table>`. |\n| `responsiveBreakpoint` | `number` | `768` | px breakpoint for mobile cards: card mode while the viewport is narrower than this. Read with an SSR-safe media query (`not all and (min-width: <n>px)`), so client renders pick the right layout on the first render and follow resizes live. |\n| `defaultMobileView` | `boolean` | `false` | Layout used on the server and while hydrating, before the media query can be read. Set `true` on phone-first pages so server-rendered HTML starts as cards. |\n| `mobileFiltersPresentation` | `string` | `\"auto\"` | Card-mode filters (with `filterable` / `globalSearch`). `sheet`: a \"Filters\" button (with an active-filter count) opening a bottom `Sheet`; edits are a draft until **Apply**, **Clear** empties the draft. `inline`: the collapsible inline panel (the previous behaviour, live filtering). `auto` uses the sheet on small touch screens (`(pointer: coarse) and (max-width: 639px)`) and the inline panel elsewhere. |\n| `swipeActions` | `(row, index) => { leading?, trailing? } \\| null` | — | Swipe actions on the mobile cards, built on [`SwipeableListItem`](SwipeableListItem.md). Each side is an array of `{ key, label, icon?, tone?, disabled?, onSelect }`; swipe right for `leading`, left for `trailing`, a full swipe commits the first action of that side. Only one card is open at a time. Every action is also reachable without a gesture through the card's \"Swipe actions\" button. Return `null` (or empty arrays) for rows without swipe actions. |\n| `stickyHeader` | `boolean` \\| `string` \\| `number` | `false` | Keep the desktop header visible while the body scrolls. `true` sticks within the table's own scroll container; a CSS length (`\"24rem\"`) or a number (px) also caps that container's height so the rows scroll under the header. |\n| `paginationPosition` | `'top'` \\| `'bottom'` \\| `'both'` | `'both'` | Which pager renders when `pagination` is on. `'both'` keeps the compact pager in the toolbar and the \"Page N of M\" footer. `'bottom'` drops the toolbar pager but keeps the rest of the toolbar (reload, page size, result count). `'top'` keeps only the toolbar pager (so with `showToolbar={false}` there is no pager). Unknown values fall back to `'both'`. |\n| `showToolbar` | `boolean` | `true` | Show the toolbar above the table (reload, page size, result count, pager header) and the column picker. `false` hides all of it; the pager footer stays, and in `interactive` mode the add-row / Save / Clear controls still render. `globalSearch` is its own opt-in and is unaffected. |\n| `showColumnPicker` | `boolean` | `true` | Show the column-picker button in the header (accessible name \"Choose columns\", with `aria-expanded`). `false` also removes its (otherwise empty) column from every row. |\n| `wrapCells` | `boolean` | `false` | Let cell text wrap instead of staying on one line. A column's own `wrap` overrides it. |\n| `mobileMaxFields` | `number` | — | Cap the fields shown on each mobile card. Applied in column order, after `hideOnMobile` columns are removed. |\n\nOnly DOM-valid attributes in `...rest` (e.g. `id`, `aria-*`, `data-*`) are\nforwarded to the root `<table>`; the table's own control props (`onPageChange`,\n`serverSide`, `pagination`, the `on*` callbacks, …) are consumed and never leak\nto the DOM as unknown attributes.\n\n## Examples\n\n### Basic table\n\n```jsx\nconst columns = [\n  { key: 'name', label: 'Name' },\n  { key: 'email', label: 'Email' },\n];\nconst data = [\n  { id: 1, name: 'Alice', email: 'alice@example.com' },\n  { id: 2, name: 'Bob', email: 'bob@example.com' },\n];\n<Table data={data} columns={columns} />\n```\n\n### With pagination and selection\n\n```jsx\n<Table\n  data={data}\n  columns={columns}\n  pagination\n  pageSize={10}\n  selectable\n  onSelectionChange={(selected) => console.log(selected)}\n/>\n```\n\n### Server-side data\n\n```jsx\n<Table\n  data={data}\n  columns={columns}\n  serverSide\n  pagination\n  totalRecords={total}\n  onFetch={async ({ setData, setLoading, page, limit, sort }) => {\n    setLoading(true);\n    const res = await fetch(`/api/users?page=${page}&limit=${limit}`);\n    const json = await res.json();\n    setData(json.rows);\n    setLoading(false);\n  }}\n/>\n```\n\n### Filtering and page clamping (client-side)\n\nWithout `serverSide`, the table filters the rows itself:\n\n- **Global search** (`globalSearch`) applies on Enter or the search button,\n  with or without `filterable`. Columns with `searchable: false` are skipped.\n- **Column filters** (`filterable`) apply as you type. Each one matches only its\n  own column's raw value (not a `render` output).\n- All matches are case-insensitive \"contains\" tests, and every active filter\n  must match (AND).\n- `onFilter` / `onFilterChange` still receive the whole `filters` object\n  (`{ global?, [columnKey]: text }`) on every change.\n\nWhen the rows shrink (filtering, deleted rows, a new `data` prop) and the\ncurrent page no longer exists, the table shows the last page that does and\ncalls `onPageChange` with it. A parent that drives `pageNumber` can simply\nstore that value, and no `clampPage` helper is needed. The clamp waits while\nthere are no rows, so a page restored from the URL survives until the data\narrives.\n\nWith `serverSide`, none of this runs locally: filters go to `onFetch` /\n`onFilter` / `onFilterChange`, the rows shown are exactly the rows you pass,\nand keeping `pageNumber` within `totalRecords` is up to you.\n\n### Compact, read-only table\n\nHide the chrome for a dashboard card, keep id columns out of the search, let\nlong text wrap, and keep phone cards short.\n\n```jsx\nconst columns = [\n  { key: 'id', label: 'ID', searchable: false, hideOnMobile: true },\n  { key: 'client', label: 'Client' },\n  { key: 'status', label: 'Status' },\n  { key: 'notes', label: 'Notes', wrap: true },\n  { key: 'owner', label: 'Owner' },\n];\n\n<Table\n  data={rows}\n  columns={columns}\n  showToolbar={false}\n  showSerial={false}\n  withAction={false}\n  mobileMaxFields={3}\n/>\n```\n\nOn a phone each card shows Client, Status and Notes. With no serial, selection,\nexpand toggle or actions, the card has no header strip either.\n\n`showToolbar={false}` does not change pagination: with `pagination` on, the pager\nfooter still renders. Hide only the picker with `showColumnPicker={false}`.\n\n### One pager instead of two\n\nWith `pagination` and the toolbar both on, the table shows a compact pager in the\ntoolbar and another under the rows. Keep the toolbar (reload, page size, result\ncount) and drop the top pager with `paginationPosition=\"bottom\"`:\n\n```jsx\n<Table data={rows} columns={columns} pagination paginationPosition=\"bottom\" />\n```\n\n`paginationPosition=\"top\"` does the opposite and keeps only the toolbar pager.\n\n### Conditional row details\n\n`hasDetails` accepts a predicate so only rows that actually have something to\nshow get an expand toggle. Rows that don't qualify still render the (empty)\ntoggle cell, so the columns stay aligned.\n\n```jsx\nconst ErrorDetails = ({ row }) => <pre>{row.stackTrace}</pre>;\n\n<Table\n  data={jobs}\n  columns={columns}\n  hasDetails={(row) => row.status === 'failed'}\n  DetailsComponent={ErrorDetails}\n/>\n```\n\n### Mobile cards, filters and swipe actions\n\nBelow `responsiveBreakpoint` rows render as cards. Card controls (expand\ntoggle, selection checkbox, inline actions, kebab) have 44×44 px hit areas.\nWith `filterable` on a phone, the filters open in a bottom sheet with an\nApply / Clear footer; pass `mobileFiltersPresentation=\"inline\"` to keep the\ninline panel.\n\n```jsx\n<Table\n  data={messages}\n  columns={columns}\n  filterable\n  defaultMobileView            // server-rendered HTML starts as cards\n  swipeActions={(row) => ({\n    leading: [{ key: 'read', label: 'Read', icon: MailOpen, tone: 'primary', onSelect: () => markRead(row) }],\n    trailing: [\n      { key: 'delete', label: 'Delete', icon: Trash2, tone: 'destructive', onSelect: () => remove(row) },\n      { key: 'flag', label: 'Flag', icon: Flag, tone: 'warning', onSelect: () => flag(row) },\n    ],\n  })}\n/>\n```\n\n### Sticky header\n\n```jsx\n<Table data={rows} columns={columns} stickyHeader=\"28rem\" />\n```\n\n### Row action menu\n\nThe kebab button (`aria-haspopup=\"menu\"`) opens the row's menu actions. On\ndesktop it is a `role=\"menu\"` popover: focus moves to the first action,\nArrowUp/ArrowDown (wrapping), Home/End and first-letter typeahead move between\nactions, Escape or Tab closes it and returns focus to the kebab, and a press\noutside or a page scroll closes it (pressing the kebab again closes it too). On phones (`actionMenuPresentation=\"auto\"`,\nthe default) the same actions open as an action sheet: 48px rows in a rounded\ncard, destructive actions in red, and a Cancel button below. Pass\n`actionMenuPresentation=\"popover\"` to keep the desktop menu everywhere.\n\n```jsx\n<Table\n  data={users}\n  columns={columns}\n  actions={[{ name: 'delete', tone: 'destructive' }]}\n  actionMenuPresentation=\"auto\"\n/>\n```\n\n### Conditional and inline actions\n\n`hidden` and `disabled` accept a `(row, index)` predicate, `label` and `icon`\naccept a `(row, index)` producer, and `inline: true` promotes an action out of\nthe kebab menu into the row itself. When no menu actions remain for a row, the\nkebab button is not rendered at all.\n\n```jsx\n<Table\n  data={jobs}\n  columns={columns}\n  replaceDefaultActions\n  actions={[\n    { name: 'view', label: 'View', icon: <Eye size={16} />, inline: true },\n    { name: 'edit', label: 'Edit', icon: <Edit size={16} />,\n      disabled: (row) => row.locked },\n    { name: 'retry', label: (row) => `Retry (${row.tries})`,\n      hidden: (row) => row.status !== 'failed' },\n  ]}\n  onAction={({ action, row }) => handle(action.name, row)}\n/>\n```\n\nFor a large table, wrap a function-valued `actions` in `useCallback` — a fresh\narrow on every render defeats the per-row memoization.\n\n```jsx\nconst actions = useCallback(\n  (row) => (row.role === 'admin' ? adminActions : userActions),\n  []\n);\n```\n\nNote that because `icon` may be a `(row, index) => node` producer, passing a\nbare component reference (`icon: Edit`) calls it rather than rendering it. Pass\nan element instead: `icon: <Edit size={16} />`.\n\n### Patching the default actions\n\nEntries you supply are merged onto the built-in Edit/Delete/View set by `name`,\nso you can swap one handler without restating the rest. Unmatched names are\nappended after the defaults, and `hidden: true` removes a default outright.\n\n```jsx\n<Table\n  data={users}\n  columns={columns}\n  actions={[\n    { name: 'edit', onClick: ({ row }) => edit(row) }, // keeps default label + icon\n    { name: 'delete', hidden: (row) => !row.canDelete },\n    { name: 'invite', label: 'Invite', icon: <Mail size={16} /> }, // appended\n  ]}\n/>\n```\n\nPass `replaceDefaultActions` to skip merging and use only your own set:\n\n```jsx\n<Table\n  data={users}\n  columns={columns}\n  replaceDefaultActions\n  actions={[{ name: 'approve', label: 'Approve' }]}\n/>\n```\n\n### Interactive Table Mode\n\nPass `interactive={true}` to enable inline cell editing (double-click a cell or press standard `'e'` key on a focused active cell to enter edit mode), instant record addition (at top or bottom), keyboard navigation (`Tab`/`Shift+Tab` to move between cells, `Escape` to exit edit mode, `Enter` to save modified changes), and constraint validation before saving.\n\n#### Interactive Props & Options\n\n- `interactive`: `boolean` (default: `false`) — Enables interactive mode.\n- `editKeyBinding`: `string | ((e) => boolean)` (default: `\"e\"`) — Standard key binding to enter cell edit mode on active focused cell.\n- `newRowPosition`: `\"bottom\" | \"top\"` (default: `\"bottom\"`) — Position where empty new rows are inserted (at the bottom or top of table dataset).\n- `addRowRef`: `React.MutableRefObject` — External ref populated with `(position?: \"top\" | \"bottom\") => void` to trigger adding a new row from external buttons.\n- `onInitAddRow`: `(addRowFn: (position?: \"top\" | \"bottom\") => void) => void` — Callback receiving the add-row function on component initialization.\n- `renderAddRowButton`: `({ addRow, newRowPosition }) => ReactNode` — Render prop for rendering a custom external add-row button in the table toolbar.\n\n#### Interactive Usage Example\n\n```jsx\nconst columns = [\n  { key: 'name', label: 'Name', type: 'text', required: true },\n  { key: 'role', label: 'Role', type: 'select', options: ['Admin', 'User'], required: true },\n  { key: 'notes', label: 'Notes', type: 'textarea' },\n];\n\nconst addRowRef = useRef();\n\nreturn (\n  <div>\n    <button onClick={() => addRowRef.current?.(\"top\")}>\n      Add Row at Top\n    </button>\n\n    <Table\n      interactive\n      editKeyBinding=\"e\"\n      newRowPosition=\"top\"\n      addRowRef={addRowRef}\n      columns={columns}\n      data={users}\n      onSave={async ({ updatedRows, newRows, allData }) => {\n        await api.saveUsers({ updatedRows, newRows });\n      }}\n    />\n  </div>\n);\n```\n\n[← Component overview](README.md)\n",
     "Tabs": "# Tabs\n\nTabbed content with list and panels. Use subcomponents: `Tabs.List`, `Tabs.Tab`, `Tabs.Panels`, `Tabs.Panel`. Supports controlled (`index` + `onChange`) or uncontrolled (`defaultIndex`), keyboard navigation, and variants.\n\n**Accessibility and SSR:** tab and panel ids come from `React.useId()`, so server-rendered markup hydrates without mismatches and two Tabs on one page never collide. Each tab's `aria-controls` and each panel's `aria-labelledby` point at elements that exist. Panels mount lazily, so only the selected tab carries `aria-controls`.\n\n## Import\n\n```jsx\nimport { Tabs } from '@dreamtree-org/twreact-ui';\n```\n\n## Props (Tabs root)\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `children` | `ReactNode` | — | Must include `Tabs.List` and `Tabs.Panels`. |\n| `defaultIndex` | `number` | `0` | Uncontrolled initial active tab index. |\n| `index` | `number` | — | Controlled active index. |\n| `onChange` | `(index: number) => void` | — | Called when tab changes. |\n| `orientation` | `\"horizontal\"` \\| `\"vertical\"` | `\"horizontal\"` | Layout direction. |\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `\"md\"` | Tab size. Other `Size` values (`xs`, `xl`, `2xl`) fall back to `md`. |\n| `variant` | `\"line\"` \\| `\"pills\"` \\| `\"segmented\"` \\| `\"unstyled\"` | `\"line\"` | Tab style. `segmented` is an iOS-style segmented control: equal-width segments on a tinted `bg-line` track (same as `SegmentedControl`, follows dark mode) with a sliding surface thumb. |\n| `animated` | `boolean` | `true` | Fade-in (`animate-fade-in`) on the newly active panel; skipped under `prefers-reduced-motion`. |\n| `swipeable` | `boolean` | `false` | Swipe the panels left/right (touch or pen, at least 50 px and mostly horizontal) to move to the next/previous enabled tab. Vertical scrolling is never blocked (`touch-action: pan-y`); mouse drags are ignored. |\n| `className` | `string` | `\"\"` | Wrapper CSS classes. |\n\n**Scrolling and indicator:** a horizontal `Tabs.List` scrolls sideways with scroll-snap and a hidden scrollbar, and keeps the active tab scrolled into view. For `line` and `segmented`, the active underline / thumb is a single indicator that slides between tabs (`duration-base`, no transition under `prefers-reduced-motion`). It is measured after mount, so server-rendered markup shows the static active style until then. Horizontal tabs draw their focus ring inset so the scroll container doesn't clip it.\n\n`Tabs.List` forwards a `ref` and spreads extra props (`aria-label`, `data-*`, …) onto the `role=\"tablist\"` element.\n\n## Tabs.Tab props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `children` | `ReactNode` | — | Tab label |\n| `leftIcon` | `ReactNode` | — | Icon before the label. Renamed from `iconLeft` in 2.0.0 ([migration](MIGRATION-2.0.md#tabstab-iconleft--iconright)) |\n| `rightIcon` | `ReactNode` | — | Icon after the label. Renamed from `iconRight` in 2.0.0 |\n| `disabled` | `boolean` | `false` | Skip the tab in keyboard navigation and ignore clicks |\n| `tabClassName` | `string` | `\"\"` | Extra classes for the tab button |\n\n## Usage\n\n```jsx\n<Tabs defaultIndex={0} variant=\"pills\" size=\"md\">\n  <Tabs.List>\n    <Tabs.Tab>Home</Tabs.Tab>\n    <Tabs.Tab>Profile</Tabs.Tab>\n    <Tabs.Tab leftIcon={<Settings className=\"h-4 w-4\" />}>Settings</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panels>\n    <Tabs.Panel>Home content</Tabs.Panel>\n    <Tabs.Panel>Profile content</Tabs.Panel>\n    <Tabs.Panel>Settings content</Tabs.Panel>\n  </Tabs.Panels>\n</Tabs>\n```\n\nControlled:\n\n```jsx\nconst [index, setIndex] = useState(0);\n<Tabs index={index} onChange={setIndex}>\n  ...\n</Tabs>\n```\n\n[← Component overview](README.md)\n",
+    "TestimonialSpotlight": "# TestimonialSpotlight\n\nClient quotes beside a 3×3 grid of soft tiles: the active client's logo sits in the centre tile and other clients' logos are faded into the corners. Dots select the quote and it can auto-advance. Part of the `/motion` entry point ([overview](Motion.md)).\n\n## Install\n\nNothing extra — the `/motion` entry point has no required peer dependency.\n\n## Import\n\n```jsx\nimport { TestimonialSpotlight } from '@dreamtree-org/twreact-ui/motion';\n```\n\nNever import it from the root `@dreamtree-org/twreact-ui` — the motion components are not exported there.\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `items` | `{ id?, quote: ReactNode, name: ReactNode, role?: ReactNode, logo?: { src, alt } \\| ReactNode }[]` | `[]` | **Required.** One entry per quote. With no items it renders nothing |\n| `autoplay` | `number` | `6000` | Auto-advance interval in ms; `0` disables. Pauses on hover, while focus is inside, while off screen, with the Pause button and under reduced motion |\n| `grid` | `boolean` | `true` | Show the 3×3 logo tile grid |\n| `label` | `string` | `\"Testimonials\"` | Accessible name of the section |\n| `className` | `string` | — | Extra classes for the root `<section>` (merged with `cn`) |\n| `ref` | `Ref<HTMLElement>` | — | Forwarded to the root `<section>` |\n| ...rest | `HTMLAttributes<HTMLElement>` | — | Forwarded to the root `<section>` |\n\n## Examples\n\n```jsx\n<TestimonialSpotlight\n  items={[\n    { quote: 'They shipped our school app in eight weeks.', name: 'Asha Rao', role: 'Principal', logo: { src: '/logos/schoo360.svg', alt: 'Schoo360' } },\n    { quote: 'Billing went from a weekend chore to a button.', name: 'Ravi Kumar', role: 'Founder', logo: { src: '/logos/billpro.svg', alt: 'BillPro' } },\n  ]}\n/>\n\n<TestimonialSpotlight items={quotes} grid={false} autoplay={0} />\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Semantics | A `<section aria-roledescription=\"carousel\">` named by `label`; the quote is a `<figure role=\"tabpanel\">` with `<blockquote>` and `<figcaption>` |\n| Dots | A `tablist` of `tab` buttons (\"Quote 2 of 3\") with roving tabindex: ←/→ (and ↑/↓) move and select, Home/End jump; selection wraps |\n| Live region | `aria-live=\"polite\"` while not auto-playing, `\"off\"` while it rotates, so screen readers are not interrupted |\n| Pause | A visible Pause / Play button whenever autoplay is on (WCAG 2.2.2) |\n| Logos | The centre logo uses your `alt`; the faded corner logos are `aria-hidden` |\n\n## Reduced motion & server rendering\n\nThe server renders the first quote. Autoplay only starts once the section is on screen. Under `prefers-reduced-motion: reduce` it never auto-advances, the Pause button is hidden and the fade-in is off.\n\n[← Component overview](README.md)\n",
     "TextToSpeech": "# TextToSpeech\n\nText-to-speech using the browser’s Speech Synthesis API. Renders a styled \"Speak\" / \"Stop\" button (matching `SpeechToText`) or a custom button via `renderButton`. Toggling speak while playing stops playback.\n\n## Import\n\n```jsx\nimport { TextToSpeech } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `text` | `string` | `\"\"` | Text to speak. The **current** value is spoken on each click, so later prop changes are honoured. |\n| `rate` | `number` | `1` | Speech rate (0.1–10). |\n| `pitch` | `number` | `0.5` | Pitch (0–2). |\n| `onSpeak` | `(text: string) => void` | `() => {}` | Called when speech starts (with the text spoken). |\n| `onError` | `(error: Error) => void` | `() => {}` | Called when synthesis fails. Intentional stops (`interrupted` / `canceled`) are not reported. |\n| `disabled` | `boolean` | `false` | Disables the button. |\n| `renderButton` | `(props: { onClick, isSpeaking, isSupported, disabled, speak, stop }) => ReactNode` | — | Custom button. `onClick` toggles; `isSupported` is `false` when the browser has no `speechSynthesis`. |\n| `className` | `string` | — | Merged (via `cn`) onto the default button. |\n| `...rest` | `ButtonHTMLAttributes` | — | Forwarded to the default `<button>` (`aria-*`, `data-*`, `id`, …). |\n\n`ref` is forwarded to the default `<button>` element.\n\n## Behavior\n\n- Clicking the button toggles: if not speaking, speaks the current `text` with a new `SpeechSynthesisUtterance`; if speaking, calls `speechSynthesis.cancel()`.\n- `onSpeak` is called when speech starts; the button returns to \"Speak\" when the utterance ends **or errors**.\n- **Unsupported browsers:** when `window.speechSynthesis` is missing the default button renders disabled with a `title` (and screen-reader text) explaining that text-to-speech is not supported. `renderButton` receives `isSupported: false` / `disabled: true`.\n- **Unmount:** if this instance is speaking when it unmounts, playback is cancelled.\n- The default button is rendered directly (no wrapper `<div>`), with `aria-pressed` reflecting the speaking state and a `focus-visible` ring.\n\n## Example\n\n```jsx\n<TextToSpeech text=\"Hello, world!\" rate={1} onSpeak={(t) => console.log('Speaking:', t)} />\n\n<TextToSpeech\n  text={content}\n  renderButton={({ onClick, isSpeaking }) => (\n    <Button onClick={onClick}>{isSpeaking ? 'Stop' : 'Play'} audio</Button>\n  )}\n/>\n```\n\n[← Component overview](README.md)\n",
     "Textarea": "# Textarea\n\nMulti-line text input that mirrors `Input`'s API: label, error, helper text, required marker, character count, plus optional auto-resize.\n\n## Import\n\n```jsx\nimport { Textarea } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `label` | `ReactNode` | — | Label rendered above the field (linked with `htmlFor`) |\n| `error` | `ReactNode` | — | Error message; sets `aria-invalid` and is shown with an icon |\n| `helperText` | `ReactNode` | — | Hint below the field; wired to `aria-describedby` |\n| `required` | `boolean` | `false` | Marks the field required (native `required` + visual `*`) |\n| `disabled` | `boolean` | `false` | Disables the field |\n| `showCount` | `boolean` | `false` | Show `current/maxLength` (needs `maxLength`) |\n| `maxLength` | `number` | — | Native max length |\n| `autoResize` | `boolean` | `false` | Grow with the content; disables the manual resize handle |\n| `rows` | `number` | `3` | Initial (minimum) rows |\n| `maxRows` | `number` | — | With `autoResize`, cap the height and scroll beyond it |\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `\"md\"` | Padding and text size (`md` is the original look); `rows` still sets the height |\n| `value` | `string` | — | Controlled value |\n| `defaultValue` | `string` | — | Uncontrolled initial value |\n| `onChange` | `function` | — | Native change handler |\n| `id` | `string` | — | Field id (auto-generated otherwise) |\n| `className` | `string` | — | Extra classes for the `<textarea>` (merged with `cn`) |\n| `...rest` | `TextareaHTMLAttributes` | — | Forwarded to the `<textarea>`; `ref` points at it |\n\nWorks controlled (`value` + `onChange`) or uncontrolled (`defaultValue`); the character count tracks both.\n\nThe focus ring is `focus-visible` only (no ring left after a mouse click), and colours use role tokens (`bg-surface`, `text-foreground`) with `dark:` counterparts.\n\n## Examples\n\n### Basic\n\n```jsx\n<Textarea label=\"Description\" placeholder=\"What needs to happen?\" helperText=\"Plain text only.\" />\n```\n\n### Count + validation\n\n```jsx\n<Textarea label=\"Reason\" required showCount maxLength={280} error={errors.reason} value={reason} onChange={(e) => setReason(e.target.value)} />\n```\n\n### Auto-resize\n\n```jsx\n<Textarea label=\"Notes\" autoResize maxRows={8} value={notes} onChange={(e) => setNotes(e.target.value)} />\n```\n\n## Accessibility\n\n| Behavior | Detail |\n|----------|--------|\n| Labelling | `label` is a real `<label htmlFor>` |\n| Description | `error` and `helperText` ids (plus any `aria-describedby` you pass) are joined into `aria-describedby` |\n| Error | `aria-invalid=\"true\"`; the message is `aria-live=\"polite\"` and paired with an icon (not color alone) |\n| Focus ring | `focus:ring-2 focus:ring-primary-500` (error ring when invalid) |\n| Dark mode | Field, border, label and helper text use `dark:` variants |\n\n[← Component overview](README.md)\n",
     "ThreeDotPopover": "# ThreeDotPopover\n\nAction menu triggered by a three-dot (kebab) button. Use for row actions (Edit, Delete, etc.). On desktop it opens a floating menu; on phones it opens an iOS-style action sheet. Closes on outside press, Escape and (by default) on item select.\n\n## Import\n\n```jsx\nimport { ThreeDotPopover } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `items` | `Array` | `[]` | Menu items: `{ key, label, icon?, onClick?, disabled?, destructive?, tone? }`. `icon` can be a component (e.g. `Edit2`) or a node. |\n| `presentation` | `string` | `\"auto\"` | One of `auto`, `popover`, `sheet`. `popover`: floating menu next to the trigger. `sheet`: action sheet from the bottom of the screen. `auto`: the sheet on small touch screens (`(pointer: coarse) and (max-width: 639px)`), the popover elsewhere and on the server. |\n| `trigger` | `ReactElement` | — | Custom trigger; default is three-dot button. It receives `ref`, `onClick`, `onKeyDown`, `aria-haspopup=\"menu\"`, `aria-expanded` and `aria-controls`. |\n| `className` | `string` | `\"\"` | CSS classes for the **default** trigger button (merged via `cn()`). |\n| `wrapperClassName` | `string` | `\"\"` | CSS classes merged (via `cn()`) onto the root container element. |\n| `menuClass` | `string` | `\"\"` | Classes for the popover menu container (popover mode only). |\n| `menuItemClass` | `string` | `\"\"` | Classes for every menu item (popover and sheet). |\n| `closeOnSelect` | `boolean` | `true` | Close menu when an item is selected. |\n| `ariaLabel` | `string` | `\"More options\"` | Trigger button aria-label; also names the menu / sheet. |\n| `cancelLabel` | `ReactNode` | `\"Cancel\"` | Text of the action sheet's Cancel button (sheet mode only). |\n\n## Item shape\n\n- `key` (string): Unique key.\n- `label` (string): Display text (also used for typeahead).\n- `icon` (optional): React component or node.\n- `onClick(item)` (optional): Called when item is clicked.\n- `disabled` (boolean): Disable the item (skipped by keyboard navigation).\n- `destructive` (boolean) or `tone: 'destructive'`: Style in the error tone (e.g. red for Delete). The two are equivalent.\n\n## Example\n\n```jsx\nimport { Edit2, Eye, Trash } from 'lucide-react';\n\n<ThreeDotPopover\n  items={[\n    { key: 'edit', label: 'Edit', icon: Edit2, onClick: () => edit(row) },\n    { key: 'view', label: 'View', icon: Eye, onClick: () => view(row) },\n    { key: 'delete', label: 'Delete', tone: 'destructive', onClick: () => remove(row) },\n  ]}\n  closeOnSelect\n/>\n```\n\nKeep the desktop menu on every device:\n\n```jsx\n<ThreeDotPopover presentation=\"popover\" items={items} />\n```\n\n## Behavior\n\n- **Popover mode.** The menu is portaled to `document.body` and positioned\n  with flip/shift, so it is never clipped by an `overflow: hidden` parent\n  (such as a scrolling table) or the screen edge. It stacks on the `z-popover`\n  layer, above dialogs and sheets.\n- **Keyboard.** Opening focuses the first enabled item (ArrowDown / ArrowUp on\n  the closed trigger also open it, focusing the first / last item).\n  ArrowDown / ArrowUp move between items and wrap, Home / End jump to the ends,\n  and typing a letter jumps to the next item starting with it. Escape closes the\n  menu and returns focus to the trigger; Tab closes it and continues from the\n  trigger.\n- **Sheet mode.** Items are 48px rows in a rounded card, destructive items in\n  the error tone, with a separate Cancel button below. Escape, the backdrop,\n  a downward drag or Cancel close it, and focus returns to the trigger.\n- **Trigger.** `aria-haspopup=\"menu\"`, `aria-expanded`, a focus-visible ring\n  and a 44×44px touch target on coarse pointers.\n\n## Notes\n\n- Forwards `ref` to the root container element and spreads unknown props\n  (`...rest`) onto it.\n- The menu is only in the DOM while open.\n\n[← Component overview](README.md)\n",
@@ -7258,7 +8203,9 @@
     "Tooltip": "# Tooltip\n\nTooltip shown on hover, focus, or click — and on long-press on touch screens. Supports placement (auto/top/bottom/left/right), delay, offset, and optional portal. Positioned by the shared floating engine (`position: fixed`, flips and shifts to stay in view) in the `z-tooltip` layer. Content can be string or render prop `({ close }) => ReactNode`. Tooltip has no sheet presentation: for interactive content on phones use [`Popover`](Popover.md).\n\n## Import\n\n```jsx\nimport { Tooltip } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `position` | `\"auto\"` \\| `\"top\"` \\| `\"bottom\"` \\| `\"left\"` \\| `\"right\"` | `\"auto\"` | Preferred side. `auto` means top; every side flips to the opposite side when there is no room and shifts along its axis to stay 8px inside the viewport. The resolved placement is on the tooltip as `data-placement`. |\n| `trigger` | `\"hover\"` \\| `\"click\"` \\| `\"focus\"` \\| `Array` | `\"hover\"` | How tooltip opens. `hover` also opens on keyboard focus (unless `click` is in the list), and on touch screens `hover` / `focus` open on a long-press (see **Touch**). |\n| `content` | `ReactNode` \\| `({ close }) => ReactNode` | — | Tooltip content. |\n| `customTrigger` | `ReactElement` | — | Element used directly as the trigger (gets the ref + `aria-describedby`; no wrapper span). Use it to avoid an extra tab stop around focusable components. |\n| `children` | `ReactNode` | — | Trigger content when `customTrigger` is not used. Wrapped in a `<span>`; see Tab stops below. |\n| `open` | `boolean` | — | Controlled open state. |\n| `defaultOpen` | `boolean` | `false` | Uncontrolled initial open. |\n| `onChange` | `(open: boolean) => void` | — | Called when open state changes. |\n| `delay` | `number` | `80` | Delay in ms before opening (hover). |\n| `offset` | `number` | `8` | Spacing in px between trigger and tooltip. |\n| `textClass` | `string` | `\"text-foreground\"` | Tailwind class for the tooltip text color (role token, flips in dark mode). |\n| `bgClass` | `string` | `\"bg-surface\"` | Tailwind class for the tooltip background (role token, flips in dark mode). |\n| `className` | `string` | `\"\"` | Tooltip box CSS classes. |\n| `portal` | `boolean` | `true` | Render tooltip in document.body. With `false` it renders inline; it is still `position: fixed`, so avoid ancestors with `transform`/`filter` (they become its containing block). |\n| `style` | `CSSProperties` | — | Merged over the computed position styles on the tooltip box. |\n| `id` | `string` | — | Tooltip id. If omitted, a `React.useId()`-based id is generated, stable across server rendering and hydration. |\n\n## Touch\n\nOn a touch pointer (`pointerType: \"touch\"`), `hover` and `focus` tooltips:\n\n- **open on a long-press** (500 ms, finger held still within 10px). The OS context menu / callout is suppressed for that press, and the click a long-press may produce is swallowed;\n- **ignore a plain tap**: the emulated `mouseenter` / focus after a tap do not open the tip, so the tap only activates the trigger's own `onClick`. A tap on the trigger while the tip is open closes it;\n- **never stick open**: the tip hides 1.5 s after the finger lifts, or at once on a tap anywhere outside the trigger and the tooltip.\n\n`trigger=\"click\"` tooltips keep tap-to-toggle.\n\n## Hover and dismissal\n\n- Leaving the trigger closes a hover tooltip after a 100 ms grace period, so the pointer can move onto the tooltip; hovering the tooltip keeps it open (WCAG 1.4.13).\n- `Escape` closes any open tooltip; a pointer-down outside closes it too.\n\n## Tab stops: `customTrigger` vs `children`\n\nWhen you pass `children`, Tooltip wraps them in a `<span>`. If that span were\nalways focusable, a tooltip around a button would give keyboard users **two**\ntab stops (span, then button) — painful in table rows, toolbars and grids.\n\n- **A single native focusable child** — an enabled `<button>`, `<a href>`,\n  `<input>`, `<select>`, `<textarea>`, or any element with `tabIndex >= 0` — is\n  detected and the span gets **no** `tabIndex`; the child itself receives\n  `aria-describedby` (merged with any it already has). One tab stop.\n- **Anything else** (text, an icon, a disabled button, several children, or a\n  *component* such as `<Button>` that Tooltip cannot inspect) keeps the\n  `tabIndex=\"0\"` wrapper so the tooltip stays keyboard-reachable. This is what\n  makes tooltips on disabled buttons work.\n- **For components (e.g. `<Button>`, `<Badge>`), prefer `customTrigger`.** It\n  attaches the ref and `aria-describedby` to your element with no wrapper and\n  no extra tab stop:\n\n```jsx\n// Grid / table row: one tab stop per action\n<Tooltip content=\"Edit row\" customTrigger={<Button size=\"sm\">Edit</Button>} />\n\n// Native button child: also a single tab stop\n<Tooltip content=\"Delete\">\n  <button type=\"button\">Delete</button>\n</Tooltip>\n\n// Disabled control: wrapper stays focusable so the reason is reachable\n<Tooltip content=\"Uploads are not available yet\">\n  <button type=\"button\" disabled>Add</button>\n</Tooltip>\n```\n\n## Example\n\n```jsx\n<Tooltip content=\"Save your changes\" customTrigger={<Button>Save</Button>} />\n\n<Tooltip trigger=\"click\" content={({ close }) => <span>Click to close <button onClick={close}>OK</button></span>}>\n  <span>Click me</span>\n</Tooltip>\n\n<Tooltip position=\"bottom\" delay={200} content=\"Delayed tip\">\n  <Input placeholder=\"Focus me\" />\n</Tooltip>\n```\n\n[← Component overview](README.md)\n",
     "Tour": "# Tour\n\nStep-based onboarding tour (coach marks): dims the page, spotlights each step's target element and shows a step card beside it with Back / Next / Skip / Finish. Generalises the `SpotlightTour` that TaskPro and ProcurementPro each hand-rolled. A step without a target — or whose target never renders — shows as a centred card, so the tour never stalls. On phones the card docks at the bottom of the screen and steps can be swiped. The step card uses the semantic `bg-surface` / `border-line` / `text-foreground` tokens, so it follows dark mode.\n\n## Import\n\n```jsx\nimport { Tour } from '@dreamtree-org/twreact-ui';\n```\n\n## Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `open` | `boolean` | `false` | Show the tour |\n| `steps` | `array` | `[]` | `TourStep[]`: `{ target, title, content, placement }` (see below) |\n| `onClose` | `function` | — | `(reason) => void`; reason is `skip`, `escape`, `close` or `finish`. Set `open` to false here |\n| `onFinish` | `function` | — | Called by the Finish button on the last step (before `onClose('finish')`) |\n| `step` | `number` | — | Controlled step index |\n| `defaultStep` | `number` | `0` | Uncontrolled starting step; the tour restarts here every time it opens |\n| `onStepChange` | `function` | — | `(index, step) => void`; use it to navigate routes before a step shows |\n| `labels` | `object` | — | Override `next`, `back`, `skip`, `finish`, `close` and `progress(current, total)` |\n| `targetTimeout` | `number` | `3000` | How long (ms) to wait for a step's target before falling back to a centred card |\n| `spotlightPadding` | `number` | `6` | Space in px between the target and the spotlight ring |\n| `presentation` | `\"auto\"`, `\"popover\"` or `\"sheet\"` | `\"auto\"` | `sheet` docks the step card at the bottom of the screen; `popover` anchors it beside the target; `auto` docks on small touch screens (`(pointer: coarse) and (max-width: 639px)`) and anchors elsewhere (anchored on the server and while hydrating) |\n| `className` | `string` | — | Extra classes for the step card (merged with `cn`) |\n| `...rest` | `HTMLAttributes` | — | Forwarded to the step card; `ref` points at it. Your `onPointerDown` / `onPointerUp` / `onPointerCancel` / `onClickCapture` run before the swipe handling |\n\n## Step shape\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `target` | `string, ref, element or function` | CSS selector (e.g. `[data-tour=\"new-task\"]`), a React ref, a DOM element, or `() => element`. Omit for a centred intro/outro card |\n| `title` | `ReactNode` | Card heading; labels the dialog |\n| `content` | `ReactNode` | Card body; describes the dialog |\n| `placement` | `string` | `top`, `bottom` (default), `left`, `right` (each optionally `-start` / `-end`) or `center`; flips when there is no room and shifts to stay in view. Ignored while docked |\n\n## Examples\n\n### Basic\n\n```jsx\nconst steps = [\n  { title: 'Welcome', content: 'A 30-second tour of your workspace.' },\n  { target: '[data-tour=\"new-task\"]', title: 'Capture work', content: 'New task opens a quick form.', placement: 'bottom' },\n  { target: searchRef, title: 'Jump anywhere', content: 'Search tasks and projects.', placement: 'right' },\n];\n\nconst [open, setOpen] = useState(false);\n\n<Button onClick={() => setOpen(true)}>Take the tour</Button>\n<Tour open={open} steps={steps} onClose={() => setOpen(false)} onFinish={() => markTourSeen()} />\n```\n\n### Route-aware (react-router)\n\n```jsx\n<Tour\n  open={open}\n  steps={steps}\n  onStepChange={(i, step) => step.route && navigate(step.route)}\n  onClose={() => setOpen(false)}\n/>\n```\n\nExtra fields on a step (like `route`) are passed back to you untouched. The tour waits up to `targetTimeout` for the next screen's target to render.\n\n### Phones (docked card)\n\n```jsx\n// Default: docked on phones, anchored on desktop\n<Tour open={open} steps={steps} onClose={() => setOpen(false)} />\n\n// Always docked (e.g. a mobile-only shell)\n<Tour presentation=\"sheet\" open={open} steps={steps} onClose={() => setOpen(false)} />\n```\n\nWhile docked:\n\n- the card spans the screen width minus a 1rem gutter, sits 1rem above the bottom edge with `pb-safe` for the home indicator, and scrolls inside `max-h-[60dvh]`;\n- the spotlight stays on the target; the card carries `data-placement=\"docked\"` and `data-presentation=\"sheet\"`;\n- swiping the card **left goes to the next step, right goes back** (at least 50px, clearly more horizontal than vertical; vertical drags still scroll the card). A swipe that ends on a button does not also press it;\n- the close button is a 44 × 44px touch target on coarse pointers.\n\nThe anchored card is capped at `calc(100dvh - 2rem)` (dynamic viewport units, so the mobile browser toolbar never clips it).\n\n## Accessibility & keyboard\n\n| Behavior | Detail |\n|----------|--------|\n| Role | The **step card** is `role=\"dialog\"` + `aria-modal=\"true\"`, labelled by the step title and described by its content (the full-screen layer has no role, so global `[role=dialog]` styles never paint over the page) |\n| Focus | Moves to the card on open and on every step change; `Tab` is trapped in the card; focus returns to the opener on close |\n| `Escape` | Closes with reason `escape` |\n| `ArrowRight` / `ArrowLeft` | Next / previous step (ignored while typing in a field inside the card) |\n| Scroll into view | The target is scrolled into view through its nearest scrolling ancestor only (never `overflow: hidden` shells); smooth unless `prefers-reduced-motion` |\n| Reduced motion | Spotlight and card transitions are disabled under `prefers-reduced-motion` |\n| Scroll lock | Body scroll is locked while open |\n| Progress | \"Step 2 of 5\" text is visible and read with the card |\n| Dark mode | Card uses `dark:` variants; the spotlight ring switches to `primary-400` |\n\n[← Component overview](README.md)\n",
     "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"
+    "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",
+    "useScrollProgress": "# useScrollProgress\n\nScroll progress (0–1) of an element, without re-rendering React on every frame. It returns a subscription (`get()` / `subscribe(fn)`), writes the value to the element as a CSS custom property (`--dt-p` by default) and calls `onChange`. Work runs on the shared motion frame loop, and only while the element is near the viewport. The building block of `ScrollStage` and `PhotoCollage`.\n\n## Import\n\n```jsx\nimport { useScrollProgress } from '@dreamtree-org/twreact-ui/motion';\n```\n\n## Props\n\nOptions object passed to `useScrollProgress(ref, options)`. `ref` is a `RefObject<HTMLElement>` attached to the tracked element.\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `mode` | `'view'` \\| `'pin'` | `'view'` | `'view'`: 0 when the element's top meets the viewport bottom, 1 when its bottom leaves the viewport top. `'pin'`: 0 when its top meets the viewport top, 1 when its bottom meets the viewport bottom (the span a sticky child stays pinned) |\n| `start` | `number` | `0` | Start of the range (0–1) re-mapped to 0–1 |\n| `end` | `number` | `1` | End of the range (0–1) re-mapped to 0–1 |\n| `cssVar` | `string` | `'--dt-p'` | CSS custom property written on the element; `''` writes none |\n| `enabled` | `boolean` | `true` | `false` stops tracking and removes the CSS variable (pass `!reducedMotion`) |\n| `onChange` | `(progress: number) => void` | — | Called with each new value, on the frame loop (not during render) |\n\n## Returns\n\n| Field | Type | Description |\n|------|------|-------------|\n| `get()` | `number` | The current value. 1 (the final state) on the server, while disabled, after unmount and before the first frame |\n| `subscribe(fn)` | `(fn: (value: number) => void) => () => void` | Called with every new value; returns the unsubscribe function |\n\n## Examples\n\n```jsx\nfunction FadeInPanel({ children }) {\n  const ref = React.useRef(null);\n  useScrollProgress(ref, { start: 0, end: 0.4 });\n  // The variable is unset on the server and under reduced motion, so the fallback (1) shows the final state.\n  return <div ref={ref} className=\"[opacity:var(--dt-p,1)]\">{children}</div>;\n}\n```\n\n```jsx\nconst progress = useScrollProgress(ref, { mode: 'pin', onChange: (p) => video.currentTime = p * video.duration });\n```\n\n## Notes\n\n- The element is watched by a shared `IntersectionObserver` with a 25 % margin. When it leaves, one last value is written, so the variable settles at 0 or 1 even after a fast fling.\n- The hook does not read reduced motion itself; pass `enabled: false` when the user prefers reduced motion.\n\n[← Component overview](README.md)\n",
+    "useSmoothScroll": "# useSmoothScroll\n\nReturns `{ lenis, scrollTo }` from the nearest `SmoothScrollProvider`. Outside a provider, or while smooth scroll is off (no `lenis` class, `enabled={false}`, or reduced motion), `lenis` is `null` and `scrollTo` uses native `window.scrollTo` with smooth behaviour.\n\n## Import\n\n```jsx\nimport { useSmoothScroll } from '@dreamtree-org/twreact-ui/motion';\n```\n\n## Props\n\nTakes no arguments.\n\n## Returns\n\n| Field | Type | Description |\n|------|------|-------------|\n| `lenis` | `LenisLike \\| null` | The live Lenis instance, or `null` when native scroll is in use |\n| `scrollTo(target, options?)` | `(target: number \\| string \\| HTMLElement, options?: { offset?: number; immediate?: boolean }) => void` | Scroll to a y offset, a CSS selector or an element. With Lenis it calls `lenis.scrollTo(target, options)`; natively it scrolls to the element's top plus `offset`, `behavior: 'auto'` when `immediate`, else `'smooth'`. A selector that matches nothing does nothing |\n\n## Examples\n\n```jsx\nfunction BackToTop() {\n  const { scrollTo } = useSmoothScroll();\n  return <Button onClick={() => scrollTo(0)}>Back to top</Button>;\n}\n```\n\n```jsx\nconst { scrollTo } = useSmoothScroll();\nscrollTo('#pricing', { offset: -80 }); // clear an 80px sticky nav\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`, `QuantityStepper` (− / value / + spinbutton), `OptionCard` + `OptionCardGroup` (selectable choice tiles) |\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), `ImageGallery` (product photos: thumbnails / mosaic, swipe, zoom, lightbox) |\n| **Blocks**      | `AppShell`, `PageHeader`, `StatCard`, `StatusPill`, `EmptyState`, `ErrorState`, `LoadingState`, `ConfirmDialog`, `BottomActionBar` (+ `BottomActionBar.Spacer`), `ProductCard` (storefront product tile) — 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` (`Button` also has `link`, a text link coloured by `tone`)\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. `navOpen` / `onNavOpenChange` control the drawer (a FootNav \"More\" tab can open it — never click the menu button by `aria-label`); `topbarFrom=\"below-lg\"` drops the top bar on desktop. `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`). Put a `ProgressBar`, a line of text or a `Button variant=\"link\"` in `children` (rendered under the value); `tinted` draws the whole card in `tone` (an overdue card). Don't rebuild a KPI card from `Card`.\n- `ProductCard` — storefront tile: `images` (cover first) + `imageRatio` + `hover` (`zoom` / `second-image`), `eyebrow`, `title`, `meta`, `badges`, `price` / `compareAtPrice` (INR by default, discount computed; `priceFormatter`), `href` / `to` / `as` (the title is the one stretched link), `actions`, `selectable` + `selected` + `onSelectedChange` (compare), `layout=\"row\"` for phone lists.\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>`. For an inline text action (\"All payments →\") use `variant=\"link\"` (+ `tone=\"error\"` etc.), not a restyled ghost button.\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- `QuantityStepper` — cart / buy-box quantity: `<QuantityStepper label=\"Quantity\" value={qty} min={1} max={stock} onChange={setQty} />` (`onChange` gets a number). `step`, `size`, `loading`, `hideLabel`, `formatValue`, `name`. Never an `Input type=\"number\"` with +/- buttons.\n- `OptionCard` / `OptionCardGroup` — choice tiles: `<OptionCardGroup value={v} onChange={setV} columns={3} aria-label=\"Template\"><OptionCard value=\"classic\" title=\"Classic\" description=\"…\" media={<Sketch />} /></OptionCardGroup>`; `multiple` for a multi-select (array value). Never a row of hand-styled `<button>` tiles.\n- `ImageGallery` — `<ImageGallery images={[{ src, alt, caption? }]} layout=\"thumbs-side\" ratio=\"4:3\" zoom lightbox />`; `index` / `defaultIndex` / `onIndexChange`, `placeholder`, `showCounter`. Use it instead of wiring thumbnails to a `Carousel`.\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`, `text-primary-foreground` on a primary band,\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# motion (scroll storytelling): @dreamtree-org/twreact-ui/motion — needs nothing;\nnpm install lenis                # only for SmoothScrollProvider (optional)\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`, `QuantityStepper` (− / value / + spinbutton), `OptionCard` + `OptionCardGroup` (selectable choice tiles) |\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), `ImageGallery` (product photos: thumbnails / mosaic, swipe, zoom, lightbox) |\n| **Blocks**      | `AppShell`, `PageHeader`, `StatCard`, `StatusPill`, `EmptyState`, `ErrorState`, `LoadingState`, `ConfirmDialog`, `BottomActionBar` (+ `BottomActionBar.Spacer`), `ProductCard` (storefront product tile) — 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| **Motion** (`@dreamtree-org/twreact-ui/motion`, optional peer `lenis`) | `ScrollStage`, `Reveal`, `RevealGroup`, `LogoMarquee`, `CountUp`, `StatStrip`, `StackedCards`, `DeviceFrame`, `DeviceMorphHero`, `BentoExpandGrid`, `TestimonialSpotlight`, `PhotoCollage`, `RotatingBadge`, `SmoothScrollProvider`, hooks `useScrollProgress`, `useSmoothScroll` — scroll-storytelling sections for landing pages; 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` (`Button` also has `link`, a text link coloured by `tone`)\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. `navOpen` / `onNavOpenChange` control the drawer (a FootNav \"More\" tab can open it — never click the menu button by `aria-label`); `topbarFrom=\"below-lg\"` drops the top bar on desktop. `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`). Put a `ProgressBar`, a line of text or a `Button variant=\"link\"` in `children` (rendered under the value); `tinted` draws the whole card in `tone` (an overdue card). Don't rebuild a KPI card from `Card`.\n- `ProductCard` — storefront tile: `images` (cover first) + `imageRatio` + `hover` (`zoom` / `second-image`), `eyebrow`, `title`, `meta`, `badges`, `price` / `compareAtPrice` (INR by default, discount computed; `priceFormatter`), `href` / `to` / `as` (the title is the one stretched link), `actions`, `selectable` + `selected` + `onSelectedChange` (compare), `layout=\"row\"` for phone lists.\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>`. For an inline text action (\"All payments →\") use `variant=\"link\"` (+ `tone=\"error\"` etc.), not a restyled ghost button.\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- `QuantityStepper` — cart / buy-box quantity: `<QuantityStepper label=\"Quantity\" value={qty} min={1} max={stock} onChange={setQty} />` (`onChange` gets a number). `step`, `size`, `loading`, `hideLabel`, `formatValue`, `name`. Never an `Input type=\"number\"` with +/- buttons.\n- `OptionCard` / `OptionCardGroup` — choice tiles: `<OptionCardGroup value={v} onChange={setV} columns={3} aria-label=\"Template\"><OptionCard value=\"classic\" title=\"Classic\" description=\"…\" media={<Sketch />} /></OptionCardGroup>`; `multiple` for a multi-select (array value). Never a row of hand-styled `<button>` tiles.\n- `ImageGallery` — `<ImageGallery images={[{ src, alt, caption? }]} layout=\"thumbs-side\" ratio=\"4:3\" zoom lightbox />`; `index` / `defaultIndex` / `onIndexChange`, `placeholder`, `showCounter`. Use it instead of wiring thumbnails to a `Carousel`.\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- Motion (`/motion`) — landing-page storytelling. `ScrollStage length={300}` pins its child while the page scrolls (CSS reads `var(--dt-p, 1)`, always with the `1` fallback = final state); `useScrollProgress(ref, { mode: 'view' | 'pin' })` for custom scenes. `Reveal effect=\"fade-up|fade|scale|clip|split-words\"` / `RevealGroup stagger={80}` for entrances. `LogoMarquee items={['Acme', { src, alt }]} speed={40}`; `StatStrip items={[{ value: 500, suffix: '+', label: 'Projects' }]}` (or one `CountUp value`); `StackedCards items={[{ kicker, title, body, bullets, metric: { value, label }, cta, media: { src, alt } }]} tilt={1}`; `DeviceMorphHero media={{ video, poster, alt }} device=\"phone\" content={<Copy />}`; `DeviceFrame device=\"browser\" url=\"…\"` for a static mock-up; `BentoExpandGrid items={[{ media: { src, alt }, title, tag, client, href }]}`; `TestimonialSpotlight items={[{ quote, name, role, logo }]}`; `PhotoCollage images chips badge={<RotatingBadge text=\"BRAND • SINCE 2012 • \" />}`. Smooth scroll is opt-in: `import Lenis from 'lenis'` and wrap the page in `<SmoothScrollProvider lenis={Lenis}>`; `useSmoothScroll().scrollTo('#id')` works with or without it. Everything renders its final state on the server and under reduced motion — don't add your own `prefers-reduced-motion` handling, and never fake counters with \"0\" in the markup.\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`, `text-primary-foreground` on a primary band,\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### Motion (optional entry point)\n\n```jsx\nimport { DeviceMorphHero, LogoMarquee, StatStrip, StackedCards, Reveal } from '@dreamtree-org/twreact-ui/motion';\n\n<DeviceMorphHero media={{ video: '/intro.mp4', poster: '/intro.jpg', alt: 'Product tour' }} device=\"phone\" content={<HeroCopy />} />\n<LogoMarquee items={clients} speed={40} />\n<StatStrip items={[{ value: 500, suffix: '+', label: 'Projects' }, { value: 14, label: 'Years' }]} />\n<Reveal as=\"h2\" effect=\"split-words\" className=\"text-page-title\">What we do</Reveal>\n<StackedCards items={pillars} stickyTop={80} tilt={1} />\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 optional entry points `@dreamtree-org/twreact-ui/charts`,\n   `@dreamtree-org/twreact-ui/rich-text` (each needs its peer installed) and\n   `@dreamtree-org/twreact-ui/motion` (no peer; `lenis` only for smooth scroll).\n   Don't suggest `@dreamtree-org/twreact-ui/src/components/core/Button`, and\n   never import charts, `RichTextEditor` or the motion components 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"
 }