@dreamtree-org/twreact-ui 1.3.0 → 1.3.2

package/DESIGN.md

@@ -41,7 +41,7 @@ rounded:
 spacing:
   grid: 4px
   steps: [4, 8, 12, 16, 20, 24, 32]
-brands: [default, practicepro]
+brands: [default, practicepro, studio]
 ---
 
 <!-- Generated by twreact-ui scripts/build-tokens.mjs from tokens/tokens.json. Edit the tokens or this generator, not this file. -->
@@ -76,7 +76,7 @@ Every Dreamtree product screen, and every prototype generated by Dreamtree Studi
 
 - **One accent per screen.** `primary` marks the primary action, the active nav item, the current step and progress. Red (`error`) is only for errors, overdue items and destructive actions.
 - Badge and status fills use the 100 step with 800 text, which keeps contrast at or above 4.5:1.
-- Products change their look with a **brand file** (`tokens/brands/<product>.json`), which overrides `--dt-*` variables. Brands available: `default`, `practicepro`.
+- Products change their look with a **brand file** (`tokens/brands/<product>.json`), which overrides `--dt-*` variables. Brands available: `default`, `practicepro`, `studio`.
 
 ## 3. Type, space and shape
 

package/README.md

@@ -64,6 +64,67 @@ npm install @dreamtree-org/twreact-ui
 yarn add @dreamtree-org/twreact-ui
 ```
 
+Import the stylesheet once (app entry or root layout):
+
+```js
+import '@dreamtree-org/twreact-ui/dist/index.css';
+```
+
+### Bundle size and tree-shaking
+
+Import from the package root. Bundlers (Vite, webpack 5, esbuild, Rollup, Next.js) resolve it to a
+per-module ES build (`dist/esm/`, via the `module` field and the `module` export condition), and the
+package declares `"sideEffects": ["**/*.css"]`, so only the components you import end up in your
+bundle. `import { Button } from '@dreamtree-org/twreact-ui'` costs about 8 KB gzip, down from about
+100 KB. `require()`, Jest and plain Node keep getting the CommonJS build (`dist/index.js`).
+
+There are no per-component subpaths such as `@dreamtree-org/twreact-ui/button`. The root import
+already tree-shakes. The only subpaths are the two **optional entry points** below, which exist
+because they need an extra dependency. Existing file paths (`dist/index.css`, `dist/tokens/*`, `tokens/*`,
+`dist/index.esm.js`, `package.json`, …) still resolve through the `exports` map.
+
+### Next.js App Router
+
+Every module that uses React starts with `'use client'`, so Server Components can import
+components directly. You no longer need a `"use client"` wrapper file that re-exports the library:
+
+```tsx
+// app/page.tsx — a Server Component
+import { Button, cn } from '@dreamtree-org/twreact-ui';
+
+export default function Page() {
+  return <Button className={cn('mt-4')}>Save</Button>;
+}
+```
+
+`cn`, `Helpers` and `Emitter` carry no directive, so they also run on the server. Two React
+Server Component rules still apply. You cannot pass functions (`onClick`, `render`, …) from a
+Server Component to these Client Components. You also cannot dot into a client export, so
+`<Card.Header>`, `<Tabs.List>` and `<Dialog.Footer>` must be used inside a `'use client'` file.
+In Vite, Rollup can log `Module level directives cause errors when bundled, "use client" … was ignored`.
+This message is harmless. To hide it, filter `MODULE_LEVEL_DIRECTIVE` in `build.rollupOptions.onwarn`.
+
+### Optional entry points: charts and rich text
+
+Charts and the rich-text editor wrap third-party libraries, so they live on their own entry points
+and use **optional peer dependencies**. If you never import them you install nothing extra, and
+nothing changes in your bundle — the root `@dreamtree-org/twreact-ui` import never touches them.
+
+| Entry point | Exports | Install first |
+|---|---|---|
+| `@dreamtree-org/twreact-ui/charts` | `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, `Sparkline` | `npm install recharts` (recharts 2.15+ or 3.x; React 18 apps also `npm install react-is@18`) |
+| `@dreamtree-org/twreact-ui/rich-text` | `RichTextEditor` | `npm install @tiptap/react @tiptap/pm @tiptap/starter-kit` (Tiptap 3) |
+
+```jsx
+import { LineChart, DonutChart } from '@dreamtree-org/twreact-ui/charts';
+import { RichTextEditor } from '@dreamtree-org/twreact-ui/rich-text';
+```
+
+Both ship ESM (with `'use client'`), CommonJS and TypeScript declarations, and resolve under every
+TypeScript `moduleResolution` (`bundler`, `node16`/`nodenext` and legacy `node`). Their styles are
+already in `dist/index.css`. Rich-text output is HTML from the user — **sanitize it on the server**
+before you store or render it (see [doc/RichTextEditor.md](doc/RichTextEditor.md#security-sanitize-the-html-on-the-server)).
+
 ## Quick Start
 
 ```jsx
@@ -147,7 +208,7 @@ Versatile button component with multiple variants and states.
 
 **Props:**
 - `variant`: 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'success' | 'warning' (default: 'primary')
-- `size`: 'sm' | 'md' | 'lg' (default: 'md')
+- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' (default: 'md') — heights h-7 / h-8 / h-10 / h-12 / h-14 / h-16
 - `disabled`: boolean
 - `loading`: boolean
 - `leftIcon`: ReactNode
@@ -172,6 +233,7 @@ Enhanced text input with validation states, icons, and clear functionality.
 - `placeholder`: string
 - `error`: string
 - `success`: string
+- `helperText`: ReactNode — hint below the input, linked via `aria-describedby`; replaced by `error` / `success` while shown
 - `disabled`: boolean
 - `required`: boolean
 - `clearable`: boolean
@@ -197,17 +259,18 @@ Enhanced text input with validation states, icons, and clear functionality.
 Advanced select component with search, multi-select, and grouping support.
 
 **Props:**
-- `options`: Array<{value: any, label: string, disabled?: boolean}>
+- `options`: Array<{value: any, label: string, disabled?: boolean, group?: string}> (with `grouped`: also `[{ label, options }]` groups)
 - `value`: any | Array<any>
 - `onChange`: (value: any) => void
 - `placeholder`: string (default: 'Select an option...')
-- `label`: string
+- `label`: string — associated with the trigger (accessible name = label + value)
 - `error`: string
+- `helperText`: ReactNode — hint below the control; replaced by `error` while shown
 - `disabled`: boolean
 - `required`: boolean
 - `multiSelect`: boolean
 - `searchable`: boolean
-- `grouped`: boolean
+- `grouped`: boolean — groups objects or flat options with a `group` key; malformed input is skipped (console warning), never thrown
 - `creatable`: boolean
 - `onCreateOption`: (value: string) => void
 - `onSearch`: (term: string) => void
@@ -241,6 +304,8 @@ Declarative form builder with validation support.
 - `resetText`: string (default: 'Reset')
 - `showReset`: boolean (default: true)
 
+Field types: `text`, `email`, `password`, `number`, `tel`, `url`, `select`, `date`, `textarea`, `checkbox`, `radio`, `file`, `switch`, `color` (mounts `ColorPicker`; accepts `swatches` / `showAlpha`), `custom`. Every field accepts `helperText` (hint under the field; the validation error replaces it while shown).
+
 ```jsx
 const formFields = [
   {
@@ -273,7 +338,8 @@ actions, and expandable row details.
 - `data`: Array<object>
 - `columns`: Array<Column>
 - `sortable`: boolean (default: true)
-- `filterable`: boolean
+- `filterable`: boolean — per-column filter inputs; filter client-side data as you type (not in `serverSide` mode)
+- `globalSearch`: boolean — search box; filters client-side data with or without `filterable` (skips `searchable: false` columns)
 - `selectable`: boolean
 - `pagination`: boolean
 - `pageSize`: number (default: 25)
@@ -281,7 +347,7 @@ actions, and expandable row details.
 - `onFilter`: (filters: object) => void
 - `onSelectionChange`: (selectedRows: object[]) => void
 - `onRowClick`: (row: object, index: number) => void
-- `onPageChange`: (page: number) => void
+- `onPageChange`: (page: number) => void — also called when the table clamps a page that no longer exists after the data shrinks
 - `hasDetails`: boolean | ((row, index) => boolean)
 - `DetailsComponent`: ReactComponent
 - `withAction`: boolean (default: true)
@@ -295,6 +361,15 @@ actions, and expandable row details.
 - `onSave`: ({ updatedRows, newRows, allData, tableData }) => void | Promise<allData | { data: allData } | void>
 - `onEdit`: ({ rowKey, colKey, newValue, row, action, isNew }) => void
 - `showSerial`: boolean (default: true)
+- `showToolbar`: boolean (default: true) — `false` hides the toolbar (reload, page size, result count, pager header) and the column picker; interactive save controls still render
+- `showColumnPicker`: boolean (default: true) — hide just the column-picker button and its column
+- `wrapCells`: boolean (default: false) — let every cell wrap; a column's own `wrap` wins
+- `mobileMaxFields`: number — cap the fields shown on each mobile card (column order, after `hideOnMobile`)
+- `serverSide` / `totalRecords`: in server-side mode the "start - end of total" counter reads `totalRecords`
+
+Column extras: `searchable: false` keeps a column out of the global search
+(ids, codes), `wrap: true` lets its text wrap instead of staying on one line, and
+`hideOnMobile: true` leaves it off the mobile card view (desktop is unaffected).
 
 An `Action` is `{ name, label, icon, render?, onClick?, hidden?, disabled?,
 inline? }`. `label`, `icon`, `hidden` and `disabled` each accept a value **or** a
@@ -335,6 +410,7 @@ Calendar-based date selection with keyboard navigation.
 - `placeholder`: string (default: 'Select date...')
 - `label`: string
 - `error`: string
+- `helperText`: ReactNode — hint below the trigger; replaced by `error` while shown
 - `disabled`: boolean
 - `required`: boolean
 - `minDate`: Date | string
@@ -367,22 +443,31 @@ Collapsible sidebar navigation with nested items.
 - `logo`: ReactNode
 - `user`: {name: string, email: string, avatar?: string, menuItems?: Array<MenuItem>}
 - `onUserClick`: (user: object) => void
+- `linkAs`: ElementType (default: `"a"`) — e.g. Next.js `Link`
+- `expandedIds` / `defaultExpandedIds`: string[] — open groups (controlled / uncontrolled); `onExpandedChange`: (ids: string[]) => void
+- `footer`: ReactNode | ({ collapsed, isMobile, closeMobile }) => ReactNode — pinned region above the user block
+- `stickyOffset`: number | string — height of a top bar above the sidebar (sticks below it, fits the viewport); `containerClassName` for the outer sticky wrapper
+- `isMobileOpen` / `setIsMobileOpen`: mobile drawer — inert while closed; focus-trapped, Escape-to-close and focus-restoring while open
+
+Every item renders as an `<a>`. Give an item an `href` and it becomes a real link, so Ctrl/Cmd-click or middle-click opens it in a new tab. Parents with an `href` navigate and expand; their chevron toggles without navigating. The group holding an `active: true` item (any depth) opens on load. Items take `badge` (+ accessible `badgeLabel`) and top-level `group` (section heading, a divider when collapsed — same as `AppShell`). With `onUserClick` the user block is a real `<button>`.
 
 ```jsx
 const sidebarItems = [
   {
     id: 'dashboard',
     label: 'Dashboard',
+    href: '/dashboard',
     icon: <Home className="h-4 w-4" />,
     active: true
   },
   {
     id: 'users',
     label: 'Users',
+    href: '/users',
     icon: <Users className="h-4 w-4" />,
     children: [
-      { id: 'all-users', label: 'All Users' },
-      { id: 'new-user', label: 'Add New User' }
+      { id: 'all-users', label: 'All Users', href: '/users' },
+      { id: 'new-user', label: 'Add New User', href: '/users/new' }
     ]
   }
 ];
@@ -398,9 +483,10 @@ const sidebarItems = [
 Top navigation bar with user menu and notifications.
 
 **Props:**
-- `logo`: ReactNode
+- `logo`: ReactNode (truncates on narrow screens)
+- `center`: ReactNode — centre slot (e.g. a search field); shrinks first so the bar fits a 390px phone
 - `items`: Array<NavItem>
-- `user`: {name: string, email: string, avatar?: string, menuItems?: Array<MenuItem>}
+- `user`: {name: string, email: string, avatar?: string, menuItems?: Array<MenuItem>} — without `avatar`, the menu shows `name` initials; below `sm` the logout icon moves into the user menu as "Sign out"
 - `notifications`: Array<Notification>
 - `searchable`: boolean
 - `onSearch`: (term: string) => void
@@ -420,6 +506,38 @@ Top navigation bar with user menu and notifications.
 />
 ```
 
+#### FootNav
+Fixed bottom tab bar for phones (`md:hidden`). Uses the semantic `bg-surface` / `border-line` tokens, so it follows dark mode.
+
+**Props:**
+- `items`: Array<{ id, label, icon, onClick?, active?, badge? }>
+- `className`: string
+
+The `active` item gets a tinted primary background, `text-primary-700` and `aria-current="page"` (inactive tabs are neutral `text-muted`). Badges sit on their own item's icon. Items share the width and labels truncate, so five tabs fit a 375px screen.
+
+```jsx
+<FootNav
+  items={[
+    { id: 'home', label: 'Home', icon: <Home />, active: true, onClick: () => navigate('/') },
+    { id: 'inbox', label: 'Inbox', icon: <Inbox />, badge: 3, onClick: () => navigate('/inbox') },
+  ]}
+/>
+```
+
+#### Breadcrumbs
+Breadcrumb trail with an optional Home link.
+
+**Props:**
+- `items`: Array<{ id?, label, href?, icon?, onClick? }> — `id` is optional (used as the React key when present)
+- `separator`: ReactNode
+- `showHome`: boolean (default: true)
+- `homeIcon`: ReactNode
+- `onHomeClick`: () => void
+
+```jsx
+<Breadcrumbs items={[{ label: 'Projects', href: '/projects' }, { label: 'Alpha' }]} />
+```
+
 ### Feedback Components
 
 #### Alert
@@ -455,6 +573,23 @@ Notification messages with different types, actions, bottom progress bar, and po
 - `onClose`: (id: string) => void
 - `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center'
 
+**App-level provider (recommended).** Wrap the app once in `ToastProvider`; every `useToast()` below it shares one queue and the provider renders it — no per-screen `ToastContainer`:
+
+```jsx
+import { ToastProvider, useToast } from '@dreamtree-org/twreact-ui';
+
+<ToastProvider position="top-right">
+  <App />
+</ToastProvider>;
+
+function SaveButton() {
+  const { toast } = useToast();
+  return <button onClick={() => toast.success('Saved')}>Save</button>;
+}
+```
+
+**Standalone (no provider).** Outside a provider each `useToast()` owns its own queue; render it with `ToastContainer`. Under a provider, a `ToastContainer` handed the provider's own `toasts` renders nothing, so it never double-renders while you migrate.
+
 ```jsx
 import { useToast, ToastContainer } from '@dreamtree-org/twreact-ui';
 
@@ -567,6 +702,90 @@ const tabItems = [
 <Tabs items={tabItems} variant="pills" />
 ```
 
+### Overlays, inputs and lists
+
+Interaction primitives that products used to compose by hand. All are `forwardRef`, accept `className` + `...rest`, are keyboard-operable with explicit ARIA, dark-mode aware and respect `prefers-reduced-motion`.
+
+| Component | Group | Use for |
+|---|---|---|
+| [`Drawer`](doc/Drawer.md) | Feedback | Side/edge sheet (`placement` right/left/top/bottom, `size` sm–full) — record peeks and editors. Same `isOpen`/`onClose` contract as `Dialog`; focus trap, Escape/backdrop close, focus restore, scroll lock; `Drawer.Header/Body/Footer` |
+| [`Popover`](doc/Popover.md) | Core | Anchored, click-triggered panel with interactive content (unlike `Tooltip`). Controlled/uncontrolled `open`, `placement` with flip, Escape/outside-click close, `aria-expanded`/`aria-controls`/`aria-haspopup="dialog"` |
+| [`Textarea`](doc/Textarea.md) | Core | Multi-line input mirroring `Input`: `label`, `error`, `helperText`, `required`, `showCount`/`maxLength`, `autoResize`/`maxRows` |
+| [`Slider`](doc/Slider.md) | Core | Single value or `[low, high]` range; `min`/`max`/`step`, arrows/PageUp/PageDown/Home/End, `role="slider"` with full `aria-value*` |
+| [`Sortable`](doc/Sortable.md) | Utility | Drag-to-reorder list (pointer events, no extra dependency) + keyboard reordering (Space, arrows, Space/Escape) with live announcements; `items`, `onReorder`, `renderItem`, `getKey` |
+| [`Tour`](doc/Tour.md) | Feedback | Step-based onboarding: spotlight on each `target` (selector or ref), Back/Next/Skip/Finish, `open`/`onClose`/`onFinish`, scrolls targets into view |
+
+```jsx
+import { Drawer, Popover, Textarea, Slider, Sortable, Tour, Button } from '@dreamtree-org/twreact-ui';
+
+<Drawer isOpen={open} onClose={() => setOpen(false)} title="Edit task" footer={<Button onClick={save}>Save</Button>}>
+  <Textarea label="Description" autoResize showCount maxLength={500} />
+</Drawer>
+
+<Popover trigger={<Button variant="outline">Filters</Button>} title="Filters">
+  <Slider label="Budget" defaultValue={[2000, 8000]} min={0} max={10000} step={500} showValue />
+</Popover>
+
+<Sortable aria-label="Backlog" items={tasks} onReorder={setTasks} renderItem={(t) => t.title} />
+
+<Tour open={tourOpen} steps={[{ title: 'Welcome' }, { target: '[data-tour="new-task"]', title: 'Capture work' }]} onClose={() => setTourOpen(false)} />
+```
+
+### Charts (optional entry point)
+
+Import from `@dreamtree-org/twreact-ui/charts` after `npm install recharts`. A data-first API over
+recharts: pass rows as `data`, the x-axis key as `index` and the series keys as `categories`.
+Colours are design tokens (`'primary'`, `'success-600'`, …) resolved from the `--dt-*` variables,
+so charts follow your theme and dark mode. Every chart is responsive, `forwardRef` + `className` +
+`...rest`, a named `role="img"` (`title` / `description`) with a visually-hidden data table for
+screen readers (`accessibleTable`), shows `emptyState` for empty data, and disables animation under
+`prefers-reduced-motion`.
+
+| Component | Use for |
+|---|---|
+| [`LineChart`](doc/LineChart.md) | Trends over time (`curveType`, `showDots`, `connectNulls`) |
+| [`BarChart`](doc/BarChart.md) | Comparisons — grouped, `stacked` or `horizontal` |
+| [`AreaChart`](doc/AreaChart.md) | Volume over time, optionally `stacked` |
+| [`DonutChart`](doc/DonutChart.md) | Part-to-whole (`variant="donut"` or `"pie"`, `centerLabel`) |
+| [`Sparkline`](doc/Sparkline.md) | Word-sized trend for stat cards and table cells |
+
+Shared props: `valueFormatter`, `height`, `showLegend`, `showTooltip`, `showXAxis`, `showYAxis`,
+`showGrid`, `colors`, `animate`.
+
+```jsx
+import { LineChart, DonutChart, Sparkline } from '@dreamtree-org/twreact-ui/charts';
+
+<LineChart
+  data={[{ month: 'Jan', revenue: 4200 }, { month: 'Feb', revenue: 5100 }]}
+  index="month"
+  categories={['revenue']}
+  valueFormatter={(v) => `$${v.toLocaleString()}`}
+  title="Revenue, Jan–Feb"
+/>
+<DonutChart data={byStatus} index="status" category="tasks" centerLabel="63 tasks" title="Tasks by status" />
+<Sparkline data={weekly} category="signups" color="success" title="Signups, last 4 weeks" />
+```
+
+### Rich text (optional entry point)
+
+[`RichTextEditor`](doc/RichTextEditor.md) — import from `@dreamtree-org/twreact-ui/rich-text` after
+`npm install @tiptap/react @tiptap/pm @tiptap/starter-kit`. A Tiptap (StarterKit) field with the
+same `label` / `error` / `helperText` / `required` wiring as `Input`; controlled (`value` +
+`onChange(html)`) or uncontrolled (`defaultValue`), `outputFormat="json"` for Tiptap JSON,
+`disabled` / `readOnly`, `minHeight` / `maxHeight`, and a `toolbar` (bold, italic, strike, code,
+headings, lists, quote, link, undo/redo) that is a `role="toolbar"` of real buttons with
+`aria-pressed` and arrow-key roving focus. The `ref` is an imperative handle (`editor`, `focus()`,
+`getHTML()`, `getJSON()`, `setContent()`, `clear()`). SSR-safe: the editor mounts on the client.
+
+```jsx
+import { RichTextEditor } from '@dreamtree-org/twreact-ui/rich-text';
+
+<RichTextEditor label="Description" placeholder="Describe the task…" value={html} onChange={setHtml} maxHeight={320} />
+```
+
+> The HTML comes from the user. Sanitize it on the server (e.g. DOMPurify / `sanitize-html`) before
+> storing or rendering it; this library ships no sanitizer.
+
 ### Page blocks
 
 Page-level patterns extracted from the Dreamtree products. Build pages from these before composing layouts by hand.
@@ -590,6 +809,29 @@ import { PageHeader, StatCard, StatusPill, EmptyState, Button } from '@dreamtree
 
 Component types now carry their props (`<Button variant="bogus" />` is a type error).
 
+### Hooks
+
+#### useApi
+Thin axios wrapper. Returns `{ data, error, loading, lastRequest, fetchData, fetchApi, fetchApiWith }`.
+
+- `fetchApi(key, data?, needLoading?)` calls `apiMap[key](data)` with **one** argument.
+- `fetchApiWith(key, args, { needLoading }?)` spreads `args` into the map entry — use it for entries like `(id, body) => ({...})`.
+
+```jsx
+const { fetchApi, fetchApiWith } = useApi({
+  BASE_URL: 'https://api.example.com',
+  apiMap: {
+    getUser: (id) => ({ url: `/users/${id}`, method: 'GET' }),
+    updateUser: (id, body) => ({ url: `/users/${id}`, method: 'PUT', data: body }),
+  },
+});
+
+fetchApi('getUser', 7);
+fetchApiWith('updateUser', [7, { name: 'Ada' }]);
+```
+
+See [doc/useApi.md](doc/useApi.md).
+
 ## Theming
 
 Every colour in the compiled CSS is a CSS variable (`--dt-primary-600`, `--dt-surface`, …) generated from `tokens/tokens.json` (W3C Design Tokens format). The defaults equal the classic palette, so nothing changes until you override a variable.
@@ -601,6 +843,8 @@ Every colour in the compiled CSS is a CSS variable (`--dt-primary-600`, `--dt-su
 @import "@dreamtree-org/twreact-ui/dist/tokens/brands/practicepro.css"; /* or your own --dt-* overrides */
 ```
 
+Shipped brands: `default`, `practicepro`, `studio` (Dreamtree Studio's own pages).
+
 **Use the same tokens in your own classes:**
 
 ```js
