@jxsuite/compiler 0.1.0 → 0.5.1

package/src/site/site-build.js

@@ -29,11 +29,15 @@ import {
   buildInitialScope,
   isTemplateString,
   evaluateStaticTemplate,
+  preRenderComponentHtml,
+  isComponentFullyStatic,
+  buildComponentCSS,
   DEFAULT_REACTIVITY_SRC,
   DEFAULT_LIT_HTML_SRC,
 } from "../shared.js";
 import { loadCollections, loadContentConfig, resolveCollectionRefs } from "./content-loader.js";
 import { resolvePrototypes } from "./prototype-resolver.js";
+import { compileMarkdown } from "../targets/compile-markdown.js";
 
 /**
  * Build an entire Jx site from a project directory.
@@ -96,10 +100,16 @@ export async function buildSite(projectRoot, options = {}) {
   const componentsDir = resolve(projectRoot, "components");
   /** @type {string[]} */
   const compiledComponentTags = [];
+  /** @type {Map<string, string>} */
+  const preRendered = new Map(); // tagName → innerHTML (default state, fallback)
+  /** @type {Map<string, string>} */
+  const componentCSS = new Map(); // tagName → CSS text
+  /** @type {Map<string, any>} */
+  const componentDefs = new Map(); // tagName → parsed component definition
   if (existsSync(componentsDir)) {
     log("Compiling components...");
-    const componentFiles = readdirSync(componentsDir).filter((/** @type {string} */ f) =>
-      f.endsWith(".json"),
+    const componentFiles = readdirSync(componentsDir).filter(
+      (/** @type {string} */ f) => f.endsWith(".json") || f.endsWith(".md"),
     );
     const componentOutDir = resolve(outDir, "components");
     mkdirSync(componentOutDir, { recursive: true });
@@ -116,6 +126,25 @@ export async function buildSite(projectRoot, options = {}) {
           if (f.tagName) compiledComponentTags.push(f.tagName);
           fileCount++;
         }
+
+        // Pre-render component HTML scaffold and CSS sidecar
+        const doc = componentPath.endsWith(".md")
+          ? (await import("@jxsuite/parser/transpile")).transpileJxMarkdown(
+              readFileSync(componentPath, "utf8"),
+            )
+          : JSON.parse(readFileSync(componentPath, "utf8"));
+        if (doc.tagName) {
+          componentDefs.set(doc.tagName, doc);
+          const innerHTML = preRenderComponentHtml(doc);
+          if (innerHTML) preRendered.set(doc.tagName, innerHTML);
+
+          const css = buildComponentCSS(doc.tagName, doc.style);
+          if (css) {
+            componentCSS.set(doc.tagName, css);
+            writeFileSync(resolve(componentOutDir, `${doc.tagName}.css`), css, "utf8");
+            fileCount++;
+          }
+        }
       } catch (e) {
         const err = /** @type {any} */ (e);
         errors.push(`Error compiling component ${file}: ${err.message}`);
@@ -134,9 +163,24 @@ export async function buildSite(projectRoot, options = {}) {
       log(`  Compiling ${route.urlPattern} ...`);
       const result = await compilePage(route, projectConfig, projectRoot, collections);
 
-      // Inject component scripts if the page references any compiled components
+      // Inject pre-rendered component HTML scaffolding (instance-aware)
+      // Must happen before script injection so we know which tags are fully static
+      /** @type {Set<string>} */
+      let staticTags = new Set();
+      if (componentDefs.size > 0) {
+        const preResult = injectPreRenderedComponents(result.html, preRendered, componentDefs);
+        result.html = preResult.html;
+        staticTags = preResult.staticTags;
+      }
+
+      // Inject component CSS and JS scripts
       if (compiledComponentTags.length > 0) {
-        result.html = injectComponentScripts(result.html, compiledComponentTags);
+        result.html = injectComponentScripts(
+          result.html,
+          compiledComponentTags,
+          componentCSS,
+          staticTags,
+        );
       }
 
       // Determine output path
@@ -145,6 +189,19 @@ export async function buildSite(projectRoot, options = {}) {
       writeFileSync(outPath, result.html, "utf8");
       fileCount++;
 
+      // Write markdown export alongside HTML
+      try {
+        const md = compileMarkdown(result.doc, componentDefs);
+        if (md.content) {
+          const mdPath = outPath.replace(/\.html$/, ".md");
+          writeFileSync(mdPath, md.content, "utf8");
+          fileCount++;
+        }
+      } catch (e) {
+        const err = /** @type {any} */ (e);
+        errors.push(`Error exporting markdown for ${route.urlPattern}: ${err.message}`);
+      }
+
       // Write any additional files (island modules, etc.)
       for (const file of result.files) {
         const filePath = resolve(dirname(outPath), file.path);
@@ -209,11 +266,17 @@ export async function buildSite(projectRoot, options = {}) {
  * @param {any} projectConfig
  * @param {string} projectRoot
  * @param {Map<string, any[]>} [collections]
- * @returns {Promise<{ html: string; files: any[]; serverHandler: string | null }>}
+ * @returns {Promise<{ html: string; files: any[]; serverHandler: string | null; doc: any }>}
  */
 async function compilePage(route, projectConfig, projectRoot, collections = new Map()) {
   // Load the raw page document
-  let pageDoc = JSON.parse(readFileSync(route.sourcePath, "utf8"));
+  let pageDoc;
+  if (route.sourcePath.endsWith(".md")) {
+    const { transpileJxMarkdown } = await import("@jxsuite/parser/transpile");
+    pageDoc = transpileJxMarkdown(readFileSync(route.sourcePath, "utf8"));
+  } else {
+    pageDoc = JSON.parse(readFileSync(route.sourcePath, "utf8"));
+  }
 
   // Resolve layout (wraps page in layout with slot distribution)
   const layoutDoc = resolveLayout(pageDoc, projectConfig, projectRoot);
@@ -278,10 +341,16 @@ async function compilePage(route, projectConfig, projectRoot, collections = new
     pageUrl: route.urlPattern,
   });
 
+  // Merge project-level $media into the layout document so responsive queries are available
+  if (projectConfig.$media) {
+    layoutDoc.$media = { ...projectConfig.$media, ...layoutDoc.$media };
+  }
+
   // Compile the document using the existing compiler
   const result = await compile(layoutDoc, {
     title,
     lang: projectConfig.defaults?.lang ?? "en",
+    projectStyle: projectConfig.style ?? null,
   });
 
   // Post-process: inject merged <head> content into the compiled HTML
@@ -307,7 +376,7 @@ async function compilePage(route, projectConfig, projectRoot, collections = new
     // No server entries — that's fine
   }
 
-  return { html: result.html, files: result.files, serverHandler };
+  return { html: result.html, files: result.files, serverHandler, doc: layoutDoc };
 }
 
 /**
@@ -386,7 +455,13 @@ function resolveDocTemplates(node, scope) {
   if (!node || typeof node !== "object") return;
 
   if (typeof node.innerHTML === "string" && isTemplateString(node.innerHTML)) {
-    node.innerHTML = evaluateStaticTemplate(node.innerHTML, scope) ?? node.innerHTML;
+    const resolved = evaluateStaticTemplate(node.innerHTML, scope);
+    if (resolved != null) {
+      // Encode any remaining `${` as HTML entities so the compile phase won't
+      // re-interpret them as template expressions. After resolution, any `${` in the
+      // result is literal content (e.g., code examples), not an intentional template.
+      node.innerHTML = resolved.replaceAll("${", "&#36;{");
+    }
   }
   if (typeof node.textContent === "string" && isTemplateString(node.textContent)) {
     node.textContent = evaluateStaticTemplate(node.textContent, scope) ?? node.textContent;
@@ -413,20 +488,40 @@ function resolveDocTemplates(node, scope) {
 }
 
 /**
- * Inject component script tags into compiled HTML for any referenced custom elements. Adds an
- * import map and module scripts before </body>.
+ * Inject component script and CSS link tags into compiled HTML for any referenced custom elements.
+ * Adds an import map and module scripts before </body>, and CSS links in <head>.
  *
  * @param {string} html
  * @param {string[]} allComponentTags - All compiled component tag names
+ * @param {Map<string, string>} [cssMap] - TagName → CSS text (for link injection)
+ * @param {Set<string>} [staticTags] - Tags where ALL instances are fully static (skip JS)
  * @returns {string}
  */
-function injectComponentScripts(html, allComponentTags) {
+function injectComponentScripts(
+  html,
+  allComponentTags,
+  cssMap = new Map(),
+  staticTags = new Set(),
+) {
   // Find which components are actually referenced in this page
   const usedTags = allComponentTags.filter(
     (/** @type {string} */ tag) => html.includes(`<${tag}`), // matches <tag> and <tag ...>
   );
   if (usedTags.length === 0) return html;
 
+  // Inject CSS links in <head> for ALL components that have CSS sidecars
+  const cssLinks = usedTags
+    .filter((/** @type {string} */ tag) => cssMap.has(tag))
+    .map((/** @type {string} */ tag) => `<link rel="stylesheet" href="./components/${tag}.css">`)
+    .join("\n  ");
+  if (cssLinks) {
+    html = html.replace("</head>", `  ${cssLinks}\n</head>`);
+  }
+
+  // Only inject JS for components that have non-static instances
+  const jsTags = usedTags.filter((/** @type {string} */ tag) => !staticTags.has(tag));
+  if (jsTags.length === 0) return html;
+
   // Build import map (needed for @vue/reactivity and lit-html)
   const importMap = `<script type="importmap">
   {
@@ -437,9 +532,9 @@ function injectComponentScripts(html, allComponentTags) {
   }
   </script>`;
 
-  const moduleScripts = usedTags
+  const moduleScripts = jsTags
     .map(
-      (/** @type {string} */ tag) => `<script type="module" src="/components/${tag}.js"></script>`,
+      (/** @type {string} */ tag) => `<script type="module" src="./components/${tag}.js"></script>`,
     )
     .join("\n  ");
 
@@ -450,6 +545,74 @@ function injectComponentScripts(html, allComponentTags) {
   return html.replace("</body>", `  ${injection}\n</body>`);
 }
 
+/**
+ * Inject pre-rendered HTML scaffolding into component tags, using instance-specific props.
+ *
+ * @param {string} html
+ * @param {Map<string, string>} preRendered - TagName → default innerHTML (fallback)
+ * @param {Map<string, any>} componentDefs - TagName → parsed component definition
+ * @returns {{ html: string; staticTags: Set<string> }}
+ */
+function injectPreRenderedComponents(html, preRendered, componentDefs) {
+  /** @type {Set<string>} */
+  const staticTags = new Set();
+  /** @type {Map<string, boolean>} */
+  const tagHasNonStaticInstance = new Map();
+
+  for (const [tag] of componentDefs) {
+    // Match both empty tags and tags with inner content (for slotted components)
+    const pattern = new RegExp(`<${tag}(\\s[^>]*?)?>([\\s\\S]*?)</${tag}>`, "g");
+    html = html.replace(pattern, (match, attrsStr, existingInner) => {
+      const attrs = attrsStr ?? "";
+      const doc = componentDefs.get(tag);
+      if (!doc) {
+        // No definition, use default pre-rendered content
+        const fallback = preRendered.get(tag) ?? "";
+        return `<${tag}${attrs}>${fallback}</${tag}>`;
+      }
+
+      // Extract data-jx-props from the attribute string
+      /** @type {Record<string, any> | null} */
+      let props = null;
+      const propsMatch = attrs.match(/\sdata-jx-props="([^"]*)"/);
+      if (propsMatch) {
+        try {
+          props = JSON.parse(
+            propsMatch[1]
+              .replace(/&quot;/g, '"')
+              .replace(/&amp;/g, "&")
+              .replace(/&lt;/g, "<")
+              .replace(/&gt;/g, ">")
+              .replace(/&#39;/g, "'"),
+          );
+        } catch {}
+      }
+
+      // Pre-render with instance-specific props
+      const slotContent = existingInner.trim() || null;
+      const innerHTML = preRenderComponentHtml(doc, props, slotContent);
+
+      const isStatic = isComponentFullyStatic(doc);
+      if (!isStatic) tagHasNonStaticInstance.set(tag, true);
+
+      if (isStatic) {
+        // Strip data-jx-props from attrs for fully static instances
+        let cleanAttrs = attrs.replace(/\s*data-jx-props="[^"]*"/, "");
+        return `<${tag}${cleanAttrs} data-jx-static>${innerHTML}</${tag}>`;
+      } else {
+        return `<${tag}${attrs} data-jx-prerendered>${innerHTML}</${tag}>`;
+      }
+    });
+
+    // Track whether ALL instances of this tag are static
+    if (componentDefs.has(tag) && !tagHasNonStaticInstance.has(tag)) {
+      staticTags.add(tag);
+    }
+  }
+
+  return { html, staticTags };
+}
+
 /**
  * Inject <script type="module"> tags for npm package $elements (cherry-picked component imports).
  * Bare specifiers are resolved to /node_modules/ paths.
@@ -462,7 +625,8 @@ function injectComponentScripts(html, allComponentTags) {
 function injectNpmElementScripts(html, npmElements) {
   const scripts = npmElements
     .map(
-      (/** @type {string} */ spec) => `<script type="module" src="/node_modules/${spec}"></script>`,
+      (/** @type {string} */ spec) =>
+        `<script type="module" src="./node_modules/${spec}"></script>`,
     )
     .join("\n  ");
 

package/src/targets/compile-client.js

@@ -41,7 +41,7 @@ export function compileClient(raw, opts) {
   } = opts;
 
   const context = createCompileContext(raw, null, raw.state ?? {}, raw.$media ?? {});
-  const styleBlock = compileStyles(raw, raw.$media ?? {});
+  const styleBlock = compileStyles(raw, raw.$media ?? {}, opts.projectStyle ?? null);
 
   // Collectors for bindings and handlers
   const counter = { t: 0, s: 0, h: 0, m: 0, sw: 0, l: 0, needsLit: false };
@@ -164,11 +164,11 @@ export function compileClient(raw, opts) {
     reactivitySrc,
   );
 
-  // Build importmap entries
-  const importmapEntries = [`      "@vue/reactivity": "${reactivitySrc}"`];
-  if (counter.needsLit) {
-    importmapEntries.push(`      "lit-html": "${litHtmlSrc}"`);
-  }
+  // Build importmap entries — always include lit-html since compiled custom elements need it
+  const importmapEntries = [
+    `      "@vue/reactivity": "${reactivitySrc}"`,
+    `      "lit-html": "${litHtmlSrc}"`,
+  ];
 
   const html = `<!DOCTYPE html>
 <html lang="en">
@@ -349,7 +349,9 @@ function buildClientNode(def, raw, context, bindings, handlers, counter) {
       inner = "";
     }
   } else if (source.innerHTML) {
-    inner = resolveStaticValue(source.innerHTML, nextContext.scope) ?? "";
+    // resolveStaticValue may return null if innerHTML contains `${` from rendered content
+    // (e.g., code examples) that isn't an actual template expression. Fall back to raw value.
+    inner = resolveStaticValue(source.innerHTML, nextContext.scope) ?? source.innerHTML;
   } else if (
     source.children &&
     typeof source.children === "object" &&

package/src/targets/compile-element.js

@@ -37,7 +37,12 @@ export async function compileElement(sourcePath, opts = {}) {
       filePath = parentDir ? resolve(parentDir, srcPath) : resolve(srcPath);
       if (visited.has(filePath)) return;
       visited.add(filePath);
-      doc = JSON.parse(readFileSync(filePath, "utf8"));
+      if (filePath.endsWith(".md")) {
+        const { transpileJxMarkdown } = await import("@jxsuite/parser/transpile");
+        doc = transpileJxMarkdown(readFileSync(filePath, "utf8"));
+      } else {
+        doc = JSON.parse(readFileSync(filePath, "utf8"));
+      }
     } else {
       doc = srcPath;
       filePath = null;
@@ -288,8 +293,21 @@ export function emitElementModule(doc, className, elementImports) {
 
   // connectedCallback
   lines.push("  connectedCallback() {");
+  // Read $props from data-jx-props attribute (set by compiler for pre-rendered instances)
+  lines.push("    const _pa = this.getAttribute('data-jx-props');");
+  lines.push("    if (_pa) {");
+  lines.push("      try {");
+  lines.push("        const _p = JSON.parse(_pa);");
+  lines.push("        for (const [k, v] of Object.entries(_p)) {");
+  lines.push("          if (k in this.state) this.state[k] = v;");
+  lines.push("        }");
+  lines.push("      } catch {}");
+  lines.push("      this.removeAttribute('data-jx-props');");
+  lines.push("    }");
+  // Merge JS properties set before connection (by parent runtime).
+  // Only check own properties to avoid inherited DOM properties like `title`.
   lines.push("    for (const key of Object.keys(this.state)) {");
-  lines.push("      if (key in this && this[key] !== undefined) {");
+  lines.push("      if (this.hasOwnProperty(key) && this[key] !== undefined) {");
   lines.push("        this.state[key] = this[key];");
   lines.push("      }");
   lines.push("    }");
@@ -333,7 +351,28 @@ export function emitElementModule(doc, className, elementImports) {
       lines.push("    });");
     }
   }
+  const hasSlot = treeHasSlot(doc.children);
+  if (hasSlot) {
+    // Save light DOM children (slotted content) before clearing
+    lines.push(
+      "    const _slotted = Array.from(this.childNodes).filter(n => n.nodeType === 1 || (n.nodeType === 3 && n.textContent.trim()));",
+    );
+  }
+  // Skip clearing innerHTML if content was pre-rendered with correct props
+  lines.push("    if (this.hasAttribute('data-jx-prerendered')) {");
+  lines.push("      this.removeAttribute('data-jx-prerendered');");
+  lines.push("    } else {");
+  lines.push("      this.innerHTML = '';");
+  lines.push("    }");
   lines.push("    this.#dispose = effect(() => render(this.template(), this));");
+  if (hasSlot) {
+    // Replace <slot> placeholder with saved slotted content
+    lines.push("    const _slot = this.querySelector('slot');");
+    lines.push("    if (_slot && _slotted.length > 0) {");
+    lines.push("      for (const n of _slotted) _slot.before(n);");
+    lines.push("      _slot.remove();");
+    lines.push("    }");
+  }
   lines.push("  }");
   lines.push("");
 
@@ -617,3 +656,19 @@ function emitStyleString(styleDef) {
 
   return parts.join("; ");
 }
+
+/**
+ * Check if a children tree contains a `<slot>` element.
+ *
+ * @param {any} children
+ * @returns {boolean}
+ */
+function treeHasSlot(children) {
+  if (!Array.isArray(children)) return false;
+  for (const child of children) {
+    if (!child || typeof child !== "object") continue;
+    if (child.tagName === "slot") return true;
+    if (treeHasSlot(child.children)) return true;
+  }
+  return false;
+}