@olddevs/ui 4.2.2 → 4.4.0

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

@@ -12,9 +12,10 @@ story: src/components/navigation/MegaMenu.stories.tsx
 ## Кратко для AI
 
 `MegaMenu` — каталог магазина в духе Amazon: слева Столбец категорий, справа от наведённой Категории — её
-Витрина с колонками ссылок и любым своим содержимым. Это навигация по ссылкам, а не меню команд: разметка по
+Полка с колонками ссылок и любым своим содержимым. Это навигация по ссылкам, а не меню команд: разметка по
 шаблону WAI-ARIA Disclosure Navigation (`nav`, кнопки с `aria-expanded`, настоящие `a`). Категории —
-`MegaMenuCategory` прямыми детьми, колонки — `MegaMenuGroup`, ссылки — `MegaMenuLink`. Тот же каталог
+`MegaMenuCategory` (прямо или внутри своих компонентов, в том числе серверных), колонки — `MegaMenuGroup`,
+ссылки — `MegaMenuLink`. Текущий раздел и текущая страница — проп `active`, как у `NavItem`. Тот же каталог
 открывается выпадающим оверлеем от кнопки: `MegaMenuTrigger` с `MegaMenuButton` и неизменным `MegaMenu`.
 
 ## Когда использовать
@@ -22,7 +23,7 @@ story: src/components/navigation/MegaMenu.stories.tsx
 - Каталог с десятком и больше разделов, у каждого — подразделы колонками: магазин, маркетплейс, справочный
   портал.
 - Разделы надо показать сразу, а подразделы — по наведению, не уводя пользователя со страницы.
-- В Витрине рядом со ссылками нужно своё содержимое: промо-карточка, картинка, подборка.
+- В Полке рядом со ссылками нужно своё содержимое: промо-карточка, картинка, подборка.
 
 ## Когда не использовать
 
@@ -37,10 +38,10 @@ story: src/components/navigation/MegaMenu.stories.tsx
 import { MegaMenu, MegaMenuCategory, MegaMenuGroup, MegaMenuLink } from "@olddevs/ui";
 
 <MegaMenu aria-label="Каталог">
-  <MegaMenuCategory id="computers" label="Компьютеры" href="/computers">
+  <MegaMenuCategory id="computers" label="Компьютеры" href="/computers" active>
     <MegaMenuGroup title="Ноутбуки" href="/computers/laptops">
       <MegaMenuLink href="/computers/laptops/gaming">Игровые</MegaMenuLink>
-      <MegaMenuLink href="/computers/laptops/ultrabooks" current>
+      <MegaMenuLink href="/computers/laptops/ultrabooks" active>
         Ультрабуки
       </MegaMenuLink>
     </MegaMenuGroup>
@@ -57,62 +58,75 @@ import { MegaMenu, MegaMenuCategory, MegaMenuGroup, MegaMenuLink } from "@olddev
 | ------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------ |
 | `aria-label`                               | —            | Доступное имя навигации, обязательно: на странице с несколькими `nav` их различают по нему |
 | `value` / `defaultValue` / `onValueChange` | `null`       | Открытая Категория (её `id`) или `null`, управляемо или нет                                |
-| `showcaseWidth`                            | `"40rem"`    | Ширина Витрины, одна на все Категории: каталог не прыгает при переходе между ними          |
+| `showcaseWidth`                            | `"40rem"`    | Ширина Полки, одна на все Категории: каталог не прыгает при переходе между ними            |
 | `className`                                | —            | Классы на `nav`; ширина Столбца по умолчанию — `w-64`                                      |
 
-`MegaMenuCategory`: `id` — ключ для `value`; `label` — подпись в Столбце и имя Витрины; `icon`; `href` или
-`link` — адрес раздела целиком; `disabled`; дети — содержимое Витрины. У Категории с Витриной адрес становится
-заголовком-ссылкой в начале Витрины, у Категории без детей сама строка Столбца — ссылка. `link` — ссылка роутера
+`MegaMenuCategory`: `id` — ключ для `value`; `label` — подпись в Столбце и имя Полки; `icon`; `href` или
+`link` — адрес раздела целиком; `disabled`; `active` — текущая страница лежит в этом разделе; дети —
+содержимое Полки. У Категории с Полкой адрес становится
+заголовком-ссылкой в начале Полки, у Категории без детей сама строка Столбца — ссылка. `link` — ссылка роутера
 пустым элементом (`link={<Link href="/x" />}`), подпись уезжает внутрь; это отдельный проп, а не `asChild`,
