"use client"; import * as React from "react"; import { motion, AnimatePresence, type Transition } from "motion/react"; import { cn } from "@/lib/utils"; import { useReducedMotion, useDisclosure, useCopy, statusVars, type StatusTone, } from "@/lib/motiq"; /* -------------------------------------------------------------------------- * FileUploadPipeline — a presentation-only view of an upload queue with * per-item progress, pause/resume, retry, cancel, processing stages, and * partial-failure handling. It is the *panel*, not the *uploader*. * * The host APPLICATION owns uploading. This component never opens an XHR/fetch, * never reads a File body, and never advances `progress` on its own — it renders * the `items` it is given and calls back (`onPause`, `onRetry`, `onAddFiles`, …) * so the app can drive the real transfer (or drive nothing, in a static demo). * There is no built-in adapter; wiring the component to a transport is the app's * job. This keeps it transport-agnostic (fetch, XHR, tus, S3 multipart, RSC * actions) and SSR-safe. * * Accessibility is first-class: a real `` integration point * plus a keyboard-accessible Browse button as the drop-zone alternative; every * in-flight item exposes `role="progressbar"` with `aria-valuenow/min/max` and a * text `aria-valuetext`; status is always conveyed with an icon AND text (never * colour alone); errors are associated to their row via `aria-describedby`; and * the polite live region announces STATUS TRANSITIONS ONLY — never per-percent — * so a screen reader isn't flooded during a transfer. Under * `prefers-reduced-motion` rows appear without offset and progress bars snap. * Clean-room original. * * PERFORMANCE. The component performs no per-frame React state updates: bar * width is set from the app-supplied `progress` and eased purely in CSS, so a * fast upload does not re-render React 60×/s (the app should throttle its own * `progress` writes to a few per second). THUMBNAIL CLEANUP is the app's * responsibility — if you pass `thumbnail` as an `URL.createObjectURL(...)` * blob URL, revoke it when the item leaves `items` (this component does not, * because it did not create the URL). For very large queues (hundreds of * concurrent items) wrap the list in your own virtualizer — this component * renders every item it is given. * ----------------------------------------------------------------------- */ /** Lifecycle of a single file, owned entirely by the application. */ export type UploadStatus = | "queued" | "preparing" | "uploading" | "paused" | "processing" | "completed" | "failed" | "cancelled"; export interface UploadItem { /** Stable id, unique within the queue. Drives keys, focus, and callbacks. */ id: string; /** Display name of the file. */ fileName: string; /** MIME type or a coarse family ("image/png", "application/pdf", "video"). */ fileType: string; /** Size in bytes. Rendered human-readable; also used for the aggregate. */ fileSize: number; /** Transfer progress 0–100, supplied and advanced by the app. */ progress: number; /** App-owned lifecycle state. */ status: UploadStatus; /** Instantaneous transfer rate in bytes/second (shown while uploading). */ speed?: number; /** Estimated seconds remaining (shown while uploading). */ remainingTime?: number; /** Human-readable error, shown and announced when `status === "failed"`. */ error?: string; /** How many times the app has retried this item. */ retryCount?: number; /** Optional label for the post-upload processing phase, e.g. "Transcoding". */ processingStage?: string; /** Optional preview image URL (the app owns creating AND revoking blob URLs). */ thumbnail?: string; /** Free-form metadata rendered in the expandable details region. */ metadata?: Record; } export interface FileUploadPipelineProps { /** The upload queue, controlled by the host application. */ items: UploadItem[]; /** * Called with the selected/dropped files. The app validates + starts them and * appends the resulting `UploadItem`s. When absent, the drop-zone is hidden. */ onAddFiles?: (files: File[]) => void; /** Pause an in-flight item. */ onPause?: (item: UploadItem) => void; /** Resume a paused item. */ onResume?: (item: UploadItem) => void; /** Retry a failed item. */ onRetry?: (item: UploadItem) => void; /** Cancel an in-flight/queued item. */ onCancel?: (item: UploadItem) => void; /** Remove a terminal item (completed/failed/cancelled) from the list. */ onRemove?: (item: UploadItem) => void; /** Clear all completed items at once. When absent, the control is hidden. */ onClearCompleted?: () => void; /** Reorder the queue (from → to index). Enables up/down controls on queued items. */ onReorder?: (fromIndex: number, toIndex: number) => void; /** Notified when an item's error text is copied. */ onCopyError?: (item: UploadItem) => void; /** `accept` attribute forwarded to the file input. */ accept?: string; /** Allow selecting multiple files (default true). */ multiple?: boolean; /** Show an offline banner and disable adding files. */ offline?: boolean; /** Override byte formatting (e.g. localisation). */ formatBytes?: (bytes: number) => string; /** Header title. */ title?: string; /** Accessible name for the whole region. */ label?: string; className?: string; } const EASE: Transition["ease"] = [0.2, 0, 0, 1]; /* -- status vocabulary — icon + label, tinted with semantic status tokens -- */ interface StatusMetaEntry { label: string; tone: StatusTone; /** Whether this state shows a determinate progress bar. */ bar: boolean; } const STATUS_META: Record = { queued: { label: "Queued", tone: "neutral", bar: false }, preparing: { label: "Preparing", tone: "info", bar: true }, uploading: { label: "Uploading", tone: "active", bar: true }, paused: { label: "Paused", tone: "warning", bar: true }, processing: { label: "Processing", tone: "info", bar: true }, completed: { label: "Completed", tone: "success", bar: false }, failed: { label: "Failed", tone: "error", bar: false }, cancelled: { label: "Cancelled", tone: "neutral", bar: false }, }; const ACTIVE: ReadonlySet = new Set([ "queued", "preparing", "uploading", "paused", "processing", ]); const TERMINAL: ReadonlySet = new Set(["completed", "failed", "cancelled"]); /* -- formatting helpers (pure, deterministic) ---------------------------- */ function defaultFormatBytes(bytes: number): string { if (!Number.isFinite(bytes) || bytes <= 0) return "0 B"; const units = ["B", "KB", "MB", "GB", "TB"]; const exp = Math.min(units.length - 1, Math.floor(Math.log(bytes) / Math.log(1024))); const value = bytes / Math.pow(1024, exp); const rounded = exp === 0 ? Math.round(value) : Math.round(value * 10) / 10; return `${rounded} ${units[exp]}`; } function formatSpeed(bytesPerSec: number, fmt: (b: number) => string): string { return `${fmt(bytesPerSec)}/s`; } function formatEta(seconds: number): string { if (!Number.isFinite(seconds) || seconds < 0) return ""; if (seconds < 60) return `${Math.round(seconds)}s left`; const m = Math.floor(seconds / 60); const s = Math.round(seconds % 60); if (m < 60) return s ? `${m}m ${s}s left` : `${m}m left`; const h = Math.floor(m / 60); return `${h}h ${m % 60}m left`; } function fileKind(fileType: string): "image" | "video" | "audio" | "pdf" | "archive" | "code" | "file" { const t = fileType.toLowerCase(); if (t.startsWith("image")) return "image"; if (t.startsWith("video")) return "video"; if (t.startsWith("audio")) return "audio"; if (t.includes("pdf")) return "pdf"; if (/(zip|tar|gzip|rar|7z|compress)/.test(t)) return "archive"; if (/(json|javascript|typescript|xml|html|css|code|text\/plain)/.test(t)) return "code"; return "file"; } /* -- icons --------------------------------------------------------------- */ const svgBase = { fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round" as const, strokeLinejoin: "round" as const, "aria-hidden": true, focusable: false, }; function StatusIcon({ status }: { status: UploadStatus }) { const p = { width: 13, height: 13, viewBox: "0 0 24 24", ...svgBase, strokeWidth: 2.4 }; switch (status) { case "completed": return ; case "failed": return ; case "paused": return ; case "cancelled": return ; case "processing": return ; case "uploading": case "preparing": return ; case "queued": default: return ; } } function FileIcon({ fileType }: { fileType: string }) { const p = { width: 18, height: 18, viewBox: "0 0 24 24", ...svgBase, strokeWidth: 1.7 }; const paper = ; switch (fileKind(fileType)) { case "image": return ; case "video": return ; case "audio": return ; case "pdf": return ; case "archive": return ; case "code": return ; default: return ; } } function glyph(path: React.ReactNode, size = 14) { return ; } const PauseGlyph = () => glyph(<>); const ResumeGlyph = () => glyph(); const RetryGlyph = () => glyph(<>); const CancelGlyph = () => glyph(<>); const RemoveGlyph = () => glyph(<>); const CopyGlyph = () => glyph(<>, 13); const CheckGlyph = () => glyph(, 13); const ChevronGlyph = () => glyph(, 13); const UpGlyph = () => glyph(, 13); const DownGlyph = () => glyph(, 13); const CloudGlyph = () => glyph(<>, 26); /* -- shared button style ------------------------------------------------- */ const focusRing = "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-focus,var(--color-accent))] focus-visible:ring-offset-1 focus-visible:ring-offset-[var(--color-surface)]"; const iconBtn = cn( "grid h-7 w-7 place-items-center rounded-md text-[var(--color-muted)] transition-colors", "[border:1px_solid_transparent] hover:bg-[var(--color-bg-secondary)] hover:text-[var(--color-fg)]", "disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:bg-transparent", focusRing, ); /* -- single row (owns its disclosure + copy state) ----------------------- */ interface RowProps { item: UploadItem; index: number; count: number; reduce: boolean; fmt: (b: number) => string; onPause?: (item: UploadItem) => void; onResume?: (item: UploadItem) => void; onRetry?: (item: UploadItem) => void; onCancel?: (item: UploadItem) => void; onRemove?: (item: UploadItem) => void; onReorder?: (fromIndex: number, toIndex: number) => void; onCopyError?: (item: UploadItem) => void; requestRemove: (item: UploadItem, index: number) => void; registerRemoveRef: (id: string, el: HTMLButtonElement | null) => void; } const UploadRow = React.memo(function UploadRow({ item, index, count, reduce, fmt, onPause, onResume, onRetry, onCancel, onRemove, onReorder, onCopyError, requestRemove, registerRemoveRef, }: RowProps) { const meta = STATUS_META[item.status]; const vars = statusVars(meta.tone); const details = useDisclosure({ idPrefix: "upl-details" }); const { copied, copy } = useCopy({ onCopy: () => onCopyError?.(item) }); const errorId = `upl-err-${item.id}`; const progress = Math.max(0, Math.min(100, Math.round(item.progress))); const hasBar = meta.bar; const isFailed = item.status === "failed"; const isUploading = item.status === "uploading"; const isPaused = item.status === "paused"; const isQueuedReorder = onReorder && item.status === "queued"; const hasMeta = !!item.metadata && Object.keys(item.metadata).length > 0; const valueText = item.processingStage && item.status === "processing" ? `${meta.label}: ${item.processingStage} - ${progress}%` : `${meta.label} - ${progress}%`; return (

{/* thumbnail / type icon */} {item.thumbnail ? ( // eslint-disable-next-line @next/next/no-img-element

) : ( )}

{/* name + status + actions */}

{item.fileName} {/* status pill: icon + text, never colour alone */} {meta.label}

{/* meta line */}

{fmt(item.fileSize)} {isUploading && item.speed != null ? · {formatSpeed(item.speed, fmt)} : null} {isUploading && item.remainingTime != null ? · {formatEta(item.remainingTime)} : null} {item.status === "processing" && item.processingStage ? · {item.processingStage} : null} {isFailed && (item.retryCount ?? 0) > 0 ? · retry {item.retryCount} : null} {hasMeta ? ( ) : null}

{/* progress bar (determinate) — updated via app-supplied progress only */} {hasBar ? (

{progress}%

) : null} {/* error — associated to the row via aria-describedby */} {isFailed && item.error ? (

Error: {item.error}

) : null} {/* details region */} {hasMeta && details.open ? ( {Object.entries(item.metadata ?? {}).map(([k, v]) => (

{k}

{String(v)}

))} ) : null}

{/* action cluster */}

{isQueuedReorder ? ( <> ) : null} {isUploading && onPause ? ( ) : null} {isPaused && onResume ? ( ) : null} {isFailed && onRetry ? ( ) : null} {ACTIVE.has(item.status) && onCancel ? ( ) : null} {TERMINAL.has(item.status) && onRemove ? ( ) : null}

); }); /* -- root component ------------------------------------------------------ */ export function FileUploadPipeline({ items, onAddFiles, onPause, onResume, onRetry, onCancel, onRemove, onClearCompleted, onReorder, onCopyError, accept, multiple = true, offline = false, formatBytes = defaultFormatBytes, title = "Uploads", label = "File upload pipeline", className, }: FileUploadPipelineProps) { const reduce = useReducedMotion(); const inputRef = React.useRef(null); const browseRef = React.useRef(null); const removeRefs = React.useRef>(new Map()); const [dragOver, setDragOver] = React.useState(false); const [liveMessage, setLiveMessage] = React.useState(""); const registerRemoveRef = React.useCallback((id: string, el: HTMLButtonElement | null) => { if (el) removeRefs.current.set(id, el); else removeRefs.current.delete(id); }, []); /* status-change announcements — NEVER per-percent -------------------- */ const prevStatus = React.useRef>(new Map()); React.useEffect(() => { const prev = prevStatus.current; const messages: string[] = []; const seen = new Set(); for (const it of items) { seen.add(it.id); const before = prev.get(it.id); if (before !== undefined && before !== it.status) { const label = STATUS_META[it.status].label.toLowerCase(); if (it.status === "failed") messages.push(`${it.fileName} failed${it.error ? `: ${it.error}` : ""}`); else messages.push(`${it.fileName} ${label}`); } prev.set(it.id, it.status); } for (const id of prev.keys()) if (!seen.has(id)) prev.delete(id); if (messages.length) setLiveMessage(messages.join(". ")); }, [items]); /* focus preservation after removal ----------------------------------- */ // A remove request records the id we want focus to land on once the app has // dropped the item from `items`; the effect below moves focus after re-render. const pendingFocus = React.useRef<{ id: string | null } | null>(null); const requestRemove = React.useCallback( (item: UploadItem, index: number) => { const next = items[index + 1] ?? items[index - 1]; pendingFocus.current = { id: next ? next.id : null }; onRemove?.(item); }, [items, onRemove], ); React.useEffect(() => { const pending = pendingFocus.current; if (!pending) return; pendingFocus.current = null; const target = pending.id ? removeRefs.current.get(pending.id) : null; // Prefer the neighbouring row's remove control; else fall back to Browse. if (target && document.contains(target)) target.focus(); else browseRef.current?.focus(); }, [items]); /* file input / drop wiring ------------------------------------------- */ const emitFiles = React.useCallback( (fileList: FileList | null) => { if (!fileList || fileList.length === 0) return; onAddFiles?.(Array.from(fileList)); }, [onAddFiles], ); const handleDrop = React.useCallback( (e: React.DragEvent) => { e.preventDefault(); setDragOver(false); if (offline) return; emitFiles(e.dataTransfer?.files ?? null); }, [emitFiles, offline], ); /* aggregate summary -------------------------------------------------- */ const summary = React.useMemo(() => { let uploading = 0, completed = 0, failed = 0, queued = 0, active = 0, progressSum = 0, activeCount = 0; for (const it of items) { if (it.status === "uploading") uploading++; else if (it.status === "completed") completed++; else if (it.status === "failed") failed++; else if (it.status === "queued") queued++; if (ACTIVE.has(it.status)) { active++; progressSum += Math.max(0, Math.min(100, it.progress)); activeCount++; } } const overall = activeCount ? Math.round(progressSum / activeCount) : 0; return { uploading, completed, failed, queued, active, overall, total: items.length }; }, [items]); const isEmpty = items.length === 0; return (

{/* header */}

{title}

{summary.total > 0 ? ( {summary.total} {summary.total === 1 ? "file" : "files"} ) : null}

{summary.active > 0 ? {summary.overall}% overall : null} {summary.completed > 0 ? ( {summary.completed} done ) : null} {summary.failed > 0 ? ( {summary.failed} failed ) : null}

{onClearCompleted && summary.completed > 0 ? ( ) : null}

{/* offline banner */} {offline ? (

You are offline. Uploads are paused and will resume when the connection returns.

) : null} {/* drop zone (only when the app accepts new files) */} {onAddFiles ? (

{ e.preventDefault(); if (!offline) setDragOver(true); }} onDragLeave={(e) => { if (e.currentTarget === e.target) setDragOver(false); }} onDrop={handleDrop} className={cn( "flex flex-col items-center justify-center gap-1.5 rounded-xl px-4 py-6 text-center transition-colors", "[border:1.5px_dashed_var(--color-border)]", dragOver && "[border-color:var(--color-accent)] bg-[color-mix(in_oklab,var(--color-accent)_8%,transparent)]", offline && "opacity-60", )} data-dragover={dragOver || undefined} >

{dragOver ? "Drop to upload" : "Drag files here"} or

{/* real input + keyboard-accessible Browse alternative */} { emitFiles(e.target.files); e.target.value = ""; // allow re-selecting the same file }} />

{accept ? `Accepted: ${accept}` : "Any file type"}{multiple ? " · multiple allowed" : ""}

) : null} {/* list */}

{isEmpty ? (

No files in the queue

{onAddFiles ? "Add files above to start uploading." : "Uploads will appear here."}

) : (

{items.map((item, index) => ( ))}

)}

{/* polite live region — status transitions only, never per-percent */}

{liveMessage}

); } export default FileUploadPipeline;