@tanishqkancharla/diffmap 0.1.3 → 0.1.5

package/src/viewer/ViewerApp.tsx

@@ -1,10 +1,18 @@
-import { useEffect, useRef, useState, type ReactNode } from "react";
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
 import {
   backgroundColor,
   border,
   colors,
   flex,
   flexItem,
+  H1,
+  P,
   proseHtml,
   proseMaxWidth,
   spacing,
@@ -14,9 +22,15 @@ 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 { CloseServerButton } from "./CloseServerButton.tsx";
 import { DiffButton } from "./DiffButton.tsx";
-import { TableOfContents } from "./TableOfContents.tsx";
+import { TocButton } from "./TocButton.tsx";
+import {
+  hasTableOfContents,
+  TableOfContents,
+  TOC_OPEN_MIN_WIDTH_PX,
+  TOC_SIDE_MARGIN_PX,
+} from "./TableOfContents.tsx";
 import { ViewerModeContext, type ViewerMode } from "./viewerMode.ts";
 
 type ViewerMeta = {
@@ -53,7 +67,64 @@ 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);
+  const tocDismissed = useRef(false);
+  const tocPinned = useRef(false);
+  const tocFits = useRef(window.innerWidth >= TOC_OPEN_MIN_WIDTH_PX);
+  const remeasureToc = useRef<() => void>(() => {});
+  const [tocOpen, setTocOpen] = useState<TocMode | undefined>(() =>
+    hasToc && window.innerWidth >= TOC_OPEN_MIN_WIDTH_PX ? "space" : undefined,
+  );
+  const tocExpanded = tocOpen !== undefined;
+  const onDwellOpen = useCallback(() => {
+    setTocOpen((mode) =>
+      mode === "click" || mode === "space" ? mode : "dwell",
+    );
+  }, []);
+  const onDwellClose = useCallback(() => {
+    setTocOpen((mode) => {
+      if (mode === "click" || mode === "space") return mode;
+      if (tocFits.current && !tocDismissed.current) {
+        return tocPinned.current ? "click" : "space";
+      }
+      return undefined;
+    });
+  }, []);
+
+  useEffect(() => {
+    if (!hasToc) return;
+    const measure = () => {
+      const node = articleRef.current;
+      if (node !== null && node.clientWidth === 0) return;
+      const width = node?.clientWidth ?? window.innerWidth;
+      const next = width >= TOC_OPEN_MIN_WIDTH_PX;
+      const previous = tocFits.current;
+      tocFits.current = next;
+      if (previous === next) return;
+      if (!next) {
+        setTocOpen(undefined);
+        return;
+      }
+      setTocOpen((mode) => {
+        if (mode === "click" || mode === "dwell") return mode;
+        if (tocDismissed.current) return undefined;
+        return tocPinned.current ? "click" : "space";
+      });
+    };
+    remeasureToc.current = measure;
+    const observer = new ResizeObserver(measure);
+    const articleNode = articleRef.current;
+    if (articleNode) observer.observe(articleNode);
+    window.addEventListener("resize", measure);
+    return () => {
+      observer.disconnect();
+      window.removeEventListener("resize", measure);
+      remeasureToc.current = () => {};
+    };
+  }, [hasToc]);
 
   useEffect(() => {
     document.title = title;
@@ -66,7 +137,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 (
@@ -74,18 +152,37 @@ export function ViewerApp(props: {
       <div className={shell}>
         <header className={header}>
           <div className={heading}>
+            {hasToc && (
+              <TocButton
+                expanded={tocExpanded}
+                onClick={() => {
+                  if (tocExpanded) {
+                    tocDismissed.current = true;
+                    tocPinned.current = false;
+                    setTocOpen(undefined);
+                    return;
+                  }
+                  tocDismissed.current = false;
+                  tocPinned.current = true;
+                  setTocOpen("click");
+                }}
+              />
+            )}
             <div className={titleClass}>{title}</div>
           </div>
           <div className={actions}>
             {hasSourceDiffs && (
               <DiffButton
                 pressed={showDiffPanel}
-                onClick={() => setShowDiffPanel((open) => !open)}
+                onClick={() => {
+                  setShowDiffPanel((open) => !open);
+                  window.requestAnimationFrame(() => remeasureToc.current());
+                }}
               />
             )}
             {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.
@@ -95,41 +192,53 @@ 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);
+                      setSelection({
+                        annotation: line,
+                        reference: line.references[0]!,
+                      });
+                      window.requestAnimationFrame(() =>
+                        remeasureToc.current(),
+                      );
+                    }}
+                  />
+                </div>
+                {hasToc && (
+                  <TableOfContents
+                    headings={viewerDocument.headings}
+                    articleRef={articleRef}
+                    open={tocExpanded}
+                    onDwellOpen={onDwellOpen}
+                    onDwellClose={onDwellClose}
+                  />
+                )}
               </div>
-            </div>
-          </article>
-          {diffPanelOpen && (
-            <SourceDiffPanel
-              items={viewerDocument.sourceDiffs}
-              selection={selection}
-              onSelect={setSelection}
-            />
-          )}
+            </article>
+            {diffPanelOpen && (
+              <SourceDiffPanel
+                items={viewerDocument.sourceDiffs}
+                selection={selection}
+                onSelect={setSelection}
+              />
+            )}
+          </div>
         </div>
       </div>
     </ViewerModeContext.Provider>
   );
 }
 
+type TocMode = "click" | "dwell" | "space";
+
 function useViewerMeta(enabled: boolean) {
   const [meta, setMeta] = useState<ViewerMeta>();
   useEffect(() => {
@@ -159,7 +268,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"),
@@ -168,8 +277,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,
@@ -177,37 +287,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",
@@ -215,9 +334,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,
@@ -247,11 +370,23 @@ const styles = {
     },
   }),
   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/main.tsx

@@ -1,8 +1,9 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
-import { MauiProvider } from "maui";
-import { viewerDocument } from "virtual:diffmap";
+import { MauiProvider, P } from "maui";
+import { parseError, viewerDocument } from "virtual:diffmap";
 import { ViewerApp } from "./ViewerApp.tsx";
+import { GistStatus } from "../gist/GistStatus.tsx";
 import "./styles.css";
 
 const root = document.getElementById("root");
@@ -11,7 +12,13 @@ if (root === null) throw new Error("diffmap root element is missing");
 createRoot(root).render(
   <StrictMode>
     <MauiProvider>
-      <ViewerApp document={viewerDocument} mode="local" />
+      {parseError !== null || viewerDocument === null ? (
+        <GistStatus title="Could not parse this spec">
+          <P>{parseError ?? "Unknown parse error."}</P>
+        </GistStatus>
+      ) : (
+        <ViewerApp document={viewerDocument} mode="local" />
+      )}
     </MauiProvider>
   </StrictMode>,
 );

package/src/viewer/sourceHeader.test.ts

@@ -0,0 +1,131 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { CodeViewDiffItem } from "@pierre/diffs";
+import {
+  sourcePanelOrigin,
+  sourcePanelPath,
+  sourcePanelPin,
+} from "./sourceHeader.ts";
+
+const sha = "ef78bf4678d2e76a7c8bcc4087fcadf347a1fcdf";
+const github = {
+  owner: "tanishqkancharla",
+  repo: "diffmap",
+  sha,
+};
+const gist = {
+  gistId: "a3d2fe2b2e0b1422a4fd5378baced900",
+  file: "walkthrough.md",
+  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,
+  });
+  assert.deepEqual(pin, {
+    kind: "github",
+    label: "tanishqkancharla/diffmap @ ef78bf4",
+    href: `https://github.com/tanishqkancharla/diffmap/blob/${sha}/src/cli.ts`,
+  });
+});
+
+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,
+  });
+  assert.deepEqual(pin, {
+    kind: "gist",
+    label: "a3d2fe2b2e0b1422a4fd5378baced900 / walkthrough.md",
+    href: "https://gist.github.com/a3d2fe2b2e0b1422a4fd5378baced900",
+  });
+});
+
+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" }), {
+    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

@@ -0,0 +1,103 @@
+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.
+ */
+export function sourcePanelPin(input: {
+  origin: SourcePanelOrigin;
+  path: string | undefined;
+  github?: GitHubPin;
+  gist?: GistPin;
+}): SourcePanelPin {
+  if (input.origin === "spec-diff") {
+    return { kind: "spec", label: "from this spec" };
+  }
+  if (input.github !== undefined && input.path !== undefined) {
+    const shortSha = input.github.sha.slice(0, 7);
+    return {
+      kind: "github",
+      label: `${input.github.owner}/${input.github.repo} @ ${shortSha}`,
+      href: githubBlobUrl(
+        input.github.owner,
+        input.github.repo,
+        input.github.sha,
+        input.path,
+      ),
+    };
+  }
+  if (input.gist !== undefined) {
+    return {
+      kind: "gist",
+      label: `${input.gist.gistId} / ${input.gist.file}`,
+      href:
+        input.gist.htmlUrl.length > 0
+          ? input.gist.htmlUrl
+          : githubGistUrl(input.gist.gistId),
+    };
+  }
+  return { kind: "none" };
+}