@petrarca/sonnet-graph 0.3.0 → 0.4.1

package/README.md

@@ -0,0 +1,144 @@
+# @petrarca/sonnet-graph
+
+Renderer-agnostic property graph visualization, exploration, and enrichment
+for the Petrarca Sonnet component library.
+
+## What's included
+
+**GraphVisualizer** — Main visualization component. Renders a property graph
+using the active renderer (Cytoscape or Reagraph). Supports node/edge
+selection, focus mode, hide/show, and graph expansion.
+
+**ActionPanel** — Side panel showing selected node/edge details and graph
+exploration actions.
+
+**GraphA11yList** — Accessible DOM mirror of the graph's selectable elements.
+Cytoscape (canvas) and Reagraph (WebGL) draw nodes/edges outside the DOM, so they
+are invisible to screen readers, keyboard users, and DOM automation; this renders
+a virtualized list of node/edge `<button>`s that drive the same selection store
+the canvas reads. `sr-only` by default (real apps); pass `visible` for an on-screen
+outline panel.
+
+**GraphRendererProvider** — Context provider that selects the active renderer
+(`"cytoscape"` or `"reagraph"`).
+
+**Store factories** — Create the Zustand stores the graph components need:
+`createGraphDataStore`, `createGraphFilterStore`, `createGraphExplorationStore`,
+`createSelectionStore`, `createGraphFocusStore`.
+
+**Graph utilities** — `enrichNodes`, `enrichEdges`, `buildColorPalette` for
+preparing raw graph data before passing it to stores.
+
+---
+
+## Install
+
+```bash
+pnpm add @petrarca/sonnet-graph
+```
+
+### Required peer dependencies
+
+```bash
+pnpm add react@">=19" react-dom@">=19"
+```
+
+### Renderer peer dependencies
+
+Install only the renderers you use:
+
+```bash
+pnpm add cytoscape          # Cytoscape.js renderer
+pnpm add reagraph           # Reagraph (3D/WebGL) renderer
+```
+
+If you use `@petrarca/sonnet-playground` (which includes the graph demo page),
+both `cytoscape` and `reagraph` are required even if your app only uses one renderer.
+
+### Cytoscape layout plugins (optional)
+
+Install the layout algorithms you need. All are optional — the graph works
+without them but with fewer layout options:
+
+```bash
+pnpm add cytoscape-fcose    # Force-directed, compound graph
+pnpm add cytoscape-cola     # Constraint-based
+pnpm add cytoscape-dagre    # DAG / hierarchical
+pnpm add cytoscape-elk      # Eclipse Layout Kernel
+pnpm add cytoscape-cise     # Circular layout
+pnpm add cytoscape-klay     # KLay hierarchical
+pnpm add cytoscape-cxtmenu  # Context menu extension
+```
+
+### Local development with SONNET_UI_LOCAL=1
+
+When resolving `@petrarca/sonnet-graph` from the local dist (via Vite aliases),
+the Cytoscape plugins must also be aliased to the consumer's `node_modules` —
+Vite cannot find them relative to the dist file. Add to your `sonnet-aliases.ts`:
+
+```ts
+const nm = path.resolve(baseDir, "node_modules");
+// ...
+"cytoscape-fcose": path.resolve(nm, "cytoscape-fcose"),
+"cytoscape-cola":  path.resolve(nm, "cytoscape-cola"),
+"cytoscape-dagre": path.resolve(nm, "cytoscape-dagre"),
+"cytoscape-elk":   path.resolve(nm, "cytoscape-elk"),
+"cytoscape-cise":  path.resolve(nm, "cytoscape-cise"),
+"cytoscape-klay":  path.resolve(nm, "cytoscape-klay"),
+"cytoscape-cxtmenu": path.resolve(nm, "cytoscape-cxtmenu"),
+```
+
+See `sonnet-ui-starter/sonnet-aliases.ts` for a complete reference implementation.
+
+---
+
+## Basic usage
+
+```tsx
+import {
+  GraphVisualizer,
+  ActionPanel,
+  GraphRendererProvider,
+  GraphStoresContext,
+  createGraphDataStore,
+  createGraphFilterStore,
+  createGraphExplorationStore,
+  createSelectionStore,
+  createGraphFocusStore,
+  enrichNodes,
+  enrichEdges,
+  buildColorPalette,
+  type RawGraphNode,
+  type RawGraphEdge,
+  type WorkspaceStores,
+} from "@petrarca/sonnet-graph";
+
+// Create stores once (e.g. in a context provider)
+const stores: WorkspaceStores = {
+  graphData:        createGraphDataStore(),
+  graphFilter:      createGraphFilterStore(),
+  graphExploration: createGraphExplorationStore(),
+  selection:        createSelectionStore(),
+  graphFocus:       createGraphFocusStore(),
+};
+
+// Render
+function MyGraph() {
+  return (
+    <GraphStoresContext.Provider value={stores}>
+      <GraphRendererProvider defaultRenderer="cytoscape">
+        <div style={{ display: "flex", height: 600 }}>
+          <GraphVisualizer />
+          <ActionPanel />
+        </div>
+      </GraphRendererProvider>
+    </GraphStoresContext.Provider>
+  );
+}
+```
+
+---
+
+## License
+
+See [LICENSE.md](../../LICENSE.md).

