@olddevs/ui 0.0.0-stage → 4.0.1

package/src/editor/features/wrapper/wrapper.ts

@@ -0,0 +1,350 @@
+"use client";
+
+import { Extension, mergeAttributes, Node, type Extensions } from "@tiptap/core";
+import type { Node as PmNode } from "@tiptap/pm/model";
+import {
+  NodeSelection,
+  Selection,
+  TextSelection,
+  type EditorState,
+  type Transaction,
+} from "@tiptap/pm/state";
+import { containerFreeContext, placeContainerBlock, WRAPPER_NODE } from "../../core/containers.js";
+import type { EditorWrapperTone } from "../../../i18n/messages.js";
+import { WRAPPER_TONE_ALERTS, wrapperToneFrom } from "./wrapperTones.js";
+
+/**
+ * Обёртка — Блок, собирающий группу Блоков: `div[data-block="wrapper"]`,
+ * внутри — Блоки. Без тона своего вида у неё нет, как у Wrapper в Redactor: в
+ * Редакторе её показывает серый пунктир, читателю граница не нужна.
+ *
+ * РАЗМЕТКА — КАК У REDACTOR, БУКВА В БУКВУ: его HTML с обёрткой читается без
+ * перевода, а наш — им. Единственный свой атрибут — тон:
+ * `data-tone` с именем словаря `Tone` кита (`wrapperTones.ts`), вид для
+ * читателя — мягкая подложка и полоса тона (`prose.ts`), в Markdown — GitHub
+ * alert. Тон — оформление: роли и `aria-*` он в разметку не добавляет.
+ *
+ * ВЛОЖЕННОСТИ НЕТ НА УРОВНЕ СХЕМЫ ДВИЖКА, как у Раскладки (ADR-0056).
+ * Обёртка не входит в группу `block`: её принимают Документ и колонка
+ * Раскладки (их content-выражения называют её поимённо — `document.ts` и
+ * `layout.ts`), а сама она держит `block+`. Значит, ни Обёртки в Обёртке, ни
+ * Раскладки в Обёртке, ни Обёртки в списке, цитате или ячейке не получить ни
+ * вставкой, ни `value`, ни командой. Разбор HTML на такой случай снимает
+ * обёртку и отдаёт её Блоки подряд — правилом с `skip` в контексте контейнера.
+ * Вставка из буфера разбирается в контексте места вставки, поэтому то же
+ * правило разворачивает и её: своего `transformPasted`, как у Раскладки, не
+ * нужно.
+ *
+ * `isolating`, как у колонки: Backspace в начале Обёртки не выводит текст
+ * наружу и не сливает его с Блоком выше, а «Превратить в» не перешагивает её
+ * границу. Флаг `blockContainer` (`blockCommands.ts`): Блоки внутри — со своей
+ * ручкой у левого края Обёртки, и их команды из неё не выходят.
+ *
+ * Решение — ADR-0057.
+ */
+
+/** Имя узла Обёртки в Схеме движка (определено в `containers.ts`). */
+export { WRAPPER_NODE };
+
+const WRAPPER_TAG = 'div[data-block="wrapper"]';
+
+/**
+ * Контейнеры, где Обёртки нет: другая Обёртка, цитата, пункт списка и ячейка
+ * (`containers.ts`). Колонки Раскладки здесь нет — Обёртку она принимает.
+ */
+const NO_WRAPPER_CONTEXT = containerFreeContext();
+
+export const Wrapper = Node.create({
+  name: WRAPPER_NODE,
+  content: "block+",
+  isolating: true,
+  extendNodeSchema: (extension) =>
+    extension.name === WRAPPER_NODE ? { blockContainer: true } : {},
+  /*
+    Тон — имя из словаря `Tone` кита в `data-tone`; без тона
+    атрибута нет. Неизвестное значение разбор отбрасывает, Обёртка остаётся.
+  */
+  addAttributes: () => ({
+    tone: {
+      default: null,
+      parseHTML: (element) => wrapperToneFrom(element.getAttribute("data-tone")),
+      renderHTML: ({ tone }) => (tone ? { "data-tone": tone } : {}),
+    },
+  }),
+  parseHTML: () => [
+    { tag: WRAPPER_TAG, context: NO_WRAPPER_CONTEXT, skip: true, priority: 60 },
+    { tag: WRAPPER_TAG },
+  ],
+  renderHTML: ({ HTMLAttributes }) => [
+    "div",
+    mergeAttributes({ "data-block": "wrapper" }, HTMLAttributes),
+    0,
+  ],
+  /*
+    Обёртка с тоном — GitHub alert: цитата, первой строкой метка
+    тона (`> [!NOTE]`), дальше её Блоки с `> ` в начале строки, пустая строка
+    между Блоками — `>`, как у цитаты движка. Без тона в Markdown Обёртке нечем
+    быть: Блоки выгружаются подряд. Обратно alert читает `markdown.ts`.
+  */
+  renderMarkdown: (node, helpers) => {
+    const blocks = node.content ? helpers.renderChildren(node.content, "\n\n") : "";
+    const tone = wrapperToneFrom(node.attrs?.tone);
+    if (!tone) return blocks;
+    // Пустая строка Блоков — голый `>`; строка из одних пробелов (в блоке кода)
+    // остаётся с ними, иначе обратный разбор их потерял бы.
+    const lines = blocks.split("\n").map((line) => (line === "" ? ">" : `> ${line}`));
+    // Линия (`---`) или `===` прямо под строкой метки — подчёркивание заголовка:
+    // метка стала бы `<h2>`, а alert — цитатой. Пустая строка цитаты их разделяет.
+    const label = `> [!${WRAPPER_TONE_ALERTS[tone]}]`;
+    const setext = /^> *(?:-+|=+) *$/.test(lines[0] ?? "");
+    return [label, ...(setext ? [">"] : []), ...lines].join("\n");
+  },
+
+  addCommands() {
+    return {
+      insertWrapper:
+        () =>
+        ({ tr, dispatch }) => {
+          if (dispatch) placeWrapper(tr);
+          return true;
+        },
+      unwrapWrapper:
+        () =>
+        ({ tr, dispatch }) => {
+          const found = wrapperAt(tr.selection);
+          if (!found) return false;
+          if (dispatch) unwrap(tr, found.pos, found.node);
+          return true;
+        },
+      setWrapperTone:
+        (tone) =>
+        ({ tr, dispatch }) => {
+          const found = wrapperAt(tr.selection);
+          // Имя вне словаря команда не пишет: её зовёт и код потребителя.
+          const value = wrapperToneFrom(tone);
+          if (!found || (tone !== null && value === null)) return false;
+          // Один шаг атрибута: позиции и выделение не сдвигаются, отмена — одна.
+          if (dispatch) tr.setNodeAttribute(found.pos, "tone", value);
+          return true;
+        },
+    };
+  },
+});
+
+declare module "@tiptap/core" {
+  interface Commands<ReturnType> {
+    wrapper: {
+      /**
+       * Вставить пустую Обёртку с одним абзацем под текущим Блоком; пустой
+       * абзац в Документе или колонке заменяется. Из колонки — в той же
+       * колонке, из Обёртки, списка, цитаты и ячейки — под их Блоком. Каретка
+       * — в абзац Обёртки.
+       */
+      insertWrapper: () => ReturnType;
+      /**
+       * Снять Обёртку под выделением: её Блоки встают на её место. Не в
+       * Обёртке — `false`.
+       */
+      unwrapWrapper: () => ReturnType;
+      /**
+       * Тон Обёртки под выделением: имя из словаря тонов или `null`
+       * — без тона. Не в Обёртке или имя вне словаря — `false`.
+       */
+      setWrapperTone: (tone: EditorWrapperTone | null) => ReturnType;
+    };
+  }
+}
+
+/** Обёртка под выделением: выделенная узлом или та, в которой каретка. */
+export function wrapperAt(selection: Selection): { pos: number; node: PmNode } | null {
+  if (selection instanceof NodeSelection && selection.node.type.name === WRAPPER_NODE) {
+    return { pos: selection.from, node: selection.node };
+  }
+  const { $from } = selection;
+  for (let depth = $from.depth; depth > 0; depth--) {
+    const node = $from.node(depth);
+    if (node.type.name === WRAPPER_NODE) return { pos: $from.before(depth), node };
+  }
+  return null;
+}
+
+/**
+ * Снять Обёртку Блока `pos` — самого Блока-Обёртки или Блока прямо в ней:
+ * действие меню Ручки (`features/builtins.ts`), у которого вместо выделения — позиция.
+ */
+export function unwrapWrapperAt(tr: Transaction, pos: number): boolean {
+  const node = tr.doc.nodeAt(pos);
+  if (node?.type.name === WRAPPER_NODE) {
+    unwrap(tr, pos, node);
+    return true;
+  }
+  const $pos = tr.doc.resolve(pos);
+  if ($pos.parent.type.name !== WRAPPER_NODE) return false;
+  unwrap(tr, $pos.before(), $pos.parent);
+  return true;
+}
+
+/**
+ * Пустая Обёртка с одним абзацем — под текущим Блоком, в ближайшем вверх
+ * контейнере, который её принимает (Документ или колонка Раскладки); правила
+ * места — общие с Раскладкой (`placeContainerBlock`, `containers.ts`).
+ */
+function placeWrapper(tr: Transaction): void {
+  const { schema } = tr.doc.type;
+  placeContainerBlock(
+    tr,
+    schema.nodes[WRAPPER_NODE]!.create(null, schema.nodes.paragraph!.create())
+  );
+}
+
+/**
+ * Снять Обёртку в `pos`: её Блоки поднимаются на уровень выше одним шагом
+ * `lift`, поэтому каретка внутри них остаётся на своём месте, а отмена — одна.
+ * Выделенная узлом Обёртка исчезает — каретка встаёт в начало её первого Блока.
+ */
+function unwrap(tr: Transaction, pos: number, node: PmNode): void {
+  // Выделена сама Обёртка, а не картинка в ней: картинку выделение сохраняет.
+  const wasNode = tr.selection instanceof NodeSelection && tr.selection.from === pos;
+  const $start = tr.doc.resolve(pos + 1);
+  const $end = tr.doc.resolve(pos + node.nodeSize - 1);
+  const range = $start.blockRange($end);
+  if (!range) return;
+  tr.lift(range, range.depth - 1);
+  if (wasNode) tr.setSelection(Selection.near(tr.doc.resolve(pos), 1));
+  tr.scrollIntoView();
+}
+
+/**
+ * Enter в пустом последнем абзаце Обёртки, где есть и другие Блоки, —
+ * выход: абзац переезжает под Обёртку, каретка — с ним. Одна правка. Без
+ * этого из Обёртки в конце Документа не выйти без мыши: `isolating` не даёт
+ * ядру поднять пустой абзац наружу, и Enter только множил бы пустые строки.
+ */
+function exitOnEnter(state: EditorState, dispatch?: (tr: Transaction) => void): boolean {
+  const { selection } = state;
+  if (!(selection instanceof TextSelection) || !selection.empty) return false;
+  const { $from } = selection;
+  if ($from.depth < 2) return false;
+  const wrapper = $from.node(-1);
+  const block = $from.parent;
+  if (
+    wrapper.type.name !== WRAPPER_NODE ||
+    block.type.name !== "paragraph" ||
+    block.content.size > 0 ||
+    wrapper.childCount < 2 ||
+    $from.indexAfter(-1) !== wrapper.childCount
+  ) {
+    return false;
+  }
+  if (dispatch) {
+    const tr = state.tr;
+    const after = $from.after(-1);
+    tr.delete($from.before(), $from.after());
+    const pos = tr.mapping.map(after);
+    tr.insert(pos, block.type.create());
+    tr.setSelection(TextSelection.create(tr.doc, pos + 1));
+    dispatch(tr.scrollIntoView());
+  }
+  return true;
+}
+
+/** Выход из Обёртки по Enter — раньше ядра: его Enter разрезал бы абзац внутри. */
+const WrapperKeys = Extension.create({
+  name: "wrapperKeys",
+  priority: 101,
+  addKeyboardShortcuts() {
+    return {
+      Enter: () =>
+        this.editor.isEditable && exitOnEnter(this.editor.state, this.editor.view.dispatch),
+    };
+  },
+});
+
+/**
+ * Каретка в самом начале Обёртки (`dir < 0`) или в самом конце (`dir > 0`), с
+ * пустым выделением: на краю текста, и каждый предок текстового Блока до
+ * Обёртки — крайний в своём родителе.
+ */
+function atWrapperBoundary(state: EditorState, dir: 1 | -1): boolean {
+  const { selection } = state;
+  if (!(selection instanceof TextSelection) || !selection.empty) return false;
+  const { $head } = selection;
+  const atTextEdge =
+    dir < 0 ? $head.parentOffset === 0 : $head.parentOffset === $head.parent.content.size;
+  if (!atTextEdge) return false;
+  for (let depth = $head.depth - 1; depth > 0; depth--) {
+    const parent = $head.node(depth);
+    const atEdge =
+      dir < 0 ? $head.index(depth) === 0 : $head.indexAfter(depth) === parent.childCount;
+    if (!atEdge) return false;
+    if (parent.type.name === WRAPPER_NODE) return true;
+  }
+  return false;
+}
+
+/**
+ * Backspace в единственном пустом абзаце Обёртки — Обёртка уходит целиком:
+ * на её месте остаётся этот абзац, каретка в нём. Одна правка. Иначе пустую
+ * Обёртку с клавиатуры не убрать: охрана границы ниже глотает Backspace, а
+ * выделить её узлом можно только с Блока под ней. Текста в ней нет, так что
+ * правило охраны — «не выводить текст наружу» — не нарушается. В колонке
+ * Раскладки абзац остаётся в той же колонке: это её Блок, а не Документа.
+ *
+ * Delete симметрично не снимает Обёртку: им удаляют то, что ПОСЛЕ каретки, а
+ * в конце Обёртки за ней — граница, а не её содержимое.
+ */
+function removeEmptyWrapper(state: EditorState, dispatch?: (tr: Transaction) => void): boolean {
+  const { selection } = state;
+  if (!(selection instanceof TextSelection) || !selection.empty) return false;
+  const { $from } = selection;
+  if ($from.depth < 2) return false;
+  const wrapper = $from.node(-1);
+  const block = $from.parent;
+  if (
+    wrapper.type.name !== WRAPPER_NODE ||
+    wrapper.childCount !== 1 ||
+    block.type.name !== "paragraph" ||
+    block.content.size > 0
+  ) {
+    return false;
+  }
+  if (dispatch) {
+    const pos = $from.before(-1);
+    const tr = state.tr.replaceWith(pos, $from.after(-1), block);
+    tr.setSelection(TextSelection.create(tr.doc, pos + 1));
+    dispatch(tr.scrollIntoView());
+  }
+  return true;
+}
+
+/**
+ * Backspace в начале Обёртки и Delete в её конце — последними, после всех
+ * правил ядра (как у колонки Раскладки, `layout.ts`). Пустой заголовок ядро
+ * ещё превращает в абзац, пункт списка — выносит из списка. Единственный
+ * пустой абзац Backspace снимает вместе с Обёрткой (`removeEmptyWrapper`).
+ * Если же никто не взялся, клавиша поглощается: `isolating` не даёт командам
+ * ProseMirror вытащить текст из Обёртки, и без поглощения правку сделал бы
+ * сам браузер — по DOM, мимо Схемы.
+ *
+ * Обёртка в колонке: здесь срабатывает раньше охраны колонки с тем же
+ * приоритетом — из равных Tiptap первым опрашивает зарегистрированное позже
+ * (`extensions.ts`), а Обёртка идёт после Раскладки.
+ */
+const WrapperBoundary = Extension.create({
+  name: "wrapperBoundary",
+  priority: 1,
+  addKeyboardShortcuts() {
+    const guard = (dir: 1 | -1) => () =>
+      this.editor.isEditable && atWrapperBoundary(this.editor.state, dir);
+    return {
+      Backspace: () =>
+        (this.editor.isEditable &&
+          removeEmptyWrapper(this.editor.state, this.editor.view.dispatch)) ||
+        guard(-1)(),
+      Delete: guard(1),
+    };
+  },
+});
+
+/** Всё, что нужно Обёртке, кроме Документа (`document.ts`): узел и клавиатура. */
+export const WRAPPER_EXTENSIONS: Extensions = [Wrapper, WrapperKeys, WrapperBoundary];

