@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/components/navigation/tabs.en.md

@@ -0,0 +1,71 @@
+---
+component: Tabs
+exports: [Tabs]
+category: navigation
+status: stable
+source: src/components/navigation/Tabs.tsx
+story: src/components/navigation/Tabs.stories.tsx
+sourceHash: cc11d7b9705a
+---
+
+# Tabs
+
+## Summary for AI
+
+`Tabs` is a controlled-only tab strip; the component renders only the tablist, not the
+panels. The consumer stores `value`, applies `onChange` and must render the
+active panel with `id={`${value}-panel`}` and `role="tabpanel"`.
+
+## When to use
+
+- Several peer, instantly switchable views of one context.
+- Vertical settings/sidebar navigation or a horizontal scrolling strip.
+- The active tab state already belongs to the URL or the consuming component.
+
+## When not to use
+
+- For a step-by-step process, use `Stepper`; for independent collapsible blocks,
+  `Accordion`; for switching between format modes, `Segmented`.
+- Do not use tabs if the content of all sections must be visible at once.
+- Do not expect an uncontrolled `defaultValue`: there is none.
+
+## Minimal example
+
+```tsx
+<Tabs items={items} value={tab} onChange={setTab} />
+<div id={`${tab}-panel`} role="tabpanel">{panels[tab]}</div>
+```
+
+## Public API
+
+`items` is an array of `{ id, label, icon? }`; `value` and `onChange` are required.
+`orientation` is `horizontal` (the default) or `vertical`, and `className` styles the
+container. To change orientation with the screen width, choose `orientation` on the
+consumer side. The item id is used to build `aria-controls`, so it must be valid
+as an HTML id and unique within this tablist.
+
+## Accessibility and keyboard
+
+The active tab has `tabIndex=0` and the rest `-1`: Tab enters only the
+active one, and roving focus uses the arrow keys. A horizontal strip moves with
+`←/→`, a vertical one with `↑/↓`; Home/End go to the ends, and the ends do not wrap.
+Selection follows focus (automatic activation). Only the active tab gets
+`aria-controls`, because the consumer may not render inactive panels.
+See the [Tabs source](../../../src/components/navigation/Tabs.tsx).
+
+## Good examples
+
+- A settings sidebar: `orientation="vertical"` and a separate `tabpanel`.
+- A horizontal strip with short labels that allows overflow-x.
+- Icons only as a complement to readable labels.
+
+## Anti-patterns
+
+- Rendering a tablist without a corresponding active panel.
+- Passing a `value` id that is not in `items`.
+- Adding a separate Enter for activation: an arrow key already switches tabs.
+
+## Related sources and Storybook
+
+- `src/components/navigation/Tabs.tsx`
+- `src/components/navigation/Tabs.stories.tsx`

package/docs/components/navigation/tabs.md

