@sableui/react 0.10.0 → 0.12.0

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.

package/llms/components/navigation-menu.md

@@ -0,0 +1,113 @@
+# NavigationMenu
+
+**Status:** stable
+
+A site header's primary nav over Base UI NavigationMenu: a bar of links and triggers, where a trigger opens a panel of links on hover, click or Enter. One shared panel glides between triggers and resizes to each one's content. Links take any router's link through `render` and mark the current page with `active`.
+
+**Keywords:** navigation, nav, header nav, site nav, mega menu, top nav, navbar, dropdown nav
+
+## Usage
+
+Use NavigationMenu for a marketing or docs site's header: a few top-level destinations, some of which open a panel of related pages. Use Menu for actions rather than destinations, Tabs to switch views inside a page, Sidebar or SideNav for an app's persistent navigation, and AppHeader for an app's mobile top bar.
+
+### Best practices
+
+- Do: Keep the bar to a handful of entries. A trigger groups related pages; a destination with nothing beneath it is a plain NavigationMenuLink in its own item.
+- Do: Give panel links a `description` when titles alone are ambiguous ("Sync" → "Offline first, conflict free"), and lay the Content out with layout classes (`grid w-[30rem] grid-cols-2`); the shared panel sizes itself to it.
+- Do: Pass your router's link through `render` (`<NavigationMenuLink render={<Link to="/pricing" />}>`) and set `active` on the current page's link, so the bar shows where the reader is and announces it as `aria-current="page"`.
+- Do: Below `md`, hide the bar and offer the same destinations in a Sheet opened from a menu Button: SheetContent side="left" holding a SideNav, its groups mirroring the panels. A hover panel has nothing to hover on a phone, and a bar of five entries does not fit one.
+- Don't: Do not put actions in it (Sign in, New project). Those are Buttons beside the nav; the nav holds places to go.
+- Don't: Do not assemble the panel yourself. The root renders the one Portal, Positioner, Popup and Viewport every trigger shares; a second one breaks the glide between triggers.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| NavigationMenu | yes | The `<nav>` root; also renders the shared floating panel. |
+| NavigationMenuList | yes | The bar: a `<ul>` the arrow keys rove across. |
+| NavigationMenuItem | yes | One `<li>`: a link, or a trigger with its content. |
+| NavigationMenuTrigger | no | Opens its item's content; carries a chevron. |
+| NavigationMenuContent | no | The links a trigger reveals, rendered into the shared panel. |
+| NavigationMenuLink | yes | A destination: a bar entry in an item, a two-line row in content. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| NavigationMenuList | Base UI NavigationMenu.List props + className | The bar of items, a `<ul>`. Arrow keys move between entries. |
+| NavigationMenuItem | Base UI NavigationMenu.Item props + className + value?: string | One `<li>` holding either a NavigationMenuLink or a NavigationMenuTrigger with its NavigationMenuContent. |
+| NavigationMenuTrigger | Base UI NavigationMenu.Trigger props + className | Opens its item's content on hover, click or Enter, with a chevron that turns while open. Styled like the bar's links: muted at rest, full ink when hovered or open. |
+| NavigationMenuContent | Base UI NavigationMenu.Content props + className + keepMounted?: boolean | The item's panel content. Size and lay it out with layout classes; the shared panel follows its size and slides it in from the side it was reached from. |
+| NavigationMenuLink | Base UI NavigationMenu.Link props + className + href?: string + active?: boolean + closeOnClick?: boolean + render?: ReactElement + description?: ReactNode | A destination. In an item it is a bar entry; in content it is a row with an optional `description` line. `active` sets `aria-current="page"`; `render={<Link to="…" />}` keeps the roving focus on your router's link. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| NavigationMenu (Root) | Base UI NavigationMenu.Root props (value, defaultValue, onValueChange, delay, closeDelay, orientation) + className | — | The `<nav>`. `value` is the open item's value (null when closed); `delay` / `closeDelay` tune hover-to-open. |
+| align | "start" \| "center" \| "end" | "start" | Alignment of the shared panel along its trigger. |
+| sideOffset | number | 8 | Gap between the bar and the panel, in px. The pointer crosses it on a bridge, so the panel does not close on the way in. |
+
+## Tokens used
+
+`popover`, `popover-foreground`, `border-floating`, `accent`, `accent-foreground`, `muted-foreground`, `foreground`, `ring`
+
+## Motion
+
+- **arrival** · Panel · _custom (outside the recipe layer)_ — The panel fades and scales in from its trigger like a popover, but it also resizes as the reader moves between triggers, which motion-pop cannot express: Base UI measures each content into --popup-width/--popup-height and the popup transitions to them on the motion tokens.
+- **response** · Trigger, Link · `motion-interactive` — Bar entries and panel rows fill on hover and focus like the other interactive surfaces, so the bar reads as live before anything opens.
+- **transition** · Panel · _custom (outside the recipe layer)_ — Moving from one trigger to the next keeps one panel open: it glides along the bar and the new content slides in from the direction of travel, so the reader sees one surface changing rather than two popups swapping. Snaps on first open and on resize (data-instant), where a glide would mean nothing.
+- **activity** · root · _no motion_ — Nothing in a nav moves on its own.
+
+## Accessibility
+
+- The root is a <nav>; give it an aria-label when the page has more than one nav ("Main").
+- Arrow keys move across the bar; Enter, Space or ArrowDown opens a trigger's content and moves focus into it; Esc closes and returns focus to the trigger.
+- A trigger is a button with aria-expanded; its content is reachable by Tab in reading order once open.
+- `active` on a link sets aria-current="page" and gives it full ink, so the current page is announced as well as shown.
+- Panel motion runs on the motion tokens, so reduced motion (or MotionProvider "reduced") collapses the glide and resize to instant.
+
+## Related
+
+- Components: Menu, SideNav, Sheet, AppHeader, Tabs
+
+## Examples
+
+### Bar with a panel
+
+```tsx
+import { NavigationMenu, NavigationMenuContent, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger } from "@sableui/react"
+
+<NavigationMenu aria-label="Main">
+	<NavigationMenuList>
+		<NavigationMenuItem>
+			<NavigationMenuTrigger>Product</NavigationMenuTrigger>
+			<NavigationMenuContent className="grid w-[30rem] grid-cols-2">
+				<NavigationMenuLink href="/editor" description="Write and review together.">Editor</NavigationMenuLink>
+				<NavigationMenuLink href="/sync" description="Offline first, conflict free.">Sync</NavigationMenuLink>
+			</NavigationMenuContent>
+		</NavigationMenuItem>
+		<NavigationMenuItem>
+			<NavigationMenuLink href="/pricing">Pricing</NavigationMenuLink>
+		</NavigationMenuItem>
+	</NavigationMenuList>
+</NavigationMenu>
+```
+
+### With a router, marking the current page
+
+```tsx
+import { NavigationMenu, NavigationMenuItem, NavigationMenuLink, NavigationMenuList } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+<NavigationMenu aria-label="Main">
+	<NavigationMenuList>
+		<NavigationMenuItem>
+			<NavigationMenuLink active={path === "/docs"} render={<Link to="/docs" />}>Docs</NavigationMenuLink>
+		</NavigationMenuItem>
+		<NavigationMenuItem>
+			<NavigationMenuLink active={path === "/blog"} render={<Link to="/blog" />}>Blog</NavigationMenuLink>
+		</NavigationMenuItem>
+	</NavigationMenuList>
+</NavigationMenu>
+```

