@olddevs/ui 0.0.0-stage → 4.0.1

package/src/components/navigation/PageHeader.tsx

@@ -0,0 +1,41 @@
+"use client";
+
+import { forwardRef, type ComponentPropsWithoutRef, type ReactNode } from "react";
+import { cn } from "../../lib/cn.js";
+
+export interface PageHeaderProps extends Omit<ComponentPropsWithoutRef<"div">, "title"> {
+  /** Заголовок страницы. `ReactNode`: во фронте сюда кладут разметку с иконкой. */
+  title: ReactNode;
+  /** Пояснение под заголовком. */
+  subtitle?: ReactNode;
+  /** Кнопки справа; на узких экранах переносятся под заголовок. */
+  actions?: ReactNode;
+}
+
+/**
+ * Шапка страницы: заголовок, пояснение и действия.
+ *
+ * Размера у него нет и не будет: страница одна, и второй ступени взяться
+ * неоткуда. Заводить `size` «на будущее» — ровно то, чего пакет избегает.
+ */
+export const PageHeader = forwardRef<HTMLDivElement, PageHeaderProps>(function PageHeader(
+  { title, subtitle, actions, className, ...rest },
+  ref
+) {
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        "mb-6 flex flex-col gap-3 md:flex-row md:items-end md:justify-between",
+        className
+      )}
+      {...rest}
+    >
+      <div>
+        <h1 className="m-0 text-[26px] font-bold tracking-tight">{title}</h1>
+        {subtitle && <div className="text-fg-2 mt-1.5 text-[13px]">{subtitle}</div>}
+      </div>
+      {actions && <div className="flex flex-wrap gap-2">{actions}</div>}
+    </div>
+  );
+});

package/src/components/navigation/Pagination.tsx