@@ -0,0 +1,70 @@
+---
+component: Tabs
+exports: [Tabs]
+category: navigation
+status: stable
+source: src/components/navigation/Tabs.tsx
+story: src/components/navigation/Tabs.stories.tsx
+---
+
+# Tabs
+
+## Кратко для AI
+
+`Tabs` — controlled-only лента вкладок; компонент рендерит только tablist, не
+панели. Потребитель хранит `value`, применяет `onChange` и обязан отрендерить
+активную панель с `id={`${value}-panel`}` и `role="tabpanel"`.
+
+## Когда использовать
+
+- Несколько равноправных мгновенно переключаемых представлений одного контекста.
+- Вертикальная навигация settings/sidebar или горизонтальная лента со скроллом.
+- Состояние активной вкладки уже принадлежит URL или компоненту-потребителю.
+
+## Когда не использовать
+
+- Для пошагового процесса используйте `Stepper`; для независимых сворачиваемых блоков —
+  `Accordion`; для переключения форматных режимов — `Segmented`.
+- Не используйте tabs, если содержимое всех секций должно быть видно одновременно.
+- Не ожидайте uncontrolled `defaultValue`: его нет.
+
+## Минимальный пример
+
+```tsx
+<Tabs items={items} value={tab} onChange={setTab} />
+<div id={`${tab}-panel`} role="tabpanel">{panels[tab]}</div>
+```
+
+## Public API
+
+`items` — массив `{ id, label, icon? }`; `value` и `onChange` обязательны.
+`orientation` — `horizontal` (умолчание) или `vertical`, `className` настраивает
+container. Чтобы ориентация менялась по ширине экрана, выбирайте `orientation` на
+стороне потребителя. Item id формирует `aria-controls`, поэтому он должен быть пригоден
+для HTML id и уникален в этой tablist.
+
+## Доступность и клавиатура
+
+У активной вкладки `tabIndex=0`, у остальных `-1`: Tab входит только в
+активную, а roving focus использует стрелки. По горизонтальной ленте
+перемещаются `←/→`, по вертикальной — `↑/↓`; Home/End идут к краям, края не зацикливаются.
+Выбор следует за фокусом (automatic activation). `aria-controls` получает лишь
+активная вкладка, потому что потребитель может не рендерить неактивные панели.
+См. [исходник Tabs](../../../src/components/navigation/Tabs.tsx).
+
+## Хорошие примеры
+
+- Settings sidebar: `orientation="vertical"` и отдельный `tabpanel`.
+- Горизонтальная лента с короткими подписями, допускающая overflow-x.
+- Иконки только как дополнение к читаемым label.
+
+## Антипаттерны
+
+- Рендерить tablist без панели активной вкладки.
+- Передавать в `value` id, отсутствующий в `items`.
+- Добавлять отдельный Enter для активации: переключение уже происходит стрелкой.
+
+## Связанные исходники и Storybook
+
+- `src/components/navigation/Tabs.tsx`
+- `src/components/navigation/Tabs.stories.tsx`

package/docs/components/navigation/tree-view.en.md

