@elabs-ai/components-viewer 4.0.0

package/src/components/grid-text.ts

@@ -0,0 +1,77 @@
+/**
+ * The one text projection every tabular format is addressed against.
+ *
+ * CSV and XLSX arrive through different parsers and render into the same
+ * `SheetTable`; they should also be *addressable* the same way, or a citation
+ * that resolves in a workbook would miss in the CSV export of the same data.
+ * So the projection is written once here and both adapters call it.
+ *
+ * Shape — a sheet's name (when it has one), then its header row, then its body
+ * rows; cells joined by a tab, rows by a newline, sheets by a blank line:
+ *
+ * ```
+ * Q3
+ * Region\tRevenue
+ * EMEA\t4.2M
+ *
+ * Q4
+ * …
+ * ```
+ *
+ * **Rows, not cells, are the finest ref** — the same trade the Word adapter
+ * makes. A cell-granular index would need a span per cell and a separator per
+ * level; a row-granular one needs neither, because a cell's offset is the sum of
+ * the cells before it ({@link chunkOffset}). The granularity of the REF is the
+ * row; the granularity of the MARK is still the character.
+ */
+
+import { createTextIndexBuilder, type TextIndex } from "../core/text-index";
+
+/** Between two cells of the same row. */
+export const GRID_CELL_SEPARATOR = "\t";
+/** Between two rows of the same sheet. */
+export const GRID_ROW_SEPARATOR = "\n";
+/** Between two sheets of the same workbook. */
+export const GRID_SHEET_SEPARATOR = "\n\n";
+
+/** The `row` of a sheet's own name line. */
+export const GRID_NAME_ROW = -2;
+/** The `row` of a sheet's header row. */
+export const GRID_HEAD_ROW = -1;
+
+/** Where a stretch of the projection came from in the grid. */
+export interface GridRef {
+  /** Index into the sheets. `0` for a single-sheet format like CSV. */
+  sheet: number;
+  /** Body row index, or {@link GRID_HEAD_ROW} / {@link GRID_NAME_ROW}. */
+  row: number;
+}
+
+/** What {@link gridToText} needs from a sheet — the shape both adapters already hold. */
+export interface GridSheetInput {
+  /** The tab's name. Absent for a single-sheet format, which has no tab. */
+  name?: string;
+  columns: readonly string[];
+  rows: readonly (readonly string[])[];
+}
+
+/** Project a workbook (or a one-sheet CSV) to text, with the map back to it. */
+export function gridToText(sheets: readonly GridSheetInput[]): TextIndex<GridRef> {
+  const builder = createTextIndexBuilder<GridRef>({ separator: GRID_ROW_SEPARATOR });
+  sheets.forEach((sheet, index) => {
+    // The blank line goes before whatever this sheet's FIRST line turns out to
+    // be — its name, or its header when it has no name.
+    let separator = index === 0 ? undefined : GRID_SHEET_SEPARATOR;
+    const push = (chunk: string, row: number) => {
+      builder.push(chunk, { sheet: index, row }, separator);
+      if (chunk.length > 0) separator = undefined;
+    };
+
+    if (sheet.name) push(sheet.name, GRID_NAME_ROW);
+    push(sheet.columns.join(GRID_CELL_SEPARATOR), GRID_HEAD_ROW);
+    sheet.rows.forEach((row, rowIndex) => {
+      push(row.join(GRID_CELL_SEPARATOR), rowIndex);
+    });
+  });
+  return builder.build();
+}

package/src/components/marked-text.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+/**
+ * One slice of text, with whatever marks land in it.
+ *
+ * The last step of the highlight funnel, and the same three lines in every
+ * adapter that draws its text in pieces — a Word run, a spreadsheet cell, a
+ * slide's bullet. Each of them holds document offsets for its own slice and
+ * needs the ranges rebased before a `<mark>` layer can paint them, so the
+ * rebase-then-paint pair is named once here rather than copied a fourth time
+ * (`.claude/rules/design-first.md` — patterns over instances).
+ *
+ * `start === undefined` means "this slice is not in the projection" (an adapter
+ * with no index, a cell past the truncation bound), which renders as plain text
+ * rather than as an error: a document that cannot be addressed is still a
+ * document that can be read.
+ */
+
+import { MatchHighlight } from "@elabs-ai/components-ui";
+
+import { localizeRanges, type MarkRanges } from "../core/highlight-marks";
+
+export interface MarkedTextProps {
+  text: string;
+  /** Marks in PROJECTION offsets — rebased here, not by the caller. */
+  marks: MarkRanges | undefined;
+  /** Where this slice begins in the projection. */
+  start: number | undefined;
+}
+
+export function MarkedText({ text, marks, start }: MarkedTextProps) {
+  const local =
+    !marks || start === undefined ? undefined : localizeRanges(marks, start, start + text.length);
+  if (!local || local.ranges.length === 0) return <>{text}</>;
+  return <MatchHighlight text={text} ranges={local.ranges} activeIndex={local.activeIndex} />;
+}

