@shortlink-org/portolan 0.2.1 → 0.2.3

package/src/components/CatIllustration.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from "react";
+
+type CatScene = "about" | "clear" | "unchanged" | "onboarding" | "search" | "trial";
+
+const IMAGE: Record<CatScene, string> = {
+  about: "cat-about-v1.webp",
+  clear: "cat-clear-skies-v1.webp",
+  unchanged: "cat-no-changes-v1.webp",
+  onboarding: "cat-onboarding-v1.webp",
+  search: "404-cat-v1.webp",
+  trial: "cat-trial-success-v1.webp",
+};
+
+export function CatIllustration({ scene, className = "" }: { scene: CatScene; className?: string }) {
+  return <img src={`${import.meta.env.BASE_URL}${IMAGE[scene]}`} alt="" aria-hidden draggable={false} className={`cat-illustration ${className}`} />;
+}
+
+/** A rare, positive empty state. Ordinary missing rows keep using `Empty`. */
+export function CatEmptyState({ scene, title, children, meta, className = "" }: { scene: Extract<CatScene, "clear" | "unchanged" | "onboarding">; title: string; children: ReactNode; meta?: ReactNode; className?: string }) {
+  return (
+    <div className={`cat-empty-state ${className}`}>
+      <CatIllustration scene={scene} className="cat-empty-illustration" />
+      <div className="min-w-0">
+        <h2 className="text-md font-semibold text-ink">{title}</h2>
+        <div className="mt-1 text-muted">{children}</div>
+        {meta ? <div className="mono mt-3 text-faint">{meta}</div> : null}
+      </div>
+    </div>
+  );
+}

package/src/components/CommitLink.tsx

