@sableui/react 0.10.0 → 0.12.0

package/llms/components/pagination.md

@@ -2,9 +2,9 @@
 
 **Status:** stable
 
-Page navigation built from our own Button + Icon (no Base UI). A <nav aria-label='Pagination'> with prev/next icon buttons that disable at the bounds and numbered page buttons; the current page is a secondary button marked aria-current. Collapses to first/last/current plus a sibling window, bridging skipped runs with an ellipsis.
+Page navigation built from our own Button + Icon (no Base UI). A <nav aria-label='Pagination'> with prev/next icon buttons that disable at the bounds and numbered page buttons; the current page is a secondary button marked aria-current. With pageLink every control is a real link (crawlable, opens in a new tab, any router through render). Collapses to first/last/current plus a sibling window, bridging skipped runs with an ellipsis.
 
-**Keywords:** pagination, pager, pages, table, results, navigation, next, previous
+**Keywords:** pagination, pager, pages, table, results, navigation, next, previous, page links, seo, url
 
 ## Usage
 
@@ -14,6 +14,7 @@ Use Pagination when a result set is split into discrete pages and the user needs
 
 - Do: Keep page state controlled by the parent route or data layer so URL, filters, and result fetches stay in sync.
 - Do: Use a specific label when multiple pagers appear on a page, such as "Customer pages".
+- Do: Pass pageLink when the page lives in the URL (search results, a blog, a catalogue): each page becomes a link a crawler can follow and a reader can open in a new tab. Use a router's Link there so navigation stays in the app.
 - Do: Reset to page 1 when filters or search terms materially change the result set.
 - Don't: Use Pagination for tiny lists where all items fit comfortably on one page.
 - Don't: Hide disabled previous/next buttons at the bounds; disabled controls make the current position clearer.
@@ -33,7 +34,8 @@ Use Pagination when a result set is split into discrete pages and the user needs
 | --- | --- | --- | --- |
 | page | number | — | The active page (1-based). Clamped into the valid range. |
 | total | number | — | Total number of pages. |
-| onPageChange | (page: number) => void | — | Called with the next page when a control is activated. No-op for out-of-range or unchanged values. |
+| onPageChange | (page: number) => void | — | Called with the next page when a control is activated. No-op for out-of-range or unchanged values. Optional with pageLink, where the URL is the page state. |
+| pageLink | (page: number) => ReactElement | — | Render each page control as a link: return the element for a page, (page) => <a href={`?page=${page}`} /> or a router's <Link to={`?page=${page}`} />. The current page keeps aria-current; previous/next at the bounds stay disabled buttons. onPageChange becomes optional and, if set, still fires on click. |
 | siblingCount | number | 1 | Page buttons shown on each side of the current page before the list collapses into ellipses. First and last pages are always shown. |
 | label | string | Pagination | Accessible label applied to the surrounding nav element. |
 | className | string | — | Extra classes merged onto the nav. |
@@ -47,6 +49,7 @@ Use Pagination when a result set is split into discrete pages and the user needs
 - Renders a landmark <nav> with aria-label so assistive tech can jump to the pager.
 - The current page button carries aria-current='page'.
 - Prev/next buttons are real <button>s with aria-label and become disabled at the bounds.
+- With pageLink the controls are real <a> links (or the router's), so they are crawlable and open in a new tab; a bound arrow stays a disabled button rather than a link to nowhere.
 - Ellipsis slots are aria-hidden — they convey no navigable target.
 
 ## Related
@@ -82,6 +85,15 @@ import { DataTable, Pagination, Stack } from "@sableui/react"
 <Stack gap={2}><DataTable data={rows} columns={columns} rowKey={(row) => row.id} /><Pagination label="Customer pages" page={page} total={12} onPageChange={setPage} /></Stack>
 ```
 
+### Page links (URL is the state)
+
+```tsx
+import { Pagination } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+<Pagination page={page} total={pageCount} pageLink={(page) => <Link to={`/search?q=${query}&page=${page}`} />} />
+```
+
 ### Server query state
 
 ```tsx

package/llms/components/panel-section.md

@@ -27,6 +27,7 @@ Use PanelSection to group properties inside an inspector or docked panel, with P
 | Header | yes | The section title in the UI section tier, with an optional trailing action. |
 | PropertyRow | no | One property: label left, control right. `stacked` moves the control to its own line for full-width controls. |
 | PropertyPair | no | Two controls side by side, with optional captions above each. |
+| PropertyGroup | no | A set of properties folded behind one row that names the group and summarises its value, opening with +/− to the controls beneath. |
 
 ## Subcomponents
 
@@ -34,6 +35,7 @@ Use PanelSection to group properties inside an inspector or docked panel, with P
 | --- | --- | --- |
 | PropertyRow | { label: ReactNode; htmlFor?: string; hint?: string; stacked?: boolean; scrub?: { value, onValueChange, step?, min?, max?, onGestureStart?, onGestureEnd?, disabled? } } | One property line. `hint` becomes the label's hover explanation; `stacked` puts the control on its own line. `scrub` makes the property NAME a drag handle for its value — the Figma/Framer/Paper convention, and the answer for a numeric row with no honest glyph to put in a ScrubField (a schema-generated `levels` or `seed`, where a `#` would be noise pretending to be meaning). Opt-in and additive: a row without it is unchanged. The label stays a real `<label htmlFor>` — a 2px jitter threshold keeps a click a click, and the click synthesised after a real drag is swallowed so a scrub does not also select the field's text. |
 | PropertyPair | { labels?: [ReactNode, ReactNode] } | Two controls side by side in a 2-up grid, with optional captions above each. |
+| PropertyGroup | { label: ReactNode; summary?: ReactNode; defaultOpen?: boolean; open?: boolean; onOpenChange?: (open: boolean) => void } | A collapsible set of properties inside a section, at the panel's scale (an Accordion is page furniture). The row shows the label, then the summary (the group's value, readable while closed: a word, a few swatches, or both), then a + that turns to − when open. Groups open independently and stack with a hairline between them. Built on Collapsible. |
 
 ## Props
 