package/src/components/sheet-table.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+/**
+ * The one grid every tabular format renders into.
+ *
+ * CSV and XLSX arrive through completely different parsers and end up wanting
+ * exactly the same thing: a header row, body rows, a truncation notice and an
+ * `sr-only` caption. That is a PATTERN, not a coincidence, so it is named once
+ * here rather than copied a second time (`.claude/rules/design-first.md` —
+ * patterns over instances).
+ *
+ * It stays deliberately dumb: no sorting, no filtering, no virtualization. A
+ * preview pane is for looking; past a few thousand rows the right component is
+ * `DataTable` in `@elabs-ai/components-data`, which virtualizes.
+ */
+
+import {
+  cn,
+  Table,
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+  useLocale,
+} from "@elabs-ai/components-ui";
+import { useRef } from "react";
+
+import { type MarkRanges } from "../core/highlight-marks";
+import { chunkOffset } from "../core/text-index";
+import { useScrollActiveHighlightIntoView } from "../core/use-highlight-scroll";
+import { GRID_CELL_SEPARATOR, GRID_HEAD_ROW } from "./grid-text";
+import { MarkedText } from "./marked-text";
+
+export interface SheetTableProps {
+  /** Header cells. May be empty — the grid still renders its body. */
+  columns: string[];
+  /** Body rows, already capped by the caller. */
+  rows: string[][];
+  /** Total body rows in the file, when more exist than `rows` holds. */
+  totalRows?: number;
+  className?: string;
+  /** Marks to paint, in projection offsets. */
+  marks?: MarkRanges;
+  /**
+   * Where a row's first cell begins in the projection — {@link GRID_HEAD_ROW}
+   * for the header. A function rather than an array so a workbook can answer
+   * for the sheet being drawn without slicing an index per tab.
+   */
+  rowStart?: (row: number) => number | undefined;
+  /** Scrolls the current mark into this grid's own viewport when it changes. */
+  activeHighlightId?: string | null;
+}
+
+export function SheetTable({
+  columns,
+  rows,
+  totalRows,
+  className,
+  marks,
+  rowStart,
+  activeHighlightId,
+}: SheetTableProps) {
+  const { t, formatNumber } = useLocale();
+  const viewport = useRef<HTMLDivElement>(null);
+
+  useScrollActiveHighlightIntoView(viewport, activeHighlightId);
+
+  return (
+    <div className={cn("flex h-full min-h-0 flex-col gap-2", className)}>
+      {totalRows !== undefined && (
+        // A status, not an error: the file is fine, we are simply showing part
+        // of it (loading-states.md — a capability bound is news, not an alarm).
+        <p role="status" className="text-meta text-muted-foreground shrink-0">
+          {t("viewer.table.truncated", { count: formatNumber(rows.length) })}
+        </p>
+      )}
+      {/* The grid keeps its OWN viewport, unlike the flowing formats: a workbook
+          puts a sheet-tab bar above it that must not scroll away with the rows.
+          A table cell is not focusable, so a scrollable region wrapping one is
+          unreachable from a keyboard (WCAG 2.1.1) — `tabIndex={0}` makes it a
+          real stop that arrow keys and Page Up/Down drive. `group`, not
+          `region`, so a sheet does not mint a second landmark inside the
+          viewer's content region. */}
+      <div
+        ref={viewport}
+        tabIndex={0}
+        role="group"
+        aria-label={t("viewer.content")}
+        className="focus-visible:ring-ring min-h-0 flex-1 overflow-auto focus-visible:outline-none focus-visible:ring-2"
+      >
+        <Table>
+          <TableCaption className="sr-only">
+            {t("viewer.table.caption", {
+              rows: formatNumber(totalRows ?? rows.length),
+              columns: formatNumber(columns.length),
+            })}
+          </TableCaption>
+          <TableHeader>
+            <TableRow>
+              {columns.map((column, index) => (
+                // The file's own header text is the only identity a column has;
+                // an empty one still needs a cell so the grid stays aligned.
+                <TableHead key={`${column}-${String(index)}`} scope="col">
+                  <MarkedText
+                    text={column}
+                    marks={marks}
+                    start={chunkOffset(
+                      columns,
+                      index,
+                      rowStart?.(GRID_HEAD_ROW),
+                      GRID_CELL_SEPARATOR,
+                    )}
+                  />
+                </TableHead>
+              ))}
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {rows.map((row, rowIndex) => {
+              const start = rowStart?.(rowIndex);
+              return (
+                <TableRow key={rowIndex}>
+                  {columns.map((_, columnIndex) => (
+                    <TableCell key={columnIndex} className="whitespace-pre-wrap">
+                      <MarkedText
+                        text={row[columnIndex] ?? ""}
+                        marks={marks}
+                        start={chunkOffset(row, columnIndex, start, GRID_CELL_SEPARATOR)}
+                      />
+                    </TableCell>
+                  ))}
+                </TableRow>
+              );
+            })}
+          </TableBody>
+        </Table>
+      </div>
+    </div>
+  );
+}

