# Рабочие заметки по UI-kit

Дата анализа: 2026-04-11.

## Цель

Вынести UI из `webclient` в отдельный универсальный UI-kit с простой сборкой для SCSS, HTML из частей и небольшого количества browser JS. Нужна отдельная страница демонстрации и документации компонентов.

## Что есть сейчас

`webclient` содержит старый клиент панели и уже частично оформленную страницу UI-kit:

- `webclient/ui.php` - PHP-страница демонстрации компонентов.
- `webclient/ui_components/*.php` - примеры разметки для компонентов.
- `webclient/src/scss/main.scss` - текущий общий вход SCSS.
- `webclient/src/scss/_ui.scss` - вход UI-слоя.
- `webclient/src/scss/ui_components/*.scss` - стили компонентов.
- `webclient/src/scss/_app.scss` и `webclient/src/scss/app/*.scss` - стили конкретного приложения.
- `webclient/src/js/components/*.js` - UI JS и app JS вперемешку.
- `webclient/src/js/index.js` - вход приложения, завязан на `SmartHomeApi`, routes, HUD и screens.
- `webclient/dist` - собранные CSS/JS.
- `webclient/assets` - локальные шрифты, иконки, highlight.js и картинка приложения.

## Текущая сборка

В `webclient/package.json` используется Gulp:

- SCSS: `gulp-sass`, `sass`, `autoprefixer`, `clean-css`, sourcemaps.
- JS: `esbuild` с `src/js/index.js` в `dist/js/main.js`.
- HTML partials: зависимость `gulp-file-include` есть, но HTML task и сервер сейчас фактически выключены.
- BrowserSync есть, но `serve` не включен в default task.

Для нового kit можно остаться на простом Gulp или перейти на более прямую схему: Sass CLI + esbuild + file include. Учитывая уже существующий `gulpfile.js`, самый короткий путь - привести Gulp к сборке `src/html` partials, `src/scss`, `src/js`, demo-серверу и watch.

## Граница UI-kit и приложения

UI-kit-кандидаты:

- tokens/base: `_palette-colors.scss`, `_fonts.scss`, `_mixins.scss`, `_spacing.scss`, `_utils.scss`.
- components SCSS: `typography`, `palette`, `loader`, `buttons`, `forms`, `lists`, `badges`, `tables`, `toasts`, `cards`, `modals`, `alerts`, `advanced-select`, `editable-string`.
- JS components: `toasts.js`, `modals.js`, `advanced-select.js`, `editable-string.js`, частично `confirm-popup.js`, частично `helper.js`.
- demo markup: `ui_components/*.php` можно конвертировать в HTML partials.

App-only или переносить отдельно как пример потребителя:

- `_app.scss`.
- `app/_hud.scss`, `app/_load-screen.scss`, `app/_error-screen.scss`, `app/_empty-here.scss`.
- `src/js/index.js`, `routes.js`, `DataProvider.js`, `sh/SmartHomeApi.js`, `Screens.js`, `hud.js`.
- `index.php`, `proxy.php`, `config.php`.

## Компоненты в текущем demo

Документированы на `ui.php`:

- Typography
- Color Palette
- Buttons
- Forms
- Editable String
- Lists
- Badges & Status
- Alerts
- Tables
- Toasts
- Cards
- Modals

Есть SCSS для `loader` и `advanced-select`, но отдельной полной demo-секции для loader нет, а advanced-select показан внутри forms.

## Дизайн-система

Текущий стиль:

- IBM Plex Mono как базовый шрифт.
- Phosphor Icons как icon font.
- темная cyberpunk/neon палитра.
- нулевые радиусы у кнопок и инпутов.
- много uppercase/mono UI.

Основные токены:

- colors: `$color-black`, `$color-dark`, `$color-grey`, `$color-cyan`, `$color-magenta`, `$color-hot-pink`, `$color-electric-blue`, `$color-orange`, `$color-purple`, `$color-indigo`, `$color-teal`, `$color-neon-yellow`, `$color-neon-green`, `$color-text-*`, `$color-primary`, `$color-secondary`, `$color-accent`, `$color-success`, `$color-warning`, `$color-error`, `$color-info`.
- spacing: `$space-0` ... `$space-12`, плюс aliases `xs/sm/md/lg/xl/xxl`.
- typography: `$font-family-base`, weights, sizes `xs..xl`, headings `h1..h6`, line heights.
- breakpoints: `xs 360`, `sm 480`, `md 768`, `lg 1024`, `xl 1280`, `xxl 1440`.

## JS замечания из первичного анализа

На момент анализа `webclient` компонентный JS был не полностью модульным: часть компонентов зависела от глобальных `Helper`, `Modals`, `Screens`, а app entry запускал routing и SmartHome API. В текущем root UI-kit entry эти app-зависимости убраны: компоненты импортируются модульно, экспортируются в `window` и `window.GNexusUIKit`, приложение не запускается.

## Риски переноса

- PHP include demo нужно заменить на HTML partials.
- Абсолютные asset URL вида `/assets/...` в CSS/HTML нужно сделать корректными для нового dist/demo.
- Нужно решить, копировать локальные шрифты и phosphor-icons в kit или подключать через npm/build.
- В demo есть внешняя placeholder-картинка в cards; лучше заменить локальным asset или убрать зависимость от внешней картинки.
- Смешение глобальных классов `.section`, `.container`, `.block`, `.row`, `.list` может конфликтовать с потребителями kit. На первом этапе можно оставить как есть, но в документации отметить глобальность.

