@uploadbox/react 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,211 @@
+# @uploadbox/react
+
+React components and hooks for Uploadbox — `UploadButton`, `UploadDropzone`, and `useUploadbox`.
+
+[![npm](https://img.shields.io/npm/v/@uploadbox/react)](https://www.npmjs.com/package/@uploadbox/react)
+[![license](https://img.shields.io/npm/l/@uploadbox/react)](./LICENSE)
+
+## Installation
+
+```bash
+npm i @uploadbox/react @uploadbox/core
+```
+
+**Peer dependencies:** React 18 or 19.
+
+## Quick Start
+
+### 1. Wrap your app with the provider
+
+```tsx
+import { UploadboxProvider } from "@uploadbox/react";
+import "@uploadbox/react/styles.css";
+
+export default function App({ children }) {
+  return (
+    <UploadboxProvider apiUrl="/api/uploadbox">
+      {children}
+    </UploadboxProvider>
+  );
+}
+```
+
+### 2. Add an upload component
+
+```tsx
+import { UploadButton, UploadDropzone } from "@uploadbox/react";
+
+function MyPage() {
+  return (
+    <>
+      <UploadButton
+        endpoint="imageUploader"
+        onClientUploadComplete={(files) => console.log("Uploaded:", files)}
+        onUploadError={(err) => console.error(err)}
+      />
+
+      <UploadDropzone
+        endpoint="imageUploader"
+        onClientUploadComplete={(files) => console.log("Uploaded:", files)}
+        onUploadError={(err) => console.error(err)}
+      />
+    </>
+  );
+}
+```
+
+## `useUploadbox` Hook
+
+For full control, use the hook directly:
+
+```tsx
+import { useUploadbox } from "@uploadbox/react";
+
+function CustomUploader() {
+  const {
+    startUpload,   // (files: File[]) => Promise<UploadedFile[]>
+    isUploading,   // boolean
+    progress,      // 0–100
+    fileProgress,  // FileProgress[] — per-file details
+    routeConfig,   // fetched route constraints
+    abort,         // cancel current upload
+  } = useUploadbox("imageUploader", {
+    onClientUploadComplete: (files) => console.log(files),
+    onUploadError: (err) => console.error(err),
+    onUploadProgress: (e) => {
+      console.log(`Overall: ${e.percent}%`);
+      e.fileProgress.forEach((f) => {
+        console.log(`${f.name}: ${f.percent}% — ${f.speed} B/s, ETA ${f.eta}s`);
+      });
+    },
+  });
+
+  return (
+    <div>
+      <input type="file" multiple onChange={(e) => startUpload([...e.target.files!])} />
+      {isUploading && <p>Uploading... {progress}%</p>}
+      <button onClick={abort} disabled={!isUploading}>Cancel</button>
+    </div>
+  );
+}
+```
+
+### Per-File Progress
+
+Each entry in `fileProgress` contains:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | File name |
+| `status` | `string` | `"pending"` \| `"uploading"` \| `"retrying"` \| `"complete"` \| `"error"` |
+| `percent` | `number` | 0–100 |
+| `speed` | `number` | Bytes/sec (3-second sliding window) |
+| `eta` | `number` | Estimated seconds remaining |
+| `retryCount` | `number` | Number of retries so far |
+| `error` | `string?` | Error message if failed |
+
+### Hook Options
+
+```ts
+useUploadbox("endpoint", {
+  onClientUploadComplete: (files) => {},
+  onUploadError: (err) => {},
+  onUploadProgress: (event) => {},
+  onBeforeUploadBegin: (files) => files, // transform files before upload
+  headers: { "x-custom": "value" },
+  getFileMetadata: (file) => ({ userId: "123" }),
+  ttlSeconds: 3600,
+  retry: { maxRetries: 5, initialDelayMs: 2000, backoffMultiplier: 2, maxDelayMs: 60000 },
+  // retry: false — to disable retries
+});
+```
+
+## Customization
+
+### Content Props
+
+Override default labels on built-in components:
+
+```tsx
+<UploadButton
+  endpoint="imageUploader"
+  content={{ button: "Choose Image", allowedContent: "PNG, JPG up to 4MB" }}
+/>
+
+<UploadDropzone
+  endpoint="imageUploader"
+  content={{ label: "Drop files here", button: "Browse", allowedContent: "Images up to 4MB" }}
+/>
+```
+
+### CSS Classes
+
+All components accept a `className` prop. The default styles use these classes:
+
+**Button:** `.uploadbox-button`, `.uploadbox-progress-bar`, `.uploadbox-progress-bar-fill`
+
+**Dropzone:** `.uploadbox-dropzone`, `.uploadbox-dropzone--dragover`, `.uploadbox-dropzone--uploading`, `.uploadbox-dropzone--complete`, `.uploadbox-dropzone--error`
+
+### Styles
+
+Import the default stylesheet:
+
+```ts
+import "@uploadbox/react/styles.css";
+```
+
+Or write your own — the components work without the default CSS.
+
+## Type-Safe Factories
+
+Generate components that are typed to your file router:
+
+```tsx
+import { generateUploadButton, generateUploadDropzone } from "@uploadbox/react";
+import type { AppRouter } from "@/lib/uploadbox";
+
+const UploadButton = generateUploadButton<AppRouter>();
+const UploadDropzone = generateUploadDropzone<AppRouter>();
+
+// `endpoint` is now typed to your router keys
+<UploadButton endpoint="imageUploader" />
+```
+
+## Multipart Uploads
+
+Files larger than 10 MB are automatically uploaded in parts (10 MB each, 4 concurrent). No extra configuration needed — the hook and components handle this transparently.
+
+## Retry
+
+Retries are enabled by default with exponential backoff:
+
+```ts
+// Default config
+{
+  maxRetries: 3,
+  initialDelayMs: 1000,
+  backoffMultiplier: 2,
+  maxDelayMs: 30000,
+}
+```
+
+Retryable errors: network failures, 408, 429, and 5xx responses. Disable with `retry: false`.
+
+## Hosted Mode
+
+For the Uploadbox hosted platform, pass an API key to the provider:
+
+```tsx
+<UploadboxProvider apiUrl="/api/uploadbox" apiKey="pk_live_xxx">
+  {children}
+</UploadboxProvider>
+```
+
+## Related Packages
+
+- [`@uploadbox/core`](https://www.npmjs.com/package/@uploadbox/core) — Core utilities, builder pattern, S3 operations
+- [`@uploadbox/nextjs`](https://www.npmjs.com/package/@uploadbox/nextjs) — Next.js route handler adapter
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uploadbox/react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "react-dropzone": "^14.3.0",
-    "@uploadbox/core": "0.1.0"
+    "@uploadbox/core": "0.2.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",