@shortlink-org/portolan 0.1.0

package/src/er/RelationCard.tsx

@@ -0,0 +1,267 @@
+// The half of a card that a table and a view have in common.
+//
+// Both are a header over a column listing, and the listing is the content: the
+// question a reader brings to an ER canvas is almost never "does this exist" —
+// it is "what does this row point at, what points at this one, and where did
+// the value come from". So the columns are drawn once, here, and the two cards
+// differ only in the header they put above them, which is exactly as much
+// difference as there is between the two things.
+
+import { Handle, Position } from "@xyflow/react";
+import type { Node } from "@xyflow/react";
+import { Key, Link2, Waypoints } from "lucide-react";
+import type { ReactNode } from "react";
+import type { Column } from "../catalog";
+import { MAX_ROWS, MORE_H, ROW_H } from "./spec";
+import type { ErNode } from "./spec";
+
+export type RelationNodeData = {
+  node: ErNode;
+  /** Column names that take part in an edge, so only those grow anchors. */
+  anchors: ReadonlySet<string>;
+  /** Search hit: lifted rather than dimmed, so the eye lands on it. */
+  matched: boolean;
+  /** Something else is lit and this is not it. */
+  dimmed: boolean;
+  /** Columns lit by a hover, on a row here or on an edge somewhere else. */
+  litColumns: ReadonlySet<string>;
+  selectedColumn: string | null;
+  onToggle: (relationId: string) => void;
+  onColumnEnter: (columnId: string | null) => void;
+  onColumnClick: (columnId: string) => void;
+};
+
+export type ErTableNode = Node<RelationNodeData, "erTable">;
+export type ErViewNode = Node<RelationNodeData, "erView">;
+export type ErFlowNode = ErTableNode | ErViewNode;
+
+export const HANDLE = {
+  opacity: 0,
+  width: 1,
+  height: 1,
+  border: "none",
+} as const;
+
+/**
+ * The box: surface, dimming, and the two anchors an edge falls back to when
+ * the column it wants is not on show. A table is a card; a view, an outbox or
+ * a projection is the outline of one, because nothing in it is the source of
+ * truth and the dash is how that is said. A search hit takes the ring, so the
+ * eye lands on it; selection takes the same ring, drawn by the canvas.
+ */
+export function CardFrame({
+  matched,
+  dimmed,
+  dashed,
+  children,
+}: {
+  matched: boolean;
+  dimmed: boolean;
+  /** Nothing in here is the source of truth: a view, a projection, an outbox. */
+  dashed: boolean;
+  children: ReactNode;
+}) {
+  return (
+    <div
+      className={`mono flex h-full w-full flex-col overflow-hidden ${
+        dashed ? "" : "flow-card"
+      }`}
+      style={{
+        background: "var(--flow-card)",
+        borderRadius: "var(--radius-node)",
+        ...(dashed ? { border: "1px dashed var(--border-strong)" } : {}),
+        ...(matched ? { boxShadow: "var(--ring)" } : {}),
+        opacity: dimmed ? 0.3 : 1,
+        fontSize: 11,
+        transition: "opacity 120ms ease-out, box-shadow var(--dur-micro) var(--ease-out)",
+      }}
+    >
+      {children}
+
+      {/* A card with no anchored column still needs somewhere for an edge to
+          land — a key into a column the collapsed card is not showing, or a
+          view that says only which table it reads. */}
+      <Handle
+        id="table"
+        type="target"
+        position={Position.Left}
+        isConnectable={false}
+        style={HANDLE}
+      />
+      <Handle
+        id="table-source"
+        type="source"
+        position={Position.Right}
+        isConnectable={false}
+        style={HANDLE}
+      />
+    </div>
+  );
+}
+
+/** The chip beside a card's name: "root", "outbox", "matview". */
+export function Badge({ children }: { children: ReactNode }) {
+  return (
+    <span
+      className="shrink-0 rounded-full px-1.5 text-muted"
+      style={{ background: "var(--surface-2)", fontSize: 9, lineHeight: "14px" }}
+    >
+      {children}
+    </span>
+  );
+}
+
+/** The column listing, and the "+n more" footer when the card is collapsed. */
+export function ColumnRows({
+  data,
+  relationId,
+}: {
+  data: RelationNodeData;
+  relationId: string;
+}) {
+  const {
+    node,
+    anchors,
+    litColumns,
+    selectedColumn,
+    onToggle,
+    onColumnEnter,
+    onColumnClick,
+  } = data;
+
+  return (
+    <>
+      <div
+        className="flex-1"
+        style={{
+          overflowY: node.scrolls ? "auto" : "visible",
+          maxHeight: MAX_ROWS * ROW_H,
+        }}
+      >
+        {node.rows.map((column) => (
+          <ColumnRow
+            key={column.name}
+            column={column}
+            id={`${relationId}.${column.name}`}
+            anchored={anchors.has(column.name)}
+            lit={
+              litColumns.has(`${relationId}.${column.name}`) ||
+              selectedColumn === `${relationId}.${column.name}`
+            }
+            onEnter={onColumnEnter}
+            onClick={onColumnClick}
+          />
+        ))}
+      </div>
+
+      {node.hidden > 0 ? (
+        <button
+          type="button"
+          onClick={() => onToggle(relationId)}
+          className="shrink-0 px-2 text-left text-muted hover:text-ink"
+          style={{
+            height: MORE_H,
+            fontSize: 9,
+            borderTop: "1px dashed var(--border)",
+          }}
+        >
+          +{node.hidden} more
+        </button>
+      ) : null}
+    </>
+  );
+}
+
+function ColumnRow({
+  column,
+  id,
+  anchored,
+  lit,
+  onEnter,
+  onClick,
+}: {
+  column: Column;
+  id: string;
+  anchored: boolean;
+  lit: boolean;
+  onEnter: (columnId: string | null) => void;
+  onClick: (columnId: string) => void;
+}) {
+  const derived = (column.from?.length ?? 0) > 0;
+  return (
+    <div
+      onMouseEnter={() => onEnter(id)}
+      onMouseLeave={() => onEnter(null)}
+      onClick={(e) => {
+        e.stopPropagation();
+        onClick(id);
+      }}
+      title={
+        column.doc ??
+        (derived
+          ? `${column.name} ${column.type} — from ${column.from?.join(", ")}`
+          : `${column.name} ${column.type}`)
+      }
+      className="relative flex items-center gap-1 px-2"
+      style={{
+        height: ROW_H,
+        background: lit ? "var(--surface-2)" : undefined,
+        cursor: "pointer",
+      }}
+    >
+      {column.pk ? (
+        <Key size={9} aria-hidden className="shrink-0 text-ink" />
+      ) : (
+        <span aria-hidden className="w-[9px] shrink-0" />
+      )}
+      <span className="truncate text-ink">{column.name}</span>
+      <span className="ml-auto shrink-0 truncate text-muted">
+        {column.type}
+        {column.nullable ? "?" : ""}
+      </span>
+      {/* Two different glyphs for two different claims: a key points at a row,
+          lineage says the value was copied from one. */}
+      {column.fk ? (
+        <Link2 size={9} aria-hidden className="shrink-0 text-muted" />
+      ) : null}
+      {derived ? (
+        <Waypoints size={9} aria-hidden className="shrink-0 text-muted" />
+      ) : null}
+
+      {/* Anchors on both sides. Which one an edge uses is decided after
+          layout, from where the two cards actually landed. */}
+      {anchored ? (
+        <>
+          <Handle
+            id={`l:${column.name}`}
+            type="source"
+            position={Position.Left}
+            isConnectable={false}
+            style={HANDLE}
+          />
+          <Handle
+            id={`r:${column.name}`}
+            type="source"
+            position={Position.Right}
+            isConnectable={false}
+            style={HANDLE}
+          />
+          <Handle
+            id={`tl:${column.name}`}
+            type="target"
+            position={Position.Left}
+            isConnectable={false}
+            style={HANDLE}
+          />
+          <Handle
+            id={`tr:${column.name}`}
+            type="target"
+            position={Position.Right}
+            isConnectable={false}
+            style={HANDLE}
+          />
+        </>
+      ) : null}
+    </div>
+  );
+}