@@ -626,6 +870,10 @@ This adds semantic utilities next to the palettes: `bg-surface`, `bg-background`
 
 **Design rules:** [`DESIGN.md`](DESIGN.md) is the rule set for product screens and AI agents: tokens only, blocks first, loading, empty and error states, 390 px, no native dialogs. It is generated from the tokens (`npm run build:tokens`).
 
+**Colour props are overrides, not defaults.** Without colour props, `ProgressBar`, `Checkbox`, `Rate` and `Skeleton` use token classes, so a brand file recolours them. Their HEX props (`color`, `bgColor`, `borderColor`, `activeColor`, `inactiveColor`) still work but are deprecated.
+
+**SSR:** `Tabs`, `Tooltip` and `Switch` generate ids with `React.useId()`, so server-rendered pages (Next.js) hydrate without mismatches.
+
 ## Dark Mode
 
 Enable dark mode with the built-in theme provider:

package/ai-skills/dreamtree-ui.md

@@ -29,6 +29,17 @@ npm install react react-dom
 `react` / `react-dom` are **peer dependencies** at `^18.3.1`. React 19
 is not yet supported.
 
+**Optional entry points** — install the peer only when the user needs it:
+
+```bash
+# charts: @dreamtree-org/twreact-ui/charts
+npm install recharts            # React 18 apps also: npm install react-is@18
+# rich text: @dreamtree-org/twreact-ui/rich-text
+npm install @tiptap/react @tiptap/pm @tiptap/starter-kit
+```
+
+Apps that don't import these subpaths install and bundle nothing extra.
+
 ## Wiring (do not invent alternatives)
 
 ```jsx
@@ -63,6 +74,14 @@ module.exports = {
 };
 ```
 
