@shortlink-org/portolan 0.1.0

package/src/likec4/levels.tsx

@@ -0,0 +1,70 @@
+// The C4 levels, in one vocabulary.
+//
+// Three pictures, three scopes, and a reader who has to be told which one they
+// are looking at — a box called "Payments" is a system on one page and a
+// container on the next, and the only thing that says which is the level.
+//
+// The levels are not a menu of everything LikeC4 could draw. They are the
+// scopes the catalog actually holds facts about: the estate and what stands
+// outside it, the containers of one context, and the parts of one service.
+// There is no level 4 here, because code is what the repository is for.
+
+import type { ReactNode } from "react";
+
+export type C4Level = 1 | 2 | 3;
+
+export const C4_LEVEL: Record<C4Level, { name: string; note: string }> = {
+  1: {
+    name: "system context",
+    note: "every bounded context, and everything outside the estate that touches one",
+  },
+  2: {
+    name: "containers",
+    note: "services, the stores they keep their state in, and the brokers between them",
+  },
+  3: {
+    name: "components",
+    note: "the aggregates inside one service, and where each is persisted",
+  },
+};
+
+/** Says which level a canvas is drawn at, for a page that only draws one. */
+export function LevelBadge({ level }: { level: C4Level }) {
+  return (
+    <span className="mono text-muted" title={C4_LEVEL[level].note}>
+      C4 L{level} · {C4_LEVEL[level].name}
+    </span>
+  );
+}
+
+/**
+ * Steps between the levels one page can draw. A segmented control rather than
+ * tabs: the picture underneath stays where it is, and only its scope changes.
+ */
+export function LevelSwitch({
+  levels,
+  level,
+  onLevel,
+}: {
+  /** The levels this page offers, with the word each one goes by here. */
+  levels: { level: C4Level; label: ReactNode }[];
+  level: C4Level;
+  onLevel: (level: C4Level) => void;
+}) {
+  return (
+    <div className="seg">
+      {levels.map((option) => (
+        <button
+          key={option.level}
+          type="button"
+          onClick={() => onLevel(option.level)}
+          aria-pressed={option.level === level}
+          title={C4_LEVEL[option.level].note}
+          className={option.level === level ? "is-on" : ""}
+        >
+          L{option.level} {option.label}
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/likec4/mapping.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { catalog } from "../data";
+import { classify } from "../selection/model";
+import { fqn, participantFqn } from "./ids";
+import { catalogIdMap, catalogIdOf } from "./mapping";
+
+describe("catalogIdOf", () => {
+  /**
+   * The ID contract, checked rather than assumed: every catalog id must survive
+   * the round trip through the LikeC4 identifier the generator emits for it.
+   */
+  it("inverts fqn for every element the generator emits", () => {
+    const ids: string[] = [];
+    for (const context of catalog.contexts) {
+      ids.push(context.id);
+      for (const service of context.services) {
+        ids.push(service.id);
+        for (const aggregate of service.aggregates) {
+          ids.push(aggregate.id);
+          for (const event of aggregate.events) ids.push(event.id);
+        }
+      }
+    }
+    for (const flow of catalog.flows) {
+      for (const participant of flow.participants) ids.push(participant.id);
+    }
+
+    for (const id of ids) {
+      expect(catalogIdOf(fqn(id)), id).toBe(id);
+    }
+  });
+
+  it("undoes the substitution LikeC4 identifiers force", () => {
+    // "ledger-pg" cannot be a LikeC4 identifier; "ledger_pg" can.
+    expect(fqn("ledger-pg")).toBe("ledger_pg");
+    expect(catalogIdOf("ledger_pg")).toBe("ledger-pg");
+    expect(catalogIdOf("shop.pricing.price_list")).toBe(
+      "shop.pricing.price-list",
+    );
+  });
+
+  it("maps a dotted root participant using the identifier the generator declares", () => {
+    const participant = {
+      id: "river.order-jobs",
+      kind: "broker" as const,
+      context: null,
+    };
+    const fixture = {
+      ...catalog,
+      flows: [
+        {
+          ...catalog.flows[0]!,
+          participants: [...catalog.flows[0]!.participants, participant],
+        },
+        ...catalog.flows.slice(1),
+      ],
+    };
+
+    expect(catalogIdMap(fixture).get(participantFqn(participant))).toBe(participant.id);
+  });
+
+  it("hands back an id it has never seen, so the click still lands", () => {
+    expect(catalogIdOf("nothing_here")).toBe("nothing_here");
+    expect(classify(catalogIdOf("nothing_here"))).toBe("unknown");
+  });
+});

package/src/likec4/mapping.ts

@@ -0,0 +1,54 @@
+// The inverse of ids.ts.
+//
+// Going out, a catalog id becomes a LikeC4 identifier by replacing whatever
+// LikeC4 will not accept. Coming back — from a clicked node to the thing it
+// stands for — that substitution has to be undone, and the only honest way to
+// undo it is to remember which catalog id produced which identifier.
+
+import { catalog } from "../data";
+import type { Catalog } from "../catalog";
+import { fqn, participantFqn } from "./ids";
+
+export function catalogIdMap(catalog: Catalog): Map<string, string> {
+  const result = new Map<string, string>();
+  const remember = (id: string): void => {
+    const likec4 = fqn(id);
+    // First writer wins: two catalog ids that collapse to one identifier would
+    // be a modelling bug, and silently reassigning would hide it.
+    if (!result.has(likec4)) result.set(likec4, id);
+  };
+
+  for (const context of catalog.contexts) {
+    remember(context.id);
+    for (const service of context.services) {
+      remember(service.id);
+      for (const aggregate of service.aggregates) {
+        remember(aggregate.id);
+        for (const event of aggregate.events) remember(event.id);
+      }
+    }
+  }
+  // A store is a container inside the service that owns it, and clicking one
+  // should open the schema rather than nothing.
+  for (const store of catalog.stores ?? []) remember(store.id);
+  // Brokers, actors and externals are model elements too, and a flow lane is
+  // the most likely thing on screen to be clicked.
+  for (const flow of catalog.flows) {
+    for (const participant of flow.participants) {
+      const likec4 = participantFqn(participant);
+      if (!result.has(likec4)) result.set(likec4, participant.id);
+    }
+  }
+
+  return result;
+}
+
+const toCatalogId = catalogIdMap(catalog);
+
+/**
+ * The catalog id a LikeC4 element id stands for, or the id unchanged when the
+ * model holds something the catalog does not — an external participant, say.
+ */
+export function catalogIdOf(likec4Id: string): string {
+  return toCatalogId.get(likec4Id) ?? likec4Id;
+}

package/src/likec4/reserved.json

@@ -0,0 +1,141 @@
+[
+  "BottomTop",
+  "LeftRight",
+  "RightLeft",
+  "TopBottom",
+  "alt",
+  "amber",
+  "and",
+  "autoLayout",
+  "blue",
+  "border",
+  "bottom",
+  "break",
+  "browser",
+  "bucket",
+  "catch",
+  "color",
+  "component",
+  "crow",
+  "cylinder",
+  "dashed",
+  "deployment",
+  "deploymentNode",
+  "description",
+  "diagram",
+  "diamond",
+  "document",
+  "dot",
+  "dotted",
+  "dynamic",
+  "dynamicPredicateGroup",
+  "element",
+  "else",
+  "exclude",
+  "extend",
+  "extends",
+  "finally",
+  "from",
+  "global",
+  "gray",
+  "green",
+  "group",
+  "head",
+  "icon",
+  "iconColor",
+  "iconPosition",
+  "iconSize",
+  "icons",
+  "if",
+  "import",
+  "include",
+  "includeAncestors",
+  "indigo",
+  "instance",
+  "instanceOf",
+  "is",
+  "kind",
+  "large",
+  "left",
+  "lg",
+  "likec4lib",
+  "line",
+  "link",
+  "loop",
+  "max",
+  "md",
+  "medium",
+  "metadata",
+  "min",
+  "mobile",
+  "model",
+  "multiple",
+  "muted",
+  "navigateTo",
+  "node",
+  "none",
+  "normal",
+  "not",
+  "notation",
+  "notes",
+  "odiamond",
+  "odot",
+  "of",
+  "onormal",
+  "opacity",
+  "open",
+  "opt",
+  "or",
+  "order",
+  "padding",
+  "par",
+  "parallel",
+  "person",
+  "predicate",
+  "predicateGroup",
+  "primary",
+  "queue",
+  "rank",
+  "rectangle",
+  "red",
+  "relationship",
+  "rgb",
+  "rgba",
+  "right",
+  "same",
+  "secondary",
+  "sequence",
+  "shape",
+  "sink",
+  "size",
+  "sky",
+  "slate",
+  "sm",
+  "small",
+  "solid",
+  "source",
+  "specification",
+  "storage",
+  "style",
+  "styleGroup",
+  "summary",
+  "tag",
+  "tail",
+  "target",
+  "technology",
+  "textSize",
+  "title",
+  "top",
+  "try",
+  "variant",
+  "vee",
+  "view",
+  "views",
+  "when",
+  "where",
+  "with",
+  "xl",
+  "xlarge",
+  "xs",
+  "xsmall"
+]

package/src/likec4/view-index.ts

@@ -0,0 +1,78 @@
+// What a generated view actually contains.
+//
+// Highlighting has to know two things before it touches the canvas: whether the
+// view on screen holds the selected element at all, and — for flows — which
+// edge draws which step. Both are answered from the generated model, so neither
+// costs a render and neither can drift from what LikeC4 will draw.
+
+import { pickViewBounds } from "likec4/react";
+import { likec4model } from "./generated";
+import type { Flow } from "../catalog";
+import { drawnStepIds, pairEdgesToSteps } from "./flow-edges";
+import type { EdgeStepPairing } from "./flow-edges";
+import { EMPTY_PAIRING } from "./flow-edges";
+import { flowCrossViewId, flowViewId } from "./ids";
+import type { BBox } from "./canvas-viewport";
+
+interface ViewShape {
+  nodeIds: Set<string>;
+  edgeIds: string[];
+}
+
+const shapes = new Map<string, ViewShape>();
+
+function shapeOf(viewId: string): ViewShape {
+  const cached = shapes.get(viewId);
+  if (cached) return cached;
+  const view = likec4model.findView(viewId)?.$layouted;
+  const shape: ViewShape = view
+    ? {
+        nodeIds: new Set(view.nodes.map((n) => String(n.id))),
+        edgeIds: view.edges.map((e) => String(e.id)),
+      }
+    : { nodeIds: new Set(), edgeIds: [] };
+  shapes.set(viewId, shape);
+  return shape;
+}
+
+/** True when the view draws a node with this LikeC4 element id. */
+export function viewHasNode(viewId: string, likec4Id: string): boolean {
+  return shapeOf(viewId).nodeIds.has(likec4Id);
+}
+
+/** The node ids a view draws, in LikeC4 model order. */
+export function viewNodeIds(viewId: string): readonly string[] {
+  return [...shapeOf(viewId).nodeIds];
+}
+
+/** The edge ids a view draws, in the order LikeC4 emits them. */
+export function viewEdgeIds(viewId: string): readonly string[] {
+  return shapeOf(viewId).edgeIds;
+}
+
+/**
+ * How big the picture is, in the units the viewport is set in. The two
+ * variants of a dynamic view are laid out separately and have different
+ * bounds, so the variant on screen has to be the one asked about.
+ */
+export function viewBounds(
+  viewId: string,
+  variant: "diagram" | "sequence",
+): BBox | null {
+  const view = likec4model.findView(viewId)?.$layouted;
+  return view ? pickViewBounds(view, variant) : null;
+}
+
+const pairings = new Map<string, EdgeStepPairing>();
+
+/** Edge-to-step pairing for one of a flow's two views. */
+export function flowPairing(flow: Flow, crossOnly: boolean): EdgeStepPairing {
+  const viewId = crossOnly ? flowCrossViewId(flow) : flowViewId(flow);
+  const cached = pairings.get(viewId);
+  if (cached) return cached;
+  const pairing = shapeOf(viewId).edgeIds.length
+    ? pairEdgesToSteps(shapeOf(viewId).edgeIds, drawnStepIds(flow, crossOnly))
+    : EMPTY_PAIRING;
+  pairings.set(viewId, pairing);
+  return pairing;
+}

package/src/main.tsx

@@ -0,0 +1,13 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import "./index.css";
+import { App } from "./app/App";
+
+const container = document.getElementById("root");
+if (!container) throw new Error("#root is missing from index.html");
+
+createRoot(container).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/src/map/ContextMapGraph.tsx

@@ -0,0 +1,274 @@
+// The map, drawn.
+//
+// ONE LINE PER RELATIONSHIP, which is what a context map is and what every
+// other graph in this app is not. The dependency graph draws an arrow per
+// event because an event is the thing it is about; here the thing is the
+// relationship, and a pair that leans on each other both ways is not two
+// facts - it is one fact called a partnership. Two arcs between the same two
+// boxes would also force a layered layout to route one of them backwards
+// around the whole diagram, which is how a map of three domains ends up
+// looking like a circuit.
+//
+// So: the arrowheads say which way the leaning runs - one head for a customer
+// and its supplier, two for a partnership, none for a pair that shares a type
+// and nothing else - and the label says which pattern that makes, in the same
+// word the list below uses. The dash is the app's usual three markers, worst
+// status among everything the line carries: a relationship is known no better
+// than its least-known hop.
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useNavigate } from "react-router";
+import {
+  Background,
+  MarkerType,
+  Panel,
+  ReactFlow,
+  ReactFlowProvider,
+} from "@xyflow/react";
+import type { Edge, Node } from "@xyflow/react";
+import "@xyflow/react/dist/style.css";
+import type { Catalog, Status } from "../catalog";
+import { DiagramSkeleton } from "../components/DiagramSkeleton";
+import { layoutWithElk } from "../graph/elk";
+import { ExportSeg } from "../graph/GraphToolbar";
+import { EDGE_W, statusColor, statusDash } from "../graph/theme";
+import type { PortolanNode } from "../graph/nodes";
+import { PATTERN_LABEL } from "../lib/context-map";
+import type { ContextRelation } from "../lib/context-map";
+import { paths } from "../routes";
+import { useSelectionStore } from "../selection/store";
+import { CTX_NODE_H, CTX_NODE_W, contextNodeTypes } from "./ContextNode";
+import { mapEdgeTypes } from "./FloatingEdge";
+
+const DIM = 0.14;
+
+/** A chain is known no better than its least-known hop. */
+function worstStatus(statuses: readonly Status[]): Status {
+  if (statuses.includes("unresolved")) return "unresolved";
+  if (statuses.includes("declared")) return "declared";
+  return "verified";
+}
+
+/** The counted pattern the line stands for; the read ones are for the list. */
+function lineLabel(relation: ContextRelation): string {
+  const counted = relation.patterns.find((p) => p.basis === "counted");
+  return counted ? PATTERN_LABEL[counted.name] : "";
+}
+
+interface Drawn {
+  nodes: PortolanNode[];
+  edges: Edge[];
+  ready: boolean;
+}
+
+export function ContextMapGraph({
+  catalog,
+  relations,
+}: {
+  catalog: Catalog;
+  relations: readonly ContextRelation[];
+}) {
+  const navigate = useNavigate();
+  const selectionId = useSelectionStore((s) => s.selection?.id ?? null);
+  const select = useSelectionStore((s) => s.select);
+  const clear = useSelectionStore((s) => s.clear);
+  const [drawn, setDrawn] = useState<Drawn>({
+    nodes: [],
+    edges: [],
+    ready: false,
+  });
+
+  // One entry per pair the catalog has anything to say about. `back` is what
+  // turns an arrow into a double-headed one; elk only ever sees a -> b, so the
+  // layout never has a cycle to route around.
+  const lines = useMemo(
+    () =>
+      relations
+        .filter((r) => r.dependencies.length > 0 || r.shared.length > 0)
+        .map((relation) => {
+          const forward = relation.dependencies.find(
+            (d) => d.upstream === relation.a,
+          );
+          const back = relation.dependencies.find(
+            (d) => d.upstream === relation.b,
+          );
+          const links = relation.dependencies.flatMap((d) => d.links);
+          return {
+            relation,
+            // Source is the upstream end wherever there is only one, so a
+            // single arrowhead always points from supplier to customer.
+            source: forward || !back ? relation.a : relation.b,
+            target: forward || !back ? relation.b : relation.a,
+            heads: relation.dependencies.length,
+            status: worstStatus(links.map((l) => l.status)),
+            label: lineLabel(relation),
+          };
+        }),
+    [relations],
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+    const run = async (): Promise<void> => {
+      const { positions } = await layoutWithElk({
+        nodes: catalog.contexts.map((c) => ({
+          id: c.id,
+          width: CTX_NODE_W,
+          height: CTX_NODE_H,
+        })),
+        edges: lines.map((line) => ({
+          id: line.relation.id,
+          source: line.source,
+          target: line.target,
+          labelWidth: Math.max(60, line.label.length * 6),
+        })),
+        algorithm: "stress",
+        // Far enough apart that a pattern name fits in the gap: "customer /
+        // supplier" is 110px of mono, and a label wider than the space between
+        // two boxes is a label lying across one of them.
+        edgeLength: 300,
+        nodeSpacing: 130,
+      });
+      if (cancelled) return;
+
+      const nodes: PortolanNode[] = catalog.contexts.map((context) => ({
+        id: context.id,
+        type: "portolan",
+        position: positions[context.id] ?? { x: 0, y: 0 },
+        data: {
+          label: context.id,
+          sub: context.name,
+          context: context.id,
+          ghost: false,
+          kind: "context",
+          ...(context.classification ? { tag: context.classification } : {}),
+        },
+        initialWidth: CTX_NODE_W,
+        initialHeight: CTX_NODE_H,
+        width: CTX_NODE_W,
+        height: CTX_NODE_H,
+        draggable: false,
+        connectable: false,
+      }));
+
+      const edges: Edge[] = lines.map((line) => {
+        const color = statusColor(line.status);
+        const dash = statusDash(line.status);
+        const head = {
+          type: MarkerType.ArrowClosed,
+          color,
+          width: 14,
+          height: 14,
+        };
+        return {
+          id: line.relation.id,
+          source: line.source,
+          target: line.target,
+          label: line.label,
+          type: "floating",
+          style: {
+            stroke: color,
+            strokeWidth: EDGE_W,
+            ...(dash ? { strokeDasharray: dash } : {}),
+            // A pair joined by a shared type and nothing else gets a line
+            // with no heads at all; it is a fact about both, not a direction.
+            ...(line.heads === 0 ? { strokeDasharray: "1 4" } : {}),
+          },
+          ...(line.heads > 0 ? { markerEnd: head } : {}),
+          ...(line.heads === 2 ? { markerStart: head } : {}),
+        };
+      });
+
+      setDrawn({ nodes, edges, ready: true });
+    };
+    void run();
+    return () => {
+      cancelled = true;
+    };
+  }, [catalog, lines]);
+
+  const fitKey = drawn.ready
+    ? `fit-${drawn.nodes.length}-${drawn.edges.length}`
+    : "pending";
+
+  // A selected domain lights the lines it is on and dims the rest, so "who
+  // does shop answer to" is one click rather than a reading of the whole map.
+  const shownEdges = useMemo(() => {
+    if (!selectionId) return drawn.edges;
+    return drawn.edges.map((edge) => {
+      const lit = edge.source === selectionId || edge.target === selectionId;
+      // The label reads its opacity off the same style object, so a dimmed
+      // line and its dimmed label can never disagree.
+      return {
+        ...edge,
+        style: { ...edge.style, opacity: lit ? 1 : DIM },
+        zIndex: lit ? 10 : 0,
+      };
+    });
+  }, [drawn.edges, selectionId]);
+
+  const shownNodes = useMemo(
+    () =>
+      drawn.nodes.map((node) => ({
+        ...node,
+        selected: node.id === selectionId,
+        style: {
+          ...node.style,
+          opacity: selectionId && selectionId !== node.id ? 0.55 : 1,
+        },
+      })),
+    [drawn.nodes, selectionId],
+  );
+
+  const onNodeClick = useCallback(
+    (_: React.MouseEvent, node: Node) => select(node.id, "diagram"),
+    [select],
+  );
+
+  const onNodeDoubleClick = useCallback(
+    (_: React.MouseEvent, node: Node) => navigate(paths.context(node.id)),
+    [navigate],
+  );
+
+  return (
+    <div className="relative h-full w-full">
+      {drawn.ready ? null : <DiagramSkeleton />}
+      <ReactFlow
+        nodes={shownNodes}
+        edges={shownEdges}
+        nodeTypes={contextNodeTypes}
+        edgeTypes={mapEdgeTypes}
+        onNodeClick={onNodeClick}
+        onNodeDoubleClick={onNodeDoubleClick}
+        onPaneClick={() => clear("diagram")}
+        nodesDraggable={false}
+        nodesConnectable={false}
+        elementsSelectable
+        proOptions={{ hideAttribution: true }}
+        fitView
+        fitViewOptions={{ padding: 0.16 }}
+        minZoom={0.2}
+        maxZoom={1.6}
+        key={fitKey}
+      >
+        <Background gap={20} size={2} />
+        {/* The map has no modes to switch, so its only control is the way
+            out: the drawing as a file, for the page that explains it. */}
+        <Panel position="top-right">
+          <ExportSeg name="context-map" />
+        </Panel>
+      </ReactFlow>
+    </div>
+  );
+}
+
+export function ContextMapPane(props: {
+  catalog: Catalog;
+  relations: readonly ContextRelation[];
+}) {
+  return (
+    <ReactFlowProvider>
+      <ContextMapGraph {...props} />
+    </ReactFlowProvider>
+  );
+}