jssm 5.136.0 → 5.137.0

package/README.md

@@ -18,10 +18,10 @@ Please edit the file it's derived from, instead: `./src/md/readme_base.md`
 
 
 
-* Generated for version 5.136.0 at 5/27/2026, 10:35:53 PM
+* Generated for version 5.137.0 at 5/27/2026, 11:01:17 PM
 
 -->
-# jssm 5.136.0
+# jssm 5.137.0
 
 [**Try the live editor**](https://stonecypher.github.io/jssm-viz-demo/graph_explorer.html) ·
 [Documentation](https://stonecypher.github.io/jssm/docs/) ·
@@ -281,7 +281,7 @@ That decision shows up everywhere downstream:
   or run `npm run benny` against your own machine.
 
 - **More thoroughly tested than any other JavaScript state-machine
-  library.**  6,277 tests at 100.0% line coverage
+  library.**  6,293 tests at 100.0% line coverage
   ([report](https://coveralls.io/github/StoneCypher/jssm)), plus
   fuzz testing via `fast-check`, with parser test data across ten natural
   languages and Emoji.
@@ -414,11 +414,11 @@ If your contribution is missing here, please open an issue.
 
 <br/>
 
-***6,277 tests***, run 57,064 times.
+***6,293 tests***, run 57,080 times.
 
-- 5,764 specs with 100.0% coverage
+- 5,780 specs with 100.0% coverage
 - 513 fuzz tests with 3.8% coverage
-- 5,014 TypeScript lines - 1.3 tests per line, 11.4 generated tests per line
+- 5,092 TypeScript lines - 1.2 tests per line, 11.2 generated tests per line
 
 [![Actions Status](https://github.com/StoneCypher/jssm/workflows/Node%20CI/badge.svg)](https://github.com/StoneCypher/jssm/actions)
 [![NPM version](https://img.shields.io/npm/v/jssm.svg)](https://www.npmjs.com/package/jssm)

package/custom-elements.json

@@ -30,11 +30,11 @@
               "description": "The current value of the host's `fsl` attribute (or property), or empty string."
             }
           ],
-          "description": "Resolve a `<jssm-instance>`'s FSL source from the three legal channels:\nthe `fsl=\"\"` attribute, a child `<script type=\"text/fsl\">`, and the\nelement's own text content (after stripping the script and any\n`<jssm-*>` companion tags).  Exactly one channel may be used; using\nnone or more than one is an error.\n\nPulled out as a pure function so it's testable without spinning up a\nLit element.\n\n```typescript\nconst div = document.createElement('div');\ndiv.setAttribute('fsl', 'Off -> On;');\nresolve_fsl_source(div as HTMLElement, 'Off -> On;');\n// => { fsl: 'Off -> On;', provided_count: 1, error: undefined }\n```"
+          "description": "Resolve a `<jssm-instance>`'s FSL source from the three legal channels:\r\nthe `fsl=\"\"` attribute, a child `<script type=\"text/fsl\">`, and the\r\nelement's own text content (after stripping the script and any\r\n`<jssm-*>` companion tags).  Exactly one channel may be used; using\r\nnone or more than one is an error.\r\n\r\nPulled out as a pure function so it's testable without spinning up a\r\nLit element.\r\n\r\n```typescript\r\nconst div = document.createElement('div');\r\ndiv.setAttribute('fsl', 'Off -> On;');\r\nresolve_fsl_source(div as HTMLElement, 'Off -> On;');\r\n// => { fsl: 'Off -> On;', provided_count: 1, error: undefined }\r\n```"
         },
         {
           "kind": "class",
-          "description": "Web component that owns a single `Machine<unknown>` constructed from an\nFSL source supplied via one of three mutually exclusive channels:\n\n  1. The `fsl=\"\"` attribute,\n  2. A child `<script type=\"text/fsl\">`,\n  3. The element's own text content (companion `<jssm-*>` children and\n     any `<script type=\"text/fsl\">` are excluded from this channel).\n\nSupplying zero or more than one channel is a thrown error.\n\nOn every transition the component reflects machine state to its own\nattributes (`current-state`, `legal-actions`, `terminal`, `complete`)\nand sets a `--current-state` CSS custom property so consumer CSS can\nstyle by state without subclassing.",
+          "description": "Web component that owns a single `Machine<unknown>` constructed from an\r\nFSL source supplied via one of three mutually exclusive channels:\r\n\r\n  1. The `fsl=\"\"` attribute,\r\n  2. A child `<script type=\"text/fsl\">`,\r\n  3. The element's own text content (companion `<jssm-*>` children and\r\n     any `<script type=\"text/fsl\">` are excluded from this channel).\r\n\r\nSupplying zero or more than one channel is a thrown error.\r\n\r\nOn every transition the component reflects machine state to its own\r\nattributes (`current-state`, `legal-actions`, `terminal`, `complete`)\r\nand sets a `--current-state` CSS custom property so consumer CSS can\r\nstyle by state without subclassing.",
           "name": "JssmInstance",
           "cssProperties": [
             {
@@ -81,7 +81,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "FSL source attribute.  When non-empty, this is the sole channel\nsupplying the machine's source.  Setting both this and a child\n`<script type=\"text/fsl\">` (or non-empty text content) is an error.",
+              "description": "FSL source attribute.  When non-empty, this is the sole channel\r\nsupplying the machine's source.  Setting both this and a child\r\n`<script type=\"text/fsl\">` (or non-empty text content) is an error.",
               "attribute": "fsl"
             },
             {
@@ -92,7 +92,17 @@
               },
               "privacy": "private",
               "default": "undefined",
-              "description": "The underlying machine instance, constructed at `connectedCallback`.\nExposed raw (not proxied) per the #639/#648 design decision so that\nconsumers can use the full Machine API directly.\n\nMarked optional because Lit will instantiate the element before\n`connectedCallback` runs; the instance is guaranteed present after\nconnection."
+              "description": "The underlying machine instance, constructed at `connectedCallback`.\r\nExposed raw (not proxied) per the #639/#648 design decision so that\r\nconsumers can use the full Machine API directly.\r\n\r\nMarked optional because Lit will instantiate the element before\r\n`connectedCallback` runs; the instance is guaranteed present after\r\nconnection."
+            },
+            {
+              "kind": "field",
+              "name": "_action_listeners",
+              "type": {
+                "text": "Array<{\r\n    target  : EventTarget;\r\n    event   : string;\r\n    handler : EventListener;\r\n  }>"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "Records every DOM listener installed by `<jssm-action>` / `data-jssm-action`\r\ndiscovery so disconnectedCallback can remove each one with the\r\nsame handler reference originally passed to `addEventListener`.\r\n\r\nListeners installed via the dedicated `<jssm-action>` tag form may target\r\nelements outside the host (its `selector` is resolved against the host,\r\nbut matching elements live in the document tree), so cleanup must be\r\nexplicit — relying on the host's GC is not sufficient."
             },
             {
               "kind": "field",
@@ -128,7 +138,7 @@
                   "description": "Optional data payload to pass to the action."
                 }
               ],
-              "description": "Convenience wrapper for `machine.action(action, data)`.\nAfter the action, reflects updated state to host attributes and the\n`--current-state` CSS custom property, and requests a Lit update so\nthe state-specific `<slot name=\"state-...\">` can re-pick."
+              "description": "Convenience wrapper for `machine.action(action, data)`.\r\nAfter the action, reflects updated state to host attributes and the\r\n`--current-state` CSS custom property, and requests a Lit update so\r\nthe state-specific `<slot name=\"state-...\">` can re-pick."
             },
             {
               "kind": "method",
@@ -138,7 +148,66 @@
                   "text": "string"
                 }
               },
-              "description": "Convenience wrapper for `machine.state()`.  Returns the current\nstate's name."
+              "description": "Convenience wrapper for `machine.state()`.  Returns the current\r\nstate's name."
+            },
+            {
+              "kind": "method",
+              "name": "_discover_jssm_actions",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Wire DOM events to machine actions, using the two declarative forms from\r\nissue #640:\r\n\r\n 1. Inline attribute form: every descendant of the host carrying a\r\n    `data-jssm-action=\"<name>\"` attribute receives a listener on the\r\n    event named by `data-jssm-event` (default `click`).\r\n 2. Dedicated tag form: each direct `<jssm-action>` child of the host\r\n    supplies a CSS `selector` (scoped to the host), an `action`, and an\r\n    optional `event` (default `click`); every matching descendant\r\n    receives a listener configured by the tag's attributes.\r\n\r\nBoth forms support optional `from-state` guards (dispatch only when the\r\nmachine's current state matches), `from-property` data extraction (pass\r\nthe source element's named property as the action's data argument), and\r\n`prevent-default` / `stop-propagation` modifiers.\r\n\r\nEvery installed listener is recorded in _action_listeners so\r\ndisconnectedCallback can detach them cleanly."
+            },
+            {
+              "kind": "method",
+              "name": "_install_action_listener",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "config",
+                  "type": {
+                    "text": "{\r\n    source           : HTMLElement;\r\n    event_name       : string;\r\n    action_name      : string;\r\n    from_state       : string | undefined;\r\n    from_property    : string | undefined;\r\n    prevent_default  : boolean;\r\n    stop_propagation : boolean;\r\n  }"
+                  },
+                  "description": "Listener configuration."
+                },
+                {
+                  "description": "Element to attach the listener to.",
+                  "name": "config.source"
+                },
+                {
+                  "description": "DOM event to listen for.",
+                  "name": "config.event_name"
+                },
+                {
+                  "description": "Action to dispatch on the machine.",
+                  "name": "config.action_name"
+                },
+                {
+                  "description": "If set, only fire when `machine.state() === from_state`.",
+                  "name": "config.from_state"
+                },
+                {
+                  "description": "If set, pass `source[from_property]` as the action's data argument.",
+                  "name": "config.from_property"
+                },
+                {
+                  "description": "If true, call `e.preventDefault()` before checking the guard.",
+                  "name": "config.prevent_default"
+                },
+                {
+                  "description": "If true, call `e.stopPropagation()` before checking the guard.",
+                  "name": "config.stop_propagation"
+                }
+              ],
+              "description": "Attach one DOM listener that translates a DOM event into a\r\n`machine.action(...)` call, honoring the configured modifiers.  The\r\nlistener is recorded in _action_listeners so it can be removed\r\non disconnect."
             },
             {
               "kind": "method",
@@ -149,7 +218,7 @@
                   "text": "void"
                 }
               },
