division-ds 0.1.1 → 0.2.0

package/public/docs/components/chat-thread.md

@@ -0,0 +1,242 @@
+# ChatThread
+
+> A scrolling log of ChatMessages. It follows new text only while the reader is at the end, and it announces each finished reply to screen readers once.
+
+- **Best for:** A conversation with an assistant, above a PromptInput, where replies stream in.
+- **Not for:** A record of events on one thing: use Timeline.
+- Organism. Source: `src/components/organisms/chat-thread/ChatThread.tsx`
+- Rendered docs page: `/components/chat-thread`
+
+## Import
+
+```tsx
+import { ChatThread } from 'src/components/organisms/chat-thread/ChatThread'
+```
+
+## Requires
+
+- A height, because the thread scrolls and the page doesn't. Use h-[28rem], or flex-1 min-h-0 inside a column.
+- ChatMessage children, so the thread can announce each finished reply.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. Names the log. |
+| `busy` | `boolean` | `false` | The assistant is working. Shows a working line and makes one announcement when it starts. |
+| `busyLabel` | `string` | `'Assistant is working'` | The working line's words, and what gets announced. |
+| `jumpLabel` | `string` | `'Jump to latest'` | The jump button's words. |
+| `className` | `string` |  | Goes on the root. Give the thread a height here. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### A live conversation: send anything, watch the reply stream in, press Stop to end it, or scroll up while it's still arriving
+
+```tsx
+type Turn =
+  | { id: number; role: 'user'; text: string }
+  | { id: number; role: 'assistant'; text: string; tool?: ToolCallStatus; approval?: boolean }
+  | { id: number; role: 'system'; text: string }
+
+const REPLIES = [
+  'Depot 4 holds 1,240 replicas across 38 lines. Two lines are under their reorder point: the K-41 field radio has 6 left against a reorder point of 10, and the trail pack has 3 left against 8. Everything else has at least two weeks of cover at the current rate. The reorder above covers both lines; once it is approved, the supplier confirms within a working day.',
+  'Inbound this week: one delivery from Arad on Thursday morning, 22 pallets, booked into bay 2. Outbound: nine shipments, the largest to Sibiu on Friday. Nothing is waiting on a person except the reorder above.',
+]
+
+const HISTORY: Turn[] = [
+  { id: 1, role: 'user', text: 'Summarise stock at Depot 4.' },
+  {
+    id: 2,
+    role: 'assistant',
+    text: 'Depot 4 is in good shape: 1,240 replicas on hand and nothing overdue. Two lines are low, so I have drafted a reorder for you to check.',
+    tool: 'done',
+    approval: true,
+  },
+]
+
+function LiveConversation() {
+  const [turns, setTurns] = useState<Turn[]>(HISTORY)
+  const [draft, setDraft] = useState('')
+  const [phase, setPhase] = useState<'idle' | 'tool' | 'streaming'>('idle')
+  const [approval, setApproval] = useState<ApprovalState>('pending')
+  const [replyIndex, setReplyIndex] = useState(0)
+  const nextId = useRef(HISTORY.length + 1)
+  const activeId = useRef<number | null>(null)
+  const reply = useStreamedText(REPLIES[replyIndex % REPLIES.length], { active: phase === 'streaming' })
+
+  const updateActive = (change: (turn: Turn & { role: 'assistant' }) => Turn) =>
+    setTurns(list => list.map(turn => (turn.id === activeId.current && turn.role === 'assistant' ? change(turn) : turn)))
+
+  const addStopped = () => {
+    const id = nextId.current++
+    setTurns(list => [...list, { id, role: 'system', text: 'Assistant stopped' }])
+  }
+
+  // The tool "runs" for a moment, then the reply starts streaming.
+  useEffect(() => {
+    if (phase !== 'tool') return
+    const timer = window.setTimeout(() => {
+      updateActive(turn => ({ ...turn, tool: 'done' }))
+      setPhase('streaming')
+    }, 1200)
+    return () => window.clearTimeout(timer)
+  }, [phase])
+
+  // Finished or stopped: keep what arrived, and hand the thread a message that is no longer streaming.
+  useEffect(() => {
+    if (phase !== 'streaming' || !reply.done) return
+    updateActive(turn => ({ ...turn, text: reply.text }))
+    if (reply.stopped) addStopped()
+    setPhase('idle')
+    setReplyIndex(index => index + 1)
+  }, [phase, reply.done, reply.text, reply.stopped])
+
+  const send = (text: string) => {
+    const question = nextId.current++
+    const answer = nextId.current++
+    activeId.current = answer
+    setTurns(list => [...list, { id: question, role: 'user', text }, { id: answer, role: 'assistant', text: '', tool: 'running' }])
+    setDraft('')
+    setPhase('tool')
+  }
+
+  const stop = () => {
+    if (phase === 'streaming') {
+      reply.stop()
+      return
+    }
+    // Stopped before any text: the empty reply goes, the system line says what happened.
+    setTurns(list => list.filter(turn => turn.id !== activeId.current))
+    addStopped()
+    setPhase('idle')
+  }
+
+  const busy = phase !== 'idle'
+
+  return (
+    <div className="flex w-full max-w-2xl flex-col border border-[var(--color-border-hairline-strong)]">
+      <ChatThread label="Conversation with the assistant" busy={phase === 'tool'} className="h-[28rem]">
+        {turns.map(turn => {
+          if (turn.role === 'user') {
+            return (
+              <ChatMessage key={turn.id} role="user" author="You">
+                {turn.text}
+              </ChatMessage>
+            )
+          }
+          if (turn.role === 'system') {
+            return (
+              <ChatMessage key={turn.id} role="system" author="Status">
+                {turn.text}
+              </ChatMessage>
+            )
+          }
+          const streaming = phase === 'streaming' && turn.id === activeId.current
+          const text = streaming ? reply.text : turn.text
+          return (
+            <ChatMessage key={turn.id} role="assistant" author="Assistant" streaming={streaming}>
+              {turn.tool === undefined ? null : (
+                <ToolCall
+                  name="query_stock_levels"
+                  title="Read stock levels at Depot 4"
+                  status={turn.tool}
+                  duration={turn.tool === 'done' ? '1.2 s' : undefined}
+                  input={'{ "depot": 4 }'}
+                  output={turn.tool === 'done' ? '{ "on_hand": 1240, "lines": 38, "below_reorder_point": 2 }' : undefined}
+                />
+              )}
+              {text === '' ? null : <p>{text}</p>}
+              {turn.approval ? (
+                <ApprovalRequest
+                  title="Send this reorder to the supplier?"
+                  state={approval}
+                  onApprove={() => setApproval('approved')}
+                  onReject={() => setApproval('rejected')}
+                  approveLabel="Send reorder"
+                  rejectLabel="Don't send"
+                >
+                  <p>To: Arad replica supply</p>
+                  <p>10 × K-41 field radio, 8 × trail pack, to Depot 4 by Thursday 22 October.</p>
+                </ApprovalRequest>
+              ) : null}
+            </ChatMessage>
+          )
+        })}
+      </ChatThread>
+      <PromptInput
+        label="Message the assistant"
+        placeholder="Ask about stock, orders or depots"
+        value={draft}
+        onValueChange={setDraft}
+        onSubmit={send}
+        busy={busy}
+        onStop={stop}
+        className="p-4 border-t border-[var(--color-border-hairline-strong)]"
+      />
+    </div>
+  )
+}
+
+<LiveConversation />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to the log, then into the controls inside messages, then to Jump to latest when it's shown. |
+| `ArrowUp` `ArrowDown` | With the log focused, scrolls it. |
+| `PageUp` `PageDown` | With the log focused, scrolls it a page at a time. |
+
+## Do
+
+- Give the thread a fixed or flexible height so the thread scrolls, not the page.
+- Set busy as soon as the request starts. Clear it when the last fragment has arrived or the reply is stopped.
+- After a Stop, add a system line ("Assistant stopped") so the record and the announcement both say what happened.
+- Keep the PromptInput outside the thread, directly under it.
+
+## Don't
+
+- Don't scroll the thread yourself on new messages. It follows the end only while the reader is there.
+- Don't move focus into the thread when a reply arrives. Focus stays where the person put it.
+- Don't add a second live region (an area screen readers announce changes from) for replies or tool calls. The thread's status is the only voice.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<div role="log" aria-live="polite">{messages}</div>
+```
+
+Right:
+
+```tsx
+<ChatThread label="Conversation with the assistant">{messages}</ChatThread>
+```
+
+A polite live log makes a screen reader read a streaming reply aloud one fragment at a time. The thread keeps the log quiet and announces each finished reply once.
+
+Wrong:
+
+```tsx
+useEffect(() => endRef.current?.scrollIntoView({ behavior: "smooth" }), [messages])
+```
+
+Right:
+
+```tsx
+<ChatThread ...>  // follows the end only while the reader is there
+```
+
+Scrolling on every change yanks away a reader who scrolled up to read. And smooth scrolling on every fragment means the screen never stops moving.
+
+## Anatomy
+
+- **Log**: Has role="log" and is named by label. aria-live is off, so screen readers don't read every change. It's a tab stop (a place the Tab key lands) so a keyboard can scroll it, and it scrolls inside its own height.
+- **Messages**: ChatMessage children, oldest first, 24px (pixels) apart.
+- **Working line**: Shown while busy: the conveyor Spinner and "Assistant is working" at the end of the log.
+- **Jump to latest**: Appears only when the reader has scrolled away from the end. It jumps instantly and puts focus on the log.
+- **Status**: A visually hidden role="status" that screen readers hear. It says the busy label once when work starts, and each finished reply once.

