@dreamtree-org/twreact-ui 1.3.0 → 1.3.1

package/README.md

@@ -64,6 +64,45 @@ 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. 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`.
+
 ## Quick Start
 
 ```jsx
@@ -147,7 +186,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 +211,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 +237,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 +282,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 +316,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 +325,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 +339,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 +388,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 +421,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 +461,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 +484,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 +551,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 +680,35 @@ 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)} />
+```
+
 ### Page blocks
 
 Page-level patterns extracted from the Dreamtree products. Build pages from these before composing layouts by hand.
@@ -590,6 +732,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.
@@ -626,6 +791,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

@@ -63,6 +63,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,10 +107,10 @@ 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 |
 
 ### Hooks
@@ -111,7 +119,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 +157,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 +171,22 @@ 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.
+- `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 +235,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,14 +306,23 @@ 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.).