@muhgholy/next-drive 4.23.14 → 4.23.19

package/README.md

@@ -193,6 +193,87 @@ function MyForm() {
 
 ---
 
+## Headless Uploads
+
+Need to build your own upload UI? Use the framework-agnostic `uploadFile` / `uploadFiles` functions. They run the same chunked, retrying upload engine that powers the built-in components — without any React or UI — so you control the markup, loading states, and cancel buttons.
+
+Capabilities:
+
+-    📈 **Byte-level progress** – smooth percentage, even for small single-chunk files
+-    🪵 **Logs** – the same per-step log stream shown by `DriveFileChooser`
+-    ✋ **Cancellation** – every call returns a `cancel()` function
+-    🔓 **Anonymous** – just omit `accountId` (works with `unauthenticated` server config)
+-    📦 **Consistent result** – returns a normalized `TDriveFile` on completion
+
+### Single File
+
+```tsx
+import { uploadFile } from "@muhgholy/next-drive/client";
+
+const { id, promise, cancel } = uploadFile({
+	apiEndpoint: "/api/drive",
+	file, // a File from an <input type="file" />
+	folderId: null, // optional: target folder id (defaults to root)
+	accountId: null, // optional: omit/null = anonymous upload
+	withCredentials: false, // optional: send cookies cross-origin
+	onProgress: ({ percent, uploadedBytes, totalBytes }) => {
+		setProgress(percent); // 0–100
+	},
+	onLog: ({ type, message, timestamp }) => {
+		console.log(`[${type}] ${message}`);
+	},
+});
+
+// Call cancel() any time to abort (e.g. a Cancel button)
+// <button onClick={cancel}>Cancel</button>
+
+const result = await promise;
+if (result.status === "complete") {
+	result.file; // TDriveFile — same shape as DriveFileChooser's onChange
+	result.driveId; // server drive item id
+	result.item; // raw item (signed URL, full metadata, etc.)
+} else if (result.status === "cancelled") {
+	// upload was aborted
+} else {
+	result.error; // failure message
+}
+```
+
+### Multiple Files (with concurrency)
+
+```tsx
+import { uploadFiles } from "@muhgholy/next-drive/client";
+
+const { uploads, cancelAll, promise } = uploadFiles(files, {
+	apiEndpoint: "/api/drive",
+	concurrency: 2, // optional: max parallel uploads (default 2)
+	onProgress: ({ id, percent }) => updateRow(id, percent),
+	onFileComplete: (result) => {
+		if (result.status === "complete") addFile(result.file);
+	},
+});
+
+// uploads: one handle per file — each has its own { id, promise, cancel }
+// cancelAll(): abort everything
+
+const results = await promise; // resolves once all files settle
+```
+
+### Result Type
+
+The result is a discriminated union (no optional fields — narrow by `status`):
+
+```typescript
+type TDriveUploadResult =
+	| { id: string; status: "complete"; driveId: string; file: TDriveFile; item: unknown }
+	| { id: string; status: "cancelled"; driveId: string | null }
+	| { id: string; status: "error"; driveId: string | null; error: string };
+```
+
+> Prefer React state management? The `useUpload` hook wraps the same engine and exposes a reactive `uploads` array — see the source for `DriveUpload` for a reference implementation.
+
+---
+
 ## Express Integration
 
 Use the Express adapter instead of Next.js API routes:

package/dist/client/components/drive/upload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../../../src/client/components/drive/upload.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAwC,MAAM,OAAO,CAAC;AA8G7D,eAAO,MAAM,WAAW,GAAI,OAAO,QAAQ,CAAC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,sBAoQD,CAAC"}
+{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../../../src/client/components/drive/upload.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAwC,MAAM,OAAO,CAAC;AA8G7D,eAAO,MAAM,WAAW,GAAI,OAAO,QAAQ,CAAC;IACvC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,sBAoQD,CAAC"}

package/dist/client/hooks/use-upload.d.ts

@@ -2,7 +2,7 @@ import type { TDriveUploadState } from '../../types/client';
 export declare const useUpload: (apiEndpoint: string, activeAccountId: string | null, withCredentials?: boolean, onUploadComplete?: (item: unknown) => void) => {
     uploads: TDriveUploadState[];
     uploadFiles: (files: File[], folderId: string | null) => Promise<void>;
-    cancelUpload: (id: string) => Promise<void>;
+    cancelUpload: (id: string) => void;
     cancelAllUploads: () => Promise<void>;
 };
 //# sourceMappingURL=use-upload.d.ts.map

package/dist/client/hooks/use-upload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-upload.d.ts","sourceRoot":"","sources":["../../../src/client/hooks/use-upload.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAYxD,eAAO,MAAM,SAAS,GAAI,aAAa,MAAM,EAAE,iBAAiB,MAAM,GAAG,IAAI,EAAE,kBAAiB,OAAe,EAAE,mBAAmB,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI;;yBAkKzG,IAAI,EAAE,YAAY,MAAM,GAAG,IAAI;uBAuB9D,MAAM;;CA+CxB,CAAC"}
+{"version":3,"file":"use-upload.d.ts","sourceRoot":"","sources":["../../../src/client/hooks/use-upload.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAMxD,eAAO,MAAM,SAAS,GAAI,aAAa,MAAM,EAAE,iBAAiB,MAAM,GAAG,IAAI,EAAE,kBAAiB,OAAe,EAAE,mBAAmB,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI;;yBA0DzG,IAAI,EAAE,YAAY,MAAM,GAAG,IAAI;uBAsBpE,MAAM;;CA6BlB,CAAC"}