+Import from the package root only (`import { Button } from '@dreamtree-org/twreact-ui'`).
+The root import tree-shakes, so do not suggest deep paths into `dist/` or `src/` for components.
+
+**Next.js App Router:** components ship with `'use client'`, so a Server Component can import
+them directly. Do not generate a `"use client"` wrapper file that re-exports the library.
+Compound members (`Card.Header`, `Tabs.List`, `Dialog.Footer`) and function props (`onClick`)
+still require a `'use client'` file. `cn`, `Helpers` and `Emitter` also work on the server.
+
 ## Live prop contracts via MCP (prefer this over guessing)
 
 An **MCP server bundled in this package** serves the authoritative prop
@@ -99,11 +118,13 @@ The library exports four kinds of things from `@dreamtree-org/twreact-ui`:
 
 | Group           | Components                                                                                                                                                                                                                  |
 | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **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` |
+| **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` |
 | **Navigation**  | `Sidebar`, `Navbar`, `FootNav`, `Breadcrumbs`                                                                                                                                                                              |
-| **Feedback**    | `Dialog`, `Toast` (+ `ToastContainer`, `useToast`), `Alert`                                                                                                                                                                |
-| **Utility**     | `Badge`, `Avatar`, `Card`, `Pagination`, `Stepper`, `FileUpload`, `Condition`, `Carousel`                                                                                                                                  |
+| **Feedback**    | `Dialog`, `Toast` (+ `ToastProvider`, `ToastContainer`, `useToast`), `Alert`, `Drawer` (side sheet; `isOpen`/`onClose` like Dialog), `Tour` (onboarding spotlight) |
+| **Utility**     | `Badge`, `Avatar`, `Card`, `Pagination`, `Stepper`, `FileUpload`, `Condition`, `Carousel`, `Sortable` (drag + keyboard reorder) |
 | **Blocks**      | `AppShell`, `PageHeader`, `StatCard`, `StatusPill`, `EmptyState`, `ErrorState`, `LoadingState`, `ConfirmDialog` — page-level patterns; build pages from these before composing layouts by hand |
