@shortlink-org/portolan 0.1.0

package/src/components/SourceDoc.tsx

@@ -0,0 +1,82 @@
+// A service's schema, drawn from the catalog rather than from the file.
+//
+// `ApiReference` draws the OpenAPI document itself, and its header explains
+// why: the catalog cannot carry the document's own shape, and re-deriving that
+// into the schema would be rebuilding OpenAPI inside it.
+//
+// For a proto that premise does not hold. The extractor reads exactly that
+// shape — the interfaces, their methods, the two messages each one moves — so
+// the catalog already has it. Drawing the raw text would be a worse copy of
+// data we hold structured, and an unlinkable one: a `<pre>` cannot take a
+// reader from a field to the shared type it refs, or from a method to the
+// operation it exposes.
+
+import { useState } from "react";
+import { Link } from "react-router";
+import { index } from "../data";
+import { Empty, SectionTitle } from "./PageHeader";
+import { Ident } from "./Ident";
+import { KindIcon } from "./kind";
+import { MessageList, MethodRows } from "./MethodRows";
+import { paths } from "../routes";
+import { packageOf } from "../lib/registry";
+
+/** The interfaces of one module, as the service page's spec tab shows them. */
+export function ModuleSpec({ moduleId }: { moduleId: string }) {
+  const [open, setOpen] = useState<ReadonlySet<string>>(new Set());
+
+  const toggle = (id: string) =>
+    setOpen((shown) => {
+      const next = new Set(shown);
+      if (!next.delete(id)) next.add(id);
+
+      return next;
+    });
+
+  const module = index.moduleById.get(moduleId);
+  const declared = index.interfacesByModule.get(moduleId) ?? [];
+
+  if (!module) {
+    return (
+      <Empty>
+        this service&apos;s interfaces name a module the catalog does not hold
+      </Empty>
+    );
+  }
+
+  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>
+
+      {declared.length === 0 ? (
+        <div className="mt-section">
+          <Empty>nothing in this catalog was declared in this module</Empty>
+        </div>
+      ) : null}
+
+      {declared.map(({ provided }) => (
+        <section key={provided.id} className="mt-section">
+          <SectionTitle>{packageOf(provided.id) || provided.id}</SectionTitle>
+          <div className="rounded-card border border-line">
+            <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} />
+            <MessageList provided={provided} open={open} onToggle={toggle} />
+          </div>
+        </section>
+      ))}
+    </div>
+  );
+}

package/src/components/SourcePreview.tsx

