@tangle-network/ui 11.24.0 → 11.26.0

package/src/files/file-preview.tsx

@@ -2,7 +2,7 @@
  * FilePreview — universal file renderer.
  *
  * Renders any file type:
- * - PDF: embedded viewer at full pane height
+ * - PDF: PdfViewer's rendered pages at full pane height
  * - Images: fit to the pane on a checker ground; click toggles natural size
  * - Video / audio: native players
  * - CSV: sticky-header table, capped at CSV_PREVIEW_ROW_LIMIT rows
@@ -14,21 +14,13 @@
  */
 
 import { useState } from "react";
-import {
-  Download,
-  FileSpreadsheet,
-  FileText,
-  Music,
-  X,
-  type LucideIcon,
-} from "lucide-react";
+import { Download, Music, X } from "lucide-react";
 import type { UrlTransform } from "react-markdown";
 import { focusRingInset } from "../lib/focus";
 import { cn } from "../lib/utils";
-import { Button } from "../primitives/button";
 import { Markdown } from "../markdown/markdown";
 import { CodeBlock, CopyButton } from "../markdown/code-block";
-import { formatBytes } from "../utils/format";
+import { FileCard } from "./file-card";
 import {
   fileExtension,
   getCodeLanguage,
@@ -36,6 +28,7 @@ import {
   resolveFilePreviewKind,
   type FilePreviewKind,
 } from "./file-format";
+import { PdfViewer } from "./pdf-viewer";
 
 export interface FilePreviewProps {
   filename: string;
@@ -239,38 +232,6 @@ function ImagePreview({ src, filename }: { src: string; filename: string }) {
   );
 }
 
-function PdfPreview({
-  blobUrl,
-  filename,
-  size,
-  onDownload,
-}: {
-  blobUrl: string;
-  filename: string;
-  size?: number;
-  onDownload?: () => void;
-}) {
-  // <object> lets a browser without an inline PDF viewer render the fallback
-  // card instead of a blank frame. The viewer draws its own chrome, so the
-  // object has no border; the card brings its own and fills the same height.
-  return (
-    <object
-      data={blobUrl}
-      type="application/pdf"
-      title={filename}
-      className="min-h-[24rem] w-full flex-1 rounded-[var(--radius-md)]"
-    >
-      <DownloadCard
-        filename={filename}
-        size={size}
-        sentence="This browser does not show PDFs inline."
-        onDownload={onDownload}
-        className="h-full"
-      />
-    </object>
-  );
-}
-
 function VideoPreview({ src, filename }: { src: string; filename: string }) {
   return (
     <div className="flex min-h-[12rem] flex-1 items-center justify-center overflow-hidden rounded-[var(--radius-md)] border border-border bg-background">
@@ -318,52 +279,10 @@ function MarkdownPreview({
   );
 }
 
-/**
- * One muted sentence plus the filename, its size when known, and a Download
- * button when the host wires `onDownload`. Serves spreadsheets, binaries, and
- * every kind whose source (blob or text) is missing.
- */
-function DownloadCard({
-  filename,
-  size,
-  sentence,
-  icon: Icon = FileText,
-  onDownload,
-  className,
-}: {
-  filename: string;
-  size?: number;
-  sentence: string;
-  icon?: LucideIcon;
-  onDownload?: () => void;
-  className?: string;
-}) {
-  return (
-    <div
-      className={cn(
-        "flex flex-col items-center justify-center rounded-[var(--radius-md)] border border-dashed border-border bg-background px-6 py-16 text-center",
-        className,
-      )}
-    >
-      <Icon className="mb-3 h-12 w-12 text-muted-foreground opacity-40" />
-      <p className="max-w-full truncate text-sm font-medium text-foreground">{filename}</p>
-      {size !== undefined && (
-        <p className="mt-1 text-xs text-muted-foreground">{formatBytes(size)}</p>
-      )}
-      <p className="mt-3 max-w-md text-sm text-muted-foreground">{sentence}</p>
-      {onDownload && (
-        <Button type="button" variant="outline" size="sm" className="mt-5" onClick={onDownload}>
-          <Download />
-          Download
-        </Button>
-      )}
-    </div>
-  );
-}
-
 function PreviewBody({
   kind,
   filename,
+  mimeType,
   content,
   blobUrl,
   size,
@@ -372,6 +291,7 @@ function PreviewBody({
 }: {
   kind: FilePreviewKind;
   filename: string;
+  mimeType?: string;
   content?: string;
   blobUrl?: string;
   size?: number;
@@ -379,12 +299,14 @@ function PreviewBody({
   onDownload?: () => void;
 }) {
   const hasText = typeof content === "string";
-  const card = (sentence: string, icon?: LucideIcon) => (
-    <DownloadCard
+  // The card takes its icon from the kind, so a spreadsheet or a recording
+  // reads as one even when it cannot be shown.
+  const card = (sentence: string) => (
+    <FileCard
       filename={filename}
+      mimeType={mimeType}
       size={size}
-      sentence={sentence}
-      icon={icon}
+      description={sentence}
       onDownload={onDownload}
     />
   );
@@ -392,7 +314,15 @@ function PreviewBody({
   switch (kind) {
     case "pdf":
       if (blobUrl) {
-        return <PdfPreview blobUrl={blobUrl} filename={filename} size={size} onDownload={onDownload} />;
+        return (
+          <PdfViewer
+            src={blobUrl}
+            filename={filename}
+            size={size}
+            onDownload={onDownload}
+            className="min-h-[24rem] flex-1"
+          />
+        );
       }
       return card(NEEDS_DOWNLOAD_LINK);
     case "image":
@@ -405,10 +335,10 @@ function PreviewBody({
       return card(NEEDS_DOWNLOAD_LINK);
     case "audio":
       if (blobUrl) return <AudioPreview src={blobUrl} filename={filename} />;
-      return card(NEEDS_DOWNLOAD_LINK, Music);
+      return card(NEEDS_DOWNLOAD_LINK);
     case "csv":
       if (hasText) return <CsvPreview content={content} />;
-      return card(NO_INLINE_CONTENT, FileSpreadsheet);
+      return card(NO_INLINE_CONTENT);
     case "code":
     case "json":
     case "yaml":
@@ -421,7 +351,7 @@ function PreviewBody({
       if (hasText) return <TextPreview content={content} />;
       return card(NO_INLINE_CONTENT);
     case "spreadsheet":
-      return card("Download to open this workbook in a spreadsheet app.", FileSpreadsheet);
+      return card("Download to open this workbook in a spreadsheet app.");
     case "binary":
       if (hasText) return <TextPreview content={content} />;
       return card(blobUrl ? NO_INLINE_PREVIEW : NEEDS_DOWNLOAD_LINK);
@@ -482,6 +412,7 @@ export function FilePreview({
         <PreviewBody
           kind={kind}
           filename={filename}
+          mimeType={mimeType}
           content={content}
           blobUrl={blobUrl}
           size={size}

package/src/files/index.ts

@@ -18,6 +18,15 @@ export {
   parseCsv,
   type FilePreviewProps,
 } from "./file-preview";
+export { PdfViewer, type PdfViewerProps } from "./pdf-viewer";
+export { configurePdfViewer, type PdfViewerConfig } from "./pdf-loader";
+export {
+  FileCard,
+  type FileCardProps,
+  type FileDetails,
+  type FileUploader,
+} from "./file-card";
+export { FileList, type FileListProps, type FileListItem } from "./file-list";
 export { FileTabs, type FileTabsProps, type FileTabData } from "./file-tabs";
 export { FileArtifactPane, type FileArtifactPaneProps } from "./file-artifact-pane";
 export {

package/src/files/pdf-loader.test.ts

@@ -0,0 +1,130 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const PDFJS = "pdfjs-dist/legacy/build/pdf.mjs";
+const WORKER = "pdfjs-dist/legacy/build/pdf.worker.min.mjs";
+
+/** What the next import of pdf.js yields: a namespace, or a thrown error. */
+let pdfjsImport: () => Record<string, unknown>;
+let workerImports = 0;
+
+function installedPdfjs() {
+  return { getDocument: () => ({}), GlobalWorkerOptions: { workerSrc: "", workerPort: null } };
+}
+
+/**
+ * Loads the module under test with pdf.js replaced. The loader reads it through
+ * a dynamic import, so the substitution happens before the graph is built.
+ */
+async function loadModule() {
+  vi.resetModules();
+  vi.doMock(PDFJS, () => pdfjsImport());
+  vi.doMock(WORKER, () => {
+    workerImports += 1;
+    return {};
+  });
+  return await import("./pdf-loader");
+}
+
+let consoleWarn: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  pdfjsImport = installedPdfjs;
+  workerImports = 0;
+  consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  consoleWarn.mockRestore();
+  vi.doUnmock(PDFJS);
+  vi.doUnmock(WORKER);
+  vi.resetModules();
+});
+
+describe("loadPdfjs", () => {
+  it("runs the worker on the main thread when no worker URL is configured", async () => {
+    const { loadPdfjs } = await loadModule();
+    const pdfjs = await loadPdfjs();
+    expect(typeof pdfjs.getDocument).toBe("function");
+    expect(workerImports).toBe(1);
+    expect(pdfjs.GlobalWorkerOptions.workerSrc).toBe("");
+  });
+
+  it("uses the configured worker URL instead of importing the worker", async () => {
+    const { configurePdfViewer, loadPdfjs } = await loadModule();
+    configurePdfViewer({ workerSrc: "/assets/pdf.worker.min.mjs", assetsUrl: "/pdfjs/" });
+    const pdfjs = await loadPdfjs();
+    expect(pdfjs.GlobalWorkerOptions.workerSrc).toBe("/assets/pdf.worker.min.mjs");
+    expect(workerImports).toBe(0);
+    expect(consoleWarn).not.toHaveBeenCalled();
+  });
+
+  it("warns once that scanned pages need assetsUrl", async () => {
+    const { loadPdfjs } = await loadModule();
+    await loadPdfjs();
+    await loadPdfjs();
+    expect(consoleWarn).toHaveBeenCalledTimes(1);
+    expect(consoleWarn.mock.calls[0][0]).toMatch(/no assetsUrl.*JBIG2, CCITT fax/);
+  });
+
+  it("treats a stub without the pdf.js API as missing, for the rest of the session", async () => {
+    // What a bundler told to ignore the uninstalled peer hands back.
+    pdfjsImport = () => ({ default: {}, getDocument: undefined });
+    const { loadPdfjs, isMissingPdfjsError } = await loadModule();
+    const first = await loadPdfjs().catch((error: unknown) => error);
+    expect(isMissingPdfjsError(first)).toBe(true);
+    expect((first as Error).message).toMatch(/Install pdfjs-dist/);
+
+    pdfjsImport = installedPdfjs;
+    expect(await loadPdfjs().catch((error: unknown) => error)).toBe(first);
+  });
+
+  it("tries again after a failure that is not a missing package", async () => {
+    let attempts = 0;
+    pdfjsImport = () => {
+      attempts += 1;
+      if (attempts === 1) throw new Error("Failed to fetch dynamically imported module");
+      return installedPdfjs();
+    };
+    const { loadPdfjs, isMissingPdfjsError } = await loadModule();
+    const failure = await loadPdfjs().catch((error: unknown) => error);
+    expect(isMissingPdfjsError(failure)).toBe(false);
+    await expect(loadPdfjs()).resolves.toHaveProperty("getDocument");
+  });
+});
+
+describe("asMissingPdfjsError", () => {
+  it("names pdfjs-dist only for a resolution failure about it", async () => {
+    const { asMissingPdfjsError, isMissingPdfjsError } = await loadModule();
+    for (const message of [
+      `Failed to resolve import "${PDFJS}". Does the file exist?`,
+      `Could not resolve "pdfjs-dist/legacy/build/pdf.mjs"`,
+      "Cannot find module 'pdfjs-dist/legacy/build/pdf.mjs'",
+    ]) {
+      expect(isMissingPdfjsError(asMissingPdfjsError(new Error(message))), message).toBe(true);
+    }
+    const chunk = new Error("Failed to fetch dynamically imported module");
+    expect(asMissingPdfjsError(chunk)).toBe(chunk);
+    const other = new Error('Could not resolve "./chunk-abc.js"');
+    expect(asMissingPdfjsError(other)).toBe(other);
+  });
+});
+
+describe("pdfAssetParams", () => {
+  it("asks for nothing until assetsUrl is configured", async () => {
+    const { pdfAssetParams } = await loadModule();
+    expect(pdfAssetParams()).toEqual({});
+  });
+
+  it("points every asset directory under an absolute assetsUrl", async () => {
+    const { configurePdfViewer, pdfAssetParams } = await loadModule();
+    configurePdfViewer({ assetsUrl: "/static/pdfjs" });
+    const base = new URL("/static/pdfjs/", document.baseURI).href;
+    expect(pdfAssetParams()).toEqual({
+      wasmUrl: `${base}wasm/`,
+      cMapUrl: `${base}cmaps/`,
+      cMapPacked: true,
+      standardFontDataUrl: `${base}standard_fonts/`,
+      iccUrl: `${base}iccs/`,
+    });
+  });
+});

package/src/files/pdf-loader.ts

@@ -0,0 +1,169 @@
+/**
+ * Loads pdf.js for `PdfViewer`, which renders PDF pages to canvas in every
+ * browser, including Android Chrome and iOS Safari, where `<object>` shows a
+ * blank frame or only the first page.
+ *
+ * `pdfjs-dist` is an optional peer, reached only through the dynamic imports
+ * below, for the reasons `editor/editor-peers.ts` gives: a static import fails
+ * the build of every consumer that does not install it, and esbuild defers an
+ * unresolved `import()` to run time only when the call carries a `.catch()`.
+ * `scripts/validate-dist.mjs` enforces both.
+ *
+ * The legacy build is deliberate. The modern build calls APIs such as
+ * `Map.prototype.getOrInsertComputed` without a fallback, so it throws on
+ * phone browsers a year or two old; the legacy build carries polyfills for
+ * them at about 60 KB more minified code. The worker comes from the same
+ * build, because pdf.js refuses a worker whose version differs from its own.
+ *
+ * Worker. pdf.js parses documents in a worker named by `workerSrc`. No
+ * bundler-neutral expression yields that URL from inside a library, and the
+ * pdf.js default fetches from a CDN, so by default this module imports the
+ * worker module itself. pdf.js then runs its worker code on the main thread,
+ * which works in Vite, esbuild, webpack and Cloudflare Workers builds with no
+ * configuration and no third-party fetch. Parsing a large document then
+ * competes with scrolling, so production apps should serve the worker file and
+ * pass its URL to `configurePdfViewer` before the first viewer renders. With
+ * Vite:
+ *
+ *   import workerSrc from "pdfjs-dist/legacy/build/pdf.worker.min.mjs?url";
+ *   configurePdfViewer({ workerSrc });
+ *
+ * The setting is page-wide because pdf.js's own worker setting is: once the
+ * main-thread worker is loaded, every document on the page uses it.
+ *
+ * Assets. pdf.js 6 decodes JBIG2, CCITT fax and JPEG 2000 images with
+ * WebAssembly modules it fetches at run time; black-and-white scans use the
+ * first two. Without `assetsUrl` those images do not render, and pdf.js warns
+ * only in the console, so this module warns once when it loads without one.
+ */
+
+import type * as Pdfjs from "pdfjs-dist";
+import { isMissingPeerError, rethrow } from "../lib/optional-peer";
+
+export type PdfjsLib = typeof Pdfjs;
+
+export interface PdfViewerConfig {
+  /**
+   * URL of `pdfjs-dist/legacy/build/pdf.worker.min.mjs` from the installed
+   * pdfjs-dist, served by the app. Moves PDF parsing off the main thread.
+   */
+  workerSrc?: string;
+  /**
+   * Base URL, ending in `/`, under which the app serves the `wasm/`, `cmaps/`,
+   * `standard_fonts/` and `iccs/` directories of the installed pdfjs-dist.
+   * Needed for scanned pages, CJK text and non-embedded fonts.
+   */
+  assetsUrl?: string;
+}
+
+let config: PdfViewerConfig = {};
+
+/**
+ * Sets the page-wide pdf.js worker and asset locations. Call it once, before
+ * the first `PdfViewer` renders; a worker set afterwards applies only when no
+ * document has loaded the main-thread worker yet.
+ */
+export function configurePdfViewer(next: PdfViewerConfig): void {
+  config = { ...next };
+}
+
+/**
+ * The optional peer behind `PdfViewer`. `scripts/validate-dist.mjs` reads this
+ * list and requires every import of it to be dynamic and caught.
+ */
+const DEFERRED_PEERS = ["pdfjs-dist"];
+
+/** pdfjs-dist is absent, or resolved to a stub with none of its API. */
+export class MissingPdfjsError extends Error {
+  constructor(options?: { cause?: unknown }) {
+    super(
+      "PdfViewer needs the optional peer pdfjs-dist. Install pdfjs-dist to render PDF pages.",
+      options,
+    );
+    this.name = "MissingPdfjsError";
+  }
+}
+
+export function isMissingPdfjsError(error: unknown): boolean {
+  return error instanceof Error && error.name === "MissingPdfjsError";
+}
+
+/**
+ * Turns a resolution failure that names pdfjs-dist into `MissingPdfjsError`.
+ * Any other rejection, such as a chunk that did not download, passes through.
+ */
+export function asMissingPdfjsError(error: unknown): unknown {
+  if (!isMissingPeerError(error)) return error;
+  const message = (error as Error).message;
+  return DEFERRED_PEERS.some((name) => message.includes(name))
+    ? new MissingPdfjsError({ cause: error })
+    : error;
+}
+
+async function importPdfjs(): Promise<PdfjsLib> {
+  let pdfjs: PdfjsLib;
+  try {
+    pdfjs = await import("pdfjs-dist/legacy/build/pdf.mjs").catch(rethrow);
+  } catch (error) {
+    throw asMissingPdfjsError(error);
+  }
+  // A bundler told to ignore the missing peer can hand back an empty module.
+  if (typeof pdfjs.getDocument !== "function") throw new MissingPdfjsError();
+  return pdfjs;
+}
+
+let pending: Promise<PdfjsLib> | null = null;
+let warnedAboutAssets = false;
+
+/**
+ * Resolves pdf.js with its worker configured. A missing peer stays missing for
+ * the session, so its rejection is kept; any other failure, such as a chunk
+ * that did not download, is dropped so the next viewer tries again.
+ */
+export function loadPdfjs(): Promise<PdfjsLib> {
+  pending ??= importPdfjs().catch((error: unknown) => {
+    if (!isMissingPdfjsError(error)) pending = null;
+    throw error;
+  });
+  return pending.then(async (pdfjs) => {
+    const { GlobalWorkerOptions } = pdfjs;
+    if (config.workerSrc) {
+      GlobalWorkerOptions.workerSrc = config.workerSrc;
+    } else if (!GlobalWorkerOptions.workerSrc && !GlobalWorkerOptions.workerPort) {
+      // Defines `globalThis.pdfjsWorker`, which pdf.js runs on this thread.
+      await import("pdfjs-dist/legacy/build/pdf.worker.min.mjs").catch(rethrow);
+    }
+    if (!config.assetsUrl && !warnedAboutAssets) {
+      warnedAboutAssets = true;
+      console.warn(
+        "PdfViewer: no assetsUrl is configured, so JBIG2, CCITT fax and JPEG 2000 images " +
+          "(most black-and-white scans) will not render. See configurePdfViewer.",
+      );
+    }
+    return pdfjs;
+  });
+}
+
+/** The `getDocument` options that locate pdf.js's run-time assets. */
+export interface PdfAssetParams {
+  wasmUrl?: string;
+  cMapUrl?: string;
+  cMapPacked?: boolean;
+  standardFontDataUrl?: string;
+  iccUrl?: string;
+}
+
+/** `getDocument` asset options for the configured `assetsUrl`, or none. */
+export function pdfAssetParams(): PdfAssetParams {
+  if (!config.assetsUrl) return {};
+  // pdf.js joins file names onto these with plain concatenation, and a
+  // worker resolves a relative URL against its own script, so make it absolute.
+  const base = new URL(config.assetsUrl, document.baseURI).href.replace(/\/?$/, "/");
+  return {
+    wasmUrl: `${base}wasm/`,
+    cMapUrl: `${base}cmaps/`,
+    cMapPacked: true,
+    standardFontDataUrl: `${base}standard_fonts/`,
+    iccUrl: `${base}iccs/`,
+  };
+}

package/src/files/pdf-viewer.stories.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { configurePdfViewer, type PdfViewerConfig } from "./pdf-loader";
+import { PdfViewer } from "./pdf-viewer";
+
+// Served by .storybook/main.ts from .storybook/fixtures.
+// US Courts form AO 440, Summons in a Civil Action: two pages, a work of the
+// United States government (https://www.uscourts.gov/sites/default/files/ao440.pdf).
+const SUMMONS = "/fixtures/summons-ao440.pdf";
+// A fictional three-page letter stored as CCITT Group 4 images at 200 dpi, the
+// way an office scanner writes black-and-white pages.
+const SCANNED_LETTER = "/fixtures/scanned-letter.pdf";
+
+/** The worker and decoder assets, served the way an app serves them. */
+const SERVED_ASSETS: PdfViewerConfig = {
+  workerSrc: "/pdfjs/legacy/build/pdf.worker.min.mjs",
+  assetsUrl: "/pdfjs/",
+};
+
+// Storybook deep-merges parameters, so an empty story-level object would keep
+// the served assets; a named mode cannot be merged into.
+type PdfAssets = "served" | "none";
+
+const meta: Meta<typeof PdfViewer> = {
+  title: "Files/PdfViewer",
+  component: PdfViewer,
+  parameters: { layout: "fullscreen", pdfAssets: "served" satisfies PdfAssets },
+  decorators: [
+    (Story, context) => {
+      // pdf.js fixes its worker with the first document on the page, so a
+      // story's configuration holds when the story is opened on its own.
+      configurePdfViewer(context.parameters.pdfAssets === "none" ? {} : SERVED_ASSETS);
+      return (
+        <div className="h-[100dvh] w-full bg-background p-3 text-foreground sm:h-[680px] sm:max-w-[820px]">
+          <Story />
+        </div>
+      );
+    },
+  ],
+  args: {
+    src: SUMMONS,
+    filename: "Summons in a Civil Action.pdf",
+    size: 25_380,
+    onDownload: () => {},
+    className: "h-full",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof PdfViewer>;
+
+export const CourtForm: Story = {
+  name: "Court form",
+};
+
+export const CourtFormLight: Story = {
+  name: "Court form (light)",
+  globals: { theme: "light" },
+};
+
+export const ScannedLetter: Story = {
+  name: "Scanned letter (CCITT pages)",
+  args: {
+    src: SCANNED_LETTER,
+    filename: "Notice of lease termination.pdf",
+    size: 75_955,
+  },
+};
+
+export const ZeroConfiguration: Story = {
+  name: "Zero configuration (main-thread worker)",
+  parameters: { pdfAssets: "none" satisfies PdfAssets },
+};
+
+export const NotAPdf: Story = {
+  name: "Not a PDF (falls back)",
+  args: {
+    src: "data:application/pdf;base64,VGhpcyBpcyBub3QgYSBQREYu",
+    filename: "Exhibit C.pdf",
+    size: 15,
+  },
+};