@@ -0,0 +1,154 @@
+import { useState } from "react";
+import {
+  FloatingPortal,
+  autoUpdate,
+  flip,
+  offset,
+  shift,
+  useDismiss,
+  useFloating,
+  useFocus,
+  useHover,
+  useInteractions,
+  useRole,
+} from "@floating-ui/react";
+import { useQuery } from "@tanstack/react-query";
+import { useForgeAccess } from "../app/forge-access";
+import { buildInfo, repositoryCommitHref } from "../lib/build-info";
+import { forgeRepoFromUrl } from "../lib/github-catalog";
+import type { ForgeCommit, ForgeRepo } from "../lib/github-catalog";
+import { forgeCommitQuery } from "../lib/queries";
+import { absoluteTime, relativeTime } from "../lib/format";
+import { Ident } from "./Ident";
+
+const buildRepo = forgeRepoFromUrl(buildInfo.repoUrl, buildInfo.forge);
+
+function repoFrom(value: string): ForgeRepo | null {
+  const url = /^https?:\/\//.test(value) ? value : `https://${value}`;
+  return forgeRepoFromUrl(url);
+}
+
+function commitHref(repo: ForgeRepo, commit: string): string {
+  const route = repo.provider === "gitlab" ? "/-/commit/" : "/commit/";
+  return `${repo.webUrl.replace(/\/$/, "")}${route}${encodeURIComponent(commit)}`;
+}
+
+export function CommitLink({
+  commit,
+  repo,
+  repository,
+  href,
+  length = 7,
+  className = "",
+}: {
+  commit: string;
+  /** Pass null when the repository is known to be unavailable. */
+  repo?: ForgeRepo | null;
+  /** A repository URL or host/owner/name, used when a ForgeRepo is not already available. */
+  repository?: string;
+  href?: string | null;
+  length?: number;
+  className?: string;
+}) {
+  const parsed = repository === undefined ? undefined : repoFrom(repository);
+  const resolvedRepo = repo !== undefined ? repo : parsed !== undefined ? parsed : buildRepo;
+  const hasExplicitRepo = repo !== undefined || repository !== undefined;
+  const resolvedHref = href !== undefined
+    ? href
+    : resolvedRepo
+      ? commitHref(resolvedRepo, commit)
+      : hasExplicitRepo
+        ? null
+        : repositoryCommitHref(commit);
+  const label = commit.slice(0, length);
+
+  if (!resolvedHref) return <Ident value={commit} className={className}>{label}</Ident>;
+  if (!resolvedRepo) {
+    return <a href={resolvedHref} target="_blank" rel="noreferrer" className={`rounded-[4px] text-accent underline-offset-4 hover:underline ${className}`}>{label}</a>;
+  }
+
+  return <CommitPopover commit={commit} repo={resolvedRepo} href={resolvedHref} label={label} className={className} />;
+}
+
+function CommitPopover({ commit, repo, href, label, className }: { commit: string; repo: ForgeRepo; href: string; label: string; className: string }) {
+  const [open, setOpen] = useState(false);
+  const { refs, floatingStyles, context } = useFloating({
+    open,
+    onOpenChange: setOpen,
+    placement: "bottom-start",
+    strategy: "fixed",
+    middleware: [offset(6), flip({ padding: 8 }), shift({ padding: 8 })],
+    whileElementsMounted: autoUpdate,
+  });
+  const hover = useHover(context, { move: false, delay: { open: 100, close: 80 } });
+  const focus = useFocus(context);
+  const dismiss = useDismiss(context);
+  const role = useRole(context, { role: "tooltip" });
+  const { getReferenceProps, getFloatingProps } = useInteractions([hover, focus, dismiss, role]);
+  const access = useForgeAccess();
+  const token = access.tokenFor(repo);
+  const details = useQuery({
+    ...forgeCommitQuery(repo, token, commit),
+    enabled: open,
+  });
+
+  return (
+    <>
+      <a
+        ref={refs.setReference}
+        href={href}
+        target="_blank"
+        rel="noreferrer"
+        aria-label={`Open commit ${commit} on the forge`}
+        className={`rounded-[4px] text-accent underline-offset-4 hover:underline focus-visible:outline focus-visible:outline-1 focus-visible:outline-accent ${className}`}
+        {...getReferenceProps()}
+      >
+        {label}
+      </a>
+      {open ? (
+        <FloatingPortal>
+          <div
+            ref={refs.setFloating}
+            style={floatingStyles}
+            className="z-50"
+            {...getFloatingProps()}
+          >
+            <div className="palette-in pointer-events-none w-80 max-w-[calc(100vw-1rem)] rounded-control border bg-canvas p-3 mono text-xs normal-case border-line-strong text-muted shadow-md">
+              <div className="label">commit</div>
+              {details.isPending ? (
+                <div className="mt-2">loading commit…</div>
+              ) : details.isError ? (
+                <div className="mt-2">commit details unavailable</div>
+              ) : (
+                <CommitHoverContent commit={details.data} />
+              )}
+            </div>
+          </div>
+        </FloatingPortal>
+      ) : null}
+    </>
+  );
+}
+
+function CommitHoverContent({ commit }: { commit: ForgeCommit }) {
+  const hasStats = commit.additions !== null || commit.deletions !== null;
+  const body = commit.body.replace(/\s+/g, " ").trim();
+  const summary = body.length > 180 ? `${body.slice(0, 177).trimEnd()}…` : body;
+  return (
+    <div className="mt-2">
+      <div className="flex items-center gap-2">
+        {commit.avatarUrl ? <img src={commit.avatarUrl} alt="" className="size-7 rounded-full" /> : null}
+        <div className="min-w-0">
+          <div className="truncate text-ink">{commit.author}</div>
+          {commit.authoredAt ? <div className="text-faint" title={absoluteTime(commit.authoredAt)}>{relativeTime(commit.authoredAt)}</div> : null}
+        </div>
+      </div>
+      <div className="mt-2 font-sans font-medium text-ink">{commit.title}</div>
+      {summary ? <div className="mt-1 font-sans text-muted">{summary}</div> : null}
+      <div className="mt-2 flex items-center gap-3 border-t pt-2 border-line text-faint">
+        <span className="truncate" title={commit.sha}>{commit.sha}</span>
+        {hasStats ? <span className="ml-auto shrink-0"><span className="text-verified">+{commit.additions ?? 0}</span>{" "}<span className="text-unresolved">−{commit.deletions ?? 0}</span></span> : null}
+      </div>
+    </div>
+  );
+}

package/src/components/EditorLink.tsx

@@ -44,6 +44,18 @@ export function useWorkspace(): string | null {
     : null;
 }
 
