feat: enhance removeFile function to support conditional deletion from storage with options

Author: genu

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

@@ -69,12 +69,31 @@ Add multiple files. Returns successfully added files (failed validations are fil
 const addedFiles = await uploader.addFiles(Array.from(input.files))
 ```
 
-#### `removeFile(fileId: string): Promise<void>`
+#### `removeFile(fileId: string, options?): Promise<void>`
 
-Remove a file by ID. If the file was uploaded, also removes it from storage (if storage plugin supports it).
+Remove a file by ID. Optionally control whether to delete from remote storage.
+
+**Options:**
+
+| Option              | Type                                       | Default    | Description                                                                                           |
+| ------------------- | ------------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------- |
+| `deleteFromStorage` | `"always"` \| `"never"` \| `"local-only"` | `"always"` | Controls storage deletion behavior                                                                    |
+
+**`deleteFromStorage` values:**
+
+- `"always"` - Always delete from storage if the file has a `remoteUrl`
+- `"never"` - Never delete from storage, only remove from local state (useful for forms that reference shared files)
+- `"local-only"` - Only delete files uploaded in this session (`source === "local"`), preserving files loaded via `initializeExistingFiles`
 
 ```ts
+// Default: removes from local state AND deletes from storage
 await uploader.removeFile(file.id)
+
+// Only remove from local state, keep in storage
+await uploader.removeFile(file.id, { deleteFromStorage: "never" })
+
+// Delete from storage only if this form uploaded it
+await uploader.removeFile(file.id, { deleteFromStorage: "local-only" })
 ```
 
 #### `removeFiles(fileIds: string[]): UploadFile[]`

src/runtime/composables/useUploadKit/index.ts

@@ -414,19 +414,45 @@ export const useUploadKit = <TUploadResult = any>(_options: UploadOptions = {})
     return addedFiles
   }
 
-  const removeFile = async (fileId: string, removeOptions?: { deleteFromStorage?: boolean }) => {
-    const { deleteFromStorage = true } = removeOptions ?? {}
+  /**
+   * Remove a file from the upload manager.
+   *
+   * @param fileId - The ID of the file to remove
+   * @param removeOptions - Options for controlling storage deletion behavior
+   * @param removeOptions.deleteFromStorage - Controls whether to delete the file from remote storage:
+   *   - `"always"` (default): Always delete from storage if the file has a remoteUrl
+   *   - `"never"`: Never delete from storage, only remove from local state
+   *   - `"local-only"`: Only delete files that were uploaded in this session (source === "local"),
+   *     preserving files that were loaded from storage via initializeExistingFiles
+   */
+  const removeFile = async (fileId: string, removeOptions?: { deleteFromStorage?: "always" | "never" | "local-only" }) => {
+    const { deleteFromStorage = "always" } = removeOptions ?? {}
     const file = files.value.find((f) => f.id === fileId)
 
     if (!file) return
 
+    // Determine if we should delete from storage based on the deleteFromStorage option
+    let shouldDelete: boolean
+    switch (deleteFromStorage) {
+      case "always":
+        shouldDelete = true
+        break
+      case "never":
+        shouldDelete = false
+        break
+      case "local-only":
+        // Only delete files that were uploaded in this session, not pre-loaded from storage
+        shouldDelete = file.source === "local"
+        break
+    }
+
     // Only call storage plugin's remove hook if:
-    // - deleteFromStorage is true (default)
+    // - shouldDelete is true
     // - file has a remoteUrl (indicates it exists in remote storage)
     // This applies to both:
     // - Local files that were uploaded (source: 'local', remoteUrl set after upload)
     // - Remote files (source: 'storage' | 'instagram' | etc., remoteUrl set from initialization)
-    if (deleteFromStorage && file.remoteUrl) {
+    if (shouldDelete && file.remoteUrl) {
       const storagePlugin = getStoragePlugin()
       if (storagePlugin?.hooks.remove) {
         try {

test/unit/useUploadKit.test.ts

@@ -182,7 +182,7 @@ describe("useUploadKit", () => {
       expect(uploader.files.value).toHaveLength(1)
     })
 
-    it("should call storage plugin remove hook by default for files with remoteUrl", async () => {
+    it("should call storage plugin remove hook by default (deleteFromStorage: 'always')", async () => {
       const removeHook = vi.fn()
       const storagePlugin: StoragePlugin = {
         id: "test-storage",
@@ -212,7 +212,7 @@ describe("useUploadKit", () => {
       expect(uploader.files.value).toHaveLength(0)
     })
 
-    it("should skip storage plugin remove hook when deleteFromStorage is false", async () => {
+    it("should skip storage plugin remove hook when deleteFromStorage is 'never'", async () => {
       const removeHook = vi.fn()
       const storagePlugin: StoragePlugin = {
         id: "test-storage",
@@ -232,12 +232,55 @@ describe("useUploadKit", () => {
       // Add a remote file using initializeExistingFiles
       await uploader.initializeExistingFiles([{ id: "remote-1" }])
 
-      await uploader.removeFile("remote-1", { deleteFromStorage: false })
+      await uploader.removeFile("remote-1", { deleteFromStorage: "never" })
 
       expect(removeHook).not.toHaveBeenCalled()
       expect(uploader.files.value).toHaveLength(0)
     })
 
+    it("should only delete local uploads when deleteFromStorage is 'local-only'", async () => {
+      const removeHook = vi.fn()
+      const uploadHook = vi.fn().mockResolvedValue({
+        url: "https://storage.example.com/uploaded.jpg",
+        storageKey: "uploaded.jpg",
+      })
+      const storagePlugin: StoragePlugin = {
+        id: "test-storage",
+        hooks: {
+          upload: uploadHook,
+          remove: removeHook,
+          getRemoteFile: vi.fn().mockResolvedValue({
+            size: 1024,
+            mimeType: "image/jpeg",
+            remoteUrl: "https://storage.example.com/existing.jpg",
+          }),
+        },
+      }
+
+      const uploader = useUploadKit({ storage: storagePlugin })
+
+      // Add a remote file (source: "storage") - simulates pre-populated file
+      await uploader.initializeExistingFiles([{ id: "existing-file" }])
+
+      // Add and upload a local file (source: "local")
+      await uploader.addFile(createMockFile("new-upload.jpg"))
+      const localFileId = uploader.files.value.find((f) => f.source === "local")!.id
+
+      // Upload to set remoteUrl
+      await uploader.upload()
+
+      expect(uploader.files.value).toHaveLength(2)
+
+      // Remove the pre-populated file with "local-only" - should NOT delete from storage
+      await uploader.removeFile("existing-file", { deleteFromStorage: "local-only" })
+      expect(removeHook).not.toHaveBeenCalled()
+
+      // Remove the locally uploaded file with "local-only" - SHOULD delete from storage
+      await uploader.removeFile(localFileId, { deleteFromStorage: "local-only" })
+      expect(removeHook).toHaveBeenCalledTimes(1)
+      expect(removeHook).toHaveBeenCalledWith(expect.objectContaining({ source: "local" }), expect.any(Object))
+    })
+
     it("should not call storage plugin remove hook for files without remoteUrl", async () => {
       const removeHook = vi.fn()
       const storagePlugin: StoragePlugin = {
@@ -252,6 +295,7 @@ describe("useUploadKit", () => {
       await uploader.addFile(createMockFile("local.jpg"))
       const fileId = uploader.files.value[0]!.id
 
+      // File hasn't been uploaded yet, so no remoteUrl
       await uploader.removeFile(fileId)
 
       // Should not call remove hook since file doesn't have remoteUrl yet