@tangle-network/ui 11.25.0 → 11.26.0

package/dist/index.js

@@ -82,7 +82,11 @@ import { LiveDuration } from "./run/run-item-primitives.js";
 import { ToolCallFeed, parseToolEvent } from "./run/tool-call-feed.js";
 import { FileTree, filterFileTree } from "./files/file-tree.js";
 import { RichFileTree } from "./files/rich-file-tree.js";
+import { FileCard } from "./files/file-card.js";
+import { configurePdfViewer } from "./files/pdf-loader.js";
+import { PdfViewer } from "./files/pdf-viewer.js";
 import { CSV_PREVIEW_ROW_LIMIT, FilePreview, parseCsv } from "./files/file-preview.js";
+import { FileList } from "./files/file-list.js";
 import { FileTabs } from "./files/file-tabs.js";
 import { FileArtifactPane } from "./files/file-artifact-pane.js";
 import { AuthHeader, GitHubLoginButton, UserMenu } from "./auth/auth.js";
@@ -99,4 +103,4 @@ import { addMessage, addParts, clearChat, isStreamingAtom, messagesAtom, partMap
 import { copyText } from "./utils/copy-text.js";
 import { timeAgo } from "./utils/time-ago.js";
 import { RedactedDocument } from "./redaction/redacted-document.js";
-export { AgentTimeline, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, ArtifactPane, AuthHeader, Avatar, AvatarFallback, AvatarImage, Badge, Button, CATEGORY_TONES, CSV_PREVIEW_ROW_LIMIT, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, ChatContainer, ChatMessage, Checkbox, Chip, CodeBlock, Collapsible, CollapsibleContent, CollapsibleTrigger, CommandPreview, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, CopyButton, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DiffPreview, DropZone, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, ExpandedToolDetail, FileArtifactPane, FilePreview, FileTabs, FileTree, FilterField, GitHubLoginButton, GlobResultsPreview, GrepResultsPreview, Heading, IconTile, InlineCode, InlineThinkingItem, InlineToolItem, Input, Label, LiveDuration, LoginLayout, Logo, Markdown, MessageAuthor, MessageList, Metric, MetricStrip, OPENUI_NODE_JSON_SCHEMA, OPENUI_NODE_TYPES, OpenUIArtifactRenderer, PageHeader, PageShell, Pagination, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, Progress, QuestionPreview, RealtimeSessionRegistry, RedactedDocument, RichFileTree, RunGroup, RunRowShell, RunRowStatusDot, SegmentedControl, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SidebarDropZone, Skeleton, SkeletonCard, SkeletonTable, Slider, StatCard, StatusPill, Switch, TONE_CLASSES, TOOL_CATEGORY_ICONS, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Tag, TangleKnot, TerminalCursor, TerminalDisplay, TerminalInput, TerminalLine, TextShimmer, Textarea, ThemeToggle, ThinkingIndicator, ToastContainer, ToastProvider, ToolCallFeed, Toolbar, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, UploadProgress, UserMenu, UserMessage, WebSearchPreview, WriteFilePreview, activeSessionsAtom, addMessage, addParts, badgeVariants, bumpActiveSessionActivity, buttonVariants, clearChat, cn, copyText, createAuthFetcher, detectFileFormat, fileExtension, filterFileTree, findUnsupportedOpenUINode, focusField, focusFieldInvalid, focusFieldWithin, focusRing, focusRingInset, formatBytes, formatDuration, formatUptime, getActiveSession, getAllActiveSessions, getAllProjectActivity, getCodeLanguage, getFormatLabel, getSanitizedMarkdownHeadingIdFromRawFragment, getSessionsByActivity, getSessionsForNavbar, getSessionsForProject, getSyntaxLanguage, getToolCategory, getToolDisplayMetadata, getToolErrorText, getTotalRunningSessionCount, hasBackgroundRunningSessions, initialsOf, isStreamingAtom, isViewerMessage, messagesAtom, parseCsv, parseToolEvent, partMapAtom, registerActiveSession, resetActiveSessions, resolveFilePreviewKind, setActiveSessionAttention, setActiveSessionConnection, setActiveSessionError, setActiveSessionRunning, setForegroundActiveSession, timeAgo, toneFor, truncateText, unregisterActiveSession, updateActiveSessionMeta, updatePart, useActiveSession, useActiveSessions, useActiveSessionsState, useApiKey, useAuth, useAutoScroll, useDropdownMenu, useHasBackgroundRunningSessions, useLiveTime, useNavbarSessions, useProjectActivity, useProjectSessions, useRealtimeSession, useRunCollapseState, useRunGroups, useSSEStream, useSdkSession, useSessionsByActivity, useTheme, useToast, useToolCallStream, useTotalRunningSessions, validateOpenUIJsonArtifact, validateOpenUIJsonNode };
+export { AgentTimeline, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, ArtifactPane, AuthHeader, Avatar, AvatarFallback, AvatarImage, Badge, Button, CATEGORY_TONES, CSV_PREVIEW_ROW_LIMIT, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, ChatContainer, ChatMessage, Checkbox, Chip, CodeBlock, Collapsible, CollapsibleContent, CollapsibleTrigger, CommandPreview, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, CopyButton, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DiffPreview, DropZone, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, ExpandedToolDetail, FileArtifactPane, FileCard, FileList, FilePreview, FileTabs, FileTree, FilterField, GitHubLoginButton, GlobResultsPreview, GrepResultsPreview, Heading, IconTile, InlineCode, InlineThinkingItem, InlineToolItem, Input, Label, LiveDuration, LoginLayout, Logo, Markdown, MessageAuthor, MessageList, Metric, MetricStrip, OPENUI_NODE_JSON_SCHEMA, OPENUI_NODE_TYPES, OpenUIArtifactRenderer, PageHeader, PageShell, Pagination, PdfViewer, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, Progress, QuestionPreview, RealtimeSessionRegistry, RedactedDocument, RichFileTree, RunGroup, RunRowShell, RunRowStatusDot, SegmentedControl, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SidebarDropZone, Skeleton, SkeletonCard, SkeletonTable, Slider, StatCard, StatusPill, Switch, TONE_CLASSES, TOOL_CATEGORY_ICONS, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Tag, TangleKnot, TerminalCursor, TerminalDisplay, TerminalInput, TerminalLine, TextShimmer, Textarea, ThemeToggle, ThinkingIndicator, ToastContainer, ToastProvider, ToolCallFeed, Toolbar, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, UploadProgress, UserMenu, UserMessage, WebSearchPreview, WriteFilePreview, activeSessionsAtom, addMessage, addParts, badgeVariants, bumpActiveSessionActivity, buttonVariants, clearChat, cn, configurePdfViewer, copyText, createAuthFetcher, detectFileFormat, fileExtension, filterFileTree, findUnsupportedOpenUINode, focusField, focusFieldInvalid, focusFieldWithin, focusRing, focusRingInset, formatBytes, formatDuration, formatUptime, getActiveSession, getAllActiveSessions, getAllProjectActivity, getCodeLanguage, getFormatLabel, getSanitizedMarkdownHeadingIdFromRawFragment, getSessionsByActivity, getSessionsForNavbar, getSessionsForProject, getSyntaxLanguage, getToolCategory, getToolDisplayMetadata, getToolErrorText, getTotalRunningSessionCount, hasBackgroundRunningSessions, initialsOf, isStreamingAtom, isViewerMessage, messagesAtom, parseCsv, parseToolEvent, partMapAtom, registerActiveSession, resetActiveSessions, resolveFilePreviewKind, setActiveSessionAttention, setActiveSessionConnection, setActiveSessionError, setActiveSessionRunning, setForegroundActiveSession, timeAgo, toneFor, truncateText, unregisterActiveSession, updateActiveSessionMeta, updatePart, useActiveSession, useActiveSessions, useActiveSessionsState, useApiKey, useAuth, useAutoScroll, useDropdownMenu, useHasBackgroundRunningSessions, useLiveTime, useNavbarSessions, useProjectActivity, useProjectSessions, useRealtimeSession, useRunCollapseState, useRunGroups, useSSEStream, useSdkSession, useSessionsByActivity, useTheme, useToast, useToolCallStream, useTotalRunningSessions, validateOpenUIJsonArtifact, validateOpenUIJsonNode };

package/dist/lib/optional-peer.js

@@ -0,0 +1,29 @@
+//#region src/lib/optional-peer.ts
+/**
+* Shared handling for optional peers that an entry reaches through a dynamic
+* `import()`: `./editor` for tiptap, yjs and Hocuspocus, `./files` for
+* pdfjs-dist. `scripts/validate-dist.mjs` holds the rules these helpers serve.
+*/
+/** The messages a bundler or a runtime gives for a module it cannot resolve. */
+const RESOLUTION_FAILURE = /could not resolve|cannot find (?:module|package)|can't resolve|failed to resolve|module not found/i;
+/**
+* True when the rejection says the package is not installed. Only such an
+* error gets the install list: a transient chunk-fetch failure that reads as
+* "install the peers" sends the reader to the wrong fix. An error this
+* predicate does not match keeps its own message, so it can only
+* under-report.
+*/
+function isMissingPeerError(error) {
+	return error instanceof Error && RESOLUTION_FAILURE.test(error.message);
+}
+/**
+* Hands an `import()` rejection on unchanged. esbuild reports an unresolvable
+* literal `import()` as a build error and defers it to run time only when the
+* call carries a `.catch()`, so every peer import attaches this handler. It
+* changes nothing at run time.
+*/
+function rethrow(error) {
+	throw error;
+}
+//#endregion
+export { isMissingPeerError, rethrow };

package/dist/primitives.d.ts

@@ -1,5 +1,7 @@
 import { Button, ButtonProps, buttonVariants } from "./primitives/button.js";
 import { ArtifactPane, ArtifactPaneProps } from "./primitives/artifact-pane.js";
+import { CATEGORY_TONES, CategoryTone, TONE_CLASSES, Tone, ToneClasses, toneFor } from "./primitives/tone.js";
+import { IconTile, IconTileProps, initialsOf } from "./primitives/icon-tile.js";
 import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, CardTitleProps } from "./primitives/card.js";
 import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger } from "./primitives/dialog.js";
 import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger } from "./primitives/alert-dialog.js";
