@sableui/react 0.6.2 → 0.7.1

package/llms/components/section-header.md

@@ -0,0 +1,144 @@
+# SectionHeader
+
+**Status:** stable
+
+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
+
+## Usage
+
+Use SectionHeader to head each section below the page title — a home-page shelf with View all, a settings group, a list with its own actions. PageHeader is the route's single h1; every section under it takes a SectionHeader, with titleId wired to the section's aria-labelledby.
+
+### 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: 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.
+- Don't: Use a second PageHeader for a section — that is a second h1, and the outline then reports two documents. And do not hand-build `<div className="flex justify-between"><h2 className="text-heading-3">…` per shelf: it misses the wrapping, the aria wiring and the shared rhythm.
+- Don't: Use SectionHeader to title a Card (use CardHeader + CardTitle) or a docked tool panel (use PanelSection). It heads a section of the page, not a surface.
+- Don't: Add margin to the header to space it from its content. It has no outer spacing on purpose; the section's gap owns that rhythm, so every section on the page keeps the same one.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Title | yes | The section's heading (h2 by default), wrapping rather than truncating. Its id names the section. |
+| Description | no | One line of supporting copy under the title, capped at the prose measure. |
+| Actions | no | Buttons or links at the title row's end; they move beneath the title when the row is too narrow for both. A borderless (ghost/link) Button at either end of the group is optically aligned: its label, not its invisible padding, meets the content edge. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| title | ReactNode | — | The section's title. |
+| description | ReactNode | — | One line of supporting copy beneath the title, capped at the prose measure. |
+| 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. |
+
+## Variants
+
+- **size**: md, sm
+
+## Tokens used
+
+`foreground`, `muted-foreground`
+
+## Motion
+
+- **arrival** · root · _no motion_ — A heading arrives with the section it names; animating it separately would make the section's title lag its content.
+- **response** · root · _no motion_ — The header itself is not interactive; the Buttons passed as actions carry their own response.
+- **transition** · root · _no motion_ — It has no states of its own to move between.
+- **activity** · root · _no motion_ — It never does indeterminate work.
+
+## Accessibility
+
+- Renders a real heading (h2 by default); choose titleAs by the outline, never to get a size — size sets the look.
+- The title always carries an id (titleId, or a generated one). Point the section at it with aria-labelledby so the section is announced as a named region and appears in landmark navigation.
+- A repeated "View all" is ambiguous in a links list; name each one for its section (aria-label="View all new releases") or keep the visible label specific.
+
+## Related
+
+- Components: PageHeader, CardHeader, PanelSection, Grid, Stack, Button
+- Patterns: SettingsPage, DashboardPage
+
+## Examples
+
+### A shelf with View all
+
+```tsx
+import { Button, Card, CardDescription, CardHeader, CardTitle, Grid, SectionHeader } from "@sableui/react"
+
+<section aria-labelledby="new-releases" className="flex flex-col gap-4">
+	<SectionHeader
+		titleId="new-releases"
+		title="New releases"
+		description="Fresh from artists you follow."
+		actions={
+			<Button variant="ghost" size="sm" render={<a href="/new" />} aria-label="View all new releases">
+				View all
+			</Button>
+		}
+	/>
+	<Grid minItemWidth="10rem" gap={2}>
+		<Card><CardHeader><CardTitle>Night Swim</CardTitle><CardDescription>Lena Vale</CardDescription></CardHeader></Card>
+		<Card><CardHeader><CardTitle>Low Tide</CardTitle><CardDescription>Harbour Lights</CardDescription></CardHeader></Card>
+	</Grid>
+</section>
+```
+
+### A settings section
+
+```tsx
+import { Field, SectionHeader, Switch } from "@sableui/react"
+
+<section aria-labelledby="playback" className="flex flex-col gap-4">
+	<SectionHeader
+		titleId="playback"
+		size="sm"
+		title="Playback"
+		description="How tracks start, end and blend into each other."
+	/>
+	<Field label="Crossfade" orientation="horizontal">
+		<Switch defaultChecked />
+	</Field>
+	<Field label="Normalize volume" orientation="horizontal">
+		<Switch />
+	</Field>
+</section>
+```
+
+### A section with two actions
+
+```tsx
+import { Button, Entity, Icon, SectionHeader, Stack } from "@sableui/react"
+
+<section aria-labelledby="playlists" className="flex flex-col gap-4">
+	<SectionHeader
+		titleId="playlists"
+		title="Your playlists"
+		actions={
+			<>
+				<Button variant="ghost" size="sm" iconStart={<Icon name="filter" />}>Filter</Button>
+				<Button size="sm" iconStart={<Icon name="plus" />}>New playlist</Button>
+			</>
+		}
+	/>
+	<Stack gap={1}>
+		<Entity className="[--entity-px:0]" title="Late drives" subtitle="42 tracks" />
+		<Entity className="[--entity-px:0]" title="Focus" subtitle="18 tracks" />
+	</Stack>
+</section>
+```
+
+### A subsection inside a section
+
+```tsx
+import { SectionHeader } from "@sableui/react"
+
+<SectionHeader titleAs="h3" size="sm" title="Appears on" />
+```