+export function useEditorTarget(location: SourceLocation | null): {
+  href: string;
+  name: string;
+} | null {
+  const workspace = useWorkspace();
+  const editor = useEditorStore((s) => s.editor);
+  if (!workspace || !location) return null;
+  const where = editorWhere(location);
+  const href = where ? editorHref(editor, workspace, where) : null;
+  return href ? { href, name: editorName(editor) } : null;
+}
+
 export function EditorLink({
   location,
   variant = "icon",
@@ -54,14 +66,9 @@ export function EditorLink({
   variant?: "icon" | "text";
   className?: string;
 }) {
-  const workspace = useWorkspace();
-  const editor = useEditorStore((s) => s.editor);
-  if (!workspace || !location) return null;
-  const where = editorWhere(location);
-  const href = where ? editorHref(editor, workspace, where) : null;
-  if (!href) return null;
-
-  const name = editorName(editor);
+  const target = useEditorTarget(location);
+  if (!target) return null;
+  const { href, name } = target;
   // No target: a scheme URL hands off to the editor and leaves the page
   // where it is. A new tab would be a blank tab.
   return variant === "icon" ? (

package/src/components/GrpcMethodReference.tsx

@@ -0,0 +1,93 @@
+import { Check, Copy, Terminal } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import type { RpcMethod, RpcService } from "../catalog";
+import { catalog } from "../data";
+import { toClipboard } from "../lib/clipboard";
+import {
+  grpcRequestJson,
+  grpcurlCommand,
+} from "../lib/grpc-reference";
+
+const SHOWN_MS = 1000;
+
+function CopyButton({ value, label }: { value: string; label: string }) {
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  const copy = () => {
+    void toClipboard(value).then((ok) => {
+      setCopied(ok);
+      if (timer.current) clearTimeout(timer.current);
+      timer.current = setTimeout(() => setCopied(false), SHOWN_MS);
+    });
+  };
+
+  return (
+    <button
+      type="button"
+      onClick={copy}
+      className="row-action opacity-100"
+      aria-label={`Copy ${label}`}
+      title={`Copy ${label}`}
+    >
+      {copied ? <Check size={12} aria-hidden /> : <Copy size={12} aria-hidden />}
+      {copied ? "copied" : "copy"}
+    </button>
+  );
+}
+
+/** The executable-looking part of a protobuf reference, collapsed per method. */
+export function GrpcMethodReference({
+  provided,
+  method,
+}: {
+  provided: RpcService;
+  method: RpcMethod;
+}) {
+  const json = grpcRequestJson(provided, method, catalog.defs);
+  const command = grpcurlCommand(provided, method, catalog.defs);
+
+  return (
+    <details className="group mt-2 overflow-hidden rounded-control border border-line bg-surface">
+      <summary className="flex cursor-pointer list-none items-center gap-2 px-2.5 py-1.5 text-muted hover:text-ink">
+        <Terminal size={13} aria-hidden />
+        <span>Call locally</span>
+        <span className="chip mono">grpcurl</span>
+        <span className="ml-auto text-faint group-open:hidden">show</span>
+        <span className="ml-auto hidden text-faint group-open:inline">hide</span>
+      </summary>
+      <div className="grid gap-3 border-t border-line p-3 lg:grid-cols-2">
+        <div className="min-w-0">
+          <div className="mb-1.5 flex items-center justify-between gap-2">
+            <span className="label">ProtoJSON request</span>
+            <CopyButton value={json} label="request JSON" />
+          </div>
+          <pre className="mono max-h-64 overflow-auto whitespace-pre rounded-control border border-line bg-canvas p-3 text-muted">
+            {json}
+          </pre>
+        </div>
+        <div className="min-w-0">
+          <div className="mb-1.5 flex items-center justify-between gap-2">
+            <span className="label">Command</span>
+            <CopyButton value={command} label="grpcurl command" />
+          </div>
+          <pre className="mono max-h-64 overflow-auto whitespace-pre rounded-control border border-line bg-canvas p-3 text-muted">
+            {command}
+          </pre>
+          <p className="mt-2 text-muted">
+            Replace <span className="mono text-ink">localhost:50051</span> and
+            remove <span className="mono text-ink">-plaintext</span> when the
+            endpoint uses TLS.
+          </p>
+        </div>
+      </div>
+    </details>
+  );
+}

package/src/components/Markdown.tsx

@@ -17,6 +17,7 @@ import { headingSlug } from "../lib/derive";
 import { Mermaid } from "./Mermaid";
 import { MarkdownTable } from "./MarkdownTable";
 import { remarkTableDirective } from "../lib/table-directive";
+import { readmeAssetHref } from "../lib/readme-assets";
 
 function textOf(node: React.ReactNode): string {
   if (typeof node === "string" || typeof node === "number") return String(node);
@@ -146,9 +147,11 @@ function Pre(props: ComponentPropsWithoutRef<"pre">) {
 export function Markdown({
   children,
   mermaid = false,
+  sourceRoot,
 }: {
   children: string;
   mermaid?: boolean;
+  sourceRoot?: string;
 }) {
   return (
     <div className="prose">
@@ -164,6 +167,20 @@ export function Markdown({
           // said not to.
           table: MarkdownTable,
           ...(mermaid ? { pre: Pre } : {}),
+          ...(sourceRoot ? {
+            a: (props: ComponentPropsWithoutRef<"a">) => {
+              const href = typeof props.href === "string"
+                ? readmeAssetHref(sourceRoot, props.href, import.meta.env.BASE_URL)
+                : null;
+              return <a {...props} href={href ?? props.href} {...(href ? { target: "_blank", rel: "noreferrer" } : {})} />;
+            },
+            img: (props: ComponentPropsWithoutRef<"img">) => {
+              const src = typeof props.src === "string"
+                ? readmeAssetHref(sourceRoot, props.src, import.meta.env.BASE_URL)
+                : null;
+              return <img {...props} src={src ?? props.src} />;
+            },
+          } : {}),
         }}
       >
         {children}

package/src/components/MethodRows.tsx

@@ -128,6 +128,7 @@ export function MethodRows({
   open,
   onToggle,
   runs,
+  reference,
 }: {
   provided: RpcService;
   /** Which shapes are expanded, keyed `<interface>/<method>/req|res`. */
@@ -135,6 +136,8 @@ export function MethodRows({
   onToggle: (key: string) => void;
   /** What the method runs, when the page knows — the service page does. */
   runs?: (method: RpcMethod) => ReactNode;
+  /** Protocol-specific tools shown below the method, when its reference has one. */
+  reference?: (method: RpcMethod) => ReactNode;
 }) {
   return (
     <ul data-nav-list>
@@ -227,6 +230,8 @@ export function MethodRows({
 
               {runs?.(method)}
 
+              {reference?.(method)}
+
               {open.has(reqKey) && reqFields ? (
                 <div className="mt-2">
                   <DiscriminatorRows discriminator={reqDiscriminator} />
@@ -240,7 +245,9 @@ export function MethodRows({
                 </div>
               ) : null}
             </div>
-            <RowActions copy={id} />
+            <span className="self-start pt-0.5">
+              <RowActions copy={id} />
+            </span>
           </li>
         );
       })}

package/src/components/PageHeader.test.tsx

@@ -0,0 +1,23 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+
+import { CapabilityEmpty } from "./PageHeader";
+
+describe("CapabilityEmpty", () => {
+  it("keeps the explanation, action and evidence signal together", () => {
+    const markup = renderToStaticMarkup(
+      <CapabilityEmpty
+        title="No dependency graph yet"
+        actions={<button type="button">Review extraction</button>}
+        signal="Signals: domain events and consumers."
+      >
+        The catalog has components, but no events to connect.
+      </CapabilityEmpty>,
+    );
+
+    expect(markup).toContain("next useful step");
+    expect(markup).toContain("No dependency graph yet");
+    expect(markup).toContain("Review extraction");
+    expect(markup).toContain("Signals: domain events and consumers.");
+  });
+});

package/src/components/PageHeader.tsx

@@ -155,6 +155,40 @@ export function Empty({ children }: { children: ReactNode }) {
   return <div className="empty">{children}</div>;
 }
 
+/**
+ * A page-level absence with a useful next move.
+ *
+ * Unlike `Empty`, this is not the result of a filter, and unlike `Blank` it
+ * does more than document the catalog field that is missing. It is used when
+ * the reader can take a concrete setup action to make the page useful.
+ */
+export function CapabilityEmpty({
+  title,
+  children,
+  actions,
+  signal,
+}: {
+  title: string;
+  children: ReactNode;
+  actions?: ReactNode;
+  /** The source evidence or catalog fact that will fill this page. */
+  signal?: ReactNode;
+}) {
+  return (
+    <div className="rounded-card border border-accent/60 bg-surface p-5 shadow-xs">
+      <div className="label text-accent">next useful step</div>
+      <h2 className="mt-1 text-md font-semibold text-ink">{title}</h2>
+      <div className="mt-2 max-w-prose text-muted">{children}</div>
+      {actions ? <div className="mt-4 flex flex-wrap gap-2">{actions}</div> : null}
+      {signal ? (
+        <div className="mono mt-4 border-t border-line pt-3 text-faint">
+          {signal}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
 /**
  * What a page says before the catalog has anything to put on it.
  *

package/src/components/ProblemRow.tsx

@@ -27,6 +27,7 @@ const KIND_OF: Record<Problem["kind"], "service" | "event" | "table"> = {
   "column-type": "table",
   "outbox-payload": "table",
   "proto-missing": "service",
+  "proto-drift": "service",
   "shared-channel": "event",
   "channel-undeclared": "event",
   "channel-unpublished": "service",
@@ -44,6 +45,7 @@ const KIND_NOTE: Record<Problem["kind"], string> = {
   "outbox-payload": "an outbox with no payload column",
   "proto-missing":
     "the provider is in the catalog but answers on no such method",
+  "proto-drift": "the vendored proto and provider schema disagree",
   "shared-channel": "a second service publishes on this channel",
   "channel-undeclared":
     "this event goes out on a channel the service does not declare",
@@ -60,6 +62,7 @@ function nearPath(problem: Problem): string | null {
     // peer is nobody; this is a call whose peer is known and whose method is
     // not - and in both the thing to go and look at is the caller.
     case "proto-missing":
+    case "proto-drift":
       return servicePath(problem.service);
     case "consumer":
     case "channel-undeclared":

package/src/components/ShapeRows.tsx

@@ -44,10 +44,13 @@ function EnumRows({ set }: { set: RpcEnum }) {
 export function ShapeRows({
   fields,
   enums,
+  showHeader = false,
 }: {
   fields: Field[];
   /** The interface's enums, so a field typed by one can open its values. */
   enums?: RpcEnum[];
+  /** A contract panel needs named columns; compact inline shapes do not. */
+  showHeader?: boolean;
 }) {
   const [open, setOpen] = useState<Set<string>>(new Set());
   const toggle = (name: string) =>
@@ -60,6 +63,15 @@ export function ShapeRows({
 
   return (
     <table className="w-full">
+      {showHeader ? (
+        <thead>
+          <tr className="label border-b border-line text-left">
+            <th className="pb-1 pr-3 font-normal">Field</th>
+            <th className="pb-1 pr-3 font-normal">Type</th>
+            <th className="pb-1 font-normal">Description</th>
+          </tr>
+        </thead>
+      ) : null}
       <tbody>
         {fields.map((field) => {
           const set = enumFor(enums, field);

package/src/components/SourceDoc.tsx

@@ -20,6 +20,7 @@ import { KindIcon } from "./kind";
 import { MessageList, MethodRows } from "./MethodRows";
 import { paths } from "../routes";
 import { packageOf } from "../lib/registry";
+import { GrpcMethodReference } from "./GrpcMethodReference";
 
 /** The interfaces of one module, as the service page's spec tab shows them. */
 export function ModuleSpec({ moduleId }: { moduleId: string }) {
@@ -46,17 +47,24 @@ export function ModuleSpec({ moduleId }: { moduleId: string }) {
 
   return (
     <div className="max-w-table">
-      <div className="mono flex flex-wrap items-center gap-x-3">
-        <KindIcon kind="module" />
-        <Link
-          to={paths.module(module.slug)}
-          className="text-ink hover:underline"
-        >
-          {module.name}
-        </Link>
-        {module.commit ? (
-          <Ident value={module.commit.slice(0, 12)} className="text-muted" />
-        ) : null}
+      <div className="rounded-card border border-line bg-surface px-4 py-3">
+        <div className="mono flex flex-wrap items-center gap-x-3">
+          <KindIcon kind="module" />
+          <span className="chip">gRPC</span>
+          <Link
+            to={paths.module(module.slug)}
+            className="text-ink hover:underline"
+          >
+            {module.name}
+          </Link>
+          {module.commit ? (
+            <Ident value={module.commit.slice(0, 12)} className="text-muted" />
+          ) : null}
+        </div>
+        <p className="mt-1.5 text-muted">
+          Methods and message shapes extracted from Protocol Buffers. Open a
+          method&apos;s local call to copy a ProtoJSON body or a grpcurl command.
+        </p>
       </div>
 
       {declared.length === 0 ? (
@@ -72,7 +80,14 @@ export function ModuleSpec({ moduleId }: { moduleId: string }) {
             <div className="mono border-b px-3 py-1.5 border-line bg-surface">
               <Ident value={provided.id} className="text-ink" />
             </div>
-            <MethodRows provided={provided} open={open} onToggle={toggle} />
+            <MethodRows
+              provided={provided}
+              open={open}
+              onToggle={toggle}
+              reference={(method) => (
+                <GrpcMethodReference provided={provided} method={method} />
+              )}
+            />
             <MessageList provided={provided} open={open} onToggle={toggle} />
           </div>
         </section>