@sableui/react 0.6.2 → 0.7.1

package/llms/components/disclosure-picker.md

@@ -0,0 +1,168 @@
+# DisclosurePicker
+
+**Status:** stable
+
+A property row that names the current value and opens its list in place, beneath the row, instead of in a popup — for a tool panel or settings column where the choice is made while looking at what it changes. Built on Collapsible; the list is a listbox — arrow keys move, Enter or a click picks, applies and closes — and an optional search field filters long lists.
+
+**Keywords:** disclosure picker, inline picker, in-place select, expanding list, property row, font picker, preset picker, inspector, picker row
+
+## Usage
+
+Use DisclosurePicker for one-of-many choices in a docked panel or inspector where a popup would cover the preview the choice is about: the row shows the current value (in its own face, with a tile, as the content warrants), and the list opens beneath it, pushing the panel down. Use Select for a form field or anywhere a popup is fine; use Combobox when people type to find an option among hundreds; use RadioGroup or RadioCard when every option should stay visible. Nothing applies while arrowing through the list — only Enter, Space or a click picks — so it suits choices with a cost (a confirm, a font load, a reset); where each option should apply as focus lands on it, that is a radio group (ThemeSelector, RadioGroup).
+
+### Best practices
+
+- Do: Enable search (`search` on DisclosurePickerPanel) only for long lists — roughly a dozen options or more, i.e. once the list scrolls. A short list (a handful of presets) reads faster with no field to skip past; the panel then has no search row and no gap.
+- Do: Show the value as the thing it is: a font row renders the family in its own face, a theme row leads with a ThemePreview tile in `media`. The row is a preview of the choice, not a label for it.
+- Do: Use `size="xs"` in a property grid (a compact Density / PanelSection), where it sits on the inset panel-field fill beside ScrubField and an xs SelectTrigger. Keep `md` in a settings column or a simple panel.
+- Do: When several rows share a panel, control `open` from the parent so only one list is open at a time — two open lists push each other and the preview out of view.
+- Do: Use it for a choice with a cost — one that opens a confirm, loads something, or resets other settings. Arrow keys only move focus; onValueChange fires once, on Enter, Space or a click, and only when the pick differs from `value`.
+- Do: Give options a leading visual with `media` (a ThemePreview tile, a swatch) instead of nesting another component's list: ThemeSelector's radio list applies each theme as the arrow keys land on it, which defeats commit-on-Enter. A list the picker cannot express (a Tree) can still close the row with `useDisclosurePicker().close()`.
+- Do: Render DisclosurePickerEmpty in place of the list when a search matches nothing, not inside it — a listbox holds only options.
+- Don't: Use it in a page-register form. A form field that pushes the form down on open reads as a layout jump; that is Select's job.
+- Don't: Rebuild the row from a Collapsible with hand-copied classes. The disclosure, the well, the hover step, the xs field shell, focus return and scroll-into-view all live here; two hand copies of this row in one panel is how it came to exist.
+- Don't: Turn search on for a short list just because the other rows have it. A search field over six options is a control with nothing to do.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| DisclosurePicker | yes | Root. Owns open state, size, focus return and scroll-into-view. |
+| DisclosurePickerTrigger | yes | The row: optional `label` caption, optional `media`, the value, and a chevron that flips when open. |
+| DisclosurePickerPanel | yes | What opens beneath the row: the opt-in search field, then the list. |
+| DisclosurePickerList | no | A listbox of options that scrolls past 16rem. Arrow keys move; Enter, Space or a click picks. |
+| DisclosurePickerOption | no | One option row, with optional leading media and trailing note. Chosen, it lifts out of the well; focused, it takes the ring. |
+| DisclosurePickerEmpty | no | The no-match line, rendered in place of the list when a search filters everything out. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| DisclosurePickerTrigger | { label?: ReactNode; media?: ReactNode; children?: ReactNode } + Base UI Collapsible.Trigger props | The row. `label` is a muted leading caption on a fixed column so stacked rows align; `media` a leading visual (a ThemePreview tile); children the value, truncated on one line. ArrowDown opens it, and steps into the list once open. |
+| DisclosurePickerPanel | { search?: { value: string; onValueChange(value: string): void; placeholder?: string; label?: string } } + Collapsible.Panel props | Opens beneath the row. `search` opts in to a SearchInput above the list (off by default); it is controlled because the consumer filters, and it is cleared when the row closes. Escape clears a query first, then closes; ArrowDown in the field steps into the list. |
+| DisclosurePickerList | { value: string; onValueChange(value: string): void; aria-label?: string } + div props | A listbox. ArrowUp/ArrowDown, Home/End and type-ahead move focus without applying anything (ArrowUp from the first option returns to the search field); Enter, Space or a click picks the focused option — onValueChange fires once, only when it differs from `value` — and closes the row. Escape closes without a pick. |
+| DisclosurePickerOption | { value: string; children?: ReactNode; media?: ReactNode; note?: ReactNode; disabled?: boolean; textValue?: string } | One option row. `media` is a leading visual (a ThemePreview tile); `note` a muted trailing annotation — options without one show a check when chosen. `disabled` skips it for the keyboard and refuses the pick; `textValue` is what type-ahead matches when the name is not plain text. |
+| DisclosurePickerEmpty | { children?: ReactNode } | The no-match line, rendered in place of the list. |
+| useDisclosurePicker | () => { open: boolean; close(): void; size: "md" \| "xs" } | For a list the picker does not own (a Tree) that should close the row when something is picked. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| open | boolean | — | Controlled open state. Pair with onOpenChange. |
+| defaultOpen | boolean | false | Uncontrolled initial open state. |
+| onOpenChange | (open: boolean) => void | — | Called with the next open state — from the trigger, a pick, or Escape. |
+| size | "md" \| "xs" | "md" | md is a --control-md row (40px comfortable) in a settings column, its own well when closed. xs is the property-grid rung: a --control-xs row on the inset panel-field fill with ui-tier type. Height, padding, radius, type and surface move together. |
+| className | string | — | Merged onto the root (layout only — the look comes from size). |
+
+## Tokens used
+
+`foreground`, `muted-foreground`, `popover`, `hairline`, `panel-field`, `panel-field-hover`, `ring`, `accent`
+
+## Motion
+
+- **arrival** · root · _no motion_ — A property row is present from first paint; animating it in would stage chrome the user is already scanning.
+- **response** · DisclosurePickerTrigger · `motion-interactive` — The row reads as a value, not a button; the hover step is what says it opens before it is clicked.
+- **transition** · DisclosurePickerPanel · `motion-disclosure` — The list pushes the panel down; growing its height ties the movement below to this row rather than to a layout jump.
+- **activity** · root · _no motion_ — Nothing is indeterminate: the options are resident. A list that loads should show its own loader inside the panel.
+
+## Accessibility
+
+- The trigger is a real <button>; Base UI wires aria-expanded and aria-controls to the panel. Its accessible name is its text (caption + value) unless an aria-label is given.
+- The list is role="listbox" with role="option" rows; aria-selected marks the committed value, not the focused row, so a screen reader hears both where focus is and what is chosen. Selection does not follow focus: ArrowUp/ArrowDown, Home/End and type-ahead move focus (roving tabindex — one tab stop, so Tab leaves the list in one step) and apply nothing; Enter, Space or a click picks, applies and closes. Disabled options carry aria-disabled and are skipped.
+- Why a listbox and not a radio group: a radio group's checked state follows focus, so every arrow press would be a pick — wrong for a choice that opens a confirm, loads a font or resets settings. Base UI ships no standalone listbox (Select is popup-only, Combobox's inline list is focus-in-the-input, Composite is internal), so the keyboard model lives here.
+- Opening from the keyboard (Enter, Space, ArrowDown) moves focus into the panel: the search field when there is one, otherwise the chosen option (or the first). A pointer open focuses the search field on a fine pointer only, so touch does not raise the on-screen keyboard.
+- Escape closes the row without changing the value (clearing a query first) and returns focus to the trigger; a pick does the same. Focus is not pulled back when it has already moved on, e.g. to a confirm dialog the pick opened.
+- The panel animates with motion-disclosure, which is static under prefers-reduced-motion or MotionProvider off; the scroll that keeps the row in view is instant, never smooth.
+
+## Related
+
+- Components: Collapsible, Select, Combobox, SearchInput, RadioGroup, ThemeSelector, FontPicker, PropertyRow
+
+## Examples
+
+### A short list — no search
+
+```tsx
+import { DisclosurePicker, DisclosurePickerList, DisclosurePickerOption, DisclosurePickerPanel, DisclosurePickerTrigger } from "@sableui/react"
+
+const [preset, setPreset] = useState("comfortable")
+const [open, setOpen] = useState(false)
+<DisclosurePicker open={open} onOpenChange={setOpen} className="w-72">
+  <DisclosurePickerTrigger label="Density">{preset === "compact" ? "Compact" : "Comfortable"}</DisclosurePickerTrigger>
+  <DisclosurePickerPanel>
+    <DisclosurePickerList aria-label="Density" value={preset} onValueChange={setPreset}>
+      <DisclosurePickerOption value="comfortable">Comfortable</DisclosurePickerOption>
+      <DisclosurePickerOption value="compact">Compact</DisclosurePickerOption>
+    </DisclosurePickerList>
+  </DisclosurePickerPanel>
+</DisclosurePicker>
+```
+
+### A long list — search opted in
+
+```tsx
+import { DisclosurePicker, DisclosurePickerEmpty, DisclosurePickerList, DisclosurePickerOption, DisclosurePickerPanel, DisclosurePickerTrigger } from "@sableui/react"
+
+const COUNTRIES = ["Argentina", "Australia", "Austria", "Belgium", "Brazil", "Canada", "Chile", "Denmark", "Finland", "France", "Germany", "Ireland", "Italy", "Japan", "Mexico", "Norway", "Portugal", "Spain", "Sweden"]
+const [country, setCountry] = useState("Canada")
+const [query, setQuery] = useState("")
+const shown = COUNTRIES.filter((name) => name.toLowerCase().includes(query.trim().toLowerCase()))
+<DisclosurePicker className="w-72">
+  <DisclosurePickerTrigger label="Country">{country}</DisclosurePickerTrigger>
+  <DisclosurePickerPanel search={{ value: query, onValueChange: setQuery, placeholder: `Search ${COUNTRIES.length} countries` }}>
+    {shown.length > 0 ? (
+      <DisclosurePickerList aria-label="Country" value={country} onValueChange={setCountry}>
+        {shown.map((name) => (
+          <DisclosurePickerOption key={name} value={name}>{name}</DisclosurePickerOption>
+        ))}
+      </DisclosurePickerList>
+    ) : (
+      <DisclosurePickerEmpty>No countries match “{query}”.</DisclosurePickerEmpty>
+    )}
+  </DisclosurePickerPanel>
+</DisclosurePicker>
+```
+
+### A theme picker — media tiles, commit on Enter
+
+```tsx
+import { DisclosurePicker, DisclosurePickerList, DisclosurePickerOption, DisclosurePickerPanel, DisclosurePickerTrigger, ThemePreview, useSableTheme } from "@sableui/react"
+
+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>
+```
+
+### Property-grid rung
+
+```tsx
+import { Density, DisclosurePicker, DisclosurePickerList, DisclosurePickerOption, DisclosurePickerPanel, DisclosurePickerTrigger } from "@sableui/react"
+
+const [blend, setBlend] = useState("normal")
+<Density value="compact" className="w-64">
+  <DisclosurePicker size="xs">
+    <DisclosurePickerTrigger label="Blend">{blend}</DisclosurePickerTrigger>
+    <DisclosurePickerPanel>
+      <DisclosurePickerList aria-label="Blend mode" value={blend} onValueChange={setBlend}>
+        <DisclosurePickerOption value="normal">normal</DisclosurePickerOption>
+        <DisclosurePickerOption value="multiply">multiply</DisclosurePickerOption>
+        <DisclosurePickerOption value="screen">screen</DisclosurePickerOption>
+      </DisclosurePickerList>
+    </DisclosurePickerPanel>
+  </DisclosurePicker>
+</Density>
+```

