FRD: File Upload Recipe

Document Summary

Field	Details
Feature Name	File Upload Seed Example
Status	Draft
Owner	David Holmes
Contributors	Engineering
Target Release	v2.0.0 (P2)
Related Links	Roadmap item #78, ADR-027 (Default Tech Stack)
Last Updated	2026-05-26

Introduction

Overview

The File Upload recipe provides a runnable example folder demonstrating a complete upload flow: file selection via file-dropzone.tsx, upload progress tracking, client-side validation, an uploaded asset list, and a signed-URL handoff pattern for secure server-side uploads. The recipe ships with stories, unit tests, and copy-pasteable code that developers can adapt for their applications.

Goals

Demonstrate a complete upload flow using the existing file-dropzone.tsx component.
Show upload progress tracking with cancel support.
Include client-side validation (file type, size, count limits).
Provide an uploaded asset list with preview, remove, and retry actions.
Document the signed-URL handoff pattern for secure uploads to cloud storage.
Ship as a runnable example folder with stories and tests.

Non-Goals

Building a new file-upload component (uses existing file-dropzone.tsx).
Implementing a real backend or cloud storage integration.
Providing image editing, cropping, or annotation.
Building a file manager or document management system.
Server-side virus scanning or content moderation.

Scope

In Scope

Area	Description
Recipe folder	Self-contained example folder with source, stories, and tests
File selection	Integration with `file-dropzone.tsx` for drag-and-drop and click-to-select
Upload progress	Progress bar per file with percentage and cancel button
Client-side validation	File type allowlist, max file size, max file count
Validation error display	Inline errors per file; rejected files listed with reasons
Uploaded asset list	List of completed uploads with preview thumbnail, filename, size, and actions
Remove action	Remove a file from the upload list (before or after upload)
Retry action	Retry a failed upload
Signed-URL handoff	Documented pattern for requesting a signed URL from the server, uploading directly to storage
Stories	Storybook stories demonstrating each state
Unit tests	Tests covering validation, progress, and asset list behavior

Out of Scope

Area	Reason
New file-upload primitive	Uses existing `file-dropzone.tsx`
Real backend/cloud storage	Recipe uses mock upload functions
Image editing/cropping	Separate concern
Chunked/resumable uploads	Advanced feature deferred to future iteration
Server-side validation	Consumer responsibility

Users and Pain Points

User Groups

User	Description	Needs
Application developers	Engineers building file upload features	A complete reference implementation they can copy and customize
QA engineers	Testers verifying upload flows	Stories showing all upload states for visual testing
New team members	Engineers learning design system patterns	A working example with tests showing best practices

Pain Points

User	Pain Point	Impact
Application developers	`file-dropzone.tsx` exists but there is no example showing the complete upload flow	Developers build incomplete flows; miss progress tracking, validation, or error handling
Application developers	No documented pattern for signed-URL uploads	Each team invents its own server handoff pattern
Application developers	Upload state management (pending, uploading, complete, failed) is built from scratch each time	Duplicated, inconsistent implementations

Definitions

Term	Definition
Recipe	A runnable example folder with source code, stories, and tests that developers copy and adapt
Signed URL	A time-limited, pre-authenticated URL that allows direct upload to cloud storage without exposing credentials
Upload progress	A per-file percentage (0-100) indicating upload completion
Validation	Client-side checks on file type, size, and count before upload begins
Asset list	A UI list showing uploaded files with preview, metadata, and actions

Current State

Existing Behavior

file-dropzone.tsx provides a drag-and-drop file selection area with configurable accept types and multiple file support. It handles file selection events but does not manage uploads, progress, validation, or asset display.

Current Limitations

No upload progress tracking pattern.
No client-side validation example (type, size, count).
No uploaded asset list component or pattern.
No signed-URL handoff documentation.
No runnable example tying the flow together.

Existing Workarounds

Developers build upload flows from scratch using file-dropzone.tsx as the starting point.
Progress tracking is often omitted or implemented with varying quality.
Signed-URL patterns are passed via tribal knowledge.

Proposed Solution

Summary

Create a recipe folder (src/recipes/file-upload/) containing a composed upload flow, a mock upload function with progress simulation, client-side validation logic, an uploaded asset list, and documentation for the signed-URL handoff pattern. Ship with Storybook stories and Vitest unit tests.

Key Capabilities

FileUploadDemo component composing FileDropzone, progress indicators, validation, and asset list.
useFileUpload hook managing upload state: pending, uploading (with progress), complete, failed.
validateFiles(files, config) function checking type, size, and count constraints.
UploadedAssetList component showing completed uploads with preview, metadata, and actions.
mockUpload(file) function simulating progress and completion for stories and tests.
Signed-URL handoff pattern documented in the recipe MDX page.

User Experience

