@olddevs/ui 0.0.0-stage → 4.0.0

package/src/editor/ui/TextCard.tsx

@@ -0,0 +1,312 @@
+"use client";
+
+import { posToDOMRect, type Editor } from "@tiptap/react";
+import { useEffect, useMemo, useRef, useState, type MutableRefObject, type RefObject } from "react";
+import { Popover, PopoverAnchor, PopoverContent } from "../../components/overlays/Popover.js";
+import { useMessages, useUiLocale } from "../../i18n/useMessages.js";
+import { cn } from "../../lib/cn.js";
+import { devError } from "../../lib/dev-warn.js";
+import { FOCUS_TARGET } from "./focusWithin.js";
+import { GLASS_PANEL_CLASS } from "../styles/glass.js";
+import { ariaShortcut, isApple } from "../core/shortcuts.js";
+import type { TextCardRecord as TextCardEntry } from "../core/toolDescriptor.js";
+
+/*
+  Карточка у текста (ADR-0058, п. 7.6–7.11): четвёртый вид UI-записи
+  своего Инструмента, например карточка комментария под Меткой. Описание —
+  диапазон `rangeAt` и тело `render`; всё остальное держит кит.
+
+  ЧТО ОТКРЫТО, РЕШАЕТ ОДНА ФУНКЦИЯ `evaluate`, и зовётся она на каждой
+  транзакции, фокусе, потере фокуса и щелчке по Документу — не на наведении.
+  Каретка — свёрнутое выделение; развёрнутое выделение закрывает Карточку (там
+  работает Меню выделения). Открыта не больше одной: самый узкий диапазон под
+  кареткой, при равной ширине — запись раньше в списке, то есть Инструмент
+  раньше в `tools`.
+
+  ВЫШЕ ДОКУМЕНТА, НО НЕ МОДАЛЬНО. Рамка — `Popover` кита: слой, стек Escape
+  (ADR-0041), переворот у края. Фокус при открытии остаётся в Документе —
+  печать не прерывается; `Alt+F10` переводит его в Карточку, Escape возвращает
+  каретку и прячет Карточку. «Спрятана» — состояние `dismissed`: оно снимается,
+  когда каретка покинет диапазон этой записи, или щелчком по диапазону.
+
+  READONLY. Каретки у такого поля нет (Документ не принимает фокус в текст),
+  поэтому открывает щелчок: место щелчка запоминается и едет за правкой.
+  Фокус не требуется; закрывает щелчок мимо поля, Escape или выделение мышью.
+*/
+
+/** Открытая Карточка: номер записи и её диапазон на текущем состоянии. */
+interface Shown {
+  index: number;
+  from: number;
+  to: number;
+}
+
+/** Что `RichTextEditor` просит у Карточки извне: `Alt+F10` ведёт в неё. */
+export interface TextCardControl {
+  /** Перевести фокус в открытую Карточку; `false` — Карточки нет или она спрятана. */
+  focus: () => boolean;
+}
+
+/**
+ * Записи, у которых есть диапазон под `pos`. Ответ, которому нельзя верить
+ * (вне Документа, `from > to`, не числа), отбрасывается; исключение в `rangeAt`
+ * — тоже: чужая функция не роняет поле.
+ */
+function rangesAt(editor: Editor, entries: readonly TextCardEntry[], pos: number): Shown[] {
+  const { state } = editor;
+  const size = state.doc.content.size;
+  const found: Shown[] = [];
+  entries.forEach((entry, index) => {
+    try {
+      const range = entry.rangeAt(state, pos);
+      if (
+        range &&
+        Number.isInteger(range.from) &&
+        Number.isInteger(range.to) &&
+        range.from >= 0 &&
+        range.from <= range.to &&
+        range.to <= size
+      ) {
+        found.push({ index, from: range.from, to: range.to });
+      }
+    } catch (error) {
+      devError(`RichTextEditor: text card "${entry.id}" threw in rangeAt`, error);
+    }
+  });
+  return found;
+}
+
+/** Самый узкий диапазон; при равной ширине — запись раньше (`found` идёт по порядку). */
+const narrowest = (found: readonly Shown[]): Shown | null =>
+  found.reduce<Shown | null>(
+    (best, item) => (best && best.to - best.from <= item.to - item.from ? best : item),
+    null
+  );
+
+export interface TextCardProps {
+  editor: Editor;
+  entries: readonly TextCardEntry[];
+  /** Выключено поле или HTML-режим: Карточек нет. */
+  enabled: boolean;
+  readOnly: boolean;
+  /** Корень поля: щелчок внутри него Карточку не закрывает сам по себе. */
+  rootRef: RefObject<HTMLElement | null>;
+  controlRef: MutableRefObject<TextCardControl | null>;
+}
+
+export function TextCard({
+  editor,
+  entries,
+  enabled,
+  readOnly,
+  rootRef,
+  controlRef,
+}: TextCardProps) {
+  const messages = useMessages().editor;
+  const locale = useUiLocale();
+  const [shown, setShown] = useState<Shown | null>(null);
+  const shownRef = useRef<Shown | null>(null);
+  const cardRef = useRef<HTMLDivElement>(null);
+  /** Запись, чью Карточку спрятали; нет — не прятали. */
+  const dismissed = useRef<number | null>(null);
+  /** `readOnly`: место последнего щелчка, едет за правкой. */
+  const pinned = useRef<number | null>(null);
+  const latest = useRef({ entries, enabled, readOnly });
+  latest.current = { entries, enabled, readOnly };
+
+  const evaluateRef = useRef<(settled?: boolean) => void>(() => {});
+  /** Пересчёт на такт позже: к тому времени фокус уже встал на новое место. */
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const later = () => {
+    clearTimeout(timer.current);
+    timer.current = setTimeout(() => evaluateRef.current(true), 0);
+  };
+  evaluateRef.current = (settled = false) => {
+    const { entries: list, enabled: on, readOnly: reading } = latest.current;
+    let next: Shown | null = null;
+    if (on && !editor.isDestroyed) {
+      const { selection } = editor.state;
+      const pos = reading ? pinned.current : selection.empty ? selection.head : null;
+      const card = cardRef.current;
+      // Каретка живёт там, где фокус: в Документе или в самой Карточке.
+      const focused =
+        reading ||
+        editor.view.hasFocus() ||
+        (card != null && card.contains(card.ownerDocument.activeElement));
+      // Фокус «ушёл» посреди перехода — в самом `blur` активного элемента ещё
+      // нет: решает пересчёт на такт позже, а пока Карточка стоит как стояла.
+      if (!focused && !settled && shownRef.current !== null) return later();
+      if (pos !== null && focused) {
+        let found = rangesAt(editor, list, pos);
+        if (dismissed.current !== null) {
+          // Спрятана, пока каретка в диапазоне этой записи: ни она, ни соседи не всплывают.
+          if (found.some((item) => item.index === dismissed.current)) found = [];
+          else dismissed.current = null;
+        }
+        next = narrowest(found);
+      }
+    }
+    const previous = shownRef.current;
+    if (
+      previous?.index === next?.index &&
+      previous?.from === next?.from &&
+      previous?.to === next?.to
+    ) {
+      return;
+    }
+    shownRef.current = next;
+    setShown(next);
+  };
+
+  /** Спрятать до выхода каретки; фокус из Карточки — в Документ, каретка на месте. */
+  const dismiss = () => {
+    const card = cardRef.current;
+    if (card?.contains(card.ownerDocument.activeElement)) editor.view.focus();
+    dismissed.current = shownRef.current?.index ?? null;
+    shownRef.current = null;
+    setShown(null);
+  };
+
+  useEffect(() => {
+    const evaluate = () => evaluateRef.current();
+    const onTransaction = ({
+      transaction,
+    }: {
+      transaction: { docChanged: boolean; mapping: { map: (pos: number) => number } };
+    }) => {
+      if (pinned.current !== null && transaction.docChanged) {
+        pinned.current = transaction.mapping.map(pinned.current);
+      }
+      evaluate();
+    };
+    const onClick = (event: MouseEvent) => {
+      const { enabled: on, readOnly: reading, entries: list } = latest.current;
+      if (!on || editor.isDestroyed) return;
+      const { view } = editor;
+      // Место щелчка: по координатам; без раскладки (jsdom) — начало узла под ним.
+      let pos: number | undefined;
+      try {
+        pos = view.posAtCoords({ left: event.clientX, top: event.clientY })?.pos;
+      } catch {
+        // Координатам нечем мерить — запасной путь ниже.
+      }
+      try {
+        if (pos === undefined && event.target instanceof Node) pos = view.posAtDOM(event.target, 0);
+      } catch {
+        // Узел вне Документа: щелчок места не назвал.
+      }
+      if (pos === undefined) return;
+      if (reading) {
+        // Выделение мышью (двойной щелчок по слову) — не открытие.
+        const selection = view.dom.ownerDocument.getSelection();
+        if (selection && !selection.isCollapsed) {
+          pinned.current = null;
+          return evaluate();
+        }
+        pinned.current = pos;
+      }
+      // Щелчок по диапазону спрятанной Карточки открывает её снова.
+      if (dismissed.current !== null) {
+        const entry = list[dismissed.current];
+        if (entry && rangesAt(editor, [entry], pos).length > 0) dismissed.current = null;
+      }
+      evaluate();
+    };
+    editor.on("transaction", onTransaction);
+    editor.on("focus", evaluate);
+    editor.on("blur", later);
+    editor.view.dom.addEventListener("click", onClick);
+    // Другая запись, режим или поле — свой пересчёт.
+    evaluate();
+    return () => {
+      clearTimeout(timer.current);
+      editor.off("transaction", onTransaction);
+      editor.off("focus", evaluate);
+      editor.off("blur", later);
+      editor.view.dom.removeEventListener("click", onClick);
+    };
+  }, [editor]);
+
+  useEffect(() => {
+    if (!enabled) pinned.current = null;
+    evaluateRef.current();
+  }, [entries, enabled, readOnly]);
+
+  useEffect(() => {
+    controlRef.current = {
+      focus: () => {
+        const card = cardRef.current;
+        if (!card || shownRef.current === null) return false;
+        (card.querySelector<HTMLElement>(FOCUS_TARGET) ?? card).focus();
+        return true;
+      },
+    };
+    return () => {
+      controlRef.current = null;
+    };
+  }, [controlRef]);
+
+  const entry = shown ? entries[shown.index] : undefined;
+  const label = entry?.label(messages, locale) ?? "";
+  // Якорь меряется при каждом пересчёте позиции: Карточка едет за диапазоном.
+  const anchor = useMemo(
+    () => ({
+      current: {
+        getBoundingClientRect: () => {
+          try {
+            return posToDOMRect(editor.view, shown?.from ?? 0, shown?.to ?? 0);
+          } catch {
+            return editor.view.dom.getBoundingClientRect();
+          }
+        },
+        contextElement: editor.view.dom,
+      },
+    }),
+    [editor, shown?.from, shown?.to]
+  );
+
+  return (
+    <>
+      {/* Живой регион смонтирован всегда: скринридер объявляет изменение, а не появление. */}
+      <div role="status" className="sr-only">
+        {entry
+          ? messages.textCardShown({ label, shortcut: ariaShortcut(["alt", "F10"], isApple()) })
+          : ""}
+      </div>
+      {shown && entry && (
+        <Popover key={shown.index} open onOpenChange={(open) => !open && dismiss()}>
+          <PopoverAnchor virtualRef={anchor} />
+          <PopoverContent
+            ref={cardRef}
+            aria-label={label}
+            side="bottom"
+            align="start"
+            collisionPadding={8}
+            // Стекло поповеров Редактора: Карточка лежит над Документом.
+            className={cn(
+              GLASS_PANEL_CLASS,
+              "max-h-[var(--radix-popover-content-available-height)] w-auto max-w-[min(24rem,calc(100vw-1rem))] overflow-y-auto p-2"
+            )}
+            // Фокус остаётся в Документе: Карточка немодальна, печать продолжается.
+            onOpenAutoFocus={(event) => event.preventDefault()}
+            onCloseAutoFocus={(event) => event.preventDefault()}
+            // Закрывает не Radix, а правила выше: Escape, `close`, выход каретки,
+            // щелчок мимо поля. Щелчок и фокус в самом поле — дело пересчёта.
+            onFocusOutside={(event) => event.preventDefault()}
+            onPointerDownOutside={(event) => {
+              event.preventDefault();
+              const target = event.target;
+              if (target instanceof Node && rootRef.current?.contains(target)) return;
+              pinned.current = null;
+              shownRef.current = null;
+              setShown(null);
+            }}
+            onBlur={later}
+          >
+            {entry.render({ editor, range: shown, close: dismiss })}
+          </PopoverContent>
+        </Popover>
+      )}
+    </>
+  );
+}

