@olddevs/ui 0.0.0-stage → 4.0.1

package/src/components/table/DataTable.tsx

@@ -0,0 +1,164 @@
+"use client";
+
+import type { ReactNode } from "react";
+import type { Key } from "react-aria-components";
+import { cn } from "../../lib/cn.js";
+import { hasContent } from "../../lib/empty.js";
+import { orderColumns, visibleColumns, type TableState } from "../../lib/table-state.js";
+import { Skeleton } from "../content/Skeleton.js";
+import { Table, type TableColumn, type TableProps } from "../content/Table.js";
+
+export interface DataTableProps<T extends { id: Key }> extends Omit<
+  TableProps<T>,
+  | "sort"
+  | "onSortChange"
+  | "selectedKeys"
+  | "onSelectionChange"
+  | "expandedKeys"
+  | "onExpandedChange"
+> {
+  /** Полный набор колонок таблицы; видимость и порядок накладываются на него из `state`. */
+  columns: TableColumn<T>[];
+  /** Строки таблицы. Каждая обязана нести `id` — по нему строится ключ и выделение. */
+  items: T[];
+  /** Состояние целиком — обычно из `useTableState`. */
+  state: TableState;
+  /**
+   * Вызывается при любом изменении состояния — сортировки, выделения, раскрытия — и получает частичный патч.
+   *
+   * Изменения уходят одним патчем: инварианты живут в хуке, а не здесь.
+   */
+  onStateChange: (patch: Partial<TableState>) => void;
+  /** Идёт загрузка. С данными на экране они остаются, без данных — скелет. */
+  loading?: boolean;
+  /** Ошибка. Если передана, показывается вместо тела всегда, даже когда данные есть. */
+  error?: ReactNode;
+  /** Полоса над таблицей — обычно `TableToolbar`. */
+  toolbar?: ReactNode;
+  /**
+   * Выделение строк.
+   *
+   * Отдельный проп, а не «раз состояние есть — значит нужно»: в состоянии
+   * `selectedKeys` лежит всегда, и передавай надстройка его безусловно, колонка
+   * флажков появлялась бы у таблиц, которым выделение не нужно. Правило `Table`
+   * — ось включается наличием пропа — надстройка не отменяет.
+   */
+  selectable?: boolean;
+}
+
+/*
+ * Тип ключа берётся у react-aria, а не у React: у `React.Key` есть `bigint`,
+ * которого в коллекциях react-aria нет, и союз не сходится.
+ */
+
+/** Плотные строки — классом, а не токеном: это раскладка, а не цвет. */
+const DENSITY_CLASS = {
+  comfortable: "",
+  compact: "[&_td]:py-1 [&_th]:py-1",
+} as const;
+
+/**
+ * Продуктовая таблица: настройки колонок, плотность, состояния загрузки и
+ * ошибки поверх низкоуровневой `Table`.
+ *
+ * НАДСТРОЙКА, А НЕ ЗАМЕНА. Внутри — та же `Table`, что снаружи: видимость и
+ * порядок колонок, плотность и состояния выражаются её пропсами. Единственное,
+ * что пришлось добавить в саму `Table`, — ось раскрытия: детальная строка живёт
+ * внутри `<tbody>`, и вставить её снаружи невозможно (ADR-0022).
+ *
+ * Признак нарушения границы проверяемый: если что-то можно было сделать
+ * пропсами снаружи, а оно оказалось внутри `Table`, — граница уже сдвинулась.
+ *
+ * СОСТОЯНИЯ РАЗЛИЧАЮТ ПЕРВУЮ ЗАГРУЗКУ И ПЕРЕЗАПРОС:
+ *
+ * - ошибка — всегда вместо тела: показанные при ошибке данные врут, а отличить
+ *   устаревшие от актуальных пользователь не может;
+ * - загрузка без данных — скелет вместо тела, шапка на месте;
+ * - загрузка с данными — данные остаются под `aria-busy`. Иначе таблица
+ *   схлопывалась бы в скелет на каждой смене страницы;
+ * - пусто — только когда загрузка кончилась и ошибки нет.
+ */
+export function DataTable<T extends { id: Key }>({
+  columns,
+  items,
+  state,
+  onStateChange,
+  loading = false,
+  error,
+  toolbar,
+  selectable = false,
+  className,
+  emptyText,
+  ...rest
+}: DataTableProps<T>) {
+  // Скрытая колонка НЕ попадает в разметку, а не прячется классом: спрятанный
+  // столбец остаётся в дереве доступности заголовком без ячеек, и скринридер
+  // читает таблицу с колонкой, которой на экране нет.
+  //
+  // Оба хелпера защищают от состояния, пришедшего из адреса: там ни порядок, ни
+  // список скрытых с реальными колонками не сверялись.
+  const visible = visibleColumns(orderColumns(columns, state.columnOrder), state.hiddenColumns);
+
+  const first = loading && items.length === 0;
+  /*
+    Через `hasContent`, а не `error != null`.
+
+    Волна завела предикат ровно против этого класса дефектов, и здесь он был
+    пропущен. Самая частая идиома условного рендера — `error={isError && <Text/>}`
+    — при отсутствии ошибки даёт `false`, а `false != null` истинно: `replaced`
+    становился истинным, строки заменялись пустым телом, и таблица С ДАННЫМИ
+    показывала пустоту плюс `role="alert"` без текста.
+  */
+  const failed = hasContent(error);
+  const body: ReactNode = failed ? (
+    /*
+        Ошибка ОБЪЯВЛЯЕТСЯ, а пустой результат — нет.
+
+        Текст ошибки подставлялся в `emptyText` и попадал в `renderEmptyState` —
+        обычный `div`. Пользователь клавиатуры жал «Обновить», запрос падал,
+        строки исчезали, на их месте появлялся текст, и не произносилось ничего:
+        таблица молча пустела и читалась как «ничего не найдено».
+
+        `alert`, а не `status`: сбой загрузки перебивает речь законно. Пустому
+        результату и скелету роль не даётся — это не сбой.
+      */
+    <div role="alert">{error}</div>
+  ) : first ? (
+    <Skeleton className="h-24 w-full" />
+  ) : (
+    (emptyText ?? undefined)
+  );
+
+  // Замещающее состояние показывается пустым телом со своим содержимым: так
+  // шапка остаётся на месте, и страница не скачет между состояниями.
+  const replaced = failed || first;
+
+  return (
+    <div className={cn("flex flex-col gap-3", className)}>
+      {toolbar}
+
+      <div
+        aria-busy={loading || undefined}
+        className={cn(loading && items.length > 0 && "opacity-60")}
+      >
+        <Table
+          {...rest}
+          columns={visible}
+          items={replaced ? [] : items}
+          emptyText={body}
+          className={DENSITY_CLASS[state.density]}
+          sort={state.sort}
+          onSortChange={(sort) => onStateChange({ sort })}
+          selectedKeys={selectable ? state.selectedKeys : undefined}
+          onSelectionChange={
+            selectable ? (selectedKeys) => onStateChange({ selectedKeys }) : undefined
+          }
+          expandedKeys={rest.renderDetail ? state.expandedKeys : undefined}
+          onExpandedChange={
+            rest.renderDetail ? (expandedKeys) => onStateChange({ expandedKeys }) : undefined
+          }
+        />
+      </div>
+    </div>
+  );
+}

