uploaderkit 1.0.0 → 2.0.0

package/dist/useUploader-CQHpj_oI.d.ts

@@ -0,0 +1,117 @@
+import { o as StoredFile, p as UploadStatus, d as ScopeConfig, e as ScopeRegistry, U as UploaderLabels } from './types-BSlJJwti.js';
+
+/** Signals the strategy receives while a file is in flight. */
+type UploadStrategyOptions = {
+    /** 0–100. Driven by the transport when it can measure (XHR can). */
+    onProgress: (percent: number) => void;
+    /** Aborting must reject the promise with an `AbortError`-named error. */
+    signal: AbortSignal;
+};
+/**
+ * Deletes one persisted object from storage. The uploaders run it themselves
+ * on a confirmed removal — unless the scope is marked `keepOnRemove`, the
+ * history contract — so a consumer that wires a strategy can no longer orphan
+ * by forgetting a callback. Resolve `false` when the server refused.
+ */
+type RemoveStrategy = (stored: StoredFile, scope: string, entityId: string) => Promise<boolean>;
+/**
+ * The physical transport for one file. Injected into `useUploader` so the hook
+ * owns state and validation while the app owns how bytes travel — swap the
+ * endpoint, the auth header or the whole protocol without touching the hook.
+ */
+type UploadStrategy = (file: File, scope: string, entityId: string, options: UploadStrategyOptions) => Promise<StoredFile>;
+/** One file tracked by the hook, from selection to stored (or failed). */
+type UploaderFile = {
+    id: string;
+    file: File;
+    status: UploadStatus;
+    /** 0–100 while uploading; 100 on success. */
+    progress: number;
+    /** Human, Spanish — comes from validation or the strategy's failure. */
+    error?: string;
+    /** Object URL for image files, for a local thumbnail before upload. */
+    preview?: string;
+    /** Present once the server confirmed the upload. */
+    stored?: StoredFile;
+};
+
+/**
+ * When the machine sends: `'manual'` holds files in `idle` until the app calls
+ * `upload()` — the form-submit flow, where the file travels together with the
+ * rest of the fields' action. `'select'` fires as soon as a valid file lands.
+ */
+type UploadTrigger = 'select' | 'manual';
+type RetryOptions = {
+    /** Total attempts per file, the first one included. @defaultValue 1 */
+    attempts?: number;
+    /** Delay before the first retry; doubles on each further one. @defaultValue 500 */
+    backoffMs?: number;
+};
+type UseUploaderOptions<T extends Record<string, ScopeConfig>> = {
+    /** The app's registry — the same object the server authorizes against. */
+    scopes: ScopeRegistry<T>;
+    scope: keyof T & string;
+    /** Owner of the uploads (customerId, userId, …), forwarded to the strategy. */
+    entityId: string;
+    /** Transport. Omit for local-only selection + validation (no `upload`). */
+    strategy?: UploadStrategy;
+    /**
+     * Overrides the arity derived from the scope's `maxFiles`. Rarely needed:
+     * the registry is what the server validates against.
+     */
+    multiple?: boolean;
+    /** Overrides the scope's own `maxFiles`, downward. */
+    maxFiles?: number;
+    /** @defaultValue 'manual' — the styled `Uploader` flips it to `'select'`. */
+    uploadOn?: UploadTrigger;
+    /**
+     * Fired when a batch actually starts travelling — from either trigger — with
+     * the files it carries. The place to flip a form into its "sending" state.
+     */
+    onUploadStart?: (files: UploaderFile[]) => void;
+    /** Fired once per batch with the files the server confirmed. */
+    onUploaded?: (stored: StoredFile[]) => void;
+    onError?: (message: string) => void;
+    /**
+     * Re-run a failed strategy call before surfacing the error. A number is
+     * shorthand for `{ attempts }`. Aborts never retry, and validation failures
+     * never reach the strategy in the first place.
+     */
+    retry?: number | RetryOptions;
+    /** Max uploads in flight per batch; the rest queue. @defaultValue Infinity */
+    concurrency?: number;
+    /**
+     * Rename each file before it enters the machine — a client-side input, a
+     * folio, a slug. Runs before validation, so a rename that changes the
+     * extension is rejected like any other invalid file. The stored key comes
+     * from the scope's `path(entityId, file)`, which reads this name.
+     */
+    rename?: (file: File) => string;
+    labels?: Partial<UploaderLabels>;
+};
+type UseUploaderReturn = {
+    files: UploaderFile[];
+    /** Ready-made value for `<input accept>`, derived from the scope. */
+    accept: string;
+    isUploading: boolean;
+    /** `true` while any file waits in `idle` — a manual trigger has work to do. */
+    hasPending: boolean;
+    addFiles: (incoming: FileList | File[]) => Promise<void>;
+    /** Uploads every file still in `idle`. Resolves with the confirmed ones. */
+    upload: () => Promise<StoredFile[]>;
+    /** Abort one in-flight upload, or all of them when no id is given. */
+    abort: (id?: string) => void;
+    removeFile: (id: string) => void;
+    clear: () => void;
+};
+/**
+ * Headless upload state machine: selection → validation → (compression) →
+ * upload with progress and abort. Owns no markup — render `files` however the
+ * screen needs and wire `addFiles` to an input or a drop zone.
+ *
+ * Validation runs here with the same `validateForScope` the server runs, so
+ * the user sees the rejection before any byte leaves the machine.
+ */
+declare const useUploader: <T extends Record<string, ScopeConfig>>({ scopes, scope, entityId, strategy, multiple: multipleOption, maxFiles: maxFilesOption, uploadOn, onUploadStart, onUploaded, onError, retry, concurrency, rename, labels, }: UseUploaderOptions<T>) => UseUploaderReturn;
+
+export { type RemoveStrategy as R, type UseUploaderOptions as U, type UploadStrategy as a, type RetryOptions as b, type UploadStrategyOptions as c, type UploadTrigger as d, type UploaderFile as e, type UseUploaderReturn as f, useUploader as u };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "uploaderkit",
-	"version": "1.0.0",
+	"version": "2.0.0",
 	"description": "One upload contract for every storage provider — scope registry, isomorphic validation, headless React and a server router.",
 	"keywords": [
 		"upload",
@@ -35,7 +35,9 @@
 	},
 	"files": [
 		"dist",
+		"tailwind.css",
 		"README.md",
+		"README.es.md",
 		"LICENSE",
 		"NOTICE"
 	],
