@shortlink-org/portolan 0.1.0

package/src/flow/prefs.test.ts

@@ -0,0 +1,80 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  SEQUENCE_MAX_STEPS,
+  defaultVariant,
+  readPrefs,
+  writePrefs,
+} from "./prefs";
+
+/** The node test environment has no localStorage; this is the whole of one. */
+function stubStorage(): Map<string, string> {
+  const store = new Map<string, string>();
+  vi.stubGlobal("localStorage", {
+    getItem: (key: string) => store.get(key) ?? null,
+    setItem: (key: string, value: string) => void store.set(key, value),
+    removeItem: (key: string) => void store.delete(key),
+  });
+  return store;
+}
+
+describe("defaultVariant", () => {
+  it("keeps a short flow as a sequence, where order is position", () => {
+    expect(defaultVariant(1)).toBe("sequence");
+    expect(defaultVariant(SEQUENCE_MAX_STEPS)).toBe("sequence");
+  });
+
+  it("folds a long flow onto the diagram, which fits on a screen", () => {
+    expect(defaultVariant(SEQUENCE_MAX_STEPS + 1)).toBe("diagram");
+    expect(defaultVariant(45)).toBe("diagram");
+  });
+});
+
+describe("readPrefs", () => {
+  beforeEach(() => {
+    stubStorage();
+  });
+
+  it("falls back to the caller's default when nothing was remembered", () => {
+    expect(readPrefs("checkout", "diagram")).toEqual({
+      variant: "diagram",
+      expanded: false,
+    });
+  });
+
+  it("remembers per flow rather than globally", () => {
+    writePrefs("checkout", { variant: "sequence", expanded: true });
+    expect(readPrefs("checkout", "diagram").variant).toBe("sequence");
+    expect(readPrefs("refund-requested", "diagram").variant).toBe("diagram");
+  });
+
+  it("ignores a stored value that is not a variant", () => {
+    localStorage.setItem(
+      "portolan.flow.checkout",
+      JSON.stringify({ variant: "isometric", expanded: true }),
+    );
+    const prefs = readPrefs("checkout", "sequence");
+    expect(prefs.variant).toBe("sequence");
+    // The half of the record that parsed is still honoured: one bad field is
+    // not a reason to forget the other one.
+    expect(prefs.expanded).toBe(true);
+  });
+
+  it("survives storage that is broken rather than merely empty", () => {
+    localStorage.setItem("portolan.flow.checkout", "{not json");
+    expect(readPrefs("checkout", "sequence")).toEqual({
+      variant: "sequence",
+      expanded: false,
+    });
+
+    vi.stubGlobal("localStorage", {
+      getItem: () => {
+        throw new Error("private mode");
+      },
+      setItem: () => {
+        throw new Error("private mode");
+      },
+    });
+    expect(readPrefs("checkout", "diagram").variant).toBe("diagram");
+    expect(() => writePrefs("checkout", { variant: "sequence", expanded: false })).not.toThrow();
+  });
+});

package/src/flow/prefs.ts

