@jxsuite/runtime 1.0.0 → 1.2.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") {
@@ -921,14 +1030,25 @@ export function applyStyle(
     if (key === "@--") {
       continue;
     } // Base canvas width, not a real media query
-    const atRule = key.startsWith("@--")
-      ? `@media ${mediaQueries[key.slice(1)] ?? key.slice(1)}`
+    const query = key.startsWith("@--")
+      ? (mediaQueries[key.slice(1)] ?? key.slice(1))
       : key.startsWith("@(")
-        ? `@media ${key.slice(1)}`
-        : key;
+        ? key.slice(1)
+        : null;
+    const atRule = query === null ? key : `@media ${query}`;
     const scope = `[data-jx="${uid}"]`;
-    css += `${atRule} { ${scope} { ${toCSSText(rules)} } }\n`;
-    emitMediaNested(atRule, scope, rules);
+    const scheme = query === null ? null : pureSchemeOf(query);
+    if (scheme) {
+      // Dual-emit scheme rules: a media-guarded copy for auto plus a forced-attribute copy.
+      // The forced root attribute wins over the OS preference.
+      const { auto, forced } = schemeSelectors(scope, scheme);
+      css += `${atRule} { ${auto} { ${toCSSText(rules)} } }\n`;
+      emitMediaNested(atRule, auto, rules);
+      emitNested(forced, rules);
+    } else {
+      css += `${atRule} { ${scope} { ${toCSSText(rules)} } }\n`;
+      emitMediaNested(atRule, scope, rules);
+    }
   }
 
   const tag = document.createElement("style");
@@ -1974,6 +2094,64 @@ export function toCSSText(rules: Record<string, unknown> | object) {
     .join("; ");
 }
 
+// ─── Color Schemes ────────────────────────────────────────────────────────────
+
+/**
+ * Attribute on the root element (`<html>`) that forces a color scheme. Absent = auto (follow the OS
+ * `prefers-color-scheme`). Values: "light" | "dark".
+ *
+ * @docs framework/concepts/color-schemes
+ */
+export const COLOR_SCHEME_ATTR = "data-color-scheme";
+
+/**
+ * The localStorage key a site switcher persists the visitor's forced scheme under; read by the
+ * compiler-injected pre-paint script. Values: "light" | "dark" (absent = auto).
+ *
+ * @docs framework/concepts/color-schemes
+ */
+export const COLOR_SCHEME_STORAGE_KEY = "jx-color-scheme";
+
+/**
+ * The scheme a _pure_ `prefers-color-scheme` media query targets. Compound queries (any other
+ * conditions attached) return null — they are not eligible for forced-scheme dual emission.
+ *
+ * @param {string} query
+ * @returns {"light" | "dark" | null}
+ * @docs framework/concepts/color-schemes
+ */
+export function pureSchemeOf(query: string): "light" | "dark" | null {
+  const m = /^\(\s*prefers-color-scheme\s*:\s*(light|dark)\s*\)$/.exec(query.trim());
+  return (m?.[1] as "light" | "dark") ?? null;
+}
+
+/**
+ * Selector pair for a scheme-conditional rule: `auto` applies inside the scheme's media query only
+ * while no scheme is forced; `forced` applies unconditionally when the root attribute forces the
+ * scheme. Guards are wrapped in `:where()` so specificity matches the unguarded selector and source
+ * order decides the cascade.
+ *
+ * @param {string} selector
+ * @param {"light" | "dark"} scheme
+ * @returns {{ auto: string; forced: string }}
+ * @docs framework/concepts/color-schemes
+ */
+export function schemeSelectors(
+  selector: string,
+  scheme: "light" | "dark",
+): { auto: string; forced: string } {
+  if (selector === ":root" || selector === "html") {
+    return {
+      auto: `${selector}:where(:not([${COLOR_SCHEME_ATTR}]))`,
+      forced: `${selector}:where([${COLOR_SCHEME_ATTR}="${scheme}"])`,
+    };
+  }
+  return {
+    auto: `:where(:root:not([${COLOR_SCHEME_ATTR}])) ${selector}`,
+    forced: `:where(:root[${COLOR_SCHEME_ATTR}="${scheme}"]) ${selector}`,
+  };
+}
+
 // ─── Custom Element Registration ──────────────────────────────────────────────
 
 let _rootMedia: Record<string, string> = {};

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");
+}