@tanishqkancharla/diffmap 0.3.0 → 0.6.0

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, 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,12 +50,25 @@ 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: {
   /** The changes to show; references with their own rev open that rev instead. */
   rev: Rev;
+  /** Paths to show first, in order, as the rev's changes card lists them. */
+  review: string[];
   /** Local viewers pick other changes with the range picker. */
   onRevChange?: (rev: Rev) => void;
   selection: SourceSelection | undefined;
@@ -57,47 +80,81 @@ 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 items = useMemo(
-    () =>
-      changes === undefined || changes instanceof Error
-        ? []
-        : changes.files.flatMap((changed) => changedFileItem(changed) ?? []),
-    [changes],
-  );
-  // 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 items = useMemo(() => {
+    if (changes === undefined || changes instanceof Error) return [];
+    const { reviewed, other } = orderForReview(changes.files, review);
+    return [...reviewed, ...other].flatMap(
+      (changed) => changedFileItem(changed) ?? [],
+    );
+  }, [changes, review]);
   const resolvedFile = source instanceof Error ? undefined : source;
   const inChanges =
     resolvedFile !== undefined &&
@@ -108,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 } };
@@ -153,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;
@@ -297,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}
       >
@@ -334,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>
@@ -362,7 +419,7 @@ export function SourceDiffPanel(props: {
                   setNavigation({
                     selection,
                     history: history.slice(0, -1),
-                    status: undefined,
+                    request: undefined,
                   });
                 }}
               >
@@ -414,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}
@@ -455,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>
   );
 }
@@ -465,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,
@@ -524,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>
+    </>
   );
 }
 
@@ -390,6 +414,9 @@ const styles = {
     justifyContent: "center",
     alignItems: "flex-start",
     pointerEvents: "none",
+    "@media (max-width: 600px)": {
+      display: "none",
+    },
   }),
   cluster: style(spacing.padding({ top: 4, bottom: 4, left: 2, right: 6 }), {
     position: "relative",
@@ -455,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,
@@ -45,7 +46,7 @@ export function ViewerApp(props: {
   const local = props.mode === "local";
   const documentRev =
     props.defaultRev ??
-    viewerDocument.changeRevs[0] ??
+    viewerDocument.changeCards[0]?.rev ??
     viewerDocument.references.find((ref) => ref.rev !== undefined)?.rev ??
     (local ? ALL : WORKING);
   const [panelRev, setPanelRev] = useState(documentRev);
@@ -58,9 +59,14 @@ export function ViewerApp(props: {
   const hasSourceDiffs =
     local ||
     viewerDocument.references.length > 0 ||
-    viewerDocument.changeRevs.length > 0 ||
+    viewerDocument.changeCards.length > 0 ||
     props.defaultRev !== undefined;
   const diffPanelOpen = hasSourceDiffs && showDiffPanel;
+  // The panel lists files in the order the rev's changes card asks them to be reviewed.
+  const panelReview =
+    viewerDocument.changeCards.find(
+      (card) => card.rev === panelRev && card.review.length > 0,
+    )?.review ?? NO_REVIEW;
   const body = useStyles(styles.body);
   const [shutDown, setShutDown] = useState(false);
   const parsedTitle =
@@ -82,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]);
@@ -108,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}>
@@ -150,6 +163,8 @@ export function ViewerApp(props: {
                   <TableOfContents
                     headings={viewerDocument.headings}
                     articleRef={articleRef}
+                    drawerOpen={tocDrawerOpen}
+                    onDrawerOpenChange={setTocDrawerOpen}
                   />
                 )}
               </div>
@@ -157,6 +172,7 @@ export function ViewerApp(props: {
             {diffPanelOpen && (
               <SourceDiffPanel
                 rev={panelRev}
+                review={panelReview}
                 onRevChange={
                   local
                     ? (rev) => {
@@ -177,6 +193,8 @@ export function ViewerApp(props: {
   );
 }
 
+const NO_REVIEW: string[] = [];
+
 function useViewerMeta(enabled: boolean) {
   const [meta, setMeta] = useState<ViewerMeta>();
   useEffect(() => {
@@ -265,6 +283,10 @@ const styles = {
     backgroundColor: backgroundColor.app,
     // Scrollport size for the sticky gutter rail (`100cqh`).
     containerType: "size",
+    "@media (max-width: 600px)": {
+      paddingInline: spacing.value(6),
+      paddingBlock: spacing.value(8),
+    },
   }),
   prose: style({
     display: "grid",
@@ -273,7 +295,10 @@ const styles = {
     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)`,
+      gridTemplateColumns: `var(--diffmap-toc-columns, minmax(${String(TOC_SIDE_MARGIN_PX)}px, 1fr) minmax(0, ${proseMaxWidth}) minmax(${String(TOC_SIDE_MARGIN_PX)}px, 1fr))`,
+    },
+    "@media (max-width: 600px)": {
+      "--diffmap-toc-columns": "0 minmax(0, 1fr) 0",
     },
   }),
   content: style({

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));
+}