@olddevs/ui 4.5.1 → 4.6.1

package/src/editor/features/details/details.ts

@@ -0,0 +1,389 @@
+"use client";
+
+import { Details, DetailsContent, DetailsSummary } from "@tiptap/extension-details";
+import { type Editor, type Extensions } from "@tiptap/core";
+import { Fragment, type Node as PmNode } from "@tiptap/pm/model";
+import {
+  NodeSelection,
+  Plugin,
+  PluginKey,
+  Selection,
+  TextSelection,
+  type Transaction,
+} from "@tiptap/pm/state";
+import { placeContainerBlock } from "../../core/containers.js";
+import { detailsTokenizer, parseDetails, renderDetails } from "./detailsMarkdown.js";
+
+/**
+ * Сворачиваемый Блок (Details) — Блок-контейнер из двух детей: заголовок
+ * (`detailsSummary`, строчное содержимое) и содержимое (`detailsContent`, Блоки).
+ * Движок — расширение Details из Tiptap (API по нему, ADR-0048: заказчика при
+ * выпуске не было); кит добавляет Схему, санитайзер, Markdown и вставку.
+ *
+ * HTML — КАК У TIPTAP, ТЕГАМИ КИТА, без классов и `style`:
+ *
+ * ```html
+ * <details>
+ *   <summary>Заголовок</summary>
+ *   <div data-type="detailsContent"><p>Блоки</p></div>
+ * </details>
+ * ```
+ *
+ * `open` пишется только с Опцией `persist` (по умолчанию нет): раскрытый при
+ * правке Блок не публикуется раскрытым без спроса. Обёртка содержимого
+ * (`div[data-type="detailsContent"]`) нужна движку, чтобы отличить содержимое от
+ * заголовка; чужой HTML без неё (GitHub, браузер: `<details><summary>…</summary>
+ * <p>…</p></details>`) читается так же, Схема достраивает её сама.
+ *
+ * ВЛОЖЕННОСТЬ — КАК У ЛЮБОГО БЛОКА. Details входит в группу `block`: он бывает на
+ * верхнем уровне, в колонке Раскладки, Обёртке, цитате, ячейке и в содержимом
+ * другого Details. Раскладки и Обёртки внутри него нет — их принимают только
+ * Документ и колонка. `isolating`, как у Обёртки: Backspace в начале Блока не
+ * выводит текст наружу.
+ *
+ * Вид Блока в Редакторе — представление узла из Tiptap: `div` с кнопкой
+ * раскрытия и классом `is-open`; открытость при `persist: false` живёт только в
+ * этом DOM, не в Документе и не в истории правок.
+ */
+
+/** Имена узлов Схемы движка. */
+export const DETAILS_NODE = "details";
+export const DETAILS_SUMMARY_NODE = "detailsSummary";
+export const DETAILS_CONTENT_NODE = "detailsContent";
+
+/** Имя обёртки содержимого в `data-type`: так её пишет Tiptap. */
+export const DETAILS_CONTENT_TYPE = DETAILS_CONTENT_NODE;
+
+export interface DetailsEngineOptions {
+  /** Пишется ли открытость Блока в Документ (Опция `persist`). */
+  persist: boolean;
+  /** Имя кнопки раскрытия по тексту заголовка: из каталога, читается при каждой перерисовке. */
+  toggleLabel: (text: string) => string;
+}
+
+/** Метка транзакции: позиция только что вставленного Блока, который надо раскрыть. */
+const OPEN_ON_INSERT = new PluginKey<number | null>("detailsOpenOnInsert");
+
+/**
+ * Раскрыть Блок, вставленный из Меню вставки: открытость при `persist: false` —
+ * класс в DOM представления, а не атрибут узла, поэтому раскрывает её щелчок по
+ * кнопке, как у автора. Пустой Блок, который не раскрыт, — заголовок без места
+ * под содержимое, а набирать его автор пришёл не в заголовок. Делается после
+ * обновления DOM и вне транзакции: кнопка Tiptap возвращает фокус в Документ.
+ */
+const openOnInsert = new Plugin<number | null>({
+  key: OPEN_ON_INSERT,
+  state: {
+    init: () => null,
+    apply: (tr) => (tr.getMeta(OPEN_ON_INSERT) as number | undefined) ?? null,
+  },
+  view: () => ({
+    update(view) {
+      const pos = OPEN_ON_INSERT.getState(view.state);
+      if (pos === null || pos === undefined) return;
+      queueMicrotask(() => {
+        if (view.isDestroyed) return;
+        const dom = view.nodeDOM(pos);
+        if (!(dom instanceof HTMLElement) || dom.getAttribute("data-type") !== DETAILS_NODE) return;
+        if (dom.classList.contains("is-open")) return;
+        dom.querySelector<HTMLButtonElement>(":scope > button")?.click();
+      });
+    },
+  }),
+});
+
+/** Текст заголовка Блока — для имени кнопки. */
+function summaryText(node: PmNode): string {
+  return node.firstChild?.type.name === DETAILS_SUMMARY_NODE ? node.firstChild.textContent : "";
+}
+
+/** Виден ли узел на позиции: свёрнутое содержимое спрятано, и у него нет `offsetParent`. */
+function isVisibleAt(editor: Editor, pos: number): boolean {
+  const { node } = editor.view.domAtPos(pos);
+  const element = node.nodeType === Node.ELEMENT_NODE ? (node as HTMLElement) : node.parentElement;
+  return element !== null && element.offsetParent !== null;
+}
+
+/**
+ * Enter в заголовке раскрытого Блока, где содержимое начинается пустым Блоком:
+ * каретка встаёт в него. Не в заголовке, свёрнутый Блок и непустое начало —
+ * `false`, дело Tiptap.
+ */
+function moveIntoEmptyContent(editor: Editor): boolean {
+  const { selection } = editor.state;
+  const { $head } = selection;
+  if (!selection.empty || $head.parent.type.name !== DETAILS_SUMMARY_NODE) return false;
+  const content = $head.node(-1).lastChild;
+  const first = content?.type.name === DETAILS_CONTENT_NODE ? content.firstChild : null;
+  if (!first?.isTextblock || first.content.size > 0) return false;
+  const start = $head.after() + 1;
+  if (!isVisibleAt(editor, start)) return false;
+  const { tr } = editor.state;
+  editor.view.dispatch(tr.setSelection(Selection.near(tr.doc.resolve(start), 1)).scrollIntoView());
+  return true;
+}
+
+/**
+ * Backspace в заголовке. Safari стирает при нём весь текст `summary` (баг
+ * WebKit), поэтому Tiptap удаляет знак сам — но один знак UTF-16, и эмодзи с
+ * суррогатной парой терял половину. Здесь удаляется последний графем:
+ * `Intl.Segmenter`, а без него — кодовая точка.
+ */
+function lastGraphemeLength(text: string): number {
+  if (typeof Intl !== "undefined" && "Segmenter" in Intl) {
+    const parts = Array.from(
+      new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(text)
+    );
+    return parts.at(-1)?.segment.length ?? 1;
+  }
+  return Array.from(text).at(-1)?.length ?? 1;
+}
+
+declare module "@tiptap/core" {
+  interface Commands<ReturnType> {
+    detailsBlock: {
+      /**
+       * Вставить пустой сворачиваемый Блок под текущим Блоком; пустой абзац
+       * заменяется. Каретка — в заголовке. Блок раскрыт: с `persist` — атрибутом,
+       * без него — сразу после вставки. Из заголовка, списка и ячейки он встаёт под
+       * их Блоком, из Обёртки, колонки и цитаты — внутри них.
+       */
+      insertDetails: () => ReturnType;
+    };
+  }
+}
+
+/**
+ * Узел Details кита: Tiptap плюс вставка, Backspace без потери знака,
+ * раскрытие вставленного и Markdown сырым HTML.
+ */
+function createDetails({ persist, toggleLabel }: DetailsEngineOptions) {
+  return Details.extend({
+    // Свой Markdown (`detailsMarkdown.ts`): вместо `:::details` — сырой HTML.
+    markdownTokenizer: detailsTokenizer,
+    parseMarkdown(token, helpers) {
+      return parseDetails(token, helpers, this.options.persist);
+    },
+    renderMarkdown(node, helpers) {
+      return renderDetails(node, helpers, this.options.persist);
+    },
+    addCommands() {
+      return {
+        ...this.parent?.(),
+        insertDetails:
+          () =>
+          ({ tr, dispatch }) => {
+            if (dispatch) placeDetails(tr, this.options.persist);
+            return true;
+          },
+      };
+    },
+    addKeyboardShortcuts() {
+      const upstream = this.parent?.() ?? {};
+      return {
+        ...upstream,
+        /*
+          Enter в заголовке раскрытого Блока Tiptap ставит НОВЫЙ пустой абзац в
+          начало содержимого. У только что вставленного Блока содержимое — уже
+          один пустой абзац, и новый оставил бы пустую строку в конце после
+          набранного: каретка идёт в тот абзац, что есть.
+        */
+        Enter: (props) => moveIntoEmptyContent(props.editor) || (upstream.Enter?.(props) ?? false),
+        Backspace: () => {
+          const { selection } = this.editor.state;
+          const { empty, $anchor } = selection;
+          if (!empty || $anchor.parent.type.name !== DETAILS_SUMMARY_NODE) return false;
+          // Начало заголовка — Блок распадается (`unsetDetails`).
+          if ($anchor.parentOffset === 0) return this.editor.commands.unsetDetails();
+          const before = $anchor.parent.textBetween(0, $anchor.parentOffset);
+          const size = lastGraphemeLength(before);
+          return this.editor.commands.command(({ tr }) => {
+            tr.delete($anchor.pos - size, $anchor.pos);
+            return true;
+          });
+        },
+      };
+    },
+    addNodeView() {
+      const parentView = this.parent?.();
+      if (!parentView) return null;
+      return (props) => {
+        const view = parentView(props);
+        const toggle = view.dom.querySelector<HTMLButtonElement>(":scope > button");
+        /*
+          Кнопка раскрытия лежит внутри Документа, и без этого её события
+          забирал бы ProseMirror: `Enter` на кнопке резал бы строку, а щелчок
+          двигал каретку. Кнопку обслуживает только она сама.
+        */
+        const stopEvent = (event: Event) =>
+          event.target instanceof Node && !!toggle && toggle.contains(event.target);
+        /*
+          Кнопка стоит внутри редактируемого Документа и без этого сама
+          редактируема. Chrome при любой клавише переводит фокус с такой кнопки
+          на редактируемый корень ещё до `keydown`: Enter и Space не доходили до
+          неё, и Блок не раскрывался с клавиатуры. Нередактируемая кнопка
+          сохраняет фокус и получает клавишу.
+        */
+        toggle?.setAttribute("contenteditable", "false");
+        /*
+          Щелчок Tiptap возвращает фокус в Документ — мышь это не задевает, а
+          клавиатуру выбросило бы с кнопки. Клавиатурный щелчок узнаём по Enter
+          или Space на самой кнопке: `detail` равен нулю и у `click()` из кода
+          (раскрытие вставленного Блока), а там фокус должен остаться в
+          Документе. Фокус Tiptap ставит кадром позже (`requestAnimationFrame`),
+          поэтому и возвращаем его кадром: колбэк стоит в очереди после Tiptap.
+          `aria-expanded` озвучивается там, где человек.
+        */
+        let byKey = false;
+        toggle?.addEventListener("keydown", (event) => {
+          if (event.key === "Enter" || event.key === " ") byKey = true;
+        });
+        toggle?.addEventListener("blur", () => {
+          byKey = false;
+        });
+        toggle?.addEventListener("click", () => {
+          if (!byKey) return;
+          byKey = false;
+          /*
+            До кадра человек может уйти дальше (Tab к кнопке следующего Блока),
+            а фокус Tiptap кадром позже утащит его и оттуда в Документ. Поэтому
+            запоминаем, куда фокус перевёл сам человек, и возвращаем туда, а не
+            на эту кнопку: иначе следующая клавиша ушла бы не той кнопке.
+          */
+          const owner = toggle.ownerDocument;
+          const root = view.dom.closest(".ProseMirror");
+          let target: HTMLElement = toggle;
+          const follow = (event: FocusEvent) => {
+            if (event.target instanceof HTMLElement && event.target !== root) target = event.target;
+          };
+          owner.addEventListener("focusin", follow, true);
+          requestAnimationFrame(() => {
+            owner.removeEventListener("focusin", follow, true);
+            const active = owner.activeElement;
+            // Фокус в Документе — его поставил Tiptap; где-то ещё — его увёл человек.
+            if (target.isConnected && (active === root || active === target)) {
+              target.focus({ preventScroll: true });
+            }
+          });
+        });
+        return { ...view, stopEvent };
+      };
+    },
+    addProseMirrorPlugins() {
+      return [...(this.parent?.() ?? []), ...(this.options.persist ? [] : [openOnInsert])];
+    },
+  }).configure({
+    persist,
+    renderToggleButton: ({ element, isOpen, node }) => {
+      // Имя кнопки — заголовок Блока; раскрыт он или нет, говорит `aria-expanded`.
+      element.setAttribute("aria-label", toggleLabel(summaryText(node)));
+      element.setAttribute("aria-expanded", String(isOpen));
+    },
+  });
+}
+
+/**
+ * Заголовок: `details > summary`. Tiptap разбирает любой `summary`, а `summary`
+ * вне Блока — это текст, который не должен превратиться в Блок целиком.
+ */
+const KitSummary = DetailsSummary.extend({
+  parseHTML: () => [{ tag: "details > summary" }],
+  // Markdown Блока пишет и читает сам Блок (`detailsMarkdown.ts`): `:::detailsSummary`
+  // Tiptap кит не принимает.
+  markdownTokenizer: {
+    name: DETAILS_SUMMARY_NODE,
+    level: "block",
+    start: () => -1,
+    tokenize: () => undefined,
+  },
+});
+
+const KitContent = DetailsContent.extend({
+  /*
+    Содержимое — контейнер Блоков (`isBlockContainer`, `blockCommands.ts`): его
+    дети — Блоки со своей ручкой, и «Вверх», «Вниз», «Добавить ниже» и `⌥⇧↑/↓`
+    остаются внутри него. Флаг в Схеме ставит кит из Признака описания
+    (`blocks`, `extensions.ts`).
+  */
+  markdownTokenizer: {
+    name: DETAILS_CONTENT_NODE,
+    level: "block",
+    start: () => -1,
+    tokenize: () => undefined,
+  },
+});
+
+/** Всё, что нужно Блоку: узел, заголовок и содержимое. */
+export function detailsExtensions(options: DetailsEngineOptions): Extensions {
+  return [createDetails(options), KitSummary, KitContent];
+}
+
+/**
+ * Пустой Блок с одним абзацем в содержимом — под текущим Блоком, в ближайшем
+ * вверх узле, который его принимает (правила места общие с Раскладкой и
+ * Обёрткой, `placeContainerBlock`). Каретка — в заголовке.
+ */
+function placeDetails(tr: Transaction, persist: boolean): void {
+  const { schema } = tr.doc.type;
+  const details = schema.nodes[DETAILS_NODE]!.create(persist ? { open: true } : null, [
+    schema.nodes[DETAILS_SUMMARY_NODE]!.create(),
+    schema.nodes[DETAILS_CONTENT_NODE]!.create(null, schema.nodes.paragraph!.create()),
+  ]);
+  placeContainerBlock(tr, details);
+  if (persist) return;
+  // Позиция Блока — над кареткой, в заголовке: два уровня вверх.
+  const { $from } = tr.selection;
+  for (let depth = $from.depth; depth > 0; depth--) {
+    if ($from.node(depth).type.name === DETAILS_NODE) {
+      tr.setMeta(OPEN_ON_INSERT, $from.before(depth));
+      break;
+    }
+  }
+}
+
+/** Сворачиваемый Блок под позицией `pos`: сам Блок или Блок прямо в его содержимом. */
+function detailsAt(tr: Transaction, pos: number): { from: number; node: PmNode } | null {
+  const node = tr.doc.nodeAt(pos);
+  if (node?.type.name === DETAILS_NODE) return { from: pos, node };
+  const $pos = tr.doc.resolve(pos);
+  if ($pos.parent.type.name !== DETAILS_CONTENT_NODE) return null;
+  const from = $pos.before($pos.depth - 1);
+  const details = tr.doc.nodeAt(from);
+  return details?.type.name === DETAILS_NODE ? { from, node: details } : null;
+}
+
+/**
+ * Снять Блок в `pos` (самого Блока или Блока в его содержимом): заголовок
+ * становится абзацем, Блоки содержимого идут за ним. Одна правка — отмена одна.
+ * Каретка остаётся в своём тексте (в заголовке — в абзаце из него); выделенный
+ * узлом Блок исчезает, и каретка встаёт в начало абзаца. `false` — Блока в `pos` нет.
+ */
+export function unwrapDetailsAt(tr: Transaction, pos: number): boolean {
+  const found = detailsAt(tr, pos);
+  if (!found) return false;
+  const { from, node } = found;
+  const to = from + node.nodeSize;
+  const { schema } = tr.doc.type;
+  const summary = node.firstChild;
+  const content = node.lastChild;
+  const lead = schema.nodes.paragraph!.create(null, summary?.content ?? Fragment.empty);
+  const blocks = content?.type.name === DETAILS_CONTENT_NODE ? content.content : Fragment.empty;
+  const before = tr.selection;
+  const wasNode = before instanceof NodeSelection && before.from === from;
+  // Позиции внутри Блока после замены: заголовок на шаг левее (нет тега `details`),
+  // Блоки содержимого — за абзацем вместо `details`, `summary` и обёртки.
+  const summaryEnd = from + 1 + (summary?.nodeSize ?? 0);
+  const delta = from + lead.nodeSize - (summaryEnd + 1);
+  const shift = (at: number) => (at < summaryEnd ? at - 1 : at + delta);
+  const inside = before.from > from && before.to < to;
+  tr.replaceWith(from, to, Fragment.from(lead).append(blocks));
+  if (wasNode || !inside) {
+    tr.setSelection(TextSelection.create(tr.doc, from + 1));
+  } else if (before instanceof NodeSelection) {
+    tr.setSelection(NodeSelection.create(tr.doc, shift(before.from)));
+  } else {
+    tr.setSelection(TextSelection.create(tr.doc, shift(before.anchor), shift(before.head)));
+  }
+  tr.scrollIntoView();
+  return true;
+}

