@skbkontur/react-ui 0.0.0-a8f1c3e7a1 → 0.0.0-ab4ec97409

package/lib/locale/LOCALECONTEXT.md

@@ -1,222 +0,0 @@
-Локализации компонентов через контекст `React.Context<LocaleContextProps>`
-
-```typescript static
-interface LocaleContextProps {
-  locale?: LocaleControls;
-  langCode?: LangCodes;
-}
-```
-
-Доступные языки
-
-```typescript static
-enum LangCodes {
-  ru_RU = 'ru_RU',
-  en_GB = 'en_GB',
-}
-```
-
-LocaleControls
-
-```typescript static
-interface LocaleControls {
-  Autocomplete?: AutocompleteLocale;
-  Spinner?: SpinnerLocale;
-  TokenInput?: TokenInputLocale;
-  ComboBox?: ComboBoxLocale;
-  Select?: SelectLocale;
-  Paging?: PagingLocale;
-  DatePicker?: DatePickerLocale;
-}
-```
-
-### Использование
-
-Дефолтная локализация `<TokenInput />`
-
-```jsx harmony
-import { LangCodes, LocaleContext, TokenInput, TokenInputType } from '@skbkontur/react-ui';
-
-const delay = time => args => new Promise(resolve => setTimeout(resolve, time, args));
-
-<LocaleContext.Provider value={{ langCode: LangCodes.en_GB }}>
-  <TokenInput type={TokenInputType.Combined} getItems={() => Promise.resolve([]).then(delay(500))} />
-</LocaleContext.Provider>;
-```
-
-Кастомная локализация `<TokenInput />`
-
-```jsx harmony
-import { LocaleContext, TokenInput, TokenInputType } from '@skbkontur/react-ui';
-
-const delay = time => args => new Promise(resolve => setTimeout(resolve, time, args));
-
-const customLocale = {
-  TokenInput: {
-    addButtonComment: 'Press Enter or type Spacebar',
-  },
-};
-
-<LocaleContext.Provider value={{ locale: customLocale }}>
-  <TokenInput type={TokenInputType.Combined} delimiters={[' ']} getItems={() => Promise.resolve([]).then(delay(500))} />
-</LocaleContext.Provider>;
-```
-
-Некоторые контролы используют компоненты других контролов.
-<br/>
-Для инкапсуляции локализации можно использовать несколько контекстов.
-
-```jsx harmony
-import { Gapped, LangCodes, LocaleContext, Spinner, TokenInput } from '@skbkontur/react-ui';
-
-const delay = time => args => new Promise(resolve => setTimeout(resolve, time, args));
-
-const customLocale = {
-  Spinner: {
-    loading: 'awaiting...',
-  },
-};
-
-<LocaleContext.Provider value={{ langCode: LangCodes.en_GB }}>
-  <Gapped vertical gap={10}>
-    <LocaleContext.Provider value={{ locale: customLocale }}>
-      <TokenInput getItems={() => Promise.resolve([]).then(delay(1500))} />
-    </LocaleContext.Provider>
-    <TokenInput getItems={() => Promise.resolve([]).then(delay(1500))} />
-    <Spinner />
-  </Gapped>
-</LocaleContext.Provider>;
-```
-
-Локализация функционального компонента через useContext.
-
-```jsx harmony
-import { useContext } from 'react';
-import { LangCodes, LocaleContext } from '@skbkontur/react-ui';
-
-const languages = {
-  [LangCodes.ru_RU]: 'Русский',
-  [LangCodes.en_GB]: 'English',
-};
-
-function LocalizedByHook() {
-  const { langCode } = useContext(LocaleContext);
-  return <div>{languages[langCode]}</div>;
-}
-
-<LocaleContext.Provider value={{ langCode: LangCodes.en_GB }}>
-  <LocalizedByHook />
-</LocaleContext.Provider>;
-```
-
-### Обзор всех доступных контролов
-
-```jsx harmony
-import {
-  ComboBox,
-  DateInput,
-  DatePicker,
-  Gapped,
-  LocaleContext,
-  Paging,
-  Select,
-  Spinner,
-  TokenInput,
-  LangCodes,
-} from '@skbkontur/react-ui';
-import { TokenInputType } from '@skbkontur/react-ui/components/TokenInput';
-
-const delay = time => args => new Promise(resolve => setTimeout(resolve, time, args));
-
-const items = [
-  { label: 'aaa', value: 1 },
-  { label: 'bbb', value: 2 },
-  { label: 'ccc', value: 3 },
-];
-
-const LocalizationControlNames = {
-  ComboBox: 'ComboBox',
-  Spinner: 'Spinner',
-  TokenInput: 'TokenInput',
-  Select: 'Select',
-  Paging: 'Paging',
-  DatePicker: 'DatePicker',
-  DateInput: 'DateInput',
-};
-
-class LocalizationControls extends React.Component {
-  constructor(props) {
-    super(props);
-    this.state = {
-      langCode: LangCodes.ru_RU,
-      controlName: null,
-    };
-  }
-
-  render() {
-    // попробуйте кастомизировать локаль любого контрола
-    const customLocaleRU = {};
-    const customLocaleEN = {};
-
-    const locale = this.state.langCode === LangCodes.en_GB ? customLocaleEN : customLocaleRU;
-
-    return (
-      <Gapped vertical gap={10}>
-        <Select
-          value={this.state.langCode}
-          placeholder="Выбрать язык"
-          items={Object.values(LangCodes)}
-          onValueChange={langCode => this.setState({ langCode })}
-        />
-        <Select
-          value={this.state.controlName}
-          placeholder="Выбрать контрол"
-          items={Object.values(LocalizationControlNames)}
-          onValueChange={controlName => this.setState({ controlName })}
-        />
-        <LocaleContext.Provider value={{ langCode: this.state.langCode, locale: locale }}>
-          {this.getControl(this.state.controlName)}
-        </LocaleContext.Provider>
-      </Gapped>
-    );
-  }
-
-  getControl(controlName) {
-    switch (controlName) {
-      case LocalizationControlNames.ComboBox:
-        return (
-          <ComboBox
-            getItems={str => Promise.resolve(items.filter(({ label }) => label.includes(str))).then(delay(500))}
-            onValueChange={({ label: langCode }) => this.setState({ langCode })}
-          />
-        );
-
-      case LocalizationControlNames.TokenInput:
-        return <TokenInput type={TokenInputType.Combined} getItems={() => Promise.resolve([]).then(delay(500))} />;
-
-      case LocalizationControlNames.Spinner:
-        return <Spinner />;
-
-      case LocalizationControlNames.DatePicker:
-        return <DatePicker value="30.12.2012" />;
-
-      case LocalizationControlNames.DateInput:
-        return <DateInput value="30.12.2012" />;
-
-      case LocalizationControlNames.Select:
-        return <Select />;
-
-      case LocalizationControlNames.Paging:
-        return <Paging activePage={1} pagesCount={12} onPageChange={value => value} />;
-    }
-    return null;
-  }
-}
-
-<LocalizationControls />;
-```
-
-### Локализация @skbkontur/react-ui-addons
-
-Компоненты `@skbkontur/react-ui-addons` так же поддерживают локализацию через `LocaleContext` из `@skbkontur/react-ui`.
-См. пример с кастомной локализацией. Дефолтные локали описаны для каждого компонента в [докумендации аддонов](https://ui.gitlab-pages.kontur.host/docs/#/react-ui-addons).

package/lib/theming/ThemeContext.md

@@ -1,265 +0,0 @@
-Для кастомизации компонентов используется ThemeContext, реализуемый через `React.Context<Theme>`
-
-Механизм работы: динамические стили генерируются в зависимости от темы в процессе render'а с помощью <a href="https://www.npmjs.com/package/emotion" target="_blank">emotion</a>, полученные классы добавляются в `className` соответствующих элементов.
-
-Тема задается с помощью `ThemeContext.Provider`:
-
-```jsx static
-import { ThemeContext } from '@skbkontur/react-ui';
-
-<ThemeContext.Provider value={theme}>{/* ... */}</ThemeContext.Provider>;
-```
-
-Использовать тему в компоненте можно через `ThemeContext.Consumer`:
-
-```jsx static
-import { ThemeContext, Button } from '@skbkontur/react-ui';
-
-<ThemeContext.Consumer>
-  {theme => /* ... */ }
-</ThemeContext.Consumer>
-```
-
-`useContext` в функциональных компонентах:
-
-```typescript static
-const theme = useContext(ThemeContext);
-```
-
-или задать `contextType` для класса:
-
-```typescript static
-public static contextType = ThemeContext;
-public context: Theme = this.context;
-```
-
-Список существующих тем:
-
-| Имя                     | Описание                                          |
-|-------------------------|---------------------------------------------------|
-| `LIGHT_THEME` | Текущая светлая тема, включена по умолчанию. Всегда включает в себя актуальные визуальные обновления. |
-| `DARK_THEME` | Текущая тёмная тема. Всегда включает в себя актуальные визуальные обновления. |
-| `LIGHT_THEME_2022_0` | Вариант светлой темы без актуальных визуальных обновлений. |
-| `DARK_THEME_2022_0` | Вариант тёмной темы без актуальных визуальных обновлений. |
-
-Если не нужны постоянные визуальные изменения, то можно использовать вариант `_2022_N`. В будущем, новые варианты с постфиксом `_2022_N` будут появлятся при обновлении дизайн системы.
-
-## Примеры использования
-
-### Создание собственной темы
-
-Собственные значения нужно передать в `ThemeFactory.create` и получившуюся тему можно использовать в `ThemeContext.Provider`. `ThemeFactory` расширяет переданный объект, задавая в качестве прототипа объект темы по умолчанию.
-
-```jsx harmony
-import { ThemeContext, ThemeFactory } from '@skbkontur/react-ui';
-import { ShowcaseGroup } from '@skbkontur/react-ui/internal/ThemePlayground/ShowcaseGroup';
-
-const myTheme = ThemeFactory.create({ btnBorderRadiusSmall: '10px' });
-
-<ThemeContext.Provider value={myTheme}>
-  <div style={{height: '100%', background: '#fff', padding: '16px'}}>
-    <ShowcaseGroup title="My Theme" />
-  </div>
-</ThemeContext.Provider>;
-```
-
-Вторым аргументом `ThemeFactory.create` может принимать объект, который будет использован в качестве базовой темы.
-
-```jsx static
-import { ThemeFactory, LIGHT_THEME } from '@skbkontur/react-ui';
-
-const myFlatTheme = ThemeFactory.create({ btnBorderRadiusSmall: '10px' }, LIGHT_THEME);
-```
-
-### Использование темы в своих компонентах
-
-```jsx harmony
-import { useContext } from 'react';
-import { ThemeContext, Button } from '@skbkontur/react-ui';
-
-function ButtonLinkWrapper(props) {
-  const theme = useContext(ThemeContext);
-
-  return (
-    <Button use="link" {...props}>
-      {props.children}
-      <span style={{ color: theme.textColorDefault }}> ↗</span>
-    </Button>
-  );
-}
-
-<ButtonLinkWrapper>ButtonLinkWrapper</ButtonLinkWrapper>;
-```
-
-### Добавление своих переменных
-
-Если вы хотите дополнить одну из тем новыми переменными для своих компонентов, то вы можете использовать отдельный контекст в расширенным объектом темы.
-
-```jsx harmony
-import { useContext } from 'react';
-import { ThemeFactory, Button } from '@skbkontur/react-ui';
-
-const MyThemeContext = React.createContext(ThemeFactory.create({ myTextColor: 'orange' }));
-
-MyThemeContext.displayName = 'MyThemeContext';
-
-function ButtonLinkWrapper(props) {
-  const theme = useContext(MyThemeContext);
-
-  return (
-    <Button use="link" {...props}>
-      {props.children}
-      <span style={{ color: theme.myTextColor }}> ↗</span>
-    </Button>
-  );
-}
-
-<ButtonLinkWrapper>ButtonLinkWrapper</ButtonLinkWrapper>;
-```
-
-### Кастомизация в legacy-приложениях
-
-В случае, если контролы рендерятся через какую-то общую обертку, достаточно добавить в нее `ThemeContext.Provider` с вашей темой. В противном случае, вам подойдет метод `ThemeFactory.overrideDefaultTheme()`.
-
-```typescript static
-import theme from './theme/theme';
-import { ThemeFactory } from '@skbkontur/react-ui/lib/theming/ThemeFactory';
-
-ThemeFactory.overrideDefaultTheme(theme);
-```
-
-### Варианты кастомизации:
-
-Несколько тем одновременно:
-<br/>
-
-```jsx harmony
-import { ThemeContext, LIGHT_THEME, DARK_THEME } from '@skbkontur/react-ui';
-import { ShowcaseGroup } from '@skbkontur/react-ui/internal/ThemePlayground/ShowcaseGroup';
-
-const CombinedComponents = () => (
-  <>
-    <div style={{height: '100%', background: '#fff', padding: '16px'}}>
-      <ThemeContext.Provider value={LIGHT_THEME}>
-        <div>
-          <ShowcaseGroup title="LIGHT_THEME" />
-        </div>
-      </ThemeContext.Provider>
-    </div>
-    <div style={{height: '100%', background: '#000', padding: '16px'}}>
-      <ThemeContext.Provider value={DARK_THEME}>
-        <div>
-          <ShowcaseGroup title="DARK_THEME" />
-        </div>
-      </ThemeContext.Provider>
-    </div>
-  </ >
-);
-
-<CombinedComponents />;
-```
-
-Вложенные темы:
-<br/>
-
-```jsx harmony
-import { ThemeContext, LIGHT_THEME, DARK_THEME } from '@skbkontur/react-ui';
-import { ShowcaseGroup } from '@skbkontur/react-ui/internal/ThemePlayground/ShowcaseGroup';
-
-const wrapperStyles = {
-  border: '1px solid rgb(188, 187, 187)',
-  padding: '0 15px 15px',
-  marginTop: 25,
-};
-
-const NestedThemes = () => (
-  <ThemeContext.Provider value={ LIGHT_THEME }>
-    <div style={{ ...wrapperStyles, width: 750, background: '#fff' }}>
-      <ShowcaseGroup title="LIGHT_THEME" />
-        <ThemeContext.Provider value={ DARK_THEME }>
-          <div style={{ ...wrapperStyles, background: '#000', color: '#fff' }}>
-            <ShowcaseGroup title="DARK_THEME" />
-          </div>
-        </ThemeContext.Provider>
-    </div>
-  </ThemeContext.Provider>
-);
-
-<NestedThemes />;
-```
-
-## Кастомизация @skbkontur/react-ui-addons
-
-Компоненты `@skbkontur/react-ui-addons` так же поддерживают кастомизацию через `ThemeContext` из `@skbkontur/react-ui`. Достаточно переопределить нужные переменные, которые перечислены на страницах компонентов в [докумендации аддонов](https://ui.gitlab-pages.kontur.host/docs/#/react-ui-addons).
-
-```tsx static
-import { ThemeContext, ThemeFactory } from '@skbkontur/react-ui';
-import { Logotype, AddonsThemeIn } from '@skbkontur/react-ui-addons';
-
-const myTheme = ThemeFactory.create<AddonsThemeIn>({
-  logoColor: 'black',
-});
-
-<ThemeContext.Provider value={myTheme}>
-  <Logotype />
-</ThemeContext.Provider>;
-```
-
-## Дополнительно
-
-### ColorFunctions.ts / DimensionFunctions.ts
-
-Несколько функций по работе с цветом вынесены из less в js, их можно использовать в своих темах (_ColorFunctions.ts_):
-
-```typescript static
-import { ColorFunctions } from '@skbkontur/react-ui'
-
-ColorFunctions.lighten(colorString: string, amount: number | string, method?: 'absolute' | 'relative'): string
-ColorFunctions.darken(colorString: string, amount: number | string, method?: 'absolute' | 'relative'): string
-ColorFunctions.contrast(colorString: string, darkString?: string, lightString?: string, threshold: number = 0.43): string
-ColorFunctions.red(colorString: string): string
-ColorFunctions.green(colorString: string): string
-ColorFunctions.blue(colorString: string): string
-ColorFunctions.alpha(colorString: string): string
-ColorFunctions.isValid(colorString: string): boolean // проверяет, можно ли распарсить строку в цвет
-```
-
-Документацию по их работе можно найти на сайте [less](http://lesscss.org/functions/#color-operations).
-В качестве colorString можно передать цвет в одном из форматов: `keyword`, `hex`, `rgb(r, g, b)`, `rgba(r, g, b, a)`, `hsl(h, s, l)`, `hsla(h, s, l, a)`.
-В качестве `amount` можно передать строку вида 'N%' или число от 0 до 1.
-Все значения больше или меньше возможных обрезаются. Например, для `rgba(300, -100, 123, 20)` `r=255, g=0, b=123, a=1`.
-Если распарсить `colorString` не получилось - выбрасывается исключение.
-Если это возможно, результат возвращается в том же виде, что и входная строка:
-
-```typescript static
-import { ColorFunctions } from '@skbkontur/react-ui'
-
-ColorFunctions.lighten('hsl(90, 0.8, 0.2)', '20%') === 'hsl(90, 0.8, 0.4)';
-ColorFunctions.lighten('rgba(50, 50, 50, 0.2)', '20%') === 'rgba(102, 102, 102, 0.2)';
-ColorFunctions.lighten('#80e619', 0.2) === '#b3f075';
-ColorFunctions.lighten('crimson', '20%') === '#f16581';
-```
-
-Для работы с размерами предусмотрена одна функция (_DimensionFunctions.ts_):
-
-```typescript static
-shift(value: string, shift: string): string
-
-// пример
-import { DimensionFunctions } from '@skbkontur/react-ui'
-
-DimensionFunctions.shift('100%', '-20') === '80%'
-DimensionFunctions.shift('2em', '+2') === '4em'
-DimensionFunctions.shift('12', '+1') === '13px'  //если единица измерения не указана - используется px
-DimensionFunctions.shift('10.2', '12.333451') === '22.5335px' //дробная часть округляется до 4 знаков
-```
-
-### Список кастомизируемых компонентов
-
-Посмотреть, какие компоненты можно кастомизировать, а также увидеть, какие переменные используются в каждом из них, можно в [таблице](#/Customization/ThemeShowcase)
-Информация собирается в рантайме с помощью `Proxy`, поэтому в IE таблица не отображается.
-
-### Playground
-
-Внутренний компонент `Playground` (_components/internal/ThemePlayground/Playground.tsx_) можно использовать для построения своей темы.
-Для удобства в редакторе добавлено действие "вывести тему в консоль".