You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: specs/001-construct-graph-viz/plan.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,9 +7,9 @@
7
7
8
8
## Summary
9
9
10
-
**Primary Requirement**: Create a YASGUI plugin that visualizes SPARQL CONSTRUCT query results as interactive graphs with nodes (subjects/objects) and edges (predicates), supporting zoom, drag, tooltips, color coding by node type, and PNG image export.
10
+
**Primary Requirement**: Create a YASGUI plugin that visualizes SPARQL CONSTRUCT query results as interactive graphs with nodes (subjects/objects) and edges (predicates), supporting zoom, drag, tooltips and color coding by node type.
11
11
12
-
**Technical Approach**: Implement a YASR plugin class following the yasgui-geo pattern (constructor, canHandleResults, draw, getIcon methods) using vis-network v9.x for graph rendering. Parse RDF triples from bindings format, transform to vis-network DataSets with color-coded nodes (grey literals, green rdf:type objects, blue other URIs), apply prefix abbreviation, and leverage vis-network's built-in force-directed layout, interaction, and export capabilities. Build with esbuild to UMD format for `Yasgui.Yasr.registerPlugin()` registration.
12
+
**Technical Approach**: Implement a YASR plugin class following the yasgui-geo pattern (constructor, canHandleResults, draw, getIcon methods) using vis-network v9.x for graph rendering. Parse RDF triples from bindings format, transform to vis-network DataSets with color-coded nodes (grey literals, green rdf:type objects, blue other URIs), apply prefix abbreviation, and leverage vis-network's built-in force-directed layoutand interaction. Build with esbuild to UMD format for `Yasgui.Yasr.registerPlugin()` registration.
- No additional layout libraries needed - vis-network handles all requirements
15
15
- Browser compatibility excellent (ES2018+ with Canvas rendering)
@@ -32,7 +32,6 @@
32
32
-**Built-in physics engine**: Force-directed and hierarchical layouts out of the box, no additional configuration
33
33
-**Interaction model**: Native support for zoom (mouse wheel), pan (drag background), node dragging, tooltips (hover events)
34
34
-**Performance**: Handles 1000+ nodes smoothly with physics stabilization optimization
35
-
-**Export**: Built-in methods for canvas-to-image conversion (PNG/SVG via canvas API)
36
35
-**API simplicity**: `Network(container, data, options)` - single constructor with straightforward data model
37
36
-**Browser compatibility**: Canvas-based rendering, works on all modern browsers (Chrome, Firefox, Safari, Edge)
38
37
-**Size**: ~500KB minified (~150KB gzipped) - reasonable for functionality provided
@@ -313,34 +312,7 @@ function applyPrefix(uri, prefixes) {
313
312
314
313
**Decision**: Extract prefixes from YASR query context, apply to all URIs. Include common RDF/RDFS/XSD defaults. Truncate unprefixed URIs with ellipsis.
315
314
316
-
### 6. Export Image Functionality
317
-
318
-
**Question**: How to implement "save as image" for current viewport?
319
-
320
-
**vis-network approach**:
321
-
```javascript
322
-
// Get canvas element from network
323
-
constcanvas=network.canvas.frame.canvas;
324
-
325
-
// Export as PNG
326
-
functionexportPNG() {
327
-
canvas.toBlob(blob=> {
328
-
consturl=URL.createObjectURL(blob);
329
-
consta=document.createElement('a');
330
-
a.href= url;
331
-
a.download='graph-visualization.png';
332
-
a.click();
333
-
URL.revokeObjectURL(url);
334
-
});
335
-
}
336
-
337
-
// Export as SVG (requires dom-to-image library or manual SVG creation)
338
-
// vis-network doesn't directly support SVG export, PNG is primary format
339
-
```
340
-
341
-
**Decision**: Implement PNG export using canvas.toBlob(). SVG export would require additional library (dom-to-image) - defer to future enhancement, PNG sufficient for success criteria.
342
-
343
-
### 7. Performance Optimization
315
+
### 6. Performance Optimization
344
316
345
317
**Question**: How to meet <2s rendering target for 1000 nodes?
346
318
@@ -373,7 +345,7 @@ const options = {
373
345
374
346
**Decision**: Use default physics settings with 200 iteration limit. Disable physics after stabilization to improve interaction performance. Monitor performance in testing phase.
375
347
376
-
### 8. Responsive Layout
348
+
### 7. Responsive Layout
377
349
378
350
**Question**: How to ensure graph fills 100% of YASR container space?
Copy file name to clipboardExpand all lines: specs/001-construct-graph-viz/spec.md
+12-36Lines changed: 12 additions & 36 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,13 +3,12 @@
3
3
**Feature Branch**: `001-construct-graph-viz`
4
4
**Created**: 2025-12-05
5
5
**Status**: Draft
6
-
**Input**: User description: "Visualize SPARQL CONSTRUCT query results as interactive graphs with nodes (subjects/objects) and edges (predicates), supporting zoom, drag, tooltips, color coding, and image export"
6
+
**Input**: User description: "Visualize SPARQL CONSTRUCT query results as interactive graphs with nodes (subjects/objects) and edges (predicates), supporting zoom, drag, tooltipsand color coding"
7
7
8
8
## Clarifications
9
9
10
10
### Session 2025-12-06
11
11
12
-
- Q: When a user exports the graph visualization as an image, what should be the exact scope of the export? → A: Export only the visible viewport content at current zoom/pan level (what user currently sees)
13
12
- Q: What visual styling should be used for graph nodes to distinguish between different node types and content lengths? → A: All nodes use uniform shape (circle/ellipse) with fixed size, regardless of label length or type
14
13
- Q: How should tooltips be triggered and displayed to balance information access with usability? → A: Hover only with 300ms delay before showing, auto-hide on mouse leave
15
14
- Q: How should the plugin handle blank nodes (anonymous RDF nodes with no URI) that appear in CONSTRUCT results? → A: Display with generated label but use unique color (e.g., yellow) to distinguish from literals
@@ -84,22 +83,6 @@ While exploring the graph, the user wants to see detailed information about node
84
83
85
84
---
86
85
87
-
### User Story 5 - Export Visualization (Priority: P5)
88
-
89
-
After exploring and potentially adjusting the graph, the user wants to save the current view as an image for documentation, presentations, or reports. They should be able to export exactly what they see in the viewport.
90
-
91
-
**Why this priority**: Essential for knowledge sharing and documentation, but only valuable after graph is rendered and explored (depends on P1, P2). Lowest priority as core functionality works without it.
92
-
93
-
**Independent Test**: Render and navigate to a specific view, click export, and verify the downloaded image matches the current viewport appearance.
94
-
95
-
**Acceptance Scenarios**:
96
-
97
-
1.**Given** a rendered graph at any zoom/pan level, **When** the user clicks "save as image" control, **Then** the browser downloads a PNG/SVG file showing only the visible viewport content at current zoom/pan (not the entire graph)
98
-
2.**Given** a graph with manually repositioned nodes, **When** the user exports the image, **Then** the exported image reflects the current node positions and zoom level exactly as displayed in viewport
99
-
3.**Given** a graph is exported, **When** the user opens the image file, **Then** the image has sufficient resolution for readable labels and maintains aspect ratio of the viewport
100
-
101
-
---
102
-
103
86
### Edge Cases
104
87
105
88
-**Empty results**: What happens when a CONSTRUCT query returns zero triples? → Display empty state message "No graph data to visualize"
@@ -163,20 +146,15 @@ After exploring and potentially adjusting the graph, the user wants to save the
163
146
-**FR-025**: Plugin MUST display tooltip after 300ms hover delay over edges showing the full prefixed predicate URI
164
147
-**FR-026**: Plugin MUST hide tooltips when cursor leaves element boundary (auto-hide on mouse leave)
165
148
166
-
#### Export
167
-
168
-
-**FR-027**: Plugin MUST provide "save as image" control that exports only the visible viewport content at current zoom/pan level as a downloadable image file
169
-
-**FR-028**: Plugin MUST export image in PNG or SVG format with sufficient resolution for readable labels
170
-
171
149
#### Edge Case Handling
172
150
173
-
-**FR-029**: Plugin MUST display empty state message when CONSTRUCT query returns zero triples
174
-
-**FR-030**: Plugin MUST handle self-referencing triples (subject equals object) by rendering loop edges
175
-
-**FR-031**: Plugin MUST handle blank nodes by creating nodes with generated labels and yellow color
176
-
-**FR-032**: Plugin MUST render multiple predicates between the same node pair as separate parallel edges with curved/offset paths
177
-
-**FR-033**: Plugin MUST truncate very long URI labels with ellipsis while preserving full URI in tooltips
178
-
-**FR-034**: Plugin MUST truncate literal labels exceeding ~50 characters while preserving full value in tooltips
179
-
-**FR-035**: Plugin MUST de-duplicate identical triples (same subject, predicate, object) to avoid rendering duplicate edges
151
+
-**FR-028**: Plugin MUST display empty state message when CONSTRUCT query returns zero triples
152
+
-**FR-029**: Plugin MUST handle self-referencing triples (subject equals object) by rendering loop edges
153
+
-**FR-030**: Plugin MUST handle blank nodes by creating nodes with generated labels and yellow color
154
+
-**FR-031**: Plugin MUST render multiple predicates between the same node pair as separate parallel edges with curved/offset paths
155
+
-**FR-032**: Plugin MUST truncate very long URI labels with ellipsis while preserving full URI in tooltips
156
+
-**FR-033**: Plugin MUST truncate literal labels exceeding ~50 characters while preserving full value in tooltips
157
+
-**FR-034**: Plugin MUST de-duplicate identical triples (same subject, predicate, object) to avoid rendering duplicate edges
180
158
181
159
### Key Entities
182
160
@@ -203,11 +181,10 @@ After exploring and potentially adjusting the graph, the user wants to save the
203
181
-**SC-001**: Users can visualize CONSTRUCT query results as graphs within 2 seconds of receiving results (for graphs up to 1,000 nodes)
204
182
-**SC-002**: Users can identify node types (literal vs. blank node vs. URI vs. type instance) through color coding without reading labels (grey/yellow/blue/green)
205
183
-**SC-003**: Users can navigate graphs of any size by zooming and panning without performance degradation
206
-
-**SC-004**: Users can export publication-ready images of graph visualizations with readable labels
207
-
-**SC-005**: Users can reorganize graph layouts manually to improve understanding of relationships
208
-
-**SC-006**: Users can access full URI details for any node or edge via hover tooltips
209
-
-**SC-007**: Plugin maintains responsive layout across all YASR container sizes (from 320px mobile to 4K desktop)
210
-
-**SC-008**: Graph rendering completes successfully for 95% of valid CONSTRUCT query results without errors or empty states (excluding intentionally empty results)
184
+
-**SC-004**: Users can reorganize graph layouts manually to improve understanding of relationships
185
+
-**SC-005**: Users can access full URI details for any node or edge via hover tooltips
186
+
-**SC-006**: Plugin maintains responsive layout across all YASR container sizes (from 320px mobile to 4K desktop)
187
+
-**SC-007**: Graph rendering completes successfully for 95% of valid CONSTRUCT query results without errors or empty states (excluding intentionally empty results)
211
188
212
189
## Assumptions
213
190
@@ -218,4 +195,3 @@ After exploring and potentially adjusting the graph, the user wants to save the
218
195
- Modern browsers support Canvas or SVG rendering for graph visualization (covered by constitution's browser compatibility requirements)
219
196
- Force-directed layout algorithms are acceptable for automatic node positioning (no specific layout algorithm mandated)
220
197
- Graph visualizations do not require persistence - each query execution produces a fresh visualization
221
-
- Export image resolution is suitable for screen viewing and standard print (no poster-size export required)
0 commit comments