vgapp 0.7.8 → 0.8.0

package/app/modules/vgfiles/readme.md

@@ -0,0 +1,193 @@
+# VGFiles — Модуль загрузки и управления файлами
+
+`VGFiles` — это расширяемый и гибкий JavaScript-модуль для управления файлами на веб-странице, поддерживающий как локальную работу с файлами, так и асинхронную загрузку через AJAX. Модуль интегрируется с DOM-элементами, предоставляет визуальный интерфейс, поддерживает драг-н-дроп, валидацию, сортировку, отслеживание статусов и обработку событий.
+
+---
+
+## 🔧 Возможности
+
+### ✅ Основные функции
+- **Добавление файлов** через `<input type="file">` или **drag & drop**.
+- **Просмотр списков файлов** с превью (если тип — изображение).
+- **Удаление отдельных файлов** и **очистка всего списка**.
+- **Интеграция с сервером** через AJAX-запросы (загрузка, удаление, сортировка).
+- **Автоматическая валидация** по типу, количеству, размеру файлов.
+- **Многоязычная поддержка** (настраиваемые кнопки и сообщения).
+
+---
+
+## 📦 Установка и инициализация
+
+Модуль автоматически инициализируется на элементах с классом `.vg-files` при загрузке DOM:
+
+Или вручную:
+
+```js
+const files = new VGFiles(document.querySelector('.vg-files'), { 
+    ajax: true,
+    uploads: {
+        route: '/api/upload', 
+        mode: 'sequential'
+    }, 
+    limits: { 
+        count: 10, 
+        sizes: 5, // MB 
+        total: 50 
+    } 
+});
+```
+
+---
+
+## ⚙️ Параметры конфигурации
+
+| Параметр | Тип | По умолчанию | Описание |
+|--------|------|-------------|---------|
+| `init` | `boolean` | `true` | Автоматическая инициализация |
+| `allowed` | `boolean` | `false` | Разрешить дроп файлов |
+| `lang` | `string` | `'ru'` | Язык интерфейса (поддерживается через `lang_buttons`, `lang_messages`) |
+| `limits.count` | `number` | `0` | Макс. количество файлов (0 — без ограничений) |
+| `limits.sizes` | `number` | `10` | Макс. размер одного файла (в МБ) |
+| `limits.total` | `number` | `0` | Общий лимит размера (в МБ, 0 — без ограничений) |
+| `image` | `boolean` | `false` | Отображать превью изображений |
+| `detach` | `boolean` | `true` | Откреплять файлы после загрузки |
+| `info` | `boolean` | `true` | Показывать кнопку удаления |
+| `types` | `array` | `[]` | Разрешённые MIME-типы (например, `['image/png', 'application/pdf']`) |
+| `ajax` | `boolean` | `false` | Использовать AJAX-загрузку |
+| `prepend` | `boolean` | `true` | Добавлять новые файлы в начало списка |
+| `uploads.route` | `string` | `''` | URL для загрузки файлов |
+| `uploads.mode` | `'sequential' \| 'parallel'` | `'sequential'` | Режим отправки файлов |
+| `uploads.maxParallel` | `number` | `3` | Макс. файлов при параллельной загрузке |
+| `uploads.maxConcurrent` | `number` | `1` | Макс. одновременных запросов |
+| `uploads.retryAttempts` | `number` | `1` | Кол-во попыток повтора при ошибке |
+| `uploads.retryDelay` | `number` | `1000` | Задержка между попытками (мс) |
+| `removes.single.route` | `string` | `''` | URL для удаления одного файла |
+| `removes.all.route` | `string` | `''` | URL для удаления всех файлов |
+| `removes.single.alert` | `boolean` | `true` | Показывать подтверждение при удалении |
+| `removes.single.toast` | `boolean` | `true` | Показывать уведомление после удаления |
+| `sortable.enabled` | `boolean` | `false` | Включить сортировку |
+| `sortable.route` | `string` | `''` | URL для сохранения порядка файлов |
+| `callbacks` | `object` | `null` | Колбэки на события (см. ниже) |
+
+---
+
+## 📢 События и колбэки
+
+Модуль поддерживает как DOM-события, так и JS-колбэки:
+
+### DOM-события
+- `vg.files.change` — изменение списка файлов
+- `vg.files.upload.allComplete` — все файлы загружены
+- `vg.files.remove` — файл удалён
+
+### Колбэки (`callbacks`)
+| Колбэк | Параметры | Описание |
+|-------|----------|--------|
+| `onInit` | `(data)` | Инициализация завершена |
+| `onChange` | `{ files, input }` | Изменён список файлов |
+| `onUploadStart` | `{ files, total }` | Началась загрузка |
+| `onUploadProgress` | `{ file, progress, bytesSent, totalBytes }` | Прогресс загрузки |
+| `onUploadComplete` | `{ file, response, status, id }` | Файл успешно загружен |
+| `onUploadError` | `{ file }` | Ошибка загрузки |
+| `onUploadAllComplete` | `{ uploaded, failed, total }` | Все файлы загружены |
+| `onRemoveFile` | `{ button, name, size, id, remaining }` | Удалён файл |
+| `onClear` | `{}` | Очищен весь список |
+| `onReload` | `{ button, file }` | Повторная попытка загрузки |
+
+---
+
+## 📊 Статусы файлов
+
+Модуль отслеживает статусы в реальном времени:
+- **`pending`** — ожидает загрузки
+- **`loading`** — идёт загрузка
+- **`completed`** — успешно загружен
+- **`failing`** — ошибка загрузки
+
+---
+
+## 🔁 Внешние (уже загруженные) файлы
+
+Модуль может отображать уже загруженные файлы, переданные через `data-file`:
+-- TODO описать полностью
+
+## 🧹 Очистка и удаление
+
+- **Удаление одного файла**: кнопка с `data-vg-dismiss="file"` → вызов `removeFile()`.
+- **Очистка всех**: кнопка с `data-vg-dismiss="vg-files"` → `clear()`.
+
+Поддержка подтверждения через `VGAlert` и уведомлений через `VGToast`.
+
+---
+
+## 🧩 Расширяемость
+
+- **FileUploader** — управляет загрузкой с поддержкой retry.
+- **VGFilesTemplateRender** — рендеринг шаблонов.
+- **Sortable (сортировка)** — подключается при необходимости.
+- Поддержка кастомных иконок через `getSVG()`.
+
+---
+
+## 🧰 API Методы
+
+| Метод | Описание |
+|------|--------|
+| `upload(file)` | Загрузить один файл |
+| `uploadAll(files)` | Загрузить все неотправленные файлы |
+| `reload(button)` | Повторить загрузку файла |
+| `removeFile(button)` | Удалить файл |
+| `clear(full, uiOnly)` | Очистить список |
+| `dispose()` | Полная деинициализация |
+| `_triggerCallback(name, data)` | Вызов колбэка |
+| `_route(params, cb)` | Выполнить AJAX-запрос |
+
+---
+
+## 🌐 AJAX-интеграция
+
+Поддерживает:
+- Загрузку `POST /upload`
+- Удаление `DELETE /files/{id}` или `POST /clear` с `ids[]`
+- Сортировку `POST /sort` с массивом `ids`
+
+---
+
+## 🛑 Ограничения и валидация
+
+- Проверка по размеру (одиночному и общему).
+- Проверка по количеству файлов.
+- Проверка MIME-типов.
+- Отображение ошибок через `VGAlert` или консоль.
+
+---
+
+## 🧾 Поддержка браузеров
+
+- Современные браузеры (Chrome, Firefox, Safari, Edge)
+- Требуется поддержка: `File`, `FormData`, `ES6+`, `CustomEvent`
+
+---
+
+## 📚 Зависимости
+
+- `VGFilesBase`, `VGFilesDroppable`, `VGFilesTemplateRender`, `FileUploader`
+- `VGAlert`, `VGToast` — модули уведомлений
+- `EventHandler`, `Selectors`, `Manipulator`, `Classes` — утилиты DOM
+- `getSVG`, `lang_buttons`, `lang_messages` — компоненты интерфейса
+
+---
+
+✅ **Гибкий | Расширяемый | Локализуемый | Готов к production**
+
+---
+
+## 📝 Лицензия
+
+MIT. Свободно использовать и модифицировать.
+
+---
+
+📌 *Разработано в рамках фронтенд-системы VG Modules.*
+> 🚀 Автор: VEGAS STUDIO (vegas-dev.com)
+> 📍 Поддерживается в проектах VEGAS