package/src/er/StoreHeader.tsx

@@ -0,0 +1,155 @@
+// The line above an ER canvas: what this store is, who owns it, how big it is.
+//
+// Written once because it appears twice — stacked on the service's Data tab and
+// again at the top of a store's own page — and a reader who has learned to read
+// it in one place has learned it in the other.
+
+import { Link } from "react-router";
+import type { Store, StoreKind } from "../catalog";
+import { storeViews } from "../catalog";
+import { index } from "../data";
+import { Ident } from "../components/Ident";
+import { KindIcon } from "../components/kind";
+import { TechIcon } from "../components/TechIcon";
+import { STORE_KIND_GLYPH } from "../lib/tech";
+import { plural } from "../lib/format";
+import { outboundKeys, outboundLineage } from "./spec";
+import { servicePath, storePath } from "../routes";
+
+/**
+ * What a kind is called on the page. The KIND icon stays the same database
+ * glyph for all of them - a store is a store in the taxonomy, and nine glyphs
+ * in the tree would make nine kinds of it. Which brand it is lives in the chip
+ * beside the word, as the brand's own mark next to its name, so the chip can
+ * be read at a glance and the tree does not have to be.
+ */
+export const STORE_KIND_LABEL: Record<StoreKind, string> = {
+  postgres: "PostgreSQL",
+  mysql: "MySQL",
+  sqlite: "SQLite",
+  redis: "Redis",
+  mongodb: "MongoDB",
+  clickhouse: "ClickHouse",
+  s3: "S3",
+  other: "store",
+};
+
+/** The brand's mark for a store kind, or nothing for a kind that has none. */
+export function StoreKindMark({
+  kind,
+  size,
+}: {
+  kind: StoreKind;
+  size?: number;
+}) {
+  const glyph = STORE_KIND_GLYPH[kind];
+  return glyph ? <TechIcon glyph={glyph} size={size} /> : null;
+}
+
+export function StoreHeader({
+  store,
+  access,
+  /** Links the store's name to its own page. Off on the page itself. */
+  linked = true,
+}: {
+  store: Store;
+  access: "owns" | "reads";
+  linked?: boolean;
+}) {
+  const to = linked ? storePath(store.id) : null;
+  const ownerTo = servicePath(store.owner);
+  const outbound = outboundKeys(index, store);
+  const copied = outboundLineage(index, store);
+  const views = storeViews(store);
+  const keyspaces = store.keyspaces ?? [];
+
+  return (
+    <div className="flex flex-wrap items-baseline gap-x-3 gap-y-1">
+      <KindIcon kind="store" />
+      {to ? (
+        <Link to={to} className="mono rounded-control text-ink hover:underline">
+          {store.slug}
+        </Link>
+      ) : (
+        <span className="mono text-ink">{store.slug}</span>
+      )}
+      <span className="meta">{store.name}</span>
+      <span className="chip">
+        <StoreKindMark kind={store.kind} />
+        {STORE_KIND_LABEL[store.kind]}
+      </span>
+
+      {access === "reads" ? (
+        <span
+          className="chip"
+          title={`${store.owner} owns this store; this service only reads it`}
+        >
+          read-only
+          {ownerTo ? (
+            <>
+              {" · "}
+              <Link to={ownerTo} className="text-accent hover:underline">
+                {store.owner}
+              </Link>
+            </>
+          ) : (
+            ` · ${store.owner}`
+          )}
+        </span>
+      ) : null}
+
+      <span className="mono ml-auto flex items-center gap-3 text-muted">
+        {/* A store with no tables is not an empty store — it is a store whose
+            shape the extractor cannot read, which a count of zero would state
+            as a fact about the database rather than about the catalog. */}
+        <span>
+          {keyspaces.length > 0 ? (
+            <span title={keyspaces.map((key) => key.pattern).join("\n")}>
+              <span className="tnum">{keyspaces.length}</span>{" "}
+              {plural(keyspaces.length, "key pattern")}
+            </span>
+          ) : store.tables.length === 0 ? (
+            <span title="no schema was extracted for this store">
+              no schema extracted
+            </span>
+          ) : (
+            <>
+              <span className="tnum">{store.tables.length}</span>{" "}
+              {plural(store.tables.length, "table")}
+            </>
+          )}
+        </span>
+        {views.length > 0 ? (
+          <span title={views.map((v) => v.name).join("\n")}>
+            <span className="tnum">{views.length}</span>{" "}
+            {plural(views.length, "view")}
+          </span>
+        ) : null}
+        {outbound.length > 0 ? (
+          <span
+            className="text-unresolved"
+            title={outbound
+              .map((o) => `${o.from}.${o.fromColumn} → ${o.to} (${o.peer})`)
+              .join("\n")}
+          >
+            <span className="tnum">{outbound.length}</span> key
+            {outbound.length === 1 ? "" : "s"} out of this store
+          </span>
+        ) : null}
+        {/* A key out of the store is a constraint nobody enforces; a value
+            copied in from another store is a row that goes stale on its own.
+            Two different worries, so two different lines. */}
+        {copied.length > 0 ? (
+          <span
+            className="text-declared"
+            title={copied.map((o) => `${o.from}.${o.fromColumn} ← ${o.to} (${o.peer})`).join("\n")}
+          >
+            <span className="tnum">{copied.length}</span> column
+            {copied.length === 1 ? "" : "s"} copied in
+          </span>
+        ) : null}
+        {store.source ? <Ident value={store.source} /> : null}
+      </span>
+    </div>
+  );
+}

