@elabs-ai/components-viewer 4.0.0

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

@@ -0,0 +1,272 @@
+"use client";
+
+/**
+ * Code adapter — source files, highlighted with Shiki and coloured by tokens.
+ *
+ * Highlighting happens at LOAD, not at render: `load()` returns lines of plain
+ * `{ text, color }` tokens, so the renderer draws data like every other adapter
+ * and Shiki never reaches the render path. The colours are `var(--code-*)`
+ * references (see `code-theme.ts`), which is why a theme switch recolours the
+ * document without re-tokenizing it.
+ *
+ * The plain-text adapter is still the backstop. This one claims extensions it
+ * has a grammar for; anything else — a log, a `.env`, no extension at all —
+ * falls through to text, and so does every file when Shiki is not installed.
+ */
+
+import { MatchHighlight, cn, StatePanel, useLocale } from "@elabs-ai/components-ui";
+import type { ResolvedFileSource } from "@elabs-ai/components-ui";
+import { Fragment, useMemo, useRef } from "react";
+import type { BundledLanguage, ThemedToken } from "shiki";
+
+import { toViewerError } from "../../core/errors";
+import { localizeRanges, toMarkRanges } from "../../core/highlight-marks";
+import { useScrollActiveHighlightIntoView } from "../../core/use-highlight-scroll";
+import type {
+  AdapterDocument,
+  AdapterLoadContext,
+  AdapterModule,
+  AdapterRendererProps,
+  FileAdapter,
+} from "../../core/types";
+import { languageFor } from "./code-language";
+import { codeManifest } from "./code-manifest";
+import { codeViewerTheme } from "./code-theme";
+
+/**
+ * Characters kept before truncation. Well below the plain-text limit because
+ * this text is also TOKENIZED — a grammar pass over multiple megabytes blocks
+ * the main thread, and no one reads a 400k-character file in a preview pane.
+ */
+export const CODE_CHARACTER_LIMIT = 400_000;
+
+/** One highlighted run. `color` is always a `var(--code-*)` reference. */
+export interface CodeToken {
+  text: string;
+  color?: string;
+  italic?: boolean;
+  bold?: boolean;
+  underline?: boolean;
+}
+
+export interface CodeDocument extends AdapterDocument {
+  kind: "code";
+  /** Shiki language id, or `undefined` when the file rendered unhighlighted. */
+  language?: string;
+  /** One entry per line; a blank line is an empty array. */
+  lines: CodeToken[][];
+  text: string;
+  /** Total characters in the file, when more than what is shown. */
+  totalCharacters?: number;
+}
+
+// Shiki encodes font style as bitflags: 1 = italic, 2 = bold, 4 = underline.
+const hasFontFlag = (fontStyle: number | undefined, flag: number) =>
+  ((fontStyle ?? 0) & flag) === flag;
+
+/**
+ * Highlighters, cached per language for the lifetime of the page.
+ *
+ * Not per-document state, so it deliberately outlives the adapter instance:
+ * building one loads a grammar and the WASM engine, and paging through twenty
+ * TypeScript files in a file tree should pay for that once.
+ */
+const highlighters = new Map<string, Promise<{ tokenize(code: string): ThemedToken[][] }>>();
+
+function getHighlighter(language: BundledLanguage) {
+  let pending = highlighters.get(language);
+  if (!pending) {
+    pending = (async () => {
+      // Dynamic: the ONLY edge to the optional peer (heavy-deps:check).
+      const { createHighlighter } = await import("shiki");
+      const highlighter = await createHighlighter({
+        themes: [codeViewerTheme],
+        langs: [language],
+      });
+      return {
+        tokenize: (code: string) =>
+          highlighter.codeToTokens(code, {
+            lang: language,
+            theme: codeViewerTheme.name as string,
+          }).tokens,
+      };
+    })().catch((error: unknown) => {
+      // Not cached: a peer installed later, or a transient chunk-load failure,
+      // must be retryable without a page reload.
+      highlighters.delete(language);
+      throw error;
+    });
+    highlighters.set(language, pending);
+  }
+  return pending;
+}
+
+/** Split unhighlighted text into the same line/token shape. */
+function plainLines(text: string): CodeToken[][] {
+  return text.split("\n").map((line) => (line.length > 0 ? [{ text: line }] : []));
+}
+
+class CodeAdapter implements FileAdapter {
+  async load(source: ResolvedFileSource, context: AdapterLoadContext): Promise<CodeDocument> {
+    let raw: string;
+    try {
+      raw = await source.text(context.signal);
+    } catch (error) {
+      throw toViewerError(error, "read-failed", { fileName: source.name });
+    }
+
+    const truncated = raw.length > CODE_CHARACTER_LIMIT;
+    const text = truncated ? raw.slice(0, CODE_CHARACTER_LIMIT) : raw;
+    const totalCharacters = truncated ? raw.length : undefined;
+    // So a passage the shell cannot find reads as "past the part we previewed"
+    // rather than "not in this document".
+    const textTruncated = truncated || undefined;
+    const language = languageFor(source.name);
+
+    // No grammar for this name — still a perfectly readable file.
+    if (!language) {
+      return { kind: "code", lines: plainLines(text), text, totalCharacters, textTruncated };
+    }
+
+    const highlighter = await getHighlighter(language);
+    if (context.signal?.aborted) {
+      return {
+        kind: "code",
+        language,
+        lines: plainLines(text),
+        text,
+        totalCharacters,
+        textTruncated,
+      };
+    }
+
+    const lines = highlighter.tokenize(text).map((line) =>
+      line.map((token) => ({
+        text: token.content,
+        color: token.color,
+        italic: hasFontFlag(token.fontStyle, 1) || undefined,
+        bold: hasFontFlag(token.fontStyle, 2) || undefined,
+        underline: hasFontFlag(token.fontStyle, 4) || undefined,
+      })),
+    );
+
+    return { kind: "code", language, lines, text, totalCharacters, textTruncated };
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* Renderer                                                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Where each rendered line begins in `document.text`.
+ *
+ * Derived from the TEXT, not from the token lines: the text is the address space
+ * every highlight is expressed in, so counting its newlines is the only mapping
+ * that cannot drift from what a caller asked for. The two agree by construction
+ * — the tokenizer splits on the same newlines — and `code-adapter.test.tsx`
+ * locks that.
+ */
+function lineStartsIn(text: string): number[] {
+  const starts = [0];
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "\n") starts.push(i + 1);
+  }
+  return starts;
+}
+
+function CodeRenderer({
+  document: doc,
+  className,
+  highlights,
+  activeHighlightId,
+}: AdapterRendererProps) {
+  const code = doc as CodeDocument;
+  const { t, formatNumber } = useLocale();
+  const container = useRef<HTMLDivElement>(null);
+  const lineStarts = useMemo(() => lineStartsIn(code.text), [code.text]);
+  const marks = useMemo(
+    () => toMarkRanges(highlights, code.text.length),
+    [highlights, code.text.length],
+  );
+  useScrollActiveHighlightIntoView(container, activeHighlightId);
+
+  if (code.text.length === 0) {
+    return <StatePanel kind="empty" title={t("viewer.file.empty")} className={className} />;
+  }
+
+  return (
+    // No `overflow-auto` here: `FileViewerContent` is the scroll boundary, and
+    // nesting a second one clips the last line above the outer pane's padding.
+    <div ref={container} className={cn("flex flex-col gap-2", className)}>
+      {code.totalCharacters !== undefined && (
+        // Not an error — the file is fine, we are showing part of it.
+        <p role="status" className="text-meta text-muted-foreground">
+          {t("viewer.text.truncated", {
+            shown: formatNumber(code.text.length),
+            total: formatNumber(code.totalCharacters),
+          })}
+        </p>
+      )}
+      <pre className="text-code text-code-foreground font-mono">
+        <code className="grid grid-cols-[auto_1fr] gap-x-4">
+          {code.lines.map((tokens, lineIndex) => {
+            let offset = lineStarts[lineIndex] ?? code.text.length;
+            return (
+              <Fragment key={lineIndex}>
+                {/* Decorative: the numbers are a reading aid, and keeping them out
+                  of the accessibility tree also keeps them out of a copy. Not
+                  `formatNumber` — a line gutter is an ordinal, so a thousands
+                  separator at line 1,000 would be wrong in every locale. */}
+                <span
+                  aria-hidden="true"
+                  className="text-muted-foreground text-right tabular-nums select-none"
+                >
+                  {lineIndex + 1}
+                </span>
+                <span className="break-words whitespace-pre-wrap">
+                  {tokens.map((token, tokenIndex) => {
+                    const start = offset;
+                    offset += token.text.length;
+                    // Syntax colour is inline `var(--code-*)` (see the module
+                    // header), and a mark's plate would fight it — so the mark
+                    // layer only wraps the tokens it actually touches, and every
+                    // other token keeps rendering exactly as before.
+                    const local = localizeRanges(marks, start, offset);
+                    const style = {
+                      color: token.color,
+                      fontStyle: token.italic ? "italic" : undefined,
+                      fontWeight: token.bold ? "bold" : undefined,
+                      textDecoration: token.underline ? "underline" : undefined,
+                    };
+                    return local.ranges.length === 0 ? (
+                      <span key={tokenIndex} style={style}>
+                        {token.text}
+                      </span>
+                    ) : (
+                      <MatchHighlight
+                        key={tokenIndex}
+                        style={style}
+                        text={token.text}
+                        ranges={local.ranges}
+                        activeIndex={local.activeIndex}
+                      />
+                    );
+                  })}
+                </span>
+              </Fragment>
+            );
+          })}
+        </code>
+      </pre>
+    </div>
+  );
+}
+
+const adapterModule: AdapterModule = {
+  manifest: codeManifest,
+  create: () => new CodeAdapter(),
+  Renderer: CodeRenderer,
+};
+
+export default adapterModule;

