spytial-core 1.4.15-beta.1 → 1.4.15-beta.2

package/README.md

@@ -146,6 +146,55 @@ See [webcola-demo/projection-controls-demo-vanilla.html](./webcola-demo/projecti
 
 ---
 
+## Node Highlighting
+
+Visualize selector and evaluator results by highlighting nodes directly in the graph. This feature allows you to examine selector results in context without triggering a layout refresh.
+
+### Unary Selectors (Single Nodes)
+
+```typescript
+// Evaluate a unary selector
+const result = evaluator.evaluate('Student');
+const nodeIds = result.selectedAtoms();
+
+// Highlight the nodes
+const graph = document.querySelector('webcola-cnd-graph');
+graph.highlightNodes(nodeIds);
+```
+
+### Binary Selectors (Node Pairs)
+
+```typescript
+// Evaluate a binary selector
+const result = evaluator.evaluate('friend');
+const pairs = result.selectedTwoples(); // [["Alice", "Bob"], ["Charlie", "Diana"]]
+
+// Highlight with visual correspondence
+graph.highlightNodePairs(pairs);
+
+// Or with badges showing 1/2 correspondence
+graph.highlightNodePairs(pairs, { showBadges: true });
+```
+
+### Clear Highlights
+
+```typescript
+// Remove all node highlights
+graph.clearNodeHighlights();
+```
+
+### Visual Styling
+
+- **Unary selectors**: Orange border with glow effect
+- **Binary selectors**: 
+  - First elements: Blue border (e.g., the source of a relation)
+  - Second elements: Red border (e.g., the target of a relation)
+  - Optional badges: Shows "1" and "2" to indicate correspondence
+
+See [webcola-demo/node-highlighter-demo.html](./webcola-demo/node-highlighter-demo.html) for an interactive demo.
+
+---
+
 ## CDN
 
 You can use the browser bundle directly from a CDN:
@@ -197,6 +246,25 @@ Once loaded, use via the global `CndCore` object:
 - **`SGraphQueryEvaluator`** - Evaluate selector expressions
 - **`AlloyDataInstance`**, **`JSONDataInstance`**, etc. - Data format adapters
 
+### WebCola Graph API
+
+The `<webcola-cnd-graph>` custom element provides methods for interacting with the rendered graph:
+
+#### Node Highlighting
+- **`highlightNodes(nodeIds: string[])`** - Highlight nodes by ID (unary selectors)
+- **`highlightNodePairs(pairs: string[][], options?)`** - Highlight node pairs with first/second correspondence (binary selectors)
+- **`clearNodeHighlights()`** - Remove all node highlights
+
+#### Relation Highlighting
+- **`getAllRelations()`** - Get all unique relation names
+- **`highlightRelation(relName: string)`** - Highlight edges by relation name
+- **`clearHighlightRelation(relName: string)`** - Clear relation highlighting
+
+#### Layout Management
+- **`renderLayout(instanceLayout, options?)`** - Render a layout with optional prior positions
+- **`clear()`** - Clear the graph and reset state
+- **`getNodePositions()`** - Get current positions of all nodes
+
 See [docs/](./docs/) for detailed documentation.
 
 ---

package/dist/browser/spytial-core-complete.global.js

@@ -91263,9 +91263,9 @@ VVbdfjptxz|~\x80\x82\x84\xA6\xA8W\b
           return group.name.startsWith(_WebColaCnDGraph.DISCONNECTED_NODE_PREFIX);
         }
         /**
-         * Computes adaptive link length based on actual node dimensions and graph density
+         * Computes adaptive link length based on actual node dimensions, edge labels, and graph density
          */
