@jxsuite/compiler 3.1.0 → 4.0.1

package/src/site/dev-command.ts

@@ -2,8 +2,10 @@
  * Dev command — `jx dev` resolves the project's @jxsuite/server dev entry and spawns it under Bun.
  *
  * The compiler cannot depend on @jxsuite/server (the server already depends on the compiler), and
- * the dev server is Bun-native while the jx bin runs under Node — so the command is pure resolution
- * + spawn: the entry module is resolved from the PROJECT's node_modules and executed with Bun.
+ * the dev server is Bun-native while the jx bin runs under Node — so the command is pure
+ * resolution
+ *
+ * - Spawn: the entry module is resolved from the PROJECT's node_modules and executed with Bun.
  *
  * @module dev-command
  */

package/src/site/format-host.ts

@@ -10,7 +10,7 @@ import { readFileSync } from "node:fs";
 import { dirname, isAbsolute, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
-import { buildExtensionRegistry } from "@jxsuite/schema/extension-registry";
+import { buildExtensionRegistry, EXTENSION_MANIFEST } from "@jxsuite/schema/extension-registry";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import type { FormatHostIO, FormatRegistry, ProjectBlock } from "@jxsuite/schema/format-registry";
 import type { ProjectConfig } from "@jxsuite/schema/types";
@@ -75,6 +75,59 @@ export function createNodeFormatIO(projectRoot: string): FormatHostIO {
   };
 }
 
