@stuly/anode-react 0.1.0 → 0.1.1

package/README.md

@@ -1,7 +1,6 @@
-# anode-react
+# @stuly/anode-react
 
-React bindings and components for Anode, providing a declarative layer over
-the headless core engine.
+React bindings and components for Anode, providing a declarative layer over the headless core engine.
 
 ## Installation
 
@@ -9,14 +8,26 @@ the headless core engine.
 npm install @stuly/anode-react @stuly/anode
 ```
 
-## Components & Hooks
+## Quick Start
 
-- **World:** The primary canvas component for rendering the node graph.
-- **Socket:** A component for rendering connection points within nodes.
-- **Hooks:**
-  - `useAnode()`: Access the core engine.
-  - `useSocketValue()`: Subscribe to reactive data flow.
-  - `useVisibleNodes()`: Optimized spatial culling.
-  - `useEntitySockets()`: Reactive socket management.
+```tsx
+import { AnodeProvider, World } from '@stuly/anode-react';
 
-For detailed documentation and usage examples, see the [root README](../../README.md).
+export default function App() {
+  return (
+    <AnodeProvider>
+      <World />
+    </AnodeProvider>
+  );
+}
+```
+
+## Key Components & Hooks
+
+- **`World`**: Primary canvas component.
+- **`AnodeProvider`**: Context provider for the engine.
+- **`useAnode()`**: Access the core engine instance.
+- **`useSocketValue()`**: Subscribe to reactive data flow.
+- **`useVisibleNodes()`**: Optimized spatial culling for large graphs.
+
+For detailed documentation, usage examples, and core principles, see the [Full README](https://github.com/stulyproject/anode?tab=readme-ov-file).

package/dist/elements/Group.js

@@ -1,10 +1,10 @@
 import { useAnode, useViewport } from "../context.js";
 import React, { useState } from "react";
-import { Rect, Vec2 } from "@stuly/anode";
+import { Group, Rect, Vec2 } from "@stuly/anode";
 import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/elements/Group.tsx
-const Group = ({ id, children }) => {
+const Group$1 = ({ id, children }) => {
 	const ctx = useAnode();
 	const { viewport } = useViewport();
 	const group = ctx.groups.get(id);
@@ -83,4 +83,4 @@ const Group = ({ id, children }) => {
 };
 
 //#endregion
-export { Group };
+export { Group$1 as Group };

package/dist/elements/World.d.ts

@@ -4,41 +4,78 @@ import React from "react";
 import { Context, LinkKind } from "@stuly/anode";
 
 //#region src/elements/World.d.ts
+/** Represents the minimal data for a node in declarative sync mode. */
 interface NodeData {
+  /** The unique ID for the node. */
   id: number;
+  /** The absolute world position. */
   position: {
     x: number;
     y: number;
   };
+  /** Type key for the `nodeTypes` map. */
   type?: string;
+  /** Custom data stored in `entity.inner`. */
   data?: any;
 }
+/** Represents the minimal data for a link in declarative sync mode. */
 interface LinkData {
+  /** The unique ID for the link. */
   id: number;
+  /** Source entity ID. */
   source: number;
+  /** Name of the source socket. */
   sourceHandle: string;
+  /** Target entity ID. */
   target: number;
+  /** Name of the target socket. */
   targetHandle: string;
+  /** Type key for the `linkTypes` map. */
   type?: string;
+  /** Custom data stored in `link.inner`. */
   data?: any;
+  /** Routing style for the link. */
   kind?: LinkKind;
+  /** Optional custom waypoints. */
   waypoints?: {
     x: number;
     y: number;
   }[];
 }
+/**
+ * The primary canvas component for Anode.
+ * Handles interaction (zoom, pan, selection) and synchronizes the React component
+ * tree with the internal headless engine.
+ *
+ * **Behaviors:**
+ * 1. **Zoom/Pan:** Implements standard wheel and touch interaction.
+ * 2. **Selection:** Multi-select with Shift + Click, Box select with Alt + Click.
+ * 3. **Declarative Sync:** If `nodes` or `links` are passed, the core engine
+ *    automatically mirrors these arrays. Changes made directly in the UI
+ *    (dragging, deleting) will trigger the corresponding `onNodesChange` callback.
+ * 4. **Spatial Culling:** Automatically uses `useVisibleNodes` to optimize rendering.
+ *
+ * **Usage:**
+ * ```tsx
+ * <World
+ *   nodeTypes={{ math: MathNode }}
+ *   nodes={state.nodes}
+ *   onNodesChange={newNodes => setState({ nodes: newNodes })}
+ * />
+ * ```
+ */
 declare const World: React.FC<{
-  children?: React.ReactNode;
-  style?: React.CSSProperties;
-  selectionBoxStyle?: React.CSSProperties;
-  nodeTypes?: Record<string, React.ComponentType<NodeComponentProps>>;
-  linkTypes?: Record<string, React.ComponentType<LinkComponentProps>>;
-  defaultLinkKind?: LinkKind;
-  onConnect?: (fromId: number, toId: number, ctx: Context<any>) => void;
-  isValidConnection?: (from: any, to: any, ctx: Context<any>) => boolean;
-  nodes?: NodeData[];
-  links?: LinkData[];
-  onNodesChange?: (nodes: NodeData[], ctx: Context<any>) => void;
+  /** Elements to overlay on the world (Background, MiniMap, etc.). */children?: React.ReactNode; /** Styles applied to the outer container. */
+  style?: React.CSSProperties; /** Styles applied to the selection box overlay. */
+  selectionBoxStyle?: React.CSSProperties; /** Map of custom node components by their `type` key. */
+  nodeTypes?: Record<string, React.ComponentType<NodeComponentProps>>; /** Map of custom link overlays/UI components by their `type` key. */
+  linkTypes?: Record<string, React.ComponentType<LinkComponentProps>>; /** Default style for newly created links. */
+  defaultLinkKind?: LinkKind; /** Callback triggered when a user completes a connection via drag-and-drop. */
+  onConnect?: (fromId: number, toId: number, ctx: Context<any>) => void; /** Custom validation for link creation. Return false to prevent a connection. */
+  isValidConnection?: (from: any, to: any, ctx: Context<any>) => boolean; /** Declarative list of nodes. Use for state-controlled synchronization. */
+  nodes?: NodeData[]; /** Declarative list of links. Use for state-controlled synchronization. */
+  links?: LinkData[]; /** Callback triggered when nodes are moved or dropped. */
+  onNodesChange?: (nodes: NodeData[], ctx: Context<any>) => void; /** Callback triggered when links are updated or deleted. */
   onLinksChange?: (links: LinkData[], ctx: Context<any>) => void;
 }>;
 //#endregion

package/dist/elements/World.js

@@ -1,7 +1,7 @@
 import { AnodeReactContext, useAnode, useSelection, useViewport } from "../context.js";
 import { useEdges, useGroups, useVisibleNodes } from "../hooks.js";
 import { Node } from "./Node.js";
-import { Group } from "./Group.js";
+import { Group as Group$1 } from "./Group.js";
 import { Link as Link$1 } from "./Link.js";
 import React, { useContext, useEffect, useRef, useState } from "react";
 import { Context, LinkKind, Rect, Vec2 } from "@stuly/anode";
@@ -26,6 +26,28 @@ const getCenter = (t1, t2) => {
 		y: (t1.clientY + t2.clientY) / 2
 	};
 };
+/**
+* The primary canvas component for Anode.
+* Handles interaction (zoom, pan, selection) and synchronizes the React component
+* tree with the internal headless engine.
+*
+* **Behaviors:**
+* 1. **Zoom/Pan:** Implements standard wheel and touch interaction.
+* 2. **Selection:** Multi-select with Shift + Click, Box select with Alt + Click.
+* 3. **Declarative Sync:** If `nodes` or `links` are passed, the core engine
+*    automatically mirrors these arrays. Changes made directly in the UI
+*    (dragging, deleting) will trigger the corresponding `onNodesChange` callback.
+* 4. **Spatial Culling:** Automatically uses `useVisibleNodes` to optimize rendering.
+*
+* **Usage:**
+* ```tsx
+* <World
+*   nodeTypes={{ math: MathNode }}
+*   nodes={state.nodes}
+*   onNodesChange={newNodes => setState({ nodes: newNodes })}
+* />
+* ```
+*/
 const World = ({ children, style, nodeTypes = {}, linkTypes = {}, defaultLinkKind = LinkKind.BEZIER, onConnect, isValidConnection, selectionBoxStyle, nodes, links: linksProp, onNodesChange, onLinksChange }) => {
 	const ctx = useAnode();
 	const { viewport: transform, setViewport: setTransform, screenToWorld } = useViewport();
@@ -595,7 +617,7 @@ const World = ({ children, style, nodeTypes = {}, linkTypes = {}, defaultLinkKin
 						zIndex: 1,
 						pointerEvents: "none"
 					},
-					children: [groups.map((group) => /* @__PURE__ */ jsx(Group, { id: group.id }, group.id)), entities.map((entity) => {
+					children: [groups.map((group) => /* @__PURE__ */ jsx(Group$1, { id: group.id }, group.id)), entities.map((entity) => {
 						const Component = nodeTypes[entity.inner?.type || "default"] || DefaultNode;
 						return /* @__PURE__ */ jsx(Node, {
 							id: entity.id,

package/dist/hooks.d.ts

@@ -1,15 +1,59 @@
-import * as _stuly_anode0 from "@stuly/anode";
-import { Entity, Link } from "@stuly/anode";
+import { Entity, Group, Link } from "@stuly/anode";
 
 //#region src/hooks.d.ts
+/**
+ * Returns an array of all entities currently in the graph.
+ * Reactively updates when nodes are created, deleted, or moved.
+ *
+ * **Usage:**
+ * ```tsx
+ * const nodes = useNodes();
+ * ```
+ */
 declare const useNodes: () => Entity<any>[];
+/**
+ * Optimized hook for rendering a large-scale node graph.
+ * Performs a spatial query on the QuadTree to return only the nodes
+ * that are currently within the user's viewport (with padding).
+ *
+ * **Side Effects:** Triggers re-renders only when nodes enter or exit the viewport
+ * OR when a visible node is moved.
+ *
+ * @param containerRect The dimensions of the canvas container. If omitted, defaults to window size.
+ * @returns Array of visible Entity objects.
+ */
 declare const useVisibleNodes: (containerRect?: {
   width: number;
   height: number;
 }) => Entity<any>[];
+/**
+ * Returns an array of all links currently in the graph.
+ * Reactively updates when links are created, deleted, or updated,
+ * or when an endpoint entity moves (triggering path recalculation).
+ */
 declare const useEdges: () => Link<any>[];
+/**
+ * Returns an array of all sockets associated with a specific entity.
+ * Reactively updates when sockets are added or removed from the entity.
+ *
+ * @param entityId The unique ID of the entity.
+ */
 declare const useEntitySockets: (entityId: number) => any[];
+/**
+ * Subscribes to the reactive value of a specific socket.
+ *
+ * **Cause:** Triggers a re-render only when the value of the socket
+ * changes due to engine propagation.
+ *
+ * @template T The type of the value held by the socket.
+ * @param socketId The unique ID of the socket.
+ * @returns The current socket value, or null if the socket doesn't exist.
+ */
 declare function useSocketValue<T = any>(socketId: number | null): T;
-declare const useGroups: () => _stuly_anode0.Group[];
+/**
+ * Returns an array of all groups currently in the graph.
+ * Reactively updates when groups are created or deleted.
+ */
+declare const useGroups: () => Group[];
 //#endregion
 export { useEdges, useEntitySockets, useGroups, useNodes, useSocketValue, useVisibleNodes };

package/dist/hooks.js

@@ -1,8 +1,17 @@
 import { useAnode, useViewport } from "./context.js";
-import React, { useMemo, useSyncExternalStore } from "react";
-import { Entity, Link, Rect } from "@stuly/anode";
+import { useMemo, useSyncExternalStore } from "react";
+import { Entity, Group, Link, Rect } from "@stuly/anode";
 
 //#region src/hooks.ts
+/**
+* Returns an array of all entities currently in the graph.
+* Reactively updates when nodes are created, deleted, or moved.
+*
+* **Usage:**
+* ```tsx
+* const nodes = useNodes();
+* ```
+*/
 const useNodes = () => {
 	const ctx = useAnode();
 	const store = useMemo(() => {
@@ -27,6 +36,17 @@ const useNodes = () => {
 	}, [ctx]);
 	return useSyncExternalStore(store.subscribe, store.getSnapshot);
 };
+/**
+* Optimized hook for rendering a large-scale node graph.
+* Performs a spatial query on the QuadTree to return only the nodes
+* that are currently within the user's viewport (with padding).
+*
+* **Side Effects:** Triggers re-renders only when nodes enter or exit the viewport
+* OR when a visible node is moved.
+*
+* @param containerRect The dimensions of the canvas container. If omitted, defaults to window size.
+* @returns Array of visible Entity objects.
+*/
 const useVisibleNodes = (containerRect) => {
 	const ctx = useAnode();
 	const { viewport } = useViewport();
@@ -45,6 +65,11 @@ const useVisibleNodes = (containerRect) => {
 		useNodes()
 	]);
 };
+/**
+* Returns an array of all links currently in the graph.
+* Reactively updates when links are created, deleted, or updated,
+* or when an endpoint entity moves (triggering path recalculation).
+*/
 const useEdges = () => {
 	const ctx = useAnode();
 	const store = useMemo(() => {
@@ -69,6 +94,12 @@ const useEdges = () => {
 	}, [ctx]);
 	return useSyncExternalStore(store.subscribe, store.getSnapshot);
 };
+/**
+* Returns an array of all sockets associated with a specific entity.
+* Reactively updates when sockets are added or removed from the entity.
+*
+* @param entityId The unique ID of the entity.
+*/
 const useEntitySockets = (entityId) => {
 	const ctx = useAnode();
 	const store = useMemo(() => {
@@ -104,6 +135,16 @@ const useEntitySockets = (entityId) => {
 	}, [ctx, entityId]);
 	return useSyncExternalStore(store.subscribe, store.getSnapshot);
 };
+/**
+* Subscribes to the reactive value of a specific socket.
+*
+* **Cause:** Triggers a re-render only when the value of the socket
+* changes due to engine propagation.
+*
+* @template T The type of the value held by the socket.
+* @param socketId The unique ID of the socket.
+* @returns The current socket value, or null if the socket doesn't exist.
+*/
 function useSocketValue(socketId) {
 	const ctx = useAnode();
 	const store = useMemo(() => {
@@ -127,6 +168,10 @@ function useSocketValue(socketId) {
 	}, [ctx, socketId]);
 	return useSyncExternalStore(store.subscribe, store.getSnapshot);
 }
+/**
+* Returns an array of all groups currently in the graph.
+* Reactively updates when groups are created or deleted.
+*/
 const useGroups = () => {
 	const ctx = useAnode();
 	const store = useMemo(() => {

package/package.json

@@ -1,23 +1,37 @@
 {
   "name": "@stuly/anode-react",
-  "version": "0.1.0",
-  "description": "Anode react wrapper",
+  "version": "0.1.1",
+  "description": "First-class React bindings for building interactive, declarative node editors with Anode.",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "publishConfig": {
     "access": "public"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stulyproject/anode.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stulyproject/anode/issues"
+  },
+  "homepage": "https://github.com/stulyproject/anode#readme",
   "files": [
     "dist"
   ],
-  "keywords": [],
+  "keywords": [
+    "react",
+    "node-editor",
+    "node-graph",
+    "anode",
+    "declarative"
+  ],
   "author": "",
   "type": "module",
   "license": "MIT",
   "peerDependencies": {
     "react": "^19.2.4",
-    "@stuly/anode": "^0.1.0"
+    "@stuly/anode": "^0.1.1"
   },
   "devDependencies": {
     "@types/react": "^19.2.14",