@jxsuite/markup 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# @jxsuite/markup
+
+Browser-safe markup conversion utilities shared by the Jx core packages:
+
+- `@jxsuite/markup/html-to-jx` — `htmlToJx(html)` converts an HTML string into
+  an array of Jx tree nodes (`JxElement | string`), mapping attributes through
+  `property-information` and inline `style` strings into style objects.
+- `@jxsuite/markup/md-html` — `markdownToHtml(markdown)` renders untrusted
+  markdown (GFM tables/strikethrough/task lists) to a **sanitized** HTML
+  string: raw HTML is dropped, event handlers and `javascript:` URLs are
+  stripped.
+
+Both pipelines are DOM-free and node-free — no `node:*` imports — so they are
+safe for any bundle target (Jx Studio, Cloudflare Workers, node/Bun CLIs).
+The package root re-exports both functions.
+
+```ts
+import { htmlToJx, markdownToHtml } from "@jxsuite/markup";
+
+htmlToJx('<p class="x">Hello</p>');
+// → [{ tagName: "p", attributes: { class: "x" }, textContent: "Hello" }]
+
+markdownToHtml("# Hi\n\n**bold**");
+// → "<h1>Hi</h1>\n<p><strong>bold</strong></p>"
+```
+
+For markdown → Jx _document_ transpilation (frontmatter, directives, Jx
+markdown), use `@jxsuite/parser` — this package deliberately stays a thin,
+dependency-light conversion layer.
+
+## Versioning
+
+The types are published as TypeScript source (like every `@jxsuite` package)
+and follow the monorepo's release train. Within the monorepo, packages depend
+on it via `workspace:^`. Consumers install `@jxsuite/markup` and import its
+`/html-to-jx` and `/md-html` entrypoints (or the root re-export); its only
+`@jxsuite` runtime dependency is `@jxsuite/schema`.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@jxsuite/markup",
+  "version": "0.1.0",
+  "description": "Browser-safe markup conversion: HTML → Jx nodes, markdown → sanitized HTML",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jxsuite/jx.git",
+    "directory": "packages/markup"
+  },
+  "files": [
+    "src/"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./html-to-jx": "./src/html-to-jx.ts",
+    "./md-html": "./src/md-html.ts"
+  },
+  "publishConfig": {
+    "provenance": false
+  },
+  "scripts": {
+    "test": "bun test --isolate",
+    "test:coverage": "bun test --isolate --coverage",
+    "upgrade": "bunx npm-check-updates -u && bun install"
+  },
+  "dependencies": {
+    "@jxsuite/schema": "workspace:^",
+    "hast-util-from-html": "^2.0.3",
+    "hast-util-whitespace": "^3.0.0",
+    "property-information": "^7.2.0",
+    "rehype-sanitize": "^6.0.0",
+    "rehype-stringify": "^10.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "unified": "^11.0.5"
+  },
+  "devDependencies": {
+    "@types/hast": "3.0.5"
+  }
+}

package/src/html-to-jx.ts