package/src/editor/ui/ToolButtonView.tsx

@@ -0,0 +1,242 @@
+"use client";
+
+import { posToDOMRect, type Editor, type EditorEvents } from "@tiptap/react";
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import { Kbd } from "../../components/content/Kbd.js";
+import {
+  Popover,
+  PopoverAnchor,
+  PopoverContent,
+  PopoverTrigger,
+} from "../../components/overlays/Popover.js";
+import { Tooltip } from "../../components/overlays/Tooltip.js";
+import { useMessages, useUiLocale } from "../../i18n/useMessages.js";
+import { buttonClasses } from "../../lib/button.js";
+import { cn } from "../../lib/cn.js";
+import { GLASS_PANEL_CLASS } from "../styles/glass.js";
+import { ariaShortcut, isApple, shortcutLabel } from "../core/shortcuts.js";
+import type { ToolPopoverRequest } from "../core/toolButtons.js";
+import { toolLabel, type KitToolButton, type ToolLabel } from "../core/toolDescriptor.js";
+
+/**
+ * Кнопка из описания Инструмента (`toolDescriptor.ts`) на Панели, плавающей
+ * Панели и в Меню выделения, и рамка её поповера.
+ *
+ * КИТ РИСУЕТ, ОПИСАНИЕ ОПИСЫВАЕТ (ADR-0058, п. 5). Хозяин места — Панель или
+ * Меню выделения — считает состояние кнопки (`pressed`, `unavailable`) вместе
+ * со своими и держит roving-фокус; здесь — то, что у всех кнопок описаний
+ * одно: подсказка с `Kbd`, `aria-pressed` только при `isActive`,
+ * `aria-keyshortcuts`, `aria-disabled` и поповер.
+ */
+
+/**
+ * Подпись записи в локали `UiProvider`: смена локали перерисовывает запись
+ * (ADR-0058, п. 6.1). Встроенным в контекст кладутся строки Редактора кита.
+ */
+export function useToolLabel(): (label: ToolLabel) => string {
+  const messages = useMessages().editor;
+  const locale = useUiLocale();
+  return (label) => toolLabel(label, { locale, messages });
+}
+
+/**
+ * Рамка поповера по умолчанию: по содержимому, с небольшим отступом. Подложка
+ * — стекло поповеров Редактора у любой рамки, и у своего
+ * Инструмента: его поповер всплывает над Документом так же, как встроенные.
+ */
+const POPOVER_FRAME_CLASS = "w-auto p-2";
+
+const OPEN_CLASS = buttonClasses({ variant: "ghost", size: "sm", iconOnly: true, selected: true });
+
+/**
+ * Рамка поповера записи — общая для якоря у кнопки, у выделения и у Блока.
+ *
+ * `Popover` КИТА. Radix ведёт стек слоёв, и `Dialog` кита — тоже Radix: Escape
+ * в поповере внутри окна закрывает поповер, а не окно (ADR-0041). Выбор мышью
+ * в `Dialog` и `Drawer` работает по той же причине: слой поповера выше слоя
+ * окна и сам включает `pointer-events`.
+ *
+ * ФОКУС. Закрытие с клавиатуры или выбором возвращает фокус в Документ, на
+ * прежнее выделение, а не на кнопку: человек пришёл править текст и
+ * продолжает с того места. Щелчок мимо фокус не трогает — человек сам
+ * выбрал, куда его поставить. Фокус внутрь берёт сам Radix — на первый
+ * фокусируемый элемент; своей рукой его ставить нельзя: внутри `Dialog`
+ * ловушка фокуса окна ещё не приостановлена и вернула бы его кнопке.
+ */
+function ToolPopoverFrame({
+  editor,
+  label,
+  className,
+  children,
+}: {
+  editor: Editor;
+  label: string;
+  className?: string;
+  children: ReactNode;
+}) {
+  const interactedOutside = useRef(false);
+  return (
+    <PopoverContent
+      aria-label={label}
+      className={cn(GLASS_PANEL_CLASS, className ?? POPOVER_FRAME_CLASS)}
+      onOpenAutoFocus={() => {
+        interactedOutside.current = false;
+      }}
+      onInteractOutside={() => {
+        interactedOutside.current = true;
+      }}
+      onCloseAutoFocus={(event) => {
+        // Radix вернул бы фокус кнопке-триггеру, а у поповера у выделения её
+        // нет вовсе. Таймер Radix мог сработать уже после размонтажа движка.
+        // Фокус — сразу, а не кадром позже, как `commands.focus()`: запоздалый
+        // фокус в Документ закрыл бы поповер, открытый повторным щелчком.
+        event.preventDefault();
+        if (!interactedOutside.current && !editor.isDestroyed) editor.view.focus();
+      }}
+    >
+      {/* Содержимое монтируется заново на каждое открытие: оно берёт
+          состояние Документа в момент открытия, а не прошлый черновик. */}
+      {children}
+    </PopoverContent>
+  );
+}
+
+export interface ToolButtonViewProps {
+  editor: Editor;
+  button: KitToolButton;
+  /** Подпись в текущей локали (`toolLabel`). */
+  label: string;
+  /** Состояние `isActive`; у кнопки без него не читается. */
+  pressed: boolean;
+  /** `aria-disabled`: `can` не выполнен или HTML-режим. */
+  unavailable: boolean;
+  /** Поле выключено: кнопка видна, но не нажимается и не берёт фокус. */
+  disabled: boolean;
+  /** Классы хозяина места: обычная и нажатая кнопка (у Меню выделения — свои). */
+  classes: { idle: string; pressed: string };
+}
+
+export function ToolButtonView({
+  editor,
+  button,
+  label,
+  pressed,
+  unavailable,
+  disabled,
+  classes,
+}: ToolButtonViewProps) {
+  const apple = isApple();
+  const [open, setOpen] = useState(false);
+  const keys = button.shortcut;
+  const tooltip = keys ? (
+    <span className="flex items-center gap-2">
+      {label}
+      <Kbd aria-hidden="true">{shortcutLabel(keys, apple)}</Kbd>
+    </span>
+  ) : (
+    label
+  );
+  const Icon = button.icon;
+  // Поповер у кнопки держит сама кнопка; у выделения — Редактор (`SelectionPopover`).
+  const atButton = button.popover != null && button.popoverFrame?.anchor !== "selection";
+  /*
+    Недоступное действие — `aria-disabled`, а не `disabled`: APG советует
+    оставлять действия панели фокусируемыми, иначе стрелки перепрыгивают
+    кнопку молча. Выключенное ПОЛЕ — другое дело: в нём фокусу делать нечего.
+  */
+  const trigger = (
+    <button
+      type="button"
+      aria-label={label}
+      aria-pressed={button.isActive ? pressed : undefined}
+      aria-haspopup={atButton ? "dialog" : undefined}
+      aria-disabled={unavailable || undefined}
+      aria-keyshortcuts={keys ? ariaShortcut(keys, apple) : undefined}
+      disabled={disabled}
+      onClick={(event) => {
+        // Radix не откроет поповер, если обработчик отменил событие.
+        if (unavailable) event.preventDefault();
+        else if (atButton) return;
+        // Поповер у выделения открывает команда движка — та же, что у
+        // сочетания (`toolButtons.ts`).
+        else if (button.popover) editor.commands.openToolPopover(button.id);
+        else button.run(editor);
+      }}
+      className={open ? OPEN_CLASS : pressed ? classes.pressed : classes.idle}
+    >
+      <Icon size={16} aria-hidden />
+    </button>
+  );
+
+  if (!atButton) return <Tooltip content={tooltip}>{trigger}</Tooltip>;
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <Tooltip content={tooltip}>
+        <PopoverTrigger asChild>{trigger}</PopoverTrigger>
+      </Tooltip>
+      <ToolPopoverFrame editor={editor} label={label} className={button.popoverFrame?.className}>
+        {button.popover?.({ editor, close: () => setOpen(false) })}
+      </ToolPopoverFrame>
+    </Popover>
+  );
+}
+
+export interface SelectionPopoverProps {
+  editor: Editor;
+  /** Запись, чей поповер открыт или был открыт последним. */
+  request: ToolPopoverRequest;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+/**
+ * Поповер записи у выделения или у Блока (ADR-0058, п. 5.6): так он встаёт,
+ * когда его открыло сочетание или меню (пункт вставки — у каретки, Действие
+ * над Блоком — у Блока), и всегда — у кнопки с рамкой `anchor: "selection"`
+ * (ссылка). Держит его `RichTextEditor`, а не кнопка или меню: сочетание
+ * работает и без Панели (`toolbar="none"`), и при спрятанной плавающей, а меню
+ * к открытию поповера уже снято.
+ *
+ * Якорь меряется при каждом пересчёте позиции, а не раз при открытии: Radix
+ * зовёт его на прокрутке и ресайзе, и поповер едет вместе с текстом. Выделение
+ * движка при этом не меняется — фокус в поповере его не сбрасывает. Позиция
+ * Блока едет за правками Документа, пока поповер открыт.
+ */
+export function SelectionPopover({ editor, request, open, onOpenChange }: SelectionPopoverProps) {
+  const label = useToolLabel();
+  // Позиция Блока своего запроса: новый запрос сразу берёт свою, без кадра со старой.
+  const [moved, setMoved] = useState({ request, block: request.block });
+  const block = moved.request === request ? moved.block : request.block;
+  const blockRef = useRef(block);
+  blockRef.current = block;
+  useEffect(() => {
+    let current = request.block;
+    if (current === undefined) return;
+    const follow = ({ transaction }: EditorEvents["transaction"]) => {
+      current = transaction.mapping.map(current!);
+      setMoved({ request, block: current });
+    };
+    editor.on("transaction", follow);
+    return () => void editor.off("transaction", follow);
+  }, [editor, request]);
+  const anchorRef = useRef({
+    getBoundingClientRect: () => {
+      const node = blockRef.current === undefined ? null : editor.view.nodeDOM(blockRef.current);
+      if (node instanceof HTMLElement) return node.getBoundingClientRect();
+      const { from, to } = editor.state.selection;
+      return posToDOMRect(editor.view, from, to);
+    },
+  });
+  return (
+    <Popover open={open} onOpenChange={onOpenChange}>
+      <PopoverAnchor virtualRef={anchorRef} />
+      <ToolPopoverFrame editor={editor} label={label(request.label)} className={request.className}>
+        {request.popover({
+          editor,
+          close: () => onOpenChange(false),
+          pos: block ?? editor.state.selection.from,
+        })}
+      </ToolPopoverFrame>
+    </Popover>
+  );
+}