@olddevs/ui 0.0.0-stage → 4.0.1

package/src/editor/hooks/useSubmenuPlacement.ts

@@ -0,0 +1,40 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+
+/** Уже `sm` (640): на такой ширине подменю сбоку от пункта не помещается. */
+const QUERY = "(max-width: 639px)";
+
+function subscribe(onChange: () => void): () => void {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return () => {};
+  const list = window.matchMedia(QUERY);
+  list.addEventListener("change", onChange);
+  return () => list.removeEventListener("change", onChange);
+}
+
+function snapshot(): boolean {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false;
+  return window.matchMedia(QUERY).matches;
+}
+
+/**
+ * Где открыть подменю Редактора: сбоку от пункта или под ним.
+ *
+ * Сбоку — привычно на десктопе. На телефоне места нет ни справа, ни слева:
+ * меню само занимает середину экрана, и react-aria, перевернув подменю на
+ * другую сторону, ширину его не ужимает — на iPhone сетка размера таблицы
+ * уехала за левый край. Поэтому на узком экране подменю встаёт под своим
+ * пунктом, поверх родительского меню, как в меню самого телефона; по
+ * поперечной оси react-aria его сдвигает в экран.
+ *
+ * Ширина, а не указатель (`useCoarsePointer`): дело в месте. Телефон,
+ * повёрнутый горизонтально, и планшет оставляют подменю сбоку.
+ *
+ * JS, а не CSS: место подменю — проп поповера, а не класс. Подписка — экран
+ * поворачивают на лету. На сервере и без `matchMedia` — сбоку: подменю
+ * открывается только в браузере, по действию пользователя.
+ */
+export function useSubmenuPlacement(): "bottom start" | "right top" {
+  const narrow = useSyncExternalStore(subscribe, snapshot, () => false);
+  return narrow ? "bottom start" : "right top";
+}

package/src/editor/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Отдельный вход для редактора форматированного текста: `@olddevs/ui/editor`.
+ *
+ * ПОЧЕМУ МИМО BARREL. Движок — Tiptap v3 на ProseMirror — в манифест кита не
+ * входит: его ставит только тот, кто импортирует этот вход, командой со
+ * страницы Редактора (раздел «Установка»). Остальные ничего не ставят, и
+ * бюджет основного входа не меняется. Реэкспорт из `src/index.ts`
+ * сделал бы Tiptap обязательным для каждого потребителя — сборка без него
+ * падала бы на неразрешимом импорте. Сторожит `tests/editor-entry.test.ts`.
+ *
+ * Директивы `"use client"` здесь нет намеренно, как у `color.ts`: модуль только
+ * реэкспортирует, а клиентский компонент несёт директиву сам. Вход заодно
+ * отдаёт серверно-безопасные `RichTextView` и `richTextSanitizeConfig`, и
+ * директива на входе увела бы их в клиентский граф.
+ *
+ * Решение — ADR-0050.
+ */
+export { RichTextEditor } from "./RichTextEditor.js";
+export type { RichTextEditorHandle, RichTextEditorProps } from "./RichTextEditor.js";
+export type { RichTextDocument } from "./core/jsonDocument.js";
+export { useRichTextEditorState } from "./hooks/useRichTextEditorState.js";
+export { RichTextView } from "./RichTextView.js";
+export type { RichTextViewProps } from "./RichTextView.js";
+export type { FieldNotice, FieldNoticeTone } from "./core/fieldNotice.js";
+export type { RichTextSurface } from "./styles/surface.js";
+export { richTextSanitizeConfig, richTextSchema, sanitizeRichText } from "./core/schema.js";
+export type {
+  RichTextAttributeHookEvent,
+  RichTextCustomBlockRules,
+  RichTextCustomMarkRules,
+  RichTextPurifier,
+  RichTextSanitizeConfig,
+  RichTextSchema,
+} from "./core/schema.js";
+export { RICH_TEXT_PRESETS } from "./core/tools.js";
+export type { RichTextEditorPreset } from "./core/tools.js";
+export { markRange } from "./core/customTool.js";
+export type {
+  TextCardRange,
+  TextCardRangeAt,
+  CustomAttribute,
+  CustomBlock,
+  CustomBlockAction,
+  CustomTextCard,
+  CustomTextCardRender,
+  CustomIslandProps,
+  CustomInsertItem,
+  CustomMark,
+  CustomTool,
+  CustomToolButton,
+  CustomToolLabel,
+  CustomToolPopover,
+  CustomTrigger,
+  PrefixedName,
+  TriggerContext,
+  TriggerItem,
+  ToolEntry as Tool,
+  ToolName,
+} from "./core/customTool.js";

