@shortlink-org/portolan 0.2.1 → 0.2.3

package/src/selection/DetailPanel.tsx

@@ -19,6 +19,7 @@ import { useNarrow } from "../app/responsive";
 import { useUiStore } from "../app/ui-store";
 import { catalog, index } from "../data";
 import {
+  allRepos,
   blockFields,
   columnId,
   columnNameOfId,
@@ -29,9 +30,11 @@ import {
   viewReads,
 } from "../catalog";
 import { flowsForService, usesOfDef } from "../lib/derive";
+import { stepLabel } from "../flow/labels";
 import { KIND_LABEL } from "../lib/kinds";
 import { eventScope, resolveShape } from "../lib/shape";
 import { stepsInto } from "../lib/backlinks";
+import { treeHref } from "../lib/source-link";
 import { walkSteps } from "../catalog";
 import { methodCount } from "../lib/api";
 import {
@@ -78,6 +81,26 @@ function Row({ children }: { children: ReactNode }) {
   return <div className="flex items-center gap-2 py-0.5">{children}</div>;
 }
 
+function PanelSection({
+  title,
+  meta,
+  children,
+}: {
+  title: string;
+  meta?: ReactNode;
+  children: ReactNode;
+}) {
+  return (
+    <section className="border-b px-3 py-3 last:border-b-0 border-line">
+      <div className="mb-2 flex items-baseline justify-between gap-3">
+        <h3 className="label">{title}</h3>
+        {meta ? <span className="mono text-muted">{meta}</span> : null}
+      </div>
+      {children}
+    </section>
+  );
+}
+
 /** The panel's own way of moving the selection, without leaving the page. */
 function SelectLink({ id, children }: { id: string; children: ReactNode }) {
   const select = useSelectionStore((s) => s.select);
@@ -699,6 +722,8 @@ function titleOf(resolved: Resolved | null, selection: Selection): string {
   switch (resolved.kind) {
     case "event":
       return resolved.event.name;
+    case "service":
+      return resolved.service.name;
     case "table":
       return resolved.table.name;
     case "view":
@@ -706,7 +731,7 @@ function titleOf(resolved: Resolved | null, selection: Selection): string {
     case "column":
       return `${resolved.view?.name ?? resolved.table?.name ?? resolved.store.slug}.${resolved.column.name}`;
     case "flow-step":
-      return resolved.step.label ?? resolved.step.ref ?? resolved.step.kind;
+      return stepLabel(resolved.step);
     case "bundle":
       return `${resolved.bundle.from} → ${resolved.bundle.to}`;
     // `acme/shop`, not the registry host as well: the host is the same for
@@ -842,99 +867,155 @@ function ServiceBody({
   const methods = methodCount(service);
   const events = service.aggregates.flatMap((a) => a.events);
   const unresolved = service.consumes.filter((c) => c.status === "unresolved");
+  const tree = treeHref(service.path, service, allRepos(catalog));
   // Each flow this service takes part in, opened on the first step it is
   // on either end of - where it enters the story, not the top of the rail.
   const appearances = flowsForService(catalog, service.id).map((flow) => {
     const steps = walkSteps(flow.steps);
-    const at = steps.findIndex((s) => s.from === service.id || s.to === service.id);
+    const at = steps.findIndex(
+      (s) => s.from === service.id || s.to === service.id,
+    );
     return { flow, step: at >= 0 ? steps[at] : undefined, number: at + 1 };
   });
 
   return (
-    <>
-      <Ident
-        block
-        value={`${service.repo}/${service.path}`}
-        className="mt-1.5 text-muted"
-      />
-
-      <Label>Provides</Label>
-      {/* The count opens the tab that lists the methods it counted. */}
-      <Link
-        to={`${paths.service(context.id, service.slug)}?tab=provides`}
-        className="mono rounded-control text-muted hover:text-ink"
-      >
-        <span className="tnum">{methods}</span> method
-        {methods === 1 ? "" : "s"} over{" "}
-        <span className="tnum">{service.provides.length}</span> service
-        {service.provides.length === 1 ? "" : "s"}
-      </Link>
-      {service.provides.map((p) => (
-        <Ident block key={p.id} value={p.id} className="text-muted" />
-      ))}
+    <section
+      aria-label="Service details"
+      className="overflow-hidden rounded-card border shadow-xs border-line"
+    >
+      <PanelSection title="Source">
+        <dl className="grid grid-cols-[6.5rem_minmax(0,1fr)] gap-x-4 gap-y-2">
+          <dt className="mono text-muted">Repository</dt>
+          <dd className="min-w-0">
+            <Ident block value={service.repo} className="text-ink" />
+          </dd>
+          <dt className="mono text-muted">Path</dt>
+          <dd className="min-w-0">
+            <Ident block value={service.path} className="text-ink" />
+          </dd>
+        </dl>
+        {tree ? (
+          <a
+            href={tree}
+            target="_blank"
+            rel="noreferrer"
+            className="mono mt-2 inline-flex items-center rounded-control border px-2 py-1 border-line bg-canvas text-accent hover:bg-raised"
+            title="Open the service directory on the forge, at the built commit"
+          >
+            forge ↗
+          </a>
+        ) : null}
+      </PanelSection>
 
-      <Label>Consumes</Label>
-      {service.consumes.length === 0 ? (
-        <div className="mono text-muted">this service calls nobody</div>
-      ) : null}
-      {service.consumes.map((call) => (
-        <Row key={call.id}>
-          <Ident value={call.id} />
-          <span className="ml-auto shrink-0">
-            <StatusChip status={call.status} title={call.note} />
-          </span>
-        </Row>
-      ))}
-      {unresolved.length > 0 ? (
+      <PanelSection
+        title="Provides"
+        meta={`${methods} method${methods === 1 ? "" : "s"}`}
+      >
+        {/* The count opens the tab that lists the interfaces it counted. */}
         <Link
-          to={paths.problems()}
-          className="mono mt-1 block rounded-control text-unresolved hover:underline"
+          to={`${paths.service(context.id, service.slug)}?tab=provides`}
+          className="mono rounded-control text-muted hover:text-ink hover:underline"
         >
-          <span className="tnum">{unresolved.length}</span> call
-          {unresolved.length === 1 ? "" : "s"} resolve to nothing in the catalog
-          →
+          {service.provides.length} interface
+          {service.provides.length === 1 ? "" : "s"} →
         </Link>
-      ) : null}
+        {service.provides.length > 0 ? (
+          <div className="mt-2 flex flex-col gap-1">
+            {service.provides.map((provided) => (
+              <Ident
+                block
+                key={provided.id}
+                value={provided.id}
+                className="text-ink"
+              />
+            ))}
+          </div>
+        ) : null}
+      </PanelSection>
 
-      <Label>Publishes</Label>
-      {events.length === 0 ? (
-        <div className="mono text-muted">no events</div>
-      ) : null}
-      {events.map((e) => (
-        <Row key={e.id}>
-          <SelectLink id={e.id}>{e.name}</SelectLink>
+      <PanelSection
+        title="Consumes"
+        meta={`${service.consumes.length} call${service.consumes.length === 1 ? "" : "s"}`}
+      >
+        {service.consumes.length === 0 ? (
+          <div className="mono text-muted">this service calls nobody</div>
+        ) : (
+          <div className="flex flex-col gap-1.5">
+            {service.consumes.map((call) => (
+              <div key={call.id} className="flex flex-wrap items-center gap-2">
+                <Ident value={call.id} />
+                <StatusChip status={call.status} title={call.note} />
+              </div>
+            ))}
+          </div>
+        )}
+        {unresolved.length > 0 ? (
           <Link
-            to={`${eventPathOf(e.id) ?? paths.service(context.id, service.slug)}#${EVENT_ANCHOR.consumers}`}
-            title={`${e.consumers.length} consumers of ${e.name}`}
-            className="mono tnum ml-auto shrink-0 rounded-control text-muted hover:text-ink"
+            to={paths.problems()}
+            className="mono mt-2 block rounded-control text-unresolved hover:underline"
           >
-            {e.consumers.length}
+            <span className="tnum">{unresolved.length}</span> call
+            {unresolved.length === 1 ? "" : "s"} resolve to nothing in the
+            catalog →
           </Link>
-        </Row>
-      ))}
+        ) : null}
+      </PanelSection>
 
-      <Label>Appears in flows</Label>
-      {appearances.length === 0 ? (
-        <div className="mono text-muted">appears in no flow</div>
-      ) : (
-        <div className="flex flex-col gap-1">
-          {appearances.map(({ flow, step, number }) => (
-            <Link
-              key={flow.slug}
-              to={step ? paths.flowStep(flow.slug, step.id) : paths.flow(flow.slug)}
-              className="mono text-accent"
-              title={step ? `${flow.name}, from step ${number}` : flow.name}
-            >
-              {flow.slug}
-              {step ? ` · step ${number}` : ""} →
-            </Link>
-          ))}
-        </div>
-      )}
+      <PanelSection
+        title="Publishes"
+        meta={`${events.length} event${events.length === 1 ? "" : "s"}`}
+      >
+        {events.length === 0 ? (
+          <div className="mono text-muted">no events</div>
+        ) : (
+          <div className="flex flex-col gap-1.5">
+            {events.map((event) => (
+              <div key={event.id} className="flex flex-wrap items-center gap-2">
+                <SelectLink id={event.id}>{event.name}</SelectLink>
+                <Link
+                  to={`${eventPathOf(event.id) ?? paths.service(context.id, service.slug)}#${EVENT_ANCHOR.consumers}`}
+                  title={`${event.consumers.length} consumers of ${event.name}`}
+                  className="mono tnum shrink-0 rounded-control text-muted hover:text-ink"
+                >
+                  {event.consumers.length} consumers
+                </Link>
+              </div>
+            ))}
+          </div>
+        )}
+      </PanelSection>
 
-      <Label>Context</Label>
-      <SelectLink id={context.id}>{context.id}</SelectLink>
-    </>
+      <PanelSection title="Appears in flows" meta={appearances.length}>
+        {appearances.length === 0 ? (
+          <div className="mono text-muted">appears in no flow</div>
+        ) : (
+          <div className="flex flex-col gap-1.5">
+            {appearances.map(({ flow, step, number }) => (
+              <Link
+                key={flow.slug}
+                to={
+                  step
+                    ? paths.flowStep(flow.slug, step.id)
+                    : paths.flow(flow.slug)
+                }
+                className="mono flex min-w-0 flex-wrap items-baseline gap-x-2 text-accent"
+                title={step ? `${flow.name}, from step ${number}` : flow.name}
+              >
+                <span className="min-w-0 truncate">{flow.slug}</span>
+                {step ? (
+                  <span className="shrink-0 text-muted">step {number}</span>
+                ) : null}
+                <span aria-hidden>→</span>
+              </Link>
+            ))}
+          </div>
+        )}
+      </PanelSection>
+
+      <PanelSection title="Context">
+        <SelectLink id={context.id}>{context.id}</SelectLink>
+      </PanelSection>
+    </section>
   );
 }
 
@@ -1066,16 +1147,7 @@ function FlowStepBody({
 }: {
   resolved: Extract<Resolved, { kind: "flow-step" }>;
 }) {
-  return (
-    <>
-      <div className="mono mt-1 mb-2 flex items-center gap-2 text-muted">
-        <Link to={paths.flow(resolved.flow.slug)} className="text-accent">
-          {resolved.flow.slug}
-        </Link>
-      </div>
-      <StepDetailBody step={resolved.step} flow={resolved.flow} />
-    </>
-  );
+  return <StepDetailBody step={resolved.step} flow={resolved.flow} />;
 }
 
 /**
@@ -1208,6 +1280,42 @@ function pinFor(
   }
 }
 
+function DetailNavigation({
+  resolved,
+  page,
+}: {
+  resolved: Resolved | null;
+  page: string | null;
+}) {
+  if (!page) return null;
+
+  const flowStep = resolved?.kind === "flow-step" ? resolved : null;
+  const destination =
+    flowStep?.flow.slug ??
+    (resolved?.kind === "service" ? "service page" : "catalog page");
+
+  return (
+    <nav
+      aria-label="Selection navigation"
+      className="my-3 flex min-w-0 items-center gap-2 rounded-control border px-2.5 py-2 border-line bg-surface"
+    >
+      <span className="label shrink-0">{flowStep ? "Flow" : "Page"}</span>
+      <span className="mono trunc text-muted" title={destination}>
+        {destination}
+      </span>
+      <Link
+        to={page}
+        className="mono ml-auto inline-flex shrink-0 items-center rounded-control border px-2 py-1 border-line-strong bg-canvas text-accent t-micro transition-colors hover:bg-raised"
+      >
+        {flowStep ? "open flow" : "open"}
+        <span aria-hidden className="ml-1">
+          →
+        </span>
+      </Link>
+    </nav>
+  );
+}
+
 export function DetailPanel() {
   const selection = useSelectionStore((s) => s.selection);
   const clear = useSelectionStore((s) => s.clear);
@@ -1225,34 +1333,33 @@ export function DetailPanel() {
       className="panel-in pane flex h-full w-full flex-col border-l border-line bg-canvas"
       aria-label="Selection detail"
     >
-      <div className="sticky-bar flex shrink-0 items-center gap-2 border-b px-4 py-2.5 border-line">
+      <div className="sticky-bar sticky top-0 z-10 flex shrink-0 items-center gap-2 border-b px-4 py-2 border-line">
         <span className="label">{kindLabel(selection, resolved)}</span>
         {resolved?.kind === "flow-step" ? (
           <StatusChip status={resolved.step.status} />
         ) : null}
-        {/* Right-aligned beside the close: both are about the panel rather
-            than about what is in it. */}
-        {pin ? (
-          <span className="ml-auto flex items-center">
-            <PinButton kind={pin.kind} id={pin.id} size={14} />
-          </span>
-        ) : null}
-        <button
-          type="button"
-          onClick={() => clear("panel")}
-          aria-label="Close selection detail (Esc)"
-          title="Esc"
-          className="rounded-control p-1 text-muted t-micro transition-colors hover:bg-surface hover:text-ink"
-        >
-          <X size={16} aria-hidden />
-        </button>
+        {/* Panel controls own the far edge even when this selection cannot be
+            pinned. The close button used to sit immediately after the status
+            in that case, which made it look attached to the status itself. */}
+        <div className="ml-auto flex shrink-0 items-center gap-1">
+          {pin ? <PinButton kind={pin.kind} id={pin.id} size={14} /> : null}
+          <button
+            type="button"
+            onClick={() => clear("panel")}
+            aria-label="Close selection detail (Esc)"
+            title="Close · Esc"
+            className="inline-flex size-7 items-center justify-center rounded-control border border-transparent text-muted t-micro transition-colors hover:border-line hover:bg-surface hover:text-ink"
+          >
+            <X size={16} aria-hidden />
+          </button>
+        </div>
       </div>
 
       <div className="flex-1 overflow-y-auto p-4">
         <div className="flex flex-wrap items-baseline gap-x-2">
-          <span className="mono break-all text-sm text-ink">
+          <h2 className="mono break-all text-sm font-medium text-ink">
             {titleOf(resolved, selection)}
-          </span>
+          </h2>
           {resolved?.kind === "event" ||
           resolved?.kind === "service" ||
           resolved?.kind === "aggregate" ? (
@@ -1274,14 +1381,7 @@ export function DetailPanel() {
           <Ident block value={selection.id} className="mt-0.5 text-muted" />
         ) : null}
 
-        {page ? (
-          <Link
-            to={page}
-            className="mono mt-3 inline-block rounded-control text-accent hover:underline"
-          >
-            open page →
-          </Link>
-        ) : null}
+        <DetailNavigation resolved={resolved} page={page} />
 
         {resolved === null ? (
           <UnknownBody selection={selection} />

package/src/selection/pages.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { pageContains, selectionPath } from "./pages";
+import { pageContains, selectionPath, selectsInPlace } from "./pages";
 import { selectionFor } from "./model";
 
 const dispatched = selectionFor("delivery.core.shipment.ShipmentDispatched");
@@ -44,6 +44,19 @@ describe("selectionPath", () => {
   });
 });
 
+describe("selectsInPlace", () => {
+  const flow = "/flows/cart-checkout";
+  const shop = selectionFor("shop");
+
+  it("selects a flow context on the flow the first time", () => {
+    expect(selectsInPlace(flow, shop, null)).toBe(true);
+  });
+
+  it("lets a repeated selection follow its link to the context page", () => {
+    expect(selectsInPlace(flow, shop, shop)).toBe(false);
+  });
+});
+
 // Navigation keeps a selection only when the page it lands on can point at it.
 // These are the cases that decide whether the palette moves the reader.
 describe("pageContains across pages", () => {

package/src/selection/pages.ts

@@ -9,7 +9,7 @@ import { walkSteps } from "../catalog";
 import { catalog, index } from "../data";
 import { paths } from "../routes";
 import type { Selection } from "./model";
-import { parseFlowStepId, resolveSelection } from "./model";
+import { parseFlowStepId, resolveSelection, sameSelection } 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 {
@@ -257,12 +257,18 @@ export function pageContains(pathname: string, selection: Selection): boolean {
  * 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.
+ * lighting the matching steps. Clicking the highlighted selection again is an
+ * explicit request to follow the tree link to its own page.
  */
 export function selectsInPlace(
   pathname: string,
   selection: Selection,
+  current: Selection | null,
 ): boolean {
   const route = parseRoute(pathname);
-  return route.kind === "flow" && pageContains(pathname, selection);
+  return (
+    !sameSelection(current, selection) &&
+    route.kind === "flow" &&
+    pageContains(pathname, selection)
+  );
 }

package/src/testing/setup.ts

@@ -0,0 +1,14 @@
+import { vi } from "vitest";
+
+// Browser navigation selects a catalog through `?catalog=`. Node has no URL,
+// so tests that exercise the shipped example estate make that same choice by
+// setting the fixture manifest's default profile explicitly.
+vi.mock("../../portolan.json", async (importOriginal) => {
+  const module = await importOriginal<{ default: Record<string, unknown> }>();
+  return {
+    default: {
+      ...module.default,
+      defaultCatalog: "example",
+    },
+  };
+});

package/vite.config.ts

@@ -7,6 +7,8 @@ import react from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
 import { nodePolyfills } from "vite-plugin-node-polyfills";
 import { publicSetupFrom } from "./src/lib/setup-info.ts";
+// @ts-expect-error plain JavaScript module intentionally has no browser types
+import { readManifest } from "./scripts/manifest.mjs";
 // The local control plane is a Node-only Vite plugin kept as plain ESM so its
 // pure discovery functions can also be tested directly.
 // @ts-expect-error plain JavaScript module intentionally has no browser types
@@ -121,7 +123,7 @@ try {
   // A clean checkout has no run to report yet. Settings says so explicitly.
 }
 const setupInfo = publicSetupFrom(
-  JSON.parse(manifestText) as unknown,
+  readManifest(resolve(workspace, "portolan.json")) as unknown,
   buildReport,
   createHash("sha256").update(manifestText).digest("hex"),
 );