Prepared Docs

Overview

FileUploadArea and FileUploadCard collect files under enforced constraints and surface progress, success, and failure honestly. Dispatch uses the pair for supervisor onboarding (bulk user CSV), protocol document imports, and evidence-grade audio attachments—contexts where a silent failure or an opaque error becomes an operational problem. The mental model is "drop it, see it, fix it": constraints are visible before the drop, progress is visible during, and the resulting status card stays on the page until the operator removes or retries it. Quiet auto-dismiss is the wrong shape for any file that matters.

When to use

For attachments with enforced MIME, size, or count policies

Evidence audio, protocol PDFs, user-roster CSVs, incident images. Upload UI is the place where the policy lives—surface it in the copy so operators aren't surprised by a server rejection.

For multi-file batches where each file has its own outcome

Uploading five files and having one fail: each should render as its own FileUploadCard with an independent status (uploading, success, error, removable) so the operator can retry or replace without starting over.

For workflows where validation must happen twice

Client-side checks for type, size, and count fail fast; server-side checks for content (audio duration, CSV schema, malware scans) arrive later. The card surface is where both conversations happen.

When not to use

For a single URL or path reference

Use Input. A drop target is overkill for text entry.

For purely programmatic ingestion

If there's no user in the loop, skip the UI and process server-side. File-upload UI exists to give a human a chance to see and fix.

For drag-only interactions with no browse fallback

Use a plain drop target. FileUpload pairs a drop affordance with a browse button because dispatch operators frequently paste file paths or pick from dialogs rather than drag from the desktop.

Variants

Variant	Purpose	Emphasis
`FileUploadArea`	Drop target + browse trigger	One per surface; the copy names what's allowed
`FileUploadCard`	One card per file-in-flight	Keep it visible until the operator removes or confirms
Custom `limitationsText`	Domain-specific rules beyond defaults	Use when the policy isn't obvious from MIME and size alone ("No audio over 10 minutes")

Composition

The area holds a headline, optional limitationsText (allowed types, size cap, count cap), and a browse button that triggers the native file picker. Cards render below or alongside the area, one per file, each with a status badge, filename, optional thumbnail, removal control, and—when applicable—a retry affordance.

Instructions

Lead with what's allowed, in plain language: "Drop a CSV up to 5 MB" rather than "application/csv, max 5000000 bytes". Spell out per-file and total caps separately; operators read one limit, not two unless you show two.

Error messages

Explain remediation in the same sentence as the failure ("File is 12 MB; try a smaller PDF or split it"). Include HTTP status only when it helps the user; prefer human-readable explanations backed by a dev log.

Content guidelines

Localize every string with formatMessage; test the longest translation inside the card's width.
Use consistent status language across the product: "Uploading", "Uploaded", "Upload failed", "Removed". Operators pattern-match the words across files.
Never show a success until the server confirms. For evidence-grade uploads, wait for the acknowledgment before changing the status—"Uploading…" staying visible a second longer is better than a false "Uploaded" that vanishes.
For sensitive deployments, never log file names or content to client analytics. Treat the surface as privacy-aware by default.

Behavior and states

Prerequisites unmet. Disable the area with a visible rationale when the operator isn't authenticated, the quota is exceeded, or the parent entity isn't ready. Silence is the wrong signal.
In-flight. Show per-card progress (determinate when the server streams it, indeterminate otherwise). Keep the area enabled for additional drops when the policy allows.
Success and failure. Surface either state on the card; don't migrate success into a toast and drop failure silently.
Removal. Animate card removal so the operator perceives the state change. For evidence-grade files, confirm removal when policy requires—irreversible deletes should not be a single click.
Retry. Offer retry on transient failures (network, 5xx). Surface a blocker on permanent failures (file type rejected) with copy that directs the operator to the fix.

Best practices

Support keyboard browse and paste where feasible. Dispatch operators drag from Outlook, paste paths from the CAD, and use the picker—support all three paths.
Enforce the same policy on the client and the server. The client check is for speed; the server check is for truth.
Surface server validation failures on the card, not in a remote toast. The file lives on the card; the verdict should too.
Keep the area available while a card is in-flight (when the count policy allows). Operators queue files; don't lock the room.

Don't

Claim success before server acknowledgment when integrity matters.
Show progress that never changes. A perpetual spinner is a maybe, not progress—switch to an indeterminate state that says so honestly.
Log file names or content to client analytics in sensitive deployments.
Auto-retry silently. Surface the retry so the operator can decide, especially for sensitive or billed uploads.

