@sableui/react 0.0.0-stage → 0.1.1

package/llms/components/code-block.md

@@ -0,0 +1,81 @@
+# CodeBlock
+
+**Status:** stable
+
+Multi-line code surface. Optional header bar carries a filename and a copy affordance; the body is a horizontally scrollable monospace pre. Syntax highlighting is opt-in: pass a highlighter per block or once via CodeHighlightProvider (the package ships none).
+
+**Keywords:** code block, snippet, pre, example
+
+## Usage
+
+Use CodeBlock for multiline code samples that users may read, inspect, or copy.
+
+### Best practices
+
+- Do: Give the snippet a filename, or a sentence of surrounding copy, when it helps readers and agents place it.
+- Do: Keep examples complete enough to teach the intended pattern.
+- Do: Wire highlighting once with CodeHighlightProvider and map token colors to semantic tone tokens (keywords → tone-edition, strings → success, comments → muted-foreground), so code follows the theme instead of a fixed palette.
+- Don't: Do not put short inline identifiers in a CodeBlock; use Code for those.
+- Don't: Do not paste code with the indentation the surrounding file had. A block indented to sit inside your JSX shows the reader leading whitespace that is not part of the example.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| CodeBlock | yes | The surface: optional filename header, copy affordance, scrollable pre. |
+| CodeHighlightProvider | no | Optional app-level wrapper that supplies one highlighter to every CodeBlock inside it. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| CodeHighlightProvider | { highlight: (code: string) => ReactNode; children: ReactNode } | Supplies one highlighter to every CodeBlock beneath it, so an app wires highlighting once. Map the highlighter's token colors to Sable tone tokens so code follows the theme. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| code | string | — | The code to display. Always what the copy button copies, whatever the highlighter renders. |
+| filename | string | — | Optional filename shown in the header bar. |
+| showCopy | boolean | true | Show the copy affordance — in the header bar with a filename, floating in the corner without one. |
+| highlight | ((code: string) => ReactNode) \| false | — | Highlighter for this block; overrides CodeHighlightProvider. false renders plain text inside a provider. |
+| prompt | string | — | A shell prompt ("$", ">"). Makes it a one-line command: the prompt is dimmed and unselectable, the line truncates, and copy takes only code. |
+
+## Tokens used
+
+`border`, `muted`, `muted-foreground`, `foreground`
+
+## Accessibility
+
+- Code renders inside a <pre><code> for correct semantics and screen-reader handling.
+- Copy is the ghost icon Button with `useCopy`, which guards clipboard access for SSR safety.
+
+## Related
+
+- Components: Code
+
+## Examples
+
+### With filename + copy
+
+```tsx
+import { CodeBlock } from "@sableui/react"
+
+<CodeBlock filename="cn.ts" code={"import { clsx } from \"clsx\"\nexport const cn = clsx"} />
+```
+
+### With a highlighter for the whole app
+
+```tsx
+import { CodeBlock, CodeHighlightProvider } from "@sableui/react"
+
+<CodeHighlightProvider highlight={(code) => <span dangerouslySetInnerHTML={{ __html: highlightToHtml(code) }} />}><CodeBlock code={"const a = 1"} /></CodeHighlightProvider>
+```
+
+### No header
+
+```tsx
+import { CodeBlock } from "@sableui/react"
+
+<CodeBlock showCopy={false} code={"type Size = \"sm\" | \"md\"\nconst size: Size = \"md\""} />
+```

package/llms/components/code.md

@@ -0,0 +1,62 @@
+# Code
+
+**Status:** stable
+
+Inline code. A styled `<code>` for code spans, keys, and identifiers inside running text — soft muted fill, monospace.
+
+**Keywords:** code, inline code, token, monospace
+
+## Usage
+
+Use Code for short inline identifiers, commands, tokens, props, and file names inside prose.
+
+### Best practices
+
+- Do: Use it for brief technical literals that need to stand apart from body copy.
+- Do: Keep inline code short enough that it does not dominate the paragraph.
+- Don't: Do not use Code for multiline snippets; use CodeBlock instead.
+- Don't: Do not put a value the reader needs to copy inside it. Code has no copy affordance, so they will select it by hand and catch the surrounding punctuation; use CodeBlock with a prompt.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| ...props | ComponentPropsWithRef<"code"> | — | All native `<code>` attributes (children, className, ref, …) pass through. |
+
+## Tokens used
+
+`muted`, `foreground`
+
+## Accessibility
+
+- Renders a semantic `<code>` element so assistive tech announces it as code.
+- A `<code>` element is not announced distinctly by most screen readers — a code span in running prose is read as ordinary text. Where the exactness matters (a command to type verbatim, a case-sensitive identifier), say so in the sentence rather than relying on the styling to carry it.
+
+## Related
+
+- Components: CodeBlock, Kbd
+
+## Examples
+
+### Inline
+
+```tsx
+import { Code } from "@sableui/react"
+
+Run <Code>pnpm dev</Code> to start the server.
+```
+
+### Code vs CodeBlock
+
+```tsx
+import { Code, CodeBlock } from "@sableui/react"
+
+// Picking the wrong one is the usual mistake:
+//
+//   Code                   inline, inside a sentence       → `useState`
+//   CodeBlock              multi-line, read-only           → an example to study
+//   CodeBlock prompt="$"   one line, meant to be COPIED    → an install command
+
+Install with <Code>pnpm add @sableui/react</Code>          {/* ✗ they will want to copy it */}
+<CodeBlock prompt="$" code="pnpm add @sableui/react" />   {/* ✓ one line, with a copy button */}
+```

