UploadQueue

Supplied transfer states

The queue renders the application's state. Request an action below, then use Supply requested result to deliver a training response. Invoking Cancel or Retry does not itself change the queue outcome.

<UploadQueue
  label="Import files"
  items={items}
  onCancel={requestCancel}
  onRetry={requestRetry}
  onRemove={requestRemove}
/>

UploadQueueItem contains id, name, sizeBytes and state. The supplied states are ready, queued, uploading, cancel-requested, uploaded, failed and canceled. A state outside that list shows as Unknown state, and a development build logs a structured INVALID_PROP_VALUE error naming it. Ready locally means a selected local file. Use Uploaded only after a transport reports acceptance. The component does not read files, start requests, estimate speed, or infer an outcome from elapsed time or byte count.

Progress and actions

Optional loadedBytes and totalBytes must be nonnegative safe integers with loaded bytes no greater than a known total. Byte counts are shown in full, and a count stays on the same line as its unit. Uploading and cancellation-requested rows show progress. An unknown total or missing loaded count is indeterminate; a zero total is stated without a percentage. Invalid counts show a readable error instead of a fabricated value. Optional message carries application feedback.

Every item uses a stable unique nonempty ID. Invalid IDs make actions unavailable. Actions require both the matching callback and an explicit capability:

• cancelable: offers Cancel for queued/uploading items. The host can supply cancel-requested while awaiting the actual transport outcome.
• retryable: offers Retry for failed items. The host owns duplicate prevention and later progress.
• removable: offers Remove wherever the application permits it. Removing a row is distinct from canceling a transport.

Callbacks receive the stable item ID. A declined request retains the row and its state. When a focused row/action is removed from the supplied items, or disabled (the queue is disabled, or duplicate IDs block its actions), focus goes to an enabled action in that or the next surviving row, that row itself, or the queue region when empty. If an action merely reports a request, its focus is retained. The application owns focus when removing the entire queue.

Props

The forwarded ref targets the named root div, which can receive programmatic focus. Native div attributes are supported. disabled blocks action requests while leaving supplied data visible.

Accessibility

• A named region contains a native file list. Every action names its file.
• Text Badge states preserve readable outcomes without relying on color or icons.
• A polite status announces only what changed: "Observation source 8.csv: Uploaded." for a row whose state or message changed, "Equipment.csv: Removed." for a removed row, and a count by state ("Uploaded: 4 files.") when more than three rows change at once. Nothing is announced on the first render, and byte ticks do not change the live message.
• Progress exposes known values or a true indeterminate state, named "Upload progress for" the file. It does not mark transfer completion.
• Buttons use native keyboard activation, token focus indicators and the project minimum target size.

Manifest entry

<UploadQueue label="Import files" items={files} onCancel={requestCancel} onRetry={requestRetry} onRemove={requestRemove} />

{
  "description": "Controlled file queue with supplied transfer states, byte progress and explicit recovery actions.",
  "props": {
    "label": {
      "type": "string",
      "required": true
    },
    "items": {
      "type": "array",
      "required": true,
      "description": "Readonly UploadQueueItem[] with unique id, name, sizeBytes, state (ready/queued/uploading/cancel-requested/uploaded/failed/canceled), optional loadedBytes/totalBytes/message and explicit cancelable/retryable/removable capabilities. Ready means local selection; uploaded requires a supplied transport outcome. Any other state shows as Unknown state."
    },
    "disabled": {
      "type": "boolean",
      "default": false
    },
    "onCancel": {
      "type": "function",
      "description": "Requests cancellation by stable ID only for explicitly cancelable queued/uploading items. Does not change supplied state."
    },
    "onRetry": {
      "type": "function",
      "description": "Requests retry by stable ID only for explicitly retryable failed items."
    },
    "onRemove": {
      "type": "function",
      "description": "Requests removal by stable ID only for explicitly removable items. The row remains until items changes; focus moves only when its focused element is removed."
    },
    "className": {
      "type": "string"
    }
  },
  "composable_with": [
    "FileUpload",
    "AttachmentPreview",
    "JobStatus"
  ],
  "never_inside": [
    "Button"
  ],
  "example": "<UploadQueue label=\"Import files\" items={files} onCancel={requestCancel} onRetry={requestRetry} onRemove={requestRemove} />"
}