@shortlink-org/portolan 0.1.0

package/src/components/TechIcon.tsx

@@ -0,0 +1,34 @@
+// A brand's mark, drawn so it sits in a row with lucide.
+//
+// simple-icons fills its 24x24 box edge to edge; lucide leaves a 2px margin
+// inside its own. Shown at the same pixel size the brand mark would read a
+// step heavier than the database glyph beside it, so the viewBox is opened by
+// two units on every side and the two families weigh the same.
+
+import type { TechGlyph } from "../lib/tech";
+
+export function TechIcon({
+  glyph,
+  size = 14,
+  className = "",
+}: {
+  glyph: TechGlyph;
+  size?: number;
+  className?: string;
+}) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox="-2 -2 28 28"
+      fill="currentColor"
+      aria-hidden
+      /* `block` for the same reason KindIcon is: no inline baseline gap, so
+         the mark centres on the text beside it. */
+      className={`block shrink-0 ${className}`}
+    >
+      <path d={glyph.path} />
+    </svg>
+  );
+}

package/src/components/Toc.tsx

@@ -0,0 +1,132 @@
+// The right-edge table of contents, with scroll-spy.
+//
+// It began as the readme outline on the aggregate page and is now the one
+// component every long page uses, because two implementations of "where am I"
+// is exactly how the two start disagreeing.
+//
+// It costs 24px of the page, not 208.
+//
+// At rest it is a column of ticks - one per section, the one you are in lit -
+// which is the whole of what a table of contents is for while you are reading:
+// how many sections, and which. The names are what you want only when you have
+// decided to leave, so they arrive on hover or focus, in a panel that opens
+// leftwards OVER the page rather than pushing it. Nothing reflows: the dock
+// keeps its 24px whether the panel is open or not.
+//
+// Spy notes: the observer's root is the page's own scroll container, not the
+// window - this shell never scrolls the document - and the bottom margin is
+// pulled up to 65% so a section counts as "here" once its heading reaches the
+// upper third, which is where a reader actually thinks they are.
+
+import { useEffect, useMemo, useState } from "react";
+
+export interface TocItem {
+  /** The id of the element on the page. */
+  id: string;
+  label: string;
+  /** 1 is flush left; each level indents 10px. */
+  depth?: number;
+}
+
+/** Nearest scrollable ancestor, or null when the page scrolls in the window. */
+function scrollParent(el: Element | null): Element | null {
+  let node = el?.parentElement ?? null;
+  while (node) {
+    const overflow = getComputedStyle(node).overflowY;
+    if (overflow === "auto" || overflow === "scroll") return node;
+    node = node.parentElement;
+  }
+  return null;
+}
+
+export function useScrollSpy(ids: readonly string[]): string | null {
+  const [active, setActive] = useState<string | null>(ids[0] ?? null);
+  const key = ids.join(" ");
+
+  useEffect(() => {
+    const list = key ? key.split(" ") : [];
+    const elements = list
+      .map((id) => document.getElementById(id))
+      .filter((el): el is HTMLElement => el !== null);
+    if (elements.length === 0) return;
+
+    const seen = new Set<string>();
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) seen.add(entry.target.id);
+          else seen.delete(entry.target.id);
+        }
+        // First in document order wins, so scrolling down moves the marker
+        // down one section at a time rather than jumping to whatever fired.
+        const first = list.find((id) => seen.has(id));
+        // Nothing intersecting means the reader is between two sections;
+        // holding the last answer beats blanking the rail.
+        if (first) setActive(first);
+      },
+      {
+        root: scrollParent(elements[0] ?? null),
+        rootMargin: "0px 0px -65% 0px",
+        threshold: 0,
+      },
+    );
+    for (const el of elements) observer.observe(el);
+    return () => observer.disconnect();
+  }, [key]);
+
+  return active;
+}
+
+export function Toc({
+  items,
+  label = "On this page",
+  title = "On this page",
+}: {
+  items: readonly TocItem[];
+  /** Accessible name for the nav landmark. */
+  label?: string;
+  /** The heading printed above the list, once the panel is open. */
+  title?: string;
+}) {
+  const ids = useMemo(() => items.map((i) => i.id), [items]);
+  const active = useScrollSpy(ids);
+
+  if (items.length === 0) return null;
+
+  return (
+    <nav
+      /* Hidden below the two-column breakpoint, where the page has no right
+         edge to spare at all. */
+      className="toc-dock sticky hidden h-fit shrink-0 self-start lg:block"
+      aria-label={label}
+    >
+      <div className="toc-panel">
+        <div className="label toc-name mb-1 px-3 pt-1">{title}</div>
+        <ul>
+          {items.map((item) => {
+            const on = item.id === active;
+            return (
+              <li key={item.id}>
+                <a
+                  href={`#${item.id}`}
+                  aria-current={on ? "location" : undefined}
+                  /* The tick is the marker AND the hairline: 2px, always
+                     drawn, transparent when idle, so nothing shifts as the
+                     spy moves down the page. */
+                  className={`toc-item ${on ? "text-ink" : "text-muted"}`}
+                  style={{
+                    borderColor: on ? "var(--accent)" : "var(--border)",
+                    marginLeft: ((item.depth ?? 1) - 1) * 10,
+                  }}
+                  title={item.label}
+                >
+                  <span className="toc-name">{item.label}</span>
+                </a>
+              </li>
+            );
+          })}
+        </ul>
+      </div>
+    </nav>
+  );
+}

