@shortlink-org/portolan 0.1.0

package/src/selection/pages.ts

@@ -0,0 +1,268 @@
+// Which page shows which entity.
+//
+// Two questions are asked of this module. "Where does this selection live?"
+// decides whether the command palette needs to navigate at all. "Does this page
+// contain it?" decides whether a navigation keeps the selection or drops it —
+// a selection nothing on screen can point at is a selection nobody can see.
+
+import { walkSteps } from "../catalog";
+import { catalog, index } from "../data";
+import { paths } from "../routes";
+import type { Selection } from "./model";
+import { parseFlowStepId, resolveSelection } from "./model";
+
+/** The page that owns a selection, or null when it has no page of its own. */
+export function selectionPath(selection: Selection): string | null {
+  const resolved = resolveSelection(selection.id);
+  if (!resolved) return null;
+  switch (resolved.kind) {
+    case "context":
+      return paths.context(resolved.context.id);
+    case "service":
+      return paths.service(resolved.context.id, resolved.service.slug);
+    case "aggregate":
+      return paths.aggregate(
+        resolved.context.id,
+        resolved.service.slug,
+        resolved.aggregate.slug,
+      );
+    case "event":
+      return paths.event(
+        resolved.context.id,
+        resolved.service.slug,
+        resolved.aggregate.slug,
+        resolved.event.slug,
+      );
+    case "flow-step":
+      return paths.flow(resolved.flow.slug);
+    // A table, a view and a column are read on the canvas of the store holding
+    // them: a column's page is the picture of what it points at and where its
+    // value came from.
+    case "store":
+    case "table":
+    case "view":
+    case "column":
+      return paths.store(
+        resolved.context.id,
+        resolved.service.slug,
+        resolved.store.slug,
+      );
+    // A shared type has no page. It is only ever read inside the event that
+    // carries it, so selecting one opens the panel and moves nobody. Nor does
+    // a bundle: it is a fact about the graph, and the graph is where it is.
+    case "value-object":
+    case "bundle":
+      return null;
+    case "module":
+      return paths.module(resolved.module.slug);
+  }
+}
+
+interface Route {
+  kind:
+    | "overview"
+    | "flows"
+    | "flow"
+    | "adrs"
+    | "adr"
+    | "graph"
+    | "c"
+    | "registry"
+    | "none";
+  segments: string[];
+}
+
+function parseRoute(pathname: string): Route {
+  const segments =
+    (pathname.split("#")[0] ?? "").split("?")[0]?.split("/").filter(Boolean) ??
+    [];
+  const head = segments[0];
+  if (segments.length === 0) return { kind: "overview", segments };
+  if (head === "flows") {
+    return { kind: segments.length > 1 ? "flow" : "flows", segments };
+  }
+  if (head === "adrs") {
+    return { kind: segments.length > 1 ? "adr" : "adrs", segments };
+  }
+  if (head === "graph") return { kind: "graph", segments };
+  if (head === "registry") return { kind: "registry", segments };
+  if (head === "c") return { kind: "c", segments };
+  return { kind: "none", segments };
+}
+
+/** Value objects a version of this event reaches, one level deep. */
+function defsOfEvent(eventId: string): Set<string> {
+  const event = index.eventById.get(eventId);
+  const out = new Set<string>();
+  if (!event) return out;
+  for (const version of event.versions) {
+    for (const field of version.fields) {
+      if (!field.ref) continue;
+      out.add(field.ref);
+      for (const sub of catalog.defs[field.ref]?.fields ?? []) {
+        if (sub.ref) out.add(sub.ref);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * True when the page at `pathname` can show the selected entity. Deliberately
+ * conservative: a page "contains" what it draws or lists, not everything it
+ * happens to link to.
+ */
+export function pageContains(pathname: string, selection: Selection): boolean {
+  const route = parseRoute(pathname);
+  const resolved = resolveSelection(selection.id);
+  if (!resolved) return false;
+
+  switch (route.kind) {
+    case "graph": {
+      // Services and events are both nodes; a bundle is a line between two
+      // services, drawn in compact mode.
+      return (
+        resolved.kind === "service" ||
+        resolved.kind === "event" ||
+        resolved.kind === "bundle"
+      );
+    }
+
+    case "flow": {
+      const flow = index.flowBySlug.get(route.segments[1] ?? "");
+      if (!flow) return false;
+      const steps = walkSteps(flow.steps);
+      switch (resolved.kind) {
+        case "flow-step":
+          return parseFlowStepId(resolved.id)?.flowSlug === flow.slug;
+        case "service":
+          return flow.participants.some((p) => p.id === resolved.id);
+        case "event":
+          return steps.some((s) => s.ref === resolved.id);
+        case "context":
+          return flow.participants.some((p) => p.context === resolved.id);
+        default:
+          return false;
+      }
+    }
+
+    case "c": {
+      const [, contextId, serviceSlug, aggregateSlug, eventSlug] =
+        route.segments;
+
+      // Value object and entity pages sit one segment deeper, behind a literal.
+      // A block is not a selectable entity and the page draws nothing else, so
+      // it contains nothing — without this the literal reads as an event slug
+      // and the page claims to hold every event of its aggregate.
+      if (
+        route.segments.length === 6 &&
+        (eventSlug === "vo" || eventSlug === "entity")
+      ) {
+        return false;
+      }
+
+      // A store page is "/c/<ctx>/<svc>/data/<store>": the literal sits where
+      // an aggregate slug would, so it is read before anything else tries to.
+      if (route.segments.length === 5 && aggregateSlug === "data") {
+        const store = (catalog.stores ?? []).find(
+          (s) => s.slug === eventSlug && s.owner === `${contextId}.${serviceSlug}`,
+        );
+        if (!store) return false;
+        switch (resolved.kind) {
+          case "store":
+            return resolved.store.id === store.id;
+          case "table":
+          case "view":
+          case "column":
+            return resolved.store.id === store.id;
+          case "aggregate":
+            // The canvas says which aggregate each table holds, so selecting
+            // one from the sidebar lights the tables that persist it.
+            return (
+              store.tables.some((t) => t.persists?.aggregate === resolved.id) ||
+              (store.views ?? []).some(
+                (v) => v.persists?.aggregate === resolved.id,
+              )
+            );
+          default:
+            return false;
+        }
+      }
+      const context = catalog.contexts.find((c) => c.id === contextId);
+      if (!context) return false;
+      const service = serviceSlug
+        ? context.services.find((s) => s.slug === serviceSlug)
+        : undefined;
+      const aggregate =
+        service && aggregateSlug
+          ? service.aggregates.find((a) => a.slug === aggregateSlug)
+          : undefined;
+      const event =
+        aggregate && eventSlug
+          ? aggregate.events.find((e) => e.slug === eventSlug)
+          : undefined;
+
+      if (event) {
+        if (resolved.kind === "event") return resolved.id === event.id;
+        if (resolved.kind === "value-object")
+          return defsOfEvent(event.id).has(resolved.id);
+        return false;
+      }
+      if (aggregate) {
+        if (resolved.kind === "aggregate") return resolved.id === aggregate.id;
+        if (resolved.kind === "event")
+          return aggregate.events.some((e) => e.id === resolved.id);
+        return false;
+      }
+      if (service) {
+        if (resolved.kind === "service") return resolved.id === service.id;
+        if (resolved.kind === "aggregate")
+          return service.aggregates.some((a) => a.id === resolved.id);
+        if (resolved.kind === "event")
+          return service.aggregates.some((a) =>
+            a.events.some((e) => e.id === resolved.id),
+          );
+        return false;
+      }
+      if (resolved.kind === "context") return resolved.id === context.id;
+      if (resolved.kind === "service")
+        return context.services.some((s) => s.id === resolved.id);
+      return false;
+    }
+
+    // A module page draws one module, its packages and its interfaces. It is
+    // deliberately narrow: it LINKS to the services that use it, and a page
+    // contains what it draws rather than everything it points at.
+    case "registry": {
+      if (resolved.kind !== "module") return false;
+      const slug = route.segments[1];
+
+      // The index lists every module, so it contains all of them.
+      return slug === undefined || slug === resolved.module.slug;
+    }
+
+    case "overview":
+    case "flows":
+    case "adrs":
+    case "adr":
+    case "none":
+      return false;
+  }
+}
+
+/**
+ * True when a click in the tree should select without navigating.
+ *
+ * A tree is a navigator, so this is deliberately narrow: only on a flow page,
+ * and only for something that flow actually draws. That is the one place where
+ * leaving is the wrong answer — picking an event there is a question about
+ * *this* sequence ("where does it appear?"), and the flow page answers it by
+ * lighting the matching steps.
+ */
+export function selectsInPlace(
+  pathname: string,
+  selection: Selection,
+): boolean {
+  const route = parseRoute(pathname);
+  return route.kind === "flow" && pageContains(pathname, selection);
+}

package/src/selection/store.test.ts

@@ -0,0 +1,62 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { useSelectionStore } from "./store";
+
+const store = () => useSelectionStore.getState();
+
+beforeEach(() => {
+  useSelectionStore.setState({ selection: null, source: null });
+});
+
+describe("selection store", () => {
+  it("derives the kind rather than taking it from the caller", () => {
+    store().select("shop.oms.order.OrderPlaced", "sidebar");
+    expect(store().selection).toEqual({
+      kind: "event",
+      id: "shop.oms.order.OrderPlaced",
+    });
+    expect(store().source).toBe("sidebar");
+  });
+
+  it("holds one selection at a time", () => {
+    store().select("shop.oms", "sidebar");
+    store().select("payments.ledger", "palette");
+    expect(store().selection?.id).toBe("payments.ledger");
+    expect(store().source).toBe("palette");
+  });
+
+  it("clears", () => {
+    store().select("shop.oms", "sidebar");
+    store().clear("panel");
+    expect(store().selection).toBeNull();
+    expect(store().source).toBe("panel");
+  });
+
+  /**
+   * A diagram that echoes its own click back must not start a render loop, so
+   * an identical write from the same panel is dropped whole - state identity
+   * included, which is what stops zustand notifying.
+   */
+  it("ignores an identical write from the same source", () => {
+    store().select("shop.oms", "diagram");
+    const before = useSelectionStore.getState();
+    store().select("shop.oms", "diagram");
+    expect(useSelectionStore.getState()).toBe(before);
+  });
+
+  /**
+   * The same entity re-selected from somewhere else is not a no-op: the
+   * diagram decides whether to mark its canvas on exactly that difference.
+   */
+  it("records a new source for the same entity", () => {
+    store().select("shop.oms", "diagram");
+    store().select("shop.oms", "sidebar");
+    expect(store().source).toBe("sidebar");
+    expect(store().selection?.id).toBe("shop.oms");
+  });
+
+  it("accepts a pre-parsed selection from a URL", () => {
+    store().set({ kind: "event", id: "shop.oms.order.OrderPlaced" }, "url");
+    expect(store().selection?.kind).toBe("event");
+    expect(store().source).toBe("url");
+  });
+});

package/src/selection/store.ts

@@ -0,0 +1,46 @@
+// One selection, globally, for the whole app.
+//
+// Every panel that can be clicked writes here; every panel that has to react
+// reads here. Nothing else holds a "what is selected" of its own, so there is
+// no pair of panels that can disagree.
+
+import { create } from "zustand";
+import type { Selection, SelectionSource } from "./model";
+import { sameSelection, selectionFor } from "./model";
+
+export interface SelectionState {
+  selection: Selection | null;
+  /** Which panel wrote the current value. Never part of identity. */
+  source: SelectionSource | null;
+  /** Selects by catalog id; the kind is derived, never passed in. */
+  select: (id: string, source: SelectionSource) => void;
+  /** Selects a value that already carries its kind (parsed from a URL). */
+  set: (selection: Selection | null, source: SelectionSource) => void;
+  clear: (source: SelectionSource) => void;
+}
+
+export const useSelectionStore = create<SelectionState>()((set) => ({
+  selection: null,
+  source: null,
+  select: (id, source) => set(next(selectionFor(id), source)),
+  set: (selection, source) => set(next(selection, source)),
+  clear: (source) => set(next(null, source)),
+}));
+
+/**
+ * Re-selecting the same entity from the same panel is a no-op, so a diagram
+ * that echoes its own click back cannot start a render loop. Re-selecting it
+ * from a *different* panel still updates `source`, because that is exactly the
+ * fact the diagram needs in order to decide whether to mark its canvas.
+ */
+function next(selection: Selection | null, source: SelectionSource) {
+  return (state: SelectionState): Partial<SelectionState> => {
+    if (sameSelection(state.selection, selection) && state.source === source) {
+      return state;
+    }
+    return { selection, source };
+  };
+}
+
+export const useSelection = (): Selection | null =>
+  useSelectionStore((s) => s.selection);

package/src/selection/sync.tsx

@@ -0,0 +1,99 @@
+// Keeps the selection, the URL and the route in step.
+//
+// Three rules, and no fourth: a selection in the URL wins on arrival; a
+// selection in the store is written back to the URL with `replace`, so cycling
+// through steps does not bury the back button; and a navigation that lands on a
+// page which cannot show the selection drops it.
+
+import { useEffect, useRef } from "react";
+import { useLocation, useNavigate } from "react-router";
+import { parseSelectionHash, selectionHash } from "./hash";
+import { sameSelection } from "./model";
+import { pageContains } from "./pages";
+import { useSelection, useSelectionStore } from "./store";
+
+const SEL = "#sel=";
+
+function isFormField(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  return (
+    target.tagName === "INPUT" ||
+    target.tagName === "TEXTAREA" ||
+    target.tagName === "SELECT" ||
+    target.isContentEditable
+  );
+}
+
+export function SelectionSync() {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const selection = useSelection();
+  const last = useRef({ pathname: "", hash: "" });
+
+  // --- URL -> store -------------------------------------------------------
+  useEffect(() => {
+    const previous = last.current;
+    last.current = { pathname: location.pathname, hash: location.hash };
+    const store = useSelectionStore.getState();
+
+    const parsed = parseSelectionHash(location.hash);
+    if (parsed) {
+      if (!sameSelection(parsed, store.selection)) store.set(parsed, "url");
+      return;
+    }
+
+    if (!store.selection) return;
+
+    // A move to another page keeps the selection only if the new page can
+    // point at it; the hash is re-stamped below when it can.
+    if (previous.pathname !== location.pathname) {
+      if (!pageContains(location.pathname, store.selection)) {
+        store.clear("page");
+      }
+      return;
+    }
+
+    // Same page, and the selection left the URL for *nothing* — history moved,
+    // not us. A hash that is some other anchor is a reader jumping to a section
+    // of the page they are already on, which is not a deselection.
+    if (previous.hash.startsWith(SEL) && location.hash === "") {
+      store.clear("url");
+    }
+  }, [location.pathname, location.hash]);
+
+  // --- store -> URL -------------------------------------------------------
+  useEffect(() => {
+    // Read through to the store rather than using the value this render
+    // captured. Both effects run after the same commit, in order, and the one
+    // above has just written the selection it parsed out of the hash — a stale
+    // `null` read here would strip that hash straight back off on first load.
+    const current = useSelectionStore.getState().selection;
+    const want = selectionHash(current);
+    if (location.hash === want) return;
+    // Anchors that are not ours — a section link, a readme outline entry — are
+    // left alone, selection or no selection. Stamping #sel= over one would
+    // scroll the reader back off the section they just asked for, and the
+    // selection is not lost by being absent from the URL for a moment.
+    if (location.hash !== "" && !location.hash.startsWith(SEL)) return;
+    if (!current && !location.hash.startsWith(SEL)) return;
+    navigate(
+      { pathname: location.pathname, search: location.search, hash: want },
+      { replace: true },
+    );
+  }, [selection, location.pathname, location.search, location.hash, navigate]);
+
+  // --- Esc clears ---------------------------------------------------------
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Escape" || e.defaultPrevented) return;
+      if (isFormField(e.target)) return;
+      if (useSelectionStore.getState().selection) {
+        useSelectionStore.getState().clear("panel");
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, []);
+
+  return null;
+}

package/src/table/ColumnsMenu.tsx

@@ -0,0 +1,72 @@
+// Which columns are on screen.
+//
+// Only offered above five columns: below that, every column fits, and a menu
+// for hiding one of four is a menu that exists to be discovered rather than
+// used. The primary column never appears here - hiding the column that names
+// the row leaves a table of attributes belonging to nothing.
+
+import { Menu, MenuButton, MenuItem, MenuItems } from "@headlessui/react";
+import { Check, Columns3 } from "lucide-react";
+
+export interface ColumnToggle {
+  id: string;
+  header: string;
+  visible: boolean;
+}
+
+export function ColumnsMenu({
+  columns,
+  onToggle,
+}: {
+  columns: readonly ColumnToggle[];
+  onToggle: (id: string) => void;
+}) {
+  return (
+    <Menu>
+      <MenuButton
+        aria-label="Choose columns"
+        title="Choose columns"
+        className={({ open }) => `tbtn ${open ? "tbtn-on" : ""}`}
+      >
+        <Columns3 size={13} aria-hidden />
+        columns
+      </MenuButton>
+      <MenuItems
+        anchor={{ to: "bottom end", gap: 4, padding: 8 }}
+        className="palette-in z-50 max-h-72 min-w-44 overflow-y-auto rounded-control border bg-canvas py-1 border-line-strong shadow-md focus:outline-none"
+      >
+        {columns.map((column) => (
+          <MenuItem key={column.id}>
+            {({ focus }) => (
+              <button
+                type="button"
+                /* The menu stays open: choosing columns is choosing several,
+                   and a menu that closes on each pick is four trips for four
+                   columns. */
+                onClick={(event) => {
+                  event.preventDefault();
+                  onToggle(column.id);
+                }}
+                aria-pressed={column.visible}
+                className={`mono flex w-full cursor-pointer items-center gap-2 px-2 py-1 text-left ${
+                  focus ? "bg-raised" : ""
+                }`}
+              >
+                <Check
+                  size={12}
+                  aria-hidden
+                  className="shrink-0"
+                  style={{
+                    opacity: column.visible ? 1 : 0,
+                    color: "var(--accent)",
+                  }}
+                />
+                <span className="truncate">{column.header}</span>
+              </button>
+            )}
+          </MenuItem>
+        ))}
+      </MenuItems>
+    </Menu>
+  );
+}