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)
• 🌓 Theme Support: Automatic light/dark mode detection and dynamic color switching
• ⚡ 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

import Yasgui from '@matdata/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/@matdata/yasgui/build/yasgui.min.css">
<script src="https://cdn.jsdelivr.net/npm/@matdata/yasgui/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.esm.js (ES Module for bundlers)
• dist/yasgui-graph-plugin.cjs.js (CommonJS for Node.js)
• dist/yasgui-graph-plugin.min.js (IIFE for browsers/unpkg)
• dist/index.d.ts (TypeScript declarations)

Local Testing

1. Build the plugin: npm run build
2. Open demo/index.html in a browser (or run npm run dev)
3. 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:

1. Plugin-First Architecture - No YASGUI core modifications
2. Visualization Quality - Performance (<2s for 1k nodes), accessibility (WCAG AA)
3. Configuration Flexibility - Sensible defaults, but customizable
4. Browser Compatibility - ES2018+, latest 2 browser versions
5. 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
• Ensure you're running a CONSTRUCT or DESCRIBE query

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:

1. 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"

2. Open demo in browser:

   http://localhost:8000/demo/index.html

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

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

4. 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 all distribution formats:

npm run build

Outputs:

• dist/yasgui-graph-plugin.esm.js - ES Module format (bundled with vis-network)
• dist/yasgui-graph-plugin.cjs.js - CommonJS format (bundled with vis-network)
• dist/yasgui-graph-plugin.min.js - IIFE browser bundle (bundled with vis-network)
• dist/index.d.ts - TypeScript type declarations

Testing

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