Make application shell components package-native

2026-07-10 12:41:12 +03:00
parent 9261d3af36
commit ebae662b52
52 changed files with 1036 additions and 185 deletions
@@ -0,0 +1,48 @@
+# Подключение дизайн-системы
+
+## Главный принцип
+
+Новый проект не копирует исходники компонентов из Launcher, CMS или этого репозитория. Он устанавливает версию пакетов NODE.DC, импортирует общий CSS и собирает интерфейс из публичных exports. Обновление пакета должно исправлять геометрию во всех подключённых приложениях без повторной ручной вёрстки.
+
+`control-c / control-v` допустим только для короткой композиции приложения: какие routes и данные переданы готовым компонентам. CSS, DOM-анатомия header, оконные переходы, media control и accessibility не копируются.
+
+## React consumer
+
+Минимальный состав нового оконного приложения:
+
+1. `@nodedc/tokens`, `@nodedc/ui-core` и `@nodedc/ui-react` фиксируются одной версией.
+2. Один раз подключаются `tokens.css`, `themes.css` и `@nodedc/ui-core/styles.css`.
+3. Theme/accent задаются через `applyNodedcTheme`.
+4. Приложение собирает `ApplicationShell` из `AppHeader`, `AdminNavigationPanel` и `ApplicationPanel`.
+5. Все состояния shell берутся из `useApplicationWorkspace`.
+6. Routes, profile, stage content и бизнес-данные передаются props.
+
+Нельзя добавлять local CSS к `AppHeader`, `HeaderNavigation`, `HeaderWorkspace`, `HeaderProfile` и `HeaderAvatar`. Если production Launcher изменяет канон, исправляется preset здесь и выпускается новая версия.
+
+## DOM consumer
+
+CMS/BIM подключают те же tokens/core styles и `@nodedc/ui-dom`. `createApplicationWorkspaceController`, `createMediaSourceController`, `createFloatingLayer` и `createModalController` связывают стабильную DOM-анатомию с тем же поведением, не вводя React в приложение.
+
+## Adapter boundary
+
+Общие компоненты не импортируют API конкретного проекта.
+
+| Библиотека владеет | Приложение владеет |
+| --- | --- |
+| размеры, радиусы, поверхности | маршруты и тексты |
+| header/window/media DOM anatomy | API, auth и permissions |
+| open/close/expand state machine | получение и сохранение данных |
+| file/URL selector и preview | file picker/media library/storage upload |
+| focus, Escape, portal, responsive flow | доменная валидация и ошибки backend |
+
+Например, `MediaSourceField` получает `onFileChange`. Consumer загружает файл, получает URL и возвращает его в контролируемое состояние. Компонент не знает S3, локальный диск, CMS media library или endpoint Launcher.
+
+## Definition of done для нового общего компонента
+
+- экспортируется из React или DOM package;
+- использует tokens/core styles без screen-local geometry;
+- показан в живом каталоге в ключевых состояниях;
+- записан в `registry/components.json`;
+- имеет документированную adapter boundary;
+- проходит desktop/mobile visual QA;
+- версия пакета зафиксирована consumer-ом.