@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/FileUpload/FileUpload.tokens.scss

@@ -0,0 +1,81 @@
+// FileUpload.tokens.scss — component-scoped tokens for <FileUpload>. Covers the drop-zone, drag-over state, and per-row item chrome (border, status icon colors).
+:root {
+  // Root layout
+  --file-upload-gap: var(--space-3);
+
+  // Dropzone
+  --file-upload-dropzone-gap: var(--space-2);
+  --file-upload-dropzone-padding: var(--space-4);
+  --file-upload-dropzone-border-color: var(--color-border);
+  --file-upload-dropzone-radius: var(--radius-md);
+  --file-upload-dropzone-bg: var(--color-bg);
+  --file-upload-dropzone-fg: var(--color-fg-muted);
+  --file-upload-dropzone-border-color-hover: var(--color-accent);
+  --file-upload-dropzone-fg-hover: var(--color-fg);
+
+  // Drag-over (active drop target)
+  --file-upload-dragover-border-color: var(--color-accent);
+  --file-upload-dragover-bg: var(--color-accent-bg-subtle);
+  --file-upload-dragover-fg: var(--color-fg);
+
+  // Dropzone children
+  --file-upload-icon-fg: var(--color-fg-subtle);
+  --file-upload-label-font-size: var(--font-size-md);
+  --file-upload-hint-font-size: var(--font-size-sm);
+
+  // .dropzoneHint declares its own colour, so it wins over .dragOver's
+  // inherited --file-upload-dragover-fg -- the hint stays this colour through
+  // drag-over, whose --file-upload-dragover-bg is --color-accent-bg-subtle.
+  // The hint is --font-size-sm (12px), so WCAG AA small-text applies at 4.5:1;
+  // there is no large-text exemption to fall back on.
+  // #511: was --color-fg-subtle, well below AA there (3.97/3.61).
+  // --color-fg-muted was a substantial improvement that still missed AA in
+  // light, at 4.41, while dark cleared. #522 closed that at the PRIMITIVE
+  // rather than here: light --color-fg-muted moved #5e6c84 -> #5b6980, an
+  // imperceptible ΔE 0.0109 step that clears every light surface. So this
+  // token needed no change for #522 -- the annotations below moved, the
+  // declaration did not.
+  // --file-upload-icon-fg above is unaffected (icon, not text; separate
+  // token; not re-pointed).
+  // @contrast --color-fg-subtle on --color-accent-bg-subtle = 3.97:1 light
+  // @contrast --color-fg-subtle on --color-accent-bg-subtle = 3.61:1 dark
+  // @contrast --color-fg-muted on --color-accent-bg-subtle = 4.62:1 light
+  // @contrast --color-fg-muted on --color-accent-bg-subtle = 4.72:1 dark
+  --file-upload-hint-fg: var(--color-fg-muted);
+
+  // File list
+  --file-upload-list-gap: var(--space-2);
+
+  // Row — surface
+  --file-upload-row-gap: var(--space-3);
+  --file-upload-row-padding-y: var(--space-2);
+  --file-upload-row-padding-x: var(--space-3);
+  --file-upload-row-border-color: var(--color-border);
+  --file-upload-row-radius: var(--radius-md);
+  --file-upload-row-bg: var(--color-bg);
+
+  // Row — error variant
+  --file-upload-row-border-color-error: var(--color-danger);
+
+  // Row — status cell. The 4th grid column (`.rowStatus`) is `auto`-sized,
+  // which measures to 0 for an uploading row: <Progress> is `width: 100%`
+  // with no intrinsic size, so it has nothing to be 100% of (#588). This
+  // gives the uploading status cell a floor so the bar has somewhere to
+  // grow into. `--size-xl` is the closest existing shared size token to a
+  // sensible progress-bar minimum (80px) — no dedicated 80-120px token
+  // exists for this, so this reuses the primitive rather than inventing one.
+  --file-upload-progress-min-width: var(--size-xl);
+
+  // Row — text + icon colors
+  --file-upload-row-icon-fg: var(--color-fg-subtle);
+  --file-upload-row-name-font-size: var(--font-size-md);
+  --file-upload-row-name-fg: var(--color-fg);
+  --file-upload-row-meta-font-size: var(--font-size-sm);
+  --file-upload-row-meta-fg: var(--color-fg-subtle);
+  --file-upload-row-error-font-size: var(--font-size-sm);
+  --file-upload-row-error-fg: var(--color-danger);
+  --file-upload-row-done-fg: var(--color-success);
+
+  // Disabled state
+  --file-upload-opacity-disabled: var(--opacity-subtle);
+}

