@vkontakte/vkui 4.28.0 → 4.29.1

package/.cache/ts/src/tokenized/index.d.ts

@@ -0,0 +1,42 @@
+export { Button } from "../components/Button/Button";
+export type { ButtonProps } from "../components/Button/Button";
+export { Card } from "../components/Card/Card";
+export type { CardProps } from "../components/Card/Card";
+export { CardScroll } from "../components/CardScroll/CardScroll";
+export type { CardScrollProps } from "../components/CardScroll/CardScroll";
+export { HorizontalScroll } from "../components/HorizontalScroll/HorizontalScroll";
+export type { HorizontalScrollProps } from "../components/HorizontalScroll/HorizontalScroll";
+export { ButtonGroup } from "../components/ButtonGroup/ButtonGroup";
+export type { ButtonGroupProps } from "../components/ButtonGroup/ButtonGroup";
+export { SegmentedControl } from "../components/SegmentedControl/SegmentedControl";
+export type { SegmentedControlProps, SegmentedControlOptionInterface, SegmentedControlValue, } from "../components/SegmentedControl/SegmentedControl";
+export { Title } from "../components/Typography/Title/Title";
+export type { TitleProps } from "../components/Typography/Title/Title";
+export { Subhead } from "../components/Typography/Subhead/Subhead";
+export type { SubheadProps } from "../components/Typography/Subhead/Subhead";
+export { Pagination } from "../components/Pagination/Pagination";
+export type { PaginationProps } from "../components/Pagination/Pagination";
+export { Calendar } from "../components/Calendar/Calendar";
+export type { CalendarProps } from "../components/Calendar/Calendar";
+export { CalendarRange } from "../components/CalendarRange/CalendarRange";
+export type { CalendarRangeProps } from "../components/CalendarRange/CalendarRange";
+export { Caption } from "../components/Typography/Caption/Caption";
+export type { CaptionProps } from "../components/Typography/Caption/Caption";
+export { Paragraph } from "../components/Typography/Paragraph/Paragraph";
+export type { ParagraphProps } from "../components/Typography/Paragraph/Paragraph";
+export { Input } from "../components/Input/Input";
+export type { InputProps } from "../components/Input/Input";
+export { FormField } from "../components/FormField/FormField";
+export type { FormFieldProps } from "../components/FormField/FormField";
+export { Select } from "../components/Select/Select";
+export type { SelectProps } from "../components/Select/Select";
+export { CustomSelect } from "../components/CustomSelect/CustomSelect";
+export type { CustomSelectProps } from "../components/CustomSelect/CustomSelect";
+export { CustomSelectDropdown } from "../components/CustomSelectDropdown/CustomSelectDropdown";
+export type { CustomSelectDropdownProps } from "../components/CustomSelectDropdown/CustomSelectDropdown";
+export { CustomSelectOption } from "../components/CustomSelectOption/CustomSelectOption";
+export type { CustomSelectOptionProps } from "../components/CustomSelectOption/CustomSelectOption";
+export { ChipsInput } from "../components/ChipsInput/ChipsInput";
+export type { ChipsInputProps } from "../components/ChipsInput/ChipsInput";
+export { ChipsSelect } from "../components/ChipsSelect/ChipsSelect";
+export type { ChipsSelectProps } from "../components/ChipsSelect/ChipsSelect";

package/.cache/ts/src/types.d.ts

@@ -0,0 +1,34 @@
+import * as React from "react";
+import { PlatformType } from "./lib/platform";
+import { Insets } from "@vkontakte/vk-bridge";
+export declare type AnyFunction = (...args: any[]) => any;
+export declare type AlignType = "left" | "center" | "right";
+export interface HasRootRef<T> {
+    getRootRef?: React.Ref<T>;
+}
+export interface HasRef<T> {
+    getRef?: React.Ref<T>;
+}
+export interface HasComponent {
+    Component?: React.ElementType;
+}
+export interface HasAlign {
+    align?: AlignType;
+}
+export interface HasPlatform {
+    /**
+     * @ignore
+     */
+    platform?: PlatformType;
+}
+export interface HasInsets {
+    /**
+     * @ignore
+     */
+    insets?: Partial<Insets>;
+}
+export interface Version {
+    major: number;
+    minor?: number;
+    patch?: number;
+}