package/llms/components/sheet.md

@@ -27,6 +27,7 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 | SheetHeader | no | The title and description region. |
 | SheetTitle | no | The sheet heading. |
 | SheetDescription | no | Supporting context for the sheet. |
+| SheetList | no | Edge-to-edge rows (Entity) aligned with the header — a queue, notifications, a picker. |
 | SheetFooter | no | Footer actions for the workflow. |
 
 ## Subcomponents
@@ -39,6 +40,7 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 | SheetHeader | ComponentProps<"div"> | Top section holding SheetTitle/SheetDescription. |
 | SheetTitle | Base UI Drawer.Title props + className | The sheet's accessible name — wires aria-labelledby on the popup. |
 | SheetDescription | Base UI Drawer.Description props + className | Muted supporting line; wires aria-describedby. |
+| SheetList | ComponentProps<"div"> | Rows that run edge to edge in the sheet, Entity most often. It bleeds through the sheet's padding (--sheet-p) and hands it back to each row as --entity-px, so row content lines up with SheetHeader and a row's hover fill reaches the panel's edges. Without it a list of Entity rows sits 12px in from the header. The Sheet equivalent of CardList. |
 | SheetFooter | ComponentProps<"div"> | Bottom row for actions, pinned after the scrollable body. In a bottom sheet it stacks: full width, the primary on top, every button at the cta height. |
 
 ## Props
@@ -72,6 +74,14 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 
 ## Examples
 
+### List of rows (a queue)
+
+```tsx
+import { Button, Entity, GradientArt, Sheet, SheetContent, SheetHeader, SheetList, SheetTitle, SheetTrigger } from "@sableui/react"
+
+<Sheet><SheetTrigger render={<Button variant="secondary">Queue</Button>} /><SheetContent><SheetHeader><SheetTitle>Up next</SheetTitle></SheetHeader><SheetList>{queue.map((track) => <Entity key={track.id} leading={<GradientArt aria-hidden seed={track.title} className="size-10 rounded-sm" />} title={track.title} subtitle={track.artist} />)}</SheetList></SheetContent></Sheet>
+```
+
 ### Basic (right)
 
 ```tsx

package/llms/components/sidebar.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Desktop side-navigation rail (in-flow sticky, hidden below lg) with SidebarHeader / SidebarNav / SidebarItem / SidebarFooter parts. Items are router-agnostic via the `render` prop; an optional collapsed icon-rail mode reveals labels in tooltips.
+Desktop side-navigation rail (in-flow sticky, hidden below lg) with SidebarHeader / SidebarBrand / SidebarNav / SidebarItem / SidebarFooter parts. Items are router-agnostic via the `render` prop; an optional collapsed icon-rail mode reveals labels in tooltips.
 
 **Keywords:** sidebar, navigation, app chrome, rail
 
@@ -28,6 +28,7 @@ Use Sidebar for persistent desktop navigation or application chrome outside the
 
 | Name | Type | Description |
 | --- | --- | --- |
+| SidebarBrand | { mark: ReactNode; label: ReactNode; render?: useRender.RenderProp } + div props | The brand row, inside SidebarHeader, on the same grid as SidebarItem: mark in the icons' 24px slot, label on the labels' column, so a logo lines up with the nav below it without copying the rail's inset numbers. Collapsed, it shows the mark alone (named by a string label). render={<Link to="/" />} makes it the home link. |
 | SidebarItem | { label: ReactNode; icon?: ReactNode; active?: boolean; badge?: ReactNode; render?: useRender.RenderProp } + button props | A single nav row. label is the row text (inline when expanded, in a hover tooltip when collapsed); icon is the leading icon node (the consumer swaps fill weight for the active state); active marks the current route (accent fill + aria-current="page"); badge is a trailing node (e.g. a count) pushed to the row end and hidden when collapsed; render composes another element, e.g. render={<Link to="/x" />}. |
 
 ## Props
@@ -62,10 +63,10 @@ Use Sidebar for persistent desktop navigation or application chrome outside the
 ### Rail with nav
 
 ```tsx
-import { Icon, NotificationBadge, Sidebar, SidebarFooter, SidebarHeader, SidebarItem, SidebarNav } from "@sableui/react"
+import { Icon, NotificationBadge, Sidebar, SidebarBrand, SidebarFooter, SidebarHeader, SidebarItem, SidebarNav } from "@sableui/react"
 // <Link> = your router's link (react-router, next/link, @tanstack/router, …)
 