package/src/components/FileUpload/FileUpload.tsx

@@ -0,0 +1,569 @@
+import {
+  forwardRef,
+  useCallback,
+  useRef,
+  useEffect,
+  useState,
+  type DragEvent,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type ChangeEvent,
+  type ReactNode,
+  type MouseEvent,
+} from 'react';
+import { CloudUpload, Check, X } from 'lucide-react';
+import clsx from 'clsx';
+import { Button } from '../Button';
+import { Progress } from '../Progress';
+import { useTranslation } from '../../i18n/useTranslation';
+import { formatBytes } from './formatBytes';
+import { iconForFile } from './iconForFile';
+import styles from './FileUpload.module.scss';
+
+/** Lifecycle status for a file in the controlled `files` array. */
+export type FileUploadStatus = 'pending' | 'uploading' | 'done' | 'error';
+
+/** Reason a file was rejected by built-in or custom validation. */
+export type FileRejectReason = 'invalid-type' | 'too-large' | 'too-many' | 'duplicate' | 'custom';
+
+/** One entry in the controlled file list. */
+export interface FileEntry {
+  /**
+   * Stable ID for React keys and consumer bookkeeping. Consumer assigns
+   * (typically `crypto.randomUUID()` when handling `onFilesAdded`).
+   * File objects don't have stable identity in JS, so this is required.
+   */
+  id: string;
+  /** The underlying browser File. */
+  file: File;
+  /** Lifecycle status. Drives the per-row rendering. */
+  status: FileUploadStatus;
+  /**
+   * 0–100. Only meaningful when status='uploading' (renders via `<Progress>`).
+   * Ignored otherwise. Omitting it during upload renders the row with an
+   * indeterminate `<Progress>` (no value).
+   */
+  progress?: number;
+  /** Error message rendered when status='error'. */
+  error?: string;
+}
+
+export interface FileUploadProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  /**
+   * Placed on the hidden native `<input type="file">`, not the root — it is
+   * the only labelable element, so a `<label for>` (Field / SettingRow wire
+   * one) opens the file picker when clicked (#568). A `role="button"` div is
+   * not labelable, so the id on the dropzone would make the label click a no-op.
+   * While the dropzone is hidden (single mode with a file) the id falls back
+   * to the root, so scroll-to-id / focus-first-invalid still find the field.
+   */
+  id?: string;
+  /** Marks the dropzone `aria-invalid` for Field / SettingRow composition. @default false */
+  invalid?: boolean;
+  /**
+   * Consumed for Field / SettingRow composition (they render the visible
+   * required marker). Not forwarded: `role="button"` does not support
+   * `aria-required`, and native `required` on the hidden input would block
+   * form submission with an invisible bubble — your state owns the files.
+   */
+  required?: boolean;
+  /** Controlled file list. The component renders this; consumer owns the state. */
+  files: FileEntry[];
+  /**
+   * Called when the user drops or picks new files AND those files pass
+   * validation. The component does NOT mutate state — consumer is responsible
+   * for adding the returned `File[]` to `files` (typically wrapped in
+   * `FileEntry` shape with new IDs).
+   */
+  onFilesAdded: (files: File[]) => void;
+  /** Called when the user clicks the X on a file row. Consumer removes from `files`. */
+  onFileRemove: (entry: FileEntry) => void;
+  /**
+   * Called when a file fails validation. `reason` is one of `FileRejectReason`;
+   * `message` is the custom message from `validator` (only present when
+   * reason='custom'). Use for toasts or inline error rendering.
+   */
+  onFileReject?: (file: File, reason: FileRejectReason, message?: string) => void;
+  /**
+   * Allow multi-file selection. Default `false`. In single mode (default),
+   * `files` should have at most 1 entry; the dropzone hides once a file is
+   * present and re-appears after removal.
+   */
+  multiple?: boolean;
+  /**
+   * Accepted file types — MIME types and/or extensions, comma-separated.
+   * Forwarded to the native `<input accept>` attribute AND used for the
+   * built-in `invalid-type` validation. Default: no filter.
+   *
+   * Examples:
+   * - `accept="image/*"` — any image
+   * - `accept=".csv,application/vnd.ms-excel"` — CSV or Excel
+   * - `accept="application/pdf,image/png,image/jpeg"` — explicit MIME list
+   */
+  accept?: string;
+  /**
+   * Per-file size cap in bytes. Default: no limit.
+   * Files exceeding this fire `onFileReject` with reason `'too-large'`.
+   */
+  maxSize?: number;
+  /**
+   * Total file count cap. Only meaningful when `multiple=true`. Counts existing
+   * entries in `files` PLUS new files being added. Default: no limit.
+   * Excess files fire `onFileReject` with reason `'too-many'`.
+   */
+  maxFiles?: number;
+  /**
+   * Custom validation hook. Return `null` for valid; return a string error
+   * message for invalid (fires `onFileReject` with reason='custom', message=
+   * the returned string). Runs LAST in the validation chain (after type,
+   * size, count, duplicate checks).
+   */
+  validator?: (file: File) => string | null;
+  /**
+   * Disable the entire component. Dropzone shows muted, drag/click handlers
+   * are no-ops, remove buttons disabled. Default `false`.
+   */
+  disabled?: boolean;
+  /**
+   * Override the dropzone's main label. Default: the i18n value at
+   * `fileUpload.dragHint`. Pass a ReactNode for richer content (e.g. with a
+   * `<Code>` for accepted extensions).
+   *
+   * **A11y note:** when `dropzoneLabel` is a plain string, the component
+   * uses it as `aria-label` on the dropzone. When it's a ReactNode, the
+   * component falls back to the i18n value at `fileUpload.upload` and the
+   * rich content is visible-only. To give screen readers the equivalent
+   * text, pass `aria-label` via the spread (e.g. `aria-label="Upload CSV
+   * or Excel files"`).
+   *
+   * An EMPTY string counts as unset, not as an explicit blank — it drives both
+   * the visible label and the dropzone's `aria-label`, so an empty one left a
+   * `role="button"` with no accessible name.
+   */
+  dropzoneLabel?: ReactNode;
+  /**
+   * Override the dropzone icon. Default: lucide `CloudUpload` at 32px.
+   * Pass an SVG ReactNode or another icon component instance.
+   */
+  dropzoneIcon?: ReactNode;
+  /**
+   * Optional secondary line under the main label, typically describing
+   * accepted formats / size limits. Renders muted at `--font-size-sm`.
+   * Default: undefined (no secondary text).
+   */
+  dropzoneHint?: ReactNode;
+}
+
+const STATUS_CLASS: Record<FileUploadStatus, string> = {
+  pending: styles.rowPending,
+  uploading: styles.rowUploading,
+  done: styles.rowDone,
+  error: styles.rowError,
+};
+
+/**
+ * Match a single file against an `accept` attribute string. Handles MIME
+ * patterns (`image/*`, `application/pdf`) and extension patterns (`.csv`,
+ * `.pdf`). Returns true if the file matches any entry in the comma-separated
+ * accept list, false otherwise.
+ *
+ * Private to FileUpload — encapsulated so the validation pipeline doesn't
+ * sprout an ad-hoc regex.
+ */
+function matchesAccept(file: File, accept: string): boolean {
+  const tokens = accept
+    .split(',')
+    .map((t) => t.trim())
+    .filter(Boolean);
+  if (tokens.length === 0) return true;
+  const mime = file.type;
+  const ext = file.name.slice(file.name.lastIndexOf('.')).toLowerCase();
+  for (const token of tokens) {
+    if (token.startsWith('.')) {
+      // Extension match (case-insensitive)
+      if (ext === token.toLowerCase()) return true;
+    } else if (token.endsWith('/*')) {
+      // Wildcard MIME (image/*, video/*, etc.)
+      const prefix = token.slice(0, -1); // "image/"
+      if (mime.startsWith(prefix)) return true;
+    } else {
+      // Exact MIME match (case-sensitive per RFC)
+      if (mime === token) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Controlled, dropzone-style file picker with built-in validation and per-file status rows.
+ * @see docs/components/FileUpload.md
+ */
+export const FileUpload = forwardRef<HTMLDivElement, FileUploadProps>(function FileUpload(
+  {
+    files,
+    onFilesAdded,
+    onFileRemove,
+    onFileReject,
+    multiple = false,
+    accept,
+    maxSize,
+    maxFiles,
+    validator,
+    disabled = false,
+    dropzoneLabel,
+    dropzoneIcon,
+    dropzoneHint,
+    'aria-labelledby': ariaLabelledBy,
+    'aria-describedby': ariaDescribedBy,
+    id,
+    invalid = false,
+    // Consumed so it never lands on the root div (#568); see the prop's JSDoc.
+    required: _required = false,
+    className,
+    ...rest
+  },
+  ref,
+) {
+  const t = useTranslation();
+  const inputRef = useRef<HTMLInputElement>(null);
+  const dragCounter = useRef(0);
+  const [isDragOver, setIsDragOver] = useState(false);
+
+  // Batch announcement text. Derived from the controlled `files` array, and
+  // deferred so region and text never mount together.
+  const total = files.length;
+  const settled = files.filter((f) => f.status === 'done' || f.status === 'error').length;
+  const failed = files.filter((f) => f.status === 'error').length;
+  const inFlight = total > 0 && settled < total;
+  const [batchStatus, setBatchStatus] = useState('');
+  // A settled batch is only announced if this component SAW it in flight.
+  // Deriving it from `files` alone announced a batch that never happened: a
+  // form opened on an entity with three existing attachments mounted already
+  // settled, and the region went from '' to "Uploaded: 3 / 3" with nothing on
+  // screen having changed. Hard rule 10 rules that out directly — gate the
+  // region on what the user can SEE change, not on the raw prop.
+  //
+  // Tracked INSIDE the effect, not during render. Mutating a ref while
+  // rendering breaks React's purity rule and a discarded concurrent render
+  // would leave the flag set for a transfer the user never saw. In the effect
+  // the ordering still works: the in-flight pass sets it, and the pass that
+  // observes the batch settled reads what that earlier pass wrote.
+  //
+  // The IDS seen in flight, not a boolean. A boolean was reset only when the
+  // list emptied, so a controlled parent swapping one already-settled `files`
+  // array for another — switching entities on a shared instance after any
+  // upload — carried it across and announced the new entity's pre-existing
+  // attachments. That is the same defect this guard exists to close, surviving
+  // on the prop-change path. Announcing requires the batch on screen to be one
+  // this component actually watched.
+  // Keyed on the FILE OBJECT, not the id. Ids are the consumer's, and a
+  // consumer numbering them per entity — `f1`, `f2` — hands the next entity
+  // the same ones, which inherited the flag and announced its pre-existing
+  // attachments. That is the fourth defect in this guard and the third of the
+  // same shape, so it now keys on something the consumer cannot collide: the
+  // `File` instance itself. A WeakSet also fails SAFE — a consumer that
+  // rebuilds `File` objects per render simply never matches, and silence is
+  // the harmless direction.
+  const seenInFlight = useRef<WeakSet<File>>(new WeakSet());
+  /** Last counts this region reported, to tell a completion from a deletion. */
+  const lastAnnounced = useRef({ total: 0, settled: 0, failed: 0 });
+  // A signature that actually changes when the BATCH changes. Ids alone did
+  // not: swapping to another entity whose file has the same id, count and
+  // status left every dependency identical, so the effect never re-ran and the
+  // region kept the previous entity's text — the guard was correct and never
+  // got to run. Name and size distinguish the files behind equal ids.
+  const signature = files
+    .map((f) => `${f.id}:${f.file.name}:${f.file.size}:${f.status}`)
+    .join('\u0000');
+  useEffect(() => {
+    if (total === 0) {
+      seenInFlight.current = new WeakSet();
+      setBatchStatus('');
+      return;
+    }
+    // Only the files actually IN FLIGHT, not the whole batch. Recording all of
+    // them meant removing the last uploading row left a settled sibling still
+    // "seen", so a deletion announced "Uploaded: 1 / 1" for a transfer that
+    // never finished. Now the removal takes the watched id with it and the
+    // region stays silent.
+    if (inFlight)
+      for (const f of files)
+        if (f.status !== 'done' && f.status !== 'error') seenInFlight.current.add(f.file);
+    const watched = files.some((f) => seenInFlight.current.has(f.file));
+    // A SHRINKING batch is a deletion, not a completion. Removing the last
+    // in-flight row was fixed by tracking only in-flight files; removing a
+    // SETTLED sibling survived that, because a watched file remained and the
+    // counts simply recomputed — so deleting one of two finished uploads
+    // announced "Uploaded: 1 / 1." The premise was right and applied one row
+    // too narrowly: nothing settled, the array just got shorter.
+    const shrank = total < lastAnnounced.current.total;
+    const progressed =
+      settled > lastAnnounced.current.settled || failed > lastAnnounced.current.failed;
+    lastAnnounced.current = { total, settled, failed };
+    if (shrank && !progressed) {
+      // Cleared, not left alone: a deletion has nothing to report, and keeping
+      // the previous text would leave "Uploading: 1 / 2" describing a batch
+      // that no longer exists. Emptying a live region announces nothing.
+      setBatchStatus('');
+      return;
+    }
+    setBatchStatus(
+      inFlight
+        ? t('fileUpload.batchUploading', { done: settled, total })
+        : watched
+          ? t('fileUpload.batchSettled', { done: total - failed, total, failed })
+          : '',
+    );
+    // `signature` rather than `files`: a controlled parent commonly passes a
+    // new array identity for the same batch on every render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [inFlight, settled, total, failed, signature, t]);
+
+  const showDropzone = multiple || files.length === 0;
+  // In single mode the implicit cap is 1; multi mode uses maxFiles (Infinity if not set).
+  const effectiveMaxFiles = multiple ? (maxFiles ?? Infinity) : 1;
+
+  const processFiles = useCallback(
+    (incoming: File[]) => {
+      if (disabled) return;
+      const accepted: File[] = [];
+      let acceptedSoFar = 0;
+      for (const file of incoming) {
+        // 1. Type check
+        if (accept && !matchesAccept(file, accept)) {
+          onFileReject?.(file, 'invalid-type');
+          continue;
+        }
+        // 2. Size check
+        if (typeof maxSize === 'number' && file.size > maxSize) {
+          onFileReject?.(file, 'too-large');
+          continue;
+        }
+        // 3. Count check — counts existing entries + accepted-so-far in this batch.
+        if (files.length + acceptedSoFar >= effectiveMaxFiles) {
+          onFileReject?.(file, 'too-many');
+          continue;
+        }
+        // 4. Duplicate check — same name+size as an existing entry.
+        const isDuplicate = files.some(
+          (e) => e.file.name === file.name && e.file.size === file.size,
+        );
+        if (isDuplicate) {
+          onFileReject?.(file, 'duplicate');
+          continue;
+        }
+        // 5. Custom validator runs LAST.
+        if (validator) {
+          const message = validator(file);
+          if (message !== null) {
+            onFileReject?.(file, 'custom', message);
+            continue;
+          }
+        }
+        accepted.push(file);
+        acceptedSoFar++;
+      }
+      if (accepted.length > 0) {
+        onFilesAdded(accepted);
+      }
+    },
+    [accept, disabled, effectiveMaxFiles, files, maxSize, onFileReject, onFilesAdded, validator],
+  );
+
+  const handleDragEnter = useCallback(
+    (e: DragEvent<HTMLDivElement>) => {
+      if (disabled) return;
+      e.preventDefault();
+      dragCounter.current++;
+      if (dragCounter.current === 1) setIsDragOver(true);
+    },
+    [disabled],
+  );
+
+  const handleDragLeave = useCallback(
+    (e: DragEvent<HTMLDivElement>) => {
+      if (disabled) return;
+      e.preventDefault();
+      dragCounter.current = Math.max(0, dragCounter.current - 1);
+      if (dragCounter.current === 0) setIsDragOver(false);
+    },
+    [disabled],
+  );
+
+  const handleDragOver = useCallback(
+    (e: DragEvent<HTMLDivElement>) => {
+      // preventDefault on dragover signals "this is a valid drop target" — without
+      // it the drop event never fires.
+      if (disabled) return;
+      e.preventDefault();
+    },
+    [disabled],
+  );
+
+  const handleDrop = useCallback(
+    (e: DragEvent<HTMLDivElement>) => {
+      if (disabled) return;
+      e.preventDefault();
+      dragCounter.current = 0;
+      setIsDragOver(false);
+      const dropped = Array.from(e.dataTransfer.files);
+      if (dropped.length > 0) processFiles(dropped);
+    },
+    [disabled, processFiles],
+  );
+
+  const handleClick = useCallback(
+    (e: MouseEvent<HTMLDivElement>) => {
+      // A label-for click activates the input itself and bubbles here; the
+      // picker is already opening, so don't click it a second time.
+      if (disabled || e.target === inputRef.current) return;
+      inputRef.current?.click();
+    },
+    [disabled],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLDivElement>) => {
+      if (disabled) return;
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        inputRef.current?.click();
+      }
+    },
+    [disabled],
+  );
+
+  const handleInputChange = useCallback(
+    (e: ChangeEvent<HTMLInputElement>) => {
+      const picked = Array.from(e.target.files ?? []);
+      // Reset the input so the same file can be re-picked (browsers cache the
+      // last value; without this, picking the same file twice in a row doesn't
+      // fire change a second time).
+      e.target.value = '';
+      if (picked.length > 0) processFiles(picked);
+    },
+    [processFiles],
+  );
+
+  // {...rest} last so consumer overrides win (Pattern A).
+  return (
+    <div
+      ref={ref}
+      // The id belongs on the file input (see the prop); while the dropzone is
+      // hidden (single mode with a file) the root keeps it so scroll-to-id /
+      // focus-first-invalid still find the field.
+      id={showDropzone ? undefined : id}
+      className={clsx(styles.root, disabled && styles.disabled, className)}
+      {...rest}
+    >
+      {/* ONE region for the whole batch. Per-row regions were the obvious
+          shape and the wrong one: twelve files resolving inside two seconds is
+          twelve announcements. Rendered unconditionally with its text deferred
+          so a FileUpload that mounts mid-transfer still announces — see
+          CLAUDE.md Hard rule 10 and #502. */}
+      <span role="status" aria-live="polite" className={styles.srOnly}>
+        {batchStatus}
+      </span>
+      {showDropzone && (
+        <div
+          role="button"
+          tabIndex={disabled ? -1 : 0}
+          aria-labelledby={ariaLabelledBy}
+          // `dropzoneLabel &&`, not just the typeof: `dropzoneLabel=""` is a
+          // string, so without it the dropzone got a literal `aria-label=""`,
+          // which names nothing and falls through to name-from-content — where
+          // the label span is empty for the same reason. A role="button" with
+          // no accessible name (#535).
+          aria-label={
+            typeof dropzoneLabel === 'string' && dropzoneLabel
+              ? dropzoneLabel
+              : t('fileUpload.upload')
+          }
+          aria-describedby={ariaDescribedBy}
+          aria-invalid={invalid || undefined}
+          aria-disabled={disabled || undefined}
+          className={clsx(styles.dropzone, isDragOver && styles.dragOver)}
+          onDragEnter={handleDragEnter}
+          onDragOver={handleDragOver}
+          onDragLeave={handleDragLeave}
+          onDrop={handleDrop}
+          onClick={handleClick}
+          onKeyDown={handleKeyDown}
+        >
+          <input
+            ref={inputRef}
+            id={id}
+            type="file"
+            multiple={multiple}
+            accept={accept}
+            disabled={disabled}
+            onChange={handleInputChange}
+            className={styles.hiddenInput}
+            tabIndex={-1}
+            aria-hidden
+          />
+          <span className={styles.dropzoneIcon}>
+            {dropzoneIcon ?? <CloudUpload size={32} aria-hidden />}
+          </span>
+          <span className={styles.dropzoneLabel}>{dropzoneLabel || t('fileUpload.dragHint')}</span>
+          {dropzoneHint && <span className={styles.dropzoneHint}>{dropzoneHint}</span>}
+        </div>
+      )}
+      {files.length > 0 && (
+        <ul className={styles.list}>
+          {files.map((entry) => {
+            const Icon = iconForFile(entry.file);
+            return (
+              <li key={entry.id} className={clsx(styles.row, STATUS_CLASS[entry.status])}>
+                <span className={styles.rowIcon}>
+                  <Icon size={20} aria-hidden />
+                </span>
+                <span className={styles.rowName} title={entry.file.name}>
+                  {entry.file.name}
+                </span>
+                <span className={styles.rowMeta}>{formatBytes(entry.file.size)}</span>
+                <span className={styles.rowStatus}>
+                  {entry.status === 'uploading' && (
+                    <Progress
+                      size="sm"
+                      value={entry.progress}
+                      aria-label={t('fileUpload.uploadingAriaLabel', { name: entry.file.name })}
+                    />
+                  )}
+                  {entry.status === 'error' && entry.error && (
+                    <span className={styles.rowErrorMsg}>{entry.error}</span>
+                  )}
+                  {entry.status === 'done' && (
+                    <Check
+                      className={styles.rowDoneIcon}
+                      size={16}
+                      role="img"
+                      aria-label={t('fileUpload.done')}
+                    />
+                  )}
+                </span>
+                <Button
+                  variant="ghost"
+                  size="xs"
+                  iconOnly
+                  onClick={() => onFileRemove(entry)}
+                  disabled={disabled}
+                  // A failed row's message is plain text in a non-focusable
+                  // <li>, so a user tabbing here later learned nothing about
+                  // it. Fold the failure into the one name they DO reach.
+                  aria-label={
+                    entry.status === 'error'
+                      ? t('fileUpload.removeFailedAriaLabel', { name: entry.file.name })
+                      : t('fileUpload.removeAriaLabel', { name: entry.file.name })
+                  }
+                >
+                  <X size={16} aria-hidden />
+                </Button>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </div>
+  );
+});

package/src/components/FileUpload/formatBytes.ts

@@ -0,0 +1,34 @@
+/**
+ * Format a byte count into a human-readable string with a unit.
+ *
+ * Uses the 1024-based (KiB) convention internally but labels as `B`/`KB`/`MB`/
+ * `GB` for consumer familiarity — the CRM presents file sizes the way Finder /
+ * Explorer / Drive present them (1024 bytes = "1 KB"), not the SI 1000-base.
+ *
+ * Examples:
+ * - `formatBytes(0)` → `"0 B"`
+ * - `formatBytes(512)` → `"512 B"`
+ * - `formatBytes(1024)` → `"1 KB"`
+ * - `formatBytes(1536)` → `"1.5 KB"`
+ * - `formatBytes(1024 * 1024 * 1.5)` → `"1.5 MB"`
+ * - `formatBytes(1024 * 1024 * 1024 * 2.3)` → `"2.3 GB"`
+ *
+ * Bytes show as integers (no decimals). KB/MB/GB show as integers when whole,
+ * otherwise one decimal place.
+ *
+ * Private to the FileUpload directory — not re-exported from the package.
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return formatWithUnit(bytes / 1024, 'KB');
+  if (bytes < 1024 * 1024 * 1024) return formatWithUnit(bytes / (1024 * 1024), 'MB');
+  return formatWithUnit(bytes / (1024 * 1024 * 1024), 'GB');
+}
+
+function formatWithUnit(value: number, unit: string): string {
+  // Integer when whole; one decimal otherwise. Avoids "1.0 KB" while keeping
+  // "1.5 KB" / "2.3 GB" precision.
+  const rounded = Math.round(value * 10) / 10;
+  const display = Number.isInteger(rounded) ? rounded.toString() : rounded.toFixed(1);
+  return `${display} ${unit}`;
+}