@olddevs/ui 0.0.0-stage → 4.0.0

package/src/lib/button.ts

@@ -0,0 +1,158 @@
+import { cn } from "./cn.js";
+import { variantClasses, type ButtonSize, type Tone, type Variant } from "./variants.js";
+
+/**
+ * Вид кнопки одной функцией — на два компонента.
+ *
+ * Вынесено из `Button` в момент появления `Menu`. Причина конкретная:
+ * `MenuTrigger` из react-aria передаёт триггеру свои пропы через `ButtonContext`
+ * (`onPress`, `aria-expanded`, `aria-haspopup`, ref), а `Button` пакета — обычный
+ * `<button>`, который этого контекста не читает и потому меню не открывает.
+ *
+ * Переписывать `Button` на react-aria нельзя: решение G спеки прямо запрещает
+ * переезд существующих примитивов — они работают и покрыты снимками. Поэтому
+ * триггер меню собран на кнопке RAC, а вид у обоих один и тот же и живёт здесь.
+ * Копипаст этой таблицы разошёлся бы: у пакета уже есть такая история с полями
+ * поиска во фронте.
+ *
+ * Строки литеральные и целиком — Tailwind сканирует исходники как текст.
+ */
+
+/**
+ * Размеры сохранены от версии во фронте — чтобы переезд не сдвинул вёрстку.
+ *
+ * `xs` пришёл позже и от заказчика: строка списка рассчитана на 32 пикселя, а
+ * самая маленькая кнопка давала 30 и растягивала строку до 42. Подпись в него
+ * влезает с трудом и не предполагается — ступень заведена под кнопку-иконку в
+ * строке, см. `iconOnly`.
+ */
+const SIZES: Record<ButtonSize, string> = {
+  xs: "h-5 gap-1 px-1.5 text-[11px]",
+  sm: "h-[30px] gap-1.5 px-2.5 text-xs",
+  md: "h-9 gap-2 px-3.5 text-[13px]",
+  lg: "h-11 gap-2.5 px-[18px] text-md",
+};
+
+/**
+ * Те же высоты, но квадрат и без горизонтальных отступов.
+ *
+ * У `xs` зона нажатия РАСШИРЕНА ПСЕВДОЭЛЕМЕНТОМ до 24 пикселей, хотя сама
+ * кнопка 20. Без этого ступень нельзя было бы выпускать: 20×20 не проходит
+ * WCAG 2.5.8 (минимальная цель — 24×24), а увеличить саму кнопку значит
+ * вернуть ту самую растянутую строку, ради которой ступень и заводилась.
+ * Псевдоэлемент разводит эти два требования: в раскладке кнопка занимает 20,
+ * пальцем и мышью ловится на 24.
+ */
+const ICON_SIZES: Record<ButtonSize, string> = {
+  xs: "relative h-5 w-5 px-0 text-[11px] before:absolute before:-inset-0.5 before:content-['']",
+  sm: "h-[30px] w-[30px] px-0 text-xs",
+  md: "h-9 w-9 px-0 text-[13px]",
+  lg: "h-11 w-11 px-0 text-md",
+};
+
+/**
+ * Кольцо спиннера под каждый размер — те же числа, что у `Spinner`.
+ *
+ * Сам `Spinner` сюда не годится, и причина не в геометрии: у него внутри
+ * `role="status"` и невидимая подпись «Загрузка», а она вошла бы в доступное
+ * имя кнопки — скринридер прочёл бы «Загрузка Сохранить». Внутри кнопки
+ * индикатор обязан быть декоративным: состояние объявляет `aria-busy`.
+ */
+export const SPINNER_SIZES: Record<ButtonSize, string> = {
+  xs: "size-3 border-[1.5px]",
+  sm: "size-3.5 border-[1.5px]",
+  md: "size-4 border-2",
+  lg: "size-5 border-2",
+};
+
+export const SPINNER_BASE =
+  "inline-block animate-spin rounded-full border-current border-t-transparent";
+
+const BASE =
+  "inline-flex cursor-pointer items-center justify-center rounded-control border font-semibold " +
+  "transition-all duration-150 " +
+  "focus-visible:outline-accent-strong focus-visible:outline-2 focus-visible:outline-offset-2 " +
+  "disabled:pointer-events-none disabled:opacity-50 " +
+  /*
+    ИКОНКА ВНУТРИ КНОПКИ НЕ ЯВЛЯЕТСЯ ЦЕЛЬЮ ПОПАДАНИЯ.
+
+    Иначе `event.target` у щелчка в иконку — сам `<svg>` или его `<path>`, а
+    не кнопка. Кнопке это не мешает: событие всплывает и она отрабатывает. А
+    вот всем, кто РАЗБИРАЕТ цель щелчка, мешает насмерть.
+
+    Нашлось на строке `EditableList` с действием: react-aria решает, не попал
+    ли щелчок во вложенный интерактивный элемент, проверкой `isTabbable` на
+    самой цели, без обхода предков. Цель — `<svg>`, он не таббабелен, и
+    действие строки срабатывало ВМЕСТЕ с кнопкой: щелчок по «удалить» в
+    списке задач заодно открывал подробности. По краю той же кнопки, где
+    целью была она сама, всё работало правильно — то есть дефект зависел от
+    того, попал ли человек в сами тридцать пикселей рисунка.
+
+    Лечится здесь, а не у потребителя, потому что это свойство кнопки: её
+    содержимое не должно подменять её собой ни для кого.
+  */
+  "[&_svg]:pointer-events-none " +
+  /*
+    ИКОНКА НЕ СЖИМАЕТСЯ. `<svg>` в кнопке — flex-элемент со `shrink: 1`, и
+    когда кнопку ужимает раскладка вокруг, flex отбирает ширину и у него: в
+    `SelectionBar` на средней ширине карандаш становился 10×18 при подписи,
+    сломанной на две строки. Высота при этом остаётся, поэтому
+    рисунок не уменьшается, а сплющивается. Подпись пусть переносится, но не
+    иконка.
+  */
+  "[&_svg]:shrink-0 " +
+  /*
+    `aria-disabled` красится ТАК ЖЕ, как родной `disabled`.
+
+    Кнопка, выключенная только атрибутом ARIA, выглядела полностью рабочей:
+    вид завязан на псевдокласс `:disabled`, а его на такой кнопке нет. Зрячий
+    пользователь мыши видел обычную кнопку с курсором-указателем, жал — и не
+    происходило ничего и не объяснялось ничего. `aria-disabled` берут там, где
+    кнопку нельзя убирать из обхода (край списка: с родным `disabled` браузер
+    снимает фокус с той самой кнопки, на которой он стоит).
+  */
+  "aria-disabled:opacity-50 aria-disabled:cursor-default";
+
+/**
+ * Размер иконки внутри кнопки каждой ступени.
+ *
+ * Словарь иконок размера не задаёт — это работа `LucideProvider` потребителя, —
+ * и без явного `size` lucide рисует 24 пикселя при толщине 2: в кнопке высотой
+ * 30 с подписью 13 пикселей такая иконка в полтора раза выше нужного. Иконки,
+ * которые кит кладёт в свои кнопки (копирование, раскрыватель `SplitButton`,
+ * переключатель `SideNav`), берут размер отсюда, чтобы следовать ступени кнопки.
+ * Числа те же, что в историях кита: 14 в компактных, 16 по умолчанию.
+ */
+export const BUTTON_ICON_SIZE: Record<ButtonSize, number> = { xs: 14, sm: 14, md: 16, lg: 18 };
+
+export interface ButtonLookOptions {
+  /** Подача: `solid`, `soft`, `outline` или `ghost` из словаря кита. По умолчанию `soft`. */
+  variant?: Variant;
+  /** Тон: цветовая роль кнопки из словаря кита. По умолчанию `neutral`. */
+  tone?: Tone;
+  /** Размер кнопки: `xs`, `sm`, `md` или `lg`. По умолчанию `md`. */
+  size?: ButtonSize;
+  /** Только иконка: квадрат без горизонтальных отступов, подпись не показывается. Нужно доступное имя. */
+  iconOnly?: boolean;
+  /** Нажатое состояние: кнопка подаётся как `soft` своего тона с тенью, какой бы ни был `variant`. */
+  selected?: boolean;
+}
+
+export function buttonClasses({
+  variant = "soft",
+  tone = "neutral",
+  size = "md",
+  iconOnly = false,
+  selected = false,
+}: ButtonLookOptions): string {
+  return cn(
+    BASE,
+    iconOnly ? ICON_SIZES[size] : SIZES[size],
+    // Нажатое состояние подаётся как `soft` того же тона независимо от варианта:
+    // у `ghost` и `outline` своей заливки нет, а нажатость обязана быть видна.
+    // Тень отделяет её от простого hover.
+    selected
+      ? cn(variantClasses("soft", tone), "shadow-[var(--shadow-1)]")
+      : variantClasses(variant, tone)
+  );
+}

