@reliability-design/web 1.4.2 → 1.4.4

package/dist/components/rel-upload/UPLOAD-DESIGN-CHANGES.md

@@ -0,0 +1,134 @@
+# rel-upload — implementation vs. Figma, and what to update in the design
+
+**For:** design team · **From:** engineering · **Date:** 2026-08-09
+**Figma reference:** Reliability DS V1.0 → "↳ File Upload" page (node `8160:917`)
+— `Upload Dropzone` (`8160:2615`), `Upload File Row` (`8160:2566`), `Upload Modal` (`8160:2622`)
+**Shipped:** `<rel-upload>` + `<rel-upload-actions>` in `packages/web/src/components/rel-upload/`
+
+This replaces the previous version of this doc, which was written against the
+outdated sandbox design. Per our agreement, engineering adapted the design where
+it had gaps or conflicted with how the design system already works — everything
+that differs is listed here so the Figma file can be brought in line.
+
+---
+
+## What matches the Figma exactly
+
+- **Dropzone**: 16px radius, dashed border, 32/24 padding, circular icon badge,
+  "Drag and drop your files here" (16/24 medium) over the format/size hint
+  (12/20), pill "Browse files" button.
+- **File rows**: 8px radius, 12/16 padding, document icon → name (14/22) + meta
+  (12/20) → trailing status icon + remove. All four states (Ready, Uploading,
+  Success, Error) including the tinted error row.
+- **Progress bar**: 4px, fully rounded, green fill, with the
+  `45% - 2.4 MB of 5.1 MB` meta line.
+- **Modal**: composed from the existing `<rel-modal>` — title, supporting text,
+  close ×, scrolling body, pinned footer. All six variants are reproduced.
+- **Copy**: every string in the design ships verbatim, including
+  `Selected files (3)`, `Uploading 3 files`, `3 files - 2 failed`,
+  `Upload 3 files`, `Retry upload`, and both alert messages.
+
+The hint row is driven by real props: formats come from `accept`, the size limit
+from `max-size`. The design's "PDF, PNG or JPG" / "10 MB" are example values.
+
+## Colour changes the design should adopt
+
+All three are contrast or token-layer corrections. Every hex in the design
+already exists in `vars.css`, but three of them are used at the wrong layer.
+
+### 1. Secondary text `#7D7D7D` → `--rel-text-caption` `#525252`
+
+`#7D7D7D` (gray-400) scores **4.12:1 on white — below the 4.5:1 gate**, and in
+the token system gray-400 is not a body-text token at all. Used for the dropzone
+hint and the file-row meta line. `--rel-text-caption` (`#525252`) scores
+**7.81:1**.
+
+### 2. Success text `#008655` → `--rel-text-success` `#006440`
+
+Green-600 passes (4.62:1) but the system's success-text token is green-700
+(**7.25:1**), and the green rule fixes success text/icons at `#006440`. Affects
+the "…- Uploaded" meta line and the success check icon.
+
+### 3. Dashed dropzone border `#C2C2C2` → `--rel-border-accent` `#8C8C8C`
+
+`#C2C2C2` scores **1.78:1**, under the 3:1 gate for UI boundaries, and gray-200
+has no border token. `--rel-border-accent` (gray-350) scores **3.36:1**.
+
+Also note: the error row border uses `--rel-border-danger` (`#CE3131`, 5.11:1)
+rather than the design's `#FF5252` (3.19:1) — red-500 has no border token.
+And the error meta on the tinted row (`#CE3131` on `#FFEBEB`) lands at
+**4.46:1**, marginally under. That pairing is inherited from the existing
+`rel-alert` subtle-error style, so it is a system-wide question rather than
+something this component introduced — flagging it, not changing it here.
+
+## Structural changes
+
+### 4. The footer is a separate element, not part of the upload body
+
+In the Figma the Cancel/Upload row sits in the Modal Sheet, outside the slot
+holding the upload body. We matched that: `<rel-upload>` renders the alert,
+dropzone and file list; `<rel-upload-actions>` renders the buttons and goes in
+`<rel-modal>`'s footer slot. This is what keeps the footer **pinned while the
+file list scrolls** — with five files the body scrolls and the buttons stay put.
+The actions element finds its `<rel-upload>` sibling automatically.
+
+### 5. The dropzone is not itself a button
+
+The design puts a "Browse files" button inside the dropzone. Making the whole
+dropzone clickable *and* focusable would nest interactive controls inside each
+other, which is an accessibility violation. The dropzone stays a drag-and-drop
+target and a mouse click affordance, but "Browse files" is the only focusable
+control — so keyboard and screen-reader users get exactly one clear action.
+
+### 6. Buttons and the alert are the standard DS components
+
+Cancel/Upload are `rel-button`, and both alerts are `rel-alert` (warning and
+error, subtle). They inherit the system's colours, states and focus rings rather
+than the frame's local styles. One visible consequence: the design draws the
+buttons as pills, which `rel-button` supports, but the disabled Upload uses the
+system's disabled fill rather than the frame's dimmed grey. If design prefers the
+dimmed look, that is a change to the *button* spec, not to upload.
+
+## Behaviour the design doesn't specify
+
+### 7. Validation failures render as error rows
+
+The Figma Failure state shows rows reading "Upload failed - file exceeds the
+10 MB limit" and "Upload failed - unsupported file type". Both are knowable
+*before* any transfer, so we surface rejected files as error rows immediately on
+drop rather than silently discarding them. The wording is unchanged.
+
+### 8. Retry only re-sends what can succeed
+
+A file rejected for format or size will fail identically every time, so
+"Retry upload" skips it — and if *every* failure is of that kind the button is
+disabled. Removing the offending row returns the card to the normal Upload state.
+
+### 9. "Upload" wins over "Retry" while anything is still pending
+
+If some rows failed but others are still ready, the primary action stays
+"Upload N files". Retry only appears once there is nothing left to send. The
+Figma Multi-upload and Failure frames are both consistent with this.
+
+## States still missing from the Figma
+
+These are implemented, but no frame specs them:
+
+| State | What ships today |
+| ----- | ---------------- |
+| **Drag-over** | Dashed border becomes solid brand green, surface takes an 8% brand tint |
+| **Disabled** | Whole card at 60% opacity, nothing interactive |
+| **Dark mode** | Works automatically — every colour is a semantic token |
+
+A frame for each (drag-over especially) would make the set complete.
+
+## Suggested Figma additions
+
+1. Drag-over variant
+2. Disabled variant
+3. Dark reference frame
+4. Apply the three colour corrections above to the shared styles
+
+Questions and pushback welcome — none of this is precious, but items 1–3 and 5
+fix measurable contrast or accessibility problems, so if the design goes a
+different way it needs to solve those rather than reverting.