@@ -53,6 +55,97 @@
 				"default": "./dist/index.cjs"
 			}
 		},
+		"./react": {
+			"import": {
+				"types": "./dist/react.d.ts",
+				"default": "./dist/react.js"
+			},
+			"require": {
+				"types": "./dist/react.d.cts",
+				"default": "./dist/react.cjs"
+			}
+		},
+		"./server": {
+			"import": {
+				"types": "./dist/server.d.ts",
+				"default": "./dist/server.js"
+			},
+			"require": {
+				"types": "./dist/server.d.cts",
+				"default": "./dist/server.cjs"
+			}
+		},
+		"./server/express": {
+			"import": {
+				"types": "./dist/server/express.d.ts",
+				"default": "./dist/server/express.js"
+			},
+			"require": {
+				"types": "./dist/server/express.d.cts",
+				"default": "./dist/server/express.cjs"
+			}
+		},
+		"./server/next": {
+			"import": {
+				"types": "./dist/server/next.d.ts",
+				"default": "./dist/server/next.js"
+			},
+			"require": {
+				"types": "./dist/server/next.d.cts",
+				"default": "./dist/server/next.cjs"
+			}
+		},
+		"./adapters/memory": {
+			"import": {
+				"types": "./dist/adapters/memory.d.ts",
+				"default": "./dist/adapters/memory.js"
+			},
+			"require": {
+				"types": "./dist/adapters/memory.d.cts",
+				"default": "./dist/adapters/memory.cjs"
+			}
+		},
+		"./adapters/gcs": {
+			"import": {
+				"types": "./dist/adapters/gcs.d.ts",
+				"default": "./dist/adapters/gcs.js"
+			},
+			"require": {
+				"types": "./dist/adapters/gcs.d.cts",
+				"default": "./dist/adapters/gcs.cjs"
+			}
+		},
+		"./ui": {
+			"import": {
+				"types": "./dist/ui.d.ts",
+				"default": "./dist/ui.js"
+			},
+			"require": {
+				"types": "./dist/ui.d.cts",
+				"default": "./dist/ui.cjs"
+			}
+		},
+		"./presets": {
+			"import": {
+				"types": "./dist/presets.d.ts",
+				"default": "./dist/presets.js"
+			},
+			"require": {
+				"types": "./dist/presets.d.cts",
+				"default": "./dist/presets.cjs"
+			}
+		},
+		"./adapters/s3": {
+			"import": {
+				"types": "./dist/adapters/s3.d.ts",
+				"default": "./dist/adapters/s3.js"
+			},
+			"require": {
+				"types": "./dist/adapters/s3.d.cts",
+				"default": "./dist/adapters/s3.cjs"
+			}
+		},
+		"./tailwind.css": "./tailwind.css",
 		"./package.json": "./package.json"
 	},
 	"scripts": {
@@ -65,18 +158,111 @@
 		"size": "size-limit",
 		"size:why": "size-limit --why",
 		"check:publish": "publint",
-		"docs": "typedoc"
+		"docs": "typedoc",
+		"check:types": "attw --pack . --exclude-entrypoints ./tailwind.css"
 	},
 	"size-limit": [
 		{
 			"name": "core (index)",
 			"path": "dist/index.js",
 			"limit": "6 kB"
+		},
+		{
+			"name": "react",
+			"path": "dist/react.js",
+			"limit": "9 kB",
+			"ignore": [
+				"react",
+				"react-dom"
+			]
+		},
+		{
+			"name": "ui",
+			"path": "dist/ui.js",
+			"limit": "17 kB",
+			"ignore": [
+				"react",
+				"react-dom"
+			]
+		},
+		{
+			"name": "presets",
+			"path": "dist/presets.js",
+			"limit": "14 kB",
+			"ignore": [
+				"react",
+				"react-dom"
+			]
 		}
 	],
 	"devDependencies": {
+		"@aws-sdk/client-s3": "^3.1109.0",
+		"@aws-sdk/s3-request-presigner": "^3.1109.0",
+		"@google-cloud/storage": "^7.22.0",
+		"@testing-library/react": "^16.3.2",
+		"@types/node": "^26.2.0",
+		"@types/react": "^18.3.12",
+		"happy-dom": "^20.11.2",
+		"react": "^18.3.1",
+		"react-dom": "^18.3.1",
 		"tsup": "^8.5.0",
 		"typescript": "^5.9.3",
-		"vitest": "^3.2.4"
+		"vitest": "^3.2.4",
+		"@types/react-dom": "^18.3.1"
+	},
+	"typesVersions": {
+		"*": {
+			"react": [
+				"./dist/react.d.ts"
+			],
+			"server": [
+				"./dist/server.d.ts"
+			],
+			"server/express": [
+				"./dist/server/express.d.ts"
+			],
+			"server/next": [
+				"./dist/server/next.d.ts"
+			],
+			"adapters/memory": [
+				"./dist/adapters/memory.d.ts"
+			],
+			"adapters/gcs": [
+				"./dist/adapters/gcs.d.ts"
+			],
+			"ui": [
+				"./dist/ui.d.ts"
+			],
+			"presets": [
+				"./dist/presets.d.ts"
+			],
+			"adapters/s3": [
+				"./dist/adapters/s3.d.ts"
+			]
+		}
+	},
+	"peerDependencies": {
+		"@aws-sdk/client-s3": ">=3",
+		"@aws-sdk/s3-request-presigner": ">=3",
+		"@google-cloud/storage": ">=7",
+		"react": ">=18",
+		"react-dom": ">=18"
+	},
+	"peerDependenciesMeta": {
+		"@aws-sdk/client-s3": {
+			"optional": true
+		},
+		"@aws-sdk/s3-request-presigner": {
+			"optional": true
+		},
+		"@google-cloud/storage": {
+			"optional": true
+		},
+		"react": {
+			"optional": true
+		},
+		"react-dom": {
+			"optional": true
+		}
 	}
 }

