@shortlink-org/portolan 0.1.0

package/src/trail/model.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from "vitest";
+import { sameVisit, visitFor, visitSubject, visitTo } from "./model";
+
+const subject = (path: string, id?: string) =>
+  visitSubject({
+    path,
+    selection: id ? { kind: "unknown", id } : null,
+  });
+
+describe("visitFor", () => {
+  it("records entity pages", () => {
+    expect(visitFor("/c/shop/oms", null)).toEqual({
+      path: "/c/shop/oms",
+      selection: null,
+    });
+  });
+
+  /**
+   * The overview, the two index lists and the two whole-estate views are one
+   * click away from the chrome that is always on screen. A trail that spends
+   * its slots on them has fewer left for the leaves nobody can get back to.
+   */
+  it("ignores the pages the chrome already reaches", () => {
+    for (const path of [
+      "/",
+      "/flows",
+      "/adrs",
+      "/graph",
+      "/map",
+      "/problems",
+    ]) {
+      expect(visitFor(path, null)).toBeNull();
+    }
+  });
+
+  it("ignores a page the catalog does not know", () => {
+    expect(visitFor("/c/shop/nope", null)).toBeNull();
+    expect(visitFor("/adrs/not-a-decision", null)).toBeNull();
+  });
+});
+
+describe("visitSubject from the path", () => {
+  it("names each level of the catalog", () => {
+    expect(subject("/c/shop")).toEqual({
+      kind: "context",
+      label: "shop",
+      contextId: "shop",
+    });
+    expect(subject("/c/shop/oms")).toEqual({ kind: "service", label: "oms" });
+    expect(subject("/c/shop/oms/order")).toEqual({
+      kind: "aggregate",
+      label: "order",
+    });
+    expect(subject("/c/shop/oms/order/order-placed")).toEqual({
+      kind: "event",
+      label: "OrderPlaced",
+    });
+  });
+
+  it("reads the block literals rather than the slug behind them", () => {
+    expect(subject("/c/shop/oms/order/vo/money")).toEqual({
+      kind: "vo",
+      label: "Money",
+    });
+    expect(subject("/c/shop/oms/order/entity/order")).toEqual({
+      kind: "entity",
+      label: "Order",
+    });
+  });
+
+  it("names flows and decisions, which have no selection of their own", () => {
+    expect(subject("/flows/cart-checkout")).toEqual({
+      kind: "flow",
+      label: "cart-checkout",
+    });
+    expect(subject("/adrs/payments-0004-idempotent-journal-entries")).toEqual({
+      kind: "adr",
+      label: "ADR-0004",
+    });
+  });
+});
+
+describe("visitSubject from the selection", () => {
+  /**
+   * An event picked on a service diagram is what the reader was looking at,
+   * even though the route still says the service. The chip says so, and going
+   * back to it puts the event under them again.
+   */
+  it("prefers what was selected over what the route says", () => {
+    expect(subject("/c/shop/oms", "shop.oms.order.OrderPlaced")).toEqual({
+      kind: "event",
+      label: "OrderPlaced",
+    });
+  });
+
+  it("carries the step number for a flow", () => {
+    expect(subject("/flows/cart-checkout", "cart-checkout/s1")).toEqual({
+      kind: "flow",
+      label: "cart-checkout · 1",
+    });
+  });
+
+  it("falls back to the page when the selection is gone", () => {
+    expect(subject("/c/shop/oms", "shop.oms.order.Deleted")).toEqual({
+      kind: "service",
+      label: "oms",
+    });
+  });
+
+  it("is null when neither the selection nor the page survives", () => {
+    expect(subject("/c/gone/nowhere", "nothing.at.all")).toBeNull();
+  });
+});
+
+describe("identity", () => {
+  /**
+   * Thirteen steps of one flow are thirteen selections on one page. They share
+   * a slot, or a single flow fills the whole trail.
+   */
+  it("is the page, so steps of one flow collapse", () => {
+    const a = { path: "/flows/cart-checkout", selection: null };
+    const b = {
+      path: "/flows/cart-checkout",
+      selection: { kind: "flow-step" as const, id: "cart-checkout/s1" },
+    };
+    expect(sameVisit(a, b)).toBe(true);
+    expect(
+      sameVisit(a, { path: "/flows/auth-login", selection: null }),
+    ).toBe(false);
+  });
+
+  it("goes back to the selection it was left on", () => {
+    expect(
+      visitTo({
+        path: "/c/shop/oms",
+        selection: { kind: "event", id: "shop.oms.order.OrderPlaced" },
+      }),
+    ).toBe("/c/shop/oms#sel=event:shop.oms.order.OrderPlaced");
+    expect(visitTo({ path: "/c/shop/oms", selection: null })).toBe(
+      "/c/shop/oms",
+    );
+  });
+});
+
+describe("a module in the trail", () => {
+  // The registry index is chrome, not an entity: a reader gets back to it from
+  // the sidebar, which is the rule the whole trail is built on.
+  it("does not record the registry index as a visit", () => {
+    expect(visitFor("/registry", null)).toBeNull();
+  });
+
+  // Every lookup goes to the catalog, so a slug it does not hold is null
+  // rather than a chip labelled with a URL fragment.
+  it("does not record a module page for a slug the catalog does not hold", () => {
+    expect(visitFor("/registry/acme-shop", null)).toBeNull();
+  });
+});

