@shortlink-org/portolan 0.1.0

package/src/app/App.tsx

@@ -0,0 +1,448 @@
+import { Suspense, lazy, useCallback, useEffect, useState } from "react";
+import {
+  BrowserRouter,
+  Navigate,
+  Route,
+  Routes,
+  useLocation,
+  useNavigate,
+} from "react-router";
+import type { Location } from "react-router";
+import {
+  Panel,
+  ResizeHandle,
+  SavedGroup,
+  useCanvasResize,
+  usePanelRef,
+} from "./panels";
+import { FlowDetail } from "../pages/FlowDetail";
+import { FlowIndex } from "../pages/FlowIndex";
+import { AdrIndex } from "../pages/AdrIndex";
+import { Language } from "../pages/Language";
+import { AdrDetail } from "../pages/AdrDetail";
+import { Overview } from "../pages/Overview";
+import { ContextMap } from "../pages/ContextMap";
+import { ContextPage } from "../pages/ContextPage";
+import { ServicePage } from "../pages/ServicePage";
+import { AggregatePage } from "../pages/AggregatePage";
+import { BlockPage } from "../pages/BlockPage";
+import { EnumPage } from "../pages/EnumPage";
+import { EventPage } from "../pages/EventPage";
+import { StorePage } from "../pages/StorePage";
+import { GraphPage } from "../pages/GraphPage";
+import { Problems } from "../pages/Problems";
+import { Settings } from "../pages/Settings";
+import { Changes } from "../pages/Changes";
+import { RegistryIndex } from "../pages/RegistryIndex";
+import { ModulePage } from "../pages/ModulePage";
+import { ExternalPage } from "../pages/ExternalPage";
+import { NotFoundPage } from "../pages/NotFound";
+import { CatalogFailure } from "../pages/CatalogFailure";
+import { activeCatalogProfile, catalogError } from "../data";
+import { SidePanel } from "../components/Overlay";
+import { Empty } from "../components/PageHeader";
+import { WithDetail } from "../selection/DetailPanel";
+import { SelectionSync } from "../selection/sync";
+import { Trail } from "../trail/Trail";
+import { TrailRecorder } from "../trail/record";
+import { HashScroll } from "./HashScroll";
+import { CommandPalette } from "./CommandPalette";
+import { Sidebar } from "./Sidebar";
+import { TopBar } from "./TopBar";
+import { ThemeProvider } from "./theme";
+import { DensityProvider } from "./density";
+import { useNarrow, usePhone } from "./responsive";
+import { ShortcutsSheet, useShortcuts } from "./shortcuts";
+import { Toaster } from "./toast";
+import { PeekLayer } from "../peek/PeekLayer";
+import { useUiStore } from "./ui-store";
+import { ForgeAccessProvider } from "./forge-access";
+import { QueryClientProvider } from "@tanstack/react-query";
+import { queryClient } from "./query-client";
+import { AnimatePresence, MotionProvider, m, page } from "../lib/motion";
+import { useChatUi } from "../chat/store";
+import { projectPreview } from "../lib/project-preview";
+
+// The chat is a chunk of its own, and a build with VITE_CHAT=off has no such
+// chunk: the test is on the literal Vite substitutes, so the import below is
+// dead code to the bundler and is dropped with everything it would pull in.
+const ChatPanel =
+  import.meta.env.VITE_CHAT !== "off"
+    ? lazy(() => import("../chat/ChatPanel"))
+    : null;
+
+/**
+ * What the click shows while that chunk is on its way: the same sheet, at the
+ * same width, with a word in it. A fallback of nothing meant the first "ask"
+ * on a slow line did nothing for a second and the reader clicked again.
+ */
+function ChatLoading() {
+  const phone = usePhone();
+  return (
+    <SidePanel
+      open
+      onClose={() => useChatUi.getState().setOpen(false)}
+      side="right"
+      label="Ask the catalog"
+      width={phone ? "100vw" : "min(560px,92vw)"}
+    >
+      <div className="h-full bg-canvas p-gutter text-ink">
+        <Empty>loading the chat…</Empty>
+      </div>
+    </SidePanel>
+  );
+}
+
+/**
+ * Every route, once. Rendered inside a pane on wide layouts and alone below.
+ *
+ * The location is a prop, not read from the router: while a page is on its
+ * way out the router already says the next address, and the page leaving
+ * must keep drawing the one it was.
+ */
+function AppRoutes({ location }: { location: Location }) {
+  return (
+    <Routes location={location}>
+      <Route path="/" element={<Overview />} />
+      <Route path="/flows" element={<FlowIndex />} />
+      <Route
+        path="/flows/:flow"
+        element={
+          <WithDetail id="flow">
+            <FlowDetail />
+          </WithDetail>
+        }
+      />
+      <Route path="/adrs" element={<AdrIndex />} />
+      <Route path="/language" element={<Language />} />
+      <Route path="/adrs/:adr" element={<AdrDetail />} />
+      <Route path="/problems" element={<Problems />} />
+      <Route path="/settings" element={<Settings />} />
+      <Route path="/changes" element={<Changes />} />
+      <Route path="/externals/:external" element={<ExternalPage />} />
+      {/* A module sits at the estate level, not under a service: it is
+          published by one and read by four, so hanging it off a service would
+          put one entity at four URLs. */}
+      <Route path="/registry" element={<RegistryIndex />} />
+      <Route
+        path="/registry/:module"
+        element={
+          <WithDetail id="module">
+            <ModulePage />
+          </WithDetail>
+        }
+      />
+      <Route
+        path="/map"
+        element={
+          <WithDetail id="map">
+            <ContextMap />
+          </WithDetail>
+        }
+      />
+      <Route
+        path="/c/:context"
+        element={
+          <WithDetail id="context">
+            <ContextPage />
+          </WithDetail>
+        }
+      />
+      <Route
+        path="/c/:context/:service"
+        element={
+          <WithDetail id="service">
+            <ServicePage />
+          </WithDetail>
+        }
+      />
+      {/* Before the aggregate routes: "data" is a literal sitting where an
+          aggregate slug would, and "/c/x/y/data/z" would otherwise be read as
+          the event "z" of an aggregate called "data". */}
+      <Route
+        path="/c/:context/:service/data/:store"
+        element={
+          <WithDetail id="store">
+            <StorePage />
+          </WithDetail>
+        }
+      />
+      <Route
+        path="/c/:context/:service/:aggregate"
+        element={<AggregatePage />}
+      />
+      {/* The two literal segments come first: a block page must not be
+          read as an event whose slug happens to be "vo". */}
+      <Route
+        path="/c/:context/:service/:aggregate/vo/:block"
+        element={<BlockPage kind="vo" />}
+      />
+      <Route
+        path="/c/:context/:service/:aggregate/entity/:block"
+        element={<BlockPage kind="entity" />}
+      />
+      <Route
+        path="/c/:context/:service/:aggregate/enum/:enum"
+        element={<EnumPage />}
+      />
+      <Route
+        path="/c/:context/:service/:aggregate/:event"
+        element={
+          <WithDetail id="event">
+            <EventPage />
+          </WithDetail>
+        }
+      />
+      <Route
+        path="/graph"
+        element={
+          <WithDetail id="graph">
+            <GraphPage />
+          </WithDetail>
+        }
+      />
+      <Route path="/index.html" element={<Navigate to="/" replace />} />
+      <Route path="*" element={<NotFoundPage />} />
+    </Routes>
+  );
+}
+
+/**
+ * The catalog tree as an overlay, below the narrow breakpoint. It is the same
+ * Sidebar; only the box around it changes, so nothing about the tree has two
+ * implementations.
+ */
+function SidebarDrawer() {
+  const open = useUiStore((s) => s.drawer);
+  const setDrawer = useUiStore((s) => s.setDrawer);
+  const { pathname } = useLocation();
+
+  // Navigating is what the tree is for, so a click that moves the reader ends
+  // the drawer's job. Without this the page they asked for is behind a scrim.
+  useEffect(() => setDrawer(false), [pathname, setDrawer]);
+
+  return (
+    <SidePanel
+      open={open}
+      onClose={() => setDrawer(false)}
+      side="left"
+      label="Catalog"
+      width="min(320px,85vw)"
+    >
+      <Sidebar />
+    </SidePanel>
+  );
+}
+
+function Shell() {
+  const [palette, setPalette] = useState(false);
+  const [help, setHelp] = useState(false);
+  const chatOpen = useChatUi((s) => s.open);
+  const [railed, setRailed] = useState(false);
+  const location = useLocation();
+  const navigate = useNavigate();
+  const { pathname } = location;
+  const settle = useCanvasResize();
+  const sidebarRef = usePanelRef();
+  const narrow = useNarrow();
+  const toggleDrawer = useUiStore((s) => s.toggleDrawer);
+  const setDrawer = useUiStore((s) => s.setDrawer);
+  const toggleDetail = useUiStore((s) => s.toggleDetail);
+  const revealNonce = useUiStore((s) => s.revealNonce);
+
+  // Keep the selected catalog shareable even though most route builders do
+  // not know about presentation state. Changing the profile itself reloads
+  // the bundle; ordinary navigation only restores its URL marker.
+  useEffect(() => {
+    const params = new URLSearchParams(location.search);
+    if (params.get("catalog") === activeCatalogProfile.id) return;
+    params.set("catalog", activeCatalogProfile.id);
+    navigate(
+      { pathname: location.pathname, search: `?${params}`, hash: location.hash },
+      { replace: true },
+    );
+  }, [location.hash, location.pathname, location.search, navigate]);
+
+  // Collapsed is a fact about pixels, not about who dragged: the rail appears
+  // whether the reader dragged past the minimum or pressed a rail button.
+  const onSidebarResize = useCallback(
+    (size: { inPixels: number }) => setRailed(size.inPixels <= 56),
+    [],
+  );
+
+  // The rail's buttons ask the panel to expand; `railed` then follows from the
+  // resize that answers, so the flag can never disagree with the layout.
+  //
+  // `expand()` restores the width the panel had before it collapsed, which
+  // after a drag all the way to the edge is the minimum - a tree too narrow to
+  // read the names in. Anything at or under the minimum is treated as "no
+  // remembered width" and goes back to the default instead.
+  const expandSidebar = useCallback(() => {
+    const panel = sidebarRef.current;
+    if (!panel) return;
+    panel.expand();
+    if (panel.getSize().asPercentage <= 13) panel.resize("18");
+  }, [sidebarRef]);
+
+  // A layout restored from a previous session can arrive already collapsed,
+  // and no resize fires for a size that never changed - so the rail has to be
+  // read off the panel once on mount, or the full tree renders into 48px.
+  useEffect(() => {
+    setRailed(sidebarRef.current?.isCollapsed() ?? false);
+  }, [sidebarRef]);
+
+  // "[" means the same thing at both widths - show me the tree, or stop
+  // showing it - and reaches for whichever mechanism is on screen.
+  const toggleSidebar = useCallback(() => {
+    if (narrow) {
+      toggleDrawer();
+      return;
+    }
+    const panel = sidebarRef.current;
+    if (!panel) return;
+    if (panel.isCollapsed()) expandSidebar();
+    else panel.collapse();
+  }, [narrow, toggleDrawer, sidebarRef, expandSidebar]);
+
+  // "Reveal in tree" selects; the tree then opens its own ancestors and scrolls
+  // itself. The one thing it cannot do from inside a collapsed pane is become
+  // visible, which is this.
+  useEffect(() => {
+    if (revealNonce === 0) return;
+    if (narrow) setDrawer(true);
+    else if (sidebarRef.current?.isCollapsed()) expandSidebar();
+  }, [revealNonce, narrow, setDrawer, sidebarRef, expandSidebar]);
+
+  useShortcuts(
+    {
+      openPalette: () => setPalette(true),
+      openHelp: () => setHelp(true),
+      toggleSidebar,
+      toggleDetail,
+    },
+    // While a modal owns the keyboard the global bindings stand down; ⌘K and
+    // Esc are handled inside the modals themselves.
+    !palette && !help && !chatOpen,
+  );
+
+  return (
+    <div className="flex h-full flex-col bg-canvas text-ink">
+      <SelectionSync />
+      <TrailRecorder />
+      <HashScroll />
+      <TopBar
+        onOpenPalette={() => setPalette(true)}
+        onOpenHelp={() => setHelp(true)}
+        onToggleSidebar={toggleSidebar}
+        narrow={narrow}
+      />
+      {projectPreview ? (
+        <div className="shrink-0 border-b border-declared/40 bg-declared/10 px-gutter py-2 text-center text-sm text-declared">
+          Temporary project preview · the repository has not been changed · expires after 15 minutes
+        </div>
+      ) : null}
+      {/* Under the bar, above everything: the trail is about the whole shell,
+          not about the page inside it. */}
+      <Trail />
+
+      {narrow ? (
+        <>
+          {/* `key` on the route content is what makes the page transition
+              fire: a new pathname is a new element. The old one leaves first,
+              on the micro duration, then the new one rises. */}
+          <AnimatePresence mode="wait">
+            <m.main
+              key={pathname}
+              {...page}
+              className="min-h-0 flex-1 overflow-hidden"
+            >
+              <AppRoutes location={location} />
+            </m.main>
+          </AnimatePresence>
+          <SidebarDrawer />
+        </>
+      ) : (
+        <SavedGroup
+          id="portolan:shell"
+          orientation="horizontal"
+          className="min-h-0 flex-1"
+        >
+          <Panel
+            id="sidebar"
+            defaultSize="18"
+            minSize="12"
+            maxSize="28"
+            collapsible
+            collapsedSize="48px"
+            className="h-full text-sm"
+            panelRef={sidebarRef}
+            onResize={onSidebarResize}
+          >
+            <Sidebar railed={railed} onExpand={expandSidebar} />
+          </Panel>
+
+          <ResizeHandle id="shell" />
+
+          {/* The main pane owns a canvas on most routes, so a drag here has to
+              reach the diagram - debounced, once the reader lets go. */}
+          <Panel id="main" className="h-full min-w-0" onResize={settle}>
+            {/* The detail rail rides along with every page that draws a
+                diagram, so a selection made anywhere has somewhere to be read. */}
+            <AnimatePresence mode="wait">
+              <m.main
+                key={pathname}
+                {...page}
+                className="h-full overflow-hidden"
+              >
+                <AppRoutes location={location} />
+              </m.main>
+            </AnimatePresence>
+          </Panel>
+        </SavedGroup>
+      )}
+
+      <CommandPalette open={palette} onClose={() => setPalette(false)} />
+      <ShortcutsSheet open={help} onClose={() => setHelp(false)} />
+      {ChatPanel && chatOpen ? (
+        <Suspense fallback={<ChatLoading />}>
+          <ChatPanel />
+        </Suspense>
+      ) : null}
+      {/* The one thing the app says out loud, and it says it here rather than
+          in the sidebar: a pin can be taken from a page whose tree is folded
+          away to a 48px rail. */}
+      <Toaster />
+      {/* A card on hover, for any row that names an entity. Mounted once,
+          here, because the rows it answers for are on every page. */}
+      <PeekLayer />
+    </div>
+  );
+}
+
+export function App() {
+  // A catalog that failed validation is the whole app's answer, so it is
+  // decided above the router: there is no route worth reaching.
+  if (catalogError) {
+    return (
+      <ThemeProvider>
+        <CatalogFailure error={catalogError} />
+      </ThemeProvider>
+    );
+  }
+
+  return (
+    <ThemeProvider>
+      <MotionProvider>
+        <DensityProvider>
+          <QueryClientProvider client={queryClient}>
+            <ForgeAccessProvider>
+              <BrowserRouter basename={import.meta.env.BASE_URL}>
+                <Shell />
+              </BrowserRouter>
+            </ForgeAccessProvider>
+          </QueryClientProvider>
+        </DensityProvider>
+      </MotionProvider>
+    </ThemeProvider>
+  );
+}

