GNexus UI Kit

UI-kit для веб-интерфейсов GNexus. Текущий стиль: темная cyber/terminal панель с легкой примесью Tokyo Night, IBM Plex Mono, Phosphor Icons, жесткие прямые формы, акцентные бордеры и яркие состояния.

Проект выделен из старого webclient, но развивается как отдельный набор UI-компонентов с demo/docs страницей.

Документация

Человеческая документация по подключению, стилю, JS API и компонентам находится в docs/. Официальный Vue 3 adapter описан в docs/vue.md.

Использование с ИИ-агентами

Если над проектом работает AI-агент (Claude, Cursor, Copilot, Codex, ...), укажите ему на:

• AGENTS.md — точка входа для агентов (файл едет в npm-пакет).
• docs/ai-guide.md — полный гайд: как выбирать компоненты из каталога, какие варианты/иконки допустимы, и рецепт «как сделать кастомный компонент в стиле GNexus» (токены, hard_panel, uppercase-заголовки, focus_ring, hover_touch).
• docs/catalog.json — машиночитаемый каталог: need → component → props → useWhen.

Быстрый способ — вставить готовый блок правил в CLAUDE.md/AGENTS.md проекта-потребителя (сниппет в конце docs/ai-guide.md).

Быстрый старт

npm install
npm run dev

Dev server:

http://localhost:3000

Production build:

npm run build

Release check:

npm run release:check

Vue adapter only:

npm run build:vue

Vue example smoke build:

npm --prefix examples/vue install
npm run build:example:vue

Структура

demo/                 Demo/docs страница и HTML partials
public/assets/        Шрифты, иконки, highlight.js и изображения
src/js/               Browser JS entry и UI-компоненты
src/scss/             SCSS entry, tokens, utilities и компоненты
dist/                 Результат сборки, не коммитится
webclient/            Исходный старый клиент, игнорируется git

Ключевые entry points:

src/scss/kit.scss     Основной CSS UI-kit
src/scss/demo.scss    CSS для demo/docs страницы
src/js/index.js       Browser JS bundle entry
src/vue/index.js      Vue 3 adapter entry
demo/index.html       Demo/docs страница

Команды

npm run dev

Собирает проект, запускает BrowserSync и следит за изменениями.

npm run build

Собирает:

