@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/components/app-shell/split-panel.en.md

@@ -0,0 +1,148 @@
+---
+component: SplitPanel
+exports: [SplitPanel, useMediaQuery]
+category: app-shell
+status: stable
+source: src/components/app-shell/SplitPanel.tsx
+story: src/components/app-shell/SplitPanel.stories.tsx
+sourceHash: d1bae22a8bfe
+---
+
+# SplitPanel
+
+## Summary for AI
+
+`SplitPanel` lays out two areas separated by a resizable boundary: the content and a details panel. The `position` axis (`side` / `bottom`) changes the layout direction. The size is controlled through `size` + `onSizeChange` or uncontrolled from `defaultSize`; persisting the size between sessions is up to the consumer. On a narrow viewport the panel is collapsed with the `collapsed` prop, and the `useMediaQuery` hook from the same package supplies the width.
+
+## When to use
+
+- A "list on the left, details on the right" screen: the selected row expands next to the list rather than on another page.
+- An inspector under a table: a log, diagnostics, a request preview.
+- The user needs to decide for themselves which area gets the space.
+
+## When not to use
+
+- The details open over the content and demand attention — that is `Drawer` or `Dialog`.
+- The details area is fixed and cannot be resized — that is a plain two-column grid.
+- You need an application navigation column — that is `SideNav` inside `AppShell`.
+
+## Minimal example
+
+```tsx
+<SplitPanel aria-label="Order details" panel={<OrderDetails id={selected} />}>
+  <OrdersTable onSelect={setSelected} />
+</SplitPanel>
+```
+
+## Public API
+
+- `position`: `side` (the default) — the panel is on the right and the user resizes its width; `bottom` — the panel is at the bottom and the user resizes its height.
+- `size` + `onSizeChange` — a controlled size in pixels; `defaultSize` — the initial one when `size` is not passed.
+- `onSizeChange` is called **on every frame** of the drag, but only when the value has actually changed: dragging the boundary past a limit clamps to the same number and stays silent. If you write the size to the page URL or to a server, you do not need every frame: throttling or writing on `pointerup` is the consumer's concern.
+- `defaultSize` is read **once, on mount**: changing the prop later does not move the starting size, otherwise the panel would jump under the user because of a re-render of the parent. A double click still resets the size to the current value of `defaultSize`.
+- `minSize` and `maxSize` are the bounds in pixels. The size is clamped to them both while dragging and when passed as a prop. Narrowing the bounds on the fly corrects the rendered size but does not call `onSizeChange`: an event without a user action would look like the consumer's state being edited against its will. An inverted range (`minSize > maxSize`) breaks nothing — the upper bound is raised to the lower one.
+- `collapsed` collapses the panel **without unmounting** its content. Collapsing in the middle of a drag ends the drag: otherwise the state would outlive the vanished handle, and hovering over a new one would move the boundary without a press.
+- The component has **no** adaptive mode of its own: on a narrow viewport the panel is collapsed with `collapsed={!wide}`, where `wide` comes from `useMediaQuery` — see "Narrow viewports" below.
+- `aria-label` gives the panel a name; without it the panel is not announced as a region.
+- `className` goes on the outer container.
+
+## Narrow viewports: `collapsed` and `useMediaQuery`
+
+Two areas side by side need room: on a screen narrower than 1024 px (the `lg` breakpoint) a side panel squeezes the
+content. What should replace it is the screen's decision, not the component's: just
+one area; the details in a `Drawer` behind a button; the list and the message "one at a
+time" (a mail client). A `SplitPanel` prop that collapses the panel at a narrow width
+would cover only the first, so the standard path is different: the component already
+has `collapsed`, and a public hook supplies the width.
+
+```tsx
+import { SplitPanel, useMediaQuery } from "@olddevs/ui";
+
+const wide = useMediaQuery("(min-width: 1024px)"); // Tailwind's `lg` breakpoint
+
+<SplitPanel aria-label="Order details" collapsed={!wide} panel={<OrderDetails id={selected} />}>
+  <OrdersTable onSelect={setSelected} />
+</SplitPanel>;
+```
+
+`useMediaQuery(query, serverValue = false)` returns whether the media query matches
+right now and re-renders the component when that changes. The query is a plain CSS
+string; the kit's breakpoints are Tailwind 4's defaults: `sm` 640 px, `md` 768 px,
+`lg` 1024 px, `xl` 1280 px.
+
+- **What is shown before hydration.** The server does not know the width. The hook
+  returns `serverValue`, `false` by default: for a `min-width` query that means
+  "narrow", i.e. mobile-first, like Tailwind itself. On the server and in the first
+  client frame the panel is collapsed. During hydration React takes the server value
+  itself and substitutes the real one right after — **with no mismatch error**, but
+  with one re-render: on a wide viewport the panel appears after hydration. If almost
+  all users are on wide screens, `useMediaQuery(query, true)` reverses the default (the
+  first frame is "wide", and a narrow viewport loses the panel after hydration). The
+  choice is the consumer's: the kit does not know which case is more likely.
+- **No `matchMedia`** (jsdom, an old browser) — the hook also returns `serverValue`
+  and does not throw.
+- **It is not a way to lay out a page.** Showing or hiding a block by width is a
+  Tailwind class's job (`hidden lg:block`): a class works from the first frame and on
+  the server with no re-render
+  (ADR-0018). The hook is for
+  when the width changes the composition or the behavior: what to mount, whether to
+  close a drawer, how many months to show.
+- `collapsed` does not unmount the panel's content: a form and the scroll position
+  inside survive the "wide ↔ narrow" transition. Focus that was in the panel moves
+  into the content on collapse.
+
+Two working patterns:
+
+```tsx
+// Details in a drawer: the panel is collapsed, a button opens the drawer on a narrow viewport only.
+<SplitPanel collapsed={!wide} panel={details}>{list}</SplitPanel>
+<Drawer title="Details" open={drawerOpen && !wide} onClose={() => setDrawerOpen(false)}>{details}</Drawer>
+
+// One area at a time: on a narrow viewport SplitPanel is not mounted at all.
+{wide ? <SplitPanel panel={message}>{list}</SplitPanel> : reading ? message : list}
+```
+
+## Size lives with the consumer
+
+The panel can remember its size by itself, but only while it is mounted. Persistent storage — the page
+URL, the user profile — stays with the consumer: they already keep the state
+somewhere, and a second store inside the kit would silently drift from the first. It is the same
+split as for table state (ADR-0023).
+
+With a controlled size the component **does not write the value to itself**: it reports an
+intent through `onSizeChange` and renders whatever size the consumer passes in `size`. Two
+sources of truth would diverge on exactly the frame where the consumer rejects a
+value.
+
+## Why the handle is a real slider
+
+react-aria provides no general-purpose resizer: `ColumnResizer` and
+`ResizableTableContainer`, which work in `Table`, are tied to the table.
+The handle borrows their model — a visible bar plus a hidden `input[type=range]`.
+
+The platform slider brings everything that would otherwise be written by hand and forgotten
+piece by piece: the role, announcing the value and bounds, the step, repeat on hold,
+screen reader support on a touch screen. A `div` with `role="separator"` and
+an arrow-key handler reimplements this at best halfway.
+
+**The slider's value is the panel size, not the boundary coordinate.** That is why the
+right arrow always enlarges the panel, even though the boundary moves left: what is dragged
+is the size, not the divider.
+
+## Keyboard
+
+- The handle is an ordinary tab stop. The arrow keys change the size in 16 px steps, or by one pixel with `Shift`, and `Home` and `End` jump exactly to the bounds.
+- The arrow step lives in the key handler, not in the `step` attribute: the step base of `input[type=range]` is `min`, and `step=16` would allow only the values `min + 16n`. Then `maxSize` could not be reached from the keyboard at all, and the browser would silently round the pixel-precise result of a drag — the announced value would drift from the panel width.
+- A double click on the handle returns `defaultSize`. There is no keyboard path to reset: you can set the size you need in two ways, and the second one (the arrow keys, `Home`, `End`) works from the keyboard.
+- Pressing the bar moves focus to the slider, so a "drag with the mouse, finish with the arrow keys" workflow works.
+- The hit area of the handle is wider than the visible bar: the bar itself is 10 px and the target is 26 px; WCAG 2.5.8 requires at least 24 px.
+- While dragging with a pointer, text selection in the neighboring areas is turned off: otherwise moving past the bar highlights half the list.
+
+## Accessibility and semantics
+
+- The handle's name comes from the message catalog: with the panel's name — "Изменить размер: Детали заказа" / Resize: Order details, without it — "Изменить размер панели" / Resize the panel. There can be several handles on screen, and a shared name would not tell them apart.
+- The current size is announced through `aria-valuetext` with plural forms from the locale.
+- Both areas are scrollable and therefore focusable (`tabindex="0"`): `Tab` does not reach content that scrolls only with a pointer — the axe rule `scrollable-region-focusable`. A collapsed panel drops out of the tab order along with everything else.
+- A collapsed panel leaves the accessibility tree: if `Tab` reaches a panel that cannot be seen, focus is lost. Its content stays mounted. If focus was inside the panel at the moment of collapsing, it is moved to the content area (the handle disappears on collapse) — otherwise it would stay on a hidden node and the next `Tab` would start from the top of the page.
+- The component does not touch `--topbar-h` (ADR-0016): it takes the area it is given and does not stick to the top.
+- See `src/components/app-shell/SplitPanel.tsx`, `src/hooks/useMediaQuery.ts`, `src/components/app-shell/SplitPanel.stories.tsx` (the `Adaptive` story), `tests/split-panel.test.tsx`, `tests/use-media-query.test.tsx`, `tests-visual/interactions.spec.ts`.