package/app/modules/vgfiles/scss/_animations.scss

@@ -0,0 +1,18 @@
+@keyframes stripes {
+	0% {
+		background-position: 0 0;
+	}
+	100% {
+		background-position: 60px 30px;
+	}
+}
+
+@keyframes flash {
+	0%, 100% { opacity: 1; }
+	50% { opacity: 0; }
+}
+
+@keyframes spinner {
+	0% { transform: rotate(0deg); }
+	100% { transform: rotate(360deg); }
+}

package/app/modules/vgfiles/scss/_mixins.scss

@@ -0,0 +1,73 @@
+/**
+ * Локальные миксины модуля (убирают дублирование между списками)
+ */
+@mixin vgfiles-sortable() {
+	&.with-sortable {
+		cursor: grab;
+
+		&:active {
+			cursor: grabbing;
+		}
+
+		&.dragging {
+			opacity: 0.6;
+			transform: scale(1.02);
+			z-index: 1000;
+			position: relative;
+		}
+
+		&.dragging-transparent {
+			pointer-events: none;
+			opacity: 0.3;
+		}
+	}
+}
+
+@mixin vgfiles-state() {
+	&.pending {
+		> * {
+			opacity: .32;
+			pointer-events: none;
+		}
+
+		.file-remove {
+			opacity: 0;
+		}
+	}
+
+	&.loading {
+		--vg-button-color: var(--vg-body-color);
+
+		> *:not(.file-remove) {
+			opacity: .52;
+			pointer-events: none;
+		}
+
+		.file-remove {
+			opacity: 1;
+			pointer-events: none;
+
+			button {
+				i {
+					animation: spinner 1s linear infinite;
+				}
+			}
+		}
+	}
+
+	&.completed {
+		--vg-button-color: var(--vg-success);
+	}
+
+	&.failing {
+		--vg-button-color: var(--vg-danger);
+
+		> * {
+			opacity: .62;
+		}
+
+		.file-remove {
+			opacity: 1;
+		}
+	}
+}

