diff --git a/src/components/ActionTooltip/README-ru.md b/src/components/ActionTooltip/README-ru.md new file mode 100644 index 0000000000..3302a21711 --- /dev/null +++ b/src/components/ActionTooltip/README-ru.md @@ -0,0 +1,34 @@ + + +# ActionTooltip + + + +`ActionTooltip` — это простая текстовая подсказка, использующая в качестве якоря дочерний элемент. Для правильной работы элемент-якорь должен поддерживать события мыши и события получения или потери фокуса. + +## Использование + +```tsx +import {ActionTooltip} from '@gravity-ui/uikit'; + + +
Anchor
+; +``` + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :--------------- | ------------------------------------------------------------------------------------------ | :----------------------------------------------: | :-------------------: | +| children | Элемент-якорь для `Tooltip`. Должен принимать `ref` для передачи DOM-элемента. | `React.ReactElement` | | +| closeDelay | Время задержки в миллисекундах перед скрытием `Tooltip` после увода курсора с элемента. | `number` | `0` | +| openDelay | Время задержки в миллисекундах перед показом `Tooltip` после наведения курсора на элемент. | `number` | `250` | +| placement | Положение `Tooltip` относительно якоря. | [`PopupPlacement`](../Popup/README.md#placement) | | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | +| title | Текст заголовка для тултипа. | `string` | | +| description | Текст описания в тултипе. | `string` | | +| hotkey | Горячие клавиши, назначенные на действие в интерфейсе. | `string` | | +| id | Используется для реализации логики доступности. | `string` | | +| disablePortal | Отключает использование `Portal` для дочерних элементов. | `boolean` | | +| contentClassName | HTML-атрибут `class` для узла с содержимым. | `string` | | +| disabled | Блокирует открытие всплывающего окна. | `boolean` | `false` | diff --git a/src/components/ActionTooltip/README.md b/src/components/ActionTooltip/README.md index 5b40131568..d5a1dd8c22 100644 --- a/src/components/ActionTooltip/README.md +++ b/src/components/ActionTooltip/README.md @@ -4,8 +4,7 @@ -A simple text tip that uses its children node as an anchor. For correct functioning, the anchor node -must be able to handle mouse events and focus or blur events. +This is a simple text tip that uses its child node as an anchor. To work correctly, the anchor node must be able to handle mouse events and focus or blur events. ## Usage @@ -21,15 +20,15 @@ import {ActionTooltip} from '@gravity-ui/uikit'; | Name | Description | Type | Default | | :--------------- | --------------------------------------------------------------------------------------- | :----------------------------------------------: | :-----: | -| children | An anchor element for a `Tooltip`. Must accept a `ref` that will provide a DOM element. | `React.ReactElement` | | +| children | Anchor element for a `Tooltip`. It must accept a `ref` that will provide a DOM element. | `React.ReactElement` | | | closeDelay | Number of ms to delay hiding the `Tooltip` after the hover ends | `number` | `0` | -| openDelay | Number of ms to delay showing the `Tooltip` after the hover begins | `number` | `250` | +| openDelay | Number of ms to delay showing the `Tooltip` once the hover starts | `number` | `250` | | placement | `Tooltip` position relative to its anchor | [`PopupPlacement`](../Popup/README.md#placement) | | -| qa | HTML `data-qa` attribute, used in tests | `string` | | +| qa | `data-qa` HTML attribute, used for testing | `string` | | | title | Tooltip title text | `string` | | | description | Tooltip description text | `string` | | -| hotkey | Hot keys that are assigned to an interface action. | `string` | | -| id | This prop is used to help implement the accessibility logic. | `string` | | -| disablePortal | Do not use Portal for children | `boolean` | | -| contentClassName | HTML class attribute for content node | `string` | | -| disabled | Prevent popup from opening | `boolean` | `false` | +| hotkey | Hotkeys assigned to an interface action | `string` | | +| id | Used for implementing the accessibility logic | `string` | | +| disablePortal | Disables using Portal for children | `boolean` | | +| contentClassName | HTML class attribute for the content node | `string` | | +| disabled | Prevents the popup from opening | `boolean` | `false` | diff --git a/src/components/Alert/README-ru.md b/src/components/Alert/README-ru.md new file mode 100644 index 0000000000..b87e8e98b7 --- /dev/null +++ b/src/components/Alert/README-ru.md @@ -0,0 +1,233 @@ + + +# Alert + + + +```tsx +import {Alert} from '@gravity-ui/uikit'; +``` + +### `Theme` (тема) + +`normal` — основная тема (используется по умолчанию). + +`info` — используется для любой стандартной информации. + +`success` — используется для положительной информации. + +`warning` — используется для информации, требующей внимания. + +`danger` — используется для критических ошибок. + +`utility` — используется для полезных советов. + + + + + +```tsx + + + + + + +``` + + + +### `View` (вид) + +`filled` — используется для настройки цвета фона алерта (используется по умолчанию). + +`outlined` — используется для настройки цвета границ алерта. + + + + + +``` + + +``` + + + +### `Layout` (расположение) + +`vertical` — используется для привлечения внимания пользователей к контенту, если задано свойство `actions` с кнопками. Кнопки отображаются под текстом (используется по умолчанию). + +`horizontal` — используется для привлечения внимания пользователей к контенту, если задано свойство `actions` с кнопками. Кнопки отображаются справа от текста. + + + + + +```tsx +button}/> +button}/> +``` + + + +### `Corners` (углы) + +`rounded` — включает скругленные углы окна алерта (используется по умолчанию). + +`square` — включает прямые углы окна алерта. + + + + + +```tsx + + +``` + + + +## Заголовок алерта + +`title` — заголовок алерта. Имеет более низкий приоритет, чем у параметра `Alert.Title`. + + + + + +```tsx +} /> +``` + + + +## Сообщение алерта + +`message` — сообщение алерта. Оно должно быть достаточно информативным, чтобы полностью объяснить суть алерта. + +## `onClose` + +`onClose` — функция обратного вызова, которая срабатывает, когда пользователь нажимает на кнопку закрытия алерта. Если это свойство задано, кнопка закрытия видима. + + + + + +```tsx + alert('Close button pressed')} + title="Alert has close" + message="Alert has close" +/> +``` + + + +### `Align` (выравнивание) + +Управляет вертикальным выравниванием содержимого внутри компонента `Alert`: + +`baseline` — выравнивание по умолчанию. + +`center` — содержимое вертикально центрируется внутри компонента `Alert`. Может быть полезно, если элементы управления занимают больше пространства, чем текст, или если иконка должна располагаться посередине содержимого. + + + + + +```tsx +button}/> +button}/> +``` + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------- | :--------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------: | :-------------------: | +| theme | Внешний вид алерта. | `"normal"` `"info"` `"success"` `"warning"` `"danger"` `"utility"` | `"normal"` | +| view | Включает или отключает цвет фона окна алерта. | `"filled"` `"outlined"` | `"filled"` | +| layout | Используется для привлечения внимания пользователей к контенту, если задано свойство `actions` с кнопками. | `"vertical"` `"horizontal"` | `"vertical"` | +| corners | Управляет оформлением углов (прямые или скругленные) для окна алерта. | `"rounded"` `"square"` | `"rounded"` | +| title | Заголовок алерта | `string` | | +| message | Сообщение алерта | `string` | | +| onClose | Функция обратного вызова, которая срабатывает, когда пользователь нажимает на кнопку закрытия алерта. | `Function` | | +| actions | Массив кнопок или пользовательских компонентов. | `React.ReactNode` `"AlertAction"` | | +| align | Управляет вертикальным выравниванием содержимого внутри компонента `Alert`. | `"center"` `"baseline"` | `"baseline"` | +| style | HTML-атрибут `style`. | `React.CSSProperties` | | +| className | Имя CSS-класса алерта. | `string` | | +| icon | Переопределяет иконку по умолчанию. | `React.ReactNode` | | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | diff --git a/src/components/Alert/README.md b/src/components/Alert/README.md index dc558652ca..feeb886e27 100644 --- a/src/components/Alert/README.md +++ b/src/components/Alert/README.md @@ -10,17 +10,17 @@ import {Alert} from '@gravity-ui/uikit'; ### Theme -`normal` - main theme (used by default). +`normal`: Main theme (used by default). -`info` - used for any kind of regular information. +`info`: Used for any kind of regular information. -`success` - used for positive information. +`success`: Used for positive information. -`warning` - used for information which needs attention. +`warning`: Used for information that needs attention. -`danger` - used for hazard information. +`danger`: Used for critical errors. -`utility` - used for utility information. +`utility`: Used for useful tips. ### View -`filled` - used to adjust the background color of the alert (used by default). +`filled`: Used to adjust the background color of the alert (used by default). -`outlined` - used to adjust the border color of the alert. +`outlined`: Used to adjust the border color of the alert. ### Layout -`vertical` - used to direct users to content if there is property `actions` with buttons. For showing buttons below text ( -used -by default). +`vertical`: Used to direct users to content if there is an `actions` property with buttons. It enables showing buttons below the text (used by default). -`horizontal` - used to direct users to content if there is property `actions` with buttons. For showing buttons to the right -of text. +`horizontal`: Used to direct users to content if there is an `actions` property with buttons. It enables showing buttons to the right of the text. ### Corners -`rounded` - used for round corners of alert window (used by default). +`rounded`: Enables rounded corners of the alert window (used by default). -`square` - used for squared corners of alert window. +`square`: Enables squared corners of the alert window. ## Alert title -`title` - the title of the alert. It has a lower priority than Alert.Title. +`title`: Alert title. It has a lower priority than `Alert.Title`. ## Alert message -`message` - message of the alert. It should fully explain the content of the alert. +`message`: Alert message. It should be meaningful enough to fully explain what the alert is about. -## Alert onClose +## `onClose` -`onClose` - callback function called when a user clicks the alert's close button. When this property is defined, a close button is visible. +`onClose`: Callback function called when a user clicks the alert's close button. When this property is defined, the close button will visible. ### Align -Determines how content inside the Alert component is vertically aligned. +Determines how the content inside the `Alert` component is vertically aligned. -`baseline` - align used by default. +`baseline`: Default alignment. -`center` - content is vertically centered within the Alert component. Useful if actions take up -more space than text, -or if the icon must be in the middle of the card. +`center`: Content is vertically centered within the `Alert` component. It may be useful if actions take up more space than text, or if the icon must be in the middle of the content. + +# ArrowToggle + + + +`ArrowToggle` — это компонент для отображения иконки в виде стрелки, которая может вращаться в четырех направлениях. Подходит для отображения выпадающих списков, компонентов в свёрнутом состоянии и других элементов. + +## Внешний вид + +`ArrowToggle` поддерживает четыре направления: `top` (вверх), `right` (вправо), `bottom` (вниз) и `left` (влево). + + + + + +```tsx + top + right + bottom + left +``` + + + +## Размер + + + + + +```tsx + 10 + 20 + 30 + 40 + 50 + 100 +``` + + + +## Использование в качестве интерактивного элемента + +Пример использования `ArrowToggle` с иконкой-переключателем: + + + + + +```tsx +const [directionIndex, setDirectionIndex] = React.useState(0); +const directions = ['top', 'left', 'bottom', 'right'] as Array; +const direction = directions[directionIndex % directions.length]; + +return ( + +); +``` + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------- | :----------------------------------------------------- | :------: | :-------------------: | +| className | HTML-атрибут `class`. | `string` | | +| direction | Задает направление `arrowToggle`. | `string` | `"bottom"` | +| size | Размер `arrowToggle` (в пикселях). | `number` | `16` | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | diff --git a/src/components/ArrowToggle/README.md b/src/components/ArrowToggle/README.md index 91356d54e7..ae68ce8f2f 100644 --- a/src/components/ArrowToggle/README.md +++ b/src/components/ArrowToggle/README.md @@ -4,11 +4,11 @@ -`ArrowToggle` is a component for displaying the chevron icon. It can rotate in four directions, and can be used to display dropdown lists, cut components, etc. +`ArrowToggle` is a component for displaying the chevron icon. It can rotate in four directions and can be used to display drop-down lists, cut components, etc. ## Appearance -The component has four possible directions: `top`, `right`, `bottom` and `left`. +`ArrowToggle` has four possible directions: `top`, `right`, `bottom`, and `left`. -## Interactive +## Use as an interactive element -Here is an example of usage ArrowToggle component with a toggling icon. +Here is an example of using ArrowToggle with a toggling icon: + +# Avatar + + + +```tsx +import {Avatar} from '@gravity-ui/uikit'; +``` + +Данный компонент предназначен для рендеринга аватаров. Он поддерживает три основных типа аватаров: изображение, иконку и текст (инициалы). Все эти типы имеют специальные свойства для настройки их поведения и внешнего вида. + +## Типы + +### Изображение + +Компонент `Avatar` можно применять для рендеринга аватаров с использованием изображений. Для добавления изображения используйте свойство `imgUrl`. + + + +Дополнительно можно передать свойство `srcSet`, которое позволяет загружать изображения разных размеров. + + + +У компонента `Avatar` есть свойство `fallbackImgUrl`, которое позволяет передать изображение, которое будет показано при ошибке загрузки изображения по ссылке `imgUrl` (ошибка CSP или отсутствие исходного изображения). + + + +### Иконка + +Этот компонент можно применять для рендеринга аватаров с использованием иконок. Чтобы задать иконку, используйте свойство `icon` точно так же, как для компонента `Icon`. + + + +### Текст + +Этот компонент можно применять для рендеринга аватаров с использованием текста. Для этого используйте свойство `text`. Текст отображается в виде инициалов (первых букв двух слов) или первых двух букв одного слова. + + + +## Внешний вид + +### Тема и вид + +Компонент `Avatar` имеет предустановленные темы (`normal` и `brand`) и виды (`filled` и `outlined`). + +По умолчанию тема — `normal`, а вид — `filled`. + + + +### Пользовательские цвета + +Можно также задать собственные цвета через свойства `backgroundColor`, `borderColor` и `color` (последнее работает только для аватарок с иконками и текстом). Эти цвета обладают бóльшим приоритетом по сравнению с цветами, которые заданы в темах. + + + +### Размер + +Размер `Avatar` можно настроить с помощью свойства `size`. Размер по умолчанию — `m`. Возможные значения: `xs`, `s`, `m`, `l` и `xl`. + + + +## Свойства + +### Общие + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------------- | :----------------------------------------------------- | :-----------------------------: | :-------------------: | +| size | Размер аватара. | `'xs'` `'s'` `'m'` `'l'` `'xl'` | `m` | +| theme | Тема аватара. | `'normal'` `'brand'` | `normal` | +| view | Варианты заполнения и обводки аватара. | `'filled'` `'outlined'` | `filled` | +| backgroundColor | Пользовательский цвет фона. | `string` | | +| borderColor | Пользовательский цвет границы. | `string` | | +| title | HTML-атрибут `title`. | `string` | | +| aria-label | Атрибут `aria-label` для секции аватара. | `string` | | +| aria-labelledby | Атрибут `aria-labelledby` для секции аватара. | `string` | | +| className | Пользовательский CSS-класс корневого элемента. | `string` | | +| style | HTML-атрибут `style`. | `React.CSSProperties` | | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | + +### Свойства изображений + +| Имя | Описание | Тип | Значение по умолчанию | +| :------------- | :--------------------------------------------------- | :----------------: | :-------------------: | +| imgUrl | HTML-атрибут `src` для `img`. | `string` | | +| fallbackImgUrl | Резервное изображение, отображаемое в случае ошибки. | `string` | | +| sizes | HTML-атрибут `sizes` для `img`. | `string` | | +| srcSet | HTML-атрибут `srcSet` для `img`. | `string` | | +| alt | HTML-атрибут `alt` для `img`. | `string` | props.title | +| loading | HTML-атрибут `loading` для `img`. | `'eager'` `'lazy'` | | + +### Свойства иконки + +| Имя | Описание | Тип | Значение по умолчанию | +| :---- | :---------------------------- | :--------: | :-------------------: | +| icon | Источник SVG-иконки. | `IconData` | | +| color | Пользовательский цвет иконки. | `string` | | + +### Свойства текста + +| Имя | Описание | Тип | Значение по умолчанию | +| :---- | :------------------------------ | :------: | :-------------------: | +| text | Текст, отображаемый на аватаре. | `string` | | +| color | Пользовательский цвет текста. | `string` | | + +## API CSS + +| Имя | Описание | +| :---------------------------- | :------------------------ | +| `--g-avatar-size` | Размер (ширина и высота). | +| `--g-avatar-background-color` | Цвет фона. | +| `--g-avatar-border-color` | Цвет границы. | +| `--g-avatar-color` | Цвет иконки и текста. | +| `--g-avatar-font-size` | Размер шрифта текста. | +| `--g-avatar-line-height` | Высота строки текста. | diff --git a/src/components/Avatar/README.md b/src/components/Avatar/README.md index 63f2edbcce..fa7fc961e3 100644 --- a/src/components/Avatar/README.md +++ b/src/components/Avatar/README.md @@ -8,13 +8,13 @@ import {Avatar} from '@gravity-ui/uikit'; ``` -The component intended to render avatars. It has three basic types of avatars: image, icon and text (initials). All of these types have special props to configure behaviour and appearance. +This component is intended for rendering avatars. It has three basic avatar types: image, icon, and text (name initials). All these types have special properties to configure the behavior and appearance. ## Types ### Image -This component can be used to render avatars using images. Provide the image via `imgUrl` property. +This component can be used to render avatars using images. To provide an image, use the `imgUrl` property. -Also, you can provide `srcSet` property to load images of different sizes. +You can also provide the `srcSet` property to load images of different sizes. -Avatar component has `fallbackImgUrl` property which allows you to provide the image that is shown when an image loading error occurs via the link `imgUrl` (CSP error or no original image). +The `Avatar` component has the `fallbackImgUrl` property which allows you to provide the image that is shown when an image loading error occurs, through the `imgUrl` link (CSP error or no original image). ### Icon -This component can be used to render avatars using icons. Provide the icon via `icon` property like in `Icon` component. +This component can be used to render avatars using icons. Use the `icon` property to provide an icon, just like you would do in case of the `Icon` component. ### Text -This component can be used to render avatars using text. Provide the text via `text` property. The text renders like initials (2 first letters of words) or just 2 first letters of a single word. +This component can be used to render avatars using text. Use the `text` property for that. The text is rendered as initials (first letters of two words) or just two first letters of a single word. ### Theme and view -The Avatar component has predefined themes (`normal`, `brand`) and views (`filled`, `outlined`) +The `Avatar` component has predefined themes (`normal`, `brand`) and views (`filled`, `outlined`). -Default theme: `normal` -Default view: `filled` +The default theme is `normal` and the default view is `filled`. ### Custom colors -Also, you can provide custom colors via props `backgroundColor`, `borderColor` and `color` (works only for icon and text avatars). These colors have a higher priority than the colors from the theme. +You can also provide custom colors through the `backgroundColor`, `borderColor`, and `color` properties (the latter works only for icon and text avatars). These colors have a higher priority than the theme colors. ### Size -To control the size of the `Avatar` use the `size` property. The default size is `m`. Possible values: `2xs`, `xs`, `s`, `m`, `l`, `xl`. +Use the `size` property to manage the `Avatar` size. The default size is `m`. The possible values are `xs`, `s`, `m`, `l`, and `xl`. ### Common -| Name | Description | Type | Default | -| :-------------- | :-------------------------------------- | :-------------------------------------: | :------: | -| size | Avatar size | `'2xs'` `'xs'` `'s'` `'m'` `'l'` `'xl'` | `m` | -| theme | Avatar theme | `'normal'` `'brand'` | `normal` | -| view | Avatar view | `'filled'` `'outlined'` | `filled` | -| backgroundColor | Custom background color | `string` | | -| borderColor | Custom border color | `string` | | -| title | HTML `title` attributes | `string` | | -| aria-label | `aria-label` for avatar block | `string` | | -| aria-labelledby | `aria-labelledby` for avatar block | `string` | | -| className | Custom CSS class for root element | `string` | | -| style | HTML style attribute | `React.CSSProperties` | | -| qa | HTML `data-qa` attribute, used in tests | `string` | | +| Name | Description | Type | Default | +| :-------------- | :----------------------------------------- | :-----------------------------: | :------: | +| size | Avatar size | `'xs'` `'s'` `'m'` `'l'` `'xl'` | `m` | +| theme | Avatar theme | `'normal'` `'brand'` | `normal` | +| view | Avatar filling and outlining options | `'filled'` `'outlined'` | `filled` | +| backgroundColor | Custom background color | `string` | | +| borderColor | Custom border color | `string` | | +| title | `title` HTML attribute | `string` | | +| aria-label | `aria-label` for the avatar section | `string` | | +| aria-labelledby | `aria-labelledby` for the avatar section | `string` | | +| className | Custom CSS class for the root element | `string` | | +| style | `style` HTML attribute | `React.CSSProperties` | | +| qa | `data-qa` HTML attribute, used for testing | `string` | | ### Image-specific -| Name | Description | Type | Default | -| :------------- | :-------------------------------------- | :----------------: | :---------: | -| imgUrl | HTML img `src` attribute | `string` | | -| fallbackImgUrl | Fallback image, shown if error happened | `string` | | -| sizes | HTML img `sizes` attribute | `string` | | -| srcSet | HTML img `srcSet` attribute | `string` | | -| alt | HTML img `alt` attribute | `string` | props.title | -| loading | HTML img `loading` attribute | `'eager'` `'lazy'` | | +| Name | Description | Type | Default | +| :------------- | :---------------------------------------- | :----------------: | :---------: | +| imgUrl | `img` `src` HTML attribute | `string` | | +| fallbackImgUrl | Fallback image shown if an error occurred | `string` | | +| sizes | `img` `sizes` HTML attribute | `string` | | +| srcSet | `img` `srcSet` HTML attribute | `string` | | +| alt | `img` `alt` HTML attribute | `string` | props.title | +| loading | `img` `loading` HTML attribute | `'eager'` `'lazy'` | | ### Icon-specific diff --git a/src/components/AvatarStack/README-ru.md b/src/components/AvatarStack/README-ru.md new file mode 100644 index 0000000000..e203b1d174 --- /dev/null +++ b/src/components/AvatarStack/README-ru.md @@ -0,0 +1,52 @@ + + +# AvatarStack + + + +```ts +import {AvatarStack} from '@gravity-ui/uikit'; +``` + +Этот компонент служит для создания стека изображений с наложением друг на друга. Опционально также может быть предусмотрен контрол. Обычно относится к аватарам пользователей. + +## Использование + +В целом `AvatarStack` не накладывает никаких ограничений на то, какие компоненты можно рендерить. Ниже приведен пример его типичного использования: + +```tsx + + + + + +``` + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------: | :-------------------: | +| max | Устанавливает максимальное количество аватаров, которые будут отображаться перед кнопкой `More`. Если количество аватаров меньше `max` всего на 1, кнопка `More` будет заменена на аватар. | `number` | 3 | +| overlapSize | Определяет, насколько каждый элемент должен перекрывать следующий. Для аватаров размером от `xs` до `m` рекомендуется использовать `s`, для `l` — `m`, а для `xl` — `l`. | `s`, `m`, `l` | `s` | +| size | Размер контрола, отображающего дополнительные аватары. Значение соответствует размеру `Avatar`. | `AvatarSize` | | +| className | Имя CSS-класса корневого DOM-узла. | `string` | | +| children | Список аватаров, которые могут иметь дополнительные обертки. | `Object[]` | | +| renderMore | Пользовательская функция для отрисовки контрола, отображающего дополнительные аватары. | `function(options: {count: number}): ReactElement` | | + +### AvatarStack.MoreButton + +Компонент для переопределения кнопки `More`. + +```tsx + ( + + + + )} +> + + + + +``` diff --git a/src/components/AvatarStack/README.md b/src/components/AvatarStack/README.md index 70ac7141df..d1efb5bc09 100644 --- a/src/components/AvatarStack/README.md +++ b/src/components/AvatarStack/README.md @@ -8,11 +8,11 @@ import {AvatarStack} from '@gravity-ui/uikit'; ``` -Stack of images with overlap over next image and optional control. This is usually users avatars. +This component is used for a stack of images with overlap over one another and, optionally, a control. It usually refers to user avatars. ## Usage -Component is not limit you to what components to render, basic usage is: +Basically, `AvatarStack` does not have any limitations in terms of what components to render. See an example of its common usage below: ```tsx @@ -24,19 +24,18 @@ Component is not limit you to what components to render, basic usage is: ## Properties -| Name | Description | Type | Default | -| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------: | :-----: | -| max | How much avatars should be visible before more button. If avatars count is only 1 short from `max`, than more button would be replaced with avatar. | `number` | 3 | -| total | Total amount of items, used to calculate number of not rendered avatars | `number` | | -| overlapSize | How much each item should overlap next one. `s` recommended for `Avatar`'s of sizes `xs`-`m`, `m` recomended for `l` size avatars and `l` overlap for `xl` avatars | `s`, `m`, `l` | `s` | -| size | Size for control displaying extra avatars. Value same to `Avatar` size. | `AvatarSize` | | -| className | Class name of root DOM node | `string` | | -| children | List of avatars, probably with some extra wrappers | `Object[]` | | -| renderMore | Custom render for control displaying extra avatars | `function(options: {count: number}): ReactElement` | | +| Name | Description | Type | Default | +| :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------: | :-----: | +| max | Determines how many avatars are visible before the `More` button. If avatar count is only 1 short from `max`, the `More` button will be replaced with an avatar. | `number` | 3 | +| overlapSize | Determines how much each item should overlap the next one. You may want to use `s` for `xs` to `m`-sized `Avatar`s , `m` for `l`-sized, and `l`, for `xl`-sized. | `s`, `m`, `l` | `s` | +| size | Size for the control displaying extra avatars. Its value is the same as the `Avatar` size. | `AvatarSize` | | +| className | Class name of the root DOM node | `string` | | +| children | List of avatars that may also have extra wrappers | `Object[]` | | +| renderMore | Custom render for the control displaying extra avatars | `function(options: {count: number}): ReactElement` | | ### AvatarStack.MoreButton -Component for overriding more button +Component for overriding the `More` button ```tsx ``` - -Alternatively, `` could be used. This component doesn't have ` + + +``` + + + +### Контурная кнопка (`outlined`) + +`outlined` — используется для вторичных действий, требующих меньшего внимания. Может использоваться как с основной кнопкой, так и без нее; при этом, если есть основная кнопка, она должна быть акцентирована. + +`outlined-action`: Обычно используется как ссылка на другую страницу или внешний ресурс. + +Этот тип кнопки также имеет дополнительные семантические варианты: `outlined-info`, `outlined-success`, `outlined-warning` и `outlined-danger`. + + + + + +```tsx + + + + + + + +``` + + + +### Плоская кнопка (`flat`) + +`flat` — используется для вспомогательных действий, требующих наименьшего внимания. Такие элементы часто встречаются в списках кнопок или иконок действий (без текста) в редакторах. + +`flat-secondary` — менее акцентированная версия кнопки `flat`. Часто используется в качестве вспомогательной кнопки в диалогах и модальных окнах. + +`flat-action` — обычно используется как ссылка на другую страницу или внешний ресурс. + +Также имеет дополнительные семантические варианты: `outlined-info`, `outlined-success`, `outlined-warning` и `outlined-danger`. + + + + + +```tsx + + + + + + + + +``` + + + +### Контрастная кнопка (`contrast`) + +Кнопки `normal-contrast`, `outline-contrast` и `flat-contrast` выделяют действия на фоне сложного фона, например, на баннере или фоне с инверсией. + + + + + +```tsx + + + +``` + + + +## Иконки + +Чтобы добавить иконку в `Button`, используйте компонент [`Icon`](../Icon), который представляет собой обертку для SVG-файлов. + + + + + +```tsx + + + + +``` + + + +## Состояния + +`Button` может иметь разные состояния: + +`disabled` — когда взаимодействие с кнопкой по каким-либо причинам недоступно. + +`loading` — когда в фоновом режиме выполняются асинхронные процессы. + +`selected` — когда пользователь может может включить (**Enable**) или отключить (**Disable**) кнопку. + + + + + +```tsx + + + +``` + + + +## Размер + +Размер `Button` можно настроить с помощью свойства `size`. Размер по умолчанию — `m`. + + + + + +```tsx + + + + + +``` + + + +## Ширина + +Для управления поведением компонента `Button` внутри контейнера используйте свойство `width`: + +`auto` — ограничивает максимальную ширину кнопки, скрывая переполняющее содержимое с помощью многоточия. + +`max` — подгоняет ширину кнопки под размер родительского контейнера, также скрывая переполняющее содержимое с помощью многоточия. + + + +## Форматирование краев + +Свойство `pin` позволяет настраивать форму _начальных_ и _конечных_ краев элемента и обычно используется для объединения нескольких кнопок в единый блок. +Значение свойства `pin` включает названия стилей _начального_ и _конечного_ краев, разделенных дефисом, например, `round-brick`. +Доступные стили краев: `round` (по умолчанию), `circle`, `brick` и `clear`. + + + + + +```tsx +
+ + +
+
+ + + +
+
+ + + + +
+``` + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :----------- | :-------------------------------------------------------------------------- | :-----------------------------: | :-------------------: | +| children | Содержимое кнопки. Можно использовать как текст, так и компонент ``. | `ReactNode` | | +| className | HTML-атрибут `class`. | `string` | | +| component | Переопределяет корневой компонент. | `ElementType` | `"button"` | +| disabled | Включает или отключает состояние `disabled`. | `false` | `false` | +| extraProps | Дополнительные свойства. | `Record` | | +| href | HTML-атрибут `href`. | `string` | | +| id | HTML-атрибут `id`. | `string` | | +| loading | Включает или отключает состояние `loading`. | `false` | `false` | +| onBlur | Обработчик события `blur`. | `Function` | | +| onClick | Обработчик события `click`. | `Function` | | +| onFocus | Обработчик события `focus`. | `Function` | | +| onMouseEnter | Обработчик события `mouseenter`. | `Function` | | +| onMouseLeave | Обработчик события `mouseleave`. | `Function` | | +| pin | Задает стиль краев кнопки. | `string` | `"round-round"` | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | +| rel | HTML-атрибут `rel`. | `string` | | +| selected | Включает или отключает состояние `selected`. | | | +| size | Задает размер кнопки. | `string` | `"m"` | +| style | HTML-атрибут `style`. | `React.CSSProperties` | | +| tabIndex | HTML-атрибут `tabIndex`. | `number` | | +| target | HTML-атрибут `target`. | `string` | | +| title | HTML-атрибут `title`. | `string` | | +| type | HTML-атрибут `type`. | `"button"` `"submit"` `"reset"` | `"button"` | +| view | Задает внешний вид кнопки. | `string` | `"normal"` | +| width | `"auto"` `"max"` | `"auto"` `"max"` | | + +## API CSS + +| Имя | Описание | +| :---------------------------------- | :------------------------------------- | +| `--g-button-text-color` | Цвет текста. | +| `--g-button-text-color-hover` | Цвет текста при ховере. | +| `--g-button-background-color` | Цвет фона. | +| `--g-button-background-color-hover` | Цвет фона при ховере. | +| `--g-button-border-width` | Ширина границы. | +| `--g-button-border-color` | Цвет границы. | +| `--g-button-border-style` | Стиль границы. | +| `--g-button-focus-outline-width` | Толщина контура при получении фокуса. | +| `--g-button-focus-outline-color` | Цвет контура при получении фокуса. | +| `--g-button-focus-outline-style` | Стиль контура при получении фокуса. | +| `--g-button-focus-outline-offset` | Смещение контура при получении фокуса. | +| `--g-button-height` | Высота (высота строки). | +| `--g-button-padding` | Боковые отступы. | +| `--g-button-border-radius` | Радиус скругления углов. | +| `--g-button-font-size` | Размер шрифта текста. | +| `--g-button-icon-size` | Размер иконки. | +| `--g-button-icon-offset` | Смещение иконки. | diff --git a/src/components/Button/README.md b/src/components/Button/README.md index 7b854c711a..0c86e93e33 100644 --- a/src/components/Button/README.md +++ b/src/components/Button/README.md @@ -8,23 +8,21 @@ import {Button} from '@gravity-ui/uikit'; ``` -Buttons act as a trigger for certain actions. While this is their main purpose, in very rare cases, -they can be used as links to navigate to another pages. +Buttons act as a trigger for certain actions. While this is their main purpose, in some very rare cases, they can be used as links to navigate to other pages. ## Appearance -There are four `Button` view types: basic, outlined, flat and contrast. -The `Button`'s appearance is determined by the `view` property. +There are four `Button` types in terms of appearance: basic, outlined, flat, and contrast. +The `Button` appearance is determined by the `view` property. ### Basic -`action` - the most prominent button, used for the primary action on a screen which requires the most attention. +`action`: The most distinctive type of `Button`. It is used for the primary action on a screen that requires the most attention. We recommend using only one such button per page. -`normal` - default type of the `Button`, designed for secondary actions or to maintain the importance of an -action without drawing too much attention to it. +`normal`: Default type of `Button` designed for secondary actions or to maintain the importance of an action without drawing too much attention to it. -`raised` - placed above the content as a "floating" element, usually with a fixed location. +`raised`: Placed above the content as a floating element, usually with a fixed location. ### Outlined -`outlined` - used for secondary actions that require less attention on a page. Can be used with or without a main button (only with an accented one). +`outlined`: Used for secondary actions that require less attention. It can be used with or without a main button; in the former case, it must be an emphasized one. -`outlined-action` - usually used as a link to another page or external resource. +`outlined-action`: Usually used as a link to another page or external resource. -There are also semantic variants of this type, which can be used when additional semantics are needed: `outlined-info`, `outlined-success`, `outlined-warning`, `outlined-danger`. +This type also has semantic variations that can be used when additional semantics are needed: `outlined-info`, `outlined-success`, `outlined-warning`, and `outlined-danger`. ### Flat -`flat` - used for auxiliary actions that require the least attention on a page. It is often used in a list of buttons or action icons (with no text) in an editor. +`flat`: Used for auxiliary actions that require the least attention. It is often used in a list of buttons or action icons (without text) in an editor. -`flat-secondary` - less accented than the `flat` button. It's often used as the secondary button in dialog boxes and modal windows. +`flat-secondary`: Less emphasized than the `flat` button. It is often used as a secondary button in dialog boxes and modal windows. -`flat-action` - usually used as link to another page or external resource. +`flat-action`: Usually used as a link to another page or external resource. -There are also semantic variants of this view, which can be used in places where additional semantic needed: `flat-info`, `flat-success`, `flat-warning`, `flat-danger`. +It also has semantic variations that can be used where additional semantics are needed: `outlined-info`, `outlined-success`, `outlined-warning`, and `outlined-danger`. ### Contrast -`normal-contrast`, `outline-contrast` and `flat-contrast` buttons highlight actions against complex background, e.g., in a banner or against an inverse background. +The `normal-contrast`, `outline-contrast`, and `flat-contrast` buttons highlight actions against complex background, e.g., in a banner, or against an inverse background. ## Icons -To add an icon to the `Button`, you should use the [`Icon`](../Icon) component, a special wrapper for SVGs. +To add an icon to a `Button`, use the [`Icon`](../Icon) component, which is a special wrapper for SVGs. ## States -The `Button` can be in different states. +A `Button` can have different states: -`disabled` - when the button is unavailable for some reason. +`disabled`: When the button is unavailable for some reason. -`loading` - when some asynchronous processes are happening in the background, `selected` - when the user can switch between "Enable" and "Disable". +`loading`: When some asynchronous processes are running in the background. + +`selected`: When the user can **Enable** and **Disable** the button. ## Size -To control the size of the `Button` use the `size` property. Default size is `m`. +Use the `size` property to manage the `Button` size. The default size is `m`. ## Width -The `width` property controls how the `Button` behaves inside the container. +Use the `width` property to manage the way the `Button` behaves inside the container: -`auto` - limits the maximum width of the component, hides overflowing content with an ellipsis. +`auto`: Limits the maximum width of the `Button` by hiding the overflowing content with an ellipsis. -`max` - matches the width to the width of the parent container, also hides overflowing content with an ellipsis. +`max`: Matches the `Button` width to the width of the parent container, also hiding the overflowing content with an ellipsis. ## Pin -The `pin` property allows you to control the shape of the "start" and "end" edges and is usually used for combining multiple buttons in a single unit. -The value of the `pin` property consists of "start" and "end" style names divided by a dash, e.g. `"round-brick"`. -The edge styles are: `round` (default), `circle`, `brick` and `clear`. +The `pin` property allows you to manage the shape of the _start_ and _end_ edges and is usually used for combining multiple buttons in a single unit. +The `pin` property value consists of the _start_ and _end_ style names separated by a hyphen, e.g., `round-brick`. +The edge styles are: `round` (default), `circle`, `brick`, and `clear`. ## Properties -| Name | Description | Type | Default | -| :----------- | :-------------------------------------------------------- | :-----------------------------: | :-------------: | -| children | Button content. You can mix text with `` component | `ReactNode` | | -| className | HTML `class` attribute | `string` | | -| component | Overrides the root component | `ElementType` | `"button"` | -| disabled | Toggles `disabled` state | `false` | `false` | -| extraProps | Any additional props | `Record` | | -| href | HTML `href` attribute | `string` | | -| id | HTML `id` attribute | `string` | | -| loading | Toggles `loading` state | `false` | `false` | -| onBlur | `blur` event handler | `Function` | | -| onClick | `click` event handler | `Function` | | -| onFocus | `focus` event handler | `Function` | | -| onMouseEnter | `mouseenter` event handler | `Function` | | -| onMouseLeave | `mouseleave` event handler | `Function` | | -| pin | Sets button edges style | `string` | `"round-round"` | -| qa | HTML `data-qa` attribute, used in tests | `string` | | -| rel | HTML `rel` attribute | `string` | | -| selected | Toggles `selected` state | | | -| size | Sets button size | `string` | `"m"` | -| style | HTML `style` attribute | `React.CSSProperties` | | -| tabIndex | HTML `tabIndex` attribute | `number` | | -| target | HTML `target` attribute | `string` | | -| title | HTML `title` attribute | `string` | | -| type | HTML `type` attribute | `"button"` `"submit"` `"reset"` | `"button"` | -| view | Sets button appearance | `string` | `"normal"` | -| width | `"auto"` `"max"` | `"auto"` `"max"` | | +| Name | Description | Type | Default | +| :----------- | :----------------------------------------------------------------- | :-----------------------------: | :-------------: | +| children | Button content. You can use both text and the `` component. | `ReactNode` | | +| className | `class` HTML attribute | `string` | | +| component | Overrides the root component | `ElementType` | `"button"` | +| disabled | Toggles the `disabled` state | `false` | `false` | +| extraProps | Additional properties | `Record` | | +| href | `href` HTML attribute | `string` | | +| id | `id` HTML attribute | `string` | | +| loading | Toggles the `loading` state | `false` | `false` | +| onBlur | `blur` event handler | `Function` | | +| onClick | `click` event handler | `Function` | | +| onFocus | `focus` event handler | `Function` | | +| onMouseEnter | `mouseenter` event handler | `Function` | | +| onMouseLeave | `mouseleave` event handler | `Function` | | +| pin | Sets the button edge style | `string` | `"round-round"` | +| qa | `data-qa` HTML attribute, used for testing | `string` | | +| rel | `rel` HTML attribute | `string` | | +| selected | Toggles the `selected` state | | | +| size | Sets the button size | `string` | `"m"` | +| style | `style` HTML attribute | `React.CSSProperties` | | +| tabIndex | `tabIndex` HTML attribute | `number` | | +| target | `target` HTML attribute | `string` | | +| title | `title` HTML attribute | `string` | | +| type | `type` HTML attribute | `"button"` `"submit"` `"reset"` | `"button"` | +| view | Sets the button appearance | `string` | `"normal"` | +| width | `"auto"` `"max"` | `"auto"` `"max"` | | ## CSS API @@ -487,11 +487,11 @@ LANDING_BLOCK--> | `--g-button-border-width` | Border width | | `--g-button-border-color` | Border color | | `--g-button-border-style` | Border style | -| `--g-button-focus-outline-width` | Focus outline color | +| `--g-button-focus-outline-width` | Focus outline width | | `--g-button-focus-outline-color` | Focus outline color | | `--g-button-focus-outline-style` | Focus outline style | | `--g-button-focus-outline-offset` | Focus outline offset | -| `--g-button-height` | Height, line-height | +| `--g-button-height` | Height (line height) | | `--g-button-padding` | Side paddings | | `--g-button-border-radius` | Border radius | | `--g-button-font-size` | Text font size | diff --git a/src/components/Card/README-ru.md b/src/components/Card/README-ru.md new file mode 100644 index 0000000000..f76f5d0aa1 --- /dev/null +++ b/src/components/Card/README-ru.md @@ -0,0 +1,157 @@ + + +# Card + + + +```tsx +import {Card} from '@gravity-ui/uikit'; +``` + +## Описание + +Компонент `Card` — это React-контейнер в виде карточки с возможностью настройки стилей и функций, применяемый для эстетичного и упорядоченного представления различного контента. + +## Внешний вид + +`Card` можно визуализировать с использованием различных комбинаций стилей: + +- `theme` — `normal`, `info`, `success`, `warning`, `danger` или `utility`; +- `type` — `selection`, `action` или `container`; +- `view` — `outlined` или `clear`, или `outlined`, `filled` или `raised` (в зависимости от параметра `type`). + +## `Theme` (тема) + +Параметр `theme` используется для указания стиля темы карточки. Он определяет цветовую схему карточки и ее внешний вид. + +Выбирая разные значения темы, вы можете кастомизировать внешний вид `Card` так, чтобы он соответствовал вашим целям и необходимому стилю. + +- `normal` — обычная/стандартная тема карточки; +- `info` — тема для отображения нейтральной информации; +- `success` — тема для отображения положительного или подтверждающего контента; +- `warning` — тема для отображения предупреждений; +- `danger` — тема для отображения контента, связанного с критическими проблемами или ошибками; +- `utility` — тема для отображения полезных советов. + + + +## `Type` (тип) + +Этот параметр используется для определения типа `Card`. Он позволяет настраивать внешний вид и поведение карточки. + +- `container` — карточка, которая выступает в роли контейнера для других элементов. Она обеспечивает структурированную компоновку контента. +- `action` — карточка с интерактивным элементом — например, кнопкой, которая активирует определенное действие при нажатии. +- `selection` — карточка, которую можно выбрать или нажать, чтобы выполнить определенное действие. + + + +## `View` (вид) + +Данный параметр используется для указания вида или стиля компоновки `Card`. Он позволяет настраивать внешний вид и расположение содержимого карточки: + +- `clear` — без стиля; +- `outlined` — добавляет контурную обводку для выделения содержимого карточки; +- `filled` — добавляет заливку содержимого карточки; +- `raised` — добавляет тень для создания эффекта приподнятого контейнера. + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------- | :------------------------------------------------------------------------------------------- | :---------: | :-------------------: | +| children | Содержимое карточки. | `ReactNode` | | +| type | Тип `Card`. Определяет, какие свойства доступны. | `string` | `"container"` | +| view | Доступно только для типов `"container"` и `"selection"`. | `string` | `"outlined"` | +| theme | Базовый цвет карточки. Свойство доступно только для типа `"container"`. | `string` | `"normal"` | +| size | Размер `Card`. Определяет, какие свойства доступны. | `string` | `"m"` | +| className | CSS-класс. | `string` | | +| onClick | Обработчик клика по карточке. Свойство доступно только для типов `"selection"` и `"action"`. | `Function` | | +| selected | Выбранная карточка. Свойство доступно только для типа `"selection"`. | `Boolean` | | +| disabled | Неактивная карточка. Свойство доступно только для типов `"selection"` и `"action"`. | `Boolean` | | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | + +## API CSS + +| Имя | Описание | +| :-------------------------- | :----------------------- | +| `--g-card-background-color` | Цвет фона. | +| `--g-card-border-width` | Ширина границы. | +| `--g-card-border-color` | Цвет границы. | +| `--g-card-border-radius` | Радиус скругления углов. | +| `--g-card-box-shadow` | Тень. | diff --git a/src/components/Card/README.md b/src/components/Card/README.md index 8d173c8f4c..f2d951f551 100644 --- a/src/components/Card/README.md +++ b/src/components/Card/README.md @@ -10,28 +10,28 @@ import {Card} from '@gravity-ui/uikit'; ## Description -The `Card` UI component is a reusable React component that represents a card-like container with customizable styles and functionality. It is used to display information or content in a visually appealing and organized manner. +`Card` is a reusable React component that basically is a card-like container with customizable styles and features. It is used to display information or content in a visually appealing and well-organized manner. ## Appearance -`Card` can be displayed with multiple styled combination +`Card` can be displayed with multiple style combinations: -- theme (`normal`, `info`, `success`, `warning`, `danger`, `utility`) -- type (`selection`, `action`, `container`) -- view (`outlined`, `clear`) or (`outlined`, `filled`, `raised`) depends on `type` parameter +- `theme`: `normal`, `info`, `success`, `warning`, `danger`, or `utility`. +- `type`: `selection`, `action`, or `container`. +- `view`:`outlined` or `clear`, or `outlined`, `filled`, or `raised` (depending on the `type` parameter). ## Theme -This parameter is used to specify the theme style of the card. It determines the color scheme and visual appearance of the card. +This parameter is used to specify the card's theme style. It determines the card's color scheme and appearance. -By specifying different theme values, you can customize the visual appearance of the `Card` component to match the desired style and purpose. +By specifying different theme values, you can customize the `Card` visual appearance to match your purpose and the style you need. -- `normal`: represents the normal/default theme of the card. -- `info`: represents the theme for displaying informational content. -- `success`: represents the theme for displaying positive/affirmative content. -- `warning`: represents the theme for displaying warning or cautionary content. -- `danger`: represents the theme for displaying content related to danger or critical situations. -- `utility`: represents the theme for displaying utility content. +- `normal`: Normal/default theme of the card. +- `info`: Theme for displaying neutral information. +- `success`: Theme for displaying positive or affirmative content. +- `warning`: Theme for displaying warnings. +- `danger`: Theme for displaying the content related to critical issues or errors. +- `utility`: Theme for displaying useful tips. This parameter is used to define the type of the `Card` component. It allows you to customize the appearance and behavior of the card. -- `container`: represents a card that acts as a container for other elements. It provides a structured layout for content. -- `action`: represents a card with an interactive element, such as a button, that triggers an action when clicked. -- `selection`: represents a card that can be selected or clicked to perform a specific action. +- `container`: Card that acts as a container for other elements. It provides a structured layout for content. +- `action`: Card with an interactive element, such as a button, that triggers an action when clicked. +- `selection`: Card that can be selected or clicked to perform a specific action. ## View -This parameter is used to specify the view or layout style of the `Card`. It allows you to customize the appearance and arrangement of the card content. +This parameter is used to specify the `Card` view or layout style. It allows you to customize the appearance and arrangement of the card content. -- `clear`: no style will be applied. -- `outlined`: applies thin border to highlight card content. -- `filled`: fills in the card content. -- `raised`: applies a shadow to slightly lift the container. +- `clear`: No style. +- `outlined`: Applies a thin border to highlight the card content. +- `filled`: Fills in the card content. +- `raised`: Applies a shadow to slightly lift the container. ## Properties -| Name | Description | Type | Default | -| :-------- | :------------------------------------------------------------------ | :---------: | :-----------: | -| children | Card's content | `ReactNode` | | -| type | The Card type affects which properties are available | `string` | `"container"` | -| view | Available for `type`: `"container"` and `"selection"` | `string` | `"outlined"` | -| theme | Card's base color. Available for `type`: `"container"` | `string` | `"normal"` | -| size | The Card size affects which properties are available | `string` | `"m"` | -| className | CSS class | `string` | | -| onClick | Card click handler. Available for `type`: `"selection"`, `"action"` | `Function` | | -| selected | Selected card. Available for type: `"selection"` | `Boolean` | | -| disabled | Disabled card. Available for type: `"selection"`, `"action"` | `Boolean` | | -| qa | HTML `data-qa` attribute, used in tests | `string` | | +| Name | Description | Type | Default | +| :-------- | :------------------------------------------------------------------------------------------------ | :---------: | :-----------: | +| children | Card content | `ReactNode` | | +| type | The `Card` type determines which properties are available. | `string` | `"container"` | +| view | This property is only available for the `"container"` and `"selection"` `type`s. | `string` | `"outlined"` | +| theme | Card's base color. This property is only available for the `"container"` `type`. | `string` | `"normal"` | +| size | The `Card` size determines which properties are available. | `string` | `"m"` | +| className | CSS class | `string` | | +| onClick | Card click handler. This property is only available for the `"selection"` and `"action"` `type`s. | `Function` | | +| selected | Selected card. This property is only available for the `"selection"` `type`. | `Boolean` | | +| disabled | Disabled card. This property is only available for the `"selection"` and `"action"` `type`s. | `Boolean` | | +| qa | `data-qa` HTML attribute, used for testing | `string` | | ## CSS API diff --git a/src/components/Checkbox/README-ru.md b/src/components/Checkbox/README-ru.md new file mode 100644 index 0000000000..246bef13b5 --- /dev/null +++ b/src/components/Checkbox/README-ru.md @@ -0,0 +1,157 @@ + + +# Checkbox + + + +```tsx +import {Checkbox} from '@gravity-ui/uikit'; +``` + +Компонент `Checkbox` позволяет пользователю выбрать или отменить выбор определенного значения. + +## Состояния + +`Checkbox` может иметь разные состояния: + +- `Checked` — чекбокс отмечен галочкой. +- `Disabled` — чекбокс недоступен. +- `Indeterminate` — чекбокс находится в промежуточном состоянии между отмеченным и неотмеченным. + + + + + +```tsx +Unchecked +Checked +Disabled +Indeterminate +``` + + + +## Размер + +Размер `Checkbox` можно настроить с помощью свойства `size`. Размер по умолчанию — `m`. + + + + + +```tsx +M Size +L Size +``` + + + +## Лейбл + +Лейбл для `Checkbox` можно задать через свойство `content` или передать его как дочерний элемент. + + + + + +```tsx +
+ +
+ + Content as children + +
+
+``` + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :------------- | :---------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------: | :-------------------: | +| children | Содержимое чекбокса (как правило, лейбл). | `ReactNode` | | +| content | Содержимое чекбокса (альтернатива `children`). | `ReactNode` | | +| disabled | Включает или отключает состояние `disabled` у чекбокса. | `boolean` | `false` | +| checked | Включает или отключает состояние `checked` у чекбокса. | `boolean` | `false` | +| defaultChecked | Задает начальное состояние `checked` при монтировании компонента. | `boolean` | `false` | +| onUpdate | Срабатывает при изменении состояния чекбокса пользователем и передает значение `checked` как аргумент обратного вызова. | `(checked: boolean) => void` | | +| onChange | Срабатывает при изменении состояния чекбокса пользователем и передает событие изменения как аргумент обратного вызова. | `Function` | | +| onFocus | Обработчик события, вызываемый, когда элемент ввода чекбокса получает фокус. | `Function` | | +| onBlur | Обработчик события, вызываемый, когда элемент ввода чекбокса теряет фокус. | `Function` | | +| size | Определяет размер чекбокса. | `m` `l` | `m` | +| id | HTML-атрибут `id`. | `string` | | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | +| style | HTML-атрибут `style`. | `React.CSSProperties` | | +| className | HTML-атрибут `class`. | `string` | | +| title | HTML-атрибут `title`. | `string` | | +| name | HTML-атрибут `name` для элемента ввода. | `string` | | +| value | HTML-атрибут `value` для элемента ввода. | `string` | | +| indeterminate | Включает или отключает состояние `indeterminate` у чекбокса. | `boolean` | `false` | +| controlProps | Дополнительные свойства базового элемента ввода. | `React.InputHTMLAttributes` | | +| controlRef | Ссылка на базовый элемент ввода. | `React.Ref` | | diff --git a/src/components/Checkbox/README.md b/src/components/Checkbox/README.md index 98e12dac19..f5c7088681 100644 --- a/src/components/Checkbox/README.md +++ b/src/components/Checkbox/README.md @@ -12,11 +12,11 @@ The `Checkbox` component allows the user to select or deselect a specific value. ## States -The Checkbox can be in different states. +A `Checkbox` can have different states: -- Checked - when the checkbox is selected. -- Disabled - when the checkbox is unavailable for interaction. -- Indeterminate - when the checkbox is in an intermediate state between being selected and unselected. +- Checked: The checkbox is ticked. +- Disabled: The checkbox is unavailable. +- Indeterminate: The checkbox is in an intermediate state between being ticked and unticked. ## Size -To control the size of the `Checkbox`, use the `size` property. The default size is `m`. +Use the `size` property to manage the `Checkbox` size. The default size is `m`. ## Label -You can set a label for a `Checkbox` component using the `content` property or pass it as children. +You can assign a label to a `Checkbox` using the `content` property or provide it as a child property. ## Properties -| Name | Description | Type | Default | -| :------------- | :--------------------------------------------------------------------------------------------------- | :-------------------------------------------: | :-----: | -| children | The content of the checkbox (usually a label). | `ReactNode` | | -| content | The content of the checkbox (alternative to children). | `ReactNode` | | -| disabled | Toggles the `disabled` state of the checkbox. | `boolean` | `false` | -| checked | Toggles the checked state of the checkbox. | `boolean` | `false` | -| defaultChecked | Sets the initial checked state when the component is mounted. | `boolean` | `false` | -| onUpdate | Fires when the user changes the checkbox state. Provides the checked value as a callback's argument. | `(checked: boolean) => void` | | -| onChange | Fires when the user changes the checkbox state. Provides the change event as a callback's argument. | `Function` | | -| onFocus | Event handler for when the checkbox input element receives focus. | `Function` | | -| onBlur | Event handler for when the checkbox input element loses focus. | `Function` | | -| size | Sets the size of the checkbox. | `m` `l` | `m` | -| id | HTML `id` attribute | `string` | | -| qa | HTML `data-qa` attribute, used in tests. | `string` | | -| style | HTML `style` attribute | `React.CSSProperties` | | -| className | HTML `class` attribute | `string` | | -| title | HTML `title` attribute | `string` | | -| name | HTML `name` attribute for the input element. | `string` | | -| value | HTML `value` attribute for the input element. | `string` | | -| indeterminate | Toggles the indeterminate state of the checkbox. | `boolean` | `false` | -| controlProps | Additional props for the underlying input element. | `React.InputHTMLAttributes` | | -| controlRef | Ref to the underlying input element. | `React.Ref` | | +| Name | Description | Type | Default | +| :------------- | :---------------------------------------------------------------------------------------------------- | :-------------------------------------------: | :-----: | +| children | Checkbox content (usually, a label). | `ReactNode` | | +| content | Checkbox content (alternative to children). | `ReactNode` | | +| disabled | Toggles the `disabled` state of the checkbox. | `boolean` | `false` | +| checked | Toggles the `checked` state of the checkbox. | `boolean` | `false` | +| defaultChecked | Sets the initial checked state when the component is mounted. | `boolean` | `false` | +| onUpdate | Fires when the user changes the checkbox state and provides the checked value as a callback argument. | `(checked: boolean) => void` | | +| onChange | Fires when the user changes the checkbox state and provides the change event as a callback argument. | `Function` | | +| onFocus | Event handler to use when the checkbox input element receives focus. | `Function` | | +| onBlur | Event handler to use when the checkbox input element loses focus. | `Function` | | +| size | Determines the checkbox size. | `m` `l` | `m` | +| id | `id` HTML attribute | `string` | | +| qa | `data-qa` HTML attribute, used for testing | `string` | | +| style | `style` HTML attribute | `React.CSSProperties` | | +| className | `class` HTML attribute | `string` | | +| title | `title` HTML attribute | `string` | | +| name | `name` HTML attribute for the input element. | `string` | | +| value | `value` HTML attribute for the input element. | `string` | | +| indeterminate | Toggles the `indeterminate` state of the checkbox. | `boolean` | `false` | +| controlProps | Additional propeties for the underlying input element. | `React.InputHTMLAttributes` | | +| controlRef | Ref to the underlying input element. | `React.Ref` | | diff --git a/src/components/ClipboardButton/README-ru.md b/src/components/ClipboardButton/README-ru.md new file mode 100644 index 0000000000..82834edc21 --- /dev/null +++ b/src/components/ClipboardButton/README-ru.md @@ -0,0 +1,51 @@ + + +# ClipboardButton + + + +```tsx +import {ClipboardButton} from '@gravity-ui/uikit'; +``` + +`ClipboardButton` — компонент, объединяющий [`CopyToClipboard`](../CopyToClipboard/README.md) и [`ClipboardIcon`](../ClipboardIcon/README.md). [`CopyToClipboard`](../CopyToClipboard/README.md) отправляет текст в буфер обмена и использует [`ClipboardIcon`](../ClipboardIcon/README.md) для отображения анимации во время копирования. + + + + + +```tsx + +``` + + + +## Свойства + +`ClipboardButton` наследует свойства от `Button`, за исключением `href`, `component`, `target`, `rel`, `loading` и `children`. + +| Имя | Описание | Тип | Значение по умолчанию | +| :----------------- | :-------------------------------------------------------------------------- | :-----------------------------------------------: | :-------------------: | +| hasTooltip | Включает или отключает отображение тултипа. | `boolean` | `true` | +| onCopy | Обратный вызов после копирования:`(text: string, result: boolean) => void`. | `Function` | | +| options | Параметры копирования в буфер обмена. | [CopyToClipboardOptions](#copytoclipboardoptions) | | +| text | Копируемый текст. | `string` | | +| timeout | Время до возврата состояния в норму после клика по кнопке. | `number` | `1000` | +| tooltipInitialText | Текст, отображаемый перед копированием. | `string` | `"Copy"` | +| tooltipSuccessText | Текст, отображаемый после копирования. | `string` | `"Copied!"` | + +### CopyToClipboardOptions + +| Имя | Описание | Тип | Значение по умолчанию | +| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------: | :-------------------: | +| debug | Включает вывод в консоль. | `boolean` | `false` | +| message | Сообщение-подсказка. | `string` | | +| format | Устанавливает MIME-тип для копирования. Используйте `text/html` для копирования в формате HTML и `text/plain`, если при вставке в текстовый редактор не нужно наследовать стили. | `string` | `"text/html"` | diff --git a/src/components/ClipboardButton/README.md b/src/components/ClipboardButton/README.md index a46c432de4..1c24b45484 100644 --- a/src/components/ClipboardButton/README.md +++ b/src/components/ClipboardButton/README.md @@ -8,7 +8,7 @@ import {ClipboardButton} from '@gravity-ui/uikit'; ``` -A component that puts all together: [`CopyToClipboard`](../CopyToClipboard/README.md) and [`ClipboardIcon`](../ClipboardIcon/README.md). [`CopyToClipboard`](../CopyToClipboard/README.md) component takes given text into the clipboard and as a wrapper uses [`ClipboardIcon`](../ClipboardIcon/README.md) as a content for itself to display animation when copy-paste happening. +This component puts [`CopyToClipboard`](../CopyToClipboard/README.md) and [`ClipboardIcon`](../ClipboardIcon/README.md) together. [`CopyToClipboard`](../CopyToClipboard/README.md) sends a text to the clipboard and, as a wrapper, uses [`ClipboardIcon`](../ClipboardIcon/README.md) as content for itself to display animation when a copy-paste event happens. ## Properties -`ClipboardButton` properties are inherited from `Button` [properties](../Button/README.md#properties) except `href`, `component`, `target`, `rel`, `loading`, `children`. +The `ClipboardButton` properties are inherited from the `Button` [properties](../Button/README.md#properties), except for `href`, `component`, `target`, `rel`, `loading`, and `children`. -| Name | Description | Type | Default | -| :----------------- | :----------------------------------------------------------------------- | :-----------------------------------------------: | :---------: | -| hasTooltip | Disable tooltip. Tooltip won't be shown | `boolean` | `true` | -| onCopy | Callback after copy `(text: string, result: boolean) => void` | `Function` | | -| options | Copy to clipboard options | [CopyToClipboardOptions](#copytoclipboardoptions) | | -| text | Text to copy | `string` | | -| timeout | Time before state bounces back to its normal after the button is clicked | `number` | `1000` | -| tooltipInitialText | Text shown before copy | `string` | `"Copy"` | -| tooltipSuccessText | Text shown after copy | `string` | `"Copied!"` | +| Name | Description | Type | Default | +| :----------------- | :------------------------------------------------------------------------ | :-----------------------------------------------: | :---------: | +| hasTooltip | Toggles displaying the tooltip | `boolean` | `true` | +| onCopy | Callback after copying `(text: string, result: boolean) => void` | `Function` | | +| options | Copy to clipboard options | [CopyToClipboardOptions](#copytoclipboardoptions) | | +| text | Text to copy | `string` | | +| timeout | Time before the state switches back to normal after the button is clicked | `number` | `1000` | +| tooltipInitialText | Text shown before copying | `string` | `"Copy"` | +| tooltipSuccessText | Text shown after copying | `string` | `"Copied!"` | ### CopyToClipboardOptions | Name | Description | Type | Default | | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------: | :-----------: | -| debug | Enable output to console | `boolean` | `false` | +| debug | Enables output to console | `boolean` | `false` | | message | Prompt message | `string` | | -| format | Set the MIME type of what you want to copy as. Use `text/html` to copy as HTML, `text/plain` to avoid inherited styles showing when pasted into rich text editor. | `string` | `"text/html"` | +| format | Set the MIME type of what you want to copy. Use `text/html` to copy as HTML and `text/plain` to avoid showing inherited styles when pasted into rich text editor. | `string` | `"text/html"` | diff --git a/src/components/ClipboardIcon/README-ru.md b/src/components/ClipboardIcon/README-ru.md new file mode 100644 index 0000000000..f2961eb891 --- /dev/null +++ b/src/components/ClipboardIcon/README-ru.md @@ -0,0 +1,48 @@ + + +# ClipboardIcon + + + +```tsx +import {ClipboardIcon} from '@gravity-ui/uikit'; +``` + +Этот компонент в основном используется вместе с `CopyToClipboard` в качестве обертки. + +### Статус + +Иконка будет изменяться в зависимости от значения свойства `status`. + + + + + +```tsx + + {(status) => } + +``` + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------- | :------------------------------------------------- | :------- | :-------------------- | +| className | HTML-атрибут `class`. | `string` | | +| size | Определяет размер иконки. | `number` | | +| status | Принимает значения `pending`, `success` и `error`. | `string` | | diff --git a/src/components/ClipboardIcon/README.md b/src/components/ClipboardIcon/README.md index 5a8f13f097..6f3a08192d 100644 --- a/src/components/ClipboardIcon/README.md +++ b/src/components/ClipboardIcon/README.md @@ -8,11 +8,11 @@ import {ClipboardIcon} from '@gravity-ui/uikit'; ``` -This component is mainly used together with `CopyToClipboard` as wrap component. +This component is mainly used along with `CopyToClipboard` as a wrap component. ### Status -Depends on `status` property icon is changed. +Depending on the `status` property, the icon will be changing accordingly: ## Properties -| Name | Description | Type | Default | -| :-------- | :---------------------------------------------- | :------- | :------ | -| className | HTML `class` attribute | `string` | | -| size | Sets icon size | `number` | | -| status | Available values: `pending`, `success`, `error` | `string` | | +| Name | Description | Type | Default | +| :-------- | :---------------------------------------------------------- | :------- | :------ | +| className | `class` HTML attribute | `string` | | +| size | Determines the icon size | `number` | | +| status | The available values are `pending`, `success`, and `error`. | `string` | | diff --git a/src/components/CopyToClipboard/README-ru.md b/src/components/CopyToClipboard/README-ru.md new file mode 100644 index 0000000000..8c90970593 --- /dev/null +++ b/src/components/CopyToClipboard/README-ru.md @@ -0,0 +1,80 @@ + + +# CopyToClipboard + + + +```tsx +import {CopyToClipboard} from '@gravity-ui/uikit'; +``` + +`CopyToClipboard` — это оберточный компонент, который копирует текст в буфер обмена и может изменять свое содержимое в зависимости от возвращенного статуса. + +### Children (функция рендеринга) + +Данная функция рендеринга передается в виде свойства `children`. Она может изменять свое содержимое в зависимости от статуса, возвращаемого в качестве первого аргумента. +Доступны три статуса — `pending`, `success` и `error`: + +`pending` — исходный статус, возвращаемый функцией рендеринга в нейтральном состоянии; + +`success` — статус результата, возвращаемый функцией рендеринга в случае успешного выполнения; + +`error` — статус результата, возвращаемый функцией рендеринга в случае ошибки. + +Параметр `timeout` устанавливает время в миллисекундах для возврата к исходному статусу (`pending`) после получения любого из статусов результата (`success` или `error`). + + + + + +```tsx +const buttonText = { + pending: 'Click Me', + success: 'Copied!', + error: "Couldn't copy...", +}; + + + {(status) => } +; +``` + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :------- | :-------------------------------------------------------------------------- | :--------: | :-------------------: | +| children | Функция рендеринга `(status: CopyToClipboardStatus) => React.ReactElement`. | `Function` | | +| onCopy | Обработчик события `copy`. | `Function` | | +| text | Копируемый текст. | `string` | | +| timeout | Время в миллисекундах для возврата к исходному статусу. | `number` | | diff --git a/src/components/CopyToClipboard/README.md b/src/components/CopyToClipboard/README.md index 8141e47215..3646f7a01c 100644 --- a/src/components/CopyToClipboard/README.md +++ b/src/components/CopyToClipboard/README.md @@ -8,20 +8,20 @@ import {CopyToClipboard} from '@gravity-ui/uikit'; ``` -CopyToClipboard is a wrapper component that copies given text to clipboard and can update its content depends on returned status. +CopyToClipboard is a wrapper component that copies text to clipboard and can update its content depending on the returned status. ### Children (render function) -The render function passed as children props and can update its content depends on status that is returned as first argument in render function. -There are 3 available statuses: pending, success, error +This is a render function provided as children properties. It can update its content depending on the status that is returned as the first argument in the render function. +There are three available statuses: pending, success, and error. -`pending` - the initial status returned in render function in neutral case +`pending`: Initial status returned in the render function in the neutral case. -`success` - the result status returned in render function in success case +`success`: Result status returned in the render function in case of success. -`error` - the result status returned in render function in error case +`error`: Result status returned in the render function in case of error. -Option `timeout` set the time in ms to restore initial (`pending`) status after one of the result statuses (`success` or `error`). +The `timeout` option sets the time in ms to restore the initial (`pending`) status after one of the result statuses (`success` or `error`). + +# Divider + + + +```tsx +import {Divider} from '@gravity-ui/uikit'; +``` + +Компонент `Divider` (разделитель) представляет собой тонкую линию для разграничения и группировки элементов с целью усиления их визуальной иерархии. + +```tsx + +``` + +### Ориентация + +Ориентацию `Divider` можно задать с помощью свойства `direction`. Ориентация по умолчанию — `horizontal`. + +#### Горизонтальная ориентация + + + + + +```tsx +import {Container, Text, Divider} from '@gravity-ui/uikit'; + + + + Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aperiam, officiis! Fugit minus ea, + perferendis eum consectetur quae vitae. Aliquid, quam reprehenderit? Maiores sed pariatur + aliquid commodi atque sunt officiis natus? + + + + Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aperiam, officiis! Fugit minus ea, + perferendis eum consectetur quae vitae. Aliquid, quam reprehenderit? Maiores sed pariatur + aliquid commodi atque sunt officiis natus? + +; +``` + + + +#### Вертикальная ориентация + + + + + +```tsx +import {Flex, Label, Divider} from '@gravity-ui/uikit'; + + + + + + + + + + + +; +``` + + + +### Пользовательский контент + + + + + +```tsx +import {Divider, Flex, Container, Icon} from '@gravity-ui/uikit'; +import {CheckIcon} from '@gravity-ui/icons'; + + + + Custom content + + + + +; +``` + + + +### Выравнивание + + + + + +```tsx +import {Divider, Flex, Container} from '@gravity-ui/uikit'; + + + + Start content + Center content + End content + +; +``` + + + +### Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :---------- | :----------------------------------------------------- | :---------------------- | :-------------------- | +| className | HTML-атрибут `class`. | `string` | - | +| orientation | Определяет направление разделителя. | `horizontal - vertical` | `horizontal` | +| children | Пользовательский контент внутри разделителя. | `React.ReactNode` | | +| align | Расположение пользовательского контента. | `start - center - end` | `start` | +| style | HTML-атрибут `style`. | `React.CSSProperties` | | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | + +### API CSS + +| Имя | Описание | +| :------------------ | :---------------- | +| `--g-divider-color` | Цвет разделителя. | diff --git a/src/components/Divider/README.md b/src/components/Divider/README.md index dbb176dbd7..c0e763b55f 100644 --- a/src/components/Divider/README.md +++ b/src/components/Divider/README.md @@ -16,7 +16,7 @@ The `Divider` component is used as a thin line for delimiting and grouping eleme ### Orientation -To control the orientation of the `Divider`, use the `orientation` property. The default orientation is `horizontal`. +Use the `direction` property to manage the `Divider` orientation. The default orientation is `horizontal`. #### Horizontal @@ -222,14 +222,14 @@ import {Divider, Flex, Container} from '@gravity-ui/uikit'; ### Properties -| Name | Description | Type | Default | -| :---------- | :-------------------------------------- | :---------------------- | :----------- | -| className | HTML `class` attribute | `string` | - | -| orientation | Sets the direction of divider | `horizontal - vertical` | `horizontal` | -| children | Custom content inside divider | `React.ReactNode` | | -| align | Custom content position | `start - center - end` | `start` | -| style | HTML `style` attribute | `React.CSSProperties` | | -| qa | HTML `data-qa` attribute, used in tests | `string` | | +| Name | Description | Type | Default | +| :---------- | :----------------------------------------- | :---------------------- | :----------- | +| className | `class` HTML attribute | `string` | - | +| orientation | Determines the divider direction | `horizontal - vertical` | `horizontal` | +| children | Custom content inside the divider | `React.ReactNode` | | +| align | Custom content position | `start - center - end` | `start` | +| style | `style` HTML attribute | `React.CSSProperties` | | +| qa | `data-qa` HTML attribute, used for testing | `string` | | ### CSS API diff --git a/src/components/DropdownMenu/README-ru.md b/src/components/DropdownMenu/README-ru.md new file mode 100644 index 0000000000..0342f9c526 --- /dev/null +++ b/src/components/DropdownMenu/README-ru.md @@ -0,0 +1,556 @@ + + +# DropdownMenu + + + +```tsx +import {DropdownMenu} from '@gravity-ui/uikit'; +``` + +Компонент `DropdownMenu` (выпадающее меню) позволяет организовывать элементы в группы, создавать подменю и настраивать переключатель. Элементы выпадающего меню настраиваются через свойство `items`. По умолчанию переключатель меню — кнопка с иконкой многоточия (**⋯**), которую можно переопределить с помощью свойства `renderSwitcher`. + + + + + +```jsx + console.log('Rename'), + text: 'Rename', + }, + { + action: () => console.log('Delete'), + text: 'Delete', + theme: 'danger', + }, + ]} +/> +``` + + + +## Сгруппированные элементы + +Элементы компонента`DropdownMenu` можно группировать и визуально отделять от остальных с помощью массивов элементов меню, вложенных в массив `items`. + + + + + +```jsx + console.log('Call'), + text: 'Call', + }, + { + action: () => console.log('Send email'), + text: 'Send email', + }, + ], + { + action: () => console.log('Rename'), + text: 'Rename', + }, + { + action: () => console.log('Delete'), + text: 'Delete', + theme: 'danger', + }, + ]} +/> +``` + + + +## Подменю + +Используя свойство `items` для отдельного элемента меню, можно добавить вложенные подэлементы. + +Для элементов меню с подменю предусмотрены следующие дополнительные классы для стилизации: + +- `.g-dropdown-menu__menu-item_with-submenu`— для элементов меню с более чем одним вложенным подэлементом; +- `.g-dropdown-menu__menu-item_active-parent`— для элемента, подменю которого в данный момент открыто. + + + + + +```jsx + console.log('Rename'), + text: 'Rename', + }, + { + action: () => console.log('Delete'), + text: 'Delete', + theme: 'danger', + }, + { + text: 'More', + items: [ + { + action: () => console.log('Mark as'), + text: 'Mark as', + items: [ + { + action: () => console.log('Important'), + text: 'Important', + }, + { + action: () => console.log('Favorite'), + text: 'Favorite', + }, + ], + }, + { + action: () => console.log('Copy'), + text: 'Copy', + }, + { + text: 'Move to', + items: [ + { + action: () => console.log('Location #1'), + text: 'Location #1', + }, + { + action: () => console.log('Location #2'), + text: 'Location #2', + }, + ], + }, + ], + }, + ]} +/> +``` + + + +## Пользовательский переключатель меню + +Для настройки переключателя меню используйте свойство `renderSwitcher`. Это может быть любая функция, возвращающая React-компонент (или `(props: SwitcherProps) => React.ReactNode` в контексте TypeScript; см. [`SwitcherProps`](#switcherprops) ниже). По умолчанию переключатель меню — кнопка с иконкой многоточия (**⋯**). + + + + + +```jsx + ( +
+ John Doe +
+ )} + items={[ + { + action: () => console.log('Rename'), + text: 'Rename', + }, + { + action: () => console.log('Delete'), + text: 'Delete', + theme: 'danger', + }, + ]} +/> +``` + + + +Пример выше упрощен с целью показать принцип работы настраиваемого переключателя меню. В реальных приложениях желательно, чтобы кликабельный переключатель меню представлял собой компонент, доступный для управления с клавиатуры и через другие вспомогательные технологии, такие как кнопка. + +## Пользовательские иконки + +Для добавления пользовательских иконок к элементам `DropdownMenu` используйте свойства `iconStart` и `iconEnd`. По умолчанию в элементах `DropdownMenu` иконки отсутствуют. + +Чтобы изменить иконку переключателя меню, используйте свойства `renderSwitcher` компонента`DropdownMenu` По умолчанию переключатель меню — кнопка с иконкой многоточия (**⋯**). + + + + + +```jsx + ( + + )} + items={[ + { + iconStart: , + action: () => console.log('Rename'), + text: 'Rename', + }, + { + iconStart: , + action: () => console.log('Delete'), + text: 'Delete', + theme: 'danger', + }, + ]} +/> +``` + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :------------------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------------: | :-------------------: | +| `items` | Массив элементов. Вложенные массивы элементов представляют визуально разделенные группы. | `(DropdownMenuItem \| DropdownMenuItem[])[] \| []` | | +| `data` | Данные, которые передаются в действия, вызываемые из меню (это может быть полезно для контекстных меню). | `any` | | +| `icon` | Иконка дефолтного переключателя (`switcher`). | `React.ReactNode` | Иконка многоточия. | +| `size` | Применяется как к дефолтному `switcher`, так и к меню. | `'s' \| 'm' \| 'l' \| 'xl'` | `'m'` | +| `disabled` | Значение `true` для этого свойства отключает кнопку `switcher` и блокирует открытие меню. | `boolean` | | +| `renderSwitcher` | Функция рендеринга для контрола переключения меню. | `React.ReactNode` | | +| `switcherWrapperClassName` | Значение для свойства `className` родительского компонента `switcher`. | `string` | | +| `defaultSwitcherProps` | Свойства дефолтного `switcher`. | `ButtonProps` | | +| `defaultSwitcherClassName` | Значение для свойства `className` дефолтного `switcher`. | `string` | | +| `menuProps` | Переопределяет свойства выпадающего меню по умолчанию. | `MenuProps` | | +| `popupProps` | Переопределяет свойства всплывающего окна по умолчанию. | `PopupProps` | | +| `open` | Переключает видимость выпадающего меню. | `boolean` | | +| `onOpenToggle` | Вызывается при открытии или закрытии меню. | `() => void` | | +| `onSwitcherClick` | Вызывается при клике по переключателю. | `React.MouseEventHandler` | | +| `hideOnScroll` | Указывает, нужно ли скрывать меню при прокрутке родительского элемента. | `boolean` | `true` | +| `children` | Пользовательский контент внутри всплывающего окна с меню. | `React.ReactNode` | | + +### DropdownMenuItem + +Используется для описания отдельных элементов выпадающего меню. + +| Имя | Описание | Тип | Значение по умолчанию | +| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------: | :-------------------: | +| `text` | Текстовое содержимое элемента меню. | `React.ReactNode` | | +| `action` | Обработчик клика по элементу меню. Получает параметры от родительского выпадающего меню (`event` и `data`). | `(event: React.MouseEvent, data: any) => void` | | +| `iconStart` | Иконка, отображаемая перед содержимым элемента меню. | `React.ReactNode` | | +| `iconEnd` | Иконка, отображаемая после содержимого элемента меню. Игнорируется, если у элемента есть подменю. | `React.ReactNode` | | +| `hidden` | Определяет, скрыт ли элемент меню. | `boolean` | | +| `disabled` | Определяет, заблокирован ли элемент меню. | `boolean` | | +| `href` | Элемент меню с этим свойством становится ссылкой на указанное местоположение. | `string` | | +| `target` | То же, что и атрибут `target` у тега ``. | `string` | | +| `rel` | То же, что и атрибут `rel` у тега ``. | `string` | | +| `extraProps` | Дополнительные свойства для элемента меню. | `object` | | +| `title` | Текст всплывающей подсказки. | `string` | | +| `className` | Значение HTML-атрибута `class`. | `string` | | +| `items` | Элементы подменю. | `(DropdownMenuItem \| DropdownMenuItem[])[]` | | +| `popupProps` | Свойства всплывающего окна подменю. | `string` | | +| `path` | Путь индексов от корня до текущего элемента. | `number[]` | | +| `closeMenu` | Пользовательская функция для закрытия меню (`closeMenu`). Ее можно вызвать вместо закрытия основного меню. Позволяет сначала закрыть подменю, а затем основное меню. | `() => void` | | + +### SwitcherProps + +| Имя | Описание | Тип | +| :---------- | :------------------------------------------------------------------------- | :----------: | +| `onClick` | Вызывается при клике по переключателю. | `() => void` | +| `onKeyDown` | Вызывается при получении переключателем фокуса и нажатии клавиши действия. | `() => void` | diff --git a/src/components/DropdownMenu/README.md b/src/components/DropdownMenu/README.md index 9c178322a1..55167a1418 100644 --- a/src/components/DropdownMenu/README.md +++ b/src/components/DropdownMenu/README.md @@ -8,7 +8,7 @@ import {DropdownMenu} from '@gravity-ui/uikit'; ``` -This is a dropdown menu component with item grouping, submenus, and a customizable toggle. The dropdown menu items are configured with the `items` prop. By default, the menu toggle is a button with the ellipsis icon (**⋯**), which can be overridden with the `renderSwitcher` prop. +The dropdown menu component provides item grouping, submenus, and a customizable toggle. The dropdown menu items are configured with the `items` property. By default, the menu toggle is a button with the ellipsis icon (**⋯**), which can be overridden with the `renderSwitcher` property. ## Submenus -The `items` property on an individual menu item adds nested subitems to this menu item. +The `items` property on an individual menu item adds nested sub-items to such item. -Menu items with submenus obtain the following additional class names to allow for extra styling: +Menu items with submenus get the following additional class names to allow for extra styling: -- the class name `.g-dropdown-menu__menu-item_with-submenu` is added to items with more than 1 nested item; -- the class name `.g-dropdown-menu__menu-item_active-parent` is added to an item whose submenu is currently open. +- `.g-dropdown-menu__menu-item_with-submenu`: For items with more than one nested item. +- `.g-dropdown-menu__menu-item_active-parent`: For the item whose submenu is currently open. ## Custom menu toggle -The menu toggle is configured with the `renderSwitcher` prop. It can be any function that returns a React component (or any `(props: SwitcherProps) => React.ReactNode` in the TypeScript terms, see [`SwitcherProps`](#switcherprops) below). By default, the menu toggle is a button with the ellipsis icon (**⋯**). +To configure the menu toggle, use the `renderSwitcher` property. It can be any function that returns a React component (or any `(props: SwitcherProps) => React.ReactNode` in the TypeScript terms, see [`SwitcherProps`](#switcherprops) below). By default, the menu toggle is a button with the ellipsis icon (**⋯**). -The example above is oversimplified to demonstrate the idea of the customizable menu toggle. In a real-life application, it is generally recommended that the clickable menu toggle should be a component accessible with a keyboard and other assistive technologies (such as a button). +The example above is oversimplified to demonstrate the idea of the customizable menu toggle. In a real-life application, it is generally recommended that the clickable menu toggle should be a component accessible with a keyboard and other assistive technologies such as a button. ## Custom icons -Custom icons can be added to a `DropdownMenu` item by assigning the `iconStart` or `iconEnd` property. By default, `DropdownMenu` items go without icons. +You can add custom icons to a `DropdownMenu` item using the `iconStart` or `iconEnd` property. By default, the `DropdownMenu` items go without icons. -The menu toggle icon can be changed with the `DropdownMenu`'s `renderSwitcher` prop. By default, the menu toggle is a button with the ellipsis icon (**⋯**). +You can change the menu toggle icon with the `DropdownMenu`'s `renderSwitcher` properties. By default, the menu toggle is a button with the ellipsis icon (**⋯**). ## Properties -| Name | Description | Type | Default | -| :------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------: | :-----------: | -| `items` | Array of items. Nested arrays of items represent visually separated groups. | `(DropdownMenuItem \| DropdownMenuItem[])[] \| []` | | -| `data` | A payload passed to the actions called from the menu. (Can be useful for context menus.) | `any` | | -| `icon` | Icon of the default `switcher`. | `React.ReactNode` | Ellipsis icon | -| `size` | Applied both to the default `switcher` and the menu. | `'s' \| 'm' \| 'l' \| 'xl'` | `'m'` | -| `disabled` | Setting this prop to `true` disables the `switcher` button and prevents the menu from opening. | `boolean` | | -| `renderSwitcher` | Render function for the menu toggle control. | `React.ReactNode` | | -| `switcherWrapperClassName` | Value for the `className` prop of the `switcher`'s parent component. | `string` | | -| `defaultSwitcherProps` | Default `switcher` props. | `ButtonProps` | | -| `defaultSwitcherClassName` | Value for the `className` prop of the default `switcher`. | `string` | | -| `menuProps` | Overrides the default dropdown menu popup props. | `MenuProps` | | -| `popupProps` | Overrides the default popup props. | `PopupProps` | | -| `open` | Controls dropdown menu visibility. | `boolean` | | -| `onOpenToggle` | Called when the menu is opened or closed. | `() => void` | | -| `onSwitcherClick` | Called when `switcher` is clicked. | `React.MouseEventHandler` | | -| `hideOnScroll` | Specifies whether to hide the menu when a parent element is scrolled. | `boolean` | `true` | -| `children` | Custom content inside the menu popup. | `React.ReactNode` | | +| Name | Description | Type | Default | +| :------------------------- | :------------------------------------------------------------------------------------------------- | :------------------------------------------------: | :-----------: | +| `items` | Array of items. Nested arrays of items represent visually separated groups. | `(DropdownMenuItem \| DropdownMenuItem[])[] \| []` | | +| `data` | A payload provided to the actions called from the menu. (This can be useful for context menus.) | `any` | | +| `icon` | Icon of the default `switcher`. | `React.ReactNode` | Ellipsis icon | +| `size` | Applied both to the default `switcher` and the menu. | `'s' \| 'm' \| 'l' \| 'xl'` | `'m'` | +| `disabled` | Setting this property to `true` disables the `switcher` button and prevents the menu from opening. | `boolean` | | +| `renderSwitcher` | Render function for the menu toggle control. | `React.ReactNode` | | +| `switcherWrapperClassName` | Value for the `className` property of the `switcher`'s parent component. | `string` | | +| `defaultSwitcherProps` | Default `switcher` properties. | `ButtonProps` | | +| `defaultSwitcherClassName` | Value for the `className` property of the default `switcher`. | `string` | | +| `menuProps` | Overrides the default dropdown menu popup properties. | `MenuProps` | | +| `popupProps` | Overrides the default popup properties. | `PopupProps` | | +| `open` | Toggles dropdown menu visibility. | `boolean` | | +| `onOpenToggle` | Called when the menu is opened or closed. | `() => void` | | +| `onSwitcherClick` | Called when `switcher` is clicked. | `React.MouseEventHandler` | | +| `hideOnScroll` | Specifies whether to hide the menu when a parent element is scrolled. | `boolean` | `true` | +| `children` | Custom content inside the menu popup. | `React.ReactNode` | | ### DropdownMenuItem @@ -532,20 +532,20 @@ This type describes individual dropdown menu items. | Name | Description | Type | Default | | :----------- | :------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------: | :-----: | | `text` | Menu item content. | `React.ReactNode` | | -| `action` | Menu item click handler. Recieves the parameters from the parent dropdown menu component (both `event` and `data`). | `(event: React.MouseEvent, data: any) => void` | | +| `action` | Menu item click handler. It gets the parameters from the parent dropdown menu component (both `event` and `data`). | `(event: React.MouseEvent, data: any) => void` | | | `iconStart` | Menu item icon before the item content. | `React.ReactNode` | | | `iconEnd` | Menu item icon after the item content. Ignored if the item has a submenu. | `React.ReactNode` | | | `hidden` | Determines whether the item is hidden. | `boolean` | | | `disabled` | Determines whether the item is disabled. | `boolean` | | -| `href` | Menu item with this prop becomes a link to the specified location. | `string` | | +| `href` | Menu item with this property becomes a link to the specified location. | `string` | | | `target` | Same as the `target` attribute of the `` tag. | `string` | | | `rel` | Same as the `rel` attribute of the `` tag. | `string` | | -| `extraProps` | Additional menu item props. | `object` | | +| `extraProps` | Additional menu item properties. | `object` | | | `title` | Tooltip text. | `string` | | -| `className` | HTML `class` attribute value. | `string` | | +| `className` | `class` HTML attribute value. | `string` | | | `items` | Submenu items. | `(DropdownMenuItem \| DropdownMenuItem[])[]` | | -| `popupProps` | Submenu popup props. | `string` | | -| `path` | Path of indexes from the root to the current item. | `number[]` | | +| `popupProps` | Submenu popup properties. | `string` | | +| `path` | Path of the indexes from the root to the current item. | `number[]` | | | `closeMenu` | Custom `closeMenu` callback. It can be called instead of closing the main menu and used to close submenus before the main menu. | `() => void` | | ### SwitcherProps diff --git a/src/components/Hotkey/README-ru.md b/src/components/Hotkey/README-ru.md new file mode 100644 index 0000000000..be1c8c4ef5 --- /dev/null +++ b/src/components/Hotkey/README-ru.md @@ -0,0 +1,88 @@ + + +# Hotkey + + + +```tsx +import {Hotkey} from '@gravity-ui/uikit'; +``` + +Компонент `Hotkey` (горячая клавиша) позволяет отображать сочетания клавиш как для Mac, так и для PC. + +### Значение + +Сочетания клавиш задаются в формате `+`, т. е. несколько клавиш, разделенных знаком плюса, например, `shift+tab`. + +Последовательности сочетаний клавиш могут быть разделены пробелом: ` `, например, `ctrl+a ctrl+c ctrl+v`. + +В качестве заменителя `cmd` на Mac и `ctrl` на других платформах можно использовать `mod`. Например, `mod+v` отображается как ⌘+A на Mac и как Ctrl+A на PC. + +### `View` (вид) + +`light` — используется для отображения на светлом фоне (по умолчанию). + +`dark` — используется для отображения на темном фоне. + + + + + +``` + + +``` + + + +### `Platform` (платформа) + +`pc` — используется для отображения горячих клавиш для клавиатуры стандартного PC. + +`mac` — используется для отображения горячих клавиш для клавиатуры Macintosh. + +По умолчанию система автоматически определяет платформу. + + + + + +``` + + + +``` + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------- | :---------------------------------------------------------------------- | :-------------------: | :-------------------------: | +| view | Задает цветовую схему. | `"light"` `"dark"` | `"light"` | +| platform | Определяет платформу (PC или Macintosh) для отображения горячих клавиш. | `"pc"` `"mac"` | Определяется автоматически. | +| title | Значение горячих клавиш. | `string` | | +| style | HTML-атрибут `style`. | `React.CSSProperties` | | +| className | Имя класса алерта. | `string` | | diff --git a/src/components/Hotkey/README.md b/src/components/Hotkey/README.md index 9c662a7b02..03cae9d7b9 100644 --- a/src/components/Hotkey/README.md +++ b/src/components/Hotkey/README.md @@ -8,21 +8,21 @@ import {Hotkey} from '@gravity-ui/uikit'; ``` -`Hotkey` component can be used for display keyboard shortcuts for different platforms: Mac or PC. +You can use the `Hotkey` component to display keyboard shortcuts for both Mac and PC. ### Value -Keyboard shortcuts are set in the format `+` – specify a set of keys separated by a plus. Example: `shift+tab`. +Keyboard shortcuts are set in the `+` format, which means you need to specify multiple keys separated by a plus sign, e.g., `shift+tab`. -The sequence of key combinations can be separated by a space: ` `. Example: `ctrl+a ctrl+c ctrl+v`. +The sequence of key combinations can be separated by a space: ` `, e.g., `ctrl+a ctrl+c ctrl+v`. -You can use `mod` as a shorthand for `cmd` on Mac and `ctrl` on other platforms. Example: `mod+v` is rendered as ⌘+A for Mac, and as Ctrl+A for PC. +You can use `mod` as a shorthand for `cmd` on Mac and `ctrl` for other platforms. For example, `mod+v` is rendered as ⌘+A for Mac and Ctrl+A for PC. ### View -`light` - used if the component is drawn on a light background (used by default). +`light`: Used if the component is displayed on a light background (used by default). -`dark` - used if the component is drawn on a dark background. +`dark`: Used if the component is displayed on a dark background. ### Platform -`pc` - used to display keyboard shortcuts for a regular PC keyboard. +`pc`: Used to display keyboard shortcuts for a regular PC keyboard. -`mac` - used to display keyboard shortcuts for a Macintosh keyboard. +`mac`: Used to display keyboard shortcuts for a Macintosh keyboard. By default, the platform is detected automatically. @@ -83,6 +83,6 @@ LANDING_BLOCK--> | :-------- | :----------------------------------------------------------------------------- | :-------------------: | :--------------------: | | view | Used to set the color scheme | `"light"` `"dark"` | `"light"` | | platform | Used to select the platform (PC or Macintosh) to display the keyboard shortcut | `"pc"` `"mac"` | Detected automatically | -| title | The value of the keyboard shortcut | `string` | | +| title | Keyboard shortcut value | `string` | | | style | HTML style attribute | `React.CSSProperties` | | -| className | The alert class name | `string` | | +| className | Alert class name | `string` | | diff --git a/src/components/Hotkey/__stories__/README.md b/src/components/Hotkey/__stories__/README.md new file mode 100644 index 0000000000..03cae9d7b9 --- /dev/null +++ b/src/components/Hotkey/__stories__/README.md @@ -0,0 +1,88 @@ + + +# Hotkey + + + +```tsx +import {Hotkey} from '@gravity-ui/uikit'; +``` + +You can use the `Hotkey` component to display keyboard shortcuts for both Mac and PC. + +### Value + +Keyboard shortcuts are set in the `+` format, which means you need to specify multiple keys separated by a plus sign, e.g., `shift+tab`. + +The sequence of key combinations can be separated by a space: ` `, e.g., `ctrl+a ctrl+c ctrl+v`. + +You can use `mod` as a shorthand for `cmd` on Mac and `ctrl` for other platforms. For example, `mod+v` is rendered as ⌘+A for Mac and Ctrl+A for PC. + +### View + +`light`: Used if the component is displayed on a light background (used by default). + +`dark`: Used if the component is displayed on a dark background. + + + + + +``` + + +``` + + + +### Platform + +`pc`: Used to display keyboard shortcuts for a regular PC keyboard. + +`mac`: Used to display keyboard shortcuts for a Macintosh keyboard. + +By default, the platform is detected automatically. + + + + + +``` + + + +``` + + + +## Properties + +| Name | Description | Type | Default | +| :-------- | :----------------------------------------------------------------------------- | :-------------------: | :--------------------: | +| view | Used to set the color scheme | `"light"` `"dark"` | `"light"` | +| platform | Used to select the platform (PC or Macintosh) to display the keyboard shortcut | `"pc"` `"mac"` | Detected automatically | +| title | Keyboard shortcut value | `string` | | +| style | HTML style attribute | `React.CSSProperties` | | +| className | Alert class name | `string` | | diff --git a/src/components/Icon/README-ru.md b/src/components/Icon/README-ru.md new file mode 100644 index 0000000000..a582ce86f2 --- /dev/null +++ b/src/components/Icon/README-ru.md @@ -0,0 +1,62 @@ + + +# Icon + + + +```tsx +import {Icon} from '@gravity-ui/uikit'; +``` + +Компонент `Icon` (иконка) представляет собой обертку для SVG-иконок. SVG-файлы можно загружать разными способами — например, через компоненты React или с использованием различных загрузчиков Webpack: [`SVGR`](https://react-svgr.com/docs/webpack/), [`svg-react-loader`](https://github.com/jhamlet/svg-react-loader), [`svg-inline-loader`](https://github.com/webpack-contrib/svg-inline-loader) или [`svg-sprite-loader`](https://github.com/JetBrains/svg-sprite-loader). +Компонент `Icon` действует как прокси для доступа к иконкам в базе кода. + +### Компонент React + +```tsx +// CheckIcon.jsx +export function CheckIcon() { + return ( + + + + ); +} + +// --- +import {CheckIcon} from './CheckIcon'; + +; +``` + +### Загрузчик Webpack + +```tsx +// webpack.config.js +{ + test: /\.svg$/, + use: [''], +} + +// check.svg + + + + +// --- +import CheckIcon from './check.svg'; + +; +``` + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------- | :--------------------------------------------- | :---------------: | :-------------------: | +| data | Источник SVG-иконки. | `IconData` | | +| width | Атрибут `width` для SVG. | `number` `string` | | +| height | Атрибут `height` для SVG. | `number` `string` | | +| size | Атрибуты `width` и `height` для SVG. | `number` `string` | | +| fill | Атрибут `fill` для SVG. | `string` | `"currentColor"` | +| stroke | Атрибут `stroke` для SVG. | `string` | `"none"` | +| className | Пользовательский CSS-класс корневого элемента. | `string` | | diff --git a/src/components/Icon/README.md b/src/components/Icon/README.md index 0e636703aa..2a624b91eb 100644 --- a/src/components/Icon/README.md +++ b/src/components/Icon/README.md @@ -8,9 +8,7 @@ import {Icon} from '@gravity-ui/uikit'; ``` -The `Icon` component is a wrapper for SVG icon. SVGs can be loaded in different ways, -such as though a React component or various Webpack -loaders: [`SVGR`](https://react-svgr.com/docs/webpack/), [`svg-react-loader`](https://github.com/jhamlet/svg-react-loader), [`svg-inline-loader`](https://github.com/webpack-contrib/svg-inline-loader), or [`svg-sprite-loader`](https://github.com/JetBrains/svg-sprite-loader). +The `Icon` component is a wrapper for SVG icon. SVGs can be loaded in different ways, such as though a React component or various Webpack loaders: [`SVGR`](https://react-svgr.com/docs/webpack/), [`svg-react-loader`](https://github.com/jhamlet/svg-react-loader), [`svg-inline-loader`](https://github.com/webpack-contrib/svg-inline-loader), or [`svg-sprite-loader`](https://github.com/JetBrains/svg-sprite-loader). The `Icon` component serves as a proxy to use through the codebase. ### React component @@ -53,12 +51,12 @@ import CheckIcon from './check.svg'; ## Properties -| Name | Description | Type | Default | -| :-------- | :-------------------------------------- | :---------------: | :--------------: | -| data | Source of SVG icon | `IconData` | | -| width | `width` SVG attribute | `number` `string` | | -| height | `height` SVG attribute | `number` `string` | | -| size | Both `width` and `height` SVG attribute | `number` `string` | | -| fill | `fill` SVG attribute | `string` | `"currentColor"` | -| stroke | `stroke` SVG attribute | `string` | `"none"` | -| className | Custom CSS class for the root element | `string` | | +| Name | Description | Type | Default | +| :-------- | :--------------------------------------- | :---------------: | :--------------: | +| data | Source of SVG icon | `IconData` | | +| width | `width` SVG attribute | `number` `string` | | +| height | `height` SVG attribute | `number` `string` | | +| size | Both `width` and `height` SVG attributes | `number` `string` | | +| fill | `fill` SVG attribute | `string` | `"currentColor"` | +| stroke | `stroke` SVG attribute | `string` | `"none"` | +| className | Custom CSS class for the root element | `string` | | diff --git a/src/components/Label/README-ru.md b/src/components/Label/README-ru.md new file mode 100644 index 0000000000..8f41a59895 --- /dev/null +++ b/src/components/Label/README-ru.md @@ -0,0 +1,272 @@ + + +# Label + + + +```tsx +import {Label} from '@gravity-ui/uikit'; +``` + +`Label` (лейбл) можно использовать для выделения определенной информации. `Label` с кнопкой `Close` или `Copy` может быть полезен для выполнения различных простых действий. + +Лейблы больше всего подходят для отображения однострочной текстовой информации с различными цветовыми кодами, показывающими ее важность. + +## Внешний вид + +`Label` можно отображать в различных стилях. + +### `Theme` (тема) + +Свойство `theme` позволяет применять различные темы в зависимости от статуса. Возможные значения: `normal`, `info`, `success`, `warning`, `danger`, `utility`, `unknown` и `clear`. +Тема по умолчанию — `normal`. + + + + + +```tsx + + + + + + + + +``` + + + +### `Type` (тип) + +Свойство `type` добавляет различные опции к `Label`: + +`copy` — добавляет кнопку копирования, при нажатии на которую копируется значение, указанное в свойстве `copyText`; + +`close` — добавляет кнопку закрытия для управления списком лейблов. + + + + + +```tsx + + + +``` + + + +### Иконка + +Иконку можно добавить с помощью свойства `icon`. Для этого используйте компонент [`Icon`](../Icon), который представляет собой обертку для SVG-файлов. + + + + + +```tsx + + + +``` + + + +## Значение + +`Label` можно применять для отображения информации в формате `ключ-значение`. Для этого необходимо передать ключ в свойство `children`, а значение — в свойство `value`. + + + + + +```tsx + + + + + + + + +``` + + + +## Состояние + +`Label` может иметь разные состояния: + +- `disabled` — взаимодействие с лейблом запрещено. +- `interactive` — лейбл становится интерактивным по ховеру. + + + + + +```tsx + + + +``` + + + +## Размер + + + + + +```tsx + + + +``` + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :--------------- | :----------------------------------------------------- | :----------------------------: | :-------------------: | +| children | Содержимое. | `React.ReactNode` | | +| className | HTML-атрибут `class`. | `string` | | +| closeButtonLabel | `aria-label` кнопки закрытия. | `string` | | +| copyButtonLabel | `aria-label` кнопки копирования. | `string` | | +| copyText | Копируемый текст. | `string` | | +| disabled | Отключенное состояние. | `boolean` | | +| icon | Иконка лейбла (слева). | `React.ReactNode` | | +| interactive | Включение эффекта ховера. | `boolean` | | +| onClick | Обработчик события `click`. | `Function` | | +| onCloseClick | Обработчик события `click` по кнопке закрытия. | `Function` | | +| onCopy | Обработчик события `copy`. | `Function` | | +| size | Размер лейбла. | `"xs"` `"s"` `"m"` | `"s"` | +| theme | Тема лейбла. | `string` | `"normal"` | +| type | Тип лейбла. | `"default"` `"copy"` `"close"` | `"default"` | +| value | Значение лейбла (в виде `"children : value"`). | `string` | | +| title | HTML-атрибут `title`. | `string` | | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | diff --git a/src/components/Label/README.md b/src/components/Label/README.md index f1d68832c7..d39d5973cc 100644 --- a/src/components/Label/README.md +++ b/src/components/Label/README.md @@ -8,17 +8,17 @@ import {Label} from '@gravity-ui/uikit'; ``` -`Label` can be used for displaying certain marking information. `Label` with the close or copy button may be useful for various simple actions. +You can use `Label`s for highlighting certain information. A `Label` with the `Close` or `Copy` button may be useful for various simple actions. -`Label` is most suitable for displaying one-line text information with different color codes indicating its importance. +`Label`s are most suitable for displaying one-line text information with different color codes that show its importance. ## Appearance -`Label` can be displayed in multiple styles. +A `Label` can be displayed in multiple styles. ### Theme -Apply different themes for various statuses with the `theme` property. You can use the following values: `normal`, `info`, `success`, `warning`, `danger`, `utility`, `unknown`, and `clear`. +Use the `theme` property to apply different themes for various statuses. You can use the following values: `normal`, `info`, `success`, `warning`, `danger`, `utility`, `unknown`, and `clear`. The default theme is `normal`. ### Type -Adds various options to the `Label` using the `type` property. +The `type` property adds various options to a `Label`: `copy`: Adds a copy button; when clicked, it copies the value of the `copyText` property. @@ -97,7 +97,7 @@ LANDING_BLOCK--> ### Icon -You can add an icon with the `icon` property. To do so, use the [`Icon`](../Icon) component, a special wrapper for SVGs. +You can add an icon with the `icon` property. To do so, use the [`Icon`](../Icon) component, which is a special wrapper for SVGs. ## Value -`Label` can be used for displaying key-value information. Pass key to the `children` and value to the `value` property. +You can use `Label`s for displaying key-value information. For that, you need to provide the key to the `children` poperty, and value, to `value`: ## Properties -| Name | Description | Type | Default | -| :--------------- | :-------------------------------------------- | :----------------------------: | :---------: | -| children | Content | `React.ReactNode` | | -| className | HTML `class` attribute | `string` | | -| closeButtonLabel | `aria-label` of the close button | `string` | | -| copyButtonLabel | `aria-label` of the copy button | `string` | | -| copyText | Text to copy | `string` | | -| disabled | Disabled state | `boolean` | | -| icon | Label icon (on the left) | `React.ReactNode` | | -| interactive | Enable hover effect | `boolean` | | -| onClick | `click` event handler | `Function` | | -| onCloseClick | Close button `click` event handler | `Function` | | -| onCopy | `copy` event handler | `Function` | | -| size | Label size | `"xs"` `"s"` `"m"` | `"s"` | -| theme | Label theme | `string` | `"normal"` | -| type | Label type | `"default"` `"copy"` `"close"` | `"default"` | -| value | Label value (displayed as "children : value") | `string` | | -| title | HTML `title` attribute | `string` | | -| qa | HTML `data-qa` attribute, used in tests | `string` | | +| Name | Description | Type | Default | +| :--------------- | :---------------------------------------------- | :----------------------------: | :---------: | +| children | Content | `React.ReactNode` | | +| className | `class` HTML attribute | `string` | | +| closeButtonLabel | `aria-label` of the close button | `string` | | +| copyButtonLabel | `aria-label` of the copy button | `string` | | +| copyText | Text to copy | `string` | | +| disabled | Disabled state | `boolean` | | +| icon | Label icon (on the left) | `React.ReactNode` | | +| interactive | Enables hover effect | `boolean` | | +| onClick | `click` event handler | `Function` | | +| onCloseClick | Close button `click` event handler | `Function` | | +| onCopy | `copy` event handler | `Function` | | +| size | Label size | `"xs"` `"s"` `"m"` | `"s"` | +| theme | Label theme | `string` | `"normal"` | +| type | Label type | `"default"` `"copy"` `"close"` | `"default"` | +| value | Label value (displayed as `"children : value"`) | `string` | | +| title | `title` HTML attribute | `string` | | +| qa | `data-qa` HTML attribute, used for testing | `string` | | diff --git a/src/components/Link/README-ru.md b/src/components/Link/README-ru.md new file mode 100644 index 0000000000..2aa6798297 --- /dev/null +++ b/src/components/Link/README-ru.md @@ -0,0 +1,187 @@ + + +# Link + + + +```tsx +import {Link} from '@gravity-ui/uikit'; +``` + +`Link` (ссылка) — это часть текста, при нажатии на которую пользователь переходит на другую часть текущей страницы, на другую страницу в рамках сервиса или на страницу внешнего сайта. + +Главное отличие `Link` от [Button](../Button) заключается в функции навигации. Чаще всего `Link` ведет на другую страницу или открывает новую вкладку браузера. + +## Внешний вид + +Существует три типа ссылок: `normal` (стандартный коричневый), `primary` (черный) и `secondary` (серый). Внешний вид ссылки можно изменять с помощью свойства `view`. Также можно включить отображение того, что на ссылку уже нажимали, используя свойство `visitable`. + +### Тип `normal` + +Это наиболее привычный и общепринятый шаблон компонента `link`. Применяется для визуального выделения элемента внутри текста или таблицы, а также для навигации. Можно использовать его для перехода как на внутренние страницы, так и на внешние источники, включая документацию. Кроме того, этот тип используется для страниц с ошибками и нулевых состояний. + + + + + +```tsx + + Link + +``` + + + +### Тип `primary` + +Этот тип используется, когда очевидно, что элемент является кликабельным, но использование коричневого компонента `Link` будет перегружать интерфейс и мешать выделению ключевых моментов на странице. + + + + + +```tsx + + Link + +``` + + + +### Тип `secondary` + +Как и `primary`, этот тип `Link` используется, когда пользователю очевидно, что элемент кликабелен, но навигация по нему не является обязательной и затрагивает лишь небольшое количество сценариев. Его основная цель — не отвлекать пользователя от ключевых моментов на странице. Тип `secondary` чаще всего используется в хлебных крошках или при отображении вторичных атрибутов. + + + + + +```tsx + + Link + +``` + + + +### `Visitable` + +Это свойство используется, чтобы показать, что на `Link` уже нажимали. + + + + + +```tsx + + Link + +``` + + + +## `href` + +Свойство `href` является обязательным. + + + + + +```tsx +Link with href +``` + + + +## Использование + +`Link` можно использовать и как независимый текстовый элемент, и как часть текста. + + + + + +```tsx + + What roles are available in the service + + + Currently, this role can only be assigned to a folder or cloud + +``` + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :--------- | :----------------------------------------------------- | :-------------------------------------------------------: | :-------------------: | +| view | Внешний вид ссылки. | `"normal" \| "primary" \| "secondary"` | `"normal"` | +| visitable | Отображает CSS-состояние `:visitable`. | `boolean \| undefined` | +| href | HTML-атрибут `href`. | `string` | +| target | HTML-атрибут `target`. | `string \| undefined` | +| rel | HTML-атрибут `rel`. | `string \| undefined` | +| title | HTML-атрибут `title`. | `string \| undefined` | +| children | Содержимое ссылки. | `React.ReactNode` | +| extraProps | Дополнительные свойства. | `Record \| undefined` | +| onClick | Обработчик события `click`. | `React.MouseEventHandler \| undefined` | +| onFocus | Обработчик события `focus`. | `React.FocusEventHandler \| undefined` | +| onBlur | Обработчик события `blur`. | `React.FocusEventHandler \| undefined` | +| id | HTML-атрибут `id`. | `string \| undefined` | +| style | HTML-атрибут `style`. | `React.CSSProperties \| undefined` | +| className | HTML-атрибут `class`. | `string \| undefined` | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string \| undefined` | +| ref | React-ссылка на DOM-узел `Link`. | `React.ForwardedRef \| undefined` | diff --git a/src/components/Link/README.md b/src/components/Link/README.md index ea9f8017d2..ab6ded8e26 100644 --- a/src/components/Link/README.md +++ b/src/components/Link/README.md @@ -8,17 +8,17 @@ import {Link} from '@gravity-ui/uikit'; ``` -`Link` is a part of text that, when clicked, takes the user to another part of the page, another page inside the service, or an external website page. +`Link` is a part of text that, when clicked, takes the user to another part of the page, another page within the service, or an external website page. -The main difference from [Button](../Button) is the navigation function. Most often, a `Link` leads to other pages or opens new browser tabs. +Its main difference from [Button](../Button) is the navigation function. Most often, a `Link` leads to another page or opens a new browser tab. ## Appearance -There are three types available: `normal`(the usual brown), `primary`(black), and `secondary`(gray). You can manage it though the `view` property. You can also display whether the link has been clicked using the `visitable` property. +There are three types of links available: `normal` (the usual brown), `primary` (black), and `secondary` (gray). You can manage it with the `view` property. You can also enable displaying that the link has already been clicked using the `visitable` property. ### Normal -This is the most familiar and well-established 'link' pattern. It is used to visually highlight an element inside a text, table, and as part of navigation. You can use it to navigate both internal pages and external sources, including documentation. Additionally, this type is used for error pages and zero states. +This is the most familiar and well-established `link` pattern. It is used to visually highlight an element inside a text or table, and as part of navigation. You can use it to navigate to both internal pages and external sources, including documentation. Additionally, this type is used for error pages and zero states. ### Secondary -Just like primary `Link`, this type is used when it is natively clear to the user that an element is clickable, while navigating through it is not essential and affects a small number of scenarios. The main task is not to distract the user from the key points on the page. The 'Secondary' type is most often used in breadcrumbs or when displaying secondary attributes. +Just like primary `Link`, this type is used when it is natively clear to the user that an element is clickable, while navigating through it is not essential and affects a small number of scenarios. Its main goal is not to distract the user from the key points on the page. The `Secondary` type is most often used in breadcrumbs or when displaying secondary attributes. -## Href +## `href` The `href` property is required. @@ -131,7 +131,7 @@ LANDING_BLOCK--> ## Usage -A `Link` can be used both as an independent text element and as part of the text: +You can use a `Link` both as an independent text element and as part of the text: | Name | Description | Type | Default | | :--------- | :----------------------------------------- | :-------------------------------------------------------: | :--------: | | view | Link appearance | `"normal" \| "primary" \| "secondary"` | `"normal"` | -| visitable | Display `:visitable` CSS state | `boolean \| undefined` | -| href | HTML `href` attribute | `string` | -| target | HTML `target` attribute | `string \| undefined` | -| rel | HTML `rel` attribute | `string \| undefined` | -| title | HTML `title` attribute | `string \| undefined` | +| visitable | Displays the `:visitable` CSS state | `boolean \| undefined` | +| href | `href` HTML attribute | `string` | +| target | `target` HTML attribute | `string \| undefined` | +| rel | `rel` HTML attribute | `string \| undefined` | +| title | `title` HTML attribute | `string \| undefined` | | children | Link content | `React.ReactNode` | -| extraProps | Any additional props | `Record \| undefined` | +| extraProps | Additional properties | `Record \| undefined` | | onClick | `click` event handler | `React.MouseEventHandler \| undefined` | | onFocus | `focus` event handler | `React.FocusEventHandler \| undefined` | | onBlur | `blur` event handler | `React.FocusEventHandler \| undefined` | -| id | HTML `id` attribute | `string \| undefined` | -| style | HTML `style` attribute | `React.CSSProperties \| undefined` | -| className | HTML `class` attribute | `string \| undefined` | -| qa | HTML `data-qa` attribute, used for testing | `string \| undefined` | -| ref | React ref to Link DOM node | `React.ForwardedRef \| undefined` | +| id | `id` HTML attribute | `string \| undefined` | +| style | `style` HTML attribute | `React.CSSProperties \| undefined` | +| className | `class` HTML attribute | `string \| undefined` | +| qa | `data-qa` HTML attribute, used for testing | `string \| undefined` | +| ref | React ref to the `Link` DOM node | `React.ForwardedRef \| undefined` | diff --git a/src/components/List/README-ru.md b/src/components/List/README-ru.md new file mode 100644 index 0000000000..d0462da2b4 --- /dev/null +++ b/src/components/List/README-ru.md @@ -0,0 +1,256 @@ + + +# List + + + +```tsx +import {List} from '@gravity-ui/uikit'; +``` + +### ItemsHeight + +Определяет высоту списка элементов (или функцию, возвращающую значение высоты для списка). Данное свойство может быть полезным, когда высота списка задается динамически, например,`(items: []) => number`. + +### Items + +Передает массив элементов для списка: + + + + + +```tsx + +``` + + + +Элемент может быть представлен скалярным или произвольным значением (при этом он всегда должен быть `truthy`). +В случае произвольного значения обязательно указывайте функции фильтрации и рендеринга. +Рендеринг по умолчанию передает элемент только как текст. + +Специальное поле `item.disabled` делает элемент неактивным. + +Настройка рендеринга и высоты открывает множество возможностей для экспериментов. +Например, код ниже позволяет эмулировать группы: + + + + + +```tsx + console.log(value)} + renderItem={(item) => { + if (item.group) { + return ( +
+
{item.title}
+
+ ); + } + return ( +
+
{item.title}
+
+ ); + }} + itemHeight={(item) => (item.group ? 24 : 36)} + itemsHeight={160} + filterItem={(filter) => (item) => item.title.includes(filter)} +/> +``` + + + +### `Filterable` + +Свойство `filterable` отключает возможность ввода для поиска элемента, если его значение — `false`. Значение по умолчанию — `true`. + + + + + +```tsx + +``` + + + +### Sortable + +Свойство `sortable` позволяет менять местами элементы списка, если его значение — `true`. Значение по умолчанию — `false`. + + + + + +```tsx + +``` + + + +### Виртуализация + +Чтобы виртуализация работала, нужно выполнить одно из двух условий: + +1. Задать свойство `itemsHeight`. В этом случае высота списка будет фиксированной и равной указанному значению. +2. Задать родительскому контейнеру списка стиль `display: flex`. В этом случае список будет подстраиваться под ширину контейнера. + +### Внешнее управление + +Иногда может потребоваться управлять действиями элементов с клавиатуры, сохраняя фокус на внешнем элементе. +В этом случае можно использовать передачу события `onKeyDown` в список. +Аналогичным образом можно передать `onFocus` и `onBlur`, если нужно воспроизвести поведение при потере активного элемента. + +### `Filter` + +Свойство `filter` позволяет задать значение фильтра, используемое для внешней сортировки. + +### PropTypes + +| Имя | Описание | Тип | Значение по умолчанию | +| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------- | :-------------------- | +| [items](#items) | Список элементов | `Array` | [] | +| itemHeight | Высота элемента в `px` или функция, возвращающая значение высоты для элемента: `(item: any) => number`. | `Number/Function` | 28 | +| itemsHeight | Высота списка элементов или функция, возвращающая значение высоты для списка. Данное свойство может быть полезным, когда высота списка задается динамически: `(items: []) => number`. | `Number/Function` | | +| renderItem | Функция рендеринга, получающая на вход элемент и возвращающая узел React: `(item: any, isItemActive: bool, itemIndex: number) => React.ReactNode`. | `Function` | | +| filterItem | Функция фильтрации, которая принимает введенную строку в инпут поиска/фильтрации и возвращает функцию, принимающую на вход элемент и возвращающую булевое значение: `(filter: string) => (item: any) => boolean`. | `Function` | | +| filterable | Флаг, активирующий поле фильтра. | `Boolean` | true | +| filterPlaceholder | Заглушка для поля фильтра. | `String` | | +| filter | Значение фильтра (при использовании внешней сортировки). | `String` | | +| filterClassName | Класс для стилизации ввода фильтра. | `String` | | +| onChangeFilter | Обработчик изменения фильтра (при использовании внешней сортировки): `(filter: string) => void`. | `Function` | | +| onFilterEnd | Функция, вызываемая после завершения внутренней фильтрации: `({items}: {items: T[]}) => void`. | `Function` | | +| emptyPlaceholder | Заглушка для пустого списка. | `React.ReactNode` | | +| sortable | Флаг, включающий сортировку списка. | `Boolean` | | +| sortHandleAlign | Выравнивание индикатора сортировки (слева или справа). | `left` `right` | | +| onSortEnd | Обработчик события сортировки — `({oldIndex: number, newIndex: number}) => void`. | `Function` | | +| virtualized | Флаг, включающий виртуализацию. При выключенном флаге будут отрисованы все элементы сразу. | `Boolean` | true | +| onItemClick | Обработчик клика по элементу — `(item: any, index: number, fromKeyboard?: bool) => void`. | `Function` | | +| deactivateOnLeave | При выставленном флаге выбор элемента сбрасывается при уходе курсора с элемента или потере фокуса списком. При снятом — последний выбранный элемент будет оставаться выбранным. | `Boolean` | true | +| activeItemIndex | При заданном значении элемент с этим индексом рендерится как активный. | `Number` | | +| selectedItemIndex | При заданном значении элемент с этим индексом рендерится как выбранный (цвет фона из `--g-color-base-selection`). | `Number/Array` | | +| itemClassName | Пользовательское имя класса, которое будет добавлено в контейнер элемента. | `String` | | +| itemsClassName | Пользовательское имя класса, которое будет добавлено в список элементов. | `String` | | +| role | HTML-атрибут `role`. | `String` | list | +| id | HTML-атрибут `id`. | `string` | | +| onChangeActive | Вызывается при изменении индекса варианта в списке, который выделен клавиатурным фокусом: `(index?: number) => void`. | `Function` | | diff --git a/src/components/List/README.md b/src/components/List/README.md index 1a76395732..c4e4e56407 100644 --- a/src/components/List/README.md +++ b/src/components/List/README.md @@ -10,8 +10,7 @@ import {List} from '@gravity-ui/uikit'; ### ItemsHeight -Determines the item list height (or a function that returns the height value for a list). It can be helpful when setting the list -height dynamically, e.g., `(items: []) => number`. +Determines the item list height (or a function that returns the height value for a list). It can be helpful when setting the list height dynamically, e.g., `(items: []) => number`. ### Items @@ -35,12 +34,12 @@ LANDING_BLOCK--> An item can be a scalar or an arbitrary value and must be `truthy` in any case. -If it is an arbitrary value, make sure to specify filtering and rendering functions. +If it is an arbitrary value, make sure to specify the filtering and rendering functions. The default render only provides an item as text. The special `item.disabled` field disables an item. -Render and height customization provides plenty of room for experimenting. +The render and height customization provides plenty of room for experimenting. For example, the code below allows you to emulate groups: ### Filterable -`filterable`: Disables the input to search for an item if the value is `false`. The default value is `true`. +The `filterable` property disables the input to search for an item if its value is `false`. Its default value is `true`. ### Sortable -`sortable`: Enables swapping list items if the value is `true`. The default value is `false`. +The `sortable` property enables swapping list items if its value is `true`. Its default value is `false`. ### Virtualization -To enable virtualization, make sure one of these conditions is met: +To enable virtualization, make sure one of these two conditions is met: 1. You set the `itemsHeight` property. In this case, the list height will be fixed and equal to that value. -2. You set the `display: flex` style for the list parent container. In this case, the list will adapt to the container - width. +2. You set the `display: flex` style for the list parent container. In this case, the list will adapt to the container width. ### External management @@ -225,34 +223,34 @@ Likewise, you can forward `onFocus` and `onBlur` if you need to repeat the behav ### Filter -`filter` - a value of the filter. Used with external sorting. +The `filter` property provides the filter value used with external sorting. ### PropTypes -| Name | Description | Type | Default | -| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------- | :------ | -| [items](#items) | List of items | `Array` | [] | -| itemHeight | Item height in `px` (or a function that returns the height value for an item). `(item: any) => number` | `Number/Function` | 28 | -| itemsHeight | Item list height (or a function that returns the height value for a list). It can be helpful when setting the list height dynamically. `(items: []) => number` | `Number/Function` | | -| renderItem | Render function with an item received as an input and a React node returned. `(item: any, isItemActive: bool, itemIndex: number) => React.ReactNode` | `Function` | | -| filterItem | Filtering function that receives a specified string as a search/filter input and returns a function that receives an item as an input and outputs boolean `(filter: string) => (item: any) => boolean` | `Function` | | -| filterable | Flag that enables a filter field. | `Boolean` | true | -| filterPlaceholder | Placeholder for a filter field. | `String` | | -| filter | Filter value (if external sorting is used). | `String` | | -| filterClassName | Class for filter input styles | `String` | | -| onChangeFilter | Filter change handler (if external sorting is used). `(filter: string) => void` | `Function` | | -| onFilterEnd | Function invoked after internal filtering is completed. `({items}: {items: T[]}) => void` | `Function` | | -| emptyPlaceholder | Placeholder for an empty list. | `React.ReactNode` | | -| sortable | Flag that enables list sorting. | `Boolean` | | -| sortHandleAlign | Sorting indicator alignment (left or right). | `left` `right` | | -| onSortEnd | Sorting event handler. `({oldIndex: number, newIndex: number}) => void` | `Function` | | -| virtualized | Flag that enables virtualization. If not active, all items are rendered at once. | `Boolean` | true | -| onItemClick | Item click handler. `(item: any, index: number, fromKeyboard?: bool) => void` | `Function` | | -| deactivateOnLeave | If the flag is set, an item's selection is deactivated once the cursor leaves the item or the list loses its focus. If not set, the last selected item will always be selected. | `Boolean` | true | -| activeItemIndex | If a value is set, an item with this index is rendered as active ~~until the curse is lifted~~. | `Number` | | -| selectedItemIndex | If a value is set, an item with this index is rendered as selected (the background color is from `--g-color-base-selection`). | `Number/Array` | | -| itemClassName | Custom class name to be added to an item container | `String` | | -| itemsClassName | Custom class name to be added to an item list | `String` | | -| role | HTML `role` attribute | `String` | list | -| id | HTML `id` attribute | `string` | | -| onChangeActive | Fires when the index of an option in the listbox, visually indicated as having keyboard focus, is changed. `(index?: number) => void` | `Function` | | +| Name | Description | Type | Default | +| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------- | :------ | +| [items](#items) | List of items | `Array` | [] | +| itemHeight | Item height in `px` or a function that returns the height value for an item: `(item: any) => number`. | `Number/Function` | 28 | +| itemsHeight | Item list height or a function that returns the height value for a list. It can be helpful when setting the list height dynamically: `(items: []) => number`. | `Number/Function` | | +| renderItem | Render function with an item received as an input and a React node returned: `(item: any, isItemActive: bool, itemIndex: number) => React.ReactNode`. | `Function` | | +| filterItem | Filtering function that receives a specified string as a search or filter input and returns a function that receives an item as an input and outputs boolean: `(filter: string) => (item: any) => boolean`. | `Function` | | +| filterable | Flag that enables a filter field. | `Boolean` | true | +| filterPlaceholder | Placeholder for a filter field. | `String` | | +| filter | Filter value (in case external sorting is used). | `String` | | +| filterClassName | Class for filter input styles. | `String` | | +| onChangeFilter | Filter change handler (in case external sorting is used): `(filter: string) => void`. | `Function` | | +| onFilterEnd | Function invoked after internal filtering is complete: `({items}: {items: T[]}) => void` | `Function` | | +| emptyPlaceholder | Placeholder for an empty list. | `React.ReactNode` | | +| sortable | Flag that enables list sorting. | `Boolean` | | +| sortHandleAlign | Sorting indicator alignment (left or right). | `left` `right` | | +| onSortEnd | Sorting event handler: `({oldIndex: number, newIndex: number}) => void`. | `Function` | | +| virtualized | Flag that enables virtualization. If inactive, all items are rendered at once. | `Boolean` | true | +| onItemClick | Item click handler: `(item: any, index: number, fromKeyboard?: bool) => void`. | `Function` | | +| deactivateOnLeave | If this flag is set, the item selection is deactivated once the cursor leaves the item or the list loses its focus. If not set, the last selected item will always be selected. | `Boolean` | true | +| activeItemIndex | If a value is set, an item with this index is rendered as active. | `Number` | | +| selectedItemIndex | If a value is set, an item with this index is rendered as selected (the background color is taken from `--g-color-base-selection`). | `Number/Array` | | +| itemClassName | Custom class name to add to an item container. | `String` | | +| itemsClassName | Custom class name to add to an item list. | `String` | | +| role | `role` HTML attribute | `String` | list | +| id | `id` HTML attribute | `string` | | +| onChangeActive | Fires when the index of an option in the listbox that is visually highlighted as having keyboard focus is changed: `(index?: number) => void`. | `Function` | | diff --git a/src/components/Loader/README-ru.md b/src/components/Loader/README-ru.md new file mode 100644 index 0000000000..db712b7151 --- /dev/null +++ b/src/components/Loader/README-ru.md @@ -0,0 +1,50 @@ + + +# Loader + + + +```tsx +import {Loader} from '@gravity-ui/uikit'; +``` + +Компонент `Loader` (загрузчик) отображает процесс загрузки в виде мигающих полос. В отличие от `Spin` он используется в глобальных сценариях, например, для всей страницы или диалога. + +### Размер + + + + + +```tsx + + + +``` + + + +`S` — маленький размер, используется, когда стандартный загрузчик слишком велик. + +`M` — средний (базовый) размер, используется в большинстве случаев. + +`L` — большой размер, используется, когда стандартный загрузчик слишком мал. + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------- | :--------------------------------------------- | :---------------: | :-------------------: | +| size | Размер загрузчика. | `"s"` `"m"` `"l"` | `"s"` | +| className | Пользовательский CSS-класс корневого элемента. | `string` | | diff --git a/src/components/Loader/README.md b/src/components/Loader/README.md index 5829f1b003..63a619b8c8 100644 --- a/src/components/Loader/README.md +++ b/src/components/Loader/README.md @@ -36,15 +36,15 @@ LANDING_BLOCK--> -S: Small size, used when the regular loader is too large. +`S`: Small size, used when the regular loader is too large. -M: Medium (basic) size, used in most cases. +`M`: Medium (basic) size, used in most cases. -L: Large size, used when the regular loader is too small. +`L`: Large size, used when the regular loader is too small. ## Properties -| Name | Description | Type | Default | -| :-------- | :-------------------------------- | :---------------: | :-----: | -| size | Loader size | `"s"` `"m"` `"l"` | `"s"` | -| className | Custom CSS class for root element | `string` | | +| Name | Description | Type | Default | +| :-------- | :------------------------------------ | :---------------: | :-----: | +| size | Loader size | `"s"` `"m"` `"l"` | `"s"` | +| className | Custom CSS class for the root element | `string` | | diff --git a/src/components/Menu/README-ru.md b/src/components/Menu/README-ru.md new file mode 100644 index 0000000000..ee26a49190 --- /dev/null +++ b/src/components/Menu/README-ru.md @@ -0,0 +1,365 @@ + + +# Menu + + + +```tsx +import {Menu} from '@gravity-ui/uikit'; +``` + +Компонент `Menu` позволяет легко создавать представления для списков действий. + +Он включает в себя специальные компоненты для элементов (`Menu.Item`) и групп (`Menu.Group`), которые можно комбинировать для создания более сложных меню. + + + + + +```tsx + + First + Second + + One + Two + + +``` + + + +### `Size` (размер) + +Позволяет задать размер меню. Значение по умолчанию — `m`. + + + + + +```tsx + + First + Second + + + + First + Second + + + + First + Second + + + + First + Second + +``` + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------- | :------------------------------------------------------- | :----------------------: | :-------------------: | +| size | Размер меню. | `"s"` `"m"` `"l"` `"xl"` | `"m"` | +| children | Дочерний элемент. | `React.ReactNode` | | +| className | HTML-атрибут `class`. | `string` | | +| style | HTML-атрибут `style`. | `React.CSSProperties` | | +| qa | Атрибут `data-qa` в HTML, используется для тестирования. | `string` | | + +## Menu.Item + +Отвечает за рендеринг элементов меню. + +### Иконка + +Для отображения иконки в начале или в конце элемента меню используйте свойства `iconStart` или `iconEnd`: + + + + + +```tsx + + }>Item with icon + Item without icon + +``` + +```tsx + + }>Item with icon + Item without icon + +``` + + + +### Состояния + +Позволяет включать или отключать (делать неактивными) отдельные элементы меню: + + + + + +```tsx + + First + Second + Third + +``` + + + +### `Theme` (тема) + +Позволяет изменить тему элемента меню. Тема по умолчанию — `normal`. + + + + + +```tsx + + First + Second + Third + +``` + + + +### Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :--------- | :------------------------------------------------------- | :-----------------------: | :-------------------: | +| iconStart | Иконка меню перед текстом элемента. | `ReactNode` | | +| iconEnd | Иконка меню после текста элемента. | `ReactNode` | | +| selected | Флаг выбранного элемента меню. | `boolean` | `false` | +| disabled | Флаг отключенного элемента меню. | `boolean` | `false` | +| active | Флаг активного элемента меню. | `boolean` | `false` | +| href | URL-адрес. | `string` | | +| title | Атрибут заголовка. | `string` | | +| target | Атрибут целевого ресурса. | `string` | | +| rel | Атрибут `rel`. | `string` | | +| onClick | Обработчик события клика. | `React.MouseEventHandler` | | +| theme | Тема элемента меню. | `"normal"` `"danger"` | `"normal"` | +| children | Дочерний элемент. | `React.ReactNode` | | +| className | HTML-атрибут `class`. | `string` | | +| style | HTML-атрибут `style`. | `React.CSSProperties` | | +| qa | Атрибут `data-qa` в HTML, используется для тестирования. | `string` | | +| extraProps | Дополнительные HTML-атрибуты. | `Record` | | + +## Menu.Group + +В пределах одного меню элементы можно группировать по темам: + + + + + +```tsx + + First + + One + Two + + + One + Two + + Middle + + One + Two + + Last + +``` + + + +### Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------- | :------------------------------------------------------- | :-------------------: | :-------------------: | +| label | Лейбл группы меню. | `string` | | +| children | Дочерний элемент. | `React.ReactNode` | | +| className | HTML-атрибут `class`. | `string` | | +| style | HTML-атрибут `style`. | `React.CSSProperties` | | +| qa | Атрибут `data-qa` в HTML, используется для тестирования. | `string` | | diff --git a/src/components/Menu/README.md b/src/components/Menu/README.md index 618b115510..06e12c0293 100644 --- a/src/components/Menu/README.md +++ b/src/components/Menu/README.md @@ -8,9 +8,9 @@ import {Menu} from '@gravity-ui/uikit'; ``` -The `Menu` component makes it easy to create views for actions lists. +The `Menu` component enables easily creating views for action lists. -`Menu` has dedicated components for items (`Menu.Item`) and a groups (`Menu.Group`). You can combine them to create more complex menus. +It has dedicated components for items (`Menu.Item`) and groups (`Menu.Group`). You can combine them to create more complex menus. | :-------- | :----------------------------------------- | :----------------------: | :-----: | | size | Menu size | `"s"` `"m"` `"l"` `"xl"` | `"m"` | | children | Child element | `React.ReactNode` | | -| className | HTML `class` attribute | `string` | | -| style | HTML `style` attribute | `React.CSSProperties` | | -| qa | HTML `data-qa` attribute, used for testing | `string` | | +| className | `class` HTML attribute | `string` | | +| style | `style` HTML attribute | `React.CSSProperties` | | +| qa | `data-qa` HTML attribute, used for testing | `string` | | ## Menu.Item @@ -133,7 +133,7 @@ This property is used to render menu items. ### Icon -The `iconStart` or `iconEnd` properties is used to display an icon at the start or end of a menu item: +Use the `iconStart` or `iconEnd` property to display an icon at the start or end of a menu item: | onClick | Handler for onclick event | `React.MouseEventHandler` | | | theme | Menu item theme | `"normal"` `"danger"` | `"normal"` | | children | Child element | `React.ReactNode` | | -| className | HTML `class` attribute | `string` | | -| style | HTML `style` attribute | `React.CSSProperties` | | -| qa | HTML `data-qa` attribute, used for testing | `string` | | -| extraProps | Additional html attributes | `Record` | | +| className | `class` HTML attribute | `string` | | +| style | `style` HTML attribute | `React.CSSProperties` | | +| qa | `data-qa` HTML attribute, used for testing | `string` | | +| extraProps | Additional HTML attributes | `Record` | | ## Menu.Group @@ -356,10 +356,10 @@ LANDING_BLOCK--> ### Properties -| Name | Description | Type | Default | -| :-------- | :-------------------------------------- | :-------------------: | :-----: | -| label | Menu group label | `string` | | -| children | Child element | `React.ReactNode` | | -| className | HTML `class` attribute | `string` | | -| style | HTML `style` attribute | `React.CSSProperties` | | -| qa | HTML `data-qa` attribute, used in tests | `string` | | +| Name | Description | Type | Default | +| :-------- | :----------------------------------------- | :-------------------: | :-----: | +| label | Menu group label | `string` | | +| children | Child element | `React.ReactNode` | | +| className | `class` HTML attribute | `string` | | +| style | `style` HTML attribute | `React.CSSProperties` | | +| qa | `data-qa` HTML attribute, used for testing | `string` | | diff --git a/src/components/Modal/README-ru.md b/src/components/Modal/README-ru.md new file mode 100644 index 0000000000..248e0b0901 --- /dev/null +++ b/src/components/Modal/README-ru.md @@ -0,0 +1,64 @@ + + +# Modal + + + +```tsx +import {Modal} from '@gravity-ui/uikit'; +``` + +Компонент `Modal` (модальное окно) используется для создания всплывающих окон, которые перекрывают основной контент страницы. +При открытии модального окна прокрутка страницы отключается, а фокус автоматически переводится на его содержимое. Дочерние компоненты `Modal` рендерятся внутри компонента [`Portal`](../Portal). +С `Modal` можно создавать диалоги, алерты, подтверждения и другие элементы. + +## Использование + +```tsx +import React from 'react'; +import {Button, Modal} from '@gravity-ui/uikit'; + +const [open, setOpen] = React.useState(false); + + + setOpen(false)}> + Content + +``` + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------------------- | :--------------------------------------------------------------------------------------------------------- | :---------------: | :-------------------: | +| autoFocus | В открытом состоянии фокус будет установлен на первый интерактивный элемент в содержимом. | `boolean` | `true` | +| children | Любое содержимое React. | `React.ReactNode` | | +| className | HTML-атрибут `class` для корневого узла. | `string` | | +| container | DOM-элемент, в который монтируются дочерние элементы. | `HTMLElement` | `document.body` | +| contentClassName | Атрибут `class` в HTML для узла с содержимым. | `string` | | +| disableBodyScrollLock | Отключает блокировку прокрутки, пока модальное окно открыто. | `boolean` | `false` | +| disableEscapeKeyDown | Отключает закрытие при нажатии на клавишу `Esc`. | `boolean` | `false` | +| disableOutsideClick | Отключает закрытие элемента по клику вне его области. | `boolean` | `false` | +| focusTrap | Включает фиксацию фокуса внутри элемента. | `boolean` | `true` | +| keepMounted | Компонент `Modal` не будет удален из DOM при скрытии. | `boolean` | `false` | +| onClose | Обработчик события закрытия `Modal`. | `Function` | | +| onEnterKeyDown | Обработчик события нажатия на клавишу `Enter`. | `Function` | | +| onEscapeKeyDown | Обработчик события нажатия на клавишу `Esc`. | `Function` | | +| onTransitionEnter | Обработчик начала анимации открытия. | `Function` | | +| onTransitionExit | Обработчик начала анимации закрытия. | `Function` | | +| onTransitionEntered | Обработчик завершения анимации открытия. | `Function` | | +| onTransitionExited | Обработчик завершения анимации закрытия. | `Function` | | +| onOutsideClick | Обработчик события клика вне элемента. | `Function` | | +| open | Управляет видимостью `Modal`. | `boolean` | `false` | +| qa | Атрибут для тестирования (`data-qa`). | `string` | | +| restoreFocusRef | Элемент, на который вернется фокус. | `React.RefObject` | | +| style | HTML-атрибут `style` для корневого узла. | `string` | | +| aria-label | HTML-атрибут `aria-label` для описания `Modal`. | `string` | | +| aria-labelledby | Идентификатор видимого элемента заголовка в `Modal`. | `string` | | +| contentOverflow | Определяет, имеет ли `Modal` внутреннюю полосу прокрутки или увеличивается в размерах вместе с содержимым. | `visible` `auto` | `visible` | + +## API CSS + +| Имя | Описание | +| :------------------------ | :----------------------------------------------------- | +| `--g-modal-margin` | Отступ вокруг содержимого `Modal`. | +| `--g-modal-border-radius` | Радиус скругления углов элемента с содержимым `Modal`. | diff --git a/src/components/Modal/README.md b/src/components/Modal/README.md index 310776c5d7..3ed62be531 100644 --- a/src/components/Modal/README.md +++ b/src/components/Modal/README.md @@ -9,8 +9,8 @@ import {Modal} from '@gravity-ui/uikit'; ``` The `Modal` component serves as base for creating pop-up windows with a backdrop above the rest of the content on a page. -It disables scrolling while opening and manages focus for content. The child components of `Modal` are rendered inside the [`Portal`](../Portal) component. -Through `Modal`, you can implement dialogs, alerts, confirmations, and more. +It disables scrolling while opening and manages focus for content. The `Modal` child components are rendered inside the [`Portal`](../Portal) component. +With `Modal`, you can implement dialogs, alerts, confirmations, and more. ## Usage @@ -28,37 +28,37 @@ const [open, setOpen] = React.useState(false); ## Properties -| Name | Description | Type | Default | -| :-------------------- | :---------------------------------------------------------------------------------- | :---------------: | :-------------: | -| autoFocus | While opened, the focus will be set to the first interactive element in the content | `boolean` | `true` | -| children | Any React content | `React.ReactNode` | | -| className | HTML `class` attribute for root node | `string` | | -| container | DOM element to which children are to be mounted to | `HTMLElement` | `document.body` | -| contentClassName | HTML `class` atribute for content node | `string` | | -| disableBodyScrollLock | Do not lock scroll while open | `boolean` | `false` | -| disableEscapeKeyDown | Do not trigger close on `Esc` | `boolean` | `false` | -| disableOutsideClick | Do not trigger close on outside clicks | `boolean` | `false` | -| focusTrap | Enable focus trapping behavior | `boolean` | `true` | -| keepMounted | `Modal` will not be removed from the DOM upon hiding | `boolean` | `false` | -| onClose | Handle `Modal` close event | `Function` | | -| onEnterKeyDown | `Enter` press event handler | `Function` | | -| onEscapeKeyDown | `Esc` press event handler | `Function` | | -| onTransitionEnter | Open transition start event handler | `Function` | | -| onTransitionExit | Close transition start event handler | `Function` | | -| onTransitionEntered | Open transition end event handler | `Function` | | -| onTransitionExited | Close transition end event handler | `Function` | | -| onOutsideClick | Outside click event handler | `Function` | | -| open | Manages `Modal` visibility | `boolean` | `false` | -| qa | Test attribute (`data-qa`) | `string` | | -| restoreFocusRef | Element the focus will be restored to | `React.RefObject` | | -| style | HTML `style` atribute for root node | `string` | | -| aria-label | HTML `aria-label` attribute to describe the `Modal` | `string` | | -| aria-labelledby | Id of the visible `Modal` caption element | `string` | | -| contentOverflow | Define whether `Modal` has a scroll indicator inside or grows with the content | `visible` `auto` | `visible` | +| Name | Description | Type | Default | +| :-------------------- | :------------------------------------------------------------------------------------------- | :---------------: | :-------------: | +| autoFocus | While open, the focus will be set to the first interactive element in the content | `boolean` | `true` | +| children | Any React content | `React.ReactNode` | | +| className | `class` HTML attribute for the root node | `string` | | +| container | DOM element to which children are mounted | `HTMLElement` | `document.body` | +| contentClassName | `class` HTML atribute for the content node | `string` | | +| disableBodyScrollLock | Disables locking scroll while open | `boolean` | `false` | +| disableEscapeKeyDown | Disables triggering close on `Esc` | `boolean` | `false` | +| disableOutsideClick | Disables triggering close on outside clicks | `boolean` | `false` | +| focusTrap | Enables focus trapping behavior | `boolean` | `true` | +| keepMounted | `Modal` will not be removed from the DOM upon hiding | `boolean` | `false` | +| onClose | Handles `Modal` close event | `Function` | | +| onEnterKeyDown | `Enter` press event handler | `Function` | | +| onEscapeKeyDown | `Esc` press event handler | `Function` | | +| onTransitionEnter | Open transition start event handler | `Function` | | +| onTransitionExit | Close transition start event handler | `Function` | | +| onTransitionEntered | Open transition end event handler | `Function` | | +| onTransitionExited | Close transition end event handler | `Function` | | +| onOutsideClick | Outside click event handler | `Function` | | +| open | Manages `Modal` visibility | `boolean` | `false` | +| qa | Test attribute (`data-qa`) | `string` | | +| restoreFocusRef | Element the focus will be restored to | `React.RefObject` | | +| style | `style` HTML attribute for the root node | `string` | | +| aria-label | `aria-label` HTML attribute to describe `Modal` | `string` | | +| aria-labelledby | ID of the visible `Modal` caption element | `string` | | +| contentOverflow | Determines whether the `Modal` has a scroll indicator inside or gets larger with the content | `visible` `auto` | `visible` | ## CSS API -| Name | Description | -| :------------------------ | :---------------------------- | -| `--g-modal-margin` | Margin around Modal's content | -| `--g-modal-border-radius` | Modal's content border radius | +| Name | Description | +| :------------------------ | :-------------------------------- | +| `--g-modal-margin` | Margin around the `Modal` content | +| `--g-modal-border-radius` | `Modal` content border radius | diff --git a/src/components/Overlay/README-ru.md b/src/components/Overlay/README-ru.md new file mode 100644 index 0000000000..cec7a85a03 --- /dev/null +++ b/src/components/Overlay/README-ru.md @@ -0,0 +1,47 @@ + + +# Overlay + + + +```tsx +import {Overlay} from '@gravity-ui/uikit'; +``` + +Компонент `Overlay` рендерит наложение поверх родительского элемента с относительным позиционированием (свойство `position` в значении `relative`). +Его можно использовать, например, чтобы сохранить необходимую структуру во время загрузки данных. + +```jsx +import {Box, Overlay, Loader} from '@gravity-ui/uikit'; + + +
Some content to hide under overlay
+ + + +; +``` + +## Внешний вид + +### Фон + +Доступны два типа фоновых цветов: `base` и `float`. + + + +```tsx + + +``` + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :--------- | :-------------------------------------------- | :----------------: | :-------------------: | +| className | Имя CSS-класса корневого элемента. | `string` | | +| visible | Состояние видимости оверлея. | `boolean` | `false` | +| background | Стиль фона оверлея. | `"base"` `"float"` | `base` | +| children | Содержимое (как правило, компонент `Loader`). | `React.ReactNode` | | diff --git a/src/components/Overlay/README.md b/src/components/Overlay/README.md index b45a32f03c..517bb02bee 100644 --- a/src/components/Overlay/README.md +++ b/src/components/Overlay/README.md @@ -8,8 +8,7 @@ import {Overlay} from '@gravity-ui/uikit'; ``` -The `Overlay` component renders an overlay over the parent element with relative position, -i.e. parent element must have `position` set to `relative`. +The `Overlay` component renders an overlay over the parent element with the relative position, i.e., the parent element must have `position` set to `relative`. For example, it can be used to preserve the desired layout while loading data. ```jsx @@ -40,9 +39,9 @@ You can use `base` or `float` background colors. ## Properties -| Name | Description | Type | Default | -| :--------- | :---------------------------------- | :----------------: | :-----: | -| className | CSS class name of the root element | `string` | | -| visible | Overlay visibility state | `boolean` | `false` | -| background | Overlay background style | `"base"` `"float"` | `base` | -| children | Content, usually a Loader component | `React.ReactNode` | | +| Name | Description | Type | Default | +| :--------- | :-------------------------------------- | :----------------: | :-----: | +| className | CSS class name of the root element | `string` | | +| visible | Overlay visibility state | `boolean` | `false` | +| background | Overlay background style | `"base"` `"float"` | `base` | +| children | Content (usually, a `Loader` component) | `React.ReactNode` | | diff --git a/src/components/Pagination/README-ru.md b/src/components/Pagination/README-ru.md new file mode 100644 index 0000000000..3a5e953d8e --- /dev/null +++ b/src/components/Pagination/README-ru.md @@ -0,0 +1,40 @@ + + +# Pagination + + + +```tsx +import {Pagination} from '@gravity-ui/uikit'; +``` + +Компонент `Pagination` используется для рендеринга элементов постраничной навигации. + +## Использование + +```jsx +import {Pagination, PaginationProps} from '@gravity-ui/uikit'; + +const [state, setState] = React.useState({page: 1, pageSize: 100}); + +const handleUpdate: PaginationProps['onUpdate'] = (page, pageSize) => + setState((prevState) => ({...prevState, page, pageSize})); + +const pagination = ; +``` + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------------- | :----------------------------------------------------------------------------------------------------------- | :--------: | :-------------------: | +| className | HTML-атрибут `class`. | `string` | | +| compact | Скрывает заголовки для кнопок `First`, `Previous` и `Next`. В мобильной версии всегда имеет значение `true`. | `boolean` | `true` | +| onUpdate | Вызывается при изменении номера страницы или свойства `pageSize`. | `Function` | | +| size | Размер элементов пагинации. По умолчанию `l` для мобильных и `m` для десктопных версий. | `string` | | +| page | Номер текущей страницы. | `number` | | +| pageSize | Количество элементов данных на одной странице. | `number` | | +| pageSizeOptions | Позволяет указать опции для `sizeChanger`. | `number[]` | | +| total | Общее количество элементов данных. | `number` | | +| showInput | Отображает элемент ввода для перехода к конкретной странице | `boolean` | `false` | +| showPages | Отображает нумерацию страниц. | `boolean` | `true` | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | diff --git a/src/components/Pagination/README.md b/src/components/Pagination/README.md index d613f176ab..a0364ea742 100644 --- a/src/components/Pagination/README.md +++ b/src/components/Pagination/README.md @@ -27,14 +27,14 @@ const pagination = + +# Palette + + + +```tsx +import {Palette} from '@gravity-ui/uikit'; +``` + +Компонент `Palette` (палитра) отображает сетку с иконками, эмодзи, реакциями и символами, которые можно выбирать или снимать с них выбор. + +### Отключенное состояние + +Можно отключить опции с помощью свойства `disabled`. Если нужно отключить только некоторые опции, измените значение свойства `disabled` у нужных опций (`PaletteOption[]`). + + + + + +```tsx +const options: PaletteOption[] = [ + // disable a single item + {content: '😎', value: 'ID-cool', disabled: true}, + {content: '🥴', value: 'ID-woozy'}, +]; +// or disable all of them +; +``` + + + +### Размер + +Размер `Palette` можно настроить с помощью свойства `size`. Размер по умолчанию — `s`. + + + + + +```tsx +const options: PaletteOption[] = [ + {content: '😎', value: 'ID-cool'}, + {content: '🥴', value: 'ID-woozy'}, +]; + + + + + +``` + + + +### Столбцы + +Количество столбцов в сетке можно изменить через свойство `columns` (по умолчанию — `6`). + + + + + +```tsx +const options: PaletteOption[] = [ + {content: '😎', value: 'ID-cool'}, + {content: '🥴', value: 'ID-woozy'}, +]; +; +``` + + + +### `Multiple` (несколько опций) + +По умолчанию можно выбирать и снимать выбор с нескольких опций. Если нужно разрешить выбор только одной опции, отключите свойство `multiple`. + + + + + +```tsx +const options: PaletteOption[] = [ + {content: '😎', value: 'ID-cool'}, + {content: '🥴', value: 'ID-woozy'}, +]; +; +``` + + + +### Свойства + +`PaletteProps`: + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------------- | :--------------------------------------------------------------------------------------- | :----------------------------------------------------: | :-------------------: | +| aria-label | HTML-атрибут `aria-label`. | `string` | | +| aria-labelledby | Идентификатор видимого элемента заголовка в `Palette`. | `string` | | +| className | HTML-атрибут `class`. | `string` | | +| columns | Количество элементов в одной строке. | `number` | `6` | +| defaultValue | Задает начальное значение состояния компонента при его монтировании. | `string[]` | | +| disabled | Отключает опции. | `boolean` | `false` | +| multiple | Включает возможность выбора нескольких опций. | `boolean` | `true` | +| onBlur | Обработчик события `onBlur`. | `(event: React.FocusEvent) => void` | | +| onFocus | Обработчик события `onFocus`. | `(event: React.FocusEvent) => void` | | +| onUpdate | Срабатывает при изменении состояния пользователем. Передает новое значение как аргумент. | `(value: string[]) => void` | | +| optionClassName | HTML-атрибут `value` для кнопки палитры. | `string` | | +| options | Список опций (элементов палитры). | `PaletteOption[]` | `[]` | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | +| rowClassName | HTML-атрибут `class` для строки палитры. | `string` | | +| size | Определяет размер элементов. | `xs` `s` `m` `l` `xl` | `m` | +| style | HTML-атрибут `style`. | `React.CSSProperties` | | +| value | Текущее значение для контролируемого использования компонента. | `string[]` | | + +`PaletteOption`: + +| Имя | Описание | Тип | Значение по умолчанию | +| :------- | :-------------------- | :---------: | :-------------------: | +| content | HTML-атрибут `class`. | `ReactNode` | | +| disabled | Отключает кнопку. | `boolean` | `false` | +| title | HTML-атрибут `title`. | `string` | | +| value | Значение контрола. | `string` | | diff --git a/src/components/Palette/README.md b/src/components/Palette/README.md index 104eaac9dc..bdf6b34597 100644 --- a/src/components/Palette/README.md +++ b/src/components/Palette/README.md @@ -8,11 +8,11 @@ import {Palette} from '@gravity-ui/uikit'; ``` -The `Palette` component is used display a grid of icons/emojis/reactions/symbols which you can select or unselect. +The `Palette` component is used to display a grid of icons, emojis, reactions, and symbols which you can select or deselect. ### Disabled state -You can disable every option with the `disabled` property. If you want to disable only a portion of options, you can change the `disabled` property of some of the `options` (`PaletteOption[]`). +You can disable every option using the `disabled` property. If you want to disable only certain options, you can change the `disabled` property of those `options` (`PaletteOption[]`). + +# PinInput + + + +```tsx +import {PinInput} from '@gravity-ui/uikit'; +``` + +`PinInput` — это группа элементов для быстрого ввода последовательности числовых или алфавитно-цифровых значений. Чаще всего используется для ввода одноразовых паролей (OTP) или кодов подтверждения, получаемых через SMS, электронную почту или приложения-аутентификаторы. + +Каждый элемент ввода принимает один символ за раз. После успешного ввода значения фокус перемещается на следующий элемент ввода, пока все поля не будут заполнены. + +## Тип + +По умолчанию элементы ввода принимают только числовые значения. Чтобы разрешить ввод алфавитно-цифровых значений, установите свойство `type` в значение `"alphanumeric"`: + + + + + +```tsx + +``` + + + +## Размер + +Данный компонент бывает 4 размеров: `s`, `m`, `l` и `xl`. Размер по умолчанию — `m`. + + + + + +```tsx + + + + +``` + + + +## Состояние + +Если вы не хотите, чтобы пользователь взаимодействовал с компонентом, задайте свойство `disabled`: + + + + + +```tsx + +``` + + + +Чтобы отобразить недопустимое состояние компонента, задайте значение `"invalid"` в свойстве `validationState`. Опционально можно задать текст сообщения об ошибке через свойство `errorMessage`. + + + + + +```tsx + +``` + + + +## Заглушка + +По умолчанию заглушка в элементах ввода отсутствует. Можно добавить ее с помощью свойства `placeholder`: + + + + + +```tsx + +``` + + + +## Маска + +Если нужно маскировать введенные значения, используйте свойство `mask`, которое работает аналогично ``: + + + + + +```tsx + +``` + + + +## OTP + +Если вы хотите, чтобы браузер предлагал одноразовые коды из внешнего контекста (например, SMS), задайте свойство `otp`. + +## API + +- `focus(): void` — переключает фокус на текущий активный элемент ввода. + +## API CSS + +| Имя | Описание | +| :------------------------- | :------------------------------------------------------------------------------------------ | +| `--g-pin-input-item-width` | Задает ширину каждого элемента ввода, если для `responsive` не установлено значение `true`. | +| `--g-pin-input-item-gap` | Задает интервал между элементами ввода. | + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :--------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | :-------------------: | +| apiRef | `Ref` к [API](#api). | `React.RefObject` | | +| aria-describedby | HTML-атрибут `aria-describedby`. | `string` | | +| aria-label | HTML-атрибут `aria-label`. | `string` | | +| aria-labelledby | HTML-атрибут `aria-labelledby`. | `string` | | +| autoFocus | Включает или отключает фокусировку на первом элементе ввода при первоначальной отрисовке. | `boolean` | | +| className | HTML-атрибут `class`. | `string` | | +| defaultValue | Начальное значение для неконтролируемого компонента. | `string[]` | | +| disabled | Включает или отключает состояние `disabled`. | `boolean` | | +| errorMessage | Текст ошибки, расположенный в нижнем левом углу рядом с контейнером заметки. Отображается только если `validationState` имеет значение `"invalid"`. | `React.ReactNode` | | +| id | Префикс HTML-атрибута `id` для элементов ввода. Полученный идентификатор также будет содержать часть `"-${index}"`. | `string` | | +| length | Количество полей ввода. | `number` | `4` | +| mask | Если установлено значение `true`, вводимые значения будут скрыты, как в поле пароля. | `boolean` | | +| name | Префикс HTML-атрибута `name` для элемента ввода. | `string` | | +| form | Ассоциированная форма базового элемента ввода. | `string` | | +| note | Элемент, расположенный в нижнем левом углу рядом с контейнером ошибки. | `React.ReactNode` | | +| onUpdate | Обратный вызов, срабатывающий при изменении любого из элементов ввода. | `(value: string[]) => void` | | +| onUpdateComplete | Обратный вызов, срабатывающий при изменении любого из элементов ввода и заполнении всех полей ввода. | `(value: string[]) => void` | | +| otp | При установке значения `true` добавляет атрибут `autocomplete="one-time-code"` к элементам ввода. | `boolean` | | +| placeholder | Заглушка для элементов ввода. | `string` | | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | +| responsive | Ширина родительского контейнера равномерно распределяется между элементами ввода. | `boolean` | | +| size | Размер поля ввода. | `"s"` `"m"` `"l"` `"xl"` | `"m"` | +| style | HTML-атрибут `style`. | `React.CSSProperties` | | +| type | Определяет допустимые типы значений для ввода. | `"numeric"` `"alphanumeric"` | `"numeric"` | +| validationState | Состояние валидации, которое определяет внешний вид компонента. | `"invalid"` | | +| value | Текущее значение для контролируемого компонента. | `string[]` | | +| `onFocus` | Обратный вызов, срабатывающий, когда компонент получает фокус. | `(event: React.FocusEvent) => void` | | +| `onBlur` | Обратный вызов, срабатывающий, когда компонент теряет фокус. | `(event: React.FocusEvent) => void` | | diff --git a/src/components/PinInput/README.md b/src/components/PinInput/README.md index 1b9e994db8..32bda61720 100644 --- a/src/components/PinInput/README.md +++ b/src/components/PinInput/README.md @@ -8,14 +8,13 @@ import {PinInput} from '@gravity-ui/uikit'; ``` -`PinInput` is a group of inputs to enter sequence of numeric or alphanumeric values quickly. The most common use case of the component -is entering OTP or confirmation codes received via SMS, email or authenticator app. +`PinInput` is a group of inputs to enter sequence of numeric or alphanumeric values quickly. Its most common use case is entering OTP or confirmation codes received through text messages (SMS), emails, or authenticator apps. -Each input collects one character at time. When value is accepted, focus is moved to the next input, until all fields are filled. +Each input collects one character at a time. When a value is accepted, the focus is moved to the next input, until all fields are filled. ## Type -By default, inputs accept only numeric values. To allow alphanumeric values set the `type` prop to `"alphanumeric"`: +By default, the inputs only accept numeric values. To allow alphanumeric values, set the `type` property to `"alphanumeric"`: ## Size -The component comes in four sizes: `s`, `m`, `l`, `xl`. The default is `m`. +This component comes in four sizes: `s`, `m`, `l`, and `xl`. The default size is `m`. ## State -If you don't want the user to interact with the component set the `disabled` prop: +If you do not want the user to interact with the component, set the `disabled` property: -To show an invalid state of the component use the `validationState` prop with the `"invalid"` value. Optionally set an error text -with the `errorMessage` prop: +To show an invalid state of the component, use the `validationState` property with the `"invalid"` value. Optionally, you can set an error message text with the `errorMessage` property: ## Placeholder -By default, there is no placeholder on inputs. You can set it with the `placeholder` prop: +By default, there is no placeholder for inputs. You can set it with the `placeholder` property: ## Mask -If you need to mask entered values use the `mask` prop. It's similar to `` behaviour. +If you need to mask entered values, use the `mask` property. It is similar to the `` behavior. ## OTP -If you want the browser to suggest "one time codes" from the outer context (e.g. SMS) set the `otp` prop. +If you want the browser to suggest one-time codes from the outer context (e.g., SMS) set the `otp` property. ## API -- `focus(): void` - Set focus to the current active input. +- `focus(): void`: Sets focus to the current active input. ## CSS API -| Name | Description | -| :------------------------- | :----------------------------------------------------- | -| `--g-pin-input-item-width` | Set width of each input, unless `responsive` is `true` | -| `--g-pin-input-item-gap` | Set gap between inputs | +| Name | Description | +| :------------------------- | :----------------------------------------------------------- | +| `--g-pin-input-item-width` | Sets the width of each input, unless `responsive` is `true`. | +| `--g-pin-input-item-gap` | Sets a gap between inputs. | ## Properties -| Name | Description | Type | Default | -| :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | :---------: | -| apiRef | Ref to the [API](#api) | `React.RefObject` | | -| aria-describedby | HTML `aria-describedby` attribute | `string` | | -| aria-label | HTML `aria-label` attribute | `string` | | -| aria-labelledby | HTML `aria-labelledby` attribute | `string` | | -| autoFocus | Whether or not to focus the first input on initial render | `boolean` | | -| className | HTML `class` attribute | `string` | | -| defaultValue | Initial value for uncontrolled component | `string[]` | | -| disabled | Toggles `disabled` state | `boolean` | | -| errorMessage | Error text placed under the bottom-start corner that shares space with the note container. Only visible when `validationState` is set to `"invalid"` | `React.ReactNode` | | -| id | HTML `id` attribute prefix for inputs. Resulting id will also contain `"-${index}"` part | `string` | | -| length | Number of input fields | `number` | `4` | -| mask | When set to `true` mask input values like password field | `boolean` | | -| name | HTML `name` attribute for input | `string` | | -| form | The associate form of the underlying input element. | `string` | | -| note | An element placed under the bottom-end corner that shares space with the error container | `React.ReactNode` | | -| onUpdate | Callback fired when any of inputs change | `(value: string[]) => void` | | -| onUpdateComplete | Callback fired when any of inputs change and all of them are filled | `(value: string[]) => void` | | -| otp | When set to `true` adds `autocomplete="one-time-code"` to inputs | `boolean` | | -| placeholder | Placeholder for inputs | `string` | | -| qa | HTML `data-qa` attribute, for test purposes | `string` | | -| responsive | Parent's width distributed evenly between inputs | `boolean` | | -| size | Size of input fields | `"s"` `"m"` `"l"` `"xl"` | `"m"` | -| style | HTML `style` attribute | `React.CSSProperties` | | -| type | What type of input value is allowed | `"numeric"` `"alphanumeric"` | `"numeric"` | -| validationState | Validation state. Affect component's appearance | `"invalid"` | | -| value | Current value for controlled component | `string[]` | | -| `onFocus` | Callback fired when the component receives focus | `(event: React.FocusEvent) => void` | | -| `onBlur` | Callback fired when the component loses focus | `(event: React.FocusEvent) => void` | | +| Name | Description | Type | Default | +| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------: | :---------: | +| apiRef | Ref to the [API](#api). | `React.RefObject` | | +| aria-describedby | `aria-describedby` HTML attribute | `string` | | +| aria-label | `aria-label` HTML attribute | `string` | | +| aria-labelledby | `aria-labelledby` HTML attribute | `string` | | +| autoFocus | Enables or disables focusing on the first input on the initial render. | `boolean` | | +| className | `class` HTML attribute | `string` | | +| defaultValue | Initial value for an uncontrolled component. | `string[]` | | +| disabled | Toggles the `disabled` state | `boolean` | | +| errorMessage | Error text placed under the bottom-start corner that shares space with the note container. Only visible when `validationState` is set to `"invalid"`. | `React.ReactNode` | | +| id | `id` HTML attribute prefix for inputs. The resulting ID will also contain the `"-${index}"` part. | `string` | | +| length | Number of input fields. | `number` | `4` | +| mask | When set to `true`, the input values will be masked as the password field. | `boolean` | | +| name | `name` HTML attribute for input. | `string` | | +| form | The associate form of the underlying input element. | `string` | | +| note | An element placed under the bottom-end corner that shares space with the error container. | `React.ReactNode` | | +| onUpdate | Callback fired when any of inputs changes. | `(value: string[]) => void` | | +| onUpdateComplete | Callback fired when any of inputs changes and all of them are filled. | `(value: string[]) => void` | | +| otp | When set to `true`, adds `autocomplete="one-time-code"` to inputs. | `boolean` | | +| placeholder | Placeholder for inputs | `string` | | +| qa | `data-qa` HTML attribute used for testing purposes. | `string` | | +| responsive | Parent's width distributed evenly between inputs. | `boolean` | | +| size | Input field size. | `"s"` `"m"` `"l"` `"xl"` | `"m"` | +| style | `style` HTML attribute | `React.CSSProperties` | | +| type | Determines which input value types are allowed. | `"numeric"` `"alphanumeric"` | `"numeric"` | +| validationState | Validation state that affects the component appearance. | `"invalid"` | | +| value | Current value for the controlled component. | `string[]` | | +| `onFocus` | Callback fired when the component receives focus. | `(event: React.FocusEvent) => void` | | +| `onBlur` | Callback fired when the component loses focus. | `(event: React.FocusEvent) => void` | | diff --git a/src/components/PlaceholderContainer/README-ru.md b/src/components/PlaceholderContainer/README-ru.md new file mode 100644 index 0000000000..9760401ff3 --- /dev/null +++ b/src/components/PlaceholderContainer/README-ru.md @@ -0,0 +1,221 @@ + + +# PlaceholderContainer + + + +`PlaceholderContainer` — это компонент для отображения контента с изображением, текстовой информацией и контролами действий. + +## Направление + +`PlaceholderContainer` поддерживает направления `row` и `column` для компоновки контента. Направление передается через свойство `direction`. Размер по умолчанию — `row`. + +## Размер + +Размер `PlaceholderContainer` можно настроить с помощью свойства `size`. Размер по умолчанию — `l`. Принимает значения: `s`, `m`, `l` и `promo`. Значение `promo` устанавливает полную ширину контентной области, без минимальной высоты и с увеличенным размером заголовка. + +## Контролы действий + +Компонент `PlaceholderContainer` может отрисовывать контролы в форме кнопок или массив кнопок. Для этого используйте свойство `actions`. + + + +```tsx + + + + + 1:1 + + + + } + actions={[ + { + text: 'Main button', + view: 'normal', + onClick: () => console.log('Click by main button'), + }, + ]} +/> +``` + + + +Вы также можете отрисовывать пользовательские контролы: + + + +```tsx + + + + + 1:1 + + + + } + actions={ + console.log()}, + {text: 'text 2', action: () => console.log()}, + ]} + onSwitcherClick={(e) => console.log(e)} + switcher={ + + } + /> + } +/> +``` + + + +## Изображения и контент + +С помощью свойства `image` можно настроить параметры `src` и `alt` для изображения либо передать узел React. + + + +```tsx + + + + + 1:1 + + + + } +/> +``` + +С параметрами `src` и `alt`: + +```tsx + +``` + + + +Контент `PlaceholderContainer` состоит из секций заголовка и описания, которые задаются через соответствующие свойства. Для отображения пользовательского контента используйте свойство `content`. + +```tsx + + + + + 1:1 + + + + } + content={ +
+

There is any custom title here

+

+ You can add here any long text with custom content and use custom content + size for displaying very long texts. +

+
+ } +/> +``` + +## `Align` (выравнивание) + +Для настройки выравнивания контента внутри родительского контейнера используйте свойство `align`. Значение по умолчанию — `center`. + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :---------- | :----------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------: | :-------------------: | +| className | HTML-атрибут `class` (опционально). | `string` | | +| direction | Задает направление компоновки контента. Возможные значения: `"row"` и `"column"`. | `string` | `"row"` | +| size | Размер компонента. Принимает значения `"s"`, `"m"`, `"l"` и `"promo"`. | `string` | `"l"` | +| align | Задает горизонтальное выравнивание контента. Возможные значения: `"center"` и `"left"`. | `string` | `"center"` | +| title | Текст заголовка контента. | `string` | | +| description | Текст описания контента. | `string` | | +| image | Задает изображение через `src` или передает узел React. | `PlaceholderContainerImageNodeProps`
`\| PlaceholderContainerImageProps` | | +| content | Используется для рендеринга элемента ReactNode вместо контента (заголовка, описания и действий). | `React.ReactNode` | | +| actions | Используется для рендеринга массива кнопок или элемента ReactNode. | `PlaceholderContainerActionProps[]`
`\| React.ReactNode ` | | diff --git a/src/components/PlaceholderContainer/README.md b/src/components/PlaceholderContainer/README.md index e7b1b6b9b8..366b8a0b1b 100644 --- a/src/components/PlaceholderContainer/README.md +++ b/src/components/PlaceholderContainer/README.md @@ -4,19 +4,19 @@ -`PlaceholderContainer` is a component for displaying content with image, text content and action controls. +`PlaceholderContainer` is a component for displaying content with an image, text content, and action controls. ## Direction -The component has `row` and `column` directions of the content layout. To control it use the `direction` property. The default size is `row`. +`PlaceholderContainer` has `row` and `column` directions for the content layout. To manage it, use the `direction` property. The default size is `row`. ## Size -To control the size of the `PlaceholderContainer` use the `size` property. The default size is `l`. Possible values: `s`, `m`, `l`, `promo`. The `promo` value sets full width of the content block without minimal content height and a larger title size. +Use the `size` property to manage the `PlaceholderContainer` size. The default size is `l`. The possible values are `s`, `m`, `l`, and `promo`. The `promo` value sets the full width of the content section without the minimum content height and a larger title size. ## Action controls -The component can render button control or array of buttons. To display it use `actions` property. +`PlaceholderContainer` can render button controls or an array of buttons. To display it, use the `actions` property. @@ -58,7 +58,7 @@ The component can render button control or array of buttons. To display it use ` -It is also possible to render custom controls: +You can also render custom controls: @@ -111,7 +111,7 @@ It is also possible to render custom controls: ## Image and content -The property `image` allows to set up image `src` and `alt` settings or react node. +The `image` property enables configuring the image `src` and `alt` settings or a React node. @@ -144,7 +144,7 @@ The property `image` allows to set up image `src` and `alt` settings or react no /> ``` -with src and alt settings +With `src` and `alt` settings: ```tsx -The content of component contains from title and description blocks that can be set by the same properties names. To render custom content use `content` property. +The `PlaceholderContainer` content contains from the title and description sections, which you can set with the appropriate properties. To render custom content, use the `content` property. ```tsx `\| PlaceholderContainerImageProps` | | -| content | Used to render node instead of content (title, description and actions) | `React.ReactNode` | | -| actions | Used to render array of button controls or custom node | `PlaceholderContainerActionProps[]`
`\| React.ReactNode ` | | +| Name | Description | Type | Default | +| :---------- | :----------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------: | :--------: | +| className | `class` HTML attribute (optional) | `string` | | +| direction | Used to set the content layout direction. The possible values are `"row"` and `"column"`. | `string` | `"row"` | +| size | Component size. The possible values are `"s"`, `"m"`, `"l"`, and `"promo"`. | `string` | `"l"` | +| align | Used to set content horizontal alignment. The possible values are `"center"` and `"left"`. | `string` | `"center"` | +| title | Content title text | `string` | | +| description | Content description text | `string` | | +| image | Used to set an image by `src` or provide a React node | `PlaceholderContainerImageNodeProps`
`\| PlaceholderContainerImageProps` | | +| content | Used to render a node instead of content (title, description, and actions) | `React.ReactNode` | | +| actions | Used to render an array of button controls or a custom node | `PlaceholderContainerActionProps[]`
`\| React.ReactNode ` | | diff --git a/src/components/Popover/README-ru.md b/src/components/Popover/README-ru.md new file mode 100644 index 0000000000..666a1090b3 --- /dev/null +++ b/src/components/Popover/README-ru.md @@ -0,0 +1,300 @@ + + +# Popover + + + +```tsx +import {Popover} from '@gravity-ui/uikit'; +``` + +Компонент `Popover` позволяет добавить раздел с всплывающим содержимым. + +### Стандартное использование + + + + + +```tsx +Open a tooltip +``` + + + +### С JSX-контентом + + + + + +```tsx +}>Open a tooltip +``` + + + +### С HTML-контентом + + + + + +```tsx +html content. Learn more here' + } +> + Open a tooltip + +``` + + + +### Со ссылками + + + + + +```tsx + alert('The link is clicked'), + }, + ]} +> + Open a tooltip + +``` + + + +### С кнопкой действия + + + + + +```tsx + console.log('Action button was clicked'), + }} +> + Open a tooltip + +``` + + + +### С автоматическим закрытием, когда курсор находится вне области в течение `delayClosing` + + + + + +```tsx + console.log('Action button was clicked'), + }} +> + Open a tooltip + +``` + + + +## Использование экземпляра + +```tsx +import {Popover, PopoverInstanceProps} from '@gravity-ui/uikit'; + +const popoverRef = useRef(); + +const open = () => { + popoverRef.current?.openTooltip(); +}; + +const close = () => { + popoverRef.current?.closeTooltip(); +}; + +<> + + + +; +``` + +### Свойства экземпляра + +| Имя | Описание | Тип | Значение по умолчанию | +| ------------ | ------------------------------ | :--------: | :-------------------: | +| openTooltip | Открывает тултип `() => void`. | `Function` | | +| closeTooltip | Закрывает тултип `() => void`. | `Function` | | + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------: | :-------------------: | +| anchorRef | Элемент-якорь `Popper.js`, который также может быть `popper.VirtualElement`. | [`PopupAnchorRef`](../Popup/README.md#anchor) | | +| autoclosable | Включает или отключает автоматическое закрытие тултипа при выходе курсора за его пределы. | `boolean` | `true` | +| autoFocus | Если установлено значение `true`, фокус будет перемещен на первый элемент при открытии компонента `Popover`. | `boolean` | | +| behavior | Поведение тултипа при его открытии или закрытии с использованием `openOnHover`: `"immediate"` — без каких-либо задержек, `"delayed"` — с задержкой 300 мс при открытии и закрытии, `"delayedClosing"` — с задержкой 300 мс только при закрытии. Это свойство не будет работать, если заданы `delayOpening` или `delayClosing`. | `"immediate"` `"delayed"` `"delayedClosing"` | `"delayed"` | +| children | Контент, который служит триггером для отображаемого над ним тултипа. Может принимать значения функции `(triggerProps: `[`TriggerProps`](#triggerprops))` => React.ReactNode` или `ReactNode`. | `React.ReactNode` `Function` | | +| className | CSS-класс контрола. | `string` | | +| content | Содержимое тултипа. | `React.ReactNode` | | +| contentClassName | CSS-класс для `content`. | `string` | | +| delayClosing | Пользовательская задержка закрытия, если задано свойство `autoclosable`. | `number` | | +| delayOpening | Пользовательская задержка открытия, если задано свойство `openOnHover`. | `number` | | +| disabled | Отключает возможность изменения состояния открытия. | `boolean` | `false` | +| disablePortal | Отключает рендеринг компонента `Popover` в портале. | `boolean` | `false` | +| focusTrap | Не допускает выхода фокуса за пределы `Popover`, пока он открыт. | `boolean` | | +| forceLinksAppearance | Принудительно применяет стили к ссылкам. | `boolean` | `false` | +| hasArrow | Включает или отключает стрелку тултипа. | `boolean` | `true` | +| hasClose | Включает или отключает кнопку закрытия тултипа. | `boolean` | `false` | +| htmlContent | HTML-содержимое тултипа, которое будет отрисовано с помощью `dangerouslySetInnerHTML`. | `string` | | +| initialOpen | Включает или отключает автоматическое открытие тултипа при загрузке. | `boolean` | `false` | +| links | Ссылки под содержимым. | `[`[`LinkProps`](#linksprops)`]` | | +| offset | Смещение контрола. | `{top: number, left: number}` | | +| onClick | Обратный вызов при клике по элементу-якорю — `(event: React.MouseEvent) => boolean \| Promise`. Если функция возвращает `true`, тултип откроется; в противном случае — нет. | `Function` | | +| onCloseClick | Обработчик клика по кнопке закрытия — `(event: React.MouseEvent) => void`. | `Function` | | +| onOpenChange | Обработчик изменения состояния открытия — `(open: boolean) => void`. Может использоваться для задержки рендеринга содержимого тултипа. | `Function` | | +| openOnHover | Включает или отключает открытие тултипа по ховеру. | `boolean` | `true` | +| placement | Размещение `Popper.js`. | [`PopupPlacement`](../Popup/README.md#placement) | `["right", "bottom"]` | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | +| restoreFocusRef | Элемент, на который возвращается фокус при закрытии `Popover`. | `React.RefObject` | | +| size | Размер тултипа. | `"s"` `"l"` | `"s"` | +| strategy | [Стратегия](https://popper.js.org/docs/v2/constructors/#strategy) позиционирования `Popper.js`. | `"absolute"` `"fixed"` | `"absolute"` | +| title | Заголовок тултипа. | `string` | | +| theme | Тема тултипа. | `"info"` `"special"` `"announcement"` | `"info"` | +| tooltipActionButton | Свойства кнопки действия. Кнопка не будет отрисована, если не задать это свойство. | [`PopoverButtonProps`](#popoverbuttonprops) | | +| tooltipCancelButton | Свойства кнопки отмены. Кнопка не будет отрисована, если не задать это свойство. | [`PopoverButtonProps`](#popoverbuttonprops) | | +| tooltipClassName | CSS-класс тултипа. | `string` | | +| tooltipContentClassName | CSS-класс содержимого тултипа. | `string` | | +| tooltipOffset | Смещение тултипа относительно контрола. | `[number, number]` | | +| tooltipId | HTML-атрибут `id` для компонента `Popover`. | `string` | | + +### TriggerProps + +| Имя | Описание | Тип | Значение по умолчанию | +| --------- | ------------------------------ | :--------------------------: | :-------------------: | +| onClick | Обработчик события клика. | `React.MouseEventHandler` | | +| onKeyDown | Обработчик события клавиатуры. | `React.KeyboardEventHandler` | | + +### LinkProps + +| Имя | Описание | Тип | Значение по умолчанию | +| ------- | ---------------------------------------------------------------------------------- | :------------------: | :-------------------: | +| text | Текст ссылки. | `string` | | +| href | Атрибут ссылки `href`. | `string` | | +| target | Определяет, где откроется ссылка. | `"_self"` `"_blank"` | | +| onClick | Обработчик события клика — `(event: React.MouseEvent) => void`. | `Function` | | + +### PopoverButtonProps + +| Имя | Описание | Тип | Значение по умолчанию | +| ------- | --------------------------------------------------------------- | :--------: | :-------------------: | +| text | Текст на кнопке. | `string` | | +| onClick | Обработчик события клика — `(event: React.MouseEvent) => void`. | `Function` | | + +| Имя | Описание | +| :---------------------- | :---------------------------- | +| `--g-popover-padding` | Отступы контента. | +| `--g-popover-max-width` | Максимальная ширина контента. | diff --git a/src/components/Popover/README.md b/src/components/Popover/README.md index 774303d967..e61468f7c7 100644 --- a/src/components/Popover/README.md +++ b/src/components/Popover/README.md @@ -8,7 +8,7 @@ import {Popover} from '@gravity-ui/uikit'; ``` -Block with pop-up content +This component allows you to add a section with some pop-up content. ### Simple usage @@ -173,7 +173,7 @@ LANDING_BLOCK--> -### With automatic closing when cursor is outside for `delayClosing` +### With automatic closing when the cursor is outside for `delayClosing` + +# Popover + + + +```tsx +import {Popover} from '@gravity-ui/uikit'; +``` + +Компонент `Popover` позволяет добавить раздел с всплывающим содержимым. + +### Стандартное использование + + + + + +```tsx +Open a tooltip +``` + + + +### С JSX-контентом + + + + + +```tsx +}>Open a tooltip +``` + + + +### С HTML-контентом + + + + + +```tsx +html content. Learn more here' + } +> + Open a tooltip + +``` + + + +### Со ссылками + + + + + +```tsx + alert('The link is clicked'), + }, + ]} +> + Open a tooltip + +``` + + + +### С кнопкой действия + + + + + +```tsx + console.log('Action button was clicked'), + }} +> + Open a tooltip + +``` + + + +### С автоматическим закрытием, когда курсор находится вне области в течение `delayClosing` + + + + + +```tsx + console.log('Action button was clicked'), + }} +> + Open a tooltip + +``` + + + +## Использование экземпляра + +```tsx +import {Popover, PopoverInstanceProps} from '@gravity-ui/uikit'; + +const popoverRef = useRef(); + +const open = () => { + popoverRef.current?.openTooltip(); +}; + +const close = () => { + popoverRef.current?.closeTooltip(); +}; + +<> + + + +; +``` + +### Свойства экземпляра + +| Имя | Описание | Тип | Значение по умолчанию | +| ------------ | ------------------------------ | :--------: | :-------------------: | +| openTooltip | Открывает тултип `() => void`. | `Function` | | +| closeTooltip | Закрывает тултип `() => void`. | `Function` | | + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------: | :-------------------: | +| anchorRef | Элемент-якорь `Popper.js`, который также может быть `popper.VirtualElement`. | [`PopupAnchorRef`](../Popup/README.md#anchor) | | +| autoclosable | Включает или отключает автоматическое закрытие тултипа при выходе курсора за его пределы. | `boolean` | `true` | +| autoFocus | Если установлено значение `true`, фокус будет перемещен на первый элемент при открытии компонента `Popover`. | `boolean` | | +| behavior | Поведение тултипа при его открытии или закрытии с использованием `openOnHover`: `"immediate"` — без каких-либо задержек, `"delayed"` — с задержкой 300 мс при открытии и закрытии, `"delayedClosing"` — с задержкой 300 мс только при закрытии. Это свойство не будет работать, если заданы `delayOpening` или `delayClosing`. | `"immediate"` `"delayed"` `"delayedClosing"` | `"delayed"` | +| children | Контент, который служит триггером для отображаемого над ним тултипа. Может принимать значения функции `(triggerProps: `[`TriggerProps`](#triggerprops))` => React.ReactNode` или `ReactNode`. | `React.ReactNode` `Function` | | +| className | CSS-класс контрола. | `string` | | +| content | Содержимое тултипа. | `React.ReactNode` | | +| contentClassName | CSS-класс для `content`. | `string` | | +| delayClosing | Пользовательская задержка закрытия, если задано свойство `autoclosable`. | `number` | | +| delayOpening | Пользовательская задержка открытия, если задано свойство `openOnHover`. | `number` | | +| disabled | Отключает возможность изменения состояния открытия. | `boolean` | `false` | +| disablePortal | Отключает рендеринг компонента `Popover` в портале. | `boolean` | `false` | +| focusTrap | Не допускает выхода фокуса за пределы `Popover`, пока он открыт. | `boolean` | | +| forceLinksAppearance | Принудительно применяет стили к ссылкам. | `boolean` | `false` | +| hasArrow | Включает или отключает стрелку тултипа. | `boolean` | `true` | +| hasClose | Включает или отключает кнопку закрытия тултипа. | `boolean` | `false` | +| htmlContent | HTML-содержимое тултипа, которое будет отрисовано с помощью `dangerouslySetInnerHTML`. | `string` | | +| initialOpen | Включает или отключает автоматическое открытие тултипа при загрузке. | `boolean` | `false` | +| links | Ссылки под содержимым. | `[`[`LinkProps`](#linksprops)`]` | | +| offset | Смещение контрола. | `{top: number, left: number}` | | +| onClick | Обратный вызов при клике по элементу-якорю — `(event: React.MouseEvent) => boolean \| Promise`. Если функция возвращает `true`, тултип откроется; в противном случае — нет. | `Function` | | +| onCloseClick | Обработчик клика по кнопке закрытия — `(event: React.MouseEvent) => void`. | `Function` | | +| onOpenChange | Обработчик изменения состояния открытия — `(open: boolean) => void`. Может использоваться для задержки рендеринга содержимого тултипа. | `Function` | | +| openOnHover | Включает или отключает открытие тултипа по ховеру. | `boolean` | `true` | +| placement | Размещение `Popper.js`. | [`PopupPlacement`](../Popup/README.md#placement) | `["right", "bottom"]` | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | +| restoreFocusRef | Элемент, на который возвращается фокус при закрытии `Popover`. | `React.RefObject` | | +| size | Размер тултипа. | `"s"` `"l"` | `"s"` | +| strategy | [Стратегия](https://popper.js.org/docs/v2/constructors/#strategy) позиционирования `Popper.js`. | `"absolute"` `"fixed"` | `"absolute"` | +| title | Заголовок тултипа. | `string` | | +| theme | Тема тултипа. | `"info"` `"special"` `"announcement"` | `"info"` | +| tooltipActionButton | Свойства кнопки действия. Кнопка не будет отрисована, если не задать это свойство. | [`PopoverButtonProps`](#popoverbuttonprops) | | +| tooltipCancelButton | Свойства кнопки отмены. Кнопка не будет отрисована, если не задать это свойство. | [`PopoverButtonProps`](#popoverbuttonprops) | | +| tooltipClassName | CSS-класс тултипа. | `string` | | +| tooltipContentClassName | CSS-класс содержимого тултипа. | `string` | | +| tooltipOffset | Смещение тултипа относительно контрола. | `[number, number]` | | +| tooltipId | HTML-атрибут `id` для компонента `Popover`. | `string` | | + +### TriggerProps + +| Имя | Описание | Тип | Значение по умолчанию | +| --------- | ------------------------------ | :--------------------------: | :-------------------: | +| onClick | Обработчик события клика. | `React.MouseEventHandler` | | +| onKeyDown | Обработчик события клавиатуры. | `React.KeyboardEventHandler` | | + +### LinkProps + +| Имя | Описание | Тип | Значение по умолчанию | +| ------- | ---------------------------------------------------------------------------------- | :------------------: | :-------------------: | +| text | Текст ссылки. | `string` | | +| href | Атрибут ссылки `href`. | `string` | | +| target | Определяет, где откроется ссылка. | `"_self"` `"_blank"` | | +| onClick | Обработчик события клика — `(event: React.MouseEvent) => void`. | `Function` | | + +### PopoverButtonProps + +| Имя | Описание | Тип | Значение по умолчанию | +| ------- | --------------------------------------------------------------- | :--------: | :-------------------: | +| text | Текст на кнопке. | `string` | | +| onClick | Обработчик события клика — `(event: React.MouseEvent) => void`. | `Function` | | + +| Имя | Описание | +| :---------------------- | :---------------------------- | +| `--g-popover-padding` | Отступы контента. | +| `--g-popover-max-width` | Максимальная ширина контента. | diff --git a/src/components/Popup/README.md b/src/components/Popup/README.md index aa0208e512..a0a4c9c76f 100644 --- a/src/components/Popup/README.md +++ b/src/components/Popup/README.md @@ -8,13 +8,12 @@ import {Popup} from '@gravity-ui/uikit'; ``` -`Popup` can be used to display floating content above the page. It is a wrapper around [Popper.js](https://popper.js.org) -with some defaults. To manage `Popup` visibility, use the `open` property. +You can use a `Popup` to display floating content above the page. Technically, it is a wrapper around [Popper.js](https://popper.js.org) with some default values. To manage `Popup` visibility, use the `open` property. The `Popup` child components are rendered inside the [`Portal`](../Portal) component. To disable this behavior, use the `disablePortal` property. ## Anchor -Ref object of the DOM element is passed to the `anchorRef` property to create a `Popper.js` instance. +Ref object of the DOM element is provided to the `anchorRef` property to create a `Popper.js` instance. ## Properties -| Name | Description | Type | Default | -| :------------------- | :--------------------------------------------------------------------------------- | :--------------------------------------: | :------------------------------: | -| altBoundary | `altBoundary` parameter for `Popper.js` `offset` modifier | `boolean` | `false` | -| anchorRef | `Popper.js` anchor element. Can also be `popper.VirtualElement` | `PopupAnchorRef` | | -| autoFocus | While open, the focus will be set to the first interactive element in the content | `boolean` | `false` | -| children | Any React content | `React.ReactNode` | | -| className | HTML `class` attribute for root node | `string` | | -| container | DOM element children to be mounted to | `HTMLElement` | `document.body` | -| contentClassName | HTML `class` attribute for content node | `string` | | -| disableEscapeKeyDown | Do not trigger close on `Esc` | `boolean` | `false` | -| disableLayer | Do not use `LayerManager` on stacking popups | `boolean` | `false` | -| disableOutsideClick | Do not trigger close on outside clicks | `boolean` | `false` | -| disablePortal | Do not use `Portal` for children | `boolean` | `false` | -| focusTrap | Enable focus trapping behavior | `boolean` | `false` | -| hasArrow | Render an arrow pointing to the anchor | `boolean` | `false` | -| id | HTML `id` attribute | `string` | | -| keepMounted | `Popup` will not be removed from the DOM upon hiding | `boolean` | `false` | -| modifiers | `Popper.js` modifiers in addition to default: `arrow`, `offset`, `flip` | `Array` | `[0, 4]` | -| offset | `Popper.js` offset | `[number, number]` | `[0, 4]` | -| onBlur | `blur` event handler | `Function` | | -| onClose | Handle `Popup` close event | `Function` | | -| onEnterKeyDown | `Enter` press event handler | `Function` | | -| onEscapeKeyDown | `Esc` press event handler | `Function` | | -| onFocus | `focus` event handler | `Function` | | -| onMouseEnter | `mouseenter` event handler | `Function` | | -| onMouseLeave | `mouseleave` event handler | `Function` | | -| onOutsideClick | Outside click event handler | `Function` | | -| onTransitionEnter | On start open popup animation | `Function` | | -| onTransitionEntered | On finish open popup animation | `Function` | | -| onTransitionExit | On start close popup animation | `Function` | | -| onTransitionExited | On finish close popup animation | `Function` | | -| open | Manages `Popup` visibility | `boolean` | `false` | -| placement | `Popper.js` placement | `PopupPlacement` `Array` | | -| qa | Test attribute (`data-qa`) | `string` | | -| restoreFocus | If true, the focus will return to the anchor element | `boolean` | `false` | -| restoreFocusRef | Element the focus will be restored to | `React.RefObject` | | -| aria-labelledby | `aria-labelledby` attribute, prefer this attribute if you have visible caption | `string` | | -| aria-label | `aria-label` attribute, use this attribute only if you didn't have visible caption | `string` | | -| aria-modal | The `aria-modal` attribute indicates whether an element is modal when displayed. | `Booleanish` | value of `focusTrap` | -| role | The accessibility role for popup | `string` | `dialog` if `aria-modal` is true | -| strategy | `Popper.js` positioning strategy | `popper.PositioningStrategy` | `[0, 4]` | -| style | HTML `style` attribute for root node | `string` | | +| Name | Description | Type | Default | +| :------------------- | :---------------------------------------------------------------------------------- | :--------------------------------------: | :------------------------------: | +| altBoundary | `altBoundary` parameter for the `Popper.js` `offset` modifier | `boolean` | `false` | +| anchorRef | `Popper.js` anchor element that can also be `popper.VirtualElement` | `PopupAnchorRef` | | +| autoFocus | While open, the focus will be set to the first interactive element in the content | `boolean` | `false` | +| children | Any React content | `React.ReactNode` | | +| className | `class` HTML attribute for the root node | `string` | | +| container | DOM element children to mount | `HTMLElement` | `document.body` | +| contentClassName | `class` HTML attribute for the content node | `string` | | +| disableEscapeKeyDown | Disables triggering close on `Esc` | `boolean` | `false` | +| disableLayer | Disables using `LayerManager` on stacking popups | `boolean` | `false` | +| disableOutsideClick | Disables triggering close on outside clicks | `boolean` | `false` | +| disablePortal | Disables using `Portal` for children | `boolean` | `false` | +| focusTrap | Enables focus trapping behavior | `boolean` | `false` | +| hasArrow | Renders arrow pointing to the anchor | `boolean` | `false` | +| id | `id` HTML attribute | `string` | | +| keepMounted | `Popup` will not be removed from the DOM upon hiding | `boolean` | `false` | +| modifiers | `Popper.js` modifiers in addition to the default one: `arrow`, `offset`, and `flip` | `Array` | `[0, 4]` | +| offset | `Popper.js` offset | `[number, number]` | `[0, 4]` | +| onBlur | `blur` event handler | `Function` | | +| onClose | Handles `Popup` close event | `Function` | | +| onEnterKeyDown | `Enter` press event handler | `Function` | | +| onEscapeKeyDown | `Esc` press event handler | `Function` | | +| onFocus | `focus` event handler | `Function` | | +| onMouseEnter | `mouseenter` event handler | `Function` | | +| onMouseLeave | `mouseleave` event handler | `Function` | | +| onOutsideClick | Outside click event handler | `Function` | | +| onTransitionEnter | Open popup animation on start | `Function` | | +| onTransitionEntered | Open popup animation on finish | `Function` | | +| onTransitionExit | Close popup animation on start | `Function` | | +| onTransitionExited | Close popup animation on finish | `Function` | | +| open | Manages `Popup` visibility | `boolean` | `false` | +| placement | `Popper.js` placement | `PopupPlacement` `Array` | | +| qa | Test attribute (`data-qa`) | `string` | | +| restoreFocus | If true, the focus will return to the anchor element | `boolean` | `false` | +| restoreFocusRef | Element the focus will be restored to | `React.RefObject` | | +| aria-labelledby | `aria-labelledby` attribute. Preferable if you have visible caption | `string` | | +| aria-label | `aria-label` attribute. Use it only if you do not have any visible caption | `string` | | +| aria-modal | Shows whether an element is modal when displayed | `Booleanish` | `focusTrap` value | +| role | Accessibility role for popup | `string` | `dialog` if `aria-modal` is true | +| strategy | `Popper.js` positioning strategy | `popper.PositioningStrategy` | `[0, 4]` | +| style | `style` HTML attribute for root node | `string` | | ## CSS API diff --git a/src/components/Portal/README-ru.md b/src/components/Portal/README-ru.md new file mode 100644 index 0000000000..88786ffcc6 --- /dev/null +++ b/src/components/Portal/README-ru.md @@ -0,0 +1,36 @@ + + +# Portal + + + +```tsx +import {Portal} from '@gravity-ui/uikit'; +``` + +`Portal` — утилитный компонент, который представляет собой простую обертку для [`createPortal`](https://react.dev/reference/react-dom/createPortal) в React и позволяет рендерить дочерние элементы в DOM-узле за пределами родительского компонента. + +## Контейнер + +По умолчанию `Portal` рендерит дочерние элементы в `document.body`. Это можно поменять в свойстве `container`. +Кроме того, можно задать контейнер для всех порталов в поддереве React с помощью компонента `PortalProvder`. + +```tsx +import {Portal, PortalProvider} from '@gravity-ui/uikit' + +const myRoot = document.getElementById('my-root'); + +This is rendered inside document.body +This is rendered inside #my-root node + + This is also rendered inside #my-root + +``` + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :------------ | :------------------------------------------------------------------------------------------------ | :---------------: | :-------------------: | +| children | Любое содержимое React. | `React.ReactNode` | | +| container | DOM-элемент, в который монтируются дочерние элементы. | `HTMLElement` | `document.body` | +| disablePortal | Если установлено значение `true`, дочерние элементы будут рендериться в стандартной иерархии DOM. | `boolean` | | diff --git a/src/components/Portal/README.md b/src/components/Portal/README.md index adb82adf0f..58085f1248 100644 --- a/src/components/Portal/README.md +++ b/src/components/Portal/README.md @@ -8,13 +8,12 @@ import {Portal} from '@gravity-ui/uikit'; ``` -`Portal` is a utility component, a simple wrapper around React [`createPortal`](https://react.dev/reference/react-dom/createPortal) -that allows you to render children into a DOM node outside the parent component. +`Portal` is a utility component. Basically, it is a simple wrapper around React's [`createPortal`](https://react.dev/reference/react-dom/createPortal) that allows you to render children into a DOM node outside the parent component. ## Container -By default, `Portal` renders its children into `document.body`; however, it can be changed with the `container` property. -Additionally, a container can be provided to all `Portal`s in the React subtree using the `PortalProvder` component. +By default, `Portal` renders its children into `document.body`; however, you can change this with the `container` property. +Additionally, you can provide a container to all `Portal`s in the React subtree using the `PortalProvder` component. ```tsx import {Portal, PortalProvider} from '@gravity-ui/uikit' @@ -30,8 +29,8 @@ const myRoot = document.getElementById('my-root'); ## Properties -| Name | Description | Type | Default | -| :------------ | :---------------------------------------------------- | :---------------: | :-------------: | -| children | Any React content | `React.ReactNode` | | -| container | DOM element children to be mounted | `HTMLElement` | `document.body` | -| disablePortal | If true, renders children within normal DOM hierarchy | `boolean` | | +| Name | Description | Type | Default | +| :------------ | :------------------------------------------------------------- | :---------------: | :-------------: | +| children | Any React content | `React.ReactNode` | | +| container | DOM element's children to mount | `HTMLElement` | `document.body` | +| disablePortal | If true, renders the children within the normal DOM hierarchy. | `boolean` | | diff --git a/src/components/Portal/__stories__/README.md b/src/components/Portal/__stories__/README.md new file mode 100644 index 0000000000..58085f1248 --- /dev/null +++ b/src/components/Portal/__stories__/README.md @@ -0,0 +1,36 @@ + + +# Portal + + + +```tsx +import {Portal} from '@gravity-ui/uikit'; +``` + +`Portal` is a utility component. Basically, it is a simple wrapper around React's [`createPortal`](https://react.dev/reference/react-dom/createPortal) that allows you to render children into a DOM node outside the parent component. + +## Container + +By default, `Portal` renders its children into `document.body`; however, you can change this with the `container` property. +Additionally, you can provide a container to all `Portal`s in the React subtree using the `PortalProvder` component. + +```tsx +import {Portal, PortalProvider} from '@gravity-ui/uikit' + +const myRoot = document.getElementById('my-root'); + +This is rendered inside document.body +This is rendered inside #my-root node + + This is also rendered inside #my-root + +``` + +## Properties + +| Name | Description | Type | Default | +| :------------ | :------------------------------------------------------------- | :---------------: | :-------------: | +| children | Any React content | `React.ReactNode` | | +| container | DOM element's children to mount | `HTMLElement` | `document.body` | +| disablePortal | If true, renders the children within the normal DOM hierarchy. | `boolean` | | diff --git a/src/components/Progress/README-ru.md b/src/components/Progress/README-ru.md new file mode 100644 index 0000000000..4e50dbd5ef --- /dev/null +++ b/src/components/Progress/README-ru.md @@ -0,0 +1,267 @@ + + +# Progress + + + +```tsx +import {Progress} from '@gravity-ui/uikit'; +``` + +Компонент `Progress` отображает текущий ход выполнения операции. Может быть разбит на секции. + +## Тема + +С помощью свойства `theme` можно настроить цвет всего прогресса или его составной части: + + + + + +```tsx + + + + + + +``` + + + +## Состояния + + + + + +```tsx + +``` + + + +## Размер + +Размер `Progress` можно настроить с помощью свойства `size`. Возможные значения: `"xs"`, `"s"` и `"m"`. Свойство `text` поддерживает только размер `"m"`. + + + + + +```tsx + + + +``` + + + +## Брейкпоинты + +Для установки брейкпоинтов в компоненте `Progress` используется свойство `colorStops`. + + + + + +```tsx + + + +``` + + + +## Стек + + + + + +```tsx + + +``` + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------: | :-------------------: | +| className | HTML-атрибут `class`. | `string` | | +| colorStops | Задает брейкпоинты с темами. | ` Array<{theme: string; stop: number;}>` | | +| colorStopsValue | Устанавливает значение для выбора текущей точки остановки цвета или альтернативное значение для `colorStops`. Диапазон значений — от 0 до 100. | `number` | | +| loading | Включает или отключает состояние `loading`. | `boolean` | `false` | +| size | Задает размер прогресс-бара. Отображение текста доступно только при размере `"m"`. | `string` | `"m"` | +| stack | Конфигурация составного прогресс-бара. Необязательное свойство, если указано `value`. | ` Array` | | +| stackClassName | HTML-атрибут `name` для стека. | `string` | | +| text | Текст внутри прогресс-бара. | `string` | | +| theme | Задает цвет прогресса. | `string` | `"default"` | +| value | Текущее значение прогресса. Диапазон значений — от 0 до 100. Свойство `stack` является необязательным и используется как `maxValue`. | `number` | | + +### `Stack` + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------- | :----------------------------------------------------------------------------------------------------------------------------------- | :---------: | :-------------------: | +| className | HTML-атрибут `class` для элемента стека. | `string` | | +| color | Задает цвет фона в HTML-атрибуте `style`. | `string` | | +| content | Содержимое элемента стека. | `ReactNode` | | +| title | HTML-атрибут `title`. | `string` | | +| theme | Задает цвет элемента стека. | `string` | `"default"` | +| value | Текущее значение прогресса. Диапазон значений — от 0 до 100. Свойство `stack` является необязательным и используется как `maxValue`. | `number` | | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | + +## API CSS + +| Имя | Описание | +| :------------------------------------- | :-------------------------------------------- | +| `--g-progress-empty-text-color` | Цвет текста для пустого `Progress`. | +| `--g-progress-filled-text-color` | Цвет текста для заполненной части `Progress`. | +| `--g-progress-empty-background-color` | Цвет фона для пустого `Progress`. | +| `--g-progress-filled-background-color` | Цвет текста для заполненной части `Progress`. | diff --git a/src/components/Progress/README.md b/src/components/Progress/README.md index 7eac4d0319..b968191de6 100644 --- a/src/components/Progress/README.md +++ b/src/components/Progress/README.md @@ -8,11 +8,11 @@ import {Progress} from '@gravity-ui/uikit'; ``` -`Progress` component indicates current operation progress. It can also be divided into sections. +The `Progress` component shows current operation progress. It can also be divided into sections. ## Theme -Use `theme` property to specify color of the whole progress or the composite part. +Use the `theme` property to specify color of the whole progress or the composite part: ## Breakpoints -To set breakpoints of the `Progress` component use the `colorStops` property. +Use the `colorStops` property to set breakpoints of the `Progress` component. ## Properties -| Name | Description | Type | Default | -| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------: | :---------: | -| className | HTML `class` attribute | `string` | | -| colorStops | Sets breakpoints with themes | `Array<{theme: string; stop: number;}>` | | -| colorStopsValue | Sets the value for choosing the current stop or alternative value for colorStops. The available range is from 0 to 100. | `number` | | -| loading | Toggles the `loading` state | `boolean` | `false` | -| size | Sets the progress bar size. The progress bar text can only be displayed in `"m"` size. | `string` | `"m"` | -| stack | Configuration of composite progress bar. Not required if a `value` is provided. | `Array` | | -| stackClassName | HTML `class` attribute of stack | `string` | | -| text | Text inside the progress bar | `string` | | -| theme | Sets progress color | `string` | `"default"` | -| value | Current progress value. The available range is from 0 to 100. Using the `stack` property value is optional and is used as maxValue. | `number` | | +| Name | Description | Type | Default | +| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------: | :---------: | +| className | `class` HTML attribute | `string` | | +| colorStops | Sets breakpoints with themes | `Array<{theme: string; stop: number;}>` | | +| colorStopsValue | Sets the value for choosing the current stop or an alternative value for `colorStops`. The available range is from 0 to 100. | `number` | | +| loading | Toggles the `loading` state | `boolean` | `false` | +| size | Sets the progress bar size. The progress bar text can only be displayed in `"m"` size. | `string` | `"m"` | +| stack | Configuration of composite progress bar. Not required if a `value` is provided. | `Array` | | +| stackClassName | `class` HTML attribute of stack | `string` | | +| text | Text inside the progress bar | `string` | | +| theme | Sets the progress color | `string` | `"default"` | +| value | Current progress value. The available range is from 0 to 100. Using the `stack` property value is optional and is used as `maxValue`. | `number` | | ### `Stack` -| Name | Description | Type | Default | -| :-------- | :---------------------------------------------------------------------------------------------------------------------------------- | :---------: | :---------: | -| className | HTML `class` attribute of the stack element | `string` | | -| color | Sets background color for the HTML `style` attribute | `string` | | -| content | Stack element content | `ReactNode` | | -| title | HTML `title` attribute | `string` | | -| theme | Sets the stack element color | `string` | `"default"` | -| value | Current progress value. The available range is from 0 to 100. Using the `stack` property value is optional and is used as maxValue. | `number` | | -| qa | HTML `data-qa` attribute, used in tests | `string` | | +| Name | Description | Type | Default | +| :-------- | :------------------------------------------------------------------------------------------------------------------------------------ | :---------: | :---------: | +| className | `class` HTML attribute of the stack element | `string` | | +| color | Sets the background color for the `style` HTML attribute | `string` | | +| content | Stack element content | `ReactNode` | | +| title | `title` HTML attribute | `string` | | +| theme | Sets the stack element color | `string` | `"default"` | +| value | Current progress value. The available range is from 0 to 100. Using the `stack` property value is optional and is used as `maxValue`. | `number` | | +| qa | `data-qa` HTML attribute, used for testing | `string` | | ## CSS API diff --git a/src/components/Radio/README-ru.md b/src/components/Radio/README-ru.md new file mode 100644 index 0000000000..0bc54b2685 --- /dev/null +++ b/src/components/Radio/README-ru.md @@ -0,0 +1,153 @@ + + +# Radio + + + +```tsx +import {Radio} from '@gravity-ui/uikit'; +``` + +Компонент `Radio` позволяет пользователям выбрать один вариант из списка. + +## Состояния + +`Radio` поддерживает следующие состояния: + +- Checked — радио выбрано. +- Disabled — радио недоступно для выбора. + + + + + +```tsx + + + +``` + + + +## Размер + +Размер `Radio` можно настроить с помощью свойства `size`. Размер по умолчанию — `m`. + + + + + +```tsx + + +``` + + + +## Лейбл + +Лейбл для `Radio` можно задать через свойство `content` или передать его как дочерний элемент. + + + + + +```tsx +
+ +
+ + Content as children + +
+
+``` + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :------------- | :------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------: | :-------------------: | +| children | Содержимое радио (как правило, лейбл). | `ReactNode` | | +| content | Содержимое радио (альтернатива `children`). | `ReactNode` | | +| disabled | Включает или отключает состояние `disabled` у радио. | `boolean` | `false` | +| checked | Включает или отключает состояние `checked` у радио. | `boolean` | `false` | +| defaultChecked | Задает начальное состояние `checked` при монтировании компонента. | `boolean` | `false` | +| onUpdate | Срабатывает при изменении состояния радио пользователем и передает значение `checked` как аргумент обратного вызова. | `(checked: boolean) => void` | | +| onChange | Срабатывает при изменении состояния радио пользователем и передает событие изменения как аргумент обратного вызова. | `Function` | | +| onFocus | Обработчик события, вызываемый, когда элемент ввода радио получает фокус. | `Function` | | +| onBlur | Обработчик события, вызываемый, когда элемент ввода радио теряет фокус. | `Function` | | +| size | Определяет размер радио. | `m` `l` | `m` | +| id | HTML-атрибут `id`. | `string` | | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | +| style | HTML-атрибут `style`. | `React.CSSProperties` | | +| className | HTML-атрибут `class`. | `string` | | +| title | HTML-атрибут `title`. | `string` | | +| name | HTML-атрибут `name` для элемента ввода. | `string` | | +| value | Значение контрола. | `string` | | +| indeterminate | Включает или отключает состояние неопределенности радио. | `boolean` | `false` | +| controlProps | Дополнительные свойства базового элемента ввода. | `React.InputHTMLAttributes` | | +| controlRef | Ссылка на базовый элемент ввода. | `React.Ref` | | diff --git a/src/components/Radio/README.md b/src/components/Radio/README.md index de3cd3811f..15a058aba8 100644 --- a/src/components/Radio/README.md +++ b/src/components/Radio/README.md @@ -12,7 +12,7 @@ The `Radio` component allows the users to select a single option from a list of ## States -Radio can have the following states: +`Radio` can have the following states: - Checked: Radio is selected. - Disabled: Radio is unavailable for selection. @@ -72,7 +72,7 @@ LANDING_BLOCK--> ## Label -You can set a label for the `Radio` component using the `content` property or pass it as a child property. +You can assign a label to a `Radio` using the `content` property or provide it as a child property. ## Properties -| Name | Description | Type | Default | -| :------------- | :------------------------------------------------------------------------------------------------ | :-------------------------------------------: | :-----: | -| children | The content of the radio (usually a label). | `ReactNode` | | -| content | The content of the radio (alternative to children). | `ReactNode` | | -| disabled | Toggles the `disabled` state of the radio. | `boolean` | `false` | -| checked | Toggles the checked state of the radio. | `boolean` | `false` | -| defaultChecked | Sets the initial checked state when the component is mounted. | `boolean` | `false` | -| onUpdate | Fires when the radio state is changed by the user. Provides checked value as a callback argument. | `(checked: boolean) => void` | | -| onChange | Fires when the radio state is changed by the user. Provides change event as a callback argument. | `Function` | | -| onFocus | Event handler used when the radio input element receives focus. | `Function` | | -| onBlur | Event handler used when the radio input element loses focus. | `Function` | | -| size | Sets the size of the radio. | `m` `l` | `m` | -| id | HTML `id` attribute | `string` | | -| qa | HTML `data-qa` attribute, used for testing. | `string` | | -| style | HTML `style` attribute | `React.CSSProperties` | | -| className | HTML `class` attribute | `string` | | -| title | HTML `title` attribute | `string` | | -| name | HTML `name` attribute for the input element. | `string` | | -| value | Control value | `string` | | -| indeterminate | Toggles the indeterminate state of the radio. | `boolean` | `false` | -| controlProps | Additional props for the underlying input element. | `React.InputHTMLAttributes` | | -| controlRef | Ref to the underlying input element. | `React.Ref` | | +| Name | Description | Type | Default | +| :------------- | :------------------------------------------------------------------------------------------------------- | :-------------------------------------------: | :-----: | +| children | The content of the radio (usually, a label). | `ReactNode` | | +| content | The content of the radio (alternative to children). | `ReactNode` | | +| disabled | Toggles the `disabled` state of the radio. | `boolean` | `false` | +| checked | Toggles the `checked` state of the radio. | `boolean` | `false` | +| defaultChecked | Sets the initial checked state when the component is mounted | `boolean` | `false` | +| onUpdate | Fires when the radio state is changed by the user and provides the checked value as a callback argument. | `(checked: boolean) => void` | | +| onChange | Fires when the radio state is changed by the user and provides the change event as a callback argument. | `Function` | | +| onFocus | Event handler to use when the radio input element receives focus. | `Function` | | +| onBlur | Event handler to use when the radio input element loses focus. | `Function` | | +| size | Sets the size of the radio. | `m` `l` | `m` | +| id | `id` HTML attribute | `string` | | +| qa | `data-qa` HTML attribute, used for testing. | `string` | | +| style | `style` HTML attribute | `React.CSSProperties` | | +| className | `class` HTML attribute | `string` | | +| title | `title` HTML attribute | `string` | | +| name | `name` HTML attribute for the input element | `string` | | +| value | Control value | `string` | | +| indeterminate | Toggles the indeterminate state of the radio. | `boolean` | `false` | +| controlProps | Additional propeties for the underlying input element | `React.InputHTMLAttributes` | | +| controlRef | Ref to the underlying input element | `React.Ref` | | diff --git a/src/components/RadioButton/README-ru.md b/src/components/RadioButton/README-ru.md new file mode 100644 index 0000000000..b72ebec334 --- /dev/null +++ b/src/components/RadioButton/README-ru.md @@ -0,0 +1,279 @@ + + +# RadioButton + + + +```tsx +import {RadioButton} from '@gravity-ui/uikit'; +``` + +Компонент `RadioButton` используется для создания группы кнопок с зависимой фиксацией (т.н. «радиокнопок»), где пользователи могут выбрать только один вариант из нескольких предложенных. + +### Отключенное состояние + + + + + +```tsx +const options: RadioButtonOption[] = [ + {value: 'Value 1', content: 'Value 1'}, + {value: 'Value 2', content: 'Value 2'}, + {value: 'Value 3', content: 'Value 3'}, +]; +; +``` + + + +### Размер + +Размер `RadioButton` можно настроить с помощью свойства `size`. Размер по умолчанию — `m`. + + + + + +```tsx + const options: RadioButtonOption[] = [ + {value: 'Value 1', content: 's'}, + {value: 'Value 2', content: 'm'}, + {value: 'Value 3', content: 'l'}, + {value: 'Value 4', content: 'xl'}, + ]; + + + + +``` + + + +### Ширина + +Ширину `RadioButton` можно настроить с помощью свойства `width`. + + + + + +```tsx +
+
+ + + + +
+
+ + + + +
+
+ + + + +
+
+``` + + + +### Свойства + +| Имя | Описание | Тип | По умолчанию | +| :----------- | :------------------------------------------------------------------------------------------------------------------------ | :-----------------------: | :----------: | +| children | Содержимое радиокнопки. | `ReactNode` | | +| disabled | Включает или отключает состояние `disabled` у радиокнопки. | `boolean` | `false` | +| options | Опции радиокнопки. | `RadioButtonOption[]` | | +| defaultValue | Задает начальное значение состояния компонента при его монтировании. | `string` | | +| onUpdate | Срабатывает при изменении состояния радиокнопки пользователем и передает новое значение как аргумент обратного вызова. | `(value: string) => void` | | +| onChange | Срабатывает при изменении состояния радиокнопки пользователем и передает событие изменения как аргумент обратного вызова. | `Function` | | +| onFocus | Обработчик события, вызываемый, когда элемент ввода радио получает фокус. | `Function` | | +| onBlur | Обработчик события, вызываемый, когда элемент ввода радио теряет фокус. | `Function` | | +| width | Определяет ширину радиокнопки. | `auto - max` | | +| size | Определяет размер радиокнопки. | `s` `m` `l` `xl` | `m` | +| name | HTML-атрибут `name` для элемента ввода. | `string` | | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | +| style | HTML-атрибут `style`. | `React.CSSProperties` | | +| className | HTML-атрибут `class`. | `string` | | + +## RadioButton.Option + +`RadioButton` также имеет вложенный компонент `Option`. Его можно использовать для создания вариантов радиокнопок внутри `RadioButton`. + + + + + +```tsx +const options: RadioButtonOption[] = [ + {value: 'Value 1', content: 'Value 1'}, + {value: 'Value 2', content: 'Value 2'}, + {value: 'Value 3', content: 'Value 3'}, +]; + + + + +; +``` + + + +### Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :------- | :--------------------------------------------------- | :---------: | :-------------------: | +| children | Содержимое радио (как правило, лейбл). | `ReactNode` | | +| content | Содержимое радио (альтернатива `children`). | `ReactNode` | | +| disabled | Включает или отключает состояние `disabled` у радио. | `boolean` | `false` | +| value | Значение контрола. | `string` | | diff --git a/src/components/RadioButton/README.md b/src/components/RadioButton/README.md index 547a8a61e0..ddf17f9c4e 100644 --- a/src/components/RadioButton/README.md +++ b/src/components/RadioButton/README.md @@ -50,7 +50,7 @@ const options: RadioButtonOption[] = [ ### Size -To control the size of the `RadioButton`, use the `size` property. The default size is `m`. +Use the `size` property to manage the `RadioButton` size. The default size is `m`. ### Width -To control the width of the `RadioButton`, use the `width` property. +Use the `width` property to manage the `RadioButton` width: ### Properties -| Name | Description | Type | Default | -| :----------- | :--------------------------------------------------------------------------------------------------- | :-----------------------: | :-----: | -| children | The content of the radio button. | `ReactNode` | | -| disabled | Toggles the `disabled` state of the radio button. | `boolean` | `false` | -| options | Options for radio button. | `RadioButtonOption[]` | | -| defaultValue | Sets the initial value state when the component is mounted. | `string` | | -| onUpdate | Fires when the user changes the radio button state. Provides the new value as a callback's argument. | `(value: string) => void` | | -| onChange | Fires when the user changes the radio button state. Provides change event as a callback's argument. | `Function` | | -| onFocus | Event handler for when the radio input element receives focus. | `Function` | | -| onBlur | Event handler for when the radio input element loses focus. | `Function` | | -| width | Sets the width of the radio button. | `auto - max` | | -| size | Sets the size of the radio button. | `s` `m` `l` `xl` | `m` | -| name | HTML `name` attribute for the input element. | `string` | | -| qa | HTML `data-qa` attribute, used in tests. | `string` | | -| style | HTML `style` attribute | `React.CSSProperties` | | -| className | HTML `class` attribute | `string` | | +| Name | Description | Type | Default | +| :----------- | :------------------------------------------------------------------------------------------------------- | :-----------------------: | :-----: | +| children | Content of the radio button. | `ReactNode` | | +| disabled | Toggles the `disabled` state of the radio button. | `boolean` | `false` | +| options | Options for radio button. | `RadioButtonOption[]` | | +| defaultValue | Sets the initial value state when the component is mounted. | `string` | | +| onUpdate | Fires when the user changes the radio button state and provides the new value as a callback argument. | `(value: string) => void` | | +| onChange | Fires when the user changes the radio button state and provides the change event as a callback argument. | `Function` | | +| onFocus | Event handler to use when the radio input element receives focus. | `Function` | | +| onBlur | Event handler to use when the radio input element loses focus. | `Function` | | +| width | Sets the width of the radio button. | `auto - max` | | +| size | Sets the size of the radio button. | `s` `m` `l` `xl` | `m` | +| name | `name` HTML attribute for the input element. | `string` | | +| qa | `data-qa` HTML attribute, used for testing | `string` | | +| style | `style` HTML attribute | `React.CSSProperties` | | +| className | `class` HTML attribute | `string` | | ## RadioButton.Option -The `RadioButton` component also exports a nested `Option` component. You can use it to create radio button options within the `RadioButton`. +The `RadioButton` component also exports a nested `Option` component. You can use it to create radio button options within a `RadioButton`. + +# RadioGroup + + + +```tsx +import {RadioGroup} from '@gravity-ui/uikit'; +``` + +Компонент `RadioGroup` (радиогруппа) используется для создания группы, где пользователи могут выбрать только один вариант из нескольких предложенных. + +### Отключенное состояние + + + + + +```tsx +const options: RadioGroupOption[] = [ + {value: 'Value 1', content: 'Value 1'}, + {value: 'Value 2', content: 'Value 2'}, + {value: 'Value 3', content: 'Value 3'}, +]; +; +``` + + + +### Размер + +Размер `RadioGroup` можно настроить с помощью свойства `size`. Размер по умолчанию — `m`. + + + + + +```tsx + const options: RadioGroupOption[] = [ + {value: 'Value 1', content: 'Value 1'}, + {value: 'Value 2', content: 'Value 2'}, + {value: 'Value 3', content: 'Value 3'}, + ]; + + +``` + + + +### Направление + +Направление расположения `RadioGroup` можно настроить с помощью свойства `direction`. Направление по умолчанию — `horizontal`. + + + + + +```tsx + const options: RadioGroupOption[] = [ + {value: 'Value 1', content: 'Value 1'}, + {value: 'Value 2', content: 'Value 2'}, + {value: 'Value 3', content: 'Value 3'}, + ]; + + +``` + + + +### Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------------- | :------------------------------------------------------------------------------------------------------------------ | :-----------------------: | :-------------------: | +| children | Содержимое радиогруппы. | `ReactNode` | | +| disabled | Включает или отключает состояние `disabled` у радиогруппы. | `boolean` | `false` | +| options | Варианты для радиогруппы. | `RadioGroupOption[]` | | +| optionClassName | HTML-атрибут `class` для дочерних элементов радиогруппы. | `string` | | +| direction | Определяет направление расположения радиогруппы. | `horizontal - vertical` | `"horizontal"` | +| defaultValue | Задает начальное значение состояния компонента при его монтировании. | `string` | | +| onUpdate | Срабатывает при изменении состояния радио пользователем и передает новое значение как аргумент обратного вызова. | `(value: string) => void` | | +| onChange | Срабатывает при изменении состояния радио пользователем и передает событие изменения как аргумент обратного вызова. | `Function` | | +| size | Определяет размер радиогруппы. | `m` `l` | `m` | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | +| style | HTML-атрибут `style`. | `React.CSSProperties` | | +| className | HTML-атрибут `class`. | `string` | | + +## RadioGroup.Option + +`RadioGroup` также имеет вложенный компонент `Option`, который является эквивалентом `Radio` и может быть использован для создания вариантов радио в рамках `RadioGroup`. + + + + + +```tsx +const options: RadioGroupOption[] = [ + {value: 'Value 1', content: 'Value 1'}, + {value: 'Value 2', content: 'Value 2'}, + {value: 'Value 3', content: 'Value 3'}, +]; + + + + +; +``` + + + +### Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :------- | :--------------------------------------------------- | :---------: | :-------------------: | +| children | Содержимое радио (как правило, лейбл). | `ReactNode` | | +| content | Содержимое радио (альтернатива `children`). | `ReactNode` | | +| disabled | Включает или отключает состояние `disabled` у радио. | `boolean` | `false` | +| value | Значение контрола. | `string` | | diff --git a/src/components/RadioGroup/README.md b/src/components/RadioGroup/README.md index be2cf09d20..25c9234c3c 100644 --- a/src/components/RadioGroup/README.md +++ b/src/components/RadioGroup/README.md @@ -50,7 +50,7 @@ const options: RadioGroupOption[] = [ ### Size -To control the size of the `RadioGroup`, use the `size` property. The default size is `m`. +Use the `size` property to manage the `RadioGroup` size. The default size is `m`. ### Direction -To control the direction of the `RadioGroup`, use the `direction` property. The default direction is `horizontal`. +Use the `direction` property to manage the `RadioGroup` direction. The default direction is `horizontal`. ### Properties -| Name | Description | Type | Default | -| :-------------- | :----------------------------------------------------------------------------------------------- | :-----------------------: | :------------: | -| children | The content of the radio group. | `ReactNode` | | -| disabled | Toggles the `disabled` state of the radio group. | `boolean` | `false` | -| options | Options for radio group. | `RadioGroupOption[]` | | -| optionClassName | HTML `class` attribute for the radio children. | `string` | | -| direction | Sets the direction of the radio group. | `horizontal - vertical` | `"horizontal"` | -| defaultValue | Sets the initial value state when the component is mounted. | `string` | | -| onUpdate | Fires when the user changes the radio state. Provides the new value as a callback's argument. | `(value: string) => void` | | -| onChange | Fires when the user changes the radio state. Provides the change event as a callback's argument. | `Function` | | -| size | Sets the size of the radio group. | `m` `l` | `m` | -| qa | HTML `data-qa` attribute, used in tests. | `string` | | -| style | HTML `style` attribute | `React.CSSProperties` | | -| className | HTML `class` attribute | `string` | | +| Name | Description | Type | Default | +| :-------------- | :------------------------------------------------------------------------------------------------ | :-----------------------: | :------------: | +| children | The content of the radio group. | `ReactNode` | | +| disabled | Toggles the `disabled` state of the radio group. | `boolean` | `false` | +| options | Options for radio group. | `RadioGroupOption[]` | | +| optionClassName | `class` HTML attribute for the radio children. | `string` | | +| direction | Determines the direction of the radio group. | `horizontal - vertical` | `"horizontal"` | +| defaultValue | Sets the initial value state when the component is mounted. | `string` | | +| onUpdate | Fires when the user changes the radio state and provides the new value as a callback argument. | `(value: string) => void` | | +| onChange | Fires when the user changes the radio state and provides the change event as a callback argument. | `Function` | | +| size | Determines the size of the radio group. | `m` `l` | `m` | +| qa | `data-qa` HTML attribute, used for testing | `string` | | +| style | `style` HTML attribute | `React.CSSProperties` | | +| className | `class` HTML attribute | `string` | | ## RadioGroup.Option -The `RadioGroup` component also exports a nested `Option` component equivalent to the `Radio` component, which can be used to create radio options within the `RadioGroup`. +The `RadioGroup` component also exports a nested `Option` component equivalent to `Radio`, which can be used to create radio options within the `RadioGroup`. + +# Select + + + +```tsx +import {Select} from '@gravity-ui/uikit'; +``` + +Компонент `Select` — это контрол, который предоставляет список вариантов для выбора. + +## `Options` (варианты) + +Варианты для выбора. + +### Определение вариантов + +Варианты можно определять в виде массива объектов или в качестве дочерних элементов компонента. Первый способ подходит для случаев, когда варианты требуют сложной подготовки и, возможно, запоминания. Второй способ удобен, когда вариантов немного и их настройка не требует сложных вычислений. + +#### Одноуровневый список + + + + + +```tsx +// Array of objects + + Value 1 + Value 2 + Value 3 + Value 4 + +``` + + + +#### Группированный список + + + + + +```tsx +// Array of objects + + + + + + + + + + +``` + + + +### Хранение данных в вариантах + +С помощью свойства `option.data` можно определить и сохранить уникальные данные в каждом варианте. Это может быть полезно при необходимости обогащения данных с использованием обратного вызова `onUpdate` или, например, при отрисовке вариантов с помощью `renderOption`. + +## Выбор нескольких вариантов + +Чтобы включить множественный выбор, используйте свойство `multiple`. Значение по умолчанию — `false`. + + + + + +```tsx + +``` + + + +### Счетчик + +С помощью свойства `hasCounter` в компонент можно добавить счетчик выбранных вариантов. + + + + + +```tsx + +``` + + + +## Варианты фильтрации + +Для активации секции фильтрации используйте свойство `filterable`. Значение по умолчанию — `false`. + + + + + +```tsx + +``` + + + +## Размер + +Чтобы задать дефолтный размер контролов и вариантов, используйте свойство `size`. Размер по умолчанию — `m`. + + + + + +```tsx + + + + +``` + + + +## Ширина контрола + +По умолчанию ширина контрола растягивается, чтобы соответствовать ширине содержимого выбранных вариантов. Вы можете самостоятельно регулировать ширину с помощью свойства `width`: + +`'max'` — растягивает ширину контрола на всю ширину родительского элемента. + +`number` — применяет ширину в пикселях. + + + +## Ширина всплывающего окна. + +Ширину всплывающего окна можно изменять с помощью свойства `popupWidth`. Возможные значения: + +`'fit'` — применяет ширину контрола. + +`number` — применяет ширину в пикселях. + +Особенности поведения по умолчанию: + +- Ширина всплывающего окна соответствует ширине самого широкого варианта, но не превышает `90vw`. Это не применимо, если используется [виртуализация](#virtualized-list). + +- Узкие варианты растягиваются до ширины контрола. + + + +### Виртуализированный список + +Для оптимального отображения большого количества вариантов в компоненте `Select`предусмотрен встроенный инструмент виртуализации списка. Виртуализация включается, когда количество вариантов превышает пороговое значение (по умолчанию `50`). Пороговое значение можно изменить с помощью свойства `virtualizationThreshold`. + +При включении виртуализации к элементу всплывающего окна применяются определенные ограничения: + +- Ширина всплывающего окна больше не изменяется в зависимости от длины самого длинного варианта. + +- Минимальная ширина всплывающего окна равна ширине контрола или `100px`, если ширина контрола меньше `100px`. + + + +## Расширенное использование + +Существует множество способов настроить `Select` более тонко. + +### Рендеринг пользовательского контрола + +Для создания пользовательского контрола используйте свойство `renderControl`. +Обратите внимание, что для правильной работы контрола необходимо передать все аргументы в узел (как при использовании стандартной конфигурации). + + + + + +```tsx +import {Button} from '@gravity-ui/uikit'; + +const MyComponent = () => { + const renderControl: SelectProps['renderControl'] = ({onClick, onKeyDown, ref}) => { + return ( + + ); + }; + + return ; +}; +``` + + + +### Отображение секции пользовательской фильтрации + +Для отображения секции пользовательской фильтрации используйте свойство `renderFilter` и установите `filterable` в значение `true`. +Обратите внимание, что для правильной работы фильтра необходимо передать все аргументы в узел (как при использовании стандартной конфигурации). + + + + + +```tsx +import {Button, TextInput} from '@gravity-ui/uikit'; +import type {SelectProps} from '@gravity-ui/uikit'; + +const MyComponent = () => { + const renderFilter: SelectProps['renderFilter'] = (props) => { + const {value, ref, onChange, onKeyDown} = props; + + return ( +
+ + +
+ ); + }; + + return ( + + ); +}; +``` + + + +### Отображение пользовательских вариантов + +Для отображения пользовательских вариантов используйте свойство `renderOption`: + + + + + +```tsx +import type {SelectProps} from '@gravity-ui/uikit'; + +const MyComponent = () => { + const renderOption: SelectProps['renderOption'] = (option) => { + return
{option.children}
; + }; + + return ( + + ); +}; +``` + + + +### Отображение выбранных пользовательских вариантов + +Для отображения выбранных пользовательских вариантов используйте свойство `renderOption`: + + + + + +```tsx +import type {SelectProps} from '@gravity-ui/uikit'; + +const MyComponent = () => { + const renderSelectedOption: SelectProps['renderSelectedOption'] = (option) => { + return
{option.children}
; + }; + + return ( + + ); +}; +``` + + + +### Отображение вариантов с разной высотой + +Варианты имеют фиксированную высоту, заданную в свойстве `size`. Если нужно отобразить варианты с разной высотой, используйте свойство `option.data`, которое будет содержать информацию о требуемой высоте варианта, а также `getOptionHeight` для установки этого значения. + + + + + +```tsx +import type {SelectProps} from '@gravity-ui/uikit'; + +const MyComponent = () => { + const getOptionHeight: SelectProps['getOptionHeight'] = (option) => option.data.height; + + return ( + + ); +}; +``` + + + +### Отображение пользовательских всплывающих окон + +Для отображения пользовательских всплывающих окон используйте свойство `renderPopup`. + + + + + +```tsx +import type {SelectProps} from '@gravity-ui/uikit'; + +const renderPopup: SelectProps['renderPopup'] = ({renderList, renderFilter}) => { + return ( + + {renderFilter()} +
+ {renderList()} + + ); +}; + +const MyComponent = () => { + return ( + + ); +}; +``` + + + +### `Error` (ошибка) + +Это состояние `Select` указывает на некорректный ввод данных пользователем. Для изменения внешнего представления `Select` примените свойство `validationState`, задав ему значение `"invalid"`. Опционально можно задать текст сообщения об ошибке через свойство `errorMessage`. По умолчанию текст сообщения выводится вне компонента. +Место вывода сообщения можно изменить с помощью свойства `errorPlacement`. + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- | :------------------------------------------------------- | +| className | Имя класса контрола. | `string` | | +| defaultValue | Значения по умолчанию для выбранных вариантов в случае использования неуправляемого состояния. | `string[]` | | +| disabled | Указывает на то, что пользователь не может взаимодействовать с контролом. | `boolean` | `false` | +| [filterable](#filtering-options) | Указывает на то, что всплывающее окно выбора содержит секцию фильтрации. | `boolean` | `false` | +| filterOption | Используется для сравнения варианта со значением фильтра. | `function` | | +| filterPlaceholder | Текст-заглушка по умолчанию для поля ввода фильтра. | `string` | | +| [getOptionHeight](#render-options-with-different-heights) | Используется для задания высоты пользовательских вариантов. | `function` | | +| getOptionGroupHeight | Используется для задания высоты группы пользовательских вариантов. | `function` | | +| hasClear | Позволяет отображать иконку для очистки выбранных вариантов. | `boolean` | `false` | +| id | HTML-атрибут `id`. | `string` | | +| label | Лейбл контрола. | `string` | | +| loading | Добавляет элемент загрузки в конец списка вариантов. Работает как постоянный индикатор загрузки, пока список вариантов пуст. | `boolean` | | +| [multiple](#selecting-multiple-options) | Указывает на наличие возможности выбора несколько вариантов в списке. | `boolean` | `false` | +| name | Имя контрола. | `string` | | +| onBlur | Обработчик, который вызывается, когда элемент теряет фокус. | `function` | | +| filter | Контролируемое значение фильтра. | `string` | `''` | +| onFilterChange | Срабатывает при каждом изменении фильтра. | `function` | | +| onFocus | Обработчик, который вызывается, когда элемент получает фокус. | `function` | | +| onLoadMore | Срабатывает, когда индикатор загрузки становится видимым. | `function` | | +| onOpenChange | Срабатывает при каждом изменении видимости всплывающего окна. | `function` | | +| onUpdate | Срабатывает, когда пользователь подтверждает изменение значения `Select`. | `function` | | +| [options](#options) | Варианты для выбора. | `(SelectOption \| SelectOptionGroup)[]` | | +| pin | Вид границ контрола. | `string` | `'round-round'` | +| placeholder | Текст-заглушка. | `string` | | +| popupClassName | Имя класса (`className`) для всплывающего окна со списком вариантов. | `string` | | +| popupPlacement | Размещение `Popper.js`. | `PopupPlacement` `Array` | `['bottom-start', 'bottom-end', 'top-start', 'top-end']` | +| [popupWidth](#popup-width) | Ширина всплывающего окна. | `number \| 'fit' \| 'outfit'` | `'outfit'` | +| qa | Атрибут идентификатора для тестирования (`data-qa`). | `string` | | +| [renderControl](#render-custom-control) | Используется для рендеринга пользовательского контрола. | `function` | | +| renderEmptyOptions | Используется для рендеринга узла для пустого списка вариантов. | `function` | | +| [renderFilter](#render-custom-filter-section) | Используется для рендеринга секции пользовательской фильтрации. | `function` | | +| [renderOption](#render-custom-options) | Используется для рендеринга пользовательских вариантов. | `function` | | +| renderOptionGroup | Используется для рендеринга групп пользовательских вариантов. | `function` | | +| [renderSelectedOption](#render-custom-selected-options) | Используется для рендеринга выбранных пользователем вариантов. | `function` | | +| [renderPopup](#render-custom-popup) | Используется для рендеринга содержимого пользовательского всплывающего окна. | `function` | | +| [size](#size) | Размер контрола / вариантов. | `string` | `'m'` | +| value | Значения для выбранных вариантов. | `string[]` | | +| view | Вид контрола. | `string` | `'normal'` | +| [virtualizationThreshold](#virtualized-list) | Порог количества вариантов, после которого включается виртуализация. | `number` | `50` | +| [width](#control-width) | Ширина контрола | `string \| number` | `undefined` | +| errorMessage | Текст ошибки. | `string` | | +| errorPlacement | Положение отображения ошибки. | `outside` `inside` | `outside` | +| validationState | Состояние валидации. | `"invalid"` | | +| [hasCounter](#counter) | Показывает количество выбранных вариантов. Счетчик появляется только тогда, когда включен [множественный](#selecting-multiple-options) выбор. | `boolean` | + +## API CSS + +| Имя | Описание | +| :------------------------------- | :-------------------------------------------------------------- | +| `--g-select-focus-outline-color` | Цвет обводки при фокусе на элементе (по умолчанию отсутствует). | diff --git a/src/components/Select/README.md b/src/components/Select/README.md index cd5031273b..e576e84413 100644 --- a/src/components/Select/README.md +++ b/src/components/Select/README.md @@ -8,7 +8,7 @@ import {Select} from '@gravity-ui/uikit'; ``` -`Select` represents a control that provides a list of options that user can select. +`Select` is a control that provides a list of options that a user can select. ## Options @@ -16,7 +16,7 @@ Options to select. ### Defining options -You can define options as an array of objects or as the children of a component. The first approach is convenient for cases where options require complex preparation and possible memoization. The second approach is convenient when there are few options, and their configuration does not require complex calculations. +You can define options as an array of objects or as the children of a component. The first approach is useful for cases where options require complex preparation and, possibly, memorization. The second one is convenient when there are few options, and their configuration does not require complex calculations. #### Flat list @@ -200,11 +200,11 @@ LANDING_BLOCK--> ### Storing data in options -You can define and store uniq data in each option by using `option.data` property. This can be useful when you need to enrich the data when using the `onUpdate` callback or, for example, when drawing your options with `renderOption`. +You can define and store unique data in each option by using the `option.data` property. This can be useful when you need to enrich the data when using the `onUpdate` callback or, for example, when drawing your options with `renderOption`. ## Selecting multiple options -To enable multiple selection use the `multiple` property. Default to `false`. +To enable multiple selection, use the `multiple` property. Its default value is `false`. ### Counter -You can add counter of the selected items to the component by using property `hasCounter`. +You can add a counter of the selected items to the component using the `hasCounter` property. ## Filtering options -To enable filter section use the `filterable` property. Default to `false`. +To enable filter section, use the `filterable` property. Its default value is `false`. ## Size -To manage default contols and options sizes use the `size` property. Default value is `m`. +To manage the default control and option size, use the `size` property. Its default size is `m`. ## Control width -By default, the width of the control stretches to match the width of the content of the selected options. You can manage it by using `width` property: +By default, the control width stretches to match the width of the content of the selected options. You can manage it by using the `width` property: -`'max'` - stretches to the full width of the parent. +`'max'`: Stretches to the full width of the parent. -`number` - apply width in pixels. +`number`: Applies width in pixels. ## Popup width -Popup width managed by the `popupWidth` property. Available values: +You can manage the popup width with the `popupWidth` property. The available values are: -`'fit'` - apply control width. +`'fit'`: Apply control width. -`number` - apply width in pixels. +`number`: Apply width in pixels. -There are some points about default behaviour: +Points to note about the default behavior: -- The width of the popup is equal to the width of the widest option, but not wider than `90vw`. Does not work in case of using [virtualization](#virtualized-list). +- The popup width is equal to the width of the widest option, but not wider than `90vw`. This does not apply in case you use [virtualization](#virtualized-list). - Narrow options are stretched to fit the width of the control. @@ -562,11 +562,11 @@ LANDING_BLOCK--> ### Virtualized list -For optimal display of a large number of options, `Select` has a built-in list virtualization mechanism. Virtualization is enabled after overcoming the threshold of the number of options (`50` by default). You can control this value using the `virtualizationThreshold` property. +For optimal display of a large number of options, `Select` has a built-in list virtualization tool. Virtualization is enabled after overcoming the threshold of the number of options (`50` by default). You can manage this value using the `virtualizationThreshold` property. -When using virtualization, some restrictions are imposed on the popup element: +When using virtualization, some restrictions apply to the popup element: -- The popup width stops adjusting to the length of the longest option. +- The popup width no longer gets adjusted to the length of the longest option. - The minimum width of the popup is equal to the width of the control, or `100px` if the control is shorter. @@ -652,12 +652,12 @@ LANDING_BLOCK--> ## Advanced usage -There are many ways to add uniqueness to your `Select`. +There are many ways to customize your `Select`. -### Render custom control +### Rendering custom control -To render custom control use the `renderControl` property. -Notice: you should forward all arguments to your node in order to have consistent behavior as in the case of using default control. +To render a custom control, use the `renderControl` property. +Note: You should forward all arguments to your node in order to enable consistent behavior, just as when using the default control. -### Render custom filter section +### Rendering custom filter section -To render custom filter section use the `renderFilter` property and set `filterable` property to `true`. -Notice: you should forward all arguments to your node in order to have properly working filter as in the case of using default. +To render a custom filter section, use the `renderFilter` property and set the `filterable` property to `true`. +Note: You need to forward all arguments to your node in order to enable a properly working filter, just as when using the default configuration. -### Render custom options +### Rendering custom options -To render custom options use the `renderOption` property. +To render custom options, use the `renderOption` property: -### Render custom selected options +### Rendering custom selected options -To render custom selected options use the `renderSelectedOption` property. +To render custom selected options, use the `renderSelectedOption` property: -### Render options with different heights +### Rendering options with different heights -The options have a fixed height according to the `size` property. If you need to render options with different heights, you can use the `option.data` property, which will store information about what height you need to set the options and `getOptionHeight` property to set this value. +Options have a fixed height according to the `size` property. If you need to render options with different heights, you can use the `option.data` property. It will store information about what height you need to set for the options, as well as the `getOptionHeight` property to set this value. -### Render custom popup +### Rendering custom popup -To render custom popup use the `renderPopup` property. +To render custom popup, use the `renderPopup` property. ## Properties -| Name | Description | Type | Default | -| :-------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- | :------------------------------------------------------- | -| className | Control className | `string` | | -| defaultValue | Default values that represent selected options in case of using uncontrolled state | `string[]` | | -| disabled | Indicates that the user cannot interact with the control | `boolean` | `false` | -| [filterable](#filtering-options) | Indicates that select popup have filter section | `boolean` | `false` | -| filterOption | Used to compare option with filter | `function` | | -| filterPlaceholder | Default filter input placeholder text | `string` | | -| [getOptionHeight](#render-options-with-different-heights) | Used to set height of customized user options | `function` | | -| getOptionGroupHeight | Used to set height of customized user option group | `function` | | -| hasClear | Enable displaying icon for clear selected options | `boolean` | `false` | -| id | HTML `id` attribute | `string` | | -| label | Control label | `string` | | -| loading | Add the loading item to the end of the options list. Works like persistant loading indicator while the options list is empty. | `boolean` | | -| [multiple](#selecting-multiple-options) | Indicates that multiple options can be selected in the list | `boolean` | `false` | -| name | Name of the control | `string` | | -| onBlur | Handler that is called when the element loses focus. | `function` | | -| filter | Controlled filter value | `string` | `''` | -| onFilterChange | Fires every time after changing filter | `function` | | -| onFocus | Handler that is called when the element receives focus. | `function` | | -| onLoadMore | Fires when loading indicator gets visible. | `function` | | -| onOpenChange | Fires every time after changing popup visibility | `function` | | -| onUpdate | Fires when an alteration to the Select value is committed by the user | `function` | | -| [options](#options) | Options to select | `(SelectOption \| SelectOptionGroup)[]` | | -| pin | Control border view | `string` | `'round-round'` | -| placeholder | Placeholder text | `string` | | -| popupClassName | Popup with options list className | `string` | | -| popupPlacement | `Popper.js` placement | `PopupPlacement` `Array` | `['bottom-start', 'bottom-end', 'top-start', 'top-end']` | -| [popupWidth](#popup-width) | Popup width | `number \| 'fit' \| 'outfit'` | `'outfit'` | -| qa | Test id attribute (`data-qa`) | `string` | | -| [renderControl](#render-custom-control) | Used to render user control | `function` | | -| renderEmptyOptions | Used to render node for an empty options list | `function` | | -| [renderFilter](#render-custom-filter-section) | Used to render user filter section | `function` | | -| [renderOption](#render-custom-options) | Used to render user options | `function` | | -| renderOptionGroup | Used to render user option groups | `function` | | -| [renderSelectedOption](#render-custom-selected-options) | Used to render user selected options | `function` | | -| [renderPopup](#render-custom-popup) | Used to render user popup content | `function` | | -| [size](#size) | Control / options size | `string` | `'m'` | -| value | Values that represent selected options | `string[]` | | -| view | Control view | `string` | `'normal'` | -| [virtualizationThreshold](#virtualized-list) | The threshold of the options count after which virtualization is enabled | `number` | `50` | -| [width](#control-width) | Control width | `string \| number` | `undefined` | -| errorMessage | Error text | `string` | | -| errorPlacement | Error placement | `outside` `inside` | `outside` | -| validationState | Validation state | `"invalid"` | | -| [hasCounter](#counter) | Indicates count of the selected options. Counter appears only when [multiple](#selecting-multiple-options) selection enabled. state | `boolean` | +| Name | Description | Type | Default | +| :-------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- | :------------------------------------------------------- | +| className | Control className | `string` | | +| defaultValue | Default values that represent selected options in case of using an uncontrolled state | `string[]` | | +| disabled | Shows that the user cannot work with the control | `boolean` | `false` | +| [filterable](#filtering-options) | Shows that select popup has a filter section | `boolean` | `false` | +| filterOption | Used to compare option with filter | `function` | | +| filterPlaceholder | Default filter input placeholder text | `string` | | +| [getOptionHeight](#render-options-with-different-heights) | Used to set height of customized user options | `function` | | +| getOptionGroupHeight | Used to set height of customized user option group | `function` | | +| hasClear | Enables displaying icon for clearing selected options | `boolean` | `false` | +| id | `id` HTML attribute | `string` | | +| label | Control label | `string` | | +| loading | Adds the loading item to the end of the option list. Works like a persistent loading indicator while the options list is empty. | `boolean` | | +| [multiple](#selecting-multiple-options) | Shows whether multiple options can be selected in the list | `boolean` | `false` | +| name | Name of the control | `string` | | +| onBlur | Handler that is called when the element loses focus. | `function` | | +| filter | Controlled filter value | `string` | `''` | +| onFilterChange | Fires every time after changing the filter | `function` | | +| onFocus | Handler that is called when the element gets focus | `function` | | +| onLoadMore | Fires when the loading indicator gets visible | `function` | | +| onOpenChange | Fires every time after changing popup visibility | `function` | | +| onUpdate | Fires when an alteration to the `Select` value is committed by the user | `function` | | +| [options](#options) | Options to select | `(SelectOption \| SelectOptionGroup)[]` | | +| pin | Control border view | `string` | `'round-round'` | +| placeholder | Placeholder text | `string` | | +| popupClassName | Popup with the option list `className` | `string` | | +| popupPlacement | `Popper.js` placement | `PopupPlacement` `Array` | `['bottom-start', 'bottom-end', 'top-start', 'top-end']` | +| [popupWidth](#popup-width) | Popup width | `number \| 'fit' \| 'outfit'` | `'outfit'` | +| qa | Test id attribute (`data-qa`) | `string` | | +| [renderControl](#render-custom-control) | Used to render user control | `function` | | +| renderEmptyOptions | Used to render a node for an empty option list | `function` | | +| [renderFilter](#render-custom-filter-section) | Used to render user filter section | `function` | | +| [renderOption](#render-custom-options) | Used to render user options | `function` | | +| renderOptionGroup | Used to render user option groups | `function` | | +| [renderSelectedOption](#render-custom-selected-options) | Used to render user selected options | `function` | | +| [renderPopup](#render-custom-popup) | Used to render user popup content | `function` | | +| [size](#size) | Control / options size | `string` | `'m'` | +| value | Values that represent selected options | `string[]` | | +| view | Control view | `string` | `'normal'` | +| [virtualizationThreshold](#virtualized-list) | Option count threshold after which virtualization is enabled | `number` | `50` | +| [width](#control-width) | Control width | `string \| number` | `undefined` | +| errorMessage | Error text | `string` | | +| errorPlacement | Error position | `outside` `inside` | `outside` | +| validationState | Validation state | `"invalid"` | | +| [hasCounter](#counter) | Shows the selected option count. The counter appears only when the [multiple](#selecting-multiple-options) selection is enabled. | `boolean` | ## CSS API -| Name | Description | -| :------------------------------- | :-------------------------------------------------- | -| `--g-select-focus-outline-color` | Outline color if focused (by default not presented) | +| Name | Description | +| :------------------------------- | :-------------------------------------------- | +| `--g-select-focus-outline-color` | Outline color if focused (missing by default) | diff --git a/src/components/Sheet/README-ru.md b/src/components/Sheet/README-ru.md new file mode 100644 index 0000000000..212ad70e91 --- /dev/null +++ b/src/components/Sheet/README-ru.md @@ -0,0 +1,53 @@ + + +# Sheet + + + +```tsx +import {Sheet} from '@gravity-ui/uikit'; +``` + +Компонент `Sheet` (шторка) предназначен для использования в мобильных интерфейсах в качестве информационного или интерактивного элемента. Благодаря поддержке внутренней прокрутки и динамического изменения размеров в него можно помещать контент любого объема. + +На мобильных устройствах `Sheet` можно перемещать, потянув за его основную часть или область свайпа. Для закрытия нужно провести вниз или коснуться области вне `Sheet`. + +## Использование + +```tsx +import React from 'react'; +import {Button, Sheet} from '@gravity-ui/uikit'; + +const SheetExample = () => { + const [visible, setVisible] = React.useState(false); + + return ( + + + setVisible(false)} title="Content Sheet"> + Content + + + ); +}; +``` + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | :--------: | :-------------------: | +| visible | Управляет видимостью `Sheet`. | `boolean` | `false` | +| allowHideOnContentScroll | Включает возможность закрытия при свайпе вниз, если контент не прокручивается или прокручен до верха (`content Node.scrollTop === 0`). | `boolean` | `true` | +| hideTopBar | Скрывает верхнюю панель с элементом для изменения размера. | `boolean` | | +| id | Идентификатор `Sheet`, используемый как хеш в URL. Необходимо задать разные значения `id`, если на странице несколько `Sheet`. | `string` | `modal` | +| title | Заголовок окна `Sheet`. | `string` | `undefined` | +| className | HTML-атрибут `class`. | `string` | `undefined` | +| contentClassName | HTML-атрибут `class` для контента шторки. | `string` | `undefined` | +| swipeAreaClassName | HTML-атрибут `class` для области свайпа. | `string` | `undefined` | +| onClose | Обработчик события закрытия. | `function` | `undefined` | + +## API CSS + +| Имя | Описание | +| :-------------------------- | :---------------- | +| `--g-sheet-content-padding` | Отступы контента. | diff --git a/src/components/Sheet/README.md b/src/components/Sheet/README.md index 5f158767be..8f2e517dd8 100644 --- a/src/components/Sheet/README.md +++ b/src/components/Sheet/README.md @@ -8,9 +8,9 @@ import {Sheet} from '@gravity-ui/uikit'; ``` -`Sheet` is a component designed to be used in a mobile context as an information or interactive element. You can place content of any size in it - internal scrolling and dynamic resizing are supported. +`Sheet` is a component designed for using in the mobile context as an information or interactive element. You can place content of any size in it, since the internal scrolling and dynamic resizing are supported. -On mobile devices, you can move `Sheet` by pulling on its main part or the swipe area. To close it, swipe down or touch the area outside the `Sheet`. +On mobile devices, you can move a `Sheet` by pulling its main part or the swipe area. To close it, swipe down or tap the area outside the `Sheet`. ## Usage @@ -34,17 +34,17 @@ const SheetExample = () => { ## Properties -| Name | Description | Type | Default | -| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------: | :---------: | -| visible | Manages `Sheet` visibility | `boolean` | `false` | -| allowHideOnContentScroll | Enable the behavior of the sheet window closing by swiping down if the content is scrolled to its top (`content Node.scrollTop === 0`) or has no scroll at all | `boolean` | `true` | -| hideTopBar | Hide top bar with resize handle | `boolean` | | -| id | ID of the sheet, used as hash in URL. It's important to specify different `id` values if there can be more than one sheet on the page | `string` | `modal` | -| title | Title of the sheet window | `string` | `undefined` | -| className | HTML `class` attribute | `string` | `undefined` | -| contentClassName | HTML `class` attribute for the sheet content | `string` | `undefined` | -| swipeAreaClassName | HTML `class` attribute for the swipe area | `string` | `undefined` | -| onClose | Handler for close event | `function` | `undefined` | +| Name | Description | Type | Default | +| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------: | :---------: | +| visible | Manages `Sheet` visibility | `boolean` | `false` | +| allowHideOnContentScroll | Enables the behavior of closing the sheet window by swiping down if the content is scrolled to its top (`content Node.scrollTop === 0`) or has no scroll at all. | `boolean` | `true` | +| hideTopBar | Hides the top bar with the resize handle. | `boolean` | | +| id | Sheet ID used as hash in a URL. Make sure to specify multiple `id` values if there can be more than one sheet on a page. | `string` | `modal` | +| title | Sheet window title. | `string` | `undefined` | +| className | `class` HTML attribute | `string` | `undefined` | +| contentClassName | `class` HTML attribute for the sheet content. | `string` | `undefined` | +| swipeAreaClassName | `class` HTML attribute for the swipe area. | `string` | `undefined` | +| onClose | Handler for close event. | `function` | `undefined` | ## CSS API diff --git a/src/components/Skeleton/README-ru.md b/src/components/Skeleton/README-ru.md new file mode 100644 index 0000000000..5de4b74a4f --- /dev/null +++ b/src/components/Skeleton/README-ru.md @@ -0,0 +1,19 @@ + + +# Skeleton + + + +```tsx +import {Skeleton} from '@gravity-ui/uikit'; +``` + +Компонент `Skeleton` отображает временный макет контента, пока фактические данные загружаются. Такой предварительный макет используется для снижения раздражения, вызываемого ожиданием загрузки. + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------- | :----------------------------------------------------- | :-------------------: | :-------------------: | +| style | Пользовательские CSS-стили корневого элемента. | `React.CSSProperties` | | +| className | Пользовательский CSS-класс корневого элемента. | `string` | | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | diff --git a/src/components/Skeleton/README.md b/src/components/Skeleton/README.md index b861d20ba5..5c2e00922e 100644 --- a/src/components/Skeleton/README.md +++ b/src/components/Skeleton/README.md @@ -8,12 +8,12 @@ import {Skeleton} from '@gravity-ui/uikit'; ``` -The Skeleton component displays a placeholder preview of your content before the data loads in order to reduce load-time frustration. +The Skeleton component displays a placeholder preview of your content before the data gets loaded. This preview is shown in order to reduce the loading time frustration. ## Properties -| Name | Description | Type | Default | -| :-------- | :-------------------------------------- | :-------------------: | :-----: | -| style | Custom CSS properties for root element | `React.CSSProperties` | | -| className | Custom CSS class for root element | `string` | | -| qa | HTML `data-qa` attribute, used in tests | `string` | | +| Name | Description | Type | Default | +| :-------- | :----------------------------------------- | :-------------------: | :-----: | +| style | Custom CSS properties for root element | `React.CSSProperties` | | +| className | Custom CSS class for the root element | `string` | | +| qa | `data-qa` HTML attribute, used for testing | `string` | | diff --git a/src/components/Slider/README-ru.md b/src/components/Slider/README-ru.md new file mode 100644 index 0000000000..a625607127 --- /dev/null +++ b/src/components/Slider/README-ru.md @@ -0,0 +1,332 @@ + + +# Slider + + + +```tsx +import {Slider} from '@gravity-ui/uikit'; +``` + +`Slider` (слайдер) — это настраиваемый и отзывчивый React-компонент, который позволяет пользователям выбирать одно значение или диапазон значений из заданного набора данных. + +## Варианты слайдера + +### Одиночный слайдер + +Представляет собой слайдер с одним ползунком для выбора одного значения. Используется по умолчанию. + + + + + +```tsx + +``` + + + +### Слайдер диапазона + +Представляет собой слайдер с двумя ползунками для выбора диапазона. Для его использования необходимо задать `defaultValue` (для неконтролируемого компонента) или `value` (для контролируемого компонента) в виде массива. + + + + + +```tsx + +``` + + + +## Состояния + +### `Disabled` (отключен) + +Состояние `Slider`, при котором пользователь не может взаимодействовать с компонентом. + + + + + +```tsx + +``` + + + +### `Error` (ошибка) + +Состояние `Slider`, которое указывает на некорректный ввод данных пользователем. Для изменения внешнего представления `Slider` примените свойство `validationState`, задав ему значение `"invalid"`. Дополнительно через свойство `errorMessage` можно добавить текст сообщения, который будет отображаться под компонентом. + + + + + +```tsx + + +``` + + + +## Размер + +Для изменения размера `Slider` используйте свойство `size`. Размер по умолчанию — `m`. + + + + + +```tsx + + + + +``` + + + +## Значение + +### Минимальное и максимальное значения + +Свойства `min` и `max` определяют пределы диапазона, который может обрабатывать `Slider`. Эти свойства необходимы для установки границ выбираемых значений. + + + + + +```tsx + + + +``` + + + +### `Step` (шаг) + +Свойство `step` компонента `Slider` задает величину шага между минимальным и максимальным значениями. Оно контролирует изменение значения при перемещении ползунка. + + + + + +```tsx + +``` + + + +### Метки + +Свойство `marks` задает количество визуальных меток компонента `Slider`, указывающих на разные значения в диапазоне от минимума до максимума. Данное свойство делает слайдер более удобным для пользователя и улучшает его визуальное оформление, особенно в тех случаях, когда необходимо обозначить конкретные интервалы. Значение по умолчанию — 2 (`min` и `max`). Его можно использовать двумя способами: + +- Для задания количества визуальных меток на слайдере: + + + + +```tsx + +``` + + + +- Для указания массива значений меток на слайдере: + + + + + +```tsx + +``` + + + +Если в свойстве `marks` указать `0` или пустой массив (`[]`), то все метки компонента `Slider` будут скрыты. + + + + + +```tsx + +``` + + + +> Значение метки можно выбрать, даже если оно не соответствует шагу (`step`). + +Формат отображения значений меток можно изменить с помощью свойства `marksFormat`. + +#### Определение доступных значений + +Установка свойства `step` в `null` позволяет задать конкретные значения, которые будут доступны на слайдере, вместо непрерывного диапазона. Это особенно полезно в случаях, когда выбор возможен только из заранее определенных дискретных значений. При такой настройке свойства `min`, `max` и `marks` позволяют задать массив чисел, представляющих собой те значения, которые пользователи могут выбрать при работе с компонентом `Slider`. + + + + + +```tsx + +``` + + + +## Тултип + +Свойство `tooltipDisplay` в компоненте `Slider` управляет поведением отображения тултипа с текущим значением при взаимодействии пользователя со слайдером. Значение `auto` позволяет отображать тултип только при наведении курсора на ползунок компонента `Slider` или получении компонентом фокуса. + + + + + +```tsx + +``` + + + +Формат отображения значения тултипа можно изменить с помощью свойства `tooltipFormat`. Если не указать `tooltipformat`, то для отображения значения в тултипе будет использовано свойство `marksFormat`. + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------: | :-------------------: | +| apiRef | Ссылка на свойства `focus` and `blur` компонента `Slider`. | `RefObject` | | +| autoFocus | Атрибут `autofocus` для контрола. | `boolean` | | +| [availableValues](#define-available-values) | Устаревшее свойство; вместо него используйте `marks` и `step === null`. Задает массив доступных значений для слайдера. | `number[]` | | +| className | Имя класса обертки контрола. | `string` | | +| debounceDelay | Устаревшее свойство; используйте внешний дебаунсинг. Определяет задержку (в миллисекундах) перед вызовом функции обработки. | `number` | `0` | +| [defaultValue](#slider-variants) | Значение по умолчанию для контрола, используемое при неконтролируемом состоянии компонента. | `number` `[number, number]` | `0` | +| [disabled](#disabled) | Указывает на то, что пользователь не может взаимодействовать с контролом. | `boolean` | `false` | +| [errorMessage](#error) | Отображаемый текст ошибки. | `string` | | +| [hasTooltip](#tooltip) | Устаревшее свойство; вместо него используйте `tooltipDisplay`. Включает или отключает отображение тултипа с текущим значением компонента. | `boolean` | `false` | +| [marks](#marks) | Текстовые метки под слайдером. В данном свойстве можно задать количество меток или массив значений, для которых они должны отображаться. При указании `0` или `[]` метки не отображаются. | `number` `number[]` | `2` | +| [marksCount](#marks) | Устаревшее свойство; вместо него используйте `marks`. Количество меток под слайдером. Делит весь диапазон на равные части. Минимальное значение — `2`. Игнорируется, если задано `availablevalues` (устаревшее свойство). | `number` | `2` | +| [marksFormat](#marks) | Определяет форматирование отображаемого значения метки. | `(value: number) => string` | | +| [max](#min-and-max-value) | Максимальное значение компонента. | `number` | `100` | +| [min](#min-and-max-value) | Минимальное значение компонента. | `number` | `0` | +| onBlur | Срабатывает, когда контрол теряет фокус. Передает событие фокуса в качестве аргумента обратного вызова. | `((e: FocusEvent) => void)` | | +| onUpdate | Срабатывает, когда пользователь изменяет значение слайдера. Передает событие изменения в качестве аргумента обратного вызова. | `((value: number \| [number, number]) => void)` | | +| onUpdateComplete | Активируется при срабатывании события `ontouchend` (завершение касания) или `onmouseup` (отпускание кнопки мыши). Передает событие изменения в качестве аргумента обратного вызова. | `((value: number \| [number, number]) => void)` | | +| onFocus | Срабатывает, когда контрол получает фокус. Передает событие фокуса в качестве аргумента обратного вызова. | `((e: FocusEvent) => void)` | | +| [size](#size) | Размер контрола. | `"s"` `"m"` `"l"` `"xl"` | `"m"` | +| [step](#step) | Величина, на которую изменяется значение слайдера при каждом перемещении ползунка. Если установить значение `null`, в качестве шагов будет использоваться свойство `marks`. Игнорируется, если задано `availablevalues` (устаревшее свойство). | `number` `null` | `1` | +| tabIndex | Атрибут `tabIndex` для контрола. | `number` `[number, number]` | | +| [tooltipDisplay](#tooltip) | Управляет поведением отображения тултипа. | `off` `on` `auto` | `off` | +| [tooltipFormat](#tooltip) | Определяет форматирование отображаемого значения тултипа. Если значение не задано, используется `marksFormat`. | `(value: number) => string` | | +| [validationState](#error) | Состояние валидации. | `"invalid"` | | +| [value](#slider-variants) | Значение контрола. | `number` `[number, number]` | | diff --git a/src/components/Slider/README.md b/src/components/Slider/README.md index 81dcf851f0..163bdbfc9f 100644 --- a/src/components/Slider/README.md +++ b/src/components/Slider/README.md @@ -8,13 +8,13 @@ import {Slider} from '@gravity-ui/uikit'; ``` -Slider is a customizable and responsive React component that allows users to select a single value or a range of values from a specified data set. +The slider is a customizable and responsive React component that allows users to select a single value or a range of values from a specified data set. -## Slider variants +## Slider variations ### Single slider -Slider with one handle to select single value. This Slider is used by default. +This is a slider with one handle to select a single value. It is used by default. ### Range slider -Slider with two handles to select range. To use this slider you should set `defaultValue` (for uncontrolled) or `value` (for controlled) to array. +This is slider with two handles to select a range. To use it, set `defaultValue` (for an uncontrolled slider) or `value` (for a controlled one) for the array. ### Disabled -The state of the `Slider` where you don't want the user to be able to interact with the component. +This is a state of a `Slider` where you do not want to allow the user to work with this component. ### Error -The state of the `Slider` in which you want to indicate incorrect user input. To change `Slider` appearance, use the `validationState` property with the `"invalid"` value. An optional message text can be added via the `errorMessage` property. Error message text will be rendered under the component. +This `Slider` state is for incorrect user input. To change the `Slider` appearance, use the `validationState` property with the `"invalid"` value. Optionally, you can provide an error message through the `errorMessage` property. This message text will be rendered under the slider. ## Size -To control the size of the `Slider` use the `size` property. Default size is `m`. +Use the `size` property to manage the `Slider` size. The default size is `m`. ## Value -### Min and max value +### Minimum and maximum value -The `min` and `max` properties define the limits of the range that the `Slider` component can handle. These properties are essential for setting the boundaries of the selectable values. +The `min` and `max` properties define the limits of the range the `Slider` can handle. These properties are essential for setting the boundaries of the selectable values. ### Step -The `step` property for `Slider` component determines the incremental steps between the min and max value range. It controls how much the value should increase or decrease as the slider is moved. +The `step` property determines the increments within the minimum and maximum value range. This means how much the value changes with a single slider move. + +# Spin + + + +```tsx +import {Spin} from '@gravity-ui/uikit'; +``` + +`Spin` — это компонент, который отображает состояние загрузки (вращающийся полукруг) в инлайн-сценариях. В отличие от `Loader`, этот компонент применяется для отображения состояния загрузки в инлайн-контексте — например, в `Button` или `Label`. + +### Размер + + + + + +```tsx + + + + + +``` + + + +`XS` — очень маленький. + +`S` — маленький, применяется, когда спин среднего размера слишком велик. + +`M` — средний (базовый), используется в большинстве случаев. + +`L` — большой, применяется, когда спин среднего размера слишком мал. + +`XL` — очень большой. + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :-------- | :--------------------------------------------- | :-----------------------------: | :-------------------: | +| size | Размер спина. | `"xs"` `"s"` `"m"` `"l"` `"xl"` | `"m"` | +| style | Пользовательские CSS-стили корневого элемента. | `React.CSSProperties` | | +| className | Пользовательский CSS-класс корневого элемента. | `string` | | +| qa | Атрибут тестирования (`data-qa`). | `string` | | diff --git a/src/components/Spin/README.md b/src/components/Spin/README.md index 089b03ef16..954c65915d 100644 --- a/src/components/Spin/README.md +++ b/src/components/Spin/README.md @@ -8,7 +8,7 @@ import {Spin} from '@gravity-ui/uikit'; ``` -The Spin component indicates the loading state (a rotating semicircle) in inline scenarios. Unlike Loader, this component is used to display the loading state in inline scenarios, e.g., in Button or Label. +The `Spin` component displays the loading state (a rotating semicircle) in inline scenarios. Unlike `Loader`, this component is used to display the loading state in inline scenarios, e.g., in a `Button` or `Label`. ### Size @@ -42,21 +42,21 @@ LANDING_BLOCK--> -XS - The smallest size. +`XS`: Extra small. -S – Small, used when standard spin is too large. +`S`: Small, used when a medium-sized spin is too large. -M – Medium (basic), used in most cases. +`M`: Medium (basic), used in most cases. -L – Large, used when standard spin is too small. +`L`: Large, used when a medium-sized spin is too small. -XL - The largest size. +`XL`: Extra large. ## Properties -| Name | Description | Type | Default | -| :-------- | :--------------------------------- | :-----------------------------: | :-----: | -| size | Spin size | `"xs"` `"s"` `"m"` `"l"` `"xl"` | `"m"` | -| style | Custom CSS styles for root element | `React.CSSProperties` | | -| className | Custom CSS class for root element | `string` | | -| qa | Test attribute (`data-qa`) | `string` | | +| Name | Description | Type | Default | +| :-------- | :------------------------------------ | :-----------------------------: | :-----: | +| size | Spin size | `"xs"` `"s"` `"m"` `"l"` `"xl"` | `"m"` | +| style | Custom CSS styles for root element | `React.CSSProperties` | | +| className | Custom CSS class for the root element | `string` | | +| qa | Test attribute (`data-qa`) | `string` | | diff --git a/src/components/Switch/README-ru.md b/src/components/Switch/README-ru.md new file mode 100644 index 0000000000..dfaa0c33bc --- /dev/null +++ b/src/components/Switch/README-ru.md @@ -0,0 +1,153 @@ + + +# Switch + + + +```tsx +import {Switch} from '@gravity-ui/uikit'; +``` + +Компонент `Switch` (переключатель) используется для переключения между двумя состояниями: как правило, между **On** и **Off** или **Enabled** и **Disabled**. + +## Состояния + +`Switch` может иметь разные состояния: + +- Checked — когда переключатель **включен**. +- Disabled — когда переключатель недоступен. + + + + + +```tsx +Unchecked +Checked +Disabled +``` + + + +## Размер + +Размер `Switch` можно настроить с помощью свойства `size`. Размер по умолчанию — `m`. + + + + + +```tsx +M Size +L Size +``` + + + +## Лейбл + +Лейбл для `Switch` можно задать через свойство `content` или передать его как дочерний элемент. + + + + + +```tsx +
+ +
+ + Content as children + +
+
+``` + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :------------- | :--------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------: | :-------------------: | +| children | Содержимое переключателя (как правило, лейбл). | `ReactNode` | | +| content | Содержимое переключателя (альтернатива `children`). | `ReactNode` | | +| disabled | Включает или отключает состояние `disabled` у переключателя. | `boolean` | `false` | +| checked | Включает или отключает состояние `checked` у переключателя. | `boolean` | `false` | +| defaultChecked | Задает начальное состояние `checked` при монтировании компонента. | `boolean` | `false` | +| onUpdate | Срабатывает при изменении состояния переключателя пользователем и передает значение `checked` как аргумент обратного вызова. | `(checked: boolean) => void` | | +| onChange | Срабатывает при изменении состояния переключателя пользователем и передает событие изменения как аргумент обратного вызова. | `Function` | | +| onFocus | Обработчик события, вызываемый, когда элемент ввода переключателя получает фокус. | `Function` | | +| onBlur | Обработчик события, вызываемый, когда элемент ввода переключателя теряет фокус. | `Function` | | +| size | Определяет размер переключателя. | `m` `l` | `m` | +| id | HTML-атрибут `id`. | `string` | | +| qa | HTML-атрибут `data-qa`, используется для тестирования. | `string` | | +| style | HTML-атрибут `style`. | `React.CSSProperties` | | +| className | HTML-атрибут `class`. | `string` | | +| title | HTML-атрибут `title`. | `string` | | +| name | HTML-атрибут `name` для элемента ввода. | `string` | | +| value | HTML-атрибут `value` для элемента ввода. | `string` | | +| indeterminate | Включает или отключает состояние неопределенности переключателя. | `boolean` | `false` | +| controlProps | Дополнительные свойства базового элемента ввода. | `React.InputHTMLAttributes` | | +| controlRef | Ссылка на базовый элемент ввода. | `React.Ref` | | diff --git a/src/components/Switch/README.md b/src/components/Switch/README.md index f314db7c24..96ccd3658c 100644 --- a/src/components/Switch/README.md +++ b/src/components/Switch/README.md @@ -8,14 +8,14 @@ import {Switch} from '@gravity-ui/uikit'; ``` -The Switch component is used to toggle between two states, typically representing "on" and "off" or "enabled" and "disabled" states. +The `Switch` component is used to toggle between two states: typically, between **on** and **off**, or **enabled** and **disabled**. ## States -The Switch can be in different states. +A `Switch` can have different states: -- Checked - when the switch is in the "On" state. -- Disabled - when the switch is unavailable for interaction. +- Checked: When the switch has the **On** state. +- Disabled: When the switch is unavailable. ## Size -To control the size of the `Switch`, use the `size` property. The default size is `m`. +Use the `size` property to manage the `Switch` size. The default size is `m`. ## Label -You can set a label for a `Switch` component using the `content` property or pass it as children. +You can assign a label to a `Switch` using the `content` property or provide it as a child property. | Name | Description | Type | Default | | :------------- | :------------------------------------------------------------------------------------------------------- | :-------------------------------------------: | :-----: | -| children | The content of the switch (usually a label). | `ReactNode` | | -| content | The content of the switch (alternative to children). | `ReactNode` | | -| disabled | Toggles the `disabled` state of the switch. | `boolean` | `false` | -| checked | Toggles the checked state of the switch. | `boolean` | `false` | -| defaultChecked | Sets the initial checked state when the component is mounted. | `boolean` | `false` | -| onUpdate | Fires when the switch state is changed by the user. Provides the checked value as a callback's argument. | `(checked: boolean) => void` | | -| onChange | Fires when the switch state is changed by the user. Provides the change event as a callback's argument. | `Function` | | -| onFocus | Event handler for when the switch input element receives focus. | `Function` | | -| onBlur | Event handler for when the switch input element loses focus. | `Function` | | -| size | Sets the size of the switch. | `m` `l` | `m` | -| id | HTML `id` attribute | `string` | | -| qa | HTML `data-qa` attribute, used in tests. | `string` | | -| style | HTML `style` attribute | `React.CSSProperties` | | -| className | HTML `class` attribute | `string` | | -| title | HTML `title` attribute | `string` | | -| name | HTML `name` attribute for the input element. | `string` | | -| value | HTML `value` attribute for the input element. | `string` | | -| indeterminate | Toggles the indeterminate state of the switch. | `boolean` | `false` | -| controlProps | Additional props for the underlying input element. | `React.InputHTMLAttributes` | | -| controlRef | Ref to the underlying input element. | `React.Ref` | | +| children | The content of the switch (usually, a label) | `ReactNode` | | +| content | The content of the switch (alternative to children) | `ReactNode` | | +| disabled | Toggles the `disabled` state of the switch | `boolean` | `false` | +| checked | Toggles the `checked` state of the switch | `boolean` | `false` | +| defaultChecked | Sets the initial checked state when the component is mounted | `boolean` | `false` | +| onUpdate | Fires when the switch state is changed by the user and provides the checked value as a callback argument | `(checked: boolean) => void` | | +| onChange | Fires when the switch state is changed by the user and provides the change event as a callback argument | `Function` | | +| onFocus | Event handler to use when the switch input element receives focus | `Function` | | +| onBlur | Event handler to use when the switch input element loses focus | `Function` | | +| size | Sets the size of the switch | `m` `l` | `m` | +| id | `id` HTML attribute | `string` | | +| qa | `data-qa` HTML attribute, used for testing | `string` | | +| style | `style` HTML attribute | `React.CSSProperties` | | +| className | `class` HTML attribute | `string` | | +| title | `title` HTML attribute | `string` | | +| name | `name` HTML attribute for the input element | `string` | | +| value | `value` HTML attribute for the input element | `string` | | +| indeterminate | Toggles the indeterminate state of the switch | `boolean` | `false` | +| controlProps | Additional propeties for the underlying input element | `React.InputHTMLAttributes` | | +| controlRef | Ref to the underlying input element | `React.Ref` | | diff --git a/src/components/Table/README-ru.md b/src/components/Table/README-ru.md new file mode 100644 index 0000000000..0b730fa129 --- /dev/null +++ b/src/components/Table/README-ru.md @@ -0,0 +1,380 @@ + + +## Table (таблица) + + + +```jsx +import {Table} from '@gravity-ui/uikit'; +``` + +Компонент `Table` позволяет выбирать и сортировать строки, а также выполнять действия с выбранной строкой. + + + +Дополнительные функции подключаются через компоненты высшего порядка (HOC): + +- [withTableActions](#usage-with-hoc-withtableactions) +- [withTableCopy](#usage-with-hoc-withtablecopy) +- [withTableSelection](#usage-with-hoc-withtableselection) +- [withTableSettings](#usage-with-hoc-withtablesettings) +- [withTableSorting](#usage-with-hoc-withtablesorting) + + + +## Свойства + +| Имя | Описание | Тип | Значение по умолчанию | +| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------: | :-------------------: | +| data | Данные. | `any[]` | | +| columns | Настройки столбцов. | `TableColumnConfig[]` | | +| verticalAlign | Выравнивание содержимого по вертикали. | `"top"` `"middle"` | | +| getRowDescriptor | Обработчик для получения дескриптора строки. | `(item: any, index: number) => DescriptorType` | | +| getRowId | Идентификатор строки, используемый при выборе и сортировке строк. Если пропустить строку, то идентификатор такой строки будет равен значению поля в данных строки с тем же именем, что и идентификатор столбца. | `string` `((item: any, index: number) => string)` | | +| getRowClassNames | CSS-классы строки. | `(item: any, index: number) => string[]` | | +| isRowDisabled | Условие блокировки столбцов. | `(item: any, index: number) => boolean` | | +| onRowClick | Обработчик клика (`click`) по строке. | `(item: any, index: number, event: React.MouseEvent) => void` | | +| onRowMouseEnter | Обработчик наведения мыши (`mouseenter`) на строку. | `(item: any, index: number, event: React.MouseEvent) => void` | | +| onRowMouseLeave | Обработчик ухода мыши (`mouseleave`) со строки. | `(item: any, index: number, event: React.MouseEvent) => void` | | +| emptyMessage | Возвращает сообщение, если данные отсутствуют. | `string` | `"No data"` | +| className | CSS-класс таблицы. | `string` | | +| edgePadding | Добавляет горизонтальные отступы для крайних ячеек. | `boolean` | | +| stickyHorizontalScroll | Добавляет горизонтальную липкую прокрутку (sticky scroll) в таблице. Обратите внимание, что таблица не может иметь фиксированную высоту и липкую прокрутку одновременно. Липкая прокрутка не будет работать при переполнении таблицы. | `boolean` | `false` | +| stickyHorizontalScrollBreakpoint | Порог, которого должен достичь родительский блок, чтобы прокрутка стала липкой. Это особенно удобно в консоли, когда панель `groupActions` перекрывает область прокрутки. | `number` | `0` | + +### DescriptorType + +| Имя | Описание | Тип | Значение по умолчанию | +| :--------- | :---------------------------------------------------------------- | :---------: | :-------------------: | +| id | Идентификатор строки, используемый при выборе и сортировке строк. | `string` | | +| disabled | Условие блокировки столбцов. | `boolean` | | +| classNames | CSS-классы строки. | ` string[]` | | + +### TableColumnConfig + +| Имя | Описание | Тип | Значение по умолчанию | +| :---------- | :---------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------: | :---------------------------------------------------------------: | +| id | Идентификатор столбца. | `string` | | +| name | Название (заголовок) столбца. | `string` `(() => React.ReactNode)` | Идентификатор столбца. | +| className | CSS-класс, который будет добавлен ко всем ячейкам в столбце. | `string` | | +| placeholder | Заглушка при отсутствии данных в ячейке. | `string` `((item: any, index: number) => React.ReactNode)` | `— (—)` | +| template | Содержимое ячейки. Если пропустить строку, ячейка будет содержать значение поля с таким же именем, как и у этой строки. | `string` `((item: any, index: number) => React.ReactNode)` | Значение поля, имя которого соответствует идентификатору столбца. | +| align | Выравнивание содержимого. | `"start"` `"center"` `"end"` | | +| sticky | Липкий столбец. | `"start"` `"end"` | | +| primary | Указывает, что столбец является первичным относительно остальных. | `boolean` | | +| width | Ширина содержимого столбца в пикселях. | `number` `string` | | +| meta | Различные данные, включая настройки HOC. | `Record` | | + +## Использование `Table` с HOC `withTableActions` + +Этот HOC добавляет к столбцам таблицы специальный столбец с действиями. + +### Свойства + +| Имя | Описание | Тип | +| :--------------- | :---------------------------------------------------- | :------------------------------------------------------: | +| getRowActions | Массив конфигураций действий для каждой строки. | `(item: any, index: number) => TableActionConfig[]` | +| renderRowActions | Функция рендеринга ячейки с действиями. | `(props: {item: any; index: number}) => React.ReactNode` | +| rowActionsSize | Размер кнопки действия и элементов всплывающего меню. | `"s"` `"m"` `"l"` `"xl"` | + +### TableActionConfig + +```ts +type TableActionConfig = TableAction | TableActionGroup; +``` + +#### TableAction + +| Имя | Описание | Тип | Значение по умолчанию | +| :------- | :---------------------------------------------------------------------------- | :----------------------------------: | :-------------------: | +| text | Текст. | `string` | | +| handler | Обработчик клика. | `(item: any, index: number) => void` | | +| disabled | Действие отключено. | `boolean` | | +| href | Элемент меню с этим свойством становится ссылкой на указанное местоположение. | `string` | | +| target | То же, что и атрибут `target` у тега ``. | `string` | | +| rel | То же, что и атрибут `rel` у тега ``. | `string` | | +| theme | Тема. | `"normal"` `"danger"` | `"normal"` | +| icon | Иконка, отображаемая рядом с текстом. | `React.ReactNode` | | + +#### TableActionGroup + +| Имя | Описание | Тип | +| :---- | :------------------------- | :-------------------: | +| title | Заголовок группы действий. | `string` | +| items | Элементы группы действий. | `TableActionConfig[]` | + +### Пример + +```jsx +import {Table, withTableActions} from '@gravity-ui/uikit'; + +const MyTable = withTableActions(Table); +const data = [ + {id: 1, text: 'Hello'}, + {id: 2, text: 'World'}, +]; +const columns = [{id: 'id'}, {id: 'text'}]; +const getRowActions = () => { + return [ + { + text: 'Print', + handler: () => {}, + }, + { + text: 'Remove', + handler: () => {}, + theme: 'danger', + }, + ]; +}; + +const table = ; +``` + +```jsx +import {Table, withTableActions, RenderRowActionsProps} from '@gravity-ui/uikit'; + +const MyTable = withTableActions(Table); +type Item = {id: number; text: string}; + +const data: Item[] = [ + {id: 1, text: 'Hello'}, + {id: 2, text: 'World'}, +]; +const columns = [{id: 'id'}, {id: 'text'}]; + +const RowAction = ({item}: RenderRowActionsProps) => { + return {`Action for - ${item.text}`}; +}; + +const table = ( + +); +``` + +## Использование `Table` с HOC `withTableCopy` + +Этот HOC позволяет копировать содержимое ячейки или произвольный текст. + +### ColumnMeta + +| Имя | Описание | Тип | +| :--- | :-------------------------------------------------------------------------------------- | :-----------------------------------------------------------------------------------------: | +| copy | Копируемый текст. Если установлено значение `true`, содержимое ячейки можно копировать. | `boolean` `((item: any, index: number) => string)` `((item: any, index: number) => number)` | + +### Пример + +```jsx +import {Table, withTableCopy} from '@gravity-ui/uikit'; + +const MyTable = withTableCopy(Table); +const data = [ + {id: 1, text: 'Hello'}, + {id: 2, text: 'World'}, +]; +const columns = [ + {id: 'id', meta: {copy: ({id}) => `ID #${id}`}}, + {id: 'text', meta: {copy: true}}, +]; + +const table = ; +``` + +## Использование `Table` с HOC `withTableSelection` + +Этот HOC позволяет выбирать строки в таблице. + +### Свойства + +| Имя | Описание | Тип | +| :---------------- | :------------------------------------ | :-----------------------: | +| selectedIds | Выбранные строки. | `string[]` | +| onSelectionChange | Обработчик изменения выбранных строк. | `(ids: string[]) => void` | + +### Пример + +```jsx +import {Table, withTableSelection} from '@gravity-ui/uikit'; + +const MyTable = withTableSelection(Table); +const data = [ + {id: 1, text: 'Hello'}, + {id: 2, text: 'World'}, +]; +const columns = [{id: 'id'}, {id: 'text'}]; +const getRowId = 'id'; + +function SelectionTable() { + const [selectedIds, setSelectedIds] = React.useState([1]); + + return ( + + ); +} +``` + +## Использование `Table` с HOC `withTableSettings` + +Этот HOC активирует функции для настройки столбцов таблицы. Его можно использовать двумя способами: + +```jsx +import {Table, withTableSettings} from './withTableSettings'; + +// No options passed +const MyTable1 = withTableSettings(Table); +// or with options +const MyTable1 = withTableSettings({sortable: false})(Table); +``` + +### Опции + +| Имя | Описание | Тип | Значение по умолчанию | +| :--------- | :---------------------------------------------------- | :--------------: | :-------------------: | +| width | Ширина всплывающего окна с настройками. | `number` `"fit"` | | +| sortable | Включает или отключает сортировку элементов настроек. | `boolean` | `true` | +| filterable | Включает или отключает фильтрацию элементов настроек. | `boolean` | `false` | + +### ColumnMeta + +| Имя | Описание | Тип | Значение по умолчанию | +| :---------------- | :-------------------------------------------------------------------------------------------------------- | :-------: | :-------------------: | +| selectedByDefault | Включает или отключает автоматический выбор столбца, если он не передан в настройках. | `boolean` | `true` | +| selectedAlways | При включении этого свойства столбец всегда остается выбранным. Изменить видимость такого столбца нельзя. | `boolean` | `false` | + +### Свойства + +| Имя | Описание | Тип | +| :------------------------- | :--------------------------------------------------------------------------- | :------------------------------------------------------: | +| settingsPopupWidth | Ширина всплывающего окна `TableColumnSetup`. | `number` `"fit"` | +| settings | Текущие настройки. | `TableSettingsData` | +| updateSettings | Обработчик обновления настроек. | `(data: TableSettingsData) => Promise` | +| renderControls | Позволяет рендерить пользовательские действия. | `RenderControls` | +| settingsFilterPlaceholder | Текст, который отображается в контроле, когда значение для поиска не задано. | `string` | +| settingsFilterEmptyMessage | Текст, который отображается, когда ни один элемент не найден. | `string` | +| filterSettings | Функция для фильтрации элементов. | `(value: string, item: TableColumnSetupItem) => boolean` | + +### TableSettingsData + +```ts +type TableSettingsData = Array<{ + id: string; + isSelected?: boolean; +}>; +``` + +### RenderControls + +```ts +type RenderControls = (params: { + DefaultApplyButton: React.ComponentType; + onApply: () => void; +}) => React.ReactNode; +``` + +### Пример + +```jsx +import {Table, withTableSettings} from '@gravity-ui/uikit'; + +const MyTable = withTableSettings({width: 100, sortable: false})(Table); +const data = [ + {id: 1, text: 'Hello'}, + {id: 2, text: 'World'}, +]; +const columns = [{id: 'id'}, {id: 'text'}]; +const initialSettings = [ + {id: 'id', isSelected: false}, + {id: 'text', isSelected: true}, +]; + +function SelectionTable() { + const [settings, setSettings] = React.useState(initialSettings); + + return ( + { + setSettings(settings); + return Promise.resolve(); + }} + renderControls={({DefaultApplyButton, onApply}) => ( + + + + + )} + /> + ); +} +``` + +## Использование `Table` с HOC `withTableSorting` + +Этот HOC позволяет выполнить сортировку столбцов. + +### ColumnMeta + +| Имя | Описание | Тип | Значение по умолчанию | +| :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------: | :-------------------: | +| defaultSortOrder | Устанавливает первичный порядок сортировки. | `"asc"` `"desc"` | `asc` | +| sort | Функция сортировки. Возвращает значение для сортировки по возрастанию. При установке `true` значения ячеек сравниваются и сортируются в порядке возрастания. | `boolean` `((itemA: any, itemB: any) => number)` | | + +### Свойства + +| Имя | Описание | Тип | +| :---------------- | :------------------------------------------------------------------ | :-----------------------------------: | +| defaultSortState | Состояние сортировки по умолчанию для неконтролируемого компонента. | `TableSortState` | +| sortState | Состояние сортировки. | `TableSortState` | +| onSortStateChange | Обработчик изменения состояния сортировки. | `(sortState: TableSortState) => void` | + +Если не передавать свойства `sortState` и `onSortStateChange`, то состояние сортировки будет храниться в самом компоненте. + +### TableSortState + +```ts +type TableSortState = Array<{ + column: string; + order: 'asc' | 'desc'; +}>; +``` + +### Пример + +```jsx +import {Table, withTableSorting} from '@gravity-ui/uikit'; + +const MyTable = withTableSorting(Table); +const data = [ + {id: 1, text: 'Hello', date: '2016-10-25'}, + {id: 2, text: 'World', date: '2020-08-15'}, +]; +const columns = [ + {id: 'id', meta: {sort: true}}, + { + id: 'text', + meta: {defaultSortOrder: 'desc', sort: (a, b) => Date.parse(a.date) - Date.parse(b.date)}, + }, +]; + +const table = ; +``` diff --git a/src/components/Table/README.md b/src/components/Table/README.md index 4e509ca448..1c9e276f09 100644 --- a/src/components/Table/README.md +++ b/src/components/Table/README.md @@ -8,11 +8,11 @@ import {Table} from '@gravity-ui/uikit'; ``` -A table that allows the selecting and sorting of rows, and performing actions on a row. +A `Table` allows selecting and sorting rows, as well as performing actions on a row. -Additional functionality is enabled via HOCs: +Additional features are enabled through HOCs: - [withTableActions](#usage-with-hoc-withtableactions) - [withTableCopy](#usage-with-hoc-withtablecopy) @@ -24,59 +24,58 @@ Additional functionality is enabled via HOCs: ## Properties -| Name | Description | Type | Default | -| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------: | :---------: | -| data | Data | `any[]` | | -| columns | Column parameters | `TableColumnConfig[]` | | -| verticalAlign | Vertical alignment of contents | `"top"` `"middle"` | | -| getRowDescriptor | Handler to get row descriptor | `(item: any, index: number) => DescriptorType` | | -| getRowId | The row ID, used when selecting and sorting rows. If you skip a row, its ID will be the value of the field in the row data with the same name as the column ID | `string` `((item: any, index: number) => string)` | | -| getRowClassNames | Row CSS classes | `(item: any, index: number) => string[]` | | -| isRowDisabled | Condition for disabling columns | `(item: any, index: number) => boolean` | | -| onRowClick | Row click handler | `(item: any, index: number, event: React.MouseEvent) => void` | | -| onRowMouseEnter | Row mouseenter handler | `(item: any, index: number, event: React.MouseEvent) => void` | | -| onRowMouseLeave | Row mouseleave handler | `(item: any, index: number, event: React.MouseEvent) => void` | | -| emptyMessage | The message returned if data is missing. | `string` | `"No data"` | -| className | Table CSS class | `string` | | -| edgePadding | Adds horizontal padding for edge cells | `boolean` | | -| stickyHorizontalScroll | A horizontal sticky scroll in a table. NB: A table cannot have a fixed height and a sticky scroll at the same time. A sticky scroll will not work if the table has an overflow. | `boolean` | `false` | -| stickyHorizontalScrollBreakpoint | The threshold that the parent block should reach before making a scroll sticky. This is useful in the console, for example, when the groupActions bar closes the scroll. | `number` | `0` | -| `width` | Table width | `"auto"` `"max"` | "auto" | +| Name | Description | Type | Default | +| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------: | :---------: | +| data | Data | `any[]` | | +| columns | Column settings | `TableColumnConfig[]` | | +| verticalAlign | Vertical alignment of content | `"top"` `"middle"` | | +| getRowDescriptor | Handler to get the row descriptor | `(item: any, index: number) => DescriptorType` | | +| getRowId | Row ID used when selecting and sorting rows. If you skip a row, its ID will be the value of the field in the row data with the same name as the column ID. | `string` `((item: any, index: number) => string)` | | +| getRowClassNames | Row CSS classes | `(item: any, index: number) => string[]` | | +| isRowDisabled | Condition for disabling columns | `(item: any, index: number) => boolean` | | +| onRowClick | Row click handler | `(item: any, index: number, event: React.MouseEvent) => void` | | +| onRowMouseEnter | Row mouseenter handler | `(item: any, index: number, event: React.MouseEvent) => void` | | +| onRowMouseLeave | Row mouseleave handler | `(item: any, index: number, event: React.MouseEvent) => void` | | +| emptyMessage | Returning a message if the data is missing | `string` | `"No data"` | +| className | Table CSS class | `string` | | +| edgePadding | Adds horizontal padding for edge cells | `boolean` | | +| stickyHorizontalScroll | Adds a horizontal sticky scroll in a table. Note: A table cannot have a fixed height and a sticky scroll at the same time. A sticky scroll will not work if the table has an overflow. | `boolean` | `false` | +| stickyHorizontalScrollBreakpoint | Threshold the parent block should reach before making a scroll sticky. This is useful in the console, such as when the `groupActions` bar overlaps the scroll. | `number` | `0` | ### DescriptorType -| Name | Description | Type | Default | -| :--------- | :----------------------------------------------- | :---------: | :-----: | -| id | The row ID, used when selecting and sorting rows | `string` | | -| disabled | Condition for disabling columns | `boolean` | | -| classNames | Row CSS classes | ` string[]` | | +| Name | Description | Type | Default | +| :--------- | :------------------------------------------ | :---------: | :-----: | +| id | Row ID used when selecting and sorting rows | `string` | | +| disabled | Condition for disabling columns | `boolean` | | +| classNames | Row CSS classes | ` string[]` | | ### TableColumnConfig -| Name | Description | Type | Default | -| :---------- | :----------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------: | :---------------------------------------------------------: | -| id | Column ID | `string` | | -| name | Column name (header) | `string` `(() => React.ReactNode)` | column ID | -| className | CSS-class that will be added to all cells in the column | `string` | | -| placeholder | The stub when there is no data in a cell | `string` `((item: any, index: number) => React.ReactNode)` | `— (—)` | -| template | Cell contents. If you skip a row, the cell contents will be the value of the field with the same name as this row. | `string` `((item: any, index: number) => React.ReactNode)` | The value of the field with the name equal to the column ID | -| align | Content alignment | `"start"` `"center"` `"end"` | | -| sticky | Sticky column | `"start"` `"end"` | | -| primary | Distinguishes a column among other | `boolean` | | -| width | Column's content width in px | `number` `string` | | -| meta | Various data, HOC settings | `Record` | | +| Name | Description | Type | Default | +| :---------- | :----------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------: | :-----------------------------------------------------: | +| id | Column ID | `string` | | +| name | Column name (header) | `string` `(() => React.ReactNode)` | column ID | +| className | CSS class that will be added to all cells in the column | `string` | | +| placeholder | Stub when there is no data in a cell | `string` `((item: any, index: number) => React.ReactNode)` | `— (—)` | +| template | Cell contents. If you skip a row, the cell contents will be the value of the field with the same name as this row. | `string` `((item: any, index: number) => React.ReactNode)` | Value of the field with the name equal to the column ID | +| align | Content alignment | `"start"` `"center"` `"end"` | | +| sticky | Sticky column | `"start"` `"end"` | | +| primary | Identifies a column as primary as opposed to others | `boolean` | | +| width | Column's content width in pixels | `number` `string` | | +| meta | Miscellaneous data including the HOC settings | `Record` | | -## Usage with HOC `withTableActions` +## Using `Table` with the `withTableActions` HOC -Adds a special column with actions to table columns. +This HOC adds a special column with actions to table columns. ### Properties -| Name | Description | Type | -| :--------------- | :------------------------------------------ | :------------------------------------------------------: | -| getRowActions | Array of action configs for each row | `(item: any, index: number) => TableActionConfig[]` | -| renderRowActions | render function for Actions Cell | `(props: {item: any; index: number}) => React.ReactNode` | -| rowActionsSize | Size of actions button and popup menu items | `"s"` `"m"` `"l"` `"xl"` | +| Name | Description | Type | +| :--------------- | :--------------------------------------------- | :------------------------------------------------------: | +| getRowActions | Array of action configs for each row | `(item: any, index: number) => TableActionConfig[]` | +| renderRowActions | Render function for Actions Cell | `(props: {item: any; index: number}) => React.ReactNode` | +| rowActionsSize | Size of the action button and popup menu items | `"s"` `"m"` `"l"` `"xl"` | ### TableActionConfig @@ -86,16 +85,16 @@ type TableActionConfig = TableAction | TableActionGroup; #### TableAction -| Name | Description | Type | Default | -| :------- | :----------------------------------------------------------------- | :----------------------------------: | :--------: | -| text | Text | `string` | | -| handler | Click handler | `(item: any, index: number) => void` | | -| disabled | Action disabled | `boolean` | | -| href | Menu item with this prop becomes a link to the specified location. | `string` | | -| target | Same as the `target` attribute of the `` tag. | `string` | | -| rel | Same as the `rel` attribute of the `` tag. | `string` | | -| theme | Theme | `"normal"` `"danger"` | `"normal"` | -| icon | Icon to display next to the text | `React.ReactNode` | | +| Name | Description | Type | Default | +| :------- | :----------------------------------------------------------------------- | :----------------------------------: | :--------: | +| text | Text | `string` | | +| handler | Click handler | `(item: any, index: number) => void` | | +| disabled | Action disabled | `boolean` | | +| href | A menu item with this property becomes a link to the specified location. | `string` | | +| target | Same as the `target` attribute of the `` tag. | `string` | | +| rel | Same as the `rel` attribute of the `` tag. | `string` | | +| theme | Theme | `"normal"` `"danger"` | `"normal"` | +| icon | Icon to display next to the text | `React.ReactNode` | | #### TableActionGroup @@ -157,15 +156,15 @@ const table = ( ); ``` -## Usage with HOC `withTableCopy` +## Using `Table` with the `withTableCopy` HOC -Allows the contents of a cell or any text to be copied. +This HOC enables copying the contents of a cell or any other text. ### ColumnMeta -| Name | Description | Type | -| :--- | :---------------------------------------------------------------------- | :-----------------------------------------------------------------------------------------: | -| copy | The text to be copies. If true is passed, the cell contents are copied. | `boolean` `((item: any, index: number) => string)` `((item: any, index: number) => number)` | +| Name | Description | Type | +| :--- | :-------------------------------------------------------------------- | :-----------------------------------------------------------------------------------------: | +| copy | Text to copy. If the value is true, copying cell contents is allowed. | `boolean` `((item: any, index: number) => string)` `((item: any, index: number) => number)` | ### Example @@ -185,15 +184,15 @@ const columns = [ const table = ; ``` -## Usage with HOC `withTableSelection` +## Using `Table` with the `withTableSelection` HOC -Enables the selection of table rows. +This HOC enables selecting table rows. ### Properties | Name | Description | Type | | :---------------- | :-------------------------- | :-----------------------: | -| selectedIds | Rows selected | `string[]` | +| selectedIds | Selected rows | `string[]` | | onSelectionChange | Selected row change handler | `(ids: string[]) => void` | ### Example @@ -224,9 +223,9 @@ function SelectionTable() { } ``` -## Usage with HOC `withTableSettings` +## Using `Table` with the `withTableSettings` HOC -Enables functionality for table column settings. You can use ut in two forms: +This HOC enables features for table column settings. You can use it in two ways: ```jsx import {Table, withTableSettings} from './withTableSettings'; @@ -239,32 +238,30 @@ const MyTable1 = withTableSettings({sortable: false})(Table); ### Options -| Name | Description | Type | Default | -| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :-----------------: | :-----: | -| width | Settings' popup width | `number` `"fit"` | | -| sortable | Whether or not add ability to sort settings items | `boolean` | `true` | -| filterable | Whether or not add ability to filter settings items | `boolean` | `false` | -| defaultSettings | Settings to which you can reset the current settings | `TableSettingsData` | | -| showResetButton | Display a reset button that resets the current settings changes. If the `defaultSettings` prop is set then the settings reset to the `defaultSettings`. | `boolean` | | +| Name | Description | Type | Default | +| :--------- | :------------------------------------------- | :--------------: | :-----: | +| width | Settings popup width | `number` `"fit"` | | +| sortable | Enables or disables sorting settings items | `boolean` | `true` | +| filterable | Enables or disables filtering settings items | `boolean` | `false` | ### ColumnMeta -| Name | Description | Type | Default | -| :---------------- | :------------------------------------------------------------------------- | :-------: | :-----: | -| selectedByDefault | Specifies whether a column is selected if it is missing from the settings. | `boolean` | `true` | -| selectedAlways | Makes the column always selected. You cannot change its visibility. | `boolean` | `false` | +| Name | Description | Type | Default | +| :---------------- | :------------------------------------------------------------------------ | :-------: | :-----: | +| selectedByDefault | Enables or disables selecting a column if it is missing from the settings | `boolean` | `true` | +| selectedAlways | Makes the column always selected. You cannot change its visibility. | `boolean` | `false` | ### Properties -| Name | Description | Type | -| :------------------------- | :------------------------------------------------------------------------- | :------------------------------------------------------: | -| settingsPopupWidth | TableColumnSetup pop-up width | `number` `"fit"` | -| settings | Current settings | `TableSettingsData` | -| updateSettings | Settings update handle | `(data: TableSettingsData) => Promise` | -| renderControls | (deprecated) use `defaultSettings` and `showResetButton` to reset settings | `RenderControls` | -| settingsFilterPlaceholder | Text that appears in the control when no search value is set | `string` | -| settingsFilterEmptyMessage | Text that appears when no one item is found | `string` | -| filterSettings | Function for filtering items | `(value: string, item: TableColumnSetupItem) => boolean` | +| Name | Description | Type | +| :------------------------- | :----------------------------------------------------------- | :------------------------------------------------------: | +| settingsPopupWidth | `TableColumnSetup` pop-up width | `number` `"fit"` | +| settings | Current settings | `TableSettingsData` | +| updateSettings | Settings update handler | `(data: TableSettingsData) => Promise` | +| renderControls | Enables rendering custom actions | `RenderControls` | +| settingsFilterPlaceholder | Text that appears in the control when no search value is set | `string` | +| settingsFilterEmptyMessage | Text that appears when no item is found | `string` | +| filterSettings | Function for filtering items | `(value: string, item: TableColumnSetupItem) => boolean` | ### TableSettingsData @@ -331,16 +328,16 @@ function SelectionTable() { } ``` -## Usage with HOC `withTableSorting` +## Using `Table` with the `withTableSorting` HOC -Enables column sorting. +This HOC enables column sorting. ### ColumnMeta -| Name | Description | Type | Default | -| :--------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------: | :-----: | -| defaultSortOrder | Sets the primary sorting order | `"asc"` `"desc"` | `asc` | -| sort | The sorting function. It should return a value for sorting in ascending order. If true is passed, cell values are compared and sorted in ascending order. | `boolean` `((itemA: any, itemB: any) => number)` | | +| Name | Description | Type | Default | +| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------: | :-----: | +| defaultSortOrder | Sets the primary sorting order | `"asc"` `"desc"` | `asc` | +| sort | Sorting function. It should return a value for sorting in the ascending order. If set to true, the cell values are compared and sorted in the ascending order. | `boolean` `((itemA: any, itemB: any) => number)` | | ### Properties @@ -350,7 +347,7 @@ Enables column sorting. | sortState | Sorting state | `TableSortState` | | onSortStateChange | Sorting state change handle | `(sortState: TableSortState) => void` | -If the `sortState` and `onSortStateChange` props are not passed, the sorting state is stored in the component itself. +If the `sortState` and `onSortStateChange` properties are missing, the sorting state is stored in the component itself. ### TableSortState diff --git a/src/components/Tabs/README-ru.md b/src/components/Tabs/README-ru.md new file mode 100644 index 0000000000..7c19a9ba9e --- /dev/null +++ b/src/components/Tabs/README-ru.md @@ -0,0 +1,325 @@ + + +# Tabs + + + +```tsx +import {Tabs} from '@gravity-ui/uikit'; +``` + +Компонент `Tabs` используется организации контента и навигации по нему, а также для переключения между различными представлениями. + +## Элементы + +Для рендеринга элементов `Tabs` используйте свойство `items`. + + + + + +```tsx +const [activeTab, setActiveTab] = React.useState('second'); + +return ( + setActiveTab(tabId)} + items={[ + {id: 'first', title: 'First Tab'}, + {id: 'second', title: 'Second Tab'}, + {id: 'third', title: 'Disabled Tab', disabled: true}, + ]} + /> +); +``` + + + +`Tabs` также имеет специальный компонент для рендеринга отдельных элементов. + + + +```tsx +const [activeTab, setActiveTab] = React.useState('second'); + +return ( + + setActiveTab(tabId)} /> + setActiveTab(tabId)} /> + +); +``` + + + +## Размер + +Размер `Tabs` можно настроить с помощью свойства `size`. Размер по умолчанию — `m`. + + + + + +```tsx + + + + + +``` + + + +## Tabs.Item + +Используется для рендеринга элемента `Tabs`. + +### Иконка + +Используется, если нужно отобразить иконку для элемента `Tabs`. + + + + + +```tsx + + } + id="first" + title="Tab with icon" + onClick={() => {}} + /> + {}} /> + +``` + + + +### Состояния + +Элементы `Tabs` поддерживают флаг `disabled`. + + + + + +```tsx + + {}} /> + {}} /> + +``` + + + +### Счетчик + +Используется, если нужно отобразить число для элемента `Tabs`. + + + + + +```tsx + + {}} counter={13} /> + {}} counter={3} /> + +``` + + + +### Свойства `Tabs.Item` + +| Имя | Описание | Тип | Значение по умолчанию | +| :------- | -------------------------------- | :------------------------: | :-------------------: | +| id | Идентификатор вкладки. | `string` | | +| title | Заголовок вкладки. | `string` `React.ReactNode` | | +| meta | Описание вкладки. | `string` | | +| hint | HTML-атрибут `title`. | `string` | | +| icon | Иконка, отображаемая в начале. | `React.ReactNode` | | +| counter | Число, отображаемое в конце. | `React.ReactNode` | | +| label | `