@jxsuite/compiler 1.5.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "1.5.0",
+  "version": "2.0.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -45,17 +45,19 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^15.5.0",
-    "@jxsuite/create": "^1.2.2",
-    "@jxsuite/runtime": "^1.3.2",
-    "@jxsuite/schema": "^1.5.0",
-    "esbuild": "^0.28.1",
+    "@apidevtools/json-schema-ref-parser": "^16.0.0",
+    "@jxsuite/create": "^1.3.0",
+    "@jxsuite/runtime": "^2.0.0",
+    "@jxsuite/schema": "^1.6.0",
+    "@vue/reactivity": "3.5.41",
+    "esbuild": "^0.28.2",
+    "lit-html": "^3.3.3",
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.1",
-    "@jxsuite/connector": "^0.4.2",
-    "@jxsuite/parser": "^1.4.1",
+    "@happy-dom/global-registrator": "^20.11.2",
+    "@jxsuite/connector": "^0.5.0",
+    "@jxsuite/parser": "^1.5.0",
     "@types/mdast": "^4.0.4"
   }
 }

package/src/compiler.ts

@@ -130,7 +130,7 @@ export async function compile(sourcePath: string | JxDocument, opts: CompileOpti
       path: `${tagName}.js`,
       tagName,
     };
-    const styleBlock = compileStyles(raw, raw.$media ?? {});
+    const styleBlock = compileStyles(raw, raw.$media ?? {}, projectStyle);
 
     const html = `<!DOCTYPE html>
 <html lang="en">

package/src/shadow.ts

@@ -0,0 +1,65 @@
+/**
+ * Shadow DOM, opt-in.
+ *
+ * Light DOM is the default and stays the default. It is not a placeholder for shadow DOM: a Jx
+ * component's styles are reachable from the page, which is how a project restyles a component it
+ * did not write, and the `<slot>` emulation that makes light-DOM composition work has different
+ * distribution semantics from real slotting. Switching a component to a shadow root changes both,
+ * so it is a per-component decision an author makes deliberately.
+ *
+ * `$shadow` on a component document, `defaults.shadow` on the project, `false` if neither says
+ * otherwise. `"open"` and `"closed"` are the standard's two modes; the difference matters more here
+ * than usual, because a **closed** declarative shadow root is not reachable through
+ * `element.shadowRoot` and hydration has to find it another way (§16.6).
+ *
+ * @docs framework/concepts/components
+ */
+
+import type { JxDocument, JxElement, ProjectConfig } from "@jxsuite/schema/types";
+
+/** The two modes the standard defines, or null for light DOM. */
+export type ShadowMode = "open" | "closed";
+
+/** A value `$shadow` or `defaults.shadow` may carry. */
+export type ShadowSetting = ShadowMode | false;
+
+function asSetting(value: unknown): ShadowSetting | undefined {
+  if (value === false || value === "open" || value === "closed") {
+    return value;
+  }
+  return undefined;
+}
+
+/**
+ * The shadow mode a component renders in, or null for light DOM.
+ *
+ * A component's own `$shadow` wins over the project default in both directions — including
+ * `$shadow: false`, which is how one component opts _out_ of a project that opted in.
+ *
+ * @param {JxDocument | JxElement | null | undefined} doc - The component definition
+ * @param {ProjectConfig["defaults"] | undefined} defaults
+ * @returns {ShadowMode | null}
+ */
+export function resolveShadowMode(
+  doc: JxDocument | JxElement | null | undefined,
+  defaults?: ProjectConfig["defaults"],
+): ShadowMode | null {
+  const own = asSetting((doc as { $shadow?: unknown } | null | undefined)?.$shadow);
+  const setting = own ?? asSetting(defaults?.shadow) ?? false;
+  return setting === false ? null : setting;
+}
+
+/**
+ * The CSS scope prefix for a component's own rules.
+ *
+ * In light DOM the prefix is the tag name, which is what makes `sty-card .inner` reach only that
+ * component's descendants. Inside a shadow root the selector cannot see the host's tag name, and
+ * `:host` is the standard's way to address it.
+ *
+ * @param {string} tagName
+ * @param {ShadowMode | null} shadow
+ * @returns {string}
+ */
+export function styleScopePrefix(tagName: string, shadow: ShadowMode | null): string {
+  return shadow === null ? tagName : ":host";
+}

package/src/shared.ts

@@ -18,21 +18,26 @@ import {
 import { evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
 import { runStatements } from "@jxsuite/runtime/statements";
 import {
+  bodyReturnsValue,
   childrenContainArray,
   hasStructuredBody,
   isExpressionDef,
   isFunctionDef,
   isMappedArray,
-  bodyReturnsValue,
   isNamedFormulaDef,
   isPrototypeDef,
   isRef,
   isSchemaOnlyDef as isSchemaOnly,
   isServerFnDef,
+  isTagExpression,
   isTemplateString,
   paramNames,
+  tagNameCandidates,
 } from "@jxsuite/schema/guards";
+import { styleScopePrefix } from "./shadow.ts";
+import type { ShadowMode } from "./shadow.ts";
 import type { ExpressionNode } from "@jxsuite/runtime/expression";
+import { readPath } from "@jxsuite/runtime/pointer";
 import type {
   JsonValue,
   JxElement,
@@ -54,7 +59,13 @@ export {
   schemeSelectors,
   toCSSText,
 } from "@jxsuite/runtime";
-export { compileExpression, evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+export {
+  compileExpression,
+  compileOperandSource,
+  evaluateExpression,
+  evaluateOperand,
+  isMutating,
+} from "@jxsuite/runtime/expression";
 export { compileStatements, runStatements } from "@jxsuite/runtime/statements";
 
 /**
@@ -416,6 +427,62 @@ export function createCompileContext(
   return { media, scope, scopeDefs };
 }
 
+/**
+ * `state.x = …`, `state.x += …`, `state.x++` — every form a string handler body can use to write a
+ * state entry. `===`/`!==`/`<=`/`>=` are excluded by the `(?!=)` guard and by the operator set.
+ */
+const STATE_ASSIGNMENT_RE =
+  /\bstate\.([A-Za-z_$][\w$]*)\s*(?:\+\+|--|(?:\*\*|\|\||&&|\?\?|<<|>>>|>>|[-+*/%&|^])?=(?!=))/g;
+
+/** `state.list.push(…)` and friends mutate in place without ever assigning to the entry. */
+const STATE_MUTATING_METHOD_RE =
+  /\bstate\.([A-Za-z_$][\w$]*)\s*\.\s*(?:push|pop|shift|unshift|splice|sort|reverse|fill|copyWithin)\s*\(/g;
+
+/**
+ * Collect every state key a handler writes to, across all the forms a body can take: a string body,
+ * a structured body (spec §20), and an `$expression` node with a mutating operator.
+ *
+ * Used to keep prerender from baking a binding over an entry that changes after hydration. A plain
+ * `{ "type": "string" }` entry holds a perfectly ordinary build-time value, so nothing else
+ * distinguishes it from a constant — but if a handler assigns to it, interpolating it at build time
+ * replaces the template in the emitted output and the element is dead for the life of the page.
+ *
+ * @param {unknown} node
+ * @param {Set<string>} into
+ */
+function collectAssignedStateKeys(node: unknown, into: Set<string>) {
+  if (typeof node === "string") {
+    for (const m of node.matchAll(STATE_ASSIGNMENT_RE)) {
+      into.add(m[1] as string);
+    }
+    for (const m of node.matchAll(STATE_MUTATING_METHOD_RE)) {
+      into.add(m[1] as string);
+    }
+    return;
+  }
+  if (!node || typeof node !== "object") {
+    return;
+  }
+  if (Array.isArray(node)) {
+    for (const entry of node) {
+      collectAssignedStateKeys(entry, into);
+    }
+    return;
+  }
+  const rec = node as Record<string, unknown>;
+  // A mutating expression names its destination as `target: { $ref: "#/state/x" }`.
+  const op = rec.operator;
+  if (typeof op === "string" && isMutating(op)) {
+    const target = rec.target as { $ref?: string } | undefined;
+    if (target && typeof target.$ref === "string" && target.$ref.startsWith("#/state/")) {
+      into.add(target.$ref.slice("#/state/".length).split("/")[0] as string);
+    }
+  }
+  for (const value of Object.values(rec)) {
+    collectAssignedStateKeys(value, into);
+  }
+}
+
 /**
  * @param {Record<string, JxStateDefinition>} [defs]
  * @param {Record<string, unknown> | null} [parentScope]
@@ -439,6 +506,26 @@ export function buildInitialScope(
     writable: true,
   });
 
+  // Pass 0: every entry some handler in this document writes to is mutable, so prerender must not
+  // Bake a binding over it. Narrow on purpose — an entry nothing ever writes stays bakeable, so
+  // Prerendered content is preserved for SEO. A `$src` handler's assignments live in a JS file this
+  // Builder cannot open, so a write that only happens there is still missed (issue #125).
+  const assigned = new Set<string>();
+  for (const def of Object.values(defs)) {
+    if (def && typeof def === "object" && (isFunctionDef(def) || isExpressionDef(def))) {
+      collectAssignedStateKeys(
+        (def as { body?: unknown; $expression?: unknown }).body ??
+          (def as { $expression?: unknown }).$expression,
+        assigned,
+      );
+    }
+  }
+  for (const key of assigned) {
+    if (key in defs) {
+      runtimeOnly.add(key);
+    }
+  }
+
   for (const [key, def] of Object.entries(defs)) {
     if (typeof def !== "object" || def === null || Array.isArray(def)) {
       setOwnScopeValue(scope, key, cloneValue(def));
@@ -457,6 +544,10 @@ export function buildInitialScope(
   // Template-string entries are deferred to a third pass: whether one is resolvable depends on the
   // Runtime-only marks the loop below adds, and key order must not decide the answer.
   const templateDefs: [string, string][] = [];
+  // Computed (`bodyReturnsValue`) entries are deferred for the same reason. A computed is stored in
+  // The scope as its already-evaluated *result*, so a template reading it sees an ordinary string
+  // And prerender bakes it — destroying the binding rather than merely staling it (issue #124).
+  const computedBodies: [string, string][] = [];
 
   for (const [key, def] of Object.entries(defs)) {
     if (typeof def === "string" && isTemplateString(def)) {
@@ -515,6 +606,7 @@ export function buildInitialScope(
           fn(...params.map((name) => (name === "state" ? state : event)));
         if (bodyReturnsValue(body)) {
           defineLazyScopeValue(scope, key, () => invoke(scope));
+          computedBodies.push([key, body]);
         } else {
           setOwnScopeValue(scope, key, invoke);
         }
@@ -539,13 +631,23 @@ export function buildInitialScope(
     }
   }
 
-  for (const [key, template] of templateDefs) {
-    // A state entry that interpolates a runtime-only key cannot resolve until hydration either, so
-    // It is runtime-only in turn. Without this, prerender would bake the failed evaluation (`null`)
-    // Into every template that reads *this* entry, one step removed from the original.
-    if (readsRuntimeOnlyState(template, scope)) {
-      runtimeOnly.add(key);
+  // A state entry that reads a runtime-only key cannot resolve until hydration either, so it is
+  // Runtime-only in turn. Without this, prerender would bake the failed evaluation (`null`) into
+  // Every template that reads *this* entry, one step removed from the original. Iterated to a
+  // Fixpoint because marking one entry can qualify another, in either direction, and declaration
+  // Order must not decide the answer.
+  let marked = true;
+  while (marked) {
+    marked = false;
+    for (const [key, source] of [...computedBodies, ...templateDefs]) {
+      if (!runtimeOnly.has(key) && readsRuntimeOnlyState(source, scope)) {
+        runtimeOnly.add(key);
+        marked = true;
+      }
     }
+  }
+
+  for (const [key, template] of templateDefs) {
     defineLazyScopeValue(scope, key, () => evaluateStaticTemplate(template, scope));
   }
 
@@ -622,14 +724,15 @@ export function resolveRefValue(refValue: unknown, scope: Record<string, unknown
     return parts.length > 2 ? getPathValue(base, parts.slice(2).join("/")) : base;
   }
   if (refValue.startsWith("#/state/")) {
-    const sub = refValue.slice("#/state/".length);
-    const slash = sub.indexOf("/");
-    if (slash === -1) {
-      return scope[sub];
-    }
-    return getPathValue(scope[sub.slice(0, slash)], sub.slice(slash + 1));
-  }
-  return scope[refValue] ?? null;
+    // One call, not a hand-split leading token: slicing at the first `/` skipped unescaping it, so
+    // `#/state/a~1b/c` looked for a member called `a~1b` rather than `a/b`.
+    return getPathValue(scope, refValue.slice("#/state/".length));
+  }
+  /*
+   * An unrecognized scheme is still a path, matching the runtime resolvers and the lowerer.
+   * Reading it as one key returned null for `a/b` while the emitted client module walked it.
+   */
+  return getPathValue(scope, refValue) ?? null;
 }
 
 /**
@@ -661,7 +764,15 @@ function readsRuntimeOnlyState(str: string, scope: Record<string, unknown>) {
     if (runtimeOnly instanceof Set && runtimeOnly.has(key)) {
       return true;
     }
-    if (typeof scope[key] === "function") {
+    // Reading the key can run a computed's getter, which is free to throw on partial build-time
+    // Data. A throw says nothing about whether the entry is runtime-only, so it is not a mark.
+    let value: unknown;
+    try {
+      value = scope[key];
+    } catch {
+      continue;
+    }
+    if (typeof value === "function") {
       return true;
     }
   }
@@ -677,20 +788,21 @@ export function evaluateStaticTemplate(str: string, scope: Record<string, unknow
   if (readsRuntimeOnlyState(str, scope)) {
     return null;
   }
+  /*
+   * `$site` and `$page` are bound as parameters, not just left on `state`.
+   *
+   * `injectContext` puts them on the document's state, so `${state.$site.name}` always worked — but
+   * every example in site-architecture.md §8.2 writes the bare `${$site.name}`, and that threw a
+   * ReferenceError the catch below turned into a silent null. A `$head` title referencing the site
+   * name reached the page as the literal template text.
+   */
+  const args = ["state", "$map", "$site", "$page"] as const;
+  const values = [scope, scope?.$map, scope?.$site, scope?.$page];
   try {
     const singleExprMatch = str.match(/^\$\{(.+)\}$/s);
-    if (singleExprMatch) {
-      const fn = new Function("state", "$map", `return (${singleExprMatch[1]})`) as (
-        state: Record<string, unknown>,
-        $map: unknown,
-      ) => unknown;
-      return fn(scope, scope?.$map);
-    }
-    const fn = new Function("state", "$map", `return \`${str}\``) as (
-      state: Record<string, unknown>,
-      $map: unknown,
-    ) => unknown;
-    return fn(scope, scope?.$map);
+    const body = singleExprMatch ? `return (${singleExprMatch[1]})` : `return \`${str}\``;
+    const fn = new Function(...args, body) as (...a: unknown[]) => unknown;
+    return fn(...values);
   } catch {
     return null;
   }
