@dreamtree-org/twreact-ui 1.3.9 → 1.3.11

package/README.md

@@ -669,6 +669,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 +693,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">
@@ -893,6 +912,17 @@ 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.
+
 ## Dark Mode
 
 Enable dark mode with the built-in theme provider:
@@ -913,6 +943,8 @@ function App() {
 
 Surfaces such as `Card`, `Sidebar`, `Navbar`, `Table`, `FootNav` and `Dropdown` use the semantic `bg-surface` / `bg-background` / `border-line` / `text-foreground` / `text-muted` tokens, which switch under `.dark` (or `[data-theme="dark"]`). Re-theme them by overriding the `--dt-surface`, `--dt-background`, `--dt-line`, … variables.
 
+> **Accessibility fixes (1.4.x):** Radio groups keep a single selection when uncontrolled, Rate and DatePicker use one tab stop with arrow-key focus, Dialog/Sidebar/AppShell drawers share one focus trap and scroll lock, Toast announces via `role="status"`, Alert's dismiss button is labelled, and Input shows a visible focus ring in its default state. No props changed.
+
 ## Examples
 
 ### Complete Form Example

package/ai-skills/dreamtree-ui.md

@@ -121,7 +121,7 @@ The library exports four kinds of things from `@dreamtree-org/twreact-ui`:
 | **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` (+ `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) |
+| **Utility**     | `Badge`, `Avatar`, `AvatarGroup` (overlapping stack + `max` "+N"), `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 |
@@ -172,7 +172,8 @@ 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.
@@ -194,13 +195,17 @@ When suggesting a component or new variant value, use this exact vocabulary.
 **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`).
 - `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.
 - `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.
 - 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.
@@ -235,8 +240,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
 

package/dist/ai-schema.json

@@ -203,7 +203,11 @@
       "yAxisWidth": {
         "type": "number",
         "required": false,
-        "default": "48"
+        "default": "48 (36 when the chart is narrower than 400 px)"
+      },
+      "aspectRatio": {
+        "type": "number",
+        "required": false
       },
       "curveType": {
         "type": "enum",
@@ -285,6 +289,34 @@
       }
     }
   },
+  "AvatarGroup": {
+    "group": "utility",
+    "import": "@dreamtree-org/twreact-ui",
+    "forwardRef": true,
+    "props": {
+      "children": {
+        "type": "ReactNode",
+        "required": false
+      },
+      "max": {
+        "type": "number",
+        "required": false
+      },
+      "size": {
+        "type": "enum",
+        "required": false,
+        "values": [
+          "xs",
+          "sm",
+          "md",
+          "lg",
+          "xl",
+          "2xl"
+        ],
+        "default": "\"md\""
+      }
+    }
+  },
   "Badge": {
     "group": "utility",
     "import": "@dreamtree-org/twreact-ui",
@@ -326,6 +358,19 @@
         "type": "boolean",
         "required": false,
         "default": "true"
+      },
+      "dot": {
+        "type": "boolean",
+        "required": false,
+        "default": "false"
+      },
+      "icon": {
+        "type": "ReactNode",
+        "required": false
+      },
+      "max": {
+        "type": "number",
+        "required": false
       }
     }
   },
@@ -416,7 +461,11 @@
       "yAxisWidth": {
         "type": "number",
         "required": false,
-        "default": "48"
+        "default": "48 (36 when the chart is narrower than 400 px)"
+      },
+      "aspectRatio": {
+        "type": "number",
+        "required": false
       },
       "stacked": {
         "type": "boolean",
@@ -457,6 +506,11 @@
       "onHomeClick": {
         "type": "(item: BreadcrumbItem) => void",
         "required": false
+      },
+      "maxItems": {
+        "type": "number",
+        "required": false,
+        "default": "— (no collapse)"
       }
     }
   },
@@ -480,16 +534,8 @@
         "default": "\"primary\""
       },
       "size": {
-        "type": "enum",
+        "type": "Size | ButtonIconSize",
         "required": false,
-        "values": [
-          "xs",
-          "sm",
-          "md",
-          "lg",
-          "xl",
-          "2xl"
-        ],
         "default": "\"md\""
       },
       "disabled": {
@@ -565,6 +611,11 @@
         "type": "boolean",
         "required": false,
         "default": "false"
+      },
+      "interactive": {
+        "type": "boolean",
+        "required": false,
+        "default": "false"
       }
     }
   },
@@ -728,7 +779,8 @@
       },
       "label": {
         "type": "string",
-        "required": false
+        "required": false,
+        "default": "\"Pick a color\""
       }
     }
   },
@@ -1168,6 +1220,11 @@
         "type": "boolean",
         "required": false,
         "default": "false"
+      },
+      "capture": {
+        "type": "boolean | 'user' | 'environment'",
+        "required": false,
+        "default": "\"user\""
       }
     }
   },
@@ -1180,6 +1237,26 @@
         "type": "FootNavItem[]",
         "required": true,
         "default": "[]"
