@elabs-ai/components-viewer 4.0.0

package/src/adapters/index.ts

@@ -0,0 +1,64 @@
+/**
+ * The built-in adapters, and the registry that has them all.
+ *
+ * Every entry is `manifest` (eager, plain data) + `() => import(…)` (lazy). The
+ * manifests are imported statically ON PURPOSE — they are a few dozen bytes of
+ * data each and answer "can this be opened, and what controls apply" with no
+ * network. The parsers and renderers behind them are not.
+ *
+ * `pnpm heavy-deps:check` enforces the split: a static import of `papaparse`
+ * (or, from P1, `pdfjs-dist`) fails CI, because those are optional peers — a
+ * static edge does not merely bloat a chunk, it makes the package unresolvable
+ * for every consumer that did not install that parser.
+ */
+
+import { codeManifest } from "./code/code-manifest";
+import { csvManifest } from "./csv/csv-manifest";
+import { docxManifest } from "./docx/docx-manifest";
+import { markdownManifest } from "./markdown/markdown-manifest";
+import { imageManifest } from "./image/image-manifest";
+import { jsonManifest } from "./json/json-manifest";
+import { mediaManifest } from "./media/media-manifest";
+import { pdfManifest } from "./pdf/pdf-manifest";
+import { pptxManifest } from "./pptx/pptx-manifest";
+import { textManifest } from "./text/text-manifest";
+import { xlsxManifest } from "./xlsx/xlsx-manifest";
+import { createRegistry, type ViewerRegistry } from "../core/registry";
+
+export {
+  codeManifest,
+  csvManifest,
+  docxManifest,
+  imageManifest,
+  jsonManifest,
+  markdownManifest,
+  mediaManifest,
+  pdfManifest,
+  pptxManifest,
+  textManifest,
+  xlsxManifest,
+};
+
+/**
+ * A registry with every built-in adapter registered.
+ *
+ * Call it per app (or per view) rather than sharing one module-level instance,
+ * so one screen's `register()` override cannot leak into another's.
+ */
+export function createDefaultRegistry(): ViewerRegistry {
+  const registry = createRegistry();
+  registry.register(imageManifest, () => import("./image/image-adapter"));
+  registry.register(jsonManifest, () => import("./json/json-adapter"));
+  registry.register(csvManifest, () => import("./csv/csv-adapter"));
+  registry.register(pdfManifest, () => import("./pdf/pdf-adapter"));
+  registry.register(mediaManifest, () => import("./media/media-adapter"));
+  registry.register(docxManifest, () => import("./docx/docx-adapter"));
+  registry.register(xlsxManifest, () => import("./xlsx/xlsx-adapter"));
+  registry.register(pptxManifest, () => import("./pptx/pptx-adapter"));
+  registry.register(markdownManifest, () => import("./markdown/markdown-adapter"));
+  registry.register(codeManifest, () => import("./code/code-adapter"));
+  // Registered last and claiming only broad categories, so anything above wins
+  // a file it names specifically. This is the "readable as text" backstop.
+  registry.register(textManifest, () => import("./text/text-adapter"));
+  return registry;
+}

package/src/adapters/json/json-adapter.test.tsx