-потому что дети Категории — её Витрина.
+потому что дети Категории — её Полка.
 
-`MegaMenuGroup`: `title` — заголовок колонки, он же подпись списка; `href` делает заголовок ссылкой; дети —
-`MegaMenuLink`, каждая уезжает в свой пункт списка.
+`active` у Категории ставит `aria-current="true"` и красит подпись акцентным цветом — тем же, что у текущей
+ссылки. Открыта Полка или нет, отметка остаётся: текущий раздел задаёт маршрут, а не наведение. Открытая
+Категория по-прежнему выделена фоном, так что у одной строки бывают оба признака. Пока ни одна Полка не открыта,
+Tab приходит в Столбец на текущий раздел. Какой раздел текущий, решает потребитель, как с `active` у `NavItem`.
 
-`MegaMenuLink`: обычные пропы `a`, `icon`, `current` и `asChild`. `current` ставит `aria-current="page"` и вид
+Категории не обязаны быть прямыми детьми `MegaMenu`: их можно разложить по своим компонентам и рендерить из
+серверного компонента Next.js. Каждая Категория сама сообщает Столбцу о себе, а Столбец не разбирает детей по
+типу — у серверного компонента тип элемента на клиенте другой. До гидратации, пока Категории о себе не сообщили,
+остановка Tab стоит у каждой доступной Категории; после гидратации Столбец снова одна остановка.
+
+`MegaMenuGroup`: `title` — заголовок колонки, он же подпись списка; `href` или `link` делают заголовок ссылкой
+(`link` — ссылка роутера пустым элементом, как у Категории); дети — `MegaMenuLink`, каждая уезжает в свой пункт
+списка, в том числе пришедшие фрагментом.
+
+`MegaMenuLink`: обычные пропы `a`, `icon`, `active` и `asChild`. `active` ставит `aria-current="page"` и вид
 текущей: текущую страницу кит не вычисляет, правила сравнения адресов у каждого роутера свои. `asChild` выводит
-ссылку элементом роутера: `<MegaMenuLink asChild><Link href="/x">Подпись</Link></MegaMenuLink>`.
+ссылку элементом роутера: `<MegaMenuLink asChild><Link href="/x">Подпись</Link></MegaMenuLink>`. Прежнее имя
+`current` работает до 5.0 и помечено `@deprecated`: текущий пункт навигации в ките называется `active`.
 
-## Наведение и Витрина
+## Наведение и Полка
 
-Наведение мышью на Категорию открывает её Витрину сразу, без задержки. Подсвечена ровно та Категория, чья
-Витрина открыта: подсветка идёт по `aria-expanded`, а не по `:hover`. Наведение на Категорию без Витрины
+Наведение мышью на Категорию открывает её Полку сразу, без задержки. Подсвечена ровно та Категория, чья
+Полка открыта: подсветка идёт по `aria-expanded`, а не по `:hover`. Наведение на Категорию без Полки
 закрывает открытую — с той же оговоркой про Прицел, что ниже.
 
-Витрина закрывается, когда курсор ушёл и со Столбца, и с Витрины, через 150 мс: короткий выход за край не
+Полка закрывается, когда курсор ушёл и со Столбца, и с Полки, через 150 мс: короткий выход за край не
 сбрасывает каталог. Закрывают её и нажатие указателем вне каталога, и уход фокуса со страницы каталога.
 
-Содержимое Витрины монтируется только у открытой Категории: каталог из сотни ссылок и картинок не грузит всё
+Содержимое Полки монтируется только у открытой Категории: каталог из сотни ссылок и картинок не грузит всё
 разом. Сам регион есть всегда, скрытым: на него указывает `aria-controls` кнопки.
 
