@olddevs/ui 4.4.0 → 4.5.1

package/src/editor/features/builtins.ts

@@ -9,11 +9,14 @@ import type { ShortcutCommand } from "../core/shortcuts.js";
 import { CODE_BLOCK_TOOL } from "./code/codeBlockTool.js";
 import { EMOJI_TOOL } from "./emoji/emojiTool.js";
 import { LINK_TOOL } from "./link/linkTool.js";
-import type { CustomTool, ToolEntry } from "../core/customTool.js";
-import { describeCustomTool } from "../core/customToolEngine.js";
+import { devError } from "../../lib/dev-warn.js";
+import type { ToolEntry } from "../core/customTool.js";
+import { describeCustomTool, describeDefinition } from "../core/customToolEngine.js";
 import { toolList, type ToolDescriptor, type ToolList } from "../core/toolDescriptor.js";
+import { isConfiguredTool, mergeOptions, type ConfiguredTool } from "../core/toolOptions.js";
 import { SEARCH_TOOL } from "./search/searchTool.js";
 import { TABLE_TOOL } from "./table/tableTool.js";
+import { TOC_TOOL } from "./toc/tocTool.js";
 import { resolveTools, TOOLS, type RichTextEditorPreset, type Tool } from "../core/tools.js";
 import { unwrapWrapperAt, WRAPPER_NODE } from "./wrapper/wrapper.js";
 
