@dreamtree-org/twreact-ui 1.3.10 → 2.0.0

package/README.md

@@ -68,6 +68,22 @@ npm install @dreamtree-org/twreact-ui
 yarn add @dreamtree-org/twreact-ui
 ```
 
+### Upgrading from 1.x
+
+2.0.0 removes the 1.x deprecated colour props and renames the icon props to the shared `leftIcon` / `rightIcon`. A codemod handles most of it:
+
+```bash
+npm install @dreamtree-org/twreact-ui@^2.0.0
+npx jscodeshift -t node_modules/@dreamtree-org/twreact-ui/codemods/v2.cjs src/
+```
+
+- **Input:** `icon` + `iconPosition` became `leftIcon` / `rightIcon`. A controlled Input's clear button now calls only `onClear`, so clear `value` there.
+- **`Tabs.Tab`:** `iconLeft` / `iconRight` became `leftIcon` / `rightIcon`.
+- **ProgressBar:** the HEX `color` / `bgColor` / `valueColor` props are gone; use `variant`.
+- **Checkbox / Switch / Rate:** `borderColor`, `activeColor` / `inactiveColor` and the `blue` / `indigo` / `purple` presets are gone.
+
+[`doc/MIGRATION-2.0.md`](doc/MIGRATION-2.0.md) has before/after code for each change and lists what the codemod leaves to you.
+
 Import the stylesheet once (app entry or root layout):
 
 ```js
@@ -235,7 +251,6 @@ Enhanced text input with validation states, icons, and clear functionality.
 
 **Props:**
 - `type`: 'text' | 'password' | 'email' | 'search' | 'number' | 'tel' | 'url'
-- `variant`: 'default' | 'filled' | 'outlined'
 - `size`: 'sm' | 'md' | 'lg' (default: 'md')
 - `label`: string
 - `placeholder`: string
@@ -245,12 +260,12 @@ Enhanced text input with validation states, icons, and clear functionality.
 - `disabled`: boolean
 - `required`: boolean
 - `clearable`: boolean
-- `icon`: ReactNode
-- `iconPosition`: 'left' | 'right' (default: 'left')
+- `leftIcon`: ReactNode — icon before the value (2.0: was `icon`)
+- `rightIcon`: ReactNode — icon after the value (2.0: was `icon` + `iconPosition="right"`)
 - `showCount`: boolean
 - `maxLength`: number
 - `readOnly`: boolean
-- `onClear`: () => void
+- `onClear`: () => void — called by the clear button. A **controlled** Input clears its own `value` here (2.0: no synthetic `onChange`)
 
 ```jsx
 <Input
@@ -669,6 +684,22 @@ User profile images with fallbacks and status indicators.
 />
 ```
 
+#### AvatarGroup
+Overlapping stack of avatars with a "+N" overflow tile.
+
+**Props:**
+- `max`: number. Avatars past `max` collapse into a "+N" tile
+- `size`: Avatar size passed to every child that doesn't set its own (default: 'md')
+
+```jsx
+<AvatarGroup max={3} size="sm">
+  <Avatar name="Ana" />
+  <Avatar name="Ben" />
+  <Avatar name="Cy" />
+  <Avatar name="Dee" />
+</AvatarGroup>
+```
+
 #### Badge
 Status indicators and labels with different variants.
 
@@ -677,6 +708,9 @@ Status indicators and labels with different variants.
 - `variant`: 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' | 'outline' (default: 'default')
 - `size`: 'sm' | 'md' | 'lg' (default: 'md')
 - `rounded`: boolean (default: true)