package/src/lib/choice-card.ts

@@ -0,0 +1,79 @@
+import type { Tone } from "./variants.js";
+
+/**
+ * Вид набора вариантов выбора.
+ *
+ * Имя оси — `appearance`, а не `variant`: `variant` в ките уже значит
+ * solid/soft/outline/ghost (подачу тона), а здесь меняется не подача, а сама
+ * форма варианта — строка с кружком или карточка. Словарь ADR-0036 имени не
+ * занимает и не запрещает: в категории «Оформление» оно новое по смыслу, а
+ * новый смысл получает новое имя.
+ */
+export type ChoiceAppearance = "default" | "card";
+
+/**
+ * Рамка выбранной карточки по тону.
+ *
+ * Свой словарь, а не `TONE_TOKENS[tone].border`: у `neutral` там `border-line` —
+ * нейтральная рамка-разделитель, которую гейт контраста не меряет намеренно
+ * (она не несёт смысла). Выбранная карточка рамкой СООБЩАЕТ состояние, то есть
+ * это признак по WCAG 1.4.11 с порогом 3:1, и для `neutral` берётся `fg-3`.
+ * Остальные тона — те же `*-strong`, что и у рамок кита.
+ *
+ * Те же значения, что у `STATE_BORDER` в `variants.ts` (рамка отмеченной
+ * коробки флажка и включённого `Toggle`): рамка карточки и рамка коробки внутри
+ * неё — один признак одного цвета. Словарь не ссылается на тот: скрипт гейта
+ * грузит `choice-card.ts` напрямую через Node, а он не сопоставляет `.js` с
+ * `.ts` — рантайм-импорт отсюда его роняет. Гейт меряет оба словаря.
+ *
+ * Литеральные строки целиком: Tailwind сканирует исходники как текст.
+ * `scripts/contrast.mjs` читает этот словарь и меряет каждую запись против
+ * подложек и против самой карточки — `bg-2`.
+ */
+export const CHOICE_CARD_SELECTED_BORDER: Record<Tone, string> = {
+  neutral: "border-fg-3",
+  accent: "border-accent-strong",
+  success: "border-success-strong",
+  warning: "border-warning-strong",
+  danger: "border-danger-strong",
+};
+
+/** Рамка карточки, пока ничего не выбрано. Такая же нейтральная, как у полей. */
+export const CHOICE_CARD_IDLE_BORDER = "border-line";
+
+/** Рамка карточки с ошибкой — `danger` независимо от тона набора. */
+export const CHOICE_CARD_INVALID_BORDER = "border-danger-strong";
+
+/**
+ * Каркас карточки: рамка и подложка на `RadioField`/`CheckboxField`. Отступа у
+ * каркаса нет — его держит метка (см. `CHOICE_CARD_LABEL`).
+ */
+export const CHOICE_CARD_BASE = "flex flex-col rounded-lg border bg-bg-2 transition-colors";
+
+/** Раскладка карточки в строке с переносом: растёт, но не уезжает в полосу. */
+export const CHOICE_CARD_ROW = "max-w-xs flex-1 basis-48";
+
+/**
+ * Метка карточки — область нажатия на всю карточку.
+ *
+ * ВСЯ КАРТОЧКА — ЭТО МЕТКА, вместе с описанием. Метка накрывает рамку (`-m-px`
+ * и отступ на пиксель больше), поэтому щелчок в любую точку карточки — щелчок
+ * по родному радио или флажку. Первый вариант растягивал на карточку
+ * псевдоэлемент метки, а описание оставлял соседом; он работал мышью, но
+ * псевдоэлемент перехватывает указатель у всего содержимого, и браузерные
+ * проверки (Playwright) не могли щёлкнуть по описанию: «метка перехватывает
+ * указатель».
+ *
+ * Описание внутри метки не попадает в доступное имя: оно скрыто от
+ * вспомогательных технологий (`aria-hidden`), а читается через
+ * `aria-describedby`, которым его связывает react-aria, — ссылка по
+ * идентификатору работает и на скрытый элемент.
+ */
+export const CHOICE_CARD_LABEL =
+  "-m-px flex cursor-pointer items-start gap-3 rounded-lg p-[13px] disabled:cursor-default";
+
+/** Кольцо фокуса на карточке, а не на кружке: ориентир клавиатуры — вся карточка. */
+export const CHOICE_CARD_FOCUS_RING = "ring-accent-strong ring-offset-bg-1 ring-2 ring-offset-1";
+
+/** Слот иконки: декоративный, поэтому вне имени и фиксированного размера. */
+export const CHOICE_CARD_ICON = "text-fg-1 mt-0.5 flex size-5 shrink-0 items-center justify-center";