@@ -0,0 +1,184 @@
+"use client";
+
+import { ChevronLeftIcon, ChevronRightIcon } from "../../icons.js";
+import { clamp } from "../../lib/clamp.js";
+import { cn } from "../../lib/cn.js";
+import { useMessages } from "../../i18n/useMessages.js";
+import { Button } from "../actions/Button.js";
+
+export interface PaginationProps {
+  /** Номер текущей страницы, с единицы. Значение вне диапазона зажимается в него. */
+  page: number;
+  /** Общее число страниц. При значении 1 и меньше компонент ничего не рисует. */
+  pageCount: number;
+  /** Вызывается с номером страницы, на которую перешли, — по номеру или стрелкам. */
+  onChange: (page: number) => void;
+  /** Сколько страниц показывать вокруг текущей с каждой стороны. */
+  siblings?: number;
+  /** Дополнительные классы на `nav`. */
+  className?: string;
+  /** Доступное имя навигации. По умолчанию берётся из словаря сообщений. */
+  "aria-label"?: string;
+}
+
+/**
+ * Диапазон страниц для показа.
+ *
+ * Алгоритм записан здесь, потому что «какие номера видны» — решение, а не
+ * деталь: список из тридцати номеров бесполезен, а из трёх — не даёт прыгнуть
+ * ни в начало, ни в конец.
+ *
+ * Правило: ВСЕГДА видны первая и последняя страница; вокруг текущей — по
+ * `siblings` соседей; разрывы между этими группами схлопываются в многоточие.
+ * Многоточие рисуется только когда за ним прячется БОЛЬШЕ одной страницы:
+ * «1 … 3 4 5» вместо «1 2 3 4 5» врёт про длину и экономит ровно ничего.
+ *
+ * Ширина ряда при этом постоянна — `2×siblings + 5` ячеек, а на коротком
+ * диапазоне столько, сколько всего страниц, — и кнопки
+ * под курсором не прыгают при переходе на соседнюю страницу.
+ */
+export function pageRange(page: number, pageCount: number, siblings: number): (number | "gap")[] {
+  const first = 1;
+  const last = pageCount;
+  /*
+    Окно ДОБИВАЕТСЯ до постоянной ширины со стороны, где есть запас.
+
+    Без этого ряд шёл 4→5→6→7→7→6→5→4 при `siblings=1` и десяти страницах, и
+    переход 4→5 уводил кнопку «5» влево: повторный щелчок по той же точке экрана
+    попадал в «4». Докстрока обещала обратное — постоянную ширину, — а постоянен
+    был только максимум.
+
+    Ширина СЧИТАЕТСЯ ПО ГОТОВОМУ РЯДУ, а не выводится формулой: крайние
+    страницы и многоточия дают то одну ячейку, то две (ровно одну пропущенную
+    страницу дешевле показать, чем спрятать), и арифметика «на глаз» здесь
+    ошибается.
+  */
+  const width = Math.min(2 * siblings + 5, pageCount);
+  /*
+    Страница ЗАЖИМАЕТСЯ здесь, а не только в компоненте.
+
+    Функция публичная (`index.ts`), и прямой вызов — ожидаемый сценарий:
+    потребитель собирает свой ряд и берёт `?page=` из адреса. Шаг добивания
+    единичный, поэтому со страницей вне диапазона цикл проходил `page −
+    pageCount` итераций, каждая со сборкой массива: `page=1e9` не завершался
+    вовсе — вкладка вешалась. Зажим в компоненте от этого не спасал, он ниже по
+    стеку.
+  */
+  const current = clamp(page, first, last);
+  let from = Math.max(first, current - siblings);
+  let to = Math.min(last, current + siblings);
+
+  while (build(from, to, first, last).length < width && (from > first || to < last)) {
+    if (to < last) to += 1;
+    else from -= 1;
+  }
+  // Последний шаг мог перескочить через цель: ячейка у края добавляет сразу
+  // две (страницу и многоточие). Тогда откатываемся.
+  if (build(from, to, first, last).length > width) {
+    if (to > Math.min(last, page + siblings)) to -= 1;
+    else if (from < Math.max(first, page - siblings)) from += 1;
+  }
+
+  return build(from, to, first, last);
+}
+
+/** Ряд ячеек для готового окна. Вынесен, чтобы ширину можно было измерить. */
+function build(from: number, to: number, first: number, last: number): (number | "gap")[] {
+  const out: (number | "gap")[] = [];
+
+  if (from > first) {
+    out.push(first);
+    // Ровно одна пропущенная страница дешевле показать, чем спрятать.
+    if (from === first + 2) out.push(first + 1);
+    else if (from > first + 1) out.push("gap");
+  }
+
+  for (let p = from; p <= to; p++) out.push(p);
+
+  if (to < last) {
+    if (to === last - 2) out.push(last - 1);
+    else if (to < last - 1) out.push("gap");
+    out.push(last);
+  }
+
+  return out;
+}
+
+/**
+ * Постраничная навигация.
+ *
+ * **При одной странице не рисуется ничего.** Пагинация из единственной кнопки
+ * «1» — это не навигация, а мусор в раскладке: она сообщает о возможности
+ * перехода там, где переходить некуда.
+ *
+ * Собрана руками, а не на react-aria: готового компонента там нет, а всё, что
+ * нужно, — это `nav`, список кнопок и `aria-current`. Своей клавиатурной
+ * механики здесь не появляется, кнопки ходятся обычным табом.
+ */
+export function Pagination({
+  page,
+  pageCount,
+  onChange,
+  siblings = 1,
+  className,
+  "aria-label": ariaLabel,
+}: PaginationProps) {
+  const messages = useMessages();
+  if (pageCount <= 1) return null;
+
+  /*
+    Страница вне диапазона — обычное дело: фильтр сузил выдачу, а номер
+    остался прежним. Без зажима ряд вырождался в «1 …» без текущей страницы
+    вовсе, а «предыдущая» вела на несуществующую.
+  */
+  const current = clamp(page, 1, pageCount);
+  const range = pageRange(current, pageCount, siblings);
+
+  return (
+    <nav
+      aria-label={ariaLabel ?? messages.pagination.label}
+      className={cn("flex items-center gap-1", className)}
+    >
+      <Button
+        size="sm"
+        iconOnly
+        icon={<ChevronLeftIcon size={16} />}
+        aria-label={messages.pagination.previous}
+        disabled={current <= 1}
+        onClick={() => onChange(current - 1)}
+      />
+
+      {range.map((item, index) =>
+        item === "gap" ? (
+          // Многоточие — не кнопка: нажимать его некуда, а кнопка обещала бы
+          // действие. Для скринридера оно скрыто, число страниц он и так знает.
+          <span key={`gap-${index}`} aria-hidden className="text-fg-3 px-1 text-sm">
+            …
+          </span>
+        ) : (
+          <Button
+            key={item}
+            size="sm"
+            variant={item === current ? "solid" : "ghost"}
+            tone={item === current ? "accent" : "neutral"}
+            // `aria-current` вместо `aria-selected`: страница — это место, а не
+            // выбранный из набора элемент.
+            aria-current={item === current ? "page" : undefined}
+            onClick={() => onChange(item)}
+          >
+            {item}
+          </Button>
+        )
+      )}
+
+      <Button
+        size="sm"
+        iconOnly
+        icon={<ChevronRightIcon size={16} />}
+        aria-label={messages.pagination.next}
+        disabled={current >= pageCount}
+        onClick={() => onChange(current + 1)}
+      />
+    </nav>
+  );
+}