-        computeAdaptiveLinkLength(nodes, scaleFactor) {
+        computeAdaptiveLinkLength(nodes, scaleFactor, links) {
           if (!nodes || nodes.length === 0) {
             return 150;
           }
@@ -91285,20 +91285,32 @@ VVbdfjptxz|~\x80\x82\x84\xA6\xA8W\b
           const avgWidth = totalWidth / validNodes;
           const avgHeight = totalHeight / validNodes;
           const avgNodeSize = Math.max(avgWidth, avgHeight);
+          let maxLabelWidth = 0;
+          if (links && links.length > 0) {
+            const fontSize = 12;
+            links.forEach((link) => {
+              if (link && link.label) {
+                const labelWidth = this.measureTextWidth(link.label, fontSize, "system-ui");
+                maxLabelWidth = Math.max(maxLabelWidth, labelWidth);
+              }
+            });
+          }
+          const markerSize = 15;
           const baseSeparation = 50;
-          let baseLinkLength = Math.max(avgNodeSize + baseSeparation, 120);
+          const labelAndMarkerSpace = maxLabelWidth + markerSize + 20;
+          let baseLinkLength = Math.max(avgNodeSize + baseSeparation + labelAndMarkerSpace, 120);
           const densityFactor = Math.max(0.7, 1 - Math.log10(validNodes) * 0.1);
           baseLinkLength *= densityFactor;
           const adjustedScaleFactor = scaleFactor / 5;
           const scaledLinkLength = baseLinkLength / adjustedScaleFactor;
           return Math.max(60, Math.min(scaledLinkLength, 350));
         }
-        getScaledDetails(constraints, scaleFactor = DEFAULT_SCALE_FACTOR, nodes, groups) {
+        getScaledDetails(constraints, scaleFactor = DEFAULT_SCALE_FACTOR, nodes, groups, links) {
           const adjustedScaleFactor = scaleFactor / 5;
           let groupCompactness = this.calculateAdaptiveGroupCompactness(groups || [], nodes?.length || 0, adjustedScaleFactor);
           let linkLength;
           if (nodes && nodes.length > 0) {
-            linkLength = this.computeAdaptiveLinkLength(nodes, scaleFactor);
+            linkLength = this.computeAdaptiveLinkLength(nodes, scaleFactor, links);
           } else {
             const min_sep = 150;
             const default_node_width = 100;
@@ -91407,11 +91419,11 @@ VVbdfjptxz|~\x80\x82\x84\xA6\xA8W\b
       <span id="error-icon" title="This graph is depicting an error state">\u26A0\uFE0F</span>
       <svg id="svg" viewBox="0 0 ${containerWidth} ${containerHeight}" preserveAspectRatio="xMidYMid meet">
         <defs>
-        <marker id="end-arrow" markerWidth="15" markerHeight="10" refX="12" refY="5" orient="auto">
-          <polygon points="0 0, 15 5, 0 10" />
+        <marker id="end-arrow" markerWidth="15" markerHeight="10" refX="12" refY="5" orient="auto" markerUnits="userSpaceOnUse">
+          <polygon points="0 0, 15 5, 0 10" fill="context-stroke" />
         </marker>
-        <marker id="start-arrow" markerWidth="15" markerHeight="10" refX="3" refY="5" orient="auto">
-          <polygon points="15 0, 0 5, 15 10" />
+        <marker id="start-arrow" markerWidth="15" markerHeight="10" refX="3" refY="5" orient="auto" markerUnits="userSpaceOnUse">
+          <polygon points="15 0, 0 5, 15 10" fill="context-stroke" />
         </marker>
         </defs>
         <g class="zoomable"></g>
@@ -91899,7 +91911,8 @@ VVbdfjptxz|~\x80\x82\x84\xA6\xA8W\b
               webcolaLayout.constraints,
               DEFAULT_SCALE_FACTOR,
               webcolaLayout.nodes,
-              webcolaLayout.groups
+              webcolaLayout.groups,
+              webcolaLayout.links
             );
             this.updateLoadingProgress("Applying constraints and initializing...");
             const convergenceThreshold = hasPriorPositions ? 0.1 : 1e-3;
@@ -93604,6 +93617,124 @@ VVbdfjptxz|~\x80\x82\x84\xA6\xA8W\b
           this.svgLinkGroups.filter((d) => d.relName === relName && !this.isAlignmentEdge(d)).selectAll("path").classed("highlighted", false);
           return true;
         }
+        /** Public API for node highlighting */
+        /**
+         * Highlights nodes based on their IDs (for unary selector results).
+         * This is useful for visualizing the results of a selector expression.
+         * 
+         * @param nodeIds - Array of node IDs to highlight (e.g., from evaluator.selectedAtoms())
+         * @returns True if any nodes were highlighted, false otherwise
+         * 
+         * @example
+         * ```typescript
+         * const result = evaluator.evaluate('Student');
+         * const nodeIds = result.selectedAtoms();
+         * graph.highlightNodes(nodeIds);
+         * ```
+         */
+        highlightNodes(nodeIds) {
+          if (!this.currentLayout?.nodes || !this.svgNodes) return false;
+          if (!nodeIds || nodeIds.length === 0) return false;
+          const nodeIdSet = new Set(nodeIds);
+          let highlighted = false;
+          this.svgNodes.each((d, i, nodes) => {
+            if (nodeIdSet.has(d.id)) {
+              d32.select(nodes[i]).classed("highlighted", true);
+              highlighted = true;
+            }
+          });
+          return highlighted;
+        }
+        /**
+         * Highlights node pairs based on binary selector results.
+         * Shows visual correspondence between first and second elements using different colors.
+         * 
+         * Note: If a node appears in multiple pairs with different roles (both first and second),
+         * it will receive both 'highlighted-first' and 'highlighted-second' classes, and if badges
+         * are enabled, only the last badge will be visible (this is intentional to avoid cluttering).
+         * 
+         * @param nodePairs - Array of [first, second] node ID pairs (e.g., from evaluator.selectedTwoples())
+         * @param options - Optional configuration for highlighting
+         * @param options.showBadges - If true, shows "1" and "2" badges on nodes (default: false)
+         * @returns True if any nodes were highlighted, false otherwise
+         * 
+         * @example
+         * ```typescript
+         * const result = evaluator.evaluate('friend');
+         * const pairs = result.selectedTwoples(); // [["Alice", "Bob"], ["Charlie", "Diana"]]
+         * graph.highlightNodePairs(pairs, { showBadges: true });
+         * ```
+         */
+        highlightNodePairs(nodePairs, options = {}) {
+          if (!this.currentLayout?.nodes || !this.svgNodes) return false;
+          if (!nodePairs || nodePairs.length === 0) return false;
+          const { showBadges = false } = options;
+          const firstNodeIds = /* @__PURE__ */ new Set();
+          const secondNodeIds = /* @__PURE__ */ new Set();
+          nodePairs.forEach((pair, index) => {
+            if (!Array.isArray(pair)) {
+              console.warn(`highlightNodePairs: Pair at index ${index} is not an array, skipping`);
+              return;
+            }
+            if (pair.length !== 2) {
+              console.warn(`highlightNodePairs: Pair at index ${index} has ${pair.length} elements (expected 2), skipping`);
+              return;
+            }
+            const [first, second] = pair;
+            if (first) firstNodeIds.add(first);
+            if (second) secondNodeIds.add(second);
+          });
+          let highlighted = false;
+          this.svgNodes.each((d, i, nodes) => {
+            const nodeGroup = d32.select(nodes[i]);
+            if (firstNodeIds.has(d.id)) {
+              nodeGroup.classed("highlighted-first", true);
+              highlighted = true;
+              if (showBadges) {
+                this.addHighlightBadge(nodeGroup, d, "1", "#007aff");
+              }
+            }
+            if (secondNodeIds.has(d.id)) {
+              nodeGroup.classed("highlighted-second", true);
+              highlighted = true;
+              if (showBadges) {
+                if (firstNodeIds.has(d.id)) {
+                  this.addHighlightBadge(nodeGroup, d, "1,2", "#9B59B6");
+                } else {
+                  this.addHighlightBadge(nodeGroup, d, "2", "#ff3b30");
+                }
+              }
+            }
+          });
+          return highlighted;
+        }
+        /**
+         * Clears all node highlights (both unary and binary).
+         * 
+         * @returns True if the operation completed successfully
+         */
+        clearNodeHighlights() {
+          if (!this.svgNodes) return false;
+          this.svgNodes.classed("highlighted", false).classed("highlighted-first", false).classed("highlighted-second", false).selectAll(".highlight-badge, .highlight-badge-bg").remove();
+          return true;
+        }
+        /**
+         * Adds a visual badge to a highlighted node to show first/second correspondence.
+         * 
+         * @param nodeGroup - D3 selection of the node group
+         * @param nodeData - Node data containing position and dimensions
+         * @param label - Badge label text ('1' or '2')
+         * @param color - Badge background color
+         */
+        addHighlightBadge(nodeGroup, nodeData, label, color) {
+          nodeGroup.selectAll(".highlight-badge, .highlight-badge-bg").remove();
+          const badgeSize = 16;
+          const padding = 4;
+          const badgeX = (nodeData.width || 0) / 2 - badgeSize / 2 - padding;
+          const badgeY = -(nodeData.height || 0) / 2 + badgeSize / 2 + padding;
+          nodeGroup.append("circle").attr("class", "highlight-badge-bg").attr("cx", badgeX).attr("cy", badgeY).attr("r", badgeSize / 2).attr("fill", color);
+          nodeGroup.append("text").attr("class", "highlight-badge").attr("x", badgeX).attr("y", badgeY).attr("dy", "0.35em").text(label);
+        }
         /**
          * Shows a runtime alert for edge routing errors.
          * 
@@ -93710,6 +93841,38 @@ VVbdfjptxz|~\x80\x82\x84\xA6\xA8W\b
         stroke:#666666; /* Change this to your desired highlight color */
         stroke-width: 3px; /* Change this to your desired highlight width */
       }
+
+      /* Node highlighting styles */
+      .node.highlighted rect {
+        stroke: #ff9500;
+        stroke-width: 3px;
+        filter: drop-shadow(0 0 6px rgba(255, 149, 0, 0.6));
+      }
+
+      .node.highlighted-first rect {
+        stroke: #007aff;
+        stroke-width: 3px;
+        filter: drop-shadow(0 0 6px rgba(0, 122, 255, 0.6));
+      }
+
+      .node.highlighted-second rect {
+        stroke: #ff3b30;
+        stroke-width: 3px;
+        filter: drop-shadow(0 0 6px rgba(255, 59, 48, 0.6));
+      }
+
+      /* Add a badge indicator for first/second in binary selectors */
+      .highlight-badge {
+        font-size: 10px;
+        font-weight: bold;
+        fill: white;
+        text-anchor: middle;
+        pointer-events: none;
+      }
+
+      .highlight-badge-bg {
+        pointer-events: none;
+      }
       
       .group {
         fill: rgba(200, 200, 200, 0.3);