@olddevs/ui 0.0.0-stage → 4.0.1

package/src/components/content/TagGroup.tsx

@@ -0,0 +1,222 @@
+"use client";
+
+import { forwardRef, type ReactNode } from "react";
+import {
+  Button as AriaButton,
+  Label,
+  Tag as AriaTag,
+  TagGroup as AriaTagGroup,
+  TagList,
+} from "react-aria-components";
+import { CloseIcon } from "../../icons.js";
+import type { AccessibleName } from "../../lib/accessible-name.js";
+import { cn } from "../../lib/cn.js";
+import { hasContent } from "../../lib/empty.js";
+import { TAG_CLASS, TAG_REMOVE_CLASS } from "../../lib/tag.js";
+import { LABEL_BG_CLASS, type LabelHue } from "../../lib/variants.js";
+import { useMessages } from "../../i18n/useMessages.js";
+
+/** Ключ метки: тот же `id`, что задан у `Tag`. */
+export type TagKey = string | number;
+
+interface TagGroupBaseProps {
+  /**
+   * Удаление меток. Задан — у каждой метки появляется кнопка удаления, а
+   * Delete и Backspace на метке вызывают его с ключом этой метки.
+   *
+   * Сам набор компонент не меняет: метку убирает потребитель, перерисовав
+   * группу. Не задан — меток не убрать ни мышью, ни клавиатурой.
+   */
+  onRemove?: (keys: Set<TagKey>) => void;
+  /**
+   * Что показать, когда меток нет.
+   *
+   * Пустая группа без текста выглядит сбоем — пропавшим содержимым, а не
+   * отсутствием категорий.
+   */
+  empty?: ReactNode;
+  /** Метки — `Tag`. Не заданы — группа пуста и показывает `empty`. */
+  children?: ReactNode;
+  /** Классы корневого элемента. */
+  className?: string;
+}
+
+/**
+ * Видимая подпись, которая годится в имя: `ReactNode` без пустых значений.
+ *
+ * Голый `ReactNode` пропускал `undefined`, `null` и `false` — ветка «есть
+ * подпись» совпадала с группой вовсе без имени, и обязательность становилась
+ * видимостью. Пустую строку тип отсечь не может (`""` — тоже `string`); её
+ * ловит `hasContent` в разметке.
+ */
+type TagGroupLabel = Exclude<ReactNode, null | undefined | boolean>;
+
+/**
+ * Имя группы обязательно: либо видимая подпись `label`, либо ровно одно из
+ * `aria-label` и `aria-labelledby` (`AccessibleName`) — но не подпись вместе с
+ * атрибутом.
+ *
+ * Группа меток — это `grid`, а у `grid` без имени скринридер называет только
+ * роль, и три группы подряд на странице («Категории», «Авторы», «Ярлыки»)
+ * неразличимы. Тот же довод, что у `Toolbar` и `Carousel`. Подпись вместе с
+ * `aria-label` — два источника одного имени: атрибут перекрыл бы видимый
+ * текст, и на слух группа называлась бы не так, как на экране.
+ */
+export type TagGroupProps = TagGroupBaseProps &
+  (
+    | {
+        /** Видимая подпись группы; она же служит её доступным именем. */
+        label: TagGroupLabel;
+        /** Доступное имя строкой, когда видимой подписи нет. Не задаётся вместе с `aria-labelledby`: два источника одного имени. */
+        "aria-label"?: never;
+        /** `id` элемента, чей текст служит доступным именем, когда видимой подписи нет. Не задаётся вместе с `aria-label`: два источника одного имени. */
+        "aria-labelledby"?: never;
+      }
+    | ({ label?: never } & AccessibleName)
+  );
+
+/**
+ * Набор меток для ПОКАЗА: оттенок палитры, ссылка, необязательное удаление.
+ *
+ * Построен на `TagGroup` из react-aria, и всё поведение — от неё: стрелки между
+ * метками, Delete и Backspace, фокус после удаления на соседней метке. Tab
+ * с метки уходит на её кнопку удаления — так устроена и `TagInput`.
+ *
+ * ЭТО НЕ ФИЛЬТР, НЕ СТАТУС И НЕ ВВОД. Выбор из набора — `Chip` и `Segmented`,
+ * поэтому `selectionMode` наружу НЕ пробрасывается: метка, которую можно
+ * выделить, становится вторым переключателем с другой клавиатурой. Состояние
+ * объекта — `StatusBadge`. Ввод новых меток — `TagInput`.
+ *
+ * Набор переносится на новую строку целиком, по метке, а не по слову.
+ */
+export const TagGroup = forwardRef<HTMLDivElement, TagGroupProps>(function TagGroup(
+  { label, onRemove, empty, children, className, ...rest },
+  ref
+) {
+  return (
+    <AriaTagGroup
+      {...rest}
+      ref={ref}
+      onRemove={onRemove}
+      className={cn("flex flex-col gap-1.5", className)}
+    >
+      {hasContent(label) ? <Label className="text-fg-2 text-caption">{label}</Label> : null}
+      <TagList
+        className="flex flex-wrap gap-1.5"
+        renderEmptyState={
+          // `hasContent`, а не `!= null`: пустая строка дала бы пустой `span`
+          // вместо «нет меток» — то есть ту же пустую группу, от которой проп и есть.
+          hasContent(empty) ? () => <span className="text-fg-3 text-sm">{empty}</span> : undefined
+        }
+      >
+        {children}
+      </TagList>
+    </AriaTagGroup>
+  );
+});
+
+interface TagBaseProps {
+  /**
+   * Ключ метки: его получает `onRemove`. Без `id` ключом станет React-ключ
+   * элемента, так что для удаляемых наборов задавайте оба.
+   */
+  id?: TagKey;
+  /**
+   * Оттенок из палитры меток (`LABEL_HUES`) — точка рядом с подписью, а не
+   * заливка под текстом.
+   *
+   * Это решение палитры, а не вкус: восемь оттенков, читаемых под текстом во
+   * всех трёх темах, стоили бы вдвое большего набора. Точка скринридеру
+   * невидима (`aria-hidden`): оттенок слова не заменяет, и смысл метки несёт
+   * подпись — иначе метки не различил бы человек с нарушением цветового зрения.
+   */
+  hue?: LabelHue;
+  /**
+   * Адрес — метка становится ссылкой: Enter и щелчок переходят по нему.
+   *
+   * react-aria не рисует `<a>`, а открывает ссылку при нажатии (атрибуты лежат
+   * в `data-href`): так метка остаётся строкой группы и сохраняет стрелки и
+   * удаление. Цена — нет контекстного меню «открыть в новой вкладке»; для
+   * клиентской маршрутизации ставится `RouterProvider` react-aria.
+   */
+  href?: string;
+  /** Где открыть ссылку (`_blank` и т. п.); действует вместе с `href`. */
+  target?: string;
+  /** Атрибут `rel` ссылки; действует вместе с `href`. */
+  rel?: string;
+}
+
+/**
+ * Метка с текстом: имя берётся из содержимого. Метка с узлом внутри обязана
+ * сообщить имя сама — иначе его нечем назвать ни кнопке удаления, ни скринридеру.
+ */
+export type TagProps = TagBaseProps &
+  (
+    | {
+        /** Содержимое метки: подпись текстом или узлом. */
+        children: string | number;
+        /** Текстовое имя метки для кнопки удаления и скринридера; по умолчанию — `children`, обязательно, когда `children` не строка. */
+        textValue?: string;
+      }
+    | {
+        /** Содержимое метки: подпись текстом или узлом. */
+        children: ReactNode;
+        /** Текстовое имя метки для кнопки удаления и скринридера; по умолчанию — `children`, обязательно, когда `children` не строка. */
+        textValue: string;
+      }
+  );
+
+/** Метка внутри `TagGroup`. */
+export function Tag({ id, hue, href, target, rel, children, textValue }: TagProps) {
+  const messages = useMessages();
+  // `||`, а не `??`: пустой `textValue` оставил бы кнопку удаления с именем
+  // «Удалить: » — без того, что она удаляет.
+  const name =
+    textValue ||
+    (typeof children === "string" || typeof children === "number" ? String(children) : "");
+
+  return (
+    <AriaTag
+      id={id}
+      textValue={name}
+      // Пустой адрес — не ссылка: метка с `href=""` вела бы на текущую страницу.
+      href={href || undefined}
+      target={target}
+      rel={rel}
+      className={cn(TAG_CLASS, href && "cursor-pointer hover:underline")}
+    >
+      {({ allowsRemoving }) => (
+        <>
+          {hue ? (
+            <span
+              aria-hidden="true"
+              className={cn("size-2.5 shrink-0 rounded-full", LABEL_BG_CLASS[hue])}
+            />
+          ) : null}
+          {children}
+          {allowsRemoving ? (
+            /*
+              Кнопка — `Button` из react-aria, а не `<button>`: поведение
+              удаления приходит через её контекст (см. `TagInput`).
+
+              Имя целиком из каталога, а react-aria по умолчанию ДОПИСЫВАЕТ
+              подпись метки к имени кнопки через `aria-labelledby`. Пустая
+              строка перекрывает его: `undefined` не годится — слияние пропсов
+              пропускает его и оставляет значение react-aria, а пустой
+              `aria-labelledby` по спецификации игнорируется, и имя берётся из
+              `aria-label`.
+            */
+            <AriaButton
+              slot="remove"
+              aria-label={messages.tagGroup.remove({ label: name })}
+              aria-labelledby=""
+              className={TAG_REMOVE_CLASS}
+            >
+              <CloseIcon size={12} />
+            </AriaButton>
+          ) : null}
+        </>
+      )}
+    </AriaTag>
+  );
+}

