@skbkontur/react-ui 6.2.0 → 6.3.0

package/components/TimePicker/TimePicker.d.ts

@@ -0,0 +1,144 @@
+import type { AriaAttributes, HTMLAttributes, ReactNode } from 'react';
+import React from 'react';
+import type { CommonProps } from '../../internal/CommonWrapper/index.js';
+import type { SizeProp } from '../../lib/types/props.js';
+import type { MenuItemState } from '../MenuItem/index.js';
+import { type TimeFormat, type TimeItem, type TimeItemValue, type TimePickerSource } 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 с массивом.
+     * Запрос — это введенные цифры сегментов с сохранением их позиций: `12`, `12:3`, а если заполнены только минуты — `:30`.
+     * Элементы задаются либо строками со временем — `'09:00'`, — либо объектами `{ value, label?, disabled? }`
+     * с любыми дополнительными полями; смешивать формы в одном источнике нельзя, это ошибка типов.
+     * В `onValueChange` приходит только время выбранного элемента: сам элемент можно найти в `source` по нему.
+     * Кроме значений времени можно передать React-элементы — например `MenuHeader` или `MenuItem`:
+     * они отображаются в меню, но не участвуют в фильтрации и выборе значения.
+     * Фильтрацию, индикацию загрузки и повторные запросы компонент берет на себя,
+     * подробности — в разделе документации про выпадающий список.
+     * Замена самой функции уже открытый список не перезапрашивает: как в `ComboBox`,
+     * актуальная функция используется при следующем запросе. */
+    source?: TimePickerSource<T>;
+    /** Отрисовывает элемент со временем в выпадающем списке. Не применяется к React-элементам из `source`.
+     * Время элемента приведено к формату поля, как и везде в компоненте:
+     * элемент `'9:00'` приходит как `'09:00'`, а `{ value: '09:00:00' }` в формате `HH:mm` — как `{ value: '09:00' }`.
+     * Остальные поля элемента сохраняются. */
+    renderItem?: (item: T, state: MenuItemState) => ReactNode;
+    /** Задает нижнюю границу времени. Элементы за границей становятся заблокированными. */
+    minTime?: string;
+    /** Задает верхнюю границу времени. Элементы за границей становятся заблокированными. */
+    maxTime?: string;
+    /** Задает значение поля: время в формате `HH:mm[:ss]`.
+     * Пустое значение можно передать как `''` или `null`.
+     * Если проп не задан, компонент неконтролируемый: он хранит значение сам и сообщает о нем через `onValueChange`. */
+    value?: string | null;
+    /** Устанавливает фокус на поле ввода после окончания загрузки страницы @default false */
+    autoFocus?: boolean;
+    /** Делает компонент заблокированным. */
+    disabled?: boolean;
+    /** Переводит контрол в состояние валидации ошибки. */
+    error?: boolean;
+    /** Переводит контрол в состояние валидации предупреждения. */
+    warning?: boolean;
+    /** Включает нативный системный выбор времени в мобильной верстке.
+     * Мобильная верстка определяется медиавыражением темы, как в остальных адаптивных контролах. */
+    useMobileNativeTimePicker?: boolean;
+    /** Расположение выпадающего меню. */
+    menuPos?: 'top' | 'bottom';
+    /** Выравнивание выпадающего меню. */
+    menuAlign?: 'left' | 'right';
+    /** Ширина выпадающего меню. По умолчанию — минимальная ширина поля ввода, расширяется по контенту. */
+    menuWidth?: string | number;
+    /** Задает ширину поля. */
+    width?: string | number;
+    /** Переопределяет иконку или скрывает, если передать `null`.
+     * Пока элементы уже показаны, а новый запрос к функции-источнику еще выполняется,
+     * вместо иконки показывается индикатор загрузки. */
+    rightIcon?: React.ReactNode | (() => React.ReactNode);
+    /** Устанавливает суффикс после значения и перед иконкой. */
+    suffix?: ReactNode;
+    /** Размер поля ввода и выпадающего меню. */
+    size?: SizeProp;
+    /** Устанавливает радиус скруглений углов.
+     * @ignore */
+    corners?: Partial<Pick<React.CSSProperties, 'borderTopRightRadius' | 'borderBottomRightRadius' | 'borderBottomLeftRadius' | 'borderTopLeftRadius'>>;
+    /** Задает функцию, которая вызывается при нажатии на контрол. */
+    onClick?(event: React.MouseEvent<HTMLElement>): void;
+    /**
+     * Событие изменения значения `value`.
+     * Вызывается при коммите значения: потере фокуса, нажатии Enter, выборе элемента из списка
+     * или изменении в нативном пикере.
+     * Время полностью нормализовано до формата `HH:mm[:ss]`, а пустое значение приходит пустой строкой.
+     * Элементы-объекты из `source` наружу не приходят: по времени их можно найти в самом `source`.
+     */
+    onValueChange?(time: string): void;
+    /**
+     * Событие изменения значения в процессе ввода.
+     * Значение частично нормализуется по сегментам, например `1` => `01`, незаполненный хвост отбрасывается.
+     * Промежуточное значение может не соответствовать полной форме `HH:mm[:ss]`, поэтому тип — произвольная строка.
+     */
+    onInputValueChange?(value: string): void;
+    /**
+     * Событие некорректного ввода: пользователь ввел или вставил значение, которое не может быть временем.
+     * Вызывается с нажатой клавишей — например `а` или `,` — либо со значением из буфера,
+     * из которого не получилось собрать время.
+     * Значение вне диапазона `minTime`/`maxTime` некорректным вводом не считается,
+     * его можно проверить через `TimePicker.validate`.
+     * Вторым аргументом передается метод вспыхивания рамки поля.
+     * Если обработчик не задан, поле вспыхивает само.
+     * Обработчик может подставить значение вместо некорректного ввода — например разобрать вставку
+     * в собственном формате: возвращенное время коммитится и приходит в `onValueChange`,
+     * `null` очищает поле, а `undefined` оставляет значение прежним.
+     */
+    onUnexpectedInput?(value: string, blink: () => void): void | string | null;
+    /**
+     * Событие потери фокуса.
+     * Вызывается после коммита значения и следующего за ним рендера,
+     * поэтому обработчик видит уже измененное значение — например при выборе элемента в мобильном попапе.
+     * Из-за этого событие приходит отложенно и его `currentTarget` уже пуст: элемент читайте из `target`.
+     */
+    onBlur?(event: React.FocusEvent<HTMLElement>): void;
+    /** Событие получения фокуса. */
+    onFocus?(event: React.FocusEvent<HTMLElement>): void;
+    /** Событие нажатия клавиши. */
+    onKeyDown?(event: React.KeyboardEvent<HTMLElement>): void;
+    /** Событие вставки из буфера. */
+    onPaste?(event: React.ClipboardEvent<HTMLElement>): void;
+}
+export interface TimePickerRef {
+    /** Устанавливает фокус на поле ввода.
+     * С опцией `withoutOpenDropdown` фокус не открывает выпадающее меню. */
+    focus(options?: {
+        withoutOpenDropdown?: boolean;
+    }): void;
+    /** Снимает фокус с поля ввода. */
+    blur(): void;
+    /** Открывает выпадающее меню, установив фокус на поле.
+     * В режиме нативного пикера открывает системный пикер. */
+    open(): void;
+    /** Закрывает выпадающее меню. */
+    close(): void;
+    /** Запускает анимацию blink у поля ввода времени. */
+    blink(): void;
+    /** Возвращает корневой DOM-узел компонента. */
+    getRootNode(): HTMLElement | null;
+}
+export type TimePicker = TimePickerRef;
+interface TimePickerComponent {
+    /** Строковый режим: элементы 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`. */
+    validate: typeof validateTimePicker;
+}
+/** Поле с временем помогает пользователю быстро и удобно указать время в правильном формате.
+ * В поле можно ввести время с клавиатуры либо выбрать из выпадающего списка,
+ * передав массив или функцию в проп `source`.
+ */
+export declare const TimePicker: TimePickerComponent;
+export {};