@@ -40,10 +42,8 @@ import { PageHeader, PageHeaderProps } from "./primitives/page-header.js";
 import { StatusPill, StatusPillProps, StatusTone } from "./primitives/status-pill.js";
 import { Alert, AlertDescription, AlertProps, AlertTitle, AlertTone } from "./primitives/alert.js";
 import { Pagination, PaginationProps } from "./primitives/pagination.js";
-import { CATEGORY_TONES, CategoryTone, TONE_CLASSES, Tone, ToneClasses, toneFor } from "./primitives/tone.js";
 import { Tag, TagProps } from "./primitives/tag.js";
 import { Chip, ChipProps } from "./primitives/chip.js";
-import { IconTile, IconTileProps, initialsOf } from "./primitives/icon-tile.js";
 import { Metric, MetricProps, MetricStrip, MetricStripProps } from "./primitives/metric-strip.js";
 import { FilterField, FilterFieldProps, Toolbar, ToolbarProps } from "./primitives/toolbar.js";
 import { Logo, LogoProps, TangleKnot } from "@tangle-network/brand";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/ui",
-  "version": "11.25.0",
+  "version": "11.26.0",
   "description": "Generic React UI components for Tangle products — primitives, chat, run, files, editor, markdown.",
   "type": "module",
   "license": "MIT",