package/src/editor/features/wrapper/wrapperTones.ts

@@ -0,0 +1,51 @@
+import type { EditorWrapperTone } from "../../../i18n/messages.js";
+
+/**
+ * Тоны Обёртки — ДАННЫМИ: их читают Схема-данные и очистка на
+ * сервере (`schema.ts`), узел Обёртки и Markdown Редактора (`wrapper.ts`,
+ * `markdown.ts`), меню ручки и гейт контраста (`scripts/contrast.mjs`).
+ *
+ * ИМЕНА — СЛОВАРЬ `Tone` КИТА, а не слова меню. В Документ уходит
+ * `data-tone="warning"`: имя переживает смену подписи и языка интерфейса, а
+ * значение цвета подставляет тема, как у `data-color` (`palette.ts`). Подписи
+ * меню — словами GitHub alerts («Заметка», «Совет», «Важно», «Внимание»,
+ * «Осторожно»): тон выбирают по смыслу заметки, а не по цвету.
+ *
+ * Порядок — порядок меню и GitHub alerts: NOTE, TIP, IMPORTANT, WARNING,
+ * CAUTION.
+ *
+ * Модуль серверно-безопасен: данные и чистые функции, без движка.
+ */
+export const EDITOR_WRAPPER_TONES = [
+  "accent",
+  "success",
+  "neutral",
+  "warning",
+  "danger",
+] as const satisfies readonly EditorWrapperTone[];
+
+const known: ReadonlySet<string> = new Set(EDITOR_WRAPPER_TONES);
+
+/**
+ * Тон из атрибута `data-tone` или `null`. Значение — точно, как его пишет
+ * Редактор: `Accent`, ` accent` и имена вне словаря отбрасываются, Обёртка
+ * остаётся без тона.
+ */
+export function wrapperToneFrom(value: unknown): EditorWrapperTone | null {
+  return typeof value === "string" && known.has(value) ? (value as EditorWrapperTone) : null;
+}
+
+/**
+ * Метка GitHub alert для тона: Обёртка с тоном в Markdown — цитата с этой
+ * меткой первой строкой (`> [!NOTE]`). Соответствие — по смыслу метки, как в
+ * меню: NOTE — акцент, TIP — успех, IMPORTANT — нейтральный (у GitHub он
+ * фиолетовый, но такого тона у кита нет), WARNING — предупреждение, CAUTION —
+ * опасность.
+ */
+export const WRAPPER_TONE_ALERTS = {
+  accent: "NOTE",
+  success: "TIP",
+  neutral: "IMPORTANT",
+  warning: "WARNING",
+  danger: "CAUTION",
+} as const satisfies Record<EditorWrapperTone, string>;