package/src/trail/model.ts

@@ -0,0 +1,189 @@
+// One visit in the reader's journal.
+//
+// The breadcrumb answers "where does this thing sit" — it walks the ancestors
+// of whatever is selected. This answers a different question, "where have I
+// been", and the two are not the same shape: an ADR and a flow have no
+// ancestors in the model at all, and they are exactly the pages a reader loses
+// the thread of after five moves.
+//
+// So a visit is a route plus whatever was selected on it, and nothing is
+// stored that the catalog could contradict later: the icon and the label are
+// derived at render time, so a renamed event is renamed in the trail too, and
+// an entity the catalog no longer has drops out of it rather than pointing at
+// a page that is gone.
+
+import { catalog, index } from "../data";
+import { adrNumber } from "../lib/adr";
+import type { Kind } from "../lib/kinds";
+import { selectionHash } from "../selection/hash";
+import type { Selection } from "../selection/model";
+import { resolveSelection } from "../selection/model";
+
+export interface Visit {
+  /** The route, with no hash and no query. */
+  path: string;
+  /** What was selected on it, or null when the page is the whole answer. */
+  selection: Selection | null;
+}
+
+/** What a chip draws: one icon, one name. */
+export interface VisitSubject {
+  kind: Kind;
+  label: string;
+  /** Only ever set for `context`, which is painted in its own colour. */
+  contextId?: string;
+}
+
+/**
+ * A visit worth recording, or null for a page that is not an entity — the
+ * overview, the two index lists, the map, the graph. Those are places the
+ * reader gets back to from the chrome that is already on screen; the trail is
+ * for the leaves, which are not reachable in one move from anywhere.
+ */
+export function visitFor(
+  pathname: string,
+  selection: Selection | null,
+): Visit | null {
+  if (!subjectOfPath(pathname)) return null;
+  return { path: pathname, selection };
+}
+
+/**
+ * Identity is the path, not the pair.
+ *
+ * That one line is what collapses a flow: thirteen steps of `checkout` are
+ * thirteen selections on one page, and a journal of seven that spends all of
+ * itself on one flow has forgotten the six other things the reader came from.
+ * The newest selection wins, so the chip still points at the step they left.
+ */
+export function sameVisit(a: Visit, b: Visit): boolean {
+  return a.path === b.path;
+}
+
+/** Where a chip goes back to: the page, and the selection it was left on. */
+export function visitTo(visit: Visit): string {
+  return `${visit.path}${selectionHash(visit.selection)}`;
+}
+
+/**
+ * The chip's icon and name, or null when nothing in the catalog answers to it
+ * any more. A trail restored from a previous session can name an event that
+ * has since been deleted, and a chip that navigates to a 404 is worse than no
+ * chip at all.
+ *
+ * The selection is asked first, and it is allowed to disagree with the page:
+ * an event picked on a service diagram was what the reader was looking at,
+ * even though the route still says the service. Going back to that route with
+ * that selection puts them back in front of it.
+ */
+export function visitSubject(visit: Visit): VisitSubject | null {
+  const selected = visit.selection ? subjectOfSelection(visit.selection) : null;
+  return selected ?? subjectOfPath(visit.path);
+}
+
+function subjectOfSelection(selection: Selection): VisitSubject | null {
+  const resolved = resolveSelection(selection.id);
+  if (!resolved) return null;
+  switch (resolved.kind) {
+    case "context":
+      return {
+        kind: "context",
+        label: resolved.context.id,
+        contextId: resolved.context.id,
+      };
+    case "service":
+      return { kind: "service", label: resolved.service.slug };
+    case "aggregate":
+      return { kind: "aggregate", label: resolved.aggregate.slug };
+    case "event":
+      return { kind: "event", label: resolved.event.name };
+    case "value-object":
+      return { kind: "def", label: resolved.id };
+    case "store":
+      return { kind: "store", label: resolved.store.slug };
+    // A table and a column both take the reader back to the same canvas, so
+    // the chip names the table either way; a column rides along in the label.
+    case "table":
+      return { kind: "table", label: resolved.table.name };
+    case "view":
+      return { kind: "view", label: resolved.view.name };
+    case "column":
+      return {
+        kind: resolved.view ? "view" : "table",
+        label: `${resolved.view?.name ?? resolved.table?.name ?? ""}.${resolved.column.name}`,
+      };
+    // The step number rides along in the label rather than in a chip of its
+    // own: one flow, one slot, and the number says how far in they had got.
+    case "flow-step":
+      return {
+        kind: "flow",
+        label: `${resolved.flow.slug} · ${resolved.number}`,
+      };
+    // A bundle is a line on one canvas and nothing anywhere else. There is no
+    // route that puts a reader back in front of it, so it earns no chip.
+    case "bundle":
+      return null;
+    case "module":
+      return { kind: "module", label: resolved.module.name };
+  }
+}
+
+/**
+ * The entity a route is about, read off the segments. Every lookup goes to the
+ * catalog, so an unrecognised slug is null rather than a chip labelled with a
+ * URL fragment.
+ */
+function subjectOfPath(pathname: string): VisitSubject | null {
+  const parts = pathname.split("/").filter(Boolean);
+  const head = parts[0];
+
+  if (head === "flows") {
+    const slug = parts[1];
+    const flow = slug ? index.flowBySlug.get(slug) : undefined;
+    return flow ? { kind: "flow", label: flow.slug } : null;
+  }
+
+  if (head === "adrs") {
+    const slug = parts[1];
+    const adr = slug ? index.adrBySlug.get(slug) : undefined;
+    return adr ? { kind: "adr", label: adrNumber(adr) } : null;
+  }
+
+  if (head === "registry") {
+    const slug = parts[1];
+    // The index itself is chrome, not an entity: a reader gets back to it from
+    // the sidebar, which is the rule the whole trail is built on.
+    const module = slug ? index.moduleBySlug.get(slug) : undefined;
+    return module ? { kind: "module", label: module.name } : null;
+  }
+
+  if (head !== "c") return null;
+
+  const [, contextId, serviceSlug, aggregateSlug, fourth, fifth] = parts;
+  const context = contextId
+    ? catalog.contexts.find((c) => c.id === contextId)
+    : undefined;
+  if (!context) return null;
+  if (!serviceSlug) {
+    return { kind: "context", label: context.id, contextId: context.id };
+  }
+
+  const service = context.services.find((s) => s.slug === serviceSlug);
+  if (!service) return null;
+  if (!aggregateSlug) return { kind: "service", label: service.slug };
+
+  const aggregate = service.aggregates.find((a) => a.slug === aggregateSlug);
+  if (!aggregate) return null;
+  if (!fourth) return { kind: "aggregate", label: aggregate.slug };
+
+  // "vo" and "entity" are literals with a slug behind them, which is what
+  // keeps an event whose slug is "vo" from being read as a block page.
+  if (fourth === "vo" || fourth === "entity") {
+    const list = fourth === "vo" ? aggregate.valueObjects : aggregate.entities;
+    const block = fifth ? list.find((b) => b.slug === fifth) : undefined;
+    return block ? { kind: fourth, label: block.name } : null;
+  }
+
+  const event = aggregate.events.find((e) => e.slug === fourth);
+  return event ? { kind: "event", label: event.name } : null;
+}

