@elabs-ai/components-viewer 4.0.0

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

@@ -0,0 +1,169 @@
+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 csvModule, { CSV_ROW_LIMIT, type CsvDocument } from "./csv-adapter";
+
+const parse = (text: string, name = "rows.csv") =>
+  csvModule
+    .create()
+    .load(normalizeFileSource({ kind: "text", text, name }), {}) as Promise<CsvDocument>;
+
+describe("csv adapter — parsing", () => {
+  it("keeps a quoted comma in one cell (the bug the split-on-comma parser had)", async () => {
+    const doc = await parse('name,address\nAda,"12 High St, London"\n');
+    expect(doc.columns).toEqual(["name", "address"]);
+    expect(doc.rows).toEqual([["Ada", "12 High St, London"]]);
+  });
+
+  it("handles escaped quotes and embedded newlines", async () => {
+    const doc = await parse('quote,note\n"She said ""hi""","line one\nline two"\n');
+    expect(doc.rows[0]).toEqual(['She said "hi"', "line one\nline two"]);
+  });
+
+  it("detects a semicolon delimiter rather than trusting the extension", async () => {
+    const doc = await parse("a;b\n1;2\n");
+    expect(doc.columns).toEqual(["a", "b"]);
+    expect(doc.rows).toEqual([["1", "2"]]);
+  });
+
+  it("reads a tab-separated file", async () => {
+    const doc = await parse("a\tb\n1\t2\n", "rows.tsv");
+    expect(doc.columns).toEqual(["a", "b"]);
+    expect(doc.rows).toEqual([["1", "2"]]);
+  });
+
+  it("reports truncation instead of silently dropping rows", async () => {
+    const rows = Array.from({ length: CSV_ROW_LIMIT + 10 }, (_, i) => `${String(i)},x`).join("\n");
+    const doc = await parse(`a,b\n${rows}\n`);
+    expect(doc.rows).toHaveLength(CSV_ROW_LIMIT);
+    expect(doc.totalRows).toBe(CSV_ROW_LIMIT + 10);
+  });
+
+  it("does not claim truncation when the file fits", async () => {
+    const doc = await parse("a,b\n1,2\n");
+    expect(doc.totalRows).toBeUndefined();
+  });
+
+  it("projects the PARSED grid as its text, not the raw file", async () => {
+    // Deliberate change: a citation has to address what the reader sees. The
+    // raw bytes carry quoting, escapes and whatever delimiter the exporter
+    // chose, so an offset into them lands nowhere in the rendered table.
+    const doc = await parse('name,address\nAda,"12 High St, London"\n');
+    expect(doc.text).toBe("name\taddress\nAda\t12 High St, London");
+  });
+
+  it("maps each row back to its place in the projection", async () => {
+    const doc = await parse("a,b\n1,2\n3,4\n");
+    const spans = doc.textIndex?.spans ?? [];
+    expect(spans.map((span) => [doc.text?.slice(span.start, span.end), span.ref])).toEqual([
+      ["a\tb", { sheet: 0, row: -1 }],
+      ["1\t2", { sheet: 0, row: 0 }],
+      ["3\t4", { sheet: 0, row: 1 }],
+    ]);
+  });
+});
+
+describe("csv adapter — rendering", () => {
+  it("renders a real table with the file's own headers", async () => {
+    const doc = await parse('name,address\nAda,"12 High St, London"\n');
+    const source = normalizeFileSource({ kind: "text", text: "", name: "rows.csv" });
+    render(<csvModule.Renderer document={doc} source={source} />);
+
+    expect(screen.getByRole("columnheader", { name: "name" })).toBeInTheDocument();
+    // One cell, not two — proof the quoted comma survived to the DOM.
+    expect(screen.getByRole("cell", { name: "12 High St, London" })).toBeInTheDocument();
+  });
+
+  it("gives the grid an accessible summary", async () => {
+    const doc = await parse("a,b\n1,2\n");
+    const source = normalizeFileSource({ kind: "text", text: "", name: "rows.csv" });
+    render(<csvModule.Renderer document={doc} source={source} />);
+    expect(screen.getByRole("table", { name: /1 rows, 2 columns/ })).toBeInTheDocument();
+  });
+
+  it("announces truncation as a status, not an error", async () => {
+    const rows = Array.from({ length: CSV_ROW_LIMIT + 1 }, () => "x,y").join("\n");
+    const doc = await parse(`a,b\n${rows}\n`);
+    const source = normalizeFileSource({ kind: "text", text: "", name: "rows.csv" });
+    render(<csvModule.Renderer document={doc} source={source} />);
+
+    expect(screen.getByRole("status")).toHaveTextContent(/Showing the first/);
+    expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+    // Parsing and rendering CSV_ROW_LIMIT+1 rows is genuinely slow on a
+    // 2-core CI runner — 7232ms observed against the 5000ms default. The cost
+    // is the fixture, not a hang, so raise the margin rather than shrink the
+    // fixture (the limit is what this test exists to cross).
+  }, 15_000);
+});
+
+describe("csv renderer — highlighting", () => {
+  const FILE = "region,revenue\nEMEA,4.2M\nAPAC,3.1M\n";
+
+  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 document's own projection. */
+  const rangeOf = (doc: CsvDocument, passage: string): [number, number] => {
+    const start = doc.text?.indexOf(passage) ?? -1;
+    expect(start).toBeGreaterThanOrEqual(0);
+    return [start, start + passage.length];
+  };
+
+  const renderWith = async (
+    pick: (doc: CsvDocument) => ResolvedHighlight[],
+    activeHighlightId?: string,
+  ) => {
+    const doc = await parse(FILE);
+    const source = normalizeFileSource({ kind: "text", text: "", name: "rows.csv" });
+    return render(
+      <csvModule.Renderer
+        document={doc}
+        source={source}
+        highlights={pick(doc)}
+        activeHighlightId={activeHighlightId}
+      />,
+    );
+  };
+
+  it("declares the address kinds it can actually honour", () => {
+    expect(csvModule.manifest.capabilities?.highlight).toEqual(["quote", "range"]);
+  });
+
+  it("marks one cell, not the whole row it shares a span with", async () => {
+    const { container } = await renderWith((doc) => [cite("a", rangeOf(doc, "4.2M"))]);
+    const marks = Array.from(container.querySelectorAll("mark"));
+    expect(marks).toHaveLength(1);
+    expect(marks[0]?.closest("td")?.textContent).toBe("4.2M");
+  });
+
+  it("marks a header cell too — the header is part of the projection", async () => {
+    const { container } = await renderWith((doc) => [cite("a", rangeOf(doc, "revenue"))]);
+    expect(container.querySelector("mark")?.closest("th")?.textContent).toBe("revenue");
+  });
+
+  it("marks in both cells when a citation spans the separator", async () => {
+    const { container } = await renderWith((doc) => [cite("a", rangeOf(doc, "EMEA\t4.2M"))]);
+    const marks = Array.from(container.querySelectorAll("mark"));
+    expect(marks.map((mark) => mark.textContent)).toEqual(["EMEA", "4.2M"]);
+  });
+
+  it("flags the current passage for assistive tech, not by colour alone", async () => {
+    const { container } = await renderWith((doc) => [cite("a", rangeOf(doc, "3.1M"), true)], "a");
+    const active = container.querySelector('mark[data-active][data-slot="match-highlight-mark"]');
+    expect(active?.getAttribute("aria-current")).toBe("true");
+    expect(active?.textContent).toBe("3.1M");
+  });
+
+  it("draws nothing when no highlight is passed", async () => {
+    const { container } = await renderWith(() => []);
+    expect(container.querySelectorAll("mark")).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,146 @@
+"use client";
+
+/**
+ * CSV / TSV adapter — a real parser and a real table.
+ *
+ * Two things this fixes at once:
+ *
+ * - **Correctness.** The repo's previous CSV "parser" was `line.split(",")`
+ *   (`packages/ai/src/asset-preview.tsx:69`), which mangles every quoted comma —
+ *   i.e. every address, every price list, every free-text column. Papa Parse
+ *   handles quoting, escapes, embedded newlines and delimiter detection.
+ * - **Theming.** anyview's CSV adapter emits an HTML string with `#ddd` and
+ *   `#f5f5f5` baked in (`CsvAdapter.ts:184`). This one emits ROWS and hands them
+ *   to `@elabs-ai/components-ui`'s `Table`, so the grid is tokened and
+ *   re-themes with everything else.
+ *
+ * `papaparse` is an OPTIONAL peer, reached only through the dynamic import
+ * below. A consumer who never opens a spreadsheet never installs it, and one who
+ * forgot gets a "install papaparse" message rather than a resolution stack trace
+ * (`isModuleNotFound` in `core/errors.ts`).
+ */
+
+import type { ResolvedFileSource } from "@elabs-ai/components-ui";
+import { useMemo } from "react";
+
+import { gridToText, type GridRef } from "../../components/grid-text";
+import { SheetTable } from "../../components/sheet-table";
+
+import { ViewerError, toViewerError } from "../../core/errors";
+import { toMarkRanges } from "../../core/highlight-marks";
+import type { TextIndex } from "../../core/text-index";
+import type {
+  AdapterDocument,
+  AdapterLoadContext,
+  AdapterModule,
+  AdapterRendererProps,
+  FileAdapter,
+} from "../../core/types";
+import { csvManifest } from "./csv-manifest";
+
+/**
+ * Rows rendered before truncation. A preview pane is for looking, not for
+ * analysis — past this, reach for `@elabs-ai/components-data`'s
+ * `DataTable`, which virtualizes.
+ */
+export const CSV_ROW_LIMIT = 5_000;
+
+export interface CsvDocument extends AdapterDocument {
+  kind: "csv";
+  /** Header cells. Empty when the file had no usable first row. */
+  columns: string[];
+  /** Body rows, already capped at {@link CSV_ROW_LIMIT}. */
+  rows: string[][];
+  /** Total body rows in the file, when more than what is shown. */
+  totalRows?: number;
+  /** Which row each stretch of `text` came from. */
+  textIndex?: TextIndex<GridRef>;
+}
+
+class CsvAdapter implements FileAdapter {
+  async load(source: ResolvedFileSource, context: AdapterLoadContext): Promise<CsvDocument> {
+    let text: string;
+    try {
+      text = await source.text(context.signal);
+    } catch (error) {
+      throw toViewerError(error, "read-failed", { fileName: source.name });
+    }
+
+    // Dynamic: this is the ONLY edge to the optional peer. A static import here
+    // would break every consumer that did not install it (heavy-deps:check).
+    const Papa = await import("papaparse");
+    const parsed = Papa.parse<string[]>(text, {
+      skipEmptyLines: "greedy",
+      // Let Papa detect `,` vs `\t` vs `;` rather than trusting the extension —
+      // a .csv exported by a European locale is very often semicolon-delimited.
+      delimiter: "",
+    });
+
+    // Papa reports recoverable problems as errors while still returning data;
+    // only an empty result with errors is genuinely unreadable.
+    if (parsed.data.length === 0 && parsed.errors.length > 0) {
+      throw new ViewerError(
+        "parse-failed",
+        parsed.errors[0]?.message ?? "Could not parse the file.",
+        {
+          fileName: source.name,
+        },
+      );
+    }
+
+    const [header = [], ...body] = parsed.data;
+    const rows = body.length <= CSV_ROW_LIMIT ? body : body.slice(0, CSV_ROW_LIMIT);
+    // `text` is the PARSED grid, not the raw file (changed in this release).
+    // A citation's offsets have to address what the reader can see: the raw
+    // bytes carry quoting, escapes and a delimiter that may not be a comma, so
+    // an offset into them lands nowhere in particular in the rendered table.
+    const textIndex = gridToText([{ columns: header, rows }]);
+    return {
+      kind: "csv",
+      columns: header,
+      rows,
+      ...(body.length > CSV_ROW_LIMIT ? { totalRows: body.length } : {}),
+      text: textIndex.text,
+      textIndex,
+    };
+  }
+}
+
+function CsvRenderer({
+  document: doc,
+  className,
+  highlights,
+  activeHighlightId,
+}: AdapterRendererProps) {
+  const csv = doc as CsvDocument;
+  const marks = useMemo(
+    () => toMarkRanges(highlights, csv.text?.length ?? 0),
+    [highlights, csv.text],
+  );
+  // One sheet, so a row's start is simply the span whose ref names that row.
+  const rowStart = useMemo(() => {
+    const starts = new Map<number, number>();
+    for (const span of csv.textIndex?.spans ?? []) starts.set(span.ref.row, span.start);
+    return (row: number) => starts.get(row);
+  }, [csv.textIndex]);
+
+  return (
+    <SheetTable
+      columns={csv.columns}
+      rows={csv.rows}
+      totalRows={csv.totalRows}
+      className={className}
+      marks={marks}
+      rowStart={rowStart}
+      activeHighlightId={activeHighlightId}
+    />
+  );
+}
+
+const adapterModule: AdapterModule = {
+  manifest: csvManifest,
+  create: () => new CsvAdapter(),
+  Renderer: CsvRenderer,
+};
+
+export default adapterModule;

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

@@ -0,0 +1,20 @@
+import type { AdapterManifest } from "../../core/types";
+import { PROTOCOL_VERSION } from "../../core/types";
+
+/**
+ * Eager, data-only (see `image-manifest.ts`).
+ *
+ * `requires` names the OPTIONAL peer this adapter dynamically imports. It is
+ * what the "install this to open that" message names when the import cannot
+ * resolve — the registry never installs anything itself.
+ */
+export const csvManifest: AdapterManifest = {
+  id: "csv",
+  protocol: PROTOCOL_VERSION,
+  extensions: ["csv", "tsv"],
+  mediaTypes: ["text/csv", "text/tab-separated-values"],
+  // Addressed against the PARSED grid (`gridToText`), not the raw bytes — see
+  // the adapter. No `rect`: a table cell has no page geometry to point at.
+  capabilities: { text: true, search: true, highlight: ["quote", "range"] },
+  requires: ["papaparse"],
+};

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

@@ -0,0 +1,192 @@
+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 { SAMPLE_DOCX_BASE64 } from "../office-fixture";
+import docxModule, { type DocxDocument } from "./docx-adapter";
+
+const MEDIA_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+
+function fixtureSource(name = "review.docx") {
+  const bytes = Uint8Array.from(atob(SAMPLE_DOCX_BASE64), (char) => char.charCodeAt(0));
+  return normalizeFileSource({
+    kind: "buffer",
+    buffer: bytes.buffer as ArrayBuffer,
+    name,
+    mediaType: MEDIA_TYPE,
+  });
+}
+
+const load = () => docxModule.create().load(fixtureSource(), {}) as Promise<DocxDocument>;
+
+describe("docx adapter — a real Word file through mammoth", () => {
+  it("reads the document's structure, not a wall of text", async () => {
+    const doc = await load();
+    expect(doc.blocks).toContainEqual({
+      type: "heading",
+      level: 1,
+      runs: [{ text: "Quarterly review" }],
+    });
+    expect(doc.blocks).toContainEqual({
+      type: "list",
+      ordered: false,
+      items: [[{ text: "EMEA beat plan" }], [{ text: "APAC held flat" }]],
+    });
+    expect(doc.blocks.some((block) => block.type === "table")).toBe(true);
+  });
+
+  it("keeps Word's emphasis as run styling", async () => {
+    const doc = await load();
+    const paragraph = doc.blocks.find((block) => block.type === "paragraph");
+    expect(paragraph).toEqual({
+      type: "paragraph",
+      runs: [
+        { text: "Revenue grew " },
+        { text: "18%", bold: true },
+        { text: " against a " },
+        { text: "flat", italic: true },
+        { text: " market." },
+      ],
+    });
+  });
+
+  it("exposes a plain-text projection for search and copy", async () => {
+    const doc = await load();
+    expect(doc.text).toContain("Quarterly review");
+    expect(doc.text).toContain("• EMEA beat plan");
+  });
+
+  it("reports a file that is not a Word document as parse-failed, not as a crash", async () => {
+    const source = normalizeFileSource({
+      kind: "text",
+      text: "not a zip",
+      name: "broken.docx",
+      mediaType: MEDIA_TYPE,
+    });
+    await expect(docxModule.create().load(source, {})).rejects.toMatchObject({
+      code: "parse-failed",
+    });
+  });
+});
+
+describe("docx renderer", () => {
+  it("draws the document with real headings, lists and links", async () => {
+    const doc = await load();
+    render(<docxModule.Renderer document={doc} source={fixtureSource()} />);
+
+    // Offset by the default base: Word's "Heading 1" is the top of THAT
+    // document, so it renders at h2 and leaves the host page's h1 alone.
+    expect(screen.getByRole("heading", { level: 2, name: "Quarterly review" })).toBeInTheDocument();
+    expect(screen.getByRole("heading", { level: 3, name: "Regions" })).toBeInTheDocument();
+    expect(screen.getAllByRole("listitem").map((item) => item.textContent)).toEqual([
+      "EMEA beat plan",
+      "APAC held flat",
+    ]);
+    // A real anchor, so it is reachable by keyboard and by a links list.
+    expect(screen.getByRole("link", { name: "Full report" })).toHaveAttribute(
+      "href",
+      "https://example.com/report",
+    );
+  });
+
+  it("puts the document's own top heading where the host asks", async () => {
+    const doc = await load();
+    render(<docxModule.Renderer document={doc} source={fixtureSource()} baseHeadingLevel={1} />);
+    expect(screen.getByRole("heading", { level: 1, name: "Quarterly review" })).toBeInTheDocument();
+  });
+
+  it("renders a Word table as a real table", async () => {
+    const doc = await load();
+    render(<docxModule.Renderer document={doc} source={fixtureSource()} />);
+    expect(screen.getByRole("table")).toBeInTheDocument();
+    expect(screen.getByRole("cell", { name: "4.2M" })).toBeInTheDocument();
+  });
+
+  it("says so when a document has no text, instead of rendering an empty pane", () => {
+    const empty: DocxDocument = { kind: "docx", blocks: [], warnings: [], text: "" };
+    render(<docxModule.Renderer document={empty} source={fixtureSource()} />);
+    expect(screen.getByText("This document has no text")).toBeInTheDocument();
+  });
+});
+
+describe("docx renderer — highlighting", () => {
+  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 document's own projection. */
+  const rangeOf = (doc: DocxDocument, passage: string): [number, number] => {
+    const start = doc.text?.indexOf(passage) ?? -1;
+    expect(start).toBeGreaterThanOrEqual(0);
+    return [start, start + passage.length];
+  };
+
+  const renderWith = async (highlights: ResolvedHighlight[], activeHighlightId?: string) => {
+    const doc = await load();
+    const result = render(
+      <docxModule.Renderer
+        document={doc}
+        source={fixtureSource()}
+        highlights={highlights}
+        activeHighlightId={activeHighlightId}
+      />,
+    );
+    return { doc, ...result };
+  };
+
+  it("declares the address kinds it can actually honour", () => {
+    expect(docxModule.manifest.capabilities?.highlight).toEqual(["quote", "range"]);
+  });
+
+  it("marks a passage inside a paragraph, in the block it came from", async () => {
+    const doc = await load();
+    const { container } = await renderWith([cite("a", rangeOf(doc, "against a"))]);
+    const marks = Array.from(container.querySelectorAll("mark"));
+    expect(marks.map((mark) => mark.textContent).join("")).toBe("against a");
+    // The paragraph still reads whole — marking wraps, it does not replace.
+    expect(container.textContent).toContain("Revenue grew 18% against a flat market.");
+  });
+
+  it("marks across run styling without flattening it", async () => {
+    const doc = await load();
+    const { container } = await renderWith([cite("a", rangeOf(doc, "grew 18% against"))]);
+    const marks = Array.from(container.querySelectorAll("mark"));
+    expect(marks.map((mark) => mark.textContent).join("")).toBe("grew 18% against");
+    // The bold run is still bold underneath the mark.
+    expect(container.querySelector("strong")?.textContent).toBe("18%");
+  });
+
+  it("marks a list item past its bullet, which is drawn by the list, not the text", async () => {
+    const doc = await load();
+    const { container } = await renderWith([cite("a", rangeOf(doc, "EMEA beat"))]);
+    const mark = container.querySelector("mark");
+    expect(mark?.textContent).toBe("EMEA beat");
+    expect(mark?.closest("li")?.textContent).toBe("EMEA beat plan");
+  });
+
+  it("marks one table cell, not the whole row it shares a span with", async () => {
+    const doc = await load();
+    const { container } = await renderWith([cite("a", rangeOf(doc, "4.2M"))]);
+    const marks = Array.from(container.querySelectorAll("mark"));
+    expect(marks).toHaveLength(1);
+    expect(marks[0]?.closest("td")?.textContent).toBe("4.2M");
+  });
+
+  it("flags the current passage for assistive tech, not by colour alone", async () => {
+    const doc = await load();
+    const { container } = await renderWith([cite("a", rangeOf(doc, "flat"), true)], "a");
+    const active = container.querySelector('mark[data-active][data-slot="match-highlight-mark"]');
+    expect(active?.getAttribute("aria-current")).toBe("true");
+  });
+
+  it("draws nothing when no highlight is passed", async () => {
+    const { container } = await renderWith([]);
+    expect(container.querySelectorAll("mark")).toHaveLength(0);
+  });
+});