package/src/components/table/FilterBar.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+import { forwardRef, type ComponentPropsWithoutRef, type ReactNode } from "react";
+import { Button as AriaButton, Tag, TagGroup, TagList } from "react-aria-components";
+import { CloseIcon } from "../../icons.js";
+import { useMessages } from "../../i18n/useMessages.js";
+import { cn } from "../../lib/cn.js";
+import { rangeText } from "../../lib/filter-range.js";
+import type { TableFilter } from "../../lib/table-state.js";
+import { Button } from "../actions/Button.js";
+
+export interface FilterBarProps extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
+  /** Применённые фильтры; каждый рисуется снимаемым токеном. */
+  filters: TableFilter[];
+  /** Получает новый список фильтров после снятия одного токена или всех сразу. */
+  onFiltersChange: (filters: TableFilter[]) => void;
+  /**
+   * Подпись токена. Не задана — «поле: значение», а у диапазона (есть `to`) —
+   * «поле: 50–100», «поле: от 50», «поле: до 100» словами каталога сообщений.
+   *
+   * Подпись **не является** идентификатором: снятие идёт по `filter.id`.
+   * Иначе два фильтра по одному полю с одинаковыми на вид подписями стали бы
+   * неразличимы, а локализованная или обрезанная подпись — вовсе непригодной.
+   */
+  renderLabel?: (filter: TableFilter) => string;
+  /** Доступное имя набора. Не задано — из каталога сообщений. */
+  label?: string;
+  /** Слот добавления фильтра — обычно `FilterBarAdd`. */
+  children?: ReactNode;
+}
+
+/**
+ * Применённые фильтры снимаемыми токенами.
+ *
+ * Компонент **не знает, какие бывают фильтры**: их список приходит пропом, а
+ * доменного словаря в ките не появляется. Это и отличает его от `LibraryFilterBar`
+ * во фронте, где 373 строки состоят из зашитых групп и продуктовых пикеров, —
+ * переносится форма, а не код.
+ *
+ * Токены стоят на `TagGroup` из react-aria, тем же приёмом, что `TagInput`, а не
+ * на `Chip`: у чипа нет снятия, и он про переключение, а не про снятие. Заодно
+ * бесплатно приходит клавиатура: Delete и Backspace на токене.
+ */
+export const FilterBar = forwardRef<HTMLDivElement, FilterBarProps>(function FilterBar(
+  { filters, onFiltersChange, renderLabel, label, className, children, ...rest },
+  ref
+) {
+  const messages = useMessages();
+
+  // Диапазон без своей подписи нельзя показать как «поле: значение»: «от 50»
+  // выглядело бы равенством «= 50» (ADR-0063). Подпись, собранная
+  // `FilterBarAdd`, приходит в `filter.label` и сюда не доходит.
+  const labelOf =
+    renderLabel ??
+    ((filter: TableFilter) =>
+      filter.label ??
+      `${filter.field}: ${
+        filter.to !== undefined ? rangeText(messages, filter.value, filter.to) : filter.value
+      }`);
+
+  return (
+    <div ref={ref} className={cn("flex flex-wrap items-center gap-2", className)} {...rest}>
+      {filters.length > 0 ? (
+        <TagGroup
+          aria-label={label ?? messages.filterBar.label}
+          className="contents"
+          onRemove={(keys) => onFiltersChange(filters.filter((f) => !keys.has(f.id)))}
+        >
+          <TagList items={filters} className="contents">
+            {(filter) => (
+              <Tag
+                id={filter.id}
+                textValue={labelOf(filter)}
+                className="border-line-soft bg-bg-2 text-fg-1 focus-visible:outline-accent-strong flex items-center gap-1 rounded-full border py-0.5 pr-1 pl-2.5 text-[13px] outline-none focus-visible:outline-2 focus-visible:outline-offset-2"
+              >
+                {labelOf(filter)}
+                {/*
+                  Кнопка ОБЯЗАНА быть `Button` из react-aria: поведение снятия
+                  подключается через `ButtonContext`, и голая `<button>` его не
+                  читает — разметка валидна, axe доволен, а нажатие не делает
+                  ничего. Ровно эта ловушка уже описана в `TagInput`.
+
+                  Подпись здесь ОБЩАЯ, без имени фильтра: react-aria дописывает
+                  к имени кнопки подпись своего тега сам, и «Снять фильтр
+                  Раздел: Договоры» читалось бы с задвоением. Проверено
+                  вычисленным доступным именем, а не глазами по разметке.
+                */}
+                <AriaButton
+                  slot="remove"
+                  aria-label={messages.filterBar.remove}
+                  className="text-fg-3 hover:text-fg-0 focus-visible:outline-accent-strong flex cursor-pointer items-center rounded-full p-0.5 outline-none focus-visible:outline-2 focus-visible:outline-offset-1"
+                >
+                  <CloseIcon size={12} />
+                </AriaButton>
+              </Tag>
+            )}
+          </TagList>
+        </TagGroup>
+      ) : null}
+
+      {children}
+
+      {/*
+        Кнопка «снять все» появляется со второго фильтра: при одном она делает
+        ровно то же, что его крестик, и только удлиняет обход с клавиатуры.
+      */}
+      {filters.length > 1 ? (
+        <Button variant="ghost" size="sm" onClick={() => onFiltersChange([])}>
+          {messages.filterBar.clear}
+        </Button>
+      ) : null}
+    </div>
+  );
+});

