npm - @iloveagents/foundry-web-graph - Versions diffs - 0.1.0 - Mend

@iloveagents/foundry-web-graph 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (68) hide show

package/LICENSE +21 -0
package/README.md +191 -0
package/dist/adapters/index.d.ts +1 -0
package/dist/adapters/index.js +1 -0
package/dist/adapters/neo4j.d.ts +52 -0
package/dist/adapters/neo4j.js +149 -0
package/dist/assistant-ui/graph-client-tools.d.ts +11 -0
package/dist/assistant-ui/graph-client-tools.js +261 -0
package/dist/assistant-ui/graph-context.d.ts +38 -0
package/dist/assistant-ui/graph-context.js +113 -0
package/dist/assistant-ui/graph-panel-content.d.ts +45 -0
package/dist/assistant-ui/graph-panel-content.js +28 -0
package/dist/assistant-ui/graph-panel.d.ts +11 -0
package/dist/assistant-ui/graph-panel.js +121 -0
package/dist/assistant-ui/graph-provenance.d.ts +17 -0
package/dist/assistant-ui/graph-provenance.js +31 -0
package/dist/assistant-ui/graph-result-seeder.d.ts +73 -0
package/dist/assistant-ui/graph-result-seeder.js +157 -0
package/dist/assistant-ui/graph-tool-registry.d.ts +25 -0
package/dist/assistant-ui/graph-tool-registry.js +15 -0
package/dist/assistant-ui/graph-tool-ui.d.ts +54 -0
package/dist/assistant-ui/graph-tool-ui.js +77 -0
package/dist/assistant-ui/index.d.ts +17 -0
package/dist/assistant-ui/index.js +17 -0
package/dist/assistant-ui/merge-into-panel.d.ts +21 -0
package/dist/assistant-ui/merge-into-panel.js +72 -0
package/dist/assistant-ui/register-graph-panel.d.ts +8 -0
package/dist/assistant-ui/register-graph-panel.js +18 -0
package/dist/caption-placement.d.ts +119 -0
package/dist/caption-placement.js +146 -0
package/dist/graph-canvas-paint.d.ts +90 -0
package/dist/graph-canvas-paint.js +186 -0
package/dist/graph-canvas.d.ts +49 -0
package/dist/graph-canvas.js +533 -0
package/dist/graph-inspector.d.ts +42 -0
package/dist/graph-inspector.js +106 -0
package/dist/graph-legend.d.ts +19 -0
package/dist/graph-legend.js +20 -0
package/dist/graph-notice.d.ts +19 -0
package/dist/graph-notice.js +30 -0
package/dist/graph-table.d.ts +28 -0
package/dist/graph-table.js +57 -0
package/dist/graph-toolbar.d.ts +22 -0
package/dist/graph-toolbar.js +8 -0
package/dist/graph-tooltip.d.ts +4 -0
package/dist/graph-tooltip.js +55 -0
package/dist/graph-view.d.ts +94 -0
package/dist/graph-view.js +338 -0
package/dist/graph-workspace.d.ts +55 -0
package/dist/graph-workspace.js +100 -0
package/dist/index.d.ts +21 -0
package/dist/index.js +21 -0
package/dist/model.d.ts +206 -0
package/dist/model.js +369 -0
package/dist/styles.css +97 -0
package/dist/theme.d.ts +36 -0
package/dist/theme.js +83 -0
package/dist/use-element-size.d.ts +13 -0
package/dist/use-element-size.js +32 -0
package/dist/use-graph-model.d.ts +101 -0
package/dist/use-graph-model.js +164 -0
package/dist/use-graph-styling.d.ts +55 -0
package/dist/use-graph-styling.js +156 -0
package/dist/use-graph-theme.d.ts +11 -0
package/dist/use-graph-theme.js +54 -0
package/dist/use-graph-view-state.d.ts +42 -0
package/dist/use-graph-view-state.js +145 -0
package/package.json +83 -0

