GrFileUpload

accept goes both to the <input type="file"> and into the chain as the first validator. The attribute alone is not enough: it limits the system dialog, but anything at all can be dragged into the zone — without the validator an extra file would reach the server.

<GrFileUpload accept="image/*,.pdf" :request="upload" multiple show-file-list />

Beside it are capture (the camera on mobile) and directory (webkitdirectory, Chromium and Safari).

The component does not pass fallthrough attributes on to the input: class and style belong to the zone, and inheritAttrs: false would take them off it. The attributes of the input itself are declared as props explicitly.

showFileList shows the chosen files; each has a remove button, and retry() repeats the upload of the current set — after an error there is no need to choose the files again.

const uploader = ref<GrFileUploadInstance>()

uploader.value?.retry()
uploader.value?.removeFile(file) // removing aborts the upload in flight: it was about the previous set
uploader.value?.abort()

Removing the last file returns the state to idle: there is no point showing an error about a set that no longer exists.

Where the files go is set by exactly one of two props: action — a URL for a multipart POST, request — an uploader of your own. Pass both, and request does the sending while action takes part in nothing.

The “exactly one” requirement cannot be expressed by a type, and that is a limitation of Vue rather than an oversight: defineProps accepts an object type or an interface but not a discriminated union — the keys are flattened into one flat object, and vue-tsc lets through both “both at once” and “neither”. Both mistakes are therefore caught in a dev build with a warning in the console: without it the first would surface at the first choice of a file, and the second would not surface at all — a silently ignored action is indistinguishable in behaviour from one that was honoured.

uploadMode decides what exactly the set of files is:

• batch (the default) — the whole set leaves in one request (request(files, ctx)). There is one state for the set: there is nothing to say about an individual file, and it has no status;
• per-file — a request of its own for every file. request is then called with an array of one file: the contract does not change, and the consumer’s uploader (axios and the rest) keeps working with no edits.

In the per-file mode a row gets a status (pending/uploading/success/error) and a percentage, and the component gets retryFile(file) and abortFile(file):

<GrFileUpload
  upload-mode="per-file"
  :concurrency="3"
  :request="upload"
  multiple
  show-file-list
/>

concurrency (3 by default) limits the number of simultaneous requests: “per file” without it would mean “all at once”, and a hundred files would open a hundred connections.

The summary state is computed by the worst outcome: uploading while at least one is uploading; an error if after the finish there is at least one; a success when all are successful. The percentage is the mean across the files: a bar weighted by bytes would jerk backwards when a large file starts after a small one.

Cancelling one file is not an error: the row returns to the queue, and it can be retried or removed.

While a file is on its way, its row has one button — “stop” (the circle-stop icon, the name “Cancel upload of …”), and “remove” appears once the upload has been stopped or has finished: two identical crosses side by side cannot be told apart. A row of the list takes the full width of the column: the name is on the left and is truncated with an ellipsis (the full one is in title), the status and the buttons stand at a shared right edge — and in a narrow container a long name does not push them out.

The success, error and progress emits receive an optional trailing file argument — it exists only in the per-file mode.

The bar built on GrProgressBar shows itself while the sending is in progress, and after a success it holds for another hideProgressOnSuccess milliseconds — 800 by default. The delay is not cosmetic: a bar that vanishes in the same frame in which it reached the end reads as “the upload failed” rather than as “done”. 0 leaves the bar forever — that is the mode for a UI of your own that removes it itself.

showProgress: false switches the default bar off entirely: it is not needed when the progress is drawn by the #progress slot or when the files are small and the bar only has time to blink. progressTone colours it during the sending phase, and progressLabel gives it a name for a screen reader.

The component is generic over the answer: TResponse is inferred from request and types the payload of the success event — the any has left the public signature.

async function upload(files: File[]): Promise<UploadedFile> { /* … */ }

function onUploaded(file: UploadedFile) { /* the payload is typed */ }

<GrFileUpload :request="upload" @success="onUploaded" />

The type parameter is set exactly this way, through request: in an SFC template the syntax <GrFileUpload<UploadedFile>> does not exist — that is TSX, not a Vue template. The action branch does not govern the type of the answer: only the consumer knows what the server will return.

preview draws a thumbnail for image/* files in the list. The link (URL.createObjectURL) is revoked when a file is removed, when the set changes and on unmount: without that the blob hangs in the memory of the tab until a reload.

The thumbnail is decorative (alt="") — the name of the file is already beside it, and there is no point duplicating it for a screen reader.

<GrFileUpload v-model="files" :request="upload" show-file-list />

modelValue is optional: without it the component keeps the set itself. If it is passed, the set follows the prop and can be replaced or cleared from the outside, for instance after the form has been submitted.

update:modelValue is emitted when the set itself changes: a new choice or the removal of a file. It is not to be confused with change — that one means “the upload has finished”, and that is a different moment.

The difference from GrFormFile remains one of purpose rather than of having a model: GrFileUpload is about sending (action/request, progress, retry, per-file statuses), GrFormFile is about a form field.

action and request are a boundary of another kind: if both are set, request works; if neither is set, a dev build warns on mounting rather than at the first choice of a file. Expressing the requirement with a type (a discriminated union) is impossible in an SFC: defineProps accepts only an object type or an interface.

beforeUpload is a prop callback: it has to return “let it through or not”, and an emit returns no value. Everything else is emits: exceed (there are more files than limit), progress, success, error, change, stateChange.

:on-exceed="fn" keeps working: in Vue an emit also arrives as a listener prop.

• Two quick choices in a row overlap (the validators are asynchronous). The last one is always the current one: a run has a number, and the one that fell behind quietly leaves the race without cutting its neighbour’s upload short.
• On unmount the component aborts the active XHR and clears the timer that hides the success — otherwise the upload would keep going and the timer would jerk the state of a destroyed instance.
• A custom request is not obliged to call onProgress. The total volume is then taken from the sizes of the files rather than from zero: “100%” with total: 0 would be read by the consumer as “zero uploaded”.

The accessible control is the native <input type="file"> itself; the zone gets no widget role, otherwise the input inside it is lost for a screen reader (nested-interactive). The zone shows the focus of the input through focus-within, and disabled is dimmed with a background rather than with opacity: transparency dilutes text tokens tuned to AA.

disabled and readonly arrive both from GrFormField and from GrForm — not only from the props of the component. readonly really does forbid input: the set is visible and leaves with the form, but the dialog will not open and a drop will not be accepted. HTML has no readonly attribute for <input type="file">, so the system dialog is suppressed by cancelling the default action — the input stays in the Tab order and is announced as read-only.

The phases of the upload are announced by a live region (role="status") that exists from the first render: a region that appears already carrying text is not announced at all by some AT. The progress as a percentage does not go there — a screen reader would choke.