Accessibility

Drop targets, per-card status, and progress updates need deliberate labelling so screen readers can follow the state machine. Associate errors with the upload region; make the remove button keyboard operable; provide text alternatives for icon-only status. See Accessibility for the full contract including live-region patterns for progress and failure.

Drop target for drag-only shells without the card set.
Button for the browse trigger styling.
Progress for long-running determinate progress.
Snackbar for the final, transient "Uploaded" if the surface is already visible elsewhere—never as a substitute for the card.

Empty State / Accessibility

File Upload / API and Development

Overview

When to use

For attachments with enforced MIME, size, or count policies

For multi-file batches where each file has its own outcome

For workflows where validation must happen twice

When not to use

For a single URL or path reference

For purely programmatic ingestion

For drag-only interactions with no browse fallback

Overview

When to use

For attachments with enforced MIME, size, or count policies

Evidence audio, protocol PDFs, user-roster CSVs, incident images. Upload UI is the place where the policy lives—surface it in the copy so operators aren't surprised by a server rejection.

For multi-file batches where each file has its own outcome

For workflows where validation must happen twice

Client-side checks for type, size, and count fail fast; server-side checks for content (audio duration, CSV schema, malware scans) arrive later. The card surface is where both conversations happen.

When not to use

For a single URL or path reference

Use Input. A drop target is overkill for text entry.

For purely programmatic ingestion

If there's no user in the loop, skip the UI and process server-side. File-upload UI exists to give a human a chance to see and fix.

For drag-only interactions with no browse fallback

Use a plain drop target. FileUpload pairs a drop affordance with a browse button because dispatch operators frequently paste file paths or pick from dialogs rather than drag from the desktop.

Variants

Variant	Purpose	Emphasis
`FileUploadArea`	Drop target + browse trigger	One per surface; the copy names what's allowed
`FileUploadCard`	One card per file-in-flight	Keep it visible until the operator removes or confirms
Custom `limitationsText`	Domain-specific rules beyond defaults	Use when the policy isn't obvious from MIME and size alone ("No audio over 10 minutes")

Composition

Instructions

Error messages

Content guidelines

Localize every string with formatMessage; test the longest translation inside the card's width.
Use consistent status language across the product: "Uploading", "Uploaded", "Upload failed", "Removed". Operators pattern-match the words across files.
Never show a success until the server confirms. For evidence-grade uploads, wait for the acknowledgment before changing the status—"Uploading…" staying visible a second longer is better than a false "Uploaded" that vanishes.
For sensitive deployments, never log file names or content to client analytics. Treat the surface as privacy-aware by default.

Behavior and states

Prerequisites unmet. Disable the area with a visible rationale when the operator isn't authenticated, the quota is exceeded, or the parent entity isn't ready. Silence is the wrong signal.
In-flight. Show per-card progress (determinate when the server streams it, indeterminate otherwise). Keep the area enabled for additional drops when the policy allows.
Success and failure. Surface either state on the card; don't migrate success into a toast and drop failure silently.
Removal. Animate card removal so the operator perceives the state change. For evidence-grade files, confirm removal when policy requires—irreversible deletes should not be a single click.
Retry. Offer retry on transient failures (network, 5xx). Surface a blocker on permanent failures (file type rejected) with copy that directs the operator to the fix.

Best practices

Support keyboard browse and paste where feasible. Dispatch operators drag from Outlook, paste paths from the CAD, and use the picker—support all three paths.
Enforce the same policy on the client and the server. The client check is for speed; the server check is for truth.
Surface server validation failures on the card, not in a remote toast. The file lives on the card; the verdict should too.
Keep the area available while a card is in-flight (when the count policy allows). Operators queue files; don't lock the room.

Don't

Claim success before server acknowledgment when integrity matters.
Show progress that never changes. A perpetual spinner is a maybe, not progress—switch to an indeterminate state that says so honestly.
Log file names or content to client analytics in sensitive deployments.
Auto-retry silently. Surface the retry so the operator can decide, especially for sensitive or billed uploads.

Accessibility

Drop target for drag-only shells without the card set.
Button for the browse trigger styling.
Progress for long-running determinate progress.
Snackbar for the final, transient "Uploaded" if the surface is already visible elsewhere—never as a substitute for the card.