@olddevs/ui 0.0.0-stage → 4.0.0

package/src/editor/ui/TriggerMenu.tsx

@@ -0,0 +1,255 @@
+"use client";
+
+import type { Editor } from "@tiptap/react";
+import { useId, useMemo, useRef, useState, type ReactNode, type RefObject } from "react";
+import { useMessages, useUiLocale } from "../../i18n/useMessages.js";
+import { devError } from "../../lib/dev-warn.js";
+import type { TriggerItem } from "../core/customTool.js";
+import {
+  closeTrigger,
+  type SlashBridge,
+  type SlashSession,
+  type TriggerBinding,
+} from "../core/slashCommand.js";
+import { toolLabel, type TriggerRecord } from "../core/toolDescriptor.js";
+import { emptyRect, SuggestionList, suggestionOptionId } from "./SuggestionList.js";
+
+export interface TriggerMenu {
+  /** Символы и мосты для расширения; пусто — у набора нет своих триггеров. */
+  bindings: readonly TriggerBinding[];
+  /** Атрибуты поля — комбобокс-часть паттерна, как у Меню вставки. */
+  attributes: Record<string, string>;
+  /** Сам список — рисуется рядом с полем. */
+  element: ReactNode;
+}
+
+/** Открытая сессия: чей символ и что набрано. */
+interface Opened {
+  char: string;
+  session: SlashSession;
+}
+
+/**
+ * Списки своих символов-триггеров (ADR-0064): тот же `SuggestionList`, что у
+ * Меню вставки «/», — поповер у каретки, строки и «Ничего не найдено», фокус в
+ * поле, стрелки и `Enter` слушает движок и передаёт сюда мостом.
+ *
+ * Открыт может быть один список: символы разные, и набранное в Документе
+ * подходит под один. Пункты приходят от потребителя по запросу — сразу или
+ * промисом; ответ устаревшего запроса отбрасывается. Выбор отдаёт пункт и
+ * диапазон `символ+запрос` обработчику потребителя; удалять набранное он
+ * должен сам, заменив его своим узлом. После вызова список закрывается.
+ */
+export function useTriggerMenu(
+  triggers: readonly TriggerRecord[],
+  editorRef: RefObject<Editor | null>
+): TriggerMenu {
+  const messages = useMessages().editor;
+  const locale = useUiLocale();
+  const listboxId = useId();
+  const [opened, setOpened] = useState<Opened | null>(null);
+  const [found, setFound] = useState<readonly TriggerItem[]>([]);
+  // Ответ ещё идёт: пустой список не должен мигнуть «Ничего не найдено».
+  const [pending, setPending] = useState(false);
+  const [active, setActive] = useState(0);
+
+  /*
+    Движок спрашивает про клавишу посреди своего обработчика, а не через
+    рендер: поэтому то, что он читает, лежит в ref и обновляется каждым
+    рендером — и сразу в обработчиках, где состояние нужно до рендера.
+  */
+  const triggersRef = useRef(triggers);
+  triggersRef.current = triggers;
+  const openedRef = useRef(opened);
+  openedRef.current = opened;
+  const foundRef = useRef(found);
+  foundRef.current = found;
+  // Ответ на текущий запрос ещё не пришёл: на экране — пункты прошлого запроса.
+  const pendingRef = useRef(false);
+  pendingRef.current = pending;
+  const activeRef = useRef(active);
+  activeRef.current = active;
+  // Номер последнего запроса: ответ с другим номером устарел.
+  const requestRef = useRef(0);
+
+  const fetchItems = (char: string, query: string) => {
+    const trigger = triggersRef.current.find((candidate) => candidate.char === char);
+    if (!trigger) return;
+    const request = ++requestRef.current;
+    const fail = (cause: unknown) =>
+      devError(`RichTextEditor: custom tool "${trigger.tool}": trigger.items failed`, cause);
+    let result: ReturnType<TriggerRecord["items"]> = [];
+    try {
+      result = trigger.items(query);
+    } catch (cause) {
+      fail(cause);
+    }
+    if (typeof (result as { then?: unknown } | null)?.then !== "function") {
+      setFound(Array.isArray(result) ? result : []);
+      setPending(false);
+      return;
+    }
+    setPending(true);
+    // Ref — сразу: Enter, нажатый до следующего рендера, не должен взять пункт прошлого запроса.
+    pendingRef.current = true;
+    Promise.resolve(result).then(
+      (list) => {
+        if (request !== requestRef.current) return;
+        setFound(Array.isArray(list) ? list : []);
+        setPending(false);
+      },
+      (cause) => {
+        if (request !== requestRef.current) return;
+        fail(cause);
+        setFound([]);
+        setPending(false);
+      }
+    );
+  };
+
+  const apply = (item: TriggerItem) => {
+    const editor = editorRef.current;
+    const current = openedRef.current;
+    const trigger = triggersRef.current.find((candidate) => candidate.char === current?.char);
+    if (!editor || editor.isDestroyed || !current || !trigger) return;
+    trigger.onSelect(item, {
+      editor,
+      range: current.session.range,
+      query: current.session.query,
+    });
+    // Обработчик обычно заменил набранное, и сессия кончилась сама; если нет — закрыть.
+    if (!editor.isDestroyed) closeTrigger(editor.view, current.char);
+  };
+
+  const handlers = {
+    open: (char: string, next: SlashSession) => {
+      const previous = openedRef.current;
+      const sameQuery = previous?.char === char && previous.session.query === next.query;
+      const value = { char, session: next };
+      openedRef.current = value;
+      setOpened(value);
+      if (sameQuery) return;
+      // Новый запрос — новый список: курсор встаёт на первую строку.
+      activeRef.current = 0;
+      setActive(0);
+      fetchItems(char, next.query);
+    },
+    close: (char: string) => {
+      if (openedRef.current?.char !== char) return;
+      openedRef.current = null;
+      requestRef.current++;
+      setOpened(null);
+      setFound([]);
+      setPending(false);
+    },
+    keyDown: (char: string, event: KeyboardEvent) => {
+      if (openedRef.current?.char !== char) return false;
+      // Enter, подтверждающий набор IME, принадлежит IME, а не списку.
+      if (event.isComposing) return false;
+      const list = foundRef.current;
+      if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+        if (list.length === 0) return false;
+        const step = event.key === "ArrowDown" ? 1 : -1;
+        // Ref — сразу, не дожидаясь рендера: две стрелки подряд не должны
+        // прочитать одну и ту же строку.
+        const next = (activeRef.current + step + list.length) % list.length;
+        activeRef.current = next;
+        setActive(next);
+        return true;
+      }
+      if (event.key === "Enter") {
+        // Ответ на набранное ещё в пути: в списке пункты прошлого запроса, и Enter
+        // вставил бы то, чего новый запрос, может быть, не находит. Enter съедается —
+        // и не выбирает, и не переводит строку посреди набора.
+        if (pendingRef.current) return true;
+        const item = list[activeRef.current];
+        // Пусто — Enter остаётся переводом строки, и список закрывается сам.
+        if (!item) return false;
+        apply(item);
+        return true;
+      }
+      return false;
+    },
+  };
+  const handlersRef = useRef(handlers);
+  handlersRef.current = handlers;
+
+  /*
+    Мосты — по одному на символ, и живут, пока набор символов тот же: от них
+    зависят расширения движка, и пересоздавать движок ради нового обработчика
+    нельзя. Сами мосты тонкие: всё читают из `handlersRef`.
+  */
+  const chars = triggers.map((trigger) => trigger.char).join("\n");
+  const bindings = useMemo<readonly TriggerBinding[]>(
+    () =>
+      chars === ""
+        ? []
+        : chars.split("\n").map((char) => {
+            const bridge: SlashBridge = {
+              open: (session) => handlersRef.current.open(char, session),
+              close: () => handlersRef.current.close(char),
+              keyDown: (event) => handlersRef.current.keyDown(char, event),
+            };
+            return { char, bridge };
+          }),
+    [chars]
+  );
+
+  const anchorRef = useRef({
+    getBoundingClientRect: () => openedRef.current?.session.rect() ?? emptyRect(),
+    get contextElement() {
+      const editor = editorRef.current;
+      return editor && !editor.isDestroyed ? editor.view.dom : undefined;
+    },
+  });
+
+  const enabled = triggers.length > 0;
+  const open = opened !== null;
+  const current = open ? found[active] : undefined;
+  const listboxLabel = (() => {
+    const trigger = triggers.find((candidate) => candidate.char === opened?.char);
+    const text = trigger?.label ? toolLabel(trigger.label, { locale, messages }).trim() : "";
+    return text !== "" ? text : messages.triggerList;
+  })();
+  const activeId = current ? suggestionOptionId(listboxId, current.id) : undefined;
+  // Объект меняется только вместе со значениями: из него собираются опции
+  // движка, и новый объект на каждом рендере переустанавливал бы их заново.
+  const attributes = useMemo(() => {
+    const result: Record<string, string> = {};
+    if (enabled) result["aria-autocomplete"] = "list";
+    if (open) result["aria-controls"] = listboxId;
+    if (open && activeId) result["aria-activedescendant"] = activeId;
+    return result;
+  }, [enabled, open, listboxId, activeId]);
+
+  const element = enabled && (
+    <SuggestionList
+      open={open}
+      onClose={() => {
+        const editor = editorRef.current;
+        const char = openedRef.current?.char;
+        if (editor && !editor.isDestroyed && char) closeTrigger(editor.view, char);
+      }}
+      anchorRef={anchorRef}
+      editorRef={editorRef}
+      listboxId={listboxId}
+      label={listboxLabel}
+      groups={[
+        {
+          id: "items",
+          rows: found.map((item) => ({ id: item.id, label: item.label, icon: item.icon })),
+        },
+      ]}
+      active={active}
+      onActivate={setActive}
+      onApply={(rowId) => {
+        const item = found.find((candidate) => candidate.id === rowId);
+        if (item) apply(item);
+      }}
+      emptyText={messages.nothingFound}
+      showEmpty={!pending}
+    />
+  );
+
+  return { bindings, attributes, element };
+}

