@sableui/react 0.16.0 → 0.18.0

package/llms-full.txt

@@ -1,6 +1,6 @@
 # Sable (@sableui/react)
 
-> An owned, themeable React component system. Default theme: **Sable** (dark-by-default, content-first, fluid product UI). Behavior from Base UI; styling via Tailwind v4 + semantic CSS-variable tokens; Reicon icons via a pluggable adapter. 121 components, 13 layout primitives, and a **patterns** tier of canonical page shells. The full, per-component contract is the generated `registry.json`.
+> An owned, themeable React component system. Default theme: **Sable** (dark-by-default, content-first, fluid product UI). Behavior from Base UI; styling via Tailwind v4 + semantic CSS-variable tokens; Reicon icons via a pluggable adapter. 123 components, 13 layout primitives, and a **patterns** tier of canonical page shells. The full, per-component contract is the generated `registry.json`.
 
 ## Start here — brief, composition, evidence
 
@@ -445,6 +445,37 @@ names the nearest pair that reads. Report it with that pair as a recommendation.
 A reasoned `design-lint-disable-next-line label-contrast` is the app's recorded
 choice: list it as intentional, not as a defect.
 
+## Adoption: an app wired for Sable that barely uses it
+
+The commonest drift is not a wrong prop. It is an app where an agent never
+loaded this skill: the stylesheet and tokens are wired, and every control is the
+app's own (a `Modal`, a `PrimaryButton`, a `Tabs` written from scratch). Wiring
+checks pass, and lint only sees the raw elements. `sable check` (and `sable
+grade --json` → `adoption`) measures it: how many UI files compose Sable, which
+app-defined components are named for something Sable ships and do the behaviour
+by hand, and what the app's foundation is. `sable doctor` warns when adoption is
+`none` or `low`. It is never a failure: whether working screens move is the
+user's call.
+
+Put the choice to the user before changing anything. Ask, don't migrate silently
+and don't leave it unmentioned. Show the swaps, behaviour first (overlays,
+controls, tabs, menus, anything with focus or keyboard handling), with what each
+one gains ("your Modal has no focus trap or Esc; Sable's Dialog has both").
+Layout and look stay the app's. How strongly to recommend it depends on the
+`foundation` the report names:
+
+| Foundation | What to say |
+|---|---|
+| `ad-hoc`: no system besides Sable | Recommend the move plainly. There is nothing to preserve but one-off components, and every one is a behaviour bug waiting. Offer to do it a screen at a time. |
+| `own`: a folder of the app's own primitives | Offer the swaps and say what each gains. Keep the app's own where the user prefers them; suggest building them on Sable's behaviour (a `Button` wrapper around Sable's `Button`) instead. |
+| `library`: another component library (MUI, Radix, shadcn-style `components/ui`) | Ask whether Sable should replace it or only cover new work. Don't mix two control libraries on one screen. |
+| `sable`: Sable already carries the UI | Mention the few swaps listed when those screens are next touched. |
+
+Use the question tool the host offers when there is one. Record the answer in
+the project's instructions, so the next task doesn't ask again. On a yes, move
+one screen or component at a time with `fix`/`polish`, running `sable check` and
+looking at the rendered states after each.
+
 ## Deliver evidence-backed findings
 
 Save the audit under `design/<surface>/audit/` or the existing review location.
@@ -2274,15 +2305,22 @@ In a monorepo where Sable belongs to one workspace package, run setup in that
 package with `--root` naming the repository root (for example
 `pnpm --filter web exec sable setup --agent --root ../..`); the entries go
 there and resolve Sable through the package.
+Setup also adds a short managed block to the project's `AGENTS.md` and
+`CLAUDE.md`, the instructions an agent reads on every task, so a UI request
+goes through the skill even when it doesn't mention Sable. Only the text between
+its `<!-- sable:begin -->` and `<!-- sable:end -->` markers is Sable's;
+`--no-instructions` skips it.
 Each entry resolves `skills/sable/SKILL.md` from the installed package, so package
 upgrades also update the workflow. Other agents can read that file directly.
 Use `$sable build <idea>`, `inspire <references>`, `audit <target>`, or
 `polish <target>` in Codex; use `/sable` with the same modes in Claude Code or
 Cursor. `create` is a build alias. These are agent modes, not shell commands.
 
-Upgrade with `pnpm update @sableui/react --latest`, then
-`pnpm exec sable setup --agent --update`. Setup only replaces managed files
-that have not been locally edited; `--dry-run` checks without writing. Keep
+Upgrade with `pnpm exec sable upgrade`: it updates the package, then runs the
+new version's `init`, which refreshes the skill entries and the instructions
+block and checks the wiring. From 0.17 or earlier, which has no `upgrade`, run
+`pnpm update @sableui/react --latest` and then `pnpm exec sable init` once.
+Setup only replaces managed files that have not been locally edited; `--dry-run` checks without writing. Keep
 project preferences in project instructions. Package installation alone does not
 change agent settings. See [building-with-sable.md](./building-with-sable.md),
 [creating-a-preset.md](./creating-a-preset.md), and
@@ -3382,8 +3420,7 @@ saved file. Replace, don't add beside:
 ## Upgrade the package and skill
 
 ```bash
-pnpm update @sableui/react --latest
-pnpm exec sable setup --agent --update
+pnpm exec sable upgrade
 pnpm exec sable preset --check .sable/presets/clay.json --json
 pnpm exec sable doctor
 ```
