npm package: @infomaximum/ui-kit
Description: Для установки библиотеки `@infomaximum/ui-kit` в ваш проект используйте один из следующих способов:
Latest version: 0.17.4

## Установка библиотеки

Для установки библиотеки `@infomaximum/ui-kit` в ваш проект используйте один из следующих способов:

### Используя npm:

```bash
npm install @infomaximum/ui-kit
```

### Используя yarn:

```bash
yarn add @infomaximum/ui-kit
```

---

## Создание компонента

### Общая структура

Компонент создается в папке `src/components`, при этом папка именуется в PascalCase по имени компонента. Директория каждого компонента должна иметь следующую структуру:

#### Пример структуры для компонента `Button`:

```
  components
      └── Button/
         ├── Button.mdx // Документация к компоненту (по необходимости)
         ├── Button.styles.ts    // Стили компонента
         ├── Button.stories.ts - / Файл Storybook для демонстрации использования
         ├── Button.test.ts - // Тесты на компонент (обязательно должны присутствовать snapshot тесты)
         ├── Button.tsx - // Сам компонент
         ├── Button.types.ts - // Типы TypeScript для компонента
         └── index.ts - // Экспорт сущностей компонента
```

#### Пример содержимого файла `src/components/Button/index.ts`:

```typescript
export { Button } from "./Button";
export { ButtonDefaultStyles } from "./Button.styles";
export type { ButtonProps } from "./Button.types";
```

---

## Добавление компонента в библиотеку

**Экспорт компонента:**
После завершения работы над компонентом, его необходимо правильно экспортировать в основном файле `src/index.ts`:

```typescript
export { Button, ButtonDefaultStyles } from "./components/Button";
export type { ButtonProps } from "./components/Button";
```

---

## Стилизация компонентов

В качестве решения по стилизации компонентов используется библиотека [Emotion](https://emotion.sh). Для предоставления возможности кастомизации стилей компонентов ui-kit, необходимо придерживаться следующих принципов:

1. Каждый компонент должен принимать в качестве пропсов свойство `className?` (это нужно при стилизации компонента через css) и передавать его необходимому дочернему компоненту в пропсы, например:

```ts
export interface ButtonProps {
  className?: string;
}

const Button: FC<ButtonProps> = ({ className }) => {
  return <button className={className}>Button</button>;
};
```

2. Если возникает необходимость кастомизации дочерних компонентов, то компонент должен принимать в качестве пропса свойство `styles`, например:

```ts
export type ButtonStyles = {
  icon?: Interpolation;
};

type ButtonProps = {
  className?: string;
  styles: ButtonStyles;
};

const Icon: FC<{ className?: string }> = ({ className }) => (
  <div className={className}>Icon</div>
);

const Button: FC<ButtonProps> = (props) => {
  const { className, styles } = props;

  return (
    <button className={className}>
      Button
      <br />
      <br />
      <Icon css={styles.icon} />
    </button>
  );
};
```

Если иконка содержит вложенную стилизацию, то нужно использовать следующий подход: пример [по ссылке](https://stackblitz.com/edit/vitejs-vite-md1k3x83?file=README.md)

3. Компонент должен экспортировать стили, которые в нем используются, поэтому в файле \*.styles.ts стили создаются следующим образом на примере Button

```ts
// Button.styles.ts

import type { InterpolationWithTheme } from "types";

export const ButtonDefaultStyles = {
  wrapper: (theme) => ({
    color: theme.color.negative,
  }),
} satisfies Record<string, InterpolationWithTheme>;
```

---

## Документация по дизайн системе

Вся необходимая документация должна располагаться в папке docs/, например

```
im-storybook
└─ docs/
    └── Дизайн система.mdx
```

---

## Основные скрипты

`yarn storybook` - запустить сторибук для разработки

`yarn build-storybook` - собрать сторибук для production

`yarn dev` - разработка библиотеки с пересборкой при изменении файлов

`yarn build` - собрать библиотеку для публикации

`yarn test` - запустить тесты

`yarn lint` - запустить проверку проекта на ошибки typescript и на соответствие правил eslint

`yarn coverage` - вывести информацию по покрытию файлов тестами

---

## Семантическое версионирование:

Библиотека использует [семантическое версионирование](https://semver.org/). При добавлении нового компонента необходимо следовать этим принципам:

- Увеличивайте мажорную версию для изменений, нарушающих обратную совместимость.
- Увеличивайте минорную версию для добавления нового функционала.
- Увеличивайте патч-версию для исправления ошибок.

---

## Планы на будущее

1. **Процент покрытия тестами:**

   - Добавить метрики покрытия тестами и установить минимальный порог.