+- `dot`: boolean. A status dot before the label (default: false)
+- `icon`: ReactNode. A leading icon
+- `max`: number. A number child above `max` shows `${max}+`
 
 ```jsx
 <Badge variant="success" size="sm">
@@ -718,19 +752,31 @@ Interaction primitives that products used to compose by hand. All are `forwardRe
 | Component | Group | Use for |
 |---|---|---|
 | [`Drawer`](doc/Drawer.md) | Feedback | Side/edge sheet (`placement` right/left/top/bottom, `size` sm–full) — record peeks and editors. `placement="bottom"` is a phone bottom sheet (grab `handle`, `swipeToClose`, rounded top, safe-area padding). Same `isOpen`/`onClose` contract as `Dialog`; focus trap, Escape/backdrop close, focus restore, scroll lock; `Drawer.Header/Body/Footer` |
+| [`Sheet`](doc/Sheet.md) | Feedback | Phone-native sheet (`placement` bottom/top/left/right): `snapPoints` (viewport fractions, `activeSnap`/`defaultSnap`/`onSnapChange`), drag-to-dismiss with rubber band and flick, keyboard-aware via `visualViewport`, opt-in `scaleBackground`. `open` (or `isOpen`) + `onClose(reason)`; focus trap, Escape/backdrop close, focus restore, scroll lock; `Sheet.Header/Body/Footer`. Use for phone sheets; keep `Drawer` for record peeks |
 | [`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 |
+| [`ActionSheet`](doc/ActionSheet.md) | Feedback | iOS action sheet on `Sheet`: `actions=[{ key?, label, icon?, tone?: 'default' | 'destructive', disabled?, onSelect }]`, optional `title`/`message`, a separate Cancel button, `onClose(reason)` |
+| [`SegmentedControl`](doc/SegmentedControl.md) | Core | Radiogroup view toggle (list/board, day/week): `options`, `value`/`defaultValue` + `onChange`, `size`, `fullWidth`, `name` for forms; arrow keys move the selection. Use `Tabs variant="segmented"` when the choice switches panels |
+| [`SwipeableListItem`](doc/SwipeableListItem.md) | Core | Mail-style swipe-to-reveal row: `leadingActions`/`trailingActions`, `fullSwipe` commits the outer action, controlled `open`; a "More actions" button reaches every action without gestures. Table cards take `swipeActions` |
+| [`SearchField`](doc/SearchField.md) | Core | iOS-style search input: clear button, phone Cancel, `onValueChange`/`onSearch`; `results`/`renderResults` show in a Sheet on phones and a popover elsewhere (`presentation`) |
+| [`PullToRefresh`](doc/PullToRefresh.md) | Utility | Touch pull-to-refresh around a scroller: `onRefresh` returns a promise, `threshold`, `maxPull`, `disabled`, `scrollRef` |
+| [`BottomActionBar`](doc/BottomActionBar.md) | Block | Sticky bottom bar for a form's primary action: `pb-safe`, rides above the on-screen keyboard (`keyboardAware`), `stackOnMobile`; add `<BottomActionBar.Spacer />` at the end of the page |
 
 ```jsx
-import { Drawer, Popover, Textarea, Slider, Sortable, Tour, Button } from '@dreamtree-org/twreact-ui';
+import { Drawer, Sheet, 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>
 
+<Sheet open={filtersOpen} onClose={() => setFiltersOpen(false)} title="Filters" snapPoints={[0.5, 1]}>
+  <Sheet.Body>…</Sheet.Body>
+  <Sheet.Footer><Button onClick={apply}>Apply</Button></Sheet.Footer>
+</Sheet>
+
 <Popover trigger={<Button variant="outline">Filters</Button>} title="Filters">
   <Slider label="Budget" defaultValue={[2000, 8000]} min={0} max={10000} step={500} showValue />
 </Popover>
@@ -841,6 +887,9 @@ fetchApiWith('updateUser', [7, { name: 'Ada' }]);
 
 See [doc/useApi.md](doc/useApi.md).
 
+#### useHaptics
+Thin `navigator.vibrate` wrapper. Returns `{ trigger, supported, reducedMotion }`; `trigger('selection' | 'success' | 'warning' | 'error' | ms | number[])` does nothing where vibration is unsupported (iOS Safari) or reduced motion is on. `Switch`, `Checkbox`, `ConfirmDialog` and `Sheet` take an opt-in `haptics` prop that uses it.
+
 ## 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.
@@ -885,7 +934,7 @@ The palettes are `primary`, `secondary`, `success`, `warning`, `error`, `info` a
 
 **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.
+**Colours come from tokens.** `ProgressBar`, `Checkbox`, `Switch`, `Rate` and `Skeleton` use token classes, so a brand file recolours them. 2.0.0 removed their raw-colour escape hatches: ProgressBar's HEX `color` / `bgColor` / `valueColor` (use `variant`), Checkbox's `borderColor`, Rate's `activeColor` / `inactiveColor`, and the `blue` / `indigo` / `purple` presets on Checkbox and Switch. See [`doc/MIGRATION-2.0.md`](doc/MIGRATION-2.0.md).
 
 **SSR:** `Tabs`, `Tooltip` and `Switch` generate ids with `React.useId()`, so server-rendered pages (Next.js) hydrate without mismatches. The `/charts` components do the same for their SVG ids, and they render token colours and reduced-motion state the way the server did until hydration finishes.
 
@@ -893,6 +942,21 @@ The palettes are `primary`, `secondary`, `success`, `warning`, `error`, `info` a
 
 The stylesheet ships a phone baseline: no tap highlight, no iOS zoom when a field is focused (text fields are 16px on touch screens; add `dt-keep-font-size` to opt one out), `color-scheme` that follows the theme, and no rubber-band overscroll on `body` (add `dt-overscroll-auto` to `<html>` to keep pull-to-refresh). Pad edge bars with `pt-safe` / `pb-safe` / `px-safe` / `inset-safe` — they need `<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">` — and size full-height layouts with `min-h-dvh` instead of `100vh`. Touch targets grow to 44px on coarse pointers.
 
+**Touch-friendly components (1.6–1.8).**
+- **Controls:** `Input`/`Textarea` take `size`, `Input` adds `floatingLabel` and `otp`, and sets mobile keyboard hints for `tel`/`email`/`url`/`search`.
+- **Buttons:** square `size="icon"` sizes, press feedback, and a loading state that keeps the button's width.
+- **FootNav:** a native tab bar with safe area, links (`href` + `linkAs`), `hideOnScroll` and `FootNav.Spacer`.
+- **Tabs:** scroll with snap, plus a `segmented` variant and `swipeable`.
+- **Navigation:** `Pagination` goes compact on phones, `Stepper` can stack (`orientation="auto"`), and `Breadcrumbs` collapses (`maxItems`).
+- **Carousel:** a native scroll-snap swiper.
+- **Sortable:** drags after a long-press on touch.
+- **FileUpload:** shows "Choose file" / "Take photo" buttons on touch (`capture`).
+- **Charts:** take `aspectRatio` and pin the tooltip on tap.
+
+**Adaptive overlays.** On phones (coarse pointer, under 640px), `Select`, `DatePicker`, `DateRangePicker`, `ThreeDotPopover`, the Table row menu, `Dialog`, `ConfirmDialog`, `Popover` and `Tour` open as a bottom `Sheet` (or an action sheet, or a docked card) by default. Each takes `presentation="auto" | "popover" | "sheet"`; use `"popover"` to keep the desktop behaviour. `Tooltip` opens on long-press on touch screens.
+
+**Native feel and PWA guide.** [`doc/MobileNativeFeel.md`](doc/MobileNativeFeel.md) walks through the rest of the setup for phones and installed apps: the viewport meta, per-theme `theme-color` kept in sync with `ThemeProvider`, a `display: "standalone"` web manifest, `dvh` layouts, the `AppShell` + `FootNav` + `Sheet` recipe, when to override `presentation`, safe areas, opt-in haptics, and a real-device testing checklist for iOS Safari and Android Chrome.
+
 ## Dark Mode
 
 Enable dark mode with the built-in theme provider:

package/ai-skills/dreamtree-ui.md

@@ -40,6 +40,13 @@ npm install @tiptap/react @tiptap/pm @tiptap/starter-kit
 
 Apps that don't import these subpaths install and bundle nothing extra.
 
+**Upgrading from 1.x to 2.0:** run the bundled codemod, then fix what it reports
+(see `doc/MIGRATION-2.0.md`, also served as `dreamtree://docs/MIGRATION-2.0`):
+
+```bash
+npx jscodeshift -t node_modules/@dreamtree-org/twreact-ui/codemods/v2.cjs src/
+```
+
 ## Wiring (do not invent alternatives)
 
 ```jsx
@@ -106,6 +113,9 @@ wire it up and **query it instead of guessing prop names**:
 - `search_components(query)` — keyword search by capability.
 
 Resources: `dreamtree://skill` (this guide) and `dreamtree://docs/<Component>`.
+Guide: `dreamtree://docs/MobileNativeFeel` (`doc/MobileNativeFeel.md`) — making an app
+feel native on phones / as a PWA (viewport + `theme-color` meta, manifest, `dvh`, safe
+areas, AppShell + FootNav + Sheet, `presentation` overrides, device testing checklist).
 Prompt: `compose_ui`. The catalog is a snapshot baked into the package, so it is
 self-contained and always matches the installed library version. The lists below
 are the fallback when the MCP server isn't connected.
@@ -118,11 +128,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`, `Textarea`, `Slider`, `Popover` |
+| **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` |
 | **Navigation**  | `Sidebar`, `Navbar`, `FootNav`, `Breadcrumbs`                                                                                                                                                                              |
-| **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 |
+| **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) |
+| **Utility**     | `Badge`, `Avatar`, `AvatarGroup` (overlapping stack + `max` "+N"), `Card`, `Pagination`, `Stepper`, `FileUpload`, `Condition`, `Carousel`, `Sortable` (drag + keyboard reorder), `PullToRefresh` (touch pull-to-refresh around a scroller) |
+| **Blocks**      | `AppShell`, `PageHeader`, `StatCard`, `StatusPill`, `EmptyState`, `ErrorState`, `LoadingState`, `ConfirmDialog`, `BottomActionBar` (+ `BottomActionBar.Spacer`) — 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 |
 
@@ -133,6 +143,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` and the `.dark` class on `<html>`.                                       |
 | `useApi`        | Thin axios wrapper. Returns `{data, error, loading, lastRequest, fetchData, fetchApi, fetchApiWith}`. Accepts `BASE_URL`, `DEFAULT_HEADERS`, `apiMap`. |
+| `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. |
 | `useMixins`     | Bridge between component state, Redux store, and an in-memory cache. Power-user hook — prefer local React state for new code.                  |
 
 ### Store
@@ -172,36 +183,57 @@ Components use a **shared variant/size/focus vocabulary**:
   (component-specific extras like `Badge: info` and `Alert: neutral` are documented per-component).
 - **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`).
+  other components MAY support a subset and fall back to `md`). `Button` also has square
+  icon-only sizes `icon-sm | icon | icon-lg` (always with `aria-label`).
 - **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.
 
+- **Icon slots:** `leftIcon` / `rightIcon` (Button, Input, `Tabs.Tab`).
+- **Colour is a token, never a HEX prop** (2.0.0): `ProgressBar variant="success"`, not
+  `color="#16a34a"`; Checkbox / Switch `color` takes `primary | secondary | success | error |
+  warning`. Checkbox `borderColor`, Rate `activeColor` / `inactiveColor` and the
+  `blue` / `indigo` / `purple` presets no longer exist.
+- **Controlled clearable Input:** clear `value` in `onClear` — the clear button does not call
+  `onChange` (2.0.0).
+
 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.
+- `AppShell` — sidebar + top bar + mobile drawer (a left `Sheet`); pass `nav` items and `linkAs={Link}` in Next.js. `bottomNav={<FootNav … />}` adds a phone tab bar (below `md`, spacer included). Fills `min-h-dvh` and pads safe areas.
+- `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). The content renders once (column on `md`+, drawer below), so don't render a second Sidebar for phones.
+- `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).
+- `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.
 - `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.
+- `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.
 
 **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"`. 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`.
