@olddevs/ui 0.0.0-stage → 4.0.1

package/src/components/inputs/CheckboxCard.tsx

@@ -0,0 +1,132 @@
+"use client";
+
+import { createContext, forwardRef, useContext } from "react";
+import { CheckboxButton, CheckboxField } from "react-aria-components";
+import { CheckIcon, MinusIcon } from "../../icons.js";
+import { cn } from "../../lib/cn.js";
+import {
+  CHOICE_CARD_BASE,
+  CHOICE_CARD_FOCUS_RING,
+  CHOICE_CARD_IDLE_BORDER,
+  CHOICE_CARD_INVALID_BORDER,
+  CHOICE_CARD_LABEL,
+  CHOICE_CARD_ROW,
+  CHOICE_CARD_SELECTED_BORDER,
+} from "../../lib/choice-card.js";
+import { STATE_BORDER, TONE_TOKENS } from "../../lib/variants.js";
+import { ChoiceCardBody } from "./ChoiceCardBody.js";
+import { CHECKBOX_SIZES, type CheckboxCardComponent } from "./Checkbox.js";
+
+/**
+ * Раскладка набора карточек. Свой контекст, а не поле контекста `Checkbox`:
+ * см. `CheckboxCardComponent`.
+ */
+export const CheckboxCardLayoutContext = createContext<"vertical" | "horizontal">("vertical");
+
+/**
+ * Флажок-карточка: то, что `CheckboxGroup appearance="card"` рисует вместо
+ * строки с коробкой.
+ *
+ * Не экспортируется из пакета и НЕ импортируется из `Checkbox.tsx`: его кладёт
+ * в контекст `CheckboxGroup`, и только тот, кто использует группу, платит за
+ * этот код в бандле (см. `CheckboxGroupStyleContext`). Тон приходит уже
+ * решённым — тон набора или собственный.
+ */
+export const CheckboxCard: CheckboxCardComponent = forwardRef<
+  HTMLDivElement,
+  Parameters<CheckboxCardComponent>[0]
+>(function CheckboxCard(
+  {
+    checked,
+    defaultChecked,
+    indeterminate,
+    onCheckedChange,
+    children,
+    label,
+    description,
+    icon,
+    size = "md",
+    tone,
+    disabled,
+    invalid,
+    name,
+    value,
+    slot,
+    className,
+  },
+  ref
+) {
+  const orientation = useContext(CheckboxCardLayoutContext);
+  const t = TONE_TOKENS[tone];
+  const s = CHECKBOX_SIZES[size];
+
+  return (
+    <CheckboxField
+      ref={ref}
+      slot={slot}
+      isSelected={checked}
+      defaultSelected={defaultChecked}
+      isIndeterminate={indeterminate}
+      onChange={onCheckedChange}
+      isDisabled={disabled}
+      isInvalid={invalid}
+      name={name}
+      value={value}
+      aria-label={label}
+      className={({ isSelected, isIndeterminate, isInvalid, isDisabled }) =>
+        cn(
+          CHOICE_CARD_BASE,
+          isInvalid
+            ? CHOICE_CARD_INVALID_BORDER
+            : isSelected || isIndeterminate
+              ? CHOICE_CARD_SELECTED_BORDER[tone]
+              : CHOICE_CARD_IDLE_BORDER,
+          isDisabled ? "opacity-50" : "hover:bg-bg-3",
+          orientation === "horizontal" && CHOICE_CARD_ROW,
+          className
+        )
+      }
+    >
+      {/*
+        Зона нажатия здесь — вся карточка: метка накрывает рамку (см.
+        `CHOICE_CARD_LABEL`). Двух полосок обычного флажка тут нет: карточка и
+        сама выше 24 пикселей.
+      */}
+      <CheckboxButton
+        className={({ isFocusVisible }) =>
+          cn(CHOICE_CARD_LABEL, isFocusVisible && CHOICE_CARD_FOCUS_RING)
+        }
+      >
+        {({ isSelected, isIndeterminate, isInvalid }) => {
+          const on = isSelected || isIndeterminate;
+          return (
+            <ChoiceCardBody
+              icon={icon}
+              label={children}
+              labelClassName={s.label}
+              description={description}
+              indicator={
+                <span
+                  data-indicator=""
+                  className={cn(
+                    "mt-0.5 flex shrink-0 items-center justify-center border transition-colors",
+                    s.box,
+                    // Рамка отмеченной коробки — см. `STATE_BORDER` и `Checkbox`.
+                    on ? cn(t.solid, STATE_BORDER[tone]) : "border-line bg-bg-2",
+                    isInvalid && "border-danger-strong"
+                  )}
+                >
+                  {isIndeterminate ? (
+                    <MinusIcon size={s.icon} strokeWidth={3} />
+                  ) : isSelected ? (
+                    <CheckIcon size={s.icon} strokeWidth={3} />
+                  ) : null}
+                </span>
+              }
+            />
+          );
+        }}
+      </CheckboxButton>
+    </CheckboxField>
+  );
+});

