refactor: separate React dependencies from core library (#74)

BREAKING CHANGE: React components moved to separate module

See [Migration Guide v0.x → v1.x](https://github.com/gravity-ui/graph/blob/main/docs/migration-guides/v0-to-v1.md) for detailed instructions.

---------

Co-authored-by: draedful <[email protected]>

Author: Antamansid

.cursor/rules/layer-rules.mdс .cursor/rules/layer-rules.mdc.cursor/rules/layer-rules.mdс renamed to .cursor/rules/layer-rules.mdc

@@ -34,6 +34,18 @@ Layers are fundamental to the Canvas rendering pipeline in @gravity-ui/graph. Th
     - Potentially culling elements outside the current viewport.
     - Managing redraws or logic updates based on relevant state changes.
 
+## Layer Lifecycle and DOM Operations
+
+- **Layer Initialization Sequence:**
+  1. **Creation (`constructor` → `init`)**: Layer is created, but not yet attached to DOM
+  2. **Attachment (`attachLayer` → `afterInit`)**: Layer is attached to DOM
+  3. **Updates (rendering cycle)**: Layer responds to changes
+  4. **Detachment (`detachLayer` → `unmount`)**: Layer is removed from DOM
+
+- **DOM Operation Timing:** Any operations that require the layer to be attached to the DOM (such as DOM manipulations, style injections, measurements, or accessing parent elements) must be performed in the `afterInit` method, not in `init` or the constructor.
+
+- **Why This Matters:** During the creation phase, the root element may be undefined or not yet attached to the document. The `afterInit` method is guaranteed to be called after the layer is properly attached to the DOM, ensuring that DOM operations work correctly.
+
 ## HTML Rendering in Layers
 
 The Layer class can create both Canvas and HTML elements for rendering:
@@ -110,6 +122,10 @@ this.html.style.transform = `matrix(${camera.scale}, 0, 0, ${camera.scale}, ${ca
       ```
     - Register the new layer in the main graph's processing pipeline in the correct order (often controlled by `zIndex` in `props.canvas` or `props.html`).
 
+- **Creating New Layers:**
+    - If adding new types of visual elements or behaviors, create a new layer class.
+    - New layers should ideally extend a base `Layer` class or a suitable existing layer, inheriting common functionality.
+    - Register the new layer in the main graph's processing pipeline in the correct order.
 - **Modifying Existing Layers:**
     - When changing how elements are rendered or behaviors are managed, modify the relevant methods (e.g., `render`, event handlers) of the corresponding layer.
     - Ensure efficiency; avoid unnecessary computations or drawing invisible elements.
@@ -125,7 +141,7 @@ this.html.style.transform = `matrix(${camera.scale}, 0, 0, ${camera.scale}, ${ca
     - Use `afterInit` for setup that requires the canvas and context to be ready.
     - Inside `afterInit`, reliably get the canvas using `this.getCanvas()`. 
     - Initialize or update the layer's full context using `this.setContext({ ...this.context, /* your additions */ });`. The base `Layer` already initializes `graph`, `camera`, `colors`, `constants`, `layer`. If you create a canvas/HTML element, you need to add `graphCanvas`/`html` and `ctx` to the context after creation (e.g., in `afterInit`).
-    - Attach event listeners (e.g., `mousemove`, `mouseleave`) to the graph's root element (`this.props.graph.getGraphHTML()`) or specific layer elements (`this.getCanvas()`, `this.getHTML()`) within `afterInit`.
+    - Attach event listeners (e.g., `mousemove`, `mouseleave`) to the layer's root element (`this.root`) or specific layer elements (`this.getCanvas()`, `this.getHTML()`) within `afterInit`.
     - Always clean up listeners and subscriptions in the `unmount` method.
 - **Camera Interaction & Coordinates:**
     - Subscribe to graph's `'camera-change'` event (`this.props.graph.on(...)`) to get updates. The event detail (`event.detail`) provides the `TCameraState` (containing `width`, `height`, `scale`, `x`, `y`).
@@ -202,4 +218,4 @@ protected afterInit() {
 }
 ```
 
-When the layer is unmounted, all handlers are automatically removed.
+When the layer is unmounted, all handlers are automatically removed. 

README-ru.md

@@ -62,7 +62,8 @@ npm install @gravity-ui/graph
 [Подробная документация по React компонентам](docs/react/usage.md)
 
 ```typescript
-import { GraphCanvas, GraphState, GraphBlock, useGraph } from "@gravity-ui/graph";
+import { Graph } from "@gravity-ui/graph";
+import { GraphCanvas, GraphState, GraphBlock, useGraph } from "@gravity-ui/graph/react";
 import React from "react";
 
 const config = {};
@@ -226,4 +227,3 @@ graph.zoomTo("center", { padding: 100 });
 |------|-----------|--------------|
 | Настройки графа | Параметры конфигурации | [Подробнее](docs/system/graph-settings.md) |
 | API | Методы для управления графом | [Подробнее](docs/system/public_api.md) |
-

README.md

@@ -23,7 +23,7 @@ Modern web applications often require complex visualization and interactivity, b
 The library uses a smart rendering system that automatically manages the transition between Canvas and React components:
 
 1. At low zoom levels, everything is rendered on Canvas for performance
-2. When zooming in to detailed view, the `BlocksList` component:
+2. When zooming in to detailed view, the `GraphCanvas` component:
    - Tracks camera viewport and scale changes
    - Calculates which blocks are visible in the current viewport (with padding for smooth scrolling)
    - Renders React components only for visible blocks
@@ -62,7 +62,8 @@ npm install @gravity-ui/graph
 [Detailed React Components Documentation](docs/react/usage.md)
 
 ```typescript
-import { GraphCanvas, GraphState, GraphBlock, useGraph } from "@gravity-ui/graph";
+import { EAnchorType, Graph } from "@gravity-ui/graph";
+import { GraphCanvas, GraphState, GraphBlock, useGraph } from "@gravity-ui/graph/react";
 import React from "react";
 
 const config = {};
@@ -82,7 +83,14 @@ export function GraphEditor() {
           height: 126,
           selected: true,
           name: "Block #1",
-          anchors: [],
+          anchors: [
+            {
+              id: "out1",
+              blockId: "action_1",
+              type: EAnchorType.OUT,
+              index: 0
+            }
+          ],
         },
         {
           id: "action_2",
@@ -93,13 +101,22 @@ export function GraphEditor() {
           height: 126,
           selected: false,
           name: "Block #2",
-          anchors: [],
+          anchors: [
+            {
+              id: "in1",
+              blockId: "action_2",
+              type: EAnchorType.IN,
+              index: 0
+            }
+          ],
         }
       ],
       connections: [
         {
           sourceBlockId: "action_1",
+          sourceAnchorId: "out1",
           targetBlockId: "action_2",
+          targetAnchorId: "in1",
         }
       ]
     });