package/dist/index.d.ts

@@ -494,6 +494,18 @@ declare const useGraphFocus: zustand.UseBoundStore<zustand.StoreApi<GraphFocusSt
  * - GraphFilter (label filters)
  */
 
+/** Options for bounded node expansion. */
+interface ExpandOptions {
+    direction?: "both" | "out" | "in";
+    relTypes?: string[];
+    limit?: number;
+}
+/** Result shape returned by the expand backend call. */
+interface ExpandResult {
+    nodes: RawGraphNode[];
+    edges: RawGraphEdge[];
+    has_more: boolean;
+}
 /**
  * Store dependencies for GraphExploration.
  * Allows workspace-specific or global store injection.
@@ -503,10 +515,8 @@ interface GraphExplorationDeps {
     selection: UseBoundStore<StoreApi<SelectionStore>>;
     graphFocus: UseBoundStore<StoreApi<GraphFocusStore>>;
     graphFilter: UseBoundStore<StoreApi<GraphFilterStore>>;
-    expandNode: (id: number) => Promise<{
-        nodes: RawGraphNode[];
-        edges: RawGraphEdge[];
-    }>;
+    expandNode: (id: number, options?: ExpandOptions) => Promise<ExpandResult>;
+    getNodeEdgeTypes?: (id: number) => Promise<string[]>;
     getNodes: (ids: number[]) => Promise<RawGraphNode[]>;
     getLabelDisplayMap?: () => LabelDisplayMap;
 }
@@ -614,9 +624,10 @@ interface GraphExplorationStore {
      * Expand a node by fetching connected nodes/edges from backend
      * and merging them into the graph data.
      * @param nodeId - ID of the node to expand
+     * @param options - Optional expand parameters (direction, relTypes, limit)
      * @returns Promise that resolves when expansion is complete
      */
-    expandNode: (nodeId: string) => Promise<void>;
+    expandNode: (nodeId: string, options?: ExpandOptions) => Promise<void>;
     /**
      * Add a node to the graph by ID.
      * If the node already exists in the graph, just focuses it (if autoFocus=true).
@@ -834,8 +845,10 @@ interface GraphVisualizerProps {
     onCopyNode?: (node: VisualGraphNode) => void;
     /** Extra toolbar content (e.g. clipboard UI) injected into the renderer toolbar. */
     extraToolbarContent?: ReactNode;
+    /** Fetch distinct edge types for a node (for expand options panel). */
+    getNodeEdgeTypes?: (id: number) => Promise<string[]>;
 }