package/docs/components/app-shell/split-panel.md

@@ -0,0 +1,147 @@
+---
+component: SplitPanel
+exports: [SplitPanel, useMediaQuery]
+category: app-shell
+status: stable
+source: src/components/app-shell/SplitPanel.tsx
+story: src/components/app-shell/SplitPanel.stories.tsx
+---
+
+# SplitPanel
+
+## Кратко для AI
+
+`SplitPanel` — две области с изменяемой границей: содержимое и панель деталей. Ось `position` (`side` / `bottom`) меняет направление раскладки. Размер управляемый через `size` + `onSizeChange` либо неуправляемый от `defaultSize`; хранение размера между сеансами — дело потребителя. На узком экране панель схлопывается пропом `collapsed`, а ширину даёт хук `useMediaQuery` из того же пакета.
+
+## Когда использовать
+
+- Экран «список слева, детали справа»: выбранная строка раскрывается рядом, а не на другой странице.
+- Инспектор под таблицей: журнал, диагностика, предпросмотр запроса.
+- Пользователю нужно самому решать, чему отдать место.
+
+## Когда не использовать
+
+- Детали открываются поверх содержимого и требуют внимания — это `Drawer` или `Dialog`.
+- Область деталей фиксирована и не меняется пользователем — это обычная сетка из двух колонок.
+- Нужна колонка навигации приложения — это `SideNav` внутри `AppShell`.
+
+## Минимальный пример
+
+```tsx
+<SplitPanel aria-label="Детали заказа" panel={<OrderDetails id={selected} />}>
+  <OrdersTable onSelect={setSelected} />
+</SplitPanel>
+```
+
+## Public API
+
+- `position`: `side` (по умолчанию) — панель справа, пользователь меняет её ширину; `bottom` — панель снизу, пользователь меняет высоту.
+- `size` + `onSizeChange` — управляемый размер в пикселях; `defaultSize` — начальный, когда `size` не передан.
+- `onSizeChange` зовётся **на каждом кадре** перетаскивания, но только когда значение действительно изменилось: тяга за границу зажимается в то же число и молчит. Если размер пишется в адрес страницы или на сервер, каждый кадр туда не нужен: throttle или запись по `pointerup` — забота потребителя.
+- `defaultSize` читается **один раз, при монтировании**: смена пропа потом стартовый размер не двигает, иначе панель прыгала бы под пользователем от перерисовки родителя. Двойной щелчок по-прежнему возвращает к текущему значению `defaultSize`.
+- `minSize` и `maxSize` — границы в пикселях. Размер зажимается ими и при перетаскивании, и при передаче пропом. Сужение границ на лету исправляет показанный размер, но `onSizeChange` не зовёт: событие без действия пользователя выглядело бы как правка состояния потребителя не по его воле. Перевёрнутый диапазон (`minSize > maxSize`) ничего не ломает — верхняя граница поднимается до нижней.
+- `collapsed` схлопывает панель, **не размонтируя** её содержимое. Схлопывание посреди перетаскивания прекращает тягу: иначе состояние пережило бы исчезнувшую ручку, и наведение на новую двигало бы границу без нажатия.
+- Адаптивного режима у компонента **нет**: на узком экране панель схлопывает `collapsed={!wide}`, где `wide` даёт `useMediaQuery` — см. «Узкий экран» ниже.
+- `aria-label` даёт панели имя; без него она не объявляется областью.
+- `className` ложится на внешний контейнер.
+
+## Узкий экран: `collapsed` и `useMediaQuery`
+
+Две области в ряд требуют места: на экране уже 1024 px (брейкпоинт `lg`) панель сбоку сжимает содержимое.
+Что должно быть вместо неё — решает экран, а не компонент: просто одна область;
+детали в `Drawer` по кнопке; список и сообщение «по одному» (почтовый клиент).
+Проп `SplitPanel`, схлопывающий панель на узкой ширине, покрыл бы только первое,
+поэтому штатный путь другой: компонент уже умеет `collapsed`, а ширину
+даёт публичный хук.
+
+```tsx
+import { SplitPanel, useMediaQuery } from "@olddevs/ui";
+
+const wide = useMediaQuery("(min-width: 1024px)"); // брейкпоинт `lg` Tailwind
+
+<SplitPanel aria-label="Детали заказа" collapsed={!wide} panel={<OrderDetails id={selected} />}>
+  <OrdersTable onSelect={setSelected} />
+</SplitPanel>;
+```
+
+`useMediaQuery(query, serverValue = false)` возвращает, выполняется ли
+медиазапрос сейчас, и перерисовывает компонент, когда это меняется. Запрос —
+обычная строка CSS; брейкпоинты кита — штатные Tailwind 4: `sm` 640 px, `md`
+768 px, `lg` 1024 px, `xl` 1280 px.
+
+- **Что показывается до гидратации.** Сервер ширины не знает. Хук отдаёт
+  `serverValue`, по умолчанию `false`: для запроса `min-width` это «узко», то
+  есть mobile-first, как у самого Tailwind. На сервере и в первом кадре
+  клиента панель схлопнута. React при гидратации сам берёт серверное значение
+  и сразу после подставляет настоящее — **без ошибки расхождения**, но с одной
+  перерисовкой: на широком экране панель появляется после гидратации. Если почти
+  все пользователи на широких экранах, `useMediaQuery(query, true)` меняет умолчание
+  на противоположное (первый кадр «широко», на узком экране панель схлопывается
+  после гидратации). Выбор — за потребителем: кит не знает, какой случай вероятнее.
+- **Нет `matchMedia`** (jsdom, старый браузер) — хук тоже отдаёт `serverValue`
+  и не бросает.
+- **Это не способ раскладывать страницу.** Показать или спрятать блок по ширине
+  надо Tailwind-классом (`hidden lg:block`): класс работает с первого кадра и
+  на сервере без перерисовки
+  (ADR-0018). Хук нужен,
+  когда от ширины зависит состав или поведение: что смонтировать, закрывать ли
+  ящик, сколько месяцев показать.
+- `collapsed` не размонтирует содержимое панели: форма и прокрутка внутри
+  переживают переход «широко ↔ узко». Фокус, стоявший в панели, при схлопывании
+  уходит в содержимое.
+
+Два рабочих шаблона:
+
+```tsx
+// Детали в ящике: панель схлопнута, ящик открывается по кнопке только на узком.
+<SplitPanel collapsed={!wide} panel={details}>{list}</SplitPanel>
+<Drawer title="Детали" open={drawerOpen && !wide} onClose={() => setDrawerOpen(false)}>{details}</Drawer>
+
+// Одна область за раз: на узком экране SplitPanel не монтируется вовсе.
+{wide ? <SplitPanel panel={message}>{list}</SplitPanel> : reading ? message : list}
+```
+
+## Размер живёт у потребителя
+
+Панель умеет помнить размер сама, но только пока смонтирована. Хранение между
+сеансами (адрес страницы, профиль пользователя) остаётся за потребителем: у него состояние уже
+где-то лежит, и второе хранилище внутри кита разошлось бы с первым молча. То же
+разделение, что у состояния таблицы (ADR-0023).
+
+При управляемом размере компонент **не пишет значение себе**: он сообщает
+намерение через `onSizeChange` и показывает размер, который потребитель передал в `size`. Два
+источника правды разошлись бы ровно на том кадре, где потребитель отклонит
+значение.
+
+## Почему ручка — настоящий ползунок
+
+Универсального компонента для изменения размера react-aria не даёт: `ColumnResizer` и
+`ResizableTableContainer`, которые работают в `Table`, привязаны к таблице.
+Взята их модель — видимая полоса плюс скрытый `input[type=range]`.
+
+Ползунок платформы приносит с собой всё, что иначе пишется руками и забывается
+по частям: роль, объявление значения и границ, шаг, повтор при удержании,
+поддержку скринридеров на сенсорном экране. `div` с `role="separator"` и
+обработчиком стрелок повторяет это в лучшем случае наполовину.
+
+**Значение ползунка — размер панели, а не координата границы.** Поэтому стрелка
+вправо всегда увеличивает панель, хотя граница при этом уезжает влево: тянут
+размер, а не разделитель.
+
+## Клавиатура
+
+- Ручка — обычный табстоп. Стрелки меняют размер шагом 16 px, со `Shift` — по одному пикселю, `Home` и `End` уводят ровно на границы.
+- Шаг стрелки живёт в обработчике клавиш, а не в атрибуте `step`: шаговая база `input[type=range]` — это `min`, и `step=16` разрешил бы только значения `min + 16n`. Тогда `maxSize` не взялся бы с клавиатуры вовсе, а попиксельный результат тяги браузер молча округлял бы — объявленное значение разошлось бы с шириной панели.
+- Двойной щелчок по ручке возвращает `defaultSize`. Клавиатурного пути к сбросу нет: нужный размер можно задать двумя способами, и второй (стрелки, `Home`, `End`) с клавиатуры работает.
+- Нажатие на полосу переводит фокус на ползунок, поэтому сценарий «потянул мышью, дотяну стрелками» работает.
+- Зона попадания у ручки шире видимой полосы: сама полоса 10 px, цель — 26 px; WCAG 2.5.8 требует не меньше 24 px.
+- Пока тянут указателем, выделение текста в соседних областях выключено: иначе движение мимо полосы подсвечивает половину списка.
+
+## Доступность и семантика
+
+- Имя ручки приходит из каталога: с именем панели — «Изменить размер: Детали заказа» / Resize: Order details, без него — «Изменить размер панели» / Resize the panel. Ручек на экране бывает несколько, и одинаковое имя не помогает их различить.
+- Текущий размер объявляется через `aria-valuetext` со склонением из локали.
+- Обе области прокручиваемы и потому фокусируемы (`tabindex="0"`): до содержимого, которое прокручивается только указателем, `Tab` не доводит — правило axe `scrollable-region-focusable`. Схлопнутая панель из табуляции при этом выпадает вместе со всем остальным.
+- Схлопнутая панель уходит из дерева доступности: если до панели доходит `Tab`, а самой её не видно, фокус теряется. Содержимое при этом остаётся смонтированным. Если фокус в момент схлопывания стоял внутри панели, он переводится в область содержимого (ручка при схлопывании исчезает) — иначе он оставался бы на скрытом узле и следующий `Tab` начинал обход с начала страницы.
+- `--topbar-h` компонент не трогает (ADR-0016): он занимает данную ему область и наверх ни к чему не липнет.
+- См. `src/components/app-shell/SplitPanel.tsx`, `src/hooks/useMediaQuery.ts`, `src/components/app-shell/SplitPanel.stories.tsx` (история `Adaptive`), `tests/split-panel.test.tsx`, `tests/use-media-query.test.tsx`, `tests-visual/interactions.spec.ts`.

