OKAUX

Модульный UX/UI-фреймворк от VEGAS Studio. OKAUX объединяет дизайн-токены, темы, адаптивную раскладку, стили интерфейса и JavaScript-компоненты с единым публичным API.

Фреймворк можно использовать как готовый CSS-набор или подключить исходный SCSS, чтобы настроить токены и префикс CSS-переменных. Интерактивные компоненты регистрируются выборочно и поддерживают декларативную инициализацию через HTML-атрибуты.

Возможности

• дизайн-токены для цветов, типографики, отступов, размеров, радиусов, теней, анимации и z-слоёв;
• светлая, тёмная, высококонтрастная и системная цветовые схемы;
• адаптивные контейнеры, grid/flex-сетки, stack-компоновка и utility-классы;
• формы, навигация, отображение данных, feedback- и overlay-компоненты;
• управление темой, анимацией, позиционированием и блокировкой прокрутки;
• декларативный запуск компонентов через data-ox-ui;
• ES-модули, готовый CSS и настраиваемый SCSS API.

Требования

• Node.js 20.19+ или 22.12+;
• сборщик с поддержкой ES-модулей;
• Sass — только для работы с исходным SCSS.

Установка

npm install okaux

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

Подключите стили, зарегистрируйте используемые компоненты и запустите OKAUX:

import okaux, {
  Collapse,
  Dropdown,
  Modal,
  Tabs,
  Toast,
  Tooltip,
} from 'okaux';
import 'okaux/style.css';

[
  Collapse,
  Dropdown,
  Modal,
  Tabs,
  Toast,
  Tooltip,
].forEach((Component) => {
  okaux.use(Component.NAME, Component);
});

okaux.boot();

boot() дожидается готовности DOM, применяет сохранённую тему и создаёт экземпляры зарегистрированных модулей для элементов с атрибутом data-ox-ui:

<section class="ox-tabs" data-ox-ui="tabs">
  <!-- Разметка компонента -->
</section>

Повторный вызов boot() не создаёт дубликаты уже существующих экземпляров. Для динамически добавленной части страницы можно передать корневой элемент:

okaux.boot(document.querySelector('#dynamic-content'));

Для освобождения обработчиков и экземпляров используйте тот же scope или весь документ:

okaux.destroy(document.querySelector('#dynamic-content'));
okaux.destroy();

Компоненты

Стили интерфейса

В готовую сборку входят:

• базовые элементы: кнопки, badges, tags, chips, аватары и состояния;
• формы: поля ввода, textarea, select, checkbox, radio и switch;
• данные: карточки, списки описаний, таблицы, Data Grid, KPI, статистика и timeline;
• навигация: breadcrumbs, tabs, pagination, stepper, sidebar и top bar;
• обратная связь: feedback, toast, tooltip, skeleton, progress и состояния загрузки;
• раскрывающиеся элементы: collapse, dropdown, context menu и command menu;
• overlay-интерфейсы: modal, drawer, coachmark и guided tour.

JavaScript-модули

| Модуль | Имя в data-ox-ui | Назначение | | --- | --- | --- | | Collapse | collapse | раскрывающиеся области | | Coachmark | coachmark | контекстные подсказки по шагам | | CommandMenu | command-menu | меню команд | | ContextMenu | context-menu | контекстное меню | | DataGrid | data-grid | сортировка, фильтрация, группы и редактирование данных | | Dropdown | dropdown | выпадающие панели | | Drawer | drawer | боковые overlay-панели | | Feedback | feedback | интерактивные сообщения обратной связи | | GuidedTour | guided-tour | пошаговые туры по интерфейсу | | Modal | modal | модальные окна | | ShiftDragScroll | shift-drag-scroll | горизонтальная прокрутка перетаскиванием с Shift | | Sidebar | sidebar | интерактивная боковая навигация | | Table | table | поведение таблиц и горизонтальная прокрутка | | Tabs | tabs | вкладки | | Toast | toast | всплывающие уведомления | | Tooltip | tooltip | подсказки и popover-панели |

Компоненты не регистрируются автоматически: приложение подключает только необходимые модули.

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

Параметры компонента задаются атрибутами data-ox-*. Имена в kebab-case преобразуются в camelCase, а значения true, false, null, числа, массивы и объекты нормализуются автоматически.

<div
  data-ox-ui="tooltip"
  data-ox-placement="top"
  data-ox-delay-show="150"
  title="Подсказка"
></div>

Значения по умолчанию для всех экземпляров модуля можно передать при создании приложения:

import { createOKAUX, Tooltip } from 'okaux';

const app = createOKAUX({
  debug: false,
  moduleDefaults: {
    placement: 'bottom',
  },
});

app.use(Tooltip.NAME, Tooltip).boot();

Стили и настройка

Готовый CSS

Подключение из JavaScript:

import 'okaux/style.css';

Или из CSS:

@import 'okaux/style.css';

Исходный SCSS

Sass-точка входа экспортирует настройки и токены и одновременно создаёт стили фреймворка:

@use 'okaux/scss' as okaux;

Префикс CSS-переменных по умолчанию — ox. Его можно изменить при подключении:

@use 'okaux/scss' with (
  $css-variable-prefix: 'vg'
);

JavaScript должен использовать тот же префикс:

import { createOKAUX, Modal } from 'okaux';

const app = createOKAUX({
  cssVariablePrefix: 'vg',
});

app.use(Modal.NAME, Modal).boot();

Префикс влияет только на CSS-переменные. Атрибуты data-ox-* остаются неизменной частью публичного контракта.

Темы

После boot() система тем восстанавливает выбор из localStorage, выставляет атрибут data-theme на <html> и отслеживает системную тёмную тему в режиме system.

okaux.theme.set('dark');
okaux.theme.set('high-contrast');
okaux.theme.set('system');
okaux.theme.toggle();

Тему также можно переключать декларативно:

<button type="button" data-ox-theme-value="light">Светлая</button>
<button type="button" data-ox-theme-value="dark">Тёмная</button>
<button type="button" data-ox-theme-value="system">Системная</button>
<button type="button" data-ox-theme-toggle>Переключить тему</button>

Публичный JavaScript API

Пакет экспортирует:

• готовый экземпляр okaux, фабрику createOKAUX() и систему theme;
• все JavaScript-компоненты из таблицы выше;
• motion API: animateIn(), animateOut(), createMotionSystem(), пресеты и скорости;
• позиционирование: place();
• блокировку прокрутки для собственных overlay-компонентов;
• DOM-селекторы и функции событий;
• создание SVG-иконок и безопасную обработку HTML;
• контроллер горизонтальной Shift-прокрутки.

Отдельный экземпляр можно настроить собственными системами:

import { createOKAUX } from 'okaux';

const app = createOKAUX({
  cssVariablePrefix: 'ox',
  debug: false,
  moduleDefaults: {},
  theme: {},
  motion: {},
  placement: {},
});

Локальная разработка

Установите зависимости:

npm install

Запустите production-сборку:

npm run build

Для пересборки при изменениях:

npm run dev

Vite создаёт ES-модуль, карту исходного кода и готовые стили:

dist/okaux.js
dist/okaux.js.map
dist/okaux.css

Ссылки

• Репозиторий
• Журнал изменений
• Сообщить о проблеме

Лицензия

OKAUX распространяется по лицензии MIT. Фреймворк можно использовать, изменять и распространять с сохранением текста лицензии и уведомления об авторских правах.