@skbkontur/react-ui 0.0.0-3c309a601b → 0.0.0-3dbb8bef27

package/components/ComboBox/ComboBox.d.ts

@@ -1,91 +1,79 @@
 import React, { AriaAttributes, HTMLAttributes } from 'react';
 import { Nullable } from '../../typings/utility-types';
 import { MenuItemState } from '../MenuItem';
-import { InputIconType } from '../Input';
+import { InputIconType, ShowClearIcon } from '../Input';
 import { CommonProps } from '../../internal/CommonWrapper';
 import { SizeProp } from '../../lib/types/props';
 export interface ComboBoxProps<T> extends Pick<AriaAttributes, 'aria-describedby' | 'aria-label'>, Pick<HTMLAttributes<HTMLElement>, 'id'>, CommonProps {
+    /** Показывать иконку очистки значения в непустом поле:
+     * - `always` — всегда показывать иконку
+     * - `auto` — показывать иконку при hover/focus
+     * - `never` — не показывать иконку
+     * При одновременной настройке `showClearIcon` и `rightIcon` показывается иконка очистки.
+     * @default never */
+    showClearIcon?: ShowClearIcon;
+    /** Задает выравнивание контента. */
     align?: 'left' | 'center' | 'right';
-    /**
-     * Вызывает функцию поиска `getItems` при фокусе и очистке поля ввода
-     * @default true
-     */
+    /** Вызывает функцию поиска getItems при фокусе и очистке поля ввода. */
     searchOnFocus?: boolean;
-    /**
-     * Рисует справа иконку в виде стрелки
-     * @default true
-     */
+    /** Отображает справа иконку в виде стрелки. */
     drawArrow?: boolean;
+    /** Устанавливает фокус на контроле после окончания загрузки страницы. */
     autoFocus?: boolean;
+    /** Убирает обводку. */
     borderless?: boolean;
-    /**
-     * Не использовать Portal для рендеринга меню.
-     * См. https://github.com/skbkontur/retail-ui/issues/15
-     * @default false
-     */
+    /** Отключает использование портала для рендеринга меню.
+     * См. https://github.com/skbkontur/retail-ui/issues/15 */
     disablePortal?: boolean;
+    /** Делает компонент недоступным. */
     disabled?: boolean;
-    /**
-     * Состояние валидации при ошибке.
-     */
+    /** Переводит контрол в состояние валидации "ошибка". */
     error?: boolean;
+    /** Добавляет иконку слева.
+     При использовании `ReactNode` применяются дефолтные стили для иконки.
+     При использовании `() => ReactNode` применяются только стили для позиционирования. */
     leftIcon?: InputIconType;
+    /** Добавляет иконку справа.
+     При использовании `ReactNode` применяются дефолтные стили для иконки.
+     При использовании `() => ReactNode` применяются только стили для позиционирования. */
     rightIcon?: InputIconType;
-    /**
-     * Функция поиска элементов, должна возвращать Promise с массивом элементов.
+    /** Задает функцию поиска элементов, которая должна возвращать Promise с массивом элементов.
      * По умолчанию ожидаются объекты с типом `{ value: string, label: string }`.
-     *
-     * Элементы могут быть любого типа. В этом случае необходимо определить
-     * свойства `itemToValue`, `renderValue`, `renderItem`, `valueToString`
-     */
+     * Элементы могут быть любого типа. В этом случае необходимо определить свойства `itemToValue`, `renderValue`, `renderItem`, `valueToString`. */
     getItems: (query: string) => Promise<Array<ComboBoxExtendedItem<T>>>;
-    /**
-     * Необходим для сравнения полученных результатов с `value`
-     * @default item => item.label
-     */
+    /** Задает функцию сравнения полученных результатов с value. */
     itemToValue?: (item: T) => string | number;
+    /** Задает максимальную длину инпута. */
     maxLength?: number;
-    /**
-     * Позволяет вручную задать текущую позицию выпадающего окна
+    /** Задает текущую позицию выпадающего окна вручную.
      */
     menuPos?: 'top' | 'bottom';
+    /** Задает выравнивание выпадающего меню. */
     menuAlign?: 'left' | 'right';
+    /** Задает функцию, которая вызывается при потере комбобоксом фокуса. */
     onBlur?: () => void;
     /** Вызывается при изменении `value` */
     onValueChange?: (value: T) => void;
+    /** Задает функцию, которая вызывается при получении комбобоксом фокуса. */
     onFocus?: () => void;
-    /**
-     * Вызывается при изменении текста в поле ввода,
-     * если результатом функции будет строка,
-     * то она станет следующим состоянием полем ввода
-     */
+    /** Задает функцию, которая вызывается при изменении текста в поле ввода, если результатом функции будет строка, то она станет следующим состоянием полем ввода. */
     onInputValueChange?: (value: string) => Nullable<string> | void;
-    /**
-     * Функция для обработки ситуации, когда была введена
-     * строка в инпут и был потерян фокус с элемента.
-     *
-     * Если при потере фокуса в выпадающем списке будет только один
-     * элемент и  результат `renderValue` с этим элементом будет
-     * совпадать со значение в текстовом поле, то
-     * сработает onValueChange со значением данного элемента
-     *
-     * Сама функция также может вернуть значение,
-     * неравное `undefined`,
-     * с которым будет вызван onValueChange.
-     */
+    /** Задает функцию для обработки ввода строки в инпут и последующей потерей фокуса компонентом.
+     * Функция срабатывает с аргументом инпута строки.
+     * Если при потере фокуса в выпадающем списке будет только один элемент и результат valueToString с этим элементом будет совпадать со значение в текстовом поле, то сработает onValueChange со значением данного элемента.
+     * Сама функция также может вернуть значение, неравное undefined, с которым будет вызван onValueChange. Если возвращаемое значение будет равно null, то сработает очистка текущего значения инпута, а в режиме редактирования токен будет удален. */
     onUnexpectedInput?: (value: string) => void | null | T;
+    /** Задает текст, который отображается если не введено никакое значение. */
     placeholder?: string;
-    /**
-     * Функция отрисовки элементов результата поиска.
+    /** Задает функцию отрисовки элементов результата поиска.
      * Не применяется если элемент является функцией или React-элементом
      * @default item => item.label
-     */
+     * @param {T} item - элемент из результата поиска.
+     * @param {MenuItemState} state? - состояние элемента.
+     * @returns {React.ReactNode} React-элемент. */
     renderItem?: (item: T, state?: MenuItemState) => React.ReactNode;
-    /**
-     * Компонент, заменяющий собой обёртку элементов результата поиска.
-     *
-     * По умолчанию все элементы результата поиска оборачиваются в тег `<button />`.
-     *
+    /** Устанавливает компонент, заменяющий собой обёртку элементов результата поиска.
+     * По умолчанию все элементы результата поиска оборачиваются в тег <button />.
      * @example
      * itemWrapper={(item) => {
      *    if (item.value === 3) {
@@ -96,52 +84,40 @@ export interface ComboBoxProps<T> extends Pick<AriaAttributes, 'aria-describedby
      * }}
      */
     itemWrapper?: (item: T) => React.ComponentType;
-    /**
-     * Функция для отрисовки сообщения о пустом результате поиска
-     * Если есть renderAddButton - не работает
-     */
+    /** Задает функцию, которая отображает сообщение о пустом результате поиска. При renderAddButton не работает. */
     renderNotFound?: () => React.ReactNode;
-    /**
-     * Функция отображающая сообщение об общем количестве элементов.
-     * `found` учитывает только компонент `MenuItem`. Им "оборачиваются" элементы, возвращаемые `getItems()`.
-     */
+    /** Задает функцию, которая отображает сообщение об общем количестве элементов.
+     * @param {number} found - количество элементов по результатам поиска. Учитывает только компонент MenuItem. Им "оборачиваются" элементы, возвращаемые getItems().
+     * @param {number} total - количество всех элементов. */
     renderTotalCount?: (found: number, total: number) => React.ReactNode;
-    /**
-     * Функция отрисовки выбранного значения
-     * @default item => item.label
-     */
+    /** Задает функцию, которая отображает выбранное значение.
+     * @default item => item.label */
     renderValue?: (item: T) => React.ReactNode;
-    /**
-     * Функция отрисовки кнопки добавления в выпадающем списке
-     */
+    /** Задает функцию отрисовки кнопки добавления в выпадающем списке. */
     renderAddButton?: (query?: string) => React.ReactNode;
-    /**
-     * Общее количество элементов.
-     * Необходим для работы `renderTotalCount`
-     */
+    /** Определяет общее количество элементов. Необходим для работы renderTotalCount. */
     totalCount?: number;
-    /**
-     * Выбранное значение
-     * Ожидается, что `value` того же типа что и элементы в массиве,
-     * возвращаемом в `getItems`
-     */
+    /** Устанавливает выбранное в комбобоксе значение. Тип `value` совпадает с типом элементов в массиве, возвращаемом в `getItems`. */
     value?: Nullable<T>;
-    /**
-     * Необходим для преобразования `value` в строку при фокусировке
-     * @default item => item.label
-     */
+    /** Задает функцию, которая возвращает строковое представление value. Необходимо при фокусировке. */
     valueToString?: (item: T) => string;
+    /** Задает размер компонента. */
     size?: SizeProp;
-    /**
-     * Состояние валидации при предупреждении.
-     */
+    /** Переводит контрол в состояние валидации "предупреждение". */
     warning?: boolean;
+    /** Задает длину комбобокса. */
     width?: string | number;
+    /** Задает максимальную высоту меню. */
     maxMenuHeight?: number | string;
+    /** Задает функцию, которая вызывается при наведении мышкой (событие `onmouseenter`). См разницу с onMouseOver в [документации](https://learn.javascript.ru/mousemove-mouseover-mouseout-mouseenter-mouseleave)  */
     onMouseEnter?: (e: React.MouseEvent) => void;
+    /** Задает функцию, которая вызывается при наведении мышкой (событие `onmouseover`). */
     onMouseOver?: (e: React.MouseEvent) => void;
+    /** Задает функцию, которая вызывается при уходе мышки с объекта (событие `onmouseleave`). */
     onMouseLeave?: (e: React.MouseEvent) => void;
+    /** Задает функцию, которая вызывается при нажатии кнопки на клавиатуре. */
     onInputKeyDown?: (e: React.KeyboardEvent<HTMLElement>) => void;
+    /** Задает типы вводимых данных. */
     inputMode?: React.HTMLAttributes<HTMLInputElement>['inputMode'];
 }
 export interface ComboBoxItem {
@@ -149,7 +125,17 @@ export interface ComboBoxItem {
     label: string;
 }
 export type ComboBoxExtendedItem<T> = T | (() => React.ReactElement<T>) | React.ReactElement<T>;
-type DefaultProps<T> = Required<Pick<ComboBoxProps<T>, 'itemToValue' | 'valueToString' | 'renderValue' | 'renderItem' | 'menuAlign' | 'searchOnFocus' | 'drawArrow'>>;
+type DefaultProps<T> = Required<Pick<ComboBoxProps<T>, 'itemToValue' | 'valueToString' | 'renderValue' | 'renderItem' | 'menuAlign' | 'searchOnFocus' | 'drawArrow' | 'showClearIcon'>>;
+/**
+ * `ComboBox` — это поле ввода со списком подсказок.
+ *
+ * `ComboBox` используют:
+ * * для выбора значения из справочника.
+ * * для добавления своего значения в справочник.
+ *
+ * `ComboBox` может работать в двух режимах — обычном и в режиме автокомплита.
+ * Основное их отличие в том, что в режиме автокомплита список вариантов появляется только после ввода первого символа или изменении уже введенного значения.
+ */
 export declare class ComboBox<T = ComboBoxItem> extends React.Component<ComboBoxProps<T>> {
     static __KONTUR_REACT_UI__: string;
     static displayName: string;
@@ -160,7 +146,9 @@ export declare class ComboBox<T = ComboBoxItem> extends React.Component<ComboBox
     /**
      * @public
      */
-    focus(): void;
+    focus(opts?: {
+        withoutOpenDropdown?: boolean;
+    }): void;
     /**
      * @public
      */

package/components/ComboBox/ComboBox.md

@@ -1,4 +1,4 @@
-Combobox with error handling
+### Комбобокс с валидацией
 
 ```jsx harmony
 import { Tooltip } from '@skbkontur/react-ui';
@@ -49,6 +49,7 @@ let handleFocus = () => setError(false);
 </Tooltip>;
 ```
 
+### Очистка комбобокса
 Очистить значение в `ComboBox`'е можно с помощью пустой строки, `null` или `undefined`
 ```jsx harmony
 import { Group, ComboBox, Button } from '@skbkontur/react-ui';
@@ -81,11 +82,11 @@ const getItems = q => {
 </Group>
 ```
 
-ComboBox with popular values, complex menu items and total count message
+### ComboBox with popular values, complex menu items and total count message
 
 ```jsx harmony
-import { getCities } from './__mocks__/getCities';
-import { Gapped, MenuHeader, MenuSeparator } from '@skbkontur/react-ui';
+import { getCities } from '@skbkontur/react-ui/components/ComboBox/__mocks__/getCities';
+import { Gapped, MenuSeparator } from '@skbkontur/react-ui';
 import {MenuFooter} from "@skbkontur/react-ui/components/MenuFooter";
 
 let popularItems = [
@@ -148,7 +149,7 @@ let renderItem = item => (
 />;
 ```
 
-Переопределение `renderValue`, `renderItem` и `itemWrapper`:
+### Переопределение `renderValue`, `renderItem` и `itemWrapper`
 
 ```jsx harmony
 import OkIcon from '@skbkontur/react-icons/Ok';
@@ -279,7 +280,7 @@ const customRenderValue = item => (
 </Tooltip>;
 ```
 
-С подсветкой результата поиска:
+### Подсветка результата поиска
 
 ```jsx harmony
 import { Tooltip } from '@skbkontur/react-ui';
@@ -359,7 +360,7 @@ const renderItem = item => {
 </Tooltip>;
 ```
 
-Добавление элементов в меню
+### Добавление элементов в меню
 
 ```jsx harmony
 import { MenuItem } from '@skbkontur/react-ui';
@@ -466,48 +467,48 @@ class ComboboxExample extends React.Component {
 <ComboboxExample />;
 ```
 
-
+### Сброс контрола
 Если нужно сбросить контрол без изменения `value`, то можно использовать метод `reset`.
 
 ```jsx harmony
 import { Button } from '@skbkontur/react-ui';
 
-  const [selected, setSelected] = React.useState({ value: 1, label: "First" });
-  const ref = React.useRef(null);
+const [selected, setSelected] = React.useState({ value: 1, label: "First" });
+const ref = React.useRef(null);
 
-  const handleReset = () => {
-    if (ref.current) {
-      ref.current.reset();
-    }
-  };
-
-  const getItems = (q) =>
-    Promise.resolve(
-      [
-        { value: 1, label: "First" },
-        { value: 2, label: "Second" },
-        { value: 3, label: "Third" }
-      ].filter(
-        (x) =>
-          x.label.toLowerCase().includes(q.toLowerCase()) ||
-          x.value.toString(10) === q
-      )
-    );
+const handleReset = () => {
+  if (ref.current) {
+    ref.current.reset();
+  }
+};
 
-  <div>
-    <ComboBox
-      ref={ref}
-      getItems={getItems}
-      onValueChange={setSelected}
-      placeholder="Enter number"
-      value={selected}
-    />
-    <Button onClick={handleReset}>Reset</Button>
-  </div>
+const getItems = (q) =>
+  Promise.resolve(
+    [
+      { value: 1, label: "First" },
+      { value: 2, label: "Second" },
+      { value: 3, label: "Third" }
+    ].filter(
+      (x) =>
+        x.label.toLowerCase().includes(q.toLowerCase()) ||
+        x.value.toString(10) === q
+    )
+  );
+
+<div>
+  <ComboBox
+    ref={ref}
+    getItems={getItems}
+    onValueChange={setSelected}
+    placeholder="Enter number"
+    value={selected}
+  />
+  <Button onClick={handleReset}>Reset</Button>
+</div>
 
 ```
 
-#### Локали по умолчанию
+### Локали по умолчанию
 
 ```typescript static
 interface ComboBoxLocale {
@@ -529,7 +530,7 @@ const en_GB = {
 };
 ```
 
-У ComboBox есть 3 стандартных размера.
+### Размер
 ```jsx harmony
 import { Gapped } from '@skbkontur/react-ui';