Skip to content

Commit d450e12

Browse files
draedfuldraedful
authored
feat(DevTools): introduce DevToolsLayer for enhanced graph debugging and measurement
1 parent 8cd9705 commit d450e12

File tree

11 files changed

+927
-2
lines changed

11 files changed

+927
-2
lines changed

‎.cursor/rules/story-rules.mdc‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ alwaysApply: false
1313
## Graph Initialization (Recommended Pattern)
1414
- **Use `useGraph` hook:** Initialize the graph instance within your story component using the `useGraph` hook from `src/react-component/hooks/useGraph.ts`.
1515
```typescript
16-
import { useGraph, GraphCanvas, GraphBlock } from "@gravity-ui/graph"; // Adjust path as needed
16+
import { Graph, GraphState } from "../../../graph"; // Adjust path as needed
17+
import { GraphCanvas, useGraph } from "../../../react-component"; // Adjust path as needed
1718

1819
const MyStoryComponent = (props) => {
1920
const { graph } = useGraph({

‎docs/plugins/devtools.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# DevTools Plugin
2+
3+
## Overview
4+
5+
The `DevToolsLayer` plugin provides visual development tools for the `@gravity-ui/graph` library, aiding developers in precise positioning, measurement, and debugging of graph elements. It adds rulers along the edges of the graph viewport and a crosshair that follows the mouse cursor, displaying real-time world coordinates.
6+
7+
This layer is intended purely for development and debugging purposes and typically should not be included in production builds.
8+
9+
## Features
10+
11+
1. **Rulers (Horizontal & Vertical):**
12+
* Displays rulers along the top and left edges of the graph viewport.
13+
* Shows dynamic ticks (major and minor) with labels representing the current **world coordinates** based on the camera's position and scale.
14+
* The tick spacing adapts automatically to the zoom level using a "nice number" algorithm (1, 2, 5, 10...) for readability.
15+
* Includes a corner square where the rulers intersect.
16+
* Rulers remain fixed to the viewport edges; the graph content scrolls underneath them.
17+
18+
2. **Crosshair:**
19+
* Displays horizontal and vertical dashed lines that follow the mouse cursor.
20+
* Shows the current **world coordinates** of the cursor in the top-left corner (below the rulers).
21+
* The crosshair is only visible when the mouse cursor is within the main graph area (not over the rulers).
22+
23+
## Usage
24+
25+
The `DevToolsLayer` can be added to the graph like any other layer.
26+
27+
### 1. Via Graph Configuration
28+
29+
```typescript
30+
import { Graph, DevToolsLayer } from "@gravity-ui/graph";
31+
32+
const graph = new Graph({
33+
// ... other graph settings
34+
layers: [
35+
// Other layers...
36+
[DevToolsLayer, {
37+
showRuler: true, // Default
38+
showCrosshair: true, // Default
39+
// Add other custom options here if needed
40+
}]
41+
]
42+
});
43+
```
44+
45+
### 2. Dynamic Addition
46+
47+
```typescript
48+
import { DevToolsLayer } from "@gravity-ui/graph";
49+
50+
// Assuming 'graph' is an existing Graph instance
51+
graph.addLayer(DevToolsLayer, {
52+
showRuler: true,
53+
showCrosshair: true,
54+
});
55+
```
56+
57+
### 3. With React (`useLayer` Hook)
58+
59+
This is the recommended way when using the React bindings.
60+
61+
```tsx
62+
import React from 'react';
63+
import { useGraph, GraphCanvas, useLayer, DevToolsLayer, TDevToolsLayerProps } from '@gravity-ui/graph';
64+
65+
function MyGraphComponent() {
66+
const { graph } = useGraph({ /* ... initial config ... */ });
67+
68+
// Add the DevTools layer using the hook
69+
useLayer(graph, DevToolsLayer, {
70+
showRuler: true, // Control via props or Storybook args
71+
showCrosshair: true,
72+
// ... other DevToolsLayer props
73+
});
74+
75+
// ... useEffect to load data and start graph ...
76+
77+
return <GraphCanvas graph={graph} renderBlock={/* ... */} />;
78+
}
79+
```
80+
81+
## Configuration Options (`TDevToolsLayerProps`)
82+
83+
The layer accepts the following options (extending base `LayerProps`), with defaults defined in `DEFAULT_DEVTOOLS_LAYER_PROPS`:
84+
85+
| Prop | Type | Default | Description |
86+
| :------------------------- | :-------- | :----------------------------- | :-------------------------------------------------------------------------- |
87+
| `showRuler` | `boolean` | `true` | Toggles the visibility of the rulers. |
88+
| `showCrosshair` | `boolean` | `true` | Toggles the visibility of the crosshair and coordinate display. |
89+
| `rulerSize` | `number` | `25` | Width/height of the ruler area in logical pixels. |
90+
| `minMajorTickDistance` | `number` | `50` | Minimum desired screen distance (logical pixels) between major ruler ticks. |
91+
| `rulerBackgroundColor` | `string` | `"rgba(46, 46, 46, .4)"` | Background color of the ruler areas. |
92+
| `rulerTickColor` | `string` | `"rgb(93, 93, 93)"` | Color of the major and minor tick marks on the rulers. |
93+
| `rulerTextColor` | `string` | `"rgba(245, 245, 245, 0.8)"` | Color of the text labels on the rulers. |
94+
| `rulerTextFont` | `string` | `"11px Helvetica"` | CSS font string for the ruler text labels. |
95+
| `crosshairColor` | `string` | `"rgba(255, 0, 0, 0.7)"` | Color of the dashed crosshair lines. |
96+
| `crosshairTextColor` | `string` | `"rgba(255, 255, 255, 1)"` | Color of the coordinate text display. |
97+
| `crosshairTextFont` | `string` | `"11px Helvetica"` | CSS font string for the coordinate text display. |
98+
| `crosshairTextBackgroundColor` | `string` | `"rgba(0, 0, 0, 0.7)"` | Background color for the coordinate text display box. |
99+
| `rulerBackdropBlur` | `number` | `5` | Blur strength (in px) for the backdrop filter under the ruler backgrounds. |
100+
101+
*Note: Base `LayerProps` like `graph`, `camera`, `root`, `emitter` are provided automatically when using `graph.addLayer` or `useLayer`.*

0 commit comments

Comments
 (0)