@dreamtree-org/twreact-ui 2.0.3 → 2.0.5

package/README.md

@@ -132,7 +132,7 @@ nothing changes in your bundle — the root `@dreamtree-org/twreact-ui` import n
 
 | Entry point | Exports | Install first |
 |---|---|---|
-| `@dreamtree-org/twreact-ui/charts` | `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, `Sparkline` | `npm install recharts` (recharts 2.15+ or 3.x; React 18 apps also `npm install react-is@18`) |
+| `@dreamtree-org/twreact-ui/charts` | `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, `Sparkline`, `ScatterChart` | `npm install recharts` (recharts 2.15+ or 3.x; React 18 apps also `npm install react-is@18`) |
 | `@dreamtree-org/twreact-ui/rich-text` | `RichTextEditor` | `npm install @tiptap/react @tiptap/pm @tiptap/starter-kit` (Tiptap 3) |
 
 ```jsx
@@ -285,7 +285,7 @@ Advanced select component with search, multi-select, and grouping support.
 - `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...')
+- `placeholder`: string (default: 'Select an option...') — shown muted (`text-muted`) with `data-empty` on the trigger while nothing is selected
 - `label`: string — associated with the trigger (accessible name = label + value)
 - `error`: string
 - `helperText`: ReactNode — hint below the control; replaced by `error` while shown
@@ -432,7 +432,7 @@ Calendar-based date selection with keyboard navigation.
 **Props:**
 - `value`: Date | string
 - `onChange`: (date: Date | null) => void
-- `placeholder`: string (default: 'Select date...')
+- `placeholder`: string (default: 'Select date...') — shown muted (`text-muted`) with `data-empty` on the trigger while empty (same for DateRangePicker)
 - `label`: string
 - `error`: string
 - `helperText`: ReactNode — hint below the trigger; replaced by `error` while shown
@@ -464,6 +464,7 @@ Collapsible sidebar navigation with nested items.
 **Props:**
 - `items`: Array<SidebarItem>
 - `collapsed`: boolean (default: false)
+- `collapsible`: boolean (default: true) — `false` removes the md+ collapse/expand toggle; the phone drawer keeps its 44px "Close navigation" button
 - `onToggle`: () => void
 - `logo`: ReactNode
 - `user`: {name: string, email: string, avatar?: string, menuItems?: Array<MenuItem>}
@@ -518,7 +519,9 @@ Top navigation bar with user menu and notifications.
 - `onNotificationClick`: (notifications: Array<Notification>) => void
 - `onUserClick`: (user: object) => void
 - `leftIcon`: ReactNode | false