@@ -156,6 +156,7 @@
     "@tiptap/react": ">=3.20.4 <4.0.0",
     "@tiptap/starter-kit": ">=3.20.4 <4.0.0",
     "nanostores": ">=0.11.3 <2.0.0",
+    "pdfjs-dist": ">=6.0.0 <7.0.0",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19",
     "react-router": "^7 || ^8",
@@ -191,6 +192,9 @@
     },
     "react-router": {
       "optional": true
+    },
+    "pdfjs-dist": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -208,6 +212,7 @@
     "@types/turndown": "^5.0.6",
     "ajv": "8.17.1",
     "nanostores": "^1.5.4",
+    "pdfjs-dist": "^6.4.299",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
     "react-router": "^8.4.0",

package/src/editor/editor-peers.ts

@@ -32,6 +32,9 @@ import type * as TiptapCollaborationCaret from "@tiptap/extension-collaboration-
 import type * as TiptapReact from "@tiptap/react";
 import type * as TiptapStarterKit from "@tiptap/starter-kit";
 import type * as Yjs from "yjs";
+import { isMissingPeerError, rethrow } from "../lib/optional-peer";
+
+export { isMissingPeerError };
 
 /** Namespaces the local markdown editor needs. */
 export interface DocumentEditorPeers {
@@ -89,31 +92,6 @@ export function isMissingEditorPeersError(error: unknown): boolean {
   return error instanceof Error && error.name === "MissingEditorPeersError";
 }
 
-/** The messages a bundler or a runtime gives for a module it cannot resolve. */
-const RESOLUTION_FAILURE =
-  /could not resolve|cannot find (?:module|package)|can't resolve|failed to resolve|module not found/i;
-
-/**
- * True when the rejection says the package is not installed. Only such an
- * error gets the install list: a transient chunk-fetch failure that reads as
- * "install the peers" sends the reader to the wrong fix. An error this
- * predicate does not match keeps its own message, so it can only
- * under-report.
- */
-export function isMissingPeerError(error: unknown): boolean {
-  return error instanceof Error && RESOLUTION_FAILURE.test(error.message);
-}
-
-/**
- * Hands an `import()` rejection on unchanged. esbuild reports an unresolvable
- * literal `import()` as a build error and defers it to run time only when the
- * call carries a `.catch()`, so every peer import attaches this handler. It
- * changes nothing at run time.
- */
-function rethrow(error: unknown): never {
-  throw error;
-}
-
 /**
  * Every optional peer the `./editor` entry needs at run time. The loaders
  * import all but `@tiptap/core`, which the tiptap packages need in turn: a

package/src/files/file-artifact-pane.test.tsx

@@ -2,6 +2,12 @@ import { describe, expect, it, vi } from "vitest";
 import { fireEvent, render, screen } from "@testing-library/react";
 import { FileArtifactPane } from "./file-artifact-pane";
 import { CSV_PREVIEW_ROW_LIMIT, parseCsv } from "./file-preview";
+import { MissingPdfjsError, loadPdfjs } from "./pdf-loader";
+
+vi.mock("./pdf-loader", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./pdf-loader")>()),
+  loadPdfjs: vi.fn(),
+}));
 
 const BLOB_URL = "blob:https://app.tangle.tools/1f2e3d4c";
 
@@ -32,16 +38,20 @@ describe("FileArtifactPane previews", () => {
     expect(container.querySelector("img")).toHaveClass("max-w-none");
   });
 
-  it("renders a PDF as an <object> of the blobUrl", () => {
+  it("renders a PDF in PdfViewer, and in an <object> of the blobUrl without pdfjs-dist", async () => {
+    vi.mocked(loadPdfjs).mockRejectedValue(new MissingPdfjsError());
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
     const { container } = render(
       <FileArtifactPane filename="report.pdf" blobUrl={BLOB_URL} mimeType="application/pdf" />,
     );
 
+    expect(screen.getByRole("status")).toHaveTextContent("Loading report.pdf");
+    expect(await screen.findByText(/does not include the page viewer/)).toBeInTheDocument();
     const viewer = container.querySelector("object");
-    expect(viewer).not.toBeNull();
     expect(viewer).toHaveAttribute("data", BLOB_URL);
     expect(viewer).toHaveAttribute("type", "application/pdf");
     expect(viewer).toHaveAttribute("title", "report.pdf");
+    consoleError.mockRestore();
   });
 
   it("renders video and audio with native controls", () => {

package/src/files/file-card.test.tsx

@@ -0,0 +1,62 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { FileCard } from "./file-card";
+
+const UPLOADED = new Date("2026-10-06T15:30:00Z");
+
+describe("FileCard", () => {
+  it("names the file with its size, date and uploader", () => {
+    const { container } = render(
+      <FileCard
+        filename="Engagement letter.pdf"
+        size={2_516_582}
+        date={UPLOADED}
+        uploader={{ name: "Dana Ruiz", role: "Client" }}
+      />,
+    );
+
+    expect(screen.getByText("Engagement letter.pdf")).toBeInTheDocument();
+    expect(screen.getByText("2.4 MB")).toBeInTheDocument();
+    expect(container.querySelector("time")).toHaveAttribute("datetime", UPLOADED.toISOString());
+    expect(screen.getByText("Uploaded by Dana Ruiz (Client)")).toBeInTheDocument();
+  });
+
+  it("leaves out what it does not know", () => {
+    const { container } = render(<FileCard filename="notes.txt" date="not a date" />);
+    expect(container.querySelector("time")).toBeNull();
+    expect(screen.queryByText(/Uploaded by/)).toBeNull();
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+
+  it("takes its icon tone from the file kind, with the MIME type outranking the name", () => {
+    const pdf = render(<FileCard filename="brief.pdf" />);
+    expect(pdf.container.querySelector("[aria-hidden='true']")?.className).toContain(
+      "--tone-orange-bg",
+    );
+    pdf.unmount();
+
+    const sheet = render(<FileCard filename="export" mimeType="text/csv" />);
+    expect(sheet.container.querySelector("[aria-hidden='true']")?.className).toContain(
+      "--tone-lime-bg",
+    );
+  });
+
+  it("offers Download and the host's own actions", () => {
+    const onDownload = vi.fn();
+    render(
+      <FileCard
+        filename="book.xlsx"
+        description="Download to open this workbook in a spreadsheet app."
+        onDownload={onDownload}
+        actions={<button type="button">Open</button>}
+      />,
+    );
+
+    expect(
+      screen.getByText("Download to open this workbook in a spreadsheet app."),
+    ).toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: "Download" }));
+    expect(onDownload).toHaveBeenCalledTimes(1);
+    expect(screen.getByRole("button", { name: "Open" })).toBeInTheDocument();
+  });
+});

package/src/files/file-card.tsx

@@ -0,0 +1,210 @@
+/**
+ * FileCard — one file, described: its kind, name, size, date and uploader,
+ * with Download and any actions the host adds. FilePreview shows it for a file
+ * it cannot render inline; a host can show it anywhere a file stands on its own.
+ */
+
+import * as React from "react";
+import {
+  Download,
+  File,
+  FileAudio,
+  FileCode,
+  FileImage,
+  FileJson,
+  FileSpreadsheet,
+  FileText,
+  FileVideo,
+  type LucideIcon,
+} from "lucide-react";
+import { cn } from "../lib/utils";
+import { Button } from "../primitives/button";
+import { IconTile, type IconTileProps } from "../primitives/icon-tile";
+import type { CategoryTone } from "../primitives/tone";
+import { formatBytes } from "../utils/format";
+import { getFormatLabel, resolveFilePreviewKind, type FilePreviewKind } from "./file-format";
+
+/** Who added a file, as a reader of the list should see them. */
+export interface FileUploader {
+  name: string;
+  /** Their relationship to the work, e.g. "Client" or "Attorney". */
+  role?: string;
+}
+
+/** What FileCard and FileList show about one file. */
+export interface FileDetails {
+  filename: string;
+  /** Wins over the extension when choosing the kind, as in FilePreview. */
+  mimeType?: string;
+  /** Size in bytes. */
+  size?: number;
+  /** When the file was added or last changed. */
+  date?: Date | string | number;
+  uploader?: FileUploader;
+}
+
+// File kinds are categories, so each takes a categorical tone and never a
+// status colour: a PDF is not an error. See "Color Roles" in the brand guide.
+const KIND_ICON: Record<FilePreviewKind, { icon: LucideIcon; tone: CategoryTone }> = {
+  pdf: { icon: FileText, tone: "orange" },
+  image: { icon: FileImage, tone: "pink" },
+  video: { icon: FileVideo, tone: "violet" },
+  audio: { icon: FileAudio, tone: "cyan" },
+  csv: { icon: FileSpreadsheet, tone: "lime" },
+  spreadsheet: { icon: FileSpreadsheet, tone: "lime" },
+  code: { icon: FileCode, tone: "blue" },
+  json: { icon: FileJson, tone: "blue" },
+  yaml: { icon: FileCode, tone: "blue" },
+  markdown: { icon: FileText, tone: "teal" },
+  text: { icon: FileText, tone: "teal" },
+  binary: { icon: File, tone: "brown" },
+};
+
+/** The kind's icon on its category tone. Decorative: the filename names the file. */
+export function FileKindTile({
+  filename,
+  mimeType,
+  size = "md",
+  className,
+}: {
+  filename: string;
+  mimeType?: string;
+  size?: IconTileProps["size"];
+  className?: string;
+}) {
+  const { icon: Icon, tone } = KIND_ICON[resolveFilePreviewKind(filename, mimeType)];
+  return <IconTile tone={tone} size={size} icon={<Icon />} className={className} />;
+}
+
+function toDate(value: FileDetails["date"]): Date | undefined {
+  if (value === undefined) return undefined;
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
+const DATE_FORMAT = new Intl.DateTimeFormat(undefined, { dateStyle: "medium" });
+
+/**
+ * A dot between facts for the eye, a comma for a screen reader, which would
+ * otherwise read the facts as one run-on word or announce "middle dot".
+ */
+export function FactSeparator() {
+  return (
+    <>
+      <span aria-hidden="true"> · </span>
+      <span className="sr-only">, </span>
+    </>
+  );
+}
+
+/**
+ * The kind, size and date as one muted line, each part only when known.
+ * The date follows the reader's locale, which a server render may not share,
+ * so the element tolerates a hydration difference.
+ */
+export function FileFacts({
+  filename,
+  mimeType,
+  size,
+  date,
+  showKind = false,
+  className,
+}: Pick<FileDetails, "filename" | "mimeType" | "size" | "date"> & {
+  showKind?: boolean;
+  className?: string;
+}) {
+  const parsed = toDate(date);
+  const parts: React.ReactNode[] = [];
+  if (showKind) parts.push(getFormatLabel(resolveFilePreviewKind(filename, mimeType)));
+  if (size !== undefined) parts.push(formatBytes(size));
+  if (parsed) {
+    parts.push(
+      <time key="date" dateTime={parsed.toISOString()} suppressHydrationWarning>
+        {DATE_FORMAT.format(parsed)}
+      </time>,
+    );
+  }
+  if (parts.length === 0) return null;
+  return (
+    <span className={cn("text-xs text-muted-foreground", className)}>
+      {parts.map((part, index) => (
+        <React.Fragment key={index}>
+          {index > 0 && <FactSeparator />}
+          {part}
+        </React.Fragment>
+      ))}
+    </span>
+  );
+}
+
+/** "Dana Ruiz (Client)", or the name alone. */
+export function uploaderLabel(uploader: FileUploader): string {
+  return uploader.role ? `${uploader.name} (${uploader.role})` : uploader.name;
+}
+
+export interface FileCardProps
+  extends FileDetails,
+    Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+  /** One sentence under the details, such as why there is no preview. */
+  description?: React.ReactNode;
+  /** Adds a Download button. */
+  onDownload?: () => void;
+  /** Further buttons after Download, such as Open or Delete. */
+  actions?: React.ReactNode;
+}
+
+export const FileCard = React.forwardRef<HTMLDivElement, FileCardProps>(
+  (
+    {
+      filename,
+      mimeType,
+      size,
+      date,
+      uploader,
+      description,
+      onDownload,
+      actions,
+      className,
+      ...props
+    },
+    ref,
+  ) => (
+    <div
+      ref={ref}
+      className={cn(
+        "flex min-w-0 flex-col items-center justify-center rounded-[var(--radius-md)] border border-border bg-card px-6 py-12 text-center",
+        className,
+      )}
+      {...props}
+    >
+      <FileKindTile filename={filename} mimeType={mimeType} size="lg" />
+      <p
+        className="mt-3 line-clamp-2 max-w-full text-sm font-medium text-foreground [overflow-wrap:anywhere]"
+        title={filename}
+      >
+        {filename}
+      </p>
+      <FileFacts filename={filename} size={size} date={date} className="mt-1" />
+      {uploader && (
+        <p className="mt-0.5 max-w-full truncate text-xs text-muted-foreground">
+          Uploaded by {uploaderLabel(uploader)}
+        </p>
+      )}
+      {description && (
+        <div className="mt-3 max-w-md text-sm text-muted-foreground">{description}</div>
+      )}
+      {(onDownload || actions) && (
+        <div className="mt-5 flex flex-wrap items-center justify-center gap-2">
+          {onDownload && (
+            <Button type="button" variant="outline" size="sm" onClick={onDownload}>
+              <Download />
+              Download
+            </Button>
+          )}
+          {actions}
+        </div>
+      )}
+    </div>
+  ),
+);
+FileCard.displayName = "FileCard";

package/src/files/file-list.stories.tsx

@@ -0,0 +1,121 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import { Button } from "../primitives/button";
+import { FileCard } from "./file-card";
+import { FileList, type FileListItem } from "./file-list";
+
+const CASE_FILES: FileListItem[] = [
+  {
+    id: "lease",
+    filename: "Commercial lease — 418 Harbor Street.pdf",
+    size: 2_516_582,
+    date: "2026-09-28T16:20:00Z",
+    uploader: { name: "Dana Ruiz", role: "Client" },
+  },
+  {
+    id: "notice",
+    filename: "Notice of lease termination.pdf",
+    size: 75_955,
+    date: "2026-10-06T09:05:00Z",
+    uploader: { name: "Priya Adeyemi", role: "Attorney" },
+  },
+  {
+    id: "photos",
+    filename: "Rear storage room, water damage.jpg",
+    mimeType: "image/jpeg",
+    size: 3_145_728,
+    date: "2026-08-12T18:42:00Z",
+    uploader: { name: "Dana Ruiz", role: "Client" },
+  },
+  {
+    id: "ledger",
+    filename: "Rent ledger 2023–2026.xlsx",
+    size: 48_640,
+    date: "2026-09-30T11:00:00Z",
+    uploader: { name: "Coastal Property Holdings" },
+  },
+  {
+    id: "estimate",
+    filename: "Contractor estimate.docx",
+    size: 182_000,
+    date: "2026-08-20T14:10:00Z",
+  },
+];
+
+function CaseDocuments() {
+  const [files, setFiles] = useState(CASE_FILES);
+  const [openId, setOpenId] = useState("notice");
+  return (
+    <FileList
+      aria-label="Case documents"
+      files={files}
+      activeId={openId}
+      onOpen={(file) => setOpenId(file.id)}
+      onDownload={() => {}}
+      onDelete={(file) => setFiles((current) => current.filter((item) => item.id !== file.id))}
+      empty="No documents yet. Upload the lease to get started."
+    />
+  );
+}
+
+const meta: Meta<typeof FileList> = {
+  title: "Files/FileList",
+  component: FileList,
+  parameters: { layout: "fullscreen" },
+  decorators: [
+    (Story) => (
+      <div className="min-h-[100dvh] bg-background p-4 text-foreground">
+        <div className="mx-auto max-w-2xl">
+          <Story />
+        </div>
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof FileList>;
+
+export const Documents: Story = {
+  name: "Case documents",
+  render: () => <CaseDocuments />,
+};
+
+export const DocumentsLight: Story = {
+  name: "Case documents (light)",
+  globals: { theme: "light" },
+  render: () => <CaseDocuments />,
+};
+
+export const ReadOnly: Story = {
+  name: "Read-only list",
+  render: () => <FileList aria-label="Shared with you" files={CASE_FILES.slice(0, 3)} />,
+};
+
+export const Empty: Story = {
+  render: () => <FileList files={[]} empty="No documents yet. Upload the lease to get started." />,
+};
+
+export const Card: Story = {
+  name: "FileCard",
+  render: () => (
+    <FileCard
+      filename="Commercial lease — 418 Harbor Street.pdf"
+      size={2_516_582}
+      date="2026-09-28T16:20:00Z"
+      uploader={{ name: "Dana Ruiz", role: "Client" }}
+      onDownload={() => {}}
+      actions={
+        <Button type="button" size="sm">
+          Open
+        </Button>
+      }
+    />
+  ),
+};
+
+export const CardLight: Story = {
+  name: "FileCard (light)",
+  globals: { theme: "light" },
+  render: Card.render,
+};

package/src/files/file-list.test.tsx

@@ -0,0 +1,81 @@
+import { fireEvent, render, screen, within } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { FileList, type FileListItem } from "./file-list";
+
+interface CaseDocument extends FileListItem {
+  matterId: string;
+}
+
+const FILES: CaseDocument[] = [
+  {
+    id: "lease",
+    matterId: "m-1",
+    filename: "Commercial lease.pdf",
+    size: 482_000,
+    date: "2026-10-01T12:00:00Z",
+    uploader: { name: "Dana Ruiz", role: "Client" },
+  },
+  {
+    id: "photos",
+    matterId: "m-1",
+    filename: "Water damage.jpg",
+    mimeType: "image/jpeg",
+    size: 3_100_000,
+  },
+];
+
+describe("FileList", () => {
+  it("shows each file's kind, size and uploader", () => {
+    render(<FileList files={FILES} aria-label="Case documents" />);
+    const rows = within(screen.getByRole("list", { name: "Case documents" })).getAllByRole(
+      "listitem",
+    );
+    expect(rows).toHaveLength(2);
+    expect(rows[0]).toHaveTextContent("Commercial lease.pdf");
+    // A dot between facts on screen, a comma for a screen reader.
+    expect(rows[0]).toHaveTextContent(/PDF · , 471 KB · , .+ · , Dana Ruiz \(Client\)/);
+    expect(rows[1]).toHaveTextContent("Image · , 3.0 MB");
+  });
+
+  it("opens a file from its row and hands back the host's own record", () => {
+    const onOpen = vi.fn();
+    render(<FileList files={FILES} onOpen={onOpen} activeId="photos" />);
+
+    fireEvent.click(screen.getByRole("button", { name: /Commercial lease\.pdf/ }));
+    expect(onOpen).toHaveBeenCalledWith(FILES[0]);
+    expect(onOpen.mock.calls[0][0].matterId).toBe("m-1");
+
+    expect(screen.getByRole("button", { name: /Water damage\.jpg/ })).toHaveAttribute(
+      "aria-current",
+      "true",
+    );
+    expect(screen.getByRole("button", { name: /Commercial lease\.pdf/ })).not.toHaveAttribute(
+      "aria-current",
+    );
+  });
+
+  it("downloads and deletes through per-file buttons", () => {
+    const onDownload = vi.fn();
+    const onDelete = vi.fn();
+    render(<FileList files={FILES} onDownload={onDownload} onDelete={onDelete} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Download Water damage.jpg" }));
+    expect(onDownload).toHaveBeenCalledWith(FILES[1]);
+    fireEvent.click(screen.getByRole("button", { name: "Delete Commercial lease.pdf" }));
+    expect(onDelete).toHaveBeenCalledWith(FILES[0]);
+  });
+
+  it("renders no controls the host did not ask for", () => {
+    render(<FileList files={FILES} />);
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+
+  it("shows the empty message in place of the list", () => {
+    const { rerender } = render(<FileList files={[]} />);
+    expect(screen.queryByRole("list")).toBeNull();
+    expect(screen.getByText("No files yet.")).toBeInTheDocument();
+
+    rerender(<FileList files={[]} empty="Upload the lease to start." />);
+    expect(screen.getByText("Upload the lease to start.")).toBeInTheDocument();
+  });
+});