diff --git a/README.md b/README.md index dbe44d3..c7d9c86 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,10 @@ Проект выделен из старого `webclient`, но развивается как отдельный набор UI-компонентов с demo/docs страницей. +## Документация + +Человеческая документация по подключению, стилю, JS API и компонентам находится в [`docs/`](docs/index.md). + ## Быстрый старт ```bash diff --git a/docs/component-coverage.md b/docs/component-coverage.md new file mode 100644 index 0000000..15c7e73 --- /dev/null +++ b/docs/component-coverage.md @@ -0,0 +1,34 @@ +# Component Coverage + +Эта страница показывает, где описана каждая секция из demo/docs. + +| Demo section | Documentation | +| --- | --- | +| Typography | [Foundations](components/foundations.md) | +| Palette | [Foundations](components/foundations.md) | +| Buttons | [Foundations](components/foundations.md) | +| Forms | [Forms](components/forms.md) | +| Utilities | [Foundations](components/foundations.md) | +| Editable String | [Forms](components/forms.md) | +| Navigation & Overlays | [Navigation](components/navigation.md) | +| Navigation Shell | [Navigation](components/navigation.md) | +| Lists | [Data Display](components/data-display.md) | +| Badges | [Data Display](components/data-display.md) | +| Alerts | [Feedback](components/feedback.md) | +| Tables | [Data Display](components/data-display.md) | +| Data Patterns | [Layout Patterns](components/layout-patterns.md) | +| Page Header | [Layout Patterns](components/layout-patterns.md) | +| Key-Value / Description List | [Data Display](components/data-display.md) | +| Progress | [Feedback](components/feedback.md) | +| Steps | [Layout Patterns](components/layout-patterns.md) | +| Chips | [Data Display](components/data-display.md) | +| Avatar / Identity | [Data Display](components/data-display.md) | +| Timeline / Activity Log | [Data Display](components/data-display.md) | +| Accordion / Disclosure | [Layout Patterns](components/layout-patterns.md) | +| Drawer / Side Panel | [Navigation](components/navigation.md) | +| Toasts | [Feedback](components/feedback.md) | +| Cards | [Data Display](components/data-display.md) | +| Modals | [Feedback](components/feedback.md) | +| Confirm Dialog | [Feedback](components/feedback.md) | + +Если в demo появляется новая секция, добавьте ее сюда и в соответствующий документ. diff --git a/docs/components/data-display.md b/docs/components/data-display.md new file mode 100644 index 0000000..3d33f69 --- /dev/null +++ b/docs/components/data-display.md @@ -0,0 +1,128 @@ +# Data Display + +## Tables + +Используйте tables для плотных списков сущностей и сравнений. + +```html + + + + + + + + + + + + + + + +
NameStatusUpdated
API GatewayOnline14:30
+``` + +## Lists + +Navigation lists используют `.list-nav`, обычные списки - `.list`. + +```html + +``` + +## Description List + +Description List подходит для read-only деталей сущности. + +```html +
+
+
Owner
+
Platform Team
+
+
+
Status
+
Active
+
+
+``` + +## Cards + +Cards используются для самостоятельных блоков: summary, action, metric, status. + +```html +
+

Card title

+
+

Card content.

+
+
+``` + +Для числовых показателей: + +```html +
+
+
+

Requests

+ +
+

24.8k

+
+ +12% + from yesterday +
+
+
+``` + +## Badges и Chips + +Badges показывают состояние, chips - компактные значения или фильтры. + +```html +Online +Review +Error +``` + +```html +API + +``` + +## Avatar и Identity + +```html +
+ AG +
+ Ada Grace + Platform +
+
+``` + +## Timeline + +Timeline подходит для audit log, activity feed и истории событий. + +```html +
    +
  1. +
    +

    Build completed

    +

    Pipeline finished successfully.

    +
    +
    2. +
+``` diff --git a/docs/components/feedback.md b/docs/components/feedback.md new file mode 100644 index 0000000..e51dbc6 --- /dev/null +++ b/docs/components/feedback.md @@ -0,0 +1,99 @@ +# Feedback Components + +## Alerts + +Alerts показывают inline-состояния и важные сообщения внутри страницы. + +```html +
+