Developers browse the recipe in Storybook, see the upload flow in action via stories, and copy the code into their application. They replace mockUpload with their real upload function (including signed-URL request) and customize the validation config.

Developer Experience

The recipe is a self-contained folder. Developers copy it, wire up their backend, and have a working upload flow. The useFileUpload hook encapsulates state management. Validation is configurable via a typed config object.

Requirements

ID	Requirement	Priority	Notes
FR-001	The recipe must integrate with `file-dropzone.tsx`	Must	Existing component
FR-002	The recipe must show upload progress per file	Must	Progress bar with percentage
FR-003	The recipe must include client-side validation	Must	Type, size, count
FR-004	The recipe must show an uploaded asset list	Must	Preview, filename, size, actions
FR-005	The recipe must document the signed-URL handoff pattern	Must	MDX documentation
FR-006	The recipe must ship with stories	Must	Visual reference
FR-007	The recipe must ship with unit tests	Must	Quality gate
FR-008	The recipe should support cancel during upload	Should	UX improvement
FR-009	The recipe should support retry on failed uploads	Should	Error recovery

Priority Definitions

Priority	Meaning
Must	Required for this feature to ship.
Should	Important, but can be deferred if needed.
Could	Nice to have. Not required for initial release.

Functional Requirements

ID	Requirement	User Benefit	Priority
FUNC-001	`useFileUpload` hook accepts a `config` with `accept`, `maxSizeMB`, `maxFiles`	Configurable validation	Must
FUNC-002	`useFileUpload` returns `{ files, addFiles, removeFile, retryFile, cancelFile, clearAll }`	Complete state management	Must
FUNC-003	Each file in `files` has `{ id, file, status, progress, error, previewUrl }`	Per-file state tracking	Must
FUNC-004	Status transitions: `pending` -> `uploading` -> `complete` or `failed`	Clear lifecycle	Must
FUNC-005	Files that fail validation are added with `status: 'rejected'` and an `error` message	Inline error display	Must
FUNC-006	Upload progress updates from 0 to 100 during upload	Progress visibility	Must
FUNC-007	`cancelFile(id)` aborts an in-progress upload and sets status to `cancelled`	User can stop unwanted uploads	Should
FUNC-008	`retryFile(id)` re-initiates upload for a failed file	Error recovery	Should
FUNC-009	`UploadedAssetList` renders completed files with thumbnail preview, filename, size, and a remove button	Visual asset management	Must
FUNC-010	Recipe MDX documents the signed-URL pattern: (1) request signed URL from server, (2) upload directly to storage, (3) confirm upload with server	Secure upload guidance	Must

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Recipe code must be copy-pasteable and self-contained	Maintainability	Must
NFR-002	All recipe code must pass TypeScript strict mode	Correctness	Must
NFR-003	Stories must render without errors in light and dark themes	Compatibility	Must
NFR-004	Upload progress must not cause excessive re-renders (throttle updates to ~100ms intervals)	Performance	Should
NFR-005	Preview thumbnails must use `URL.createObjectURL` and revoke on cleanup	Performance	Must
NFR-006	Tests must not perform real network requests	Testing	Must

API / Interface Requirements

Public API

This is a recipe, not a published package. No new public API is exported from the design system. The recipe provides copy-pasteable code.

Name	Type	Description	Required
Recipe folder	`source`	`src/recipes/file-upload/` with components, hook, and utilities	Yes
Recipe MDX	`documentation`	Storybook MDX page documenting the pattern	Yes
Recipe stories	`stories`	Storybook stories showing all states	Yes
Recipe tests	`tests`	Vitest tests covering hook and validation	Yes

Example Usage

import { FileDropzone } from "@dmwd/design-system";
import { useFileUpload, UploadedAssetList } from "./file-upload";

function UploadPage() {
  const { files, addFiles, removeFile, retryFile } = useFileUpload({
    accept: ["image/png", "image/jpeg", "application/pdf"],
    maxSizeMB: 10,
    maxFiles: 5,
    uploadFn: async (file, onProgress) => {
      const { url } = await requestSignedUrl(file.name, file.type);
      await uploadToStorage(url, file, onProgress);
    },
  });

  return (
    <div>
      <FileDropzone onDrop={addFiles} accept="image/*,.pdf" />
      <UploadedAssetList
        files={files}
        onRemove={removeFile}
        onRetry={retryFile}
      />
    </div>
  );
}

API Notes

useFileUpload accepts an uploadFn that receives the file and an onProgress callback.
The mockUpload function in the recipe simulates progress with configurable delay and failure rate.
previewUrl is generated via URL.createObjectURL for image files; non-image files show a file-type icon.

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	File dropzone must be keyboard-accessible (Enter/Space to open file picker)	Existing `file-dropzone.tsx` behavior
A11Y-002	Upload progress must be announced to screen readers	`aria-live="polite"` on progress or `role="progressbar"`
A11Y-003	Remove and retry buttons must have accessible labels including the filename	”Remove invoice.pdf”, “Retry report.xlsx”
A11Y-004	Validation errors must be associated with the rejected file	`aria-describedby` linking error to file entry
A11Y-005	Cancel button must have an accessible label	”Cancel upload of photo.jpg”