package/llms/components/collapsible.md

@@ -0,0 +1,83 @@
+# Collapsible
+
+**Status:** stable
+
+Show/hide a panel of content over Base UI Collapsible — open/close state, ARIA expanded wiring, and the animated height transition. The minimal primitive behind Accordion: a trigger that toggles an overflow-clipped panel.
+
+**Keywords:** collapsible, disclosure, expand, collapse
+
+## Usage
+
+Use Collapsible for a single piece of optional content that can expand in place.
+
+### Best practices
+
+- Do: Use it for local detail, advanced settings, or secondary context.
+- Do: Make the trigger label describe the hidden content, not the mechanism.
+- Don't: Do not use Collapsible for multi-section navigation; use Accordion or Tabs instead.
+- Don't: Do not animate it by transitioning height from auto. Use the motion-disclosure recipe, which transitions to the measured panel height — `auto` does not animate and the panel will snap.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| CollapsibleTrigger | yes | The control that toggles the panel. |
+| CollapsiblePanel | yes | The content that expands or collapses. |
+| CollapsibleIndicator | no | A visual affordance for open or closed state. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| CollapsibleTrigger | Base UI Collapsible.Trigger props + render | The button that toggles the panel. Compose with render={<Button variant="ghost" … />}. |
+| CollapsiblePanel | Base UI Collapsible.Panel props + className (keepMounted, hiddenUntilFound) | The collapsible contents. Overflow-hidden; animates height via the --collapsible-panel-height var Base UI sets. |
+| CollapsibleIndicator | { className? } | Auto-rotating disclosure chevron. Place it inside the trigger content and add the `group/collapsible` class to the trigger so it flips 180° on open. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| Collapsible (Root) | Base UI Collapsible.Root props (open, defaultOpen, onOpenChange, disabled) | — | Groups the trigger and panel and owns open state. Uncontrolled by default; pass `open` + `onOpenChange` to control it. |
+| defaultOpen | boolean | false | Whether the panel starts open in the uncontrolled case. |
+| disabled | boolean | false | Disables the trigger and prevents toggling. |
+
+## Tokens used
+
+`foreground`, `muted-foreground`
+
+## Accessibility
+
+- Base UI wires aria-expanded on the trigger and aria-controls/id between trigger and panel.
+- Trigger is a real <button>; toggles on click and Enter/Space.
+- Animate open/close via data-[starting-style]/data-[ending-style]; data-[panel-open] marks the open state.
+- Set hiddenUntilFound on the panel to let in-page browser search expand it.
+
+## Related
+
+- Components: Accordion, ShowMore
+
+## Examples
+
+### Basic
+
+```tsx
+import { Button, Collapsible, CollapsiblePanel, CollapsibleTrigger } from "@sableui/react"
+
+<Collapsible><CollapsibleTrigger render={<Button variant="ghost">Details</Button>} /><CollapsiblePanel><p className="pt-3">Hidden content revealed on toggle.</p></CollapsiblePanel></Collapsible>
+```
+
+### Open by default
+
+```tsx
+import { Button, Collapsible, CollapsiblePanel, CollapsibleTrigger } from "@sableui/react"
+
+<Collapsible defaultOpen><CollapsibleTrigger render={<Button variant="ghost">Summary</Button>} /><CollapsiblePanel><p className="pt-3">Visible on first render.</p></CollapsiblePanel></Collapsible>
+```
+
+### With rotating chevron
+
+```tsx
+import { Button, Collapsible, CollapsibleIndicator, CollapsiblePanel, CollapsibleTrigger } from "@sableui/react"
+
+<Collapsible><CollapsibleTrigger className="group/collapsible" render={<Button variant="ghost">Details <CollapsibleIndicator /></Button>} /><CollapsiblePanel><p className="pt-3">Revealed on toggle.</p></CollapsiblePanel></Collapsible>
+```

package/llms/components/color-field.md