@@ -159,7 +176,15 @@ graph.setEntities({
             y: 100,
             width: 120,
             height: 120,
-            name: "Block #1"
+            name: "Block #1",
+            anchors: [
+                {
+                    id: "out1",
+                    blockId: "block1",
+                    type: EAnchorType.OUT,
+                    index: 0
+                }
+            ]
         },
         {
             is: "block-action",
@@ -168,13 +193,23 @@ graph.setEntities({
             y: 300,
             width: 120,
             height: 120,
-            name: "Block #2"
+            name: "Block #2",
+            anchors: [
+                {
+                    id: "in1",
+                    blockId: "block2",
+                    type: EAnchorType.IN,
+                    index: 0
+                }
+            ]
         }
     ],
     connections: [
         {
             sourceBlockId: "block1",
-            targetBlockId: "block2"
+            sourceAnchorId: "out1",
+            targetBlockId: "block2",
+            targetAnchorId: "in1"
         }
     ]
 });
@@ -208,6 +243,7 @@ graph.zoomTo("center", { padding: 100 });
 2. Components
    - [Canvas Graph Component](docs/components/canvas-graph-component.md)
    - [Block Component](docs/components/block-component.md)
+   - [Anchors](docs/components/anchors.md)
 
 3. Rendering
    - [Rendering Mechanism](docs/rendering/rendering-mechanism.md)

docs/components/anchors.md

