@matdata/yasgui-graph-plugin 1.5.0 → 1.6.0

package/README.md

@@ -17,7 +17,8 @@ A YASGUI plugin for visualizing SPARQL CONSTRUCT and DESCRIBE query results as i
 - **� Compact Mode**: Hide literal and class nodes; show rdf:type and datatype properties in enhanced tooltips instead
 - **🔍 Navigation**: Mouse wheel zoom, drag to pan, "Zoom to Fit" button
 - **✋ Drag & Drop**: Reorganize nodes by dragging them to new positions (nodes stay pinned after manual drag)
-- **💬 Rich Tooltips**: Modern HTML tooltips with node type, value, namespace, and datatype information
+- **� Node Expansion**: Double-click any URI node to fetch and merge related triples via DESCRIBE queries (see [Expand Nodes with Double Click](#-expand-nodes-with-double-click))
+- **�💬 Rich Tooltips**: Modern HTML tooltips with node type, value, namespace, and datatype information
 - **🌓 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
@@ -105,6 +106,7 @@ After running the query, click the **"Graph"** tab to see the visualization.
 
 ### Interaction
 - **Drag Nodes**: Click and drag any node to reposition it (nodes are automatically pinned in place after dragging)
+- **Expand Nodes**: 🆕 Double-click any blue URI node to fetch and merge additional RDF triples for that resource (see [Node Expansion](#expand-nodes-with-double-click) below)
 - **Tooltips**: Hover over nodes/edges to see rich HTML tooltips with type, value, namespace, and datatype information
 
 ### Understanding Colors
@@ -240,7 +242,100 @@ class CustomGraphPlugin extends GraphPlugin {
 Yasgui.Yasr.registerPlugin('customGraph', CustomGraphPlugin);
 ```
 
-## 🔧 Development
+## � Expand Nodes with Double Click
+
+The graph plugin supports **interactive node expansion** via double-clicking. This allows you to progressively explore RDF graphs by fetching additional triples for any URI node without redrawing the entire graph.
+
+### How It Works
+
+1. **Double-click a blue URI node** in the graph
+2. The node's border turns **orange and thickens** (loading state)
+3. A `DESCRIBE <uri>` query is sent to the SPARQL endpoint
+4. **New triples are merged** into the existing graph
+5. Node's border returns to normal width with **thicker border (3px) to indicate expansion**
+6. Graph layout and zoom level are **preserved**
+
+### Visual Feedback
+
+| State | Border | Meaning |
+|-------|--------|---------|
+| **Default** | 2px | Node has not been expanded |
+| **Loading** | 4px, orange | DESCRIBE query in progress |
+| **Expanded** | 3px, normal color | Successfully expanded |
+
+### Supported Node Types
+
+| Node Type | Can Expand? | Reason |
+|-----------|-------|----|
+| 🔵 **URI nodes** | ✅ Yes | DESCRIBE works on URIs |
+| 🟢 **Literals** | ❌ No | Cannot run DESCRIBE on literal values |
+| ⚪ **Blank nodes** | ❌ No | Blank nodes have no resolvable identity |
+
+### Example: Exploring a Knowledge Graph
+
+**Initial Query**:
+```sparql
+PREFIX ex: <http://example.org/>
+PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+
+CONSTRUCT {
+  ex:alice foaf:knows ex:bob .
+  ex:alice foaf:name "Alice" .
+  ex:bob foaf:name "Bob" .
+}
+WHERE {}
+```
+
+**Initial Graph**: 3 nodes (Alice, "Alice", Bob, "Bob"), 2 edges
+
+**User Action**: Double-click the `ex:bob` node
+
+**What Happens**:
+- System executes: `DESCRIBE <http://example.org/bob>`
+- Endpoint returns all triples about Bob (from your SPARQL endpoint)
+- New nodes and edges appear in the graph
+- Graph layout shifts smoothly to accommodate new nodes
+- `ex:bob` node gets a thicker border
+
+**Result**: You can now see Bob's relationships, properties, and connections without losing your current view
+
+### Requirements
+
+The node expansion feature requires:
+
+1. **SPARQL 1.1 DESCRIBE support**: Your endpoint must support DESCRIBE queries
+2. **Query execution callback**: YASR must provide `yasr.executeQuery()` for background queries
+3. **RDF response format**: Endpoint must return results in RDF (JSON-LD, Turtle, N-Triples, etc.)
+
+### Limitations & Behavior
+
+- Only new triples are added (existing triples are skipped if already in graph)
+- Expansion is **one-level deep** - only triples directly about the URI are added
+- For very large result sets (1000+ triples from DESCRIBE), performance may be affected
+- Blank nodes returned by DESCRIBE may not connect properly if disconnected from existing nodes
+
+### Troubleshooting Expansion
+
+**"Nothing happens when I double-click"**
+- Ensure the node is blue (URI node, not literal or blank node)
+- Check browser console for warnings about `yasr.executeQuery`
+- Verify your SPARQL endpoint supports DESCRIBE queries
+
+**"Graph becomes slow after many expansions"**
+- Disable physics simulation in Settings panel for faster UI response
+- Consider limiting query results with WHERE clause constraints
+- Each expansion adds more triples to the visualization
+
+**"New nodes don't appear where I expect"**
+- The force-directed layout will position new nodes to minimize overlaps
+- Disable Physics in Settings to lock positions if desired
+- Manually drag new nodes to preferred positions
+
+### Demo
+
+See [demo/expand.html](./demo/expand.html) for a working example with mock DESCRIBE responses and detailed logging.
+
+## �🔧 Development
 
 ### Build
 
@@ -272,6 +367,7 @@ npm run format  # Prettier format
 ## 📚 Documentation
 
 - **[Quickstart Guide](./specs/001-construct-graph-viz/quickstart.md)** - Installation, usage, troubleshooting
+- **[Node Expansion Feature](./specs/001-construct-graph-viz/EXPAND_FEATURE.md)** - Complete guide to double-click expansion (FR-001 through FR-009)
 - **[Data Model](./specs/001-construct-graph-viz/data-model.md)** - Entity definitions and relationships
 - **[Contracts](./specs/001-construct-graph-viz/contracts/)** - API specifications for YASR plugin and vis-network integration
 - **[Specification](./specs/001-construct-graph-viz/spec.md)** - Complete feature specification
@@ -312,19 +408,18 @@ Contributions welcome! Please follow the project constitution (`.specify/memory/
 **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
+- ✅ **Basic graph visualization** (US1) - CONSTRUCT/DESCRIBE results as interactive graphs
+- ✅ **Navigation controls** (US2) - Zoom, pan, "Fit to View" button
+- ✅ **Color-coded nodes** - URIs, literals, blank nodes, rdf:type objects
+- ✅ **Prefix abbreviation** - Display prefixed URIs instead of full URLs
+- ✅ **Blank node support** - Handle anonymous RDF nodes
+- ✅ **Drag & repositioning** - Manually adjust node positions
+- ✅ **Rich tooltips** - Hover for detailed node/edge information
+- ✅ **Theme support** - Light/dark mode detection and switching
+- ✅ **Settings panel** - Configurable display options with localStorage persistence
+- ✅ **Node icons & images** - Display images via schema:image property
+- ✅ **Compact mode** - Hide literals and classes for cleaner visualization
+- ✅ **Double-click expansion** (US5) - Fetch and merge related triples via DESCRIBE queries (see [Expand Nodes with Double Click](#-expand-nodes-with-double-click))
 
 ## 🐛 Troubleshooting
 

package/dist/yasgui-graph-plugin.cjs.js

@@ -142,6 +142,40 @@ function getDefaultNetworkOptions(themeColors, settings) {
 }
 
 // src/parsers.ts
+async function parseBackgroundQueryResponse(response) {
+  var _a, _b;
+  if (!response) return [];
+  try {
+    let data2;
+    if (typeof response.json === "function") {
+      data2 = await response.json();
+    } else if (typeof response.data === "string") {
+      data2 = JSON.parse(response.data);
+    } else if (typeof response === "object") {
+      data2 = response;
+    } else {
+      return [];
+    }
+    const bindings = (_b = (_a = data2 == null ? void 0 : data2.results) == null ? void 0 : _a.bindings) != null ? _b : [];
+    const triples = [];
+    for (const binding of bindings) {
+      if (!binding.subject || !binding.predicate || !binding.object || typeof binding.subject.value !== "string" || typeof binding.predicate.value !== "string" || typeof binding.object.value !== "string") continue;
+      triples.push({
+        subject: binding.subject.value,
+        predicate: binding.predicate.value,
+        object: {
+          value: binding.object.value,
+          type: binding.object.type || "uri",
+          datatype: binding.object.datatype,
+          lang: binding.object["xml:lang"]
+        }
+      });
+    }
+    return triples;
+  } catch (e) {
+    return [];
+  }
+}
 function parseConstructResults(yasrResults) {
   const triples = [];
   if (!yasrResults || !yasrResults.getBindings) {
@@ -30014,10 +30048,16 @@ function saveSettings(settings) {
 }
 
 // src/GraphPlugin.ts
+var LOADING_BORDER_WIDTH = 4;
+var LOADING_BORDER_COLOR = "#ffa500";
+var EXPANDED_BORDER_WIDTH = 3;
+var DEFAULT_BORDER_WIDTH = 2;
 var GraphPlugin = class {
   constructor(yasr) {
     this.settingsPanelOpen = false;
     this.clickOutsideHandler = null;
+    this.expansionAbortController = null;
+    this.uriToNodeId = /* @__PURE__ */ new Map();
     this.yasr = yasr;
     this.network = null;
     this.currentTheme = getCurrentTheme();
@@ -30041,6 +30081,12 @@ var GraphPlugin = class {
   static get label() {
     return "Graph";
   }
+  /**
+   * Help/documentation URL
+   */
+  static get helpReference() {
+    return "https://yasgui-doc.matdata.eu/docs/user-guide#graph-plugin";
+  }
   /**
    * Check if plugin can handle the current results
    * @returns True if results are from CONSTRUCT or DESCRIBE query
@@ -30062,6 +30108,12 @@ var GraphPlugin = class {
    */
   draw() {
     const wasPanelOpen = this.settingsPanelOpen;
+    if (this.expansionAbortController) {
+      this.expansionAbortController.abort();
+      this.expansionAbortController = null;
+    }
+    this.expandedNodes = /* @__PURE__ */ new Set();
+    this.uriToNodeId = /* @__PURE__ */ new Map();
     this.yasr.resultsEl.innerHTML = "";
     try {
       this.triples = parseConstructResults(this.yasr.results);
@@ -30118,6 +30170,13 @@ var GraphPlugin = class {
           this.nodesDataSet.update(updates);
         }
       });
+      this.setupNodeExpansion();
+      this.uriToNodeId = /* @__PURE__ */ new Map();
+      this.nodesDataSet.get().forEach((node) => {
+        if (node.uri) {
+          this.uriToNodeId.set(node.uri, node.id);
+        }
+      });
       if (!this.themeObserver) {
         this.themeObserver = watchThemeChanges((newTheme) => {
           this.applyTheme(newTheme);
@@ -30500,7 +30559,119 @@ var GraphPlugin = class {
     return panel;
   }
   /**
-   * Get icon for plugin tab
+   * Setup double-click handler for node expansion
+   */
+  setupNodeExpansion() {
+    if (!this.network) return;
+    this.network.on("doubleClick", (params) => {
+      if (params.nodes.length === 0) return;
+      const nodeId = params.nodes[0];
+      const node = this.nodesDataSet.get(nodeId);
+      if (node && node.uri && !node.uri.startsWith("_:")) {
+        this.expandNode(node.uri);
+      }
+    });
+  }
+  /**
+   * Expand a node by executing a DESCRIBE query for the given URI and
+   * merging the returned triples into the existing graph.
+   * @param uri - URI of the node to expand
+   */
+  async expandNode(uri) {
+    if (!this.yasr.executeQuery) {
+      console.warn("yasgui-graph-plugin: background query execution not available (yasr.executeQuery is not configured)");
+      return;
+    }
+    if (!this.triples || !this.prefixMap) return;
+    if (this.expansionAbortController) {
+      this.expansionAbortController.abort();
+    }
+    const controller = new AbortController();
+    this.expansionAbortController = controller;
+    const nodeId = this.uriToNodeId.get(uri);
+    let originalColor = void 0;
+    let originalBorderWidth = void 0;
+    if (nodeId !== void 0) {
+      const node = this.nodesDataSet.get(nodeId);
+      if (node) {
+        originalColor = node.color;
+        originalBorderWidth = node.borderWidth;
+      }
+      this.nodesDataSet.update({
+        id: nodeId,
+        borderWidth: LOADING_BORDER_WIDTH,
+        color: typeof originalColor === "object" && originalColor !== null ? { ...originalColor, border: LOADING_BORDER_COLOR } : { border: LOADING_BORDER_COLOR, background: originalColor != null ? originalColor : void 0 }
+      });
+    }
+    const restoreNode = (borderWidth) => {
+      if (nodeId !== void 0) {
+        this.nodesDataSet.update({ id: nodeId, borderWidth, color: originalColor });
+      }
+    };
+    try {
+      const response = await this.yasr.executeQuery(`DESCRIBE <${uri}>`, {
+        acceptHeader: "application/sparql-results+json",
+        signal: controller.signal
+      });
+      if (controller.signal.aborted) {
+        restoreNode(originalBorderWidth != null ? originalBorderWidth : DEFAULT_BORDER_WIDTH);
+        return;
+      }
+      const newTriples = await parseBackgroundQueryResponse(response);
+      if (controller.signal.aborted) {
+        restoreNode(originalBorderWidth != null ? originalBorderWidth : DEFAULT_BORDER_WIDTH);
+        return;
+      }
+      const existingKeys = new Set(
+        this.triples.map((t) => `${t.subject}|${t.predicate}|${t.object.value}`)
+      );
+      const uniqueNew = newTriples.filter(
+        (t) => !existingKeys.has(`${t.subject}|${t.predicate}|${t.object.value}`)
+      );
+      if (uniqueNew.length > 0) {
+        this.triples = [...this.triples, ...uniqueNew];
+        this.mergeNewTriples();
+      }
+      restoreNode(EXPANDED_BORDER_WIDTH);
+    } catch (error) {
+      if ((error == null ? void 0 : error.name) === "AbortError") {
+        restoreNode(originalBorderWidth != null ? originalBorderWidth : DEFAULT_BORDER_WIDTH);
+        return;
+      }
+      console.error("yasgui-graph-plugin: error expanding node", uri, error);
+      restoreNode(originalBorderWidth != null ? originalBorderWidth : DEFAULT_BORDER_WIDTH);
+    }
+  }
+  /**
+   * Incrementally add new triples to the vis-network DataSets without a full redraw.
+   * New nodes and edges are added; existing ones are left untouched.
+   * Expects `this.triples` to already include the new triples.
+   */
+  mergeNewTriples() {
+    if (!this.triples || !this.prefixMap || !this.nodesDataSet || !this.edgesDataSet) return;
+    const themeColors = getThemeNodeColors(this.currentTheme);
+    const { nodes, edges } = triplesToGraph(this.triples, this.prefixMap, themeColors, this.settings);
+    const existingValues = new Set(this.nodesDataSet.get().map((n) => n.fullValue));
+    const nodesToAdd = nodes.filter((n) => !existingValues.has(n.fullValue));
+    const existingEdgeKeys = new Set(
+      this.edgesDataSet.get().map((e) => `${e.from}|${e.predicate}|${e.to}`)
+    );
+    const edgesToAdd = edges.filter(
+      (e) => !existingEdgeKeys.has(`${e.from}|${e.predicate}|${e.to}`)
+    );
+    if (nodesToAdd.length > 0) {
+      this.nodesDataSet.add(nodesToAdd);
+      nodesToAdd.forEach((n) => {
+        if (n.uri != null) {
+          this.uriToNodeId.set(n.uri, n.id);
+        }
+      });
+    }
+    if (edgesToAdd.length > 0) {
+      this.edgesDataSet.add(edgesToAdd);
+    }
+  }
+  /**
    * @returns Icon element
    */
   getIcon() {
@@ -30522,6 +30693,10 @@ var GraphPlugin = class {
    */
   destroy() {
     this.removeClickOutsideHandler();
+    if (this.expansionAbortController) {
+      this.expansionAbortController.abort();
+      this.expansionAbortController = null;
+    }
     if (this.themeObserver) {
       this.themeObserver.disconnect();
       this.themeObserver = null;