package/llms/components/font-picker.md

@@ -0,0 +1,104 @@
+# FontPicker
+
+**Status:** stable
+
+A DisclosurePicker for a typeface: the row names the chosen family in its own face and opens in place into a searchable list of families, each drawn in itself. The app supplies the families and loads the faces; Sable bundles no catalog.
+
+**Keywords:** font picker, typeface, font family, font selector, typography, google fonts, inspector, customizer
+
+## Usage
+
+Use FontPicker wherever someone chooses a typeface for a role (body, headings, code) in a panel that shows the result: a theme editor, a document inspector, a brand customizer. It is a DisclosurePicker, so the list opens beneath the row rather than over the preview; arrow keys walk the families (each drawn in its own face) without applying or loading anything, and Enter, Space or a click picks one, loads it and closes the row.
+
+### Best practices
+
+- Do: Pass `loadFont` and load faces lazily: `"preview"` fires for every family when the list opens (load just the glyphs of its name — Google Fonts' `text=` parameter makes a 20-font list cost a few KB), `"use"` for the chosen one (load its real weights). Make it idempotent and define it once, outside render.
+- Do: Put non-font choices — "Preset (Figtree)", "Same as body" — in `options`, with a short `valueLabel` for the row. They list first and render in the app's face, so they never read as a family.
+- Do: Give each row a role `label` ("Body", "Headings", "Mono") and stack them; the caption column aligns. Control `open` from the parent so only one list is open at a time.
+- Don't: Leave search on for a short curated list — under a dozen families, pass `searchable={false}`. Search is on by default because font lists are usually long.
+- Don't: Use a Select of family names for this. A popup covers the text it changes, and a family name set in the app's face says nothing about the face.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | string | — | The chosen family, or the value of one of `options`. |
+| onValueChange | (value: string) => void | — | Called once a family (or option) is picked — Enter, Space or a click — and only when it differs from `value`; the row then closes. Arrow keys and type-ahead only move focus; Escape closes without a pick. |
+| fonts | readonly { family: string; note?: string; stack?: string }[] | — | The families to offer, in order. `note` is a muted annotation (searched too); `stack` the CSS font-family to draw it in (default `"<family>"`). |
+| options | readonly { value: string; label: string; valueLabel?: string }[] | [] | Non-font choices listed above the fonts, in the app's face. `valueLabel` is what the row shows while it is chosen. |
+| label | ReactNode | — | The row's leading caption — the role the font plays. |
+| listLabel | string | "Font" | Accessible name of the list. |
+| searchable | boolean | true | A search field above the list, filtering by family and note. Pass false for a short curated list (under a dozen). |
+| searchLabel | string | "Search fonts" | Accessible name of the search field. |
+| loadFont | (font, purpose: "preview" \| "use") => void | — | Loads a face on demand: "preview" for every family when the list opens, "use" for the chosen one once it is picked (never while the list is only being walked). Receives your own font objects. Idempotent. |
+| open | boolean | — | Controlled open state, as DisclosurePicker. Control it to keep one of several rows open at a time. |
+| defaultOpen | boolean | false | Uncontrolled initial open state. |
+| onOpenChange | (open: boolean) => void | — | Called with the next open state. |
+| size | "md" \| "xs" | "md" | md for a settings column; xs for the property-grid rung (see DisclosurePicker). |
+
+## Tokens used
+
+`foreground`, `muted-foreground`, `popover`, `hairline`, `panel-field`, `ring`
+
+## Motion
+
+- **arrival** · root · _no motion_ — A property row is present from first paint.
+- **response** · Trigger · `motion-interactive` — Inherited from DisclosurePicker: the hover step says the value row opens.
+- **transition** · Panel · `motion-disclosure` — Inherited from DisclosurePicker: the list grows in place, tying the panel's movement to this row.
+- **activity** · root · _no motion_ — Faces load in the background and swap in when ready; the names are legible in the fallback meanwhile, so there is nothing to wait on.
+
+## Accessibility
+
+- Inherits DisclosurePicker: a button trigger with aria-expanded/controls whose name is the caption plus the family; a listbox named by `listLabel`, aria-selected on the chosen family.
+- Keyboard open focuses the search field; ArrowDown steps from it into the list (ArrowUp from the first option steps back); arrows, Home/End and type-ahead move without applying; Enter or Space picks and closes; Escape clears the query, then closes without a pick and returns focus to the row.
+- Each family is set in its own face, but its name is still plain text, so a screen reader reads the name, not the glyphs.
+
+## Related
+
+- Components: DisclosurePicker, ThemeSelector, Select, Combobox
+
+## Examples
+
+### Body font with lazy loading
+
+```tsx
+import { FontPicker } from "@sableui/react"
+
+const FONTS = [
+  { family: "Inter", note: "Neutral, dense UI" },
+  { family: "Figtree", note: "Friendly geometric" },
+  { family: "Fraunces", note: "Soft, wonky serif", stack: '"Fraunces", serif' },
+]
+// Your loader; Sable never fetches fonts itself.
+const loadFont = (font: { family: string }, purpose: "preview" | "use") => {
+  const id = `font-${purpose}-${font.family}`
+  if (document.getElementById(id)) return
+  const link = Object.assign(document.createElement("link"), { id, rel: "stylesheet" })
+  const family = font.family.replace(/ /g, "+")
+  link.href = purpose === "preview"
+    ? `https://fonts.googleapis.com/css2?family=${family}&text=${encodeURIComponent(font.family)}`
+    : `https://fonts.googleapis.com/css2?family=${family}:wght@400..700&display=swap`
+  document.head.appendChild(link)
+}
+const [family, setFamily] = useState("Inter")
+<FontPicker label="Body" listLabel="Body font" value={family} onValueChange={setFamily} fonts={FONTS} loadFont={loadFont} searchable={false} />
+```
+
+### With a preset option, one row of several
+
+```tsx
+import { FontPicker } from "@sableui/react"
+
+const [open, setOpen] = useState<string | null>(null)
+const [body, setBody] = useState("theme")
+<FontPicker
+  label="Body"
+  listLabel="Body font"
+  value={body}
+  onValueChange={setBody}
+  options={[{ value: "theme", label: "Preset (Figtree)", valueLabel: "Figtree" }]}
+  fonts={[{ family: "Inter" }, { family: "Figtree" }, { family: "Geist" }]}
+  open={open === "body"}
+  onOpenChange={(next) => setOpen(next ? "body" : null)}
+/>
+```

package/llms/components/media-image.md

@@ -0,0 +1,98 @@
+# MediaImage
+
+**Status:** beta
+
+An image that fills its box and falls back to GradientArt seeded by the item when it has no source or the source fails — Avatar's image-load tracking, for covers, thumbnails and product shots instead of faces.
+
+**Keywords:** image, img, image fallback, broken image, cover art, album art, thumbnail, placeholder image, onError, missing image
+
+## Usage
+
+Use MediaImage wherever content imagery may be missing or broken: a cover in a grid, a thumbnail in a row, a product shot. It fills the box it is given — an AspectBox for a cover, a sized and rounded box for a thumbnail — shows a quiet muted surface while the image loads, fades the image in once decoded, and paints GradientArt seeded by the item when there is no image to show, so a grid of missing covers still reads as distinct things. For a person use Avatar; for a whole tile with title and actions use MediaTile, which composes this.
+
+### Best practices
+
+- 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.
+- 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.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| src | string | — | Image URL. Omitted, empty or failing to load ⇒ the fallback shows. |
+| alt | string | "" | Alt text. Empty is decorative — right beside a visible title. When set and no image shows, it names the fallback instead. |
+| 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). |
+| 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. |
+| className | string | — | Sizing and rounding when MediaImage is the box itself (`size-14 rounded-md`). Inside an AspectBox it already fills. |
+
+## Variants
+
+- **fit**: cover, contain
+
+## Tokens used
+
+`muted`, `art-1`, `art-2`, `art-3`, `art-4`, `art-5`, `art-6`, `art-ground`
+
+## Motion
+
+- **arrival** · image · `motion-fade` — The image fades in over the muted surface once it has decoded, so a slow cover settles in instead of popping row by row as the grid loads.
+- **response** · root · _no motion_ — Imagery, not a control. The tile or row around it answers the pointer.
+- **transition** · root · _no motion_ — Its only state change is loading → loaded or failed, which the arrival covers.
+- **activity** · root · _no motion_ — A loading image rests on a static muted surface; a shimmer per cover across a long grid would be noise.
+
+## Accessibility
+
+- `alt` defaults to empty (decorative), because the usual neighbour is a visible title that already names the item; describe the image when it stands alone.
+- When no image is on screen and `alt` is set, the frame takes `role="img"` with that label, so a broken URL does not erase the description. The fallback art itself is always aria-hidden.
+- The `<img>` mounts only once it has loaded, so assistive technology never meets a broken-image icon.
+
+## Related
+
+- Components: MediaTile, Avatar, GradientArt, AspectBox
+
+## Examples
+
+### Cover with fallback
+
+```tsx
+import { AspectBox, MediaImage } from "@sableui/react"
+
+<AspectBox ratio={1} className="rounded-md">
+	<MediaImage src={album.cover} seed={album.title} />
+</AspectBox>
+```
+
+### No image yet
+
+```tsx
+import { AspectBox, MediaImage } from "@sableui/react"
+
+<AspectBox ratio={1} className="rounded-md">
+	<MediaImage seed="Low tide, high noon" />
+</AspectBox>
+```
+
+### Row thumbnail
+
+```tsx
+import { MediaImage } from "@sableui/react"
+
+<MediaImage src={track.art} seed={track.title} className="size-12 shrink-0 rounded-sm" />
+```
+
+### Logo, never cropped
+
+```tsx
+import { AspectBox, MediaImage } from "@sableui/react"
+
+<AspectBox ratio={16 / 9} className="rounded-lg">
+	<MediaImage src={brand.logo} alt={brand.name} fit="contain" />
+</AspectBox>
+```

package/llms/components/media-tile.md

@@ -0,0 +1,143 @@
+# MediaTile
+
+**Status:** beta
+
+A cover-first tile — square, 16:9 or poster artwork with an optional play-style action over it, then a title and a subtitle that can each be links — that is one link as a whole without nesting its other controls inside one.
+
+**Keywords:** album, album art, cover, tile, media card, video thumbnail, podcast, playlist, gallery, product tile, poster, grid item, play button, music
+
+## Usage
+
+The item in a media grid or shelf: an album, a playlist, a video, a podcast, a film, a photo, a product. The cover leads and carries the weight; the title and subtitle sit underneath without a card around them. The whole tile follows the title's link, the subtitle can link somewhere else (the artist, the channel), and an action — usually play — floats over the cover's corner, revealed on hover and focus and always shown on touch. A missing or broken cover becomes GradientArt seeded by the title, so a grid of items without artwork still reads as distinct things.
+
+### Best practices
+
+- Do: Lay tiles out with `Grid` (`<Grid minItemWidth="10rem">`) or a horizontal `Scroller` for a shelf. The tile fills its cell; the grid decides the width.
+- Do: Pass `render={<Link to="…" />}` (or `href`) for where the tile goes, and `subtitleRender` / `subtitleHref` for a second destination. Each stays a separate control; never wrap the tile in your own link.
+- Do: Name the action for its item — `aria-label="Play Low tide, high noon"`, not "Play". A grid of twenty identical "Play" buttons is unusable from a screen reader's list of controls.
+- Do: Use `titleAs="h3"` when the tiles sit under a section heading, so screen-reader users can move tile to tile by heading.
+- Don't: Do not build this from `Card render={<Link />}`. A card that is a link cannot hold a second link or a button — interactive content cannot nest — which is exactly what a media tile needs.
+- Don't: Do not put more than one action on the cover. A second control over the art is a toolbar on a thumbnail; move secondary actions (add to queue, share) into an OverflowMenu in the action slot or onto the item's page.
+- Don't: Do not use it for a framed commerce card with a price and a buy button — that is ProductCardBlock — or for a person, which is an Avatar.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Cover | yes | An AspectBox holding MediaImage: the image, or GradientArt seeded by the title. Drawn first, read last. |
+| Title | yes | The item's name. When the tile links, this is the link, stretched over the whole tile. |
+| Subtitle | no | The second line. Optionally its own link, raised above the stretched one. |
+| Action | no | One control over the cover's bottom-end corner — usually play. Revealed on hover and focus; always visible on touch. |
+| Badge | no | A static label over the cover's top-start corner — a duration, "New". Click-through. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| title | ReactNode | — | The item's name. Seeds the fallback art when it is a string. |
+| subtitle | ReactNode | — | The second line — an artist, a channel, a year. |
+| src | string | — | Cover image URL. Without one, or when it fails, the cover is GradientArt seeded by the item. |
+| 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. |
+| 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. |
+| render | useRender.RenderProp | — | The title link's element, for a router: `render={<Link to="/albums/1" />}`. Takes precedence over `href`. |
+| subtitleHref | string | — | Makes the subtitle its own link — a separate tab stop above the tile's. |
+| subtitleRender | useRender.RenderProp | — | The subtitle link's element, for a router. |
+| action | ReactNode | — | One control over the cover's bottom-end corner, usually a play Button. Hidden until hover or focus on hover-capable devices; always shown on touch. |
+| badge | ReactNode | — | A static label on the cover's top-start corner — `<Badge appearance="overlay">`. |
+| titleAs | "h2" \| "h3" \| "h4" \| "h5" \| "p" | "p" | The title's element. A heading one level below the section's lets screen-reader users move tile to tile. |
+| loading | "lazy" \| "eager" | "lazy" | Native image loading. `eager` for the first row above the fold. |
+| ...div props | Omit<ComponentPropsWithRef<"div">, "title"> | — | Spread onto the root. |
+
+## Variants
+
+- **size**: sm, md, lg
+- **aspect**: square, video, poster
+
+## Tokens used
+
+`foreground`, `muted-foreground`, `muted`, `overlay`, `ring`
+
+## Motion
+
+- **arrival** · Cover · `motion-fade` — The cover image fades in over a quiet surface once it decodes, so a grid loading on a slow connection settles tile by tile instead of popping.
+- **response** · Cover · `motion-interactive` — Hovering the tile deepens the cover with a light scrim and lifts the action in (`reveal-on-hover`), so it is clear the whole tile is one target and where its action is.
+- **transition** · root · _no motion_ — A tile has no states of its own to move between; the action carries any (play / pause).
+- **activity** · root · _no motion_ — Nothing runs inside a tile; a now-playing indicator belongs to the player, not the grid.
+
+## Accessibility
+
+- No nested interactive content: the title is the tile's link, and its `stretched-link` overlay covers the tile, while the subtitle link and the action sit above it as separate controls.
+- Tab order is title → subtitle → action. The text comes first in the DOM and the cover is drawn above it with CSS `order`, so focus follows how a reader names the item.
+- Focusing the title link rings the whole tile, rounded like the cover, because the whole tile is what the link is; the subtitle link and the action ring themselves.
+- The action is hidden with opacity only, and only where the device can hover; it stays in the tab order and the accessibility tree, appears when anything in the tile has focus, and is always visible on touch.
+- The cover is decorative by default (`alt=""`), since the title names the item; the fallback art is aria-hidden.
+- Truncated titles keep their full text in the link's accessible name and in a `title` tooltip.
+
+## Related
+
+- Components: MediaImage, GradientArt, Grid, AspectBox, Card, Scroller
+
+## Examples
+
+### Album grid
+
+```tsx
+import { Button, Grid, Icon, MediaTile } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+<Grid minItemWidth="10rem" gap={3}>
+	{albums.map((album) => (
+		<MediaTile
+			key={album.id}
+			title={album.title}
+			subtitle={album.artist}
+			src={album.cover}
+			render={<Link to={`/albums/${album.id}`} />}
+			subtitleRender={<Link to={`/artists/${album.artistId}`} />}
+			action={
+				<Button size="icon" aria-label={`Play ${album.title}`} onClick={() => play(album)}>
+					<Icon name="play" variant="solid" />
+				</Button>
+			}
+		/>
+	))}
+</Grid>
+```
+
+### Video tile with a duration
+
+```tsx
+import { Badge, MediaTile } from "@sableui/react"
+
+<MediaTile
+	aspect="video"
+	title="Building a synth from scratch"
+	subtitle="Undertow Sessions · 2 days ago"
+	src={video.thumbnail}
+	href={`/watch/${video.id}`}
+	badge={<Badge appearance="overlay">12:04</Badge>}
+/>
+```
+
+### Gallery, no links
+
+```tsx
+import { Grid, MediaTile } from "@sableui/react"
+
+<Grid minItemWidth="8rem" gap={2}>
+	{photos.map((photo) => (
+		<MediaTile key={photo.id} size="sm" title={photo.caption} src={photo.url} alt={photo.description} />
+	))}
+</Grid>
+```
+
+### Poster shelf
+
+```tsx
+import { MediaTile } from "@sableui/react"
+
+<MediaTile aspect="poster" size="lg" titleAs="h3" title="The Long Dark" subtitle="2026 · Drama" href="/films/the-long-dark" />
+```

package/llms/components/page-header.md

@@ -15,6 +15,7 @@ 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.
 - 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.
 
 ## Props
@@ -23,8 +24,8 @@ Use PageHeader to establish a page's title, supporting description, and primary
 | --- | --- | --- | --- |
 | title | ReactNode | — | The page title (renders an <h1>). |
 | description | ReactNode | — | Supporting copy beneath the title. |
-| 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. |
-| actions | ReactNode | — | Trailing actions aligned to the title row's end. They drop under the title when the row runs out of room, and the title wraps rather than truncating. |
+| 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 row runs out of room, 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. |
 
 ## Tokens used
@@ -38,7 +39,7 @@ Use PageHeader to establish a page's title, supporting description, and primary
 
 ## Related
 
-- Components: AppHeader, Breadcrumbs, Button
+- Components: AppHeader, SectionHeader, Breadcrumbs, Button
 
 ## Examples
 
@@ -69,8 +70,8 @@ import { Button, PageHeader, Region } from "@sableui/react"
 
 // ✗ Outside the Region. The header then sits at a different measure from the
 //   content it introduces, and the page reads as two documents.
-// ✗ Two on one page. A second one is a section heading — an h2 in a
-//   smaller step (text-heading-3 or below), not another PageHeader.
+// ✗ Two on one page. A second one is a section heading: a SectionHeader
+//   (an h2 on text-heading-3, same title row and actions), not another PageHeader.
 // ✗ Global actions in it (account, search). Those persist across routes and
 //   belong in AppHeader.
 ```