package/src/editor/highlight-entry.ts

@@ -0,0 +1,23 @@
+/**
+ * Лёгкий вход `@olddevs/ui/editor/highlight`: подсветка кода без Редактора —
+ * и больше ничего.
+ *
+ * - `highlightCodeBlocks` — серверная подсветка блоков кода в сохранённом
+ *   Документе для `RichTextView` (ADR-0051).
+ * - `highlightCodeNodes` — токены узлами React для `children` у `CodeView`
+ *   (ADR-0052).
+ *
+ * ПОЧЕМУ ОТДЕЛЬНЫЙ ВХОД, А НЕ ПРОП `highlight` У `RichTextView` ИЛИ `language`
+ * У `CodeView`. Подсветка — lowlight, ядро highlight.js и восемь грамматик,
+ * 22,6 кБ gzip. Импорт не бывает условным: проп-флаг держал бы их в графе
+ * компонента всегда, и показ Документа вырос бы с 2 кБ до 23 даже там, где
+ * подсветка выключена. Здесь подсветчик приезжает только к тому, кто его
+ * импортировал, — обычно к серверу, — а компоненты остаются крошечными: они
+ * получают уже подсвеченные HTML или узлы.
+ * Граф входа сторожит `tests/editor-highlight-entry.test.ts`.
+ *
+ * Директивы `"use client"` нет: модуль только реэкспортирует серверно-безопасные
+ * функции.
+ */
+export { highlightCodeBlocks } from "./features/code/highlight.js";
+export { highlightCodeNodes } from "./features/code/highlightNodes.js";

