@olddevs/ui 0.0.0-stage → 4.0.0

package/src/components/actions/Segmented.tsx

@@ -0,0 +1,162 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { cn } from "../../lib/cn.js";
+import { hasContent } from "../../lib/empty.js";
+import { Tooltip } from "../overlays/Tooltip.js";
+
+export interface SegmentedOption<T extends string = string> {
+  /** Значение сегмента: оно приходит в `onChange` и сравнивается с `value` переключателя. */
+  value: T;
+  /** Подпись сегмента. Пустая строка считается отсутствием подписи. */
+  label?: ReactNode;
+  /** Иконка перед подписью. */
+  icon?: ReactNode;
+  /**
+   * Подсказка при наведении на сегмент и доступное имя сегмента без подписи.
+   *
+   * **Обязательна, если у сегмента нет подписи** —
+   * она же становится доступным именем. Отсутствием подписи считается и
+   * `undefined`, и пустая строка.
+   */
+  tooltip?: string;
+  /** Недоступный сегмент: режим есть, но сейчас применить его нельзя. */
+  disabled?: boolean;
+}
+
+export interface SegmentedProps<T extends string = string> {
+  /** Значение выбранного сегмента: переключатель управляемый, своего состояния не держит. */
+  value: T;
+  /** Вызывается с `value` сегмента, по которому нажали. */
+  onChange: (value: T) => void;
+  /** Сегменты по порядку слева направо. */
+  options: SegmentedOption<T>[];
+  /**
+   * На узком экране (< 640 пикселей) у сегмента остаётся одна иконка: подпись
+   * прячется только визуально и остаётся доступным именем кнопки.
+   *
+   * Свойство всего переключателя, а не отдельного сегмента: ряд, где часть
+   * вкладок со словами, а часть без, менял бы ширину при переключении, и
+   * кнопки прыгали бы под пальцем.
+   *
+   * Порог — тот же `sm`, что у `Chip.mobileIconOnly`. Наружу он не выносится:
+   * два потребителя с разными порогами разошлись бы в поведении без причины.
+   *
+   * `tooltip` при этом НЕ становится обязательным. Требование «сегмент без
+   * подписи обязан иметь подсказку» относится к настоящему отсутствию подписи
+   * (`label: ""`); здесь подпись есть, просто её не видно.
+   */
+  mobileIconOnly?: boolean;
+}
+
+/**
+ * Переключатель из нескольких сегментов — вид списка, режим поиска, период.
+ *
+ * Выбранный сегмент помечен `aria-pressed`, а не только фоном. Прежняя версия
+ * во фронте различала состояние исключительно цветом: для скринридера все
+ * сегменты выглядели одинаковыми безымянными кнопками, и понять, какой из них
+ * включён, было нельзя. Это тот же дефект, что был у переключателя тем.
+ *
+ * Сегменты без подписи (только иконка) обязаны иметь `tooltip` — он же даёт
+ * доступное имя через `aria-label`. Без него кнопка остаётся безымянной,
+ * и аудит axe роняет прогон как `critical`. Подписью не считается пустая
+ * строка: `label: ""` рядом с иконкой — это «только иконка».
+ *
+ * `mobileIconOnly` — ДРУГОЕ: подпись остаётся, её просто не видно на узком
+ * экране. Имя кнопки при этом берёт сама подпись, и подсказка не нужна —
+ * поэтому режим и живёт в ките, а не собирается у потребителя: спрятать
+ * подпись правильно это одна строка классов, а неправильно — три способа
+ * получить кнопку без имени, которую видно только аудитом.
+ */
+export function Segmented<T extends string = string>({
+  value,
+  onChange,
+  options,
+  mobileIconOnly = false,
+}: SegmentedProps<T>) {
+  return (
+    /*
+      `flex-wrap` — ПОВЕДЕНИЕ, А НЕ ВКУСОВЩИНА. Сегмент не сжимается
+      (`shrink-0` плюс `whitespace-nowrap`, и это правильно: сжатая подпись
+      вкладки читается хуже перенесённой). Без переноса единственный исход на
+      узком экране — выезд за край и горизонтальная прокрутка, то есть
+      нарушение WCAG 1.4.10 у каждого потребителя.
+
+      Зазор развёрнут по осям: между сегментами 2 пикселя, между рядами 4.
+      Один `gap-0.5` на обе оси поставил бы ряды в те же 2 пикселя, и два ряда
+      прочитались бы слипшейся сеткой, а не одним контролом.
+    */
+    <div className="border-line-soft bg-bg-2 rounded-control inline-flex flex-wrap gap-x-0.5 gap-y-1 border p-[3px]">
+      {options.map((opt) => {
+        const selected = value === opt.value;
+        /*
+          ПОДПИСЬ ПРЯЧЕТСЯ ТОЛЬКО У СЕГМЕНТА С ИКОНКОЙ.
+
+          У сегмента без иконки прятать подпись не в пользу чего: кнопка
+          осталась бы пустой — имя есть, на экране ничего. Это хуже неровного
+          ряда с одним словом: пустую кнопку не нажимают, её не видно.
+
+          Режим при этом остаётся свойством всего переключателя — здесь не
+          выбор потребителя, а защита от набора, в котором иконку забыли.
+        */
+        const hideLabel = mobileIconOnly && opt.icon != null;
+        const button = (
+          <button
+            key={opt.value}
+            type="button"
+            aria-pressed={selected}
+            /*
+              Пустая строка — это ОТСУТСТВИЕ подписи, а не подпись.
+
+              Проверка была `opt.label == null`, и потребитель, передавший
+              `label: ""` рядом с иконкой (штатный способ сказать «только
+              иконка»), получал кнопку без имени: пустая строка не `null`,
+              условие не срабатывало, `aria-label` не проставлялся. Докстрока
+              при этом обещала обратное, а аудит ронял прогон как `critical`.
+            */
+            aria-label={hasContent(opt.label) ? undefined : opt.tooltip}
+            disabled={opt.disabled}
+            onClick={() => onChange(opt.value)}
+            className={cn(
+              "inline-flex shrink-0 cursor-pointer items-center gap-1.5 rounded-sm px-3 py-1.5",
+              // Вокруг одной иконки `px-3` читается широким: кнопка выходит
+              // заметно шире своей высоты и перестаёт походить на вкладку.
+              // Отступ режется вместе с подписью и тем же брейкпоинтом.
+              hideLabel && "max-sm:px-2",
+              "text-xs font-semibold whitespace-nowrap transition-colors",
+              "focus-visible:outline-accent-strong focus-visible:outline-2 focus-visible:outline-offset-2",
+              "disabled:pointer-events-none disabled:opacity-50",
+              selected ? "bg-bg-3 text-fg-0" : "text-fg-2 hover:text-fg-0 bg-transparent"
+            )}
+          >
+            {opt.icon}
+            {/*
+              Подпись прячется классом «видно только скринридеру», а не
+              `hidden` и не выброшенными детьми: и то и другое убирает узел из
+              дерева доступности, то есть оставляет кнопку БЕЗ ИМЕНИ. Видно
+              это было бы только аудитом — глазами иконка на месте, вкладка
+              работает. Тот же приём и тот же один узел, что у `Chip`: копия
+              подписи рядом читалась бы дважды.
+            */}
+            {hasContent(opt.label) ? (
+              <span className={hideLabel ? "sr-only sm:not-sr-only sm:inline" : undefined}>
+                {opt.label}
+              </span>
+            ) : null}
+          </button>
+        );
+
+        // Ключ живёт на самой кнопке, поэтому обёртка нужна только там, где
+        // есть подсказка: `Tooltip` принимает ровно один элемент и `key`
+        // на нём же и остаётся.
+        return opt.tooltip ? (
+          <Tooltip key={opt.value} content={opt.tooltip}>
+            {button}
+          </Tooltip>
+        ) : (
+          button
+        );
+      })}
+    </div>
+  );
+}

