@olddevs/ui 0.0.0-stage → 4.0.0

package/src/components/content/Link.tsx

@@ -0,0 +1,199 @@
+"use client";
+
+import type { ComponentPropsWithRef, ElementType, ReactNode } from "react";
+import { ExternalLinkIcon } from "../../icons.js";
+import { cn } from "../../lib/cn.js";
+import { useMessages } from "../../i18n/useMessages.js";
+import { TONE_TOKENS, type Tone } from "../../lib/variants.js";
+
+export type LinkVariant = "inline" | "standalone" | "quiet";
+
+export interface LinkOwnProps {
+  /** Вид ссылки: `inline` (всегда подчёркнута), `standalone` (подчёркивание при наведении) или `quiet` (цвет текста, акцент при наведении). По умолчанию `inline`. */
+  variant?: LinkVariant;
+  /** Цветовой тон ссылки: `neutral`, `accent`, `success`, `warning` или `danger`. По умолчанию `accent`. */
+  tone?: Tone;
+  /**
+   * Ссылка ведёт наружу: рядом с подписью появляется иконка.
+   *
+   * `target` этим пропом НЕ выставляется. Открывать ли внешнее в новой вкладке —
+   * решение экрана, а не системы: в одном месте это удобно, в другом уносит
+   * пользователя из наполовину заполненной формы.
+   */
+  external?: boolean;
+  /** Содержимое ссылки. */
+  children?: ReactNode;
+  /** Классы корневого элемента. */
+  className?: string;
+}
+
+/**
+ * Пропсы полиморфны по `as`: с `next/link` компилятор примет и `prefetch`, и
+ * объектный `href`, а с обычной `a` — только атрибуты якоря.
+ *
+ * Без этого тип был бы прибит к якорю, и каждый проп маршрутизатора
+ * компилятор отвергал бы у компонента, который ради маршрутизатора и заведён.
+ */
+export type LinkProps<T extends ElementType = "a"> = LinkOwnProps & {
+  /**
+   * Тег или компонент ссылки: `next/link`, `Link` роутера, обычная `a`.
+   *
+   * Пакет намеренно не знает про маршрутизацию: у потребителя она своя, и
+   * зависимость на неё превратила бы дизайн-систему в часть приложения.
+   */
+  as?: T;
+} & Omit<ComponentPropsWithRef<T>, keyof LinkOwnProps | "as">;
+
+/**
+ * Подчёркивание — не украшение, а второй признак ссылки.
+ *
+ * `inline` подчёркнут ВСЕГДА: ссылка внутри абзаца, отличающаяся от текста
+ * только цветом, для дальтоника не отличается ничем. Это прямое требование
+ * WCAG 1.4.1, и оно не смягчается «у нас контрастный акцент».
+ *
+ * `standalone` — ссылка, стоящая отдельной строкой: её и так видно по месту,
+ * подчёркивание появляется при наведении. `quiet` — ссылка цветом текста,
+ * акцент только при наведении: хлебные крошки, служебные ссылки в подвале.
+ */
+const VARIANT_CLASS: Record<LinkVariant, string> = {
+  inline: "underline underline-offset-2",
+  standalone: "no-underline hover:underline hover:underline-offset-2",
+  quiet: "no-underline hover:underline hover:underline-offset-2",
+};
+
+/**
+ * Тон `quiet` при наведении. Отдельная таблица литеральных строк, а не
+ * `hover:` + атом словаря: Tailwind сканирует исходники как текст, и класс,
+ * склеенный в рантайме, молча не попадёт в CSS — ссылка осталась бы серой
+ * навсегда, без единой ошибки сборки.
+ */
+const QUIET_HOVER_CLASS: Record<Tone, string> = {
+  neutral: "hover:text-fg-0",
+  accent: "hover:text-accent-strong",
+  success: "hover:text-success-strong",
+  warning: "hover:text-warning-strong",
+  danger: "hover:text-danger-strong",
+};
+
+/**
+ * Схемы, исполняющие код в origin страницы.
+ *
+ * Пробелы и переводы строк внутри схемы браузер игнорирует
+ * (`java\tscript:`), регистр тоже, поэтому сверяется очищенное начало строки.
+ */
+function isExecutableHref(href: unknown): boolean {
+  /*
+    НЕ СТРОКА — не схема.
+
+    `LinkProps` полиморфны по `as`, и докстрока пропа прямо обещает, что с
+    `next/link` компилятор примет объектный `href` (`{ pathname, query }`).
+    Проверка, добавленная без сужения типа, звала на нём `.replace` и роняла
+    рендер: `TypeError: href.replace is not a function` — причём на том самом
+    способе вызова, ради которого полиморфность и заведена. Исполняемую схему
+    объект выразить не может: у `UrlObject` нет `protocol`, который дошёл бы
+    до `<a>`.
+  */
+  if (typeof href !== "string" || !href) return false;
+  // Управляющие символы здесь НУЖНЫ: браузер их из схемы выбрасывает, поэтому
+  // `java\u0000script:` — рабочая ссылка, и вычищать их обязаны и мы.
+  // eslint-disable-next-line no-control-regex
+  const scheme = href.replace(/[\s\u0000-\u001f]/g, "").toLowerCase();
+  return (
+    /*
+      Из `data:` блокируются только ИСПОЛНЯЕМЫЕ типы.
+
+      Отвергать схему целиком значило молча ломать законную
+      `<Link href={csvDataUrl} download="report.csv">`: подпись оставалась на
+      экране, но не фокусировалась и не нажималась, а отказ ничем не
+      объяснялся. Код исполняют `text/html`, `application/xhtml+xml` и
+      `image/svg+xml`; картинка или CSV кодом не являются, а навигацию верхнего
+      уровня по `data:` браузеры и так блокируют сами.
+    */
+    scheme.startsWith("javascript:") ||
+    scheme.startsWith("vbscript:") ||
+    scheme.startsWith("data:text/html") ||
+    scheme.startsWith("data:application/xhtml+xml") ||
+    scheme.startsWith("data:image/svg+xml")
+  );
+}
+
+/**
+ * Ссылка.
+ *
+ * Тон работает как везде в ките — семантикой, а не оттенком; у `quiet` он
+ * проявляется только при наведении, поэтому в покое такая ссылка окрашена
+ * приглушённым текстом, а не тоном.
+ */
+export function Link<T extends ElementType = "a">({
+  as,
+  variant = "inline",
+  tone = "accent",
+  external,
+  className,
+  children,
+  ...rest
+}: LinkProps<T>) {
+  const messages = useMessages();
+  const Comp = (as ?? "a") as ElementType;
+
+  /*
+    `rel` выводится из `target`, а не из `external`, и это не педантизм.
+    `noopener` защищает от доступа открытой вкладки к `window.opener` — то есть
+    имеет смысл ровно тогда, когда вкладка открывается. Навесить его на обычную
+    внутристраничную ссылку значит поставить оберег от того, чего не бывает,
+    и приучить читающего код не вчитываться в `rel`.
+
+    Обратное тоже верно: `target="_blank"` получает `rel` независимо от того,
+    объявлена ссылка внешней или нет, — дыра открывается тегом, а не пропом.
+  */
+  const props = rest as { target?: string; rel?: string; href?: unknown };
+  const opensNewTab = props.target === "_blank";
+  const rel = opensNewTab ? (props.rel ?? "noopener noreferrer") : props.rel;
+
+  /*
+    ИСПОЛНЯЕМЫЕ СХЕМЫ не доходят до разметки.
+
+    Компонент уже взял на себя безопасность ссылки — выводит `rel` из `target`
+    с обоснованием «дыру открывает тег, а не проп», — а схему не смотрел вовсе:
+    `href` уходил на `<a>` как есть. Поле «сайт» в профиле пользователя,
+    нарисованное как `<Link href={profile.website}>`, со значением
+    `javascript:fetch('/api/keys')…` давало РАБОТАЮЩУЮ ссылку: щелчок исполнял
+    код в origin приложения с сессионной кукой.
+
+    ЧЁРНЫЙ СПИСОК, А НЕ БЕЛЫЙ, и это решение владельца. Белый список молча
+    ломает собственные схемы приложений — `slack://`, `ms-teams://`, внутренние
+    протоколы админок. Отвергается только то, что исполняет код: `javascript:`,
+    `vbscript:` и исполняемые типы `data:` (см. `isExecutableHref`). Остальное —
+    `http`, `https`, `mailto`, `tel`, относительные пути, якоря, картинка или
+    CSV в `data:` — проходит без изменений.
+
+    Ссылка без `href` остаётся в разметке `<a>` без адреса: так потребитель
+    видит, что значение отвергнуто, а не гадает, почему ничего не происходит.
+  */
+  const href = isExecutableHref(props.href) ? undefined : props.href;
+
+  return (
+    <Comp
+      {...rest}
+      href={href}
+      rel={rel}
+      className={cn(
+        // Раскладка НЕ флексовая, и это существенно: `inline-flex` — атомарный
+        // бокс, его текст не разрывается между строками. Ссылка в четыре слова
+        // внутри абзаца уезжала бы целиком на следующую строку или вылезала за
+        // край — то есть вариант `inline` не работал бы ровно там, ради чего
+        // заведён. Иконка ниже поэтому свой отступ несёт сама.
+        "focus-visible:outline-accent-strong transition-colors focus-visible:outline-2 focus-visible:outline-offset-2",
+        variant === "quiet" ? cn("text-fg-2", QUIET_HOVER_CLASS[tone]) : TONE_TOKENS[tone].fg,
+        VARIANT_CLASS[variant],
+        className
+      )}
+    >
+      {children}
+      {external ? (
+        <ExternalLinkIcon size={12} aria-hidden className="ml-1 inline-block align-[-1px]" />
+      ) : null}
+      {opensNewTab ? <span className="sr-only">{messages.link.opensInNewTab}</span> : null}
+    </Comp>
+  );
+}

