@reliability-design/web 1.4.6 → 1.4.8

package/dist/components/rel-upload/README.md

@@ -0,0 +1,220 @@
+# rel-upload
+
+File upload: `<rel-upload>` renders the dropzone, the format / size hint, the status alert and the per-file list (Figma "↳ File Upload" — `Upload Dropzone`, `Upload File Row`, `Upload Modal`), and `<rel-upload-actions>` renders the Cancel / Upload footer as a separate element so it can sit in `<rel-modal>`'s `footer` slot and stay pinned while the file list scrolls. Use it wherever users attach one or more files and need per-file progress, success and failure states; the pair runs either **controlled** (the component picks and validates, your app transfers) or **self-driving** (pass an `uploader` and the component runs the whole batch). For a plain native file field without a list, use `<input type="file">` directly.
+
+## Usage
+
+```html
+<!-- Controlled mode: pick + validate here, transfer in your app -->
+<rel-upload
+  id="docs"
+  accept=".pdf,.png,.jpg"
+  max-size="10MB"
+  multiple>
+</rel-upload>
+<rel-upload-actions for="docs"></rel-upload-actions>
+<script>
+  const upload = document.getElementById('docs');
+
+  upload.addEventListener('rel-upload', async (e) => {
+    for (const entry of e.detail.files) {
+      // Write progress / result back onto `files` — the rows re-render from it.
+      const patch = (partial) => {
+        upload.files = upload.files.map((f) => (f.id === entry.id ? { ...f, ...partial } : f));
+      };
+      patch({ status: 'uploading', progress: 0, loaded: 0 });
+      try {
+        await sendToServer(entry.file, (loaded) =>
+          patch({ loaded, progress: Math.round((loaded / entry.size) * 100) }));
+        patch({ status: 'success', progress: 100, loaded: entry.size });
+      } catch (err) {
+        patch({ status: 'error', error: err.message });
+      }
+    }
+  });
+</script>
+
+<!-- Self-driving mode: hand over an uploader and listen for the outcome -->
+<rel-upload id="photos" accept="image/*" max-size="5MB" multiple concurrency="2"></rel-upload>
+<rel-upload-actions for="photos"></rel-upload-actions>
+<script>
+  const photos = document.getElementById('photos');
+  photos.uploader = async (file, { signal, onProgress }) => {
+    // Any transport works; honour `signal` so Cancel aborts, call `onProgress(loaded, total)` for the bar.
+    await putWithProgress('/api/photos', file, { signal, onProgress });
+  };
+  photos.addEventListener('rel-complete', (e) => {
+    console.log('done', e.detail.succeeded.length, 'failed', e.detail.failed.length);
+  });
+</script>
+
+<!-- Inside rel-modal: body scrolls, footer stays pinned; the actions find the sibling upload automatically -->
+<rel-modal open side="center" title="Upload documents">
+  <rel-upload accept=".pdf" max-size="10MB" multiple></rel-upload>
+  <rel-upload-actions slot="footer"></rel-upload-actions>
+</rel-modal>
+
+<!-- Single file, custom copy, forward-only footer -->
+<rel-upload
+  id="avatar"
+  accept=".png,.jpg"
+  max-size="2MB"
+  dropzone-title="Drop your avatar here"
+  browse-label="Choose image"
+  hint="PNG or JPG, square, up to 2 MB">
+</rel-upload>
+<rel-upload-actions for="avatar" no-cancel></rel-upload-actions>
+
+<!-- Disabled -->
+<rel-upload disabled></rel-upload>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-upload.ts, rel-upload-actions.ts — do not edit; run readme-generate.mjs -->
+
+## Elements
+
+| Element | Class | Source |
+| --- | --- | --- |
+| `<rel-upload>` | `RelUpload` | `rel-upload.ts` |
+| `<rel-upload-actions>` | `RelUploadActions` | `rel-upload-actions.ts` |
+
+## API
+
+### `<rel-upload>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `accept` | `accept` | `string` | `""` | Comma-separated accept list, e.g. ".pdf,.png,.jpg" or "image/*". |
+| `maxSize` | `max-size` | `string` | `""` | Max size per file as a human string ("10MB", "500kb"). Empty → no limit. |
+| `multiple` | `multiple` | `boolean` | `false` | Allow more than one file. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the whole control. Reflected. |
+| `hint` | `hint` | `string` | `""` | Overrides the derived "PDF, PNG or JPG - up to 10 MB per file" hint. |
+| `dropzoneTitle` | `dropzone-title` | `string` | `"Drag and drop your files here"` | Dropzone headline. |
+| `browseLabel` | `browse-label` | `string` | `"Browse files"` | Browse button label. |
+| `files` | — | `UploadFile[]` | `[]` | The file list. Set it to drive the component in controlled mode; the component also maintains it itself as files are added and removed. Property only. |
+| `uploader` | — | `(file: File, ctx: UploaderContext) => Promise<void>` | `undefined` | Supply an `Uploader` `(file, { file, signal, onProgress }) => Promise<void>` to switch to self-driving mode: the component runs the batch itself with `concurrency`, progress, the delay alert, abort and retry. Unset (default) the component only emits intents. Property only. |
+| `concurrency` | `concurrency` | `number` | `3` | Max files transferred at once in self-driving mode. |
+| `delayThreshold` | `delay-threshold` | `number` | `15000` | ms of continuous uploading before the "taking longer than usual" alert. |
+
+#### Public fields / accessors
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `phase` | `UploadPhase` | Aggregate state. Read-only; corresponds to the Figma modal variants. `failed` means there is nothing left to send AND something errored — while any row is still `ready` the primary action is Upload, not Retry. |
+| `canUpload` | `boolean` | Whether the primary action is enabled: not disabled, nothing in flight, and either `ready` rows exist or (in the failed phase) at least one failed row can be retried. |
+| `primaryLabel` | `string` | Footer button label — "Upload", "Upload 3 files" or "Retry upload". |
+| `state` | `UploadState` | The snapshot `<rel-upload-actions>` renders from. |
+
+#### Methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `upload` | `upload()` | Start (or resume) the batch. Emits `rel-upload`; runs it when `uploader` is set. |
+| `retry` | `retry()` | Re-queue every retryable failed row and send again. |
+| `cancel` | `cancel()` | Abort anything in flight and emit `rel-cancel`. Does not clear the list. |
+| `removeFile` | `removeFile(id: string)` | Remove one row by id. |
+| `reset` | `reset()` | Clear everything and abort in-flight transfers. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-cancel` | — | bubbles / composed | Fired when Cancel is pressed (or `cancel()` is called); in-flight transfers are aborted, the list is kept. No detail. |
+| `rel-change` | `{ files: this.files }` | bubbles / composed | Fired whenever the file list changes (files added, a row removed, `reset()`). Detail: `{ files: UploadFile[] }`. |
+| `rel-complete` | `{ succeeded: this.files.filter((f) => f.status === "success"), failed: this.failedFiles, }` | bubbles / composed | Fired when the whole self-driving batch settles without being cancelled. Detail: `{ succeeded: UploadFile[], failed: UploadFile[] }`. |
+| `rel-file-complete` | `{ id: item.id, file: item.file }` | bubbles / composed | Fired when one file finishes uploading in self-driving mode. Detail: `{ id: string, file: File }`. |
+| `rel-file-error` | `{ id: item.id, file: item.file, error: message }` | bubbles / composed | Fired when one file's `uploader` rejects in self-driving mode. Detail: `{ id: string, file: File, error: string }`. |
+| `rel-files-added` | `{ added, rejected }` | bubbles / composed | Fired after files are picked or dropped and validated. Detail: `{ added: UploadFile[], rejected: UploadRejection[] }`. |
+| `rel-invalid` | `{ rejected }` | bubbles / composed | Fired just before `rel-files-added` when at least one picked file fails `accept` / `max-size`. Detail: `{ rejected: UploadRejection[] }`. |
+| `rel-progress` | `{ id: item.id, progress, loaded, total: t }` | bubbles / composed | Fired on every progress tick in self-driving mode. Detail: `{ id: string, progress: number (0–100), loaded: number, total: number }` (bytes). |
+| `rel-remove` | `{ id, file: target?.file }` | bubbles / composed | Fired when a row is removed via its delete button or `removeFile()`. Detail: `{ id: string, file?: File }`. |
+| `rel-retry` | `{ files: requeued }` | bubbles / composed | Fired when Retry re-queues the retryable failed rows. Detail: `{ files: UploadFile[] }`. |
+| `rel-state` | `s / this.state` | bubbles / composed | Fired when the derived `state` snapshot changes (and once after connecting). Detail: `UploadState`. |
+| `rel-upload` | `{ files: targets }` | bubbles / composed | Fired when Upload is pressed (or `upload()` is called) with the rows still `ready`; in controlled mode the app performs the transfer. Detail: `{ files: UploadFile[] }`. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `browse` | The `rel-button` that opens the file picker (Figma "Browse Button": Size=Medium, Style=Secondary). |
+
+### Tokens / CSS Variables
+
+#### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-upload-browse-hover-bg` | `transparent` | Background of the Browse button on hover. Defaults to `transparent`, which is what the underlying `rel-button` secondary style draws (Figma's outline button reacts on its border, not its fill), so this only takes effect when you set it. |
+
+### `<rel-upload-actions>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `for` | `for` | `string` | `""` | Id of the `<rel-upload>` to control. Omit to auto-discover a sibling. |
+| `cancelLabel` | `cancel-label` | `string` | `"Cancel"` | Cancel button label. |
+| `noCancel` | `no-cancel` | `boolean` | `false` | Hides Cancel for flows that only ever move forward. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-cancel` | — | bubbles / composed | Fired when the Cancel button is pressed, after `cancel()` has been called on the target `<rel-upload>`. No detail. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The right-aligned flex row holding the buttons |
+| `cancel` | The secondary Cancel `rel-button` (absent when `no-cancel` is set) |
+| `primary` | The primary Upload / Retry `rel-button` |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The dropzone itself is a mouse / drag-and-drop affordance only — it has no role and is not focusable, so no interactive control is nested inside another. The **Browse** `<button type="button">` is the only focusable control in the dropzone; it opens the hidden native `<input type="file">` (which carries `accept` and `multiple`).
+- The file rows container is `role="list"`. Each row shows a status icon with `role="img"` and an accessible name ("Uploaded" / "Failed") and a remove button labelled "Remove {file name}"; remove buttons are disabled while `disabled` is set.
+- Browse and remove buttons show a 2px `--rel-border-focus` focus ring on `:focus-visible`.
+- In `<rel-upload-actions>` the primary button is `disabled` whenever `canUpload` is false and, while a batch is in flight, shows `rel-button`'s `loading` state with `aria-label="Uploading"`.
+- Screen-reader announcements go through the shared `announce()` live region: "N file(s) added" (polite) and "N file(s) rejected" (assertive) after a pick or drop; the list heading whenever it changes — "Selected files (3)", "Uploading 3 files" (polite) or "3 files - 2 failed" (assertive); the alert text ("This is taking longer than usual…" / "We couldn't upload…") assertively when it appears; "{name} removed" after `removeFile()`; "File list cleared" after `reset()`.
+- Status colours are backed by the tokens `--rel-text-caption`, `--rel-text-success` and `--rel-text-danger` rather than the Figma hexes (see `UPLOAD-DESIGN-CHANGES.md` for the contrast rationale).
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move between Browse, each row's Remove button and the footer buttons (all native buttons) |
+| `Enter` / `Space` on Browse | Open the native file picker |
+| `Enter` / `Space` on Remove | Remove that row (`rel-remove` + `rel-change`) |
+| `Enter` / `Space` on Upload / Retry / Cancel | Call `upload()` / `retry()` / `cancel()` on the target `<rel-upload>` |
+
+## Notes / Edge Cases
+
+- **Modes.** Without `uploader` the component only emits intents (`rel-upload`, `rel-retry`, `rel-cancel`, `rel-remove`) and your app must write `status` / `progress` / `loaded` / `error` back onto `files` (replace the array — rows are keyed by `id`). With `uploader` the component patches `files` itself, runs up to `concurrency` transfers at once, emits `rel-progress` / `rel-file-complete` / `rel-file-error` per file and `rel-complete` when the batch settles.
+- **Validation happens on pick.** Files failing `accept` or `max-size` are kept as `error` rows ("unsupported file type" / "file exceeds the 10MB limit") — that is how the Figma Failure state surfaces them — and are reported in `rel-invalid` and `rel-files-added.rejected`. `retry()` skips rows that would fail validation again (and rows without a `file` object); if every failed row is unretryable the Retry button stays disabled — remove the row instead.
+- **`accept` tokens** are `.ext` (name suffix), `type/*` (MIME prefix) or an exact MIME type; the hint line is derived from them ("PDF, PNG or JPG") plus `max-size` ("- up to 10MB per file"). `max-size` accepts `b` / `kb` / `mb` / `gb` (decimal: 1MB = 1,000,000 bytes); an unparseable string means no limit.
+- **Same-named files replace** the existing entry instead of duplicating it. Without `multiple` only the first picked file is taken and it replaces the whole list.
+- **Phase.** `phase` is `failed` only when nothing is left to send AND something errored; while any row is still `ready` the primary action remains "Upload N files". `delayed` is entered after `delay-threshold` ms of continuous uploading (`0` disables the "taking longer than usual" alert) and shows a subtle warning `rel-alert`; failures show a subtle destructive `rel-alert`.
+- **Cancel** aborts the `AbortSignal` handed to `uploader` and returns in-flight rows to `ready`; it keeps the list. `reset()` aborts and clears everything.
+- **`rel-state` is de-duplicated** — it only fires when the derived snapshot (`phase`, counts, `canUpload`, `primaryLabel`) changes, so progress ticks do not spam `<rel-upload-actions>`; it also fires once right after connecting.
+- **Pairing.** `<rel-upload-actions>` resolves its target by `for` (an id in the same DOM root), else the first `<rel-upload>` in its parent element, else the first in its root. It listens for `rel-state` on its root node, so both elements must share the same document or shadow root — slotting the actions into `<rel-modal>`'s footer is fine because slotting does not change the root.
+- **Figma deviations.** The Browse button (not the whole dropzone) is the focusable control; the drag-over frame (solid brand border + 8% brand tint) and the disabled state (60% opacity) have no Figma frame; three colours were moved to the correct token layer for contrast. Details in `UPLOAD-DESIGN-CHANGES.md`.
+- The Browse hover background reads `--rel-upload-browse-hover-bg` and falls back to `--rel-action-neutral-outline-hover`, then `--rel-bg-surface-elevated`.