package/src/components/WhatLinksHere.tsx

@@ -0,0 +1,273 @@
+// The incoming half of the graph, drawn the same way on every entity page.
+//
+// A page's own body says what a thing depends on. This says what depends on
+// it — the question a reader actually arrives with, and the one no single
+// entity can answer about itself. It sits last on every page and answers under
+// the same heading, at the same anchor, in the same row shape, so "who breaks
+// if I change this" is one place to look rather than five different ones.
+//
+// Every row says WHY it is here. A name with no reason attached would send the
+// reader to open the page just to find out, which is the trip this section
+// exists to save.
+
+import { useMemo } from "react";
+import type { ReactNode } from "react";
+import { Link } from "react-router";
+import { catalog, index } from "../data";
+import { backlinkCount, backlinksFor } from "../lib/backlinks";
+import type { Backlink, BacklinkGroup, BacklinkTarget } from "../lib/backlinks";
+import { plural } from "../lib/format";
+import { KIND_LABEL, KIND_PLURAL } from "../lib/kinds";
+import type { Kind } from "../lib/kinds";
+import { LINKS_HERE, backlinkPath } from "../routes";
+import { KIND_COLOR, KindIcon } from "./kind";
+import { Empty, SectionTitle } from "./PageHeader";
+import { RowActions } from "./RowActions";
+import { StatusChip } from "./primitives";
+
+/** A section on this same page that already lists one kind of link, in full. */
+export interface Elsewhere {
+  /** Where it is: a fragment, or a tab's query string. */
+  href: string;
+  /** What it is called there, so the pointer names the thing it points at. */
+  label: string;
+}
+
+/** Kinds the tree draws a row for, and so the ones "reveal" can find. */
+const REVEALABLE: readonly Kind[] = [
+  "context",
+  "service",
+  "aggregate",
+  "event",
+] as const;
+
+/**
+ * The same answer this section draws, for a page that also wants to count it
+ * in its header. Derived twice rather than threaded through props, because it
+ * is a pure walk over a catalog that does not change while the page is open.
+ */
+export function useBacklinks(target: BacklinkTarget): BacklinkGroup[] {
+  return useMemo(
+    () => backlinksFor(catalog, index, target),
+    [target.kind, target.id],
+  );
+}
+
+function Row({ link }: { link: Backlink }) {
+  const to = backlinkPath(link);
+  // What a reader takes to a grep: the flow's slug is not enough to find the
+  // step inside it, so a link that points through one carries both.
+  const id = link.at ? `${link.id}/${link.at}` : link.id;
+  const reveal = to && REVEALABLE.includes(link.kind) ? link.id : undefined;
+  return (
+    /* A div holding a link, not a link holding buttons: the row actions are
+       interactive too, and interactive content does not nest. */
+    <div className="row gap-2">
+      <KindIcon kind={link.kind} contextId={link.context ?? undefined} />
+      {to ? (
+        /* Only events are painted by kind. Everything else keeps the ink of a
+           link in a row, because eight muted names in a column would read as
+           eight pieces of text rather than eight places to go. */
+        <Link
+          to={to}
+          data-nav-item
+          data-peek={link.id}
+          className="mono shrink-0 rounded-control"
+          style={
+            link.kind === "event" ? { color: KIND_COLOR.event } : undefined
+          }
+          title={id}
+        >
+          {link.name}
+        </Link>
+      ) : (
+        <span
+          className={`mono shrink-0 ${
+            link.status === "unresolved" ? "text-unresolved" : "text-muted"
+          }`}
+          title={id}
+        >
+          {link.name}
+        </span>
+      )}
+      {/* One cell per column, empty ones included: the rows share a subgrid,
+          and a row that skips a field would slide every field after it into
+          the wrong column. */}
+      {link.owner ? (
+        <span className="min-w-0 truncate text-muted" title={link.owner}>
+          {link.owner}
+        </span>
+      ) : (
+        <span />
+      )}
+      <span className="mono shrink-0 text-muted" title="how it points here">
+        {link.via}
+      </span>
+      {link.versions && link.versions.length > 0 ? (
+        <span
+          className="mono justify-self-start rounded-[4px] border px-1 border-line text-muted"
+          title="event versions carrying it"
+        >
+          {link.versions.join(" ")}
+        </span>
+      ) : (
+        <span />
+      )}
+      {link.status ? <StatusChip status={link.status} /> : <span />}
+      <RowActions copy={id} {...(reveal ? { reveal } : {})} label={link.name} />
+    </div>
+  );
+}
+
+export function WhatLinksHere({
+  target,
+  variant = "section",
+  className = "",
+  elsewhere,
+  empty,
+}: {
+  target: BacklinkTarget;
+  /** `line` only: what the row it is folded into wants of its spacing. */
+  className?: string;
+  /**
+   * `section` is the block every scrolling page ends with. `line` is the same
+   * facts as one row of chips, for a page with no bottom to put a section on -
+   * the flow, whose rail and canvas take the whole height.
+   */
+  variant?: "section" | "line";
+  /**
+   * Kinds this page already lists in a section of their own, mapped to where
+   * that section is. Those rows are not repeated here; the count and a pointer
+   * to them are, so the whole answer is still readable in one place.
+   */
+  elsewhere?: Partial<Record<Kind, Elsewhere>>;
+  /** What to say when nothing points here, when the reason is worth saying. */
+  empty?: ReactNode;
+}) {
+  const groups = useBacklinks(target);
+
+  const total = backlinkCount(groups);
+  const shown = groups.filter((g) => !elsewhere?.[g.kind]);
+  const pointers = groups
+    .map((g) => ({ group: g, at: elsewhere?.[g.kind] }))
+    .filter((p): p is { group: (typeof groups)[number]; at: Elsewhere } =>
+      Boolean(p.at),
+    );
+
+  if (variant === "line") {
+    // Nothing to say, so nothing is said: a hero row is not the place for an
+    // empty state, and "linked from —" is worse than silence.
+    if (total === 0) return null;
+    return (
+      <span
+        className={`mono flex flex-wrap items-center gap-1.5 text-muted ${className || "mt-2"}`}
+      >
+        linked from
+        {groups
+          .flatMap((g) => g.links)
+          .map((link) => {
+            const to = backlinkPath(link);
+            const body = (
+              <>
+                <KindIcon
+                  kind={link.kind}
+                  contextId={link.context ?? undefined}
+                />
+                {link.name}
+              </>
+            );
+            const title = `${link.owner ?? link.id} — ${link.via}`;
+            return to ? (
+              <Link
+                key={`${link.kind}:${link.id}:${link.name}`}
+                to={to}
+                data-peek={link.id}
+                className="chip border-line-strong hover:text-ink"
+                title={title}
+              >
+                {body}
+              </Link>
+            ) : (
+              <span
+                key={`${link.kind}:${link.id}:${link.name}`}
+                className="chip border-line"
+                title={title}
+              >
+                {body}
+              </span>
+            );
+          })}
+      </span>
+    );
+  }
+
+  return (
+    <section id={LINKS_HERE} className="mt-section max-w-table">
+      <SectionTitle
+        anchor={LINKS_HERE}
+        right={
+          <span>
+            <span className="tnum">{total}</span> incoming
+          </span>
+        }
+      >
+        What links here
+      </SectionTitle>
+
+      {total === 0 ? (
+        <Empty>{empty ?? "nothing in the catalog points here"}</Empty>
+      ) : null}
+
+      {shown.map((group) => (
+        <div key={group.kind} className="mt-3 first:mt-0">
+          <div className="label mb-1.5">
+            {KIND_PLURAL[group.kind]}{" "}
+            <span className="tnum">{group.links.length}</span>
+          </div>
+          {/* icon, name, owner, why it points here, the versions carrying
+              it, status, actions. The owner takes the slack, so the reason
+              and everything after it hold the same column down the group. */}
+          <div
+            className="rows grid-cols-[auto_auto_1fr_auto_auto_auto_auto]"
+            data-nav-list
+          >
+            {group.links.map((link, i) => (
+              <Row
+                key={`${link.kind}:${link.id}:${link.at ?? i}`}
+                link={link}
+              />
+            ))}
+          </div>
+        </div>
+      ))}
+
+      {pointers.map(({ group, at }) => {
+        const body = (
+          <>
+            <KindIcon kind={group.kind} />
+            <span className="tnum">{group.links.length}</span>
+            {plural(
+              group.links.length,
+              KIND_LABEL[group.kind],
+              KIND_PLURAL[group.kind],
+            )}
+            <span className="ml-auto">listed under {at.label}</span>
+          </>
+        );
+        const className = "row mono mt-3 gap-2 text-muted hover:text-ink";
+        // A section on this page is a fragment and the browser can jump to it
+        // on its own; a tab is a route, and routing it through <a> would
+        // reload the whole app to change one panel.
+        return at.href.startsWith("#") ? (
+          <a key={group.kind} href={at.href} className={className}>
+            {body}
+          </a>
+        ) : (
+          <Link key={group.kind} to={at.href} className={className}>
+            {body}
+          </Link>
+        );
+      })}
+    </section>
+  );
+}