package/src/adapters/code/code-language.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import { CODE_EXTENSIONS, languageFor } from "./code-language";
+
+describe("languageFor", () => {
+  it("maps an extension to its Shiki grammar", () => {
+    expect(languageFor("registry.ts")).toBe("typescript");
+    expect(languageFor("Button.tsx")).toBe("tsx");
+    expect(languageFor("deploy.yml")).toBe("yaml");
+  });
+
+  it("is case-insensitive — a file name is not a grammar", () => {
+    expect(languageFor("MAIN.PY")).toBe("python");
+  });
+
+  it("reads the WHOLE name when a language carries it there", () => {
+    // Dockerfile and Makefile have no extension at all; matching only the last
+    // dot-segment would send both to the plain-text backstop.
+    expect(languageFor("Dockerfile")).toBe("docker");
+    expect(languageFor("Makefile")).toBe("make");
+  });
+
+  it("takes the LAST extension of a multi-part name", () => {
+    expect(languageFor("vite.config.ts")).toBe("typescript");
+  });
+
+  it("returns nothing for a file it has no grammar for", () => {
+    expect(languageFor("server.log")).toBeUndefined();
+    expect(languageFor("notes")).toBeUndefined();
+  });
+
+  it("leaves the formats other adapters own alone", () => {
+    // Claiming these would decide the winner by registration order rather than
+    // by design: JSON gets a tree, CSV a table, markdown a document.
+    for (const extension of ["json", "csv", "md", "markdown", "svg", "pdf"]) {
+      expect(CODE_EXTENSIONS).not.toContain(extension);
+    }
+  });
+
+  it("claims every extension it can actually highlight, and only those", () => {
+    for (const extension of CODE_EXTENSIONS) {
+      expect(languageFor(`file.${extension}`)).toBeTruthy();
+    }
+  });
+});