package/src/editor/ui/focusWithin.ts

@@ -0,0 +1,26 @@
+import type { EditorView } from "@tiptap/pm/view";
+
+/**
+ * Фокус в документе Редактора или внутри его плавающей панели — условие показа
+ * `BubbleMenu` (Панель над выделением, панель картинки).
+ *
+ * АКТИВНЫЙ ЭЛЕМЕНТ — ИЗ ДОКУМЕНТА САМОЙ ПАНЕЛИ, а не из глобального `document`.
+ * Редактор в `iframe` или теневом корне живёт в чужом документе: глобальный
+ * `document.activeElement` там — сам `iframe`, и панель пряталась бы от
+ * собственной кнопки в фокусе. И второе: `BubbleMenu` зовёт условие по
+ * таймеру, который может сработать после того, как окно уже снято (размонтаж,
+ * конец теста), — обращение к глобальному `document` тогда падает, а у
+ * `ownerDocument` элемента он есть всегда.
+ */
+export function focusWithin(view: Pick<EditorView, "hasFocus">, element: HTMLElement): boolean {
+  return view.hasFocus() || element.contains(element.ownerDocument.activeElement);
+}
+
+/**
+ * Куда щелчок мимо поповера или меню ставит фокус осознанно: поле, кнопка,
+ * ссылка, документ. Фокус на таком элементе после закрытия не отбирают; на
+ * теле страницы или на контейнере окна (ловушка фокуса `Dialog` ставит его
+ * туда, когда фокусный узел исчез) он оказался сам — его возвращают.
+ */
+export const FOCUS_TARGET =
+  'a[href], button, input, select, textarea, summary, [contenteditable]:not([contenteditable="false"]), [tabindex]:not([tabindex="-1"])';