+| **Charts** (`@dreamtree-org/twreact-ui/charts`, peer `recharts`) | `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, `Sparkline` — NOT exported from the root |
+| **Rich text** (`@dreamtree-org/twreact-ui/rich-text`, peers `@tiptap/react @tiptap/pm @tiptap/starter-kit`) | `RichTextEditor` — NOT exported from the root |
 
 ### Hooks
 
@@ -111,7 +132,7 @@ The library exports four kinds of things from `@dreamtree-org/twreact-ui`:
 | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | `useTheme`      | Read/write the current theme (`light | dark`); pairs with `<ThemeProvider>`. Throws if used outside the provider.                              |
 | `ThemeProvider` | Provider that persists theme to `localStorage` (`dreamtree-theme`) and toggles `data-theme` on `<html>`.                                       |
-| `useApi`        | Thin axios wrapper. Returns `{data, error, loading, sendRequest}`. Accepts `BASE_URL`, `DEFAULT_HEADERS`, `apiMap`.                            |
+| `useApi`        | Thin axios wrapper. Returns `{data, error, loading, lastRequest, fetchData, fetchApi, fetchApiWith}`. Accepts `BASE_URL`, `DEFAULT_HEADERS`, `apiMap`. |
 | `useMixins`     | Bridge between component state, Redux store, and an in-memory cache. Power-user hook — prefer local React state for new code.                  |
 
 ### Store
@@ -149,8 +170,9 @@ Components use a **shared variant/size/focus vocabulary**:
 
 - **Variants:** `primary | secondary | outline | ghost | destructive | success | warning`
   (component-specific extras like `Badge: info` and `Alert: neutral` are documented per-component).
-- **Sizes:** `xs | sm | md | lg | xl` mapping to heights `h-7 / h-8 / h-10 / h-12 / h-14`
-  and padding `px-2 / px-3 / px-4 / px-6 / px-8` (a component MAY support a subset).
+- **Sizes:** `xs | sm | md | lg | xl | 2xl` mapping to heights `h-7 / h-8 / h-10 / h-12 / h-14 / h-16`
+  and padding `px-2 / px-3 / px-4 / px-6 / px-8 / px-10` (`Button` implements all six;
+  other components MAY support a subset and fall back to `md`).
 - **Focus ring:** `focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-primary-500`
   (the color token swaps for destructive / etc.).
 - **Dark mode:** Tailwind `darkMode: 'class'`. Every color choice has a `dark:` counterpart.
@@ -162,12 +184,24 @@ When suggesting a component or new variant value, use this exact vocabulary.
 **Blocks** are page-level patterns extracted from the products, so screens stop re-inventing them:
 
 - `AppShell` — sidebar + top bar + mobile drawer; pass `nav` items and `linkAs={Link}` in Next.js.
+- `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 and closes on Escape.
 - `PageHeader` — the page's only `h1`, subtitle, one primary action, optional `back` link.
 - `StatCard` — KPI tile (`label`, `value`, `icon`, `tone`, `change`).
 - `StatusPill` — map domain states to `{ label, tone }` once; unknown states are humanized, never raw.
 - `EmptyState`, `ErrorState`, `LoadingState` — every data card needs all three.
 - `ConfirmDialog` — use instead of `window.confirm()`; title is the question, button is the verb.
 
