@skbkontur/react-ui 0.0.0-80ce75eca6 → 0.0.0-8431409396

package/README.md

@@ -1,61 +1,133 @@
-# 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)
-
-### Глобальные 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);
-```
-
-Специфичность должна устанавливаться в коде раньше импорта любых компонентов из библиотеки.
-
-## FAQ
-
-### Есть ли способ отключить анимации во время тестирования?
-
-Анимации в компонентах отключаются переменной окружения `process.env.NODE_ENV === 'test'`.
-
-### Прокидывание className и style компонентам
-
-Начиная с версии 2.14.0, стало возможным передавать в компоненты свои 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
+
+### Отключение анимаций во время тестирования
+
+Анимации в компонентах отключаются любой из следующих глобальных переменных:
+
+```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/ROADMAP.md

@@ -0,0 +1,116 @@
+# 5.0 Август 2022
+
+- <input type="checkbox" readonly /> Адаптивные версии компонентов DatePicker, Tabs, Paging для мобильных устройств.
+- <input type="checkbox" readonly /> Обновление дизайна компонентов в соответствии с новым фирменным стилем и визуальным языком.
+- <input type="checkbox" readonly /> Добавление нового компонента — панель действий.
+
+# 2021
+
+- <input type="checkbox" readonly checked/> Адаптивные версии компонентов использующих выпадающие меню — селекта, автокомплита, комбобокса для мобильных [#1963](https://github.com/skbkontur/retail-ui/issues/1963).
+- <input type="checkbox" readonly checked/> Адаптивные версии модалки и сайдпейджа.
+- <input type="checkbox" readonly checked/> Поддержка [StrictMode](https://reactjs.org/docs/strict-mode.html) и React 18.
+- <input type="checkbox" readonly checked/> Новые цвета контролов. Обновление в соответствии с «переходным» дизайном.
+- <input type="checkbox" readonly checked/> Официальный старт поддержки темной темы.
+- <input type="checkbox" readonly checked/> Адаптация контролов для использования с шрифтом Lab Grotesque.
+- <input type="checkbox" readonly checked/> Добавление компонента FileUploader для загрузки файлов на сервер.
+- <input type="checkbox" readonly checked/> Добавление компонента [GlobalLoader](https://guides.kontur.ru/components/global-loader/).
+
+### 3.0 Май 2021
+
+- <input type="checkbox" readonly checked/> Релиз версии 3.0 [#2123](https://github.com/skbkontur/retail-ui/issues/2123)
+- <input type="checkbox" readonly checked/> Второй этап поддержки 8px сетки по Контур.Гайдам [#1733](https://github.com/skbkontur/retail-ui/issues/1733)
+
+
+# 2020
+
+
+### 2.4 Август 2020
+
+- <input type="checkbox" readonly checked/> Первый этап дизайн-решения по сбору телеметрии — пакет React Sorge. [#1539](https://github.com/skbkontur/retail-ui/issues/1539)
+- <input type="checkbox" readonly checked/> Создание и выпуск темы с новыми размерами контролов для поддержки 8px сетки по Контур.Гайдам. [#1733](https://github.com/skbkontur/retail-ui/issues/1733)
+
+
+### 2.0.0 Март 2020
+
+- <input type="checkbox" readonly checked/> Релиз версии [2.0](https://github.com/skbkontur/retail-ui/blob/master/packages/react-ui/MIGRATION.md)
+- <input type="checkbox" readonly checked/> Уменьшение техдолга [#1578](https://github.com/skbkontur/retail-ui/issues/1578)
+- <input type="checkbox" readonly checked/> Переезд всех стилей с Less на CSS-in-JS [#1625](https://github.com/skbkontur/retail-ui/issues/1625)
+- <input type="checkbox" readonly checked/> Перенос kontur-specific компонентов в приватную библиотеку (Fias, TopBar, Logotype, Spinner) [#1842](https://github.com/skbkontur/retail-ui/issues/1842)
+- <input type="checkbox" readonly checked/> Реорганизация файлов компонентов в библиотеке для упрощения импорта и работы tree-shaking [#1772](https://github.com/skbkontur/retail-ui/issues/1772)
+- <input type="checkbox" readonly checked/> Отказ от retail-ui, паблиш только пакета @skbkontur/react-ui
+
+# 2019
+
+### Декабрь 2019
+
+- <input type="checkbox" readonly checked/> Создание отдельного репозитория для «велосипедов» (парковка для общеконтуровских решений для фронта), в которую пойдет приватная библиотека для kontur-specific компонентов типа Fias, TopBar, Logotype, Spinner.
+- <input type="checkbox" readonly checked/> Обновление react-styleguidist и примеров в доке [#1791](https://github.com/skbkontur/retail-ui/issues/1791)
+
+### Ноябрь 2019
+
+- <input type="checkbox" readonly checked/> Обновлены зависимости, в том числе storybook/webpack/react/etc [#1756](https://github.com/skbkontur/retail-ui/pull/1756)
+
+### Октябрь 2019
+
+- <input type="checkbox" readonly checked/> ZIndex: add layers priority для [#776](https://github.com/skbkontur/retail-ui/issues/776)
+
+### Сентябрь 2019
+
+- <input type="checkbox" readonly checked/> Библиотека идентификации нажатой клавиши [#1639](https://github.com/skbkontur/retail-ui/pull/1639)
+
+### Август 2019
+
+- <input type="checkbox" readonly checked/> Отказ от SauceLabs в пользу SeleniumGrid для скриншотных тестов [#1131](https://github.com/skbkontur/retail-ui/issues/1131)
+
+### Июль 2019
+
+- <input type="checkbox" readonly checked/> Гайдлайн для контрибьюторов [#1274](https://github.com/skbkontur/retail-ui/pull/1274)
+
+### Июнь 2019
+
+- <input type="checkbox" readonly checked/> Старт поддержки `LTS` версии библиотеки [#1295](https://github.com/skbkontur/retail-ui/issues/1295)
+- <input type="checkbox" readonly checked/> Локализация DateInput и DatePicker [#1278](https://github.com/skbkontur/retail-ui/pull/1278)
+- <input type="checkbox" readonly checked/> Реализация механизма кастомизации на `css-in-js` [#1318](https://github.com/skbkontur/retail-ui/issues/1318)
+
+### Май 2019
+
+- <input type="checkbox" readonly checked/> Обновление документации `react-ui-validations` [#1430](https://github.com/skbkontur/retail-ui/pull/1430)
+- <input type="checkbox" readonly checked/> Реализация декларативного механизма валидаций `react-ui-validations` [#1421](https://github.com/skbkontur/retail-ui/pull/1421)
+
+### Апрель 2019
+
+- <input type="checkbox" readonly checked/> Добавлены скриншотные тесты на плоскую тему [#1253](https://github.com/skbkontur/retail-ui/pull/1253)
+- <input type="checkbox" readonly checked/> Ссылки со стайлгайдиста на ишьюс гитхаба и гайды  [#1376](https://github.com/skbkontur/retail-ui/pull/1376)
+
+### Март 2019
+
+- <input type="checkbox" readonly checked/> Интеграция `react-ui-validations` [#917](https://github.com/skbkontur/retail-ui/issues/917)
+- <input type="checkbox" readonly checked/> Добавление поддержки локализации компонентов
+
+### Февраль 2019
+
+- <input type="checkbox" readonly checked/> Обновление версии через CI [#1042](https://github.com/skbkontur/retail-ui/issues/1042)
+
+### Январь 2019
+
+- <input type="checkbox" readonly checked/> Добавление свойств `prefix/postfix` для `Input` [#727](https://github.com/skbkontur/retail-ui/issues/727)
+
+# 2018
+
+### Декабрь 2018
+
+- <input type="checkbox" readonly checked/> Переезд с Travis на TeamCity [#985](https://github.com/skbkontur/retail-ui/issues/985)
+- <input type="checkbox" readonly checked/> Оптимизация тестов `react-ui-testing` [#872](https://github.com/skbkontur/retail-ui/issues/872)
+- <input type="checkbox" readonly checked/> Улучшение `MaskedInput` [#900](https://github.com/skbkontur/retail-ui/pull/900)
+- <input type="checkbox" readonly checked/> Скриншоты на `ComboBox` [#929](https://github.com/skbkontur/retail-ui/pull/929)
+- <input type="checkbox" readonly checked/> Методы `open/close` для `ComboBox` [#967](https://github.com/skbkontur/retail-ui/pull/967)
+- <input type="checkbox" readonly checked/> Доработки по `Fias` [#960](https://github.com/skbkontur/retail-ui/pull/960)
+
+### Ноябрь 2018
+
+- <input type="checkbox" readonly checked/> Версии библиотеки в `styleguidist` [#919](https://github.com/skbkontur/retail-ui/pull/919)
+- <input type="checkbox" readonly checked/> Поддержка праздничных дней [#904](https://github.com/skbkontur/retail-ui/pull/904)
+- <input type="checkbox" readonly checked/> Новые стили для кнопок-стрелок [#839](https://github.com/skbkontur/retail-ui/pull/839)
+- <input type="checkbox" readonly checked/> Компонент `Fias` [#800](https://github.com/skbkontur/retail-ui/pull/800)
+- <input type="checkbox" readonly checked/> Интеграция `react-ui-testing` [#813](https://github.com/skbkontur/retail-ui/pull/813), [#738](https://github.com/skbkontur/retail-ui/pull/738)
+- <input type="checkbox" readonly checked/> Новое состояние `Checkbox` [#820](https://github.com/skbkontur/retail-ui/pull/820)

package/SSR.md

@@ -0,0 +1,59 @@
+## Server Side Rendering
+
+Контролы поддерживают рендеринг на стороне сервера начиная с версии `2.12.0`.
+Но для предварительного рендеринга стилей понадобится установить пакеты `@emotion/react` и `@emotion/server`. И импортировать `cache` из библиотеки контролов.
+
+Подробнее - [https://emotion.sh](https://emotion.sh/docs/ssr)
+
+Условный файл `server.js` будет выглядеть примерно так:
+
+```typescript static
+import React from 'react';
+import { renderToString } from 'react-dom/server';
+import { CacheProvider } from '@emotion/react';
+import createEmotionServer, { EmotionCritical } from '@emotion/server/create-instance';
+import { cache } from '@skbkontur/react-ui/lib/theming/Emotion';
+
+import { App } from './App';
+
+const { extractCritical } = createEmotionServer(cache);
+
+const element = (
+  <CacheProvider value={cache}>
+    <App />
+  </CacheProvider>
+);
+
+const { html, css, ids } = extractCritical(renderToString(element));
+
+res.status(200).header('Content-Type', 'text/html').send(`<!DOCTYPE html>
+<html>
+  <head>
+    <style data-emotion-css="${cache.key} ${ids.join(' ')}">${css}</style>
+  </head>
+  <body>
+    <div id="root">${html}</div>
+    <script src="client.js"></script>
+  </body>
+</html>`);
+```
+
+`client.js`
+
+```typescript static
+import React from 'react';
+import ReactDOM from 'react-dom';
+import { CacheProvider } from '@emotion/react';
+import { cache } from '@skbkontur/react-ui/lib/theming/Emotion';
+
+import { App } from './App';
+
+ReactDOM.hydrate(
+  <CacheProvider value={cache}>
+    <App />
+  </CacheProvider>,
+  document.getElementById('root'),
+);
+```
+
+Для `react-ui` версии `2.x` актуален [старый пример](https://github.com/skbkontur/retail-ui/blob/2.x/packages/react-ui/SSR.md) с Emotion 10.

package/components/Autocomplete/Autocomplete.md

@@ -1,7 +1,21 @@
-```jsx
-let items = ['Grey Face', 'Grey Space', 'Kappa', 'Keepo', 'Resident Sleeper'];
-
-let initialState = { value: 'Kappa' };
-
-<Autocomplete source={items} value={state.value} onValueChange={value => setState({ value })} />;
-```
+```jsx harmony
+const items = ['Grey Face', 'Grey Space', 'Kappa', 'Keepo', 'Resident Sleeper'];
+
+const [value, setValue] = React.useState('Kappa');
+
+<Autocomplete source={items} value={value} onValueChange={setValue} />;
+```
+
+Очистить значение в `Autocomplete` можно только с помощью пустой строки
+```jsx harmony
+import { Button, Group } from '@skbkontur/react-ui';
+
+const items = ['Grey Face', 'Grey Space', 'Kappa', 'Keepo', 'Resident Sleeper'];
+
+const [value, setValue] = React.useState('Kappa');
+
+<Group>
+  <Autocomplete source={items} value={value} onValueChange={setValue} />
+  <Button onClick={() => setValue('')}>Очистить</Button>
+</Group>
+```

package/components/Autocomplete/Autocomplete.styles.ts

@@ -0,0 +1,11 @@
+import { css, memoizeStyle } from '../../lib/theming/Emotion';
+import { Theme } from '../../lib/theming/Theme';
+
+export const styles = memoizeStyle({
+  root(t: Theme) {
+    return css`
+      display: inline-block;
+      width: ${t.inputWidth};
+    `;
+  },
+});