@@ -0,0 +1,77 @@
+import { normalizeFileSource } from "@elabs-ai/components-ui";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { isViewerError } from "../../core/errors";
+import jsonModule, { toTreeNodes, type JsonDocument } from "./json-adapter";
+
+const parse = (text: string) =>
+  jsonModule
+    .create()
+    .load(
+      normalizeFileSource({ kind: "text", text, name: "data.json" }),
+      {},
+    ) as Promise<JsonDocument>;
+
+describe("toTreeNodes", () => {
+  it("uses the JSON path as the node id, so ids are stable and addressable", () => {
+    const nodes = toTreeNodes({ items: [{ name: "a" }] });
+    expect(nodes[0]?.id).toBe("$.items");
+    expect(nodes[0]?.children?.[0]?.id).toBe("$.items[0]");
+    expect(nodes[0]?.children?.[0]?.children?.[0]?.id).toBe("$.items[0].name");
+  });
+
+  it("gives scalars no children, so they render as leaves", () => {
+    const nodes = toTreeNodes({ n: 1, s: "x", b: true, nul: null });
+    expect(nodes.map((node) => node.children)).toEqual([
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+    ]);
+  });
+
+  it("returns nothing for a scalar root — there is no structure to expand", () => {
+    expect(toTreeNodes(42)).toEqual([]);
+    expect(toTreeNodes("hello")).toEqual([]);
+    expect(toTreeNodes(null)).toEqual([]);
+  });
+
+  it("keeps empty containers expandable-looking but childless", () => {
+    const nodes = toTreeNodes({ empty: {}, none: [] });
+    expect(nodes[0]?.children).toEqual([]);
+    expect(nodes[1]?.children).toEqual([]);
+  });
+});
+
+describe("json adapter — parsing", () => {
+  it("parses to a real value and keeps the source text", async () => {
+    const doc = await parse('{"a":1}');
+    expect(doc.value).toEqual({ a: 1 });
+    expect(doc.text).toBe('{"a":1}');
+  });
+
+  it("fails invalid JSON terminally rather than falling through to plain text", async () => {
+    const error = await parse("{ not json ").catch((e: unknown) => e);
+    expect(isViewerError(error) && error.code).toBe("parse-failed");
+    // The engine's own message carries the position — the one fact the user needs.
+    expect(isViewerError(error) && error.fileName).toBe("data.json");
+  });
+});
+
+describe("json adapter — rendering", () => {
+  const source = normalizeFileSource({ kind: "text", text: "", name: "data.json" });
+
+  it("renders a named tree", async () => {
+    const doc = await parse('{"items":[1,2]}');
+    render(<jsonModule.Renderer document={doc} source={source} />);
+    expect(screen.getByRole("tree", { name: "JSON structure" })).toBeInTheDocument();
+  });
+
+  it("falls back to the raw text for a scalar document", async () => {
+    const doc = await parse("42");
+    const { container } = render(<jsonModule.Renderer document={doc} source={source} />);
+    expect(screen.queryByRole("tree")).not.toBeInTheDocument();
+    expect(container.querySelector("pre")).toHaveTextContent("42");
+  });
+});

package/src/adapters/json/json-adapter.tsx

