vgapp 1.4.2 → 1.4.4

package/README.md

@@ -1,181 +1,270 @@
-# VEGAS APP (VGApp)
-[FUNC.TRUE?!](http://func-true.ru)
-
-VGApp — набор фронтенд‑модулей (UI‑компонентов и утилит) на чистом JavaScript от Vegas Studio.  
-Проект объединяет типовые элементы интерфейса и сценарии (модалки, табы, формы, загрузка файлов и т.д.) с едиными подходами к инициализации, data‑API, событиям и локализации.
-
-[![npm](https://img.shields.io/npm/v/vgapp.svg?style=flat-square&maxAge=600)](https://www.npmjs.com/package/vgapp) [![npm](https://img.shields.io/npm/l/vgapp.svg?style=flat-square)]()
-
-## Install
-```
-npm i vgapp
-```
-
-## API
-```js
-import vgapp from 'vgapp';
-
-vgapp.boot();
-```
-
-- `vgapp` экспортируется как singleton app.
-- `vgapp.register()` использует единый контракт: `register(name, Module)`.
-- `vgapp.boot()` вызывает общий boot-контракт модуля.
-- У модулей со своим `initAll()` boot использует его автоматически.
-
-Для выборочного набора модулей создавайте отдельный экземпляр:
-```js
-import { VGApp, VGModal, VGTooltip } from 'vgapp';
-
-const app = new VGApp();
-
-app
-	.register(VGModal.NAME, VGModal)
-	.register(VGTooltip.NAME, VGTooltip)
-	.boot();
-```
-
-## Подключение
-
-### Laravel + Vite
-`resources/js/app.js`
-```js
-import vgapp from 'vgapp';
-import 'vgapp/build/vgapp.css';
-
-vgapp.boot();
-```
-
-`vite.config.js`
-```js
-import { defineConfig } from 'vite';
-import laravel from 'laravel-vite-plugin';
-
-export default defineConfig({
-	plugins: [
-		laravel([
-			'resources/css/app.css',
-			'resources/js/app.js',
-		]),
-	],
-});
-```
-
-В Blade:
-```php
-@vite(['resources/css/app.css', 'resources/js/app.js'])
-```
-
-### Vite
-`src/main.js`
-```js
-import vgapp from 'vgapp';
-import 'vgapp/build/vgapp.css';
-
-vgapp.boot();
-```
-
-### Webpack
-`src/app.js`
-```js
-import vgapp from 'vgapp';
-import 'vgapp/build/vgapp.css';
-
-vgapp.boot();
-```
-
-Минимально в `webpack.config.js`:
-```js
-module.exports = {
-	entry: './src/app.js',
-	module: {
-		rules: [
-			{
-				test: /\.css$/i,
-				use: ['style-loader', 'css-loader'],
-			},
-		],
-	},
-};
-```
-
-### Частичный boot
-Если не нужно поднимать весь реестр singleton-приложения:
-```js
-import { VGApp, VGModal, VGTooltip } from 'vgapp';
-import 'vgapp/build/vgapp.css';
-
-const app = new VGApp();
-
-app
-	.register(VGModal.NAME, VGModal)
-	.register(VGTooltip.NAME, VGTooltip)
-	.boot();
-```
-
-## Что умеет
-
-### Общие возможности
-- Работает без jQuery, ориентирован на ES6+.
-- Поддерживает инициализацию через JS и `data-*` атрибуты.
-- События на DOM для интеграции и расширения поведения.
-- AJAX‑интеграция в ключевых модулях.
-- Локализация интерфейсных текстов.
-- Расширяемая архитектура модулей и рендереров.
-
-### Основные модули
-- `VGAlert` — диалоги подтверждения и уведомления с поддержкой AJAX‑сценариев.
-- `VGCollapse` — сворачиваемые секции и аккордеоны с анимацией.
-- `VGDropdown` — выпадающие меню с гибким открытием и позиционированием.
-- `VGDynamicTable` — интерактивные таблицы с сортировкой, фильтрацией, remote-режимом и состоянием.
-- `VGFiles` — загрузка и управление файлами (dropzone, валидация, AJAX, сортировка).
-- `VGFilePreview` — предпросмотр файлов разных типов и действия по файлу (preview/download).
-- `VGFormSender` — отправка форм (AJAX/нативно), обработка состояний и ответов.
-- `VGLawCookie` — баннер cookies с сохранением выбора пользователя.
-- `VGLoadMore` — подгрузка контента кнопкой или при прокрутке.
-- `VGModal` — базовый модуль модальных окон.
-- `VGNav` — навигация и мобильное меню.
-- `VGNestable` — drag‑and‑drop вложенных списков с обновлением структуры.
-- `VGRangeSlider` — одиночные и диапазонные слайдеры со значениями, лимитами и синхронизацией полей.
-- `VGRollup` — ограничение контента по высоте/элементам с кнопкой разворота.
-- `VGSelect` — кастомный select с поиском, мультивыбором и i18n.
-- `VGSidebar` — боковые панели с управлением открытием/закрытием.
-- `VGSpy` — scroll‑spy для подсветки активных ссылок по секциям.
-- `VGTabs` — вкладки с переключением контента и поддержкой URL/hash.
+# VEGAS APP (VGApp)
+[FUNC.TRUE?!](http://func-true.ru)
+
+VGApp — набор фронтенд‑модулей (UI‑компонентов и утилит) на чистом JavaScript от Vegas Studio.  
+Проект объединяет типовые элементы интерфейса и сценарии (модалки, табы, формы, загрузка файлов и т.д.) с едиными подходами к инициализации, data‑API, событиям и локализации.
+
+[![npm](https://img.shields.io/npm/v/vgapp.svg?style=flat-square&maxAge=600)](https://www.npmjs.com/package/vgapp) [![npm](https://img.shields.io/npm/l/vgapp.svg?style=flat-square)]()
+
+## Что умеет
+
+### Общие возможности
+- Работает без jQuery, ориентирован на ES6+.
+- Поддерживает инициализацию через JS и `data-*` атрибуты.
+- События на DOM для интеграции и расширения поведения.
+- AJAX‑интеграция в ключевых модулях.
+- Локализация интерфейсных текстов.
+- Расширяемая архитектура модулей и рендереров.
+
+### Основные модули
+- `VGAlert` — диалоги подтверждения и уведомления с поддержкой AJAX‑сценариев.
+- `VGCollapse` — сворачиваемые секции и аккордеоны с анимацией.
+- `VGDropdown` — выпадающие меню с гибким открытием и позиционированием.
+- `VGDynamicTable` — интерактивные таблицы с сортировкой, фильтрацией, remote-режимом и состоянием.
+- `VGFiles` — загрузка и управление файлами (dropzone, валидация, AJAX, сортировка).
+- `VGFilePreview` — предпросмотр файлов разных типов и действия по файлу (preview/download).
+- `VGFormSender` — отправка форм (AJAX/нативно), обработка состояний и ответов.
+- `VGLawCookie` — баннер cookies с сохранением выбора пользователя.
+- `VGLoadMore` — подгрузка контента кнопкой или при прокрутке.
+- `VGModal` — базовый модуль модальных окон.
+- `VGNav` — навигация и мобильное меню.
+- `VGNestable` — drag‑and‑drop вложенных списков с обновлением структуры.
+- `VGRangeSlider` — одиночные и диапазонные слайдеры со значениями, лимитами и синхронизацией полей.
+- `VGRollup` — ограничение контента по высоте/элементам с кнопкой разворота.
+- `VGSelect` — кастомный select с поиском, мультивыбором и i18n.
+- `VGSidebar` — боковые панели с управлением открытием/закрытием.
+- `VGSpy` — scroll‑spy для подсветки активных ссылок по секциям.
+- `VGTabs` — вкладки с переключением контента и поддержкой URL/hash.
 - `VGToast` — всплывающие уведомления со стеком и автозакрытием.
 - `VGTooltip` — tooltip/popover подсказки с Data API, автопозиционированием и закрытием по `Esc`/клику вне элемента.
 
-### VGSelect: автоматический поиск
+## Install
+```
+npm i vgapp
+```
+
+## API
+```js
+import vgapp from 'vgapp';
+
+vgapp.boot();
+```
 
-По умолчанию `autosearch: true`: поле поиска автоматически появляется, если в `<select>` больше 7 непустых видимых опций. Число вместо `true` задаёт собственный порог:
+- `vgapp` экспортируется как singleton app.
+- `vgapp.register()` использует единый контракт: `register(name, Module)`.
+- `vgapp.boot()` вызывает общий boot-контракт модуля.
+- У модулей со своим `initAll()` boot использует его автоматически.
 
+Для выборочного набора модулей создавайте отдельный экземпляр:
 ```js
-VGSelect.init(select, { autosearch: 10 }); // поиск появится при 11+ опциях
-VGSelect.init(select, { autosearch: 15 }); // поиск появится при 16+ опциях
-VGSelect.init(select, { autosearch: false }); // автоматический поиск отключён
+import { VGApp, VGModal, VGTooltip } from 'vgapp';
+
+const app = new VGApp();
+
+app
+	.register(VGModal.NAME, VGModal)
+	.register(VGTooltip.NAME, VGTooltip)
+	.boot();
 ```
 
-Ручное включение поиска не зависит от количества опций и имеет приоритет над `autosearch`:
+## Подключение
+
+### Laravel + Vite
+`resources/js/app.js`
+```js
+import vgapp from 'vgapp';
+import 'vgapp/build/vgapp.css';
+
+vgapp.boot();
+```
 
+`vite.config.js`
 ```js
-VGSelect.init(select, {
-	search: { enabled: true }, // поиск будет виден даже для двух опций
+import { defineConfig } from 'vite';
+import laravel from 'laravel-vite-plugin';
+
+export default defineConfig({
+	plugins: [
+		laravel([
+			'resources/css/app.css',
+			'resources/js/app.js',
+		]),
+	],
 });
 ```
 
-`search.remote: true` также всегда включает поле поиска: remote-режим не зависит от количества локальных опций.
+В Blade:
+```php
+@vite(['resources/css/app.css', 'resources/js/app.js'])
+```
+
+### Vite
+`src/main.js`
+```js
+import vgapp from 'vgapp';
+import 'vgapp/build/vgapp.css';
+
+vgapp.boot();
+```
+
+### Webpack
+`src/app.js`
+```js
+import vgapp from 'vgapp';
+import 'vgapp/build/vgapp.css';
+
+vgapp.boot();
+```
+
+Минимально в `webpack.config.js`:
+```js
+module.exports = {
+	entry: './src/app.js',
+	module: {
+		rules: [
+			{
+				test: /\.css$/i,
+				use: ['style-loader', 'css-loader'],
+			},
+		],
+	},
+};
+```
 
-Те же настройки через Data API:
+### Частичный boot
+Если не нужно поднимать весь реестр singleton-приложения:
+```js
+import { VGApp, VGModal, VGTooltip } from 'vgapp';
+import 'vgapp/build/vgapp.css';
+
+const app = new VGApp();
+
+app
+	.register(VGModal.NAME, VGModal)
+	.register(VGTooltip.NAME, VGTooltip)
+	.boot();
+```
+
+## Темы и SCSS-токены
+
+VGApp использует семантические CSS-переменные с префиксом `--vg-`. Значения переменных формируются из SCSS-карт `$theme-light` и `$theme-dark`, расположенных в `app/utils/scss/_tokens.scss`.
+
+Светлая тема используется по умолчанию. Явно выбрать тему можно атрибутом `data-vg-theme` на `<html>`:
+
+```html
+<html data-vg-theme="light">
+```
 
 ```html
-<select class="vg-select" data-autosearch="10">...</select>
-<select class="vg-select" data-search-enabled="true">...</select>
-<select class="vg-select" data-search-remote="true" data-search-route="/api/search">...</select>
+<html data-vg-theme="dark">
 ```
 
+Атрибут также можно установить на отдельный контейнер, чтобы изменить тему только внутри него:
+
+```html
+<section data-vg-theme="dark">
+	<!-- Компоненты внутри секции используют тёмную тему -->
+</section>
+```
+
+Тему можно переключать во время работы приложения:
+
+```js
+document.documentElement.dataset.vgTheme = 'dark';
+```
+
+`data-vg-theme` — стандартный адаптер готового `vgapp.css`, а не обязательный механизм темы сайта. При сборке из SCSS карты и генератор можно подключить к селекторам основного проекта:
+
+```scss
+@use "vgapp/theme" as vg-theme;
+
+[data-bs-theme="light"] {
+	@include vg-theme.theme-variables(vg-theme.$theme-light);
+}
+
+[data-bs-theme="dark"] {
+	@include vg-theme.theme-variables(vg-theme.$theme-dark);
+}
+```
+
+Таким же способом можно использовать `data-ox-theme`, класс `.dark` или любой другой селектор. VGApp генерирует только переменные с префиксом `--vg-` и не меняет глобальный `color-scheme` проекта.
+
+### Структура карт
+
+Карты содержат не названия конкретных компонентов, а общие семантические роли:
+
+- фон страницы и поверхности компонентов;
+- обычный, акцентный, вторичный, disabled и контрастный текст;
+- обычные, усиленные и disabled-границы;
+- primary-цвет и его состояния;
+- тени и backdrop;
+- цвета состояний `success`, `warning`, `danger` и `info`.
+
+У `$theme-light` и `$theme-dark` должен быть одинаковый набор ключей. Значения этих ключей для каждой темы могут отличаться.
+
+### Добавление нового токена
+
+Например, чтобы добавить secondary-цвет и цвет focus-ring, нужно расширить обе карты:
+
+```scss
+$theme-light: (
+	// Существующие токены...
+	secondary-color: #6b7280,
+	secondary-hover-color: #4b5563,
+	focus-ring-color: rgba(0, 101, 255, .35),
+);
+
+$theme-dark: (
+	// Существующие токены...
+	secondary-color: #a7a7a7,
+	secondary-hover-color: #d1d1d1,
+	focus-ring-color: rgba(110, 168, 254, .45),
+);
+```
+
+Генератор темы автоматически создаст CSS-переменные:
+
+```css
+--vg-secondary-color: ...;
+--vg-secondary-hover-color: ...;
+--vg-focus-ring-color: ...;
+```
+
+После этого токены можно использовать в компонентах:
+
+```scss
+.vg-control {
+	color: var(--vg-secondary-color);
+
+	&:hover {
+		color: var(--vg-secondary-hover-color);
+	}
+
+	&:focus-visible {
+		box-shadow: 0 0 0 3px var(--vg-focus-ring-color);
+	}
+}
+```
+
+При миграции существующего значения следует указывать fallback светлой темы. Благодаря этому отдельный SCSS-вход компонента продолжит работать, даже если базовый файл темы не был подключён:
+
+```scss
+border-color: var(--vg-border-color, rgba(0, 0, 0, .2));
+background: var(--vg-surface-bg, #ffffff);
+```
+
+### Правила именования
+
+- Токен должен описывать назначение, например `surface-hover-bg`, а не конкретное значение вроде `gray-100`.
+- Общие токены не должны содержать название компонента. Настройки конкретного компонента остаются в его собственной SCSS-карте.
+- Новый ключ необходимо добавлять одновременно в `$theme-light` и `$theme-dark`.
+- Компоненты должны использовать `var(--vg-...)`, чтобы тема могла переключаться без повторной сборки CSS.
+
+CSS-переменные темы генерируются в `app/utils/scss/_theme.scss` и подключаются через базовый `default.scss` и полную SCSS-сборку. Все SCSS-компоненты VGApp переведены на модульную систему Sass, семантические токены и публичные настраиваемые карты.
+
 ## Authors
-
-[VEGAS STUDIO](https://vegas-dev.com)  Russia
-
-## License
-Is published under the [MIT license](http://www.opensource.org/licenses/mit-license)
+
+[VEGAS STUDIO](https://vegas-dev.com)  Russia
+
+## License
+Is published under the [MIT license](http://www.opensource.org/licenses/mit-license)

package/app/modules/vgalert/scss/_variables.scss

@@ -1,14 +1,16 @@
+@use "../../../utils/scss" as vg;
+
 $alert-map: (
 	overlay-z-index: 1,
 	overlay-backdrop-bg: rgba(0, 0, 0, 0),
-	overlay-backdrop-show-bg: rgba(0, 0, 0, 0.25),
+	overlay-backdrop-show-bg: var(--vg-backdrop-subtle-color, rgba(0, 0, 0, .25)),
 	overlay-backdrop-transition: background-color .05s linear,
-	overlay-wrapper-bg: #fff,
+	overlay-wrapper-bg: var(--vg-surface-bg, #{vg.$surface-bg}),
 	overlay-wrapper-width: 90%,
 	overlay-wrapper-top: 1rem,
 	overlay-wrapper-start: 50%,
 	overlay-wrapper-transform: translate(-50%, -1rem),
 	overlay-wrapper-show-transform: translate(-50%, 0),
 	overlay-wrapper-transition: transform .12s ease-out,
-	buttons-bg: #F5F5F5,
-);
+	buttons-bg: var(--vg-surface-muted-bg, #{vg.$surface-muted-bg}),
+) !default;

package/app/modules/vgalert/scss/vgalert.scss

@@ -6,10 +6,9 @@
 *--------------------------------------------------------------------------
 **/
 
-@import "../../../utils/scss/functions";
-@import "../../../utils/scss/mixin";
-@import "../../../utils/scss/variables";
-@import "variables";
+@forward "variables";
+@use "../../../utils/scss" as vg;
+@use "variables" as vars;
 
 .vg-alert {
 	&-modal {
@@ -19,7 +18,7 @@
 	}
 
 	&-overlay {
-		@include mix-vars('alert', $alert-map);
+		@include vg.mix-vars('alert', vars.$alert-map);
 		width: 100%;
 		height: 100%;
 		position: absolute;
@@ -111,9 +110,9 @@
 	}
 
 	&-wrapper {
-		@include mix-vars('alert', $alert-map);
-		@include mix-alert-color-mode($class: vg-alert);
-		border-radius: var(--vg-border-radius);
+		@include vg.mix-vars('alert', vars.$alert-map);
+		@include vg.mix-alert-color-mode($class: vg-alert);
+		border-radius: var(--vg-border-radius, #{vg.$border-radius});
 		overflow: hidden;
 
 		.vg-alert-content {

package/app/modules/vgcollapse/scss/_variables.scss

@@ -1,5 +1,7 @@
-$collapse-accordion-map: (
-		border: 1px solid $border-color,
-		border-radius: $border-radius,
-		padding: 1rem
-);
+@use "../../../utils/scss" as vg;
+
+$collapse-accordion-map: (
+		border: vg.$border-width vg.$border-style var(--vg-border-color, #{vg.$border-color}),
+		border-radius: vg.$border-radius,
+		padding: 1rem
+) !default;

package/app/modules/vgcollapse/scss/vgcollapse.scss

@@ -6,14 +6,13 @@
 *--------------------------------------------------------------------------
 **/
 
-@import "../../../utils/scss/functions";
-@import "../../../utils/scss/mixin";
-@import "../../../utils/scss/variables";
-@import "variables";
+@forward "variables";
+@use "../../../utils/scss" as vg;
+@use "variables" as vars;
 
 
 .vg-accordion {
-	@include mix-vars('accordion', $collapse-accordion-map);
+	@include vg.mix-vars('accordion', vars.$collapse-accordion-map);
 	position: relative;
 	border: var(--vg-accordion-border);
 	border-radius: var(--vg-accordion-border-radius);
@@ -38,4 +37,4 @@
 		display: block;
 		padding: var(--vg-accordion-padding);
 	}
-}
+}

package/app/modules/vgdropdown/scss/_variables.scss

@@ -1,12 +1,14 @@
-$dropdown-map: (
-		bg-color:                  $bg-color,
-		color:                     $color,
-		box-shadow:                $box-shadow,
-		border-width:              1px,
-		border-style:              solid,
-		border-color:              $border-color,
-		border-radius:             $border-radius,
-		z-index:                   $dropdown-index,
-		transition:                $transition-base,
-		min-width:                 225px
-);
+@use "../../../utils/scss" as vg;
+
+$dropdown-map: (
+		bg-color:                  var(--vg-surface-bg, #{vg.$surface-bg}),
+		color:                     var(--vg-text-color, #{vg.$color}),
+		box-shadow:                var(--vg-box-shadow, #{vg.$box-shadow}),
+		border-width:              vg.$border-width,
+		border-style:              vg.$border-style,
+		border-color:              var(--vg-border-color, #{vg.$border-color}),
+		border-radius:             vg.$border-radius,
+		z-index:                   vg.$dropdown-index,
+		transition:                vg.$transition-base,
+		min-width:                 225px
+) !default;

package/app/modules/vgdropdown/scss/vgdropdown.scss

@@ -6,14 +6,13 @@
 *--------------------------------------------------------------------------
 **/
 
-@import "../../../utils/scss/functions";
-@import "../../../utils/scss/mixin";
-@import "../../../utils/scss/variables";
-@import "variables";
+@forward "variables";
+@use "../../../utils/scss" as vg;
+@use "variables" as vars;
 
 .vg-dropdown {
 	position: relative;
-	@include mix-vars('dropdown', $dropdown-map);
+	@include vg.mix-vars('dropdown', vars.$dropdown-map);
 
 	&-content {
 		z-index: var(--vg-dropdown-z-index);
@@ -78,4 +77,4 @@
 		border-radius: var(--vg-dropdown-border-radius);
 		box-shadow: var(--vg-dropdown-box-shadow);
 	}
-}
+}

package/app/modules/vgdynamictable/scss/_actions.scss

@@ -1,4 +1,5 @@
-[data-table-state] {
+@mixin actions() {
+[data-table-state] {
 	text-align: center;
 	padding: 18px 14px;
 	vertical-align: middle;
@@ -66,12 +67,12 @@ tbody tr[data-row-dragging="1"] {
 	opacity: 0.55;
 }
 
-tbody tr[data-row-drag-over="before"] {
-	box-shadow: inset 0 2px 0 #3f8cff;
-}
-
-tbody tr[data-row-drag-over="after"] {
-	box-shadow: inset 0 -2px 0 #3f8cff;
+tbody tr[data-row-drag-over="before"] {
+	box-shadow: inset 0 2px 0 var(--vg-dynamic-table-actions-drag-indicator);
+}
+
+tbody tr[data-row-drag-over="after"] {
+	box-shadow: inset 0 -2px 0 var(--vg-dynamic-table-actions-drag-indicator);
 }
 
 .vgdt-row-reorder-cell {
@@ -103,19 +104,19 @@ tbody tr[data-row-drag-over="after"] {
 	gap: 6px;
 }
 
-.vgdt-row-action {
-	border: 1px solid #a22929;
-	background: transparent;
-	color: #a22929;
+.vgdt-row-action {
+	border: 1px solid var(--vg-dynamic-table-actions-danger-color);
+	background: transparent;
+	color: var(--vg-dynamic-table-actions-danger-color);
 	border-radius: 8px;
 	padding: 5px 10px;
 	font-size: 12px;
 	cursor: pointer;
 }
 
-.vgdt-row-action:hover {
-	background: #a22929;
-	color: #fff;
+.vgdt-row-action:hover {
+	background: var(--vg-dynamic-table-actions-danger-color);
+	color: var(--vg-dynamic-table-actions-danger-contrast);
 }
 
 .vgdt-pan-hint {
@@ -184,10 +185,12 @@ tbody tr[data-row-drag-over="after"] {
 	}
 }
 
-@media (hover: none), (pointer: coarse), (any-pointer: coarse), (any-hover: none) {
+@media (hover: none), (pointer: coarse), (any-pointer: coarse), (any-hover: none) {
 	.vgdt-pan-hint {
 		display: none !important;
 	}
-}
+}
+
+}
 
 

package/app/modules/vgdynamictable/scss/_pagination.scss

@@ -1,4 +1,5 @@
-&.table-pagination {
+@mixin pagination() {
+&.table-pagination {
 	.vgdt-pagination {
 		padding: var(--vg-dynamic-table-pagination-padding-y) var(--vg-dynamic-table-pagination-padding-x);
 		border-top: 1px solid var(--vg-dynamic-table-pagination-border-color);
@@ -179,5 +180,7 @@
 	.vgdt-page--ellipsis:hover .vgdt-ellipsis-chevron {
 		display: inline;
 	}
-}
+}
+
+}