@@ -48,6 +50,7 @@ Use PanelSection to group properties inside an inspector or docked panel, with P
 
 ## Accessibility
 
+- PropertyGroup's row is a real button with aria-expanded (Collapsible); its summary is part of the button's name, so a closed group still announces its value.
 - PropertyRow renders a real <label>; pass htmlFor with the control's id so clicking the label focuses it.
 - The section title is an h3, so panels contribute a real heading outline rather than styled divs.
 - `hint` is exposed as the label's title attribute — keep the essential meaning in the label itself, since title text is not reliably announced.
@@ -59,6 +62,31 @@ Use PanelSection to group properties inside an inspector or docked panel, with P
 
 ## Examples
 
+### Groups that fold behind their value
+
+```tsx
+import { PanelSection, PropertyGroup, PropertyRow, ScrubField, Select, SelectContent, SelectItem, SelectTrigger } from "@sableui/react"
+
+<PanelSection title="Color">
+  <PropertyGroup label="Tones" summary="Brand only">
+    <PropertyRow label="Scheme">
+      <Select value="brand">
+        <SelectTrigger size="xs" />
+        <SelectContent>
+          <SelectItem value="brand">Brand only</SelectItem>
+          <SelectItem value="harmonize">Harmonize</SelectItem>
+        </SelectContent>
+      </Select>
+    </PropertyRow>
+  </PropertyGroup>
+  <PropertyGroup label="Grid" summary="8px">
+    <PropertyRow label="Size">
+      <ScrubField label="Grid size" value={8} min={1} max={64} suffix="px" />
+    </PropertyRow>
+  </PropertyGroup>
+</PanelSection>
+```
+
 ### Blending section, 2-up
 
 ```tsx

package/llms/components/scroller.md

@@ -27,6 +27,7 @@ Use Scroller to create a contained overflow region for content that naturally ex
 | --- | --- | --- | --- |
 | orientation | "vertical" \| "horizontal" | "vertical" | "vertical" scrolls and fades top/bottom; "horizontal" scrolls and fades left/right. |
 | wheelScroll | boolean | true | On a horizontal Scroller, let a vertical mouse wheel scroll it sideways. Ignored when vertical. Turn it off only if the region is inside something that owns the wheel itself (a map, a canvas). |
+| smoothWheel | boolean | true | Ease mouse-wheel steps toward their target, on either axis: the inertia a smooth-scroll library such as Lenis adds, scoped to this region. Only a mouse wheel is eased; trackpads and touch keep their own momentum, keys and scrollbar drags stay native, and reduced motion (the OS preference or MotionProvider) turns it off. Anything else that moves the region (scrollIntoView, a stick-to-bottom chat) stops the easing at once. For a scroll container of your own, `useSmoothWheel()` returns the same behaviour as a ref callback. |
 | label | string | — | Accessible name for the scroll region. The region takes focus, so it should say what it contains; without one a screen reader announces an unnamed group. |
 | viewportClassName | string | — | Classes for the inner element that actually scrolls. Narrow on purpose — `className` is what you want almost always. This is for the few utilities that only mean something on the scrolling box: `snap-x`, `scroll-smooth`, `scroll-p-*`. |
 | ...div props | ComponentPropsWithRef<'div'> | — | Everything except `className`/`style` spreads onto the SCROLLING element — `role`, `id`, `aria-*`, `data-*` and event handlers all describe the thing that scrolls, and CommandMenu relies on it to make this component its listbox. `ref` and `onScroll` likewise address the scroller, and compose with the component's own. |

package/llms/components/sheet.md

@@ -4,7 +4,7 @@
 
 Edge-anchored drawer over Base UI Drawer — focus trap, scroll lock, Esc/outside dismissal, portal backdrop, plus swipe-to-dismiss on touch. Slides in from a viewport edge via side and swipes back out toward the same edge.
 
-**Keywords:** sheet, drawer, side panel, overlay, swipe to dismiss
+**Keywords:** sheet, drawer, side panel, overlay, swipe to dismiss, bottom sheet, snap points, detents
 
 ## Usage
 
@@ -14,6 +14,7 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 
 - Do: Use it for inspect, edit, filter, or create flows that relate to the current page.
 - Do: Include clear title, close path, and footer actions for task-oriented sheets.
+- Do: Give a bottom sheet snap points when it shows a summary first and detail on demand (a map result, a now-playing panel): `snapPoints={[0.4, 1]}`. The first stop is where it opens; put what matters at that height, because the rest is a drag away.
 - Don't: Do not use Sheet for simple confirmations or deeply nested workflows.
 - Don't: Do not use it on desktop where a Dialog fits. A sheet's affordance is edge-anchored travel for thumb reach; on a wide viewport it becomes a dialog that arrives from the wrong place.
 
@@ -34,7 +35,7 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 
 | Name | Type | Description |
 | --- | --- | --- |
-| SheetContent | Base UI Drawer.Popup props (initialFocus, finalFocus, …) + side: "right" \| "left" \| "top" \| "bottom" + className | Backdrop + edge-anchored popup; portals to <body>. side picks which viewport edge the sheet anchors to and slides in from (defaults to "right"). Left/right are full-height side panels; top/bottom span the width up to 80vh. On touch it swipes closed toward that same edge (right swipes right, left swipes left, top swipes up, bottom swipes down). |
+| SheetContent | Base UI Drawer.Popup props (initialFocus, finalFocus, …) + side: "right" \| "left" \| "top" \| "bottom" + className | Backdrop + edge-anchored popup; portals to <body>. side picks which viewport edge the sheet anchors to and slides in from (defaults to "right"). Left/right are full-height side panels; top/bottom span the width up to 80vh. A bottom sheet with snapPoints is as tall as its highest stop allows (the viewport less a top gap), shows a drag handle, and translates down to the active stop; the part below the screen becomes bottom padding, so its scroll area and SheetFooter end at the visible edge. A bottom sheet rides above the on-screen keyboard (measured from visualViewport). On touch it swipes closed toward that same edge (right swipes right, left swipes left, top swipes up, bottom swipes down). |
 | SheetTrigger | Base UI Drawer.Trigger props (render) | Element that opens the sheet. Compose via render prop. |
 | SheetClose | Base UI Drawer.Close props (render) | Element that dismisses the sheet. Compose via render prop. |
 | SheetHeader | ComponentProps<"div"> | Top section holding SheetTitle/SheetDescription. |
@@ -47,7 +48,11 @@ 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) — minus swipeDirection and snap points | — | 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. |
+| 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. |
+| snapToSequentialPoints | boolean | false | Move one stop per swipe, by distance. Off, a fast flick can skip past a stop. |
 
 ## Variants
 
@@ -67,6 +72,8 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 - 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.
+- Snap points add stops, not a gate: at any stop the content scrolls within the visible part and every control stays reachable by keyboard, so nothing needs the drag. The handle is decorative (aria-hidden).
+- A bottom sheet stays above the on-screen keyboard: its bottom edge is lifted by the height the keyboard takes from the visual viewport, so a focused field is not covered. An app that sets interactive-widget=resizes-content in its viewport meta gets the same result from the browser, and the inset reads 0.
 
 ## Related
 
@@ -98,6 +105,14 @@ import { Button, Sheet, SheetClose, SheetContent, SheetFooter, SheetHeader, Shee
 <Sheet><SheetTrigger render={<Button variant="secondary">Menu</Button>} /><SheetContent side="left"><SheetHeader><SheetTitle>Navigation</SheetTitle></SheetHeader><SheetFooter><SheetClose render={<Button variant="secondary">Close</Button>} /></SheetFooter></SheetContent></Sheet>
 ```
 
