@pgcorp/ui-kit 0.1.0 → 0.1.2

package/README.md

@@ -1,33 +1,27 @@
 # @pgcorp/ui-kit
 
-[![npm version](https://img.shields.io/npm/v/%40pgcorp%2Fui-kit)](https://www.npmjs.com/package/@pgcorp/ui-kit)
-[![npm downloads](https://img.shields.io/npm/dm/%40pgcorp%2Fui-kit)](https://www.npmjs.com/package/@pgcorp/ui-kit)
-[![Vue 3](https://img.shields.io/badge/Vue-3.5%2B-42b883)](https://vuejs.org/)
-[![License](https://img.shields.io/npm/l/%40pgcorp%2Fui-kit)](./LICENSE)
+**Типизированная дизайн-система PGCorp для Vue 3: от базовых controls до
+полноценных workbench-интерфейсов.**
 
-Production design system PGCorp для Vue 3: типизированные компоненты, layout-примитивы,
-design tokens, темы, accessibility-контракты и готовые сложные интерфейсные паттерны.
+**A typed PGCorp design system for Vue 3, spanning foundational controls and
+complete workbench interfaces.**
 
-PGCorp production design system for Vue 3: typed components, layout primitives,
-design tokens, themes, accessibility contracts, and reusable complex UI patterns.
+`Vue 3` · `TypeScript` · `118 exact exports` · `6 themes` · `MIT`
 
-## Возможности / Features
+## Что входит / What is included
 
-- 118 точных package exports без wildcard и private imports.
-- Vue Single-File Components с TypeScript-контрактами.
-- Светлые и тёмные темы на semantic CSS tokens.
-- Controls, navigation, data display, overlays, workbench layouts, editors and graphs.
-- Keyboard, focus, ARIA, disabled, loading and error states.
-- Проверяемые unit, Storybook, browser, accessibility и visual contracts.
-
----
-
-- 118 exact package exports without wildcards or private imports.
-- Vue Single-File Components with TypeScript contracts.
-- Light and dark themes built on semantic CSS tokens.
-- Controls, navigation, data display, overlays, workbench layouts, editors, and graphs.
-- Keyboard, focus, ARIA, disabled, loading, and error states.
-- Executable unit, Storybook, browser, accessibility, and visual contracts.
+- Vue Single-File Components с типизированными props, slots, events и exposed methods.
+  Vue Single-File Components with typed props, slots, events, and exposed methods.
+- Controls, navigation, containers, data display, overlays и layout-примитивы.
+  Controls, navigation, containers, data display, overlays, and layout primitives.
+- Таблицы, деревья, редакторы, graph surfaces и составные workbench-компоненты.
+  Tables, trees, editors, graph surfaces, and composed workbench components.
+- Semantic CSS tokens и шесть светлых и тёмных тем.
+  Semantic CSS tokens and six light and dark themes.
+- Контракты keyboard navigation, focus, ARIA, loading, disabled, invalid и error states.
+  Contracts for keyboard navigation, focus, ARIA, loading, disabled, invalid, and error states.
+- Только явные package exports: wildcard и private source imports отсутствуют.
+  Explicit package exports only, with no wildcards or private source imports.
 
 ## Установка / Installation
 
@@ -35,123 +29,240 @@ design tokens, themes, accessibility contracts, and reusable complex UI patterns
 npm install @pgcorp/ui-kit vue pinia vue-router
 ```
 
-Требования:
-
-- Node.js `>=20.19`;
-- npm `>=11.10 <12`;
-- Vue `^3.5`;
-- Pinia `^3.0`;
-- Vue Router `^5.0`;
-- Vite-based Vue application.
+| Требование / Requirement | Версия / Version |
+| --- | --- |
+| Node.js | `>=20.19.0` |
+| npm | `>=11.10.0 <12` |
+| Vue | `^3.5.0` |
+| Pinia | `^3.0.4` |
+| Vue Router | `^5.0.0` |
+| Build tool | Vite with Vue SFC support |
 
-Requirements:
+`vue`, `pinia` и `vue-router` являются peer dependencies. Consumer-приложение
+владеет их единственными runtime-экземплярами.
 
-- Node.js `>=20.19`;
-- npm `>=11.10 <12`;
-- Vue `^3.5`;
-- Pinia `^3.0`;
-- Vue Router `^5.0`;
-- a Vite-based Vue application.
+`vue`, `pinia`, and `vue-router` are peer dependencies. The consumer application
+owns their single runtime instances.
 
 ## Быстрый старт / Quick start
 
-Подключите базовые стили один раз в entrypoint приложения:
+Подключите Pinia, router и базовые стили в entrypoint приложения:
 
-Import the base stylesheet once in the application entrypoint:
+Register Pinia, the router, and the base stylesheet in the application entrypoint:
 
 ```ts
+import { createPinia } from 'pinia'
 import { createApp } from 'vue'
 import '@pgcorp/ui-kit/style.css'
 
 import App from './App.vue'
+import router from './router'
 
-createApp(App).mount('#app')
+createApp(App)
+  .use(createPinia())
+  .use(router)
+  .mount('#app')
 ```
 
-Импортируйте компоненты только через документированные subpaths:
+Импортируйте каждый компонент через точный публичный subpath:
 
-Import components only through documented subpaths:
+Import every component through its exact public subpath:
 
 ```vue
 <script setup lang="ts">
-import SButton from '@pgcorp/ui-kit/shared/controls/SButton.vue'
 import SPanel from '@pgcorp/ui-kit/shared/containers/SPanel.vue'
+import SButton from '@pgcorp/ui-kit/shared/controls/SButton.vue'
 </script>
 
 <template>
-  <SPanel>
-    <template #header>Профиль</template>
-    <SButton variant="primary">Сохранить</SButton>
+  <SPanel
+    title="Профиль"
+    description="Настройки рабочей области"
+    :heading-level="2"
+    content-layout="stack"
+    content-gap="content"
+  >
+    <SButton variant="primary">
+      Сохранить
+    </SButton>
   </SPanel>
 </template>
 ```
 
-## Стили и темы / Styling and themes
+Production build должен разрешать package exports напрямую, без alias на
+исходный monorepo и без копирования файлов UI-kit.
+
+The production build must resolve package exports directly, without a source
+monorepo alias or copied UI-kit files.
+
+## Карта компонентов / Component map
+
+| Группа / Group | Назначение / Purpose | Примеры exports / Example exports |
+| --- | --- | --- |
+| Layout | App shell, dock regions, stacks, workbench layout | `layout/SAppShell.vue`, `layout/SStack.vue`, `layout/SWorkbenchLayout.vue` |
+| Controls | Buttons, fields, inputs, selects, menus, selection | `shared/controls/SButton.vue`, `shared/controls/SInputText.vue`, `shared/controls/SSelect.vue` |
+| Containers | Panels, modal, drawer, popover, sidebars | `shared/containers/SPanel.vue`, `shared/containers/SModal.vue`, `shared/containers/SPopover.vue` |
+| Data display | Tables, status, progress, code, JSON, tooltips | `shared/data-display/STable.vue`, `shared/data-display/SCodeBlock.vue`, `shared/data-display/SStatus.vue` |
+| Navigation | Tabs, breadcrumbs, catalog navigation, wizard | `shared/navigation/STabs.vue`, `shared/navigation/SBreadcrumbs.vue`, `shared/navigation/SWizardSteps.vue` |
+| Complex surfaces | Tree, Kanban, data grid, SQL editor, graph | `shared/complex/STree.vue`, `shared/database/SDataGrid.vue`, `shared/graph/SGraphViewport.vue` |
+| Runtime | Themes, variants, icons, composables, stores | `theme`, `variants`, `icons`, `composables/useNotifier`, `stores/useNotifierStore` |
+
+Полный машинно-читаемый каталог находится в `package.json#exports`. IDE и
+TypeScript показывают доступные subpaths при импорте.
+
+The complete machine-readable catalog is declared in `package.json#exports`.
+IDEs and TypeScript expose the available subpaths during import.
+
+## Темы и стили / Themes and styles
 
-`style.css` подключает semantic tokens и базовый визуальный контракт. Для token-only
-интеграции доступен отдельный export:
+Для обычного приложения подключайте полный style entrypoint один раз:
 
-`style.css` provides semantic tokens and the base visual contract. A token-only
-integration is available as a separate export:
+For a regular application, import the complete style entrypoint once:
+
+```ts
+import '@pgcorp/ui-kit/style.css'
+```
+
+Для token-only интеграции доступен отдельный entrypoint:
+
+A separate entrypoint is available for token-only integration:
 
 ```ts
 import '@pgcorp/ui-kit/tokens.css'
 ```
 
-Компоненты используют semantic tokens. Consumer не переоформляет внутренний DOM
-компонентов через deep selectors; варианты задаются публичными props, slots и tokens.
+Тема применяется через типизированный runtime API:
+
+Apply a theme through the typed runtime API:
+
+```ts
+import { applyThemeIdToDocument } from '@pgcorp/ui-kit/theme'
+
+applyThemeIdToDocument(document, 'classic-dark')
+```
+
+Поддерживаемые идентификаторы:
+
+Supported identifiers:
+
+```ts
+type ThemeId =
+  | 'classic-light'
+  | 'classic-dark'
+  | 'pink-light'
+  | 'pink-dark'
+  | 'green-light'
+  | 'green-dark'
+```
+
+Компоненты используют semantic custom properties. Consumer переопределяет
+документированные tokens на корневом theme-контейнере и не зависит от
+внутренних CSS-классов или структуры template.
 
-Components consume semantic tokens. Consumers do not restyle component internals
-through deep selectors; variants are expressed through public props, slots, and tokens.
+Components consume semantic custom properties. Consumers override documented
+tokens on the root theme container and do not depend on internal CSS classes or
+template structure.
 
-Подробнее: [темы и tokens](./docs/theming.md).
+## Публичный контракт / Public contract
 
-Learn more: [themes and tokens](./docs/theming.md).
+`package.json#exports` — источник истины для импортов. Публичный контракт
+компонента состоит из typed props, slots, events и exposed methods.
 
-## Публичный API / Public API
+`package.json#exports` is the source of truth for imports. A component's public
+contract consists of typed props, slots, events, and exposed methods.
 
-Корневой export содержит theme, variants и icon registry:
+Поддерживается:
 
-The root export contains theme, variants, and the icon registry:
+Supported:
 
 ```ts
-import { applyThemeIdToDocument, uiVariantClasses } from '@pgcorp/ui-kit'
+import SModal from '@pgcorp/ui-kit/shared/containers/SModal.vue'
+import { useNotifier } from '@pgcorp/ui-kit/composables/useNotifier'
+import { themeVariants } from '@pgcorp/ui-kit/theme'
 ```
 
-Компоненты и модули импортируются через exact subpaths из `package.json#exports`.
-Wildcard imports и доступ к внутренним путям пакета не поддерживаются.
+- Не используйте wildcard imports и private source paths.
+  Do not use wildcard imports or private source paths.
+- Не стилизуйте внутренний DOM через `:deep` и private selectors.
+  Do not style internal DOM through `:deep` or private selectors.
+- Выражайте состояние через documented props, slots, variants и tokens.
+  Express state through documented props, slots, variants, and tokens.
+- Передавайте человекочитаемые labels интерактивным компонентам.
+  Provide human-readable labels to interactive components.
+
+## Доступность / Accessibility
+
+Leaf-компоненты UI-kit владеют интерактивной семантикой:
+
+UI-kit leaf components own interactive semantics:
+
+- keyboard navigation и ожидаемые клавиши / keyboard navigation and expected keys;
+- visible focus и focus restoration / visible focus and focus restoration;
+- accessible names, roles и ARIA state / accessible names, roles, and ARIA state;
+- disabled, loading, invalid и error states / disabled, loading, invalid, and error states;
+- hitboxes и narrow-viewport behavior / hitboxes and narrow-viewport behavior.
+
+Consumer передаёт содержательные labels и не заменяет семантику компонента
+локальными DOM listeners или CSS.
 
-Components and modules are imported through exact subpaths declared in
-`package.json#exports`. Wildcard imports and package-internal paths are unsupported.
+Consumers provide meaningful labels and do not replace component semantics with
+local DOM listeners or CSS.
 
-Полный маршрут по API: [Public API](./docs/public-api.md).
+## Версии / Versioning
 
-Complete API guide: [Public API](./docs/public-api.md).
+Пакет следует Semantic Versioning:
 
-## Документация / Documentation
+The package follows Semantic Versioning:
 
-- [Начало работы / Getting started](./docs/getting-started.md)
-- [Public API](./docs/public-api.md)
-- [Темы и design tokens / Themes and design tokens](./docs/theming.md)
-- [Accessibility](./docs/accessibility.md)
-- [Версии и релизы / Versioning and releases](./docs/versioning.md)
-- [Лицензирование и Enterprise / Licensing and Enterprise](./docs/licensing.md)
-- [Безопасность / Security](./docs/security.md)
+- `patch` — исправление с сохранением документированного контракта;
+  a fix that preserves the documented contract;
+- `minor` — обратно совместимое расширение public API;
+  a backward-compatible public API extension;
+- `major` — несовместимое изменение exports, props, events, tokens или поведения;
+  an incompatible change to exports, props, events, tokens, or behavior.
 
-## Поддержка / Support
+Один и тот же номер версии не публикуется повторно.
 
-Ошибки и запросы на изменение принимаются по адресу
-[remand-gambol4g@icloud.com](mailto:remand-gambol4g@icloud.com).
-Security reports отправляются по процессу из [Security](./docs/security.md).
+A version number is never republished.
 
-Bugs and change requests are accepted at
-[remand-gambol4g@icloud.com](mailto:remand-gambol4g@icloud.com).
-Security reports follow the process documented in [Security](./docs/security.md).
+## Поддержка и безопасность / Support and security
+
+Контакт сопровождения хранится в npm package metadata:
+
+The maintainer contact is published in the npm package metadata:
+
+```bash
+npm view @pgcorp/ui-kit bugs
+```
+
+Для дефекта укажите версию, affected subpath, воспроизводимый сценарий,
+ожидаемое и фактическое поведение.
+
+For a defect report, include the version, affected subpath, reproducible
+scenario, expected behavior, and actual behavior.
+
+Сведения об уязвимости не публикуются открыто до согласования исправления.
+Private security report включает версию, affected component/subpath,
+reproduction, impact и известные ограничения.
+
+Do not disclose vulnerability details publicly before a fix is coordinated. A
+private security report includes the version, affected component/subpath,
+reproduction, impact, and known constraints.
 
 ## Лицензия / License
 
-`@pgcorp/ui-kit` распространяется по лицензии MIT. Copyright и текст лицензии
-должны сохраняться в копиях и существенных частях пакета. См. [LICENSE](./LICENSE).
+`@pgcorp/ui-kit` распространяется по лицензии MIT. Copyright notice и текст
+лицензии сохраняются в копиях и существенных частях пакета.
 
 `@pgcorp/ui-kit` is distributed under the MIT License. The copyright and license
-notice must be retained in copies and substantial portions. See [LICENSE](./LICENSE).
+notice must be retained in copies and substantial portions of the package.
+
+Enterprise-возможности могут поставляться отдельным закрытым пакетом,
+приложением или сервисом по коммерческой лицензии. Это не изменяет лицензию
+опубликованных MIT-версий `@pgcorp/ui-kit`. Название PGCorp и связанные товарные
+знаки не лицензируются условиями MIT.
+
+Enterprise capabilities may be distributed as a separate private package,
+application, or service under a commercial license. This does not change the
+license of published MIT versions of `@pgcorp/ui-kit`. The PGCorp name and
+related trademarks are not licensed under the MIT License.

package/docs/security.md

@@ -3,9 +3,11 @@
 ## Русский
 
 Не публикуйте сведения об уязвимости в public issue до согласования исправления.
-Отправьте private security report на
-[remand-gambol4g@icloud.com](mailto:remand-gambol4g@icloud.com) с темой
-`[SECURITY] @pgcorp/ui-kit`.
+Актуальный private contact сопровождения доступен в npm package metadata:
+
+```bash
+npm view @pgcorp/ui-kit bugs
+```
 
 Укажите версию пакета, затронутый component/subpath, воспроизводимый сценарий,
 impact и известные ограничения.
@@ -13,9 +15,11 @@ impact и известные ограничения.
 ## English
 
 Do not disclose a vulnerability in a public issue before a fix is coordinated.
-Send a private security report to
-[remand-gambol4g@icloud.com](mailto:remand-gambol4g@icloud.com) with the subject
-`[SECURITY] @pgcorp/ui-kit`.
+The current private maintainer contact is available from npm package metadata:
+
+```bash
+npm view @pgcorp/ui-kit bugs
+```
 
 Include the package version, affected component/subpath, reproducible scenario,
 impact, and known constraints.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pgcorp/ui-kit",
-  "version": "0.1.0",
-  "description": "Production Vue 3 design system and UI component library for Sputnig applications.",
+  "version": "0.1.2",
+  "description": "Typed Vue 3 design system with accessible components, semantic themes, and workbench patterns.",
   "type": "module",
   "types": "./index.ts",
   "files": [
@@ -19,11 +19,17 @@
   "keywords": [
     "vue",
     "vue3",
+    "vite",
+    "typescript",
     "ui-kit",
+    "component-library",
     "design-system",
-    "components",
-    "typescript",
-    "accessibility"
+    "design-tokens",
+    "accessibility",
+    "a11y",
+    "dark-theme",
+    "data-grid",
+    "workbench"
   ],
   "license": "MIT",
   "author": "PGCorp",
@@ -543,7 +549,7 @@
     "@codemirror/theme-one-dark": "^6.1.3",
     "@codemirror/view": "^6.39.15",
     "@uiw/codemirror-extensions-langs": "^4.25.8",
-    "codemirror": "^6.0.2",
+    "codemirror": "6.0.2",
     "codemirror-lang-makefile": "^0.1.1",
     "dompurify": "^3.4.12",
     "graphology": "^0.26.0",