package/src/editor/ui/lockableMenu.ts

@@ -0,0 +1,37 @@
+"use client";
+
+import { useState } from "react";
+
+/**
+ * Недоступная кнопка меню — `aria-disabled`, а не `disabled`: APG советует
+ * оставлять действия панели фокусируемыми, иначе стрелки перепрыгивают кнопку
+ * молча (как у кнопок Панели, `EditorToolbar`). Тип `MenuButton` атрибута не
+ * знает, а кнопка react-aria передаёт его в DOM.
+ */
+export function unavailableProps(unavailable: boolean | undefined): object {
+  return unavailable ? { "aria-disabled": true } : {};
+}
+
+/**
+ * Меню Панели, которое бывает недоступным (HTML-режим, `aria-disabled`):
+ * управляемый `MenuTrigger`. Недоступная кнопка нажимается — фокус и стрелки у
+ * неё есть, — но меню не открывает, а ставшее недоступным открытое меню
+ * закрывается. Общий каркас «¶», «…», «Выравнивания», «Списков», «+» и
+ * «Таблицы»: `trigger` — пропы `MenuTrigger`, `button` — пропы кнопки меню,
+ * `close` — закрыть меню из кода (выбор не пунктом, а, например, в сетке).
+ *
+ * Отдельным модулем, а не в `FormatMenus.tsx`: каркасом пользуются и меню
+ * фич (таблица), и тянуть ради него форматные меню фича не должна — иначе
+ * общий UI и фича импортируют друг друга (ADR-0060, пункт 14).
+ */
+export function useLockableMenu(unavailable: boolean) {
+  const [open, setOpen] = useState(false);
+  return {
+    trigger: {
+      isOpen: open && !unavailable,
+      onOpenChange: (next: boolean) => setOpen(next && !unavailable),
+    },
+    button: unavailableProps(unavailable),
+    close: () => setOpen(false),
+  };
+}

