feat: file viewer

.gitignore

@@ -25,3 +25,6 @@ yarn-debug.log*
 yarn-error.log*
 
 *storybook.log
+
+# "yarn pack" output
+*.tgz

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kleros/ui-components-library",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "UI components library which implements the Kleros design system.",
   "source": "./src/lib/index.ts",
   "main": "./dist/index.js",
@@ -91,6 +91,7 @@
     "tailwindcss": "^4.0.11"
   },
   "dependencies": {
+    "@cyntler/react-doc-viewer": "^1.17.0",
     "@internationalized/date": "^3.7.0",
     "bignumber.js": "^9.1.2",
     "clsx": "^2.1.1",
@@ -99,6 +100,7 @@
     "react-aria-components": "^1.7.1",
     "react-dom": "^18.0.0",
     "react-is": "^18.0.0",
+    "react-markdown": "^9.0.1",
     "simplebar": "^5.3.6",
     "simplebar-react": "^2.3.6",
     "tailwind-merge": "^3.0.2",

src/lib/file-viewer/index.tsx

@@ -0,0 +1,250 @@
+import React, { useMemo } from "react";
+import DocViewer, {
+  DocViewerRenderers,
+  type IConfig,
+  type ITheme,
+  type IDocument,
+} from "@cyntler/react-doc-viewer";
+
+import { cn } from "../../utils";
+import MarkdownDocRenderer from "./markdown-viewer";
+import SvgDocRenderer from "./svg-viewer";
+import "@cyntler/react-doc-viewer/dist/index.css";
+
+interface FileViewerProps {
+  /** URL of the file to display. Supports https:, http:, blob:, and data: URIs. */
+  url: string;
+  /** Optional file name override (used for download). Useful when the URL path lacks a meaningful filename. */
+  fileName?: string;
+  /** Override the DocViewer config. Merged shallowly over the defaults. */
+  config?: IConfig;
+  /** Class applied to the outer wrapper. */
+  className?: string;
+  /**
+   * Opt-in allowlist of `data:` URI MIME types that bypass the script-execution
+   * gate. By default the viewer rejects `data:` URLs whose MIME can execute
+   * code on top-frame navigation: `text/html`, `application/xhtml+xml`,
+   * `application/xml`, `text/xml`, `image/svg+xml`.
+   *
+   * Pass entries here only when the URL source is trusted. `image/svg+xml`
+   * is rendered through `<img>` (W3C secure static mode — scripts and
+   * external references are disabled by the browser) so opting it in stays
+   * safe; the other entries lose the defense-in-depth gate against the
+   * fallback "open in new tab" link.
+   */
+  allowedDataMimes?: readonly string[];
+}
+
+const SAFE_URL_SCHEMES = new Set(["http:", "https:", "blob:", "data:"]);
+
+// Data-URL MIMEs that execute script on top-frame navigation. Modern Firefox
+// and Chrome already block most of these via their data:-navigation
+// restrictions, but coverage varies by version and type (XHTML and XML have
+// historically slipped through), so re-enforcing at the gate keeps the threat
+// model trivially auditable. SVG is included because `<svg onload>` runs
+// script when navigated to (it does not when loaded via `<img src>`). XML and
+// XHTML can execute script via xml-stylesheet processing instructions or
+// inline `<script>` once parsed as a document.
+const UNSAFE_DATA_MIMES = new Set([
+  "text/html",
+  "application/xhtml+xml",
+  "application/xml",
+  "text/xml",
+  "image/svg+xml",
+]);
+
+/**
+ * Returns true if `raw` is a relative URL or uses an allowlisted scheme.
+ * Blocks `javascript:`, `vbscript:`, `file:`, `about:`, and anything else
+ * that could execute code or escape sandboxing when clicked.
+ *
+ * `allowedDataMimes` is a consumer-supplied override for the default
+ * `UNSAFE_DATA_MIMES` blocklist — entries here pass even if blocklisted.
+ */
+const isSafeUrl = (
+  raw: string,
+  allowedDataMimes: ReadonlySet<string>,
+): boolean => {
+  if (typeof raw !== "string" || raw.length === 0) return false;
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    // Relative URLs (e.g. "/foo", "./bar.pdf") throw — they resolve against
+    // the page origin and inherit its safety, so they're allowed.
+    return true;
+  }
+  const protocol = parsed.protocol.toLowerCase();
+  if (!SAFE_URL_SCHEMES.has(protocol)) return false;
+  if (protocol === "data:") {
+    const rawMime = parsed.pathname.split(/[,;]/)[0].trim().toLowerCase();
+    // Defense-in-depth: spec-compliant browsers do NOT percent-decode the
+    // data:-URL mediatype (WHATWG Fetch § data URL processor parses it raw;
+    // Chromium's DataURL::Parse only unescapes the body), so `text%2Fhtml`
+    // fails MIME parsing and falls back to `text/plain` — already safe. We
+    // decode anyway to harden against legacy or non-conforming runtimes;
+    // reject if decoding throws so malformed inputs can't slip through.
+    let mime: string;
+    try {
+      mime = decodeURIComponent(rawMime);
+    } catch {
+      return false;
+    }
+    if (allowedDataMimes.has(mime)) return true;
+    if (UNSAFE_DATA_MIMES.has(mime)) return false;
+  }
+  return true;
+};
+
+const defaultConfig: IConfig = {
+  header: {
+    disableHeader: true,
+    disableFileName: true,
+  },
+  pdfZoom: {
+    defaultZoom: 0.8,
+    zoomJump: 0.1,
+  },
+  pdfVerticalScrollByDefault: true,
+};
+
+const docTheme: ITheme = {
+  primary: "var(--klerosUIComponentsWhiteBackground)",
+  secondary: "var(--klerosUIComponentsLightBackground)",
+  tertiary: "var(--klerosUIComponentsLightBackground)",
+  textPrimary: "var(--klerosUIComponentsPrimaryText)",
+  textSecondary: "var(--klerosUIComponentsSecondaryText)",
+  textTertiary: "var(--klerosUIComponentsSecondaryText)",
+};
+
+const UnsupportedUrlMessage = ({ url }: { url: string }) => (
+  <div
+    className={cn(
+      "text-klerosUIComponentsSecondaryText text-sm",
+      "flex flex-col gap-2 p-6",
+    )}
+  >
+    <p>Unable to display this file.</p>
+    <p className="font-mono text-xs break-all">{url}</p>
+  </div>
+);
+
+const NoRendererFallback = ({
+  document,
+  fileName,
+}: {
+  document: IDocument | undefined;
+  fileName: string;
+}) => (
+  <div
+    className={cn(
+      "text-klerosUIComponentsPrimaryText text-sm",
+      "flex flex-col items-start gap-3 p-6",
+    )}
+  >
+    <p>This file type can&apos;t be previewed.</p>
+    <a
+      className="text-klerosUIComponentsPrimaryBlue underline"
+      href={document?.uri ?? ""}
+      download={fileName}
+      rel="noopener noreferrer"
+      target="_blank"
+    >
+      Open in a new tab
+    </a>
+  </div>
+);
+
+/**
+ * Displays a file from a URL inside the application. Supports PDFs, images,
+ * markdown, plaintext, and common document formats.
+ *
+ * Security: rejects `javascript:`, `vbscript:`, `file:`, and other unlisted
+ * schemes up front so a hostile `url` can't deliver code execution through
+ * the underlying viewer or its fallback download link.
+ */
+function FileViewer({
+  url,
+  fileName,
+  config,
+  className,
+  allowedDataMimes,
+}: Readonly<FileViewerProps>) {
+  const allowedDataMimesSet = useMemo(
+    () => new Set((allowedDataMimes ?? []).map((m) => m.toLowerCase())),
+    [allowedDataMimes],
+  );
+  const safe = isSafeUrl(url, allowedDataMimesSet);
+
+  const docs = useMemo(() => [{ uri: url, fileName }], [url, fileName]);
+
+  const pluginRenderers = useMemo(
+    () => [...DocViewerRenderers, MarkdownDocRenderer, SvgDocRenderer],
+    [],
+  );
+
+  const mergedConfig = useMemo<IConfig>(
+    () => ({
+      ...defaultConfig,
+      ...config,
+      noRenderer: {
+        ...config?.noRenderer,
+        overrideComponent:
+          config?.noRenderer?.overrideComponent ?? NoRendererFallback,
+      },
+    }),
+    [config],
+  );
+
+  return (
+    <div
+      className={cn(
+        "bg-klerosUIComponentsWhiteBackground shadow-default",
+        "rounded-base max-h-[80vh] overflow-auto",
+        className,
+      )}
+    >
+      {safe ? (
+        <DocViewer
+          documents={docs}
+          pluginRenderers={pluginRenderers}
+          config={mergedConfig}
+          theme={docTheme}
+          className={cn(
+            "!bg-klerosUIComponentsWhiteBackground",
+            "[&_#pdf-controls]:!z-[3]",
+            "[&_#pdf-controls]:!bg-klerosUIComponentsPrimaryPurple/15",
+            "dark:[&_#pdf-controls]:!bg-klerosUIComponentsLightBackground/50",
+            "[&_#pdf-controls]:!backdrop-saturate-150",
+            "[&_#pdf-controls_svg_path]:!fill-klerosUIComponentsPrimaryText",
+            "[&_#pdf-controls_svg_polygon]:!fill-klerosUIComponentsPrimaryText",
+            "[&_#image-renderer]:!bg-klerosUIComponentsWhiteBackground",
+            "[&_#image-renderer]:!h-auto",
+            "[&_#image-renderer]:!flex-none",
+            "[&_#image-renderer]:!px-6",
+            // Transparency checkerboard. The gradient is inlined in the
+            // arbitrary property (rather than a theme token) so the inner
+            // `var(--klerosUIComponentsImageCheckerColor)` resolves at this
+            // element's cascade — consumers can override that single variable
+            // anywhere up the tree and the color propagates. A theme-token
+            // wrapper would bake the inner var() at `:root` and the override
+            // would silently no-op for descendants. Full arbitrary-property
+            // syntax (not `bg-*` shortcut) so `tailwind-merge` recognizes this
+            // as background-image and doesn't collide with the bg-color above.
+            // eslint-disable-next-line max-len
+            "[&_#image-renderer]:![background-image:linear-gradient(45deg,var(--klerosUIComponentsImageCheckerColor)_25%,transparent_25%),linear-gradient(-45deg,var(--klerosUIComponentsImageCheckerColor)_25%,transparent_25%),linear-gradient(45deg,transparent_75%,var(--klerosUIComponentsImageCheckerColor)_75%),linear-gradient(-45deg,transparent_75%,var(--klerosUIComponentsImageCheckerColor)_75%)]",
+            "[&_#image-renderer]:![background-size:20px_20px]",
+            "[&_#image-renderer]:![background-position:0_0,0_10px,10px_-10px,-10px_0px]",
+            "[&_#image-img]:!max-w-full",
+            "[&_#image-img]:!max-h-[80vh]",
+            "[&_[class*='--loading']]:text-klerosUIComponentsSecondaryText",
+          )}
+        />
+      ) : (
+        <UnsupportedUrlMessage url={url} />
+      )}
+    </div>
+  );
+}
+
+export default FileViewer;