-- `onLeftIconClick`: () => void
+- `onLeftIconClick`: (event) => void
+- `leftIconLabel`: string (default: "Go back") — the left button's accessible name, e.g. "Open navigation" when it opens a Sidebar drawer
+- `leftIconProps`: ButtonHTMLAttributes — spread onto the left button (e.g. `aria-expanded`, `aria-controls`); `className` merges last
 
 ```jsx
 <Navbar
@@ -758,6 +761,7 @@ Interaction primitives that products used to compose by hand. All are `forwardRe
 | [`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` |
+| [`SortableGroup`](doc/SortableGroup.md) | Utility | Moves items between `Sortable` lists (each with an `id`): pointer drag or cross-axis arrow keys, `onMove({ item, from, to })`, and `canDrop(item, target, from)` which marks and announces a refused list before the drop |
 | [`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 |
@@ -767,7 +771,7 @@ Interaction primitives that products used to compose by hand. All are `forwardRe
 | [`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, Sheet, Popover, Textarea, Slider, Sortable, Tour, Button } from '@dreamtree-org/twreact-ui';
+import { Drawer, Sheet, Popover, Textarea, Slider, Sortable, SortableGroup, 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} />
@@ -784,6 +788,11 @@ import { Drawer, Sheet, Popover, Textarea, Slider, Sortable, Tour, Button } from
 
 <Sortable aria-label="Backlog" items={tasks} onReorder={setTasks} renderItem={(t) => t.title} />
 
+<SortableGroup onMove={({ item, from, to }) => moveTask(item, from, to)} canDrop={(task, target) => canEnter(task, target.listId)}>
+  <Sortable id="backlog" aria-label="Backlog" items={backlog} onReorder={setBacklog} />
+  <Sortable id="sprint" aria-label="Sprint" items={sprint} onReorder={setSprint} />
+</SortableGroup>
+
 <Tour open={tourOpen} steps={[{ title: 'Welcome' }, { target: '[data-tour="new-task"]', title: 'Capture work' }]} onClose={() => setTourOpen(false)} />
 ```
 
@@ -804,12 +813,13 @@ screen readers (`accessibleTable`), shows `emptyState` for empty data, and disab
 | [`AreaChart`](doc/AreaChart.md) | Volume over time, optionally `stacked` |
 | [`DonutChart`](doc/DonutChart.md) | Part-to-whole (`variant="donut"` or `"pie"`, `centerLabel`) |
 | [`Sparkline`](doc/Sparkline.md) | Word-sized trend for stat cards and table cells |
+| [`ScatterChart`](doc/ScatterChart.md) | Two numeric axes, one point per entity: `x` + `y` keys, optional `index` (entity name) and `category` (series), `xAxisLabel` / `yAxisLabel`; single points sit on padded axes |
 
 Shared props: `valueFormatter`, `height`, `showLegend`, `showTooltip`, `showXAxis`, `showYAxis`,
 `showGrid`, `colors`, `animate`.
 
 ```jsx
-import { LineChart, DonutChart, Sparkline } from '@dreamtree-org/twreact-ui/charts';
+import { LineChart, DonutChart, Sparkline, ScatterChart } from '@dreamtree-org/twreact-ui/charts';
 
 <LineChart
   data={[{ month: 'Jan', revenue: 4200 }, { month: 'Feb', revenue: 5100 }]}
@@ -820,6 +830,7 @@ import { LineChart, DonutChart, Sparkline } from '@dreamtree-org/twreact-ui/char
 />
 <DonutChart data={byStatus} index="status" category="tasks" centerLabel="63 tasks" title="Tasks by status" />
 <Sparkline data={weekly} category="signups" color="success" title="Signups, last 4 weeks" />
+<ScatterChart data={projects} x="health" y="variance" index="project" category="department" title="Health vs budget variance" />
 ```
 
 ### Rich text (optional entry point)

package/ai-skills/dreamtree-ui.md

@@ -131,9 +131,9 @@ 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`, `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), `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) |
+| **Utility**     | `Badge`, `Avatar`, `AvatarGroup` (overlapping stack + `max` "+N"), `Card`, `Pagination`, `Stepper`, `FileUpload`, `Condition`, `Carousel`, `Sortable` (drag + keyboard reorder), `SortableGroup` (move items between `Sortable` lists, `canDrop`), `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 |
+| **Charts** (`@dreamtree-org/twreact-ui/charts`, peer `recharts`) | `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, `Sparkline`, `ScatterChart` — NOT exported from the root |
 | **Rich text** (`@dreamtree-org/twreact-ui/rich-text`, peers `@tiptap/react @tiptap/pm @tiptap/starter-kit`) | `RichTextEditor` — NOT exported from the root |
 
 ### Hooks
@@ -204,7 +204,7 @@ 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 (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.
+- `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). `collapsible={false}` drops the desktop collapse toggle (the drawer keeps "Close navigation"). Hide drawer items with real CSS if you must — the focus trap skips `display:none` / `visibility:hidden` elements. 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`).
@@ -232,9 +232,10 @@ When suggesting a component or new variant value, use this exact vocabulary.
 - `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. 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.
+- `SortableGroup` — for boards / backlog → sprint: wrap the lists, give each `Sortable` an `id` (+ `aria-label`, used in announcements) and handle `onMove({ item, from: { listId, index }, to: { listId, index } })`; pass `canDrop(item, target, from)` (e.g. from a server transition list) so refused columns are marked and announced before the drop instead of reverting after it. Within-list reorders still call each list's `onReorder`. Give lists a `min-h-*` so empty ones can be dropped on.
 - `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.
+- 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`; `ScatterChart` takes `x` + `y` (numeric keys) plus optional `index` (entity name) and `category` (series), e.g. `<ScatterChart data={projects} x="health" y="variance" index="project" category="department" />`. 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.
 
@@ -312,7 +313,13 @@ with a `group` key (`{ value, label, group: 'Code' }`) — no need to pre-group.
 `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`.
+Search button that opens a `SearchField` sheet wired to `onSearch`. When the left
+button opens your Sidebar drawer (`leftIcon={<Menu />}`), name it with
+`leftIconLabel="Open navigation"` (default "Go back") and pass
+`leftIconProps={{ 'aria-expanded': open, 'aria-controls': 'app-sidebar' }}`.
+
+**Select / DatePicker / DateRangePicker** show their placeholder muted (`text-muted`)
+and set `data-empty` on the trigger while empty — don't add a muted `className` yourself.
 
 **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

package/dist/ai-schema.json

@@ -1785,7 +1785,16 @@
         "default": "false"
       },
       "onLeftIconClick": {
-        "type": "() => void",
+        "type": "(event: React.MouseEvent<HTMLButtonElement>) => void",
+        "required": false
+      },
+      "leftIconLabel": {
+        "type": "string",
+        "required": false,
+        "default": "\"Go back\""
+      },
+      "leftIconProps": {
+        "type": "ButtonHTMLAttributes<HTMLButtonElement> & Record<`data-${string}`, string | undefined>",
         "required": false
       },
       "onLoginClick": {
@@ -2435,6 +2444,118 @@
       }
     }
   },
