@jxsuite/parser 0.0.1

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@jxsuite/parser",
+  "version": "0.0.1",
+  "description": "Jx markdown parser and external class integration",
+  "license": "MIT",
+  "files": [
+    "src/"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/md.js",
+    "./MarkdownFile.class.json": "./src/MarkdownFile.class.json",
+    "./MarkdownCollection.class.json": "./src/MarkdownCollection.class.json"
+  },
+  "scripts": {
+    "test": "bun test",
+    "upgrade": "bunx npm-check-updates -u && bun install"
+  },
+  "dependencies": {
+    "glob": "^13.0.6",
+    "mdast-util-to-string": "^4.0.0",
+    "rehype-stringify": "^10.0.1",
+    "remark-directive": "^4.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-parse-frontmatter": "^1.0.3",
+    "remark-rehype": "^11.1.2",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.9.0",
+    "@jxsuite/runtime": "workspace:*"
+  }
+}

package/src/MarkdownCollection.class.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jxsuite.com/schemas/MarkdownCollection.class.json",
+  "title": "MarkdownCollection",
+  "description": "Load and parse a collection of Markdown files",
+  "$prototype": "Class",
+  "extends": "Object",
+  "$implementation": "./md.js",
+
+  "$defs": {
+    "parameters": {
+      "src": {
+        "identifier": "src",
+        "type": { "type": "string" },
+        "description": "Glob pattern for markdown files",
+        "examples": ["./content/posts/*.md"]
+      },
+      "sortBy": {
+        "identifier": "sortBy",
+        "type": { "type": "string", "default": "frontmatter.date" },
+        "description": "Dot-path to sort key"
+      },
+      "sortOrder": {
+        "identifier": "sortOrder",
+        "type": { "type": "string", "enum": ["asc", "desc"], "default": "desc" },
+        "description": "Sort direction"
+      },
+      "limit": {
+        "identifier": "limit",
+        "type": { "type": "integer", "minimum": 1 },
+        "description": "Maximum number of results"
+      },
+      "directives": {
+        "identifier": "directives",
+        "type": { "type": "boolean", "default": false },
+        "description": "Enable remark-directive plugin"
+      },
+      "basePath": {
+        "identifier": "basePath",
+        "type": { "type": "string" },
+        "description": "Base path for resolving src glob"
+      },
+      "itemSchema": {
+        "identifier": "itemSchema",
+        "type": { "type": "object" },
+        "format": "json-schema",
+        "description": "JSON Schema describing frontmatter fields for items in this collection"
+      }
+    },
+
+    "returnTypes": {
+      "MarkdownFileResult": {
+        "type": "object",
+        "description": "A single parsed markdown file in the collection",
+        "properties": {
+          "slug": { "type": "string", "description": "Filename without extension" },
+          "path": { "type": "string", "description": "Absolute file path" },
+          "frontmatter": {
+            "type": "object",
+            "description": "Shape defined by itemSchema parameter"
+          },
+          "$body": { "type": "string", "description": "Rendered HTML string" },
+          "$excerpt": { "type": "string", "description": "First paragraph as plain text" },
+          "$toc": {
+            "type": "array",
+            "description": "Table of contents entries",
+            "items": {
+              "type": "object",
+              "properties": {
+                "depth": { "type": "integer" },
+                "text": { "type": "string" },
+                "id": { "type": "string" }
+              }
+            }
+          },
+          "$readingTime": { "type": "integer", "description": "Estimated reading time in minutes" },
+          "$wordCount": { "type": "integer", "description": "Total word count" }
+        }
+      },
+      "MarkdownCollection": {
+        "type": "array",
+        "description": "Sorted, filtered array of MarkdownFileResult objects",
+        "items": { "$ref": "#/$defs/returnTypes/MarkdownFileResult" }
+      }
+    },
+
+    "fields": {
+      "config": {
+        "role": "field",
+        "access": "private",
+        "scope": "instance",
+        "identifier": "config",
+        "type": { "type": "object" },
+        "description": "Raw configuration object passed to the constructor"
+      }
+    },
+
+    "constructor": {
+      "role": "constructor",
+      "$prototype": "Function",
+      "parameters": [
+        { "$ref": "#/$defs/parameters/src" },
+        { "$ref": "#/$defs/parameters/sortBy" },
+        { "$ref": "#/$defs/parameters/sortOrder" },
+        { "$ref": "#/$defs/parameters/limit" },
+        { "$ref": "#/$defs/parameters/directives" },
+        { "$ref": "#/$defs/parameters/basePath" },
+        { "$ref": "#/$defs/parameters/itemSchema" }
+      ],
+      "body": ["this.config = config;"],
+      "description": "Stores the configuration for deferred resolution"
+    },
+
+    "methods": {
+      "resolve": {
+        "role": "method",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "instance",
+        "identifier": "resolve",
+        "parameters": [],
+        "returnType": { "$ref": "#/$defs/returnTypes/MarkdownCollection" },
+        "description": "Glob files, parse each, sort, filter, and limit. Returns array of MarkdownFileResult."
+      }
+    }
+  }
+}

