nuxt-ui-elements 0.1.30 → 0.1.32

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-ui-elements",
   "configKey": "uiElements",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/composables/useUploadManager/index.js

@@ -154,12 +154,12 @@ The LAST storage plugin ("${plugin.id}") will be used for uploads.
           size: remoteFileData.size,
           mimeType: remoteFileData.mimeType,
           remoteUrl: remoteFileData.remoteUrl,
+          preview: remoteFileData.preview || file.preview || remoteFileData.remoteUrl,
+          // Use preview from storage, passed-in value, or fallback to remoteUrl
           source: "storage"
           // File loaded from remote storage
         };
-        const processedFile = await runPluginStage("process", existingFile);
-        if (!processedFile) return null;
-        return processedFile;
+        return existingFile;
       })
     );
     const filteredFiles = initializedfiles.filter((f) => f !== null);
@@ -185,14 +185,14 @@ The LAST storage plugin ("${plugin.id}") will be used for uploads.
     };
     const validatedFile = await runPluginStage("validate", uploadFile);
     if (!validatedFile) return null;
-    const processedFile = await runPluginStage("process", validatedFile);
-    if (!processedFile) return null;
-    files.value.push(processedFile);
-    emitter.emit("file:added", processedFile);
+    const preprocessedFile = await runPluginStage("preprocess", validatedFile);
+    const fileToAdd = preprocessedFile || validatedFile;
+    files.value.push(fileToAdd);
+    emitter.emit("file:added", fileToAdd);
     if (options.autoProceed) {
       upload();
     }
