git:20260202.b236384 to git:20260316.00cb75b

+ > **Quick Guide:** Use drag-and-drop dropzones with fallback file inputs for uploads. Validate files client-side (MIME + magic bytes) AND server-side. For files >5MB use chunked uploads with progress tracking. Upload directly to S3 using presigned URLs to avoid server bottlenecks. Always implement proper accessibility with keyboard support and ARIA announcements. Use XHR (not fetch) for upload progress events.

+ **(You MUST use presigned URLs for cloud storage uploads - never proxy large files through your server)**

+ **Auto-detection:** file upload, dropzone, drag-drop, drag and drop upload, useDropzone, TUS protocol, presigned URL, multipart upload, file validation, magic bytes, MIME type, progress indicator, upload progress, XHR upload, S3 upload, file input, aria-label upload, chunked upload, resumable upload

+ - Uploading to cloud storage directly from browser

+ ---

+

+ - [examples/core.md](examples/core.md) - Dropzone, file list, combined upload component

+ - [examples/validation.md](examples/validation.md) - MIME type, magic bytes, dimension validation

+ - [examples/progress.md](examples/progress.md) - Progress tracking, speed, abort, multi-file

+ - [examples/preview.md](examples/preview.md) - Image preview, thumbnails, EXIF orientation

+ - [examples/s3-upload.md](examples/s3-upload.md) - Presigned URLs, multipart uploads

+ - [examples/resumable.md](examples/resumable.md) - Chunked uploads, TUS protocol

+ - [examples/accessibility.md](examples/accessibility.md) - ARIA patterns, keyboard, announcements

+ - [reference.md](reference.md) - Decision frameworks, anti-patterns, checklists

+ File uploads are deceptively complex. A simple file input works for basic cases, but production apps need validation, progress feedback, error handling, and accessibility. The key insight is that **client-side validation is for UX, not security** - always validate on the server too.

+ 3. **Direct uploads** - Use presigned URLs to upload to cloud storage directly, not through your server

+ ### Pattern 1: Drag-and-Drop Dropzone

+ Build a dropzone with drag-and-drop and fallback file input. Key elements:

+ - Track drag state with a counter ref (not boolean) to handle nested element events

+ - `role="button"` + `tabIndex={0}` + Enter/Space key handlers for keyboard access

+ - Hidden `<input type="file">` triggered by click/keyboard

+ - Type validation via `accept` attribute plus runtime checking

+ - Reset `event.target.value = ''` after selection to allow re-selecting same file

+ // Key structure - full implementation in examples/core.md

