refactor: extract composable logic into focused modules and enhance docs

Author: genu

docs/content/2.usage/1.overview.md

@@ -128,45 +128,6 @@ Clear all files and reset state.
 uploader.reset()
 ```
 
-### Upload Configuration
-
-#### `onUpload(fn: UploadFn): void`
-
-Set the upload handler function. Required unless using a storage plugin.
-
-```ts
-uploader.onUpload(async (file, onProgress) => {
-  const formData = new FormData()
-  formData.append("file", file.data as Blob)
-
-  const xhr = new XMLHttpRequest()
-
-  xhr.upload.onprogress = (e) => {
-    if (e.lengthComputable) {
-      onProgress(Math.round((e.loaded / e.total) * 100))
-    }
-  }
-
-  return new Promise((resolve, reject) => {
-    xhr.onload = () => resolve(JSON.parse(xhr.response))
-    xhr.onerror = () => reject(new Error("Upload failed"))
-    xhr.open("POST", "/api/upload")
-    xhr.send(formData)
-  })
-})
-```
-
-#### `onGetRemoteFile(fn: GetRemoteFileFn): void`
-
-Set a function to fetch remote file metadata. Used when initializing existing files.
-
-```ts
-uploader.onGetRemoteFile(async (fileId) => {
-  const response = await fetch(`/api/files/${fileId}`)
-  return await response.json()
-})
-```
-
 ### File Access Methods
 
 #### `getFile(fileId: string): UploadFile`

docs/content/2.usage/2.events.md

@@ -107,20 +107,33 @@ uploader.on("upload:progress", ({ file, progress }) => {
 
 #### `upload:complete`
 
-Fired when all uploads are complete.
+Fired when the current upload batch completes (including any errors).
 
 ```ts
 uploader.on("upload:complete", (files: UploadFile[]) => {
-  console.log("All uploads complete!")
+  console.log("Batch complete:", files.length, "files processed")
   hideLoadingIndicator()
+})
+```
 
-  // Access upload results
-  files.forEach((file) => {
-    console.log(file.name, "->", file.remoteUrl)
-  })
+#### `files:uploaded`
+
+Fired when **all** files in the uploader reach `complete` status. This is the best event for final form submission.
+
+```ts
+uploader.on("files:uploaded", (files: UploadFile[]) => {
+  console.log("All files uploaded successfully!")
+
+  // Safe to submit form - all files are uploaded
+  const urls = files.map((f) => f.remoteUrl)
+  submitForm({ attachments: urls })
 })
 ```
 
+::callout{type="info"}
+`files:uploaded` only fires once per "session" - adding new files resets it so it can fire again.
+::
+
 #### `upload:error`
 
 Fired on upload errors.
@@ -215,6 +228,7 @@ type UploaderEvents = {
   "upload:complete": UploadFile[]
   "upload:error": FileError
   "upload:progress": { file: UploadFile; progress: number }
+  "files:uploaded": UploadFile[] // All files complete
   "files:reorder": { oldIndex: number; newIndex: number }
   "initialFiles:loaded": UploadFile[]
   "initialFiles:error": unknown

docs/content/5.advanced/2.custom-plugins.md

@@ -1,16 +1,63 @@
 ---
-title: Plugins
-description: Create your own validators and processors.
+title: Plugin Authoring
+description: Create your own validators and processors with this comprehensive guide.
 navigation:
   icon: i-lucide-puzzle
 ---
 
-# Custom Plugins
+# Plugin Authoring Guide
 
-Use `defineProcessingPlugin` to create custom validators and file processors.
+This guide covers everything you need to know to create custom plugins for Nuxt Upload Kit.
+
+## Architecture Overview
+
+Nuxt Upload Kit uses a **plugin-based architecture** with three plugin types:
+
+| Type | Purpose | Example | Define With |
+|------|---------|---------|-------------|
+| **Validator** | Gate files before adding | Max file size, allowed types | `defineProcessingPlugin` |
+| **Processor** | Transform files | Thumbnails, compression | `defineProcessingPlugin` |
+| **Storage** | Handle persistence | S3, Azure, Firebase | `defineStorageAdapter` |
+
+## Plugin Lifecycle
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         ADDING FILES                                │
+│                                                                     │
+│   addFile() ──▶ [validate] ──▶ [preprocess] ──▶ file:added         │
+│                     │                                               │
+│                     ▼ (fail)                                        │
+│                  file:error                                         │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              │ upload() called
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                         UPLOADING                                   │
+│                                                                     │
+│   [process] ──▶ storage.upload ──▶ [complete] ──▶ upload:complete  │
+│       │              │                                              │
+│       ▼ (fail)       ▼ (fail)                                       │
+│    file:error     file:error                                        │
+└─────────────────────────────────────────────────────────────────────┘
+
+Legend: [hooks] are plugin extension points
+```
+
+### When Each Hook Runs
+
+| Hook | When | Use For |
+|------|------|---------|
+| `validate` | Immediately on `addFile()` | Rejecting invalid files |
+| `preprocess` | After validation passes | Generating thumbnails, previews |
+| `process` | When `upload()` is called | Compression, transformations |
+| `complete` | After successful upload | Post-upload cleanup |
 
 ## Basic Structure
 
