Fork: 0
root / gnexus-ui-kit
Transfer to URL with SHA Find file
Newer
Older
gnexus-ui-kit / PROJECT_NOTES.md
@root root 3 hours ago 12 KB Add page header and description list
Raw Blame History

Рабочие заметки по 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.

Добавлены Page Header и Key-Value / Description List:

  • src/scss/components/_page-header.scss
  • src/scss/components/_description-list.scss
  • demo/partials/page-header.html
  • demo/partials/description-list.html

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

  • GNexusUIKit.Helper
  • GNexusUIKit.Toasts
  • GNexusUIKit.Modals
  • GNexusUIKit.advancedSelect
  • GNexusUIKit.editableString
  • GNexusUIKit.confirmPopup
  • GNexusUIKit.Overlays
  • GNexusUIKit.InputPatterns

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

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

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

  • 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/build debt: стили переведены на @use / @forward, map-* global functions заменены на sass:map, gulp-sass убран из pipeline в пользу modern sass.compileAsync.
  • Обновлен сборочный стек: Gulp 5, BrowserSync 3, прямые PostCSS/autoprefixer и clean-css. npm audit --audit-level=low показывает 0 vulnerabilities.
  • Добавить отдельную demo-секцию для loader/progress states.

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

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

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

  • На текущий момент npm run build проходит без Sass deprecation warnings.
  • npm audit --audit-level=low проходит без найденных уязвимостей.