@tanishqkancharla/diffmap 0.1.3

package/src/viewer/ViewerApp.tsx

@@ -0,0 +1,257 @@
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import {
+  backgroundColor,
+  border,
+  colors,
+  flex,
+  flexItem,
+  proseHtml,
+  proseMaxWidth,
+  spacing,
+  text,
+} from "maui";
+import { style, useStyles } from "purse-styles";
+import type { ViewerDocument } from "../parseViewer.js";
+import { ComarkView } from "./ComarkView.tsx";
+import { SourceDiffPanel, type SourceSelection } from "./SourceDiffPanel.js";
+import { DoneButton } from "./DoneButton.tsx";
+import { DiffButton } from "./DiffButton.tsx";
+import { TableOfContents } from "./TableOfContents.tsx";
+import { ViewerModeContext, type ViewerMode } from "./viewerMode.ts";
+
+type ViewerMeta = {
+  title: string;
+};
+
+export function ViewerApp(props: {
+  document: ViewerDocument;
+  mode: ViewerMode;
+  title?: string;
+  headerActions?: ReactNode;
+}) {
+  const viewerDocument = props.document;
+  const meta = useViewerMeta(props.mode === "local");
+  const [selection, setSelection] = useState<SourceSelection>();
+  const [showDiffPanel, setShowDiffPanel] = useState(false);
+  const hasSourceDiffs =
+    viewerDocument.sourceDiffs.length > 0 || viewerDocument.hasReferences;
+  const diffPanelOpen = hasSourceDiffs && showDiffPanel;
+  const body = useStyles(styles.body);
+  const [shutDown, setShutDown] = useState(false);
+  const parsedTitle =
+    props.title ??
+    viewerDocument.headings.find((heading) => heading.level === 1)?.text ??
+    "diffmap";
+  const title =
+    props.mode === "local" && meta !== undefined ? meta.title : parsedTitle;
+  const shell = useStyles(styles.shell);
+  const header = useStyles(styles.header);
+  const heading = useStyles(styles.heading);
+  const titleClass = useStyles(styles.title);
+  const actions = useStyles(styles.actions);
+  const article = useStyles(styles.article);
+  const prose = useStyles(styles.prose);
+  const content = useStyles(proseHtml("md"), styles.content);
+  const closed = useStyles(styles.closed);
+  const articleRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    document.title = title;
+  }, [title]);
+
+  useEffect(() => {
+    const id = decodeURIComponent(window.location.hash.replace(/^#/, ""));
+    if (id === "") return;
+    document.getElementById(id)?.scrollIntoView({ block: "start" });
+  }, []);
+
+  if (shutDown) {
+    return <main className={closed}>Closed.</main>;
+  }
+
+  return (
+    <ViewerModeContext.Provider value={props.mode}>
+      <div className={shell}>
+        <header className={header}>
+          <div className={heading}>
+            <div className={titleClass}>{title}</div>
+          </div>
+          <div className={actions}>
+            {hasSourceDiffs && (
+              <DiffButton
+                pressed={showDiffPanel}
+                onClick={() => setShowDiffPanel((open) => !open)}
+              />
+            )}
+            {props.headerActions}
+            {props.mode === "local" && (
+              <DoneButton
+                onClick={() => {
+                  setShutDown(true);
+                  // oxlint-disable-next-line typescript/no-floating-promises -- React click callbacks cannot await the server shutdown request.
+                  void closeViewer();
+                }}
+              />
+            )}
+          </div>
+        </header>
+        <div className={body} data-has-source-diffs={diffPanelOpen}>
+          <TableOfContents
+            headings={viewerDocument.headings}
+            articleRef={articleRef}
+          />
+          <article ref={articleRef} className={article}>
+            <div className={prose}>
+              <div className={content} data-diffmap-kind="page">
+                <ComarkView
+                  document={viewerDocument}
+                  selectedAnnotation={selection?.annotation}
+                  onSelectAnnotation={(line) => {
+                    setShowDiffPanel(true);
+                    setSelection({
+                      annotation: line,
+                      reference: line.references[0]!,
+                    });
+                  }}
+                />
+              </div>
+            </div>
+          </article>
+          {diffPanelOpen && (
+            <SourceDiffPanel
+              items={viewerDocument.sourceDiffs}
+              selection={selection}
+              onSelect={setSelection}
+            />
+          )}
+        </div>
+      </div>
+    </ViewerModeContext.Provider>
+  );
+}
+
+function useViewerMeta(enabled: boolean) {
+  const [meta, setMeta] = useState<ViewerMeta>();
+  useEffect(() => {
+    if (!enabled) return;
+    // oxlint-disable-next-line typescript/no-floating-promises -- React effects cannot await; this request owns the metadata update.
+    void fetch("/__diffmap/meta")
+      .then((response) => response.json())
+      .then((value) => {
+        // SAFETY: the diffmap CLI serves this shape from extractTitle.
+        setMeta(value as ViewerMeta);
+      });
+  }, [enabled]);
+  return meta;
+}
+
+async function closeViewer() {
+  await fetch("/__diffmap/shutdown", { method: "POST" });
+}
+
+const styles = {
+  shell: style(flex({ direction: "column" }), {
+    width: "100%",
+    height: "100vh",
+    minWidth: 0,
+    minHeight: 0,
+    overflow: "hidden",
+    backgroundColor: colors.gray[4],
+  }),
+  header: style(
+    flex({ direction: "row", align: "center", justify: "between" }),
+    spacing.padding({ x: 6, y: 3 }),
+    flexItem({ size: "hug" }),
+    border(["bottom"], "border"),
+    {
+      minWidth: 0,
+      backgroundColor: backgroundColor.app,
+    },
+  ),
+  heading: style(flex({ direction: "column" }), {
+    minWidth: 0,
+  }),
+  title: style(text({ size: "md", fontWeight: 600, color: "highContrast" }), {
+    minWidth: 0,
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+  }),
+  actions: style(flex({ direction: "row", align: "center", gap: 3 }), {
+    flexShrink: 0,
+  }),
+  body: style({
+    display: "grid",
+    gridTemplateColumns: "var(--diffmap-columns)",
+    gridTemplateRows: "minmax(0, 1fr)",
+    "--diffmap-columns": "minmax(0, max-content) minmax(0, 1fr)",
+    flex: "1 1 auto",
+    minHeight: 0,
+    minWidth: 0,
+    overflow: "hidden",
+    "&[data-has-source-diffs='true']": {
+      "--diffmap-columns":
+        "minmax(0, max-content) minmax(0, 1fr) minmax(0, 1fr)",
+    },
+    "@media (max-width: 900px)": {
+      gridTemplateColumns: "minmax(0, 1fr)",
+      gridTemplateRows: "minmax(0, 1fr) auto",
+    },
+  }),
+  article: style(spacing.padding({ x: 12, y: 12 }), {
+    gridColumn: "2",
+    flex: "1 1 auto",
+    minWidth: 0,
+    minHeight: 0,
+    overflowY: "auto",
+    backgroundColor: backgroundColor.app,
+    "@media (max-width: 900px)": {
+      gridColumn: "1",
+    },
+  }),
+  prose: style({
+    display: "grid",
+    gridTemplateColumns: `minmax(0, 1fr) minmax(0, ${proseMaxWidth}) minmax(0, 1fr)`,
+    width: "100%",
+    maxWidth: "none",
+    minWidth: 0,
+  }),
+  content: style({
+    gridColumn: "2 / 3",
+    width: "100%",
+    maxWidth: "none",
+    minWidth: 0,
+    "& h1, & h2, & h3, & h4, & h5, & h6": {
+      scrollMarginTop: spacing.value(4),
+    },
+    "& ul > li[data-task]::before, & ol > li[data-task]::before": {
+      content: "none",
+    },
+    "& ul > li[data-task] > .diffmap-task-checkbox, & ol > li[data-task] > .diffmap-task-checkbox":
+      {
+        // Maui proseHtml md listPadding.
+        position: "absolute",
+        left: "-20px",
+        top: "6px",
+      },
+    "& .diffmap-task-checkbox label > span:last-child": {
+      position: "absolute",
+      width: "1px",
+      height: "1px",
+      padding: 0,
+      margin: "-1px",
+      overflow: "hidden",
+      clip: "rect(0, 0, 0, 0)",
+      whiteSpace: "nowrap",
+      border: 0,
+    },
+  }),
+  closed: style(
+    text({ size: "md", fontWeight: 500, color: "highContrast" }),
+    spacing.padding({ all: 12 }),
+    {
+      minHeight: "100vh",
+      backgroundColor: backgroundColor.app,
+    },
+  ),
+};

package/src/viewer/diagramLinks.ts

@@ -0,0 +1,74 @@
+import type { DiagramAnnotation } from "../diagramAnnotations.js";
+import { DiffmapAnnotationError } from "../errors.js";
+
+export function linkDiagram(svg: string, links: DiagramAnnotation[]) {
+  const document = new DOMParser().parseFromString(svg, "image/svg+xml");
+  for (const markerPart of document.querySelectorAll("marker *")) {
+    if (markerPart.getAttribute("fill") === "var(--_arrow)")
+      markerPart.setAttribute("fill", "context-stroke");
+    if (markerPart.getAttribute("stroke") === "var(--_arrow)")
+      markerPart.setAttribute("stroke", "context-stroke");
+  }
+  const edges = [
+    ...document.querySelectorAll<SVGElement>(
+      ".edge, .message, .class-relationship, .er-relationship",
+    ),
+  ];
+  const labels = [...document.querySelectorAll<SVGElement>(".edge-label")];
+  for (const [index, link] of links.entries()) {
+    const elements =
+      link.target === "node"
+        ? [...document.querySelectorAll<SVGElement>("[data-id]")].filter(
+            (element) => element.dataset.id === link.id,
+          )
+        : edges.slice(Number(link.id), Number(link.id) + 1);
+    if (elements.length === 0)
+      return new DiffmapAnnotationError({
+        reason: `Mermaid ${link.target}:${link.id} does not exist in this diagram.`,
+      });
+    for (const element of elements) {
+      const wrapper = document.createElementNS(
+        "http://www.w3.org/2000/svg",
+        "g",
+      );
+      element.replaceWith(wrapper);
+      wrapper.append(element);
+      wrapper.setAttribute("data-source-index", String(index));
+      wrapper.setAttribute("class", `source-target source-${link.target}`);
+      wrapper.setAttribute("role", "button");
+      wrapper.setAttribute("tabindex", "0");
+      wrapper.setAttribute("aria-controls", "source-diff-panel");
+      wrapper.setAttribute("aria-pressed", "false");
+      const label = element.getAttribute("data-label");
+      wrapper.setAttribute(
+        "aria-label",
+        `Open source: ${label === null || label.length === 0 ? link.annotation.text : label}`,
+      );
+      if (link.target !== "edge") continue;
+      const edgeIndex = Number(link.id);
+      const sameEdge = (candidate: SVGElement) =>
+        candidate.dataset.from === element.dataset.from &&
+        candidate.dataset.to === element.dataset.to &&
+        candidate.dataset.label === element.dataset.label;
+      const occurrence = edges.slice(0, edgeIndex).filter(sameEdge).length;
+      const edgeLabel = labels.filter(sameEdge)[occurrence];
+      if (edgeLabel !== undefined) wrapper.append(edgeLabel);
+      const strokes = element.matches("polyline, path, line")
+        ? [element]
+        : [...element.querySelectorAll<SVGElement>("line, polyline, path")];
+      for (const stroke of strokes) {
+        // SAFETY: cloning an SVG element preserves its element type.
+        const hit = stroke.cloneNode(true) as SVGElement;
+        hit.removeAttribute("marker-start");
+        hit.removeAttribute("marker-end");
+        hit.setAttribute("class", "source-hit");
+        hit.setAttribute("stroke", "transparent");
+        hit.setAttribute("stroke-width", "14");
+        hit.setAttribute("fill", "none");
+        hit.setAttribute("aria-hidden", "true");
+        wrapper.prepend(hit);
+      }
+    }
+  }
+  return document.documentElement.outerHTML;
+}

package/src/viewer/diffsTheme.ts

@@ -0,0 +1,4 @@
+export const diffsTheme = {
+  dark: "pierre-dark",
+  light: "pierre-light",
+} as const;

package/src/viewer/main.tsx

@@ -0,0 +1,17 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { MauiProvider } from "maui";
+import { viewerDocument } from "virtual:diffmap";
+import { ViewerApp } from "./ViewerApp.tsx";
+import "./styles.css";
+
+const root = document.getElementById("root");
+if (root === null) throw new Error("diffmap root element is missing");
+
+createRoot(root).render(
+  <StrictMode>
+    <MauiProvider>
+      <ViewerApp document={viewerDocument} mode="local" />
+    </MauiProvider>
+  </StrictMode>,
+);

package/src/viewer/pierre.ts

@@ -0,0 +1,47 @@
+import { colors, radius, shadow } from "maui";
+import { style } from "purse-styles";
+import { codeFontFamily } from "../codeFont.js";
+import { diffsTheme } from "./diffsTheme.ts";
+
+const pierreUnsafeCss = `:host { --diffs-font-family: ${codeFontFamily}; }`;
+
+export const sourceSelectionCss = `
+[data-selected-line] {
+  --diffs-computed-selected-line-bg: var(--diffs-computed-diff-line-bg);
+}
+[data-line][data-selected-line] {
+  box-shadow: inset 4px 0 ${colors.blue[9]};
+}
+[data-column-number][data-selected-line] {
+  background-color: ${colors.blue[3]};
+  color: ${colors.blue[12]};
+}
+`;
+
+export const pierreShell = style(radius.md, shadow.subtle, {
+  overflow: "hidden",
+  minWidth: 0,
+});
+
+export function pierreDiffOptions(input: {
+  themeType: "light" | "dark";
+  disableFileHeader: boolean;
+}) {
+  return {
+    theme: diffsTheme,
+    themeType: input.themeType,
+    overflow: "wrap" as const,
+    diffStyle: "unified" as const,
+    unsafeCSS: pierreUnsafeCss,
+    disableFileHeader: input.disableFileHeader,
+  };
+}
+
+export function pierreFileOptions(themeType: "light" | "dark") {
+  return {
+    theme: diffsTheme,
+    themeType,
+    overflow: "wrap" as const,
+    unsafeCSS: pierreUnsafeCss,
+  };
+}

package/src/viewer/sourceNavigation.ts

@@ -0,0 +1,104 @@
+import { useEffect, useState } from "react";
+import type { CodeViewDiffItem, CodeViewLineSelection } from "@pierre/diffs";
+import type { SourceReference } from "../annotations.js";
+import type { SourceDefinition, DefinitionResponse } from "../definitions.js";
+import { DiffmapDefinitionError } from "../errors.js";
+
+export async function requestSource(
+  endpoint: "source" | "definition",
+  params: URLSearchParams,
+) {
+  const response = await fetch(`/__diffmap/${endpoint}?${params}`).catch(
+    (cause) =>
+      new DiffmapDefinitionError({
+        reason: "Could not reach the source service.",
+        cause,
+      }),
+  );
+  if (response instanceof Error) return response;
+  const result = await response
+    .json()
+    .then((value) => {
+      // SAFETY: the local diffmap source endpoints own this response shape.
+      return value as DefinitionResponse;
+    })
+    .catch(
+      (cause) =>
+        new DiffmapDefinitionError({
+          reason: "Could not read the source response.",
+          cause,
+        }),
+    );
+  if (result instanceof Error) return result;
+  if (result.error !== undefined)
+    return new DiffmapDefinitionError({ reason: result.error });
+  if (result.definition === undefined)
+    return new DiffmapDefinitionError({ reason: "No definition found." });
+  return result.definition;
+}
+
+export function useSourceReference(reference: SourceReference | undefined) {
+  const [resolution, setResolution] = useState<{
+    reference: SourceReference;
+    result: SourceDefinition | Error;
+  }>();
+  useEffect(() => {
+    if (reference?.kind !== "file") return;
+    const params = new URLSearchParams({ path: reference.path });
+    if (reference.symbol !== undefined) params.set("symbol", reference.symbol);
+    if (reference.start !== undefined)
+      params.set("start", String(reference.start));
+    if (reference.end !== undefined) params.set("end", String(reference.end));
+    let active = true;
+    // oxlint-disable-next-line typescript/no-floating-promises -- The effect owns its asynchronous source result.
+    void requestSource("source", params).then((result) => {
+      if (active) setResolution({ reference, result });
+    });
+    return () => {
+      active = false;
+    };
+  }, [reference]);
+  return resolution?.reference === reference ? resolution?.result : undefined;
+}
+
+export function matchingSourceDiff(
+  source: SourceDefinition,
+  items: CodeViewDiffItem[],
+): CodeViewLineSelection | undefined {
+  const lines = source.contents.split(/\r?\n/);
+  for (const item of items) {
+    const diff = item.fileDiff;
+    if (diff.name !== source.path) continue;
+    const ranges = diff.hunks.flatMap((hunk) => {
+      const start = Math.max(source.start, hunk.additionStart);
+      const end = Math.min(
+        source.end,
+        hunk.additionStart + hunk.additionCount - 1,
+      );
+      return start <= end ? [{ start, end, hunk }] : [];
+    });
+    if (ranges.length === 0) continue;
+    const matches = ranges.every(({ start, end, hunk }) => {
+      for (let line = start; line <= end; line++) {
+        const index = diff.isPartial
+          ? hunk.additionLineIndex + line - hunk.additionStart
+          : line - 1;
+        if (
+          diff.additionLines[index]?.replace(/\r?\n$/, "") !== lines[line - 1]
+        )
+          return false;
+      }
+      return true;
+    });
+    if (!matches) continue;
+    return {
+      id: item.id,
+      range: {
+        start: Math.min(...ranges.map((range) => range.start)),
+        end: Math.max(...ranges.map((range) => range.end)),
+        side: "additions",
+      },
+    };
+  }
+  return undefined;
+}

package/src/viewer/styles.css

@@ -0,0 +1,9 @@
+html {
+  min-width: 320px;
+  min-height: 100%;
+}
+
+body,
+#root {
+  min-height: 100vh;
+}

