@olddevs/ui 4.2.2 → 4.4.0

package/src/components/navigation/useMenuAim.ts

@@ -5,14 +5,14 @@ import { useCallback, useEffect, useRef, type RefObject } from "react";
 /*
   ПРИЦЕЛ МЕГАМЕНЮ — приём Amazon, разобранный Беном Каменсом в 2013 году.
 
-  Курсор идёт от Категории к её Витрине наискосок и по пути задевает соседние
-  Категории. Наивное «наведение открывает» сменило бы Витрину у человека под
+  Курсор идёт от Категории к её Полке наискосок и по пути задевает соседние
+  Категории. Наивное «наведение открывает» сменило бы Полку у человека под
   рукой. Прицел смотрит, КУДА движется курсор: пока он идёт в сторону открытой
-  Витрины, соседняя Категория наведение не перехватывает.
+  Полки, соседняя Категория наведение не перехватывает.
 
   Модель — как у `useSafelyMouseToSubmenu` в react-aria, чтобы подменю `Menu` и
   мегаменю вели себя одинаково: направление последнего шага сравнивается с
-  сектором от предыдущей точки к двум углам ближнего края Витрины; смена
+  сектором от предыдущей точки к двум углам ближнего края Полки; смена
   направления прощается; обработка прорежена до кадра; только мышь.
 
   Два осознанных расхождения с react-aria:
@@ -32,7 +32,7 @@ export const AIM_SETTLE_MS = 300;
 const THROTTLE_MS = 16;
 
 /**
- * Сколько шагов «не туда» подряд прощается. Счётчик растёт на шаг к Витрине и
+ * Сколько шагов «не туда» подряд прощается. Счётчик растёт на шаг к Полке и
  * падает на шаг мимо; целится курсор, пока счётчик выше нуля. Отсюда: одно
  * случайное движение вбок прицел не сбрасывает, два подряд — сбрасывают.
  */
@@ -40,7 +40,7 @@ const ALLOWED_INVALID_MOVES = 2;
 
 /**
  * Запас сектора по вертикали, пиксели. Без него курсор, идущий точно в угол
- * Витрины, выпадал бы из сектора на дрожании руки.
+ * Полки, выпадал бы из сектора на дрожании руки.
  */
 const SECTOR_PADDING = 24;
 
@@ -50,7 +50,7 @@ interface Point {
 }
 
 /**
- * Идёт ли шаг `from → to` к Витрине: направление шага лежит внутри сектора от
+ * Идёт ли шаг `from → to` к Полке: направление шага лежит внутри сектора от
  * `from` к двум углам её ближнего края.
  *
  * Векторное произведение, а не `atan2`: тот же сектор без разрыва угла на ±π.
@@ -61,9 +61,9 @@ export function isMovingToward(from: Point, to: Point, rect: DOMRect, side: "lef
   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 };
@@ -79,25 +79,25 @@ export function isMovingToward(from: Point, to: Point, rect: DOMRect, side: "lef
 const NONE = Symbol("none");
 
 interface MenuAimOptions {
-  /** Открытая Категория; `null` — Витрины нет, и целиться не во что. */
+  /** Открытая Категория; `null` — Полки нет, и целиться не во что. */
   value: string | null;
-  /** Открытая сейчас Витрина: её прямоугольник — цель. */
+  /** Открытая сейчас Полка: её прямоугольник — цель. */
   showcaseRef: RefObject<HTMLElement | null>;
