@dowel-ui/react 0.2.0 → 0.4.0

package/src/components/diff-viewer/diff-viewer.tsx

@@ -0,0 +1,339 @@
+"use client";
+
+import { useMemo, type ComponentPropsWithRef, type ReactNode } from "react";
+
+import { disabledStyles, focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+import { countChanges, toSplitRows, type DiffHunk, type DiffRow } from "./diff-model";
+
+/**
+ * A diff, and a decision about it.
+ *
+ * The rendering half exists because every packaged viewer brings its own
+ * styling system — emotion, or HTML strings plus a stylesheet — which design
+ * tokens cannot reach and which is awkward under RSC. The deciding half exists
+ * because Dowel is for AI products, and an agent proposing a change to a file is
+ * the case that needs it: what every coding agent ships, and no component
+ * library does.
+ *
+ * Decisions are controlled. The component never mutates the diff or applies
+ * anything; it reports which hunks were accepted and rejected and leaves the
+ * consequences to the application, the same way ai-action-ledger does.
+ *
+ * Not a grid. A code listing is a table of text, and role="grid" would promise
+ * cell-by-cell arrow navigation that neither exists here nor makes sense for
+ * reading code. Line kind is carried in text, because a plus sign and a green
+ * background are not information.
+ */
+
+export type HunkDecision = "accepted" | "rejected";
+
+const KIND_LABEL: Record<DiffRow["kind"], string> = {
+  added: "Added",
+  removed: "Removed",
+  context: "Unchanged",
+};
+
+export interface DiffViewerProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+  hunks: DiffHunk[];
+  /** Names the diff — usually the path of the file being changed. */
+  label: string;
+  view?: "unified" | "split";
+  /** Per-hunk decisions, keyed by hunk id. Controlled. */
+  decisions?: Record<string, HunkDecision>;
+  onDecision?: (hunkId: string, decision: HunkDecision) => void;
+  children?: ReactNode;
+}
+
+export function DiffViewer({
+  className,
+  hunks,
+  label,
+  view = "unified",
+  decisions,
+  onDecision,
+  children,
+  ...props
+}: DiffViewerProps) {
+  const counts = useMemo(() => countChanges(hunks), [hunks]);
+
+  return (
+    <div
+      data-slot="diff-viewer"
+      data-view={view}
+      className={cn("flex flex-col gap-2", className)}
+      {...props}
+    >
+      <div className="flex flex-wrap items-baseline justify-between gap-2">
+        <span className="font-mono text-sm font-medium">{label}</span>
+        {/* Said in words as well as coloured, and before the diff rather than
+            after it: a reader deserves to know the size of the change before
+            they start reading it. */}
+        <span data-slot="diff-viewer-summary" className="text-xs text-muted-foreground">
+          <span className="text-success">+{counts.added}</span>{" "}
+          <span className="text-destructive">−{counts.removed}</span>
+          <span className="sr-only">
+            {` — ${String(counts.added)} lines added, ${String(counts.removed)} removed`}
+          </span>
+        </span>
+      </div>
+
+      {children}
+
+      {hunks.length === 0 ? (
+        <p className="rounded-lg border border-border bg-muted/30 p-3 text-sm text-muted-foreground">
+          No changes.
+        </p>
+      ) : (
+        <div className="overflow-hidden rounded-lg border border-border">
+          {hunks.map((hunk) => (
+            <DiffHunkView
+              key={hunk.id}
+              hunk={hunk}
+              label={label}
+              view={view}
+              decision={decisions?.[hunk.id]}
+              onDecision={onDecision}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function DiffHunkView({
+  hunk,
+  label,
+  view,
+  decision,
+  onDecision,
+}: {
+  hunk: DiffHunk;
+  label: string;
+  view: "unified" | "split";
+  decision?: HunkDecision;
+  onDecision?: (hunkId: string, decision: HunkDecision) => void;
+}) {
+  const splitRows = useMemo(
+    () => (view === "split" ? toSplitRows(hunk.rows) : []),
+    [view, hunk.rows],
+  );
+
+  return (
+    <section
+      data-slot="diff-hunk"
+      data-decision={decision}
+      aria-label={`${label}, hunk ${hunk.id}`}
+      className={cn(
+        "border-b border-border last:border-b-0",
+        decision === "rejected" && "opacity-55",
+      )}
+    >
+      {hunk.skippedBefore > 0 ? (
+        <p
+          data-slot="diff-hunk-skipped"
+          className="border-b border-border bg-muted/40 px-3 py-1 font-mono text-2xs text-muted-foreground"
+        >
+          {hunk.skippedBefore} unchanged {hunk.skippedBefore === 1 ? "line" : "lines"} hidden
+        </p>
+      ) : null}
+
+      {onDecision ? (
+        <div className="flex flex-wrap items-center gap-2 border-b border-border bg-muted/20 px-3 py-1.5">
+          <span className="flex-1 text-xs text-muted-foreground">
+            {decision === "accepted"
+              ? "Accepted"
+              : decision === "rejected"
+                ? "Rejected"
+                : "Not decided"}
+          </span>
+          <HunkButton
+            pressed={decision === "accepted"}
+            onClick={() => {
+              onDecision(hunk.id, "accepted");
+            }}
+          >
+            Accept
+          </HunkButton>
+          <HunkButton
+            pressed={decision === "rejected"}
+            onClick={() => {
+              onDecision(hunk.id, "rejected");
+            }}
+          >
+            Reject
+          </HunkButton>
+        </div>
+      ) : null}
+
+      <div className="overflow-x-auto">
+        <table data-slot="diff-table" className="w-full border-collapse font-mono text-xs">
+          <tbody>
+            {view === "split"
+              ? splitRows.map((pair, index) => (
+                  <tr key={index} data-slot="diff-row">
+                    <SplitCell row={pair.left} side="before" />
+                    <SplitCell row={pair.right} side="after" />
+                  </tr>
+                ))
+              : hunk.rows.map((row, index) => <UnifiedRow key={index} row={row} />)}
+          </tbody>
+        </table>
+      </div>
+    </section>
+  );
+}
+
+const ROW_STYLES: Record<DiffRow["kind"], string> = {
+  added: "bg-success/10",
+  removed: "bg-destructive/10",
+  context: "",
+};
+
+function UnifiedRow({ row }: { row: DiffRow }) {
+  return (
+    <tr data-slot="diff-row" data-kind={row.kind} className={ROW_STYLES[row.kind]}>
+      <LineNumber value={row.before} />
+      <LineNumber value={row.after} />
+      <td className="w-4 pr-1 text-center text-muted-foreground select-none" aria-hidden="true">
+        {row.kind === "added" ? "+" : row.kind === "removed" ? "−" : ""}
+      </td>
+      <td className="w-full py-0.5 pr-3 break-all whitespace-pre-wrap">
+        {/* The kind, for anyone who cannot see the sign or the tint. Reading a
+            diff aloud without it is reading the same file twice. */}
+        <span className="sr-only">{KIND_LABEL[row.kind]}: </span>
+        <RowContent row={row} />
+      </td>
+    </tr>
+  );
+}
+
+function SplitCell({ row, side }: { row: DiffRow | null; side: "before" | "after" }) {
+  if (!row) {
+    // An empty half of a pair, not a blank line of code. Hidden from assistive
+    // technology so a reader is not read padding.
+    return (
+      <>
+        <td aria-hidden="true" className="w-10 bg-muted/40" />
+        <td aria-hidden="true" className="w-1/2 bg-muted/20" />
+      </>
+    );
+  }
+
+  return (
+    <>
+      <LineNumber value={side === "before" ? row.before : row.after} />
+      <td
+        className={cn("w-1/2 py-0.5 pr-3 break-all whitespace-pre-wrap", ROW_STYLES[row.kind])}
+      >
+        <span className="sr-only">{KIND_LABEL[row.kind]}: </span>
+        <RowContent row={row} />
+      </td>
+    </>
+  );
+}
+
+function RowContent({ row }: { row: DiffRow }) {
+  if (!row.segments) return <>{row.content}</>;
+
+  return (
+    <>
+      {row.segments.map((segment, index) =>
+        segment.changed ? (
+          // A mark element, so the changed words survive as structure rather
+          // than existing only as a slightly stronger background.
+          <mark
+            key={index}
+            className={cn(
+              "rounded-[2px] text-inherit",
+              row.kind === "added" ? "bg-success/30" : "bg-destructive/30",
+            )}
+          >
+            {segment.text}
+          </mark>
+        ) : (
+          <span key={index}>{segment.text}</span>
+        ),
+      )}
+    </>
+  );
+}
+
+function LineNumber({ value }: { value?: number }) {
+  return (
+    <td
+      // Decorative: the line number is orientation for a sighted reader, and
+      // announcing two numbers before every line makes the diff unlistenable.
+      aria-hidden="true"
+      className="w-10 border-r border-border bg-muted/40 px-2 py-0.5 text-right text-muted-foreground tabular-nums select-none"
+    >
+      {value ?? ""}
+    </td>
+  );
+}
+
+function HunkButton({
+  className,
+  pressed,
+  ...props
+}: ComponentPropsWithRef<"button"> & { pressed: boolean }) {
+  return (
+    <button
+      type="button"
+      aria-pressed={pressed}
+      className={cn(
+        "rounded-md border px-2 py-0.5 text-xs font-medium transition-colors",
+        pressed
+          ? "border-primary bg-primary text-primary-foreground"
+          : "border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        focusRing,
+        disabledStyles,
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/** Switches between unified and side-by-side. */
+export function DiffViewerToolbar({
+  className,
+  view,
+  onViewChange,
+  ...props
+}: Omit<ComponentPropsWithRef<"div">, "onChange"> & {
+  view: "unified" | "split";
+  onViewChange: (view: "unified" | "split") => void;
+}) {
+  return (
+    <div
+      data-slot="diff-viewer-toolbar"
+      role="group"
+      aria-label="Diff layout"
+      className={cn("flex items-center gap-1", className)}
+      {...props}
+    >
+      {(["unified", "split"] as const).map((option) => (
+        <button
+          key={option}
+          type="button"
+          aria-pressed={view === option}
+          onClick={() => {
+            onViewChange(option);
+          }}
+          className={cn(
+            "rounded-md border px-2 py-0.5 text-xs font-medium capitalize transition-colors",
+            view === option
+              ? "border-transparent bg-secondary text-secondary-foreground"
+              : "border-input bg-background text-muted-foreground hover:text-foreground",
+            focusRing,
+          )}
+        >
+          {option}
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/components/diff-viewer/index.ts

@@ -0,0 +1,17 @@
+export {
+  DiffViewer,
+  DiffViewerToolbar,
+  type DiffViewerProps,
+  type HunkDecision,
+} from "./diff-viewer";
+export {
+  buildDiff,
+  countChanges,
+  groupIntoHunks,
+  toSplitRows,
+  type BuildDiffOptions,
+  type DiffHunk,
+  type DiffRow,
+  type RowKind,
+  type WordSegment,
+} from "./diff-model";

package/src/components/diff-viewer/meta.ts

@@ -0,0 +1,20 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "diff-viewer",
+  title: "Diff Viewer",
+  description: "A diff you can style, and accept or reject hunk by hunk.",
+  category: "data",
+  status: "stable",
+  dependencies: ["diff"],
+  registryDependencies: [],
+  files: ["diff-model.ts", "diff-viewer.tsx"],
+  a11y:
+    'A semantic table, not a grid. role="grid" would promise cell-by-cell arrow navigation that ' +
+    "does not exist here and makes no sense for reading code. Every row states added, removed or " +
+    "unchanged in text, because a plus sign and a green tint are not information — a diff read " +
+    "aloud without it is just the same file twice. Line numbers are aria-hidden: they orient a " +
+    "sighted reader, and announcing two numbers before every line makes the diff unlistenable. " +
+    "Changed words are marked with mark elements so they survive as structure, and the empty half " +
+    "of a split pair is hidden rather than read as a blank line of code.",
+});

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>
+  );
+}