@@ -0,0 +1,141 @@
+"use client";
+
+/**
+ * JSON adapter — parses to a real value and renders it as a collapsible tree.
+ *
+ * Why a tree and not a pretty-printed `<pre>`: the whole reason to open a JSON
+ * file in a viewer rather than an editor is to find something in it. A tree
+ * collapses the parts you are not reading, and `@elabs-ai/components-ui`'s
+ * `Tree` already ships the keyboard model, roving tabindex and virtualization,
+ * so this adapter contributes the MAPPING and nothing else.
+ *
+ * Invalid JSON is a terminal `parse-failed`, reported with the position the
+ * engine gave us — not a silent fall-through to plain text, which would hide
+ * the one fact the user needs.
+ */
+
+import { cn, Tree, type TreeNode, useLocale } from "@elabs-ai/components-ui";
+import type { ResolvedFileSource } from "@elabs-ai/components-ui";
+
+import { ViewerError, toViewerError } from "../../core/errors";
+import type {
+  AdapterDocument,
+  AdapterLoadContext,
+  AdapterModule,
+  AdapterRendererProps,
+  FileAdapter,
+} from "../../core/types";
+import { jsonManifest } from "./json-manifest";
+
+export interface JsonDocument extends AdapterDocument {
+  kind: "json";
+  /** The parsed value. `unknown` on purpose — it is whatever the file held. */
+  value: unknown;
+  /** The original source text, for the raw view and for copy. */
+  text: string;
+}
+
+/** A one-line preview of a value, used as the collapsed label for a container. */
+function summarize(value: unknown): string {
+  if (Array.isArray(value)) return `[${String(value.length)}]`;
+  if (value !== null && typeof value === "object") {
+    return `{${String(Object.keys(value).length)}}`;
+  }
+  if (typeof value === "string") return `"${value}"`;
+  return String(value);
+}
+
+/** True for a value that has children worth expanding. */
+function isContainer(value: unknown): value is Record<string, unknown> | unknown[] {
+  return value !== null && typeof value === "object";
+}
+
+/**
+ * Map a parsed value onto `Tree` nodes.
+ *
+ * Ids are the JSON path (`$.items[2].name`), which makes them stable across
+ * re-renders and directly usable as a "reveal this node" target later.
+ */
+export function toTreeNodes(value: unknown, path = "$"): TreeNode[] {
+  if (!isContainer(value)) return [];
+
+  const entries: [string, unknown][] = Array.isArray(value)
+    ? value.map((item, index) => [String(index), item])
+    : Object.entries(value);
+
+  return entries.map(([key, child]) => {
+    const childPath = Array.isArray(value) ? `${path}[${key}]` : `${path}.${key}`;
+    const container = isContainer(child);
+    return {
+      id: childPath,
+      label: (
+        <span className="font-mono">
+          <span className="text-foreground">{key}</span>
+          <span className="text-muted-foreground">: </span>
+          <span className={container ? "text-muted-foreground" : "text-info-text"}>
+            {summarize(child)}
+          </span>
+        </span>
+      ),
+      children: container ? toTreeNodes(child, childPath) : undefined,
+    };
+  });
+}
+
+class JsonAdapter implements FileAdapter {
+  async load(source: ResolvedFileSource, context: AdapterLoadContext): Promise<JsonDocument> {
+    let text: string;
+    try {
+      text = await source.text(context.signal);
+    } catch (error) {
+      throw toViewerError(error, "read-failed", { fileName: source.name });
+    }
+
+    try {
+      return { kind: "json", value: JSON.parse(text) as unknown, text };
+    } catch (error) {
+      throw new ViewerError(
+        "parse-failed",
+        error instanceof Error ? error.message : "Invalid JSON.",
+        { fileName: source.name, cause: error },
+      );
+    }
+  }
+}
+
+function JsonRenderer({ document: doc, className }: AdapterRendererProps) {
+  const json = doc as JsonDocument;
+  const { t } = useLocale();
+  const nodes = toTreeNodes(json.value);
+
+  // A scalar top level (`42`, `"hello"`, `null`) has no children to expand —
+  // a tree of nothing would read as an empty state, which it is not.
+  if (nodes.length === 0) {
+    return (
+      <pre className={cn("text-code font-mono break-words whitespace-pre-wrap", className)}>
+        {json.text}
+      </pre>
+    );
+  }
+
+  return (
+    <Tree
+      aria-label={t("viewer.json.tree")}
+      nodes={nodes}
+      // The top level open, everything below collapsed: enough to see the shape
+      // without paying to build a DOM for a deeply nested document.
+      defaultExpandedIds={nodes.map((node) => node.id)}
+      selectionMode="none"
+      virtualize
+      className={cn("h-full overflow-auto", className)}
+    />
+  );
+}
+
+const adapterModule: AdapterModule = {
+  manifest: jsonManifest,
+  create: () => new JsonAdapter(),
+  Renderer: JsonRenderer,
+};
+
+export default adapterModule;

package/src/adapters/json/json-manifest.ts

@@ -0,0 +1,11 @@
+import type { AdapterManifest } from "../../core/types";
+import { PROTOCOL_VERSION } from "../../core/types";
+
+/** Eager, data-only (see `image-manifest.ts`). */
+export const jsonManifest: AdapterManifest = {
+  id: "json",
+  protocol: PROTOCOL_VERSION,
+  extensions: ["json"],
+  mediaTypes: ["application/json"],
+  capabilities: { text: true, search: true },
+};

package/src/adapters/markdown/markdown-adapter.test.tsx

