@olddevs/ui 4.3.0 → 4.5.0

package/src/editor/features/toc/documentHeadings.ts

@@ -0,0 +1,59 @@
+import type { Editor } from "@tiptap/core";
+import type { Node as PmNode } from "@tiptap/pm/model";
+import { WRAPPER_NODE } from "../../core/nodeNames.js";
+import type { TocLevel, TocToolOptions } from "../../core/toolOptions.js";
+
+/*
+  Модуль без Tiptap в рантайме (только типы): его читает ядро Оглавления
+  (`TocCore`, `RichTextToc.tsx`), которому движок в бандл не нужен.
+*/
+
+/** Заголовок Документа с позицией: по ней команда `jumpTo` находит DOM-узел. */
+export interface TocDocumentHeading {
+  level: TocLevel;
+  text: string;
+  /** Позиция узла заголовка в Документе (для `editor.view.nodeDOM`). */
+  pos: number;
+}
+
+/**
+ * Заголовки Оглавления по Документу движка, а не по DOM: ядро Оглавления
+ * (`TocCore`) — ленивый чанк, и пока он не пришёл (или нарисован HTML-режим),
+ * узлов для обхода нет, а данные экран просит с первого кадра. Это единственный
+ * обход, по которому считаются индексы: и снимок Состояния `toc`, и команда
+ * `jumpTo` берут заголовок отсюда, поэтому индекс из снимка ведёт к тому же
+ * заголовку сразу после правки, не дожидаясь, пока ядро пересоберёт свой список
+ * из DOM (`REBUILD_DELAY`).
+ *
+ * ТЕ ЖЕ ПРАВИЛА, ЧТО У `collectHeadings` (`headings.ts`), иначе индексы разойдутся
+ * с пунктами списка: заголовок на верхнем уровне или внутри Обёрток (колонки
+ * Раскладки, свои Блоки, цитаты и списки — нет), уровень из `levels`, текст без
+ * крайних пробелов не пуст. Текст — тот же, что у `textContent` DOM: мягкий
+ * перенос в него не входит, а Текст атома — входит.
+ *
+ * Обход по верхнему уровню и Обёрткам, а не по всему Документу: стоимость — число
+ * Блоков верхнего уровня, она не растёт от вложенности и заметна не будет даже
+ * на каждой транзакции.
+ */
+export function tocDocumentHeadings(
+  editor: Editor,
+  { levels }: Pick<TocToolOptions, "levels">
+): TocDocumentHeading[] {
+  const headings: TocDocumentHeading[] = [];
+  // `start` — позиция, с которой начинается содержимое `parent`.
+  const visit = (parent: PmNode, start: number) =>
+    parent.forEach((node, offset) => {
+      const pos = start + offset;
+      if (node.type.name === WRAPPER_NODE) return visit(node, pos + 1);
+      if (node.type.name !== "heading") return;
+      const level = node.attrs.level as TocLevel;
+      const text = node
+        .textBetween(0, node.content.size, "", (leaf) =>
+          leaf.type.name === "hardBreak" ? "" : leaf.textContent
+        )
+        .trim();
+      if (text && levels.includes(level)) headings.push({ level, text, pos });
+    });
+  visit(editor.state.doc, 0);
+  return headings;
+}

package/src/editor/features/toc/headings.ts

