@olddevs/ui 0.0.0-stage → 4.0.0

package/src/components/overlays/ModalHeader.tsx

@@ -0,0 +1,125 @@
+"use client";
+
+import type { ComponentType, ReactNode } from "react";
+import { cn } from "../../lib/cn.js";
+import { useMessages } from "../../i18n/useMessages.js";
+import { CloseIcon } from "../../icons.js";
+import { Button } from "../actions/Button.js";
+
+/** Всё, что нужно от компонента заголовка: принять `id`, класс и содержимое. */
+type TitleProps = { id?: string; className?: string; children?: ReactNode };
+
+export interface ModalHeaderProps {
+  /**
+   * Заголовок окна: одна строка слева в шапке.
+   *
+   * `ReactNode`, а не строка: во фронте рядом с текстом
+   * регулярно стоит счётчик выбранного — «В коллекцию (12)», где скобка
+   * набрана другим кеглем и цветом.
+   */
+  title: ReactNode;
+  /**
+   * `id` заголовка, чтобы сослаться на него из `aria-labelledby`.
+   *
+   * Нужен вызывающему, чтобы сослаться на него из
+   * `aria-labelledby` своего диалога: имя окна знает только он, и назначить
+   * его здесь мы не можем.
+   */
+  titleId?: string;
+  /**
+   * Строка под заголовком: слаг, дата, счётчик.
+   *
+   * Отдельным пропом, а не внутри
+   * `title`, потому что `<h2>` принимает только фразовое содержимое — блочная
+   * разметка внутри заголовка невалидна, а подпись почти всегда блочная.
+   */
+  subtitle?: ReactNode;
+  /** Иконка слева от заголовка. Цвет задаёт потребитель — он же знает тон окна. */
+  icon?: ReactNode;
+  /**
+   * Обработчик закрытия. Кнопка рисуется, только если он передан.
+   *
+   * Отдельного пропа «скрыть кнопку закрытия» нет намеренно: во фронте кнопка
+   * пропадает на время отправки формы, и это выражается тем же самым —
+   * `onClose={loading ? undefined : закрыть}`. Ещё один булев проп описывал бы
+   * ровно то же состояние вторым способом.
+   */
+  onClose?: () => void;
+  /** Доступное имя кнопки закрытия. */
+  closeLabel?: string;
+  /**
+   * Чем рендерить заголовок. По умолчанию `<h2>`.
+   *
+   * Нужно ровно одному потребителю — `Dialog`, который передаёт сюда
+   * `Dialog.Title` из Radix. Тот не просто рисует заголовок: он регистрирует
+   * его в контексте диалога, и `aria-labelledby` проставляется сам. Без этого
+   * пришлось бы либо дублировать разметку шапки внутри `Dialog` (а она вынесена
+   * сюда именно потому, что повторялась десять раз), либо оставить в консоли
+   * предупреждение Radix о диалоге без заголовка.
+   */
+  titleComponent?: ComponentType<TitleProps> | "h2";
+  /** Классы на корень шапки. */
+  className?: string;
+}
+
+/**
+ * Шапка модального окна: заголовок слева, кнопка закрытия справа, линия снизу.
+ *
+ * Перенесена в кит потому, что повторялась ДЕСЯТЬ раз байт-в-байт — включая
+ * набор классов `border-line-soft flex items-center justify-between border-b
+ * px-5 py-4` и `m-0 text-base font-bold` на заголовке. Ровно тот случай, когда
+ * копия расходится молча: достаточно поправить отступ в одном диалоге, и он
+ * начинает отличаться от девяти остальных, а заметит это только глаз.
+ *
+ * Изначально в план был записан другой компонент — проп `closable` у
+ * `ModalOverlay`, рисующий крестик в углу подложки. От него отказались, увидев
+ * код: НИ ОДИН из пятнадцати крестиков во фронте не стоит в углу, все они
+ * лежат в строке шапки рядом с заголовком. Тот проп не убрал бы ни одного
+ * повтора и добавил бы неиспользуемый API.
+ */
+export function ModalHeader({
+  title,
+  titleId,
+  subtitle,
+  icon,
+  onClose,
+  closeLabel,
+  titleComponent: Title = "h2",
+  className,
+}: ModalHeaderProps) {
+  const messages = useMessages();
+
+  return (
+    <div
+      className={cn(
+        "border-line-soft flex items-center justify-between border-b px-5 py-4",
+        className
+      )}
+    >
+      <div className="flex min-w-0 items-center gap-2.5">
+        {icon}
+        <div className="min-w-0">
+          {/*
+            `id` передаётся, ТОЛЬКО если он задан. Явный `id={undefined}`
+            затирает собственный идентификатор `Dialog.Title` из Radix, и
+            `aria-labelledby` окна начинает указывать в пустоту — то есть
+            диалог остаётся без доступного имени, ровно как до этого примитива.
+          */}
+          <Title {...(titleId ? { id: titleId } : {})} className="m-0 truncate text-base font-bold">
+            {title}
+          </Title>
+          {subtitle ? <div className="text-fg-3 mt-0.5 truncate">{subtitle}</div> : null}
+        </div>
+      </div>
+      {onClose ? (
+        <Button
+          variant="ghost"
+          iconOnly
+          aria-label={closeLabel ?? messages.common.close}
+          icon={<CloseIcon size={18} />}
+          onClick={onClose}
+        />
+      ) : null}
+    </div>
+  );
+}