package/src/editor/schema-entry.ts

@@ -0,0 +1,40 @@
+/**
+ * Лёгкий вход `@olddevs/ui/editor/schema`: Схема Редактора данными, очистка по
+ * ней (`sanitizeRichText` с DOMPurify потребителя) и закрытый конфиг для
+ * DOMPurify — и больше ничего.
+ *
+ * ПОЧЕМУ ОТДЕЛЬНО ОТ `@olddevs/ui/editor`. Очистка HTML — дело сервера
+ * потребителя (ADR-0050), и Node-процессу, которому нужен один конфиг, не нужны
+ * ни React, ни Tiptap. Вход `./editor` реэкспортирует редактор вместе с
+ * движком, а без сборщика (чистый Node, воркер, скрипт миграции) лишнее никто
+ * не отбросит. Здесь в графе модулей только `schema.ts` — данные и функция над
+ * ними. Сторожит `tests/editor-schema-entry.test.ts`.
+ *
+ * Свои Инструменты (ADR-0058, п. 2.3) сюда приходят массивом `tools` в
+ * `sanitizeRichText` и `richTextSchema`: читаются только правила Схемы из
+ * описания (`customTool.ts`, тоже без движка), Часть для движка не трогается.
+ * Описание своего Инструмента с Карточкой у текста собирается и на сервере,
+ * поэтому её помощник `markRange` (функция над состоянием, Tiptap — только
+ * типом) отдаётся и здесь.
+ *
+ * Те же имена по-прежнему отдаёт и `@olddevs/ui/editor`: это не перенос, а
+ * второй, короткий путь к тем же значениям. Список имён здесь явный, чтобы
+ * новый экспорт `schema.ts` попадал в публичный вход решением, а не случайно.
+ *
+ * Директивы `"use client"` нет, как у остальных входов-реэкспортов.
+ */
+export {
+  RICH_TEXT_SCHEMA,
+  richTextSanitizeConfig,
+  richTextSchema,
+  sanitizeRichText,
+} from "./core/schema.js";
+export { markRange } from "./core/customTool.js";
+export type {
+  RichTextAttributeHookEvent,
+  RichTextCustomBlockRules,
+  RichTextCustomMarkRules,
+  RichTextPurifier,
+  RichTextSanitizeConfig,
+  RichTextSchema,
+} from "./core/schema.js";

package/src/editor/styles/codeTheme.ts