@@ -0,0 +1,173 @@
+---
+component: TreeView
+exports: [TreeView]
+category: navigation
+status: stable
+source: src/components/navigation/TreeView.tsx
+story: src/components/navigation/TreeView.stories.tsx
+sourceHash: 8c71d43035a9
+---
+
+# TreeView
+
+## Summary for AI
+
+A hierarchy with expansion, selection and keyboard support, built on react-aria's `Tree`.
+It stores no state: expanded and selected nodes arrive as sets. The selection
+mode is turned on by `selectionMode` — without it there are no checkboxes at all.
+The current navigation node (an article tree) is marked with `activeKey` — that is
+`aria-current="page"` with no checkboxes and no selection.
+
+## When to use
+
+- A tree of categories, folders, help sections, an organization's structure.
+- A list where nesting matters and has to be expanded.
+- Navigating a tree of articles, sections, documents: the open page is marked
+  with `activeKey`, and `onAction` handles navigation.
+
+## When not to use
+
+- For a flat list with selection, use `Select` or `CheckboxGroup`.
+- For picking from a hierarchy in a field — the kit has no such component (`TreeSelect`):
+  it is assembled from `TreeView` and `Popover`, and adding it without a requesting
+  screen would mean designing blind
+  (ADR-0024).
+
+## Minimal example
+
+```tsx
+import { TreeView, type TreeNode } from "@olddevs/ui";
+
+const items: TreeNode[] = [
+  { id: "nature", label: "Nature", children: [{ id: "forest", label: "Forest" }] },
+  { id: "city", label: "City" },
+];
+
+const [expanded, setExpanded] = useState<Set<Key>>(new Set(["nature"]));
+
+<TreeView
+  items={items}
+  aria-label="Categories"
+  expandedKeys={expanded}
+  onExpandedChange={setExpanded}
+/>;
+```
+
+## Props
+
+| Prop                  | Default | Purpose                                                                                                                |
+| --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `items`               | —       | Nodes: `id`, `label`, optionally `icon`, `children`, `disabled`; `textValue` is required when `label` is not a string. |
+| `aria-label`          | —       | The tree's name. Required, checked by the compiler.                                                                    |
+| `expandedKeys`        | —       | Expanded nodes. The tree does not store them.                                                                          |
+| `onExpandedChange`    | —       | Called with the set of expanded nodes.                                                                                 |
+| `defaultExpandedKeys` | —       | Expanded on first render; after that react-aria drives it.                                                             |
+| `selectionMode`       | —       | Turns on the selection mode: `single` or `multiple`.                                                                   |
+| `selectedKeys`        | —       | Selected nodes.                                                                                                        |
+| `onSelectionChange`   | —       | Called with the selection.                                                                                             |
+| `disabledKeys`        | —       | Unavailable nodes.                                                                                                     |
+| `activeKey`           | —       | The current navigation node: `aria-current="page"` and a backing.                                                      |
+| `onAction`            | —       | An action on a node: navigation, opening. It is not selection.                                                         |
+| `emptyText`           | —       | What to show when there are no nodes.                                                                                  |
+
+## The role is `treegrid`, not `tree`
+
+That is react-aria's decision, and a sound one: a row holds an expand button and a
+checkbox, and a `treeitem` does not expect a second interactive element inside
+itself. Nodes have the `row` role with `aria-level`, `aria-expanded`,
+`aria-posinset` and `aria-setsize`.
+
+The kit will not override roles by hand: then the keyboard from the behavior layer
+would stop matching the markup. In tests nodes are found by
+the `row` role — that is not a workaround but an exact reflection of what the screen reader sees.
+
+## No state is kept, and `useTreeData` is not exported
+
+The rule is the same as for `Table`: expanded and selected nodes arrive as sets
+(ADR-0023).
+
+The kit does **not** re-export react-aria's `useTreeData`. It is a store, and the kit
+does not own state; whoever needs a ready-made one takes it from
+`react-aria-components` directly, and then it is their choice, not one imposed by the kit.
+
+## The selection mode is turned on by `selectionMode`
+
+Without it there are neither checkboxes nor `aria-selected` in the markup: a category tree that
+users only browse should not drag in a selection column. The same rule as for
+`Table`.
+
+`onAction` is not selection: it is navigation or opening a card.
+
+## The current node: `activeKey`
+
+A navigation tree, such as a knowledge base or a structure of sections, shows "you are
+here", not a set of checked items. The selection mode does not fit: `selectionMode`
+renders a checkbox in every row and sets `aria-selected`, while the current page
+is a place, not a choice. Hence a separate prop:
+
+```tsx
+<TreeView
+  items={articles}
+  aria-label="Articles"
+  activeKey={articleId}
+  onAction={(id) => openArticle(id)}
+/>
+```
+
+- The node whose key equals `activeKey` gets `aria-current="page"` on its row and a
+  `bg-3` backing with a semibold label, like `NavItem` with `active`. If the key is not
+  among the nodes or the prop is not set, nothing is marked.
+- The tree **does not move "current" by itself**: a click on a leaf calls `onAction`,
+  and the consumer passes the new `activeKey` when the route has changed. Like
+  selection and expansion, it is a value, not kit state.
+- No checkboxes, no `aria-selected`. With `selectionMode` the current node and the
+  selection can be kept together — they are two independent sets.
+- A node inside a collapsed folder is absent from the markup and has no mark until
+  the folder is expanded. Expanding the path to the open article is the consumer's job,
+  through `expandedKeys`.
+
+**The name is `activeKey`, not `currentKey` and not `selectedKey`.** In the kit's
+vocabulary ([conventions.md](../../conventions.md)) `active` is reserved for one meaning: the
+current navigation item, `aria-current="page"`; `selected` is a choice in a set. The
+tree holds not items but data addressed by keys, so a boolean `active` on a node does
+not fit: following `selectedKeys`, `expandedKeys` and `disabledKeys`, the prop takes a
+key. One value, not a set: a navigation has only one current page.
+
+## An action on a folder does not expand it
+
+When `onAction` is set, a click on a folder row calls `onAction` with its key but
+**does not expand the folder**. The chevron and the Right Arrow key expand a folder
+(the Left Arrow key collapses it): the expand and action gestures are kept apart. This is the
+behavior of react-aria's `Tree`, and the kit does not change it. Without `onAction`
+a click on a row expands the folder.
+
+If the tree should expand a folder on click, do that in `onAction` itself:
+check whether the node has children and update your own `expandedKeys`.
+
+```tsx
+onAction={(id) => (isFolder(id) ? toggle(id) : openArticle(id))}
+```
+
+## Keyboard and names
+
+Arrow keys, Home, End, type-ahead search and expansion come from the behavior layer
+(ADR-0005),
+and are not written by hand; they are verified in a live browser.
+
+The expand button's name is only a verb: "Expand" on a collapsed node and "Collapse" on an
+expanded one, **without** the node label: react-aria
+appends it itself, and "Expand Nature" would be read as "Expand Nature
+Nature". The wave 18 review found the same defect in `TagInput` and `FilterBar`.
+
+The level indent comes from the `--tree-item-level` variable, which react-aria
+puts on the row: computing the depth in the kit would mean keeping a second copy of
+the same number. The indent step is `--tree-indent`.
+
+## Related sources and tests
+
+- Implementation: `src/components/navigation/TreeView.tsx`.
+- Tests: `tests/tree-view.test.tsx` — roles and levels, expansion by a set,
+  no selection mode without the prop, the button name, a disabled node, the empty state,
+  `activeKey` (the mark, changing it with the same `items`, no checkboxes) and the action
+  on a folder; the browser test covers arrow keys, focus movement and `activeKey` moving on click.
+- Story: `src/components/navigation/TreeView.stories.tsx`.