package/src/components/WsdlReference.tsx

@@ -0,0 +1,84 @@
+// A WSDL contract drawn from the structured facts extract-wsdl recorded.
+// Unlike OpenAPI, the catalog already carries the operation binding and the
+// reachable message shapes, so this remains useful when the source repository
+// is not bundled into the generated site.
+
+import { useState } from "react";
+import type { RpcMethod, RpcService } from "../catalog";
+import { Empty, SectionTitle } from "./PageHeader";
+import { Ident } from "./Ident";
+import { MessageList, MethodRows } from "./MethodRows";
+
+export function WsdlReference({
+  source,
+  provided,
+}: {
+  source: string;
+  provided: RpcService[];
+}) {
+  const [open, setOpen] = useState<ReadonlySet<string>>(new Set());
+  const interfaces = provided.filter((item) => item.source === source);
+  const toggle = (id: string) =>
+    setOpen((shown) => {
+      const next = new Set(shown);
+      if (!next.delete(id)) next.add(id);
+      return next;
+    });
+
+  if (interfaces.length === 0) {
+    return <Empty>the WSDL source names no interface in this catalog</Empty>;
+  }
+
+  return (
+    <div className="max-w-table">
+      <p className="mono text-muted">{source}</p>
+      {interfaces.map((iface) => {
+        const soap = iface.methods.find((method) => method.soap)?.soap;
+        return (
+          <section key={iface.id} className="mt-section">
+            <SectionTitle>{iface.id}</SectionTitle>
+            <div className="rounded-card border border-line">
+              <div className="flex flex-wrap items-center gap-x-2 border-b border-line bg-surface px-3 py-1.5">
+                <Ident value={iface.id} className="text-ink" />
+                {soap?.version ? <span className="chip">SOAP {soap.version}</span> : null}
+                {soap?.style ? <span className="chip">{soap.style}</span> : null}
+                {soap?.binding ? <span className="chip mono">{soap.binding}</span> : null}
+                {soap?.endpoint ? (
+                  <span className="mono min-w-0 truncate text-muted" title={soap.endpoint}>
+                    {soap.endpoint}
+                  </span>
+                ) : null}
+              </div>
+              <MethodRows provided={iface} open={open} onToggle={toggle} />
+              <MessageList provided={iface} open={open} onToggle={toggle} />
+            </div>
+          </section>
+        );
+      })}
+    </div>
+  );
+}
+
+/** The one external SOAP operation a consumer card points at. */
+export function SoapCallContract({
+  provided,
+  method,
+}: {
+  provided: RpcService;
+  method: RpcMethod;
+}) {
+  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 one = { ...provided, methods: [method] };
+
+  return (
+    <div className="mt-1 w-full rounded-control border border-line bg-surface">
+      <MethodRows provided={one} open={open} onToggle={toggle} />
+    </div>
+  );
+}

