@shortlink-org/portolan 0.1.0

package/src/components/PageHeader.tsx

@@ -0,0 +1,189 @@
+import { useDocumentTitle } from "../app/title";
+import { useLayoutEffect, useRef, useState } from "react";
+import type { ReactNode } from "react";
+import { ctxStyle } from "../lib/context-color";
+import { PinButton } from "../app/pins";
+import type { PinKind } from "../lib/pins";
+import { AnchorLink } from "./AnchorLink";
+import { Ident } from "./Ident";
+
+/**
+ * The header strip every entity page opens with. `contextId` paints the hero
+ * wash - 120px of that context's colour at 6%, fading to nothing. The header's
+ * own content sits above it on solid background, so no text is ever read off
+ * a gradient.
+ *
+ * `pin` puts the pin control at the head of the right-hand group, before
+ * whatever else the page puts there. It is first because it is the only
+ * control on the strip that is about the reader rather than about the entity,
+ * and a reader looking for it should find it in the same place on every page.
+ *
+ * Only the name row is pinned (`.page-bar`): the name, its id, and the
+ * controls at its right. The kind label above it and whatever the page puts
+ * under it - a meta row, a tab list - scroll away like the rest of the page;
+ * they were read on arrival, and a strip that kept them would be a strip that
+ * kept a third of a small window. The row is transparent in place and goes
+ * opaque once it is pinned, so the text is never read through the page
+ * scrolling under it. Rendered as siblings rather than one wrapper, because a
+ * sticky row pins inside its parent only, and its parent has to be the box
+ * that scrolls.
+ *
+ * The row publishes its height as `--page-header-h` on that box: the toc dock
+ * pins itself under it, and the box's scroll-padding keeps an anchor jump
+ * from landing behind it.
+ */
+const HEIGHT_VAR = "--page-header-h";
+
+export function PageHeader({
+  kind,
+  name,
+  id,
+  contextId,
+  pin,
+  right,
+  children,
+}: {
+  /** The kind of thing, and what it belongs to - the latter usually a link. */
+  kind: ReactNode;
+  name: string;
+  id?: string;
+  contextId?: string | null;
+  /** What pinning this page pins. Omitted on pages that are not pinnable. */
+  pin?: { kind: PinKind; id: string };
+  right?: ReactNode;
+  children?: ReactNode;
+}) {
+  const bar = useRef<HTMLDivElement>(null);
+  const [stuck, setStuck] = useState(false);
+  useDocumentTitle(name);
+
+  useLayoutEffect(() => {
+    const el = bar.current;
+    const host = el?.parentElement;
+    if (!el || !host) return;
+
+    const publish = () =>
+      host.style.setProperty(HEIGHT_VAR, `${el.offsetHeight}px`);
+    publish();
+    const observer =
+      typeof ResizeObserver === "undefined" ? null : new ResizeObserver(publish);
+    observer?.observe(el);
+
+    // Pinned means the row is at the top of the box and the box has scrolled:
+    // the same test the browser applies, read back off the geometry.
+    let was = false;
+    const onScroll = () => {
+      const now =
+        host.scrollTop > 0 &&
+        el.getBoundingClientRect().top - host.getBoundingClientRect().top < 1;
+      if (now !== was) {
+        was = now;
+        setStuck(now);
+      }
+    };
+    onScroll();
+    host.addEventListener("scroll", onScroll, { passive: true });
+
+    return () => {
+      observer?.disconnect();
+      host.removeEventListener("scroll", onScroll);
+      host.style.removeProperty(HEIGHT_VAR);
+    };
+  }, []);
+
+  return (
+    <>
+      <div className="hero px-gutter pt-5">
+        <div aria-hidden className="hero-wash" style={ctxStyle(contextId)} />
+        <div className="label">{kind}</div>
+      </div>
+      <div
+        ref={bar}
+        className="page-bar flex flex-wrap items-baseline gap-x-3 gap-y-1 px-gutter py-1.5"
+        data-stuck={stuck ? "" : undefined}
+      >
+        <h1 className="text-md font-semibold" title={name}>
+          {name}
+        </h1>
+        {/* The id under a page's own name is the single most-copied string in
+            the app - it is what a reader takes to a grep or a ticket. */}
+        {id ? <Ident value={id} className="text-muted" /> : null}
+        {pin || right ? (
+          <div className="ml-auto flex items-center gap-2">
+            {pin ? (
+              <PinButton kind={pin.kind} id={pin.id} label={name} />
+            ) : null}
+            {right}
+          </div>
+        ) : null}
+      </div>
+      <div className="border-b border-line px-gutter pb-3.5">{children}</div>
+    </>
+  );
+}
+
+export function SectionTitle({
+  children,
+  right,
+  anchor,
+}: {
+  children: ReactNode;
+  right?: ReactNode;
+  /**
+   * The id of the section this titles. Every count in this app already links
+   * to one of these; passing it here is what lets a reader link back out.
+   */
+  anchor?: string;
+}) {
+  return (
+    <div
+      className={`section-head mb-3 flex items-center gap-2 ${anchor ? "anchored" : ""}`}
+    >
+      <h2 className="section-title">{children}</h2>
+      {anchor ? (
+        <AnchorLink
+          id={anchor}
+          {...(typeof children === "string" ? { label: children } : {})}
+        />
+      ) : null}
+      {right ? <div className="section-aside ml-auto">{right}</div> : null}
+    </div>
+  );
+}
+
+export function Empty({ children }: { children: ReactNode }) {
+  return <div className="empty">{children}</div>;
+}
+
+/**
+ * What a page says before the catalog has anything to put on it.
+ *
+ * `Empty` answers a question the reader asked - a filter, a lookup - with
+ * "nothing". This answers one they have not asked yet: the first catalog off a
+ * real repository is one context and a handful of events, and the sections it
+ * cannot fill must read as the start of something rather than as a dashboard
+ * with its wires cut. So it says where the missing facts come from, and names
+ * the file they land in - the one thing a reader can act on today.
+ */
+export function Blank({
+  children,
+  where,
+}: {
+  children: ReactNode;
+  /** Path in the repository the absent facts are read from. */
+  where?: string;
+}) {
+  return (
+    <div className="empty">
+      {/* The box is as wide as the list it stands in for, but a sentence is
+          not: capped at prose width and centred, so it does not run the full
+          bleed of a wide window. */}
+      <div className="mx-auto max-w-prose">{children}</div>
+      {where ? (
+        <div className="mt-2">
+          <Ident value={where} />
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/RowActions.tsx

@@ -0,0 +1,97 @@
+// What a row offers once the pointer is on it.
+//
+// Two actions, and both answer a question a table cannot: "give me that id" and
+// "where does this sit?". They are hidden at rest because a list of forty rows
+// with eighty buttons in it is a list nobody can read, and they are in the DOM
+// rather than conditionally rendered so keyboard focus can still reach them.
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Copy, ListTree } from "lucide-react";
+import { toClipboard } from "../lib/clipboard";
+import { useUiStore } from "../app/ui-store";
+import { useSelectionStore } from "../selection/store";
+
+const SHOWN_MS = 1000;
+
+export function RowActions({
+  copy,
+  reveal,
+  label,
+}: {
+  /** The string the copy button puts on the clipboard. */
+  copy: string;
+  /**
+   * A catalog id the sidebar tree draws a row for - a context, a service, an
+   * aggregate or an event. Omitted for anything the tree has no row for.
+   */
+  reveal?: string;
+  /** What the buttons say they are acting on, for the accessible names. */
+  label?: string;
+}) {
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const select = useSelectionStore((s) => s.select);
+  const requestReveal = useUiStore((s) => s.requestReveal);
+
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  const what = label ?? copy;
+
+  const onCopy = useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      void toClipboard(copy).then((ok) => {
+        setCopied(ok);
+        if (timer.current) clearTimeout(timer.current);
+        timer.current = setTimeout(() => setCopied(false), SHOWN_MS);
+      });
+    },
+    [copy],
+  );
+
+  const onReveal = useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      if (!reveal) return;
+      // The tree opens its own ancestors and scrolls itself once the selection
+      // lands; all this has to do is make sure there is a tree to scroll.
+      select(reveal, "page");
+      requestReveal();
+    },
+    [reveal, select, requestReveal],
+  );
+
+  return (
+    <span className="row-actions ml-auto shrink-0">
+      <button
+        type="button"
+        onClick={onCopy}
+        className="row-action"
+        aria-label={`Copy ${what}`}
+        title={`Copy ${what}`}
+      >
+        <Copy size={12} aria-hidden />
+        {copied ? "copied" : "copy"}
+      </button>
+      {reveal ? (
+        <button
+          type="button"
+          onClick={onReveal}
+          className="row-action"
+          aria-label={`Reveal ${what} in the catalog tree`}
+          title="Reveal in tree"
+        >
+          <ListTree size={12} aria-hidden />
+          reveal
+        </button>
+      ) : null}
+    </span>
+  );
+}

