Skip to content

Commit 06da655

Browse files
fangsmilefangsmile
committed
docs: refine vgraph skill guidance
1 parent 12b9289 commit 06da655

3 files changed

Lines changed: 89 additions & 9 deletions

File tree

‎skills/vgraph-development-assistant/references/examples/demo-html-page.md‎

Lines changed: 40 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,28 @@ A polished standalone demo should contain:
1717

1818
## Minimal HTML shell
1919

20+
For a real standalone HTML file, use an executable module script. Prefer a local
21+
package/dev-server import when working inside this repository; use an ESM CDN
22+
only when the user explicitly wants a portable single HTML file and accepts
23+
network access. Do not paste TypeScript-only syntax such as generic query
24+
selectors or `interface` declarations into a plain browser `<script>`.
25+
2026
```html
27+
<!doctype html>
28+
<html lang="en">
29+
<head>
30+
<meta charset="utf-8" />
31+
<meta name="viewport" content="width=device-width, initial-scale=1" />
32+
<title>VGraph Demo</title>
33+
<style>
34+
html,
35+
body {
36+
height: 100%;
37+
margin: 0;
38+
}
39+
</style>
40+
</head>
41+
<body>
2142
<div class="tabs">
2243
<button class="tab active" data-tab="demo-panel">Demo</button>
2344
<button class="tab" data-tab="code-panel">Code</button>
@@ -34,6 +55,20 @@ A polished standalone demo should contain:
3455
</div>
3556
<pre><code id="code-block"></code></pre>
3657
</section>
58+
59+
<script type="module">
60+
import {
61+
Graph,
62+
TreeGraph,
63+
panZoom,
64+
dragCanvas
65+
} from "https://esm.sh/@visactor/vgraph";
66+
67+
// Put the demo logic here. If developing inside the monorepo, replace the
68+
// CDN import with the package/dev-server import used by the local example.
69+
</script>
70+
</body>
71+
</html>
3772
```
3873

3974
```css
@@ -78,10 +113,10 @@ A polished standalone demo should contain:
78113
}
79114
```
80115

81-
```ts
82-
const tabs = Array.from(document.querySelectorAll<HTMLButtonElement>(".tab"));
83-
const panels = Array.from(document.querySelectorAll<HTMLElement>(".panel"));
84-
const container = document.getElementById("container") as HTMLDivElement;
116+
```js
117+
const tabs = Array.from(document.querySelectorAll(".tab"));
118+
const panels = Array.from(document.querySelectorAll(".panel"));
119+
const container = document.getElementById("container");
85120
const { width, height } = container.getBoundingClientRect();
86121

87122
for (const tab of tabs) {
@@ -170,7 +205,7 @@ graph.addBehavior(panZoom, { sensitivity: 4 });
170205
graph.addBehavior(dragCanvas);
171206

172207
graph.on("node:click", ev => {
173-
const id = ev?.datum?.id ?? ev?.target?.id;
208+
const id = ev?.target?.get?.("id");
174209
if (!id || !nodeMap.get(id)?.children?.length) return;
175210

176211
if (collapsedIds.has(id)) collapsedIds.delete(id);

‎skills/vgraph-development-assistant/references/examples/react-viewer.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,19 @@
33
Use this pattern when the user asks for React-rendered nodes.
44

55
```tsx
6-
import React, { useEffect, useState } from "react";
6+
import React, { useEffect, useRef, useState } from "react";
77
import { Graph, panZoom, dragCanvas } from "@visactor/vgraph";
88
import { Viewer } from "@visactor/react-vgraph";
99

1010
export function VGraphPanel() {
11+
const containerRef = useRef<HTMLDivElement | null>(null);
1112
const [graph, setGraph] = useState<Graph | null>(null);
1213

1314
useEffect(() => {
15+
if (!containerRef.current) return;
16+
1417
const g = new Graph({
15-
container: "vgraph-canvas",
18+
container: containerRef.current,
1619
width: 900,
1720
height: 560,
1821
renderMode: "dom",
@@ -38,13 +41,12 @@ export function VGraphPanel() {
3841

3942
return () => {
4043
g.destroy();
41-
setGraph(null);
4244
};
4345
}, []);
4446

4547
return (
4648
<div>
47-
<div id="vgraph-canvas" style={{ width: 900, height: 560 }} />
49+
<div ref={containerRef} style={{ width: 900, height: 560 }} />
4850
{graph && (
4951
<Viewer
5052
graph={graph}
@@ -60,4 +62,8 @@ export function VGraphPanel() {
6062
}
6163
```
6264

65+
Use a DOM ref instead of a hard-coded container id in reusable React components;
66+
hard-coded ids collide when the component is mounted more than once or in
67+
strict-mode development workflows.
68+
6369
Avoid React Viewer for very large graphs unless the user explicitly needs DOM nodes.

‎skills/vgraph-development-assistant/references/knowledge/08-performance-debugging.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,20 @@ Check in order:
1515
7. Layout is configured or coordinates are provided.
1616
8. Old graph instances were destroyed before recreating in the same container.
1717

18+
Fast falsification checks:
19+
20+
```ts
21+
console.log(graph.get("width"), graph.get("height"));
22+
console.log(graph.getNodes().length, graph.getEdges().length);
23+
graph.on(GRAPH_EVENTS.LAYOUT_END, () => console.log("layout end"));
24+
graph.on(GRAPH_EVENTS.DRAW_END, () => console.log("draw end"));
25+
```
26+
27+
If node/edge counts are zero, inspect the data path first. If counts are
28+
positive but nothing is visible, inspect layout completion, viewport transform,
29+
style opacity/stroke/fill, and whether the graph was created in a hidden or
30+
zero-size container.
31+
1832
## Edges Missing
1933

2034
Likely causes:
@@ -24,6 +38,19 @@ Likely causes:
2438
- Edge style makes stroke invisible.
2539
- Edge anchor configuration points to hidden or invalid anchors.
2640

41+
Use a concrete endpoint check before changing layout:
42+
43+
```ts
44+
const nodeIds = new Set(graph.getNodes().map(node => node.get("id")));
45+
for (const edge of graph.getEdges()) {
46+
const source = edge.get("source");
47+
const target = edge.get("target");
48+
if (!nodeIds.has(source) || !nodeIds.has(target)) {
49+
console.warn("invalid edge endpoint", edge.get("id"), source, target);
50+
}
51+
}
52+
```
53+
2754
## Layout Not Updating
2855

2956
Check:
@@ -32,6 +59,9 @@ Check:
3259
- `autoLayout` is true, or `graph.layout()` is called manually.
3360
- Batch code restored `autoLayout` after disabling it.
3461
- Data update preserved IDs as intended.
62+
- The container was not hidden or zero-size when layout ran.
63+
- `fitViewAfterLayout` or a manual `fitView()` is used when newly laid-out data
64+
can land outside the current viewport.
3565

3666
## Slow Interaction
3767

@@ -43,6 +73,15 @@ Most common causes:
4373
- Auto layout/draw active during bulk mutations.
4474
- Large force layouts running continuously.
4575

76+
VGraph-specific checks:
77+
78+
- If using `@visactor/react-vgraph`, compare DOM node count against graph node
79+
count. Large graphs should usually stay canvas-first.
80+
- If interactions slow down after repeated page/component mounts, verify old
81+
graph instances were destroyed and high-frequency listeners were removed.
82+
- If force layout keeps consuming CPU, check whether the force layout is still
83+
ticking after the user expects it to settle.
84+
4685
## Batch Mutation Pattern
4786

4887
```ts

0 commit comments

Comments
 (0)