-<Sidebar><SidebarHeader>{brand}</SidebarHeader><SidebarNav><SidebarItem icon={<Icon name="bell" />} label="Notifications" badge={<NotificationBadge count={3} />} render={<Link to="/notifications" />} /></SidebarNav><SidebarFooter>{wallet}</SidebarFooter></Sidebar>
+<Sidebar><SidebarHeader><SidebarBrand mark={<Icon name="music" variant="solid" />} label="Undertow" render={<Link to="/" />} /></SidebarHeader><SidebarNav><SidebarItem icon={<Icon name="bell" />} label="Notifications" badge={<NotificationBadge count={3} />} render={<Link to="/notifications" />} /></SidebarNav><SidebarFooter>{wallet}</SidebarFooter></Sidebar>
 ```
 
 ### Collapsible (icon rail)

package/llms/components/slider.md

@@ -52,6 +52,9 @@ Use Slider for bounded numeric choices where approximate adjustment is faster th
 | step | number | 1 | Granularity the slider steps through. Snaps to multiples. |
 | disabled | boolean | false | Ignore user interaction and dim the control. |
 | orientation | 'horizontal' \| 'vertical' | horizontal | Axis the slider tracks along. A vertical slider has no intrinsic length — give it a height (h-40, or flex-1 in a column). |
+| aria-label | string | — | Accessible name, applied to each thumb's input (the element with role=slider). A range also names its group with it. |
+| getAriaLabel | (index) => string | — | Per-thumb name for a range ("Minimum price" / "Maximum price"). Wins over aria-label on the thumbs. |
+| getAriaValueText | (formattedValue, value, index) => string | — | What a screen reader announces for the value when the number alone is wrong — a seek bar's "1:23 of 3:45". For units or percent, `format` (Intl.NumberFormatOptions) is enough. |
 
 ## Tokens used
 
@@ -64,7 +67,8 @@ Use Slider for bounded numeric choices where approximate adjustment is faster th
 - The thumb's hit area is a fixed 16px box at every state. Only the decorative inner dot resizes — rest 12px, full 16px on hover, keyboard focus, and drag — so the target a pointer or finger must land on never moves or changes size. Keyboard users, who never hover, get the enlarged dot from focus-visible.
 - The rest-to-full transition uses the motion duration/easing tokens, so it collapses to an instant state change under prefers-reduced-motion or MotionProvider off. The size change itself still happens: it reports interaction state, it is not decoration.
 - Range sliders get one thumb per value with minStepsBetweenValues honored.
-- Pass an aria-label (or getAriaLabel on a thumb) so each handle has an accessible name.
+- Pass aria-label (or getAriaLabel for a range) so each handle has an accessible name. On Slider it reaches the thumb inputs; on a bare SliderRoot it only names the role=group — when composing, put aria-label / getAriaLabel on each SliderThumb, or label the Root with aria-labelledby or a Field, which Base UI does carry to the thumbs.
+- getAriaValueText sets aria-valuetext for values a number misreads (time, named steps).
 
 ## Related
 
@@ -86,7 +90,15 @@ import { Slider } from "@sableui/react"
 import { Slider } from "@sableui/react"
 
 const [range, setRange] = useState([20, 60])
-<Slider value={range} onValueChange={setRange} aria-label="Price range" />
+<Slider value={range} onValueChange={setRange} aria-label="Price range" getAriaLabel={(i) => (i ? "Maximum price" : "Minimum price")} />
+```
+
+### Seek bar with spoken time
+
+```tsx
+import { Slider } from "@sableui/react"
+
+<Slider value={position} max={duration} onValueChange={seek} aria-label="Seek" getAriaValueText={(_, v) => `${formatTime(v)} of ${formatTime(duration)}`} />
 ```
 
 ### Stepped

package/llms/components/theme-selector.md

@@ -2,23 +2,37 @@
 
 **Status:** stable
 
-A presentational radiogroup for choosing a Sable design theme from theme manifests — swatch-strip cards for a settings page, or compact rows for tool chrome. Pair it with useSableTheme().themeId and setThemeId when the app uses SableThemeProvider.
+A presentational radiogroup for choosing a Sable design theme from theme manifests — tiles that draw each theme as a miniature of its own interface (its colours, type and corner shape) for a settings page, or compact rows for tool chrome. Pair it with useSableTheme().themeId and setThemeId when the app uses SableThemeProvider.
 
 **Keywords:** theme selector, theme, appearance, skin, design theme, preset
 
 ## Usage
 
-Use ThemeSelector wherever a person picks a theme. The default `cards` layout is page-register furniture: a swatch strip, a name, and a caption only where one distinguishes the card (the default theme, or a single-mode theme), at ~144px tall. Use `layout="list"` in tool chrome, a popover, or any docked panel — five cards is the wrong object for a 256px surface, however it is sized. For colour mode (light/dark/system) use ThemeSwitcher, which is a segmented control and belongs in chrome as-is.
+Use ThemeSelector wherever a person picks a theme. The default `cards` layout is page-register furniture: a miniature of each theme's interface (its background, "Aa" in its display face, a card, and a primary button in its own corner shape), with the name and a caption only where one distinguishes it (the default theme, or a single-mode theme). Use `layout="list"` in tool chrome, a popover, or any docked panel — five cards is the wrong object for a 256px surface, however it is sized. For colour mode (light/dark/system) use ThemeSwitcher, which is a segmented control and belongs in chrome as-is.
 
 ### Best practices
 