@@ -0,0 +1,121 @@
+import { fromHtml } from "hast-util-from-html";
+import { whitespace } from "hast-util-whitespace";
+import { find, html as htmlInfo } from "property-information";
+
+import type { Nodes as HastNode } from "hast";
+import type { JxElement } from "@jxsuite/schema/types";
+
+/**
+ * Convert an HTML string into an array of Jx tree nodes.
+ *
+ * @param {string} htmlString
+ * @returns {(JxElement | string)[]}
+ */
+export function htmlToJx(htmlString: string) {
+  const hast = fromHtml(htmlString, { fragment: true });
+  return convertHastChildren(hast.children as HastNode[]);
+}
+
+/**
+ * @param {HastNode[]} children
+ * @returns {(JxElement | string)[]}
+ */
+function convertHastChildren(children: HastNode[]) {
+  const result: (JxElement | string)[] = [];
+  for (const child of children) {
+    const converted = convertHastNode(child);
+    if (converted != null) {
+      result.push(converted);
+    }
+  }
+  return result;
+}
+
+/**
+ * @param {HastNode} node
+ * @returns {JxElement | string | null}
+ */
+function convertHastNode(node: HastNode) {
+  if (node.type === "text") {
+    if (whitespace(node as unknown as HastNode)) {
+      return null;
+    }
+    return node.value ?? null;
+  }
+
+  if (node.type === "element") {
+    const el: JxElement = { tagName: node.tagName };
+
+    if (node.properties && Object.keys(node.properties).length > 0) {
+      const { style, attrs } = hastPropsToJx(node.properties);
+      if (Object.keys(attrs).length > 0) {
+        el.attributes = attrs;
+      }
+      if (Object.keys(style).length > 0) {
+        el.style = style;
+      }
+    }
+
+    const kids = node.children ? convertHastChildren(node.children) : [];
+
+    if (kids.length === 1 && typeof kids[0] === "string") {
+      [el.textContent] = kids;
+    } else if (kids.length > 0) {
+      el.children = kids as JxElement[];
+    }
+
+    return el;
+  }
+
+  return null;
+}
+
+/**
+ * @param {Record<string, unknown>} properties
+ * @returns {{ style: Record<string, string>; attrs: Record<string, string> }}
+ */
+function hastPropsToJx(properties: Record<string, unknown>) {
+  const attrs: Record<string, string> = {};
+  const style: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(properties)) {
+    if (value === false || value === undefined || value === null) {
+      continue;
+    }
+
+    const info = find(htmlInfo, key);
+    const name = info.attribute;
+
+    if (name === "style" && typeof value === "string") {
+      parseInlineStyle(value, style);
+      continue;
+    }
+
+    if (value === true) {
+      attrs[name] = "";
+    } else if (Array.isArray(value)) {
+      attrs[name] = value.join(info.commaSeparated ? ", " : " ");
+    } else {
+      attrs[name] = String(value);
+    }
+  }
+  return { attrs, style };
+}
+
+/**
+ * @param {string} styleStr
+ * @param {Record<string, string>} out
+ */
+function parseInlineStyle(styleStr: string, out: Record<string, string>) {
+  for (const decl of styleStr.split(";")) {
+    const colon = decl.indexOf(":");
+    if (colon === -1) {
+      continue;
+    }
+    const prop = decl.slice(0, colon).trim();
+    const val = decl.slice(colon + 1).trim();
+    if (prop && val) {
+      out[prop] = val;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Markup — browser-safe markup conversion utilities.
+ *
+ * Re-exports the package's two pipelines: `htmlToJx` (HTML string → Jx tree nodes) and
+ * `markdownToHtml` (markdown → sanitized HTML string). Both are DOM-free and node-free, so
+ * they are safe for any bundle target (studio, workers, node).
+ *
+ * @module @jxsuite/markup
+ * @license MIT
+ */
+
+export { htmlToJx } from "./html-to-jx";
+export { markdownToHtml } from "./md-html";

package/src/md-html.ts

@@ -0,0 +1,49 @@
+/**
+ * Md-html — browser-safe markdown → sanitized HTML string
+ *
+ * Small display pipeline for rendering untrusted markdown (e.g. LLM chat output) as
+ * HTML: remark-parse + remark-gfm → remark-rehype (raw HTML disabled) → rehype-sanitize
+ * (default schema: strips scripts, event handlers, javascript:/data: URLs) → stringify.
+ *
+ * Like everything in @jxsuite/markup this module has no node-only imports, so it is safe
+ * for the studio bundle. It intentionally produces an HTML *string*, not Jx nodes — use
+ * `@jxsuite/parser/markdown` for markdown → Jx document transpilation.
+ *
+ * @module @jxsuite/markup/md-html
+ * @license MIT
+ */
+
+import rehypeSanitize from "rehype-sanitize";
+import rehypeStringify from "rehype-stringify";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import { unified } from "unified";
+
+/**
+ * Minimal structural surface of the unified processor used here — same rationale as
+ * `UnifiedProcessor` in @jxsuite/parser's types (oxlint sees the ESM-only unified types as `any`),
+ * plus `processSync` which that shared type doesn't carry.
+ */
+interface MdHtmlProcessor {
+  use: (plugin: unknown, ...options: unknown[]) => MdHtmlProcessor;
+  processSync: (source: string) => { toString: () => string };
+}
+
+const processor = (unified as unknown as () => MdHtmlProcessor)()
+  .use(remarkParse)
+  .use(remarkGfm)
+  .use(remarkRehype)
+  .use(rehypeSanitize)
+  .use(rehypeStringify);
+
+/**
+ * Convert markdown source to a sanitized HTML string (GFM tables/strikethrough/task lists
+ * supported). Raw HTML in the source is dropped, not passed through.
+ *
+ * @param {string} markdown
+ * @returns {string}
+ */
+export function markdownToHtml(markdown: string): string {
+  return String(processor.processSync(markdown));
+}