package/src/trail/record.tsx

@@ -0,0 +1,32 @@
+// What counts as a visit.
+//
+// Not every render, and not every URL the router passes through. A reader
+// holding the back button, or stepping through a flow with the arrow keys,
+// crosses a dozen states in a second; a journal of seven that recorded all of
+// them would be full of places nobody stopped at. So a page has to be stood on
+// before it is written down.
+
+import { useEffect } from "react";
+import { useLocation } from "react-router";
+import { useSelection } from "../selection/store";
+import { visitFor } from "./model";
+import { useTrailStore } from "./store";
+
+/** Long enough to skip a page passed through, short enough to be there on
+ *  arrival — the trail is read after a move, not during one. */
+const VISIT_SETTLE_MS = 400;
+
+export function TrailRecorder() {
+  const { pathname } = useLocation();
+  const selection = useSelection();
+  const record = useTrailStore((s) => s.record);
+
+  useEffect(() => {
+    const visit = visitFor(pathname, selection);
+    if (!visit) return;
+    const timer = setTimeout(() => record(visit), VISIT_SETTLE_MS);
+    return () => clearTimeout(timer);
+  }, [pathname, selection, record]);
+
+  return null;
+}

package/src/trail/store.test.ts

@@ -0,0 +1,66 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import type { Visit } from "./model";
+import { MAX_VISITS, useTrailStore } from "./store";
+
+const store = () => useTrailStore.getState();
+const paths = () => store().visits.map((v) => v.path);
+
+const visit = (path: string, id?: string): Visit => ({
+  path,
+  selection: id ? { kind: "event", id } : null,
+});
+
+beforeEach(() => {
+  useTrailStore.setState({ visits: [] });
+});
+
+describe("trail store", () => {
+  it("keeps the most recent first", () => {
+    store().record(visit("/c/shop"));
+    store().record(visit("/c/shop/oms"));
+    expect(paths()).toEqual(["/c/shop/oms", "/c/shop"]);
+  });
+
+  /**
+   * A reader who goes back to an event they were on an hour ago has just made
+   * it the freshest thing in their head, not a second copy of it.
+   */
+  it("moves a page already in the trail to the front", () => {
+    store().record(visit("/c/shop"));
+    store().record(visit("/c/shop/oms"));
+    store().record(visit("/c/shop"));
+    expect(paths()).toEqual(["/c/shop", "/c/shop/oms"]);
+  });
+
+  it("keeps the newest selection for a page it already holds", () => {
+    store().record(visit("/flows/checkout"));
+    store().record(visit("/flows/checkout", "checkout/a1"));
+    expect(store().visits).toHaveLength(1);
+    expect(store().visits[0]?.selection?.id).toBe("checkout/a1");
+  });
+
+  it("holds no more than the strip can be glanced at", () => {
+    for (let i = 0; i < MAX_VISITS + 3; i++) store().record(visit(`/c/c${i}`));
+    expect(store().visits).toHaveLength(MAX_VISITS);
+    expect(paths()[0]).toBe(`/c/c${MAX_VISITS + 2}`);
+    expect(paths().at(-1)).toBe("/c/c3");
+  });
+
+  /**
+   * The recorder fires on every settled render, so the common case is a write
+   * that changes nothing. It must not notify, or the strip re-renders behind
+   * a reader who has not moved.
+   */
+  it("ignores a write that repeats the head", () => {
+    store().record(visit("/c/shop/oms", "shop.oms.order.OrderPlaced"));
+    const before = useTrailStore.getState();
+    store().record(visit("/c/shop/oms", "shop.oms.order.OrderPlaced"));
+    expect(useTrailStore.getState()).toBe(before);
+  });
+
+  it("clears", () => {
+    store().record(visit("/c/shop"));
+    store().clear();
+    expect(store().visits).toEqual([]);
+  });
+});

