@jxsuite/runtime 0.22.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/runtime",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "JSON-native reactive web component runtime",
   "license": "MIT",
   "repository": {
@@ -14,7 +14,8 @@
   ],
   "type": "module",
   "exports": {
-    ".": "./src/runtime.js"
+    ".": "./src/runtime.js",
+    "./expression": "./src/expression.js"
   },
   "publishConfig": {
     "provenance": true

package/src/expression.js

@@ -0,0 +1,469 @@
+/**
+ * Jx Declarative Expression Engine (spec §19)
+ *
+ * Shared module used by both runtime (evaluateExpression) and compiler (compileExpression).
+ *
+ * @module expression
+ */
+
+/** @typedef {{ operator: string; target: any; value?: any; initial?: any }} ExpressionNode */
+
+const MUTATING_OPS = new Set([
+  "=",
+  "+=",
+  "-=",
+  "*=",
+  "/=",
+  "push",
+  "pop",
+  "shift",
+  "unshift",
+  "splice",
+]);
+const UNARY_OPS = new Set(["!", "-"]);
+const BINARY_OPS = new Set([
+  "+",
+  "-",
+  "*",
+  "/",
+  "%",
+  "===",
+  "!==",
+  "<",
+  "<=",
+  ">",
+  ">=",
+  "&&",
+  "||",
+]);
+const ASSIGNMENT_OPS = new Set(["=", "+=", "-=", "*=", "/="]);
+const ARRAY_METHOD_OPS = new Set(["push", "pop", "shift", "unshift", "splice"]);
+const AGGREGATE_OPS = new Set(["reduce", "map", "filter"]);
+
+export const BLESSED_OPERATORS = new Set([
+  ...MUTATING_OPS,
+  ...UNARY_OPS,
+  ...BINARY_OPS,
+  ...AGGREGATE_OPS,
+]);
+
+/**
+ * @param {string} op
+ * @returns {boolean}
+ */
+export function isMutating(op) {
+  return MUTATING_OPS.has(op);
+}
+
+// ─── Runtime Evaluation ──────────────────────────────────────────────────────
+
+/**
+ * Resolve an operand to its runtime value.
+ *
+ * @param {any} operand
+ * @param {Record<string, any>} state
+ * @param {Event | null} event
+ * @param {{ acc?: any; item?: any; index?: number }} [iterCtx]
+ * @returns {any}
+ */
+function resolveOperand(operand, state, event, iterCtx) {
+  if (operand === null || operand === undefined) return operand;
+
+  // Nested expression node
+  if (typeof operand === "object" && !Array.isArray(operand) && "operator" in operand) {
+    return evaluateExpression(operand, state, event, iterCtx);
+  }
+
+  // $ref pointer
+  if (typeof operand === "object" && !Array.isArray(operand) && "$ref" in operand) {
+    return resolveExprRef(operand.$ref, state, event, iterCtx);
+  }
+
+  // Array of operands (e.g., splice args)
+  if (Array.isArray(operand)) {
+    return operand.map((o) => resolveOperand(o, state, event, iterCtx));
+  }
+
+  // Literal
+  return operand;
+}
+
+/**
+ * Resolve a $ref string within expression context. Handles event#/, $reduce/acc, $map/, #/state/,
+ * and other schemes.
+ *
+ * @param {string} ref
+ * @param {Record<string, any>} state
+ * @param {Event | null} event
+ * @param {{ acc?: any; item?: any; index?: number }} [iterCtx]
+ * @returns {any}
+ */
+function resolveExprRef(ref, state, event, iterCtx) {
+  if (ref === "$reduce/acc") {
+    return iterCtx?.acc;
+  }
+  if (ref.startsWith("$reduce/")) {
+    return iterCtx?.acc;
+  }
+  if (ref.startsWith("event#/")) {
+    const path = ref.slice("event#/".length);
+    return getPath(event, path);
+  }
+  if (ref.startsWith("$map/")) {
+    const parts = ref.split("/");
+    const key = parts[1];
+    let base;
+    if (key === "item") base = iterCtx?.item ?? state.$map?.item ?? state["$map/item"];
+    else if (key === "index") base = iterCtx?.index ?? state.$map?.index ?? state["$map/index"];
+    else base = state.$map?.[key] ?? state["$map/" + key];
+    return parts.length > 2 ? getPath(base, parts.slice(2).join("/")) : base;
+  }
+  if (ref.startsWith("#/state/")) {
+    const sub = ref.slice("#/state/".length);
+    const slash = sub.indexOf("/");
+    if (slash < 0) return state[sub];
+    return getPath(state[sub.slice(0, slash)], sub.slice(slash + 1));
+  }
+  if (ref.startsWith("parent#/")) return state[ref.slice("parent#/".length)];
+  if (ref.startsWith("window#/")) return getPath(globalThis.window, ref.slice("window#/".length));
+  if (ref.startsWith("document#/"))
+    return getPath(globalThis.document, ref.slice("document#/".length));
+  return state[ref] ?? null;
+}
+
+/**
+ * Resolve a $ref to a writable location — returns { obj, key } for assignment.
+ *
+ * @param {string} ref
+ * @param {Record<string, any>} state
+ * @param {Event | null} event
+ * @param {{ acc?: any; item?: any; index?: number }} [iterCtx]
+ * @returns {{ obj: any; key: string }}
+ */
+function resolveWritableRef(ref, state, event, iterCtx) {
+  if (ref.startsWith("$map/")) {
+    const parts = ref.split("/");
+    const key = parts[1];
+    let base;
+    if (key === "item") base = iterCtx?.item ?? state.$map?.item ?? state["$map/item"];
+    else if (key === "index") base = iterCtx?.index ?? state.$map?.index ?? state["$map/index"];
+    else base = state.$map?.[key] ?? state["$map/" + key];
+    if (parts.length > 2) {
+      const pathParts = parts.slice(2);
+      const lastKey = pathParts.pop();
+      const obj = pathParts.length > 0 ? getPath(base, pathParts.join("/")) : base;
+      return { obj, key: /** @type {string} */ (lastKey) };
+    }
+    return { obj: state.$map ?? state, key: key === "item" ? "$map/item" : "$map/index" };
+  }
+  if (ref.startsWith("#/state/")) {
+    const sub = ref.slice("#/state/".length);
+    const slash = sub.indexOf("/");
+    if (slash < 0) return { obj: state, key: sub };
+    const parts = sub.split("/");
+    const lastKey = parts.pop();
+    let obj = state;
+    for (const p of parts) obj = obj[p];
+    return { obj, key: /** @type {string} */ (lastKey) };
+  }
+  return { obj: state, key: ref };
+}
+
+/**
+ * Evaluate an expression node at runtime.
+ *
+ * @param {ExpressionNode} node
+ * @param {Record<string, any>} state
+ * @param {Event | null} event
+ * @param {{ acc?: any; item?: any; index?: number }} [iterCtx]
+ * @returns {any}
+ */
+export function evaluateExpression(node, state, event, iterCtx) {
+  const { operator, target, value, initial } = node;
+
+  if (!BLESSED_OPERATORS.has(operator)) {
+    throw new Error(`$expression: unknown operator "${operator}"`);
+  }
+
+  // ─── Unary ───
+  if (UNARY_OPS.has(operator) && !("value" in node)) {
+    const operand = resolveOperand(target, state, event, iterCtx);
+    if (operator === "!") return !operand;
+    if (operator === "-") return -operand;
+  }
+
+  // ─── Binary (pure) ───
+  if (BINARY_OPS.has(operator)) {
+    const left = resolveOperand(target, state, event, iterCtx);
+    const right = resolveOperand(value, state, event, iterCtx);
+    switch (operator) {
+      case "+":
+        return left + right;
+      case "-":
+        return left - right;
+      case "*":
+        return left * right;
+      case "/":
+        return left / right;
+      case "%":
+        return left % right;
+      case "===":
+        return left === right;
+      case "!==":
+        return left !== right;
+      case "<":
+        return left < right;
+      case "<=":
+        return left <= right;
+      case ">":
+        return left > right;
+      case ">=":
+        return left >= right;
+      case "&&":
+        return left && right;
+      case "||":
+        return left || right;
+    }
+  }
+
+  // ─── Assignment ───
+  if (ASSIGNMENT_OPS.has(operator)) {
+    const rhs = resolveOperand(value, state, event, iterCtx);
+    const { obj, key } = resolveWritableRef(target.$ref, state, event, iterCtx);
+    switch (operator) {
+      case "=":
+        obj[key] = rhs;
+        break;
+      case "+=":
+        obj[key] += rhs;
+        break;
+      case "-=":
+        obj[key] -= rhs;
+        break;
+      case "*=":
+        obj[key] *= rhs;
+        break;
+      case "/=":
+        obj[key] /= rhs;
+        break;
+    }
+    return;
+  }
+
+  // ─── Array methods ───
+  if (ARRAY_METHOD_OPS.has(operator)) {
+    const arr = resolveOperand(target, state, event, iterCtx);
+    switch (operator) {
+      case "push":
+        return arr.push(resolveOperand(value, state, event, iterCtx));
+      case "unshift":
+        return arr.unshift(resolveOperand(value, state, event, iterCtx));
+      case "pop":
+        return arr.pop();
+      case "shift":
+        return arr.shift();
+      case "splice": {
+        const args = resolveOperand(value, state, event, iterCtx);
+        return arr.splice(...args);
+      }
+    }
+  }
+
+  // ─── Aggregates (pure) ───
+  if (AGGREGATE_OPS.has(operator)) {
+    const arr = resolveOperand(target, state, event, iterCtx);
+    if (operator === "reduce") {
+      const seed = resolveOperand(initial, state, event, iterCtx);
+      return arr.reduce(
+        (/** @type {any} */ acc, /** @type {any} */ item, /** @type {number} */ index) => {
+          return evaluateExpression(value, state, event, { acc, item, index });
+        },
+        seed,
+      );
+    }
+    if (operator === "map") {
+      return arr.map((/** @type {any} */ item, /** @type {number} */ index) => {
+        return evaluateExpression(value, state, event, { ...iterCtx, item, index });
+      });
+    }
+    if (operator === "filter") {
+      return arr.filter((/** @type {any} */ item, /** @type {number} */ index) => {
+        return evaluateExpression(value, state, event, { ...iterCtx, item, index });
+      });
+    }
+  }
+}
+
+// ─── Compiler: Expression → JS Source ────────────────────────────────────────
+
+/** @typedef {{ statePrefix?: string; eventParam?: string }} CompileOpts */
+
+/**
+ * Compile an operand to a JS source string.
+ *
+ * @param {any} operand
+ * @param {CompileOpts} opts
+ * @returns {string}
+ */
+function compileOperand(operand, opts) {
+  if (operand === null) return "null";
+  if (operand === undefined) return "undefined";
+
+  // Nested expression node
+  if (typeof operand === "object" && !Array.isArray(operand) && "operator" in operand) {
+    return compileExpression(operand, opts);
+  }
+
+  // $ref pointer
+  if (typeof operand === "object" && !Array.isArray(operand) && "$ref" in operand) {
+    return compileRef(operand.$ref, opts);
+  }
+
+  // Array of operands
+  if (Array.isArray(operand)) {
+    return operand.map((o) => compileOperand(o, opts)).join(", ");
+  }
+
+  // Literal
+  return JSON.stringify(operand);
+}
+
+/**
+ * Compile a $ref to its JS equivalent.
+ *
+ * @param {string} ref
+ * @param {CompileOpts} opts
+ * @returns {string}
+ */
+function compileRef(ref, opts) {
+  const s = opts.statePrefix ?? "state";
+  const e = opts.eventParam ?? "event";
+
+  if (ref === "$reduce/acc") return "_acc";
+  if (ref.startsWith("$reduce/")) return "_acc";
+
+  if (ref.startsWith("event#/")) {
+    const path = ref.slice("event#/".length);
+    return `${e}.${path.replace(/\//g, ".")}`;
+  }
+
+  if (ref.startsWith("$map/")) {
+    const parts = ref.split("/");
+    const key = parts[1];
+    if (key === "item") {
+      return parts.length > 2 ? `_item.${parts.slice(2).join(".")}` : "_item";
+    }
+    if (key === "index") return "_index";
+    return `_${key}`;
+  }
+
+  if (ref.startsWith("#/state/")) {
+    const path = ref.slice("#/state/".length);
+    return `${s}.${path.replace(/\//g, ".")}`;
+  }
+
+  if (ref.startsWith("parent#/")) return `${s}.${ref.slice("parent#/".length)}`;
+  if (ref.startsWith("window#/"))
+    return `window.${ref.slice("window#/".length).replace(/\//g, ".")}`;
+  if (ref.startsWith("document#/"))
+    return `document.${ref.slice("document#/".length).replace(/\//g, ".")}`;
+
+  return `${s}.${ref}`;
+}
+
+/**
+ * Compile a writable $ref target to its JS equivalent (for LHS of assignment).
+ *
+ * @param {any} target
+ * @param {CompileOpts} opts
+ * @returns {string}
+ */
+function compileTarget(target, opts) {
+  if (typeof target === "object" && "$ref" in target) {
+    return compileRef(target.$ref, opts);
+  }
+  return compileOperand(target, opts);
+}
+
+/**
+ * Compile an expression node to a JS source string. Returns a statement for mutating ops, a value
+ * expression for pure ops.
+ *
+ * @param {ExpressionNode} node
+ * @param {CompileOpts} [opts]
+ * @returns {string}
+ */
+export function compileExpression(node, opts = {}) {
+  const { operator, target, value, initial } = node;
+
+  // ─── Unary ───
+  if (UNARY_OPS.has(operator) && !("value" in node)) {
+    const operand = compileOperand(target, opts);
+    if (operator === "!") return `!(${operand})`;
+    if (operator === "-") return `-(${operand})`;
+  }
+
+  // ─── Binary (pure) ───
+  if (BINARY_OPS.has(operator)) {
+    const left = compileOperand(target, opts);
+    const right = compileOperand(value, opts);
+    return `(${left} ${operator} ${right})`;
+  }
+
+  // ─── Assignment ───
+  if (ASSIGNMENT_OPS.has(operator)) {
+    const lhs = compileTarget(target, opts);
+    const rhs = compileOperand(value, opts);
+    return `${lhs} ${operator} ${rhs}`;
+  }
+
+  // ─── Array methods ───
+  if (ARRAY_METHOD_OPS.has(operator)) {
+    const arr = compileTarget(target, opts);
+    switch (operator) {
+      case "push":
+        return `${arr}.push(${compileOperand(value, opts)})`;
+      case "unshift":
+        return `${arr}.unshift(${compileOperand(value, opts)})`;
+      case "pop":
+        return `${arr}.pop()`;
+      case "shift":
+        return `${arr}.shift()`;
+      case "splice": {
+        const args = Array.isArray(value)
+          ? value.map((o) => compileOperand(o, opts)).join(", ")
+          : compileOperand(value, opts);
+        return `${arr}.splice(${args})`;
+      }
+    }
+  }
+
+  // ─── Aggregates (pure) ───
+  if (AGGREGATE_OPS.has(operator)) {
+    const arr = compileOperand(target, opts);
+    const itemExpr = compileExpression(value, opts);
+    if (operator === "reduce") {
+      const seed = compileOperand(initial, opts);
+      return `${arr}.reduce((_acc, _item, _index) => ${itemExpr}, ${seed})`;
+    }
+    if (operator === "map") {
+      return `${arr}.map((_item, _index) => ${itemExpr})`;
+    }
+    if (operator === "filter") {
+      return `${arr}.filter((_item, _index) => ${itemExpr})`;
+    }
+  }
+
+  return "undefined";
+}
+
+// ─── Utilities ───────────────────────────────────────────────────────────────
+
+/**
+ * @param {any} obj
+ * @param {string} path
+ * @returns {any}
+ */
+function getPath(obj, path) {
+  return path.split(/[./]/).reduce((o, k) => /** @type {any} */ (o)?.[k], obj);
+}

package/src/runtime.js

@@ -13,6 +13,7 @@
  */
 
 import { reactive, ref, computed, effect, isRef, onEffectCleanup } from "@vue/reactivity";
+import { evaluateExpression, isMutating } from "./expression.js";
 
 // ─── Public API ───────────────────────────────────────────────────────────────
 
@@ -43,6 +44,10 @@ export async function Jx(source, target = document.body, options) {
     injectHead(doc.$head, base);
   }
 
+  if (doc.$media) {
+    _rootMedia = doc.$media;
+  }
+
   const state = await buildScope(doc, {}, base);
   target.appendChild(renderNode(doc, state, options));
   if (typeof state.onMount === "function") state.onMount(state);
@@ -157,6 +162,7 @@ export async function buildScope(doc, parentScope = {}, base = location.href) {
     // 4. Object
     if (typeof def === "object") {
       if (def.$prototype) continue; // handled in later passes
+      if ("$expression" in def) continue; // handled in pass 2.5
       if (def.timing === "server" && def.$src && def.$export) continue; // handled in fifth pass
       if ("default" in def) {
         raw[key] = def.default;
@@ -177,6 +183,19 @@ export async function buildScope(doc, parentScope = {}, base = location.href) {
     }
   }
 
+  // Pass 2.5: $expression entries (Shape 5)
+  for (const [key, def] of Object.entries(defs)) {
+    if (def && typeof def === "object" && !Array.isArray(def) && "$expression" in def) {
+      const node = /** @type {any} */ (def).$expression;
+      if (isMutating(node.operator)) {
+        state[key] = (/** @type {any} */ s, /** @type {any} */ event) =>
+          evaluateExpression(node, s, event);
+      } else {
+        state[key] = computed(() => evaluateExpression(node, state, null));
+      }
+    }
+  }
+
   // Third pass: $prototype: "Function" entries
   for (const [key, def] of Object.entries(defs)) {
     if (typeof def === "object" && def?.$prototype === "Function") {
@@ -209,6 +228,8 @@ export async function buildScope(doc, parentScope = {}, base = location.href) {
 
   if (doc.$media) {
     state["$media"] = doc.$media;
+  } else if (!state["$media"] && Object.keys(_rootMedia).length > 0) {
+    state["$media"] = _rootMedia;
   }
 
   return state;
@@ -489,6 +510,13 @@ function applyProperties(el, def, state) {
         el.addEventListener(key.slice(2), (e) => fn(scope, e));
         continue;
       }
+      // Event handler: inline $expression
+      if (val && typeof val === "object" && "$expression" in val) {
+        const node = /** @type {any} */ (val).$expression;
+        const scope = state;
+        el.addEventListener(key.slice(2), (e) => evaluateExpression(node, scope, e));
+        continue;
+      }
     }
 
     bindProperty(el, key, val, state);
@@ -542,6 +570,27 @@ export function applyStyle(el, styleDef, mediaQueries = {}, state = {}) {
   const nested = {};
   /** @type {Record<string, any>} */
   const media = {};
+  /** @type {Record<string, string>} */
+  const baseDecls = {};
+
+  // Collect properties overridden by media queries so we can avoid inline styles for them
+  /** @type {Set<string>} */
+  const mediaOverriddenProps = new Set();
+  for (const [prop, val] of Object.entries(styleDef)) {
+    if (prop.startsWith("@") && val && typeof val === "object") {
+      for (const k of Object.keys(val)) {
+        if (
+          !k.startsWith(":") &&
+          !k.startsWith(".") &&
+          !k.startsWith("&") &&
+          !k.startsWith("[") &&
+          !k.startsWith("@")
+        ) {
+          mediaOverriddenProps.add(k);
+        }
+      }
+    }
+  }
 
   for (const [prop, val] of Object.entries(styleDef)) {
     if (prop.startsWith("@")) media[prop] = val;
@@ -558,17 +607,21 @@ export function applyStyle(el, styleDef, mediaQueries = {}, state = {}) {
         /** @type {Record<string, string>} */ (/** @type {unknown} */ (el.style))[prop] =
           evaluateTemplate(val, state);
       });
+    else if (mediaOverriddenProps.has(prop)) baseDecls[prop] = val;
     else /** @type {Record<string, string>} */ (/** @type {unknown} */ (el.style))[prop] = val;
   }
 
   const hasNested = Object.keys(nested).length > 0;
   const hasMedia = Object.keys(media).length > 0;
-  if (!hasNested && !hasMedia) return;
+  const hasBaseDecls = Object.keys(baseDecls).length > 0;
+  if (!hasNested && !hasMedia && !hasBaseDecls) return;
 
   const uid = `jx-${Math.random().toString(36).slice(2, 7)}`;
   el.dataset.jx = uid;
 
   let css = "";
+  const baseCSS = toCSSText(baseDecls);
+  if (baseCSS) css += `[data-jx="${uid}"] { ${baseCSS} }\n`;
 
   function emitNested(/** @type {string} */ scope, /** @type {Record<string, any>} */ rules) {
     const props = toCSSText(rules);
@@ -600,11 +653,13 @@ export function applyStyle(el, styleDef, mediaQueries = {}, state = {}) {
 
   for (const [key, rules] of Object.entries(media)) {
     if (key === "@--") continue; // base canvas width, not a real media query
-    const query = key.startsWith("@--")
-      ? (mediaQueries[key.slice(1)] ?? key.slice(1))
-      : key.slice(1);
+    const atRule = key.startsWith("@--")
+      ? `@media ${mediaQueries[key.slice(1)] ?? key.slice(1)}`
+      : key.startsWith("@(")
+        ? `@media ${key.slice(1)}`
+        : key;
     const scope = `[data-jx="${uid}"]`;
-    css += `@media ${query} { ${scope} { ${toCSSText(rules)} } }\n`;
+    css += `${atRule} { ${scope} { ${toCSSText(rules)} } }\n`;
 
     function emitMediaNested(
       /** @type {string} */ parentSel,
@@ -621,7 +676,7 @@ export function applyStyle(el, styleDef, mediaQueries = {}, state = {}) {
               ? `${parentSel}${sel}`
               : `${parentSel} ${sel}`;
         const props = toCSSText(sub);
-        if (props) css += `@media ${query} { ${resolved} { ${props} } }\n`;
+        if (props) css += `${atRule} { ${resolved} { ${props} } }\n`;
         emitMediaNested(resolved, sub);
       }
     }
@@ -667,8 +722,7 @@ function renderMappedArray(def, state, options) {
   applyProperties(container, def, state);
   applyStyle(container, def.style ?? {}, state["$media"] ?? {}, state);
   applyAttributes(container, def.attributes ?? {}, state);
-  const { items: _items, of: _of, map: mapDef, filter: filterRef, sort: sortRef } = def.children;
-  const itemsSrc = _items ?? _of;
+  const { items: itemsSrc, map: mapDef, filter: filterRef, sort: sortRef } = def.children;
 
   effect(() => {
     container.innerHTML = "";
@@ -1562,6 +1616,7 @@ export function toCSSText(rules) {
 
 // ─── Custom Element Registration ──────────────────────────────────────────────
 
+let _rootMedia = {};
 const _elementDefs = new Map();
 
 /**