package/src/MarkdownFile.class.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jxsuite.com/schemas/MarkdownFile.class.json",
+  "title": "MarkdownFile",
+  "description": "Load and parse a single Markdown file",
+  "$prototype": "Class",
+  "extends": "Object",
+  "$implementation": "./md.js",
+
+  "$defs": {
+    "parameters": {
+      "src": {
+        "identifier": "src",
+        "type": { "type": "string" },
+        "description": "Path to markdown file",
+        "examples": ["./content/about.md"]
+      },
+      "directives": {
+        "identifier": "directives",
+        "type": { "type": "boolean", "default": false },
+        "description": "Enable remark-directive plugin"
+      },
+      "basePath": {
+        "identifier": "basePath",
+        "type": { "type": "string" },
+        "description": "Base path for resolving src"
+      }
+    },
+
+    "returnTypes": {
+      "MarkdownFileResult": {
+        "type": "object",
+        "description": "Parsed markdown file result",
+        "properties": {
+          "slug": { "type": "string", "description": "Filename without extension" },
+          "path": { "type": "string", "description": "Absolute file path" },
+          "frontmatter": { "type": "object", "description": "YAML frontmatter key-value pairs" },
+          "$body": { "type": "string", "description": "Rendered HTML string" },
+          "$excerpt": { "type": "string", "description": "First paragraph as plain text" },
+          "$toc": {
+            "type": "array",
+            "description": "Table of contents entries",
+            "items": {
+              "type": "object",
+              "properties": {
+                "depth": { "type": "integer" },
+                "text": { "type": "string" },
+                "id": { "type": "string" }
+              }
+            }
+          },
+          "$readingTime": { "type": "integer", "description": "Estimated reading time in minutes" },
+          "$wordCount": { "type": "integer", "description": "Total word count" }
+        }
+      }
+    },
+
+    "fields": {
+      "config": {
+        "role": "field",
+        "access": "private",
+        "scope": "instance",
+        "identifier": "config",
+        "type": { "type": "object" },
+        "description": "Raw configuration object passed to the constructor"
+      }
+    },
+
+    "constructor": {
+      "role": "constructor",
+      "$prototype": "Function",
+      "parameters": [
+        { "$ref": "#/$defs/parameters/src" },
+        { "$ref": "#/$defs/parameters/directives" },
+        { "$ref": "#/$defs/parameters/basePath" }
+      ],
+      "body": ["this.config = config;"],
+      "description": "Stores the configuration for deferred resolution"
+    },
+
+    "methods": {
+      "resolve": {
+        "role": "method",
+        "$prototype": "Function",
+        "access": "public",
+        "scope": "instance",
+        "identifier": "resolve",
+        "parameters": [],
+        "returnType": { "$ref": "#/$defs/returnTypes/MarkdownFileResult" },
+        "description": "Parse and resolve the markdown file into a MarkdownFileResult"
+      }
+    }
+  }
+}

