@jxsuite/parser 0.28.4 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/parser",
-  "version": "0.28.4",
+  "version": "0.29.0",
   "description": "Jx markdown parser and external class integration",
   "license": "MIT",
   "repository": {
@@ -34,12 +34,13 @@
   "scripts": {
     "prepare": "bun build src/content.ts src/markdown.ts src/csv.ts src/serialize.ts --outdir=dist --format=esm --target=node",
     "build": "bun run prepare",
+    "build:metafile": "bun build src/content.ts src/markdown.ts src/csv.ts src/serialize.ts --outdir=dist --format=esm --target=node --metafile=metafile.json",
     "test": "bun test --isolate",
     "test:coverage": "bun test --isolate --coverage",
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
-    "@jxsuite/schema": "^0.28.4",
+    "@jxsuite/schema": "^0.29.0",
     "glob": "^13.0.6",
     "hast-util-from-html": "^2.0.3",
     "hast-util-whitespace": "^3.0.0",
@@ -59,7 +60,7 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.2",
-    "@jxsuite/runtime": "^0.28.4",
+    "@jxsuite/runtime": "^0.29.0",
     "@types/hast": "^3.0.4",
     "@types/mdast": "^4.0.4"
   }

package/src/content.ts

@@ -63,9 +63,15 @@ export function evaluateFilterRule(
       return actual != null && actual !== "" && !(Array.isArray(actual) && actual.length === 0);
     }
     case "contains": {
+      if (Array.isArray(actual)) {
+        return actual.includes(rule.value);
+      }
       return typeof actual === "string" && actual.includes(String(rule.value ?? ""));
     }
     case "not contains": {
+      if (Array.isArray(actual)) {
+        return !actual.includes(rule.value);
+      }
       return typeof actual === "string" && !actual.includes(String(rule.value ?? ""));
     }
     case ">": {

package/src/csv.ts

@@ -78,12 +78,12 @@ export function parseCSV(csv: string): Record<string, string>[] {
     return fields;
   };
 
-  const headers = parseRow(lines[0]);
+  const headers = parseRow(lines[0]!);
   for (let i = 1; i < lines.length; i++) {
-    const fields = parseRow(lines[i]);
+    const fields = parseRow(lines[i]!);
     const obj: Record<string, string> = {};
     for (let j = 0; j < headers.length; j++) {
-      obj[headers[j].trim()] = fields[j]?.trim() ?? "";
+      obj[headers[j]!.trim()] = fields[j]?.trim() ?? "";
     }
     rows.push(obj);
   }

package/src/md.ts

@@ -21,7 +21,7 @@ import { readFileSync } from "node:fs";
 import { basename, extname, resolve as resolvePath } from "node:path";
 import { globSync } from "glob";
 import { mdastNodeToJx } from "./transpile.ts";
-import type { MarkdownFileResult, MdastNode, TocEntry } from "./types.ts";
+import type { MarkdownFileResult, MdastNode, TocEntry, UnifiedProcessor } from "./types.ts";
 import type { JxElement } from "@jxsuite/schema/types";
 
 // ─── Tree utilities (inline to avoid Bun ESM resolution issues with unist-util-*) ──
@@ -153,7 +153,7 @@ export function processMarkdown(
     directiveOptions?: unknown;
   } = {},
 ) {
-  let processor = unified()
+  let processor = (unified as unknown as () => UnifiedProcessor)()
     .use(remarkParse)
     .use(remarkFrontmatter, ["yaml"])
     .use(remarkParseFrontmatter)
@@ -175,7 +175,7 @@ export function processMarkdown(
   const excerpt = extractExcerpt(tree);
   const slug = basename(filePath, extname(filePath));
 
-  const bodyNodes = tree.children.filter(
+  const bodyNodes = tree.children!.filter(
     (n: MdastNode) => n.type !== "yaml" && n.type !== "toml",
   ) as MdastNode[];
   const $children = bodyNodes.map((n: MdastNode) => mdastNodeToJx(n)).filter(Boolean) as (
@@ -280,7 +280,9 @@ export class MarkdownCollection {
     const resolved = basePath ? resolvePath(basePath, src) : src;
     // Normalize to forward slashes — glob requires POSIX paths on all platforms
     const pattern = resolved.split("\\").join("/");
-    const files = globSync(pattern, { absolute: true });
+    const files = (globSync as (p: string, o: { absolute: boolean }) => string[])(pattern, {
+      absolute: true,
+    });
 
     const results = files.map((filePath: string) => {
       const source = readFileSync(filePath, "utf8");

package/src/serialize.ts

@@ -25,6 +25,7 @@ import remarkDirective from "remark-directive";
 import remarkGfm from "remark-gfm";
 import { stringify as stringifyYaml } from "yaml";
 import { htmlToJx } from "./html-to-jx.ts";
+import { expandDotPaths } from "./transpile.ts";
 import type {
   JsonValue,
   JxAttributeValue,
@@ -33,7 +34,7 @@ import type {
   JxMutableNode,
   JxStateDefinition,
 } from "@jxsuite/schema/types";
-import type { MdastNode } from "./types.ts";
+import type { MdastNode, UnifiedProcessor } from "./types.ts";
 import type { Root } from "mdast";
 
 /** Static text content of a node — bound (`$ref`) text has no serializable form. */
@@ -285,8 +286,8 @@ function convertMdastNode(node: MdastNode): JxElement | null {
       | string
     )[];
   const flattenOrChildren = () => {
-    if (node.children?.length === 1 && node.children[0].type === "text") {
-      el.textContent = node.children[0].value ?? null;
+    if (node.children?.length === 1 && node.children[0]!.type === "text") {
+      el.textContent = node.children[0]!.value ?? null;
     } else if (node.children?.length) {
       el.children = childNodes();
     }
@@ -386,13 +387,18 @@ function convertMdastNode(node: MdastNode): JxElement | null {
 }
 
 function convertDirective(node: MdastNode): JxElement {
+  // Prototype directive (e.g. `:::Array`) → `{ $prototype: name, ... }`, tagName dropped.
+  if (node.name && PROTOTYPE_DIRECTIVE_NAMES.has(node.name)) {
+    return prototypeDirectiveToJx(node);
+  }
+
   const el: JxElement = { tagName: node.name ?? "div" };
   if (node.attributes && Object.keys(node.attributes).length > 0) {
     el.attributes = { ...node.attributes };
   }
   if (node.type === "textDirective") {
-    if (node.children?.length === 1 && node.children[0].type === "text") {
-      el.textContent = node.children[0].value ?? null;
+    if (node.children?.length === 1 && node.children[0]!.type === "text") {
+      el.textContent = node.children[0]!.value ?? null;
     } else if (node.children?.length) {
       el.children = node.children.flatMap((n) => convertMdastNode(n)).filter(Boolean) as (
         | JxElement
@@ -408,6 +414,34 @@ function convertDirective(node: MdastNode): JxElement {
   return el;
 }
 
+/**
+ * Roundtrip md → Jx for a prototype directive (e.g. `:::Array`): name → `$prototype` (tagName
+ * dropped), dot-path attributes expanded (items/filter/sort), single nested child → `map`.
+ */
+function prototypeDirectiveToJx(node: MdastNode): JxElement {
+  const el: JxElement = { $prototype: node.name as string };
+  if (node.attributes && Object.keys(node.attributes).length > 0) {
+    const expanded = expandDotPaths(node.attributes);
+    for (const [key, value] of Object.entries(expanded)) {
+      if (key === "$prototype") {
+        continue;
+      }
+      el[key] = value as JsonValue;
+    }
+  }
+  if (node.children?.length) {
+    const children = node.children.flatMap((n) => convertMdastNode(n)).filter(Boolean) as (
+      | JxElement
+      | string
+    )[];
+    const template = children.find((c) => c != null && typeof c === "object");
+    if (template) {
+      el.map = template as JxElement;
+    }
+  }
+  return el;
+}
+
 // ─── Roundtrip: Jx → mdast ───────────────────────────────────────────────────
 
 /**
@@ -656,6 +690,12 @@ const JX_DOLLAR_KEYS = new Set([
   "$elements",
 ]);
 
+/**
+ * `$prototype` element types that serialize as a directive named after the prototype (no tagName),
+ * e.g. `:::Array`. Mirrors the set in transpile.ts.
+ */
+const PROTOTYPE_DIRECTIVE_NAMES = new Set(["Array"]);
+
 const JX_ANNOTATION_KEYS = new Set(["$title", "$description"]);
 
 function collectDirectiveAttrs(el: JxElement) {
@@ -688,6 +728,16 @@ function convertToDirective(
   isBlock: boolean,
   allowlist: ReadonlySet<string>,
 ): MdastNode {
+  // Prototype pseudo-element (e.g. Array repeater) with no tagName → directive named after the
+  // Prototype; the `map` template is the directive body, items/filter/sort are attributes.
+  if (
+    !el.tagName &&
+    typeof el.$prototype === "string" &&
+    PROTOTYPE_DIRECTIVE_NAMES.has(el.$prototype)
+  ) {
+    return prototypeToDirective(el, isBlock, allowlist);
+  }
+
   const tag = (el.tagName as string) ?? "div";
   const attrs = collectDirectiveAttrs(el);
 
@@ -749,6 +799,35 @@ function convertToDirective(
   };
 }
 
+/**
+ * Serialize a tagName-less `$prototype` node (e.g. an Array repeater) to a directive named after
+ * its prototype. items/filter/sort (and any other scalar props) become attributes; the `map`
+ * template is the single nested child. `$prototype` (carried by the name) and `map` (the body) are
+ * omitted from the attributes.
+ */
+function prototypeToDirective(
+  el: JxElement,
+  isBlock: boolean,
+  allowlist: ReadonlySet<string>,
+): MdastNode {
+  const propsObj: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(el)) {
+    if (key === "$prototype" || key === "map" || key === "tagName") {
+      continue;
+    }
+    propsObj[key] = value;
+  }
+  const attrs = collapsePropsToAttrMap(propsObj);
+  const mapNode = el.map ? convertJxNode(el.map as JxElement, isBlock, allowlist) : null;
+  const children = mapNode ? [mapNode] : [];
+  return {
+    attributes: attrs,
+    children,
+    name: el.$prototype as string,
+    type: isBlock ? "containerDirective" : "textDirective",
+  };
+}
+
 function collapsePropsToAttrMap(propsObj: Record<string, unknown>) {
   const result: Record<string, string> = {};
 
@@ -1264,14 +1343,14 @@ function splitHtmlBlocks(html: string) {
 function parseHtmlElement(html: string) {
   const hMatch = html.match(/^<(h[1-6])(?:\s[^>]*)?>(.+?)<\/\1>$/is);
   if (hMatch) {
-    const depth = Number.parseInt(hMatch[1].slice(1), 10);
-    const children = parseInlineHtml(hMatch[2]);
+    const depth = Number.parseInt(hMatch[1]!.slice(1), 10);
+    const children = parseInlineHtml(hMatch[2]!);
     return [{ children, depth, type: "heading" }];
   }
 
   const pMatch = html.match(/^<p(?:\s[^>]*)?>(.+?)<\/p>$/is);
   if (pMatch) {
-    const children = parseInlineHtml(pMatch[1]);
+    const children = parseInlineHtml(pMatch[1]!);
     if (children.length === 0) {
       return null;
     }
@@ -1287,13 +1366,13 @@ function parseHtmlElement(html: string) {
   );
   if (preMatch) {
     const lang = preMatch[1] ?? null;
-    const value = decodeHtmlEntities(preMatch[2]);
+    const value = decodeHtmlEntities(preMatch[2]!);
     return [{ lang, type: "code", value }];
   }
 
   const bqMatch = html.match(/^<blockquote(?:\s[^>]*)?>([^]*?)<\/blockquote>$/is);
   if (bqMatch) {
-    const inner = htmlToMdast(bqMatch[1]);
+    const inner = htmlToMdast(bqMatch[1]!);
     const children = inner.map((c) =>
       c.type === "text" ? { children: [c], type: "paragraph" } : c,
     );
@@ -1302,7 +1381,7 @@ function parseHtmlElement(html: string) {
 
   const ulMatch = html.match(/^<ul(?:\s[^>]*)?>([^]*?)<\/ul>$/is);
   if (ulMatch) {
-    const items = parseListItems(ulMatch[1]);
+    const items = parseListItems(ulMatch[1]!);
     if (items.length === 0) {
       return null;
     }
@@ -1311,7 +1390,7 @@ function parseHtmlElement(html: string) {
 
   const olMatch = html.match(/^<ol(?:\s[^>]*)?>([^]*?)<\/ol>$/is);
   if (olMatch) {
-    const items = parseListItems(olMatch[1]);
+    const items = parseListItems(olMatch[1]!);
     if (items.length === 0) {
       return null;
     }
@@ -1320,14 +1399,14 @@ function parseHtmlElement(html: string) {
 
   const tableMatch = html.match(/^<table(?:\s[^>]*)?>([^]*?)<\/table>$/is);
   if (tableMatch) {
-    return parseHtmlTable(tableMatch[1]);
+    return parseHtmlTable(tableMatch[1]!);
   }
 
   const wrapperMatch = html.match(
     /^<(?:div|section|article|aside|figure|nav|header|footer|main)(?:\s[^>]*)?>([^]*?)<\/(?:div|section|article|aside|figure|nav|header|footer|main)>$/is,
   );
   if (wrapperMatch) {
-    return htmlToMdast(wrapperMatch[1]);
+    return htmlToMdast(wrapperMatch[1]!);
   }
 
   const text = stripHtmlTags(html).trim();
@@ -1382,7 +1461,7 @@ function parseInlineHtml(html: string) {
 
     const openMatch = html.slice(tagStart).match(/^<(a|em|strong|del|code|b|i|s)(\s[^>]*)?>/);
     if (openMatch) {
-      const tag = openMatch[1].toLowerCase();
+      const tag = openMatch[1]!.toLowerCase();
       const attrs = openMatch[2] ?? "";
       const innerStart = tagStart + openMatch[0].length;
       const closeTag = `</${tag}>`;
@@ -1477,7 +1556,7 @@ function parseListItems(html: string) {
   const liPattern = /<li(?:\s[^>]*)?>([\s\S]*?)<\/li>/gi;
   let m;
   while ((m = liPattern.exec(html)) !== null) {
-    const inner = m[1].trim();
+    const inner = m[1]!.trim();
     const innerNodes = /<(?:p|ul|ol|blockquote|pre)[\s>]/i.test(inner)
       ? htmlToMdast(inner)
       : [{ children: parseInlineHtml(inner), type: "paragraph" }];
@@ -1494,8 +1573,8 @@ function parseHtmlTable(html: string) {
     const cellPattern = /<(?:th|td)(?:\s[^>]*)?>([\s\S]*?)<\/(?:th|td)>/gi;
     const cells: MdastNode[] = [];
     let c;
-    while ((c = cellPattern.exec(m[1])) !== null) {
-      cells.push({ children: parseInlineHtml(c[1]), type: "tableCell" });
+    while ((c = cellPattern.exec(m[1]!)) !== null) {
+      cells.push({ children: parseInlineHtml(c[1]!), type: "tableCell" });
     }
     if (cells.length > 0) {
       rows.push({ children: cells, type: "tableRow" });
@@ -1555,22 +1634,19 @@ function serializeRoundtrip(doc: JxDocument, opts: SerializeOptions): string {
     }
 
     if (Object.keys(frontmatter).length > 0) {
-      lines.push("---");
-      lines.push(stringifyYaml(frontmatter).trim());
-      lines.push("---");
-      lines.push("");
+      lines.push("---", stringifyYaml(frontmatter).trim(), "---", "");
     }
   }
 
   if (Array.isArray(doc.children) && doc.children.length > 0) {
     const mdast = jxToMdast(doc as JxElement, opts);
-    const md = unified()
+    const processor = (unified as unknown as () => UnifiedProcessor)()
       .use(remarkGfm)
       .use(remarkDirective)
-      .use(remarkStringify, { bullet: "-", emphasis: "*", strong: "*" })
-      .stringify(mdast as unknown as Root);
+      .use(remarkStringify, { bullet: "-", emphasis: "*", strong: "*" });
+    const md = processor.stringify(mdast as unknown as Root);
 
-    lines.push(md as string);
+    lines.push(md);
   }
 
   return `${lines
@@ -1586,7 +1662,7 @@ function serializeExport(doc: JxDocument, opts: SerializeOptions): string {
 
   const ctx: ExportContext = {
     buildScope: opts.buildScope,
-    componentDefs: opts.componentDefs ?? new Map(),
+    componentDefs: opts.componentDefs ?? new Map<string, JxElement>(),
     evaluateTemplate: opts.evaluateTemplate,
   };
 
@@ -1623,15 +1699,15 @@ function serializeExport(doc: JxDocument, opts: SerializeOptions): string {
     type: "root",
   } as unknown as Root;
 
-  const md = unified()
+  const processor = (unified as unknown as () => UnifiedProcessor)()
     .use(remarkGfm)
     .use(remarkStringify, {
       bullet: "-",
       emphasis: "*",
       setext: false,
       strong: "*",
-    })
-    .stringify(mdast);
+    });
+  const md = processor.stringify(mdast);
 
   return `${md.replaceAll(/\n{3,}/g, "\n\n").trim()}\n`;
 }

package/src/transpile.ts

@@ -18,10 +18,10 @@ import remarkParseFrontmatter from "remark-parse-frontmatter";
 import remarkGfm from "remark-gfm";
 import remarkDirective from "remark-directive";
 import { htmlToJx } from "./html-to-jx.ts";
-import type { MdastNode } from "./types.ts";
+import type { MdastNode, UnifiedProcessor } from "./types.ts";
 import type { JsonValue, JxAttributeValue, JxDocument, JxElement } from "@jxsuite/schema/types";
 
-export { htmlToJx };
+export { htmlToJx } from "./html-to-jx.ts";
 
 // ─── Dot-path expansion ─────────────────────────────────────────────────────
 
@@ -31,6 +31,12 @@ export { htmlToJx };
  */
 const JX_DOLLAR_KEYS = new Set(["prototype", "ref", "component", "props", "switch", "elements"]);
 
+/**
+ * `$prototype` element types that serialize as a directive named after the prototype (no tagName),
+ * e.g. `:::Array`. On parse the synthetic tagName is dropped and `$prototype` is restored.
+ */
+const PROTOTYPE_DIRECTIVE_NAMES = new Set(["Array"]);
+
 /**
  * Annotation keys written as `--key` in markdown directives, mapped to `$key` in JX JSON. These use
  * `--` prefix to avoid collision with HTML attributes like `title`.
@@ -88,7 +94,7 @@ export function expandDotPaths(attrs: Record<string, string>) {
     const segments = key.split(".");
     let target = result;
     for (let i = 0; i < segments.length - 1; i++) {
-      const seg = jxKey(segments[i]);
+      const seg = jxKey(segments[i]!);
       if (!(seg in target) || typeof target[seg] !== "object") {
         target[seg] = {};
       }
@@ -222,7 +228,7 @@ export function isJxMarkdown(source: string) {
   if (!fmMatch) {
     return false;
   }
-  return /^tagName:\s*.+-.+/m.test(fmMatch[1]);
+  return /^tagName:\s*.+-.+/m.test(fmMatch[1]!);
 }
 
 // ─── Transpiler ─────────────────────────────────────────────────────────────
@@ -472,6 +478,11 @@ export function mdastNodeToJx(node: MdastNode) {
  * @returns {JxElement}
  */
 function directiveToJx(node: MdastNode) {
+  // Prototype directive (e.g. `:::Array`) → `{ $prototype: name, ... }` with no tagName.
+  if (PROTOTYPE_DIRECTIVE_NAMES.has(node.name as string)) {
+    return prototypeDirectiveToJx(node);
+  }
+
   const el: JxElement = { tagName: node.name as string };
 
   if (node.attributes && Object.keys(node.attributes).length > 0) {
@@ -595,6 +606,36 @@ function directiveToJx(node: MdastNode) {
   return el;
 }
 
+/**
+ * Convert a prototype directive (e.g. `:::Array`) to a tagName-less `$prototype` node. Attributes
+ * (items/filter/sort, dot-path expanded) become element-level props; the single nested child is the
+ * `map` template.
+ *
+ * @param {MdastNode} node
+ * @returns {JxElement}
+ */
+function prototypeDirectiveToJx(node: MdastNode) {
+  const el: JxElement = { $prototype: node.name as string };
+
+  if (node.attributes && Object.keys(node.attributes).length > 0) {
+    const expanded = expandDotPaths(node.attributes);
+    for (const [key, value] of Object.entries(expanded)) {
+      // The prototype is carried by the directive name; ignore any redundant attribute form.
+      if (key === "$prototype") {
+        continue;
+      }
+      el[key] = value as JsonValue;
+    }
+  }
+
+  const children = convertChildren(node.children ?? []);
+  const template = children.find((c) => c != null && typeof c === "object");
+  if (template) {
+    el.map = template as JxElement;
+  }
+  return el;
+}
+
 /**
  * Convert an array of mdast children to Jx elements/strings.
  *
@@ -621,7 +662,7 @@ export function convertChildren(children: MdastNode[]) {
  * @returns {object} Complete Jx JSON document
  */
 export function transpileJxMarkdown(source: string) {
-  const processor = unified()
+  const processor = (unified as unknown as () => UnifiedProcessor)()
     .use(remarkParse)
     .use(remarkFrontmatter, ["yaml"])
     .use(remarkParseFrontmatter)
@@ -640,7 +681,7 @@ export function transpileJxMarkdown(source: string) {
     doc[key] = value;
   }
 
-  const bodyNodes = tree.children.filter(
+  const bodyNodes = tree.children!.filter(
     (n: MdastNode) => n.type !== "yaml" && n.type !== "toml",
   ) as unknown as MdastNode[];
 

package/src/types.ts

@@ -54,6 +54,21 @@ export interface MdastNode {
   align?: (string | null)[] | null;
 }
 
+/**
+ * Minimal structural type for the unified() processor chain.
+ *
+ * The unified/remark packages ship ESM-only types that oxlint's type-aware engine cannot resolve
+ * under `moduleResolution: bundler` (it sees them as `any`), even though tsgo resolves them
+ * correctly. We cast the `unified()` result to this hand-written surface once, at the construction
+ * boundary, so the rest of the pipeline is properly typed instead of `any`.
+ */
+export interface UnifiedProcessor {
+  use: (plugin: unknown, ...options: unknown[]) => UnifiedProcessor;
+  parse: (source: string) => MdastNode;
+  runSync: (tree: MdastNode, file?: unknown) => MdastNode;
+  stringify: (tree: unknown) => string;
+}
+
 export interface HastNode {
   type: string;
   tagName?: string;