@olddevs/ui 0.0.0-stage → 4.0.0

package/src/editor/features/builtins.ts

@@ -0,0 +1,145 @@
+"use client";
+
+import Blockquote from "@tiptap/extension-blockquote";
+import HorizontalRule from "@tiptap/extension-horizontal-rule";
+import { DividerIcon, QuoteIcon, UnwrapIcon } from "../../icons.js";
+import { turnIntoTypes } from "../core/blockTypes.js";
+import type { InsertItem } from "../core/insertItems.js";
+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 { toolList, type ToolDescriptor, type ToolList } from "../core/toolDescriptor.js";
+import { SEARCH_TOOL } from "./search/searchTool.js";
+import { TABLE_TOOL } from "./table/tableTool.js";
+import { resolveTools, TOOLS, type RichTextEditorPreset, type Tool } from "../core/tools.js";
+import { unwrapWrapperAt, WRAPPER_NODE } from "./wrapper/wrapper.js";
+
+/** Сочетание цитаты: одна запись на справочник, Меню вставки и «¶». */
+const BLOCKQUOTE_SHORTCUT: ShortcutCommand = {
+  id: "blockquote",
+  group: "blockType",
+  tool: "blockquote",
+  keys: ["mod", "shift", "B"],
+  label: (m) => m.blockquote,
+};
+
+const BLOCKQUOTE_ITEMS: readonly InsertItem[] = [
+  {
+    id: "blockquote",
+    section: "turnInto",
+    label: (m) => m.blockquote,
+    icon: QuoteIcon,
+    aliases: [">"],
+    markdown: ">",
+    keys: BLOCKQUOTE_SHORTCUT.keys,
+    run: (chain) => chain.setBlockquote(),
+  },
+];
+
+/**
+ * Описания встроенных Инструментов, переехавших со старых реестров
+ * (ADR-0058, п. 10; тип — `toolDescriptor.ts`).
+ *
+ * Сюда Инструмент переезжает целиком: его записи удаляются из старых
+ * реестров, и с этой минуты он берётся только из описания. Кого здесь нет, тот
+ * стоит в развёрнутом списке заглушкой `legacy` и по-прежнему живёт в старых
+ * реестрах. `image`, `layout` и виджеты Панели переезжают постепенно, и выпуск
+ * их не ждёт.
+ */
+export const BUILTIN_TOOLS: Partial<Record<Tool, ToolDescriptor>> = {
+  search: SEARCH_TOOL,
+  /*
+    Обёртка переехала только Действием над Блоком, поэтому
+    `legacy`: её узел, вставка и сочетания остаются в старых реестрах. «Тон ›» —
+    меню-виджет, своего Инструмента у него нет, и он собирается в Ручке по-старому.
+  */
+  wrapper: {
+    name: "wrapper",
+    legacy: true,
+    blockActions: [
+      {
+        id: "unwrap",
+        label: (messages) => messages.unwrap,
+        icon: UnwrapIcon,
+        blocks: [WRAPPER_NODE],
+        // Одна правка: Блоки встают на место Обёртки, отмена — одна.
+        run: (editor, pos) =>
+          void editor
+            .chain()
+            .focus()
+            .command(({ tr }) => unwrapWrapperAt(tr, pos))
+            .run(),
+      },
+    ],
+  },
+  /*
+    Проверочный набор: Инструмент с пунктом вставки и Инструмент
+    с «Превратить в». Поля `insertItems` и `engine` совпадают с будущим
+    публичным описанием, чтобы его форма проверялась кодом кита.
+  */
+  horizontalRule: {
+    name: "horizontalRule",
+    engine: () => [HorizontalRule],
+    insertItems: [
+      {
+        id: "horizontalRule",
+        section: "insert",
+        label: (m) => m.horizontalRule,
+        icon: DividerIcon,
+        aliases: ["hr", "---"],
+        markdown: "---",
+        run: (chain) => chain.setHorizontalRule(),
+      },
+    ],
+  },
+  blockquote: {
+    name: "blockquote",
+    engine: () => [Blockquote],
+    insertItems: BLOCKQUOTE_ITEMS,
+    // «¶» — тот же пункт «Превратить в»: те же слова, иконка и сочетание.
+    blockTypes: turnIntoTypes("blockquote", BLOCKQUOTE_ITEMS),
+    // Клавишу вешает расширение Tiptap; строка справочника — подпись к ней.
+    shortcuts: [BLOCKQUOTE_SHORTCUT],
+  },
+  link: LINK_TOOL,
+  emoji: EMOJI_TOOL,
+  /*
+    Ленивые встроенные (ADR-0058, п. 11.1): их нет в `basic`, а
+    Часть для движка тяжелее 10 кБ gzip, поэтому она грузится загрузчиком
+    (`load`) — тем же, что у своего Инструмента.
+  */
+  codeBlock: CODE_BLOCK_TOOL,
+  table: TABLE_TOOL,
+};
+
+/**
+ * Развернуть `tools` (или `preset`) в один список описаний.
+ *
+ * Имена — те же, что у `resolveTools`: точный `tools` или пресет, неизвестная
+ * строка отбрасывается молча. Порядок встроенных — порядок кита (`TOOLS`), а
+ * не `tools`: место встроенного на поверхности решает кит. Свои Инструменты
+ * (описания в `tools`) идут следом, в порядке `tools` (ADR-0058, п. 5.3);
+ * набор имён (`Set`) — только имена кита.
+ */
+export function expandTools(
+  preset: RichTextEditorPreset,
+  tools: readonly ToolEntry[] | undefined
+): ToolList {
+  const names = resolveTools(
+    preset,
+    tools?.filter((tool): tool is Tool => typeof tool === "string")
+  );
+  const builtin = TOOLS.filter((name) => names.has(name)).map(
+    (name): ToolDescriptor => BUILTIN_TOOLS[name] ?? { name, legacy: true }
+  );
+  const custom = (tools ?? [])
+    .filter((tool): tool is CustomTool => typeof tool === "object" && tool !== null)
+    .map(describeCustomTool);
+  return toolList(
+    builtin.map((descriptor) => descriptor.name as Tool),
+    [...builtin, ...custom]
+  );
+}