+### Bottom sheet with snap points
+
+```tsx
+import { Button, Entity, Sheet, SheetContent, SheetDescription, SheetHeader, SheetList, SheetTitle, SheetTrigger } from "@sableui/react"
+
+<Sheet snapPoints={[0.4, 1]}><SheetTrigger render={<Button variant="secondary">Nearby</Button>} /><SheetContent side="bottom"><SheetHeader><SheetTitle>12 places nearby</SheetTitle><SheetDescription>Drag up for the full list.</SheetDescription></SheetHeader><SheetList>{places.map((place) => <Entity key={place.id} title={place.name} subtitle={place.distance} />)}</SheetList></SheetContent></Sheet>
+```
+
 ### Bottom side
 
 ```tsx

package/llms/components/sidebar.md

@@ -14,6 +14,7 @@ Use Sidebar for persistent desktop navigation or application chrome outside the
 
 - Do: Use it for stable app destinations that should remain visible while content changes.
 - Do: Keep item labels predictable and active state obvious.
+- Do: Set surface="page" when a full-width top bar sits above the rail. A theme's tinted or dark rail is for a full-height rail that frames the app.
 - Don't: Do not use Sidebar for page-local settings, filters, or temporary action groups.
 - Don't: Do not put page content in it. It is fixed-width chrome OUTSIDE the content grid, so anything in it is exempt from the page's measure and rhythm.
 
@@ -39,6 +40,7 @@ Use Sidebar for persistent desktop navigation or application chrome outside the
 | collapsed | boolean | false | Collapse the rail to an icon-only width (--sidebar-width-collapsed). Items hide their label + badge and reveal the label in a hover tooltip; the content area reflows. Controlled — wire a toggle from app state. Read the state in custom header/footer content via useSidebar(). |
 | icons | boolean | true | Render the leading icon on each SidebarItem. Set false for a text-only rail. Ignored while collapsed (icon-only by definition). |
 | variant | "app" \| "inline" | "app" | Where the rail lives. "app" is the page's chrome column — sticky, full viewport height, hidden below lg where AppHeader + BottomNav take over. "inline" is always visible and fills its parent's height, for a rail inside a bounded frame (a nested shell, an embedded preview). Use it instead of overriding the layout with !important classes. |
+| surface | "rail" \| "page" | "rail" | Which surface the rail is painted on. "rail" is its own --sidebar-* surface with a border — right for a full-height rail that frames the app, which a theme may tint or paint dark. "page" uses the page's surface and ink with no border — use it when a full-width header sits above the rail, where a tinted column starting under a page-coloured bar reads as pasted on. Use it instead of overriding bg-/text- classes, which the rail's re-pointed tokens defeat. |
 
 ## Variants
 

package/llms/components/streaming-text.md

@@ -12,6 +12,7 @@ Use StreamingText for text whose final length is unknown while it renders — a
 
 ### Best practices
 
+- Do: In a chat, read `sable docs building-a-chat`: one status drives `streaming` and the composer, a regenerated answer takes a new key (the text is append-only), and the finished turn is announced once.
 - Do: Grow `text` and let the component do the rest. It assumes an append-only string and keys units by index, so React mounts only the new spans — re-rendering a longer string animates what was added and leaves what the reader has already read alone.
 - Do: Drop `streaming` to false the moment the source closes. That is what removes the caret and the softened tail, and their disappearance is the only signal the reader gets that the answer is complete.
 - Do: Turn `caret` off when something adjacent already reports the wait — a spinner in the message header, a status row beneath. Two indicators for one wait read as two things happening.
@@ -74,7 +75,7 @@ import { StreamingText } from "@sableui/react"
 ```tsx
 import { Message, StreamingText } from "@sableui/react"
 
