@jxsuite/runtime 3.1.0 → 4.0.0

package/src/statements.ts

@@ -7,7 +7,7 @@
  * (interpreter) and `compileStatements` (JS emitter), shared by the runtime and every compiler
  * target. Statement kinds reuse web-platform names only: bare expression nodes (§19), the JSON
  * Schema `if`/`then`/`else` triple, `$switch`/`cases` in statement position, and WHATWG's
- * `dispatchEvent` with `CustomEventInit` members.
+ * `dispatchEvent` with `CustomEventInit` members, `stopPropagation` and `preventDefault`.
  */
 
 import {
@@ -24,11 +24,23 @@ import type { JxScope } from "./types.ts";
 interface RunOpts {
   /** Named-formula-style arguments bound for $args/<name> refs in the body. */
   args?: Record<string, unknown>;
-  /** Dispatch target for dispatchEvent statements; defaults to event?.currentTarget. */
-  target?: EventTarget | null;
+  /**
+   * Dispatch target for dispatchEvent statements when there is no event to read `currentTarget`
+   * from — a parameterised body invoked through `call`, or a lifecycle hook. A thunk is read at
+   * dispatch time, because a mount's root does not exist yet when its scope is built.
+   */
+  target?: EventTarget | null | (() => EventTarget | null);
 }
 
-function statementKind(statement: JxStatement): "expression" | "if" | "switch" | "dispatch" {
+type StatementKind =
+  | "expression"
+  | "if"
+  | "switch"
+  | "dispatch"
+  | "stopPropagation"
+  | "preventDefault";
+
+function statementKind(statement: JxStatement): StatementKind {
   if ("operator" in statement) {
     return "expression";
   }
@@ -38,6 +50,12 @@ function statementKind(statement: JxStatement): "expression" | "if" | "switch" |
   if ("$switch" in statement) {
     return "switch";
   }
+  if ("stopPropagation" in statement) {
+    return "stopPropagation";
+  }
+  if ("preventDefault" in statement) {
+    return "preventDefault";
+  }
   return "dispatch";
 }
 
@@ -91,7 +109,9 @@ export async function runStatements(
           bubbles?: boolean;
           composed?: boolean;
         };
-        const target = opts.target ?? event?.currentTarget;
+        // An event's own target wins; the option is the fallback for bodies run without one.
+        const fallback = typeof opts.target === "function" ? opts.target() : opts.target;
+        const target = event?.currentTarget ?? fallback;
         if (!target) {
           break;
         }
@@ -108,6 +128,15 @@ export async function runStatements(
         target.dispatchEvent(new CustomEvent(dispatch.dispatchEvent, init));
         break;
       }
+      case "stopPropagation": {
+        // The event the handler is running for; a body run without one has nothing to stop.
+        event?.stopPropagation();
+        break;
+      }
+      case "preventDefault": {
+        event?.preventDefault();
+        break;
+      }
       default: {
         break;
       }
@@ -203,6 +232,14 @@ export function compileStatements(
         );
         break;
       }
+      case "stopPropagation": {
+        lines.push(`${indent}${opts.eventParam ?? "event"}?.stopPropagation();`);
+        break;
+      }
+      case "preventDefault": {
+        lines.push(`${indent}${opts.eventParam ?? "event"}?.preventDefault();`);
+        break;
+      }
       default: {
         break;
       }

package/src/types.ts

@@ -1,5 +1,5 @@
 /// <reference lib="dom" />
-import type { JxElement, JxPath } from "@jxsuite/schema/types";
+import type { JxDocument, JxElement, JxPath } from "@jxsuite/schema/types";
 
 export type { JxPath } from "@jxsuite/schema/types";
 
@@ -13,8 +13,74 @@ export type JxScope = Record<string, unknown>;
 /** An event handler stored in the scope: `(scope, event) => void`. */
 export type JxEventHandler = (scope: JxScope, event: Event) => unknown;
 
+/**
+ * A host-supplied document source consulted before the network. Returning `undefined` means "not
+ * mine" and the runtime fetches as usual; a hit is served for THIS mount only and never enters the
+ * shared resolve cache.
+ */
+export type DocumentResolver = (url: string) => JxDocument | Promise<JxDocument> | undefined;
+
+/**
+ * Per-mount configuration, threaded through a render instead of read from module globals. A shell
+ * that hosts many roots beside a canvas needs each root to answer "which `$media`, which base,
+ * which documents" for itself; the module-level setters remain the defaults a context inherits.
+ */
+export interface JxContext {
+  /** Base URL the document's own references resolve against. */
+  base: string;
+  /**
+   * Root `$media` map for components that declare `@--name` blocks but carry no own `$media`; null
+   * inherits the module default.
+   */
+  media: Record<string, string> | null;
+  /** The mount's rendered root, set once render completes — the default `dispatchEvent` target. */
+  root: HTMLElement | Text | null;
+  resolver?: DocumentResolver;
+  /** Per-mount override of `setSkipServerFunctions`; undefined inherits the module default. */
+  skipServerFunctions?: boolean;
+  /** Per-mount override of `setSkipAutoRequests`; undefined inherits the module default. */
+  skipAutoRequests?: boolean;
+}
+
+/** Options for {@link mount}: the host's half of the embedding contract (specs/embedding.md). */
+export interface JxMountOptions {
+  /**
+   * Host members merged into the document's scope before its own `state` is built: reactive
+   * records, refs, computeds and plain functions. A document `state` entry of the same name wins.
+   * Keys beginning with `$` or `#` are runtime vocabulary and are refused.
+   */
+  scope?: Record<string, unknown>;
+  base?: string;
+  media?: Record<string, string>;
+  resolver?: DocumentResolver;
+  skipServerFunctions?: boolean;
+  skipAutoRequests?: boolean;
+  /** Aborting disposes the mount; an already-aborted signal mounts nothing. */
+  signal?: AbortSignal;
+  onNodeCreated?: JxRenderOptions["onNodeCreated"];
+  onNodeMoved?: JxRenderOptions["onNodeMoved"];
+}
+
+/** A mounted document: its live scope, its root node, and the disposer that tears it down. */
+export interface JxMount {
+  /** The reactive scope. Host writes to members it supplied propagate into the render. */
+  readonly scope: JxScope;
+  readonly root: HTMLElement | Text;
+  /**
+   * Custom-element tag names this render instantiated, so a host can re-mount what a redefinition
+   * touches.
+   */
+  readonly elements: ReadonlySet<string>;
+  /** Stops every effect, calls `onUnmount`, removes the root. Idempotent. */
+  readonly dispose: () => void;
+}
+
 export interface JxRenderOptions {
   _path?: JxPath;
+  /** The mount context this render belongs to; absent on the legacy direct-render path. */
+  _ctx?: JxContext;
+  /** Read by {@link Jx} only: aborting disposes the mount. */
+  signal?: AbortSignal;
   /**
    * Base URL the document's own references resolve against — `$ref`, `$elements`, `$head` and the
    * asset paths beneath them.
@@ -38,6 +104,12 @@ export interface JxRenderOptions {
     def: JxElement | string,
     state?: JxScope,
   ) => void;
+  /**
+   * Called when a keyed mapped-array row is reused at a new index. The node is the same one
+   * `onNodeCreated` reported; `path` is its new document path, so a host that stamped the old one
+   * can re-stamp it.
+   */
+  onNodeMoved?: (node: HTMLElement | Text, path: JxPath) => void;
 }
 
 export interface DynamicClass {