@jxsuite/runtime 2.1.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/runtime",
-  "version": "2.1.0",
+  "version": "3.1.0",
   "description": "JSON-native reactive web component runtime",
   "license": "MIT",
   "repository": {
@@ -15,10 +15,12 @@
   "type": "module",
   "exports": {
     ".": "./src/runtime.ts",
+    "./css": "./src/css.ts",
     "./expression": "./src/expression.ts",
     "./pointer": "./src/pointer.ts",
     "./statements": "./src/statements.ts",
-    "./types": "./src/types.ts"
+    "./types": "./src/types.ts",
+    "./dist/runtime.js": "./dist/runtime.js"
   },
   "publishConfig": {
     "provenance": true
@@ -28,13 +30,13 @@
     "build:metafile": "bun build ./src/runtime.ts --outdir dist --target browser --sourcemap=linked --metafile=metafile.json",
     "test": "bun test --isolate",
     "test:coverage": "bun test --isolate --coverage",
-    "upgrade": "bunx npm-check-updates -u && bun install"
+    "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^1.9.0",
-    "@vue/reactivity": "3.5.41"
+    "@jxsuite/schema": "^2.1.0",
+    "@vue/reactivity": "3.5.42"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.6"
+    "@happy-dom/global-registrator": "^20.12.0"
   }
 }

package/src/css.ts

@@ -0,0 +1,119 @@
+/**
+ * The CSS-authoring rules that are not the DOM.
+ *
+ * `@jxsuite/runtime` renders a document in a browser, and every consumer of its root export pays
+ * for that: the element registry, the reactive scope, `@vue/reactivity`. These six exports need
+ * none of it. They are pure string and regex math over what a `style` block MEANS — how a property
+ * name is spelled in CSS, which media query an `@`-key resolves to, and which selector pair a
+ * scheme-conditional rule dual-emits as.
+ *
+ * They are a subpath of their own because of who else needs them. `@jxsuite/site/site-style` turns
+ * `project.json`'s `style` into a stylesheet, and it runs in places the DOM runtime cannot go — a
+ * static build, and a Cloudflare Worker serving a live preview. Importing the root export for
+ * `camelToKebab` would put the whole renderer plus `@vue/reactivity` inside a Worker script for
+ * four pure functions.
+ *
+ * `./runtime` re-exports all of these, so nothing that already imported them from the root export
+ * has to change. This is a narrow door beside the wide one, not a replacement for it.
+ */
+
+/**
+ * Convert camelCase to kebab-case.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function camelToKebab(s: string) {
+  return s.replaceAll(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}
+
+// ─── Style At-Rules ───────────────────────────────────────────────────────────
+
+/**
+ * The four CSS media types. A media _type_ is bare — `@media print` — while a media _feature_ is
+ * parenthesised, so `@media (print)` reads as a boolean feature named `print`, which does not exist
+ * and evaluates false.
+ */
+const MEDIA_TYPES = new Set(["all", "print", "screen", "speech"]);
+
+/**
+ * The media query an `@`-prefixed style key names, or null when the key is some other at-rule
+ * (`@supports`, `@starting-style`) that is emitted verbatim.
+ *
+ * `@--name` resolves through the project's `$media` map. `@(…)` carries its own parentheses, so
+ * they are stripped only when what they wrap is a bare media type: `@(print)` must become `@media
+ * print`, while `@(min-width: 40rem)` keeps them.
+ *
+ * @param {string} atKey
+ * @param {Record<string, string>} mediaQueries
+ * @returns {string | null}
+ * @docs framework/concepts/styling
+ */
+export function resolveAtQuery(atKey: string, mediaQueries: Record<string, string>): string | null {
+  if (atKey.startsWith("@--")) {
+    return mediaQueries[atKey.slice(1)] ?? atKey.slice(1);
+  }
+  if (atKey.startsWith("@(")) {
+    const inner = atKey.slice(2, -1).trim();
+    return MEDIA_TYPES.has(inner.toLowerCase()) ? inner : atKey.slice(1);
+  }
+  return null;
+}
+
+// ─── 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}`,
+  };
+}

package/src/runtime.ts

@@ -23,6 +23,7 @@ import {
   ref,
   toRaw,
 } from "@vue/reactivity";
+import { camelToKebab, pureSchemeOf, resolveAtQuery, schemeSelectors } from "./css.ts";
 import { evaluateExpression, evaluateOperand, isMutating } from "./expression.ts";
 import { readPath } from "./pointer.ts";
 import type { DynamicClass, JxEventHandler, JxPath, JxRenderOptions, JxScope } from "./types.ts";