package/src/viewer/viewerMode.ts

@@ -0,0 +1,9 @@
+import { createContext, useContext } from "react";
+
+export type ViewerMode = "local" | "gist";
+
+export const ViewerModeContext = createContext<ViewerMode>("local");
+
+export function useViewerMode() {
+  return useContext(ViewerModeContext);
+}

package/src/viewer/vite-env.d.ts

@@ -0,0 +1,4 @@
+declare module "virtual:diffmap" {
+  import type { ViewerDocument } from "../parseViewer.js";
+  export const viewerDocument: ViewerDocument;
+}

package/vite.config.ts

@@ -0,0 +1,41 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+import { gistAppConfig } from "./vite.gist.config.ts";
+
+const packageRoot = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig(({ command }) => {
+  // Vercel’s Vite preset runs `vite build` with this file. Production must
+  // be the gist app (`gist/index.html`), not the local viewer that imports
+  // `virtual:diffmap`.
+  if (command === "build") return gistAppConfig();
+
+  return {
+    // Browser ESM cannot load CJS packages such as Pierre. Vite writes one
+    // prebundle into this directory and reuses it until dependencies change.
+    cacheDir: path.join(packageRoot, "node_modules/.vite"),
+    optimizeDeps: {
+      include: [
+        "react",
+        "react-dom",
+        "react/jsx-dev-runtime",
+        "maui",
+        "purse-styles",
+        "@pierre/diffs/react",
+        "beautiful-mermaid",
+        "errore",
+      ],
+    },
+    plugins: [react()],
+    resolve: {
+      dedupe: ["react", "react-dom", "purse-styles"],
+    },
+    clearScreen: false,
+    server: {
+      port: 4177,
+      strictPort: false,
+    },
+  };
+});