package/src/components/content/Text.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+import type { ComponentPropsWithRef, CSSProperties } from "react";
+import { cn } from "../../lib/cn.js";
+import { NUMERIC_CLASS, TONE_TOKENS, type Numeric, type Tone } from "../../lib/variants.js";
+
+/** Ступени шкалы, доступные тексту. Заголовочные (`xl`, `2xl`) — у `Heading`. */
+export type TextSize = "caption" | "xs" | "sm" | "md" | "lg";
+
+export interface TextProps extends Omit<ComponentPropsWithRef<"p">, "color"> {
+  /** Ступень размера текста: `caption`, `xs`, `sm`, `md` или `lg`. По умолчанию `md`. */
+  size?: TextSize;
+  /**
+   * Приглушённость: `1` — основной текст, `2` — вторичный, `3` — служебный.
+   *
+   * Это НЕ уровень заголовка, хотя проп `Heading` называется так же. Разводить
+   * их именами было бы честнее, но у `Heading` `level` — понятие HTML, а не
+   * выдумка кита, и переименовывать надо было бы именно его. Здесь же за
+   * «уровнем» стоит ровно то же слово в бытовом смысле: насколько текст важен.
+   *
+   * Спутать их на практике нечем: у `Text` нет ни `h1`, ни роли заголовка, а у
+   * `Heading` нет приглушённости — заголовок бледнее основного текста не бывает.
+   */
+  level?: 1 | 2 | 3;
+  /**
+   * Семантический цвет. `neutral` (по умолчанию) означает «цвет по
+   * приглушённости»: тон и `level` — разные оси, и смешивать их нельзя.
+   */
+  tone?: Tone;
+  /** Начертание: `regular`, `medium` или `bold`. По умолчанию `regular`. */
+  weight?: "regular" | "medium" | "bold";
+  /**
+   * Начертание цифр: `tabular` — равной ширины, для того, что тикает,
+   * пересчитывается или стоит колонкой.
+   *
+   * Умолчания нет намеренно: цифры равной ширины шире пропорциональных, и в
+   * обычном тексте они читаются хуже. Ось включается там, где числа меняются
+   * на месте, а не везде.
+   */
+  numeric?: Numeric;
+  /**
+   * Обрезка многоточием. `true` — одна строка, число — столько строк.
+   */
+  truncate?: boolean | number;
+  /** Тег текста: `p`, `span` или `div`. По умолчанию `p`. */
+  as?: "p" | "span" | "div";
+}
+
+const SIZE_CLASS: Record<TextSize, string> = {
+  caption: "text-caption",
+  xs: "text-xs",
+  sm: "text-sm",
+  md: "text-md",
+  lg: "text-lg",
+};
+
+/**
+ * Приглушённость. Ступени взяты те же, что во всём ките: `fg-0` — основной,
+ * `fg-1` — вторичный, `fg-2` — служебный. Ниже (`fg-3`, `fg-4`) шкала не идёт:
+ * те два уровня не проходят контраст 4.5 на подложках приложения и оставлены
+ * для нетекстовых ролей — иконок и разделителей.
+ */
+const LEVEL_CLASS: Record<1 | 2 | 3, string> = {
+  1: "text-fg-0",
+  2: "text-fg-1",
+  3: "text-fg-2",
+};
+
+const WEIGHT_CLASS = {
+  regular: "font-normal",
+  medium: "font-medium",
+  bold: "font-semibold",
+} as const;
+
+/**
+ * Абзац или строка текста на ступени шкалы.
+ *
+ * Компонент существует не ради `<p className="text-sm">`, а ради того, чтобы
+ * размер и приглушённость брались из двух конечных наборов. До шкалы кит
+ * пользовался восемью размерами, три из которых произвольные, и разница между
+ * «служебной подписью» и «вторичным текстом» жила в голове автора экрана.
+ *
+ * Тега по умолчанию два не бывает: `as` меняет только тег и ничего в виде —
+ * `<span>` внутри строки и `<p>` в абзаце обязаны выглядеть одинаково.
+ */
+export function Text({
+  size = "md",
+  level = 1,
+  tone = "neutral",
+  weight = "regular",
+  numeric,
+  truncate,
+  as: Comp = "p",
+  className,
+  style,
+  ...rest
+}: TextProps) {
+  // Ноль строк — это не «без предела», а спрятанный текст: `-webkit-line-clamp: 0`
+  // на коробке с `overflow: hidden` не показывает ничего. Считаем это опечаткой
+  // вызывающего и обрезаем как одну строку.
+  const lines = typeof truncate === "number" && truncate > 0 ? truncate : undefined;
+  const oneLine = truncate === true || truncate === 0;
+
+  return (
+    <Comp
+      className={cn(
+        SIZE_CLASS[size],
+        // Тон перекрывает приглушённость: у окрашенного текста «вторичность»
+        // выражается самим тоном, а не второй краской поверх. Гасить тон
+        // прозрачностью нельзя — тона откалиброваны ровно под 4.5.
+        tone === "neutral" ? LEVEL_CLASS[level] : TONE_TOKENS[tone].fg,
+        WEIGHT_CLASS[weight],
+        numeric && NUMERIC_CLASS[numeric],
+        oneLine && "truncate",
+        // Многострочная обрезка — классы коробки литеральные, а число строк
+        // уходит в inline-стиль. Собрать `line-clamp-${lines}` нельзя: Tailwind
+        // сканирует исходники как текст, и класс, склеенный в рантайме, молча
+        // не попадёт в CSS. Литеральный словарь на 2–6 строк закрыл бы обычные
+        // случаи и врал бы на седьмой.
+        lines != null && "[display:-webkit-box] overflow-hidden [-webkit-box-orient:vertical]",
+        className
+      )}
+      style={lines != null ? ({ WebkitLineClamp: lines, ...style } as CSSProperties) : style}
+      {...rest}
+    />
+  );
+}

