@shortlink-org/portolan 0.1.0

package/src/app/Breadcrumbs.tsx

@@ -0,0 +1,223 @@
+import { Fragment } from "react";
+import { Link, useLocation } from "react-router";
+import { ChevronRight } from "lucide-react";
+import { catalog, index } from "../data";
+import { enumsOf } from "../catalog";
+import { adrNumber } from "../lib/adr";
+import { selectionLabel, selectionTrail } from "../selection/model";
+import { selectionPath } from "../selection/pages";
+import { useSelectionStore } from "../selection/store";
+import { paths } from "../routes";
+
+interface Crumb {
+  label: string;
+  to: string;
+}
+
+export function crumbsFor(pathname: string): Crumb[] {
+  const parts = pathname.split("/").filter(Boolean);
+  if (parts.length === 0) return [];
+
+  if (parts[0] === "flows") {
+    const crumbs: Crumb[] = [{ label: "flows", to: "/flows" }];
+    const slug = parts[1];
+    if (slug) {
+      const flow = index.flowBySlug.get(slug);
+      crumbs.push({ label: flow?.slug ?? slug, to: `/flows/${slug}` });
+    }
+    return crumbs;
+  }
+
+  if (parts[0] === "adrs") {
+    const crumbs: Crumb[] = [{ label: "decisions", to: paths.adrs() }];
+    const slug = parts[1];
+    if (slug) {
+      const adr = index.adrBySlug.get(slug);
+      crumbs.push({
+        label: adr ? adrNumber(adr) : slug,
+        to: `/adrs/${slug}`,
+      });
+    }
+    return crumbs;
+  }
+
+  if (parts[0] === "graph") return [{ label: "graph", to: "/graph" }];
+
+  if (parts[0] === "map") return [{ label: "map", to: "/map" }];
+
+  if (parts[0] === "settings")
+    return [{ label: "settings", to: paths.settings() }];
+
+  if (parts[0] === "changes")
+    return [{ label: "changes", to: paths.changes() }];
+
+  if (parts[0] === "externals") {
+    const slug = parts[1];
+    if (!slug) return [];
+    const external = (catalog.externals ?? []).find(
+      (candidate) => candidate.slug === slug,
+    );
+    return [
+      {
+        label: external?.name ?? slug,
+        to: paths.external(slug),
+      },
+    ];
+  }
+
+  if (parts[0] === "language")
+    return [{ label: "language", to: paths.language() }];
+
+  if (parts[0] === "problems")
+    return [{ label: "problems", to: paths.problems() }];
+
+  if (parts[0] === "registry") {
+    const crumbs: Crumb[] = [{ label: "registry", to: paths.registry() }];
+    const slug = parts[1];
+    if (slug) {
+      const module = index.moduleBySlug.get(slug);
+      crumbs.push({ label: module?.name ?? slug, to: paths.module(slug) });
+    }
+    return crumbs;
+  }
+
+  if (parts[0] === "c") {
+    const [, contextId, serviceSlug, aggregateSlug, eventSlug] = parts;
+    const crumbs: Crumb[] = [];
+    if (!contextId) return crumbs;
+    crumbs.push({ label: contextId, to: `/c/${contextId}` });
+    if (!serviceSlug) return crumbs;
+    crumbs.push({ label: serviceSlug, to: `/c/${contextId}/${serviceSlug}` });
+    if (!aggregateSlug) return crumbs;
+
+    // "data" is a literal too: a store hangs off its service, and the segment
+    // after it is the store slug, not an event of an aggregate called "data".
+    if (aggregateSlug === "data") {
+      const storeSlug = parts[4];
+      if (!storeSlug) return crumbs;
+      const service = catalog.contexts
+        .find((c) => c.id === contextId)
+        ?.services.find((s) => s.slug === serviceSlug);
+      const store = (catalog.stores ?? []).find(
+        (s) => s.slug === storeSlug && s.owner === service?.id,
+      );
+      crumbs.push({
+        label: store?.name ?? storeSlug,
+        to: paths.store(contextId, serviceSlug, storeSlug),
+      });
+      return crumbs;
+    }
+
+    crumbs.push({
+      label: aggregateSlug,
+      to: `/c/${contextId}/${serviceSlug}/${aggregateSlug}`,
+    });
+    if (!eventSlug) return crumbs;
+    const aggregate = catalog.contexts
+      .find((c) => c.id === contextId)
+      ?.services.find((s) => s.slug === serviceSlug)
+      ?.aggregates.find((a) => a.slug === aggregateSlug);
+
+    // "vo", "entity" and "enum" are literals, not slugs: one more segment follows.
+    if (eventSlug === "vo" || eventSlug === "entity" || eventSlug === "enum") {
+      const blockSlug = parts[5];
+      if (!blockSlug) return crumbs;
+      const list =
+        eventSlug === "vo"
+          ? aggregate?.valueObjects
+          : eventSlug === "entity"
+            ? aggregate?.entities
+            : aggregate
+              ? enumsOf(aggregate)
+              : undefined;
+      const block = list?.find((b) => b.slug === blockSlug);
+      crumbs.push({
+        label: block?.name ?? blockSlug,
+        to: `/c/${contextId}/${serviceSlug}/${aggregateSlug}/${eventSlug}/${blockSlug}`,
+      });
+      return crumbs;
+    }
+
+    const event = aggregate?.events.find((e) => e.slug === eventSlug);
+    crumbs.push({
+      label: event?.name ?? eventSlug,
+      to: `/c/${contextId}/${serviceSlug}/${aggregateSlug}/${eventSlug}`,
+    });
+    return crumbs;
+  }
+
+  return [];
+}
+
+export function Breadcrumbs() {
+  const { pathname } = useLocation();
+  const crumbs = crumbsFor(pathname);
+
+  const selection = useSelectionStore((s) => s.selection);
+  const select = useSelectionStore((s) => s.select);
+
+  // The route says where the reader is; the selection says what they are
+  // looking at, and the two are often not the same thing - an event picked
+  // while a flow is open, say. The selection trail is appended rather than
+  // substituted so neither answer is lost.
+  const alreadyOnRoute =
+    selection !== null &&
+    selection.kind !== "flow-step" &&
+    selectionPath(selection) === pathname;
+  // Only the part of the trail the route does not already say. Repeating
+  // "shop > oms" either side of the marker is noise, not information.
+  const onRoute = new Set(crumbs.map((c) => c.to));
+  const full = selection && !alreadyOnRoute ? selectionTrail(selection) : [];
+  const trail = full.filter(
+    (step) =>
+      step.kind === "flow-step" || !onRoute.has(selectionPath(step) ?? ""),
+  );
+
+  return (
+    <div className="mono flex min-w-0 items-center gap-1 truncate">
+      <Link to="/" className="hover:underline text-muted">
+        portolan
+      </Link>
+      {crumbs.map((crumb, i) => (
+        <Fragment key={crumb.to}>
+          <ChevronRight size={11} aria-hidden className="text-line-strong" />
+          <Link
+            to={crumb.to}
+            className={`truncate hover:underline ${i === crumbs.length - 1 && trail.length === 0 ? "text-ink" : "text-muted"}`}
+          >
+            {crumb.label}
+          </Link>
+        </Fragment>
+      ))}
+
+      {trail.length > 0 ? (
+        <>
+          <span
+            aria-hidden
+            title="selected"
+            className="mx-1 size-1.5 shrink-0"
+            style={{ background: "var(--accent)" }}
+          />
+          {trail.map((step, i) => (
+            <Fragment key={step.id}>
+              {i > 0 ? (
+                <ChevronRight
+                  size={11}
+                  aria-hidden
+                  className="text-line-strong"
+                />
+              ) : null}
+              <button
+                type="button"
+                onClick={() => select(step.id, "breadcrumb")}
+                className={`truncate hover:underline ${i === trail.length - 1 ? "text-ink" : "text-muted"}`}
+              >
+                {selectionLabel(step)}
+              </button>
+            </Fragment>
+          ))}
+        </>
+      ) : null}
+    </div>
+  );
+}

