@olddevs/ui 4.4.0 → 4.5.1

package/src/editor/RichTextEditor.tsx

@@ -32,7 +32,8 @@ import { BlockHandle } from "./ui/BlockHandle.js";
 import { expandTools } from "./features/builtins.js";
 import {
   createHandleMethods,
-  notifyHandleEditor,
+  clearToolSignals,
+  publishToolSignals,
   type RichTextEditorHandleMethods,
 } from "./core/handle.js";
 import { EditorToolbar, ToolbarSkeleton } from "./ui/EditorToolbar.js";
@@ -47,14 +48,14 @@ import { customToolsError, FALLBACK_EXTENSIONS } from "./core/customToolEngine.j
 import { startLoad, type ToolLoad } from "./core/toolLoader.js";
 import { skeletonHtml } from "./core/skeleton.js";
 import { Button } from "../components/actions/Button.js";
-import { devError } from "../lib/dev-warn.js";
+import { devError, devWarn } from "../lib/dev-warn.js";
 import { describeImageNotice } from "./features/image/imageNotice.js";
 import { insertItemsFor } from "./core/insertItems.js";
 import type { CustomColorKind } from "./features/color/customColor.js";
 import { isImageSelection } from "./features/image/image.js";
 import { ImagePopover } from "./features/image/ImagePopover.js";
 import { ImageToolbar } from "./features/image/ImageToolbar.js";
-import { textCardsOf, triggersOf } from "./core/toolDescriptor.js";
+import { textCardsOf, toolOptions, triggersOf, type ToolBridge } from "./core/toolDescriptor.js";
 import type { ToolPopoverRequest } from "./core/toolButtons.js";
 import type { TextCardControl } from "./ui/TextCard.js";
 import { SelectionPopover } from "./ui/ToolButtonView.js";