-- Do: Use layout="list" in a popover, a menu, or a docked panel. Rows sit on the --control-sm ladder and still show each theme's swatch strip, so the choice stays visible rather than described. Rows take `sable-frame-inner`, so host the list in a sable-frame (`sable-frame sable-surface sable-surface-popover sable-frame-popover` — PopoverContent is not one; give it that class list, or its p-4 leaves the rows unnested) and their corners nest concentrically.
+- Do: Use layout="list" in a popover, a menu, or a docked panel. Rows sit on the --control-sm ladder and still show a small tile of each theme, so the choice stays visible rather than described. Rows take `sable-frame-inner`, so host the list in a sable-frame (`sable-frame sable-surface sable-surface-popover sable-frame-popover` — PopoverContent is not one; give it that class list, or its p-4 leaves the rows unnested) and their corners nest concentrically.
 - Do: Pass mode={useSableTheme().mode} so every preview renders in the colour mode actually in use, rather than in each theme's manifest default.
+- Do: Use ThemeSelector when switching is free: it is a radio group, so arrow keys check the next theme and onValueChange fires on every press — the page restyles as you go, which is the point of a live theme switcher. When a switch has a cost (it opens a "discard changes?" confirm, loads fonts, or resets other settings), use a DisclosurePicker list instead, with a `ThemePreview size="sm"` as each option's `media`: arrows only move there, and Enter, Space or a click commits.
 - Do: Load each theme's fonts in the host app. Every card carries a type specimen in that theme's own face so people can compare typography as well as color. A theme whose fonts are not loaded falls back to system-ui, and its specimen stops telling the truth.
 - Don't: Add a viewport breakpoint to force a column count — `className="sm:grid-cols-1"` or similar. `sm:` keys off the VIEWPORT, not this component's container, so on a wide screen it does nothing for a narrow parent. The cards grid already reflows on its own width via auto-fit.
 - Don't: Put the cards layout in workspace chrome. It was built for a settings page; in a 256px popover the cards clip their labels to a single character and grow to roughly twice their intended height.
 - Don't: Use ThemeSelector for light / dark / system colour mode. That is ThemeSwitcher — a segmented control. This picks the design theme, which is a different axis entirely, and the two are frequently confused.
 
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| ThemeSelector | yes | The radiogroup of themes, as cards or list rows. |
+| ThemePreview | no | The tile each option draws, exported for showing a theme outside the picker — the row naming the current theme, or the `media` of each option in a commit-on-Enter DisclosurePicker list. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| ThemePreview | { theme: ThemeManifest; mode?: "light" \| "dark"; size?: "md" \| "sm" } | The tile each option draws: the theme as a miniature of itself (background, "Aa" in its display face, a card, a primary button in its own corner shape), in its own scope. Exported for anywhere that shows a theme outside the picker, e.g. a row naming the current preset, or each option of a DisclosurePicker list where a pick has a cost. Sized in the caller's spacing unit, so it lines up with the row it sits in. |
+
 ## Props
 
 | Name | Type | Default | Description |
@@ -26,7 +40,7 @@ Use ThemeSelector wherever a person picks a theme. The default `cards` layout is
 | value | ThemeId | — | The currently selected Sable design theme id. |
 | onValueChange | (themeId: ThemeId) => void | — | Called with the next design theme id when an option is chosen. |
 | themes | readonly ThemeManifest[] | themeManifests | Theme manifests to render. Defaults to Sable's built-in themes. |
-| mode | "light" \| "dark" | — | Preview mode for each card's swatch strip. Pass useSableTheme().mode to match the current color mode; omitted cards use their manifest defaultMode. |
+| mode | "light" \| "dark" | — | Preview mode for each theme's tile. Pass useSableTheme().mode to match the current color mode; omitted cards use their manifest defaultMode. |
 | label | string | "Design theme" | Accessible label for the radiogroup. |
 | layout | "cards" \| "list" | "cards" | Presentation. "cards" is the page-register picker (~144px per card); "list" is one compact --control-sm row per theme, for chrome and popovers. A presentation variant, not a size — "list" is not "cards, smaller" — which is why it is a prop rather than a density scope. |
 | className | string | — | Merged onto the outer radiogroup grid. |
@@ -38,6 +52,7 @@ Use ThemeSelector wherever a person picks a theme. The default `cards` layout is
 ## Accessibility
 
 - The container is role="radiogroup" with an aria-label; each card is a role="radio" button with aria-checked reflecting the selected theme.