package/public/docs/components/checkbox.md

@@ -0,0 +1,147 @@
+# Checkbox
+
+> A checkbox with three states: off, on and mixed. Radix (the open-source library of accessible building blocks underneath it) handles the semantics and the keyboard behaviour. The look comes from the system's shape language: a square with no rounding and a tick in ink.
+
+- **Best for:** An on/off choice that applies when the form is saved, or a parent whose children are partly selected.
+- **Not for:** A setting that takes effect the moment you flip it. Use Switch for that.
+- Atom. Source: `src/components/atoms/checkbox/Checkbox.tsx`
+- Rendered docs page: `/components/checkbox`
+
+## Import
+
+```tsx
+import { Checkbox } from 'src/components/atoms/checkbox/Checkbox'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `checked` | `boolean \| 'indeterminate'` |  | The checked state, when your code controls it. |
+| `defaultChecked` | `boolean` |  | The starting state when the checkbox manages itself (uncontrolled). It's narrower than Radix's own boolean \| 'indeterminate'. The tick or dash can only follow a checked value the caller passed in. Radix would track an uncontrolled mixed state internally but never hand it back, so that state is excluded instead of being drawn with the wrong mark. |
+| `onCheckedChange` | `(checked: boolean \| 'indeterminate') => void` |  | Runs every time it toggles. |
+| `disabled` | `boolean` |  | Takes it out of the tab order and stops it toggling. |
+| `required` | `boolean` |  | Uses the browser's built-in form validation. |
+| `name` | `string` |  | The field name sent with a native form. |
+| `value` | `string \| number \| readonly string[]` |  | The field value sent with a native form. |
+| `invalid` | `boolean` | `false` | Sets aria-invalid (an ARIA attribute, from Accessible Rich Internet Applications, that tells screen readers the field has an error) and shows the invalid border. |
+| `id` | `string` |  | Pair it with a real label through htmlFor. |
+| `className` | `string` |  | Merged with the control's classes. If two clash, the later Tailwind utility wins (Tailwind is the CSS framework this system styles with). |
+| `ref` | `Ref<HTMLButtonElement>` |  | Passed through to the Radix root button. |
+| `...rest` | `Omit<CheckboxProps, 'aria-invalid' \| 'defaultChecked'>` |  | Every Radix Checkbox.Root prop except aria-invalid, spread onto the root. aria-invalid is removed from the type, so you can't pass it, instead of being quietly overwritten while the page runs. invalid is the only thing that sets both the attribute and the border. defaultChecked is declared again above, narrowed to boolean. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### States
+
+```tsx
+<div className="flex items-center gap-2">
+  <Checkbox id="state-unchecked" />
+  <label htmlFor="state-unchecked">Unchecked</label>
+</div>
+<div className="flex items-center gap-2">
+  <Checkbox id="state-checked" checked />
+  <label htmlFor="state-checked">Checked</label>
+</div>
+<div className="flex items-center gap-2">
+  <Checkbox id="state-indeterminate" checked="indeterminate" />
+  <label htmlFor="state-indeterminate">Mixed</label>
+</div>
+<div className="flex items-center gap-2">
+  <Checkbox id="state-disabled" disabled />
+  <label htmlFor="state-disabled">Disabled</label>
+</div>
+```
+
+### A group
+
+```tsx
+const KIT_ITEMS = ['Speed loader', 'Rail light', 'Spare battery', 'First aid kit']
+
+const slug = (s: string) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-')
+
+function GroupExample() {
+  const [checkedItems, setCheckedItems] = useState<Record<string, boolean>>({
+    'Speed loader': true,
+    'Rail light': true,
+    'Spare battery': false,
+    'First aid kit': false,
+  })
+
+  const checkedCount = KIT_ITEMS.filter(item => checkedItems[item]).length
+  const parentChecked: boolean | 'indeterminate' =
+    checkedCount === 0 ? false : checkedCount === KIT_ITEMS.length ? true : 'indeterminate'
+
+  function setAll(value: boolean) {
+    setCheckedItems(Object.fromEntries(KIT_ITEMS.map(item => [item, value])))
+  }
+
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="flex items-center gap-2">
+        <Checkbox
+          id="kit-parent"
+          checked={parentChecked}
+          onCheckedChange={checked => setAll(checked === true)}
+        />
+        <label htmlFor="kit-parent" className="font-medium">
+          Pack full field kit
+        </label>
+      </div>
+      <div className="flex flex-col gap-2 pl-6">
+        {KIT_ITEMS.map(item => (
+          <div key={item} className="flex items-center gap-2">
+            <Checkbox
+              id={`kit-item-${slug(item)}`}
+              checked={checkedItems[item]}
+              onCheckedChange={checked =>
+                setCheckedItems(prev => ({ ...prev, [item]: checked === true }))
+              }
+            />
+            <label htmlFor={`kit-item-${slug(item)}`}>{item}</label>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+<GroupExample />
+```
+
+### Invalid
+
+```tsx
+<div className="flex items-center gap-2">
+  <Checkbox id="state-invalid" invalid />
+  <label htmlFor="state-invalid">Confirm waiver on file</label>
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves focus to it. |
+| `Space` | Toggles it. |
+| `Enter` | Nothing. That's how a native checkbox behaves, so it isn't a bug to fix. |
+
+## Do
+
+- Give it a real <label htmlFor>, or let FormField do it.
+- Use the mixed state for a parent whose children are partly selected.
+- Put the label on the right and make it part of the clickable target.
+
+## Don't
+
+- Don't use a checkbox for something that takes effect right away. That's a Switch.
+- Don't rely on the fill colour alone. The tick and the dash are what show the state.
+- Don't nest checkbox groups more than one level deep.
+
+## Anatomy
+
+- **Root**: A button with role=checkbox, which tells screen readers it's a checkbox. A native input can't be styled this way. The box is 20px (pixels) and the hit area, the part you can click or tap, is 24px.
+- **Indicator**: A tick when checked, a dash when mixed. The shape changes, so the state never depends on colour alone.
+- **Hit area**: A ::before inset of -2px, which clears the 24×24 minimum in WCAG 2.2 (the Web Content Accessibility Guidelines, the public rulebook for making websites usable by people with disabilities).

package/public/docs/components/checkout-form.md

@@ -0,0 +1,126 @@
+# CheckoutForm
+
+> Shipping, delivery and payment in three steps, with the order summary beside them. It's a demo: no payment is ever taken, and the card fields say so.
+
+- **Best for:** A demo checkout: shipping, delivery and payment in three steps beside the order summary.
+- **Not for:** Taking a real payment. It's a demo and never charges.
+- Organism. Source: `src/components/organisms/checkout-form/CheckoutForm.tsx`
+- Rendered docs page: `/components/checkout-form`
+
+## Import
+
+```tsx
+import { CheckoutForm, DELIVERY_OPTIONS } from 'src/components/organisms/checkout-form/CheckoutForm'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `lines` | `CartLine[]` |  | Required. What's being bought. The order summary lists them. |
+| `countries` | `SelectOption[]` |  | Required. The options for the country Select. |
+| `deliveryOptions` | `DeliveryOption[]` | `DELIVERY_OPTIONS` | Prices in the currency's smallest unit. Zero shows as Free. |
+| `onPlaceOrder` | `(order: CheckoutOrder) => void \| { error: string } \| Promise<void \| { error: string }>` |  | Required. Gets the contact details, addresses, delivery id and total, and never a card field. If it rejects, an alert appears that lets the person try again, so the failure isn't lost. Resolving { error } shows that specific message in the same alert. |
+| `headingLevel` | `2 \| 3` | `2` | The level of the 'Checkout' heading. Steps and the order summary sit one level below it, and never below ErrorSummary's own fixed h4 (level-4 heading). |
+| `currency` | `string` | `'EUR'` | Passed to formatMoney. |
+| `locale` | `string` | `'en-IE'` | Passed to formatMoney. |
+| `className` | `string` |  | Merged with the root classes. Later Tailwind utilities win. |
+| `ref` | `Ref<HTMLDivElement>` |  | The root. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type DeliveryOption = {
+  id: string
+  label: string
+  detail: string
+  /** In the currency's minor unit (cents for EUR). Zero shows as "Free". */
+  price: number
+}
+```
+
+```ts
+export const DELIVERY_OPTIONS: DeliveryOption[] = [
+  { id: 'standard', label: 'Standard', detail: '3 to 5 working days', price: 0 },
+  { id: 'express', label: 'Express', detail: 'Next working day', price: 1200 },
+]
+```
+
+```ts
+export type CheckoutAddress = { line1: string; line2: string; city: string; postalCode: string; country: string }
+```
+
+```ts
+/** What the form hands over. No card field ever leaves it, demo or not. */
+export type CheckoutOrder = {
+  email: string
+  name: string
+  phone: string
+  shipping: CheckoutAddress
+  deliveryId: string
+  billing: CheckoutAddress | 'same-as-shipping'
+  /** In the currency's minor unit: the lines plus delivery. */
+  total: number
+}
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Three steps, a demo order
+
+```tsx
+const LINES: CartLine[] = [
+  { id: 'kestrel-c', name: 'Kestrel C carbine replica', unitPrice: 13900, quantity: 1 },
+  { id: 'prism-holo-sight', name: 'Prism holo sight', unitPrice: 4900, quantity: 2 },
+  { id: 'beam-600', name: 'Beam 600 rail light', unitPrice: 2400, quantity: 1 },
+]
+
+const COUNTRIES = [
+  { value: 'ie', label: 'Ireland' },
+  { value: 'ro', label: 'Romania' },
+  { value: 'de', label: 'Germany' },
+  { value: 'fr', label: 'France' },
+  { value: 'es', label: 'Spain' },
+]
+
+const wait = (ms: number) => new Promise(resolve => window.setTimeout(resolve, ms))
+
+<CheckoutForm lines={LINES} countries={COUNTRIES} onPlaceOrder={() => wait(800).then(() => undefined)} headingLevel={3} />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves through the fields, then Back and Continue. |
+| `Enter` | In a field, goes on to the next step, or places the order on the last one. |
+| `↑` `↓` | In the delivery options, moves and picks. |
+| `Space` | On the billing checkbox, toggles it. |
+
+## Do
+
+- Pass the cart lines, so the order summary and the total come from the same numbers.
+- Keep the demo notice whenever the card fields are fake.
+- Store prices in the currency's smallest unit (cents for EUR).
+
+## Don't
+
+- Don't make the Stepper clickable. Back and Continue move between steps.
+- Don't ask for the billing address unless it's different from shipping.
+- Don't validate a card number in a demo. Nothing's charged.
+
+## Anatomy
+
+- **Stepper**: Shows where the person is. It isn't clickable, so nobody can skip to a step whose fields don't exist yet.
+- **Step heading**: Read as 'Step 2 of 3: Delivery' by a screen reader. Focus (where keyboard input goes) lands here on Continue and Back.
+- **Error summary**: Lists the step's missing or wrong fields and takes focus. Each entry jumps to its field.
+- **Delivery options**: A radio group with prices, and nothing picked in advance.
+- **Billing**: Uses the shipping address by default. Unticking the box asks for a billing address.
+- **Demo notice**: An info Alert above the card fields saying no payment is taken.
+- **Order summary**: Lines, subtotal, delivery and total, formatted by formatMoney.
+- **Confirmation**: A status line that's always on the page and confirms the order.
+- **Placement alert**: Also always on the page. If onPlaceOrder rejects, or resolves { error } with a specific message, this alert says so, instead of the button just quietly stopping being busy. Everything already typed stays put for another try.

package/public/docs/components/command-palette.md

@@ -0,0 +1,145 @@
+# CommandPalette
+
+> Every action in one place. Press Ctrl+K anywhere, type a few letters, move with the arrow keys and press Enter. Focus (where keyboard input goes) returns to where it was, and then the command runs.
+
+- **Best for:** Every action in one place behind Ctrl+K, with a visible button that opens it too.
+- **Not for:** Searching page content: use Search. A few actions on one control: use DropdownMenu.
+- Organism. Source: `src/components/organisms/command-palette/CommandPalette.tsx`
+- Rendered docs page: `/components/command-palette`
+
+## Import
+
+```tsx
+import { CommandPalette, filterCommands, groupCommands } from 'src/components/organisms/command-palette/CommandPalette'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `commands` | `Command[]` |  | Required. Each has id, label, group, keywords, shortcut, icon and onSelect. |
+| `open` | `boolean` |  | Open state when controlled, meaning your code decides whether it is open. |
+| `defaultOpen` | `boolean` | `false` | Starting open state when uncontrolled, meaning the palette keeps track of it itself. |
+| `onOpenChange` | `(open: boolean) => void` |  | Called on every open and close, including Escape and a click on the scrim (the dimmed backdrop). If you refuse the close, the chosen command stays ready to run until the user does anything else in the palette. Closing it yourself later counts as accepting it. |
+| `shortcut` | `boolean` | `true` | Ctrl+K or Cmd+K opens and closes the palette from anywhere. |
+| `label` | `string` | `'Command palette'` | The dialog's accessible name (what a screen reader announces), hidden from view. |
+| `searchLabel` | `string` | `'Search commands'` | The search field's accessible name. |
+| `placeholder` | `string` | `'Type a command or search'` | Shown in the empty search field. |
+| `emptyMessage` | `string` | `'No matching commands'` | Shown when nothing matches the search. |
+| `ref` | `Ref<HTMLInputElement>` |  | The search field, while the palette is open. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type Command = {
+  id: string
+  label: string
+  /** Commands with the same group are drawn together under its heading. */
+  group?: string
+  /** Extra words a search matches on. */
+  keywords?: string[]
+  /** A hint shown on the option, e.g. "N". Display only: the palette does not bind it. */
+  shortcut?: string
+  /** Drawn aria-hidden; the label carries the meaning. */
+  icon?: ReactNode
+  onSelect: () => void
+}
+```
+
+```ts
+export type CommandGroup = { group?: string; commands: Command[] }
+```
+
+```ts
+/** Every whitespace-separated term must appear in the label, the group or a keyword, ignoring case.
+ *  A label that starts with the first term ranks first; otherwise the given order holds. */
+export function filterCommands(commands: readonly Command[], query: string): Command[]
+```
+
+```ts
+/** Groups in the order each group first appears; order within a group is kept. */
+export function groupCommands(commands: readonly Command[]): CommandGroup[]
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Store commands
+
+```tsx
+function StoreCommands() {
+  const [open, setOpen] = useState(false)
+  const [last, setLast] = useState('none')
+  const make = (id: string, label: string, group: string, icon: ReactNode, extra: Partial<Command> = {}): Command => ({
+    id,
+    label,
+    group,
+    icon,
+    onSelect: () => setLast(label),
+    ...extra,
+  })
+  const commands = [
+    make('orders', 'Go to orders', 'Navigate', <Package />, { keywords: ['sales'] }),
+    make('shipments', 'Go to shipments', 'Navigate', <Truck />),
+    make('returns', 'Go to returns', 'Navigate', <Inbox />),
+    make('new-shipment', 'New shipment', 'Create', <Plus />, { shortcut: 'N' }),
+    make('new-product', 'New product', 'Create', <Box />),
+    make('invite', 'Invite a teammate', 'Account', <Users />, { keywords: ['team', 'people'] }),
+    make('settings', 'Open settings', 'Account', <Settings />),
+  ]
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <Button variant="secondary" aria-keyshortcuts="Control+K Meta+K" onClick={() => setOpen(true)}>
+        Open command palette
+      </Button>
+      <span aria-hidden="true" className="inline-flex gap-1">
+        <Kbd>Ctrl</Kbd>
+        <Kbd>K</Kbd>
+      </span>
+      <p role="status" className="font-mono text-xs text-[var(--color-text-secondary)]">
+        Last command: {last}
+      </p>
+      <CommandPalette commands={commands} open={open} onOpenChange={setOpen} />
+    </div>
+  )
+}
+
+<StoreCommands />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Ctrl` `K` | Opens or closes it from anywhere on the page (Cmd+K on macOS). |
+| `↓` | Next command, wrapping round to the first. |
+| `↑` | Previous command, wrapping round to the last. |
+| `Home` | First command. |
+| `End` | Last command. |
+| `Enter` | Runs the active command. |
+| `Esc` | Closes without running anything. |
+
+## Do
+
+- Name commands as verbs: 'Go to orders', 'New shipment'.
+- Add keywords for the words people actually type.
+- Give it a visible button that opens it too. People won't find a shortcut on its own.
+
+## Don't
+
+- Don't put destructive commands in it without a dialog that asks for confirmation.
+- Don't show a shortcut hint the app doesn't actually set up.
+- Don't put more than one palette on a page. Each one listens for the same Ctrl+K/Cmd+K across the whole page, so a second one fights the first for the shortcut.
+
+## Anatomy
+
+- **Dialog**: Named 'Command palette', with the name hidden from view. Drawn on surface.base with the corner crosshair.
+- **Search field**: A combobox, a text field tied to a list of choices. Focus stays here the whole time.
+- **Listbox**: Named 'Commands'. It's not there at all when nothing matches.
+- **Group**: Named by its heading.
+- **Option**: The active one gets the fill, and the search field points to it as its active descendant, so screen readers announce it while focus stays in the field.
+- **Count**: A status line hidden from view but read by screen readers: '2 commands'.
+- **Shortcut hint**: A Kbd that's hidden from assistive technology (screen readers and similar tools). It's for display only.