package/src/components/content/Timeline.tsx

@@ -0,0 +1,126 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { cn } from "../../lib/cn.js";
+import { PROGRESS_STATUS_TONE, type ProgressStatus } from "../../lib/progress-status.js";
+import { TONE_TOKENS } from "../../lib/variants.js";
+
+export interface TimelineItem {
+  /** Идентификатор шага. */
+  id: string;
+  /** Что произошло. Обычно короткое имя шага. */
+  label: ReactNode;
+  /** Состояние шага. Порядок в ленте задаёт потребитель, а не статус. */
+  status: ProgressStatus;
+  /** Подпись состояния — «выполнен», «ошибка». Рисуется пилюлей справа от имени. */
+  statusLabel?: ReactNode;
+  /** Подробности: сообщение об ошибке, длительность, идентификатор. */
+  details?: ReactNode;
+  /** Время шага — уходит вправо, моноширинным. */
+  time?: ReactNode;
+}
+
+export interface TimelineProps {
+  /** Шаги в порядке показа; пустой список ничего не выводит. */
+  items: TimelineItem[];
+  /** Классы корневого элемента. */
+  className?: string;
+  /** Доступное имя списка шагов для скринридера. */
+  "aria-label"?: string;
+}
+
+/**
+ * Лента шагов процесса: что уже произошло и чем закончилось.
+ *
+ * ГРАНИЦА СО `Stepper`, и её стоит держать в голове:
+ *
+ *   `Stepper`  — мастер: линейный `current`, шаги впереди ещё не случались,
+ *                провалиться шаг не может, назад ведёт клик.
+ *   `Timeline` — наблюдение: у КАЖДОГО шага своё состояние, любой может
+ *                провалиться, кликать не по чему.
+ *
+ * Именно из-за этой разницы конвейер шагов задачи во фронте не переехал на
+ * `Stepper` и жил там рукописным: 122 строки инлайн-стилей с захардкоженными
+ * `rgba`, то есть цветами мимо токенов, которые не менялись ни с темой, ни со
+ * сменой акцента.
+ *
+ * РАЗМЕТКА — упорядоченный список. Шаги идут по порядку, и скринридер обязан
+ * сообщить и порядок, и общее число; набор `div` не сообщает ни того, ни
+ * другого. Идущий шаг помечается `aria-current="step"`.
+ *
+ * ЦВЕТА БЕРУТСЯ ИЗ АТОМОВ ТОНА (`TONE_TOKENS`), а не задаются заново: «ошибка»
+ * означает один и тот же цвет здесь, в `Alert`, в `StatusBadge` и на кнопке
+ * удаления. Свечение у идущего шага снято намеренно — оно было единственным
+ * местом в ленте, где цвет задавался тенью, а не токеном.
+ */
+export function Timeline({ items, className, "aria-label": ariaLabel }: TimelineProps) {
+  if (items.length === 0) return null;
+
+  return (
+    <ol aria-label={ariaLabel} className={cn("flex flex-col", className)}>
+      {items.map((item, index) => {
+        // Незнакомый статус подаётся нейтральным, а не роняет ленту целиком.
+        // Потребитель пакета — приложение на JS, компилятор его данные не
+        // проверяет, а статусы приходят с бэкенда: пятый вид шага не должен
+        // стоить экрана. Прежняя рукописная версия этот случай закрывала, и
+        // терять защиту при переезде нельзя.
+        const tone = TONE_TOKENS[PROGRESS_STATUS_TONE[item.status] ?? "neutral"];
+        const isLast = index === items.length - 1;
+
+        return (
+          <li
+            key={item.id}
+            aria-current={item.status === "running" ? "step" : undefined}
+            className="relative flex items-start gap-2.5"
+          >
+            {/* Колонка маркера: точка и соединительная линия. Линии после
+                последнего шага нет — она обещала бы продолжение. */}
+            <div className="flex w-3.5 shrink-0 flex-col items-center pt-1">
+              <span aria-hidden className={cn("size-2 shrink-0 rounded-full", tone.dotBg)} />
+              {!isLast ? <span aria-hidden className="bg-line-soft mt-[3px] w-px flex-1" /> : null}
+            </div>
+
+            <div className={cn("min-w-0 flex-1", isLast ? "pb-0" : "pb-1.5")}>
+              <div className="flex flex-wrap items-center gap-1.5">
+                <span
+                  className={cn(
+                    "text-caption font-mono tracking-wide",
+                    tone.fg,
+                    item.status === "failed" ? "font-bold" : "font-medium"
+                  )}
+                >
+                  {item.label}
+                </span>
+                {item.statusLabel ? (
+                  <span
+                    className={cn(
+                      "text-caption rounded-xs px-1.5 py-px font-bold uppercase",
+                      tone.bg,
+                      tone.fg
+                    )}
+                  >
+                    {item.statusLabel}
+                  </span>
+                ) : null}
+                {item.time ? (
+                  <span className="text-fg-3 ml-auto font-mono text-[10px]">{item.time}</span>
+                ) : null}
+              </div>
+
+              {item.details ? (
+                <div
+                  className={cn(
+                    "mt-0.5 text-xs leading-relaxed break-words",
+                    item.status === "failed" ? "text-danger-strong" : "text-fg-3"
+                  )}
+                >
+                  {item.details}
+                </div>
+              ) : null}
+            </div>
+          </li>
+        );
+      })}
+    </ol>
+  );
+}