@@ -0,0 +1,104 @@
+// What the flow page remembers, per flow.
+//
+// Two settings, and both are per-flow rather than global on purpose. Which
+// variant reads better depends on how long the sequence is, and whether the
+// summary is worth two lines or ten depends on what the summary says — neither
+// is a statement about how this reader likes flow pages in general, so neither
+// belongs in a global preference.
+
+import { useCallback, useState } from "react";
+
+export type Variant = "diagram" | "sequence";
+
+/**
+ * Above this many steps a sequence rendered at a readable zoom is longer than
+ * any screen, and the diagram — which folds the same steps onto the lanes that
+ * repeat — is the one that fits. Below it the sequence is strictly better,
+ * because the order is the whole point of a flow and only the sequence draws
+ * order as position.
+ */
+export const SEQUENCE_MAX_STEPS = 12;
+
+export function defaultVariant(stepCount: number): Variant {
+  return stepCount > SEQUENCE_MAX_STEPS ? "diagram" : "sequence";
+}
+
+export interface FlowPrefs {
+  variant: Variant;
+  /** The summary is shown in full rather than clamped to two lines. */
+  expanded: boolean;
+}
+
+const key = (slug: string): string => `portolan.flow.${slug}`;
+
+/**
+ * localStorage, but a private-mode failure is not worth a crash: a preference
+ * that cannot be remembered is a preference that starts at its default.
+ */
+export function readPrefs(slug: string, fallback: Variant): FlowPrefs {
+  const defaults: FlowPrefs = { variant: fallback, expanded: false };
+  try {
+    const raw = localStorage.getItem(key(slug));
+    if (!raw) return defaults;
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) return defaults;
+    const value = parsed as Partial<FlowPrefs>;
+    return {
+      variant:
+        value.variant === "diagram" || value.variant === "sequence"
+          ? value.variant
+          : fallback,
+      expanded: value.expanded === true,
+    };
+  } catch {
+    return defaults;
+  }
+}
+
+export function writePrefs(slug: string, prefs: FlowPrefs): void {
+  try {
+    localStorage.setItem(key(slug), JSON.stringify(prefs));
+  } catch {
+    /* private mode: this session still switches, it just does not persist */
+  }
+}
+
+/**
+ * The remembered settings for one flow, and one setter for changing part of
+ * them. Re-reads when the slug changes, so walking from flow to flow picks up
+ * each one's own choice rather than carrying the last one along.
+ */
+export function useFlowPrefs(
+  slug: string,
+  stepCount: number,
+): [FlowPrefs, (patch: Partial<FlowPrefs>) => void] {
+  const fallback = defaultVariant(stepCount);
+  const [state, setState] = useState<{ slug: string; prefs: FlowPrefs }>(() => ({
+    slug,
+    prefs: readPrefs(slug, fallback),
+  }));
+
+  // Derived during render rather than in an effect: an effect would draw one
+  // frame of the previous flow's settings before correcting itself, and on
+  // this page that frame is a whole re-layout of the canvas.
+  const prefs =
+    state.slug === slug ? state.prefs : readPrefs(slug, defaultVariant(stepCount));
+  if (state.slug !== slug) setState({ slug, prefs });
+
+  const update = useCallback(
+    (patch: Partial<FlowPrefs>) => {
+      setState((current) => {
+        const base =
+          current.slug === slug
+            ? current.prefs
+            : readPrefs(slug, defaultVariant(stepCount));
+        const next = { ...base, ...patch };
+        writePrefs(slug, next);
+        return { slug, prefs: next };
+      });
+    },
+    [slug, stepCount],
+  );
+
+  return [prefs, update];
+}

package/src/graph/DependencyGraph.tsx