package/src/trail/store.ts

@@ -0,0 +1,102 @@
+// The journal itself: the last few entities the reader stood in front of.
+//
+// Most recent first, one slot per page, seven slots. Seven is not a round
+// number picked for looks — it is about as many names as a reader can scan
+// without reading, and a strip longer than that stops being a glance and
+// becomes another list to search.
+
+import { create } from "zustand";
+import { sameSelection, selectionFor } from "../selection/model";
+import type { Selection } from "../selection/model";
+import type { Visit } from "./model";
+import { sameVisit } from "./model";
+
+export const MAX_VISITS = 7;
+
+const KEY = "portolan.trail";
+
+interface TrailState {
+  /** Newest first. */
+  visits: Visit[];
+  record: (visit: Visit) => void;
+  clear: () => void;
+}
+
+export const useTrailStore = create<TrailState>()((set) => ({
+  visits: load(),
+  record: (visit) =>
+    set((state) => {
+      const head = state.visits[0];
+      // Nothing moved: the same page with the same thing selected on it. The
+      // whole state object is returned so zustand notifies nobody.
+      if (
+        head &&
+        sameVisit(head, visit) &&
+        sameSelection(head.selection, visit.selection)
+      ) {
+        return state;
+      }
+      return {
+        visits: [
+          visit,
+          ...state.visits.filter((v) => !sameVisit(v, visit)),
+        ].slice(0, MAX_VISITS),
+      };
+    }),
+  clear: () => set({ visits: [] }),
+}));
+
+/**
+ * The trail is per tab and per session: a reader who opens a second tab to
+ * compare two contexts is on a second thread of thought, and neither tab
+ * should be writing into the other's journal. sessionStorage is exactly that
+ * scope, and it is also why a reload keeps the trail while tomorrow does not.
+ */
+useTrailStore.subscribe((state) => save(state.visits));
+
+function load(): Visit[] {
+  const raw = read();
+  if (!raw) return [];
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.flatMap(toVisit).slice(0, MAX_VISITS);
+  } catch {
+    return []; // hand-edited or half-written: start empty, say nothing
+  }
+}
+
+/**
+ * Storage is a text field anyone can edit, so every field is checked. The
+ * selection's kind is re-derived rather than trusted: a stored `event` whose
+ * id is now a value object would otherwise put the wrong icon on the chip.
+ */
+function toVisit(value: unknown): Visit[] {
+  if (typeof value !== "object" || value === null) return [];
+  const { path, selection } = value as { path?: unknown; selection?: unknown };
+  if (typeof path !== "string" || !path.startsWith("/")) return [];
+  return [{ path, selection: toSelection(selection) }];
+}
+
+function toSelection(value: unknown): Selection | null {
+  if (typeof value !== "object" || value === null) return null;
+  const { id } = value as { id?: unknown };
+  if (typeof id !== "string" || !id) return null;
+  return selectionFor(id);
+}
+
+function read(): string | null {
+  try {
+    return sessionStorage.getItem(KEY);
+  } catch {
+    return null; // no storage, or a private mode that refuses it
+  }
+}
+
+function save(visits: Visit[]): void {
+  try {
+    sessionStorage.setItem(KEY, JSON.stringify(visits));
+  } catch {
+    /* this session still keeps its trail, it just does not survive a reload */
+  }
+}

package/tsconfig.json

@@ -0,0 +1,35 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": false,
+    "types": [
+      "vite/client",
+      "node"
+    ]
+  },
+  "include": [
+    "src",
+    "vite.config.ts",
+    "vitest.config.ts"
+  ]
+}