package/src/app/BranchPicker.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { branchCompareHref } from "../lib/branch-compare";
+import type { BuildInfo } from "../lib/build-info";
+
+const BUILD: BuildInfo = {
+  commit: "abc",
+  shortCommit: "abc",
+  branch: "feature/catalog",
+  builtAt: "",
+  commitUrl: "",
+  buildUrl: "",
+  buildNumber: "",
+  dirty: false,
+  repoUrl: "https://github.com/acme/portolan/",
+};
+
+describe("branchCompareHref", () => {
+  it("builds a GitHub comparison without losing slashes in branch names", () => {
+    expect(branchCompareHref("main", "feature/catalog", BUILD)).toBe(
+      "https://github.com/acme/portolan/compare/main...feature%2Fcatalog",
+    );
+  });
+
+  it("uses GitLab's namespaced comparison route", () => {
+    expect(
+      branchCompareHref("main", "feature", {
+        ...BUILD,
+        repoUrl: "https://gitlab.com/acme/portolan",
+      }),
+    ).toBe("https://gitlab.com/acme/portolan/-/compare/main...feature");
+  });
+
+  it("uses GitLab's route for self-hosted repositories", () => {
+    expect(
+      branchCompareHref("main", "feature", {
+        ...BUILD,
+        forge: "gitlab",
+        repoUrl: "https://code.example.com/acme/portolan",
+      }),
+    ).toBe("https://code.example.com/acme/portolan/-/compare/main...feature");
+  });
+
+  it("does not offer a comparison for the same branch", () => {
+    expect(branchCompareHref("main", "main", BUILD)).toBeNull();
+  });
+});

