@olddevs/ui 0.0.0-stage → 4.0.0

package/src/components/content/NotificationList.tsx

@@ -0,0 +1,329 @@
+"use client";
+
+import { forwardRef, useId, type ComponentPropsWithoutRef, type ReactNode } from "react";
+import { useMessages } from "../../i18n/useMessages.js";
+import { cn } from "../../lib/cn.js";
+import { devWarn } from "../../lib/dev-warn.js";
+import { hasContent } from "../../lib/empty.js";
+import { TONE_TOKENS, type Tone } from "../../lib/variants.js";
+
+interface NotificationItemBaseProps extends Omit<ComponentPropsWithoutRef<"li">, "title"> {
+  /** О чём событие. Первая строка. */
+  title: ReactNode;
+  /** Подробности. Вторая строка. */
+  description?: ReactNode;
+  /**
+   * Когда — уже отформатированное.
+   *
+   * «5 минут назад» и «вчера в 14:03» кит не считает: относительное время
+   * зависит от локали и часового пояса потребителя, а не от дизайн-системы.
+   */
+  time?: ReactNode;
+  /** Иконка слева. Тип события — знание приложения, поэтому иконка приходит. */
+  icon?: ReactNode;
+  /**
+   * Превью объекта, о котором событие, — второй визуальный слот рядом с
+   * текстом.
+   *
+   * Независим от `icon`: иконка говорит, ЧТО случилось, превью — С ЧЕМ. Размер
+   * задаёт потребитель самим элементом (картинка 36px, `Avatar`); слот лишь не
+   * даёт ему сжаться и ставит по верхнему краю. Декоративное превью — с
+   * `alt=""`: заголовок уже называет объект.
+   */
+  media?: ReactNode;
+  /** Тон иконки и точки непрочитанного. */
+  tone?: Tone;
+  /**
+   * Непрочитанное.
+   *
+   * Отличается НЕ ТОЛЬКО ЦВЕТОМ: рядом с заголовком встаёт слово для
+   * скринридера. Точка и подложка — сигнал для глаз, и человек, который их не
+   * видит, иначе не отличит новое событие от старого вовсе.
+   */
+  unread?: boolean;
+}
+
+/**
+ * Действие строки: либо `actions` справа, либо `onAction` на всю строку.
+ *
+ * Вместе нельзя, и это сказано типом: кнопки внутри кнопки — недопустимая
+ * разметка, на которой потребитель уже забраковал свою строку очереди.
+ */
+export type NotificationItemProps = NotificationItemBaseProps &
+  (
+    | {
+        /** Действия справа — «отметить прочитанным», «перейти». */
+        actions?: ReactNode;
+        onAction?: never;
+      }
+    | {
+        actions?: never;
+        /**
+         * Вся строка — одна кнопка: щелчок, Enter и Space вызывают обработчик.
+         *
+         * Доступное имя кнопки — заголовок (и слово «Не прочитано»), а время и
+         * подробности — её описание: полным содержимым имя получилось бы на
+         * полстраницы. Строка остаётся `<li>`, кнопка лежит внутри неё.
+         */
+        onAction: () => void;
+      }
+  );
+
+/**
+ * Строка события: что произошло, когда и прочитано ли.
+ *
+ * ТИПОВ СОБЫТИЙ КИТ НЕ ЗНАЕТ. «Публикация не прошла», «канал отключён»,
+ * «модерация завершена» — словарь приложения; сюда приходят иконка, тон и
+ * текст. Тот же раздел обязанностей, что у `StatusBadge`, который приехал из
+ * фронта, оставив снаружи одиннадцать доменных статусов
+ * (ADR-0027).
+ *
+ * Строка не навигирует и не отмечает себя прочитанной: и переход, и отметка —
+ * действия потребителя. Они приходят в `actions`, в `onAction` (вся строка —
+ * кнопка) или оборачивают строку.
+ */
+export const NotificationItem = forwardRef<HTMLLIElement, NotificationItemProps>(
+  function NotificationItem(
+    {
+      title,
+      description,
+      time,
+      icon,
+      media,
+      tone = "accent",
+      unread,
+      actions,
+      onAction,
+      className,
+      ...rest
+    },
+    ref
+  ) {
+    const messages = useMessages();
+    const baseId = useId();
+    const t = TONE_TOKENS[tone];
+
+    // Оба пропа пришли только у потребителя на JS: типы это запрещают. `actions`
+    // побеждает — вложенная кнопка в кнопке недопустима, а `actions` может быть
+    // единственным путём к действию (удалить, открыть), и прятать его из-за
+    // лишнего `onAction` хуже, чем потерять щелчок по всей строке. Сбой виден
+    // сразу — строка не реагирует на щелчок, — а в разработке о нём ещё и
+    // говорит консоль: у потребителя на JS это единственное, что заменяет ошибку
+    // типов.
+    if (onAction != null && actions != null) {
+      devWarn(
+        "NotificationItem: both `onAction` and `actions` were passed, but they are mutually " +
+          "exclusive (a button cannot contain buttons). `actions` wins and `onAction` is ignored, " +
+          "so clicking the row does nothing. Pass only one: `onAction` for a clickable row, or " +
+          "`actions` for buttons on the right."
+      );
+    }
+    const asButton = onAction != null && actions == null;
+
+    // `id` нужны только кнопке (имя и описание). Обычной строке они не ставятся:
+    // без `onAction` разметка не должна меняться ни на атрибут.
+    const idOf = (part: string) => (asButton ? `${baseId}-${part}` : undefined);
+    const titleId = idOf("title");
+    const unreadId = idOf("unread");
+    const descriptionId = idOf("description");
+    const timeId = idOf("time");
+
+    // Внутри кнопки допустим только фразовый контент, поэтому блоки строки в
+    // режиме кнопки — `span` (у `span` блочность дают классы). Без `onAction`
+    // остаются `div`, как были.
+    const Block = asButton ? "span" : "div";
+
+    const layout = "flex items-start gap-3 px-3 py-2.5";
+
+    const content = (
+      <>
+        {icon != null && (
+          <span className={cn("flex shrink-0 items-center pt-0.5", t.fg)}>{icon}</span>
+        )}
+
+        {hasContent(media) && <span className="flex shrink-0 items-start">{media}</span>}
+
+        <Block className="min-w-0 flex-1">
+          <Block className="flex items-baseline gap-2">
+            <span id={titleId} className="min-w-0 text-[13px] font-medium">
+              {title}
+            </span>
+            {unread && (
+              <>
+                <span
+                  aria-hidden="true"
+                  className={cn("size-1.5 shrink-0 rounded-full", t.dotBg)}
+                />
+                <span id={unreadId} className="sr-only">
+                  {messages.notifications.unread}
+                </span>
+              </>
+            )}
+            {time != null && (
+              <span id={timeId} className="text-fg-2 ml-auto shrink-0 text-[11px]">
+                {time}
+              </span>
+            )}
+          </Block>
+          {description != null && (
+            <Block
+              id={descriptionId}
+              className={cn("text-fg-2 mt-0.5 text-xs leading-relaxed", asButton && "block")}
+            >
+              {description}
+            </Block>
+          )}
+        </Block>
+      </>
+    );
+
+    if (asButton) {
+      // `hasContent`, а не `!= null`: `""` и `false` из `{note && ...}` рисуют
+      // пустой узел, и ссылка на него объявлялась бы пустым описанием.
+      const describedBy = [hasContent(description) && descriptionId, hasContent(time) && timeId]
+        .filter(Boolean)
+        .join(" ");
+
+      return (
+        <li
+          ref={ref}
+          // Подложка непрочитанного — на `li`, а наведение и кольцо фокуса — на
+          // кнопке: так они занимают всю строку, а не её внутренность.
+          // Отступы и раскладка тоже на кнопке, поэтому `className` потребителя
+          // (подложка, граница) их не меняет — это сказано в справочнике.
+          className={cn(unread && "bg-accent-soft", className)}
+          {...rest}
+        >
+          <button
+            type="button"
+            onClick={() => onAction()}
+            // Имя из заголовка и слова «Не прочитано», а не `aria-label`: тот
+            // продублировал бы текст в разметке и разошёлся бы с ним при правке.
+            aria-labelledby={unread ? `${titleId} ${unreadId}` : titleId}
+            aria-describedby={describedBy || undefined}
+            className={cn(
+              layout,
+              "focus-visible:outline-accent-strong w-full cursor-pointer text-left transition-colors",
+              // Наведение у непрочитанного — затемнение поверх подложки, а не
+              // нейтральная заливка: иначе строка на время наведения выглядела
+              // бы прочитанной.
+              unread ? "hover:bg-accent/10" : "hover:bg-bg-2",
+              // Кольцо внутрь строки: снаружи его срежет прокрутка центра.
+              "focus-visible:outline-2 focus-visible:-outline-offset-2"
+            )}
+          >
+            {content}
+          </button>
+        </li>
+      );
+    }
+
+    return (
+      <li
+        ref={ref}
+        className={cn(
+          layout,
+          // Подложка у непрочитанного — сигнал для глаз, и он не единственный:
+          // слово рядом с заголовком говорит то же самое скринридеру.
+          unread && "bg-accent-soft",
+          className
+        )}
+        {...rest}
+      >
+        {content}
+
+        {actions != null && <div className="flex shrink-0 items-center gap-1">{actions}</div>}
+      </li>
+    );
+  }
+);
+
+export interface NotificationGroup {
+  /** Идентификатор группы. */
+  id: string;
+  /** Подпись группы: «Сегодня», «Вчера», «Раньше». */
+  label: ReactNode;
+  /** Строки группы — обычно `NotificationItem`. */
+  children: ReactNode;
+}
+
+export interface NotificationListProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+  /**
+   * Группы событий — уже собранные потребителем.
+   *
+   * Что такое «вчера», знает локаль и часовой пояс потребителя, а не кит: у
+   * приложения с ночными сменами граница суток своя, и считать её здесь значило
+   * бы навязать чужой календарь.
+   */
+  groups?: NotificationGroup[];
+  /** Строки без группировки. Используется вместо `groups`, а не вместе с ними. */
+  children?: ReactNode;
+  /** Что показать при пустом списке — обычно `EmptyState`. */
+  empty?: ReactNode;
+  /** Доступное имя списка для скринридера. По умолчанию — стандартная подпись пакета. */
+  "aria-label"?: string;
+}
+
+/**
+ * Список событий с группировкой по времени и пустым состоянием.
+ *
+ * ГРУППА — НАСТОЯЩАЯ ГРУППА (`role="group"` с подписью), а не заголовок над
+ * набором строк. Заголовок уровня `h3` здесь поставить нельзя: уровень зависит
+ * от того, куда список встал — в попап, в ящик или на страницу, — и кит этого
+ * не знает. Группа с именем сообщает структуру, не занимая уровня.
+ *
+ * ПУСТОЕ СОСТОЯНИЕ — существующий `EmptyState`, приходящий пропом: у пустоты
+ * «нет уведомлений» и пустоты «ничего не нашлось по фильтру» разный текст и
+ * разные действия, и выбирает их потребитель.
+ */
+export const NotificationList = forwardRef<HTMLDivElement, NotificationListProps>(
+  function NotificationList(
+    { groups, children, empty, className, "aria-label": ariaLabel, ...rest },
+    ref
+  ) {
+    const messages = useMessages();
+    const baseId = useId();
+    const label = ariaLabel ?? messages.notifications.label;
+
+    // `hasContent`, а не `== null`: основной способ вызова — `{items.map(...)}`,
+    // и при пустом `items` сюда приходит ПУСТОЙ МАССИВ. Он не `null`, поэтому
+    // список считался непустым и рисовался пустой `<ul>` вместо слота `empty`.
+    const isEmpty = groups != null ? groups.length === 0 : !hasContent(children);
+    if (isEmpty) return <>{empty}</>;
+
+    return (
+      // Имя стоит на внешнем узле, а не на внутреннем списке: с группами
+      // списков несколько, и назвать надо всё вместе. Роль обязательна — у
+      // голого `div` с `aria-label` имени нет, атрибут просто игнорируется.
+      <div
+        ref={ref}
+        role="group"
+        aria-label={label}
+        className={cn("flex flex-col", className)}
+        {...rest}
+      >
+        {groups != null ? (
+          groups.map((group, index) => {
+            const labelId = `${baseId}-${group.id}`;
+            return (
+              <div key={group.id} role="group" aria-labelledby={labelId}>
+                <div
+                  id={labelId}
+                  className={cn(
+                    "text-fg-2 px-3 pb-1 text-[11px] font-bold tracking-wide uppercase",
+                    index === 0 ? "pt-2" : "pt-4"
+                  )}
+                >
+                  {group.label}
+                </div>
+                <ul className="flex flex-col">{group.children}</ul>
+              </div>
+            );
+          })
+        ) : (
+          <ul className="flex flex-col">{children}</ul>
+        )}
+      </div>
+    );
+  }
+);