package/src/components/navigation/SectionHeader.tsx

@@ -0,0 +1,54 @@
+"use client";
+
+import { forwardRef, type ComponentPropsWithoutRef, type ReactNode } from "react";
+import { cn } from "../../lib/cn.js";
+import type { Size } from "../../lib/variants.js";
+
+export interface SectionHeaderProps extends Omit<ComponentPropsWithoutRef<"div">, "title"> {
+  /** Заголовок: строка или разметка, например иконка с подписью, счётчик, переключатель периода. */
+  title: ReactNode;
+  /** Действия справа: ссылка, кнопка, счётчик. */
+  right?: ReactNode;
+  /** Кегль заголовка: `sm` — мельче, `md` — крупнее (по умолчанию). */
+  size?: Extract<Size, "sm" | "md">;
+  /**
+   * Уровень заголовка в документе: `h2`, `h3` (по умолчанию) или `h4`.
+   *
+   * Уровень заголовка в документе — отдельно от размера, по тому же правилу,
+   * что у `Heading`: порядок заголовков обязан быть непрерывным, а кегль к
+   * нему не привязан.
+   *
+   * Умолчание `3` — то, что компонент рисовал всегда. Оно верно для секции
+   * внутри карточки, стоящей под заголовком секции страницы, и неверно сразу
+   * под `PageHeader`: там между `h1` и `h3` образуется дыра, и оглавление для
+   * скринридера рвётся. На таком экране передавайте `level={2}`.
+   */
+  level?: 2 | 3 | 4;
+}
+
+/** Шкала заголовков секции. Обе ступени взяты из фактических вызовов. */
+const SIZES = {
+  sm: "text-[13px]",
+  md: "text-[15px]",
+} as const;
+
+/**
+ * Заголовок секции внутри карточки: подпись слева, действия справа.
+ *
+ * `title` типизирован как `ReactNode`, а не как строка, потому что во фронте
+ * в него кладут разметку — иконку с подписью, счётчик, переключатель периода.
+ * Сузить тип до строки значило бы сломать восемь вызовов из семнадцати.
+ */
+export const SectionHeader = forwardRef<HTMLDivElement, SectionHeaderProps>(function SectionHeader(
+  { title, right, size = "md", level = 3, className, ...rest },
+  ref
+) {
+  const Comp = `h${level}` as const;
+
+  return (
+    <div ref={ref} className={cn("mb-3.5 flex items-center justify-between", className)} {...rest}>
+      <Comp className={cn("m-0 font-bold", SIZES[size])}>{title}</Comp>
+      {right}
+    </div>
+  );
+});

package/src/components/navigation/SelectionBar.tsx

