sommark 4.0.3 → 4.1.0

package/mappers/languages/mdx.js

@@ -1,5 +1,5 @@
 import Mapper from "../mapper.js";
-import MARKDOWN, { renderHeading } from "./markdown.js";
+import MARKDOWN from "./markdown.js";
 import { VOID_ELEMENTS } from "../../constants/void_elements.js";
 
 /**
@@ -28,14 +28,14 @@ const MDX = Mapper.define({
 
 		return {
 			render: (ctx) => {
-				const { args, content } = ctx;
+				const { args, content, isSelfClosing } = ctx;
 				const element = this.tag(tagName).jsxProps(args);
-				return isVoid ? element.selfClose() : element.body(content);
+				return (isSelfClosing || isVoid) ? element.selfClose() : element.body(content);
 			},
 			options: {
 				type: isVoid ? "Block" : (isCodeStyleOrScript ? ["Block", "AtBlock"] : ["Block", "Inline", "AtBlock"]),
 				escape: !isCodeStyleOrScript,
-				rules: { is_self_closing: isVoid }
+				rules: { is_empty_body: isVoid }
 			}
 		};
 	},
@@ -48,14 +48,22 @@ const MDX = Mapper.define({
 	 * Formats a plain text node with Markdown escaping.
 	 */
 	text(text, options) {
-		return MARKDOWN.text.call(this, text, options);
+		let out = text;
+		if (options?.escape !== false) {
+			out = this.escapeHTML(out);
+		}
+		return out;
 	},
 
 	/**
 	 * Formats inline content before rendering, respecting explicit escape flags.
 	 */
 	inlineText(text, options) {
-		return MARKDOWN.inlineText.call(this, text, options);
+		let out = text;
+		if (options?.escape !== false) {
+			out = this.escapeHTML(out);
+		}
+		return out;
 	},
 
 	/**
@@ -66,9 +74,6 @@ const MDX = Mapper.define({
 		if (options?.escape !== false) {
 			out = this.escapeHTML(out);
 		}
-		if (out.includes('\n')) {
-			out = '\n' + out + '\n';
-		}
 		return out;
 	}
 });
@@ -76,13 +81,17 @@ const MDX = Mapper.define({
 const { tag } = MDX;
 
 MDX.inherit(MARKDOWN);
-MDX.md = MARKDOWN.md; // Provide the Markdown escaping tool
+MDX.md = MARKDOWN.md;
 
-// MDX defaults to HTML tags for headings to ensure high-fidelity JSX output
-["h1", "h2", "h3", "h4", "h5", "h6"].forEach(heading => {
-	MDX.register(heading, function (ctx) {
-		return renderHeading.call(this, ctx, "html");
-	}, { type: "Block" });
+["h1", "h2", "h3", "h4", "h5", "h6"].forEach(h => {
+	MDX.register(h, function ({ args, content }) {
+		const format = this.safeArg({ args, key: "format", fallBack: "" });
+		if (format === "md" || format === "markdown") {
+			return this.md.heading(content, h.slice(1) || 1);
+		}
+		delete args.format;
+		return tag(h).jsxProps(args).body(content);
+	});
 });
 
 /**
@@ -92,4 +101,30 @@ MDX.register("mdx", ({ content }) => {
 	return content;
 }, { escape: false, type: "AtBlock" });
 
+// Inline CSS tag (Moved from shared)
+MDX.register("css", ({ args, content }) => {
+	// Compile style from named arguments (keys that are not numeric digits)
+	const namedStyle = Object.keys(args)
+		.filter(k => isNaN(parseInt(k)))
+		.map(k => `${k}:${args[k]}`)
+		.join(";");
+
+	// Fetch positional style string (index 0) or "style" key if present
+	let positionalStyle = MDX.safeArg({ args, index: 0, key: "style", fallBack: "" });
+
+	// Filter out positional styles that are just duplicates of named arguments
+	const hasDuplicateNamed = Object.keys(args)
+		.filter(k => isNaN(parseInt(k)))
+		.some(k => args[k] === positionalStyle);
+
+	if (hasDuplicateNamed) {
+		positionalStyle = "";
+	}
+
+	// Combine both together
+	let style = [positionalStyle, namedStyle].filter(s => s.trim()).join(";");
+
+	return MDX.tag("span").jsxProps({ style }).body(content);
+}, { type: "Inline" });
+
 export default MDX;

package/mappers/languages/text.js

@@ -0,0 +1,67 @@
+import Mapper from "../mapper.js";
+
+/**
+ * The Text Mapper used for plain-text extraction.
+ */
+const TEXT = Mapper.define({
+	options: {
+		trimAndWrapBlocks: false
+	},
+
+	/**
+	 * Comments are discarded in plain-text output.
+	 */
+	comment() {
+		return "";
+	},
+
+	/**
+	 * Comment blocks are discarded in plain-text output.
+	 */
+	commentBlock() {
+		return "";
+	},
+
+	/**
+	 * Runtime logic is discarded in plain-text output.
+	 */
+	runtimeLogic() {
+		return "";
+	},
+
+	/**
+	 * Returns plain text literally.
+	 */
+	text(text) {
+		return text;
+	},
+
+	/**
+	 * Returns inline text literally.
+	 */
+	inlineText(text) {
+		return text;
+	},
+
+	/**
+	 * Returns at-block body text literally.
+	 */
+	atBlockBody(text) {
+		return text;
+	},
+
+	/**
+	 * Fallback for all tags - extracts inner content.
+	 */
+	getUnknownTag(node) {
+		const isBlock = node.type === "Block" || node.type === "ForEach";
+		return {
+			render: ({ content }) => content,
+			options: {
+				type: isBlock ? "Block" : (node.type === "AtBlock" ? "AtBlock" : "Inline")
+			}
+		};
+	}
+});
+
+export default TEXT;