package/src/components/SchemaDocument.tsx

@@ -0,0 +1,89 @@
+// The GraphQL schema itself, as it is written.
+//
+// The rule the OpenAPI reference beside it states - draw the document, because
+// the catalog cannot carry the document's own shape - is not quite the reason
+// here. `extract-graphql` does read the shape: the provides tab lists every
+// field with what it takes and what it answers, linked and searchable, and a
+// second copy of that would be worth nothing.
+//
+// What the SDL carries that the catalog does not is that it is the artifact
+// itself. A client author is given this text and writes queries against it,
+// and a proto's reader has a module page to go to for the same thing while a
+// schema has nowhere else to be. So it is shown as written - no rendering, no
+// second navigation tree - and the facts stay next door.
+
+import { useEffect, useState } from "react";
+import { loaderFor as loaderIn } from "../lib/spec-files";
+import { Empty } from "./PageHeader";
+
+/**
+ * The schemas in the repository, by path, loaded on demand. A schema that
+ * lives in another repository is not here, which is the normal case: the
+ * catalog still lists what the service answers, and this tab says plainly that
+ * it has nothing to show.
+ */
+const SCHEMAS = import.meta.glob<string>(
+  [
+    "../../**/*.graphql",
+    "../../**/*.graphqls",
+    "!../../node_modules/**",
+    "!../../dist/**",
+    "!../../.portolan/**",
+  ],
+  { query: "?raw", import: "default" },
+);
+
+/** Whether the schema a catalog entry points at is one this site can show. */
+export function hasSchema(source: string): boolean {
+  return loaderIn(SCHEMAS, source) !== null;
+}
+
+export function SchemaDocument({ source }: { source: string }) {
+  const [schema, setSchema] = useState<string | null>(null);
+  const [missing, setMissing] = useState(false);
+
+  useEffect(() => {
+    const load = loaderIn(SCHEMAS, source);
+    if (!load) {
+      setMissing(true);
+
+      return;
+    }
+
+    let live = true;
+    load()
+      .then((text) => {
+        if (live) setSchema(text);
+      })
+      .catch(() => {
+        if (live) setMissing(true);
+      });
+
+    return () => {
+      live = false;
+    };
+  }, [source]);
+
+  if (missing) {
+    return (
+      <Empty>
+        this service&apos;s schema is not in this repository — only the fields
+        the catalog extracted from it are
+      </Empty>
+    );
+  }
+
+  if (schema === null) return <Empty>reading the schema…</Empty>;
+
+  return (
+    <div className="flex flex-col gap-2">
+      <p className="text-muted text-sm">
+        The module as it is written, at <code className="mono">{source}</code>.
+        What it declares is on the provides tab, where it links.
+      </p>
+      <pre className="mono overflow-x-auto rounded-card border border-line p-2 text-sm">
+        {schema}
+      </pre>
+    </div>
+  );
+}