@@ -0,0 +1,151 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { CloseIcon } from "../../icons.js";
+import { cn } from "../../lib/cn.js";
+import { useMessages } from "../../i18n/useMessages.js";
+import { useStickyOffset } from "../../hooks/useStickyOffset.js";
+import { BUTTON_ICON_SIZE } from "../../lib/button.js";
+
+export interface SelectionBarProps {
+  /** Сколько объектов выбрано. При нуле полоса не рисуется вовсе. */
+  count: number;
+  /**
+   * Подпись счётчика. Умолчание — «Выбрано N»; своя нужна там, где счёт идёт
+   * в предметных единицах («Выбрано 12 обоев») и слово при числе нужно согласовать с ним.
+   */
+  countLabel?: (count: number) => ReactNode;
+  /** Вызывается, когда пользователь снимает выделение. Кнопка стоит слева от счётчика и рисуется иконкой «×»; без обработчика её нет. */
+  onClear?: () => void;
+  /** Действия над выбранным — обычно `Button size="sm"`. */
+  children?: ReactNode;
+  /**
+   * Правый край полосы: «Выбрать все», ссылка на справку. Отделён от
+   * `children`, потому что живёт по другую сторону распорки и на узком экране
+   * уезжает в первую строку, к счётчику.
+   */
+  secondary?: ReactNode;
+  /**
+   * Липнуть под верхней панелью приложения. Выключается там, где полоса стоит
+   * в области без прокрутки.
+   */
+  sticky?: boolean;
+  /**
+   * Имя CSS-переменной с высотой панели — см. `useStickyOffset` и ADR-0016.
+   *
+   * Одно имя на обе половины липкости: по нему считается и точка прилипания
+   * (`top`), и момент, когда полоса теряет верхние скругления. Разъехавшись,
+   * они дали бы полосу, которая липнет к одной панели, а углы срезает по
+   * другой.
+   */
+  offsetVar?: string;
+  /** Доступное имя группы действий. */
+  "aria-label"?: string;
+  /** Дополнительные классы на полосу. */
+  className?: string;
+}
+
+/** Умолчание общее с `useStickyOffset`: так эта переменная зовётся у потребителя. */
+const DEFAULT_OFFSET_VAR = "--topbar-h";
+
+const PANEL =
+  "border-line z-20 mb-4 flex flex-col gap-2 border p-[10px_14px] backdrop-blur-md " +
+  "shadow-[var(--shadow-1)] sm:flex-row sm:items-center sm:gap-[14px]";
+
+/**
+ * Полоса массовых действий: «Выбрано 12» и что с этим можно сделать.
+ *
+ * Во фронте таких полос было три, и они разошлись: разные тени (`shadow-1`
+ * против `shadow-2`), разные радиусы (14 против 12), а третья собрана на
+ * инлайн-стилях с захардкоженной `rgba(47,139,230,0.07)` вместо токена. Одна
+ * и та же вещь в трёх видах — ровно тот случай, ради которого существует
+ * дизайн-система.
+ *
+ * ДВА СЛОТА, А НЕ ОДИН. `children` — действия, `secondary` — правый край
+ * («Выбрать все»). Разделение не косметическое: действия занимают всё
+ * свободное место и прижимают `secondary` к правому краю, а на узком экране
+ * `secondary` уезжает наверх, к счётчику, и действия переносятся во вторую
+ * строку. Одним слотом это не выражается.
+ *
+ * ЛИПКОСТЬ ОТСЧИТЫВАЕТСЯ ОТ НАСТОЯЩЕЙ ВЫСОТЫ ШАПКИ, которую публикует
+ * приложение (`--topbar-h` по умолчанию, имя переменной — проп). Зашитое
+ * число оставляло просвет: на узких экранах шапка ниже. Прижавшись, полоса
+ * теряет верхние скругления — иначе они приоткрывают фон страницы уголками
+ * на стыке. Контракт и отвергнутые варианты — ADR-0016.
+ *
+ * Полоса объявляется группой с доступным именем: для скринридера это набор
+ * действий над выбранным, а не случайные кнопки посреди страницы. Счётчик
+ * стоит первым и читается вместе с именем группы.
+ */
+export function SelectionBar({
+  count,
+  countLabel,
+  onClear,
+  children,
+  secondary,
+  sticky = true,
+  offsetVar = DEFAULT_OFFSET_VAR,
+  "aria-label": ariaLabel,
+  className,
+}: SelectionBarProps) {
+  const messages = useMessages();
+  const label = countLabel ?? ((n: number) => messages.selectionBar.count({ count: n }));
+  const { sentinelRef, isStuck } = useStickyOffset({ offsetVar });
+
+  if (count <= 0) return null;
+
+  return (
+    <>
+      {/* Маркер нулевой высоты: его пересечение и означает, что полоса встала
+          на место. Отдельный узел нужен потому, что сама полоса уже липкая и
+          из потока не выпадает. */}
+      {sticky ? <div ref={sentinelRef} aria-hidden="true" style={{ height: 0 }} /> : null}
+
+      <div
+        role="group"
+        aria-label={ariaLabel ?? messages.selectionBar.label}
+        className={cn(PANEL, sticky && "sticky", className)}
+        style={{
+          top: sticky ? `var(${offsetVar}, 0px)` : undefined,
+          background: "var(--topbar-bg)",
+          borderRadius: sticky && isStuck ? "0 0 14px 14px" : "14px",
+          transition: "border-radius 120ms ease",
+        }}
+      >
+        <div className="flex items-center justify-between gap-2 sm:shrink-0">
+          <div className="flex items-center gap-2.5 whitespace-nowrap">
+            {onClear ? (
+              <button
+                type="button"
+                onClick={onClear}
+                aria-label={messages.selectionBar.clearSelection}
+                className="text-fg-1 hover:text-fg-0 focus-visible:outline-accent-strong flex cursor-pointer items-center focus-visible:outline-2 focus-visible:outline-offset-2"
+              >
+                <CloseIcon size={BUTTON_ICON_SIZE.md} />
+              </button>
+            ) : null}
+            <span className="text-[13px] font-semibold">{label(count)}</span>
+          </div>
+          {secondary ? <span className="sm:hidden">{secondary}</span> : null}
+        </div>
+
+        <span className="bg-line hidden h-[22px] w-px sm:block" />
+
+        {/*
+          Действия — своя переносимая строка, которая занимает всё место между
+          счётчиком и правым краем. Прежде с `sm` обёртка была `contents`, и
+          кнопки вставали в общую строку полосы без переноса: на средней
+          ширине flex ужимал их ниже подписи, подписи ломались на две строки,
+          иконки сплющивались. В переносимой строке элемент не
+          ужимается, пока влезает целиком, — лишние кнопки уходят ниже. Зазор
+          между кнопками — прежние 14 px полосы, между строками — 8.
+        */}
+        <div className="flex flex-wrap items-center gap-2 sm:min-w-0 sm:flex-1 sm:gap-x-[14px]">
+          {children}
+        </div>
+
+        {secondary ? <span className="hidden whitespace-nowrap sm:block">{secondary}</span> : null}
+      </div>
+    </>
+  );
+}