@@ -0,0 +1,66 @@
+// Происхождение цветов: highlight.js, `styles/github.css` и `styles/github-dark.css`
+// (BSD-3-Clause, © 2006 Ivan Sagalaev, https://github.com/highlightjs/highlight.js).
+// Значения цветов перенесены в `styles.css`, соответствие классов `hljs-*` ролям —
+// сюда, Tailwind-классами. Лицензия — NOTICE в корне пакета.
+
+/**
+ * Тема подсветки блока кода (ADR-0051): GitHub Light в теме `light`,
+ * GitHub Dark в `dark` и `dim`. Это ВТОРАЯ СИСТЕМА ЦВЕТА кита, и живёт она
+ * только в блоке кода: токены кита ничего не знают о `hljs-*`, а тема
+ * подсветки — о токенах. Решение владельца — привычные цвета подсветки вместо
+ * сопоставления с токенами (ADR-0051, п. 5).
+ *
+ * ДВЕ ПОЛОВИНЫ, И КАЖДАЯ НА СВОЁМ МЕСТЕ.
+ *
+ * - ЦВЕТА — переменные `--rte-hl-*` и `--rte-code-block-*` в `styles.css`, на
+ *   элементах с `data-theme` (и на `:root` без него). Блок кода наследует их
+ *   от БЛИЖАЙШЕГО предка с темой, поэтому Документ во вложенной светлой
+ *   «бумаге» (`data-theme="light"` внутри тёмного приложения) получает GitHub
+ *   Light. Значения здесь не задаются намеренно: класс на контейнере
+ *   перебил бы унаследованное, и вложенная тема перестала бы работать.
+ * - ПРАВИЛА — эта строка классов, часть `PROSE_CLASS` на контейнере Документа
+ *   (Редактор и `RichTextView`), и та же строка — на корне токенов
+ *   `highlightCodeNodes` для `CodeView` (ADR-0052): роль токена →
+ *   переменная, и ничего про тему.
+ *   Tailwind потребителя находит классы в `dist` по той же строке `@source`,
+ *   что и остальные классы кита; ни CSS-модулей, ни отдельного файла стилей.
+ *   Только классы: в разметке ни одного `style`.
+ *
+ * ПОДЛОЖКА — ТЕМЫ, А НЕ КИТА. Цвета GitHub подобраны к своему фону (`#ffffff`
+ * и `#0d1117`); на подложке кода кита (`--bg-3`) тёмные тона не держат 4.5:1
+ * (ключевое слово — 3.95, комментарий — 3.24). Поэтому блок кода целиком
+ * берёт фон и основной цвет темы подсветки, а строчный `code` остаётся на
+ * токенах кита. Одно отступление от GitHub Light — `built_in` и `symbol`
+ * (`#953800` вместо `#e36209`, см. `styles.css`). `section`, `addition` и
+ * `deletion` не перенесены: их дают грамматики Markdown и diff, которых у
+ * Редактора нет (а `section` тёмной темы контраст не держит).
+ *
+ * ПОЧЕМУ `[class*=hljs-built]`, А НЕ `.hljs-built_in`. В произвольном варианте
+ * Tailwind `_` — это пробел, а `\_` попадает в имя класса с обратной косой и
+ * не совпадает с классом в разметке. Подстрока однозначна: других областей на
+ * `built` у highlight.js нет. По той же причине `this` и `self`
+ * (`hljs-variable language_`) ловятся как `.hljs-variable[class*=language]`.
+ *
+ * СОСТАВНЫЕ СЕЛЕКТОРЫ И ДЕКОРАЦИИ. В `RichTextView` токены вложены, как их
+ * отдал lowlight (`.hljs-meta > .hljs-string`), а декорации Редактора
+ * сплющивают вложенность в один `span class="hljs-meta hljs-string"`. Поэтому
+ * строка и ключевое слово названы ещё и парой классов (`.hljs-meta.hljs-string`)
+ * — это поднимает специфичность их группы над `.hljs-meta`, и одинаковый код
+ * красится одинаково в правке и на странице.
+ *
+ * Модуль серверно-безопасен: строка классов, без React и без движка.
+ */
+export const CODE_THEME_CLASS =
+  // Класс целиком в одной строке: Tailwind читает исходник как текст, и класс,
+  // разорванный `+`, он бы не нашёл.
+  "[&_:is(.hljs-doctag,.hljs-keyword,.hljs-template-tag,.hljs-template-variable,.hljs-type,.hljs-variable[class*=language],.hljs-meta.hljs-keyword)]:text-(--rte-hl-keyword) " +
+  "[&_.hljs-title]:text-(--rte-hl-title) " +
+  // Markdown: заголовок — цветом заголовка и жирным, как в теме GitHub; ссылка — подчёркнутой.
+  "[&_.hljs-section]:text-(--rte-hl-title) [&_.hljs-section]:font-bold [&_.hljs-link]:underline " +
+  "[&_:is(.hljs-attr,.hljs-attribute,.hljs-literal,.hljs-meta,.hljs-number,.hljs-operator,.hljs-variable,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-id)]:text-(--rte-hl-constant) " +
+  "[&_:is(.hljs-regexp,.hljs-string,.hljs-meta.hljs-string)]:text-(--rte-hl-string) " +
+  "[&_:is([class*=hljs-built],.hljs-symbol)]:text-(--rte-hl-variable) " +
+  "[&_:is(.hljs-comment,.hljs-code,.hljs-formula)]:text-(--rte-hl-comment) " +
+  "[&_:is(.hljs-name,.hljs-quote,.hljs-selector-tag,.hljs-selector-pseudo)]:text-(--rte-hl-tag) " +
+  "[&_.hljs-subst]:text-(--rte-code-block-foreground) [&_.hljs-bullet]:text-(--rte-hl-bullet) " +
+  "[&_.hljs-emphasis]:italic [&_.hljs-strong]:font-bold ";