package/src/components/ddd-icons.tsx

@@ -0,0 +1,107 @@
+// The five DDD building blocks, drawn rather than borrowed.
+//
+// Lucide has no vocabulary for a domain event or a value object, so what it
+// lends instead is a metaphor: Zap for an event, Diamond for a value object,
+// Square for an entity. Each of those says "roughly this shape" and nothing
+// about what the thing IS. These five say what the thing is.
+//
+// They are drawn on lucide's own grid - 24x24, 1.5px stroke, round caps and
+// joins, no fill - so a value object standing next to a lucide chevron in the
+// tree reads as one family and not as an imported sticker.
+//
+// The semantics, one line each:
+//
+//   event    a fact, announced: a point that already happened, and the pulse
+//            leaving it. Every other context hears about it after the fact.
+//   vo       a shape with no identity: a diamond holding an equals sign -
+//            two equal values ARE the same value.
+//   entity   a shape with identity: the same square, and the one dot that
+//            says this instance is not that one.
+//   command  a directive arriving at the aggregate: an arrow that lands on
+//            the boundary and changes what is behind it.
+//   query    the same boundary, answering: rows leaving it, changing nothing.
+
+import type { SVGProps } from "react";
+
+export interface DddIconProps extends Omit<SVGProps<SVGSVGElement>, "ref"> {
+  size?: number;
+}
+
+/**
+ * Shared frame. Every attribute lucide sets on its own icons is set here, so
+ * the two families size, colour and align identically.
+ */
+function Icon({ size = 16, children, ...rest }: DddIconProps) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      {...rest}
+    >
+      {children}
+    </svg>
+  );
+}
+
+/** A fact that happened, and the pulse that carried it outward. */
+export function EventIcon(props: DddIconProps) {
+  return (
+    <Icon {...props}>
+      <circle cx={7} cy={12} r={1.6} />
+      <path d="M9.9 8.4a4.6 4.6 0 0 1 0 7.2" />
+      <path d="M12.2 5.4a8.4 8.4 0 0 1 0 13.2" />
+    </Icon>
+  );
+}
+
+/** No identity: equal values are the same value. */
+export function ValueObjectIcon(props: DddIconProps) {
+  return (
+    <Icon {...props}>
+      <path d="M12 3.5 20.5 12 12 20.5 3.5 12Z" />
+      <path d="M9 10.5h6" />
+      <path d="M9 13.5h6" />
+    </Icon>
+  );
+}
+
+/** Identity: this one, tracked over time, and not that one. */
+export function EntityIcon(props: DddIconProps) {
+  return (
+    <Icon {...props}>
+      <rect x={4} y={4} width={16} height={16} rx={3} />
+      <circle cx={12} cy={12} r={1.6} />
+    </Icon>
+  );
+}
+
+/** A directive landing on the aggregate boundary. */
+export function CommandIcon(props: DddIconProps) {
+  return (
+    <Icon {...props}>
+      <path d="M19 4.5v15" />
+      <path d="M4 12h11" />
+      <path d="m11.5 8.5 3.5 3.5-3.5 3.5" />
+    </Icon>
+  );
+}
+
+/** The same boundary, answering. Rows out, nothing changed. */
+export function QueryIcon(props: DddIconProps) {
+  return (
+    <Icon {...props}>
+      <path d="M19 4.5v15" />
+      <path d="M19 9H7" />
+      <path d="m10.5 5.5-3.5 3.5 3.5 3.5" />
+      <path d="M19 15h-8" />
+      <path d="m14.5 11.5-3.5 3.5 3.5 3.5" />
+    </Icon>
+  );
+}