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.

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

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();

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

Need	Component	Props you will use
Button	`GnButton`	`variant`, `size`, `icon`, `loading`, `disabled`
Icon-only button	`GnIconButton`	`icon`, `label`
Copy button	`GnCopyButton`	`text`, `icon`, `successIcon`, `duration`, `label`
Status label	`GnBadge`	`variant`, `outline`
Message block	`GnAlert`	`variant`
Card / panel	`GnCard`	`title` (slot), `footer` (slot)
Horizontal card	`GnHorizontalCard`	`image`, `title`, `titleHref`, `icon`, `footer` (slot)
Page title bar	`GnPageHeader`	`kicker`, `title`, `subtitle`, `meta`, `actions` (slot)
Text field	`GnInput`	`v-model`, `label`, `icon`, `state`, `help`
Textarea	`GnTextarea`	`v-model`, `label`, `state`, `help`
Select dropdown	`GnSelect`	`v-model`, `label`, `options`
Checkbox	`GnCheckbox`	`v-model`, `label`, `disabled`
Toggle switch	`GnSwitch`	`v-model`, `label`, `disabled`
Radio	`GnRadio` / `GnRadioGroup`	`v-model`, `options`
Range slider	`GnRange`	`v-model`, `label`, `min`, `max`
File upload	`GnFileUpload`	`v-model`, `badge`, `multiple`, `accept`
Searchable select	`GnCombobox`	`v-model`, `label`, `options`, `placeholder`
Tabs	`GnTabs`	`v-model`, `items`
Router tabs	`GnRouterTabs`	`items` (with `to`), `activeMatch`
Accordion	`GnAccordion`	`items`, `v-model`, `multiple`
Modal dialog	`GnModal`	`v-model:open`, `title`, `closeOnBackdrop`
Side drawer	`GnDrawer`	`v-model:open`, `title`, `position`
Toasts	`GnToastProvider` + `useToast`	Wrap app once; call `toast.success({ title, text })`
Confirm dialog	`GnConfirmDialog`	`v-model:open`, `title`, `message`, `confirmVariant`
Table	`GnTable`	`columns`, `rows`, `caption`, `emptyText`
Toolbar	`GnToolbar`	`title`, `meta`, `actions` (slot)
Input group	`GnInputGroup`	`addon` (slot), `action` (slot)
Search field	`GnSearchField`	`v-model`
Pagination	`GnPagination`	`page`, `total-pages`
Empty state	`GnEmptyState`	`title`, `text`, `icon`, `actions` (slot)
Skeleton loader	`GnSkeleton`	—
Key-value list	`GnDescriptionList`	`items`
Progress bar	`GnProgress`	`value`, `label`, `animated`
Usage meter card	`GnUsageMeter`	`value`, `label`, `max`
Staged progress	`GnProgressStages`	`items`
Wizard steps	`GnSteps`	`items`, `current`
Chip / tag	`GnChip`	`variant`, `selected`, `removable`
Chip group	`GnChipGroup`	—
Avatar	`GnAvatar`	`initials`, `icon`, `image`, `size`, `status`
Identity row	`GnIdentity`	`title`, `meta`, `avatar` props
Avatar stack	`GnAvatarStack`	`items`
Timeline	`GnTimeline`	`items`
Activity log	`GnActivityLog`	`items`
Basic list	`GnList`	`items`
Definition list	`GnDefinitionList`	`items`
Action list	`GnActionList`	`items`
Loader / spinner	`GnLoader`	—
Status card	`GnStatusCard`	`variant`, `title`, `meta`
Metric card	`GnMetricCard`	`title`, `value`, `trend`
Action card	`GnActionCard`	`title`, `text`, `actions` (slot)
Dropdown menu	`GnDropdown`	`items`, `label`, `variant`
Popover panel	`GnPopover`	`title`, `text`, `label`
Tooltip	`GnTooltip`	`text`
Navigation list	`GnNavList`	`items`
App shell	`GnNavigationShell`	`brand`, `items`, `current`, `footerLeft`, `footerRight`

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 содержит визуальный пример, короткое описание и копируемый блок кода.

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

Tabs
Dropdown
Tooltip
Popover

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

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

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 пуст; дальше расширяем компонентный набор.

GNexus UI Kit

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

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

Структура

Команды

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

Vue Adapter (Primary Contract)

Icon Naming

Vue Component Catalog

What NOT to do

JS API

Компоненты

Navigation & Overlays

Navigation Shell

Utilities

Data Patterns

Page Header и Key-Value

Progress и Steps

Chips и Avatar

Timeline и Accordion

Drawer и Confirm Dialog

SCSS

Assets

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

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