package/src/components/content/MediaCard.tsx

@@ -0,0 +1,167 @@
+"use client";
+
+import { forwardRef, type ComponentPropsWithoutRef, type ReactNode } from "react";
+import { CheckIcon } from "../../icons.js";
+import { useMessages } from "../../i18n/useMessages.js";
+import { cn } from "../../lib/cn.js";
+import { AspectRatio } from "./AspectRatio.js";
+
+export interface MediaCardProps extends Omit<
+  ComponentPropsWithoutRef<"div">,
+  "title" | "onSelect"
+> {
+  /** Превью — обычно `Image`. Своей загрузки и своего скелетона плитка не пишет. */
+  preview: ReactNode;
+  /** Отношение сторон превью числом: `16 / 9`, `1`, `9 / 16`. */
+  ratio?: number;
+  /** Подпись под превью. */
+  title?: ReactNode;
+  /** Вторая строка: размер, автор, дата — что угодно, уже отформатированное. */
+  subtitle?: ReactNode;
+  /** Бейджи поверх превью — обычно `StatusBadge`. */
+  badges?: ReactNode;
+  /**
+   * Действия поверх превью — обычно `Button iconOnly`.
+   *
+   * Они ВСЕГДА в разметке и всегда достижимы с клавиатуры; прячутся они только
+   * прозрачностью, а показываются при наведении, при фокусе внутри, когда
+   * плитка выбрана и всегда на устройствах без наведения (`hover: none`).
+   * Оверлей, появляющийся по `:hover` через `display: none`,
+   * недостижим для клавиатуры вовсе — а это не «менее удобно», а «нельзя
+   * пользоваться».
+   */
+  actions?: ReactNode;
+  /**
+   * Плитка выбрана.
+   *
+   * Рамка выбора рисуется по нему. Своя ось (кнопка выбора) включается ЯВНО —
+   * парой `selected` и `onSelectedChange`; один `selected` — показ чужой оси,
+   * как в `VirtualGrid`. Без `selected` рамки в разметке нет.
+   */
+  selected?: boolean;
+  /** Вызывается при переключении выбора и получает новое значение. Без обработчика оси выбора нет. */
+  onSelectedChange?: (selected: boolean) => void;
+  /** Своя подпись кнопки выбора. Умолчание — из каталога. */
+  selectLabel?: string;
+}
+
+/**
+ * Плитка с изображением: превью, действия поверх него, бейджи и выбор.
+ *
+ * ГРАНИЦА С `Card`: `Card` — блок содержимого, `MediaCard` — плитка, у которой
+ * главное превью, а всё остальное лежит поверх него или под ним
+ * (ADR-0027). Общего у них
+ * меньше, чем кажется: у карточки нет ни пропорции, ни оверлея, ни выбора.
+ *
+ * ДОМЕННОЕ ОСТАЁТСЯ СНАРУЖИ. Избранное, дубликаты, длинное нажатие и переход по
+ * плитке — знание приложения; сюда приходят узлы. Обобщение делалось с `WPCard`
+ * фронта (212 строк), и вместе с формой домен не поехал.
+ *
+ * ВЫБОР ОБЪЯВЛЯЕТСЯ СОСТОЯНИЕМ, а не рамкой. `aria-pressed` у кнопки говорит
+ * скринридеру, выбрана плитка или нет; рамка — сигнал для глаз, и человек,
+ * который её не видит, иначе не узнает о выборе вовсе. Подпись кнопки при этом
+ * состояние НЕ повторяет: `aria-pressed` уже объявлен, и «Выбрать» вместе с ним
+ * читается однозначно.
+ */
+export const MediaCard = forwardRef<HTMLDivElement, MediaCardProps>(function MediaCard(
+  {
+    preview,
+    ratio = 1,
+    title,
+    subtitle,
+    badges,
+    actions,
+    selected,
+    onSelectedChange,
+    selectLabel,
+    className,
+    ...rest
+  },
+  ref
+) {
+  const messages = useMessages();
+  const selectable = onSelectedChange != null;
+
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        "group border-line-soft bg-bg-2 relative flex flex-col overflow-hidden rounded-xl border transition-colors",
+        // Рамка выбранной плитки — по `selected`, а не по наличию своей оси.
+        // Внутри `VirtualGrid` ось у сетки, карточка — показ: `selected` без
+        // `onSelectedChange`. Рамка по одной своей оси оставляла выбранную
+        // плитку в сетке без всякого знака — при том что справочник
+        // это обещал. Без `selected` класса выбора в разметке нет, как и было.
+        selected && "border-accent-strong ring-accent-strong/40 ring-2",
+        className
+      )}
+      {...rest}
+    >
+      <AspectRatio ratio={ratio} className="bg-bg-3">
+        {preview}
+      </AspectRatio>
+
+      {badges != null && (
+        <div className="pointer-events-none absolute top-2 left-2 flex flex-wrap gap-1">
+          {badges}
+        </div>
+      )}
+
+      {(actions != null || selectable) && (
+        /*
+          Оверлей ВСЕГДА в разметке. Прячется прозрачностью, а показывается при
+          наведении, при фокусе внутри (`focus-within`) и когда плитка выбрана —
+          иначе снятая с выбора плитка теряла бы кнопку под курсором.
+        */
+        <div
+          className={cn(
+            /*
+              Указатель снимается ВМЕСТЕ с прозрачностью и возвращается вместе
+              с ней. `opacity` на попадание указателя не влияет: невидимый
+              оверлей продолжал ловить касания, и на телефоне — где `:hover` не
+              срабатывает и панель прозрачна навсегда — касание правого верхнего
+              угла плитки попадало в невидимую кнопку выбора вместо перехода по
+              плитке. Соседний блок бейджей эту защиту имеет с самого начала.
+            */
+            "pointer-events-none absolute top-2 right-2 flex items-center gap-1 opacity-0 transition-opacity",
+            "group-focus-within:pointer-events-auto group-focus-within:opacity-100",
+            "group-hover:pointer-events-auto group-hover:opacity-100",
+            // Грубый указатель `:hover` не даёт вовсе — там панель открыта
+            // всегда, иначе действия недостижимы.
+            "[@media(hover:none)]:pointer-events-auto [@media(hover:none)]:opacity-100",
+            // Выбранная плитка держит оверлей открытым: иначе снять выбор можно
+            // было бы только вернув курсор, а с клавиатуры — только вернув фокус.
+            // В сетке в оверлее флажок её оси (`Checkbox slot="selection"`) —
+            // правило то же.
+            selected && "pointer-events-auto opacity-100"
+          )}
+        >
+          {actions}
+          {selectable && (
+            <button
+              type="button"
+              aria-pressed={selected ?? false}
+              aria-label={selectLabel ?? messages.mediaCard.select}
+              onClick={() => onSelectedChange(!selected)}
+              className={cn(
+                "focus-visible:outline-accent-strong flex size-6 cursor-pointer items-center justify-center rounded-full border transition-colors focus-visible:outline-2 focus-visible:outline-offset-2",
+                selected
+                  ? "border-accent-strong bg-accent-strong text-white"
+                  : "border-line bg-bg-1/90 text-fg-2"
+              )}
+            >
+              <CheckIcon size={14} />
+            </button>
+          )}
+        </div>
+      )}
+
+      {(title != null || subtitle != null) && (
+        <div className="flex min-w-0 flex-col gap-0.5 px-2.5 py-2">
+          {title != null && <span className="truncate text-[13px] font-medium">{title}</span>}
+          {subtitle != null && <span className="text-fg-2 truncate text-[11px]">{subtitle}</span>}
+        </div>
+      )}
+    </div>
+  );
+});

