@olddevs/ui 0.0.0-stage → 4.0.0

package/src/editor/core/blockTypes.ts

@@ -0,0 +1,252 @@
+"use client";
+
+import type { ChainedCommands } from "@tiptap/core";
+import type { Node as PmNode } from "@tiptap/pm/model";
+import type { EditorState } from "@tiptap/pm/state";
+import type { ComponentType } from "react";
+import {
+  Heading1Icon,
+  Heading2Icon,
+  Heading3Icon,
+  Heading4Icon,
+  ListIcon,
+  OrderedListIcon,
+  TaskListIcon,
+  TextIcon,
+  type IconProps,
+} from "../../icons.js";
+import type { PrefixedName } from "./customTool.js";
+import type { InsertItem } from "./insertItems.js";
+import { shortcutKeys } from "./shortcuts.js";
+import { projectRecords, type ToolList } from "./toolDescriptor.js";
+import type { Tool } from "./tools.js";
+
+/**
+ * Пункт меню «¶» — тип Блока.
+ *
+ * Это пункт раздела «Превратить в» Меню вставки (`InsertItem`, `section:
+ * "turnInto"`), и применяется он тем же `applyInsertItem`: сначала с Блока
+ * снимаются обёртки (список, цитата), потом пункт оборачивает или меняет его
+ * заново — одной транзакцией, на одну отмену. Своего пути смены типа у меню
+ * нет: два пути разошлись бы на первом же списке внутри цитаты.
+ *
+ * Отдельный реестр, а не выборка из `INSERT_ITEMS`, потому что у меню «¶»
+ * другие слова и иконки: «Текст» с иконкой `T`, а не
+ * «Абзац» с пилкроу, и уровень заголовка на иконке. Блока кода в нём нет — у
+ * него своя кнопка Панели.
+ */
+export interface BlockTypeItem extends InsertItem {
+  section: "turnInto";
+  /**
+   * Инструмент, без которого пункта нет. У «Текста» — `null`: абзац есть всегда.
+   * У пункта своего Инструмента — его имя (ADR-0058, п. 5): набор уже отфильтрован.
+   */
+  tool: Tool | PrefixedName | null;
+  /** Второй нужный инструмент: H1 — надстройка над `heading`. */
+  alsoTool?: Tool;
+  keys: readonly string[];
+}
+
+/**
+ * Пункты «¶» Инструмента из его описания — те же пункты «Превратить в» Меню
+ * вставки: слова, иконка, сочетание и команда у них одни, поэтому вторую запись
+ * Инструмент не пишет (ADR-0058, п. 5).
+ */
+export function turnIntoTypes(
+  tool: Tool | PrefixedName,
+  items: readonly InsertItem[]
+): BlockTypeItem[] {
+  return items
+    .filter((item) => item.section === "turnInto")
+    .map((item) => ({ ...item, section: "turnInto", tool, keys: item.keys ?? [] }));
+}
+
+const heading = (level: 1 | 2 | 3 | 4, icon: ComponentType<IconProps>): BlockTypeItem => ({
+  id: `heading${level}`,
+  section: "turnInto",
+  tool: "heading",
+  alsoTool: level === 1 ? "heading1" : undefined,
+  label: (m) => m.heading({ level }),
+  icon,
+  keys: shortcutKeys(`h${level}`),
+  run: (chain: ChainedCommands) => chain.setHeading({ level }),
+});
+
+/**
+ * Пункты «¶» по порядку показа. Сочетания — подписи из общей таблицы
+ * (`shortcuts.ts`), по тем же id, что у Меню вставки и справочника:
+ * вешают их расширения движка, и подпись обязана совпадать с ними.
+ */
+export const BLOCK_TYPE_ITEMS: readonly BlockTypeItem[] = [
+  {
+    id: "text",
+    section: "turnInto",
+    tool: null,
+    label: (m) => m.textBlock,
+    icon: TextIcon,
+    keys: shortcutKeys("paragraph"),
+    run: (chain) => chain.setParagraph(),
+  },
+  heading(1, Heading1Icon),
+  heading(2, Heading2Icon),
+  heading(3, Heading3Icon),
+  heading(4, Heading4Icon),
+  {
+    id: "bulletList",
+    section: "turnInto",
+    tool: "bulletList",
+    label: (m) => m.bulletList,
+    icon: ListIcon,
+    keys: shortcutKeys("bulletList"),
+    run: (chain) => chain.toggleBulletList(),
+  },
+  {
+    id: "orderedList",
+    section: "turnInto",
+    tool: "orderedList",
+    label: (m) => m.orderedList,
+    icon: OrderedListIcon,
+    keys: shortcutKeys("orderedList"),
+    run: (chain) => chain.toggleOrderedList(),
+  },
+  {
+    id: "taskList",
+    section: "turnInto",
+    tool: "taskList",
+    label: (m) => m.taskList,
+    icon: TaskListIcon,
+    keys: shortcutKeys("taskList"),
+    run: (chain) => chain.toggleTaskList(),
+  },
+];
+
+/**
+ * Место встроенных Инструментов в «¶». «Текст» стоит первым всегда: абзац —
+ * не Инструмент. Держится отдельно от `BLOCK_TYPE_ITEMS`: Инструмент,
+ * переехавший на описание (`toolDescriptor.ts`), уходит из реестра, а место
+ * остаётся здесь.
+ */
+const BLOCK_TYPE_ORDER: readonly Tool[] = [
+  "heading",
+  "blockquote",
+  "bulletList",
+  "orderedList",
+  "taskList",
+];
+
+/**
+ * Пункты «¶» набора — проекция списка описаний: у переехавшего Инструмента —
+ * из описания (`blockTypes`), у остальных — из `BLOCK_TYPE_ITEMS`.
+ */
+function blockTypeItemsOf(tools: ToolList): readonly BlockTypeItem[] {
+  return [
+    ...BLOCK_TYPE_ITEMS.filter((item) => item.tool === null),
+    ...projectRecords(
+      tools,
+      BLOCK_TYPE_ORDER,
+      (tool) => BLOCK_TYPE_ITEMS.filter((item) => item.tool === tool),
+      (descriptor) => descriptor.blockTypes
+    ),
+  ].filter((item) => item.alsoTool === undefined || tools.has(item.alsoTool));
+}
+
+/**
+ * Пункты, которые «¶» больше не предлагает: списки живут в меню
+ * «Списки ▾», цитата — флажком в «…». В «Формат ›» ручки Блока и в «/» они
+ * остаются: там Блок превращают во что угодно, а не выбирают тип строки.
+ */
+const notInBlockTypeMenu = (id: string) =>
+  id === "blockquote" || (LIST_TYPES as readonly string[]).includes(id);
+
+/**
+ * Пункты «¶» для набора инструментов: «Текст», заголовки и пункты своих
+ * Инструментов. Меню из одного «Текста» ничего не выбирает, и тогда список
+ * пуст: кнопки «¶» на Панели нет.
+ */
+export function blockTypeItemsFor(tools: ToolList): readonly BlockTypeItem[] {
+  const items = blockTypeItemsOf(tools).filter((item) => !notInBlockTypeMenu(item.id));
+  return items.length > 1 ? items : [];
+}
+
+/**
+ * Пункты «Формат ›» ручки Блока: весь набор «Превратить в» —
+ * с цитатой и списками, в отличие от «¶» (решение владельца).
+ */
+export function formatItemsFor(tools: ToolList): readonly BlockTypeItem[] {
+  const items = blockTypeItemsOf(tools);
+  return items.length > 1 ? items : [];
+}
+
+/** Пункт цитаты набора — для флажка «Цитата» в «…»; без инструмента — `undefined`. */
+export function quoteItemFor(tools: ToolList): BlockTypeItem | undefined {
+  return blockTypeItemsOf(tools).find((item) => item.id === "blockquote");
+}
+
+/** Обёртки, которые сами — тип Блока в «Формат ›» ручки. */
+const WRAPPERS: Record<string, string> = {
+  blockquote: "blockquote",
+  bulletList: "bulletList",
+  orderedList: "orderedList",
+  taskList: "taskList",
+};
+
+/** Тип текстового Блока: `id` пункта «¶», `"codeBlock"` или `null` (не текст). */
+function textBlockType(block: PmNode): string | null {
+  if (block.type.name === "heading") return `heading${String(block.attrs.level)}`;
+  if (block.type.name === "codeBlock") return "codeBlock";
+  if (block.type.name === "paragraph") return "text";
+  return null;
+}
+
+/**
+ * Текущий тип Блока под началом выделения: `id` пункта «¶», `"codeBlock"` или
+ * `null` (выделен не текст — картинка, разделитель).
+ *
+ * РЕШАЕТ СТРОКА ПОД КАРЕТКОЙ (решение владельца). Списков и цитаты
+ * в «¶» больше нет, и абзац в пункте списка или в цитате — это «Текст», а
+ * заголовок в цитате — его уровень. Список и цитату показывают свои кнопки:
+ * «Списки ▾» и флажок «Цитата» в «…». Прежде решала ближайшая обёртка.
+ */
+export function currentBlockType(state: EditorState): string | null {
+  return textBlockType(state.selection.$from.parent);
+}
+
+/**
+ * Тип Блока целиком — для «Формат ›» ручки Блока: решает сам
+ * Блок, а не текст под кареткой. Цитата со списком внутри — «Цитата»: ручка
+ * превращает всю цитату. `null` — Блок, который превратить нельзя (таблица,
+ * картинка, линия).
+ */
+export function blockTypeOf(block: PmNode): string | null {
+  return WRAPPERS[block.type.name] ?? textBlockType(block);
+}
+
+/** Виды списка — id пунктов «Превратить в» Меню вставки и имена узлов Схемы. */
+export const LIST_TYPES = ["bulletList", "orderedList", "taskList"] as const;
+
+export type ListType = (typeof LIST_TYPES)[number];
+
+/**
+ * Пункты меню «Списки» — те же пункты «Превратить в» Меню вставки,
+ * что и виды списка: одни слова, иконки, сочетания и одна команда. В отличие от «¶», меню из одного
+ * пункта остаётся меню: «Чек-лист» без соседей — всё равно выбор вида списка.
+ */
+export function listTypeItemsFor(tools: ToolList): readonly BlockTypeItem[] {
+  return blockTypeItemsOf(tools).filter((item) =>
+    (LIST_TYPES as readonly string[]).includes(item.id)
+  );
+}
+
+/**
+ * Вид ближайшего списка вокруг начала выделения или `null` — каретка не в
+ * списке. Цитата между текстом и списком не мешает: пункт списка с цитатой
+ * внутри всё равно пункт списка, и снимать меню «Списки» должно его.
+ */
+export function currentListType(state: EditorState): ListType | null {
+  const { $from } = state.selection;
+  for (let depth = $from.depth - 1; depth > 0; depth--) {
+    const name = $from.node(depth).type.name;
+    if ((LIST_TYPES as readonly string[]).includes(name)) return name as ListType;
+  }
+  return null;
+}