package/src/er/TableNode.tsx

@@ -0,0 +1,84 @@
+// One table, as a card.
+//
+// The rows come from RelationCard, which a view uses too. What is left here is
+// the header: the table's name, what it is FOR, and which aggregate it holds —
+// the three facts that decide how every row under it should be read.
+
+import type { NodeProps } from "@xyflow/react";
+import { Link } from "react-router";
+import { contextVar } from "../lib/context-color";
+import { aggregatePath } from "../routes";
+import { HEADER_H } from "./spec";
+import { Badge, CardFrame, ColumnRows } from "./RelationCard";
+import type { ErTableNode } from "./RelationCard";
+
+/**
+ * Roles that change how a table is READ get a dashed border: an outbox and a
+ * projection are both derived — nothing in them is the source of truth — and
+ * that is the one thing a reader has to know before believing a row.
+ */
+function isDerived(role: string | undefined): boolean {
+  return role === "outbox" || role === "projection";
+}
+
+export function TableNodeCard({ data }: NodeProps<ErTableNode>) {
+  const { node, matched, dimmed, onToggle } = data;
+  const table = node.table;
+  if (!table) return null;
+
+  const accent = node.ghost ? "var(--fg-muted)" : contextVar(node.context);
+  const aggregateTo = node.aggregate ? aggregatePath(node.aggregate) : null;
+  // The chip is a caption on the table's name, so it shows the aggregate's own
+  // slug; the full id is in the title and one click away.
+  const aggregateSlug = node.aggregate?.split(".").at(-1) ?? "";
+
+  return (
+    <CardFrame
+      matched={matched}
+      dimmed={dimmed}
+      dashed={isDerived(table.role) || node.ghost}
+    >
+      {/* Header. Tinted by the context that owns the aggregate this table
+          holds — never by the store's kind, never by the table's type. */}
+      {/* The click is not swallowed: it opens the card AND selects the table,
+          which is the one gesture a reader makes when they want to know more
+          about it. The links inside are the exceptions, and stop it. */}
+      <button
+        type="button"
+        onClick={() => onToggle(table.id)}
+        title={table.doc ?? table.name}
+        className="flex w-full shrink-0 items-center gap-1.5 px-2 text-left"
+        style={{
+          height: HEADER_H,
+          background: `color-mix(in srgb, ${accent} 9%, var(--flow-card))`,
+          borderBottom: "1px solid var(--border)",
+        }}
+      >
+        <span className="truncate text-ink">{table.name}</span>
+        {node.badge ? <Badge>{node.badge}</Badge> : null}
+        {node.aggregate ? (
+          <span
+            className="ml-auto shrink-0 truncate"
+            style={{ fontSize: 9, maxWidth: 78 }}
+            title={`persists ${node.aggregate}`}
+          >
+            {aggregateTo ? (
+              <Link
+                to={aggregateTo}
+                onClick={(e) => e.stopPropagation()}
+                className="rounded-control hover:underline"
+                style={{ color: accent }}
+              >
+                {aggregateSlug}
+              </Link>
+            ) : (
+              <span className="text-muted">{aggregateSlug}</span>
+            )}
+          </span>
+        ) : null}
+      </button>
+
+      <ColumnRows data={data} relationId={table.id} />
+    </CardFrame>
+  );
+}

