@sableui/react 0.17.0 → 0.18.0

package/dist/styles.css

@@ -1665,13 +1665,19 @@
 /* ==========================================================================
    Layout — responsive grid spans + split panes.
 
-   The fluid layout primitives (Region, Grid, Stack…) compute their styles inline
-   so any dynamic value works without Tailwind scanning a class. Breakpoint-aware
-   layout can't be inline (a style attribute has no media queries), so `Col` and
-   `SplitPane` set per-breakpoint CSS custom properties inline and these rules
-   resolve them mobile-first. Breakpoints match Tailwind's defaults
-   (sm 40 / md 48 / lg 64 / xl 80 / 2xl 96 rem) so they line up with the `lg:*`
-   visibility utilities the app-shell components already use.
+   The fluid layout primitives (Region, Grid, Stack…) put their layout in
+   classes (`flex`, `grid`, `items-*`, `px-(--page-inset)`) and pass dynamic
+   values as inline CSS custom properties that those classes read, so any value
+   works without Tailwind scanning a class. Never an inline `display`, `gap` or
+   padding: inline style beats every utility, and `<Row className="hidden
+   md:flex">` silently did nothing. Breakpoint-aware layout can't be inline (a
+   style attribute has no media queries), so `Col` and `SplitPane` set
+   per-breakpoint CSS custom properties inline and these rules resolve them
+   mobile-first. The rules sit in `@layer components` so a utility in the
+   caller's `className` (`hidden`, `lg:grid-cols-3`, `gap-8`) still wins.
+   Breakpoints match Tailwind's defaults (sm 40 / md 48 / lg 64 / xl 80 /
+   2xl 96 rem) so they line up with the `lg:*` visibility utilities the
+   app-shell components already use.
    ========================================================================== */
 
 /* Each element owns its breakpoint values. Custom properties inherit, so a
@@ -1679,18 +1685,20 @@
    Grid inside `Columns count={{ lg: 12 }}` drew 12 tracks at lg. Resetting
    them here makes an unset one invalid, so the fallback chain below runs on the
    element itself; the values it was given are inline and win over this. */
