@shortlink-org/portolan 0.1.0

package/src/flow/StepRail.tsx

@@ -0,0 +1,428 @@
+import { useEffect, useId, useRef } from "react";
+import { Link } from "react-router";
+import { LayoutGroup, m, transitions } from "../lib/motion";
+import {
+  ArrowRight,
+  ChevronDown,
+  ChevronRight,
+  CornerDownLeft,
+  CornerDownRight,
+} from "lucide-react";
+import type { Step } from "../catalog";
+import { STATUSES } from "../catalog";
+import { contextName, ctxStyle } from "../lib/context-color";
+import { paths } from "../routes";
+import { statusVar } from "../components/primitives";
+import { railRows } from "./chapters";
+import type { Chapter, ChapterGroup } from "./chapters";
+import type { Continuation } from "./continues";
+import type { OutlineFrame, OutlineStep } from "./outline";
+
+
+
+/**
+ * A chapter header. The one row on the rail that is a control rather than a
+ * reading: it folds its own steps away and nothing else — the canvas keeps
+ * drawing them, because a chapter is how the reader is walking the list, not a
+ * claim about what the flow does.
+ */
+function ChapterRow({
+  chapter,
+  collapsed,
+  onToggle,
+}: {
+  chapter: Chapter;
+  collapsed: boolean;
+  onToggle: () => void;
+}) {
+  const Chevron = collapsed ? ChevronRight : ChevronDown;
+  const range =
+    chapter.from === chapter.to
+      ? `${chapter.from}`
+      : `${chapter.from}–${chapter.to}`;
+  return (
+    <button
+      type="button"
+      onClick={onToggle}
+      aria-expanded={!collapsed}
+      className="chapter-row"
+      title={
+        collapsed
+          ? `Show steps ${range} — ${chapter.title}`
+          : `Hide steps ${range} — ${chapter.title}`
+      }
+    >
+      {/* This header stands in for the frame's own opening row, so the one
+          thing that row would have shouted has to be shouted here too. */}
+      {chapter.terminal ? (
+        <CornerDownRight
+          size={10}
+          aria-hidden
+          className="shrink-0"
+          style={{ color: "var(--status-unresolved)" }}
+        />
+      ) : null}
+      <Chevron size={12} aria-hidden className="shrink-0 text-muted" />
+      {chapter.kind === "steps" ? null : (
+        <span className="mono shrink-0 rounded-[4px] border px-1 uppercase border-line-strong text-muted">
+          {chapter.kind}
+        </span>
+      )}
+      <span className="mono min-w-0 flex-1 truncate text-ink" title={chapter.title}>
+        {chapter.title}
+      </span>
+      {/* The contexts this episode touches, as colour and nothing else: the
+          rail has no room for three names, and the names are one hover away. */}
+      <span className="flex shrink-0 items-center gap-0.5">
+        {chapter.contexts.map((id) => (
+          <span
+            key={id}
+            aria-hidden
+            className="size-1.5 rounded-[1px] ctx"
+            style={{ ...ctxStyle(id), background: "var(--ctx)" }}
+            title={contextName(id)}
+          />
+        ))}
+      </span>
+      {/* Status as a count per colour rather than one dot per step: a chapter
+          of twelve steps would otherwise be a bar chart nobody asked for. */}
+      <span className="mono flex shrink-0 items-center gap-1 text-muted">
+        {STATUSES.filter((status) => chapter.status[status] > 0).map(
+          (status) => (
+            <span key={status} className="flex items-center gap-0.5" title={status}>
+              <span
+                aria-hidden
+                className="size-1.5 rounded-[1px]"
+                style={{ background: statusVar(status) }}
+              />
+              <span className="tnum">{chapter.status[status]}</span>
+            </span>
+          ),
+        )}
+      </span>
+      <span className="mono tnum shrink-0 text-faint">{range}</span>
+    </button>
+  );
+}
+
+/**
+ * A frame header. It is deliberately not a button: the frame is context for the
+ * steps under it, not something you can select, and making it clickable would
+ * put a second kind of selection on the rail.
+ */
+function FrameRow({ frame }: { frame: OutlineFrame }) {
+  const choice = frame.keyword === "alt" || frame.keyword === "else";
+  return (
+    <div
+      className="px-2 py-1"
+      style={{
+        paddingLeft: 8 + frame.depth * 10,
+        background: "color-mix(in srgb, var(--fg) 3%, transparent)",
+        opacity: frame.offPath ? 0.35 : 1,
+      }}
+    >
+      <div className="flex items-baseline gap-1.5">
+        <span
+          className="mono shrink-0 rounded-[4px] border px-1 uppercase"
+          style={{
+            borderColor: choice ? "var(--border-strong)" : "var(--border)",
+            color: choice ? "var(--fg)" : "var(--fg-muted)",
+          }}
+        >
+          {frame.keyword}
+        </span>
+        {frame.title ? (
+          <span
+            className="mono min-w-0 flex-1 truncate text-muted"
+            title={frame.title}
+          >
+            {frame.title}
+          </span>
+        ) : null}
+      </div>
+      {/* On its own line: a branch that ends the flow is the whole reason the
+          rail draws frames at all, and it must not be what the title truncates
+          away in a narrow rail. */}
+      {frame.terminal ? (
+        <div
+          className="mono mt-0.5 flex items-center gap-1"
+          style={{ color: "var(--status-unresolved)" }}
+          title="This branch ends the flow — the steps after this alt do not follow it"
+        >
+          <CornerDownRight size={9} aria-hidden className="shrink-0" />
+          ends the flow — nothing below follows it
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * Where a step leaves the context it was in. This is the first thing the eye
+ * should catch on the rail: every other fact about a step is local to the
+ * service that runs it, and this one is the only one that is somebody else's
+ * problem.
+ */
+function CrossChip({ step, context }: { step: Step; context: string | null }) {
+  const label = context ? contextName(context) : step.to;
+  return (
+    <span
+      className="chip shrink-0 ctx"
+      style={context ? ctxStyle(context) : { borderColor: "var(--border-strong)" }}
+      title={`crosses into ${label}`}
+    >
+      → {label}
+    </span>
+  );
+}
+
+function StepRow({
+  row,
+  answer,
+  active,
+  dimmed,
+  onSelect,
+  onHover,
+  crossContext,
+  continuations,
+  full,
+}: {
+  row: OutlineStep;
+  /** What the callee hands back, when a contract says. */
+  answer?: string | undefined;
+  active: boolean;
+  dimmed: boolean;
+  onSelect: (id: string) => void;
+  onHover: (id: string | null) => void;
+  /** The context this step crosses into, or undefined when it stays home. */
+  crossContext?: string | null | undefined;
+  continuations: readonly Continuation[];
+  full?: boolean;
+}) {
+  const { step, number, depth, hidden, offPath, offStatus } = row;
+  const self = step.from === step.to;
+  const crosses = crossContext !== undefined;
+  return (
+    <div
+      onMouseEnter={() => onHover(step.id)}
+      onMouseLeave={() => onHover(null)}
+      style={{ opacity: dimmed || offPath || offStatus ? 0.3 : 1 }}
+    >
+      <button
+        type="button"
+        data-nav-item
+        onClick={() => onSelect(step.id)}
+        /* Focus lights the canvas arrow the way hover does: j and k walk the
+           rail, and the reader walking it should see where each step goes. */
+        onFocus={() => onHover(step.id)}
+        onBlur={() => onHover(null)}
+        /* Playback dims and undims at the narrative tier - the reader is meant to
+           watch the sequence recede, not to be blinked at. The edge is always
+           2px and transparent, so lighting a step never nudges the text beside
+           it; the light itself is the one element below, which slides from the
+           step it was on to this one. `isolate` keeps its -z under the text but
+           above the rail. */
+        className="relative isolate flex w-full items-start gap-2 px-2 py-1.5 text-left t-narrative hover:bg-surface"
+        style={{
+          borderLeftWidth: 2,
+          borderLeftStyle: "solid",
+          borderLeftColor: "transparent",
+          paddingLeft: 8 + depth * 10,
+        }}
+        aria-current={active ? "true" : undefined}
+      >
+        {active ? (
+          <m.span
+            layoutId="active-step"
+            aria-hidden
+            className="pointer-events-none absolute inset-y-0 right-0 -left-0.5 -z-10 border-l-2 border-accent bg-raised"
+            transition={transitions.settle}
+          />
+        ) : null}
+        <span
+          className={`mono w-5 shrink-0 text-right t-micro transition-colors ${active ? "text-accent" : "text-muted"}`}
+        >
+          {number}
+        </span>
+        <span className="min-w-0 flex-1">
+          <span className="mono flex items-baseline gap-1">
+            {/* No flex-1 here: a basis of zero makes shrinking proportional
+                to nothing, and the label collapses before the answer gives up
+                a character. Both sit on their content and the answer, weighted
+                to give way ten times faster, is the one that loses. */}
+            <span
+              className="min-w-0 truncate text-ink"
+              title={step.label ?? step.ref ?? step.kind}
+            >
+              {step.label ?? step.ref ?? step.kind}
+            </span>
+            {/* The reply is not a step of its own - it is the far end of this
+                one - so it is read on the same line, and only where a contract
+                says what comes back. */}
+            {/* Only where there is room for it: two truncated halves read
+                worse than one whole label, so on a rail dragged narrow the
+                answer steps aside and the step's own panel still says it. */}
+            {answer ? (
+              <span
+                className={`min-w-0 shrink-[10] truncate text-muted ${full ? "" : "hidden @[16rem]:inline"}`}
+                title={`answers with ${answer}`}
+              >
+                → {answer}
+              </span>
+            ) : null}
+          </span>
+          {/* Two ids on one line in a rail the reader can drag down to a
+              quarter of the pane. Both are cut from the left, so what survives
+              is the end that differs. */}
+          <span className="mono flex items-center gap-1 text-muted">
+            <span className="trunc-tail" title={step.from}>
+              <bdi>{step.from}</bdi>
+            </span>
+            {self ? (
+              <CornerDownLeft size={12} aria-hidden className="shrink-0" />
+            ) : (
+              <ArrowRight size={12} aria-hidden className="shrink-0" />
+            )}
+            <span className="trunc-tail" title={step.to}>
+              <bdi>{step.to}</bdi>
+            </span>
+          </span>
+        </span>
+        {full ? (
+          <span className="mono shrink-0 text-muted">{step.kind}</span>
+        ) : null}
+        {crosses ? <CrossChip step={step} context={crossContext} /> : null}
+        {hidden ? (
+          <span
+            className="mono shrink-0 text-muted"
+            title="hidden by the cross-context filter"
+          >
+            ·
+          </span>
+        ) : null}
+        {/* Last, and always last: the status dot is the column the eye runs
+            down when it is asking one question of forty steps at once. */}
+        <span
+          aria-hidden
+          className="mt-1 size-1.5 shrink-0 rounded-[1px]"
+          style={{ background: statusVar(step.status) }}
+          title={step.status}
+        />
+      </button>
+      {/* Where this step hands the story over. Outside the button because it is
+          a different destination from the step's own selection, and nesting a
+          link inside a button is not a thing the DOM allows. */}
+      {continuations.map((next) => (
+        <Link
+          key={next.slug}
+          to={paths.flow(next.slug)}
+          className="mono flex items-center gap-1 py-0.5 pr-2 text-accent hover:underline"
+          style={{ paddingLeft: 8 + depth * 10 + 28 }}
+          title={`this event opens ${next.name}`}
+        >
+          <CornerDownRight size={9} aria-hidden className="shrink-0" />
+          continues in {next.name}
+        </Link>
+      ))}
+    </div>
+  );
+}
+
+export function StepRail({
+  groups,
+  answers,
+  activeId,
+  matchIds,
+  collapsed,
+  onToggleChapter,
+  onSelect,
+  onHover,
+  crossContextOf,
+  continuations,
+  full,
+}: {
+  /** The rail's rows, already cut into chapters. */
+  groups: readonly ChapterGroup[];
+  /** What each step's callee hands back, by step id; see flow/answers.ts. */
+  answers: ReadonlyMap<string, string>;
+  /** The step the rail marks and scrolls to. */
+  activeId: string | null;
+  /**
+   * When set, only these steps read at full strength. Used when an event is
+   * selected somewhere else: every step that carries it stays lit, and the
+   * rest of the sequence recedes.
+   */
+  matchIds?: ReadonlySet<string> | null;
+  collapsed: ReadonlySet<string>;
+  onToggleChapter: (chapterId: string) => void;
+  onSelect: (id: string) => void;
+  /** Hovering a step lights its arrow on the canvas, and nothing else. */
+  onHover: (id: string | null) => void;
+  /** The context a step crosses into; undefined for a step that crosses none. */
+  crossContextOf: (step: Step) => string | null | undefined;
+  continuations: ReadonlyMap<string, Continuation[]>;
+  full?: boolean;
+}) {
+  const listRef = useRef<HTMLDivElement | null>(null);
+  // Namespaces the light's layoutId to this rail, for a screen with two.
+  const railId = useId();
+
+  useEffect(() => {
+    if (!activeId || !listRef.current) return;
+    const el = listRef.current.querySelector<HTMLElement>(
+      `[data-step="${CSS.escape(activeId)}"]`,
+    );
+    el?.scrollIntoView({ block: "nearest" });
+  }, [activeId]);
+
+  return (
+    /* `data-nav-list`: j / k walk the steps and ⏎ selects the one under the
+       cursor, the same keys that walk every table. Chapter and frame rows are
+       not items - a chapter folds, it is not somewhere to stand. */
+    // A container so a row can ask how wide the rail is: the reader drags it,
+    // and what fits at half a pane does not fit at a quarter.
+    <div ref={listRef} data-nav-list className="@container">
+      <LayoutGroup id={railId}>
+        {groups.map((group) => {
+          const { chapter } = group;
+          const rows = railRows(group);
+          const folded = collapsed.has(chapter.id);
+          return (
+            <section key={chapter.id}>
+              <ChapterRow
+                chapter={chapter}
+                collapsed={folded}
+                onToggle={() => onToggleChapter(chapter.id)}
+              />
+              {folded ? null : (
+                <ul className="divide-y divide-line">
+                  {rows.map((row) =>
+                    row.type === "frame" ? (
+                      <li key={row.key}>
+                        <FrameRow frame={row} />
+                      </li>
+                    ) : (
+                      <li key={row.key} data-step={row.step.id}>
+                        <StepRow
+                          row={row}
+                          answer={answers.get(row.step.id)}
+                          active={activeId === row.step.id}
+                          dimmed={matchIds ? !matchIds.has(row.step.id) : false}
+                          onSelect={onSelect}
+                          onHover={onHover}
+                          crossContext={crossContextOf(row.step)}
+                          continuations={continuations.get(row.step.id) ?? []}
+                          full={full}
+                        />
+                      </li>
+                    ),
+                  )}
+                </ul>
+              )}
+            </section>
+          );
+        })}
+      </LayoutGroup>
+    </div>
+  );
+}

package/src/flow/answers.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { catalog, index } from "../data";
+import { walkSteps } from "../catalog";
+import { flowAnswers, stepAnswer } from "./answers";
+
+const flow = (slug: string) => {
+  const found = catalog.flows.find((f) => f.slug === slug);
+  if (!found) throw new Error(`no flow ${slug}`);
+  return found;
+};
+
+const step = (slug: string, id: string) => {
+  const found = walkSteps(flow(slug).steps).find((s) => s.id === id);
+  if (!found) throw new Error(`no step ${id} in ${slug}`);
+  return found;
+};
+
+describe("stepAnswer", () => {
+  it("reads the answer of an endpoint off the document that declares it", () => {
+    // billing's ViewSet is exposed by billing.v1.Invoices, and the document
+    // says a void answers 204 and an issue answers with the invoice's id.
+    expect(stepAnswer(index, step("billing-invoice-destroy", "s1"))).toBe("204");
+    expect(stepAnswer(index, step("billing-invoice-issue", "s1"))).toBe(
+      "InvoiceId",
+    );
+  });
+
+  it("reads the answer of a call to another service off the callee's contract", () => {
+    expect(stepAnswer(index, step("cart-checkout", "s2"))).toBe("SessionInfo");
+  });
+
+  it("has none for a hop no interface describes", () => {
+    // A call lands inside a service - a repository, a queryset - and an event
+    // is a publication. Neither has a reply to read.
+    for (const s of walkSteps(flow("billing-invoice-destroy").steps)) {
+      if (s.kind !== "rpc") expect(stepAnswer(index, s), s.id).toBeUndefined();
+    }
+  });
+
+  it("collects a flow's answers by step id", () => {
+    // Three, now that pricing is a service rather than a hand-written entry:
+    // its contract says what a quote comes back as.
+    const answers = flowAnswers(index, flow("cart-checkout"));
+    expect([...answers.entries()].sort()).toEqual([
+      ["s1", "CheckedOut"],
+      ["s2", "SessionInfo"],
+      ["s4", "GetQuoteResponse"],
+    ]);
+  });
+});

package/src/flow/answers.ts

@@ -0,0 +1,58 @@
+// What comes back from a call, when a contract says.
+//
+// The catalog records hops - a call was made, an event was published - and
+// never a reply: a reply is not a second thing that happened, it is the far end
+// of the same one. But a reader of a sequence still wants to see what the far
+// end hands over, and for an rpc the answer is already written down twice over:
+// in the proto that declares the method, and in the OpenAPI document that
+// declares the operation. So it is looked up rather than recorded, and a step
+// whose method nobody in the catalog provides simply has no answer to draw.
+//
+// Only an rpc has one. A `call` lands inside a service - a repository, a
+// queryset - which no interface in the catalog describes; an event is a
+// publication, and drawing a reply to it would be a lie about the bus.
+
+import type { CatalogIndex, Flow, RpcMethod, Step } from "../catalog";
+import { walkSteps } from "../catalog";
+
+/** The method a step reaches, when the catalog has it. */
+function methodOf(index: CatalogIndex, step: Step): RpcMethod | undefined {
+  if (step.kind !== "rpc") return undefined;
+
+  // Outgoing: the step names the call, and the call id is `<interface>/<method>`.
+  if (step.ref) {
+    const cut = step.ref.lastIndexOf("/");
+    if (cut < 0) return undefined;
+    const [interfaceId, name] = [step.ref.slice(0, cut), step.ref.slice(cut + 1)];
+    // A service of ours, or a system outside the estate whose vendored
+    // document names the operation: what comes back is written down either way.
+    const provider =
+      index.rpcProviderByMethod.get(step.ref) ?? index.externalProviderByMethod.get(step.ref);
+    const provided = provider?.provides.find((p) => p.id === interfaceId);
+    return provided?.methods.find((m) => m.name === name);
+  }
+
+  // Incoming: somebody called this service, and the label is the operation.
+  const service = index.serviceById.get(step.to);
+  if (!service || !step.label) return undefined;
+  for (const provided of service.provides) {
+    const found = provided.methods.find((m) => m.name === step.label);
+    if (found) return found;
+  }
+  return undefined;
+}
+
+/** What the callee hands back, as the contract names it. */
+export function stepAnswer(index: CatalogIndex, step: Step): string | undefined {
+  return methodOf(index, step)?.response || undefined;
+}
+
+/** Every step of a flow that has one, by step id. */
+export function flowAnswers(index: CatalogIndex, flow: Flow): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const step of walkSteps(flow.steps)) {
+    const answer = stepAnswer(index, step);
+    if (answer) out.set(step.id, answer);
+  }
+  return out;
+}