@olddevs/ui 0.0.0-stage → 4.0.0

package/src/components/content/VisuallyHidden.tsx

@@ -0,0 +1,25 @@
+"use client";
+
+/**
+ * Содержимое для скринридера, невидимое глазами.
+ *
+ * Реэкспорт react-aria, а не своя реализация, и это осознанно: «спрятать, но
+ * оставить доступным» — приём, который легко написать неправильно и не
+ * заметить. `display: none` и `visibility: hidden` убирают узел из дерева
+ * доступности вовсе; `width: 0` схлопывает текст в ничто и часть
+ * скринридеров его пропускает; `text-indent: -9999px` ломает горизонтальную
+ * прокрутку страницы в RTL.
+ *
+ * Правильный набор — квадрат 1×1 с `clip-path`, `overflow: hidden` и
+ * `white-space: nowrap` — библиотека держит сама и правит вместе с
+ * изменениями браузеров. Утилита `sr-only` из Tailwind делает то же самое и
+ * применяется там, где хватает класса; компонент нужен, когда прятать надо
+ * поддерево.
+ *
+ * ВНУТРИ СТРОКИ НУЖЕН `elementType="span"`. По умолчанию react-aria рисует
+ * `<div>`, и вставка его в `<p>` или в заголовок даёт невалидную вложенность:
+ * React пишет в консоль ошибку гидрации, а браузер разрывает абзац. Долго это
+ * не замечалось — тесты были зелёными, предупреждение уезжало в stderr.
+ */
+export { VisuallyHidden } from "react-aria-components";
+export type { VisuallyHiddenProps } from "react-aria-components";

package/src/components/content/keyboardEditing.ts

@@ -0,0 +1,51 @@
+export interface KeyboardSelection {
+  /** Начало выделения (позиция курсора, если совпадает с `end`). */
+  start: number;
+  /** Конец выделения. */
+  end: number;
+}
+
+export interface KeyboardEdit {
+  /** Текст после правки. */
+  value: string;
+  /** Позиция курсора после правки. */
+  selection: KeyboardSelection;
+}
+
+function normalizeSelection(value: string, selection: KeyboardSelection): KeyboardSelection {
+  const start = Math.max(0, Math.min(selection.start, value.length));
+  const end = Math.max(start, Math.min(selection.end, value.length));
+  return { start, end };
+}
+
+export function replaceKeyboardSelection(
+  value: string,
+  selection: KeyboardSelection,
+  text: string
+): KeyboardEdit {
+  const { start, end } = normalizeSelection(value, selection);
+  const caret = start + text.length;
+
+  return {
+    value: value.slice(0, start) + text + value.slice(end),
+    selection: { start: caret, end: caret },
+  };
+}
+
+export function deletePreviousKeyboardCodePoint(
+  value: string,
+  selection: KeyboardSelection
+): KeyboardEdit {
+  const { start, end } = normalizeSelection(value, selection);
+  if (start !== end) return replaceKeyboardSelection(value, { start, end }, "");
+
+  const prefix = value.slice(0, start);
+  const previous = Array.from(prefix).pop();
+  if (previous == null) return { value, selection: { start, end } };
+
+  const caret = start - previous.length;
+  return {
+    value: value.slice(0, caret) + value.slice(end),
+    selection: { start: caret, end: caret },
+  };
+}

package/src/components/content/useDragToSelect.ts