package/mappers/languages/xml.js

@@ -10,7 +10,7 @@ import { registerSharedOutputs } from "../shared/index.js";
  * @param {string} content - The rendered inner content of the tag.
  * @returns {string} The fully rendered XML tag string.
  */
-const renderXmlTag = function (id, args, content) {
+const renderXmlTag = function (id, args, content, isSelfClosing) {
     // XML is case-sensitive, so we use the exact id provided
     const element = this.tag(id);
 
@@ -27,7 +27,7 @@ const renderXmlTag = function (id, args, content) {
 
     const hasBody = typeof content === "string" && content.trim().length > 0;
 
-    if (!hasBody) {
+    if (isSelfClosing || !hasBody) {
         return element.selfClose();
     }
 
@@ -55,7 +55,7 @@ const XML = Mapper.define({
     getUnknownTag(node) {
         const id = node.id;
         return {
-            render: ({ args, content }) => renderXmlTag.call(this, id, args, content),
+            render: ({ args, content, isSelfClosing }) => renderXmlTag.call(this, id, args, content, isSelfClosing),
             options: {
                 type: "any"
             }
@@ -71,13 +71,13 @@ XML.register("xml", ({ args }) => {
     const version = args.version || "1.0";
     const encoding = args.encoding || "UTF-8";
     return `<?xml version="${version}" encoding="${encoding}"?>`;
-}, { type: "Block", rules: { is_self_closing: true } });
+}, { type: "Block", rules: { is_empty_body: true } });
 
 /**
  * Registers the DOCTYPE declaration.
  * Usage: [doctype = root: "note", system: "note.dtd"]
  */
-XML.register("doctype", ({ args }) => {
+XML.register(["DOCTYPE", "doctype"], ({ args }) => {
     const root = args.root || "root";
     const system = args.system;
     const pub = args.public || args.fpi;
@@ -88,7 +88,7 @@ XML.register("doctype", ({ args }) => {
         return `<!DOCTYPE ${root} SYSTEM "${system}">`;
     }
     return `<!DOCTYPE ${root}>`;
-}, { type: "Block", rules: { is_self_closing: true } });
+}, { type: "Block", rules: { is_empty_body: true } });
 
 /**
  * Registers the XML stylesheet processing instruction.

package/mappers/mapper.js

@@ -32,7 +32,13 @@ class Mapper {
 	 * Registers a new tag rule. It needs a name and a function that says how to format it.
 	 * 
 	 * @param {string|Array<string>} id - The name of the tag (like 'Person' or ['p', 'para']).
-	 * @param {Function} renderOutput - The function that formats this tag.
+	 * @param {Function} renderOutput - The function that formats this tag. It receives:
+	 *    - `args`: Tag attributes.
+	 *    - `content`: Formatted inner content.
+	 *    - `textContent`: Raw inner text.
+	 *    - `nodeType`: Type of node (Block, Inline, etc.).
+	 *    - `isSelfClosing`: (Blocks only) True if marked with !.
+	 *    - `ast`: The full AST node.
 	 * @param {Object} [options={ escape: true }] - Settings for this tag.
 	 * @param {boolean} [options.escape=true] - If true, the content will be made safe for HTML automatically.
 	 */
@@ -48,12 +54,18 @@ class Mapper {
 		if (typeof renderOutput !== "function") {
 			throw new TypeError("argument 'renderOutput' expected to be a function");
 		}
-		
+
 		const render = renderOutput;
 
-		// Prevent duplicate IDs by removing any existing overlap before registering
+		// -- RESERVED KEYWORD PROTECTION --
+		// We protect core engine keywords that would cause syntax errors if used as tag names.
+		const RESERVED = new Set(["end", "import", "slot", "$use-module", "for-each"]);
 		const ids = Array.isArray(id) ? id : [id];
+
 		for (const singleId of ids) {
+			if (RESERVED.has(singleId.toLowerCase())) {
+				sommarkError(`<$red:Reserved Keyword Error:$> Cannot register mapper for <$yellow:${singleId}$>. This is a protected SomMark engine keyword.`);
+			}
 			this.removeOutput(singleId);
 		}
 
@@ -85,6 +97,10 @@ class Mapper {
 	 * @param {string} id - The output identifier to remove.
 	 */
 	removeOutput(id) {
+		if (typeof id !== "string") {
+			throw new TypeError("argument 'id' expected to be a string");
+		}
+
 		this.outputs = this.outputs
 			.map(output => {
 				if (Array.isArray(output.id)) {
@@ -120,6 +136,15 @@ class Mapper {
 		return "";
 	}
 
+	/**
+	 * Placeholder for block comment rendering. Should be overridden by specific mappers.
+	 * @param {string} text - The raw comment text.
+	 * @returns {string} - The formatted block comment string.
+	 */
+	commentBlock(text, indent = "") {
+		return this.comment(text);
+	}
+
 	/**
 	 * Formats a plain text node.
 	 * @param {string} text - The raw text content.
@@ -150,6 +175,13 @@ class Mapper {
 		return text;
 	}
 
+	/**
+	 * Formats runtime logic blocks natively.
+	 * By default, this returns an empty string to discard logic for formats like JSON/MDX.
+	 */
+	runtimeLogic(code, isGlobal) {
+		return "";
+	}
 
 	/**
 	 * Handles unknown tags. Should be overridden by specific mappers to provide fallback behavior.
@@ -245,7 +277,7 @@ class Mapper {
 		}));
 
 		newMapper.customProps = new Set(this.customProps);
-		
+
 		return newMapper;
 	}
 

package/mappers/shared/index.js

@@ -1,22 +1,21 @@
+import { runtimeError } from "../../core/errors.js";
+
 /**
- * Registers shared utility tags across HTML, Markdown, and MDX mappers.
+ * Registers universal utility tags shared across all SomMark mappers.
+ * These tags are considered "Format Agnostic."
+ * 
  * @param {Mapper} mapper - The mapper instance to register tags on.
  */
 export function registerSharedOutputs(mapper) {
     // 1. 'raw' - AtBlock that return the raw, unparsed content.
-    mapper.register("raw", ({ content }) => content, { 
+    mapper.register("raw", ({ content, nodeType }) => {
+        if (nodeType === "Block") {
+            return String(content);
+        }
+        return content;
+    }, {
         type: "AtBlock",
-        escape: false 
-    });
-
-    // 2. 'css' - An Inline tag that applies inline styles to its content.
-    // Usage: (text)->(css: "color: red")
-    mapper.register("css", ({ args, content }) => {
-        let style = mapper.safeArg({ args, index: 0, key: "style", fallBack: "" });
-        style = style.split(";").map(s => s.trim().split(":").map(s => s.trim()).join(":")).join(";");
-        return mapper.tag("span").attributes({ style }).body(content);
-    }, { 
-        type: "Inline" 
+        escape: false
     });
 
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sommark",
-	"version": "4.0.3",
+	"version": "4.1.0",
 	"description": "SomMark is a declarative, extensible markup language for structured content that can be converted to HTML, Markdown, MDX, JSON, XML, and more.",
 	"main": "index.js",
 	"files": [
@@ -61,10 +61,15 @@
 	"devDependencies": {
 		"@mdx-js/mdx": "^3.1.1",
 		"fast-xml-parser": "^5.5.11",
+		"isomorphic-dompurify": "^3.14.0",
 		"jsdom": "^29.0.2",
 		"remark": "^15.0.1",
 		"remark-gfm": "^4.0.1",
 		"remark-parse": "^11.0.0",
 		"vitest": "^4.0.16"
+	},
+	"dependencies": {
+		"@sebastianwessel/quickjs": "^1.1.1",
+		"acorn": "^8.15.0"
 	}
 }

package/core/formatter.js

@@ -1,215 +0,0 @@
-import { IMPORT, USE_MODULE, TEXT, INLINE, BLOCK, ATBLOCK, COMMENT } from "./labels.js";
-
-/**
- * Turns an AST back into a clean SomMark source string.
- * This is useful for "pretty-printing" or saving changes back to a file.
- * 
- * @param {Object[]|Object} ast - The AST or single node to turn into text.
- * @param {Object} [options] - Optional settings for formatting.
- * @returns {string} - The final SomMark source code.
- */
-export function formatAST(ast, options = {}) {
-	const indentStr = options.indentString || "\t";
-
-	// -- Escaping Helpers ----------------------------------------------------- //
-	
-	/**
-	 * Escapes special characters in argument values so they don't break the syntax.
-	 * 
-	 * @param {any} val - The value to escape.
-	 * @param {string} type - The type of tag (e.g., Block or Inline).
-	 * @returns {string} - The safely escaped text.
-	 */
-	const escapeArg = (val, type) => {
-		let escaped = String(val).replace(/\\/g, "\\\\").replace(/,/g, "\\,");
-		if (type === BLOCK || type === ATBLOCK) escaped = escaped.replace(/:/g, "\\:");
-		if (type === ATBLOCK) escaped = escaped.replace(/;/g, "\\;");
-		if (type === BLOCK && escaped.startsWith("=")) escaped = escaped.replace(/^=/, "\\=");
-		return escaped;
-	};
-
-	/**
-	 * Escapes characters in the left side of an inline statement (the text in parentheses).
-	 * 
-	 * @param {any} val - The text inside parentheses.
-	 * @returns {string} - The safely escaped text.
-	 */
-	const escapeInlineValue = (val) => String(val).replace(/\\/g, "\\\\").replace(/\)/g, "\\)");
-
-	/**
-	 * Escapes special characters in plain text so they aren't mistaken for SomMark tags.
-	 * 
-	 * @param {string} str - The raw text to escape.
-	 * @returns {string} - The safe text.
-	 */
-	const escapeText = (str) => {
-		return String(str)
-			.replace(/\\/g, "\\\\")
-			.replace(/\[/g, "\\[")
-			.replace(/\]/g, "\\]")
-			.replace(/\(/g, "\\(")
-			.replace(/\)/g, "\\)")
-			.replace(/->/g, "\\->")
-			.replace(/@_/g, "\\@_")
-			.replace(/_@/g, "\\_@")
-			.replace(/#/g, "\\#");
-	};
-
-	/**
-	 * Checks if a value needs to be wrapped in double quotes (like if it has spaces or commas).
-	 * 
-	 * @param {any} val - The value to check.
-	 * @returns {boolean} - True if quotes are needed.
-	 */
-	const shouldQuote = (val) => {
-		if (typeof val !== "string") return false;
-		return /[ \t\n\r,:[\]()@#]/.test(val);
-	};
-
-	// -- Formatting Logic ----------------------------------------------------- //
-	
-	/**
-	 * Formats the arguments of a node into a SomMark string (e.g., "= key: value, 123").
-	 * 
-	 * @param {Object} args - The list of arguments to format.
-	 * @param {string} type - The type of tag.
-	 * @returns {string} - The final formatted argument string.
-	 */
-	const formatArgs = (args, type) => {
-		if (!args || Object.keys(args).length === 0) return "";
-		let usedKeys = new Set();
-		let formattedArgs = [];
-
-		const keys = Object.keys(args);
-		const positionalCount = keys.filter(k => !isNaN(parseInt(k))).length;
-
-		for (let i = 0; i < positionalCount; i++) {
-			let val = args[i];
-			let matchedKey = null;
-
-			// Find if this value has a named alias
-			if (type !== INLINE) {
-				for (const key of keys) {
-					if (isNaN(parseInt(key)) && args[key] === val && !usedKeys.has(key)) {
-						matchedKey = key;
-						usedKeys.add(key);
-						break;
-					}
-				}
-			}
-
-			let escapedVal = escapeArg(val, type);
-			if (shouldQuote(val)) {
-				const quotedVal = String(val).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-				escapedVal = `"${quotedVal}"`;
-			}
-
-			if (matchedKey) formattedArgs.push(`${matchedKey}: ${escapedVal}`);
-			else formattedArgs.push(escapedVal);
-		}
-
-		const res = formattedArgs.join(", ");
-		if (!res) return "";
-
-		if (type === BLOCK || type === IMPORT || type === USE_MODULE) return " = " + res;
-		if (type === ATBLOCK) return ": " + res + ";";
-		if (type === INLINE) return ": " + res;
-		return res;
-	};
-
-	/**
-	 * Formats a list of nodes (like the body of a block) into indented SomMark source.
-	 * It also handles the correct spacing between text and inline tags.
-	 * 
-	 * @param {Object[]} body - The list of content nodes.
-	 * @param {number} depth - How far to indent the text.
-	 * @returns {string} - The final formatted text content.
-	 */
-	const formatBody = (body, depth) => {
-		if (!body || !Array.isArray(body)) return "";
-		const innerIndentStr = depth >= 0 ? indentStr.repeat(depth) : "";
-		let result = "";
-		let currentText = "";
-
-		const flushText = () => {
-			if (!currentText) return;
-			const cleanText = currentText
-				.replace(/[ \t]+/g, " ")
-				.replace(/\n([ \t]*\n)+/g, "\n\n")
-				.trim();
-
-			if (cleanText) {
-				const indentedText = cleanText.split("\n").map(line => {
-					return line.trim() ? innerIndentStr + line.trim() : "";
-				}).join("\n");
-				result += `${indentedText}\n`;
-			}
-			currentText = "";
-		};
-
-		for (let i = 0; i < body.length; i++) {
-			const child = body[i];
-			if (child.type === TEXT) {
-				let textStr = escapeText(child.text);
-				if (i > 0 && body[i - 1].type === INLINE) {
-					if (textStr.length > 0 && !/^\s/.test(textStr) && !/^[.,!?;:\])}>"']/.test(textStr)) {
-						textStr = " " + textStr;
-					}
-				}
-				currentText += textStr;
-			} else if (child.type === INLINE) {
-				const argsStr = formatArgs(child.args, INLINE);
-				const inlineVal = child.value ? String(child.value).trim() : "";
-				const inlineStr = `(${escapeInlineValue(inlineVal)})->(${child.id}${argsStr})`;
-				if (i > 0) {
-					const prev = body[i - 1];
-					if (prev.type === INLINE) { if (!/[ \t\n\r]$/.test(currentText)) currentText += " "; }
-					else if (prev.type === TEXT) { if (currentText.length > 0 && !/[ \t\n\r]$/.test(currentText) && !/[({\[<"']$/.test(currentText)) currentText += " "; }
-				}
-				currentText += inlineStr;
-			} else {
-				flushText();
-				if (child.type === BLOCK) {
-					const argsStr = formatArgs(child.args, BLOCK);
-					// Check if it's a self-closing block (Rules support)
-					const isSelfClosing = child.rules?.is_self_closing;
-					if (isSelfClosing && (!child.body || child.body.length === 0)) {
-						result += `${innerIndentStr}[${child.id}${argsStr}][end]\n`;
-					} else {
-						result += `${innerIndentStr}[${child.id}${argsStr}]\n`;
-						result += formatBody(child.body, depth + 1);
-						result += `${innerIndentStr}[end]\n`;
-					}
-				} else if (child.type === ATBLOCK) {
-					const argsStr = formatArgs(child.args, ATBLOCK);
-					const atHeader = argsStr ? `@_${child.id}_@${argsStr}` : `@_${child.id}_@;`;
-					result += `${innerIndentStr}${atHeader}\n`;
-					if (child.content) {
-						const lines = child.content.replace(/\r\n/g, "\n").split("\n");
-						while (lines.length && !lines[0].trim()) lines.shift();
-						while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
-						let minIndent = Infinity;
-						for (const line of lines) { if (line.trim()) { const leading = line.match(/^[ \t]*/)[0].length; if (leading < minIndent) minIndent = leading; } }
-						if (minIndent === Infinity) minIndent = 0;
-						const indentedContent = lines.map(line => line.trim() ? innerIndentStr + indentStr + line.substring(minIndent) : "").join("\n");
-						result += indentedContent + "\n";
-					}
-					result += `${innerIndentStr}@_end_@\n`;
-				} else if (child.type === COMMENT) {
-					result += `${innerIndentStr}# ${child.text.replace(/^#+\s*/, "").trim()}\n`;
-				} else if (child.type === IMPORT) {
-					const argsStr = formatArgs(child.args, IMPORT);
-					result += `${innerIndentStr}[import${argsStr}][end]\n`;
-				} else if (child.type === USE_MODULE) {
-					const argsStr = formatArgs(child.args, USE_MODULE);
-					result += `${innerIndentStr}[$use-module${argsStr}][end]\n`;
-				}
-			}
-		}
-		flushText();
-		return result;
-	};
-
-	const rootNodes = Array.isArray(ast) ? ast : [ast];
-	return formatBody(rootNodes, 0).trim() + "\n";
-}