@smwb/ui-react 2.8.0 → 2.10.0

package/README.md

@@ -66,6 +66,482 @@ component sets the same prop there itself, the two meet by these rules, the same
   `Chip`, `Card` or `MenuItem` (for roving focus, say) replaces the component's default. Passing `undefined` keeps
   the default.
 
+### Composer
+
+`Composer` is a task input for chat-style screens: a multi-line field that grows from `minRows` to `maxRows`, a
+`toolbar` slot for chip selectors, a send button that turns into Stop while `busy`, and optional attachments and
+character counter. Ctrl/⌘+Enter sends and Enter adds a line; `sendKey="enter"` swaps that for a reply line.
+
+```tsx
+import { Composer } from "@smwb/ui-react";
+
+function TaskInput({ run, cancel, running }: { run: (task: string) => void; cancel: () => void; running: boolean }) {
+  return (
+    <Composer
+      aria-label="Task for the agent"
+      placeholder="Describe the task"
+      maxLength={2000}
+      busy={running}
+      onSend={run}
+      onStop={cancel}
+      toolbar={<span>Agent · Model</span>}
+    />
+  );
+}
+```
+
+Name the field with `aria-label` or `aria-labelledby`: a placeholder is not a name. `onAttach` turns on the attach
+button and makes the whole composer a drop target for files (dragged text and links still go into the field);
+`accept`, `multiple` and `maxFiles` apply to a pick and to a drop alike, and `onAttach` is never called with an empty
+list. The composer keeps no file state, so show the picked files in the `attachments` slot yourself. The second click
+of a double-click on the action button is ignored, so sending does not stop the run it has just started.
+
+`Chat` draws a `Composer` as its footer now, so a chat gets the growing field, the Stop button and the file drop
+target without a separate component. See "Migrating from `ChatComposer`" below for what changed in `Chat`.
+
+### Migrating from `ChatComposer`
+
+`Chat` builds its footer out of `Composer` now. `ChatComposer` still works and `Chat` still draws it when you ask for
+it, but both are deprecated and go in the next major.
+
+**Stop and the agent's reply** are new props on `Chat`, the same pair `Composer` has: while `busy` the send button
+becomes Stop and calls `onStop`, the keys do not send and the text stays editable. Everything else the composer needs
+goes through one `composerProps` object.
+
+```tsx
+import { Chat } from "@smwb/ui-react";
+
+<Chat
+  messages={messages}
+  onSendMessage={send}
+  busy={replying}
+  onStop={cancel}
+  composerProps={{ maxLength: 2000, counter: true, toolbar: <span>Agent · Model</span> }}
+/>;
+```
+
+**Keys.** Enter still sends, but the modifiers swap sides — Ctrl/⌘+Enter now sends instead of adding a line, and
+Alt+Enter no longer sends: it is left to the browser, which adds a line on macOS (`Option+Return`) and does nothing in
+Chromium on Windows and Linux.
+
+| Keys in the chat input      | `ChatComposer` (before)      | `Chat` default `Composer` (after) |
+| --------------------------- | ---------------------------- | --------------------------------- |
+| Enter                       | send                         | send                              |
+| Shift+Enter                 | newline (`false` → send)     | newline, always                   |
+| Ctrl/⌘+Enter                | **newline** (`false` → send) | **send**                          |
+| Alt+Enter                   | send                         | left to the browser               |
+| Enter during an IME compose | ignored                      | ignored                           |
+
+`composerProps={{ sendKey: "modEnter" }}` gives the `Composer` default instead: Enter adds a line, Ctrl/⌘+Enter sends.
+`composerShiftEnterNewline` and `composerCtrlEnterNewline` are deprecated and do nothing unless `legacyComposer` is on.
+
+**DOM, classes and test ids.**
+
+| Before (`ChatComposer`)                                 | After (`Composer`)                                                |
+| ------------------------------------------------------- | ----------------------------------------------------------------- |
+| `.smwb-chat-composer`                                   | `.smwb-composer` (also `.smwb-chat__composer` on a Chat's footer) |
+| `.smwb-chat-composer__input`, `.smwb-text-field__input` | `.smwb-composer__input`                                           |
+| `chat-composer`                                         | `composer`                                                        |
+| `chat-composer-send`                                    | `composer-action` (`data-action="send"` / `"stop"`)               |
+| `chat-composer-attach` (a `label`)                      | `composer-attach` (a focusable `button`)                          |
+| `chat-file-input`                                       | `composer-file-input`                                             |
+
+The textarea is now named "Message" (it had only a placeholder before); override it with
+`composerProps={{ "aria-label": … }}` or `composerProps={{ "aria-labelledby": … }}`. The send button keeps the name
+"Send message".
+
+**Keeping the old composer while you migrate:** pass `legacyComposer` and `Chat` draws `ChatComposer` exactly as
+before, with the old DOM, test ids and Enter/Ctrl+Enter semantics. `busy`, `onStop` and `composerProps` are ignored in
+that mode. `composerShiftEnterNewline` and `composerCtrlEnterNewline` work only there.
+
+**Porting a standalone `ChatComposer`:**
+
+| `ChatComposer`                                   | `Composer`                                |
+| ------------------------------------------------ | ----------------------------------------- |
+| `onSendMessage`                                  | `onSend`                                  |
+| Enter sends                                      | `sendKey="enter"`                         |
+| `sendAriaLabel`                                  | `sendLabel`                               |
+| `attachAriaLabel`                                | `attachLabel`                             |
+| `fileUpload` + `attachInputId` / `onAttachClick` | `onAttach` (button, picker and drop zone) |
+| `shiftEnterNewline`                              | `sendKey="enter"`                         |
+| `ctrlEnterNewline`                               | none: Ctrl/⌘+Enter always sends           |
+| `className`                                      | `className`                               |
+
+Inside a `Chat` the composer is not a drop target (`dropTarget={false}`): the whole chat shell already is, so a drop
+anywhere — including on the field — uploads once.
+
+`ChatComposer`, `shouldComposerNewlineOnEnter`, `ChatComposerNewlineOptions`, `Chat`'s `legacyComposer`,
+`composerShiftEnterNewline` and `composerCtrlEnterNewline` are removed in the next major.
+
+### Tabs, panels and link tabs
+
+`Tabs` follows the WAI-ARIA tabs pattern with **manual activation**: the arrow keys along the row's `orientation` (Left
+and Right, Up and Down for `"vertical"`), Home and End move focus between the tabs and skip disabled ones, and Enter or
+Space selects the focused tab (`onChange`, as a click does). Moving focus selects nothing, so a row of links does not
+navigate as the arrows pass it. Only one tab, the focused or else the selected one, is in the page's Tab order; Tab
+leaves the row for the selected panel.
+
+The root of `Tabs` has no role. Give the content to `panels` as `TabPanel`s (`index` is the tab's index, counted as for
+`value`): each is `role="tabpanel"`, hidden unless its tab is selected, and linked to its tab by `aria-labelledby`
+and `aria-controls`. Ids derive from `Tabs`' `id` (`{id}-tab-0`, `{id}-panel-0`, ...; generated by default). An `id`
+of your own on a `Tab` wins over the derived one, and its panel is labelled by it; an `id` of your own on a `TabPanel`
+wins too, and then so must your own `aria-controls` on its `Tab`. Give a panel to every tab. Without `panels` the tabs
+link to nothing, as before. A `TabPanel` outside `panels` is not linked to any tabs and is always shown. With
+`scrollButtons` the scroll buttons are for the pointer and stay out of the Tab order: the arrow keys reach every tab and
+scroll it into view, and Tab goes on from the row to the panel.
+
+A `Tab` with an `href` is a link tab for route navigation: a real `<a href role="tab">` that never has a `target`.
+The router takes the plain click in the tab's `onClick` with `event.preventDefault()`; `Tabs` still calls `onChange`
+for it. A modified or non-primary click (Ctrl, Meta, Shift or Alt held, or a button other than the main one) is the
+browser's, as "open in a new tab": the router leaves it alone, as a router's `Link` does, and `Tabs` does not call
+`onChange` for it. A disabled link tab has no `href`.
+
+A `Tab` can be closable and carry actions, for workspace tabs such as terminal sessions. `closable` draws a close button
+after the tab, and `onClose` is called for it, with the click, and for Delete or Backspace on the focused tab (Backspace
+because a Mac has no Delete key), with the key; the tab does not remove itself, your `onClose` removes it. `onClose`
+also gets what asked for the close, `"button"`, `"key"` or `"actions"`. The button is labelled "Close tab", `closeLabel`
+localises it or names the tab. `actions` is content after the tab and before the close button: a trigger with a `Menu`
+("Rename", "Terminate"), or any control; given as a function it receives `{ close }`.
+
+The close button and the actions are the tab's siblings, not inside its `role="tab"` element: a control inside a tab
+would join the tab's accessible name, so a screen reader reads the tab as its label alone. They are not hidden from
+assistive technology, though. The close button keeps its localisable label because a screen reader user who cannot press
+Delete, as on a touch screen, closes the tab with it, and `actions` is yours. The cost: they sit in the tab list beside
+their tab, and ARIA 1.2 lets a `tablist` own only `tab`s, so a linter that applies that strictly (axe's
+`aria-required-children`) can flag them. The tab says which keys it answers to in `aria-keyshortcuts`: "Delete Backspace"
+when closable, "Shift+F10 ContextMenu" with `actions`.
+
+A tab given `closable` or `actions` (even `closable={false}`) is wrapped with them in a `.smwb-tab-item`; one given neither
+is the bare element, as before. `ref`, `className` and the handlers stay on the tab. The row keeps one tab stop: the close
+button has `tabIndex` -1, and so should the trigger in `actions`.
+
+The keyboard reaches the actions with Shift+F10 or the Menu key on the focused tab: it focuses the first control in
+`actions` and clicks it (a control that says `aria-expanded="true"` is already open and is left so). If that control
+names its popup in `aria-controls`, focus then moves to the first enabled `menuitem` in it, as the WAI-ARIA menu button
+pattern asks: ArrowDown moves on, Enter chooses, and Escape hands focus back to the trigger, which still counts as focus
+on its tab. Without `aria-controls` focus stays on the trigger. The tab row clips what overflows it, so draw the menu in a
+portal (`createPortal`), anchored to the trigger and with the `id` the trigger names.
+
+When the tab that has focus closes, focus moves to the tab that takes its place, the previous one if it was last,
+skipping disabled tabs; a close from a pointer with focus elsewhere takes none. A choice in the menu that removes the tab
+("Terminate") should call the `close` that `actions` receives, with its event: that runs `onClose` with the reason
+`"actions"` and tells the row that focus, which is in the menu outside it, is to move on. A tab removed some other way
+leaves focus on the page. A link tab can be closable too: the anchor is the tab and the button its sibling.
+
+### Tab groups
+
+`TabGroups` is a split area of tab groups: one CSS grid holding any number of tab rows, each with its panels, and a
+handle between neighbours that resizes them. It is the workspace screen — an agent beside two terminals, a log under a
+preview — and the whole arrangement is one JSON value you can store and hand back.
+
+The layout holds **ids and sizes only**: no labels, no content, no state. It stays small, and it survives a rename of
+what a tab is called.
+
+```json
+{
+  "version": 1,
+  "activeGroup": "g1",
+  "root": {
+    "type": "split",
+    "id": "s1",
+    "direction": "row",
+    "sizes": [50, 50],
+    "children": [
+      { "type": "group", "id": "g1", "tabs": ["agent"], "active": "agent" },
+      { "type": "group", "id": "g2", "tabs": ["term-1", "term-2"], "active": "term-1" }
+    ]
+  }
+}
+```
+
+A group is a row of `tabs` with the `active` one selected; a split has a `direction` (`"row"` puts its children side by
+side, `"column"` stacks them), `sizes` in percent and `children`. `version` is 1, and it is what
+`tabGroupsLayout.parseTabGroupsLayout` checks before it trusts anything else: that call drops tab ids that are no longer
+open, repairs sizes and node ids, and returns `null` for JSON that is not a layout, which is all the validation a stored
+or shared layout needs. Reading order is depth-first: it is the Tab order and the order a screen reader reads the area
+in, though the panels keep the DOM order they first appeared in. Generated group and split ids are the next free number
+(`g4`, `s3`), so an id can come back after its group closed: key what the app keeps per pane by tab id, not by group id.
+
+Give the component a `layout` and it is controlled: it draws what you hand it and reports through
+`onLayoutChange(layout, change)`, where `change` says which of `select`, `activate`, `move`, `split`, `close` and
+`resize` happened (an `activate` is a focus move into another group, not an edit worth storing). Give it a
+`defaultLayout` instead and it keeps the layout itself. `onLayoutChange` is called in both modes, and a controlled owner
+that ignores a change simply sees nothing move. A change that takes the focus with it — a chord, a menu item, a drop
+of the focused tab, the close of a group's last tab — focuses that tab on the first layout the owner draws after it,
+also when the owner applies `onLayoutChange` later (in a transition or a timeout); a layout drawn without the change
+drops it.
+
+`getTab(tabId)` says what a tab shows — `label`, `title` for the announcements, `icon`, `closable`, `closeLabel`,
+`actions`, `disabled` — and an id it returns nothing for is drawn by the id itself. `renderPanel(tabId)` says what the
+panel holds. A panel is rendered the first time its tab is selected and stays mounted from then on: hidden while
+another tab of the group is shown, and kept when the tab moves to another group, so a form keeps what was typed and a
+terminal its scrollback. A move changes only where the panel is drawn — its node stays where it is in the DOM — so a
+scrolled panel keeps its scroll, an iframe in it does not reload, and the focus inside it stays, in the moved tab's
+panel as in every other one.
+
+The model behind the component is exported as a namespace, so none of its names collide with yours:
+
+```tsx
+import React from "react";
+import { TabGroups, tabGroupsLayout, type TabGroupsLayout, type TabGroupsTab } from "@smwb/ui-react";
+
+const TABS: Record<string, TabGroupsTab> = {
+  agent: { label: "Agent" },
+  "term-1": { label: "Terminal 1" },
+  "term-2": { label: "Terminal 2" },
+};
+const KEY = "workspace.layout";
+
+/** What storage holds, or a fresh layout: `parseTabGroupsLayout` repairs it or refuses it. */
+function readLayout(tabs: string[]): TabGroupsLayout {
+  try {
+    const raw = window.localStorage.getItem(KEY);
+    const parsed = raw === null ? null : tabGroupsLayout.parseTabGroupsLayout(JSON.parse(raw), { tabs });
+    return parsed ?? tabGroupsLayout.createTabGroupsLayout(tabs);
+  } catch {
+    return tabGroupsLayout.createTabGroupsLayout(tabs);
+  }
+}
+
+export function Workspace() {
+  const [open, setOpen] = React.useState(() => Object.keys(TABS));
+  const [layout, setLayout] = React.useState(() => readLayout(open));
+  const nextTerminal = React.useRef(3);
+  return (
+    <div style={{ height: "70vh" }}>
+      <button
+        type="button"
+        onClick={() => {
+          const tabId = `term-${nextTerminal.current}`;
+          nextTerminal.current += 1;
+          setOpen((list) => [...list, tabId]);
+          setLayout((current) => tabGroupsLayout.addTab(current, tabId));
+        }}
+      >
+        New terminal
+      </button>
+      <TabGroups
+        layout={layout}
+        getTab={(tabId) => TABS[tabId]}
+        renderPanel={(tabId) => <pre>{`$ ${tabId}`}</pre>}
+        empty={<p>Nothing open.</p>}
+        onTabClose={(tabId) => {
+          setOpen((list) => list.filter((id) => id !== tabId));
+        }}
+        onLayoutChange={(next) => {
+          setLayout(next);
+          try {
+            window.localStorage.setItem(KEY, JSON.stringify(next));
+          } catch {
+            /* storage off: the layout is simply not remembered */
+          }
+        }}
+      />
+    </div>
+  );
+}
+```
+
+`addTab` is the "New terminal" case: the tab goes into the group the user last worked in, selected. When your own code
+changes which tabs are open — a session loaded, a command closed three of them — `tabGroupsLayout.syncTabs(layout, tabs)`
+makes the layout hold exactly that list: ids that are gone close, and new ones are appended to that same group.
+`removeTab`, `selectTab`, `moveTab`, `resizeSplit` and `setActiveGroup` are the rest of it, and every one returns the
+layout it was given when there is nothing to do.
+
+**Keyboard.** Everything is reachable without a mouse, and every move is announced in a `role="status"` region:
+
+| Where                    | Keys                        | What happens                                                                        |
+| ------------------------ | --------------------------- | ----------------------------------------------------------------------------------- |
+| A tab row                | ← → Home End                | move focus between the row's tabs, as `Tabs` does                                   |
+| A tab row                | Enter, Space                | select the focused tab                                                              |
+| The focused tab          | Alt+Shift+Arrow             | move it into the group that way, or split a new group there when the area ends      |
+| The focused tab          | Ctrl/⌘+Shift+← →            | move it one place along its row, without wrapping                                   |
+| The focused tab          | Delete, Backspace, Ctrl/⌘+W | close it, `onTabClose` first                                                        |
+| The focused tab          | Shift+F10, Menu             | open the tab's own `actions` menu                                                   |
+| A group's actions button | Enter, Space, ↓             | open the group menu on its first enabled item                                       |
+| The group menu           | ↑ ↓ Enter Esc               | split right or down, move to the previous or next group, move the tab left or right |
+| A separator              | ← → or ↑ ↓                  | resize by `keyboardStep` percent of the split (5 by default)                        |
+| A separator              | Home, End                   | as small as `minGroupSize` (120 px) allows, then as large                           |
+| Anywhere                 | Tab                         | a row, its actions button, its selected panel, the separator after it, the next row |
+
+Tab and Shift+Tab follow the reading order from group to group, while inside a row, a panel or a separator the
+browser keeps its own rules: a radio group is one stop (its checked radio), a frame is entered at its first or its last
+stop, and a `TabGroups` nested in a panel is part of that panel, gone through in its own reading order.
+
+The group menu acts on that group's selected tab, and an item is disabled when it cannot act: a split needs two tabs to
+leave one behind, and "previous" is grey on the first group in reading order. `groupActions={false}` takes the buttons
+away and leaves the chords and the pointer.
+
+**Drag and drop.** Dragging a tab draws a zone over every group's body. The centre of a body drops the tab into that
+group; within a quarter of the body's edge it splits a new group there, and the zone is drawn as that half. The group
+the drag started in refuses its own centre, and its own edge splits only with two tabs or more, so the cursor says "not
+allowed" instead of the drop doing nothing. Dropping on another group's tab row inserts the tab before the one under the
+pointer, or at the end over the row's empty part; a drop on its own row reorders, as `Tabs` does. After a drop the moved
+tab is focused at its new place when it had focus before the drag.
+
+**Accessibility.** The rows are `Tabs`, and its caveat applies: a closable tab, or one with `actions`, keeps those
+controls as siblings inside the `tablist`, which a strict `aria-required-children` linter can flag (see above). Each row
+is named "Group 1 of 4" — "Tabs" when there is only one group, so a single group reads as a plain tab row — and the
+group the user is in carries a primary line over its header. Each separator is a `role="separator"` with an
+`aria-orientation` and an `aria-valuenow` of 0–100 (the first of its two neighbours' share of the pair), and each panel
+is a tab stop of its own, so Tab leaves a row for the content it shows. Closing the last tab of a group moves focus to
+the selected tab of the group that takes the space, never to the page. The groups, rows and selected panels render on
+the server; dragging and resizing run in the browser.
+
+### Links in `Button` and `ListItem`
+
+A `Button` or a `ListItem` with an `href` is a real link (`<a href>`). By default it opens in a new tab, as `Button`
+always did: `target="_blank"` and `rel="noreferrer"`. For a link inside your app, in a footer list of pages say:
+
+- `target={null}` leaves the `target` attribute out, so the link opens in place and has no `rel` of its own. An empty
+  string does the same. Any other string is used as is (`"_self"`, or a window name, which gets `rel="noreferrer"`
+  like `"_blank"`); `undefined` keeps `"_blank"`.
+- `rel` replaces the default `rel` (`rel=""` drops it), so add `noreferrer` yourself if you still want it.
+- A router takes the plain click in `onClick` with `event.preventDefault()`, and leaves a modified or non-primary click
+  (Ctrl, Meta, Shift or Alt held, or a button other than the main one) to the browser, as a router's `Link` does; test
+  it before you call the router. Without `preventDefault` the browser follows the `href`.
+
+`ListItem` with an `href` puts its `startAdornment` and content in an anchor that fills the row, so the link is the
+row's Tab stop, `Enter` follows it, and the row is not focusable on its own. A disabled link row has no `href`.
+
+- The `endAdornment` sits beside the anchor, not in it: a control there (a pin button, a toggle) is not nested in the
+  link, and a click on it is not a click of the row, so `onClick` and its `preventDefault` do not see it. Keep the
+  `startAdornment` non-interactive.
+- `selected` paints the row and marks the link `aria-current="page"` (a list item cannot be `aria-selected`), which is
+  how a list of pages tells assistive technology where the user is.
+
+See the `InternalLinks` story of `List`, which stands in for the router with a few lines of state, and `InternalLink`
+of `Button`.
+
+### Sheet: header labels and focus return
+
+The icon-only header buttons of `Sheet` are named: `closeAriaLabel` (default `"Close sheet"`) for the close button and,
+for the size toggle, `expandAriaLabel` (`"Expand sheet"`), `collapseAriaLabel` (`"Collapse sheet"`) and
+`restoreAriaLabel` (`"Restore sheet size"`). The toggle cycles normal, expanded, collapsed (header only) and back, and
+its name always says what the next press does, so the name changing is how it exposes its state (it is not an
+`aria-pressed` button). It shows the `open_in_full` icon, and `close_fullscreen` while expanded; both are in the smwb
+icon set (Storybook, **UI/Base/Icon → All Icons**). Pass translated labels for a localized UI.
+
+When a `Sheet` opens it remembers the element that had focus (usually the button that opened it) and moves focus into
+the sheet. When it closes (Escape, the close button, the outside click of a modal sheet, `isOpen` turning false, or the
+sheet unmounting while open), focus goes back to that element. Focus the app moved on purpose is left alone: the
+element is focused only while focus is still inside the sheet or has fallen back to the page body, and an element that
+has left the document is skipped.
+
+### Keyboard shortcuts
+
+`Kbd` draws a shortcut as key caps, for a `Tooltip` message, beside a `MenuItemText` in a `MenuItem`, or in a command
+palette: `<Kbd keys={["Mod", "K"]} />`. The root and every cap are `<kbd>` elements. `Mod` is the Command symbol on
+macOS and `Ctrl` elsewhere. On macOS `Shift`, `Alt`/`Option`, `Ctrl`/`Control`, `Meta`/`Cmd`/`Command`, `Enter`, `Escape`,
+`Tab`, `Backspace` and `Delete` are drawn as the symbols of the Mac keyboard; elsewhere the same names, in any case, are drawn as
+`Ctrl`, `Alt`, `Shift`, `Meta`, `Enter`, `Esc`, `Tab`, `Backspace` and `Del`. `" "` and `Space` are the Space key, `+` and
+`Plus` the plus key. Arrow names (`ArrowUp` or `Up`, ...) are arrows everywhere, a single letter is
+upper-cased, and any other key is drawn as given. A `+` stands between the caps elsewhere (`separator` changes it), and
+none on macOS.
+
+Assistive technology skips the caps and reads one text: "Ctrl+K", or "Command K" on macOS (`label` replaces it). The
+platform is the browser's own, found after the page has mounted: the server, and the first client render, draw the
+non-Mac keys so that hydration matches. Pass `platform="mac"` or `platform="other"` for a fixed look, in stories and tests.
+`detectKbdPlatform()` and `kbdKeyLabel(key, platform)` are exported for your own use.
+
+`useKeyboardShortcut` binds one while the component that calls it is mounted, and
+`matchesKeyboardShortcut(event, keys)` answers the same question for your own listener:
+
+```tsx
+import { Kbd, useKeyboardShortcut } from "@smwb/ui-react";
+
+const [open, setOpen] = useState(false);
+useKeyboardShortcut({ keys: ["Mod", "K"], onTrigger: () => setOpen((was) => !was) });
+
+<Button label="Search" onClick={() => setOpen(true)} endIcon={<Kbd keys={["Mod", "K"]} />} />;
+```
+
+The palette does **not** bind its own key: one binding per app, so two palettes never fight over it
+and any opener works. The listener ignores events another handler already used (`defaultPrevented`),
+key repeats and IME compositions, and prevents the default action on a match — Chrome and Firefox
+otherwise take Ctrl+K for their own search. Modifiers must match exactly (Mod+K does not fire on
+Mod+Shift+K), and a single letter or digit also matches by `event.code`, so `["Mod", "K"]` keeps
+working on a keyboard layout that types other letters.
+
+### Command palette (⌘K)
+
+`CommandPalette` is the dialog that key opens: one search field and grouped results, used with the
+keyboard alone. It is built on `Modal` — portaled into `<body>`, `role="dialog"`, closed by Escape
+when it is the top overlay, focus trapped in the field and handed back to the element that opened it.
+
+```tsx
+import { CommandPalette, Kbd, useKeyboardShortcut } from "@smwb/ui-react";
+import type { CommandPaletteGroup, CommandPaletteItem } from "@smwb/ui-react";
+
+const groups: CommandPaletteGroup[] = [
+  {
+    label: "Actions",
+    items: [
+      {
+        id: "new-worktree",
+        label: "New worktree",
+        icon: "add",
+        shortcut: ["Mod", "Shift", "N"],
+        onSelect: newWorktree,
+      },
+      { id: "theme", label: "Toggle dark theme", keywords: ["theme", "night"], onSelect: toggleTheme },
+    ],
+  },
+  { label: "Projects", items: projects.map((p) => ({ id: p.slug, label: p.slug, subtitle: p.owner })) },
+];
+
+<CommandPalette
+  open={open}
+  onOpenChange={setOpen}
+  groups={groups}
+  recent={recent}
+  footer={
+    <>
+      <Kbd keys={["Up"]} /> <Kbd keys={["Down"]} /> to move, <Kbd keys={["Enter"]} /> to run, <Kbd keys={["Esc"]} /> to
+      close
+    </>
+  }
+  onSelect={(item, group) => pushRecent(item, group)}
+/>;
+```
+
+ArrowUp/ArrowDown (and PageUp/PageDown) move the active option, Enter runs it, Escape closes. The
+active option is the first one right away, so Enter runs the top hit; the field keeps the focus and
+points at it with `aria-activedescendant`. An option is named by its label, while its `subtitle` and
+its `Kbd` shortcut are a description, so a screen reader reads "New worktree" and then "acme/web,
+Ctrl+Shift+N". `disabled` items are drawn dimmed and skipped by the arrows.
+
+**Recent items are yours.** The palette draws `recent` as its first group while the query is empty
+and never filters it, but it does not store anything: keep the list where your users keep their
+preferences (local storage, a server, per user) and update it from `onSelect`, which reports the item
+and the group it was chosen from. The recent group arrives there as `{ id: "recent", label: recentLabel, items: recent }`.
+
+**Async search.** `source(query, { signal })` is called after `debounce` (200 ms) of quiet typing and
+only for a query of at least `minQueryLength` (1) characters. Its groups are appended after the
+static ones. Honour `signal` — it is aborted when a newer query, a close or an unmount makes the
+answer useless — and an answer that arrives late is dropped even if you ignored the signal:
+
+```tsx
+const source = async (query: string, { signal }: { signal: AbortSignal }) => {
+  const response = await fetch(`/api/tasks?q=${encodeURIComponent(query)}`, { signal });
+  if (!response.ok) throw new Error(`Search failed: ${response.status}`);
+  return [{ label: "Tasks", items: (await response.json()).map(toItem) }];
+};
+```
+
+While a request is pending the palette draws skeleton rows and marks the listbox `aria-busy`; a
+rejection that is not an abort shows `errorText` and leaves the static matches usable. Results are
+announced politely once the search settles ("3 results", `noResultsText` for none).
+
+**Filtering.** The default `commandPaletteFilter` matches every word of the query against the label,
+the subtitle and `keywords`, ignoring case and accents ("cafe" finds "Café menu"). It never reorders.
+If you rank yourself or search on a server, pass `filter={false}` and send the groups in your order.
+Both `commandPaletteFilter` and `normalizeSearchText` are exported.
+
+Filtering and rendering are linear, so cap what you pass — 50 items per group is a good ceiling — or
+rank on the server. Every text is a prop (`placeholder`, `searchLabel`, `noResultsText`, `errorText`,
+`recentLabel`, `resultsAnnouncement`), so a localized UI needs no wrapper.
+
 ## Icons
 
 `<Icon>` renders one of two icon sets under the **same name**, so switching sets never touches
@@ -241,6 +717,184 @@ needed. Fill them in order: slots 8–12 are unset by default and emit nothing,
 colours as are set. An unset slot is skipped, not kept as a gap: if you set slot 9 but not 8, slot 9's
 colour is drawn for the 8th series. A colour you give in the chart's own `option.color` wins over the theme's.
 
+### Change size (DiffStat)
+
+```tsx
+import { DiffStat } from "@smwb/ui-react";
+
+<DiffStat added={128} removed={37} />
+<DiffStat added={128} removed={37} compact />
+```
+
+How big a change is: `+N −M` (the minus is U+2212, not a hyphen) in the theme's success and error colours, with a
+bar of five cells beside it whose shares match the two figures; the cells a side leaves over are neutral, so `0` and
+`0` leave every cell neutral. Each side takes `floor(5 × its share)` cells, so a side under a fifth of the change reaches
+no cell and shows in its figure only. `compact` is the tab variant: smaller figures and no bar (`bar` turns the bar on
+or off either way). Counts are written with `group`, three digits per group split by U+202F NARROW NO-BREAK SPACE
+(`12 345`) by default; the separator is fixed rather than taken from a locale because the server and the browser
+would group the same figure differently and break hydration, so an app that knows its reader's locale passes
+`group={(n) => n.toLocaleString(locale)}`. Fractions are dropped, a count below zero or one that is not a number (`NaN`, `undefined`, `Infinity`) counts as `0`
+in the figures, the name and the bar alike, and the count is otherwise shown as given, without abbreviating (`1.2k` is
+left to the caller's `group`).
+
+The whole is one `role="img"` with one accessible name, `added 12, removed 3`, and the digits and the cells are
+hidden from assistive technology so nothing is read twice. Translate the name with `format={(added, removed) => ...}`
+(it gets the two counts as numbers, so the default name reads plain digits, `added 12345, removed 3`, and a localiser
+can write them as it likes, e.g. `добавлено 12, удалено 3`), or replace it with `aria-label`. The figures and the
+cells use the theme's success and error colours mixed toward the surface ink (`@diffStatColorMix` in your
+`theme.config`, 55% by default), which keeps text contrast at 5.4:1 or better on the page and the surface in both the
+light and the dark theme; a cell nobody owns is an outline of the surface ink (`@diffStatNeutralMix`, 60%), 3.69:1 or
+better against the page in every bundled theme, so it reads as empty next to a filled cell. See Storybook → **Data Display / DiffStat**.
+
+### Status marker (StatusDot)
+
+```tsx
+import { StatusDot } from "@smwb/ui-react";
+
+<StatusDot status="active" label="Working" />;
+```
+
+`status` is `active` (info, pulses), `attention` (warning), `idle` (neutral), `done` (success), `error` or `unknown`
+(a ring in the outline colour; also the default). `color` takes the theme colour names `Chip` takes and, with no
+`status`, makes a plain disc. `size` is `md` (12px) or `sm` (8px); `pulse` turns the ring on or off (on for `active`
+only, and never drawn under `prefers-reduced-motion: reduce`). `label` is required: the dot is a `role="img"` named
+by it, so screen readers hear the status. For sighted users the filled statuses differ by colour only (`idle` is
+solid and `unknown` a ring), so show the status in text or a tooltip where it matters. Each status colour reaches 3:1 against the surface in the light and dark
+themes (see `@smwb/ui-styles`).
+
+### Participant lanes (Swimlanes)
+
+```tsx
+import { Swimlanes } from "@smwb/ui-react";
+
+<Swimlanes
+  label="Agent team"
+  lanes={[
+    {
+      id: "anna",
+      header: <Who name="Anna" role="Team lead" />,
+      content: <Now item="Release notes" done={7} of={12} />,
+    },
+    { id: "ilya", header: <Who name="Ilya" role="Frontend" />, content: <Now item="Sticky column" done={3} of={9} /> },
+    { id: "vera", header: <Who name="Vera" role="Design" />, content: <Now item="Migration guide" done={0} of={6} /> },
+  ]}
+  onSelectedChange={(id) => openDetails(id)}
+/>;
+```
+
+One row per participant: a header on the left (an avatar, a name, a role) and the content on the right (the current
+item, progress, the last signal, the budget). A lane is `{ id, header, content }`, where `id` is stable and unique —
+it keys the row, the selection and the Tab stop — and `header` and `content` are any nodes. A `disabled` lane stays
+readable and focusable but cannot be selected. Rows are keyed by `id`, so a `lanes` array rebuilt on every refresh
+(`participants.map(toLane)`) keeps its rows, their cells and the focus, and the new content is drawn in place.
+
+The header column stays put while the content scrolls sideways under it. `headerWidth` is its width (240px by
+default; a number of pixels or any CSS length) and `contentMinWidth` the narrowest the content column can be, so a
+grid too narrow for the two together scrolls sideways. Cells clip, so content that needs more room needs a wider
+`contentMinWidth`; an ellipsis inside it is yours.
+
+Every lane is `rowHeight` tall (64px by default) — the rows are virtualised, which needs a fixed height — and the
+grid is `height` tall (480px from the stylesheet, so a height in `style` works too). Only the lanes in view and
+`overscan` more above and below them (4 by default) are in the DOM, so 200 lanes cost about 16 rows, while
+`aria-rowcount` still reports all of them and each row carries its own `aria-rowindex`. On the server, and at the
+first paint before the grid can measure itself, the window is the one `height` implies, so the browser hydrates the
+markup the server sent.
+
+A click in a lane, or Enter or Space on its focused cell, selects it: `selectedId` / `defaultSelectedId` /
+`onSelectedChange(id | null)`, controlled while `selectedId` is not `undefined`, where `null` means "controlled,
+nothing selected". Escape clears the selection, and only when there is one, so an enclosing dialog still gets the
+key. A click on a control _inside_ a lane selects nothing — that click belongs to the control. `selectable={false}`
+turns selection off altogether: nothing is painted or exposed, a `selectedId` given anyway is ignored and Escape is
+left alone. A selected lane that leaves `lanes` clears the selection through `onSelectedChange(null)`.
+
+For assistive technology the grid is a `role="grid"` named by `label` (your `aria-labelledby` wins), two columns
+wide, each lane's header a `rowheader`. Focus is on cells, and the grid is **one Tab stop**: the cell focused last,
+else the selected lane's header, else the first lane's header. Links and buttons inside a lane stay reachable — Tab
+from the active cell walks that lane's own controls and then leaves the grid — so there is no cell edit mode to
+switch into and no F2 to press. Focus on a control inside a lane (a click on its button) makes that lane the Tab stop,
+and the lane holding focus stays in the DOM when it scrolls out of the window and keeps focus when it scrolls back.
+
+| Key                    | Moves to                                                                         |
+| ---------------------- | -------------------------------------------------------------------------------- |
+| ArrowDown / ArrowUp    | the next or the previous lane, same column; no wrap at the ends                  |
+| ArrowRight / ArrowLeft | the content cell / the header cell of the same lane                              |
+| Home / End             | the first / the last cell of the row                                             |
+| Ctrl+Home / Ctrl+End   | the first / the last lane, same column                                           |
+| PageDown / PageUp      | a page of lanes: the rows that fit, less one so a row of context stays on screen |
+| Enter / Space          | selects the lane                                                                 |
+| Escape                 | clears the selection                                                             |
+
+A disabled lane takes focus like any other and is not skipped. Keys pressed inside a lane's own control belong to
+that control, and combinations with Ctrl, Cmd or Alt are the browser's, apart from Ctrl+Home and Ctrl+End. With
+`lanes={[]}` the root carries no grid role at all — an empty grid has no rows — and shows `emptyLabel` instead.
+Colours come from the theme's runtime tokens, so the dark theme follows with no extra rules. See Storybook → **Data
+Display / Swimlanes**.
+
+### QR code (QrCode)
+
+```tsx
+import { QrCode } from "@smwb/ui-react";
+
+<QrCode value="https://mateme.io/pair" caption="Scan with the phone app" />;
+```
+
+`value` (a URL, a pairing token) is encoded as UTF-8 bytes and drawn as an SVG image, `role="img"` named
+"QR code" (rename with `label`). The modules are dark on a white square — the quiet zone is part of the
+white — in every theme, so a phone camera reads the code in dark mode too; the colours are fixed and never
+follow the theme. `size` is the side in pixels, quiet zone included (192 by default); keep at least ~4px per
+module, so a long payload needs a bigger `size` (or a shorter value). `errorCorrection` is `L`/`M` (default)/
+`Q`/`H` — the share of the code that may be damaged or covered; `quietZone` is the light margin in modules
+(4, the spec minimum). `caption` renders a `<figcaption>` under the code, and the figure is named by it.
+A `value` past the QR capacity does not throw: the code renders an empty white square with
+`data-error="too-long"`, named "QR code: value too long". Any other encode failure (a lone surrogate fails in
+`encodeURI`) renders the same empty square with `data-error="encode-failed"`, named "QR code: value could not be
+encoded". Neither throws, and each cause is reported once — a code bound to a growing text field does not add a
+console line per keystroke. The value itself is not exposed to assistive technology (tokens may be secret), so show
+a copyable link or code next to the QR for users who cannot scan.
+Encoding runs on `uqr`, a new runtime dependency of `@smwb/ui-react` (external in the bundle, like `clsx`).
+See Storybook → **Data Display / QR Code**.
+
+### Window title bar (`AppBar variant="window"`)
+
+```tsx
+import { AppBar } from "@smwb/ui-react";
+
+<AppBar
+  variant="window"
+  windowControls="left"
+  title="Untitled document"
+  leftContent={<Button icon={<MenuIcon />} variant="text" aria-label="Main menu" onClick={openMenu} />}
+  rightContent={<Button label="Login" variant="contained" size="small" />}
+/>;
+```
+
+`variant="window"` makes the bar the title bar of a desktop app window (Electron, Tauri, an installed PWA with
+Window Controls Overlay): the bar becomes a drag region (`-webkit-app-region: drag`), so dragging it moves the
+window. Interactive content stays clickable, which matters because Electron delivers no mouse events at all
+inside a drag region. The styles already take `no-drag` on buttons, links, fields, anything focusable or
+role-tagged, and on the library's tooltip wrapper; a custom control that is neither focusable nor role-tagged (a
+plain `div` with an `onClick`) opts out with the `smwb-appbar__no-drag` class or the `data-no-drag` attribute.
+Overlays are excluded from the drag region too — they portal to `<body>`, out of the bar's subtree, while Electron
+hit-tests drag regions by geometry, not by the DOM tree. That covers the layers carrying `data-smwb-overlay-layer`,
+the `Menu`, `Tooltip` and Snackbar popups, and the library's own full-screen portals (the Chat attachment lightbox,
+the ImagesList lightbox, the ThumbCard preview and the ChatShell panel). Roles that keep `tabindex="-1"` while their
+group holds the tab stop (`menuitemcheckbox`, `menuitemradio`, `treeitem`, `spinbutton`, `gridcell`, `listbox`,
+`scrollbar`) are in the list as well, because the focusable rule alone cannot see them. Nothing is inherited by
+`children`, so a bar of your own markup drags the same way.
+
+`windowControls` keeps the content clear of the window buttons the OS draws: `left` for the macOS traffic lights,
+`right` for the Windows/Linux caption buttons, `none` to reserve nothing, and `auto` (the default) for the area the
+shell reports through `env(titlebar-area-*)` — under Window Controls Overlay and Electron's `titleBarOverlay` that
+is the exact rectangle, and in a plain browser tab nothing is reserved. The platform is never sniffed: the app
+knows its own platform, so the server and the browser render the same classes and nothing shifts after hydration.
+In Electron, `titleBarStyle: "hiddenInset"` goes with `windowControls="left"` and `titleBarOverlay` with `"auto"`;
+set the overlay's height to the bar's (65px, or 48px with `dense`).
+
+The reserved width is `@appBarWindowControlsLeft` (64px) and `@appBarWindowControlsRight` (138px), overridable at
+runtime for both sides with `--smui-appBarWindowControlsWidth` (see `@smwb/ui-styles`). A bar without `variant`
+renders exactly as before. See Storybook → **Navigation / AppBar**: `WindowTitleBar`, `WindowTitleBarWindows`,
+`WindowDense`.
+
 ## Customization and theming
 
 Pick the shallowest layer that solves the task: