@petrarca/sonnet-graph 0.6.0 → 0.8.0

package/README.md

@@ -1,35 +1,33 @@
 # @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.
-
----
+Property-graph visualization for the Petrarca Sonnet component library. The
+state and the transformations are renderer-independent; Cytoscape and Reagraph
+are two implementations of the drawing surface, switched at runtime
+([ADR-0004](../../docs/adr/0004-graph-rendering-is-renderer-agnostic.md)).
+
+## What it provides
+
+**A viewer.** `GraphVisualizer` draws the graph through the active renderer,
+with selection, focus mode, hide and show, and expansion.
+`GraphRendererProvider` holds the choice and reports changes so a host can
+persist it; `ActionPanel` shows the selected element and its actions.
+
+**An accessible list.** Both renderers draw outside the DOM, so `GraphA11yList`
+mirrors the selectable elements as buttons driving the same selection store,
+`sr-only` by default and displayable as an outline panel.
+
+**Stores and transforms.** `createGraphDataStore`, `createGraphFilterStore`,
+`createGraphExplorationStore`, `createSelectionStore`, `createGraphFocusStore`
+and `createActionPanelStore`, plus `enrichNodes`, `enrichEdges`,
+`normalizeGraph` and the palette builders. The consumer creates the stores, so
+two graph views in one application are isolated.
+
+**Two editors.** `GraphModelEditor` authors the metamodel -- node types, edge
+types, relations -- as a graph over a controlled `value`. The `graph-edit`
+surface (`GraphEditToolbar`, `NodeFormSheet`, `EdgeFormSheet`,
+`DeleteNodeDialog`) edits the instance data, writing through a
+`GraphMutationPort` you implement and reading schemas from a
+`GraphSchemaProvider` you supply. Nothing here does I/O of its own.
 
 ## Install
 
@@ -37,108 +35,81 @@ preparing raw graph data before passing it to stores.
 pnpm add @petrarca/sonnet-graph
 ```
 
-### Required peer dependencies
-
-```bash
-pnpm add react@">=19" react-dom@">=19"
-```
+| Peer | Range | Needed for |
+|---|---|---|
+| `react`, `react-dom` | `>=19` | Everything |
+| `lucide-react` | `>=0.300` | Toolbar and panel icons |
+| `cytoscape` | `>=3` | The Cytoscape renderer |
+| `cytoscape-cola`, `cytoscape-cise`, `cytoscape-cxtmenu`, `cytoscape-dagre`, `cytoscape-elk`, `cytoscape-fcose`, `cytoscape-klay` | `>=1` to `>=3` | Cytoscape layouts and the context menu |
+| `reagraph` | `>=4` | The Reagraph renderer |
 
-### Renderer peer dependencies
+**The renderer peers are declared optional, and are not optional in practice.**
+Both renderers and all seven Cytoscape plugins are statically imported at
+module scope, so `peerDependenciesMeta.optional` only stops your package manager
+warning at install time. Omit any one of the nine and importing
+`GraphVisualizer` fails; there is no supported subset.
 
-Install only the renderers you use:
+The plugin specifiers must also resolve from your own `node_modules`. If your
+bundler resolves this package from anywhere else -- a linked checkout, a build
+output outside the project, any alias pointing elsewhere -- resolution starts
+from that location and there is nothing to find. Alias all seven plugin
+specifiers to your own `node_modules`; a partial list fails on whichever one was
+left out, when the renderer first mounts. The configuration is in
+[getting started](docs/usage/getting-started.md).
 
-```bash
-pnpm add cytoscape          # Cytoscape.js renderer
-pnpm add reagraph           # Reagraph (3D/WebGL) renderer
-```
+## Usage
 
-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
+Create the stores once, never in a render body, and give the container a height.
 
 ```tsx
 import {
-  GraphVisualizer,
-  ActionPanel,
-  GraphRendererProvider,
-  GraphStoresContext,
-  createGraphDataStore,
-  createGraphFilterStore,
-  createGraphExplorationStore,
-  createSelectionStore,
-  createGraphFocusStore,
-  enrichNodes,
-  enrichEdges,
-  buildColorPalette,
-  type RawGraphNode,
-  type RawGraphEdge,
-  type WorkspaceStores,
+  GraphRendererProvider, GraphStoresContext, GraphVisualizer,
+  createGraphDataStore, createGraphExplorationStore, createGraphFilterStore,
+  createGraphFocusStore, createSelectionStore, type WorkspaceStores,
 } from "@petrarca/sonnet-graph";
 
-// Create stores once (e.g. in a context provider)
+const graphData = createGraphDataStore();
+const graphFilter = createGraphFilterStore();
+const selection = createSelectionStore();
+
+// WorkspaceStores has exactly these four members. The focus store is a
+// dependency of the exploration store, which requires its deps object.
 const stores: WorkspaceStores = {
-  graphData:        createGraphDataStore(),
-  graphFilter:      createGraphFilterStore(),
-  graphExploration: createGraphExplorationStore(),
-  selection:        createSelectionStore(),
-  graphFocus:       createGraphFocusStore(),
+  graphData,
+  graphFilter,
+  selection,
+  graphExploration: createGraphExplorationStore({
+    graphData,
+    selection,
+    graphFilter,
+    graphFocus: createGraphFocusStore(),
+    expandNode: async () => ({ nodes: [], edges: [], has_more: false }),
+    getNodes: async () => [],
+  }),
 };
 
-// Render
-function MyGraph() {
-  return (
-    <GraphStoresContext.Provider value={stores}>
-      <GraphRendererProvider defaultRenderer="cytoscape">
-        <div style={{ display: "flex", height: 600 }}>
-          <GraphVisualizer />
-          <ActionPanel />
-        </div>
-      </GraphRendererProvider>
-    </GraphStoresContext.Provider>
-  );
-}
+const GraphView = () => (
+  <GraphStoresContext.Provider value={stores}>
+    <GraphRendererProvider defaultRenderer="cytoscape">
+      <div className="h-[600px] w-full">
+        <GraphVisualizer />
+      </div>
+    </GraphRendererProvider>
+  </GraphStoresContext.Provider>
+);
 ```
 
----
+## Documentation
+
+- [Usage guides](docs/usage/index.md) -- getting started,
+  [stores and data](docs/usage/stores-and-data.md),
+  [exploration and selection](docs/usage/exploration-and-selection.md),
+  [accessibility](docs/usage/accessibility.md), and both editors:
+  [model](docs/usage/model-editing.md) and
+  [instance](docs/usage/instance-editing.md).
+- [Design docs](docs/design/index.md) -- the renderer boundary and both editors.
+- [Workspace documentation](../../docs/README.md) -- how the packages layer.
 
 ## License
 
-See [LICENSE.md](../../LICENSE.md).
+Apache 2.0. See [LICENSE.md](../../LICENSE.md).