@olddevs/ui 4.1.1 → 4.2.0

package/src/components/navigation/useMenuAim.ts

@@ -0,0 +1,202 @@
+"use client";
+
+import { useCallback, useEffect, useRef, type RefObject } from "react";
+
+/*
+  ПРИЦЕЛ МЕГАМЕНЮ — приём Amazon, разобранный Беном Каменсом в 2013 году.
+
+  Курсор идёт от Категории к её Витрине наискосок и по пути задевает соседние
+  Категории. Наивное «наведение открывает» сменило бы Витрину у человека под
+  рукой. Прицел смотрит, КУДА движется курсор: пока он идёт в сторону открытой
+  Витрины, соседняя Категория наведение не перехватывает.
+
+  Модель — как у `useSafelyMouseToSubmenu` в react-aria, чтобы подменю `Menu` и
+  мегаменю вели себя одинаково: направление последнего шага сравнивается с
+  сектором от предыдущей точки к двум углам ближнего края Витрины; смена
+  направления прощается; обработка прорежена до кадра; только мышь.
+
+  Два осознанных расхождения с react-aria:
+
+  1. Механизм — ОТЛОЖЕННАЯ СМЕНА Категории, а не `pointer-events: none` на
+     Столбце. Отключённые события гасят подсветку под курсором и съедают щелчок
+     по соседней Категории, а щелчок должен открывать сразу.
+  2. Время сброса — 300 мс (значение Каменса), а не 1000 мс react-aria. Его
+     подменю узкое и короткое; Столбец каталога листают, и секунда ожидания на
+     каждой остановке ощущается как залипание.
+*/
+
+/** Курсор стоит дольше — Категория под ним открывается, даже если он «целился». */
+export const AIM_SETTLE_MS = 300;
+
+/** Прореживание: один шаг на кадр. Чаще направление шумит пиксельной дрожью. */
+const THROTTLE_MS = 16;
+
+/**
+ * Сколько шагов «не туда» подряд прощается. Счётчик растёт на шаг к Витрине и
+ * падает на шаг мимо; целится курсор, пока счётчик выше нуля. Отсюда: одно
+ * случайное движение вбок прицел не сбрасывает, два подряд — сбрасывают.
+ */
+const ALLOWED_INVALID_MOVES = 2;
+
+/**
+ * Запас сектора по вертикали, пиксели. Без него курсор, идущий точно в угол
+ * Витрины, выпадал бы из сектора на дрожании руки.
+ */
+const SECTOR_PADDING = 24;
+
+interface Point {
+  x: number;
+  y: number;
+}
+
+/**
+ * Идёт ли шаг `from → to` к Витрине: направление шага лежит внутри сектора от
+ * `from` к двум углам её ближнего края.
+ *
+ * Векторное произведение, а не `atan2`: тот же сектор без разрыва угла на ±π.
+ * Ось y экрана направлена вниз, отсюда знаки.
+ */
+export function isMovingToward(from: Point, to: Point, rect: DOMRect, side: "left" | "right") {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  if (dx === 0 && dy === 0) return false;
+  const edge = side === "right" ? rect.left : rect.right;
+  // Курсор уже за ближним краем — он в Витрине, а не на пути к ней.
+  if (side === "right" ? from.x >= edge : from.x <= edge) return false;
+  // Шаг от Витрины по горизонтали не может к ней вести.
+  if (side === "right" ? dx <= 0 : dx >= 0) return false;
+  const top = { x: edge - from.x, y: rect.top - SECTOR_PADDING - from.y };
+  const bottom = { x: edge - from.x, y: rect.bottom + SECTOR_PADDING - from.y };
+  const cross = (a: Point, b: Point) => a.x * b.y - a.y * b.x;
+  const step = { x: dx, y: dy };
+  // Справа: шаг «ниже» луча к верхнему углу и «выше» луча к нижнему. Слева
+  // ориентация лучей зеркальна, и знаки меняются местами.
+  return side === "right"
+    ? cross(top, step) >= 0 && cross(step, bottom) >= 0
+    : cross(top, step) <= 0 && cross(step, bottom) <= 0;
+}
+
+const NONE = Symbol("none");
+
+interface MenuAimOptions {
+  /** Открытая Категория; `null` — Витрины нет, и целиться не во что. */
+  value: string | null;
+  /** Открытая сейчас Витрина: её прямоугольник — цель. */
+  showcaseRef: RefObject<HTMLElement | null>;
+  /** Сменить Категорию (или закрыть Витрину — `null`). */
+  commit: (next: string | null) => void;
+}
+
+/**
+ * Прицел: решает, сменить Категорию под курсором сейчас или отложить.
+ *
+ * `request` зовётся из наведения на строку Столбца. Если Витрины нет или
+ * курсор не целится — смена сразу. Если целится — смена откладывается: курсор
+ * перестал целиться или стоит `AIM_SETTLE_MS` — открывается то, что под ним
+ * сейчас; дошёл до Витрины — смена отменяется.
+ *
+ * Прямоугольник Витрины берётся заново на каждом шаге, а не кешируется:
+ * прокрутка страницы и смена размера окна не оставляют его устаревшим, а цена
+ * — одно чтение раскладки на кадр, и только пока Витрина открыта.
+ */
+export function useMenuAim({ value, showcaseRef, commit }: MenuAimOptions) {
+  const previous = useRef<Point | null>(null);
+  const lastStep = useRef(0);
+  const aim = useRef(0);
+  const pending = useRef<string | null | typeof NONE>(NONE);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const commitRef = useRef(commit);
+  commitRef.current = commit;
+
+  const clearTimer = () => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = null;
+  };
+
+  const flush = useCallback(() => {
+    clearTimer();
+    const next = pending.current;
+    pending.current = NONE;
+    if (next !== NONE) commitRef.current(next);
+  }, []);
+
+  const settleLater = useCallback(() => {
+    clearTimer();
+    timer.current = setTimeout(flush, AIM_SETTLE_MS);
+  }, [flush]);
+
+  // Новая Витрина — новая цель: прежний счёт к ней отношения не имеет.
+  useEffect(() => {
+    aim.current = 0;
+    previous.current = null;
+    pending.current = NONE;
+    clearTimer();
+  }, [value]);
+
+  useEffect(() => clearTimer, []);
+
+  useEffect(() => {
+    if (value === null) return;
+    const onPointerMove = (event: PointerEvent) => {
+      if (event.pointerType === "touch" || event.pointerType === "pen") return;
+      const now = Date.now();
+      if (now - lastStep.current < THROTTLE_MS) return;
+      lastStep.current = now;
+      const point = { x: event.clientX, y: event.clientY };
+      const showcase = showcaseRef.current;
+      const from = previous.current;
+      previous.current = point;
+      if (!showcase || !from) return;
+
+      // Курсор дошёл до Витрины — отложенная смена больше не нужна.
+      if (event.target instanceof Node && showcase.contains(event.target)) {
+        pending.current = NONE;
+        clearTimer();
+        return;
+      }
+
+      const rect = showcase.getBoundingClientRect();
+      const side = rect.left >= from.x ? "right" : "left";
+      aim.current = isMovingToward(from, point, rect, side)
+        ? Math.min(aim.current + 1, ALLOWED_INVALID_MOVES)
+        : Math.max(aim.current - 1, 0);
+
+      if (pending.current === NONE) return;
+      // Перестал целиться — открывается то, над чем он сейчас; иначе ждём
+      // остановки заново: каждый шаг откладывает срок.
+      if (aim.current === 0) flush();
+      else settleLater();
+    };
+    document.addEventListener("pointermove", onPointerMove);
+    return () => document.removeEventListener("pointermove", onPointerMove);
+  }, [value, showcaseRef, flush, settleLater]);
+
+  /** Курсор наведён на строку Столбца: открыть её (`null` — закрыть Витрину). */
+  const request = useCallback(
+    (next: string | null) => {
+      if (next === value) {
+        // Вернулся на открытую Категорию — отложенная смена отменяется.
+        pending.current = NONE;
+        clearTimer();
+        return;
+      }
+      if (value === null || aim.current === 0) {
+        pending.current = NONE;
+        clearTimer();
+        commitRef.current(next);
+        return;
+      }
+      pending.current = next;
+      settleLater();
+    },
+    [value, settleLater]
+  );
+
+  /** Отменить отложенную смену: щелчок, клавиатура, уход из меню решают сами. */
+  const cancel = useCallback(() => {
+    pending.current = NONE;
+    clearTimer();
+  }, []);
+
+  return { request, cancel };
+}