@@ -702,14 +814,7 @@ export function evaluateStaticTemplate(str: string, scope: Record<string, unknow
  * @returns {unknown}
  */
 export function getPathValue(base: unknown, path: string) {
-  if (!path) {
-    return base;
-  }
-  let acc: unknown = base;
-  for (const key of path.split("/")) {
-    acc = acc == null ? undefined : (acc as Record<string, unknown>)[key];
-  }
-  return acc;
+  return readPath(base, path);
 }
 
 /**
@@ -801,15 +906,6 @@ export function buildAttrs(def: JxElement | JxMutableNode, scope: Record<string,
     }
   }
 
-  if (def.tagName === "img") {
-    if (!def.attributes?.loading) {
-      out += ` loading="lazy"`;
-    }
-    if (!def.attributes?.decoding) {
-      out += ` decoding="async"`;
-    }
-  }
-
   if (def.$static) {
     out += ` data-jx-static`;
   } else if (def.$prerendered) {
@@ -1173,11 +1269,16 @@ export function collectStyles(
     counter.n += 1;
   }
 
+  /* A chosen tag needs a selector that matches every candidate, not the first one.
+     `#id` and `.class` are unaffected — they identify the element regardless of what it turns out
+     to be — but a bare tag selector has to become the union, or styling an `<a>|<div>` wrapper
+     would style exactly one of the two branches and silently miss the other. */
+  const tagSelector = tagNameCandidates(def.tagName).join(", ") || "*";
   const selector = def.id
     ? `#${def.id}`
     : def.className
       ? `.${def.className.split(" ")[0]}`
-      : (def.tagName ?? "*");
+      : tagSelector;
 
   if (def.style) {
     const baseDecls = [];
@@ -1378,6 +1479,40 @@ export const SELF_CLOSING = new Set<string>([
   "source",
 ]);
 
+/**
+ * A tag for the PRERENDER, resolved against the same scope the attributes are.
+ *
+ * The static renderer produces bytes, so it must commit to one element. Every candidate is a
+ * literal `TagName`, so committing is safe — and it is resolved here rather than left as text
+ * precisely because the old `${…}` form was left as text and then re-resolved against the page
+ * scope, where a component's own state is undefined.
+ *
+ * @param {unknown} tagName
+ * @param {Record<string, unknown>} scope
+ * @returns {string}
+ */
+export function resolveStaticTagName(
+  tagName: unknown,
+  scope: Record<string, unknown> | null,
+): string {
+  if (typeof tagName === "string") {
+    return tagName;
+  }
+  const candidates = tagNameCandidates(tagName);
+  if (candidates.length === 0) {
+    return "div";
+  }
+  if (!isTagExpression(tagName)) {
+    return candidates[0]!;
+  }
+  const expression = tagName.$expression;
+  if (expression.operator === "?:") {
+    return resolveStaticValue(expression.target, scope) ? expression.value : expression.initial;
+  }
+  const key = resolveStaticValue(expression.target, scope);
+  return expression.cases[String(key)] ?? expression.default;
+}
+
 /**
  * Recursively render a Jx node tree to static HTML for pre-rendering.
  *
@@ -1435,7 +1570,11 @@ export function renderStaticNode(
     return `<${switchTag}${attrs}>${inner}</${switchTag}>`;
   }
 
-  const tag = node.tagName ?? "div";
+  /* Resolved against the SAME scope the attributes are resolved against, so the prerendered markup
+     and the client's first render agree about what element this is. The old `${…}` form could not
+     do this — it re-resolved the emitted string against the page scope, where a component's own
+     state does not exist, so SSR silently emitted the fallback branch's tag. */
+  const tag = resolveStaticTagName(node.tagName, scope);
 
   // Replace <slot> with provided slot content
   if (tag === "slot" && slotContent != null) {
@@ -1584,13 +1723,55 @@ function _isStaticNode(node: JxElement | string | (JxElement | string)[]): boole
  * @param {Record<string, string>} [mediaQueries] - Project media query definitions
  * @returns {string} CSS text, or empty string if no styles
  */
+/** `::slotted()` and `::part()` select through a shadow boundary, not the host that owns it. */
+const SHADOW_STANDALONE = /^(?:::slotted\(|::part\()/;
+
+/**
+ * Turn one nested style key into a selector, given the component's scope prefix.
+ *
+ * Three shapes, and the interesting one is `:host`. A style object should mean the same thing in
+ * both modes, so `:host` and `:host(.foo)` are **translated** rather than passed through: inside a
+ * shadow root they stand alone, and in the light DOM they become the tag name and `<tag>.foo` —
+ * which is what "the host, matching this" means when there is no shadow root. Moving a component
+ * between modes therefore does not silently break its styles.
+ *
+ * @param {string} prop - The style-object key, e.g. `":hover"`, `"& .inner"`, `":host(.wide)"`
+ * @param {string} scope - `":host"` in shadow mode, the tag name otherwise
+ * @returns {string}
+ */
+function resolveSelector(prop: string, scope: string): string {
+  if (prop.startsWith("&")) {
+    return prop.replace("&", scope);
+  }
+  if (prop.startsWith(":host")) {
+    const inner = /^:host\((.*)\)$/.exec(prop)?.[1];
+    if (scope === ":host") {
+      return prop;
+    }
+    return inner === undefined ? scope : `${scope}${inner}`;
+  }
+  // `:host::slotted(x)` matches nothing — the pseudo-element attaches to a slot, not the host.
+  if (scope === ":host" && SHADOW_STANDALONE.test(prop)) {
+    return prop;
+  }
+  return `${scope}${prop}`;
+}
+
 export function buildComponentCSS(
   tagName: string,
   styleDef?: JxStyle | null | undefined,
   doc: JxElement | null = null,
   mediaQueries: Record<string, string> = {},
+  shadow: ShadowMode | null = null,
 ) {
   const rules: string[] = [];
+  /*
+   * The scope prefix. In light DOM it is the tag name, which is what keeps `sty-card .inner` from
+   * reaching another component's `.inner`. Inside a shadow root the selector cannot see the host's
+   * tag name at all, and `:host` is the standard's way to address it — so the same style object
+   * produces different, correct CSS in each mode without the author restating it.
+   */
+  const scope = styleScopePrefix(tagName, shadow);
 
   if (styleDef && typeof styleDef === "object") {
     const decls: string[] = [];
@@ -1613,20 +1794,21 @@ export function buildComponentCSS(
       decls.push(`  ${camelToKebab(prop)}: ${value};`);
     }
     if (decls.length > 0) {
-      rules.push(`${tagName} {\n${decls.join("\n")}\n}`);
+      rules.push(`${scope} {\n${decls.join("\n")}\n}`);
     }
 
     for (const [prop, val] of Object.entries(styleDef)) {
       if (prop.startsWith("@")) {
-        pushConditionalRule(rules, prop, mediaQueries, tagName, val as Record<string, unknown>);
+        pushConditionalRule(rules, prop, mediaQueries, scope, val as Record<string, unknown>);
       } else if (
         prop.startsWith(":") ||
         prop.startsWith(".") ||
         prop.startsWith("&") ||
         prop.startsWith("[")
       ) {
-        const resolved = prop.startsWith("&") ? prop.replace("&", tagName) : `${tagName}${prop}`;
-        rules.push(`${resolved} { ${toCSSText(val as Record<string, unknown>)} }`);
+        rules.push(
+          `${resolveSelector(prop, scope)} { ${toCSSText(val as Record<string, unknown>)} }`,
+        );
       }
     }
   }