@olddevs/ui 4.1.0 → 4.2.0

package/docs/components/navigation/mega-menu.md

@@ -0,0 +1,258 @@
+---
+component: MegaMenu
+exports: [MegaMenu, MegaMenuCategory, MegaMenuGroup, MegaMenuLink, MegaMenuTrigger, MegaMenuButton]
+category: navigation
+status: stable
+source: src/components/navigation/MegaMenu.tsx
+story: src/components/navigation/MegaMenu.stories.tsx
+---
+
+# MegaMenu
+
+## Кратко для AI
+
+`MegaMenu` — каталог магазина в духе Amazon: слева Столбец категорий, справа от наведённой Категории — её
+Витрина с колонками ссылок и любым своим содержимым. Это навигация по ссылкам, а не меню команд: разметка по
+шаблону WAI-ARIA Disclosure Navigation (`nav`, кнопки с `aria-expanded`, настоящие `a`). Категории —
+`MegaMenuCategory` прямыми детьми, колонки — `MegaMenuGroup`, ссылки — `MegaMenuLink`. Тот же каталог
+открывается выпадающим оверлеем от кнопки: `MegaMenuTrigger` с `MegaMenuButton` и неизменным `MegaMenu`.
+
+## Когда использовать
+
+- Каталог с десятком и больше разделов, у каждого — подразделы колонками: магазин, маркетплейс, справочный
+  портал.
+- Разделы надо показать сразу, а подразделы — по наведению, не уводя пользователя со страницы.
+- В Витрине рядом со ссылками нужно своё содержимое: промо-карточка, картинка, подборка.
+
+## Когда не использовать
+
+- Для команд над объектом («Переименовать», «Удалить») — `Menu`: там действия, а не переходы.
+- Для навигации приложения с текущим разделом — `SideNav`.
+- Для глубокой иерархии, которую раскрывают на месте, — `TreeView`.
+- Для двух-трёх ссылок без подразделов — обычный список ссылок или `Tabs`.
+
+## Минимальный пример
+
+```tsx
+import { MegaMenu, MegaMenuCategory, MegaMenuGroup, MegaMenuLink } from "@olddevs/ui";
+
+<MegaMenu aria-label="Каталог">
+  <MegaMenuCategory id="computers" label="Компьютеры" href="/computers">
+    <MegaMenuGroup title="Ноутбуки" href="/computers/laptops">
+      <MegaMenuLink href="/computers/laptops/gaming">Игровые</MegaMenuLink>
+      <MegaMenuLink href="/computers/laptops/ultrabooks" current>
+        Ультрабуки
+      </MegaMenuLink>
+    </MegaMenuGroup>
+  </MegaMenuCategory>
+  <MegaMenuCategory id="deals" label="Скидки дня" href="/deals" />
+</MegaMenu>;
+```
+
+## Пропы
+
+`MegaMenu`:
+
+| Проп                                       | По умолчанию | Смысл                                                                                      |
+| ------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------ |
+| `aria-label`                               | —            | Доступное имя навигации, обязательно: на странице с несколькими `nav` их различают по нему |
+| `value` / `defaultValue` / `onValueChange` | `null`       | Открытая Категория (её `id`) или `null`, управляемо или нет                                |
+| `showcaseWidth`                            | `"40rem"`    | Ширина Витрины, одна на все Категории: каталог не прыгает при переходе между ними          |
+| `className`                                | —            | Классы на `nav`; ширина Столбца по умолчанию — `w-64`                                      |
+
+`MegaMenuCategory`: `id` — ключ для `value`; `label` — подпись в Столбце и имя Витрины; `icon`; `href` или
+`link` — адрес раздела целиком; `disabled`; дети — содержимое Витрины. У Категории с Витриной адрес становится
+заголовком-ссылкой в начале Витрины, у Категории без детей сама строка Столбца — ссылка. `link` — ссылка роутера
+пустым элементом (`link={<Link href="/x" />}`), подпись уезжает внутрь; это отдельный проп, а не `asChild`,
+потому что дети Категории — её Витрина.
+
+`MegaMenuGroup`: `title` — заголовок колонки, он же подпись списка; `href` делает заголовок ссылкой; дети —
+`MegaMenuLink`, каждая уезжает в свой пункт списка.
+
+`MegaMenuLink`: обычные пропы `a`, `icon`, `current` и `asChild`. `current` ставит `aria-current="page"` и вид
+текущей: текущую страницу кит не вычисляет, правила сравнения адресов у каждого роутера свои. `asChild` выводит
+ссылку элементом роутера: `<MegaMenuLink asChild><Link href="/x">Подпись</Link></MegaMenuLink>`.
+
+## Наведение и Витрина
+
+Наведение мышью на Категорию открывает её Витрину сразу, без задержки. Подсвечена ровно та Категория, чья
+Витрина открыта: подсветка идёт по `aria-expanded`, а не по `:hover`. Наведение на Категорию без Витрины
+закрывает открытую — с той же оговоркой про Прицел, что ниже.
+
+Витрина закрывается, когда курсор ушёл и со Столбца, и с Витрины, через 150 мс: короткий выход за край не
+сбрасывает каталог. Закрывают её и нажатие указателем вне каталога, и уход фокуса со страницы каталога.
+
+Содержимое Витрины монтируется только у открытой Категории: каталог из сотни ссылок и картинок не грузит всё
+разом. Сам регион есть всегда, скрытым: на него указывает `aria-controls` кнопки.
+
+Витрина — потомок своей Категории в DOM, а не портал. Поэтому порядок Tab идёт «Категория → её ссылки → дальше
+по странице», и Витрина встаёт вплотную к Столбцу без расчёта позиции. Предок с `overflow: hidden` её обрежет:
+ставьте каталог туда, где рядом есть место.
+
+Витрина стоит со стороны конца строки — справа, а при письме справа налево слева. Если там не хватает места, а с
+другой стороны хватает, она переходит на другую сторону; сторону кит меряет заранее и при смене размера окна,
+поэтому стрелка «к Витрине» сразу смотрит туда, где Витрина окажется.
+
+## Касание и узкий экран
+
+Касание наведения не знает, поэтому Категорию открывает само касание (`click`), без Прицела. Указатель с
+`pointerType` «touch» или «pen» не открывает Категорию наведением и не закрывает Витрину уходом: перо
+ведёт себя как палец. Повторное касание открытой Категории её не закрывает и никуда не ведёт: закрывает
+Витрину касание вне каталога или Escape.
+
+Мышь ведёт себя, как раньше: наведение, Прицел и закрытие через 150 мс остаются, пока экран широкий.
+
+На узком экране — меньше 640px, граница та же, что у подменю `Menu` и подменю Редактора, — Витрине некуда
+встать сбоку: справа от Столбца её обрезал бы край окна. Поэтому каталог идёт «спуском»:
+
+- Столбец занимает всю ширину, подписи Категорий переносятся, а не обрезаются.
+- Открытая Категория (касанием, щелчком, Enter или Пробелом) заменяет Столбец своей Витриной. Витрина
+  начинается строкой «Назад» с названием Категории; если у Категории есть своя ссылка, название показывает она,
+  строкой ниже, а не строка «Назад». Ниже — колонки ссылок, одна под другой.
+- «Назад» возвращает Столбец и ставит фокус на Категорию, из которой человек пришёл. Escape внутри
+  Витрины работает как «Назад».
+- Фокус при спуске переходит на «Назад»: кнопка Категории скрыта вместе со Столбцом, и фокус на ней
+  пропал бы. Стрелка в сторону Столбца в Витрине на узком экране ничего не делает: Столбца рядом нет.
+- Прицела на узком экране нет, наведение мышью Категорию не открывает, а уход мыши не отменяет спуск:
+  заменять Столбец под курсором значило бы вырывать его из-под руки.
+- Разметка остаётся по шаблону disclosure: кнопка Категории сохраняет `aria-expanded` и `aria-controls`
+  на показанный регион (сама кнопка при спуске скрыта), регион подписан именем Категории.
+
+Подпись «Назад» берётся из каталога сообщений: ключ `megaMenu.back`, по умолчанию «Back»; русский каталог
+отдаёт «Назад».
+
+Ширину кит читает через `matchMedia`, а не через CSS: от неё зависит состав разметки (прячется Столбец), а
+не только вид. До гидратации и на сервере хук возвращает «широкий» (ADR-0018): сервер ширины не знает, и
+разметка с него всегда обычная. На телефоне после гидратации Витрина, открытая `defaultValue`, один раз
+перерисовывается спуском. На телефоне `nav` занимает всю ширину классом `max-sm:w-full`; `w-*` из `className` действует на
+широком экране.
+
+## Прицел
+
+Курсор идёт от Категории к её Витрине наискосок и по пути задевает соседние Категории. Если бы наведение
+открывало их сразу, Витрина менялась бы у человека под рукой, и до ссылки было бы не дотянуться. Прицел смотрит,
+куда движется курсор: пока он идёт в сторону открытой Витрины, соседняя Категория наведение не перехватывает.
+
+- Направление последнего шага курсора сравнивается с сектором от его прежней точки к двум углам ближнего края
+  Витрины — это и есть треугольник Каменса из раздела «Откуда это». Шаг в сектор — курсор целится.
+- Одно движение мимо прощается, два подряд — нет: тогда открывается Категория под курсором.
+- Курсор остановился на 300 мс — открывается Категория под ним, даже если он целился. Меню не «залипает».
+- Курсор дошёл до Витрины — отложенная смена отменяется.
+- Щелчок по Категории открывает её сразу, мимо Прицела. Клавиатура Прицела не знает вовсе.
+- Только мышь, и только на широком экране: касание и перо открывают Категорию сразу, а на узком экране
+  Прицела нет вовсе.
+- Первое наведение, пока Витрины нет, открывает Категорию без всякой задержки: целиться ещё не во что.
+
+Модель та же, что у подменю react-aria (`Menu` с `SubmenuTrigger`), чтобы два меню кита вели себя одинаково.
+Отличий два. Смена Категории откладывается, а не гасится `pointer-events: none` на Столбце: иначе пропала бы
+подсветка под курсором и щелчок по соседней Категории. И время остановки — 300 мс, как в плагине Каменса (о нём — в «Откуда это»), а не секунда,
+как у react-aria: его подменю короткое, а Столбец каталога листают.
+
+## Откуда это
+
+Приём пришёл из Amazon. К 2013 году меню «Shop by Department» на amazon.com уже работало так: столбец отделов
+слева, большая панель справа, и переключение без всякой задержки — при этом наискосок к панели курсор проходил,
+не сбивая её. Как это устроено, разобрал Бен Каменс.
+
+- **6 марта 2013** — Бен Каменс, разработчик Khan Academy, публикует разбор «Breaking down Amazon's mega
+  dropdown». Он показывает, что Amazon не тормозит открытие задержкой, как большинство выпадающих меню, а следит
+  за направлением курсора: пока тот внутри треугольника между курсором и углами панели, подменю не меняется.
+  Khan Academy ставит приём в своё новое меню «Learn».
+- **Март 2013** — Каменс выкладывает плагин `jQuery-menu-aim` на GitHub: треугольник, допуск у углов и
+  задержка 300 мс для курсора, который остановился.
+- **7 марта 2013** — пересказ статьи на Хабре, с которого приём разошёлся по рунету.
+- **Дальше** — приём уходит в библиотеки: «безопасный многоугольник» `safePolygon()` в Floating UI, «grace
+  area» подменю в Radix, «безопасный треугольник» `useSafelyMouseToSubmenu` в react-aria. В react-aria подменю
+  вышли альфой 13 февраля 2024 года (v1.1.0) и стали стабильными 1 мая 2024 года (v1.2.0).
+- **2026** — `MegaMenu` в `@olddevs/ui`: модель react-aria и пауза Каменса.
+
+Первоисточники:
+[статья Бена Каменса](https://bjk5.com/post/44698559168/breaking-down-amazons-mega-dropdown),
+[репозиторий `jQuery-menu-aim`](https://github.com/kamens/jQuery-menu-aim),
+[пересказ на Хабре](https://habr.com/ru/articles/171905/).
+
+## Клавиатура и имена
+
+- Столбец — одна остановка Tab. Стрелки вверх и вниз, Home и End ходят по Категориям; выключенные
+  пропускаются. Вернувшись Tab'ом, пользователь попадает на ту Категорию, где был.
+- Enter, Пробел и стрелка в сторону Витрины открывают её и ставят фокус на первую ссылку. У Категории-ссылки
+  Enter — переход.
+- Внутри Витрины работает обычный Tab. Стрелка в сторону Столбца возвращает фокус на Категорию, Escape — тоже,
+  и закрывает Витрину. Tab за последней ссылкой уходит дальше по странице и закрывает Витрину.
+- Пока Витрина открыта, она следует за фокусом стрелок, как следует за наведением.
+- Стрелка «к Витрине» — та, что смотрит туда, где Витрина стоит: при письме справа налево и у края экрана
+  стрелки меняются местами.
+- Скринридер слышит навигацию с именем из `aria-label`, Категории — кнопками «развёрнуто / свёрнуто», Витрину
+  — регионом с именем Категории, колонку — списком с именем заголовка.
+
+## Выпадающий вид
+
+Каталог в шапке открывают кнопкой «Каталог», а не держат на странице. Разметка Категорий та же, что во встроенном
+виде, меняется только обёртка: `MegaMenu` кладут в `MegaMenuTrigger` вторым после кнопки `MegaMenuButton`.
+
+```tsx
+import {
+  MegaMenu,
+  MegaMenuButton,
+  MegaMenuCategory,
+  MegaMenuGroup,
+  MegaMenuLink,
+  MegaMenuTrigger,
+} from "@olddevs/ui";
+import { ListIcon } from "@olddevs/ui/icons";
+
+<MegaMenuTrigger>
+  <MegaMenuButton icon={<ListIcon size={16} />}>Каталог</MegaMenuButton>
+  <MegaMenu aria-label="Каталог">
+    <MegaMenuCategory id="computers" label="Компьютеры" href="/computers">
+      <MegaMenuGroup title="Ноутбуки">
+        <MegaMenuLink href="/computers/laptops/gaming">Игровые</MegaMenuLink>
+      </MegaMenuGroup>
+    </MegaMenuCategory>
+  </MegaMenu>
+</MegaMenuTrigger>;
+```
+
+`MegaMenuTrigger`: `open`, `defaultOpen` и `onOpenChange` — открытость, управляемо или нет, как у других
+оверлеев кита. Первый ребёнок — кнопка, все остальные уходят в оверлей; разбор идёт по позиции, поэтому кнопку
+можно обернуть своим компонентом, а `MegaMenu` — вынести в свой. `MegaMenuButton` принимает вид кнопки кита
+(`variant`, `tone`, `size`, `iconOnly`, `selected`), `icon`, `disabled`, `aria-label` и `className`; вид тот же, что у
+`MenuButton`.
+
+- **Открытие.** Щелчок, Enter, Пробел и стрелка вниз на кнопке. Наведение каталог не открывает: он не должен
+  выпрыгивать от случайного движения мыши.
+- **Фокус.** При открытии фокус встаёт на первую доступную Категорию (если одна из них уже открыта через `value` или
+  `defaultValue` — на неё), Витрина закрыта до выбора. Дальше Столбец и Витрина работают как во встроенном виде.
+- **Закрытие.** Escape на Категории, нажатие вне каталога, повторный щелчок по кнопке, переход по любой ссылке
+  (Категория, заголовок колонки, `MegaMenuLink`, в том числе ссылки роутера) и Tab за последним элементом.
+  Первый Escape внутри Витрины закрывает только Витрину и возвращает фокус на её Категорию; оверлей закрывает
+  следующий.
+- **Возврат фокуса.** На кнопку фокус возвращается при Escape и при повторном щелчке. После Tab за последним
+  элементом фокус идёт дальше по странице, за кнопкой; Shift+Tab перед первым элементом возвращает на кнопку. После
+  нажатия вне каталога фокус остаётся там, куда нажал пользователь.
+- **Скринридер.** Кнопка — раскрыватель с `aria-expanded` и `aria-controls`, без `aria-haspopup`: оверлей — не
+  меню и не диалог, а та же навигация с ссылками. Роли `dialog` у оверлея нет.
+- **Слои.** Оверлей лежит на слое `popover`: выше затемнения открытого `Dialog`, ниже подтверждения. Внутри окна
+  первый Escape закрывает каталог, следующий — окно. Если фокус в открытой Витрине, самый первый Escape закрывает
+  только её и возвращает фокус на Категорию.
+- **Высота.** Оверлей не выше видимой области от кнопки до края окна. Столбец и Витрина прокручиваются каждый
+  внутри себя (`overscroll-contain`), а не оверлей целиком: иначе рамка оверлея обрезала бы Витрину, которая
+  стоит рядом со Столбцом. На iOS высота ограничена `min(24rem, 60dvh)`, как у панели `Menu`.
+- **Появление.** Плавное, по шкале движения кита; при `prefers-reduced-motion` без анимации.
+- **Сервер.** На сервере рисуется закрытая кнопка; оверлей монтируется в портале после открытия.
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/navigation/MegaMenu.tsx`, Прицел — `src/components/navigation/useMenuAim.ts`.
+- Тесты: `tests/mega-menu.test.tsx` — роли и `aria-controls`, наведение и монтирование только открытой
+  Витрины, закрытие с задержкой, roving tabindex, Enter, Escape и стрелки, Tab за последней ссылкой,
+  Категория-ссылка, выключенная Категория, `current`, `asChild` и `link`, управляемое значение, нажатие вне
+  каталога, рендер на сервере; `tests/mega-menu-aim.test.tsx` — Прицел на подменённой геометрии и поддельном
+  времени, переворот у края; `tests/mega-menu-touch.test.tsx` — касание и перо, подмена `matchMedia`, спуск
+  вместо Столбца, «Назад» и фокус, Escape, подписи из каталога сообщений, рендер на сервере; браузерный тест `tests-visual/mega-menu.spec.ts` — настоящая мышь наискосок и вниз
+  по Столбцу.
+- Выпадающий вид: `tests/mega-menu-dropdown.test.tsx` — открытие щелчком и клавишами с фокусом на первой
+  Категории, все пути закрытия и возврат фокуса, Escape в Витрине, `open` / `defaultOpen` / `onOpenChange`, слой
+  `popover`, порядок Escape внутри `Dialog`, рендер на сервере.
+- История: `src/components/navigation/MegaMenu.stories.tsx` — в том числе `DropdownInTopBar`, мегаменю в шапке; на ширине
+  телефона — `PhoneColumn` и `PhoneDrillDown`.

package/docs/components/overlays/menu.en.md

@@ -5,7 +5,7 @@ category: overlays
 status: stable
 source: src/components/overlays/Menu.tsx
 story: src/components/overlays/Menu.stories.tsx
-sourceHash: cedb4db63593
+sourceHash: 473c4ffa0e0a
 ---
 
 # Menu
@@ -15,7 +15,11 @@ sourceHash: cedb4db63593
 `Menu` is a compound action menu opened by `MenuTrigger`. Inside `MenuTrigger`,
 use the dedicated `MenuButton`, not a regular `Button`: only it reads react-aria's
 `ButtonContext`. The menu suits heterogeneous commands, sections, selected modes
-and submenus; it is not for choosing a field value.
+and submenus; it is not for choosing a field value. A nested `Menu` inside
+`SubmenuTrigger` opens beside its item on its own, and below it on a narrow
+screen: you do not need to set `placement`. The "aim" (protection that keeps a
+submenu from closing while the pointer travels toward it) comes from react-aria;
+do not write your own.
 
 ## When to use
 
@@ -52,8 +56,9 @@ the props that set the button's look, `icon`, `children`, `disabled`, `aria-labe
 and `className`; `aria-label` is required if the button has no text, and with
 `iconOnly` it never does. `Menu` accepts the usual `AriaMenuProps`, plus `offset`,
 the gap between the panel and the button in pixels (default 6), and `placement`,
-the side where the panel opens (default `bottom start`; also `bottom end`,
-`top start`, `top end`, `right top` and `left top`).
+the side where the panel opens (default for the root menu `bottom start`; also
+`bottom end`, `top start`, `top end`, `right top` and `left top`; the submenu
+default is described below).
 
 `MenuItem` accepts the `AriaMenuItem` props, `icon`, `shortcut`, `tone`,
 `disabled` and `className`; pass the action in `onAction`. `MenuSection` accepts
@@ -61,6 +66,19 @@ the side where the panel opens (default `bottom start`; also `bottom end`,
 `selectedKeys` and `onSelectionChange` on the section, not `checked` on the item.
 `MenuSeparator` separates groups.
 
+A submenu, a `Menu` inside a `SubmenuTrigger`, opens to the right of its item by
+default, with its top edge level with the item. When there is not enough room on
+the right, react-aria flips it to the left. In a right-to-left layout everything is
+mirrored: the submenu opens to the left of its item. On a narrow screen (up to 639px wide)
+there is no room on either side, so the submenu opens below its item, over the
+parent menu. An explicit `placement` on the nested `Menu` wins over the default,
+phones included. The root menu opens as before, at `bottom start`. The Editor's
+submenus follow the same rule.
+
+Moving the pointer diagonally toward a submenu neither closes it nor switches to a
+neighboring item: this "aim" is handled by react-aria's `SubmenuTrigger`. The kit
+does not replace it and adds none of its own, so do not write one on top of it.
+
 react-aria sets the menu panel's height from the visible area. Items that do
 not fit scroll inside the panel (`overflow-y: auto`, the scroll does not leak to
 the page) instead of being rendered past its edge over the content. On iOS the panel

package/docs/components/overlays/menu.md

@@ -14,7 +14,10 @@ story: src/components/overlays/Menu.stories.tsx
 `Menu` — составное меню действий, открываемое `MenuTrigger`. Внутри `MenuTrigger`
 используйте специальный `MenuButton`, а не обычный `Button`: только он читает
 `ButtonContext` react-aria. Меню подходит для разнородных команд, разделов, выбранных режимов и
-подменю; не для выбора значения поля.
+подменю; не для выбора значения поля. Вложенный `Menu` в `SubmenuTrigger` сам
+раскрывается сбоку от пункта, на узком экране под ним: `placement` задавать не
+нужно. «Прицел» (защита подменю от случайного закрытия при движении курсора к
+нему) даёт react-aria, свой не пишите.
 
 ## Когда использовать
 
@@ -50,9 +53,9 @@ story: src/components/overlays/Menu.stories.tsx
 button look props, `icon`, `children`, `disabled`, `aria-label` и `className`;
 `aria-label` обязателен, если у кнопки нет подписи; с `iconOnly` её нет всегда.
 `Menu` принимает обычные `AriaMenuProps`, плюс `offset` — отступ панели от кнопки
-в пикселях (умолчание 6) и `placement` — сторона раскрытия (умолчание
-`bottom start`; ещё `bottom end`, `top start`, `top end`, `right top`,
-`left top`).
+в пикселях (умолчание 6) и `placement` — сторона раскрытия (умолчание корневого
+меню `bottom start`; ещё `bottom end`, `top start`, `top end`, `right top`,
+`left top`; умолчание подменю — ниже).
 
 `MenuItem` принимает props `AriaMenuItem`, `icon`, `shortcut`, `tone`, `disabled`
 и `className`; действие передавайте в `onAction`. `MenuSection` принимает
@@ -60,6 +63,19 @@ button look props, `icon`, `children`, `disabled`, `aria-label` и `className`;
 `selectionMode`, `selectedKeys` и `onSelectionChange` на section, а не `checked`
 на item. `MenuSeparator` разделяет группы.
 
+Подменю — `Menu` внутри `SubmenuTrigger` — по умолчанию раскрывается справа от
+своего пункта, верхним краем вровень с ним. Если справа не хватает места,
+react-aria переворачивает подменю влево. При письме справа налево всё зеркально:
+подменю раскрывается слева от пункта. На узком экране (до 639px шириной) места
+сбоку нет ни справа, ни слева, и подменю встаёт под своим пунктом, поверх
+родительского меню. Явный `placement` у вложенного `Menu` побеждает умолчание, в
+том числе на телефоне. Корневое меню раскрывается как прежде — `bottom start`.
+То же правило у подменю Редактора.
+
+Движение курсора к подменю по диагонали его не закрывает и не переключает на
+соседний пункт: этот «Прицел» работает в `SubmenuTrigger` из react-aria. Кит его
+не подменяет и своего не добавляет — не пишите поверх него свой.
+
 Высоту панели меню задаёт react-aria по видимой области. Пункты, которые в неё
 не влезли, прокручиваются внутри панели (`overflow-y: auto`, прокрутка не
 уходит на страницу), а не рисуются за её краем поверх содержимого. На iOS

package/docs/getting-started.en.md

@@ -1,5 +1,5 @@
 ---
-sourceHash: 19857ad0f54d
+sourceHash: 5f89459633fb
 ---
 
 # Setting up `@olddevs/ui`
@@ -132,10 +132,10 @@ peer dependencies are treated as external, and the metric is gzip:
 | `cn` and `tableStateToParams`                                                                            | 0.6 kB   |
 | one `Button`                                                                                             | 1.6 kB   |
 | `DataTable`                                                                                              | 9.0 kB   |
-| the whole kit (`import *`)                                                                               | 71.1 kB  |
-| `RichTextEditor` from `@olddevs/ui/editor`, without the engine, "start"                                  | 70.4 kB  |
-| `RichTextEditor` with the Tiptap engine, "start" (static graph, `basic`)                                 | 295.1 kB |
-| `RichTextEditor` with the Tiptap engine, "full" (with all lazy chunks, `full`)                           | 338.9 kB |
+| the whole kit (`import *`)                                                                               | 76.4 kB  |
+| `RichTextEditor` from `@olddevs/ui/editor`, without the engine, "start"                                  | 70.6 kB  |
+| `RichTextEditor` with the Tiptap engine, "start" (static graph, `basic`)                                 | 295.3 kB |
+| `RichTextEditor` with the Tiptap engine, "full" (with all lazy chunks, `full`)                           | 339.1 kB |
 | `RichTextView` from `@olddevs/ui/editor`, Tiptap engine included in the measurement                      | 12.0 kB  |
 | `sanitizeRichText` and `richTextSanitizeConfig` from `@olddevs/ui/editor/schema`, Tiptap engine included | 3.6 kB   |
 | `highlightCodeBlocks` from `@olddevs/ui/editor/highlight`, with lowlight                                 | 22.6 kB  |

package/docs/getting-started.md

@@ -129,10 +129,10 @@ peer-зависимости внешние, метрика gzip:
 | `cn` и `tableStateToParams`                                                                                 | 0,6 кБ   |
 | одна `Button`                                                                                               | 1,6 кБ   |
 | `DataTable`                                                                                                 | 9,0 кБ   |
-| весь кит целиком (`import *`)                                                                               | 71,1 кБ  |
-| `RichTextEditor` из `@olddevs/ui/editor`, без движка, «старт»                                               | 70,4 кБ  |
-| `RichTextEditor` вместе с движком Tiptap, «старт» (статический граф, `basic`)                               | 295,1 кБ |
-| `RichTextEditor` вместе с движком Tiptap, «полный» (со всеми ленивыми чанками, `full`)                      | 338,9 кБ |
+| весь кит целиком (`import *`)                                                                               | 76,4 кБ  |
+| `RichTextEditor` из `@olddevs/ui/editor`, без движка, «старт»                                               | 70,6 кБ  |
+| `RichTextEditor` вместе с движком Tiptap, «старт» (статический граф, `basic`)                               | 295,3 кБ |
+| `RichTextEditor` вместе с движком Tiptap, «полный» (со всеми ленивыми чанками, `full`)                      | 339,1 кБ |
 | `RichTextView` из `@olddevs/ui/editor`, движок Tiptap в замер включён                                       | 12,0 кБ  |
 | `sanitizeRichText` и `richTextSanitizeConfig` из `@olddevs/ui/editor/schema`, движок Tiptap в замер включён | 3,6 кБ   |
 | `highlightCodeBlocks` из `@olddevs/ui/editor/highlight`, вместе с lowlight                                  | 22,6 кБ  |

package/docs/glossary.en.md

@@ -1,5 +1,5 @@
 ---
-sourceHash: 7b328de94ead
+sourceHash: 2524e6589eaa
 ---
 
 # Glossary of `@olddevs/ui`
@@ -124,6 +124,11 @@ search for a single word.
 | **tag**               | `Tag` in `TagGroup` and `TagInput`: a compact element with text and an optional remove button                              | The Editor's Mark and a field label                                                                    |
 | **close button**      | The button with an "×" that closes a dialog, drawer, popover or notification; in a search field it is the **clear button** | A "Cancel" button. Do not write: cross                                                                 |
 | **shortcut list**     | `ShortcutsHelp`: a dialog with a list of keyboard shortcuts                                                                | The Editor's Shortcuts reference: that one opens from the Toolbar and describes the Editor's shortcuts |
+| **mega menu**         | `MegaMenu`: a category column and the showcase of the hovered category, an Amazon-style catalog                            | `Menu`: that one is for commands, not navigation. Do not write: mega dropdown                          |
+| **category**          | `MegaMenuCategory`: a row of the category column with a label, an icon and its own showcase                                | A menu item (`MenuItem`)                                                                               |
+| **category column**   | The vertical list of categories in a mega menu                                                                             | `SideNav`: that one expands branches in place                                                          |
+| **showcase**          | The area next to the category column with the open category's content: link columns, promos                                | The Editor toolbar, a popover                                                                          |
+| **aim**               | Deferring the category switch while the pointer cuts diagonally toward the open showcase                                   | An opening delay: aim never slows down a direct hover                                                  |
 
 ## Editor
 

package/docs/glossary.md

@@ -120,6 +120,11 @@
 | **Тег**                    | `Tag` в `TagGroup` и `TagInput`: компактный элемент с текстом и необязательной кнопкой удаления                 | Меткой Редактора (`Mark`) и подписью поля. Не пишем: таг                                                |
 | **Кнопка закрытия**        | Кнопка с иконкой «×», которая закрывает окно, ящик, поповер или уведомление; у поля поиска — **кнопка очистки** | Кнопкой «Отмена». Не пишем: крестик                                                                     |
 | **Свод сочетаний**         | `ShortcutsHelp`: окно со списком сочетаний клавиш                                                               | Справочником Редактора: тот открывается из Панели и описывает сочетания Редактора                       |
+| **Мегаменю**               | `MegaMenu`: Столбец категорий и Витрина наведённой Категории — каталог в духе Amazon                            | `Menu`: тот для команд, а не для навигации. Не пишем: мега-дропдаун                                     |
+| **Категория**              | `MegaMenuCategory`: строка Столбца с подписью, иконкой и своей Витриной                                         | Пунктом меню (`MenuItem`)                                                                               |
+| **Столбец категорий**      | Вертикальный список Категорий Мегаменю                                                                          | `SideNav`: тот раскрывает ветки на месте                                                                |
+| **Витрина**                | Область рядом со Столбцом с содержимым открытой Категории: колонки ссылок, промо                                | Панелью Редактора и поповером                                                                           |
+| **Прицел**                 | Отложенная смена Категории, пока курсор идёт наискосок к открытой Витрине                                       | Задержкой открытия: прямое наведение Прицел не тормозит                                                 |
 
 ## Редактор
 

package/llms.txt

@@ -108,6 +108,7 @@
 - [Breadcrumbs](docs/components/navigation/breadcrumbs.md): `Breadcrumbs` показывает путь до текущей страницы.
 - [Pagination](docs/components/navigation/pagination.md): `Pagination` — controlled pagination для уже разбитой на страницы коллекции.
 - [Stepper](docs/components/navigation/stepper.md): `Stepper` показывает порядок шагов мастера; текущий индекс задаёт родитель (controlled).
+- [MegaMenu](docs/components/navigation/mega-menu.md): `MegaMenu` — каталог магазина в духе Amazon: слева Столбец категорий, справа от наведённой Категории — её Витрина с колонками ссылок и любым своим содержимым.
 - [TreeView](docs/components/navigation/tree-view.md): Иерархия с раскрытием, выбором и клавиатурой на `Tree` из react-aria.
 - [SelectionBar и useStickyOffset](docs/components/navigation/selection-bar.md): `SelectionBar` — полоса массовых действий: «Выбрано 12» и что с этим можно сделать.
 - [ContextualSaveBar](docs/components/navigation/contextual-save-bar.md): Полоса несохранённых изменений: появляется с первой правкой формы, показывает «есть несохранённые изменения» (или их число) и две кнопки — сохранить и отменить.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olddevs/ui",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Olddevs UI — design system: tokens, themes and accessible UI primitives",
   "license": "MIT",
   "private": false,

package/src/components/actions/Toggle.tsx

@@ -194,10 +194,17 @@ export const Toggle = forwardRef<HTMLButtonElement, ToggleProps>(function Toggle
     оно обёрнуто в свой `<label for>`.
   */
   return (
-    <div className={cn("flex items-center justify-between gap-4", className)}>
+    <div className={cn("group/toggle flex items-center justify-between gap-4", className)}>
       {/* Приглушается только текст: дорожка приглушает себя сама (`disabled:opacity-50`),
-          и общая прозрачность строки дала бы ей 25 % вместо 50 % — иначе, чем без подписи. */}
-      <div className={cn("flex min-w-0 flex-col", disabled && "opacity-50")}>
+          и общая прозрачность строки дала бы ей 25 % вместо 50 % — иначе, чем без подписи.
+          `group-has-[[role=switch]:disabled]/toggle:` — для кнопки, выключенной предком-`fieldset`:
+          свойство `disabled` у неё при этом ложно, и одно оно текст не погасило бы. */}
+      <div
+        className={cn(
+          "flex min-w-0 flex-col group-has-[[role=switch]:disabled]/toggle:opacity-50",
+          disabled && "opacity-50"
+        )}
+      >
         <label
           id={labelId}
           htmlFor={switchId}

package/src/components/actions/Truncate.tsx

@@ -68,10 +68,12 @@ export function Truncate({ children, lines = 1, side = "top", className, ...rest
       // клавиатурой не нужен и мешал бы.
       tabIndex={truncated ? 0 : undefined}
       className={cn(
-        "focus-visible:outline-accent-strong block min-w-0 focus-visible:outline-2 focus-visible:outline-offset-2",
+        "focus-visible:outline-accent-strong min-w-0 focus-visible:outline-2 focus-visible:outline-offset-2",
         lines === 1
-          ? "truncate"
-          : // Многострочная обрезка: `line-clamp` считает строки сам, и число
+          ? "block truncate"
+          : // `block` сюда нельзя: в CSS он стоит позже `[display:-webkit-box]`,
+            // перебивает его, и `line-clamp` молча не работает.
+            // Многострочная обрезка: `line-clamp` считает строки сам, и число
             // приходит переменной — иначе класс собирался бы конкатенацией, а
             // такого текста в исходниках нет и Tailwind его не увидит.
             "[display:-webkit-box] overflow-hidden [-webkit-box-orient:vertical]",

package/src/components/app-shell/MobileTabBar.tsx

@@ -263,7 +263,15 @@ export const MobileTabBarItem = forwardRef<HTMLAnchorElement, MobileTabBarItemPr
             {custom ? (
               <span className="absolute top-[-2px] -right-1.5 flex">{custom}</span>
             ) : shown ? (
-              <Badge overlay dot={dot} className="top-[-2px] -right-1.5">
+              // Значок держится ЛЕВОЙ кромкой у правого верхнего угла иконки и растёт
+              // вправо: привязка правой кромкой (`-right-1.5`) растила широкий «99+» или
+              // «Beta» влево, на иконку. Сдвиг `-ml-*` повторяет прежнее положение точки
+              // (8px) и короткого числа (16px): они выглядят как раньше.
+              <Badge
+                overlay
+                dot={dot}
+                className={cn("top-[-2px] right-auto left-full", dot ? "-ml-0.5" : "-ml-2.5")}
+              >
                 {count ?? text}
               </Badge>
             ) : null}

package/src/components/app-shell/NavItem.tsx

@@ -68,7 +68,12 @@ export interface NavItemProps extends Omit<ComponentPropsWithoutRef<"a">, "child
 const BASE =
   "focus-visible:outline-accent-strong flex items-center gap-3 rounded-control border " +
   "px-3 py-[9px] text-[13px] leading-5 no-underline transition-colors " +
-  "focus-visible:outline-2 focus-visible:outline-offset-2";
+  "focus-visible:outline-2 focus-visible:outline-offset-2 " +
+  // Недоступный пункт красится по `aria-disabled`, как у `Button`: у ссылки нет
+  // родного `disabled`, и без этого правила пункт, выключенный атрибутом ARIA,
+  // выглядел бы рабочим — с тем же цветом и курсором-указателем.
+  "aria-disabled:opacity-50 aria-disabled:cursor-default " +
+  "aria-disabled:hover:bg-transparent aria-disabled:hover:text-fg-1";
 
 const STATE = {
   active: "border-line bg-bg-3 text-fg-0 font-semibold",

package/src/components/content/AvatarGroup.tsx

@@ -56,6 +56,9 @@ export function AvatarGroup({
   const members = names.map((entry) => (typeof entry === "string" ? { name: entry } : entry));
   const shown = members.slice(0, max);
   const rest = members.length - shown.length;
+  // Перекрытие по размеру круга: на 28px прежние 8px плюс кольцо срезали
+  // инициалы слева и плюс у «+N»; на 64px они не мешают.
+  const overlap = size === "lg" ? "-ml-2" : "-ml-1";
 
   return (
     <span
@@ -67,7 +70,7 @@ export function AvatarGroup({
         <span
           key={`${name}-${index}`}
           aria-hidden
-          className={cn("ring-bg-1 relative rounded-full ring-2", index > 0 && "-ml-2")}
+          className={cn("ring-bg-1 relative rounded-full ring-2", index > 0 && overlap)}
           style={{ zIndex: shown.length - index }}
         >
           {/* `alt=""`: круг скрыт, имя объявляет группа — подпись у фото была бы вторым чтением. */}
@@ -80,7 +83,8 @@ export function AvatarGroup({
           className={cn(
             // `text-fg-1`, а не `fg-2`: на подложке `bg-3` вторая ступень не держит 4.5 —
             // поймал аудит axe. Остаток «+N» это содержимое, а не подсказка.
-            "bg-bg-3 text-fg-1 ring-bg-1 relative -ml-2 flex items-center justify-center rounded-full font-semibold ring-2",
+            "bg-bg-3 text-fg-1 ring-bg-1 relative flex items-center justify-center rounded-full font-semibold ring-2",
+            overlap,
             size === "lg" ? "text-md h-16 w-16" : "text-caption h-7 w-7"
           )}
         >

package/src/components/content/Table.tsx

@@ -298,6 +298,13 @@ export function Table<T extends { id: Key }>({
   /** Сколько ячеек в строке — столько же обязана занять детальная. */
   const span = columns.length + (selectable ? 1 : 0) + (expandable ? 1 : 0);
 
+  /*
+    Ширина служебных колонок (выбор, раскрытие) идёт тем же путём, что и
+    `column.width`: `width` действует только внутри `ResizableTableContainer`,
+    вне его колонка растягивается наравне с данными, поэтому нужен CSS-стиль.
+  */
+  const serviceWidth = resizable ? { width: 40 } : { style: { width: 40 } };
+
   const table = (
     <AriaTable
       {...rest}
@@ -339,7 +346,7 @@ export function Table<T extends { id: Key }>({
         {selectable ? (
           <Column
             className="border-line-soft bg-bg-1 text-fg-2 border-b px-3 py-2 text-left font-semibold"
-            width={40}
+            {...serviceWidth}
           >
             {/*
               Флажок «выделить всё» — родной RAC (`slot="selection"`), а не наш
@@ -354,7 +361,7 @@ export function Table<T extends { id: Key }>({
         {expandable ? (
           <Column
             id={`${COLUMN_KEY}od-expander`}
-            width={40}
+            {...serviceWidth}
             className="border-line-soft bg-bg-1 border-b px-3 py-2"
           >
             {/*
@@ -401,7 +408,12 @@ export function Table<T extends { id: Key }>({
                   />
                 ) : null}
                 {resizable ? (
-                  <ColumnResizer className="bg-line-soft hover:bg-accent-strong ml-auto w-px cursor-col-resize" />
+                  <ColumnResizer
+                    className={cn(
+                      "bg-line-soft hover:bg-accent-strong w-px cursor-col-resize",
+                      column.align !== "end" && "ml-auto"
+                    )}
+                  />
                 ) : null}
               </span>
             )}