-  /** Сменить Категорию (или закрыть Витрину — `null`). */
+  /** Сменить Категорию (или закрыть Полку — `null`). */
   commit: (next: string | null) => void;
 }
 
 /**
  * Прицел: решает, сменить Категорию под курсором сейчас или отложить.
  *
- * `request` зовётся из наведения на строку Столбца. Если Витрины нет или
+ * `request` зовётся из наведения на строку Столбца. Если Полки нет или
  * курсор не целится — смена сразу. Если целится — смена откладывается: курсор
  * перестал целиться или стоит `AIM_SETTLE_MS` — открывается то, что под ним
- * сейчас; дошёл до Витрины — смена отменяется.
+ * сейчас; дошёл до Полки — смена отменяется.
  *
- * Прямоугольник Витрины берётся заново на каждом шаге, а не кешируется:
+ * Прямоугольник Полки берётся заново на каждом шаге, а не кешируется:
  * прокрутка страницы и смена размера окна не оставляют его устаревшим, а цена
- * — одно чтение раскладки на кадр, и только пока Витрина открыта.
+ * — одно чтение раскладки на кадр, и только пока Полка открыта.
  */
 export function useMenuAim({ value, showcaseRef, commit }: MenuAimOptions) {
   const previous = useRef<Point | null>(null);
@@ -125,7 +125,7 @@ export function useMenuAim({ value, showcaseRef, commit }: MenuAimOptions) {
     timer.current = setTimeout(flush, AIM_SETTLE_MS);
   }, [flush]);
 