package/src/editor/features/code/CodeBlockView.tsx

@@ -0,0 +1,240 @@
+"use client";
+
+import { NodeViewContent, NodeViewWrapper, type Editor, type NodeViewProps } from "@tiptap/react";
+import { useEffect, useRef, useSyncExternalStore, type Key, type KeyboardEvent } from "react";
+import {
+  Menu,
+  MenuButton,
+  MenuItem,
+  MenuSection,
+  MenuTrigger,
+} from "../../../components/overlays/Menu.js";
+import { useMessages } from "../../../i18n/useMessages.js";
+import { ChevronDownIcon } from "../../../icons.js";
+import type { RichCodeBlockOptions } from "./codeBlock.js";
+import { CodeCopyButton } from "./CodeCopyButton.js";
+import { CODE_BLOCK_CLASS, CODE_HEADER_CLASS, CODE_LABEL_CLASS } from "./codeHeader.js";
+import {
+  CODE_LANGUAGES,
+  codeLanguage,
+  normalizeCodeLanguage,
+  type CodeLanguageId,
+} from "./codeLanguages.js";
+import { GLASS_MENU_CLASS } from "../../styles/glass.js";
+
+/** Атрибут кнопки языка у блока: по нему `Alt+F10` находит её в DOM блока. */
+export const CODE_LANGUAGE_TRIGGER = "data-code-language-trigger";
+
+/** Атрибут кнопки «Копировать»: по нему стрелки и `Alt+F10` ходят между кнопками шапки. */
+export const CODE_COPY_TRIGGER = "data-code-copy-trigger";
+
+/**
+ * Сменить язык блока на позиции `pos` — одной транзакцией, то есть одним шагом
+ * отмены. Шаг меняет только атрибут (`AttrStep`) и не задевает текст, поэтому
+ * история не склеивает его с набором перед ним: `Mod+Z` возвращает язык, а код
+ * остаётся (сторожит `tests/rich-text-editor-code-block.test.tsx`).
+ */
+function setCodeLanguage(editor: Editor, pos: number, language: CodeLanguageId | null) {
+  editor.view.dispatch(editor.state.tr.setNodeAttribute(pos, "language", language));
+}
+
+/** Ключ пункта «Обычный текст» в меню: у блока без языка имени нет. */
+const PLAIN_KEY = "plain";
+
+/*
+  RAC ставит триггеру меню `aria-haspopup="true"`; явное `menu` — как у меню
+  «Таблица» на Панели.
+*/
+const HAS_POPUP_MENU = { "aria-haspopup": "menu" } as object;
+
+/**
+ * Можно ли править Документ — по атрибуту `contenteditable` корня.
+ *
+ * ПОЧЕМУ НЕ `editor.isEditable` ОДИН РАЗ. `readOnly` и `disabled` меняются на
+ * лету через `setEditable` без транзакции, а представление узла перерисовывается
+ * только при смене самого узла: кнопка осталась бы у поля, которое уже нельзя
+ * править. ProseMirror отражает режим в `contenteditable` корня — за ним и следим.
+ */
+function useEditable(editor: Editor): boolean {
+  return useSyncExternalStore(
+    (notify) => {
+      const observer = new MutationObserver(notify);
+      observer.observe(editor.view.dom, {
+        attributes: true,
+        attributeFilter: ["contenteditable"],
+      });
+      return () => observer.disconnect();
+    },
+    () => editor.isEditable,
+    () => false
+  );
+}
+
+/**
+ * Блок кода в Редакторе: шапка с языком слева и «Копировать» справа, под ней код.
+ *
+ * ШАПКА — ХРОМ БЛОКА (`contentEditable={false}`): ProseMirror не ставит в неё
+ * каретку и не принимает её текст за содержимое блока; выделение и копия
+ * Документа её не захватывают (`select-none`). Полоса в потоке, а не поверх
+ * кода: первая строка не уходит под кнопки, как бы длинна ни была.
+ *
+ * Язык — `Menu` кита: стек оверлеев ADR-0041, стрелки, `Escape` и радиогруппа с
+ * отмеченным языком достаются от него. Имя — «Language: Python»: язык слышен на
+ * самой кнопке, не открывая меню. Выбор меняет язык одним шагом отмены и
+ * возвращает фокус в код.
+ *
+ * «КОПИРОВАТЬ» ЕСТЬ В ЛЮБОМ РЕЖИМЕ — и при `readOnly`, и при `disabled`: править
+ * нельзя, а скопировать код можно. Копируется `node.textContent`, то есть текст
+ * блока как набран, без токенов подсветки (они — декорации) и без хвостового
+ * перевода строки, которого в узле нет (ADR-0039: копируется текст, а не DOM).
+ *
+ * КЛАВИАТУРА. Обе кнопки вне обхода Tab (`tabindex="-1"`): иначе каждый блок
+ * кода добавлял бы две остановки между полем и следующим элементом формы. Вход —
+ * `Alt+F10` из блока (`codeBlock.ts`) на язык; `Alt+F10` или стрелка вправо —
+ * дальше, на «Копировать»; стрелка влево — назад; `Alt+F10` с «Копировать» — в
+ * Панель. `Escape` с любой из двух возвращает фокус в код, каретка там же, где
+ * была. Редактор только для чтения не принимает фокус в текст, и `Alt+F10` из
+ * блока недостижим, — там «Копировать» остаётся в обычном порядке Tab.
+ *
+ * Только чтение и выключенное поле — вместо кнопки языка подпись: менять нечего,
+ * а сказать, на каком языке код, по-прежнему стоит. У блока без языка подписи
+ * нет: «Обычный текст» — строка каталога, и нужна она кнопке меню, а не метке.
+ * Так же ведёт себя `RichTextView`, где каталога нет вовсе.
+ */
+export function CodeBlockView({ editor, node, getPos, extension }: NodeViewProps) {
+  const messages = useMessages().editor;
+  const editable = useEditable(editor);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const headerRef = useRef<HTMLDivElement>(null);
+  const language = codeLanguage(normalizeCodeLanguage(node.attrs.language));
+  const label = language?.label ?? messages.codeLanguagePlain;
+  const options = extension.options as RichCodeBlockOptions;
+
+  // `tabIndex` и `aria-keyshortcuts` RAC-кнопка пропами не принимает — ставим
+  // атрибутами, как `ImageToolbar` убирает лишнюю остановку у узла плагина.
+  useEffect(() => {
+    triggerRef.current?.setAttribute("tabindex", "-1");
+    triggerRef.current?.setAttribute("aria-keyshortcuts", "Alt+F10");
+  }, [editable]);
+
+  /*
+    Escape шапки — «обратно в код», и окно кита под Редактором его не получает.
+    Radix слушает Escape на документе в фазе перехвата, то есть раньше
+    `onKeyDown` шапки: внутри `Dialog` или `Drawer` уход из шапки закрывал окно,
+    стоило меню языка исчезнуть. Перехват на `window` идёт раньше документа;
+    `preventDefault` слой Radix читает как «закрывать не нужно», а всплытие не
+    останавливается — фокус в код вернёт `onKeyDown` ниже. Только у правки: без
+    неё каретки нет, и Escape с «Копировать» остаётся окну.
+  */
+  useEffect(() => {
+    const header = headerRef.current;
+    const view = header?.ownerDocument.defaultView;
+    if (!header || !view) return;
+    const keepLayer = (event: globalThis.KeyboardEvent) => {
+      if (event.key !== "Escape" || !editor.isEditable) return;
+      if (event.target instanceof Node && header.contains(event.target)) event.preventDefault();
+    };
+    view.addEventListener("keydown", keepLayer, true);
+    return () => view.removeEventListener("keydown", keepLayer, true);
+  }, [editor]);
+
+  const choose = (key: Key) => {
+    const pos = getPos();
+    if (pos === undefined || !editor.isEditable) return;
+    const id = key === PLAIN_KEY ? null : normalizeCodeLanguage(String(key));
+    if (id !== normalizeCodeLanguage(node.attrs.language)) setCodeLanguage(editor, pos, id);
+    /*
+      Фокус — в код таймером: react-aria после выбора возвращает фокус кнопке,
+      и поставленный сразу он ушёл бы обратно к ней. `view.focus()` вернёт
+      каретку туда, где она была до кнопки.
+    */
+    setTimeout(() => {
+      if (!editor.isDestroyed) editor.view.focus();
+    }, 0);
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    // Меню — в портале, но события React всплывают и из него: клавиши самого
+    // меню (его `Escape`) сюда не относятся. Подсказка — тоже в портале.
+    const target = event.target;
+    if (!(target instanceof HTMLElement)) return;
+    const onLanguage = target === triggerRef.current;
+    const onCopy = target.hasAttribute(CODE_COPY_TRIGGER);
+    if (!onLanguage && !onCopy) return;
+    const copy = headerRef.current?.querySelector<HTMLElement>(`[${CODE_COPY_TRIGGER}]`);
+    if (event.key === "Escape") {
+      event.preventDefault();
+      editor.view.focus();
+    } else if (event.key === "F10" && event.altKey) {
+      event.preventDefault();
+      if (onLanguage && copy) copy.focus();
+      else options.focusToolbar();
+    } else if (event.key === "ArrowRight" && onLanguage && copy) {
+      event.preventDefault();
+      copy.focus();
+    } else if (event.key === "ArrowLeft" && onCopy && triggerRef.current) {
+      event.preventDefault();
+      triggerRef.current.focus();
+    }
+  };
+
+  return (
+    <NodeViewWrapper className={CODE_BLOCK_CLASS}>
+      <div
+        ref={headerRef}
+        contentEditable={false}
+        className={CODE_HEADER_CLASS}
+        data-code-header=""
+        onKeyDown={onKeyDown}
+      >
+        {editable ? (
+          <MenuTrigger>
+            <MenuButton
+              ref={triggerRef}
+              variant="ghost"
+              size="sm"
+              aria-label={messages.codeLanguage({ current: label })}
+              className="h-6 px-1.5 font-sans text-xs"
+              {...{ [CODE_LANGUAGE_TRIGGER]: "" }}
+              {...HAS_POPUP_MENU}
+            >
+              {/* Подпись и шевроном в строку: `MenuButton` кладёт детей в один `span`. */}
+              <span className="inline-flex items-center gap-1">
+                {label}
+                <ChevronDownIcon size={12} aria-hidden />
+              </span>
+            </MenuButton>
+            {/* Имя меню react-aria берёт у кнопки (`aria-labelledby`): «Language: Python». */}
+            <Menu className={GLASS_MENU_CLASS} placement="bottom start" onAction={choose}>
+              <MenuSection selectionMode="single" selectedKeys={[language?.id ?? PLAIN_KEY]}>
+                <MenuItem id={PLAIN_KEY} textValue={messages.codeLanguagePlain}>
+                  {messages.codeLanguagePlain}
+                </MenuItem>
+                {CODE_LANGUAGES.map(({ id, label: name }) => (
+                  <MenuItem key={id} id={id} textValue={name}>
+                    {name}
+                  </MenuItem>
+                ))}
+              </MenuSection>
+            </Menu>
+          </MenuTrigger>
+        ) : (
+          <span className={CODE_LABEL_CLASS}>{language?.label}</span>
+        )}
+        <CodeCopyButton
+          code={node.textContent}
+          // Вне обхода Tab, пока Редактор правится: туда ведёт `Alt+F10`. Без
+          // каретки (только чтение, выключено) другого пути к кнопке нет.
+          tabIndex={editable ? -1 : undefined}
+          {...{ [CODE_COPY_TRIGGER]: "" }}
+        />
+      </div>
+      <pre>
+        <NodeViewContent<"code">
+          as="code"
+          className={language ? `language-${language.id}` : undefined}
+        />
+      </pre>
+    </NodeViewWrapper>
+  );
+}