package/dist/use-graph-theme.js ADDED Viewed

@@ -0,0 +1,54 @@
+import { useEffect, useState } from "react";
+import { FALLBACK_THEME, resolveGraphTheme } from "./theme.js";
+const sameTheme = (a, b) => a.foreground === b.foreground &&
+    a.mutedForeground === b.mutedForeground &&
+    a.background === b.background &&
+    a.border === b.border &&
+    a.ring === b.ring &&
+    a.palette.length === b.palette.length &&
+    a.palette.every((colour, index) => colour === b.palette[index]);
+/**
+ * Keep {@link GraphTheme} in sync with the DOM.
+ *
+ * Re-resolves when the `class`, `data-theme` or `style` attribute changes
+ * anywhere up the tree — between them that is how every theme switcher in this
+ * stack signals a flip (Tailwind's `.dark` class, an explicit `data-theme`, or
+ * a runtime layer writing variables inline). Watching the element itself is not
+ * enough: the class usually lands on `<html>`, far above.
+ */
+export function useGraphTheme(element) {
+    const [theme, setTheme] = useState(FALLBACK_THEME);
+    useEffect(() => {
+        if (!element)
+            return;
+        // Keep the previous object when nothing resolved differently. `theme` is a
+        // dependency of the canvas painters and of `styleMap`, so a fresh object
+        // per mutation is a re-render and a full repaint — and `style` mutations
+        // are not rare: an ancestor's inline width changes on every frame of a
+        // panel drag-resize.
+        const sync = () => setTheme((previous) => {
+            const next = resolveGraphTheme(element);
+            return sameTheme(previous, next) ? previous : next;
+        });
+        sync();
+        if (typeof MutationObserver === "undefined")
+            return;
+        const observer = new MutationObserver(sync);
+        // Observe every ancestor: the theme class can sit on <html>, on a
+        // ThemeScope wrapper, or on the container itself.
+        //
+        // `style` is in the filter because a RUNTIME theme layer never touches a
+        // class. `ThemeRuntimeProvider` publishes its variables with
+        // `root.style.setProperty(...)`, so switching one changed the DOM while
+        // the canvas went on painting the previous palette — until some unrelated
+        // class or `data-theme` mutation happened to wake this up.
+        for (let node = element; node; node = node.parentElement) {
+            observer.observe(node, {
+                attributes: true,
+                attributeFilter: ["class", "data-theme", "style"],
+            });
+        }
+        return () => observer.disconnect();
+    }, [element]);
+    return theme;
+}

package/dist/use-graph-view-state.d.ts ADDED Viewed

@@ -0,0 +1,42 @@
+import { type GraphEdge, type GraphNode, type GraphPayload } from "./model.js";
+/** What the user currently has selected. `null` when nothing is selected. */
+export interface GraphSelection {
+    node: GraphNode | null;
+    edge: GraphEdge | null;
+}
+export interface GraphViewState {
+    selection: GraphSelection;
+    selectNode: (node: GraphNode | null) => void;
+    selectEdge: (edge: GraphEdge | null) => void;
+    clearSelection: () => void;
+    hoveredId: string | null;
+    setHoveredId: (id: string | null) => void;
+    /** Lowercased search term. Empty string = no search active. */
+    query: string;
+    setQuery: (value: string) => void;
+    /** Ids matching the current query. Empty set when the query is empty. */
+    matchedIds: Set<string>;
+    /** Labels the user has hidden by clicking the legend. */
+    hiddenLabels: Set<string>;
+    toggleLabel: (label: string) => void;
+    showAllLabels: () => void;
+    /** Ids the user pinned by dragging. Pinned nodes hold their position. */
+    pinnedIds: Set<string>;
+    togglePinned: (id: string) => void;
+    unpinAll: () => void;
+}
+/**
+ * Search across caption AND every property value.
+ *
+ * Matching only the caption looks broken the moment someone searches for an
+ * id, an email, or a status that the caption rule did not pick — which is most
+ * of what people actually search a graph for.
+ */
+declare function matchNodes(nodes: GraphNode[], query: string, captionOf: (n: GraphNode) => string): Set<string>;
+/**
+ * All the interaction state a graph view carries: selection, hover, search,
+ * legend filtering and pinning. Kept out of the view component so the view
+ * stays a renderer and this stays unit-testable without a canvas.
+ */
+export declare function useGraphViewState(payload: GraphPayload, captionOf: (node: GraphNode) => string): GraphViewState;
+export { matchNodes as __matchNodesForTest };