-  // Новая Витрина — новая цель: прежний счёт к ней отношения не имеет.
+  // Новая Полка — новая цель: прежний счёт к ней отношения не имеет.
   useEffect(() => {
     aim.current = 0;
     previous.current = null;
@@ -148,7 +148,7 @@ export function useMenuAim({ value, showcaseRef, commit }: MenuAimOptions) {
       previous.current = point;
       if (!showcase || !from) return;
 
-      // Курсор дошёл до Витрины — отложенная смена больше не нужна.
+      // Курсор дошёл до Полки — отложенная смена больше не нужна.
       if (event.target instanceof Node && showcase.contains(event.target)) {
         pending.current = NONE;
         clearTimer();
@@ -171,7 +171,7 @@ export function useMenuAim({ value, showcaseRef, commit }: MenuAimOptions) {
     return () => document.removeEventListener("pointermove", onPointerMove);
   }, [value, showcaseRef, flush, settleLater]);
 
-  /** Курсор наведён на строку Столбца: открыть её (`null` — закрыть Витрину). */
+  /** Курсор наведён на строку Столбца: открыть её (`null` — закрыть Полку). */
   const request = useCallback(
     (next: string | null) => {
       if (next === value) {

package/src/components/overlays/Menu.tsx

@@ -89,9 +89,19 @@ export interface MenuProps<T extends object = object> extends AriaMenuProps<T> {
    * Сторона, с которой панель раскрывается. Корневое меню по умолчанию — под
    * кнопкой слева (`bottom start`); вложенное, внутри `SubmenuTrigger`, —
    * сбоку от своего пункта, а на узком экране под ним. Явное значение
-   * побеждает оба умолчания.
+   * побеждает оба умолчания. `end top` и `start top` — сбоку по концу или
+   * началу строки: при письме справа налево они меняются местами, а
+   * `right top` и `left top` — нет.
    */
-  placement?: "bottom start" | "bottom end" | "top start" | "top end" | "right top" | "left top";
+  placement?:
+    | "bottom start"
+    | "bottom end"
+    | "top start"
+    | "top end"
+    | "end top"
+    | "start top"
+    | "right top"
+    | "left top";
 }
 
 export interface MenuItemProps extends Omit<AriaMenuItemProps, "children" | "className"> {

package/src/editor/RichTextEditor.tsx

@@ -16,6 +16,7 @@ import {
   useId,
   useImperativeHandle,
   useLayoutEffect,
+  useCallback,
   useMemo,
   useRef,
   useState,
@@ -58,6 +59,7 @@ import type { ToolPopoverRequest } from "./core/toolButtons.js";
 import type { TextCardControl } from "./ui/TextCard.js";
 import { SelectionPopover } from "./ui/ToolButtonView.js";
 import { tableChunk } from "./features/table/tableTool.js";
+import { stickyOffset } from "./features/toc/stickyOffset.js";
 import { replaceWithMarkdown } from "./core/markdown.js";
 import {
   documentFromJSON,
@@ -107,6 +109,15 @@ const TextCard = lazy(() =>
  * `basic`, который меряется бюджетом «старта». Плагин подсветки и сочетания
  * маленькие и стоят в движке сразу.
  */
+/*
+  Ядро Оглавления (Инструмент `toc`) — ленивым чанком: его включают единицы, а
+  полоса со списком и `HoverCard` стоили бы каждому Редактору ~5 kB gzip на
+  старте. Чанк приходит, только когда Инструмент включён и движок готов.
+*/
+const TocCore = lazy(() =>
+  import("./features/toc/RichTextToc.js").then((module) => ({ default: module.TocCore }))
+);
+
 const SearchPanel = lazy(() =>
   import("./features/search/SearchPanel.js").then((module) => ({ default: module.SearchPanel }))
 );
@@ -994,6 +1005,52 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
           }
         : { maxHeight: areaLength };
 
+    /*
+      Оглавление в левом поле (Инструмент `toc`, ADR-0068). Полоса липнет под
+      фиксированной Панелью: её высота меряется, потому что Панель переносит
+      ряд кнопок на узком поле. В прокручиваемом поле край — верх области.
+    */
+    const tocOn = enabledTools.has("toc");
+    const [toolbarShell, setToolbarShell] = useState<HTMLDivElement | null>(null);
+    const [toolbarHeight, setToolbarHeight] = useState(0);
+    useEffect(() => {
+      if (!toolbarShell || typeof ResizeObserver === "undefined") {
+        setToolbarHeight(toolbarShell?.offsetHeight ?? 0);
+        return;
+      }
+      const observer = new ResizeObserver(() => setToolbarHeight(toolbarShell.offsetHeight));
+      observer.observe(toolbarShell);
+      return () => observer.disconnect();
+    }, [toolbarShell]);
+    /*
+      Нижний край липкого верха поля: шапка приложения и Панель над Документом.
+      Не `null` никогда, даже без шапки: иначе переход ушёл бы в `scrollIntoView`,
+      а тот двигает и страницу вокруг поля с `maxHeight`. В прокручиваемом поле
+      подсветка и переход считают от верха области и этот край не используют.
+    */
+    const tocStickyTop = useCallback(
+      () => (stickyOffset("--topbar-h") ?? 0) + toolbarHeight,
+      [toolbarHeight]
+    );
+    /*
+      Переход в правке ставит каретку в конец заголовка, как структура документа
+      в Google Docs: с ним можно сразу писать. Прокрутку делает Оглавление, а
+      движок не прокручивает, чтобы не спорить с ним.
+      В `readOnly` каретки нет — фокус на заголовок ставит само Оглавление.
+    */
+    const tocFocusHeading = useCallback((heading: HTMLElement) => {
+      const current = editorRef.current;
+      if (!current || current.isDestroyed || !current.isEditable) return false;
+      const inside = current.view.posAtDOM(heading, 0);
+      const end = inside + current.state.doc.resolve(inside).parent.content.size;
+      current.commands.setTextSelection(end);
+      // `view.focus()`, а не команда `focus`: та ставит фокус кадром позже, и
+      // пункт списка, отпускающий фокус после клика, отдал бы его странице.
+      // ProseMirror фокусирует без прокрутки — прокрутку делает Оглавление.
+      current.view.focus();
+      return true;
+    }, []);
+
     /*
       `Alt+F10` — фокус на первое доступное действие Панели. Плавающую Панель
       клавиша показывает сама, не дожидаясь задержки показа: человек с
@@ -1395,6 +1452,15 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
     const leaveTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
     useEffect(() => () => clearTimeout(leaveTimerRef.current), []);
 
+    /** Цель Оглавления — Документ движка; объект новый с каждым движком. */
+    const tocTarget = useMemo(
+      () => ({
+        get current() {
+          return editor && !editor.isDestroyed ? (editor.view.dom as HTMLElement) : null;
+        },
+      }),
+      [editor]
+    );
     const searchPanelElement = (className: string) =>
       editor &&
       searchPanel && (
@@ -1450,7 +1516,7 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
               `z-[1]` — внутри поля, а не ступень стека слоёв: Панель не
               оверлей и должна оставаться ниже любого из них.
             */
-            <div className={TOOLBAR_SHELL_CLASS}>
+            <div ref={setToolbarShell} className={TOOLBAR_SHELL_CLASS}>
               <EditorToolbar
                 editor={editor}
                 tools={enabledTools}
@@ -1511,7 +1577,37 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
             style={areaStyle}
           >
             {/* В HTML-режиме Документ скрыт, но смонтирован: движок и история живы. */}
-            <EditorContent editor={editor} hidden={sourceOpen} />
+            {tocOn ? (
+              /*
+                Левое поле Оглавления: колонка есть, только пока есть полоса —
+                `TocCore` с меньше чем двумя заголовками не рисует ничего, и
+                текст стоит у края, как без Инструмента (ADR-0068, п. 2).
+              */
+              <div className="flex items-start">
+                {editor && !sourceOpen && (
+                  <Suspense fallback={null}>
+                    <TocCore
+                      target={tocTarget}
+                      stickyTop={tocStickyTop}
+                      focusHeading={tocFocusHeading}
+                      alignToFirstHeading
+                      data-toc-gutter=""
+                      className="sticky mr-3 shrink-0"
+                      style={{
+                        top: scrolls
+                          ? "0.5rem"
+                          : `calc(var(--topbar-h, 0px) + ${toolbarHeight}px + 0.5rem)`,
+                      }}
+                    />
+                  </Suspense>
+                )}
+                <div className="min-w-0 flex-1">
+                  <EditorContent editor={editor} hidden={sourceOpen} />
+                </div>
+              </div>
+            ) : (
+              <EditorContent editor={editor} hidden={sourceOpen} />
+            )}
             {!editor && (
               /*
               Скелет (ADR-0058, п. 11.4): до Готовности и при сбое загрузчика —
@@ -1737,7 +1833,15 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
             ref={hiddenRef}
             type="hidden"
             name={name}
-            defaultValue={initial}
+            /*
+              Значение скрытого поля пишет Редактор (`emit`, эффекты движка), а
+              не React. Но React на КАЖДОМ обновлении заново ставит `defaultValue`,
+              а у `type="hidden"` это и есть его значение: любой рендер родителя
+              откатывал бы поле формы к входящей строке. Поэтому после монтажа в
+              `defaultValue` уходит то, что уже лежит в поле, — React видит равенство
+              и ничего не трогает. Серверный рендер и первый кадр несут `initial`.
+            */
+            defaultValue={hiddenRef.current?.value ?? initial}
             // Выключенное поле не уходит в форму — как нативное. Поле только
             // для чтения уходит: это показанное значение, а не недоступный
             // контрол.

package/src/editor/core/handle.ts

@@ -4,10 +4,11 @@ import { createNodeFromContent, type JSONContent } from "@tiptap/core";
 import { closeHistory } from "@tiptap/pm/history";
 import type { Fragment } from "@tiptap/pm/model";
 import type { Editor } from "@tiptap/react";
-import type { RefObject } from "react";
 import { textBetween } from "./atomText.js";
 import { isRichTextDocument, type RichTextDocument } from "./jsonDocument.js";
 
+export { notifyHandleEditor, watchHandleEditor } from "./handleWatchers.js";
+
 /**
  * Плоские методы Хэндла (ADR-0058, раздел 8): то, что экран делает с Редактором
  * чаще всего. Остальное — `editor` (команды Меток, Блоков и своих Инструментов).
@@ -287,25 +288,3 @@ export function createHandleMethods(host: HandleHost): RichTextEditorHandleMetho
     canRedo: () => available("redo"),
   };
 }
-
-/*
-  Хук-селектор не знает, когда у `ref` появится движок: Редактор создаёт его
-  после первого рендера экрана и перерисовывается сам, а экран — нет. Поэтому
-  подписки живут по самому объекту `ref`, который есть с первого рендера, и
-  Редактор сообщает об смене движка по нему.
-*/
-const watchers = new WeakMap<object, Set<() => void>>();
-
-/** Подписка хука на смену движка у Редактора, привязанного к этому `ref`. */
-export function watchHandleEditor(ref: RefObject<unknown>, listener: () => void): () => void {
-  let set = watchers.get(ref);
-  if (!set) watchers.set(ref, (set = new Set()));
-  set.add(listener);
-  return () => void set.delete(listener);
-}
-
-/** Редактор сообщает: движок у `ref` появился или сменился. */
-export function notifyHandleEditor(ref: unknown): void {
-  if (typeof ref !== "object" || ref === null) return;
-  watchers.get(ref)?.forEach((listener) => listener());
-}

package/src/editor/core/handleWatchers.ts

@@ -0,0 +1,27 @@
+import type { RefObject } from "react";
+
+/*
+  Хук-селектор не знает, когда у `ref` появится движок: Редактор создаёт его
+  после первого рендера экрана и перерисовывается сам, а экран — нет. Поэтому
+  подписки живут по самому объекту `ref`, который есть с первого рендера, и
+  Редактор сообщает об смене движка по нему.
+
+  Модуль вынесен из `handle.ts` и не знает движка: подписаться на смену движка
+  нужно и `RichTextToc`, а ему Tiptap в бандл не нужен.
+*/
+
+const watchers = new WeakMap<object, Set<() => void>>();
+
+/** Подписка хука на смену движка у Редактора, привязанного к этому `ref`. */
+export function watchHandleEditor(ref: RefObject<unknown>, listener: () => void): () => void {
+  let set = watchers.get(ref);
+  if (!set) watchers.set(ref, (set = new Set()));
+  set.add(listener);
+  return () => void set.delete(listener);
+}
+
+/** Редактор сообщает: движок у `ref` появился или сменился. */
+export function notifyHandleEditor(ref: unknown): void {
+  if (typeof ref !== "object" || ref === null) return;
+  watchers.get(ref)?.forEach((listener) => listener());
+}

package/src/editor/core/tools.ts

@@ -50,6 +50,11 @@
  * разметку решает Схема, и режим её не расширяет. В `basic` его нет: в
  * комментарии кнопка «HTML» без явного запроса экрана — лишняя.
  *
+ * `toc` — Оглавление в левом поле рамки (ADR-0068): полоса и список
+ * `RichTextToc`, липкие под Панелью или в прокручиваемом поле. Своей Схемы нет.
+ * В пресеты не входит — ни в `full`, ни в `basic`: оно меняет раскладку поля,
+ * и обновление кита не должно сдвигать текст там, где его не просили.
+ *
  * `search` — поиск и замена по Документу: кнопка «Поиск»
  * фиксированной Панели и `Mod+F` в поле открывают панель в углу поля. Своей
  * Схемы нет, как у `clearFormatting`. Есть и в `basic`: искать по длинному
@@ -85,6 +90,7 @@ export const TOOLS = [
   "source",
   "search",
   "insertMenu",
+  "toc",
 ] as const;
 
 /** Имя инструмента Редактора. Список и смысл каждого — на странице компонента. */
@@ -104,7 +110,8 @@ export type RichTextEditorPreset = "full" | "basic";
  * markdown-шорткатом, чем через меню.
  */
 export const PRESETS: Record<RichTextEditorPreset, readonly Tool[]> = {
-  full: TOOLS,
+  // Все встроенные, кроме Оглавления: его включают только явно (ADR-0068).
+  full: TOOLS.filter((tool) => tool !== "toc"),
   basic: [
     "history",
     "bold",
@@ -122,7 +129,7 @@ export const PRESETS: Record<RichTextEditorPreset, readonly Tool[]> = {
 /**
  * Пресеты наружу — массивами (ADR-0058, п. 1.2): свой набор собирается из них,
  * например `[...RICH_TEXT_PRESETS.full, mergeTagTool]`. Копии заморожены:
- * `PRESETS.full` — это `TOOLS`, и правка массива потребителем меняла бы набор
+ * `PRESETS.full` — почти весь `TOOLS`, и правка массива потребителем меняла бы набор
  * кита во всех Редакторах страницы. Состав пресета — не контракт (ADR-0058,
  * п. 12.5): стабильный набор — точный список имён.
  */