@@ -0,0 +1,77 @@
+/**
+ * Заголовки Документа для Оглавления (`RichTextToc`, ADR-0066).
+ *
+ * Читаются из DOM цели, а не из строки `html`: один путь для Просмотра,
+ * Редактора и JSON-конверта, и переходу всё равно нужен живой узел.
+ *
+ * Модуль без React и без движка: только обход DOM.
+ */
+
+/** Заголовок в Оглавлении. */
+export interface TocHeading {
+  /** Узел заголовка в Документе: к нему ведёт переход. */
+  element: HTMLElement;
+  /** Текст пункта — текст заголовка без разметки. */
+  text: string;
+  /** Уровень по тегу: 1 для `h1` … 4 для `h4`. */
+  level: number;
+  /**
+   * Глубина относительно самого крупного заголовка Документа: у него 0. Отступ
+   * пункта и длина штриха считаются от неё, а не от уровня, — иначе Документ,
+   * где старший заголовок H2, начинался бы с пустой ступени.
+   */
+  depth: number;
+}
+
+const HEADING = "h1, h2, h3, h4";
+
+/**
+ * Обёртка — единственный контейнер, чьи заголовки идут в Оглавление.
+ *
+ * Колонки Раскладки — нет: два заголовка на одной высоте в соседних колонках
+ * путают подсветку текущего раздела, и порядок «левая колонка, затем правая»
+ * читателю ничего не говорит. Острова и свои Блоки — тоже нет: их содержимое —
+ * часть Блока, а не структура Документа.
+ */
+const WRAPPER = 'div[data-block="wrapper"]';
+
+/**
+ * Корень Документа внутри цели. У Просмотра это сам контейнер; у Редактора
+ * Документ лежит глубже, в узле движка — Панель и строка статуса снаружи него.
+ */
+export function documentRoot(target: HTMLElement): HTMLElement {
+  return target.querySelector<HTMLElement>(".ProseMirror") ?? target;
+}
+
+/** Заголовок лежит на верхнем уровне Документа или только в Обёртках. */
+function isStructural(heading: Element, root: HTMLElement): boolean {
+  for (let node = heading.parentElement; node && node !== root; node = node.parentElement) {
+    if (!node.matches(WRAPPER)) return false;
+  }
+  return true;
+}
+
+/**
+ * Заголовки Документа в порядке чтения. `only` — какие уровни (1–4) берутся:
+ * остальные не попадают в список, и глубина (`depth`) считается от самого
+ * крупного из оставшихся. Нет — все.
+ */
+export function collectHeadings(target: HTMLElement, only?: readonly number[]): TocHeading[] {
+  const root = documentRoot(target);
+  // Пустой заголовок (автор только начал его в Редакторе) — не пункт: у
+  // кнопки без текста не было бы имени, а у полосы — лишний штрих.
+  const found = [...root.querySelectorAll<HTMLElement>(HEADING)].filter(
+    (heading) =>
+      isStructural(heading, root) &&
+      heading.textContent?.trim() &&
+      (!only || only.includes(Number(heading.tagName[1])))
+  );
+  const levels = found.map((heading) => Number(heading.tagName[1]));
+  const top = Math.min(...levels);
+  return found.map((element, index) => ({
+    element,
+    text: element.textContent?.trim() ?? "",
+    level: levels[index]!,
+    depth: levels[index]! - top,
+  }));
+}

package/src/editor/features/toc/stickyOffset.ts

@@ -0,0 +1,21 @@
+"use client";
+
+import { toPixels } from "../../../hooks/useStickyOffset.js";
+
+/**
+ * Последний замер шапки. Подсветка читает отступ на каждом кадре прокрутки, а
+ * `toPixels` для значения не в пикселях (`4rem`) меряет зонд — две раскладки.
+ * Замер повторяется только при смене сырого значения, как в `useStickyOffset`.
+ */
+let measured: { raw: string; px: number | null } = { raw: "", px: null };
+
+/** Высота липкой шапки в пикселях; переменной нет — `null`. */
+export function stickyOffset(offsetVar: string): number | null {
+  const raw = getComputedStyle(document.documentElement).getPropertyValue(offsetVar).trim();
+  if (!raw) return null;
+  if (raw !== measured.raw) {
+    const px = parseFloat(toPixels(raw, "0px"));
+    measured = { raw, px: Number.isFinite(px) && px > 0 ? px : null };
+  }
+  return measured.px;
+}

package/src/editor/features/toc/tocSnapshot.ts

@@ -0,0 +1,24 @@
+"use client";
+
+import type { Editor } from "@tiptap/core";
+import type { TocToolOptions } from "../../core/toolOptions.js";
+import type { TocToolHeading, TocToolState } from "../../core/toolState.js";
+import { tocDocumentHeadings } from "./documentHeadings.js";
+
+/**
+ * Снимок Состояния `toc` для `useRichTextToolState`: заголовки из
+ * `tocDocumentHeadings` без позиций (они в контракт не входят) и текущий раздел.
+ * `at` — индекс текущего раздела, который сообщило ядро Оглавления.
+ */
+export function tocSnapshot(
+  editor: Editor,
+  options: Pick<TocToolOptions, "levels">,
+  at: number | undefined
+): TocToolState {
+  const headings: TocToolHeading[] = tocDocumentHeadings(editor, options).map(
+    ({ level, text }, index) => ({ level, text, index })
+  );
+  // Прокрутка сообщает индекс по прежнему списку: после правки он мог выйти за край.
+  const current = headings.length ? Math.min(Math.max(at ?? 0, 0), headings.length - 1) : -1;
+  return { headings, current };
+}

