@pylonsync/client 0.22.47 → 0.22.50

package/dist/components/FileUpload.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
 import { type ReactNode } from "react";
-import { type FileVisibility, type UploadedFile } from "@pylonsync/react";
+import { type FileVisibility, type QueuedUploadHandle, type UploadAttachTarget, type UploadedFile } from "@pylonsync/react";
 export interface FileUploadProps {
     /** Called once for each successfully uploaded file. */
     onUploaded?: (file: UploadedFile, source: File) => void;
@@ -17,6 +17,19 @@ export interface FileUploadProps {
      * only. "public": anyone, for content every visitor sees.
      */
     visibility?: FileVisibility;
+    /**
+     * Keep each file on the device and upload it when there is a network
+     * (`queueUpload`), instead of uploading now. Needs `attach`.
+     */
+    offline?: boolean;
+    /**
+     * With `offline`: the record each file belongs to and the field that
+     * gets its id (and `urlField`, its URL). A function is called once per
+     * file, for example to insert a row per photo and return its target.
+     */
+    attach?: UploadAttachTarget | ((file: File) => UploadAttachTarget | Promise<UploadAttachTarget>);
+    /** With `offline`: called once for each file kept on the device. */
+    onQueued?: (queued: QueuedUploadHandle, source: File) => void;
     /** Override the headline. */
     label?: ReactNode;
     /** Override the helper text. */
@@ -28,14 +41,20 @@ export interface FileUploadResult {
     status: "ok" | "error";
     uploaded?: UploadedFile;
     error?: string;
+    /** With `offline`: the queued upload. */
+    queued?: QueuedUploadHandle;
 }
 /**
  * Drop-in drag-and-drop file picker. Uploads each file with `uploadFile`
  * (init, PUT, confirm), shows per-file progress and errors, and emits
  * `onUploaded` as each file lands.
  *
+ * With `offline` and `attach`, each file is kept on the device with
+ * `queueUpload` and shown from there at once; it uploads when there is a
+ * network and is then set on its record.
+ *
  * Pure UI shell — no provider configuration of its own. Pylon's file
  * router handles where bytes actually go (local disk for self-host,
  * Stack0 / S3 for cloud).
  */
-export declare function FileUpload({ onUploaded, onComplete, accept, multiple, maxSizeBytes, visibility, label, helperText, className, }: FileUploadProps): React.JSX.Element;
+export declare function FileUpload({ onUploaded, onComplete, accept, multiple, maxSizeBytes, visibility, offline, attach, onQueued, label, helperText, className, }: FileUploadProps): React.JSX.Element;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.22.47",
+  "version": "0.22.50",
   "type": "module",
   "main": "src/index.ts",
   "types": "./dist/index.d.ts",
@@ -17,18 +17,24 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "check": "tsc -p tsconfig.json --noEmit",
-    "prepack": "bun run build"
+    "prepack": "bun run build",
+    "test": "bun test"
   },
   "dependencies": {
-    "@pylonsync/react": "0.22.47",
-    "@pylonsync/sync": "0.22.47",
+    "@pylonsync/react": "0.22.50",
+    "@pylonsync/sync": "0.22.50",
     "clsx": "^2.1.1"
   },
   "peerDependencies": {
     "react": ">=19.0.0"
   },
   "devDependencies": {
-    "@types/react": "^19.0.0"
+    "@happy-dom/global-registrator": "^20.10.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "files": [
     "src",

package/src/components/FileUpload.offline.test.tsx

@@ -0,0 +1,70 @@
+// <FileUpload offline attach>: each file is kept on the device and shown
+// from there at once, set on its record, and uploaded when there is a
+// network.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { db, init } from "@pylonsync/react";
+import { createTestEnv, type TestEnv } from "@pylonsync/sync/src/test-harness";
+
+import { FileUpload } from "./FileUpload";
+
+let env: TestEnv | null = null;
+afterEach(async () => {
+	cleanup();
+	if (env) {
+		await env.dispose();
+		env = null;
+	}
+});
+
+describe("FileUpload offline", () => {
+	test("queues each file, shows it from the device, and attaches it once uploaded", async () => {
+		env = createTestEnv({ transport: "poll" });
+		env.signIn({ userId: "rep1" });
+		env.server.seed("Photo", [{ id: "p1", fileId: null, url: null }]);
+		// The component reads the default engine: point it at the harness.
+		init({
+			baseUrl: "http://test.invalid",
+			appName: "harness",
+			persist: false,
+			multiTab: false,
+			transport: "poll",
+			storage: (env.engine as unknown as { storage: never }).storage,
+		});
+		await db.sync.start();
+		// Hold the upload so the waiting stage is observable.
+		let release!: () => void;
+		env.server.files.putGate = new Promise<void>((r) => (release = r));
+
+		const queued: string[] = [];
+		const { container } = render(
+			<FileUpload
+				offline
+				accept="image/*"
+				attach={{ entity: "Photo", id: "p1", field: "fileId", urlField: "url" }}
+				onQueued={(q) => queued.push(q.ref)}
+			/>,
+		);
+		const input = container.querySelector("input[type=file]") as HTMLInputElement;
+		const file = new File([new Uint8Array(32)], "gutter.jpg", { type: "image/jpeg" });
+		await act(async () => {
+			fireEvent.change(input, { target: { files: [file] } });
+		});
+		await waitFor(() => expect(queued).toHaveLength(1));
+		// The record holds the local reference and the picker shows the copy.
+		expect(db.sync.store.get("Photo", "p1")).toMatchObject({ fileId: queued[0], url: queued[0] });
+		expect(screen.getByText("Waiting to upload")).toBeTruthy();
+		expect(container.querySelector("img")?.getAttribute("src")).toMatch(/^blob:/);
+
+		env.server.files.putGate = null;
+		await act(async () => {
+			release();
+		});
+		await waitFor(() => expect(screen.getByText("Uploaded")).toBeTruthy());
+		await waitFor(() =>
+			expect(db.sync.store.get("Photo", "p1")).toMatchObject({ fileId: "f_1", url: "/api/files/f_1" }),
+		);
+		db.sync.stop();
+	});
+});

package/src/components/FileUpload.tsx

@@ -9,7 +9,15 @@ import {
 	useRef,
 	useState,
 } from "react";
-import { uploadFile, type FileVisibility, type UploadedFile } from "@pylonsync/react";
+import {
+	queueUpload,
+	uploadFile,
+	useOutbox,
+	type FileVisibility,
+	type QueuedUploadHandle,
+	type UploadAttachTarget,
+	type UploadedFile,
+} from "@pylonsync/react";
 import { cn } from "../lib/cn";
 
 export interface FileUploadProps {
@@ -28,6 +36,21 @@ export interface FileUploadProps {
 	 * only. "public": anyone, for content every visitor sees.
 	 */
 	visibility?: FileVisibility;
+	/**
+	 * Keep each file on the device and upload it when there is a network
+	 * (`queueUpload`), instead of uploading now. Needs `attach`.
+	 */
+	offline?: boolean;
+	/**
+	 * With `offline`: the record each file belongs to and the field that
+	 * gets its id (and `urlField`, its URL). A function is called once per
+	 * file, for example to insert a row per photo and return its target.
+	 */
+	attach?:
+		| UploadAttachTarget
+		| ((file: File) => UploadAttachTarget | Promise<UploadAttachTarget>);
+	/** With `offline`: called once for each file kept on the device. */
+	onQueued?: (queued: QueuedUploadHandle, source: File) => void;
 	/** Override the headline. */
 	label?: ReactNode;
 	/** Override the helper text. */
@@ -40,6 +63,8 @@ export interface FileUploadResult {
 	status: "ok" | "error";
 	uploaded?: UploadedFile;
 	error?: string;
+	/** With `offline`: the queued upload. */
+	queued?: QueuedUploadHandle;
 }
 
 /**
@@ -47,6 +72,10 @@ export interface FileUploadResult {
  * (init, PUT, confirm), shows per-file progress and errors, and emits
  * `onUploaded` as each file lands.
  *
+ * With `offline` and `attach`, each file is kept on the device with
+ * `queueUpload` and shown from there at once; it uploads when there is a
+ * network and is then set on its record.
+ *
  * Pure UI shell — no provider configuration of its own. Pylon's file
  * router handles where bytes actually go (local disk for self-host,
  * Stack0 / S3 for cloud).
@@ -58,6 +87,9 @@ export function FileUpload({
 	multiple,
 	maxSizeBytes,
 	visibility,
+	offline,
+	attach,
+	onQueued,
 	label = "Drop files to upload",
 	helperText = "or click to browse",
 	className,
@@ -86,6 +118,30 @@ export function FileUpload({
 				initial.map(async (entry) => {
 					if (entry.status === "error") return entry;
 					try {
+						if (offline) {
+							if (!attach) throw new Error("FileUpload offline needs attach");
+							const target =
+								typeof attach === "function" ? await attach(entry.file) : attach;
+							const queued = await queueUpload(entry.file, {
+								attach: target,
+								visibility,
+							});
+							onQueued?.(queued, entry.file);
+							const result: FileUploadResult = { ...entry, queued };
+							queued.done.then(
+								(uploaded) => {
+									// Also seen by the batch update below when the
+									// upload beats it.
+									result.uploaded = uploaded;
+									onUploaded?.(uploaded, entry.file);
+									setItems((prev) =>
+										prev.map((r) => (r.file === entry.file ? { ...r, uploaded } : r)),
+									);
+								},
+								() => {},
+							);
+							return result;
+						}
 						const uploaded = await uploadFile(entry.file, { visibility });
 						onUploaded?.(uploaded, entry.file);
 						return { ...entry, uploaded } satisfies FileUploadResult;
@@ -110,7 +166,7 @@ export function FileUpload({
 			});
 			onComplete?.(settled);
 		},
-		[maxSizeBytes, onComplete, onUploaded, visibility],
+		[attach, maxSizeBytes, offline, onComplete, onQueued, onUploaded, visibility],
 	);
 
 	function onDrop(e: DragEvent<HTMLDivElement>) {
@@ -170,7 +226,14 @@ export function FileUpload({
 							key={`${item.file.name}-${i}`}
 							className="flex items-center justify-between gap-3 px-3 py-2 text-sm"
 						>
-							<span className="min-w-0">
+							{item.queued?.localUrl && item.file.type.startsWith("image/") ? (
+								<img
+									src={item.queued.localUrl}
+									alt=""
+									className="h-10 w-10 flex-none rounded object-cover"
+								/>
+							) : null}
+							<span className="min-w-0 flex-1">
 								<span className="block truncate font-medium text-[var(--pylon-ink,#0a0a0a)]">
 									{item.file.name}
 								</span>
@@ -188,7 +251,30 @@ export function FileUpload({
 	);
 }
 
+function QueuedStatus({ result }: { result: FileUploadResult }) {
+	const { failed } = useOutbox();
+	const failure = failed.find((f) => f.id === result.queued?.localId);
+	if (failure) {
+		return (
+			<span
+				title={failure.error}
+				className="rounded-md bg-[var(--pylon-error-bg,#fef2f2)] px-2 py-0.5 text-[11px] font-medium text-[var(--pylon-error-ink,#b91c1c)]"
+			>
+				Failed
+			</span>
+		);
+	}
+	return (
+		<span className="text-[11px] text-[var(--pylon-ink-3,#71717a)]">
+			Waiting to upload
+		</span>
+	);
+}
+
 function UploadStatus({ result }: { result: FileUploadResult }) {
+	if (result.queued && !result.uploaded && result.status !== "error") {
+		return <QueuedStatus result={result} />;
+	}
 	if (result.uploaded) {
 		return (
 			<span className="rounded-md bg-[var(--pylon-paper-2,#f4f4f5)] px-2 py-0.5 text-[11px] font-medium text-[var(--pylon-ink-2,#52525b)]">