package/src/editor/styles/glass.ts

@@ -0,0 +1,66 @@
+/**
+ * Стекло всплывающих поверхностей Редактора: полупрозрачная
+ * подложка своей поверхности с размытием того, что под ней.
+ *
+ * ЗНАЧЕНИЯ — КАК У ТОСТОВ (ADR-0010): 82 % цвета в `color-mix` и размытие в
+ * 14px. Это уже принятое стекло кита; второе со своими числами разошлось бы с
+ * ним при первой правке. Подсказка не в счёт: у неё свои 85 % и 10px, и
+ * Редактор её не трогает.
+ *
+ * ЦВЕТ — ТОКЕН СВОЕЙ ПОВЕРХНОСТИ, а не новый. Панель лежит на `bg-1`, списки
+ * меню — на `surface-elevated`, меню выделения — на инверсной; тема меняет
+ * токен, и стекло меняется вместе с ним без отдельных значений на тему. Внутри
+ * меню выделения переназначен только мост `--color-*` (`SelectionBubble.tsx`),
+ * а сырые `--bg-1` и `--surface-inverse` — нет, поэтому здесь читаются они.
+ *
+ * ПОЧЕМУ ТОЛЬКО РЕДАКТОР. Поверхности попадают сюда классом: `Menu` и
+ * `PopoverContent` принимают `className`, а `tailwind-merge` в `cn` снимает
+ * сплошную подложку панели. Те же компоненты вне Редактора остаются
+ * сплошными, и публичный API не меняется.
+ *
+ * СПЛОШНОЙ ФОЛБЭК. `prefers-reduced-transparency` (просьба системы убрать
+ * прозрачность) и `prefers-contrast: more` возвращают сплошной токен и
+ * снимают размытие: под полупрозрачной подложкой контраст текста зависит от
+ * того, что лежит под меню, и проверить его `scripts/contrast.mjs` не может.
+ *
+ * НА iOS — ТОЖЕ СПЛОШНАЯ. В Safari на iOS 27 меню Редактора вышли
+ * без подложки вовсе: пункты легли на текст Документа в полную силу. Подложку
+ * стеклянного элемента iOS-WebKit не нарисовал, а воспроизвести это вне
+ * устройства не вышло — безголовый WebKit размытие не рисует вовсе, и разницы
+ * не видно. Условие `@supports (-webkit-touch-callout: none)` понимает только
+ * WebKit на iOS (Chrome там — тот же WebKit), десктоп его не видит и стекло
+ * сохраняет.
+ */
+
+/*
+  ИМЕНА КЛАССОВ — ЦЕЛИКОМ, БЕЗ СБОРКИ ИЗ КУСКОВ. Tailwind (и у нас, и у
+  потребителя через `@source` на `dist`) находит класс только как целое слово
+  в исходнике. Подложка, собранная шаблонной строкой из имени токена, в CSS не
+  попадала: размытие было, а подложка оставалась прозрачной.
+*/
+
+/** Размытие и его снятие при просьбе убрать прозрачность или поднять контраст. */
+const BLUR =
+  "backdrop-blur-[14px] [@media(prefers-reduced-transparency:reduce)]:backdrop-blur-none " +
+  "contrast-more:backdrop-blur-none [@supports(-webkit-touch-callout:none)]:backdrop-blur-none";
+
+/** Плавающая Панель, панель картинки, поповеры Редактора — поверхность `bg-1`. */
+export const GLASS_PANEL_CLASS =
+  "bg-[color-mix(in_srgb,var(--bg-1)_82%,transparent)] " +
+  "[@media(prefers-reduced-transparency:reduce)]:bg-bg-1 contrast-more:bg-bg-1 " +
+  "[@supports(-webkit-touch-callout:none)]:bg-bg-1 " +
+  BLUR;
+
+/** Списки меню Редактора — поверхность `surface-elevated`, как у `Menu`. */
+export const GLASS_MENU_CLASS =
+  "bg-[color-mix(in_srgb,var(--surface-elevated)_82%,transparent)] " +
+  "[@media(prefers-reduced-transparency:reduce)]:bg-surface-elevated " +
+  "contrast-more:bg-surface-elevated [@supports(-webkit-touch-callout:none)]:bg-surface-elevated " +
+  BLUR;
+
+/** Меню выделения — инверсная поверхность. */
+export const GLASS_INVERSE_CLASS =
+  "bg-[color-mix(in_srgb,var(--surface-inverse)_82%,transparent)] " +
+  "[@media(prefers-reduced-transparency:reduce)]:bg-surface-inverse " +
+  "contrast-more:bg-surface-inverse [@supports(-webkit-touch-callout:none)]:bg-surface-inverse " +
+  BLUR;