+**Interaction primitives** — reach for these before hand-rolling the pattern:
+
+- `Drawer` — side/edge sheet for record peeks and editors (`isOpen`, `onClose`, `title`, `placement`, `size`, `footer`); don't fake one with `Dialog size="lg"`.
+- `Popover` — click-triggered panel with controls (`trigger={<Button>…</Button>}`, children or `({ close }) => …`); `Tooltip` is for read-only hover text only.
+- `Textarea` — same API as `Input` plus `autoResize`/`maxRows`; never a raw `<textarea>`.
+- `Slider` — `defaultValue={40}` for one thumb, `[low, high]` for a range; `onChangeEnd` to save after a drag.
+- `Sortable` — `items` + `onReorder(newItems)` + `renderItem`; keyboard reordering and announcements are built in. Pass `handle` and spread `handleProps` on a grip for touch screens.
+- Charts (`/charts`) — `<LineChart data={rows} index="month" categories={['revenue', 'costs']} />`; same shape for `BarChart` (`stacked`, `horizontal`) and `AreaChart` (`stacked`); `DonutChart` takes `index` (name key) + `category` (value key) + `centerLabel`; `Sparkline` takes `category` + `color`. Colours are tokens (`colors={['primary', 'success-600']}`), never hex. Always pass `title` (accessible name) and, for key charts, a `description` with the takeaway. `valueFormatter` formats tooltip/axis/table values.
+- `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.
+- `Tour` — onboarding coach marks: `steps=[{ target: '[data-tour="x"]', title, content, placement }]`, `open`, `onClose(reason)`; a missing target falls back to a centred card.
+
 **Tokens:** colours are CSS variables (`--dt-primary-600`, `--dt-surface`, …) generated from
 `tokens/tokens.json`. Use semantic classes (`bg-primary-600`, `bg-surface`, `text-foreground`,
 `text-muted`, `border-line`, `text-micro`, `rounded-card`) — never hex values or Tailwind's raw
@@ -216,17 +250,48 @@ import { Input } from '@dreamtree-org/twreact-ui';
 `Form` integrates with `react-hook-form` + `yup` (`@hookform/resolvers`).
 Validation rules live in consumer code.
 
+**Helper text:** `Input`, `Select`, `DatePicker`, `DateRangePicker` and every
+`Form` field take `helperText` (rendered below, linked via `aria-describedby`).
+While `error` is set it **replaces** the helper text — don't render both. Don't
+hand-roll a `<p>` hint under a field.
+
+```jsx
+<Select label="Role" helperText="Controls access." options={roles} value={role} onChange={setRole} />
+<Form fields={[
+  { type: 'email', name: 'email', label: 'Email', helperText: 'Receipts only.' },
+  { type: 'color', name: 'brand', label: 'Brand colour', swatches: ['#2563eb'] }, // ColorPicker
+]} />
+```
+
+`Form` field types: `text | email | password | number | tel | url | select |
+date | textarea | checkbox | radio | file | switch | color | custom`. Use
+`type: 'color'` rather than a `custom` field wrapping `ColorPicker`.
+
+**Select `grouped`** accepts `[{ label, options }]` groups **or** flat options
+with a `group` key (`{ value, label, group: 'Code' }`) — no need to pre-group.
+
+**Navbar** takes a `center` slot (search field / primary action) and shows
+`user.name` initials when `user.avatar` is missing; it fits a 390px phone.
+
+**Tooltip** around a component (e.g. `<Button>`) in a row/grid: use
+`customTrigger={<Button>…</Button>}` so there is one tab stop, not two. A lone
+native `<button>` / `<a href>` / `<input>` child is detected automatically.
+
 ### Toast
 
+Wrap the app ONCE in `ToastProvider`; every `useToast()` below it shares one
+queue and the provider renders it. (Without a provider each `useToast()` owns a
+private queue that only shows where that same hook's `toasts` are passed to a
+`<ToastContainer toasts={toasts} onRemove={removeToast} />`.)
+
 ```jsx
