@olddevs/ui 0.0.0-stage → 4.0.0

package/src/editor/core/slashCommand.ts

@@ -0,0 +1,143 @@
+"use client";
+
+import { Extension, type Editor, type Range } from "@tiptap/core";
+import { PluginKey } from "@tiptap/pm/state";
+import { exitSuggestion, Suggestion } from "@tiptap/suggestion";
+
+/** Ключ плагина: по нему меню закрывает сессию снаружи (`closeSlashMenu`). */
+const SLASH_KEY = new PluginKey("olddevsSlashMenu");
+
+/**
+ * Ключ плагина своего триггера — свой на каждый символ (ADR-0064): плагинам
+ * `@tiptap/suggestion` в одном состоянии нужны разные ключи, а сессию
+ * закрывают снаружи по тому же ключу. Один ключ на символ на весь модуль:
+ * ключ — идентификатор, а не состояние, и разные Редакторы делят его без вреда.
+ */
+const TRIGGER_KEYS = new Map<string, PluginKey>([["/", SLASH_KEY]]);
+
+function triggerKey(char: string): PluginKey {
+  let key = TRIGGER_KEYS.get(char);
+  if (!key) {
+    key = new PluginKey(`olddevsTrigger:${char}`);
+    TRIGGER_KEYS.set(char, key);
+  }
+  return key;
+}
+
+/** Сессия символа-триггера: что набрано, где и как найти курсор на экране. */
+export interface SlashSession {
+  /** Набранное после символа, без него самого. */
+  query: string;
+  /** Диапазон `символ+запрос` в документе — его заменяет выбранный пункт. */
+  range: Range;
+  /** Прямоугольник набранного на экране — якорь списка. */
+  rect: () => DOMRect | null;
+}
+
+/**
+ * Мост между плагином и React. Расширение живёт столько же, сколько движок,
+ * а меню — компонент, поэтому мост — объект с подменяемыми полями, а не
+ * колбэки в опциях: пересоздавать движок ради нового обработчика нельзя.
+ */
+export interface SlashBridge {
+  open: (session: SlashSession) => void;
+  close: () => void;
+  /** Клавиша при открытом меню; `true` — меню её съело, движку она не нужна. */
+  keyDown: (event: KeyboardEvent) => boolean;
+}
+
+/** Закрыть сессию `/`, оставив набранное в тексте (Escape, щелчок мимо). */
+export function closeSlashMenu(view: Parameters<typeof exitSuggestion>[0]): void {
+  exitSuggestion(view, SLASH_KEY);
+}
+
+/** Закрыть сессию своего триггера `char`, оставив набранное в тексте. */
+export function closeTrigger(view: Parameters<typeof exitSuggestion>[0], char: string): void {
+  exitSuggestion(view, triggerKey(char));
+}
+
+/**
+ * Плагин символа-триггера: общая механика «/» и своих символов. Сопоставление
+ * — `@tiptap/suggestion`: символ в начале Блока или после пробела, запрос — до
+ * пробела. Внутри слова (`и/или`, `a@b.com`) список молчит: перед символом нет
+ * разрешённого префикса. Неразрывный пробел — тоже пробел: браузер ставит его
+ * в `contenteditable` на месте конечного.
+ *
+ * В блоке кода и в строчном коде список не открывается: там символ — это пути,
+ * комментарии и деление, а не команда.
+ *
+ * Escape до плагина обычно не доходит: открытый список — слой Radix, и стек
+ * слоёв забирает Escape раньше движка (`SlashMenu`). Ветка плагина остаётся
+ * на случай, когда списка на экране нет, — сессия тогда закрывается так же.
+ */
+function triggerPlugin(editor: Editor, char: string, bridge: SlashBridge) {
+  const open = (props: {
+    query: string;
+    range: Range;
+    clientRect?: (() => DOMRect | null) | null;
+  }) =>
+    bridge.open({
+      query: props.query,
+      range: props.range,
+      rect: () => props.clientRect?.() ?? null,
+    });
+  return Suggestion({
+    editor,
+    pluginKey: triggerKey(char),
+    char,
+    allowedPrefixes: [" ", "\u00a0"],
+    allow: ({ state, range }) => {
+      const $from = state.doc.resolve(range.from);
+      if ($from.parent.type.spec.code) return false;
+      return !$from.marks().some((mark) => mark.type.spec.code);
+    },
+    render: () => ({
+      onStart: open,
+      onUpdate: open,
+      onExit: () => bridge.close(),
+      onKeyDown: ({ event }) => (event.key === "Escape" ? false : bridge.keyDown(event)),
+    }),
+  });
+}
+
+/**
+ * Открытие Меню вставки по `/`: правила символа-триггера (`triggerPlugin`).
+ */
+export const SlashCommand = Extension.create<{ bridge: SlashBridge | null }>({
+  name: "slashCommand",
+
+  addOptions() {
+    return { bridge: null };
+  },
+
+  addProseMirrorPlugins() {
+    const bridge = this.options.bridge;
+    if (!bridge) return [];
+    return [triggerPlugin(this.editor, "/", bridge)];
+  },
+});
+
+/** Символ своего триггера и мост его списка. */
+export interface TriggerBinding {
+  char: string;
+  bridge: SlashBridge;
+}
+
+/**
+ * Свои символы-триггеры Инструментов (ADR-0064): по плагину на символ, у
+ * каждого свой ключ. Символ проверяет набор Инструментов (`customToolsError`),
+ * здесь он уже годный и уникальный.
+ */
+export const TriggerCommand = Extension.create<{ triggers: readonly TriggerBinding[] }>({
+  name: "triggerCommand",
+
+  addOptions() {
+    return { triggers: [] };
+  },
+
+  addProseMirrorPlugins() {
+    return this.options.triggers.map(({ char, bridge }) =>
+      triggerPlugin(this.editor, char, bridge)
+    );
+  },
+});

