<bmx-upload>

<div class="row">
  <bmx-upload
    label="Proof of address"
    accept=".pdf,image/*"
    max-size="5242880"
    description="Held for the form to submit — no request of its own."
  ></bmx-upload>
</div>
<div class="row">
  <bmx-upload
    id="ex-upload-many"
    label="Supporting documents"
    multiple="true"
    max-files="6"
    accept=".pdf,.docx,image/*"
    max-size="10485760"
    concurrency="2"
    description="Uploaded as they arrive. Cancel one, or retry the one that fails."
  ></bmx-upload>
</div>
<script type="module">
  await customElements.whenDefined('bmx-upload');

  // `uploader` is a function, so it is a property. This one pretends to be a
  // server: it reports bytes on a timer, honours the abort signal, and fails
  // anything with "fail" in its name so the retry button has something to do.
  document.getElementById('ex-upload-many').uploader = ({ item, onProgress, signal }) =>
    new Promise((resolve, reject) => {
      let sent = 0;

      const timer = setInterval(() => {
        sent = Math.min(item.size, sent + item.size / 12);
        onProgress(sent);

        if (sent >= item.size) {
          clearInterval(timer);

          if (item.name.toLowerCase().includes('fail')) {
            reject(new Error('The file server rejected this document.'));
          } else {
            resolve({ url: `/files/${item.name}` });
          }
        }
      }, 180);

      // Without this the timer outlives the cancel and the row keeps moving
      // after the user has stopped it.
      signal.addEventListener('abort', () => {
        clearInterval(timer);
        reject(new Error('Cancelled.'));
      });
    });

  // A file dropped anywhere *outside* a drop zone makes the browser navigate to
  // it, taking the half-filled form with it. The component does not listen on
  // the document on your behalf - a component that changes the behaviour of a
  // whole page is worse than the problem - so a page with an upload on it is
  // worth adding these two lines to.
  for (const type of ['dragover', 'drop']) {
    addEventListener(type, event => {
      // The target is retargeted to the host for a drop inside the component's
      // shadow root, so this reaches its own zone as one element. It can also
      // be a text node on a drop over bare page text, which is why the type is
      // checked before `closest` is called on it.
      const over = event.target instanceof Element && event.target.closest('bmx-upload');

      if (!over) {
        event.preventDefault();
      }
    });
  }
</script>

WHAT IT DOES NOT DO

Talk to your server. It has no opinion about your endpoint, your authentication or your chunk protocol. Set url and a default XMLHttpRequest uploader is used; set uploader instead and it calls your function, with the file, a progress callback and an AbortSignal. Set neither and the component simply holds the files for the form to submit, which is the whole of what most forms need.

THE QUEUE IS THE COMPONENT

Everything interesting about an upload control is bookkeeping - per-file state, retry, cancel, removal, admitting forty files against a limit of three - and all of it lives in src/core/upload.ts as pure functions with unit tests. What is left here is a rendering of that queue and the two things that genuinely need a browser: the drag events and the transport.

FORM PARTICIPATION

The field submits its files as a FormData under its own name, one entry per file, which is precisely what <input type="file" multiple> does - so a server handler already written for a native file input needs no change.

It is also invalid while an upload is still running, and invalid if one failed. A form that can be submitted with a half-sent attachment is a form that will be, and the resulting record - a row referring to a file the file store never received - is the kind of defect nobody traces back to the upload control.

DRAG AND DROP

dragenter and dragleave fire for every descendant, so the highlight is driven by a depth count rather than by the last event seen; the naive version flickers the moment the pointer crosses a child. Drags carrying anything but files are ignored, so selected text dragged across the page does not light the zone up.

Folders are refused by name rather than uploaded. A directory dropped into a browser arrives as a zero-byte, typeless File, and sending that produces an empty file on the server with a plausible name on it - a corruption that is only ever noticed later.

One thing this does not do, deliberately: guard the rest of the page. A file dropped outside the zone makes the browser navigate to it, losing the form. Preventing that means listening on window, and a component that quietly changes the behaviour of the whole document is worse than the problem

• so a page that wants the guard adds four lines of its own, and the documentation shows them.

ACCESSIBILITY

• Dragging is never the only way to do anything: the zone's button opens the platform's own file picker, which meets SC 2.5.7 and is how most people will use it regardless.
• Every row's buttons are named for their file - "Remove report.pdf", not "Remove" repeated eleven times down a list.
• Refusals are announced in a live region present from the first render, and they name the file and the reason.
• The end of a run is summarised once, politely, rather than announcing forty individual completions over the top of whatever the user is reading.
• Removing a row moves focus to the row that took its place, so a keyboard user clearing a list is not returned to the top of the document each time.