package/src/components/inputs/CheckboxGroup.tsx

@@ -0,0 +1,140 @@
+"use client";
+
+import { forwardRef, useMemo, type ReactNode } from "react";
+import { CheckboxGroup as AriaCheckboxGroup, FieldError, Label, Text } from "react-aria-components";
+import { cn } from "../../lib/cn.js";
+import type { ChoiceAppearance } from "../../lib/choice-card.js";
+import type { Tone } from "../../lib/variants.js";
+import { CheckboxGroupStyleContext } from "./Checkbox.js";
+import { CheckboxCard, CheckboxCardLayoutContext } from "./CheckboxCard.js";
+
+export interface CheckboxGroupProps {
+  /** Отмеченные пункты: массив `value` отмеченных флажков группы. */
+  value: string[];
+  /** Вызывается при смене набора и получает новый массив значений. */
+  onChange: (value: string[]) => void;
+  /** Подпись всей группы. Обязательна: набор флажков без общего вопроса нечитаем. */
+  label: ReactNode;
+  /** Пояснение под подписью. */
+  description?: ReactNode;
+  /** Сообщение об ошибке. Заменяет `description`, когда задано. */
+  errorMessage?: ReactNode;
+  /** Раскладка флажков. Горизонтальная — для двух-трёх коротких подписей. */
+  orientation?: "vertical" | "horizontal";
+  /**
+   * Выключает всю группу целиком: недоступен каждый её пункт.
+   *
+   * Выключает всю группу целиком. Перекрывает `disabled` отдельных флажков, а
+   * не складывается с ним: недоступна вся группа — недоступен каждый её пункт,
+   * и обратного прочтения тут быть не может.
+   */
+  disabled?: boolean;
+  /** Помечает группу обязательной для заполнения (передаётся в `react-aria-components`). */
+  isRequired?: boolean;
+  /**
+   * Тон отмеченных флажков набора — один на всех.
+   *
+   * Цвет отмеченных флажков набора (в карточках — ещё и рамки отмеченной
+   * карточки). Один на весь набор и приходит флажкам контекстом, как у
+   * `RadioGroup`: тон `Checkbox` внутри группы с этим пропом игнорируется —
+   * набор не может разъехаться по виду. Не задан — каждый флажок красится своим
+   * `tone`, как и вне группы. Неотмеченные всегда нейтральны.
+   */
+  tone?: Tone;
+  /**
+   * Вид группы: `default` — строки с коробкой, `card` — карточки.
+   *
+   * Вид группы: `default` — строки с коробкой, `card` — карточки с подписью,
+   * описанием и необязательной иконкой. Живёт у группы и приходит флажкам
+   * контекстом. Не `variant`: тот в ките уже значит подачу тона.
+   */
+  appearance?: ChoiceAppearance;
+  /** `<Checkbox value="…">` — по одному на пункт. */
+  children?: ReactNode;
+  /** Классы на корневой элемент группы. */
+  className?: string;
+}
+
+/**
+ * Группа флажков.
+ *
+ * СОБИРАЕТСЯ ИЗ `children`, А НЕ ИЗ МАССИВА `items` — и это осознанное
+ * расхождение с `Select` и `Segmented`.
+ *
+ * Те два рисуют однородные строки: у пункта есть подпись, иногда картинка и
+ * счётчик, и всё это описывается объектом. У флажка в группе бывает своё
+ * пояснение, свой `disabled`, своя иконка и своя вложенная разметка подписи —
+ * описать это объектом можно только заведя второй язык разметки рядом с JSX,
+ * который уже есть.
+ *
+ * Значение группы — массив, а состояние отдельного флажка внутри неё
+ * определяется вхождением его `value` в этот массив: `checked` у детей группы
+ * не задаётся вовсе. Это тот же принцип, по которому `RadioGroup` держит
+ * значение у группы, а не у каждой кнопки.
+ */
+export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(function CheckboxGroup(
+  {
+    value,
+    onChange,
+    label,
+    description,
+    errorMessage,
+    orientation = "vertical",
+    disabled,
+    isRequired,
+    tone,
+    appearance = "default",
+    children,
+    className,
+  },
+  ref
+) {
+  // Значение контекста не пересоздаётся на каждый рендер: иначе каждый флажок
+  // набора перерисовывался бы от любого рендера группы.
+  const style = useMemo(
+    () => ({ tone, Card: appearance === "card" ? CheckboxCard : undefined }),
+    [tone, appearance]
+  );
+  return (
+    <AriaCheckboxGroup
+      ref={ref}
+      value={value}
+      onChange={onChange}
+      isDisabled={disabled}
+      isRequired={isRequired}
+      isInvalid={errorMessage != null || undefined}
+      className={cn("flex flex-col gap-1.5", className)}
+    >
+      <Label className="text-fg-2 text-[11px] font-bold tracking-wide uppercase">{label}</Label>
+      <div
+        className={cn(
+          "flex",
+          appearance === "card" ? "gap-3" : "gap-2",
+          orientation === "vertical"
+            ? "flex-col"
+            : cn("flex-row flex-wrap", appearance === "card" ? "items-stretch" : "items-center")
+        )}
+      >
+        <CheckboxGroupStyleContext.Provider value={style}>
+          <CheckboxCardLayoutContext.Provider value={orientation}>
+            {children}
+          </CheckboxCardLayoutContext.Provider>
+        </CheckboxGroupStyleContext.Provider>
+      </div>
+      {/*
+          Ошибка ВЫТЕСНЯЕТ пояснение, а не встаёт под ним: две строки под
+          группой, одна из которых противоречит другой, — источник шума.
+          То же правило, что у `FormField`.
+        */}
+      {errorMessage != null ? (
+        <FieldError className="text-danger-strong text-[11px]">{errorMessage}</FieldError>
+      ) : (
+        description != null && (
+          <Text slot="description" className="text-fg-3 text-[11px]">
+            {description}
+          </Text>
+        )
+      )}
+    </AriaCheckboxGroup>
+  );
+});