package/src/editor/core/sourceFormat.ts

@@ -0,0 +1,194 @@
+/**
+ * HTML Документа → читаемый текст для HTML-режима Редактора.
+ *
+ * ПРАВИЛО ОДНО И ПО СТРУКТУРЕ, А НЕ ПО СПИСКУ БЛОКОВ. Элемент, среди детей
+ * которого есть не-строчный элемент и нет текста, раскладывается: открывающий
+ * тег на своей строке, каждый ребёнок — на своей строке с отступом в два
+ * пробела, закрывающий тег — на своей. Остальное (абзац, заголовок, подпись,
+ * `pre`) остаётся одной строкой, как было в HTML. Так верхний уровень,
+ * пункты списков, строки и ячейки таблиц, колонки Раскладки и части `figure`
+ * раскладываются без перечня, и следующий контейнер Блоков (Обёртка,
+ * `div data-block`) — тоже, без правки этого модуля.
+ *
+ * «Строчный» — содержимое фразы по HTML (`strong`, `a`, `img`, `br`…): этот
+ * список задаёт язык разметки, а не Схема Редактора, и с новыми Блоками не
+ * меняется.
+ *
+ * БЕЗ ПОТЕРЬ. Пробелы и переводы строк добавляются только между детьми
+ * раскладываемого элемента — там, где текста нет и разбор Схемой пробелы
+ * пропускает. Содержимое строки берётся из исходной строки как есть, `pre` не
+ * трогается вовсе. Поэтому разбор результата Схемой даёт тот же Документ, что
+ * исходный HTML. На разметке, которую разбор не понял (незакрытый тег —
+ * не наш сериализатор), функция возвращает строку без изменений: лучше
+ * неотформатированный текст, чем изменённый.
+ *
+ * Пустой Документ — пустая строка (его HTML уже `""`).
+ *
+ * Модуль серверно-безопасен: строки, без DOM, без React и без движка.
+ */
+export function formatSourceHtml(html: string): string {
+  const root = parse(html);
+  if (!root || !expands(html, root)) return html;
+  return root.children
+    .filter((child) => !isBlank(html, child))
+    .map((child) => render(html, child, ""))
+    .join("\n");
+}
+
+/** Элементы без закрывающего тега (HTML, «void elements»). Списки — строкой: в сборке короче. */
+const VOID = new Set("area base br col embed hr img input link meta source track wbr".split(" "));
+
+/** Содержимое фразы (HTML, «phrasing content»): такой ребёнок не делает родителя контейнером. */
+const PHRASING = new Set(
+  (
+    "a abbr b bdi bdo br button cite code data del dfn em i img input ins kbd label mark q s " +
+    "samp small span strong sub sup time u var wbr"
+  ).split(" ")
+);
+
+/** Содержимое как есть: внутри пробелы — часть текста. */
+const VERBATIM = new Set(["pre", "textarea", "script", "style"]);
+
+interface Text {
+  kind: "text";
+  start: number;
+  end: number;
+}
+
+interface Element {
+  kind: "element";
+  name: string;
+  /** Начало открывающего тега и конец закрывающего (или открывающего у пустого). */
+  start: number;
+  end: number;
+  /** Конец открывающего тега и начало закрывающего. */
+  openEnd: number;
+  closeStart: number;
+  children: Child[];
+}
+
+type Child = Text | Element;
+
+/**
+ * Разбор в дерево позиций. Это не парсер HTML вообще, а разбор того, что
+ * отдаёт сериализатор движка: теги закрыты, атрибуты в кавычках. Комментарии
+ * и всё, что не тег, считаются текстом — их строка не раскладывается.
+ */
+function parse(html: string): Element | null {
+  const root: Element = {
+    kind: "element",
+    name: "#root",
+    start: 0,
+    end: html.length,
+    openEnd: 0,
+    closeStart: html.length,
+    children: [],
+  };
+  const stack: Element[] = [root];
+  const lower = html.toLowerCase();
+  let index = 0;
+  let textStart = -1;
+
+  const closeText = (at: number) => {
+    if (textStart < 0) return;
+    stack[stack.length - 1]!.children.push({ kind: "text", start: textStart, end: at });
+    textStart = -1;
+  };
+
+  while (index < html.length) {
+    const top = stack[stack.length - 1]!;
+    // Внутри `pre` и подобных ищется только свой закрывающий тег.
+    if (VERBATIM.has(top.name)) {
+      const close = lower.indexOf(`</${top.name}`, index);
+      if (close < 0) return null;
+      const closeEnd = html.indexOf(">", close);
+      if (closeEnd < 0) return null;
+      top.closeStart = close;
+      top.end = closeEnd + 1;
+      stack.pop();
+      index = closeEnd + 1;
+      continue;
+    }
+    const tag = html[index] === "<" ? /^<(\/?)([a-zA-Z][^\s/>]*)/.exec(html.slice(index)) : null;
+    if (!tag) {
+      if (textStart < 0) textStart = index;
+      index += 1;
+      continue;
+    }
+    closeText(index);
+    const tagEnd = endOfTag(html, index);
+    if (tagEnd < 0) return null;
+    const name = tag[2]!.toLowerCase();
+    if (tag[1]) {
+      if (top.name !== name) return null;
+      top.closeStart = index;
+      top.end = tagEnd;
+      stack.pop();
+    } else {
+      const element: Element = {
+        kind: "element",
+        name,
+        start: index,
+        end: tagEnd,
+        openEnd: tagEnd,
+        closeStart: tagEnd,
+        children: [],
+      };
+      top.children.push(element);
+      if (!VOID.has(name) && html[tagEnd - 2] !== "/") stack.push(element);
+    }
+    index = tagEnd;
+  }
+  closeText(html.length);
+  return stack.length === 1 ? root : null;
+}
+
+/** Конец тега, начатого в `from`: первая `>` вне кавычек значения атрибута. */
+function endOfTag(html: string, from: number): number {
+  let quote: string | null = null;
+  for (let index = from + 1; index < html.length; index += 1) {
+    const char = html[index];
+    if (quote) {
+      if (char === quote) quote = null;
+    } else if (char === '"' || char === "'") {
+      quote = char;
+    } else if (char === ">") {
+      return index + 1;
+    }
+  }
+  return -1;
+}
+
+/** Пробелы между детьми контейнера: разбор Схемой их пропускает, при раскладке они заменяются отступом. */
+function isBlank(html: string, child: Child): boolean {
+  return child.kind === "text" && html.slice(child.start, child.end).trim() === "";
+}
+
+/** Раскладывается ли элемент: есть не-строчный ребёнок и нет текста. */
+function expands(html: string, element: Element): boolean {
+  if (VERBATIM.has(element.name)) return false;
+  let block = false;
+  for (const child of element.children) {
+    if (child.kind === "text") {
+      if (!isBlank(html, child)) return false;
+    } else if (!PHRASING.has(child.name)) {
+      block = true;
+    }
+  }
+  return block;
+}
+
+function render(html: string, node: Child, indent: string): string {
+  if (node.kind === "text" || !expands(html, node)) {
+    return indent + html.slice(node.start, node.end);
+  }
+  const inner = indent + "  ";
+  const children = node.children
+    .filter((child) => !isBlank(html, child))
+    .map((child) => render(html, child, inner));
+  return [
+    indent + html.slice(node.start, node.openEnd),
+    ...children,
+    indent + html.slice(node.closeStart, node.end),
+  ].join("\n");
+}

