@koslibs/components 0.0.0-stage → 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+# @koslibs/components
+
+Опубликованных версий пока нет. После первого релиза Changesets добавит сюда историю пакета.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+Демо: <https://koslibs.github.io/components/>
 
-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.
+## Добавление компонента
+
+Рекомендуемая структура:
+
+```text
+src/components/Button/
+    index.ts
+    button.tsx
+    button.module.css
+    button.stories.tsx
+    button.docs.tsx
+    CHANGELOG.md
+```
+
+1. Перенесите компонент в `src/components/<Name>`; имя папки — PascalCase, например `Button`.
+   Регистр пути важен, в том числе на Linux. Стили храните в CSS Modules.
+2. Экспортируйте публичный API из его `index.ts`. Для удобного импорта из корня можно
+   также добавить реэкспорт в `src/index.ts`; отдельный импорт компонента его не использует.
+3. Общий шаблон в `package.json` → `exports` уже связывает каждый компонент с его файлами:
+
+   ```json
+   {
+       "./*": {
+           "types": "./dist/components/*/index.d.ts",
+           "import": "./dist/components/*/index.js"
+       }
+   }
+   ```
+
+4. Добавьте Docs, Playground и `CHANGELOG.md` по [примеру документации](https://github.com/koslibs/components/blob/main/docs/component-changelogs.md).
+5. Добавьте тесты поведения. Unit-тесты можно запускать через `koslibs-builder lib:test`;
+   в каркасе unit-suite отсутствует, потому что runtime-компонентов пока нет.
+6. Выполните сборку и проверьте реальные пути JS, деклараций и CSS в `dist`.
+
+После публикации предполагается такой импорт:
+
+```tsx
+import { Button } from '@koslibs/components/Button';
+```
+
+Этот путь ведёт прямо к `dist/components/Button/index.js`, минуя общий `dist/index.js`.
+Входной файл компонента должен экспортировать только свой API и импортировать только
+нужные ему зависимости; не импортируйте внутри компонента общий barrel библиотеки.
+Builder сохраняет отдельные JS-модули и отдельные CSS-файлы для каждого компонента.
+Поэтому приложение подключает выбранный компонент, его стили и необходимые зависимости.
+Соседние независимые компоненты не входят в его граф импортов.
+
+При установке npm скачивает весь пакет; отдельные импорты ограничивают состав бандла
+приложения. React, общие утилиты и другие зависимости используемого компонента
+по-прежнему могут входить в бандл.
+
+Тест `tests/component-imports.test.mjs` запускается через Node.js test runner командой
+`npm test` (или отдельно `npm run test:imports`) и проверяет схему через builder:
+собирает временную библиотеку с Button
+и Spinner, затем приложение с импортом только `@koslibs/components/Button`.
+Проверка подтверждает наличие Button и его CSS и отсутствие Spinner и его CSS
+в production-бандле. Временные компоненты находятся в `.cache` и не публикуются.
+
+Пакет выпускается в ESM. CSS помечен как side effect, чтобы оптимизация потребителя
+не удаляла стили. Builder сохраняет структуру модулей; Docs, stories и Markdown
+исключены из npm-сборки. Storybook загружает Markdown как текст через `?raw`.

package/dist/index.d.ts

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

package/package.json

@@ -1,6 +1,80 @@
 {
-  "name": "@koslibs/components",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@koslibs/components",
+    "version": "0.0.0",
+    "description": "Shared React components for koslibs projects",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./*": {
+            "types": "./dist/components/*/index.d.ts",
+            "import": "./dist/components/*/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "CHANGELOG.md"
+    ],
+    "sideEffects": [
+        "**/*.css"
+    ],
+    "engines": {
+        "node": ">=24.13.0"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/koslibs/components.git"
+    },
+    "homepage": "https://koslibs.github.io/components/",
+    "bugs": {
+        "url": "https://github.com/koslibs/components/issues"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "start": "koslibs-builder lib:start",
+        "watch": "koslibs-builder lib:watch",
+        "build": "koslibs-builder lib:build",
+        "typecheck": "koslibs-builder lib:typecheck",
+        "lint": "koslibs-lint lint",
+        "lint:fix": "koslibs-lint lint:fix",
+        "format": "koslibs-lint format",
+        "format:check": "koslibs-lint format:check",
+        "storybook": "koslibs-builder storybook:start",
+        "build-storybook": "koslibs-builder storybook:build",
+        "test": "node --test tests/*.test.mjs",
+        "test:imports": "node --test tests/component-imports.test.mjs",
+        "prepack": "koslibs-builder lib:build",
+        "changeset": "koslibs-release add",
+        "changeset:check": "koslibs-release check",
+        "version-package": "koslibs-release version",
+        "release": "koslibs-release publish",
+        "prepare": "koslibs-release hooks:install"
+    },
+    "prettier": "@koslibs/configs/prettier",
+    "commitlint": {
+        "extends": [
+            "@koslibs/configs/commitlint"
+        ]
+    },
+    "devDependencies": {
+        "@koslibs/builder": "^1.0.0",
+        "@koslibs/configs": "^1.0.0",
+        "@types/node": "^24.19.0",
+        "@types/react": "^18.3.18",
+        "@types/react-dom": "^18.3.5",
+        "react": "18.3.1",
+        "react-dom": "18.3.1"
+    },
+    "peerDependencies": {
+        "react": "^18.3.1 || ^19.0.0",
+        "react-dom": "^18.3.1 || ^19.0.0"
+    }
+}