package/src/components/overlays/Menu.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { forwardRef, type ReactNode } from "react";
+import { forwardRef, useContext, type ReactNode } from "react";
 import {
   Button as AriaButton,
   Menu as AriaMenu,
@@ -8,6 +8,7 @@ import {
   MenuSection as AriaMenuSection,
   Header,
   Popover,
+  PopoverContext,
   Separator,
   type MenuItemProps as AriaMenuItemProps,
   type MenuProps as AriaMenuProps,
@@ -15,6 +16,7 @@ import {
 } from "react-aria-components";
 import { CheckIcon, ChevronRightIcon } from "../../icons.js";
 import { buttonClasses, type ButtonLookOptions } from "../../lib/button.js";
+import { useSubmenuPlacement } from "../../hooks/useSubmenuPlacement.js";
 import { cn } from "../../lib/cn.js";
 import {
   MENU_ITEM_CLASS,
@@ -83,7 +85,12 @@ export const MenuButton = forwardRef<HTMLButtonElement, MenuButtonProps>(functio
 export interface MenuProps<T extends object = object> extends AriaMenuProps<T> {
   /** Отступ панели от кнопки, в пикселях. */
   offset?: number;
-  /** Сторона, с которой панель раскрывается. */
+  /**
+   * Сторона, с которой панель раскрывается. Корневое меню по умолчанию — под
+   * кнопкой слева (`bottom start`); вложенное, внутри `SubmenuTrigger`, —
+   * сбоку от своего пункта, а на узком экране под ним. Явное значение
+   * побеждает оба умолчания.
+   */
   placement?: "bottom start" | "bottom end" | "top start" | "top end" | "right top" | "left top";
 }
 
@@ -115,6 +122,19 @@ export interface MenuItemProps extends Omit<AriaMenuItemProps, "children" | "cla
  * меню руками. Это же делает работоспособным `SubmenuTrigger`: он ждёт вторым
  * ребёнком именно попоувер.
  *
+ * ПОДМЕНЮ раскрывается сбоку от своего пункта, и это умолчание нужно
+ * выставлять самим. `SubmenuTrigger` отдаёт вложенному поповеру место
+ * `end top` через контекст, но явный проп поповера важнее контекста, а корневое
+ * умолчание кита `bottom start` — как раз явный проп: вложенное меню без
+ * особого случая раскрывалось бы под пунктом. Поэтому `Menu` узнаёт подменю по
+ * контексту (`trigger: "SubmenuTrigger"`, публичное поле `PopoverContext`) и
+ * спрашивает общий хук `useSubmenuPlacement` — тот же, что в Редакторе: на
+ * телефоне подменю встаёт под пунктом, на широком экране кит своего места не
+ * передаёт, и действует `end top` react-aria — сбоку, с учётом направления
+ * письма. Переворот у края экрана
+ * (`shouldFlip`) и «Прицел» — движение курсора к подменю по диагонали не
+ * закрывает его — остаются у react-aria, кит их не трогает.
+ *
  * ПЕРЕКЛЮЧАТЕЛИ — через выбор на разделе, а не через `checked` у пункта:
  *
  *     <MenuSection label="Вид" selectionMode="multiple"
@@ -128,11 +148,34 @@ export interface MenuItemProps extends Omit<AriaMenuItemProps, "children" | "cla
  * чужую работу и расходиться с ней при первом же обновлении.
  */
 export const Menu = forwardRef<HTMLDivElement, MenuProps>(function Menu(
-  { offset = 6, placement = "bottom start", className, ...rest },
+  { offset = 6, placement, className, ...rest },
   ref
 ) {
+  const popoverContext = useContext(PopoverContext);
+  // Контекст бывает пустым, со слотами или с самими пропами поповера; «подменю»
+  // говорит только последнее.
+  const isSubmenu =
+    popoverContext != null &&
+    "trigger" in popoverContext &&
+    popoverContext.trigger === "SubmenuTrigger";
+  const submenuPlacement = useSubmenuPlacement();
+  // Широкий экран — место не передаётся вовсе: тогда действует `end top` из
+  // контекста `SubmenuTrigger`. Оно логическое, и при письме справа налево
+  // подменю раскрывается слева, а `right top` хука уводило бы его вправо.
+  const resolvedPlacement =
+    placement ??
+    (isSubmenu
+      ? submenuPlacement === "bottom start"
+        ? submenuPlacement
+        : undefined
+      : "bottom start");
+
   return (
-    <Popover offset={offset} placement={placement} className={cn(MENU_PANEL_CLASS, className)}>
+    <Popover
+      offset={offset}
+      placement={resolvedPlacement}
+      className={cn(MENU_PANEL_CLASS, className)}
+    >
       {/*
         `data-disable-focus-ring` — механизм пакета, тот же, что у `TextControl`.
         Глобальное правило `:focus-visible` в styles.css рисует контур вокруг

package/src/editor/features/table/TableMenuButton.tsx

@@ -56,7 +56,7 @@ import {
   type TableAction,
 } from "./tableActions.js";
 import { TableSizeGrid } from "./TableSizeGrid.js";
-import { useSubmenuPlacement } from "../../hooks/useSubmenuPlacement.js";
+import { useSubmenuPlacement } from "../../../hooks/useSubmenuPlacement.js";
 import { GLASS_MENU_CLASS } from "../../styles/glass.js";
 
 export interface TableMenuButtonProps {

package/src/editor/ui/BlockHandle.tsx

@@ -42,7 +42,7 @@ import { ariaShortcut, findShortcutKeys, isApple, shortcutLabel } from "../core/
 import { blockActionsOf, blockActionVisible, type ToolList } from "../core/toolDescriptor.js";
 import { WRAPPER_NODE } from "../features/wrapper/wrapper.js";
 import { EDITOR_WRAPPER_TONES, wrapperToneFrom } from "../features/wrapper/wrapperTones.js";
-import { useSubmenuPlacement } from "../hooks/useSubmenuPlacement.js";
+import { useSubmenuPlacement } from "../../hooks/useSubmenuPlacement.js";
 import { GLASS_MENU_CLASS } from "../styles/glass.js";
 
 /** Размер ручки и зазор до текста, px: ручка `h-6 w-5` стоит в левом поле Документа. */

package/src/editor/ui/FormatMenus.tsx

@@ -45,7 +45,7 @@ import { DEFAULT_ALIGNMENT, EDITOR_ALIGNMENTS, type EditorAlignment } from "../s
 import { findShortcutKeys } from "../core/shortcuts.js";
 import type { ToolList } from "../core/toolDescriptor.js";
 import type { Tool } from "../core/tools.js";
-import { useSubmenuPlacement } from "../hooks/useSubmenuPlacement.js";
+import { useSubmenuPlacement } from "../../hooks/useSubmenuPlacement.js";
 import { GLASS_MENU_CLASS } from "../styles/glass.js";
 
 type EditorMessages = UiMessages["editor"];

package/src/{editor/hooks → hooks}/useSubmenuPlacement.ts

@@ -1,24 +1,25 @@
 "use client";
 
-import { useSyncExternalStore } from "react";
+import { useMediaQuery } from "./useMediaQuery.js";
 
 /** Уже `sm` (640): на такой ширине подменю сбоку от пункта не помещается. */
-const QUERY = "(max-width: 639px)";
+const NARROW_QUERY = "(max-width: 639px)";
 
-function subscribe(onChange: () => void): () => void {
-  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return () => {};
-  const list = window.matchMedia(QUERY);
-  list.addEventListener("change", onChange);
-  return () => list.removeEventListener("change", onChange);
-}
-
-function snapshot(): boolean {
-  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false;
-  return window.matchMedia(QUERY).matches;
+/**
+ * Узкий ли экран по правилу кита — граница одна на подменю и мегаменю.
+ *
+ * Внутренний хук, как и `useSubmenuPlacement`. До гидратации и без `matchMedia`
+ * — `false`, то есть широкий: серверной ширины нет, а угадывать значило бы
+ * получить расхождение разметки (ADR-0018, см. `useMediaQuery`).
+ */
+export function useNarrowScreen(): boolean {
+  return useMediaQuery(NARROW_QUERY);
 }
 
 /**
- * Где открыть подменю Редактора: сбоку от пункта или под ним.
+ * Где открыть подменю: сбоку от пункта или под ним.
+ *
+ * Правило одно на весь кит: его применяет вложенный `Menu` и подменю Редактора.
  *
  * Сбоку — привычно на десктопе. На телефоне места нет ни справа, ни слева:
  * меню само занимает середину экрана, и react-aria, перевернув подменю на
@@ -33,8 +34,10 @@ function snapshot(): boolean {
  * JS, а не CSS: место подменю — проп поповера, а не класс. Подписка — экран
  * поворачивают на лету. На сервере и без `matchMedia` — сбоку: подменю
  * открывается только в браузере, по действию пользователя.
+ *
+ * Внутренний хук: наружу не экспортируется. Потребитель кита решает за себя
+ * проп `placement` у `Menu`, а умолчание для вложенного меню уже здесь.
  */
 export function useSubmenuPlacement(): "bottom start" | "right top" {
-  const narrow = useSyncExternalStore(subscribe, snapshot, () => false);
-  return narrow ? "bottom start" : "right top";
+  return useNarrowScreen() ? "bottom start" : "right top";
 }

package/src/i18n/defaults.ts

@@ -347,6 +347,10 @@ export const DEFAULT_MESSAGES: UiMessages = {
     slide: ({ index, total }) => `${index} of ${total}`,
   },
 
+  megaMenu: {
+    back: "Back",
+  },
+
   shortcutsHelp: {
     title: "Keyboard shortcuts",
     list: "Shortcuts",

package/src/i18n/messages.ts

@@ -591,6 +591,15 @@ export interface UiMessages {
     slide: (vars: { index: number; total: number }) => string;
   };
 
+  megaMenu: {
+    /**
+     * Строка возврата на узком экране: открытая Категория заменяет Столбец, и
+     * эта кнопка возвращает его. Имя кнопки — одно слово без названия
+     * Категории: название стоит рядом текстом, а регион им уже подписан.
+     */
+    back: string;
+  };
+
   shortcutsHelp: {
     /** Заголовок окна по умолчанию. Он же доступное имя диалога. */
     title: string;

package/src/index.ts

@@ -428,6 +428,23 @@ export type { PaginationProps } from "./components/navigation/Pagination.js";
 export { Stepper } from "./components/navigation/Stepper.js";
 export type { StepperProps, Step } from "./components/navigation/Stepper.js";
 
+export {
+  MegaMenu,
+  MegaMenuButton,
+  MegaMenuCategory,
+  MegaMenuGroup,
+  MegaMenuLink,
+  MegaMenuTrigger,
+} from "./components/navigation/MegaMenu.js";
+export type {
+  MegaMenuProps,
+  MegaMenuButtonProps,
+  MegaMenuCategoryProps,
+  MegaMenuGroupProps,
+  MegaMenuLinkProps,
+  MegaMenuTriggerProps,
+} from "./components/navigation/MegaMenu.js";
+
 export { ToggleGroup } from "./components/actions/ToggleGroup.js";
 export type { ToggleGroupProps, ToggleGroupOption } from "./components/actions/ToggleGroup.js";
 

package/src/locales/ru.ts

@@ -376,6 +376,10 @@ export const messages: UiMessages = {
     slide: ({ index, total }) => `${index} из ${total}`,
   },
 
+  megaMenu: {
+    back: "Назад",
+  },
+
   shortcutsHelp: {
     title: "Горячие клавиши",
     list: "Сочетания клавиш",

package/dist/editor/hooks/useSubmenuPlacement.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useSubmenuPlacement.d.ts","sourceRoot":"","sources":["../../../src/editor/hooks/useSubmenuPlacement.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,GAAG,WAAW,CAGlE"}

package/dist/editor/hooks/useSubmenuPlacement.js

@@ -1,20 +0,0 @@
-"use client";
-import { useSyncExternalStore } from "react";
-const QUERY = "(max-width: 639px)";
-function subscribe(onChange) {
-    if (typeof window === "undefined" || typeof window.matchMedia !== "function")
-        return () => { };
-    const list = window.matchMedia(QUERY);
-    list.addEventListener("change", onChange);
-    return () => list.removeEventListener("change", onChange);
-}
-function snapshot() {
-    if (typeof window === "undefined" || typeof window.matchMedia !== "function")
-        return false;
-    return window.matchMedia(QUERY).matches;
-}
-export function useSubmenuPlacement() {
-    const narrow = useSyncExternalStore(subscribe, snapshot, () => false);
-    return narrow ? "bottom start" : "right top";
-}
-//# sourceMappingURL=useSubmenuPlacement.js.map

package/dist/editor/hooks/useSubmenuPlacement.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"useSubmenuPlacement.js","sourceRoot":"","sources":["../../../src/editor/hooks/useSubmenuPlacement.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAG7C,MAAM,KAAK,GAAG,oBAAoB,CAAC;AAEnC,SAAS,SAAS,CAAC,QAAoB;IACrC,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,UAAU;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAC9F,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IACtC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC1C,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,QAAQ;IACf,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAC3F,OAAO,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC;AAC1C,CAAC;AAmBD,MAAM,UAAU,mBAAmB;IACjC,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;IACtE,OAAO,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,WAAW,CAAC;AAC/C,CAAC"}