@jxsuite/runtime 6.3.0 → 7.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/runtime",
-  "version": "6.3.0",
+  "version": "7.1.0",
   "description": "JSON-native reactive web component runtime",
   "license": "MIT",
   "repository": {
@@ -33,12 +33,12 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^5.6.0",
-    "@vue/reactivity": "3.5.44"
+    "@jxsuite/schema": "^6.0.2",
+    "@vue/reactivity": "3.5.45"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^21.0.4",
-    "@jxsuite/erase": "^0.2.0",
+    "@jxsuite/erase": "^0.3.2",
     "@jxsuite/test-support": "^0.0.0"
   }
 }

package/src/body-eraser.ts

@@ -7,6 +7,9 @@
  * with {@link setBodyEraserLoader}, which is fetched only when a document has a body that needs it.
  * With neither, a body compiles as written, and one that does not compile says what would fix it.
  *
+ * The same file carries what imports a module written in TypeScript (`spec.md` §23.2), so the same
+ * loader brings it: {@link moduleLoaderFor} is what the runtime asks before importing one.
+ *
  * @docs framework/concepts/functions
  */
 import { isFunctionEntry, isJsonObject, isString } from "@jxsuite/schema/guards";
@@ -25,9 +28,27 @@ export type BodyEraser = (text: string) => {
   problems: readonly BodyEraserProblem[];
 };
 
+/** What a host tells {@link ModuleLoader} about one import. */
+export interface ModuleLoadOptions {
+  /** The URL a relative specifier, and a document's path in a `jx-script:` one, resolves against. */
+  base?: string | undefined;
+  /** Where the host serves a package, as given to `setNpmModuleResolver`. */
+  resolveNpm?: ((specifier: string) => string) | null | undefined;
+  /** The module's text when the runtime already holds it, so nothing is fetched for it. */
+  text?: string | undefined;
+}
+
+/**
+ * What `loadModule` from `@jxsuite/erase/browser` is: a TypeScript module's URL, or a document
+ * script's `jx-script:` specifier, in and its namespace out (`spec.md` §23.2).
+ */
+export type ModuleLoader = (specifier: string, options: ModuleLoadOptions) => Promise<object>;
+
 /** What importing `@jxsuite/erase/browser` gives. */
 export interface BodyEraserModule {
   eraseBody: BodyEraser;
+  /** Absent from an eraser built before document scripts; a TypeScript module then cannot load. */
+  loadModule?: ModuleLoader;
 }
 
 /** A compiled body: called with what its caller passes, returning what its body returns. */
@@ -37,6 +58,7 @@ export type CompiledBody = (...args: never[]) => JxScopeValue;
 export type BodyEraserLoader = () => Promise<BodyEraserModule>;
 
 let eraser: BodyEraser | null = null;
+let moduleLoader: ModuleLoader | null = null;
 let loader: BodyEraserLoader | null = null;
 let loading: Promise<void> | null = null;
 
@@ -57,6 +79,53 @@ export function setBodyEraser(fn: BodyEraser | null): void {
   }
 }
 
+/**
+ * Install (or with `null`, remove) the function that imports a module written in TypeScript: a
+ * `.ts` file a `$src` names, or a document's own client script (`spec.md` §23.2). A host that sets
+ * {@link setBodyEraserLoader} needs no call to this: the loader it fetches brings one.
+ *
+ * @param fn `loadModule` from `@jxsuite/erase/browser`.
+ */
+export function setModuleLoader(fn: ModuleLoader | null): void {
+  moduleLoader = fn;
+  if (!fn) {
+    // Taken away, so a later module that needs one loads it again.
+    loading = null;
+  }
+}
+
+/** Whether this page can import a TypeScript module: a loader is installed, or can be fetched. */
+export function canLoadModules(): boolean {
+  return moduleLoader !== null || loader !== null;
+}
+
+/** Fetch the eraser through the host's loader, once, and install what it gives. */
+function fetchEraser(load: BodyEraserLoader): Promise<void> {
+  loading ??= load().then((module) => {
+    if (loader !== load) {
+      return;
+    }
+    if (!eraser) {
+      setBodyEraser(module.eraseBody);
+    }
+    if (!moduleLoader && module.loadModule) {
+      setModuleLoader(module.loadModule);
+    }
+  });
+  return loading;
+}
+
+/**
+ * What imports a TypeScript module on this page, fetching the eraser for it when the host said how
+ * and nothing is installed yet. Null when the host gave the page neither.
+ */
+export async function moduleLoaderFor(): Promise<ModuleLoader | null> {
+  if (!moduleLoader && loader) {
+    await fetchEraser(loader);
+  }
+  return moduleLoader;
+}
+
 /**
  * Say how to fetch the eraser when a document needs it, so a page with no typed body downloads
  * nothing. The runtime installs what the promise gives.
@@ -146,12 +215,7 @@ export async function prepareBodies(doc: JsonValue | JxDocument | JxClassDef): P
   if (!bodiesOf(tree).some((body) => bodyNeedsEraser(body))) {
     return;
   }
-  loading ??= load().then((module) => {
-    if (loader === load) {
-      setBodyEraser(module.eraseBody);
-    }
-  });
-  await loading;
+  await fetchEraser(load);
 }
 
 /** A body's JavaScript, through the eraser when one is installed. */