@@ -0,0 +1,283 @@
+// The dependency graph, drawn.
+//
+// Events are nodes here, not edge labels. The old canvas wrote an event's name
+// once per consumer and hung it on a line, so the sample's nine events became
+// twenty-one pieces of text lying across the densest part of the picture. A
+// pill written once, with bare lines into and out of it, says the same thing
+// with a third of the ink and gives the reader something to click.
+//
+// Everything geometric is elk's: the positions AND the routes. Nothing here
+// invents a curve.
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useNavigate } from "react-router";
+import {
+  Background,
+  MiniMap,
+  ReactFlow,
+  ReactFlowProvider,
+  useStore,
+} from "@xyflow/react";
+import type { Edge, Node } from "@xyflow/react";
+import "@xyflow/react/dist/style.css";
+import { DiagramSkeleton } from "../components/DiagramSkeleton";
+import { contextVar } from "../lib/context-color";
+import type { EventGraph } from "../lib/event-graph";
+import { bundles } from "../lib/event-graph";
+import { servicePath } from "../routes";
+import { useSelectionStore } from "../selection/store";
+import { dependencyNodeTypes, TinyZoom } from "./DependencyNodes";
+import type { DependencyNode } from "./DependencyNodes";
+import { catalogIdOf, EVENT_NODE, layoutDependencyGraph } from "./dependency-layout";
+import type { GraphMode, Layout } from "./dependency-layout";
+import { dependencyEdgeTypes } from "./RoutedEdge";
+import { FIT_OPTIONS, GraphToolbar } from "./GraphToolbar";
+import { EDGE_W, EDGE_W_LIT, LEGIBLE_ZOOM } from "./theme";
+
+/** How far out of the way everything more than one hop from the subject goes. */
+const DIM_EDGE = 0.1;
+const DIM_NODE = 0.2;
+
+/** Past this many boxes the canvas is bigger than the frame; below it, it is not. */
+const MINIMAP_FROM = 12;
+
+export interface DependencyGraphProps {
+  graph: EventGraph;
+  mode: GraphMode;
+  onMode: (mode: GraphMode) => void;
+  /**
+   * Changes whenever the filters do. Remounting the flow on a new value is
+   * what makes fitView measure the layout that just arrived rather than the
+   * one it replaced.
+   */
+  fitKey: string;
+}
+
+export function DependencyGraph({
+  graph,
+  mode,
+  onMode,
+  fitKey,
+}: DependencyGraphProps) {
+  const navigate = useNavigate();
+  const [layout, setLayout] = useState<Layout | null>(null);
+  const [focusing, setFocusing] = useState(false);
+  const [focused, setFocused] = useState<string | null>(null);
+
+  const selectionId = useSelectionStore((s) => s.selection?.id ?? null);
+  const select = useSelectionStore((s) => s.select);
+  const clear = useSelectionStore((s) => s.clear);
+
+  // Below the legible zoom an 11px label is a smudge, so pills give up their
+  // name and keep their icon. A boolean, not the zoom: a pinch that stays on
+  // one side of the threshold re-renders nothing.
+  const tiny = useStore((s) => s.transform[2] < LEGIBLE_ZOOM);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLayout(null);
+    void layoutDependencyGraph(graph, mode).then((next) => {
+      if (!cancelled) setLayout(next);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [graph, mode]);
+
+  // --- focus -------------------------------------------------------------
+
+  // Esc unwinds the innermost thing first. It is caught on the way DOWN so it
+  // gets ahead of the shell's "Esc clears the selection": a reader who has
+  // dimmed the canvas means the dimming when they press it.
+  useEffect(() => {
+    if (!focused) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Escape" || e.defaultPrevented) return;
+      e.preventDefault();
+      setFocused(null);
+    };
+    window.addEventListener("keydown", onKey, true);
+    return () => window.removeEventListener("keydown", onKey, true);
+  }, [focused]);
+
+  /**
+   * One hop, in the sense a reader means it.
+   *
+   * In events mode the graph is literally bipartite, so one hop from a service
+   * reaches only pills - focusing would dim every other service to nothing and
+   * answer no question at all. The hop that is being counted is the dependency:
+   * this service, the events on either side of it, and whoever is at the far
+   * end of those events.
+   */
+  const neighbourhood = useMemo(() => {
+    if (!focused) return null;
+    const nodes = new Set<string>([focused]);
+    const edges = new Set<string>();
+    if (mode === "compact") {
+      for (const bundle of bundles(graph)) {
+        if (bundle.from !== focused && bundle.to !== focused) continue;
+        nodes.add(bundle.from);
+        nodes.add(bundle.to);
+        edges.add(bundle.id);
+      }
+      return { nodes, edges };
+    }
+    for (const event of graph.events) {
+      const touches =
+        event.publisher === focused ||
+        event.consumers.some((c) => c.service === focused);
+      if (!touches) continue;
+      nodes.add(EVENT_NODE(event.id));
+      nodes.add(event.publisher);
+      edges.add(`pub:${event.id}`);
+      for (const consumer of event.consumers) {
+        if (consumer.self) continue;
+        nodes.add(consumer.service);
+        edges.add(`con:${event.id}->${consumer.service}`);
+      }
+    }
+    return { nodes, edges };
+  }, [focused, graph, mode]);
+
+  // --- what actually gets handed to React Flow ---------------------------
+
+  const nodes: DependencyNode[] = useMemo(() => {
+    const built = layout?.nodes ?? [];
+    return built.map((node) => ({
+      ...node,
+      selected:
+        node.id === selectionId ||
+        (node.type === "event" && node.id === EVENT_NODE(selectionId ?? "")),
+      style: {
+        ...node.style,
+        opacity:
+          neighbourhood && !neighbourhood.nodes.has(node.id) ? DIM_NODE : 1,
+      },
+    }));
+  }, [layout, selectionId, neighbourhood]);
+
+  const edges: Edge[] = useMemo(() => {
+    const built = layout?.edges ?? [];
+    return built.map((edge) => {
+      const dimmed = neighbourhood ? !neighbourhood.edges.has(edge.id) : false;
+      // A selected event lights the lines that carry it. Selection thickens;
+      // focus dims. They are different questions and they read differently.
+      const lit =
+        selectionId !== null &&
+        (edge.data?.["eventId"] === selectionId ||
+          edge.data?.["bundleId"] === selectionId);
+      return {
+        ...edge,
+        selected: edge.id === selectionId,
+        style: {
+          ...edge.style,
+          opacity: dimmed ? DIM_EDGE : 1,
+          strokeWidth: lit ? EDGE_W_LIT : (edge.style?.strokeWidth ?? EDGE_W),
+        },
+        zIndex: lit ? 10 : 0,
+      };
+    });
+  }, [layout, neighbourhood, selectionId]);
+
+  // --- interaction -------------------------------------------------------
+
+  const onNodeClick = useCallback(
+    (_: React.MouseEvent, node: Node) => {
+      if (focusing && node.type === "service") setFocused(node.id);
+      select(catalogIdOf(node.id), "diagram");
+    },
+    [focusing, select],
+  );
+
+  const onNodeDoubleClick = useCallback(
+    (_: React.MouseEvent, node: Node) => {
+      if (node.type !== "service") return;
+      const to = servicePath(node.id);
+      if (to) navigate(to);
+    },
+    [navigate],
+  );
+
+  const onEdgeClick = useCallback(
+    (_: React.MouseEvent, edge: Edge) => {
+      const bundleId = edge.data?.["bundleId"];
+      if (typeof bundleId === "string") {
+        select(bundleId, "diagram");
+        return;
+      }
+      const eventId = edge.data?.["eventId"];
+      if (typeof eventId === "string") select(eventId, "diagram");
+    },
+    [select],
+  );
+
+  const ready = layout !== null;
+  const minimap = nodes.length > MINIMAP_FROM;
+
+  return (
+    /* The box is the box whether elk has answered or not: the skeleton is
+       laid over it, never in place of it, so nothing reflows on arrival. */
+    <div className="relative h-full w-full">
+      {ready ? null : <DiagramSkeleton />}
+      <TinyZoom.Provider value={tiny}>
+        <ReactFlow
+          nodes={nodes}
+          edges={edges}
+          nodeTypes={dependencyNodeTypes}
+          edgeTypes={dependencyEdgeTypes}
+          onNodeClick={onNodeClick}
+          onNodeDoubleClick={onNodeDoubleClick}
+          onEdgeClick={onEdgeClick}
+          onPaneClick={() => {
+            setFocused(null);
+            clear("diagram");
+          }}
+          nodesDraggable={false}
+          nodesConnectable={false}
+          elementsSelectable
+          proOptions={{ hideAttribution: true }}
+          fitView
+          fitViewOptions={FIT_OPTIONS}
+          minZoom={0.08}
+          maxZoom={2}
+          key={ready ? `fit-${fitKey}-${nodes.length}-${edges.length}` : "pending"}
+        >
+          <Background gap={20} size={2} />
+          <GraphToolbar
+            mode={mode}
+            onMode={onMode}
+            focusing={focusing}
+            onFocusing={(on) => {
+              setFocusing(on);
+              if (!on) setFocused(null);
+            }}
+            focused={focused}
+          />
+          {minimap ? (
+            <MiniMap
+              position="bottom-right"
+              pannable
+              zoomable
+              ariaLabel="Graph overview"
+              nodeBorderRadius={4}
+              nodeColor={(node) =>
+                contextVar(
+                  (node.data as { context?: string | null }).context ?? null,
+                )
+              }
+              nodeStrokeWidth={0}
+            />
+          ) : null}
+        </ReactFlow>
+      </TinyZoom.Provider>
+    </div>
+  );
+}
+
+export function DependencyGraphPane(props: DependencyGraphProps) {
+  return (
+    <ReactFlowProvider>
+      <DependencyGraph {...props} />
+    </ReactFlowProvider>
+  );
+}