package/src/components/navigation/Stepper.tsx

@@ -0,0 +1,153 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { CheckIcon } from "../../icons.js";
+import { cn } from "../../lib/cn.js";
+import { useMessages } from "../../i18n/useMessages.js";
+
+export interface Step {
+  /** Стабильный идентификатор шага, ключ списка. */
+  id: string;
+  /** Подпись шага. */
+  label: string;
+  /** Короткое пояснение под подписью. */
+  hint?: ReactNode;
+}
+
+export interface StepperProps {
+  /** Шаги мастера по порядку. */
+  steps: Step[];
+  /** Индекс текущего шага, с нуля. */
+  current: number;
+  /**
+   * Вызывается по клику на пройденный шаг и получает его индекс.
+   *
+   * Не задан — шаги некликабельны вовсе, и это умолчание. Вернуться назад
+   * можно **только на пройденный** шаг: будущий шаг требует данных, которых
+   * ещё нет, и пустить туда — значит показать форму, которая не сможет
+   * ни отправиться, ни объяснить, чего ей не хватает.
+   *
+   * Мастер, где возвращаться нельзя вовсе (оплата, необратимый импорт),
+   * просто не передаёт колбэк.
+   */
+  onStepClick?: (index: number) => void;
+  /** Направление ряда: `horizontal` — шаги в строку (по умолчанию), `vertical` — в колонку. */
+  orientation?: "horizontal" | "vertical";
+  /** Дополнительные классы на `nav`. */
+  className?: string;
+  /** Доступное имя навигации. По умолчанию берётся из словаря сообщений. */
+  "aria-label"?: string;
+}
+
+/**
+ * Шаги мастера: где пользователь сейчас и сколько осталось.
+ *
+ * Собран руками: в react-aria такого компонента нет, а из поведения здесь —
+ * только переход по клику, который целиком принадлежит вызывающему.
+ *
+ * Разметка — упорядоченный список внутри `nav`: шаги идут по порядку, и
+ * скринридер обязан сообщить и порядок, и общее число. Текущий помечается
+ * `aria-current="step"`.
+ */
+export function Stepper({
+  steps,
+  current,
+  onStepClick,
+  orientation = "horizontal",
+  className,
+  "aria-label": ariaLabel,
+}: StepperProps) {
+  const messages = useMessages();
+
+  return (
+    <nav aria-label={ariaLabel ?? messages.stepper.label} className={cn("min-w-0", className)}>
+      <ol
+        className={cn(
+          "flex gap-2",
+          orientation === "horizontal" ? "flex-row items-start" : "flex-col"
+        )}
+      >
+        {steps.map((step, index) => {
+          const done = index < current;
+          const active = index === current;
+          const clickable = onStepClick != null && done;
+
+          const body = (
+            <>
+              <span
+                aria-hidden
+                className={cn(
+                  "text-caption flex size-6 shrink-0 items-center justify-center rounded-full border font-semibold",
+                  done && "border-accent-strong bg-accent-soft text-accent-strong",
+                  // `text-text-on-accent`, а не `text-on-accent`: второго класса не
+                  // существует вовсе, и номер активного шага красился ничем
+                  // поверх акцентной заливки. Поймала матрица покрытия классов —
+                  // ровно то, ради чего она заведена.
+                  active && "border-accent-strong bg-accent text-text-on-accent",
+                  !done && !active && "border-line text-fg-3"
+                )}
+              >
+                {done ? <CheckIcon size={12} /> : index + 1}
+              </span>
+              {/*
+                Состояние шага — ТЕКСТОМ, а не только кружком.
+
+                Кружок с номером или галочкой помечен `aria-hidden`, а больше
+                признак «пройден / текущий / впереди» нигде не выражен: у `li`
+                есть только `aria-current` у активного. Скринридер читал мастер
+                из пяти одинаковых пунктов и текущий — какие уже заполнены, а
+                какие впереди, не сообщалось никак.
+              */}
+              {/*
+                Текущий шаг СВОЕЙ строки не получает: его объявляет
+                `aria-current="step"` на `li`, и вторая строка давала «current
+                step, current step, Оплата» — состояние читалось дважды.
+              */}
+              {active ? null : (
+                <span className="sr-only">
+                  {messages.stepper.state({ state: done ? "done" : "upcoming" })}
+                </span>
+              )}
+              <span className="flex min-w-0 flex-col">
+                <span
+                  className={cn(
+                    "truncate text-sm",
+                    active ? "text-fg-0 font-semibold" : done ? "text-fg-1" : "text-fg-2"
+                  )}
+                >
+                  {step.label}
+                </span>
+                {step.hint ? <span className="text-fg-2 text-caption">{step.hint}</span> : null}
+              </span>
+            </>
+          );
+
+          return (
+            <li
+              key={step.id}
+              className={cn(
+                "flex min-w-0 flex-1 items-start gap-2",
+                orientation === "vertical" && "flex-none"
+              )}
+              // Текущий шаг объявляется шагом, а не страницей: `aria-current`
+              // различает эти значения, и «step» — ровно этот случай.
+              aria-current={active ? "step" : undefined}
+            >
+              {clickable ? (
+                <button
+                  type="button"
+                  onClick={() => onStepClick(index)}
+                  className="focus-visible:outline-accent-strong flex min-w-0 cursor-pointer items-start gap-2 text-left outline-none focus-visible:outline-2 focus-visible:outline-offset-2"
+                >
+                  {body}
+                </button>
+              ) : (
+                <span className="flex min-w-0 items-start gap-2">{body}</span>
+              )}
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+}