@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/components/date-time/calendar.en.md

@@ -0,0 +1,47 @@
+---
+component: Calendar
+exports: [Calendar, NAV_BUTTON_CLASS, WEEKDAY_CELL_CLASS]
+category: date-time
+status: stable
+source: src/components/date-time/Calendar.tsx
+story: src/components/date-time/Calendar.stories.tsx
+sourceHash: 16a76c5ab721
+---
+
+# Calendar
+
+## Summary for AI
+
+`Calendar` is a low-level controlled building block for picking a single React Aria `DateValue`. For a ready-made form field, use `DatePicker`; choose `Calendar` only for your own composition.
+
+## When to use
+
+- You need an inline calendar grid with React Aria props: `value`, `defaultValue`, `onChange`, unavailable dates and constraints.
+- You need your own overlay or layout around the calendar.
+
+## When not to use
+
+- For ordinary compact date selection, use `DatePicker`.
+- For a period with two bounds, use `RangeCalendar` or `DateRangePicker`.
+- Do not store a calendar date as a `Date`: it has a time zone. Use `DateValue` at the `Calendar` boundary, or an ISO string in a ready-made `DatePicker`.
+
+## Minimal example
+
+```tsx
+<Calendar value={date} onChange={setDate} locale="ru-RU" minValue={today(getLocalTimeZone())} />
+```
+
+## Public API
+
+- Inherits React Aria's `CalendarProps<DateValue>`, including controlled/uncontrolled value, `minValue`, `maxValue`, `isDateUnavailable`.
+- **A date is an object or an ISO string.** `value`, `defaultValue`, `minValue`, `maxValue` and `defaultFocusedValue` accept both an `@internationalized/date` object and a `YYYY-MM-DD` string, like `DatePicker`. There is no need to import `@internationalized/date` for this (the package itself stays a peer dependency of the kit): `minValue="2026-03-09"`. An unparsable string (`2026-02-29`, garbage from the address bar) does not throw: the value is treated as empty and the bound as not set.
+- `onChange(value, iso)`: the first argument is a calendar object, as in React Aria (it always was); the second is the same day as an ISO string. Whoever stores the date as a string needs only `onChange={(_, iso) => setDate(iso)}`. What `onChange` receives does not depend on whether `value` is passed as an object or a string: existing calls with objects work unchanged.
+- `isDateUnavailable` receives a calendar object: `date.toString()` returns the day as a `YYYY-MM-DD` string.
+- Without `locale`, the locale comes from above: from `UiProvider`, the consumer's `I18nProvider` or the browser; `locale` overrides it for this calendar and affects labels and the first day of the week; `className` applies to the root.
+- `NAV_BUTTON_CLASS` and `WEEKDAY_CELL_CLASS` are public style constants for a consistent custom composition, not separate components.
+
+## Accessibility and keyboard
+
+- React Aria implements `grid`, full accessible names for dates and keyboard navigation.
+- Today is marked with a dot, the selected date with a fill; do not make the dot and the fill the only indicator of a date in your own markup around the calendar: React Aria provides the cell name (the full date).
+- See `src/components/date-time/Calendar.tsx`, `src/components/date-time/Calendar.stories.tsx`, `tests/matrix.tsx`.

package/docs/components/date-time/calendar.md