package/src/editor/ui/rowMarks.ts

@@ -0,0 +1,66 @@
+"use client";
+
+import type { Editor } from "@tiptap/react";
+import type { ComponentType } from "react";
+import type { UiMessages } from "../../i18n/messages.js";
+import { BoldIcon, ItalicIcon, UnderlineIcon, type IconProps } from "../../icons.js";
+import type { Tool } from "../core/tools.js";
+
+/** Метка-переключатель ряда: кнопка с `aria-pressed` на Панели и в плашке. */
+export interface RowMark {
+  tool: Tool;
+  /** Id строки общей таблицы сочетаний (`shortcuts.ts`) — оттуда подсказка. */
+  id: string;
+  label: (messages: UiMessages["editor"]) => string;
+  icon: ComponentType<IconProps>;
+  run: (editor: Editor) => void;
+  can: (editor: Editor) => boolean;
+  isActive: (editor: Editor) => boolean;
+}
+
+/**
+ * Частые Метки в ряду (решения владельца): у Панели — жирный и
+ * курсив (`TOOLBAR_ROW_MARKS`), у плашки меню выделения — ещё и подчёркнутый
+ * (`BUBBLE_ROW_MARKS`). Остальные Метки — в меню «…» (`FormatMenus.tsx`), и
+ * то, что стоит в ряду, в «…» того же хозяина не повторяется.
+ *
+ * Маркер стоял здесь же — один щелчок жёлтым. Теперь это кнопка с
+ * поповером (`ColorMenus.tsx`): щелчок открывает ряд маркеров.
+ */
+const ROW_MARKS: readonly RowMark[] = [
+  {
+    tool: "bold",
+    id: "bold",
+    label: (m) => m.bold,
+    icon: BoldIcon,
+    run: (editor) => editor.chain().focus().toggleBold().run(),
+    can: (editor) => editor.can().toggleBold(),
+    isActive: (editor) => editor.isActive("bold"),
+  },
+  {
+    tool: "italic",
+    id: "italic",
+    label: (m) => m.italic,
+    icon: ItalicIcon,
+    run: (editor) => editor.chain().focus().toggleItalic().run(),
+    can: (editor) => editor.can().toggleItalic(),
+    isActive: (editor) => editor.isActive("italic"),
+  },
+  {
+    tool: "underline",
+    id: "underline",
+    label: (m) => m.underline,
+    icon: UnderlineIcon,
+    run: (editor) => editor.chain().focus().toggleUnderline().run(),
+    can: (editor) => editor.can().toggleUnderline(),
+    isActive: (editor) => editor.isActive("underline"),
+  },
+];
+
+const pick = (ids: readonly string[]) => ids.map((id) => ROW_MARKS.find((mark) => mark.id === id)!);
+
+/** Ряд Метак Панели: B · I. */
+export const TOOLBAR_ROW_MARKS: readonly RowMark[] = pick(["bold", "italic"]);
+
+/** Ряд Метак плашки меню выделения: B · I · U. */
+export const BUBBLE_ROW_MARKS: readonly RowMark[] = pick(["bold", "italic", "underline"]);