package/src/editor/highlight-grammars.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Типы грамматик highlight.js по одной: пакет отдаёт `lib/languages/*` через
+ * `exports`, но без `.d.ts` рядом, и в строгом режиме импорт падал бы с TS7016.
+ * Каждая грамматика — функция `LanguageFn` по умолчанию; так её и описывают
+ * типы самого highlight.js. В `dist` объявление не нужно: наружу типы
+ * грамматик не выходят (`lowlight.ts` их не экспортирует).
+ */
+declare module "highlight.js/lib/languages/*" {
+  import type { LanguageFn } from "highlight.js";
+  const grammar: LanguageFn;
+  export default grammar;
+}

package/src/editor/hooks/useChangeThrottle.ts

@@ -0,0 +1,62 @@
+"use client";
+
+// Происхождение: minimal-tiptap, `hooks/use-throttle.ts` (MIT, © 2024 Aslam,
+// https://github.com/Aslam97/minimal-tiptap). Переписан: добавлены `flush` и
+// `cancel`, вызов идёт по заднему фронту. Лицензия — NOTICE в корне пакета.
+
+import { useCallback, useEffect, useMemo, useRef } from "react";
+
+/**
+ * Не чаще раза в `delay` мс — и только по заднему фронту.
+ *
+ * ПОЧЕМУ ЗАДНИЙ ФРОНТ, А НЕ ПЕРЕДНИЙ, как в оригинале. Отдать значение — значит
+ * сериализовать документ в HTML, а это проход по всему дереву. Передний фронт
+ * платил бы его на первой же букве после паузы, то есть почти на каждой при
+ * обычном наборе. Задний копит правки и сериализует один раз, когда набор
+ * улёгся, — `emit` читает документ сам, в момент вызова, а не получает
+ * значение, посчитанное на каждую букву.
+ *
+ * `flush` — то же самое, но сейчас и только если что-то ждёт: на `blur` и
+ * перед отправкой формы значение обязано быть свежим, а не отставать на
+ * `delay`. `cancel` — отказ от ожидающего вызова, когда документ заменили
+ * снаружи и отдавать прежнюю правку уже нечего.
+ *
+ * Размонтирование тоже сбрасывает ожидание: иначе последние буквы перед
+ * закрытием формы молча терялись бы.
+ */
+export function useChangeThrottle(emit: () => void, delay: number) {
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const emitRef = useRef(emit);
+  emitRef.current = emit;
+
+  const flush = useCallback(() => {
+    if (timer.current === null) return;
+    clearTimeout(timer.current);
+    timer.current = null;
+    emitRef.current();
+  }, []);
+
+  const cancel = useCallback(() => {
+    if (timer.current === null) return;
+    clearTimeout(timer.current);
+    timer.current = null;
+  }, []);
+
+  const schedule = useCallback(() => {
+    if (delay <= 0) {
+      emitRef.current();
+      return;
+    }
+    if (timer.current !== null) return;
+    timer.current = setTimeout(() => {
+      timer.current = null;
+      emitRef.current();
+    }, delay);
+  }, [delay]);
+
+  useEffect(() => flush, [flush]);
+
+  // Один объект на всю жизнь при неизменной задержке: эффекты потребителя
+  // держат его в зависимостях и не должны перезапускаться на каждом рендере.
+  return useMemo(() => ({ schedule, flush, cancel }), [schedule, flush, cancel]);
+}