package/.cache/ts/src/unstable/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Forms
+ */
+export { ChipsSelect } from "../components/ChipsSelect/ChipsSelect";
+export type { ChipsSelectProps } from "../components/ChipsSelect/ChipsSelect";
+export { Dropdown } from "../components/Dropdown/Dropdown";
+export type { DropdownProps } from "../components/Dropdown/Dropdown";
+export { TextTooltip } from "../components/TextTooltip/TextTooltip";
+export type { TextTooltipProps } from "../components/TextTooltip/TextTooltip";
+export { RichTooltip } from "../components/RichTooltip/RichTooltip";
+export type { RichTooltipProps } from "../components/RichTooltip/RichTooltip";
+export { Popper } from "../components/Popper/Popper";
+export type { PopperProps } from "../components/Popper/Popper";
+export { ViewInfinite } from "../components/View/ViewInfinite";
+export type { ViewInfiniteProps } from "../components/View/ViewInfinite";
+export { SimpleCheckbox } from "../components/SimpleCheckbox/SimpleCheckbox";
+export type { SimpleCheckboxProps } from "../components/SimpleCheckbox/SimpleCheckbox";

package/.codesandbox/ci.json

@@ -0,0 +1,5 @@
+{
+  "node": "14",
+  "installCommand": "codesandbox:install",
+  "sandboxes": ["vkui-default-example-b7kyy"]
+}

package/.editorconfig

@@ -0,0 +1,14 @@
+# editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

package/.eslintignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+docs/
+*.test.js
+src/vkui.js
+stylelint.config.js

package/.eslintrc.json

@@ -0,0 +1,151 @@
+{
+  "extends": [
+    "@vkontakte/eslint-config/typescript/react",
+    "prettier",
+    "prettier/react",
+    "prettier/@typescript-eslint",
+    "plugin:react-hooks/recommended"
+  ],
+  "parserOptions": {
+    "project": "./tsconfig.json",
+    "ecmaVersion": 2018, // Allows for the parsing of modern ECMAScript features
+    "sourceType": "module", // Allows for the use of imports
+    "ecmaFeatures": {
+      "jsx": true, // Allows for the parsing of JSX
+      "restParams": true,
+      "spread": true
+    }
+  },
+  "globals": {
+    "Element": true
+  },
+  "ignorePatterns": ["unstable/**/*.ts", "tokenized/**/*.ts"],
+  "env": {
+    "es6": true, // Enable global es6 variables, like Set, Map, etc
+    "browser": true,
+    "node": true
+  },
+  "plugins": ["import", "vkui"],
+  "rules": {
+    "@typescript-eslint/explicit-member-accessibility": "off",
+    "@typescript-eslint/no-unnecessary-condition": "off",
+    "@typescript-eslint/no-magic-numbers": "off",
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      {
+        "ignoreRestSiblings": true
+      }
+    ],
+    "@typescript-eslint/no-non-null-assertion": "off",
+    "no-restricted-globals": ["error", "window", "document"],
+    "no-restricted-imports": [
+      "error",
+      {
+        "paths": [
+          // prevent absolute imports from src subfolders like `import { ... } from "lib"`
+          "appearance",
+          "components",
+          "helpers",
+          "hoc",
+          "hooks",
+          "lib",
+          "styles",
+          "testing",
+          "types",
+          "unstable",
+          "tokenized"
+        ],
+        "patterns": [
+          "@vkontakte/icons/dist/*",
+          // prevent absolute imports from src subfolders like `import { ... } from "lib/platform"`
+          "appearance/*",
+          "components/*",
+          "helpers/*",
+          "hoc/*",
+          "hooks/*",
+          "lib/*",
+          "styles/*",
+          "testing/*",
+          "types/*",
+          "unstable/*",
+          "tokenized/*"
+        ]
+      }
+    ],
+    "no-restricted-properties": [
+      "error",
+      {
+        "property": "querySelector",
+        "message": "Make sure to use [data-*] selector, not class"
+      },
+      {
+        "property": "querySelectorAll",
+        "message": "Make sure to use [data-*] selector, not class"
+      },
+      {
+        "property": "matches",
+        "message": "Make sure to use [data-*] selector, not class"
+      },
+      {
+        "property": "closest",
+        "message": "Make sure to use [data-*] selector, not class"
+      },
+      {
+        "property": "getElementsByClassName",
+        "message": "Use .querySelectorAll('[data-*]')"
+      },
+      {
+        "property": "classList",
+        "message": "Make sure to use 'vkui' prefix"
+      },
+      {
+        "property": "getElementById",
+        "message": "Absolutely do not use id"
+      },
+      {
+        "object": "React",
+        "property": "useLayoutEffect",
+        "message": "Prefer lib/useIsomorphicLayoutEffect"
+      }
+    ],
+    "react/react-in-jsx-scope": "off",
+    "no-restricted-syntax": [
+      "error",
+      {
+        "selector": "ImportDeclaration[source.value=/^\\W+(index(\\.ts)?)?$/i]",
+        "message": "Do not import index"
+      },
+      {
+        "selector": "ImportDeclaration[source.value=/\\.css$/i] ~ ImportDeclaration[source.value!=/\\.css$/i]",
+        "message": "CSS import must be last"
+      }
+    ],
+    "import/no-default-export": "error",
+    "vkui/no-object-expression-in-arguments": [
+      "error",
+      {
+        "onlyForFunctionsWithNames": ["classNames", "classNamesString"]
+      }
+    ]
+  },
+  "overrides": [
+    {
+      "files": [
+        "src/**/*.{test,spec,e2e}.{ts,tsx}",
+        "e2e/**/*",
+        "src/testing/**/*"
+      ],
+      "env": {
+        "jest": true
+      },
+      "rules": {
+        "no-restricted-properties": "off",
+        "no-restricted-globals": "off"
+      }
+    },
+    {
+      "files": ["src/**/*.e2e.{ts,tsx}", "e2e/**/*", "src/testing/**/*"],
+      "extends": ["plugin:jest-playwright/recommended"]
+    }
+  ]
+}

