diff --git a/skills/vgraph-development-assistant/SKILL.md b/skills/vgraph-development-assistant/SKILL.md index 59f59ddc1..eeacc758a 100644 --- a/skills/vgraph-development-assistant/SKILL.md +++ b/skills/vgraph-development-assistant/SKILL.md @@ -1,6 +1,6 @@ --- name: vgraph-development-assistant -description: "Expert assistant for @visactor/vgraph, @visactor/react-vgraph, and @visactor/react-vgraph-ui. Use when the user asks to create, configure, debug, optimize, or review VGraph Graph/TreeGraph visualizations, graph data, GraphStructure, layouts (dag, force, compactBox, dendrogram, mindMap, indented, pipeline, nestedDag), behaviors (panZoom, dragCanvas, dragNode, brushSelect, highlightRelations), events (node:click, GRAPH_EVENTS), React Viewer integration, CommonFlowEditor/DAGFlowEditor, examples, blank-canvas bugs, layout bugs, performance issues, or migration/open-source docs for VGraph code." +description: "Expert assistant for @visactor/vgraph, @visactor/react-vgraph, and @visactor/react-vgraph-ui. Use when the user asks to create, configure, debug, optimize, or review VGraph Graph/TreeGraph visualizations, graph data, GraphStructure, layouts (dag, force, compactBox, dendrogram, mindMap, indented, pipeline, nestedDag), behaviors (panZoom, dragCanvas, dragNode, brushSelect, highlightRelations), events (node:click, GRAPH_EVENTS), React Viewer integration, CommonFlowEditor/DAGFlowEditor, VGraph examples, API docs, demos, blank-canvas bugs, layout bugs, performance issues, or VGraph-specific migration guidance." --- # VGraph Development Assistant @@ -28,20 +28,20 @@ If a reasonable default exists, proceed with that default and name it. ## Mandatory Routing -Read only the files needed for the task. If you load one reference, read it completely. - -| User intent or keywords | Read these files | -| --- | --- | -| Getting started, create graph, basic demo, simple snippet | `references/knowledge/00-overview.md`, then `references/examples/basic-graph.md` | -| Standalone demo page, runnable HTML demo, previewable structure diagram, knowledge map showcase, code tab | `references/examples/demo-html-page.md`, plus the relevant graph/layout/behavior references below | -| Graph vs TreeGraph vs GraphStructure | `references/knowledge/01-graph-treegraph.md`, then `references/type/graph-options.md` | -| Data, nodes, edges, groups, TreeData, GraphData | `references/knowledge/02-data-model.md` | -| Node, edge, group style, state, custom shape, anchors | `references/knowledge/03-node-edge-group.md`, then `references/type/model-options.md` | -| Layout, dag, force, tree, compactBox, mindMap, nestedDag, pipeline | `references/knowledge/04-layouts.md`, then `references/examples/tree-graph.md` for tree tasks | -| Behavior, interaction, drag, panZoom, brush select, events | `references/knowledge/05-behaviors-events.md`, then `references/type/event-types.md`, then `references/examples/events-behaviors.md` for code | -| React node, Viewer, hooks, tooltip, context menu | `references/knowledge/06-react-integration.md`, then `references/examples/react-viewer.md` | -| Editor, stack, node mover, edge editor, minimap, grid | `references/knowledge/07-components-editor.md` | -| Blank canvas, not rendering, performance, memory, export, update bugs | `references/knowledge/08-performance-debugging.md` | +Read only the files needed for the task. If you load one reference, read it completely. Do NOT load unrelated reference files just because they are nearby; keep answers grounded in the chosen route. + +| User intent or keywords | Read | Do NOT load by default | +| --- | --- | --- | +| Getting started, create graph, basic demo, simple snippet | `references/knowledge/00-overview.md`, then `references/examples/basic-graph.md` | React/editor/performance references | +| Standalone demo page, runnable HTML demo, previewable structure diagram, knowledge map showcase, code tab | `references/examples/demo-html-page.md`, plus the relevant graph/layout/behavior references below | All examples not used by the selected graph family | +| Graph vs TreeGraph vs GraphStructure | `references/knowledge/01-graph-treegraph.md`, then `references/type/graph-options.md` | React/editor examples | +| Data, nodes, edges, groups, TreeData, GraphData | `references/knowledge/02-data-model.md` | Layout examples unless layout is part of the question | +| Node, edge, group style, state, custom shape, anchors | `references/knowledge/03-node-edge-group.md`, then `references/type/model-options.md` | Demo page reference | +| Layout, dag, force, tree, compactBox, mindMap, nestedDag, pipeline | `references/knowledge/04-layouts.md`, then `references/examples/tree-graph.md` for tree tasks | React/editor references | +| Behavior, interaction, drag, panZoom, brush select, events | `references/knowledge/05-behaviors-events.md`, then `references/type/event-types.md`, then `references/examples/events-behaviors.md` for code | Layout/debug references unless needed | +| React node, Viewer, hooks, tooltip, context menu | `references/knowledge/06-react-integration.md`, then `references/examples/react-viewer.md` | Standalone HTML demo reference | +| Editor, stack, node mover, edge editor, minimap, grid | `references/knowledge/07-components-editor.md` | React Viewer example unless DOM nodes are requested | +| Blank canvas, not rendering, performance, memory, export, update bugs | `references/knowledge/08-performance-debugging.md` | Demo/examples unless reproducing | Do not load all references by default. For simple code-generation requests, one knowledge file plus one example file is usually enough. @@ -76,7 +76,9 @@ For simple examples, API usage, configuration help, or debugging answers, prefer A standard demo page should include a `Demo` tab for the live VGraph canvas and a `Code` tab for the core runnable TypeScript/JavaScript. The Code tab should be a fixed-size panel with internal scrolling (`overflow: auto`) so long examples do not expand the whole page or hide the live demo. Include a copy-code action when practical. -For large trees, knowledge maps, organization charts, or any graph that can overwhelm the viewport, add readability controls by default. Use `panZoom` and `dragCanvas`, start from a conservative overview when it helps users understand the top-level structure, and provide controls such as "expand all", "collapse details", search, filter, group focus, or fit-to-view. Implement tree collapse by keeping source data immutable, deriving visible `children` from a collapsed-ID set, and refreshing the graph with `graph.data(visibleTree)`. For non-tree Graph/DAG demos, do not force tree-collapse patterns onto edge-list data; prefer viewport, filtering, grouping, highlighting, or progressive disclosure controls. +For large trees, knowledge maps, organization charts, or any graph that can overwhelm the viewport, add readability controls by default. Use `panZoom` and `dragCanvas`, start from a conservative overview when it helps users understand the top-level structure, and provide controls such as "expand all", "collapse details", search, filter, group focus, or fit-to-view. For `TreeGraph` hierarchy expand/collapse, use native `collapse`, `expand`, or `toggleCollapse` first so the interaction stays a visibility/layout operation instead of a full data replacement. For non-tree Graph/DAG demos, do not force tree-collapse patterns onto edge-list data; prefer viewport, filtering, grouping, highlighting, or progressive disclosure controls. + +For knowledge-system or structure-map demos, preserve semantic shape before visual polish. Decide whether the requested content is a strict hierarchy, a DAG, or a general network. For school-stage or curriculum maps, keep the main levels explicit (for example stage -> subject -> topic -> skill) and avoid turning cross-links into primary parent-child edges. If the user asks for expand/collapse on a hierarchy, use `TreeGraph` native `collapse`, `expand`, or `toggleCollapse` first; do not rebuild a visible tree and call `graph.data(...)` on each click unless the user specifically needs data filtering or virtualization. After creating a standalone HTML demo, verify that it renders without console errors. If the environment supports browser preview, start or reuse a local static/dev server and provide the accessible URL; if browser preview is unavailable, say what validation was skipped and why. @@ -93,4 +95,4 @@ After creating a standalone HTML demo, verify that it renders without console er ## Verification Habit -For generated snippets, make sure the imports exist in the repo exports and the chosen data shape matches the chosen graph class. For debugging, report the smallest falsifiable check first: container size, graph size, data IDs, edge endpoints, layout choice, behavior conflicts, then React lifecycle. +For generated snippets, make sure the imports exist in `packages/vgraph/src/index.ts` or the relevant package export, and verify non-obvious config fields against source typings or implementation before suggesting them. For debugging, report the smallest falsifiable check first: container size, graph size, data IDs, edge endpoints, layout choice, behavior conflicts, then React lifecycle. diff --git a/skills/vgraph-development-assistant/references/examples/demo-html-page.md b/skills/vgraph-development-assistant/references/examples/demo-html-page.md index c4f49a9d7..710dfe1f8 100644 --- a/skills/vgraph-development-assistant/references/examples/demo-html-page.md +++ b/skills/vgraph-development-assistant/references/examples/demo-html-page.md @@ -15,6 +15,10 @@ A polished standalone demo should contain: - For large tree or hierarchy demos, an initial collapsed view and controls such as `Expand all` and `Collapse details`. - For large non-tree Graph/DAG demos, readability controls such as fit-to-view, search/highlight, filtering, grouping, or progressive disclosure. Do not force tree-collapse patterns onto edge-list data. +Keep generic HTML/CSS minimal. Spend tokens on VGraph data shape, layout, +behaviors, interaction controls, and runtime verification rather than decorative +page chrome. + ## Minimal HTML shell For a real standalone HTML file, use an executable module script. Prefer a local @@ -130,7 +134,13 @@ for (const tab of tabs) { ## Tree collapse pattern -Use `TreeGraph` for nested `children` data. Keep the original full tree immutable, derive a visible tree from collapsed IDs, and call `graph.data(visibleTree)` after each toggle. +Use `TreeGraph` for nested `children` data. Prefer the native collapse API: +`graph.collapse(node)`, `graph.expand(node)`, or `graph.toggleCollapse(node)`. +Do not implement ordinary expand/collapse by deriving a new visible tree and +calling `graph.data(...)` on every click; that turns a visibility interaction +into a data update, re-layout, redraw, and possible animation replay. Use the +visible-tree pattern only when the user needs true data filtering, +virtualization, or server-side paging. ```ts import { TreeGraph, panZoom, dragCanvas } from "@visactor/vgraph"; @@ -143,7 +153,6 @@ interface TreeNode { children?: TreeNode[]; } -const collapsedIds = new Set(); const nodeMap = new Map(); function walkTree(node: TreeNode, visitor: (node: TreeNode) => void) { @@ -153,33 +162,14 @@ function walkTree(node: TreeNode, visitor: (node: TreeNode) => void) { walkTree(sourceTree, node => { nodeMap.set(node.id, node); - if (node.children?.length && node.level === "module") { - collapsedIds.add(node.id); - } + node.collapsed = Boolean(node.children?.length && node.level === "module"); }); -function cloneVisibleNode(node: TreeNode): TreeNode { - const children = node.children ?? []; - const collapsed = children.length > 0 && collapsedIds.has(node.id); - const next: TreeNode = { - ...node, - collapsed, - name: children.length ? `${collapsed ? "▸" : "▾"} ${node.name}` : node.name - }; - - if (children.length && !collapsed) { - next.children = children.map(cloneVisibleNode); - } else { - delete next.children; - } - - return next; -} - const graph = new TreeGraph({ container: "container", width, height, + animate: false, layout: { type: "compactBox", options: { direction: "LR" } @@ -197,10 +187,6 @@ const graph = new TreeGraph({ }) }); -function renderTree() { - graph.data(cloneVisibleNode(sourceTree)); -} - graph.addBehavior(panZoom, { sensitivity: 4 }); graph.addBehavior(dragCanvas); @@ -208,15 +194,16 @@ graph.on("node:click", ev => { const id = ev?.target?.get?.("id"); if (!id || !nodeMap.get(id)?.children?.length) return; - if (collapsedIds.has(id)) collapsedIds.delete(id); - else collapsedIds.add(id); - - renderTree(); + graph.toggleCollapse(ev.target); }); -renderTree(); +graph.data(sourceTree); ``` +Set `animate: false` for static knowledge-map demos when repeated expand/collapse +should feel instant and not replay layout transitions. Keep animation on only +when the transition itself is part of the requested experience. + ## Verification After creating the HTML file, open it through a local static/dev server when possible and check the browser console. The expected result is a visible graph in the Demo tab, a scrollable Code tab, working copy-code behavior if included, and no console errors. If browser preview is unavailable, state that runtime validation was skipped instead of implying it passed. diff --git a/skills/vgraph-development-assistant/references/knowledge/04-layouts.md b/skills/vgraph-development-assistant/references/knowledge/04-layouts.md index b4877e922..54326d876 100644 --- a/skills/vgraph-development-assistant/references/knowledge/04-layouts.md +++ b/skills/vgraph-development-assistant/references/knowledge/04-layouts.md @@ -33,10 +33,12 @@ Batch pattern: const autoDraw = graph.disableAutoDraw(); const autoLayout = graph.disableAutoLayout(); -graph.updateData(nextData); - -graph.enableAutoLayout(autoLayout); -graph.enableAutoDraw(autoDraw); +try { + graph.updateData(nextData); +} finally { + graph.enableAutoLayout(autoLayout); + graph.enableAutoDraw(autoDraw); +} ``` If layout still does not appear to run: diff --git a/skills/vgraph-development-assistant/references/knowledge/05-behaviors-events.md b/skills/vgraph-development-assistant/references/knowledge/05-behaviors-events.md index d8cf46de2..0f971f6b9 100644 --- a/skills/vgraph-development-assistant/references/knowledge/05-behaviors-events.md +++ b/skills/vgraph-development-assistant/references/knowledge/05-behaviors-events.md @@ -25,9 +25,18 @@ Some behaviors accept options: ```ts graph.addBehavior(panZoom, { sensitivity: 5 }); -graph.addBehavior(dragCanvas, { eventType: "right" }); +graph.addBehavior(dragCanvas, { + shouldTrigger(event) { + return !event.target || event.target.type === "canvas"; + } +}); ``` +`dragCanvas` does not expose an `eventType: "right"` option. Its built-in +trigger rejects right-button drags (`nativeEvent.buttons === 2`). Use +`shouldTrigger`, `canvasOnly`, `xOnly`, `yOnly`, `limit`, or behavior mode +switching instead of inventing event-type configuration. + Remove by behavior config or type string: ```ts