@@ -0,0 +1,46 @@
+---
+component: Calendar
+exports: [Calendar, NAV_BUTTON_CLASS, WEEKDAY_CELL_CLASS]
+category: date-time
+status: stable
+source: src/components/date-time/Calendar.tsx
+story: src/components/date-time/Calendar.stories.tsx
+---
+
+# Calendar
+
+## Кратко для AI
+
+`Calendar` — низкоуровневый controlled building block для выбора одной `DateValue` из React Aria. Для готового поля формы обычно используйте `DatePicker`; `Calendar` выбирайте только для собственной композиции.
+
+## Когда использовать
+
+- Нужна встроенная сетка календаря с React Aria props: `value`, `defaultValue`, `onChange`, недоступные даты и ограничения.
+- Требуется собственный оверлей или раскладка вокруг календаря.
+
+## Когда не использовать
+
+- Для обычного компактного выбора даты используйте `DatePicker`.
+- Для периода с двумя границами используйте `RangeCalendar` или `DateRangePicker`.
+- Не храните календарную дату как `Date`: у него есть часовой пояс. Берите `DateValue` на границе `Calendar` или ISO-строку в готовом `DatePicker`.
+
+## Минимальный пример
+
+```tsx
+<Calendar value={date} onChange={setDate} locale="ru-RU" minValue={today(getLocalTimeZone())} />
+```
+
+## Public API
+
+- Наследует `CalendarProps<DateValue>` React Aria, включая controlled/uncontrolled value, `minValue`, `maxValue`, `isDateUnavailable`.
+- **Дата — объект или ISO-строка.** `value`, `defaultValue`, `minValue`, `maxValue` и `defaultFocusedValue` принимают и объект `@internationalized/date`, и строку `ГГГГ-ММ-ДД`, как `DatePicker`. Импортировать `@internationalized/date` для этого не нужно (сам пакет остаётся peer-зависимостью кита): `minValue="2026-03-09"`. Неразбираемая строка (`2026-02-29`, мусор из адреса) не бросает исключение: значение считается пустым, граница — незаданной.
+- `onChange(value, iso)`: первый аргумент — объект календаря, как у React Aria (так было всегда), второй — тот же день ISO-строкой. Хранящему дату строкой достаточно `onChange={(_, iso) => setDate(iso)}`. Что получает `onChange`, не зависит от того, объектом или строкой передан `value`: прежние вызовы с объектами работают без правок.
+- `isDateUnavailable` получает объект календаря: `date.toString()` возвращает день строкой `ГГГГ-ММ-ДД`.
+- Без `locale` локаль приходит сверху: от `UiProvider`, `I18nProvider` потребителя или браузера; `locale` перебивает её для этого календаря, влияет на подписи и первый день недели; `className` относится к корню.
+- `NAV_BUTTON_CLASS` и `WEEKDAY_CELL_CLASS` — публичные константы стилей для согласованной пользовательской композиции, не отдельные компоненты.
+
+## Доступность и клавиатура
+
+- React Aria реализует `grid`, полные доступные имена дат и клавиатурную навигацию.
+- Сегодня отмечается точкой, выбранная дата — заливкой; не делайте точку и заливку единственным признаком даты в собственной вёрстке вокруг календаря: имя ячейки (полная дата) даёт React Aria.
+- См. `src/components/date-time/Calendar.tsx`, `src/components/date-time/Calendar.stories.tsx`, `tests/matrix.tsx`.

package/docs/components/date-time/date-picker.en.md