+ export function FileDropzone({ onFilesSelected, accept, multiple, disabled }: FileDropzoneProps) {

+ const dragCounterRef = useRef(0); // Handles nested element drag events

+ onDragEnter={() => { dragCounterRef.current++; setState('drag-over'); }}

+ onDragLeave={() => { dragCounterRef.current--; if (dragCounterRef.current === 0) setState('idle'); }}

+ onClick={() => inputRef.current?.click()}

+ onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') inputRef.current?.click(); }}

+ <input ref={inputRef} type="file" hidden aria-hidden="true" tabIndex={-1} />

+ See [examples/core.md](examples/core.md) for full implementation with SCSS.

+ Track multiple files with status, progress, and preview URLs:

+ // use-file-list.ts - full implementation in examples/core.md

+ // addFiles returns { added, rejected } with rejection reasons

+ // removeFile cleans up object URLs via URL.revokeObjectURL()

+ // clearFiles revokes all object URLs before clearing

+ hasFiles,

+ canAddMore,

+ Key: Always `URL.revokeObjectURL()` on remove and clear. Return rejected files with reasons for user feedback.

+ See [examples/core.md](examples/core.md) for full hook.

+

+ The Fetch API does not support upload progress events. Use XHR:

+ // use-upload-progress.ts - full implementation in examples/progress.md

+ const xhr = new XMLHttpRequest();

+ xhr.upload.addEventListener("progress", (event) => {

+ if (event.lengthComputable) {

+ const speed = calculateRollingAverageSpeed(event.loaded, performance.now());

+ const remaining = (event.total - event.loaded) / speed;

+ setProgress({

+ loaded: event.loaded,

+ total: event.total,

+ percentage,

+ speed,

+ remainingTime: remaining,

+ });

+ }

+ });

+ ```

+ Key: Use a rolling average (5 samples) for smooth speed display. Always provide abort capability via `xhr.abort()`.

+ **Note:** Fetch streams measure bytes taken from your stream, not actual network transmission ([Jake Archibald's analysis](https://jakearchibald.com/2025/fetch-streams-not-for-progress/)). A native fetch progress API is in development. Until then, use XHR.

+ See [examples/progress.md](examples/progress.md) for full hook and multi-file manager.

+ MIME types and extensions can be spoofed. Read actual file bytes:

+ // file-type-detection.ts - full implementation in examples/validation.md

+ // Match against signatures, return { mime, extension, confidence }

+ Key: Only read first 8-12 bytes (not entire file). Office documents (.docx/.xlsx/.pptx) are ZIP files - detect by checking for `word/`/`xl/`/`ppt/` in the first 1000 bytes.

+ See [examples/validation.md](examples/validation.md) for full detection and validator class.

+

+ ### Pattern 5: Direct-to-Storage Upload with Presigned URLs

+ Upload directly to cloud storage from the browser. The flow:

+ 1. Client requests presigned URL from your server (with file metadata)

+ 2. Server generates time-limited presigned URL and returns it

+ 3. Client uploads directly to storage using the presigned URL

+ 4. Server never touches the file bytes

+ // Client-side upload - full implementation in examples/s3-upload.md

+ export async function uploadWithPresignedPut(

+ presignedUrl: string,

+ options: {

+ onProgress?: (progress: number) => void;

+ abortSignal?: AbortSignal;

+ } = {},

+ ): Promise<void> {

+ const xhr = new XMLHttpRequest();

+ // XHR for progress + PUT to presigned URL

+ xhr.open("PUT", presignedUrl);

+ xhr.setRequestHeader("Content-Type", file.type);

+ xhr.send(file);

+ Key: For POST uploads, add presigned fields to FormData **before** the file (order matters). For large files (>100MB), use multipart upload with per-part presigned URLs. Always sanitize filenames server-side.

+ See [examples/s3-upload.md](examples/s3-upload.md) for POST/PUT uploads, multipart, and full flow hook.

+ ### Pattern 6: Chunked and Resumable Uploads

+ For files >100MB, split into chunks with concurrency control:

+ // chunked-upload.ts - full implementation in examples/resumable.md

+ const DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024; // 5MB

+ // Upload chunks in parallel with concurrency limit

+ // Retry failed chunks with exponential backoff

+ // Save progress to localStorage for browser refresh recovery

+ // Support pause/resume/cancel

+ Key: Use localStorage keyed by `filename-size-lastModified` to persist completed chunks. Expire stored progress after 24 hours. For standards-based resumable uploads, implement the TUS protocol (POST to create, HEAD to check offset, PATCH to upload chunks).

+ See [examples/resumable.md](examples/resumable.md) for chunked uploader, localStorage persistence, and TUS client.

+

+ </patterns>

+

+ - Exposing cloud storage credentials in client code - use presigned URLs from server

+ - Using fetch for uploads - no upload progress events; use XHR

+ - Fake progress bars - show real progress or spinner, not fake animation

+ - Creating object URLs on every render without cleanup

+ - CORS required for direct cloud storage uploads - configure bucket policy

+ - EXIF orientation in photos - images may appear rotated (modern browsers auto-rotate for display, but manual handling needed for Canvas processing)

+ - `dragenter`/`dragleave` fire for nested elements - use a counter ref, not boolean state

+ **(You MUST use presigned URLs for cloud storage uploads - never proxy large files through your server)**