jssm 5.155.1 → 5.156.0

package/dist/wc/viz.js

@@ -351,6 +351,125 @@ class FslViz extends LitElement {
     render() {
         return html `<div class="container">${unsafeHTML(this._svg)}</div>`;
     }
+    /**
+     * Clears any active programmatic highlights from the rendered SVG,
+     * restoring every node and edge to its default Graphviz presentation.
+     *
+     * Removes only the inline `fill` / `stroke` / `opacity` overrides that
+     * {@link highlightTrace} installs; the SVG's own presentation attributes
+     * are untouched. Safe to call when nothing is highlighted, before the
+     * first render, or while detached — it no-ops if there is no rendered
+     * SVG to clear.
+     *
+     * ```typescript
+     * const viz = document.querySelector('fsl-viz');
+     * viz.highlightTrace(['a', 'b']);
+     * viz.clearHighlights();   // back to the default rendering
+     * ```
+     *
+     * @see highlightTrace
+     */
+    clearHighlights() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        const container = this.shadowRoot.querySelector('.container');
+        if (!container) {
+            return;
+        }
+        // Remove the inline styles that override the SVG presentation attributes.
+        const elements = container.querySelectorAll('.node, .edge, .node *, .edge *');
+        elements.forEach(el => {
+            el.style.removeProperty('fill');
+            el.style.removeProperty('stroke');
+            el.style.removeProperty('opacity');
+        });
+    }
+    /**
+     * Programmatically highlights one execution trace (a path of state names)
+     * through the rendered graph, optionally fading everything off the path.
+     *
+     * Matches nodes by their Graphviz `<title>` (the state name) and edges by
+     * the `from->to` title Graphviz emits, applying inline style overrides so
+     * the highlight composes over — and is reversible against — the default
+     * rendering (see {@link clearHighlights}, which this calls first). No-ops
+     * when detached, before the first render, or given an empty trace.
+     *
+     * ```typescript
+     * // Highlight a -> b -> c in green, without dimming the rest:
+     * viz.highlightTrace(['a', 'b', 'c'], { color: '#2e7d32', fadeOthers: false });
+     * ```
+     *
+     * @param trace   Ordered state names describing the path (e.g.
+     *                `['A', 'B', 'C']`). Consecutive pairs select the edges
+     *                `A->B` and `B->C`. An empty array is a no-op.
+     * @param options Highlight styling; see {@link HighlightOptions}. Defaults
+     *                to crimson with off-trace fading enabled.
+     *
+     * @see clearHighlights
+     * @see HighlightOptions
+     */
+    highlightTrace(trace, options = {}) {
+        if (!this.shadowRoot) {
+            return;
+        }
+        const container = this.shadowRoot.querySelector('.container');
+        if (!container || trace.length === 0) {
+            return;
+        }
+        this.clearHighlights();
+        const color = options.color || '#b71c1c'; // default: a distinct crimson
+        const fadeOthers = options.fadeOthers !== false; // default: true
+        const targetNodes = new Set();
+        const targetEdges = new Set();
+        for (let i = 0; i < trace.length; i++) {
+            targetNodes.add(trace[i]);
+            if (i < trace.length - 1) {
+                targetEdges.add(`${trace[i]}->${trace[i + 1]}`);
+            }
+        }
+        const allNodes = container.querySelectorAll('.node');
+        const allEdges = container.querySelectorAll('.edge');
+        // Graphviz escapes '->' inside <title> as '&#45;&gt;'; DOM textContent
+        // usually decodes it, but normalize defensively (and drop quotes).
+        const unescapeTitle = (title) => title.replace(/&#45;/g, '-').replace(/&gt;/g, '>').replace(/"/g, '');
+        allNodes.forEach(node => {
+            const titleEl = node.querySelector('title');
+            const title = titleEl ? unescapeTitle(titleEl.textContent || '') : '';
+            if (targetNodes.has(title)) {
+                node.querySelectorAll('polygon, ellipse, path').forEach(shape => {
+                    shape.style.stroke = color;
+                    shape.style.strokeWidth = '2px';
+                });
+                node.querySelectorAll('text').forEach(text => {
+                    text.style.fill = color;
+                });
+            }
+            else if (fadeOthers) {
+                node.style.opacity = '0.2';
+            }
+        });
+        allEdges.forEach(edge => {
+            const titleEl = edge.querySelector('title');
+            const title = titleEl ? unescapeTitle(titleEl.textContent || '') : '';
+            if (targetEdges.has(title)) {
+                // Recolour the edge line and its arrowhead. The edge's action label
+                // is intentionally left alone: reorder_svg_layers() hoists every edge
+                // <text> out of its group onto a top paint layer (so labels can't be
+                // overdrawn), where it carries no <title> to correlate back to this
+                // edge — so a state-name trace cannot reliably re-style it.
+                edge.querySelectorAll('path, polygon').forEach(shape => {
+                    shape.style.stroke = color;
+                    if (shape.tagName.toLowerCase() === 'polygon') {
+                        shape.style.fill = color; // arrowheads
+                    }
+                });
+            }
+            else if (fadeOthers) {
+                edge.style.opacity = '0.2';
+            }
+        });
+    }
 }
 FslViz.styles = css `
     :host {
@@ -371,6 +490,21 @@ FslViz.styles = css `
       width: 90%;
       height: 90%;
     }
+
+    /* Smoothly animate the inline style overrides applied by highlightTrace()
+       so a trace fades in/out rather than snapping. */
+    .container svg g.node path,
+    .container svg g.node polygon,
+    .container svg g.node ellipse,
+    .container svg g.edge path,
+    .container svg g.edge polygon {
+      transition: fill 0.3s ease, stroke 0.3s ease, opacity 0.3s ease;
+    }
+
+    .container svg g.node text,
+    .container svg g.edge text {
+      transition: fill 0.3s ease, opacity 0.3s ease;
+    }
   `;
 __decorate([
     property({ type: String })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jssm",
-  "version": "5.155.1",
+  "version": "5.156.0",
   "engines": {
     "node": ">=10.0.0"
   },