-<Message role="assistant"><StreamingText text={answer} streaming={pending} caret={false} /></Message>
+<Message align="start"><StreamingText text={answer} streaming={pending} caret={false} /></Message>
 ```
 
 ### A headline resolving character by character

package/llms/patterns/chat-panel.md

@@ -6,6 +6,7 @@ A full-height conversation surface: titled header, scrolling transcript, and a c
 
 ## Notes
 
+- This is the assembled screen with sample data. To wire it to a real streaming source (a hook such as useChat, or your own transport), read `sable docs building-a-chat`: who owns what, the turn lifecycle mapped to props, and every failure state.
 - The panel is a fixed-height column, not a growing page. `h-[calc(100dvh_-_--spacing(12))]` on the Card (the viewport minus the Page's py-6, in spacing units so density moves both together — a fixed `3rem` drifts the moment density moves the padding) and `flex-1 min-h-0` on the MessageScroller are what make the transcript scroll instead of the document — the single most common thing to get wrong here, and it fails by pushing the composer off the bottom of the screen.
 - The panel is a Card, not a hand-built bordered section: CardHeader (title, description, CardAction), the MessageScroller and a CardFooter all inset by the card's own `--card-p`, so the three regions share one edge at any card density.
 - `dvh` rather than `vh`: on mobile the URL bar collapses, and a `vh`-sized panel puts the composer under it exactly when someone is trying to type.
@@ -245,7 +246,9 @@ export function ChatPanel() {
 						onStop={() => undefined}
 						stopLabel="Stop answering"
 						onAttach={() => undefined}
-						footer="Enter to send · Shift+Enter for a new line"
+						// A keyboard hint, so only where Enter sends: on touch Return
+						// breaks the line and the button sends, and the row goes away.
+						footer={({ sendOn }) => (sendOn === "enter" ? "Enter to send · Shift+Enter for a new line" : null)}
 						// Model and effort sit in `actions`, at the send end of the row:
 						// they qualify the message about to be sent, so they belong beside
 						// the button that sends it rather than next to the attach control.

package/llms/tasks/building-a-chat.md

@@ -0,0 +1,158 @@
+# Task: building a chat
+
+Sable ships the parts a conversation is made of, and the [`ChatPanel`
+pattern](../patterns/chat-panel.md) assembles them into a working screen. It
+ships no transport, no message store and no model client. This guide is the
+seam between the two: which part owns what, how a request's lifecycle maps
+onto the parts' props, what each failure looks like, and what is left for the
+app.
+
+Check every name here against the installed package with
+`sable component <Name> --detail full` before relying on it.
+
+## Who owns what
+
+| Sable part | Owns | Does not own |
+|---|---|---|
+| [`MessageScroller`](../components/message-scroller.md) | The scroll region: following the newest message, letting go when the reader scrolls up, the jump-to-latest button, holding still when history is prepended, `scrollToMessage`, `onVisibleMessagesChange` | Your messages, your loading of history |
+| [`Message`](../components/message.md) | One turn's row: side (`align`), avatar gutter, `header` and `footer`, `grouped` runs, `messageId` | How the content looks |
+| [`Bubble`](../components/bubble.md) | The surface: `muted` (them), `primary` (me), `plain` (long-form answers), the tail, reactions | Timestamps and names (those go in Message's `header`/`footer`) |
+| [`StreamingText`](../components/streaming-text.md) | Text arriving a token at a time: `text` (append-only), `streaming`, the caret, `aria-busy` | Markdown, and announcing the finished answer |
+| [`ThinkingOrb`](../components/thinking-orb.md), [`Marker`](../components/marker.md) | The wait before the first token (orb or `Marker icon="spinner" spin`), and every non-message row: status, tool notes, date breaks, bordered notices | — |
+| [`Attachment`](../components/attachment.md) | A file's four states: queued, `uploading` with `progress`, `error` with the reason in `meta`, delivered | The upload itself |
+| [`ChatComposer`](../components/chat-composer.md) | The input: Enter to send (never mid-IME; Return breaks the line on touch), `busy` + `onStop`, `allowEmpty` for attachment-only sends, `disabled`, `invalid`, `footer` as a function of the send key in effect | Whether the send succeeded |
+| [`Toast`](../components/toast.md) | Notices about the app, not the conversation | — |
+
+**The app owns** the transport (HTTP, SSE, WebSocket), the streaming state, message ids, persistence and history, retries and backoff, auth, rate limits, moderation, uploads, and what counts as a failed turn. Sable renders whatever state you hand it; it never infers one.
+
+## The lifecycle, mapped to props
+
+A turn moves through five states. Keep **one** status value in the app and derive every prop from it; two flags (`sending` here, `streaming` there) drift, and the composer ends up saying "sending" under an answer that already finished.
+
+| State | Transcript | Composer |
+|---|---|---|
+| **idle** | Settled messages. The last answer's `footer` carries its actions (copy, regenerate) as a `Toolbar` of icon `ToolbarButton`s | Normal; `busy={false}` |
+| **submitted** (sent, no token yet) | The reader's message, optimistically, with the id you generated. Below it, the wait: `<Marker icon="spinner" spin shimmer>Thinking…</Marker>` or a `ThinkingOrb` | `busy` and `onStop` |
+| **streaming** | The wait is **replaced** by the answer: `StreamingText` with `streaming` in a `plain` Bubble. No answer actions yet | `busy` and `onStop` |
+| **done** | `streaming={false}`, which removes the caret: the only signal the reader gets that the answer is complete. Actions appear in the `footer` | `busy={false}` |
+| **stopped / error** | See [Failures](#failures) | `busy={false}`; the draft is still the reader's |
+
+Rules that follow from it:
+
+- **One indicator per wait.** The spinner Marker (or orb) shows before the first token and is removed when tokens land. While the answer streams, its own caret is the indicator; pass `caret={false}` only when something adjacent already reports the wait.
+- **`busy` is not `disabled`.** `busy` is temporary and comes with a way out (`onStop` turns send into stop). `disabled` is for a composer that cannot send at all: offline, over a quota, a read-only thread.
+- **Controlled composers are cleared by you, after the send is accepted.** An uncontrolled composer clears itself; a controlled one leaves the text so a failed send loses nothing.
+- **Regenerate replaces the answer, not appends to it.** `StreamingText` assumes `text` only grows. When regenerating, give the new answer a new `key` (a new message id does it) so the old spans unmount instead of being diffed against.
+- **Editing a sent message** is the app's feature: put the text back in a controlled composer, or swap the Bubble's content for a `Textarea` in place, then truncate the turns after it before re-sending. Sable has no edit mode on Message.
+
+## Scrolling
+
+`MessageScroller` needs no configuration for streaming. It follows the newest message as messages arrive **and** as the last one grows, and stops following the moment the reader scrolls up past `followThreshold` (64px). The jump-to-latest button appears while they are away; returning to the bottom resumes following.
+
+- Bound it: `flex-1 min-h-0` inside a flex column. A transcript that grows the page pushes the composer off the screen.
+- Never call `scrollToBottom` per token. It fights a reader who scrolled up to read. Call it once when **they** send, so their own message is in view.
+- Give every `Message` a `messageId`; it is the handle for `scrollToMessage`, `initialScroll={{ messageId }}` (restore a read position) and `onVisibleMessagesChange` (read receipts).
+- Load older history by prepending to `children`. The scroller anchors on the first rendered message, so the view does not jump.
+
+## Attachments
+
+- **Pending** files are `Attachment` chips in the composer's `attachments`, each with a remove action. Upload when picked, not when sent, so `status="uploading"` and `progress` can show in the box the file belongs to.
+- **Failed** uploads keep their card: `status="error"`, the reason in `meta` ("Over the 50 MB limit"), a Retry action. Colour alone is not a status.
+- **Attachment-only sends:** `allowEmpty={files.length > 0}`. `onSend` then receives `""`. Tie it to the pending files; a constant `allowEmpty` leaves send enabled with nothing to send. Disable sending while an upload is still in flight if your backend needs the file first.
+- **Sent** files move into the turn: one `Message` holding the files and the text together, `variant="media"` for images, `variant="card"` for documents, `onOpen` to preview.
+
+## Failures
+
+Put each failure where the reader is looking when it happens. A failure that belongs to a turn stays in the transcript, next to that turn; a toast is for things that are not about the conversation.
+
+| Failure | UI |
+|---|---|
+| **Send rejected** (network down, 4xx before streaming) | The optimistic message stays, with a Message `footer` of `<InlineStatus tone="destructive">Not sent</InlineStatus>` and a Retry button. The composer keeps the draft if it was controlled |
+| **Error mid-stream** | Keep what streamed, set `streaming={false}`, and add `<Marker variant="bordered" icon="warning">The answer was cut off.</Marker>` with Retry in the answer's `footer`. Never delete partial text the reader may be reading |
+| **Stopped by the reader** | Keep the partial answer, `streaming={false}`, and a quiet `<Marker variant="note">Stopped</Marker>`. Not an error, so no warning colour |
+| **Rate limited / quota** | `ChatComposer disabled`, with the reason and the wait in its `footer` ("Limit reached · try again in 2 min"). Re-enable it when the window passes |
+| **Empty response** | Treat as an error: a bordered Marker ("No answer came back") and Retry. An empty plain Bubble reads as a rendering bug |
+| **Tool call failed** | A `Marker variant="note" icon="warning"` in that turn's `header` ("Search failed: timeout"). The answer may continue without it; say so rather than hiding the failure |
+| **Disconnected** (socket dropped) | A `Banner` above the transcript, or a toast if the panel is small, and `disabled` on the composer until reconnected |
+| **Moderation / blocked** | A bordered Marker in place of the answer, naming what happened. Don't render the blocked content and then hide it |
+
+## Accessibility
+
+- **Don't put streamed text in a live region.** Every token would be announced. `StreamingText` sets `aria-busy` while streaming instead.
+- **Announce the turn once, when it settles.** Keep an empty `<p role="status" className="sr-only">` mounted from the start, and set its text when a turn ends ("Answer ready", "Answer stopped", "Couldn't answer"). A region inserted together with its text is announced unreliably (`sable docs AGENTS` → Announcing and focusing).
+- **A status Marker is already live** (`role="status"`), so replacing its text as the work moves on ("Searching the docs" → "Writing the answer") is announced. Remove it when the work ends; a permanent "Thinking…" is a region that never resolves.
+- **ThinkingOrb's `label` must stay constant** while it is mounted. Put the changing phase in adjacent text.
+- **Focus:** after sending, keep focus in the composer (`fieldRef`) so the reader can keep typing. After Stop, ChatComposer moves focus to the field itself (the stop button turns back into send in place, and a disabled send would drop focus to the page); on touch it leaves focus alone rather than raise the keyboard.
+- **Reduced motion:** StreamingText, ThinkingOrb, the Marker shimmer and the scroller's smooth scrolling all fall back under `prefers-reduced-motion` or `MotionProvider` off. Don't add your own animation that ignores it.
+
+## Rendering the model's output
+
+Sable has no Markdown renderer; use one (react-markdown, or your own parser) and map its elements to Sable parts:
+
+- the answer sits in `<Bubble variant="plain">`, which drops the surface and the measure cap; give it `max-w-full` so a wide code line scrolls inside its block rather than pushing the transcript sideways on a phone;
+- fenced code → `CodeBlock` (copy button included; wire highlighting once with `CodeHighlightProvider`);
+- inline code → `Code`; tables → `Table` parts; links → your router's link or a plain `<a>` with `rel="noopener noreferrer"` for outside URLs;
+- paragraphs and lists take the prose tier (`useTypeTier().prose`) rather than a hand-picked size.
+
+**Never render model output as HTML** (`dangerouslySetInnerHTML`, or a Markdown renderer with raw HTML on). Model output is untrusted input. Strip or escape HTML, and allow only `http(s)` and `mailto` link targets.
+
+While an answer streams, render it with `StreamingText` (plain text); switch to the Markdown renderer when it settles, or render Markdown progressively if your renderer tolerates half-finished syntax (an unclosed fence). Either way the switch must not move the text the reader is on.
+
+## Wiring a chat hook
+
+The shape below fits most streaming chat hooks. The hook's names (`messages`, `status`, `send`, `stop`, `regenerate`, `error`) belong to **your library**, not Sable. The AI SDK's `useChat`, for example, exposes a `status` of `"submitted" | "streaming" | "ready" | "error"`; check the version you have installed.
+
+```tsx
+import {
+	Bubble, ChatComposer, Marker, Message, MessageScroller, StreamingText,
+} from "@sableui/react"
+
+function Chat() {
+	const { messages, status, send, stop } = useYourChat() // your library
+	const busy = status === "submitted" || status === "streaming"
+	const last = messages.at(-1)
+	return (
+		<div className="flex h-full min-h-0 flex-col">
+			<MessageScroller className="flex-1 min-h-0 px-4 py-6">
+				{messages.map((m) => {
+					const mine = m.role === "user"
+					const live = status === "streaming" && m.id === last?.id && !mine
+					return (
+						<Message key={m.id} messageId={m.id} align={mine ? "end" : "start"}>
+							<Bubble variant={mine ? "primary" : "plain"} align={mine ? "end" : "start"} className={mine ? undefined : "max-w-full"}>
+								{mine ? m.text : <StreamingText text={m.text} streaming={live} />}
+							</Bubble>
+						</Message>
+					)
+				})}
+				{status === "submitted" ? <Marker icon="spinner" spin shimmer>Thinking…</Marker> : null}
+			</MessageScroller>
+			<ChatComposer
+				onSend={(text) => send(text)}
+				busy={busy}
+				onStop={stop}
+				footer={({ sendOn }) => (sendOn === "enter" ? "Enter to send · Shift+Enter for a new line" : null)}
+			/>
+		</div>
+	)
+}
+```
+
+For the full screen (header, grouping, avatars, answer actions, the empty state), start from `sable pattern ChatPanel --skeleton` and replace its sample data with your hook. For a chat docked beside other work, compose the same three parts inside a `Sheet` or a panel and wrap them in `<Density value="compact">`.
+
+## What Sable does not do
+
+- No transport, retries or reconnection.
+- No message store, ids, history paging or persistence; `MessageScroller` only renders what you pass.
+- No Markdown parsing or sanitising.
+- No mentions or slash commands in `ChatComposer` (it holds a plain string).
+- No typing indicators or presence from other people; compose them from `Marker` and `Avatar` status if your product has them.
+
+## Before you ship
+
+1. `sable check src` passes.
+2. Walk the journey (`sable docs reviewing-a-journey`) through every row of the lifecycle and failure tables: send, wait, stream, stop mid-answer, regenerate, a failed send, an error mid-stream, attachment-only send, an upload failure, and a reload that restores the thread.
+3. Scroll up mid-stream: the view must stay put, and jump-to-latest must appear and work.
+4. Keyboard only, then a screen reader: the finished answer is announced once; Stop is reachable from the composer; nothing announces per token.
+5. On a phone: Return breaks the line, the send button sends, the composer stays above the on-screen keyboard (`dvh`, not `vh`), and wide code scrolls inside its block.
+6. Reduced motion on: text still arrives, nothing keeps moving after the turn settles (`sable docs reviewing-motion`).

package/llms/tasks/building-with-sable.md

@@ -25,6 +25,7 @@ $sable inspire these references into a warm, compact shop preset
 $sable build a ceramics shop using .sable/presets/clay.json
 $sable audit our checkout and report prioritized findings
 $sable polish our checkout and repair the reported issues
+$sable fix the settings dialog's footer buttons
 ```
 
 Claude Code and Cursor use `/sable` with the same modes. `create` is a `build`