package/src/components/overlays/ModalOverlay.tsx

@@ -0,0 +1,108 @@
+"use client";
+
+import { useEffect, useRef, type ReactNode } from "react";
+import { cn } from "../../lib/cn.js";
+import { hasOpenAriaOverlay, OVERLAY_LAYER } from "../../lib/overlay-layer.js";
+import { useOverlayLayer } from "../../hooks/useOverlayLayer.js";
+
+export interface ModalOverlayProps {
+  /** Вызывается по клику на подложку и по Escape. */
+  onClose: () => void;
+  /** Класс z-index: у приложения несколько слоёв оверлеев. */
+  zIndex?: string;
+  /** Вертикальное выравнивание содержимого. */
+  align?: "center" | "start";
+  /** Цвет подложки; по умолчанию `--overlay-scrim`. */
+  backdrop?: string;
+  /** Радиус размытия подложки. */
+  blur?: string;
+  /** Закрывать ли по Escape. */
+  escape?: boolean;
+  /** Классы на обёртку содержимого. */
+  className?: string;
+  /** Содержимое поверх подложки — само окно. */
+  children?: ReactNode;
+}
+
+/**
+ * Затемнённая подложка под модальным окном.
+ *
+ * ЧЕГО ЗДЕСЬ НЕТ И ПОЧЕМУ. Это не диалог, а только подложка: ни `role="dialog"`,
+ * ни `aria-modal`, ни ловушки фокуса, ни блокировки прокрутки. Полноценный
+ * диалог требует доступного имени, а имя знает только вызывающий — навесить
+ * `role="dialog"` без имени значит сделать хуже, чем без роли вовсе:
+ * скринридер объявит безымянный диалог. Ловушка фокуса и блокировка прокрутки
+ * во фронте живут отдельными хуками (`useScrollLock`), и тащить их сюда —
+ * отдельное решение, а не побочный эффект переезда.
+ *
+ * То есть примитив честно делает одно: гасит фон, ловит Escape и клик мимо.
+ *
+ * ВЫХОДНОЙ АНИМАЦИИ ЗДЕСЬ НЕТ, и это не недоделка. Волна 29 дала уход всем
+ * оверлеям кита, кроме этого: у `ModalOverlay` нет пропа `open` — потребитель
+ * монтирует его условием (`{isOpen && <ModalOverlay>}`), и в момент закрытия
+ * узла уже нет в дереве. Анимировать нечего: уходить должен элемент, а он
+ * исчез до того, как о закрытии стало известно.
+ *
+ * Дать ему уход можно только одним способом: принять `open` внутрь и удерживать
+ * узел самому, пока идёт анимация, — как это делают Radix и react-aria. Это
+ * смена контракта и поломка существующих вызовов, то есть отдельное решение, а
+ * не побочный эффект волны про движение.
+ */
+export function ModalOverlay({
+  onClose,
+  zIndex = OVERLAY_LAYER.modal,
+  align = "center",
+  backdrop = "var(--overlay-scrim)",
+  blur = "4px",
+  escape = true,
+  className,
+  children,
+}: ModalOverlayProps) {
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const layer = useOverlayLayer(true, rootRef);
+
+  useEffect(() => {
+    if (!escape) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Escape") return;
+
+      /*
+        Отвечает ТОЛЬКО верхний слой, и только если чужой не занял событие.
+
+        Слушатель висел на `document` в фазе всплытия и реагировал на любой
+        Escape: две вложенные подложки схлопывались одним нажатием, а `Select`
+        или `Popover` внутри подложки закрывался вместе с ней целиком. Radix к
+        этому моменту уже обработал событие в фазе ЗАХВАТА и позвал
+        `preventDefault()` — подложка это игнорировала. Разбор — ADR-0041.
+      */
+      if (e.defaultPrevented) return;
+      if (hasOpenAriaOverlay()) return;
+      if (!layer.isTopmost()) return;
+      onClose();
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [escape, onClose]);
+
+  return (
+    <div
+      ref={rootRef}
+      onClick={onClose}
+      className={cn(
+        "animate-fadein fixed inset-0 flex justify-center overflow-auto p-6",
+        zIndex,
+        align === "start" ? "items-start" : "items-center"
+      )}
+      style={{ background: backdrop, backdropFilter: `blur(${blur})` }}
+    >
+      <div
+        // Клик по содержимому не должен закрывать окно — всплытие останавливается
+        // здесь, а не проверкой `e.target === e.currentTarget` снаружи.
+        onClick={(e) => e.stopPropagation()}
+        className={cn("animate-sheetin", className)}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/components/overlays/Popover.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+import * as PopoverPrimitive from "@radix-ui/react-popover";
+import { forwardRef, type ComponentPropsWithoutRef } from "react";
+import { cn } from "../../lib/cn.js";
+import { OVERLAY_LAYER } from "../../lib/overlay-layer.js";
+import { withoutToolbarAxis } from "../../lib/toolbar-axis.js";
+
+/**
+ * Всплывающая панель — подложка для выпадающих списков, календарей и подсказок
+ * со сложным содержимым.
+ *
+ * Составной API (`Popover` / `PopoverTrigger` / `PopoverContent`) здесь оправдан,
+ * в отличие от `SearchSelect`: у панели нет своего содержимого, она только
+ * позиционирует чужое, и «один компонент с пропсами» превратился бы в проброс
+ * десятка пропсов радикса наружу.
+ *
+ * Вторая внешняя зависимость пакета — `@radix-ui/react-popover`, в
+ * `peerDependencies`. Позиционирование у края экрана, порталы, возврат фокуса
+ * и закрытие по Escape — не то, что стоит писать заново.
+ */
+export const Popover = PopoverPrimitive.Root;
+export const PopoverTrigger = PopoverPrimitive.Trigger;
+export const PopoverAnchor = PopoverPrimitive.Anchor;
+export const PopoverClose = PopoverPrimitive.Close;
+
+/** Портал панели: ось `Toolbar`, из которой открыта панель, внутрь не проходит. */
+const Portal = withoutToolbarAxis(PopoverPrimitive.Portal);
+
+type RadixContentProps = ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>;
+
+/**
+ * Свойства панели: всё, что принимает `Content` из Radix, и те же свойства
+ * позиционирования, объявленные заново с описанием. У самой библиотеки на них
+ * нет документации, а таблицы Справочника строятся из неё. Типы — ровно Radix'а
+ * (`RadixContentProps[...]`): потребитель, передающий пропсы Radix, не получит
+ * новой ошибки компиляции.
+ */
+export interface PopoverContentProps extends RadixContentProps {
+  /** Отдать роль панели вашему элементу вместо встроенного `div`: свойства и `ref` сливаются с его собственными. По умолчанию `false`. */
+  asChild?: RadixContentProps["asChild"];
+  /** С какой стороны от триггера открывается панель: `top`, `right`, `bottom` или `left`. По умолчанию `bottom`; не хватает места — панель переходит на противоположную сторону. */
+  side?: RadixContentProps["side"];
+  /** Расстояние от триггера до панели, в пикселях. По умолчанию 4. */
+  sideOffset?: RadixContentProps["sideOffset"];
+  /** Выравнивание панели вдоль выбранной стороны: `start`, `center` или `end`. По умолчанию `start`. */
+  align?: RadixContentProps["align"];
+  /** Сдвиг панели вдоль выравнивания, в пикселях. По умолчанию 0. */
+  alignOffset?: RadixContentProps["alignOffset"];
+  /** Минимальный отступ стрелки от края панели, в пикселях. Кит стрелку не рисует: нужен, только если вы вставляете её сами. По умолчанию 0. */
+  arrowPadding?: RadixContentProps["arrowPadding"];
+  /** Сдвигать и переворачивать панель, чтобы она не выходила за край окна. По умолчанию `true`. */
+  avoidCollisions?: RadixContentProps["avoidCollisions"];
+  /** Элемент или список элементов, за границы которых панель не выходит. По умолчанию — окно браузера. */
+  collisionBoundary?: RadixContentProps["collisionBoundary"];
+  /** Зазор до границы, за которую панель не выходит, в пикселях: число для всех сторон или объект по сторонам. По умолчанию 0. */
+  collisionPadding?: RadixContentProps["collisionPadding"];
+  /** Удерживать панель на виду, когда триггер прокручен за край: `partial` — пока виден хотя бы край триггера, `always` — всегда. По умолчанию `partial`. */
+  sticky?: RadixContentProps["sticky"];
+  /** Скрывать панель, когда триггер полностью ушёл из видимой области. По умолчанию `false`. */
+  hideWhenDetached?: RadixContentProps["hideWhenDetached"];
+  /** Когда пересчитывать положение панели: `optimized` — при изменении размеров и прокрутке, `always` — на каждом кадре. По умолчанию `optimized`. */
+  updatePositionStrategy?: RadixContentProps["updatePositionStrategy"];
+}
+
+export const PopoverContent = forwardRef<HTMLDivElement, PopoverContentProps>(
+  function PopoverContent({ className, align = "start", sideOffset = 4, ...rest }, ref) {
+    return (
+      <Portal>
+        <PopoverPrimitive.Content
+          ref={ref}
+          align={align}
+          sideOffset={sideOffset}
+          className={cn(
+            /*
+              `z-[120]` — выше слоя окон, а не ниже него.
+
+              Поповер всегда открывают из того, что уже на экране, поэтому под
+              оверлеем он не нужен никогда: при `z-50` панель уходила под
+              `ModalOverlay` (`z-90`) и под ящик редактирования во фронте
+              (`z-100`) — в разметке она есть, на экране её нет. Потребитель
+              лечил это по месту вызова: в четырёх местах фронта висели
+              `contentClassName="z-[200]"` и `"!z-[110]"`. Значит, неверным
+              было умолчание, а не вызовы.
+            */
+            OVERLAY_LAYER.popover,
+            "border-line-soft bg-bg-1 text-fg-0 shadow-2 rounded-md border p-0 outline-hidden",
+            /*
+              Вход — токеном кита, а не утилитами `tailwindcss-animate`.
+
+              Здесь стояли десять классов (`animate-in`, `zoom-in-95`,
+              `fade-in-0`, четыре `slide-in-from-*` и пара `-out`), и ни один из
+              них не давал ни единого правила: плагина, который их объявляет, в
+              зависимостях кита нет и не было. Сборка Tailwind поверх
+              `styles.css` и `src/` не содержала ни одного такого селектора, а у
+              открытой панели `animationName` был `none`. Три строки описывали
+              анимацию, которой не существовало.
+
+              Замена — свой токен `animate-popoverIn`, заведённый по образцу
+              `tooltipIn`: 0,16 с против 0,4 с у общего `fadein`, которым входят
+              меню и `Select` (`lib/menu.ts`). Общий токен подошёл бы по смыслу,
+              но не по скорости: он рассчитан на подложку окна во весь экран, а
+              якорная панель на четыреста миллисекунд — это заметно вяло.
+              Направленный въезд со стороны триггера при этом теряется: у токенов
+              кита осей `data-side` нет, а четыре токена ради четырёх сторон —
+              цена выше пропажи.
+
+              Выхода нет намеренно: `Tooltip` устроен так же (только вход), и
+              закрытие панели остаётся мгновенным — ровно таким, каким было всё
+              это время.
+            */
+            "data-[state=open]:animate-popoverIn data-[state=closed]:animate-popoverOut",
+            className
+          )}
+          {...rest}
+        />
+      </Portal>
+    );
+  }
+);

package/src/components/overlays/ShortcutsHelp.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+import { Fragment, useId, type ReactNode } from "react";
+import { useMessages } from "../../i18n/useMessages.js";
+import { hasContent } from "../../lib/empty.js";
+import { Dialog } from "./Dialog.js";
+import { Kbd } from "../content/Kbd.js";
+import { ScrollArea } from "../content/ScrollArea.js";
+
+export interface ShortcutItem {
+  /**
+   * Клавиши сочетания по порядку: `["Ctrl", "K"]`.
+   *
+   * Одна строка на клавишу, а не «Ctrl+K» целиком: каждая рисуется своей `Kbd`,
+   * а между ними встают разделитель для глаз и слово для слуха. Разбирать
+   * строку по `+` кит не берётся — сама клавиша бывает плюсом.
+   */
+  keys: string[];
+  /** Что делает сочетание: «Открыть поиск». */
+  description: ReactNode;
+}
+
+export interface ShortcutGroup {
+  /** Стабильный ключ группы для списка React; в разметку как `id` не попадает. */
+  id: string;
+  /** Подпись группы: «Навигация», «Редактирование». */
+  label: ReactNode;
+  /** Сочетания группы в порядке показа. */
+  items: ShortcutItem[];
+}
+
+export interface ShortcutsHelpProps {
+  /** Показано ли окно со сводом. */
+  open: boolean;
+  /** Окно просит сменить состояние: кнопка закрытия, Escape и клик мимо дают `false`. */
+  onOpenChange: (open: boolean) => void;
+  /** Заголовок окна. Не задан — «Горячие клавиши» из каталога сообщений. */
+  title?: ReactNode;
+  /** Группы сочетаний — уже собранные: что и под какой клавишей — знает приложение. */
+  groups: ShortcutGroup[];
+}
+
+/**
+ * Свод горячих клавиш в модальном окне.
+ *
+ * КИТ НЕ ЗНАЕТ СОЧЕТАНИЙ И НЕ ВЕШАЕТ ГЛОБАЛЬНЫХ КЛАВИШ. Какие клавиши есть у
+ * экрана и по какой из них открывается свод («?», как у GitHub и Linear), решает
+ * приложение: оно же сопоставляет нажатия, и с этим кит ничего сделать не может.
+ * Буквенные сочетания («G, H») стоит сверять по положению клавиши (`event.code`),
+ * иначе на русской раскладке они молчат; знак «?» — по символу (`event.key`). Обработчик глобальной
+ * клавиши, поставленный здесь, срабатывал бы и в поле ввода, и поверх чужого
+ * диалога — ровно там, где потребитель знает, что делать, а кит нет.
+ *
+ * СОЧЕТАНИЕ СОБИРАЕТ `Kbd`, А НЕ `Keyboard`. Одноимённый `Keyboard` — экранная
+ * клавиатура для ввода текста, а не способ нарисовать «Ctrl+K»; формулировка
+ * задачи путала их из-за имени.
+ *
+ * ЧТО УСЛЫШИТ СКРИНРИДЕР. Видимый «+» между клавишами убран из дерева
+ * доступности, вместо него читается слово из каталога: «Ctrl плюс K». Знак
+ * «+» озвучивается по настройкам пользователя — NVDA на умолчательном уровне
+ * пунктуации его пропускает, и «Ctrl K» звучало бы как две клавиши подряд, а не
+ * как сочетание. В отличие от `CommandPalette`, где сочетание у пункта целиком
+ * `aria-hidden`: там это подсказка рядом с пунктом, который и так выбирается.
+ * Здесь сочетание — единственное содержимое окна, скрыть его значило бы
+ * показать слепому пустую шпаргалку.
+ *
+ * ПУНКТ — СТРОКА СПИСКА, А НЕ `dl`. Пары «термин — определение» выглядят точнее,
+ * но их озвучка непоследовательна: часть пар скринридер/браузер читает без числа
+ * элементов и без границ пары. Список читают везде — «список, 3 элемента» — и
+ * порядок «описание, затем сочетание» в нём естественен.
+ *
+ * ГРУППА — ГРУППА С ИМЕНЕМ, а не заголовок. Уровень заголовка зависит от того,
+ * куда окно встало; тот же довод и тот же разбор, что у `NotificationList`.
+ *
+ * ПРОКРУТКА — ВНУТРИ ОКНА, на `ScrollArea` кита. Длинный свод не выталкивает
+ * шапку с крестиком за экран. Область получает остановку табуляции и имя: без
+ * первой пользователь клавиатуры не прокрутит её стрелками, без второй
+ * остановка безымянна.
+ */
+export function ShortcutsHelp({ open, onOpenChange, title, groups }: ShortcutsHelpProps) {
+  const messages = useMessages();
+  const baseId = useId();
+  // `hasContent`, а не `??`: пустая строка оставила бы окно без заголовка, а
+  // с ним — без доступного имени.
+  const heading = hasContent(title) ? title : messages.shortcutsHelp.title;
+  return (
+    <Dialog
+      open={open}
+      onClose={() => onOpenChange(false)}
+      title={heading}
+      className="w-full max-w-md"
+    >
+      <ScrollArea
+        label={messages.shortcutsHelp.list}
+        // Рамка фокуса внутри области: снаружи её срезало бы краем самой области.
+        // `relative` — не косметика: слова-разделители под `sr-only` абсолютно
+        // позиционированы, и без опорного предка они уезжали к подложке окна и
+        // растягивали её прокрутку на всю длину списка (нашла ручная проверка).
+        className="relative max-h-[min(70vh,32rem)] rounded-b-lg px-5 py-4 focus-visible:-outline-offset-2"
+      >
+        <div className="flex flex-col gap-5">
+          {groups
+            .filter((group) => group.items.length > 0)
+            .map((group, groupIndex) => {
+              // Номер, а не `group.id`: `aria-labelledby` — список идентификаторов
+              // через пробел, и `id` с пробелом оставил бы группу без имени.
+              const labelId = `${baseId}-${groupIndex}`;
+              return (
+                <div key={group.id} role="group" aria-labelledby={labelId}>
+                  <div
+                    id={labelId}
+                    className="text-fg-2 pb-2 text-[11px] font-bold tracking-wide uppercase"
+                  >
+                    {group.label}
+                  </div>
+                  <ul className="m-0 flex list-none flex-col gap-2 p-0">
+                    {group.items.map((item, index) => (
+                      <li key={index} className="flex items-center justify-between gap-4">
+                        <span className="text-fg-1 min-w-0 text-[13px]">{item.description}</span>
+                        <span className="flex shrink-0 items-center gap-1">
+                          {item.keys.map((key, keyIndex) => (
+                            <Fragment key={keyIndex}>
+                              {keyIndex > 0 && (
+                                <>
+                                  <span aria-hidden="true" className="text-fg-3 text-caption">
+                                    +
+                                  </span>
+                                  <span className="sr-only">
+                                    {messages.shortcutsHelp.keySeparator}
+                                  </span>
+                                </>
+                              )}
+                              <Kbd size="md">{key}</Kbd>
+                            </Fragment>
+                          ))}
+                        </span>
+                      </li>
+                    ))}
+                  </ul>
+                </div>
+              );
+            })}
+        </div>
+      </ScrollArea>
+    </Dialog>
+  );
+}

package/src/components/overlays/Tooltip.tsx

@@ -0,0 +1,89 @@
+"use client";
+
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import {
+  forwardRef,
+  type ComponentPropsWithoutRef,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { cn } from "../../lib/cn.js";
+import { OVERLAY_LAYER } from "../../lib/overlay-layer.js";
+
+export interface TooltipProps {
+  /** Текст подсказки. Пусто — тултипа нет, `children` рендерится как есть. */
+  content?: ReactNode;
+  /** Элемент, к которому крепится подсказка. Должен принимать ref. */
+  children: ReactElement;
+  /** С какой стороны от элемента показать подсказку: `top`, `right`, `bottom` или `left`. Не хватает места — Radix переносит на другую. */
+  side?: TooltipPrimitive.TooltipContentProps["side"];
+  /** Выравнивание подсказки вдоль стороны: `start`, `center` или `end`. */
+  align?: TooltipPrimitive.TooltipContentProps["align"];
+  /** Сколько миллисекунд наведение держится до показа. Не задано — задержка из `TooltipProvider`. */
+  delayDuration?: number;
+}
+
+/**
+ * Подсказка при наведении и фокусе.
+ *
+ * Единственный примитив пакета с внешней зависимостью — `@radix-ui/react-tooltip`.
+ * Она объявлена в `peerDependencies`, то есть ставит её потребитель: тултип
+ * держит фокус, Escape, порталы и позиционирование у края экрана, и своя
+ * реализация этого была бы не примитивом, а второй библиотекой.
+ *
+ * `TooltipProvider` здесь НЕ встроен в каждый экземпляр намеренно: провайдер
+ * задаёт общую задержку и группировку подсказок на всё приложение, и вложенные
+ * провайдеры эту группировку ломают. Потребитель ставит один на корень.
+ *
+ * Пустой `content` возвращает `children` без обёртки — так вызывающему не нужно
+ * ветвиться самому, а лишний слой DOM не появляется.
+ */
+export function Tooltip({ content, children, side, align, delayDuration }: TooltipProps) {
+  if (!content) return children;
+  return (
+    <TooltipPrimitive.Root delayDuration={delayDuration}>
+      <TooltipPrimitive.Trigger asChild>{children}</TooltipPrimitive.Trigger>
+      <TooltipContent side={side} align={align}>
+        {content}
+      </TooltipContent>
+    </TooltipPrimitive.Root>
+  );
+}
+
+export const TooltipContent = forwardRef<
+  HTMLDivElement,
+  ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>
+>(function TooltipContent({ className, sideOffset = 6, ...rest }, ref) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        ref={ref}
+        sideOffset={sideOffset}
+        className={cn(
+          // Полупрозрачная подложка на токенах темы: цвет меняется вместе с
+          // `data-theme` без участия JS.
+          //
+          // `z-[120]` — по той же причине, что у `Popover`: подсказку всегда
+          // вызывают из того, что уже на экране, поэтому под оверлеем она не
+          // нужна никогда. При `z-[60]` она уходила под `ModalOverlay` (`z-90`)
+          // и под ящик редактирования во фронте (`z-100`) — в разметке есть,
+          // на экране нет, причём ровно у кнопок с одними иконками, где
+          // подсказка и есть подпись.
+          OVERLAY_LAYER.popover,
+          "text-fg-0 border-line-soft shadow-2 rounded-control max-w-[240px] border px-2.5 py-1.5",
+          "bg-[color-mix(in_srgb,var(--bg-1)_85%,transparent)] backdrop-blur-[10px]",
+          "text-xs font-medium select-none",
+          "origin-[var(--radix-tooltip-content-transform-origin)]",
+          "data-[state=delayed-open]:animate-tooltipIn data-[state=instant-open]:animate-tooltipIn",
+          "data-[state=closed]:animate-tooltipOut",
+          className
+        )}
+        {...rest}
+      />
+    </TooltipPrimitive.Portal>
+  );
+});
+
+export const TooltipProvider = TooltipPrimitive.Provider;
+export const TooltipRoot = TooltipPrimitive.Root;
+export const TooltipTrigger = TooltipPrimitive.Trigger;