@olddevs/ui 0.0.0-stage → 4.0.0

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

@@ -0,0 +1,172 @@
+---
+component: AppShell
+exports: [AppShell]
+category: app-shell
+status: stable
+source: src/components/app-shell/AppShell.tsx
+story: src/components/app-shell/AppShell.stories.tsx
+sourceHash: 854d2f42944d
+---
+
+# AppShell
+
+## Summary for AI
+
+The application shell: navigation on the left, a header on top, content in `<main>`,
+an optional right area and a bottom bar. It handles the skip link,
+the mobile mode (navigation moves into a `Drawer`) and focus return on route
+change. It knows nothing about the router: the `routeKey` prop marks a screen change.
+
+## When to use
+
+- An application page with permanent navigation: an admin panel, an account area, a console.
+- Anywhere you need landmarks, a skip link and predictable focus on navigation.
+
+## When not to use
+
+- For a standalone page without navigation — the shell adds nothing there.
+- For layout inside a page (two columns, a card grid) — that is plain CSS.
+- For a modal scenario — use `Dialog` or `Drawer`.
+
+## Minimal example
+
+```tsx
+import { AppShell, NavGroup, NavItem, SideNav, TopBar } from "@olddevs/ui";
+
+<AppShell
+  routeKey={pathname}
+  sidebar={
+    <SideNav>
+      <NavGroup label="Work">
+        <NavItem label="Dashboard" icon={<DashboardIcon />} active asChild>
+          <Link href="/dashboard" />
+        </NavItem>
+      </NavGroup>
+    </SideNav>
+  }
+  header={<TopBar brand={<Logo />} actions={<UserMenu />} />}
+>
+  <PageContent />
+</AppShell>;
+```
+
+## Props
+
+| Prop                 | Default           | Purpose                                                                                                                                                   |
+| -------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sidebar`            | —                 | Navigation on the left. On narrow screens it moves into a `Drawer`.                                                                                       |
+| `header`             | —                 | The header. Usually `TopBar`.                                                                                                                             |
+| `banners`            | —                 | Application-level messages above the header. Usually `Banner`.                                                                                            |
+| `aside`              | —                 | The right area. An unnamed slot with no resize handle.                                                                                                    |
+| `bottomBar`          | —                 | The bottom bar on narrow screens, usually `MobileTabBar`. The slot handles sticking to the bottom edge of the screen, hiding at `md` and the notch inset. |
+| `bottomBarHeightVar` | `"--bottombar-h"` | The name of the variable the slot publishes its height to. `null` switches publishing off.                                                                |
+| `routeKey`           | —                 | The route key. When it changes, focus moves to `<main>` and the navigation drawer closes.                                                                 |
+
+## Banners sit above the header and are not sticky
+
+The `banners` slot puts application-level messages in the content column, above
+the header. The side navigation still spans the full height: turning the shell
+from a row into a column for a node that is often empty costs more than a banner
+over the side navigation is worth.
+
+**Banners are not sticky, and that is deliberate.** The header stays at `top: 0`, and
+`--topbar-h` keeps meaning exactly its height; the sticky-offset contract
+(ADR-0016) and
+the header publishing it
+(ADR-0019) are
+untouched. A sticky stack would need a second offset variable, and everything that
+currently computes its offset from `--topbar-h` (`SelectionBar`, the sticky column
+headers of `Table`) would have to add the stack's height. The analysis is in
+ADR-0027.
+
+A message persists because the banner never leaves the markup,
+not because it is always in view: after scrolling a list the user does not see it,
+but sees it again on returning to the top.
+
+The slot has no queue: the consumer decides the order and set of banners.
+
+## Decisions visible in the API
+
+**Scrolling stays with the document, not with `<main>`.** The kit's sticky elements,
+such as `SelectionBar`, measure their offset from the header height, and
+if the content scrolled in its own container, it would sit with a gap of exactly that
+height. The
+ADR-0016 contract
+keeps working without caveats.
+
+**The root is positioned.** On focus the skip link gets `focus:absolute`, and
+absolute positioning is resolved against the nearest positioned ancestor: without `relative` on
+the root, the link of a nested shell would appear not above that shell but somewhere else on the page.
+
+**Mobile mode switches CSS, not `matchMedia`.** The navigation column is hidden
+by a class, and the drawer is shown by a class. `matchMedia` produces the wrong first frame in SSR, and
+the user sees a layout jump after hydration.
+
+**`TopBar` gets the button that opens the navigation automatically** — through the shell's context, not
+through a slot: the shell receives the header already assembled by the consumer and cannot put
+anything into it. Outside `AppShell` the header has no such button.
+
+**If your header is not the kit's, use `useAppShell`.** Without `useAppShell`, navigation below
+`md` is unreachable: the column is hidden, nobody can open the drawer,
+and there is no warning.
+
+```tsx
+import { useAppShell } from "@olddevs/ui";
+
+function OwnHeader() {
+  const { openNavigation } = useAppShell();
+  return <header>{openNavigation ? <button onClick={openNavigation}>Menu</button> : null}</header>;
+}
+```
+
+`openNavigation` appears only when `sidebar` is passed to the shell; the check for
+its presence is part of the contract, not a guard against `undefined`.
+
+**The right area has no name and no resize handle.** The `aside` slot is just a place
+to the right of `<main>`: it cannot be resized. A resize handle comes from a separate
+component, [`SplitPanel`](split-panel.md)
+(ADR-0018).
+
+**The bottom bar slot provides everything that belongs to the shell:** it sticks the bar to the bottom
+edge of the screen, hides it at `md` and wider, reserves its height in the document flow and adds the
+`env(safe-area-inset-bottom)` inset for the screen notch. This is why `MobileTabBar`
+([page](mobile-tab-bar.md)) carries no `fixed`, `md:hidden` or padding of its own, and
+a third-party bar in the slot must not repeat them: the inset would be doubled.
+
+**The slot publishes its height — `--bottombar-h`.** Just as `TopBar` publishes
+`--topbar-h`, but for the bottom edge: the shell measures the slot wrapper (with its
+border and the screen notch inset) and writes the value to the document root.
+Whatever sticks to the bottom edge of the screen computes its offset from this height and sits above
+the bar, not under it: `ContextualSaveBar` and `Toaster` read it themselves (the
+`offsetVar` prop), and for your own sticky elements use
+`bottom: var(--bottombar-h, 0px)`.
+
+At `md` and wider the bar is hidden and the value is
+`0px`; without the slot the variable does not exist, and the components that read it use the `0px` fallback,
+so nothing changes on a wide screen. The name is set by the `bottomBarHeightVar` prop, for the
+same reason `TopBar` has `heightVar`: the kit does not know how many shells the
+document holds; `null` switches publishing off.
+
+## Requirements for the consumer
+
+**Always pass `routeKey`.** Without it there is no focus return on navigation, and this is a
+**silent degradation**: no error and no warning
+appears — focus just stays where it was, and a keyboard user
+continues from the middle of the previous page after navigating.
+
+Focus is left alone on page load, including under `StrictMode`, where effects run twice in dev.
+On navigation it moves to `<main>` without scrolling to it: the router sets the scroll position,
+and a scroll of its own would tuck the top of `<main>` under the sticky header.
+
+**`TooltipProvider` is needed if the navigation collapses** — a requirement of
+`NavItem`, see [SideNav](side-nav.md).
+
+## Related sources and tests
+
+- Implementation: `src/components/app-shell/AppShell.tsx`.
+- Tests: `tests/app-shell.test.tsx` — landmarks, the skip link as the first
+  focusable element, the bottom bar slot with and without the safe area, focus
+  return by key (and its absence on first render, including under `StrictMode`; no scroll on navigation), the navigation button in the
+  header.
+- Story: `src/components/app-shell/AppShell.stories.tsx` — the `AdminEntityList`
+  story without local shell primitives.

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

@@ -0,0 +1,172 @@
+---
+component: AppShell
+exports: [AppShell]
+category: app-shell
+status: stable
+source: src/components/app-shell/AppShell.tsx
+story: src/components/app-shell/AppShell.stories.tsx
+---
+
+# AppShell
+
+## Кратко для AI
+
+Каркас приложения: навигация слева, шапка сверху, содержимое в `<main>`,
+опциональные правая область и нижняя панель. Отвечает за ссылку «к содержимому» (skip-ссылку),
+мобильный режим (навигация уезжает в `Drawer`) и возврат фокуса при смене
+маршрута. О маршрутизаторе не знает: смену экрана обозначает проп `routeKey`.
+
+## Когда использовать
+
+- Страница приложения с постоянной навигацией: админка, кабинет, консоль.
+- Везде, где нужны landmark'и, skip-ссылка и предсказуемый фокус при переходах.
+
+## Когда не использовать
+
+- Для отдельной страницы без навигации — каркас там ничего не даёт.
+- Для раскладки внутри страницы (две колонки, сетка карточек) — это обычный CSS.
+- Для модального сценария — это `Dialog` или `Drawer`.
+
+## Минимальный пример
+
+```tsx
+import { AppShell, NavGroup, NavItem, SideNav, TopBar } from "@olddevs/ui";
+
+<AppShell
+  routeKey={pathname}
+  sidebar={
+    <SideNav>
+      <NavGroup label="Работа">
+        <NavItem label="Дашборд" icon={<DashboardIcon />} active asChild>
+          <Link href="/dashboard" />
+        </NavItem>
+      </NavGroup>
+    </SideNav>
+  }
+  header={<TopBar brand={<Logo />} actions={<UserMenu />} />}
+>
+  <PageContent />
+</AppShell>;
+```
+
+## Пропы
+
+| Проп                 | Умолчание         | Назначение                                                                                                                                      |
+| -------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sidebar`            | —                 | Навигация слева. На узких экранах уезжает в `Drawer`.                                                                                           |
+| `header`             | —                 | Шапка. Обычно `TopBar`.                                                                                                                         |
+| `banners`            | —                 | Сообщения уровня приложения над шапкой. Обычно `Banner`.                                                                                        |
+| `aside`              | —                 | Правая область. Безымянный слот без ручки размера.                                                                                              |
+| `bottomBar`          | —                 | Нижняя панель на узких экранах, обычно `MobileTabBar`. Прилипание к нижнему краю экрана, скрытие на `md` и отступ под вырез берёт на себя слот. |
+| `bottomBarHeightVar` | `"--bottombar-h"` | Имя переменной, в которую слот публикует свою высоту. `null` отключает публикацию.                                                              |
+| `routeKey`           | —                 | Ключ маршрута. Когда он меняется, фокус переходит в `<main>`, а ящик навигации закрывается.                                                     |
+
+## Баннеры стоят над шапкой и не липнут
+
+Слот `banners` кладёт сообщения уровня приложения в колонку содержимого, над
+шапкой. Боковая навигация при этом остаётся во всю высоту: разворачивать каркас
+из строки в колонку ради узла, который бывает пустым, дороже, чем польза от
+баннера поверх боковой навигации.
+
+**Липкости у баннеров нет, и это решение.** Шапка остаётся на `top: 0`, а
+`--topbar-h` продолжает означать ровно её высоту; контракт липкости
+(ADR-0016) и
+его публикация шапкой
+(ADR-0019) не
+трогаются. Липкая стопка потребовала бы второй переменной смещения, и всё, что
+сегодня считает от `--topbar-h` (`SelectionBar`, липкие заголовки колонок
+`Table`), обязано было бы прибавлять высоту стопки. Разбор —
+ADR-0027.
+
+Постоянство сообщения держится на том, что баннер не исчезает из разметки, а не
+на том, что он всегда в кадре: прокрутив список, пользователь его не видит, но
+вернувшись наверх — видит снова.
+
+Очереди у слота нет: порядок и состав баннеров задаёт потребитель.
+
+## Решения, которые видно в API
+
+**Скролл остаётся у документа, а не у `<main>`.** Липкие элементы кита,
+например `SelectionBar`, отсчитывают смещение от высоты шапки, и если бы
+содержимое прокручивалось в собственном контейнере, он встал бы с просветом
+ровно в эту высоту. Контракт
+ADR-0016
+продолжает работать без оговорок.
+
+**Корень позиционирован.** При фокусе skip-ссылка получает `focus:absolute`, а
+абсолютное позиционирование отсчитывается от ближайшего позиционированного
+предка: без `relative` на корне ссылка вложенного каркаса оказалась бы не над
+ним, а в другом месте страницы.
+
+**Мобильный режим переключает CSS, а не `matchMedia`.** Колонка навигации скрыта
+классом, ящик показан классом. `matchMedia` в SSR даёт неверный первый кадр, и
+пользователь видит скачок раскладки после гидратации.
+
+**Кнопку открытия навигации `TopBar` получает сам** — через контекст каркаса, а
+не слотом: шапку каркас получает уже собранной потребителем и вложить в неё
+ничего не может. Вне `AppShell` кнопки у шапки нет.
+
+**Если шапка не из кита, берите `useAppShell`.** Без `useAppShell` навигация
+ниже `md` недостижима: колонка скрыта, ящик открывать некому, предупреждения
+нет.
+
+```tsx
+import { useAppShell } from "@olddevs/ui";
+
+function OwnHeader() {
+  const { openNavigation } = useAppShell();
+  return <header>{openNavigation ? <button onClick={openNavigation}>Меню</button> : null}</header>;
+}
+```
+
+`openNavigation` появляется только когда каркасу передан `sidebar`; проверка на
+наличие — часть контракта, а не защита от `undefined`.
+
+**Правая область — без имени и без ручки размера.** Слот `aside` — просто место
+справа от `<main>`: размер в нём не меняется. Ручку размера даёт отдельный
+компонент [`SplitPanel`](split-panel.md)
+(ADR-0018).
+
+**Слот нижней панели даёт всё, что принадлежит каркасу:** прилипание к нижнему
+краю экрана, скрытие на `md` и шире, высоту в потоке и отступ
+`env(safe-area-inset-bottom)` под вырез экрана. Поэтому `MobileTabBar`
+([страница](mobile-tab-bar.md)) своих `fixed`, `md:hidden` и отступа не несёт, а
+сторонняя панель в слоте не должна их повторять: отступ вышел бы двойным.
+
+**Слот публикует свою высоту — `--bottombar-h`.** Как `TopBar` публикует
+`--topbar-h`, только для нижнего края: каркас измеряет обёртку слота (вместе с
+рамкой и отступом под вырез экрана) и пишет значение в корень документа. Всё,
+что липнет к нижнему краю экрана, отсчитывает отступ от этой высоты и встаёт над
+панелью, а не под ней: `ContextualSaveBar` и `Toaster` читают её сами (проп
+`offsetVar`), а для ваших липких элементов подойдёт
+`bottom: var(--bottombar-h, 0px)`.
+
+На `md` и шире панель скрыта, и значение равно `0px`; без слота переменной нет, а
+компоненты, которые её читают, берут запасное `0px`, поэтому вид на широком
+экране не меняется. Имя задаёт проп `bottomBarHeightVar` — по той же причине, что
+`heightVar` у шапки: кит не знает, сколько в документе каркасов; `null` отключает
+публикацию.
+
+## Требования к потребителю
+
+**Передавайте `routeKey` всегда.** Без него возврата фокуса при переходе не
+будет, и это **молчаливая деградация**: ни ошибки, ни предупреждения не
+появится — фокус просто останется там, где был, и клавиатурный пользователь
+после перехода продолжит с середины прежней страницы.
+
+На загрузке страницы фокус не трогается — в том числе под `StrictMode`, где эффекты
+в dev отрабатывают дважды. При переходе он уходит в `<main>` без прокрутки к нему:
+прокрутку задаёт маршрутизатор, а своя увела бы верх `<main>` под липкую шапку.
+
+**`TooltipProvider` нужен, если навигация схлопывается** — требование
+`NavItem`, см. [SideNav](side-nav.md).
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/app-shell/AppShell.tsx`.
+- Тесты: `tests/app-shell.test.tsx` — landmark'и, skip-ссылка как первый
+  фокусируемый элемент, слот нижней панели с safe-area и без него, возврат
+  фокуса по ключу (и его отсутствие на первой отрисовке, в том числе под `StrictMode`; переход без прокрутки), кнопка навигации в
+  шапке.
+- История: `src/components/app-shell/AppShell.stories.tsx` — история `AdminEntityList`
+  без локальных примитивов каркаса.

package/docs/components/app-shell/mobile-tab-bar.en.md

@@ -0,0 +1,207 @@
+---
+component: MobileTabBar
+exports: [MobileTabBar, MobileTabBarItem]
+category: app-shell
+status: stable
+source: src/components/app-shell/MobileTabBar.tsx
+story: src/components/app-shell/MobileTabBar.stories.tsx
+sourceHash: 2aa4a3681282
+---
+
+# MobileTabBar and MobileTabBarItem
+
+## Summary for AI
+
+`MobileTabBar` is the bottom bar of main sections for a phone: a named `<nav>`
+(the default comes from the message catalog) with `MobileTabBarItem` items in a row, equal in width.
+It goes in the `bottomBar` slot of `AppShell`, and **it does not duplicate anything that belongs to
+the shell**: sticking to the bottom edge of the viewport, hiding at `md` and wider, the inset for the screen
+notch and the height all come from the slot. The slot also publishes the height as `--bottombar-h`
+so that `ContextualSaveBar` and `Toaster`, which stick to the bottom, sit above the bar.
+
+An item is an icon over a label: `active` sets
+`aria-current="page"`, `badge` renders a number or a "something new" dot with text for the
+screen reader, and `asChild` renders the item as the consumer's element, such as the router's link: the item's styles,
+props and `ref` pass to it. The bar knows nothing about the router: the model is the same as for `NavItem`.
+
+## When to use
+
+- The application's main sections on a phone, up to five items, where switching
+  between them must take a single tap.
+- As the companion of the side navigation: `SideNav` at `md` and wider, `MobileTabBar` below.
+
+## When not to use
+
+- For tabs inside a page — that is `Tabs`: they do not navigate to another page.
+- For side navigation and for more than five items — that is `SideNav`; a sixth item
+  on a phone leaves no room for the labels.
+- For an action rather than navigation — that is `Button`. A bar item leads to a page, and
+  the link role is no accident.
+- The kit has no "more" item with a menu and no hiding of the bar on scroll.
+
+## Minimal example
+
+```tsx
+import { AppShell, MobileTabBar, MobileTabBarItem } from "@olddevs/ui";
+import { DashboardIcon, FolderIcon } from "@olddevs/ui/icons";
+import Link from "next/link";
+
+<AppShell
+  routeKey={pathname}
+  bottomBar={
+    <MobileTabBar>
+      <MobileTabBarItem
+        label="Dashboard"
+        icon={<DashboardIcon />}
+        active={pathname.startsWith("/dashboard")}
+        asChild
+      >
+        <Link href="/dashboard" />
+      </MobileTabBarItem>
+      <MobileTabBarItem label="Documents" icon={<FolderIcon />} badge={3} asChild>
+        <Link href="/docs" />
+      </MobileTabBarItem>
+    </MobileTabBar>
+  }
+>
+  <PageContent />
+</AppShell>;
+```
+
+With `asChild`, the child of `MobileTabBarItem` is passed **empty**: the icon and label
+move inside it through `Slottable`. `NavItem` and `Button` work the same way.
+
+## `MobileTabBar` props
+
+| Prop              | Default         | Purpose                                                                                  |
+| ----------------- | --------------- | ---------------------------------------------------------------------------------------- |
+| `aria-label`      | message catalog | The navigation's accessible name instead of "Разделы" / Sections                         |
+| `aria-labelledby` | —               | A name taken from a visible heading — the heading's `id`; not together with `aria-label` |
+
+The name is optional, and the default comes from the message catalog; you can pass one of the two, and the
+type does not allow both at once. An empty `aria-label` does not count as a name, and the default is
+announced instead. The bar has no `label` prop: in the kit, `label` is only a visible label
+([conventions.md](../../conventions.md#доступное-имя)). The other props go
+to the `<nav>`, and so does `ref`.
+
+## `MobileTabBarItem` props
+
+| Prop         | Default         | Purpose                                                                                                                                                                                            |
+| ------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`      | —               | The label and the accessible name, in full. Required.                                                                                                                                              |
+| `icon`       | —               | The icon over the label. Hidden from the screen reader: the label provides the name.                                                                                                               |
+| `active`     | `false`         | The current section: `aria-current="page"`, color and a stripe on top.                                                                                                                             |
+| `badge`      | —               | A number is a counter (above 99 — "99+"), `true` is a "something new" dot, a string is text in a pill, an element is the consumer's badge as is. `0`, `false` and `""` render nothing.             |
+| `badgeLabel` | message catalog | The badge text for the screen reader instead of "3 new" / "Новых: 3" or the string itself. **Required** for the consumer's own element — the type checks it, and in JS a development warning does. |
+| `asChild`    | `false`         | Render the item as the consumer's element: `next/link`, the router's `<Link>`; the item's styles, props and `ref` pass to it.                                                                      |
+
+The other props go to the element — including `href` for the case without `asChild`.
+
+## Decisions visible in the API
+
+**The bar knows nothing about `fixed`, `md:hidden` and the screen notch.** The `bottomBar`
+slot of `AppShell` provides them, and repeating them in the bar would drift from the shell
+silently: the notch inset, for example, would come out doubled. Outside the `bottomBar` slot the bar is
+a plain row in the normal flow: the background is exactly its height, and sticking, hiding and
+the notch inset are left to the consumer.
+
+**The current section is a prop, not a computation.** The kit knows nothing about the router or
+the rules for comparing paths (trailing slash, nested routes, a locale in the prefix);
+a mistake shows up not as a crash but as a quietly unhighlighted item
+(ADR-0018).
+The prop is called `active` — the same as on `NavItem`: one idea in two navigation
+items should not have two names. The `aria-current="page"` attribute is derived from
+it.
+
+**The badge is standard or the consumer's own.** On an item the badge sits over the icon: its position,
+the "99+" cap and the screen reader text are part of the decision, so the standard values
+(a number, `true`, a string) are rendered by the kit itself as a `Badge` pill. The visible number
+is hidden from the screen reader, and a phrase is read instead: a bare "3" next to a section name tells
+nothing, and a dot without text sounds like no badge at all. The phrase comes
+from the message catalog with the real number ("237 new" when the screen shows "99+");
+a string is read as is; `badgeLabel` sets a different phrase.
+
+The consumer's own element, such as `<Badge tone="success">` or an icon badge, is also accepted, like
+`badge` on `NavItem`: it sits in the icon's corner as is. Then `badgeLabel` is
+required, and the type checks it: the badge is hidden from the screen reader along with the
+icon, and the kit cannot read the contents of the consumer's node on the consumer's behalf: it
+may be an image. For a JS consumer who forgot `badgeLabel`, a warning is logged to the console once in
+development mode: the badge is visible but not audible
+([warning rules](../../conventions.md#предупреждения-в-режиме-разработки)).
+
+**The background is a kit surface token, with no blur.** `backdrop-filter` on
+every mobile screen costs a repaint on scroll, and the labels do not need it to stay
+readable. In the `bottomBar` slot the background extends below the bar by the notch
+height: the slot wrapper adds the notch inset, and a background clipped to the
+bar would leave a transparent gap through which the scrolling content shows.
+Outside the slot nobody adds the inset, and the background is exactly the bar — otherwise on a
+phone with a notch it would cover whatever sits under the bar.
+
+The consumer's sticky wrapper with a notch inset paints that inset itself: the wrapper's background is
+`bg-bg-1`, the same token as the background. The slot tells the bar where it is placed
+through the shell's internal context: this is decided by the markup from the first frame, including on
+the server, and does not affect a bar placed in the `<main>` of the same shell.
+
+**The current item differs by more than color**: an accent color on the label and icon
+plus a stripe on top. The weight does not change — otherwise the current item's label
+would become wider than its neighbors and truncate sooner.
+
+## Known trade-off: the 11px label truncates sooner than the consumer's
+
+The label is the kit's `text-caption` scale step (11px), truncated with an ellipsis
+(`truncate`), and the full label remains the accessible name. A consumer
+whose bar predates the kit measured at 360px: with five items an item's column
+leaves 50px for the label, and the two Russian labels "Библиотека" and "Расписание" at 11px take
+64–65px against 58–59px at 10px. So **the kit's step truncates two labels out of
+five** on the most common Android screens, and the consumer keeps its own 10px, outside the scale.
+
+The kit follows its own scale, and there is no separate step for the bar here. Whether one is needed
+will be decided by the first adoption: if the truncation turns out to be noticeable, the right move is
+first to shorten the labels or the number of items, and only then to add a step
+for a single component.
+
+## Accessibility
+
+- A `<nav>` landmark with a name: from the message catalog ("Разделы" / Sections), `aria-label`
+  or `aria-labelledby`.
+  The main side navigation and the bar are two different landmarks with different names.
+- An item is a link; the current one is announced as "current page".
+- The icon is hidden from the screen reader, and the name is the full label, even if it
+  is truncated on screen.
+- The badge is read as a phrase, not a bare number — see above.
+- Keyboard — ordinary Tab through the links, a focus ring on the item.
+
+## Requirements for the consumer
+
+**The bar goes in `bottomBar` of `AppShell`.** Sticking, hiding at `md` and the
+screen notch come from there; without the shell you have to set them yourself. The bar's
+height comes from there too: the slot publishes it as `--bottombar-h`, and `ContextualSaveBar`
+and `Toaster` sit above the bar without a hand-tuned `bottom-14` workaround. Outside the shell the
+consumer publishes the variable.
+
+**Without `asChild`, an item needs `href`.** The type does not require it — `NavItem` works the same way —
+but an `<a>` without `href` is not a link: no role, no place in the tab order,
+although `aria-current` and the badge name are still announced. An item without `href` looks functional
+but is inaccessible.
+
+**With `asChild`, the item needs a link element inside.** If there is none (forgotten in
+JS code), the item does not crash the page but renders its own `<a>` without `href`: the label
+is visible, but the item is inaccessible for the same reason as above.
+
+**Without an icon, the badge goes into the label line**, after it: the corner of an empty node
+has nothing to anchor to. The label then truncates sooner than the badge.
+
+**No more than five items.** The row is divided equally; a sixth leaves labels
+under 50px at 360px, and almost every label truncates.
+
+## Related sources and tests
+
+- Implementation: `src/components/app-shell/MobileTabBar.tsx`.
+- Tests: `tests/mobile-tab-bar.test.tsx` — the landmark and its name (message catalog,
+  `aria-label`, `aria-labelledby`, empty string), `ref`, `active`, `asChild`,
+  the name with a long label, badge text (number, cap, dot, `badgeLabel`,
+  zero), the warning for the consumer's own badge without `badgeLabel`, the background in the `bottomBar`
+  slot and outside it; the Russian strings are in
+  `tests/locale-ru.test.tsx`.
+- Stories: `src/components/app-shell/MobileTabBar.stories.tsx` and `WithBottomBar` in
+  `src/components/app-shell/AppShell.stories.tsx`.