-Витрина — потомок своей Категории в DOM, а не портал. Поэтому порядок Tab идёт «Категория → её ссылки → дальше
-по странице», и Витрина встаёт вплотную к Столбцу без расчёта позиции. Предок с `overflow: hidden` её обрежет:
+Полка — потомок своей Категории в DOM, а не портал. Поэтому порядок Tab идёт «Категория → её ссылки → дальше
+по странице», и Полка встаёт вплотную к Столбцу без расчёта позиции. Предок с `overflow: hidden` её обрежет:
 ставьте каталог туда, где рядом есть место.
 
-Витрина стоит со стороны конца строки — справа, а при письме справа налево слева. Если там не хватает места, а с
+Полка стоит со стороны конца строки — справа, а при письме справа налево слева. Если там не хватает места, а с
 другой стороны хватает, она переходит на другую сторону; сторону кит меряет заранее и при смене размера окна,
-поэтому стрелка «к Витрине» сразу смотрит туда, где Витрина окажется.
+поэтому стрелка «к Полке» сразу смотрит туда, где Полка окажется.
 
 ## Касание и узкий экран
 
 Касание наведения не знает, поэтому Категорию открывает само касание (`click`), без Прицела. Указатель с
-`pointerType` «touch» или «pen» не открывает Категорию наведением и не закрывает Витрину уходом: перо
+`pointerType` «touch» или «pen» не открывает Категорию наведением и не закрывает Полку уходом: перо
 ведёт себя как палец. Повторное касание открытой Категории её не закрывает и никуда не ведёт: закрывает
-Витрину касание вне каталога или Escape.
+Полку касание вне каталога или Escape.
 
 Мышь ведёт себя, как раньше: наведение, Прицел и закрытие через 150 мс остаются, пока экран широкий.
 
-На узком экране — меньше 640px, граница та же, что у подменю `Menu` и подменю Редактора, — Витрине некуда
+На узком экране — меньше 640px, граница та же, что у подменю `Menu` и подменю Редактора, — Полке некуда
 встать сбоку: справа от Столбца её обрезал бы край окна. Поэтому каталог идёт «спуском»:
 
 - Столбец занимает всю ширину, подписи Категорий переносятся, а не обрезаются.
-- Открытая Категория (касанием, щелчком, Enter или Пробелом) заменяет Столбец своей Витриной. Витрина
+- Открытая Категория (касанием, щелчком, Enter или Пробелом) заменяет Столбец своей Полкой. Полка
   начинается строкой «Назад» с названием Категории; если у Категории есть своя ссылка, название показывает она,
   строкой ниже, а не строка «Назад». Ниже — колонки ссылок, одна под другой.
 - «Назад» возвращает Столбец и ставит фокус на Категорию, из которой человек пришёл. Escape внутри
-  Витрины работает как «Назад».
+  Полки работает как «Назад».
 - Фокус при спуске переходит на «Назад»: кнопка Категории скрыта вместе со Столбцом, и фокус на ней
-  пропал бы. Стрелка в сторону Столбца в Витрине на узком экране ничего не делает: Столбца рядом нет.
+  пропал бы. Стрелка в сторону Столбца в Полке на узком экране ничего не делает: Столбца рядом нет.
 - Прицела на узком экране нет, наведение мышью Категорию не открывает, а уход мыши не отменяет спуск:
   заменять Столбец под курсором значило бы вырывать его из-под руки.
 - Разметка остаётся по шаблону disclosure: кнопка Категории сохраняет `aria-expanded` и `aria-controls`
@@ -123,25 +137,25 @@ import { MegaMenu, MegaMenuCategory, MegaMenuGroup, MegaMenuLink } from "@olddev
 
 Ширину кит читает через `matchMedia`, а не через CSS: от неё зависит состав разметки (прячется Столбец), а
 не только вид. До гидратации и на сервере хук возвращает «широкий» (ADR-0018): сервер ширины не знает, и
-разметка с него всегда обычная. На телефоне после гидратации Витрина, открытая `defaultValue`, один раз
+разметка с него всегда обычная. На телефоне после гидратации Полка, открытая `defaultValue`, один раз
 перерисовывается спуском. На телефоне `nav` занимает всю ширину классом `max-sm:w-full`; `w-*` из `className` действует на
 широком экране.
 
 ## Прицел
 