@@ -32,7 +33,9 @@ alias. These are agent instructions; the shell CLI serves catalog resources and
 validates records. Other agents can read the package's `skills/sable/SKILL.md`.
 
 `inspire` produces a preset and component preview. `audit` evaluates an existing
-interface and reports by default. A reference URL does not request a cloned site.
+interface and reports by default. `fix` repairs one scoped defect: it reads only the
+contracts the change touches and finishes with `sable check` on the changed files
+and a look at the affected state, escalating to `polish` when the change grows. A reference URL does not request a cloned site.
 Develop alternative rendered directions when requested or when a consequential
 choice needs comparison. A three-design comparison is not a mandatory build step.
 

package/llms/tasks/converting-an-app.md

@@ -3,6 +3,11 @@
 Migrating a React app that has its own styles. The order below front-loads the
 decisions that invalidate later work if you get them wrong.
 
+Coming from **shadcn/ui or Radix**? Do this order, then use
+[migrating-from-shadcn.md](./migrating-from-shadcn.md) for step 3: it maps
+`asChild` → `render`, array values, renamed parts and events, the tokens and
+icons, and every shadcn component to its Sable counterpart.
+
 ## 0. Classify every surface first
 
 Before touching a component, **list the routes and assign a register to each** —
@@ -147,5 +152,7 @@ layers panel lost 174 lines by adopting `Tree`.
 
 - [building-a-tool.md](./building-a-tool.md) or
   [building-a-page.md](./building-a-page.md)