-              "description": "Reflect machine state onto host attributes and CSS custom properties.\nCalled after every transition and once during `connectedCallback`.\n\nMechanism 1 (#639): writes to host attributes.\nMechanism 3 (#639): writes to host inline-style custom properties."
+              "description": "Reflect machine state onto host attributes and CSS custom properties.\r\nCalled after every transition and once during `connectedCallback`.\r\n\r\nMechanism 1 (#639): writes to host attributes.\r\nMechanism 3 (#639): writes to host inline-style custom properties."
             }
           ],
           "attributes": [
@@ -159,7 +228,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "FSL source attribute.  When non-empty, this is the sole channel\nsupplying the machine's source.  Setting both this and a child\n`<script type=\"text/fsl\">` (or non-empty text content) is an error.",
+              "description": "FSL source attribute.  When non-empty, this is the sole channel\r\nsupplying the machine's source.  Setting both this and a child\r\n`<script type=\"text/fsl\">` (or non-empty text content) is an error.",
               "fieldName": "fsl"
             }
           ],

package/dist/cdn/instance.js

@@ -21327,7 +21327,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.136.0";
+const version = "5.137.0";
 
 // whargarbl lots of these return arrays could/should be sets
 const { state_name_chars, state_name_first_chars, action_label_chars } = constants;
