refactor: standardize canvas transformations across layers (#69)

Author: draedful

.cursor/rules/event-model-rules.mdc

@@ -81,4 +81,25 @@ The system uses **`CustomEvent`**, and interaction follows a `.on`/`.off`/`.emit
 - **Use `event.detail`:** Access event-specific data here.
 - **Check `event.detail.target`:** Identify the specific component involved.
 - **Emit Custom Events:** Use `graph.emit(...)` to broadcast custom global events.
-- **Performance:** Avoid heavy logic in listeners. 
+- **Performance:** Avoid heavy logic in listeners.
+
+## Connection Creation Events (`ConnectionLayer.ts`)
+These events are fired by the `ConnectionLayer` during the interactive creation of connections.
+
+- **`connection-create-start`**: Fires when the user starts dragging a connection from a block or anchor.
+  - **`event.detail`**: `{ blockId: TBlockId; anchorId: string | undefined; }`
+  - **Preventable:** Yes. Preventing this stops the connection creation process.
+
+- **`connection-create-hover`**: Fires when the dragged connection endpoint hovers over a potential target block or anchor.
+  - **`event.detail`**: `{ sourceBlockId: TBlockId; sourceAnchorId: string | undefined; targetBlockId: TBlockId | undefined; targetAnchorId: string | undefined; }`
+  - **Preventable:** Yes. Preventing this prevents the connection from being made to the current target (hover state might not show).
+
+- **`connection-created`**: Fires when a connection is successfully created (user drops the endpoint onto a valid target).
+  - **`event.detail`**: `{ sourceBlockId: TBlockId; sourceAnchorId?: string; targetBlockId: TBlockId; targetAnchorId?: string; }`
+  - **Preventable:** Yes. Preventing this stops the connection from being added to the `connectionsList` store (default action).
+
+- **`connection-create-drop`**: Fires when the user drops the connection endpoint, regardless of whether it landed on a valid target.
+  - **`event.detail`**: `{ sourceBlockId: TBlockId; sourceAnchorId: string | undefined; targetBlockId?: TBlockId; targetAnchorId?: string; point: Point; }` (target details are present if dropped on a valid target).
+  - **Preventable:** No (typically used for cleanup or alternative actions on drop).
+
+------- 

.cursor/rules/layer-rules.mdc

@@ -10,6 +10,22 @@ Layers are fundamental to the Canvas rendering pipeline in @gravity-ui/graph. Th
 
 ## Key Layer Concepts
 - **Purpose:** Each layer is responsible for a specific aspect of the graph, which can include **rendering visual elements** (e.g., `BackgroundLayer`, `ConnectionLayer`) or **managing behavior and logic** (e.g., handling specific user interactions, managing non-visual state). A layer might not have a direct visual representation but still participate in the graph's lifecycle and logic.
+- **Base Class:** `src/services/Layer.ts` (Exports `Layer`, `LayerProps`, `LayerContext`).
+- **`LayerProps` Interface:** Defines configuration for a layer. Key properties include:
+    - `canvas`: Configuration for the HTML5 Canvas element (optional).
+        - `zIndex`: Stacking order.
+        - `classNames`: CSS classes.
+        - `respectPixelRatio`: (boolean, default: true) Whether the canvas should account for device pixel ratio for sharper rendering.
+        - `transformByCameraPosition`: (boolean, default: false) Whether the canvas transform should automatically follow the camera's position and scale.
+    - `html`: Configuration for the HTML overlay element (optional).
+        - `zIndex`: Stacking order.
+        - `classNames`: CSS classes.
+        - `transformByCameraPosition`: (boolean, default: false) Whether the HTML element's transform should automatically follow the camera's position and scale via CSS `matrix()`.
+    - `camera`: The `ICamera` instance.
+    - `graph`: The main `Graph` instance.
+    - `root`: The root HTML element where the layer will be attached.
+- **`LayerContext` Interface:** Provides context information accessible within the layer (via `this.context`). Includes:
+    - `graph`, `camera`, `constants`, `colors`, `graphCanvas`, `ctx`, `layer` (self-reference).
 - **Location:** Core layer logic and specific layer implementations are found in `src/components/canvas/layers/` and potentially base classes/services like `src/services/Layer.ts`.
 - **Rendering Order/Priority:** Layers are rendered/processed in a specific sequence determined by the main graph component. The order is crucial for visual correctness and logical flow (e.g., connections below blocks, interaction handlers processed before rendering). Typical order might be: Background -> Connections -> Blocks -> Groups -> Behavior/Interaction Layers -> Highlight Layers.
 - **Performance:** Layers optimize rendering and processing by:
@@ -25,7 +41,7 @@ Layers are fundamental to the Canvas rendering pipeline in @gravity-ui/graph. Th
     - The base `Layer` class has the following generic signature: `Layer<Props extends LayerProps, Context extends LayerContext, State extends TComponentState>`.
     - `LayerProps`, `LayerContext`, and `TComponentState` are defined in `src/services/Layer.ts` and `src/lib/Component.ts` respectively.
     - When defining your custom layer, specify your custom Props, Context (if needed, extending `LayerContext`), and State (if needed, extending `TComponentState`) in this order: `class MyLayer extends Layer<TMyLayerProps, TMyLayerContext, TMyLayerState> {...}`.
-    - Your custom `TMyLayerProps` interface **must extend the base `LayerProps`**. This is because the base constructor requires properties like `graph` and `camera`.
+    - Your custom `TMyLayerProps` interface **must extend the base `LayerProps`**. This is because the base constructor requires properties like `graph` and `camera`. Make sure to define custom props alongside the base ones.
 
 - **Constructor and Props:**
     - The constructor of your custom layer will typically receive the *full* `LayerProps` (or your extended `TMyLayerProps`).
@@ -53,18 +69,19 @@ Layers are fundamental to the Canvas rendering pipeline in @gravity-ui/graph. Th
 - **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.
-- **Handling Device Pixel Ratio (DPR):** For crisp rendering on HiDPI displays, ensure the layer respects DPR.
-    - **Recommended:** Set `respectPixelRatio: true` in the `canvas` options when initializing the layer via `super({ canvas: { respectPixelRatio: true }, ... })`. The base `Layer` class will then attempt to handle canvas sizing automatically.
-    - **Manual (if needed):** If automatic handling isn't sufficient or more control is required:
-        1.  Get the DPR from context: `const dpr = this.context.constants.system.PIXEL_RATIO;`
-        2.  In your layer's `render` method, reset the transform: `ctx.setTransform(1, 0, 0, 1, 0, 0);`
-        3.  Clear the correct area: `ctx.clearRect(0, 0, viewWidth * dpr, viewHeight * dpr);` (where `viewWidth`/`viewHeight` are CSS dimensions from camera state).
-        4.  Scale the context *before* drawing: `ctx.scale(dpr, dpr);`
+- **Handling Device Pixel Ratio (DPR) and Transforms:** For crisp rendering and correct positioning, especially when using Canvas:
+    - **`respectPixelRatio`:** Set this to `true` (default) in `LayerProps.canvas` to enable automatic DPR handling by the base `Layer` class. The canvas dimensions will be scaled, and transforms applied correctly.
+    - **`transformByCameraPosition`:** Set this to `true` in `LayerProps.canvas` or `LayerProps.html` if the layer's content should move/scale with the camera automatically.
+    - **Manual Transforms:**
+        - Use `this.resetTransform()` at the beginning of your `render` method. This clears the canvas and applies the base camera transform (if `transformByCameraPosition` is true for canvas) respecting the DPR.
+        - Use `this.applyTransform(x, y, scale, respectPixelRatio)` to apply additional transformations relative to the camera or world space, ensuring DPR is accounted for.
+        - Use `this.getDRP()` to get the calculated Device Pixel Ratio (respecting `respectPixelRatio` flag).
+    - **Coordinate Systems:** Remember that `this.context.ctx` transformations managed by `resetTransform` and `applyTransform` handle the conversion from world space to the scaled canvas coordinate space. Draw using world coordinates.
 - **Layer Lifecycle & Context:**
     - 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({ canvas, ctx: canvas.getContext('2d'), camera: ..., constants: ..., colors: ..., graph: ..., ...this.context });`. This ensures the context object (`this.context`) is correctly typed and populated for your layer.
-    - Attach event listeners (e.g., `mousemove`, `mouseleave`) to the graph's root element (`this.props.graph.layers?.$root`) within `afterInit`.
+    - 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`.
     - 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`).