package/src/app/BuildStamp.tsx

@@ -0,0 +1,146 @@
+import { useEffect, useState } from "react";
+import { Popover, PopoverButton, PopoverPanel } from "@headlessui/react";
+import { GitCommitHorizontal } from "lucide-react";
+import {
+  buildHref,
+  buildInfo,
+  buildLabel,
+  buildTitle,
+} from "../lib/build-info";
+import { absoluteTime, relativeTime } from "../lib/format";
+
+const BOX =
+  "mono flex items-center gap-1.5 rounded-control border px-2 py-1.5 border-line text-muted";
+
+/**
+ * What is deployed, and where to go to see it: the run that built this bundle,
+ * or the commit it was built from when nobody built it but you. It is stamped
+ * once, in the top bar, where it is one control among five and its border
+ * makes it one of them; a second copy in the sidebar said nothing new.
+ *
+ * `compact` is the phone form: the icon alone, and everything the wide stamp
+ * says in line - the commit, when it was built, the branch and the run - behind
+ * a tap. The stamp is not a control a reader reaches for often enough to spend
+ * a fifth of a phone's top bar on, but it is the one they reach for when they
+ * are asking "is what I am looking at the build I think it is", and a title
+ * attribute is not an answer on a device with no pointer to hover.
+ */
+export function BuildStamp({ compact = false }: { compact?: boolean }) {
+  const [, force] = useState(0);
+
+  // The stamp reads as relative time; nudge it once a minute.
+  useEffect(() => {
+    const t = setInterval(() => force((n) => n + 1), 60_000);
+    return () => clearInterval(t);
+  }, []);
+
+  // The stamp names a commit, so it opens the commit; the run that built it
+  // is one click further, in the checks on that page.
+  const href = buildHref();
+
+  if (compact) return <CompactStamp href={href} />;
+
+  const body = (
+    <>
+      <GitCommitHorizontal size={16} aria-hidden className="shrink-0" />
+      {buildLabel()}
+      {buildInfo.builtAt && (
+        <>
+          <span aria-hidden className="text-line-strong">
+            ·
+          </span>
+          {relativeTime(buildInfo.builtAt)}
+        </>
+      )}
+    </>
+  );
+
+  if (!href)
+    return (
+      <span className={BOX} title={buildTitle()}>
+        {body}
+      </span>
+    );
+  return (
+    <a
+      href={href}
+      target="_blank"
+      rel="noreferrer"
+      title={buildTitle()}
+      className={`${BOX} transition-colors hover:border-line-strong hover:bg-surface hover:text-ink`}
+    >
+      {body}
+    </a>
+  );
+}
+
+function CompactStamp({ href }: { href: string | null }) {
+  return (
+    <Popover className="shrink-0">
+      <PopoverButton
+        aria-label={`Build — ${buildTitle()}`}
+        title={buildTitle()}
+        className={({ open }) =>
+          `flex size-8 items-center justify-center rounded-control border t-micro transition-colors border-line hover:bg-surface ${
+            open ? "text-accent" : "text-muted hover:text-ink"
+          }`
+        }
+      >
+        <GitCommitHorizontal size={16} aria-hidden />
+      </PopoverButton>
+      <PopoverPanel
+        anchor={{ to: "bottom end", gap: 4, padding: 8 }}
+        className="palette-in z-50 w-64 rounded-control border bg-canvas p-2 border-line-strong shadow-md focus:outline-none"
+      >
+        <div className="label mb-1.5 px-1">build</div>
+        <dl className="mono grid grid-cols-[auto_1fr] gap-x-3 gap-y-1 px-1 text-muted">
+          <dt>commit</dt>
+          {/* `buildLabel` ends a dirty tree in a "+", which is what the wide
+              stamp has room to say. Here the word says it, so the sign would
+              be saying it twice. */}
+          <dd className="truncate text-ink">
+            {buildInfo.shortCommit || buildLabel()}
+            {buildInfo.dirty ? (
+              <span className="ml-1.5 text-muted">uncommitted</span>
+            ) : null}
+          </dd>
+          {buildInfo.branch ? (
+            <>
+              <dt>branch</dt>
+              <dd className="truncate text-ink">{buildInfo.branch}</dd>
+            </>
+          ) : null}
+          {buildInfo.buildNumber ? (
+            <>
+              <dt>run</dt>
+              <dd className="truncate text-ink">#{buildInfo.buildNumber}</dd>
+            </>
+          ) : null}
+          <dt>built</dt>
+          <dd className="text-ink">
+            {buildInfo.builtAt ? (
+              <>
+                {relativeTime(buildInfo.builtAt)}
+                <div className="text-muted">
+                  {absoluteTime(buildInfo.builtAt)}
+                </div>
+              </>
+            ) : (
+              "at an unrecorded time"
+            )}
+          </dd>
+        </dl>
+        {href ? (
+          <a
+            href={href}
+            target="_blank"
+            rel="noreferrer"
+            className="mono mt-2 block rounded-control px-1 py-1 text-accent hover:bg-surface"
+          >
+            open on the forge ↗
+          </a>
+        ) : null}
+      </PopoverPanel>
+    </Popover>
+  );
+}