package/src/editor/features/toc/tocTool.ts

@@ -0,0 +1,41 @@
+"use client";
+
+import type { ToolDescriptor } from "../../core/toolDescriptor.js";
+import type { TocToolCommands } from "../../core/toolCommands.js";
+import type { TocLevel, TocToolOptions } from "../../core/toolOptions.js";
+
+/**
+ * Оглавление на описании Инструмента (ADR-0068). Части для движка и UI-записей
+ * у него нет: полосу и список рисует `RichTextEditor` в левом поле рамки
+ * (`TocCore`, ленивым чанком), а описание несёт Опции — умолчания и проверки,
+ * из которых `expandTools` собирает Опции Редактора.
+ *
+ * Тяжёлых импортов нет: описание лежит в стартовом куске Редактора, а UI
+ * Оглавления — нет.
+ */
+const TOC_LEVELS: readonly TocLevel[] = [1, 2, 3, 4];
+
+/** Умолчания Опций: переменная `TopBar` (ADR-0016), все четыре уровня, список в 240 пикселей. */
+export const TOC_DEFAULTS: TocToolOptions = {
+  offsetVar: "--topbar-h",
+  levels: TOC_LEVELS,
+  listWidth: 240,
+};
+
+export const TOC_TOOL: ToolDescriptor = {
+  name: "toc",
+  defaults: TOC_DEFAULTS,
+  checks: {
+    // Имя вставляется в `var(…)` стиля поля, поэтому — только слово с дефисами.
+    offsetVar: (value) => typeof value === "string" && /^--[\w-]+$/.test(value),
+    levels: (value) =>
+      Array.isArray(value) &&
+      value.length > 0 &&
+      value.every((level) => (TOC_LEVELS as readonly unknown[]).includes(level)),
+    listWidth: (value) =>
+      (typeof value === "number" && Number.isFinite(value) && value > 0) ||
+      (typeof value === "string" && value.trim() !== ""),
+  },
+  // Переход живёт в ленивом ядре Оглавления: мост зовёт его, пока оно смонтировано.
+  commands: ({ bridge }): TocToolCommands => ({ jumpTo: bridge.jumpToc }),
+};

package/src/editor/hooks/useRichTextToolState.ts