.cursor/rules/project-rules.mdc

@@ -62,6 +62,7 @@ Rendering system:
 - Full graph is rendered on Canvas for performance
 - When zooming in, HTML/React mode is automatically enabled for interactive elements
 - Uses a smart system that tracks visible blocks and renders only them in React
+- Rendering is organized into Layers (`src/services/Layer.ts`) which control drawing order and can optimize rendering based on camera position and device pixel ratio (`respectPixelRatio`, `transformByCameraPosition` properties in `LayerProps`).
 
 ## Development Guidelines
 Development guidelines:

docs/rendering/layers.md

@@ -70,59 +70,140 @@ const newBlockLayer = graph.addLayer(NewBlockLayer, { ghostBackground: "rgba(0,
 
 ### Basic Structure
 
-Each layer can have its own canvas and/or HTML elements for rendering and interaction:
+Custom layers should extend the base `Layer` class (`src/services/Layer.ts`). This class provides the core functionality for managing Canvas and HTML elements within the graph's rendering pipeline.
 
 ```typescript
-import { Layer, LayerContext, LayerProps } from "@/services/Layer";
-import { CameraService } from "@/services/camera/CameraService";
+import { Layer, LayerContext, LayerProps, TGraphColors, TGraphConstants } from "@/services/Layer";
+import { ICamera } from "@/services/camera/CameraService";
 import { Graph } from "@/graph";
 
+// Define custom properties for your layer, extending the base LayerProps
 interface MyLayerProps extends LayerProps {
   customOption?: string;
+  gridColor?: string;
+}
+
+// Optionally extend the LayerContext if your layer needs additional context
+interface MyLayerContext extends LayerContext {
+  // Add specific context properties here
 }
 
-export class MyLayer extends Layer<MyLayerProps> {
+// Define the Layer, specifying Props and optionally Context
+export class MyLayer extends Layer<MyLayerProps, MyLayerContext> {
   constructor(props: MyLayerProps) {
+    // Call the base constructor, passing props and potentially overriding default layer settings
     super({
-      // Canvas element for drawing
+      // Canvas element configuration (optional)
       canvas: {
         zIndex: 10,
-        classNames: ["my-layer"]
+        classNames: ["my-layer-canvas"],
+        respectPixelRatio: true, // Default: true. Set to false to disable DPR scaling.
+        transformByCameraPosition: true // Default: false. Set to true to automatically apply camera transform.
       },
-      // HTML element for DOM-based interactions
+      // HTML element configuration (optional)
       html: {
-        zIndex: 10,
+        zIndex: 11,
         classNames: ["my-layer-html"],
-        transformByCameraPosition: true
+        transformByCameraPosition: true // Default: false. Set to true to apply camera transform via CSS.
       },
-      ...props
+      ...props // Pass remaining props, including required `graph` and `camera`
     });
-    
+
+    // --- Context Setup ---
+    // Base context (graph, camera, constants, colors, layer) is set by the super constructor.
+    // You need to add context specific to the elements created by this layer.
+    // It's recommended to do this in `afterInit` when elements are guaranteed to exist.
+  }
+
+  // `afterInit` is called after the layer's elements (canvas/html) are created and attached.
+  protected afterInit() {
+    // Get the created elements (if configured)
+    const canvas = this.getCanvas(); // Returns HTMLCanvasElement or undefined
+    const html = this.getHTML(); // Returns HTMLElement or undefined
+
+    // Set up the context, including the canvas context if needed
     this.setContext({
-      canvas: this.getCanvas(),
-      ctx: this.getCanvas().getContext("2d"),
-      camera: props.camera,
-      graph: this.props.graph
+      // Keep existing context properties
+      ...this.context,
+      // Add properties specific to this layer's setup
+      graphCanvas: canvas, // Use the correct property name
+      ctx: canvas?.getContext("2d") || undefined,
+      // Add any custom context fields defined in MyLayerContext
     });
-    
-    // Subscribe to events
-    this.context.graph.on("camera-change", this.performRender);
+
+    // Now the full context (this.context) is available and typed.
+    // Subscribe to events here
+    this.cameraSubscription = this.context.graph.on("camera-change", this.performRender);
+    // Add other event listeners (e.g., to this.getHTML() or this.getCanvas())
+
+    // Perform initial render
+    this.performRender();
   }
-  
-  // Rendering method
+
+  // --- Rendering --- 
+  // This method is called automatically when performRender is invoked (e.g., on camera change).
   protected render() {
-    const { ctx } = this.context;
-    ctx.clearRect(0, 0, this.context.canvas.width, this.context.canvas.height);
-    // Custom rendering code
+    // Check if context is fully initialized
+    if (!this.context.ctx || !this.context.graphCanvas) {
+      return; 
+    }
+
+    // Reset transformations and clear canvas
+    this.resetTransform(); // Applies camera transform if transformByCameraPosition=true, respects DPR
+
+    const { ctx, camera, constants, colors } = this.context;
+    const { scale, x, y } = camera.getCameraState();
+
+    // --- Custom Rendering Logic --- 
+    // Draw using world coordinates. `resetTransform` handles the necessary scaling and translation.
+    ctx.fillStyle = this.props.gridColor || colors.canvas.gridColor; // Example using props/colors
+    ctx.fillRect(10, 10, 50, 50); // Draws a rectangle at world coordinates (10, 10)
+
+    // Example: Apply additional transform relative to the camera
+    // this.applyTransform(worldX, worldY, worldScale); // Respects DPR
   }
-  
-  // Resource cleanup
+
+  // --- Cleanup --- 
+  // Called when the layer is removed from the graph.
   protected unmount(): void {
-    this.context.graph.off("camera-change", this.performRender);
+    // Always clean up subscriptions and event listeners
+    this.cameraSubscription?.();
+    // Remove other listeners added in `afterInit`
+    super.unmount(); // Calls base unmount logic (removes elements)
   }
 }
 ```
 
+### Handling Transformations and Device Pixel Ratio (DPR)
+
+The `Layer` class provides tools to handle rendering correctly with camera transformations and on high-resolution (HiDPI) displays.
+
+- **`respectPixelRatio`** (`LayerProps.canvas.respectPixelRatio`, default: `true`):
+    - When `true`, the canvas dimensions are automatically scaled by the device pixel ratio (`window.devicePixelRatio`).
+    - The `resetTransform()` and `applyTransform()` methods automatically account for this scaling, so you can draw using world coordinates without manual DPR calculation.
+    - Set to `false` only if you need explicit manual control over pixel scaling.
+
+- **`transformByCameraPosition`** (`LayerProps.canvas.transformByCameraPosition` / `LayerProps.html.transformByCameraPosition`, default: `false`):
+    - **For Canvas:** When `true`, the `resetTransform()` method automatically applies the current camera translation (`x`, `y`) and `scale` to the canvas context (`ctx`). This means your subsequent drawing operations in the `render` method should use world coordinates.
+    - **For HTML:** When `true`, the HTML element gets the `layer-with-camera` class, and its CSS `transform: matrix(...)` is automatically updated on camera changes to match the camera's position and scale.
+
+- **`resetTransform()`**:
+    - Call this at the beginning of your canvas `render` method.
+    - It resets the canvas context's transform to the identity matrix.
+    - It clears the entire canvas (`clearRect`).
+    - If `transformByCameraPosition` is `true` for the canvas, it applies the current camera transform (`scale`, `x`, `y`), automatically accounting for DPR if `respectPixelRatio` is `true`.
+
+- **`applyTransform(x, y, scale, respectPixelRatioOverride)`**:
+    - Applies an *additional* transformation to the canvas context, relative to the current transform (which includes the camera transform if set by `resetTransform`).
+    - Useful for drawing elements at specific world positions/scales relative to the base camera view.
+    - It automatically accounts for DPR based on the layer's `respectPixelRatio` setting unless overridden by the optional fourth argument.
+
+- **`getDRP()`**:
+    - Returns the device pixel ratio value that the layer is currently using (respecting the `respectPixelRatio` flag).
+    - Use this only if you need the DPR value for complex manual calculations, usually unnecessary when using `resetTransform` and `applyTransform`.
+
+**In summary:** For most canvas layers, set `respectPixelRatio: true` and `transformByCameraPosition: true`, call `resetTransform()` at the start of `render`, and draw using world coordinates. Use `applyTransform` for specific relative positioning if needed.
+
 ### Built-in CSS Classes
 
 The library provides several built-in CSS classes that can be used with layers:

src/components/canvas/blocks/Block.ts

@@ -376,7 +376,7 @@ export class Block<T extends TBlock = TBlock, Props extends TBlockProps = TBlock
     return this.getConnectionAnchorPosition(anchor);
   };
 
-  protected updateChildren(): void | object[] {
+  protected updateChildren() {
     if (!this.isAnchorsAllowed()) {
       return undefined;
     }

src/components/canvas/connections/BlockConnections.ts

@@ -53,7 +53,7 @@ export class BlockConnections extends Component<CoreComponentProps, TComponentSt
     this.unsubscribe.forEach((reactionDisposer) => reactionDisposer());
   }
 
-  protected updateChildren(): void | object[] {
+  protected updateChildren() {
     if (!this.connections) return [];
     const settings = this.context.graph.rootStore.settings.$connectionsSettings.value;
     const ConnectionCtop = this.context.graph.rootStore.settings.$connection.value || BlockConnection;