package/src/editor/hooks/useCoarsePointer.ts

@@ -0,0 +1,36 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+
+const QUERY = "(pointer: coarse)";
+
+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;
+}
+
+/**
+ * Основной указатель — палец (`pointer: coarse`): телефон, планшет.
+ *
+ * ПОЧЕМУ JS, А НЕ МЕДИАЗАПРОС В CSS. Медиазапрос спрятал бы плавающую Панель,
+ * но не заменил бы её фиксированной: это разные узлы с разной раскладкой, и
+ * выбор между ними — ветка рендера. До гидратации ветки нет вовсе — движок и
+ * Панели появляются только в браузере (`immediatelyRender: false`), — поэтому
+ * мигания «не та Панель до гидратации» здесь не бывает.
+ *
+ * Подписка, а не разовый замер: планшет с подключённой мышью и ноутбук-
+ * трансформер меняют основной указатель на лету.
+ *
+ * На сервере и без `matchMedia` — `false`: устройство неизвестно, и
+ * остаётся то, что выбрал потребитель.
+ */
+export function useCoarsePointer(): boolean {
+  return useSyncExternalStore(subscribe, snapshot, () => false);
+}

package/src/editor/hooks/useFieldsetDisabled.ts

@@ -0,0 +1,53 @@
+"use client";
+
+import { useEffect, useState, type RefObject } from "react";
+
+/**
+ * Лежит ли узел внутри выключенного `<fieldset disabled>` — и следит за ним.
+ *
+ * ЗАЧЕМ DOM, А НЕ КОНТЕКСТ. Кит выключает форму на время запроса именно через
+ * `<fieldset disabled>` (`Form pending`), и поле, которое смотрит в `Form`,
+ * остаётся слепым к любому чужому `fieldset` — а потребитель вправе
+ * выключить группу полей сам. Родные поля реагируют на оба случая одинаково, и
+ * чтобы редактор не отличался, он читает то, что читает браузер, — атрибут
+ * предка. Второй канал через контекст `Form` дублировал бы это правило и всё
+ * равно не покрыл бы чужие `fieldset`.
+ *
+ * Обход идёт по предкам, а не по ближайшему `fieldset`: вложенный в выключенный
+ * тоже выключен. Исключение браузера повторено — потомки ПЕРВОГО `<legend>`
+ * выключенного набора остаются доступными.
+ *
+ * Переключения ловит `MutationObserver` на атрибуте `disabled` каждого предка:
+ * `Form pending` переключает его без перемонтажа детей. Перенос самого узла в
+ * другой `fieldset` не отслеживается — такое DOM-перемещение React не делает.
+ */
+export function useFieldsetDisabled(ref: RefObject<HTMLElement | null>): boolean {
+  const [disabled, setDisabled] = useState(false);
+
+  useEffect(() => {
+    const node = ref.current;
+    if (!node) return;
+
+    const fieldsets: HTMLFieldSetElement[] = [];
+    for (let el = node.parentElement; el; el = el.parentElement) {
+      if (el.localName === "fieldset") fieldsets.push(el as HTMLFieldSetElement);
+    }
+    if (fieldsets.length === 0) return;
+
+    const inFirstLegend = (fieldset: HTMLFieldSetElement) =>
+      Array.from(fieldset.children)
+        .find((child) => child.localName === "legend")
+        ?.contains(node) ?? false;
+    const read = () =>
+      setDisabled(fieldsets.some((fieldset) => fieldset.disabled && !inFirstLegend(fieldset)));
+
+    read();
+    const observer = new MutationObserver(read);
+    for (const fieldset of fieldsets) {
+      observer.observe(fieldset, { attributes: true, attributeFilter: ["disabled"] });
+    }
+    return () => observer.disconnect();
+  }, [ref]);
+
+  return disabled;
+}