package/llms/components/overflow-menu.md

@@ -4,7 +4,7 @@
 
 An overflow ellipsis icon button that opens a Menu. Composes our Menu + Button + Icon — pass MenuItems as children and it wires the ghost icon trigger, accessible label, and portal-rendered content. All keyboard, focus, and dismissal behavior comes through Menu.
 
-**Keywords:** dots menu, more actions, ellipsis, kebab
+**Keywords:** dots menu, more actions, ellipsis, kebab, responsive actions, responsive action menu, collapse actions, actions overflow on mobile
 
 ## Usage
 
@@ -14,6 +14,7 @@ Use OverflowMenu for compact overflow actions when the primary action is already
 
 - Do: Use it for secondary commands that belong to a row, card, or toolbar item.
 - Do: Keep labels explicit so the icon-only trigger does not obscure the command meaning.
+- Do: For actions that fit inline on a wide screen but not a narrow one, render them twice: inline (a Row inside a wrapper shown from a container width; Row sets its own display, so the wrapper does the hiding), and as MenuItems in an OverflowMenu hidden from that width (`@container` + `@md:`). display:none takes the hidden copy out of the accessibility tree, so only one set is ever announced. Keep the primary action inline at every width.
 - Don't: Do not hide the most important or most frequent action inside OverflowMenu.
 - Don't: Do not use it as the only affordance on a touch surface. It is revealed on hover in most layouts, and hover does not exist on touch — pair it with a visible action or make it always-visible there.
 
@@ -62,3 +63,27 @@ import { Icon, MenuItem, MenuSeparator, OverflowMenu } from "@sableui/react"
 
 <OverflowMenu><MenuItem><Icon name="check" className="text-sm" />Mark as read</MenuItem><MenuSeparator /><MenuItem variant="destructive"><Icon name="xmark" className="text-sm" />Delete</MenuItem></OverflowMenu>
 ```
+
+### Responsive actions: inline when wide, in a menu when narrow
+
+```tsx
+import { Button, Icon, MenuItem, OverflowMenu, Row } from "@sableui/react"
+
+<div className="@container/actions flex w-full justify-end">
+	<Row gap={1} align="center">
+		<div className="hidden @md/actions:block">
+			<Row gap={1}>
+				<Button variant="ghost" size="sm" iconStart={<Icon name="share" />}>Share</Button>
+				<Button variant="ghost" size="sm" iconStart={<Icon name="download" />}>Export</Button>
+			</Row>
+		</div>
+		<div className="@md/actions:hidden">
+			<OverflowMenu label="Report actions" size="icon-sm">
+				<MenuItem icon={<Icon name="share" />}>Share</MenuItem>
+				<MenuItem icon={<Icon name="download" />}>Export</MenuItem>
+			</OverflowMenu>
+		</div>
+		<Button size="sm" iconStart={<Icon name="edit" />}>Edit report</Button>
+	</Row>
+</div>
+```