package/src/core/errors.ts

@@ -0,0 +1,120 @@
+/**
+ * Typed failures, so the UI can decide what to SHOW without string-matching a
+ * message.
+ *
+ * The `message` on these errors is developer-facing — it goes to the console and
+ * to bug reports. Everything the user reads is looked up from {@link ViewerErrorCode}
+ * through `t()` (ADR 0017), which is why the code, not the prose, is the contract.
+ */
+
+/** Why a file could not be shown. */
+export type ViewerErrorCode =
+  /** No registered adapter claims this file. */
+  | "unsupported-format"
+  /** An adapter was built against a different registry protocol. */
+  | "protocol-mismatch"
+  /** The adapter exists but its optional peer dependency is not installed. */
+  | "parser-missing"
+  /** The bytes could not be obtained (network, permissions, a revoked blob). */
+  | "read-failed"
+  /** The bytes arrived but the parser rejected them. */
+  | "parse-failed"
+  /** The load was cancelled — a new source, or an unmounted view. */
+  | "aborted";
+
+export interface ViewerErrorOptions extends ErrorOptions {
+  /** The file this is about, for the developer-facing message. */
+  fileName?: string;
+  /** For `parser-missing`: the packages a consumer has to install. */
+  packages?: string[];
+}
+
+/** A failure a `FileViewer` can render, carrying a machine-readable {@link ViewerErrorCode}. */
+export class ViewerError extends Error {
+  readonly code: ViewerErrorCode;
+  readonly fileName?: string;
+  readonly packages?: string[];
+
+  constructor(code: ViewerErrorCode, message: string, options: ViewerErrorOptions = {}) {
+    super(message, { cause: options.cause });
+    this.name = "ViewerError";
+    this.code = code;
+    this.fileName = options.fileName;
+    this.packages = options.packages;
+  }
+}
+
+/** True for a {@link ViewerError}, without relying on `instanceof` across bundles. */
+export function isViewerError(value: unknown): value is ViewerError {
+  return value instanceof ViewerError || (value instanceof Error && value.name === "ViewerError");
+}
+
+/** True when the failure is a cancellation rather than something to report. */
+export function isAbort(value: unknown): boolean {
+  if (isViewerError(value)) return value.code === "aborted";
+  return value instanceof Error && (value.name === "AbortError" || value.name === "TimeoutError");
+}
+
+/**
+ * Wrap an unknown throw as a {@link ViewerError}, preserving an existing one and
+ * mapping an abort to the `aborted` code so callers do not report cancellations
+ * as failures.
+ */
+export function toViewerError(
+  value: unknown,
+  fallbackCode: ViewerErrorCode,
+  options: ViewerErrorOptions = {},
+): ViewerError {
+  if (isViewerError(value)) return value;
+  if (isAbort(value)) {
+    return new ViewerError("aborted", "The file load was cancelled.", { ...options, cause: value });
+  }
+  const message = value instanceof Error ? value.message : String(value);
+  return new ViewerError(fallbackCode, message, { ...options, cause: value });
+}
+
+/**
+ * A dynamic `import()` of an OPTIONAL peer that is not installed.
+ *
+ * Bundlers and Node report this differently (`ERR_MODULE_NOT_FOUND`,
+ * `Cannot find module`, `Failed to resolve module specifier`, Vite's
+ * `Failed to fetch dynamically imported module`), so match on the shapes rather
+ * than one runtime's wording. A false positive here is cheap — the user is told
+ * to install a package instead of seeing a raw parse error — and a false
+ * negative is the anyview failure mode this exists to avoid: an unhelpful
+ * module-resolution stack trace where a "install papaparse to open CSV files"
+ * message belongs.
+ */
+export function isModuleNotFound(value: unknown): boolean {
+  if (!(value instanceof Error)) return false;
+  if ("code" in value && value.code === "ERR_MODULE_NOT_FOUND") return true;
+  return /cannot find module|failed to resolve|dynamically imported module|module not found/i.test(
+    value.message,
+  );
+}
+
+/**
+ * The `parser-missing` error, worded the same wherever the peer turns out to be
+ * absent.
+ *
+ * There are TWO such places, which is why this is a function and not a literal
+ * at one call site. The registry catches it when the adapter MODULE cannot be
+ * fetched; `FileViewerProvider` catches it when the module loaded fine and the
+ * adapter's own `await import("mammoth")` — inside `load()`, where every parser
+ * engine is actually reached — rejects. Without the second, a consumer who
+ * skipped an optional peer was told their file was damaged and offered a retry
+ * that could never work.
+ */
+export function parserMissingError(
+  adapterId: string,
+  packages: string[],
+  options: ViewerErrorOptions = {},
+): ViewerError {
+  return new ViewerError(
+    "parser-missing",
+    packages.length > 0
+      ? `The "${adapterId}" adapter needs ${packages.join(", ")}, which is not installed.`
+      : `The "${adapterId}" adapter could not be loaded.`,
+    { ...options, packages },
+  );
+}