package/src/editor/core/toolButtons.ts

@@ -0,0 +1,133 @@
+"use client";
+
+import { Extension, type Editor } from "@tiptap/core";
+import type { ReactNode } from "react";
+import type { KitToolButton, ToolLabel } from "./toolDescriptor.js";
+
+declare module "@tiptap/core" {
+  interface Commands<ReturnType> {
+    toolButtons: {
+      /**
+       * Внутренняя команда кита, не API: открыть поповер записи описания.
+       * Кнопка — у выделения (сочетание, рамка `anchor: "selection"`); пункт
+       * вставки — у каретки; Действие над Блоком — у Блока `block`. В
+       * нередактируемом поле и при невыполненном `can` кнопки — нет.
+       */
+      openToolPopover: (id: string, block?: number) => ReturnType;
+    };
+  }
+}
+
+/** Запись с поповером, кроме кнопки: пункт вставки или Действие над Блоком. */
+export interface ToolPopoverEntry {
+  id: string;
+  label: ToolLabel;
+  popover: ToolPopoverRequest["popover"];
+}
+
+/** Что открыть: рамку держит `RichTextEditor` (`SelectionPopover`). */
+export interface ToolPopoverRequest {
+  /** Подпись записи — имя рамки. */
+  label: ToolLabel;
+  /** Содержимое; `pos` — Блок у поповера или, у каретки, начало выделения. */
+  popover: (props: { editor: Editor; close: () => void; pos: number }) => ReactNode;
+  /** Классы рамки вместо умолчания (`popoverFrame` кнопки кита). */
+  className?: string;
+  /** Позиция Блока: поповер у Блока. Нет — у выделения. */
+  block?: number;
+}
+
+export interface ToolButtonsOptions {
+  /** Кнопки описаний включённых Инструментов — в порядке списка. */
+  buttons: readonly KitToolButton[];
+  /** Пункты вставки и Действия над Блоком с поповером. */
+  entries: readonly ToolPopoverEntry[];
+  /** Открыть поповер у выделения или у Блока: его держит `RichTextEditor`. */
+  openPopover: (request: ToolPopoverRequest) => void;
+}
+
+/** Нажать кнопку можно: поле правится, кнопка видна и доступна. */
+function available(editor: Editor, button: KitToolButton): boolean {
+  return editor.isEditable && (button.isVisible?.(editor) ?? true) && button.can(editor);
+}
+
+const KEY_NAMES: Record<string, string> = {
+  mod: "Mod",
+  alt: "Alt",
+  shift: "Shift",
+  "↑": "ArrowUp",
+  "↓": "ArrowDown",
+};
+
+/**
+ * Сочетание из нотации Панели (`["mod", "K"]`) — в имя клавиши ProseMirror
+ * (`Mod-k`). Буква — строчной: заглавную keymap читает как клавишу с Shift.
+ */
+export function keymapName(keys: readonly string[]): string {
+  return keys
+    .map((key) => KEY_NAMES[key] ?? (/^[A-Z]$/.test(key) ? key.toLowerCase() : key))
+    .join("-");
+}
+
+/**
+ * Часть для движка у кнопок описаний (ADR-0058, п. 5.7): сочетание — поле
+ * записи и единственный его источник, поэтому клавишу вешает кит, а не Часть
+ * для движка Инструмента. `run` выполняется, поповер открывается у выделения.
+ * Недоступная кнопка клавишу не берёт: она идёт дальше, в Документ.
+ */
+export const ToolButtons = Extension.create<ToolButtonsOptions>({
+  name: "toolButtons",
+
+  addOptions: () => ({ buttons: [], entries: [], openPopover: () => {} }),
+
+  addCommands() {
+    return {
+      openToolPopover:
+        (id, block) =>
+        ({ editor, dispatch }) => {
+          const button = this.options.buttons.find((candidate) => candidate.id === id);
+          const entry = this.options.entries.find((candidate) => candidate.id === id);
+          if (!editor.isEditable) return false;
+          if (button ? !button.popover || !available(editor, button) : !entry) return false;
+          // `can()` зовёт команду всухую, без `dispatch`: поповер открывается
+          // только настоящим вызовом.
+          if (!dispatch) return true;
+          if (button?.popover) {
+            const { label, popover, popoverFrame } = button;
+            this.options.openPopover({ label, popover, className: popoverFrame?.className });
+          } else if (entry) {
+            /*
+              Кадром позже: пункт меню зовёт команду после `focus()` в цепочке,
+              а Tiptap возвращает фокус в Документ в следующем кадре, и меню
+              тем временем снимается. Поповер, открытый сразу, потерял бы фокус
+              и закрылся как «фокус ушёл наружу» — как поповер картинки.
+            */
+            requestAnimationFrame(() => {
+              if (!editor.isDestroyed) this.options.openPopover({ ...entry, block });
+            });
+          }
+          return true;
+        },
+    };
+  },
+
+  addKeyboardShortcuts() {
+    return Object.fromEntries(
+      this.options.buttons.flatMap((button) =>
+        button.shortcut
+          ? [
+              [
+                keymapName(button.shortcut),
+                () => {
+                  if (button.popover) return this.editor.commands.openToolPopover(button.id);
+                  if (!available(this.editor, button)) return false;
+                  button.run(this.editor);
+                  return true;
+                },
+              ],
+            ]
+          : []
+      )
+    );
+  },
+});