@skbkontur/react-ui 6.1.7-65057.0 → 6.1.7-8e9d5.0

package/components/TimePicker/TimePicker.d.ts

@@ -4,28 +4,23 @@ import type { CommonProps } from '../../internal/CommonWrapper/index.js';
 import type { SizeProp } from '../../lib/types/props.js';
 import { type NoInfer } from '../../lib/utils.js';
 import type { MenuItemState } from '../MenuItem/index.js';
-import { type TimeFormat, type TimeItemValue, type TimePickerSource, type TimePickerValue, type TimePickerValueToItem } from './helpers/TimePicker.shared.js';
+import { type TimeFormat, type TimeItem, type TimePickerEmptyItem, type TimeItemValue, type TimePickerSource, type TimePickerValue, type TimePickerValueToItem } from './helpers/TimePicker.shared.js';
 import { validateTimePicker } from './helpers/validateTimePicker.js';
 export interface TimePickerProps<T extends TimeItemValue = string> extends CommonProps, Pick<AriaAttributes, 'aria-describedby' | 'aria-label'>, Pick<HTMLAttributes<HTMLElement>, 'id'> {
     /** Устанавливает формат времени @default HH:mm */
     format?: TimeFormat;
-    /** Задает источник элементов выпадающего списка.
-     * Можно передать массив или функцию, которая получает текущий запрос и возвращает массив либо Promise с массивом.
+    /** Задает источник элементов выпадающего списка: массив либо функцию запроса,
+     * которая возвращает массив или Promise с массивом.
      * Запрос — это введенные цифры сегментов с сохранением их позиций: `12`, `12:3`, а если заполнены только минуты — `:30`.
-     * Элемент задается строкой со временем — `'09:00'` — или объектом `{ value, label?, disabled? }`
-     * с любыми дополнительными полями. Выбранный элемент приходит в `onValueChange` в той же форме.
-     * Кроме значений времени можно передать React-элементы или функции, возвращающие React-элемент:
-     * например, `MenuHeader`, `MenuFooter`, `MenuSeparator` или `MenuItem`.
-     * Такие элементы отображаются в меню, но не участвуют в фильтрации и выборе значения.
-     * Полученные элементы всегда фильтруются компонентом одинаково для массива и функции:
-     * введенные цифры сегмента сравниваются с началом соответствующего сегмента элемента.
-     * В выпадающем списке не может быть двух элементов с одинаковым временем:
-     * из элементов с одинаковым временем компонент оставляет первый.
-     * Пустые элементы из условного рендера — `isVisible && item` — пропускаются.
-     * Пока Promise не разрешился и предыдущих результатов нет, в выпадающем меню показывается спиннер загрузки.
-     * Если предыдущие результаты есть, подходящие элементы остаются видимыми до прихода новых,
-     * а индикация загрузки показывается в правой иконке поля.
-     * Замена функции не перезапрашивает уже открытый список: актуальная функция используется при следующем запросе. */
+     * Элементы задаются либо строками со временем — `'09:00'`, — либо объектами `{ value, label?, disabled? }`
+     * с любыми дополнительными полями; смешивать формы в одном источнике нельзя, это ошибка типов.
+     * Выбранный элемент приходит в `onValueChange` в той же форме.
+     * Кроме значений времени можно передать React-элементы — например `MenuHeader` или `MenuItem`:
+     * они отображаются в меню, но не участвуют в фильтрации и выборе значения.
+     * Фильтрацию, индикацию загрузки и повторные запросы компонент берет на себя,
+     * подробности — в разделе документации про выпадающий список.
+     * Замена самой функции уже открытый список не перезапрашивает: как в `ComboBox`,
+     * актуальная функция используется при следующем запросе. */
     source?: TimePickerSource<T>;
     /** Отрисовывает значение времени в выпадающем списке. Не применяется к React-элементам из `source`. */
     renderItem?: (item: T, state: MenuItemState) => ReactNode;
@@ -43,9 +38,8 @@ export interface TimePickerProps<T extends TimeItemValue = string> extends Commo
      * ручной ввод, изменение стрелками, вставка из буфера, нативный пикер.
      * По умолчанию компонент повторяет форму элементов `source` и `value`:
      * для строк отдает строку, для объектов — `{ value }`.
-     * Форму элементов функции-источника компонент узнает только после первого ответа,
-     * поэтому до него — и всегда в режиме нативного пикера — время без этого пропа уходит строкой.
-     * Задавайте этот проп, если элементы содержат поля, кроме `value`, `label` и `disabled`.
+     * Задавайте этот проп, если элементы содержат поля, кроме `value`, `label` и `disabled`:
+     * форму элементов функции-источника компонент узнает только после ее первого ответа.
      * @default (value) => value | ({ value }) */
     valueToItem?: TimePickerValueToItem<T>;
     /** Устанавливает фокус на поле ввода после окончания загрузки страницы @default false */
@@ -56,7 +50,8 @@ export interface TimePickerProps<T extends TimeItemValue = string> extends Commo
     error?: boolean;
     /** Переводит контрол в состояние валидации предупреждения. */
     warning?: boolean;
-    /** Включает нативный системный выбор времени на мобильных устройствах. */
+    /** Включает нативный системный выбор времени в мобильной верстке.
+     * Мобильная верстка определяется медиавыражением темы, как в остальных адаптивных контролах. */
     useMobileNativeTimePicker?: boolean;
     /** Расположение выпадающего меню. */
     menuPos?: 'top' | 'bottom';
@@ -83,14 +78,15 @@ export interface TimePickerProps<T extends TimeItemValue = string> extends Commo
      * Событие изменения значения `value`.
      * Вызывается при коммите значения: потере фокуса, нажатии Enter, выборе элемента из списка
      * или изменении в нативном пикере.
-     * Первым аргументом приходит элемент в той же форме, в которой элементы переданы в `source`:
-     * при выборе из выпадающего списка — тот же элемент, в остальных случаях — результат `valueToItem`,
-     * а при пустом значении — `null`.
-     * Вторым аргументом приходит полностью нормализованное время в формате `HH:mm[:ss]` или пустая строка.
+     * Элемент приходит в той же форме, в которой элементы переданы в `source`:
+     * при выборе из выпадающего списка — тот же элемент, в остальных случаях — результат `valueToItem`.
+     * Пустое значение приходит пустой строкой в строковой форме и `null` — в объектной.
+     * Время элемента полностью нормализовано до формата `HH:mm[:ss]`,
+     * у элемента-объекта его можно прочитать из `item.value`.
      * Тип элемента выводится из `source` и `value`, но не из этого обработчика,
      * иначе `onValueChange={setItem}` сузил бы его до `TimeItem`.
      */
-    onValueChange?(item: NoInfer<T> | null, value: string): void;
+    onValueChange?(item: NoInfer<T> | TimePickerEmptyItem<T>): void;
     /**
      * Событие изменения значения в процессе ввода.
      * Значение частично нормализуется по сегментам, например `1` => `01`, незаполненный хвост отбрасывается.
@@ -105,9 +101,17 @@ export interface TimePickerProps<T extends TimeItemValue = string> extends Commo
      * его можно проверить через `TimePicker.validate`.
      * Вторым аргументом передается метод вспыхивания рамки поля.
      * Если обработчик не задан, поле вспыхивает само.
+     * Обработчик может подставить значение вместо некорректного ввода — например разобрать вставку
+     * в собственном формате: возвращенный элемент коммитится и приходит в `onValueChange`,
+     * `null` очищает поле, а `undefined` оставляет значение прежним.
+     */
+    onUnexpectedInput?(value: string, blink: () => void): void | NoInfer<T> | null;
+    /**
+     * Событие потери фокуса.
+     * Вызывается после коммита значения и следующего за ним рендера,
+     * поэтому обработчик видит уже измененное значение — например при выборе элемента в мобильном попапе.
+     * Из-за этого событие приходит отложенно и его `currentTarget` уже пуст: элемент читайте из `target`.
      */
-    onUnexpectedInput?(value: string, blink: () => void): void;
-    /** Событие потери фокуса. */
     onBlur?(event: React.FocusEvent<HTMLElement>): void;
     /** Событие получения фокуса. */
     onFocus?(event: React.FocusEvent<HTMLElement>): void;
@@ -136,7 +140,10 @@ export interface TimePickerRef {
 }
 export type TimePicker = TimePickerRef;
 interface TimePickerComponent {
-    <T extends TimeItemValue = string>(props: TimePickerProps<T> & React.RefAttributes<TimePickerRef>): React.ReactElement | null;
+    /** Строковый режим: элементы source — строки со временем. */
+    (props: TimePickerProps<string> & React.RefAttributes<TimePickerRef>): React.ReactElement | null;
+    /** Объектный режим: элементы source — объекты, расширяющие `{ value: string }`. */
+    <T extends TimeItem>(props: TimePickerProps<T> & React.RefAttributes<TimePickerRef>): React.ReactElement | null;
     displayName?: string;
     __KONTUR_REACT_UI__: string;
     /** Проверяет, что значение полностью заполнено, соответствует формату и попадает в диапазон `minTime`/`maxTime`. */