# Як працювати над компонентною бібліотекою

Ласкаво просимо до бібліотеки freeCodeCamp `ui-components`. Переважно компоненти побудовані з нуля завдяки базовим елементам HTML та [Tailwind CSS](https://tailwindcss.com/).

> [!NOTE]
> 
> freeCodeCamp використовує компоненти Bootstrap в UI. Однак ми віддаляємось від цього та будуємо власну компонентну бібліотеку, яка допоможе стандартизувати наші шаблони UX/UI та покращити доступність. Проєкт відстежується у [цьому завданні на GitHub](https://github.com/freeCodeCamp/freeCodeCamp/issues/44668).

Для роботи над новим компонентом рекомендовані наступні кроки:

- Дослідження та планування
- Реалізація компонента
- Показ сценаріїв використання на Storybook
- Написання модульних тестів

## Дослідження та планування

Перед побудовою компонента вам потрібно дослідити та задокументувати поведінку й вигляд поточної версії, щоб переконатись, що нова версія відповідатиме стилю та підтримуватиме усі поточні використання. Щоб відповідати вимогам доступності мережі, також звертайте увагу на аспекти доступності компонента, перегляньте, які елементи HTML та атрибути ARIA використовуються під капотом.

Як тільки ви зібрали достатньо інформації про компонент, можна почати думати про інтерфейс властивостей. В ідеалі інтерфейс повинен бути максимально схожим до поточної версії, щоб полегшити майбутнє впровадження. Оскільки ми використовуємо компоненти Bootstrap, найпростіший спосіб — імітувати [їхню реалізацію](https://github.com/react-bootstrap/react-bootstrap/tree/master/src).

Ми надаємо перевагу коротким запитам на злиття, оскільки вони пришвидшують час на перегляд та зменшують когнітивне навантаження на рецензентів. З цієї причини подумайте, як би ви розбили реалізацію та розробили план доставки.

Ми рекомендуємо відкривати окреме завдання на GitHub для кожного компонента та додавати всі нотатки в опис завдання. Його можна використовувати як місце для розміщення всіх робочих нотаток, а також як спосіб донести свій підхід до рецензентів. За потреби ми використаємо тред завдання для подальшого обговорення. [Завдання для компонента Button](https://github.com/freeCodeCamp/freeCodeCamp/issues/45357) можна використати як зразок.

## Реалізація компонента

Новий компонент можна створити за допомогою наступної команди з кореневого каталогу:

```bash
cd tools/ui-components

pnpm run gen-component MyComponent
```

Всередині каталогу `ui-components` команда згенерує папку з наступними файлами:

| Назва файлу                | Призначення                                                |
| -------------------------- | ---------------------------------------------------------- |
| `index.ts`                 | Використовується для експорту компонента та його типів.    |
| `my-component.stories.tsx` | Використовується для демонстрації компонента на Storybook. |
| `my-component.test.tsx`    | Тестовий файл.                                             |
| `my-component.tsx`         | Місце реалізації компонента.                               |
| `types.ts`                 | Місце розташування інтерфейсу та типів компонента.         |

Кожен компонент відрізняється, але загалом він повинен:

- Підтримувати перенаправлення ref
- Бути стилізованим для світлої та темної тем
- Бути внутрішньо стилізованим на основі своїх властивостей (споживачам не знадобиться ще раз стилізувати компонент за допомогою властивості `className`)
- Використовувати вбудовану систему стилізації з Tailwind замість власних стилів

### Використання кольорів

У компонентній бібліотеці є два «шари» кольорів:

- Базовий шар, де назви кольорів описують колір, тобто `gray00`, `blue50`
- Семантичний шар, де назви кольорів описують для чого використані кольори, тобто `foreground-primary`, `background-danger`

Під час використання кольору в компоненті варто надавати перевагу семантичним змінним. Однак бувають винятки, особливо коли ви стилізуєте стани компонента (hover, active, disabled тощо). У таких випадках ми рекомендуємо використовувати базові змінні, а не створювати семантичні змінні, оскільки кожен компонент може мати різні стилі для своїх станів.

> [!NOTE] Визначення кольору можна знайти у файлі [`colors.css`](https://github.com/freeCodeCamp/freeCodeCamp/blob/main/tools/ui-components/src/colors.css). Колір доступний для використання лише якщо його додано до [ файлу `tailwind.config.js`](https://github.com/freeCodeCamp/freeCodeCamp/blob/main/tools/ui-components/tailwind.config.js) під властивістю `colors`.

### Корисні посилання

- [Конфігурація CSS Tailwind](https://tailwindcss.com/docs/configuration)
- [Документація React Bootstrap v0.33](https://react-bootstrap-v3.netlify.app)
- [Таблиця стилів Bootstrap 3.3.7](https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.css)
- [Поточне впровадження React Bootstrap](https://github.com/react-bootstrap/react-bootstrap/tree/master/src)
- [Поточні тести React Bootstrap](https://github.com/react-bootstrap/react-bootstrap/tree/master/test)

## Показ сценаріїв використання на Storybook

Сценарії використання компонентів потрібно додати до файлу Storybook (`.stories.tsx`).

Щоб запустити Storybook, виконайте наступну команду з кореневого каталогу:

```bash
pnpm run storybook
```

Сторінка Storybook доступна на [http://localhost:6006](http://localhost:6006).

## Написання модульних тестів

Ми використовуємо [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) для написання модульних тестів. Тести повинні підтверджувати, що компоненти поводяться як потрібно та є доступними.

Щоб запустити тести компонентної бібліотеки, виконайте наступну команду з кореневого каталогу:

```bash
pnpm run test-ui-components
```

## Запропонуйте запит на злиття (PR)

Як тільки ви затвердили свої зміни, див. [як відкрити запит на злиття](how-to-open-a-pull-request.md).

## Додавання пакетів до компонентної бібліотеки UI

Ми обмежуємо додавання нових пакетів до компонентів UI, щоб допомогти з обслуговуванням проєкту. За рідкісних випадків, якщо на вашу думку потрібна залежність, будь ласка, обговоріть це зі спеціалістом з обслуговування та використайте наступну команду, щоб додати пакет:

```bash
cd tools/ui-components 
pnpm add package_name
```

## Корисні посилання

- [Тестування доступності](https://testing-library.com/docs/dom-testing-library/api-accessibility)
- [Черговість запитів React Testing Library](https://testing-library.com/docs/queries/about/#priority)
- [Часті помилки при роботі з React Testing Library](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library)