@@ -0,0 +1,228 @@
+import { normalizeFileSource } from "@elabs-ai/components-ui";
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import type { ResolvedHighlight } from "../../core/highlight";
+import markdownModule, {
+  MARKDOWN_CHARACTER_LIMIT,
+  type MarkdownDocument,
+} from "./markdown-adapter";
+
+const SAMPLE = [
+  "# Quarterly review",
+  "",
+  "Revenue grew **18%** against a flat market.",
+  "",
+  "- EMEA beat plan",
+  "- APAC held flat",
+  "",
+  "See the [full report](https://example.com/report) and `pnpm build`.",
+  "",
+  "```ts",
+  "const total = 18;",
+  "```",
+].join("\n");
+
+function source(text: string, name = "README.md") {
+  return normalizeFileSource({ kind: "text", text, name, mediaType: "text/markdown" });
+}
+
+const load = (text = SAMPLE) =>
+  markdownModule.create().load(source(text), {}) as Promise<MarkdownDocument>;
+
+describe("markdown adapter — loading", () => {
+  it("keeps the source as-is; the parse belongs to the renderer", async () => {
+    const doc = await load();
+    expect(doc.kind).toBe("markdown");
+    expect(doc.text).toBe(SAMPLE);
+    expect(doc.totalCharacters).toBeUndefined();
+  });
+
+  it("truncates a file too large to parse, and says how much it kept", async () => {
+    const doc = await load("a\n".repeat(600_000));
+    expect(doc.text).toHaveLength(MARKDOWN_CHARACTER_LIMIT);
+    expect(doc.totalCharacters).toBe(1_200_000);
+  });
+
+  it("reports an unreadable source as read-failed, not parse-failed", async () => {
+    const failing = {
+      ...source(""),
+      text: () => Promise.reject(new Error("network down")),
+    };
+    await expect(markdownModule.create().load(failing, {})).rejects.toMatchObject({
+      code: "read-failed",
+    });
+  });
+});
+
+describe("markdown adapter — rendering", () => {
+  const Renderer = markdownModule.Renderer;
+
+  const draw = async (text = SAMPLE) => {
+    const doc = await load(text);
+    return render(<Renderer document={doc} source={source(text)} />);
+  };
+
+  it("renders a document, not a wall of source", async () => {
+    await draw();
+    // A real heading element — this is the ASSET-2 defect in reverse: markdown
+    // shown as highlighted source instead of as the document it is.
+    expect(screen.getByRole("heading", { name: "Quarterly review" })).toBeInTheDocument();
+    expect(screen.getAllByRole("listitem").map((item) => item.textContent)).toEqual([
+      "EMEA beat plan",
+      "APAC held flat",
+    ]);
+  });
+
+  it("offsets the document's headings below the host page's own", async () => {
+    // A viewed README's `#` is the top of THAT document, not of the page. The
+    // default puts it at h2, so a host page keeping its own h1 does not end up
+    // with two of them in a screen reader's flat heading list.
+    await draw();
+    expect(screen.getByRole("heading", { name: "Quarterly review", level: 2 })).toBeInTheDocument();
+  });
+
+  it("honours a host that owns no h1 of its own", async () => {
+    const doc = await load();
+    render(<Renderer document={doc} source={source(SAMPLE)} baseHeadingLevel={1} />);
+    expect(screen.getByRole("heading", { name: "Quarterly review", level: 1 })).toBeInTheDocument();
+  });
+
+  it("never renders past h6, whatever the offset", async () => {
+    const doc = await load("###### Deep\n");
+    render(<Renderer document={doc} source={source("")} baseHeadingLevel={6} />);
+    // 6 + 6 - 1 = 11, clamped: an `h11` is not an element.
+    expect(screen.getByRole("heading", { name: "Deep", level: 6 })).toBeInTheDocument();
+  });
+
+  it("renders links as links", async () => {
+    await draw();
+    expect(screen.getByRole("link", { name: "full report" })).toHaveAttribute(
+      "href",
+      "https://example.com/report",
+    );
+  });
+
+  it("keeps fenced code as code", async () => {
+    const { container } = await draw();
+    expect(container.querySelector("pre")).toHaveTextContent("const total = 18;");
+  });
+
+  it("announces truncation as a status, not an error", async () => {
+    const doc: MarkdownDocument = {
+      kind: "markdown",
+      text: "# Partial",
+      totalCharacters: 1_200_000,
+    };
+    render(<Renderer document={doc} source={source("")} />);
+    expect(screen.getByRole("status")).toHaveTextContent(/Showing the first/);
+    expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+  });
+
+  it("shows a whitespace-only file as an empty state, not a blank pane", async () => {
+    await draw("   \n\n");
+    expect(screen.getByText("This file is empty")).toBeInTheDocument();
+  });
+});
+
+describe("markdown renderer — highlighting", () => {
+  const Renderer = markdownModule.Renderer;
+
+  const cite = (id: string, range: [number, number], active = false): ResolvedHighlight => ({
+    id,
+    source: "citation",
+    status: "resolved",
+    address: { kind: "range", start: range[0], end: range[1] },
+    active,
+    range,
+  });
+
+  /** Offsets of a passage in the markdown SOURCE, which is the address space. */
+  const rangeOf = (passage: string, text = SAMPLE): [number, number] => {
+    const start = text.indexOf(passage);
+    expect(start).toBeGreaterThanOrEqual(0);
+    return [start, start + passage.length];
+  };
+
+  const drawWith = async (
+    highlights: ResolvedHighlight[],
+    activeHighlightId?: string,
+    text = SAMPLE,
+  ) => {
+    const doc = await load(text);
+    return render(
+      <Renderer
+        document={doc}
+        source={source(text)}
+        highlights={highlights}
+        activeHighlightId={activeHighlightId}
+      />,
+    );
+  };
+
+  const plates = (container: HTMLElement) =>
+    Array.from(container.querySelectorAll('[data-slot="highlight-block"]'));
+
+  it("declares the address kinds it can actually honour", () => {
+    expect(markdownModule.manifest.capabilities?.highlight).toEqual(["quote", "range"]);
+  });
+
+  it("plates the paragraph a passage falls in, and only that one", async () => {
+    const { container } = await drawWith([cite("a", rangeOf("against a flat"))]);
+    expect(plates(container).map((el) => el.textContent)).toEqual([
+      "Revenue grew 18% against a flat market.",
+    ]);
+  });
+
+  it("plates the heading when the passage is the heading", async () => {
+    const { container } = await drawWith([cite("a", rangeOf("Quarterly review"))]);
+    const [plate] = plates(container);
+    expect(plate?.tagName).toBe("H2");
+  });
+
+  it("plates one list item, not the whole list", async () => {
+    const { container } = await drawWith([cite("a", rangeOf("APAC held"))]);
+    expect(plates(container).map((el) => el.textContent)).toEqual(["APAC held flat"]);
+  });
+
+  it("plates a fenced block on its `pre`, so the code keeps its own ground", async () => {
+    const { container } = await drawWith([cite("a", rangeOf("const total"))]);
+    const [plate] = plates(container);
+    expect(plate?.tagName).toBe("PRE");
+  });
+
+  it("plates every block a passage spans", async () => {
+    const start = SAMPLE.indexOf("Revenue");
+    const end = SAMPLE.indexOf("APAC held flat") + "APAC held flat".length;
+    const { container } = await drawWith([cite("a", [start, end])]);
+    // The paragraph plus both list items — a citation that runs across a break
+    // is still one passage, so every block it touches says so.
+    expect(plates(container)).toHaveLength(3);
+  });
+
+  it("does not plate the block after a passage that ends where it starts", async () => {
+    // Half-open on both sides: the heading's span ends exactly where the blank
+    // line before the paragraph begins, and the paragraph must stay unplated.
+    const { container } = await drawWith([cite("a", rangeOf("# Quarterly review"))]);
+    expect(plates(container)).toHaveLength(1);
+  });
+
+  it("flags the current passage for assistive tech, not by colour alone", async () => {
+    const { container } = await drawWith([cite("a", rangeOf("against a flat"), true)], "a");
+    const active = container.querySelector('[data-slot="highlight-block"][data-active]');
+    expect(active?.getAttribute("aria-current")).toBe("true");
+  });
+
+  it("plates a loose list item once, not once per nested paragraph", async () => {
+    // A loose list renders as `li > p`; both nodes' source spans contain the
+    // mark, so without the nesting guard the reader sees two stacked fills.
+    const text = "- One\n\n- Two\n";
+    const { container } = await drawWith([cite("a", rangeOf("One", text))], undefined, text);
+    expect(plates(container)).toHaveLength(1);
+  });
+
+  it("draws nothing when no highlight is passed", async () => {
+    const { container } = await drawWith([]);
+    expect(plates(container)).toHaveLength(0);
+  });
+});