@@ -0,0 +1,255 @@
+"use client";
+
+import { useEffect, useRef, type RefObject } from "react";
+import type { Key, Selection } from "react-aria-components";
+import { toPixels } from "../../hooks/useStickyOffset.js";
+
+export interface DragToSelectOptions {
+  /** Жест включён: `dragToSelect` и множественный выбор. */
+  enabled: boolean;
+  /** Порядок ячеек в коллекции: диапазон считается по нему, а не по экрану. */
+  order: readonly Key[];
+  /** Что прокручивается у края: своя область сетки или окно. */
+  scroll: "container" | "window";
+  /** Переменная высоты липкой шапки: верхний край окна для автопрокрутки. */
+  offsetVar: string;
+  /** Текущий выбор — основа, к которой жест добавляет диапазон. */
+  selection: () => Selection;
+  /** Новый набор: прежний выбор и диапазон от первой ячейки жеста до текущей. */
+  onChange: (keys: Selection) => void;
+}
+
+/** Сколько держать палец неподвижно, прежде чем жест станет выделением. */
+const HOLD_MS = 300;
+/** Сдвиг до удержания, после которого это прокрутка, а не жест. */
+const SLOP_PX = 8;
+/** Полоса у края, где начинается автопрокрутка. */
+const EDGE_PX = 56;
+/** Наибольший шаг автопрокрутки за кадр. */
+const MAX_STEP_PX = 18;
+
+/**
+ * Выделение протяжкой пальца по ячейкам сетки.
+ *
+ * СВОЁ, А НЕ react-aria: у react-aria такого жеста нет
+ * (ADR-0028,
+ * дополнение). Выбор остаётся осью сетки: жест только сообщает новый набор тем
+ * же `onSelectionChange`.
+ *
+ * НА СОБЫТИЯХ КАСАНИЯ, А НЕ УКАЗАТЕЛЯ. Как только браузер начинает прокрутку,
+ * он шлёт `pointercancel`, и жест обрывается. Остановить прокрутку можно только
+ * `preventDefault` на `touchmove`, а для этого нужен непассивный слушатель
+ * касания.
+ *
+ * С ДОЛГИМ НАЖАТИЕМ МЕНЮ НЕ СПОРИТ. Удержание лишь взводит жест (300 мс, меню
+ * Radix ждёт 700), а выделение начинается, когда палец перешёл на другую
+ * ячейку. Палец, который остался на месте, получает меню.
+ *
+ * НАЧАЛО ЖЕСТА ОТМЕНЯЕТ НАЖАТИЕ — событием `pointercancel` в элемент, где
+ * началось касание. Сами они не отменятся: при касании `pointermove` уходит
+ * к ячейке под пальцем, а не к стартовой, и таймер меню Radix (он снимается
+ * на `pointermove` стартового триггера) открывал меню посреди протяжки;
+ * `usePress` ячейки принял бы отпускание за нажатие. Одно событие гасит оба.
+ */
+export function useDragToSelect(
+  gridRef: RefObject<HTMLElement | null>,
+  options: DragToSelectOptions
+): void {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  useEffect(() => {
+    const grid = gridRef.current;
+    if (!grid || !options.enabled) return;
+
+    let timer = 0;
+    let frame = 0;
+    let armed = false;
+    let dragging = false;
+    let suppressClick = false;
+    let suppressTimer = 0;
+    let pointerId = -1;
+    let start: { x: number; y: number; key: Key; target: EventTarget | null } | null = null;
+    let last = { x: 0, y: 0 };
+    let base: Set<Key> = new Set();
+    let current: Key | null = null;
+
+    // Порядковый номер по строке ключа: на каждом движении пальца и кадре
+    // автопрокрутки — без прохода по тысячам ключей. Пересобирается со сменой
+    // `order` (новая страница).
+    let indexed: readonly Key[] | null = null;
+    let positions = new Map<string, number>();
+    const positionOf = (key: string) => {
+      const { order } = optionsRef.current;
+      if (indexed !== order) {
+        indexed = order;
+        positions = new Map(order.map((k, i) => [String(k), i]));
+      }
+      return positions.get(key);
+    };
+
+    const keyAt = (x: number, y: number): Key | null => {
+      const row = document.elementFromPoint(x, y)?.closest<HTMLElement>('[role="row"]');
+      if (!row || !grid.contains(row) || row.dataset.key == null) return null;
+      // `data-key` — строка; ключ коллекции может быть числом.
+      const at = positionOf(row.dataset.key);
+      return at == null ? null : optionsRef.current.order[at]!;
+    };
+
+    const apply = (key: Key) => {
+      if (!start || key === current) return;
+      current = key;
+      const { order, onChange } = optionsRef.current;
+      const from = positionOf(String(start.key)) ?? -1;
+      const to = positionOf(String(key)) ?? -1;
+      if (from < 0 || to < 0) return;
+      const range = order.slice(Math.min(from, to), Math.max(from, to) + 1);
+      onChange(new Set<Key>([...base, ...range]));
+    };
+
+    const topEdge = () => {
+      if (optionsRef.current.scroll === "container") return grid.getBoundingClientRect().top;
+      const raw = getComputedStyle(document.documentElement)
+        .getPropertyValue(optionsRef.current.offsetVar)
+        .trim();
+      // `4rem` и `calc()` — тем же зондом, что у `useStickyOffset`.
+      return Number.parseFloat(toPixels(raw, "0px")) || 0;
+    };
+
+    const bottomEdge = () =>
+      optionsRef.current.scroll === "container"
+        ? grid.getBoundingClientRect().bottom
+        : window.innerHeight;
+
+    const autoscroll = () => {
+      frame = 0;
+      if (!dragging) return;
+      const top = topEdge() + EDGE_PX;
+      const bottom = bottomEdge() - EDGE_PX;
+      let step = 0;
+      if (last.y < top) step = -Math.min(MAX_STEP_PX, ((top - last.y) / EDGE_PX) * MAX_STEP_PX);
+      else if (last.y > bottom)
+        step = Math.min(MAX_STEP_PX, ((last.y - bottom) / EDGE_PX) * MAX_STEP_PX);
+      if (step !== 0) {
+        if (optionsRef.current.scroll === "container") grid.scrollTop += step;
+        else window.scrollBy(0, step);
+        // Под неподвижным пальцем проехали другие ячейки.
+        const key = keyAt(last.x, last.y);
+        if (key != null) apply(key);
+      }
+      frame = requestAnimationFrame(autoscroll);
+    };
+
+    const reset = () => {
+      window.clearTimeout(timer);
+      if (frame) cancelAnimationFrame(frame);
+      frame = 0;
+      armed = false;
+      dragging = false;
+      start = null;
+      current = null;
+    };
+
+    const onTouchStart = (event: TouchEvent) => {
+      reset();
+      suppressClick = false;
+      if (event.touches.length !== 1) return;
+      const touch = event.touches[0]!;
+      const key = keyAt(touch.clientX, touch.clientY);
+      if (key == null) return;
+      start = { x: touch.clientX, y: touch.clientY, key, target: event.target };
+      last = { x: touch.clientX, y: touch.clientY };
+      timer = window.setTimeout(() => {
+        armed = true;
+      }, HOLD_MS);
+    };
+
+    const onTouchMove = (event: TouchEvent) => {
+      if (!start) return;
+      const touch = event.touches[0];
+      if (!touch) return;
+      last = { x: touch.clientX, y: touch.clientY };
+      if (!armed) {
+        // Палец поехал раньше удержания — это прокрутка, не жест.
+        if (Math.hypot(touch.clientX - start.x, touch.clientY - start.y) > SLOP_PX) reset();
+        return;
+      }
+      event.preventDefault();
+      const key = keyAt(touch.clientX, touch.clientY);
+      if (!dragging) {
+        if (key == null || key === start.key) return;
+        dragging = true;
+        start.target?.dispatchEvent(
+          new PointerEvent("pointercancel", { bubbles: true, pointerId, pointerType: "touch" })
+        );
+        const selection = optionsRef.current.selection();
+        // «Выделено всё» — основа из всех ключей: пустая основа сузила бы выбор
+        // до диапазона протяжки.
+        base = new Set(selection === "all" ? optionsRef.current.order : selection);
+        current = null;
+        apply(start.key);
+        frame = requestAnimationFrame(autoscroll);
+      }
+      if (key != null) apply(key);
+    };
+
+    const onTouchEnd = () => {
+      if (dragging) {
+        // Сдвинутое касание щелчка обычно не порождает: флаг, оставшийся
+        // взведённым, съел бы следующий настоящий тап (кнопку «в избранное»).
+        // Синтезированный щелчок приходит сразу — ждать его дольше незачем.
+        suppressClick = true;
+        window.clearTimeout(suppressTimer);
+        suppressTimer = window.setTimeout(() => {
+          suppressClick = false;
+        }, 400);
+      }
+      reset();
+    };
+
+    // Номер указателя нужен отмене: `usePress` сверяет его со своим.
+    const rememberPointer = (event: PointerEvent) => {
+      if (event.pointerType === "touch") pointerId = event.pointerId;
+    };
+
+    // Щелчок, который браузер мог синтезировать после жеста, — не нажатие.
+    const swallowClick = (event: Event) => {
+      if (!suppressClick) return;
+      suppressClick = false;
+      event.stopPropagation();
+      event.preventDefault();
+    };
+
+    grid.addEventListener("touchstart", onTouchStart, { passive: true });
+    grid.addEventListener("touchmove", onTouchMove, { passive: false });
+    grid.addEventListener("touchend", onTouchEnd);
+    grid.addEventListener("touchcancel", reset);
+    // Отмена касания до начала протяжки — долгое нажатие ячейки с меню (сетка
+    // гасит им выделение react-aria) или прокрутка браузера. Протяжка не
+    // начнётся, даже если палец поедет потом: человек работает с меню.
+    // Только отмена СВОЕГО касания: стартовый элемент или ячейка, в которой он
+    // лежит. Отмена в соседней ячейке (второй палец) протяжку не трогает.
+    const disarm = (event: PointerEvent) => {
+      if (event.pointerType !== "touch" || dragging || !start) return;
+      const own = start.target;
+      const at = event.target;
+      if (at === own || (at instanceof Node && own instanceof Node && at.contains(own))) reset();
+    };
+
+    grid.addEventListener("pointerdown", rememberPointer, true);
+    grid.addEventListener("pointercancel", disarm, true);
+    grid.addEventListener("click", swallowClick, true);
+
+    return () => {
+      reset();
+      window.clearTimeout(suppressTimer);
+      grid.removeEventListener("touchstart", onTouchStart);
+      grid.removeEventListener("touchmove", onTouchMove);
+      grid.removeEventListener("touchend", onTouchEnd);
+      grid.removeEventListener("touchcancel", reset);
+      grid.removeEventListener("pointerdown", rememberPointer, true);
+      grid.removeEventListener("pointercancel", disarm, true);
+      grid.removeEventListener("click", swallowClick, true);
+    };
+  }, [gridRef, options.enabled]);
+}