package/src/components/inputs/ChoiceCardBody.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { Text } from "react-aria-components";
+import { cn } from "../../lib/cn.js";
+import { hasContent } from "../../lib/empty.js";
+import { CHOICE_CARD_ICON } from "../../lib/choice-card.js";
+
+/**
+ * Содержимое карточки выбора — общее для `Radio` и `Checkbox`.
+ *
+ * Не экспортируется из пакета: это разметка внутри метки, а не компонент
+ * потребителя. Иконка, подпись и описание лежат столбцом, индикатор —
+ * справа от них: выбранность не должна жить одним цветом рамки.
+ */
+export function ChoiceCardBody({
+  icon,
+  label,
+  labelClassName,
+  description,
+  indicator,
+}: {
+  icon?: ReactNode;
+  label?: ReactNode;
+  labelClassName: string;
+  description?: ReactNode;
+  indicator: ReactNode;
+}) {
+  // `hasContent`, а не `!= null`: пустая строка или `{flag && …}` при ложном
+  // флаге дали бы пустой узел — лишний зазор в столбце карточки.
+  return (
+    <>
+      {hasContent(icon) && (
+        <span aria-hidden="true" className={CHOICE_CARD_ICON}>
+          {icon}
+        </span>
+      )}
+      <span className="flex min-w-0 flex-1 flex-col gap-1">
+        {hasContent(label) && (
+          <span className={cn("text-fg-0 font-medium", labelClassName)}>{label}</span>
+        )}
+        {hasContent(description) && (
+          // Внутри метки, чтобы щелчок по описанию выбирал карточку, и скрыто от
+          // имени: читается как описание через `aria-describedby` (см. lib).
+          <Text slot="description" aria-hidden="true" className="text-fg-3 text-[11px]">
+            {description}
+          </Text>
+        )}
+      </span>
+      {indicator}
+    </>
+  );
+}

package/src/components/inputs/ColorPicker.tsx

