@dreamtree-org/twreact-ui 1.2.1 → 1.3.1

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,11 @@ 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
 
@@ -110,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
@@ -148,14 +157,51 @@ 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.
 
 When suggesting a component or new variant value, use this exact vocabulary.
 
+## Page blocks and design tokens
+
+**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
+palette (`bg-blue-500`). A product re-themes by loading `dist/tokens/brands/<brand>.css`.
+The full rule set for screens is `DESIGN.md` in the package root.
+
+```jsx
+<PageHeader title="Compliance calendar" actions={<Button>Add obligation</Button>} />
+<div className="grid grid-cols-2 gap-4 lg:grid-cols-4">
+  <StatCard label="Due this week" value={18} icon={<CalendarDays className="h-6 w-6" />} />
+  <StatCard label="Overdue" value={3} tone="error" icon={<AlertCircle className="h-6 w-6" />} />
+</div>
+<Card>{loading ? <LoadingState /> : error ? <ErrorState onRetry={retry} /> : rows.length ? <Table … /> : <EmptyState title="No obligations yet" />}</Card>
+```
+
 ## Canonical examples
 
 ### Button
@@ -189,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>
   );
 }
 
@@ -229,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.).