src/lib/file-viewer/markdown-viewer.tsx

@@ -0,0 +1,54 @@
+import React from "react";
+import { type DocRenderer } from "@cyntler/react-doc-viewer";
+import ReactMarkdown from "react-markdown";
+
+const decodeBase64Utf8 = (base64: string): string => {
+  const binary = atob(base64);
+  const bytes = Uint8Array.from(binary, (char) => char.codePointAt(0) ?? 0);
+  return new TextDecoder("utf-8").decode(bytes);
+};
+
+const MarkdownDocRenderer: DocRenderer = ({
+  mainState: { currentDocument },
+}) => {
+  if (!currentDocument?.fileData) return null;
+
+  const { fileData } = currentDocument;
+  let text: string;
+
+  if (fileData instanceof ArrayBuffer) {
+    text = new TextDecoder("utf-8").decode(fileData);
+  } else if (fileData.startsWith("data:")) {
+    // RFC 2397: `data:[<mediatype>][;base64],<payload>` — the payload is
+    // base64 only when `;base64` is the last parameter before the comma;
+    // otherwise it's percent-encoded. Dispatching on `atob` success would
+    // mis-decode payloads that happen to be valid base64 by coincidence
+    // (e.g. the literal string "test" atob's into garbage bytes).
+    const commaIdx = fileData.indexOf(",");
+    const header =
+      commaIdx === -1 ? "" : fileData.slice("data:".length, commaIdx);
+    const payload = commaIdx === -1 ? "" : fileData.slice(commaIdx + 1);
+    const isBase64 = header.toLowerCase().endsWith(";base64");
+    try {
+      text = isBase64 ? decodeBase64Utf8(payload) : decodeURIComponent(payload);
+    } catch {
+      text = "";
+    }
+  } else {
+    text = fileData;
+  }
+
+  return (
+    <div
+      id="md-renderer"
+      className="text-klerosUIComponentsPrimaryText [&_code]:text-klerosUIComponentsSecondaryText p-4 [&_a]:text-base"
+    >
+      <ReactMarkdown>{text}</ReactMarkdown>
+    </div>
+  );
+};
+
+MarkdownDocRenderer.fileTypes = ["md", "text/plain"];
+MarkdownDocRenderer.weight = 1;
+
+export default MarkdownDocRenderer;