package/src/components/table/FilterBarAdd.tsx

@@ -0,0 +1,268 @@
+"use client";
+
+import { forwardRef, useRef, useState, type ComponentPropsWithoutRef } from "react";
+import { AddIcon } from "../../icons.js";
+import { useMessages, useUiLocale } from "../../i18n/useMessages.js";
+import { cn } from "../../lib/cn.js";
+import { parseDateOrNull } from "../../lib/date.js";
+import { formatRangeDate, formatRangeNumber, rangeText } from "../../lib/filter-range.js";
+import type { TableFilter } from "../../lib/table-state.js";
+import { Button } from "../actions/Button.js";
+import { DatePicker } from "../date-time/DatePicker.js";
+import { NumberInput } from "../inputs/NumberInput.js";
+import { Popover, PopoverContent, PopoverTrigger } from "../overlays/Popover.js";
+import { Select } from "../inputs/Select.js";
+
+/**
+ * Разделитель составного ключа «поле + значение».
+ *
+ * Ключ нужен, чтобы за один проход узнать, какие пары уже выбраны: искать
+ * пару перебором списка на каждый пункт меню — квадрат по числу фильтров.
+ * Разделителем взят символ, которого не бывает в идентификаторе поля или
+ * значения, иначе пары `a` + `bc` и `ab` + `c` дали бы один ключ.
+ *
+ * Записан ИМЕННО escape-последовательностью, а не самим символом. Сырой
+ * нулевой байт в исходнике делает файл бинарным для `file` и `grep`: `grep`
+ * такой файл молча пропускает, выходя с кодом 1 и без сообщения, — то есть
+ * любой текстовый гейт обходит его стороной, не сказав об этом ни слова.
+ */
+const KEY_SEPARATOR = "\u0000";
+
+const filterKey = (field: string | undefined, value: string) => `${field}${KEY_SEPARATOR}${value}`;
+
+export interface FilterField {
+  /** Идентификатор поля; попадает в `field` создаваемого фильтра. */
+  id: string;
+  /** Подпись поля. Строка: она же попадает в подпись токена. */
+  label: string;
+  /**
+   * Вид поля (ADR-0063). `"values"` — выбор из списка `values`, равенство;
+   * `"number-range"` и `"date-range"` — два поля «от» и «до», токен с `to`.
+   * Не задан — `"values"`.
+   */
+  kind?: "values" | "number-range" | "date-range";
+  /**
+   * Допустимые значения для `kind: "values"`. Пустой список — поле в выборе не
+   * появится. У диапазонов не используется: передайте `[]`.
+   *
+   * Обязательно и у диапазонов: необязательное поле сломало бы потребителя,
+   * который читает `field.values.length` у своих полей (minor не ломает типы).
+   */
+  values: { id: string; label: string }[];
+}
+
+/** Строка границы диапазона → число для `NumberInput`; пусто — `null`. */
+const toNumber = (bound: string) => (bound === "" ? null : Number(bound));
+
+/** Перевёрнутый диапазон: обе границы заданы, и нижняя больше верхней. ISO-даты сравнимы как строки. */
+function isInverted(kind: FilterField["kind"], from: string, to: string) {
+  if (from === "" || to === "") return false;
+  return kind === "number-range" ? Number(from) > Number(to) : from > to;
+}
+
+export interface FilterBarAddProps extends Omit<
+  ComponentPropsWithoutRef<"div">,
+  "onChange" | "children"
+> {
+  /** Поля, по которым можно добавить фильтр, со своими значениями. */
+  fields: FilterField[];
+  /** Уже применённые: их значения повторно не предлагаются. */
+  filters: TableFilter[];
+  /** Получает собранный фильтр после нажатия «Применить». */
+  onAdd: (filter: TableFilter) => void;
+}
+
+/**
+ * Добавление фильтра: выбор поля, затем значения.
+ *
+ * Список полей и значений приходит пропом — доменного словаря в ките не
+ * появляется, как и в `FilterBar`.
+ *
+ * УЖЕ ПРИМЕНЁННОЕ ЗНАЧЕНИЕ ПОВТОРНО НЕ ПРЕДЛАГАЕТСЯ. Иначе пользователь
+ * добавляет второй такой же токен, выборка не меняется, и он остаётся с двумя
+ * одинаковыми на вид фильтрами, из которых непонятно, какой снимать.
+ *
+ * Идентификатор токена собирается из поля и значения: пара уникальна как раз
+ * потому, что дубли запрещены выше.
+ *
+ * ДИАПАЗОН (`kind: "number-range" | "date-range"`) — два поля вместо списка
+ * значений, ADR-0063. «Применить» доступно, когда задана хотя бы одна граница;
+ * перевёрнутый диапазон («от 100 до 50») применить нельзя — он ничего не
+ * выберет, а пустоту пользователь прочтёт как «данных нет». Поле с уже
+ * применённым диапазоном повторно не предлагается: два диапазона по одному
+ * полю — пересечение, а не добавление, и токены были бы неразличимы. Подпись
+ * токена («Сумма: 50–100», «Дата: до 12 марта 2026 г.») собирается здесь, из
+ * каталога сообщений и локали `UiProvider`, и едет в `label`.
+ */
+export const FilterBarAdd = forwardRef<HTMLDivElement, FilterBarAddProps>(function FilterBarAdd(
+  { fields, filters, onAdd, className, ...rest },
+  ref
+) {
+  const messages = useMessages();
+  const locale = useUiLocale();
+  const [open, setOpen] = useState(false);
+  const [field, setField] = useState<string | null>(null);
+  const [value, setValue] = useState<string | null>(null);
+  // Границы диапазона строками, как они уйдут в фильтр; пусто — не задана.
+  const [from, setFrom] = useState("");
+  const [to, setTo] = useState("");
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+
+  const taken = new Set(filters.map((f) => filterKey(f.field, f.value)));
+  const rangeApplied = (f: FilterField) => filters.some((x) => x.field === f.id);
+  const availableFields = fields.filter((f) =>
+    f.kind === "number-range" || f.kind === "date-range"
+      ? !rangeApplied(f)
+      : (f.values ?? []).some((v) => !taken.has(filterKey(f.id, v.id)))
+  );
+  const current = fields.find((f) => f.id === field);
+  const kind = current?.kind ?? "values";
+  const isRange = kind === "number-range" || kind === "date-range";
+  const availableValues = (current?.values ?? []).filter(
+    (v) => !taken.has(filterKey(current?.id, v.id))
+  );
+
+  const close = () => {
+    setOpen(false);
+    setField(null);
+    setValue(null);
+    setFrom("");
+    setTo("");
+    // Фокус возвращается на кнопку, а не теряется в закрывшемся попоувере:
+    // потерянный фокус уезжает в начало документа, и клавиатурный пользователь
+    // начинает обход страницы заново.
+    triggerRef.current?.focus();
+  };
+
+  const canApply = isRange
+    ? (from !== "" || to !== "") && !isInverted(kind, from, to)
+    : value != null;
+
+  const apply = () => {
+    if (!current || !canApply) return;
+
+    if (isRange) {
+      const format = kind === "number-range" ? formatRangeNumber : formatRangeDate;
+      onAdd({
+        id: `${current.id}:range`,
+        field: current.id,
+        value: from,
+        // Пустая строка, а не отсутствие ключа: именно `to` отличает «от 50»
+        // от равенства «= 50».
+        to,
+        label: `${current.label}: ${rangeText(messages, format(from, locale), format(to, locale))}`,
+      });
+      close();
+      return;
+    }
+
+    const label = (current.values ?? []).find((v) => v.id === value)?.label ?? value;
+    onAdd({
+      id: `${current.id}:${value}`,
+      field: current.id,
+      value: value!,
+      label: `${current.label}: ${label}`,
+    });
+    close();
+  };
+
+  const inverted = isInverted(kind, from, to);
+
+  return (
+    <div ref={ref} className={cn("inline-flex", className)} {...rest}>
+      <Popover open={open} onOpenChange={(next) => (next ? setOpen(true) : close())}>
+        <PopoverTrigger asChild>
+          {/*
+            `asChild` обязателен: без него Radix рисует свою кнопку вокруг
+            нашей, и получается кнопка в кнопке — аудит роняет прогон.
+          */}
+          <Button
+            ref={triggerRef}
+            variant="outline"
+            size="sm"
+            icon={<AddIcon size={14} />}
+            disabled={availableFields.length === 0}
+          >
+            {messages.filterBar.add}
+          </Button>
+        </PopoverTrigger>
+
+        <PopoverContent className="flex w-[260px] flex-col gap-3 p-3">
+          <Select
+            aria-label={messages.filterBar.field}
+            placeholder={messages.filterBar.field}
+            items={availableFields.map((f) => ({ id: f.id, label: f.label }))}
+            value={field}
+            onChange={(id) => {
+              setField(id == null ? null : String(id));
+              setValue(null);
+              setFrom("");
+              setTo("");
+            }}
+          />
+
+          {/*
+            Второй шаг рисуется ТОЛЬКО после выбора поля: пустой выключенный
+            селект рядом с заполненным читается как ошибка, а не как «шаг ещё
+            не пройден».
+          */}
+          {current && kind === "values" ? (
+            <Select
+              aria-label={messages.filterBar.value}
+              placeholder={messages.filterBar.value}
+              items={availableValues}
+              value={value}
+              onChange={(id) => setValue(id == null ? null : String(id))}
+            />
+          ) : null}
+
+          {current && kind === "number-range" ? (
+            <>
+              <NumberInput
+                label={messages.filterBar.fromField}
+                value={toNumber(from)}
+                onChange={(n) => setFrom(n == null ? "" : String(n))}
+                invalid={inverted}
+              />
+              <NumberInput
+                label={messages.filterBar.toField}
+                value={toNumber(to)}
+                onChange={(n) => setTo(n == null ? "" : String(n))}
+                invalid={inverted}
+              />
+            </>
+          ) : null}
+
+          {current && kind === "date-range" ? (
+            <>
+              {/*
+                У `DatePicker` нет пропа с именем, а триггер показывает дату, а
+                не подпись поля: имя несёт группа вокруг него.
+              */}
+              <div role="group" aria-label={messages.filterBar.fromField}>
+                <DatePicker
+                  value={from}
+                  onChange={setFrom}
+                  placeholder={messages.filterBar.fromField}
+                  maxValue={parseDateOrNull(to) ?? undefined}
+                />
+              </div>
+              <div role="group" aria-label={messages.filterBar.toField}>
+                <DatePicker
+                  value={to}
+                  onChange={setTo}
+                  placeholder={messages.filterBar.toField}
+                  minValue={parseDateOrNull(from) ?? undefined}
+                />
+              </div>
+            </>
+          ) : null}
+
+          <Button size="sm" tone="accent" disabled={!canApply} onClick={apply}>
+            {messages.filterBar.apply}
+          </Button>
+        </PopoverContent>
+      </Popover>
+    </div>
+  );
+});