+- [migrating-from-shadcn.md](./migrating-from-shadcn.md) — the per-component map from shadcn/ui and Radix
+- [extending-a-component.md](./extending-a-component.md) — what to do where the app used to edit a component's source
 - `DESIGN.md → Registers`
 - `llms/reference/token-intent.md`

package/llms/tasks/extending-a-component.md

@@ -0,0 +1,170 @@
+# Task: extending a Sable component
+
+You need a component to do something it doesn't do out of the box: be a link,
+carry an extra control, react to a key, suggest names as someone types. Before
+restyling it from the outside or copying it into the app, go through the
+extension points below, roughly in this order. Most needs are one of them, and
+each keeps the component's states, density, focus and keyboard contract, which a
+copy loses the day it is made.
+
+The split to keep in mind: **behaviour** comes from Base UI and Sable, **look**
+comes from variants and tokens, and **what is yours** (content, data, what an
+action does) goes in through props and slots.
+
+## 1. Compose an element: `render`
+
+Every component that renders an element takes `render`, and keeps its props,
+ref and state on the element you give it. This is how a Sable control becomes a
+link, or any router's link:
+
+```tsx
+<Button render={<a href="/pricing" />}>See pricing</Button>
+<Card render={<Link to="/projects/42" />}>…</Card>
+<Button variant="ghost" render={<Link to="/inbox" />} iconStart={<Icon name="inbox" />}>Inbox</Button>
+```
+
+A link that looks like a button is `<Button render={<a … />}>`, never an `<a>`
+wearing button classes (`sable-lint` flags that as `lookalike-control`).
+
+## 2. Fill a slot
+
+Slots take content you own. The component lays it out and keeps it aligned with
+its own parts. Check `sable component <Name> --props` for the full list.
+
+| Component | Slots |
+|---|---|
+| Button | `iconStart`, `iconEnd`, `badge` |
+| ChatComposer | `leading`, `actions`, `attachments`, `footer` (a node, or a function of the send key in effect) |
+| Message | `avatar`, `header`, `footer` |
+| PageHeader | `actions`, `back` |
+| MenuItem, MenuLinkItem, CaretMenuItem | `icon`, `description` |
+
+`className` on a component is for layout (margins, width, alignment). It is not
+a slot for a new look; see section 5.
+
+## 3. Hold the state, reach the element
+
+Controlled props (`value` + `onValueChange`, `open` + `onOpenChange`) let the
+app own the state and change it from anywhere: clear a draft after a server
+confirms the send, open a menu from a shortcut.
+
+Refs reach the element itself. ChatComposer's `fieldRef` is the textarea, which
+is enough to focus it, read the caret, or **listen to it**. That last one is an
+extension point in its own right: a key handler on the field that handles a key
+and calls `event.preventDefault()` owns that key, and ChatComposer does not also
+act on it. That is how the suggestion list below takes Enter without the message
+being sent.
+
+## 4. Add behaviour on top: mentions and slash commands
+
+The worked example. Mentions and slash commands are behaviour that sits on a
+text field, not a new kind of field, so Sable ships the parts every app gets
+wrong and leaves the rest to the app:
+
+- **Sable owns:** noticing a trigger character at the caret (`@`, `/`, `#`), on
+  a word boundary and after IME composition; placing the list at the caret;
+  ↑/↓/Enter/Tab/Escape while focus stays in the field; the ARIA that lets a
+  screen reader follow along.
+- **The app owns:** the items (filter or fetch them, debounced, from the query),
+  the loading and empty states, and what choosing one does.
+
+```tsx
+const trigger = useCaretTrigger({
+	triggers: [{ char: "@", allowSpaces: true }, { char: "/", atStart: true }],
+})
+const q = trigger.match?.query.toLowerCase() ?? ""
+const commands = trigger.match?.trigger.char === "/"
+
+<ChatComposer fieldRef={trigger.fieldRef} onSend={send} />
+<CaretMenu trigger={trigger} label={commands ? "Commands" : "People"} status={loading ? "Searching…" : undefined}>
+	{commands
+		? slashCommands.filter((c) => c.name.startsWith(q)).map((c) => (
+				<CaretMenuItem key={c.name} description={c.hint} onSelect={() => { c.run(); trigger.replace("") }}>
+					/{c.name}
+				</CaretMenuItem>
+			))
+		: people.filter((p) => p.name.toLowerCase().includes(q)).map((p) => (
+				<CaretMenuItem key={p.id} onSelect={() => trigger.replace(`@${p.name} `)}>{p.name}</CaretMenuItem>
+			))}
+</CaretMenu>
+```
+
+A mention is inserted as text with a trailing space; a command runs and
+`replace("")` clears its `/query`. The same hook works on `Textarea` and
+`Input` through `ref={trigger.fieldRef}`. `sable component CaretMenu` has the
+props and the accessibility notes.
+
+The pattern generalises. To add your own behaviour to a Sable field, attach to
+it through its ref, read and write through the field's own input path (the hook's
+`replace()` does, so controlled values and undo keep working), and take a key by
+handling it first and calling `preventDefault()`.
+
+### Mentions as chips are a different job
+
+`useCaretTrigger` keeps the value a plain string, because that is what a
+textarea holds. Showing a mention as a token *inside the field* needs a
+rich-text (contenteditable) editor such as TipTap or Lexical, with its own value
+model. Sable does not own an editor. Two ways to get chips today:
+
+- Keep text mentions in the field and render them as chips where the message is
+  shown: parse `@Name` against your people list when you render the Message.
+- Use an editor in place of the composer's field and keep Sable's controls around
+  it. A ChatComposer slot for a custom editor is a possible later addition; it
+  doesn't exist yet, so don't write code that assumes it.
+
+## 5. Change the look: tokens and presets, not overrides
+
+A component's fill, edge, corners, ink and interaction states come from its
+variants and the theme's tokens. To change how it looks:
+
+- **Everywhere:** override tokens on `:root` (or any subtree) after Sable's CSS:
+  radius, density, accent, type scale, motion. `sable token --list` lists them.
+- **As a reusable direction:** a preset (`sable docs creating-a-preset`), compiled
+  to scoped CSS with `sable preset --css <path>`.
+- **One component, a look it lacks:** that is a missing variant. Report it (see
+  section 8); don't paint it on with `className`. `component-restyle`,
+  `destructive-item-ink` and `table-edge-padding` flag the common overrides,
+  because a class that repaints a part fights the part's own hover, focus and
+  disabled states.
+
+Parts carry `data-slot` names (`chat-composer-attachments`,
+`menu-item-description`, `button-group`). They are good test selectors and fine
+for layout from a parent. They are not a way around the rule above, and a slot
+name a component's docs don't mention may change between versions.
+
+## 6. Add icons: `composeIconSets`
+
+`<IconProvider set={composeIconSets(appExtras, reiconIconSet)}>` adds your own
+glyphs alongside Reicon's (list the added names in `.sable/icons.json` so
+`sable grade` accepts them). Components keep using semantic names.
+
+## 7. Fix a defect: `sable patch`
+
+When a component is wrong, not merely missing something, patch the installed
+module and record why: `sable patch <Component> --reason … --repro …`. Doctor
+re-checks it on every upgrade. `sable docs patching-a-component` has the steps.
+
+## 8. App-owned, or a library gap?
+
+It belongs in the app when it is about **your** product: domain data, copy,
+business rules, which items a list offers, what an action does, the layout of a
+signature surface.
+
+It is a library gap when **another app would need the same thing** and none of
+the sections above gets there without fighting the component: a missing
+variant, slot, prop, or piece of behaviour. Then:
+
+1. Show the search: `sable search "<need>"` and what came back.
+2. Name the missing capability and the smallest API that would cover it.
+3. Meanwhile, compose the nearest thing from Sable's parts in the app (not a
+   copy of the component), and say in your summary that it is a stand-in for a
+   reported gap.
+
+In the Sable repository itself, close the gap in the package and then use it
+(`sable docs adding-a-component`).
+
+## Read next
+
+- [patching-a-component.md](./patching-a-component.md): the patch workflow
+- [creating-a-preset.md](./creating-a-preset.md): a reusable look
+- [building-a-chat.md](./building-a-chat.md): the chat parts and who owns what