package/src/editor/hooks/useRichTextEditorState.ts

@@ -0,0 +1,51 @@
+"use client";
+
+import { useEditorState, type Editor } from "@tiptap/react";
+import { useCallback, useEffect, useSyncExternalStore, type RefObject } from "react";
+import { watchHandleEditor } from "../core/handle.js";
+import type { RichTextEditorHandle } from "../RichTextEditor.js";
+
+/**
+ * Срез состояния Редактора для своей панели экрана: активные Метки, возможность
+ * команды, выделение — всё, что `selector` вычислит из `editor`.
+ *
+ * ПЕРЕРИСОВКА — ТОЛЬКО ПРИ СМЕНЕ СРЕЗА. Хук сидит на `useEditorState` Tiptap:
+ * селектор считается на каждую транзакцию, а компонент перерисовывается, когда
+ * результат стал другим (сравнение по значению, поэтому селектор вправе вернуть
+ * объект). Набор текста, не меняющий срез, панель не трогает.
+ *
+ * БЕЗОПАСЕН ДО МОНТАЖА И ПРИ SSR. Пока движка нет — на сервере, в первом рендере
+ * экрана — возвращает `null`, селектор не вызывается. Когда движок появится,
+ * экран перерисуется сам. Один и тот же `ref` отдаётся в `RichTextEditor`.
+ *
+ * Команды панели вызываются через `ref.current.editor.chain().focus()…run()`;
+ * кнопкам панели нужен `preventDefault` на `mousedown`, иначе клик снимет фокус.
+ *
+ * @example
+ * const ref = useRef<RichTextEditorHandle>(null);
+ * const state = useRichTextEditorState(ref, (editor) => ({ bold: editor.isActive("bold") }));
+ */
+export function useRichTextEditorState<T>(
+  ref: RefObject<RichTextEditorHandle | null>,
+  selector: (editor: Editor) => T
+): T | null {
+  const editor = useSyncExternalStore(
+    useCallback((listener) => watchHandleEditor(ref, listener), [ref]),
+    () => ref.current?.editor ?? null,
+    () => null
+  );
+  const state = useEditorState({
+    editor,
+    selector: ({ editor: current }) => (current ? selector(current) : null),
+  });
+  /*
+    `useEditorState` пересобирает снимок только на транзакции движка: у него
+    нет события на смену самого `editor`, и срез, взятый при `null`, оставался
+    бы прежним до первой правки. Пустая транзакция при появлении движка — то же,
+    что Редактор делает для плейсхолдера: документ и история не затронуты.
+  */
+  useEffect(() => {
+    if (editor && !editor.isDestroyed) editor.view.dispatch(editor.state.tr);
+  }, [editor]);
+  return state;
+}