-import { ToastContainer, useToast } from '@dreamtree-org/twreact-ui';
+import { ToastProvider, useToast } from '@dreamtree-org/twreact-ui';
 
 function App() {
   return (
-    <>
-      <ToastContainer />
+    <ToastProvider position="top-right">
       <YourApp />
-    </>
+    </ToastProvider>
   );
 }
 
@@ -256,17 +321,45 @@ toggles `data-theme` on `<html>`.
 ```jsx
 import { useApi } from '@dreamtree-org/twreact-ui';
 
-const { data, error, loading, sendRequest } = useApi({
+const { data, error, loading, fetchData, fetchApi, fetchApiWith } = useApi({
   BASE_URL: 'https://api.example.com',
   DEFAULT_HEADERS: { Authorization: `Bearer ${token}` },
+  apiMap: {
+    getUser: (id) => ({ url: `/users/${id}`, method: 'GET' }),
+    updateUser: (id, body) => ({ url: `/users/${id}`, method: 'PUT', data: body }),
+  },
 });
 
-useEffect(() => { sendRequest('GET', '/users'); }, []);
+useEffect(() => { fetchData('/users', 'GET'); }, []);
+fetchApi('getUser', 7);                         // apiMap.getUser(7) — ONE argument
+fetchApiWith('updateUser', [7, { name: 'A' }]); // apiMap.updateUser(7, {...}) — spread
 ```
 