package/docs/components/navigation/tree-view.md

@@ -0,0 +1,172 @@
+---
+component: TreeView
+exports: [TreeView]
+category: navigation
+status: stable
+source: src/components/navigation/TreeView.tsx
+story: src/components/navigation/TreeView.stories.tsx
+---
+
+# TreeView
+
+## Кратко для AI
+
+Иерархия с раскрытием, выбором и клавиатурой на `Tree` из react-aria.
+Состояний не хранит: раскрытые и выбранные узлы приходят множествами. Режим
+выбора включается `selectionMode` — без него флажков нет вовсе. Текущий узел
+навигации (дерево статей) отмечается `activeKey` — это `aria-current="page"`
+без флажков и без выбора.
+
+## Когда использовать
+
+- Дерево категорий, папок, разделов справки, структуры организации.
+- Список, где вложенность существенна и её нужно раскрывать.
+- Навигация по дереву статей, разделов, документов: открытая страница
+  отмечена `activeKey`, переход делает `onAction`.
+
+## Когда не использовать
+
+- Для плоского списка с выбором используйте `Select` или `CheckboxGroup`.
+- Для выбора из иерархии в поле — такого компонента (`TreeSelect`) в ките нет:
+  он собирается из `TreeView` и `Popover`, а заводить его без экрана-заказчика —
+  значит проектировать вслепую
+  (ADR-0024).
+
+## Минимальный пример
+
+```tsx
+import { TreeView, type TreeNode } from "@olddevs/ui";
+
+const items: TreeNode[] = [
+  { id: "nature", label: "Природа", children: [{ id: "forest", label: "Лес" }] },
+  { id: "city", label: "Город" },
+];
+
+const [expanded, setExpanded] = useState<Set<Key>>(new Set(["nature"]));
+
+<TreeView
+  items={items}
+  aria-label="Категории"
+  expandedKeys={expanded}
+  onExpandedChange={setExpanded}
+/>;
+```
+
+## Пропы
+
+| Проп                  | Умолчание | Назначение                                                                                                       |
+| --------------------- | --------- | ---------------------------------------------------------------------------------------------------------------- |
+| `items`               | —         | Узлы: `id`, `label`, опционально `icon`, `children`, `disabled`; `textValue` обязателен, если `label` не строка. |
+| `aria-label`          | —         | Имя дерева. Обязательно, проверяет компилятор.                                                                   |
+| `expandedKeys`        | —         | Раскрытые узлы. Дерево их не хранит.                                                                             |
+| `onExpandedChange`    | —         | Колбэк получает множество раскрытых узлов.                                                                       |
+| `defaultExpandedKeys` | —         | Раскрытые при первом показе; дальше ведёт react-aria.                                                            |
+| `selectionMode`       | —         | Включает режим выбора: `single` или `multiple`.                                                                  |
+| `selectedKeys`        | —         | Выбранные узлы.                                                                                                  |
+| `onSelectionChange`   | —         | Колбэк получает выбранные узлы.                                                                                  |
+| `disabledKeys`        | —         | Недоступные узлы.                                                                                                |
+| `activeKey`           | —         | Текущий узел навигации: `aria-current="page"` и подложка.                                                        |
+| `onAction`            | —         | Действие по узлу: переход, открытие. Выбором не является.                                                        |
+| `emptyText`           | —         | Что показать, когда узлов нет.                                                                                   |
+
+## Роль — `treegrid`, а не `tree`
+
+Так решил react-aria, и решение обоснованное: в строке живут кнопка раскрытия и
+флажок, а `treeitem` второго интерактивного элемента внутри себя не
+предполагает. У узлов роль `row` с `aria-level`, `aria-expanded`,
+`aria-posinset` и `aria-setsize`.
+
+Переопределять роли руками кит не станет: тогда клавиатура из слоя поведения
+перестала бы соответствовать разметке. В тестах узлы и ищутся по
+роли `row` — это не обход, а точное отражение того, что видит скринридер.
+
+## Состояний не хранит, `useTreeData` наружу не идёт
+
+Правило то же, что у `Table`: раскрытые и выбранные приходят множествами
+(ADR-0023).
+
+`useTreeData` из react-aria кит **не** реэкспортирует. Это хранилище, а кит
+состоянием не владеет; кому нужно готовое — берёт его из
+`react-aria-components` напрямую, и тогда это его выбор, а не навязанный китом.
+
+## Режим выбора включается `selectionMode`
+
+Без него ни флажков, ни `aria-selected` в разметке нет: дерево категорий, по
+которому просто ходят, не должно тащить колонку выбора. То же правило, что у
+`Table`.
+
+`onAction` выбором не является: это переход или открытие карточки.
+
+## Текущий узел: `activeKey`
+
+Дерево навигации (база знаний, структура разделов) показывает «вы здесь», а
+не набор отмеченного. Режим выбора для этого не годится: `selectionMode` рендерит
+флажок в каждой строке и выставляет `aria-selected`, а текущая страница — это
+место, а не выбор. Поэтому отдельный проп:
+
+```tsx
+<TreeView
+  items={articles}
+  aria-label="Статьи"
+  activeKey={articleId}
+  onAction={(id) => openArticle(id)}
+/>
+```
+
+- Узел с ключом `activeKey` получает на строке `aria-current="page"` и
+  подложку `bg-3` с полужирной подписью, как у `NavItem` с `active`. Если ключа нет
+  среди узлов или проп не задан, ничего не отмечается.
+- Дерево **само «текущее» не переставляет**: клик по листу вызывает `onAction`, а
+  новый `activeKey` присылает потребитель, когда сменился маршрут. Так же, как
+  выбор и раскрытие, это значение, а не состояние кита.
+- Флажков нет, `aria-selected` нет. С `selectionMode` текущий узел и выбор
+  можно держать вместе — это два независимых набора.
+- Узел внутри свёрнутой папки в разметке отсутствует, и отметки у него нет,
+  пока папку не раскроют. Раскрыть путь до открытой статьи — забота
+  потребителя через `expandedKeys`.
+
+**Имя — `activeKey`, а не `currentKey` и не `selectedKey`.** По словарю кита
+([conventions.md](../../conventions.md)) `active` занят одним смыслом: текущий
+пункт навигации, `aria-current="page"`; `selected` — выбор в наборе. Дерево
+хранит не пункты, а данные по ключам, поэтому булев `active` на узле здесь не
+годится: по образцу `selectedKeys`, `expandedKeys` и `disabledKeys` проп
+принимает ключ. Одно значение, а не набор: страница в навигации одна.
+
+## Действие по папке не раскрывает её
+
+Когда задан `onAction`, клик по строке-папке вызывает `onAction` с
+её ключом — но **папку не раскрывает**. Папку раскрывают шеврон и стрелка вправо
+(сворачивает стрелка влево), то есть жесты раскрытия и действия разведены: это
+поведение `Tree` из react-aria, кит его не меняет. Без `onAction` клик по строке
+раскрывает папку.
+
+Если по клику на папку дерево должно раскрываться, это делается в самом `onAction`:
+определить, что у узла есть дети, и обновить свой `expandedKeys`.
+
+```tsx
+onAction={(id) => (isFolder(id) ? toggle(id) : openArticle(id))}
+```
+
+## Клавиатура и имена
+
+Стрелки, Home, End, поиск набором и раскрытие приходят из слоя поведения
+(ADR-0005),
+а не пишутся руками; проверяются они в живом браузере.
+
+Имя кнопки раскрытия — только глагол: «Раскрыть» у свёрнутого узла и «Свернуть» у
+раскрытого, **без** подписи узла: react-aria
+дописывает её сам, и «Раскрыть Природа» читалось бы как «Раскрыть Природа
+Природа». Тот же дефект ревью волны 18 нашло у `TagInput` и `FilterBar`.
+
+Отступ уровня берётся из переменной `--tree-item-level`, которую react-aria
+кладёт на строку: считать глубину самим — значило бы держать вторую копию того
+же числа. Шаг отступа — `--tree-indent`.
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/navigation/TreeView.tsx`.
+- Тесты: `tests/tree-view.test.tsx` — роли и уровни, раскрытие множеством,
+  отсутствие режима выбора без пропа, имя кнопки, выключенный узел, пустота,
+  `activeKey` (отметка, смена при тех же `items`, без флажков) и действие по
+  папке; браузерный тест — стрелки, переход фокуса и перенос `activeKey` по клику.
+- История: `src/components/navigation/TreeView.stories.tsx`.

package/docs/components/overlays/command-palette.en.md

@@ -0,0 +1,153 @@
+---
+component: CommandPalette
+exports: [CommandPalette]
+category: overlays
+status: stable
+source: src/components/overlays/CommandPalette.tsx
+story: src/components/overlays/CommandPalette.stories.tsx
+sourceHash: c00f29a36684
+---
+
+# CommandPalette
+
+## Summary for AI
+
+`CommandPalette` is a controlled modal search over the app's actions. Pass
+structured `sections` and handle the chosen `id` in `onSelect`; the palette
+searches `label` and `keywords` by itself, closes after a choice and does not
+register a global shortcut to open itself.
+
+For server results, turn off the palette's own search with the `prefiltered: true`
+flag on a section; the query arrives in `onQueryChange`, and `loading` shows
+that a response is pending.
+
+## When to use
+
+- Quick search among actions, especially when there are already many commands.
+- A table of contents of the available commands: with an empty query you need the full list of sections.
+- The actions fall naturally into `CommandSection` groups.
+
+## When not to use
+
+- Use `SearchControl` to filter a list on the screen.
+- Use plain links or tabs to navigate between a few static pages.
+- Do not expect the component to listen for `⌘K` itself: the app owns that
+  shortcut and `open`.
+
+## Minimal example
+
+```tsx
+<CommandPalette
+  open={open}
+  onClose={() => setOpen(false)}
+  sections={[{ id: "files", label: "Files", items: [{ id: "upload", label: "Upload" }] }]}
+  onSelect={(id) => runCommand(id)}
+/>
+```
+
+## Public API
+
+`open`, `onClose`, `sections` and `onSelect` are required. Each section has `id`,
+`label`, `items` and optionally `prefiltered`; an item requires `id`, `label` and
+optionally `shortcut`, `keywords`, `icon`. `placeholder`, `title` and
+`notFoundText` set the strings. `emptyBehaviour="all"` (the default) shows all
+sections on an empty query; `"hint"` shows `emptyHint` instead, until the first
+character is typed.
+
+`onQueryChange(query)` is called with the typed text on every change of the
+field, including a click on the clear button and the reset on close. It only
+notifies you; it does not control the field: the component owns its value.
+Debouncing the query is up to the consumer: how long to wait depends on the cost
+of a query, which the kit cannot know.
+
+`loading` signals that a search is under way on the consumer's side: a `Spinner` appears
+in place of the search icon, and the empty state shows `loadingText` instead of
+`notFoundText` (the default is "Loading"). Results that are already shown are not
+hidden.
+
+**The slot for the icon has a fixed size: the layout sets it.** The
+search icon is 16 pixels, the `Spinner` is 14, and while the slot took its size from
+the icon itself, the field together with the typed text shifted by those two
+pixels every time loading was turned on. The palette's search goes to the
+server, and a request goes out on every change of the field; the text flickered
+in step with the pauses in typing and read not as "loading" but as "the screen is
+reloading". Since 3.26.0 the slot has a fixed size, and it is safe to turn
+`loading` on for every fetch (the consumer's measurement; a browser
+test guards it).
+
+## Server-side search: `prefiltered`
+
+The palette filters the sections it is given by itself. For app actions that is
+right: the set is known in advance and sits in memory in full. For server
+results it is destructive: they have already been filtered, and by different
+rules, and a second pass by substring throws away valid matches.
+
+Take morphology as an example. A `tsvector` search with a Russian dictionary finds
+the task "Подписать договор с подрядчиком" for the query "договоры". A local
+`contains` will never match such a pair: "договоры" is another form of the word
+"договор" in the title, so the substring is not there, and the person sees "nothing
+found" where the server found something.
+`keywords` cannot work around this at all: no matter how many words you put there,
+a substring filter does not become morphological.
+
+`prefiltered: true` on a section turns off local filtering for that section only.
+The order of items is kept as passed: whoever searched did the ranking. Sections
+of both kinds coexist in one list, and the keyboard works in a `prefiltered`
+section exactly the same way: arrow keys, `aria-activedescendant`, choosing with
+Enter.
+
+```tsx
+const [query, setQuery] = useState("");
+const found = useQuery({
+  queryKey: ["task-search", query],
+  queryFn: () => tasksApi.search(query),
+  enabled: query.trim().length >= 2,
+});
+
+<CommandPalette
+  open={open}
+  onClose={close}
+  onQueryChange={setQuery}
+  loading={found.isFetching}
+  sections={[
+    { id: "commands", label: "Commands", items: commands },
+    { id: "tasks", label: "Tasks", items: taskItems, prefiltered: true },
+  ]}
+  onSelect={run}
+/>;
+```
+
+## Accessibility and keyboard
+
+The component combines Radix Dialog and react-aria `Autocomplete`/`ListBox`. The
+field gets autofocus, a hidden title gives the dialog its name, and the list gets
+the same name. Search respects the locale and ignores case and diacritics;
+`keywords` extend the `textValue`. react-aria handles the arrow keys and selection.
+After an item is chosen, `onSelect(id)` is called first, then `onClose`.
+
+The busy state is announced by the `Spinner` itself — it has `role="status"` with
+a hidden label inside. There is deliberately no separate live region with a count
+of results: it would be a second voice saying the same thing, and on locally
+filtered commands it would fire on every typed character.
+
+## Good examples
+
+- An empty list (`emptyBehaviour="hint"`) if there are hundreds of actions.
+- `prefiltered: true` on a section with server results — together with `loading`.
+- `keywords="similar поиск"` on a "Find similar" item: an English name and a Russian synonym.
+- `shortcut={["⌘", "K"]}` to show a command the app already has.
+
+## Anti-patterns
+
+- Storing a callback in `CommandItem` instead of a stable `id`.
+- Introducing sections with duplicate item `id` values.
+- Putting server results into a regular section: the local filter sifts them a
+  second time and throws away valid results.
+- Making network requests directly from `onQueryChange`, without debouncing: the
+  query changes on every character.
+- Leaving the palette open after moving on to the action.
+
+## Related sources and Storybook
+
+- `src/components/overlays/CommandPalette.tsx`
+- `src/components/overlays/CommandPalette.stories.tsx`