• dist/css/kit.css
• dist/css/demo.css
• dist/js/gnexus-ui-kit.js
• dist/vue/index.js
• dist/index.html
• dist/assets/*

npm run release:check

Runs the Vue adapter smoke build and package smoke validation from a packed tarball. See docs/release.md.

Использование

Для подключения kit в обычную HTML-страницу нужны CSS, иконки и JS bundle:

<link rel="stylesheet" href="/assets/fonts/phosphor-icons/src/css/icons.css">
<link rel="stylesheet" href="/css/kit.css">
<script src="/js/gnexus-ui-kit.js"></script>

JS bundle публикует API в window:

Toasts.createSuccess("Success", "Saved").show();

const modal = Modals.create("example-modal", {
  title: "Modal",
  bodyText: "Content"
});

modal.show();

Также доступен global namespace:

GNexusUIKit.Toasts.createInfo("Info", "Message").show();

В kit.css дизайн-токены публикуются как CSS custom properties --gn-* на :root — в проекте без сборщика можно стилизовать через var(--gn-color-secondary), var(--gn-space-4) и т.д. без сырых хексов. Полный список — в docs/style-guide.md.

Vue Adapter (Primary Contract)

In Vue projects, always use the official adapter. It is the primary contract — not a thin wrapper. Import CSS once, then use adapter components:

import "gnexus-ui-kit/dist/css/kit.css";
import "gnexus-ui-kit/dist/assets/fonts/phosphor-icons/src/css/icons.css";
import { GnButton, GnTabs, GnexusUiVue } from "gnexus-ui-kit/vue";

Do not write raw .btn, .modal, .tabs markup in Vue SFCs when the adapter exposes GnButton, GnModal, GnTabs.

Icon Naming

All icon props must use the ph- prefix. Phosphor Icons are the only supported icon set.

// Correct
icon="ph-house"
icon="ph-plus"
icon="ph-bold ph-spinner"

// Wrong — triggers a dev warning and may not render
icon="house"
icon="plus"

Vue Component Catalog

What NOT to do

• Do not copy raw modal markup from demo partials into Vue apps.
• Do not call GNexusUIKit.Modals.create() from Vue components.
• Do not call GNexusUIKit.Overlays.init() or GNexusUIKit.NavigationShell.init() in Vue projects.
• Do not run Accordion.init() or Tabs.init() inside Vue components.
• Do not use the legacy advancedSelect() helper in Vue; use GnCombobox.
• Do not use InputPatterns.init() for Vue file upload previews; use GnFileUpload.
• Do not invent new variant names.
• Do not duplicate GNexus CSS in scoped <style> blocks.
• Do not write class="btn btn-primary" when GnButton exists.
• Do not pass icon names without the ph- prefix.

See docs/vue.md and docs/vue/ai-usage-guide.md for full details.

JS API

Bundle публикует компоненты и helper-модули двумя способами:

Toasts.createSuccess("Success", "Saved").show();
GNexusUIKit.Toasts.createInfo("Info", "Message").show();

Текущий публичный namespace:

GNexusUIKit.Helper
GNexusUIKit.Toasts
GNexusUIKit.Modals
GNexusUIKit.advancedSelect
GNexusUIKit.editableString
GNexusUIKit.confirmPopup
GNexusUIKit.Drawer
GNexusUIKit.NavigationShell
GNexusUIKit.Overlays
GNexusUIKit.InputPatterns
GNexusUIKit.Accordion

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

Компоненты

Сейчас в demo/docs представлены:

• Typography
• Palette
• Buttons
• Forms
• Utilities
• Editable String
• Navigation & Overlays
• Navigation Shell
• Lists
• Badges
• Alerts
• Tables
• Data Patterns
• Page Header
• Key-Value / Description List
• Progress
• Steps
• Chips
• Avatar / Identity
• Timeline / Activity Log
• Accordion / Disclosure
• Drawer / Side Panel
• Toasts
• Cards
• Modals
• Confirm Dialog

Каждая секция demo содержит визуальный пример, короткое описание и копируемый блок кода.

Navigation & Overlays

Секция включает:

• Tabs
• Dropdown
• Tooltip
• Popover

JS-модуль: src/js/components/overlays.js.

Navigation Shell

Секция включает:

• Topbar: sticky верхняя панель с menu toggle, brand и текущим разделом.
• Nav Drawer: left drawer для длинной навигации.
• Footer: версия продукта и copyright.
• Responsive behavior: drawer работает на desktop, tablet и mobile.

JS-модуль: src/js/components/navigation-shell.js обрабатывает data-navigation-toggle, data-navigation-drawer, data-navigation-close и data-navigation-link.

Utilities

Секция включает:

• Spacing scale: $space-0 ... $space-12.
• Margin utilities: m-*, mt-*, mr-*, mb-*, ml-*, mx-*, my-*.
• Padding utilities: p-*, pt-*, pr-*, pb-*, pl-*, px-*, py-*.
• Gap utilities: g-*, gx-*, gy-*.
• Layout/display/text helpers: grid-*, row, column, items-*, justify-*, d-*, text-*.

Data Patterns

Секция включает:

• Toolbar
• Search Field
• Input Group
• Pagination
• Empty State
• Skeleton

JS-модуль: src/js/components/input-patterns.js добавляет поведение для data-input-clear.

Page Header и Key-Value

Секции включают:

• Page Header: заголовок экрана, subtitle, status/meta и actions.
• Compact Page Header: плотный вариант для внутренних экранов и настроек.
• Description List: read-only пары key-value для деталей сущности.
• Compact Description List: плотный вариант для metadata blocks.

Progress и Steps

Секции включают:

• Progress Bar: determinate progress с CSS custom property --progress-value.
• Usage Meter: карточка лимита/использования с progress bar.
• Staged Progress: сегментированное состояние операции.
• Steps: горизонтальный и вертикальный wizard-flow.

Chips и Avatar

Секции включают:

• Chips: static, selectable, removable и state variants.
• Avatar: initials, icon, image, sizes и status marker.
• Identity: avatar + title/meta row.
• Avatar Stack: компактное отображение группы.

Timeline и Accordion

Секции включают:

• Timeline: вертикальная история событий со state variants.
• Activity Log: компактный audit/job log.
• Accordion: группы на native <details> / <summary>.
• Disclosure: компактная одиночная раскрываемая группа.

JS-модуль: src/js/components/accordion.js добавляет управляемую анимацию раскрытия.

Drawer и Confirm Dialog

Секции включают:

• Drawer: боковая overlay-панель для деталей, quick edit и secondary flows.
• Side Panel variants: правая и левая позиция через position: "left".
• Confirm Dialog: документация для существующего confirmPopup.

JS-модули: src/js/components/drawer.js и src/js/components/confirm-popup.js.

SCSS

Базовые файлы:

src/scss/_palette-colors.scss
src/scss/_design-tokens.scss
src/scss/_spacing.scss
src/scss/_mixins.scss
src/scss/_utils.scss

Компоненты находятся в:

src/scss/components/

Основная идея стиля сохраняется от исходного UI: моноширинная типографика, Tokyo Night influenced dark surface, sharp edges, толстые акцентные бордеры, цветовая инверсия на hover/focus и яркие status colors.

Assets

Локально подключены:

• IBM Plex Mono
• Phosphor Icons
• highlight.js для подсветки кода в demo/docs

dist/ генерируется из public/assets, src и demo.

Текущие замечания

• Сборка работает на Gulp 5, modern Dart Sass API, PostCSS/autoprefixer, clean-css, esbuild и gulp-file-include.
• Sass переведен на @use / @forward; deprecated map-* global functions заменены на sass:map.
• npm audit --audit-level=low проходит без найденных уязвимостей.
• webclient/ оставлен как источник старого клиента и игнорируется git.
• .codex является локальным служебным файлом и не должен попадать в коммиты.

Запланировано

Ближайшие полезные компоненты:

• На текущий момент список запланированных компонентов закрыт; дальше можно расширять набор по новым сценариям.

Технические задачи:

• На текущий момент технический backlog пуст; дальше расширяем компонентный набор.