@shortlink-org/portolan 0.1.0

package/src/pages/Language.tsx

@@ -0,0 +1,257 @@
+// The estate's vocabulary, every glossary in one place.
+//
+// Cards rather than a table, and that is not a style choice: a term is two
+// sentences, and two sentences in a cell are a cell nobody reads. The decisions
+// index is a table because its rows differ by status, date and scope - things
+// you scan down a column. Entries differ only by what they say.
+//
+// The homonyms come first when there are any. A vocabulary is something each
+// context already keeps for itself; the same word meaning two things in two
+// contexts is the one fact no single glossary can state, and it is what a
+// reader crossing a boundary gets wrong.
+
+import { useDocumentTitle } from "../app/title";
+import { useMemo, useState } from "react";
+import { Link, useSearchParams } from "react-router";
+import { CATALOG_PATH, catalog, index } from "../data";
+import { allTerms } from "../catalog";
+import { Blank, Empty, SectionTitle } from "../components/PageHeader";
+import { ContextPill } from "../components/primitives";
+import { contextVar } from "../lib/context-color";
+import { plural } from "../lib/format";
+import { paths } from "../routes";
+import { TermCard } from "../language/TermCard";
+import { homonyms, matchTerms, vocabularies } from "../language/cards";
+import { bindTerms } from "../lib/terms";
+
+export function Language() {
+  useDocumentTitle("Language");
+  // `?context=` is how the sidebar arrives here: the reader clicked one
+  // vocabulary, so the page opens showing it. It seeds the chips rather than
+  // replacing them - once here, the filter is theirs to widen.
+  const [params] = useSearchParams();
+  const [active, setActive] = useState<Set<string>>(
+    () =>
+      new Set(
+        params
+          .getAll("context")
+          .filter((id) => catalog.contexts.some((c) => c.id === id)),
+      ),
+  );
+  const [query, setQuery] = useState("");
+
+  // One word, asked for by ⌘K or by a link. It overrides both filters rather
+  // than combining with them: a reader who picked a word is owed that word,
+  // not "no term matches" because a chip they set a minute ago excluded it.
+  const focused = index.termById.get(params.get("term") ?? "");
+
+  const all = useMemo(() => vocabularies(catalog), []);
+  const shared = useMemo(() => homonyms(catalog), []);
+  const bound = useMemo(() => bindTerms(catalog), []);
+  const total = allTerms(catalog).length;
+
+  const shown = useMemo(
+    () =>
+      all
+        .filter((v) => active.size === 0 || active.has(v.contextId))
+        .map((v) => ({ ...v, terms: matchTerms(v.terms, query) }))
+        .filter((v) => v.terms.length > 0),
+    [all, active, query],
+  );
+  const showing = shown.reduce((n, v) => n + v.terms.length, 0);
+
+  const toggle = (id: string) =>
+    setActive((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+
+  if (total === 0) {
+    return (
+      <div className="h-full overflow-y-auto p-gutter">
+        <h1 className="text-lg font-semibold">Language</h1>
+        <div className="mt-section">
+          <Blank where={CATALOG_PATH}>
+            No glossary yet — one file per bounded context, beside its README,
+            saying what each word means inside the boundary and what it does
+            not. They are read from every <span className="text-ink">GLOSSARY.md</span>{" "}
+            the manifest points at and land in{" "}
+            <span className="text-ink">terms[]</span>.
+          </Blank>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="h-full overflow-y-auto p-gutter">
+      <div className="flex flex-wrap items-center gap-3">
+        <h1 className="text-lg font-semibold">Language</h1>
+        <span className="mono text-muted">
+          {showing === total
+            ? `${total} ${plural(total, "term")}`
+            : `${showing} of ${total}`}
+        </span>
+
+        {/* Both filters stand down while one word is asked for: they would be
+            controls that change nothing, and the way back is the link beside
+            the card. */}
+        {focused ? null : (
+          <input
+            type="search"
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            placeholder="a word, or something it says"
+            aria-label="Filter terms"
+            spellCheck={false}
+            className="mono w-56 rounded-control border bg-transparent px-2 py-1 outline-none border-line placeholder:text-faint focus:border-accent"
+          />
+        )}
+
+        {!focused && all.length > 1 ? (
+          <div className="seg ml-auto" role="group" aria-label="Filter by context">
+            {all.map((v) => {
+              const on = active.has(v.contextId);
+              return (
+                <button
+                  key={v.contextId}
+                  type="button"
+                  onClick={() => toggle(v.contextId)}
+                  aria-pressed={on}
+                  className="flex items-center gap-1.5"
+                  style={{
+                    color: on ? contextVar(v.contextId) : "var(--fg-muted)",
+                    background: on
+                      ? `color-mix(in srgb, ${contextVar(v.contextId)} 12%, transparent)`
+                      : undefined,
+                  }}
+                >
+                  <span
+                    aria-hidden
+                    className="size-1.5 rounded-[1px]"
+                    style={{ background: contextVar(v.contextId) }}
+                  />
+                  {v.contextId}
+                  <span className="tnum">{v.terms.length}</span>
+                </button>
+              );
+            })}
+          </div>
+        ) : null}
+      </div>
+
+      {focused ? (
+        <div className="mt-section">
+          <SectionTitle
+            right={
+              <Link to={paths.language()} className="text-accent">
+                show all {total} →
+              </Link>
+            }
+          >
+            <span className="flex items-center gap-2">
+              one word
+              <ContextPill id={focused.context} />
+            </span>
+          </SectionTitle>
+          <div className="grid gap-grid grid-cols-[repeat(auto-fill,minmax(340px,1fr))]">
+            <TermCard term={focused} targets={bound.byTerm.get(focused.id)} />
+          </div>
+        </div>
+      ) : null}
+
+      {/* Only while the reader is looking at everything. Narrowed to one
+          context, "the same word, twice" is a comparison with one side of it
+          hidden, which is worse than not drawing it. */}
+      {!focused && shared.length > 0 && active.size === 0 && query === "" ? (
+        <div className="mt-section">
+          <SectionTitle
+            anchor="homonyms"
+            right={
+              <span>
+                two meanings, both correct — each belongs to its own boundary
+              </span>
+            }
+          >
+            The same word, twice
+          </SectionTitle>
+          <div className="flex flex-col gap-grid">
+            {shared.map((homonym) => (
+              <div
+                key={homonym.slug}
+                className="grid gap-grid grid-cols-[repeat(auto-fit,minmax(320px,1fr))]"
+              >
+                {homonym.terms.map((term, i) => (
+                  <TermCard
+                    key={term.id}
+                    term={term}
+                    targets={bound.byTerm.get(term.id)}
+                    index={i}
+                    showContext
+                  />
+                ))}
+              </div>
+            ))}
+          </div>
+        </div>
+      ) : null}
+
+      {focused ? null : shown.length === 0 ? (
+        <div className="mt-section">
+          <Empty>no term matches</Empty>
+        </div>
+      ) : (
+        shown.map((vocabulary) => (
+          <div key={vocabulary.contextId} className="mt-section">
+            <SectionTitle
+              anchor={`ctx-${vocabulary.contextId}`}
+              right={
+                <span className="mono">
+                  {vocabulary.terms.length}{" "}
+                  {plural(vocabulary.terms.length, "term")}
+                </span>
+              }
+            >
+              <span className="flex items-center gap-2">
+                {vocabulary.context ? (
+                  <Link to={paths.context(vocabulary.contextId)}>
+                    <ContextPill
+                      id={vocabulary.contextId}
+                      name={vocabulary.context.name}
+                    />
+                  </Link>
+                ) : (
+                  <ContextPill id={vocabulary.contextId} />
+                )}
+              </span>
+            </SectionTitle>
+            {/* What the context is, in its own words, above the words it
+                uses. A context that has not said renders nothing rather than a
+                placeholder - the same silence every other page keeps about a
+                fact the estate has not stated. */}
+            {vocabulary.context?.summary ? (
+              <p className="mb-3 max-w-prose text-muted">
+                {vocabulary.context.summary}
+              </p>
+            ) : null}
+            <div
+              className="grid gap-grid grid-cols-[repeat(auto-fill,minmax(340px,1fr))]"
+              data-nav-list
+            >
+              {vocabulary.terms.map((term, i) => (
+                <TermCard
+                  key={term.id}
+                  term={term}
+                  targets={bound.byTerm.get(term.id)}
+                  index={i}
+                />
+              ))}
+            </div>
+          </div>
+        ))
+      )}
+    </div>
+  );
+}

package/src/pages/ModulePage.tsx

@@ -0,0 +1,366 @@
+import { useState } from "react";
+import { TabGroup, TabList, TabPanel, TabPanels } from "@headlessui/react";
+import { Link, useParams, useSearchParams } from "react-router";
+import { catalog, index } from "../data";
+import { Empty, PageHeader, SectionTitle } from "../components/PageHeader";
+import { Ident } from "../components/Ident";
+import { TabButton, TabCount, TabRow } from "../components/TabRow";
+import { KindIcon } from "../components/kind";
+import { MessageList, MethodRows } from "../components/MethodRows";
+import { RowActions } from "../components/RowActions";
+import { MODULE_ANCHOR, packageAnchor, paths, servicePath } from "../routes";
+import { plural } from "../lib/format";
+import {
+  callsThrough,
+  consumersOf,
+  countsOf,
+  dependenciesOf,
+  dependentsOf,
+  interfacesOf,
+  packagesOf,
+  registryUrl,
+} from "../lib/registry";
+import { NotFound } from "./NotFound";
+
+const TABS = ["overview", "interfaces", "types", "deps"] as const;
+type Tab = (typeof TABS)[number];
+
+function isTab(value: string | null): value is Tab {
+  return value !== null && (TABS as readonly string[]).includes(value);
+}
+
+/**
+ * One schema module.
+ *
+ * The page is assembled from the catalog rather than read off the module: a
+ * module carries identity and inventory, and its interfaces are found through
+ * `RpcService.module`. That keeps the shapes in one place — the interface that
+ * declares them — instead of two that can disagree.
+ */
+export function ModulePage() {
+  const { module: slug } = useParams();
+  const [params, setParams] = useSearchParams();
+  const [openShapes, setOpenShapes] = useState<ReadonlySet<string>>(new Set());
+
+  const toggleShape = (id: string) =>
+    setOpenShapes((open) => {
+      const next = new Set(open);
+      if (!next.delete(id)) next.add(id);
+
+      return next;
+    });
+
+  const module = slug ? index.moduleBySlug.get(slug) : undefined;
+  const raw = params.get("tab");
+  const tab: Tab = isTab(raw) ? raw : "overview";
+
+  if (!module) return <NotFound kind="Module" id={slug} />;
+
+  const counts = countsOf(index, module);
+  const packages = packagesOf(index, module);
+  const declared = interfacesOf(index, module);
+  const consumers = consumersOf(index, module);
+  const deps = dependenciesOf(index, module);
+  const dependents = dependentsOf(catalog, module);
+  const calls = callsThrough(catalog, module);
+  const owner = module.owner ? index.serviceById.get(module.owner) : undefined;
+  const url = registryUrl(module);
+
+  const tabCounts: Record<Tab, number | null> = {
+    overview: null,
+    interfaces: counts.interfaces,
+    types: counts.messages,
+    deps: deps.length + dependents.length,
+  };
+
+  return (
+    <TabGroup
+      manual
+      as="div"
+      className="h-full overflow-y-auto"
+      selectedIndex={TABS.indexOf(tab)}
+      onChange={(at) => {
+        const next = TABS[at] ?? "overview";
+        setParams(next === "overview" ? {} : { tab: next }, { replace: true });
+      }}
+    >
+      <PageHeader
+        kind="buf module"
+        name={module.name}
+        id={module.id}
+        pin={{ kind: "module", id: module.id }}
+        right={
+          url ? (
+            <a
+              href={url}
+              target="_blank"
+              rel="noreferrer"
+              className="mono text-muted hover:text-ink"
+            >
+              {module.registry} ↗
+            </a>
+          ) : undefined
+        }
+      >
+        <div className="mono mt-2 flex flex-wrap items-center gap-x-4 gap-y-1 text-muted">
+          <span>
+            {counts.packages} {plural(counts.packages, "package")}
+          </span>
+          <span>
+            {counts.methods} {plural(counts.methods, "method")}
+          </span>
+          {module.commit ? (
+            <Ident value={module.commit.slice(0, 12)} />
+          ) : (
+            /* Unpinned means two builds a day apart can describe two different
+               modules under one name. Worth saying on the page, not only in a
+               diagnostic nobody reads twice. */
+            <span title="tracked by label rather than pinned to a commit">
+              not pinned
+            </span>
+          )}
+        </div>
+
+        {/* The same underline the service page uses, and the same scrolling
+            strip: these tabs switch the page under them rather than filtering
+            a list beside it, and they run out of row at the same width. */}
+        <div className="mt-4">
+          <TabRow active={tab}>
+            <TabList className="flex w-max gap-0">
+              {TABS.map((name) => (
+                <TabButton key={name}>
+                  {name}
+                  {tabCounts[name] !== null ? (
+                    <TabCount>{tabCounts[name]}</TabCount>
+                  ) : null}
+                </TabButton>
+              ))}
+            </TabList>
+          </TabRow>
+        </div>
+      </PageHeader>
+
+      <TabPanels className="p-gutter">
+        <TabPanel>
+          <>
+            <section id={MODULE_ANCHOR.packages} className="max-w-table">
+              <SectionTitle anchor={MODULE_ANCHOR.packages}>
+                Packages
+              </SectionTitle>
+              {packages.length === 0 ? (
+                <Empty>this module declares no packages</Empty>
+              ) : (
+                <div className="rows">
+                  {packages.map((pkg) => (
+                    <Link
+                      key={pkg.name}
+                      to={`?tab=interfaces#${packageAnchor(pkg.name)}`}
+                      className="row mono hover:text-ink"
+                    >
+                      <span className="flex-1 truncate">{pkg.name}</span>
+                      <span className="tnum text-muted">
+                        {pkg.interfaces.length}{" "}
+                        {plural(pkg.interfaces.length, "interface")}
+                      </span>
+                    </Link>
+                  ))}
+                </div>
+              )}
+            </section>
+
+            <section id={MODULE_ANCHOR.used} className="mt-section max-w-table">
+              <SectionTitle anchor={MODULE_ANCHOR.used}>
+                Who uses it
+              </SectionTitle>
+              <div className="rows">
+                <div className="row">
+                  <span className="flex-1">published by</span>
+                  {owner ? (
+                    <Link
+                      to={servicePath(owner.id) ?? "#"}
+                      className="mono hover:text-ink"
+                    >
+                      {owner.id}
+                    </Link>
+                  ) : (
+                    /* A module published by another team is the ordinary case,
+                       and the reason `owner` is optional at all. */
+                    <span className="text-muted">nobody in this catalog</span>
+                  )}
+                </div>
+              </div>
+
+              <div className="mt-3">
+                <SectionTitle>Read by</SectionTitle>
+                {consumers.length === 0 ? (
+                  <Empty>
+                    nothing in this catalog reads this module but the service
+                    that publishes it
+                  </Empty>
+                ) : (
+                  <div className="rows">
+                    {consumers.map((service) => (
+                      <Link
+                        key={service.id}
+                        to={servicePath(service.id) ?? "#"}
+                        className="row mono hover:text-ink"
+                      >
+                        <span className="flex-1 truncate">{service.id}</span>
+                        <span className="tnum text-muted">
+                          {
+                            calls.filter((c) => c.service.id === service.id)
+                              .length
+                          }{" "}
+                          calls
+                        </span>
+                      </Link>
+                    ))}
+                  </div>
+                )}
+              </div>
+            </section>
+
+            <section className="mt-section max-w-table">
+              <SectionTitle>Files</SectionTitle>
+              {module.files.length === 0 ? (
+                <Empty>no files were recorded for this module</Empty>
+              ) : (
+                <ul className="rows">
+                  {module.files.map((file) => (
+                    <li key={file} className="row mono text-muted">
+                      {file}
+                    </li>
+                  ))}
+                </ul>
+              )}
+            </section>
+          </>
+        </TabPanel>
+
+        <TabPanel>
+          <div id={MODULE_ANCHOR.interfaces} className="flex flex-col gap-6">
+            {declared.length === 0 ? (
+              <Empty>
+                no interface in this catalog says it was declared in this module
+              </Empty>
+            ) : null}
+            {packages.map((pkg) =>
+              pkg.interfaces.length === 0 ? null : (
+                <section key={pkg.name} id={packageAnchor(pkg.name)}>
+                  <SectionTitle anchor={packageAnchor(pkg.name)}>
+                    {pkg.name}
+                  </SectionTitle>
+                  <div className="flex flex-col gap-4">
+                    {pkg.interfaces.map(({ provided, service }) => (
+                      <div
+                        key={provided.id}
+                        className="rounded-card border border-line"
+                      >
+                        <div className="mono flex flex-wrap items-center gap-x-3 border-b px-3 py-1.5 border-line bg-surface">
+                          <KindIcon kind="endpoint" />
+                          <Ident value={provided.id} className="text-ink" />
+                          {/* Which service actually answers on it: a module is
+                              a schema, and a schema does not serve requests. */}
+                          <Link
+                            to={servicePath(service.id) ?? "#"}
+                            className="ml-auto hover:text-ink"
+                          >
+                            {service.id}
+                          </Link>
+                        </div>
+                        <MethodRows
+                          provided={provided}
+                          open={openShapes}
+                          onToggle={toggleShape}
+                        />
+                      </div>
+                    ))}
+                  </div>
+                </section>
+              ),
+            )}
+          </div>
+        </TabPanel>
+
+        <TabPanel>
+          <div id={MODULE_ANCHOR.types} className="flex flex-col gap-4">
+            {counts.messages === 0 ? (
+              <Empty>
+                no shapes were read from this module — its interfaces list their
+                methods but not the messages they move
+              </Empty>
+            ) : null}
+            {declared.map(({ provided }) =>
+              provided.messages?.length ? (
+                <div
+                  key={provided.id}
+                  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>
+                  <MessageList
+                    provided={provided}
+                    open={openShapes}
+                    onToggle={toggleShape}
+                  />
+                </div>
+              ) : null,
+            )}
+          </div>
+        </TabPanel>
+
+        <TabPanel>
+          <div id={MODULE_ANCHOR.deps} className="max-w-table">
+            <SectionTitle>Depends on</SectionTitle>
+            {deps.length === 0 ? (
+              <Empty>this module depends on nothing</Empty>
+            ) : (
+              <div className="rows">
+                {deps.map((dep) =>
+                  dep.module ? (
+                    <Link
+                      key={dep.id}
+                      to={paths.module(dep.module.slug)}
+                      className="row mono hover:text-ink"
+                    >
+                      <span className="flex-1 truncate">{dep.module.name}</span>
+                      <RowActions copy={dep.id} />
+                    </Link>
+                  ) : (
+                    /* A module may depend on one the estate never vendored.
+                       That is normal, not broken: naming it and saying the
+                       catalog does not hold it beats a link into nothing. */
+                    <div key={dep.id} className="row mono text-muted">
+                      <span className="flex-1 truncate">{dep.id}</span>
+                      <span>not in this catalog</span>
+                    </div>
+                  ),
+                )}
+              </div>
+            )}
+
+            <div className="mt-section">
+              <SectionTitle>Depended on by</SectionTitle>
+              {dependents.length === 0 ? (
+                <Empty>no module in this catalog depends on this one</Empty>
+              ) : (
+                <div className="rows">
+                  {dependents.map((other) => (
+                    <Link
+                      key={other.id}
+                      to={paths.module(other.slug)}
+                      className="row mono hover:text-ink"
+                    >
+                      {other.name}
+                    </Link>
+                  ))}
+                </div>
+              )}
+            </div>
+          </div>
+        </TabPanel>
+      </TabPanels>
+    </TabGroup>
+  );
+}

package/src/pages/NotFound.tsx

@@ -0,0 +1,54 @@
+import { Link } from "react-router";
+import { useDocumentTitle } from "../app/title";
+
+/**
+ * Both shapes of "not here" end the same way: the one control that finds a
+ * thing by its current name. A reader who followed a stale link has a name in
+ * mind, and the palette is where that name still works.
+ */
+function SearchHint() {
+  return (
+    <p className="mono mt-3 text-muted">
+      <kbd>⌘K</kbd> searches the whole catalog
+    </p>
+  );
+}
+
+export function NotFound({ kind, id }: { kind: string; id?: string }) {
+  useDocumentTitle(`${kind} not found`);
+  return (
+    <div className="glow p-gutter">
+      <h1 className="text-lg font-semibold">{kind} not found</h1>
+      <p className="mt-3 text-muted">
+        nothing in the catalog answers to “{id ?? ""}” — it may have been
+        renamed since this chart was drawn
+      </p>
+      <SearchHint />
+      <Link
+        to="/"
+        className="mono mt-6 inline-block rounded-control text-accent hover:underline"
+      >
+        ← overview
+      </Link>
+    </div>
+  );
+}
+
+export function NotFoundPage() {
+  useDocumentTitle("Not found");
+  return (
+    <div className="glow p-gutter">
+      <h1 className="text-lg font-semibold">Not found</h1>
+      <p className="mt-3 text-muted">
+        off the edge of the chart — no route runs through here
+      </p>
+      <SearchHint />
+      <Link
+        to="/"
+        className="mono mt-6 inline-block rounded-control text-accent hover:underline"
+      >
+        ← overview
+      </Link>
+    </div>
+  );
+}