package/src/app/BranchPicker.tsx

@@ -0,0 +1,153 @@
+import {
+  Listbox,
+  ListboxButton,
+  ListboxOption,
+  ListboxOptions,
+} from "@headlessui/react";
+import { Check, ChevronDown, ExternalLink, GitBranch, LoaderCircle, Tag } from "lucide-react";
+import { useQuery } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { Link, useLocation, useNavigate, useSearchParams } from "react-router";
+import { branchCompareHref } from "../lib/branch-compare";
+import { buildInfo } from "../lib/build-info";
+import { findRef, sortRefs } from "../lib/forge-refs";
+import { forgeRepoFromUrl } from "../lib/github-catalog";
+import type { ForgeRef } from "../lib/github-catalog";
+import { forgetComparison, rememberComparison } from "../lib/comparison-memory";
+import { forgeRefsQuery } from "../lib/queries";
+import { paths } from "../routes";
+import { useForgeAccess } from "./forge-access";
+
+const NO_REFS: ForgeRef[] = [];
+
+function refNote(ref: ForgeRef, current: string): string {
+  if (ref.kind === "branch" && ref.name === current) return `${ref.commit.slice(0, 7)} · current catalog`;
+  return `${ref.commit.slice(0, 7)}${ref.protected ? " · protected" : ""}`;
+}
+
+/**
+ * Selects the comparison head. Branches and tags are read from the configured forge at
+ * runtime; a choice opens the first-class changes route, whose URL carries both heads.
+ */
+export function BranchPicker({ compact = false }: { compact?: boolean }) {
+  const current = buildInfo.branch || "main";
+  const repo = forgeRepoFromUrl(buildInfo.repoUrl, buildInfo.forge);
+  const access = useForgeAccess();
+  const navigate = useNavigate();
+  const { pathname } = useLocation();
+  const [search] = useSearchParams();
+  const token = repo ? access.tokenFor(repo) : "";
+  // The same query the changes page reads: whichever mounts first fetches,
+  // the other one joins it.
+  const refsQuery = useQuery(forgeRefsQuery(repo, token));
+  const remote = refsQuery.data ?? NO_REFS;
+  const loading = refsQuery.isLoading;
+  const error = refsQuery.error?.message ?? "";
+
+  const refs = useMemo(() => {
+    const known = remote.some((ref) => ref.kind === "branch" && ref.name === current)
+      ? remote
+      : [...remote, { name: current, commit: buildInfo.commit, protected: false, kind: "branch" as const }];
+    return sortRefs(known, current);
+  }, [current, remote]);
+  const branches = refs.filter((ref) => ref.kind === "branch");
+  const tags = refs.filter((ref) => ref.kind === "tag");
+
+  const requested = pathname === paths.changes() ? search.get("head") ?? "" : "";
+  const selected = findRef(refs, requested) ? requested : current;
+  const comparing = selected !== current;
+  const compareHref = branchCompareHref(current, selected);
+
+  const choose = (name: string) => {
+    if (name === current) {
+      forgetComparison();
+      navigate(paths.changes());
+      return;
+    }
+    rememberComparison(current, name);
+    const next = new URLSearchParams({ base: current, head: name });
+    navigate(`${paths.changes()}?${next}`);
+  };
+
+  return (
+    <Listbox value={selected} onChange={choose}>
+      <ListboxButton
+        aria-label={comparing ? `Compare ${current} with ${selected}` : `Branch ${current}`}
+        title={comparing ? `${current} compared with ${selected}` : `Branch ${current}`}
+        className={({ open }) =>
+          compact
+            ? `flex size-8 shrink-0 items-center justify-center rounded-control border t-micro transition-colors border-line hover:bg-surface ${open || comparing ? "text-accent" : "text-muted hover:text-ink"}`
+            : `mono flex max-w-56 shrink-0 items-center gap-1.5 rounded-control border px-2 py-1.5 t-micro transition-colors ${open || comparing ? "border-accent text-accent" : "border-line text-muted hover:border-line-strong hover:bg-surface hover:text-ink"}`
+        }
+      >
+        {({ open }) => (
+          <>
+            <GitBranch size={16} aria-hidden className="shrink-0" />
+            {!compact ? <span className="min-w-0 truncate">{comparing ? `${current} → ${selected}` : current}</span> : null}
+            {!compact ? (
+              <ChevronDown size={13} aria-hidden className={`shrink-0 t-micro transition-transform ${open ? "rotate-180" : ""}`} />
+            ) : null}
+          </>
+        )}
+      </ListboxButton>
+
+      <ListboxOptions
+        aria-label="Comparison head branch or tag"
+        anchor={{ to: "bottom end", gap: 4, padding: 8 }}
+        className="branch-options palette-in z-50 w-80 overflow-y-auto rounded-control border bg-canvas py-1 border-line-strong shadow-md focus:outline-none"
+      >
+        <div className="label px-3 pt-2 pb-1">compare {current} with</div>
+        {branches.map((ref) => <RefOption key={`branch:${ref.name}`} item={ref} current={current} />)}
+        {/* A tag and a branch can share a name; the option's value is the
+            name, which the changes route resolves branch-first, so a tag
+            shadowed that way is listed but selects the branch. */}
+        {tags.length > 0 ? (
+          <div className="label flex items-center gap-1.5 border-t border-line px-3 pt-2 pb-1">
+            <Tag size={11} aria-hidden /> tags
+          </div>
+        ) : null}
+        {tags.map((ref) => <RefOption key={`tag:${ref.name}`} item={ref} current={current} />)}
+        {loading ? (
+          <div className="mono flex items-center gap-2 border-t border-line px-3 py-2 text-muted" role="status">
+            <LoaderCircle size={13} aria-hidden className="animate-spin" /> Loading {repo?.provider === "gitlab" ? "GitLab" : "GitHub"} branches and tags…
+          </div>
+        ) : error ? (
+          <div className="border-t border-line px-3 py-2 text-sm">
+            <div className="text-unresolved">{error}</div>
+            <Link to={paths.changes()} className="mt-1 inline-block text-accent hover:underline">
+              repository access →
+            </Link>
+          </div>
+        ) : !repo ? (
+          <div className="border-t border-line px-3 py-2 text-sm text-muted">Runtime comparison needs a GitHub or GitLab repository.</div>
+        ) : null}
+        {compareHref ? (
+          <div className="sticky bottom-0 mt-1 border-t border-line bg-canvas px-3 py-2">
+            <a href={compareHref} target="_blank" rel="noreferrer" className="mono flex items-center gap-1.5 rounded-control text-accent hover:underline">
+              open comparison on {repo?.provider === "gitlab" ? "GitLab" : "GitHub"} <ExternalLink size={12} aria-hidden />
+            </a>
+          </div>
+        ) : null}
+      </ListboxOptions>
+    </Listbox>
+  );
+}
+
+function RefOption({ item, current }: { item: ForgeRef; current: string }) {
+  return (
+    <ListboxOption
+      value={item.name}
+      className={({ focus }) => `mono flex cursor-pointer items-start gap-2 px-3 py-2 ${focus ? "bg-raised" : ""}`}
+    >
+      {({ selected: on }) => (
+        <>
+          <Check size={13} aria-hidden className="mt-0.5 shrink-0 text-accent" style={{ opacity: on ? 1 : 0 }} />
+          <span className="min-w-0 flex-1">
+            <span className={`block truncate ${on ? "text-accent" : "text-ink"}`}>{item.name}</span>
+            <span className="block truncate text-muted">{refNote(item, current)}</span>
+          </span>
+        </>
+      )}
+    </ListboxOption>
+  );
+}