@@ -0,0 +1,185 @@
+# Anchors Documentation
+
+Anchors are connection points on blocks that allow creating connections between blocks. This document describes the anchor structure, behavior, and how to properly configure them.
+
+> **Note:** Anchors are optional in the graph system. You can create graphs without anchors by setting the `useBlocksAnchors` setting to `false`. In this case, connections will be made directly between blocks without specific anchor points.
+
+## Anchor Structure
+
+Anchors are defined using the `TAnchor` interface:
+
+```typescript
+export type TAnchor = {
+  id: string;           // Unique identifier for the anchor
+  blockId: TBlockId;    // ID of the block this anchor belongs to
+  type: EAnchorType;    // Type of anchor (IN or OUT)
+  index?: number;       // Optional index for ordering anchors of the same type
+};
+```
+
+### Key Properties
+
+1. **id**: A unique identifier for the anchor within the block. This is used to reference the anchor in connections and for selection.
+
+2. **blockId**: The ID of the block this anchor belongs to. This is critical for the anchor to be properly associated with its parent block and for the selection system to work correctly.
+
+3. **type**: The type of anchor, defined by the `EAnchorType` enum:
+   ```typescript
+   export enum EAnchorType {
+     IN = "IN",   // Input anchor (can receive connections)
+     OUT = "OUT", // Output anchor (can initiate connections)
+   }
+   ```
+
+4. **index**: An optional numeric value that determines the order of anchors of the same type. This affects the visual positioning of anchors on the block.
+
+## Configuring Anchors and Connections
+
+When defining blocks in your graph configuration, you can configure anchors and connections between them:
+
+```typescript
+const graphConfig = {
+  blocks: [
+    {
+      id: "block1",
+      is: "Block",
+      x: 100,
+      y: 100,
+      width: 150,
+      height: 80,
+      name: "Source Block",
+      selected: false,
+      anchors: [
+        {
+          id: "out1",
+          blockId: "block1", // Must match the parent block's ID
+          type: EAnchorType.OUT,
+          index: 0
+        }
+      ]
+    },
+    {
+      id: "block2",
+      is: "Block",
+      x: 400,
+      y: 200,
+      width: 150,
+      height: 80,
+      name: "Target Block",
+      selected: false,
+      anchors: [
+        {
+          id: "in1",
+          blockId: "block2", // Must match the parent block's ID
+          type: EAnchorType.IN,
+          index: 0
+        }
+      ]
+    }
+  ],
+  connections: [
+    {
+      id: "conn1",
+      sourceBlockId: "block1",
+      sourceAnchorId: "out1", // Reference to the source anchor
+      targetBlockId: "block2",
+      targetAnchorId: "in1", // Reference to the target anchor
+      selected: false
+    }
+  ]
+};
+```
+
+## Dynamic Anchor Creation
+
+When creating blocks dynamically, ensure you set the correct `blockId` for each anchor:
+
+```typescript
+// Create a new block with a unique ID
+const newBlockId = `block-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+
+const blockId = graph.api.addBlock({
+  id: newBlockId, // Explicitly set the block ID
+  is: "Block",
+  x: 100,
+  y: 100,
+  width: 150,
+  height: 80,
+  name: "New Block",
+  selected: false,
+  anchors: [
+    {
+      id: "in",
+      blockId: newBlockId, // Use the same ID as the block
+      type: EAnchorType.IN,
+      index: 0
+    },
+    {
+      id: "out",
+      blockId: newBlockId, // Use the same ID as the block
+      type: EAnchorType.OUT,
+      index: 0
+    }
+  ]
+});
+```
+
+## Anchor Selection
+
+Anchors can be selected programmatically or through user interaction. The selection state is managed by the `AnchorState` class:
+
+```typescript
+// Get the anchor state
+const anchorState = block.getAnchorState("anchorId");
+
+// Select the anchor
+anchorState.setSelection(true);
+
+// Deselect the anchor
+anchorState.setSelection(false);
+```
+
+## Anchor Positioning
+
+The position of anchors is determined by the block's geometry and the anchor's type and index. The `Block` class provides methods to get the position of an anchor:
+
+```typescript
+// Get the position of an anchor
+const position = block.getAnchorPosition(anchorId);
+```
+
+## Anchor Positioning and Block Height
+
+The vertical position of anchors is determined by the block's constants, specifically `HEAD_HEIGHT` and `BODY_PADDING`. These constants are defined in the graph configuration and affect where anchors are placed on blocks.
+
+```typescript
+// From Block.ts - getAnchorPosition method
+const offset = this.context.constants.block.HEAD_HEIGHT + this.context.constants.block.BODY_PADDING;
+return {
+  x: anchor.type === EAnchorType.OUT ? this.state.width : 0,
+  y: offset + index * this.context.constants.system.GRID_SIZE * 2,
+};
+```
+
+### Important Considerations for Block Height
+
+1. **Default Constants**: By default, `HEAD_HEIGHT` is 64px and `BODY_PADDING` is 24px, resulting in an 88px vertical offset for the first anchor.
+
+2. **Small Blocks Warning**: If your blocks have a small height (e.g., less than 90px), the anchors may appear below the actual block. To fix this:
+   - Set `HEAD_HEIGHT` to 0 or a smaller value
+   - Reduce `BODY_PADDING` as needed
+
+3. **Custom Configuration Example**:
+   ```javascript
+   const graph = new Graph({
+     constants: {
+       block: {
+         HEAD_HEIGHT: 0,  // Remove header height for small blocks
+         BODY_PADDING: 8  // Reduce padding for better anchor positioning
+       }
+     },
+     // other configuration...
+   }, container);
+   ```
+
+4. **Anchor Index Impact**: Each additional anchor is positioned with an offset of `GRID_SIZE * 2` (default 32px). Consider this when determining how many anchors can fit on a block of a given height.