package/src/components/actions/Spinner.tsx

@@ -0,0 +1,80 @@
+"use client";
+
+import { forwardRef } from "react";
+import { cn } from "../../lib/cn.js";
+import { useMessages } from "../../i18n/useMessages.js";
+import { TONE_TOKENS, type Size, type Tone } from "../../lib/variants.js";
+
+export interface SpinnerProps {
+  /** Размер кольца: `sm`, `md` или `lg`. По умолчанию `md`. */
+  size?: Size;
+  /** Цвет кольца из словаря тонов. По умолчанию `accent`. */
+  tone?: Tone;
+  /** Доступное имя. По умолчанию — «Загрузка». */
+  label?: string;
+  /** Классы на корневой элемент. */
+  className?: string;
+}
+
+const SIZES: Record<Size, string> = {
+  sm: "size-3.5 border-[1.5px]",
+  md: "size-4 border-2",
+  lg: "size-6 border-2",
+};
+
+/**
+ * Крутящийся индикатор — когда неизвестно ни сколько ждать, ни что появится.
+ *
+ * ГРАНИЦА С СОСЕДЯМИ, и её стоит держать в голове:
+ *
+ *   `Skeleton`  — форма будущего содержимого известна: строки списка, карточка.
+ *   `Progress`  — известна доля выполненной работы.
+ *   `Spinner`   — не известно ни то, ни другое: отправка формы, ожидание ответа
+ *                 без раскладки под него.
+ *
+ * Скелетон вместо спиннера там, где форма известна, — не украшение: он
+ * удерживает раскладку, и содержимое не прыгает при появлении.
+ *
+ * `role="status"` с невидимой подписью, а не голый `div`: без имени вращающийся
+ * кружок для скринридера просто не существует, и пользователь не узнаёт, что
+ * страница чем-то занята.
+ *
+ * Вращение при `prefers-reduced-motion` НЕ гасится — это одно из двух
+ * названных исключений кита (ADR-0043; второе — неопределённый `Progress`).
+ * Довод тот же, что и у `role="status"` абзацем выше: спиннер — единственное,
+ * чем кит сообщает «идёт работа». Остановленный кружок не спокойнее
+ * крутящегося, он выглядит сломанным, и пользователь теряет сведения, а не
+ * раздражитель. W3C выводит существенное движение из-под правила; здесь оно
+ * существенное.
+ *
+ * Чтобы исключение было видно не только отсюда, `--animate-spin` объявлен в
+ * `@theme` кита явно: гейт читает `styles.css` и о дефолтной теме Tailwind не
+ * знает.
+ *
+ * До волны 27 этот абзац утверждал обратное — что анимация гасится «глобальным
+ * правилом пакета». Правила не существовало: во всём репозитории строка
+ * `prefers-reduced-motion` встречалась ровно один раз, в нём самом.
+ */
+export const Spinner = forwardRef<HTMLSpanElement, SpinnerProps>(function Spinner(
+  { size = "md", tone = "accent", label, className },
+  ref
+) {
+  const messages = useMessages();
+  const t = TONE_TOKENS[tone];
+
+  return (
+    <span ref={ref} role="status" className={cn("inline-flex items-center", className)}>
+      <span
+        aria-hidden
+        className={cn(
+          // Кольцо с одним прозрачным сектором: три стороны цветные, четвёртая
+          // прозрачная — отсюда и видно вращение.
+          "animate-spin rounded-full border-current border-t-transparent",
+          SIZES[size],
+          t.fg
+        )}
+      />
+      <span className="sr-only">{label ?? messages.spinner.label}</span>
+    </span>
+  );
+});