Needs review

+

Check configuration before publishing.

+
+``` + +Состояния: + +- `.alert-success` +- `.alert-warning` +- `.alert-info` +- `.alert-danger` +- `.alert-error` + +## Toasts + +Toasts создаются через JS. + +```js +GNexusUIKit.Toasts.createSuccess("Saved", "Changes applied").show(); +GNexusUIKit.Toasts.createInfo("Queued", "Job started").show(); +GNexusUIKit.Toasts.createWarning("Review", "Check before publishing").show(); +GNexusUIKit.Toasts.createError("Failed", "Request failed").show(); +``` + +`createSuccess` по умолчанию закрывает другие toast-ы и исчезает через `4000ms`. + +## Modals + +```js +const modal = GNexusUIKit.Modals.create("example-modal", { + title: "Edit item", + bodyText: "Modal content" +}); + +modal.show(); +``` + +Используйте modal для blocking flow, подтверждения ввода или короткого edit-flow. + +## Confirm Dialog + +`confirmPopup` предназначен для подтверждения рискованного действия. + +```js +GNexusUIKit.confirmPopup({ + title: "Delete item", + text: "This action cannot be undone.", + confirmText: "Delete", + cancelText: "Cancel", + onConfirm: () => { + // delete item + } +}); +``` + +## Progress + +Determinate progress: + +```html +
+
+
+``` + +Usage meter: + +```html +
+
+ Storage + 64% +
+
+
+
+
+``` + +## Skeleton + +Skeleton используется для loading preview. + +```html +
+ + + + +
+``` diff --git a/docs/components/forms.md b/docs/components/forms.md new file mode 100644 index 0000000..156560e --- /dev/null +++ b/docs/components/forms.md @@ -0,0 +1,177 @@ +# Forms + +## Basic Input + +Формы строятся из `.form-group`, `.label` и `.input`. + +```html +
+ +
+``` + +Состояния задаются на `.label`: + +```html + +
+ + Field cannot be empty +
+``` + +Доступные состояния: + +- `.error` +- `.success` +- `.warning` + +## Icons + +Иконка ставится перед input внутри label. + +```html + +``` + +## Select + +```html + +``` + +## Date & Time + +Date/time поля остаются нативными, но всё поле кликабельно через `data-date-picker`. + +```html + + + + + +``` + +`InputPatterns.init()` добавляет progressive enhancement через `showPicker()`. + +## File Upload + +Универсальный upload поддерживает накопительный выбор файлов, preview для изображений, file type cards для остальных файлов и удаление item-ов. + +```html +
+
+
+
+

Upload files

+

Attach documents, archives or images.

+
+ Max 12 MB +
+ + + + +
+
+``` + +Behavior: + +```js +GNexusUIKit.InputPatterns.init(); +``` + +## Checkbox и Radio + +```html + + + +``` + +## Advanced Select + +`advancedSelect` создается через JS и привязывается к input. + +```js +document.querySelector(".advanced-select-container").append( + GNexusUIKit.advancedSelect( + document.querySelector(".advanced-select-input"), + { + user_1: "Ada", + user_2: "Grace" + }, + "Nothing found" + ) +); +``` + +## Editable String + +Editable String подходит для inline-редактирования коротких значений: названия, slug, label, metadata. + +```html +
+ Release Plan + +
+``` + +Поведение находится в `src/js/components/editable-string.js` и доступно как: + +```js +GNexusUIKit.editableString +``` + +Используйте этот паттерн только для короткого inline-edit. Для длинного текста или сложной формы лучше открыть modal/drawer. diff --git a/docs/components/foundations.md b/docs/components/foundations.md new file mode 100644 index 0000000..1ec7336 --- /dev/null +++ b/docs/components/foundations.md @@ -0,0 +1,95 @@ +# Foundations + +## Typography + +Typography задает базовый язык интерфейса: mono font, плотные заголовки, readable body text. + +```html +

Heading 1

+

Heading 2

+

Body text for interface copy.

+Meta text +``` + +Практика: + +- Используйте крупные заголовки только для настоящего начала экрана. +- Внутри cards, drawer, toolbar и compact panels используйте небольшие заголовки. +- Для technical labels и meta используйте uppercase только там, где это помогает scanning. + +## Palette + +Palette демонстрирует доступные цвета и state colors. + +Основные роли: + +- `primary` - системный accent. +- `secondary` - action/navigation accent. +- `success` - успешное состояние. +- `warning` - требует внимания. +- `error/danger` - ошибка или рискованное действие. +- `info` - нейтральная информационная подсветка. + +Не используйте state colors как декоративную палитру. Они должны означать состояние. + +## Buttons + +Базовая кнопка: + +```html + + + +``` + +Кнопка с иконкой: + +```html + +``` + +Icon-only: + +```html + +``` + +Правила: + +- Primary/accent используйте для главного действия в группе. +- Danger/error используйте только для destructive actions. +- Icon-only кнопкам всегда нужен `aria-label`. + +## Utilities + +Utilities закрывают частые layout-задачи без локального CSS. + +Spacing: + +```html +
Content
+
Content
+``` + +Layout: + +```html +
+ Label + +
+``` + +Text: + +```html +

Secondary text

+

Centered text

+``` + +Используйте utilities для небольших компоновочных задач. Если паттерн повторяется как компонент, лучше вынести SCSS. diff --git a/docs/components/layout-patterns.md b/docs/components/layout-patterns.md new file mode 100644 index 0000000..24621ad --- /dev/null +++ b/docs/components/layout-patterns.md @@ -0,0 +1,124 @@ +# Layout Patterns + +## Page Header + +Page Header задаёт начало экрана: title, subtitle, status/meta, actions. + +```html +
+
+

Deployments

+

Release operations and runtime status

+
+
+ + +
+
+``` + +## Toolbar + +Toolbar собирает title/meta, search, filters и primary action. + +```html +
+
+
+

Projects

+ 24 items +
+
+
+
+ + + +
+ +
+
+``` + +## Input Group + +```html +
+ https:// + + +
+``` + +## Pagination + +```html + +``` + +## Empty State + +```html +
+
+ +
+

No results

+

Nothing matched the current filters.

+
+ + +
+
+``` + +## Steps + +Steps показывают wizard-flow или staged process. + +```html +
    +
  1. + 1 + Created +
    2. +
  2. + 2 + Review +
    3. +
  3. + 3 + Publish +
    4. +
+``` + +## Accordion + +Accordion основан на native `
` / `` и получает enhanced animation через JS. + +```html +
+
+ Details +
+ Content +
+
+
+``` + +```js +GNexusUIKit.Accordion.init(); +``` diff --git a/docs/components/navigation.md b/docs/components/navigation.md new file mode 100644 index 0000000..a8550f1 --- /dev/null +++ b/docs/components/navigation.md @@ -0,0 +1,127 @@ +# Navigation Components + +## Navigation Shell + +Navigation Shell - основной паттерн для приложений с длинной навигацией: sticky topbar, кнопка меню, left drawer, footer. + +Используйте его для: + +- dashboards; +- docs; +- admin panels; +- workspace-интерфейсов; +- mobile/tablet shell. + +```html +
+ +
+ + Product Console +
+
Overview
+
+ +
+ +``` + +Behavior: + +```js +GNexusUIKit.NavigationShell.init(); +``` + +`NavigationShell.init()` запускается автоматически, если подключен bundle. + +## List Navigation + +Используйте `.list.list-nav` внутри drawer или sidebar-like панелей. + +```html + +``` + +Active state задается классом `.list-item-active`. + +## Tabs + +Tabs подходят для близких представлений внутри одного контекста. + +```html +
+ + + +
+``` + +## Dropdown, Tooltip, Popover + +Эти паттерны живут в `Navigation & Overlays`. + +```html +
+ + +
+``` + +```js +GNexusUIKit.Overlays.init(); +``` + +## Drawer + +`Drawer` - programmatic side panel для secondary flows. Navigation Shell использует похожий визуальный паттерн, но его markup статический. + +```js +const drawer = GNexusUIKit.Drawer.create("details", { + title: "Details", + bodyText: "Content", + position: "left" +}); + +drawer.show(); +``` diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..ebea414 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,79 @@ +# Getting Started + +## Установка и сборка + +```bash +npm install +npm run dev +``` + +Production build: + +```bash +npm run build +``` + +Сборка кладет результат в `dist/`: + +- `dist/css/kit.css` +- `dist/css/demo.css` +- `dist/js/gnexus-ui-kit.js` +- `dist/index.html` +- `dist/assets/*` + +## Подключение в HTML + +Минимально нужны иконки, CSS kit и JS bundle: + +```html + + + +``` + +Если странице не нужны интерактивные компоненты, JS можно не подключать. Но для drawer, modals, toasts, overlays, accordion, date picker helpers и file upload previews нужен `gnexus-ui-kit.js`. + +## Базовая страница + +```html + + + + + + + + + +
+
+

Projects

+

Internal workspace

+
+
+ +
+
+ + + + +``` + +## Assets + +Kit ожидает локальные assets из `dist/assets`: + +- IBM Plex Mono fonts +- Phosphor icon font +- highlight.js для demo/docs +- `gnexus-mark.svg` + +В приложении можно использовать свои пути, но классы с `.ph` предполагают, что Phosphor Icons подключены. + +## Версия + +Текущая версия пакета: `0.2.0`. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..801f659 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,42 @@ +# GNexus UI Kit Docs + +GNexus UI Kit - набор HTML/CSS/JS компонентов для внутренних интерфейсов GNexus. +Документация в этой директории описывает, как подключать kit и как собирать из него реальные экраны. + +## С чего начать + +- [Getting Started](getting-started.md) - подключение CSS, иконок и JS bundle. +- [Style Guide](style-guide.md) - визуальные правила, токены, spacing и типографика. +- [JavaScript API](javascript.md) - глобальный namespace и автоинициализация. + +## Компоненты + +- [Foundations](components/foundations.md) - typography, palette, buttons, utilities. +- [Navigation](components/navigation.md) - Navigation Shell, tabs, dropdown, tooltip, popover, drawer. +- [Forms](components/forms.md) - input, select, date/time, file upload, checkbox/radio, advanced select. +- [Data Display](components/data-display.md) - tables, lists, cards, description list, timeline, avatar, badges, chips. +- [Feedback](components/feedback.md) - alerts, toasts, modals, confirm dialog, progress, skeleton. +- [Layout Patterns](components/layout-patterns.md) - page header, toolbar, pagination, empty state, steps, accordion. +- [Component Coverage](component-coverage.md) - соответствие demo-секций страницам документации. + +## Где смотреть живые примеры + +Локальная demo/docs страница собирается из `demo/index.html` и `demo/partials/*.html`. + +```bash +npm install +npm run dev +``` + +После запуска: + +```text +http://localhost:3000 +``` + +## Что считать источником правды + +- Для поведения компонентов: `src/js/components/`. +- Для CSS API: `src/scss/components/`. +- Для копируемой разметки: `demo/partials/`. +- Для человеческих правил использования: `docs/`. diff --git a/docs/javascript.md b/docs/javascript.md new file mode 100644 index 0000000..236493c --- /dev/null +++ b/docs/javascript.md @@ -0,0 +1,88 @@ +# JavaScript API + +`dist/js/gnexus-ui-kit.js` публикует API двумя способами: + +```js +Toasts.createSuccess("Saved", "Changes applied").show(); +GNexusUIKit.Toasts.createInfo("Info", "Message").show(); +``` + +## Namespace + +```text +GNexusUIKit.Helper +GNexusUIKit.Toasts +GNexusUIKit.Modals +GNexusUIKit.advancedSelect +GNexusUIKit.editableString +GNexusUIKit.confirmPopup +GNexusUIKit.Drawer +GNexusUIKit.NavigationShell +GNexusUIKit.Overlays +GNexusUIKit.InputPatterns +GNexusUIKit.Accordion +``` + +## Auto init + +На `DOMContentLoaded` автоматически запускаются: + +```js +Overlays.init(); +NavigationShell.init(); +InputPatterns.init(); +Accordion.init(); +``` + +Если вы динамически вставляете HTML после загрузки страницы, можно повторно вызвать init для root-элемента: + +```js +GNexusUIKit.NavigationShell.init(document.querySelector("#dynamic-root")); +GNexusUIKit.InputPatterns.init(document.querySelector("#dynamic-root")); +GNexusUIKit.Accordion.init(document.querySelector("#dynamic-root")); +``` + +Модули защищены от повторной инициализации одного и того же root. + +## Data attributes + +Компоненты используют declarative attributes: + +- `data-navigation-toggle` +- `data-navigation-drawer` +- `data-navigation-close` +- `data-navigation-link` +- `data-dropdown-toggle` +- `data-popover-toggle` +- `data-tooltip-toggle` +- `data-input-clear` +- `data-file-upload-input` +- `data-file-upload-preview` +- `data-date-picker` + +## Programmatic components + +Некоторые компоненты создаются через JS: + +```js +const drawer = GNexusUIKit.Drawer.create("details-drawer", { + title: "Details", + bodyText: "Drawer content", + position: "left" +}); + +drawer.show(); +``` + +```js +const modal = GNexusUIKit.Modals.create("edit-modal", { + title: "Edit", + bodyText: "Modal content" +}); + +modal.show(); +``` + +```js +GNexusUIKit.Toasts.createSuccess("Saved", "Changes applied").show(); +``` diff --git a/docs/style-guide.md b/docs/style-guide.md new file mode 100644 index 0000000..ccc7e7e --- /dev/null +++ b/docs/style-guide.md @@ -0,0 +1,86 @@ +# Style Guide + +## Характер интерфейса + +GNexus UI Kit использует темный terminal/cyber стиль: + +- IBM Plex Mono как базовый шрифт. +- Прямые формы без скруглений. +- Толстые accent borders. +- Яркие state colors для success, warning, error, info. +- Контрастные hover/focus состояния. + +Интерфейс рассчитан на рабочие панели, админки, dev tools, monitoring и внутренние инструменты. + +## Цвета + +Основные цвета лежат в `src/scss/_palette-colors.scss`, производные design tokens - в `src/scss/_design-tokens.scss`. + +Чаще всего в компонентах используются: + +- `$surface-page` - фон страницы. +- `$surface-panel` - базовая поверхность панели. +- `$surface-panel-muted` - приглушенная поверхность карточек и блоков. +- `$color-text-light` - основной текст. +- `$color-text-medium` - вторичный текст. +- `$color-primary` - основной accent. +- `$color-secondary` - cyan/action accent. +- `$color-success`, `$color-warning`, `$color-error`, `$color-info` - состояния. + +## Spacing + +Spacing scale определен в `src/scss/_spacing.scss`. + +Используйте `$space-1` ... `$space-12` вместо случайных пикселей. Для layout helpers доступны utility-классы: + +- `m-*`, `mt-*`, `mr-*`, `mb-*`, `ml-*`, `mx-*`, `my-*` +- `p-*`, `pt-*`, `pr-*`, `pb-*`, `pl-*`, `px-*`, `py-*` +- `g-*`, `gx-*`, `gy-*` + +## Типографика + +Базовая типографика находится в `src/scss/components/_typography.scss`. + +Практика: + +- Заголовки секций - uppercase и плотный line-height. +- Внутри compact UI используйте небольшие заголовки, не hero-size. +- Для meta/status текста используйте `$font-size-xs` или `$font-size-sm`. + +## Focus + +Интерактивные элементы должны иметь видимый focus. В SCSS используйте mixin: + +```scss +&:focus-visible { + @include focus_ring; +} +``` + +## Motion + +Переходы короткие и функциональные: + +- `$motion-fast` +- `$motion-base` +- `$motion-slow` +- `$motion-ease` + +Не добавляйте декоративные анимации, которые отвлекают от работы. Hover должен помогать понять affordance, а не привлекать внимание сам по себе. + +## Иконки + +Используйте Phosphor Icons: + +```html + +``` + +Кнопки команд лучше делать `with-icon`, если действие становится понятнее с иконкой: + +```html + +```