@@ -51,6 +54,8 @@ const BLOCKQUOTE_ITEMS: readonly InsertItem[] = [
  */
 export const BUILTIN_TOOLS: Partial<Record<Tool, ToolDescriptor>> = {
   search: SEARCH_TOOL,
+  // Оглавление несёт только Опции: полоса и список рисуются в `RichTextEditor`.
+  toc: TOC_TOOL,
   /*
     Обёртка переехала только Действием над Блоком, поэтому
     `legacy`: её узел, вставка и сочетания остаются в старых реестрах. «Тон ›» —
@@ -115,31 +120,85 @@ export const BUILTIN_TOOLS: Partial<Record<Tool, ToolDescriptor>> = {
   table: TABLE_TOOL,
 };
 
+/**
+ * Опции Инструмента для Редактора: умолчания описания, поверх них — те, что
+ * передал `tool()`. Значение, не прошедшее проверку, и опция, которой у
+ * Инструмента нет (проверки для неё тоже нет), отбрасываются, в разработке —
+ * одним `console.error` на Инструмент: потребитель на JS обходит типы карты, а
+ * поле от этого не падает.
+ */
+function resolveOptions(
+  descriptor: ToolDescriptor,
+  configured: ConfiguredTool | undefined
+): ToolDescriptor {
+  const { defaults, checks } = descriptor;
+  const given = Object.entries(configured?.options ?? {}).filter(
+    ([, value]) => value !== undefined
+  );
+  const valid = given.filter(([key, value]) => checks?.[key]?.(value));
+  if (valid.length < given.length) {
+    devError(
+      `RichTextEditor: tool "${descriptor.name}": ignored invalid options: ` +
+        given
+          .filter((entry) => !valid.includes(entry))
+          .map(([key]) => key)
+          .join(", ")
+    );
+  }
+  return defaults
+    ? { ...descriptor, options: mergeOptions(defaults, Object.fromEntries(valid)) }
+    : descriptor;
+}
+
 /**
  * Развернуть `tools` (или `preset`) в один список описаний.
  *
  * Имена — те же, что у `resolveTools`: точный `tools` или пресет, неизвестная
- * строка отбрасывается молча. Порядок встроенных — порядок кита (`TOOLS`), а
- * не `tools`: место встроенного на поверхности решает кит. Свои Инструменты
- * (описания в `tools`) идут следом, в порядке `tools` (ADR-0058, п. 5.3);
- * набор имён (`Set`) — только имена кита.
+ * строка отбрасывается молча. Запись `tool()` включает Инструмент так же, как
+ * его имя, а если в `tools` есть и имя (из пресета), и запись, побеждает
+ * Настроенный Инструмент; две записи с одним именем — ошибка набора
+ * (`ToolList.error`). Порядок встроенных — порядок кита (`TOOLS`), а не
+ * `tools`: место встроенного на поверхности решает кит, и Настроенный стоит
+ * там же, где голое имя. Свои Инструменты (описания в `tools`) идут следом, в
+ * порядке `tools` (ADR-0058, п. 5.3); набор имён (`Set`) — только имена кита.
+ *
+ * Опции Инструментов читаются здесь, один раз, вместе с набором.
  */
 export function expandTools(
   preset: RichTextEditorPreset,
   tools: readonly ToolEntry[] | undefined
 ): ToolList {
+  // Настроенные встроенные: запись с определением настраивает свой Инструмент, она ниже.
+  const configured = (tools ?? []).filter(
+    (entry): entry is ConfiguredTool => isConfiguredTool(entry) && !entry.definition
+  );
+  const twice = configured.find((entry, index) =>
+    configured.some((e, i) => i < index && e.name === entry.name)
+  );
   const names = resolveTools(
     preset,
-    tools?.filter((tool): tool is Tool => typeof tool === "string")
+    tools && [
+      ...tools.filter((entry) => typeof entry === "string"),
+      ...configured.map((entry) => entry.name),
+    ]
   );
-  const builtin = TOOLS.filter((name) => names.has(name)).map(
-    (name): ToolDescriptor => BUILTIN_TOOLS[name] ?? { name, legacy: true }
+  const builtin = TOOLS.filter((name) => names.has(name)).map((name) =>
+    resolveOptions(
+      BUILTIN_TOOLS[name] ?? { name, legacy: true },
+      configured.find((entry) => entry.name === name)
+    )
   );
-  const custom = (tools ?? [])
-    .filter((tool): tool is CustomTool => typeof tool === "object" && tool !== null)
-    .map(describeCustomTool);
+  // Свои: определение (с `tool()` и без) и обычное описание; уникальность имени проверяет набор.
+  const custom = (tools ?? []).flatMap((entry) => {
+    if (typeof entry !== "object" || entry === null) return [];
+    if (isConfiguredTool(entry)) {
+      return entry.definition ? describeDefinition(entry.definition, entry.options) : [];
+    }
+    return "defined" in entry ? describeDefinition(entry) : describeCustomTool(entry);
+  });
   return toolList(
     builtin.map((descriptor) => descriptor.name as Tool),
-    [...builtin, ...custom]
+    [...builtin, ...custom],
+    twice && `tool "${twice.name}": two tool() entries share this name`
   );
 }

package/src/editor/features/search/SearchPanel.tsx

@@ -12,9 +12,12 @@ import { useMessages } from "../../../i18n/useMessages.js";
 import { cn } from "../../../lib/cn.js";
 import { GLASS_PANEL_CLASS } from "../../styles/glass.js";
 import type { SearchOptions } from "./searchMatch.js";
-import { revealCurrentMatch } from "./revealMatch.js";
+import { cancelRevealMatch, registerSearchOverlays, scheduleRevealMatch } from "./revealMatch.js";
 import { searchState } from "./searchPlugin.js";
 
+const NO_OPTIONS: SearchOptions = { matchCase: false, wholeWord: false, regex: false };
+const FLAGS = ["matchCase", "wholeWord", "regex"] as const;
+
 export interface SearchPanelProps {
   editor: Editor;
   /**
@@ -27,8 +30,6 @@ export interface SearchPanelProps {
   className?: string;
 }
 
-const NO_OPTIONS: SearchOptions = { matchCase: false, wholeWord: false, regex: false };
-
 /**
  * Панель «Поиск и замена»: немодальная, в углу поля. Состояние
  * поиска — в плагине движка (`searchPlugin.ts`); панель держит только то, что
@@ -44,9 +45,14 @@ const NO_OPTIONS: SearchOptions = { matchCase: false, wholeWord: false, regex: f
  */
 export function SearchPanel({ editor, focus, onClose, className }: SearchPanelProps) {
   const messages = useMessages().editor;
-  const [query, setQuery] = useState(focus.query);
+  /*
+    Запрос и флажки панели — зеркало поиска в движке: на открытии она берёт
+    то, что в нём уже есть (стартовые флажки — Опции Инструмента, запрос — если
+    экран задал его командой), а позже подхватывает такие же правки снаружи.
+  */
+  const [query, setQuery] = useState(() => focus.query || searchState(editor.state)?.query || "");
   const [replacement, setReplacement] = useState("");
-  const [options, setOptions] = useState(NO_OPTIONS);
+  const [options, setOptions] = useState(() => searchState(editor.state)?.options ?? NO_OPTIONS);
   const searchRef = useRef<HTMLInputElement>(null);
   const replaceRef = useRef<HTMLInputElement>(null);
   const panelRef = useRef<HTMLElement>(null);
@@ -60,6 +66,8 @@ export function SearchPanel({ editor, focus, onClose, className }: SearchPanelPr
         current: state?.current ?? -1,
         total: state?.total ?? 0,
         error: state?.error,
+        engineQuery: state?.query ?? "",
+        engineOptions: state?.options ?? NO_OPTIONS,
         editable: current.isEditable,
       };
     },
@@ -91,15 +99,18 @@ export function SearchPanel({ editor, focus, onClose, className }: SearchPanelPr
     разложена и её край можно учесть. Панель и её липкий родитель (Панель
     Редактора) лежат поверх Документа: совпадение под ними не считается видимым.
   */
-  const revealFrame = useRef(0);
-  const reveal = () => {
-    cancelAnimationFrame(revealFrame.current);
-    revealFrame.current = requestAnimationFrame(() => {
-      const panel = panelRef.current;
-      revealCurrentMatch(editor.view.dom, [panel, panel?.parentElement]);
-    });
-  };
-  useEffect(() => () => cancelAnimationFrame(revealFrame.current), []);
+  const reveal = () => scheduleRevealMatch(editor);
+  // Команды Инструмента показывают совпадение тем же путём и обходят эту же панель.
+  useEffect(() => {
+    const unregister = registerSearchOverlays(editor, () => [
+      panelRef.current,
+      panelRef.current?.parentElement,
+    ]);
+    return () => {
+      unregister();
+      cancelRevealMatch(editor);
+    };
+  }, [editor]);
 
   useEffect(() => {
     editor.commands.setSearch(query, options);
@@ -109,6 +120,19 @@ export function SearchPanel({ editor, focus, onClose, className }: SearchPanelPr
     // `reveal` — новая на каждый рендер, но читает только рефы и `editor`.
   }, [editor, query, options]);
 
+  /*
+    Запрос и флажки, заданные в движке мимо панели (команда `setQuery`), встают
+    в поля. Сверка с движком «вживую», а не по снимку `search`: эффект выше уже
+    протолкнул набранное в этом же коммите, и устаревший снимок откатил бы его.
+  */
+  useEffect(() => {
+    const live = searchState(editor.state);
+    if (!live) return;
+    if (live.query !== query) setQuery(live.query);
+    if (FLAGS.some((flag) => live.options[flag] !== options[flag])) setOptions(live.options);
+    // Только на смену поиска в движке; набор в полях уходит в движок эффектом выше.
+  }, [search.engineQuery, search.engineOptions]);
+
   const step = (direction: 1 | -1) => {
     editor.commands.searchStep(direction);
     reveal();

package/src/editor/features/search/revealMatch.ts

@@ -1,5 +1,7 @@
 "use client";
 
+import type { Editor } from "@tiptap/core";
+
 interface Band {
   top: number;
   bottom: number;
@@ -67,3 +69,46 @@ export function revealCurrentMatch(
     delta -= scroller.scrollTop - before;
   }
 }
+
+/** Что лежит поверх Документа у каждого поля: панель поиска, пока она открыта. */
+const overlayProviders = new WeakMap<Editor, () => readonly (Element | null | undefined)[]>();
+const frames = new WeakMap<Editor, number>();
+
+/**
+ * Панель поиска сообщает, что лежит поверх Документа, пока открыта. Команды
+ * Инструмента (`next`, `previous`, `setQuery`) живут вне панели, но должны
+ * обходить её так же. Возвращает снятие регистрации.
+ */
+export function registerSearchOverlays(
+  editor: Editor,
+  overlays: () => readonly (Element | null | undefined)[]
+): () => void {
+  overlayProviders.set(editor, overlays);
+  return () => {
+    if (overlayProviders.get(editor) === overlays) overlayProviders.delete(editor);
+  };
+}
+
+/**
+ * Показать текущее совпадение кадром позже, когда панель уже разложена. Вызовы
+ * одного поля в пределах кадра сливаются в одну прокрутку: панель и команда
+ * Инструмента, сработавшие на один переход, не прокручивают дважды. Фокус не
+ * трогает.
+ */
+export function scheduleRevealMatch(editor: Editor): void {
+  cancelAnimationFrame(frames.get(editor) ?? 0);
+  frames.set(
+    editor,
+    requestAnimationFrame(() => {
+      frames.delete(editor);
+      if (editor.isDestroyed) return;
+      revealCurrentMatch(editor.view.dom, overlayProviders.get(editor)?.() ?? []);
+    })
+  );
+}
+
+/** Отменить отложенную прокрутку (панель закрылась или поле разобрано). */
+export function cancelRevealMatch(editor: Editor): void {
+  cancelAnimationFrame(frames.get(editor) ?? 0);
+  frames.delete(editor);
+}

package/src/editor/features/search/searchPlugin.ts

@@ -23,7 +23,7 @@ interface SearchPluginState {
 }
 
 type SearchMeta =
-  | { type: "set"; query: string; options: SearchOptions }
+  | { type: "set"; query: string; options?: Partial<SearchOptions> }
   | { type: "select"; index: number }
   | { type: "clear" };
 
@@ -85,17 +85,39 @@ function build(
   };
 }
 
-function searchPlugin() {
+/**
+ * Флажки после `setSearch`: названные в `named` заменяют прежние, остальные
+ * остаются. Ключ со значением `undefined` — не названный: обычное слияние
+ * `{ ...a, ...b }` стёрло бы им флажок, а вызов `setQuery(q, { matchCase: value })`
+ * с необязательным значением экрана не просит ничего менять.
+ */
+function withNamedFlags(current: SearchOptions, named: Partial<SearchOptions> = {}): SearchOptions {
+  const next = { ...current };
+  for (const key of Object.keys(named) as (keyof SearchOptions)[]) {
+    const value = named[key];
+    if (value !== undefined) next[key] = value;
+  }
+  return next;
+}
+
+/**
+ * @param flags флажки без запроса: до первого `setSearch` и после `clearSearch`
+ * (Опции Инструмента). Поиск, который идёт, держит свои.
+ */
+function searchPlugin(flags: SearchOptions) {
   return new Plugin<SearchPluginState>({
     key: SEARCH_KEY,
     state: {
-      init: (_, state) => build(state, "", EMPTY_OPTIONS, () => -1),
+      init: (_, state) => build(state, "", flags, () => -1),
       apply(tr: Transaction, previous, _old, state) {
         const meta = tr.getMeta(SEARCH_KEY) as SearchMeta | undefined;
-        if (meta?.type === "clear") return build(state, "", previous.options, () => -1);
+        if (meta?.type === "clear") return build(state, "", flags, () => -1);
         if (meta?.type === "set") {
-          return build(state, meta.query, meta.options, (matches) =>
-            indexFrom(matches, state.selection.from)
+          return build(
+            state,
+            meta.query,
+            withNamedFlags(previous.options, meta.options),
+            (matches) => indexFrom(matches, state.selection.from)
           );
         }
         if (meta?.type === "select") {
@@ -151,8 +173,11 @@ function replaceRange(tr: Transaction, { from, to }: SearchMatch, text: string)
 declare module "@tiptap/core" {
   interface Commands<ReturnType> {
     search: {
-      /** Новый запрос или опции: совпадения пересчитываются, текущее — первое после каретки. */
-      setSearch: (query: string, options: SearchOptions) => ReturnType;
+      /**
+       * Новый запрос или флажки: совпадения пересчитываются, текущее — первое после
+       * каретки. Не названные флажки остаются как были.
+       */
+      setSearch: (query: string, options?: Partial<SearchOptions>) => ReturnType;
       /**
        * Следующее (`1`) или предыдущее (`-1`) совпадение по кругу; выделяет его.
        * Прокрутка ProseMirror срабатывает, только когда фокус в Документе; из
@@ -163,13 +188,15 @@ declare module "@tiptap/core" {
       replaceMatch: (replacement: string) => ReturnType;
       /** Заменить все совпадения — одна транзакция, одна отмена. */
       replaceAllMatches: (replacement: string) => ReturnType;
-      /** Убрать запрос и подсветку. */
+      /** Убрать запрос и подсветку; флажки вернутся к Опциям Инструмента. */
       clearSearch: () => ReturnType;
     };
   }
 }
 
 export interface SearchExtensionOptions {
+  /** Флажки, с которых стартует поиск и к которым он возвращается: Опции Инструмента. */
+  flags: SearchOptions;
   /**
    * Открыть панель поиска (`replace` — с фокусом в поле замены). Панель держит
    * `RichTextEditor`; `false` — панели нет, и `Mod+F` уходит браузеру.
@@ -186,8 +213,10 @@ export interface SearchExtensionOptions {
  */
 export const SearchExtension = Extension.create<SearchExtensionOptions>({
   name: "search",
-  addOptions: () => ({ open: () => false }),
-  addProseMirrorPlugins: () => [searchPlugin()],
+  addOptions: () => ({ open: () => false, flags: EMPTY_OPTIONS }),
+  addProseMirrorPlugins() {
+    return [searchPlugin(this.options.flags)];
+  },
   addKeyboardShortcuts() {
     return {
       "Mod-f": () => this.options.open(false),

package/src/editor/features/search/searchSnapshot.ts

@@ -0,0 +1,29 @@
+"use client";
+
+import type { Editor } from "@tiptap/core";
+import type { SearchToolState } from "../../core/toolState.js";
+import { searchState } from "./searchPlugin.js";
+
+/**
+ * Снимок Состояния `search` для `useRichTextToolState`: открытые поля
+ * `searchState` плагина плюс открытость панели, без позиций совпадений. Лежит
+ * отдельно от `searchPlugin.ts`: вычисление нужно только хуку и не должно
+ * попадать в статический граф Редактора.
+ *
+ * Флажки — из плагина и при закрытой панели: их держит движок, а не панель.
+ * Закрытие возвращает их к стартовым из Опций, а `setQuery` без панели ставит
+ * свои. `null` — плагина нет (Инструмент `search` не вошёл в движок).
+ */
+export function searchSnapshot(editor: Editor, open: boolean): SearchToolState | null {
+  const state = searchState(editor.state);
+  if (!state) return null;
+  const { matchCase, wholeWord, regex } = state.options;
+  return {
+    open,
+    query: state.query,
+    flags: { matchCase, wholeWord, regex },
+    total: state.total,
+    current: state.current,
+    error: state.error ?? null,
+  };
+}

package/src/editor/features/search/searchTool.ts

@@ -1,6 +1,9 @@
 "use client";
 
+import type { Editor } from "@tiptap/core";
 import type { ToolDescriptor } from "../../core/toolDescriptor.js";
+import type { SearchToolCommands } from "../../core/toolCommands.js";
+import type { SearchToolOptions } from "../../core/toolOptions.js";
 import { SearchExtension } from "./searchPlugin.js";
 
 /**
@@ -14,9 +17,56 @@ import { SearchExtension } from "./searchPlugin.js";
 /** Сочетание кнопки «Поиск»: строка справочника и подсказка кнопки — из одной записи. */
 export const SEARCH_KEYS = ["mod", "F"] as const;
 
+/** Стартовые флажки панели: все выключены. */
+export const SEARCH_DEFAULTS: SearchToolOptions = {
+  matchCase: false,
+  wholeWord: false,
+  regex: false,
+};
+
+const isFlag = (value: unknown) => typeof value === "boolean";
+
+/*
+  Показать текущее совпадение после команды. ProseMirror прокручивает только
+  при фокусе в Документе, а команды зовут и с кнопки экрана. Код прокрутки
+  (`revealMatch.ts`) лежит в ленивом куске панели и в старт не входит:
+  грузится при первом вызове, поэтому прокрутка приходит на микрозадачу и кадр
+  позже. Открытая панель уже подгрузила его, и её переходы сливаются с этим
+  вызовом в одну прокрутку.
+*/
+const reveal = (editor: Editor, done: boolean) => {
+  if (done) void import("./revealMatch.js").then((module) => module.scheduleRevealMatch(editor));
+  return done;
+};
+
 export const SEARCH_TOOL: ToolDescriptor = {
   name: "search",
-  engine: (context) => [SearchExtension.configure({ open: context.openSearch ?? (() => false) })],
+  defaults: SEARCH_DEFAULTS,
+  checks: { matchCase: isFlag, wholeWord: isFlag, regex: isFlag },
+  /*
+    Запрос, переходы и замена — команды движка, как у панели; панель и HTML-режим
+    знает мост. `editor.commands` читается при каждом вызове, а не один раз:
+    Tiptap собирает его вместе с транзакцией, и сохранённый набор отправил бы
+    устаревшую.
+  */
+  commands: ({ editor, bridge }): SearchToolCommands => ({
+    open: (options) => bridge.openSearch(options?.replace === true, options?.query),
+    close: bridge.closeSearch,
+    setQuery: (query, flags) =>
+      !bridge.sourceOpen() &&
+      editor.commands.setSearch(query, flags) &&
+      (reveal(editor, query !== ""), true),
+    next: () => reveal(editor, editor.commands.searchStep(1)),
+    previous: () => reveal(editor, editor.commands.searchStep(-1)),
+    replace: (text) => editor.commands.replaceMatch(text),
+    replaceAll: (text) => editor.commands.replaceAllMatches(text),
+  }),
+  engine: (context, options) => [
+    SearchExtension.configure({
+      open: context.openSearch ?? (() => false),
+      flags: options as SearchToolOptions,
+    }),
+  ],
   shortcuts: [
     { id: "search", group: "search", tool: "search", keys: SEARCH_KEYS, label: (m) => m.search },
     {