YASGUI Graph Plugin

A YASGUI plugin for visualizing SPARQL CONSTRUCT and DESCRIBE query results as interactive graphs with nodes (subjects/objects) and edges (predicates).

✨ Features

🔷 Interactive Graph Visualization: Automatic force-directed layout with smooth physics-based positioning
🎨 Smart Color Coding:
- 🔵 Light Blue (#97C2FC) = URIs
- 🟢 Light Green (#a6c8a6ff) = Literals
- ⚪ Light Grey (#c5c5c5ff) = Blank nodes
- 🟠 Orange (#e15b13ff) = rdf:type objects (classes)
🔍 Navigation: Mouse wheel zoom, drag to pan, "Zoom to Fit" button
✋ Drag & Drop: Reorganize nodes by dragging them to new positions
💬 Tooltips: Hover for full URI/literal details (300ms delay)
⚡ Performance: Handles up to 1,000 nodes with <2s render time
♿ Accessible: WCAG AA color contrast, keyboard navigation support

📦 Installation

NPM

npm install @matdata/yasgui-graph-plugin @zazuko/yasgui vis-network

import Yasgui from '@zazuko/yasgui';
import GraphPlugin from '@matdata/yasgui-graph-plugin';

Yasgui.Yasr.registerPlugin('Graph', GraphPlugin);

const yasgui = new Yasgui(document.getElementById('yasgui'));

CDN (UMD)

<!-- YASGUI -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@zazuko/yasgui@4/build/yasgui.min.css">
<script src="https://cdn.jsdelivr.net/npm/@zazuko/yasgui@4/build/yasgui.min.js"></script>

<!-- Graph Plugin -->
<script src="https://cdn.jsdelivr.net/npm/@matdata/yasgui-graph-plugin/dist/yasgui-graph-plugin.min.js"></script>

<script>
  // Plugin auto-registers as 'graph'
  const yasgui = new Yasgui(document.getElementById('yasgui'));
</script>

🚀 Quick Start

See the complete working example in demo/index.html.

Basic Usage

const yasgui = new Yasgui(document.getElementById('yasgui'), {
  requestConfig: { 
    endpoint: 'https://dbpedia.org/sparql' 
  }
});

Sample Queries

CONSTRUCT Query:

PREFIX ex: <http://example.org/>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>

CONSTRUCT {
  ex:Alice rdf:type ex:Person .
  ex:Alice ex:knows ex:Bob .
  ex:Alice ex:name "Alice" .
  ex:Bob rdf:type ex:Person .
  ex:Bob ex:name "Bob" .
}
WHERE {}

DESCRIBE Query:

PREFIX ex: <http://example.org/>

# Returns all triples about the specified resources
DESCRIBE ex:Alice ex:Bob

After running the query, click the "Graph" tab to see the visualization.

🎮 User Guide

Navigation

Zoom: Mouse wheel (scroll up = zoom in, scroll down = zoom out)
Pan: Click and drag the background
Fit to View: Click the "Zoom to Fit" button to center the entire graph

Interaction

Drag Nodes: Click and drag any node to reposition it
Tooltips: Hover over nodes/edges for 300ms to see full details

Understanding Colors

| Color | Meaning | Example | |-------|---------|---------|| | 🔵 Light Blue (#97C2FC) | URI nodes | ex:Person, ex:Alice | | 🟢 Light Green (#a6c8a6ff) | Literal values | "Alice", "30"^^xsd:integer | | ⚪ Light Grey (#c5c5c5ff) | Blank nodes | _:b1, _:addr1 | | 🟠 Orange (#e15b13ff) | rdf:type objects (classes) | ex:Person in ex:Alice rdf:type ex:Person |

⚙️ Configuration

The plugin uses sensible defaults but can be customized by extending the GraphPlugin class:

class CustomGraphPlugin extends GraphPlugin {
  constructor(yasr) {
    super(yasr);
  }
  
  // Override network options
  getNetworkOptions() {
    return {
      ...super.getNetworkOptions(),
      physics: {
        enabled: true,
        stabilization: { iterations: 100 } // Faster but less optimal layout
      }
    };
  }
}

Yasgui.Yasr.registerPlugin('customGraph', CustomGraphPlugin);

🔧 Development

Build

npm install
npm run build

Output: dist/yasgui-graph-plugin.min.js

Local Testing

Build the plugin: npm run build
Open example/index.html in a browser
Try the sample queries in different tabs

Code Quality

npm run lint    # ESLint check
npm run format  # Prettier format

📚 Documentation

Quickstart Guide - Installation, usage, troubleshooting
Data Model - Entity definitions and relationships
Contracts - API specifications for YASR plugin and vis-network integration
Specification - Complete feature specification
[Constitution](./. specify/memory/constitution.md) - Project governance and principles

🧪 Browser Compatibility

Tested on latest 2 versions of:

✅ Chrome
✅ Firefox
✅ Safari
✅ Edge

Requires ES2018+ support and Canvas API.

🤝 Contributing

Contributions welcome! Please follow the project constitution (.specify/memory/constitution.md) for governance principles:

Plugin-First Architecture - No YASGUI core modifications
Visualization Quality - Performance (<2s for 1k nodes), accessibility (WCAG AA)
Configuration Flexibility - Sensible defaults, but customizable
Browser Compatibility - ES2018+, latest 2 browser versions
Documentation - Keep docs updated with changes

📄 License

Apache 2.0

🙏 Acknowledgments

Built with vis-network for graph rendering
Integrates with YASGUI SPARQL editor
Follows the yasgui-geo plugin pattern

📊 Project Status

Current Version: 0.1.0 (MVP)

Implemented Features (v0.1.0):

✅ Basic graph visualization (US1)
✅ Navigation controls (US2)
✅ Color-coded nodes
✅ Prefix abbreviation
✅ Blank node support
✅ Performance optimization

Planned Features (Future):

⏳ Enhanced tooltips with datatype display (US4)
⏳ Manual testing across all browsers (US3 verification)
⏳ Large graph optimization (>1k nodes)
⏳ Custom color schemes
⏳ Layout algorithm selection

🐛 Troubleshooting

Plugin tab not showing

Verify plugin is registered correctly
Check browser console for errors
Verify YASGUI version is ^4.0.0

Empty visualization

Ensure query type is CONSTRUCT or DESCRIBE
Confirm query returns triples (check "Table" or "Response" tab)
Verify results have RDF structure

Performance issues

Limit results to <1000 nodes for best performance
Disable physics after initial layout
Consider using LIMIT clause in SPARQL query

For more help, see Quickstart Guide - Troubleshooting.

🛠️ Development

Setup

git clone https://github.com/yourusername/yasgui-graph-plugin.git
cd yasgui-graph-plugin
npm install

Dev Workflow (Live Reload)

The project supports live development - edit source files and see changes immediately without rebuilding:

Start a local dev server (any HTTP server will work):

# Using Python
python -m http.server 8000

# Using Node.js (http-server)
npx http-server -p 8000

# Using VS Code Live Server extension
# Right-click demo/index.html → "Open with Live Server"

Open demo in browser:
```
http://localhost:8000/demo/index.html
```

Edit source files (e.g., src/colorUtils.js):

export function getNodeColor(node) {
  // Change colors here
  if (node.isBlankNode) return '#FF00FF'; // Magenta
  // ...
}

Refresh browser - changes appear immediately! ⚡

The demo automatically loads ES modules directly from src/ in development mode, so no rebuild is needed.

Production Build

Build the minified UMD bundle for distribution:

npm run build

Output: dist/yasgui-graph-plugin.min.js (bundled with vis-network)

Testing

npm test          # Run all tests
npm run lint      # Check code style
npm run format    # Auto-fix formatting

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
.github		.github
.specify		.specify
.vscode		.vscode
demo		demo
specs/001-construct-graph-viz		specs/001-construct-graph-viz
src		src
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
RELEASE_NOTES_INSTRUCTIONS.md		RELEASE_NOTES_INSTRUCTIONS.md
esbuild.config.js		esbuild.config.js
package-lock.json		package-lock.json
package.json		package.json

License

Matdata-eu/yasgui-graph-plugin

Folders and files

Latest commit

History

Repository files navigation