+- Standard radio keyboard: arrow keys move the check — calling onValueChange on each press — and Space checks the focused option. That instant switching is right for a free, reversible choice; where a switch has a cost, use a DisclosurePicker list (a listbox: arrows move, Enter commits) with ThemePreview tiles instead.
 - Focus-visible draws a 2px ring on the focused card.
 - The selected card wears the shared selection-card checked ring (the same as RadioCard and CheckboxCard), a muted fill and a check icon, so selection does not rely on colour alone.
 - Presentational only: it does not change the document theme; pass useSableTheme().setThemeId or apply the change in onValueChange.
@@ -48,6 +63,31 @@ Use ThemeSelector wherever a person picks a theme. The default `cards` layout is
 
 ## Examples
 
+### When a switch has a cost: a DisclosurePicker list of ThemePreview tiles
+
+```tsx
+import { DisclosurePicker, DisclosurePickerList, DisclosurePickerOption, DisclosurePickerPanel, DisclosurePickerTrigger, ThemePreview, useSableTheme } from "@sableui/react"
+
+// Arrows move; Enter, Space or a click commits — so whatever the switch costs
+// (a confirm, a font load, a reset) happens once, on the pick.
+const { themeId, setThemeId, themes, mode } = useSableTheme()
+const current = themes.find((theme) => theme.id === themeId)
+<DisclosurePicker>
+  <DisclosurePickerTrigger aria-label={`Theme: ${current?.label}`} media={current ? <ThemePreview theme={current} mode={mode} size="sm" /> : null}>
+    {current?.label}
+  </DisclosurePickerTrigger>
+  <DisclosurePickerPanel>
+    <DisclosurePickerList aria-label="Theme" value={themeId} onValueChange={setThemeId}>
+      {themes.map((theme) => (
+        <DisclosurePickerOption key={theme.id} value={theme.id} media={<ThemePreview theme={theme} mode={mode} size="sm" />}>
+          {theme.label}
+        </DisclosurePickerOption>
+      ))}
+    </DisclosurePickerList>
+  </DisclosurePickerPanel>
+</DisclosurePicker>
+```
+
 ### With SableThemeProvider
 
 ```tsx

package/llms/components/tree.md

@@ -15,7 +15,7 @@ Use Tree for the hierarchy panel in a workspace: layers, objects, an inspector o
 - Do: Give Tree an aria-label naming the hierarchy ("Layers", "Files"). It is a role="tree", and an unnamed tree is announced as just "tree".
 - Do: For a file tree, nest with `subtree` and use the icon convention: `icon={<Icon name="folder" />}` on a row with a subtree, `icon={<Icon name="file" />}` on a leaf. There are no folder/file presets — they would only bind those two props.
 - Do: Give TreeAddRow the same depth as the rows it adds to, so its mark lands in their type column: one deeper than the parent for a child list, the parent's own depth for a sibling list.
-- Do: Put mutable per-row state (visibility, solo, a row menu) in `actions`, on the right rail. Show it on hover, and at rest only when its value is the non-default one.
+- Do: Put mutable per-row state (visibility, solo, a row menu) in `actions`, on the right rail. Show it on hover with `reveal-on-hover` (the row is its `group`), and at rest only when its value is the non-default one.
 - Do: Let section headers sit on the rail at the same height as a depth-0 row. Space and a hairline separate sections; TreeSection handles both, including dropping the divider on the first.
 - Don't: Hardcode a left inset anywhere in the panel. Use treeIndent(depth) or var(--tree-rail); a hand-written px value is how a tree ends up with four different left edges.
 - Don't: Redefine --tree-indent to anything other than --tree-column. A step smaller than the column puts a child's content left of its parent's and the nesting reads inverted.
@@ -58,7 +58,7 @@ Use Tree for the hierarchy panel in a workspace: layers, objects, an inspector o
 | selected | boolean | false | Selection fill and accent bar on a TreeRow. Inside a Tree it is exposed as aria-selected on the treeitem; a row rendered outside a Tree is a plain div and exposes aria-current instead. |
 | toggleLabel | string | — | Names the thing being disclosed, for the toggle's accessible label — "Expand Background" rather than "Expand group". Every example passes it; a screen-reader user hearing twenty identical "Expand group" buttons has no way to tell them apart. |
 | icon | ReactNode | — | The kind marker for a TreeRow, rendered in the type column at 1em. Use a semantic Icon so it follows the app icon set. |
-| disclosureIcon | ReactNode | — | Replaces TreeRow's semantic chevron-down icon. Omit to use the current IconProvider set or Reicon by default. |
+| disclosureIcon | ReactNode | — | Replaces TreeRow's semantic chevron-down icon. Omit to use the chevron-down from the app's IconProvider set. |
 | actions | ReactNode | — | Right-rail controls for a TreeRow: visibility, solo, a row menu. |
 | label | ReactNode | — | TreeAddRow's visible label. Name what gets added — 'Add effect', not 'Add'. |
 
@@ -74,7 +74,7 @@ Use Tree for the hierarchy panel in a workspace: layers, objects, an inspector o
 - Each treeitem is named by its own label (aria-labelledby the name), never by the text of its icon or action buttons.
 - The disclosure is a real button with aria-expanded and a label naming what it discloses, and it stops propagation so collapsing a group never changes the selection. Inside a Tree the treeitem carries aria-expanded and the arrow keys, so the button becomes a pointer target only: aria-hidden, out of the tab order, and it leaves focus where it was when clicked.
 - The disclosure's POINTER TARGET is bigger than the mark it draws. `--tree-column` is 20px comfortable and 18px compact, both under WCAG 2.5.8's 24x24 floor, so a centred pseudo-element takes the hit at `--control-xs` (28/24) instead. The drawn box stays on the column, because that column is also the indent step — growing the button would push every name in the tree one column right.
-- Right-rail actions stay in the tab order, so a row with actions costs extra Tab stops. Keep actions few and show them on hover and focus-visible.
+- Right-rail actions stay in the tab order, so a row with actions costs extra Tab stops. Keep actions few and reveal them with `reveal-on-hover`, which also shows them on focus and always on touch.
 - `dimmed` is presentation only. A row switched off must also say so in its actions' aria-pressed or its accessible name; opacity alone is invisible to a screen reader and fails contrast.
 - Right-rail controls that appear on hover must also appear on focus-visible, or they are unreachable by keyboard.
 

package/llms/layout/grid.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-CSS Grid within a region. Two modes: fixed/responsive cols count, or minItemWidth auto-fit so cells breathe with NO breakpoints (the default choice for card grids).
+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.
 
 **Keywords:** grid, card grid, auto fit, layout
 
@@ -13,16 +13,20 @@ Use Grid for uniform grid layouts inside a Region, especially card grids that ca
 ### Best practices
 
 - Do: Prefer minItemWidth for responsive card grids that do not need breakpoint-specific spans.
+- Do: Keep the default track="fill" for collections whose count is data (search results, shelves, galleries): sparse rows keep their empty columns, so one result stays one cell wide.
+- Do: Use track="fit" only for a fixed set designed to span the row, such as three KPI cards.
 - Do: Use explicit columns only when the design truly needs a fixed track count.
 - Don't: Do not use Grid to set a page's reading width; use Region or Center.
+- Don't: Do not use track="fit" for results or other data-driven collections: with one or two items the empty columns collapse and each item stretches across the row (a single result rendered as a full-width cover).
 
 ## Props
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | cols | number \| { base?, sm?, md?, lg?, xl?, "2xl"? } | 12 | Fixed column count or a mobile-first breakpoint map ({ base: 2, md: 4 }). Ignored when minItemWidth is set. |
-| minItemWidth | string | — | Auto-fit mode: repeat(auto-fit, minmax(minItemWidth, 1fr)) — the grid grows/wraps responsively without breakpoints. e.g. "16rem". |
-| gap | number \| string | var(--grid-gutter) | Gap between cells. Number = rhythm units (×8px); string = raw CSS. |
+| minItemWidth | string | — | Breathing mode: repeat(auto-fill, minmax(minItemWidth, 1fr)) — as many columns of at least minItemWidth as fit, wrapping without breakpoints. e.g. "16rem". |
+| track | "fill" \| "fit" | "fill" | What a minItemWidth grid does with columns it has no items for (only visible when fewer items than fit one row). "fill" (auto-fill) keeps them, so items keep their size whatever their count — one search result is one cover wide, not a banner. Use it for collections whose count is data: results, shelves, galleries. "fit" (auto-fit) collapses them and stretches the items to share the row — only for a fixed set designed to span it (three KPI cards, plan tiers). |
+| gap | number \| [row, column] \| string | var(--grid-gutter) | Gap between cells. Number = rhythm units (×8px); [row, column] = two rhythm counts, for a gallery whose rows want more air than its columns; string = raw CSS. |
 
 ## Related
 
@@ -38,6 +42,23 @@ import { Card, CardHeader, CardTitle, Grid } from "@sableui/react"
 <Grid minItemWidth="16rem" gap={3}><Card><CardHeader><CardTitle>Alpha</CardTitle></CardHeader></Card><Card><CardHeader><CardTitle>Beta</CardTitle></CardHeader></Card><Card><CardHeader><CardTitle>Gamma</CardTitle></CardHeader></Card></Grid>
 ```
 