package/src/adapters/code/code-language.ts

@@ -0,0 +1,100 @@
+/**
+ * Extension → Shiki language id.
+ *
+ * A pure data module on purpose: `code-manifest.ts` derives the extensions it
+ * claims from this map, so the list the registry matches on and the list the
+ * highlighter can actually tokenize can never drift apart. Adding a language is
+ * one line here.
+ *
+ * What is deliberately ABSENT is as load-bearing as what is present. `json`,
+ * `csv`, `md` and `svg` are claimed by their own adapters — a JSON file gets a
+ * collapsible tree, not a coloured wall of text — and an extension listed in two
+ * manifests would be decided by registration order rather than by design.
+ */
+
+import type { BundledLanguage } from "shiki";
+
+/**
+ * Shiki's own language ids.
+ *
+ * `satisfies Record<string, BundledLanguage>` is the point of the annotation: a
+ * typo'd grammar name fails typecheck HERE, rather than at runtime as a file
+ * that silently refuses to highlight. Type-only import, so this stays a pure
+ * data module with no edge to the engine.
+ */
+const LANGUAGE_BY_EXTENSION = {
+  bash: "shellscript",
+  c: "c",
+  cc: "cpp",
+  cjs: "javascript",
+  cpp: "cpp",
+  cs: "csharp",
+  css: "css",
+  cts: "typescript",
+  dart: "dart",
+  diff: "diff",
+  dockerfile: "docker",
+  go: "go",
+  gql: "graphql",
+  graphql: "graphql",
+  groovy: "groovy",
+  h: "c",
+  hcl: "hcl",
+  hpp: "cpp",
+  htm: "html",
+  html: "html",
+  ini: "ini",
+  java: "java",
+  js: "javascript",
+  jsx: "jsx",
+  kt: "kotlin",
+  kts: "kotlin",
+  less: "less",
+  lua: "lua",
+  makefile: "make",
+  mjs: "javascript",
+  mts: "typescript",
+  patch: "diff",
+  php: "php",
+  pl: "perl",
+  proto: "proto",
+  ps1: "powershell",
+  py: "python",
+  r: "r",
+  rb: "ruby",
+  rs: "rust",
+  sass: "sass",
+  scala: "scala",
+  scss: "scss",
+  sh: "shellscript",
+  sql: "sql",
+  svelte: "svelte",
+  swift: "swift",
+  tf: "terraform",
+  toml: "toml",
+  ts: "typescript",
+  tsx: "tsx",
+  vue: "vue",
+  xml: "xml",
+  yaml: "yaml",
+  yml: "yaml",
+  zsh: "shellscript",
+} as const satisfies Record<string, BundledLanguage>;
+
+/** Every extension the code adapter claims, lowercase and without the dot. */
+export const CODE_EXTENSIONS = Object.keys(LANGUAGE_BY_EXTENSION);
+
+/**
+ * The Shiki language for a file name, or `undefined` when nothing matches.
+ *
+ * Matches the extension first, then the whole (lowercased) file name — that is
+ * what catches `Dockerfile` and `Makefile`, which carry their language in the
+ * name and have no extension at all.
+ */
+export function languageFor(fileName: string): BundledLanguage | undefined {
+  const name = fileName.toLowerCase();
+  const dot = name.lastIndexOf(".");
+  const extension = dot > 0 ? name.slice(dot + 1) : name;
+  const map: Record<string, BundledLanguage> = LANGUAGE_BY_EXTENSION;
+  return map[extension] ?? map[name];
+}

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