package/dist/components/rel-upload/rel-upload-actions.ts

@@ -0,0 +1,163 @@
+import { LitElement, html, css, nothing } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+import "@reliability-design/icons/rel-icon";
+import "../rel-button/rel-button";
+import type { RelUpload, UploadState } from "./rel-upload";
+
+const EMPTY_STATE: UploadState = {
+  phase: "empty",
+  total: 0,
+  failed: 0,
+  canUpload: false,
+  primaryLabel: "Upload",
+};
+
+/**
+ * `<rel-upload-actions>` — the Cancel / Upload footer for `<rel-upload>`.
+ *
+ * Lives outside `<rel-upload>` so it can sit in `<rel-modal>`'s footer slot and
+ * stay pinned while the upload body scrolls. It mirrors the sibling
+ * `<rel-upload>`'s derived state, so the button label follows the design:
+ * "Upload" → "Upload 3 files" → spinner → "Retry upload".
+ *
+ * ```html
+ * <rel-modal open side="center" title="Upload documents">
+ *   <rel-upload multiple .uploader=${fn}></rel-upload>
+ *   <rel-upload-actions slot="footer"></rel-upload-actions>
+ * </rel-modal>
+ * ```
+ *
+ * The target is found automatically among its siblings. Use `for` to point at a
+ * specific `<rel-upload>` by id when a container holds more than one.
+ *
+ * @element rel-upload-actions
+ */
+@customElement("rel-upload-actions")
+export class RelUploadActions extends LitElement {
+  /** Id of the `<rel-upload>` to control. Omit to auto-discover a sibling. */
+  @property({ type: String }) for = "";
+
+  /** Cancel button label. */
+  @property({ type: String, attribute: "cancel-label" }) cancelLabel = "Cancel";
+
+  /** Hides Cancel for flows that only ever move forward. */
+  @property({ type: Boolean, attribute: "no-cancel" }) noCancel = false;
+
+  @state() private snapshot: UploadState = EMPTY_STATE;
+
+  private target: RelUpload | null = null;
+
+  static styles = css`
+    :host {
+      display: block;
+      font-family: var(--rel-fonts-font-family);
+    }
+
+    .actions {
+      display: flex;
+      align-items: center;
+      justify-content: flex-end;
+      gap: var(--rel-spacing-xs, 8px);
+    }
+
+    rel-button rel-icon {
+      margin-inline-end: var(--rel-spacing-xs, 8px);
+    }
+  `;
+
+  connectedCallback() {
+    super.connectedCallback();
+    // Siblings may not be upgraded yet when the footer slot connects first.
+    queueMicrotask(() => this.resolveTarget());
+    this.root.addEventListener("rel-state", this.onState as EventListener);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.root.removeEventListener("rel-state", this.onState as EventListener);
+    this.target = null;
+  }
+
+  updated(changed: Map<string, unknown>) {
+    if (changed.has("for")) this.resolveTarget();
+  }
+
+  /**
+   * Listen on our own root rather than `document`: a shared root means no
+   * shadow boundary sits between us and the sibling `<rel-upload>`, so
+   * `event.target` is never retargeted away from it.
+   */
+  private get root(): Document | ShadowRoot {
+    const node = this.getRootNode();
+    return node instanceof ShadowRoot ? node : this.ownerDocument;
+  }
+
+  private resolveTarget() {
+    const root = this.getRootNode() as ParentNode;
+    let found: RelUpload | null = null;
+
+    if (this.for) {
+      found = root.querySelector<RelUpload>(`#${CSS.escape(this.for)}`);
+    } else {
+      found =
+        this.parentElement?.querySelector<RelUpload>("rel-upload") ??
+        root.querySelector<RelUpload>("rel-upload");
+    }
+
+    this.target = found;
+    if (found) this.snapshot = found.state;
+  }
+
+  private onState = (e: CustomEvent<UploadState>) => {
+    if (!this.target) this.resolveTarget();
+    if (e.target !== this.target) return;
+    this.snapshot = e.detail;
+  };
+
+  private onCancel = () => {
+    this.target?.cancel();
+    this.dispatchEvent(new CustomEvent("rel-cancel", { bubbles: true, composed: true }));
+  };
+
+  private onPrimary = () => {
+    if (!this.target) return;
+    if (this.snapshot.phase === "failed") this.target.retry();
+    else this.target.upload();
+  };
+
+  render() {
+    const { phase, canUpload, primaryLabel } = this.snapshot;
+    const busy = phase === "uploading" || phase === "delayed";
+
+    return html`
+      <div class="actions" part="base">
+        ${this.noCancel
+          ? nothing
+          : html`<rel-button part="cancel" variant="secondary" @click=${this.onCancel}>
+              ${this.cancelLabel}
+            </rel-button>`}
+
+        <rel-button
+          part="primary"
+          variant="primary"
+          ?loading=${busy}
+          ?disabled=${!canUpload}
+          aria-label=${busy ? "Uploading" : primaryLabel}
+          @click=${this.onPrimary}
+        >
+          ${busy
+            ? nothing
+            : html`${phase === "failed"
+                  ? html`<rel-icon name="refresh" size="sm"></rel-icon>`
+                  : nothing}${primaryLabel}`}
+        </rel-button>
+      </div>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "rel-upload-actions": RelUploadActions;
+  }
+}