package/.gitattributes

@@ -0,0 +1 @@
+src/**/__image_snapshots__/*.png filter=lfs diff=lfs merge=lfs -text

package/.prettierignore

@@ -0,0 +1,14 @@
+node_modules
+dist
+coverage
+.idea
+.vscode
+e2e/dist
+test-results.json
+lint-results.json
+e2e-results.json
+.nyc_output
+__diff_output__
+.cache
+docs/
+src/styles/generated

package/.prettierrc.json

@@ -0,0 +1 @@
+{}

package/.stylelintignore

@@ -0,0 +1,2 @@
+node_modules
+dist

package/CONTRIBUTING.md

@@ -14,12 +14,13 @@
 - Дизайн компонента описан в [Figma](https://www.figma.com/@vk)
 - Компонент находится в своей папке в `src/components` и не делит её с другими публичными компонентами (один файл — один компонент)
 - У компонента есть понятная документация, описанная в директории компонента в файле `Readme.md`. Файл подключается в `styleguide/config.js`
+- Вся документация и предупреждения в коде компонента (`warnOnce`) написаны на русском языке
 - Вся стилизация — в соответствующем `.css` файле. Файл подключается в `src/styles/components.css`
 
 ### Требования к разработке
 
 - CSS-классы компонента передаем через `vkuiClass="Cmp"`
-- CSS-классы названы по БЭМ: `.Component__element-name--modificator`
+- CSS-классы названы по БЭМ: `.Component__element-name--modificator`. [Гайд по написанию стилей](https://github.com/VKCOM/VKUI/blob/master/CSS_GUIDE.md)
 - Свойства `className` и `style` навешиваются на корневой элемент компонента
 - Свойства, не используемые в коде компонента, навешиваются на **главный** элемент компонента. По умолчанию главным является корневой элемент:
 
@@ -57,7 +58,7 @@ const Cmp: React.FC<CmpProps> = ({
 }) => <div vkuiClass={classNames("Cmp", `Cmp--${mode}`)} {...restProps} />;
 ```
 
-- Для цветов используются цветовые токены
+- Для цветов используются цветовые токены. Старые компоненты поддерживают [Appearance](https://github.com/VKCOM/Appearance) и [vkui-tokens](https://github.com/VKCOM/vkui-tokens), новые — только vkui-tokens. [Гайд по миграции](https://github.com/VKCOM/VKUI/blob/master/VKUI_TOKENS_MIGRATION_GUIDE.md)
 - Для типографии используются компоненты [Typography](https://vkcom.github.io/VKUI/#!/Typography) там, где это возможно
 - Добавлен `export` компонента и его свойств в `src/index.ts`
 - Компонент покрыт юнит- и скриншотными тестами. [Гайд по тестированию](./TESTING.md)

package/CSS_GUIDE.md

@@ -0,0 +1,145 @@
+# Гайд по написанию стилей
+
+## Соглашения
+
+- Используем БЭМ-нотацию
+- Блок начинается с заглавной буквы: `.Checkbox`
+- Многословный блок разделяется через camelCase: `.SimpleCheckbox`
+- Элемент от блока отделяется двумя подчеркиваниями: `.Checkbox__in`
+- Многословные элементы разделяются через kebab-case: `.Banner__before-title`
+- Модификатор отделяется двумя дефисами: `.Input--plain`
+- Многословные модификаторы разделяются через kebab-case или camelCase: `.Checkbox--sizeX-regular`
+
+### Связность стилей
+
+Если компонент состоит из других компонентов, то для их модификации используем БЭМ-миксин. Пример:
+
+```tsx
+// Button.tsx
+<button vkuiClass="Button">
+  <Text vkuiClass="Button__text">{children}</Text>
+</button>
+```
+
+```css
+/* Button.css */
+.Button__text {
+  margin: 4px 0;
+}
+```
+
+Если в компонент прокидываются другие компоненты извне, то для их модификации используем обращение к блоку. Пример:
+
+```tsx
+// Cell.tsx
+<div vkuiClass="Cell">
+  {before} {/* В before может быть <Icon /> или <Avatar /> */}
+</div>
+```
+
+```css
+/* Cell.css */
+.Cell .Icon {
+  margin-right: 10px;
+}
+
+.Cell .Avatar {
+  margin-right: 8px;
+}
+```
+
+Таких ситуаций стоит избегать, так как подобное связывание лишает нас возможности в будущем хешировать имена классов с
+помощью css-modules.
+
+## Проблемы
+
+### Конфликт стилей блока и миксина
+
+```css
+/* Text.css */
+.Text {
+  margin: 0;
+}
+```
+
+```css
+/* Button.css */
+.Button__text {
+  margin: 4px 0;
+}
+```
+
+Вес селекторов одинаковый, поэтому применится последний по порядку. Рассчитывать на порядок сложно, так как он может
+меняться, если собирать стили вебпаком.
+
+#### Решение
+
+Избегать правил на блоке, которые могут быть в миксине.
+
+Список правил, которых стоит избегать:
+
+- display;
+- margin;
+- position;
+- left, right, top, bottom;
+- transform: translate
+
+### Сброс стилей
+
+Допустим, мы делаем компонент типографики. Для семантики мы даём возможность рендерить
+любой html-элемент. В итоге, если пользователь рендерит, допустим, `h1`, у него появляются
+дефолтные браузерные `margin`. Наше решение такое:
+
+```css
+/* Title.css */
+
+.Title {
+  /*...*/
+  margin: 0; /* или любое другое значение, диктуемое дизайном */
+}
+```
+
+Решение приводит нас к предыдущей проблеме.
+
+#### Решение
+
+В таком случае необходимо снабдить компонент режимом `withSpaces`, который
+если `false`, то никакие `margin` на блок не навешиваются.
+
+### Нормализация стилей
+
+Допустим, мы делаем компонент кнопки. Согласно дизайну, кнопка может быть ссылкой. Поэтому
+Button мы тоже наделяем возможностью рендерить любой html-элемент, в том числе `a`. В силу
+ряда стилей нам необходимо, что кнопка не была инлайновой. Поэтому мы пишем следующее:
+
+```css
+/* Button.css */
+
+.Button {
+  /* ... */
+  display: inline-block;
+}
+```
+
+Теперь те, кто хочет скрыть кнопку, используя миксин, столкнутся с проблемой конфликта
+блока и миксина.
+
+#### Решение
+
+В данном случае мы можем только порекомендовать разработчикам оборачивать кнопку
+в условный `div`.
+
+### Обращения к элементам другого блока
+
+```css
+/* Banner.css */
+.Banner .Button__in {
+  padding-top: 4px;
+}
+```
+
+Мы завязываемся на реализацию другого компонента. Это плохо, так как реализация может меняться.
+
+#### Решение
+
+Не обращаться к элементам другого блока

package/TESTING.md

@@ -0,0 +1,58 @@
+Мы используем три вида тестов:
+
+**Юнит-тесты** на jest в файлах `moduleName.test.ts` [пример](./src/helpers/getClassName.test.ts)
+
+**Компонентные тесты** на jest + [react-testing-library](https://testing-library.com/docs/react-testing-library/example-intro) + [jest-dom](https://github.com/testing-library/jest-dom#table-of-contents) в `ComponentName.test.tsx` [пример](./src/components/Checkbox/Checkbox.test.tsx)
+
+**Скриншотные тесты** на jest + [playwright](https://playwright.dev/#?path=docs/api.md) + [jest-playwright](https://github.com/playwright-community/jest-playwright) в `ComponentName.e2e.tsx` [пример](./src/components/Checkbox/Checkbox.e2e.tsx).
+
+Чтобы запускать скриншотные тесты локально, нужно установить:
+
+- [git-lfs](https://git-lfs.github.com) — чтобы от эталонных скриншотов не раздувало репозиторий
+- [докер](https://www.docker.com/products/docker-desktop) — чтобы платформа не влияла на рендеринг шрифтов. На линуксе докер не нужен.
+
+## Команды
+
+- `yarn test:unit` — только быстрые юниты + компонентные;
+- `yarn test:unit:quick` — только юниты + компонентные тесты на незакоммиченные изменения;
+- `yarn test:e2e` — только браузерные тесты;
+
+Все команды работают в интерактивном режиме с опцией `--watch` (`yarn test:unit --watch`).
+
+Чтобы обновить скриншоты, установите докер и git-lfs и запустите `yarn test:e2e -u`.
+
+## Покрытие
+
+Чтобы сгенерировать карту покрытия в `coverage/lcov/index.html`:
+
+- Только юнитами — просто `yarn test:unit`
+- Только E2E — `yarn test:e2e && yarn test:combine-coverage`
+- Совмещенного — `&& yarn test:e2e && yarn test:unit:ci && yarn test:combine-coverage`
+
+## `describeScreenshotFuzz`
+
+Функция `describeScreenshotFuzz` из [`/testing/utils`](./src/testing/e2e/utils.tsx) помогает быстро заскриншотить все состояния компонента в разных темах и на разных платформах:
+
+```ts
+describe("Button", () => {
+  describeScreenshotFuzz(
+    // Можем передать компонент или вот так добавить дефолтные пропы для скриншотов
+    (props: ButtonProps) => <Button {...props}>Кнопка</Button>,
+    // Описание комбинаций пропов — по элементу массива на независимый набор
+    [
+      // mode и disabled влияют на цвет, но не на размер
+      { mode: ["primary", "secondary"], disabled: [undefined, true] },
+      // size влияет на размер, но не на цвет
+      { size: ["s", "m", "l"] },
+    ]
+  );
+  // всего 2 * 2 + 3 = 7 состояний:
+  // mode="primary"
+  // mode="primary" disabled
+  // mode="secondary"
+  // mode="secondary" disabled
+  // size="s"
+  // size="m"
+  // size="l"
+});
+```

package/babel.cjs.config.js

@@ -0,0 +1,15 @@
+module.exports = {
+  extends: "./babel.config.js",
+  presets: [
+    [
+      "@babel/preset-env",
+      {
+        modules: "commonjs",
+        exclude: [
+          "@babel/plugin-proposal-unicode-property-regex",
+          "@babel/plugin-transform-unicode-regex",
+        ],
+      },
+    ],
+  ],
+};

package/babel.config.js

@@ -0,0 +1,72 @@
+const { NODE_ENV, BABEL_KEEP_CSS } = process.env;
+const isProduction = NODE_ENV === "production";
+const isDevelopment = NODE_ENV === "development";
+const useModules = isProduction || isDevelopment;
+const keepCss = Boolean(BABEL_KEEP_CSS);
+const runtimeVersion = require("./package.json").dependencies["@babel/runtime"];
+
+const testFiles = [
+  "./src/**/*.test.ts",
+  "./src/**/*.test.tsx",
+  "./src/**/*.spec.ts",
+  "./src/**/*.spec.tsx",
+  "./src/**/*.e2e.ts",
+  "./src/**/*.e2e.tsx",
+  "./e2e/",
+  "./src/testing/",
+];
+
+module.exports = {
+  presets: [
+    [
+      "@babel/preset-env",
+      {
+        modules: useModules ? false : "commonjs",
+        exclude: [
+          "@babel/plugin-proposal-unicode-property-regex",
+          "@babel/plugin-transform-unicode-regex",
+        ],
+      },
+    ],
+    [
+      "@babel/preset-react",
+      {
+        pragma: "createScopedElement",
+        pragmaFrag: "createScopedElement.Fragment",
+      },
+    ],
+    [
+      "@babel/preset-typescript",
+      {
+        jsxPragma: "createScopedElement",
+        jsxPragmaFrag: "createScopedElement.Fragment",
+      },
+    ],
+  ],
+  plugins: [
+    "@babel/plugin-proposal-class-properties",
+    "@babel/plugin-proposal-object-rest-spread",
+    ["@babel/plugin-transform-runtime", { version: runtimeVersion }],
+    [
+      require.resolve("babel-plugin-auto-import"),
+      {
+        declarations: [
+          { members: ["createScopedElement"], path: "#jsxRuntime" },
+        ],
+      },
+    ],
+    [
+      require.resolve("babel-plugin-module-resolver"),
+      {
+        alias: {
+          "#jsxRuntime": "./src/lib/jsxRuntime",
+        },
+      },
+    ],
+  ].concat(
+    keepCss
+      ? []
+      : [["babel-plugin-transform-remove-imports", { test: "\\.css$" }]]
+  ),
+  ignore: ["./src/vkui.js"].concat(isProduction ? testFiles : []),
+};