package/src/graph/DependencyNodes.tsx

@@ -0,0 +1,162 @@
+// The dependency graph's two node kinds.
+//
+// A service is a card and an event is a pill, and the difference in
+// silhouette is doing most of the work: a reader scanning the canvas can tell
+// which of the two rows they are looking at without reading a word of either.
+
+import { createContext, useContext } from "react";
+import { Handle, Position } from "@xyflow/react";
+import type { Node, NodeProps } from "@xyflow/react";
+import { Server, Zap } from "lucide-react";
+import { contextVar } from "../lib/context-color";
+import { EVENT_ICON_W } from "./theme";
+
+/**
+ * True when the viewport is zoomed out past the point where an 11px label is
+ * a word. It is a context rather than node data so that crossing the threshold
+ * re-renders the pills without rebuilding every node object - and it is a
+ * boolean rather than the zoom, so a pinch that stays on one side of the line
+ * costs nothing at all.
+ */
+export const TinyZoom = createContext(false);
+
+export interface ServiceNodeData {
+  kind: "service";
+  label: string;
+  context: string | null;
+  ghost: boolean;
+  publishes: number;
+  consumes: number;
+  [key: string]: unknown;
+}
+
+export interface EventNodeData {
+  kind: "event";
+  label: string;
+  /** the publishing service's context; the pill borrows its colour */
+  context: string | null;
+  eventId: string;
+  publisher: string;
+  /** the publisher consumes it too */
+  self: boolean;
+  [key: string]: unknown;
+}
+
+export type ServiceNodeType = Node<ServiceNodeData, "service">;
+export type EventNodeType = Node<EventNodeData, "event">;
+export type DependencyNode = ServiceNodeType | EventNodeType;
+
+const HANDLE = { opacity: 0, width: 1, height: 1 } as const;
+
+export function ServiceNode({ data }: NodeProps<ServiceNodeType>) {
+  const accent = data.ghost ? "var(--status-unresolved)" : contextVar(data.context);
+
+  return (
+    <div
+      className={`flex h-full w-full items-center gap-2 px-2.5 ${
+        data.ghost ? "flow-card-ghost" : "flow-card"
+      }`}
+      style={{ color: data.ghost ? "var(--status-unresolved)" : "var(--fg)" }}
+      title={data.ghost ? `${data.label} — not in the catalog` : data.label}
+    >
+      <span className="flow-tile" style={{ color: accent }}>
+        <Server size={12} aria-hidden />
+      </span>
+      <div className="flex min-w-0 flex-1 flex-col justify-center gap-0.5">
+        <span className="mono truncate" style={{ fontSize: 11, lineHeight: 1.3 }}>
+          {data.label}
+        </span>
+        {data.ghost ? (
+          <span className="truncate" style={{ fontSize: 10, opacity: 0.8 }}>
+            not in catalog
+          </span>
+        ) : (
+          /* Two numbers, one line: what it emits and what it listens to. The
+             arrows carry the direction so the words do not have to shout it. */
+          <span
+            className="tnum truncate text-muted"
+            style={{ fontSize: 10, lineHeight: 1.4 }}
+          >
+            ↑{data.publishes} publishes · ↓{data.consumes} consumes
+          </span>
+        )}
+      </div>
+      <Handle type="target" position={Position.Left} style={HANDLE} />
+      <Handle type="source" position={Position.Right} style={HANDLE} />
+    </div>
+  );
+}
+
+/**
+ * The pill. A tinted badge in the publisher's colour, the way a status badge
+ * is tinted: the tint is the context, the bolt is the kind, and neither needs
+ * a border to say so. Selection draws its own ring here because the pill is
+ * not the shape of its box - see the rule on `.react-flow__node.selected`.
+ */
+export function EventNode({ data, selected }: NodeProps<EventNodeType>) {
+  const accent = contextVar(data.context);
+  const tiny = useContext(TinyZoom);
+
+  return (
+    <div className="flex h-full w-full items-center">
+      <div
+        className="flex h-full items-center gap-1.5 overflow-hidden px-2"
+        style={{
+          width: tiny ? EVENT_ICON_W : "100%",
+          background: `color-mix(in srgb, ${accent} 10%, var(--flow-card))`,
+          // A pill, not a box: the shape is the kind.
+          borderRadius: 999,
+          boxShadow: selected ? "var(--ring)" : "var(--shadow-card)",
+          justifyContent: tiny ? "center" : undefined,
+          paddingInline: tiny ? 0 : undefined,
+          transition: "box-shadow var(--dur-micro) var(--ease-out)",
+        }}
+        title={
+          data.self
+            ? `${data.label} — published and consumed by ${data.publisher}`
+            : `${data.label} — published by ${data.publisher}`
+        }
+      >
+        <Zap
+          size={11}
+          aria-hidden
+          className="shrink-0"
+          style={{ color: accent }}
+          fill="currentColor"
+        />
+        {tiny ? null : (
+          <>
+            <span
+              className="mono truncate"
+              style={{ fontSize: 11, lineHeight: 1.2, color: "var(--fg)" }}
+            >
+              {data.label}
+            </span>
+            {/* A service listening to its own event is a fact about the pill,
+                not a line: a loop edge would have to circle the node it leaves
+                and arrives at, and there is nothing between the two ends of it
+                for a reader to follow. */}
+            {data.self ? (
+              <span
+                className="ml-auto shrink-0 rounded-full px-1.5"
+                style={{
+                  fontSize: 9,
+                  lineHeight: "14px",
+                  fontWeight: 600,
+                  background: `color-mix(in srgb, ${accent} 16%, transparent)`,
+                  color: accent,
+                }}
+              >
+                self
+              </span>
+            ) : null}
+          </>
+        )}
+      </div>
+      <Handle type="target" position={Position.Left} style={HANDLE} />
+      <Handle type="source" position={Position.Right} style={HANDLE} />
+    </div>
+  );
+}
+
+export const dependencyNodeTypes = { service: ServiceNode, event: EventNode };

