@nesso-how/graph 0.1.0-alpha.33 → 0.1.0-alpha.35

package/README.md

@@ -1,13 +1,15 @@
 # @nesso-how/graph
 
-Embeddable read-only Nesso knowledge graph React component, built on [React Flow](https://reactflow.dev).
+Embeddable Nesso knowledge graph React component, built on [React Flow](https://reactflow.dev). Read-only by default; enable drag, connect, and selection when you need an interactive canvas.
 
 ## Install
 
 ```bash
-npm install @nesso-how/graph
+npm install @nesso-how/graph @xyflow/react react react-dom
 ```
 
+`@xyflow/react`, `react`, and `react-dom` are peer dependencies — match the ranges in this package's `peerDependencies`.
+
 ## Usage
 
 ```tsx
@@ -21,27 +23,29 @@ import '@xyflow/react/dist/style.css'
 />
 ```
 
-`nodes`/`edges` (or a full `graph: NessoGraphFile`) render read-only by default —
-no drag, connect, or selection. Default `nodeTypes`/`edgeTypes` use `ConceptNode` and
-`NessoEdge` from this package (display settings via `GraphDisplayContext`).
+Pass a full `NessoGraphDocument` (from `@nesso-how/vocab-learning`) via `graph` instead of separate `nodes`/`edges`:
+
+```tsx
+import { deserialize } from '@nesso-how/vocab-learning'
+
+const doc = deserialize(json)
+;<NessoGraph graph={doc} style={{ width: '100%', height: 400 }} />
+```
+
+Or build React Flow props yourself with `documentToRenderGraph(doc)` when you need the raw `nodes`/`edges` arrays.
+
+`nodes`/`edges` render read-only by default — no drag, connect, or selection. Default `nodeTypes`/`edgeTypes` use `ConceptNode` and `NessoEdge` from this package (display settings via `GraphDisplayContext`).
+
+Pass `display`/`palette` to control categories, glyphs, and curves. Use `categoryColorMode: 'css'` when `--cat-*` CSS variables are set on the page (the main app); embeds default to `palette` (hex from `PALETTES` in `@nesso-how/vocab-learning`). Optional `getRelationLabel` and `isItemSelected` customize labels and selection. Pass any other [`ReactFlow`](https://reactflow.dev/api-reference/react-flow) prop through `reactFlowProps`.
 
-Pass `display`/`palette` to control categories, glyphs, and curves. Use
-`categoryColorMode: 'css'` when `--cat-*` CSS variables are set on the page (the main
-app); embeds default to `palette` (hex from `PALETTES`). Optional `getRelationLabel`
-and `isItemSelected` customize labels and selection. Pass any other
-[`ReactFlow`](https://reactflow.dev/api-reference/react-flow) prop through `reactFlowProps`.
+Full guide: [Embedding graphs](https://nesso.how/docs/guides/embedding-graphs/).
 
 ### Interactivity
 
-Turn on `nodesDraggable`/`nodesConnectable`/`elementsSelectable` as needed. How you
-provide nodes determines who owns their state:
+Turn on `nodesDraggable`/`nodesConnectable`/`elementsSelectable` as needed. How you provide nodes determines who owns their state:
 
-- `nodes`/`edges` — _controlled_: you own the state and must also pass
-  `onNodesChange`/`onEdgesChange`/`onConnect` to apply updates (e.g. the main app,
-  where positions live in its own store).
-- `defaultNodes`/`defaultEdges` — _uncontrolled_: React Flow seeds its internal
-  state once and manages drag/connect/selection itself — no wiring needed, the
-  right choice for decorative or one-off embeds.
+- `nodes`/`edges` — _controlled_: you own the state and must also pass `onNodesChange`/`onEdgesChange`/`onConnect` to apply updates (e.g. the main app, where positions live in its own store).
+- `defaultNodes`/`defaultEdges` — _uncontrolled_: React Flow seeds its internal state once and manages drag/connect/selection itself — no wiring needed, the right choice for decorative or one-off embeds.
 
 ```tsx
 <NessoGraph

package/dist/ConceptNode.d.ts

@@ -1,5 +1,5 @@
 import type { Node, NodeProps } from '@xyflow/react';
-import type { ConceptNodeData } from '@nesso-how/types';
+import type { ConceptNodeData } from '@nesso-how/vocab-learning';
 type ConceptNodeType = Node<ConceptNodeData>;
 export declare function ConceptNode({ data, selected }: NodeProps<ConceptNodeType>): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/GlyphSVG.d.ts

@@ -1,9 +1,9 @@
-import type { GlyphKind } from '@nesso-how/relation-types';
+import type { GlyphKind } from '@nesso-how/vocab-learning';
 interface Props {
     kind: GlyphKind;
     color?: string;
     size?: number;
 }
-/** Renders a relation glyph from `@nesso-how/relation-types`' framework-agnostic SVG data. */
+/** Renders a relation glyph from `@nesso-how/vocab-learning`' framework-agnostic SVG data. */
 export declare function GlyphSVG({ kind, color, size }: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/GlyphSVG.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 // SPDX-License-Identifier: MIT
-import { GLYPH_PATHS } from '@nesso-how/relation-types';
-/** Renders a relation glyph from `@nesso-how/relation-types`' framework-agnostic SVG data. */
+import { GLYPH_PATHS } from '@nesso-how/vocab-learning';
+/** Renders a relation glyph from `@nesso-how/vocab-learning`' framework-agnostic SVG data. */
 export function GlyphSVG({ kind, color = 'currentColor', size = 14 }) {
     return (_jsx("svg", { width: size, height: size, viewBox: "0 0 14 14", style: { color }, strokeWidth: 1.4, strokeLinecap: "round", strokeLinejoin: "round", fill: "none", stroke: "currentColor", dangerouslySetInnerHTML: { __html: GLYPH_PATHS[kind] } }));
 }

package/dist/NessoEdge.d.ts

@@ -1,5 +1,5 @@
 import type { Edge, EdgeProps } from '@xyflow/react';
-import type { NessoEdgeData } from '@nesso-how/types';
+import type { NessoEdgeData } from './display.js';
 type NessoFlowEdge = Edge<NessoEdgeData, 'nesso'>;
 export declare function NessoEdge({ id, source, target, data, selected }: EdgeProps<NessoFlowEdge>): import("react/jsx-runtime").JSX.Element | null;
 export {};

package/dist/NessoEdge.js

@@ -2,12 +2,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // SPDX-License-Identifier: MIT
 import { useState } from 'react';
 import { useStore } from '@xyflow/react';
-import { PALETTES, RELATION_TYPES } from '@nesso-how/relation-types';
+import { PALETTES, RELATION_TYPES } from '@nesso-how/vocab-learning';
 import { GlyphSVG } from './GlyphSVG.js';
 import { useGraphDisplay } from './context.js';
 import { arcControlPoint, effectiveCurveFlip, flowNodeCenterX, flowNodeCenterY, nessoArcPath, rectExit, } from './geometry.js';
-function asEdgeTypeName(value, fallback = 'causes') {
-    return typeof value === 'string' && value in RELATION_TYPES ? value : fallback;
+function asRelationTypeName(value, fallback = 'causes') {
+    return typeof value === 'string' && value in RELATION_TYPES
+        ? value
+        : fallback;
 }
 function categoryColor(cat, mode, palette) {
     if (mode === 'css')
@@ -39,7 +41,7 @@ export function NessoEdge({ id, source, target, data, selected }) {
     const { edgeEncoding, curveStyle, autoCurveFlip, palette, categoryColorMode, getRelationLabel, isItemSelected, } = useGraphDisplay();
     const sourceNode = useStore((s) => s.nodeLookup.get(source));
     const targetNode = useStore((s) => s.nodeLookup.get(target));
-    const edgeType = asEdgeTypeName(data?.type);
+    const edgeType = asRelationTypeName(data?.type);
     const T = RELATION_TYPES[edgeType];
     const color = edgeEncoding === 'minimal'
         ? 'var(--ink-3, #888888)'

package/dist/NessoGraph.d.ts

@@ -1,11 +1,10 @@
 import type { Node, Edge, NodeTypes, EdgeTypes, ReactFlowProps, Viewport, OnNodesChange, OnEdgesChange, OnConnect, OnConnectStart, OnConnectEnd, OnMoveEnd } from '@xyflow/react';
-import type { NessoGraphFile } from '@nesso-how/formats';
-import type { EdgeTypeName } from '@nesso-how/relation-types';
-import type { ConceptNodeData, NessoEdgeData, GraphDisplaySettings, CategoryPalette } from '@nesso-how/types';
+import type { RelationTypeName, ConceptNodeData, NessoGraphDocument, NessoGraphDocumentInput, CategoryPalette } from '@nesso-how/vocab-learning';
+import type { NessoEdgeData, GraphDisplaySettings } from './display.js';
 import { type CategoryColorMode } from './context.js';
 type PassthroughKeys = 'nodes' | 'defaultNodes' | 'edges' | 'defaultEdges' | 'nodeTypes' | 'edgeTypes' | 'nodesDraggable' | 'nodesConnectable' | 'elementsSelectable' | 'onNodesChange' | 'onEdgesChange' | 'onConnect' | 'onConnectStart' | 'onConnectEnd' | 'onSelectionChange' | 'onMoveEnd' | 'onNodeClick' | 'onEdgeClick' | 'fitView' | 'defaultViewport' | 'minZoom' | 'maxZoom' | 'panOnDrag' | 'zoomOnScroll';
 export interface NessoGraphProps {
-    graph?: NessoGraphFile;
+    graph?: NessoGraphDocument | NessoGraphDocumentInput;
     nodes?: Node[];
     defaultNodes?: Node[];
     edges?: Edge[];
@@ -14,7 +13,7 @@ export interface NessoGraphProps {
     palette?: CategoryPalette;
     /** `palette` (default) for embeds; `css` when `--cat-*` vars are set on the page. */
     categoryColorMode?: CategoryColorMode;
-    getRelationLabel?: (type: EdgeTypeName) => string;
+    getRelationLabel?: (type: RelationTypeName) => string;
     isItemSelected?: (kind: 'node' | 'edge', id: string) => boolean;
     nodeTypes?: NodeTypes;
     edgeTypes?: EdgeTypes;

package/dist/NessoGraph.js

@@ -3,31 +3,34 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { useMemo } from 'react';
 import { ReactFlow, Background, Controls } from '@xyflow/react';
 import { GraphDisplayContext } from './context.js';
+import { documentToRenderGraph } from './documentToRenderGraph.js';
 import { ConceptNode } from './ConceptNode.js';
 import { NessoEdge } from './NessoEdge.js';
 const DEFAULT_NODE_TYPES = { concept: ConceptNode };
 const DEFAULT_EDGE_TYPES = { nesso: NessoEdge };
 export function NessoGraph({ graph, nodes: nodesProp, defaultNodes, edges: edgesProp, defaultEdges, display, palette = 'default', categoryColorMode = 'palette', getRelationLabel, isItemSelected, nodeTypes = DEFAULT_NODE_TYPES, edgeTypes = DEFAULT_EDGE_TYPES, nodesDraggable = false, nodesConnectable = false, elementsSelectable = true, panOnDrag = true, zoomOnScroll = true, onNodesChange, onEdgesChange, onConnect, onConnectStart, onConnectEnd, onSelectionChange, onMoveEnd, onNodeClick, onEdgeClick, fitView = true, defaultViewport, minZoom, maxZoom, reactFlowProps, style, className, onDoubleClick, children, }) {
-    const controlledNodes = nodesProp ?? graph?.nodes;
-    const controlledEdges = (edgesProp ?? graph?.edges);
-    // Controlled (`nodes`/`graph`) takes precedence; otherwise fall back to ReactFlow's
-    // own uncontrolled mode via `defaultNodes`/`defaultEdges` — see prop docs above.
-    const nodesProps = controlledNodes !== undefined
-        ? { nodes: controlledNodes }
-        : { defaultNodes: defaultNodes ?? [] };
-    const edgesProps = controlledEdges !== undefined
-        ? { edges: controlledEdges }
-        : { defaultEdges: defaultEdges ?? [] };
+    const rendered = graph ? documentToRenderGraph(graph) : undefined;
+    const graphDisplay = rendered?.display;
+    // `graph` alone → uncontrolled (React Flow owns drag/selection). With `onNodesChange` /
+    // explicit `nodes`, or `nodesProp` without `graph`, use controlled mode instead.
+    const nodeControlled = nodesProp !== undefined || (rendered !== undefined && onNodesChange !== undefined);
+    const edgeControlled = edgesProp !== undefined || (rendered !== undefined && onEdgesChange !== undefined);
+    const nodesProps = nodeControlled
+        ? { nodes: nodesProp ?? rendered?.nodes ?? [] }
+        : { defaultNodes: defaultNodes ?? rendered?.nodes ?? [] };
+    const edgesProps = edgeControlled
+        ? { edges: (edgesProp ?? rendered?.edges ?? []) }
+        : { defaultEdges: defaultEdges ?? rendered?.edges ?? [] };
     const ctx = useMemo(() => ({
-        edgeEncoding: display?.edgeEncoding ?? graph?.display?.edgeEncoding ?? 'full',
-        showHeatmap: display?.showHeatmap ?? graph?.display?.showHeatmap ?? true,
-        curveStyle: display?.curveStyle ?? graph?.display?.curveStyle ?? 'arc',
-        autoCurveFlip: display?.autoCurveFlip ?? graph?.display?.autoCurveFlip ?? true,
+        edgeEncoding: display?.edgeEncoding ?? graphDisplay?.edgeEncoding ?? 'full',
+        showHeatmap: display?.showHeatmap ?? graphDisplay?.showHeatmap ?? true,
+        curveStyle: display?.curveStyle ?? graphDisplay?.curveStyle ?? 'arc',
+        autoCurveFlip: display?.autoCurveFlip ?? graphDisplay?.autoCurveFlip ?? true,
         palette,
         categoryColorMode,
         getRelationLabel,
         isItemSelected,
-    }), [display, graph?.display, palette, categoryColorMode, getRelationLabel, isItemSelected]);
+    }), [display, graphDisplay, palette, categoryColorMode, getRelationLabel, isItemSelected]);
     return (_jsx("div", { style: { width: '100%', height: '100%', ...style }, className: className, onDoubleClick: onDoubleClick, children: _jsx(GraphDisplayContext.Provider, { value: ctx, children: _jsx(ReactFlow, { ...nodesProps, ...edgesProps, nodeTypes: nodeTypes, edgeTypes: edgeTypes, nodesDraggable: nodesDraggable, nodesConnectable: nodesConnectable, elementsSelectable: elementsSelectable, panOnDrag: panOnDrag, zoomOnScroll: zoomOnScroll, onNodesChange: onNodesChange, onEdgesChange: onEdgesChange, onConnect: onConnect, onConnectStart: onConnectStart, onConnectEnd: onConnectEnd, onSelectionChange: onSelectionChange, onMoveEnd: onMoveEnd, fitView: fitView, defaultViewport: defaultViewport, minZoom: minZoom, maxZoom: maxZoom, onNodeClick: onNodeClick
                     ? (_, node) => onNodeClick(node.id, node.data)
                     : undefined, onEdgeClick: onEdgeClick ? (_, edge) => onEdgeClick(edge.id, edge.data) : undefined, ...reactFlowProps, children: children ?? (_jsxs(_Fragment, { children: [_jsx(Background, {}), _jsx(Controls, {})] })) }) }) }));

package/dist/context.d.ts

@@ -1,5 +1,5 @@
-import type { EdgeTypeName } from '@nesso-how/relation-types';
-import type { EdgeEncoding, CurveStyle, CategoryPalette } from '@nesso-how/types';
+import type { RelationTypeName, CategoryPalette } from '@nesso-how/vocab-learning';
+import type { EdgeEncoding, CurveStyle } from './display.js';
 export type CategoryColorMode = 'palette' | 'css';
 export interface NessoGraphDisplayContext {
     edgeEncoding: EdgeEncoding;
@@ -9,7 +9,7 @@ export interface NessoGraphDisplayContext {
     palette: CategoryPalette;
     /** `palette` uses hex from PALETTES; `css` uses `var(--cat-*)` (app with live palette switching). */
     categoryColorMode: CategoryColorMode;
-    getRelationLabel?: (type: EdgeTypeName) => string;
+    getRelationLabel?: (type: RelationTypeName) => string;
     isItemSelected?: (kind: 'node' | 'edge', id: string) => boolean;
 }
 export declare const GraphDisplayContext: import("react").Context<NessoGraphDisplayContext>;

package/dist/display.d.ts

@@ -0,0 +1,15 @@
+import type { RelationTypeName } from '@nesso-how/vocab-learning';
+export type EdgeEncoding = 'full' | 'category' | 'minimal';
+export type CurveStyle = 'arc' | 'straight';
+export interface GraphDisplaySettings {
+    edgeEncoding: EdgeEncoding;
+    showHeatmap: boolean;
+    curveStyle: CurveStyle;
+    autoCurveFlip: boolean;
+}
+export interface NessoEdgeData extends Record<string, unknown> {
+    type: RelationTypeName;
+    siblingIdx?: number;
+    curveFlip?: boolean;
+    curveFlipPinned?: boolean;
+}

package/dist/display.js

@@ -0,0 +1 @@
+export {};

package/dist/documentToRenderGraph.d.ts

@@ -0,0 +1,9 @@
+import type { Node, Edge } from '@xyflow/react';
+import type { ConceptNodeData, NessoGraphDocumentInput } from '@nesso-how/vocab-learning';
+import type { NessoEdgeData, GraphDisplaySettings } from './display.js';
+/** Convert a Nesso graph document to React Flow nodes/edges for rendering (no FSRS). */
+export declare function documentToRenderGraph(doc: NessoGraphDocumentInput): {
+    nodes: Node<ConceptNodeData>[];
+    edges: Edge<NessoEdgeData>[];
+    display?: Partial<GraphDisplaySettings>;
+};

package/dist/documentToRenderGraph.js

@@ -0,0 +1,36 @@
+import { defaultConceptReviewFields } from '@nesso-how/vocab-learning';
+function edgeDataFromRelation(r) {
+    return {
+        type: r.type,
+        ...(r.data?.curveFlip !== undefined ? { curveFlip: r.data.curveFlip } : {}),
+        ...(r.data?.curveFlipPinned !== undefined ? { curveFlipPinned: r.data.curveFlipPinned } : {}),
+    };
+}
+function relationToEdge(r) {
+    return {
+        id: r.id,
+        source: r.source,
+        target: r.target,
+        sourceHandle: 'out',
+        targetHandle: 'in',
+        type: 'nesso',
+        data: edgeDataFromRelation(r),
+    };
+}
+/** Convert a Nesso graph document to React Flow nodes/edges for rendering (no FSRS). */
+export function documentToRenderGraph(doc) {
+    const fsrsDefaults = defaultConceptReviewFields();
+    const nodes = doc.concepts.map((c) => ({
+        id: c.id,
+        type: 'concept',
+        position: { x: c.x, y: c.y },
+        data: {
+            ...fsrsDefaults,
+            text: c.label,
+            ...(c.data?.elaboration !== undefined && { elaboration: c.data.elaboration }),
+        },
+    }));
+    const edges = doc.relations.map(relationToEdge);
+    const meta = doc.meta;
+    return { nodes, edges, display: meta?.display };
+}

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export type { ConceptNodeBodyProps } from './ConceptNodeBody.js';
 export { NessoEdge } from './NessoEdge.js';
 export { useGraphDisplay, GraphDisplayContext } from './context.js';
 export type { NessoGraphDisplayContext, CategoryColorMode } from './context.js';
+export type { CurveStyle, EdgeEncoding, GraphDisplaySettings, NessoEdgeData, } from './display.js';
+export { documentToRenderGraph } from './documentToRenderGraph.js';
 export { GlyphSVG } from './GlyphSVG.js';
 export { ratingColor } from './ratingColor.js';
 export { arcControlPoint, defaultCurveFlip, nodeCenterX, nodeCenterY, flowNodeCenterX, flowNodeCenterY, effectiveCurveFlip, rectExit, nessoArcPath, } from './geometry.js';

package/dist/index.js

@@ -4,6 +4,7 @@ export { ConceptNode } from './ConceptNode.js';
 export { ConceptNodeBody } from './ConceptNodeBody.js';
 export { NessoEdge } from './NessoEdge.js';
 export { useGraphDisplay, GraphDisplayContext } from './context.js';
+export { documentToRenderGraph } from './documentToRenderGraph.js';
 // Shared canvas utilities — import from here to avoid duplication with the main app.
 export { GlyphSVG } from './GlyphSVG.js';
 export { ratingColor } from './ratingColor.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nesso-how/graph",
-  "version": "0.1.0-alpha.33",
-  "description": "Embeddable read-only Nesso knowledge graph React component",
+  "version": "0.1.0-alpha.35",
+  "description": "Embeddable Nesso knowledge graph React component (read-only by default)",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -22,9 +22,7 @@
     }
   },
   "dependencies": {
-    "@nesso-how/formats": "0.1.0-alpha.33",
-    "@nesso-how/relation-types": "0.1.0-alpha.33",
-    "@nesso-how/types": "0.1.0-alpha.33"
+    "@nesso-how/vocab-learning": "0.1.0-alpha.35"
   },
   "peerDependencies": {
     "@xyflow/react": "^12.6.4",