File Upload Staging Area

1"use client";
2 
3import { useEffect, useImperativeHandle, useRef, useState, type Ref } from "react";
4import { MotionConfig, motion } from "motion/react";
5 
6// File upload staging area - a pipeline expressed through motion.
7//
8// Three hard problems, none of them the dropzone:
9//
10//   · A reflowing GRID that never jump-cuts. Tiles are motion.li with `layout`:
11//     removing a tile mid-grid makes every later tile glide up and across, and
12//     entering tiles scale + unblur in. Exits stay subtler than enters - here,
13//     instant.
14//   · An interruptible state machine PER TILE: queued → uploading → done, or
15//     → error frozen at the failure percent. Retry RESUMES from that percent
16//     (the arc never lies by rewinding), removal works in any state, and a
17//     freed slot immediately promotes the next queued tile - concurrency is
18//     capped at 2 so the pipeline is visible instead of everything blasting
19//     to 100% at once.
20//   · Honest jittered progress. One shared ticker advances every uploading
21//     tile by a random 0.6-4% with a 12% chance to stall a beat - variable
22//     like a real network - but progress NEVER moves backwards and 100% is
23//     the only way to complete. Failures are decided up front (a hidden
24//     failAt percent), not rolled per frame.
25//
26// TWO MODES, one pipeline:
27//
28//   · No `upload` prop → the built-in simulation (nothing leaves the page).
29//     Works out of the box; `failRate` shapes the demo.
30//   · An `upload` adapter → REAL uploads. The component keeps owning the queue,
31//     concurrency, retry and removal; your adapter owns the network:
32//
33//       <UploadStaging
34//         upload={async ({ file, name }, { onProgress, signal }) => {
35//           await api.upload(file!, { signal, onProgress }); // report 0-100
36//         }}
37//       />
38//
39//     Resolve → done. Throw → error, frozen at the last reported percent.
40//     Removing a tile mid-flight aborts via the AbortSignal. Retry re-invokes
41//     the adapter; the arc still never rewinds (progress is forward-only, so a
42//     restarted transfer catches up to the frozen percent before it moves).
43//
44// Real drag-and-drop and the file picker both work (the original File rides
45// along for the adapter); stage files programmatically through the ref handle:
46//
47//   const staging = useRef<UploadStagingHandle>(null);
48//   staging.current?.addFiles([{ name: "report.pdf", size: 842_000 }]);
49//
50// … truncated