@iloveagents/foundry-web-graph 0.1.0

package/dist/graph-inspector.js

@@ -0,0 +1,106 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect } from "react";
+import { Maximize2, Snowflake, X } from "lucide-react";
+import { cn } from "@iloveagents/foundry-web-primitives";
+import { primaryLabel, resolveCaption, safeStringify, } from "./model.js";
+/** Render a property value without collapsing structure into "[object Object]". */
+function formatValue(value) {
+    if (value === null || value === undefined)
+        return "—";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+        return String(value);
+    }
+    if (Array.isArray(value))
+        return value.map(formatValue).join(", ");
+    // `safeStringify`, not `JSON.stringify`: a structured property containing a
+    // `bigint` (`{ count: 10n }`) THROWS, and the fallback then renders
+    // "[object Object]" — hiding the value in the one panel whose entire job is
+    // showing it. Cycles are handled for the same reason.
+    return safeStringify(value);
+}
+/**
+ * Label/value rows, matching the field list a downstream app already uses for
+ * "inspect this item".
+ *
+ * A fixed label column rather than a two-column grid: property names in a
+ * graph are short and repetitive (`name`, `year`, `title`), values are not, so
+ * an auto-sized label column jitters between selections and makes the drawer
+ * feel like it is redrawing itself every time you click.
+ */
+function PropertyRows({ properties }) {
+    const entries = Object.entries(properties ?? {});
+    if (entries.length === 0) {
+        return (_jsx("p", { className: "text-muted-foreground rounded-xl border border-dashed px-3 py-6 text-center text-sm", children: "No properties." }));
+    }
+    return (_jsx("div", { className: "divide-border/60 border-border/70 divide-y rounded-xl border", children: entries.map(([key, value]) => (_jsx("div", { className: "px-3 py-2", children: _jsxs("div", { className: "flex min-h-9 items-start gap-3", children: [_jsx("span", { className: "text-muted-foreground w-28 shrink-0 truncate pt-0.5 text-sm", title: key, children: key }), _jsx("div", { className: "text-foreground min-w-0 flex-1 break-words text-sm", children: formatValue(value) })] }) }, key))) }));
+}
+/**
+ * The drawer's width in pixels, matching `w-80` below.
+ *
+ * Exported because the canvas has to know how much of itself is covered:
+ * a node hidden behind the drawer is a node you selected and then could not
+ * see. Kept as a number rather than measured, so the pan can be issued in
+ * the same frame the drawer opens.
+ */
+export const GRAPH_INSPECTOR_WIDTH = 320;
+/**
+ * Details for the selected node or relationship.
+ *
+ * A drawer over the canvas, not a rail beside it. A rail is the obvious
+ * layout and it is wrong here: it takes its width from the graph permanently,
+ * so selecting a node — the one gesture that means "I want to look at this
+ * more closely" — is also the gesture that shrinks what you are looking at.
+ * Over the canvas, the graph keeps its full width and the drawer is dismissed
+ * the moment you are done with it.
+ *
+ * Also the accessible surface for the graph: the canvas itself is opaque to a
+ * screen reader, so everything a sighted user learns by hovering has to be
+ * readable here as ordinary DOM.
+ */
+export function GraphInspector({ selection, colorForLabel, captionOf, onClose, onExpandNode, onToggleFrozen, isFrozen, actions, className, }) {
+    const { node, edge } = selection;
+    const open = Boolean(node || edge);
+    // Escape closes, matching every other dismissible surface. Bound to the
+    // window rather than the drawer because the canvas keeps keyboard focus —
+    // people select with the mouse and expect Escape to work without clicking
+    // into the panel first.
+    useEffect(() => {
+        if (!open)
+            return;
+        const onKey = (event) => {
+            if (event.key !== "Escape" || event.defaultPrevented)
+                return;
+            // One press, one dismissal. The host's tool panel listens for Escape on
+            // the window too, and it was registered first (it mounts before a
+            // selection exists), so in the bubble phase it ran first and closed the
+            // WHOLE graph panel out from under the drawer this key was meant for.
+            //
+            // Hence capture: a capture listener on `window` runs before every bubble
+            // listener on it, and `stopPropagation` there ends the trip — the event
+            // never reaches the target and never bubbles back. `preventDefault` as
+            // well, for any handler that guards on `defaultPrevented` instead.
+            event.stopPropagation();
+            event.preventDefault();
+            onClose();
+        };
+        window.addEventListener("keydown", onKey, true);
+        return () => window.removeEventListener("keydown", onKey, true);
+    }, [open, onClose]);
+    if (!node && !edge)
+        return null;
+    const frozen = node ? Boolean(isFrozen?.(node)) : false;
+    return (
+    // Non-modal, and pointer-transparent everywhere but the drawer itself.
+    // No scrim, no click-catcher: with the graph covered by an invisible
+    // button you cannot click the next node, pan, or zoom while a node's
+    // details are open — which is most of what you do with a graph. Dismissal
+    // is the close button, Escape, or simply selecting something else.
+    _jsx("div", { className: cn("pointer-events-none absolute inset-0 z-20 flex justify-end", className), children: _jsxs("aside", { role: "dialog", "aria-modal": "false", "aria-label": node ? "Selected node" : "Selected relationship", className: "foundry-graph-drawer border-border bg-background pointer-events-auto flex h-full w-80 max-w-[85%] flex-col border-l shadow-2xl", children: [_jsxs("header", { className: "border-border flex items-start justify-between gap-3 border-b px-4 py-3", children: [_jsxs("div", { className: "min-w-0", children: [node ? (_jsxs("p", { className: "text-muted-foreground flex flex-wrap items-center gap-1.5 text-[11px] font-semibold uppercase tracking-[0.14em]", children: [_jsx("span", { "aria-hidden": "true", className: "size-2 shrink-0 rounded-full", style: { backgroundColor: colorForLabel(primaryLabel(node)) } }), (node.labels?.length ? node.labels : ["Node"]).join(" · ")] })) : (_jsx("p", { className: "text-muted-foreground text-[11px] font-semibold uppercase tracking-[0.14em]", children: "Relationship" })), _jsx("h2", { className: "text-foreground truncate text-base font-semibold", title: headingOf(), children: headingOf() })] }), _jsx("button", { type: "button", onClick: onClose, "aria-label": "Close details", className: "border-border text-muted-foreground hover:bg-muted focus-visible:ring-ring rounded-lg border p-1.5 transition-colors focus-visible:outline-none focus-visible:ring-1", children: _jsx(X, { className: "size-4" }) })] }), _jsx("div", { className: "min-h-0 flex-1 overflow-y-auto px-4 py-4", children: _jsx(PropertyRows, { properties: (node ?? edge).properties }) }), node && (onExpandNode || onToggleFrozen || actions) && (_jsxs("footer", { className: "border-border flex items-center justify-end gap-1.5 border-t px-4 py-3", children: [actions, onToggleFrozen && (_jsxs("button", { type: "button", onClick: () => onToggleFrozen(node), "aria-pressed": frozen, title: frozen ? "Let the layout move this node" : "Freeze this node in place", className: cn("border-border hover:bg-muted focus-visible:ring-ring inline-flex items-center gap-1.5 rounded-lg border px-2.5 py-1.5 text-xs transition-colors focus-visible:outline-none focus-visible:ring-1", frozen ? "text-primary" : "text-muted-foreground"), children: [_jsx(Snowflake, { className: "size-3.5" }), frozen ? "Frozen" : "Freeze"] })), onExpandNode && (_jsxs("button", { type: "button", onClick: () => onExpandNode(node), title: "Load this node's neighbours", className: "border-border hover:bg-muted text-foreground focus-visible:ring-ring inline-flex items-center gap-1.5 rounded-lg border px-2.5 py-1.5 text-xs transition-colors focus-visible:outline-none focus-visible:ring-1", children: [_jsx(Maximize2, { className: "size-3.5" }), "Expand"] }))] }))] }) }));
+    function headingOf() {
+        if (node)
+            return captionOf(node) || resolveCaption(node);
+        return edge?.type ?? "RELATED";
+    }
+}

