@jxsuite/runtime 1.1.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/runtime",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "JSON-native reactive web component runtime",
   "license": "MIT",
   "repository": {
@@ -30,10 +30,10 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^1.1.0",
-    "@vue/reactivity": "^3.5.40"
+    "@jxsuite/schema": "^1.3.0",
+    "@vue/reactivity": "3.5.40"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.10.6"
+    "@happy-dom/global-registrator": "^20.11.0"
   }
 }

package/src/runtime.ts

@@ -26,6 +26,7 @@ import {
 import { evaluateExpression, isMutating } from "./expression.ts";
 import type { DynamicClass, JxEventHandler, JxPath, JxRenderOptions, JxScope } from "./types.ts";
 import {
+  bodyReturnsValue,
   hasStructuredBody,
   isExpressionDef,
   isFunctionDef,
@@ -35,6 +36,7 @@ import {
   isPrototypeDef,
   isRef as isRefValue,
   isServerFnDef,
+  isTemplateString,
   paramNames,
 } from "@jxsuite/schema/guards";
 import { runStatements } from "./statements.ts";
@@ -68,6 +70,29 @@ import type { Ref } from "@vue/reactivity";
  * @returns {Promise<JxScope>} Resolves with the live component scope (state reactive
  * proxy)
  */
+/** The document-schema version this runtime understands (the `/schema/vN` in a hosted `$schema`). */
+export const SUPPORTED_SCHEMA_VERSION = 1;
+let _schemaVersionWarned = false;
+
+/**
+ * Warn once when a document declares a hosted `$schema` whose version differs from the one this
+ * runtime supports. A relative or non-hosted `$schema` (local dev schema paths) is ignored. This is
+ * a diagnostic only — there is no document-format migration story yet (see spec §3.2 / §21.4).
+ */
+function checkSchemaVersion($schema: unknown): void {
+  if (_schemaVersionWarned || typeof $schema !== "string") {
+    return;
+  }
+  const match = $schema.match(/\/schema\/v(\d+)\b/);
+  if (match && Number(match[1]) !== SUPPORTED_SCHEMA_VERSION) {
+    _schemaVersionWarned = true;
+    console.warn(
+      `Jx: document $schema is version v${match[1]} but this runtime supports ` +
+        `v${SUPPORTED_SCHEMA_VERSION}. Behavior may be undefined; there is no format migrator yet.`,
+    );
+  }
+}
+
 export async function Jx(
   source: string | JxDocument,
   target: HTMLElement = document.body,
@@ -75,6 +100,7 @@ export async function Jx(
 ) {
   const base = typeof source === "string" ? new URL(source, location.href).href : location.href;
   const doc = await resolve(source);
+  checkSchemaVersion(doc.$schema);
 
   // Register custom elements declared in $elements (depth-first)
   if (doc.$elements) {
@@ -615,9 +641,9 @@ async function resolveFunction(def: JxFunctionDef, state: JxScope, key: string,
   let isComputed = false;
   if (!hasParams) {
     if (typeof def.body === "string") {
-      isComputed = /\breturn\b/.test(def.body);
+      isComputed = bodyReturnsValue(def.body);
     } else if (fn) {
-      isComputed = fn.length <= 1 && /\breturn\b/.test(fn.toString());
+      isComputed = fn.length <= 1 && bodyReturnsValue(fn.toString());
     }
   }
   if (isComputed) {
@@ -690,6 +716,9 @@ export const RESERVED_KEYS = new Set([
  * @param {JxRenderOptions} [options]
  * @returns {HTMLElement | Text}
  */
+/** Refs already warned about, so the §13 diagnostic fires once per distinct target. */
+const warnedRefChildren = new Set<string>();
+
 export function renderNode(
   def: JxElement | string | number | boolean,
   state: JxScope,
@@ -719,6 +748,22 @@ export function renderNode(
     }
   }
 
+  /*
+   * §13 diagnostic: a node-level external `$ref` (the withdrawn component-instance syntax) has no
+   * tagName and silently renders an empty <div>. Warn once per target instead of failing silently —
+   * the supported mechanism is $elements + a custom-element tag (see spec §13).
+   */
+  if ("$ref" in def && !def.tagName) {
+    const refTarget = String((def as { $ref?: unknown }).$ref ?? "");
+    if (!warnedRefChildren.has(refTarget)) {
+      warnedRefChildren.add(refTarget);
+      console.warn(
+        `Jx: a $ref child ("${refTarget}") is not a supported component instance; register the ` +
+          `component in $elements and use its custom-element tag instead (spec §13).`,
+      );
+    }
+  }
+
   // Custom element with $props: set JS properties on the element instance
   const tagName = def.tagName ?? "div";
   const isCustomEl = tagName.includes("-") && customElements.get(tagName);
@@ -780,10 +825,6 @@ export function renderNode(
  * @param {unknown} val
  * @returns {boolean}
  */
-function isTemplateString(val: unknown): val is string {
-  return typeof val === "string" && val.includes("${");
-}
-
 // ─── Property / style / attribute application ─────────────────────────────────
 
 /**
@@ -1030,14 +1071,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");
@@ -2083,6 +2135,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> = {};