@@ -0,0 +1,19 @@
+import type { AdapterManifest } from "../../core/types";
+import { PROTOCOL_VERSION } from "../../core/types";
+import { CODE_EXTENSIONS } from "./code-language";
+
+/**
+ * Eager, data-only (see `image-manifest.ts`).
+ *
+ * Claims EXTENSIONS only — never the `code` category. That is what keeps the
+ * plain-text adapter as the backstop: a `.log`, a `.env` or an unknown
+ * extension still opens as text instead of failing to find a grammar, and a
+ * consumer who never installs Shiki loses highlighting rather than the file.
+ */
+export const codeManifest: AdapterManifest = {
+  id: "code",
+  protocol: PROTOCOL_VERSION,
+  extensions: CODE_EXTENSIONS,
+  capabilities: { text: true, search: true, highlight: ["quote", "range"] },
+  requires: ["shiki"],
+};

package/src/adapters/code/code-theme.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+
+import { codeViewerTheme } from "./code-theme";
+
+const rules = codeViewerTheme.settings ?? [];
+
+/** Every rule whose scope list contains `scope`, whatever else it contains. */
+const rulesFor = (scope: string) =>
+  rules.filter((rule) => {
+    const declared = rule.scope;
+    const list = Array.isArray(declared) ? declared : declared ? [declared] : [];
+    return list.includes(scope);
+  });
+
+describe("code viewer theme", () => {
+  it("colours every scope with a token, never a literal", () => {
+    // The whole reason ONE theme is correct in every brand theme. A hex here
+    // would freeze at tokenize time and survive a theme switch unchanged.
+    for (const rule of rules) {
+      expect(rule.settings?.foreground).toMatch(/^var\(--code-[a-z-]+\)$/);
+    }
+    expect(codeViewerTheme.bg).toBe("transparent");
+  });
+
+  it("italicises comments and attribute names — and nothing else", () => {
+    const italic = rules.filter((rule) => rule.settings?.fontStyle === "italic");
+    const scopes = italic.flatMap((rule) =>
+      Array.isArray(rule.scope) ? rule.scope : rule.scope ? [rule.scope] : [],
+    );
+    expect(scopes).toContain("comment");
+    expect(scopes).toContain("entity.other.attribute-name");
+    expect(scopes).not.toContain("variable");
+    expect(scopes).not.toContain("meta.object-literal.key");
+  });
+
+  it("keeps plain identifiers upright", () => {
+    // The regression this locks: `entity.other.attribute-name` shared an array
+    // with `variable`, and a rule's `fontStyle` applies to its whole scope list
+    // — so every local, parameter and imported binding in the file leaned.
+    // Asserting on the rule (not on rendered output) is the point: the bug was
+    // invisible in any fixture without attributes.
+    for (const rule of rulesFor("variable")) {
+      expect(rule.settings?.fontStyle).toBeUndefined();
+    }
+  });
+});