+### Sparse results keep their size
+
+```tsx
+import { Card, CardDescription, CardHeader, CardTitle, Grid } from "@sableui/react"
+
+// One match still renders one cover wide: the empty columns are kept (track="fill", the default).
+<Grid minItemWidth="10rem" gap={2}><Card><CardHeader><CardTitle>Night Swim</CardTitle><CardDescription>Album · Undertow</CardDescription></CardHeader></Card></Grid>
+```
+
+### A fixed set that spans the row
+
+```tsx
+import { Card, CardDescription, CardHeader, Grid } from "@sableui/react"
+
+<Grid minItemWidth="12rem" track="fit" gap={2}><Card><CardHeader><CardDescription>Listeners</CardDescription><span className="text-mono-xl">48.2k</span></CardHeader></Card><Card><CardHeader><CardDescription>Streams</CardDescription><span className="text-mono-xl">1.3M</span></CardHeader></Card><Card><CardHeader><CardDescription>Saves</CardDescription><span className="text-mono-xl">9,410</span></CardHeader></Card></Grid>
+```
+
 ### Responsive fixed columns
 
 ```tsx

package/llms/layout/region.md

@@ -12,9 +12,14 @@ Use Region as the page-width primitive that applies fluid page inset and an opti
 
 ### Best practices
 
-- Do: Choose the max value by content role, such as prose, form, feed, content, wide, or full.
+- Do: Choose the max value by what the person does on the page: read (prose), fill in a form (form), scroll one stream (feed), review one record or settings (content), scan and compare rows or cards (wide).
+- Do: Omit max (fluid) for work across panes, a board, an editor or a map, where a flexible part uses the extra width; cap text inside it with --measure-prose.
+- Do: Give sibling routes in one nav the same width so the header does not jump between them.
+- Do: Review a capped or fluid route at 1920px and 2560px: a cap is a ceiling, so below the cap plus app chrome every choice looks the same.
 - Do: Use Region near the route or section boundary so inner layout stays intentional.
 - Don't: Do not use Region as a global wrapper that forces every page into the same max width.
+- Don't: Do not go fluid when the extra width only widens the gaps between fixed columns; cap it.
+- Don't: Do not read full as edge to edge: it is the largest cap and keeps the page inset. Use bleed for edge to edge.
 
 ## Props
 
@@ -22,7 +27,7 @@ Use Region as the page-width primitive that applies fluid page inset and an opti
 | --- | --- | --- | --- |
 | as | ElementType | "div" | Semantic element to render (e.g. "main", "section", "nav"). |
 | inset | boolean | true | Apply the fluid horizontal page inset (--page-inset). |
-| max | "prose" \| "form" \| "feed" \| "content" \| "wide" \| "full" \| CSS length | — | Opt-in centered max-width cap, purpose-named: prose 65ch (long-form reading) · form 480px (auth, narrow single-column forms) · feed 640px (single-column timeline) · content 896px (settings/admin panes) · wide 1280px (dashboards, tables, card grids) · full 1536px (full-bleed ceiling). Omit for fully fluid. |
+| max | "prose" \| "form" \| "feed" \| "content" \| "wide" \| "full" \| CSS length | — | Opt-in centered max-width cap, purpose-named: prose 65ch (long-form reading) · form 480px (auth, narrow single-column forms) · feed 640px (single-column timeline) · content 896px (settings/admin panes) · wide 1280px (dashboards, tables, card grids) · full 1536px (the largest cap; keeps the inset, so not edge to edge — that is bleed). Omit for fluid: work views whose panes, board or canvas use the extra width. A cap is a ceiling: it applies only once the viewport minus app chrome exceeds it, so judge it at 1920px and up. |
 | bleed | boolean | false | Full-bleed: edge to edge with no inset. Overrides inset. |
 | safeArea | boolean \| ("top"\|"bottom"\|"left"\|"right")[] | false | env(safe-area-inset-*) padding for fixed or native-shell surfaces. true pads top+bottom; pass an edge array to target edges. |
 
@@ -40,10 +45,18 @@ import { PageHeader, Region } from "@sableui/react"
 <Region as="main" max="content"><PageHeader title="Settings" /></Region>
 ```
 