@@ -254,14 +255,18 @@ export interface RichTextEditorProps {
    * клавиш, ни markdown-шорткатом, ни вставкой.
    *
    * Вперемешку с именами кита — описания своих Инструментов (`CustomTool`):
-   * `[...RICH_TEXT_PRESETS.full, mergeTagTool]`. Неизвестное имя отбрасывается
+   * `[...RICH_TEXT_PRESETS.full, mergeTagTool]`. Встроенный Инструмент с
+   * Опциями (`search`, `toc`) настраивается записью `tool()`:
+   * `[...RICH_TEXT_PRESETS.full, tool("toc", { levels: [2, 3] })]` — запись
+   * включает Инструмент и без имени, а имя из пресета уступает ей; две записи
+   * `tool()` с одним именем — ошибка поля. Неизвестное имя отбрасывается
    * молча; описание с ошибкой (имя без Префикса потребителя, совпадение имён,
    * Часть для движка мимо правил Схемы) — ошибка поля: движок не создаётся,
    * значение формы остаётся входящим, причина — в консоли разработчика.
    *
-   * `preset` и `tools` читаются при создании движка: Схема ProseMirror после
-   * этого не меняется. Чтобы сменить набор у живого поля, перемонтируйте его
-   * (`key`) — история правок при этом теряется.
+   * `preset` и `tools`, а с ними и Опции Инструментов, читаются при создании
+   * движка: Схема ProseMirror после этого не меняется. Чтобы сменить набор у
+   * живого поля, перемонтируйте его (`key`) — история правок при этом теряется.
    */
   tools?: readonly ToolEntry[];
   /**
@@ -362,6 +367,9 @@ export interface RichTextEditorHandle extends RichTextEditorHandleMethods {
    * Открыть панель «Поиск и замена» из кода экрана — то же, что
    * кнопка «Поиск» и `Mod+F`; `replace` — фокус в поле замены. Без Инструмента
    * `search`, в HTML-режиме и до монтажа — ничего.
+   *
+   * @deprecated Работает как `handle.tool("search")?.open(options)`; в разработке
+   * один раз предупреждает об этом в консоли. Будет удалён в 5.0.
    */
   openSearch(options?: { replace?: boolean }): void;
   /**
@@ -662,6 +670,8 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
       replace: boolean;
       query: string;
     } | null>(null);
+    /** Переход ядра Оглавления (`TocCore`): есть, пока оно смонтировано. */
+    const tocJumpRef = useRef<((index: number) => boolean) | null>(null);
     const sourceFieldRef = useRef<HTMLTextAreaElement>(null);
     const sourceTextRef = useRef<string | null>(null);
     const sourceBaseRef = useRef("");
@@ -794,8 +804,9 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
     const openSource = () => {
       const current = editorRef.current;
       if (!current) return;
-      // Документа на экране не будет — искать в нём негде.
-      if (searchPanel) closeSearch(false);
+      // Документа на экране не будет — искать в нём негде. Подсветка бывает и без
+      // панели (команда `setQuery`): `next()` в скрытом Документе вышла бы удачной.
+      if (enabledTools.has("search")) closeSearch(false);
       const text = writeSource(current);
       switchFocusRef.current = "source";
       setSource({ text, minHeight: current.view.dom.getBoundingClientRect().height });
@@ -816,18 +827,25 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
 
     /*
       Открыть панель поиска: кнопка Панели, `Mod+F`/`Mod+Alt+F` из движка и
-      `openSearch()` Хэндла. Выделенный текст одного Блока становится запросом,
+      команда `open` Инструмента. Выделенный текст одного Блока становится запросом,
       как в редакторах кода; выделение через Блоки — нет: запрос не переходит
-      границу Блока, и такой текст не нашёлся бы. В HTML-режиме Документа на
-      экране нет — искать негде, и `Mod+F` остаётся браузеру.
+      границу Блока, и такой текст не нашёлся бы. Явный `query` команды главнее
+      выделения. В HTML-режиме Документа на экране нет — искать негде, и `Mod+F`
+      остаётся браузеру.
     */
-    const openSearch = (replace: boolean): boolean => {
+    const openSearch = (replace: boolean, query?: string): boolean => {
       const current = editorRef.current;
       if (!current || !enabledTools.has("search") || sourceTextRef.current !== null) return false;
       const { $from, $to, empty } = current.state.selection;
-      const query =
+      const selected =
         !empty && $from.sameParent($to) ? current.state.doc.textBetween($from.pos, $to.pos) : "";
-      setSearchPanel((previous) => ({ token: (previous?.token ?? 0) + 1, replace, query }));
+      setSearchPanel((previous) => ({
+        token: (previous?.token ?? 0) + 1,
+        replace,
+        query: query ?? selected,
+      }));
+      // Подсветка и переходы — сразу, не дожидаясь ленивой панели.
+      if (query !== undefined) current.commands.setSearch(query);
       return true;
     };
     const openSearchRef = useRef(openSearch);
@@ -849,6 +867,7 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
         chain.clearSearch().run();
       }
       setSearchPanel(null);
+      return true;
     };
 
     // Пункты Меню вставки — из того же замороженного набора, что и Схема.
@@ -1010,7 +1029,9 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
       фиксированной Панелью: её высота меряется, потому что Панель переносит
       ряд кнопок на узком поле. В прокручиваемом поле край — верх области.
     */
-    const tocOn = enabledTools.has("toc");
+    const tocOptions = toolOptions(enabledTools, "toc");
+    const tocOn = enabledTools.has("toc") && tocOptions !== undefined;
+    const tocOffsetVar = tocOptions?.offsetVar ?? "--topbar-h";
     const [toolbarShell, setToolbarShell] = useState<HTMLDivElement | null>(null);
     const [toolbarHeight, setToolbarHeight] = useState(0);
     useEffect(() => {
@@ -1029,8 +1050,8 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
       подсветка и переход считают от верха области и этот край не используют.
     */
     const tocStickyTop = useCallback(
-      () => (stickyOffset("--topbar-h") ?? 0) + toolbarHeight,
-      [toolbarHeight]
+      () => (stickyOffset(tocOffsetVar) ?? 0) + toolbarHeight,
+      [tocOffsetVar, toolbarHeight]
     );
     /*
       Переход в правке ставит каретку в конец заголовка, как структура документа
@@ -1351,22 +1372,36 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
       };
     }, [throttle, name]);
 
-    useImperativeHandle(
-      ref,
-      () => ({
+    const toolBridge: ToolBridge = {
+      openSearch,
+      // Фокус и каретку не трогаем: команду зовёт код экрана, а не автор в панели.
+      closeSearch: () => closeSearch(false),
+      sourceOpen: () => sourceTextRef.current !== null,
+      jumpToc: (index) => tocJumpRef.current?.(index) ?? false,
+    };
+
+    useImperativeHandle(ref, () => {
+      const methods = createHandleMethods({
         editor,
-        ...createHandleMethods({
-          editor,
-          editable,
-          known: () => knownRef.current,
-          initialDocument: () => initialDocumentRef.current,
-          tables: enabledTools.has("table"),
-          sourceOpen: () => sourceTextRef.current !== null,
-          sourceField: () => sourceFieldRef.current,
-          applySource: () => applySourceRef.current(),
-          rewriteSource,
-          fieldEmpty,
-        }),
+        editable,
+        known: () => knownRef.current,
+        initialDocument: () => initialDocumentRef.current,
+        tables: enabledTools.has("table"),
+        sourceOpen: () => sourceTextRef.current !== null,
+        sourceField: () => sourceFieldRef.current,
+        applySource: () => applySourceRef.current(),
+        rewriteSource,
+        fieldEmpty,
+        commands: (name) => {
+          const descriptor = enabledTools.descriptors.find((entry) => entry.name === name);
+          return editor && !editor.isDestroyed && descriptor?.commands
+            ? descriptor.commands({ editor, bridge: toolBridge })
+            : null;
+        },
+      });
+      return {
+        editor,
+        ...methods,
         getHTML: () => {
           applySourceRef.current();
           return editor ? serialize(editor) : knownRef.current;
@@ -1400,7 +1435,12 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
           rewriteSource(editor);
           return true;
         },
-        openSearch: (options) => void openSearchRef.current(options?.replace ?? false),
+        openSearch: (options) => {
+          devWarn(
+            'RichTextEditor: handle.openSearch() is deprecated; use handle.tool("search")?.open() instead'
+          );
+          methods.tool("search")?.open(options);
+        },
         clear: () => {
           if (!editor) return;
           throttle.cancel();
@@ -1413,11 +1453,20 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
           emit("");
           rewriteSource(editor);
         },
-      }),
-      [editor, editable, throttle]
+      };
+    }, [editor, editable, throttle]);
+    /*
+      Хуки `useRichTextEditorState` и `useRichTextToolState` не видят смену
+      движка у `ref` сами — сообщаем. Тем же сообщением идут сигналы кита для
+      Состояния Инструмента: набор Инструментов и открытость панели Поиска.
+    */
+    const searchOpen = searchPanel !== null;
+    useEffect(
+      () => publishToolSignals(ref, { tools: enabledTools, searchOpen }),
+      [ref, editor, enabledTools, searchOpen]
     );
-    // Хук `useRichTextEditorState` не видит смену движка у `ref` сам — сообщаем.
-    useEffect(() => notifyHandleEditor(ref), [ref, editor]);
+    // Размонтирование (и смена `ref`) забирает сигналы: хук экрана отдаёт `null`.
+    useEffect(() => () => clearToolSignals(ref), [ref]);
 
     /*
       Готовность (спека, словарь): один раз за монтаж, когда движок создан.
@@ -1588,15 +1637,21 @@ export const RichTextEditor = forwardRef<RichTextEditorHandle, RichTextEditorPro
                   <Suspense fallback={null}>
                     <TocCore
                       target={tocTarget}
+                      offsetVar={tocOptions.offsetVar}
+                      levels={tocOptions.levels}
+                      listWidth={tocOptions.listWidth}
                       stickyTop={tocStickyTop}
                       focusHeading={tocFocusHeading}
                       alignToFirstHeading
+                      onCurrentChange={(tocAt) => publishToolSignals(ref, { tocAt })}
+                      editor={editor}
+                      jumpRef={tocJumpRef}
                       data-toc-gutter=""
                       className="sticky mr-3 shrink-0"
                       style={{
                         top: scrolls
                           ? "0.5rem"
-                          : `calc(var(--topbar-h, 0px) + ${toolbarHeight}px + 0.5rem)`,
+                          : `calc(var(${tocOffsetVar}, 0px) + ${toolbarHeight}px + 0.5rem)`,
                       }}
                     />
                   </Suspense>

package/src/editor/RichTextView.tsx

@@ -31,7 +31,8 @@ export interface RichTextViewProps extends Omit<
   surface?: RichTextSurface;
   /**
    * Свои Инструменты Документа — тот же массив, что у `RichTextEditor` и
-   * `sanitizeRichText`. Просмотр читает из него только Острова своих Блоков
+   * `sanitizeRichText`; Настроенный Инструмент (`tool()`) в нём допустим и
+   * Просмотром игнорируется. Просмотр читает из него только Острова своих Блоков
    * (`blocks[имя].island`): Блок, у которого он есть и который есть в
    * Документе, оживает клиентским компонентом, а серверный HTML Блока виден до
    * загрузки и без JS. Остальное в описании Просмотру не нужно. Без `tools`, и

package/src/editor/core/containers.ts

@@ -2,6 +2,7 @@
 
 import type { Node as PmNode, NodeType, ResolvedPos } from "@tiptap/pm/model";
 import { TextSelection, type Transaction } from "@tiptap/pm/state";
+import { WRAPPER_NODE } from "./nodeNames.js";
 
 /**
  * Общее у контейнерных Блоков — Раскладки (`layout.ts`, ADR-0056) и Обёртки
@@ -13,12 +14,13 @@ import { TextSelection, type Transaction } from "@tiptap/pm/state";
  * арифметика позиций не разъезжались молча.
  */
 
-/**
- * Имя узла Обёртки в Схеме движка. Живёт здесь, а не в `wrapper.ts`: оно же
- * входит в общий список ниже, а `wrapper.ts` импортирует этот модуль —
- * определение там дало бы цикл импортов. `wrapper.ts` его реэкспортирует.
- */
-export const WRAPPER_NODE = "wrapper";
+/*
+  Имя узла Обёртки живёт в `nodeNames.ts`, без Tiptap: его читает и Оглавление.
+  Не в `wrapper.ts`: оно же входит в общий список ниже, а `wrapper.ts`
+  импортирует этот модуль — определение там дало бы цикл импортов. `wrapper.ts`
+  его реэкспортирует.
+*/
+export { WRAPPER_NODE };
 
 /**
  * Узлы, внутри которых контейнерного Блока нет ни одного: Обёртка, цитата,

package/src/editor/core/customTool.ts

@@ -3,6 +3,8 @@ import type { Mark } from "@tiptap/pm/model";
 import type { EditorState } from "@tiptap/pm/state";
 import type { ComponentType, ReactNode } from "react";
 import type { IconProps } from "../../icons.js";
+import type { ToolDefinition } from "./toolDefinition.js";
+import type { ConfiguredTool } from "./toolOptions.js";
 import type { Tool as ToolName } from "./tools.js";
 
 /*
@@ -428,8 +430,12 @@ export type CustomToolButton = CustomToolButtonFields &
       }
   );
 
-/** Элемент `tools`: имя Инструмента кита или описание своего. */
-export type ToolEntry = ToolName | CustomTool;
+/**
+ * Элемент `tools`: имя Инструмента кита, Настроенный Инструмент (`tool()`),
+ * определение своего Инструмента (`defineTool()`) или описание своего
+ * Инструмента обычным объектом.
+ */
+export type ToolEntry = ToolName | ConfiguredTool<string> | ToolDefinition | CustomTool;
 
 /**
  * Годится ли значение атрибута по его виду (`CustomAttribute`). Живёт в

package/src/editor/core/customToolEngine.ts

@@ -34,6 +34,7 @@ import {
   type ToolLabel,
   type ToolList,
 } from "./toolDescriptor.js";
+import { resolveDefinition, type ToolDefinition } from "./toolDefinition.js";
 import { markdownFallback } from "./customMarkdown.js";
 import { CUSTOM_ATTRIBUTE_NAME, CUSTOM_NAME, customElement } from "./schema.js";
 import { loaded } from "./toolLoader.js";
@@ -237,6 +238,22 @@ export function describeCustomTool(tool: CustomTool): ToolDescriptor {
   };
 }
 
+/**
+ * Внутреннее описание Инструмента из определения (`defineTool`): тело из
+ * `create` и имя определения собираются в обычный `CustomTool` и идут тем же
+ * путём, а Опции этого Редактора — умолчания, слитые с `tool()`, — достаются
+ * `create`, `state` и `commands`.
+ */
+export function describeDefinition(definition: ToolDefinition, given: object = {}): ToolDescriptor {
+  const { options, tool } = resolveDefinition(definition, given);
+  return {
+    ...describeCustomTool(tool),
+    options,
+    state: definition.state && ((editor) => definition.state!({ editor, options })),
+    commands: definition.commands && (({ editor }) => definition.commands!({ editor, options })),
+  };
+}
+
 /**
  * Набор движка, который `RichTextEditor` собирает при ошибке набора: движок
  * нужен хуку `useEditor` в любом случае, но наружу он не выходит.
@@ -311,7 +328,7 @@ export interface CustomToolsError {
 }
 
 /**
- * Ошибка сборки набора своих Инструментов или `null` (ADR-0058, п. 1.5, 2.4).
+ * Ошибка сборки набора Инструментов или `null` (ADR-0058, п. 1.5, 2.4).
  *
  * Имя без Префикса потребителя, совпадение имён, Node или Mark Части для
  * движка без правил Схемы (и правило без них), атрибут, которого нет в
@@ -325,6 +342,8 @@ export interface CustomToolsError {
  * Исключение движка — отдельно, в `cause`: текст — ключ «один раз» у `devError`.
  */
 export function customToolsError(tools: ToolList, extensions: Extensions): CustomToolsError | null {
+  // Ошибка, найденная при развороте `tools` (две записи `tool()` с одним именем), идёт тем же путём.
+  if (tools.error) return { message: tools.error };
   const custom = tools.descriptors.flatMap((descriptor) => descriptor.custom ?? []);
   if (custom.length === 0) return null;
   // Имена Инструментов и имена Блоков и Меток — разные пространства: Инструмент

package/src/editor/core/extensions.ts

@@ -268,7 +268,8 @@ export function createEditorExtensions(options: EditorExtensionOptions): Extensi
     (`codeBlockTool.ts`): его расширение здесь, после `ToolbarFocus`, и
     опрашивается раньше.
   */
-  for (const descriptor of described) extensions.push(...(descriptor.engine?.(options) ?? []));
+  for (const descriptor of described)
+    extensions.push(...(descriptor.engine?.(options, descriptor.options) ?? []));
   // Сочетания кнопок описаний вешает кит: поле записи — их единственный источник.
   const buttons = described.flatMap((descriptor) => descriptor.buttons ?? []);
   // Поповер пункта вставки и Действия открывает та же команда, что у кнопки.

package/src/editor/core/handle.ts

@@ -6,8 +6,15 @@ import type { Fragment } from "@tiptap/pm/model";
 import type { Editor } from "@tiptap/react";
 import { textBetween } from "./atomText.js";
 import { isRichTextDocument, type RichTextDocument } from "./jsonDocument.js";
+import type { ToolCommandsOf } from "./toolCommands.js";
+import type { RichTextTools } from "./toolOptions.js";
 
-export { notifyHandleEditor, watchHandleEditor } from "./handleWatchers.js";
+export {
+  clearToolSignals,
+  notifyHandleEditor,
+  publishToolSignals,
+  watchHandleEditor,
+} from "./handleWatchers.js";
 
 /**
  * Плоские методы Хэндла (ADR-0058, раздел 8): то, что экран делает с Редактором
@@ -81,6 +88,19 @@ export interface RichTextEditorHandleMethods {
   canUndo(): boolean;
   /** Есть ли что повторить. Без Инструмента `history` и до монтажа — `false`. */
   canRedo(): boolean;
+  /**
+   * Команды Инструмента: `handle.tool("search")?.open({ query: "TODO" })`,
+   * `handle.tool("toc")?.jumpTo(2)`. Тип Команд выводится из имени по карте
+   * `RichTextTools`. `null`, если Инструмента нет в наборе `tools`, у него нет
+   * Команд или движок ещё не создан, — поэтому Команды выключенного Инструмента
+   * недоступны и в типах (`?.`), и во время работы.
+   *
+   * Каждая Команда возвращает `boolean`: выполнена или нет (HTML-режим, нет
+   * совпадений, нет заголовка, поле нельзя править) — как `insertHTML`. Имя вне
+   * карты (свой Инструмент без типизации) даёт `unknown`.
+   */
+  tool<Name extends keyof RichTextTools>(name: Name): ToolCommandsOf<Name> | null;
+  tool(name: string): unknown;
 }
 
 /** Что Хэндлу нужно от Редактора: движок и то, что знает только он. */
@@ -109,6 +129,8 @@ export interface HandleHost {
   rewriteSource: (editor: Editor) => void;
   /** Пуст ли Документ по правилу кита, с учётом неприменённой правки поля HTML. */
   fieldEmpty: (editor: Editor) => boolean;
+  /** Команды Инструмента набора; `null` — Инструмента или Команд нет (`ToolDescriptor.commands`). */
+  commands: (name: string) => object | null;
 }
 
 /** Тег целиком; комментарий и содержимое `script`/`style`/`template` разбор Схемой не видит. */
@@ -286,5 +308,7 @@ export function createHandleMethods(host: HandleHost): RichTextEditorHandleMetho
     redo: () => history("redo"),
     canUndo: () => available("undo"),
     canRedo: () => available("redo"),
+    // Типы Команд выводятся из карты, а реализация знает только имя.
+    tool: host.commands as RichTextEditorHandleMethods["tool"],
   };
 }

package/src/editor/core/handleWatchers.ts

@@ -1,4 +1,5 @@
 import type { RefObject } from "react";
+import type { ToolList } from "./toolDescriptor.js";
 
 /*
   Хук-селектор не знает, когда у `ref` появится движок: Редактор создаёт его
@@ -25,3 +26,47 @@ export function notifyHandleEditor(ref: unknown): void {
   if (typeof ref !== "object" || ref === null) return;
   watchers.get(ref)?.forEach((listener) => listener());
 }
+
+/**
+ * Сигналы кита для `useRichTextToolState`: то, что меняется не транзакцией
+ * движка, а интерфейсом Инструмента, и поэтому в движке его не прочитать.
+ * Редактор кладёт их по `ref`, как и сообщение о движке, и хук получает
+ * уведомление той же подпиской.
+ */
+export interface ToolSignals {
+  /** Набор Инструментов этого Редактора: есть ли Инструмент и с какими Опциями. */
+  tools?: ToolList;
+  /** Панель Поиска открыта (состояние React в `RichTextEditor`). */
+  searchOpen?: boolean;
+  /** Индекс текущего раздела Оглавления (вычисляет `TocCore` от прокрутки). */
+  tocAt?: number;
+}
+
+const signals = new WeakMap<object, ToolSignals>();
+
+/**
+ * Редактор сообщает сигналы Инструментов: слитые с прежними, подписчикам идёт то
+ * же уведомление, что и о смене движка.
+ */
+export function publishToolSignals(ref: unknown, next: ToolSignals): void {
+  if (typeof ref !== "object" || ref === null) return;
+  signals.set(ref, { ...signals.get(ref), ...next });
+  notifyHandleEditor(ref);
+}
+
+/**
+ * Редактор размонтирован: его сигналы уходят вместе с ним. Иначе они пережили бы
+ * его в таблице по `ref`, и хук отдавал бы снимок уже не существующего Редактора
+ * (а новый Редактор под тем же `ref` начинал бы с чужих сигналов). Подписчики
+ * получают уведомление: компонент, который из-за размонтирования не
+ * перерисовывается сам, узнаёт о нём только так.
+ */
+export function clearToolSignals(ref: unknown): void {
+  if (typeof ref !== "object" || ref === null || !signals.delete(ref)) return;
+  notifyHandleEditor(ref);
+}
+
+/** Сигналы Инструментов Редактора, привязанного к `ref`. */
+export function toolSignals(ref: object): ToolSignals {
+  return signals.get(ref) ?? {};
+}

package/src/editor/core/nodeNames.ts

@@ -0,0 +1,7 @@
+/**
+ * Имена узлов Схемы, которые знает не только движок. Модуль без Tiptap: имя
+ * нужно и Оглавлению (`features/toc`), которому движок в бандл не нужен.
+ */
+
+/** Имя узла Обёртки в Схеме движка (ADR-0057). */
+export const WRAPPER_NODE = "wrapper";

package/src/editor/core/schema.ts

@@ -3,6 +3,7 @@ import { EDITOR_LAYOUTS } from "../features/layout/columnLayouts.js";
 import { CUSTOM_COLOR_STYLE_PATTERN } from "../features/color/customColor.js";
 import { devWarn } from "../../lib/dev-warn.js";
 import type { CustomAttribute, PrefixedName, ToolEntry } from "./customTool.js";
+import { customToolOf } from "./toolDefinition.js";
 import {
   EDITOR_ALIGNMENTS,
   EDITOR_MARKER_NAMES,
@@ -375,8 +376,10 @@ function customAttributes(
 export function richTextSchema(tools: readonly ToolEntry[] = []): RichTextSchema {
   const customBlocks: Record<PrefixedName, RichTextCustomBlockRules> = {};
   const customMarks: Record<PrefixedName, RichTextCustomMarkRules> = {};
-  for (const tool of tools) {
-    if (typeof tool !== "object" || tool === null) continue;
+  for (const entry of tools) {
+    // Строка — имя кита, Настроенный встроенный — его опции: Схемы у них нет.
+    const tool = customToolOf(entry);
+    if (!tool) continue;
     for (const [name, block] of Object.entries(tool.blocks ?? {})) {
       if (!CUSTOM_NAME.test(name)) continue;
       const kind = block.kind === "inline" ? "inline" : "block";

package/src/editor/core/toolCommands.ts

@@ -0,0 +1,85 @@
+import type { RichTextTools, SearchToolOptions } from "./toolOptions.js";
+
+/*
+  Команды Инструмента: типы того, что экран вызывает через `handle.tool(name)`.
+  Модуль серверно-безопасен, как `toolOptions.ts`: одни типы, без Tiptap и React.
+  Реализации встроенных лежат рядом с их описаниями (`searchTool.ts`, `tocTool.ts`).
+*/
+
+/**
+ * Команды Инструмента `search`. Каждая возвращает `boolean`: выполнена или нет
+ * (HTML-режим, нет совпадений, поле нельзя править). Команды ведут себя как
+ * панель «Поиск и замена»: тот же запрос, те же флажки, та же подсветка.
+ * Запрос и флажки живут в движке, поэтому `setQuery`, `next` и `replace` работают
+ * и без открытой панели — на них можно собрать свой интерфейс поиска.
+ */
+export interface SearchToolCommands {
+  /**
+   * Открыть панель — то же, что кнопка «Поиск» и `Mod+F`. `query` сразу ставит
+   * запрос в поле и в подсветку документа; без него запросом становится текст,
+   * выделенный в одном Блоке. `replace` ставит фокус в поле замены. Флажки на
+   * открытой панели не меняются, на закрытой панель стартует с Опций Инструмента.
+   * `false` — в HTML-режиме (Документа на экране нет).
+   */
+  open(options?: { replace?: boolean; query?: string }): boolean;
+  /**
+   * Закрыть панель и убрать подсветку. Фокус и каретка остаются где были:
+   * в отличие от Escape в панели, команда в Документ их не переводит. Панель,
+   * уже закрытая, — не ошибка: подсветка всё равно убирается.
+   */
+  close(): boolean;
+  /**
+   * Задать запрос. Не названные в `flags` флажки (и флажки со значением
+   * `undefined`) берутся из открытой панели, а если её нет — из Опций
+   * Инструмента. Открытая панель показывает новый запрос
+   * и флажки. Непустой запрос прокручивает к первому совпадению после каретки,
+   * как `next` (прокрутка приходит чуть позже). `true` — запрос применён, даже
+   * если совпадений нет (их число — Состояние Инструмента); `false` — в
+   * HTML-режиме.
+   */
+  setQuery(query: string, flags?: Partial<SearchToolOptions>): boolean;
+  /**
+   * Следующее совпадение по кругу, выделяет его и прокручивает к нему ближайшую
+   * прокручиваемую область поля или окно — как панель, даже когда фокус вне
+   * Документа; фокус при этом не забирается. Прокрутка приходит чуть позже
+   * вызова (микрозадачей и кадром): её код грузится при первом вызове. `false` —
+   * совпадений нет.
+   */
+  next(): boolean;
+  /** Предыдущее совпадение по кругу; выделяет и прокручивает, как `next`. `false` — совпадений нет. */
+  previous(): boolean;
+  /**
+   * Заменить текущее совпадение: одна правка, одна отмена. Текущим становится
+   * следующее. `false` — совпадений нет или поле нельзя править.
+   */
+  replace(text: string): boolean;
+  /** Заменить все совпадения: одна правка, одна отмена. Условия — как у `replace`. */
+  replaceAll(text: string): boolean;
+}
+
+/** Команды Инструмента `toc`. */
+export interface TocToolCommands {
+  /**
+   * Перейти к заголовку списка Оглавления — как клик по пункту. Индекс считается
+   * в том же списке, что и пункты: с учётом `levels`, с нуля, пустые заголовки
+   * пропускаются. В правке каретка встаёт в конец заголовка, в `readOnly` фокус
+   * получает сам заголовок; прокрутка ставит его под липкую шапку (`offsetVar`) и
+   * Панель, подсветка заголовка гаснет.
+   *
+   * `false` — нет заголовка с таким индексом, либо Оглавление ещё не готово: его
+   * UI грузится отдельным куском после создания движка, и в HTML-режиме его нет.
+   * Заголовков меньше двух — не причина отказа: полоса не рисуется, но список
+   * есть, и переход работает.
+   */
+  jumpTo(index: number): boolean;
+}
+
+/**
+ * Команды Инструмента по имени из карты `RichTextTools`. Имя вне карты — `unknown`:
+ * типизация добровольна, Инструмент работает и без неё.
+ */
+export type ToolCommandsOf<Name extends string> = Name extends keyof RichTextTools
+  ? RichTextTools[Name] extends { commands: infer Commands }
+    ? Commands
+    : unknown
+  : unknown;