package/src/editor/features/code/CodeCopyButton.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { CopyButton, type CopyButtonProps } from "../../../components/actions/CopyButton.js";
+import { Tooltip, TooltipProvider } from "../../../components/overlays/Tooltip.js";
+import { useMessages } from "../../../i18n/useMessages.js";
+import { cn } from "../../../lib/cn.js";
+
+/** Сколько держать «Скопировано» — столько же, сколько `CopyButton` по умолчанию. */
+const RESET_MS = 2000;
+
+export interface CodeCopyButtonProps extends Omit<
+  CopyButtonProps,
+  "value" | "children" | "onCopy" | "size" | "variant" | "resetDelay"
+> {
+  /** Текст блока строкой — то, что уйдёт в буфер (ADR-0039: копируется текст, а не DOM). */
+  code: string;
+}
+
+/**
+ * Кнопка «Копировать» в шапке блока кода: `CopyButton` кита с подсказкой
+ * «Copy code» → «Copied».
+ *
+ * ПОДСКАЗКА НЕ ЗАМЕНЯЕТ ИМЯ. Имя кнопки и объявление результата — дело
+ * `CopyButton` («Copy» → «Copied», живая область); подсказка лишь для глаз и
+ * уточняет, ЧТО копируется. Состояние для неё берётся из `onCopy`, а не из
+ * внутренностей кнопки.
+ *
+ * СВОЙ `TooltipProvider`, как у Панели и у панели картинки: корневой кит
+ * оставляет потребителю, а Редактор и просмотр без него падали бы на Radix.
+ * Подсказка вешается на обёртку — `CopyButton` сам ref не принимает.
+ */
+export function CodeCopyButton({ code, ...rest }: CodeCopyButtonProps) {
+  const messages = useMessages();
+  const [state, setState] = useState<"idle" | "copied" | "failed">("idle");
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timer.current != null) clearTimeout(timer.current);
+    },
+    []
+  );
+
+  const content =
+    state === "copied"
+      ? messages.copyButton.copied
+      : state === "failed"
+        ? messages.copyButton.failed
+        : messages.editor.codeCopy;
+
+  return (
+    <TooltipProvider>
+      <Tooltip content={content}>
+        <span className="inline-flex">
+          <CopyButton
+            {...rest}
+            value={code}
+            // Иконка — 12 px, как шеврон у кнопки языка напротив: шапка в
+            // строку текста `text-xs`, и стандартная иконка кнопки в ней
+            // выглядел крупнее подписи. Зону нажатия (24 px) держит `xs`.
+            className={cn("[&_svg]:size-3", rest.className)}
+            size="xs"
+            variant="ghost"
+            resetDelay={RESET_MS}
+            onCopy={(ok) => {
+              setState(ok ? "copied" : "failed");
+              if (timer.current != null) clearTimeout(timer.current);
+              timer.current = setTimeout(() => setState("idle"), RESET_MS);
+            }}
+          />
+        </span>
+      </Tooltip>
+    </TooltipProvider>
+  );
+}

