sommark 3.3.4 → 4.0.0

package/mappers/languages/mdx.js

@@ -1,139 +1,95 @@
 import Mapper from "../mapper.js";
-import MARKDOWN from "./markdown.js";
-import { HTML_TAGS } from "../../constants/html_tags.js";
+import MARKDOWN, { renderHeading } from "./markdown.js";
 import { VOID_ELEMENTS } from "../../constants/void_elements.js";
 
-class MdxMapper extends Mapper {
-	constructor() {
-		super();
-	}
+/**
+ * The MDX Mapper used for generating Markdown with JSX.
+ */
+const MDX = Mapper.define({
+	/**
+	 * Renders a JSX-style comment in MDX output.
+	 * @param {string} text - The raw comment text.
+	 * @returns {string} - Formatted JSX comment string.
+	 */
 	comment(text) {
-		return `{/*${text.replace("#", "")} */}\n`;
-	}
+		return `{/* ${text} */}`;
+	},
+
+	/**
+	 * Provides high-fidelity fallback for unknown tags by rendering them as JSX components.
+	 * @param {Object} node - The unknown AST node.
+	 * @returns {Object} - A virtual tag registration for JSX rendering.
+	 */
 	getUnknownTag(node) {
 		const tagName = node.id;
+		const lowerId = tagName.toLowerCase();
+		const isVoid = VOID_ELEMENTS.has(lowerId);
+		const isCodeStyleOrScript = ["code", "style", "script"].includes(lowerId);
+
 		return {
-			render: ({ args, content }) => {
-				const element = this.tag(tagName);
-				element.props(this.jsxProps(args, tagName));
-				return element.body(content);
+			render: (ctx) => {
+				const { args, content } = ctx;
+				const element = this.tag(tagName).jsxProps(args);
+				return isVoid ? element.selfClose() : element.body(content);
+			},
+			options: {
+				type: isVoid ? "Block" : (isCodeStyleOrScript ? ["Block", "AtBlock"] : ["Block", "Inline", "AtBlock"]),
+				escape: !isCodeStyleOrScript,
+				rules: { is_self_closing: isVoid }
 			}
 		};
-	}
-
-	jsxProps(args, tagName = "div") {
-		const jsxProps = [];
-		const styleObj = {};
-		const isHtmlTag = HTML_TAGS.has(tagName.toLowerCase());
-
-		const keys = Object.keys(args).filter(arg => isNaN(arg));
-		keys.forEach(key => {
-			let val = args[key];
-			const isEvent = key.toLowerCase().startsWith("on");
-
-			let k = key;
-			if (k === "class") k = "className";
-
-			// Quote stripping
-			if (typeof val === "string" && ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'")))) {
-				val = val.slice(1, -1);
-			}
-
-			if (k === "style") {
-				if (typeof val === "string") {
-					const pairs = val.includes(";") ? val.split(";") : val.split(",");
-					pairs.forEach(pair => {
-						let [prop, value] = pair.split(":").map(s => s.trim());
-						if (prop && value) {
-							const camelProp = prop.replace(/-([a-z])/g, g => g[1].toUpperCase());
-							styleObj[camelProp] = value;
-						}
-					});
-				} else if (typeof val === "object") {
-					Object.assign(styleObj, val);
-				}
-			} else {
-				// Detection for expressions
-				const isBoolean = val === "true" || val === "false" || typeof val === "boolean";
-				const isNumeric = val !== "" && !isNaN(val) && typeof val !== "boolean";
-				const looksLikeExpression = typeof val === "string" && 
-					(/[0-9]/.test(val) && /[+\-*/%()]/.test(val)); // Math expression detection
-
-				const shouldBeJSXExpression = isEvent || isBoolean || isNumeric || looksLikeExpression;
-
-				let finalVal = val;
-				if (val === "true") finalVal = true;
-				if (val === "false") finalVal = false;
-				if (isNumeric && typeof val === "string") finalVal = Number(val);
-
-				jsxProps.push({ 
-					__type__: shouldBeJSXExpression ? "other" : "string", 
-					[k]: finalVal 
-				});
-			}
-		});
-
-		if (Object.keys(styleObj).length > 0) {
-			const styleStr = JSON.stringify(styleObj).replace(/"/g, "'").replace(/'([^']+)':/g, '$1:');
-			jsxProps.push({ __type__: "other", style: styleStr });
+	},
+
+	options: {
+		trimAndWrapBlocks: true
+	},
+
+	/**
+	 * Formats a plain text node with Markdown escaping.
+	 */
+	text(text, options) {
+		return MARKDOWN.text.call(this, text, options);
+	},
+
+	/**
+	 * Formats inline content before rendering, respecting explicit escape flags.
+	 */
+	inlineText(text, options) {
+		return MARKDOWN.inlineText.call(this, text, options);
+	},
+
+	/**
+	 * Formats the literal content inside AtBlocks.
+	 */
+	atBlockBody(text, options) {
+		let out = text;
+		if (options?.escape !== false) {
+			out = this.escapeHTML(out);
 		}
-
-		return jsxProps;
+		if (out.includes('\n')) {
+			out = '\n' + out + '\n';
+		}
+		return out;
 	}
-}
+});
 
-const MDX = new MdxMapper();
 const { tag } = MDX;
 
 MDX.inherit(MARKDOWN);
+MDX.md = MARKDOWN.md; // Provide the Markdown escaping tool
 
-// Block for raw MDX content (ESM, etc.)
-MDX.register("mdx", ({ content }) => {
-	// Clean up hidden characters
-	let clean = content.replace(/\u200B/g, "").trim();
-	// Remove leading semicolon to avoid MDX errors
-	if (clean.startsWith(";")) clean = clean.substring(1).trim();
-	// Add spacing around ESM blocks
-	return "\n" + clean + "\n\n";
-}, { escape: false, type: ["AtBlock", "Block"] });
-
-// Re-register HTML tags to use jsxProps
-HTML_TAGS.forEach(tagName => {
-	const capitalized = tagName.charAt(0).toUpperCase() + tagName.slice(1);
-
-	// Register even if it exists in MARKDOWN to override it with JSX version
-	const idsToRegister = [tagName, capitalized];
-
-	MDX.register(
-		idsToRegister,
-		({ args, content }) => {
-			const element = tag(tagName);
-
-			// Auto-ID for Headings
-			if (/^h[1-6]$/i.test(tagName) && !args.id && content && /^[A-Za-z0-9]/.test(content)) {
-				const id = content
-					.toString()
-					.toLowerCase()
-					.replace(/[^\w\s-]/g, "")
-					.replace(/\s+/g, "-");
-				args.id = id;
-			}
-
-			element.props(MDX.jsxProps(args, tagName));
-
-			if (VOID_ELEMENTS.has(tagName)) {
-				return element.selfClose();
-			}
-			return element.body(content);
-		},
-		{
-			escape: false,
-			type: VOID_ELEMENTS.has(tagName) ? "Block" : ["Block", "Inline"],
-			rules: {
-				is_self_closing: VOID_ELEMENTS.has(tagName)
-			}
-		}
-	);
+// 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" });
 });
 
+/**
+ * mdx AtBlock - Renders raw MDX content (ESM imports, exports, or complex JSX).
+ */
+MDX.register("mdx", ({ content }) => {
+	return content;
+}, { escape: false, type: "AtBlock" });
+
 export default MDX;

package/mappers/languages/xml.js

@@ -0,0 +1,114 @@
+import Mapper from "../mapper.js";
+import { registerSharedOutputs } from "../shared/index.js";
+
+/**
+ * Renders a standard XML tag based on the provided identifier and arguments.
+ * Ensures strict attribute quoting and handles self-closing tags for empty bodies.
+ * 
+ * @param {string} id - The XML tag identifier (case-sensitive).
+ * @param {Object} args - Key-value pairs to be rendered as XML attributes.
+ * @param {string} content - The rendered inner content of the tag.
+ * @returns {string} The fully rendered XML tag string.
+ */
+const renderXmlTag = function (id, args, content) {
+    // XML is case-sensitive, so we use the exact id provided
+    const element = this.tag(id);
+
+    // Filter out positional indices (numeric keys) for XML attributes
+    const namedArgs = {};
+    Object.keys(args).forEach(key => {
+        if (isNaN(parseInt(key))) {
+            namedArgs[key] = args[key];
+        }
+    });
+
+    // In XML, attributes must always have values (strict = true)
+    element.attributes(namedArgs, true);
+
+    const hasBody = typeof content === "string" && content.trim().length > 0;
+
+    if (!hasBody) {
+        return element.selfClose();
+    }
+
+    return element.body(content);
+};
+
+/**
+ * The XML Mapper used for creating XML pages.
+ */
+const XML = Mapper.define({
+    /**
+     * Renders a comment in XML format.
+     * @param {string} text - The comment content.
+     * @returns {string}
+     */
+    comment(text) {
+        return `<!-- ${text} -->`;
+    },
+
+    /**
+     * Resolves unknown tags by preserving their original case and applying XML rules.
+     * @param {Object} node - The AST node representing the unknown tag.
+     * @returns {Object} Renderer definition for the tag.
+     */
+    getUnknownTag(node) {
+        const id = node.id;
+        return {
+            render: ({ args, content }) => renderXmlTag.call(this, id, args, content),
+            options: {
+                type: "any"
+            }
+        };
+    }
+});
+
+/**
+ * Registers the XML declaration as a self-closing block.
+ * Usage: [xml = version: "1.0", encoding: "UTF-8"]
+ */
+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 } });
+
+/**
+ * Registers the DOCTYPE declaration.
+ * Usage: [doctype = root: "note", system: "note.dtd"]
+ */
+XML.register("doctype", ({ args }) => {
+    const root = args.root || "root";
+    const system = args.system;
+    const pub = args.public || args.fpi;
+
+    if (pub && system) {
+        return `<!DOCTYPE ${root} PUBLIC "${pub}" "${system}">`;
+    } else if (system) {
+        return `<!DOCTYPE ${root} SYSTEM "${system}">`;
+    }
+    return `<!DOCTYPE ${root}>`;
+}, { type: "Block", rules: { is_self_closing: true } });
+
+/**
+ * Registers the XML stylesheet processing instruction.
+ * Usage: [xml-stylesheet = href: "style.xsl"]
+ */
+XML.register("xml-stylesheet", ({ args }) => {
+    const type = args.type || "text/xsl";
+    const href = args.href;
+    if (!href) return "";
+    return `<?xml-stylesheet type="${type}" href="${href}"?>`;
+}, { type: "Block", rules: { is_self_closing: true } });
+
+/**
+ * Registers CDATA sections.
+ * Usage: @_cdata_@: ; raw content @_end_@
+ */
+XML.register("cdata", ({ content }) => {
+    return `<![CDATA[${content}]]>`;
+}, { type: "AtBlock" });
+
+registerSharedOutputs(XML);
+
+export default XML;