src/lib/file-viewer/svg-viewer.tsx

@@ -0,0 +1,34 @@
+import React from "react";
+import { type DocRenderer } from "@cyntler/react-doc-viewer";
+
+// Render SVG via `<img src>` rather than navigating to it or embedding it as a
+// document. `<img>`-loaded SVG runs in the W3C "secure static" mode: scripts,
+// event handlers, external `<image>`/`<use>` references, CSS `url()`, and
+// `<foreignObject>` are all disabled by the browser. This is the same sandbox
+// GitHub, Wikipedia, and Notion use for user-uploaded SVGs. Without this
+// renderer, DocViewer has no SVG match and falls back to the "open in new
+// tab" link, which top-frame-navigates to the URL and executes any scripts
+// in the SVG document.
+//
+// IDs match upstream image renderer ids (`#image-renderer`, `#image-img`) so
+// the existing arbitrary-variant styles in `index.tsx` apply uniformly.
+// `flex items-center justify-center` here mirrors what doc-viewer's PNG
+// styled-component provides for raster renderers — our element doesn't pick
+// up that class, so we set it inline to keep the image centered.
+const SvgDocRenderer: DocRenderer = ({ mainState: { currentDocument } }) => {
+  if (!currentDocument?.uri) return null;
+  return (
+    <div id="image-renderer" className="flex items-center justify-center">
+      <img
+        id="image-img"
+        src={currentDocument.uri}
+        alt={currentDocument.fileName ?? ""}
+      />
+    </div>
+  );
+};
+
+SvgDocRenderer.fileTypes = ["svg", "image/svg+xml"];
+SvgDocRenderer.weight = 1;
+
+export default SvgDocRenderer;

src/lib/index.ts

@@ -52,3 +52,5 @@ export { default as ScrollbarContainer } from "../lib/scrollbar";
 export { default as Copiable } from "../lib/copiable";
 
 export { default as DraggableList } from "../lib/draggable-list";
+
+export { default as FileViewer } from "../lib/file-viewer";