package/src/editor/ui/selectionMenu.ts

@@ -0,0 +1,97 @@
+"use client";
+
+import { NodeSelection, TextSelection } from "@tiptap/pm/state";
+import type { BubbleMenuProps } from "@tiptap/react/menus";
+import { useEffect, useMemo, type RefObject } from "react";
+import { focusWithin } from "./focusWithin.js";
+import { isImageSelection } from "../features/image/image.js";
+
+/**
+ * Общее у всего, что всплывает над выделением на `BubbleMenu` Tiptap: у
+ * плавающей Панели (`toolbar="floating"`) и у меню выделения
+ * (`toolbar="bubble"`). Условие показа и позиция у них одни: две
+ * копии разъехались бы молча, и плашка показывалась бы там, где Панель — нет.
+ */
+
+/**
+ * Условие показа — умолчание `BubbleMenu` плюс два исключения: над
+ * выделенной картинкой стоит её собственная панель (`ImageToolbar`), и меню
+ * форматирования спорило бы с ней за одно место; над выделенным своим Блоком
+ * с Признаком «атом без меню форматирования» (`plainAtom` в spec узла) Меток
+ * не ставят.
+ *
+ * Пустое выделение, пустой текст под выделением, нередактируемое поле и фокус
+ * вне документа и вне самого меню — не показывать.
+ *
+ * ОТКРЫТОЕ ИЗ МЕНЮ — ТОЖЕ «ФОКУС ВНУТРИ». Списки «¶», «…», цвета и сетка эмодзи
+ * живут в портале, вне узла меню, и фокус в них для `focusWithin` — снаружи.
+ * А условие пересчитывается таймером после каждой правки: жирный за миг до
+ * открытия «¶» прятал плашку вместе с кнопкой меню, и Escape возвращал фокус в
+ * никуда. Пока у кнопки внутри меню `aria-expanded="true"` (его ставят и
+ * react-aria, и Radix), человек работает с меню — прятать его нельзя.
+ */
+export const showOverSelection: NonNullable<BubbleMenuProps["shouldShow"]> = ({
+  editor,
+  view,
+  state,
+  from,
+  to,
+  element,
+}) => {
+  const { selection } = state;
+  if (selection.empty || !editor.isEditable || isImageSelection(selection)) return false;
+  // Признак «атом без меню форматирования» своего Блока (ADR-0058, п. 1.4).
+  if (selection instanceof NodeSelection && selection.node.type.spec.plainAtom === true) {
+    return false;
+  }
+  const emptyText = !state.doc.textBetween(from, to).length && selection instanceof TextSelection;
+  if (emptyText) return false;
+  return focusWithin(view, element) || element.querySelector('[aria-expanded="true"]') !== null;
+};
+
+/**
+ * Позиция — над выделением, с переворотом под него у верхнего края окна и
+ * сдвигом от боковых краёв.
+ *
+ * `strategy: "absolute"` (умолчание), а не `fixed`: меню лежит в DOM Редактора
+ * и едет вместе с текстом в любом контейнере прокрутки — в окне, в ящике, в
+ * карточке. `fixed` пересчитывался бы только на прокрутке окна. Цена — предок
+ * с `overflow: hidden` срежет меню у края; на странице компонента это сказано.
+ */
+export const SELECTION_MENU_OPTIONS = {
+  placement: "top",
+  offset: 8,
+  flip: true,
+  shift: { padding: 8 },
+} as const satisfies BubbleMenuProps["options"];
+
+/**
+ * Опции плашки с прокруткой области Документа (ADR-0059). Плагин `BubbleMenu`
+ * пересчитывает позицию на прокрутке окна; когда Документ прокручивается
+ * внутри рамки (`maxHeight`, `resizable`), слушать надо его область, иначе
+ * плашка висит на месте, а текст под ней уезжает. Без области — окно.
+ */
+export function useSelectionMenuOptions(
+  scrollTarget: HTMLElement | undefined,
+  options: NonNullable<BubbleMenuProps["options"]> = SELECTION_MENU_OPTIONS
+): NonNullable<BubbleMenuProps["options"]> {
+  return useMemo(
+    () => (scrollTarget ? { ...options, scrollTarget } : options),
+    [scrollTarget, options]
+  );
+}
+
+/**
+ * Убрать узел `BubbleMenu` из обхода Tab.
+ *
+ * Плагин ставит своему узлу `tabindex="0"` — ради щелчков по пустому месту
+ * меню, которые иначе сняли бы фокус с документа. Но это лишняя остановка
+ * Tab перед `role="toolbar"`, у которого остановка уже есть. `-1` оставляет
+ * узел фокусируемым щелчком и убирает его из обхода. Эффект родителя идёт
+ * после эффекта `BubbleMenu`, создающего плагин, — значение доживает.
+ */
+export function useOutOfTabOrder(ref: RefObject<HTMLElement | null>, dependency: unknown): void {
+  useEffect(() => {
+    ref.current?.setAttribute("tabindex", "-1");
+  }, [ref, dependency]);
+}