package/docs/components/app-shell/top-bar.en.md

@@ -0,0 +1,103 @@
+---
+component: TopBar
+exports: [TopBar]
+category: app-shell
+status: stable
+source: src/components/app-shell/TopBar.tsx
+story: src/components/app-shell/TopBar.stories.tsx
+sourceHash: 53daaa81276d
+---
+
+# TopBar
+
+## Summary for AI
+
+The application header: brand, search and action slots, sticky positioning, a translucent
+background on a theme token. It publishes **its own measured height** to a CSS variable
+(`--topbar-h` by default), which `useStickyOffset` reads. This is why
+`SelectionBar` sits flush under the header without a single line of code from
+the consumer.
+
+## When to use
+
+- The application's top bar: brand, global search, notifications, the user menu.
+- Inside `AppShell` or on its own — the header does not require the shell.
+
+## When not to use
+
+- For a page title with a description and actions — that is `PageHeader`.
+- For actions on selected rows — that is `SelectionBar`; for the title, counter,
+  filters and settings of a table — `TableToolbar` (since 2.2.0).
+- For a dialog header — that is `ModalHeader`.
+
+## Minimal example
+
+```tsx
+import { Avatar, Button, SearchControl, TopBar } from "@olddevs/ui";
+import { BellIcon } from "@olddevs/ui/icons";
+
+<TopBar
+  brand={<Logo />}
+  search={<SearchControl label="Search" value={q} onChange={setQ} />}
+  actions={
+    <>
+      <Button variant="ghost" iconOnly icon={<BellIcon />} aria-label="Notifications" />
+      <Avatar name="JD" />
+    </>
+  }
+/>;
+```
+
+## Props
+
+| Prop        | Default         | Purpose                                                                |
+| ----------- | --------------- | ---------------------------------------------------------------------- |
+| `brand`     | —               | The leftmost slot: a logo, the product name.                           |
+| `search`    | —               | The central slot. Takes the free space; if absent, the space is empty. |
+| `actions`   | —               | Actions on the right: notifications, settings, the user menu.          |
+| `children`  | —               | Extra header content: placed after the `actions` slot.                 |
+| `heightVar` | `"--topbar-h"`  | The name of the height variable. `null` turns publishing off.          |
+| `label`     | message catalog | The header's accessible name.                                          |
+
+## Height contract
+
+The header measures itself with a `ResizeObserver` and writes the height to
+`document.documentElement` — where `useStickyOffset` looks for it. An observer,
+not a one-off measurement: the height changes with the breakpoint and with the
+wrapping of slot content, and the sticky bar under the header has to move
+along with it.
+
+**This is not the option "the kit finds and measures the header"** — the one rejected in
+ADR-0016.
+There the kit would have to recognize an element it does not own by a selector or attribute; here
+the component measures itself, and the kit never learns which element in
+this application is the header. The analysis is in
+ADR-0019.
+
+**A departing header does not remove a value it did not publish.** When it unmounts, it removes
+the variable only if the variable is still its own: two headers with the same name replace
+each other when navigating between screens, and otherwise the first would remove a value already
+published by the second.
+
+**Two headers in one document is a real case** (an application header and the header of
+an embedded widget). They would silently overwrite each other's variable: the sticky
+bars would shift to the other header's height, and it would show up not as an error but as a broken
+layout. So the second header gets a different variable name, or publishing
+is turned off:
+
+```tsx
+<TopBar heightVar="--widget-topbar-h" />
+<TopBar heightVar={null} />
+```
+
+**An external header keeps working.** An application with a non-kit header and without `TopBar`
+publishes the variable itself, as before 2.1.0 — the ADR-0016 contract is untouched.
+
+## Related sources and tests
+
+- Implementation: `src/components/app-shell/TopBar.tsx`.
+- Tests: `tests/top-bar.test.tsx` — the landmark and its name, publishing and removing the
+  variable, a custom variable name, turning publishing off.
+- In a live browser: `tests-visual/interactions.spec.ts` — the published
+  value matches the measured height, and the bar sits flush.
+- Story: `src/components/app-shell/TopBar.stories.tsx`.