@@ -103,7 +104,11 @@ export async function Jx(
   target: HTMLElement = document.body,
   options?: JxRenderOptions,
 ) {
-  const base = typeof source === "string" ? new URL(source, location.href).href : location.href;
+  const base = options?.base
+    ? new URL(options.base, location.href).href
+    : typeof source === "string"
+      ? new URL(source, location.href).href
+      : location.href;
   const doc = await resolve(source);
   checkSchemaVersion(doc.$schema);
 
@@ -711,6 +716,71 @@ function evaluateTemplate(str: string, state: JxScope): string {
   return fn(state, $map, $map?.item, $map?.index);
 }
 
+/**
+ * Whether a template is ONE expression end to end — `"${a.b}"` rather than `"a ${b}"` or
+ * `"${a}${b}"`.
+ *
+ * Depth-counted rather than pattern-matched. A greedy `/^\$\{(.+)\}$/` also matched `"${a} /
+ * ${b}"`, spliced the interior into `return (a} / ${b)`, and the SyntaxError became a silent null:
+ * the node rendered empty and a `$head` entry shipped its own template text. A brace scan is exact
+ * where a tightened regex is not — `"${`${a}-x`}"` is still one expression, and must keep its raw
+ * value.
+ *
+ * Lives here rather than in the compiler because both renderers must draw the line in the same
+ * place. It is what decides whether a value keeps its own type, and a value that is a boolean in
+ * one renderer and the string `"false"` in the other is a page that changes meaning as it
+ * hydrates.
+ *
+ * @param {string} str - Template source
+ * @returns {boolean} True when the whole string is a single `${…}`
+ */
+export function isSingleExpression(str: string): boolean {
+  if (!str.startsWith("${") || !str.endsWith("}")) {
+    return false;
+  }
+  let depth = 0;
+  for (let i = 1; i < str.length; i += 1) {
+    const c = str[i];
+    if (c === "{") {
+      depth += 1;
+    } else if (c === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return i === str.length - 1;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Evaluate a template for an ATTRIBUTE, keeping the expression's own type.
+ *
+ * `evaluateTemplate` interpolates into a string, which is what text wants and what an attribute
+ * cannot afford: `"${state.expanded}"` has to arrive as the boolean `false`, or `booleanAttrValue`
+ * never sees a boolean, `open="false"` is written, and HTML reads that as open. Only a single
+ * expression can carry a type at all — `"a ${b}"` is text by construction — which is the same line
+ * `evaluateStaticTemplate` draws in the compiler, and drawing it identically is what keeps a
+ * prerendered page and the same document rendered live in agreement.
+ *
+ * @param {string} str - Template source
+ * @param {JxScope} state - Reactive scope
+ * @returns {unknown} The expression's value, or the interpolated string
+ */
+function evaluateAttrTemplate(str: string, state: JxScope): unknown {
+  if (!isSingleExpression(str)) {
+    return evaluateTemplate(str, state);
+  }
+  const $map = state?.$map as { item?: unknown; index?: number } | undefined;
+  const fn = new Function("state", "$map", "item", "index", `return (${str.slice(2, -1)})`) as (
+    state: JxScope,
+    $map: unknown,
+    item: unknown,
+    index: number | undefined,
+  ) => unknown;
+  return fn(state, $map, $map?.item, $map?.index);
+}
+
 // ─── Step 2b: Function resolution (Shape 4) ─────────────────────────────────
 
 /** Shape of a dynamically imported module: named exports plus an optional default. */
@@ -1363,6 +1433,45 @@ export function reapplyStyle(
   applyStyle(el, styleDef ?? {}, mediaQueries, state);
 }
 
+/*
+ * HTML carries a boolean two incompatible ways, and writing one as the other inverts it in silence.
+ *
+ * A *boolean attribute* — `open`, `disabled`, `hidden`, `required` — is read by PRESENCE. Any value
+ * at all counts as true, `"false"` included, so `<details open="false">` is an OPEN `<details>`.
+ * The value must never be written; absence is the only way to say false.
+ *
+ * An *enumerated* attribute carries the word in its own text and reads an empty value as unset, so
+ * the presence form is the broken one here: bare `aria-hidden` is NOT hidden, and a dropped
+ * `contenteditable` means "inherit from the parent" rather than `false`. Every `aria-*` is in this
+ * family — ARIA has no presence attributes at all — along with the three HTML attributes below.
+ *
+ * @docs framework/concepts/elements
+ */
+const ENUMERATED_ATTRS = new Set(["contenteditable", "draggable", "spellcheck"]);
+
+/**
+ * The text an attribute's boolean value must be written with, or `null` when saying it means
+ * removing the attribute instead.
+ *
+ * An empty string is the bare form: `setAttribute(name, "")` is how the DOM spells the `open` that
+ * HTML source writes with no `=`.
+ *
+ * Shared rather than restated because two renderers must agree. The compiler writes attributes into
+ * a string of HTML and this file writes them onto live elements; were they to disagree about which
+ * family an attribute belongs to, a prerendered page would change meaning as it hydrated.
+ *
+ * @param {string} name - Attribute name, already resolved to what will be written
+ * @param {boolean} value - The resolved boolean
+ * @returns {string | null} Text to write, or null to omit the attribute
+ */
+export function booleanAttrValue(name: string, value: boolean): string | null {
+  const lower = name.toLowerCase();
+  if (lower.startsWith("aria-") || ENUMERATED_ATTRS.has(lower)) {
+    return String(value);
+  }
+  return value ? "" : null;
+}
+
 /**
  * @param {HTMLElement} el
  * @param {Record<string, import("@jxsuite/schema/types").JxAttributeValue>} attrs
@@ -1374,12 +1483,25 @@ function applyAttributes(el: HTMLElement, attrs: Record<string, JxAttributeValue
     /* Inside the effects, not before them. A `$ref` or `${…}` value is not a string until the
        effect runs — which is exactly why the document walk this replaced could never see it. */
     const write = (resolved: unknown) => {
+      if (typeof resolved === "boolean") {
+        const text = booleanAttrValue(attr, resolved);
+        /* `removeAttribute`, not `setAttribute(attr, "false")`. A binding that flips back has to
+           take the attribute WITH it: the element is being re-used, so anything left behind is the
+           state the page just said it had left. Asset rewriting is skipped because a boolean names
+           no asset — `canvasAssetValue` reads `src`/`href` values, which are never booleans. */
+        if (text === null) {
+          el.removeAttribute(attr);
+        } else {
+          el.setAttribute(attr, text);
+        }
+        return;
+      }
       el.setAttribute(attr, canvasAssetValue(el.tagName, k, String(resolved ?? "")));
     };
     if (isRefObj(v)) {
       effect(() => write(resolveRef(v.$ref, state)));
     } else if (isTemplateString(v)) {
-      effect(() => write(evaluateTemplate(v, state)));
+      effect(() => write(evaluateAttrTemplate(v, state)));
     } else {
       write(v);
     }
@@ -2438,15 +2560,19 @@ function mergeProps(def: JxElement, parentState: JxScope): JxScope {
   return child;
 }
 
-/**
- * Convert camelCase to kebab-case.
- *
- * @param {string} s
- * @returns {string}
+/*
+ * The CSS-authoring rules live in `./css.ts`, which imports nothing at all. They are re-exported
+ * here because they always were part of this module's surface and moving them must not break a
+ * consumer; a host that cannot afford the DOM runtime imports `@jxsuite/runtime/css` instead.
  */
-export function camelToKebab(s: string) {
-  return s.replaceAll(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
-}
+export {
+  camelToKebab,
+  COLOR_SCHEME_ATTR,
+  COLOR_SCHEME_STORAGE_KEY,
+  pureSchemeOf,
+  resolveAtQuery,
+  schemeSelectors,
+} from "./css.ts";
 
 /**
  * Convert a style rules object to a CSS text string (skipping nested selectors).
@@ -2461,97 +2587,6 @@ export function toCSSText(rules: Record<string, unknown> | object) {
     .join("; ");
 }
 
-// ─── Style At-Rules ───────────────────────────────────────────────────────────
-
-/**
- * The four CSS media types. A media _type_ is bare — `@media print` — while a media _feature_ is
- * parenthesised, so `@media (print)` reads as a boolean feature named `print`, which does not exist
- * and evaluates false.
- */
-const MEDIA_TYPES = new Set(["all", "print", "screen", "speech"]);
-
-/**
- * The media query an `@`-prefixed style key names, or null when the key is some other at-rule
- * (`@supports`, `@starting-style`) that is emitted verbatim.
- *
- * `@--name` resolves through the project's `$media` map. `@(…)` carries its own parentheses, so
- * they are stripped only when what they wrap is a bare media type: `@(print)` must become `@media
- * print`, while `@(min-width: 40rem)` keeps them.
- *
- * @param {string} atKey
- * @param {Record<string, string>} mediaQueries
- * @returns {string | null}
- * @docs framework/concepts/styling
- */
-export function resolveAtQuery(atKey: string, mediaQueries: Record<string, string>): string | null {
-  if (atKey.startsWith("@--")) {
-    return mediaQueries[atKey.slice(1)] ?? atKey.slice(1);
-  }
-  if (atKey.startsWith("@(")) {
-    const inner = atKey.slice(2, -1).trim();
-    return MEDIA_TYPES.has(inner.toLowerCase()) ? inner : atKey.slice(1);
-  }
-  return null;
-}
-
-// ─── 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/types.ts

@@ -15,6 +15,17 @@ export type JxEventHandler = (scope: JxScope, event: Event) => unknown;
 
 export interface JxRenderOptions {
   _path?: JxPath;
+  /**
+   * Base URL the document's own references resolve against — `$ref`, `$elements`, `$head` and the
+   * asset paths beneath them.
+   *
+   * Only {@link Jx} reads it, and only when it was handed a document OBJECT rather than a URL. A URL
+   * carries its own base; an object does not, so the base defaulted to `location.href` — which is
+   * right for a page served at the project root and wrong everywhere else. A host that composes a
+   * document server-side and serves it at `/blog/hello/` needs to say that its references are still
+   * root-relative, or every one of them resolves a directory too deep.
+   */
+  base?: string;
   /** The namespace the parent element established — SVG and MathML descendants inherit it. */
   _ns?: string | null;
   /**