@@ -0,0 +1,153 @@
+"use client";
+
+import type { Editor } from "@tiptap/react";
+import { useCallback, useRef, useSyncExternalStore, type RefObject } from "react";
+import { toolSignals, watchHandleEditor } from "../core/handleWatchers.js";
+import { toolOptions } from "../core/toolDescriptor.js";
+import type { RichTextTools } from "../core/toolOptions.js";
+import type { RichTextEditorHandle } from "../RichTextEditor.js";
+import { searchSnapshot } from "../features/search/searchSnapshot.js";
+import { tocSnapshot } from "../features/toc/tocSnapshot.js";
+
+/**
+ * Состояние Инструмента по имени: тип из карты `RichTextTools`. Имя, которого в
+ * карте нет, — `unknown`: типизация добровольна, и Инструмент без записи в карте
+ * не ломает сборку.
+ */
+export type RichTextToolState<Name extends string> = Name extends keyof RichTextTools
+  ? RichTextTools[Name] extends { state: infer State }
+    ? State
+    : unknown
+  : unknown;
+
+/** Снимок встроенного Инструмента; `null` — Инструмента в движке нет. */
+const SNAPSHOTS = new Map<string, (editor: Editor, ref: object) => unknown>([
+  [
+    "search",
+    (editor, ref) => {
+      const { tools, searchOpen } = toolSignals(ref);
+      return tools?.has("search") ? searchSnapshot(editor, searchOpen === true) : null;
+    },
+  ],
+  [
+    "toc",
+    (editor, ref) => {
+      const { tools, tocAt } = toolSignals(ref);
+      const options = tools && toolOptions(tools, "toc");
+      return options && tocSnapshot(editor, options, tocAt);
+    },
+  ],
+]);
+
+/** Простой объект: литерал или `Object.create(null)`, не экземпляр класса. */
+function isPlainObject(value: object): boolean {
+  const prototype = Object.getPrototypeOf(value) as unknown;
+  return prototype === Object.prototype || prototype === null;
+}
+
+/**
+ * Равенство для снимков. По значению сравниваются только простые данные:
+ * примитивы, массивы и простые объекты. Всё прочее — `Date`, `Map`, `Set`,
+ * экземпляры классов — по ссылке: у них нет собственных ключей, по которым можно
+ * было бы увидеть разницу, и «равными по значению» оказались бы любые два, то есть
+ * экран тихо не обновлялся бы. Новый экземпляр — новый снимок.
+ */
+function sameValue(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (!Array.isArray(a) && !(isPlainObject(a) && isPlainObject(b))) return false;
+  const left = a as Record<string, unknown>;
+  const right = b as Record<string, unknown>;
+  const keys = Object.keys(left);
+  return (
+    keys.length === Object.keys(right).length &&
+    keys.every((key) => key in right && sameValue(left[key], right[key]))
+  );
+}
+
+/**
+ * Состояние встроенного Инструмента для своего экрана: «3 из 12» в Строке
+ * статуса из Поиска, внешняя навигация из заголовков Оглавления. Имя —
+ * Инструмент из набора `tools`, а тип снимка выводится из карты
+ * `RichTextTools`: `search` отдаёт `SearchToolState`, `toc` — `TocToolState`.
+ *
+ * ПЕРЕРИСОВКА — ТОЛЬКО ПРИ СМЕНЕ СНИМКА. Снимок пересчитывается на каждую
+ * транзакцию движка и на сигналы кита, которых в движке нет: открытие и закрытие
+ * панели Поиска, смена текущего раздела Оглавления при прокрутке. Экран
+ * перерисовывается, когда результат стал другим (простые данные — примитивы,
+ * массивы, простые объекты — сравниваются по значению, как у
+ * `useRichTextEditorState`; `Date`, `Map`, `Set` и экземпляры классов — по
+ * ссылке), поэтому набор текста, не меняющий снимок, его не трогает. Срез из `selector` сравнивается так же: `(state) => state.total`
+ * подписывает экран на одно число.
+ *
+ * `null` — до монтажа и в первом рендере экрана, на сервере, а также когда
+ * Инструмента нет в наборе `tools`: пресеты `toc` не включают, его включают
+ * именем или записью `tool("toc")`. Селектор при `null` не вызывается. Один и
+ * тот же `ref` отдаётся в `RichTextEditor`.
+ *
+ * Снимок — данные без DOM-узлов и позиций ProseMirror; изменять его не нужно.
+ * Хук в стартовый граф `RichTextEditor` не входит: его цена — только у экрана,
+ * который его импортировал.
+ *
+ * @example
+ * const ref = useRef<RichTextEditorHandle>(null);
+ * const total = useRichTextToolState(ref, "search", (state) => state.total);
+ * const headings = useRichTextToolState(ref, "toc", (state) => state.headings);
+ */
+export function useRichTextToolState<Name extends string>(
+  ref: RefObject<RichTextEditorHandle | null>,
+  name: Name
+): RichTextToolState<Name> | null;
+export function useRichTextToolState<Name extends string, Slice>(
+  ref: RefObject<RichTextEditorHandle | null>,
+  name: Name,
+  selector: (state: RichTextToolState<Name>) => Slice
+): Slice | null;
+export function useRichTextToolState(
+  ref: RefObject<RichTextEditorHandle | null>,
+  name: string,
+  selector?: (state: never) => unknown
+): unknown {
+  const last = useRef<{ value: unknown } | null>(null);
+
+  const subscribe = useCallback(
+    (listener: () => void) => {
+      // Транзакции движка — на текущем движке; он меняется — пересаживаем слушателя.
+      let followed: Editor | null = null;
+      const follow = () => {
+        followed?.off("transaction", listener);
+        const editor = ref.current?.editor ?? null;
+        followed = editor && !editor.isDestroyed ? editor : null;
+        followed?.on("transaction", listener);
+      };
+      follow();
+      const stop = watchHandleEditor(ref, () => {
+        follow();
+        listener();
+      });
+      return () => {
+        stop();
+        followed?.off("transaction", listener);
+      };
+    },
+    [ref]
+  );
+
+  const read = (): unknown => {
+    const editor = ref.current?.editor;
+    // Своё Состояние — функция описания из набора этого Редактора; встроенное — таблица.
+    const own = toolSignals(ref).tools?.descriptors.find((entry) => entry.name === name)?.state;
+    const snapshot =
+      editor && !editor.isDestroyed
+        ? ((own ? own(editor) : SNAPSHOTS.get(name)?.(editor, ref)) ?? null)
+        : null;
+    const value = snapshot === null || !selector ? snapshot : selector(snapshot as never);
+    // Прежняя ссылка, пока значение то же: иначе React видит новый снимок на каждый рендер.
+    if (last.current && sameValue(last.current.value, value)) return last.current.value;
+    last.current = { value };
+    return value;
+  };
+
+  return useSyncExternalStore(subscribe, read, () => null);
+}