@@ -0,0 +1,100 @@
+# ColorField
+
+**Status:** stable
+
+A colour swatch that opens a themed picker — saturation/value area, hue and alpha sliders, hex entry, presets, and transparent as a value rather than a separate toggle.
+
+**Keywords:** color, colour, color picker, swatch, hex, alpha, transparency, eyedropper, property, workspace
+
+## Usage
+
+Use ColorField wherever a colour is a property: a canvas background, an effect parameter, a stroke or fill. It is sized to the control ladder so it lines up inside a PropertyRow or PropertyPair. Deliberately not <input type="color">, which opens the OS dialog — that ignores the theme entirely, cannot show a transparency checkerboard, has no alpha channel, hosts no eyedropper or presets, and renders at whatever size the platform picks, so it never aligns in a property grid.
+
+### Best practices
+
+- Do: Use allowTransparent when "no colour" is a real value. It appears inside the picker as a value; a transparent switch sitting beside a colour control reads as two properties when it is one.
+- Do: Pass swatches when a surface has a house palette. Presets are how most colour choices actually get made, and they cost one row.
+- Do: Decide whether your persistence layer accepts 8-digit hex before enabling allowAlpha. The value format is the contract — see the tokens note.
+- Don't: Put a separate opacity slider next to a ColorField that already has allowAlpha. Two controls writing one channel is how they drift out of sync.
+- Don't: Re-derive hue from the committed value on every render. Grey has no hue, so dragging saturation to zero would snap the hue slider to red with no way back — ColorField keeps hue in its own state for exactly this reason.
+- Don't: Hand-roll a transparency checkerboard. Use the `checkerboard` utility with `--checkerboard-size` (~16px for an artboard, ~8px for a 24px swatch); two hand-rolled copies had already drifted before it existed. Its colours come from --panel / --panel-raised, so it is correct in both modes. It is deliberately not named bg-checkerboard: a custom bg-* utility lands in tailwind-merge's background group and silently evicts, or is evicted by, a real bg-* colour class.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Trigger | yes | A swatch at --control-xs with a hairline ring, on a checkerboard so a translucent or transparent value reads as such. |
+| Picker | yes | Saturation/value area over the current hue, a hue slider, an alpha slider when allowAlpha, and a hex field. |
+| Presets | no | An optional swatch row, and the Transparent entry when allowTransparent. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | string | — | The current value: "transparent", "#rrggbb", or "#rrggbbaa". |
+| onValueChange | (value: string) => void | — | Called with the new value on every commit, including mid-drag. |
+| allowTransparent | boolean | false | Offers "transparent" as a value inside the picker. Colour → transparent → colour restores the colour you had. |
+| allowAlpha | boolean | false | Enables the alpha slider, and therefore 8-digit hex output. Off by default because it widens the value format. |
+| swatches | string[] | — | Optional preset row. |
+| label | string | "Colour" | Accessible name for the trigger; the current value is appended to it. |
+
+## Tokens used
+
+`panel`, `panel-raised`, `hairline`, `hairline-strong`, `ring`, `popover`
+
+## Accessibility
+
+- The trigger's accessible name includes the current value, so a screen reader announces the colour rather than just "button" — the swatch itself conveys nothing without sight.
+- The Transparent entry is a toggle with aria-pressed, because it is a state of the value and not a navigation action.
+- The hex field is the keyboard path to any colour. The saturation/value area and the sliders are pointer-driven and are NOT keyboard operable — a known gap, and the reason the hex field is never hidden.
+- The eyedropper is only rendered where the EyeDropper API exists (Chromium), rather than shown and broken elsewhere.
+
+## Related
+
+- Components: PropertyRow, PropertyPair, ScrubField, Input, Popover
+
+## Examples
+
+### Canvas background
+
+```tsx
+import { ColorField, PropertyRow } from "@sableui/react"
+
+<PropertyRow label="Background">
+  <ColorField value={background} onValueChange={setBackground} allowTransparent />
+</PropertyRow>
+```
+
+### With alpha and a palette
+
+```tsx
+import { ColorField } from "@sableui/react"
+
+<ColorField
+  value={tint}
+  onValueChange={setTint}
+  allowAlpha
+  swatches={["#f43f5e", "#facc15", "#22c55e", "#3b82f6", "#a855f7"]}
+  label="Tint"
+/>
+```
+
+### The value format is the contract
+
+```tsx
+import { isTransparent, parseHex } from "@sableui/react"
+
+// ColorField only ever EMITS these three shapes:
+//   "transparent" | "#rrggbb" | "#rrggbbaa"
+// It accepts #rgb and #rgba on paste but never produces them, so a consumer's
+// parser has three cases to handle rather than five.
+//
+// Alpha is omitted when fully opaque — "#3b82f6", never "#3b82f6ff" — so a
+// parser written before alpha support keeps reading opaque colours correctly.
+// Only enable allowAlpha once your parser and your persisted format accept the
+// 8-digit form, or a document saved by a newer build degrades on an older one.
+
+import { parseHex, isTransparent } from "@sableui/react"
+
+const parsed = isTransparent(value) ? null : parseHex(value) // null = not a colour
+```