package/src/components/actions/SplitButton.tsx

@@ -0,0 +1,164 @@
+"use client";
+
+import { useEffect, useState, type MouseEventHandler, type ReactNode } from "react";
+import { useMessages } from "../../i18n/useMessages.js";
+import { ChevronDownIcon } from "../../icons.js";
+import type { Size, Tone, Variant } from "../../lib/variants.js";
+import { Button } from "./Button.js";
+import { ButtonGroup } from "./ButtonGroup.js";
+import { Menu, MenuButton, MenuTrigger } from "../overlays/Menu.js";
+import { BUTTON_ICON_SIZE } from "../../lib/button.js";
+
+export interface SplitButtonProps {
+  /**
+   * Подпись главного действия — строка, а не узел.
+   *
+   * Это единственное ограничение компонента по сравнению с `Button`, и оно
+   * следует из его устройства: из подписи строится доступное имя раскрывателя
+   * («Другие действия: Экспорт»). Узел дал бы имя, которого нет, — или
+   * потребовал бы второго пропа с той же подписью строкой, то есть двух мест,
+   * где написано одно и то же, и они разошлись бы при первой правке.
+   */
+  label: string;
+  /** Иконка слева у главного действия. */
+  icon?: ReactNode;
+  /** Главное действие. Раскрыватель его не зовёт. */
+  onClick?: MouseEventHandler<HTMLButtonElement>;
+  /**
+   * Гасит обе кнопки сразу.
+   *
+   * Раздельной выключенности здесь нет намеренно: живой раскрыватель при мёртвом
+   * действии предлагает варианты того, что сделать нельзя.
+   */
+  disabled?: boolean;
+  /**
+   * Главное действие отправляется: кольцо вместо иконки, `aria-busy`.
+   *
+   * Раскрыватель на это время тоже гаснет — по той же причине, что и при
+   * `disabled`. Открытое меню посреди отправки предлагает второй способ сделать
+   * то, что уже делается.
+   */
+  loading?: boolean;
+  /** Подача обеих кнопок: оси словаря те же, что у `Button`. Без значения действует умолчание `Button`. */
+  variant?: Variant;
+  /** Тон обеих кнопок: ось словаря та же, что у `Button`. Без значения действует умолчание `Button`. */
+  tone?: Tone;
+  /** Размер обеих кнопок: ось словаря та же, что у `Button`. Без значения действует умолчание `Button`. */
+  size?: Size;
+  /** Пункты меню: `MenuItem`, `MenuSection`, `MenuSeparator`. */
+  children?: ReactNode;
+  /**
+   * Сторона, с которой раскрывается панель меню.
+   *
+   * Четыре значения из шести, которые умеет `Menu`: боковые (`right top`,
+   * `left top`) сузили намеренно — панель, уезжающая вбок от раскрывателя,
+   * встаёт поверх главного действия, то есть закрывает то, ради чего пришли.
+   */
+  placement?: "bottom start" | "bottom end" | "top start" | "top end";
+  /**
+   * Классы на группу, а не на кнопку.
+   *
+   * Отличие от одноимённого пропа `Button`, и оно вынужденное: элементов здесь
+   * два, и «класс на кнопку» не имеет однозначного адресата.
+   */
+  className?: string;
+}
+
+/**
+ * Кнопка главного действия и раскрыватель его вариантов рядом.
+ *
+ * ДВЕ ОТДЕЛЬНЫЕ КНОПКИ, А НЕ КНОПКА С ЗОНОЙ. Одна кнопка, у которой правая
+ * часть открывает меню, — это элемент с двумя разными исходами и одним
+ * доступным именем: с клавиатуры до второго исхода не добраться вовсе, а
+ * скринридер объявит одно действие вместо двух. Разделение здесь не оформление,
+ * а разные элементы управления.
+ *
+ * ИМЯ РАСКРЫВАТЕЛЯ СТРОИТСЯ ИЗ ПОДПИСИ ДЕЙСТВИЯ, и это единственное собственное
+ * решение компонента. Без него в речи идут «Экспорт» и следом безымянная кнопка
+ * со стрелкой — а таких стрелок на странице обычно несколько, и различить их
+ * нечем. Отсюда и требование к `label` быть строкой.
+ *
+ * Вид и раскладка целиком чужие: `ButtonGroup` срезает внутренние углы и
+ * схлопывает соседние рамки, `Button` и `MenuButton` берут вид из
+ * `lib/button.ts`. Своей палитры компонент не заводит — оси `variant`, `tone` и
+ * `size` те же, что у кнопки, и значат то же самое.
+ *
+ * Почему `MenuButton`, а не второй `Button`: `MenuTrigger` передаёт триггеру
+ * свои пропы через `ButtonContext` react-aria, и обычный `<button>` этого
+ * контекста не читает — меню молча не откроется. Разбор — в докстроке `Menu`.
+ *
+ * ТРИГГЕР УПРАВЛЯЕМЫЙ, И ЭТО НЕ ПРИХОТЬ. Неуправляемый `MenuTrigger` держит
+ * открытую панель независимо от того, что стало с кнопкой: выключенность гасила
+ * бы только раскрыватель, а уже раскрытое меню оставалось бы в DOM и его пункты
+ * продолжали бы срабатывать. Компонент выглядел бы выключенным, а второй способ
+ * сделать действие работал бы — ровно то, что обещание `disabled` отрицает.
+ *
+ * Остальные пропы наружу НЕ пробрасываются, и это тоже следствие двух
+ * элементов: у `id`, `type` или `data-*` здесь нет однозначного адресата.
+ * Кнопке, которая обязана отправлять форму, нужен `Button` с `MenuTrigger`
+ * рядом, собранные вручную, — у них адресат каждый свой.
+ */
+export function SplitButton({
+  label,
+  icon,
+  onClick,
+  disabled = false,
+  loading = false,
+  variant,
+  tone,
+  size,
+  children,
+  placement = "bottom end",
+  className,
+}: SplitButtonProps) {
+  const messages = useMessages();
+  const moreLabel = messages.splitButton.more({ action: label });
+  const off = disabled || loading;
+  const [open, setOpen] = useState(false);
+
+  /*
+    Выключение не только прячет панель, но и ЗАБЫВАЕТ, что она была открыта.
+
+    `isOpen={open && !off}` гасит показ, но управляемая смена `isOpen` не зовёт
+    `onOpenChange`, поэтому само `open` остаётся `true`. Без этой уборки меню
+    раскрывалось бы само по себе, когда выключенность снимут: открыли меню →
+    пошла отправка → панель закрылась → отправка кончилась → панель вернулась,
+    хотя пользователь ничего не нажимал.
+  */
+  useEffect(() => {
+    if (off) setOpen(false);
+  }, [off]);
+
+  return (
+    <ButtonGroup className={className}>
+      <Button
+        variant={variant}
+        tone={tone}
+        size={size}
+        icon={icon}
+        disabled={disabled}
+        loading={loading}
+        onClick={onClick}
+      >
+        {label}
+      </Button>
+      <MenuTrigger isOpen={open && !off} onOpenChange={setOpen}>
+        <MenuButton
+          variant={variant}
+          tone={tone}
+          size={size}
+          iconOnly
+          disabled={off}
+          aria-label={moreLabel}
+          icon={<ChevronDownIcon size={BUTTON_ICON_SIZE[size ?? "md"]} aria-hidden />}
+        />
+        {/*
+          Своего `aria-label` панели не даётся: `MenuTrigger` связывает её с
+          триггером, и имя приходит оттуда. Второй источник имени разошёлся бы
+          с первым при правке одного из них. Что имя есть — сторожит тест.
+        */}
+        <Menu placement={placement}>{children}</Menu>
+      </MenuTrigger>
+    </ButtonGroup>
+  );
+}