-declare function GraphVisualizer({ onCopyNode, extraToolbarContent, }: GraphVisualizerProps): react_jsx_runtime.JSX.Element;
+declare function GraphVisualizer({ onCopyNode, extraToolbarContent, getNodeEdgeTypes, }: GraphVisualizerProps): react_jsx_runtime.JSX.Element;
 
 interface ActionPanelProps {
     /** Optional actions rendered at the top of the panel (e.g. CRUD buttons) */
@@ -855,4 +868,15 @@ declare function EdgeInfoCard({ edge }: Props): react_jsx_runtime.JSX.Element;
 
 declare function Overview(): react_jsx_runtime.JSX.Element | null;
 
-export { ActionPanel, type ActionPanelState, type ActionPanelStore, type ColorPalette, EMPTY_NORMALIZED, EdgeInfoCard, type EdgeVisual, type GraphDataHook, type GraphDataStore, type GraphDisplayConfig, type GraphExplorationDeps, type GraphExplorationStore, type GraphFilterStore, type GraphFocusAction, type GraphFocusStore, type GraphProperties, type GraphProperty, type GraphRenderer, GraphRendererProvider, type GraphStatistics, type WorkspaceStores as GraphStoreBundle, GraphStoresContext, GraphVisualizer, type GraphVisualizerProps, type LabelDisplayMap, type LiveGraphDataResult, NodeInfoCard, type NodeVisual, type NormalizedGraph, Overview, type RawGraphEdge, type RawGraphNode, type SelectionStore, type StoreFactory, type VisualGraphEdge, type VisualGraphNode, type VisualGraphNormalized, type WorkspaceStores, buildColorPalette, buildColorPaletteFromNodes, createActionPanelStore, createGraphDataStore, createGraphExplorationStore, createGraphFilterStore, createGraphFocusStore, createSelectionStore, enrichEdge, enrichEdges, enrichNode, enrichNodes, extractDisplayLabel, isRawGraphNode, isVisualEdge, isVisualNode, normalizeGraph, toCytoscapeEdge, toCytoscapeNode, toReagraphEdge, toReagraphNode, useActionPanelStore, useCytoscapeData, useGraphFocus, useGraphRenderer, useLiveGraphData, useReagraphData, useWorkspaceGraphData, useWorkspaceGraphExploration, useWorkspaceGraphFilter, useWorkspaceSelection };
+interface GraphA11yListProps {
+    /** Render on-screen instead of visually-hidden (still a11y-present). */
+    visible?: boolean;
+    /** Estimated row height in px (virtualization). Default 28. */
+    rowHeight?: number;
+    /** Max viewport height in px when visible. Default 320. */
+    maxHeight?: number;
+    className?: string;
+}
+declare function GraphA11yList({ visible, rowHeight, maxHeight, className, }: GraphA11yListProps): react_jsx_runtime.JSX.Element;
+
+export { ActionPanel, type ActionPanelState, type ActionPanelStore, type ColorPalette, EMPTY_NORMALIZED, EdgeInfoCard, type EdgeVisual, type ExpandOptions, type ExpandResult, GraphA11yList, type GraphA11yListProps, type GraphDataHook, type GraphDataStore, type GraphDisplayConfig, type GraphExplorationDeps, type GraphExplorationStore, type GraphFilterStore, type GraphFocusAction, type GraphFocusStore, type GraphProperties, type GraphProperty, type GraphRenderer, GraphRendererProvider, type GraphStatistics, type WorkspaceStores as GraphStoreBundle, GraphStoresContext, GraphVisualizer, type GraphVisualizerProps, type LabelDisplayMap, type LiveGraphDataResult, NodeInfoCard, type NodeVisual, type NormalizedGraph, Overview, type RawGraphEdge, type RawGraphNode, type SelectionStore, type StoreFactory, type VisualGraphEdge, type VisualGraphNode, type VisualGraphNormalized, type WorkspaceStores, buildColorPalette, buildColorPaletteFromNodes, createActionPanelStore, createGraphDataStore, createGraphExplorationStore, createGraphFilterStore, createGraphFocusStore, createSelectionStore, enrichEdge, enrichEdges, enrichNode, enrichNodes, extractDisplayLabel, isRawGraphNode, isVisualEdge, isVisualNode, normalizeGraph, toCytoscapeEdge, toCytoscapeNode, toReagraphEdge, toReagraphNode, useActionPanelStore, useCytoscapeData, useGraphFocus, useGraphRenderer, useLiveGraphData, useReagraphData, useWorkspaceGraphData, useWorkspaceGraphExploration, useWorkspaceGraphFilter, useWorkspaceSelection };