{"id":36952198,"url":"https://github.com/matdata-eu/yasgui-graph-plugin","last_synced_at":"2026-02-28T16:01:18.401Z","repository":{"id":328992880,"uuid":"1110867345","full_name":"Matdata-eu/yasgui-graph-plugin","owner":"Matdata-eu","description":"A plugin for Yasgui to explore a query result with a graph vizualisation","archived":false,"fork":false,"pushed_at":"2026-02-28T11:55:54.000Z","size":369,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-28T12:31:22.098Z","etag":null,"topics":["graph","knowledge","rdf","sparql","yasgui"],"latest_commit_sha":null,"homepage":"https://matdata-eu.github.io/yasgui-graph-plugin/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Matdata-eu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-05T21:05:58.000Z","updated_at":"2026-02-28T11:24:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Matdata-eu/yasgui-graph-plugin","commit_stats":null,"previous_names":["matdata-eu/yasgui-graph-plugin"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/Matdata-eu/yasgui-graph-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Matdata-eu%2Fyasgui-graph-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Matdata-eu%2Fyasgui-graph-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Matdata-eu%2Fyasgui-graph-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Matdata-eu%2Fyasgui-graph-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Matdata-eu","download_url":"https://codeload.github.com/Matdata-eu/yasgui-graph-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Matdata-eu%2Fyasgui-graph-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29941795,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T13:49:17.081Z","status":"ssl_error","status_checked_at":"2026-02-28T13:48:50.396Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["graph","knowledge","rdf","sparql","yasgui"],"created_at":"2026-01-13T12:21:37.004Z","updated_at":"2026-02-28T16:01:18.388Z","avatar_url":"https://github.com/Matdata-eu.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# YASGUI Graph Plugin\r\n\r\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\r\n[![npm version](https://img.shields.io/npm/v/@matdata/yasgui-graph-plugin.svg)](https://www.npmjs.com/package/@matdata/yasgui-graph-plugin)\r\n\r\nA YASGUI plugin for visualizing SPARQL CONSTRUCT and DESCRIBE query results as interactive graphs with nodes (subjects/objects) and edges (predicates).\r\n\r\n## ✨ Features\r\n\r\n- **🔷 Interactive Graph Visualization**: Automatic force-directed layout with smooth physics-based positioning\r\n- **🎨 Smart Color Coding**: \r\n  - 🔵 Light Blue (#97C2FC) = URIs\r\n  - 🟢 Light Green (#a6c8a6ff) = Literals\r\n  - ⚪ Light Grey (#c5c5c5ff) = Blank nodes\r\n  - 🟠 Orange (#e15b13ff) = rdf:type objects (classes)\r\n- **🖼️ Node Icons \u0026 Images**: Render images or emoji/icons on nodes via `schema:image` / `schema:icon` properties (see [Node icons and images](#node-icons-and-images))\r\n- **� Compact Mode**: Hide literal and class nodes; show rdf:type and datatype properties in enhanced tooltips instead\r\n- **🔍 Navigation**: Mouse wheel zoom, drag to pan, \"Zoom to Fit\" button\r\n- **✋ Drag \u0026 Drop**: Reorganize nodes by dragging them to new positions (nodes stay pinned after manual drag)\r\n- **💬 Rich Tooltips**: Modern HTML tooltips with node type, value, namespace, and datatype information\r\n- **🌓 Theme Support**: Automatic light/dark mode detection and dynamic color switching\r\n- **⚡ Performance**: Handles up to 1,000 nodes with \u003c2s render time\r\n- **♿ Accessible**: WCAG AA color contrast, keyboard navigation support\r\n\r\n## 📦 Installation\r\n\r\n### NPM\r\n\r\n```bash\r\nnpm install @matdata/yasgui-graph-plugin\r\n```\r\n\r\n```javascript\r\nimport Yasgui from '@matdata/yasgui';\r\nimport GraphPlugin from '@matdata/yasgui-graph-plugin';\r\n\r\nYasgui.Yasr.registerPlugin('Graph', GraphPlugin);\r\n\r\nconst yasgui = new Yasgui(document.getElementById('yasgui'));\r\n```\r\n\r\n### CDN (UMD)\r\n\r\n```html\r\n\u003c!-- YASGUI --\u003e\r\n\u003clink rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/npm/@matdata/yasgui/build/yasgui.min.css\"\u003e\r\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/@matdata/yasgui/build/yasgui.min.js\"\u003e\u003c/script\u003e\r\n\r\n\u003c!-- Graph Plugin --\u003e\r\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/@matdata/yasgui-graph-plugin/dist/yasgui-graph-plugin.min.js\"\u003e\u003c/script\u003e\r\n\r\n\u003cscript\u003e\r\n  // Plugin auto-registers as 'graph'\r\n  const yasgui = new Yasgui(document.getElementById('yasgui'));\r\n\u003c/script\u003e\r\n```\r\n\r\n## 🚀 Quick Start\r\n\r\nSee the complete working example in [`demo/index.html`](./demo/index.html).\r\n\r\n### Basic Usage\r\n\r\n```javascript\r\nconst yasgui = new Yasgui(document.getElementById('yasgui'), {\r\n  requestConfig: { \r\n    endpoint: 'https://dbpedia.org/sparql' \r\n  }\r\n});\r\n```\r\n\r\n### Sample Queries\r\n\r\n**CONSTRUCT Query:**\r\n```sparql\r\nPREFIX ex: \u003chttp://example.org/\u003e\r\nPREFIX rdf: \u003chttp://www.w3.org/1999/02/22-rdf-syntax-ns#\u003e\r\n\r\nCONSTRUCT {\r\n  ex:Alice rdf:type ex:Person .\r\n  ex:Alice ex:knows ex:Bob .\r\n  ex:Alice ex:name \"Alice\" .\r\n  ex:Bob rdf:type ex:Person .\r\n  ex:Bob ex:name \"Bob\" .\r\n}\r\nWHERE {}\r\n```\r\n\r\n**DESCRIBE Query:**\r\n```sparql\r\nPREFIX ex: \u003chttp://example.org/\u003e\r\n\r\n# Returns all triples about the specified resources\r\nDESCRIBE ex:Alice ex:Bob\r\n```\r\n\r\nAfter running the query, click the **\"Graph\"** tab to see the visualization.\r\n\r\n## 🎮 User Guide\r\n\r\n### Navigation\r\n- **Zoom**: Mouse wheel (scroll up = zoom in, scroll down = zoom out)\r\n- **Pan**: Click and drag the background\r\n- **Fit to View**: Click the \"Zoom to Fit\" button to center the entire graph\r\n\r\n### Interaction\r\n- **Drag Nodes**: Click and drag any node to reposition it (nodes are automatically pinned in place after dragging)\r\n- **Tooltips**: Hover over nodes/edges to see rich HTML tooltips with type, value, namespace, and datatype information\r\n\r\n### Understanding Colors\r\n\r\n| Color | Meaning | Example |\r\n|-------|---------|---------||\r\n| 🔵 Light Blue (#97C2FC) | URI nodes | `ex:Person`, `ex:Alice` |\r\n| 🟢 Light Green (#a6c8a6ff) | Literal values | `\"Alice\"`, `\"30\"^^xsd:integer` |\r\n| ⚪ Light Grey (#c5c5c5ff) | Blank nodes | `_:b1`, `_:addr1` |\r\n| 🟠 Orange (#e15b13ff) | rdf:type objects (classes) | `ex:Person` in `ex:Alice rdf:type ex:Person` |\r\n\r\n## ⚙️ Configuration\r\n\r\nThe plugin ships with sensible defaults and stores every change in **`localStorage`** so settings survive page reloads.\r\n\r\n### Settings panel\r\n\r\nClick the **⚙ Settings** button (top-right of the graph) to open the settings panel.\r\n\r\n| Setting | Values | Default | Description |\r\n|---------|--------|---------|-------------|\r\n| **Compact mode** | on / off | off | Hide literal and class nodes; show rdf:type and datatype properties in tooltips instead |\r\n| **Arrow style** | Curved / Straight | Curved | Toggle between smooth curved edges and straight lines between nodes |\r\n| **Predicate display** | Label / Icon / Hidden | Icon | Show the full prefixed URI on edges, a compact symbol/icon, or nothing |\r\n| **Show literals** | on / off | on | Include or exclude literal value nodes (strings, numbers, dates, …) |\r\n| **Show classes** | on / off | on | Include or exclude nodes that are objects of `rdf:type` triples (class nodes) |\r\n| **Show blank nodes** | on / off | on | Include or exclude blank nodes (`_:b0`, `_:b1`, …) |\r\n| **Show node labels** | on / off | on | Render the prefixed URI / literal text inside each node |\r\n| **Enable physics** | on / off | on | Keep the force-directed layout simulation running so nodes keep adjusting |\r\n| **Node size** | Small / Medium / Large | Medium | Set the radius of all nodes |\r\n\r\n### Predicate icons\r\n\r\nWhen *Predicate display* is set to **Icon**, each edge displays a compact symbol instead of the full label.  Symbols are defined for the 20+ most common predicates:\r\n\r\n| Predicate | Symbol |\r\n|-----------|--------|\r\n| `rdf:type` | `a` |\r\n| `rdfs:label` | `lbl` |\r\n| `rdfs:comment` | `cmt` |\r\n| `rdfs:subClassOf` | `⊂` |\r\n| `rdfs:subPropertyOf` | `⊆` |\r\n| `rdfs:domain` | `dom` |\r\n| `rdfs:range` | `rng` |\r\n| `rdfs:seeAlso` | `see` |\r\n| `rdfs:isDefinedBy` | `idb` |\r\n| `owl:sameAs` | `≡` |\r\n| `owl:equivalentClass` | `≅` |\r\n| `owl:inverseOf` | `⇄` |\r\n| `owl:disjointWith` | `≠` |\r\n| `skos:prefLabel` | `★` |\r\n| `skos:altLabel` | `☆` |\r\n| `skos:definition` | `def` |\r\n| `skos:broader` | `↑` |\r\n| `skos:narrower` | `↓` |\r\n| `skos:related` | `↔` |\r\n| `skos:note` | `note` |\r\n| `skos:exactMatch` | `≡` |\r\n| `skos:closeMatch` | `≈` |\r\n| `dcterms:title` | `ttl` |\r\n| `dcterms:description` | `dsc` |\r\n| `dcterms:created` | `crt` |\r\n| `dcterms:modified` | `mod` |\r\n| `dcterms:creator` | `by` |\r\n| `dcterms:subject` | `sbj` |\r\n| `foaf:name` | `nm` |\r\n| `foaf:knows` | `⟷` |\r\n| `foaf:member` | `mbr` |\r\n| `schema:name` | `nm` |\r\n| `schema:description` | `dsc` |\r\n\r\nFor predicates not in the table the full prefixed label is used as a fallback.\r\n\r\n## 🖼️ Node icons and images\r\n\r\nAny URI node can display an image or an icon instead of (or in addition to) the default coloured dot by attaching `schema:image` or `schema:icon` as a property directly in the SPARQL result.\r\n\r\n| Property | Object | Effect |\r\n|----------|--------|--------|\r\n| `schema:image` (`https://schema.org/image`) | URL literal or URI | Node is rendered as a circular image |\r\n| `schema:icon` (`https://schema.org/icon`) | emoji / short string | The string is used as the node's label |\r\n\r\n`schema:icon` takes priority over `schema:image`. The corresponding `schema:icon`/`schema:image` triples are **not** rendered as separate nodes or edges, but their values **are** shown in the node tooltip. Similarly, any `rdfs:label` triple is consumed to determine the node's displayed label and is never drawn as an edge, even when predicate display is enabled.\r\n\r\n### Example – inline image on a resource\r\n\r\n```sparql\r\nCONSTRUCT {\r\n  ex:alice schema:image \u003chttps://example.com/alice.png\u003e .\r\n  ex:alice ex:knows ex:bob .\r\n}\r\nWHERE {}\r\n```\r\n\r\n`ex:alice` will be drawn as a circular photograph.\r\n\r\n### Example – icon/emoji on a class\r\n\r\n```sparql\r\nCONSTRUCT {\r\n  ex:alice  rdf:type    ex:Person .\r\n  ex:Person schema:icon \"👤\" .\r\n}\r\nWHERE {}\r\n```\r\n\r\n`ex:alice` remains a normal dot node in regular mode.\r\nIn **compact mode** the class node (`ex:Person`) is hidden and Alice's node inherits the `👤` emoji as its label.\r\n\r\n### Compact mode visual inheritance\r\n\r\nWhen compact mode is enabled, class nodes are hidden and the plugin resolves the image/icon to show on the resource node using the following priority:\r\n\r\n1. `schema:image` / `schema:icon` directly on the **resource** (highest priority)\r\n2. `schema:image` / `schema:icon` on the **rdf:type class**\r\n3. `schema:image` / `schema:icon` on a **rdfs:subClassOf superclass** (one hop)\r\n\r\n### Programmatic configuration\r\n\r\nYou can also pass initial settings when extending the class:\r\n\r\n```javascript\r\nclass CustomGraphPlugin extends GraphPlugin {\r\n  constructor(yasr) {\r\n    super(yasr);\r\n    // Override defaults\r\n    this.settings.edgeStyle = 'straight';\r\n    this.settings.predicateDisplay = 'label';\r\n    this.settings.nodeSize = 'large';\r\n  }\r\n}\r\n\r\nYasgui.Yasr.registerPlugin('customGraph', CustomGraphPlugin);\r\n```\r\n\r\n## 🔧 Development\r\n\r\n### Build\r\n\r\n```bash\r\nnpm install\r\nnpm run build\r\n```\r\n\r\nOutput:\r\n- `dist/yasgui-graph-plugin.esm.js` (ES Module for bundlers)\r\n- `dist/yasgui-graph-plugin.cjs.js` (CommonJS for Node.js)\r\n- `dist/yasgui-graph-plugin.min.js` (IIFE for browsers/unpkg)\r\n- `dist/index.d.ts` (TypeScript declarations)\r\n\r\n### Local Testing\r\n\r\n1. Build the plugin: `npm run build`\r\n2. Open `demo/index.html` in a browser (or run `npm run dev`)\r\n3. Try the sample queries in different tabs\r\n\r\n### Code Quality\r\n\r\n```bash\r\nnpm test        # Run Jest unit tests\r\nnpm run lint    # ESLint check\r\nnpm run format  # Prettier format\r\n```\r\n\r\n## 📚 Documentation\r\n\r\n- **[Quickstart Guide](./specs/001-construct-graph-viz/quickstart.md)** - Installation, usage, troubleshooting\r\n- **[Data Model](./specs/001-construct-graph-viz/data-model.md)** - Entity definitions and relationships\r\n- **[Contracts](./specs/001-construct-graph-viz/contracts/)** - API specifications for YASR plugin and vis-network integration\r\n- **[Specification](./specs/001-construct-graph-viz/spec.md)** - Complete feature specification\r\n- **[Constitution](./. specify/memory/constitution.md)** - Project governance and principles\r\n\r\n## 🧪 Browser Compatibility\r\n\r\nTested on latest 2 versions of:\r\n- ✅ Chrome\r\n- ✅ Firefox\r\n- ✅ Safari\r\n- ✅ Edge\r\n\r\nRequires ES2018+ support and Canvas API.\r\n\r\n## 🤝 Contributing\r\n\r\nContributions welcome! Please follow the project constitution (`.specify/memory/constitution.md`) for governance principles:\r\n\r\n1. **Plugin-First Architecture** - No YASGUI core modifications\r\n2. **Visualization Quality** - Performance (\u003c2s for 1k nodes), accessibility (WCAG AA)\r\n3. **Configuration Flexibility** - Sensible defaults, but customizable\r\n4. **Browser Compatibility** - ES2018+, latest 2 browser versions\r\n5. **Documentation** - Keep docs updated with changes\r\n\r\n## 📄 License\r\n\r\n[Apache 2.0](./LICENSE)\r\n\r\n## 🙏 Acknowledgments\r\n\r\n- Built with [vis-network](https://visjs.github.io/vis-network/) for graph rendering\r\n- Integrates with [YASGUI](https://github.com/matdata/yasgui) SPARQL editor\r\n- Follows the [yasgui-geo](https://github.com/matdata/yasgui-geo) plugin pattern\r\n\r\n## 📊 Project Status\r\n\r\n**Current Version**: 0.1.0 (MVP)\r\n\r\n**Implemented Features** (v0.1.0):\r\n- ✅ Basic graph visualization (US1)\r\n- ✅ Navigation controls (US2)\r\n- ✅ Color-coded nodes\r\n- ✅ Prefix abbreviation\r\n- ✅ Blank node support\r\n- ✅ Performance optimization\r\n\r\n**Planned Features** (Future):\r\n- ⏳ Enhanced tooltips with datatype display (US4)\r\n- ⏳ Manual testing across all browsers (US3 verification)\r\n- ⏳ Large graph optimization (\u003e1k nodes)\r\n- ⏳ Custom color schemes\r\n- ⏳ Layout algorithm selection\r\n\r\n## 🐛 Troubleshooting\r\n\r\n### Plugin tab not showing\r\n- Verify plugin is registered correctly\r\n- Check browser console for errors\r\n- Ensure you're running a CONSTRUCT or DESCRIBE query\r\n\r\n### Empty visualization\r\n- Ensure query type is **CONSTRUCT** or **DESCRIBE**\r\n- Confirm query returns triples (check \"Table\" or \"Response\" tab)\r\n- Verify results have RDF structure\r\n\r\n### Performance issues\r\n- Limit results to \u003c1000 nodes for best performance\r\n- Disable physics after initial layout\r\n- Consider using LIMIT clause in SPARQL query\r\n\r\nFor more help, see [Quickstart Guide - Troubleshooting](./specs/001-construct-graph-viz/quickstart.md#troubleshooting).\r\n\r\n## 🛠️ Development\r\n\r\n### Setup\r\n\r\n```bash\r\ngit clone https://github.com/yourusername/yasgui-graph-plugin.git\r\ncd yasgui-graph-plugin\r\nnpm install\r\n```\r\n\r\n### Dev Workflow (Live Reload)\r\n\r\nThe project supports **live development** - edit source files and see changes immediately without rebuilding:\r\n\r\n1. **Start a local dev server** (any HTTP server will work):\r\n   ```bash\r\n   # Using Python\r\n   python -m http.server 8000\r\n   \r\n   # Using Node.js (http-server)\r\n   npx http-server -p 8000\r\n   \r\n   # Using VS Code Live Server extension\r\n   # Right-click demo/index.html → \"Open with Live Server\"\r\n   ```\r\n\r\n2. **Open demo in browser**:\r\n   ```\r\n   http://localhost:8000/demo/index.html\r\n   ```\r\n\r\n3. **Edit source files** (e.g., `src/colorUtils.js`):\r\n   ```javascript\r\n   export function getNodeColor(node) {\r\n     // Change colors here\r\n     if (node.isBlankNode) return '#FF00FF'; // Magenta\r\n     // ...\r\n   }\r\n   ```\r\n\r\n4. **Refresh browser** - changes appear immediately! ⚡\r\n\r\nThe demo automatically loads ES modules directly from `src/` in development mode, so no rebuild is needed.\r\n\r\n### Production Build\r\n\r\nBuild all distribution formats:\r\n\r\n```bash\r\nnpm run build\r\n```\r\n\r\nOutputs:\r\n- `dist/yasgui-graph-plugin.esm.js` - ES Module format (bundled with vis-network)\r\n- `dist/yasgui-graph-plugin.cjs.js` - CommonJS format (bundled with vis-network)\r\n- `dist/yasgui-graph-plugin.min.js` - IIFE browser bundle (bundled with vis-network)\r\n- `dist/index.d.ts` - TypeScript type declarations\r\n\r\n### Testing\r\n\r\n```bash\r\nnpm test          # Run all tests\r\nnpm run lint      # Check code style\r\nnpm run format    # Auto-fix formatting\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatdata-eu%2Fyasgui-graph-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatdata-eu%2Fyasgui-graph-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatdata-eu%2Fyasgui-graph-plugin/lists"}