@@ -25185,6 +25185,17 @@ class JssmInstance extends i {
          * connection.
          */
         this._machine = undefined;
+        /**
+         * Records every DOM listener installed by `<jssm-action>` / `data-jssm-action`
+         * discovery so {@link disconnectedCallback} can remove each one with the
+         * same handler reference originally passed to `addEventListener`.
+         *
+         * Listeners installed via the dedicated `<jssm-action>` tag form may target
+         * elements outside the host (its `selector` is resolved against the host,
+         * but matching elements live in the document tree), so cleanup must be
+         * explicit — relying on the host's GC is not sufficient.
+         */
+        this._action_listeners = [];
     }
     /**
      * Raw machine accessor.  Returns the owned {@link Machine} instance.
@@ -25251,7 +25262,7 @@ class JssmInstance extends i {
         //            and dispatch DOM CustomEvents from this element.
         // TODO #641: <jssm-hook> discovery happens here.
         // TODO #643: <jssm-on> discovery happens here.
-        // TODO #640: <jssm-action> discovery happens here.
+        this._discover_jssm_actions();
         // TODO #645: <jssm-bind> discovery happens here.
     }
     /**
@@ -25265,6 +25276,121 @@ class JssmInstance extends i {
         // TODO #638: unsubscribe from machine.on(...) handlers.
         // TODO #641: remove installed hooks.
         // TODO #643/#645: remove installed listeners / bindings.
+        // Remove every listener installed during `<jssm-action>` / `data-jssm-action`
+        // discovery.  Using the original handler reference ensures `removeEventListener`
+        // actually unbinds — anonymous re-creation here would silently leak.
+        for (const entry of this._action_listeners) {
+            entry.target.removeEventListener(entry.event, entry.handler);
+        }
+        this._action_listeners = [];
+    }
+    /**
+     * Wire DOM events to machine actions, using the two declarative forms from
+     * issue #640:
+     *
+     *  1. Inline attribute form: every descendant of the host carrying a
+     *     `data-jssm-action="<name>"` attribute receives a listener on the
+     *     event named by `data-jssm-event` (default `click`).
+     *  2. Dedicated tag form: each direct `<jssm-action>` child of the host
+     *     supplies a CSS `selector` (scoped to the host), an `action`, and an
+     *     optional `event` (default `click`); every matching descendant
+     *     receives a listener configured by the tag's attributes.
+     *
+     * Both forms support optional `from-state` guards (dispatch only when the
+     * machine's current state matches), `from-property` data extraction (pass
+     * the source element's named property as the action's data argument), and
+     * `prevent-default` / `stop-propagation` modifiers.
+     *
+     * Every installed listener is recorded in {@link _action_listeners} so
+     * {@link disconnectedCallback} can detach them cleanly.
+     */
+    _discover_jssm_actions() {
+        var _a, _b, _c, _d;
+        // Inline attribute form: `[data-jssm-action]` descendants.  Per the
+        // ticket, we scan the host's light DOM (not the shadow tree, which is
+        // owned by us) and skip any element living inside a `<jssm-action>` tag
+        // — those tags are pure data markup, never the source of an event.
+        const inline_targets = Array.from(this.querySelectorAll('[data-jssm-action]')).filter(el => el.closest('jssm-action') === null);
+        for (const el of inline_targets) {
+            this._install_action_listener({
+                source: el,
+                event_name: (_a = el.dataset['jssmEvent']) !== null && _a !== void 0 ? _a : 'click',
+                action_name: el.dataset['jssmAction'],
+                from_state: el.dataset['jssmFromState'],
+                from_property: el.dataset['jssmFromProperty'],
+                prevent_default: 'jssmPreventDefault' in el.dataset,
+                stop_propagation: 'jssmStopPropagation' in el.dataset,
+            });
+        }
+        // Dedicated tag form: direct `<jssm-action>` children of the host.
+        // `:scope >` keeps a nested `<jssm-instance>`'s actions from being
+        // claimed by an outer host.
+        const tags = this.querySelectorAll(':scope > jssm-action');
+        for (const tag of Array.from(tags)) {
+            const selector = tag.getAttribute('selector');
+            const action_name = tag.getAttribute('action');
+            if (selector === null || action_name === null) {
+                // Required attrs missing — skip, but don't throw: a malformed tag
+                // shouldn't break the rest of the host's wiring.
+                continue;
+            }
+            const event_name = (_b = tag.getAttribute('event')) !== null && _b !== void 0 ? _b : 'click';
+            const from_state = (_c = tag.getAttribute('from-state')) !== null && _c !== void 0 ? _c : undefined;
+            const from_property = (_d = tag.getAttribute('from-property')) !== null && _d !== void 0 ? _d : undefined;
+            const prevent_default = tag.hasAttribute('prevent-default');
+            const stop_propagation = tag.hasAttribute('stop-propagation');
+            const sources = this.querySelectorAll(selector);
+            for (const src of Array.from(sources)) {
+                this._install_action_listener({
+                    source: src,
+                    event_name,
+                    action_name,
+                    from_state,
+                    from_property,
+                    prevent_default,
+                    stop_propagation,
+                });
+            }
+        }
+    }
+    /**
+     * Attach one DOM listener that translates a DOM event into a
+     * `machine.action(...)` call, honoring the configured modifiers.  The
+     * listener is recorded in {@link _action_listeners} so it can be removed
+     * on disconnect.
+     *
+     * @param config - Listener configuration.
+     * @param config.source - Element to attach the listener to.
+     * @param config.event_name - DOM event to listen for.
+     * @param config.action_name - Action to dispatch on the machine.
+     * @param config.from_state - If set, only fire when `machine.state() === from_state`.
+     * @param config.from_property - If set, pass `source[from_property]` as the action's data argument.
+     * @param config.prevent_default - If true, call `e.preventDefault()` before checking the guard.
+     * @param config.stop_propagation - If true, call `e.stopPropagation()` before checking the guard.
+     */
+    _install_action_listener(config) {
+        const handler = (e) => {
+            if (config.prevent_default) {
+                e.preventDefault();
+            }
+            if (config.stop_propagation) {
+                e.stopPropagation();
+            }
+            // Guard: skip dispatch when the machine isn't in the required state.
+            if (config.from_state !== undefined && this.state() !== config.from_state) {
+                return;
+            }
+            const data = config.from_property !== undefined
+                ? config.source[config.from_property]
+                : undefined;
+            this.do(config.action_name, data);
+        };
+        config.source.addEventListener(config.event_name, handler);
+        this._action_listeners.push({
+            target: config.source,
+            event: config.event_name,
+            handler,
+        });
     }
     /**
      * Reflect machine state onto host attributes and CSS custom properties.

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.136.0";
+const version = "5.137.0";
 
 // whargarbl lots of these return arrays could/should be sets
 const { state_name_chars, state_name_first_chars, action_label_chars } = constants;