package/src/editor/styles/palette.ts

@@ -0,0 +1,191 @@
+/**
+ * Палитры цвета текста и маркера Редактора ДАННЫМИ: имена, токены кита и
+ * выравнивания.
+ *
+ * ПАЛИТРЫ ДВЕ, И ИМЁН У НИХ НЕТ ОБЩИХ. Цвет текста — шесть тонов
+ * статуса кита; маркер — девять цветов: три ярких и шесть прежних. Оба пишутся в
+ * `data-color`, но на разных тегах: `span[data-color]` берёт имя из текстовой
+ * палитры, `mark[data-color]` — из палитры маркера. Имя чужой палитры на теге не
+ * принимается.
+ *
+ * ОДНА ТАБЛИЦА НА ЧЕТЫРЕХ ПОТРЕБИТЕЛЕЙ: Схема (`schema.ts`) берёт отсюда белый
+ * список имён, расширения (`extensions.ts`) — допустимые значения атрибутов,
+ * Панель (`EditorToolbar.tsx`) — набор образцов, а `scripts/contrast.mjs` —
+ * пары для проверки контраста. Имя цвета, добавленное в одном месте и
+ * забытое в другом, было бы молчаливым дефектом: образец есть, а в сохранённом
+ * HTML его нет. Поэтому место одно, а совпадение с классами `prose.ts` сторожит
+ * `tests/rich-text-editor-color.test.tsx`.
+ *
+ * ЗАЧЕМ ИМЕНА, А НЕ ЗНАЧЕНИЯ. В документ уходит `data-color="danger"`, а не
+ * `#eea8a0`: значение — дело темы (`dark`, `light`, `dim`), и один и тот же
+ * сохранённый текст читается в каждой из них. Имя уезжает в базу потребителя и
+ * переживает смену значений токенов.
+ *
+ * ЦВЕТ ТЕКСТА. `strong`-ступень тона подобрана под 4.5:1 на всех подложках
+ * приложения. Оттенки меток (`--label-*`) подбирались под 3:1 (кружок рядом с
+ * названием) и на `surface-elevated` в тёмных темах текстом не держат: синий
+ * 3.5, красный 3.56. Ценой стала привязка к акценту: `accent` — цвет бренда
+ * приложения, а не фиксированный синий. Индиго (`accent-alt`) в список не
+ * вошёл: токен не имеет `strong`-ступени и даёт 2.3–3.5:1 текстом.
+ *
+ * МАРКЕР. Яркий, как настоящий текстовыделитель: жёлтый
+ * `#ffea80`, ярко-зелёный `#aaff80`, розовый `#ff80bf`, одинаковые во всех темах
+ * (`dark`, `light`, `dim`) и на листе `surface="paper"`. Текст на маркере всегда
+ * тёмный — токен `--marker-text` (около 14:1 на жёлтом и зелёном, 7.5:1 на
+ * розовом), и порог 4.5:1 держит он, а не `fg-0`. Шесть прежних цветов Notion
+ * живут со своими значениями (`--marker-*` компонентного слоя, ADR-0003): у каждой
+ * темы своё, и текст на них — основной. Их снова предлагает меню
+ * (сетка «Цвет маркера», решение владельца) — см. `EDITOR_MARKERS`. Токен цветом
+ * статуса не назван и от акцента с брендом не зависит: `blue` не меняется вслед
+ * за `data-accent`.
+ *
+ * Модуль серверно-безопасен: данные, без React и без движка, и без импортов —
+ * `scripts/contrast.mjs` читает его напрямую.
+ */
+export const EDITOR_TEXT_COLORS = [
+  { name: "accent", text: "accent-strong" },
+  { name: "success", text: "success-strong" },
+  { name: "warning", text: "warning-strong" },
+  { name: "danger", text: "danger-strong" },
+  { name: "lime", text: "draft-strong" },
+  { name: "muted", text: "fg-2" },
+] as const;
+
+/** Имя цвета текста: то, что пишется в `span[data-color]`. */
+export type EditorTextColorName = (typeof EDITOR_TEXT_COLORS)[number]["name"];
+
+/** Имена цвета текста по порядку палитры — белый список `span[data-color]`. */
+export const EDITOR_TEXT_COLOR_NAMES: readonly EditorTextColorName[] = EDITOR_TEXT_COLORS.map(
+  (color) => color.name
+);
+
+/**
+ * Маркер: имя, токен подложки (`--marker-<имя>`) и признак «яркий».
+ *
+ * ВСЕ ДЕВЯТЬ В МЕНЮ (решение владельца). До того меню предлагало
+ * только три ярких, а шесть прежних цветов Notion оставались читаемыми: Схема,
+ * `RichTextView` и prose-стили их понимали, но выбрать их было нельзя. Сетка
+ * «Цвет маркера» кружками показывает все девять: цвет выбирают глазами, и
+ * девять различимых кружков — не перегруз, в отличие от девяти строк меню.
+ *
+ * ЯРКИЙ — ДРУГОЕ ОФОРМЛЕНИЕ ТЕКСТА. Подложка яркого (жёлтый, зелёный, розовый)
+ * одна во всех темах, и текст на нём всегда тёмный — `--marker-text`. Подложки
+ * прежних — свои у каждой темы (в тёмных — тёмные), текст на них основной. Это
+ * же различает пары в `scripts/contrast.mjs`.
+ *
+ * Порядок меню — порядок этого массива: по оттенку, как в Notion.
+ */
+export const EDITOR_MARKERS = [
+  { name: "gray", token: "marker-gray", bright: false },
+  { name: "brown", token: "marker-brown", bright: false },
+  { name: "orange", token: "marker-orange", bright: false },
+  { name: "yellow", token: "marker-yellow", bright: true },
+  { name: "green", token: "marker-green", bright: true },
+  { name: "blue", token: "marker-blue", bright: false },
+  { name: "purple", token: "marker-purple", bright: false },
+  { name: "pink", token: "marker-pink", bright: true },
+  { name: "red", token: "marker-red", bright: false },
+] as const;
+
+/** Имя маркера: то, что пишется в `mark[data-color]`. */
+export type EditorMarkerName = (typeof EDITOR_MARKERS)[number]["name"];
+
+/** Имена маркера по порядку меню — белый список `mark[data-color]`. */
+export const EDITOR_MARKER_NAMES: readonly EditorMarkerName[] = EDITOR_MARKERS.map(
+  (marker) => marker.name
+);
+
+/** Яркие маркеры: подложка одна во всех темах, текст на ней — `--marker-text`. */
+export const EDITOR_BRIGHT_MARKER_NAMES: readonly EditorMarkerName[] = EDITOR_MARKERS.filter(
+  (marker) => marker.bright
+).map((marker) => marker.name);
+
+/** Прежние маркеры Notion: подложка своя у каждой темы, текст на ней основной. */
+export const EDITOR_PALE_MARKER_NAMES: readonly EditorMarkerName[] = EDITOR_MARKERS.filter(
+  (marker) => !marker.bright
+).map((marker) => marker.name);
+
+/**
+ * Имена маркера ДО палитры Notion и их перевод в ближайший цвет.
+ *
+ * Прежний маркер делил имена с цветом текста и красил подложку `soft`-ступенью
+ * тона. Документы, сохранённые тогда, несут на `mark` одно из шести имён, и
+ * отбросить их значило бы молча снять подсветку с чужого текста. Поэтому имя
+ * переводится при загрузке и вставке, а `RichTextView` красит его тем же цветом
+ * (`prose.ts`), если сервер сохранил старый HTML как есть.
+ *
+ * Перевод — по оттенку подложки, а не по смыслу тона:
+ *
+ * - `accent` → `blue`: акцент кита синий (у бренда другой, но сохранённый
+ *   документ видел синий);
+ * - `success` → `green`, `danger` → `red`, `muted` → `gray`: одноимённые цвета;
+ * - `warning` → `yellow`: янтарь `warning-soft` ближе к жёлтому Notion, чем к
+ *   оранжевому — тот красноватее;
+ * - `lime` → `green`: подложка лайма читается зелёной (оттенок 83° лежит между
+ *   жёлтым и зелёным, но у `warning` жёлтый уже занят, и слить с ним «черновик»
+ *   значило бы отдать ему смысл предупреждения).
+ *
+ * Работает только на `mark`: на `span` цвета текста не переименовываются.
+ */
+export const LEGACY_MARKER_NAMES = {
+  accent: "blue",
+  success: "green",
+  warning: "yellow",
+  danger: "red",
+  lime: "green",
+  muted: "gray",
+} as const satisfies Record<EditorTextColorName, EditorMarkerName>;
+
+/** Имя маркера из атрибута `mark[data-color]`: новое как есть, старое — переведённое. */
+export function markerNameFromAttribute(value: string | null | undefined): EditorMarkerName | null {
+  if (value === null || value === undefined) return null;
+  if ((EDITOR_MARKER_NAMES as readonly string[]).includes(value)) return value as EditorMarkerName;
+  return Object.hasOwn(LEGACY_MARKER_NAMES, value)
+    ? LEGACY_MARKER_NAMES[value as keyof typeof LEGACY_MARKER_NAMES]
+    : null;
+}
+
+/**
+ * Выравнивание Блока. `left` — умолчание: атрибут не пишется, и документ без
+ * выравнивания остаётся таким, каким был до среза. `justify` намеренно нет:
+ * текст «по ширине» без переносов по слогам рвётся «реками» пробелов, а WCAG
+ * (1.4.8, AAA) советует его не использовать.
+ */
+export const EDITOR_ALIGNMENTS = ["left", "center", "right"] as const;
+
+/** Значение `data-align`. */
+export type EditorAlignment = (typeof EDITOR_ALIGNMENTS)[number];
+
+/** Выравнивание по умолчанию — то, что не пишется в атрибут. */
+export const DEFAULT_ALIGNMENT: EditorAlignment = "left";
+
+/**
+ * Выравнивание, которое пишется в Схему, из чужого атрибута: `center` или
+ * `right`; `left` (умолчание), `start`, `justify` и прочее — `null`.
+ */
+function writtenAlignment(value: string | null | undefined): EditorAlignment | null {
+  const normalized = value?.trim().toLowerCase();
+  return normalized === "center" || normalized === "right" ? normalized : null;
+}
+
+/**
+ * Выравнивание элемента входящего HTML (`value` и вставка).
+ *
+ * Своё — `data-align`, точным значением, как его пишет Редактор. Чужое
+ * читается тоже, но только переводом в имя Схемы: `style="text-align: …"` (так
+ * выравнивают Word, Excel и Google Docs) и устаревший атрибут `align`. Сами
+ * `style` и `align` в документ не попадают — на выходе только `data-align`.
+ */
+export function alignmentFromElement(element: HTMLElement): EditorAlignment | null {
+  const own = element.getAttribute("data-align");
+  if (own !== null) {
+    return (EDITOR_ALIGNMENTS as readonly string[]).includes(own) && own !== DEFAULT_ALIGNMENT
+      ? (own as EditorAlignment)
+      : null;
+  }
+  // Разбор строки, а не `element.style`: регистр имени свойства и пробелы
+  // вокруг двоеточия CSSOM разных сред (браузер, jsdom, сервер) понимает
+  // по-разному, а значение здесь нужно одно.
+  const style = /(?:^|;)\s*text-align\s*:\s*([a-z-]+)/i.exec(element.getAttribute("style") ?? "");
+  return writtenAlignment(style?.[1]) ?? writtenAlignment(element.getAttribute("align"));
+}