+Use `defineProcessingPlugin` to create custom validators and file processors.
+
 ```ts
 import { defineProcessingPlugin } from "nuxt-upload-kit"
 
@@ -292,3 +339,103 @@ export const PluginImageResizer = defineProcessingPlugin<ImageResizerOptions, Im
   }
 })
 ````
+
+## Best Practices
+
+### 1. Always Check File Source
+
+Remote files (`source: "storage"`) have `data: null`. Always check before accessing file data:
+
+```ts
+process: async (file, context) => {
+  if (file.source !== "local") {
+    context.emit("skip", { file, reason: "Remote file" })
+    return file
+  }
+
+  // Safe to access file.data
+  const blob = file.data
+}
+```
+
+### 2. Return Original on Failure
+
+Never throw from `process` hooks unless you want to fail the upload. Return the original file to continue:
+
+```ts
+process: async (file, context) => {
+  try {
+    // Transform file...
+    return transformedFile
+  } catch (error) {
+    console.warn(`[MyPlugin] Failed:`, error)
+    return file // Continue with original
+  }
+}
+```
+
+### 3. Use Namespaced Plugin IDs
+
+Prefix your plugin IDs to avoid collisions:
+
+```ts
+// Good
+id: "mycompany-watermark"
+id: "acme-validator-dimensions"
+
+// Avoid
+id: "watermark" // Too generic
+```
+
+### 4. Emit Events for Observability
+
+Emit events so users can track plugin activity:
+
+```ts
+process: async (file, context) => {
+  context.emit("start", { file })
+
+  // Do work...
+
+  context.emit("complete", { file, savings: originalSize - newSize })
+  return file
+}
+```
+
+### 5. Document Your Plugin
+
+Include JSDoc comments with examples:
+
+```ts
+/**
+ * Validates that images meet minimum dimension requirements.
+ *
+ * @example
+ * ```ts
+ * useUploadKit({
+ *   plugins: [
+ *     ValidatorMinDimensions({ minWidth: 800, minHeight: 600 })
+ *   ]
+ * })
+ * ```
+ */
+export const ValidatorMinDimensions = defineProcessingPlugin<Options>((options) => ({
+  // ...
+}))
+```
+
+### 6. Handle All Image Types Appropriately
+
+Some formats need special handling:
+
+```ts
+process: async (file, context) => {
+  // Skip non-processable formats
+  if (file.mimeType === "image/gif" || file.mimeType === "image/svg+xml") {
+    context.emit("skip", { file, reason: "Format not supported" })
+    return file
+  }
+
+  // Process other images...
+}
+```

docs/content/5.advanced/3.custom-storage-adapters.md

@@ -101,7 +101,10 @@ export const PluginMyStorage = defineStorageAdapter<MyStorageOptions, MyStorageR
 
     // Optional: Delete a file
     remove: async (file, context) => {
-      await fetch(`${options.apiUrl}/${file.id}`, {
+      // Use storageKey for deletion (set after upload or from initialFiles)
+      if (!file.storageKey) return
+
+      await fetch(`${options.apiUrl}/${file.storageKey}`, {
         method: "DELETE",
         headers: { "X-API-Key": options.apiKey },
       })
@@ -153,18 +156,60 @@ The `upload` hook **must** return an object containing at least a `url` property
 // Minimum required
 return { url: "https://storage.example.com/file.jpg" }
 
-// With additional metadata
+// With additional metadata (recommended)
 return {
   url: "https://storage.example.com/file.jpg",
-  id: "file-123",
+  storageKey: "uploads/user-123/file.jpg", // Full path for retrieval/deletion
   etag: "abc123",
   bucket: "my-bucket",
-  // Any other properties you need
 }
 ```
 
 The returned object becomes available as `file.uploadResult` after the upload completes.
 
+## The storageKey Pattern
+
+The `storageKey` is the **full path** used to identify files in storage. It enables:
+- Loading existing files via `initialFiles`
+- Deleting files with `removeFile()`
+- Round-trip consistency (upload → store key → retrieve later)
+
+```ts
+// Upload returns storageKey
+upload: async (file, context) => {
+  const path = `uploads/${options.folder}/${file.id}`
+
+  await uploadToStorage(path, file.data)
+
+  return {
+    url: `https://cdn.example.com/${path}`,
+    storageKey: path, // Save this to your database
+  }
+}
+
+// getRemoteFile receives storageKey
+getRemoteFile: async (storageKey, context) => {
+  const metadata = await getFromStorage(storageKey)
+
+  return {
+    size: metadata.size,
+    mimeType: metadata.contentType,
+    remoteUrl: `https://cdn.example.com/${storageKey}`,
+  }
+}
+
+// remove receives file with storageKey
+remove: async (file, context) => {
+  if (!file.storageKey) return // Not uploaded yet
+
+  await deleteFromStorage(file.storageKey)
+}
+```
+
+::callout{type="info"}
+Store the `storageKey` in your database alongside other file metadata. Pass it back via `initialFiles` to reload files.
+::
+
 ## Remote File Metadata
 
 The `getRemoteFile` hook must return an object with these properties: