"use client"; import * as React from "react"; import { motion, AnimatePresence, type Transition } from "motion/react"; import { cn } from "@/lib/utils"; import { useReducedMotion, statusVars, type StatusTone } from "@/lib/motiq"; /* -------------------------------------------------------------------------- * MultiFileQueue — a presentation-only view for *managing a collection* of * files that the host application schedules through a bounded number of * concurrent slots. Where an upload panel shows one transfer's progress, this * component is the queue *manager*: priority lanes, active-slot occupancy, * blocked-item explanation, queue-level progress, and queue-wide operations * (pause-all / resume-all / retry-failed / clear-completed) plus per-item * reorder and priority changes. * * It NEVER uploads, reads a File body, opens a socket, or advances `progress` * on its own. The application owns the scheduler and the transport; this * component renders the `items` it is given and emits intent callbacks * (`onPauseAll`, `onReorder`, `onPriorityChange`, …) so the app can react. * `concurrency` (how many slots run at once) is app-supplied — the component * only *visualises* occupancy, it does not enforce it. * * Accessibility is first-class: the queue is a semantic list; every status is * conveyed with an icon AND text (never colour alone); priority is a labelled * badge, not a hue; in-flight items expose `role="progressbar"` with * `aria-valuetext`; blocked items explain *what* they wait on and associate it * via `aria-describedby`; reorder and priority changes are ordinary keyboard * buttons that announce the item's new lane position in a polite live region; * focus is preserved onto a neighbour after an item is removed; and the live * region announces STATUS TRANSITIONS and MOVES ONLY — never per-percent — so a * screen reader isn't flooded while the queue drains. Under * `prefers-reduced-motion` rows appear without offset and bars snap. * * PERFORMANCE. No per-frame React state: bar width comes from the app-supplied * `progress` and is eased purely in CSS, so a fast queue does not re-render * React 60×/s (throttle your `progress` writes to a few per second). Rows are * memoised and use Motion `layout="position"` so changing one item does not * replay every other item's entrance. For very large queues wrap the lanes in * your own virtualiser — this component renders every item it is given. * Clean-room original. * ----------------------------------------------------------------------- */ /** Lifecycle of a single queued file, owned entirely by the application. */ export type QueueStatus = | "queued" | "waiting" | "active" | "paused" | "blocked" | "processing" | "completed" | "failed" | "cancelled"; /** Scheduling priority. Rendered as a labelled lane + badge, never colour alone. */ export type QueuePriority = "high" | "normal" | "low"; export interface QueueItem { /** 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. */ fileSize: number; /** Scheduling priority — determines which lane the item sits in. */ priority: QueuePriority; /** App-maintained 1-based position within the whole queue (display only). */ queuePosition?: number; /** App-owned lifecycle state. */ status: QueueStatus; /** Per-item progress 0–100, supplied and advanced by the app. */ progress: number; /** Instantaneous transfer rate in bytes/second (shown while active). */ speed?: number; /** Estimated seconds remaining (shown while active). */ remainingTime?: number; /** How many times the app has retried this item. */ retryCount?: number; /** Human-readable error, shown and announced when `status === "failed"`. */ error?: string; /** Optional preview image URL (the app owns creating AND revoking blob URLs). */ thumbnail?: string; /** What a `blocked` item is waiting on, e.g. "cover.png to finish". */ dependency?: string; /** Destination label, e.g. "Media library / 2026 campaign". */ destination?: string; /** Free-form metadata rendered by `renderItemDetails` or the default list. */ metadata?: Record; } export interface MultiFileQueueProps { /** The queue, controlled by the host application. Array order IS queue order. */ items: QueueItem[]; /** * How many items the app runs concurrently. Drives the active-slot indicator. * The component only visualises occupancy — it does not start work itself. */ concurrency?: number; /** Add files to the queue (the app validates + appends `QueueItem`s). */ onAdd?: () => void; /** Remove a single item from the queue. */ onRemove?: (item: QueueItem) => void; /** Pause a single active item. */ onPause?: (item: QueueItem) => void; /** Resume a single paused item. */ onResume?: (item: QueueItem) => void; /** Retry a single failed item. */ onRetry?: (item: QueueItem) => void; /** Cancel a single in-flight/queued item. */ onCancel?: (item: QueueItem) => void; /** Move an item within the queue (from → to index in `items`). */ onReorder?: (fromIndex: number, toIndex: number) => void; /** Change an item's scheduling priority (moves it between lanes). */ onPriorityChange?: (item: QueueItem, priority: QueuePriority) => void; /** Pause every running item at once. */ onPauseAll?: () => void; /** Resume every paused item at once. */ onResumeAll?: () => void; /** Retry every failed item at once. */ onRetryFailed?: () => void; /** Clear all completed items at once. */ onClearCompleted?: () => void; /** Show an offline banner; the app is expected to pause scheduling. */ offline?: boolean; /** Denser rows (hide secondary meta, smaller thumbnails). */ compact?: boolean; /** Render extra per-item detail below the meta line. */ renderItemDetails?: (item: QueueItem) => React.ReactNode; /** 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 + semantic tone -------------------- */ 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 }, waiting: { label: "Waiting for slot", tone: "neutral", bar: false }, active: { label: "Active", tone: "active", bar: true }, paused: { label: "Paused", tone: "warning", bar: true }, blocked: { label: "Blocked", tone: "warning", bar: false }, 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 }, }; /** Items currently occupying a concurrency slot. */ const RUNNING: ReadonlySet = new Set(["active", "processing"]); /** Items that can be reordered / re-prioritised (still pending). */ const PENDING: ReadonlySet = new Set(["queued", "waiting", "blocked", "paused"]); /** Terminal states. */ const TERMINAL: ReadonlySet = new Set(["completed", "failed", "cancelled"]); const PRIORITY_ORDER: QueuePriority[] = ["high", "normal", "low"]; const PRIORITY_LABEL: Record = { high: "High", normal: "Normal", low: "Low" }; /* -- 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: QueueStatus }) { 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 "blocked": return ; case "cancelled": return ; case "processing": return ; case "active": return ; case "waiting": case "queued": default: return ; } } function PriorityIcon({ priority }: { priority: QueuePriority }) { const p = { width: 12, height: 12, viewBox: "0 0 24 24", ...svgBase, strokeWidth: 2.4 }; switch (priority) { case "high": return ; case "low": return ; case "normal": 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 UpGlyph = () => glyph(, 13); const DownGlyph = () => glyph(, 13); const RaiseGlyph = () => glyph(<>, 13); /* -- shared styles ------------------------------------------------------- */ 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, ); const toolbarBtn = cn( "inline-flex items-center gap-1.5 rounded-md bg-[var(--color-surface)] px-2 py-1 text-[12px] font-medium text-[var(--color-fg)] [border:1px_solid_var(--color-border)] transition-colors", "hover:border-[var(--color-accent)] hover:text-[var(--color-accent)] disabled:cursor-not-allowed disabled:opacity-45", focusRing, ); /* -- lane item, with its global index + within-lane siblings ------------- */ interface LaneEntry { item: QueueItem; globalIndex: number; } interface RowProps { entry: LaneEntry; laneEntries: LaneEntry[]; laneRank: number; // 1-based position within the lane compact: boolean; reduce: boolean; fmt: (b: number) => string; renderItemDetails?: (item: QueueItem) => React.ReactNode; onPause?: (item: QueueItem) => void; onResume?: (item: QueueItem) => void; onRetry?: (item: QueueItem) => void; onCancel?: (item: QueueItem) => void; onPriorityChange?: (item: QueueItem, priority: QueuePriority) => void; move: (entry: LaneEntry, laneEntries: LaneEntry[], direction: -1 | 1) => void; raisePriority: (item: QueueItem) => void; requestRemove: (item: QueueItem) => void; registerRemoveRef: (id: string, el: HTMLButtonElement | null) => void; } const QueueRow = React.memo(function QueueRow({ entry, laneEntries, laneRank, compact, reduce, fmt, renderItemDetails, onPause, onResume, onRetry, onCancel, onPriorityChange, move, raisePriority, requestRemove, registerRemoveRef, }: RowProps) { const { item } = entry; const meta = STATUS_META[item.status]; const vars = statusVars(meta.tone); const errorId = `mfq-err-${item.id}`; const blockedId = `mfq-blk-${item.id}`; const progress = Math.max(0, Math.min(100, Math.round(item.progress))); const hasBar = meta.bar; const isRunning = item.status === "active"; const isPaused = item.status === "paused"; const isBlocked = item.status === "blocked"; const isFailed = item.status === "failed"; const canReorder = onReorderEnabled(move) && PENDING.has(item.status) && laneEntries.length > 1; const canRaise = !!onPriorityChange && PENDING.has(item.status) && item.priority !== "high"; const describedBy = [isBlocked && item.dependency ? blockedId : null, isFailed && item.error ? errorId : null] .filter(Boolean) .join(" ") || undefined; const valueText = `${meta.label} - ${progress}%`; return (

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

) : ( )} ) : null}

{/* name + priority + status */}

{item.fileName} {/* priority badge — icon + text, never colour alone */} {PRIORITY_LABEL[item.priority]} {/* status pill — icon + text, never colour alone */} {meta.label}

{/* meta line */} {!compact ? (

{fmt(item.fileSize)} {isRunning && item.speed != null ? · {formatSpeed(item.speed, fmt)} : null} {isRunning && item.remainingTime != null ? · {formatEta(item.remainingTime)} : null} {item.destination ? · → {item.destination} : null} {isFailed && (item.retryCount ?? 0) > 0 ? · retry {item.retryCount} : null}

) : null} {/* progress bar (determinate) — driven by app-supplied progress only */} {hasBar ? (

{progress}%

) : null} {/* blocked explanation — associated to the row */} {isBlocked && item.dependency ? (

Blocked: Waiting for {item.dependency}

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

Error: {item.error}

) : null} {/* app-provided details */} {renderItemDetails ?

{renderItemDetails(item)}

: null}

{/* action cluster */}

{canReorder ? ( <> ) : null} {canRaise ? ( ) : null} {isRunning && onPause ? ( ) : null} {isPaused && onResume ? ( ) : null} {isFailed && onRetry ? ( ) : null} {!TERMINAL.has(item.status) && onCancel ? ( ) : null}

); }); // Small guard so the row only shows reorder controls when the app wired onReorder // (the `move` handler is a no-op sentinel otherwise). Kept as a function to avoid // leaking the raw callback into the memoised row's identity checks. function onReorderEnabled(move: RowProps["move"]): boolean { return move !== NOOP_MOVE; } const NOOP_MOVE: RowProps["move"] = () => {}; /* -- root component ------------------------------------------------------ */ export function MultiFileQueue({ items, concurrency, onAdd, onRemove, onPause, onResume, onRetry, onCancel, onReorder, onPriorityChange, onPauseAll, onResumeAll, onRetryFailed, onClearCompleted, offline = false, compact = false, renderItemDetails, formatBytes = defaultFormatBytes, title = "Queue", label = "Multi-file queue", className, }: MultiFileQueueProps) { const reduce = useReducedMotion(); const removeRefs = React.useRef>(new Map()); const fallbackFocusRef = React.useRef(null); 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 lbl = STATUS_META[it.status].label.toLowerCase(); if (it.status === "failed") messages.push(`${it.fileName} failed${it.error ? `: ${it.error}` : ""}`); else if (it.status === "blocked") messages.push(`${it.fileName} blocked${it.dependency ? `, waiting for ${it.dependency}` : ""}`); else messages.push(`${it.fileName} ${lbl}`); } 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 ----------------------------------- */ const pendingFocus = React.useRef<{ id: string | null } | null>(null); const requestRemove = React.useCallback( (item: QueueItem) => { const index = items.findIndex((it) => it.id === item.id); 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; if (target && document.contains(target)) target.focus(); else fallbackFocusRef.current?.focus(); }, [items]); /* reorder + priority (with position announcement) -------------------- */ const move = React.useCallback( (entry: LaneEntry, laneEntries: LaneEntry[], direction: -1 | 1) => { if (!onReorder) return; const rank = laneEntries.findIndex((e) => e.globalIndex === entry.globalIndex); const targetRank = rank + direction; const target = laneEntries[targetRank]; if (!target) return; onReorder(entry.globalIndex, target.globalIndex); setLiveMessage( `Moved ${entry.item.fileName} to position ${targetRank + 1} of ${laneEntries.length} in the ${PRIORITY_LABEL[entry.item.priority]} lane`, ); }, [onReorder], ); const raisePriority = React.useCallback( (item: QueueItem) => { if (!onPriorityChange) return; const idx = PRIORITY_ORDER.indexOf(item.priority); const next = PRIORITY_ORDER[Math.max(0, idx - 1)]; if (next === item.priority) return; onPriorityChange(item, next); setLiveMessage(`${item.fileName} priority raised to ${PRIORITY_LABEL[next]}`); }, [onPriorityChange], ); /* derived queue state ------------------------------------------------ */ const summary = React.useMemo(() => { let running = 0, paused = 0, failed = 0, completed = 0, pending = 0, blocked = 0, completionSum = 0; for (const it of items) { if (RUNNING.has(it.status)) running++; if (it.status === "paused") paused++; if (it.status === "failed") failed++; if (it.status === "completed") completed++; if (it.status === "blocked") blocked++; if (PENDING.has(it.status)) pending++; completionSum += it.status === "completed" ? 100 : Math.max(0, Math.min(100, it.progress)); } const overall = items.length ? Math.round(completionSum / items.length) : 0; return { running, paused, failed, completed, pending, blocked, overall, total: items.length }; }, [items]); // Lanes: fixed high→normal→low order; only lanes with items are shown. const lanes = React.useMemo(() => { const byPriority: Record = { high: [], normal: [], low: [] }; items.forEach((item, globalIndex) => byPriority[item.priority].push({ item, globalIndex })); return PRIORITY_ORDER.filter((p) => byPriority[p].length > 0).map((p) => ({ priority: p, entries: byPriority[p] })); }, [items]); const queueRunning = summary.running > 0; const canPauseAll = !!onPauseAll && queueRunning; const canResumeAll = !!onResumeAll && !queueRunning && summary.paused > 0; const moveHandler = onReorder ? move : NOOP_MOVE; const isEmpty = items.length === 0; const slotsText = concurrency != null ? `${summary.running} / ${concurrency} slots active` : `${summary.running} active`; return (

{/* header */}

{title}

{summary.total > 0 ? ( {summary.total} {summary.total === 1 ? "file" : "files"} ) : null} {/* active-slot indicator */} {concurrency != null ? ( {Array.from({ length: Math.max(concurrency, summary.running) }).map((_, i) => ( ))} ) : null} {slotsText} {onAdd ? ( ) : null}

{/* queue-level progress */} {summary.total > 0 ? (

{summary.completed}/{summary.total} done

) : null} {/* queue-level operations */} {summary.total > 0 ? (

{canPauseAll ? ( ) : null} {canResumeAll ? ( ) : null} {onRetryFailed && summary.failed > 0 ? ( ) : null} {onClearCompleted && summary.completed > 0 ? ( ) : null} {/* compact status summary — icon + text */}

{summary.blocked > 0 ? ( {summary.blocked} blocked ) : null} {summary.failed > 0 ? ( {summary.failed} failed ) : null}

) : null}

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

You are offline. The queue is paused and resumes automatically when the connection returns.

) : null} {/* lanes */}

{isEmpty ? (

The queue is empty

{onAdd ? "Add files to start scheduling them." : "Queued files will appear here."}

) : ( lanes.map((lane) => (

{PRIORITY_LABEL[lane.priority]} priority {lane.entries.length} {lane.entries.length === 1 ? "file" : "files"}

{lane.entries.map((entry, laneRank) => ( ))}

)) )}

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

{liveMessage}

); } export default MultiFileQueue;