jssm 5.136.0 → 5.138.0

package/dist/wc/instance.js

@@ -1,6 +1,208 @@
 import { css, LitElement, html } from 'lit';
 import { sm } from 'jssm';
 
+const VALID_KINDS = new Set([
+    'hook',
+    'named',
+    'any transition',
+    'standard transition',
+    'main transition',
+    'forced transition',
+    'entry',
+    'exit',
+    'any action',
+    'global action',
+]);
+/**
+ * Build a {@link JssmHookProxy} that wraps an arbitrary hook context object.
+ *
+ * The context shape varies by hook kind (`from`/`to`/`action` may be absent
+ * for transition-kind hooks), so this normalizes the shape via optional
+ * fields and exposes mutable `data` while keeping the rest read-only.
+ *
+ * The `machine` parameter is used only for `state()`, so unit tests can
+ * substitute any object with a `state(): unknown` method.
+ *
+ * @param ctx     - Raw hook context passed by jssm.
+ * @param machine - The owning machine; used for the `state()` accessor.
+ * @returns A proxy object suitable for passing to a user handler.
+ */
+function make_hook_proxy(ctx, machine) {
+    return {
+        get data() {
+            return ctx.data;
+        },
+        set data(next) {
+            ctx.data = next;
+        },
+        get from() {
+            return ctx.from;
+        },
+        get to() {
+            return ctx.to;
+        },
+        get action() {
+            return ctx.action;
+        },
+        state() {
+            return String(machine.state());
+        },
+    };
+}
+/**
+ * Compile a textContent body into a callable user handler.
+ *
+ * Uses dynamic function construction — the same primitive browsers use
+ * internally for `<a onclick="...">` and `setTimeout(stringBody, ms)`.
+ * Strict CSP without `'unsafe-eval'` blocks this and the call will throw;
+ * consumers should fall back to the `handler="name"` form there.
+ *
+ * Prepends a `//# sourceURL=` comment so devtools surface a meaningful name
+ * in stack traces instead of `anonymous`.
+ *
+ * @param body     - Trimmed textContent of the `<jssm-hook>` element.
+ * @param debug_id - Identifier appended to the synthetic sourceURL.
+ * @returns The compiled handler.
+ */
+function compile_inline_body(body, debug_id) {
+    const annotated = `//# sourceURL=jssm-hook:${debug_id}\n${body}`;
+    const ctor = Function;
+    return new ctor('m', annotated);
+}
+/**
+ * Resolve a `handler="name"` attribute to a callable by consulting first the
+ * optional in-WC registry, then `globalThis[name]`.  Throws a clear error if
+ * neither resolves.
+ *
+ * @param name     - The handler name from the `handler=""` attribute.
+ * @param registry - Optional in-WC registry to consult first.
+ * @returns The resolved handler.
+ * @throws Error  - If no callable of that name is found in either location.
+ */
+function resolve_named_handler(name, registry) {
+    if (registry !== undefined) {
+        const registered = registry.get(name);
+        if (registered !== undefined) {
+            return registered;
+        }
+    }
+    const global = globalThis[name];
+    if (typeof global === 'function') {
+        return global;
+    }
+    throw new Error(`<jssm-hook handler="${name}">: handler not found in registry or globalThis`);
+}
+/**
+ * Validate and normalize a `<jssm-hook kind="...">` value, defaulting to
+ * `"hook"` when the attribute is absent.  Throws on unknown kinds rather
+ * than silently doing nothing later.
+ *
+ * @param raw - The raw attribute value, or null if not present.
+ * @returns The normalized {@link JssmHookKind}.
+ * @throws Error - On an unknown kind.
+ */
+function normalize_hook_kind(raw) {
+    if (raw === null || raw === undefined || raw === '') {
+        return 'hook';
+    }
+    if (!VALID_KINDS.has(raw)) {
+        throw new Error(`<jssm-hook kind="${raw}">: unknown hook kind (expected one of: ${[...VALID_KINDS].join(', ')})`);
+    }
+    return raw;
+}
+/**
+ * Parse a single `<jssm-hook>` element into a {@link JssmHookInstallSpec}.
+ *
+ * Validates the mutual-exclusion rule between `handler="name"` and inline
+ * body, defaults `kind` to `"hook"`, resolves named handlers against the
+ * optional registry then `globalThis`, and compiles inline bodies via
+ * dynamic function construction.  Conditional-required attributes (e.g.
+ * `from`/`to` for `kind="hook"`) are NOT validated here — `set_hook` will
+ * throw with its own clear errors on missing pieces, which keeps the
+ * error surface single-sourced.
+ *
+ * @param el       - The `<jssm-hook>` element to parse.
+ * @param debug_id - Identifier used in the inline body's sourceURL.
+ * @param registry - Optional in-WC registry of named handlers.
+ * @returns A {@link JssmHookInstallSpec} describing what to install.
+ * @throws Error - On mutual-exclusion violation, unknown kind, or unresolved name.
+ */
+function parse_hook_element(el, debug_id, registry) {
+    var _a, _b, _c, _d;
+    const handler_attr = el.getAttribute('handler');
+    const raw_text = el.textContent;
+    const body_text = (raw_text === null ? '' : raw_text).trim();
+    if (handler_attr !== null && body_text.length > 0) {
+        throw new Error('<jssm-hook>: specify handler="name" OR inline body, not both');
+    }
+    if (handler_attr === null && body_text.length === 0) {
+        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);
+    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;
+    const to = (_b = el.getAttribute('to')) !== null && _b !== void 0 ? _b : undefined;
+    const action = (_c = el.getAttribute('action')) !== null && _c !== void 0 ? _c : undefined;
+    const name = (_d = el.getAttribute('name')) !== null && _d !== void 0 ? _d : undefined;
+    return { kind, name, from, to, action, user_handler };
+}
+/**
+ * Wrap a {@link JssmHookUserHandler} so that jssm's native hook contract is
+ * satisfied: the user gets a friendly proxy, the proxy's mutated `data`
+ * becomes the `HookComplexResult.data`, and an explicit `false` return
+ * cancels the transition.
+ *
+ * Any non-`false` return — including `undefined`, `true`, or an arbitrary
+ * object — allows the transition.  This matches the contract spelled out
+ * in the issue (#641): "return false cancels; anything else allows".
+ *
+ * @param spec    - The parsed install spec carrying the user handler.
+ * @param machine - The owning machine; used by the proxy's `state()`.
+ * @returns A wrapped handler suitable for `set_hook`.
+ */
+function wrap_user_handler(spec, machine) {
+    const user = spec.user_handler;
+    return (ctx) => {
+        const proxy = make_hook_proxy(ctx, machine);
+        const result = user(proxy);
+        if (result === false) {
+            return false;
+        }
+        return { pass: true, data: proxy.data };
+    };
+}
+/**
+ * Build the typed descriptor object passed to `machine.set_hook` (and later
+ * to `machine.remove_hook` for cleanup) from a parsed {@link JssmHookInstallSpec}
+ * and the wrapped handler.
+ *
+ * For kinds that need `from`/`to`/`action`, the descriptor includes those.
+ * Missing required keys produce `undefined` here; jssm's `set_hook` will
+ * surface the error with its own clear message so we don't duplicate
+ * validation.
+ *
+ * Return type is `unknown` because jssm's `HookDescription` is a
+ * discriminated union and our runtime-discriminator value can't be tracked
+ * by TypeScript across the build.  The WC casts at the `set_hook` call site.
+ *
+ * @param spec    - The parsed install spec.
+ * @param wrapped - The wrapped (friendly-proxy) handler from {@link wrap_user_handler}.
+ * @returns A descriptor object for `set_hook`/`remove_hook`.
+ */
+function build_hook_descriptor(spec, wrapped) {
+    const base = { kind: spec.kind, handler: wrapped };
+    if (spec.from !== undefined)
+        base.from = spec.from;
+    if (spec.to !== undefined)
+        base.to = spec.to;
+    if (spec.action !== undefined)
+        base.action = spec.action;
+    return base;
+}
+
 /**
  * Resolve a `<jssm-instance>`'s FSL source from the three legal channels:
  * the `fsl=""` attribute, a child `<script type="text/fsl">`, and the
@@ -116,6 +318,46 @@ class JssmInstance extends LitElement {
          * connection.
          */
         this._machine = undefined;
