@sableui/react 0.11.0 → 0.13.0

package/dist/patterns/chat-panel.js

@@ -145,7 +145,7 @@ function ChatPanel() {
             onStop: () => void 0,
             stopLabel: "Stop answering",
             onAttach: () => void 0,
-            footer: "Enter to send \xB7 Shift+Enter for a new line",
+            footer: ({ sendOn }) => sendOn === "enter" ? "Enter to send \xB7 Shift+Enter for a new line" : null,
             actions: /* @__PURE__ */ jsxs(
               SettingsMenu,
               {

package/dist/patterns/chat-panel.meta.js

@@ -4,6 +4,7 @@ var chatPanelMeta = {
   summary: "A full-height conversation surface: titled header, scrolling transcript, and a composer pinned to the bottom \u2014 the assembled shape of an AI assistant, a support thread, or a DM.",
   intent: "Reach for this for any conversation that owns its screen \u2014 an assistant, a support inbox thread, a DM. Not for a chat docked beside other work (compose the same three parts inside a Sheet or a PanelGroup instead), and not for a comment thread under an article, which is a FeedPage concern.",
   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 \u2014 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 \u2014 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.",

package/dist/styles.css

@@ -1006,6 +1006,31 @@
 	margin-inline: calc(-1 * max(--spacing(1), calc(var(--radius-md) / 3)));
 }
 
+/* ButtonGroup's joins. Keyed to sibling Buttons (`data-variant`), never to
+   :first/:last-child: an open Menu inserts focus-guard spans beside its
+   trigger, and a position rule then read the chevron as "not last" and
+   squared its outer corner for as long as the menu was open. Inner corners
+   square through the per-side radius vars Button reads; bordered buttons
+   overlap by their hairline; filled and ghost ones get a seam in their own
+   ink, except while focused, where the shadow is the focus ring. */
+@utility button-group-join {
+	& > [data-variant] ~ [data-variant] {
+		--button-radius-s: 0px;
+	}
+	& > [data-variant]:has(~ [data-variant]) {
+		--button-radius-e: 0px;
+	}
+	& > [data-variant] ~ [data-variant="outline"] {
+		margin-inline-start: -1px;
+	}
+	& > [data-variant] ~ [data-variant]:not([data-variant="outline"], :focus-visible) {
+		box-shadow: inset 1px 0 0 color-mix(in oklab, currentColor 20%, transparent);
+	}
+	& > :focus-visible {
+		z-index: 1;
+	}
+}
+
 @utility sable-frame {
 	--sable-frame-radius: var(--radius-lg);
 	--sable-frame-padding: --spacing(4);

package/llms/components/app-header.md

@@ -36,7 +36,7 @@ Use AppHeader for compact application chrome at the top of a screen, usually wit
 
 ## Related
 
-- Components: AppShell, PageHeader, BottomNav
+- Components: AppShell, PageHeader, BottomNav, NavigationMenu
 
 ## Examples
 

package/llms/components/button-group.md

@@ -0,0 +1,55 @@
+# ButtonGroup
+
+**Status:** stable
+
+Buttons joined into one control: a split button (an action beside the chevron that opens its menu) or a short run of related actions. The children stay ordinary Buttons; the group squares their inner corners, collapses bordered seams into one hairline, and draws a seam between filled ones.
+
+**Keywords:** split button, button group, segmented actions, dropdown button, joined buttons, toolbar
+
+## Usage
+
+Use ButtonGroup when one action has close alternatives (Copy page, with Open in… behind a chevron) or a few actions belong together as one object (zoom out, reset, zoom in). Use ToggleGroup for a choice that stays selected, and Tabs to switch views.
+
+### Best practices
+
+- Do: Give the children one height: `size="sm"` with `size="icon-sm"`, `md` with `icon`. The group aligns them but cannot reconcile two heights into one edge.
+- Do: For a split button, put the main action first and a Menu whose trigger is the chevron Button second, with an aria-label on the trigger ("More page actions").
+- Do: Name the group with aria-label when the buttons alone do not say what they act on.
+- Don't: Do not round or border the children yourself to make them meet; that is the group's job, and an override breaks under a theme's button shape.
+- Don't: Do not use it for a selection that stays on. That is ToggleGroup, which carries the pressed state.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| role | string | "group" | Group semantics, so a screen reader announces the buttons as one set. Pass `toolbar` when it carries arrow-key navigation of your own. |
+| className | string | — | Layout classes for the group (margins, alignment). The children's look comes from their own variants. |
+| ...props | ComponentPropsWithRef<"div"> | — | All native <div> attributes, including aria-label. |
+
+## Accessibility
+
+- Renders role="group", so assistive tech announces the buttons as one set; name it with aria-label.
+- Each child keeps its own focus stop and label; a focused child is raised above its neighbour so its ring is drawn whole.
+- An icon-only chevron that opens a menu needs its own aria-label, such as "More page actions".
+
+## Related
+
+- Components: Button, Menu, Toggle
+
+## Examples
+
+### Split button with a menu
+
+```tsx
+import { Button, ButtonGroup, Icon, Menu, MenuContent, MenuItem, MenuTrigger } from "@sableui/react"
+
+<ButtonGroup aria-label="Page actions"><Button variant="outline" size="sm" iconStart={<Icon name="copy" />} onClick={copy}>Copy page</Button><Menu><MenuTrigger render={<Button variant="outline" size="icon-sm" aria-label="More page actions" />}><Icon name="chevron-down" /></MenuTrigger><MenuContent align="end"><MenuItem icon={<Icon name="file" />} description="View this page as plain text">View as Markdown</MenuItem></MenuContent></Menu></ButtonGroup>
+```
+
+### Related actions
+
+```tsx
+import { Button, ButtonGroup, Icon } from "@sableui/react"
+
+<ButtonGroup aria-label="Zoom"><Button variant="secondary" size="icon-sm" aria-label="Zoom out"><Icon name="minus" /></Button><Button variant="secondary" size="sm">100%</Button><Button variant="secondary" size="icon-sm" aria-label="Zoom in"><Icon name="plus" /></Button></ButtonGroup>
+```

package/llms/components/button.md

@@ -13,7 +13,7 @@ Use Button when the user commits an action, submits a form, opens UI, or confirm
 ### Best practices
 
 - Do: Use a single primary button in a view or dense panel so the action hierarchy stays obvious.
-- Do: For a copy control, pair an icon Button with `useCopy(text, { timeout? })`. It takes the text when the hook is called and returns `{ copy, copied }`; `copy()` takes no argument, so pass the value the button copies to the hook, not to `copy`.
+- Do: For a copy control, pair an icon Button with `useCopy(text, { timeout? })`. It takes the text when the hook is called and returns `{ copy, copied }`; `copy()` takes no argument, so pass the value the button copies to the hook, not to `copy`. Text that costs something to produce (a file to fetch) goes in as a function, `useCopy(() => fetch(url).then((r) => r.text()))`, called only on click.
 - Do: Write labels as actions, such as "Save changes" or "Delete draft", instead of vague labels like "OK".
 - Do: Use loading with loadingLabel for async work so the action cannot double-fire and the state is announced.
 - Do: Put icons in iconStart / iconEnd rather than as children, so the button applies its optical padding. Start icons say what the action is (plus, share); end icons say where it goes (chevron-right, external).

package/llms/components/caret-menu.md

@@ -0,0 +1,100 @@
+# CaretMenu
+
+**Status:** beta
+
+Suggestions at the caret of a text field, for @mentions and /slash commands. `useCaretTrigger` watches a Textarea, Input or ChatComposer (through `fieldRef`) for a trigger character and reports the query; CaretMenu draws the list beside the trigger and drives it from the field's keys, so focus never leaves the field. The value stays plain text: a mention is inserted as `@Sam Rivera`, a command runs and clears its `/query`.
+
+**Keywords:** mention, mentions, at mention, slash command, slash commands, autocomplete, typeahead, suggestions, emoji picker, hashtag, trigger
+
+## Usage
+
+Use CaretMenu with `useCaretTrigger` when typing a character in running text should offer choices: `@` for people, `/` for commands, `#` for channels, `:` for emoji. The app owns the items (filter or fetch them from `trigger.match.query`) and what choosing one does; Sable owns detecting the trigger, placing the list at the caret, the keys and the accessibility. Use Combobox when the whole field is a search for one value, and CommandMenu for a global palette.
+
+### Best practices
+
+- Do: Attach the hook's `fieldRef` to the field: `ref` on Textarea or Input, `fieldRef` on ChatComposer. On ChatComposer, Enter picks the highlighted suggestion instead of sending, because CaretMenu takes the Enter first.
+- Do: Insert a mention with a trailing space, `trigger.replace(`@${person.name} `)`, so the reader keeps typing; run a slash command and then `trigger.replace("")` to clear `/query` from the field.
+- Do: For `@` names with spaces set `allowSpaces: true` on that trigger; for `/` commands set `atStart: true` so `and/or` mid-sentence stays text.
+- Do: Fetch remote suggestions from `trigger.match?.query` yourself, debounced, and pass `status` while loading or when nothing matches ("Searching…", "No one matches"). The status row is also what the list announces.
+- Don't: Do not expect chips inside the field. A textarea holds text, so a mention is text. Rendering tokens in the field needs a rich-text editor, which Sable does not own (`sable docs extending-a-component`).
+- Don't: Do not move focus into the list or wrap the field in a Popover. Focus stays in the field; the list is pointed at with aria-activedescendant.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| useCaretTrigger | yes | The hook on the field: trigger detection, the query, the caret anchor, replace() and dismiss(). |
+| CaretMenu | yes | The list at the caret, its keys, and its announcements. |
+| CaretMenuItem | yes | One suggestion row, with optional icon and description. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| CaretMenuItem | div props + onSelect: () => void + disabled?: boolean + icon?: ReactNode + description?: ReactNode | One suggestion, styled as a Menu row. `onSelect` runs on Enter, Tab or click; `icon` and `description` work as on MenuItem. A disabled row shows but the arrow keys skip it. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| trigger | UseCaretTriggerResult | — | The result of `useCaretTrigger({ triggers })`, whose `fieldRef` is attached to the field. Each trigger is `{ char, atStart?, allowSpaces?, maxQueryLength? }`; the result carries `match` (`{ trigger, query, start, end }` or null), `replace(text)`, `dismiss()` and `getAnchorRect()`. |
+| label | string | — | The list's accessible name, e.g. "People" or "Commands". |
+| status | ReactNode | — | A row under the items for what the list is doing: loading, nothing found, an error. Announced politely in place of the suggestion count. With no items and no status the list stays shut. |
+| children | ReactNode | — | CaretMenuItems, already filtered for the query. |
+| className | string | — | Layout classes for the popup, such as a width. |
+
+## Tokens used
+
+`popover`, `popover-foreground`, `border-floating`, `accent`, `accent-foreground`, `muted-foreground`
+
+## Motion
+
+- **arrival** · root · `motion-pop` — Scales in from the caret's side, so the list reads as coming from the character just typed. It leaves instantly: it answers a keystroke and should be gone by the next one.
+
+## Accessibility
+
+- Focus stays in the field. The field carries aria-autocomplete="list", aria-controls (the listbox) and aria-activedescendant (the highlighted option), so a screen reader follows the arrow keys without focus moving.
+- An <input> becomes role="combobox" with aria-expanded. A <textarea> keeps its textbox role (combobox would drop multiline), and since a textbox cannot carry aria-expanded, opening is announced through a polite status, mounted from the start: "3 suggestions", or the `status` text.
+- ↑/↓ move the highlight and wrap; Enter or Tab choose it; Escape closes the list without reaching an enclosing Dialog or Sheet. Shift+Enter is left alone, so a line break still breaks the line.
+- Rows keep focus in the field on pointer down, so a click does not blur it and close the list first.
+- Triggers follow a word boundary (`ana@example.com` and `and/or` stay text), wait for IME composition to end, and stay closed after Escape until the caret leaves that trigger.
+
+## Related
+
+- Components: ChatComposer, Textarea, Input, Combobox, CommandMenu, Menu
+
+## Examples
+
+### Mentions and slash commands in a ChatComposer
+
+```tsx
+import { Avatar, CaretMenu, CaretMenuItem, ChatComposer, useCaretTrigger } from "@sableui/react"
+
+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={!commands && people.length === 0 ? "No one matches" : 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} icon={<Avatar size="sm" src={p.avatar} fallback={p.initials} />} onSelect={() => trigger.replace(`@${p.name} `)}>{p.name}</CaretMenuItem>
+		))}
+</CaretMenu>
+```
+
+### On a Textarea, with remote results
+
+```tsx
+import { CaretMenu, CaretMenuItem, Textarea, useCaretTrigger } from "@sableui/react"
+
+const trigger = useCaretTrigger({ triggers: [{ char: "#" }] })
+// Fetch from trigger.match?.query yourself, debounced; pass the state as status.
+<Textarea ref={trigger.fieldRef} aria-label="Note" />
+<CaretMenu trigger={trigger} label="Channels" status={loading ? "Searching…" : channels.length === 0 ? "No channels match" : undefined}>
+	{channels.map((c) => <CaretMenuItem key={c.id} onSelect={() => trigger.replace(`#${c.name} `)}>#{c.name}</CaretMenuItem>)}
+</CaretMenu>
+```

package/llms/components/chat-composer.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-The input half of a conversation: one surface holding attachments, an auto-growing field, and its controls. Enter sends, Shift+Enter breaks the line (sendOn="mod-enter" swaps them for long-form replies), and send becomes stop while a reply streams.
+The input half of a conversation: one surface holding attachments, an auto-growing field, and its controls. Enter sends, Shift+Enter breaks the line (sendOn="mod-enter" swaps them for long-form replies; on touch, Return always breaks the line), and send becomes stop while a reply streams. allowEmpty sends attachments without text.
 
 **Keywords:** chat input, composer, message input, prompt input, send message, ai chat, support chat, textarea
 
@@ -12,13 +12,15 @@ Pairs with MessageScroller to make a working chat. A single surface rather than
 
 ### Best practices
 
+- Do: Wiring it to a streaming source? `sable docs building-a-chat` maps a turn lifecycle (submitted, streaming, done, stopped, error) onto `busy`, `onStop` and `disabled`, and says where each failure goes.
 - Do: Pass `busy` while a reply streams, and `onStop` alongside it. Interrupting a long generation is the most common thing a reader wants during one, and the control belongs where their cursor already is.
 - Do: Leave it uncontrolled unless you need the text elsewhere — a slash-command menu, a draft you persist. Uncontrolled clears itself on send; controlled does not.
 - Do: Render pending uploads as `<Attachment>` chips in `attachments`, so the file and the message it belongs to stay in one box.
+- Do: Pass `allowEmpty={files.length > 0}` when a file can go without a caption. Send enables on the attachment alone and `onSend` receives `""`. Tie it to the pending files: a constant `allowEmpty` leaves send enabled with nothing to send.
 - Do: Put model pickers and tool toggles in `leading`, beside the attach button — they are composer state, not message content, and belong on the chrome row rather than in the field.
 - Do: Building a docked agent panel inside a tool? Wrap the whole conversation — scroller, messages and composer — in `<Density value="compact">`. The entire set follows the workspace register from there: prose drops a tier, the rhythm tightens, and the controls come off the compact ladder. Do not hand-size it at the call site.
 - Don't: Do not clear a controlled composer for the user on send. Only the caller knows whether the send succeeded, and clearing on their behalf loses the message when it did not.
-- Don't: Do not add your own Enter-to-send handler on top. The built-in one already guards against firing mid-IME-composition, which is the line hand-rolled chat inputs miss.
+- Don't: Do not add your own Enter-to-send handler on top. The built-in one already guards against firing mid-IME-composition, and on a touch device lets Return break the line (a soft keyboard has no Shift+Return), which are the lines hand-rolled chat inputs miss.
 - Don't: Do not use it as a general multi-line input inside a larger form. That is `Textarea`. A standalone reply box that sends multi-paragraph messages (email, support replies) is this one with sendOn="mod-enter".
 - Don't: Do not override the field's type utility to make it match your transcript. The field and `Bubble` both read the same tier already, which is what stops a message changing size the moment it is sent — overriding one breaks that pairing.
 - Don't: Do not remove the height cap to let the field grow without limit. A pasted essay would push the conversation off the screen; past the cap it scrolls.
@@ -39,9 +41,10 @@ Pairs with MessageScroller to make a working chat. A single surface rather than
 | value | string | — | Controlled value. Omit for an uncontrolled composer that owns its own text. |
 | defaultValue | string | "" | Initial value when uncontrolled. |
 | onValueChange | (value: string) => void | — | Notified on every keystroke. Required when `value` is supplied. |
-| onSend | (value: string) => void | — | Called with the trimmed message. An uncontrolled composer clears itself afterwards; a controlled one is the caller's to clear. |
+| onSend | (value: string) => void | — | Called with the trimmed message. An uncontrolled composer clears itself afterwards; a controlled one is the caller's to clear. With `allowEmpty` the message can be `""`. |
+| allowEmpty | boolean | false | Let the reader send with no text, because the app has something else to send (pending attachments). Pass it only while that is true, `allowEmpty={files.length > 0}`; `onSend` then receives `""`. |
 | placeholder | string | "Send a message…" | Placeholder for the field. |
-| sendOn | "enter" \| "mod-enter" | "enter" | Which key sends. enter for chat (Shift+Enter breaks the line). mod-enter for long-form replies such as an email or a support answer: Enter breaks the line and Cmd/Ctrl+Enter sends, so a paragraph break never mails a draft. Say so in footer ("Cmd+Enter to send"). |
+| sendOn | "enter" \| "mod-enter" | "enter" | Which key sends. enter for chat (Shift+Enter breaks the line). mod-enter for long-form replies such as an email or a support answer: Enter breaks the line and Cmd/Ctrl+Enter sends, so a paragraph break never mails a draft. Say so in footer ("Cmd+Enter to send"). On a touch device (pointer: coarse) enter behaves as mod-enter: a soft keyboard has no Shift+Return, so Return breaks the line and the send button sends. |
 | busy | boolean | false | A reply is streaming. Disables send, and swaps it for a stop control when `onStop` is supplied. |
 | onStop | () => void | — | Interrupt the in-flight reply. Supplying it turns send into stop while busy. |
 | disabled | boolean | false | Block sending entirely — over a limit, disconnected, read-only thread. Distinct from `busy`, which is temporary and offers a way out (stop). |
@@ -53,8 +56,8 @@ Pairs with MessageScroller to make a working chat. A single surface rather than
 | label | string | "Message" | Accessible label for the field. |
 | sendLabel | string | "Send message" | Accessible label for the send button. |
 | stopLabel | string | "Stop generating" | Accessible label for the stop button. |
-| footer | ReactNode | — | Helper text or counter below the controls. |
-| fieldRef | Ref<HTMLTextAreaElement> | — | Ref to the underlying textarea — for focusing after a send, or on mount. |
+| footer | ReactNode \| ((state: { sendOn: "enter" \| "mod-enter" }) => ReactNode) | — | Helper text or counter below the controls. For a keyboard hint pass a function: it receives the send key in effect (touch turns `enter` into `mod-enter`), and returning null removes the row, e.g. `footer={({ sendOn }) => sendOn === "enter" ? "Enter to send" : null}`. |
+| fieldRef | Ref<HTMLTextAreaElement> | — | Ref to the underlying textarea — for focusing after a send, or on mount, and the extension point for anything that listens to the field. Pass `useCaretTrigger`'s `fieldRef` here for mentions and slash commands (CaretMenu). An Enter another listener already handled (`preventDefault()`) does not send. |
 | ...form props | Omit<ComponentPropsWithRef<"form">, "onSubmit" \| "defaultValue"> | — | Spread onto the form element. Use `onSend` rather than `onSubmit`. |
 
 ## Variants
@@ -70,7 +73,8 @@ Pairs with MessageScroller to make a working chat. A single surface rather than
 - A real `<form>`, so the send button is a submit button and the whole thing behaves as one control to assistive tech and to password managers alike.
 - Enter never submits while an IME composition is open (`isComposing`), so a CJK reader confirming a candidate word does not mail a fragment of their first sentence.
 - The focus ring is drawn on the surface via `focus-within`, not on the textarea, so the visible focus indicator matches the box a sighted user perceives as the input.
-- Send is disabled — not merely styled down — until there is non-whitespace to send, so the affordance and the behaviour agree for keyboard users.
+- Send is disabled — not merely styled down — until there is non-whitespace to send (or `allowEmpty` says an attachment is enough), so the affordance and the behaviour agree for keyboard users.
+- On a touch device Return breaks the line and the send button sends; `aria-keyshortcuts` reports the shortcut actually in effect (⌘/Ctrl+Enter there, Enter on desktop).
 - Icon-only attach, send and stop buttons all carry accessible labels, each overridable for localisation.
 
 ## Related
@@ -112,6 +116,19 @@ import { Attachment, Button, ChatComposer, Icon } from "@sableui/react"
 />
 ```
 
+### Attachments sent without text
+
+```tsx
+import { Attachment, ChatComposer } from "@sableui/react"
+
+<ChatComposer
+	onSend={(text) => post(text, files)}
+	allowEmpty={files.length > 0}
+	onAttach={pickFile}
+	attachments={files.map((f) => <Attachment key={f.id} name={f.name} meta={f.size} />)}
+/>
+```
+
 ### A working chat, end to end
 
 ```tsx

package/llms/components/combobox.md

@@ -14,6 +14,7 @@ Use Combobox when users choose from a list that benefits from typing, filtering,
 
 - Do: Pass items so internal filtering, empty state, and accessibility wiring have the full option set.
 - Do: Use ComboboxEmpty with helpful copy for zero matches.
+- Do: For results from a server, pass `filter={null}` so Base UI shows the items as the server returned them, fetch from `onInputValueChange`, and make ComboboxEmpty say which state it is in (searching, no results, type to search). Object items take `itemToStringLabel`.
 - Do: Wrap in Field when the combobox is part of a form.
 - Do: Reach for ComboboxVirtualList past roughly a thousand rows, and leave filtering to the root. It reads the filtered list through useFilteredItems(), so the rendered rows and the rows Base UI navigates cannot drift apart.
 - Do: Use `multiple` with ComboboxChips for several values from a filterable set, and keep chip labels short so the field does not turn into a paragraph.
@@ -54,6 +55,9 @@ Use Combobox when users choose from a list that benefits from typing, filtering,
 | Combobox (Root) | Base UI Combobox.Root props (items, value, defaultValue, onValueChange, inputValue, onInputValueChange, open, onOpenChange, multiple, autoHighlight, filter, disabled) | — | Groups all parts and owns selection + filter state. Pass `items` (flat array or groups) to enable internal filtering and ComboboxEmpty. |
 | items | readonly any[] \| readonly ComboboxItemGroup[] | — | The pool of options, flat or grouped ({ value, items }). Drives type-to-filter and is required for ComboboxEmpty to render its fallback. |
 | multiple | boolean | false | Select several items instead of one. `value` / `defaultValue` / `onValueChange` become arrays, choosing an item toggles its membership, and the popup stays open between picks. Pair it with ComboboxChips in place of ComboboxInput; every other part is unchanged. |
+| filter | null \| ((item, query, itemToString?) => boolean) | Base UI's locale-aware contains | How items match the query. `null` turns matching off, for items a server already filtered: pair it with `onInputValueChange` to fetch. |
+| onInputValueChange | (inputValue: string, eventDetails) => void | — | Fires as the reader types. The place to fetch results for a server-backed combobox. |
+| itemToStringLabel | (item) => string | item.label for { value, label } items | The text an object item shows in the input once chosen, and is matched by. Needed for object items without a `label` field. |
 | virtualized | boolean | false | Tells Base UI the DOM holds only part of the list. Required when using ComboboxVirtualList. |
 
 ## Tokens used
@@ -102,6 +106,14 @@ import { Combobox, ComboboxChips, ComboboxContent, ComboboxEmpty, ComboboxItem,
 <Combobox multiple items={tags} value={value} onValueChange={setValue}><ComboboxChips placeholder="Add tags…" /><ComboboxContent><ComboboxEmpty>No matching tags.</ComboboxEmpty><ComboboxList>{(item) => (<ComboboxItem key={item} value={item}>{item}</ComboboxItem>)}</ComboboxList></ComboboxContent></Combobox>
 ```
 
+### Async search (server results)
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxList } from "@sableui/react"
+
+<Combobox items={results} filter={null} itemToStringLabel={(person) => person.name} value={person} onValueChange={setPerson} onInputValueChange={setQuery}><ComboboxInput placeholder="Search people…" /><ComboboxContent><ComboboxEmpty>{searching ? "Searching…" : query ? "No one matches." : "Type a name to search."}</ComboboxEmpty><ComboboxList>{(item) => (<ComboboxItem key={item.id} value={item}>{item.name}</ComboboxItem>)}</ComboboxList></ComboboxContent></Combobox>
+```
+
 ### Virtualized (long list)
 
 ```tsx

package/llms/components/input-group.md

@@ -0,0 +1,78 @@
+# InputGroup
+
+**Status:** stable
+
+An Input with addons inside the same field: a prefix or suffix ("https://", ".com", "$"), an icon, or a borderless Button such as copy or reveal. One shell, one focus ring, one error state; a Field's label and error wiring reaches the Input inside.
+
+**Keywords:** input group, input addon, prefix, suffix, adornment, url input, currency input, password reveal, copy field, icon in input
+
+## Usage
+
+Use InputGroup when something belongs inside the field with the text: a unit, a fixed prefix, an icon, or a small action on the value itself (copy, reveal, clear). Use Field's `trailing` for an action beside the field (Apply next to a promo code), SearchInput for search, and NumberField for numbers with steppers.
+
+### Best practices
+
+- Do: Keep text addons short and fixed ("https://", "kg", "USD"). They are part of the field, not its label.
+- Do: For a button addon, use a borderless Button (`variant="ghost"`, `size="icon-sm"`) with an aria-label. The addon tightens around it, so it sits as far from the edge as from the top and bottom.
+- Do: Wrap the group in Field for a label and errors: `<Field label="Website"><InputGroup leading="https://"><Input /></InputGroup></Field>`.
+- Don't: Do not put the value's meaning only in an addon. A screen reader hears the label and the text, so "Price (USD)" belongs in the label too.
+- Don't: Do not restyle an Input to fake an addon; the group owns the border, the fill and the ring.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| leading | ReactNode | — | Inside the field, before the text: a prefix ("https://", "$"), an icon, or a borderless Button. |
+| trailing | ReactNode | — | Inside the field, after the text: a suffix (".com", "kg"), an icon, or a borderless Button (copy, reveal, clear). |
+| children | ReactElement | — | The single `<Input />`. It keeps its own props and type; the group takes over its border, fill and focus ring. |
+| id / required / disabled / aria-describedby / aria-invalid | control props | — | Forwarded to the Input, not set on the group. This is how a Field's wiring reaches the text box when the group is its child. |
+| className | string | — | Layout classes for the group (width, margins). |
+
+## Tokens used
+
+`input`, `card`, `ring`, `destructive`, `muted-foreground`, `foreground`
+
+## Accessibility
+
+- The Input stays the focusable control; the group draws the focus ring around the whole field while it is focused.
+- Inside a Field, the label, description and error are wired to the Input itself, not the group.
+- Text addons are plain text beside the input, read in order; put a unit or currency in the label as well so it is not only visual.
+- A button addon is a real Button with its own focus stop and needs an aria-label.
+
+## Related
+
+- Components: Input, Field, SearchInput, NumberField, Button
+
+## Examples
+
+### Prefix and suffix
+
+```tsx
+import { Field, Input, InputGroup } from "@sableui/react"
+
+<Field label="Website"><InputGroup leading="https://" trailing=".com"><Input placeholder="example" /></InputGroup></Field>
+```
+
+### Leading icon
+
+```tsx
+import { Field, Icon, Input, InputGroup } from "@sableui/react"
+
+<Field label="Email"><InputGroup leading={<Icon name="mail" />}><Input type="email" placeholder="you@example.com" /></InputGroup></Field>
+```
+
+### Copy button
+
+```tsx
+import { Button, Field, Icon, Input, InputGroup } from "@sableui/react"
+
+<Field label="API key"><InputGroup trailing={<Button variant="ghost" size="icon-sm" aria-label="Copy key" onClick={copy}><Icon name={copied ? "check" : "copy"} /></Button>}><Input readOnly value={key} /></InputGroup></Field>
+```
+
+### Password with reveal
+
+```tsx
+import { Button, Field, Icon, Input, InputGroup } from "@sableui/react"
+
+<Field label="Password"><InputGroup trailing={<Button variant="ghost" size="icon-sm" aria-label={shown ? "Hide password" : "Show password"} aria-pressed={shown} onClick={() => setShown(!shown)}><Icon name={shown ? "eye-off" : "eye"} /></Button>}><Input type={shown ? "text" : "password"} autoComplete="current-password" /></InputGroup></Field>
+```

package/llms/components/menu.md

@@ -35,7 +35,8 @@ Use Menu for a compact list of actions opened from a visible trigger.
 | --- | --- | --- |
 | MenuTrigger | Base UI Menu.Trigger props + render | The button that opens the menu. Compose with render={<Button … />}. |
 | MenuContent | Base UI Popup props + side: 'top' \| 'right' \| 'bottom' \| 'left' + align: 'start' \| 'center' \| 'end' + sideOffset: number + className | Portal + Positioner + Popup. side picks which side of the trigger the popup renders against (auto-flips on collision; defaults to 'bottom'); align sets alignment along that side (defaults to 'start'); sideOffset is the gap in px between trigger and popup (defaults to 6). |
-| MenuItem | Base UI Menu.Item props + className (disabled, closeOnClick, onClick) + variant?: "default" \| "destructive" | An interactive row. Highlights via data-[highlighted]; dims via data-[disabled]. variant="destructive" for a delete or irreversible action: it keeps the destructive ink when highlighted (never className="text-destructive", which the highlight repaints). |
+| MenuItem | Base UI Menu.Item props + className (disabled, closeOnClick, onClick) + variant?: "default" \| "destructive" + icon?: ReactNode + description?: ReactNode | An interactive row. Highlights via data-[highlighted]; dims via data-[disabled]. variant="destructive" for a delete or irreversible action: it keeps the destructive ink when highlighted (never className="text-destructive", which the highlight repaints). `icon` leads the row; `description` adds a quieter second line saying what the action does, and the icon then sits in a small tile spanning both lines. |
+| MenuLinkItem | Base UI Menu.LinkItem props (href, target, closeOnClick) + className + icon?: ReactNode + description?: ReactNode | A row that navigates: a real <a>, so it opens in a new tab, middle-clicks and copies as a link. With target="_blank" it adds rel="noopener noreferrer" and a trailing ↗. Takes icon and description like MenuItem. |
 | MenuSeparator | Base UI Separator props + className | Hairline rule between item runs. |
 | MenuSubmenu | Base UI Menu.SubmenuRoot props | A nested menu. Wraps a MenuSubmenuTrigger and its own MenuContent — pass side="inline-end" to that content so the submenu opens away from its parent in RTL as well as LTR. |
 | MenuSubmenuTrigger | Base UI Menu.SubmenuTrigger props + value: ReactNode + className | The row that opens a submenu: item styling, a trailing chevron, and an optional `value` showing the current choice so the row reads "Effort  High ›" rather than making the reader open it to find out. |
@@ -107,6 +108,20 @@ import { Button, Menu, MenuContent, MenuItem, MenuRadioGroup, MenuRadioItem, Men
 </Menu>
 ```
 
+### Rows with icons and descriptions, and links
+
+```tsx
+import { Button, Icon, Menu, MenuContent, MenuItem, MenuLinkItem, MenuTrigger } from "@sableui/react"
+
+<Menu>
+	<MenuTrigger render={<Button variant="outline" size="sm">Share</Button>} />
+	<MenuContent align="end">
+		<MenuItem icon={<Icon name="copy" />} description="Copy page as Markdown for LLMs" onClick={copy}>Copy page</MenuItem>
+		<MenuLinkItem icon={<Icon name="file" />} description="View this page as plain text" href={markdownUrl} target="_blank">View as Markdown</MenuLinkItem>
+	</MenuContent>
+</Menu>
+```
+
 ### Toggling rows
 
 ```tsx

package/llms/components/menubar.md

@@ -0,0 +1,110 @@
+# Menubar
+
+**Status:** stable
+
+An application's row of menus — File, Edit, View — over Base UI's Menubar. Each menu is an ordinary Sable Menu with a MenubarTrigger as its title; the bar joins them into one tab stop with ←/→ between titles, and once one menu is open, pointing at a neighbour opens it.
+
+**Keywords:** menubar, menu bar, app menu, file menu, edit menu, application menu, desktop menu
+
+## Usage
+
+Use Menubar for a tool or editor whose commands are too many for a toolbar and belong under named menus (File, Edit, View, Help). Use Toolbar for a row of direct actions, a single Menu or OverflowMenu for one set of options, and NavigationMenu-style links for site navigation.
+
+### Best practices
+
+- Do: Compose each menu from the Menu parts: `<Menu><MenubarTrigger>File</MenubarTrigger><MenuContent>…</MenuContent></Menu>`. Rows, groups, submenus, checkbox and radio items are the same parts a lone Menu uses.
+- Do: Name the bar with aria-label ("Editor") so it is announced as the application's menus, not a list of buttons.
+- Do: Keep titles to one short word each. A reader scans a menubar left to right; a phrase in the bar is a toolbar button.
+- Don't: Do not use MenubarTrigger outside a Menubar, or a plain MenuTrigger inside one. The bar's arrow keys and hover-to-switch work on the triggers it owns; a Button trigger in the bar looks like a menu title and behaves like a stray button.
+- Don't: Do not use a menubar for site navigation. Its items are commands in menus (role=menuitem), not links between pages.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Menubar | yes | The bar: role=menubar, one tab stop, arrow keys between titles. |
+| Menu | yes | One per title; the ordinary Menu root. |
+| MenubarTrigger | yes | The title in the bar that opens its menu. |
+| MenuContent | yes | The menu's popup, with MenuItem / MenuSubmenu / MenuCheckboxItem rows inside. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| MenubarTrigger | Base UI Menu.Trigger props + className | A menu's title in the bar. A small ghost Button in the control type tier, held in the accent wash while its menu is open (`sable-open:`), so the reader sees which title the popup belongs to. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| orientation | "horizontal" \| "vertical" | "horizontal" | The bar's axis. Arrow keys follow it: ←/→ along a horizontal bar, ↑/↓ down a vertical one. |
+| loopFocus | boolean | true | Wrap from the last title back to the first with the arrow keys. |
+| modal | boolean | true | While a menu is open, block pointer interaction outside it and lock page scroll, like a lone Menu. |
+| disabled | boolean | false | Disable every menu in the bar. |
+| className | string | — | Layout classes for the bar. Titles take their look from MenubarTrigger. |
+
+## Tokens used
+
+`accent`, `accent-foreground`, `foreground`, `ring`
+
+## Accessibility
+
+- Base UI renders role="menubar" with aria-orientation; each title is a menuitem with aria-haspopup and aria-expanded.
+- The bar is one tab stop. ←/→ move between titles (↑/↓ when vertical), ↓ or Enter opens a menu and moves into it, and Esc closes it and returns focus to its title.
+- With one menu open, pointing at another title opens that menu instead, so a reader can sweep across the bar, as in a desktop application.
+- Name the bar with aria-label; titles are their own text.
+
+## Related
+
+- Components: Menu, Toolbar, OverflowMenu, ContextMenu
+
+## Examples
+
+### Editor menus
+
+```tsx
+import { Menu, Menubar, MenubarTrigger, MenuContent, MenuItem, MenuSeparator } from "@sableui/react"
+
+<Menubar aria-label="Editor">
+	<Menu>
+		<MenubarTrigger>File</MenubarTrigger>
+		<MenuContent>
+			<MenuItem>New</MenuItem>
+			<MenuItem>Open…</MenuItem>
+			<MenuSeparator />
+			<MenuItem>Save</MenuItem>
+		</MenuContent>
+	</Menu>
+	<Menu>
+		<MenubarTrigger>Edit</MenubarTrigger>
+		<MenuContent>
+			<MenuItem>Undo</MenuItem>
+			<MenuItem>Redo</MenuItem>
+		</MenuContent>
+	</Menu>
+</Menubar>
+```
+
+### With a submenu and toggling rows
+
+```tsx
+import { Menu, Menubar, MenubarTrigger, MenuCheckboxItem, MenuContent, MenuRadioGroup, MenuRadioItem, MenuSubmenu, MenuSubmenuTrigger } from "@sableui/react"
+
+<Menubar aria-label="Editor">
+	<Menu>
+		<MenubarTrigger>View</MenubarTrigger>
+		<MenuContent>
+			<MenuCheckboxItem checked={ruler} onCheckedChange={setRuler}>Show ruler</MenuCheckboxItem>
+			<MenuSubmenu>
+				<MenuSubmenuTrigger value={zoom}>Zoom</MenuSubmenuTrigger>
+				<MenuContent side="inline-end" align="start" sideOffset={4}>
+					<MenuRadioGroup value={zoom} onValueChange={setZoom}>
+						<MenuRadioItem value="100%">100%</MenuRadioItem>
+						<MenuRadioItem value="Fit">Fit</MenuRadioItem>
+					</MenuRadioGroup>
+				</MenuContent>
+			</MenuSubmenu>
+		</MenuContent>
+	</Menu>
+</Menubar>
+```

package/llms/components/message-scroller.md

@@ -12,6 +12,7 @@ The scroll region a conversation lives in. It owns the scrolling and nothing els
 
 ### Best practices
 
+- Do: Building a whole chat? `sable docs building-a-chat` covers what the scroller does during a stream, what the app owns, and the failure states around it.
 - Do: Bound it the way you would bound any scroll box — `flex-1 min-h-0` inside a flex column, or `max-h-96`. `className` lands on the element that actually scrolls, so the obvious bound is the correct one (same contract as Scroller).
 - Do: Give every Message a `messageId`. It is the handle for `scrollToMessage`, `initialScroll`, and `onVisibleMessagesChange` — a message without one is invisible to all three.
 - Do: Prepend older history directly into `children` when the reader reaches the top. The scroller anchors on the first rendered message and re-adds the height that appeared above it, so the view does not jump.