@slotted/angular 0.0.0-stage → 0.1.0-beta.0

package/docs/upload.examples.md

@@ -0,0 +1,358 @@
+<!-- index: ./index.md -->
+# upload
+
+`data-ui="upload"` · Picks or drops files and shows their progress.
+
+## Examples
+
+### The three shapes one family has
+
+A drop region, a bare trigger and a control-height row. They are one axis rather than three families: the list, the summary and every per-row control below them are the same parts in all three, and only the region changes shape.
+
+Excerpt — not a complete module
+
+```html
+<div multiple slUpload variant="dropzone"></div>
+<div slUpload variant="button"></div>
+<div slUpload variant="field"></div>
+```
+
+### A column of rows, or a wall of pictures
+
+The same rows, arranged. An image set is read by looking rather than by reading, so the grid gives the preview the card, moves the controls onto the corner of the picture and puts the name underneath — and a file with no thumbnail shows its extension in words on the tile.
+
+Excerpt — not a complete module
+
+```html
+<div accept="image/*" label="Photographs of the damage" layout="grid" multiple slUpload></div>
+```
+
+### Three steps, and what moves with them
+
+The trigger height, the type, the glyphs, the chip and the row’s controls all step together, because every one of them reads a control token the theme restates per density. The insets come from the space scale and do not move, which is the cost card and alert both accepted.
+
+Excerpt — not a complete module
+
+```html
+<div size="sm" slUpload></div>
+<div size="md" slUpload></div>
+<div size="lg" slUpload></div>
+```
+
+### What is refused, and what the reader is told
+
+Nine reasons, each with its own sentence. accept filters the picker’s dialog and nothing else, so the family applies it to a drop as well — otherwise the same region accepts by drop what it refuses by picker. A refused file stays in the list rather than vanishing, because silence leaves the reader hunting for a file that never appeared.
+
+Excerpt — not a complete module
+
+```html
+<div
+  (reject)="warn($event)"
+  [maxFiles]="10"
+  [maxSize]="10 * 1024 * 1024"
+  [maxTotalSize]="50 * 1024 * 1024"
+  [minSize]="1"
+  accept="application/pdf,image/*"
+  multiple
+  slUpload
+></div>
+```
+
+### The same file, twice
+
+Identity is the name, the size and the modification time, and it is replaceable — because whether two files are the same file is a question about an application. reject refuses the second copy, allow keeps both, replace puts the new one in the old one’s place.
+
+Excerpt — not a complete module
+
+```html
+<div [fileKey]="byNameAndSize" duplicates="replace" multiple slUpload></div>
+```
+
+### A whole folder
+
+webkitdirectory reaches the input untouched and every file keeps its webkitRelativePath. A folder dropped into a region that does not accept folders is refused with the directory reason rather than added as a zero-byte row with the folder’s name on it, which is what the surveyed implementations do.
+
+Excerpt — not a complete module
+
+```html
+<div [maxFiles]="400" directory label="Scanned case file" multiple slUpload></div>
+```
+
+### Straight from the camera
+
+capture is the platform’s own attribute and the family forwards it: on a phone the picker opens a camera rather than a file browser. Nothing here is implemented by the family, which is the point — an adjuster standing beside a car photographs it.
+
+Excerpt — not a complete module
+
+```html
+<div accept="image/*" capture="environment" label="Photograph the damage" slUpload></div>
+```
+
+### Pasted rather than chosen
+
+Focus the region and press ⌘V or Ctrl+V: a screenshot on the clipboard is a file, and it is the keyboard’s only route to one that is not on disk. It runs through the same rules a drop and a picker do.
+
+Excerpt — not a complete module
+
+```html
+<div allowPaste label="Paste a screenshot" slUpload></div>
+```
+
+### The answer before the reader lets go
+
+DataTransfer.items gives an item’s kind and its type during a drag, and neither its name nor its size. Three of the five rules are answerable then and two are not, so a certain refusal is painted and a possible one is never: teaching the reader that the red edge means nothing would be worse than saying nothing.
+
+Excerpt — not a complete module
+
+```css
+/* A drag carrying files is anywhere over the document. */
+[data-ui='upload'][data-dragging] {
+}
+
+/* It is over this region, and it will be taken. */
+[data-ui='upload'] [data-part='dropzone'][data-drop-target] {
+}
+
+/* It is over this region, and it has already been refused. */
+[data-ui='upload'] [data-part='dropzone'][data-drop-invalid] {
+}
+```
+
+### Sending, with a real adapter
+
+The family calls an adapter and reports what it says — it holds no URL, no method, no header and no credential. createXhrUpload is the one this library ships, and it is XMLHttpRequest rather than fetch because fetch reports no upload progress in any browser this library supports.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [
+    provideUploadDefaults({
+      adapter: createXhrUpload({
+        url: '/api/claims/CLM-2026-0914/attachments',
+        headers: () => ({ Authorization: `Bearer ${token()}` }),
+      }),
+    }),
+  ],
+});
+```
+
+### The reader decides when it goes
+
+autoUpload off leaves every accepted file in ready with its own start control, for a form where the attachments should go with the submit rather than before it. Vaadin is the one surveyed implementation that ships the same switch.
+
+Excerpt — not a complete module
+
+```html
+<div #upload="slUpload" [autoUpload]="false" multiple slUpload></div>
+<button (click)="upload.upload()" type="button">Send the attachments</button>
+```
+
+### Nine files and three at a time
+
+Uppy alone among the surveyed implementations limits how many transfers run at once; Ant Design and Vaadin start every file together, which is how twelve files on a slow uplink all stall at the same moment. What is waiting says queued, and the summary carries the count and the time left.
+
+Excerpt — not a complete module
+
+```html
+<div [concurrency]="3" locale="pt-BR" multiple slUpload></div>
+```
+
+### When the server says no
+
+A failed row keeps its place, says Failed and offers to try again. Automatic retry ships and is off: an upload is a POST, and a POST that succeeded on the server and failed on the response is duplicated by a retry — a second invoice, a second attachment. A library may not choose that for an application.
+
+Excerpt — not a complete module
+
+```html
+<div [retries]="2" [retryDelay]="1000" multiple slUpload></div>
+```
+
+### Suspending a transfer that can be suspended
+
+The pause control is drawn only when the running adapter declares pausable, because one drawn over a sender that cannot suspend is a control that lies. An adapter that can suspend awaits context.whenResumed() between chunks; createXhrUpload cannot, and says so.
+
+Excerpt — not a complete module
+
+```ts
+const resumable = {
+  pausable: true,
+  async send(file, { signal, progress, whenResumed }) {
+    for (const chunk of chunksOf(file)) {
+      await whenResumed();
+      await put(chunk, { signal });
+      progress(chunk.end, file.size);
+    }
+  },
+};
+```
+
+### Stopping one, and taking one away
+
+Two different actions, kept apart. Cancel aborts the run through the adapter’s own AbortSignal and leaves the file in the list so it can be sent again; remove aborts it and takes the row out. Every surveyed implementation collapses the two into one control and one red row.
+
+Excerpt — not a complete module
+
+```ts
+const adapter = {
+  async send(file, { signal }) {
+    // The platform's own cancellation: XMLHttpRequest aborts, fetch aborts,
+    // and a hand-written sender checks signal.aborted between chunks.
+    const response = await fetch('/attachments', { body: file, method: 'POST', signal });
+    if (!response.ok) throw new Error(String(response.status));
+    return response.json();
+  },
+};
+```
+
+### A transfer that stops without failing
+
+Vaadin has the word stalled in its i18n object and nothing that produces it. Here the runner marks a run stalled when no progress arrives inside stallAfter and clears it on the next byte, so a bar sitting at 43% has something to read beside it.
+
+Excerpt — not a complete module
+
+```html
+<div [stallAfter]="10000" multiple slUpload></div>
+```
+
+### What the reader sees before they open anything
+
+An image gets a thumbnail from an object URL the family creates and revokes; everything else gets its kind’s tile. §14 of the feature guide requires the revocation by name, and two of the nine surveyed implementations leave it to the consumer.
+
+Excerpt — not a complete module
+
+```html
+<div layout="grid" multiple preview="auto" slUpload></div>
+<div multiple preview="none" slUpload></div>
+```
+
+### Opening a file without leaving the form
+
+Click a file’s name. The viewer is a composed sl-dialog with the file rendered inside it — an img, a video, an audio, or an iframe for a PDF and for text — and arrow keys move through the set, skipping what it cannot draw. A preview that opened a new tab was the first answer and it lost the form the reader was filling in.
+
+Excerpt — not a complete module
+
+```html
+<div [(viewing)]="openAttachment" multiple slUpload></div>
+<button (click)="openAttachment.set(key)" type="button">Open the police report</button>
+```
+
+### Nine kinds, nine colours
+
+A PDF red, a word-processed document blue, a spreadsheet green, a deck orange, a picture teal, a film indigo, a recording magenta, an archive amber. The colours are a scale of the theme’s rather than five tones stretched over nine kinds, because the tones hold no second blue and no indigo at all.
+
+Excerpt — not a complete module
+
+```css
+:root {
+  --slotted-upload-kind-pdf: #b3261e;
+  --slotted-upload-kind-document: #1a56db;
+  --slotted-upload-kind-spreadsheet: #0f7b3f;
+  --slotted-upload-kind-foreground: #ffffff;
+}
+```
+
+### Names the family did not choose
+
+A name two hundred characters long truncates in the middle so the extension survives; an Arabic name reads in its own direction inside a left-to-right page, because the name and its extension are one bidi-isolated run; and a refusal’s sentence wraps under the row without moving the chip or the controls.
+
+Excerpt — not a complete module
+
+```html
+<span data-part="filename" dir="auto">
+  <span data-part="name">2026-09-14-northgate-motors-consolidated-repair…</span>
+  <span data-part="extension">.pdf</span>
+</span>
+```
+
+### In the middle of a form
+
+A field above owns the label, the necessity mark, the description and the error slot, so the upload draws none of its own — two labels on one control is what a form gets otherwise. And a form submitted while the bytes are still moving is refused, which none of the nine surveyed implementations answers.
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Proof of ownership</label>
+  <div [formControl]="proof" [minFiles]="1" slUpload variant="field"></div>
+</div>
+
+<!-- proof.errors is { uploadPending: true } while the bytes are moving. -->
+```
+
+### Every state the contract declares
+
+Disabled refuses the picker and the drop alike, because a drag is not routed through the input at all. Read-only keeps the list readable and takes every control away. Invalid retargets the focus ring to the danger colour. Loading and complete are the queue’s own two, and they are on the root.
+
+Excerpt — not a complete module
+
+```html
+<div disabled slUpload></div>
+<div readOnly slUpload></div>
+<div invalid required slUpload></div>
+
+<!-- data-loading and data-complete are written by the queue, never by a prop. -->
+```
+
+### Everything, without a pointer
+
+Tab reaches the trigger, then each row’s name and its controls in order. Enter and Space open the picker from the control and activate the button focus is on. Ctrl+V pastes. Inside the viewer, arrows move through the set, Home and End jump to its ends and Escape closes it back onto the name that opened it.
+
+Excerpt — not a complete module
+
+```html
+<!-- WCAG 2.2 SC 2.5.7: every action reachable by dragging is reachable by
+     a single pointer action that is not a drag. The trigger is that action. -->
+<div allowDrop label="Supporting documents" multiple slUpload></div>
+```
+
+### Substituting what the family draws
+
+The directive attaches to the consumer’s own element, so the element is theirs and the identity, the axes and every state are written onto it. Projected content lands inside the root, and exportAs reaches the six actions a template cannot write.
+
+Excerpt — not a complete module
+
+```html
+<div #upload="slUpload" multiple slUpload>
+  <p>Documents are kept for seven years.</p>
+</div>
+
+<button (click)="upload.browse()" type="button">browse()</button>
+<button (click)="upload.retryAll()" type="button">retryAll()</button>
+<button (click)="upload.cancelAll()" type="button">cancelAll()</button>
+```
+
+### Deciding once for the whole application
+
+Where files go and how many run at once — set once in the injector rather than repeated on every form, which is how one of them ends up pointing somewhere else. An upload that states any of them itself still wins. What every control is called, what a refusal says and how the queue counts itself come from the language in force, and an upload lays its own messages over them.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [
+    provideSlotted({ locale: 'pt-BR', catalogs: { 'pt-BR': PT_BR } }),
+    provideUploadDefaults({ adapter, concurrency: 3 }),
+  ],
+});
+```
+
+### Writing a sender of your own
+
+The adapter is one function, or an object that also declares whether it can be paused. It is handed the file, an AbortSignal, a progress reporter and the pause handshake — which is everything a chunked or resumable sender needs from a control, and the reason chunking is not this family’s.
+
+Excerpt — not a complete module
+
+```ts
+type UploadAdapter = {
+  send(
+    file: File,
+    context: {
+      signal: AbortSignal;
+      progress(loaded: number, total?: number): void;
+      whenResumed(): Promise<void>;
+    },
+  ): Promise<unknown>;
+  pausable?: boolean;
+};
+```