@jxsuite/runtime 1.0.0 → 1.1.0

package/src/runtime.ts

@@ -21,19 +21,23 @@ import {
   onEffectCleanup,
   reactive,
   ref,
+  toRaw,
 } from "@vue/reactivity";
 import { evaluateExpression, isMutating } from "./expression.ts";
 import type { DynamicClass, JxEventHandler, JxPath, JxRenderOptions, JxScope } from "./types.ts";
 import {
+  hasStructuredBody,
   isExpressionDef,
   isFunctionDef,
   isJsonObject,
   isMappedArray,
+  isNamedFormulaDef,
   isPrototypeDef,
   isRef as isRefValue,
   isServerFnDef,
   paramNames,
 } from "@jxsuite/schema/guards";
+import { runStatements } from "./statements.ts";
 import type {
   JxAttributeValue,
   JxClassDef,
@@ -259,6 +263,55 @@ function canvasAttrName(el: HTMLElement, key: string): string {
   return key;
 }
 
+/**
+ * Studio-canvas prop-binding markers. When on, `bindProperty` stamps `data-jx-bound-prop="<key>"`
+ * on elements whose `textContent` is an invertible single-key state binding — the pure template
+ * `"${state.key}"` or `{ "$ref": "#/state/key" }`. The studio canvas uses the marker to offer
+ * inline editing of component-instance prop values; the rendered text must BE the prop value
+ * verbatim, so mixed templates and deep paths are never stamped. Off (the default) leaves
+ * production rendering untouched; the studio sets it for design/edit (not preview — see
+ * iframe-render).
+ */
+let _stampPropBindings = false;
+export function setStampPropBindings(on: boolean) {
+  _stampPropBindings = on;
+}
+
+/** The single invertible template form: the whole string is exactly one `${state.key}` access. */
+const PURE_STATE_TEMPLATE = /^\s*\$\{\s*state\.(\w+)\s*\}\s*$/;
+
+/** The state key of an invertible `textContent` binding, or null (mixed template, deep path). */
+function boundPropKey(key: string, val: unknown, state: JxScope): string | null {
+  if (!_stampPropBindings || key !== "textContent") {
+    return null;
+  }
+  let sub: string | null = null;
+  if (isRefObj(val)) {
+    if (!val.$ref.startsWith("#/state/")) {
+      return null;
+    }
+    const rest = val.$ref.slice("#/state/".length);
+    sub = rest && !rest.includes("/") ? rest : null;
+  } else if (typeof val === "string") {
+    sub = PURE_STATE_TEMPLATE.exec(val)?.[1] ?? null;
+  }
+  if (!sub) {
+    return null;
+  }
+  // Only plain writable data entries are per-instance props. Computed/signal entries live as refs
+  // In the raw scope (auto-unwrapped by the reactive proxy), and function/object entries (handlers,
+  // $prototype instances) are not prop-overridable either — an instance $props write against any of
+  // Them would clobber the definition's behavior, so their bindings are never marked editable.
+  const stored = (toRaw(state) as Record<string, unknown>)[sub];
+  if (isRef(stored) || typeof stored === "function") {
+    return null;
+  }
+  if (typeof stored === "object" && stored !== null) {
+    return null;
+  }
+  return sub;
+}
+
 /**
  * Build the reactive scope (state) from the document using the five-shape detection algorithm.
  *
@@ -356,7 +409,24 @@ export async function buildScope(
   for (const [key, def] of Object.entries(defs)) {
     if (isExpressionDef(def)) {
       const node = def.$expression;
-      if (isMutating(node.operator)) {
+      if (isNamedFormulaDef(def)) {
+        // A named formula: callable with positional args mapped onto its declared parameters.
+        const params = def.parameters as (string | { name?: string; default?: unknown })[];
+        state[key] = (...argValues: unknown[]) => {
+          const args: Record<string, unknown> = {};
+          for (const [i, p] of params.entries()) {
+            const name = typeof p === "string" ? p : (p?.name ?? "");
+            if (!name) {
+              continue;
+            }
+            args[name] =
+              argValues[i] === undefined && typeof p === "object" && p !== null && "default" in p
+                ? p.default
+                : argValues[i];
+          }
+          return evaluateExpression(node, state, null, { args });
+        };
+      } else if (isMutating(node.operator)) {
         const handler: JxEventHandler = (s, event) => evaluateExpression(node, s, event);
         state[key] = handler;
       } else {
@@ -367,7 +437,33 @@ export async function buildScope(
 
   // Third pass: $prototype: "Function" entries
   for (const [key, def] of Object.entries(defs)) {
-    if (isFunctionDef(def)) {
+    if (hasStructuredBody(def)) {
+      // Structured body (spec §20): with parameters → a callable mapping positional args onto
+      // $args names (invoked via the call operator); without → an event handler.
+      const { body } = def;
+      if (Array.isArray(def.parameters) && def.parameters.length > 0) {
+        const params = def.parameters as (string | { name?: string; default?: unknown })[];
+        state[key] = (...argValues: unknown[]) => {
+          const args: Record<string, unknown> = {};
+          for (const [i, p] of params.entries()) {
+            const name = typeof p === "string" ? p : (p?.name ?? "");
+            if (!name) {
+              continue;
+            }
+            args[name] =
+              argValues[i] === undefined && typeof p === "object" && p !== null && "default" in p
+                ? p.default
+                : argValues[i];
+          }
+          return runStatements(body, state, null, { args });
+        };
+      } else {
+        const handler: JxEventHandler = (s, event) => {
+          void runStatements(body, s, event ?? null);
+        };
+        state[key] = handler;
+      }
+    } else if (isFunctionDef(def)) {
       state[key] = await resolveFunction(def, state, key, base);
     }
   }
@@ -476,7 +572,7 @@ async function resolveFunction(def: JxFunctionDef, state: JxScope, key: string,
 
   let fn: ((...args: unknown[]) => unknown) | undefined;
 
-  if (def.body) {
+  if (typeof def.body === "string") {
     const params = resolveParamNames(def);
     fn = new Function(...params, def.body) as (...args: unknown[]) => unknown;
     Object.defineProperty(fn, "name", {
@@ -518,7 +614,7 @@ async function resolveFunction(def: JxFunctionDef, state: JxScope, key: string,
   const hasParams = (def.parameters ?? def.arguments ?? []).length > 0;
   let isComputed = false;
   if (!hasParams) {
-    if (def.body) {
+    if (typeof def.body === "string") {
       isComputed = /\breturn\b/.test(def.body);
     } else if (fn) {
       isComputed = fn.length <= 1 && /\breturn\b/.test(fn.toString());
@@ -715,8 +811,17 @@ function applyProperties(el: HTMLElement, def: JxElement, state: JxScope) {
         }
         continue;
       }
+      // Event handler: inline $prototype: "Function" with a structured body (spec §20)
+      if (hasStructuredBody(val)) {
+        const { body } = val;
+        const scope = state;
+        el.addEventListener(key.slice(2), (e) => {
+          void runStatements(body, scope, e);
+        });
+        continue;
+      }
       // Event handler: inline $prototype: "Function"
-      if (isFunctionDef(val) && val.body) {
+      if (isFunctionDef(val) && typeof val.body === "string") {
         const params = resolveParamNames(val);
         const fn = new Function(...params, val.body) as (s: JxScope, e: Event) => unknown;
         const scope = state;
@@ -744,6 +849,10 @@ function applyProperties(el: HTMLElement, def: JxElement, state: JxScope) {
  */
 function bindProperty(el: HTMLElement, key: string, val: unknown, state: JxScope) {
   const target = el as unknown as Record<string, unknown>;
+  const boundProp = boundPropKey(key, val, state);
+  if (boundProp) {
+    el.dataset.jxBoundProp = boundProp;
+  }
   if (isRefObj(val)) {
     const refVal = val as { $ref: string };
     if (key === "id") {

package/src/statements.ts

@@ -0,0 +1,212 @@
+/// <reference lib="dom" />
+/**
+ * Jx Statement Engine (spec §20) — structured function bodies.
+ *
+ * A Function entry's `body` may be a statement array instead of opaque JS source. This module is
+ * the statements counterpart to expression.ts, with the same dual shape: `runStatements`
+ * (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.
+ */
+
+import {
+  compileExpression,
+  compileOperandSource,
+  evaluateExpression,
+  evaluateOperand,
+} from "./expression.ts";
+
+import type { JxStatement } from "@jxsuite/schema/types";
+import type { CompileOpts, ExpressionNode, IterCtx } from "./expression.ts";
+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;
+}
+
+function statementKind(statement: JxStatement): "expression" | "if" | "switch" | "dispatch" {
+  if ("operator" in statement) {
+    return "expression";
+  }
+  if ("if" in statement) {
+    return "if";
+  }
+  if ("$switch" in statement) {
+    return "switch";
+  }
+  return "dispatch";
+}
+
+/**
+ * Execute a statement list sequentially against the reactive scope. A statement whose value is a
+ * thenable is awaited before the next runs (ECMA async/await semantics); purely synchronous bodies
+ * complete synchronously before the returned promise settles.
+ */
+export async function runStatements(
+  statements: JxStatement[],
+  state: JxScope,
+  event: Event | null,
+  opts: RunOpts = {},
+): Promise<void> {
+  const iterCtx: IterCtx | undefined = opts.args ? { args: opts.args } : undefined;
+  for (const statement of statements) {
+    switch (statementKind(statement)) {
+      case "expression": {
+        const result = evaluateExpression(statement as ExpressionNode, state, event, iterCtx);
+        if (result && typeof (result as PromiseLike<unknown>).then === "function") {
+          await (result as PromiseLike<unknown>);
+        }
+        break;
+      }
+      case "if": {
+        const branch = statement as { if: unknown; then: JxStatement[]; else?: JxStatement[] };
+        const taken = evaluateOperand(branch.if, state, event, iterCtx) ? branch.then : branch.else;
+        if (Array.isArray(taken)) {
+          await runStatements(taken, state, event, opts);
+        }
+        break;
+      }
+      case "switch": {
+        const branch = statement as {
+          $switch: unknown;
+          cases: Record<string, JxStatement[]>;
+          default?: JxStatement[];
+        };
+        const key = String(evaluateOperand(branch.$switch, state, event, iterCtx));
+        const cases = branch.cases ?? {};
+        const taken = Object.hasOwn(cases, key) ? cases[key] : branch.default;
+        if (Array.isArray(taken)) {
+          await runStatements(taken, state, event, opts);
+        }
+        break;
+      }
+      case "dispatch": {
+        const dispatch = statement as {
+          dispatchEvent: string;
+          detail?: unknown;
+          bubbles?: boolean;
+          composed?: boolean;
+        };
+        const target = opts.target ?? event?.currentTarget;
+        if (!target) {
+          break;
+        }
+        const init: CustomEventInit = {};
+        if ("detail" in dispatch) {
+          init.detail = evaluateOperand(dispatch.detail, state, event, iterCtx);
+        }
+        if (dispatch.bubbles !== undefined) {
+          init.bubbles = dispatch.bubbles;
+        }
+        if (dispatch.composed !== undefined) {
+          init.composed = dispatch.composed;
+        }
+        target.dispatchEvent(new CustomEvent(dispatch.dispatchEvent, init));
+        break;
+      }
+      default: {
+        break;
+      }
+    }
+  }
+}
+
+interface StatementCompileOpts extends CompileOpts {
+  /** JS expression for the dispatchEvent target; defaults to `(event && event.currentTarget)`. */
+  dispatchTarget?: string;
+  /** Indentation prefix for emitted lines. */
+  indent?: string;
+}
+
+/**
+ * Compile a statement list to a JS statement block (no surrounding braces). Mirrors `runStatements`
+ * exactly; each statement kind lowers to its genuine ECMAScript form — expression statements,
+ * `if`/`else`, `switch` over the discriminant's string form, and `dispatchEvent(new
+ * CustomEvent(...))`.
+ */
+export function compileStatements(
+  statements: JxStatement[],
+  opts: StatementCompileOpts = {},
+): string {
+  const indent = opts.indent ?? "";
+  const lines: string[] = [];
+  for (const statement of statements) {
+    switch (statementKind(statement)) {
+      case "expression": {
+        lines.push(`${indent}${compileExpression(statement as ExpressionNode, opts)};`);
+        break;
+      }
+      case "if": {
+        const branch = statement as { if: unknown; then: JxStatement[]; else?: JxStatement[] };
+        const test = compileOperandSource(branch.if, opts);
+        const inner = { ...opts, indent: `${indent}  ` };
+        lines.push(`${indent}if (${test}) {`, compileStatements(branch.then ?? [], inner));
+        if (branch.else) {
+          lines.push(`${indent}} else {`, compileStatements(branch.else, inner));
+        }
+        lines.push(`${indent}}`);
+        break;
+      }
+      case "switch": {
+        const branch = statement as {
+          $switch: unknown;
+          cases: Record<string, JxStatement[]>;
+          default?: JxStatement[];
+        };
+        const disc = compileOperandSource(branch.$switch, opts);
+        const inner = { ...opts, indent: `${indent}    ` };
+        lines.push(`${indent}switch (String(${disc})) {`);
+        for (const [key, caseStatements] of Object.entries(branch.cases ?? {})) {
+          lines.push(
+            `${indent}  case ${JSON.stringify(key)}: {`,
+            compileStatements(caseStatements, inner),
+            `${indent}    break;`,
+            `${indent}  }`,
+          );
+        }
+        if (branch.default) {
+          lines.push(
+            `${indent}  default: {`,
+            compileStatements(branch.default, inner),
+            `${indent}  }`,
+          );
+        }
+        lines.push(`${indent}}`);
+        break;
+      }
+      case "dispatch": {
+        const dispatch = statement as {
+          dispatchEvent: string;
+          detail?: unknown;
+          bubbles?: boolean;
+          composed?: boolean;
+        };
+        const eventName = opts.eventParam ?? "event";
+        const target = opts.dispatchTarget ?? `(${eventName} && ${eventName}.currentTarget)`;
+        const init: string[] = [];
+        if ("detail" in dispatch) {
+          init.push(`detail: ${compileOperandSource(dispatch.detail, opts)}`);
+        }
+        if (dispatch.bubbles !== undefined) {
+          init.push(`bubbles: ${JSON.stringify(dispatch.bubbles)}`);
+        }
+        if (dispatch.composed !== undefined) {
+          init.push(`composed: ${JSON.stringify(dispatch.composed)}`);
+        }
+        const initSource = init.length > 0 ? `, { ${init.join(", ")} }` : "";
+        lines.push(
+          `${indent}${target}?.dispatchEvent(new CustomEvent(${JSON.stringify(dispatch.dispatchEvent)}${initSource}));`,
+        );
+        break;
+      }
+      default: {
+        break;
+      }
+    }
+  }
+  return lines.join("\n");
+}