@olddevs/ui 4.4.0 → 4.5.1

package/src/editor/features/toc/RichTextToc.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import type { Editor } from "@tiptap/core";
 import {
   forwardRef,
   useCallback,
@@ -8,6 +9,7 @@ import {
   useState,
   type HTMLAttributes,
   type KeyboardEvent,
+  type MutableRefObject,
   type RefObject,
 } from "react";
 import {
@@ -19,6 +21,7 @@ import { useMessages } from "../../../i18n/useMessages.js";
 import { cn } from "../../../lib/cn.js";
 import { watchHandleEditor } from "../../core/handleWatchers.js";
 import type { RichTextEditorHandle } from "../../RichTextEditor.js";
+import { tocDocumentHeadings } from "./documentHeadings.js";
 import { collectHeadings, documentRoot, type TocHeading } from "./headings.js";
 import { stickyOffset } from "./stickyOffset.js";
 
@@ -50,6 +53,13 @@ export interface RichTextTocProps extends Omit<HTMLAttributes<HTMLDivElement>, "
    * По умолчанию 240px.
    */
   listWidth?: number | string;
+  /**
+   * Уровни заголовков, которые попадают в Оглавление: подмножество 1–4. Заголовка
+   * другого уровня нет ни в полосе, ни в списке, а отступ пунктов считается от
+   * самого крупного из оставшихся. Читается при каждой сборке списка, поэтому
+   * смена набора уровней пересобирает его. По умолчанию все четыре.
+   */
+  levels?: readonly (1 | 2 | 3 | 4)[];
 }
 
 /**
@@ -77,6 +87,9 @@ const itemIndent = (depth: number) => ITEM_INDENT[Math.min(depth, ITEM_INDENT.le
 const OPEN_DELAY = 200;
 const CLOSE_DELAY = 300;
 
+/** Все уровни заголовков: Оглавление без `levels`. */
+const ALL_LEVELS = [1, 2, 3, 4] as const;
+
 /** Пауза после последней правки Документа, по которой список пересобирается. */
 const REBUILD_DELAY = 150;
 
@@ -185,12 +198,23 @@ function jumpTo(
   flash(heading);
 
   const behavior: ScrollBehavior = prefersReducedMotion() ? "auto" : "smooth";
-  // Без шапки браузер сам учтёт `scroll-margin-top` заголовка.
+  const scroller = scrollParent(heading);
   if (offset === null) {
-    heading.scrollIntoView({ behavior, block: "start" });
+    // Без шапки отступ задаёт `scroll-margin-top` заголовка (ADR-0016). Окно
+    // прокручивает браузер. Но `scrollIntoView` двигает ещё и всех
+    // прокручиваемых предков, а значит, при Документе в своей прокручиваемой
+    // области уехала бы и страница, — поэтому область прокручивается сама,
+    // а окно не трогается.
+    if (!scroller) {
+      heading.scrollIntoView({ behavior, block: "start" });
+      return;
+    }
+    const margin = parseFloat(getComputedStyle(heading).scrollMarginTop) || 0;
+    const edge = scroller.getBoundingClientRect().top;
+    const top = heading.getBoundingClientRect().top;
+    scroller.scrollTo({ top: scroller.scrollTop + top - edge - margin, behavior });
     return;
   }
-  const scroller = scrollParent(heading);
   const top = heading.getBoundingClientRect().top;
   if (scroller) {
     const edge = scroller.getBoundingClientRect().top;
@@ -320,6 +344,26 @@ export interface TocCoreProps extends RichTextTocProps {
    * уровня, а не полоса выше текста.
    */
   alignToFirstHeading?: boolean;
+  /**
+   * Текущий раздел сменился (в том числе при первом показе): Редактор кладёт
+   * индекс в Состояние Инструмента `toc`. Индекс считается по списку, который
+   * видит `TocCore`; пока заголовков меньше двух, он остаётся прежним.
+   */
+  onCurrentChange?: (index: number) => void;
+  /**
+   * Движок Редактора. Нужен команде `jumpTo` (`jumpRef`): индекс команды — это
+   * индекс заголовка в снимке Состояния `toc`, а снимок читает Документ движка
+   * на каждой транзакции. Список ядра пересобирается из DOM с задержкой
+   * (`REBUILD_DELAY`), и сразу после правки индексы двух списков расходились бы.
+   * Без движка `jumpTo` считает по списку ядра.
+   */
+  editor?: Editor;
+  /**
+   * Куда ядро кладёт переход к заголовку по индексу снимка Состояния (команда
+   * `jumpTo` Инструмента): ведёт себя как клик по пункту. Пока ядро смонтировано,
+   * там функция, после — `null`. Нет заголовка с таким индексом — `false`.
+   */
+  jumpRef?: MutableRefObject<((index: number) => boolean) | null>;
 }
 
 export const TocCore = forwardRef<HTMLDivElement, TocCoreProps>(function TocCore(
@@ -327,9 +371,13 @@ export const TocCore = forwardRef<HTMLDivElement, TocCoreProps>(function TocCore
     target,
     offsetVar = "--topbar-h",
     listWidth = 240,
+    levels,
     stickyTop,
     focusHeading,
     alignToFirstHeading = false,
+    onCurrentChange,
+    editor,
+    jumpRef,
     className,
     style,
     ...rest
@@ -338,10 +386,12 @@ export const TocCore = forwardRef<HTMLDivElement, TocCoreProps>(function TocCore
 ) {
   // Настройки хозяина читаются в обработчиках прокрутки: последние значения —
   // через ссылку, чтобы новая функция на каждом рендере не пересоздавала слушателей.
-  const latest = useRef({ stickyTop, focusHeading, offsetVar });
+  const latest = useRef({ stickyTop, focusHeading, offsetVar, levels, onCurrentChange, editor });
   useEffect(() => {
-    latest.current = { stickyTop, focusHeading, offsetVar };
+    latest.current = { stickyTop, focusHeading, offsetVar, levels, onCurrentChange, editor };
   });
+  // Набор уровней сравнивается по значению: массив-литерал новый на каждом рендере.
+  const levelsKey = levels ? levels.join(",") : "";
   const offsetNow = useCallback(() => {
     const own = latest.current;
     return own.stickyTop ? own.stickyTop() : stickyOffset(own.offsetVar);
@@ -351,6 +401,10 @@ export const TocCore = forwardRef<HTMLDivElement, TocCoreProps>(function TocCore
   const [headings, setHeadings] = useState<TocHeading[]>([]);
   const [gap, setGap] = useState(STRIP_GAP);
   const [current, setCurrent] = useState(0);
+  // Текущий раздел — в Состояние Инструмента (`useRichTextToolState`).
+  useEffect(() => {
+    latest.current.onCurrentChange?.(current);
+  }, [current]);
   const [open, setOpen] = useState(false);
   const [fits, setFits] = useState(true);
   const stripRef = useRef<HTMLButtonElement>(null);
@@ -379,7 +433,7 @@ export const TocCore = forwardRef<HTMLDivElement, TocCoreProps>(function TocCore
       return;
     }
     const read = () => {
-      const next = collectHeadings(element);
+      const next = collectHeadings(element, latest.current.levels);
       setHeadings((prev) => (sameHeadings(prev, next) ? prev : next));
     };
     read();
@@ -397,7 +451,7 @@ export const TocCore = forwardRef<HTMLDivElement, TocCoreProps>(function TocCore
       clearTimeout(timer);
       observer.disconnect();
     };
-  }, [element]);
+  }, [element, levelsKey]);
 
   // Шаг полосы зависит от высоты окна и числа заголовков.
   useEffect(() => {
@@ -426,7 +480,7 @@ export const TocCore = forwardRef<HTMLDivElement, TocCoreProps>(function TocCore
     Пересчёт возвращается со следующей прокрутки после того, как переход
     улёгся (`settled`).
   */
-  const pinned = useRef<{ index: number; settled: boolean; timer: number } | null>(null);
+  const pinned = useRef<{ heading: HTMLElement; settled: boolean; timer: number } | null>(null);
   /** (Пере)запустить ожидание: прокрутка перехода молчит `PIN_SETTLE` — переход улёгся. */
   const settle = (lock: { settled: boolean; timer: number }) => {
     window.clearTimeout(lock.timer);
@@ -434,12 +488,62 @@ export const TocCore = forwardRef<HTMLDivElement, TocCoreProps>(function TocCore
       lock.settled = true;
     }, PIN_SETTLE);
   };
-  const pin = (index: number) => {
+  /*
+    Раздел перехода помнится узлом, а не индексом: список может пересобраться,
+    пока идёт прокрутка (правка моложе `REBUILD_DELAY`), и индекс повёл бы к
+    соседнему заголовку.
+  */
+  const pin = (index: number, heading: HTMLElement) => {
     if (pinned.current) window.clearTimeout(pinned.current.timer);
-    pinned.current = { index, settled: false, timer: 0 };
+    pinned.current = { heading, settled: false, timer: 0 };
     settle(pinned.current);
     setCurrent(index);
   };
+  /*
+    Переход к пункту списка: клик и команда `jumpTo` Инструмента идут одним
+    путём. Заголовок, уже вышедший из Документа (правка моложе `REBUILD_DELAY`),
+    не пункт: список вот-вот пересоберётся.
+  */
+  const go = (index: number): boolean => {
+    const heading = headings[index];
+    if (!heading?.element.isConnected) return false;
+    pin(index, heading.element);
+    jumpTo(heading.element, offsetNow(), latest.current.focusHeading);
+    return true;
+  };
+  /*
+    Команда `jumpTo(index)`: индекс — из снимка Состояния, а снимок читает
+    Документ движка (`tocDocumentHeadings`, тот же обход), поэтому заголовок
+    берётся оттуда: `view.nodeDOM` отдаёт его узел, ProseMirror обновляет DOM
+    синхронно с транзакцией. Список ядра при этом может отставать до
+    `REBUILD_DELAY`, поэтому читается заново, а не из состояния: от него нужен
+    только индекс пункта для подсветки.
+  */
+  const goToSnapshotIndex = (index: number): boolean => {
+    const { editor: engine, levels: shown } = latest.current;
+    if (!engine) return go(index);
+    if (engine.isDestroyed) return false;
+    const found = tocDocumentHeadings(engine, { levels: shown ?? ALL_LEVELS })[index];
+    const node = found && engine.view.nodeDOM(found.pos);
+    if (!(node instanceof HTMLElement) || !node.isConnected || !element) return false;
+    const fresh = collectHeadings(element, shown);
+    setHeadings((prev) => (sameHeadings(prev, fresh) ? prev : fresh));
+    const listed = fresh.findIndex((heading) => heading.element === node);
+    if (listed >= 0) pin(listed, node);
+    jumpTo(node, offsetNow(), latest.current.focusHeading);
+    return true;
+  };
+  const goRef = useRef(goToSnapshotIndex);
+  useEffect(() => {
+    goRef.current = goToSnapshotIndex;
+  });
+  useEffect(() => {
+    if (!jumpRef) return;
+    jumpRef.current = (index) => goRef.current(index);
+    return () => {
+      jumpRef.current = null;
+    };
+  }, [jumpRef]);
 
   // Подсветка текущего раздела. Слушатель прокрутки — на документе с захватом:
   // так его достигает прокрутка и окна, и любого контейнера вокруг цели.
@@ -448,7 +552,13 @@ export const TocCore = forwardRef<HTMLDivElement, TocCoreProps>(function TocCore
     let frame = 0;
     const update = () => {
       frame = 0;
-      setCurrent(currentIndex(headings, offsetNow()));
+      // Список пересобрался, пока идёт прокрутка перехода: раздел перехода тот
+      // же заголовок, но под новым индексом. Замер посреди прокрутки назвал бы
+      // соседний, и он остался бы текущим, когда прокрутка уляжется.
+      const lock = pinned.current;
+      const held =
+        lock && !lock.settled ? headings.findIndex((h) => h.element === lock.heading) : -1;
+      setCurrent(held >= 0 ? held : currentIndex(headings, offsetNow()));
     };
     const schedule = (event?: Event) => {
       // Считается только прокрутка, которая двигает Документ: окна или
@@ -670,8 +780,7 @@ export const TocCore = forwardRef<HTMLDivElement, TocCoreProps>(function TocCore
                       index === current ? "bg-bg-2 text-fg-0" : "text-fg-2 hover:text-fg-0"
                     )}
                     onClick={(event) => {
-                      pin(index);
-                      jumpTo(heading.element, offsetNow(), latest.current.focusHeading);
+                      go(index);
                       /*
                         В Редакторе в правке фокус на заголовок не переходит и
                         остаётся на пункте, а фокус в списке держит его открытым:

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

@@ -51,13 +51,20 @@ function isStructural(heading: Element, root: HTMLElement): boolean {
   return true;
 }
 
-/** Заголовки Документа в порядке чтения. */
-export function collectHeadings(target: HTMLElement): TocHeading[] {
+/**
+ * Заголовки Документа в порядке чтения. `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()
+    (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);

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,6 +19,8 @@ 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";
@@ -36,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,