package/src/md.js

@@ -0,0 +1,372 @@
+/**
+ * jxsuite/md — Markdown integration for Jx
+ *
+ * Provides three exports:
+ *   - MarkdownFile       — Parse a single markdown file (external class for $prototype)
+ *   - MarkdownCollection — Parse a glob of markdown files as a content collection
+ *   - MarkdownDirective  — Remark plugin mapping directives to custom element tags
+ *
+ * Built on the unified/remark/rehype ecosystem. No framework dependency.
+ *
+ * @module @jxsuite/md
+ * @license MIT
+ */
+
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkParseFrontmatter from "remark-parse-frontmatter";
+import remarkGfm from "remark-gfm";
+import remarkDirective from "remark-directive";
+import remarkRehype from "remark-rehype";
+import rehypeStringify from "rehype-stringify";
+import { readFileSync } from "node:fs";
+import { basename, extname, resolve as resolvePath } from "node:path";
+import { globSync } from "glob";
+
+// ─── Tree utilities (inline to avoid Bun ESM resolution issues with unist-util-*) ──
+
+/**
+ * Walk an AST tree, calling visitor for nodes matching the given type.
+ *
+ * @param {any} tree
+ * @param {string | function} typeOrVisitor
+ * @param {function} [maybeVisitor]
+ */
+function visit(tree, typeOrVisitor, maybeVisitor) {
+  const type = typeof typeOrVisitor === "string" ? typeOrVisitor : null;
+  const visitor = type ? maybeVisitor : typeOrVisitor;
+
+  function walk(/** @type {any} */ 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);
+}
+
+/**
+ * Serialize an mdast tree to plain text.
+ *
+ * @param {any} node
+ * @returns {string}
+ */
+function mdastToString(node) {
+  if (!node) return "";
+  if (typeof node === "string") return node;
+  if (node.value) return node.value;
+  if (Array.isArray(node.children)) return node.children.map(mdastToString).join("");
+  return "";
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Estimate reading time based on word count (~200 wpm average).
+ *
+ * @param {string} text
+ * @returns {number} Minutes (rounded up, minimum 1)
+ */
+function readingTime(text) {
+  const words = text.split(/\s+/).filter(Boolean).length;
+  return Math.max(1, Math.ceil(words / 200));
+}
+
+/**
+ * Extract table of contents entries from an mdast tree.
+ *
+ * @param {object} tree - Mdast AST
+ * @returns {{ depth: number; text: string; id: string }[]}
+ */
+function extractToc(tree) {
+  /** @type {{ depth: number; text: string; id: string }[]} */
+  const entries = [];
+  visit(tree, "heading", (/** @type {any} */ node) => {
+    const text = mdastToString(node);
+    const id = text
+      .toLowerCase()
+      .replace(/[^\w\s-]/g, "")
+      .replace(/\s+/g, "-")
+      .replace(/-+/g, "-")
+      .replace(/^-|-$/g, "");
+    entries.push({ depth: node.depth, text, id });
+  });
+  return entries;
+}
+
+/**
+ * Extract first paragraph as HTML excerpt from an mdast tree.
+ *
+ * @param {object} tree - Mdast AST
+ * @returns {Promise<string>} HTML string of first paragraph, or empty string
+ */
+async function extractExcerpt(tree) {
+  /** @type {any} */
+  let firstParagraph = null;
+  visit(tree, "paragraph", (/** @type {any} */ node) => {
+    if (!firstParagraph) firstParagraph = node;
+  });
+  if (!firstParagraph) return "";
+  const excerptTree = { type: "root", children: [firstParagraph] };
+  const result = await unified()
+    .use(remarkRehype)
+    .use(rehypeStringify)
+    .stringify(
+      /** @type {any} */ (await unified().use(remarkRehype).run(/** @type {any} */ (excerptTree))),
+    );
+  return String(result);
+}
+
+/**
+ * Build the unified processing pipeline with standard plugins.
+ *
+ * @param {object} config
+ * @param {any} [config.directiveOptions]
+ * @param {any[]} [config.remarkPlugins]
+ * @param {any[]} [config.rehypePlugins]
+ * @returns {any} Unified processor
+ */
+function buildProcessor(config = {}) {
+  let processor = unified()
+    .use(remarkParse)
+    .use(remarkFrontmatter, ["yaml"])
+    .use(remarkParseFrontmatter)
+    .use(remarkGfm)
+    .use(remarkDirective)
+    .use(/** @type {any} */ (MarkdownDirective), config.directiveOptions ?? {});
+
+  for (const plugin of config.remarkPlugins ?? []) {
+    processor = Array.isArray(plugin) ? processor.use(plugin[0], plugin[1]) : processor.use(plugin);
+  }
+
+  processor = processor.use(remarkRehype, { allowDangerousHtml: true });
+
+  for (const plugin of config.rehypePlugins ?? []) {
+    processor = Array.isArray(plugin) ? processor.use(plugin[0], plugin[1]) : processor.use(plugin);
+  }
+
+  processor = /** @type {any} */ (
+    processor.use(rehypeStringify, /** @type {any} */ ({ allowDangerousHtml: true }))
+  );
+
+  return processor;
+}
+
+/**
+ * Process a single markdown source string into a MarkdownFileResult.
+ *
+ * @param {string} source - Raw markdown string
+ * @param {string} filePath - File path (for slug derivation)
+ * @param {any} config - Processing options
+ * @returns {Promise<object>} MarkdownFileResult
+ */
+async function processMarkdown(source, filePath, config = {}) {
+  const processor = buildProcessor(config);
+
+  const vfile = await processor.process(source);
+  const frontmatter = /** @type {any} */ (vfile.data)?.frontmatter ?? {};
+
+  // Parse a separate tree for TOC/excerpt extraction (without rehype transform)
+  const mdProcessor = unified().use(remarkParse).use(remarkFrontmatter, ["yaml"]).use(remarkGfm);
+  const tree = mdProcessor.parse(source);
+
+  const plainText = mdastToString(tree);
+  const toc = extractToc(tree);
+  const excerpt = await extractExcerpt(tree);
+  const slug = basename(filePath, extname(filePath));
+
+  return {
+    slug,
+    path: filePath,
+    frontmatter,
+    $body: String(vfile),
+    $excerpt: excerpt,
+    $toc: toc,
+    $readingTime: readingTime(plainText),
+    $wordCount: plainText.split(/\s+/).filter(Boolean).length,
+  };
+}
+
+/**
+ * Resolve a dot-notation path within an object.
+ *
+ * @param {any} obj
+ * @param {string} path
+ * @returns {any}
+ */
+function getNestedValue(obj, path) {
+  return path.split(".").reduce((/** @type {any} */ o, k) => o?.[k], obj);
+}
+
+// ─── MarkdownFile ─────────────────────────────────────────────────────────────
+
+/**
+ * Parse a single markdown file. Satisfies the Jx external class contract ($prototype).
+ *
+ * @example
+ *   { "$prototype": "MarkdownFile", "$src": "@jxsuite/md", "src": "./content/about.md" }
+ */
+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 {string} [config.basePath] - Base path for resolving src
+   * @param {boolean} [config.directives] - Enable directive support
+   */
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Parse and resolve the markdown file.
+   *
+   * @returns {Promise<object>} MarkdownFileResult
+   */
+  async resolve() {
+    const { src, basePath, ...processorConfig } = this.config;
+    const filePath = basePath ? resolvePath(basePath, src) : resolvePath(src);
+    const source = readFileSync(filePath, "utf-8");
+    return processMarkdown(source, filePath, processorConfig);
+  }
+}
+
+// ─── MarkdownCollection ───────────────────────────────────────────────────────
+
+/**
+ * Parse a glob of markdown files into a sorted, filterable array. Satisfies the Jx external class
+ * contract ($prototype).
+ *
+ * @example
+ *   { "$prototype": "MarkdownCollection", "$src": "@jxsuite/md", "src": "./posts/*.md" }
+ */
+export class MarkdownCollection {
+  /**
+   * @param {object} config
+   * @param {string} config.src - Glob pattern or directory path
+   * @param {string} [config.sortBy] Default is `'frontmatter.date'`
+   * @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 {string} [config.basePath] - Base path for resolving glob
+   * @param {boolean} [config.directives] - Enable directive support
+   */
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Glob files, parse each, sort, filter, and limit.
+   *
+   * @returns {Promise<object[]>} Array of MarkdownFileResult
+   */
+  async resolve() {
+    const {
+      src,
+      sortBy = "frontmatter.date",
+      sortOrder = "desc",
+      limit,
+      filter,
+      basePath,
+      ...processorConfig
+    } = this.config;
+
+    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 results = await Promise.all(
+      files.map(async (filePath) => {
+        const source = readFileSync(filePath, "utf-8");
+        return processMarkdown(source, filePath, processorConfig);
+      }),
+    );
+
+    // Filter
+    let filtered = results;
+    if (typeof filter === "function") {
+      filtered = results.filter(/** @type {any} */ (filter));
+    }
+
+    // Sort
+    filtered.sort((a, b) => {
+      const aVal = getNestedValue(a, sortBy) ?? "";
+      const bVal = getNestedValue(b, sortBy) ?? "";
+      if (aVal < bVal) return sortOrder === "asc" ? -1 : 1;
+      if (aVal > bVal) return sortOrder === "asc" ? 1 : -1;
+      return 0;
+    });
+
+    // Limit
+    if (limit && limit > 0) {
+      return filtered.slice(0, limit);
+    }
+
+    return filtered;
+  }
+}
+
+// ─── MarkdownDirective ────────────────────────────────────────────────────────
+
+/**
+ * Remark plugin: map markdown directives to custom element tags in HTML output.
+ *
+ * Works with `remark-directive` — must be placed after it in the pipeline. Converts
+ * ::directive-name{attrs} → <directive-name attrs> in hast output.
+ *
+ * @example
+ *   unified()
+ *     .use(remarkParse)
+ *     .use(remarkDirective)
+ *     .use(MarkdownDirective, { prefix: "jx-" })
+ *     .use(remarkRehype)
+ *     .use(rehypeStringify);
+ *
+ * @param {object} [options]
+ * @param {string} [options.prefix] - Prefix for directives without hyphens. Default is `'jx-'`
+ * @param {boolean} [options.passContent] - Pass container content as slot. Default is `true`
+ * @param {string[]} [options.allowedNames] - Whitelist of allowed directive names
+ * @returns {function} Remark plugin transform function
+ */
+export function MarkdownDirective(options = {}) {
+  const { prefix = "jx-", passContent = true, allowedNames } = options;
+
+  return (/** @type {any} */ tree) => {
+    visit(tree, (/** @type {any} */ node) => {
+      if (
+        node.type === "leafDirective" ||
+        node.type === "containerDirective" ||
+        node.type === "textDirective"
+      ) {
+        const rawName = node.name;
+
+        // Check whitelist
+        if (allowedNames && !allowedNames.includes(rawName)) return;
+
+        // Custom element names must contain a hyphen per Web Components spec
+        const tagName = rawName.includes("-") ? rawName : `${prefix}${rawName}`;
+
+        // Set hast properties for remarkRehype
+        const data = node.data || (node.data = {});
+        data.hName = tagName;
+        data.hProperties = { ...node.attributes };
+
+        // For text directives, preserve label as children
+        if (node.type === "textDirective" && node.children?.length > 0) {
+          // Children are already part of the mdast node; remarkRehype handles them
+        }
+
+        // For container directives, content is already in node.children
+        if (node.type === "containerDirective" && !passContent) {
+          node.children = [];
+        }
+      }
+    });
+  };
+}