@shortlink-org/portolan 0.1.0

package/src/components/Mermaid.tsx

@@ -0,0 +1,211 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Check, Copy } from "lucide-react";
+import { useTheme } from "../app/theme";
+import { toClipboard } from "../lib/clipboard";
+
+/**
+ * Renders one mermaid fence. The library is ~500kB and is wanted on the pages
+ * that carry somebody's writing - a decision record, a service or aggregate
+ * readme - so it is imported on first render and never from the app entry.
+ *
+ * A diagram in a readme is a quotation, not a measurement. It is drawn exactly
+ * as written, even when the current catalog disagrees with it - but it is
+ * drawn in this app's colours, because a picture in the estate's own palette
+ * reads as part of the page and a picture in mermaid's reads as a screenshot
+ * somebody pasted.
+ */
+
+let seq = 0;
+
+type Phase = "loading" | "drawn" | { error: string };
+
+const SHOWN_MS = 1000;
+
+/** One custom property's value, resolved. Mermaid wants colours, not `var()`. */
+function token(name: string): string {
+  return getComputedStyle(document.documentElement)
+    .getPropertyValue(name)
+    .trim();
+}
+
+/**
+ * The theme mermaid is given, in this app's tokens.
+ *
+ * `base` is the only theme whose variables are honoured in full; every other
+ * one computes its own and ignores most of what is passed. The mapping follows
+ * LifecycleDiagram, which draws the catalog's own state machines: a node is
+ * the page's background inside a `--border-strong` box, and an edge is
+ * `--fg-muted` - so a quoted diagram and a measured one sit in the same family.
+ *
+ * Read after the palette is on the document, never before: the theme class is
+ * set by ThemeProvider's effect, and a child's effect runs first.
+ */
+function themeVariables(dark: boolean) {
+  const bg = token("--bg");
+  const surface = token("--surface");
+  const surface2 = token("--surface-2");
+  const border = token("--border");
+  const borderStrong = token("--border-strong");
+  const fg = token("--fg");
+  const muted = token("--fg-muted");
+
+  return {
+    darkMode: dark,
+    background: surface,
+    fontFamily: token("--font-mono"),
+    fontSize: token("--text-sm"),
+
+    primaryColor: bg,
+    primaryBorderColor: borderStrong,
+    primaryTextColor: fg,
+    secondaryColor: surface2,
+    tertiaryColor: surface,
+    lineColor: muted,
+    textColor: fg,
+    mainBkg: bg,
+    nodeBorder: borderStrong,
+    nodeTextColor: fg,
+    titleColor: fg,
+
+    // The chip a label sits on. Painted as the sheet it lies on, so what the
+    // reader sees is the word and not the box around it.
+    edgeLabelBackground: surface,
+    labelBackground: surface,
+    labelBackgroundColor: surface,
+    labelColor: fg,
+
+    // State diagrams.
+    stateBkg: bg,
+    stateBorder: borderStrong,
+    transitionColor: muted,
+    transitionLabelColor: fg,
+    specialStateColor: fg,
+    innerEndBackground: bg,
+    compositeBackground: surface,
+    compositeTitleBackground: surface2,
+    compositeBorder: border,
+    altBackground: surface2,
+
+    // Sequence diagrams.
+    actorBkg: bg,
+    actorBorder: borderStrong,
+    actorTextColor: fg,
+    actorLineColor: border,
+    signalColor: muted,
+    signalTextColor: fg,
+    noteBkgColor: surface2,
+    noteBorderColor: border,
+    noteTextColor: fg,
+    activationBkgColor: surface2,
+    activationBorderColor: border,
+    sequenceNumberColor: bg,
+    loopTextColor: fg,
+    labelBoxBkgColor: surface,
+    labelBoxBorderColor: border,
+    labelTextColor: fg,
+
+    // Flowcharts.
+    clusterBkg: surface,
+    clusterBorder: border,
+    defaultLinkColor: muted,
+  };
+}
+
+export function Mermaid({ code }: { code: string }) {
+  const { theme } = useTheme();
+  const host = useRef<HTMLDivElement>(null);
+  const [phase, setPhase] = useState<Phase>("loading");
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+    setPhase("loading");
+
+    void (async () => {
+      try {
+        const mermaid = (await import("mermaid")).default;
+        mermaid.initialize({
+          startOnLoad: false,
+          securityLevel: "strict",
+          theme: "base",
+          themeVariables: themeVariables(theme === "dark"),
+          fontFamily: "var(--font-mono)",
+          // A diagram wider than the prose column belongs scaled down, not
+          // behind a scrollbar. Every kind that can outgrow the column says so
+          // for itself; the ones that cannot have nothing to say.
+          sequence: { useMaxWidth: true },
+          flowchart: { useMaxWidth: true },
+          state: { useMaxWidth: true },
+          class: { useMaxWidth: true },
+          er: { useMaxWidth: true },
+        });
+        seq += 1;
+        const { svg } = await mermaid.render(`mermaid-${seq}`, code);
+        if (cancelled) return;
+        if (host.current) host.current.innerHTML = svg;
+        setPhase("drawn");
+      } catch (err) {
+        if (cancelled) return;
+        setPhase({ error: err instanceof Error ? err.message : String(err) });
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [code, theme]);
+
+  // The way out of the page with the diagram in hand, on the same terms as a
+  // flow's toolbar: the source, for a wiki or a pull request. Selecting text
+  // inside an SVG gets you nothing.
+  const copy = useCallback(() => {
+    void toClipboard(code).then((ok) => {
+      setCopied(ok);
+      if (timer.current) clearTimeout(timer.current);
+      timer.current = setTimeout(() => setCopied(false), SHOWN_MS);
+    });
+  }, [code]);
+
+  // A diagram that will not parse is still evidence: show the source it was
+  // written as, rather than an empty box.
+  if (typeof phase === "object") {
+    return (
+      <figure className="my-3">
+        <div className="mono border border-dashed px-2 py-1 status-unresolved">
+          this diagram does not parse — {phase.error}
+        </div>
+        <pre className="mt-1">{code}</pre>
+      </figure>
+    );
+  }
+
+  return (
+    <figure className="group relative my-3 border border-line bg-surface p-3">
+      <button
+        type="button"
+        onClick={copy}
+        title={copied ? "copied" : "Copy the diagram as Mermaid"}
+        aria-label="Copy the diagram as Mermaid"
+        className="absolute right-1.5 top-1.5 inline-flex items-center rounded-[4px] p-1 text-muted opacity-0 t-micro transition-opacity hover:text-ink focus-visible:opacity-100 group-hover:opacity-100"
+      >
+        {copied ? (
+          <Check size={12} aria-hidden />
+        ) : (
+          <Copy size={12} aria-hidden />
+        )}
+      </button>
+      <div ref={host} className="mermaid-figure overflow-x-auto" />
+      {phase === "loading" ? (
+        <div className="mono text-muted">drawing…</div>
+      ) : null}
+    </figure>
+  );
+}

package/src/components/MethodRows.tsx

@@ -0,0 +1,309 @@
+// One method of one interface, drawn the same way wherever it appears.
+//
+// The service page's `provides` tab and the module page both list methods, and
+// a method that reads differently in the two places is a method a reader has to
+// re-learn. So the row lives here, and both pages hand it the same thing.
+//
+// What a method carries beyond its name — the shapes on either side and how it
+// streams — is the whole reason `RpcService.methods` stopped being a list of
+// strings. Unary draws nothing at all: it is the common case, and a marker on
+// every row would say only that most methods are ordinary.
+
+import { ChevronDown, ChevronRight } from "lucide-react";
+import type { ReactNode } from "react";
+import type {
+  Field,
+  RpcDiscriminator,
+  RpcMethod,
+  RpcService,
+} from "../catalog";
+import { catalog } from "../data";
+import { streamingKind } from "../lib/api";
+import { Ident } from "./Ident";
+import { RowActions } from "./RowActions";
+import { ShapeRows } from "./ShapeRows";
+
+const STREAM_LABEL: Record<"client" | "server" | "bidi", string> = {
+  client: "client stream",
+  server: "server stream",
+  bidi: "bidi stream",
+};
+
+/**
+ * The fields of a message a method names.
+ *
+ * Resolution order matters and is one rule: a `ref` into `catalog.defs` wins,
+ * because a shared type is the same type wherever it turns up; otherwise the
+ * name is looked up among the messages the interface itself lists. A name that
+ * resolves to neither is still shown — the catalog knows what the method sends
+ * even when it could not read the shape.
+ */
+export function shapeFor(
+  provided: RpcService,
+  name: string | undefined,
+  ref: string | undefined,
+): Field[] | null {
+  if (ref) {
+    const def = catalog.defs[ref];
+    if (def) return def.fields;
+  }
+  if (!name) return null;
+
+  return provided.messages?.find((m) => m.name === name)?.fields ?? null;
+}
+
+function discriminatorFor(
+  provided: RpcService,
+  name: string | undefined,
+): RpcDiscriminator | undefined {
+  if (!name) return undefined;
+  return provided.messages?.find((message) => message.name === name)
+    ?.discriminator;
+}
+
+function DiscriminatorRows({
+  discriminator,
+}: {
+  discriminator: RpcDiscriminator | undefined;
+}) {
+  if (!discriminator) return null;
+  return (
+    <div className="mono mb-2 border-l-2 border-line pl-2 text-muted">
+      <div>
+        discriminator <span className="text-ink">{discriminator.property}</span>
+      </div>
+      {discriminator.variants.map((variant) => (
+        <div key={`${variant.value}:${variant.message}`}>
+          {variant.value} → <span className="text-ink">{variant.message}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function Shape({
+  provided,
+  label,
+  name,
+  refKey,
+  open,
+  onToggle,
+}: {
+  provided: RpcService;
+  label: string;
+  name: string | undefined;
+  refKey: string | undefined;
+  open: boolean;
+  onToggle: () => void;
+}) {
+  if (!name) return null;
+
+  const fields = shapeFor(provided, name, refKey);
+
+  // Nothing to expand into: the shape is named but was never read, which is
+  // ordinary for an interface described by an OpenAPI document.
+  if (!fields) {
+    return (
+      <span className="mono text-muted" title={`${label} ${name}`}>
+        {name}
+      </span>
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={onToggle}
+      aria-expanded={open}
+      className="mono rounded-control text-left text-muted hover:text-ink"
+      title={`${label} ${name}`}
+    >
+      {name}
+    </button>
+  );
+}
+
+export function MethodRows({
+  provided,
+  open,
+  onToggle,
+  runs,
+}: {
+  provided: RpcService;
+  /** Which shapes are expanded, keyed `<interface>/<method>/req|res`. */
+  open: ReadonlySet<string>;
+  onToggle: (key: string) => void;
+  /** What the method runs, when the page knows — the service page does. */
+  runs?: (method: RpcMethod) => ReactNode;
+}) {
+  return (
+    <ul data-nav-list>
+      {provided.methods.map((method) => {
+        const id = `${provided.id}/${method.name}`;
+        const reqKey = `${id}/req`;
+        const resKey = `${id}/res`;
+        const streaming = streamingKind(method);
+        const reqFields = shapeFor(provided, method.request, method.requestRef);
+        const resFields = shapeFor(
+          provided,
+          method.response,
+          method.responseRef,
+        );
+        const reqDiscriminator = discriminatorFor(provided, method.request);
+        const resDiscriminator = discriminatorFor(provided, method.response);
+
+        return (
+          <li
+            key={method.name}
+            className="row rounded-none border-x-0 border-t-0 last:border-b-0"
+          >
+            <div className="min-w-0 flex-1">
+              <div className="flex flex-wrap items-center gap-x-2">
+                <Ident
+                  value={id}
+                  className={method.deprecated ? "line-through" : undefined}
+                />
+                {method.http ? (
+                  <span className="chip mono" title="the route this operation answers on">
+                    {method.http.method} {method.http.path}
+                  </span>
+                ) : null}
+                {method.soap ? (
+                  <span
+                    className="chip mono"
+                    title={method.soap.endpoint || "SOAP operation"}
+                  >
+                    SOAP{method.soap.version ? ` ${method.soap.version}` : ""}
+                    {method.soap.action ? ` · ${method.soap.action}` : ""}
+                  </span>
+                ) : null}
+                {method.deprecated ? (
+                  <span className="chip">deprecated</span>
+                ) : null}
+                {streaming !== "unary" ? (
+                  <span className="chip">{STREAM_LABEL[streaming]}</span>
+                ) : null}
+              </div>
+
+              {method.request || method.response ? (
+                <p className="mono mt-0.5 flex flex-wrap items-center gap-x-1.5 text-muted">
+                  <Shape
+                    provided={provided}
+                    label="sends"
+                    name={method.request}
+                    refKey={method.requestRef}
+                    open={open.has(reqKey)}
+                    onToggle={() => onToggle(reqKey)}
+                  />
+                  <span aria-hidden>→</span>
+                  <Shape
+                    provided={provided}
+                    label="returns"
+                    name={method.response}
+                    refKey={method.responseRef}
+                    open={open.has(resKey)}
+                    onToggle={() => onToggle(resKey)}
+                  />
+                </p>
+              ) : null}
+
+              {method.doc ? (
+                <p className="mt-0.5 text-muted">{method.doc}</p>
+              ) : null}
+
+              {method.soap?.faults?.length || method.soap?.headers?.length ? (
+                <p className="mono mt-0.5 text-muted">
+                  {method.soap.headers?.length
+                    ? `headers ${method.soap.headers.join(", ")}`
+                    : null}
+                  {method.soap.headers?.length && method.soap.faults?.length
+                    ? " · "
+                    : null}
+                  {method.soap.faults?.length
+                    ? `faults ${method.soap.faults.join(", ")}`
+                    : null}
+                </p>
+              ) : null}
+
+              {runs?.(method)}
+
+              {open.has(reqKey) && reqFields ? (
+                <div className="mt-2">
+                  <DiscriminatorRows discriminator={reqDiscriminator} />
+                  <ShapeRows fields={reqFields} enums={provided.enums} />
+                </div>
+              ) : null}
+              {open.has(resKey) && resFields ? (
+                <div className="mt-2">
+                  <DiscriminatorRows discriminator={resDiscriminator} />
+                  <ShapeRows fields={resFields} enums={provided.enums} />
+                </div>
+              ) : null}
+            </div>
+            <RowActions copy={id} />
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+
+/**
+ * The messages an interface moves, collapsed.
+ *
+ * Extracted from the service page so the module page lists them identically.
+ * Collapsed by default for the reason the service page always had: the question
+ * a reader opens with is "what can I call", and a page that opens with six
+ * schemas answers a question nobody asked yet.
+ */
+export function MessageList({
+  provided,
+  open,
+  onToggle,
+}: {
+  provided: RpcService;
+  open: ReadonlySet<string>;
+  onToggle: (key: string) => void;
+}) {
+  if (!provided.messages?.length) return null;
+
+  return (
+    <div className="border-t border-line">
+      <div className="mono px-3 py-1 text-muted">
+        <span className="tnum">{provided.messages.length}</span> message
+        {provided.messages.length === 1 ? "" : "s"}
+      </div>
+      {provided.messages.map((message) => {
+        const id = `${provided.id}/${message.name}`;
+        const shown = open.has(id);
+
+        return (
+          <div key={id} className="border-t border-line last:border-b-0">
+            <button
+              type="button"
+              onClick={() => onToggle(id)}
+              aria-expanded={shown}
+              className="mono flex w-full items-center gap-1.5 px-3 py-1.5 text-left"
+            >
+              {shown ? (
+                <ChevronDown size={11} aria-hidden className="text-muted" />
+              ) : (
+                <ChevronRight size={11} aria-hidden className="text-muted" />
+              )}
+              <span className="truncate">{message.name}</span>
+              <span className="tnum ml-auto text-muted">
+                {message.fields.length}
+              </span>
+            </button>
+            {shown ? (
+              <div className="px-3 pb-3">
+                <DiscriminatorRows discriminator={message.discriminator} />
+                <ShapeRows fields={message.fields} enums={provided.enums} />
+              </div>
+            ) : null}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/components/Overlay.tsx

@@ -0,0 +1,125 @@
+// The two shapes anything in this app can take when it covers the page.
+//
+// There were four hand-rolled overlays before this file: the palette, the
+// shortcuts sheet, the catalog drawer and the detail sheet. All four wrote the
+// same fixed box, the same 45% scrim, the same "mousedown on the scrim closes
+// me", and each one had a different half of a modal's real job. None trapped
+// focus, so Tab walked out of the palette into the page behind it; none gave
+// focus back to whatever opened them; two listened for Escape on `window` with
+// capture and two did not.
+//
+// So the behaviour is Headless UI's Dialog - focus trap, focus restore, scroll
+// lock, `aria-modal`, outside click, Escape - and what is left here is the two
+// paints this app actually has: a MODAL, which arrives in the middle and is
+// about a task, and a SIDE PANEL, which arrives from an edge and is a pane that
+// ran out of room to be one.
+//
+// Both leave the way they came. Headless UI unmounts a closed Dialog on the
+// spot, so the exit is Motion's: `static` hands the mounting to us, an
+// <AnimatePresence> keeps the node alive for the exit, and the backdrop and
+// panel are `m.div`s wearing the presets from lib/motion - the scrim fades,
+// the modal shrinks its two percent, the side panel slides back off its edge.
+//
+// Escape closes, and Headless UI marks the event handled. That matters: the
+// shell clears the catalog selection on an unhandled Escape, and a reader
+// dismissing a sheet was closing a sheet, not deselecting anything.
+
+import { Dialog, DialogBackdrop, DialogPanel } from "@headlessui/react";
+import type { ReactNode } from "react";
+import { AnimatePresence, fade, m, scaleIn, slideFrom } from "../lib/motion";
+
+const SCRIM = "color-mix(in srgb, #000 45%, transparent)";
+
+export function Modal({
+  open,
+  onClose,
+  label,
+  children,
+  width = "min(680px,92vw)",
+}: {
+  open: boolean;
+  onClose: () => void;
+  /** Accessible name for the dialog. */
+  label: string;
+  children: ReactNode;
+  /** Any CSS width; the default is the palette's. */
+  width?: string;
+}) {
+  return (
+    <AnimatePresence>
+      {open && (
+        <Dialog static open={open} onClose={onClose} className="relative z-50">
+          <DialogBackdrop
+            as={m.div}
+            {...fade}
+            className="fixed inset-0"
+            style={{ background: SCRIM }}
+          />
+          {/* The scrim is a sibling of the panel and both are fixed, so the
+              click that lands outside the panel lands on this box - which is
+              what Headless UI watches to close. */}
+          <div className="fixed inset-0 flex items-start justify-center pt-[12vh]">
+            <DialogPanel
+              as={m.div}
+              {...scaleIn}
+              aria-label={label}
+              className="flex max-h-[70vh] flex-col overflow-hidden rounded-modal border bg-canvas border-line-strong shadow-md"
+              style={{ width }}
+            >
+              {children}
+            </DialogPanel>
+          </div>
+        </Dialog>
+      )}
+    </AnimatePresence>
+  );
+}
+
+export function SidePanel({
+  open,
+  onClose,
+  side,
+  label,
+  children,
+  width,
+}: {
+  open: boolean;
+  onClose: () => void;
+  side: "left" | "right";
+  label: string;
+  children: ReactNode;
+  /** Any CSS width. */
+  width: string;
+}) {
+  const left = side === "left";
+  return (
+    <AnimatePresence>
+      {open && (
+        <Dialog static open={open} onClose={onClose} className="relative z-40">
+          <DialogBackdrop
+            as={m.div}
+            {...fade}
+            className="fixed inset-0"
+            style={{ background: SCRIM }}
+          />
+          <div
+            className={`fixed inset-0 flex ${left ? "justify-start" : "justify-end"}`}
+          >
+            {/* Arrives from the edge it belongs to, at the panel duration, and
+                leaves by the same edge: it is a panel, it has just run out of
+                room to be one. */}
+            <DialogPanel
+              as={m.div}
+              {...slideFrom(left ? "-100%" : "100%")}
+              aria-label={label}
+              className={`${left ? "bg-canvas " : ""}h-full shadow-md`}
+              style={{ width }}
+            >
+              {children}
+            </DialogPanel>
+          </div>
+        </Dialog>
+      )}
+    </AnimatePresence>
+  );
+}