@@ -0,0 +1,441 @@
+import {
+  Code2,
+  ExternalLink,
+  LoaderCircle,
+  LockKeyhole,
+  Pin,
+  X,
+} from "lucide-react";
+import { EditorLink } from "./EditorLink";
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import type {
+  CSSProperties,
+  FormEvent,
+  PointerEvent as ReactPointerEvent,
+  ReactNode,
+} from "react";
+import { createPortal } from "react-dom";
+import { useQuery } from "@tanstack/react-query";
+import { useForgeAccess } from "../app/forge-access";
+import { sourceCodeQuery } from "../lib/queries";
+import {
+  sourceLanguage,
+  sourceWindow,
+  SourceLoadError,
+} from "../lib/source-code";
+import type { SourceFile } from "../lib/source-code";
+import { highlightSource } from "../lib/source-highlight";
+import type { HighlightNode } from "../lib/source-highlight";
+import type { SourceLocation } from "../lib/source-link";
+
+const OPEN_DELAY_MS = 220;
+const CLOSE_DELAY_MS = 140;
+const PANEL_WIDTH = 720;
+const PANEL_HEIGHT = 430;
+const EDGE = 8;
+
+type Position = { left: number; top: number; width: number; maxHeight: number };
+
+function positionFor(trigger: DOMRect): Position {
+  const width = Math.min(PANEL_WIDTH, window.innerWidth - EDGE * 2);
+  const maxHeight = Math.min(PANEL_HEIGHT, window.innerHeight - EDGE * 2);
+  const left = Math.max(
+    EDGE,
+    Math.min(trigger.left, window.innerWidth - width - EDGE),
+  );
+  const below = window.innerHeight - trigger.bottom - EDGE;
+  const top =
+    below >= Math.min(maxHeight, 260)
+      ? trigger.bottom + 6
+      : Math.max(EDGE, trigger.top - maxHeight - 6);
+  return { left, top, width, maxHeight };
+}
+
+function AccessForm({
+  location,
+  message,
+}: {
+  location: Extract<SourceLocation, { kind: "remote" }>;
+  message: string;
+}) {
+  const access = useForgeAccess();
+  const [draft, setDraft] = useState("");
+  const connected = access.connectedTo(location.origin);
+  const provider = location.provider === "github" ? "GitHub" : "GitLab";
+
+  const submit = (event: FormEvent) => {
+    event.preventDefault();
+    if (!draft.trim()) return;
+    access.connect(location.origin, draft);
+    setDraft("");
+  };
+
+  return (
+    <div className="p-4">
+      <div className="flex items-start gap-2 text-ink">
+        <LockKeyhole
+          size={16}
+          className="mt-0.5 shrink-0 text-accent"
+          aria-hidden
+        />
+        <div>
+          <div className="font-medium">Repository access required</div>
+          <p className="mt-1 text-sm text-muted">{message}</p>
+        </div>
+      </div>
+      <form onSubmit={submit} className="mt-4 flex gap-2">
+        <label className="min-w-0 flex-1">
+          <span className="sr-only">{provider} read-only access token</span>
+          <input
+            type="password"
+            value={draft}
+            onChange={(event) => setDraft(event.target.value)}
+            autoComplete="off"
+            spellCheck={false}
+            placeholder={`${provider} read-only access token`}
+            className="mono w-full rounded-control border border-line bg-canvas px-3 py-2 text-sm text-ink outline-none placeholder:text-muted focus:border-accent"
+          />
+        </label>
+        <button
+          type="submit"
+          disabled={!draft.trim()}
+          className="btn-accent shrink-0 disabled:opacity-40"
+        >
+          {connected ? "Replace token" : "Connect"}
+        </button>
+      </form>
+      <p className="mt-2 text-xs text-muted">
+        Kept only in this tab&apos;s memory. Never written to URLs, Web Storage,
+        or Cache Storage.
+      </p>
+      {connected ? (
+        <button
+          type="button"
+          className="mono mt-3 text-xs text-muted hover:text-ink"
+          onClick={() => access.disconnect(location.origin)}
+        >
+          Forget current token
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+function CodeWindow({
+  file,
+  location,
+}: {
+  file: SourceFile;
+  location: SourceLocation;
+}) {
+  const rows = useMemo(
+    () => sourceWindow(file.content, location.line),
+    [file.content, location.line],
+  );
+  const highlighted = useMemo(
+    () => highlightSource(location.path, rows.map((row) => row.text).join("\n")),
+    [location.path, rows],
+  );
+  const focusedIndex = rows.findIndex((row) => row.focused);
+
+  const renderNode = (node: HighlightNode, key: string): ReactNode => {
+    if (node.type === "text") return node.value;
+    const names = node.properties?.className;
+    const className = Array.isArray(names)
+      ? names.filter((name): name is string => typeof name === "string").join(" ")
+      : typeof names === "string"
+        ? names
+        : undefined;
+    return (
+      <span key={key} className={className}>
+        {node.children.map((child, index) =>
+          renderNode(child, `${key}-${index}`),
+        )}
+      </span>
+    );
+  };
+
+  return (
+    <div
+      className="min-h-0 flex-1 overflow-auto bg-canvas py-2 text-[12px] leading-5"
+      tabIndex={0}
+    >
+      <div className="mono relative grid min-w-max grid-cols-[4rem_minmax(max-content,1fr)] text-ink">
+        {focusedIndex >= 0 ? (
+          <span
+            className="pointer-events-none absolute inset-x-0 h-5 bg-accent/10"
+            style={{ top: `${focusedIndex * 20}px` }}
+            aria-hidden
+          />
+        ) : null}
+        <div className="relative z-10">
+          {rows.map((row) => (
+            <div
+              key={row.number}
+              className={`h-5 select-none border-r pr-3 text-right ${row.focused ? "border-accent text-accent" : "border-line text-muted"}`}
+              aria-hidden
+            >
+              {row.number}
+            </div>
+          ))}
+        </div>
+        <pre className="source-code relative z-10 min-w-max pl-3 pr-4 text-ink">
+          <code>{highlighted.map((node, index) => renderNode(node, String(index)))}</code>
+        </pre>
+      </div>
+    </div>
+  );
+}
+
+function PreviewPanel({
+  id,
+  location,
+  pinned,
+  position,
+  panelRef,
+  onEnter,
+  onLeave,
+  onClose,
+}: {
+  id: string;
+  location: SourceLocation;
+  pinned: boolean;
+  position: Position;
+  panelRef: React.RefObject<HTMLDivElement | null>;
+  onEnter: () => void;
+  onLeave: () => void;
+  onClose: () => void;
+}) {
+  const access = useForgeAccess();
+  const token =
+    location.kind === "remote" ? access.tokenFor(location.origin) : "";
+  const source = useQuery(sourceCodeQuery(location, token));
+  const file = source.data ?? null;
+  const error = source.error;
+  const loading = source.isLoading;
+
+  const auth =
+    location.kind === "remote" &&
+    error instanceof SourceLoadError &&
+    error.authRequired;
+  const ref =
+    location.kind === "remote" ? location.ref.slice(0, 12) : "working tree";
+
+  return (
+    <div
+      id={id}
+      ref={panelRef}
+      role="dialog"
+      aria-label={`Source preview for ${location.path}`}
+      tabIndex={-1}
+      onPointerEnter={onEnter}
+      onPointerLeave={onLeave}
+      onKeyDown={(event) => {
+        if (event.key === "Escape") {
+          event.stopPropagation();
+          onClose();
+        }
+      }}
+      className="fixed z-[80] flex overflow-hidden rounded-control border border-line-strong bg-canvas shadow-md outline-none"
+      style={
+        {
+          position: "fixed",
+          zIndex: 80,
+          left: position.left,
+          top: position.top,
+          width: position.width,
+          maxHeight: position.maxHeight,
+          minHeight: 180,
+        } satisfies CSSProperties
+      }
+    >
+      <div className="flex min-h-0 min-w-0 flex-1 flex-col">
+        <div className="flex items-center gap-2 border-b border-line bg-surface px-3 py-2">
+          <Code2 size={15} className="shrink-0 text-accent" aria-hidden />
+          <span
+            className="mono min-w-0 flex-1 truncate text-xs text-ink"
+            title={location.path}
+          >
+            {location.path}
+          </span>
+          <span className="chip mono shrink-0">
+            {sourceLanguage(location.path)}
+          </span>
+          <span className="mono shrink-0 text-[11px] text-muted">{ref}</span>
+          {pinned ? (
+            <Pin
+              size={13}
+              className="shrink-0 text-accent"
+              aria-label="Preview pinned"
+            />
+          ) : null}
+          <EditorLink location={location} />
+          {location.href ? (
+            <a
+              href={location.href}
+              target="_blank"
+              rel="noreferrer"
+              className="rounded-control p-1 text-muted hover:bg-raised hover:text-accent"
+              aria-label="Open source on the forge"
+              title="Open on the forge"
+            >
+              <ExternalLink size={14} aria-hidden />
+            </a>
+          ) : null}
+          <button
+            type="button"
+            onClick={onClose}
+            className="rounded-control p-1 text-muted hover:bg-raised hover:text-ink"
+            aria-label="Close source preview"
+          >
+            <X size={14} aria-hidden />
+          </button>
+        </div>
+        {loading ? (
+          <div className="flex min-h-44 items-center justify-center gap-2 text-sm text-muted">
+            <LoaderCircle size={16} className="animate-spin" aria-hidden />{" "}
+            Loading source…
+          </div>
+        ) : auth ? (
+          <AccessForm location={location} message={error.message} />
+        ) : error ? (
+          <div className="p-4 text-sm text-muted">{error.message}</div>
+        ) : file ? (
+          <CodeWindow file={file} location={location} />
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+/** Hover/focus for a glance; click pins the same preview for scrolling and copying. */
+export function SourcePreviewButton({
+  location,
+  className = "",
+}: {
+  location: SourceLocation | null;
+  className?: string;
+}) {
+  const [open, setOpen] = useState(false);
+  const [pinned, setPinned] = useState(false);
+  const [position, setPosition] = useState<Position | null>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const pinnedRef = useRef(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const id = useMemo(
+    () => `source-preview-${Math.random().toString(36).slice(2)}`,
+    [],
+  );
+
+  const cancelTimer = useCallback(() => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = null;
+  }, []);
+  const close = useCallback(() => {
+    cancelTimer();
+    pinnedRef.current = false;
+    setOpen(false);
+    setPinned(false);
+  }, [cancelTimer]);
+  const openSoon = useCallback(() => {
+    cancelTimer();
+    timer.current = setTimeout(() => setOpen(true), OPEN_DELAY_MS);
+  }, [cancelTimer]);
+  const closeSoon = useCallback(() => {
+    if (pinnedRef.current) return;
+    cancelTimer();
+    timer.current = setTimeout(() => setOpen(false), CLOSE_DELAY_MS);
+  }, [cancelTimer]);
+
+  useEffect(() => () => cancelTimer(), [cancelTimer]);
+
+  useLayoutEffect(() => {
+    if (!open || !triggerRef.current) return;
+    const place = () => {
+      if (triggerRef.current)
+        setPosition(positionFor(triggerRef.current.getBoundingClientRect()));
+    };
+    place();
+    window.addEventListener("resize", place);
+    window.addEventListener("scroll", place, true);
+    return () => {
+      window.removeEventListener("resize", place);
+      window.removeEventListener("scroll", place, true);
+    };
+  }, [open]);
+
+  useEffect(() => {
+    if (!pinned) return;
+    const outside = (event: globalThis.PointerEvent) => {
+      const node = event.target as Node;
+      if (
+        !triggerRef.current?.contains(node) &&
+        !panelRef.current?.contains(node)
+      )
+        close();
+    };
+    document.addEventListener("pointerdown", outside);
+    return () => document.removeEventListener("pointerdown", outside);
+  }, [close, pinned]);
+
+  if (!location) return null;
+
+  const hover = (event: ReactPointerEvent) => {
+    if (event.pointerType === "mouse" || event.pointerType === "pen")
+      openSoon();
+  };
+
+  return (
+    <>
+      <button
+        ref={triggerRef}
+        type="button"
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        aria-controls={open ? id : undefined}
+        className={`mono inline-flex items-center gap-1 rounded-control text-accent hover:underline focus-visible:outline focus-visible:outline-1 focus-visible:outline-accent ${className}`}
+        title="Preview source · click to pin"
+        onPointerEnter={hover}
+        onPointerLeave={closeSoon}
+        onFocus={() => setOpen(true)}
+        onBlur={closeSoon}
+        onClick={() => {
+          cancelTimer();
+          if (open && pinned) {
+            close();
+            return;
+          }
+          setOpen(true);
+          pinnedRef.current = true;
+          setPinned(true);
+          setTimeout(() => panelRef.current?.focus(), 0);
+        }}
+      >
+        <Code2 size={13} aria-hidden /> preview
+      </button>
+      {open && position && typeof document !== "undefined"
+        ? createPortal(
+            <PreviewPanel
+              id={id}
+              location={location}
+              pinned={pinned}
+              position={position}
+              panelRef={panelRef}
+              onEnter={cancelTimer}
+              onLeave={closeSoon}
+              onClose={close}
+            />,
+            document.body,
+          )
+        : null}
+    </>
+  );
+}

package/src/components/TabRow.tsx

@@ -0,0 +1,182 @@
+import { useCallback, useEffect, useId, useRef, useState } from "react";
+import type { ReactNode } from "react";
+import { Tab } from "@headlessui/react";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { LayoutGroup, m, transitions } from "../lib/motion";
+
+/**
+ * The strip a page's tab list scrolls inside.
+ *
+ * Eight tabs are wider than a phone and wider than a laptop with something
+ * beside it, and a plain flex row answers that by cutting the last of them off
+ * mid-word - which reads as a rendering fault, not as a row that continues.
+ * So the row scrolls, and says so: a fade at whichever edge still has tabs
+ * behind it, and a chevron on the fade for a reader who has no trackpad to
+ * flick with. Both edges are tested independently, because the row can be
+ * scrolled to the middle and be cut off at both ends at once.
+ *
+ * The fades are drawn in the header's own background, so the tabs pass under
+ * them rather than into a band of some other colour; they take no pointer
+ * events, and the chevrons on top of them take theirs back.
+ */
+export function TabRow({
+  active,
+  children,
+}: {
+  /** The selected tab. Changing it scrolls that tab back into view. */
+  active?: string;
+  children: ReactNode;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  // Namespaces the bar's layoutId to this strip, for a screen with two.
+  const group = useId();
+  const [edges, setEdges] = useState({ left: false, right: false });
+
+  const measure = useCallback(() => {
+    const el = ref.current;
+    if (!el) return;
+    // Sub-pixel layout leaves a fraction of overflow on a row that is not
+    // actually cut off, and a fade over nothing is a lie about the row. One
+    // pixel of slack at each end is what keeps the affordance honest.
+    const max = el.scrollWidth - el.clientWidth;
+    const left = el.scrollLeft > 1;
+    const right = el.scrollLeft < max - 1;
+    setEdges((was) =>
+      was.left === left && was.right === right ? was : { left, right },
+    );
+  }, []);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    measure();
+    if (typeof ResizeObserver === "undefined") return;
+    // The strip's own width says how much room there is; the list inside it
+    // says how much is wanted, and that changes when the counts arrive.
+    const observer = new ResizeObserver(measure);
+    observer.observe(el);
+    if (el.firstElementChild) observer.observe(el.firstElementChild);
+    return () => observer.disconnect();
+  }, [measure]);
+
+  // A tab picked from the url can start life off the end of the strip, and a
+  // reader who cannot see the selected tab cannot tell which page they are on.
+  useEffect(() => {
+    const selected = ref.current?.querySelector('[aria-selected="true"]');
+    selected?.scrollIntoView({ block: "nearest", inline: "nearest" });
+  }, [active]);
+
+  const nudge = (direction: -1 | 1) => {
+    const el = ref.current;
+    if (!el) return;
+    el.scrollBy({
+      left: direction * Math.max(120, el.clientWidth * 0.6),
+      behavior: "smooth",
+    });
+  };
+
+  return (
+    <LayoutGroup id={group}>
+      <div className="relative">
+        {/* `layoutScroll`: the bar under the selected tab measures its trip
+            through this box, and the box scrolls the new tab into view in the
+            same breath. Without it the bar would start its slide from where
+            the old tab was before the scroll. */}
+        <m.div
+          ref={ref}
+          layoutScroll
+          onScroll={measure}
+          className="tab-scroll overflow-x-auto overscroll-x-contain"
+        >
+          {children}
+        </m.div>
+        <Edge side="left" show={edges.left} onClick={() => nudge(-1)} />
+        <Edge side="right" show={edges.right} onClick={() => nudge(1)} />
+      </div>
+    </LayoutGroup>
+  );
+}
+
+function Edge({
+  side,
+  show,
+  onClick,
+}: {
+  side: "left" | "right";
+  show: boolean;
+  onClick: () => void;
+}) {
+  const Icon = side === "left" ? ChevronLeft : ChevronRight;
+  return (
+    <div
+      aria-hidden
+      className={`pointer-events-none absolute inset-y-0 flex items-center transition-opacity ${
+        side === "left"
+          ? "left-0 justify-start bg-gradient-to-r"
+          : "right-0 justify-end bg-gradient-to-l"
+      } w-12 from-canvas to-transparent ${show ? "opacity-100" : "opacity-0"}`}
+    >
+      {/* Not a tab stop: everything behind the fade is reachable by tabbing
+          through the tabs themselves, which scrolls the strip on its own. The
+          chevron is for the pointer that has no wheel to spin sideways. */}
+      <button
+        type="button"
+        tabIndex={-1}
+        onClick={onClick}
+        disabled={!show}
+        className={`pointer-events-auto flex size-6 items-center justify-center rounded-control text-muted transition-colors hover:bg-surface hover:text-ink ${
+          show ? "" : "invisible"
+        }`}
+      >
+        <Icon size={14} />
+      </button>
+    </div>
+  );
+}
+
+/**
+ * The count beside a tab's name. A bare number ran straight into the label -
+ * "provides 6" read as one token at a glance - so it gets a box of its own:
+ * the same hairline the rest of the chrome is drawn in, tight enough that the
+ * tab does not grow a second word.
+ */
+export function TabCount({ children }: { children: ReactNode }) {
+  return (
+    <span className="tnum ml-1.5 rounded-[4px] border px-1 border-line text-muted">
+      {children}
+    </span>
+  );
+}
+
+/**
+ * A tab. The same on every page that has tabs, and the strip's one moving
+ * part: the accent bar under the selected tab is a single element that slides
+ * from the old tab to the new, not a border each tab paints for itself. Every
+ * tab keeps a transparent 2px border so the bar has a slot to sit in and
+ * selecting one never nudges the text.
+ */
+export function TabButton({ children }: { children: ReactNode }) {
+  return (
+    <Tab
+      className={({ selected }) =>
+        `mono relative shrink-0 rounded-t-control border-b-2 border-transparent px-3 py-1.5 t-micro transition-colors focus:outline-none ${
+          selected ? "text-ink" : "text-muted hover:text-ink"
+        }`
+      }
+    >
+      {({ selected }) => (
+        <>
+          {children}
+          {selected ? (
+            <m.span
+              layoutId="tab-bar"
+              aria-hidden
+              className="pointer-events-none absolute inset-x-0 -bottom-0.5 h-0.5 bg-accent"
+              transition={transitions.settle}
+            />
+          ) : null}
+        </>
+      )}
+    </Tab>
+  );
+}