@sableui/react 0.17.0 → 0.19.0

package/dist/{theme-provider-BydfM5Z0.d.ts → theme-provider-BUBealk_.d.ts}

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { T as ThemeManifest } from './_contract-CDa9-NdB.js';
+import { T as ThemeManifest } from './_contract-DlklV0Im.js';
 
 declare const SABLE_THEME_ATTRIBUTE: "data-sable-theme";
 declare const DEFAULT_THEME_ID: string;

package/dist/themes/_contract.js

@@ -150,6 +150,10 @@ var TYPE_SCALE_TOKENS = [
   "type-title-sm-tracking"
 ];
 var TYPE_REFINEMENT_TOKENS = [
+  // The base the page scale is built on, as a unitless px number (default 16).
+  // `14` rebuilds every page tier, and the baseline rhythm, at 14 — see
+  // styles.css → Typography → "The base size".
+  "type-base",
   "type-display-4xl-size",
   "type-title-lg-size",
   "type-title-sm-size",
@@ -331,7 +335,11 @@ var TYPE_UI_TOKENS = [
   "type-ui-leading",
   "type-ui-section-weight",
   "type-ui-micro-size",
-  "type-ui-micro-weight"
+  "type-ui-micro-weight",
+  // The panel/inspector title, one step above ui-md (compact `text-title-lg`).
+  "type-ui-title-size",
+  "type-ui-title-weight",
+  "type-ui-title-leading"
 ];
 export {
   APP_SHELL_TOKENS,

package/dist/themes/atelier/index.d.ts

@@ -1,4 +1,4 @@
-import { T as ThemeManifest } from '../../_contract-CDa9-NdB.js';
+import { T as ThemeManifest } from '../../_contract-DlklV0Im.js';
 
 /**
  * Mono Editorial — a Sable theme. Concrete token values live in

package/dist/themes/ember/index.d.ts

@@ -1,4 +1,4 @@
-import { T as ThemeManifest } from '../../_contract-CDa9-NdB.js';
+import { T as ThemeManifest } from '../../_contract-DlklV0Im.js';
 
 /**
  * Ember — a Sable theme. Concrete token values live in

package/dist/themes/index.d.ts

@@ -1,4 +1,4 @@
-export { A as AnyThemeId, D as DEFAULT_THEME_ID, S as SABLE_COLOR_STORAGE_KEY, a as SABLE_THEME_ATTRIBUTE, b as SABLE_THEME_STORAGE_KEY, c as SableColorMode, d as SableThemeContextValue, e as SableThemePreference, f as SableThemeProvider, g as SableThemeProviderProps, T as ThemeId, h as applySableColorMode, i as applySableTheme, j as buildThemeManifestById, k as defaultThemeId, l as featuredThemeManifests, m as getThemeManifest, n as isKnownThemeId, o as isThemeId, t as themeIds, p as themeManifestById, q as themeManifests, u as useSableTheme } from '../theme-provider-BydfM5Z0.js';
+export { A as AnyThemeId, D as DEFAULT_THEME_ID, S as SABLE_COLOR_STORAGE_KEY, a as SABLE_THEME_ATTRIBUTE, b as SABLE_THEME_STORAGE_KEY, c as SableColorMode, d as SableThemeContextValue, e as SableThemePreference, f as SableThemeProvider, g as SableThemeProviderProps, T as ThemeId, h as applySableColorMode, i as applySableTheme, j as buildThemeManifestById, k as defaultThemeId, l as featuredThemeManifests, m as getThemeManifest, n as isKnownThemeId, o as isThemeId, t as themeIds, p as themeManifestById, q as themeManifests, u as useSableTheme } from '../theme-provider-BUBealk_.js';
 export { atelierTheme } from './atelier/index.js';
 export { default as emberTheme } from './ember/index.js';
 export { default as meridianTheme } from './meridian/index.js';
@@ -7,4 +7,4 @@ export { default as prismTheme } from './prism/index.js';
 export { default as sableTheme } from './sable/index.js';
 export { default as verdantTheme } from './verdant/index.js';
 import 'react';
-import '../_contract-CDa9-NdB.js';
+import '../_contract-DlklV0Im.js';

package/dist/themes/meridian/index.d.ts

@@ -1,4 +1,4 @@
-import { T as ThemeManifest } from '../../_contract-CDa9-NdB.js';
+import { T as ThemeManifest } from '../../_contract-DlklV0Im.js';
 
 /**
  * Meridian — a Sable theme. Concrete token values live in

package/dist/themes/poppy/index.d.ts

@@ -1,4 +1,4 @@
-import { T as ThemeManifest } from '../../_contract-CDa9-NdB.js';
+import { T as ThemeManifest } from '../../_contract-DlklV0Im.js';
 
 /** Original Sable preset; no third-party artwork or reference-site code. */
 declare const poppyTheme: ThemeManifest;

package/dist/themes/prism/index.d.ts

@@ -1,4 +1,4 @@
-import { T as ThemeManifest } from '../../_contract-CDa9-NdB.js';
+import { T as ThemeManifest } from '../../_contract-DlklV0Im.js';
 
 /** Original Sable preset; no third-party artwork or reference-site code. */
 declare const prismTheme: ThemeManifest;

package/dist/themes/sable/index.d.ts

@@ -1,4 +1,4 @@
-import { T as ThemeManifest } from '../../_contract-CDa9-NdB.js';
+import { T as ThemeManifest } from '../../_contract-DlklV0Im.js';
 
 /**
  * Sable — the default theme. Concrete token values live in

package/dist/themes/verdant/index.d.ts

@@ -1,4 +1,4 @@
-import { T as ThemeManifest } from '../../_contract-CDa9-NdB.js';
+import { T as ThemeManifest } from '../../_contract-DlklV0Im.js';
 
 /**
  * Verdant — a Sable theme. Concrete token values live in

package/llms/components/activity-heatmap.md

@@ -0,0 +1,133 @@
+# ActivityHeatmap
+
+**Status:** stable
+
+A calendar heatmap: one value per day as a grid of weeks by weekdays — the GitHub contribution graph, for any daily measure. Levels by quartile, categories by source, a real ARIA grid with one tab stop, and a sideways scroll on narrow screens that opens on the latest week.
+
+**Keywords:** heatmap, calendar heatmap, contribution graph, contributions, activity, github, streak, habit, daily, commits, uptime
+
+## Usage
+
+Use ActivityHeatmap to show how often something happened day by day over weeks or months: commits, habits kept, orders, uptime. Pass days as ISO dates with a value; levels, colours, labels, keyboard and tooltips work with no further props. Put it inside a Card and compose any totals beside it (NumberTicker, StatRowBlock). For a value over time that a reader needs to compare precisely, use AreaChart or BarChart; for a month calendar with marked days (a streak calendar), use Calendar.
+
+### Best practices
+
+- Do: Pass dates as "YYYY-MM-DD" strings. The grid reads them as calendar days, so no time zone can shift a day — never build them with `new Date(...).toISOString()` from a local date.
+- Do: Give it a `unit` ("contribution" / "contributions") so the tooltip and every cell's name say what the number counts.
+- Do: Let the default quantile scale pick levels — one exceptional day then does not wash every other day out. Pass a day's own `level` when the source already has one (GitHub's API).
+- Don't: Use it for a handful of values or for values a reader must compare exactly; a heatmap shows rhythm, not amounts. Use BarChart. → use **BarChart**, **AreaChart**
+- Don't: Use it for a single month of marked days with a streak; that is Calendar with modifiers. → use **Calendar**
+- Don't: Fetch inside the component or call GitHub from the browser with a token. Fetch on your server and pass days in; `@sableui/react/adapters/github` converts GitHub's response.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Weekday labels | no | Short weekday names beside the rows, outside the scroller so the weeks never slide under them. |
+| Month labels | no | Short month names over each month's first week; they scroll with their weeks. |
+| Cell grid | yes | A role=grid table, one gridcell per day, inside a horizontal Scroller that opens on the latest week. |
+| Tooltip | no | The chart tooltip card, anchored to the hovered, focused or tapped day. |
+| Legend | no | A Less–More ramp for intensity, or swatches for categories. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| label | string | — | What the grid shows ("Contributions in 2026") — its caption and accessible name. |
+| data | ActivityDay[] \| Record<string, number> | — | The days: `{ date: "YYYY-MM-DD", value, level?, category? }[]`, or a map of date to value. Sparse is fine — a missing day is 0; duplicates sum. |
+| start | string | 53 weeks before end | First day drawn, "YYYY-MM-DD". The default starts at the beginning of that week, as GitHub's does. |
+| end | string | today | Last day drawn. Days after today inside the range are drawn hollow and skipped by the keyboard. |
+| year | number | — | Draw Jan 1 – Dec 31 of this year. Wins over start / end. |
+| weekStart | 0 \| 1 | the locale's | 0 puts Sunday on the top row, 1 Monday. |
+| levels | number | 5 | How many levels, including the empty level 0. |
+| levelScale | "quantile" \| "linear" \| number[] \| ((value, stats) => number) | "quantile" | How a value becomes a level. Quantile splits the positive values evenly, as GitHub does; an array gives each level's lower bound from 1 up; a function decides. A day's own `level` always wins. |
+| tone | ChartTone | "1" | The hue of the intensity ramp. Decorative tones lead, as on every chart; "success" gives the GitHub look. |
+| categories | ChartCategories | — | Colour days by `day.category` (label, tone or colour per key). Pair with `levels={2}` for flat category colours. |
+| unit | string \| { one: string; other: string } | — | Names the value in the tooltip and each cell's accessible name, pluralised with Intl.PluralRules. |
+| formatValue | (value: number) => string | full to 9,999, compact past | Formats a value wherever it is shown or read. |
+| tooltip | boolean \| ((day: ActivityHeatmapDay) => ReactNode) | true | Show the tooltip on hover, focus and tap; a function replaces its content on the same card. |
+| legend | boolean | true | The Less–More ramp for intensity, swatches for categories. |
+| legendLabels | [string, string] | ["Less", "More"] | The ramp's end words. |
+| monthLabels | boolean | true | Short month names over each month's first week. |
+| weekdayLabels | "alternate" \| "all" \| "none" | "alternate" | Which weekday names to show beside the rows; alternate is Mon, Wed, Fri. |
+| size | "sm" \| "md" \| "lg" | "md" | The smallest a cell may get (10, 12, 14 px) before the grid scrolls instead of shrinking. |
+| stretch | boolean | true | Grow cells to fill the width, up to 20 px. false keeps them at `size`. |
+| activeDate | string \| null | — | The hovered or focused day, controlled. Pair with defaultActiveDate / onActiveDateChange. |
+| selectedDate | string \| null | — | The selected day, controlled. Selection is on only when onSelectDate is set. |
+| onSelectDate | (date: string) => void | — | Called when a day is clicked or chosen with Enter / Space — to filter a feed below, as GitHub does. |
+| renderCell | (day, cell) => ReactNode | — | Draw something over a cell's fill — an icon for a milestone, a reward, an outage. |
+| loading | boolean | false | Draw the empty grid, shimmering, while data loads. |
+| motion | "full" \| "subtle" \| "off" | "full" | Turns the arrival down; `subtle` shows the finished grid at once. |
+| locale | string | runtime locale | Month and weekday names, numbers and plurals. |
+
+## Tokens used
+
+`foreground`, `muted-foreground`, `border-strong`, `ring`, `tone-1-mark`, `tone-2-mark`, `tone-3-mark`, `success-mark`, `tone-info-mark`
+
+## Motion
+
+- **arrival** · Cell grid · _custom (outside the recipe layer)_ — Weeks fade in left to right as the grid first scrolls into view, staggered on the chart motion helpers; expressive, so subtle shows the finished grid.
+- **response** · Cell · _custom (outside the recipe layer)_ — The active day takes a ring outline at once and the tooltip glides to it; the other cells stay still — dimming hundreds of cells reads as a flash.
+- **transition** · Cell · _custom (outside the recipe layer)_ — When data or the range changes, each cell's fill cross-fades on the base duration token, so the reader sees which days changed.
+- **activity** · Cell grid · `motion-shimmer` — `loading` shimmers the empty grid until days arrive.
+
+## Accessibility
+
+- The grid is a role=grid table, as GitHub's is: weekday row headers and month column headers carry full names for screen readers, and the caption is `label`.
+- One tab stop. Arrows move a day or a week; Home / End go to the ends of the row, Page Up / Page Down to the ends of the column, Ctrl+Home / Ctrl+End to the first and last day. Enter or Space selects when onSelectDate is set; Escape hides the tooltip.
+- Each cell is named with its date and value ("Tuesday, October 14, 2026: 12 contributions") and described by its level's words, which the legend repeats visually.
+- Levels rise in lightness, so they read without colour; under forced colours each level draws as a larger inner square.
+
+## Related
+
+- Components: Card, NumberTicker, BarChart, Calendar, Scroller
+
+## Examples
+
+### Contributions, last year
+
+```tsx
+import { ActivityHeatmap } from "@sableui/react"
+
+const days = [
+	{ date: "2026-10-12", value: 4 },
+	{ date: "2026-10-13", value: 11 },
+	{ date: "2026-10-14", value: 2 },
+]
+
+<ActivityHeatmap label="Contributions in the last year" data={days} tone="success" unit={{ one: "contribution", other: "contributions" }} />
+```
+
+### Two sources, in a card
+
+```tsx
+import { ActivityHeatmap, Card, CardContent, CardHeader, CardTitle, mergeActivity } from "@sableui/react"
+
+const github = [{ date: "2026-10-13", value: 6 }]
+const codex = [{ date: "2026-10-13", value: 1 }, { date: "2026-10-14", value: 3 }]
+
+<Card>
+	<CardHeader>
+		<CardTitle>Building, day by day</CardTitle>
+	</CardHeader>
+	<CardContent>
+		<ActivityHeatmap
+			label="GitHub and Codex activity in 2026"
+			year={2026}
+			levels={2}
+			data={mergeActivity({ github, codex })}
+			categories={{ github: { label: "GitHub", tone: "success" }, codex: { label: "Codex", tone: "info" }, both: { label: "Both", tone: "2" } }}
+		/>
+	</CardContent>
+</Card>
+```
+
+### Selecting a day
+
+```tsx
+import { ActivityHeatmap } from "@sableui/react"
+
+const [day, setDay] = useState<string | null>(null)
+
+<ActivityHeatmap label="Orders per day" data={{ "2026-10-13": 18, "2026-10-14": 25 }} unit="orders" selectedDate={day} onSelectDate={setDay} />
+```

package/llms/components/avatar.md

@@ -2,9 +2,9 @@
 
 **Status:** stable
 
-Circular profile image over Base UI Avatar — automatic image-load tracking with an initials/glyph fallback. Ergonomic Avatar plus low-level AvatarRoot/AvatarImage/AvatarFallback parts, and AvatarGroup for an overlapping stack with a "+N" overflow count.
+Circular (or square) profile image over Base UI Avatar — automatic image-load tracking with an initials/glyph fallback. Ergonomic Avatar plus low-level AvatarRoot/AvatarImage/AvatarFallback parts, and AvatarGroup for an overlapping stack with a "+N" overflow count.
 
-**Keywords:** avatar, profile, user, identity, initials, fallback, group, team, stack, overflow, collaborators, facepile
+**Keywords:** avatar, profile, user, identity, initials, fallback, group, team, stack, overflow, collaborators, facepile, monogram, project mark, workspace icon, org logo, assignee
 
 ## Usage
 
@@ -15,12 +15,13 @@ Use Avatar to represent a person, team, or account with a compact visual identit
 - Do: Use `variant="art"` where people without photos sit side by side — a member list, an activity feed, a chat. Seeded by the person, each gets their own colour, so faces stay tellable apart at a glance; the neutral fallback makes everyone the same grey circle.
 - Do: Provide meaningful alt text for profile images, or an empty alt when the adjacent text already names the person.
 - Do: Use initials or a simple glyph fallback so missing images still communicate identity.
-- Do: Pick the size by the job: sm in dense rows and tables, md (the default) beside one line of text, lg in a row with a title and subtitle, xl (96px) for a profile header beside the person's name, 2xl (160px) for an artist or profile hero and roster portraits. Keep one size within a list or group.
+- Do: Pick the size by the job: 2xs (20px) or xs (24px) in a compact workspace row (an assignee in an issue list, a project mark in a nav item), sm in dense rows and tables, md (the default) beside one line of text, lg in a row with a title and subtitle, xl (96px) for a profile header beside the person's name, 2xl (160px) for an artist or profile hero and roster portraits. Keep one size within a list or group.
 - Do: Use AvatarGroup for a stack of people, and give it an aria-label with the real count ("12 collaborators"). Set `surface` (or `--avatar-group-ring`) to whatever the group sits on, so the separating ring matches a card or popover, not the page. When it shares a row with actions, set `fit` so it gives up avatars to the "+N" count before the row has to wrap.
+- Do: Use `shape="square"` for what is not a person (a workspace, a project, an org, a team), with `tone` set to a palette family so each one keeps its own colour: `<Avatar shape="square" tone="teal" fallback="N" alt="Northwind storefront" size="xs" />`. Circles mean people; keep that distinction across the app.
 - Don't: Hand-build a stack with negative margins and per-avatar ring classes, or fake the overflow as an Avatar with "+4" initials — screen readers hear "plus 4" with no context. Use AvatarGroup's `max`/`total`, or AvatarGroupCount.
 - Don't: Use avatars as decoration without nearby identity context. They should help users recognize a person or account.
 - Don't: Overload a dense table with large avatars; use sm or omit images when scanning data is more important.
-- Don't: Build a portrait by stretching an Avatar with size classes (`className="size-40"`) — the initials, the status indicator and the image fade stay at row scale. Use size="xl" or "2xl", which scale all three. Past 160px, or for a non-circular cover, it is media: an AspectBox, not an avatar.
+- Don't: Resize an Avatar with size classes (`className="size-5"`, `className="size-40"`) — the initials, the status indicator and the image fade stay at the size they were drawn for. Use size="2xs"/"xs" for dense rows and size="xl"/"2xl" for portraits, which scale all three. Don't hand-build a tinted initials tile for a project or workspace mark either: that is Avatar shape="square" with a tone. Past 160px, or for a cover, it is media: an AspectBox, not an avatar.
 
 ### Anatomy
 
@@ -36,11 +37,11 @@ Use Avatar to represent a person, team, or account with a compact visual identit
 
 | Name | Type | Description |
 | --- | --- | --- |
-| AvatarRoot | Base UI Avatar.Root props + size + className | Low-level circular frame for full composition control — clips the image and holds the `size` axis. Wraps AvatarImage and AvatarFallback. |
+| AvatarRoot | Base UI Avatar.Root props + size + shape + tone + className | Low-level circular frame for full composition control — clips the image and holds the `size` axis. Wraps AvatarImage and AvatarFallback. |
 | AvatarImage | Base UI Avatar.Image props + className | The profile image. Fills and crops the frame; hidden by Base UI until it loads. |
 | AvatarFallback | Base UI Avatar.Fallback props (delay) + className | Shown when no image is available — typically initials or a glyph. Accepts a delay prop. |
-| AvatarGroup | { size?: "sm" \| "md" \| "lg"; surface?: "background" \| "card" \| "popover" \| "muted"; max?: number; fit?: boolean; total?: number; countLabel?: (count: number) => string; "aria-label"?: string; className?: string; children: ReactNode } | Overlapping stack (role=group) — name it with aria-label ("12 collaborators"). `size` applies to every avatar inside. `max` shows that many and collapses the rest into a "+N" count; `total` is the real head-count when you only pass some people. `fit` shows only as many avatars as fit the width the group is given (it fills the space left in a flex row) and folds the rest into the count, so a tight row reads "MO SR +5" instead of wrapping. The separating ring reads the inherited `--avatar-group-ring` (default: the page background); `surface` sets it to card, popover, or muted. |
-| AvatarGroupCount | { count: number; label?: string; size?: "sm" \| "md" \| "lg"; className?: string } | The "+N" avatar. Shows "+4" and reads "and 4 more" (override with label). AvatarGroup renders it for you from max/total; use it directly only when composing the stack yourself. |
+| AvatarGroup | { size?: "2xs" \| "xs" \| "sm" \| "md" \| "lg"; surface?: "background" \| "card" \| "popover" \| "muted"; max?: number; fit?: boolean; total?: number; countLabel?: (count: number) => string; "aria-label"?: string; className?: string; children: ReactNode } | Overlapping stack (role=group) — name it with aria-label ("12 collaborators"). `size` applies to every avatar inside. `max` shows that many and collapses the rest into a "+N" count; `total` is the real head-count when you only pass some people. `fit` shows only as many avatars as fit the width the group is given (it fills the space left in a flex row) and folds the rest into the count, so a tight row reads "MO SR +5" instead of wrapping. The separating ring reads the inherited `--avatar-group-ring` (default: the page background); `surface` sets it to card, popover, or muted. |
+| AvatarGroupCount | { count: number; label?: string; size?: "2xs" \| "xs" \| "sm" \| "md" \| "lg"; className?: string } | The "+N" avatar. Shows "+4" and reads "and 4 more" (override with label). AvatarGroup renders it for you from max/total; use it directly only when composing the stack yourself. |
 
 ## Props
 
@@ -51,13 +52,16 @@ Use Avatar to represent a person, team, or account with a compact visual identit
 | fallback | ReactNode | — | Initials or a glyph rendered when no image is displayed. |
 | fallbackDelay | number | — | Delay before showing the fallback, in ms — avoids a flash on fast loads. |
 | status | ReactNode | — | A presence indicator pinned to the bottom-end edge, usually <StatusDot tone="success" />. It sits outside the clipped circle and wears a ring in the surface colour (--avatar-group-ring, else the page background). Use this instead of absolutely positioning a dot over an Avatar. |
-| size | "sm" \| "md" \| "lg" \| "xl" \| "2xl" | "md" | Square footprint: 32px / 40px / 48px for rows; 96px / 160px for portraits (a profile header, an artist hero, a roster tile). The initials, a status indicator and its cut-out ring scale with it, and at the portrait sizes the photo fades in over the resting surface. |
+| size | "2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" | "md" | Square footprint: 20px / 24px for compact workspace rows; 32px / 40px / 48px for rows; 96px / 160px for portraits (a profile header, an artist hero, a roster tile). The initials, a status indicator and its cut-out ring scale with it, and at the portrait sizes the photo fades in over the resting surface. |
+| shape | "circle" \| "square" | "circle" | The frame's corner. circle is a person. square is what is not a face — a workspace, a project, an org, a team — with a radius from the theme's steps that grows with the size (4px at 20–24px to 20px at 160px), so a square theme stays square. A status indicator sits on the square's corner. |
+| tone | "neutral" \| "red" \| "orange" \| "yellow" \| "green" \| "teal" \| "blue" \| "purple" \| "pink" | "neutral" | The fallback's colour. neutral is the muted surface; a palette family paints its wash behind the initials and its deep ink on them (a soft Badge's pair, held to contrast in every theme), for a category colour such as one per project. Ignored by variant="art", which colours by seed. |
 | variant | "neutral" \| "art" | "neutral" | What the fallback looks like. neutral: initials on the muted surface. art: initials over GradientArt seeded by the person, so each person without a photo gets their own stable colour from the theme. |
 | seed | string \| number | — | The art variant's seed. Defaults to the fallback text, then `alt`, so a person keeps one colour wherever they appear; pass a user id to tell apart two people who share initials. |
 
 ## Variants
 
-- **size**: sm, md, lg, xl, 2xl
+- **size**: 2xs, xs, sm, md, lg, xl, 2xl
+- **shape**: circle, square
 - **variant**: neutral, art
 
 ## Tokens used
@@ -134,6 +138,25 @@ import { Avatar, StatusDot } from "@sableui/react"
 </div>
 ```
 
+### Dense row sizes
+
+```tsx
+import { Avatar } from "@sableui/react"
+
+<Avatar fallback="EL" alt="Emma Lee" size="2xs" />
+<Avatar fallback="EL" alt="Emma Lee" size="xs" />
+```
+
+### Project marks
+
+```tsx
+import { Avatar } from "@sableui/react"
+
+<Avatar shape="square" tone="teal" size="xs" fallback="N" alt="Northwind storefront" />
+<Avatar shape="square" tone="orange" size="xs" fallback="H" alt="Harbor brand refresh" />
+<Avatar shape="square" tone="purple" size="xs" fallback="L" alt="Lumen editorial" />
+```
+
 ### Low-level parts
 
 ```tsx

package/llms/components/code-block.md

@@ -40,6 +40,7 @@ Use CodeBlock for multiline code samples that users may read, inspect, or copy.
 | showCopy | boolean | true | Show the copy affordance — in the header bar with a filename, floating in the corner without one. |
 | highlight | ((code: string) => ReactNode) \| false | — | Highlighter for this block; overrides CodeHighlightProvider. false renders plain text inside a provider. |
 | prompt | string | — | A shell prompt ("$", ">"). Makes it a one-line command: the prompt is dimmed and unselectable, the line truncates, and copy takes only code. |
+| wrap | boolean | false | Wrap long lines instead of scrolling them. For prose in a code face (a prompt to paste into an agent, a log line); code keeps scrolling, since wrapping breaks its indentation. |
 
 ## Tokens used
 

package/llms/components/collapsible.md

@@ -4,7 +4,7 @@
 
 Show/hide a panel of content over Base UI Collapsible — open/close state, ARIA expanded wiring, and the animated height transition. The minimal primitive behind Accordion: a trigger that toggles an overflow-clipped panel.
 
-**Keywords:** collapsible, disclosure, expand, collapse
+**Keywords:** collapsible, disclosure, expand, collapse, chevron, caret, rotate, group header, section toggle
 
 ## Usage
 
@@ -31,7 +31,7 @@ Use Collapsible for a single piece of optional content that can expand in place.
 | --- | --- | --- |
 | CollapsibleTrigger | Base UI Collapsible.Trigger props + render | The button that toggles the panel. Compose with render={<Button variant="ghost" … />}. |
 | CollapsiblePanel | Base UI Collapsible.Panel props + className (keepMounted, hiddenUntilFound) | The collapsible contents. Overflow-hidden; animates height via the --collapsible-panel-height var Base UI sets. |
-| CollapsibleIndicator | { className? } | Auto-rotating disclosure chevron. Place it inside the trigger content and add the `group/collapsible` class to the trigger so it flips 180° on open. |
+| CollapsibleIndicator | { direction?: "down" \| "end"; className? } | Auto-rotating disclosure chevron. Place it anywhere inside the trigger content; it reads the trigger's open state itself, no class to add. direction="down" (default) flips 180° on open; direction="end" points to the inline end while closed and turns down on open — the caret for a grouped list's section header or a tree row. Use it instead of rotating your own chevron with CSS, which snaps with no transition. |
 
 ## Props
 
@@ -50,7 +50,7 @@ Use Collapsible for a single piece of optional content that can expand in place.
 - **arrival** · Root · _no motion_ — A collapsible is part of the page it sits in, present from first paint. Its trigger is what the reader notices, not an entrance.
 - **response** · CollapsibleTrigger · _no motion_ — The trigger is whatever the consumer renders (usually a Button), and that control brings its own response. Adding one here would double it.
 - **transition** · CollapsiblePanel · `motion-disclosure` — The height change ties the content that appears to the trigger that was pressed; snapped open, everything below jumps with nothing linking cause to effect.
-- **transition** · CollapsibleIndicator · `motion-interactive` — The chevron turns with the panel rather than flipping in one frame: motion-interactive lists `rotate`, the property rotate-180 writes.
+- **transition** · CollapsibleIndicator · `motion-interactive` — The chevron turns with the panel rather than flipping in one frame: motion-interactive lists `rotate`, the property rotate-180 and rotate-0 write.
 - **activity** · Root · _no motion_ — Nothing here is indeterminate; content that loads on open should put its own loader inside the panel.
 
 ## Accessibility
@@ -87,5 +87,13 @@ import { Button, Collapsible, CollapsiblePanel, CollapsibleTrigger } from "@sabl
 ```tsx
 import { Button, Collapsible, CollapsibleIndicator, CollapsiblePanel, CollapsibleTrigger } from "@sableui/react"
 
-<Collapsible><CollapsibleTrigger className="group/collapsible" render={<Button variant="ghost">Details <CollapsibleIndicator /></Button>} /><CollapsiblePanel><p className="pt-3">Revealed on toggle.</p></CollapsiblePanel></Collapsible>
+<Collapsible><CollapsibleTrigger render={<Button variant="ghost">Details <CollapsibleIndicator /></Button>} /><CollapsiblePanel><p className="pt-3">Revealed on toggle.</p></CollapsiblePanel></Collapsible>
+```
+
+### Group header with a side caret
+
+```tsx
+import { Button, Collapsible, CollapsibleIndicator, CollapsiblePanel, CollapsibleTrigger } from "@sableui/react"
+
+<Collapsible defaultOpen><CollapsibleTrigger render={<Button variant="ghost" size="xs"><CollapsibleIndicator direction="end" />In progress <span className="text-ui-num text-muted-foreground">5</span></Button>} /><CollapsiblePanel><ul className="text-ui-body"><li>Refine product detail page</li><li>Build the ingredient library</li></ul></CollapsiblePanel></Collapsible>
 ```

package/llms/components/data-table.md

@@ -2,9 +2,9 @@
 
 **Status:** stable
 
-A data-driven table over the Table primitives — a columns def + data array with built-in client-side sorting (click a sortable header to cycle asc → desc → none), optional row click / selection, and an empty state. For server data or paging, sort/page the data and pair with Pagination.
+A data-driven table over the Table primitives — a columns def + data array with built-in client-side sorting (click a sortable header to cycle asc → desc → none), optional row click / selection, rows grouped under collapsible header rows (groupBy), and an empty state. For server data or paging, sort/page the data and pair with Pagination.
 
-**Keywords:** data table, table, sortable, columns, rows, empty state, pagination, list
+**Keywords:** data table, table, sortable, columns, rows, empty state, pagination, list, grouped, group by, sections, issue list, issue tracker, status groups, collapsible groups
 
 ## Usage
 
@@ -16,7 +16,8 @@ Use DataTable when a data array and column definition should render a sortable,
 - Do: Provide stable rowKey values for dynamic data so selection and sorting do not jump.
 - Do: Use sortable only on columns where ordering is obvious and useful.
 - Do: Pair server-side datasets with Pagination and pass already-sorted/paged rows.
-- Do: Move to TanStack Table, rendered with Sable's Table parts, once the table needs server-side sorting or filtering, column visibility or resizing, grouping, or virtualised rows. DataTable stays dependency-free and does not grow into a data grid; `sable docs tables-with-tanstack` maps one onto the other.
+- Do: Group rows by status for an issue tracker (or by owner, by day) with groupBy + groups on ONE DataTable: every group shares the header and the column widths, each header row carries the group's count and an add action, and sorting applies within each group. Do not stack one DataTable per group inside Collapsibles; the header repeats and the columns stop lining up.
+- Do: Move to TanStack Table, rendered with Sable's Table parts, once the table needs server-side sorting or filtering, column visibility or resizing, nested or aggregated grouping, or virtualised rows. DataTable stays dependency-free and does not grow into a data grid; `sable docs tables-with-tanstack` maps one onto the other.
 - Don't: Make every row clickable and also fill it with competing buttons. Choose a clear row interaction model.
 - Don't: Use DataTable for heterogeneous cards or timeline content. A list or card layout will scan better.
 
@@ -27,6 +28,7 @@ Use DataTable when a data array and column definition should render a sortable,
 | Columns | yes | Definitions for headers, cell renderers, sorting, alignment, and classes. |
 | Rows | yes | The data array rendered through the column definitions. |
 | Empty state | no | Content spanning all columns when the row array is empty. |
+| Group header row | no | With groupBy: one row per group heading its own tbody (a th with scope=rowgroup across every column) holding the disclosure toggle, the group's icon, label and count, and an optional trailing action. |
 | Caption | no | Accessible table caption rendered by the underlying Table. |
 
 ## Props
@@ -45,6 +47,11 @@ Use DataTable when a data array and column definition should render a sortable,
 | defaultSort | { key: string; direction: "asc" \| "desc" } | — | Initial sort column + direction. |
 | empty | ReactNode | "No results." | Rendered spanning all columns when data is empty. Pass an EmptyState for the full treatment (icon, title, next step). |
 | caption | ReactNode | — | Bottom table caption. |
+| groupBy | (row) => string | — | Group the rows under header rows by the key this returns (a status, an owner, a day). One header serves every group, so the columns line up across them; sorting applies within each group. |
+| groups | { key: string; label?: ReactNode; icon?: ReactNode; action?: ReactNode; defaultExpanded?: boolean }[] | — | Order and presentation of the groups, by key: the header row's label (defaults to the key), a leading icon such as a status mark, a trailing action such as an icon Button that adds a row to the group, and whether it starts open (default true). Groups groupBy returns that are not listed follow, in the order their first row appears in data. A listed group with no rows is not shown. |
+| collapsible | boolean | true | Whether each group's header row is a toggle that opens and closes the group. A closed group keeps its header row and count; its rows are hidden and select-all skips them. |
+| expandedGroups | ReadonlySet<string> | — | The open groups, by key (controlled). Without it each group starts at its defaultExpanded and the table holds the state. |
+| onExpandedGroupsChange | (keys: Set<string>) => void | — | Called with the new set of open group keys when a group header is toggled. |
 
 ## Tokens used
 
@@ -53,9 +60,11 @@ Use DataTable when a data array and column definition should render a sortable,
 ## Motion
 
 - **arrival** · Root · _no motion_ — Rows render with the page or the query that produced them. Staggering rows in delays reading a table someone opened to scan.
+- **arrival** · Group rows · _no motion_ — Opening a group shows its rows at once: table rows cannot animate their height without leaving the table layout, and the rows are the content the reader asked for.
 - **response** · Row · `motion-interactive` — Body rows ease to a muted wash under the pointer (TableRow's recipe), which keeps the eye on the right line across a wide row of numbers. Sortable headers are ghost Buttons and answer on Button's recipe.
 - **transition** · Sort chevron · `motion-interactive` — One chevron turns to show direction instead of two glyphs swapping, so ascending to descending reads as the same column reversing. Its opacity rises from the resting 60% as the column becomes the sort.
 - **transition** · Row · `motion-interactive` — A checked row's fill eases in across its cells, so selecting by checkbox reads as the row being picked rather than a band stamped over it.
+- **transition** · Group chevron · `motion-interactive` — A group's chevron turns from pointing along the reading direction (closed) to down (open), so the group reads as folding rather than a glyph being swapped.
 - **activity** · Root · _no motion_ — DataTable has no loading state. While data is fetched, render Skeleton rows (motion-shimmer) in its place — only the caller knows a fetch is in flight.
 
 ## Accessibility
@@ -63,6 +72,7 @@ Use DataTable when a data array and column definition should render a sortable,
 - Sorted columns set aria-sort=ascending/descending on the header cell.
 - Sortable headers are real <button>s with a focus-visible ring, keyboard-operable.
 - Inherits the Table's scrollable frame and semantic <table>/<th>/<td> structure.
+- Grouped, each group is its own <tbody> (a rowgroup) headed by a <th scope="rowgroup"> spanning the columns, so group headers are never read as data rows; the toggle is a real button with aria-expanded and aria-controls naming that tbody.
 
 ## Related
 
@@ -131,6 +141,33 @@ import { Card, CardContent, CardHeader, CardTitle, DataTable } from "@sableui/re
 <Card><CardHeader><CardTitle>Deployments</CardTitle></CardHeader><CardContent flush><DataTable data={deployments} rowKey={(row) => row.id} columns={[{ key: "project", header: "Project", sortable: true }, { key: "duration", header: "Duration", align: "end" }]} /></CardContent></Card>
 ```
 
+### Issues grouped by status
+
+```tsx
+import { Button, DataTable, Icon, StatusDot } from "@sableui/react"
+
+const STATUSES = [
+	{ key: "in-progress", label: "In progress", icon: <StatusDot tone="warning" /> },
+	{ key: "in-review", label: "In review", icon: <StatusDot tone="purple" /> },
+	{ key: "todo", label: "Todo", icon: <StatusDot /> },
+	{ key: "done", label: "Done", icon: <StatusDot tone="success" />, defaultExpanded: false },
+]
+
+<DataTable
+	data={issues}
+	rowKey={(t) => t.id}
+	groupBy={(t) => t.status}
+	groups={STATUSES.map((s) => ({ ...s, action: <Button variant="ghost" size="icon-xs" aria-label={`Add issue to ${s.label}`} onClick={() => create(s.key)}><Icon name="plus" /></Button> }))}
+	onRowClick={(t) => setSelectedId(t.id)}
+	isRowSelected={(t) => t.id === selectedId}
+	columns={[
+		{ key: "id", header: "ID", className: "w-20", cell: (t) => <span className="text-mono-caption text-muted-foreground">{t.id}</span> },
+		{ key: "title", header: "Issue", sortable: true },
+		{ key: "due", header: "Due", sortable: true, sortValue: (t) => t.due.getTime(), cell: (t) => formatDate(t.due) },
+	]}
+/>
+```
+
 ### Empty state
 
 ```tsx

package/llms/components/date-picker.md

@@ -4,7 +4,7 @@
 
 Date (and optionally time) picker: a field-shaped trigger (the Input / SelectTrigger shell) opens a Popover holding Sable's Calendar. With granularity="day" selecting a day fires onValueChange and closes; granularity="minute" adds an hour + minute row of Selects and keeps the time-of-day when the day changes.
 
-**Keywords:** date picker, calendar, date input, date time picker, time, schedule, form
+**Keywords:** date picker, due date, property row, inspector, calendar, date input, date time picker, time, schedule, form
 
 ## Usage
 
@@ -33,6 +33,8 @@ Use DatePicker when users need to choose one date — or, with granularity="minu
 | disabled | boolean | — | Disable the trigger and block selection. |
 | minDate | Date | — | Earliest selectable day (inclusive). Earlier days are disabled and navigation is bounded. |
 | maxDate | Date | — | Latest selectable day (inclusive). Later days are disabled and navigation is bounded. |
+| size | "md" \| "xs" | "md" | The trigger's rung. md is the form field beside Input and Select. xs is the property-grid rung (24px in a workspace): an inset panel-field well with no border, the same shape as SelectTrigger size="xs" and ScrubField on the neighbouring rows of an inspector — use it for a due date in a PropertyRow instead of a native date input. |
+| formatOptions | Intl.DateTimeFormatOptions | — | How the trigger writes the chosen date, as Intl.DateTimeFormat options in the reader's locale — { month: "short", day: "numeric" } for "Oct 23" where the rest of a list writes dates that way. Omitted: "Oct 23, 2026" (with "at 14:30" under granularity="minute"). |
 | className | string | — | Extra classes merged onto the trigger. |
 | id / aria-label / aria-labelledby / aria-describedby / aria-invalid / aria-required | button attributes | — | Forwarded to the trigger, so a wrapping Field ties its label to the picker and announces its description and error. Pass them yourself only when labelling the picker without a Field. |
 
@@ -54,6 +56,18 @@ Use DatePicker when users need to choose one date — or, with granularity="minu
 
 ## Examples
 
+### In an inspector row
+
+```tsx
+import { DatePicker, PanelSection, PropertyRow } from "@sableui/react"
+
+<PanelSection title="Properties">
+	<PropertyRow label="Due date">
+		<DatePicker size="xs" aria-label="Due date" value={due} onValueChange={setDue} formatOptions={{ month: "short", day: "numeric" }} />
+	</PropertyRow>
+</PanelSection>
+```
+
 ### Controlled
 
 ```tsx

package/llms/components/dialog.md

@@ -17,11 +17,14 @@ Use Dialog for focused decisions, short modal forms, confirmations, and content
 - Do: Use showCloseButton for dismissible informational dialogs; keep destructive confirmations action-led.
 - Do: In a destructive confirmation, state the consequence in DialogDescription ("This is permanent.") and reserve the destructive button variant for actions that cannot be undone.
 - Do: Use size="fullscreen" when an image, video, or gallery needs a larger view than the layout can give it. Give the popup an accessible name (aria-label on DialogContent, or a visually hidden DialogTitle) and alt text on the media.
+- Do: Open a dialog from your own button with controlled open/onOpenChange when the trigger is not a DialogTrigger (a menu item, a row action, a keyboard shortcut). Focus returns on close to whatever held it when the dialog opened, with no finalFocus wiring; pass finalFocus only to send it somewhere else.
+- Do: Set keepMounted on DialogContent for a draft the user may come back to (a compose form, a long comment, a half-filled request). Closing by Esc or a stray click then hides the dialog instead of unmounting it, so the fields are still filled when it reopens. Clear the draft yourself on submit or discard.
 - Do: Use the AlertDialog family for a confirmation that must be answered (discard changes, leave without saving). It looks identical but is role="alertdialog" and a backdrop click does not dismiss it — only Cancel, Esc, or the action. For irreversible deletes, use DestructiveActionModal, which is built on it.
 - Don't: Put large multipage workflows in a centered dialog. Use Sheet or a page route when the task needs space. → use **Sheet**
 - Don't: Use size="fullscreen" for forms, confirmations, or anything that isn't media. A dialog that happens to need room is a Sheet or a page; the fullscreen affordances (dark scrim, corner close, centred content) all assume something to look at. → use **Sheet**
 - Don't: Hide the close button at size="fullscreen" without another visible way out. A full-bleed viewer that only Esc dismisses is a dead end for anyone who doesn't know the key.
 - Don't: Open a dialog for passive status updates. Use Toast, Banner, or InlineStatus instead. → use **Toast**, **Banner**, **InlineStatus**
+- Don't: Set keepMounted by default. A dialog that should open fresh (a confirmation, a create form after a successful save) would show stale input, and live content (polling, video) keeps running while hidden.
 
 ### Anatomy
 
@@ -37,7 +40,7 @@ Use Dialog for focused decisions, short modal forms, confirmations, and content
 
 | Name | Type | Description |
 | --- | --- | --- |
-| DialogContent | Base UI Popup props + size?: "default" \| "fullscreen" + showCloseButton?: boolean + scroll?: boolean + className | Backdrop + popup; portals to <body>. Composes DialogOverlay by default. size="fullscreen" is the media viewer: a near-opaque scrim (bg-overlay/95), an edge-to-edge popup that centres its children with no card chrome, motion-fade instead of motion-pop, and a safe-area-aware floating close button (Button variant="floating"); at that size showCloseButton defaults to true and scroll to false, and the media fits itself with max-h-full max-w-full object-contain. At the default size, showCloseButton (defaults to false) renders a built-in close (X) button in the top-end corner, and the header leaves room for it (Icon name="xmark"). The popup caps at the viewport height less a 1rem margin and wraps its children in a scrolling region, so a tall dialog scrolls instead of overflowing a viewport whose own scroll is locked; pass scroll={false} when the dialog owns its internal layout (a pinned header over a scrolling body) and supplies its own min-h-0 scroll region. |
+| DialogContent | Base UI Popup props (initialFocus, finalFocus) + size?: "default" \| "fullscreen" + showCloseButton?: boolean + scroll?: boolean + keepMounted?: boolean + className | Backdrop + popup; portals to <body>. Composes DialogOverlay by default. size="fullscreen" is the media viewer: a near-opaque scrim (bg-overlay/95), an edge-to-edge popup that centres its children with no card chrome, motion-fade instead of motion-pop, and a safe-area-aware floating close button (Button variant="floating"); at that size showCloseButton defaults to true and scroll to false, and the media fits itself with max-h-full max-w-full object-contain. At the default size, showCloseButton (defaults to false) renders a built-in close (X) button in the top-end corner, and the header leaves room for it (Icon name="xmark"). The popup caps at the viewport height less a 1rem margin and wraps its children in a scrolling region, so a tall dialog scrolls instead of overflowing a viewport whose own scroll is locked; pass scroll={false} when the dialog owns its internal layout (a pinned header over a scrolling body) and supplies its own min-h-0 scroll region. keepMounted (default false) keeps the content mounted and hidden while closed, so a draft survives close and reopen. finalFocus defaults to the element focused when the dialog opened, trigger or not; an explicit finalFocus (a ref, a function, or false) wins. |
 | DialogOverlay | Base UI Backdrop props + size?: "default" \| "fullscreen" + className | The styleable scrim/backdrop — bg-overlay/(--scrim-alpha) by default (50% light, 72% dark, so it dims a near-black page as visibly as a white one), near-opaque bg-overlay/95 at size="fullscreen". Composed into DialogContent (at the matching size) by default; exported for manual styling. |
 | DialogTrigger | Base UI Dialog.Trigger props (render) | Element that opens the dialog. Compose via render prop. |
 | DialogClose | Base UI Dialog.Close props (render) | Element that dismisses the dialog. Compose via render prop. |
@@ -45,7 +48,7 @@ Use Dialog for focused decisions, short modal forms, confirmations, and content
 | DialogTitle | Base UI Dialog.Title props + className | The dialog's accessible name — wires aria-labelledby on the popup. |
 | DialogDescription | Base UI Dialog.Description props + className | Muted supporting line; wires aria-describedby. |
 | DialogFooter | ComponentProps<"div"> | Bottom action row (right-aligned buttons). |
-| AlertDialog (Root) | Base UI AlertDialog.Root props (open, defaultOpen, onOpenChange) | Root for a confirmation that needs an answer. Always modal; the popup is role="alertdialog" and a click outside does not dismiss — only an AlertDialogClose, an action that sets open to false, or Esc. |
+| AlertDialog (Root) | Base UI AlertDialog.Root props (open, defaultOpen, onOpenChange) | Root for a confirmation that needs an answer. Always modal; the popup is role="alertdialog" and a click outside does not dismiss — only an AlertDialogClose, an action that sets open to false, or Esc. Returns focus on close to the element focused when it opened, exactly as Dialog does. |
 | AlertDialogTrigger | Base UI AlertDialog.Trigger props (render) | Opens the alert dialog. |
 | AlertDialogContent / AlertDialogOverlay / AlertDialogTitle / AlertDialogDescription / AlertDialogHeader / AlertDialogFooter / AlertDialogClose | Same props as the matching Dialog part | The Dialog parts under AlertDialog names — Base UI shares the popup, backdrop, title, description and close parts between the two, so the surface is identical. Pass initialFocus to AlertDialogContent (a ref to the Cancel button) to open focus on the safe action. |
 
@@ -53,7 +56,10 @@ Use Dialog for focused decisions, short modal forms, confirmations, and content
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| Dialog (Root) | Base UI Dialog.Root props (open, defaultOpen, onOpenChange, modal) | — | Controls open state. Uncontrolled by default. |
+| Dialog (Root) | Base UI Dialog.Root props (open, defaultOpen, onOpenChange, modal) | — | Controls open state. Uncontrolled by default. Records the element that holds focus when the dialog opens (through a DialogTrigger, or your own button flipping a controlled open) and returns focus there on close. |
+| open | boolean | — | Controlled open state. Pair with onOpenChange — for a dialog opened from your own button instead of a DialogTrigger. |
+| defaultOpen | boolean | false | Initial open state when uncontrolled. |
+| onOpenChange | (open: boolean, eventDetails) => void | — | Called when the dialog asks to open or close (a trigger, Esc, an outside click, DialogClose). |
 
 ## Variants
 
@@ -75,6 +81,8 @@ Use Dialog for focused decisions, short modal forms, confirmations, and content
 
 - Base UI provides focus trapping, scroll lock, aria-modal, and labelled-by wiring (DialogTitle).
 - Content taller than the viewport scrolls inside the dialog (thin scrollbar, contained overscroll) rather than overflowing off screen — the page behind is scroll-locked, so anything past the edge would be unreachable.
+- On close, focus returns to the element that held it when the dialog opened, whether a DialogTrigger opened it or your own button set a controlled open. It is captured before the content mounts, so an autoFocus field inside cannot displace it. If that element has left the page, Base UI's default (the trigger, if any) applies; an explicit finalFocus on the content always wins. AlertDialog and Sheet behave the same.
+- keepMounted hides closed content with the hidden attribute, so a kept draft is out of the accessibility tree and the tab order until the dialog reopens.
 - Esc and click-outside dismiss by default. AlertDialog keeps Esc but ignores click-outside, and its popup is role="alertdialog".
 - Animate via data-[starting-style]/data-[ending-style] attributes.
 - size="fullscreen" has no title chrome, so name the popup yourself: aria-label on DialogContent (or a visually hidden DialogTitle), plus alt text on the media — the zoomed image is a separate image to assistive technology. Its built-in close button carries aria-label="Close" and clears the safe-area insets (notch, home indicator).
@@ -118,6 +126,29 @@ import { Button, Dialog, DialogClose, DialogContent, DialogDescription, DialogFo
 <Dialog><DialogTrigger render={<Button variant="secondary">Rename collection</Button>} /><DialogContent showCloseButton><DialogHeader><DialogTitle>Rename collection</DialogTitle><DialogDescription>Update the display name shown to collectors.</DialogDescription></DialogHeader><Form><Field label="Collection name"><Input defaultValue="Midnight Archive" /></Field><DialogFooter><DialogClose render={<Button variant="secondary">Cancel</Button>} /><Button type="submit">Save changes</Button></DialogFooter></Form></DialogContent></Dialog>
 ```
 
+### Opened from your own button, keeping a draft
+
+```tsx
+import { Button, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, Field, Textarea } from "@sableui/react"
+
+const [open, setOpen] = useState(false)
+
+<Button variant="secondary" onClick={() => setOpen(true)}>New message</Button>
+<Dialog open={open} onOpenChange={setOpen}>
+	<DialogContent keepMounted showCloseButton>
+		<DialogHeader>
+			<DialogTitle>New message</DialogTitle>
+			<DialogDescription>Close it any time. Your draft is here when you come back.</DialogDescription>
+		</DialogHeader>
+		<Field label="Message"><Textarea /></Field>
+		<DialogFooter>
+			<DialogClose render={<Button variant="secondary">Close</Button>} />
+			<Button onClick={() => setOpen(false)}>Send</Button>
+		</DialogFooter>
+	</DialogContent>
+</Dialog>
+```
+
 ### Destructive confirmation
 
 ```tsx