package/src/components/Select.tsx

@@ -0,0 +1,126 @@
+// A picker that looks like the rest of the app.
+//
+// A native <select> is a control the operating system draws: a different font,
+// a different radius, a different focus ring and, on macOS, a popup that
+// ignores the dark theme entirely. Two of them sat in the middle of pages
+// otherwise built out of six radii and one border colour, and both were the
+// only place where the app stopped looking like itself.
+//
+// The behaviour is Headless UI's Listbox and the paint is ours. That division
+// is the whole point of the dependency: the ARIA wiring, the focus return, the
+// typeahead, the scroll-into-view and the outside-click are a listbox's boring
+// half and are the half that is easy to get subtly wrong, while the part this
+// app actually cares about - that a control is `.tbtn` and a popup is a
+// hairline on --bg - stays here, in tokens, where every other control keeps it.
+//
+// Positioning comes with it: `anchor` puts the panel under the button and
+// flips it to the other edge when the button is near the side of the window.
+// A picker in a page header's right slot has no room to its right, and a panel
+// that opens off the edge does not clip - it widens the pane and scrolls the
+// whole page sideways.
+
+import {
+  Listbox,
+  ListboxButton,
+  ListboxOption,
+  ListboxOptions,
+} from "@headlessui/react";
+import { Check, ChevronDown } from "lucide-react";
+
+export interface SelectOption {
+  value: string;
+  label: string;
+  /** Second line, for the options that need saying rather than naming. */
+  note?: string;
+}
+
+export function Select({
+  value,
+  options,
+  onChange,
+  label,
+  title,
+  className = "",
+  menuWidth,
+}: {
+  value: string;
+  options: readonly SelectOption[];
+  onChange: (value: string) => void;
+  /** Accessible name. Rendered by the caller when it is visible. */
+  label: string;
+  title?: string;
+  className?: string;
+  /** Width of the panel. Defaults to "as wide as the button, at least 160px". */
+  menuWidth?: number;
+}) {
+  const selected = options.find((o) => o.value === value);
+
+  return (
+    <Listbox value={value} onChange={onChange}>
+      {/* Open state comes back as a render prop rather than a `data-open:`
+          variant: `.tbtn-on` is a component class, and Tailwind variants
+          compose utilities, not those. */}
+      <ListboxButton
+        aria-label={label}
+        title={title ?? label}
+        className={({ open }) =>
+          `tbtn justify-between gap-1.5 ${open ? "tbtn-on" : ""} ${className}`
+        }
+      >
+        {({ open }) => (
+          <>
+            <span className="min-w-0 truncate">{selected?.label ?? value}</span>
+            <ChevronDown
+              size={13}
+              aria-hidden
+              className="shrink-0 t-micro transition-transform"
+              style={{ transform: open ? "rotate(180deg)" : "none" }}
+            />
+          </>
+        )}
+      </ListboxButton>
+
+      <ListboxOptions
+        aria-label={label}
+        /* `padding` is the gap the panel keeps from the window edge; below it
+           Floating UI flips the panel to the button's other side rather than
+           letting it hang off the page. */
+        anchor={{ to: "bottom start", gap: 4, padding: 8 }}
+        className="palette-in z-50 max-h-64 overflow-y-auto rounded-control border bg-canvas py-1 border-line-strong shadow-md focus:outline-none"
+        style={menuWidth ? { width: menuWidth } : { minWidth: 160 }}
+      >
+        {options.map((option) => (
+          <ListboxOption
+            key={option.value}
+            value={option.value}
+            className={({ focus }) =>
+              `mono flex cursor-pointer items-start gap-2 px-2 py-1 ${focus ? "bg-raised" : ""}`
+            }
+          >
+            {({ selected: on }) => (
+              <>
+                <Check
+                  size={12}
+                  aria-hidden
+                  className="mt-0.5 shrink-0"
+                  style={{ opacity: on ? 1 : 0, color: "var(--accent)" }}
+                />
+                <span
+                  className="min-w-0"
+                  style={on ? { color: "var(--accent)" } : undefined}
+                >
+                  <span className="block truncate">{option.label}</span>
+                  {option.note ? (
+                    <span className="block truncate text-muted">
+                      {option.note}
+                    </span>
+                  ) : null}
+                </span>
+              </>
+            )}
+          </ListboxOption>
+        ))}
+      </ListboxOptions>
+    </Listbox>
+  );
+}