Checklist

Keyboard support is defined.
Focus behavior is defined.
Screen reader behavior is defined.
Color contrast requirements are met.
Reduced motion behavior is considered.
Semantic HTML expectations are documented.
ARIA usage is defined only where needed.

Content and Documentation Requirements

ID	Requirement	Location	Priority
DOC-001	Recipe MDX page with complete upload flow documentation	Storybook MDX	Must
DOC-002	Signed-URL handoff pattern explanation with sequence diagram	Storybook MDX	Must
DOC-003	Validation configuration guide	Storybook MDX	Must
DOC-004	”How to customize” section for replacing mockUpload with real upload	Storybook MDX	Must
DOC-005	Accessibility notes for the upload flow	Storybook MDX	Must

Documentation Should Include

Overview of the upload flow
When to use this recipe
Prerequisites
File selection and validation
Upload progress and state management
Signed-URL handoff pattern
Asset list and actions
Customization guide
Accessibility notes
Testing notes
Common mistakes (e.g., not revoking object URLs, not throttling progress)

Dependencies

Dependency	Type	Owner	Status	Notes
`file-dropzone.tsx`	Design System	David Holmes	Ready	Existing component
React 18+	Engineering	David Holmes	Ready	Peer dependency
Vitest	Engineering	David Holmes	Ready	Test runner

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
Recipe uses mock upload; real integrations vary significantly	Developers may need substantial adaptation for their backend	Document the signed-URL pattern clearly; keep the upload interface generic
No chunked/resumable upload support	Large files may fail on slow connections	Document as a known limitation; suggest chunked upload as a future enhancement
Preview thumbnails consume memory for large image files	Browser memory pressure with many large files	Revoke object URLs on cleanup; document memory considerations
Recipe folder structure may not match all project conventions	Developers may need to reorganize files	Keep the folder flat and simple; document how to adapt

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should the recipe include drag-and-drop reordering of the asset list?	David Holmes	Open	—
Q-002	Should the recipe show inline image preview during upload (before completion)?	David Holmes	Open	—
Q-003	Should `useFileUpload` support concurrent upload limits (e.g., max 3 simultaneous)?	David Holmes	Open	—
Q-004	Should the recipe include a file-type icon mapping utility?	David Holmes	Open	—

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	Recipe integrates with `file-dropzone.tsx` for file selection	FR-001
AC-002	Upload progress is displayed per file as a percentage	FR-002
AC-003	Files exceeding size limit are rejected with an inline error message	FR-003
AC-004	Files with disallowed types are rejected with an inline error message	FR-003
AC-005	Uploaded asset list shows preview, filename, size, and remove button	FR-004
AC-006	Recipe MDX documents the signed-URL handoff pattern	FR-005
AC-007	Stories demonstrate: empty state, file selected, uploading, complete, failed, rejected	FR-006
AC-008	Unit tests cover validation, progress state transitions, and cancel/retry	FR-007
AC-009	All recipe code passes TypeScript strict mode	NFR-002
AC-010	Object URLs are revoked on component unmount	NFR-005

LLM Handoff Instructions

Expected LLM Behavior

Follow the requirements and acceptance criteria in this document.
Do not expand scope beyond the In Scope section.
Respect the Out of Scope section.
Use the existing file-dropzone.tsx component; do not rebuild it.
The useFileUpload hook must accept a generic uploadFn so consumers can inject their own upload logic.
Use URL.createObjectURL for previews and revoke them on cleanup.
Throttle progress updates to avoid excessive re-renders.
The mock upload function should support configurable failure probability for testing error states.
Place the recipe in src/recipes/file-upload/ or a similar recipe folder.

LLM Should Not

Invent undocumented product behavior.
Implement real cloud storage uploads.
Add new dependencies without justification.
Change the existing file-dropzone.tsx component.
Skip object URL cleanup.
Perform real network requests in tests.

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Recipe with runnable folder, not a published package	Recipes give developers full control and understanding	David Holmes
2026-05-26	Generic `uploadFn` injection in `useFileUpload`	Keeps the hook testable and backend-agnostic	David Holmes
2026-05-26	Client-side validation only (no server-side)	Server-side validation is consumer responsibility; recipe focuses on the UI flow	David Holmes
2026-05-26	Signed-URL pattern documented, not implemented	Real implementation requires backend; recipe shows the contract	David Holmes

Document History

Date	Author	Change
2026-05-26	David Holmes	Initial draft