@tanishqkancharla/diffmap 0.1.4 → 0.2.0

package/src/viewer/ViewerApp.tsx

@@ -5,18 +5,25 @@ import {
   colors,
   flex,
   flexItem,
+  H1,
+  P,
   proseHtml,
   proseMaxWidth,
   spacing,
   text,
 } from "maui";
 import { style, useStyles } from "purse-styles";
+import { ALL, WORKING, type Rev } from "../changes.js";
 import type { ViewerDocument } from "../parseViewer.js";
 import { ComarkView } from "./ComarkView.tsx";
 import { SourceDiffPanel, type SourceSelection } from "./SourceDiffPanel.js";
-import { DoneButton } from "./DoneButton.tsx";
+import { CloseServerButton } from "./CloseServerButton.tsx";
 import { DiffButton } from "./DiffButton.tsx";
-import { TableOfContents } from "./TableOfContents.tsx";
+import {
+  hasTableOfContents,
+  TableOfContents,
+  TOC_SIDE_MARGIN_PX,
+} from "./TableOfContents.tsx";
 import { ViewerModeContext, type ViewerMode } from "./viewerMode.ts";
 
 type ViewerMeta = {
@@ -28,15 +35,31 @@ export function ViewerApp(props: {
   mode: ViewerMode;
   title?: string;
   headerActions?: ReactNode;
+  /** Changes the Diff button opens before any reference is selected, such as a pull request. */
+  defaultRev?: Rev;
 }) {
   const viewerDocument = props.document;
   const meta = useViewerMeta(props.mode === "local");
   const [selection, setSelection] = useState<SourceSelection>();
-  const [showDiffPanel, setShowDiffPanel] = useState(
-    viewerDocument.sourceDiffs.length > 0,
-  );
+  const [showDiffPanel, setShowDiffPanel] = useState(false);
+  const local = props.mode === "local";
+  const documentRev =
+    props.defaultRev ??
+    viewerDocument.changeRevs[0] ??
+    viewerDocument.references.find((ref) => ref.rev !== undefined)?.rev ??
+    (local ? ALL : WORKING);
+  const [panelRev, setPanelRev] = useState(documentRev);
+  // A reference opens its own rev; a rev-less one opens uncommitted changes locally.
+  const select = (next: SourceSelection) => {
+    setSelection(next);
+    setPanelRev(next.reference.rev ?? (local ? WORKING : documentRev));
+  };
+  // A local viewer always has git changes to show.
   const hasSourceDiffs =
-    viewerDocument.sourceDiffs.length > 0 || viewerDocument.hasReferences;
+    local ||
+    viewerDocument.references.length > 0 ||
+    viewerDocument.changeRevs.length > 0 ||
+    props.defaultRev !== undefined;
   const diffPanelOpen = hasSourceDiffs && showDiffPanel;
   const body = useStyles(styles.body);
   const [shutDown, setShutDown] = useState(false);
@@ -55,8 +78,10 @@ export function ViewerApp(props: {
   const prose = useStyles(styles.prose);
   const content = useStyles(proseHtml("md"), styles.content);
   const closed = useStyles(styles.closed);
+  const closedCopy = useStyles(styles.closedCopy);
+  const stage = useStyles(styles.stage);
   const articleRef = useRef<HTMLElement>(null);
-
+  const hasToc = hasTableOfContents(viewerDocument.headings);
   useEffect(() => {
     document.title = title;
   }, [title]);
@@ -68,7 +93,14 @@ export function ViewerApp(props: {
   }, []);
 
   if (shutDown) {
-    return <main className={closed}>Closed.</main>;
+    return (
+      <main className={closed}>
+        <div className={closedCopy}>
+          <H1>Closed spec</H1>
+          <P>The local server stopped.</P>
+        </div>
+      </main>
+    );
   }
 
   return (
@@ -87,7 +119,7 @@ export function ViewerApp(props: {
             )}
             {props.headerActions}
             {props.mode === "local" && (
-              <DoneButton
+              <CloseServerButton
                 onClick={() => {
                   setShutDown(true);
                   // oxlint-disable-next-line typescript/no-floating-promises -- React click callbacks cannot await the server shutdown request.
@@ -97,35 +129,48 @@ export function ViewerApp(props: {
             )}
           </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 className={stage}>
+          <div className={body} data-has-source-diffs={diffPanelOpen}>
+            <article ref={articleRef} className={article}>
+              <div className={prose} data-has-toc={hasToc ? "true" : "false"}>
+                <div className={content} data-diffmap-kind="page">
+                  <ComarkView
+                    document={viewerDocument}
+                    selectedAnnotation={selection?.annotation}
+                    onSelectAnnotation={(line) => {
+                      setShowDiffPanel(true);
+                      select({
+                        annotation: line,
+                        reference: line.references[0]!,
+                      });
+                    }}
+                  />
+                </div>
+                {hasToc && (
+                  <TableOfContents
+                    headings={viewerDocument.headings}
+                    articleRef={articleRef}
+                  />
+                )}
               </div>
-            </div>
-          </article>
-          {diffPanelOpen && (
-            <SourceDiffPanel
-              items={viewerDocument.sourceDiffs}
-              selection={selection}
-              onSelect={setSelection}
-            />
-          )}
+            </article>
+            {diffPanelOpen && (
+              <SourceDiffPanel
+                rev={panelRev}
+                onRevChange={
+                  local
+                    ? (rev) => {
+                        // A focused reference's lines belong to its own rev.
+                        setSelection(undefined);
+                        setPanelRev(rev);
+                      }
+                    : undefined
+                }
+                selection={selection}
+                onSelect={select}
+              />
+            )}
+          </div>
         </div>
       </div>
     </ViewerModeContext.Provider>
@@ -161,7 +206,7 @@ const styles = {
     backgroundColor: colors.gray[4],
   }),
   header: style(
-    flex({ direction: "row", align: "center", justify: "between" }),
+    flex({ direction: "row", alignItems: "center", justifyContent: "between" }),
     spacing.padding({ x: 6, y: 3 }),
     flexItem({ size: "hug" }),
     border(["bottom"], "border"),
@@ -170,8 +215,9 @@ const styles = {
       backgroundColor: backgroundColor.app,
     },
   ),
-  heading: style(flex({ direction: "column" }), {
+  heading: style(flex({ direction: "row", alignItems: "center", gap: 3 }), {
     minWidth: 0,
+    flex: "1 1 auto",
   }),
   title: style(text({ size: "md", fontWeight: 600, color: "highContrast" }), {
     minWidth: 0,
@@ -179,38 +225,46 @@ const styles = {
     textOverflow: "ellipsis",
     whiteSpace: "nowrap",
   }),
-  actions: style(flex({ direction: "row", align: "center", gap: 3 }), {
+  actions: style(flex({ direction: "row", alignItems: "center", gap: 3 }), {
     flexShrink: 0,
   }),
+  stage: style(flex({ direction: "column" }), {
+    position: "relative",
+    flex: "1 1 auto",
+    minWidth: 0,
+    minHeight: 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",
     backgroundColor: backgroundColor.app,
+    "--diffmap-columns": "minmax(0, 1fr)",
+    "--diffmap-areas": '"article"',
+    gridTemplateColumns: "var(--diffmap-columns)",
+    gridTemplateAreas: "var(--diffmap-areas)",
     "&[data-has-source-diffs='true']": {
-      "--diffmap-columns":
-        "minmax(0, max-content) minmax(0, 1fr) minmax(0, 1fr)",
+      "--diffmap-columns": "minmax(0, 1fr) minmax(0, 1fr)",
+      "--diffmap-areas": '"article diff"',
     },
     "@media (max-width: 900px)": {
       gridTemplateColumns: "minmax(0, 1fr)",
       gridTemplateRows: "minmax(0, 1fr) auto",
+      gridTemplateAreas: '"article" "diff"',
     },
   }),
   article: style(spacing.padding({ x: 12, y: 12 }), {
-    gridColumn: "2",
+    gridArea: "article",
     flex: "1 1 auto",
     minWidth: 0,
     minHeight: 0,
     overflowY: "auto",
     backgroundColor: backgroundColor.app,
-    "@media (max-width: 900px)": {
-      gridColumn: "1",
-    },
+    // Scrollport size for the sticky gutter rail (`100cqh`).
+    containerType: "size",
   }),
   prose: style({
     display: "grid",
@@ -218,9 +272,13 @@ const styles = {
     width: "100%",
     maxWidth: "none",
     minWidth: 0,
+    "&[data-has-toc='true']": {
+      gridTemplateColumns: `minmax(${String(TOC_SIDE_MARGIN_PX)}px, 1fr) minmax(0, ${proseMaxWidth}) minmax(${String(TOC_SIDE_MARGIN_PX)}px, 1fr)`,
+    },
   }),
   content: style({
     gridColumn: "2 / 3",
+    gridRow: "1",
     width: "100%",
     maxWidth: "none",
     minWidth: 0,
@@ -230,31 +288,25 @@ const styles = {
     "& 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 }),
+    flex({
+      direction: "column",
+      alignItems: "center",
+      justifyContent: "center",
+    }),
+    spacing.padding({ x: 12, y: 12 }),
     {
       minHeight: "100vh",
       backgroundColor: backgroundColor.app,
     },
   ),
+  closedCopy: style(
+    flex({ direction: "column", alignItems: "center", gap: 3 }),
+    {
+      width: "100%",
+      maxWidth: proseMaxWidth,
+      textAlign: "center",
+    },
+  ),
 };

package/src/viewer/changesSource.ts

@@ -0,0 +1,91 @@
+import { createContext, useContext, useEffect, useState } from "react";
+import {
+  isCommitRev,
+  type Delta,
+  type DeltasResponse,
+  type Changes,
+  type ChangesResponse,
+  type Rev,
+} from "../changes.js";
+import { DiffmapDefinitionError } from "../errors.js";
+
+/** Where a viewer reads changes: the local server, GitHub, or a gist snapshot. */
+export type ChangesLoader = (rev: Rev) => Promise<Changes | Error>;
+
+const localCache = new Map<Rev, Promise<Changes | Error>>();
+
+/** Commits never change, so they are cached; anything uncommitted is re-read. */
+export const loadLocalChanges: ChangesLoader = (rev) => {
+  const cached = localCache.get(rev);
+  if (cached !== undefined) return cached;
+  const request = fetch(`/__diffmap/changes?${new URLSearchParams({ rev })}`)
+    .then((response) => response.json())
+    .then((value) => {
+      // SAFETY: the local diffmap server owns this response shape.
+      const result = value as ChangesResponse;
+      if (result.changes !== undefined) return result.changes;
+      return new DiffmapDefinitionError({
+        reason: result.error ?? "Could not load changes.",
+      });
+    })
+    .catch(
+      (cause) =>
+        new DiffmapDefinitionError({
+          reason: "Could not reach the source service.",
+          cause,
+        }),
+    );
+  if (isCommitRev(rev)) localCache.set(rev, request);
+  return request;
+};
+
+/** The range picker's rows. Always re-read: uncommitted changes and HEAD move. */
+export async function loadLocalDeltas(rev: Rev): Promise<Delta[] | Error> {
+  const result = await fetch(
+    `/__diffmap/deltas?${new URLSearchParams({ rev })}`,
+  )
+    .then((response) => response.json())
+    .then((value) => {
+      // SAFETY: the local diffmap server owns this response shape.
+      return value as DeltasResponse;
+    })
+    .catch(
+      (cause) =>
+        new DiffmapDefinitionError({
+          reason: "Could not reach the source service.",
+          cause,
+        }),
+    );
+  if (result instanceof Error) return result;
+  return (
+    result.deltas ??
+    new DiffmapDefinitionError({
+      reason: result.error ?? "Could not list changes.",
+    })
+  );
+}
+
+export const ChangesLoaderContext =
+  createContext<ChangesLoader>(loadLocalChanges);
+
+export function useChanges(rev: Rev) {
+  const load = useContext(ChangesLoaderContext);
+  const [loaded, setLoaded] = useState<{
+    rev: Rev;
+    load: ChangesLoader;
+    result: Changes | Error;
+  }>();
+  useEffect(() => {
+    let active = true;
+    // oxlint-disable-next-line typescript/no-floating-promises -- The effect owns this request and ignores it after cleanup.
+    void load(rev).then((result) => {
+      if (active) setLoaded({ rev, load, result });
+    });
+    return () => {
+      active = false;
+    };
+  }, [rev, load]);
+  return loaded?.rev === rev && loaded.load === load
+    ? loaded.result
+    : undefined;
+}

package/src/viewer/sourceHeader.test.ts

@@ -1,11 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import type { CodeViewDiffItem } from "@pierre/diffs";
-import {
-  sourcePanelOrigin,
-  sourcePanelPath,
-  sourcePanelPin,
-} from "./sourceHeader.ts";
+import { sourcePanelPin } from "./sourceHeader.ts";
 
 const sha = "ef78bf4678d2e76a7c8bcc4087fcadf347a1fcdf";
 const github = {
@@ -19,18 +14,9 @@ const gist = {
   htmlUrl: "https://gist.github.com/a3d2fe2b2e0b1422a4fd5378baced900",
 };
 
-function diffItem(id: string, name: string): CodeViewDiffItem {
-  return {
-    id,
-    type: "diff",
-    fileDiff: { name } as CodeViewDiffItem["fileDiff"],
-  };
-}
-
 test("github file pin is owner/repo @ shortsha linking to the blob at the pin SHA", () => {
   const path = "src/cli.ts";
   const pin = sourcePanelPin({
-    origin: "file",
     path,
     github,
   });
@@ -41,42 +27,8 @@ test("github file pin is owner/repo @ shortsha linking to the blob at the pin SH
   });
 });
 
-test("embedded source-diff says from this spec, not a GitHub blob", () => {
-  const items = [diffItem("cli", "src/cli.ts")];
-  const origin = sourcePanelOrigin({
-    showingFile: false,
-    reference: { kind: "file", path: "src/cli.ts" },
-    items,
-    linkedDiffId: "cli",
-  });
-  assert.equal(origin, "spec-diff");
-  assert.deepEqual(sourcePanelPin({ origin, path: "src/cli.ts", github }), {
-    kind: "spec",
-    label: "from this spec",
-  });
-});
-
-test("PR file diffs pin to the repo blob, not from this spec", () => {
-  const items = [diffItem("pr:src/cli.ts", "src/cli.ts")];
-  const origin = sourcePanelOrigin({
-    showingFile: false,
-    reference: { kind: "file", path: "src/cli.ts" },
-    items,
-  });
-  assert.equal(origin, "repo-diff");
-  const pin = sourcePanelPin({ origin, path: "src/cli.ts", github });
-  assert.equal(pin.kind, "github");
-  if (pin.kind !== "github") return;
-  assert.equal(pin.label, "tanishqkancharla/diffmap @ ef78bf4");
-  assert.match(
-    pin.href,
-    /\/blob\/ef78bf4678d2e76a7c8bcc4087fcadf347a1fcdf\/src\/cli.ts$/,
-  );
-});
-
 test("gist pin is gist id / filename, not a fake repo", () => {
   const pin = sourcePanelPin({
-    origin: "file",
     path: "src/cli.ts",
     gist,
   });
@@ -87,45 +39,8 @@ test("gist pin is gist id / filename, not a fake repo", () => {
   });
 });
 
-test("gist embedded source-diff says from this spec", () => {
-  const origin = sourcePanelOrigin({
-    showingFile: false,
-    items: [diffItem("serve", "src/serve.ts")],
-    reference: { kind: "diff", id: "serve", side: "new", start: 1, end: 3 },
-  });
-  assert.equal(origin, "spec-diff");
-  assert.deepEqual(sourcePanelPin({ origin, path: "src/serve.ts", gist }), {
-    kind: "spec",
-    label: "from this spec",
-  });
-});
-
 test("local file has no pin line", () => {
-  assert.deepEqual(sourcePanelPin({ origin: "file", path: "src/cli.ts" }), {
+  assert.deepEqual(sourcePanelPin({ path: "src/cli.ts" }), {
     kind: "none",
   });
 });
-
-test("sourcePanelPath prefers the open file, then the linked diff, then the reference", () => {
-  const items = [diffItem("cli", "src/cli.ts")];
-  assert.equal(
-    sourcePanelPath({ filePath: "src/registry.ts", items }),
-    "src/registry.ts",
-  );
-  assert.equal(
-    sourcePanelPath({
-      items,
-      linkedDiffId: "cli",
-      reference: { kind: "file", path: "src/other.ts" },
-    }),
-    "src/cli.ts",
-  );
-  assert.equal(
-    sourcePanelPath({
-      items,
-      reference: { kind: "file", path: "src/cli.ts" },
-    }),
-    "src/cli.ts",
-  );
-  assert.equal(sourcePanelPath({ items: [] }), undefined);
-});

package/src/viewer/sourceHeader.ts

@@ -1,82 +1,23 @@
-import type { CodeViewDiffItem } from "@pierre/diffs";
-import type { SourceReference } from "../annotations.js";
 import type { GistPin } from "../gist/pin.ts";
 import { githubGistUrl } from "../gist/route.ts";
 import type { GitHubPin } from "../github/pin.ts";
 import { githubBlobUrl } from "../github/route.ts";
 
-const PR_DIFF_PREFIX = "pr:";
-
-export type SourcePanelOrigin = "file" | "spec-diff" | "repo-diff";
-
 export type SourcePanelPin =
   | { kind: "github"; label: string; href: string }
   | { kind: "gist"; label: string; href: string }
-  | { kind: "spec"; label: "from this spec" }
   | { kind: "none" };
 
-/** Pull-files diffs are repo patches at the pin SHA; everything else is embedded in the spec. */
-export function isSpecEmbeddedDiff(item: CodeViewDiffItem) {
-  return !item.id.startsWith(PR_DIFF_PREFIX);
-}
-
-export function sourcePanelPath(input: {
-  filePath?: string;
-  reference?: SourceReference;
-  items: CodeViewDiffItem[];
-  linkedDiffId?: string;
-}): string | undefined {
-  if (input.filePath !== undefined && input.filePath.length > 0) {
-    return input.filePath;
-  }
-  if (input.linkedDiffId !== undefined) {
-    const linked = input.items.find((item) => item.id === input.linkedDiffId);
-    if (linked !== undefined) return linked.fileDiff.name;
-  }
-  const ref = input.reference;
-  if (ref === undefined) return undefined;
-  if (ref.kind === "file") return ref.path;
-  return input.items.find((item) => item.id === ref.id)?.fileDiff.name;
-}
-
-export function sourcePanelOrigin(input: {
-  showingFile: boolean;
-  reference?: SourceReference;
-  items: CodeViewDiffItem[];
-  linkedDiffId?: string;
-}): SourcePanelOrigin {
-  if (input.showingFile) return "file";
-  const ref = input.reference;
-  const focused =
-    input.linkedDiffId !== undefined
-      ? input.items.find((item) => item.id === input.linkedDiffId)
-      : ref?.kind === "diff"
-        ? input.items.find((item) => item.id === ref.id)
-        : ref?.kind === "file"
-          ? input.items.find((item) => item.fileDiff.name === ref.path)
-          : undefined;
-  if (focused !== undefined) {
-    return isSpecEmbeddedDiff(focused) ? "spec-diff" : "repo-diff";
-  }
-  if (input.items.some(isSpecEmbeddedDiff)) return "spec-diff";
-  if (input.items.length > 0) return "repo-diff";
-  return "file";
-}
-
 /**
- * Pin line for the source panel. A hosted spec is one SHA; blob links use that
- * SHA for the open path. Embedded `source-diff` is from the spec, not a blob.
+ * Pin line under a single open file. A hosted spec is one SHA; blob links use
+ * that SHA for the open path.
  */
 export function sourcePanelPin(input: {
-  origin: SourcePanelOrigin;
-  path: string | undefined;
+  path: string;
   github?: GitHubPin;
   gist?: GistPin;
 }): SourcePanelPin {
-  if (input.origin === "spec-diff") {
-    return { kind: "spec", label: "from this spec" };
-  }
-  if (input.github !== undefined && input.path !== undefined) {
+  if (input.github !== undefined) {
     const shortSha = input.github.sha.slice(0, 7);
     return {
       kind: "github",