package/src/graph/EdgeLabel.tsx

@@ -0,0 +1,61 @@
+// The pill that sits on a line.
+//
+// A word printed straight onto a line is a word with a line through it, so
+// the label carries a surface of its own - the card colour and the card's
+// ring - and lives in React Flow's label layer, which is above the nodes: on
+// a short line between two neighbours the pill is wider than the gap, and a
+// pill laid over a corner beats half a pill. The bundled edges of the
+// dependency graph and the relation labels of the context map both draw this
+// one; they used to draw two copies of it.
+
+import { EdgeLabelRenderer } from "@xyflow/react";
+import type { CSSProperties, ReactNode } from "react";
+import type { Point } from "./elk";
+
+export function EdgeLabel({
+  at,
+  opacity,
+  title,
+  onClick,
+  children,
+}: {
+  at: Point;
+  /** Follows the line's own opacity, so a dimmed line cannot have a lit label. */
+  opacity: number;
+  title?: string | undefined;
+  /** When given the pill is a button and takes the pointer; otherwise it lets clicks through to the line. */
+  onClick?: (() => void) | undefined;
+  children: ReactNode;
+}) {
+  const style: CSSProperties = {
+    position: "absolute",
+    transform: `translate(-50%, -50%) translate(${at.x}px, ${at.y}px)`,
+    background: "var(--flow-card)",
+    color: "var(--fg-muted)",
+    boxShadow: "var(--shadow-card)",
+    borderRadius: 999,
+    padding: "0 6px",
+    fontSize: 10,
+    lineHeight: "16px",
+    whiteSpace: "nowrap",
+    opacity,
+    zIndex: 5,
+    pointerEvents: onClick ? "all" : "none",
+    cursor: onClick ? "pointer" : undefined,
+  };
+  const className = "mono nodrag nopan tnum";
+
+  return (
+    <EdgeLabelRenderer>
+      {onClick ? (
+        <button type="button" onClick={onClick} className={className} title={title} style={style}>
+          {children}
+        </button>
+      ) : (
+        <div className={className} title={title} style={style}>
+          {children}
+        </div>
+      )}
+    </EdgeLabelRenderer>
+  );
+}