-Курсор идёт от Категории к её Витрине наискосок и по пути задевает соседние Категории. Если бы наведение
-открывало их сразу, Витрина менялась бы у человека под рукой, и до ссылки было бы не дотянуться. Прицел смотрит,
-куда движется курсор: пока он идёт в сторону открытой Витрины, соседняя Категория наведение не перехватывает.
+Курсор идёт от Категории к её Полке наискосок и по пути задевает соседние Категории. Если бы наведение
+открывало их сразу, Полка менялась бы у человека под рукой, и до ссылки было бы не дотянуться. Прицел смотрит,
+куда движется курсор: пока он идёт в сторону открытой Полки, соседняя Категория наведение не перехватывает.
 
 - Направление последнего шага курсора сравнивается с сектором от его прежней точки к двум углам ближнего края
-  Витрины — это и есть треугольник Каменса из раздела «Откуда это». Шаг в сектор — курсор целится.
+  Полки — это и есть треугольник Каменса из раздела «Откуда это». Шаг в сектор — курсор целится.
 - Одно движение мимо прощается, два подряд — нет: тогда открывается Категория под курсором.
 - Курсор остановился на 300 мс — открывается Категория под ним, даже если он целился. Меню не «залипает».
-- Курсор дошёл до Витрины — отложенная смена отменяется.
+- Курсор дошёл до Полки — отложенная смена отменяется.
 - Щелчок по Категории открывает её сразу, мимо Прицела. Клавиатура Прицела не знает вовсе.
 - Только мышь, и только на широком экране: касание и перо открывают Категорию сразу, а на узком экране
   Прицела нет вовсе.
-- Первое наведение, пока Витрины нет, открывает Категорию без всякой задержки: целиться ещё не во что.
+- Первое наведение, пока Полки нет, открывает Категорию без всякой задержки: целиться ещё не во что.
 
 Модель та же, что у подменю react-aria (`Menu` с `SubmenuTrigger`), чтобы два меню кита вели себя одинаково.
 Отличий два. Смена Категории откладывается, а не гасится `pointer-events: none` на Столбце: иначе пропала бы
@@ -194,15 +208,20 @@ _Анимация из [поста Бена Каменса](https://bjk5.com/pos
 ## Клавиатура и имена
 
 - Столбец — одна остановка Tab. Стрелки вверх и вниз, Home и End ходят по Категориям; выключенные
-  пропускаются. Вернувшись Tab'ом, пользователь попадает на ту Категорию, где был.
-- Enter, Пробел и стрелка в сторону Витрины открывают её и ставят фокус на первую ссылку. У Категории-ссылки
+  пропускаются. Вернувшись Tab'ом, пользователь попадает на ту Категорию, где был; в первый раз — на открытую,
+  иначе на текущий раздел (`active`), иначе на первую.
+- Буква на Категории переводит фокус на следующую Категорию, чья подпись с неё начинается, по кругу; та же буква
+  ещё раз — на следующую. Буквы, набранные подряд, ищут начало подписи, пауза в полсекунды сбрасывает набранное.
+  Пробел посреди набора — часть подписи («Home and garden»), а не открытие Категории.
+  Буква с Ctrl, Cmd или Alt — сочетание клавиш, каталог её не трогает.
+- Enter, Пробел и стрелка в сторону Полки открывают её и ставят фокус на первую ссылку. У Категории-ссылки
   Enter — переход.
-- Внутри Витрины работает обычный Tab. Стрелка в сторону Столбца возвращает фокус на Категорию, Escape — тоже,
-  и закрывает Витрину. Tab за последней ссылкой уходит дальше по странице и закрывает Витрину.
-- Пока Витрина открыта, она следует за фокусом стрелок, как следует за наведением.
-- Стрелка «к Витрине» — та, что смотрит туда, где Витрина стоит: при письме справа налево и у края экрана
+- Внутри Полки работает обычный Tab. Стрелка в сторону Столбца возвращает фокус на Категорию, Escape — тоже,
+  и закрывает Полку. Tab за последней ссылкой уходит дальше по странице и закрывает Полку.
+- Пока Полка открыта, она следует за фокусом стрелок и букв, как следует за наведением.
+- Стрелка «к Полке» — та, что смотрит туда, где Полка стоит: при письме справа налево и у края экрана
   стрелки меняются местами.
-- Скринридер слышит навигацию с именем из `aria-label`, Категории — кнопками «развёрнуто / свёрнуто», Витрину
+- Скринридер слышит навигацию с именем из `aria-label`, Категории — кнопками «развёрнуто / свёрнуто», Полку
   — регионом с именем Категории, колонку — списком с именем заголовка.
 
 ## Выпадающий вид
@@ -242,10 +261,10 @@ import { ListIcon } from "@olddevs/ui/icons";
 - **Открытие.** Щелчок, Enter, Пробел и стрелка вниз на кнопке. Наведение каталог не открывает: он не должен
   выпрыгивать от случайного движения мыши.
 - **Фокус.** При открытии фокус встаёт на первую доступную Категорию (если одна из них уже открыта через `value` или
-  `defaultValue` — на неё), Витрина закрыта до выбора. Дальше Столбец и Витрина работают как во встроенном виде.
+  `defaultValue` — на неё), Полка закрыта до выбора. Дальше Столбец и Полка работают как во встроенном виде.
 - **Закрытие.** Escape на Категории, нажатие вне каталога, повторный щелчок по кнопке, переход по любой ссылке
   (Категория, заголовок колонки, `MegaMenuLink`, в том числе ссылки роутера) и Tab за последним элементом.
