@olddevs/ui 0.0.0-stage → 4.0.1

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

@@ -0,0 +1,210 @@
+---
+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
+---
+
+# MobileTabBar и MobileTabBarItem
+
+## Кратко для AI
+
+`MobileTabBar` — нижняя панель главных разделов для телефона: `<nav>` с именем
+(умолчание из каталога сообщений) и пунктами `MobileTabBarItem` в ряд, поровну.
+Ставится в слот `bottomBar` у `AppShell`, и **всё, что принадлежит каркасу, она
+не дублирует**: прилипание к нижнему краю экрана, скрытие на `md` и шире, отступ
+под вырез экрана и высоту даёт слот. Он же публикует высоту в `--bottombar-h`,
+чтобы липнущие к низу `ContextualSaveBar` и `Toaster` вставали над панелью.
+
+Пункт — иконка над подписью: `active` ставит `aria-current="page"`, `badge`
+рисует число или точку «есть новое» с текстом для скринридера, `asChild`
+отрисовывает пункт элементом потребителя, например ссылкой маршрутизатора: стили,
+пропы и `ref` пункта переходят на него. Маршрутизатора панель не знает: модель
+та же, что у `NavItem`.
+
+## Когда использовать
+
+- Главные разделы приложения на телефоне, до пяти пунктов, переход между
+  которыми должен быть в один тап.
+- Как пара боковой навигации: `SideNav` на `md` и шире, `MobileTabBar` ниже.
+
+## Когда не использовать
+
+- Для вкладок внутри страницы — это `Tabs`: у них нет перехода на другую страницу.
+- Для боковой навигации и для пунктов больше пяти — это `SideNav`; шестой пункт
+  на телефоне уже не оставляет подписи места.
+- Для действия, а не перехода — это `Button`. Пункт панели ведёт на страницу, и
+  роль ссылки не случайна.
+- Пункта «ещё» с меню и скрытия панели при прокрутке в ките нет.
+
+## Минимальный пример
+
+```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="Дашборд"
+        icon={<DashboardIcon />}
+        active={pathname.startsWith("/dashboard")}
+        asChild
+      >
+        <Link href="/dashboard" />
+      </MobileTabBarItem>
+      <MobileTabBarItem label="Документы" icon={<FolderIcon />} badge={3} asChild>
+        <Link href="/docs" />
+      </MobileTabBarItem>
+    </MobileTabBar>
+  }
+>
+  <PageContent />
+</AppShell>;
+```
+
+Потомок `MobileTabBarItem` при `asChild` передаётся **пустым**: иконка и подпись
+уезжают внутрь него через `Slottable`. Так же устроены `NavItem` и `Button`.
+
+## Пропы `MobileTabBar`
+
+| Проп              | Умолчание | Назначение                                                           |
+| ----------------- | --------- | -------------------------------------------------------------------- |
+| `aria-label`      | каталог   | Доступное имя навигации вместо «Разделы» / Sections                  |
+| `aria-labelledby` | —         | Имя от видимого заголовка — `id` заголовка; не вместе с `aria-label` |
+
+Имя необязательно: умолчание берётся из каталога; передать можно одно из двух,
+оба сразу тип не пропускает. Пустой `aria-label` именем не считается, и тогда
+звучит умолчание. Пропа `label` у панели нет: в ките `label` — только видимая подпись
+([conventions.md](../../conventions.md#доступное-имя)). Остальные пропы уходят
+на `<nav>`, `ref` — на него же.
+
+## Пропы `MobileTabBarItem`
+
+| Проп         | Умолчание | Назначение                                                                                                                                                              |
+| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`      | —         | Подпись и доступное имя, целиком. Обязательна.                                                                                                                          |
+| `icon`       | —         | Иконка над подписью. Скрыта от скринридера: имя даёт подпись.                                                                                                           |
+| `active`     | `false`   | Текущий раздел: `aria-current="page"`, цвет и полоска сверху.                                                                                                           |
+| `badge`      | —         | Число — счётчик (больше 99 — «99+»), `true` — точка «есть новое», строка — надпись в «таблетке», элемент — значок потребителя как есть. `0`, `false` и `""` — ничего.   |
+| `badgeLabel` | каталог   | Текст значка для скринридера вместо «3 new» / «Новых: 3» или самой строки. У своего элемента **обязателен** — это проверяет тип, а на JS — предупреждение в разработке. |
+| `asChild`    | `false`   | Отрисовать пункт элементом потребителя: `next/link`, `<Link>` роутера; стили, пропы и `ref` пункта переходят на него.                                                   |
+
+Остальные пропы уходят на элемент — включая `href` для случая без `asChild`.
+
+## Решения, которые видно в API
+
+**Панель не знает про `fixed`, `md:hidden` и вырез экрана.** Их даёт слот
+`bottomBar` у `AppShell`, и повтор в панели разошёлся бы с каркасом молча:
+отступ под вырез, например, вышел бы двойным. Вне слота `bottomBar` панель —
+обычная строка в потоке: подложка ровно по её высоте, а прилипание, скрытие и
+отступ под вырез остаются на потребителе.
+
+**Текущий раздел — проп, а не вычисление.** Кит не знает маршрутизатора и
+правил сравнения путей (хвостовой слэш, вложенные маршруты, локаль в префиксе);
+ошибка выражается не падением, а тихо неподсвеченным пунктом
+(ADR-0018).
+Проп называется `active` — так же, как у `NavItem`: одна идея в двух пунктах
+навигации не должна иметь двух имён. Атрибут `aria-current="page"` выводится
+из него.
+
+**Значок — штатный или потребителя.** У пункта значок лежит поверх иконки:
+положение, предел «99+» и текст для скринридера — часть решения, поэтому штатные
+значения (число, `true`, строка) кит рисует сам в «таблетке» `Badge`. Видимое
+число скрыто от скринридера, а слышна фраза: голое «3» рядом с названием раздела
+ни о чём не говорит, а точка без текста звучит как отсутствие значка. Фраза
+берётся из каталога сообщений с настоящим числом («237 new» при «99+» на
+экране); строка звучит сама собой; `badgeLabel` задаёт другую фразу.
+
+Принимается и элемент потребителя, например `<Badge tone="success">` или
+иконка в роли значка, как у `badge` в `NavItem`: он встаёт в угол иконки как есть. Тогда
+`badgeLabel` обязателен, и это проверяет тип: значок спрятан от скринридера
+вместе с иконкой, а прочитать за потребителя содержимое переданного им узла кит
+не может: там может быть картинка. Потребителю на JS, забывшему `badgeLabel`, в
+режиме разработки один раз выводится предупреждение в консоль: значок виден, но
+не слышен
+([правила предупреждений](../../conventions.md#предупреждения-в-режиме-разработки)).
+
+**Подложка — токен поверхности кита, без размытия.** `backdrop-filter` на
+каждом мобильном экране стоит перерисовки при прокрутке, а читаемость подписей
+ему не нужна. В слоте `bottomBar` подложка спускается ниже панели на высоту
+выреза: отступ под него добавляет обёртка слота, и подложка, обрезанная по
+панели, оставляла бы прозрачную щель, сквозь которую виден уезжающий контент.
+Вне слота отступа никто не добавляет, и подложка ровно по панели — иначе на
+телефоне с вырезом она перекрыла бы то, что стоит под панелью.
+
+Прилипающая обёртка потребителя с отступом под вырез красит этот отступ сама:
+фон обёртки — `bg-bg-1`, тот же токен, что у подложки. Где стоит панель, ей
+сообщает слот через внутренний контекст каркаса: это решается разметкой с
+первого кадра, в том числе на сервере, и не задевает панель, положенную в
+`<main>` того же каркаса.
+
+**Текущий пункт отличается не одним цветом**: акцентный цвет подписи и иконки
+плюс полоска сверху. Жирность не меняется — иначе подпись текущего пункта
+становилась бы шире соседей и обрезалась раньше.
+
+## Известный компромисс: подпись 11px обрезается раньше, чем у потребителя
+
+Подпись — ступень шкалы кита `text-caption` (11px), обрезается многоточием
+(`truncate`), а полная подпись остаётся доступным именем. Потребитель, у
+которого эта панель жила до кита, замерил на 360px: колонка пункта при пяти
+пунктах даёт 50px под подпись, а две русские подписи «Библиотека» и
+«Расписание» на 11px занимают 64–65px против 58–59px на 10px. То есть **ступень кита обрезает две подписи из
+пяти** на самых распространённых Android-экранах, и потребитель держит у себя
+10px мимо шкалы.
+
+Кит идёт по своей шкале, и отдельной ступени для панели здесь нет. Нужна ли она,
+решит первое внедрение: если обрезание окажется заметным, правильный ход —
+сначала сократить подписи или число пунктов, и только потом заводить ступень
+под один компонент.
+
+## Доступность
+
+- Landmark `<nav>` с именем: из каталога («Разделы» / Sections), `aria-label`
+  или `aria-labelledby`.
+  Главная боковая навигация и панель — два разных landmark'а с разными именами.
+- Пункт — ссылка; текущий объявляется как «текущая страница».
+- Иконка скрыта от скринридера, имя — подпись целиком, даже если на экране она
+  обрезана.
+- Значок читается фразой, а не голым числом — см. выше.
+- Клавиатура — обычная табуляция по ссылкам, кольцо фокуса на пункте.
+
+## Требования к потребителю
+
+**Панель стоит в `bottomBar` у `AppShell`.** Прилипание, скрытие на `md` и
+вырез экрана — оттуда; без каркаса их нужно задать самому. Оттуда же высота
+панели: слот публикует её в `--bottombar-h`, и `ContextualSaveBar` и `Toaster`
+встают над панелью без подпорки `bottom-14` «на глаз». Вне каркаса переменную
+публикует потребитель сам.
+
+**Без `asChild` пункту нужен `href`.** Тип его не требует — так же устроен
+`NavItem`, — а `<a>` без `href` не ссылка: ни роли, ни места в порядке табуляции,
+хотя `aria-current` и имя значка объявляются. Пункт без `href` выглядит рабочим
+и недоступен.
+
+**С `asChild` внутри нужен элемент-ссылка.** Если его нет (забыли в коде на
+JS), пункт не ломает страницу, а отрисовывается собственным `<a>` без `href`:
+подпись видна, но пункт недоступен по той же причине, что выше.
+
+**Без иконки значок встаёт в строку подписи**, после неё: углу пустого узла не
+за что зацепиться. Подпись тогда обрезается раньше значка.
+
+**Пунктов — не больше пяти.** Ряд делится поровну; шестой оставит подписи
+меньше 50px на 360px, и обрезаться будет почти каждая.
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/app-shell/MobileTabBar.tsx`.
+- Тесты: `tests/mobile-tab-bar.test.tsx` — landmark и его имя (каталог,
+  `aria-label`, `aria-labelledby`, пустая строка), `ref`, `active`, `asChild`,
+  имя при длинной подписи, текст значка (число, предел, точка, `badgeLabel`,
+  ноль), предупреждение о значке потребителя без `badgeLabel`, подложка в слоте
+  `bottomBar` и вне его; русские строки — в
+  `tests/locale-ru.test.tsx`.
+- История: `src/components/app-shell/MobileTabBar.stories.tsx` и `WithBottomBar` в
+  `src/components/app-shell/AppShell.stories.tsx`.

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

@@ -0,0 +1,153 @@
+---
+component: SideNav
+exports: [SideNav, NavGroup, NavItem]
+category: app-shell
+status: stable
+source: src/components/app-shell/SideNav.tsx, src/components/app-shell/NavItem.tsx
+story: src/components/app-shell/SideNav.stories.tsx, src/components/app-shell/NavItem.stories.tsx
+sourceHash: 7af78e06b543
+---
+
+# SideNav, NavGroup and NavItem
+
+## Summary for AI
+
+`SideNav` is the application's side navigation: a named landmark, header and
+footer slots, and `NavGroup` sections with `NavItem` items. It holds the collapsed state itself
+(`defaultCollapsed`) or hands it to the consumer (`collapsed` + `onCollapsedChange`);
+**persisting** it is the consumer's job. `NavItem` knows nothing about the router:
+the link target comes from the child element passed with `asChild` (or from `href`), and the current item is set by the
+`active` prop. In collapsed mode the labels are visually hidden but remain accessible
+names, and section headings are replaced by a divider line.
+
+There is no mobile mode here: below `md`, `AppShell` moves the navigation into a `Drawer`.
+`SideNav` itself is just a column, and it can be placed inside a drawer.
+
+## When to use
+
+- The application's main navigation on the left — an admin panel, an account area, a console.
+- A single side-menu item (`NavItem`) — in the consumer's own navigation.
+- Any list of links where one item is "current" and the items have icons.
+
+## When not to use
+
+- For tabs inside a page — that is `Tabs`.
+- For the path to the current page — that is `Breadcrumbs`.
+- For an action rather than navigation — that is `Button`. A navigation item leads somewhere, and
+  the link role is no accident: users open it in a new tab, copy the link and see its `href`
+  in the status bar.
+
+## Minimal example
+
+```tsx
+import { NavGroup, NavItem, SideNav } from "@olddevs/ui";
+import { DashboardIcon, FolderIcon } from "@olddevs/ui/icons";
+import Link from "next/link";
+
+<SideNav header={<Logo />} footer={<CurrentUser />}>
+  <NavGroup label="Work">
+    <NavItem
+      label="Dashboard"
+      icon={<DashboardIcon />}
+      active={pathname.startsWith("/dashboard")}
+      asChild
+    >
+      <Link href="/dashboard" />
+    </NavItem>
+    <NavItem label="Documents" icon={<FolderIcon />} asChild>
+      <Link href="/docs" />
+    </NavItem>
+  </NavGroup>
+</SideNav>;
+```
+
+The child of `NavItem` is passed **empty**: the icon and label move inside it
+through `Slottable`. `Button` works the same way.
+
+## `SideNav` props
+
+| Prop                | Default         | Purpose                                                                                  |
+| ------------------- | --------------- | ---------------------------------------------------------------------------------------- |
+| `header`            | —               | The header slot: a logo, the product name.                                               |
+| `footer`            | —               | The footer slot: the current user block (name, avatar), links.                           |
+| `collapsed`         | —               | The collapsed state in controlled mode. If set, the component keeps no state of its own. |
+| `defaultCollapsed`  | `false`         | The initial collapsed state in uncontrolled mode.                                        |
+| `onCollapsedChange` | —               | Reports an intent to toggle.                                                             |
+| `collapsible`       | `true`          | The built-in collapse button in the footer.                                              |
+| `label`             | message catalog | The navigation's accessible name.                                                        |
+
+## `NavGroup` props
+
+| Prop    | Default | Purpose                                                                                         |
+| ------- | ------- | ----------------------------------------------------------------------------------------------- |
+| `label` | —       | The section heading and the group's accessible name. A string, not a `ReactNode`: it is a name. |
+
+## `NavItem` props
+
+| Prop       | Default | Purpose                                                                                                                       |
+| ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `label`    | —       | The label and the accessible name. Required.                                                                                  |
+| `icon`     | —       | An icon on the left. Hidden from the screen reader: the label provides the name.                                              |
+| `active`   | `false` | The current item: `aria-current="page"`, a border and a background.                                                           |
+| `badge`    | —       | A counter on the right: `Badge`, a number, a dot. Not rendered in collapsed mode.                                             |
+| `shortcut` | —       | A keyboard shortcut slot, usually `Kbd`. Not rendered in collapsed mode.                                                      |
+| `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
+
+**Active state is a prop, not a computation.** The kit knows neither the router nor
+the rules for comparing paths: trailing slash, query, nested routes, a locale in the
+prefix — each router has its own. A mistake here shows up not as a crash but as a quietly
+unhighlighted item, so that logic stays with the application —
+ADR-0018.
+
+**The label is a separate prop, not content.** In collapsed mode it has to be
+wrapped, to hide it visually and keep it for the screen reader. With
+`asChild` the content belongs to the child, and it cannot be wrapped.
+
+**The collapsed state arrives through context from `SideNav`**, not as a prop on each
+item: otherwise the consumer would pass one value to ten places by hand and
+one day forget it in one of them.
+
+**A prop's presence makes the mode controlled, not its value.** `collapsed={false}`
+means "I control it, it is expanded now", not "there is no control". Confusing these two
+cases leaves you with an external button that silently stops working.
+
+**Widths are the `--sidenav-w` and `--sidenav-w-collapsed` tokens, not props.** The `AppShell`
+grid needs the same value, and routing it through React would mean
+re-rendering for something CSS reads on its own. To change them, see
+[theming.md](../../theming.md).
+
+**In the mobile-mode drawer the navigation is always expanded.** When `AppShell` shows
+`SideNav` in a `Drawer`, it hides the collapse button and keeps the collapsed state from
+taking effect — neither `collapsed` nor `defaultCollapsed`. Collapsed mode exists
+for one purpose: to free up width for the page content, and an overlay has no page content next to it.
+Removing only the button would be worse: a consumer who keeps the collapsed state
+outside the component would get icons in the drawer with no way to expand them.
+
+`onCollapsedChange` is not called in the drawer — the consumer's state belongs
+to the column, and the overlay must not change it.
+
+**The kit cannot persist the collapsed state and never will.** `localStorage`, a cookie,
+the application's storage — that is up to the consumer; the component only reports
+the toggle.
+
+## Requirements for the consumer
+
+**Collapsed navigation must sit inside a `TooltipProvider`** — otherwise Radix
+throws on the very first item. The component does not create the provider itself, for
+the same reason as `Segmented`: the provider sets the tooltip grouping for the whole
+application, and a nested one breaks it. In expanded mode there is no tooltip,
+and so no requirement.
+
+## Related sources and tests
+
+- Implementation: `src/components/app-shell/SideNav.tsx`, `src/components/app-shell/NavItem.tsx`.
+- Tests: `tests/nav-item.test.tsx` — active state, `asChild`, the accessible name in
+  collapsed mode; `tests/side-nav.test.tsx` — the landmark and its name from the message catalog,
+  both modes of collapsed-state ownership, the group name with a hidden heading;
+  `tests/app-shell.test.tsx` — behavior in the drawer.
+- Stories: `src/components/app-shell/SideNav.stories.tsx`,
+  `src/components/app-shell/NavItem.stories.tsx`.

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

@@ -0,0 +1,152 @@
+---
+component: SideNav
+exports: [SideNav, NavGroup, NavItem]
+category: app-shell
+status: stable
+source: src/components/app-shell/SideNav.tsx, src/components/app-shell/NavItem.tsx
+story: src/components/app-shell/SideNav.stories.tsx, src/components/app-shell/NavItem.stories.tsx
+---
+
+# SideNav, NavGroup и NavItem
+
+## Кратко для AI
+
+`SideNav` — боковая навигация приложения: landmark с именем, слоты шапки и
+подвала, разделы `NavGroup` с пунктами `NavItem`. Схлопнутость держит сама
+(`defaultCollapsed`) или отдаёт потребителю (`collapsed` + `onCollapsedChange`);
+**сохранять** её — дело потребителя. `NavItem` о маршрутизаторе не знает ничего:
+ссылку задаёт дочерний элемент при `asChild` (или проп `href`), текущий пункт — пропом
+`active`. В схлопнутом режиме подписи прячутся от глаз, но остаются доступными
+именами, а заголовки разделов заменяются чертой.
+
+Мобильного режима здесь нет: ниже `md` навигацию убирает в `Drawer` сам `AppShell`.
+Сама `SideNav` — просто колонка, и её можно положить внутрь ящика.
+
+## Когда использовать
+
+- Основная навигация приложения слева — админка, кабинет, консоль.
+- Отдельный пункт бокового меню (`NavItem`) — в навигации потребителя.
+- Любой список ссылок, где один из пунктов «текущий», а у пунктов есть иконки.
+
+## Когда не использовать
+
+- Для вкладок внутри страницы — это `Tabs`.
+- Для пути к текущей странице — это `Breadcrumbs`.
+- Для действия, а не перехода — это `Button`. Пункт навигации ведёт куда-то, и
+  роль ссылки не случайна: его открывают в новой вкладке, копируют ссылку, видят
+  `href` в строке состояния.
+
+## Минимальный пример
+
+```tsx
+import { NavGroup, NavItem, SideNav } from "@olddevs/ui";
+import { DashboardIcon, FolderIcon } from "@olddevs/ui/icons";
+import Link from "next/link";
+
+<SideNav header={<Logo />} footer={<CurrentUser />}>
+  <NavGroup label="Работа">
+    <NavItem
+      label="Дашборд"
+      icon={<DashboardIcon />}
+      active={pathname.startsWith("/dashboard")}
+      asChild
+    >
+      <Link href="/dashboard" />
+    </NavItem>
+    <NavItem label="Документы" icon={<FolderIcon />} asChild>
+      <Link href="/docs" />
+    </NavItem>
+  </NavGroup>
+</SideNav>;
+```
+
+Потомок `NavItem` передаётся **пустым**: иконка и подпись уезжают внутрь него
+через `Slottable`. Так же устроен `Button`.
+
+## Пропы `SideNav`
+
+| Проп                | Умолчание | Назначение                                                                        |
+| ------------------- | --------- | --------------------------------------------------------------------------------- |
+| `header`            | —         | Слот шапки: логотип, название продукта.                                           |
+| `footer`            | —         | Слот подвала: блок текущего пользователя (имя, аватар), ссылки.                   |
+| `collapsed`         | —         | Схлопнутость в управляемом режиме. Задана — компонент своего состояния не держит. |
+| `defaultCollapsed`  | `false`   | Начальная схлопнутость в неуправляемом режиме.                                    |
+| `onCollapsedChange` | —         | Сообщает о намерении переключиться.                                               |
+| `collapsible`       | `true`    | Встроенная кнопка сворачивания в подвале.                                         |
+| `label`             | каталог   | Доступное имя навигации.                                                          |
+
+## Пропы `NavGroup`
+
+| Проп    | Умолчание | Назначение                                                                   |
+| ------- | --------- | ---------------------------------------------------------------------------- |
+| `label` | —         | Заголовок раздела и доступное имя группы. Строка, а не `ReactNode`: это имя. |
+
+## Пропы `NavItem`
+
+| Проп       | Умолчание | Назначение                                                                                                            |
+| ---------- | --------- | --------------------------------------------------------------------------------------------------------------------- |
+| `label`    | —         | Подпись и доступное имя. Обязательна.                                                                                 |
+| `icon`     | —         | Иконка слева. Скрыта от скринридера: имя даёт подпись.                                                                |
+| `active`   | `false`   | Текущий пункт: `aria-current="page"`, рамка и фон.                                                                    |
+| `badge`    | —         | Счётчик справа: `Badge`, число, точка. В схлопнутом режиме не рендерится.                                             |
+| `shortcut` | —         | Слот горячей клавиши, обычно `Kbd`. В схлопнутом режиме не рендерится.                                                |
+| `asChild`  | `false`   | Отрисовать пункт элементом потребителя: `next/link`, `<Link>` роутера; стили, пропы и `ref` пункта переходят на него. |
+
+Остальные пропы уходят на элемент — включая `href` для случая без `asChild`.
+
+## Решения, которые видно в API
+
+**Активность — проп, а не вычисление.** Кит не знает ни маршрутизатора, ни
+правил сравнения путей: хвостовой слэш, query, вложенные маршруты, локаль в
+префиксе — у каждого маршрутизатора они свои. Ошибка здесь выражается не падением, а тихо
+неподсвеченным пунктом, поэтому логика сравнения остаётся у приложения —
+ADR-0018.
+
+**Подпись отдельным пропом, а не содержимым.** В схлопнутом режиме её нужно
+обернуть, чтобы спрятать от глаз и оставить скринридеру. Содержимое при
+`asChild` принадлежит потомку, и обернуть его нельзя.
+
+**Схлопнутость приходит контекстом от `SideNav`**, а не пропом на каждом
+пункте: иначе потребитель протаскивал бы одно значение в десять мест руками и
+однажды забыл бы в одном.
+
+**Управляемым режим делает наличие пропа, а не его значение.** `collapsed={false}`
+— это «я управляю, сейчас развёрнуто», а не «управления нет». Спутать эти два
+случая — значит получить внешнюю кнопку, которая молча перестала работать.
+
+**Ширины — токены `--sidenav-w` и `--sidenav-w-collapsed`, а не пропы.** То же
+значение нужно сетке `AppShell`, и гонять его через React — значило бы
+ререндерить ради того, что CSS читает сам. Как их менять — в
+[theming.md](../../theming.md).
+
+**В ящике мобильного режима навигация всегда развёрнута.** `AppShell`, показывая
+`SideNav` в `Drawer`, прячет кнопку сворачивания и не даёт схлопнутости
+действовать — ни `collapsed`, ни `defaultCollapsed`. Схлопнутый режим существует
+ради одного: отдать ширину содержимому страницы, а рядом с оверлеем содержимого
+нет. Убрать при этом только кнопку было бы хуже: потребитель, который сам
+хранит схлопнутость, получил бы в ящике иконки без способа их развернуть.
+
+`onCollapsedChange` в ящике не зовётся — состояние потребителя относится к
+колонке, и оверлей не вправе его менять.
+
+**Сохранять схлопнутость кит не умеет и не будет.** `localStorage`, cookie,
+хранилище приложения — дело потребителя; компонент только сообщает о
+переключении.
+
+## Требования к потребителю
+
+**Схлопнутая навигация обязана стоять внутри `TooltipProvider`** — иначе Radix
+бросает на первом же пункте. Компонент не создаёт провайдер сам, по
+той же причине, что и `Segmented`: провайдер задаёт группировку подсказок на всё
+приложение, а вложенный её ломает. В развёрнутом режиме подсказки нет, и
+требования тоже нет.
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/app-shell/SideNav.tsx`, `src/components/app-shell/NavItem.tsx`.
+- Тесты: `tests/nav-item.test.tsx` — активность, `asChild`, доступное имя в
+  схлопнутом режиме; `tests/side-nav.test.tsx` — landmark и его имя из каталога,
+  оба режима владения схлопнутостью, имя группы при спрятанном заголовке;
+  `tests/app-shell.test.tsx` — поведение в ящике.
+- Истории: `src/components/app-shell/SideNav.stories.tsx`,
+  `src/components/app-shell/NavItem.stories.tsx`.