jssm 5.138.0 → 5.139.0

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.138.0";
+const version = "5.139.0";
 
 // whargarbl lots of these return arrays could/should be sets
 const { state_name_chars, state_name_first_chars, action_label_chars } = constants;
@@ -25133,7 +25133,7 @@ function make_hook_proxy(ctx, machine) {
  * @param debug_id - Identifier appended to the synthetic sourceURL.
  * @returns The compiled handler.
  */
-function compile_inline_body(body, debug_id) {
+function compile_inline_body$1(body, debug_id) {
     const annotated = `//# sourceURL=jssm-hook:${debug_id}\n${body}`;
     const ctor = Function;
     return new ctor('m', annotated);
@@ -25148,7 +25148,7 @@ function compile_inline_body(body, debug_id) {
  * @returns The resolved handler.
  * @throws Error  - If no callable of that name is found in either location.
  */
-function resolve_named_handler(name, registry) {
+function resolve_named_handler$1(name, registry) {
     if (registry !== undefined) {
         const registered = registry.get(name);
         if (registered !== undefined) {
@@ -25208,8 +25208,8 @@ function parse_hook_element(el, debug_id, registry) {
         throw new Error('<jssm-hook>: must specify either handler="name" attribute or an inline body');
     }
     const user_handler = handler_attr !== null
-        ? resolve_named_handler(handler_attr, registry)
-        : compile_inline_body(body_text, debug_id);
+        ? resolve_named_handler$1(handler_attr, registry)
+        : compile_inline_body$1(body_text, debug_id);
     const kind = normalize_hook_kind(el.getAttribute('kind'));
     // Convert null → undefined so downstream descriptors omit absent keys.
     const from = (_a = el.getAttribute('from')) !== null && _a !== void 0 ? _a : undefined;
@@ -25272,6 +25272,177 @@ function build_hook_descriptor(spec, wrapped) {
     return base;
 }
 
+/**
+ * Allow-list of event names accepted by `<jssm-on event="...">`.  Must stay
+ * in sync with the `JssmEventName` union in `jssm_types.ts` (the library's
+ * `machine.on(...)` event API, added in #638).  Validating here gives the
+ * declarative wiring a clear "unknown event name" error at the WC layer
+ * instead of relying on a downstream library throw whose message would
+ * mention `machine.on(...)` rather than the offending tag.
+ */
+const JSSM_ON_EVENT_NAMES = new Set([
+    'transition',
+    'rejection',
+    'action',
+    'entry',
+    'exit',
+    'terminal',
+    'complete',
+    'error',
+    'data-change',
+    'override',
+    'timeout',
+    'hook-registration',
+    'hook-removal'
+]);
+/**
+ * Parse a `<jssm-on>` element into a validated {@link ParsedJssmOn}
+ * record.  Centralized so the declarative-tag logic is testable without
+ * spinning up the full `<jssm-instance>` lifecycle.
+ *
+ * Validation rules (per #643):
+ *   - `event` is required and must be in {@link JSSM_ON_EVENT_NAMES}.
+ *   - Either a `handler="name"` attribute or non-empty `textContent`
+ *     must be supplied, but not both.
+ *   - `state` is only meaningful for `event="entry"` / `event="exit"`;
+ *     it's silently ignored on other events.
+ *   - `from` / `to` are only meaningful for `event="transition"`; they
+ *     are silently ignored on other events.  Both → AND (a specific
+ *     edge).  Neither → unfiltered.
+ *
+ * ```typescript
+ * const el = document.createElement('jssm-on');
+ * el.setAttribute('event', 'entry');
+ * el.setAttribute('state', 'paid');
+ * el.setAttribute('handler', 'onPaid');
+ * parse_jssm_on_element(el);
+ * // => { event: 'entry', handler_name: 'onPaid', inline_body: undefined,
+ * //      once: false, name: undefined, filter: { state: 'paid' } }
+ * ```
+ *
+ * @param el - The `<jssm-on>` element to parse.
+ * @returns A validated {@link ParsedJssmOn} record.
+ * @throws If `event` is missing, unknown, both handler forms are
+ *         supplied, or neither handler form is supplied.
+ */
+function parse_jssm_on_element(el) {
+    const event_attr = el.getAttribute('event');
+    if (event_attr === null || event_attr.trim().length === 0) {
+        throw new Error('<jssm-on>: missing required `event` attribute');
+    }
+    const event = event_attr.trim();
+    if (!JSSM_ON_EVENT_NAMES.has(event)) {
+        throw new Error(`<jssm-on>: unknown event "${event}"`);
+    }
+    const handler_attr = el.getAttribute('handler');
+    const handler_name = (handler_attr !== null && handler_attr.trim().length > 0)
+        ? handler_attr.trim()
+        : undefined;
+    // textContent on a connected HTMLElement is always a string, so the
+    // historical `?? ''` fallback never executed.  Use a direct cast here
+    // and let test cases that supply a literal `null` (defensive coverage)
+    // hit the `=== null` branch instead — that branch is reachable via
+    // Object.defineProperty in tests, where the `??` form would be a dead
+    // operator.
+    const body_text = el.textContent;
+    const inline_body = (body_text !== null && body_text.trim().length > 0) ? body_text : undefined;
+    if (handler_name !== undefined && inline_body !== undefined) {
+        throw new Error('<jssm-on>: specify handler="name" OR inline body, not both');
+    }
+    if (handler_name === undefined && inline_body === undefined) {
+        throw new Error('<jssm-on>: must specify handler="name" or an inline body');
+    }
+    const once_attr = el.hasAttribute('once');
+    const name_attr = el.getAttribute('name');
+    const name = (name_attr !== null && name_attr.trim().length > 0) ? name_attr.trim() : undefined;
+    // Build the filter, but only honour attributes that apply to this event.
+    // Unknown filter attributes for an event are silently ignored, matching
+    // the documented semantics in the issue.
+    let filter;
+    if (event === 'entry' || event === 'exit') {
+        const state_attr = el.getAttribute('state');
+        if (state_attr !== null && state_attr.length > 0) {
+            filter = { state: state_attr };
+        }
+    }
+    else if (event === 'transition') {
+        const from_attr = el.getAttribute('from');
+        const to_attr = el.getAttribute('to');
+        const candidate = {};
+        if (from_attr !== null && from_attr.length > 0) {
+            candidate.from = from_attr;
+        }
+        if (to_attr !== null && to_attr.length > 0) {
+            candidate.to = to_attr;
+        }
+        if (Object.keys(candidate).length > 0) {
+            filter = candidate;
+        }
+    }
+    return {
+        event,
+        handler_name,
+        inline_body,
+        once: once_attr,
+        name,
+        filter
+    };
+}
+/**
+ * Optional global registry that `<jssm-on>` (and, later, `<jssm-hook>`)
+ * consult first when resolving a `handler="name"` attribute.  Consumers
+ * register named handlers here in a strict-CSP environment where a stray
+ * `globalThis[name]` isn't acceptable.  Falls through to `globalThis[name]`
+ * if the registry has no entry.
+ *
+ * Intentionally a `Map<string, Function>` rather than a class with methods,
+ * so consumers can use any of `.get`, `.set`, `.delete`, `.clear` directly
+ * without a thin wrapper API.
+ */
+const jssm_handler_registry = new Map();
+/**
+ * Resolve a named handler from the registry, then from `globalThis`.
+ * Throws if neither lookup finds a function — earlier failure here is
+ * better than a delayed "is not a function" at first event delivery.
+ *
+ * @param name - The handler name as supplied by `handler="..."`.
+ * @returns The resolved function.
+ * @throws If no function is registered under `name`.
+ */
+function resolve_named_handler(name) {
+    const from_registry = jssm_handler_registry.get(name);
+    if (typeof from_registry === 'function') {
+        return from_registry;
+    }
+    const from_global = globalThis[name];
+    if (typeof from_global === 'function') {
+        return from_global;
+    }
+    throw new Error(`<jssm-on>: handler "${name}" not found in registry or globalThis`);
+}
+/**
+ * Compile an inline-body string into a handler function whose single
+ * parameter is `e` (the event detail object).  Uses the same dynamic
+ * `Function(...)` constructor that browsers use internally for inline
+ * event-handler attributes such as `<a onclick="...">`; the input here
+ * is consumer-authored markup, never network data, so the surface is
+ * exactly that of an inline event-handler attribute and the same CSP
+ * caveats apply (strict CSP without `'unsafe-eval'` blocks it).  A
+ * `//# sourceURL=jssm-on:N` pragma is appended so devtools stack traces
+ * point at a meaningful name.
+ *
+ * @param body - The inline JS body (function body, not full function).
+ * @param source_id - A short identifier for the sourceURL pragma.
+ * @returns The compiled handler.
+ */
+function compile_inline_body(body, source_id) {
+    const wrapped = `${body}\n//# sourceURL=jssm-on:${source_id}`;
+    // The Function constructor is intentional here — see the docblock above
+    // for the rationale and the CSP caveat.  Equivalent to how browsers wire
+    // up inline event handlers; the input is consumer-authored markup.
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
+    return new Function('e', wrapped); // skipcq: JS-0086
+}
 /**
  * Resolve a `<jssm-instance>`'s FSL source from the three legal channels:
  * the `fsl=""` attribute, a child `<script type="text/fsl">`, and the
@@ -25387,6 +25558,15 @@ class JssmInstance extends i {
          * connection.
          */
         this._machine = undefined;
+        /**
+         * Unsubscribe callbacks for every `machine.on(...)` / `machine.once(...)`
+         * subscription installed from a `<jssm-on>` child during
+         * `connectedCallback`.  Walked in `disconnectedCallback` so a removed
+         * `<jssm-instance>` doesn't leave dangling handlers on its (now-orphan)
+         * machine.  Array (insertion order) rather than Set so cleanup order is
+         * deterministic and easy to reason about.
+         */
+        this._on_unsubscribes = [];
         /**
          * Per-instance registry of named hook handlers consulted before
          * `globalThis` when resolving `<jssm-hook handler="name">`.
@@ -25493,9 +25673,52 @@ class JssmInstance extends i {
         //            and dispatch DOM CustomEvents from this element.
         // #641: <jssm-hook> declarative discovery.
         this._install_declarative_hooks();
-        // TODO #643: <jssm-on> discovery happens here.
-        this._discover_jssm_actions();
+        // #643: <jssm-on> declarative event observation.
+        this._install_jssm_on_children();
         // TODO #645: <jssm-bind> discovery happens here.
+        // #640: <jssm-action> DOM event → machine action wiring.
+        this._discover_jssm_actions();
+    }
+    /**
+     * Discover direct-child `<jssm-on>` elements and install their
+     * subscriptions on the owned machine.  Per #643:
+     *
+     * - Direct children only (`:scope > jssm-on`).  Deeper nesting is the
+     *   responsibility of a future MutationObserver-driven v2.
+     * - Each `<jssm-on>` is parsed by {@link parse_jssm_on_element}, which
+     *   enforces the form / event-name / filter rules.
+     * - Handlers come from {@link resolve_named_handler} (form A) or
+     *   {@link compile_inline_body} (form B), and the result is installed
+     *   via `machine.on(...)` or `machine.once(...)` depending on the
+     *   element's `once` attribute.
+     * - Every returned unsubscribe is tracked in {@link _on_unsubscribes}
+     *   so {@link disconnectedCallback} can release them all.
+     *
+     * Called once from `connectedCallback` after the machine has been
+     * constructed.  Any error thrown by parsing or resolution propagates
+     * out so it surfaces via jsdom's error event (matching the rest of
+     * `<jssm-instance>`'s "fail loud at connect" policy).
+     */
+    _install_jssm_on_children() {
+        const machine = this._machine;
+        const on_nodes = this.querySelectorAll(':scope > jssm-on');
+        let index = 0;
+        for (const el of Array.from(on_nodes)) {
+            index += 1;
+            const parsed = parse_jssm_on_element(el);
+            const handler = parsed.handler_name !== undefined
+                ? resolve_named_handler(parsed.handler_name)
+                : compile_inline_body(parsed.inline_body, String(index));
+            // Argument shape: machine.on(name, handler) when no filter, or
+            // machine.on(name, filter, handler) when filtered.  Same for once.
+            // `as any` collapses the per-event detail typing — the WC is a
+            // schema-erased entry point and the type-safety belongs upstream.
+            const subscribe = parsed.once ? machine.once.bind(machine) : machine.on.bind(machine);
+            const unsubscribe = parsed.filter === undefined
+                ? subscribe(parsed.event, handler)
+                : subscribe(parsed.event, parsed.filter, handler);
+            this._on_unsubscribes.push(unsubscribe);
+        }
     }
     /**
      * Discover every direct-child `<jssm-hook>` element and install each
@@ -25503,17 +25726,6 @@ class JssmInstance extends i {
      * adapter that lets user code write `m.data = ...` and return `false` to
      * cancel — see {@link make_hook_proxy} and the issue (#641) doc-comment
      * for the full contract.
-     *
-     * Direct children only (the `:scope > jssm-hook` selector) so that nested
-     * `<jssm-instance>` elements don't have their child hooks installed on
-     * the outer machine.
-     *
-     * Tracks every installed descriptor in `_installed_hooks` so that
-     * `disconnectedCallback` can remove them on detach.
-     *
-     * @throws Error - On a malformed `<jssm-hook>` (mutual-exclusion violation,
-     *                 unknown kind, unresolved name, or jssm's own missing-key
-     *                 errors from `set_hook`).
      */
     _install_declarative_hooks() {
         const machine = this._machine;
@@ -25523,35 +25735,26 @@ class JssmInstance extends i {
             const spec = parse_hook_element(el, debug_id, this.registry);
             const wrapped = wrap_user_handler(spec, machine);
             const desc = build_hook_descriptor(spec, wrapped);
-            // `desc` is shaped from runtime kind discrimination; jssm's typed
-            // `HookDescription` is a static discriminated union that TS can't
-            // unify with our runtime-built object, hence the cast.
             machine.set_hook(desc);
             this._installed_hooks.push(desc);
         }
     }
     /**
      * Prefix used in synthetic `//# sourceURL=jssm-hook:<prefix><n>` annotations
-     * for inline-body hooks compiled by this element.  Includes the element's
-     * `id` when present so multi-instance pages can tell sources apart in
-     * devtools.
+     * for inline-body hooks compiled by this element.
      */
     _hook_id_prefix() {
         const host_id = this.getAttribute('id');
         return host_id !== null && host_id.length > 0 ? `${host_id}-` : '';
     }
     /**
-     * Lifecycle hook.  Removes every hook this WC installed via
-     * `<jssm-hook>` discovery so the underlying machine doesn't leak handlers
-     * when the element detaches.  Called automatically by the browser; the
-     * machine itself is not destroyed (consumers can reuse it).
-     *
-     * Future tickets #638/#643/#645 will extend this to drop other
-     * subscriptions / listeners installed by their respective tags.
+     * Lifecycle hook.  Cleans up everything the WC installed at connect: hook
+     * registrations from `<jssm-hook>`, event subscriptions from `<jssm-on>`,
+     * and DOM listeners from `<jssm-action>` / `data-jssm-action`.
      */
     disconnectedCallback() {
         super.disconnectedCallback();
-        // TODO #638: unsubscribe from machine.on(...) handlers.
+        // TODO #638: unsubscribe from any direct machine.on(...) handlers added by host.
         // #641: remove installed hooks.
         if (this._machine !== undefined) {
             const machine = this._machine;
@@ -25560,10 +25763,16 @@ class JssmInstance extends i {
             }
         }
         this._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.
+        // #643: release every subscription installed from a <jssm-on> child.
+        for (const off of this._on_unsubscribes) {
+            try {
+                off();
+            }
+            catch ( /* swallow — cleanup must not throw past us */_a) { /* swallow — cleanup must not throw past us */ }
+        }
+        this._on_unsubscribes = [];
+        // TODO #645: remove installed bindings.
+        // #640: remove DOM listeners installed via <jssm-action> / data-jssm-action.
         for (const entry of this._action_listeners) {
             entry.target.removeEventListener(entry.event, entry.handler);
         }
@@ -25571,30 +25780,12 @@ class JssmInstance extends i {
     }
     /**
      * 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.
+     * issue #640.  Both forms support optional `from-state` guards,
+     * `from-property` data extraction, and `prevent-default` /
+     * `stop-propagation` modifiers.
      */
     _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({
@@ -25607,16 +25798,11 @@ class JssmInstance extends i {
                 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';
@@ -25640,18 +25826,7 @@ class JssmInstance extends i {
     }
     /**
      * 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.
+     * `machine.action(...)` call, honoring the configured modifiers.
      */
     _install_action_listener(config) {
         const handler = (e) => {
@@ -25661,7 +25836,6 @@ class JssmInstance extends i {
             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;
             }

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