+      },
+      "linkAs": {
+        "type": "ElementType",
+        "required": false,
+        "default": "\"a\""
+      },
+      "hideOnScroll": {
+        "type": "boolean",
+        "required": false,
+        "default": "false"
+      },
+      "badgeMax": {
+        "type": "number",
+        "required": false,
+        "default": "99"
+      },
+      "aria-label": {
+        "type": "string",
+        "required": false,
+        "default": "\"Primary\""
       }
     }
   },
@@ -1195,7 +1272,8 @@
       },
       "onSubmit": {
         "type": "(data: any) => void",
-        "required": false
+        "required": false,
+        "default": "Promise<void>"
       },
       "defaultValues": {
         "type": "Record",
@@ -1332,6 +1410,21 @@
       "onChange": {
         "type": "(event: React.ChangeEvent<HTMLInputElement>) => void",
         "required": false
+      },
+      "size": {
+        "type": "'sm' | 'md' | 'lg' | number",
+        "required": false,
+        "default": "\"md\""
+      },
+      "floatingLabel": {
+        "type": "boolean",
+        "required": false,
+        "default": "false"
+      },
+      "otp": {
+        "type": "boolean",
+        "required": false,
+        "default": "false"
       }
     }
   },
@@ -1422,7 +1515,11 @@
       "yAxisWidth": {
         "type": "number",
         "required": false,
-        "default": "48"
+        "default": "48 (36 when the chart is narrower than 400 px)"
+      },
+      "aspectRatio": {
+        "type": "number",
+        "required": false
       },
       "curveType": {
         "type": "enum",
@@ -1474,8 +1571,7 @@
       },
       "secondaryColor": {
         "type": "string",
-        "required": false,
-        "default": "\"rgba(0,0,0,0.08)\""
+        "required": false
       },
       "variant": {
         "type": "string",
@@ -1546,6 +1642,11 @@
         "type": "string",
         "required": false,
         "default": "\"lat, lng\""
+      },
+      "fullWidth": {
+        "type": "boolean",
+        "required": false,
+        "default": "false"
       }
     }
   },
@@ -1800,7 +1901,7 @@
       "colorClass": {
         "type": "string",
         "required": false,
-        "default": "\"bg-pink-500\""
+        "default": "\"bg-primary-600\""
       },
       "ariaLabel": {
         "type": "string",
@@ -2164,8 +2265,7 @@
       },
       "ariaLabel": {
         "type": "string",
-        "required": false,
-        "default": "\"tag\""
+        "required": false
       },
       "avatarPosition": {
         "type": "enum",
@@ -2512,6 +2612,11 @@
         "required": false,
         "default": "false"
       },
+      "showBubble": {
+        "type": "boolean",
+        "required": false,
+        "default": "true"
+      },
       "formatValue": {
         "type": "(value: number) => string",
         "required": false,
@@ -2748,18 +2853,14 @@
         "required": false
       },
       "orientation": {
-        "type": "enum",
+        "type": "Orientation | 'auto'",
         "required": false,
-        "values": [
-          "horizontal",
-          "vertical"
-        ],
         "default": "\"vertical\""
       },
       "variant": {
-        "type": "string",
+        "type": "'default' | 'dots' | (string & {})",
         "required": false,
-        "default": "\"default\""
+        "default": "\"dots\""
       }
     }
   },
@@ -3104,6 +3205,7 @@
         "values": [
           "line",
           "pills",
+          "segmented",
           "unstyled"
         ],
         "default": "\"pills\""
@@ -3112,13 +3214,18 @@
         "type": "boolean",
         "required": false,
         "default": "true"
+      },
+      "swipeable": {
+        "type": "boolean",
+        "required": false,
+        "default": "false"
       }
     }
   },
   "TextToSpeech": {
     "group": "core",
     "import": "@dreamtree-org/twreact-ui",
-    "forwardRef": false,
+    "forwardRef": true,
     "props": {
       "text": {
         "type": "string",
@@ -3140,6 +3247,16 @@
         "required": false,
         "default": "() => {}"
       },
+      "onError": {
+        "type": "(error: Error) => void",
+        "required": false,
+        "default": "() => {}"
+      },
+      "disabled": {
+        "type": "boolean",
+        "required": false,
+        "default": "false"
+      },
       "renderButton": {
         "type": "(state: TextToSpeechState) => ReactNode",
         "required": false
@@ -3195,6 +3312,16 @@
       "maxRows": {
         "type": "number",
         "required": false
+      },
+      "size": {
+        "type": "enum",
+        "required": false,
+        "values": [
+          "sm",
+          "md",
+          "lg"
+        ],
+        "default": "\"md\""
       }
     }
   },
@@ -3347,12 +3474,12 @@
       "textClass": {
         "type": "string",
         "required": false,
-        "default": "\"text-black\""
+        "default": "\"text-foreground\""
       },
       "bgClass": {
         "type": "string",
         "required": false,
-        "default": "\"bg-white\""
+        "default": "\"bg-surface\""
       },
       "portal": {
         "type": "boolean",