package/mappers/mapper.js

@@ -2,92 +2,40 @@ import TagBuilder from "../formatter/tag.js";
 import MarkdownBuilder from "../formatter/mark.js";
 import escapeHTML from "../helpers/escapeHTML.js";
 import { sommarkError } from "../core/errors.js";
-import { matchedValue, safeArg, htmlTable, list, todo } from "../helpers/utils.js";
+import { matchedValue, safeArg } from "../helpers/utils.js";
 
 
-// ========================================================================== //
-//  Main Mapper Class                                                         //
-// ========================================================================== //
+/**
+ * The base class for all mappers. It manages how tags and blocks are turned into final text.
+ * This is used to build HTML, MDX, and other output formats.
+ */
 class Mapper {
-	#customHeaderContent;
-	// ========================================================================== //
-	//  Constructor                                                               //
-	// ========================================================================== //
+	/**
+	 * Sets up a new mapper with empty lists for rules and tags.
+	 */
 	constructor() {
+		/** @type {Array<Object>} List of rules for formatting tags. */
 		this.outputs = [];
+		/** @type {MarkdownBuilder} Specialized builder for Markdown-related formatting. */
 		this.md = new MarkdownBuilder();
-
-		this.extraProps = new Set(); // For plugins to add recognized arguments
-
-		this.pageProps = {
-			pageTitle: "SomMark Page",
-			tabIcon: {
-				type: "image/x-icon",
-				src: ""
-			},
-			charset: "UTF-8",
-			viewport: "width=device-width, initial-scale=1.0",
-			httpEquiv: { "X-UA-Compatible": "IE=edge" }
-		};
-
-		this.#customHeaderContent = "";
-
+		/** @type {Set<string>} A list of extra property names this mapper understands. */
+		this.customProps = new Set();
+		/** @type {Function} Helper that makes text safe for HTML. */
 		this.escapeHTML = escapeHTML;
-		this.htmlTable = htmlTable;
-		this.list = list;
-		this.todo = todo;
-		this.styles = [];
-	}
-
-	// ========================================================================== //
-	//  Style Management                                                          //
-	// ========================================================================== //
-
-	addStyle(css) {
-		if (typeof css === "object" && css !== null) {
-			let styleString = "";
-			for (const [selector, rules] of Object.entries(css)) {
-				let rulesString = "";
-				for (const [prop, value] of Object.entries(rules)) {
-					rulesString += `${prop}:${value};`;
-				}
-				styleString += `${selector}{${rulesString}}`;
-			}
-			css = styleString;
-		}
-
-		if (typeof css === "string" && css.trim() && !this.styles.includes(css.trim())) {
-			this.styles.push(css.trim());
-		}
+		/** @type {Object} Settings that change how this mapper works. */
+		this.options = {};
 	}
 
+	// -- Tag Registration ---------------------------------------------------- //
 
-	// ========================================================================== //
-	//  Header Generation                                                         //
-	// ========================================================================== //
-	get header() {
-		const { pageTitle, tabIcon, charset, viewport, httpEquiv } = this.pageProps;
-
-		let metas = "";
-		metas += `${this.tag("meta").attributes({ charset }).selfClose()}\n`;
-		metas += `${this.tag("meta").attributes({ name: "viewport", content: viewport }).selfClose()}\n`;
-
-		for (const [key, value] of Object.entries(httpEquiv)) {
-			metas += `${this.tag("meta").attributes({ "http-equiv": key, content: value }).selfClose()}\n`;
-		}
-
-		metas += `${this.tag("title").body(pageTitle)}\n`;
-
-		if (tabIcon && tabIcon.src) {
-			metas += `${this.tag("link").attributes({ rel: "icon", type: tabIcon.type, href: tabIcon.src }).selfClose()}\n`;
-		}
-
-		return metas + this.#customHeaderContent;
-	}
-
-	// ========================================================================== //
-	//  Mappings                                                                  //
-	// ========================================================================== //
+	/**
+	 * 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 {Object} [options={ escape: true }] - Settings for this tag.
+	 * @param {boolean} [options.escape=true] - If true, the content will be made safe for HTML automatically.
+	 */
 	register(id, renderOutput, options = { escape: true }) {
 		if (!id || !renderOutput) {
 			throw new Error("Expected arguments are not defined");
@@ -100,17 +48,8 @@ class Mapper {
 		if (typeof renderOutput !== "function") {
 			throw new TypeError("argument 'renderOutput' expected to be a function");
 		}
-		const render = function (data) {
-			if (
-				typeof data !== "object" ||
-				data === null ||
-				!Object.prototype.hasOwnProperty.call(data, "args") ||
-				!Object.prototype.hasOwnProperty.call(data, "content")
-			) {
-				throw new TypeError("render expects an object with properties { args, content }");
-			}
-			return renderOutput.call(this, data);
-		};
+		
+		const render = renderOutput;
 
 		// Prevent duplicate IDs by removing any existing overlap before registering
 		const ids = Array.isArray(id) ? id : [id];
@@ -121,6 +60,12 @@ class Mapper {
 		this.outputs.push({ id, render, options });
 	}
 
+	/**
+	 * Inherits all registered outputs from one or more other mappers.
+	 * Last-match-wins logic: If an output exists in multiple mappers, the one from the last mapper in the list is used.
+	 * 
+	 * @param {...Mapper} mappers - The mapper instances to inherit from.
+	 */
 	inherit(...mappers) {
 		for (const mapper of mappers) {
 			if (mapper && Array.isArray(mapper.outputs)) {
@@ -135,46 +80,100 @@ class Mapper {
 		}
 	}
 
+	/**
+	 * Removes a specific output registration by its ID.
+	 * @param {string} id - The output identifier to remove.
+	 */
 	removeOutput(id) {
-		this.outputs = this.outputs.filter(output => {
-			if (Array.isArray(output.id)) {
-				return !output.id.some(singleId => singleId === id);
-			} else {
-				return output.id !== id;
-			}
-		});
+		this.outputs = this.outputs
+			.map(output => {
+				if (Array.isArray(output.id)) {
+					// Only remove the specific ID from the array
+					const newIds = output.id.filter(singleId => singleId !== id);
+					if (newIds.length === 0) return null; // Remove entire entry if no IDs left
+					if (newIds.length === output.id.length) return output; // No change
+					return { ...output, id: newIds }; // Return updated entry
+				} else {
+					return output.id === id ? null : output;
+				}
+			})
+			.filter(Boolean); // Clean up nulls
 	}
 
+	/**
+	 * Retrieves a registered output entry (render function and options) by ID.
+	 * @param {string} id - The output identifier.
+	 * @returns {Object|null} - The output entry or null if not found.
+	 */
 	get(id) {
 		return matchedValue(this.outputs, id) || null;
 	}
 
-	// ========================================================================== //
-	//  Helpers                                                                   //
-	// ========================================================================== //
+	// -- Utility Helpers ------------------------------------------------------ //
+
+	/**
+	 * Placeholder for comment rendering. Should be overridden by specific mappers.
+	 * @param {string} text - The raw comment text.
+	 * @returns {string} - The formatted comment string.
+	 */
 	comment(text) {
 		return "";
 	}
+
+	/**
+	 * Formats a plain text node.
+	 * @param {string} text - The raw text content.
+	 * @param {Object} [options] - Target options like { escape: false }.
+	 * @returns {string} - The formatted text string.
+	 */
+	text(text, options) {
+		return text;
+	}
+
+	/**
+	 * Formats the content of an inline statement.
+	 * @param {string} text - The raw inline content.
+	 * @param {Object} options - The target output options.
+	 * @returns {string} - The formatted inline string.
+	 */
+	inlineText(text, options) {
+		return text;
+	}
+
+	/**
+	 * Formats the raw body of an At-Block.
+	 * @param {string} text - The raw atblock body.
+	 * @param {Object} options - The target output options.
+	 * @returns {string} - The formatted atblock string.
+	 */
+	atBlockBody(text, options) {
+		return text;
+	}
+
+
+	/**
+	 * Handles unknown tags. Should be overridden by specific mappers to provide fallback behavior.
+	 * @param {Object} node - The AST node for the unknown id.
+	 * @returns {Object|null} - A tag-like entry for fallback rendering.
+	 */
 	getUnknownTag(node) {
 		return null;
 	}
+
+	/**
+	 * Creates a new TagBuilder instance for programmatic HTML-like tag creation.
+	 * @param {string} tagName - The name of the tag (e.g., 'div', 'p').
+	 * @returns {TagBuilder}
+	 */
 	tag(tagName) {
 		return new TagBuilder(tagName);
 	}
 
-	getCustomHeaderContent() {
-		return this.#customHeaderContent;
-	}
-
-	setHeader(rawData) {
-		if (Array.isArray(rawData)) {
-			for (const data of rawData) {
-				if (typeof data === "string") {
-					this.#customHeaderContent += data + "\n";
-				}
-			}
-		}
-	}
+	/**
+	 * Checks if this mapper has any of the specified IDs registered.
+	 * @param {Array<string>} ids - List of IDs to check for.
+	 * @returns {boolean} - True if at least one ID exists.
+	 */
 	includesId(ids) {
 		try {
 			if (!Array.isArray(ids) || ids.length === 0) {
@@ -209,35 +208,65 @@ class Mapper {
 		}
 	}
 
-	safeArg(args, index, key, type = null, setType = null, fallBack = null) {
-		return safeArg(args, index, key, type, setType, fallBack);
+	/**
+	 * Safely retrieves an argument value, handling both named and positional access.
+	 * 
+	 * @param {Object} options - Resolution options.
+	 * @returns {any} - The resolved argument value.
+	 */
+	safeArg(options) {
+		return safeArg(options);
 	}
 
+	/**
+	 * Creates a deep clone of the mapper instance, isolating output registrations.
+	 * Inherits all properties and binds methods to the new instance.
+	 * 
+	 * @returns {Mapper} - The cloned mapper instance.
+	 */
 	clone() {
-		const newMapper = new this.constructor();
+		const newMapper = new Mapper();
+		for (const [key, val] of Object.entries(this)) {
+			if (key === "outputs" || key === "customProps" || key === "md") continue;
 
-		// Map-clone outputs to ensure options are isolated but render remains bound
+			if (typeof val === "object" && val !== null && !Array.isArray(val)) {
+				newMapper[key] = { ...val };
+			} else {
+				newMapper[key] = val;
+			}
+		}
+
+		newMapper.options = { ...this.options };
+
+		// Deep-clone specific structural properties
 		newMapper.outputs = this.outputs.map(out => ({
 			...out,
 			options: out.options ? { ...out.options } : { escape: true }
 		}));
 
-		newMapper.styles = [...this.styles];
-
-		// deep clone pageProps
-		newMapper.pageProps = JSON.parse(JSON.stringify(this.pageProps));
-
-		newMapper.extraProps = new Set(this.extraProps);
-		newMapper.setHeader([this.getCustomHeaderContent()]);
+		newMapper.customProps = new Set(this.customProps);
+		
 		return newMapper;
 	}
 
+	/**
+	 * Clears all registered outputs from the mapper.
+	 */
 	clear() {
 		this.outputs = [];
 	}
 
-	formatOutput(output, includeDocument) {
-		return output;
+	/**
+	 * Static factory method to create a new Mapper instance with pre-defined properties.
+	 * @param {Object} [options={}] - Properties and methods to add to the mapper.
+	 * @returns {Mapper}
+	 */
+	static define(options = {}) {
+		const mapper = new Mapper();
+		for (const [key, val] of Object.entries(options)) {
+			mapper[key] = val;
+		}
+		return mapper;
 	}
 }
 export default Mapper;