@shortlink-org/portolan 0.1.0 → 0.2.0

package/src/likec4/C4View.tsx

@@ -1,4 +1,5 @@
 import { useCallback } from "react";
+import type { ViewPadding } from "likec4/react";
 import { InteractiveView } from "./InteractiveView";
 import { catalogIdOf } from "./mapping";
 import { fqn } from "./ids";
@@ -14,11 +15,14 @@ export function C4View({
   viewId,
   height = 320,
   controls = false,
+  fitViewPadding,
 }: {
   viewId: string;
   height?: number | string;
   /** Zoom controls, useful when a whole estate has to fit on a phone. */
   controls?: boolean;
+  /** Space around the fitted model; overview uses a tighter product frame. */
+  fitViewPadding?: ViewPadding;
 }) {
   const selection = useSelectionStore((s) => s.selection);
   const source = useSelectionStore((s) => s.source);
@@ -46,6 +50,7 @@ export function C4View({
       <InteractiveView
         viewId={viewId}
         controls={controls}
+        fitViewPadding={fitViewPadding}
         highlightNodes={marked}
         onNode={onNode}
         onCanvas={onCanvas}

package/src/likec4/InteractiveView.tsx

@@ -1,6 +1,6 @@
 import { useCallback, useMemo, useRef } from "react";
 import type { ReactNode } from "react";
-import type { DiagramApi } from "likec4/react";
+import type { DiagramApi, ViewPadding } from "likec4/react";
 import { ReactLikeC4, isLikeC4ViewId } from "./generated";
 import { useTheme } from "../app/theme";
 import { Ident } from "../components/Ident";
@@ -12,6 +12,8 @@ export interface InteractiveViewProps {
   /** Sequence for flows, diagram for element views. */
   variant?: "diagram" | "sequence";
   controls?: boolean;
+  /** Space around an initially fitted diagram. */
+  fitViewPadding?: ViewPadding;
   walkthrough?: boolean;
   /** LikeC4 element ids to mark; everything else on the canvas is dimmed. */
   highlightNodes?: readonly string[];
@@ -71,6 +73,7 @@ export function InteractiveView({
   viewId,
   variant = "diagram",
   controls = false,
+  fitViewPadding,
   walkthrough = false,
   highlightNodes = [],
   highlightEdges = [],
@@ -122,6 +125,7 @@ export function InteractiveView({
         background="dots"
         controls={controls}
         fitView
+        fitViewPadding={fitViewPadding}
         pannable
         zoomable
         enableDynamicViewWalkthrough={walkthrough}

package/src/map/ContextMapGraph.tsx

@@ -61,13 +61,33 @@ interface Drawn {
   ready: boolean;
 }
 
+export interface ContextMapGraphProps {
+  catalog: Catalog;
+  relations: readonly ContextRelation[];
+  /**
+   * Whether the wheel zooms the map. On the map's own page it does; on a page
+   * the map is embedded in, the wheel belongs to the page and the map is
+   * zoomed by pinch or by the fit control instead.
+   */
+  zoomOnScroll?: boolean;
+  /** Tighter geometry for small embedded canvases such as the landing hero. */
+  compactLayout?: boolean;
+  /** The full map exports files; embedded previews keep the canvas focused. */
+  showExport?: boolean;
+  /** Embedded previews keep the surrounding estate readable while touring it. */
+  inactiveEdgeOpacity?: number;
+  inactiveNodeOpacity?: number;
+}
+
 export function ContextMapGraph({
   catalog,
   relations,
-}: {
-  catalog: Catalog;
-  relations: readonly ContextRelation[];
-}) {
+  zoomOnScroll = true,
+  compactLayout = false,
+  showExport = true,
+  inactiveEdgeOpacity = DIM,
+  inactiveNodeOpacity = 0.55,
+}: ContextMapGraphProps) {
   const navigate = useNavigate();
   const selectionId = useSelectionStore((s) => s.selection?.id ?? null);
   const select = useSelectionStore((s) => s.select);
@@ -126,8 +146,8 @@ export function ContextMapGraph({
         // 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,
+        edgeLength: compactLayout ? 210 : 300,
+        nodeSpacing: compactLayout ? 80 : 130,
       });
       if (cancelled) return;
 
@@ -185,7 +205,7 @@ export function ContextMapGraph({
     return () => {
       cancelled = true;
     };
-  }, [catalog, lines]);
+  }, [catalog, compactLayout, lines]);
 
   const fitKey = drawn.ready
     ? `fit-${drawn.nodes.length}-${drawn.edges.length}`
@@ -201,11 +221,14 @@ export function ContextMapGraph({
       // line and its dimmed label can never disagree.
       return {
         ...edge,
-        style: { ...edge.style, opacity: lit ? 1 : DIM },
+        style: {
+          ...edge.style,
+          opacity: lit ? 1 : inactiveEdgeOpacity,
+        },
         zIndex: lit ? 10 : 0,
       };
     });
-  }, [drawn.edges, selectionId]);
+  }, [drawn.edges, inactiveEdgeOpacity, selectionId]);
 
   const shownNodes = useMemo(
     () =>
@@ -214,10 +237,13 @@ export function ContextMapGraph({
         selected: node.id === selectionId,
         style: {
           ...node.style,
-          opacity: selectionId && selectionId !== node.id ? 0.55 : 1,
+          opacity:
+            selectionId && selectionId !== node.id
+              ? inactiveNodeOpacity
+              : 1,
         },
       })),
-    [drawn.nodes, selectionId],
+    [drawn.nodes, inactiveNodeOpacity, selectionId],
   );
 
   const onNodeClick = useCallback(
@@ -231,7 +257,7 @@ export function ContextMapGraph({
   );
 
   return (
-    <div className="relative h-full w-full">
+    <div className="canvas-motion relative h-full w-full">
       {drawn.ready ? null : <DiagramSkeleton />}
       <ReactFlow
         nodes={shownNodes}
@@ -246,7 +272,9 @@ export function ContextMapGraph({
         elementsSelectable
         proOptions={{ hideAttribution: true }}
         fitView
-        fitViewOptions={{ padding: 0.16 }}
+        fitViewOptions={{ padding: compactLayout ? 0.06 : 0.16 }}
+        zoomOnScroll={zoomOnScroll}
+        preventScrolling={zoomOnScroll}
         minZoom={0.2}
         maxZoom={1.6}
         key={fitKey}
@@ -254,18 +282,17 @@ export function ContextMapGraph({
         <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>
+        {showExport ? (
+          <Panel position="top-right">
+            <ExportSeg name="context-map" />
+          </Panel>
+        ) : null}
       </ReactFlow>
     </div>
   );
 }
 
-export function ContextMapPane(props: {
-  catalog: Catalog;
-  relations: readonly ContextRelation[];
-}) {
+export function ContextMapPane(props: ContextMapGraphProps) {
   return (
     <ReactFlowProvider>
       <ContextMapGraph {...props} />

package/src/pages/ContextMap.tsx

@@ -495,7 +495,11 @@ export function ContextMap() {
               Map
             </SectionTitle>
             <div className="h-[340px] overflow-hidden rounded-card border border-line">
-              <ContextMapPane catalog={catalog} relations={relations} />
+              <ContextMapPane
+                catalog={catalog}
+                relations={relations}
+                zoomOnScroll={false}
+              />
             </div>
           </section>
 

package/src/pages/FlowDetail.tsx

@@ -8,7 +8,7 @@ import {
   useState,
 } from "react";
 import { useParams } from "react-router";
-import { ChevronLeft, ChevronRight } from "lucide-react";
+import { ChevronLeft, ChevronRight, MessageSquare } from "lucide-react";
 import { saveCanvasImage } from "../lib/export-canvas";
 import { allRepos, flowContexts, walkSteps } from "../catalog";
 import type { Flow, Status, Step } from "../catalog";
@@ -55,6 +55,8 @@ import { ContextPill } from "../components/primitives";
 import { WhatLinksHere } from "../components/WhatLinksHere";
 import { FlowTrigger } from "../components/FlowTrigger";
 import { NotFound } from "./NotFound";
+import { useChatAvailable } from "../chat/prefs";
+import { useChatUi } from "../chat/store";
 
 /**
  * The summary, clamped to two lines.
@@ -117,6 +119,7 @@ export function FlowDetail() {
   const [statusFilter, setStatusFilter] = useState<Status | null>(null);
   const [exporting, setExporting] = useState(false);
   const say = useToastStore((s) => s.say);
+  const chatAvailable = useChatAvailable();
   /** Empty means every branch at once — the union, not a run. */
   const [pathId, setPathId] = useState("");
   /** Chapters the reader has folded away. Empty means the whole flow is open. */
@@ -441,12 +444,23 @@ export function FlowDetail() {
         {/* A flow belongs to no single context, so the wash takes the first one
             it crosses - the context it starts in. */}
         <div aria-hidden className="hero-wash" style={ctxStyle(contexts[0])} />
-        <div className="flex flex-wrap items-baseline gap-x-3 gap-y-1">
-          <h1 className="text-md font-semibold" title={flow.name}>
+        <div className="flex flex-wrap items-center gap-x-3 gap-y-2">
+          <h1 className="text-lg font-semibold" title={flow.name}>
             {flow.name}
           </h1>
           <Ident value={flow.id} className="text-muted" />
           <div className="ml-auto flex items-center gap-2">
+            {chatAvailable ? (
+              <button
+                type="button"
+                onClick={() => useChatUi.getState().setOpen(true)}
+                className="product-primary"
+                title={`Ask the catalog about ${flow.name}`}
+              >
+                <MessageSquare size={14} aria-hidden />
+                ask this flow
+              </button>
+            ) : null}
             <PinButton kind="flow" id={flow.id} label={flow.name} />
           </div>
         </div>
@@ -465,7 +479,8 @@ export function FlowDetail() {
             What the row does NOT carry is anything about the picture: the view
             id and the filter's own count are facts about what is on the canvas
             right now, and they live with the controls that changed them. */}
-        <div className="mt-1.5 flex flex-wrap items-center gap-x-2.5 gap-y-1.5">
+        <div className="mt-2 flex flex-wrap items-center gap-x-2.5 gap-y-1.5 rounded-control border border-line bg-surface px-2.5 py-1.5 shadow-xs">
+          <span className="label shrink-0 text-faint">evidence</span>
           {flow.trigger ? <FlowTrigger trigger={flow.trigger} /> : null}
           {flow.includes && flow.includes.length > 0 ? (
             <span
@@ -501,9 +516,11 @@ export function FlowDetail() {
             variant="line"
             className="mt-0"
           />
-          {contexts.map((c) => (
-            <ContextPill key={c} id={c} name={contextName(c)} />
-          ))}
+          <div className="flex flex-wrap items-center gap-1.5 sm:ml-auto">
+            {contexts.map((c) => (
+              <ContextPill key={c} id={c} name={contextName(c)} />
+            ))}
+          </div>
         </div>
 
         <FlowToolbar

package/src/pages/Overview.tsx

@@ -3,11 +3,9 @@ import { useState } from "react";
 import { Link } from "react-router";
 import { AlertTriangle } from "lucide-react";
 import { activeCatalogProfile, CATALOG_PATH, catalog, index } from "../data";
-import { contextOwners, contextStats, problems, widestFlows } from "../lib/derive";
+import { contextOwners, contextStats, widestFlows } from "../lib/derive";
 import type { ContextOwner } from "../lib/derive";
-import { dataProblems } from "../lib/data-problems";
-import { protoProblems } from "../lib/proto-problems";
-import { wireProblems } from "../lib/wire-problems";
+import { allProblems } from "../lib/all-problems";
 import { ctxStyle } from "../lib/context-color";
 import { middleTruncate, plural } from "../lib/format";
 import { useCountUp, staggerStyle } from "../lib/motion";
@@ -19,6 +17,7 @@ import { profileContainersViewId, profileLandscapeViewId } from "../likec4/ids";
 import { LevelSwitch } from "../likec4/levels";
 import type { C4Level } from "../likec4/levels";
 import { CatalogStamp } from "../components/CatalogStamp";
+import { ProblemRow } from "../components/ProblemRow";
 import { RowActions } from "../components/RowActions";
 import { MachineDocs } from "../components/MachineDocs";
 import {
@@ -26,6 +25,9 @@ import {
   ContextPill,
 } from "../components/primitives";
 
+/** How many problems the overview lists before pointing at the page that lists them all. */
+const OVERVIEW_PROBLEMS = 4;
+
 /**
  * A measurement that arrives rather than appears - 200ms, linear, once - and
  * then takes you to what it measured. A number that counts something the app
@@ -99,12 +101,9 @@ export function Overview() {
     (count, context) => count + context.services.length,
     0,
   );
-  const issueCount = [
-    ...problems(catalog),
-    ...protoProblems(catalog, index),
-    ...dataProblems(catalog, index),
-    ...wireProblems(catalog, index),
-  ].length;
+  const issues = allProblems(catalog, index);
+  const issueCount = issues.length;
+  const errorCount = issues.filter((p) => p.severity === "error").length;
 
   return (
     <div className="h-full overflow-y-auto p-gutter">
@@ -144,7 +143,7 @@ export function Overview() {
         <HealthMetric
           value={issueCount}
           unit="problem"
-          to={paths.problems()}
+          to={issueCount > 0 ? `#${OVERVIEW_ANCHOR.problems}` : paths.problems()}
           problem
         />
       </div>
@@ -178,8 +177,9 @@ export function Overview() {
               ? profileContainersViewId(activeCatalogProfile.id)
               : profileLandscapeViewId(activeCatalogProfile.id)
           }
-          height={phone ? 300 : level === 2 ? 560 : 400}
+          height={phone ? 320 : level === 2 ? 660 : 580}
           controls={phone}
+          fitViewPadding={{ x: 8, y: 8 }}
         />
       </section>
 
@@ -338,6 +338,62 @@ export function Overview() {
         </div>
       </section>
 
+      {/* The first few problems, errors first, on the page a reader lands on.
+          The count in the health row says how many; this says which, so
+          "13 problems" is a list to start on rather than a number to worry
+          about. Nothing is shown for a clean estate - the metric already
+          says zero, and a heading over an empty list is a dead end. */}
+      {issueCount > 0 ? (
+        <section id={OVERVIEW_ANCHOR.problems} className="mt-section">
+          <SectionTitle
+            anchor={OVERVIEW_ANCHOR.problems}
+            right={
+              <span className="flex items-center gap-2">
+                <span className="section-aside">
+                  <span className="text-unresolved">
+                    {errorCount} {plural(errorCount, "error")}
+                  </span>
+                  {issueCount - errorCount > 0 ? (
+                    <>
+                      {" · "}
+                      <span className="text-declared">
+                        {issueCount - errorCount}{" "}
+                        {plural(issueCount - errorCount, "warning")}
+                      </span>
+                    </>
+                  ) : null}
+                </span>
+                <Link
+                  to={paths.problems()}
+                  className="rounded-control px-1 text-accent hover:underline"
+                >
+                  all problems →
+                </Link>
+              </span>
+            }
+          >
+            Problems
+          </SectionTitle>
+          <div className="flex max-w-table flex-col gap-2" data-nav-list>
+            {issues.slice(0, OVERVIEW_PROBLEMS).map((problem, i) => (
+              <ProblemRow
+                key={`${problem.kind}:${problem.id}:${problem.peer}`}
+                problem={problem}
+                index={i}
+              />
+            ))}
+            {issueCount > OVERVIEW_PROBLEMS ? (
+              <Link
+                to={paths.problems()}
+                className="mono self-start rounded-control px-1 text-muted hover:text-ink"
+              >
+                {issueCount - OVERVIEW_PROBLEMS} more →
+              </Link>
+            ) : null}
+          </div>
+        </section>
+      ) : null}
+
       <MachineDocs className="mt-section pb-section" />
     </div>
   );

package/src/pages/Problems.tsx

@@ -6,62 +6,14 @@
 
 import { useDocumentTitle } from "../app/title";
 import { useMemo, useState } from "react";
-import { Link, useSearchParams } from "react-router";
+import { useSearchParams } from "react-router";
 import { catalog, index } from "../data";
-import { edgeCount, problems } from "../lib/derive";
-import type { Problem } from "../lib/derive";
-import { dataProblems } from "../lib/data-problems";
-import { protoProblems } from "../lib/proto-problems";
-import { wireProblems } from "../lib/wire-problems";
-import { contextVar, ctxStyle } from "../lib/context-color";
+import { edgeCount } from "../lib/derive";
+import { allProblems } from "../lib/all-problems";
+import { contextVar } from "../lib/context-color";
 import { absoluteTime, plural, relativeTime } from "../lib/format";
-import { staggerStyle } from "../lib/motion";
-import { KindIcon } from "../components/kind";
-import { Ident } from "../components/Ident";
 import { SectionTitle } from "../components/PageHeader";
-import {
-  eventPath,
-  servicePath,
-  storePath,
-  tablePath,
-  viewPath,
-} from "../routes";
-
-/** The icon a problem row carries: what the near end of the edge IS. */
-const KIND_OF: Record<Problem["kind"], "service" | "event" | "table"> = {
-  rpc: "service",
-  consumer: "event",
-  "cross-service-fk": "table",
-  "cross-service-lineage": "table",
-  "shared-store": "table",
-  "persistence-drift": "table",
-  "column-type": "table",
-  "outbox-payload": "table",
-  "proto-missing": "service",
-  "shared-channel": "event",
-  "channel-undeclared": "event",
-  "channel-unpublished": "service",
-  "subscription-unresolved": "service",
-};
-
-const KIND_NOTE: Record<Problem["kind"], string> = {
-  rpc: "the provider of this call is not in the catalog",
-  consumer: "this consumer of the event is not in the catalog",
-  "cross-service-fk": "foreign key across a service boundary",
-  "cross-service-lineage": "a value copied from another service's schema",
-  "shared-store": "a second service writes this database",
-  "persistence-drift": "this table no longer carries the aggregate it claims",
-  "column-type": "column type and domain type disagree",
-  "outbox-payload": "an outbox with no payload column",
-  "proto-missing":
-    "the provider is in the catalog but answers on no such method",
-  "shared-channel": "a second service publishes on this channel",
-  "channel-undeclared":
-    "this event goes out on a channel the service does not declare",
-  "channel-unpublished": "a declared channel no event of this service names",
-  "subscription-unresolved":
-    "nothing in the catalog publishes what this service listens for",
-};
+import { ProblemRow } from "../components/ProblemRow";
 
 export function Problems() {
   useDocumentTitle("Problems");
@@ -81,18 +33,7 @@ export function Problems() {
   // Unresolved edges first, then everything the schema disagrees with. Within
   // each, errors before warnings: a boundary leak is not the same kind of news
   // as a column whose type has drifted, and mixing them buries the first.
-  const all = useMemo(() => {
-    const found = [
-      ...problems(catalog),
-      ...protoProblems(catalog, index),
-      ...dataProblems(catalog, index),
-      ...wireProblems(catalog, index),
-    ];
-    return [
-      ...found.filter((p) => p.severity === "error"),
-      ...found.filter((p) => p.severity === "warning"),
-    ];
-  }, []);
+  const all = useMemo(() => allProblems(catalog, index), []);
   // How many edges there were to resolve at all. Zero problems out of zero
   // edges is not a clean bill of health - nothing crossed a boundary, so
   // nothing was checked, and saying "every edge resolved" there is a green
@@ -230,131 +171,3 @@ function ClearSkies({ checked }: { checked: number }) {
   );
 }
 
-/** Where the near end of a problem lives, by what kind of edge it is. */
-function nearPath(problem: Problem): string | null {
-  switch (problem.kind) {
-    case "rpc":
-    // The near end is the CALLING service either way. `rpc` is a call whose
-    // peer is nobody; this is a call whose peer is known and whose method is
-    // not - and in both the thing to go and look at is the caller.
-    case "proto-missing":
-      return servicePath(problem.service);
-    case "consumer":
-    case "channel-undeclared":
-      return eventPath(problem.id);
-    // The near end is an event when the service has one on the channel, and
-    // the service itself when the claim comes from its document alone.
-    case "shared-channel":
-      return eventPath(problem.id) ?? servicePath(problem.service);
-    case "channel-unpublished":
-    case "subscription-unresolved":
-      return servicePath(problem.service);
-    case "shared-store":
-    case "persistence-drift":
-    case "outbox-payload":
-      return tablePath(problem.id);
-    // The id is "<relation>.<column>", so the relation is its own id minus the
-    // last segment — and the relation is what the canvas can actually show.
-    case "cross-service-fk":
-    case "column-type":
-      return relationPath(problem.id.split(".").slice(0, -1).join("."));
-    // Lineage is stated on a column, except when a view states it whole, so
-    // the id is one or the other and both are looked up the same way.
-    case "cross-service-lineage":
-      return (
-        relationPath(problem.id) ??
-        relationPath(problem.id.split(".").slice(0, -1).join("."))
-      );
-  }
-}
-
-/** A table or a view, whichever the id turns out to name. */
-function relationPath(id: string): string | null {
-  return tablePath(id) ?? viewPath(id);
-}
-
-/** Where the far end lives, when the catalog knows it. */
-function peerPath(problem: Problem): string | null {
-  switch (problem.kind) {
-    case "cross-service-fk":
-      return tablePath(problem.peer);
-    case "cross-service-lineage":
-      return (
-        relationPath(problem.peer) ??
-        relationPath(problem.peer.split(".").slice(0, -1).join("."))
-      );
-    case "shared-store":
-    case "shared-channel":
-      return servicePath(problem.peer);
-    case "outbox-payload":
-      return storePath(problem.peer);
-    default:
-      return null;
-  }
-}
-
-function ProblemRow({ problem, index }: { problem: Problem; index: number }) {
-  const near = nearPath(problem);
-  const peerTo = peerPath(problem);
-  const tone =
-    problem.severity === "error"
-      ? "var(--status-unresolved)"
-      : "var(--status-declared)";
-
-  return (
-    <div
-      className="stagger-in flex flex-wrap items-baseline gap-x-3 gap-y-1 rounded-control border px-3 py-2"
-      style={{ ...staggerStyle(index), borderColor: tone }}
-    >
-      <KindIcon kind={KIND_OF[problem.kind]} />
-      {near ? (
-        <Link
-          to={near}
-          data-nav-item
-          className="mono rounded-control text-accent hover:underline"
-          title={problem.id}
-        >
-          {problem.id}
-        </Link>
-      ) : (
-        <Ident value={problem.id} />
-      )}
-      <span aria-hidden className="text-muted">
-        →
-      </span>
-      {peerTo ? (
-        <Link
-          to={peerTo}
-          className="mono rounded-control hover:underline"
-          style={{ color: tone }}
-          title={problem.peer}
-        >
-          {problem.peer}
-        </Link>
-      ) : (
-        <Ident
-          value={problem.peer}
-          className={
-            problem.severity === "error" ? "text-unresolved" : "text-declared"
-          }
-          title={`${problem.peer} — ${KIND_NOTE[problem.kind]}. Click to copy.`}
-        />
-      )}
-      <span className="chip ctx" style={ctxStyle(problem.context)}>
-        <span aria-hidden className="dot" />
-        {problem.context}
-      </span>
-      <span className="mono ml-auto text-muted">{KIND_NOTE[problem.kind]}</span>
-      {problem.note ? (
-        <p className="w-full border-l-2 pl-2 border-line-strong text-muted">
-          {problem.note}
-        </p>
-      ) : null}
-      {problem.source ? (
-        <div className="mono w-full text-muted">
-          <Ident value={problem.source} />
-        </div>
-      ) : null}
-    </div>
-  );
-}