package/src/components/actions/StatusBadge.tsx

@@ -0,0 +1,61 @@
+"use client";
+
+import { forwardRef, type ComponentPropsWithoutRef, type ReactNode } from "react";
+import { cn } from "../../lib/cn.js";
+import { TONE_TOKENS, type Size, type Tone } from "../../lib/variants.js";
+
+export interface StatusBadgeProps extends Omit<ComponentPropsWithoutRef<"span">, "children"> {
+  /** Подпись состояния. Сопоставление «статус → тон и подпись» остаётся за потребителем. */
+  children: ReactNode;
+  /** Цвет подложки, текста и точки из словаря тонов. По умолчанию `neutral`. */
+  tone?: Tone;
+  // Через Extract от общего Size, а не собственным union: если в словарь добавят
+  // размер, здесь это увидит компилятор, а не читатель кода.
+  /** Высота бейджа: `sm` — компактный, `md` — выше. По умолчанию `sm`. */
+  size?: Extract<Size, "sm" | "md">;
+  /** Точка-индикатор слева, цвета тона. По умолчанию показана. */
+  dot?: boolean;
+}
+
+const SIZES = {
+  sm: "h-[18px] gap-1.5 pr-2 pl-1.5 text-[11px]",
+  md: "h-[22px] gap-1.5 pr-2.5 pl-2 text-xs",
+} as const;
+
+/**
+ * Бейдж состояния: приглушённая подложка тона, текст цветом тона, точка слева.
+ *
+ * Версия во фронте держала внутри словарь из 11 доменных статусов вместе с
+ * русскими подписями — `in_progress` → «В процессе», `duplicate` → «Дубль».
+ * Пакету знать о доменных статусах нельзя: он не про обои и не про публикации.
+ * Поэтому здесь остаётся только форма, а сопоставление «статус → тон + подпись»
+ * живёт во фронте, рядом с доменом.
+ *
+ * Размеры и отступы прежней версии задавались инлайн-числами (`fontSize: 11`,
+ * `padding: "3px 8px 3px 6px"`) мимо шкалы токенов — здесь это утилиты.
+ */
+export const StatusBadge = forwardRef<HTMLSpanElement, StatusBadgeProps>(function StatusBadge(
+  { children, tone = "neutral", size = "sm", dot = true, className, ...rest },
+  ref
+) {
+  const t = TONE_TOKENS[tone];
+
+  return (
+    <span
+      ref={ref}
+      className={cn(
+        "inline-flex items-center rounded-full font-semibold tracking-wider whitespace-nowrap",
+        SIZES[size],
+        t.bg,
+        t.fg,
+        className
+      )}
+      {...rest}
+    >
+      {dot ? (
+        <span aria-hidden="true" className={cn("h-1.5 w-1.5 shrink-0 rounded-full", t.dotBg)} />
+      ) : null}
+      {children}
+    </span>
+  );
+});