package/src/hooks/useFieldDescription.ts

@@ -0,0 +1,126 @@
+"use client";
+
+import { createContext, useContext } from "react";
+
+/**
+ * Идентификатор сообщения под полем — подсказки или ошибки, — чтобы поле могло
+ * сослаться на него в `aria-describedby`.
+ *
+ * ЗАЧЕМ КОНТЕКСТ, А НЕ ПРОП. Сообщение рисует `FormField`, а поле лежит у него
+ * в `children`: поставить атрибут на чужой узел снаружи нечем. `cloneElement`
+ * ломается на любой обёртке — а поле обёрнуто почти всегда, хотя бы
+ * `MaskedInput` в `TextControl`. Поэтому `id` придумывает тот, кто рисует
+ * сообщение, а забирают его поля — тем же приёмом, что ось раскладки
+ * (`FieldLayoutContext`) и режим навигации (`NavCollapsedContext`).
+ *
+ * ОТДЕЛЬНЫЙ МОДУЛЬ, А НЕ СТРОКА В `FormField.tsx`, по той же причине, по
+ * которой отделён контекст `UiProvider`: иначе `TextControl` импортировал бы
+ * `FormField`, то есть каждое голое поле тащило бы в бандл раскладку формы,
+ * которая ему не нужна.
+ *
+ * Без `FormField` значение `undefined` — это законное состояние, а не ошибка:
+ * поле бывает и вне формы, и описывать там нечего.
+ */
+const FieldDescriptionContext = createContext<string | undefined>(undefined);
+
+/** @internal Ставит `FormField`, когда под полем есть подсказка или ошибка. */
+export const FieldDescriptionProvider = FieldDescriptionContext.Provider;
+
+/**
+ * `id` сообщения под полем — для `aria-describedby`.
+ *
+ * @internal Читают поля кита. Потребителю не нужен: он передаёт полю свой
+ * `aria-describedby` пропом, и поле сливает его с этим значением, а не
+ * заменяет.
+ */
+export function useFieldDescribedBy(): string | undefined {
+  return useContext(FieldDescriptionContext);
+}
+
+/**
+ * Признак невалидности поля, объявленный `FormField`.
+ *
+ * Отдельный контекст рядом с описанием и по той же причине: ошибку рисует
+ * `FormField`, а поле лежит у него в `children` — поставить `aria-invalid` на
+ * чужой узел снаружи нечем.
+ *
+ * ЗАЧЕМ ЭТО ВООБЩЕ НУЖНО. `FIELD_SHELL_CLASS` красит рамку по
+ * `has-[input[aria-invalid=true]]`, то есть дотягивается до атрибута НА САМОМ
+ * ПОЛЕ. В контекст же уходило только описание, и поле атрибут не ставило:
+ * `<FormField error="…"><TextControl/></FormField>` рисовал красный текст под
+ * полем и обычную рамку у поля. Чтобы она покраснела, потребитель обязан был
+ * передать `aria-invalid` сам — а строки `aria-invalid` нет ни в одном файле
+ * `docs/`, то есть узнать об этой обязанности было неоткуда.
+ */
+const FieldInvalidContext = createContext(false);
+
+/** @internal Ставит `FormField`, когда под полем есть ошибка. */
+export const FieldInvalidProvider = FieldInvalidContext.Provider;
+
+/**
+ * Объявлено ли поле невалидным раскладкой формы.
+ *
+ * @internal Читают поля кита и сливают со своим пропом: явный `aria-invalid` от
+ * потребителя сильнее — он знает про своё поле больше, чем форма.
+ */
+export function useFieldInvalid(): boolean {
+  return useContext(FieldInvalidContext);
+}
+
+/**
+ * Описание поля: СЛИЯНИЕ своего и того, что объявила форма.
+ *
+ * Вытеснение здесь ошибается в обе стороны, и обе встречались в ките:
+ *
+ * - спред `{...rest}` ПОСЛЕ условного — пользовательский `aria-describedby`
+ *   затирал контекстный, и ошибка формы не объявлялась вовсе;
+ * - спред ПЕРЕД условным — контекстный затирал пользовательский, и терялась
+ *   подсказка потребителя.
+ *
+ * Склейка снимает вопрос порядка целиком: оба идентификатора попадают в
+ * атрибут, скринридер читает оба. Приём был расписан в `TextControl` и
+ * `TagInput`, но не вынесен — и пять компонентов, подключённых к контексту
+ * позже, повторили его каждый по-своему.
+ */
+export function useDescribedBy(own?: string): string | undefined {
+  const fromField = useContext(FieldDescriptionContext);
+  /*
+    Идентификаторы ещё и РАЗДВАИВАТЬСЯ не должны.
+
+    Тот же `id` приходит дважды, когда библиотека спускает описание группы на
+    свой внутренний узел, а мы добавляем его же (так делает `Slider`
+    react-aria с бегунком). Скринридер прочитал бы подсказку два раза подряд.
+  */
+  const ids = `${own ?? ""} ${fromField ?? ""}`.trim().split(/\s+/).filter(Boolean);
+  return ids.length > 0 ? [...new Set(ids)].join(" ") : undefined;
+}
+
+/**
+ * `id` подписи `FormField` — для полей, которые нельзя назвать через
+ * `<label for>`.
+ *
+ * Браузер связывает `for` только с «labelable»-элементами (`input`, `textarea`,
+ * `select`…); `contenteditable` к ним не относится, и безымянным он остаётся,
+ * сколько ни проставляй `htmlFor`. Такое поле ссылается на подпись через
+ * `aria-labelledby`, а `id` подписи придумывает тот, кто её рисует, — тем же
+ * приёмом, что описание выше. Раньше поле искало подпись в DOM по `for` и
+ * дописывало ей `id` само, то есть правило жило на чужом узле и ломалось от
+ * любой обёртки между ними.
+ *
+ * Без `FormField` — `undefined`: подписи нет, поле называется своим
+ * `aria-label`.
+ */
+const FieldLabelContext = createContext<string | undefined>(undefined);
+
+/** @internal Ставит `FormField` всегда: подпись у него обязательна. */
+export const FieldLabelProvider = FieldLabelContext.Provider;
+
+/**
+ * `id` подписи объемлющего `FormField`.
+ *
+ * @internal Читают поля, которые не называются через `<label for>`
+ * (сейчас — `RichTextEditor`). Остальным хватает `htmlFor`.
+ */
+export function useFieldLabelId(): string | undefined {
+  return useContext(FieldLabelContext);
+}