package/src/editor/index.ts

@@ -19,8 +19,12 @@ export { RichTextEditor } from "./RichTextEditor.js";
 export type { RichTextEditorHandle, RichTextEditorProps } from "./RichTextEditor.js";
 export type { RichTextDocument } from "./core/jsonDocument.js";
 export { useRichTextEditorState } from "./hooks/useRichTextEditorState.js";
+export { useRichTextToolState } from "./hooks/useRichTextToolState.js";
+export type { RichTextToolState } from "./hooks/useRichTextToolState.js";
 export { RichTextView } from "./RichTextView.js";
 export type { RichTextViewProps } from "./RichTextView.js";
+export { RichTextToc } from "./features/toc/RichTextToc.js";
+export type { RichTextTocProps } from "./features/toc/RichTextToc.js";
 export type { FieldNotice, FieldNoticeTone } from "./core/fieldNotice.js";
 export type { RichTextSurface } from "./styles/surface.js";
 export { richTextSanitizeConfig, richTextSchema, sanitizeRichText } from "./core/schema.js";
@@ -34,6 +38,23 @@ export type {
 } from "./core/schema.js";
 export { RICH_TEXT_PRESETS } from "./core/tools.js";
 export type { RichTextEditorPreset } from "./core/tools.js";
+export { tool } from "./core/toolOptions.js";
+export { defineTool } from "./core/toolDefinition.js";
+export type {
+  CustomToolBody,
+  ToolDefinition,
+  ToolDefinitionContext,
+  ToolDefinitionInput,
+} from "./core/toolDefinition.js";
+export type {
+  ConfiguredTool,
+  RichTextTools,
+  SearchToolOptions,
+  TocLevel,
+  TocToolOptions,
+} from "./core/toolOptions.js";
+export type { SearchToolCommands, TocToolCommands } from "./core/toolCommands.js";
+export type { SearchToolState, TocToolHeading, TocToolState } from "./core/toolState.js";
 export { markRange } from "./core/customTool.js";
 export type {
   TextCardRange,

package/src/i18n/defaults.ts

@@ -654,6 +654,7 @@ export const DEFAULT_MESSAGES: UiMessages = {
     blockMoveDown: "Move down",
     blockDuplicate: "Duplicate",
     blockDelete: "Delete",
+    toc: "Table of contents",
   },
 };
 

package/src/i18n/messages.ts

@@ -1080,6 +1080,11 @@ export interface UiMessages {
     blockMoveDown: string;
     blockDuplicate: string;
     blockDelete: string;
+    /**
+     * Оглавление Документа (`RichTextToc`): имя кнопки-полосы и подпись
+     * `nav` со списком заголовков — одно слово на оба, это одна вещь.
+     */
+    toc: string;
   };
 }
 

package/src/locales/ru.ts

@@ -693,6 +693,7 @@ export const messages: UiMessages = {
     blockMoveDown: "Вниз",
     blockDuplicate: "Дублировать",
     blockDelete: "Удалить",
+    toc: "Оглавление",
   },
 };