-  Первый Escape внутри Витрины закрывает только Витрину и возвращает фокус на её Категорию; оверлей закрывает
+  Первый Escape внутри Полки закрывает только Полку и возвращает фокус на её Категорию; оверлей закрывает
   следующий.
 - **Возврат фокуса.** На кнопку фокус возвращается при Escape и при повторном щелчке. После Tab за последним
   элементом фокус идёт дальше по странице, за кнопкой; Shift+Tab перед первым элементом возвращает на кнопку. После
@@ -253,10 +272,14 @@ import { ListIcon } from "@olddevs/ui/icons";
 - **Скринридер.** Кнопка — раскрыватель с `aria-expanded` и `aria-controls`, без `aria-haspopup`: оверлей — не
   меню и не диалог, а та же навигация с ссылками. Роли `dialog` у оверлея нет.
 - **Слои.** Оверлей лежит на слое `popover`: выше затемнения открытого `Dialog`, ниже подтверждения. Внутри окна
-  первый Escape закрывает каталог, следующий — окно. Если фокус в открытой Витрине, самый первый Escape закрывает
+  первый Escape закрывает каталог, следующий — окно. Если фокус в открытой Полке, самый первый Escape закрывает
   только её и возвращает фокус на Категорию.
-- **Высота.** Оверлей не выше видимой области от кнопки до края окна. Столбец и Витрина прокручиваются каждый
-  внутри себя (`overscroll-contain`), а не оверлей целиком: иначе рамка оверлея обрезала бы Витрину, которая
+- **Узкий экран.** Уже 640px оверлей занимает всю ширину окна за вычетом отступов по 8px с краёв, а не сжимается по
+  самой длинной подписи: подписи переносятся, длинная не выталкивает каталог за край, и ширина не меняется при
+  спуске в Категорию. Спуск, «Назад» и Escape работают внутри оверлея так же, как во встроенном виде: первый
+  Escape в Полке возвращает Столбец, следующий закрывает каталог.
+- **Высота.** Оверлей не выше видимой области от кнопки до края окна. Столбец и Полка прокручиваются каждый
+  внутри себя (`overscroll-contain`), а не оверлей целиком: иначе рамка оверлея обрезала бы Полку, которая
   стоит рядом со Столбцом. На iOS высота ограничена `min(24rem, 60dvh)`, как у панели `Menu`.
 - **Появление.** Плавное, по шкале движения кита; при `prefers-reduced-motion` без анимации.
 - **Сервер.** На сервере рисуется закрытая кнопка; оверлей монтируется в портале после открытия.
@@ -265,14 +288,16 @@ import { ListIcon } from "@olddevs/ui/icons";
 
 - Реализация: `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` — Прицел на подменённой геометрии и поддельном
