@tk-kit/design-system 0.1.17 → 0.1.19

package/README.md

@@ -0,0 +1,175 @@
+# @tk-kit/design-system
+
+Дизайн-система проектов tk-kit: переиспользуемые UI-компоненты, хуки и утилиты, опубликованные как публичный npm-пакет на npmjs.com, Storybook для разработки и просмотра компонентов.
+
+---
+
+
+### Стек
+
+TypeScript, React 19, Vite, Tailwind CSS v4, shadcn/ui (Radix UI), Storybook, опубликовано на npmjs.com.
+
+### Установка зависимостей
+
+```bash
+pnpm install
+```
+
+При первом запуске может потребоваться подтвердить выполнение build-скриптов нативных зависимостей — это уже настроено в `pnpm-workspace.yaml` (`allowBuilds`), повторно подтверждать не нужно.
+
+### Структура проекта
+
+```
+design-system/
+├── src/
+│   ├── components/
+│   │   ├── base/           # базовые UI-компоненты (Button, Input, Dialog...)
+│   │   ├── form/            # компоненты для форм (TextField, FileUploadField...)
+│   │   └── icons/            # иконки (генерируются автоматически, см. ниже)
+│   ├── hooks/                # переиспользуемые хуки
+│   ├── lib/                   # утилиты, zod-схемы
+│   ├── styles/                # глобальные стили, токены, переменные Tailwind
+│   └── index.ts               # публичная точка входа пакета — единственное
+│                               # место, откуда что-либо доступно потребителям
+├── scripts/
+│   └── generate-icons-index.ts  # автогенерация index.ts для папки icons
+├── .storybook/                  # конфигурация Storybook
+├── vite.config.ts                # конфиг для Storybook/Vitest
+├── vite.config.lib.ts             # конфиг для сборки библиотеки (lib mode)
+└── pnpm-workspace.yaml             # разрешённые build-скрипты зависимостей
+```
+
+### Как добавить новый компонент
+
+1. Создай папку компонента внутри `src/components/base/` (или `src/components/form/`, если это поле формы):
+   ```
+   src/components/base/my-component/
+   ├── my-component.tsx
+   ├── my-component.variants.ts   # если используется cva
+   ├── my-component.stories.tsx
+   └── index.ts
+   ```
+
+2. В `index.ts` папки компонента — именованный реэкспорт:
+   ```ts
+   export { MyComponent } from './my-component'
+   export type { MyComponentProps } from './my-component'
+   ```
+
+3. Добавь экспорт в **публичный** `src/index.ts` — без этого шага компонент не попадёт в собранный пакет и будет недоступен в приложениях-потребителях:
+   ```ts
+   export { MyComponent, type MyComponentProps } from '@/components/base/my-component'
+   ```
+
+4. Напиши историю в `my-component.stories.tsx`, чтобы компонент был виден в Storybook со всеми вариантами (`variant`, `size`, `disabled` и т.д.).
+
+5. Проверь визуально через Storybook (см. ниже), при необходимости — через `pnpm link` в тестовом приложении.
+
+### Как добавить иконку
+
+1. Положи `.tsx`-файл иконки в `src/components/icons/`, имя файла в формате `kebab-case`, суффикс `-icon` (например `arrow-up-icon.tsx`).
+2. Запусти автогенерацию реэкспортов:
+   ```bash
+   pnpm generate:icons
+   ```
+   Скрипт сам пересоберёт `src/components/icons/index.ts` со всеми иконками из папки. Файл генерируемый — руками не редактируется, перезапишется при следующей сборке.
+
+   Запускается автоматически при `pnpm build`, отдельный запуск нужен только если хочешь сразу увидеть иконку в Storybook без полного билда.
+
+### Важные принципы дизайн-системы
+
+- Дизайн-система **не должна** напрямую зависеть от инфраструктуры конкретного приложения (роутер, стейт-менеджер, HTTP-клиент). Если компоненту нужен роутинг — используется паттерн инверсии через проп `as` (см. компонент `Link`), а не прямой импорт `react-router-dom`.
+- Библиотеки форматирования/работы с данными без привязки к окружению (`date-fns`, `react-number-format`, `react-dropzone` и т.п.) — можно использовать напрямую как обычные зависимости.
+- Любой новый компонент обязан иметь `.stories.tsx` файл.
+- Публичный API пакета — только то, что явно реэкспортировано в `src/index.ts`. Не используем широкие `export *` для компонентов (только для иконок и zod-схем, где это оправдано).
+
+### Запуск Storybook локально
+
+```bash
+pnpm storybook
+```
+
+Откроется на `http://localhost:6006`. Hot reload работает автоматически при изменении файлов компонентов и `.stories.tsx`.
+
+### Запуск Storybook через Docker (как на сервере)
+
+```bash
+docker compose build storybook
+docker compose up storybook
+```
+
+Откроется на `http://localhost:6006`.
+
+### Сборка пакета (для публикации)
+
+```bash
+pnpm build
+```
+
+Генерирует иконки, прогоняет проверку типов, собирает `dist/` (ESM + CJS + типы + стили) через `vite.config.lib.ts`.
+
+Проверить итоговую сборку перед публикацией можно через:
+```bash
+pnpm pack
+```
+— создаст `.tgz`-архив, который можно установить в тестовое приложение командой `pnpm add /путь/к/архиву.tgz` и проверить вживую (стили, типы, импорты).
+
+### Публикация новой версии
+
+Публикация происходит автоматически через GitLab CI, **только при пуше git-тега** — обычный пуш в `main` пакет не публикует (только обновляет Storybook).
+
+Версию поднимаем командой `npm version` — она сама обновляет `package.json`, создаёт коммит и git-тег нужного формата (`vX.Y.Z`), вручную ничего не редактируем:
+
+```bash
+# 1. Закоммить изменения кода
+git add .
+git commit -m "feat: добавлен компонент MyComponent"
+
+# 2. Поднять версию (сама создаст commit "vX.Y.Z" и git-тег vX.Y.Z)
+npm version patch   # багфикс, без изменения API
+# npm version minor  # новый компонент/хук, без breaking changes
+# npm version major  # сломан/изменён публичный API
+
+# 3. Запушить коммит и тег одной командой
+git push --follow-tags
+```
+
+CI запускает job `build-package` **только когда тег соответствует формату `vX.Y.Z`** (например `v0.2.0`). Так как тег создаёт сам `npm version`, версия в `package.json` и имя тега всегда совпадают автоматически.
+
+**Если версия уже была опубликована** — job упадёт с ошибкой `E403`/`cannot publish over previously published version` (npm registry не разрешает переопубликовать существующую версию). В этом случае просто поднимите версию ещё раз (`npm version patch`) и запушьте новый тег.
+
+**Правила версионирования:**
+
+| Что изменилось                          | Версия          |
+|------------------------------------------|-----------------|
+| Новый компонент / хук, без breaking changes | minor (`0.X.0`) |
+| Багфикс, без изменения API                | patch (`0.0.X`) |
+| Сломан/изменён публичный API компонента   | major (`X.0.0`) |
+
+### Установка пакета в приложении-потребителе
+
+Пакет публичный и опубликован на npmjs.com — никакой дополнительной авторизации для установки не требуется.
+
+```bash
+pnpm add @tk-kit/design-system
+```
+
+```text
+/* globals.css приложения */
+@import 'tailwindcss';
+@import 'tw-animate-css';
+@import '@tk-kit/design-system/tokens.css';
+
+@source "../../../node_modules/@tk-kit/design-system/dist";
+```
+
+```tsx
+import { Button, TextField } from '@tk-kit/design-system'
+```
+
+**Для CI/CD** — тоже ничего настраивать не нужно, обычный `pnpm install` подтянет пакет с публичного registry:
+
+```yaml
+script:
+  - pnpm install
+```