-- `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.
+- `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`).
+- `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.
+- `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.
+- `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.
 - `Button` as a link — `<Button href="tel:…">` or `<Button as={Link} to="/x">`; never copy Button's class string onto an `<a>`.
+- 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.
+- `Badge` — `dot` (live/status dot), `icon` (leading icon slot), `max={99}` with a numeric child renders `99+`.
+- `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" />`.
 - `Select size="lg"` — 44px trigger for phone forms (`md` already grows to 44px on touch screens).
-- `Stepper` steps take `title` (or its alias `label`). `Radio` follows the primary token by default — don't pass `radioColor` to match the brand.
+- `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.
+- `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.
+- `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.
+- `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.
 - `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.
+- `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).
 - `Sortable` — `items` + `onReorder(newItems)` + `renderItem`; keyboard reordering and announcements are built in. Pass `handle` and spread `handleProps` on a grip for touch screens.
+- `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.
+- 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')`.
 - 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.
@@ -235,8 +267,8 @@ import { Button } from '@dreamtree-org/twreact-ui';
 <Button variant="outline" leftIcon={<Plus className="h-4 w-4" />}>Add item</Button>
 ```
 
-Props: `variant`, `size`, `disabled`, `loading`, `leftIcon`, `rightIcon`,
-`fullWidth`, `className`, plus all native `<button>` props.
+Props: `variant`, `size` (incl. `icon-sm`/`icon`/`icon-lg`), `disabled`, `loading`, `leftIcon`, `rightIcon`,
+`fullWidth`, `as`, `href`, `className`, plus all native `<button>` props.
 
 ### Input + Form
 
@@ -278,6 +310,9 @@ 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.
+`sticky` makes it a translucent sticky bar with the top safe area; `largeTitle="Inbox"`
+adds an iOS large title that collapses on scroll. With `searchable`, phones get a
+Search button that opens a `SearchField` sheet wired to `onSearch`.
 
 **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
@@ -307,6 +342,12 @@ function SomeButton() {
 }
 ```
 
