@dowel-ui/react 0.2.0 → 0.3.0

package/src/components/file-upload/file-upload.tsx

@@ -0,0 +1,322 @@
+"use client";
+
+import {
+  useId,
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+  type DragEvent,
+  type ReactNode,
+} from "react";
+
+import { disabledStyles, focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+import { formatBytes, type QueuedFile, type UploadStatus } from "./upload-queue";
+
+/**
+ * The visible half of uploading. The queue is in `upload-queue.ts` and is the
+ * part worth owning.
+ *
+ * There is no dropzone pattern in the WAI-ARIA APG, and inventing one is the
+ * usual failure: a `div` with `role="button"`, a keydown handler, and a file
+ * picker that keyboard users can never reach. So the control here is a real
+ * `<input type="file">` with a real `<label>`. That is already operable by
+ * keyboard, already announces itself, already opens the picker on Enter and
+ * Space, and needs nothing added. Drag and drop is layered on top as a pointer
+ * convenience, and every drop can also be done from the input.
+ */
+
+const STATUS_LABEL: Record<UploadStatus, string> = {
+  queued: "Waiting",
+  uploading: "Uploading",
+  done: "Uploaded",
+  failed: "Failed",
+  cancelled: "Cancelled",
+};
+
+export interface FileUploadProps extends Omit<ComponentPropsWithRef<"div">, "onDrop"> {
+  /** Names the control. */
+  label: string;
+  onFiles: (files: File[]) => void;
+  accept?: string;
+  multiple?: boolean;
+  disabled?: boolean;
+  /** Shown under the prompt: accepted types, size limit. */
+  hint?: ReactNode;
+  children?: ReactNode;
+}
+
+export function FileUpload({
+  className,
+  label,
+  onFiles,
+  accept,
+  multiple = true,
+  disabled = false,
+  hint,
+  children,
+  ...props
+}: FileUploadProps) {
+  const inputId = useId();
+  const hintId = useId();
+  const [dragging, setDragging] = useState(false);
+  const depth = useRef(0);
+
+  function handleDrop(event: DragEvent<HTMLDivElement>) {
+    event.preventDefault();
+    depth.current = 0;
+    setDragging(false);
+    if (disabled) return;
+
+    const dropped = [...event.dataTransfer.files];
+    if (dropped.length > 0) onFiles(multiple ? dropped : dropped.slice(0, 1));
+  }
+
+  return (
+    <div data-slot="file-upload" className={cn("flex flex-col gap-3", className)} {...props}>
+      {/* dragenter/dragleave fire for every child element, so a plain boolean
+          flickers as the pointer crosses the prompt text. Counting depth is
+          what makes the highlight steady. */}
+      <div
+        data-slot="file-upload-dropzone"
+        data-dragging={dragging || undefined}
+        onDragEnter={(event) => {
+          event.preventDefault();
+          depth.current += 1;
+          if (!disabled) setDragging(true);
+        }}
+        onDragLeave={() => {
+          depth.current -= 1;
+          if (depth.current <= 0) setDragging(false);
+        }}
+        onDragOver={(event) => {
+          event.preventDefault();
+        }}
+        onDrop={handleDrop}
+        className={cn(
+          "rounded-lg border border-dashed border-border-strong bg-muted/30 px-4 py-6 text-center",
+          "transition-colors duration-[var(--duration-fast)]",
+          dragging && "border-primary bg-primary/5",
+          disabled && "pointer-events-none opacity-55",
+        )}
+      >
+        {/* The label is the control. Clicking it opens the picker, Enter and
+            Space activate it, and assistive technology already describes it. */}
+        <label
+          htmlFor={inputId}
+          className={cn(
+            "inline-flex cursor-pointer flex-col items-center gap-1 rounded-md px-2 py-1 text-sm",
+            "focus-within:ring-2 focus-within:ring-ring/55",
+          )}
+        >
+          <span className="font-medium">{label}</span>
+          <span className="text-xs text-muted-foreground">
+            Drop {multiple ? "files" : "a file"} here, or choose from your device
+          </span>
+          <input
+            id={inputId}
+            type="file"
+            accept={accept}
+            multiple={multiple}
+            disabled={disabled}
+            aria-describedby={hint ? hintId : undefined}
+            onChange={(event) => {
+              const chosen = [...(event.target.files ?? [])];
+              if (chosen.length > 0) onFiles(chosen);
+              // Reset, so choosing the same file twice fires change twice.
+              event.target.value = "";
+            }}
+            className="sr-only"
+          />
+        </label>
+
+        {hint ? (
+          <p id={hintId} className="mt-2 text-xs text-muted-foreground">
+            {hint}
+          </p>
+        ) : null}
+      </div>
+
+      {children}
+    </div>
+  );
+}
+
+export interface FileUploadListProps extends ComponentPropsWithRef<"ul"> {
+  files: QueuedFile[];
+  onCancel?: (id: string) => void;
+  onRetry?: (id: string) => void;
+  onRemove?: (id: string) => void;
+}
+
+export function FileUploadList({
+  className,
+  files,
+  onCancel,
+  onRetry,
+  onRemove,
+  ...props
+}: FileUploadListProps) {
+  if (files.length === 0) return null;
+
+  return (
+    <ul
+      data-slot="file-upload-list"
+      className={cn("flex list-none flex-col gap-2", className)}
+      {...props}
+    >
+      {files.map((entry) => (
+        <FileUploadItem
+          key={entry.id}
+          entry={entry}
+          onCancel={onCancel}
+          onRetry={onRetry}
+          onRemove={onRemove}
+        />
+      ))}
+    </ul>
+  );
+}
+
+export interface FileUploadItemProps extends Omit<ComponentPropsWithRef<"li">, "children"> {
+  entry: QueuedFile;
+  onCancel?: (id: string) => void;
+  onRetry?: (id: string) => void;
+  onRemove?: (id: string) => void;
+}
+
+export function FileUploadItem({
+  className,
+  entry,
+  onCancel,
+  onRetry,
+  onRemove,
+  ...props
+}: FileUploadItemProps) {
+  const { id, file, status, progress, error } = entry;
+  const percent = progress === null ? null : Math.round(progress * 100);
+
+  return (
+    <li
+      data-slot="file-upload-item"
+      data-status={status}
+      className={cn(
+        "flex items-center gap-3 rounded-lg border px-3 py-2 text-sm",
+        status === "failed"
+          ? "border-destructive/40 bg-destructive/5"
+          : "border-border bg-card",
+        className,
+      )}
+      {...props}
+    >
+      <div className="flex min-w-0 flex-1 flex-col gap-1">
+        <div className="flex items-baseline justify-between gap-2">
+          <span className="truncate font-medium">{file.name}</span>
+          <span className="shrink-0 text-xs text-muted-foreground tabular-nums">
+            {formatBytes(file.size)}
+          </span>
+        </div>
+
+        {/* Status in words, always. A bar at 60% with a red tint does not say
+            whether it is uploading, stalled or failed. */}
+        <p
+          className={cn(
+            "text-xs",
+            status === "failed" ? "text-destructive" : "text-muted-foreground",
+          )}
+        >
+          {STATUS_LABEL[status]}
+          {status === "uploading" && percent !== null ? ` · ${String(percent)}%` : null}
+          {error ? ` · ${error}` : null}
+        </p>
+
+        {status === "uploading" ? (
+          <div
+            role="progressbar"
+            aria-label={`Uploading ${file.name}`}
+            aria-valuenow={percent ?? undefined}
+            aria-valuemin={0}
+            aria-valuemax={100}
+            className="h-1 w-full overflow-hidden rounded-full bg-muted"
+          >
+            <div
+              data-slot="file-upload-progress"
+              className="h-full rounded-full bg-primary transition-[width] duration-[var(--duration-normal)] ease-[var(--ease-out-quint)]"
+              style={{ width: `${String(percent ?? 0)}%` }}
+            />
+          </div>
+        ) : null}
+      </div>
+
+      <div className="flex shrink-0 items-center gap-1">
+        {status === "uploading" && onCancel ? (
+          <ItemButton onClick={() => onCancel(id)}>Cancel</ItemButton>
+        ) : null}
+        {(status === "failed" || status === "cancelled") && onRetry ? (
+          <ItemButton onClick={() => onRetry(id)}>Retry</ItemButton>
+        ) : null}
+        {onRemove ? (
+          <ItemButton onClick={() => onRemove(id)} aria-label={`Remove ${file.name}`}>
+            Remove
+          </ItemButton>
+        ) : null}
+      </div>
+    </li>
+  );
+}
+
+function ItemButton({ className, ...props }: ComponentPropsWithRef<"button">) {
+  return (
+    <button
+      type="button"
+      className={cn(
+        "rounded-md border border-input bg-background px-2 py-0.5 text-xs font-medium",
+        "transition-colors hover:bg-accent hover:text-accent-foreground",
+        focusRing,
+        disabledStyles,
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * One sentence covering the whole queue, announced politely.
+ *
+ * Per-file live regions would talk over each other the moment two uploads run
+ * at once; one summary of the set is readable where six competing ones are not.
+ */
+export function FileUploadStatus({
+  className,
+  stats,
+  ...props
+}: ComponentPropsWithRef<"p"> & {
+  stats: { total: number; active: number; done: number; failed: number };
+}) {
+  const { total, active, done, failed } = stats;
+
+  // Progress through the set, not a count of what happens to be in flight.
+  // "3 of 5 uploading" is wrong the moment a concurrency limit holds two back,
+  // and it never tells the reader how much of the job is left.
+  const message =
+    total === 0
+      ? ""
+      : active > 0
+        ? `${String(done)} of ${String(total)} uploaded`
+        : failed > 0
+          ? `${String(done)} uploaded, ${String(failed)} failed`
+          : `${String(done)} uploaded`;
+
+  return (
+    <p
+      data-slot="file-upload-status"
+      aria-live="polite"
+      className={cn("text-xs text-muted-foreground", className)}
+      {...props}
+    >
+      {message}
+    </p>
+  );
+}

package/src/components/file-upload/index.ts

@@ -0,0 +1,20 @@
+export {
+  FileUpload,
+  FileUploadItem,
+  FileUploadList,
+  FileUploadStatus,
+  type FileUploadItemProps,
+  type FileUploadListProps,
+  type FileUploadProps,
+} from "./file-upload";
+export {
+  formatBytes,
+  matchesAccept,
+  useUploadQueue,
+  xhrUpload,
+  type QueuedFile,
+  type UploadContext,
+  type UploadFn,
+  type UploadQueueOptions,
+  type UploadStatus,
+} from "./upload-queue";

package/src/components/file-upload/meta.ts

@@ -0,0 +1,21 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "file-upload",
+  title: "File Upload",
+  description: "A dropzone over a real file input, plus the upload queue nobody ships.",
+  category: "form",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: [],
+  files: ["upload-queue.ts", "file-upload.tsx"],
+  a11y:
+    "The APG has no dropzone pattern, and inventing one is the usual failure — a div with " +
+    'role="button", a keydown handler, and a picker keyboard users never reach. The control here ' +
+    "is a real input[type=file] with a real label, which is already operable, already announced, " +
+    "and opens the picker on Enter and Space with nothing added. Drag and drop is a pointer " +
+    "convenience layered on top; every drop can also be done from the input. Each uploading file " +
+    "gets a progressbar named after it, status is always stated in words as well as drawn, and " +
+    "one polite live region summarises the whole queue rather than six per-file regions talking " +
+    "over each other.",
+});

package/src/components/file-upload/upload-queue.ts

@@ -0,0 +1,337 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+/**
+ * The upload queue.
+ *
+ * The dropzone is the most duplicated component in the React ecosystem and the
+ * least valuable half: it is a styled rectangle over `<input type="file">`.
+ * What almost nobody ships is this — progress, cancel, retry with backoff, and
+ * a concurrency limit — so every team writes it again, usually twice, because
+ * the first version has no cancel and no retry.
+ *
+ * Transport is injected. This never calls `fetch` or constructs a request,
+ * because the request is the part that differs everywhere: presigned S3 PUT,
+ * multipart POST, tus, an internal gateway with its own auth. `upload` receives
+ * the file, a progress callback and an AbortSignal, and returns a promise. That
+ * is the whole contract.
+ *
+ * Progress needs XHR, not fetch. `fetch` still cannot report upload progress in
+ * any shipping browser — there is no readable stream for the request body — so
+ * a transport that wants a real progress bar has to use XMLHttpRequest. That is
+ * the consumer's choice to make, and `xhrUpload` below is a working example
+ * rather than a dependency.
+ */
+
+export type UploadStatus = "queued" | "uploading" | "done" | "failed" | "cancelled";
+
+export interface QueuedFile {
+  /** Stable across retries, so React keys and announcements do not jump. */
+  id: string;
+  file: File;
+  status: UploadStatus;
+  /** 0–1, or null when the transport cannot report it. */
+  progress: number | null;
+  /** Why it failed or was refused. Kept so it can be read and acted on. */
+  error?: string;
+  attempts: number;
+}
+
+export interface UploadContext {
+  onProgress: (fraction: number) => void;
+  signal: AbortSignal;
+}
+
+export type UploadFn = (file: File, context: UploadContext) => Promise<void>;
+
+export interface UploadQueueOptions {
+  upload: UploadFn;
+  /** Uploads running at once. More is not faster once the link is saturated. */
+  concurrency?: number;
+  /** Automatic retries per file before it is left failed. */
+  maxAttempts?: number;
+  /** Largest accepted file, in bytes. */
+  maxSize?: number;
+  /** Accepted types, as an `accept` attribute value: ".pdf,image/*". */
+  accept?: string;
+  /** Total files the queue will hold. */
+  maxFiles?: number;
+  onComplete?: (file: QueuedFile) => void;
+}
+
+/** Backoff between attempts. Bounded, because a person is waiting. */
+function backoffMs(attempt: number): number {
+  return Math.min(8000, 500 * 2 ** (attempt - 1));
+}
+
+/** Matches a file against an `accept` string the same way the browser does. */
+export function matchesAccept(file: File, accept: string | undefined): boolean {
+  if (!accept) return true;
+  const patterns = accept
+    .split(",")
+    .map((part) => part.trim().toLowerCase())
+    .filter(Boolean);
+  if (patterns.length === 0) return true;
+
+  const type = file.type.toLowerCase();
+  const name = file.name.toLowerCase();
+
+  return patterns.some((pattern) => {
+    if (pattern.startsWith(".")) return name.endsWith(pattern);
+    if (pattern.endsWith("/*")) return type.startsWith(pattern.slice(0, -1));
+    return type === pattern;
+  });
+}
+
+export function formatBytes(bytes: number): string {
+  if (bytes < 1000) return `${String(bytes)} B`;
+  const units = ["kB", "MB", "GB", "TB"];
+  let value = bytes / 1000;
+  let unit = 0;
+  while (value >= 1000 && unit < units.length - 1) {
+    value /= 1000;
+    unit += 1;
+  }
+  return `${value.toFixed(value < 10 ? 1 : 0)} ${units[unit] ?? "B"}`;
+}
+
+let sequence = 0;
+
+export function useUploadQueue(options: UploadQueueOptions) {
+  const {
+    upload,
+    concurrency = 3,
+    maxAttempts = 3,
+    maxSize,
+    accept,
+    maxFiles,
+    onComplete,
+  } = options;
+
+  const [files, setFiles] = useState<QueuedFile[]>([]);
+
+  const controllers = useRef(new Map<string, AbortController>());
+  const running = useRef(new Set<string>());
+
+  // The live option values, so an in-flight upload reads the current transport
+  // without `run` being re-created — which would churn the scheduling effect
+  // every time a consumer passes an inline `upload`. Written after commit
+  // rather than during render, because a ref write during render is unsafe
+  // under concurrent rendering; `run` only reads this once it is executing,
+  // which is always after the effect has run.
+  const latest = useRef({ upload, concurrency, maxAttempts, onComplete });
+  useEffect(() => {
+    latest.current = { upload, concurrency, maxAttempts, onComplete };
+  });
+
+  const patch = useCallback((id: string, changes: Partial<QueuedFile>) => {
+    setFiles((current) =>
+      current.map((entry) => (entry.id === id ? { ...entry, ...changes } : entry)),
+    );
+  }, []);
+
+  const run = useCallback(
+    async (entry: QueuedFile) => {
+      const controller = new AbortController();
+      controllers.current.set(entry.id, controller);
+
+      const attempt = entry.attempts + 1;
+      patch(entry.id, {
+        status: "uploading",
+        progress: 0,
+        attempts: attempt,
+        error: undefined,
+      });
+
+      try {
+        await latest.current.upload(entry.file, {
+          signal: controller.signal,
+          onProgress: (fraction) => {
+            patch(entry.id, { progress: Math.min(1, Math.max(0, fraction)) });
+          },
+        });
+
+        patch(entry.id, { status: "done", progress: 1 });
+        latest.current.onComplete?.({ ...entry, status: "done", progress: 1 });
+      } catch (error) {
+        if (controller.signal.aborted) {
+          patch(entry.id, { status: "cancelled", progress: null });
+        } else if (attempt < latest.current.maxAttempts) {
+          // Back off, then requeue. Releasing the slot only after the delay is
+          // what makes the wait real rather than a busy retry, and the file
+          // re-enters the queue like any other so retries obey concurrency too.
+          setTimeout(() => {
+            running.current.delete(entry.id);
+            controllers.current.delete(entry.id);
+            patch(entry.id, { status: "queued", progress: null });
+          }, backoffMs(attempt));
+          return;
+        } else {
+          patch(entry.id, {
+            status: "failed",
+            progress: null,
+            error: error instanceof Error ? error.message : "Upload failed",
+          });
+        }
+      }
+
+      controllers.current.delete(entry.id);
+      running.current.delete(entry.id);
+      // No explicit pump: the scheduling effect below reacts to the state
+      // change and starts whatever can start next.
+      setFiles((current) => [...current]);
+    },
+    [patch],
+  );
+
+  // Starts whatever can start, once the state that made it startable has been
+  // committed. Doing this inside a setState updater — the obvious shortcut —
+  // means React may run it twice and upload the same file twice; the `running`
+  // set guards that, but the effect is the honest place for it.
+  useEffect(() => {
+    const free = concurrency - running.current.size;
+    if (free <= 0) return;
+
+    const next = files
+      .filter((entry) => entry.status === "queued" && !running.current.has(entry.id))
+      .slice(0, free);
+
+    for (const entry of next) {
+      running.current.add(entry.id);
+      void run(entry);
+    }
+  }, [files, concurrency, run]);
+
+  /** Validates and enqueues. A rejected file is kept and told why. */
+  const add = useCallback(
+    (incoming: File[]) => {
+      setFiles((current) => {
+        const room = maxFiles === undefined ? incoming.length : maxFiles - current.length;
+        const admitted: QueuedFile[] = [];
+
+        for (const file of incoming.slice(0, Math.max(0, room))) {
+          sequence += 1;
+          const id = `upload-${String(sequence)}`;
+
+          // A rejected file becomes a failed entry rather than disappearing.
+          // Silently dropping a file the reader chose is how these components
+          // lose work without anybody noticing.
+          if (maxSize !== undefined && file.size > maxSize) {
+            admitted.push({
+              id,
+              file,
+              status: "failed",
+              progress: null,
+              attempts: 0,
+              error: `Larger than ${formatBytes(maxSize)}`,
+            });
+            continue;
+          }
+          if (!matchesAccept(file, accept)) {
+            admitted.push({
+              id,
+              file,
+              status: "failed",
+              progress: null,
+              attempts: 0,
+              error: "Type not accepted",
+            });
+            continue;
+          }
+
+          admitted.push({ id, file, status: "queued", progress: null, attempts: 0 });
+        }
+
+        return [...current, ...admitted];
+      });
+    },
+    [accept, maxFiles, maxSize],
+  );
+
+  const cancel = useCallback((id: string) => {
+    controllers.current.get(id)?.abort();
+  }, []);
+
+  const retry = useCallback((id: string) => {
+    setFiles((current) =>
+      current.map((entry) =>
+        entry.id === id
+          ? { ...entry, status: "queued" as const, error: undefined, attempts: 0 }
+          : entry,
+      ),
+    );
+  }, []);
+
+  const remove = useCallback((id: string) => {
+    controllers.current.get(id)?.abort();
+    controllers.current.delete(id);
+    running.current.delete(id);
+    setFiles((current) => current.filter((entry) => entry.id !== id));
+  }, []);
+
+  const clearCompleted = useCallback(() => {
+    setFiles((current) => current.filter((entry) => entry.status !== "done"));
+  }, []);
+
+  const stats = useMemo(() => {
+    const by = (status: UploadStatus) =>
+      files.filter((entry) => entry.status === status).length;
+    return {
+      total: files.length,
+      queued: by("queued"),
+      uploading: by("uploading"),
+      done: by("done"),
+      failed: by("failed"),
+      cancelled: by("cancelled"),
+      active: by("queued") + by("uploading"),
+    };
+  }, [files]);
+
+  return { files, stats, add, cancel, retry, remove, clearCompleted };
+}
+
+/**
+ * A working XHR transport, as an example rather than a dependency.
+ *
+ * XMLHttpRequest and not fetch, because fetch still cannot report upload
+ * progress: there is no readable stream for a request body in any shipping
+ * browser. Copy this and change the request to match your backend.
+ */
+export function xhrUpload(
+  url: string,
+  init: { method?: string; headers?: Record<string, string> } = {},
+): UploadFn {
+  return (file, { onProgress, signal }) =>
+    new Promise<void>((resolve, reject) => {
+      const request = new XMLHttpRequest();
+      request.open(init.method ?? "POST", url);
+
+      for (const [header, value] of Object.entries(init.headers ?? {})) {
+        request.setRequestHeader(header, value);
+      }
+
+      request.upload.addEventListener("progress", (event) => {
+        if (event.lengthComputable) onProgress(event.loaded / event.total);
+      });
+
+      request.addEventListener("load", () => {
+        if (request.status >= 200 && request.status < 300) resolve();
+        else reject(new Error(`Upload failed with status ${String(request.status)}`));
+      });
+      request.addEventListener("error", () => {
+        reject(new Error("Network error"));
+      });
+      request.addEventListener("abort", () => {
+        reject(new Error("Cancelled"));
+      });
+
+      signal.addEventListener("abort", () => {
+        request.abort();
+      });
+
+      const body = new FormData();
+      body.append("file", file);
+      request.send(body);
+    });
+}