package/src/editor/core/containers.ts

@@ -0,0 +1,100 @@
+"use client";
+
+import type { Node as PmNode, NodeType, ResolvedPos } from "@tiptap/pm/model";
+import { TextSelection, type Transaction } from "@tiptap/pm/state";
+
+/**
+ * Общее у контейнерных Блоков — Раскладки (`layout.ts`, ADR-0056) и Обёртки
+ * (`wrapper.ts`, ADR-0057): где их нет и куда встаёт новый.
+ *
+ * Оба не входят в группу `block`: их принимают только узлы, назвавшие их
+ * поимённо, — Документ, а Обёртку ещё и колонка Раскладки. Поэтому правила
+ * разбора и вставки у них одни и те же, и живут здесь, чтобы списки и
+ * арифметика позиций не разъезжались молча.
+ */
+
+/**
+ * Имя узла Обёртки в Схеме движка. Живёт здесь, а не в `wrapper.ts`: оно же
+ * входит в общий список ниже, а `wrapper.ts` импортирует этот модуль —
+ * определение там дало бы цикл импортов. `wrapper.ts` его реэкспортирует.
+ */
+export const WRAPPER_NODE = "wrapper";
+
+/**
+ * Узлы, внутри которых контейнерного Блока нет ни одного: Обёртка, цитата,
+ * пункты списков и ячейки таблицы. Колонки здесь нет — Обёртку она принимает;
+ * Раскладка добавляет её своим аргументом.
+ */
+const CONTAINER_FREE_NODES = [
+  WRAPPER_NODE,
+  "blockquote",
+  "listItem",
+  "taskItem",
+  "tableCell",
+  "tableHeader",
+];
+
+/**
+ * Контекст правила разбора (`context` в `parseHTML`), где контейнерный Блок
+ * снимается: правило с `skip` отдаёт его Блоки подряд, а не режет контейнер
+ * вставки надвое. `more` — узлы, где нет именно этого Блока (колонка — для
+ * Раскладки). Имена выключенных инструментов безвредны: контекст сверяется по
+ * имени узла.
+ */
+export function containerFreeContext(...more: string[]): string {
+  return [...more, ...CONTAINER_FREE_NODES].map((name) => `${name}//`).join(" | ");
+}
+
+/**
+ * Лежит ли позиция в узле, где контейнерного Блока нет (`CONTAINER_FREE_NODES`):
+ * то же правило, что `containerFreeContext` для разбора HTML, — для путей, где
+ * Блоки строятся не разбором HTML (вставка Markdown, `markdown.ts`).
+ */
+export function inContainerFreeNode($pos: ResolvedPos): boolean {
+  for (let depth = $pos.depth; depth > 0; depth--) {
+    if (CONTAINER_FREE_NODES.includes($pos.node(depth).type.name)) return true;
+  }
+  return false;
+}
+
+/** Может ли узел держать узел типа `type` ребёнком. */
+function holds(node: PmNode, type: NodeType): boolean {
+  return node.type.contentMatch.matchType(type) !== null;
+}
+
+/**
+ * Поставить контейнерный Блок `container` под текущим Блоком — в ближайший
+ * вверх узел, который его принимает (Документ; для Обёртки — и колонку).
+ *
+ * Пустой абзац прямо в нём (его готовит Меню вставки) заменяется. Из Обёртки,
+ * колонки, списка, цитаты или ячейки Блок встаёт под их Блоком в этом узле;
+ * пустой абзац контейнера Блоков (Обёртки или колонки), в котором набрали `/`,
+ * при этом убирается, если там есть что-то ещё, — иначе от вставки оставался
+ * бы пустой хвост. Каретка — в первый текстовый Блок нового контейнера.
+ */
+export function placeContainerBlock(tr: Transaction, container: PmNode): void {
+  const { selection } = tr;
+  const { $from } = selection;
+  let depth = $from.depth;
+  while (depth > 0 && !holds($from.node(depth), container.type)) depth--;
+  const emptyBlock = $from.parent.isTextblock && $from.parent.content.size === 0;
+  let pos: number;
+  if (emptyBlock && $from.depth === depth + 1) {
+    pos = $from.before();
+    tr.replaceWith(pos, $from.after(), container);
+  } else {
+    pos = $from.depth === depth ? selection.to : $from.after(depth + 1);
+    const parent = $from.depth > depth + 1 ? $from.node(-1) : null;
+    if (emptyBlock && parent?.type.spec.blockContainer === true && parent.childCount > 1) {
+      const steps = tr.mapping.maps.length;
+      tr.delete($from.before(), $from.after());
+      pos = tr.mapping.slice(steps).map(pos);
+    }
+    tr.insert(pos, container);
+  }
+  // По шагу внутрь на каждый уровень до текстового Блока: Обёртка › абзац —
+  // два, Раскладка › колонка › абзац — три.
+  let inner = pos + 1;
+  for (let node = container; !node.isTextblock && node.firstChild; node = node.firstChild) inner++;
+  tr.setSelection(TextSelection.create(tr.doc, inner)).scrollIntoView();
+}