package/src/lib/clamp.ts

@@ -0,0 +1,18 @@
+/**
+ * Зажать число между границами.
+ *
+ * Вынесено, когда выражение написали четвёртый раз: `Pagination`, `Tabs`,
+ * `SplitPanel` и `Rating`. Функция тривиальная, и ценность не в экономии
+ * строк — в том, что перевёрнутый диапазон везде обрабатывается одинаково.
+ *
+ * При `min > max` возвращается `max`: единственный вариант, при котором
+ * результат остаётся внутри объявленного верхнего предела. Компоненту, которому
+ * важно не отдать наружу невалидный диапазон, границы надо приводить до вызова
+ * — так делает `SplitPanel`.
+ *
+ * `@internal` — наружу из пакета не экспортируется: это утилита кита, а не
+ * часть его public API.
+ */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}

package/src/lib/cn.ts

@@ -0,0 +1,48 @@
+import { clsx, type ClassValue } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+
+/**
+ * Слияние с разрешением конфликтов, знающее про шкалу кита.
+ *
+ * Штатный `twMerge` раскладывает `text-*` по группам, глядя на суффикс:
+ * t-shirt-размер (`sm`, `md`, `2xl`) или произвольная длина — это размер
+ * шрифта, всё остальное — цвет. Ступень `caption` под это правило не подходит,
+ * и `text-caption` попадал в группу ЦВЕТА, конфликтуя с `text-fg-2`:
+ *
+ *     twMerge("text-caption", "text-fg-2") === "text-fg-2"   // размер съеден
+ *     twMerge("text-fg-2", "text-caption") === "text-caption" // цвет съеден
+ *
+ * Молча, без ошибки сборки, и результат зависел от порядка аргументов. Так
+ * `Text size="caption"` рисовался унаследованным кеглем, а `Kbd` терял цвет.
+ *
+ * Остальные шесть ступеней (`xs`, `sm`, `md`, `lg`, `xl`, `2xl`) — законные
+ * t-shirt-размеры, и их `twMerge` разбирает сам.
+ *
+ * `rounded-control` — вторая такая ступень и ровно тот же случай. Радиус
+ * контролов назван по роли, а не по размеру (см. `--r-control` в styles.css),
+ * поэтому под t-shirt-правило не подходит: без регистрации ниже `twMerge` не
+ * узнаёт в нём радиус вовсе и перестаёт разрешать конфликт —
+ * `cn("rounded-control", "rounded-full")` вернул бы ОБА класса, и выиграл бы
+ * тот, что ниже в CSS, а не тот, что передан последним.
+ */
+const merge = extendTailwindMerge({
+  extend: {
+    classGroups: {
+      "font-size": [{ text: ["caption"] }],
+      rounded: [{ rounded: ["control"] }],
+    },
+  },
+});
+
+/**
+ * Слияние Tailwind-классов с разрешением конфликтов: последний выигрывает.
+ * Перенесено из `src/lib/utils.js` фронта — там остаются прикладные утилиты
+ * (formatFileSize, maskTime, normalizeTime, pluralize), они пакету не нужны.
+ *
+ * Экспортируется наружу намеренно: у потребителя свой `cn` на голом `twMerge`,
+ * и `cn("text-caption", "text-fg-2")` там сломается ровно так же. Пары
+ * «ступень шкалы + цвет» собирайте этим.
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return merge(clsx(inputs));
+}

package/src/lib/date.ts

@@ -0,0 +1,87 @@
+import { type CalendarDate, parseDate } from "@internationalized/date";
+import type { DateValue } from "react-aria-components";
+
+/**
+ * Разбор ISO-даты, не бросающий на неразбираемом значении.
+ *
+ * `parseDate` бросает ДВА разных исключения, и оба достижимы из адреса:
+ * `parseDate("ерунда")` — это `Error: Invalid ISO 8601 date string`, а
+ * `parseDate("2026-02-29")` — `RangeError: Value out of range`, потому что 2026
+ * год не високосный. Второе особенно коварно: строка выглядит правильной, и
+ * ссылка с ней живёт до первого не-високосного года.
+ *
+ * Вынесено, когда выяснилось, что защита стоит в одном месте из трёх.
+ * `DateRangePicker` заворачивал разбор в `try/catch` и в комментарии
+ * утверждал, что соседний `DatePicker` на том же вводе показывает
+ * плейсхолдер, — а `DatePicker` разбирал значение выражением в JSX-потомке,
+ * то есть на каждом рендере и без всякой защиты. Комментарий описывал
+ * инвариант, которого не было: ровно так и разъезжаются три копии одной мысли.
+ *
+ * `@internal` — наружу не экспортируется: у потребителя есть `parseDate`
+ * библиотеки, и решать за него, что делать с неразбираемым значением, кит не
+ * должен.
+ */
+export function parseDateOrNull(value: string | null | undefined): CalendarDate | null {
+  if (!value) return null;
+  try {
+    return parseDate(value);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Дата в любом из двух видов, которые принимают календари кита: ISO-строка
+ * `ГГГГ-ММ-ДД` или объект `@internationalized/date`.
+ *
+ * Строка нужна потребителю, у которого этого пакета нет: `@internationalized/date`
+ * не входит в публичные точки входа кита, и ради одной границы `minValue`
+ * тянуть его в зависимости приложения незачем. Объект остаётся — им уже
+ * пользуются.
+ */
+export type DateInput = DateValue | string;
+
+/**
+ * Приводит `DateInput` к объекту календаря.
+ *
+ * `undefined` и `null` проходят насквозь — у react-aria это разные вещи
+ * (`value={undefined}` — неуправляемое поле, `value={null}` — управляемое
+ * пустое), и стирать различие здесь нельзя. Неразбираемая строка даёт `null`:
+ * «значения нет», а не исключение, как у `DatePicker` с мусором из адреса.
+ */
+export function toDateValue(value: DateInput | null | undefined): DateValue | null | undefined {
+  if (value === undefined || value === null) return value;
+  return typeof value === "string" ? parseDateOrNull(value) : value;
+}
+
+/**
+ * То же для границы и фокуса: пустое и неразбираемое — одинаково «не задано».
+ * Граница из мусора не должна превращаться в `null`: react-aria читает `null`
+ * как ошибку типа, а не как отсутствие.
+ */
+export function toDateBound(value: DateInput | undefined): DateValue | undefined {
+  return toDateValue(value) ?? undefined;
+}
+
+/** Календарный день объекта календаря в виде ISO-строки `ГГГГ-ММ-ДД`. */
+export function toIsoDate(value: DateValue): string {
+  // `toString()` у `CalendarDateTime` и `ZonedDateTime` несёт время и зону;
+  // наружу идёт день, как у `DatePicker`.
+  return value.toString().slice(0, 10);
+}
+
+/** Диапазон в любом из двух видов: пара ISO-строк или `{ start, end }` объектов. */
+export interface DateRangeInput {
+  start: DateInput;
+  end: DateInput;
+}
+
+/** Пара границ диапазона в виде объектов календаря; половина диапазона — не диапазон. */
+export function toRangeValue(
+  value: DateRangeInput | null | undefined
+): { start: DateValue; end: DateValue } | null | undefined {
+  if (value === undefined || value === null) return value;
+  const start = toDateValue(value.start);
+  const end = toDateValue(value.end);
+  return start && end ? { start, end } : null;
+}

package/src/lib/dev-warn.ts

@@ -0,0 +1,82 @@
+// Тип `process` объявлен здесь же, а не берётся из `@types/node`: сборка пакета
+// Node-типов не подключает, а тянуть их ради одного поля незачем.
+declare const process: { env: { NODE_ENV?: string } };
+
+/**
+ * Предупреждение потребителю в режиме разработки — один раз на сообщение.
+ *
+ * ЗАЧЕМ. Типы ловят нарушение контракта у потребителя на TypeScript, а у
+ * потребителя на JS — нет: два взаимоисключающих пропа приходят молча, и один
+ * из них молча проигрывает. Предупреждение закрывает именно эту дыру. Правила,
+ * когда оно уместно, — в `docs/conventions.md`, раздел «Предупреждения в режиме
+ * разработки».
+ *
+ * КАК ОПРЕДЕЛЯЕТСЯ РЕЖИМ. Пакет выходит голым `tsc` без бандлера, поэтому
+ * значение `process.env.NODE_ENV` в `dist` не вшито — его подставляет сборка
+ * потребителя (Vite, Next, webpack, esbuild с `define`), и в продакшн-сборке
+ * ветка с предупреждением вырезается как мёртвая. Без бандлера (Node, браузер с
+ * нативными модулями) `process` не определён: ссылка на него бросает
+ * `ReferenceError`, и это тоже «тихо». Поэтому `try/catch`, а не
+ * `typeof process !== "undefined"`: той проверки бандлер не заменяет, и в
+ * браузерной сборке Vite, где `process` нет, предупреждение не сработало бы
+ * никогда — даже в разработке. Для `try/catch` подстановка вида
+ * `"development" !== "production"` остаётся константой, а не вызовом.
+ *
+ * Читается при каждом вызове, а не при загрузке модуля: тесты подменяют
+ * значение через `vi.stubEnv`.
+ *
+ * `@internal` — наружу из пакета не экспортируется.
+ */
+function isDevelopment(): boolean {
+  try {
+    return process.env.NODE_ENV !== "production";
+  } catch {
+    return false;
+  }
+}
+
+/** Сообщения, которые уже были показаны. Ключ — сам текст. */
+const shown = new Set<string>();
+
+/**
+ * Написать в консоль предупреждение — только в разработке и только впервые.
+ *
+ * «Один раз» нужно потому, что вызов стоит в теле рендера: строка списка
+ * перерисовывается сотни раз, а `StrictMode` вызывает рендер дважды. Ключ —
+ * текст сообщения, поэтому текст не должен содержать меняющихся данных: два
+ * разных значения дали бы два предупреждения об одном и том же.
+ *
+ * Текст — по-английски (ADR-0034: консоль — адресат вне кита) и называет, что
+ * передано, что победило и как исправить.
+ */
+export function devWarn(message: string): void {
+  if (!isDevelopment() || shown.has(message)) return;
+  shown.add(message);
+  // Единственное место кита, где `console` законен: предупреждение и есть вывод.
+  // eslint-disable-next-line no-console
+  console.warn(message);
+}
+
+/** Забыть показанное. Нужно только тестам: состояние живёт на уровне модуля. */
+export function resetDevWarnings(): void {
+  shown.clear();
+}
+
+/**
+ * Ошибка потребителя в консоль — только в разработке и только впервые, как
+ * `devWarn`. Для того, что ломает компонент целиком (набор Инструментов
+ * Редактора собран с ошибкой): само поле показывает её пользователю строкой
+ * каталога, а причина нужна разработчику.
+ *
+ * `cause` — пойманное исключение: оно идёт в консоль вторым аргументом, а не в
+ * текст. Ключ «один раз» — текст, и сообщение исключения в нём сделало бы
+ * каждую ошибку новой; консоль же покажет у объекта `Error` и стек.
+ */
+export function devError(message: string, cause?: unknown): void {
+  if (!isDevelopment() || shown.has(message)) return;
+  shown.add(message);
+  // eslint-disable-next-line no-console
+  if (cause === undefined) console.error(message);
+  // eslint-disable-next-line no-console
+  else console.error(message, cause);
+}

package/src/lib/empty.ts

@@ -0,0 +1,43 @@
+import type { ReactNode } from "react";
+
+/**
+ * Пустота, которую `== null` не видит.
+ *
+ * Один и тот же дефект кит ловил уже пять раз, и каждый раз чинил ОДНУ точку, а
+ * не правило: подпись `""` не считалась отсутствующей (`Segmented`, потом
+ * `CopyButton`, потом `ToggleGroup`), пустой массив детей не считался пустым
+ * списком (`NotificationList`), `NaN` проходил проверку на «значение задано»
+ * (`Progress`). Проверка `== null` ловит ровно `null` и `undefined` — а пустым
+ * в разметке бывает ещё и `""`, и `[]`, и `false`, и `NaN`.
+ *
+ * Отсюда общее место и тест-семейство рядом с ним: починка одной кнопки
+ * воспроизводит причину, починка предиката — нет.
+ */
+
+/**
+ * Есть ли что показать: подпись, имя, содержимое ячейки.
+ *
+ * `false` тоже пустой — это результат `{flag && <Icon/>}`, самой частой идиомы
+ * условного рендера. Ноль НЕ пустой: `0` — законное значение счётчика.
+ *
+ * Для пропа типа `string` предикат не нужен: там `value || fallback` выражает
+ * то же правило и не спорит с сужением типов. `hasContent` — про `ReactNode`,
+ * где пустыми бывают ещё `false` и массив.
+ */
+export function hasContent(value: ReactNode): boolean {
+  if (value == null || value === false || value === "") return false;
+  if (Array.isArray(value)) return value.some(hasContent);
+  return true;
+}
+
+/**
+ * Число, которое можно показать и объявить.
+ *
+ * `NaN` и бесконечности отсекаются вместе с `null`: они приходят из арифметики
+ * потребителя (`loaded / total` при нулевом `total`) и до волны 26 проходили
+ * насквозь — `width: NaN%` растягивал полосу прогресса на всю ширину, а
+ * скринридер читал «NaN процентов».
+ */
+export function isShowableNumber(value: number | null | undefined): value is number {
+  return value != null && Number.isFinite(value);
+}

package/src/lib/field.ts

@@ -0,0 +1,125 @@
+/**
+ * Оболочка поля ввода: рамка, фокус, выключенное состояние.
+ *
+ * Вынесено из `TextControl` в момент появления `NumberInput` — второго
+ * компонента с такой же оболочкой. Копипаст этих строк разошёлся бы: во фронте
+ * до пакета так и вышло — пять рукописных полей поиска красили фокус в `--tg`,
+ * тогда как обычные поля через `TextControl` — в `--accent-strong`, и увидеть
+ * расхождение можно было, только открыв пять файлов рядом.
+ *
+ * ВАЖНО про склейку `+` ниже — она безопасна, и это не то же самое, что
+ * запрещено в `variants.ts`. Tailwind сканирует исходники как ТЕКСТ и ищет в
+ * нём кандидатов: каждое имя класса здесь присутствует в файле целиком, внутри
+ * литерала, а `+` только соединяет готовые строки. Запрещено другое — собирать
+ * само ИМЯ класса (`` `hover:${t.bg}` ``): такого текста в файле нет, и в CSS
+ * он не попадёт молча, без ошибки сборки. Сторожит `tests/class-coverage.test.ts`.
+ */
+
+import { INVALID_BORDER_CLASS } from "./variants.js";
+
+/**
+ * Рамка живёт на оболочке, а не на самом поле. Разделение не косметическое:
+ * оно позволяет положить внутрь иконку или счётчик, не воюя с браузерным
+ * оформлением поля.
+ *
+ * Подсветка фокуса — через `focus-within`, и цвет берётся из `--accent-strong`,
+ * а не из `--accent`: индикатор фокуса это не-текст под порогом 3:1, а
+ * `--accent` рассчитан на белый текст поверх.
+ *
+ * Выключенное состояние гасит ОБОЛОЧКУ, а не поле: `disabled:opacity-50` на
+ * самом поле приглушил бы только текст, оставив рамку такой же яркой, как у
+ * соседнего рабочего поля.
+ *
+ * Селектор адресует именно поле (`has-[input:disabled]`, `has-[textarea:disabled]`),
+ * а не любого выключенного потомка (`has-[:disabled]`, как было до появления
+ * `NumberInput`). Разница не теоретическая: в оболочке числового поля стоят ещё
+ * две кнопки ступеней, и на границе `min`/`max` одна из них законно выключена —
+ * прежний селектор гасил из-за неё всё поле вместе со значением. Поймал аудит
+ * axe: унаследованная прозрачность роняла контраст значения с 4.5 до 4.07.
+ *
+ * НЕВАЛИДНОСТЬ КРАСИТ ТУ ЖЕ ОБОЛОЧКУ, И ИСТОЧНИКОВ У НЕЁ ДВА. У контролов
+ * react-aria признак висит атрибутом `data-invalid` на самой оболочке — его
+ * ловит вариант `invalid:` из плагина. У полей на нативных `input`/`textarea`
+ * оболочка — обычный `div`, на котором ловить нечего: там признак живёт на
+ * самом поле в `aria-invalid`, и оболочка дотягивается до него через `has-`.
+ * Одного селектора не хватало: до этой правки `INVALID_BORDER_CLASS` был
+ * объявлен, но применён ровно в одном месте — вручную в `NumberInput`, — и
+ * `TextControl`, `Combobox`, `TagInput` и построенный на первом `SearchControl`
+ * показать ошибку не умели вовсе.
+ *
+ * Порядок в строке значим: `invalid:` стоит ПОСЛЕ `focus-within:`, поэтому у
+ * поля в фокусе с ошибкой рамка остаётся красной. Так вело себя числовое поле
+ * до переноса правила сюда, и менять это заодно с переносом не стоит.
+ */
+export const FIELD_SHELL_CLASS =
+  "border-line bg-bg-2 rounded-control border px-3 shadow-[var(--shadow-1)] " +
+  "transition-[border-color,box-shadow] duration-150 " +
+  "focus-within:border-accent-strong focus-within:ring-[3px] focus-within:ring-[color:var(--focus-ring)] " +
+  INVALID_BORDER_CLASS +
+  " has-[input[aria-invalid=true]]:border-danger-strong " +
+  "has-[textarea[aria-invalid=true]]:border-danger-strong " +
+  "has-[input:disabled]:cursor-not-allowed has-[input:disabled]:opacity-50 " +
+  "has-[textarea:disabled]:cursor-not-allowed has-[textarea:disabled]:opacity-50";
+
+/**
+ * Само поле обнулено полностью: без этого Safari и Chrome рисуют разное.
+ * Глобальное правило `:focus-visible` в `styles.css` гасится атрибутом
+ * `data-disable-focus-ring` на элементе — контур вокруг поля здесь лишний,
+ * подсветку даёт оболочка.
+ *
+ * `leading-5` — не косметика, а объявленная высота строчного бокса контрола,
+ * и она же держит общую высоту в 42px: `20 + 2×10 отступа + 2 рамки`. Без неё
+ * бокс получался из унаследованного множителя `1.5` при `text-[13px]`, то есть
+ * 19.5px, а поле — 41.5px. Число случайное, и совпадать с ним чему-то ещё
+ * нечем: триггер `Select` с картинкой в 22px давал 44px и расходился с
+ * соседним полем на пару пикселей. Теперь высота задана, а не выведена, и
+ * `Select` пришёл к тем же 42 — тем же `leading-5` на триггере.
+ *
+ * Оговорка: объявление живёт, пока потребитель не пришлёт свой размер шрифта.
+ * `cn` — это `twMerge`, и чужой `text-*` в `className` вытесняет пару
+ * `text-[13px] leading-5` целиком. Со ступенями шкалы это безвредно — у них
+ * строчный бокс задан свой (`text-sm` — те же 13/20), — а вот произвольный
+ * `text-[15px]` вернёт высоту к выведенной из множителя.
+ */
+export const FIELD_INPUT_CLASS =
+  "text-fg-0 w-full [appearance:none] border-0 bg-transparent px-0 py-[10px] text-[13px] leading-5 " +
+  "shadow-none outline-none [-webkit-tap-highlight-color:transparent] " +
+  "focus:border-0 focus:ring-0 focus:outline-none focus-visible:ring-0 focus-visible:outline-none " +
+  "disabled:cursor-not-allowed";
+
+/**
+ * Компактная ступень поля: 36 пикселей вместо 42.
+ *
+ * ОДНО ЗНАЧЕНИЕ ВЕРТИКАЛЬНОГО ОТСТУПА, и больше ничего: рамка, скругление,
+ * тень, шрифт и строчный бокс те же. `20 + 2×7 + 2 = 36` — ровно рост
+ * `Button size="md"` и пилюли-триггера `Select`, то есть число, которое кит уже
+ * дважды выбрал сам. В одной строке панели управления поле до этого выпадало из
+ * ряда в одиночку.
+ *
+ * ЗАЧЕМ СТУПЕНЬ, ЕСЛИ ВЫСОТА И ТАК ДОСТИЖИМА. Достижима: `className` уходит в
+ * конец `cn(FIELD_INPUT_CLASS, …, className)`, а `cn` — это `twMerge`, и `py-0`
+ * снаружи вытесняет `py-[10px]`. Именно так и сделано у двух потребителей — с
+ * двумя разными числами (34 и 36) и двумя разными шрифтами. Довод тот же, что у
+ * самого `SearchControl`: пять рукописных полей поиска во фронте красили фокус
+ * не тем цветом, и увидеть это можно было, только открыв пять файлов рядом.
+ *
+ * Зона нажатия остаётся выше порога: 36 — в полтора раза больше минимальной
+ * цели WCAG 2.5.8.
+ */
+export const FIELD_INPUT_COMPACT_CLASS = "py-[7px]";
+
+/**
+ * Кнопка очистки внутри оболочки поля.
+ *
+ * Вынесена, когда третьим её написал `TreeSelect`, символ в символ повторив
+ * `Select`. Разъехались бы они молча: у обоих это крестик в углу поля, и заметил
+ * бы расхождение только тот, кто поставит их рядом.
+ *
+ * `relative` и `z-10` не косметика: у триггера поля растянутый псевдоэлемент
+ * зоны попадания, и без подъёма клик по крестику открывал бы список вместо
+ * очистки.
+ */
+export const FIELD_CLEAR_CLASS =
+  "bg-bg-3 text-fg-2 hover:text-fg-0 focus-visible:outline-accent-strong relative z-10 flex h-4 w-4 " +
+  "shrink-0 cursor-pointer items-center justify-center rounded-full transition-colors " +
+  "focus-visible:outline-2 focus-visible:outline-offset-2";