package/src/adapters/code/code-theme.ts

@@ -0,0 +1,99 @@
+/**
+ * The Shiki theme the code adapter tokenizes with — brand tokens, not a
+ * recoloured `github-light`.
+ *
+ * Every colour here is a `var(--code-*)` reference rather than a literal, which
+ * is what makes ONE theme correct in EVERY brand theme: the active `data-theme`
+ * block decides what `--code-keyword` resolves to, so a runtime theme switch
+ * recolours already-tokenized code with no re-highlight, no `MutationObserver`
+ * and no cache to invalidate. It is the same technique Shiki ships as
+ * `createCssVariablesTheme`, written out by hand for one reason: that helper
+ * maps a fixed, smaller scope set and cannot reach `--code-type` or
+ * `--code-tag`, which this design system does define.
+ *
+ * `@elabs-ai/components-ai`'s `CodeBlock` resolves the same tokens
+ * the other way round (oklch → hex, re-derived per theme change) because
+ * `@streamdown/code` freezes its themes at import time and cannot take a live
+ * `var()`. Nothing here needs that, so nothing here pays for it.
+ *
+ * Type-only import: this module is pure data and holds no edge to the engine.
+ */
+
+import type { ThemeRegistrationRaw } from "shiki";
+
+/**
+ * TextMate scopes → brand code tokens.
+ *
+ * Ordered coarse-to-fine, because Shiki resolves the LAST matching rule: the
+ * broad `constant` rule has to come before `constant.numeric` or every number
+ * would read as a constant.
+ *
+ * `italic` is a convention, not a colour, so it is theme-safe — but it is
+ * declared PER RULE and never inferred from the scope list. A rule's styling
+ * applies to every scope in its array, so a lone italic scope sharing an array
+ * with ordinary ones italicises all of them: bundling `entity.other.attribute-name`
+ * with `variable` slanted every plain identifier in the file, which is the most
+ * common token class there is. Give an italic scope its own entry.
+ */
+const SCOPE_COLORS: ReadonlyArray<{
+  readonly scopes: string[];
+  readonly token: string;
+  readonly italic?: boolean;
+}> = [
+  {
+    scopes: ["comment", "punctuation.definition.comment"],
+    token: "--code-comment",
+    italic: true,
+  },
+  { scopes: ["string", "string.quoted", "punctuation.definition.string"], token: "--code-string" },
+  {
+    scopes: ["constant", "constant.language", "constant.character", "support.constant"],
+    token: "--code-constant",
+  },
+  { scopes: ["constant.numeric", "keyword.other.unit"], token: "--code-number" },
+  {
+    scopes: ["keyword", "keyword.control", "keyword.operator", "storage", "storage.type"],
+    token: "--code-keyword",
+  },
+  {
+    scopes: ["entity.name.function", "support.function", "meta.function-call"],
+    token: "--code-function",
+  },
+  {
+    scopes: ["entity.name.type", "entity.name.class", "support.type", "support.class"],
+    token: "--code-type",
+  },
+  { scopes: ["entity.name.tag", "punctuation.definition.tag"], token: "--code-tag" },
+  { scopes: ["variable", "support.variable", "meta.object-literal.key"], token: "--code-property" },
+  // Same colour as a property, but the one other scope that leans. Its own rule,
+  // for the reason in the docblock above.
+  { scopes: ["entity.other.attribute-name"], token: "--code-property", italic: true },
+];
+
+/**
+ * The theme, built once at module load. Shiki treats a theme object as opaque
+ * data, so one instance is safely shared by every highlighter.
+ */
+export const codeViewerTheme: ThemeRegistrationRaw = {
+  name: "brand-ui-viewer",
+  // Shiki uses `type` only to pick its own light/dark defaults, which this theme
+  // overrides wholesale. It is `css` — neither, resolved at paint time.
+  type: "dark",
+  colors: {
+    // The renderer owns the surface; the theme must not paint over it.
+    "editor.background": "transparent",
+    "editor.foreground": "var(--code-foreground)",
+  },
+  fg: "var(--code-foreground)",
+  bg: "transparent",
+  settings: [
+    { settings: { foreground: "var(--code-foreground)" } },
+    ...SCOPE_COLORS.map(({ scopes, token, italic }) => ({
+      scope: scopes,
+      settings: {
+        foreground: `var(${token})`,
+        ...(italic ? { fontStyle: "italic" } : undefined),
+      },
+    })),
+  ],
+};