package/src/components/date-time/Calendar.tsx

@@ -0,0 +1,181 @@
+"use client";
+
+import { getLocalTimeZone, today, type CalendarDate } from "@internationalized/date";
+import { useEffect, useState } from "react";
+import {
+  Button,
+  CalendarCell,
+  CalendarGrid,
+  CalendarGridBody,
+  CalendarGridHeader,
+  CalendarHeaderCell,
+  Calendar as CalendarRac,
+  Heading,
+  HeadingContext,
+  I18nProvider,
+  useSlottedContext,
+  type CalendarProps as CalendarPropsRac,
+  type DateValue,
+} from "react-aria-components";
+import { cn } from "../../lib/cn.js";
+import { ChevronLeftIcon, ChevronRightIcon } from "../../icons.js";
+import { toDateBound, toDateValue, toIsoDate, type DateInput } from "../../lib/date.js";
+
+export interface CalendarProps extends Omit<
+  CalendarPropsRac<DateValue>,
+  "value" | "defaultValue" | "onChange" | "minValue" | "maxValue" | "defaultFocusedValue"
+> {
+  /**
+   * Выбранный день: объект `@internationalized/date` или ISO-строка `ГГГГ-ММ-ДД`.
+   * `null` — управляемое пустое значение. Неразбираемая строка считается пустой.
+   */
+  value?: DateInput | null;
+  /** Начальный день неуправляемого календаря; те же два вида, что у `value`. */
+  defaultValue?: DateInput | null;
+  /**
+   * Вызывается при выборе дня. Первый аргумент — объект календаря, как у React
+   * Aria; второй — тот же день ISO-строкой `ГГГГ-ММ-ДД`, для
+   * тех, у кого значение хранится строкой, как в `DatePicker`.
+   */
+  onChange?: (value: DateValue, iso: string) => void;
+  /** Самый ранний доступный день: объект календаря или ISO-строка `ГГГГ-ММ-ДД`. */
+  minValue?: DateInput;
+  /** Самый поздний доступный день; те же два вида, что у `minValue`. */
+  maxValue?: DateInput;
+  /** Месяц, на котором открывается неуправляемый календарь; те же два вида, что у `minValue`. */
+  defaultFocusedValue?: DateInput;
+  /** Классы на корень календаря: ширина, отступы, фон. */
+  className?: string;
+  /**
+   * Локаль подписей и первого дня недели. По умолчанию русская: подписи
+   * примитивов кита русские везде, и календарь не исключение.
+   */
+  locale?: string;
+}
+
+/** Кнопки листания месяцев — одинаковые в обоих календарях. */
+export const NAV_BUTTON_CLASS =
+  "text-fg-3 hover:bg-bg-3 hover:text-fg-1 data-[focus-visible]:ring-accent-strong flex size-8 cursor-pointer items-center justify-center rounded-lg transition-colors outline-none data-[focus-visible]:ring-2";
+
+/** Подписи дней недели — тоже общие. */
+export const WEEKDAY_CELL_CLASS = "text-fg-3 size-9 p-0 text-[11px] font-medium";
+
+/**
+ * Пробелы, которые Intl разных сборок ICU ставит по-разному: тонкий (U+2009)
+ * вокруг тире в диапазоне и узкий неразрывный (U+202F). Обычный неразрывный
+ * не трогается — он одинаков у сервера и браузера и держит «2026 г.» вместе.
+ */
+const INTL_SPACES = /[\u2009\u202f]/g;
+
+/**
+ * Заголовок календаря — месяц или диапазон месяцев над сеткой.
+ *
+ * Текст берётся у react-aria (`HeadingContext`), а там он — `formatRange` из
+ * Intl, и Intl у сервера и браузера разный: ICU в Node ставит вокруг тире
+ * тонкие пробелы, Chrome — обычные. Отрисованный на сервере `RangeCalendar`
+ * с двумя месяцами не проходил гидратацию (React #418). Здесь
+ * пробелы приводятся к обычным, и строка одна на обеих сторонах.
+ */
+export function CalendarHeading() {
+  const title = useSlottedContext(HeadingContext)?.children;
+  return (
+    <Heading className="text-fg-1 grow text-center text-[13px] font-semibold">
+      {typeof title === "string" ? title.replace(INTL_SPACES, " ") : title}
+    </Heading>
+  );
+}
+
+/**
+ * Сегодняшний день — только в браузере, после монтирования.
+ *
+ * На сервере «сегодня» неизвестно: статику собирают в другой день и в другом
+ * часовом поясе, и точка в HTML стояла бы не на том дне, что у читателя, а
+ * гидратация расходилась бы классами ячеек. Первый кадр без точки.
+ */
+export function useToday(): CalendarDate | null {
+  const [now, setNow] = useState<CalendarDate | null>(null);
+  useEffect(() => setNow(today(getLocalTimeZone())), []);
+  return now;
+}
+
+/**
+ * Календарь одной даты.
+ *
+ * Поведение — `react-aria-components`: клавиатура, роль `grid`, объявление
+ * полной даты у ячейки, локаль и первый день недели. Своя реализация этого
+ * была бы не примитивом, а второй библиотекой — та же логика, что у Radix
+ * для тултипа и поповера (ADR-0004).
+ *
+ * Сегодняшний день помечается точкой под числом, а не заливкой: заливка
+ * занята выбранным значением, и два разных состояния одним приёмом
+ * различить нельзя.
+ */
+export function Calendar({
+  className,
+  locale,
+  value,
+  defaultValue,
+  onChange,
+  minValue,
+  maxValue,
+  defaultFocusedValue,
+  ...props
+}: CalendarProps) {
+  const now = useToday();
+
+  /*
+    Свой `I18nProvider` разворачивается ТОЛЬКО под точечный проп `locale`.
+    До 2.0.0 он стоял всегда и жёстко на `ru-RU` — то есть календарь перебивал
+    локаль приложения собственной. Теперь без пропа локаль приходит сверху:
+    от `UiProvider` кита, от `I18nProvider` потребителя или от браузера.
+  */
+  const calendar = (
+    <CalendarRac
+      {...props}
+      value={toDateValue(value)}
+      defaultValue={toDateValue(defaultValue)}
+      onChange={onChange && ((next) => onChange(next, toIsoDate(next)))}
+      minValue={toDateBound(minValue)}
+      maxValue={toDateBound(maxValue)}
+      defaultFocusedValue={toDateBound(defaultFocusedValue)}
+      className={cn("w-fit p-3 select-none", className)}
+    >
+      <header className="mb-1 flex items-center gap-1">
+        <Button slot="previous" className={NAV_BUTTON_CLASS}>
+          <ChevronLeftIcon size={15} />
+        </Button>
+        <CalendarHeading />
+        <Button slot="next" className={NAV_BUTTON_CLASS}>
+          <ChevronRightIcon size={15} />
+        </Button>
+      </header>
+
+      <CalendarGrid>
+        <CalendarGridHeader>
+          {(day) => <CalendarHeaderCell className={WEEKDAY_CELL_CLASS}>{day}</CalendarHeaderCell>}
+        </CalendarGridHeader>
+        <CalendarGridBody className="[&_td]:px-0">
+          {(date) => (
+            <CalendarCell
+              date={date}
+              className={cn(
+                "text-fg-1 relative flex size-9 cursor-pointer items-center justify-center rounded-lg border border-transparent p-0 text-[13px] font-normal outline-none",
+                "duration-fast transition-colors",
+                "data-[hovered]:bg-bg-3 data-[hovered]:text-fg-0",
+                "data-[selected]:bg-accent data-[selected]:text-text-on-accent data-[selected]:border-transparent",
+                "data-[disabled]:pointer-events-none data-[disabled]:opacity-30",
+                "data-[unavailable]:pointer-events-none data-[unavailable]:line-through data-[unavailable]:opacity-30",
+                "data-[focus-visible]:outline-accent-strong data-[focus-visible]:outline data-[focus-visible]:outline-2",
+                now !== null &&
+                  date.compare(now) === 0 &&
+                  "after:bg-accent data-[selected]:after:bg-text-on-accent after:absolute after:bottom-1 after:left-1/2 after:size-[3px] after:-translate-x-1/2 after:rounded-full"
+              )}
+            />
+          )}
+        </CalendarGridBody>
+      </CalendarGrid>
+    </CalendarRac>
+  );
+
+  return locale ? <I18nProvider locale={locale}>{calendar}</I18nProvider> : calendar;
+}