+  "ScatterChart": {
+    "group": "charts",
+    "import": "@dreamtree-org/twreact-ui/charts",
+    "forwardRef": true,
+    "props": {
+      "data": {
+        "type": "ChartDatum[]",
+        "required": true
+      },
+      "title": {
+        "type": "string",
+        "required": false
+      },
+      "description": {
+        "type": "string",
+        "required": false
+      },
+      "valueFormatter": {
+        "type": "ChartValueFormatter",
+        "required": false,
+        "default": "toLocaleString"
+      },
+      "height": {
+        "type": "number | string",
+        "required": false,
+        "default": "300"
+      },
+      "emptyState": {
+        "type": "ReactNode",
+        "required": false,
+        "default": "\"No data to display\""
+      },
+      "accessibleTable": {
+        "type": "boolean",
+        "required": false,
+        "default": "true"
+      },
+      "animate": {
+        "type": "boolean",
+        "required": false,
+        "default": "true"
+      },
+      "showTooltip": {
+        "type": "boolean",
+        "required": false,
+        "default": "true"
+      },
+      "x": {
+        "type": "string",
+        "required": true
+      },
+      "y": {
+        "type": "string",
+        "required": true
+      },
+      "index": {
+        "type": "string",
+        "required": false
+      },
+      "category": {
+        "type": "string",
+        "required": false
+      },
+      "colors": {
+        "type": "ChartColor[]",
+        "required": false,
+        "default": "primary, success, warning, error, info, secondary, gray"
+      },
+      "xAxisFormatter": {
+        "type": "(value: number) => string",
+        "required": false,
+        "default": "toLocaleString"
+      },
+      "xAxisLabel": {
+        "type": "string",
+        "required": false
+      },
+      "yAxisLabel": {
+        "type": "string",
+        "required": false
+      },
+      "showLegend": {
+        "type": "boolean",
+        "required": false,
+        "default": "true"
+      },
+      "showXAxis": {
+        "type": "boolean",
+        "required": false,
+        "default": "true"
+      },
+      "showYAxis": {
+        "type": "boolean",
+        "required": false,
+        "default": "true"
+      },
+      "showGrid": {
+        "type": "boolean",
+        "required": false,
+        "default": "true"
+      },
+      "yAxisWidth": {
+        "type": "number",
+        "required": false,
+        "default": "48 (36 when the chart is narrower than 400 px)"
+      },
+      "aspectRatio": {
+        "type": "number",
+        "required": false
+      }
+    }
+  },
   "SearchField": {
     "group": "core",
     "import": "@dreamtree-org/twreact-ui",
@@ -2811,6 +2932,11 @@
         "required": false,
         "default": "false"
       },
+      "collapsible": {
+        "type": "boolean",
+        "required": false,
+        "default": "true"
+      },
       "onToggle": {
         "type": "() => void",
         "required": false
@@ -3089,6 +3215,29 @@
       "messages": {
         "type": "SortableMessages",
         "required": false
+      },
+      "id": {
+        "type": "string",
+        "required": false
+      }
+    }
+  },
+  "SortableGroup": {
+    "group": "utility",
+    "import": "@dreamtree-org/twreact-ui",
+    "forwardRef": true,
+    "props": {
+      "onMove": {
+        "type": "(move: SortableMove<T>) => void",
+        "required": false
+      },
+      "canDrop": {
+        "type": "(item: T, target: SortableLocation, from: SortableLocation) => boolean",
+        "required": false
+      },
+      "children": {
+        "type": "ReactNode",
+        "required": false
       }
     }
   },

package/dist/charts/index.d.ts

@@ -1,9 +1,10 @@
 import type * as React from "react";
-import type { AreaChartProps, BarChartProps, DonutChartProps, LineChartProps, SparklineProps } from "../types/charts";
+import type { AreaChartProps, BarChartProps, DonutChartProps, LineChartProps, ScatterChartProps, SparklineProps } from "../types/charts";
 export declare const LineChart: React.ForwardRefExoticComponent<LineChartProps & React.RefAttributes<HTMLDivElement>>;
 export declare const BarChart: React.ForwardRefExoticComponent<BarChartProps & React.RefAttributes<HTMLDivElement>>;
 export declare const AreaChart: React.ForwardRefExoticComponent<AreaChartProps & React.RefAttributes<HTMLDivElement>>;
 export declare const DonutChart: React.ForwardRefExoticComponent<DonutChartProps & React.RefAttributes<HTMLDivElement>>;
 export declare const Sparkline: React.ForwardRefExoticComponent<SparklineProps & React.RefAttributes<HTMLDivElement>>;
+export declare const ScatterChart: React.ForwardRefExoticComponent<ScatterChartProps & React.RefAttributes<HTMLDivElement>>;
 export * from "../types/charts";
 //# sourceMappingURL=index.d.ts.map