package/src/core/highlight-marks.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+
+import type { ResolvedHighlight } from "./highlight";
+import { localizeRanges, toMarkRanges } from "./highlight-marks";
+
+const resolved = (
+  id: string,
+  range: [number, number],
+  extra: Partial<ResolvedHighlight> = {},
+): ResolvedHighlight => ({
+  id,
+  source: "citation",
+  status: "resolved",
+  address: { kind: "range", start: range[0], end: range[1] },
+  active: false,
+  range,
+  ...extra,
+});
+
+describe("toMarkRanges", () => {
+  it("is empty for no highlights at all", () => {
+    expect(toMarkRanges(undefined, 10)).toEqual({ ranges: [], activeIndex: -1 });
+    expect(toMarkRanges([], 10)).toEqual({ ranges: [], activeIndex: -1 });
+  });
+
+  it("keeps only the entries that actually located", () => {
+    const misses: ResolvedHighlight[] = [
+      { ...resolved("a", [0, 2]), status: "not-found", range: undefined, reason: "absent" },
+      { ...resolved("b", [0, 2]), status: "unsupported", range: undefined },
+      { ...resolved("c", [0, 2]), status: "pending", range: undefined },
+    ];
+    expect(toMarkRanges(misses, 10).ranges).toEqual([]);
+    expect(toMarkRanges([...misses, resolved("d", [4, 6])], 10).ranges).toEqual([[4, 6]]);
+  });
+
+  it("sorts and merges, so out-of-order citations still paint one run", () => {
+    const marks = toMarkRanges(
+      [resolved("b", [6, 9]), resolved("a", [0, 3]), resolved("c", [3, 5])],
+      10,
+    );
+    expect(marks.ranges).toEqual([
+      [0, 5],
+      [6, 9],
+    ]);
+  });
+
+  it("points activeIndex at the MERGED mark containing the active range", () => {
+    // Three requests, two marks: the active one is the second REQUEST but sits
+    // inside the first mark. Counting against the unmerged list would be wrong.
+    const marks = toMarkRanges(
+      [resolved("a", [0, 3]), resolved("b", [3, 5], { active: true }), resolved("c", [7, 9])],
+      10,
+    );
+    expect(marks.ranges).toEqual([
+      [0, 5],
+      [7, 9],
+    ]);
+    expect(marks.activeIndex).toBe(0);
+  });
+
+  it("reports no active mark when nothing is active", () => {
+    expect(toMarkRanges([resolved("a", [0, 3])], 10).activeIndex).toBe(-1);
+  });
+
+  it("clamps to the text it will actually be painted on", () => {
+    expect(toMarkRanges([resolved("a", [8, 40])], 10).ranges).toEqual([[8, 10]]);
+  });
+});
+
+describe("localizeRanges", () => {
+  const marks = toMarkRanges(
+    [resolved("a", [2, 6]), resolved("b", [10, 14], { active: true })],
+    20,
+  );
+
+  it("rebases a range onto the slice that contains it", () => {
+    expect(localizeRanges(marks, 0, 8)).toEqual({ ranges: [[2, 6]], activeIndex: -1 });
+  });
+
+  it("carries the active flag only into the slice the active range touches", () => {
+    expect(localizeRanges(marks, 8, 16)).toEqual({ ranges: [[2, 6]], activeIndex: 0 });
+  });
+
+  it("clips a range that straddles the slice boundary, so it survives in both", () => {
+    // A citation crossing a line break must still read as one continuous run.
+    const straddling = toMarkRanges([resolved("a", [3, 9], { active: true })], 20);
+    expect(localizeRanges(straddling, 0, 6)).toEqual({ ranges: [[3, 6]], activeIndex: 0 });
+    expect(localizeRanges(straddling, 6, 12)).toEqual({ ranges: [[0, 3]], activeIndex: 0 });
+  });
+
+  it("is empty for a slice no range reaches", () => {
+    expect(localizeRanges(marks, 16, 20)).toEqual({ ranges: [], activeIndex: -1 });
+    expect(localizeRanges(marks, 5, 5)).toEqual({ ranges: [], activeIndex: -1 });
+  });
+});