package/src/components/table/SavedViews.tsx

@@ -0,0 +1,122 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { useMessages } from "../../i18n/useMessages.js";
+import { cn } from "../../lib/cn.js";
+import { Chip } from "../actions/Chip.js";
+
+/**
+ * Сохранённый вид: имя и СНИМОК состояния, каким его дал потребитель.
+ *
+ * Тип параметризован снимком, а не привязан к `TableState`, и это результат
+ * чтения заказчика, а не запас на будущее
+ * (ADR-0033).
+ * У известного заказчика — `features/library/useFilters.js` во фронте —
+ * состояние живёт в АДРЕСЕ и экран вовсе не таблица, а сетка карточек.
+ * Привязка к `TableState` отрезала бы единственного потребителя от компонента,
+ * написанного ради него же.
+ *
+ * Кит внутрь `state` не заглядывает и ничего в нём не понимает: хранит как
+ * непрозрачное значение и отдаёт обратно при выборе. Сравнение видов между
+ * собой, вычисление «текущий вид изменён» и сериализация — знание потребителя.
+ */
+export interface SavedView<T = unknown> {
+  /** Идентификатор вида: ключ в списке и значение для сравнения с `activeId`. */
+  id: string;
+  /** Имя вида — оно же подпись чипа. */
+  name: ReactNode;
+  /** Снимок состояния. Кит его не читает и не интерпретирует. */
+  state: T;
+}
+
+export interface SavedViewsProps<T = unknown> {
+  /** Список сохранённых видов; пустой список не рисуется вовсе. */
+  views: SavedView<T>[];
+  /**
+   * Идентификатор активного вида, который подсвечивается и объявляется нажатым.
+   *
+   * `null` и `undefined` означают «активного
+   * нет» — состояние, которое у заказчика называется «вид по умолчанию» и
+   * получается сбросом адреса.
+   *
+   * Возврат к умолчанию делается видом, который потребитель кладёт в список
+   * сам: его снимок — это пустое состояние. Своего понятия «сброс» кит не
+   * заводит, потому что не знает, что для приложения пусто.
+   */
+  activeId?: string | null;
+  /**
+   * Выбран вид. Приходит вид целиком, а не его идентификатор: применять
+   * снимок потребитель обязан одним действием.
+   */
+  onSelect: (view: SavedView<T>) => void;
+  /** Доступное имя группы. Без него берётся строка из каталога. */
+  "aria-label"?: string;
+  /** Класс контейнера группы. */
+  className?: string;
+}
+
+/**
+ * Переключатель сохранённых видов: набор именованных снимков состояния.
+ *
+ * ХРАНЕНИЯ ЗДЕСЬ НЕТ ВОВСЕ. Компонент ничего не пишет — ни в `localStorage`,
+ * ни в адрес, ни в сеть — и ни на что не подписывается. Модель та же, что у
+ * `useTableState` (ADR-0023): кит описывает форму, владеет потребитель. Выбор
+ * между адресом, локальным хранилищем и сервером остаётся приложению, а шаринг
+ * видов между пользователями — вообще бэкенд.
+ *
+ * Соблазн здесь сильнее обычного: «сохранённый вид», который ничего не
+ * сохраняет, на первый взгляд выглядит бессмыслицей. Он ею не является — кит
+ * отвечает за то, как вид ВЫГЛЯДИТ И ПЕРЕКЛЮЧАЕТСЯ, а не за то, где он лежит.
+ * Обратное означало бы, что хук, специально ничего не хранящий, обзаводится
+ * хранилищем через соседа.
+ *
+ * Выбор отдаёт весь снимок за один вызов, и это не стилистика. У заказчика
+ * состояние переносится в адрес, а последовательные записи по ключу строят
+ * адрес из одного и того же снимка текущего рендера: побеждает последняя, а
+ * правки предыдущих пропадают. Ровно так во фронте терялась нижняя граница
+ * периода при выборе диапазона поверх пресета, и ради этого там появился
+ * `setMany`. Компонент, применяющий вид по ключу за раз, воспроизвёл бы тот же
+ * дефект у каждого потребителя.
+ *
+ * АКТИВНЫЙ ВИД ОБЪЯВЛЯЕТСЯ, а не только подсвечивается: `Chip` несёт
+ * `aria-pressed`. Подсветка цветом — не сообщение для скринридера, и это тот
+ * же дефект, который чинили у `Segmented` и у переключателя тем.
+ *
+ * ЧТО ОСТАЁТСЯ У ПОТРЕБИТЕЛЯ помимо хранения: создание, переименование и
+ * удаление вида, доменные ключи внутри снимка и правила их разбора. Из
+ * прочитанного экрана в кит не приехало ничего доменного — ни отображение имён
+ * сортировки в поля бэкенда, ни ключи фильтров обоев, ни часовой пояс сервера.
+ */
+export function SavedViews<T = unknown>({
+  views,
+  activeId,
+  onSelect,
+  "aria-label": ariaLabel,
+  className,
+}: SavedViewsProps<T>) {
+  const messages = useMessages();
+
+  // Пустой список не рисуется вовсе: пустая группа объявила бы себя
+  // скринридеру, не имея внутри ничего. Тот же приём, что у `Timeline`.
+  if (views.length === 0) return null;
+
+  return (
+    <div
+      role="group"
+      aria-label={ariaLabel ?? messages.savedViews.label}
+      className={cn("flex flex-wrap items-center gap-1.5", className)}
+    >
+      {views.map((view) => (
+        <Chip
+          key={view.id}
+          selected={view.id === activeId}
+          // Весь вид целиком, а не `view.id`: потребитель обязан получить
+          // снимок и применить его одним действием (см. докстроку выше).
+          onClick={() => onSelect(view)}
+        >
+          {view.name}
+        </Chip>
+      ))}
+    </div>
+  );
+}