package/llms/components/pie-chart.md

@@ -28,7 +28,7 @@ Use PieChart for a share of one total across two to six categories — traffic s
 | categories | Record<string, { label?: string; tone?: ChartTone; color?: string; icon?: string }> | — | Labels, tones and icons per slice, keyed by the slice's name. Unlisted slices take the tones in order. |
 | className | string | "h-64" | Sizes the chart. Set a height. |
 | donut | boolean \| number | false | Cut out the middle: `true` for a ring at 60% of the radius, or a ratio (0–0.9). |
-| centerLabel | { value: string; label?: string } | — | A value and caption in the hole of a donut. |
+| centerLabel | { value: string \| number; label?: string } | — | A value and caption in the hole of a donut. The value holds the centre and the caption hangs below it. A number is formatted for you: in full up to 9,999, compact from 10,000 (10.2K, 102.1K, 1.2M); pass a string for units. |
 | separator | boolean | true | A hairline in the surface colour between slices. |
 | labels | "none" \| "outside" \| "inside" | "none" | Label each slice outside the pie or inside it. |
 | labelContent | "value" \| "percent" \| "name" | "value" | What a slice label says. |
@@ -82,7 +82,7 @@ const sources = [
 	index="source"
 	valueKey="visitors"
 	donut
-	centerLabel={{ value: "752", label: "Visitors" }}
+	centerLabel={{ value: 752, label: "Visitors" }}
 />
 ```
 

package/llms/components/radial-chart.md

@@ -32,7 +32,7 @@ Use RadialChart for progress toward goals (several rings), a single score or usa
 | stacked | boolean | false | Split ONE ring between the rows instead of a ring each. |
 | track | boolean | true | Draw each ring's full track behind it. |
 | labels | boolean | false | Name each ring at its start. |
-| centerLabel | { value: string; label?: string } | — | A value and caption in the middle. |
+| centerLabel | { value: string \| number; label?: string } | — | A value and caption in the middle. On a full ring the value holds the centre and the caption hangs below it. A number is formatted for you: in full up to 9,999, compact from 10,000 (10.2K); pass a string for units ("7.2 GB", "72%"). |
 | legend | boolean | true unless rings are labelled | Show the legend. |
 | tooltip | boolean \| { indicator?: "dot" \| "line" \| "dashed" \| "none"; hideLabel?: boolean; labelFormatter?: (label, datum) => ReactNode; showTotal?: boolean } | true | Show a tooltip on hover and keyboard focus, or configure it: the row marker, hiding the heading, rewriting it, adding a Total row. |
 | valueFormatter | (value: number) => string | — | Format values everywhere (axis, labels, tooltip, table) — units like "$12,480". Default: compact on the axis, full elsewhere. |