package/src/editor/features/details/detailsMarkdown.ts

@@ -0,0 +1,158 @@
+"use client";
+
+import type {
+  JSONContent,
+  MarkdownLexerConfiguration,
+  MarkdownParseHelpers,
+  MarkdownRendererHelpers,
+  MarkdownToken,
+  MarkdownTokenizer,
+} from "@tiptap/core";
+
+/**
+ * Сворачиваемый Блок в Markdown — СЫРЫМ HTML, как на GitHub:
+ *
+ * ```
+ * <details>
+ * <summary>Заголовок</summary>
+ *
+ * Содержимое — Markdown.
+ *
+ * </details>
+ * ```
+ *
+ * ПОЧЕМУ СВОЙ РАЗБОР. Расширение Tiptap пишет Блок синтаксисом `:::details`
+ * (Pandoc), которого не знает ни GitHub, ни другой Markdown. А общий разбор
+ * сырого HTML в `@tiptap/markdown` режет Блок на куски по пустым строкам: HTML-блок
+ * CommonMark кончается на первой пустой строке, и открывающий тег, Markdown
+ * внутри и закрывающий тег приходят тремя токенами, которые обратно не
+ * склеиваются. Поэтому Блок разбирает отдельный токенизатор: от `<details>` до
+ * парного `</details>` с учётом вложенных Блоков, а содержимое между ними — снова
+ * Markdown. Заголовок (`summary`) — строчный Markdown одной строкой; GitHub его
+ * как Markdown не читает (звёздочки останутся звёздочками), но круг через
+ * `setMarkdown` и `getMarkdown` от этого без потерь.
+ *
+ * Модуль без Tiptap-значений: только типы и чистые функции над строкой.
+ */
+
+/** Открывающий тег Блока с любыми атрибутами. */
+const OPEN_TAG = /^<details(?:\s[^<>]*)?>/i;
+/** Любой тег Блока — для подсчёта вложенности. */
+const ANY_TAG = /<(\/?)details(?:\s[^<>]*)?>/gi;
+/** `summary` сразу после открывающего тега, пробелы и переводы строк до него не в счёт. */
+const SUMMARY = /^\s*<summary(?:\s[^<>]*)?>([\s\S]*?)<\/summary>[ \t]*/i;
+
+/**
+ * Копия строки, где всё, что тегами Блока быть не может, заменено пробелами:
+ * кодовые заборы и строчный код. Длина и позиции те же, поэтому найденные в
+ * копии теги указывают в исходную строку. Иначе `<details>` в примере кода внутри
+ * Блока сдвинул бы вложенность и Блок закрылся бы не там.
+ */
+function maskCode(src: string): string {
+  let fence: string | null = null;
+  const lines = src.split("\n").map((line) => {
+    const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+    if (fence === null && marker) {
+      fence = marker[0]!.repeat(3);
+      return " ".repeat(line.length);
+    }
+    if (fence !== null) {
+      if (marker && marker.startsWith(fence)) fence = null;
+      return " ".repeat(line.length);
+    }
+    return line.replace(/(`+)[^`\n]*?\1/g, (span) => " ".repeat(span.length));
+  });
+  return lines.join("\n");
+}
+
+/** Позиция конца парного `</details>` (после тега) для Блока, открытого в начале `src`. */
+function closingEnd(src: string, afterOpen: number): number {
+  const masked = maskCode(src);
+  let level = 1;
+  ANY_TAG.lastIndex = afterOpen;
+  for (let match = ANY_TAG.exec(masked); match; match = ANY_TAG.exec(masked)) {
+    level += match[1] ? -1 : 1;
+    if (level === 0) return match.index + match[0].length;
+  }
+  return -1;
+}
+
+/** Заголовок одной строкой: переводы строк и повторы пробелов — в один пробел. */
+function oneLine(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+/** Токенизатор Блока `details` для `marked` (`markdownTokenizer` расширения). */
+export const detailsTokenizer: MarkdownTokenizer = {
+  name: "details",
+  level: "block",
+  start: (src) => src.search(/^<details[\s>]/im),
+  tokenize(src, _tokens, lexer: MarkdownLexerConfiguration) {
+    const open = OPEN_TAG.exec(src);
+    if (!open) return undefined;
+    const end = closingEnd(src, open[0].length);
+    if (end < 0) return undefined;
+    // Конец Блока — строка целиком: хвост после `</details>` не наше дело.
+    const raw = src.slice(0, end);
+    const closeTag = /<\/details(?:\s[^<>]*)?>$/i.exec(raw)?.[0] ?? "";
+    const inner = raw.slice(open[0].length, raw.length - closeTag.length);
+    const summary = SUMMARY.exec(inner);
+    const body = summary ? inner.slice(summary[0].length) : inner;
+    const tokens: MarkdownToken[] = body.trim() ? lexer.blockTokens(body) : [];
+    // Строчные токены блоков без своих `tokens` (абзац, заголовок) разбирает
+    // сам `marked` внутри `blockTokens`; здесь дозаполняется только то, что он
+    // оставил текстом, как в `createBlockMarkdownSpec` Tiptap.
+    for (const token of tokens) {
+      if (token.text && (!token.tokens || token.tokens.length === 0)) {
+        token.tokens = lexer.inlineTokens(token.text);
+      }
+    }
+    return {
+      type: "details",
+      raw,
+      // `open` — если он в открывающем теге: `<details open>`.
+      open: /^<details(?:\s[^<>]*)?\sopen(?:[\s=>/]|$)/i.test(open[0]),
+      summary: summary ? lexer.inlineTokens(oneLine(summary[1] ?? "")) : [],
+      tokens,
+    } as MarkdownToken;
+  },
+};
+
+/**
+ * Токен — в узел Блока: заголовок из текста с Метками, содержимое Блоками (пустое
+ * — одним пустым абзацем). Атрибут `open` — только когда он в Схеме (`persist`).
+ */
+export function parseDetails(
+  token: MarkdownToken,
+  helpers: MarkdownParseHelpers,
+  persist: boolean
+): JSONContent {
+  const title = helpers
+    .parseInline((token.summary as MarkdownToken[] | undefined) ?? [])
+    // Заголовок — только текст с Метками: перенос и картинка в нём не живут.
+    .filter((node) => node.type === "text");
+  const blocks = helpers.parseChildren(token.tokens ?? []);
+  return helpers.createNode("details", persist && token.open === true ? { open: true } : {}, [
+    helpers.createNode("detailsSummary", {}, title),
+    helpers.createNode("detailsContent", {}, blocks.length > 0 ? blocks : [{ type: "paragraph" }]),
+  ]);
+}
+
+/**
+ * Узел — в Markdown: открывающий тег с `summary` на своей строке, пустая строка,
+ * Блоки через пустую строку, пустая строка, закрывающий тег. Пустая строка после
+ * `summary` — то, что заставляет GitHub читать содержимое как Markdown.
+ * `<` в заголовке пишется как `&lt;`: иначе текст «a </summary> b» закрыл бы
+ * заголовок раньше времени.
+ */
+export function renderDetails(
+  node: JSONContent,
+  helpers: MarkdownRendererHelpers,
+  persist: boolean
+): string {
+  const [summary, content] = node.content ?? [];
+  const title = summary?.content ? helpers.renderChildren(summary.content) : "";
+  const body = content?.content ? helpers.renderChildren(content.content, "\n\n") : "";
+  const open = persist && node.attrs?.open ? " open" : "";
+  return `<details${open}>\n<summary>${title.replace(/</g, "&lt;")}</summary>\n\n${body}\n\n</details>`;
+}

package/src/editor/features/details/detailsTool.ts

@@ -0,0 +1,69 @@
+"use client";
+
+import { DetailsIcon, UnwrapIcon } from "../../../icons.js";
+import type { ToolDescriptor } from "../../core/toolDescriptor.js";
+import type { DetailsToolOptions } from "../../core/toolOptions.js";
+import {
+  DETAILS_CONTENT_NODE,
+  DETAILS_NODE,
+  detailsExtensions,
+  unwrapDetailsAt,
+} from "./details.js";
+
+/** Умолчания Опций: открытость в Документ не пишется (как `persist` у Tiptap). */
+export const DETAILS_DEFAULTS: DetailsToolOptions = { persist: false };
+
+/**
+ * Сворачиваемый Блок на описании Инструмента (ADR-0048): узлы и их клавиатура
+ * (`details.ts`), Markdown сырым HTML (`detailsMarkdown.ts`), пункт Меню вставки,
+ * Действие «Снять сворачивание» и Признак «контейнер» для содержимого.
+ *
+ * Своей группы в модели Документа у Блока нет: он входит в `block`, как абзац.
+ * Меню ручки — как у Обёртки: «Вверх», «Вниз», «Дублировать», «Удалить» общие, к
+ * ним «Снять сворачивание» у самого Блока и у Блока в его содержимом. «Тон ›» у
+ * Блока нет — тонов он не знает.
+ */
+export const DETAILS_TOOL: ToolDescriptor = {
+  name: "details",
+  defaults: DETAILS_DEFAULTS,
+  checks: { persist: (value) => typeof value === "boolean" },
+  /*
+    Без Инструмента `details` из вставки и `value` не разбирается: заголовок
+    становится абзацем, Блоки содержимого идут за ним (расширения в Схеме нет, и
+    браузерный разбор берёт содержимое тегов, как у любого неизвестного).
+  */
+  engine: (context, options) =>
+    detailsExtensions({
+      persist: (options as DetailsToolOptions | undefined)?.persist === true,
+      toggleLabel: context.detailsToggle,
+    }),
+  // Содержимое — контейнер Блоков: дети со своей Ручкой (`blockContainer`).
+  blocks: { [DETAILS_CONTENT_NODE]: { container: true } },
+  // Теги Схемы кита; обёртка содержимого — `div[data-type="detailsContent"]`.
+  kitTags: ["details", "summary"],
+  insertItems: [
+    {
+      id: "details",
+      section: "insert",
+      label: (m) => m.details,
+      icon: DetailsIcon,
+      aliases: ["details", "summary", "toggle", "accordion", "spoiler", "collapse"],
+      run: (chain) => chain.insertDetails(),
+    },
+  ],
+  blockActions: [
+    {
+      id: "unwrapDetails",
+      label: (messages) => messages.unwrapDetails,
+      icon: UnwrapIcon,
+      blocks: [DETAILS_NODE, DETAILS_CONTENT_NODE],
+      // Одна правка: заголовок — абзац, содержимое на месте Блока, отмена — одна.
+      run: (editor, pos) =>
+        void editor
+          .chain()
+          .focus()
+          .command(({ tr }) => unwrapDetailsAt(tr, pos))
+          .run(),
+    },
+  ],
+};

package/src/editor/features/emoji/emojiTool.tsx

@@ -37,7 +37,7 @@ export function insertEmoji(editor: Editor, char: string): boolean {
 /**
  * Эмодзи на описании Инструмента (ADR-0058, п. 10.4) — проверка
  * кнопки с поповером на той же форме, что у своего Инструмента. Своей Схемы и
- * Части для движка нет: эмодзи — обычный текст.
+ * Extensions нет: эмодзи — обычный текст.
  *
  * Поповер — сетка `EmojiGrid` в рамке кита у кнопки. Выбор вставляет эмодзи и
  * закрывает поповер; фокус возвращается в Документ, а не на кнопку: человек