package/src/components/date-time/DatePicker.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+import { useState, type ReactNode } from "react";
+import type { DateValue } from "react-aria-components";
+import { cn } from "../../lib/cn.js";
+import { parseDateOrNull, type DateInput } from "../../lib/date.js";
+import { useMessages, useUiLocale } from "../../i18n/useMessages.js";
+import { ChevronDownIcon } from "../../icons.js";
+import { Calendar } from "./Calendar.js";
+import { useFieldDescribedBy } from "../../hooks/useFieldDescription.js";
+import { Popover, PopoverContent, PopoverTrigger } from "../overlays/Popover.js";
+
+export interface DatePickerProps {
+  /** Дата в ISO-формате `ГГГГ-ММ-ДД` либо пусто. */
+  value?: string | null;
+  /** Вызывается с выбранной датой в виде ISO-строки `ГГГГ-ММ-ДД`, как `value`. Компонент не знает про `Date` и таймзоны. */
+  onChange: (date: string) => void;
+  /** Текст триггера, пока дата не выбрана; по умолчанию стандартная подпись кита. */
+  placeholder?: string;
+  /** Блокирует кнопку-триггер: календарь не открывается. */
+  disabled?: boolean;
+  /**
+   * Самая ранняя доступная дата.
+   *
+   * Ограничения показываются в календаре, а не проверяются после выбора.
+   * ISO-строка `ГГГГ-ММ-ДД`, как и `value`; объект `@internationalized/date`
+   * тоже принимается.
+   */
+  minValue?: DateInput;
+  /** Самая поздняя доступная дата; показывается в календаре так же, как `minValue`. */
+  maxValue?: DateInput;
+  /** Отмечает конкретные дни недоступными (праздники, занятые даты): их нельзя выбрать. */
+  isDateUnavailable?: (date: DateValue) => boolean;
+  /** Локаль подписи даты и календаря; по умолчанию локаль `UiProvider`. */
+  locale?: string;
+  /** Классы на кнопку-триггер. */
+  triggerClassName?: string;
+  /**
+   * Своё описание триггера. Сливается с описанием `FormField`, а не заменяет
+   * его: подсказка формы и пояснение потребителя обязаны звучать обе.
+   */
+  "aria-describedby"?: string;
+}
+
+/**
+ * Дата с подчёркнутым триггером — компактный вид для строки формы.
+ *
+ * Значение ходит ISO-строкой, а не объектом `@internationalized/date`:
+ * потребитель хранит дату в URL и шлёт в API, и заставлять его конвертировать
+ * туда-обратно значит переложить на него внутреннюю кухню календаря.
+ */
+export function DatePicker({
+  value,
+  onChange,
+  placeholder,
+  disabled,
+  minValue,
+  maxValue,
+  isDateUnavailable,
+  locale,
+  triggerClassName,
+  "aria-describedby": ariaDescribedBy,
+}: DatePickerProps) {
+  const messages = useMessages();
+  const uiLocale = useUiLocale();
+  const effectiveLocale = locale ?? uiLocale;
+  /**
+   * Описание поля из `FormField` плюс своё, если потребитель его передал.
+   *
+   * Тот же приём, что у `TextControl` и `NumberInput`: значения СЛИВАЮТСЯ, а
+   * не заменяют друг друга. Вне `FormField` контекст пуст, и разметка та же,
+   * что была до появления описаний.
+   */
+  const fieldDescribedBy = useFieldDescribedBy();
+  const describedBy = [ariaDescribedBy, fieldDescribedBy].filter(Boolean).join(" ") || undefined;
+
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          disabled={disabled}
+          aria-describedby={describedBy}
+          className={cn(
+            "border-line-soft text-fg-2 hover:border-line hover:text-fg-1 inline-flex cursor-pointer items-center gap-1 border-b pb-px font-mono text-[13px] transition-colors outline-none",
+            "focus-visible:outline-accent-strong focus-visible:outline-2 focus-visible:outline-offset-2",
+            "disabled:cursor-not-allowed disabled:opacity-50",
+            triggerClassName
+          )}
+        >
+          {formatDate(value, effectiveLocale) ?? placeholder ?? messages.datePicker.placeholder}
+          <ChevronDownIcon size={12} className="text-fg-3 shrink-0" />
+        </button>
+      </PopoverTrigger>
+      <PopoverContent className="w-auto p-0" align="start">
+        <Calendar
+          value={parseDateOrNull(value)}
+          onChange={(date) => {
+            if (!date) return;
+            onChange(date.toString());
+            setOpen(false);
+          }}
+          minValue={minValue}
+          maxValue={maxValue}
+          isDateUnavailable={isDateUnavailable}
+          locale={locale ?? uiLocale}
+        />
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+/**
+ * Дата разбирается по частям, а не через `new Date(iso)`.
+ *
+ * `new Date("2026-03-05")` — это полночь **UTC**, и восточнее Гринвича строка
+ * превращается в предыдущий день. Компонент оперирует календарной датой без
+ * времени, поэтому и собирать её надо в местном полудне календаря.
+ *
+ * НО СОБИРАТЬ МОЖНО ТОЛЬКО РАЗОБРАННОЕ. Сборка по частям ничего не проверяет, и
+ * до волны 26 функция отвечала на мусор правдоподобной ложью: `2026-02-29`
+ * (год не високосный) молча становился `Mar 01, 2026`, `2026-09` — `Sep 01,
+ * 2026`, а `ерунда` — строкой `Invalid Date` прямо на кнопке. Значение
+ * приходит из адреса, поэтому сначала строгий разбор, и только потом сборка.
+ */
+export function formatDate(isoDate: string | null | undefined, locale = "en-US"): ReactNode {
+  const parsed = parseDateOrNull(isoDate);
+  if (!parsed) return null;
+
+  const date = new Date(parsed.year, parsed.month - 1, parsed.day);
+  // Годы 0–99 конструктор `Date` отображает в 1900+y — легаси-правило, живое до
+  // сих пор. `parseDate` такие годы принимает (`0026-03-05` — законная строка из
+  // адреса), и без этой строки кнопка показывала бы «Mar 05, 1926»: та же
+  // правдоподобная ложь, ради устранения которой разбор и сделан строгим.
+  date.setFullYear(parsed.year);
+  return date.toLocaleDateString(locale, {
+    day: "2-digit",
+    month: "short",
+    year: "numeric",
+  });
+}