+/**
+ * Where an extension package's manifest resolves from — the two answers `createNodeFormatIO`
+ * merges.
+ */
+export interface ExtensionResolution {
+  /** Resolvable from the PROJECT's own node_modules. */
+  project: boolean;
+  /** Resolvable from the HOST's module graph — `createNodeFormatIO`'s fallback branch. */
+  host: boolean;
+  /** The manifest path from whichever probe answered; the project wins, matching resolution order. */
+  manifestPath?: string;
+}
+
+/**
+ * Split `createNodeFormatIO`'s two-branch resolution into its two ANSWERS.
+ *
+ * The IO deliberately collapses them (project first, then host) because a caller loading a class
+ * only needs the file. A catalogue needs them apart: "the project installed this" and "this host
+ * ships it" are different affordances — install-then-enable versus enable — and a surface that
+ * cannot tell them apart offers the wrong one.
+ *
+ * Probes the MANIFEST rather than the package directory, because the manifest is what the registry
+ * resolves (see `loadExtension`): a package present in node_modules whose `exports` map omits
+ * `./jx-extension.json` is one whose enablement would throw, so it must not read as resolvable.
+ *
+ * @param {string} projectRoot - The project whose node_modules is tried first
+ * @param {string} name - Bare package specifier, e.g. "@jxsuite/parser"
+ * @returns {ExtensionResolution}
+ */
+export function probeExtension(projectRoot: string, name: string): ExtensionResolution {
+  const ref = `${name}/${EXTENSION_MANIFEST}`;
+  let manifestPath: string | undefined;
+
+  let project = false;
+  try {
+    manifestPath = createRequire(resolve(projectRoot, "package.json")).resolve(ref);
+    project = true;
+  } catch {
+    // Not installed in the project. The host probe below decides whether it resolves at all.
+  }
+
+  let host = false;
+  try {
+    const fromHost = createRequire(import.meta.url).resolve(ref);
+    host = true;
+    manifestPath ??= fromHost;
+  } catch {
+    // Not shipped by this host either.
+  }
+
+  return { host, project, ...(manifestPath === undefined ? {} : { manifestPath }) };
+}
+
 /** Build the extension registry for a project from its project.json `extensions` array. */
 export async function buildProjectExtensionRegistry(
   projectRoot: string,

package/src/site/prototype-resolver.ts

@@ -56,8 +56,9 @@ const RESERVED_KEYS = new Set([
  * to a .class.json path via doc.imports
  *
  * The resolver: - Reads the .class.json from disk - Follows $implementation to import the JS module
+ *
  * - Instantiates the class with the config - Calls .resolve() and replaces the state entry with the
- * result
+ *   result
  *
  * @param {JxMutableNode | JxDocument} doc - The page document (mutated in place)
  * @param {{ sourcePath?: string; _pathParams?: Record<string, string> }} route - Route info

package/src/site/site-build.ts

@@ -68,6 +68,7 @@ import type { SiteConnectorSpec, SiteMountSpec } from "../targets/compile-server
 import {
   buildComponentCSS,
   buildInitialScope,
+  buildInstanceScope,
   collectServerEntries,
   collectStyles,
   colorSchemePrePaintScript,
@@ -76,12 +77,14 @@ import {
   isComponentFullyStatic,
   isSingleExpression,
   isTemplateString,
+  liftPropsAttributes,
   preRenderComponentHtml,
   pureSchemeOf,
   renderStaticNode,
+  resolveHostStyle,
   resolveRefValue,
-  resolveStaticValue,
 } from "../shared.ts";
+import type { ComponentPrerenderContext } from "../shared.ts";
 import { resolvePrototypes } from "./prototype-resolver.ts";
 import { transformImageNodes } from "./image-transform.ts";
 import { collectCspSources, emptyCspSources } from "./csp.ts";
@@ -453,11 +456,24 @@ export async function buildSite(
           // The full drive path on Windows, so resolve() then wrote the sidecar back into the
           // Source tree instead of dist.
           const outName = f.tagName ? `${f.tagName}.js` : basename(f.path);
-          writeFileSync(resolve(componentOutDir, outName), f.content, "utf8");
-          if (f.tagName) {
+          /*
+           * Written and recorded ONCE per tag, in first-seen order. `compileElement` returns a
+           * component's `$elements` dependencies as extra files, so a dependency two parents name
+           * arrives here once per parent and once more for its own compile — and
+           * `injectComponentScripts` inlines a tag's stylesheet and loads its module once per
+           * record: three copies of `lcb-icon { display: inline-block }` in one head on a
+           * card → button → icon page (#330). The FIRST position is the one kept, because
+           * equal-specificity component rules cascade by source order and a later duplicate must
+           * not move a sheet that already landed. The write is skipped with the record: every
+           * arrival is the same file compiled with the same options (a fresh `visited` set each
+           * call), so the bytes are identical and a second write only inflates `fileCount`, which
+           * reports files produced rather than writes attempted.
+           */
+          if (!compiledComponentTags.includes(f.tagName)) {
+            writeFileSync(resolve(componentOutDir, outName), f.content, "utf8");
             compiledComponentTags.push(f.tagName);
+            fileCount += 1;
           }
-          fileCount += 1;
         }
 
         // Pre-render component HTML scaffold and CSS sidecar
@@ -2041,27 +2057,23 @@ function expandComponents(
 
   const def = componentDefs.get(node.tagName as string);
   if (def) {
-    // JSON-authored instances pass props as literal `props.*` attribute keys (markdown directives
-    // Are normalized to $props by the parser's expandDotPaths, but JSON is parsed verbatim).
-    // Lift them into $props so the pre-render sees them, and strip them from attributes so they
-    // Don't leak into the emitted HTML. Values stay raw strings — no coercion, matching the
-    // Markdown path and the runtime's $props semantics. Explicit $props wins on key conflicts.
+    // Literal `props.*` attribute keys become $props (`liftPropsAttributes` says why) and leave the
+    // Attributes, so they do not reach the emitted HTML. Explicit $props wins on key conflicts.
     if (node.attributes) {
-      let lifted: NonNullable<JxElement["$props"]> | null = null;
-      for (const [key, value] of Object.entries(node.attributes)) {
-        if (key.startsWith("props.") && key.length > "props.".length) {
-          lifted ??= {};
-          // JxAttributeValue is JSON-representable (primitives or a $ref object), so the
-          // Narrowing to JsonValue is sound.
-          lifted[key.slice("props.".length)] = value as JsonValue;
-          delete node.attributes[key];
-        }
-      }
+      const { lifted, rest } = liftPropsAttributes(node.attributes);
       if (lifted) {
+        node.attributes = rest;
         node.$props = { ...lifted, ...node.$props };
       }
     }
 
+    /*
+     * Slotted children are rendered with NO component registry: this walk is bottom-up, so any
+     * instance among them was expanded a moment ago and now carries its markup as `innerHTML` and
+     * no `$props`. Expanding it again would render the definition's defaults over the props it
+     * was given. Instances written inside `def` itself are another matter — those are reached
+     * below, through `preRenderComponentHtml`, with `node` as the first frame of the path.
+     */
     const slotContent =
       Array.isArray(node.children) && node.children.length > 0
         ? node.children
@@ -2081,7 +2093,15 @@ function expandComponents(
      * render them twice.
      */
     const shadow = resolveShadowMode(def, defaults);
-    const innerHTML = preRenderComponentHtml(def, node.$props || null, shadow ? null : slotContent);
+    const props = node.$props || null;
+    // This instance is the first frame of the path, so a definition that names itself is reported
+    // At the first nesting rather than after the stack overflows.
+    const context: ComponentPrerenderContext = {
+      componentDefs,
+      defaults,
+      path: [{ key: JSON.stringify(props ?? {}), tag: node.tagName as string }],
+    };
+    const innerHTML = preRenderComponentHtml(def, props, shadow ? null : slotContent, context);
     const isStatic = isComponentFullyStatic(def);
 
     /*
@@ -2097,26 +2117,20 @@ function expandComponents(
       : innerHTML;
     delete node.children;
 
-    // Resolve template-string host styles with props (per-instance values like background-image)
-    if (def.style && node.$props) {
-      const stateDefs: Record<string, JxStateDefinition> = { ...def.state };
-      for (const [key, value] of Object.entries(node.$props)) {
-        stateDefs[key] =
-          key in stateDefs ? (value as JxStateDefinition) : (value as JxStateDefinition);
-      }
-      const scope = buildInitialScope(stateDefs, null);
-      const resolvedStyle: Record<string, unknown> = {};
-      for (const [prop, value] of Object.entries(def.style)) {
-        if (typeof value === "string" && isTemplateString(value)) {
-          const resolved = resolveStaticValue(value, scope);
-          if (resolved != null) {
-            resolvedStyle[prop] = resolved;
-          }
-        }
-      }
-      if (Object.keys(resolvedStyle).length > 0) {
-        node.style = { ...node.style, ...resolvedStyle } as JxStyle;
-      }
+    /*
+     * Resolve template-string host styles against the instance (per-instance values like
+     * background-image). The page's style pass gives the result a class rule; a nested instance
+     * gets the same values inline, from the same resolver (`renderComponentInstance` in shared.ts).
+     *
+     * Resolved whether or not the instance passes props: a template declaration is a reactive one
+     * and `pushStyleRules` drops it from the component stylesheet, so the value resolved here is
+     * the ONLY place it reaches a static page. This used to be guarded on `$props`, which left an
+     * instance that took the definition's defaults with no host style at all — no size, no mask —
+     * while the same instance one level down had them.
+     */
+    const resolvedStyle = resolveHostStyle(def.style, buildInstanceScope(def, props));
+    if (Object.keys(resolvedStyle).length > 0) {
+      node.style = { ...node.style, ...resolvedStyle } as JxStyle;
     }
 
     /*

package/src/site/validate-command.ts

@@ -22,6 +22,11 @@ import { createRequire } from "node:module";
 import { join, relative, resolve } from "node:path";
 import { generateClassSchema } from "@jxsuite/schema";
 import { validateProjectFile } from "@jxsuite/schema/validate-project";
+import { findA11yDefects } from "@jxsuite/schema/a11y";
+import { findDialogDefects } from "@jxsuite/schema/dialogs";
+import { findPopoverDefects, overlayScopeFor } from "@jxsuite/schema/overlays";
+import type { OverlayScope } from "@jxsuite/schema/overlays";
+import type { JxElement } from "@jxsuite/schema/types";
 import { buildProjectExtensionRegistry } from "./format-host.ts";
 import { loadProjectConfig } from "./site-loader.ts";
 import { readBundledProjectSchemas } from "./schema-command.ts";
@@ -46,8 +51,36 @@ export interface ProjectTreeIssue {
   errors: unknown[];
 }
 
+/**
+ * One overlay, dialog or accessibility finding in a document — `jx validate`'s rendering of the
+ * lints Studio files as Problems (spec §8.7, §8.8). Advisory by default: a lint is a judgement
+ * about a document that is well-formed, so it never makes the tree INVALID unless `strict` asks it
+ * to.
+ */
+export interface ProjectTreeLintFinding {
+  /** Project-relative file path. */
+  file: string;
+  /** The node's path inside the document. */
+  path: (string | number)[];
+  /** Which lint: `popover`, `dialog` or `accessibility`. */
+  source: "popover" | "dialog" | "accessibility";
+  rule: string;
+  message: string;
+  detail: string;
+  severity: "error" | "warn";
+  /** The WCAG success criterion, for accessibility findings. */
+  criterion?: string;
+}
+
+export interface ValidateProjectTreeOptions {
+  /** Fail the tree on a lint ERROR as well as on a schema error. Warnings never fail it. */
+  strict?: boolean;
+}
+
 export interface ProjectTreeValidationResult {
   valid: boolean;
+  /** Every lint finding, whatever `valid` says. */
+  lint: ProjectTreeLintFinding[];
   /** Number of files checked across all five walks. */
   checked: number;
   issues: ProjectTreeIssue[];
@@ -91,9 +124,11 @@ async function loadAjv(): Promise<{ Ajv: AjvCtor; addFormats: AddFormatsFn }> {
  */
 export async function validateProjectTree(
   projectRoot: string,
+  options: ValidateProjectTreeOptions = {},
 ): Promise<ProjectTreeValidationResult> {
   const root = resolve(projectRoot);
   const issues: ProjectTreeIssue[] = [];
+  const lint: ProjectTreeLintFinding[] = [];
   let checked = 0;
 
   /* 1. Committed entry documents must be self-contained (the editor-resolution guarantee). This
@@ -120,7 +155,7 @@ export async function validateProjectTree(
     }
   }
   if (issues.length > 0) {
-    return { checked, issues, valid: false };
+    return { checked, issues, lint, valid: false };
   }
 
   // 2. project.json against the generated entry schema.
@@ -137,6 +172,21 @@ export async function validateProjectTree(
   const docAjv = new Ajv({ allErrors: true, ownProperties: true, strict: false });
   addFormats(docAjv);
   const validateDoc = docAjv.compile(documentSchema);
+  /* The project's own element definitions, so the overlay rules judge a custom element as what it
+     renders. A component IS a popover when its definition declares one, and a component FORWARDS
+     invocation when it observes the four invoker attributes — neither fact is visible in the page
+     that uses it, so without this the CLI reports a target mismatch on correct markup that the
+     studio, which passes the same scope, calls clean. */
+  const scope = overlayScopeFor(
+    walkClassFiles(root).flatMap((file) => {
+      try {
+        return [JSON.parse(readFileSync(file, "utf8")) as JxElement];
+      } catch {
+        // A malformed definition is reported by the class-schema pass below, not here.
+        return [];
+      }
+    }),
+  );
   for (const dir of DOCUMENT_DIRS) {
     for (const file of walkJsonFiles(resolve(root, dir))) {
       if (file.endsWith(".class.json")) {
@@ -144,7 +194,10 @@ export async function validateProjectTree(
       }
       checked += 1;
       const doc = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>;
-      if (!validateDoc(doc)) {
+      if (validateDoc(doc)) {
+        // Only a well-formed document is judged; a schema error is the report for the rest.
+        lint.push(...lintDocument(doc as JxElement, relative(root, file), scope));
+      } else {
         issues.push({ errors: validateDoc.errors ?? [], file: relative(root, file) });
       }
     }
@@ -191,7 +244,51 @@ export async function validateProjectTree(
     }
   }
 
-  return { checked, issues, valid: issues.length === 0 };
+  const fatalLint = options.strict === true && lint.some((finding) => finding.severity === "error");
+  return { checked, issues, lint, valid: issues.length === 0 && !fatalLint };
+}
+
+/** The three lints over one document, as findings that name their file. */
+function lintDocument(doc: JxElement, file: string, scope: OverlayScope): ProjectTreeLintFinding[] {
+  const findings: ProjectTreeLintFinding[] = [];
+  for (const defect of findPopoverDefects(doc, scope)) {
+    findings.push({ ...pick(defect), file, source: "popover" });
+  }
+  for (const defect of findDialogDefects(doc, scope)) {
+    findings.push({ ...pick(defect), file, source: "dialog" });
+  }
+  for (const defect of findA11yDefects(doc)) {
+    findings.push({ ...pick(defect), criterion: defect.criterion, file, source: "accessibility" });
+  }
+  return findings;
+}
+
+/** The fields every defect shape shares. */
+function pick(defect: {
+  rule: string;
+  path: (string | number)[];
+  message: string;
+  detail: string;
+  severity: "error" | "warn";
+}): Pick<ProjectTreeLintFinding, "rule" | "path" | "message" | "detail" | "severity"> {
+  return {
+    detail: defect.detail,
+    message: defect.message,
+    path: defect.path,
+    rule: defect.rule,
+    severity: defect.severity,
+  };
+}
+
+/** One line per lint finding, for the CLI: `file: severity: message [source/rule, WCAG n]`. */
+export function formatProjectTreeLint(result: ProjectTreeValidationResult): string[] {
+  return result.lint.map((finding) => {
+    const cite =
+      finding.criterion === undefined
+        ? `${finding.source}/${finding.rule}`
+        : `${finding.source}/${finding.rule}, WCAG ${finding.criterion}`;
+    return `${finding.file}: ${finding.severity}: ${finding.message} [${cite}]`;
+  });
 }
 
 /**

package/src/targets/compile-client.ts

@@ -13,6 +13,9 @@
 
 import { RESERVED_KEYS, camelToKebab } from "@jxsuite/runtime";
 import {
+  ATTR_HELPER,
+  attrHelperSource,
+  booleanAttrValue,
   DEFAULT_LIT_HTML_SRC,
   DEFAULT_REACTIVITY_SRC,
   buildAttrs,
@@ -675,10 +678,24 @@ function emitLitMapTemplate(def: JxMutableNode | undefined, preformatted = false
   // Attributes object
   if (def.attributes && typeof def.attributes === "object") {
     for (const [k, v] of Object.entries(def.attributes)) {
-      attrs +=
-        typeof v === "string" && isTemplateString(v)
-          ? ` ${k}="${mapRefsToLit(v)}"`
-          : ` ${k}="${escapeHtml(String(v))}"`;
+      if (typeof v === "string" && isTemplateString(v)) {
+        attrs += ` ${k}="${mapRefsToLit(v)}"`;
+        continue;
+      }
+      /* A boolean is the attribute's PRESENCE or its text depending on the family its NAME puts it
+         in — `booleanAttrValue` owns that judgement, and the static emitter in `shared.ts` and the
+         runtime's `applyAttributes` both defer to it, so a prerendered page cannot change meaning
+         as it hydrates (spec.md §8.3). Stringifying here emitted `open="false"`, which HTML reads
+         by presence and therefore as an OPEN element: the author wrote "closed" and the page
+         rendered open. */
+      if (typeof v === "boolean") {
+        const text = booleanAttrValue(k, v);
+        if (text !== null) {
+          attrs += text === "" ? ` ${k}` : ` ${k}="${escapeHtml(text)}"`;
+        }
+        continue;
+      }
+      attrs += ` ${k}="${escapeHtml(String(v))}"`;
     }
   }
 
@@ -884,7 +901,9 @@ function emitClientModule(
   }
 
   // State — reactive state
-  lines.push("", "const state = reactive({");
+  /* The boolean-attribute rule, inlined because this module loads with `@vue/reactivity` and
+     nothing else — see `attrHelperSource`. The hydration script below is its only caller. */
+  lines.push("", attrHelperSource(), "", "const state = reactive({");
   for (const [key, val] of stateEntries) {
     /*
      * State keys come from the document, so `{"user.name": 1}` is legal input. Pasting one raw as
@@ -960,7 +979,14 @@ function emitClientModule(
   lines.push(
     "          effect(() => { el.style[parts[1]] = bind[key](); });",
     "        } else if (parts[0] === 'attr' && parts.length > 1) {",
-    "          effect(() => { el.setAttribute(parts[1], bind[key]()); });",
+    // 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. Same decision as the
+    // Runtime's `applyAttributes`, through the same inlined rule — see `attrHelperSource`.
+    "          effect(() => {",
+    `            const _t = ${ATTR_HELPER}(parts[1], bind[key]());`,
+    "            if (_t === null) { el.removeAttribute(parts[1]); }",
+    "            else { el.setAttribute(parts[1], _t); }",
+    "          });",
     "        } else {",
     "          const prop = parts[0].replace(/-([a-z])/g, (_, c) => c.toUpperCase());",
     "          effect(() => { el[prop] = bind[key](); });",

package/src/targets/compile-element.ts

@@ -7,6 +7,9 @@
 
 import { RESERVED_KEYS, camelToKebab } from "@jxsuite/runtime";
 import {
+  ATTR_HELPER,
+  attrHelperSource,
+  booleanAttrValue,
   PREFORMATTED_TAGS,
   collectStyles,
   compileExpression,
@@ -405,7 +408,11 @@ export function emitElementModule(
 
   lines.push(
     `import { reactive, computed, effect, stop } from '@vue/reactivity';`,
-    `import { render, html } from 'lit-html';`,
+    /* `nothing` is what REMOVES an attribute in a lit template, and it is the only way to express a
+       false presence attribute: writing `open="false"` produces an OPEN <details>. See
+       `attrHelperSource`. */
+    `import { render, html, nothing } from 'lit-html';`,
+    attrHelperSource(),
   );
 
   /*
@@ -1037,10 +1044,26 @@ ${no}
 
   if (def.attributes) {
     for (const [key, val] of Object.entries(def.attributes)) {
+      /* Every branch here answers the same question the runtime's `applyAttributes` answers, and
+         must answer it the same way or a prerendered page changes meaning as it hydrates (spec.md
+         §8.3). A LITERAL boolean is decided now; a BOUND one cannot be, because its resolved type
+         is not known until the effect runs — so it goes through the emitted helper, whose `null`
+         becomes lit's `nothing` and takes the attribute off. */
       if (val && typeof val === "object" && isRef(val)) {
-        parts.push(`${key}="\${${refToExpr(val.$ref)}}"`);
+        parts.push(`${key}="\${${ATTR_HELPER}('${key}', ${refToExpr(val.$ref)}) ?? nothing}"`);
+      } else if (typeof val === "string" && isWholeTemplate(val)) {
+        parts.push(
+          `${key}="\${${ATTR_HELPER}('${key}', ${toLitExpr(val).slice(2, -1)}) ?? nothing}"`,
+        );
       } else if (typeof val === "string" && val.includes("${")) {
+        /* A template with literal text around it — `"page ${n}"` — is a string by construction, so
+           there is no boolean to decide and wrapping it would only add a call. */
         parts.push(`${key}="${toLitExpr(val)}"`);
+      } else if (typeof val === "boolean") {
+        const text = booleanAttrValue(key, val);
+        if (text !== null) {
+          parts.push(text === "" ? key : `${key}="${text}"`);
+        }
       } else {
         parts.push(`${key}="${val}"`);
       }
@@ -1404,6 +1427,20 @@ function toLitExpr(str: string) {
   return str.replaceAll("state.", "s.");
 }
 
+/**
+ * Whether the whole attribute value is ONE `${…}` and nothing else.
+ *
+ * Only such a value can resolve to a boolean — anything with literal text around the expression is
+ * a string by construction — so this is the test for whether the boolean decision has to be
+ * deferred to runtime.
+ *
+ * @param {string} str
+ * @returns {boolean}
+ */
+function isWholeTemplate(str: string): boolean {
+  return str.startsWith("${") && str.endsWith("}") && !str.slice(2).includes("${");
+}
+
 /**
  * Convert textContent value to lit-html text content. Bug fix: handles $ref objects, which
  * previously produced [object Object].