package/src/components/actions/Toaster.tsx

@@ -0,0 +1,148 @@
+"use client";
+
+import { type ReactNode } from "react";
+import { Toaster as SonnerToaster, toast as sonnerToast } from "sonner";
+import { ErrorIcon, InfoIcon, SuccessIcon, WarningIcon } from "../../icons.js";
+import { TONE_TOKENS } from "../../lib/variants.js";
+
+export interface ToasterProps {
+  /** Угол или край экрана, в котором стекаются тосты. По умолчанию `bottom-right`. */
+  position?: "top-right" | "top-center" | "bottom-right" | "bottom-center";
+  /** Сколько тост держится на экране, мс. По умолчанию 4000. */
+  duration?: number;
+  /** Тема. Нужна витрине; в приложении цвета и так приходят из токенов. */
+  theme?: "light" | "dark" | "system";
+  /**
+   * Имя CSS-переменной с высотой нижней панели приложения. Тосты у нижнего края
+   * встают на эту высоту выше обычного отступа, а не под панель. По умолчанию
+   * `--bottombar-h` — её публикует слот `bottomBar` у `AppShell`. Переменной нет
+   * (панели нет или она скрыта на широком экране) — отступ прежний. Для верхних
+   * позиций не имеет значения.
+   */
+  offsetVar?: string;
+}
+
+/** Умолчание общее с `AppShell` (`bottomBarHeightVar`). */
+const DEFAULT_OFFSET_VAR = "--bottombar-h";
+
+/**
+ * Область, в которой всплывают тосты. Ставится один раз рядом с корнем.
+ *
+ * СОБРАН НА `sonner`, а не написан заново, и не на react-aria: тостов она не
+ * даёт вовсе. Стек, очередь, свайп, пауза при наведении, схлопывание пачки —
+ * всё это у sonner уже есть и проверено; своя реализация была бы не примитивом,
+ * а второй библиотекой. Ровно та же логика, по которой порталы арендованы у
+ * Radix, а поведение полей — у react-aria.
+ *
+ * Вид задаётся токенами пакета через `--normal-*`, которые sonner подставляет
+ * в свои внутренние классы. Умолчания sonner при этом не отключаются наполовину:
+ * `unstyled` увёл бы за собой и раскладку, и анимации, а вместе с ними смысл
+ * брать библиотеку.
+ */
+export function Toaster({
+  position = "bottom-right",
+  duration = 4000,
+  theme,
+  offsetVar = DEFAULT_OFFSET_VAR,
+}: ToasterProps) {
+  return (
+    <SonnerToaster
+      position={position}
+      // Отступ sonner по умолчанию (24px, на узком экране 16px) сохраняется,
+      // к нему прибавляется высота нижней панели: тост поверх `MobileTabBar`
+      // перекрывал бы вкладки. `calc` с запасным `0px` не меняет вид там, где
+      // панели нет. Ширина, на которой sonner переключается на `mobileOffset`,
+      // его собственная (600px), а панель скрывается на `md` — поэтому на
+      // промежутке 600–768px нужны обе записи.
+      offset={{ bottom: `calc(var(${offsetVar}, 0px) + 24px)` }}
+      mobileOffset={{ bottom: `calc(var(${offsetVar}, 0px) + 16px)` }}
+      duration={duration}
+      theme={theme}
+      // `--normal-*` — публичные переменные sonner: он красит ими подложку,
+      // текст и рамку тоста. Отдаём токены пакета, и тост едет за темой
+      // приложения сам, без переключателя внутри библиотеки.
+      style={
+        {
+          // Подложка полупрозрачная и с размытием — так тост выглядел во фронте
+          // до переезда, и этот вид уезжает в пакет, а не теряется: размытие
+          // уже часть словаря системы (подложка диалога), а «стеклянность»
+          // всплывающего слоя — решение дизайн-системы, а не отдельного экрана.
+          "--normal-bg": "color-mix(in srgb, var(--surface-elevated) 82%, transparent)",
+          "--normal-text": "var(--fg-0)",
+          "--normal-border": "var(--line-soft)",
+        } as React.CSSProperties
+      }
+      toastOptions={{
+        classNames: {
+          toast: "rounded-lg border text-[13px] shadow-[var(--shadow-2)] backdrop-blur-[14px]",
+          title: "font-semibold",
+          description: "text-fg-2 text-[12px]",
+          actionButton: TONE_TOKENS.accent.solid,
+          cancelButton: TONE_TOKENS.neutral.solid,
+        },
+      }}
+      icons={{
+        success: <SuccessIcon size={16} className="text-success-strong" />,
+        error: <ErrorIcon size={16} className="text-danger-strong" />,
+        warning: <WarningIcon size={16} className="text-warning-strong" />,
+        info: <InfoIcon size={16} className="text-accent-strong" />,
+      }}
+    />
+  );
+}
+
+export interface ToastOptions {
+  /** Вторая строка — подробности. У ошибки сюда идёт текст с сервера. */
+  description?: ReactNode;
+  /** Сколько этот тост держится на экране, мс. Перекрывает `duration` области `Toaster`. */
+  duration?: number;
+  /** Кнопка действия в тосте: подпись и обработчик нажатия. */
+  action?: { label: string; onClick: () => void };
+}
+
+/**
+ * Тосты по тонам словаря.
+ *
+ * ЧЕТЫРЕ МЕТОДА, А НЕ ПРОИЗВОЛЬНЫЙ JSX. У sonner есть и `toast.custom`, и
+ * произвольное содержимое — здесь их нет намеренно: тост, умеющий всё,
+ * перестаёт быть частью системы, и через полгода в приложении оказывается
+ * пять разных тостов. Тон — это словарь пакета, а не оформление места вызова.
+ *
+ * `neutral` выражается `info`: отдельного «никакого» тона у события не бывает.
+ *
+ * ЧТО СЮДА НЕ ВХОДИТ: разбор ошибки API. `extractErrorMessage` остаётся у
+ * потребителя — формат ответов сервера это его знание, а не дизайн-системы.
+ * Вызов выглядит так:
+ *
+ *     toast.error("Не удалось сохранить", { description: extractErrorMessage(err) })
+ */
+export const toast = {
+  success: (message: ReactNode, options?: ToastOptions) => sonnerToast.success(message, options),
+  error: (message: ReactNode, options?: ToastOptions) => sonnerToast.error(message, options),
+  warning: (message: ReactNode, options?: ToastOptions) => sonnerToast.warning(message, options),
+  info: (message: ReactNode, options?: ToastOptions) => sonnerToast.info(message, options),
+  /**
+   * Тост, следящий за промисом: ожидание → успех или ошибка.
+   *
+   * Сигнатура СВОЯ, а не проброшенная у sonner, и это вынужденно: его тип
+   * ссылается на внутренний, неэкспортированный (`PromiseIExtendedResult`), и
+   * компилятор отказывается порождать `.d.ts` пакета — «cannot be named».
+   * Пакет всё равно обязан объявлять свой контракт, так что здесь он написан
+   * явно и заодно сужен до того, что действительно нужно.
+   *
+   * Подписи задаёт вызывающий: только он знает, что именно сохраняется.
+   */
+  // Запятая в `<T,>` обязательна: в `.tsx` дженерик-стрелка иначе неотличима
+  // от JSX-тега, и парсер спотыкается.
+  promise: <T,>(
+    promise: Promise<T>,
+    messages: {
+      loading: ReactNode;
+      success: ReactNode | ((data: T) => ReactNode);
+      error: ReactNode | ((error: unknown) => ReactNode);
+    }
+  ): void => {
+    sonnerToast.promise(promise, messages);
+  },
+  dismiss: (id?: string | number) => sonnerToast.dismiss(id),
+};