package/src/hooks/useMediaQuery.ts

@@ -0,0 +1,46 @@
+"use client";
+
+import { useCallback, useSyncExternalStore } from "react";
+
+/**
+ * Совпадает ли медиазапрос с окном прямо сейчас — и следит за изменением.
+ *
+ * ЭТО НЕ СПОСОБ РАСКЛАДЫВАТЬ СТРАНИЦУ. Показать или спрятать блок по ширине
+ * надо классом (`hidden lg:block`): класс работает с первого кадра и на
+ * сервере, а раскладка, зависящая от JS, до гидратации показывает неверную
+ * (ADR-0018). Хук нужен там, где от ширины зависит не вид, а СОСТАВ или ПОВЕДЕНИЕ
+ * — что смонтировать, сколько месяцев рисовать, закрывать ли ящик по Escape, —
+ * и класс этого не выразит.
+ *
+ * ДО ГИДРАТАЦИИ ХУК ВОЗВРАЩАЕТ `serverValue`, ПО УМОЛЧАНИЮ `false`. Сервер
+ * ширины не знает, и угадывать её значило бы получить расхождение разметки.
+ * `false` — потому что отсчёт mobile-first, как у самого Tailwind: запрос
+ * `min-width` на сервере «ещё не выполнен», и первый кадр всегда узкий. React
+ * при гидратации сам берёт серверное значение, а настоящее подставляет сразу
+ * после — без ошибки расхождения, но с одной перерисовкой. На широком экране
+ * это видимый переход, поэтому всё, что можно выразить классом, выражайте им.
+ *
+ * Нет `matchMedia` вовсе (jsdom, сервер) — тоже `serverValue`: хук не бросает.
+ *
+ * Запрос — строка как есть: `(min-width: 1024px)`. Брейкпойнты кита — штатные
+ * Tailwind 4: `sm` 640, `md` 768, `lg` 1024, `xl` 1280.
+ */
+export function useMediaQuery(query: string, serverValue = false): boolean {
+  const subscribe = useCallback(
+    (notify: () => void) => {
+      if (typeof window.matchMedia !== "function") return () => {};
+      const list = window.matchMedia(query);
+      list.addEventListener("change", notify);
+      return () => list.removeEventListener("change", notify);
+    },
+    [query]
+  );
+
+  const getSnapshot = useCallback(
+    () =>
+      typeof window.matchMedia === "function" ? window.matchMedia(query).matches : serverValue,
+    [query, serverValue]
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot, () => serverValue);
+}