Skip to content

Commit cb55742

Browse files
carloseberhardtcarloseberhardt
authored
switched to d3 for schema visualizer. added list of future fixes/enhancements (#100)
1 parent 23778d7 commit cb55742

File tree

4 files changed

+861
-504
lines changed

4 files changed

+861
-504
lines changed

‎docs/visualizer.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
<!--
2+
Copyright IBM Corp. 2025
3+
Assisted by CursorAI
4+
-->
5+
6+
# StepZen Schema Visualizer
7+
8+
The StepZen Schema Visualizer provides an interactive, force-directed graph visualization of GraphQL schemas, helping developers understand type relationships and schema structure.
9+
10+
## Current Features
11+
12+
### Core Visualization
13+
14+
- **Force-directed layout**: Uses D3.js physics simulation for natural node positioning
15+
- **Dual attachment points**: Smart connection routing with left/right attachment optimization
16+
- **Type boxes**: Professional-styled boxes with headers and field sections
17+
- **Field-to-type connections**: Curved lines connecting specific fields to their referenced types
18+
- **Scalar type filtering**: Excludes scalar types to reduce visual clutter
19+
20+
### Interactive Features
21+
22+
- **Click navigation**: Navigate to type/field definitions in source code
23+
- **Drag and drop**: Manual repositioning without simulation interference
24+
- **Zoom and pan**: Full viewport control with mouse wheel and drag
25+
- **Search functionality**: Find types and fields with highlighting and navigation
26+
- **Auto-fit**: Automatic layout with generous padding on initial load
27+
28+
### Visual Design
29+
30+
- **Theme awareness**: Adapts to VS Code light/dark themes
31+
- **Color-coded types**: Different colors for scalar, list, and object types
32+
- **Root type highlighting**: Special styling for Query/Mutation/Subscription
33+
- **Hover effects**: Interactive feedback on field boxes
34+
- **Connection labels**: Field names displayed along connection paths
35+
36+
## Architecture
37+
38+
### Technology Stack
39+
40+
- **D3.js v7**: Force simulation and SVG rendering
41+
- **VS Code Webview API**: Integration with editor
42+
- **TypeScript**: Type safety and IntelliSense support
43+
44+
### Code Organization
45+
46+
```
47+
webview/js/schema-visualizer.js # Main visualization logic
48+
├── Constants # Visual and layout parameters
49+
├── Data Processing # Schema model transformation
50+
├── Force Simulation # D3.js physics setup
51+
├── Connection System # Dual attachment point logic
52+
├── Interaction Handlers # Drag, zoom, search, navigation
53+
└── Utility Functions # Position calculations, auto-fit
54+
```
55+
56+
### Key Components
57+
58+
1. **Schema Model**: Processed from StepZen schema index
59+
2. **Node System**: Type boxes with headers and field sections
60+
3. **Connection System**: Smart routing between fields and types
61+
4. **Layout Engine**: D3.js force simulation with collision detection
62+
5. **Interaction Layer**: Mouse/keyboard event handling
63+
64+
## Performance Considerations
65+
66+
### Current Optimizations
67+
68+
- Scalar type filtering reduces node count
69+
- Simulation stops after initial layout
70+
- Efficient SVG rendering with proper z-ordering
71+
72+
### Known Performance Issues
73+
74+
- Connection path calculations run on every tick
75+
- Label positioning recalculates bezier math redundantly
76+
- No caching of computed positions when nodes are static
77+
78+
## Future Enhancements
79+
80+
### High Priority Performance Optimizations
81+
82+
- [ ] **Connection caching**: Cache path calculations when nodes aren't moving
83+
- [ ] **Shared computation**: Combine path and label calculations
84+
- [ ] **Debounced search**: Improve search input responsiveness
85+
- [ ] **Lazy rendering**: Virtualize large schemas
86+
- [ ] **Web Workers**: Offload heavy calculations
87+
88+
### High Priority Code Organization
89+
90+
- [ ] **Modular architecture**: Split into focused modules
91+
- [ ] **Configuration system**: Centralized settings management
92+
- [ ] **Error boundaries**: Graceful degradation strategies
93+
- [ ] **Unit testing**: Test coverage for core functions
94+
- [ ] **Documentation**: JSDoc comments and API docs
95+
96+
### Visual Improvements
97+
98+
- [ ] **Smart routing**: Pathfinding algorithm to avoid crossing type boxes
99+
- [ ] **Connection bundling**: Group multiple connections between same types
100+
- [ ] **Minimap**: Overview navigation for large schemas
101+
- [ ] **Type grouping**: Cluster related types by domain/namespace
102+
- [ ] **Collapsible sections**: Hide/show fields to reduce complexity
103+
- [ ] **Connection filtering**: Show only selected type relationships
104+
- [ ] **Animation system**: Smooth transitions for layout changes
105+
106+
### Interaction Features
107+
108+
- [ ] **Multi-select**: Bulk operations on multiple types
109+
- [ ] **Connection highlighting**: Highlight paths on hover
110+
- [ ] **Breadcrumb navigation**: Track focused view history
111+
- [ ] **Keyboard shortcuts**: Common actions (zoom, search, navigate)
112+
- [ ] **Context menus**: Right-click operations
113+
- [ ] **Touch support**: Mobile/tablet interaction
114+
- [ ] **Accessibility**: Screen reader and keyboard navigation
115+
116+
### Schema Analysis
117+
118+
- [ ] **Dependency analysis**: Show all types that depend on selected type
119+
- [ ] **Circular dependency detection**: Highlight problematic relationships
120+
- [ ] **Schema metrics**: Complexity, depth, and usage statistics
121+
- [ ] **Unused type detection**: Identify orphaned types
122+
- [ ] **Schema diff**: Compare different schema versions
123+
- [ ] **Performance impact**: Analyze query complexity implications
124+
- [ ] **Validation warnings**: Overlay schema issues
125+
126+
### Export and Integration
127+
128+
- [ ] **Export formats**: SVG, PNG, PDF generation
129+
- [ ] **Documentation generation**: Auto-generate docs from visualization
130+
- [ ] **GraphQL Playground**: Integration with query testing
131+
- [ ] **Schema validation**: Real-time error highlighting
132+
- [ ] **Version control**: Track schema evolution over time
133+
- [ ] **Sharing**: Shareable links for specific views
134+
135+
### Layout Options
136+
137+
- [ ] **Multiple algorithms**: Hierarchical, circular, tree layouts
138+
- [ ] **Layout persistence**: Save/load custom arrangements
139+
- [ ] **Layout suggestions**: AI-powered optimal arrangements
140+
- [ ] **Responsive design**: Adapt to different screen sizes
141+
- [ ] **Print optimization**: Layout suitable for documentation
142+
143+
### Advanced Features
144+
145+
- [ ] **Schema comparison**: Side-by-side diff visualization
146+
- [ ] **Query path tracing**: Visualize resolver execution paths
147+
- [ ] **Federation support**: Multi-service schema visualization
148+
- [ ] **Real-time updates**: Live schema change detection
149+
- [ ] **Collaborative features**: Shared viewing sessions
150+
- [ ] **Plugin system**: Extensible visualization components
151+
152+
## Development Guidelines
153+
154+
### Adding New Features
155+
156+
1. Follow the existing modular pattern
157+
2. Add constants for magic numbers
158+
3. Include defensive null checks
159+
4. Update this documentation
160+
5. Consider performance implications
161+
162+
### Testing Strategy
163+
164+
- Unit tests for utility functions
165+
- Integration tests for D3.js interactions
166+
- Visual regression tests for layout consistency
167+
- Performance benchmarks for large schemas
168+
169+
### Code Quality
170+
171+
- TypeScript strict mode enabled
172+
- ESLint configuration enforced
173+
- Consistent error handling patterns
174+
- Comprehensive logging for debugging
175+
176+
---
177+
178+
_Portions of the Content may be generated with the assistance of CursorAI_

‎src/panels/schemaVisualizerPanel.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -480,6 +480,7 @@ class SchemaVisualizerPanel extends BaseWebviewPanel {
480480
const { schemaModel, focusedType } = data;
481481
// Load resources
482482
const jointJsUri = this.getWebviewUri(webview, ["libs", "joint.min.js"]);
483+
const d3JsUri = this.getWebviewUri(webview, ["libs", "d3.min.js"]);
483484
const customJsUri = this.getWebviewUri(webview, ["js", "schema-visualizer.js"]);
484485
const customCssUri = this.getWebviewUri(webview, ["css", "schema-visualizer.css"]);
485486
const nonce = this.nonce();
@@ -547,6 +548,7 @@ class SchemaVisualizerPanel extends BaseWebviewPanel {
547548
<button id="zoom-out" title="Zoom out">-</button>
548549
<button id="reset" title="Reset view">Reset</button>
549550
<button id="refresh" title="Refresh schema data">🔄</button>
551+
550552
<div style="position: relative; flex: 1; display: flex; align-items: center;">
551553
<input type="text" id="search" placeholder="Search for types or fields..." style="width: 100%;">
552554
<!-- Search navigation buttons will be added by JS -->
@@ -556,6 +558,9 @@ class SchemaVisualizerPanel extends BaseWebviewPanel {
556558
557559
<!-- Load JointJS v4 first -->
558560
<script nonce="${nonce}" src="${jointJsUri}"></script>
561+
562+
<!-- Load D3.js for force simulation -->
563+
<script nonce="${nonce}" src="${d3JsUri}"></script>
559564
560565
<!-- Then pass data and create navigator function -->
561566
<script nonce="${nonce}">

0 commit comments

Comments
 (0)