package/src/components/content/ScrollArea.tsx

@@ -0,0 +1,69 @@
+"use client";
+
+import type { ComponentPropsWithoutRef } from "react";
+import { cn } from "../../lib/cn.js";
+
+export interface ScrollAreaProps extends ComponentPropsWithoutRef<"div"> {
+  /** Направление прокрутки: `vertical` или `horizontal`. По умолчанию `vertical`. */
+  orientation?: "vertical" | "horizontal";
+  /**
+   * Доступное имя области.
+   *
+   * Задавать его стоит там, где прокручиваемый кусок — самостоятельная часть
+   * экрана: список пунктов, панель фильтров. Без имени область остаётся просто
+   * прокручиваемым блоком — это законно и не хуже: `role="region"` без имени
+   * скринридер называет только по роли: «регион».
+   */
+  label?: string;
+}
+
+/**
+ * Прокручиваемая область со стилизованной полосой.
+ *
+ * Своя, а не зависимость. `@radix-ui/react-scroll-area` подменяет родную
+ * прокрутку своей: рисует полосу дивами и считает положение в JS. Это даёт
+ * одинаковый вид во всех браузерах — и отнимает инерцию прокрутки на
+ * тачпадах, `scroll-behavior`, поиск по странице, прокрутку колесом с
+ * зажатым Shift. Кит арендует поведение там, где своё было бы второй
+ * библиотекой (см. ADR-0005), а здесь родное поведение уже есть и лучше.
+ *
+ * Полоса красится псевдоэлементами WebKit и `scrollbar-*` в Firefox. В
+ * браузерах, где не работает ни то, ни другое, останется системная полоса —
+ * это вид, а не поломка.
+ */
+export function ScrollArea({
+  orientation = "vertical",
+  label,
+  className,
+  children,
+  ...rest
+}: ScrollAreaProps) {
+  return (
+    <div
+      /*
+        `tabIndex={0}` обязателен, и это не вкусовщина: прокручиваемый блок,
+        до которого нельзя добраться с клавиатуры, — нарушение, которое ловит
+        axe правилом `scrollable-region-focusable`. Без фокуса содержимое
+        области недоступно тому, кто не пользуется мышью.
+      */
+      tabIndex={0}
+      role={label ? "region" : undefined}
+      aria-label={label}
+      className={cn(
+        "focus-visible:outline-accent-strong focus-visible:outline-2 focus-visible:outline-offset-2",
+        orientation === "vertical" ? "overflow-y-auto" : "overflow-x-auto",
+        // Firefox: два свойства и всё.
+        "[scrollbar-width:thin] [scrollbar-color:var(--border-default)_transparent]",
+        // WebKit: полоса, дорожка, бегунок.
+        "[&::-webkit-scrollbar]:h-2 [&::-webkit-scrollbar]:w-2",
+        "[&::-webkit-scrollbar-track]:bg-transparent",
+        "[&::-webkit-scrollbar-thumb]:bg-line [&::-webkit-scrollbar-thumb]:rounded-full",
+        "[&::-webkit-scrollbar-thumb:hover]:bg-fg-4",
+        className
+      )}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+}

package/src/components/content/Separator.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import {
+  Separator as RACSeparator,
+  SeparatorContext,
+  useSlottedContext,
+  type SeparatorProps as RACSeparatorProps,
+} from "react-aria-components";
+import { cn } from "../../lib/cn.js";
+
+export interface SeparatorProps extends Omit<RACSeparatorProps, "elementType"> {
+  /** Отступы вокруг черты. `none` — когда расстояние задаёт раскладка снаружи. */
+  spacing?: "none" | "sm" | "md";
+}
+
+const SPACING_CLASS = {
+  horizontal: { none: "", sm: "my-2", md: "my-4" },
+  vertical: { none: "", sm: "mx-2", md: "mx-4" },
+} as const;
+
+/**
+ * Разделительная черта.
+ *
+ * Взят у react-aria, а не нарисован `<div className="border-t">`, ровно из-за
+ * одной вещи: роль. Черта, разделяющая **группы** (пункты меню, блоки панели),
+ * обязана быть `role="separator"` — скринридер объявляет ею границу группы.
+ * Черта, которая просто украшает, обязана быть скрыта от него совсем.
+ *
+ * Различать эти два случая — работа вызывающего, и react-aria ставит роль сам,
+ * а вертикальной черте добавляет `aria-orientation`. Рукописная версия почти
+ * всегда останавливается на `border-t` и не сообщает ни того, ни другого.
+ */
+export function Separator({
+  orientation: orientationProp,
+  spacing = "none",
+  className,
+  ...rest
+}: SeparatorProps) {
+  /*
+    Ось берётся из контекста react-aria, когда пропа нет: `Toolbar` кладёт туда
+    направление поперёк своей оси, и черта между группами действий ложится
+    нужным боком без подсказки. Явный проп всегда сильнее контекста; вне панели
+    контекст пуст, и черта горизонтальна, как раньше.
+  */
+  // Хук — безусловно: за `??` он вызывался бы не на каждом рендере.
+  const fromContext = useSlottedContext(SeparatorContext)?.orientation;
+  const orientation = orientationProp ?? fromContext ?? "horizontal";
+  return (
+    <RACSeparator
+      orientation={orientation}
+      className={cn(
+        "bg-line-soft border-0",
+        // Толщина в один пиксель задаётся размером, а не рамкой: рамка на
+        // элементе без содержимого даёт разную высоту в разных браузерах.
+        orientation === "vertical" ? "h-full w-px self-stretch" : "h-px w-full",
+        SPACING_CLASS[orientation][spacing],
+        className
+      )}
+      {...rest}
+    />
+  );
+}

package/src/components/content/Skeleton.tsx

@@ -0,0 +1,40 @@
+"use client";
+
+import { forwardRef, type ComponentPropsWithoutRef } from "react";
+import { cn } from "../../lib/cn.js";
+
+export interface SkeletonProps extends ComponentPropsWithoutRef<"div"> {
+  /** Ширина. Число трактуется как пиксели, строка — как CSS-значение. */
+  width?: number | string;
+  /** Высота. Число — пиксели, строка — любое CSS-значение. */
+  height?: number | string;
+  /** Скругление. По умолчанию `--r-md`. */
+  borderRadius?: number | string;
+}
+
+/**
+ * Плейсхолдер загрузки: прямоугольник с бегущим бликом.
+ *
+ * Единственный примитив пакета, который принимает размеры числами и кладёт их
+ * в инлайн-`style`, — и это не недосмотр. Скелетон повторяет форму того, что
+ * подменяет: 43 вызова во фронте задают 12 разных сочетаний ширины, высоты
+ * и скругления (`4`, `10`, `3`, `6`, `8`, `0`, `"50%"`, `9999`). Шкала из трёх
+ * ступеней здесь не описывает предметную область, а мешает: под каждый новый
+ * блок пришлось бы заводить ступень.
+ *
+ * Сам блик — правило `.skeleton` в `styles.css` (градиент + `shimmer`), а не
+ * утилиты: анимация с `background-position` в утилитах не выражается.
+ */
+export const Skeleton = forwardRef<HTMLDivElement, SkeletonProps>(function Skeleton(
+  { width, height, borderRadius, className, style, ...rest },
+  ref
+) {
+  return (
+    <div
+      ref={ref}
+      className={cn("skeleton", className)}
+      style={{ width, height, borderRadius: borderRadius ?? "var(--r-md)", ...style }}
+      {...rest}
+    />
+  );
+});