package/app/modules/vgfiles/scss/_variables.scss

@@ -1,28 +1,105 @@
 $files-map: (
-		label-bg: #242424,
-		label-color: #ffffff,
-		label-border-color: #343434,
-		label-border-radius: 4px,
-		label-padding: 8px 24px,
-		label-padding-icon: 8px 16px,
-		info-mt: 10px,
-		info-mb: 10px,
-		info-title-fw: 600,
-		info-title-color: darkgreen,
-		info-count-fw: 400,
-		info-count-fs: 14px,
-		info-count-color: #999999,
-		info-count-ms: 7px,
-		info-dismiss-fs: 14px,
-		info-dismiss-ms: 10px,
-		info-image-width: 100px,
-		info-image-me: 15px,
-		info-image-mb: 15px,
-		info-image-padding: 5px,
-		info-image-border: 1px solid #e0e0e0,
-		info-list-fs: 15px,
-		info-list-mt: 7px,
-		info-list-span-fs: 12px,
-		info-list-span-color: #999999,
-		info-list-span-me: 6px,
+	// label (уже используется в vgfiles.scss)
+	label-bg: #242424,
+	label-color: #ffffff,
+	label-border-color: #343434,
+	label-border-radius: 4px,
+	label-padding: 8px 24px,
+	label-padding-icon: 8px 16px,
+
+	// errors
+	errors-padding-y: 10px,
+	errors-font-size: 16px,
+
+	// drop zone
+	drop-bg: var(--vg-secondary-bg),
+	drop-border-width: 2px,
+	drop-border-style: dashed,
+	drop-border-color: var(--vg-secondary),
+	drop-radius: 8px,
+	drop-height: 200px,
+	drop-transition: all 0.2s ease,
+
+	drop-after-font-size: 14px,
+	drop-after-color: #007bff,
+	drop-after-bottom: 10px,
+
+	drop-hover-border-color: #007bff,
+	drop-hover-bg: #e3f2fd,
+	drop-hover-shadow: 0 0 10px rgba(0, 123, 255, 0.2),
+
+	drop-stripes-alpha: 0.03,
+	drop-stripes-size: 30px 30px,
+	drop-stripes-duration: 2s,
+
+	// drop message
+	drop-message-gap: 8px,
+	drop-message-font-size: 14px,
+	drop-message-line-height: 22px,
+	drop-message-color: #999999,
+	drop-message-icon-size: 48px,
+	drop-message-icon-color: #999999,
+
+	// drop list / file tiles
+	drop-list-gap: 8px,
+	drop-list-padding: 0.5rem,
+	drop-file-radius: 6px,
+	drop-file-height: 100px,
+	drop-file-flex: calc(25% - 6px),
+
+	drop-remove-offset: 10px,
+	drop-remove-size: 36px,
+	drop-remove-radius: 3px,
+	drop-remove-hover-bg: rgba(var(--vg-body-bg-rgb), .4),
+
+	// stat
+	stat-padding: 12px 8px,
+	stat-gap: 1rem,
+	stat-mb: 1rem,
+	stat-border-color: var(--vg-secondary-bg),
+	stat-title-fw: 600,
+	stat-count-font-size: 14px,
+	stat-count-ms: 6px,
+	stat-dismiss-font-size: 16px,
+
+	// info
+	info-mt: 1rem,
+	info-border-color: var(--vg-secondary-bg),
+	info-radius: 4px,
+	info-list-max-height: 360px,
+
+	info-gap: 8px,
+	info-padding: 8px,
+	info-border-bottom-color: var(--vg-secondary-bg),
+	info-hover-bg: rgba(var(--vg-secondary-bg-rgb), .4),
+
+	info-image-radius: 4px,
+	info-iteration-font-size: 16px,
+	info-name-font-size: 16px,
+	info-size-font-size: 14px,
+
+	info-remove-icon-size: 16px,
+	info-row-remove-size: 22px,
+	info-row-remove-icon-size: 10px,
+
+	// legacy (оставлено для совместимости со старым API темы)
+	info-mb: 10px,
+	info-title-color: darkgreen,
+	info-count-fw: 400,
+	info-count-fs: 14px,
+	info-count-color: #999999,
+	info-dismiss-fs: 14px,
+	info-dismiss-ms: 10px,
+	info-image-width: 100px,
+	info-image-me: 15px,
+	info-image-mb: 15px,
+	info-image-padding: 5px,
+	info-image-border: 1px solid #e0e0e0,
+	info-list-fs: 15px,
+	info-list-mt: 7px,
+	info-list-span-fs: 12px,
+	info-list-span-color: #999999,
+	info-list-span-me: 6px,
+	info-list-button-fs: 12px,
+	info-list-button-color: #999999,
 );