package/docs/components/app-shell/top-bar.md

@@ -0,0 +1,100 @@
+---
+component: TopBar
+exports: [TopBar]
+category: app-shell
+status: stable
+source: src/components/app-shell/TopBar.tsx
+story: src/components/app-shell/TopBar.stories.tsx
+---
+
+# TopBar
+
+## Кратко для AI
+
+Шапка приложения: слоты бренда, поиска и действий, липкость, полупрозрачная
+подложка на токене темы. Публикует **свою измеренную высоту** в CSS-переменную
+(по умолчанию `--topbar-h`), которую читает `useStickyOffset`. Поэтому
+`SelectionBar` встаёт вплотную под шапку без единой строки кода у потребителя.
+
+## Когда использовать
+
+- Шапка приложения: бренд, глобальный поиск, уведомления, меню пользователя.
+- Внутри `AppShell` или самостоятельно — шапка не требует каркаса.
+
+## Когда не использовать
+
+- Для заголовка страницы с описанием и действиями — это `PageHeader`.
+- Для действий над выбранными строками — это `SelectionBar`; для заголовка,
+  счётчика, фильтров и настроек таблицы — `TableToolbar` (с 2.2.0).
+- Для шапки диалога — это `ModalHeader`.
+
+## Минимальный пример
+
+```tsx
+import { Avatar, Button, SearchControl, TopBar } from "@olddevs/ui";
+import { BellIcon } from "@olddevs/ui/icons";
+
+<TopBar
+  brand={<Logo />}
+  search={<SearchControl label="Поиск" value={q} onChange={setQ} />}
+  actions={
+    <>
+      <Button variant="ghost" iconOnly icon={<BellIcon />} aria-label="Уведомления" />
+      <Avatar name="ИП" />
+    </>
+  }
+/>;
+```
+
+## Пропы
+
+| Проп        | Умолчание      | Назначение                                                      |
+| ----------- | -------------- | --------------------------------------------------------------- |
+| `brand`     | —              | Крайний левый слот: логотип, название продукта.                 |
+| `search`    | —              | Центральный слот. Занимает свободное место; нет — место пустое. |
+| `actions`   | —              | Действия справа: уведомления, настройки, меню пользователя.     |
+| `children`  | —              | Дополнительное содержимое шапки: после слота `actions`.         |
+| `heightVar` | `"--topbar-h"` | Имя переменной с высотой. `null` отключает публикацию.          |
+| `label`     | каталог        | Доступное имя шапки.                                            |
+
+## Контракт высоты
+
+Шапка измеряет себя `ResizeObserver` и пишет высоту в
+`document.documentElement` — туда, где её ищет `useStickyOffset`. Наблюдатель, а
+не разовый замер: высота меняется от брейкпоинта и от переноса содержимого
+слотов, и липкая полоса под шапкой обязана переезжать вместе с ней.
+
+**Это не вариант «кит находит и измеряет шапку»** — тот, что отвергнут в
+ADR-0016.
+Там киту пришлось бы опознавать по селектору или атрибуту элемент, которого он не создавал; здесь
+компонент измеряет себя, и знание «какой элемент в этом приложении шапка» у кита
+не появляется. Разбор —
+ADR-0019.
+
+**Уходящая шапка не снимает значение, которое не она опубликовала.** Размонтируясь, она убирает
+переменную только если та всё ещё её: две шапки с одним именем сменяют друг
+друга при переходе между экранами, и иначе первая снимала бы значение, уже
+опубликованное второй.
+
+**Две шапки в одном документе — реальный случай** (шапка приложения и шапка
+встроенного виджета). Они молча перезаписывали бы переменную друг друга: липкие
+полосы сдвинулись бы на высоту другой шапки, причём проявилось бы это не
+ошибкой, а сбитой раскладкой. Поэтому второй шапке задают другое имя переменной
+либо выключают публикацию:
+
+```tsx
+<TopBar heightVar="--widget-topbar-h" />
+<TopBar heightVar={null} />
+```
+
+**Внешняя шапка продолжает работать.** Приложение с шапкой не из кита, без `TopBar`,
+публикует переменную само, как и до 2.1.0 — контракт ADR-0016 не тронут.
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/app-shell/TopBar.tsx`.
+- Тесты: `tests/top-bar.test.tsx` — landmark и его имя, публикация и снятие
+  переменной, заданное потребителем имя переменной, отключение публикации.
+- В живом браузере: `tests-visual/interactions.spec.ts` — опубликованное
+  значение совпадает с измеренной высотой, полоса встаёт вплотную.
+- История: `src/components/app-shell/TopBar.stories.tsx`.

package/docs/components/content/avatar.en.md

@@ -0,0 +1,123 @@
+---
+component: Avatar
+exports: [Avatar, AvatarGroup]
+category: content
+status: stable
+source: src/components/content/Avatar.tsx, src/components/content/AvatarGroup.tsx
+story: src/components/content/Avatar.stories.tsx, src/components/content/AvatarGroup.stories.tsx
+sourceHash: 5daaa4cb2e8d
+---
+
+# Avatar and AvatarGroup
+
+## Summary for AI
+
+`Avatar` shows a photo from `src` or, if there is none or it failed to load,
+initials and a stable gradient computed from the name. `AvatarGroup` shows
+participants compactly (strings or `{ name, src? }`) and announces the whole list
+under a single accessible name. It represents a person or participants; it is
+not a status badge or a profile button.
+
+## When to use
+
+- `Avatar` — to represent a user compactly: with a photo from `src` or with
+  initials alone.
+- `AvatarGroup` — when it matters that there is a group and it is fine to show only the
+  first few participants with a `+N` remainder; for example, the participants of a campaign.
+  Photos are passed as `{ name, src }` objects.
+- The photo on `Avatar` was added "for the future" (ADR-0048): there was no
+  requesting screen at release, and the API was modeled on comparable kits: in all twelve kits
+  compared, the avatar has a photo that falls back to initials. Your screen is
+  the first to test this API; if it needs a different one, that is not a violation of the contract.
+
+## When not to use
+
+- Do not replace the initials with your own image fallback: the fallback to
+  initials when the photo is missing or fails to load is built in, and `Avatar`
+  has no separate `fallback`.
+- Do not use it for arbitrary images (a logo, a document preview); use
+  `Image` instead: the avatar is a fixed-size circle with an accessible name derived from a person's
+  name.
+- Do not pass partial initials to `AvatarGroup` instead of names: the group's
+  accessible name is built from `names`.
+- Do not use the group as an interactive list of participants. Selecting or
+  opening a profile needs a separate control.
+
+## Minimal example
+
+```tsx
+import { Avatar, AvatarGroup } from "@olddevs/ui";
+
+<Avatar name="Anna Smith" />
+<Avatar name="Anna Smith" src="/avatars/anna.jpg" />
+<AvatarGroup names={["Anna Smith", "John Peterson", "Oliver Cooper"]} />
+<AvatarGroup names={[{ name: "Anna Smith", src: "/avatars/anna.jpg" }, "John Peterson"]} />
+```
+
+## Public API
+
+### `Avatar`
+
+| Prop                              | Default | Meaning                                                                                                                                                                         |
+| --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`                            | `"IV"`  | A name or login; the first two characters become the initials, the first character sets the stable hue.                                                                         |
+| `size`                            | `md`    | `md` is a compact size for lists and headers; `lg` is a large size for a profile card.                                                                                          |
+| `src`                             | —       | Photo URL. While the photo loads, a circle in the name's hue is shown; if it is missing or fails to load, initials appear on the same circle. An empty value counts as missing. |
+| `alt`                             | `name`  | The photo's alt text. `""` — decorative (the name is already written next to it). With neither `name` nor `alt` the photo is decorative. No effect without `src`.               |
+| `className` and `span` attributes | —       | Passed to the root `span`; `children` is intentionally not supported.                                                                                                           |
+
+### `AvatarGroup`
+
+| Prop         | Default                      | Meaning                                                                        |
+| ------------ | ---------------------------- | ------------------------------------------------------------------------------ |
+| `names`      | —                            | Required full list: a name string or `{ name, src? }`; the forms can be mixed. |
+| `max`        | `3`                          | Number of visible avatars; the remainder is shown as `+N`.                     |
+| `size`       | `md`                         | Size of all visible avatars: `md` or `lg`.                                     |
+| `aria-label` | all `names`, comma-separated | Overrides the group's single accessible name.                                  |
+| `className`  | —                            | Class of the root group.                                                       |
+
+## Photo and fallback to initials
+
+The photo is rendered through the kit's `Image` (ADR-0011): loading and failure are
+handled in one place. The background layer with the hue from the name sits on the
+circle's root, so the size does not change between "loading", "loaded" and
+"failed", and the circle does not flicker: first you see a circle in the name's
+color, then the photo or the initials. Once the photo has loaded, the background
+layer is removed, so a transparent PNG is not tinted with the name's hue. The
+avatar has no `Skeleton`. The photo is fitted with `cover` and is not distorted;
+the circle and the `md`/`lg` sizes do not change. Changing `src` after an error
+tries the new URL. Without `src`, the markup, appearance and announcement do not change.
+
+## Accessibility
+
+`AvatarGroup` renders as a single `role="img"` with the full list of names. The
+inner circles and `+N` are hidden from the screen reader, so it does not read
+useless two-letter initials or repeat the name for a photo: the group announces
+the list. Do not remove `names` to shorten the display.
+
+A single `Avatar` with a photo is an `img` named from `alt` (by default `name`);
+if the photo fails to load, the initials keep the same name. Without `src` the
+avatar carries no role, and its text is the initials. Next to a person's written
+name, set `alt=""` so the name is not spoken twice.
+
+## Anti-patterns
+
+```tsx
+// Bad: the screen reader gets abbreviations, not names.
+<AvatarGroup names={["AS", "JP"]} />
+
+// Good: keep names that people can understand.
+<AvatarGroup names={["Anna Smith", "John Peterson"]} max={2} />
+
+// Bad: the name is already written next to it, so the photo is announced a second time.
+<><Avatar name="Anna Smith" src={url} /> Anna Smith</>
+
+// Good: the photo is decorative.
+<><Avatar name="Anna Smith" src={url} alt="" /> Anna Smith</>
+```
+
+## Related sources and Storybook
+
+- Sources: `src/components/content/Avatar.tsx`, `src/components/content/AvatarGroup.tsx`.
+- Stories: `src/components/content/Avatar.stories.tsx`, `src/components/content/AvatarGroup.stories.tsx`.
+- The group's accessible name is tested in `tests/data.test.tsx`; the photo, the fallback to initials and the unchanged markup without `src` — in `tests/avatar.test.tsx`.