+Toasts swipe away horizontally, pause while hovered / focused / touched, and
+past three collapse into a stack that expands on hover, focus or tap
+(`expand` forces it open, `visibleToasts` changes the limit). On phones they
+sit bottom-center, full width, above the FootNav — pass `mobileOffset={16}`
+when the app has no FootNav, or `mobilePosition={false}` to keep `position`.
+
 ### Theme
 
 ```jsx
@@ -386,7 +427,9 @@ import { cn } from '@dreamtree-org/twreact-ui';
    matching primitive.
 2. **Use the shared vocabulary.** `variant="primary"`, `size="md"`,
    `leftIcon={...}`, `fullWidth`, `clearable` — these are exact names.
-   Don't invent `color="blue"` or `iconLeft={...}`.
+   Don't invent `color="blue"` or `iconLeft={...}`. Icon slots are
+   `leftIcon` / `rightIcon` on `Button`, `Input` and `Tabs.Tab` (2.0 renamed
+   Input `icon`/`iconPosition` and Tab `iconLeft`/`iconRight`).
 3. **Wrap in `<ThemeProvider>`.** Examples that use `useTheme`, or rely
    on dark-mode classes, MUST show the provider.
 4. **`<StoreProvider>` is optional.** Only mention it when the user is

package/codemods/v2.cjs

@@ -0,0 +1,198 @@
+/**
+ * @dreamtree-org/twreact-ui 1.x -> 2.0.0 codemod (DTUI-67).
+ *
+ *   npx jscodeshift -t node_modules/@dreamtree-org/twreact-ui/codemods/v2.cjs src/
+ *
+ * Only JSX on components imported from `@dreamtree-org/twreact-ui` is touched
+ * (named imports, aliases such as `{ Input as TextInput }`, and namespace
+ * imports such as `UI.Input`). See doc/MIGRATION-2.0.md for every change and
+ * for what this script leaves to you.
+ *
+ * Automated:
+ *   - Input       icon (+ iconPosition "left" / absent) -> leftIcon
+ *                 icon + iconPosition="right"           -> rightIcon
+ *                 a literal iconPosition without icon    -> removed
+ *   - Tabs.Tab    iconLeft -> leftIcon, iconRight -> rightIcon
+ *   - Checkbox    borderColor                            -> removed
+ *   - ProgressBar color / bgColor / valueColor            -> removed
+ *   - Rate        activeColor / inactiveColor            -> removed
+ *
+ * Reported for a manual fix (the file and line are printed):
+ *   - Input with a non-literal iconPosition
+ *   - Input `clearable` + `value` without `onClear` (clear no longer calls onChange)
+ *   - Checkbox / Switch color="blue" | "indigo" | "purple"
+ *   - ProgressBar that had a colour prop (pick a `variant`)
+ *
+ * The default parser is `tsx`, which reads .js, .jsx, .ts and .tsx files.
+ * Pass `--parser=babel` (or another) to override.
+ */
+
+const PACKAGE = "@dreamtree-org/twreact-ui";
+const RAW_PRESETS = new Set(["blue", "indigo", "purple"]);
+
+const REMOVED = {
+  Checkbox: ["borderColor"],
+  ProgressBar: ["color", "bgColor", "valueColor"],
+  Rate: ["activeColor", "inactiveColor"],
+};
+
+const RENAMED = {
+  "Tabs.Tab": { iconLeft: "leftIcon", iconRight: "rightIcon" },
+};
+
+/** Map local JSX names to the library component they refer to. */
+function collectImports(j, root) {
+  const named = new Map(); // local name -> exported name
+  const namespaces = new Set(); // `import * as UI`
+  root
+    .find(j.ImportDeclaration, { source: { value: PACKAGE } })
+    .forEach((path) => {
+      (path.node.specifiers || []).forEach((spec) => {
+        if (spec.type === "ImportSpecifier") {
+          const imported = spec.imported.name || spec.imported.value;
+          named.set(spec.local ? spec.local.name : imported, imported);
+        } else if (spec.type === "ImportNamespaceSpecifier") {
+          namespaces.add(spec.local.name);
+        }
+        // A default import has no named component to match; skip it.
+      });
+    });
+  return { named, namespaces };
+}
+
+/** Resolve a JSX element name to "Input", "Tabs.Tab", … or null. */
+function componentName(nameNode, imports) {
+  if (nameNode.type === "JSXIdentifier") {
+    return imports.named.get(nameNode.name) || null;
+  }
+  if (nameNode.type !== "JSXMemberExpression") return null;
+  const parts = [];
+  let node = nameNode;
+  while (node.type === "JSXMemberExpression") {
+    parts.unshift(node.property.name);
+    node = node.object;
+  }
+  if (node.type !== "JSXIdentifier") return null;
+  if (imports.namespaces.has(node.name)) {
+    // UI.Input / UI.Tabs.Tab
+    return parts.join(".") || null;
+  }
+  const head = imports.named.get(node.name);
+  return head ? [head, ...parts].join(".") : null;
+}
+
+function attrName(attr) {
+  return attr.type === "JSXAttribute" && attr.name.type === "JSXIdentifier"
+    ? attr.name.name
+    : null;
+}
+
+/** The string value of a literal attribute (`x="a"`, `x={'a'}`), else undefined. */
+function literalValue(attr) {
+  const v = attr.value;
+  if (!v) return undefined;
+  if (v.type === "StringLiteral" || v.type === "Literal") {
+    return typeof v.value === "string" ? v.value : undefined;
+  }
+  if (v.type === "JSXExpressionContainer") {
+    const e = v.expression;
+    if ((e.type === "StringLiteral" || e.type === "Literal") && typeof e.value === "string") return e.value;
+    if (e.type === "TemplateLiteral" && e.expressions.length === 0) return e.quasis[0].value.cooked;
+  }
+  return undefined;
+}
+
+module.exports = function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  const imports = collectImports(j, root);
+  if (imports.named.size === 0 && imports.namespaces.size === 0) return undefined;
+
+  let changed = false;
+  const report = (node, msg) => {
+    // jscodeshift prefixes each report with the file path.
+    const text = node.loc ? `line ${node.loc.start.line}: ${msg}` : msg;
+    if (typeof api.report === "function") api.report(text);
+  };
+
+  root.find(j.JSXOpeningElement).forEach((path) => {
+    const el = path.node;
+    const name = componentName(el.name, imports);
+    if (!name) return;
+    const attrs = el.attributes;
+    const find = (n) => attrs.find((a) => attrName(a) === n);
+    const remove = (attr) => {
+      attrs.splice(attrs.indexOf(attr), 1);
+      changed = true;
+    };
+    const rename = (attr, to) => {
+      attr.name = j.jsxIdentifier(to);
+      changed = true;
+    };
+
+    // --- removals --------------------------------------------------------
+    const removedProps = REMOVED[name] || [];
+    let hadColourProp = false;
+    removedProps.forEach((prop) => {
+      const attr = find(prop);
+      if (attr) {
+        remove(attr);
+        hadColourProp = true;
+      }
+    });
+    if (name === "ProgressBar" && hadColourProp) {
+      report(el, "ProgressBar: removed HEX colour props; set `variant` (primary|secondary|success|warning|destructive) if you need a non-primary tone.");
+    }
+
+    // --- renames ---------------------------------------------------------
+    const renames = RENAMED[name];
+    if (renames) {
+      Object.keys(renames).forEach((from) => {
+        const attr = find(from);
+        if (!attr) return;
+        if (find(renames[from])) {
+          report(el, `${name}: both \`${from}\` and \`${renames[from]}\` are set; remove \`${from}\` by hand.`);
+          return;
+        }
+        rename(attr, renames[from]);
+      });
+    }
+
+    // --- Input icon / iconPosition / clear ---------------------------------
+    if (name === "Input") {
+      const icon = find("icon");
+      const position = find("iconPosition");
+      const posValue = position ? literalValue(position) : "left";
+      if (position && posValue === undefined) {
+        report(el, "Input: `iconPosition` is not a literal; replace `icon` + `iconPosition` with `leftIcon` or `rightIcon` by hand.");
+      } else if (icon) {
+        const target = posValue === "right" ? "rightIcon" : "leftIcon";
+        if (find(target)) {
+          report(el, `Input: \`${target}\` is already set; merge \`icon\` by hand.`);
+        } else {
+          rename(icon, target);
+          if (position) remove(position);
+        }
+      } else if (position) {
+        remove(position); // iconPosition without icon never rendered anything
+      }
+
+      if (find("clearable") && find("value") && !find("onClear")) {
+        report(el, "Input: controlled + clearable without `onClear`. The clear button no longer calls onChange; add onClear={() => setValue('')}.");
+      }
+    }
+
+    // --- raw colour presets ---------------------------------------------
+    if (name === "Checkbox" || name === "Switch") {
+      const color = find("color");
+      const value = color && literalValue(color);
+      if (value && RAW_PRESETS.has(value)) {
+        report(el, `${name}: color="${value}" is no longer a preset (it now paints the CSS colour inline). Use a token: primary, secondary, success, error or warning.`);
+      }
+    }
+  });
+
+  return changed ? root.toSource({ quote: "double" }) : undefined;
+};
+
+module.exports.parser = "tsx";