@zelelo/iskra-ui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Zelelo622 (Iskra UI)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN CONNECTED WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,210 @@
-# Temporary Holding Version
+# Iskra UI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Современная, доступная (a11y) и легковесная библиотека React-компонентов, написанная на TypeScript.
+
+## Установка
+
+```bash
+npm install @zelelo/iskra-ui
+# или
+yarn add @zelelo/iskra-ui
+# или
+pnpm add @zelelo/iskra-ui
+```
+
+**Peer Dependencies:**
+Убедитесь, что в вашем проекте установлен React версии 18 или выше:
+
+```bash
+npm install react react-dom
+```
+
+## Использование
+
+Стили поставляются отдельным файлом - подключите его один раз в корне приложения:
+
+```tsx
+import { Button, Input } from "@zelelo/iskra-ui";
+import "@zelelo/iskra-ui/styles.css";
+
+function App() {
+  return (
+    <div>
+      <Input placeholder="Введите имя..." />
+      <Button variant="primary" size="md">
+        Отправить
+      </Button>
+    </div>
+  );
+}
+```
+
+## Доступные компоненты
+
+- **Accordion** - гармошка для скрытия/показа контента.
+- **Alert** - цветные блоки для уведомлений.
+- **Badge** - индикаторы.
+- **Button** - основная кнопка.
+- **Checkbox** - чекбокс, в том числе с состоянием "частично выбрано".
+- **Input** - поле ввода.
+- **Modal** - модальное окно на нативном `<dialog>`.
+- **Radio** - радиокнопка.
+- **RadioGroup** - группа радиокнопок.
+- **Skeleton** - заглушки для загрузки контента.
+- **Spinner** - индикатор загрузки.
+- **Switch** - переключатель.
+- **Tabs** - вкладки с навигацией с клавиатуры.
+- **Toast** - всплывающие уведомления.
+- **Tooltip** - всплывающие подсказки при наведении и фокусе.
+
+История изменений - в [CHANGELOG.md](https://github.com/Zelelo622/Iskra-UI/blob/main/CHANGELOG.md) (появится после первого релиза).
+
+---
+
+## Разработка
+
+### Окружение
+
+Версия Node.js зафиксирована в `.nvmrc`:
+
+```bash
+nvm use        # переключиться на нужную версию Node
+npm install    # зависимости + git-хуки (ставятся автоматически через lefthook)
+```
+
+После `npm install` в `.git/hooks` должны появиться `pre-commit`, `commit-msg` и `pre-push`. Если их нет - выполните `npx lefthook install`.
+
+Все файлы в репозитории хранятся с переводами строк LF (см. `.gitattributes`), поэтому на Windows не нужно ничего настраивать в git.
+
+### Команды
+
+| Команда                | Что делает                                                      |
+| :--------------------- | :-------------------------------------------------------------- |
+| `npm run dev`          | Ladle - витрина компонентов для разработки                      |
+| `npm run build`        | Сборка библиотеки в `dist` (ESM + CJS + типы + `index.css`)     |
+| `npm run lint`         | oxlint + ESLint (порядок и стиль импортов)                      |
+| `npm run lint:fix`     | То же с автоисправлением                                        |
+| `npm run format`       | Форматирование oxfmt                                            |
+| `npm run format:check` | Проверка форматирования без изменений                           |
+| `npm run typecheck`    | Проверка типов TypeScript                                       |
+| `npm run check`        | Всё сразу: lint, format:check, typecheck, build                 |
+| `npm run check:fix`    | Исправить всё, что исправляется автоматически, и прогнать check |
+
+### Git-хуки (lefthook)
+
+- **pre-commit** - oxlint и ESLint по изменённым файлам; oxfmt сам форматирует файлы и добавляет исправления в коммит.
+- **commit-msg** - commitlint проверяет сообщение коммита (правила ниже).
+- **pre-push** - проверка типов и сборка.
+
+---
+
+## Коммиты и CHANGELOG
+
+`CHANGELOG.md`, номер версии и релизы генерируются **автоматически** из истории коммитов в `main` с помощью [release-please](https://github.com/googleapis/release-please). Поэтому сообщение коммита - это не формальность: тип решает, попадёт ли изменение в changelog и какая выйдет версия, а описание пользователи прочитают в списке изменений.
+
+### Формат
+
+```
+<тип>(<область>): <описание>
+```
+
+- **тип** - обязательный, из таблицы ниже;
+- **область** - необязательная, но для изменений в компоненте указывайте её;
+- **описание** - по-русски, с маленькой буквы, без точки в конце, в прошедшем времени или как результат: «добавлено…», «исправлено…».
+
+Для ломающих изменений после типа ставится `!` (см. ниже).
+
+### Типы
+
+| Тип        | Когда использовать                                           | В CHANGELOG          | Версия |
+| :--------- | :----------------------------------------------------------- | :------------------- | :----- |
+| `feat`     | Новый компонент, проп, вариант, возможность для пользователя | «Новые возможности»  | minor  |
+| `fix`      | Исправление бага, который видит пользователь библиотеки      | «Исправления»        | patch  |
+| `perf`     | Ускорение без изменения поведения                            | «Производительность» | patch  |
+| `revert`   | Откат предыдущего коммита                                    | «Откаты»             | patch  |
+| `docs`     | README, JSDoc, сторис                                        | нет                  | -      |
+| `style`    | Форматирование, без изменения логики                         | нет                  | -      |
+| `refactor` | Переписан код без изменения поведения                        | нет                  | -      |
+| `test`     | Тесты                                                        | нет                  | -      |
+| `build`    | Сборка, tsup, `package.json`, зависимости                    | нет                  | -      |
+| `ci`       | GitHub Actions                                               | нет                  | -      |
+| `chore`    | Прочее: конфиги линтеров, хуки, рутина                       | нет                  | -      |
+
+Если с последнего релиза в `main` были только коммиты без версии (`docs`, `chore` и т. п.), релиз не создаётся.
+
+### Области
+
+- Компоненты - имя папки в нижнем регистре: `accordion`, `alert`, `badge`, `button`, `checkbox`, `input`, `modal`, `radio`, `radiogroup`, `skeleton`, `spinner`, `switch`, `tabs`, `toast`, `tooltip`. Новый компонент становится допустимой областью автоматически, как только появляется его папка в `src/components`.
+- `tokens` - CSS-переменные и дизайн-токены.
+- `utils` - общие утилиты (`src/utils`).
+- `deps` - зависимости.
+- `build`, `lint`, `ci`, `docs`, `release` - инфраструктура проекта.
+
+Если указать область, которой нет в этом списке, commitlint отклонит коммит.
+
+### Ломающие изменения
+
+Если изменение требует правок в коде у пользователей библиотеки (переименован или удалён проп, изменилось поведение по умолчанию), поставьте `!` и опишите, что делать, в теле коммита:
+
+```
+feat(button)!: проп variant="outline" переименован в "secondary"
+
+BREAKING CHANGE: замените variant="outline" на variant="secondary".
+```
+
+Пока версия ниже 1.0.0, ломающее изменение повышает minor (`0.3.0 → 0.4.0`), после 1.0.0 - major (`1.4.0 → 2.0.0`).
+
+### Примеры
+
+| ✅ Хорошо                                           | ❌ Плохо                      |
+| :-------------------------------------------------- | :---------------------------- |
+| `feat(checkbox): добавлено состояние indeterminate` | `feat: чекбокс`               |
+| `fix(modal): onClose больше не вызывается дважды`   | `fix: фикс`                   |
+| `feat(tokens): добавлены токены радиусов`           | `feat(Tokens): Радиусы.`      |
+| `chore(lint): включено правило import/no-cycle`     | `feat(lint): правила линтера` |
+| `build(deps): обновлён tsup до 8.3`                 | `refactor(deps): tsup`        |
+| `docs(input): добавлены сторис для иконок`          | `feat: сторис`                |
+
+Описание - это строка, которую увидят пользователи в CHANGELOG. Пишите, **что изменилось для них**, а не что вы делали в коде.
+
+---
+
+## Pull Request и релизы
+
+### Как вносить изменения
+
+1. Создайте ветку от `main`.
+2. Откройте Pull Request в `main`. **Заголовок PR должен соответствовать правилам коммитов** - при Squash and Merge именно он становится коммитом в `main` и строкой в CHANGELOG. Заголовок проверяется в CI.
+3. После прохождения проверок PR сливается через **Squash and Merge**.
+
+Ветка `main` защищена: прямой пуш запрещён, слить код можно только через PR с успешными проверками.
+
+### Как выходит релиз
+
+1. После каждого слияния в `main` release-please открывает или обновляет PR `chore: release X.Y.Z`. В нём уже посчитана новая версия, обновлены `package.json` и `CHANGELOG.md`.
+2. Когда нужно выпустить версию - слейте этот PR. Перед слиянием CHANGELOG в нём можно отредактировать вручную.
+3. После слияния автоматически создаются тег `vX.Y.Z` и GitHub Release, и пакет публикуется в npm.
+
+Версию в `package.json` и `CHANGELOG.md` **не меняйте руками** вне релизного PR - release-please ведёт их сам.
+
+### Однократная настройка репозитория
+
+- **Settings → Actions → General → Workflow permissions:** включить «Allow GitHub Actions to create and approve pull requests».
+- **Secret `NPM_TOKEN`** - npm access token с правом публикации пакета `@zelelo/iskra-ui`.
+- **Secret `RELEASE_PLEASE_TOKEN`** - fine-grained personal access token на этот репозиторий (Contents и Pull requests: Read and write). Нужен потому, что PR, созданный стандартным токеном GitHub Actions, не запускает CI, и обязательные проверки на релизном PR не пройдут. Без этого секрета release-please работает со стандартным токеном.
+
+---
+
+## CI / GitHub Actions
+
+| Workflow       | Когда запускается       | Что делает                                                      |
+| :------------- | :---------------------- | :-------------------------------------------------------------- |
+| `ci.yml`       | PR и пуш в `main`       | lint, format:check, typecheck, build, сборка Ladle              |
+| `pr-title.yml` | Открытие и изменение PR | Проверяет заголовок PR правилами commitlint                     |
+| `release.yml`  | Пуш в `main`            | Ведёт релизный PR; после его слияния - тег, GitHub Release, npm |
+
+---
+
+## Лицензия
+
+MIT © Zelelo622