package/src/editor/core/customMarkdown.ts

@@ -0,0 +1,74 @@
+"use client";
+
+import {
+  getExtensionField,
+  type AnyExtension,
+  type Editor,
+  type JSONContent,
+  type MarkdownRendererHelpers,
+} from "@tiptap/core";
+import { devWarn } from "../../lib/dev-warn.js";
+
+/*
+  Markdown своего Инструмента по умолчанию (ADR-0058, п. 3.1).
+
+  Свои правила Markdown — в Части для движка: `renderMarkdown` и токенайзер
+  Tiptap, отдельного поля в описании нет. Без них `@tiptap/markdown` молча
+  выгрузил бы узел пустой строкой — вместе со всем текстом внутри. Поэтому
+  Node и Mark без `renderMarkdown` кит дописывает сам: Блок выгружается своим
+  содержимым (как `conform` при разборе Markdown разворачивает чужой узел),
+  атом — Текстом атома (`renderText`, ADR-0058, п. 4), Метка — своим текстом.
+  Пропадает только атом без текста. Обратно такой Блок из Markdown не
+  создаётся: правил разбора у него нет, его текст встаёт абзацами.
+
+  Предупреждение — одно на Инструмент и только когда умолчание сработало:
+  потребителю, который Markdown не выгружает, оно ни к чему.
+*/
+
+/** Поле конфигурации атома своего Инструмента без правил Markdown: имя Инструмента. */
+export const MARKDOWN_FALLBACK = "kitMarkdownFallback";
+
+/** Предупреждение о Markdown по умолчанию — одно на Инструмент (`devWarn` помнит текст). */
+export function warnNoMarkdown(tool: string): void {
+  devWarn(
+    `custom tool "${tool}" has no Markdown rules (renderMarkdown in its engine part): ` +
+      "getMarkdown() writes its blocks as their content and its atoms as their text"
+  );
+}
+
+/** Поля Node или Mark, дописывающие Markdown по умолчанию; `{}`, если свои правила есть. */
+export function markdownFallback(extension: AnyExtension, tool: string): object {
+  if (getExtensionField(extension, "renderMarkdown") !== undefined) return {};
+  // Атом (лист или `atom: true`) выгружает `markdownOf` (`atomText.ts`) — тем же
+  // Текстом атома, что у встроенных, и без пустого Блока на месте атома без
+  // текста. Здесь — только метка, чтобы `markdownOf` предупредил о нём сам.
+  if (
+    extension.type === "node" &&
+    (getExtensionField(extension, "atom") === true ||
+      getExtensionField(extension, "content") === undefined)
+  ) {
+    return { [MARKDOWN_FALLBACK]: tool };
+  }
+  // Редактор, в чьей Схеме живёт узел: Markdown получает JSON, а Текст атома
+  // считает `renderText` по узлу ProseMirror. Описание своего Инструмента
+  // разворачивается на каждый Редактор (`expandTools`), поэтому Редактор один.
+  let editor: Editor | null = null;
+  return {
+    onBeforeCreate(
+      this: { editor: Editor; parent?: ((...args: unknown[]) => void) | null },
+      ...args: unknown[]
+    ) {
+      editor = this.editor;
+      this.parent?.(...args);
+    },
+    renderMarkdown(node: JSONContent, helpers: MarkdownRendererHelpers): string {
+      warnNoMarkdown(tool);
+      // Метка: Tiptap вызывает это ради открывающей и закрывающей разметки
+      // вокруг заглушки — их нет, остаётся текст.
+      if (extension.type === "mark") return helpers.renderChildren(node);
+      const type = editor?.schema.nodes[node.type ?? ""];
+      if (!node.content) return "";
+      return helpers.renderChildren(node.content, type && !type.inlineContent ? "\n\n" : "");
+    },
+  };
+}