@olddevs/ui 4.1.1 → 4.2.0

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

@@ -0,0 +1,273 @@
+---
+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
+sourceHash: 8e166f4b1ab7
+---
+
+# MegaMenu
+
+## Summary for AI
+
+`MegaMenu` is an Amazon-style store catalog: a category column on the left and, next to the hovered
+category, its showcase with columns of links and any content of your own. It is link navigation, not a command
+menu: the markup follows the WAI-ARIA Disclosure Navigation pattern (`nav`, buttons with `aria-expanded`, real
+`a` elements). Categories are `MegaMenuCategory` as direct children, columns are `MegaMenuGroup`, links are
+`MegaMenuLink`. The same catalog opens as a dropdown overlay from a button: `MegaMenuTrigger` with
+`MegaMenuButton` and an unchanged `MegaMenu`.
+
+## When to use
+
+- A catalog with ten or more sections, each with subsections in columns: a store, a marketplace, a help portal.
+- The sections should be visible at once and the subsections should appear on hover, without taking the user
+  off the page.
+- The showcase needs content of its own next to the links: a promo card, an image, a selection.
+
+## When not to use
+
+- For commands on an object ("Rename", "Delete"), use `Menu`: it holds actions, not navigation.
+- For application navigation with a current section, use `SideNav`.
+- For a deep hierarchy that expands in place, use `TreeView`.
+- For two or three links with no subsections, use a plain list of links or `Tabs`.
+
+## Minimal example
+
+```tsx
+import { MegaMenu, MegaMenuCategory, MegaMenuGroup, MegaMenuLink } from "@olddevs/ui";
+
+<MegaMenu aria-label="Catalog">
+  <MegaMenuCategory id="computers" label="Computers" href="/computers">
+    <MegaMenuGroup title="Laptops" href="/computers/laptops">
+      <MegaMenuLink href="/computers/laptops/gaming">Gaming</MegaMenuLink>
+      <MegaMenuLink href="/computers/laptops/ultrabooks" current>
+        Ultrabooks
+      </MegaMenuLink>
+    </MegaMenuGroup>
+  </MegaMenuCategory>
+  <MegaMenuCategory id="deals" label="Deals of the day" href="/deals" />
+</MegaMenu>;
+```
+
+## Props
+
+`MegaMenu`:
+
+| Prop                                       | Default   | Meaning                                                                                                           |
+| ------------------------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------- |
+| `aria-label`                               | —         | The accessible name of the navigation. Required: on a page with several `nav` elements, the name tells them apart |
+| `value` / `defaultValue` / `onValueChange` | `null`    | The open category (its `id`) or `null`, controlled or uncontrolled                                                |
+| `showcaseWidth`                            | `"40rem"` | The width of the showcase, shared by all categories so that the catalog does not jump between them                |
+| `className`                                | —         | Classes for the `nav`; the default width of the category column is `w-64`                                         |
+
+`MegaMenuCategory`: `id` is the key for `value`; `label` is the text in the category column and the name of the
+showcase; `icon`; `href` or `link` is the address of the whole section; `disabled`; the children are the content of
+the showcase. For a category with a showcase, the address becomes a title link at the top of the showcase; for a
+category without children, the row in the category column is itself the link. `link` is a router link passed as an
+empty element (`link={<Link href="/x" />}`), and the label moves inside it. It is a separate prop rather than
+`asChild` because the children of a category are its showcase.
+
+`MegaMenuGroup`: `title` is the title of the column and the name of its list; `href` turns the title into a link;
+the children are `MegaMenuLink` elements, and each one is placed in its own list item.
+
+`MegaMenuLink`: the usual `a` props, `icon`, `current` and `asChild`. `current` sets `aria-current="page"` and the
+look of the current link. The kit does not work out the current page itself, because every router compares
+addresses by its own rules. `asChild` renders the link as a router element:
+`<MegaMenuLink asChild><Link href="/x">Label</Link></MegaMenuLink>`.
+
+## Hover and the showcase
+
+Hovering a category with the mouse opens its showcase at once, with no delay. Exactly one category is highlighted,
+the one whose showcase is open: the highlight follows `aria-expanded`, not `:hover`. Hovering a category without a
+showcase closes the open one, with the same caveat about aim as below.
+
+The showcase closes 150 ms after the pointer has left both the category column and the showcase, so a brief
+excursion past the edge does not reset the catalog. It also closes on a pointer press outside the catalog and when
+focus leaves the catalog.
+
+The content of a showcase is mounted only for the open category, so a catalog of a hundred links and images does
+not load everything at once. The region itself is always there, hidden: the button's `aria-controls` points to it.
+
+The showcase is a DOM descendant of its category, not a portal. That is why the Tab order runs "category, its
+links, then on down the page", and why the showcase sits flush against the category column without any position
+calculation. An ancestor with `overflow: hidden` clips it, so put the catalog where there is room beside it.
+
+The showcase sits on the end side of the line: on the right, or on the left in right-to-left writing. If there is
+not enough room there and there is enough on the other side, it moves to the other side. The kit measures the side
+ahead of time and again when the window is resized, so the arrow key that points "toward the showcase" already
+points to where the showcase will appear.
+
+## Touch and narrow screens
+
+Touch has no hover, so the touch itself (`click`) opens a category, without aim. A pointer whose `pointerType` is
+"touch" or "pen" neither opens a category on hover nor closes the showcase when it leaves: a pen behaves like a
+finger. Touching an open category again neither closes it nor goes anywhere. The showcase closes on a touch outside
+the catalog or on Escape.
+
+The mouse behaves as before: hover, aim and closing after 150 ms all remain while the screen is wide.
+
+On a narrow screen, under 640px (the same breakpoint as `Menu` submenus and Editor submenus), there is no room beside
+the category column for the showcase: the edge of the window would cut it off on the right. So the catalog works as a
+drill-down:
+
+- The category column takes the full width, and category labels wrap instead of being truncated.
+- An open category (by touch, click, Enter or Space) replaces the category column with its showcase. The showcase
+  starts with a "Back" row that shows the category name. If the category has a link of its own, the link shows the
+  name, on the row below, instead of the "Back" row. Below that, the columns of links follow, one under another.
+- "Back" returns the category column and puts focus on the category the person came from. Escape inside the showcase
+  works like "Back".
+- When you drill down, focus moves to "Back": the category button is hidden along with the category column, and focus
+  left on it would be lost. In the showcase on a narrow screen, the arrow key toward the category column does
+  nothing, because the column is not beside it.
+- There is no aim on a narrow screen: hovering with the mouse does not open a category, and moving the mouse away does
+  not cancel the drill-down. Replacing the column under the cursor would pull it out from under the person's hand.
+- The markup stays on the disclosure pattern: the category button keeps `aria-expanded` and `aria-controls` pointing
+  to the region on screen (the button itself is hidden during the drill-down), and the region is named after the
+  category.
+
+The "Back" label comes from the message catalog: the key is `megaMenu.back`, with the default "Back"; the Russian
+catalog supplies "Назад".
+
+The kit reads the width through `matchMedia`, not through CSS, because the width determines the contents of the
+markup (the category column is hidden), not just the look. Before hydration and on the server, the hook reports a wide
+screen (ADR-0018): the server does not know the width, and the markup it produces is always the regular one. On a phone,
+after hydration, a showcase opened by `defaultValue` is re-rendered once as a drill-down. On a phone the `nav` takes
+the full width through the `max-sm:w-full` class; a `w-*` class from `className` applies on a wide screen.
+
+## Aim
+
+On its way from a category to its showcase, the pointer cuts diagonally and brushes against the neighboring
+categories. If hover opened them at once, the showcase would change under the person's hand, and the links would be
+out of reach. Aim watches where the pointer is heading: while it moves toward the open showcase, a neighboring
+category does not take over the hover.
+
+- The direction of the pointer's last step is compared with the wedge from its previous position to the two corners
+  of the showcase's near edge: Kamens's triangle from "Where it comes from". A step into the wedge means the pointer
+  is aiming.
+- One movement off course is forgiven; two in a row are not, and then the category under the pointer opens.
+- If the pointer stops for 300 ms, the category under it opens even if it was aiming. The menu does not get stuck.
+- When the pointer reaches the showcase, the deferred switch is canceled.
+- Clicking a category opens it at once, bypassing aim. The keyboard knows nothing about aim.
+- Mouse only, and only on a wide screen: touch and pen open a category at once, and a narrow screen has no aim at all.
+- The first hover, while there is no showcase yet, opens the category with no delay at all: there is nothing to aim at.
+
+The model is the same as for react-aria submenus (`Menu` with `SubmenuTrigger`), so that the two menus of the kit
+behave alike. There are two differences. The category switch is deferred, not suppressed with `pointer-events: none`
+on the category column, since that would lose the highlight under the pointer and the click on a neighboring category.
+And the stop time is 300 ms, as in Kamens's plugin (more on it in "Where it comes from"), not a second, as in react-aria: its submenu is short, while the
+category column of a catalog gets scrolled through.
+
+## Where it comes from
+
+The technique comes from Amazon. By 2013 the "Shop by Department" menu on amazon.com already worked like this: a
+column of departments on the left, a large panel on the right, and switching with no delay at all, while the pointer
+could cut diagonally toward the panel without knocking it away. Ben Kamens worked out how it does that.
+
+- **6 March 2013**: Ben Kamens, a developer at Khan Academy, publishes the analysis "Breaking down Amazon's mega
+  dropdown". He shows that Amazon does not slow the opening down with a delay, as most dropdown menus do, but
+  follows the direction of the pointer: while it stays inside the triangle between the pointer and the corners of the
+  panel, the submenu does not change. Khan Academy puts the technique into its new "Learn" menu.
+- **March 2013**: Kamens publishes the `jQuery-menu-aim` plugin on GitHub: the triangle, a tolerance near the corners
+  and a 300 ms delay for a pointer that has stopped.
+- **7 March 2013**: a retelling of the article appears on Habr, from which the technique spread across the Russian-speaking web.
+- **After that**: the technique moves into libraries: the "safe polygon" `safePolygon()` in Floating UI, the "grace
+  area" of submenus in Radix, the "safe triangle" `useSafelyMouseToSubmenu` in react-aria. Submenus shipped in
+  react-aria as an alpha on 13 February 2024 (v1.1.0) and became stable on 1 May 2024 (v1.2.0).
+- **2026**: `MegaMenu` in `@olddevs/ui`: the react-aria model and Kamens's pause.
+
+Primary sources:
+[Ben Kamens's article](https://bjk5.com/post/44698559168/breaking-down-amazons-mega-dropdown),
+[the `jQuery-menu-aim` repository](https://github.com/kamens/jQuery-menu-aim),
+[a retelling on Habr, in Russian](https://habr.com/ru/articles/171905/).
+
+## Keyboard and names
+
+- The category column is a single Tab stop. The Up and Down arrows, Home and End move through the categories;
+  disabled ones are skipped. When the user comes back with Tab, they land on the category they were on.
+- Enter, Space and the arrow toward the showcase open it and put focus on the first link. On a category that is a
+  link, Enter follows it.
+- Inside the showcase, plain Tab works. The arrow toward the category column returns focus to the category, and so
+  does Escape, which also closes the showcase. Tab past the last link moves on down the page and closes the showcase.
+- While the showcase is open, it follows the arrow-key focus the way it follows hover.
+- The arrow "toward the showcase" is the one that points to where the showcase sits: in right-to-left writing and at
+  the edge of the screen, the arrows swap places.
+- A screen reader hears a navigation with the name from `aria-label`, the categories as expand/collapse buttons, the
+  showcase as a region named after the category, and a column as a list named after its title.
+
+## Dropdown mode
+
+A catalog in a page header is opened with a "Catalog" button rather than kept on the page. The markup of the
+categories is the same as in the embedded mode; only the wrapper changes: put `MegaMenu` into `MegaMenuTrigger`
+as the second child, after the `MegaMenuButton`.
+
+```tsx
+import {
+  MegaMenu,
+  MegaMenuButton,
+  MegaMenuCategory,
+  MegaMenuGroup,
+  MegaMenuLink,
+  MegaMenuTrigger,
+} from "@olddevs/ui";
+import { ListIcon } from "@olddevs/ui/icons";
+
+<MegaMenuTrigger>
+  <MegaMenuButton icon={<ListIcon size={16} />}>Catalog</MegaMenuButton>
+  <MegaMenu aria-label="Catalog">
+    <MegaMenuCategory id="computers" label="Computers" href="/computers">
+      <MegaMenuGroup title="Laptops">
+        <MegaMenuLink href="/computers/laptops/gaming">Gaming</MegaMenuLink>
+      </MegaMenuGroup>
+    </MegaMenuCategory>
+  </MegaMenu>
+</MegaMenuTrigger>;
+```
+
+`MegaMenuTrigger`: `open`, `defaultOpen` and `onOpenChange` control whether the overlay is open, controlled or
+uncontrolled, as with other overlays of the kit. The first child is the button, and all the others go into the
+overlay. Children are sorted by position, so you can wrap the button in a component of your own and move `MegaMenu`
+into one. `MegaMenuButton` accepts the kit's button look (`variant`, `tone`, `size`, `iconOnly`, `selected`), `icon`,
+`disabled`, `aria-label` and `className`; the look is the same as for `MenuButton`.
+
+- **Opening.** Click, Enter, Space and the Down arrow on the button. Hover does not open the catalog: it should not
+  jump out at a stray mouse movement.
+- **Focus.** On opening, focus goes to the first available category (or, if one is already open through `value` or
+  `defaultValue`, to that one), and the showcase stays closed until a category is chosen. After that the category column
+  and the showcase work as in the embedded mode.
+- **Closing.** Escape on a category, a press outside the catalog, a second click on the button, following any link (a
+  category, a column title, a `MegaMenuLink`, router links included) and Tab past the last element.
+  The first Escape inside a showcase closes only the showcase and returns focus to its category; the next one closes
+  the overlay.
+- **Returning focus.** Focus returns to the button on Escape and on a second click. After Tab past the last element,
+  focus moves on down the page, past the button; Shift+Tab before the first element returns it to the button. After a
+  press outside the catalog, focus stays where the user pressed.
+- **Screen reader.** The button is a disclosure with `aria-expanded` and `aria-controls` and no `aria-haspopup`: the
+  overlay is neither a menu nor a dialog, but the same navigation with links. The overlay has no `dialog` role.
+- **Layers.** The overlay sits on the `popover` layer: above the scrim of an open `Dialog`, below the confirmation.
+  Inside a dialog, the first Escape closes the catalog and the next one closes the dialog. If focus is in an open
+  showcase, the very first Escape closes only the showcase and returns focus to its category.
+- **Height.** The overlay is no taller than the visible area from the button to the edge of the window. The category
+  column and the showcase each scroll within themselves (`overscroll-contain`), not the overlay as a whole: otherwise the
+  overlay's frame would clip the showcase, which stands beside the category column. On iOS the height is capped at
+  `min(24rem, 60dvh)`, like the `Menu` panel.
+- **Appearance.** Smooth, on the kit's motion scale; with `prefers-reduced-motion`, no animation.
+- **Server.** The server renders a closed button; the overlay is mounted in a portal after opening.
+
+## Related sources and tests
+
+- Implementation: `src/components/navigation/MegaMenu.tsx`; aim is in `src/components/navigation/useMenuAim.ts`.
+- Tests: `tests/mega-menu.test.tsx` covers roles and `aria-controls`, hover and mounting only the open
+  showcase, closing with a delay, roving tabindex, Enter, Escape and the arrows, Tab past the last link,
+  a category that is a link, a disabled category, `current`, `asChild` and `link`, the controlled value, a press
+  outside the catalog and server rendering; `tests/mega-menu-aim.test.tsx` covers aim on mocked geometry and fake
+  time, and the flip at the edge; `tests/mega-menu-touch.test.tsx` covers touch and pen, a mocked `matchMedia`,
+  the drill-down in place of the category column, "Back" and focus, Escape, labels from the message catalog and server
+  rendering; the browser test `tests-visual/mega-menu.spec.ts` uses a real mouse moving diagonally and down
+  the category column.
+- Dropdown mode: `tests/mega-menu-dropdown.test.tsx` covers opening by click and keys with focus on the first
+  category, every way of closing and returning focus, Escape in the showcase, `open` / `defaultOpen` / `onOpenChange`, the
+  `popover` layer, the order of Escape inside a `Dialog` and server rendering.
+- Story: `src/components/navigation/MegaMenu.stories.tsx`, including `DropdownInTopBar`, a mega menu in a top bar; at phone
+  width, `PhoneColumn` and `PhoneDrillDown`.

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