+        /**
+         * Per-instance registry of named hook handlers consulted before
+         * `globalThis` when resolving `<jssm-hook handler="name">`.
+         *
+         * Initialized to an empty `Map`; consumers may populate it before the
+         * element connects to provide handlers without polluting global scope —
+         * useful for module-scoped SPAs where strict CSP blocks inline-body hooks.
+         *
+         * @see {@link parse_hook_element}
+         */
+        this.registry = new Map();
+        /**
+         * Descriptors for hooks this WC installed at connect time, used in
+         * `disconnectedCallback` to call `remove_hook` for each so the underlying
+         * machine doesn't leak handlers when the element is detached.
+         *
+         * Captured at install time because `remove_hook` matches by descriptor
+         * shape (not handler identity), and we need to record the wrapped handler
+         * we passed to `set_hook` to undo the registration cleanly.  Stored as
+         * `unknown[]` and cast at the call site because jssm's `HookDescription`
+         * is a discriminated union whose discriminator is only known at runtime.
+         */
+        this._installed_hooks = [];
+        /**
+         * Counter used to give each compiled inline-body hook a unique debug id
+         * for its `//# sourceURL=jssm-hook:N` annotation.  Per-instance so that
+         * multiple `<jssm-instance>` elements on a page don't share numbering.
+         */
+        this._hook_debug_counter = 0;
+        /**
+         * 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.
@@ -180,22 +422,191 @@ class JssmInstance extends LitElement {
         this.requestUpdate();
         // TODO #638: subscribe to machine.on('transition', ...) once available
         //            and dispatch DOM CustomEvents from this element.
-        // TODO #641: <jssm-hook> discovery happens here.
+        // #641: <jssm-hook> declarative discovery.
+        this._install_declarative_hooks();
         // 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.
     }
     /**
-     * Lifecycle hook.  Cleans up any installed subscriptions.  Currently a
-     * no-op (no subscriptions are installed in the base scaffolding) — the
-     * empty body is intentional so the future tickets #638/#641/#643/#645
-     * have a single canonical hook to extend.
+     * Discover every direct-child `<jssm-hook>` element and install each
+     * against the owned machine.  Handlers are wrapped with the friendly-proxy
+     * 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;
+        const hook_els = this.querySelectorAll(':scope > jssm-hook');
+        for (const el of Array.from(hook_els)) {
+            const debug_id = `${this._hook_id_prefix()}${++this._hook_debug_counter}`;
+            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.
+     */
+    _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.
      */
     disconnectedCallback() {
         super.disconnectedCallback();
         // TODO #638: unsubscribe from machine.on(...) handlers.
-        // TODO #641: remove installed hooks.
+        // #641: remove installed hooks.
+        if (this._machine !== undefined) {
+            const machine = this._machine;
+            for (const desc of this._installed_hooks) {
+                machine.remove_hook(desc);
+            }
+        }
+        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.
+        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/package.json

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