package/src/components/content/NotificationCenter.tsx

@@ -0,0 +1,168 @@
+"use client";
+
+import { forwardRef, type ComponentPropsWithoutRef, type ReactNode } from "react";
+import { useMessages } from "../../i18n/useMessages.js";
+import { cn } from "../../lib/cn.js";
+import { hasContent } from "../../lib/empty.js";
+import { Badge } from "./Badge.js";
+import { SelectionBar } from "../navigation/SelectionBar.js";
+
+export interface NotificationCenterProps extends Omit<ComponentPropsWithoutRef<"div">, "title"> {
+  /** Заголовок центра. Умолчание — «Уведомления» из каталога. */
+  title?: ReactNode;
+  /**
+   * Уровень заголовка, 2–4: заголовок становится настоящим `<h2>`–`<h4>`.
+   *
+   * Уровень зависит от того, куда центр встал, — в поповер под `h1` страницы
+   * или в ящик, — и это знает потребитель, а не кит. Без пропа заголовок
+   * остаётся обычным текстом и в структуру заголовков страницы не входит.
+   *
+   * Называется `level`, как у `SectionHeader`: одно понятие — одно имя на весь
+   * кит (словарь пропсов в `docs/conventions.md`).
+   */
+  level?: 2 | 3 | 4;
+  /**
+   * `id` заголовка — для `aria-labelledby` поповера или ящика потребителя.
+   *
+   * Ложится на элемент заголовка, какой бы он ни был: с `level` это
+   * `<hN>`, без него — обычный текст, и имя поверхности всё равно приходит от
+   * него.
+   */
+  titleId?: string;
+  /**
+   * Сколько непрочитанных всего — пропом, а не счётом по строкам.
+   *
+   * Список бывает страницей, а счётчик относится ко всей коллекции: посчитав по
+   * детям, центр показывал бы «3» там, где непрочитанных триста.
+   */
+  unreadCount?: number;
+  /** Фильтры — слот. Их состав доменный: типы событий знает приложение. */
+  filters?: ReactNode;
+  /** Действия шапки — обычно «прочитать всё». */
+  actions?: ReactNode;
+  /** Сколько строк выбрано. При нуле полосы массовых действий нет вовсе. */
+  selectedCount?: number;
+  /** Вызывается, когда пользователь снимает выделение. */
+  onClearSelection?: () => void;
+  /** Действия над выбранным — обычно `Button size="sm"`. */
+  selectionActions?: ReactNode;
+  /** Список событий — обычно `NotificationList`. */
+  children?: ReactNode;
+  /** Низ: «Показать все», ссылка на страницу событий. */
+  footer?: ReactNode;
+}
+
+/**
+ * Оболочка ленты событий: заголовок, счётчик непрочитанных, фильтры, массовые
+ * действия.
+ *
+ * ПОВЕРХНОСТИ У ЦЕНТРА НЕТ, и это главное решение
+ * (ADR-0027). Он не
+ * попап, не ящик и не страница — он их содержимое. Потребитель ставит его
+ * внутрь существующих `Popover` или `Drawer` либо прямо на страницу, и центр не
+ * открывает и не закрывает себя: состояние поверхности живёт снаружи.
+ *
+ * Иначе пришлось бы выбрать одну поверхность за все приложения сразу — а в
+ * админке лента чаще страница, в клиентском приложении чаще попап.
+ *
+ * МАССОВЫЕ ДЕЙСТВИЯ — СУЩЕСТВУЮЩИЙ `SelectionBar`, а не своя полоса: он уже
+ * несёт счётчик, снятие выделения, два слота действий и правило «при нуле
+ * полосы нет вовсе». Липкость у него здесь выключена — центр стоит в попапе
+ * или в ящике, где прилипать не к чему.
+ *
+ * СЧЁТЧИК ПРИХОДИТ ПРОПОМ. Считать его по детям нельзя: список бывает страницей
+ * коллекции, и «3» вместо «300» — не округление, а неправда.
+ */
+export const NotificationCenter = forwardRef<HTMLDivElement, NotificationCenterProps>(
+  function NotificationCenter(
+    {
+      title,
+      level,
+      titleId,
+      unreadCount,
+      filters,
+      actions,
+      selectedCount = 0,
+      onClearSelection,
+      selectionActions,
+      children,
+      footer,
+      className,
+      ...rest
+    },
+    ref
+  ) {
+    const messages = useMessages();
+    // Без уровня остаётся `span`, как было: разметка тех, кто новых пропов не
+    // передаёт, не меняется, и заголовков на их странице не прибавляется.
+    // Уровень вне 2–4 (потребитель на JS, `depth + 1`) — тоже `span`: элемента
+    // `<h7>` нет, и заголовок молча пропал бы из структуры вместе с именем.
+    const Title = level === 2 || level === 3 || level === 4 ? (`h${level}` as const) : "span";
+
+    return (
+      <div ref={ref} className={cn("flex min-h-0 flex-col", className)} {...rest}>
+        <div className="border-line-soft flex items-center gap-2 border-b px-3 py-2.5">
+          <Title id={titleId} className="text-[13px] font-semibold">
+            {/* Пустая строка — не заголовок: `??` пропустил бы её, и центр остался бы безымянным. */}
+            {hasContent(title) ? title : messages.notifications.label}
+          </Title>
+          {unreadCount != null && unreadCount > 0 && (
+            /*
+              Имя даётся `sr-only`-текстом, а НЕ `aria-label` на бейдже.
+
+              `Badge` — это `<span>` без роли, то есть роль `generic`, а у неё
+              имя от автора не поддерживается: браузер `aria-label` просто
+              отбрасывает. Скринридер объявлял голое «3» — ровно то, что
+              комментарий обещал предотвратить. Тест давал ложную уверенность:
+              `getByLabelText` читает DOM-атрибут напрямую и проходит
+              независимо от того, признаёт ли его дерево доступности.
+
+              Число при этом прячется от озвучки, чтобы не читалось дважды.
+            */
+            <>
+              <Badge tone="accent" aria-hidden>
+                {unreadCount}
+              </Badge>
+              <span className="sr-only">
+                {messages.notifications.unreadCount({ count: unreadCount })}
+              </span>
+            </>
+          )}
+          {actions != null && <div className="ml-auto flex items-center gap-1.5">{actions}</div>}
+        </div>
+
+        {filters != null && (
+          <div className="border-line-soft flex flex-wrap items-center gap-1.5 border-b px-3 py-2">
+            {filters}
+          </div>
+        )}
+
+        {/*
+          Полоса массовых действий: своей не заводим. `sticky={false}` —
+          центр живёт в попапе или ящике, где липнуть не к чему, а зашитое
+          `--topbar-h` увело бы полосу под чужую шапку.
+        */}
+        {selectedCount > 0 && (
+          <div className="px-3 pt-2">
+            <SelectionBar
+              count={selectedCount}
+              onClear={onClearSelection}
+              sticky={false}
+              className="mb-0"
+            >
+              {selectionActions}
+            </SelectionBar>
+          </div>
+        )}
+
+        {/* Прокручивается СПИСОК, а не центр целиком: шапка и фильтры обязаны
+            остаться на виду, иначе фильтровать приходится вслепую. */}
+        <div className="min-h-0 flex-1 overflow-y-auto">{children}</div>
+
+        {footer != null && (
+          <div className="border-line-soft border-t px-3 py-2 text-center">{footer}</div>
+        )}
+      </div>
+    );
+  }
+);