@@ -7093,49 +7130,46 @@ export function ApiKeysBlock({ className, framed = true, onCreate, onKeyAction }
 
 # ApprovalBlock
 
-An agent asking permission for one tool call: the question, what will happen and what can't be undone, the call's details, an "allow for the rest of this chat" Checkbox, and Deny / Allow.
+An agent asking permission for one tool call: the question, what is at stake, the call itself as a ToolCall with its exact input, and Deny / Always allow / Allow once.
 
-**Intent:** Reach for this in a chat or agent run when a tool call waits on the person — sending, paying, deleting, publishing. The call itself, before and after the decision, is a ToolCall with status="awaiting", then "complete" or "denied". A destructive action outside an agent is DestructiveActionModal.
+**Intent:** Reach for this in a chat or agent run when a tool call waits on the person — running a command, sending, paying, deleting, publishing. It wraps the call's own ToolCall, which shows status="awaiting" until the person answers and then "complete" or "denied". A destructive action outside an agent is DestructiveActionModal.
 
 **Block:** AI & agents · card · designed for 18rem–28rem wide (fills its container up to the max)
 
 ## Notes
 
-- The title is the question in plain words ("Send the invoice to Ada?"), not the tool's name; the tool's name is one row of the details, for the person who wants to know exactly what runs.
-- The description says what can't be undone. That sentence is what the person is deciding on.
-- Deny comes first and Allow is the primary on the end, the same order as every Sable confirmation. Neither is focused on arrival: an approval that a stray Enter can grant is not an approval.
-- After a decision the buttons give way to one InlineStatus line saying what happened, so the thread keeps a record of the answer.
+- The title is the question in plain words ("Run this command?"); the description says what is at stake. That sentence is what the person is deciding on.
+- The call is shown as the agent made it — tool name and raw input, open on arrival — because the exact arguments are what a careful person checks. Do not paraphrase them into a form.
+- Three answers, as agent products settle on: Deny on the start edge, then Always allow and Allow once, the primary on the end. Neither is focused on arrival: an approval that a stray Enter can grant is not an approval.
+- After a decision the buttons give way to one InlineStatus line saying what happened, and the ToolCall shows the outcome, so the thread keeps a record of the answer.
 
 ## Accessibility
 
 - Focus moves to the outcome line when the buttons leave, instead of dropping to the page; the line is a role=status region, so the decision is announced.
-- The details are a dl, so each value is read with its label.
-- The remember Checkbox has its own Label, so the tool name inside it is part of its accessible name.
+- The ToolCall announces its own status change, and its input is a labelled code view.
 
 ## Source
 
 ```tsx
-import { useState, useEffect, useRef, useId } from "react"
-import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, cn, Code, InlineStatus, Label } from "@sableui/react"
+import { useState, useEffect, useRef } from "react"
+import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, cn, InlineStatus, ToolCall } from "@sableui/react"
 
 const request = {
-	tool: "send_email",
-	title: "Send the invoice to Ada?",
-	description: "The agent wants to email invoice INV-1042. An email can't be unsent.",
-	details: [
-		{ label: "To", value: "ada@example.com" },
-		{ label: "Subject", value: "INV-1042 for October" },
-		{ label: "Attached", value: "INV-1042.pdf" },
-	],
-	allowed: "Allowed. Sending the email.",
-	denied: "Denied. The agent won't send it.",
+	title: "Run this command?",
+	description: "The agent wants to migrate the production database in acme/api. It changes live data.",
+	tool: "run_command",
+	action: "Run a command",
+	// A command reads as the command; a structured call would pass its arguments object.
+	input: "pnpm db:migrate --env production",
+	allowed: "Allowed. Running the migration.",
+	denied: "Denied. The agent won't run it.",
 }
 
 export interface ApprovalBlockProps {
 	className?: string
 	/** false drops the card's surface and border — for a chat column that already frames it. */
 	framed?: boolean
-	/** The person allowed the call. `remember` is the "for the rest of this chat" choice. */
+	/** The person allowed the call. `remember` is true for "Always allow". */
 	onApprove?: (options: { remember: boolean }) => void
 	/** The person declined the call. */
 	onDeny?: () => void
@@ -7143,8 +7177,6 @@ export interface ApprovalBlockProps {
 
 export function ApprovalBlock({ className, framed = true, onApprove, onDeny }: ApprovalBlockProps) {
 	const [decision, setDecision] = useState<"allowed" | "denied" | null>(null)
-	const [remember, setRemember] = useState(false)
-	const id = useId()
 	const outcome = useRef<HTMLDivElement>(null)
 	// The buttons leave with the decision, so focus moves to the line that
 	// replaces them instead of falling back to the top of the page.
@@ -7152,37 +7184,30 @@ export function ApprovalBlock({ className, framed = true, onApprove, onDeny }: A
 		if (decision) outcome.current?.focus()
 	}, [decision])
 
+	const approve = (remember: boolean) => {
+		setDecision("allowed")
+		onApprove?.({ remember })
+	}
+
 	return (
 		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-md", className)}>
 			<CardHeader>
 				<CardTitle>{request.title}</CardTitle>
 				<CardDescription>{request.description}</CardDescription>
 			</CardHeader>
-			<CardContent className="flex flex-col gap-4">
-				<dl className="grid grid-cols-[auto_minmax(0,1fr)] gap-x-4 gap-y-1.5 text-body-sm">
-					{request.details.map((d) => (
-						<div key={d.label} className="contents">
-							<dt className="text-muted-foreground">{d.label}</dt>
-							<dd className="truncate text-foreground">{d.value}</dd>
-						</div>
-					))}
-					<div className="contents">
-						<dt className="text-muted-foreground">Tool</dt>
-						<dd className="min-w-0">
-							<Code>{request.tool}</Code>
-						</dd>
-					</div>
-				</dl>
-				{decision ? null : (
-					<div className="flex items-center gap-2">
-						<Checkbox id={`${id}-remember`} checked={remember} onCheckedChange={(v: boolean) => setRemember(v)} />
-						<Label htmlFor={`${id}-remember`} className="text-body-sm">
-							Allow <Code>{request.tool}</Code> for the rest of this chat
-						</Label>
-					</div>
-				)}
+			<CardContent>
+				{/* The call itself, exactly as the agent made it. It answers with the
+				    person: held, then done or denied. */}
+				<ToolCall
+					name={request.tool}
+					title={request.action}
+					status={decision === "allowed" ? "complete" : decision === "denied" ? "denied" : "awaiting"}
+					statusLabel={decision === "allowed" ? "Allowed" : undefined}
+					input={request.input}
+					defaultOpen
+				/>
 			</CardContent>
-			<CardFooter actions className="justify-end">
+			<CardFooter actions>
 				{decision ? (
 					<InlineStatus
 						ref={outcome}
@@ -7196,7 +7221,8 @@ export function ApprovalBlock({ className, framed = true, onApprove, onDeny }: A
 				) : (
 					<>
 						<Button
-							variant="outline"
+							variant="ghost"
+							className="me-auto"
 							onClick={() => {
 								setDecision("denied")
 								onDeny?.()
@@ -7204,14 +7230,10 @@ export function ApprovalBlock({ className, framed = true, onApprove, onDeny }: A
 						>
 							Deny
 						</Button>
-						<Button
-							onClick={() => {
-								setDecision("allowed")
-								onApprove?.({ remember })
-							}}
-						>
-							Allow
+						<Button variant="outline" onClick={() => approve(true)}>
+							Always allow
 						</Button>
+						<Button onClick={() => approve(false)}>Allow once</Button>
 					</>
 				)}
 			</CardFooter>
@@ -10332,7 +10354,7 @@ export function WalletBlock({ className, framed = true, onSend, onReceive }: Wal
 
 **Status:** stable
 
-The page region: fluid, edge-to-edge with the fluid page inset (--page-inset). Opt-in centered max cap picked by ROLE (prose/form/feed/content/wide/full), never a global page max-width. The root of nearly every route.
+The page region: fluid, edge-to-edge with the fluid page inset (--page-inset). Opt-in centered max cap picked by ROLE (prose/form/feed/content/wide/full), never a global page max-width. The root of nearly every route. The inset and cap are classes (px-(--page-inset), max-w-…), so className overrides them at a breakpoint (max-sm:px-0); only safeArea padding is inline.
 
 **Keywords:** region, page width, container, layout
 
@@ -10439,7 +10461,7 @@ import { Card, CardContent, Page, PageHeader } from "@sableui/react"
 
 **Status:** stable
 
-CSS Grid within a region. Two modes: fixed/responsive cols count, or minItemWidth so cells breathe with NO breakpoints (the default choice for card grids). A minItemWidth grid keeps its empty columns (track="fill"), so one result stays one cell wide; track="fit" stretches a fixed set across the row.
+CSS Grid within a region. Two modes: fixed/responsive cols count, or minItemWidth so cells breathe with NO breakpoints (the default choice for card grids). A minItemWidth grid keeps its empty columns (track="fill"), so one result stays one cell wide; track="fit" stretches a fixed set across the row. display is the grid class and the gap a CSS variable, so className utilities win at any breakpoint (hidden md:grid, md:gap-6, lg:grid-cols-3).
 
 **Keywords:** grid, card grid, auto fit, layout
 
@@ -10510,7 +10532,7 @@ import { Badge, Grid } from "@sableui/react"
 
 **Status:** stable
 
-An explicit N-column track (default 12) for proportioned layouts — pair with Col spans (list-detail, asymmetric editorial layouts). For uniform card grids prefer Grid minItemWidth.
+An explicit N-column track (default 12) for proportioned layouts — pair with Col spans (list-detail, asymmetric editorial layouts). For uniform card grids prefer Grid minItemWidth. display is the grid class, so hidden md:grid works; a gap-* utility replaces both gaps and the column-gap cap.
 
 **Keywords:** columns, 12 column, span, layout
 
@@ -10564,7 +10586,7 @@ import { Card, CardHeader, CardTitle, Col, Columns } from "@sableui/react"
 
 **Status:** stable
 
-Vertical flow on the 8px rhythm — the default container for stacked content. Gap by role: tight within a group (1.5–2), looser between groups (3–4), generous between sections (6+).
+Vertical flow on the 8px rhythm — the default container for stacked content. Gap by role: tight within a group (1.5–2), looser between groups (3–4), generous between sections (6+). Layout lives in classes (flex flex-col items-* justify-*) and the gap in a CSS variable, never inline style, so className utilities override any prop at a breakpoint (max-lg:hidden, md:flex-row, md:gap-8).
 
 **Keywords:** stack, vertical rhythm, layout, spacing
 
@@ -10606,7 +10628,7 @@ import { Field, Input, Stack, Textarea } from "@sableui/react"
 
 **Status:** stable
 
-Horizontal flex flow — inline rows of controls, toolbars, action clusters. Defaults to center-aligned, no wrap.
+Horizontal flex flow — inline rows of controls, toolbars, action clusters. Defaults to center-aligned, no wrap. Layout lives in classes (flex flex-row items-* justify-*) and the gap in a CSS variable, never inline style, so className utilities override any prop at a breakpoint (hidden md:flex, max-md:flex-col, md:gap-6).
 
 **Keywords:** row, toolbar, horizontal, layout
 
@@ -10643,13 +10665,21 @@ import { Button, Row } from "@sableui/react"
 <Row gap={2} justify="end"><Button variant="ghost">Cancel</Button><Button>Save changes</Button></Row>
 ```
 
+### Responsive through className
+
+```tsx
+import { Button, Row } from "@sableui/react"
+
+<Row justify="between"><span className="text-title-sm">Acme</span><Row gap={1} className="max-md:hidden"><Button variant="ghost" size="sm">Docs</Button><Button variant="ghost" size="sm">Pricing</Button></Row></Row>
+```
+
 ---
 
 # Spacer
 
 **Status:** stable
 
-Explicit space on the rhythm, or a flexible grow pusher between siblings (e.g. pushing a footer item to the end of a Row).
+Explicit space on the rhythm, or a flexible grow pusher between siblings (e.g. pushing a footer item to the end of a Row). The size is a class reading a CSS variable, so className resizes or hides it at a breakpoint.
 
 **Keywords:** spacer, spacing, grow, layout
 
@@ -10691,7 +10721,7 @@ import { Button, Row, Spacer } from "@sableui/react"
 
 **Status:** stable
 
-Horizontally center a block, optionally capping its width (commonly "prose" for a reading column inside a wider layout).
+Horizontally center a block, optionally capping its width (commonly "prose" for a reading column inside a wider layout). Centering and cap are classes, so className overrides them at a breakpoint.
 
 **Keywords:** center, measure, reading width, layout
 
@@ -10731,7 +10761,7 @@ import { Center } from "@sableui/react"
 
 **Status:** stable
 
-Reserves space via aspect-ratio so async media loads with zero layout shift. Wrap images, video, embeds.
+Reserves space via aspect-ratio so async media loads with zero layout shift. Wrap images, video, embeds. The ratio is a class reading a CSS variable, so className reshapes it at a breakpoint (md:aspect-video).
 
 **Keywords:** aspect box, aspect ratio, media, layout shift
 
@@ -10771,7 +10801,7 @@ import { AspectBox } from "@sableui/react"
 
 **Status:** stable
 
-Escape a width-capped or inset ancestor to span the full CONTENT area (container-query units, so it stops at a fixed Sidebar instead of bleeding under it). Hero bands, profile covers, full-bleed media inside a capped Page.
+Escape a width-capped or inset ancestor to span the full CONTENT area (container-query units, so it stops at a fixed Sidebar instead of bleeding under it). Hero bands, profile covers, full-bleed media inside a capped Page. Width and margins are classes, so a breakpoint can turn the bleed off (lg:mx-0 lg:w-auto).
 
 **Keywords:** bleed, full bleed, media band, layout
 
@@ -10805,7 +10835,7 @@ import { AspectBox, Bleed, Page, PageHeader } from "@sableui/react"
 
 **Status:** stable
 
-Responsive two-pane layout: side-by-side at/above a breakpoint, stacked (primary first) below. List-detail, media + metadata.
+Responsive two-pane layout: side-by-side at/above a breakpoint, stacked (primary first) below. List-detail, media + metadata. display is the grid class and the breakpoint rules are layered, so className utilities (hidden lg:grid, gap-8) win.
 
 **Keywords:** split pane, two pane, list detail, responsive
 
@@ -11025,6 +11055,142 @@ import { Accordion, AccordionItem, AccordionPanel, AccordionTrigger, Icon } from
 
 ---
 
+# 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} />
+```
+
+---
+
 # AppHeader
 
 **Status:** stable
@@ -13689,6 +13855,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
 
@@ -14935,11 +15102,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
 
@@ -14955,7 +15125,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. |
@@ -14963,7 +15133,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. |
 
@@ -14971,7 +15141,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
 
@@ -14993,6 +15166,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).
@@ -15036,6 +15211,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
@@ -16998,6 +17196,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.
 
@@ -17010,6 +17209,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. |
@@ -17080,6 +17280,16 @@ import { AspectBox, MediaImage } from "@sableui/react"
 </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>
+```
+
 ---
 
 # MediaTile
@@ -17126,6 +17336,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. |
@@ -17250,6 +17461,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
@@ -18629,7 +18860,7 @@ import { Button, Icon, MenuItem, OverflowMenu, Row } from "@sableui/react"
 
 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
 
@@ -18639,6 +18870,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.
@@ -18652,6 +18885,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
 
@@ -18676,6 +18914,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
@@ -19356,7 +19602,7 @@ import { PieChart } from "@sableui/react"
 
 **Status:** stable
 
-A chip someone clicks: a filter, a tag choice, an option in a row. Always a button with aria-pressed. appearance="solid" (filters; selected lifts onto the primary surface) or "outline" (quiet chips that annotate content, like reactions); size md or sm. A static label is a Badge.
+A chip someone clicks: a filter, a tag choice, an option in a row. Always a button with aria-pressed. appearance="solid" (filters; selected lifts onto the primary surface) or "outline" (quiet chips that annotate content, like reactions); size lg, md or sm. A static label is a Badge.
 
 **Keywords:** pill, chip, filter, tag, toggle chip, category
 
@@ -19368,9 +19614,10 @@ Use Pill for a row of filters or choices a person clicks to narrow or toggle wha
 
 - Do: Use short text that names the filter or choice.
 - Do: Reflect the current choice with selected, so the active filter reads at a glance.
+- Do: In a toolbar where filter chips share a row with a search field ("All 8 · Products 5 · Open source 2 … [Find a project]"), pair Pill size="lg" with SearchInput size="sm", and Button size="sm" for any action beside them. All three stand on --control-sm (32px, 28 compact), the rung the spacing doctrine gives toolbar controls, so the row is one height in either density. Pill md (28px) has no text field of its height in the page register, so md beside a field always reads as a mismatch.
 - Don't: Do not use Pill as a static label. A pressable-looking chip that does nothing is the most common cause of dead clicks in a filter row — that is a Badge. → use **Badge**
 - Don't: Do not use Pill for primary actions or important system status.
-- Don't: Do not restyle a Pill with border or background classes to get a quieter chip. That is appearance="outline" (and size="sm" for a small one); an override is a look that exists nowhere else in the system.
+- Don't: Do not restyle a Pill with border or background classes to get a quieter chip. That is appearance="outline" (and size="sm" for a small one); an override is a look that exists nowhere else in the system. Likewise never set h-* on a Pill to match a neighbour: pick the size that shares its rung.
 
 ## Props
 
@@ -19378,14 +19625,14 @@ Use Pill for a row of filters or choices a person clicks to narrow or toggle wha
 | --- | --- | --- | --- |
 | selected | boolean | false | Marks the pill as chosen. Solid lifts onto the primary surface; outline takes a primary tint and soft primary edge. Sets aria-pressed. |
 | appearance | "solid" \| "outline" | "solid" | solid for a filter row; outline for quiet chips that annotate other content (a reaction under a message, a tag on a card), where a filled chip would compete with what it annotates. |
-| size | "md" \| "sm" | "md" | md sits on the density ladder's xs control height (28px); sm is 24px, for chips under or inside other content. |
+| size | "lg" \| "md" \| "sm" | "md" | lg sits on --control-sm (32px, 28 compact), the toolbar rung it shares with SearchInput sm and Button sm, for a filter row beside a search field. md sits on --control-xs (28px, 24 compact), the chip in a row of its own or among content. sm is a fixed 24px (the target floor, which density does not shrink), for chips under or inside other content. |
 | tone | "neutral" \| "red" \| "orange" \| "yellow" \| "green" \| "teal" \| "blue" \| "purple" \| "pink" | "neutral" | neutral is the chip as described. A palette family colours it as a category, like the choices in a tag picker: a wash at rest, the solid family colour when selected. Painted from the theme's generated palette. |
 | icon | ReactNode | — | Optional leading glyph (e.g. <Icon name="lock" />), rendered before the children with the base gap. |
 
 ## Variants
 
 - **appearance**: solid, outline
-- **size**: md, sm
+- **size**: lg, md, sm
 - **selected**: true, false
 - **tone**: neutral, red, orange, yellow, green, teal, blue, purple, pink
 
@@ -19408,7 +19655,7 @@ Use Pill for a row of filters or choices a person clicks to narrow or toggle wha
 
 ## Related
 
-- Components: Badge, ToggleGroup
+- Components: Badge, ToggleGroup, SearchInput
 
 ## Examples
 
@@ -19428,6 +19675,24 @@ import { Pill, Row } from "@sableui/react"
 <Row gap={1}><Pill selected onClick={() => {}}>All</Pill><Pill onClick={() => {}}>Projects</Pill><Pill onClick={() => {}}>Reports</Pill></Row>
 ```
 
+### Filters with search
+
+```tsx
+import { Pill, Row, SearchInput } from "@sableui/react"
+
+const [filter, setFilter] = useState("all")
+const [q, setQ] = useState("")
+
+<Row gap={2} align="center" justify="between" wrap>
+	<Row gap={1}>
+		<Pill size="lg" selected={filter === "all"} onClick={() => setFilter("all")}>All 8</Pill>
+		<Pill size="lg" selected={filter === "products"} onClick={() => setFilter("products")}>Products 5</Pill>
+		<Pill size="lg" selected={filter === "oss"} onClick={() => setFilter("oss")}>Open source 2</Pill>
+	</Row>
+	<SearchInput size="sm" value={q} onValueChange={setQ} placeholder="Find a project…" aria-label="Find a project" className="max-w-64" />
+</Row>
+```
+
 ### Outline, small (reactions)
 
 ```tsx
@@ -20446,7 +20711,7 @@ import { PropertyRow, ScrubField, Slider } from "@sableui/react"
 
 **Status:** stable
 
-Styled search field with a leading magnifier and a clearable X. Soft-square (rounded-sm), the theme's field surface, 2px focus ring; the clear button appears only when there is a value.
+Styled search field with a leading magnifier and a clearable X. Soft-square (rounded-sm), the theme's field surface, 2px focus ring; the clear button appears only when there is a value. size md (form), sm (toolbar, matching Pill lg and Button sm) or xs (inset tool-panel field).
 
 **Keywords:** search, input, filter, query
 
@@ -20460,6 +20725,8 @@ Use SearchInput for text queries that filter or search a known content set.
 - Do: Provide a visible clear affordance when query state persists.
 - Do: When a button stands in for search (a header trigger that opens CommandMenu with ⌘K), use CommandMenuTrigger. It wears this field's shell from the same source, so the two cannot drift; a hand-styled button already did once, into a borderless chip that matched neither the field nor a button.
 - Do: Light the query in the results it filters with `useMatchHighlight(query)` — a callback ref for the results container, with `selector` to keep it to titles. It paints on the `highlight` pair without wrapping matches in `<mark>`, the same paint Combobox and CommandMenu use for their rows.
+- Do: In a toolbar beside filter chips, use size="sm" with Pill size="lg" (and Button size="sm" for actions). All three stand on --control-sm (32px, 28 compact), the rung the spacing doctrine gives toolbar controls, so the row is one height in either density. Keep md for a search field in a form or a page header beside md buttons, and xs for a filter inside a workspace panel, where it matches Input xs's inset surface.
+- Don't: Do not match a neighbour's height with h-* on className or inputClassName. The magnifier, padding and clear button would stay sized for the old rung; pick the size that shares the neighbour's rung.
 - Don't: Do not use SearchInput as a command palette; use CommandMenu for global commands, opened from the header by CommandMenuTrigger. A SearchInput that opens a dialog on focus is a text box you cannot type in.
 - Don't: Do not search on every keystroke against an expensive backend without debouncing. The user sees results flicker and reorder under them, and you send a request per character.
 
@@ -20467,6 +20734,7 @@ Use SearchInput for text queries that filter or search a known content set.
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
+| size | "md" \| "sm" \| "xs" | "md" | The rung of the control ladder, named as on Input, Select and Combobox. md is the form field (--control-md, 40px / 32 compact). sm is the toolbar field (--control-sm, 32px / 28 compact), the rung Pill lg and Button sm share, so filters + search + actions in one row are one height. xs is the tool-panel field (--control-xs, 28px / 24 compact) on Input xs's inset panel-field surface. The magnifier, inline padding and clear button scale with the rung and stay vertically centred. |
 | value | string | — | Controlled value of the search field. |
 | defaultValue | string | — | Uncontrolled initial value. The field tracks its own text, so the clear button still appears and empties it. |
 | className | string | — | Sizes and places the whole field — magnifier, input and clear button together (e.g. max-w-80). A width cap here keeps the clear button inside the field. |
@@ -20475,11 +20743,11 @@ Use SearchInput for text queries that filter or search a known content set.
 | onClear | () => void | — | Called when the clear button is pressed. The component also fires onValueChange('') so a controlled value resets. |
 | placeholder | string | "Search" | Placeholder text shown when the field is empty. |
 | disabled | boolean | false | Dims the control and blocks pointer interaction. |
-| ...props | ComponentPropsWithRef<"input"> | — | All native input attributes (name, autoFocus, ref, aria-invalid, …) pass through to the <input> except value/onChange, which are owned by value/onValueChange, and className, which sizes the whole field. |
+| ...props | ComponentPropsWithRef<"input"> | — | All native input attributes (name, autoFocus, ref, aria-invalid, …) pass through to the <input> except value/onChange, which are owned by value/onValueChange, className, which sizes the whole field, and the native numeric size attribute, which the size prop replaces. |
 
 ## Tokens used
 
-`field-border`, `field`, `foreground`, `muted-foreground`, `ring`, `destructive`
+`field-border`, `field`, `foreground`, `muted-foreground`, `ring`, `destructive`, `panel-field`, `panel-field-hover`
 
 ## Motion
 
@@ -20498,7 +20766,7 @@ Use SearchInput for text queries that filter or search a known content set.
 
 ## Related
 
-- Components: Input, CommandMenu, Combobox
+- Components: Input, CommandMenu, Combobox, Pill
 
 ## Examples
 
@@ -20544,6 +20812,36 @@ const shown = posts.filter((post) => post.title.toLowerCase().includes(q.trim().
 </ul>
 ```
 
+### Filters with search
+
+```tsx
+import { Pill, Row, SearchInput } from "@sableui/react"
+
+const [filter, setFilter] = useState("all")
+const [q, setQ] = useState("")
+
+<Row gap={2} align="center" justify="between" wrap>
+	<Row gap={1}>
+		<Pill size="lg" selected={filter === "all"} onClick={() => setFilter("all")}>All 8</Pill>
+		<Pill size="lg" selected={filter === "products"} onClick={() => setFilter("products")}>Products 5</Pill>
+		<Pill size="lg" selected={filter === "oss"} onClick={() => setFilter("oss")}>Open source 2</Pill>
+	</Row>
+	<SearchInput size="sm" value={q} onValueChange={setQ} placeholder="Find a project…" aria-label="Find a project" className="max-w-64" />
+</Row>
+```
+
+### Sizes
+
+```tsx
+import { SearchInput, Stack } from "@sableui/react"
+
+<Stack gap={1}>
+	<SearchInput size="md" placeholder="Search posts" aria-label="Search posts" />
+	<SearchInput size="sm" placeholder="Find a project…" aria-label="Find a project" />
+	<SearchInput size="xs" placeholder="Filter layers" aria-label="Filter layers" />
+</Stack>
+```
+
 ### Disabled
 
 ```tsx
@@ -20560,7 +20858,7 @@ import { SearchInput } from "@sableui/react"
 
 The heading block for one section of a page: a title (h2 by default), an optional line of description, and actions on the title row — a "View all" link or a couple of buttons — that drop beneath the title only when the row runs out of room.
 
-**Keywords:** section header, section heading, section title, shelf, view all, see all, show all, h2, subsection, optical alignment, bleed
+**Keywords:** section header, section heading, section title, shelf, view all, see all, show all, h2, subsection, optical alignment, bleed, editorial section, large section title
 
 ## Usage
 
@@ -20569,7 +20867,7 @@ Use SectionHeader to head each section below the page title — a home-page shel
 ### Best practices
 
 - Do: Wrap the header and its content in a `<section aria-labelledby={titleId}>` (a flex column with a gap, or a Stack inside it) so the section is a named region and the header's title is its name.
-- Do: Pick titleAs by the document outline (h2 under the page h1, h3 inside an h2 section) and size by visual weight: md for a page's sections and shelves, sm for denser groups like settings.
+- Do: Pick titleAs by the document outline (h2 under the page h1, h3 inside an h2 section) and size by visual weight: lg for an editorial page's sections under a PageHeader size="lg", md for a page's sections and shelves, sm for denser groups like settings.
 - Do: Keep actions to one or two `size="sm"` buttons — the title is centred on that height. A shelf's "View all" is a ghost Button rendered as a link (`render={<a href=… />}`), named for what it opens when the label alone is ambiguous (aria-label="View all new releases").
 - Do: Pass a ghost or link action as a plain Button and let the header align it: the last direct child bleeds by its own padding at the end, so "View all" sits on the edge of the grid below, and the first bleeds at the start, which is the edge once the actions wrap beneath the title. Filled buttons keep their edge on the line. Set bleed="none" on the Button to opt one out.
 - Don't: Nudge a View all onto the edge with -me-3, or wrap the actions in your own div: the header aligns direct children only, and only by each button's real padding. If you must wrap them, set bleed on the Button inside instead.
@@ -20594,11 +20892,11 @@ Use SectionHeader to head each section below the page title — a home-page shel
 | actions | ReactNode | — | Trailing actions on the title row — a View all link or a couple of buttons, size="sm". They stay on the title's row and drop beneath it only when the row runs out of room; the title wraps rather than truncating. A ghost or link Button that ends the group bleeds by its padding at the end (and one that starts it, at the start — the edge once wrapped), so its label lines up with the content below; Button bleed="none" opts out. Direct children only. |
 | titleAs | "h2" \| "h3" \| "h4" | "h2" | The heading element, chosen by the document outline: h2 for a section under the page's h1, h3 for a subsection inside one. |
 | titleId | string | — | The title's id, so the section it heads can point at it: <section aria-labelledby={titleId}>. Generated when omitted. |
-| size | "md" \| "sm" | "md" | Visual weight, independent of the heading level: md (text-heading-3) for a page's sections and shelves; sm (text-heading-4) for denser sets — settings groups, subsections. |
+| size | "lg" \| "md" \| "sm" | "md" | Visual weight, independent of the heading level: lg (text-heading-2 over a text-body-md description) for an editorial page's sections, under a PageHeader size="lg"; md (text-heading-3) for a page's sections and shelves; sm (text-heading-4) for denser sets — settings groups, subsections. lg stops at heading-2: heading-1 is the page title's, one per route. The actions stay centred on the title's first line at every size. |
 
 ## Variants
 
-- **size**: md, sm
+- **size**: lg, md, sm
 
 ## Tokens used
 
@@ -20691,6 +20989,30 @@ import { Button, Entity, Icon, SectionHeader, Stack } from "@sableui/react"
 </section>
 ```
 
+### An editorial section (size lg)
+
+```tsx
+import { Button, Card, CardDescription, CardHeader, CardTitle, Grid, SectionHeader } from "@sableui/react"
+
+<section aria-labelledby="selected-work" className="flex flex-col gap-6">
+	<SectionHeader
+		titleId="selected-work"
+		size="lg"
+		title="Selected work"
+		description="Five projects from the last two years."
+		actions={
+			<Button variant="ghost" size="sm" render={<a href="/work" />} aria-label="View all work">
+				View all
+			</Button>
+		}
+	/>
+	<Grid minItemWidth="16rem" gap={3}>
+		<Card><CardHeader><CardTitle>Tidewater</CardTitle><CardDescription>Brand identity</CardDescription></CardHeader></Card>
+		<Card><CardHeader><CardTitle>Northlight</CardTitle><CardDescription>Product design</CardDescription></CardHeader></Card>
+	</Grid>
+</section>
+```
+
 ### A subsection inside a section
 
 ```tsx
@@ -20701,6 +21023,110 @@ import { SectionHeader } from "@sableui/react"
 
 ---
 
+# SectionRail
+
+**Status:** stable
+
+A slim vertical rail of dots, one per section of a long page, that shows where the reader is and jumps to any section. The current section's bar glides as the page scrolls; a shared tooltip names each dot.
+
+**Keywords:** section rail, scroll spy, scrollspy, dot navigation, page navigation, table of contents, on this page, chapter nav, scroll progress, case study nav
+
+## Usage
+
+Use SectionRail beside a long, single-column read — a case study, an essay, a long landing page — so the reader can see which section they are in and jump to another without leaving the text. It follows the scroll by itself (useActiveSection); pass value when the parent already knows the current section.
+
+### Best practices
+
+- Do: Give every section an id that matches its entry, and keep the list to the page's top-level sections — about ten at most, so the rail stays shorter than the viewport.
+- Do: Place it with layout classes — usually `fixed top-1/2 left-6 z-(--z-nav) -translate-y-1/2` — and hide it below the width where it would overlap the text (`max-lg:hidden`). Offer the same links another way on narrow screens, such as a Collapsible list at the top of the page.
+- Do: Pass `root` when the content scrolls inside an element (a Scroller, an inset AppShell main) rather than the window, and give sections `scroll-mt-*` when a sticky header would cover their tops after a jump.
+- Do: Set `side="right"` when the rail sits on the right edge, so labels open toward the content.
+- Don't: Use it for app navigation between pages; that is SideNav or Sidebar. A SectionRail only moves within one page. → use **SideNav**, **Sidebar**
+- Don't: Use it to show the steps of a task or a flow; that is Stepper, which shows progress through steps rather than position in a read. → use **Stepper**
+- Don't: Use it for a handful of switchable views in one place; that is Tabs. → use **Tabs**
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Rail | yes | The `<nav>` landmark: a rounded muted track holding one link per section. |
+| Dot | yes | A link to `#id`, drawn as a small dot that grows under the pointer or focus. |
+| Marker | yes | One primary bar that sits on the current section's dot and glides to the next. |
+| Label | yes | A shared tooltip that names the hovered or focused dot and travels between dots. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| sections | readonly { id: string; label: string }[] | — | The sections, in document order. `id` is the section element's id (the link goes to `#id`); `label` is the tooltip and the link's accessible name. |
+| value | string | — | The current section's id, when the parent decides it. Leave it unset and the rail follows the scroll itself. |
+| onValueChange | (id: string) => void | — | Called with the new id when the reader scrolls into a section or picks one. |
+| offset | number | 0.35 | Where the reading line sits, as a fraction of the viewport from its top. A section becomes current once its top crosses it. |
+| root | RefObject<HTMLElement \| null> | — | The element that scrolls, when it is not the window. |
+| side | "left" \| "right" | "left" | Which edge of the page the rail sits on. The labels open on the other side, toward the content. |
+| motion | "full" \| "subtle" \| "off" | "full" | How much motion this component uses: `full` inherits the app's policy, `subtle` keeps feedback and drops the marker's glide, `off` stills it. It can only turn motion down — it never overrides a reader's reduce-motion setting. |
+| aria-label | string | "Sections" | The nav landmark's name. Name it for the page ("Case study sections") when it has other navs. |
+
+## Tokens used
+
+`muted`, `muted-foreground`, `foreground`, `primary`, `ring`, `popover`, `popover-foreground`, `border-floating`
+
+## Motion
+
+- **arrival** · Root · _no motion_ — Page chrome arrives with the page; the marker lands on the current section with no transition, because a bar sliding in on load narrates a move nobody made.
+- **response** · Dot · `motion-interactive` — The dot darkens and grows under the pointer or focus, and the label travels between dots as one tooltip (TooltipGroup) rather than closing and reopening at each.
+- **transition** · Marker · `motion-glide` — One bar travels to the new section as the page scrolls, so the change reads as movement down the page. A picked section holds the bar until the reader scrolls by hand, so it goes straight there instead of stepping through every section in between, and stays on the pick even when the page ends before that section can reach the reading line. Expressive: `subtle` moves it at once.
+- **activity** · Root · _no motion_ — Navigation chrome has no working state.
+
+## Accessibility
+
+- Renders a <nav> landmark (default name "Sections") of real links to `#id`, so it works with no script, middle-click and copy-link.
+- Each link is named by its section's label; the current one carries aria-current="location".
+- Activating a link from the keyboard moves focus into the section, as following an anchor does, so the next Tab continues from there.
+- The tooltip opens on focus as well as hover; the dots are 44×32 targets.
+- Under reduced motion the jump is instant and the marker moves without travel.
+
+## Related
+
+- Components: SideNav, Tooltip, Stepper, Tabs, GlidingHighlight
+
+## Examples
+
+### Fixed beside a long read
+
+```tsx
+import { SectionRail } from "@sableui/react"
+
+<SectionRail
+  aria-label="Case study sections"
+  sections={[
+    { id: "overview", label: "Overview" },
+    { id: "problem", label: "The problem" },
+    { id: "process", label: "Process" },
+    { id: "outcome", label: "Outcome" },
+  ]}
+  className="fixed top-1/2 left-6 z-(--z-nav) -translate-y-1/2 max-lg:hidden"
+/>
+```
+
+### On the right edge
+
+```tsx
+import { SectionRail } from "@sableui/react"
+
+<SectionRail
+  side="right"
+  sections={[
+    { id: "intro", label: "Introduction" },
+    { id: "usage", label: "Usage" },
+    { id: "api", label: "API" },
+  ]}
+  className="fixed top-1/2 right-6 z-(--z-nav) -translate-y-1/2 max-lg:hidden"
+/>
+```
+
+---
+
 # SegmentedBar
 
 **Status:** stable
@@ -21180,7 +21606,7 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| Sheet (Root) | Base UI Drawer.Root props (open, defaultOpen, onOpenChange, onOpenChangeComplete, modal, disablePointerDismissal, actionsRef, handle, snapPoints, snapPoint, defaultSnapPoint, onSnapPointChange, snapToSequentialPoints) — minus swipeDirection | — | Controls open state. Uncontrolled by default. The dismiss swipe direction is not a prop: it follows SheetContent's side. onOpenChange reports reason "swipe" when a swipe closed it. |
+| Sheet (Root) | Base UI Drawer.Root props (open, defaultOpen, onOpenChange, onOpenChangeComplete, modal, disablePointerDismissal, actionsRef, handle, snapPoints, snapPoint, defaultSnapPoint, onSnapPointChange, snapToSequentialPoints) — minus swipeDirection | — | Controls open state. Uncontrolled by default. The dismiss swipe direction is not a prop: it follows SheetContent's side. onOpenChange reports reason "swipe" when a swipe closed it. Records the element focused when the sheet opens, trigger or not, and returns focus there on close. |
 | snapPoints | (number \| string)[] | — | Stops a bottom sheet rests at, smallest first: a fraction of the viewport (0.4), pixels (320), or a px/rem string ("20rem"). The panel is the full stop's height and opens at the first stop; a swipe moves between stops and a swipe below the first closes it. side="bottom" only: other sides ignore them, with a development warning. |
 | snapPoint | number \| string \| null | — | The active stop, controlled. Pair with onSnapPointChange; use defaultSnapPoint to open at a different stop uncontrolled. |
 | onSnapPointChange | (snapPoint: number \| string \| null, eventDetails) => void | — | Fires when a swipe (or your code) moves the sheet to another stop. |
@@ -21200,7 +21626,7 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 - The panel scrolls its own content (thin scrollbar, contained overscroll) when it outgrows its bound — the full height on left/right, 80vh on top/bottom.
 - Esc and click-outside dismiss by default; on touch, a swipe toward the sheet's own edge dismisses too. A short or slow drag springs back.
 - Swipe is an extra path, never the only one: Esc, click-outside and SheetClose all still work.
-- Focus matches Dialog: the first tabbable on mouse/keyboard open, the panel itself on touch (so the virtual keyboard stays down); focus returns to the trigger on close.
+- Focus matches Dialog: the first tabbable on mouse/keyboard open, the panel itself on touch (so the virtual keyboard stays down). On close, focus returns to the element that held it when the sheet opened: the SheetTrigger, or your own button when it drives a controlled open. It is captured before the content mounts, so an autoFocus field inside cannot displace it; an explicit finalFocus on SheetContent wins.
 - Render a SheetClose inside SheetContent so screen-reader users can escape the popup.
 - Slide animation runs via data-[starting-style]/data-[ending-style] attributes on the motion-duration token; while swiping the panel tracks the finger directly, and a released swipe finishes on the same token (scaled by flick speed), so reduced motion makes it instant.
 - A mouse drag that starts on sheet content selects text rather than dragging the panel; mouse dragging only starts from the padding edge.