package/dist/use-graph-view-state.js ADDED Viewed

@@ -0,0 +1,145 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { deepEqual } from "./model.js";
+const EMPTY_SELECTION = { node: null, edge: null };
+/**
+ * Search across caption AND every property value.
+ *
+ * Matching only the caption looks broken the moment someone searches for an
+ * id, an email, or a status that the caption rule did not pick — which is most
+ * of what people actually search a graph for.
+ */
+function matchNodes(nodes, query, captionOf) {
+    const needle = query.trim().toLowerCase();
+    if (needle.length === 0)
+        return new Set();
+    const out = new Set();
+    for (const node of nodes) {
+        if (captionOf(node).toLowerCase().includes(needle)) {
+            out.add(node.id);
+            continue;
+        }
+        if (node.labels?.some((l) => l.toLowerCase().includes(needle))) {
+            out.add(node.id);
+            continue;
+        }
+        for (const value of Object.values(node.properties ?? {})) {
+            if (value == null)
+                continue;
+            if (String(value).toLowerCase().includes(needle)) {
+                out.add(node.id);
+                break;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * All the interaction state a graph view carries: selection, hover, search,
+ * legend filtering and pinning. Kept out of the view component so the view
+ * stays a renderer and this stays unit-testable without a canvas.
+ */
+export function useGraphViewState(payload, captionOf) {
+    const [selection, setSelection] = useState(EMPTY_SELECTION);
+    const [hoveredId, setHoveredId] = useState(null);
+    const [query, setQuery] = useState("");
+    const [hiddenLabels, setHiddenLabels] = useState(() => new Set());
+    const [pinnedIds, setPinnedIds] = useState(() => new Set());
+    const matchedIds = useMemo(() => matchNodes(payload.nodes, query, captionOf), [payload.nodes, query, captionOf]);
+    /**
+     * A selection outlives its node otherwise.
+     *
+     * `graph_show` replacing an open graph reuses the renderer deliberately —
+     * that is what makes a refined query read as a change — but the drawer would
+     * go on describing a node the canvas no longer contains, with an Expand
+     * button that queries something nobody can see.
+     *
+     * Only DROPS; it never swaps in the equivalent node from the new payload.
+     * Hosts pass `data` as a fresh object on many renders, and replacing the
+     * selection with an equal-but-different object every time is a render loop.
+     */
+    useEffect(() => {
+        setSelection((prev) => {
+            if (prev.node && !payload.nodes.some((node) => node.id === prev.node?.id)) {
+                return EMPTY_SELECTION;
+            }
+            if (prev.edge) {
+                const fresh = payload.edges.find((edge) => edge.id === prev.edge?.id);
+                if (!fresh)
+                    return EMPTY_SELECTION;
+                // Edges, unlike nodes, are REBUILT on every payload —
+                // `reconcileGraphModel` reuses node objects to keep their positions
+                // but has no such reason for links. So a merge that rewrote this
+                // relationship's type or properties left the drawer describing the
+                // version before the write, with no way to notice short of
+                // reselecting it. Swapped only when the content actually differs, so
+                // a host handing us a fresh `data` object on every render cannot turn
+                // this into a loop.
+                if (!deepEqual(fresh, prev.edge)) {
+                    return { node: null, edge: fresh };
+                }
+            }
+            return prev;
+        });
+        // Pins are ids, and an id outlives the node it named. `graph_show`
+        // replacing the graph left the pin in the set: the toolbar counted a pin nothing shows, Unpin
+        // All had something to clear that was not there, and — the part that is
+        // not merely cosmetic — a LATER graph containing the same id got that
+        // node frozen on arrival, by a pin the user made for a different graph.
+        setPinnedIds((prev) => {
+            if (prev.size === 0)
+                return prev;
+            const present = new Set(payload.nodes.map((node) => node.id));
+            const next = new Set([...prev].filter((id) => present.has(id)));
+            // Same set, same object: this runs on every payload, and a fresh Set
+            // each time would re-run every consumer that depends on it.
+            return next.size === prev.size ? prev : next;
+        });
+    }, [payload]);
+    const selectNode = useCallback((node) => {
+        setSelection({ node, edge: null });
+    }, []);
+    const selectEdge = useCallback((edge) => {
+        setSelection({ node: null, edge });
+    }, []);
+    const clearSelection = useCallback(() => setSelection(EMPTY_SELECTION), []);
+    const toggleLabel = useCallback((label) => {
+        setHiddenLabels((prev) => {
+            const next = new Set(prev);
+            if (next.has(label))
+                next.delete(label);
+            else
+                next.add(label);
+            return next;
+        });
+    }, []);
+    const showAllLabels = useCallback(() => setHiddenLabels(new Set()), []);
+    const togglePinned = useCallback((id) => {
+        setPinnedIds((prev) => {
+            const next = new Set(prev);
+            if (next.has(id))
+                next.delete(id);
+            else
+                next.add(id);
+            return next;
+        });
+    }, []);
+    const unpinAll = useCallback(() => setPinnedIds(new Set()), []);
+    return {
+        selection,
+        selectNode,
+        selectEdge,
+        clearSelection,
+        hoveredId,
+        setHoveredId,
+        query,
+        setQuery,
+        matchedIds,
+        hiddenLabels,
+        toggleLabel,
+        showAllLabels,
+        pinnedIds,
+        togglePinned,
+        unpinAll,
+    };
+}
+export { matchNodes as __matchNodesForTest };

package/package.json ADDED Viewed

@@ -0,0 +1,83 @@
+{
+  "name": "@iloveagents/foundry-web-graph",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Graph visualization for Foundry UI — a Bloom-like force-directed graph view, a source-agnostic graph payload contract, and an optional assistant-ui tool card + panel renderer.",
+  "keywords": [
+    "react",
+    "graph",
+    "visualization",
+    "force-directed",
+    "neo4j",
+    "cypher",
+    "foundry-ui",
+    "assistant-ui"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iLoveAgents/foundry-ui.git",
+    "directory": "packages/web-graph"
+  },
+  "homepage": "https://github.com/iLoveAgents/foundry-ui/tree/main/packages/web-graph#readme",
+  "bugs": "https://github.com/iLoveAgents/foundry-ui/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./adapters/neo4j": {
+      "types": "./dist/adapters/index.d.ts",
+      "import": "./dist/adapters/index.js"
+    },
+    "./assistant-ui": {
+      "types": "./dist/assistant-ui/index.d.ts",
+      "import": "./dist/assistant-ui/index.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "lucide-react": ">=0.400.0",
+    "@assistant-ui/react": "^0.15.1",
+    "zustand": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@assistant-ui/react": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "react-force-graph-2d": "^1.29.1",
+    "@iloveagents/foundry-agent": "^0.24.0",
+    "@iloveagents/foundry-web-ui": "^0.24.0",
+    "@iloveagents/foundry-web-primitives": "^0.24.0"
+  },
+  "devDependencies": {
+    "@assistant-ui/react": "^0.15.1",
+    "@types/react": "^19.2.2",
+    "jsdom": "^28.1.0",
+    "lucide-react": ">=0.400.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.4",
+    "zustand": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/fix-dts-extensions.mjs dist && cp src/styles.css dist/styles.css",
+    "test:unit": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}