package/dist/graph-legend.d.ts

@@ -0,0 +1,19 @@
+import type { GraphStyleMap } from "./use-graph-styling.js";
+export interface GraphLegendProps {
+    styleMap: GraphStyleMap;
+    /** Node count per label, so the legend doubles as a breakdown. */
+    counts: ReadonlyMap<string, number>;
+    hiddenLabels: Set<string>;
+    onToggleLabel: (label: string) => void;
+    onShowAll: () => void;
+    className?: string;
+}
+/**
+ * Colour key for node labels, and the filter control.
+ *
+ * Clicking a label hides that type — the fastest way to make a dense graph
+ * readable, and the one interaction Bloom users reach for first. Rendered as
+ * real `<button>`s so the filter is keyboard-reachable; the canvas beside it
+ * is not.
+ */
+export declare function GraphLegend({ styleMap, counts, hiddenLabels, onToggleLabel, onShowAll, className, }: GraphLegendProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/graph-legend.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@iloveagents/foundry-web-primitives";
+/**
+ * Colour key for node labels, and the filter control.
+ *
+ * Clicking a label hides that type — the fastest way to make a dense graph
+ * readable, and the one interaction Bloom users reach for first. Rendered as
+ * real `<button>`s so the filter is keyboard-reachable; the canvas beside it
+ * is not.
+ */
+export function GraphLegend({ styleMap, counts, hiddenLabels, onToggleLabel, onShowAll, className, }) {
+    if (styleMap.labels.length === 0)
+        return null;
+    return (_jsxs("div", { className: cn("flex flex-wrap items-center gap-1.5", className), children: [styleMap.labels.map((label) => {
+                const hidden = hiddenLabels.has(label);
+                return (_jsxs("button", { type: "button", onClick: () => onToggleLabel(label), "aria-pressed": !hidden, title: hidden ? `Show ${label}` : `Hide ${label}`, className: cn("inline-flex items-center gap-1.5 rounded-full border px-2 py-0.5 text-xs transition-colors", "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring", hidden
+                        ? "border-border text-muted-foreground opacity-60"
+                        : "border-border bg-card text-foreground hover:bg-accent"), children: [_jsx("span", { "aria-hidden": "true", className: "size-2 shrink-0 rounded-full", style: { backgroundColor: styleMap.colorForLabel(label) } }), _jsx("span", { className: cn(hidden && "line-through"), children: label }), _jsx("span", { className: "text-muted-foreground tabular-nums", children: counts.get(label) ?? 0 })] }, label));
+            }), hiddenLabels.size > 0 && (_jsx("button", { type: "button", onClick: onShowAll, className: "rounded-full px-2 py-0.5 text-xs text-muted-foreground underline-offset-2 hover:underline focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring", children: "Show all" }))] }));
+}

package/dist/graph-notice.d.ts

@@ -0,0 +1,19 @@
+import type { GraphModelLoss } from "./use-graph-model.js";
+/** Shown in place of the canvas when there is nothing to draw. */
+export declare function GraphEmptyState({ message, className }: {
+    message?: string;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Say what was withheld, and why.
+ *
+ * A graph that silently renders 1,500 of 40,000 nodes is worse than one that
+ * refuses to render: the user reads the picture as the whole answer. Each
+ * cause is named separately because the fixes differ — a cap means "narrow the
+ * query", dangling edges mean "the projection is incomplete".
+ */
+export declare function GraphLossNotice({ loss, truncatedByProducer, className, }: {
+    loss: GraphModelLoss;
+    truncatedByProducer?: boolean;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/graph-notice.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { AlertTriangle, Network } from "lucide-react";
+import { cn } from "@iloveagents/foundry-web-primitives";
+/** Shown in place of the canvas when there is nothing to draw. */
+export function GraphEmptyState({ message, className }) {
+    return (_jsxs("div", { className: cn("text-muted-foreground flex h-full flex-col items-center justify-center gap-2 p-6 text-center", className), children: [_jsx(Network, { className: "size-6 opacity-50", "aria-hidden": "true" }), _jsx("p", { className: "text-sm", children: message ?? "No graph data to display." })] }));
+}
+/**
+ * Say what was withheld, and why.
+ *
+ * A graph that silently renders 1,500 of 40,000 nodes is worse than one that
+ * refuses to render: the user reads the picture as the whole answer. Each
+ * cause is named separately because the fixes differ — a cap means "narrow the
+ * query", dangling edges mean "the projection is incomplete".
+ */
+export function GraphLossNotice({ loss, truncatedByProducer, className, }) {
+    const reasons = [];
+    if (truncatedByProducer)
+        reasons.push("the query hit the server's result cap");
+    if (loss.cappedNodes > 0)
+        reasons.push(`${loss.cappedNodes} nodes over the render limit`);
+    if (loss.cappedEdges > 0)
+        reasons.push(`${loss.cappedEdges} relationships over the render limit`);
+    if (loss.danglingEdges > 0) {
+        reasons.push(`${loss.danglingEdges} relationships whose endpoints weren't returned`);
+    }
+    if (reasons.length === 0)
+        return null;
+    return (_jsxs("p", { role: "status", className: cn("text-muted-foreground flex items-start gap-1.5 text-xs", className), children: [_jsx(AlertTriangle, { className: "mt-px size-3.5 shrink-0", "aria-hidden": "true" }), _jsxs("span", { children: ["Showing a partial graph \u2014 ", reasons.join("; "), "."] })] }));
+}

package/dist/graph-table.d.ts

@@ -0,0 +1,28 @@
+import { type GraphEdge, type GraphNode } from "./model.js";
+import { type GraphModel } from "./use-graph-model.js";
+import type { GraphStyleMap } from "./use-graph-styling.js";
+export interface GraphTableProps {
+    model: GraphModel;
+    styleMap: GraphStyleMap;
+    onSelectNode?: (node: GraphNode) => void;
+    /**
+     * Open a relationship in the inspector.
+     *
+     * The drawer has always handled edges; only the canvas could reach them.
+     * This table IS the accessibility surface — the canvas is one opaque element
+     * to a screen reader — so without this a keyboard user could read that a
+     * relationship exists and never see a single one of its properties, while a
+     * mouse user clicks the same line and gets all of them.
+     */
+    onSelectEdge?: (edge: GraphEdge) => void;
+    className?: string;
+}
+/**
+ * The same graph as a table.
+ *
+ * This is the accessible surface, not a developer escape hatch: a `<canvas>` is
+ * opaque to a screen reader, so without this the graph is simply unavailable to
+ * anyone using one. It is also what renders when there is no canvas at all —
+ * jsdom in tests, and print.
+ */
+export declare function GraphTable({ model, styleMap, onSelectNode, onSelectEdge, className, }: GraphTableProps): import("react/jsx-runtime").JSX.Element;

package/dist/graph-table.js

@@ -0,0 +1,57 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@iloveagents/foundry-web-primitives";
+import { useMemo } from "react";
+import { primaryLabel } from "./model.js";
+import { endpointId } from "./use-graph-model.js";
+/**
+ * The same graph as a table.
+ *
+ * This is the accessible surface, not a developer escape hatch: a `<canvas>` is
+ * opaque to a screen reader, so without this the graph is simply unavailable to
+ * anyone using one. It is also what renders when there is no canvas at all —
+ * jsdom in tests, and print.
+ */
+export function GraphTable({ model, styleMap, onSelectNode, onSelectEdge, className, }) {
+    // Counted once, not per row. The old version filtered the whole link array
+    // for every node — quadratic, and this is the ACCESSIBILITY path, where a
+    // capped graph can still carry 1,500 nodes and 3,000 edges.
+    //
+    // Endpoints are read through a helper because force-graph replaces the ids
+    // with the node objects once it has run: after a canvas render, comparing
+    // against `node.id` would silently give every row a degree of zero.
+    const degrees = useMemo(() => {
+        const counts = new Map();
+        const bump = (id) => {
+            if (id === undefined)
+                return;
+            counts.set(id, (counts.get(id) ?? 0) + 1);
+        };
+        for (const link of model.links) {
+            bump(endpointId(link.source));
+            bump(endpointId(link.target));
+        }
+        return counts;
+    }, [model.links]);
+    // The relationships, resolved to the captions the nodes are listed under.
+    // A degree count says a node is connected; it does not say to WHAT, by which
+    // type, or in which direction — which is the whole content of a graph. A
+    // screen-reader user reading only the node table could not tell two
+    // completely different graphs apart.
+    const captionFor = useMemo(() => {
+        const byId = new Map(model.nodes.map((node) => [node.id, styleMap.styleForNode(node).caption]));
+        return (id) => (id === undefined ? "—" : (byId.get(id) ?? id));
+    }, [model.nodes, styleMap]);
+    return (_jsxs("div", { className: cn("flex flex-col gap-4 overflow-auto", className), children: [_jsxs("table", { className: "w-full border-collapse text-left text-xs", children: [_jsxs("caption", { className: "sr-only", children: ["Nodes: ", model.nodes.length, " of them, in a graph with ", model.links.length, " relationships"] }), _jsx("thead", { className: "text-muted-foreground sticky top-0", children: _jsxs("tr", { className: "border-border bg-card border-b", children: [_jsx("th", { scope: "col", className: "px-2 py-1 font-medium", children: "Label" }), _jsx("th", { scope: "col", className: "px-2 py-1 font-medium", children: "Caption" }), _jsx("th", { scope: "col", className: "px-2 py-1 font-medium", children: "Relationships" })] }) }), _jsx("tbody", { children: model.nodes.map((node) => {
+                            const degree = degrees.get(node.id) ?? 0;
+                            return (_jsxs("tr", { className: "border-border/60 border-b last:border-0", children: [_jsx("td", { className: "text-muted-foreground px-2 py-1", children: primaryLabel(node) }), _jsx("td", { className: "px-2 py-1", children: onSelectNode ? (_jsx("button", { type: "button", onClick: () => onSelectNode(node), className: "focus-visible:ring-ring rounded underline-offset-2 hover:underline focus-visible:outline-none focus-visible:ring-1", children: styleMap.styleForNode(node).caption })) : (styleMap.styleForNode(node).caption) }), _jsx("td", { className: "text-muted-foreground px-2 py-1 tabular-nums", children: degree })] }, node.id));
+                        }) })] }), model.links.length > 0 && (_jsxs("table", { className: "w-full border-collapse text-left text-xs", children: [_jsxs("caption", { className: "sr-only", children: ["Relationships: ", model.links.length, " of them, as source, type and target", onSelectEdge ? "; the type opens its properties" : ""] }), _jsx("thead", { className: "text-muted-foreground sticky top-0", children: _jsxs("tr", { className: "border-border bg-card border-b", children: [_jsx("th", { scope: "col", className: "px-2 py-1 font-medium", children: "From" }), _jsx("th", { scope: "col", className: "px-2 py-1 font-medium", children: "Type" }), _jsx("th", { scope: "col", className: "px-2 py-1 font-medium", children: "To" })] }) }), _jsx("tbody", { children: model.links.map((link) => (_jsxs("tr", { className: "border-border/60 border-b last:border-0", children: [_jsx("td", { className: "px-2 py-1", children: captionFor(endpointId(link.source)) }), _jsx("td", { className: "text-muted-foreground px-2 py-1", children: onSelectEdge ? (_jsx("button", { type: "button", 
+                                        // Endpoints normalised for the same reason
+                                        // `getViewState` normalises them: force-graph swaps a
+                                        // link\'s `source`/`target` for the node objects once it
+                                        // has run, and the inspector reads ids.
+                                        onClick: () => onSelectEdge({
+                                            ...link,
+                                            source: endpointId(link.source) ?? "",
+                                            target: endpointId(link.target) ?? "",
+                                        }), className: "hover:text-foreground focus-visible:ring-ring rounded text-left underline decoration-dotted underline-offset-2 focus-visible:outline-none focus-visible:ring-1", children: link.type ?? "RELATED" })) : ((link.type ?? "RELATED")) }), _jsx("td", { className: "px-2 py-1", children: captionFor(endpointId(link.target)) })] }, link.id))) })] }))] }));
+}

package/dist/graph-toolbar.d.ts

@@ -0,0 +1,22 @@
+export interface GraphToolbarProps {
+    query: string;
+    onQueryChange: (value: string) => void;
+    /** Number of nodes matching the query — shown next to the search box. */
+    matchCount: number;
+    nodeCount: number;
+    edgeCount: number;
+    onZoomToFit: () => void;
+    onReheat: () => void;
+    pinnedCount: number;
+    onUnpinAll: () => void;
+    /**
+     * Whether the table is showing, and how to swap. Omitted where there is no
+     * choice to offer — a host that pinned the view with `forceTable`, or an
+     * environment with no canvas at all.
+     */
+    showsTable?: boolean;
+    onToggleTable?: () => void;
+    className?: string;
+}
+/** Search, layout controls and element counts. */
+export declare function GraphToolbar({ query, onQueryChange, matchCount, nodeCount, edgeCount, onZoomToFit, onReheat, pinnedCount, onUnpinAll, showsTable, onToggleTable, className, }: GraphToolbarProps): import("react/jsx-runtime").JSX.Element;

package/dist/graph-toolbar.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Maximize2, PinOff, Play, Search, Share2, Table2, X } from "lucide-react";
+import { cn } from "@iloveagents/foundry-web-primitives";
+const iconButton = "text-muted-foreground hover:text-foreground hover:bg-accent focus-visible:ring-ring inline-flex size-7 items-center justify-center rounded focus-visible:outline-none focus-visible:ring-1";
+/** Search, layout controls and element counts. */
+export function GraphToolbar({ query, onQueryChange, matchCount, nodeCount, edgeCount, onZoomToFit, onReheat, pinnedCount, onUnpinAll, showsTable, onToggleTable, className, }) {
+    return (_jsxs("div", { className: cn("flex items-center gap-2", className), children: [_jsxs("div", { className: "border-border bg-card focus-within:ring-ring flex min-w-0 flex-1 items-center gap-1.5 rounded-md border px-2 py-1 focus-within:ring-1", children: [_jsx(Search, { className: "text-muted-foreground size-3.5 shrink-0", "aria-hidden": "true" }), _jsx("input", { type: "search", value: query, onChange: (event) => onQueryChange(event.target.value), placeholder: "Search nodes\u2026", "aria-label": "Search nodes", className: "text-foreground placeholder:text-muted-foreground min-w-0 flex-1 bg-transparent text-xs outline-none" }), query.length > 0 && (_jsxs(_Fragment, { children: [_jsx("span", { className: "text-muted-foreground shrink-0 text-xs tabular-nums", title: `${matchCount} matching ${matchCount === 1 ? "node" : "nodes"}`, "aria-label": `${matchCount} matching ${matchCount === 1 ? "node" : "nodes"}`, children: matchCount }), _jsx("button", { type: "button", onClick: () => onQueryChange(""), "aria-label": "Clear search", className: "text-muted-foreground hover:text-foreground shrink-0", children: _jsx(X, { className: "size-3" }) })] }))] }), _jsxs("span", { className: "text-muted-foreground shrink-0 text-xs tabular-nums", children: [nodeCount, " nodes \u00B7 ", edgeCount, " rels"] }), onToggleTable && (_jsxs("button", { type: "button", onClick: onToggleTable, title: showsTable ? "Show the graph" : "Show as a table", "aria-pressed": showsTable, className: iconButton, children: [showsTable ? _jsx(Share2, { className: "size-3.5" }) : _jsx(Table2, { className: "size-3.5" }), _jsx("span", { className: "sr-only", children: showsTable ? "Show the graph" : "Show as a table" })] })), pinnedCount > 0 && (_jsxs("button", { type: "button", onClick: onUnpinAll, title: "Unpin all nodes", className: iconButton, children: [_jsx(PinOff, { className: "size-3.5" }), _jsx("span", { className: "sr-only", children: "Unpin all nodes" })] })), _jsxs("button", { type: "button", onClick: onReheat, title: "Restart layout", className: iconButton, children: [_jsx(Play, { className: "size-3.5" }), _jsx("span", { className: "sr-only", children: "Restart layout" })] }), _jsxs("button", { type: "button", onClick: onZoomToFit, title: "Zoom to fit", className: iconButton, children: [_jsx(Maximize2, { className: "size-3.5" }), _jsx("span", { className: "sr-only", children: "Zoom to fit" })] })] }));
+}

package/dist/graph-tooltip.d.ts

@@ -0,0 +1,4 @@
+import { type GraphStyleMap } from "./use-graph-styling.js";
+import type { GraphEdge, GraphNode } from "./model.js";
+export declare function nodeTooltip(node: GraphNode, styleMap: GraphStyleMap): HTMLElement;
+export declare function edgeTooltip(edge: GraphEdge): HTMLElement;

package/dist/graph-tooltip.js

@@ -0,0 +1,55 @@
+import { describeEdge, describeNode } from "./use-graph-styling.js";
+/**
+ * Build the hover tooltip as a DOM element, NOT as an HTML string.
+ *
+ * `force-graph`'s tooltip (`float-tooltip`) does `selection.html(content)` when
+ * given a string — i.e. `innerHTML`. Node captions and property values come
+ * straight out of the database, so a string tooltip would execute markup stored
+ * in the graph. Returning an `HTMLElement` takes the library's other branch,
+ * which appends the node as-is, and everything here is set via `textContent`.
+ *
+ * Do not "simplify" this back into a template literal.
+ */
+function tooltipElement(heading, rows) {
+    const root = document.createElement("div");
+    const title = document.createElement("div");
+    title.style.fontWeight = "600";
+    title.textContent = heading;
+    title.style.marginBottom = rows.length ? "0.125rem" : "0";
+    root.appendChild(title);
+    for (const [key, value] of rows) {
+        const row = document.createElement("div");
+        // The token, not a hardcoded grey — the tooltip sits on the host's
+        // popover surface (see `.float-tooltip-kap` in styles.css).
+        row.style.color = "var(--muted-foreground)";
+        row.textContent = `${key}: ${value}`;
+        root.appendChild(row);
+    }
+    return root;
+}
+/** Property rows to preview in a tooltip — enough to identify, not a dump. */
+const MAX_TOOLTIP_ROWS = 4;
+const MAX_TOOLTIP_VALUE_CHARS = 80;
+function previewRows(properties) {
+    const rows = [];
+    for (const [key, value] of Object.entries(properties ?? {})) {
+        if (rows.length >= MAX_TOOLTIP_ROWS)
+            break;
+        if (value === null || value === undefined)
+            continue;
+        const text = String(value);
+        rows.push([
+            key,
+            text.length > MAX_TOOLTIP_VALUE_CHARS
+                ? `${text.slice(0, MAX_TOOLTIP_VALUE_CHARS - 1)}…`
+                : text,
+        ]);
+    }
+    return rows;
+}
+export function nodeTooltip(node, styleMap) {
+    return tooltipElement(describeNode(node, styleMap.styleForNode(node).caption), previewRows(node.properties));
+}
+export function edgeTooltip(edge) {
+    return tooltipElement(describeEdge(edge), previewRows(edge.properties));
+}

package/dist/graph-view.d.ts

@@ -0,0 +1,94 @@
+import { type ReactNode, type Ref } from "react";
+import { type GraphEdge, type GraphNode, type GraphPayload } from "./model.js";
+import { type GraphModelLimits } from "./use-graph-model.js";
+import { type GraphStyling } from "./use-graph-styling.js";
+export interface GraphViewHandle {
+    zoomToFit: (durationMs?: number) => void;
+    centerOn: (nodeId: string, durationMs?: number) => void;
+    /** Smallest pan that brings a node into view; a no-op if it already is. */
+    reveal: (nodeId: string, durationMs?: number) => void;
+    search: (term: string) => void;
+    /**
+     * Select a node by id, or clear with `null`. Returns whether it worked:
+     * a node in the payload can still be absent from what is RENDERED, because
+     * `selectConnectedCore` caps a large graph — and a caller that assumed
+     * success would tell the user about a node that is not on screen.
+     */
+    select: (nodeId: string | null) => boolean;
+    unpinAll: () => void;
+    /**
+     * What the view is actually showing — the single honest answer to "what is
+     * on screen", which is why anything REPORTING on the graph reads it.
+     *
+     * `nodes`/`edges` are what is DRAWN: the payload capped to the connected
+     * core, then filtered by the legend. Counting the payload instead described
+     * a graph the user was not looking at, in two directions at once — the
+     * agent naming nodes the cap had dropped, and a hidden label still counted.
+     *
+     * It also exists because the view OUTLIVES the workspace it publishes to.
+     * Closing the tool panel disconnects the workspace but does not unmount this
+     * component, so on reopening, the drawer and the search box still show what
+     * they showed — while the change callbacks, which fire only on change, have
+     * nothing to report. A host reconnecting reads this instead of guessing.
+     */
+    getViewState: () => GraphViewState_Reported;
+}
+/** What {@link GraphViewHandle.getViewState} reports. */
+export interface GraphViewState_Reported {
+    selection: GraphNode | null;
+    /** A relationship can be selected too, and the drawer shows it. */
+    selectedEdge: GraphEdge | null;
+    query: string;
+    hiddenLabels: string[];
+    /** Whether the selected node is among the DRAWN nodes. False when none. */
+    selectionDrawn: boolean;
+    /** Nodes actually drawn: capped to the connected core, legend filter applied. */
+    nodes: GraphNode[];
+    /** Relationships actually drawn, re-filtered against the surviving nodes. */
+    edges: GraphEdge[];
+    /** Whether anything was dropped to get here — the cap, or a dangling edge. */
+    lossy: boolean;
+}
+export interface GraphViewProps {
+    data: GraphPayload;
+    /** `inline` is the compact card form; `full` adds the details drawer. */
+    variant?: "inline" | "full";
+    height?: number | string;
+    className?: string;
+    styling?: GraphStyling;
+    limits?: GraphModelLimits;
+    /**
+     * Called when the user asks to expand a node (double-click, or the
+     * inspector's Expand button). The host runs whatever query that means and
+     * feeds a larger payload back in through `data` — the view never queries.
+     */
+    onExpandNode?: (node: GraphNode) => void;
+    onSelectionChange?: (node: GraphNode | null) => void;
+    /** Fires when the search term changes, whoever changed it. */
+    onQueryChange?: (query: string) => void;
+    /**
+     * Fires when the legend filter changes: the labels currently switched OFF.
+     *
+     * Hosts publish it so anything REPORTING on the graph agrees with what is
+     * drawn — a hidden label's nodes and relationships are not on screen, and
+     * counting them describes a screen nobody is looking at.
+     */
+    onFilterChange?: (hiddenLabels: readonly string[]) => void;
+    /**
+     * Extra footer actions for the details drawer, rendered for the selected
+     * node. The host owns them — the view has no opinion about what "pin to
+     * chat" or "open the record" mean.
+     */
+    inspectorActions?: (node: GraphNode) => ReactNode;
+    /** Render the table instead of the canvas. Used by tests and print. */
+    forceTable?: boolean;
+    handleRef?: Ref<GraphViewHandle>;
+}
+/**
+ * An interactive, force-directed graph.
+ *
+ * Source-agnostic by construction: it takes a {@link GraphPayload} and knows
+ * nothing about where the nodes came from. Expansion is a callback, so the view
+ * never issues a query of its own.
+ */
+export declare function GraphView({ data, variant, height, className, styling, limits, onExpandNode, onSelectionChange, onQueryChange, onFilterChange, inspectorActions, forceTable, handleRef, }: GraphViewProps): import("react/jsx-runtime").JSX.Element;