@@ -0,0 +1,52 @@
+---
+component: DatePicker
+exports: [DatePicker, formatDate]
+category: date-time
+status: stable
+source: src/components/date-time/DatePicker.tsx
+story: src/components/date-time/DatePicker.stories.tsx
+sourceHash: 389a684cb62f
+---
+
+# DatePicker
+
+## Summary for AI
+
+`DatePicker` is a ready-made trigger + popover for a single calendar date. The value the component accepts and returns is an ISO `YYYY-MM-DD` string, not a JS `Date`, so the time zone cannot shift the date.
+
+## When to use
+
+- A form needs a single day with a compact trigger and a calendar.
+- Your API, URL or state already uses ISO strings.
+
+## When not to use
+
+- For custom placement of the grid, use `Calendar`.
+- For date and time together, use `DateTimePicker`; for a period, use `DateRangePicker`.
+
+## Minimal example
+
+```tsx
+<DatePicker value={publishDate} onChange={setPublishDate} minValue="2026-03-09" />
+```
+
+## Public API
+
+- `value?: string | null`; `onChange(date: string)` receives an ISO string after the user picks a date.
+- `minValue`, `maxValue`, `isDateUnavailable` limit the choice in the calendar; this is a UI boundary and does not replace server-side validation.
+- `minValue` and `maxValue` are ISO strings `YYYY-MM-DD`, like `value` (`minValue="2026-03-09"`); there is no need to import `@internationalized/date` (the package itself stays a peer dependency of the kit). An `@internationalized/date` object is still accepted. An unparsable string is treated as an unset bound. `isDateUnavailable` receives a calendar object: `date.toString()` returns the day as a `YYYY-MM-DD` string.
+- In `DateTimePicker` these bounds are calendar bounds, that is, day bounds: see [DateTimePicker](date-time-picker.md#public-api) for details.
+- `placeholder`, `disabled`, `locale`, `triggerClassName` configure the control.
+- `formatDate(isoDate, locale?)` is a public utility for displaying an ISO calendar date the same safe way; do not use `new Date("YYYY-MM-DD")` unless the date is a UTC instant.
+
+## Accessibility and keyboard
+
+- **The `FormField` hint and error are announced together with the field.** The
+  description is passed through context, and `aria-describedby` is set on the
+  trigger; the consumer's `aria-describedby` value is not overridden but merged
+  with it. Before version 3.0.0 the react-aria families did not pick up the form description — it was on
+  screen but never reached the screen reader
+  (ADR-0031).
+- The popover uses `Calendar` with its grid and keyboard contract; it closes on selection.
+- Associate an external label through `FormField` and `htmlFor` only when the trigger is bound to it in your composition; do not rely on the placeholder.
+- See `src/components/date-time/DatePicker.tsx`, `src/components/date-time/DatePicker.stories.tsx`, `tests/matrix.tsx`.

package/docs/components/date-time/date-picker.md

@@ -0,0 +1,50 @@
+---
+component: DatePicker
+exports: [DatePicker, formatDate]
+category: date-time
+status: stable
+source: src/components/date-time/DatePicker.tsx
+story: src/components/date-time/DatePicker.stories.tsx
+---
+
+# DatePicker
+
+## Кратко для AI
+
+`DatePicker` — готовый триггер + поповер для одной календарной даты. Значение, которое компонент принимает и отдаёт, — ISO `ГГГГ-ММ-ДД`, а не JS `Date`, поэтому часовой пояс не сдвигает дату.
+
+## Когда использовать
+
+- В форме нужен один день с компактным триггером и календарём.
+- API, URL или состояние уже используют ISO-строки.
+
+## Когда не использовать
+
+- Для произвольного размещения сетки используйте `Calendar`.
+- Для даты и времени вместе используйте `DateTimePicker`; для периода — `DateRangePicker`.
+
+## Минимальный пример
+
+```tsx
+<DatePicker value={publishDate} onChange={setPublishDate} minValue="2026-03-09" />
+```
+
+## Public API
+
+- `value?: string | null`; `onChange(date: string)` получает ISO-строку после выбора.
+- `minValue`, `maxValue`, `isDateUnavailable` ограничивают выбор в календаре; это ограничение интерфейса, серверную валидацию не отменяет.
+- `minValue` и `maxValue` — ISO-строки `ГГГГ-ММ-ДД`, как и `value`: `minValue="2026-03-09"`, импортировать `@internationalized/date` не нужно (сам пакет остаётся peer-зависимостью кита). Объект `@internationalized/date` по-прежнему принимается. Неразбираемая строка считается незаданной границей. `isDateUnavailable` получает объект календаря: `date.toString()` возвращает день строкой `ГГГГ-ММ-ДД`.
+- У `DateTimePicker` эти границы календарные, то есть дневные: подробности — в [DateTimePicker](date-time-picker.md#public-api).
+- `placeholder`, `disabled`, `locale`, `triggerClassName` настраивают контрол.
+- `formatDate(isoDate, locale?)` — публичная утилита для того же безопасного отображения календарной ISO-даты; не используйте `new Date("YYYY-MM-DD")`, если дата — не момент UTC.
+
+## Доступность и клавиатура
+
+- **Пояснение и ошибка `FormField` объявляются вместе с полем.** Описание
+  приходит контекстом, `aria-describedby` ставится на триггер; значение
+  `aria-describedby` потребителя не вытесняется, а сливается с ним. До версии 3.0.0 семьи react-aria
+  описание формы не забирали — на экране оно было, скринридеру не доставалось
+  (ADR-0031).
+- Поповер использует `Calendar` с его контрактом сетки и клавиатуры; при выборе закрывается.
+- Внешнюю подпись связывайте через `FormField` и `htmlFor`, только когда триггер к ней привязан в вашей композиции; не полагайтесь на плейсхолдер.
+- См. `src/components/date-time/DatePicker.tsx`, `src/components/date-time/DatePicker.stories.tsx`, `tests/matrix.tsx`.

package/docs/components/date-time/date-range-picker.en.md

@@ -0,0 +1,58 @@
+---
+component: DateRangePicker
+exports: [DateRangePicker]
+category: date-time
+status: stable
+source: src/components/date-time/DateRangePicker.tsx
+story: src/components/date-time/DateRangePicker.stories.tsx
+sourceHash: 1cc8eb9120cd
+---
+
+# DateRangePicker
+
+## Summary for AI
+
+`DateRangePicker` is a ready-made period picker: a trigger, `RangeCalendar`, relative presets and a separate clear control. `onChange` is called only after both bounds are picked.
+
+## When to use
+
+- In a filter or report, users pick "from/to" dates and often use "7 days", "30 days" and other presets.
+- The consumer can store both an expanded `DateRange` and the original `RelativePeriod`.
+
+## When not to use
+
+- For an arbitrary period layout, use `RangeCalendar`.
+- For a single date, use `DatePicker`.
+- Do not use it to pick only the start of a period: the component emits only a complete range.
+
+## Minimal example
+
+```tsx
+<DateRangePicker
+  value={range}
+  period={period}
+  onChange={(nextRange, nextPeriod) => {
+    setRange(nextRange);
+    setPeriod(nextPeriod);
+  }}
+  onClear={() => {
+    setRange(null);
+    setPeriod(null);
+  }}
+/>
+```
+
+## Public API
+
+- `value?: DateRange | null`, where the bounds are ISO strings; `period?: RelativePeriod | null` ties the selected preset to the range.
+- `onChange(range, period)` receives `period=null` on a manual pick; `onClear` is required for the clear button to appear, because clearing must reset both values: `value` and `period`.
+- `presets`, `timeZone`, `minValue`, `maxValue`, `defaultFocusedValue`, `locale` define the allowed and relative periods.
+- `minValue`, `maxValue` and `defaultFocusedValue` are ISO strings `YYYY-MM-DD`, like `value` (`minValue="2026-03-09"`); there is no need to import `@internationalized/date` (the package itself stays a peer dependency of the kit). An object is still accepted; an unparsable string is treated as an unset bound.
+- `isDateUnavailable(date)` marks specific days unavailable — booked dates, holidays: in the calendar they are struck through and cannot be picked. The function receives a calendar object; `date.toString()` returns the day as a `YYYY-MM-DD` string. `RangeCalendar` and `DatePicker` have the same prop. Presets ignore the rule: they are clamped only by `minValue` and `maxValue`, and a preset that covers an unavailable day is picked as is — if that is not allowed, do not leave such a preset in `presets`.
+- `open`/`onOpenChange` let you control the popover; otherwise internal state is used.
+
+## Accessibility and keyboard
+
+- The clear control is a separate button next to the trigger, not an interactive element inside a button.
+- The two-month view appears at a screen width of 640 pixels and up; do not rely on an incomplete selection for a network request.
+- Sources: `src/components/date-time/DateRangePicker.tsx`, `src/components/date-time/DateRangePicker.stories.tsx`.

package/docs/components/date-time/date-range-picker.md

@@ -0,0 +1,57 @@
+---
+component: DateRangePicker
+exports: [DateRangePicker]
+category: date-time
+status: stable
+source: src/components/date-time/DateRangePicker.tsx
+story: src/components/date-time/DateRangePicker.stories.tsx
+---
+
+# DateRangePicker
+
+## Кратко для AI
+
+`DateRangePicker` — готовый выбор периода: триггер, `RangeCalendar`, относительные пресеты и отдельная очистка. `onChange` вызывается только после выбора обеих границ.
+
+## Когда использовать
+
+- В фильтре или отчёте выбирают даты «с/по» и часто используют «7 дней», «30 дней» и другие пресеты.
+- Потребитель может хранить и развёрнутый `DateRange`, и исходный `RelativePeriod`.
+
+## Когда не использовать
+
+- Для произвольной раскладки периода используйте `RangeCalendar`.
+- Для одной даты используйте `DatePicker`.
+- Не используйте для выбора только начала периода: компонент отдаёт только полный диапазон.
+
+## Минимальный пример
+
+```tsx
+<DateRangePicker
+  value={range}
+  period={period}
+  onChange={(nextRange, nextPeriod) => {
+    setRange(nextRange);
+    setPeriod(nextPeriod);
+  }}
+  onClear={() => {
+    setRange(null);
+    setPeriod(null);
+  }}
+/>
+```
+
+## Public API
+
+- `value?: DateRange | null`, где границы — ISO-строки; `period?: RelativePeriod | null` связывает выбранный пресет с диапазоном.
+- `onChange(range, period)` получает `period=null` при ручном выборе; `onClear` обязателен для появления кнопки очистки, потому что очистка должна сбросить оба значения: `value` и `period`.
+- `presets`, `timeZone`, `minValue`, `maxValue`, `defaultFocusedValue`, `locale` задают допустимые и относительные периоды.
+- `minValue`, `maxValue` и `defaultFocusedValue` — ISO-строки `ГГГГ-ММ-ДД`, как `value`: `minValue="2026-03-09"`, импортировать `@internationalized/date` не нужно (сам пакет остаётся peer-зависимостью кита). Объект по-прежнему принимается; неразбираемая строка считается незаданной границей.
+- `isDateUnavailable(date)` отмечает конкретные дни недоступными — занятые даты, праздники: в календаре они зачёркнуты и не выбираются. Функция получает объект календаря: `date.toString()` возвращает день строкой `ГГГГ-ММ-ДД`. Такое же свойство есть у `RangeCalendar` и `DatePicker`. Пресеты правило не учитывают: они подрезаются только по `minValue` и `maxValue`, а пресет, захвативший недоступный день, выбирается как есть — если так нельзя, не оставляйте такой пресет в `presets`.
+- `open`/`onOpenChange` позволяют управлять открытием поповера, иначе используется внутреннее состояние.
+
+## Доступность и клавиатура
+
+- Очистка — отдельная кнопка рядом с триггером, а не интерактивный элемент внутри кнопки.
+- Два месяца показываются при ширине экрана от 640 пикселей; не полагайтесь на незавершённый выбор для сетевого запроса.
+- Источники: `src/components/date-time/DateRangePicker.tsx`, `src/components/date-time/DateRangePicker.stories.tsx`.

package/docs/components/date-time/date-time-picker.en.md

@@ -0,0 +1,44 @@
+---
+component: DateTimePicker
+exports: [DateTimePicker, maskTime, normalizeTime]
+category: date-time
+status: stable
+source: src/components/date-time/DateTimePicker.tsx
+story: src/components/date-time/DateTimePicker.stories.tsx
+sourceHash: f7084730cbb6
+---
+
+# DateTimePicker
+
+## Summary for AI
+
+`DateTimePicker` is composed of `DatePicker` and `TimePicker`. The consumer stores the date and time separately: an ISO date without a time zone and an `HH:MM` time string.
+
+## When to use
+
+- You need user input for the publication/event date and time as two independent values.
+- You need shared calendar-date constraints and a disabled state.
+
+## When not to use
+
+- For a single day without a time, use `DatePicker`.
+- For an arbitrary calendar layout, compose `Calendar` and `TimePicker` yourself.
+- Do not treat the result as a ready-made UTC timestamp: the time zone and server-side conversion belong to the domain.
+
+## Minimal example
+
+```tsx
+<DateTimePicker date={date} onDateChange={setDate} time={time} onTimeChange={setTime} />
+```
+
+## Public API
+
+- The contract is `date`, `onDateChange`, `time`, `onTimeChange`; `minValue`, `maxValue` (calendar, day bounds), `disabled`, `hourCycle` (`12` or `24`, as in `TimePicker`), `locale` and `timeZoneLabel` (a time-zone label to the right of the time) are also supported.
+- The `minValue` and `maxValue` bounds are **calendar bounds, that is, day bounds**: calendar cells are dates without a time, and the comparison is by day. `minValue={…T14:00}` in the sense of "no earlier than an hour from now" will not work — the same day at nine in the morning passes. The component accepts no time bounds: "no earlier than an hour from now" depends on a time zone the kit does not know, and on the moment of submission, not rendering. This is a consumer rule.
+- `maskTime(value)` is a public helper that coerces input to the `HH:MM` format; `normalizeTime(value, fallback)` normalizes a valid time. These are helpers, not components.
+- Use strict date and time APIs; do not merge them into a `Date` at the UI boundary.
+
+## Accessibility and keyboard
+
+- The child pickers keep their own accessible names and keyboard contracts.
+- See `src/components/date-time/DateTimePicker.tsx`, `src/components/date-time/DateTimePicker.stories.tsx`, `tests/matrix.tsx`.

package/docs/components/date-time/date-time-picker.md

@@ -0,0 +1,43 @@
+---
+component: DateTimePicker
+exports: [DateTimePicker, maskTime, normalizeTime]
+category: date-time
+status: stable
+source: src/components/date-time/DateTimePicker.tsx
+story: src/components/date-time/DateTimePicker.stories.tsx
+---
+
+# DateTimePicker
+
+## Кратко для AI
+
+`DateTimePicker` собран из `DatePicker` и `TimePicker`. Потребитель хранит дату и время отдельно: ISO-дата без часового пояса и строка времени `HH:MM`.
+
+## Когда использовать
+
+- Нужен пользовательский ввод даты и времени публикации/события как два независимых значения.
+- Нужны единые ограничения календарной даты и выключенное состояние.
+
+## Когда не использовать
+
+- Для одного дня без времени используйте `DatePicker`.
+- Для произвольной раскладки календаря составьте `Calendar` и `TimePicker` самостоятельно.
+- Не трактуйте результат как готовый UTC timestamp: часовой пояс и серверная конвертация принадлежат домену.
+
+## Минимальный пример
+
+```tsx
+<DateTimePicker date={date} onDateChange={setDate} time={time} onTimeChange={setTime} />
+```
+
+## Public API
+
+- Контракт состоит из `date`, `onDateChange`, `time`, `onTimeChange`; также `minValue`, `maxValue` (календарные, дневные границы), `disabled`, `hourCycle` (`12` или `24`, как у `TimePicker`), `locale` и `timeZoneLabel` (подпись зоны справа от времени).
+- Границы `minValue` и `maxValue` **календарные, то есть дневные**: ячейки календаря — даты без времени, и сравнение идёт по дню. `minValue={…T14:00}` в смысле «не раньше чем через час» не сработает — тот же день с девятью утра пройдёт. Границ времени компонент не принимает: «не раньше чем через час» зависит от часового пояса, которого кит не знает, и от момента отправки, а не отрисовки. Это правило потребителя.
+- `maskTime(value)` — public helper, приводящий ввод к виду `HH:MM`; `normalizeTime(value, fallback)` нормализует допустимое время. Это helpers, не компоненты.
+- Используйте строгие API даты и времени, а не соединяйте их в `Date` на UI-границе.
+
+## Доступность и клавиатура
+
+- Дочерние поля сохраняют своё доступное имя и клавиатурное поведение.
+- См. `src/components/date-time/DateTimePicker.tsx`, `src/components/date-time/DateTimePicker.stories.tsx`, `tests/matrix.tsx`.

package/docs/components/date-time/range-calendar.en.md

@@ -0,0 +1,47 @@
+---
+component: RangeCalendar
+exports: [RangeCalendar]
+category: date-time
+status: stable
+source: src/components/date-time/RangeCalendar.tsx
+story: src/components/date-time/RangeCalendar.stories.tsx
+sourceHash: 0d83dbf9735c
+---
+
+# RangeCalendar
+
+## Summary for AI
+
+`RangeCalendar` is a building block for a single continuous React Aria `DateValue` range. Its `onChange` is called only for a completed period; it does not replace the ready-made `DateRangePicker` with its trigger and presets.
+
+## When to use
+
+- You need a custom composition of a period calendar inside your own panel.
+- You need one or two visible months (`months={1 | 2}`) and all of React Aria's constraints.
+
+## When not to use
+
+- For a standard period field with presets and clearing, use `DateRangePicker`.
+- For a single date, use `Calendar`/`DatePicker`.
+
+## Minimal example
+
+```tsx
+<RangeCalendar value={range} onChange={setRange} months={2} locale="ru-RU" />
+```
+
+## Public API
+
+- Inherits React Aria's `RangeCalendarProps<DateValue>`: controlled `value`, `defaultValue`, `onChange`, `minValue`, `maxValue`, unavailable dates.
+- An empty controlled value is passed as `null`.
+- **A period can be objects or ISO strings.** `value` and `defaultValue` accept `{ start, end }`, where the bounds are either `@internationalized/date` objects or `YYYY-MM-DD` strings (the strings are the same as `DateRange` in `DateRangePicker`). `minValue`, `maxValue` and `defaultFocusedValue` accept a string too (`minValue="2026-03-09"`); there is no need to import `@internationalized/date` (the package itself stays a peer dependency of the kit). An unparsable string does not throw: a period with such a bound is treated as empty (half a range is never selected) and the bound as not set.
+- `onChange(range, iso)` is called once both bounds are chosen. The first argument is `{ start, end }` of calendar objects, as in React Aria (it always was); the second is the same period as a pair of ISO strings, that is, the same `DateRange`. Whoever stores the period as strings needs only `onChange={(_, iso) => setRange(iso)}`. What `onChange` receives does not depend on whether `value` is passed as objects or strings: existing calls with objects work unchanged.
+- `isDateUnavailable` receives a calendar object: `date.toString()` returns the day as a `YYYY-MM-DD` string.
+- `months` is 1 or 2 and defaults to 1; without `locale`, the locale comes from above: from `UiProvider`, the consumer's `I18nProvider` or the browser; `locale` overrides it for this calendar.
+- A server-rendered calendar hydrates cleanly. The heading above the grid ("March – April 2026") is the same on the server and in the browser: `Intl` in Node puts thin spaces around the dash, and the kit converts them to regular ones. The browser renders the "today" dot after mounting: the server does not know what day it is for the reader, so the first render has no dot.
+
+## Accessibility and keyboard
+
+- React Aria handles range selection, grid semantics and the keyboard.
+- The start and end of the range look different from the middle; do not replace this with arbitrary cell classes.
+- See `src/components/date-time/RangeCalendar.tsx`, `src/components/date-time/RangeCalendar.stories.tsx`, `tests/matrix.tsx`.

package/docs/components/date-time/range-calendar.md

@@ -0,0 +1,46 @@
+---
+component: RangeCalendar
+exports: [RangeCalendar]
+category: date-time
+status: stable
+source: src/components/date-time/RangeCalendar.tsx
+story: src/components/date-time/RangeCalendar.stories.tsx
+---
+
+# RangeCalendar
+
+## Кратко для AI
+
+`RangeCalendar` — building block для одного непрерывного диапазона React Aria `DateValue`. Его `onChange` срабатывает только для завершённого периода; он не заменяет готовый `DateRangePicker` с триггером и пресетами.
+
+## Когда использовать
+
+- Нужна нестандартная композиция календаря периода внутри собственной панели.
+- Нужен один или два видимых месяца (`months={1 | 2}`) и все ограничения React Aria.
+
+## Когда не использовать
+
+- Для стандартного поля выбора периода с пресетами и очисткой используйте `DateRangePicker`.
+- Для одной даты используйте `Calendar`/`DatePicker`.
+
+## Минимальный пример
+
+```tsx
+<RangeCalendar value={range} onChange={setRange} months={2} locale="ru-RU" />
+```
+
+## Public API
+
+- Наследует `RangeCalendarProps<DateValue>` React Aria: controlled `value`, `defaultValue`, `onChange`, `minValue`, `maxValue`, unavailable dates.
+- Пустое controlled значение передаётся как `null`.
+- **Период — объекты или ISO-строки.** `value` и `defaultValue` принимают `{ start, end }`, где границы — объекты `@internationalized/date` или строки `ГГГГ-ММ-ДД` (строки такие же, как `DateRange` у `DateRangePicker`). `minValue`, `maxValue` и `defaultFocusedValue` тоже принимают строку: `minValue="2026-03-09"`, импортировать `@internationalized/date` не нужно (сам пакет остаётся peer-зависимостью кита). Неразбираемая строка не бросает исключение: период с такой границей считается пустым (половина диапазона выбранной не бывает), граница — незаданной.
+- `onChange(range, iso)` вызывается, когда выбраны обе границы. Первый аргумент — `{ start, end }` объектов календаря, как у React Aria (так было всегда), второй — тот же период парой ISO-строк, тот самый `DateRange`. Хранящему период строками достаточно `onChange={(_, iso) => setRange(iso)}`. Что получает `onChange`, не зависит от того, объектами или строками передан `value`: прежние вызовы с объектами работают без правок.
+- `isDateUnavailable` получает объект календаря: `date.toString()` возвращает день строкой `ГГГГ-ММ-ДД`.
+- `months` по умолчанию 1, допустимы 1 и 2; без `locale` локаль приходит сверху: от `UiProvider`, `I18nProvider` потребителя или браузера; `locale` перебивает её для этого календаря.
+- Отрисованный на сервере календарь проходит гидратацию. Заголовок над сеткой («March – April 2026») одинаков на сервере и в браузере: `Intl` в Node ставит вокруг тире тонкие пробелы, и кит приводит их к обычным. Точку «сегодня» ставит браузер после монтирования: сервер не знает, какой день у читателя, поэтому первый кадр рисуется без точки.
+
+## Доступность и клавиатура
+
+- React Aria управляет диапазонным выбором, семантикой сетки и клавиатурой.
+- Начало и конец диапазона отличаются от середины визуально; не заменяйте произвольными классами ячеек.
+- См. `src/components/date-time/RangeCalendar.tsx`, `src/components/date-time/RangeCalendar.stories.tsx`, `tests/matrix.tsx`.

package/docs/components/date-time/time-picker.en.md

@@ -0,0 +1,47 @@
+---
+component: TimePicker
+exports: [TimePicker, upcomingSlots]
+category: date-time
+status: stable
+source: src/components/date-time/TimePicker.tsx
+story: src/components/date-time/TimePicker.stories.tsx
+sourceHash: 948ee600b428
+---
+
+# TimePicker
+
+## Summary for AI
+
+`TimePicker` is a time field with a mask and a list of upcoming slots. The value the component accepts and returns is an `HH:MM` string; input is normalized on blur or confirmation. An empty field stays empty: since 3.6.0, moving focus out of it does not fill in `00:00`.
+
+## When to use
+
+- The user can quickly type an exact time or pick a convenient slot.
+- The time is stored separately from the calendar date, for example in `DateTimePicker`.
+
+## When not to use
+
+- For a complete point in time that includes a date, use `DateTimePicker`.
+- For a free-form string that is not necessarily a time, use `TextControl`.
+
+## Minimal example
+
+```tsx
+<TimePicker value={time} onChange={setTime} step={30} aria-label="Publication time" />
+```
+
+## Public API
+
+- `value?: string | null`; `onChange(time: string)` is required; `step` defaults to 30 minutes.
+- `hourCycle?: 12 | 24` is the clock of the field and the list; the default is `24` (`14:30`). With `12`, the field and the slots show `2:30 PM`; you can type `230p` or `2:30 PM`, and a typed 24-hour time (`14:30`) is accepted too. This affects only display and input: `value` and `onChange` stay `HH:MM`. The `AM` and `PM` labels and the `h:mm AM` mask come from the catalog (`timePicker.am`, `timePicker.pm`, `timePicker.placeholder12`). If no period is typed, the period of the previous value is used, and `AM` for an empty field.
+- `placeholder` and `aria-label` come from the message catalog (`timePicker.placeholder`,
+  `timePicker.label`): without a provider they are `HH:MM` and "Time", with `@olddevs/ui/locales/ru` —
+  `ЧЧ:ММ` and "Время". A prop overrides the catalog string individually. `disabled` and `className` are available.
+- `invalid` shows the field in an error state: the line under the time turns red (including when focused), and `aria-invalid` is set on the field. The validation rule stays with the consumer. Inside a `FormField` with `error` the prop is not needed: the flag comes from the form, as it does for `TextControl` and `NumberInput`, and an explicit `invalid={false}` clears it. The form's hint and error are also announced with the field — their `id` goes into `aria-describedby`.
+- `upcomingSlots(step, now)` is a public utility that returns the full 24-hour list, starting from the nearest future slot. It is useful for presentation, but it is not a UI component.
+
+## Accessibility and keyboard
+
+- The input has combobox semantics; focus stays in the field, and the list reports the active slot through `aria-activedescendant`.
+- The Down Arrow and Up Arrow keys move through the slots, Enter picks a slot or confirms the typed text, Escape closes the list and keeps bubbling up to the parent overlay.
+- Sources: `src/components/date-time/TimePicker.tsx`, `src/components/date-time/TimePicker.stories.tsx`, `tests/timepicker.test.tsx`.

package/docs/components/date-time/time-picker.md

@@ -0,0 +1,51 @@
+---
+component: TimePicker
+exports: [TimePicker, upcomingSlots]
+category: date-time
+status: stable
+source: src/components/date-time/TimePicker.tsx
+story: src/components/date-time/TimePicker.stories.tsx
+---
+
+# TimePicker
+
+## Кратко для AI
+
+`TimePicker` — поле времени с маской и списком ближайших слотов. Значение, которое компонент принимает и отдаёт, — строка `HH:MM`; ввод нормализуется на blur или подтверждение. Пустое поле пустым и остаётся: с 3.6.0 уход фокуса из него не подставляет `00:00`.
+
+## Когда использовать
+
+- Пользователь может быстро напечатать точное время или выбрать удобный слот.
+- Время хранится отдельно от календарной даты, например в `DateTimePicker`.
+
+## Когда не использовать
+
+- Для полного момента времени с датой используйте `DateTimePicker`.
+- Для свободной строки, не обязательно времени, используйте `TextControl`.
+
+## Минимальный пример
+
+```tsx
+<TimePicker value={time} onChange={setTime} step={30} aria-label="Время публикации" />
+```
+
+## Public API
+
+- `value?: string | null`; `onChange(time: string)` обязателен; `step` по умолчанию 30 минут.
+- `hourCycle?: 12 | 24` — часы поля и списка; по умолчанию `24` (`14:30`). При `12` поле и слоты
+  показывают `2:30 PM`, печатать можно `230p` или `2:30 PM`, а набранное 24-часовое время
+  (`14:30`) тоже принимается. Это только показ и ввод: `value` и `onChange` остаются `HH:MM`.
+  Подписи `AM` и `PM` и маска `h:mm AM` берутся из каталога (`timePicker.am`, `timePicker.pm`,
+  `timePicker.placeholder12`). Если период не набран, берётся период прежнего значения, а у
+  пустого поля — `AM`.
+- `placeholder` и `aria-label` берутся из каталога сообщений (`timePicker.placeholder`,
+  `timePicker.label`): без провайдера это `HH:MM` и «Time», с `@olddevs/ui/locales/ru` —
+  `ЧЧ:ММ` и «Время». Проп переопределяет каталог точечно. `disabled`, `className` доступны.
+- `invalid` показывает поле в состоянии ошибки: линия под временем краснеет (и в фокусе тоже), на поле ставится `aria-invalid`. Правило проверки остаётся у потребителя. Внутри `FormField` с `error` проп не нужен: признак приходит из формы, как у `TextControl` и `NumberInput`, а явный `invalid={false}` его снимает. Пояснение и ошибка формы ещё и объявляются с полем — их `id` уходит в `aria-describedby`.
+- `upcomingSlots(step, now)` — публичная утилита, которая возвращает полный суточный список, начиная с ближайшего будущего слота. Она полезна для представления, но это не UI-компонент.
+
+## Доступность и клавиатура
+
+- Поле ввода имеет семантику combobox; фокус остаётся в поле, а список сообщает активный слот через `aria-activedescendant`.
+- Стрелки вниз и вверх ходят по слотам, Enter выбирает слот или подтверждает введённый текст, Escape закрывает список и продолжает всплытие к родительскому оверлею.
+- Источники: `src/components/date-time/TimePicker.tsx`, `src/components/date-time/TimePicker.stories.tsx`, `tests/timepicker.test.tsx`.