package/src/css.ts

@@ -284,7 +284,8 @@ export function splitSelectorList(selector: string): string[] {
  * `null` means "do not emit this rule at all", and `::backdrop` is the one thing it is returned
  * for. There is no backdrop pseudo-element outside the top layer; synthesising one would paint a
  * full-canvas scrim over the document being edited, and emitting an inert rule would mark the
- * selector as "styled" in the Style panel while doing nothing. Preview renders it natively.
+ * selector as "styled" in the Style panel while doing nothing. A page in a browser renders it
+ * natively.
  *
  * @param {string} selector - A fully resolved selector, canvas-side
  * @returns {string | null} The selector to emit, or null to emit nothing
@@ -506,8 +507,8 @@ export interface CssRule {
    * It is NOT in {@link CssRule.text}, and that is the point. `text` is what a sheet inserts and
    * what {@link hashCss} interns, so prose there would make two identical rules two rules and put a
    * paragraph in every adopted sheet at runtime. A static emitter — the one writing a stylesheet a
-   * person will read — renders it as a comment; every other consumer ignores it, exactly as a
-   * document's own `$description` is ignored.
+   * person will read — renders it as a comment through {@link commentedRuleText}; every other
+   * consumer ignores it, exactly as a document's own `$description` is ignored.
    */
   description?: string;
   /** See {@link CssRuleTarget}. */
@@ -520,8 +521,8 @@ export interface CssRule {
 export interface CssBuildOptions {
   /**
    * The selector the style object hangs off. Every nested key resolves against it, so the runtime
-   * passes a placeholder it substitutes afterwards and the compiler passes `#id` / `.jx-N` / a
-   * tag.
+   * passes a placeholder it substitutes afterwards and the compiler passes an element's generated
+   * class or a component's tag.
    */
   scope?: string | null;
   /** The project's `$media` map, for resolving `@--name` keys. */
@@ -613,6 +614,25 @@ export function cssRuleText(
   return text;
 }
 
+/**
+ * A rule as a static build writes it: its `$description` as a comment on the line above, then its
+ * text (spec.md §9.2). An undescribed rule is its text, byte for byte.
+ *
+ * CSS comments have no escape, so a comment terminator in the prose (an asterisk and then a slash)
+ * is written with a space between the two: breaking the sequence is the only way to keep the
+ * comment from ending early. The prose is otherwise verbatim, newlines included.
+ *
+ * @param {Pick<CssRule, "text" | "description">} rule
+ * @returns {string}
+ * @docs framework/concepts/styling
+ */
+export function commentedRuleText(rule: Pick<CssRule, "text" | "description">): string {
+  if (rule.description === undefined) {
+    return rule.text;
+  }
+  return `/* ${rule.description.replaceAll("*/", "* /")} */\n${rule.text}`;
+}
+
 /**
  * Serialize one `@keyframes` block: every stop, in authored order, inside ONE at-rule, wrapped in
  * its enclosing conditions.
@@ -814,6 +834,10 @@ export function buildStyleRules(style: JxStyle, options: CssBuildOptions = {}):
     return declarations;
   };
 
+  /** A block's `$description` as the member a rule carries, when it wrote a non-empty one. */
+  const describedBy = (description: JxStyle[string]): { description?: string } =>
+    isString(description) && description !== "" ? { description } : {};
+
   const emit = (
     conditions: readonly string[],
     selector: string | null,
@@ -841,10 +865,7 @@ export function buildStyleRules(style: JxStyle, options: CssBuildOptions = {}):
       target,
       key: hashCss(text),
     };
-    if (isString(description) && description !== "") {
-      rule.description = description;
-    }
-    rules.push(rule);
+    rules.push({ ...rule, ...describedBy(description) });
   };
 
   /**
@@ -883,6 +904,7 @@ export function buildStyleRules(style: JxStyle, options: CssBuildOptions = {}):
       return;
     }
     const text = cssKeyframesText(conditions, name, blocks);
+    // The block's own `$description` documents the rule; a stop's is ignored, as a stop is no rule.
     rules.push({
       blocks,
       conditions: [...conditions],
@@ -891,6 +913,7 @@ export function buildStyleRules(style: JxStyle, options: CssBuildOptions = {}):
       selector: null,
       target: "unscoped",
       text,
+      ...describedBy(block["$description"]),
     });
   };
 

package/src/expression.ts

@@ -13,12 +13,15 @@ import {
   INTL_HELPER_PATHS,
   INTL_LOCALE_PARAM,
 } from "@jxsuite/schema/intl";
-import { isFunction, isNonNullObject, isString } from "@jxsuite/schema/guards";
+import { isFunction, isNamedFormulaDef, isNonNullObject, isString } from "@jxsuite/schema/guards";
 import type {
   CemParameter,
+  JxDocumentValue,
+  JxExpressionDef,
   JxExpressionNode,
   JxExpressionOperand,
   JxRef,
+  JxStateDefinition,
 } from "@jxsuite/schema/types";
 import type { JxScope, JxScopeValue } from "./types.ts";
 import { readPath, refAccessor, refSegments } from "./pointer.ts";
@@ -341,6 +344,19 @@ function withPageLocale(path: string, args: JxScopeValue[], state: JxScope): JxS
   return filled;
 }
 
+/**
+ * The object a `window#/…` ref reads from. A site build prerenders in a process with no `window`,
+ * where the standard library the blessed list names (Math, JSON, Array, …) hangs off the global
+ * object itself, so the read falls back to it and a formula resolves at build as it does in a
+ * page.
+ */
+function windowRoot(): object {
+  /* SAFETY: the DOM lib types `window` as always present; outside a browser the property is simply
+     absent, which is the one fact this read exists to observe. */
+  const root = (globalThis as { window?: object }).window;
+  return root ?? globalThis;
+}
+
 /** Whether a `window#/…` callee ref is on the blessed pure-globals list. */
 export function isBlessedGlobal(ref: string): boolean {
   return ref.startsWith("window#/") && BLESSED_GLOBALS.has(ref.slice("window#/".length));
@@ -354,6 +370,125 @@ export function isMutating(op: string) {
   return MUTATING_OPS.has(op);
 }
 
+// ─── Pure named formulas, and the ones a component inherits ─────────────────
+
+/** Whether an operand, or any node nested in it, carries a mutating operator. */
+function operandMutates(operand: JxExpressionOperand | undefined): boolean {
+  if (Array.isArray(operand)) {
+    return operand.some((item) => operandMutates(item));
+  }
+  if (operand === undefined || !isNodeOperand(operand)) {
+    return false;
+  }
+  return (
+    isMutating(operand.operator) ||
+    [operand.target, operand.value, operand.initial, operand.default].some((part) =>
+      operandMutates(part),
+    ) ||
+    Object.values(operand.cases ?? {}).some((part) => operandMutates(part))
+  );
+}
+
+/**
+ * Whether a state entry is a pure named formula (spec.md §19.4c): an `$expression` with
+ * `parameters` whose body mutates nothing.
+ *
+ * Such an entry is a function, not reactive state. It holds no value, nothing can write it, and
+ * reading it subscribes to nothing, so the entry by itself gives a page nothing to do in the
+ * browser: only a read of it that is left for the client does (compiler.md §3).
+ *
+ * @param {JxDocumentValue | JxStateDefinition | undefined} def
+ * @returns {boolean}
+ */
+export function isPureNamedFormula(
+  def: JxDocumentValue | JxStateDefinition | undefined,
+): def is JxExpressionDef & { parameters: unknown[] } {
+  return isNamedFormulaDef(def) && !operandMutates(def.$expression);
+}
+
+/** The ref schemes a formula body reads that are not the scope it is built in (spec.md §7.4). */
+const OUTSIDE_SCOPE_REF = /^(?:\$args\/|\$reduce\/|\$map\/|window#\/|document#\/|event#\/)/;
+
+/**
+ * Collect into `into` the state key each scope `$ref` in an operand names. A plain-object literal
+ * is a value, not a tree (spec.md §19.2), so nothing inside one is a read.
+ */
+function collectScopeReads(operand: JxExpressionOperand | undefined, into: Set<string>): void {
+  if (Array.isArray(operand)) {
+    for (const item of operand) {
+      collectScopeReads(item, into);
+    }
+    return;
+  }
+  if (operand === undefined || !isNonNullObject(operand)) {
+    return;
+  }
+  if (isRefOperand(operand)) {
+    if (!OUTSIDE_SCOPE_REF.test(operand.$ref)) {
+      // `#/state/x`, `parent#/x` and a bare `x` all resolve in the scope (spec.md §15.4).
+      const path = operand.$ref.replace(/^(?:#\/state\/|parent#\/)/, "");
+      into.add(refSegments(path)[0] ?? "");
+    }
+    return;
+  }
+  if (isNodeOperand(operand)) {
+    const parts = [operand.target, operand.value, operand.initial, operand.default];
+    for (const part of [...parts, ...Object.values(operand.cases ?? {})]) {
+      collectScopeReads(part, into);
+    }
+  }
+}
+
+/**
+ * The state keys a named formula's body reads from the scope it is built in: every `#/state/key`,
+ * `parent#/key` or schemeless `$ref` in it, by the key it names. `$args/`, an iteration context and
+ * a global are not the scope.
+ *
+ * @param {JxExpressionDef} def
+ * @returns {string[]}
+ */
+export function formulaScopeReads(def: JxExpressionDef): string[] {
+  const reads = new Set<string>();
+  collectScopeReads(def.$expression, reads);
+  return [...reads];
+}
+
+/**
+ * The project `state` entries a component inherits (spec.md §13.4): the pure named formulas that
+ * are closed, meaning every scope read in the body names another inherited formula.
+ *
+ * Only a function crosses the component boundary. A formula that reads project data state would
+ * carry that state across with it, so it stays on the page side, and so does anything that calls
+ * it. The project's injected context names (`$site`, `$page`) are never entries of this kind.
+ *
+ * @param {Record<string, JxStateDefinition> | null | undefined} projectState - `project.json`
+ *   `state`
+ * @returns {Record<string, JxStateDefinition>} In the project's order; empty when there are none
+ * @docs framework/concepts/props-and-scope
+ */
+export function inheritableFormulas(
+  projectState: Record<string, JxStateDefinition> | null | undefined,
+): Record<string, JxStateDefinition> {
+  const candidates = new Map<string, JxExpressionDef>();
+  for (const [key, def] of Object.entries(projectState ?? {})) {
+    if (!key.startsWith("$") && isPureNamedFormula(def)) {
+      candidates.set(key, def);
+    }
+  }
+  // Drop what reads outside the set until nothing does: a caller of a dropped formula goes too.
+  let settled = false;
+  while (!settled) {
+    settled = true;
+    for (const [key, def] of candidates) {
+      if (formulaScopeReads(def).some((read) => !candidates.has(read))) {
+        candidates.delete(key);
+        settled = false;
+      }
+    }
+  }
+  return Object.fromEntries(candidates);
+}
+
 // ─── Runtime Evaluation ──────────────────────────────────────────────────────
 
 interface IterCtx {
@@ -526,7 +661,7 @@ function resolveExprRef(ref: string, state: JxScope, event: Event | null, iterCt
     return readPath(state, ref.slice("parent#/".length));
   }
   if (ref.startsWith("window#/")) {
-    return readPath(globalThis.window, ref.slice("window#/".length));
+    return readPath(windowRoot(), ref.slice("window#/".length));
   }
   if (ref.startsWith("document#/")) {
     return readPath(globalThis.document, ref.slice("document#/".length));
@@ -712,14 +847,12 @@ function evaluateNode(
           ...withPageLocale(globalPath, argValues, state),
         );
       }
+      const root = windowRoot();
       /* SAFETY: `isBlessedGlobal` admitted `globalPath`, and every BLESSED_GLOBALS entry without a
          synthetic helper names a standard-library function on `window` (Math.max, JSON.parse, …). */
-      const fn = readPath(globalThis.window, globalPath) as FormulaCallable;
+      const fn = readPath(root, globalPath) as FormulaCallable;
       const lastSlash = globalPath.lastIndexOf("/");
-      const thisArg =
-        lastSlash === -1
-          ? globalThis.window
-          : readPath(globalThis.window, globalPath.slice(0, lastSlash));
+      const thisArg = lastSlash === -1 ? root : readPath(root, globalPath.slice(0, lastSlash));
       return fn.apply(thisArg, argValues);
     }