@tanishqkancharla/diffmap 0.4.0 → 0.6.1

package/src/viewer/SourceDiffPanel.tsx

@@ -2,6 +2,7 @@ import { useEffect, useMemo, useRef, useState, type MouseEvent } from "react";
 import { CodeView, type CodeViewHandle } from "@pierre/diffs/react";
 import type { CodeViewOptions, CodeViewLineSelection } from "@pierre/diffs";
 import {
+  ActivityIndicator,
   backgroundColor,
   border,
   borderColor,
@@ -9,7 +10,11 @@ import {
   Button,
   ChevronDown,
   flex,
+  motion,
+  radius,
+  shadow,
   spacing,
+  Text,
   text,
   useTheme,
 } from "maui";
@@ -19,7 +24,12 @@ import {
   type SourceAnnotation,
   type SourceReference,
 } from "../annotations.js";
-import { changedFileItem, orderForReview, type Rev } from "../changes.js";
+import {
+  changedFileItem,
+  orderForReview,
+  type Changes,
+  type Rev,
+} from "../changes.js";
 import type { SourceDefinition } from "../definitions.js";
 import { useGistPin } from "../gist/pin.ts";
 import { useGitHubPin } from "../github/pin.ts";
@@ -40,7 +50,18 @@ export type SourceSelection = {
 type DefinitionNavigation = {
   selection: SourceSelection | undefined;
   history: SourceDefinition[];
-  status: string | undefined;
+  /** A definition request in flight, or the error it ended with. */
+  request: "finding" | Error | undefined;
+};
+
+/** Everything the panel renders from; it keeps the last loaded page while the next one loads. */
+type PanelPage = {
+  rev: Rev;
+  review: string[];
+  selection: SourceSelection | undefined;
+  history: SourceDefinition[];
+  changes: Changes | Error | undefined;
+  source: SourceDefinition | Error | undefined;
 };
 
 export function SourceDiffPanel(props: {
@@ -59,35 +80,74 @@ export function SourceDiffPanel(props: {
   const [navigation, setNavigation] = useState<DefinitionNavigation>({
     selection: props.selection,
     history: [],
-    status: undefined,
+    request: undefined,
   });
   if (navigation.selection !== props.selection) {
     setNavigation({
       selection: props.selection,
       history: [],
-      status: undefined,
+      request: undefined,
     });
   }
-  const { history } = navigation;
   const request = useRef(0);
+  const hostFiles = useHostFiles();
+  const nextChanges = useChanges(props.rev);
+  const nextReference = props.selection?.reference;
+  // A rev-less reference resolves against current files; a commit reference names its lines directly.
+  const nextSource = useSourceReference(
+    nextReference?.kind === "file" && nextReference.rev === undefined
+      ? nextReference
+      : undefined,
+  );
+  const loading =
+    nextChanges === undefined
+      ? "Loading changes…"
+      : nextReference?.kind === "file" &&
+          nextReference.rev === undefined &&
+          nextSource === undefined &&
+          (mode === "local" || mode === "github" || hostFiles !== undefined)
+        ? "Opening source…"
+        : navigation.request === "finding"
+          ? "Finding definition…"
+          : undefined;
+  const next: PanelPage = {
+    rev: props.rev,
+    review: props.review,
+    selection: props.selection,
+    history: navigation.history,
+    changes: nextChanges,
+    source: nextSource,
+  };
+  // The new page replaces the old one only once it has loaded, so nothing half-loaded shows in between.
+  const [page, setPage] = useState(next);
+  if (
+    loading === undefined &&
+    (page.rev !== next.rev ||
+      page.review !== next.review ||
+      page.selection !== next.selection ||
+      page.history !== next.history ||
+      page.changes !== next.changes ||
+      page.source !== next.source)
+  ) {
+    setPage(next);
+  }
+  const { history, selection, changes, source, review } = page;
   const definition = history.at(-1);
   const panel = useStyles(styles.panel);
-  const header = useStyles(styles.header);
+  const header = useStyles(styles.header, styles.dimmed);
   const titleRow = useStyles(styles.titleRow);
   const titleClass = useStyles(styles.title);
   const pinClass = useStyles(styles.pin);
   const links = useStyles(styles.links);
   const code = useStyles(styles.code);
   const summary = useStyles(styles.summary);
-  const codeWrap = useStyles(styles.codeWrap);
+  const codeWrap = useStyles(styles.codeWrap, styles.dimmed);
   const collapseIcon = useStyles(styles.collapseIcon);
   const github = useGitHubPin();
   const gist = useGistPin();
-  const hostFiles = useHostFiles();
-  const selection = props.selection;
+  const loadingClass = useStyles(styles.loading);
+  const spinner = useStyles(styles.spinner);
   const reference = selection?.reference;
-  const changes = useChanges(props.rev);
-  const { review } = props;
   const items = useMemo(() => {
     if (changes === undefined || changes instanceof Error) return [];
     const { reviewed, other } = orderForReview(changes.files, review);
@@ -95,12 +155,6 @@ export function SourceDiffPanel(props: {
       (changed) => changedFileItem(changed) ?? [],
     );
   }, [changes, review]);
-  // A rev-less reference resolves against current files; a commit reference names its lines directly.
-  const source = useSourceReference(
-    reference?.kind === "file" && reference.rev === undefined
-      ? reference
-      : undefined,
-  );
   const resolvedFile = source instanceof Error ? undefined : source;
   const inChanges =
     resolvedFile !== undefined &&
@@ -111,25 +165,16 @@ export function SourceDiffPanel(props: {
       ? resolvedFile
       : undefined);
   const status =
-    navigation.status !== undefined
-      ? navigation.status
+    navigation.request instanceof Error
+      ? navigation.request.message
       : source instanceof Error
         ? source.message
         : // A shown file replaces the changes, so their error is moot, as in a gist without uncommitted changes.
           changes instanceof Error && file === undefined
           ? changes.message
-          : changes === undefined
-            ? "Loading changes…"
-            : reference?.kind === "file" &&
-                reference.rev === undefined &&
-                source === undefined &&
-                (mode === "local" ||
-                  mode === "github" ||
-                  hostFiles !== undefined)
-              ? "Opening source…"
-              : items.length === 0 && file === undefined
-                ? "No changes."
-                : undefined;
+          : changes !== undefined && items.length === 0 && file === undefined
+            ? "No changes."
+            : undefined;
   const selectedLines = useMemo<CodeViewLineSelection | null>(() => {
     if (file !== undefined)
       return { id: file.path, range: { start: file.start, end: file.end } };
@@ -156,9 +201,9 @@ export function SourceDiffPanel(props: {
     rev: Rev;
     selection: SourceSelection | undefined;
     paths: ReadonlySet<string>;
-  }>({ rev: props.rev, selection, paths: new Set() });
-  if (collapse.rev !== props.rev || collapse.selection !== selection) {
-    setCollapse({ rev: props.rev, selection, paths: new Set() });
+  }>({ rev: page.rev, selection, paths: new Set() });
+  if (collapse.rev !== page.rev || collapse.selection !== selection) {
+    setCollapse({ rev: page.rev, selection, paths: new Set() });
   }
   const rangeId = selectedLines?.id;
   const rangeStart = selectedLines?.range.start;
@@ -300,28 +345,33 @@ export function SourceDiffPanel(props: {
       text: lineText,
     });
     const currentRequest = ++request.current;
-    setNavigation({ selection, history, status: "Finding definition…" });
+    setNavigation({ selection, history, request: "finding" });
     // oxlint-disable-next-line typescript/no-floating-promises -- Token callbacks cannot await; the request owns its status update.
     void requestSource("definition", params).then((result) => {
       if (currentRequest !== request.current) return;
       setNavigation((current) => {
         if (current.selection !== selection) return current;
-        if (result instanceof Error)
-          return { ...current, status: result.message };
+        if (result instanceof Error) return { ...current, request: result };
         return {
           selection,
           history: [...history, result],
-          status: undefined,
+          request: undefined,
         };
       });
     });
   };
 
   return (
-    <aside id="source-diff-panel" aria-label="Source changes" className={panel}>
+    <aside
+      id="source-diff-panel"
+      aria-label="Source changes"
+      aria-busy={loading !== undefined}
+      className={panel}
+    >
       <div
         className={header}
         data-diffmap-kind="source-header"
+        data-loading={loading !== undefined}
         // Pierre's file headers draw their own top border, which divides them from this header.
         data-file-headers={!showTitle && items.length > 0}
       >
@@ -337,7 +387,11 @@ export function SourceDiffPanel(props: {
           props.onRevChange === undefined &&
           loadedChanges !== undefined && (
             <div className={titleRow}>
-              {loadedChanges.url === undefined ? (
+              {selection?.annotation.title !== undefined ? (
+                <div className={titleClass} title={selection.annotation.title}>
+                  {selection.annotation.title}
+                </div>
+              ) : loadedChanges.url === undefined ? (
                 <div className={titleClass} title={loadedChanges.title}>
                   {loadedChanges.title}
                 </div>
@@ -365,7 +419,7 @@ export function SourceDiffPanel(props: {
                   setNavigation({
                     selection,
                     history: history.slice(0, -1),
-                    status: undefined,
+                    request: undefined,
                   });
                 }}
               >
@@ -417,7 +471,13 @@ export function SourceDiffPanel(props: {
           )}
       </div>
       {/* oxlint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions -- Pierre's file headers are the click targets; this only catches their clicks. */}
-      <div className={codeWrap} onClick={onHeaderClick}>
+      <div
+        className={codeWrap}
+        data-loading={loading !== undefined}
+        // The last page stays visible while the next one loads, but it is no longer the one to act on.
+        inert={loading !== undefined}
+        onClick={onHeaderClick}
+      >
         <CodeView
           ref={viewer}
           className={code}
@@ -458,6 +518,19 @@ export function SourceDiffPanel(props: {
           )}
         />
       </div>
+      <div
+        className={loadingClass}
+        role="status"
+        data-loading={loading !== undefined}
+      >
+        {loading !== undefined && (
+          // Inline in the label, the spinner sits on the text's baseline at its size, so it lines up in any font.
+          <Text size="sm" color="lowContrast">
+            <ActivityIndicator className={spinner} />
+            {loading}
+          </Text>
+        )}
+      </div>
     </aside>
   );
 }
@@ -468,6 +541,7 @@ const panelBackgroundCss = `:host { --diffs-light-bg: ${backgroundColor.app}; --
 
 const styles = {
   panel: style(flex({ direction: "column" }), border(["left"], "border"), {
+    position: "relative",
     gridArea: "diff",
     minWidth: 0,
     minHeight: 0,
@@ -527,6 +601,28 @@ const styles = {
     minWidth: 0,
     minHeight: 0,
   }),
+  // Loads that finish within the delay swap pages without dimming.
+  dimmed: style(motion.standard("opacity"), {
+    "&[data-loading='true']": { opacity: 0.4, transitionDelay: "150ms" },
+  }),
+  loading: style(
+    radius.md,
+    shadow.medium,
+    spacing.padding({ x: 6, y: 3 }),
+    motion.standard("opacity"),
+    {
+      position: "absolute",
+      top: "50%",
+      left: "50%",
+      transform: "translate(-50%, -50%)",
+      whiteSpace: "nowrap",
+      backgroundColor: backgroundColor.app,
+      pointerEvents: "none",
+      opacity: 0,
+      "&[data-loading='true']": { opacity: 1, transitionDelay: "150ms" },
+    },
+  ),
+  spinner: style({ marginRight: spacing.value(4) }),
   collapseIcon: style({
     display: "flex",
     color: colors.gray[11],

package/src/viewer/TableOfContents.tsx

@@ -10,6 +10,7 @@ import { motion, useReducedMotion, type Transition } from "motion/react";
 import {
   background,
   colors,
+  Drawer,
   focusRing,
   motionEasing,
   overlayMotion,
@@ -67,6 +68,9 @@ export function tocLineWidth(level: number, shallowestLevel: number) {
 export function TableOfContents(props: {
   headings: ViewerHeading[];
   articleRef: RefObject<HTMLElement | null>;
+  /** The narrow-screen drawer, opened from the header's TOC button. */
+  drawerOpen: boolean;
+  onDrawerOpenChange: (open: boolean) => void;
 }) {
   const headings = tocHeadings(props.headings);
   const items = nestHeadings(headings);
@@ -78,6 +82,7 @@ export function TableOfContents(props: {
   const docked = useDocked(navRef);
   const railClass = useStyles(styles.rail);
   const dockedClass = useStyles(styles.docked);
+  const drawerClass = useStyles(styles.drawer);
   const listClass = useStyles(styles.list);
 
   if (items.length === 0) return undefined;
@@ -92,24 +97,43 @@ export function TableOfContents(props: {
   );
 
   return (
-    <nav
-      ref={navRef}
-      id="diffmap-toc"
-      className={railClass}
-      aria-label="Table of contents"
-      data-diffmap-kind="toc"
-      data-docked={docked ? "true" : "false"}
-    >
-      {docked ? (
-        <div className={dockedClass} data-diffmap-kind="toc-list">
-          {list}
-        </div>
-      ) : (
-        <TocRail headings={headings} activeId={activeId}>
-          {list}
-        </TocRail>
-      )}
-    </nav>
+    <>
+      <nav
+        ref={navRef}
+        id="diffmap-toc"
+        className={railClass}
+        aria-label="Table of contents"
+        data-diffmap-kind="toc"
+        data-docked={docked ? "true" : "false"}
+      >
+        {docked ? (
+          <div className={dockedClass} data-diffmap-kind="toc-list">
+            {list}
+          </div>
+        ) : (
+          <TocRail headings={headings} activeId={activeId}>
+            {list}
+          </TocRail>
+        )}
+      </nav>
+      <Drawer
+        isOpen={props.drawerOpen}
+        onOpenChange={props.onDrawerOpenChange}
+        aria-label="Table of contents"
+      >
+        <nav className={drawerClass} aria-label="Table of contents">
+          <TocList
+            items={items}
+            className={listClass}
+            activeId={activeId}
+            onSelect={(id) => {
+              setActiveId(id);
+              props.onDrawerOpenChange(false);
+            }}
+          />
+        </nav>
+      </Drawer>
+    </>
   );
 }
 
@@ -458,6 +482,8 @@ const styles = {
     pointerEvents: "auto",
     ...tocListRules,
   }),
+  // The same list in Maui's Drawer, which supplies the surface and scrolling.
+  drawer: style(spacing.padding({ x: 3, y: 3 }), tocListRules),
   list: style(text({ size: "sm", fontWeight: 400, color: "lowContrast" })),
   item: style({
     "&::before": {

package/src/viewer/TocButton.tsx

@@ -0,0 +1,28 @@
+import { Button, UnorderedList } from "maui";
+import { style, useStyles } from "purse-styles";
+
+/** Opens the table of contents on narrow screens, where the gutter rail is hidden. */
+export function TocButton(props: { expanded: boolean; onClick: () => void }) {
+  const className = useStyles(styles.button);
+  return (
+    <Button
+      className={className}
+      variant="quiet"
+      aria-label="Table of contents"
+      aria-haspopup="dialog"
+      aria-expanded={props.expanded}
+      onClick={props.onClick}
+    >
+      <UnorderedList size="sm" />
+    </Button>
+  );
+}
+
+const styles = {
+  button: style({
+    flexShrink: 0,
+    "@media (min-width: 601px)": {
+      display: "none",
+    },
+  }),
+};

package/src/viewer/ViewerApp.tsx

@@ -19,6 +19,7 @@ import { ComarkView } from "./ComarkView.tsx";
 import { SourceDiffPanel, type SourceSelection } from "./SourceDiffPanel.js";
 import { CloseServerButton } from "./CloseServerButton.tsx";
 import { DiffButton } from "./DiffButton.tsx";
+import { TocButton } from "./TocButton.tsx";
 import {
   hasTableOfContents,
   TableOfContents,
@@ -87,6 +88,7 @@ export function ViewerApp(props: {
   const stage = useStyles(styles.stage);
   const articleRef = useRef<HTMLElement>(null);
   const hasToc = hasTableOfContents(viewerDocument.headings);
+  const [tocDrawerOpen, setTocDrawerOpen] = useState(false);
   useEffect(() => {
     document.title = title;
   }, [title]);
@@ -113,6 +115,12 @@ export function ViewerApp(props: {
       <div className={shell}>
         <header className={header}>
           <div className={heading}>
+            {hasToc && (
+              <TocButton
+                expanded={tocDrawerOpen}
+                onClick={() => setTocDrawerOpen(true)}
+              />
+            )}
             <div className={titleClass}>{title}</div>
           </div>
           <div className={actions}>
@@ -155,6 +163,8 @@ export function ViewerApp(props: {
                   <TableOfContents
                     headings={viewerDocument.headings}
                     articleRef={articleRef}
+                    drawerOpen={tocDrawerOpen}
+                    onDrawerOpenChange={setTocDrawerOpen}
                   />
                 )}
               </div>

package/src/viewer/diagramDiff.ts

@@ -0,0 +1,69 @@
+const edgeSelector =
+  ".edge, .edge-label, .message, .class-relationship, .er-relationship";
+
+/**
+ * Marks what changed in a `mermaid diff`. `svg` draws every line; `today`
+ * and `proposed` draw each side alone. A node or edge missing from Proposed
+ * gets data-change="-", one missing from Today "+", and a node whose label
+ * differs between the sides "~".
+ */
+export function markDiagramChanges(
+  svg: string,
+  sides: { today: string; proposed: string },
+) {
+  const document = parse(svg);
+  const today = parse(sides.today);
+  const proposed = parse(sides.proposed);
+
+  const todayNodes = nodeLabels(today);
+  const proposedNodes = nodeLabels(proposed);
+  for (const node of document.querySelectorAll("[data-id]")) {
+    const id = node.getAttribute("data-id");
+    if (!proposedNodes.has(id)) node.setAttribute("data-change", "-");
+    else if (!todayNodes.has(id)) node.setAttribute("data-change", "+");
+    else if (todayNodes.get(id) !== proposedNodes.get(id))
+      node.setAttribute("data-change", "~");
+  }
+  // A removed sequence participant takes its lifeline with it.
+  for (const lifeline of document.querySelectorAll("[data-actor]")) {
+    const id = lifeline.getAttribute("data-actor");
+    if (!proposedNodes.has(id)) lifeline.setAttribute("data-change", "-");
+    else if (!todayNodes.has(id)) lifeline.setAttribute("data-change", "+");
+  }
+
+  const todayEdges = edgeKeys(today);
+  const proposedEdges = edgeKeys(proposed);
+  for (const edge of document.querySelectorAll(edgeSelector)) {
+    const key = edgeKey(edge);
+    if (!proposedEdges.has(key)) edge.setAttribute("data-change", "-");
+    else if (!todayEdges.has(key)) edge.setAttribute("data-change", "+");
+  }
+  return document.documentElement.outerHTML;
+}
+
+function parse(svg: string) {
+  return new DOMParser().parseFromString(svg, "image/svg+xml");
+}
+
+function nodeLabels(document: Document) {
+  return new Map(
+    [...document.querySelectorAll("[data-id]")].map((node) => [
+      node.getAttribute("data-id"),
+      node.getAttribute("data-label"),
+    ]),
+  );
+}
+
+/** An edge, edge label, or message by its kind, ends, and label. */
+function edgeKey(edge: Element) {
+  return [
+    edge.getAttribute("class"),
+    edge.getAttribute("data-from"),
+    edge.getAttribute("data-to"),
+    edge.getAttribute("data-label") ?? "",
+  ].join("\u0000");
+}
+
+function edgeKeys(document: Document) {
+  return new Set([...document.querySelectorAll(edgeSelector)].map(edgeKey));
+}

package/src/viewer/diagramLinks.ts

@@ -1,14 +1,21 @@
+import { colors } from "maui";
 import type { DiagramAnnotation } from "../diagramAnnotations.js";
 import { DiffmapAnnotationError } from "../errors.js";
 
+/**
+ * Arrowhead colors for edges that are not plain gray: changed in a diff,
+ * hovered, or selected. Later tones win when several apply.
+ */
+const markerTones = [
+  ["added", "[data-change='+']", colors.green[9]],
+  ["removed", "[data-change='-']", colors.red[9]],
+  ["hover", ".source-edge:hover", colors.blue[8]],
+  ["selected", ".source-edge[aria-pressed='true']", colors.blue[9]],
+] as const;
+
 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");
-  }
+  colorMarkers(document);
   const edges = [
     ...document.querySelectorAll<SVGElement>(
       ".edge, .message, .class-relationship, .er-relationship",
@@ -72,3 +79,44 @@ export function linkDiagram(svg: string, links: DiagramAnnotation[]) {
   }
   return document.documentElement.outerHTML;
 }
+
+/**
+ * A marker draws in its own colors, not its edge's, and `context-stroke`
+ * falls back to black where browsers lack it. So each marker gets one copy
+ * per tone, and a style rule swaps an edge to the copy its state needs.
+ */
+function colorMarkers(document: Document) {
+  const rules: string[] = [];
+  for (const marker of document.querySelectorAll("marker[id]")) {
+    const id = marker.id;
+    for (const [tone, , color] of markerTones) {
+      // SAFETY: cloning an element preserves its element type.
+      const copy = marker.cloneNode(true) as Element;
+      copy.id = `${id}--${tone}`;
+      paintArrow(copy, color);
+      marker.after(copy);
+    }
+    // Mermaid draws arrowheads in the accent color; match the gray line.
+    paintArrow(marker, "var(--_line)");
+    for (const end of ["start", "end"]) {
+      const uses = `[marker-${end}="url(#${id})"]`;
+      if (document.querySelector(uses) === null) continue;
+      for (const [tone, state] of markerTones)
+        rules.push(
+          `:is(${state}, ${state} *)${uses} { marker-${end}: url(#${id}--${tone}); }`,
+        );
+    }
+  }
+  if (rules.length === 0) return;
+  const style = document.createElementNS("http://www.w3.org/2000/svg", "style");
+  style.textContent = rules.join("\n");
+  document.documentElement.prepend(style);
+}
+
+/** Repaints a marker's mermaid arrow color. */
+function paintArrow(marker: Element, color: string) {
+  for (const part of [marker, ...marker.querySelectorAll("*")])
+    for (const paint of ["fill", "stroke"])
+      if (part.getAttribute(paint) === "var(--_arrow)")
+        part.setAttribute(paint, color);
+}

package/src/viewer/notes.tsx

@@ -105,7 +105,6 @@ export function NoteText(props: { text: string }) {
 
 const symbolNoteClass = style(focusRing(), {
   borderRadius: "3px",
-  cursor: "help",
   textDecorationLine: "underline",
   textDecorationStyle: "dotted",
   textDecorationColor: colors.gray[9],

package/src/viewer/pierre.ts

@@ -1,9 +1,18 @@
-import { colors, radius, shadow } from "maui";
+import {
+  backgroundColor,
+  border,
+  colors,
+  radius,
+  shadow,
+  spacing,
+  text,
+} from "maui";
 import { style } from "purse-styles";
 import { codeFontFamily } from "../codeFont.js";
 import { diffsTheme } from "./diffsTheme.ts";
 
-const pierreUnsafeCss = `:host { --diffs-font-family: ${codeFontFamily}; }`;
+// Pierre paints its own white; widgets use the element surface instead.
+const pierreUnsafeCss = `:host { --diffs-font-family: ${codeFontFamily}; --diffs-light-bg: ${backgroundColor.app}; --diffs-dark-bg: ${backgroundColor.app}; }`;
 
 export const sourceSelectionCss = `
 [data-selected-line] {
@@ -18,11 +27,20 @@ export const sourceSelectionCss = `
 }
 `;
 
+/** The card every widget sits in: a subtle ring on the page background. */
 export const pierreShell = style(radius.md, shadow.subtle, {
   overflow: "hidden",
   minWidth: 0,
 });
 
+/** The header row atop a card: a fence's `[Title]` or a diagram's caption. */
+export const fenceTitle = style(
+  text({ size: "xs", fontWeight: 500, color: "lowContrast" }),
+  spacing.padding({ x: 6, y: 4 }),
+  border(["bottom"], "border"),
+  { margin: 0, overflowWrap: "anywhere", backgroundColor: colors.gray[2] },
+);
+
 export function pierreDiffOptions(input: {
   themeType: "light" | "dark";
   disableFileHeader: boolean;