@jxsuite/parser 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/parser",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Jx markdown parser and external class integration",
   "license": "MIT",
   "repository": {
@@ -28,7 +28,9 @@
   "dependencies": {
     "glob": "^13.0.6",
     "hast-util-from-html": "^2.0.3",
+    "hast-util-whitespace": "^3.0.0",
     "mdast-util-to-string": "^4.0.0",
+    "property-information": "^7.1.0",
     "rehype-stringify": "^10.0.1",
     "remark-directive": "^4.0.0",
     "remark-frontmatter": "^5.0.0",
@@ -41,6 +43,7 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.9.0",
-    "@jxsuite/runtime": "^0.18.0"
+    "@jxsuite/runtime": "^0.20.0",
+    "@types/hast": "^3.0.4"
   }
 }

package/src/html-to-jx.js

@@ -2,23 +2,25 @@ import { fromHtml } from "hast-util-from-html";
 import { whitespace } from "hast-util-whitespace";
 import { find, html as htmlInfo } from "property-information";
 
+/** @typedef {import("hast").Nodes} HastNode */
+
 /**
  * Convert an HTML string into an array of Jx tree nodes.
  *
  * @param {string} htmlString
- * @returns {any[]}
+ * @returns {(JxElement | string)[]}
  */
 export function htmlToJx(htmlString) {
   const hast = fromHtml(htmlString, { fragment: true });
-  return convertHastChildren(hast.children);
+  return convertHastChildren(/** @type {HastNode[]} */ (hast.children));
 }
 
 /**
- * @param {any[]} children
- * @returns {any[]}
+ * @param {HastNode[]} children
+ * @returns {(JxElement | string)[]}
  */
 function convertHastChildren(children) {
-  /** @type {any[]} */
+  /** @type {(JxElement | string)[]} */
   const result = [];
   for (const child of children) {
     const converted = convertHastNode(child);
@@ -28,17 +30,17 @@ function convertHastChildren(children) {
 }
 
 /**
- * @param {any} node
- * @returns {any}
+ * @param {HastNode} node
+ * @returns {JxElement | string | null}
  */
 function convertHastNode(node) {
   if (node.type === "text") {
-    if (whitespace(node)) return null;
-    return node.value;
+    if (whitespace(/** @type {HastNode} */ (/** @type {unknown} */ (node)))) return null;
+    return node.value ?? null;
   }
 
   if (node.type === "element") {
-    /** @type {Record<string, any>} */
+    /** @type {JxElement} */
     const el = { tagName: node.tagName };
 
     if (node.properties && Object.keys(node.properties).length > 0) {
@@ -52,7 +54,7 @@ function convertHastNode(node) {
     if (kids.length === 1 && typeof kids[0] === "string") {
       el.textContent = kids[0];
     } else if (kids.length > 0) {
-      el.children = kids;
+      el.children = /** @type {JxElement[]} */ (kids);
     }
 
     return el;
@@ -62,7 +64,7 @@ function convertHastNode(node) {
 }
 
 /**
- * @param {Record<string, any>} properties
+ * @param {Record<string, unknown>} properties
  * @returns {{ style: Record<string, string>; attrs: Record<string, string> }}
  */
 function hastPropsToJx(properties) {

package/src/md.js

@@ -27,7 +27,7 @@ import { mdastNodeToJx } from "./transpile.js";
 /**
  * Walk an AST tree, calling visitor for nodes matching the given type.
  *
- * @param {any} tree
+ * @param {object} tree
  * @param {string | function} typeOrVisitor
  * @param {function} [maybeVisitor]
  */
@@ -35,20 +35,20 @@ function visit(tree, typeOrVisitor, maybeVisitor) {
   const type = typeof typeOrVisitor === "string" ? typeOrVisitor : null;
   const visitor = type ? maybeVisitor : typeOrVisitor;
 
-  function walk(/** @type {any} */ node) {
+  function walk(/** @type {MdastNode} */ node) {
     if (!node || typeof node !== "object") return;
     if (!type || node.type === type) /** @type {Function} */ (visitor)(node);
     if (Array.isArray(node.children)) {
       for (const child of node.children) walk(child);
     }
   }
-  walk(tree);
+  walk(/** @type {MdastNode} */ (tree));
 }
 
 /**
  * Serialize an mdast tree to plain text.
  *
- * @param {any} node
+ * @param {MdastNode} node
  * @returns {string}
  */
 function mdastToString(node) {
@@ -81,7 +81,7 @@ function readingTime(text) {
 function extractToc(tree) {
   /** @type {{ depth: number; text: string; id: string }[]} */
   const entries = [];
-  visit(tree, "heading", (/** @type {any} */ node) => {
+  visit(tree, "heading", (/** @type {MdastNode} */ node) => {
     const text = mdastToString(node);
     const id = text
       .toLowerCase()
@@ -89,7 +89,7 @@ function extractToc(tree) {
       .replace(/\s+/g, "-")
       .replace(/-+/g, "-")
       .replace(/^-|-$/g, "");
-    entries.push({ depth: node.depth, text, id });
+    entries.push({ depth: /** @type {number} */ (node.depth), text, id });
   });
   return entries;
 }
@@ -101,9 +101,9 @@ function extractToc(tree) {
  * @returns {string} Plain text of first paragraph, or empty string
  */
 function extractExcerpt(tree) {
-  /** @type {any} */
+  /** @type {MdastNode | null} */
   let firstParagraph = null;
-  visit(tree, "paragraph", (/** @type {any} */ node) => {
+  visit(tree, "paragraph", (/** @type {MdastNode} */ node) => {
     if (!firstParagraph) firstParagraph = node;
   });
   if (!firstParagraph) return "";
@@ -117,8 +117,10 @@ function extractExcerpt(tree) {
  *
  * @param {string} source - Raw markdown string
  * @param {string} filePath - File path (for slug derivation)
- * @param {any} config - Processing options
- * @returns {object} MarkdownFileResult
+ * @param {object} config - Processing options
+ * @param {boolean} [config.directives] - Enable directive support
+ * @param {unknown} [config.directiveOptions] - Directive plugin options
+ * @returns {MarkdownFileResult}
  */
 function processMarkdown(source, filePath, config = {}) {
   let processor = unified()
@@ -133,18 +135,25 @@ function processMarkdown(source, filePath, config = {}) {
 
   const tree = processor.parse(source);
   const vfile = { data: {} };
-  processor.runSync(tree, /** @type {any} */ (vfile));
+  // @ts-ignore - vfile shape satisfies unified's internal contract
+  processor.runSync(tree, vfile);
 
-  const frontmatter = /** @type {any} */ (vfile.data).frontmatter ?? {};
-  const plainText = mdastToString(tree);
+  const vfileData = /** @type {Record<string, unknown>} */ (vfile.data);
+  const frontmatter = /** @type {Record<string, unknown>} */ (vfileData.frontmatter ?? {});
+  const mdTree = /** @type {MdastNode} */ (/** @type {unknown} */ (tree));
+  const plainText = mdastToString(mdTree);
   const toc = extractToc(tree);
   const excerpt = extractExcerpt(tree);
   const slug = basename(filePath, extname(filePath));
 
-  const bodyNodes = tree.children.filter(
-    (/** @type {any} */ n) => n.type !== "yaml" && n.type !== "toml",
+  const bodyNodes = /** @type {MdastNode[]} */ (
+    tree.children.filter(
+      (/** @type {{ type: string }} */ n) => n.type !== "yaml" && n.type !== "toml",
+    )
+  );
+  const $children = /** @type {(JxElement | string)[]} */ (
+    bodyNodes.map(/** @type {(n: MdastNode) => any} */ (mdastNodeToJx)).filter(Boolean)
   );
-  const $children = bodyNodes.map(mdastNodeToJx).filter(Boolean);
 
   return {
     slug,
@@ -161,12 +170,17 @@ function processMarkdown(source, filePath, config = {}) {
 /**
  * Resolve a dot-notation path within an object.
  *
- * @param {any} obj
+ * @param {Record<string, unknown> | MarkdownFileResult} obj
  * @param {string} path
- * @returns {any}
+ * @returns {unknown}
  */
 function getNestedValue(obj, path) {
-  return path.split(".").reduce((/** @type {any} */ o, k) => o?.[k], obj);
+  return path
+    .split(".")
+    .reduce(
+      (/** @type {unknown} */ o, k) => /** @type {Record<string, unknown> | undefined} */ (o)?.[k],
+      /** @type {unknown} */ (obj),
+    );
 }
 
 // ─── MarkdownFile ─────────────────────────────────────────────────────────────
@@ -181,8 +195,8 @@ export class MarkdownFile {
   /**
    * @param {object} config
    * @param {string} config.src - File path to markdown file
-   * @param {any[]} [config.remarkPlugins] Default is `[]`
-   * @param {any[]} [config.rehypePlugins] Default is `[]`
+   * @param {unknown[]} [config.remarkPlugins] Default is `[]`
+   * @param {unknown[]} [config.rehypePlugins] Default is `[]`
    * @param {string} [config.basePath] - Base path for resolving src
    * @param {boolean} [config.directives] - Enable directive support
    */
@@ -193,7 +207,7 @@ export class MarkdownFile {
   /**
    * Parse and resolve the markdown file.
    *
-   * @returns {object} MarkdownFileResult
+   * @returns {MarkdownFileResult}
    */
   resolve() {
     const { src, basePath, ...processorConfig } = this.config;
@@ -220,8 +234,8 @@ export class MarkdownCollection {
    * @param {string} [config.sortOrder] Default is `'desc'`
    * @param {number} [config.limit]
    * @param {Function} [config.filter] - Filter function
-   * @param {any[]} [config.remarkPlugins] Default is `[]`
-   * @param {any[]} [config.rehypePlugins] Default is `[]`
+   * @param {unknown[]} [config.remarkPlugins] Default is `[]`
+   * @param {unknown[]} [config.rehypePlugins] Default is `[]`
    * @param {string} [config.basePath] - Base path for resolving glob
    * @param {boolean} [config.directives] - Enable directive support
    */
@@ -232,7 +246,7 @@ export class MarkdownCollection {
   /**
    * Glob files, parse each, sort, filter, and limit.
    *
-   * @returns {Promise<object[]>} Array of MarkdownFileResult
+   * @returns {Promise<MarkdownFileResult[]>} Array of MarkdownFileResult
    */
   async resolve() {
     const {
@@ -250,7 +264,7 @@ export class MarkdownCollection {
     const pattern = resolved.split("\\").join("/");
     const files = globSync(pattern, { absolute: true });
 
-    const results = files.map((filePath) => {
+    const results = files.map((/** @type {string} */ filePath) => {
       const source = readFileSync(filePath, "utf-8");
       return processMarkdown(source, filePath, processorConfig);
     });
@@ -258,13 +272,13 @@ export class MarkdownCollection {
     // Filter
     let filtered = results;
     if (typeof filter === "function") {
-      filtered = results.filter(/** @type {any} */ (filter));
+      filtered = results.filter(/** @type {(r: MarkdownFileResult) => boolean} */ (filter));
     }
 
     // Sort
-    filtered.sort((a, b) => {
-      const aVal = getNestedValue(a, sortBy) ?? "";
-      const bVal = getNestedValue(b, sortBy) ?? "";
+    filtered.sort((/** @type {MarkdownFileResult} */ a, /** @type {MarkdownFileResult} */ b) => {
+      const aVal = /** @type {string | number} */ (getNestedValue(a, sortBy) ?? "");
+      const bVal = /** @type {string | number} */ (getNestedValue(b, sortBy) ?? "");
       if (aVal < bVal) return sortOrder === "asc" ? -1 : 1;
       if (aVal > bVal) return sortOrder === "asc" ? 1 : -1;
       return 0;

package/src/transpile.js

@@ -66,10 +66,10 @@ export function mdKey(key) {
  * Expand dot-path attribute keys into nested objects.
  *
  * @param {Record<string, string>} attrs - Flat attribute map from remark-directive
- * @returns {Record<string, any>} Nested object
+ * @returns {Record<string, unknown>} Nested object
  */
 export function expandDotPaths(attrs) {
-  /** @type {Record<string, any>} */
+  /** @type {Record<string, unknown>} */
   const result = {};
 
   for (const [key, value] of Object.entries(attrs)) {
@@ -86,7 +86,7 @@ export function expandDotPaths(attrs) {
       if (!(seg in target) || typeof target[seg] !== "object") {
         target[seg] = {};
       }
-      target = target[seg];
+      target = /** @type {Record<string, unknown>} */ (target[seg]);
     }
     target[jxKey(segments[segments.length - 1])] = value;
   }
@@ -97,18 +97,18 @@ export function expandDotPaths(attrs) {
 /**
  * Collapse a nested object back to dot-path flat attributes (inverse of expandDotPaths).
  *
- * @param {Record<string, any>} obj - Nested object
+ * @param {Record<string, unknown>} obj - Nested object
  * @returns {Record<string, string>} Flat attribute map
  */
 export function collapseDotPaths(obj) {
   /** @type {Record<string, string>} */
   const result = {};
 
-  function walk(/** @type {Record<string, any>} */ node, /** @type {string} */ prefix) {
+  function walk(/** @type {Record<string, unknown>} */ node, /** @type {string} */ prefix) {
     for (const [key, value] of Object.entries(node)) {
       const path = prefix ? `${prefix}.${key}` : key;
       if (value && typeof value === "object" && !Array.isArray(value)) {
-        walk(value, path);
+        walk(/** @type {Record<string, unknown>} */ (value), path);
       } else {
         result[path] = String(value);
       }
@@ -148,11 +148,11 @@ const CSS_PSEUDO_NAMES = new Set([
  * `:hover` (for known CSS pseudo-class names) - `--dark` → `@--dark` (for custom property / media
  * query keys)
  *
- * @param {Record<string, any>} styleObj
- * @returns {Record<string, any>}
+ * @param {Record<string, unknown>} styleObj
+ * @returns {Record<string, unknown>}
  */
 export function applyStyleKeyMapping(styleObj) {
-  /** @type {Record<string, any>} */
+  /** @type {Record<string, unknown>} */
   const result = {};
   for (const [key, value] of Object.entries(styleObj)) {
     if (CSS_PSEUDO_NAMES.has(key)) {
@@ -173,7 +173,7 @@ export function applyStyleKeyMapping(styleObj) {
  * cannot appear at the start of remark-directive attribute keys.
  *
  * @param {Record<string, string>} attrs
- * @returns {Record<string, any>}
+ * @returns {Record<string, unknown>}
  */
 export function expandStylePaths(attrs) {
   return applyStyleKeyMapping(expandDotPaths(attrs));
@@ -185,11 +185,11 @@ export function expandStylePaths(attrs) {
  * Strips `:` prefix from pseudo-class keys and `@` prefix from media keys before flattening with
  * collapseDotPaths.
  *
- * @param {Record<string, any>} styleObj
+ * @param {Record<string, unknown>} styleObj
  * @returns {Record<string, string>}
  */
 export function collapseStylePaths(styleObj) {
-  /** @type {Record<string, any>} */
+  /** @type {Record<string, unknown>} */
   const normalized = {};
 
   for (const [key, value] of Object.entries(styleObj)) {
@@ -271,24 +271,24 @@ const PHRASING_ELEMENTS = new Set([
  * Route directive attributes to their correct Jx locations.
  *
  * @param {Record<string, string>} attrs
- * @returns {{ props: Record<string, any>; attributes: Record<string, string> }}
+ * @returns {{ props: Record<string, unknown>; attributes: Record<string, string> }}
  */
 function routeAttributes(attrs) {
   const expanded = expandDotPaths(attrs);
 
   // Apply style-key mapping (pseudo-classes, media queries) to the style sub-object
   if (expanded.style && typeof expanded.style === "object") {
-    expanded.style = applyStyleKeyMapping(expanded.style);
+    expanded.style = applyStyleKeyMapping(/** @type {Record<string, unknown>} */ (expanded.style));
   }
 
-  /** @type {Record<string, any>} */
+  /** @type {Record<string, unknown>} */
   const props = {};
   /** @type {Record<string, string>} */
   const attributes = {};
 
   for (const [key, value] of Object.entries(expanded)) {
     if (HTML_ATTR_PATTERN.test(key)) {
-      attributes[key] = value;
+      attributes[key] = /** @type {string} */ (value);
     } else {
       props[key] = value;
     }
@@ -300,10 +300,10 @@ function routeAttributes(attrs) {
 /**
  * Mdast node-type → Jx tagName mapping.
  *
- * @type {Record<string, (n: any) => string>}
+ * @type {Record<string, (n: MdastNode) => string>}
  */
 const JX_TAG_MAP = {
-  heading: (/** @type {any} */ n) => `h${n.depth}`,
+  heading: (/** @type {MdastNode} */ n) => `h${n.depth}`,
   paragraph: () => "p",
   emphasis: () => "em",
   strong: () => "strong",
@@ -312,21 +312,21 @@ const JX_TAG_MAP = {
   link: () => "a",
   image: () => "img",
   blockquote: () => "blockquote",
-  list: (/** @type {any} */ n) => (n.ordered ? "ol" : "ul"),
+  list: (/** @type {MdastNode} */ n) => (n.ordered ? "ol" : "ul"),
   listItem: () => "li",
   code: () => "pre",
   thematicBreak: () => "hr",
   break: () => "br",
   table: () => "table",
   tableRow: () => "tr",
-  tableCell: (/** @type {any} */ n) => (n.isHeader ? "th" : "td"),
+  tableCell: (/** @type {MdastNode} */ n) => (n.isHeader ? "th" : "td"),
 };
 
 /**
  * Convert a standard mdast node to a Jx element definition.
  *
- * @param {any} node
- * @returns {any} Jx element or null
+ * @param {MdastNode} node
+ * @returns {JxElement | string | (JxElement | string)[] | null} Jx element or null
  */
 export function mdastNodeToJx(node) {
   if (!node || typeof node !== "object") return null;
@@ -342,7 +342,7 @@ export function mdastNodeToJx(node) {
   }
 
   if (node.type === "text") {
-    return node.value;
+    return node.value ?? null;
   }
 
   if (node.type === "html") {
@@ -354,7 +354,7 @@ export function mdastNodeToJx(node) {
   if (!tagFn) return null;
 
   const tag = tagFn(node);
-  /** @type {Record<string, any>} */
+  /** @type {JxElement} */
   const el = { tagName: tag };
 
   switch (node.type) {
@@ -367,7 +367,7 @@ export function mdastNodeToJx(node) {
     case "listItem":
     case "tableRow":
     case "tableCell": {
-      const children = convertChildren(node.children);
+      const children = convertChildren(node.children ?? []);
       if (children.length === 1 && typeof children[0] === "string") {
         el.textContent = children[0];
       } else if (children.length > 0) {
@@ -384,7 +384,7 @@ export function mdastNodeToJx(node) {
       el.attributes = { href: node.url };
       if (node.title) el.attributes.title = node.title;
       {
-        const children = convertChildren(node.children);
+        const children = convertChildren(node.children ?? []);
         if (children.length === 1 && typeof children[0] === "string") {
           el.textContent = children[0];
         } else if (children.length > 0) {
@@ -399,7 +399,7 @@ export function mdastNodeToJx(node) {
       break;
 
     case "list":
-      if (node.children?.length > 0) {
+      if (node.children && node.children.length > 0) {
         el.children = convertChildren(node.children);
       }
       if (node.start != null && node.start !== 1) {
@@ -422,10 +422,10 @@ export function mdastNodeToJx(node) {
       break;
 
     case "table": {
-      const rows = convertChildren(node.children);
+      const rows = convertChildren(node.children ?? []);
       const thead = rows.length > 0 ? { tagName: "thead", children: [rows[0]] } : null;
       const tbody = rows.length > 1 ? { tagName: "tbody", children: rows.slice(1) } : null;
-      el.children = [thead, tbody].filter(Boolean);
+      el.children = /** @type {JxElement[]} */ ([thead, tbody].filter(Boolean));
       break;
     }
   }
@@ -436,16 +436,16 @@ export function mdastNodeToJx(node) {
 /**
  * Convert a directive mdast node to a Jx element.
  *
- * @param {any} node
- * @returns {any}
+ * @param {MdastNode} node
+ * @returns {JxElement}
  */
 function directiveToJx(node) {
-  /** @type {Record<string, any>} */
-  const el = { tagName: node.name };
+  /** @type {JxElement} */
+  const el = { tagName: /** @type {string} */ (node.name) };
 
   if (node.attributes && Object.keys(node.attributes).length > 0) {
     const { props, attributes } = routeAttributes(node.attributes);
-    const isCustomElement = node.name.includes("-");
+    const isCustomElement = /** @type {string} */ (node.name).includes("-");
     if (isCustomElement) {
       // For custom elements:
       //   - style, children, textContent, innerHTML, $-prefixed → element-level
@@ -461,7 +461,7 @@ function directiveToJx(node) {
         ) {
           el[key] = value;
         } else if (key === "props") {
-          el.$props = value;
+          el.$props = /** @type {Record<string, unknown>} */ (value);
         } else {
           if (!el.attributes) el.attributes = {};
           el.attributes[key] = value;
@@ -500,8 +500,8 @@ function directiveToJx(node) {
   }
 
   if (node.type === "textDirective") {
-    if (node.children?.length > 0) {
-      const children = convertChildren(node.children);
+    if (node.children && node.children.length > 0) {
+      const children = convertChildren(node.children ?? []);
       if (children.length === 1 && typeof children[0] === "string") {
         el.textContent = children[0];
       } else if (children.length > 0) {
@@ -515,21 +515,25 @@ function directiveToJx(node) {
     return el;
   }
 
-  if (node.children?.length > 0) {
-    /** @type {any[]} */
+  if (node.children && node.children.length > 0) {
+    /** @type {(JxElement | string)[]} */
     const jxChildren = [];
-    const isPhrasingParent = PHRASING_ELEMENTS.has(node.name);
+    const isPhrasingParent = PHRASING_ELEMENTS.has(/** @type {string} */ (node.name));
 
     for (const child of node.children) {
       if (isPhrasingParent && child.type === "paragraph") {
         // Unwrap: promote paragraph's inline children directly
         for (const inline of child.children ?? []) {
           const converted = mdastNodeToJx(inline);
-          if (converted != null) jxChildren.push(converted);
+          if (converted == null) continue;
+          if (Array.isArray(converted)) jxChildren.push(...converted);
+          else jxChildren.push(converted);
         }
       } else {
         const converted = mdastNodeToJx(child);
-        if (converted != null) jxChildren.push(converted);
+        if (converted == null) continue;
+        if (Array.isArray(converted)) jxChildren.push(...converted);
+        else jxChildren.push(converted);
       }
     }
 
@@ -550,12 +554,14 @@ function directiveToJx(node) {
 /**
  * Convert an array of mdast children to Jx elements/strings.
  *
- * @param {any[]} children
- * @returns {any[]}
+ * @param {MdastNode[]} children
+ * @returns {(JxElement | string)[]}
  */
 export function convertChildren(children) {
   if (!children) return [];
-  return children.flatMap(mdastNodeToJx).filter((c) => c != null);
+  return /** @type {(JxElement | string)[]} */ (
+    children.flatMap(mdastNodeToJx).filter((c) => c != null)
+  );
 }
 
 /**
@@ -579,20 +585,25 @@ export function transpileJxMarkdown(source) {
   const vfile = { data: {} };
   processor.runSync(tree, vfile);
 
-  const frontmatter = /** @type {any} */ (vfile.data)?.frontmatter ?? {};
+  const frontmatter = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (vfile.data))
+    ?.frontmatter ?? {};
 
-  /** @type {Record<string, any>} */
+  /** @type {JxDocument} */
   const doc = {};
 
   for (const [key, value] of Object.entries(frontmatter)) {
     doc[key] = value;
   }
 
-  const bodyNodes = tree.children.filter(
-    (/** @type {any} */ n) => n.type !== "yaml" && n.type !== "toml",
+  const bodyNodes = /** @type {MdastNode[]} */ (
+    /** @type {unknown} */ (
+      tree.children.filter(
+        (/** @type {{ type: string }} */ n) => n.type !== "yaml" && n.type !== "toml",
+      )
+    )
   );
 
-  /** @type {any[]} */
+  /** @type {(JxElement | string)[]} */
   const children = [];
 
   for (const node of bodyNodes) {