jssm 5.138.0 → 5.141.0

package/dist/cdn/viz.js

@@ -21352,7 +21352,7 @@ var constants = /*#__PURE__*/Object.freeze({
  *  Useful for runtime diagnostics and for embedding in serialized machine
  *  snapshots so that deserializers can detect version-skew.
  */
-const version = "5.138.0";
+const version = "5.141.0";
 
 // whargarbl lots of these return arrays could/should be sets
 const { state_name_chars, state_name_first_chars, action_label_chars } = constants;
@@ -25705,6 +25705,16 @@ async function dot_to_svg(dot, options) {
 async function fsl_to_svg_string(fsl, opts = {}) {
     return dot_to_svg(fsl_to_dot(fsl, opts), opts);
 }
+/**
+ *  Render a {@link jssm.Machine} to SVG.
+ *
+ *  @param u_jssm The machine to render.
+ *  @param opts Optional render flags.  See {@link VizRenderOpts}.
+ *  @returns A promise resolving to an SVG XML string.
+ */
+async function machine_to_svg_string(u_jssm, opts = {}) {
+    return dot_to_svg(machine_to_dot(u_jssm, opts));
+}
 
 var __decorate = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -25746,6 +25756,17 @@ function normalize_viz_error(e) {
 /**
  * Web component that renders a jssm machine as inline SVG.
  *
+ * Two operating modes:
+ *
+ *   1. **Standalone** (no parent `<jssm-instance>` ancestor): render from
+ *      the element's own `fsl=""` attribute / property.  Re-renders on
+ *      attribute change.
+ *   2. **Nested** (inside a `<jssm-instance>` ancestor, found via
+ *      `closest('jssm-instance')` at `connectedCallback`): bind to the
+ *      parent's machine and re-render on every `transition` event.  The
+ *      element's own `fsl` attribute is ignored in this mode; supplying it
+ *      emits a `console.warn` for developer feedback.
+ *
  * @element jssm-viz
  * @cssproperty [--jssm-viz-min-height=100px] - Minimum height of the rendered SVG container.
  * @fires {CustomEvent<{ message: string; location?: unknown }>} viz-error - Fires when the FSL source fails to parse or render.
@@ -25758,18 +25779,137 @@ class JssmViz extends i$1 {
         /** Optional Graphviz layout engine override (e.g. 'dot', 'neato'). */
         this.engine = undefined;
         this._svg = '';
+        /**
+         * Parent `<jssm-instance>` host reference, set in `connectedCallback`
+         * when a parent is found.  When non-null the viz is in nested mode and
+         * renders the parent's machine instead of its own `fsl` attribute.
+         */
+        this._parent_host = null;
+        /**
+         * Unsubscribe callback returned from `host.machine.on('transition', ...)`.
+         * Held so `disconnectedCallback` can release the subscription.
+         */
+        this._parent_sub = null;
     }
     /**
      * Lit lifecycle hook. Triggers an async SVG render whenever `fsl` or
-     * `engine` change.
+     * `engine` change — but only in standalone mode.  In nested mode the
+     * `fsl` attribute is ignored; renders are driven by the parent machine's
+     * transition events instead.
      *
      * @param changed - Map of changed reactive properties supplied by Lit.
      */
     willUpdate(changed) {
+        if (this._parent_host !== null) {
+            // Nested mode: ignore `fsl` attr changes; renders come from the
+            // parent's transition events.  `engine` changes still re-render
+            // because they apply to whichever source is in use.
+            if (changed.has('engine')) {
+                this._rerenderFromHostMachine();
+            }
+            return;
+        }
         if (changed.has('fsl') || changed.has('engine')) {
             this._renderSvg();
         }
     }
+    /**
+     * Web Components lifecycle hook.  Walks up to find a parent
+     * `<jssm-instance>` ancestor; if found, switches into nested mode and
+     * subscribes to the parent machine's `transition` events.  Otherwise
+     * leaves standalone behavior intact.
+     *
+     * Subscription setup is deferred via `customElements.whenDefined` so the
+     * parent has had a chance to upgrade and construct its machine before
+     * we touch `host.machine`.
+     */
+    connectedCallback() {
+        super.connectedCallback();
+        const host = this.closest('jssm-instance');
+        if (host === null) {
+            return; // standalone: existing behavior, willUpdate handles render
+        }
+        // Conflicting-configuration feedback: nested viz with its own `fsl`
+        // attribute is almost certainly a bug.  Warn but proceed — the parent
+        // owns the machine.
+        if (typeof this.fsl === 'string' && this.fsl.trim().length > 0) {
+            // eslint-disable-next-line no-console
+            console.warn('<jssm-viz>: `fsl` ignored when nested inside <jssm-instance>; parent owns the machine');
+        }
+        this._parent_host = host;
+        // Defer to whenDefined so a not-yet-upgraded host has its machine
+        // available before we access `host.machine` (which throws when called
+        // pre-connection).
+        void customElements.whenDefined('jssm-instance').then(() => {
+            // Re-check the host is still attached and the viz still belongs to
+            // it — disconnection between the deferred resolution and now is
+            // legal and should not error.
+            if (this._parent_host !== host) {
+                return;
+            }
+            try {
+                this._parent_sub = host.machine.on('transition', () => {
+                    this._rerenderFromHostMachine();
+                });
+            }
+            catch (e) {
+                // The parent existed but its machine wasn't ready / threw.  Emit
+                // a viz-error so the consumer learns about it instead of silently
+                // showing nothing.
+                this.dispatchEvent(new CustomEvent('viz-error', {
+                    detail: normalize_viz_error(e),
+                    bubbles: true,
+                    composed: true,
+                }));
+                return;
+            }
+            this._rerenderFromHostMachine();
+        });
+    }
+    /**
+     * Web Components lifecycle hook.  Releases any installed
+     * parent-transition subscription and clears the host reference so a
+     * subsequent re-attach goes through the full `connectedCallback` path
+     * again.
+     */
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        if (this._parent_sub !== null) {
+            this._parent_sub();
+            this._parent_sub = null;
+        }
+        this._parent_host = null;
+    }
+    /**
+     * Nested-mode render path.  Renders the bound parent's machine via the
+     * {@link machine_to_svg_string} pipeline and commits the result to
+     * `_svg`.  On failure emits a `viz-error` `CustomEvent` and clears the
+     * SVG.
+     *
+     * @returns A promise that resolves once the render attempt has finished.
+     */
+    async _rerenderFromHostMachine() {
+        const host = this._parent_host;
+        if (host === null) {
+            return;
+        }
+        try {
+            const m = host.machine;
+            const result = await machine_to_svg_string(m, this.engine ? { engine: this.engine } : undefined);
+            // Guard against the parent disappearing mid-render.
+            if (this._parent_host === host) {
+                this._svg = result;
+            }
+        }
+        catch (e) {
+            this._svg = '';
+            this.dispatchEvent(new CustomEvent('viz-error', {
+                detail: normalize_viz_error(e),
+                bubbles: true,
+                composed: true,
+            }));
+        }
+    }
     /**
      * Render the current `fsl` source to an SVG string via the headless
      * `fsl_to_svg_string` pipeline. Updates `_svg` on success; emits a
@@ -25843,9 +25983,9 @@ __decorate([
  *
  * Both tags render identically; `<fsl-viz>` is provided as an alternative
  * spelling for users whose mental model is "FSL viz" rather than "jssm
- * viz".
- *
- * TODO: parent-context binding from #647 Stage 2 lands once #648 exists.
+ * viz".  Parent-context binding for both tags lives on the shared
+ * `JssmViz` base class (see {@link JssmViz}); the synonym inherits it
+ * automatically.
  */
 class FslViz extends JssmViz {
 }