@@ -0,0 +1,221 @@
+"use client";
+
+import type { ReactNode } from "react";
+import {
+  ColorArea,
+  ColorPicker as AriaColorPicker,
+  ColorField,
+  ColorSlider,
+  ColorSwatch,
+  ColorSwatchPicker,
+  ColorSwatchPickerItem,
+  ColorThumb,
+  parseColor,
+  Input,
+  Label,
+  SliderTrack,
+  type Color,
+} from "react-aria-components";
+import { useMessages } from "../../i18n/useMessages.js";
+import { useDescribedBy } from "../../hooks/useFieldDescription.js";
+import { cn } from "../../lib/cn.js";
+import { FIELD_SHELL_CLASS } from "../../lib/field.js";
+import { Popover, PopoverContent, PopoverTrigger } from "../overlays/Popover.js";
+
+export interface ColorPickerProps {
+  /** Текущий цвет строкой: `#4f7df3`, `rgb(...)`, `hsl(...)`. */
+  value: string;
+  /** Вызывается при смене цвета и получает строку в формате `outputFormat`. */
+  onChange: (value: string) => void;
+  /** Подпись поля. Обязательна: безымянный контрол скринридер называет только по роли. */
+  label: string;
+  /**
+   * Пресеты под областью выбора.
+   *
+   * Умолчания нет намеренно: набор «фирменных» цветов — это домен потребителя,
+   * а не кита. Значения токенов темы сюда подставляет тот, кто знает, какие из
+   * них применимы к его сущности.
+   *
+   * Нераспознанная заготовка **пропускается**, а не роняет рендер. Это не то же
+   * самое, что молчаливая правка `value`: значение потребитель хранит и отдаёт
+   * дальше, а заготовка — оформление, и падать из-за оформления компонент не
+   * должен. Библиотека на нераспознанной строке бросает **в фазе рендера**, то есть
+   * уносит поддерево потребителя целиком.
+   */
+  presets?: string[];
+  /**
+   * Формат строки, которую компонент отдаёт в `onChange`.
+   *
+   * Поле ввода под ползунками остаётся **шестнадцатеричным всегда**, и это
+   * названо в имени пропа: `rgb` и `hsl` — это не одно поле, а три поля
+   * каналов, то есть другой контрол, а не другой формат того же. Подпись поля
+   * поэтому тоже всегда `HEX`: подписать его «HSL», принимая hex, значило бы
+   * врать пользователю прямо на экране.
+   */
+  outputFormat?: "hex" | "rgb" | "hsl";
+  /** Выключает кнопку-триггер: панель выбора цвета не открывается. */
+  disabled?: boolean;
+  /** Содержимое кнопки-триггера вместо образца с подписью. */
+  children?: ReactNode;
+  /** Классы на кнопку-триггер. */
+  className?: string;
+}
+
+/**
+ * Заготовки, которые библиотека действительно умеет разобрать.
+ *
+ * `parseColor` бросает на непонятой строке, и бросок этот происходит в фазе
+ * рендера. Причём ломается не экзотика: `rebeccapurple` — законный CSS-цвет,
+ * который библиотека не берёт, а фирменную палитру совершенно естественно
+ * держать именами.
+ */
+function parsablePresets(presets: string[] | undefined): string[] {
+  if (!presets) return [];
+  /*
+    Дубликаты снимаются заодно — ради React-ключа, а не ради картинки: сам
+    `ColorSwatchPicker` одинаковые цвета схлопывает, так что на экране повтор и
+    так не виден, а `key={preset}` на нём дал бы два узла с одним ключом.
+    Отдельным тестом это не проверяется: наблюдаемой разницы нет.
+  */
+  return [...new Set(presets)].filter((preset) => {
+    try {
+      parseColor(preset);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
+const AREA_CLASS = "h-[132px] w-full rounded-md";
+const THUMB_CLASS =
+  "h-4 w-4 rounded-full border-2 border-white shadow-[0_0_0_1px_rgba(0,0,0,0.45)]";
+
+/**
+ * Выбор произвольного цвета.
+ *
+ * ОБЁРТКА, А НЕ СВОЯ МАТЕМАТИКА ЦВЕТА. Преобразования пространств, разбор
+ * строк, доступные описания оттенков для скринридера и клавиатура двумерной
+ * области — всё это уже есть в `react-aria-components` (общедоступно с 1.4.0).
+ * Здесь только словарь токенов сверху и раскладка.
+ *
+ * КОМПОНЕНТ ВЫДАЁТ ЦВЕТ МИМО СИСТЕМЫ ТОКЕНОВ, и это его назначение, а не
+ * недосмотр. Всё остальное в ките берёт цвет из темы; здесь пользователь
+ * называет свой — и результат по построению не подчиняется ни теме, ни бренду.
+ * Отсюда же следует, что контраст выбранного цвета кит не проверяет и
+ * проверить не может: он не знает, на чём этот цвет окажется.
+ *
+ * ЖИВЁТ ОТДЕЛЬНЫМ ВХОДОМ `@olddevs/ui/color`, а не в barrel: цветовая
+ * подсистема RAC стоит 61 кБ gzip — столько же, сколько весь остальной кит.
+ * Разбор в ADR-0038 и в
+ * докстроке `src/color.ts`.
+ *
+ * НАРУЖУ И ВНУТРЬ — СТРОКА, а не объект `Color` библиотеки. Объект протащил бы
+ * тип RAC в сигнатуры потребителя и в его состояние; строку он и так хранит,
+ * ею же и отдаёт на сервер.
+ *
+ * НЕРАСПОЗНАННАЯ СТРОКА В `value` СТАНОВИТСЯ ЧЁРНОЙ. Это поведение
+ * react-aria, и кит его не перехватывает: подменять чужое значение молча — то
+ * же самое, что молча его чинить. Но последствие стоит знать: первое же
+ * движение ползунка отдаст в `onChange` чёрный, то есть заменит нераспознанное
+ * значение распознанным. Проверять строку — обязанность потребителя, он же её и
+ * сформировал.
+ */
+export function ColorPicker({
+  value,
+  onChange,
+  label,
+  presets,
+  outputFormat = "hex",
+  disabled = false,
+  children,
+  className,
+}: ColorPickerProps) {
+  const messages = useMessages();
+  const describedBy = useDescribedBy(undefined);
+  const swatches = parsablePresets(presets);
+
+  return (
+    <AriaColorPicker
+      value={value}
+      onChange={(color: Color) => onChange(color.toString(outputFormat))}
+    >
+      <Popover>
+        <PopoverTrigger asChild>
+          <button
+            type="button"
+            disabled={disabled}
+            /*
+              Имя стоит на кнопке безусловно, а не рисуется подписью внутри:
+              с `children` подпись не попадает никуда, и кнопка остаётся
+              безымянной — ровно то, что докстрока `label` объявляет
+              недопустимым.
+            */
+            aria-label={label}
+            {...(describedBy ? { "aria-describedby": describedBy } : {})}
+            className={cn(
+              FIELD_SHELL_CLASS,
+              "flex cursor-pointer items-center gap-2 px-2.5 py-1.5",
+              "disabled:cursor-not-allowed disabled:opacity-50",
+              className
+            )}
+          >
+            {children ?? (
+              <>
+                <ColorSwatch className="border-line h-[18px] w-[18px] shrink-0 rounded border" />
+                <span className="text-fg-0 text-[13px]">{label}</span>
+              </>
+            )}
+          </button>
+        </PopoverTrigger>
+
+        <PopoverContent className="w-[268px] p-3">
+          <div className="flex flex-col gap-2.5">
+            <ColorArea
+              colorSpace="hsb"
+              xChannel="saturation"
+              yChannel="brightness"
+              className={AREA_CLASS}
+            >
+              <ColorThumb className={THUMB_CLASS} />
+            </ColorArea>
+
+            <ColorSlider colorSpace="hsb" channel="hue">
+              <SliderTrack className="h-3 w-full rounded-full">
+                <ColorThumb className={cn(THUMB_CLASS, "top-1/2")} />
+              </SliderTrack>
+            </ColorSlider>
+
+            <ColorField className="flex items-center gap-2">
+              <Label className="text-fg-2 text-caption">{messages.colorPicker.hex}</Label>
+              <Input
+                data-disable-focus-ring="true"
+                className={cn(
+                  FIELD_SHELL_CLASS,
+                  "text-fg-0 min-w-0 flex-1 px-2 py-1 text-[13px] outline-none"
+                )}
+              />
+            </ColorField>
+
+            {swatches.length > 0 && (
+              <div className="flex flex-col gap-1.5">
+                <span className="text-fg-2 text-caption">{messages.colorPicker.presets}</span>
+                <ColorSwatchPicker className="flex flex-wrap gap-1.5">
+                  {swatches.map((preset) => (
+                    <ColorSwatchPickerItem
+                      key={preset}
+                      color={preset}
+                      className="focus-visible:outline-accent-strong selected:ring-accent-strong selected:ring-2 selected:ring-offset-1 cursor-pointer rounded focus-visible:outline-2 focus-visible:outline-offset-2"
+                    >
+                      <ColorSwatch className="border-line h-[22px] w-[22px] rounded border" />
+                    </ColorSwatchPickerItem>
+                  ))}
+                </ColorSwatchPicker>
+              </div>
+            )}
+          </div>
+        </PopoverContent>
+      </Popover>
+    </AriaColorPicker>
+  );
+}