diff --git a/src/components/Calendar/README-ru.md b/src/components/Calendar/README-ru.md new file mode 100644 index 00000000..2c19e90d --- /dev/null +++ b/src/components/Calendar/README-ru.md @@ -0,0 +1,208 @@ + + +# Calendar + + + +```tsx +import {Calendar} from '@gravity-ui/date-components'; +``` + +`Calendar` — это гибкий и удобный компонент календаря для React-приложений. Он позволяет пользователям легко выбирать, просматривать и настраивать даты, что делает его отличным решением для планирования событий, систем бронирования и других задач, требующих выбора даты. Компонент становится контролируемым при установке свойства `value`. Если это значение не задано, компонент используется в неконтролируемом режиме. В этом случае задать начальное состояние можно через дополнительное свойство `defaultValue`. По умолчанию `Calendar` — неконтролируемый компонент. + +### Полезная рекомендация + +Для установки дат в правильном формате может понадобиться подключение вспомогательных функций из [библиотеки Date Utils](https://gravity-ui.com/libraries/date-utils). + +```tsx +import {dateTimeParse} from '@gravity-ui/date-utils'; +``` + +## Размер + +Для изменения размера `Calendar` используйте свойство `size`. Размер по умолчанию — `m`. + + + + + +```tsx + + + +``` + + + +## Значение + +### Минимальное и максимальное значения + +Свойство `minValue` позволяет задать наиболее ранние дату и время, которые может ввести пользователь. Свойство `maxValue`, в свою очередь, определяет наиболее поздние дату и время, которые доступны для ввода. Все остальные значения будут недоступны для пользователя. + + + + + +```tsx + +``` + + + +## Режим отображения + +Определяет временной интервал, который будет отображаться в компоненте `Calendar`. С помощью свойства `mode` можно задать нужный интервал для контролируемого компонента. Для неконтролируемого компонента значение этого свойства указывать не требуется, а начальный режим отображения можно задать через `defaultMode`. + +`days` — режим по умолчанию для `Calendar`. Отображает календарь с днями месяца. + +`months` — отображает календарь с месяцами года. + +`quarters` — отображает календарь с кварталами по годам (недоступно в качестве значения для `defaultMode`). + +`years` — отображает календарь с несколькими годами для выбора. + +С помощью свойства `modes` можно указать, какие режимы будут доступны пользователю. + + + + + +```tsx + +``` + + + +## Состояния + +### `Disabled` (отключен) + +Состояние `Calendar`, при котором пользователь не может взаимодействовать с компонентом. + + + + + +```tsx + +``` + + + +### `readOnly` (только для чтения) + +`readOnly` — это булев атрибут, который при установке в `true` делает компонент `Calendar` недоступным для редактирования пользователем. Это означает, что пользователи видят текущее значение поля, но не могут его изменить. + + + + + +```tsx + +``` + + + +## Значение, получающее фокус + +Позволяет выбрать дату, на которой будет установлен фокус представления `Calendar`. Если необходимо контролировать это значение, используйте свойство `focusedValue`. Для неконтролируемого компонента начальное значение, получающее фокус, можно установить через `defaultFocusedValue`. + + + + + +```tsx + +``` + + + +## Часовой пояс + +`timeZone` — это свойство, позволяющее задать часовой пояс для значения в поле ввода. Подробнее о часовых поясах см. [здесь](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------: | :---------------------------------------------------------: | +| aria-describedby | Атрибут `aria-describedby` для контрола. | `string` | | +| aria-details | Атрибут `aria-details` для контрола. | `string` | | +| aria-label | Атрибут `aria-label` для контрола. | `string` | | +| aria-labelledby | Атрибут `aria-labelledby` для контрола. | `string` | | +| autoFocus | Атрибут `autofocus` для контрола. | `boolean` | | +| className | Имя класса обертки контрола. | `string` | | +| [defaultFocusedValue](#focused-value) | Дата, на которую устанавливается фокус при первом открытии календаря (если компонент неконтролируемый). | `DateTime` | | +| [defaultMode](#mode) | Начальный режим отображения календаря. | `days` `months` `quarters` `years` | | +| [defaultValue](#value) | Задает начальное значение для неконтролируемого компонента. | `DateTime` | | +| [disabled](#disabled) | Указывает на то, что пользователь не может взаимодействовать с контролом. | `boolean` | `false` | +| [focusedValue](#focused-value) | Устанавливает вид неконтролируемого компонента по умолчанию, включающий данное значение. | `DateTime` `null` | | +| id | Атрибут `id` для контрола. | `string` | | +| isDateUnavailable | Функция обратного вызова для каждой даты в календаре. Если она возвращает `true`, дата недоступна для выбора. | `((date: DateTime) => boolean)` | | +| isWeekend | Функция обратного вызова для каждой даты в календаре. Если она возвращает `true`, дата является выходным днем. | `((date: DateTime) => boolean)` | | +| [maxValue](#min-and-max-value) | Верхний предел выбора даты. | `DateTime` | | +| [minValue](#min-and-max-value) | Нижний предел выбора даты. | `DateTime` | | +| [mode](#mode) | Определяет временной интервал, который будет отображаться в контролируемом компоненте `Calendar`. | `days` `months` `quarters` `years` | | +| modes | Режимы, доступные для выбора пользователем. | `Partial>` | `{days: true, months: true, quarters: false, years: true }` | +| onBlur | Срабатывает, когда контрол теряет фокус. Передает событие фокуса в качестве аргумента обратного вызова. | `((e: FocusEvent) => void)` | | +| onFocus | Срабатывает, когда контрол получает фокус. Передает событие фокуса в качестве аргумента обратного вызова. | `((e: FocusEvent) => void)` | | +| onFocusUpdate | Срабатывает при изменении даты, на которой фокусируется контрол. | `((date: DateTime) => void)` | | +| onUpdate | Срабатывает при изменении значения. | `((value: DateTime) => void` | | +| onUpdateMode | Срабатывает при изменении режима. | `((value: 'days' \| 'months' \| 'quarters' \| 'years' ) => void` | | +| [readOnly](#readonly) | Определяет, можно ли изменять значение календаря. | `boolean` | `false` | +| [size](#size) | Размер контрола. | `"m"` `"l"` `"xl"` | `"m"` | +| style | Задает инлайн-стиль для элемента. | `CSSProperties` | | +| [timeZone](#time-zone) | Задает часовой пояс. Подробнее о часовых поясах см. [здесь](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). | `string` | | +| [value](#calendar) | Значение контрола. | `DateTime` `null` | | diff --git a/src/components/DateField/README-ru.md b/src/components/DateField/README-ru.md new file mode 100644 index 00000000..cd10fd46 --- /dev/null +++ b/src/components/DateField/README-ru.md @@ -0,0 +1,390 @@ + + +# DateField + + + +```tsx +import {DateField} from '@gravity-ui/date-components'; +``` + +Компонент `DateField` — это универсальное и удобное поле ввода, специально созданное для работы с датами в React-приложениях. Благодаря интуитивно понятному интерфейсу и простой интеграции `DateField` идеально подходит для форм, требующих ввода даты или времени, например, планировщиков событий, систем бронирования или отчетов на основе данных. Компонент становится контролируемым при установке свойства `value`. Если это значение не задано, компонент используется в неконтролируемом режиме. В этом случае задать начальное состояние можно через дополнительное свойство `defaultValue`. По умолчанию `DateField` — неконтролируемый компонент. + +### Полезная рекомендация + +Для установки дат в правильном формате может понадобиться подключение вспомогательных функций из [библиотеки Date Utils](https://gravity-ui.com/libraries/date-utils). + +```tsx +import {dateTimeParse} from '@gravity-ui/date-utils'; +``` + +## Внешний вид + +Внешний вид `DateField` можно настроить с помощью свойств `size`, `view` и `pin`. + +### `Size` (размер) + +Для изменения размера `DateField` используйте свойство `size`. Размер по умолчанию — `m`. + + + + + +```tsx + + + + +``` + + + +### `View` (вид) + +`normal` — основной вид `DateField` (используется по умолчанию). + + + +`clear` — вид `DateField` без видимых границ (может использоваться с пользовательской оберткой). + + + + + +```tsx + + +``` + + + +### `Pin` (форматирование краев) + +Свойство `pin` позволяет настраивать форму правого и левого краев элемента и обычно используется для объединения нескольких контролов в единый блок. +Значение свойства `pin` формируется из названий стилей левого и правого краев, разделенных дефисом, например, `"round-brick"`. +Доступные стили краев: `round` (по умолчанию), `circle`, `brick` и `clear`. + + + + + +```tsx + + + +``` + + + +## Значение + +### Минимальное и максимальное значения + +Свойство `minValue` позволяет задать наиболее ранние дату и время, которые может ввести пользователь. Свойство `maxValue`, в свою очередь, определяет наиболее поздние дату и время, которые доступны для ввода. Если введенное значение выходит за эти пределы, компонент меняет свой вид, сигнализируя об ошибке валидации. + + + + + +```tsx + + + +``` + + + +## Состояния + +### `Disabled` (отключен) + +Состояние `DateField`, при котором пользователь не может взаимодействовать с компонентом. + + + + + +```tsx + +``` + + + +### `readOnly` (только для чтения) + +`readOnly` — это булев атрибут, который при установке в `true` делает компонент `DateField` недоступным для редактирования пользователем. Это означает, что пользователи видят текущее значение поля, но не могут его изменить. + + + + + +```tsx + +``` + + + +### `Error` (ошибка) + +Состояние `DateField`, которое указывает на некорректный ввод данных пользователем. Для изменения внешнего представления `DateField` примените свойство `validationState`, задав ему значение `"invalid"`. Дополнительно через свойство `errorMessage` можно добавить текст сообщения, который будет отображаться под компонентом. + + + + + +```tsx + + +``` + + + +## Дополнительные свойства + +### `Placeholder` (заглушка) + +С помощью этого свойства можно задать короткую подсказку, описывающую ожидаемое значение для поля ввода. Подсказка отображается в поле до начала ввода и исчезает, когда пользователь начинает вводить текст. + + + + + +```tsx + +``` + + + +### `Label` (лейбл) + +Данное свойство позволяет разместить лейбл в левой части поля. Лейбл может занимать не более половины ширины всего пространства `DateField`. + + + + + +```tsx + +``` + + + +### `Clear button` (кнопка очистки) + +`hasClear` — это булево свойство, позволяющее пользователям быстро очищать содержимое поля ввода. + + + + + +```tsx + +``` + + + +### `Start content` (контент в начале поля) + +Позволяет добавить контент в начало поля. Он помещается перед остальными компонентами. + + + + + +```tsx +Start content} /> +``` + + + +### `End content` (контент в конце поля) + +Позволяет добавить контент в конце поля. Он помещается после остальных компонентов. + + + + + +```tsx +End content} /> +``` + + + +## Формат + +Свойство `format` — это строка, задающая формат даты и времени, который компонент `DateField` будет принимать и отображать. Оно определяет, как дата и время отображаются для пользователя и в каком формате пользователь должен вводить данные. С доступными форматами можно ознакомиться по [этой ссылке](https://day.js.org/docs/en/display/format). + + + + + +```tsx + +``` + + + +## Часовой пояс + +`timeZone` — это свойство, позволяющее задать часовой пояс для значения в поле ввода. Подробнее о часовых поясах см. [здесь](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------: | :-----------------------: | +| aria-describedby | Атрибут `aria-describedby` для контрола. | `string` | | +| aria-details | Атрибут `aria-details` для контрола. | `string` | | +| aria-label | Атрибут `aria-label` для контрола. | `string` | | +| aria-labelledby | Атрибут `aria-labelledby` для контрола. | `string` | | +| autoFocus | Атрибут `autofocus` для контрола. | `boolean` | | +| className | Имя класса обертки контрола. | `string` | | +| defaultValue | Задает начальное значение для неконтролируемого компонента. | `DateTime` | | +| disabled | Указывает на то, что пользователь не может взаимодействовать с контролом. | `boolean` | `false` | +| errorMessage | Текст ошибки. | `ReactNode` | | +| format | Формат отображения даты в поле ввода. С доступными форматами можно ознакомиться по [этой ссылке](https://day.js.org/docs/en/display/format). | `string` | | +| hasClear | Отображает иконку для очистки значения контрола. | `boolean` | `false` | +| id | Атрибут `id` для контрола. | `string` | | +| isDateUnavailable | Функция обратного вызова для каждой даты в календаре. Если она возвращает `true`, дата недоступна для выбора. | `((date: DateTime) => boolean)` | | +| label | Текст подсказки (лэйбл), отображаемый слева от поля ввода. | `string` | | +| startContent | Пользовательский контент, отображаемый перед лэйблом и полем ввода. | `React.ReactNode` | | +| maxValue | Верхний предел выбора даты. | `DateTime` | | +| minValue | Нижний предел выбора даты. | `DateTime` | | +| onBlur | Срабатывает, когда контрол теряет фокус. Передает событие фокуса в качестве аргумента обратного вызова. | `((e: FocusEvent) => void)` | | +| onFocus | Срабатывает, когда контрол получает фокус. Передает событие фокуса в качестве аргумента обратного вызова. | `((e: FocusEvent) => void)` | | +| onKeyDown | Срабатывает при нажатии клавиши. Передает событие клавиатуры в качестве аргумента обратного вызова. | `((e: KeyboardEvent) => void)` | | +| onKeyUp | Срабатывает при отпускании клавиши. Передает событие клавиатуры в качестве аргумента обратного вызова. | `((e: KeyboardEvent) => void)` | | +| onUpdate | Срабатывает, когда пользователь изменяет значение. Передает новое значение в качестве аргумента обратного вызова. | `((value: DateTime \| null) => void` | | +| pin | Скругление углов. | `string` | `'round-round'` | +| placeholder | Текст, который отображается в контроле, когда его значение не задано. | `string` | | +| placeholderValue | Дата-заполнитель, которая определяет начальное состояние (значение по умолчанию) для каждого сегмента календаря при первом его открытии пользователем. | `DateTime` | `today's date at midnigh` | +| readOnly | Определяет, можно ли изменять значение компонента. | `boolean` | `false` | +| endContent | Пользовательский контент, отображаемый после поля ввода и кнопки очистки. | `React.ReactNode` | | +| size | Размер контрола. | `"s"` `"m"` `"l"` `"xl"` | `"m"` | +| style | Задает инлайн-стиль для элемента. | `CSSProperties` | | +| timeZone | Задает часовой пояс. Подробнее о часовых поясах см. [здесь](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). | `string` | | +| validationState | Состояние валидации. | `"invalid"` | | +| value | Значение контрола. | `DateTime` `null` | | +| view | Вид контрола. | `"normal"` `"clear"` | `"normal"` | diff --git a/src/components/DatePicker/README-ru.md b/src/components/DatePicker/README-ru.md new file mode 100644 index 00000000..2f8840d1 --- /dev/null +++ b/src/components/DatePicker/README-ru.md @@ -0,0 +1,356 @@ + + +# DatePicker + + + +```tsx +import {DatePicker} from '@gravity-ui/date-components'; +``` + +`DatePicker` — удобный, легкий и полностью настраиваемый компонент, обеспечивающий интуитивно понятный выбор дат в React-приложениях. Благодаря своей ориентированности на удобство пользователя и простоту интеграции, `DatePicker` идеально подходит для использования в формах, модальных окнах и любых UI-элементах, требующих ввода даты. Компонент становится контролируемым при установке свойства `value`. Если это значение не задано, компонент используется в неконтролируемом режиме. В этом случае задать начальное состояние можно через дополнительное свойство `defaultValue`. По умолчанию `DatePicker` — неконтролируемый компонент. + +### Полезная рекомендация + +Для установки дат в правильном формате может понадобиться подключение вспомогательных функций из [библиотеки Date Utils](https://gravity-ui.com/libraries/date-utils). + +```tsx +import {dateTimeParse, dateTime} from '@gravity-ui/date-utils'; +``` + +## Внешний вид + +Внешний вид `DatePicker` можно настроить с помощью свойств `size`, `view` и `pin`. + +### Размер + +Для изменения размера `DatePicker` используйте свойство `size`. Размер по умолчанию — `m`. + + + + + +```tsx + + + + +``` + + + +### `View` (вид) + +`normal` — основной вид `DatePicker` (используется по умолчанию). + + + +`clear` — вид `DatePicker` без видимых границ (может использоваться с пользовательской оберткой). + + + + + +```tsx + + +``` + + + +### `Pin` (форматирование краев) + +Свойство `pin` позволяет настраивать форму правого и левого краев элемента и обычно используется для объединения нескольких контролов в единый блок. +Значение свойства `pin` формируется из названий стилей левого и правого краев, разделенных дефисом, например, `"round-brick"`. +Доступные стили краев: `round` (по умолчанию), `circle`, `brick` и `clear`. + + + + + +```tsx + + + +``` + + + +## Значение + +### Минимальное и максимальное значения + +Свойство `minValue` позволяет задать наиболее ранние дату и время, которые может ввести пользователь. Свойство `maxValue`, в свою очередь, определяет наиболее поздние дату и время, которые доступны для ввода. Если введенное значение выходит за эти пределы, компонент меняет свой вид, сигнализируя об ошибке валидации. + + + + + +```tsx + + + +``` + + + +## Состояния + +### `Disabled` (отключен) + +Состояние `DatePicker`, при котором пользователь не может взаимодействовать с компонентом. + + + + + +```tsx + +``` + + + +### `readOnly` (только для чтения) + +`readOnly` — это булев атрибут, который при установке в `true` делает компонент `DatePicker` недоступным для редактирования пользователем. Это означает, что пользователи видят текущее значение поля, но не могут его изменить. + + + + + +```tsx + +``` + + + +### `Error` (ошибка) + +Состояние `DatePicker`, которое указывает на некорректный ввод данных пользователем. Для изменения внешнего представления `DatePicker` примените свойство `validationState`, задав ему значение `"invalid"`. Дополнительно через свойство `errorMessage` можно добавить текст сообщения, который будет отображаться под компонентом. + + + + + +```tsx + + +``` + + + +## Дополнительные свойства + +### `Placeholder` (заглушка) + +С помощью этого свойства можно задать короткую подсказку, описывающую ожидаемое значение для поля ввода. Подсказка отображается в поле до начала ввода и исчезает, когда пользователь начинает вводить текст. + + + + + +```tsx + +``` + + + +### `Label` (лейбл) + +Данное свойство позволяет разместить лейбл в левой части поля. Лейбл может занимать не более половины ширины всего пространства `DatePicker`. + + + + + +```tsx + +``` + + + +### `Clear button` (кнопка очистки) + +`hasClear` — это булево свойство, позволяющее пользователям быстро очищать содержимое поля ввода. + + + + + +```tsx + +``` + + + +## Формат + +Свойство `format` — это строка, задающая формат даты и времени, который компонент `DatePicker` будет принимать и отображать. Оно определяет, как дата и время отображаются для пользователя и в каком формате пользователь должен вводить данные. С доступными форматами можно ознакомиться по [этой ссылке](https://day.js.org/docs/en/display/format). + + + + + +```tsx + +``` + + + +## Часовой пояс + +`timeZone` — это свойство, позволяющее задать часовой пояс для значения в поле ввода. Подробнее о часовых поясах см. [здесь](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). + +## Кастомизация + +Можно использовать собственный компонент календаря внутри `DatePicker`, передав его как `children` с теми же свойствами, что и у стандартного календаря. + + + + + +Подробнее о компоненте `Calendar` см. [здесь](https://github.com/gravity-ui/date-components/blob/main/src/components/Calendar/README.md). + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------: | :-----------------------: | +| aria-describedby | Атрибут `aria-describedby` для контрола. Определяет элемент или элементы, содержащие описание объекта. | `string` | | +| aria-details | Атрибут `aria-details` для контрола. Определяет элемент или элементы, содержащие подробное описание объекта. | `string` | | +| aria-label | Атрибут `aria-label` для контрола. Определяет строковое значение, используемое в качестве метки для текущего элемента. | `string` | | +| aria-labelledby | Атрибут `aria-labelledby` для контрола. Определяет элемент или элементы, используемые в качестве метки для текущего элемента. | `string` | | +| autoFocus | Атрибут `autofocus` для контрола. Определяет, должен ли элемент получать фокус при рендеринге. | `boolean` | | +| className | Имя класса обертки контрола. | `string` | | +| [defaultValue](#datepicker) | Задает начальное значение для неконтролируемого компонента. | `DateTime` | | +| [disabled](#disabled) | Указывает на то, что пользователь не может взаимодействовать с контролом. | `boolean` | `false` | +| [errorMessage](#error) | Текст ошибки. | `ReactNode` | | +| [format](#format) | Формат отображения даты в поле ввода. С доступными форматами можно ознакомиться по [этой ссылке](https://day.js.org/docs/en/display/format). | `string` | | +| [hasClear](#clear-button) | Отображает иконку для очистки значения контрола. | `boolean` | `false` | +| id | Атрибут `id` для контрола. | `string` | | +| isDateUnavailable | Функция обратного вызова для каждой даты в календаре. Если она возвращает `true`, дата недоступна для выбора. | `((date: DateTime) => boolean)` | | +| [label](#label) | Текст подсказки (лейбл), отображаемый слева от поля ввода. | `string` | | +| [maxValue](#min-and-max-value) | Верхний предел выбора даты. | `DateTime` | | +| [minValue](#min-and-max-value) | Нижний предел выбора даты. | `DateTime` | | +| onBlur | Срабатывает, когда контрол теряет фокус. Передает событие фокуса в качестве аргумента обратного вызова. | `((e: FocusEvent) => void)` | | +| onFocus | Срабатывает, когда контрол получает фокус. Передает событие фокуса в качестве аргумента обратного вызова. | `((e: FocusEvent) => void)` | | +| onKeyDown | Срабатывает при нажатии клавиши. Передает событие клавиатуры в качестве аргумента обратного вызова. | `((e: KeyboardEvent) => void)` | | +| onKeyUp | Срабатывает при отпускании клавиши. Передает событие клавиатуры в качестве аргумента обратного вызова. | `((e: KeyboardEvent) => void)` | | +| onUpdate | Срабатывает, когда пользователь изменяет значение. Передает новое значение в качестве аргумента обратного вызова. | `((value: DateTime \| null) => void` | | +| [pin](#pin) | Скругление углов. | `TextInputPin` | `'round-round'` | +| [placeholder](#placeholder) | Текст, который отображается в контроле, когда его значение не задано. | `string` | | +| placeholderValue | Дата-заполнитель, которая определяет начальное состояние (значение по умолчанию) для каждого сегмента календаря при первом его открытии пользователем. | `DateTime` | `today's date at midnigh` | +| [readOnly](#readonly) | Определяет, можно ли изменять значение компонента. | `boolean` | `false` | +| [size](#size) | Размер контрола. | `"s"` `"m"` `"l"` `"xl"` | `"m"` | +| style | Задает инлайн-стиль для элемента. | `CSSProperties` | | +| [timeZone](#time-zone) | Задает часовой пояс. Подробнее о часовых поясах см. [здесь](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). | `string` | | +| [validationState](#error) | Состояние валидации. | `"invalid"` | | +| [value](#datepicker) | Значение контрола. | `DateTime` `null` | | +| [view](#view) | Вид контрола. | `"normal"` `"clear"` | `"normal"` | diff --git a/src/components/RangeCalendar/README-ru.md b/src/components/RangeCalendar/README-ru.md new file mode 100644 index 00000000..a4274a74 --- /dev/null +++ b/src/components/RangeCalendar/README-ru.md @@ -0,0 +1,232 @@ + + +# RangeCalendar + + + +```tsx +import {RangeCalendar} from '@gravity-ui/date-components'; +``` + +`RangeCalendar` — это полнофункциональный, гибкий и удобный UI-компонент для выбора диапазона дат. Он создан на базе React и сочетает в себе функциональность календаря и элемента для выбора диапазона дат, что делает его идеальным решением для приложений, требующих ввода начальной и конечной дат. Компонент становится контролируемым при установке свойства `value`. Если это значение не задано, компонент используется в неконтролируемом режиме. В этом случае задать начальное состояние можно через дополнительное свойство `defaultValue`. По умолчанию `RangeCalendar` — неконтролируемый компонент. + +### Полезная рекомендация + +Для установки дат в правильном формате может понадобиться подключение вспомогательных функций из [библиотеки Date Utils](https://gravity-ui.com/libraries/date-utils). + +```tsx +import {dateTimeParse, dateTime} from '@gravity-ui/date-utils'; +``` + + + +## Размер + +Для изменения размера `RangeCalendar` используйте свойство `size`. Размер по умолчанию — `m`. + + + + + +```tsx + + + +``` + + + +## Значение + +### Минимальное и максимальное значения + +Свойство `minValue` позволяет задать наиболее ранние дату и время, которые может ввести пользователь. Свойство `maxValue`, в свою очередь, определяет наиболее поздние дату и время, которые доступны для ввода. Все остальные значения будут недоступны для пользователя. + + + + + +```tsx + +``` + + + +## Режим + +Определяет временной интервал, который будет отображаться в компоненте `RangeCalendar`. С помощью свойства `mode` можно задать нужный интервал для контролируемого компонента. Для неконтролируемого компонента значение этого свойства указывать не требуется, а начальный режим отображения можно задать через `defaultMode`. + +`days` — режим по умолчанию для `RangeCalendar`. Отображает календарь с днями месяца. + +`months` — отображает календарь с месяцами года. + +`quarters` — отображает календарь с кварталами по годам (недоступно в качестве значения для `defaultMode`). + +`years` — отображает календарь с несколькими годами для выбора. + +С помощью свойства `modes` можно указать, какие режимы будут доступны пользователю. + + + + + +```tsx + +``` + + + +## Состояния + +### `Disabled` (отключен) + +Состояние `RangeCalendar`, при котором пользователь не может взаимодействовать с компонентом. + + + + + +```tsx + +``` + + + +### `readOnly` (только для чтения) + +`readOnly` — это булев атрибут, который при установке в `true` делает компонент `RangeCalendar` недоступным для редактирования пользователем. Это означает, что пользователи видят текущее значение поля, но не могут его изменить. + + + + + +```tsx + +``` + + + +## Значение, получающее фокус + +Позволяет выбрать дату, на которой будет установлен фокус представления `RangeCalendar`. Если необходимо контролировать это значение, используйте свойство `focusedValue`. Для неконтролируемого компонента начальное значение, получающее фокус, можно установить через `defaultFocusedValue`. + + + + + +```tsx + +``` + + + +## Часовой пояс + +`timeZone` — это свойство, позволяющее задать часовой пояс для значения в поле ввода. Подробнее о часовых поясах см. [здесь](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------: | :---------------------------------------------------------: | +| aria-describedby | Атрибут `aria-describedby` для контрола. | `string` | | +| aria-details | Атрибут `aria-details` для контрола. | `string` | | +| aria-label | Атрибут `aria-label` для контрола. | `string` | | +| aria-labelledby | Атрибут `aria-labelledby` для контрола. | `string` | | +| autoFocus | Атрибут `autofocus` для контрола. | `boolean` | | +| className | Имя класса обертки контрола. | `string` | | +| [defaultFocusedValue](#focused-value) | Дата, на которую устанавливается фокус при первом открытии календаря (если компонент неконтролируемый). | `DateTime` | | +| [defaultMode](#mode) | Начальный режим отображения календаря. | `days` `months` `quarters` `years` | | +| [defaultValue](#value) | Задает начальное значение для неконтролируемого компонента. | `RangeValue` | | +| [disabled](#disabled) | Указывает на то, что пользователь не может взаимодействовать с контролом. | `boolean` | `false` | +| [focusedValue](#focused-value) | Устанавливает вид неконтролируемого компонента по умолчанию, включающий данное значение. | `DateTime` `null` | | +| id | Атрибут `id` для контрола. | `string` | | +| isDateUnavailable | Функция обратного вызова для каждой даты в календаре. Если она возвращает `true`, дата недоступна для выбора. | `((date: DateTime) => boolean)` | | +| isWeekend | Функция обратного вызова для каждой даты в календаре. Если она возвращает `true`, дата является выходным днем. | `((date: DateTime) => boolean)` | | +| [maxValue](#min-and-max-value) | Верхний предел выбора даты. | `DateTime` | | +| [minValue](#min-and-max-value) | Нижний предел выбора даты. | `DateTime` | | +| [mode](#mode) | Определяет временной интервал, который будет отображаться в контролируемом компоненте `RangeCalendar`. | `days` `months` `quarters` `years` | | +| modes | Режимы, доступные для выбора пользователем. | `Partial>` | `{days: true, months: true, quarters: false, years: true }` | +| onBlur | Срабатывает, когда контрол теряет фокус. Передает событие фокуса в качестве аргумента обратного вызова. | `((e: FocusEvent) => void)` | | +| onFocus | Срабатывает, когда контрол получает фокус. Передает событие фокуса в качестве аргумента обратного вызова. | `((e: FocusEvent) => void)` | | +| onFocusUpdate | Срабатывает при изменении даты, на которой фокусируется контрол. | `((date: DateTime) => void)` | | +| onUpdate | Срабатывает при изменении значения. | `((value: DateTime) => void` | | +| onUpdateMode | Срабатывает при изменении режима. | `((value: 'days' \| 'months' \| 'quarters' \| 'years' ) => void` | | +| [readOnly](#readonly) | Определяет, можно ли изменять значение календаря. | `boolean` | `false` | +| [size](#size) | Размер контрола. | `"m"` `"l"` `"xl"` | `"m"` | +| style | Задает инлайн-стиль для элемента. | `CSSProperties` | | +| [timeZone](#time-zone) | Задает часовой пояс. Подробнее о часовых поясах см. [здесь](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). | `string` | | +| [value](#calendar) | Значение контрола. | `RangeValue` `null` | | diff --git a/src/components/RelativeDateField/README-ru.md b/src/components/RelativeDateField/README-ru.md new file mode 100644 index 00000000..bd6d9593 --- /dev/null +++ b/src/components/RelativeDateField/README-ru.md @@ -0,0 +1,77 @@ + + +# RelativeDateField + + + +```tsx +import {RelativeDateField} from '@gravity-ui/date-components'; +``` + +Компонент `RelativeDateField` предназначен исключительно для ввода относительных дат и не может использоваться как стандартный `DateField`. + +## Относительный формат ввода + +Компонент получает значения в специальном относительном формате. Значения устанавливаются в виде формул, которые вычисляют конкретную дату. Этот формат можно назвать Grafana-подобным (`grafana-like format`), поскольку он аналогичен формату относительных временных полей в Grafana. Подробнее об относительных временных значениях см. в [статье](https://grafana.com/docs/grafana/latest/panels-visualizations/query-transform-data/) документации Grafana. + +Этот режим позволяет передавать данные от источника к приемнику, точно рассчитывая значение непосредственно на нужном эндпоинте без каких-либо неточностей. + +## Правила корректного ввода + +- Значение должно начинаться с ключевого слова `now`. +- Выражение относительной даты в общем виде должно выглядеть следующим образом: `now${operand}${count}${unit}`. +- Доступные значения для `operand`: + - `-` — вычитание; + - `+` — сложение; + - `/` — приведение даты к началу `unit` (выбранной единицы). +- Допустимые значения для `count` (количество) — любое натуральное число. +- Допустимые значения для `unit`: + - `d` — день; + - `w` — неделя; + - `M` — месяц; + - `Q` — квартал; + - `y` — год; + - `h` — час; + - `m` — минута. + +### Примеры использования + +> `now-1d` +> +> `now/w` +> +> `now+10d-5d/M` + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :--------------- | :------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------: | :-------------------: | +| aria-describedby | Атрибут `aria-describedby` для контрола. | `string` | | +| aria-details | Атрибут `aria-details` для контрола. | `string` | | +| aria-label | Атрибут `aria-label` для контрола. | `string` | | +| aria-labelledby | Атрибут `aria-labelledby` для контрола. | `string` | | +| autoFocus | Атрибут `autofocus` для контрола. | `boolean` | | +| className | Имя класса обертки контрола. | `string` | | +| defaultValue | Задает начальное значение для неконтролируемого компонента. | `string` | | +| disabled | Указывает на то, что пользователь не может взаимодействовать с контролом. | `boolean` | `false` | +| errorMessage | Текст ошибки. | `ReactNode` | | +| hasClear | Отображает иконку для очистки значения контрола. | `boolean` | `false` | +| hasTime | Отображает поле для выбора времени во всплывающем окне. | `boolean` | `false` | +| id | Атрибут `id` для контрола. | `string` | | +| label | Текст подсказки (лейбл), отображаемый слева от поля ввода. | `string` | | +| leftContent | Пользовательский контент, отображаемый перед лэйблом и полем ввода. | `React.ReactNode` | | +| onBlur | Срабатывает, когда контрол теряет фокус. Передает событие фокуса в качестве аргумента обратного вызова. | `((e: FocusEvent) => void)` | | +| onFocus | Срабатывает, когда контрол получает фокус. Передает событие фокуса в качестве аргумента обратного вызова. | `((e: FocusEvent) => void)` | | +| onKeyDown | Срабатывает при нажатии клавиши. Передает событие клавиатуры в качестве аргумента обратного вызова. | `((e: KeyboardEvent) => void)` | | +| onKeyUp | Срабатывает при отпускании клавиши. Передает событие клавиатуры в качестве аргумента обратного вызова. | `((e: KeyboardEvent) => void)` | | +| onUpdate | Срабатывает, когда пользователь изменяет значение. Передает новое значение в качестве аргумента обратного вызова. | `((value: string \| null) => void` | | +| pin | Скругление углов. | `string` | `'round-round'` | +| placeholder | Текст, который отображается в контроле, когда его значение не задано. | `string` | | +| readOnly | Определяет, можно ли изменять значение компонента. | `boolean` | `false` | +| rightContent | Пользовательский контент, отображаемый после поля ввода и кнопки очистки. | `React.ReactNode` | | +| size | Размер контрола. | `"s"` `"m"` `"l"` `"xl"` | `"m"` | +| style | Задает инлайн-стиль для элемента. | `CSSProperties` | | +| timeZone | Задает часовой пояс. Подробнее о часовых поясах см. [здесь](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). | `string` | | +| validationState | Состояние валидации. | `"invalid"` | | +| value | Значение контрола. | `string` `null` | | +| view | Вид контрола. | `"normal"` `"clear"` | `"normal"` | diff --git a/src/components/RelativeDatePicker/README-ru.md b/src/components/RelativeDatePicker/README-ru.md new file mode 100644 index 00000000..81ca028f --- /dev/null +++ b/src/components/RelativeDatePicker/README-ru.md @@ -0,0 +1,83 @@ + + +# RelativeDatePicker + + + +```tsx +import {RelativeDatePicker} from '@gravity-ui/date-components'; +``` + +`RelativeDatePicker` — компонент, аналогичный `DatePicker`, но с возможностью использования относительных дат. + +## Отличие от `DatePicker` + +`RelativeDatePicker` поддерживает два режима: `absolute` и `relative`. Режимы можно переключать между собой нажатием на кнопку `f(x)` или установкой поля `type` в объекте `value` или `defaultValue` + +### Режим `absolute` + +В режиме `absolute` `RelativeDatePicker` работает как `DatePicker`. + + + + + +Подробнее о компоненте `DatePicker` см. [здесь](/src/components/DatePicker). + + + +### Режим `relative` + +В этом режиме `RelativeDatePicker` принимает и возвращает значения в специальном относительном формате. + + + + + +Подробнее о правилах создания относительных формул см. [здесь](/src/components/RelativeDateField#relative-input). + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------: | :-----------------------: | +| aria-describedby | Атрибут `aria-describedby` для контрола. Определяет элемент или элементы, содержащие описание объекта. | `string` | | +| aria-details | Атрибут `aria-details` для контрола. Определяет элемент или элементы, содержащие подробное описание объекта. | `string` | | +| aria-label | Атрибут `aria-label` для контрола. Определяет строковое значение, используемое в качестве метки для текущего элемента. | `string` | | +| aria-labelledby | Атрибут `aria-labelledby` для контрола. Определяет элемент или элементы, используемые в качестве метки для текущего элемента. | `string` | | +| autoFocus | Атрибут `autofocus` для контрола. Определяет, должен ли элемент получать фокус при рендеринге. | `boolean` | | +| className | Имя класса обертки контрола. | `string` | | +| defaultValue | Задает начальное значение для неконтролируемого компонента. | `Value` | | +| disabled | Указывает на то, что пользователь не может взаимодействовать с контролом. | `boolean` | `false` | +| errorMessage | Текст ошибки. | `ReactNode` | | +| format | Формат отображения даты в поле ввода. С доступными форматами можно ознакомиться по [этой ссылке](https://day.js.org/docs/en/display/format). | `string` | | +| hasClear | Отображает иконку для очистки значения контрола. | `boolean` | `false` | +| id | Атрибут `id` для контрола. | `string` | | +| isDateUnavailable | Функция обратного вызова для каждой даты в календаре. Если она возвращает `true`, дата недоступна для выбора. | `((date: DateTime) => boolean)` | | +| label | Текст подсказки (лейбл), отображаемый слева от поля ввода. | `string` | | +| maxValue | Верхний предел выбора даты. | `DateTime` | | +| minValue | Нижний предел выбора даты. | `DateTime` | | +| onBlur | Срабатывает, когда контрол теряет фокус. Передает событие фокуса в качестве аргумента обратного вызова. | `((e: FocusEvent) => void)` | | +| onFocus | Срабатывает, когда контрол получает фокус. Передает событие фокуса в качестве аргумента обратного вызова. | `((e: FocusEvent) => void)` | | +| onKeyDown | Срабатывает при нажатии клавиши. Передает событие клавиатуры в качестве аргумента обратного вызова. | `((e: KeyboardEvent) => void)` | | +| onKeyUp | Срабатывает при отпускании клавиши. Передает событие клавиатуры в качестве аргумента обратного вызова. | `((e: KeyboardEvent) => void)` | | +| onUpdate | Срабатывает, когда пользователь изменяет значение. Передает новое значение в качестве аргумента обратного вызова. | `((value: Value \| null) => void` | | +| pin | Скругление углов. | `TextInputPin` | `'round-round'` | +| placeholder | Текст, который отображается в контроле, когда его значение не задано. | `string` | | +| placeholderValue | Дата-заполнитель, которая определяет начальное состояние (значение по умолчанию) для каждого сегмента календаря при первом его открытии пользователем. | `DateTime` | `today's date at midnigh` | +| readOnly | Определяет, можно ли изменять значение компонента. | `boolean` | `false` | +| size | Размер контрола. | `"s"` `"m"` `"l"` `"xl"` | `"m"` | +| style | Задает инлайн-стиль для элемента. | `CSSProperties` | | +| timeZone | Задает часовой пояс. Подробнее о часовых поясах см. [здесь](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List). | `string` | | +| validationState | Состояние валидации. | `"invalid"` | | +| value | Значение контрола. | `Value` `null` | | +| view | Вид контрола. | `"normal"` `"clear"` | `"normal"` |