package/src/core/highlight-marks.ts

@@ -0,0 +1,95 @@
+/**
+ * The MAP + PAINT half of the highlight funnel, for adapters whose document IS
+ * its own text projection — plain text, code, and anything else that renders
+ * `document.text` verbatim.
+ *
+ * The shell has already done LOCATE (every quote is now a character range). All
+ * that is left is to hand those ranges to `MatchHighlight` and say which one is
+ * current. An adapter with a richer model (pages, blocks, cells) maps the same
+ * ranges through its own `textIndex` instead and does not use this.
+ */
+
+import { normalizeRanges, type MatchRange } from "@elabs-ai/components-ui";
+
+import type { ResolvedHighlight } from "./highlight";
+
+/** What `MatchHighlight` takes: merged ranges, plus which merged mark is current. */
+export interface MarkRanges {
+  /** Clamped, sorted and merged — the same ranges `MatchHighlight` will paint. */
+  readonly ranges: readonly MatchRange[];
+  /** Index into {@link MarkRanges.ranges}, or `-1` when none is current. */
+  readonly activeIndex: number;
+}
+
+const EMPTY: MarkRanges = { ranges: [], activeIndex: -1 };
+
+/**
+ * Fold resolved highlights into the ranges a `<mark>` layer paints.
+ *
+ * Merging happens HERE rather than being left to `MatchHighlight`, because the
+ * two would otherwise disagree about what "the third mark" is: overlapping
+ * citations collapse into one mark, and an `activeIndex` counted against the
+ * unmerged list would then point at the wrong one — or past the end. The active
+ * entry is located by which merged range CONTAINS its start, so it stays right
+ * no matter how many requests collapsed into that mark.
+ *
+ * Non-`range` addresses and unresolved entries are skipped: an adapter paints
+ * what it can and the shell is what tells the reader about the rest.
+ */
+export function toMarkRanges(
+  highlights: readonly ResolvedHighlight[] | undefined,
+  textLength: number,
+): MarkRanges {
+  if (!highlights || highlights.length === 0) return EMPTY;
+
+  const located = highlights.filter(
+    (highlight): highlight is ResolvedHighlight & { range: MatchRange } =>
+      highlight.status === "resolved" && highlight.range !== undefined,
+  );
+  if (located.length === 0) return EMPTY;
+
+  const ranges = normalizeRanges(
+    located.map((highlight) => highlight.range),
+    textLength,
+  );
+
+  const active = located.find((highlight) => highlight.active);
+  const activeStart = active?.range[0];
+  const activeIndex =
+    activeStart === undefined
+      ? -1
+      : ranges.findIndex(([start, end]) => activeStart >= start && activeStart < end);
+
+  return { ranges, activeIndex };
+}
+
+/**
+ * Re-express document ranges relative to one slice of the document — a code
+ * token, a table cell, a block of prose.
+ *
+ * A renderer that draws its text in pieces cannot hand whole-document offsets to
+ * a `<mark>` layer that only knows about the piece in front of it. Ranges are
+ * clipped to the slice and rebased to 0; the ones that miss it entirely drop
+ * out, which is also how a caller learns there is nothing to mark here (an empty
+ * `ranges`). A range spanning several slices survives in each of them, so a
+ * citation crossing a line break stays one visual run.
+ */
+export function localizeRanges(
+  { ranges, activeIndex }: MarkRanges,
+  start: number,
+  end: number,
+): MarkRanges {
+  if (ranges.length === 0 || start >= end) return EMPTY;
+
+  const local: MatchRange[] = [];
+  let localActive = -1;
+  ranges.forEach(([from, to], index) => {
+    const clippedFrom = Math.max(from, start);
+    const clippedTo = Math.min(to, end);
+    if (clippedFrom >= clippedTo) return;
+    if (index === activeIndex) localActive = local.length;
+    local.push([clippedFrom - start, clippedTo - start]);
+  });
+
+  return local.length === 0 ? EMPTY : { ranges: local, activeIndex: localActive };
+}