@shortlink-org/portolan 0.1.0

package/src/components/FieldTree.tsx

@@ -0,0 +1,305 @@
+// The fields of a shape, and the shapes inside those fields, as far down as
+// the catalog can see.
+//
+// A schema table shows one level: the event's own fields. Under a field
+// whose type is a value object or an entity there is another shape, and under
+// its `unit_price` another. This draws that descent as a tree, each level one
+// step in from the last, with a guide line so the eye can find its way back
+// up, and a header per shape saying what it is and where its page is.
+//
+// State is a set of dotted paths - `items`, `items.unit_price` - held by the
+// page, not here. The page owns "expand all", and a tree that kept its own
+// state would forget it every time the table re-sorted a row out and back.
+
+import { Link } from "react-router";
+import { ChevronDown, ChevronRight } from "lucide-react";
+import type { EnumValue, Field } from "../catalog";
+import { catalog } from "../data";
+import { KIND_LABEL } from "../lib/kinds";
+import { plural } from "../lib/format";
+import { parseType, resolveShape, scopeOf, MAX_DEPTH } from "../lib/shape";
+import type { Scope, Shape } from "../lib/shape";
+import { blockPath, enumPath } from "../routes";
+import { Ident } from "./Ident";
+import { KindIcon } from "./kind";
+
+/** The words the type chip uses for what `parseType` found. */
+const CARDINALITY: Record<"many" | "map", string> = {
+  many: "list of",
+  map: "map of",
+};
+
+/**
+ * The type of a field, as a reader wants it: the raw spelling to copy, a
+ * word for the wrapper it is in, and a way to the page of the shape it
+ * names. Shared by the table cell and the tree row so both say it the same.
+ */
+export function TypeCell({
+  field,
+  shape,
+  muted = true,
+}: {
+  field: Field;
+  shape: Shape | null;
+  muted?: boolean;
+}) {
+  const parts = parseType(field.type);
+  const page = pageOf(shape);
+  const copy = field.ref ?? field.type;
+
+  return (
+    <span className="inline-flex max-w-full items-center gap-1.5">
+      <Ident
+        value={copy}
+        className={muted ? "text-muted" : ""}
+        title={
+          field.ref
+            ? `shared type ${field.ref} — click to copy`
+            : `${field.type} — click to copy`
+        }
+      >
+        {field.type}
+      </Ident>
+      {parts.cardinality !== "one" ? (
+        <span className="type-mark" title={`${field.type}: ${CARDINALITY[parts.cardinality]} ${parts.base}`}>
+          {CARDINALITY[parts.cardinality]}
+        </span>
+      ) : null}
+      {parts.optional ? (
+        <span className="type-mark" title="may be absent">
+          optional
+        </span>
+      ) : null}
+      {page && shape ? (
+        <Link
+          to={page}
+          className="rounded-control text-muted hover:text-accent"
+          title={`open ${KIND_LABEL[shape.kind as "vo" | "entity" | "enum"]} ${shape.name}`}
+          aria-label={`open ${KIND_LABEL[shape.kind as "vo" | "entity" | "enum"]} ${shape.name}`}
+        >
+          ↗
+        </Link>
+      ) : null}
+    </span>
+  );
+}
+
+/** The page a shape has, when it has one: a def has none of its own. */
+function pageOf(shape: Shape | null): string | null {
+  if (!shape) return null;
+  if (shape.kind === "enum") return enumPath(shape.id);
+  if (shape.kind === "def") return null;
+  return blockPath(shape.id);
+}
+
+/** What is under a field, once opened: the shape's header and its own rows. */
+export function ShapeBody({
+  shape,
+  scope,
+  path,
+  open,
+  onToggle,
+  seen,
+  depth,
+  root = false,
+}: {
+  shape: Shape;
+  scope: Scope;
+  path: string;
+  open: ReadonlySet<string>;
+  onToggle: (path: string) => void;
+  seen: ReadonlySet<string>;
+  depth: number;
+  /**
+   * The body sits directly in a table cell. A cell grows to fit its content,
+   * and a doc line two hundred characters long would widen every column
+   * above it; the root takes no width of its own and fills what the row has.
+   */
+  root?: boolean;
+}) {
+  const page = pageOf(shape);
+  const kindLabel = shape.kind === "def" ? "shared type" : KIND_LABEL[shape.kind];
+  const count =
+    shape.kind === "enum"
+      ? `${shape.values.length} ${plural(shape.values.length, "value")}`
+      : `${shape.fields.length} ${plural(shape.fields.length, "field")}`;
+  const where =
+    shape.kind === "def"
+      ? "the same shape wherever it is named"
+      : (shape.aggregate?.id ?? "");
+  const inner = scopeOf(shape, scope);
+
+  return (
+    <div className={root ? "shape shape-root" : "shape"}>
+      <div className="shape-head">
+        {shape.kind !== "def" ? (
+          <KindIcon kind={shape.kind} size={12} className="shrink-0 text-muted" />
+        ) : null}
+        {page ? (
+          <Link
+            to={page}
+            className={`mono rounded-control text-accent hover:underline${shape.deprecated ? " line-through" : ""}`}
+            title={shape.id}
+          >
+            {shape.name}
+          </Link>
+        ) : (
+          <Ident value={shape.id} className="text-ink">
+            {shape.name}
+          </Ident>
+        )}
+        <span className="meta">
+          {kindLabel}
+          {where ? <> · {where}</> : null} · {count}
+        </span>
+      </div>
+      {shape.doc ? (
+        <div className="meta shape-doc" title={shape.doc}>
+          {shape.doc}
+        </div>
+      ) : null}
+      {shape.kind === "enum" ? (
+        <EnumValues values={shape.values} />
+      ) : shape.fields.length === 0 ? (
+        <div className="meta pl-4">the catalog knows this shape by name only</div>
+      ) : (
+        <FieldTree
+          fields={shape.fields}
+          scope={inner}
+          prefix={path}
+          open={open}
+          onToggle={onToggle}
+          seen={seen}
+          depth={depth}
+        />
+      )}
+    </div>
+  );
+}
+
+/**
+ * The values of an enum, one per row, in the source's order. A value has no
+ * type and nothing under it, so the row is the name and the doc; a
+ * deprecated one is struck through, and the tooltip says so.
+ */
+export function EnumValues({ values }: { values: EnumValue[] }) {
+  if (values.length === 0) {
+    return <div className="meta pl-4">the catalog knows this set by name only</div>;
+  }
+  return (
+    <div className="field-tree" role="list">
+      {values.map((value) => (
+        <div key={value.name} role="listitem" className="field-row">
+          <span className="field-toggle" aria-hidden />
+          <span
+            className={`mono whitespace-nowrap${value.deprecated ? " line-through text-muted" : ""}`}
+            title={value.deprecated ? "deprecated" : undefined}
+          >
+            {value.name}
+          </span>
+          {value.doc ? (
+            <span className="meta min-w-0 truncate" title={value.doc}>
+              {value.doc}
+            </span>
+          ) : null}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Rows for a list of fields, each openable when its type is a shape the
+ * catalog has. `seen` holds the shapes already on the way down, so a shape
+ * that names itself, however indirectly, is shown once and not opened
+ * again; `depth` cuts the honest case of a shape that simply goes on.
+ */
+export function FieldTree({
+  fields,
+  scope,
+  prefix = "",
+  open,
+  onToggle,
+  seen = new Set(),
+  depth = 0,
+}: {
+  fields: Field[];
+  scope: Scope;
+  prefix?: string;
+  open: ReadonlySet<string>;
+  onToggle: (path: string) => void;
+  seen?: ReadonlySet<string>;
+  depth?: number;
+}) {
+  return (
+    <div className="field-tree" role="list">
+      {fields.map((field) => {
+        const path = prefix ? `${prefix}.${field.name}` : field.name;
+        const shape = resolveShape(catalog, field, scope);
+        const openable =
+          shape !== null && !seen.has(shape.id) && depth < MAX_DEPTH;
+        const shown = openable && open.has(path);
+        const nameClass = `mono${field.deprecated ? " line-through" : ""}`;
+
+        return (
+          <div key={field.name} role="listitem">
+            <div className="field-row" data-open={shown ? "true" : undefined}>
+              {openable ? (
+                <button
+                  type="button"
+                  onClick={() => onToggle(path)}
+                  aria-expanded={shown}
+                  aria-label={`${shown ? "collapse" : "expand"} ${field.name}`}
+                  className="field-toggle"
+                >
+                  {shown ? (
+                    <ChevronDown size={11} aria-hidden />
+                  ) : (
+                    <ChevronRight size={11} aria-hidden />
+                  )}
+                </button>
+              ) : (
+                <span className="field-toggle" aria-hidden />
+              )}
+              <span
+                className={nameClass}
+                title={field.deprecated ? "deprecated" : undefined}
+              >
+                {field.name}
+              </span>
+              <TypeCell field={field} shape={shape} />
+              {shape && !openable ? (
+                <span
+                  className="type-mark"
+                  title={
+                    seen.has(shape.id)
+                      ? `${shape.name} is already open above this row`
+                      : "as deep as the tree goes"
+                  }
+                >
+                  ↑ {shape.name}
+                </span>
+              ) : null}
+              {field.doc ? (
+                <span className="meta min-w-0 truncate" title={field.doc}>
+                  {field.doc}
+                </span>
+              ) : null}
+            </div>
+            {shown && shape ? (
+              <ShapeBody
+                shape={shape}
+                scope={scope}
+                path={path}
+                open={open}
+                onToggle={onToggle}
+                seen={new Set([...seen, shape.id])}
+                depth={depth + 1}
+              />
+            ) : null}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/components/FlowTrigger.tsx

@@ -0,0 +1,34 @@
+import type { FlowTrigger as Trigger } from "../catalog";
+
+const KIND: Record<Trigger["kind"], string> = {
+  http: "HTTP endpoint",
+  callback: "callback",
+  event: "event",
+  message: "message",
+  job: "job",
+  startup: "startup",
+  scheduled: "scheduled",
+  manual: "manual",
+  unproven: "root unproven",
+};
+
+const CONFIDENCE: Record<Trigger["confidence"], string> = {
+  high: "status-verified",
+  medium: "status-declared",
+  low: "status-unresolved",
+};
+
+export function FlowTrigger({ trigger }: { trigger: Trigger }) {
+  const label = KIND[trigger.kind];
+  const detail = trigger.label && trigger.label !== label ? ` · ${trigger.label}` : "";
+  return (
+    <span
+      className={`chip ${CONFIDENCE[trigger.confidence]}`}
+      title={`${label}${detail} · ${trigger.confidence}-confidence source evidence`}
+    >
+      {label}
+      <span aria-hidden className="opacity-60"> · </span>
+      {trigger.confidence}
+    </span>
+  );
+}

package/src/components/Ident.tsx

@@ -0,0 +1,89 @@
+// Every identifier in the app, in one component.
+//
+// An id in a catalog browser exists to be pasted somewhere else - into a grep,
+// a proto file, a ticket. Selecting 40 characters of monospace with a mouse is
+// the worst way to do that, so every id, path and type name is a button that
+// copies itself, and says so for a second afterwards.
+//
+// Written once and used everywhere on purpose: an id that copies on one page
+// and merely sits there on the next teaches the reader not to try.
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { CSSProperties, ReactNode } from "react";
+import { toClipboard } from "../lib/clipboard";
+
+/** How long "copied" stays up. One second: long enough to read, short enough. */
+const SHOWN_MS = 1000;
+
+export function Ident({
+  value,
+  children,
+  className = "",
+  style,
+  title,
+  mono = true,
+  block = false,
+}: {
+  /** What lands on the clipboard. */
+  value: string;
+  /** What is shown, when that differs from what is copied. */
+  children?: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+  title?: string;
+  /** Off for the rare identifier already inside a mono container. */
+  mono?: boolean;
+  /**
+   * Takes a line of its own. The wrapper has to carry this, not the button:
+   * the tooltip is positioned against the wrapper, so the wrapper is what
+   * decides whether the id sits in the text flow or on its own row.
+   */
+  block?: boolean;
+}) {
+  const [state, setState] = useState<"idle" | "copied" | "failed">("idle");
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  const copy = useCallback(
+    (e: React.MouseEvent) => {
+      // Ids live inside rows that are themselves links often enough that this
+      // has to say "the click was for me" every time.
+      e.preventDefault();
+      e.stopPropagation();
+      void toClipboard(value).then((ok) => {
+        setState(ok ? "copied" : "failed");
+        if (timer.current) clearTimeout(timer.current);
+        timer.current = setTimeout(() => setState("idle"), SHOWN_MS);
+      });
+    },
+    [value],
+  );
+
+  return (
+    <span
+      className={`relative max-w-full align-baseline ${block ? "flex" : "inline-flex"}`}
+    >
+      <button
+        type="button"
+        onClick={copy}
+        title={title ?? `${value} — click to copy`}
+        aria-label={`Copy ${value}`}
+        className={`ident ${mono ? "mono" : ""} ${className}`}
+        style={style}
+      >
+        {children ?? value}
+      </button>
+      {state !== "idle" ? (
+        <span role="status" className="ident-tip overlay-in">
+          {state === "copied" ? "copied" : "copy failed"}
+        </span>
+      ) : null}
+    </span>
+  );
+}

package/src/components/Integrations.tsx

@@ -0,0 +1,243 @@
+import {
+  ChevronDown,
+  ChevronRight,
+  CircleAlert,
+  Cloud,
+  ExternalLink,
+  Server,
+} from "lucide-react";
+import { useState } from "react";
+import { Link } from "react-router";
+import type { IntegrationGroup } from "../lib/integrations";
+import { paths, servicePath } from "../routes";
+import { Empty, SectionTitle } from "./PageHeader";
+import { Ident } from "./Ident";
+import { RowActions } from "./RowActions";
+import { SoapCallContract } from "./WsdlReference";
+import { StatusChip } from "./primitives";
+
+function Metric({ value, label }: { value: number | string; label: string }) {
+  return (
+    <div className="rounded-card border border-line bg-surface px-3 py-2">
+      <div className="tnum text-lg font-semibold text-ink">{value}</div>
+      <div className="text-muted">{label}</div>
+    </div>
+  );
+}
+
+function kindLabel(group: IntegrationGroup): string {
+  if (group.kind === "external") return "outside the estate";
+  if (group.kind === "service") return "internal service";
+  return "contract missing";
+}
+
+function integrationTone(group: IntegrationGroup): string {
+  if (group.documented === group.operations.length) {
+    return "var(--status-verified)";
+  }
+  if (group.documented === 0) return "var(--status-unresolved)";
+  return "var(--status-declared)";
+}
+
+function IntegrationIcon({ group }: { group: IntegrationGroup }) {
+  const Icon =
+    group.kind === "external"
+      ? Cloud
+      : group.kind === "service"
+        ? Server
+        : CircleAlert;
+  return (
+    <span
+      className="flex size-8 shrink-0 items-center justify-center rounded-control border bg-canvas"
+      style={{
+        borderColor: integrationTone(group),
+        color: integrationTone(group),
+      }}
+    >
+      <Icon size={15} aria-hidden />
+    </span>
+  );
+}
+
+export function Integrations({ groups }: { groups: IntegrationGroup[] }) {
+  const [open, setOpen] = useState<ReadonlySet<string>>(new Set());
+  const operations = groups.flatMap((group) => group.operations);
+  const documented = operations.filter(
+    ({ call }) => call.status !== "unresolved",
+  ).length;
+  const soap = operations.filter(({ protocol }) => protocol === "SOAP");
+  const documentedSOAP = soap.filter(
+    ({ call }) => call.status !== "unresolved",
+  ).length;
+
+  if (groups.length === 0) {
+    return <Empty>this service has no outbound integrations</Empty>;
+  }
+
+  const toggle = (id: string) =>
+    setOpen((current) => {
+      const next = new Set(current);
+      if (!next.delete(id)) next.add(id);
+      return next;
+    });
+
+  return (
+    <div className="max-w-table">
+      <SectionTitle
+        right={<span>derived from outbound calls and their contracts</span>}
+      >
+        Integration coverage
+      </SectionTitle>
+      <div className="grid grid-cols-2 gap-2 md:grid-cols-4">
+        <Metric value={groups.length} label="systems" />
+        <Metric value={operations.length} label="outbound calls" />
+        <Metric
+          value={`${documented}/${operations.length}`}
+          label="documented"
+        />
+        <Metric
+          value={soap.length ? `${documentedSOAP}/${soap.length}` : "—"}
+          label="SOAP covered"
+        />
+      </div>
+
+      <div className="mt-section flex flex-col gap-2" data-nav-list>
+        {groups.map((group) => {
+          const shown = open.has(group.id);
+          const percent = group.operations.length
+            ? Math.round((group.documented / group.operations.length) * 100)
+            : 0;
+          const internalPath = group.service
+            ? servicePath(group.service.id)
+            : null;
+          const tone = integrationTone(group);
+          const coverageLabel =
+            group.documented === group.operations.length
+              ? "fully documented"
+              : group.documented === 0
+                ? "contract missing"
+                : `${percent}% documented`;
+
+          return (
+            <section
+              key={group.id}
+              className="overflow-hidden rounded-card border border-line bg-canvas"
+              style={{ borderLeftColor: tone, borderLeftWidth: 2 }}
+            >
+              <div className="flex flex-wrap items-center gap-x-3 gap-y-2 bg-surface px-3 py-2.5">
+                <button
+                  type="button"
+                  data-nav-item
+                  aria-expanded={shown}
+                  onClick={() => toggle(group.id)}
+                  className="flex min-w-48 flex-1 items-center gap-2 rounded-control text-left"
+                >
+                  {shown ? (
+                    <ChevronDown size={14} className="shrink-0 text-muted" />
+                  ) : (
+                    <ChevronRight size={14} className="shrink-0 text-muted" />
+                  )}
+                  <IntegrationIcon group={group} />
+                  <span className="min-w-0">
+                    <span className="block truncate font-medium text-ink">
+                      {group.name}
+                    </span>
+                    <span className="mt-0.5 flex flex-wrap items-center gap-1.5">
+                      <span
+                        className={`chip ${group.kind === "unresolved" ? "status-unresolved" : ""}`}
+                      >
+                        {kindLabel(group)}
+                      </span>
+                      {group.protocols.map((protocol) => (
+                        <span key={protocol} className="chip mono">
+                          {protocol}
+                        </span>
+                      ))}
+                    </span>
+                  </span>
+                </button>
+                <div className="mono min-w-28 text-right text-muted">
+                  <div>
+                    <span className="tnum text-ink">
+                      {group.operations.length}
+                    </span>{" "}
+                    {group.operations.length === 1 ? "call" : "calls"}
+                  </div>
+                  <div className="t-micro" style={{ color: tone }}>
+                    {coverageLabel}
+                  </div>
+                </div>
+                {group.external ? (
+                  <Link
+                    to={paths.external(group.external.slug)}
+                    className="btn-quiet shrink-0"
+                    title={`Open ${group.external.name} contract`}
+                  >
+                    view contract <ExternalLink size={12} />
+                  </Link>
+                ) : internalPath ? (
+                  <Link
+                    to={internalPath}
+                    data-peek={group.service?.id}
+                    className="btn-quiet shrink-0"
+                  >
+                    view service
+                  </Link>
+                ) : null}
+              </div>
+              <div
+                className="h-0.5 bg-line"
+                aria-label={`${percent}% documented`}
+              >
+                <div
+                  className="h-full"
+                  style={{ width: `${percent}%`, backgroundColor: tone }}
+                />
+              </div>
+
+              {shown ? (
+                <div>
+                  {group.operations.map(
+                    ({ call, provided, method, protocol }) => (
+                      <div
+                        key={call.id}
+                        className="flex flex-wrap items-start gap-x-3 gap-y-1 border-t border-line px-3 py-2 first:border-t-0"
+                      >
+                        <span className="chip mono">{protocol}</span>
+                        <Ident value={call.id} className="min-w-0 text-ink" />
+                        <StatusChip status={call.status} />
+                        <Ident value={call.source} className="ml-auto" />
+                        <RowActions copy={call.id} label={call.id} />
+                        {method?.http ? (
+                          <p className="mono w-full text-muted">
+                            {method.http.method} {method.http.path}
+                          </p>
+                        ) : null}
+                        {call.note ? (
+                          <p className="w-full border-l-2 border-line-strong pl-2 text-muted">
+                            {call.note}
+                          </p>
+                        ) : null}
+                        {provided && method?.soap ? (
+                          <SoapCallContract
+                            provided={provided}
+                            method={method}
+                          />
+                        ) : call.status === "unresolved" ? (
+                          <p className="w-full text-unresolved">
+                            no matching operation was found in the available
+                            contracts
+                          </p>
+                        ) : null}
+                      </div>
+                    ),
+                  )}
+                </div>
+              ) : null}
+            </section>
+          );
+        })}
+      </div>
+    </div>
+  );
+}