-### Fluid dashboard region
+### Dashboard region (capped at wide)
 
 ```tsx
 import { Card, CardHeader, CardTitle, Grid, Region } from "@sableui/react"
 
 <Region max="wide"><Grid minItemWidth="16rem"><Card><CardHeader><CardTitle>Revenue</CardTitle></CardHeader></Card><Card><CardHeader><CardTitle>Collects</CardTitle></CardHeader></Card></Grid></Region>
 ```
+
+### Fluid workspace: the queue's table takes the extra width
+
+```tsx
+import { Card, CardContent, Col, Columns, DataTable, Region, SideNav, SideNavItem } from "@sableui/react"
+
+<Region as="main"><Columns count={{ base: 1, lg: 12 }}><Col span={{ base: 1, lg: 3 }}><SideNav aria-label="Views"><SideNavItem label="Open" active /><SideNavItem label="Pending" /></SideNav></Col><Col span={{ base: 1, lg: 9 }}><Card><CardContent flush><DataTable columns={columns} data={tickets} /></CardContent></Card></Col></Columns></Region>
+```

package/llms/patterns/dashboard-page.md

@@ -29,7 +29,7 @@ App-shell creator dashboard: a branded Sidebar with an account footer (AppHeader
 ## Source
 
 ```tsx
-import { AppHeader, AppShell, Avatar, Badge, BottomNav, BottomNavItem, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardList, CardTitle, DataTable, Entity, Grid, Icon, MenuItem, MenuSeparator, Meter, NotificationBadge, OverflowMenu, Page, PageHeader, RelativeTime, Row, Sidebar, SidebarFooter, SidebarHeader, SidebarItem, SidebarNav, Stack } from "@sableui/react"
+import { AppHeader, AppShell, Avatar, Badge, BottomNav, BottomNavItem, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardList, CardTitle, DataTable, Entity, Grid, Icon, MenuItem, MenuSeparator, Meter, NotificationBadge, OverflowMenu, Page, PageHeader, RelativeTime, Row, Sidebar, SidebarBrand, SidebarFooter, SidebarHeader, SidebarItem, SidebarNav, Stack } from "@sableui/react"
 
 // Edition status → Badge tone. Sable has no status vocabulary of its own;
 // an app maps ITS states onto tones once, here, and every badge follows.
@@ -126,10 +126,7 @@ export function DashboardPage() {
 			sidebar={
 				<Sidebar>
 					<SidebarHeader>
-						<Row gap={1} align="center" className="px-3">
-							<Icon name="gem" variant="solid" className="text-xl" />
-							<span className="text-title-sm">Atelier</span>
-						</Row>
+						<SidebarBrand mark={<Icon name="gem" variant="solid" />} label="Atelier" render={<a href="/" />} />
 					</SidebarHeader>
 					<SidebarNav>
 						<SidebarItem icon={<Icon name="grid" />} label="Overview" active render={<a href="/" />} />
@@ -274,7 +271,7 @@ export function DashboardPage() {
 							<span className="text-caption text-muted-foreground">
 								Showing {editions.length} of {editionCount} editions
 							</span>
-							<Button variant="ghost" size="sm" render={<a href="/editions" />}>
+							<Button variant="ghost" size="sm" bleed="end" render={<a href="/editions" />}>
 								View all editions
 								<Icon name="arrow-right" />
 							</Button>

package/llms/patterns/feed-page.md

@@ -147,10 +147,10 @@ const renderPost = (post: Post) => (
 						</Meter>
 					</Stack>
 				) : null}
-				{/* Pulled out by exactly a sm Button's own padding (px-3), so the
-				    first icon lands on the text edge above it. */}
-				<Row gap={0.5} className="-ms-3">
-					<Button variant="ghost" size="sm" aria-label={`Like, ${post.likes} likes`}>
+				{/* bleed="start" pulls the first button out by exactly its own
+				    padding, so its icon lands on the text edge above it. */}
+				<Row gap={0.5}>
+					<Button variant="ghost" size="sm" bleed="start" aria-label={`Like, ${post.likes} likes`}>
 						<Icon name="heart" />
 						{post.likes}
 					</Button>

package/llms/patterns/list-detail-page.md

@@ -257,6 +257,7 @@ export function ListDetailPage() {
 							ref={backRef}
 							variant="ghost"
 							size="sm"
+							bleed="start"
 							iconStart={<Icon name="chevron-left" />}
 							onClick={backToList}
 							className="self-start lg:hidden"

package/llms/patterns/settings-page.md

@@ -28,7 +28,7 @@ Account settings inside the app shell: a sticky SideNav section rail beside a co
 
 ```tsx
 import { useState } from "react"
-import { AppHeader, AppShell, Avatar, BottomNav, BottomNavItem, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardList, CardTitle, Col, Columns, DestructiveActionModal, Entity, Field, Form, Grid, Icon, Input, MenuItem, MenuSeparator, NotificationBadge, OverflowMenu, Page, PageHeader, Row, Select, SelectContent, SelectItem, SelectTrigger, Sidebar, SidebarFooter, SidebarHeader, SidebarItem, SidebarNav, SideNav, SideNavItem, Stack, Switch, Textarea } from "@sableui/react"
+import { AppHeader, AppShell, Avatar, BottomNav, BottomNavItem, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardList, CardTitle, Col, Columns, DestructiveActionModal, Entity, Field, Form, Grid, Icon, Input, MenuItem, MenuSeparator, NotificationBadge, OverflowMenu, Page, PageHeader, Row, Select, SelectContent, SelectItem, SelectTrigger, Sidebar, SidebarBrand, SidebarFooter, SidebarHeader, SidebarItem, SidebarNav, SideNav, SideNavItem, Stack, Switch, Textarea } from "@sableui/react"
 
 const sections = [
 	{ id: "profile", label: "Profile" },
@@ -90,10 +90,7 @@ export function SettingsPage() {
 			sidebar={
 				<Sidebar>
 					<SidebarHeader>
-						<Row gap={1} align="center" className="px-3">
-							<Icon name="gem" variant="solid" className="text-xl" />
-							<span className="text-title-sm">Atelier</span>
-						</Row>
+						<SidebarBrand mark={<Icon name="gem" variant="solid" />} label="Atelier" render={<a href="/" />} />
 					</SidebarHeader>
 					<SidebarNav>
 						<SidebarItem icon={<Icon name="grid" />} label="Overview" render={<a href="/" />} />