package/tailwind.css

@@ -0,0 +1,80 @@
+/*
+ * uploaderkit — Tailwind v4 entry.
+ *
+ * Consumers add, in this order:
+ *   @import 'tailwindcss';
+ *   @import 'uploaderkit/tailwind.css';
+ *
+ * `@source` registers the compiled output so the utilities the components use
+ * are generated by the consumer's own Tailwind build.
+ *
+ * `@theme` declares DEFAULTS only. Every token is a CSS variable, so an app
+ * rebrands the whole styled layer by redeclaring the ones it cares about:
+ *
+ *   :root {
+ *     --color-ui-primary: #c41e3a;
+ *     --color-ui-primary-hover: #8b1529;
+ *   }
+ */
+
+@source './dist/ui.js';
+@source './dist/ui.cjs';
+
+@theme {
+	/* Surfaces */
+	--color-ui-surface: #ffffff;
+	--color-ui-surface-subtle: #fafafa;
+	--color-ui-surface-muted: #f4f4f5;
+
+	/* Text */
+	--color-ui-fg: #111827;
+	--color-ui-muted: #6b7280;
+	--color-ui-placeholder: #9ca3af;
+
+	/* Borders & focus */
+	--color-ui-border: #e5e7eb;
+	--color-ui-border-strong: #d1d5db;
+	--color-ui-ring: #93c5fd;
+
+	/* Primary action */
+	--color-ui-primary: #2563eb;
+	--color-ui-primary-hover: #1d4ed8;
+	--color-ui-primary-fg: #ffffff;
+	--color-ui-primary-soft: #eff6ff;
+	--color-ui-primary-soft-fg: #1d4ed8;
+
+	/* Semantic — danger */
+	--color-ui-danger: #dc2626;
+	--color-ui-danger-hover: #b91c1c;
+	--color-ui-danger-fg: #ffffff;
+	--color-ui-danger-soft: #fef2f2;
+	--color-ui-danger-soft-fg: #b91c1c;
+
+	/* Semantic — success */
+	--color-ui-success: #16a34a;
+	--color-ui-success-soft: #f0fdf4;
+
+	/* Semantic — warning */
+	--color-ui-warning: #d97706;
+	--color-ui-warning-soft: #fffbeb;
+
+	/* Overlay scrim behind the viewer and dialogs */
+	--color-ui-overlay: oklch(0.28 0.03 265 / 0.45);
+
+	/* Control radii */
+	--radius-ui: 0.5rem;
+	--radius-ui-lg: 0.75rem;
+	--radius-ui-xl: 1rem;
+
+	/* Motion */
+	--animate-ui-fade-in: ui-fade-in 200ms ease-out;
+}
+
+@keyframes ui-fade-in {
+	from {
+		opacity: 0;
+	}
+	to {
+		opacity: 1;
+	}
+}