-[data-sable-col] {
-	--col-span-base: initial; --col-span-sm: initial; --col-span-md: initial;
-	--col-span-lg: initial; --col-span-xl: initial; --col-span-2xl: initial;
-	--col-start-base: initial; --col-start-sm: initial; --col-start-md: initial;
-	--col-start-lg: initial; --col-start-xl: initial; --col-start-2xl: initial;
-}
-[data-sable-grid-cols] {
-	--cols-base: initial; --cols-sm: initial; --cols-md: initial;
-	--cols-lg: initial; --cols-xl: initial; --cols-2xl: initial;
-}
-[data-sable-split] {
-	--split-gap: initial;
+@layer components {
+	[data-sable-col] {
+		--col-span-base: initial; --col-span-sm: initial; --col-span-md: initial;
+		--col-span-lg: initial; --col-span-xl: initial; --col-span-2xl: initial;
+		--col-start-base: initial; --col-start-sm: initial; --col-start-md: initial;
+		--col-start-lg: initial; --col-start-xl: initial; --col-start-2xl: initial;
+	}
+	[data-sable-grid-cols] {
+		--cols-base: initial; --cols-sm: initial; --cols-md: initial;
+		--cols-lg: initial; --cols-xl: initial; --cols-2xl: initial;
+	}
+	[data-sable-split] {
+		--split-gap: initial;
+	}
 }
 
 /* Toasts keep clear of an open Sheet's actions. A right sheet's pinned footer
@@ -1761,126 +1769,126 @@
 	}
 }
 
-/* `Col span={{ base, md, lg }}` / `start={…}` — each breakpoint resolves to the
-   most specific value defined at or below it (mobile-first cascade). */
-[data-sable-col] {
-	grid-column: var(--col-start, auto) / span var(--col-span, 1);
-	--col-span: var(--col-span-base, 1);
-	--col-start: var(--col-start-base, auto);
-}
-@media (width >= 40rem) {
+@layer components {
+	/* `Col span={{ base, md, lg }}` / `start={…}` — each breakpoint resolves to the
+	   most specific value defined at or below it (mobile-first cascade). */
 	[data-sable-col] {
-		--col-span: var(--col-span-sm, var(--col-span-base, 1));
-		--col-start: var(--col-start-sm, var(--col-start-base, auto));
+		grid-column: var(--col-start, auto) / span var(--col-span, 1);
+		--col-span: var(--col-span-base, 1);
+		--col-start: var(--col-start-base, auto);
+	}
+	@media (width >= 40rem) {
+		[data-sable-col] {
+			--col-span: var(--col-span-sm, var(--col-span-base, 1));
+			--col-start: var(--col-start-sm, var(--col-start-base, auto));
+		}
 	}
-}
-@media (width >= 48rem) {
-	[data-sable-col] {
-		--col-span: var(--col-span-md, var(--col-span-sm, var(--col-span-base, 1)));
-		--col-start: var(--col-start-md, var(--col-start-sm, var(--col-start-base, auto)));
+	@media (width >= 48rem) {
+		[data-sable-col] {
+			--col-span: var(--col-span-md, var(--col-span-sm, var(--col-span-base, 1)));
+			--col-start: var(--col-start-md, var(--col-start-sm, var(--col-start-base, auto)));
+		}
 	}
-}
-@media (width >= 64rem) {
-	[data-sable-col] {
-		--col-span: var(--col-span-lg, var(--col-span-md, var(--col-span-sm, var(--col-span-base, 1))));
-		--col-start: var(--col-start-lg, var(--col-start-md, var(--col-start-sm, var(--col-start-base, auto))));
+	@media (width >= 64rem) {
+		[data-sable-col] {
+			--col-span: var(--col-span-lg, var(--col-span-md, var(--col-span-sm, var(--col-span-base, 1))));
+			--col-start: var(--col-start-lg, var(--col-start-md, var(--col-start-sm, var(--col-start-base, auto))));
+		}
 	}
-}
-@media (width >= 80rem) {
-	[data-sable-col] {
-		--col-span: var(--col-span-xl, var(--col-span-lg, var(--col-span-md, var(--col-span-sm, var(--col-span-base, 1)))));
-		--col-start: var(--col-start-xl, var(--col-start-lg, var(--col-start-md, var(--col-start-sm, var(--col-start-base, auto)))));
+	@media (width >= 80rem) {
+		[data-sable-col] {
+			--col-span: var(--col-span-xl, var(--col-span-lg, var(--col-span-md, var(--col-span-sm, var(--col-span-base, 1)))));
+			--col-start: var(--col-start-xl, var(--col-start-lg, var(--col-start-md, var(--col-start-sm, var(--col-start-base, auto)))));
+		}
 	}
-}
-@media (width >= 96rem) {
-	[data-sable-col] {
-		--col-span: var(--col-span-2xl, var(--col-span-xl, var(--col-span-lg, var(--col-span-md, var(--col-span-sm, var(--col-span-base, 1))))));
-		--col-start: var(--col-start-2xl, var(--col-start-xl, var(--col-start-lg, var(--col-start-md, var(--col-start-sm, var(--col-start-base, auto))))));
+	@media (width >= 96rem) {
+		[data-sable-col] {
+			--col-span: var(--col-span-2xl, var(--col-span-xl, var(--col-span-lg, var(--col-span-md, var(--col-span-sm, var(--col-span-base, 1))))));
+			--col-start: var(--col-start-2xl, var(--col-start-xl, var(--col-start-lg, var(--col-start-md, var(--col-start-sm, var(--col-start-base, auto))))));
+		}
 	}
-}
 
-/* `Columns count` / `Grid cols` as a breakpoint map — set per-breakpoint --cols-*
-   props inline; resolved mobile-first into the track's column count, so a grid
-   thins to fewer columns on small screens (e.g. 2 → 6 → 12). */
-[data-sable-grid-cols] {
-	display: grid;
-	grid-template-columns: repeat(var(--cols, var(--grid-columns)), minmax(0, 1fr));
-	--cols: var(--cols-base, var(--grid-columns));
-}
-@media (width >= 40rem) {
+	/* `Columns count` / `Grid cols` as a breakpoint map — set per-breakpoint --cols-*
+	   props inline; resolved mobile-first into the track's column count, so a grid
+	   thins to fewer columns on small screens (e.g. 2 → 6 → 12). */
 	[data-sable-grid-cols] {
-		--cols: var(--cols-sm, var(--cols-base, var(--grid-columns)));
+		grid-template-columns: repeat(var(--cols, var(--grid-columns)), minmax(0, 1fr));
+		--cols: var(--cols-base, var(--grid-columns));
 	}
-}
-@media (width >= 48rem) {
-	[data-sable-grid-cols] {
-		--cols: var(--cols-md, var(--cols-sm, var(--cols-base, var(--grid-columns))));
+	@media (width >= 40rem) {
+		[data-sable-grid-cols] {
+			--cols: var(--cols-sm, var(--cols-base, var(--grid-columns)));
+		}
 	}
-}
-@media (width >= 64rem) {
-	[data-sable-grid-cols] {
-		--cols: var(
-			--cols-lg,
-			var(--cols-md, var(--cols-sm, var(--cols-base, var(--grid-columns))))
-		);
+	@media (width >= 48rem) {
+		[data-sable-grid-cols] {
+			--cols: var(--cols-md, var(--cols-sm, var(--cols-base, var(--grid-columns))));
+		}
 	}
-}
-@media (width >= 80rem) {
-	[data-sable-grid-cols] {
-		--cols: var(
-			--cols-xl,
-			var(
+	@media (width >= 64rem) {
+		[data-sable-grid-cols] {
+			--cols: var(
 				--cols-lg,
 				var(--cols-md, var(--cols-sm, var(--cols-base, var(--grid-columns))))
-			)
-		);
+			);
+		}
 	}
-}
-@media (width >= 96rem) {
-	[data-sable-grid-cols] {
-		--cols: var(
-			--cols-2xl,
-			var(
+	@media (width >= 80rem) {
+		[data-sable-grid-cols] {
+			--cols: var(
 				--cols-xl,
 				var(
 					--cols-lg,
 					var(--cols-md, var(--cols-sm, var(--cols-base, var(--grid-columns))))
 				)
-			)
-		);
+			);
+		}
+	}
+	@media (width >= 96rem) {
+		[data-sable-grid-cols] {
+			--cols: var(
+				--cols-2xl,
+				var(
+					--cols-xl,
+					var(
+						--cols-lg,
+						var(--cols-md, var(--cols-sm, var(--cols-base, var(--grid-columns))))
+					)
+				)
+			);
+		}
 	}
-}
 
-/* `SplitPane collapseBelow="lg"` — a single stacked column below the breakpoint;
-   a two-column track (primary:secondary fr ratio) at or above it. */
-[data-sable-split] {
-	display: grid;
-	gap: var(--split-gap, var(--grid-gutter));
-	grid-template-columns: 1fr;
-}
-@media (width >= 40rem) {
-	[data-sable-split][data-collapse="sm"] {
-		grid-template-columns: var(--split-primary, 1fr) var(--split-secondary, 1fr);
+	/* `SplitPane collapseBelow="lg"` — a single stacked column below the breakpoint;
+	   a two-column track (primary:secondary fr ratio) at or above it. */
+	[data-sable-split] {
+		gap: var(--split-gap, var(--grid-gutter));
+		grid-template-columns: 1fr;
 	}
-}
-@media (width >= 48rem) {
-	[data-sable-split][data-collapse="md"] {
-		grid-template-columns: var(--split-primary, 1fr) var(--split-secondary, 1fr);
+	@media (width >= 40rem) {
+		[data-sable-split][data-collapse="sm"] {
+			grid-template-columns: var(--split-primary, 1fr) var(--split-secondary, 1fr);
+		}
 	}
-}
-@media (width >= 64rem) {
-	[data-sable-split][data-collapse="lg"] {
-		grid-template-columns: var(--split-primary, 1fr) var(--split-secondary, 1fr);
+	@media (width >= 48rem) {
+		[data-sable-split][data-collapse="md"] {
+			grid-template-columns: var(--split-primary, 1fr) var(--split-secondary, 1fr);
+		}
 	}
-}
-@media (width >= 80rem) {
-	[data-sable-split][data-collapse="xl"] {
-		grid-template-columns: var(--split-primary, 1fr) var(--split-secondary, 1fr);
+	@media (width >= 64rem) {
+		[data-sable-split][data-collapse="lg"] {
+			grid-template-columns: var(--split-primary, 1fr) var(--split-secondary, 1fr);
+		}
 	}
-}
-@media (width >= 96rem) {
-	[data-sable-split][data-collapse="2xl"] {
-		grid-template-columns: var(--split-primary, 1fr) var(--split-secondary, 1fr);
+	@media (width >= 80rem) {
+		[data-sable-split][data-collapse="xl"] {
+			grid-template-columns: var(--split-primary, 1fr) var(--split-secondary, 1fr);
+		}
+	}
+	@media (width >= 96rem) {
+		[data-sable-split][data-collapse="2xl"] {
+			grid-template-columns: var(--split-primary, 1fr) var(--split-secondary, 1fr);
+		}
 	}
 }
 

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/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/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

package/llms/components/media-image.md

@@ -15,6 +15,7 @@ Use MediaImage wherever content imagery may be missing or broken: a cover in a g
 - Do: Give the box the shape: `<AspectBox ratio={1} className="rounded-md"><MediaImage … /></AspectBox>`, or `size-14 rounded-md` on MediaImage itself for a thumbnail. It clips to whatever radius the box has.
 - Do: Pass `seed` (the title or an id) when `alt` is empty, so the fallback art is the item's own and stays the same in every list it appears in.
 - Do: Leave `alt` empty when a visible title sits next to the image — a tile, a row — and describe it when the image stands alone. A set `alt` also names the fallback, so the description survives a broken URL.
+- Do: Set `position` when a cover crop would cut off the subject — a face high in a portrait, a product at one edge. Store the focus with the image (`"35% 50%"`) rather than re-cropping the file.
 - Don't: Do not hand-write `<img onError={() => setBroken(true)}>`. An image that fails before hydration never fires the handler on a prerendered page; MediaImage preloads off the DOM and catches it.
 - Don't: Do not use it for profile pictures. A person is a circle with initials — Avatar, whose `variant="art"` is the same fallback with the person's initials over it.
 
@@ -27,6 +28,7 @@ Use MediaImage wherever content imagery may be missing or broken: a cover in a g
 | seed | string \| number | — | Seeds the fallback art. Defaults to `alt`; pass the title or an id when `alt` is empty. |
 | fallback | ReactNode | — | Replaces the GradientArt fallback — a glyph or monogram. Fills the frame under the same clipping. |
 | fit | "cover" \| "contain" | "cover" | `cover` crops to fill (artwork, photos); `contain` letterboxes on the muted surface (a logo, a product that must not be cropped). |
+| position | CSSProperties["objectPosition"] | "center" | Where the image sits in its frame — CSS `object-position`, the sibling of `fit`. Under `cover` it is the part the crop keeps (`"50% 30%"` for a face, `"bottom"` for a horizon); under `contain` it is the side the letterbox gives way to. |
 | srcSet | string | — | Responsive sources, passed to the `<img>`. |
 | sizes | string | — | The `sizes` attribute for `srcSet`. |
 | loading | "lazy" \| "eager" | "lazy" | Native lazy loading. Use `eager` for the first row of a grid above the fold. |
@@ -96,3 +98,13 @@ import { AspectBox, MediaImage } from "@sableui/react"
 	<MediaImage src={brand.logo} alt={brand.name} fit="contain" />
 </AspectBox>
 ```
+
+### Crop focus per image
+
+```tsx
+import { AspectBox, MediaImage } from "@sableui/react"
+
+<AspectBox ratio={1} className="rounded-md">
+	<MediaImage src={project.thumbnail} seed={project.title} position={project.focus ?? "center"} />
+</AspectBox>
+```

package/llms/components/media-tile.md

@@ -42,6 +42,7 @@ The item in a media grid or shelf: an album, a playlist, a video, a podcast, a f
 | sizes | string | — | The cover's layout width for `srcSet`, e.g. `"(min-width: 64rem) 25vw, 50vw"`. |
 | alt | string | "" | Cover alt text. Empty by default: the title below already names the item. |
 | seed | string \| number | — | Seeds the fallback art. Defaults to `title` when it is a string. |
+| position | CSSProperties["objectPosition"] | "center" | Which part of the cover the crop keeps — CSS `object-position`, forwarded to the cover's MediaImage: `"50% 30%"` for a face, `"top"` for a poster's title. Store it with the image when each one frames differently. |
 | aspect | "square" \| "video" \| "poster" \| number | "square" | The cover's shape: square (albums, podcasts), video (16:9), poster (2:3 — films, books), or any width / height ratio. |
 | size | "sm" \| "md" \| "lg" | "md" | Moves the type tier, the cover-to-text gap, the corner and the overlay inset together. |
 | href | string | — | Where the tile goes. The title becomes the link, stretched over the whole tile. |
@@ -166,6 +167,26 @@ import { Grid, MediaTile } from "@sableui/react"
 </Grid>
 ```
 
+### Portfolio grid with crop focus
+
+```tsx
+import { Grid, MediaTile } from "@sableui/react"
+
+<Grid minItemWidth="16rem" gap={4}>
+	{projects.map((project) => (
+		<MediaTile
+			key={project.slug}
+			aspect="video"
+			title={project.title}
+			subtitle={project.client}
+			src={project.thumbnail}
+			position={project.focus}
+			href={`/work/${project.slug}`}
+		/>
+	))}
+</Grid>
+```
+
 ### Poster shelf
 
 ```tsx

package/llms/components/page-header.md

@@ -4,7 +4,7 @@
 
 In-flow page heading block: a title row (optional back control + actions) over an optional description, with room for children (filters, tabs) below.
 
-**Keywords:** page header, title, lede, page actions
+**Keywords:** page header, title, lede, page actions, page title size, display title, editorial header, hero title
 
 ## Usage
 
@@ -14,6 +14,8 @@ Use PageHeader to establish a page's title, supporting description, and primary
 
 - Do: Use one PageHeader per major page or route.
 - Do: Keep the title literal and put explanation in the lede or nearby content.
+- Do: Use size="lg" for an editorial page (a personal site, a marketing page, an article index): a display-tier title over a body-lg lede. Pair it with SectionHeader size="lg" for the sections below, so the steps stay display → heading-2 → body.
+- Don't: Use size="lg" on product routes (settings, lists, dashboards). Display type is never product chrome: there it competes with the content it frames. Keep md, and do not restyle the title with a display class through className either.
 - Don't: Do not use PageHeader inside repeated cards, dialogs, or compact panels.
 - Don't: Do not use a second PageHeader for a section of the page. It is the route's one h1; each section below it takes a SectionHeader (an h2 with the same title row, description and actions).
 - Don't: Do not put it outside the Region that holds the page content. It then sits at a different measure from what it introduces, and the page reads as two documents.
@@ -27,6 +29,11 @@ Use PageHeader to establish a page's title, supporting description, and primary
 | back | ReactNode | — | Leading element before the title — typically a back control on drill-in routes. Keep it a ghost icon Button (size="icon", variant="ghost", aria-label="Back") so it stays quieter than the title. A ghost back control bleeds by its inset at the start, so its glyph lines up with the content edge below (Button bleed="none" opts out). |
 | actions | ReactNode | — | Trailing actions aligned to the title row's end. They drop under the title when the title would have less than 20rem beside them (on a phone, nearly always), and the title wraps rather than truncating. A ghost or link Button at either end of the group bleeds by its own padding, so its label meets the content edge (the end on the title row, the start once wrapped); filled buttons keep their edge on the line. Direct children only. |
 | titleAs | "h1" \| "h2" | "h1" | The title's heading element. Keep h1 — the route's one h1. Use h2 only when something above already owns the h1: a shell that renders the route title, or a page showing a PageHeader as an example. |
+| size | "md" \| "lg" | "md" | The title's scale. md: text-heading-2 over a text-body-sm description, for product pages. lg: text-display-lg over a text-body-lg lede capped at the prose measure, with more space between and below, for an editorial page (personal site, marketing page, article index). Beside actions or a back control, a title line taller than the controls lifts by half the difference, so its first line stays centred on them. |
+
+## Variants
+
+- **size**: md, lg
 
 ## Tokens used
 
@@ -51,6 +58,14 @@ import { Button, PageHeader } from "@sableui/react"
 <PageHeader title="Storage credits" description="Fund permanent storage." actions={<Button>Top up</Button>} />
 ```
 
+### Editorial page title (size lg)
+
+```tsx
+import { Button, PageHeader } from "@sableui/react"
+
+<PageHeader size="lg" title="Field notes" description="Essays on making things slowly, from a studio by the sea." actions={<Button variant="outline">Subscribe</Button>} />
+```
+
 ### One per page, inside the region
 
 ```tsx