@tulipfarm/sprout 0.2.0 → 0.3.1

package/dist/components/schema-diagram.js

@@ -1,14 +1,11 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { Background, BaseEdge, EdgeLabelRenderer, getSmoothStepPath, Handle, Panel, Position, ReactFlow, ReactFlowProvider, useNodesInitialized, useReactFlow, useStore, } from "@xyflow/react";
-import { useEffect, useId, useMemo, useSyncExternalStore, } from "react";
-import { Add } from "reicon-react/icons/Add";
+import { Background, BaseEdge, EdgeLabelRenderer, getSmoothStepPath, Handle, Position, ReactFlow, ReactFlowProvider, } from "@xyflow/react";
+import { useId, useMemo } from "react";
 import { Key } from "reicon-react/icons/Key";
-import { Minus } from "reicon-react/icons/Minus";
-import { Scan } from "reicon-react/icons/Scan";
 import { cn } from "../internal/classes.js";
+import { FitOnResize, flowMaxZoom as maxZoom, flowMinZoom as minZoom, useKeyboardView, useViewportMobile, ZoomControls, } from "../internal/flow.js";
 import { Badge } from "./badge.js";
-import { Button } from "./button.js";
 export const schemaTableStateNames = [
     "new",
     "changed",
@@ -24,10 +21,7 @@ export const schemaDiagramLayoutNames = [
 const tableWidth = 264;
 const columnGap = 80;
 const rowGap = 48;
-const minZoom = 0.2;
-const maxZoom = 1.5;
 const fitOptions = { padding: 0.15, maxZoom: 1 };
-const panStep = 48;
 const tableHeight = (table) => 44 +
     (table.fields.length === 0
         ? 32
@@ -117,80 +111,13 @@ function LinkLine({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targ
 }
 const nodeTypes = { table: TableCard };
 const edgeTypes = { link: LinkLine };
-const mobileQuery = "(max-width: 767px)";
-const motionQuery = "(prefers-reduced-motion: reduce)";
-function subscribeMobile(callback) {
-    const media = window.matchMedia(mobileQuery);
-    media.addEventListener("change", callback);
-    return () => media.removeEventListener("change", callback);
-}
-function useViewportMobile() {
-    return useSyncExternalStore(subscribeMobile, () => window.matchMedia(mobileQuery).matches, () => false);
-}
-const motion = (ms) => typeof window !== "undefined" && window.matchMedia(motionQuery).matches
-    ? 0
-    : ms;
-// The canvas panel animates open, so the first fit sees a narrower pane than the final one.
-function FitOnResize({ nodes }) {
-    const { fitView } = useReactFlow();
-    const width = useStore((state) => state.width);
-    const height = useStore((state) => state.height);
-    const measured = useNodesInitialized();
-    useEffect(() => {
-        if (!measured)
-            return;
-        const frame = requestAnimationFrame(() => void fitView(fitOptions));
-        return () => cancelAnimationFrame(frame);
-    }, [fitView, width, height, measured, nodes]);
-    return null;
-}
-function ZoomControls({ position, }) {
-    const { zoomIn, zoomOut, fitView } = useReactFlow();
-    const zoom = useStore((state) => state.transform[2]);
-    return (_jsxs(Panel, { position: position, className: "sprout-schema-controls", "data-slot": "schema-diagram-controls", role: "toolbar", "aria-label": "Diagram view", "aria-orientation": "vertical", children: [_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Zoom in", title: "Zoom in", disabled: zoom >= maxZoom, onClick: () => void zoomIn({ duration: motion(160) }), children: _jsx(Add, { size: 16, "aria-hidden": "true" }) }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Zoom out", title: "Zoom out", disabled: zoom <= minZoom, onClick: () => void zoomOut({ duration: motion(160) }), children: _jsx(Minus, { size: 16, "aria-hidden": "true" }) }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Fit to view", title: "Fit to view", onClick: () => void fitView({ ...fitOptions, duration: motion(180) }), children: _jsx(Scan, { size: 16, "aria-hidden": "true" }) })] }));
-}
-function useKeyboardView() {
-    const { getViewport, setViewport, zoomIn, zoomOut, fitView } = useReactFlow();
-    return (event) => {
-        const target = event.target;
-        if (event.altKey || event.ctrlKey || event.metaKey)
-            return;
-        if (target !== event.currentTarget &&
-            !target.classList.contains("react-flow__node"))
-            return;
-        const step = panStep * (event.shiftKey ? 4 : 1);
-        const pan = {
-            ArrowLeft: [step, 0],
-            ArrowRight: [-step, 0],
-            ArrowUp: [0, step],
-            ArrowDown: [0, -step],
-        };
-        const move = pan[event.key];
-        if (move) {
-            const { x, y, zoom } = getViewport();
-            void setViewport({ x: x + move[0], y: y + move[1], zoom }, { duration: motion(120) });
-        }
-        else if (event.key === "+" || event.key === "=") {
-            void zoomIn({ duration: motion(160) });
-        }
-        else if (event.key === "-" || event.key === "_") {
-            void zoomOut({ duration: motion(160) });
-        }
-        else if (event.key === "0") {
-            void fitView({ ...fitOptions, duration: motion(180) });
-        }
-        else
-            return;
-        event.preventDefault();
-    };
-}
 const keyboardHint = "Arrow keys pan, plus and minus zoom, and 0 fits the diagram. Tab moves between tables.";
 function DiagramFlow({ nodes, edges, direction, label, hintId, }) {
-    const onKeyDown = useKeyboardView();
+    const onKeyDown = useKeyboardView(fitOptions);
     return (_jsxs(ReactFlow, { className: "sprout-schema-flow", "data-slot": "schema-diagram-viewport", "aria-label": label, "aria-describedby": hintId, tabIndex: 0, onKeyDown: onKeyDown, nodes: nodes, edges: edges, nodeTypes: nodeTypes, edgeTypes: edgeTypes, fitView: true, fitViewOptions: fitOptions, minZoom: minZoom, maxZoom: maxZoom, nodesConnectable: false, elementsSelectable: false, edgesFocusable: false, ariaLabelConfig: {
             "node.a11yDescription.default": keyboardHint,
             "node.a11yDescription.keyboardDisabled": keyboardHint,
-        }, proOptions: { hideAttribution: true }, children: [_jsx(Background, { gap: 16, size: 1 }), _jsx(FitOnResize, { nodes: nodes }), _jsx(ZoomControls, { position: direction === "vertical" ? "top-right" : "bottom-right" })] }));
+        }, proOptions: { hideAttribution: true }, children: [_jsx(Background, { gap: 16, size: 1 }), _jsx(FitOnResize, { nodes: nodes, fit: fitOptions }), _jsx(ZoomControls, { position: direction === "vertical" ? "top-right" : "bottom-right", fit: fitOptions, className: "sprout-schema-controls", slot: "schema-diagram-controls" })] }));
 }
 /**
  * A pan-and-zoom diagram of tables, their fields, and the links between them,

package/dist/components/sql-viewer.d.ts

@@ -0,0 +1,76 @@
+import { type HTMLAttributes } from "react";
+export declare const sqlViewerLayoutNames: readonly ["auto", "horizontal", "vertical"];
+export type SqlViewerLayout = (typeof sqlViewerLayoutNames)[number];
+export type SqlViewerCardinality = "one" | "many";
+export interface SqlViewerOption {
+    id: string;
+    label: string;
+    retired: boolean;
+}
+/** One field of a TulipFarm table definition (format 2) or table document (format 3). */
+export type SqlViewerField = {
+    id: string;
+    label: string;
+    required: boolean;
+} & ({
+    kind: "text";
+    maxLength: number;
+} | {
+    kind: "numeric";
+    precision: number;
+    scale: number;
+} | {
+    kind: "boolean";
+} | {
+    kind: "date";
+} | {
+    kind: "timestamp";
+    timezone?: "UTC";
+} | {
+    kind: "single-select" | "multi-select";
+    options: readonly SqlViewerOption[];
+} | {
+    kind: "relationship";
+    /** A table name (format 3) or table UUID (format 2), matching a table's `id`. */
+    targetTableId: string;
+    cardinality: SqlViewerCardinality;
+    inverseCardinality: SqlViewerCardinality;
+    reverse?: {
+        fieldId: string;
+        label: string;
+    } | null;
+    onDelete?: "restrict";
+} | {
+    kind: "file";
+    cardinality: SqlViewerCardinality;
+    access?: "independent";
+});
+export interface SqlViewerUniqueKey {
+    id: string;
+    fieldIds: readonly string[];
+}
+/** A TulipFarm table definition or table document. Extra keys are ignored. */
+export interface SqlViewerTable {
+    id: string;
+    label: string;
+    owningTeamId?: string;
+    fields: readonly SqlViewerField[];
+    uniqueKeys?: readonly SqlViewerUniqueKey[];
+}
+export interface SqlViewerProps extends Omit<HTMLAttributes<HTMLDivElement>, "role" | "children"> {
+    /** TulipFarm table definitions or table documents, in display order. */
+    tables: readonly SqlViewerTable[];
+    /** Names the diagram for assistive tech, such as “Tables in Sales”. */
+    label: string;
+    /** Team names by `owningTeamId`. Tables of a named team sit in one tinted group. */
+    groups?: Readonly<Record<string, string>> | undefined;
+    /** Tables shown before the rest collapse into one “+N tables” card. Default 4. */
+    maxVisible?: number | undefined;
+    /** `auto` stacks tables under 768px and uses columns otherwise. */
+    layout?: SqlViewerLayout | undefined;
+}
+/**
+ * A pan-and-zoom map of SQL tables, their columns and keys, and the joins
+ * between them. Hover or pin a table or a foreign key to trace its joins.
+ */
+export declare function SqlViewer({ tables, label, groups, maxVisible, layout, className, ...props }: SqlViewerProps): import("react").JSX.Element;

package/dist/components/sql-viewer.js

@@ -0,0 +1,409 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Background, getSmoothStepPath, Handle, Panel, Position, ReactFlow, ReactFlowProvider, useInternalNode, useNodesState, } from "@xyflow/react";
+import { createContext, useCallback, useContext, useEffect, useId, useMemo, useState, } from "react";
+import { Fingerprint } from "reicon-react/icons/Fingerprint";
+import { Key } from "reicon-react/icons/Key";
+import { Layers } from "reicon-react/icons/Layers";
+import { Link } from "reicon-react/icons/Link";
+import { cn } from "../internal/classes.js";
+import { FitOnResize, flowMaxZoom, flowMinZoom, useKeyboardView, useViewportMobile, ZoomControls, } from "../internal/flow.js";
+import { Button } from "./button.js";
+export const sqlViewerLayoutNames = ["auto", "horizontal", "vertical"];
+const moreId = "~more";
+const groupId = (key) => `~group:${key}`;
+// Card geometry. The CSS uses the same numbers so layout never waits for a measure.
+const cardWidth = 272;
+const cardChrome = 4;
+const headerHeight = 40;
+const rowHeight = 28;
+const keysChrome = 36;
+const keyHeight = 26;
+const moreHeight = 132;
+const colGap = 104;
+const rowGap = 32;
+const groupPad = 20;
+const groupHeader = 44;
+const groupGap = 56;
+const wrapWidth = 1400;
+const tones = 5;
+const fitAll = { padding: 0.12, maxZoom: 1 };
+const compositeKeys = (table) => (table.uniqueKeys ?? []).filter((key) => key.fieldIds.length > 1);
+const cardHeight = (table) => {
+    const keys = compositeKeys(table).length;
+    return (cardChrome +
+        headerHeight +
+        (table.fields.length + 1) * rowHeight +
+        (keys ? keysChrome + keys * keyHeight : 0));
+};
+function columnType(field) {
+    switch (field.kind) {
+        case "text":
+            return `varchar(${field.maxLength})`;
+        case "numeric":
+            return `numeric(${field.precision},${field.scale})`;
+        case "timestamp":
+            return "timestamptz";
+        case "single-select":
+            return "enum";
+        case "multi-select":
+            return "enum[]";
+        case "relationship":
+            return field.cardinality === "one" ? "uuid" : "uuid[]";
+        case "file":
+            return field.cardinality === "one" ? "file" : "file[]";
+        default:
+            return field.kind;
+    }
+}
+function joinText(from, field, to, many) {
+    return many
+        ? `${to}.id = ANY(${from}.${field})`
+        : `${from}.${field} = ${to}.id`;
+}
+/** Places tables in team groups. Linked tables sit one column right of the tables that link to them. */
+function arrange(visible, hidden, groups, direction) {
+    const blocks = [];
+    for (const table of visible) {
+        const team = table.owningTeamId;
+        const key = team !== undefined && groups?.[team] ? team : null;
+        let block = blocks.find((candidate) => candidate.key === key);
+        if (!block) {
+            block = { key, label: key ? groups[key] : "", tables: [] };
+            blocks.push(block);
+        }
+        block.tables.push(table);
+    }
+    const nodes = [];
+    let cursorX = 0;
+    let cursorY = 0;
+    let lineHeight = 0;
+    let right = 0;
+    let bottom = 0;
+    let tone = 0;
+    for (const block of blocks) {
+        const ids = new Set(block.tables.map((table) => table.id));
+        const depth = new Map(block.tables.map((table) => [table.id, 0]));
+        if (direction === "horizontal") {
+            for (let pass = 0; pass < block.tables.length; pass++) {
+                let moved = false;
+                for (const table of block.tables)
+                    for (const field of table.fields) {
+                        if (field.kind !== "relationship")
+                            continue;
+                        const target = field.targetTableId;
+                        const next = depth.get(table.id) + 1;
+                        if (target !== table.id &&
+                            ids.has(target) &&
+                            next > depth.get(target) &&
+                            next < block.tables.length) {
+                            depth.set(target, next);
+                            moved = true;
+                        }
+                    }
+                if (!moved)
+                    break;
+            }
+        }
+        const columnBottoms = new Map();
+        const placed = block.tables.map((table) => {
+            const column = depth.get(table.id);
+            const y = columnBottoms.get(column) ?? 0;
+            columnBottoms.set(column, y + cardHeight(table) + rowGap);
+            return { table, x: column * (cardWidth + colGap), y };
+        });
+        const innerWidth = Math.max(...placed.map((item) => item.x)) + cardWidth;
+        const innerHeight = Math.max(...columnBottoms.values()) - rowGap;
+        const framed = block.key !== null;
+        const width = framed ? innerWidth + groupPad * 2 : innerWidth;
+        const height = framed ? innerHeight + groupHeader + groupPad : innerHeight;
+        if (direction === "horizontal" &&
+            cursorX > 0 &&
+            cursorX + width > wrapWidth) {
+            cursorX = 0;
+            cursorY += lineHeight + groupGap;
+            lineHeight = 0;
+        }
+        const blockTone = framed ? (tone++ % tones) + 1 : 0;
+        const parent = framed ? groupId(block.key) : undefined;
+        if (framed)
+            nodes.push({
+                id: parent,
+                type: "group",
+                position: { x: cursorX, y: cursorY },
+                width,
+                height,
+                data: {
+                    label: block.label,
+                    tone: blockTone,
+                    count: block.tables.length,
+                },
+                dragHandle: ".sprout-sql-group-label",
+                focusable: false,
+                selectable: false,
+            });
+        for (const item of placed)
+            nodes.push({
+                id: item.table.id,
+                type: "table",
+                position: framed
+                    ? { x: groupPad + item.x, y: groupHeader + item.y }
+                    : { x: cursorX + item.x, y: cursorY + item.y },
+                ...(parent ? { parentId: parent, expandParent: true } : {}),
+                data: { table: item.table, tone: blockTone },
+                ariaRole: "group",
+                ariaLabel: `${item.table.label} table, ${item.table.fields.length + 1} columns`,
+                domAttributes: { "aria-roledescription": "table card" },
+            });
+        right = Math.max(right, cursorX + width);
+        bottom = Math.max(bottom, cursorY + height);
+        if (direction === "horizontal") {
+            cursorX += width + groupGap;
+            lineHeight = Math.max(lineHeight, height);
+        }
+        else {
+            cursorY += height + groupGap;
+        }
+    }
+    if (hidden.length)
+        nodes.push({
+            id: moreId,
+            type: "more",
+            position: direction === "horizontal"
+                ? { x: right + colGap, y: 0 }
+                : { x: 0, y: bottom + groupGap },
+            data: { tables: [...hidden] },
+            focusable: false,
+        });
+    return nodes;
+}
+function joins(visible, hidden) {
+    const shown = new Set(visible.map((table) => table.id));
+    const collapsed = new Set(hidden.map((table) => table.id));
+    const labels = new Map([...visible, ...hidden].map((table) => [table.id, table.label]));
+    const node = (id) => shown.has(id) ? id : collapsed.has(id) ? moreId : null;
+    const edges = [];
+    for (const table of [...visible, ...hidden])
+        for (const field of table.fields) {
+            if (field.kind !== "relationship")
+                continue;
+            const source = node(table.id);
+            const target = node(field.targetTableId);
+            if (!source || !target || (source === moreId && target === moreId))
+                continue;
+            const to = labels.get(field.targetTableId);
+            const sourceMany = field.inverseCardinality === "many";
+            const targetMany = field.cardinality === "many";
+            edges.push({
+                id: `${table.id}/${field.id}`,
+                type: "join",
+                source,
+                sourceHandle: source === moreId ? "out:right" : `${field.id}:right`,
+                target,
+                targetHandle: target === moreId ? "in:left" : "id:left",
+                data: {
+                    join: joinText(table.label, field.label, to, targetMany),
+                    description: `${table.label}.${field.label} joins ${to}.id, ${sourceMany ? "many" : "one"} to ${targetMany ? "many" : "one"}`,
+                    sourceMany,
+                    targetMany,
+                },
+            });
+        }
+    return edges;
+}
+const ViewerContext = createContext(null);
+const useViewer = () => useContext(ViewerContext);
+function sideHandles(type, id) {
+    return (_jsxs(_Fragment, { children: [_jsx(Handle, { id: `${id}:left`, type: type, position: Position.Left, isConnectable: false, className: "sprout-sql-handle" }), _jsx(Handle, { id: `${id}:right`, type: type, position: Position.Right, isConnectable: false, className: "sprout-sql-handle" })] }));
+}
+function TableCard({ id, data: { table, tone } }) {
+    const viewer = useViewer();
+    const composite = compositeKeys(table);
+    const unique = new Set((table.uniqueKeys ?? [])
+        .filter((key) => key.fieldIds.length === 1)
+        .map((key) => key.fieldIds[0]));
+    const labels = new Map(table.fields.map((field) => [field.id, field.label]));
+    const focused = viewer.focus?.table === id;
+    return (_jsxs("section", { "data-slot": "sql-table", "data-tone": tone, "data-dimmed": viewer.focus && !viewer.related.has(id) ? "" : undefined, "data-active": focused ? "" : undefined, className: "sprout-sql-table", onMouseLeave: () => viewer.hover(null), children: [_jsx("header", { className: "sprout-sql-table-header", children: _jsx("h3", { className: "sprout-sql-table-title", title: table.label, children: table.label }) }), _jsxs("ul", { className: "sprout-sql-columns", children: [_jsxs("li", { className: "sprout-sql-column", "data-key": "primary", children: [sideHandles("target", "id"), _jsx("span", { className: "sprout-sql-column-icon", children: _jsx(Key, { size: 12, role: "img", "aria-label": "Primary key" }) }), _jsx("span", { className: "sprout-sql-column-name", children: "id" }), _jsx("span", { className: "sprout-sql-column-type", children: "uuid" })] }), table.fields.map((field) => {
+                        const join = field.kind === "relationship";
+                        const type = columnType(field);
+                        return (_jsxs("li", { className: "sprout-sql-column", "data-join": join ? "" : undefined, "data-active": focused && viewer.focus?.field === field.id ? "" : undefined, title: field.kind === "single-select" || field.kind === "multi-select"
+                                ? field.options
+                                    .filter((option) => !option.retired)
+                                    .map((option) => option.label)
+                                    .join(" · ")
+                                : undefined, onMouseEnter: join
+                                ? () => viewer.hover({ table: id, field: field.id })
+                                : undefined, onMouseLeave: join ? () => viewer.hover({ table: id }) : undefined, onClick: join
+                                ? (event) => {
+                                    event.stopPropagation();
+                                    viewer.pin({ table: id, field: field.id });
+                                }
+                                : undefined, children: [join && sideHandles("source", field.id), _jsx("span", { className: "sprout-sql-column-icon", children: join ? (_jsx(Link, { size: 12, role: "img", "aria-label": "Foreign key" })) : unique.has(field.id) ? (_jsx(Fingerprint, { size: 12, role: "img", "aria-label": "Unique" })) : null }), _jsx("span", { className: "sprout-sql-column-name", title: field.label, children: field.label }), _jsxs("span", { className: "sprout-sql-column-type", children: [type, !field.required && (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": "true", children: "?" }), _jsx("span", { className: "sprout-sql-sr-only", children: ", nullable" })] }))] })] }, field.id));
+                    })] }), composite.length > 0 && (_jsxs("div", { className: "sprout-sql-keys", children: [_jsx("p", { className: "sprout-sql-keys-title", children: "Unique keys" }), _jsx("ul", { className: "sprout-sql-keys-list", children: composite.map((key) => (_jsxs("li", { className: "sprout-sql-key", children: [_jsx(Fingerprint, { size: 12, "aria-hidden": "true" }), _jsx("span", { children: key.fieldIds
+                                        .map((field) => labels.get(field) ?? field)
+                                        .join(", ") })] }, key.id))) })] }))] }));
+}
+function GroupFrame({ data: { label, tone, count } }) {
+    return (_jsx("section", { "data-slot": "sql-group", "data-tone": tone, "aria-label": `${label}, ${count} ${count === 1 ? "table" : "tables"}`, className: "sprout-sql-group", children: _jsxs("header", { className: "sprout-sql-group-label", children: [_jsx(Layers, { size: 14, "aria-hidden": "true" }), _jsx("span", { className: "sprout-sql-group-name", children: label }), _jsx("span", { className: "sprout-sql-group-count", children: count })] }) }));
+}
+function MoreCard({ data: { tables } }) {
+    const { expand } = useViewer();
+    const names = tables.slice(0, 3).map((table) => table.label);
+    const rest = tables.length - names.length;
+    return (_jsxs("div", { "data-slot": "sql-more", className: "sprout-sql-more", children: [sideHandles("target", "in"), sideHandles("source", "out"), _jsx("span", { "aria-hidden": "true", className: "sprout-sql-more-sheet" }), _jsx("span", { "aria-hidden": "true", className: "sprout-sql-more-sheet" }), _jsxs("button", { type: "button", className: "nodrag sprout-sql-more-button", onClick: expand, "aria-label": `Show ${tables.length} more ${tables.length === 1 ? "table" : "tables"}: ${tables.map((table) => table.label).join(", ")}`, children: [_jsxs("span", { className: "sprout-sql-more-count", children: ["+", tables.length, " ", tables.length === 1 ? "table" : "tables"] }), _jsxs("span", { className: "sprout-sql-more-names", children: [names.join(", "), rest > 0 && ` and ${rest} more`] }), _jsx("span", { className: "sprout-sql-more-action", children: "Show all" })] })] }));
+}
+function handlePoint(node, type, id) {
+    const handle = node.internals.handleBounds?.[type]?.find((candidate) => candidate.id === id);
+    if (!handle)
+        return null;
+    return {
+        x: node.internals.positionAbsolute.x + handle.x + handle.width / 2,
+        y: node.internals.positionAbsolute.y + handle.y + handle.height / 2,
+    };
+}
+/** A crow's foot for many, a bar for one, drawn outward from the card edge. */
+function endMark(x, y, side, many) {
+    const out = side === "right" ? 1 : -1;
+    return many
+        ? `M ${x + out * 12} ${y} L ${x} ${y - 6} M ${x + out * 12} ${y} L ${x} ${y + 6}`
+        : `M ${x + out * 9} ${y - 5} L ${x + out * 9} ${y + 5}`;
+}
+// Picks the facing sides of the two cards on every render, so links stay tidy while tables are dragged.
+function JoinLine({ id, source, target, sourceHandleId, targetHandleId, data, }) {
+    const from = useInternalNode(source);
+    const to = useInternalNode(target);
+    const viewer = useViewer();
+    if (!from || !to || !data || !sourceHandleId || !targetHandleId)
+        return null;
+    const fromLeft = from.internals.positionAbsolute.x;
+    const toLeft = to.internals.positionAbsolute.x;
+    const fromRight = fromLeft + (from.measured.width ?? 0);
+    const toRight = toLeft + (to.measured.width ?? 0);
+    const [sourceSide, targetSide] = fromRight + 24 <= toLeft
+        ? ["right", "left"]
+        : toRight + 24 <= fromLeft
+            ? ["left", "right"]
+            : ["right", "right"];
+    const base = (handle) => handle.slice(0, handle.lastIndexOf(":"));
+    const start = handlePoint(from, "source", `${base(sourceHandleId)}:${sourceSide}`);
+    const end = handlePoint(to, "target", `${base(targetHandleId)}:${targetSide}`);
+    if (!start || !end)
+        return null;
+    const position = (side) => side === "right" ? Position.Right : Position.Left;
+    const [path] = getSmoothStepPath({
+        sourceX: start.x,
+        sourceY: start.y,
+        sourcePosition: position(sourceSide),
+        targetX: end.x,
+        targetY: end.y,
+        targetPosition: position(targetSide),
+        borderRadius: 10,
+        offset: 28,
+    });
+    const active = viewer.activeEdges.has(id);
+    return (_jsx("path", { d: `${path} ${endMark(start.x, start.y, sourceSide, data.sourceMany)} ${endMark(end.x, end.y, targetSide, data.targetMany)}`, className: "react-flow__edge-path sprout-sql-join", "data-active": active ? "" : undefined, "data-dimmed": viewer.focus && !active ? "" : undefined }));
+}
+const nodeTypes = { table: TableCard, group: GroupFrame, more: MoreCard };
+const edgeTypes = { join: JoinLine };
+const keyboardHint = "Arrow keys pan, plus and minus zoom, and 0 fits the diagram. Tab moves between tables; Enter pins a table's joins.";
+function ViewerFlow({ layoutNodes, edges, direction, label, hintId, expanded, setExpanded, collapsible, maxVisible, }) {
+    const [nodes, setNodes, onNodesChange] = useNodesState(layoutNodes);
+    useEffect(() => setNodes(layoutNodes), [layoutNodes, setNodes]);
+    const [hovered, setHovered] = useState(null);
+    const [pinned, setPinned] = useState(null);
+    const focus = hovered ?? pinned;
+    const pin = useCallback((next) => setPinned((current) => current?.table === next.table && current.field === next.field
+        ? null
+        : next), []);
+    const state = useMemo(() => {
+        const activeEdges = new Set();
+        const related = new Set();
+        if (focus) {
+            related.add(focus.table);
+            for (const edge of edges) {
+                const hit = focus.field
+                    ? edge.id === `${focus.table}/${focus.field}`
+                    : edge.source === focus.table || edge.target === focus.table;
+                if (!hit)
+                    continue;
+                activeEdges.add(edge.id);
+                related.add(edge.source).add(edge.target);
+            }
+        }
+        return {
+            focus,
+            related,
+            activeEdges,
+            hover: setHovered,
+            pin,
+            expand: () => setExpanded(true),
+        };
+    }, [focus, edges, pin, setExpanded]);
+    const shownEdges = useMemo(() => state.activeEdges.size
+        ? edges.map((edge) => state.activeEdges.has(edge.id) ? { ...edge, zIndex: 1000 } : edge)
+        : edges, [edges, state.activeEdges]);
+    // Phones fit the first block to the width and let people pan down; wider panes fit everything.
+    const fitFirst = useMemo(() => direction === "vertical" && layoutNodes[0]
+        ? { padding: 0.06, maxZoom: 1, nodes: [{ id: layoutNodes[0].id }] }
+        : fitAll, [direction, layoutNodes]);
+    const keyboardView = useKeyboardView(fitAll);
+    const onKeyDown = (event) => {
+        const target = event.target;
+        const id = target.dataset["id"];
+        if ((event.key === "Enter" || event.key === " ") &&
+            target.classList.contains("react-flow__node-table") &&
+            id) {
+            event.preventDefault();
+            pin({ table: id });
+            return;
+        }
+        if (event.key === "Escape" && pinned) {
+            setPinned(null);
+            return;
+        }
+        keyboardView(event);
+    };
+    const onFocus = (event) => {
+        const id = event.target.dataset["id"];
+        if (event.target.classList.contains("react-flow__node-table") && id)
+            setHovered({ table: id });
+    };
+    const onNodeMouseEnter = (_, node) => {
+        if (node.type === "table")
+            setHovered({ table: node.id });
+    };
+    const onNodeClick = (_, node) => {
+        if (node.type === "table")
+            pin({ table: node.id });
+    };
+    return (_jsx(ViewerContext.Provider, { value: state, children: _jsxs(ReactFlow, { className: "sprout-schema-flow sprout-sql-flow", "data-slot": "sql-viewer-viewport", "data-focus": focus ? "" : undefined, "aria-label": label, "aria-describedby": hintId, tabIndex: 0, onKeyDown: onKeyDown, onFocus: onFocus, onBlur: () => setHovered(null), nodes: nodes, edges: shownEdges, onNodesChange: onNodesChange, nodeTypes: nodeTypes, edgeTypes: edgeTypes, onNodeMouseEnter: onNodeMouseEnter, onNodeClick: onNodeClick, onPaneClick: () => setPinned(null), fitView: true, fitViewOptions: fitFirst, minZoom: flowMinZoom, maxZoom: flowMaxZoom, nodesConnectable: false, elementsSelectable: false, edgesFocusable: false, ariaLabelConfig: {
+                "node.a11yDescription.default": keyboardHint,
+                "node.a11yDescription.keyboardDisabled": keyboardHint,
+            }, proOptions: { hideAttribution: true }, children: [_jsx(Background, { gap: 16, size: 1 }), _jsx(FitOnResize, { nodes: layoutNodes, fit: fitFirst }), collapsible && expanded && (_jsx(Panel, { position: "top-left", "data-slot": "sql-viewer-collapse", children: _jsxs(Button, { variant: "secondary", size: "sm", onClick: () => {
+                            setPinned(null);
+                            setExpanded(false);
+                        }, children: ["Show ", maxVisible, " tables"] }) })), state.activeEdges.size > 0 && (_jsxs(Panel, { position: "bottom-left", "data-slot": "sql-viewer-joins", "aria-hidden": "true", className: "sprout-sql-joins", children: [edges
+                            .filter((edge) => state.activeEdges.has(edge.id))
+                            .slice(0, 3)
+                            .map((edge) => (_jsx("code", { className: "sprout-sql-join-text", children: edge.data.join }, edge.id))), state.activeEdges.size > 3 && (_jsxs("span", { className: "sprout-sql-joins-more", children: ["and ", state.activeEdges.size - 3, " more"] }))] })), _jsx(ZoomControls, { position: direction === "vertical" ? "top-right" : "bottom-right", fit: fitAll, className: "sprout-schema-controls", slot: "sql-viewer-controls" })] }) }));
+}
+/**
+ * A pan-and-zoom map of SQL tables, their columns and keys, and the joins
+ * between them. Hover or pin a table or a foreign key to trace its joins.
+ */
+export function SqlViewer({ tables, label, groups, maxVisible = 4, layout = "auto", className, ...props }) {
+    const mobile = useViewportMobile();
+    const direction = layout === "auto" ? (mobile ? "vertical" : "horizontal") : layout;
+    const hintId = useId();
+    const [expanded, setExpanded] = useState(false);
+    const limit = Math.max(1, Math.floor(maxVisible));
+    const collapsible = tables.length > limit;
+    const [visible, hidden] = useMemo(() => collapsible && !expanded
+        ? [tables.slice(0, limit), tables.slice(limit)]
+        : [tables, []], [tables, limit, collapsible, expanded]);
+    const layoutNodes = useMemo(() => arrange(visible, hidden, groups, direction), [visible, hidden, groups, direction]);
+    const edges = useMemo(() => joins(visible, hidden), [visible, hidden]);
+    const descriptions = joins(tables, []);
+    return (_jsxs("div", { ...props, role: "figure", "aria-label": label, "data-slot": "sql-viewer", "data-layout": direction, className: cn("sprout-sql-viewer", className), children: [_jsx("p", { id: hintId, className: "sprout-sql-sr-only", children: keyboardHint }), descriptions.length > 0 && (_jsx("ul", { "aria-label": "Joins", className: "sprout-sql-sr-only", children: descriptions.map((edge) => (_jsx("li", { children: edge.data.description }, edge.id))) })), tables.length === 0 ? (_jsx("p", { className: "sprout-sql-empty", children: "No tables to show" })) : (_jsx(ReactFlowProvider, { children: _jsx(ViewerFlow, { layoutNodes: layoutNodes, edges: edges, direction: direction, label: label, hintId: hintId, expanded: expanded, setExpanded: setExpanded, collapsible: collapsible, maxVisible: limit }) }, direction))] }));
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./components/accordion.js";
+export * from "./components/agent-fanout.js";
 export * from "./components/alert.js";
 export * from "./components/alert-dialog.js";
 export * from "./components/aspect-ratio.js";
@@ -53,6 +54,7 @@ export * from "./components/page-header.js";
 export * from "./components/pagination.js";
 export * from "./components/plan-outline.js";
 export * from "./components/popover.js";
+export * from "./components/presence-cursor.js";
 export * from "./components/progress.js";
 export * from "./components/prompt-list.js";
 export * from "./components/questionnaire.js";
@@ -63,6 +65,7 @@ export * from "./components/result-card.js";
 export * from "./components/review-card.js";
 export * from "./components/rich-text-editor.js";
 export * from "./components/schema-diagram.js";
+export * from "./components/sql-viewer.js";
 export * from "./components/scroll-area.js";
 export * from "./components/search-dialog.js";
 export * from "./components/search-field.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./components/accordion.js";
+export * from "./components/agent-fanout.js";
 export * from "./components/alert.js";
 export * from "./components/alert-dialog.js";
 export * from "./components/aspect-ratio.js";
@@ -53,6 +54,7 @@ export * from "./components/page-header.js";
 export * from "./components/pagination.js";
 export * from "./components/plan-outline.js";
 export * from "./components/popover.js";
+export * from "./components/presence-cursor.js";
 export * from "./components/progress.js";
 export * from "./components/prompt-list.js";
 export * from "./components/questionnaire.js";
@@ -63,6 +65,7 @@ export * from "./components/result-card.js";
 export * from "./components/review-card.js";
 export * from "./components/rich-text-editor.js";
 export * from "./components/schema-diagram.js";
+export * from "./components/sql-viewer.js";
 export * from "./components/scroll-area.js";
 export * from "./components/search-dialog.js";
 export * from "./components/search-field.js";