package/src/er/ViewNode.tsx

@@ -0,0 +1,83 @@
+// One view, as a card.
+//
+// A view is drawn as a table that admits it is not one: same width, same rows,
+// dashed border, and a header that says `view` or `matview` before it says
+// anything else. That ordering is the whole design. A reader who mistakes a
+// view for a table believes rows that may not exist yet, or joins onto a thing
+// that has no key — so the card states what it is before it states its name,
+// and never grows the primary-key glyph a table's header earns.
+
+import type { NodeProps } from "@xyflow/react";
+import { Eye, RefreshCw } from "lucide-react";
+import { Link } from "react-router";
+import { contextVar } from "../lib/context-color";
+import { aggregatePath } from "../routes";
+import { HEADER_H } from "./spec";
+import { Badge, CardFrame, ColumnRows } from "./RelationCard";
+import type { ErViewNode } from "./RelationCard";
+
+export function ViewNodeCard({ data }: NodeProps<ErViewNode>) {
+  const { node, matched, dimmed, onToggle } = data;
+  const view = node.view;
+  if (!view) return null;
+
+  const accent = node.ghost ? "var(--fg-muted)" : contextVar(node.context);
+  const aggregateTo = node.aggregate ? aggregatePath(node.aggregate) : null;
+  const aggregateSlug = node.aggregate?.split(".").at(-1) ?? "";
+  const Glyph = view.materialized ? RefreshCw : Eye;
+
+  return (
+    <CardFrame
+      matched={matched}
+      /* Always dashed: nothing in a view is the source of truth, which is the
+         same claim the dash makes on an outbox or a projection. */
+      dashed
+      dimmed={dimmed}
+    >
+      <button
+        type="button"
+        onClick={() => onToggle(view.id)}
+        title={
+          view.definition
+            ? `${view.doc ? `${view.doc}\n\n` : ""}${view.definition}`
+            : (view.doc ?? view.name)
+        }
+        className="flex w-full shrink-0 items-center gap-1.5 px-2 text-left"
+        style={{
+          height: HEADER_H,
+          /* Lighter than a table's tint, and striped, so a canvas of twenty
+             cards sorts itself into "rows live here" and "rows are computed
+             here" before a single name has been read. */
+          background: `repeating-linear-gradient(135deg, color-mix(in srgb, ${accent} 8%, var(--flow-card)) 0 6px, var(--flow-card) 6px 12px)`,
+          borderBottom: "1px dashed var(--border)",
+        }}
+      >
+        <Glyph size={9} aria-hidden className="shrink-0 text-muted" />
+        <span className="truncate text-ink">{view.name}</span>
+        {node.badge ? <Badge>{node.badge}</Badge> : null}
+        {node.aggregate ? (
+          <span
+            className="ml-auto shrink-0 truncate"
+            style={{ fontSize: 9, maxWidth: 62 }}
+            title={`presents ${node.aggregate}`}
+          >
+            {aggregateTo ? (
+              <Link
+                to={aggregateTo}
+                onClick={(e) => e.stopPropagation()}
+                className="rounded-control hover:underline"
+                style={{ color: accent }}
+              >
+                {aggregateSlug}
+              </Link>
+            ) : (
+              <span className="text-muted">{aggregateSlug}</span>
+            )}
+          </span>
+        ) : null}
+      </button>
+
+      <ColumnRows data={data} relationId={view.id} />
+    </CardFrame>
+  );
+}