@jxsuite/compiler 0.19.0 → 0.21.0

package/src/targets/compile-markdown.js

@@ -65,10 +65,10 @@ const WRAPPER_TAGS = new Set([
  * Convert a Jx node to an array of mdast nodes. Returns an array because wrapper unwrapping can
  * produce multiple children.
  *
- * @param {any} node
- * @param {Map<string, any>} componentDefs
- * @param {any} [scope] - Current resolution scope
- * @returns {any[]}
+ * @param {JxElement | string} node
+ * @param {Map<string, JxElement>} componentDefs
+ * @param {Record<string, unknown> | null} [scope] - Current resolution scope
+ * @returns {MdastNode[]}
  */
 function nodeToMdast(node, componentDefs, scope) {
   // Bare text
@@ -153,8 +153,8 @@ function nodeToMdast(node, componentDefs, scope) {
       return [{ type: "inlineCode", value: text ?? "" }];
 
     case "link": {
-      const href = node.attributes?.href ?? "";
-      const title = node.attributes?.title ?? null;
+      const href = String(node.attributes?.href ?? "");
+      const title = /** @type {string | null} */ (node.attributes?.title ?? null);
       const children =
         text != null
           ? [{ type: "text", value: text }]
@@ -163,9 +163,9 @@ function nodeToMdast(node, componentDefs, scope) {
     }
 
     case "image": {
-      const src = node.attributes?.src ?? "";
-      const alt = node.attributes?.alt ?? "";
-      const title = node.attributes?.title ?? null;
+      const src = String(node.attributes?.src ?? "");
+      const alt = String(node.attributes?.alt ?? "");
+      const title = /** @type {string | null} */ (node.attributes?.title ?? null);
       return [{ type: "image", url: src, alt, title }];
     }
 
@@ -199,10 +199,16 @@ function nodeToMdast(node, componentDefs, scope) {
     case "code": {
       // pre > code → fenced code block
       const codeChild = Array.isArray(node.children)
-        ? node.children.find((/** @type {any} */ c) => c?.tagName === "code")
+        ? node.children.find(
+            (/** @type {JxElement | string} */ c) =>
+              /** @type {JxMutableNode} */ (c)?.tagName === "code",
+          )
         : null;
-      const value = codeChild?.textContent ?? text ?? "";
-      const lang = codeChild?.className?.replace("language-", "") ?? null;
+      const value = /** @type {JxElement | undefined} */ (codeChild)?.textContent ?? text ?? "";
+      const lang = /** @type {JxElement | undefined} */ (codeChild)?.className?.replace(
+        "language-",
+        "",
+      ) ?? null;
       return [{ type: "code", lang, value }];
     }
 
@@ -250,10 +256,10 @@ function isInlineType(type) {
 /**
  * Convert a node's children to mdast nodes (block context).
  *
- * @param {any} node
- * @param {Map<string, any>} componentDefs
- * @param {any} [scope]
- * @returns {any[]}
+ * @param {JxElement} node
+ * @param {Map<string, JxElement>} componentDefs
+ * @param {Record<string, unknown> | null} [scope]
+ * @returns {MdastNode[]}
  */
 function convertChildren(node, componentDefs, scope) {
   if (node.textContent != null) {
@@ -262,16 +268,18 @@ function convertChildren(node, componentDefs, scope) {
     return [];
   }
   if (!Array.isArray(node.children)) return [];
-  return node.children.flatMap((/** @type {any} */ c) => nodeToMdast(c, componentDefs, scope));
+  return node.children.flatMap((/** @type {JxElement | string} */ c) =>
+    nodeToMdast(c, componentDefs, scope),
+  );
 }
 
 /**
  * Convert children in inline context — same as convertChildren but for inline content.
  *
- * @param {any} node
- * @param {Map<string, any>} componentDefs
- * @param {any} [scope]
- * @returns {any[]}
+ * @param {JxElement} node
+ * @param {Map<string, JxElement>} componentDefs
+ * @param {Record<string, unknown> | null} [scope]
+ * @returns {MdastNode[]}
  */
 function convertChildrenInline(node, componentDefs, scope) {
   if (node.textContent != null) {
@@ -280,7 +288,9 @@ function convertChildrenInline(node, componentDefs, scope) {
     return [];
   }
   if (!Array.isArray(node.children)) return [];
-  return node.children.flatMap((/** @type {any} */ c) => nodeToMdast(c, componentDefs, scope));
+  return node.children.flatMap((/** @type {JxElement | string} */ c) =>
+    nodeToMdast(c, componentDefs, scope),
+  );
 }
 
 // ─── Component inlining ─────────────────────────────────────────────────────
@@ -288,10 +298,10 @@ function convertChildrenInline(node, componentDefs, scope) {
 /**
  * Inline a custom element by resolving its component definition.
  *
- * @param {any} node - The element instance (with $props, children, etc.)
+ * @param {JxElement} node - The element instance (with $props, children, etc.)
  * @param {string} tag - The tagName
- * @param {Map<string, any>} componentDefs
- * @returns {any[]}
+ * @param {Map<string, JxElement>} componentDefs
+ * @returns {MdastNode[]}
  */
 function inlineComponent(node, tag, componentDefs) {
   const def = componentDefs.get(tag);
@@ -314,10 +324,10 @@ function inlineComponent(node, tag, componentDefs) {
       ) {
         stateDefs[key] = { ...existing, default: value };
       } else {
-        stateDefs[key] = value;
+        stateDefs[key] = /** @type {JxStateDefinition} */ (value);
       }
     } else {
-      stateDefs[key] = value;
+      stateDefs[key] = /** @type {JxStateDefinition} */ (value);
     }
   }
 
@@ -331,10 +341,15 @@ function inlineComponent(node, tag, componentDefs) {
 
   // Convert to mdast, passing instance's own children as potential slot content
   const instanceChildren = node.children;
-  return resolved.flatMap((/** @type {any} */ child) => {
+  return resolved.flatMap((/** @type {JxElement | string} */ child) => {
     // Replace slot elements with instance children
-    if (child?.tagName === "slot" && Array.isArray(instanceChildren)) {
-      return instanceChildren.flatMap((/** @type {any} */ c) => nodeToMdast(c, componentDefs));
+    if (
+      /** @type {JxMutableNode} */ (child)?.tagName === "slot" &&
+      Array.isArray(instanceChildren)
+    ) {
+      return instanceChildren.flatMap((/** @type {JxElement | string} */ c) =>
+        nodeToMdast(c, componentDefs),
+      );
     }
     return nodeToMdast(child, componentDefs, scope);
   });
@@ -343,35 +358,37 @@ function inlineComponent(node, tag, componentDefs) {
 /**
  * Deep-resolve template expressions in a node tree.
  *
- * @param {any} nodes
- * @param {any} scope
- * @returns {any[]}
+ * @param {(JxElement | string)[]} nodes
+ * @param {Record<string, unknown>} scope
+ * @returns {(JxElement | string)[]}
  */
 function deepResolve(nodes, scope) {
   if (!Array.isArray(nodes)) return [];
-  return nodes.map((/** @type {any} */ node) => resolveNode(node, scope));
+  return nodes.map((/** @type {JxElement | string} */ node) => resolveNode(node, scope));
 }
 
 /**
  * Resolve template expressions in a single node.
  *
- * @param {any} node
- * @param {any} scope
- * @returns {any}
+ * @param {JxElement | string} node
+ * @param {Record<string, unknown>} scope
+ * @returns {JxElement | string}
  */
 function resolveNode(node, scope) {
   if (typeof node === "string") {
-    return isTemplateString(node) ? (evaluateStaticTemplate(node, scope) ?? node) : node;
+    return isTemplateString(node) ? String(evaluateStaticTemplate(node, scope) ?? node) : node;
   }
   if (!node || typeof node !== "object") return node;
 
   const result = { ...node };
 
   if (typeof result.textContent === "string" && isTemplateString(result.textContent)) {
-    result.textContent = evaluateStaticTemplate(result.textContent, scope) ?? result.textContent;
+    result.textContent = String(
+      evaluateStaticTemplate(result.textContent, scope) ?? result.textContent,
+    );
   }
   if (typeof result.innerHTML === "string" && isTemplateString(result.innerHTML)) {
-    result.innerHTML = evaluateStaticTemplate(result.innerHTML, scope) ?? result.innerHTML;
+    result.innerHTML = String(evaluateStaticTemplate(result.innerHTML, scope) ?? result.innerHTML);
   }
   if (result.attributes) {
     result.attributes = { ...result.attributes };
@@ -393,23 +410,23 @@ function resolveNode(node, scope) {
 /**
  * Expand a $prototype: "Array" descriptor into concrete mdast nodes.
  *
- * @param {any} arrayDef
- * @param {Map<string, any>} componentDefs
- * @param {any} [scope]
- * @returns {any[]}
+ * @param {JxElement} arrayDef
+ * @param {Map<string, JxElement>} componentDefs
+ * @param {Record<string, unknown> | null} [scope]
+ * @returns {MdastNode[]}
  */
 function expandArray(arrayDef, componentDefs, scope) {
-  const itemsRef = arrayDef.items?.$ref;
+  const itemsRef = /** @type {JxMutableNode} */ (arrayDef).items?.$ref;
   if (!itemsRef || !scope) return [];
 
   // Resolve the items array from scope
   const items = resolveRef(itemsRef, scope);
   if (!Array.isArray(items)) return [];
 
-  const mapTemplate = arrayDef.map;
+  const mapTemplate = /** @type {JxMutableNode} */ (arrayDef).map;
   if (!mapTemplate) return [];
 
-  return items.flatMap((/** @type {any} */ item, /** @type {number} */ index) => {
+  return items.flatMap((/** @type {JxMutableNode} */ item, /** @type {number} */ index) => {
     // Create a scope with $map values
     const mapScope = Object.create(scope);
     mapScope.item = item;
@@ -424,8 +441,8 @@ function expandArray(arrayDef, componentDefs, scope) {
 /**
  * Resolve $map/ references in a map template node.
  *
- * @param {any} node
- * @param {any} item
+ * @param {JxMutableNode} node
+ * @param {Record<string, unknown>} item
  * @returns {any}
  */
 function resolveMapNode(node, item) {
@@ -436,8 +453,8 @@ function resolveMapNode(node, item) {
 
   // Resolve $ref values
   for (const [key, value] of Object.entries(result)) {
-    if (value && typeof value === "object" && value.$ref) {
-      const ref = value.$ref;
+    if (value && typeof value === "object" && /** @type {JxMutableNode} */ (value).$ref) {
+      const ref = /** @type {string} */ (/** @type {JxMutableNode} */ (value).$ref);
       if (ref.startsWith("$map/")) {
         const path = ref.slice("$map/".length);
         result[key] = resolvePath(
@@ -457,7 +474,9 @@ function resolveMapNode(node, item) {
   }
 
   if (Array.isArray(result.children)) {
-    result.children = result.children.map((/** @type {any} */ c) => resolveMapNode(c, item));
+    result.children = result.children.map((c) =>
+      resolveMapNode(/** @type {JxMutableNode} */ (/** @type {unknown} */ (c)), item),
+    );
   }
 
   return result;
@@ -466,13 +485,13 @@ function resolveMapNode(node, item) {
 /**
  * Resolve a dot/slash-separated path on an object.
  *
- * @param {any} obj
+ * @param {unknown} obj
  * @param {string} path
  * @returns {any}
  */
 function resolvePath(obj, path) {
   const parts = path.split(/[/.]/);
-  let current = obj;
+  let current = /** @type {JxMutableNode} */ (obj);
   for (const part of parts) {
     if (current == null) return undefined;
     current = current[part];
@@ -484,8 +503,8 @@ function resolvePath(obj, path) {
  * Resolve a $ref string against a scope.
  *
  * @param {string} ref
- * @param {any} scope
- * @returns {any}
+ * @param {Record<string, unknown>} scope
+ * @returns {unknown}
  */
 function resolveRef(ref, scope) {
   if (ref.startsWith("#/state/")) {
@@ -499,10 +518,10 @@ function resolveRef(ref, scope) {
 /**
  * Convert a table element to mdast table node.
  *
- * @param {any} node
- * @param {Map<string, any>} componentDefs
- * @param {any} [scope]
- * @returns {any[]}
+ * @param {JxElement} node
+ * @param {Map<string, JxElement>} componentDefs
+ * @param {Record<string, unknown> | null} [scope]
+ * @returns {MdastNode[]}
  */
 function convertTable(node, componentDefs, scope) {
   // Flatten thead/tbody wrappers to get rows
@@ -516,8 +535,8 @@ function convertTable(node, componentDefs, scope) {
 /**
  * Resolve text content, handling template strings if a scope is available.
  *
- * @param {any} value
- * @param {any} [scope]
+ * @param {unknown} value
+ * @param {Record<string, unknown> | null} [scope]
  * @returns {string | null}
  */
 function resolveText(value, scope) {
@@ -539,10 +558,10 @@ function resolveText(value, scope) {
  * markdown content.
  *
  * @param {string} html
- * @returns {any[]}
+ * @returns {MdastNode[]}
  */
 function htmlToMdast(html) {
-  /** @type {any[]} */
+  /** @type {MdastNode[]} */
   const nodes = [];
 
   // Simple top-level block parser
@@ -594,7 +613,7 @@ function splitHtmlBlocks(html) {
  * Parse a single HTML element string into mdast node(s).
  *
  * @param {string} html
- * @returns {any[] | null}
+ * @returns {MdastNode[] | null}
  */
 function parseHtmlElement(html) {
   // Heading
@@ -679,10 +698,10 @@ function parseHtmlElement(html) {
  * Parse inline HTML content to mdast inline nodes.
  *
  * @param {string} html
- * @returns {any[]}
+ * @returns {MdastNode[]}
  */
 function parseInlineHtml(html) {
-  /** @type {any[]} */
+  /** @type {MdastNode[]} */
   const nodes = [];
   let pos = 0;
 
@@ -813,10 +832,10 @@ function findMatchingClose(html, start, tag) {
  * Parse <li> elements from list HTML.
  *
  * @param {string} html
- * @returns {any[]}
+ * @returns {MdastNode[]}
  */
 function parseListItems(html) {
-  /** @type {any[]} */
+  /** @type {MdastNode[]} */
   const items = [];
   const liPattern = /<li(?:\s[^>]*)?>([\s\S]*?)<\/li>/gi;
   let m;
@@ -835,16 +854,16 @@ function parseListItems(html) {
  * Parse an HTML table to mdast table node.
  *
  * @param {string} html
- * @returns {any[]}
+ * @returns {MdastNode[]}
  */
 function parseHtmlTable(html) {
-  /** @type {any[]} */
+  /** @type {MdastNode[]} */
   const rows = [];
   const trPattern = /<tr(?:\s[^>]*)?>([\s\S]*?)<\/tr>/gi;
   let m;
   while ((m = trPattern.exec(html)) !== null) {
     const cellPattern = /<(?:th|td)(?:\s[^>]*)?>([\s\S]*?)<\/(?:th|td)>/gi;
-    /** @type {any[]} */
+    /** @type {MdastNode[]} */
     const cells = [];
     let c;
     while ((c = cellPattern.exec(m[1])) !== null) {
@@ -888,8 +907,8 @@ function decodeHtmlEntities(str) {
 /**
  * Compile a fully-resolved Jx document to clean markdown.
  *
- * @param {any} doc - Resolved Jx document (post layout, context, prototypes, templates)
- * @param {Map<string, any>} [componentDefs] - Component definitions for inlining
+ * @param {JxDocument} doc - Resolved Jx document (post layout, context, prototypes, templates)
+ * @param {Map<string, JxElement>} [componentDefs] - Component definitions for inlining
  * @returns {{ content: string }}
  */
 export function compileMarkdown(doc, componentDefs = new Map()) {
@@ -901,14 +920,14 @@ export function compileMarkdown(doc, componentDefs = new Map()) {
   const scope = doc.state ? buildInitialScope(doc.state, null) : null;
 
   // Convert to mdast
-  const mdastChildren = doc.children.flatMap((/** @type {any} */ child) =>
+  const mdastChildren = doc.children.flatMap((/** @type {JxElement | string} */ child) =>
     nodeToMdast(child, componentDefs, scope),
   );
 
   // Clean up: ensure block-level structure (no bare inline nodes at root)
-  /** @type {any[]} */
+  /** @type {MdastNode[]} */
   const cleaned = [];
-  /** @type {any[]} */
+  /** @type {MdastNode[]} */
   let inlineBuf = [];
 
   const flushInline = () => {
@@ -928,7 +947,9 @@ export function compileMarkdown(doc, componentDefs = new Map()) {
   }
   flushInline();
 
-  const mdast = /** @type {any} */ ({ type: "root", children: cleaned });
+  const mdast = /** @type {import("mdast").Root} */ (
+    /** @type {unknown} */ ({ type: "root", children: cleaned })
+  );
 
   const md = unified()
     .use(remarkGfm)

package/src/targets/compile-server.js

@@ -24,7 +24,7 @@ import { collectServerEntries } from "../shared.js";
  */
 export async function compileServer(sourcePath, opts = {}) {
   const { baseUrl = "/_jx/server" } = opts;
-  const doc = await $RefParser.dereference(sourcePath);
+  const doc = /** @type {JxElement} */ (await $RefParser.dereference(sourcePath));
   const entries = collectServerEntries(doc);
   if (entries.length === 0) return null;
 

package/src/targets/compile-static.js

@@ -18,15 +18,20 @@ import { emitElementModule } from "./compile-element.js";
 /**
  * Compile a static document to HTML, with dynamic subtrees as islands.
  *
- * @param {any} raw - Raw JSON document (with $ref pointers preserved)
- * @param {any} opts
+ * @param {JxMutableNode | Record<string, any>} raw - Raw JSON document (with $ref pointers
+ *   preserved)
+ * @param {Record<string, unknown>} opts
  * @returns {{ html: string; files: { path: string; content: string; tagName: string }[] }}
  */
 export function compileStaticPage(raw, opts) {
-  const { title, reactivitySrc, litHtmlSrc } = opts;
+  const { title, reactivitySrc, litHtmlSrc } = /** @type {JxMutableNode} */ (opts);
 
   const rootContext = createCompileContext(raw, null, raw.state ?? {}, raw.$media ?? {});
-  const styleBlock = compileStyles(raw, raw.$media ?? {}, opts.projectStyle ?? null);
+  const styleBlock = compileStyles(
+    raw,
+    raw.$media ?? {},
+    /** @type {JxStyle | null} */ (opts.projectStyle ?? null),
+  );
   /** @type {{ def: any; tagName: string; className: string }[]} */
   const islands = [];
   const bodyContent = compileNode(raw, false, raw, rootContext, islands);
@@ -83,9 +88,9 @@ export function compileStaticPage(raw, opts) {
  * Compile a single Jx node to an HTML string. Dynamic nodes become hydration islands; static nodes
  * become plain HTML.
  *
- * @param {any} def
+ * @param {JxMutableNode} def
  * @param {boolean} dynamic
- * @param {any} raw
+ * @param {JxMutableNode} raw
  * @param {any} context
  * @param {{ def: any; tagName: string; className: string }[]} islands
  * @returns {string}
@@ -127,8 +132,8 @@ function compileNode(def, dynamic, raw, context, islands) {
  * Build the inner HTML (textContent or children) for a node. For children, emit islands only for
  * those that are actually dynamic.
  *
- * @param {any} def
- * @param {any} raw
+ * @param {JxMutableNode} def
+ * @param {JxMutableNode} raw
  * @param {any} context
  * @param {{ def: any; tagName: string; className: string }[]} islands
  * @returns {string}
@@ -141,14 +146,20 @@ function buildInnerWithIslands(def, raw, context, islands) {
     return value == null ? "" : escapeHtml(String(value));
   }
   if (source.innerHTML)
-    return resolveStaticValue(source.innerHTML, context.scope) ?? source.innerHTML;
+    return (
+      /** @type {string} */ (resolveStaticValue(source.innerHTML, context.scope)) ??
+      source.innerHTML
+    );
   if (Array.isArray(source.children)) {
     const rawChildren = raw?.children;
     return source.children
-      .map((/** @type {any} */ c, /** @type {number} */ i) => {
-        const childDynamic = isNodeDynamic(c);
-        const childRaw = rawChildren?.[i] ?? c;
-        return compileNode(c, childDynamic, childRaw, context, islands);
+      .map((c, /** @type {number} */ i) => {
+        const child = /** @type {JxMutableNode} */ (/** @type {unknown} */ (c));
+        const childDynamic = isNodeDynamic(child);
+        const childRaw = /** @type {JxMutableNode} */ (
+          /** @type {unknown} */ (rawChildren?.[i] ?? c)
+        );
+        return compileNode(child, childDynamic, childRaw, context, islands);
       })
       .join("\n  ");
   }