package/src/app/CommandPalette.tsx

@@ -0,0 +1,292 @@
+// ⌘K. Everything the catalog names, in one list.
+//
+// Enter sets the selection first and navigates second, and only when the page
+// already on screen cannot show what was picked. Choosing an event while its
+// service page is open therefore opens the panel and leaves the reader where
+// they were, which is the whole point of holding selection globally.
+//
+// Rows carry the same kind icons as the sidebar tree, and the same taxonomy
+// narrows the list: "e: item" searches events, "vo: money" value objects.
+
+import { Fragment, useMemo, useRef, useState } from "react";
+import {
+  Combobox,
+  ComboboxInput,
+  ComboboxOption,
+  ComboboxOptions,
+} from "@headlessui/react";
+import { useLocation, useNavigate } from "react-router";
+import { Modal } from "../components/Overlay";
+import { catalog } from "../data";
+import { paletteItems, search } from "../lib/palette";
+import type { PaletteHit, PaletteItem } from "../lib/palette";
+import { recentSections } from "../lib/palette-recent";
+import { useTrailStore } from "../trail/store";
+import { usePinsStore } from "./pins";
+import { KIND_LABEL, KIND_PREFIXES, canonicalPrefix } from "../lib/kinds";
+import type { Kind } from "../lib/kinds";
+import { ctxStyle } from "../lib/context-color";
+import { KindIcon } from "../components/kind";
+import { pageContains, selectionPath } from "../selection/pages";
+import { selectionHash } from "../selection/hash";
+import { selectionFor } from "../selection/model";
+import { useSelectionStore } from "../selection/store";
+
+const ITEMS = paletteItems(catalog);
+
+/** The prefixes offered under an empty input. Kinds, not every spelling. */
+const HINT_KINDS: Kind[] = [
+  "event",
+  "vo",
+  "entity",
+  "aggregate",
+  "command",
+  "query",
+];
+
+/** One row of the list, drawn the same whether it was searched for or recalled. */
+function Row({ hit: { item, excerpt } }: { hit: PaletteHit }) {
+  return (
+    <ComboboxOption
+      value={{ item, ...(excerpt ? { excerpt } : {}) }}
+      /* The 2px edge is always drawn and only changes colour, so the row
+         under the cursor never nudges the text beside it. */
+      className={({ focus }) =>
+        `flex w-full cursor-pointer flex-col gap-0.5 border-l-2 px-4 py-1.5 text-left t-micro transition-colors ${
+          focus ? "bg-raised border-accent" : "border-transparent"
+        }`
+      }
+    >
+      {() => (
+        <>
+          <span className="flex w-full items-center gap-2">
+            <span className="flex shrink-0" style={ctxStyle(item.context)}>
+              <KindIcon
+                kind={item.kind}
+                {...(item.context ? { contextId: item.context } : {})}
+              />
+            </span>
+            <span
+              className="mono shrink-0"
+              title={item.name}
+              style={
+                item.kind === "event"
+                  ? { color: "var(--kind-event)" }
+                  : undefined
+              }
+            >
+              {item.name}
+            </span>
+            <span className="mono truncate text-muted" title={item.detail}>
+              {item.detail}
+            </span>
+            <span className="mono ml-auto flex shrink-0 items-center gap-2 text-muted">
+              {item.badge ? (
+                <span className="rounded-[4px] border px-1 border-line">
+                  {item.badge}
+                </span>
+              ) : null}
+              <span className="label">{KIND_LABEL[item.kind]}</span>
+            </span>
+          </span>
+          {/* Why this row is here. Sans, not mono: the line above is
+              identifiers, this one is a sentence, and the two must not be
+              mistaken for each other. */}
+          {excerpt ? (
+            <span className="w-full truncate pl-6 text-xs text-muted">
+              {excerpt.before}
+              <span style={{ color: "var(--accent)" }}>{excerpt.match}</span>
+              {excerpt.after}
+            </span>
+          ) : null}
+        </>
+      )}
+    </ComboboxOption>
+  );
+}
+
+export function CommandPalette({
+  open,
+  onClose,
+}: {
+  open: boolean;
+  onClose: () => void;
+}) {
+  const [query, setQuery] = useState("");
+  // Only so a hint chip can hand the caret back after filling the prefix in.
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const navigate = useNavigate();
+  const location = useLocation();
+  const setSelection = useSelectionStore((s) => s.set);
+
+  const result = useMemo(() => search(ITEMS, open ? query : ""), [open, query]);
+  const results = open ? result.hits : [];
+
+  // Under an empty input: where the reader has been and what they pinned,
+  // when they have either. The full index is what a reader with neither
+  // gets, and what typing anything switches back to.
+  const visits = useTrailStore((s) => s.visits);
+  const pins = usePinsStore((s) => s.pins);
+  const sections = useMemo(() => {
+    if (!open || query.trim() !== "") return null;
+    const found = recentSections(visits, pins, ITEMS, location.pathname);
+    return found.length > 0 ? found : null;
+  }, [open, query, visits, pins, location.pathname]);
+  const shown = sections
+    ? sections.reduce((n, s) => n + s.hits.length, 0)
+    : results.length;
+
+  const close = (): void => {
+    onClose();
+    // Cleared on the way out rather than on the way in: the palette unmounts,
+    // and a query left behind would flash under the next ⌘K before the effect
+    // that cleared it ran.
+    setQuery("");
+  };
+
+  const commit = (item: PaletteItem): void => {
+    close();
+
+    if (item.selectId) {
+      const selection = selectionFor(item.selectId);
+
+      // This page can already point at it: select in place and move nobody.
+      if (pageContains(location.pathname, selection)) {
+        setSelection(selection, "palette");
+        return;
+      }
+
+      // Otherwise carry the selection in the URL rather than writing it to the
+      // store first. Two writers - this handler and SelectionSync - would race
+      // for the same history entry, and the sync's `replace` would land with
+      // the pathname it had before the navigation, undoing it. A selection in
+      // the URL wins on arrival, so one write does both jobs.
+      const to = selectionPath(selection) ?? item.path;
+      if (to) navigate(`${to}${selectionHash(selection)}`);
+      else setSelection(selection, "palette");
+      return;
+    }
+
+    // Rows the selection model does not resolve - value objects, entities,
+    // commands, queries, flows, decisions - simply go to their page.
+    if (item.path && item.path !== location.pathname) navigate(item.path);
+  };
+
+  return (
+    <Modal open={open} onClose={close} label="Command palette">
+      {/* The combobox owns the list: which row is active, keeping it in view,
+          ↑↓ and ⏎, and the aria wiring that makes the input announce the row
+          under it. Escape is caught on the way DOWN, before the combobox can
+          take it - inside a modal there is nothing to close but the modal, and
+          a first Escape that only closes an invisible listbox reads as an
+          Escape that did nothing. */}
+      <div
+        className="flex min-h-0 flex-col"
+        onKeyDownCapture={(e) => {
+          if (e.key !== "Escape") return;
+          e.preventDefault();
+          e.stopPropagation();
+          close();
+        }}
+      >
+        <Combobox<PaletteHit | null>
+          value={null}
+          onChange={(hit) => {
+            if (hit) commit(hit.item);
+          }}
+          immediate
+        >
+          {/* The one accent glow the palette gets: 4%, radial, behind the input. */}
+          <ComboboxInput
+            ref={inputRef}
+            autoFocus
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            placeholder="jump to anything — or narrow with e: vo: ent: agg: cmd: q:"
+            spellCheck={false}
+            aria-label="Search the catalog"
+            className="glow mono w-full shrink-0 border-b bg-transparent px-4 py-3 text-sm outline-none border-line placeholder:text-muted"
+          />
+
+          <div className="mono flex shrink-0 flex-wrap items-center gap-x-2 gap-y-1 border-b px-4 py-2 border-line text-muted">
+            {result.kind ? (
+              <>
+                <span>only</span>
+                <span
+                  className="chip"
+                  style={{
+                    borderColor: "var(--accent)",
+                    color: "var(--accent)",
+                  }}
+                >
+                  <KindIcon kind={result.kind} />
+                  {KIND_LABEL[result.kind]}
+                </span>
+                {result.term ? <span>matching “{result.term}”</span> : null}
+              </>
+            ) : (
+              <>
+                <span>narrow to</span>
+                {HINT_KINDS.map((kind) => (
+                  <button
+                    key={kind}
+                    type="button"
+                    onClick={() => {
+                      setQuery(`${canonicalPrefix(kind)}: `);
+                      inputRef.current?.focus();
+                    }}
+                    className="inline-flex items-center gap-1 rounded-control px-0.5 t-micro transition-colors hover:text-ink"
+                    title={`${KIND_PREFIXES[kind].join(" / ")} — ${KIND_LABEL[kind]}`}
+                  >
+                    <KindIcon kind={kind} />
+                    {canonicalPrefix(kind)}:
+                  </button>
+                ))}
+              </>
+            )}
+          </div>
+
+          {shown === 0 ? (
+            <div className="glow mono px-4 py-8 text-center text-muted">
+              no match
+            </div>
+          ) : (
+            /* `static` because the list is the palette: there is no closed
+               state to render, and the modal around it is what "closed" means
+               here. */
+            <ComboboxOptions static className="min-h-0 flex-1 overflow-y-auto">
+              {sections
+                ? sections.map((section) => (
+                    <Fragment key={section.title}>
+                      {/* A heading, not an option: ↑↓ skip it, and the
+                          list reads as two short lists rather than one. */}
+                      <div className="label sticky top-0 z-10 px-4 pt-2 pb-1 bg-canvas">
+                        {section.title}
+                      </div>
+                      {section.hits.map((hit) => (
+                        <Row key={`${hit.item.kind}:${hit.item.id}`} hit={hit} />
+                      ))}
+                    </Fragment>
+                  ))
+                : results.map((hit) => (
+                    <Row key={`${hit.item.kind}:${hit.item.id}`} hit={hit} />
+                  ))}
+            </ComboboxOptions>
+          )}
+        </Combobox>
+
+        <div className="mono flex shrink-0 items-center gap-3 border-t px-4 py-2 border-line text-muted">
+          <span>↑↓ move</span>
+          <span>⏎ select</span>
+          <span>esc close</span>
+          <span className="ml-auto">
+            {shown} shown
+            {!sections && result.truncated > 0
+              ? ` · +${result.truncated} more`
+              : ""}
+          </span>
+        </div>
+      </div>
+    </Modal>
+  );
+}