package/src/components/ShapeRows.tsx

@@ -0,0 +1,118 @@
+// A shape, small enough to sit inside something else.
+//
+// Three columns and no toolbar: this is what a reader wants when the shape is
+// an aside - the fields of a shared type opened from a schema row, the body an
+// endpoint accepts - rather than the subject of the page. When it IS the
+// subject, the sortable, filterable table on the block page is the right
+// instrument and this one would be a worse version of it.
+
+import { Fragment, useState } from "react";
+import { ChevronDown, ChevronRight } from "lucide-react";
+import type { Field, RpcEnum } from "../catalog";
+import { parseType } from "../lib/shape";
+
+/**
+ * The enum a field's type names, among the ones the interface declares. By
+ * bare name: a proto field says `OrderStatus`, and the list holds it as
+ * `OrderStatus` too.
+ */
+function enumFor(enums: RpcEnum[] | undefined, field: Field): RpcEnum | null {
+  if (!enums?.length) return null;
+  const { base } = parseType(field.type);
+  return enums.find((e) => e.name === base) ?? null;
+}
+
+/** The values of a proto enum, with the numbers a binary message carries. */
+function EnumRows({ set }: { set: RpcEnum }) {
+  return (
+    <table className="ml-4 mt-1 mb-1">
+      <tbody>
+        {set.values.map((value) => (
+          <tr key={value.name} className="align-top">
+            <td className="mono py-0.5 pr-3 whitespace-nowrap">{value.name}</td>
+            <td className="mono tnum py-0.5 pr-3 text-right text-muted">
+              {value.number}
+            </td>
+            <td className="py-0.5 text-muted">{value.doc}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+export function ShapeRows({
+  fields,
+  enums,
+}: {
+  fields: Field[];
+  /** The interface's enums, so a field typed by one can open its values. */
+  enums?: RpcEnum[];
+}) {
+  const [open, setOpen] = useState<Set<string>>(new Set());
+  const toggle = (name: string) =>
+    setOpen((prev) => {
+      const next = new Set(prev);
+      if (next.has(name)) next.delete(name);
+      else next.add(name);
+      return next;
+    });
+
+  return (
+    <table className="w-full">
+      <tbody>
+        {fields.map((field) => {
+          const set = enumFor(enums, field);
+          const shown = set !== null && open.has(field.name);
+          return (
+          <Fragment key={field.name}>
+          <tr className="align-top">
+            {/* Struck through rather than chipped: an aside has no room for a
+                badge, and the doc beside it says why. */}
+            <td
+              className={`mono py-0.5 pr-3 whitespace-nowrap${field.deprecated ? " line-through" : ""}`}
+              title={field.deprecated ? "deprecated" : undefined}
+            >
+              {field.name}
+            </td>
+            {/* An arrow marks a type that is a shared definition rather than a
+                primitive, so a reader can tell which names are worth following
+                without the row becoming a link it is not. */}
+            <td className="mono py-0.5 pr-3 whitespace-nowrap text-muted">
+              {set ? (
+                <button
+                  type="button"
+                  onClick={() => toggle(field.name)}
+                  aria-expanded={shown}
+                  className="inline-flex items-center gap-1 rounded-control hover:text-ink"
+                  title={`${set.name}: ${set.values.length} values — click to ${shown ? "hide" : "show"} them`}
+                >
+                  {shown ? (
+                    <ChevronDown size={11} aria-hidden />
+                  ) : (
+                    <ChevronRight size={11} aria-hidden />
+                  )}
+                  {field.type}
+                </button>
+              ) : field.ref ? (
+                `${field.type} →`
+              ) : (
+                field.type
+              )}
+            </td>
+            <td className="py-0.5 text-muted">{field.doc}</td>
+          </tr>
+          {shown && set ? (
+            <tr>
+              <td colSpan={3} className="pb-1">
+                <EnumRows set={set} />
+              </td>
+            </tr>
+          ) : null}
+          </Fragment>
+          );
+        })}
+      </tbody>
+    </table>
+  );
+}