package/llms/components/combobox.md

@@ -0,0 +1,119 @@
+# Combobox
+
+**Status:** stable
+
+Autocomplete over Base UI Combobox — type-to-filter, roving focus, ARIA combobox/listbox wiring, collision-aware positioning, Esc/outside dismissal. A search input (with chevron trigger) plus a portal-rendered popup of filterable items.
+
+**Keywords:** combobox, autocomplete, typeahead, search select, filter, suggestions, picker
+
+## Usage
+
+Use Combobox when users choose from a list that benefits from typing, filtering, or autocomplete — one value, or several with `multiple` and ComboboxChips (tags, collaborators, categories). Use Select for short finite sets, a Checkbox group when every choice should stay visible, and CommandMenu for global actions.
+
+### Best practices
+
+- 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: 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.
+- Don't: Use Combobox for tiny option sets where Select or Radio would be easier to scan.
+- Don't: Use Combobox as a command launcher. Use CommandMenu for actions and navigation.
+- Don't: Take filtering over with filteredItems in order to virtualize. Base UI ignores filteredItems while the untouched field still holds the selected item's label, so the list you render and the list it indexes diverge — and the symptom is clicking one row and getting another.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Root | yes | Owns selected value, input value, filtering, and open state. |
+| Input | yes | The searchable text field and trigger. |
+| Chips | no | The field for `multiple`, used in place of Input: one removable chip per selected item plus the text input, in one wrapping shell. |
+| Content | yes | The positioned popup surface. |
+| List | yes | The listbox inside the popup. Takes a render function that receives each filtered item. |
+| Item | yes | A selectable suggestion row. |
+| Empty | no | Fallback shown when filtering returns no items. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| ComboboxInput | Base UI Combobox.Input props (minus the native `size` attribute) + size?: "md" \| "xs" + className | The search field, styled like Input, wrapped with an InputGroup + chevron Trigger that toggles the popup. The chevron flips while the popup is open (data-[popup-open] on the toggle). `size="xs"` is the property-grid rung and mirrors SelectTrigger's `xs` exactly — same height, radius and inset surface — so a combobox and a select in one panel are the same shape holding different content (a font-family picker directly above a font-weight select is the case it exists for). Note the type: the native numeric `size` attribute is omitted rather than shadowed, because intersecting a string union onto it resolves to `never` and breaks every call site. |
+| ComboboxChips | Base UI Combobox.Input props (minus the native `size` attribute) + size?: "md" \| "xs" + chipLabel?: (item) => string + className | The field for a `multiple` combobox, used in place of ComboboxInput. Each selected item renders as a soft `sm` Badge with a ghost `icon-xs` Button that removes it (labelled "Remove {label}"), followed by the text input; the shell wraps and grows as chips are added. `chipLabel` turns an item into its chip text — defaults to the item for strings/numbers and its `label` field for objects. Keyboard is Base UI's: Backspace in an empty field removes the last chip, ←/→ move between chips, Backspace/Delete removes the highlighted one. `size="xs"` mirrors ComboboxInput's property-grid rung. |
+| ComboboxContent | Base UI Popup props + { side?: Side; align?: Align; sideOffset?: number; scroll?: boolean; className?: string } | Portal + Positioner + Popup — it does not render a list, so put a ComboboxList (or ComboboxVirtualList) inside it. Width matches the input via --anchor-width. side is which side of the input the popup renders against (auto-flips on collision), align its alignment along that side, sideOffset the gap in px. Defaults to side='bottom', align='start', sideOffset=6, scroll=true. Pass scroll={false} when a ComboboxVirtualList inside owns the scrolling. |
+| ComboboxList | Base UI Combobox.List props (children: ReactNode \| (item, index) => ReactNode) | The listbox. Required inside ComboboxContent: pass a render function and it is called once per filtered item (or per group when `items` is grouped), so the rendered rows always match Base UI's filtering. |
+| ComboboxVirtualList | { itemHeight: number; groupLabelHeight?: number; overscan?: number; children: (item, { index }) => ReactNode; renderGroupLabel?; className?; itemClassName? } | A windowed list: only the rows on screen exist. Fixed row heights (nothing is measured, so late-arriving content changes how a row looks and never where the rows are). Filtering stays Base UI's — the component reads the filtered list through useFilteredItems() — and groups keep their role=group wrapper and label association. Needs virtualized on the root and scroll={false} on ComboboxContent. |
+| ComboboxItem | Base UI Combobox.Item props + className (value, disabled, index, onClick) | A suggestion row. Highlights via data-[highlighted]; shows a trailing check (ItemIndicator) when it matches the selected value. |
+| ComboboxEmpty | Base UI Combobox.Empty props + className | Fallback shown when the filtered list is empty. Requires the `items` prop on the root. |
+| ComboboxGroup | Base UI Combobox.Group props + className | Groups related items under an accessible label auto-associated with the group. |
+| ComboboxGroupLabel | Base UI Combobox.GroupLabel props + className | The label for a ComboboxGroup. Auto-associated with the group it sits in. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| 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. |
+| virtualized | boolean | false | Tells Base UI the DOM holds only part of the list. Required when using ComboboxVirtualList. |
+
+## Tokens used
+
+`input`, `card`, `foreground`, `muted-foreground`, `ring`, `destructive`, `popover`, `popover-foreground`, `border`, `accent`, `accent-foreground`, `primary`, `secondary`, `secondary-foreground`
+
+## Accessibility
+
+- Base UI provides role=combobox/listbox/option, roving tabindex, arrow-key navigation, and type-to-filter.
+- Esc and outside-press dismiss; focus returns to the input on close.
+- The chevron Trigger carries an aria-label and toggles the suggestions popup.
+- ComboboxEmpty announces filter results politely; keep it mounted (do not conditionally render it).
+- Animate open/close via data-[starting-style]/data-[ending-style] attributes.
+- With `multiple`, the listbox is multi-selectable and each chip's remove button is labelled `Remove {label}`; Backspace in an empty field removes the last chip and ←/→ move between chips, so every chip is reachable without a pointer.
+- ComboboxVirtualList gives every rendered row aria-setsize (the full filtered count) and aria-posinset, so a screen reader is told the size of the list rather than the size of the window.
+- A highlight that lands on a row the window has not rendered is scrolled into view by the root, which forwards it to the list; Base UI's own scrollIntoView only reaches rows that exist.
+
+## Related
+
+- Components: Select, Checkbox, CommandMenu, Field, SearchInput, Badge
+- Patterns: SettingsPage, ListDetailPage
+
+## Examples
+
+### Basic
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxList } from "@sableui/react"
+
+<Combobox items={fruits}><ComboboxInput placeholder="Search fruit…" /><ComboboxContent><ComboboxEmpty>No matches.</ComboboxEmpty><ComboboxList>{(item) => (<ComboboxItem key={item} value={item}>{item}</ComboboxItem>)}</ComboboxList></ComboboxContent></Combobox>
+```
+
+### Controlled value
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem, ComboboxList } from "@sableui/react"
+
+<Combobox items={fruits} value={value} onValueChange={setValue}><ComboboxInput /><ComboboxContent><ComboboxList>{(item) => (<ComboboxItem key={item} value={item}>{item}</ComboboxItem>)}</ComboboxList></ComboboxContent></Combobox>
+```
+
+### Multiple selection
+
+```tsx
+import { Combobox, ComboboxChips, ComboboxContent, ComboboxEmpty, ComboboxItem, ComboboxList } from "@sableui/react"
+
+<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>
+```
+
+### Virtualized (long list)
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxVirtualList } from "@sableui/react"
+
+<Combobox virtualized items={districts} value={district} onValueChange={setDistrict}><ComboboxInput placeholder="Search districts…" /><ComboboxContent scroll={false}><ComboboxEmpty>No district matches.</ComboboxEmpty><ComboboxVirtualList itemHeight={32}>{(item) => item.label}</ComboboxVirtualList></ComboboxContent></Combobox>
+```
+
+### Inside Field
+
+```tsx
+import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxList, Field } from "@sableui/react"
+
+<Field label="Creator" description="Search by display name."><Combobox items={creators} value={creator} onValueChange={setCreator}><ComboboxInput placeholder="Search creators" /><ComboboxContent><ComboboxEmpty>No creators found.</ComboboxEmpty><ComboboxList>{(item) => (<ComboboxItem key={item.id} value={item}>{item.name}</ComboboxItem>)}</ComboboxList></ComboboxContent></Combobox></Field>
+```

package/llms/components/command-menu.md

@@ -0,0 +1,158 @@
+# CommandMenu
+
+**Status:** stable
+
+A command palette (Cmd+K) built on our Dialog: a top-aligned wide surface with a search input and a scrollable, JS-filtered list of grouped commands. CommandMenuPanel renders the same palette in place, on a card in the page.
+
+**Keywords:** command, command menu, palette, launcher, cmd k, search, quick action, spotlight, navigation, search trigger, header search, keyboard shortcut, inline command menu, embedded palette, settings search
+
+## Usage
+
+Use CommandMenu for global or contextual keyboard-driven actions: navigation, creation, quick settings, or searchable commands. It should feel curated and fast; use Select, Menu, or Combobox for ordinary inline choices.
+
+### Best practices
+
+- Do: Open the palette from a header search with CommandMenuTrigger: a button wearing SearchInput's field shell, with the ⌘K / Ctrl K hint and the page-wide shortcut built in. A palette with no visible trigger still takes useCommandMenuShortcut rather than a hand-written keydown listener.
+- Do: Group items by task area, such as Navigation, Create, or Settings, so users can scan before typing.
+- Do: Keep command labels action-oriented and unique enough to search.
+- Do: Provide useful bootstrap items so the menu is valuable before the user types.
+- Do: Pass a filter when the palette searches more than one source. Ranking (exact prefix over substring over subsequence) is the caller's to own, and the returned order is kept verbatim — including group order, which follows each group's first surviving row.
+- Do: List a command the user cannot currently run as disabled with the reason in hint, rather than filtering it away. A palette that hides what you cannot do teaches you nothing about why.
+- Do: Resize the list with listClassName rather than reaching past className into the palette's DOM. className is the dialog surface; listClassName is the Scroller that actually scrolls.
+- Do: Use CommandMenuPanel when the palette lives in the page: a sidebar launcher, a settings search, a demo. It takes the same items, filter, query and children, and keeps the same keyboard model; it is a static card, so it does not trap focus or take it on mount, and Esc clears the query instead of closing anything.
+- Don't: Hand-style a <button> to look like a search field, or put a SearchInput in the header that opens a dialog when focused. The first drifts from the field it imitates; the second is a text box you cannot type in. A header search that opens the palette is CommandMenuTrigger.
+- Don't: Use CommandMenu as a replacement for every dropdown. Simple choices belong in Select, Menu, or Tabs.
+- Don't: Hand-build a palette mock from a search glyph, a row of buttons and a highlight. That is CommandMenuPanel, and the hand-built one has no combobox, no filtering and no keyboard model.
+- Don't: Dump every app route and action into one uncurated list. Keep the palette opinionated.
+- Don't: Rebuild the combobox over Dialog to get consumer-owned ranking. query/onQueryChange and filter are that seam; the keyboard model, activedescendant wiring, and result-count live region come with them.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Trigger | no | CommandMenuTrigger — the search-field-shaped button in a header that opens the palette on click or on ⌘K / Ctrl+K. It sits outside CommandMenu; wire its onOpen to the palette's open state. |
+| Dialog surface | yes | The modal shell that traps focus and positions the launcher. CommandMenuPanel replaces it with a static card in the page (border, card fill, no shadow). |
+| Search input | yes | The combobox input that filters commands while focus remains in the field. |
+| Groups | no | Labelled command sections that keep results scannable. |
+| Items | yes | Keyboard-selectable command rows that run onSelect and close the palette. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| CommandMenuTrigger | { onOpen?: () => void; placeholder?: string; shortcut?: string \| false; size?: "sm" \| "md"; disabled?: boolean } | The search field in a header that is really a button. Wears SearchInput's shell (border-input, card surface, leading magnifier, muted placeholder) on the control ladder, with a trailing Kbd: ⌘K on macOS, Ctrl K elsewhere. onOpen runs on click and on the shortcut, which it listens for page-wide (useCommandMenuShortcut). shortcut is the key (default "k"); false drops both the hint and the listener. size is sm in a header beside small buttons, md (default) beside Input and SearchInput. It sits outside CommandMenu, so the Dialog returns focus to it on close. |
+| useCommandMenuShortcut | (onShortcut: (event: KeyboardEvent) => void, key?: string \| false) => void | The page-wide ⌘K / Ctrl+K listener CommandMenuTrigger installs, for a palette with no visible trigger. Ignored while focus is in a text field, textarea, select or contenteditable (Ctrl+K belongs to the field there) except the palette's own input, so the callback may toggle. It calls preventDefault() on a match and skips an event already prevented, so two listeners on one page fire once. key defaults to "k"; false turns it off. Removed on unmount. |
+| CommandMenuPanel | { items?: CommandItem[]; query?: string; onQueryChange?: (query: string) => void; filter?: CommandFilter; listClassName?: string; placeholder?: string; emptyMessage?: string; title?: string; scope?: ReactNode; inputProps?: ComponentProps<'input'>; className?: string; children?: ReactNode } | The palette rendered in place: the same search header, filtered and grouped listbox, keyboard model and result-count live region, on a static card (border-border, bg-card, no shadow) instead of in a Dialog. Takes every CommandMenu prop except open, onOpenChange, finalFocus and description; className lands on the card, title names the listbox. Focus is not trapped and the input does not take focus on mount (inputProps.autoFocus opts in). Esc clears the query, and passes through once it is empty, so a Popover around the panel still closes. A chosen row runs its onSelect and the panel stays as it was. The page-wide shortcut does not fire from its input. |
+| CommandMenuGroup | { label: string; children } | A labelled group of command rows. |
+| CommandMenuItem | { onSelect?: () => void; icon?: string; detail?: ReactNode; hint?: ReactNode; disabled?: boolean; id?: string; children } | A selectable row. Self-filters by its text (unless the root was given a filter), runs onSelect, then closes the palette. detail is secondary text after the label; hint is the end-aligned trailing slot — a shortcut, a count, or a disabled row's reason. A disabled row stays listed, stays announced, and stays reachable by arrow key so its reason can be read, but is inert to Enter and to a click. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| scope | ReactNode | — | A scope chip in the header, between the search glyph and the input — "In: Backdrop". A scope belongs beside the field rather than in its value: put it in the value and the user deletes prose to widen their search, and your filter parses it back out. Pair with inputProps.onKeyDown handling Backspace on an empty query, or the only way out of a scope is the mouse. |
+| inputProps | Omit<ComponentProps<'input'>, 'role' \| 'value' \| 'onChange' \| aria-*> | — | Extra props for the search input. `onKeyDown` runs BEFORE the palette's own handling and opts out of a key by calling preventDefault() — which is what makes a scope chip Backspace-dismissable. Running first is deliberate: Backspace happens not to be a key the palette claims today, so a plain passthrough would work until the palette grows a 'Backspace clears the query' affordance, at which point the consumer's behaviour breaks silently. The combobox wiring (role, aria relationships, controlled value) is not overridable; aria-label and className compose. |
+| open | boolean | — | Controlled open state of the palette. |
+| onOpenChange | (open: boolean) => void | — | Called on open/close (select, Esc, outside click). |
+| items | CommandItem[] | — | Data-driven commands ({ group, label, onSelect, id?, icon?, detail?, hint?, disabled? }). Ignored when children are provided. id is optional identity: filter is handed these same objects, so it is how a caller that ranks over its own richer model maps the array back onto it — and it becomes the row's DOM id (namespaced to the palette) and React key, so two rows may share a label. |
+| query | string | — | Controlled query. Leave undefined to let the palette own it; either way it resets on close (a controlled caller gets onQueryChange('')). |
+| onQueryChange | (query: string) => void | — | Called on every query change. Required to control query, optional otherwise. |
+| filter | ((items: CommandItem[], query: string) => CommandItem[]) \| null | case-insensitive substring match on label | Replaces or disables the built-in match. A function ranks and filters items itself and its order is kept verbatim; null renders items exactly as given. Either also stops declarative CommandMenuItem children self-filtering. The query arrives raw — trimming and case are policy, and this is the prop that hands policy over. |
+| listClassName | string | — | Classes for the scrolling list. className lands on the dialog surface, so this is the seam for the list's own height cap — listClassName="max-h-[60vh]". The list is a Scroller, so the cap lands on the element that scrolls and the edge fades come free. |
+| placeholder | string | "Type a command or search…" | Placeholder for the search input. |
+| emptyMessage | string | "No results found." | Copy shown when the query matches nothing. |
+| title | string | "Command menu" | Accessible name for the palette dialog (visually hidden). |
+| description | string | "Search for a command and press Enter to run it." | Accessible description for the palette dialog (visually hidden). |
+| finalFocus | RefObject<HTMLElement> \| ((closeType) => HTMLElement \| false) \| false | — | Where focus goes when the palette closes. The Dialog default returns it to the trigger — the CommandMenuTrigger, when there is one. A palette opened by the keystroke alone has none, so pass a resolver to restore whatever had focus, or false to restore nothing. |
+| children | ReactNode | — | Declarative commands via CommandMenuGroup / CommandMenuItem. Takes precedence over items. |
+
+## Tokens used
+
+`card`, `card-foreground`, `border`, `foreground`, `muted-foreground`, `accent`, `accent-foreground`
+
+## Accessibility
+
+- CommandMenuTrigger is a real <button> named by its visible placeholder, with aria-haspopup=dialog and aria-keyshortcuts (Meta+K on macOS, Control+K elsewhere). Its Kbd hint is aria-hidden, so the shortcut is announced once rather than read as part of the name.
+- The shortcut never fires from inside a text field, textarea, select or contenteditable (Ctrl+K is delete-to-end-of-line in macOS text views), except the palette's own input.
+- CommandMenuPanel is the same combobox and listbox in the page, with no dialog: it does not trap or steal focus, and Esc clears a non-empty query (stopping there) instead of dismissing. With an empty query Esc is left alone for whatever contains the panel.
+- Built on Base UI Dialog, so focus trap, scroll lock, and Esc/outside dismissal come for free; the dialog carries a visually-hidden title + description so it is announced.
+- Follows the ARIA combobox pattern: the search input is role=combobox (aria-autocomplete=list) that owns the role=listbox popup via aria-controls.
+- ArrowDown/ArrowUp/Home/End and PageUp/PageDown move a virtual aria-activedescendant highlight while focus stays in the input; Enter runs the highlighted command. Arrow keys wrap; page jumps clamp.
+- Groups expose role=group labelled by their heading; items are role=option and never enter the tab order.
+- A polite role=status live region announces the result count as the query narrows, so the size of the list is available without reading it.
+- A disabled row carries aria-disabled and is skipped when seeding the highlight, but stays in the arrow-key walk so its reason can be reached and read.
+- The component keeps ownership of aria-activedescendant even when a caller claims a key through inputProps.onKeyDown. Skipping a move is coherent (they took responsibility for that key), but nothing may leave the active id naming a row that is not painted as active — so the opt-out returns before any highlight change rather than after it.
+- Exactly one row is ever painted as active: the pointer takes the highlight over (moving onto a row makes it the aria-activedescendant) rather than adding a hover fill of its own, so what looks highlighted is always what Enter will run.
+
+## Related
+
+- Components: Dialog, SearchInput, Kbd, Menu, Select, Combobox
+- Patterns: DashboardPage, ListDetailPage
+
+## Examples
+
+### Data-driven
+
+```tsx
+import { CommandMenu } from "@sableui/react"
+
+<CommandMenu open={open} onOpenChange={setOpen} items={[{ group: 'Navigation', label: 'Go to feed', icon: 'home', onSelect: () => {} }, { group: 'Actions', label: 'New post', onSelect: () => {} }]} />
+```
+
+### Declarative
+
+```tsx
+import { CommandMenu, CommandMenuGroup, CommandMenuItem } from "@sableui/react"
+
+<CommandMenu open={open} onOpenChange={setOpen}><CommandMenuGroup label='Navigation'><CommandMenuItem icon='home' onSelect={() => {}}>Go to feed</CommandMenuItem></CommandMenuGroup></CommandMenu>
+```
+
+### Grouped launcher
+
+```tsx
+import { CommandMenu, CommandMenuGroup, CommandMenuItem } from "@sableui/react"
+
+<CommandMenu open={open} onOpenChange={setOpen}><CommandMenuGroup label="Create"><CommandMenuItem icon="plus" onSelect={() => createPost()}>New post</CommandMenuItem><CommandMenuItem icon="sparkles" onSelect={() => createEdition()}>New edition</CommandMenuItem></CommandMenuGroup><CommandMenuGroup label="Navigation"><CommandMenuItem icon="home" onSelect={() => navigate("/")}>Home</CommandMenuItem><CommandMenuItem icon="gear" onSelect={() => navigate("/settings")}>Settings</CommandMenuItem></CommandMenuGroup></CommandMenu>
+```
+
+### Consumer-owned ranking
+
+```tsx
+import { CommandMenu } from "@sableui/react"
+
+<CommandMenu open={open} onOpenChange={setOpen} query={query} onQueryChange={setQuery} filter={(items, q) => rank(items, q)} items={items} />
+```
+
+### Listed but unavailable
+
+```tsx
+import { CommandMenu } from "@sableui/react"
+
+<CommandMenu open={open} onOpenChange={setOpen} items={[{ group: 'Layers', label: 'Align left', disabled: true, hint: 'Select another layer to align to', onSelect: () => {} }]} />
+```
+
+### Inline panel
+
+```tsx
+import { CommandMenuPanel, Kbd } from "@sableui/react"
+
+<CommandMenuPanel className="w-80" items={[{ group: 'Create', label: 'New project', icon: 'plus', hint: <Kbd>N</Kbd>, onSelect: () => {} }, { group: 'Settings', label: 'Open settings', icon: 'gear', onSelect: () => {} }]} />
+```
+
+### Header search trigger
+
+```tsx
+import { CommandMenu, CommandMenuTrigger } from "@sableui/react"
+
+<CommandMenuTrigger size="sm" placeholder="Search docs" onOpen={() => setOpen(true)} className="w-56" />
+<CommandMenu open={open} onOpenChange={setOpen} items={items} />
+```
+
+### Keyboard shortcut with no visible trigger
+
+```tsx
+import { CommandMenu, useCommandMenuShortcut } from "@sableui/react"
+
+useCommandMenuShortcut(() => setOpen((value) => !value))
+<CommandMenu open={open} onOpenChange={setOpen} items={items} />
+```