package/src/editor/features/code/CodeCopyIsland.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { CodeCopyButton } from "./CodeCopyButton.js";
+
+export interface CodeCopyIslandProps {
+  /** Идентификатор просмотра: гнёзда его блоков помечены им же (`withCodeHeaders`). */
+  hostId: string;
+  /** Отпечаток HTML просмотра: сменился Документ — гнёзда новые, и остров ищет их заново. */
+  docKey: string;
+}
+
+interface Slot {
+  element: HTMLElement;
+  code: string;
+}
+
+/**
+ * Островок клиента у `RichTextView`: вставляет кнопку «Копировать» в гнёзда
+ * шапок блоков кода.
+ *
+ * ЗАЧЕМ ОН. `RichTextView` — серверный компонент, и обработчика клика у него
+ * быть не может. Шапка с подписью языка и пустым гнездом приходит в HTML от
+ * сервера; здесь, после монтирования, в каждое гнездо своего просмотра
+ * вставляется порталом `CodeCopyButton`. До гидрации и без JS кнопки нет, а
+ * документ читается так же.
+ *
+ * ЧТО КОПИРУЕТСЯ — `textContent` элемента `code` рядом с гнездом. Для текста
+ * без разметки и для блока, уже подсвеченного `highlightCodeBlocks` (токены —
+ * `span` внутри `code`), это один и тот же исходный код: токены текста не
+ * добавляют (ADR-0039: копируется текст, а не разметка).
+ *
+ * ГНЁЗДА ИЩУТСЯ ОТ СВОЕГО МЕСТА В ДЕРЕВЕ, а не по глобальному `document`. У
+ * серверного компонента нет ссылки, которую можно передать клиентскому, поэтому
+ * остров рисует пустой инертный `<template>` сразу за контейнером просмотра
+ * (`RichTextView` ставит их соседями) и после монтирования берёт его соседа
+ * слева. Так просмотр в теневом корне или в `iframe`, которых глобальный
+ * `document` не видит, получает свои кнопки, а обход идёт только по своему
+ * контейнеру, а не по всей странице. Идентификатор гнезда сверяется всё равно:
+ * гнездо с чужим идентификатором кнопку не получает.
+ *
+ * `<template>` есть и в разметке сервера, и в первом клиентском проходе, а
+ * порталы появляются только после эффекта — разметка сервера и гидрации
+ * совпадают. `<template>` браузер не показывает и в дерево доступности не
+ * кладёт; во флексе и гриде родителя он не занимает ячейку.
+ */
+export function CodeCopyIsland({ hostId, docKey }: CodeCopyIslandProps) {
+  const [slots, setSlots] = useState<Slot[]>([]);
+  const markerRef = useRef<HTMLTemplateElement>(null);
+
+  useEffect(() => {
+    const view = markerRef.current?.previousElementSibling;
+    const found = [...(view?.querySelectorAll<HTMLElement>("[data-code-copy]") ?? [])]
+      .filter((element) => element.dataset.codeCopy === hostId)
+      .map((element) => ({
+        element,
+        code: element.closest("[data-code-block]")?.querySelector("pre > code")?.textContent ?? "",
+      }));
+    setSlots(found);
+  }, [hostId, docKey]);
+
+  return (
+    <>
+      <template ref={markerRef} data-code-copy-island="" />
+      {slots.map(({ element, code }, index) =>
+        createPortal(<CodeCopyButton code={code} />, element, `${hostId}:${index}`)
+      )}
+    </>
+  );
+}