@tanishqkancharla/diffmap 0.2.0 → 0.4.0

package/src/viewer/SourceDiffPanel.tsx

@@ -19,7 +19,7 @@ import {
   type SourceAnnotation,
   type SourceReference,
 } from "../annotations.js";
-import { changedFileItem, type Rev } from "../changes.js";
+import { changedFileItem, orderForReview, type Rev } from "../changes.js";
 import type { SourceDefinition } from "../definitions.js";
 import { useGistPin } from "../gist/pin.ts";
 import { useGitHubPin } from "../github/pin.ts";
@@ -46,6 +46,8 @@ type DefinitionNavigation = {
 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;
@@ -85,13 +87,14 @@ export function SourceDiffPanel(props: {
   const selection = props.selection;
   const reference = selection?.reference;
   const changes = useChanges(props.rev);
-  const items = useMemo(
-    () =>
-      changes === undefined || changes instanceof Error
-        ? []
-        : changes.files.flatMap((changed) => changedFileItem(changed) ?? []),
-    [changes],
-  );
+  const { review } = props;
+  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]);
   // A rev-less reference resolves against current files; a commit reference names its lines directly.
   const source = useSourceReference(
     reference?.kind === "file" && reference.rev === undefined
@@ -112,7 +115,8 @@ export function SourceDiffPanel(props: {
       ? navigation.status
       : source instanceof Error
         ? source.message
-        : changes instanceof Error
+        : // 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…"

package/src/viewer/TableOfContents.tsx

@@ -390,6 +390,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",

package/src/viewer/ViewerApp.tsx

@@ -45,7 +45,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 +58,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 =
@@ -157,6 +162,7 @@ export function ViewerApp(props: {
             {diffPanelOpen && (
               <SourceDiffPanel
                 rev={panelRev}
+                review={panelReview}
                 onRevChange={
                   local
                     ? (rev) => {
@@ -177,6 +183,8 @@ export function ViewerApp(props: {
   );
 }
 
+const NO_REVIEW: string[] = [];
+
 function useViewerMeta(enabled: boolean) {
   const [meta, setMeta] = useState<ViewerMeta>();
   useEffect(() => {
@@ -265,6 +273,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 +285,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/notes.tsx

@@ -0,0 +1,126 @@
+import type { ReactNode } from "react";
+import { Code, colors, focusRing, Tooltip } from "maui";
+import { style, useStyles } from "purse-styles";
+import type { SymbolMatch } from "../codeNotes.js";
+
+export type Token = {
+  content: string;
+  color?: string;
+  fontStyle?: number;
+  className?: string;
+};
+
+/** Splits tokens at symbol note boundaries and wraps each match in a tooltip. */
+export function NoteTokens(props: {
+  tokens: Token[];
+  matches: SymbolMatch[];
+  /** False inside a button, which cannot contain focusable elements. */
+  focusable?: boolean;
+}) {
+  const { tokens, matches } = props;
+  const symbolClassName = useStyles(symbolNoteClass);
+  const cuts = new Set(matches.flatMap((match) => [match.start, match.end]));
+  const pieces: { start: number; token: Token }[] = [];
+  let column = 0;
+  for (const token of tokens) {
+    let start = column;
+    for (let at = column + 1; at < column + token.content.length; at++) {
+      if (!cuts.has(at)) continue;
+      pieces.push({
+        start,
+        token: {
+          ...token,
+          content: token.content.slice(start - column, at - column),
+        },
+      });
+      start = at;
+    }
+    pieces.push({
+      start,
+      token: { ...token, content: token.content.slice(start - column) },
+    });
+    column += token.content.length;
+  }
+
+  const out: ReactNode[] = [];
+  let group: ReactNode[] = [];
+  for (const piece of pieces) {
+    const span = <TokenSpan key={piece.start} token={piece.token} />;
+    const match = matches.find(
+      (m) => piece.start >= m.start && piece.start < m.end,
+    );
+    if (match === undefined) {
+      out.push(span);
+      continue;
+    }
+    group.push(span);
+    if (piece.start + piece.token.content.length < match.end) continue;
+    out.push(
+      <Tooltip
+        key={`note-${match.start}`}
+        content={<NoteText text={match.note.text} />}
+      >
+        <span
+          className={symbolClassName}
+          tabIndex={props.focusable === false ? undefined : 0}
+        >
+          {group}
+        </span>
+      </Tooltip>,
+    );
+    group = [];
+  }
+  return <>{out}</>;
+}
+
+function TokenSpan(props: { token: Token }) {
+  const fontStyle = props.token.fontStyle ?? 0;
+  return (
+    <span
+      className={props.token.className}
+      style={{
+        color: props.token.color,
+        fontStyle: fontStyle & 1 ? "italic" : undefined,
+        fontWeight: fontStyle & 2 ? 500 : undefined,
+        textDecoration: fontStyle & 4 ? "underline" : undefined,
+      }}
+    >
+      {props.token.content}
+    </span>
+  );
+}
+
+/** Note text with `backtick` spans as inline code. */
+export function NoteText(props: { text: string }) {
+  return props.text
+    .split(/(`[^`]+`)/)
+    .map((part, index) =>
+      part.startsWith("`") && part.endsWith("`") && part.length > 1 ? (
+        <Code key={index}>{part.slice(1, -1)}</Code>
+      ) : (
+        part
+      ),
+    );
+}
+
+const symbolNoteClass = style(focusRing(), {
+  borderRadius: "3px",
+  cursor: "help",
+  textDecorationLine: "underline",
+  textDecorationStyle: "dotted",
+  textDecorationColor: colors.gray[9],
+  textUnderlineOffset: "3px",
+  "&:hover": { backgroundColor: colors.blueAlpha[5] },
+});
+
+/** A dot in the left gutter of the first row a line note covers. */
+export const lineNoteDot = {
+  content: '""',
+  position: "absolute",
+  left: "4px",
+  top: "calc(0.5lh - 2.5px)",
+  width: "5px",
+  height: "5px",
+  borderRadius: "50%",
+  backgroundColor: colors.blue[9],
+} as const;

package/src/viewer/serviceLayout.ts

@@ -0,0 +1,189 @@
+import ELK, {
+  type ElkExtendedEdge,
+  type ElkNode,
+} from "elkjs/lib/elk.bundled.js";
+import {
+  flattenServices,
+  type Service,
+  type ServiceDiagram,
+} from "../services.js";
+
+export type Point = { x: number; y: number };
+export type Rect = { x: number; y: number; width: number; height: number };
+export type Size = { width: number; height: number };
+
+/**
+ * One connection per pair of services that ever talk, pointing from the one
+ * declared first. Requests and replies share it, so the graph has no cycles
+ * and ELK never routes a reply around the whole diagram.
+ */
+export type ServiceLink = {
+  id: string;
+  a: string;
+  b: string;
+  /** Some event goes a → b. */
+  forward: boolean;
+  /** Some event goes b → a. */
+  backward: boolean;
+  /** The longest label on the link. */
+  label: string | undefined;
+};
+
+export type ServiceLayout = {
+  width: number;
+  height: number;
+  /** Each service's own header and state, measured before layout. */
+  sizes: Map<string, Size>;
+  boxes: Map<string, Rect>;
+  routes: Map<string, Point[]>;
+};
+
+export function serviceLinks(diagram: ServiceDiagram): ServiceLink[] {
+  const order = new Map(
+    flattenServices(diagram.services).map(({ service }, index) => [
+      service.name,
+      index,
+    ]),
+  );
+  const links = new Map<string, ServiceLink>();
+  for (const step of diagram.steps)
+    for (const event of step.events) {
+      const forward = order.get(event.from)! <= order.get(event.to)!;
+      const [a, b] = forward ? [event.from, event.to] : [event.to, event.from];
+      const id = linkId(a, b);
+      const link = links.get(id) ?? {
+        id,
+        a,
+        b,
+        forward: false,
+        backward: false,
+        label: undefined,
+      };
+      if (forward) link.forward = true;
+      else link.backward = true;
+      // Measure the pill as drawn: a linked event shows ↗.
+      const shown =
+        event.label !== "" && event.annotation !== undefined
+          ? `${event.label} ↗`
+          : event.label;
+      if (shown.length > (link.label?.length ?? 0)) link.label = shown;
+      links.set(id, link);
+    }
+  return [...links.values()];
+}
+
+export function linkId(from: string, to: string) {
+  return from < to ? `${from}|${to}` : `${to}|${from}`;
+}
+
+const elk = new ELK();
+
+function contains(service: Service, name: string): boolean {
+  return service.children.some(
+    (child) => child.name === name || contains(child, name),
+  );
+}
+
+/**
+ * `sizes` are each service's own header and state; a parent grows around its
+ * children. `label` is the largest event label, which must fit between layers.
+ */
+export async function layoutServices(input: {
+  diagram: ServiceDiagram;
+  links: ServiceLink[];
+  sizes: Map<string, Size>;
+  label: Size;
+  direction: "RIGHT" | "DOWN";
+}): Promise<ServiceLayout> {
+  // Room for a label pill on the edge between two layers. Each parent lays out
+  // its own children, so parents need it too.
+  const betweenLayers = String(
+    input.direction === "RIGHT"
+      ? Math.max(40, input.label.width + 24)
+      : Math.max(40, input.label.height + 28),
+  );
+  const node = (service: Service): ElkNode => {
+    const own = input.sizes.get(service.name)!;
+    if (service.children.length === 0)
+      return { id: service.name, width: own.width, height: own.height };
+    // A parent that talks to its own children needs room for that route and
+    // its label between its header and the children.
+    const inner = input.links.some(
+      (link) => link.a === service.name && contains(service, link.b),
+    );
+    const room = (size: number) => (inner ? size + 24 : 0);
+    const top =
+      own.height +
+      4 +
+      (input.direction === "DOWN" ? room(input.label.height) : 0);
+    const left =
+      16 + (input.direction === "RIGHT" ? room(input.label.width) : 0);
+    return {
+      id: service.name,
+      layoutOptions: {
+        "elk.padding": `[top=${top},left=${left},bottom=16,right=16]`,
+        "elk.nodeSize.constraints": "MINIMUM_SIZE",
+        "elk.layered.spacing.nodeNodeBetweenLayers": betweenLayers,
+        // Wide enough for its own header. ELK applies this before rotating
+        // a top-to-bottom layout, so the axes swap.
+        "elk.nodeSize.minimum":
+          input.direction === "DOWN" ? `(0,${own.width})` : `(${own.width},0)`,
+      },
+      children: service.children.map(node),
+    };
+  };
+  const graph: ElkNode = {
+    id: "root",
+    layoutOptions: {
+      "elk.algorithm": "layered",
+      "elk.direction": input.direction,
+      "elk.edgeRouting": "ORTHOGONAL",
+      "elk.hierarchyHandling": "INCLUDE_CHILDREN",
+      "elk.layered.considerModelOrder.strategy": "NODES_AND_EDGES",
+      "elk.json.edgeCoords": "ROOT",
+      "elk.json.shapeCoords": "ROOT",
+      "elk.padding": "[top=8,left=8,bottom=8,right=8]",
+      "elk.spacing.nodeNode": "32",
+      "elk.layered.spacing.nodeNodeBetweenLayers": betweenLayers,
+      "elk.spacing.edgeNode": "16",
+      "elk.spacing.edgeEdge": "12",
+    },
+    children: input.diagram.services.map(node),
+    edges: input.links.map((link): ElkExtendedEdge => ({
+      id: link.id,
+      sources: [link.a],
+      targets: [link.b],
+    })),
+  };
+  const result = await elk.layout(graph);
+
+  const boxes = new Map<string, Rect>();
+  const visit = (nodes: ElkNode[] | undefined) => {
+    for (const child of nodes ?? []) {
+      boxes.set(child.id, {
+        x: child.x!,
+        y: child.y!,
+        width: child.width!,
+        height: child.height!,
+      });
+      visit(child.children);
+    }
+  };
+  visit(result.children);
+  const routes = new Map(
+    (result.edges ?? []).map((edge) => {
+      const section = edge.sections![0]!;
+      return [
+        edge.id,
+        [section.startPoint, ...(section.bendPoints ?? []), section.endPoint],
+      ];
+    }),
+  );
+  return {
+    width: result.width!,
+    height: result.height!,
+    sizes: input.sizes,
+    boxes,
+    routes,
+  };
+}

package/vite.config.ts

@@ -26,6 +26,7 @@ export default defineConfig(({ command }) => {
         "purse-styles",
         "@pierre/diffs/react",
         "beautiful-mermaid",
+        "elkjs/lib/elk.bundled.js",
         "errore",
       ],
     },

package/vite.gist.config.ts

@@ -22,6 +22,7 @@ export function gistAppConfig(): UserConfig {
         "purse-styles",
         "@pierre/diffs/react",
         "beautiful-mermaid",
+        "elkjs/lib/elk.bundled.js",
         "errore",
         "md4x/standalone",
       ],