+`fetchApi(key, data)` always passes the map entry exactly one argument; use
+`fetchApiWith(key, [a, b])` for multi-argument entries.
+
 Treat `useApi` as a thin axios wrapper, not a caching/dedup layer. For
 cache, the consumer brings their own (React Query, SWR, etc.).
 
+### Charts and rich text (optional entry points)
+
+```jsx
+import { LineChart, DonutChart, Sparkline } from '@dreamtree-org/twreact-ui/charts';
+import { RichTextEditor } from '@dreamtree-org/twreact-ui/rich-text';
+
+<LineChart
+  data={[{ month: 'Jan', revenue: 4200 }, { month: 'Feb', revenue: 5100 }]}
+  index="month"
+  categories={['revenue']}
+  valueFormatter={(v) => `$${v.toLocaleString()}`}
+  title="Revenue, Jan–Feb"
+/>
+<DonutChart data={byStatus} index="status" category="tasks" colors={['info', 'error', 'success']} centerLabel="63 tasks" title="Tasks by status" />
+<Sparkline data={weekly} category="signups" color="success" title="Signups, last 4 weeks" />
+
+<RichTextEditor label="Description" placeholder="Describe the task…" value={html} onChange={setHtml} maxHeight={320} />
+```
+
 ### cn
 
 ```jsx
@@ -282,7 +375,7 @@ import { cn } from '@dreamtree-org/twreact-ui';
 1. **Use library components.** When the user asks for a button, input,
    table, modal, toast, navbar, sidebar, breadcrumb, badge, card,
    stepper, file uploader, date picker, color picker, location picker,
-   pagination, or carousel — reach into this library FIRST. Don't
+   pagination, carousel, chart or rich-text editor — reach into this library FIRST. Don't
    propose a hand-rolled `<div>` + Tailwind unless the library has no
    matching primitive.
 2. **Use the shared vocabulary.** `variant="primary"`, `size="md"`,
@@ -297,8 +390,11 @@ import { cn } from '@dreamtree-org/twreact-ui';
    "components render unstyled," check first whether their
    `tailwind.config.js` `content[]` includes
    `./node_modules/@dreamtree-org/twreact-ui/dist/**/*.{js,mjs}`.
-6. **Don't deep-import.** Only `@dreamtree-org/twreact-ui` is public.
-   Don't suggest `@dreamtree-org/twreact-ui/src/components/core/Button`.
+6. **Don't deep-import.** The public modules are `@dreamtree-org/twreact-ui`
+   plus the two optional entry points `@dreamtree-org/twreact-ui/charts` and
+   `@dreamtree-org/twreact-ui/rich-text` (each needs its peer installed).
+   Don't suggest `@dreamtree-org/twreact-ui/src/components/core/Button`, and
+   never import charts or `RichTextEditor` from the root.
 7. **React 18 only.** If the user is on React 19, warn them: this
    library has not yet been verified on React 19.
 8. **Accessibility-first.** Icon-only buttons need `aria-label`.

package/charts/package.json

@@ -0,0 +1,5 @@
+{
+  "main": "../dist/charts/index.js",
+  "module": "../dist/esm/charts/index.js",
+  "types": "../dist/charts/index.d.ts"
+}