-    return processedFile;
+    return validatedFile;
   };
   const addFiles = (newFiles) => {
     return Promise.all(newFiles.map((file) => addFile(file)));
@@ -328,10 +328,27 @@ The LAST storage plugin ("${plugin.id}") will be used for uploads.
     emitter.emit("upload:start", filesToUpload);
     for (const file of filesToUpload) {
       try {
-        updateFile(file.id, { status: "uploading" });
+        const processedFile = await runPluginStage("process", file);
+        if (!processedFile) {
+          const error = {
+            message: "File processing failed",
+            details: {
+              fileName: file.name,
+              fileSize: file.size,
+              timestamp: (/* @__PURE__ */ new Date()).toISOString()
+            }
+          };
+          updateFile(file.id, { status: "error", error });
+          emitter.emit("file:error", { file, error });
+          continue;
+        }
+        if (processedFile.id !== file.id) {
+          files.value = files.value.map((f) => f.id === file.id ? processedFile : f);
+        }
+        updateFile(processedFile.id, { status: "uploading" });
         const onProgress = (progress) => {
-          updateFile(file.id, { progress: { percentage: progress } });
-          emitter.emit("upload:progress", { file, progress });
+          updateFile(processedFile.id, { progress: { percentage: progress } });
+          emitter.emit("upload:progress", { file: processedFile, progress });
         };
         const storagePlugin = getStoragePlugin();
         let uploadResult;
@@ -342,12 +359,14 @@ The LAST storage plugin ("${plugin.id}") will be used for uploads.
             onProgress,
             emit: getPluginEmitFn(storagePlugin.id)
           };
-          uploadResult = await storagePlugin.hooks.upload(file, context);
+          uploadResult = await storagePlugin.hooks.upload(processedFile, context);
         } else {
-          uploadResult = await uploadFn(file, onProgress);
+          uploadResult = await uploadFn(processedFile, onProgress);
         }
         const remoteUrl = uploadResult?.url;
-        updateFile(file.id, { status: "complete", uploadResult, remoteUrl });
+        const currentFile = files.value.find((f) => f.id === processedFile.id);
+        const preview = currentFile?.preview || remoteUrl;
+        updateFile(processedFile.id, { status: "complete", uploadResult, remoteUrl, preview });
       } catch (err) {
         const error = {
           message: err instanceof Error ? err.message : "Unknown upload error",
@@ -372,6 +391,7 @@ The LAST storage plugin ("${plugin.id}") will be used for uploads.
       case "validate":
         await hook(file, context);
         return file;
+      case "preprocess":
       case "process":
       case "complete":
         if (!file) throw new Error("File is required for this hook type");

package/dist/runtime/composables/useUploadManager/plugins/thumbnail-generator.js

@@ -3,7 +3,7 @@ export const PluginThumbnailGenerator = defineUploaderPlugin((pluginOptions) =>
   return {
     id: "thumbnail-generator",
     hooks: {
-      process: async (file, _context) => {
+      preprocess: async (file, _context) => {
         const { width = 100, height = 100, quality = 0.7 } = pluginOptions;
         const sourceUrl = file.source === "local" ? URL.createObjectURL(file.data) : file.remoteUrl;
         if (file.mimeType.startsWith("image/")) {

package/dist/runtime/composables/useUploadManager/plugins/video-compressor.js

@@ -1,7 +1,7 @@
 import { defineUploaderPlugin } from "../types.js";
 import { useFFMpeg } from "../../useFFMpeg.js";
 import { watchEffect } from "vue";
-export const PluginVideoCompressor = defineUploaderPlugin((pluginOptions) => {
+export const PluginVideoCompressor = defineUploaderPlugin((pluginOptions = {}) => {
   return {
     id: "video-compressor",
     hooks: {
@@ -35,10 +35,7 @@ export const PluginVideoCompressor = defineUploaderPlugin((pluginOptions) => {
         try {
           context.emit("start", { file, originalSize: file.size });
           const inputUrl = URL.createObjectURL(file.data);
-          const ffmpeg = useFFMpeg({
-            inputUrl,
-            convertOptions: []
-          });
+          const ffmpeg = useFFMpeg({ inputUrl });
           await ffmpeg.load();
           watchEffect(() => {
             context.emit("progress", { file, percentage: Math.round(ffmpeg.progress.value * 100) });

package/dist/runtime/composables/useUploadManager/types.d.ts

@@ -29,33 +29,112 @@ export type FileSource = 'local' | 'storage' | 'instagram' | 'dropbox' | 'google
  * Base properties shared by both local and remote upload files
  */
 export interface BaseUploadFile<TUploadResult = any> {
+    /** Unique identifier for the file */
     id: string;
+    /** Original filename (e.g., "vacation-photo.jpg") */
     name: string;
+    /** File size in bytes */
     size: number;
+    /** MIME type (e.g., "image/jpeg", "video/mp4") */
     mimeType: string;
+    /**
+     * Current upload status
+     */
     status: FileStatus;
+    /**
+     * Preview URL for displaying in UI (always populated after initialization)
+     * - For local files: Generated by thumbnail plugin as data URL, or remoteUrl after upload
+     * - For remote files: Provided by backend/storage, or falls back to remoteUrl
+     * - No manual fallback needed: Always available for display
+     */
     preview?: string;
+    /** Upload progress tracking */
     progress: FileProgress;
+    /** Error information if upload fails */
     error?: FileError;
+    /**
+     * Result returned by the upload function/storage plugin
+     * Can contain additional metadata like etag, key, etc.
+     */
     uploadResult?: TUploadResult;
+    /**
+     * Custom metadata for storing additional file information
+     * Plugins can add data here (e.g., { extension: 'jpg', originalWidth: 4000 })
+     */
     meta: Record<string, unknown>;
 }
 /**
  * Local upload file - originates from user's device
- * Has local data (File/Blob) and may get a remoteUrl after upload
+ *
+ * Lifecycle:
+ * 1. User selects file → created with data, no remoteUrl
+ * 2. Validation → runs validate hooks
+ * 3. Preprocessing → generates thumbnails (preview set here)
+ * 4. User clicks upload → runs process hooks (compression)
+ * 5. Upload → remoteUrl set after successful upload
+ *
+ * @example
+ * ```typescript
+ * const localFile: LocalUploadFile = {
+ *   source: 'local',
+ *   data: fileBlob,        // Has local data
+ *   remoteUrl: undefined,  // Not uploaded yet
+ *   preview: 'data:image/jpeg;base64,...', // Generated by thumbnail plugin
+ *   ...
+ * }
+ * ```
  */
 export interface LocalUploadFile<TUploadResult = any> extends BaseUploadFile<TUploadResult> {
+    /** Always 'local' for files selected from user's device */
     source: 'local';
+    /**
+     * The actual file data (File from input or Blob)
+     * Available for processing, compression, thumbnail generation, etc.
+     */
     data: File | Blob;
+    /**
+     * URL where file was uploaded (set after successful upload)
+     * undefined before upload, populated after upload completes
+     * Use to check if file has been uploaded: `if (file.remoteUrl) { ... }`
+     */
     remoteUrl?: string;
 }
 /**
- * Remote upload file - originates from remote source (cloud pickers, etc.)
- * Has remoteUrl but no local data
+ * Remote upload file - originates from remote source
+ *
+ * These files already exist remotely and don't need uploading.
+ * Common sources:
+ * - 'storage': Previously uploaded files being re-loaded
+ * - 'instagram', 'dropbox', etc.: Files from cloud pickers
+ *
+ * @example
+ * ```typescript
+ * const remoteFile: RemoteUploadFile = {
+ *   source: 'storage',
+ *   data: null,           // No local data - file is remote
+ *   remoteUrl: 'https://storage.com/file.jpg',  // Always present
+ *   preview: 'https://storage.com/thumbnails/file.jpg', // Optional, from backend
+ *   status: 'complete',   // Already uploaded
+ *   ...
+ * }
+ * ```
  */
 export interface RemoteUploadFile<TUploadResult = any> extends BaseUploadFile<TUploadResult> {
+    /**
+     * Source of the remote file
+     * - 'storage': File from your storage (previously uploaded)
+     * - 'instagram', 'dropbox', etc.: File from cloud picker
+     */
     source: Exclude<FileSource, 'local'>;
+    /**
+     * Always null for remote files (no local data available)
+     * File exists remotely and is accessed via remoteUrl
+     */
     data: null;
+    /**
+     * URL to the remote file (always present for remote files)
+     * Use this to display/download the file
+     */
     remoteUrl: string;
 }
 /**
@@ -199,9 +278,10 @@ export type UploadHook<TUploadResult = any, TPluginEvents extends Record<string,
 }>;
 export type GetRemoteFileHook<TPluginEvents extends Record<string, any> = Record<string, never>> = (fileId: string, context: PluginContext<TPluginEvents>) => Promise<MinimumRemoteFileAttributes>;
 export type RemoveHook<TPluginEvents extends Record<string, any> = Record<string, never>> = (file: UploadFile, context: PluginContext<TPluginEvents>) => Promise<void>;
-export type PluginLifecycleStage = "validate" | "process" | "upload" | "complete";
+export type PluginLifecycleStage = "validate" | "preprocess" | "process" | "upload" | "complete";
 export type PluginHooks<TUploadResult = any, TPluginEvents extends Record<string, any> = Record<string, never>> = {
     validate?: ValidationHook<TPluginEvents>;
+    preprocess?: ProcessingHook<TPluginEvents>;
     process?: ProcessingHook<TPluginEvents>;
     upload?: UploadHook<TUploadResult, TPluginEvents>;
     getRemoteFile?: GetRemoteFileHook<TPluginEvents>;
@@ -280,5 +360,6 @@ type MinimumRemoteFileAttributes = {
     size: number;
     mimeType: string;
     remoteUrl: string;
+    preview?: string;
 };
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-ui-elements",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "A collection of beautiful, animated UI components for Nuxt applications",
   "license": "MIT",
   "repository": "https://github.com/genu/nuxt-ui-elements.git",