+  Полки, закрытие с задержкой, roving tabindex, Enter, Escape и стрелки, Tab за последней ссылкой,
+  Категория-ссылка, выключенная Категория, `active` и алиас `current`, `asChild` и `link` (у Категории и у
+  колонки), фрагменты в колонке, текущий раздел и остановка Tab, поиск по первой букве, Категории в своих
+  компонентах, управляемое значение, нажатие вне каталога, рендер на сервере; `tests/mega-menu-aim.test.tsx` — Прицел на подменённой геометрии и поддельном
   времени, переворот у края; `tests/mega-menu-touch.test.tsx` — касание и перо, подмена `matchMedia`, спуск
-  вместо Столбца, «Назад» и фокус, Escape, подписи из каталога сообщений, рендер на сервере; браузерный тест `tests-visual/mega-menu.spec.ts` — настоящая мышь наискосок и вниз
-  по Столбцу.
+  вместо Столбца, «Назад» и фокус, Escape, подписи из каталога сообщений, спуск у Категорий в своих
+  компонентах, рендер на сервере; браузерный тест `tests-visual/mega-menu.spec.ts` — настоящая мышь наискосок и
+  вниз по Столбцу, ширина выпадающего вида на телефоне.
 - Выпадающий вид: `tests/mega-menu-dropdown.test.tsx` — открытие щелчком и клавишами с фокусом на первой
-  Категории, все пути закрытия и возврат фокуса, Escape в Витрине, `open` / `defaultOpen` / `onOpenChange`, слой
-  `popover`, порядок Escape внутри `Dialog`, рендер на сервере.
+  Категории, все пути закрытия и возврат фокуса, Escape в Полке, `open` / `defaultOpen` / `onOpenChange`, слой
+  `popover`, порядок Escape внутри `Dialog`, спуск на узком экране, рендер на сервере.
 - История: `src/components/navigation/MegaMenu.stories.tsx` — в том числе `DropdownInTopBar`, мегаменю в шапке; на ширине
-  телефона — `PhoneColumn` и `PhoneDrillDown`.
+  телефона — `PhoneColumn`, `PhoneDrillDown`, `PhoneDropdown` и `PhoneDropdownDrillDown`.

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: 473c4ffa0e0a
+sourceHash: e6bb9a14d118
 ---
 
 # Menu
@@ -57,8 +57,11 @@ 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 for the root menu `bottom start`; also
-`bottom end`, `top start`, `top end`, `right top` and `left top`; the submenu
-default is described below).
+`bottom end`, `top start`, `top end`, `end top`, `start top`, `right top` and
+`left top`; the submenu default is described below). `end top` and `start top`
+open beside the panel at the end or the start of the line, so they swap sides in
+right-to-left writing; `right top` and `left top` don't depend on the writing
+direction.
 
 `MenuItem` accepts the `AriaMenuItem` props, `icon`, `shortcut`, `tone`,
 `disabled` and `className`; pass the action in `onAction`. `MenuSection` accepts
@@ -72,7 +75,8 @@ the right, react-aria flips it to the left. In a right-to-left layout everything
 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
+phones included; to pick the side yourself without breaking right-to-left
+writing, use `end top` or `start top`. 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

package/docs/components/overlays/menu.md

@@ -54,8 +54,10 @@ 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`; умолчание подменю — ниже).
+меню `bottom start`; ещё `bottom end`, `top start`, `top end`, `end top`,
+`start top`, `right top`, `left top`; умолчание подменю — ниже). `end top` и
+`start top` — сбоку по концу и по началу строки: при письме справа налево они
+меняются местами. `right top` и `left top` от направления письма не зависят.
 
 `MenuItem` принимает props `AriaMenuItem`, `icon`, `shortcut`, `tone`, `disabled`
 и `className`; действие передавайте в `onAction`. `MenuSection` принимает
@@ -69,7 +71,8 @@ react-aria переворачивает подменю влево. При пис
 подменю раскрывается слева от пункта. На узком экране (до 639px шириной) места
 сбоку нет ни справа, ни слева, и подменю встаёт под своим пунктом, поверх
 родительского меню. Явный `placement` у вложенного `Menu` побеждает умолчание, в
-том числе на телефоне. Корневое меню раскрывается как прежде — `bottom start`.
+том числе на телефоне; чтобы задать сторону самому и не сломать письмо справа
+налево, берите `end top` или `start top`. Корневое меню раскрывается как прежде — `bottom start`.
 То же правило у подменю Редактора.
 
 Движение курсора к подменю по диагонали его не закрывает и не переключает на