Upload Panel

Install

pnpm exec vegastack-design verify upload-panel

pnpm dlx shadcn@4.21.0 add @vegastack/upload-panel

Usage

import { UploadPanel } from "@/components/ui/upload-panel";

// Mount once in the app shell, so uploads survive navigation.
<UploadPanel
  items={uploads.items}
  summary={uploads.summary}
  collapsed={collapsed}
  onCollapsedChange={setCollapsed}
  onCancel={uploads.cancel}
  onRetry={uploads.retry}
  onResume={uploads.chooseFileAgain}
  onOpen={(href) => router.push(href)}
  onCancelAll={uploads.cancelAll}
  onRetryFailed={uploads.retryFailed}
  onDismiss={uploads.clear}
/>;

The panel is presentational and controlled: the host's upload engine owns the queue, the bytes and the retries, and passes items (files, and folders with their files) and a summary (counts, bytes, timeLeftMs and the batch status). The time left comes from createRateEstimator in the upload-progress lib, which smooths acknowledged bytes and holds the estimate until it moves by more than 15%; formatTimeLeft turns it into "About 2 minutes left".

import {
  createRateEstimator,
  formatTimeLeft,
  formatBytesProgress,
} from "@/lib/upload-progress";

const estimator = createRateEstimator();
estimator.sample(bytesAcked, performance.now());
const timeLeftMs = estimator.timeLeftMs(
  total - bytesAcked,
  bytesAcked / total,
  performance.now(),
);

Scope

Anatomy

Examples

Collapsed

The chevron folds the list to the header, with one bar for the whole batch.

Folder

A folder upload is one row with its count and aggregate progress; its chevron expands the files. Cancel and Retry on the folder call back with the folder's id.

Errors

A failure keeps the panel open until the person acts: the reason under the name, Retry on the row and Retry failed below the list. An interrupted upload (the page reloaded mid-upload) asks for its file again with Choose file, and a cancelled one is muted.

Done

When everything finishes cleanly the panel shrinks into a done card that calls onDismiss after autoDismissMs (8 s), paused while it is hovered or focused. Its chevron reopens the list.

Phone

Below 768px the panel is a compact bar with the batch's progress; tapping it opens every row in a bottom sheet. compact asks for the bar at any width.

File types

FileTypeIcon resolves every row's icon and tint from one table: MIME type first, the extension when the type is missing or generic.

API Reference

UploadItem

UploadGroup

Accessibility

• The panel is a region named "Uploads"; the list is a list, and each folder's files a nested list.
• Each uploading row has a progressbar named by its file, with its percentage.
• A polite live region announces milestones only — "Uploading 3 items", "3 uploads complete", "1 upload failed" — never each percent.
• Cancel, Retry and Choose file are buttons named with the file. The cancel button takes the ring's place on hover or focus, and is always shown on a touch screen.
• Closing while uploads are moving opens an alert dialog with focus on "Keep uploading".
• The success check and the card's arrival collapse to their end state under reduced motion.

Do / Don't