@skbkontur/react-ui 0.0.0-2eafa74fd6 → 0.0.0-30619a873c

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2017 SKB Kontur
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2017 SKB Kontur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,79 +1,161 @@
-# React UI
-
-[![Build Status](https://tc.skbkontur.ru/app/rest/builds/buildType:FrontendInfrastructure_Packages_RunAll/statusIcon)](https://tc.skbkontur.ru/project.html?projectId=FrontendInfrastructure_Packages_ReactUI&tab=projectOverview)
-
-- [Квик-старт](#Квик-старт) **@skbkontur/react-ui** собранная версия библиотеки
-- [FAQ](#FAQ)
-
-### <a name="Квик-старт"></a>Квик-старт
-
-```bash
-yarn add @skbkontur/react-ui
-```
-
-И используем компонентики у себя в проекте:
-
-```jsx harmony static
-import { Button, Toast } from '@skbkontur/react-ui';
-
-const MyApp = () => (
-  <div>
-    Click this button <Button onClick={() => Toast.push('Hey!')}>Click me</Button>
-  </div>
-);
-```
-
-Если ругается, что `regeneratorRuntime` не определен, то необходимо подключить `regenerator-runtime` или `@babel/polyfill`, например в `index.html`
-
-Квик-старт подойдёт, если Вебпак настроен на сборку. Например, вы используете `create-react-app`. В противном случае добавьте в конфиг Вебпака `style-`, `css-` и `file-loader`
-
-### Хотим другой цвет кнопки!
-
-Нужно использовать [ThemeProvider](https://tech.skbkontur.ru/react-ui/#/Customization/ThemeProvider). Список переменных можно глянуть в [ThemeShowcase](https://tech.skbkontur.ru/react-ui/#/Customization/ThemeShowcase)
-
-### Глобальные css-стили приложения портят внешний вид контролов
-
-Если библиотека используется в проекте с легаси, где стилизация сделана прямо по названиям тегов, то внешний вид контролов из библиотеки может сильно испортиться
-
-Если нет возможности разобрать легаси, то можно увеличить специфичность селекторов в библиотеке, тогда стили контролов будут приоритетнее стилей из легаси проекта
-
-Специфичность достигается за счет n-кратного повторения css-класса `react-ui` в селекторе стилей. Количество повторений задается через переменную `specificityLevel`, значение по умолчанию равно нулю, то есть по умолчанию css-класс `react-ui` никак ни на что не будет влиять
-
-Чтобы специфичность заработала в легаси проекте, react-блок, в котором используются компоненты из библиотеки, должен быть обернут в тег с css-классом `react-ui`
-
-Пример настройки специфичности:
-
-```js static
-import { Upgrade } from '@skbkontur/react-ui/lib/Upgrades';
-
-Upgrade.setSpecificityLevel(1);
-```
-
-Специфичность должна устанавливаться в коде раньше импорта любых компонентов из библионтеки.
-
-## <a name="FAQ"></a>FAQ
-
-### Сломались стили при использовании css-loader 2.x (create-react-app/CRA 3.x)
-
-Во [2-й версии](https://github.com/webpack-contrib/css-loader/releases/tag/v2.0.0), `css-loader` отключили использование `css-modules` по умолчанию.
-**Решение**: В опциях к `css-loader` явно задать `modules: 'global'`.
-
-### Как использовать react-ui с storybook 5.x?
-
-В 5-й версии изменилось [API сторибука для кастомизации настроек webpack](https://github.com/storybooks/storybook/blob/v5.0.0/MIGRATION.md#webpack-config-simplifcation).
-Кроме того был изменен дефолтный webpack конфиг. Это порождает проблемы вида [storybooks/storybook#4891](https://github.com/storybooks/storybook/issues/4891).
-**Решение**: Заменить лоадеры для `css/less`. Например [так](https://github.com/storybooks/storybook/issues/6319#issuecomment-477852640) на свои
-
-### Возникает ошибка `Error: Can't resolve 'mask-char-font/font.eot'`
-
-Ошибка проявляется при использовании `css-loader@1.x` с выставленой опцией `modules`.
-**Решение**: Обновить `css-loader` до 2-й версии или дополнительно указать опцию `url: false`
-
-### Не могу прокинуть css-класс компонентам. Как кастомизировать?
-
-Никак.
-
-### Помощь в развитии
-
-Мы рады любой сторонней помощи. Не стесняйтесь писать в [issues](https://github.com/skbkontur/retail-ui/issues)
-баги и идеи для развития библиотеки.<br />
+# React UI
+
+[![Build Status](https://tc.skbkontur.ru/app/rest/builds/buildType:FrontendInfrastructure_Packages_RunAll/statusIcon)](https://tc.skbkontur.ru/project.html?projectId=FrontendInfrastructure_Packages_ReactUI&tab=projectOverview)
+
+- [Как использовать](#как-использовать)
+- [FAQ](#faq)
+
+### Как использовать
+
+```bash
+yarn add @skbkontur/react-ui
+```
+
+```jsx harmony static
+import { Button, Toast } from '@skbkontur/react-ui';
+
+const MyApp = () => (
+  <div>
+    Click this button <Button onClick={() => Toast.push('Hey!')}>Click me</Button>
+  </div>
+);
+```
+
+### Хотим другой цвет кнопки!
+
+Нужно использовать [ThemeContext](https://tech.skbkontur.ru/react-ui/#/Customization/ThemeContext). Список переменных
+можно глянуть в [ThemeShowcase](https://tech.skbkontur.ru/react-ui/#/Customization/ThemeShowcase)
+
+### StrictMode
+
+Начиная с версий `@skbkontur/react-ui@3.10.0` и `@skbkontur/react-ui-validations@1.7.0`, библиотека поддерживает работу
+в React.StrictMode.
+
+Некоторым компонентам библиотеки необходимо иметь доступ до корневой DOM-ноды своих children. Ранее для этого
+использовался метод findDomNode, который в StrictMode запрещён. Теперь получение DOM-ноды реализовано в библиотеке через
+ref, из-за чего появились некоторые требования к компонентам, передаваемым в Hint, Tooltip, Popup или Tab:
+
+- при передаче функциональных компонентов, они должны использовать `React.ForwardRef`:
+
+```js static
+import { Hint } from '@skbkontur/react-ui';
+
+const CustomFunctionComponent = React.forwardRef(
+  (props, ref) => <div ref={ref}>children text</div>
+);
+
+export const WithFunctionChildren = () => (
+  <React.StrictMode>
+    <Hint pos="top" text="Something will never be changed" manual opened>
+      <CustomFunctionComponent/>
+    </Hint>
+  </React.StrictMode>
+);
+```
+
+- при использовании хука `useImperativeHandle`, возвращаемый объект должен реализовывать метод `getRootNode`,
+  возвращающий DOM-ноду:
+
+```js static
+import { Hint } from '@skbkontur/react-ui';
+
+const ImperativeHandleComponent = React.forwardRef(function FN(_, ref) {
+  const rootNode = React.useRef < HTMLDivElement > (null);
+  React.useImperativeHandle(ref, () => ({
+    foo: 'bar',
+    getRootNode: () => rootNode.current,
+  }));
+  return <div ref={rootNode}>children text</div>;
+});
+
+export const WithImperativeHandleChildren = () => (
+  <React.StrictMode>
+    <Hint pos="top" text="Something will never be changed" manual opened>
+      <ImperativeHandleComponent/>
+    </Hint>
+  </React.StrictMode>
+);
+```
+
+- при передаче классовых компонентов, их инстанс должен реализовывать метод `getRootNode`, возвращающий DOM-ноду:
+
+```js static
+import { Hint } from '@skbkontur/react-ui';
+
+class CustomClassComponent extends React.Component {
+  rootNode = React.createRef();
+
+  render() {
+    return <div ref={this.rootNode}>children text</div>;
+  }
+
+  getRootNode() {
+    return this.rootNode.current;
+  }
+}
+
+export const WithClassChildren = () => (
+  <React.StrictMode>
+    <Hint pos="top" text="Something will never be changed" manual opened>
+      <CustomClassComponent/>
+    </Hint>
+  </React.StrictMode>
+);
+```
+
+В случае несоблюдения требования, будет использоваться старый метод findDomNode, который не совместим с StrictMode.
+
+Подробнее в [пулл-реквесте](https://github.com/skbkontur/retail-ui/pull/2518)
+
+## FAQ
+
+### Выпадашки и несколько react-рутов
+
+Реакт позволяет создавать рут внутри рута. Но контекст между ними не прокидывается. Это вызывает проблемы в работе
+различных выпадашек, типа `Tooltip`, `Select`, `Modal` и других.
+
+В версии `4.26.0` появился мехнизм, который решает большинство этих проблем. Если вложенный реакт-рут является виджетом,
+то будет достаточно обновить библиотеку только в нём.
+
+Однако, при удалении html-элемента, который был реакт-рутом, его необходимо предварительно явно размонтировать:
+
+```tsx static
+React.useLayoutEffect(
+  () => () => {
+    if (React.version === 17) {
+      rootRef.current && ReactDOM.unmountComponentAtNode(rootRef.current);
+    } else if (React.version === 18) {
+      setTimeout(() => reactRoot.current?.unmount());
+    }
+  },
+  [],
+);
+```
+
+### Отключение анимаций во время тестирования
+
+Анимации в компонентах отключаются любой из следующих глобальных переменных:
+
+```static
+REACT_UI_TEST
+process.env.NODE_ENV === 'test'
+process.env.REACT_UI_TEST
+process.env.REACT_APP_REACT_UI_TEST
+process.env.STORYBOOK_REACT_UI_TEST
+```
+
+### Прокидывание className и style компонентам
+
+Начиная с версии 2.14.0, стало возможным передавать в компоненты свои css-классы для дополнительной стилизации. Однако,
+не стоит пользоваться этой возможностью для вмешательства во внутренние стили компонентов. Верстка компонентов может
+быть изменена в любой момент без предупреждения, что приведет к поломке ваших переопределенных стилей.
+
+### Мобильная верстка
+
+С версии 4.0 многие компоненты умеют адаптироваться под мобильные устройства. Подробнее об управлении этим поведением
+в [MOBILES.md](https://github.com/skbkontur/retail-ui/blob/master/packages/react-ui/MOBILES.md).
+
+### Помощь в развитии
+
+Мы рады любой сторонней помощи. Не стесняйтесь писать в [issues](https://github.com/skbkontur/retail-ui/issues)
+баги и идеи для развития библиотеки.<br />

package/cjs/components/Autocomplete/Autocomplete.d.ts

@@ -0,0 +1,131 @@
+import React, { AriaAttributes } from 'react';
+import PropTypes from 'prop-types';
+import { InputProps } from '../Input';
+import { Nullable, Override } from '../../typings/utility-types';
+import { CommonProps, CommonWrapperRestProps } from '../../internal/CommonWrapper';
+import { SizeProp } from '../../lib/types/props';
+export interface AutocompleteProps extends CommonProps, Pick<AriaAttributes, 'aria-label'>, Override<InputProps, {
+    /** Задает функцию, которая отрисовывает элементы меню. */
+    renderItem?: (item: string) => React.ReactNode;
+    /** Задает промис, который резолвит элементы меню. */
+    source?: string[] | ((patter: string) => Promise<string[]>);
+    /** Отключает использование портала. */
+    disablePortal?: boolean;
+    /** Определяет, нужно ли показывать тень у выпадающего меню. */
+    hasShadow?: boolean;
+    /** Задает выравнивание выпадающего меню. */
+    menuAlign?: 'left' | 'right';
+    /** Задает максимальную высоту выпадающего меню. */
+    menuMaxHeight?: number | string;
+    /** Задает ширину выпадающего меню. */
+    menuWidth?: number | string;
+    /** Отключает скролл окна, когда меню открыто. */
+    preventWindowScroll?: boolean;
+    /** Задает функцию, которая вызывается при изменении value. */
+    onValueChange: (value: string) => void;
+    /** Задает функцию, которая вызывается при потере автокомплитом фокуса. */
+    onBlur?: () => void;
+    /** Задаёт размер инпута. */
+    size?: SizeProp;
+    /** Задает значение автокомплита. */
+    value: string;
+    /** Задает текст заголовка выпадающего меню в мобильной версии. */
+    mobileMenuHeaderText?: string;
+}> {
+    /**
+     * Позволяет вручную задать текущую позицию выпадающего окна
+     */
+    menuPos?: 'top' | 'bottom';
+}
+export interface AutocompleteState {
+    items: Nullable<string[]>;
+    selected: number;
+    focused: boolean;
+    isMobileOpened: boolean;
+}
+export declare const AutocompleteDataTids: {
+    readonly root: "Autocomplete__root";
+    readonly menu: "Autocomplete__menu";
+};
+export declare const AutocompleteIds: {
+    readonly menu: "Autocomplete__menu";
+};
+type DefaultProps = Required<Pick<AutocompleteProps, 'renderItem' | 'size' | 'disablePortal' | 'hasShadow' | 'menuMaxHeight' | 'preventWindowScroll'>>;
+/**
+ * `Autocomplete` — стандартный инпут с подсказками.
+ *
+ * Подсказки определяются в пропе `source`.
+ * Все свойства передаются во внутренний `Input`.
+ */
+export declare class Autocomplete extends React.Component<AutocompleteProps, AutocompleteState> {
+    static __KONTUR_REACT_UI__: string;
+    static displayName: string;
+    static propTypes: {
+        /**
+         * Функция для отрисовки элемента в выпадающем списке. Единственный аргумент
+         * — *item*.
+         */
+        renderItem: PropTypes.Requireable<(...args: any[]) => any>;
+        /**
+         * Если передан массив, то совпадения ищутся по этому массиву.
+         *
+         * Если передается функция, то она должна возвращать thenable, который
+         * резолвится уже отфильтрованным массивом. Возвращенный thenable может
+         * иметь метод cancel, который будет вызван при отмене поиска (пользователь
+         * изменил строку поиска, автокомплит потерял фокус).
+         * ```
+         * function(pattern) {
+         *   return service.findAll(pattern);
+         * }
+         * ```
+         */
+        source: PropTypes.Requireable<NonNullable<any[] | ((...args: any[]) => any) | null | undefined>>;
+    };
+    static defaultProps: DefaultProps;
+    state: AutocompleteState;
+    private theme;
+    private readonly locale;
+    private isMobileLayout;
+    private opened;
+    private input;
+    private menu;
+    private menuId;
+    private rootSpan;
+    private mobilePopup;
+    private requestId;
+    private getProps;
+    private setRootNode;
+    /**
+     * @public
+     */
+    focus(): void;
+    /**
+     * @public
+     */
+    blur(): void;
+    componentDidUpdate(prevProps: AutocompleteProps): void;
+    render(): React.JSX.Element;
+    renderMain: (props: CommonWrapperRestProps<AutocompleteProps>) => React.JSX.Element;
+    private renderHints;
+    private renderMenu;
+    private renderMobileMenu;
+    private getItems;
+    private handleValueChange;
+    private handleCloseMobile;
+    private handleKeyPressMobile;
+    private handleFocus;
+    private handleBlur;
+    private handleClickOutside;
+    private handleKeyDown;
+    private handleMenuItemClick;
+    private getAnchor;
+    private handleItemClick;
+    private choose;
+    private updateItems;
+    private fireChange;
+    private refInput;
+    private refMenu;
+    private refRootSpan;
+    private refMobilePopup;
+}
+export {};