## Предлагаемый первый этап

1. Создать структуру kit: `src/scss`, `src/js`, `src/html`, `src/partials`, `public/assets`, `dist`.
2. Разделить SCSS entries: `kit.scss` для UI и, при необходимости, `app-demo.scss` только для демо-страницы.
3. Перенести PHP demo partials в HTML partials.
4. Сделать JS entry для kit: `Toasts`, `Modals`, `advancedSelect`, `editableString`, `confirmPopup`, `Helper`.
5. Обновить сборку: SCSS, JS bundle, HTML partials, static assets, dev server/watch.
6. Проверить demo в браузере и затем уже менять стилизацию.

## Фактическая структура после старта среды

- `package.json` - root npm scripts: `npm run build`, `npm run dev`, `npm start`.
- `gulpfile.js` - сборка SCSS, JS, HTML partials, static assets и BrowserSync server.
- `src/scss/kit.scss` - основной SCSS entry UI-kit.
- `src/scss/components/*.scss` - перенесенные стили UI-компонентов.
- `src/js/index.js` - browser entry, экспортирует UI API в `window` и `window.GNexusUIKit`.
- `src/js/components/*.js` - перенесенные JS-компоненты UI-kit.
- `demo/index.html` - демонстрационная страница.
- `demo/partials/*.html` - HTML partials, перенесенные из бывших PHP demo partials.
- `public/assets` - исходные статичные assets для demo/build.
- `dist` - генерируемый результат сборки, игнорируется git.

## Текущее состояние UI-kit

Дизайн теперь универсальный, без доменной привязки к умному дому. Визуальный стиль: dark cyber/terminal с легкой примесью Tokyo Night, IBM Plex Mono, Phosphor Icons, прямые формы, толстые акцентные бордеры, яркие status colors. После Tokyo Night pass на плотных светлых state-заливках используется темный `$color-black` текст для контраста.

Favicon и карточечный image asset заменены на нейтральный `public/assets/imgs/gnexus-mark.svg`; старый `sh-icon.png` удален.

Документированные секции demo:

- Typography
- Palette
- Buttons
- Forms
- Editable String
- Navigation & Overlays
- Lists
- Badges
- Alerts
- Tables
- Data Patterns
- Toasts
- Cards
- Modals

Новые компоненты после базового scaffold:

- `src/scss/components/_navigation-overlays.scss`
- `src/js/components/overlays.js`
- `demo/partials/navigation-overlays.html`
- `src/scss/components/_input-group.scss`
- `src/scss/components/_data-patterns.scss`
- `src/js/components/input-patterns.js`
- `demo/partials/data-patterns.html`

`Navigation & Overlays` включает tabs, dropdown, tooltip, popover. `Data Patterns` включает toolbar, search field, input group, pagination, empty state, skeleton.

Публичный JS API:

- `GNexusUIKit.Helper`
- `GNexusUIKit.Toasts`
- `GNexusUIKit.Modals`
- `GNexusUIKit.advancedSelect`
- `GNexusUIKit.editableString`
- `GNexusUIKit.confirmPopup`
- `GNexusUIKit.Overlays`
- `GNexusUIKit.InputPatterns`

`Overlays.init()` и `InputPatterns.init()` запускаются автоматически на `DOMContentLoaded`.

## Запланированные компоненты

Ближайшие полезные additions:

- Page Header: заголовок страницы, subtitle, actions, status.
- Key-Value / Description List: компактный read-only блок для деталей сущности.
- Progress: progress bar, usage meter, staged progress.
- Stepper / Steps: пошаговые сценарии и wizard-flow.
- Chip / Tag: selectable/removable метки для фильтров и labels.
- Avatar / Identity: initials, icon avatar, image avatar, status marker.
- Timeline / Activity Log: история событий, audit log, jobs.
- Accordion / Disclosure: раскрываемые группы настроек и деталей.
- Drawer / Side Panel: контекстные детали и quick edit без полной модалки.
- Confirm Dialog docs: `confirm-popup.js` уже есть, но его нужно вывести в demo/docs.

Технический backlog:

- Закрыты JS-долги из ревью: toast title/text, confirm text и advanced-select options больше не строятся через HTML-строки; `Overlays.init()` и `InputPatterns.init()` идемпотентны для повторных roots; advanced-select устойчивее при пустых результатах; app-хвост `Screens` и production `console.log` удалены из toasts.
- В `Modals` сохранен явный HTML escape hatch через `bodyHtml` / `bodyMode: "html"` для сложной разметки; для обычных строк использовать `bodyText`.
- Мигрировать Sass с `@import` на `@use`.
- Заменить deprecated Sass functions на `sass:map` и `sass:color`.
- Пересмотреть Gulp-зависимости или заменить сборку на более свежий простой pipeline.
- Добавить отдельную demo-секцию для loader/progress states.

Проверенные команды:

- `npm install` - установлены зависимости.
- `npm run build` - сборка проходит.
- `npm run dev` - запускает BrowserSync на `http://localhost:3000`.

Текущие предупреждения:

- Sass ругается на legacy JS API, `@import`, `lighten()`, `map-get()` и `map-has-key()`. Это не блокирует сборку, но перед долгой жизнью kit лучше мигрировать на `@use`, `color.adjust`, `map.get`, `map.has-key`.
- `npm audit` после установки показывает уязвимости в цепочке старого Gulp-стека. Позже стоит либо обновить зависимости, либо заменить Gulp на более свежую легкую сборку.