package/src/app/Breadcrumbs.test.ts

@@ -0,0 +1,38 @@
+// The trail under the top bar, one crumb per segment. What matters is that no
+// route falls through to nothing, and that a literal in the path - "data",
+// "vo" - is never mistaken for the name of a thing.
+
+import { describe, expect, it } from "vitest";
+import { crumbsFor } from "./Breadcrumbs";
+
+describe("crumbsFor", () => {
+  it("names the four index pages that used to have no trail", () => {
+    expect(crumbsFor("/language")).toEqual([
+      { label: "language", to: "/language" },
+    ]);
+    expect(crumbsFor("/problems")).toEqual([
+      { label: "problems", to: "/problems" },
+    ]);
+    expect(crumbsFor("/registry")).toEqual([
+      { label: "registry", to: "/registry" },
+    ]);
+    expect(crumbsFor("/registry/no-such-module").map((c) => c.to)).toEqual([
+      "/registry",
+      "/registry/no-such-module",
+    ]);
+  });
+
+  it("calls the decisions what the tree calls them", () => {
+    expect(crumbsFor("/adrs")[0]).toEqual({ label: "decisions", to: "/adrs" });
+  });
+
+  it("reads 'data' as a literal, not as an aggregate", () => {
+    const crumbs = crumbsFor("/c/ctx/svc/data/pg");
+    expect(crumbs.map((c) => c.to)).toEqual([
+      "/c/ctx",
+      "/c/ctx/svc",
+      "/c/ctx/svc/data/pg",
+    ]);
+    expect(crumbs.some((c) => c.label === "data")).toBe(false);
+  });
+});