sommark 3.3.4 → 4.0.1

package/formatter/mark.js

@@ -1,8 +1,16 @@
+/**
+ * MarkdownBuilder - A utility class for generating Markdown strings from structured data.
+ * Used primarily by the Markdown mapper to produce formatted text.
+ */
 class MarkdownBuilder {
 	constructor() { }
-	// ========================================================================== //
-	//  Headings                                                                  //
-	// ========================================================================== //
+
+	/**
+	 * Formats text as a Markdown heading.
+	 * @param {string} text - The heading content.
+	 * @param {number|string} [level=1] - The heading level (1-6).
+	 * @returns {string} - Formatted heading string.
+	 */
 	heading(text, level) {
 		if (!text && !level) {
 			return "";
@@ -18,22 +26,32 @@ class MarkdownBuilder {
 			} else if (level < min) {
 				level = min;
 			}
-			return `\n${"#".repeat(level)} ${text}\n`;
+			return `${"#".repeat(level)} ${text}`;
 		}
 		return text;
 	}
-	// ========================================================================== //
-	//  Url                                                                       //
-	// ========================================================================== //
+
+	/**
+	 * Formats a Markdown link or image.
+	 * @param {string} [type=""] - The link type ("image" for '!', otherwise empty).
+	 * @param {string} text - The display text or alt text.
+	 * @param {string} [url=""] - The target URL.
+	 * @param {string} [title=""] - Optional hover title.
+	 * @returns {string} - Formatted Markdown link/image string.
+	 */
 	url(type = "", text, url = "", title = "") {
 		if (!text && !url) {
 			return "";
 		}
-		return ` ${type === "image" ? "!" : ""}[${text}](${url + (title ? " " : "")}${title ? JSON.stringify(title) : ""}) `;
+		return `${type === "image" ? "!" : ""}[${text}](${url + (title ? " " : "")}${title ? JSON.stringify(title) : ""})`;
 	}
-	// ========================================================================== //
-	//  Bold                                                                      //
-	// ========================================================================== //
+
+	/**
+	 * Formats text as bold.
+	 * @param {string} text - The content to bold.
+	 * @param {boolean} [is_underscore=false] - Use underscores ('__') instead of asterisks ('**').
+	 * @returns {string} - Formatted bold string.
+	 */
 	bold(text, is_underscore = false) {
 		if (!text) {
 			return "";
@@ -41,9 +59,13 @@ class MarkdownBuilder {
 		const format = is_underscore ? "__" : "**";
 		return `${format}${text}${format}`;
 	}
-	// ========================================================================== //
-	//  Italic                                                                    //
-	// ========================================================================== //
+
+	/**
+	 * Formats text as italic (emphasis).
+	 * @param {string} text - The content to italicize.
+	 * @param {boolean} [is_underscore=false] - Use underscores ('_') instead of asterisks ('*').
+	 * @returns {string} - Formatted italic string.
+	 */
 	italic(text, is_underscore = false) {
 		if (!text) {
 			return "";
@@ -51,9 +73,13 @@ class MarkdownBuilder {
 		const format = is_underscore ? "_" : "*";
 		return `${format}${text}${format}`;
 	}
-	// ========================================================================== //
-	//  Emphasis                                                                  //
-	// ========================================================================== //
+
+	/**
+	 * Formats text as bold-italic (strong emphasis).
+	 * @param {string} text - The content to emphasize.
+	 * @param {boolean} [is_underscore=false] - Use underscores ('___') instead of asterisks ('***').
+	 * @returns {string} - Formatted emphasized string.
+	 */
 	emphasis(text, is_underscore = false) {
 		if (!text) {
 			return "";
@@ -61,9 +87,25 @@ class MarkdownBuilder {
 		const format = is_underscore ? "___" : "***";
 		return `${format}${text}${format}`;
 	}
-	// ========================================================================== //
-	//  Code Block                                                                //
-	// ========================================================================== //
+
+	/**
+	 * Formats text with strikethrough.
+	 * @param {string} text - The content to strike.
+	 * @returns {string} - Formatted strikethrough string.
+	 */
+	strike(text) {
+		if (!text) {
+			return "";
+		}
+		return `~~${text}~~`;
+	}
+
+	/**
+	 * Formats source code as a Markdown fenced code block.
+	 * @param {string|Array} code - The code content.
+	 * @param {string} [language=""] - The language identifier for syntax highlighting.
+	 * @returns {string} - Formatted code block string.
+	 */
 	codeBlock(code, language = "") {
 		if (!code) return "";
 
@@ -78,31 +120,85 @@ class MarkdownBuilder {
 		if (!content) return "";
 
 		const lang = language ? language : "";
-		return `\n\`\`\`${lang}\n${content}\`\`\`\n`;
+		return `\n\`\`\`${lang}\n${content.trim()}\n\`\`\``;
 	}
 
-	// ========================================================================== //
-	//  Horizontal rule                                                           //
-	// ========================================================================== //
+	/**
+	 * Formats a Markdown horizontal rule.
+	 * @param {string} [format="*"] - The character to use for the rule.
+	 * @returns {string} - Formatted horizontal rule string.
+	 */
 	horizontal(format = "*") {
-		return `\n${format.repeat(3)}\n`;
+		return `\n${format.repeat(3)}`;
 	}
-	// ========================================================================== //
-	//  Escape                                                                    //
-	// ========================================================================== //
+
+	/**
+	 * Escapes special Markdown characters to prevent unintended formatting.
+	 * @param {string} text - The text to escape.
+	 * @returns {string} - Escaped text string.
+	 */
 	escape(text) {
 		if (!text) return "";
 
-		const special = /[\\*_{}\[\]()#+\-.!>|]/g;
+		const special = /[\\*_{}\[\]()#+\-.!>|~`]/g;
 
 		return text.replace(special, "\\$&");
 	}
 
-	// ========================================================================== //
-	//  Table                                                                     //
-	// ========================================================================== //
+	/**
+	 * Smartly escapes text to prevent unintended Markdown/HTML formatting
+	 * while keeping "innocent" symbols clean (e.g., math, solo symbols).
+	 * 
+	 * @param {string} text - The raw text to escape.
+	 * @returns {string} - The safely escaped text.
+	 */
+	smartEscaper(text) {
+		if (!text) return "";
+
+		// 1. Literal backslashes must stay literal
+		let result = text.replace(/\\/g, "\\\\");
+
+		// 2. HTML Tags: Detect <tag ... > or </tag>
+		// We do this BEFORE escaping & to prevent &amp;lt;
+		result = result.replace(/<([a-zA-Z\/][^>]*?)>/g, "&lt;$1&gt;");
+
+		// 3. Basics: Escape ampersands and quotes
+		// We use a lookahead to avoid double-escaping the '&' in '&lt;' and '&gt;' we just created
+		result = result.replace(/&(?!lt;|gt;)/g, "&amp;")
+			.replace(/"/g, "&quot;")
+			.replace(/'/g, "&#39;");
+
+		// 4. Markdown Heading Triggers: # at the start of a line
+		result = result.replace(/^#{1,6}\s+/gm, "\\$&");
+
+		// 5. Markdown List Triggers: -, *, +, or 1. at the start of a line
+		result = result.replace(/^([-*+]\s+)/gm, "\\$1");
+		result = result.replace(/^(\d+\.\s+)/gm, "\\$1");
+
+		// 6. Emphasis Triggers: *text*, **text**, _text_, ~~text~~
+		// We look for balanced wrappers around non-whitespace content.
+		result = result.replace(/(\*+|_+|~~)(\S[\s\S]*?\S)\1/g, (match, prefix, content) => {
+			const escapedPrefix = prefix.split("").map(c => "\\" + c).join("");
+			return escapedPrefix + content + escapedPrefix;
+		});
+
+		// 7. Horizontal Rule Triggers: ---, ***, ___ on their own line
+		result = result.replace(/^([*_-]{3,})\s*$/gm, "\\$1");
+
+		return result;
+	}
+
+
+
+
+	/**
+	 * Formats data as a Markdown table.
+	 * @param {Array<string>} headers - The table column headers.
+	 * @param {Array<string|Array>} rows - The table row data.
+	 * @returns {string} - Formatted Markdown table string.
+	 */
 	table(headers, rows) {
-		let result = "\n\n";
+		let result = "";
 		const isNotEmptyArray = arr => Array.isArray(arr) && arr.length > 0;
 		if (isNotEmptyArray(headers) && isNotEmptyArray(rows)) {
 			for (let i = 0; i < headers.length; i++) {
@@ -113,8 +209,8 @@ class MarkdownBuilder {
 				const header = headers[i];
 				result +=
 					i === 0
-						? `|${"-".repeat(header.length + 2)}|`
-						: `${"-".repeat(header.length + 2)}|${i === headers.length - 1 ? "\n" : ""}`;
+						? `| --- |`
+						: ` --- |${i === headers.length - 1 ? "\n" : ""}`;
 			}
 			rows = rows.map(row => {
 				let columns;
@@ -132,18 +228,82 @@ class MarkdownBuilder {
 
 				return `| ${columns.join(" | ")}`;
 			});
-			for (const row of rows) {
-				result += `${row} |\n`;
+			for (let i = 0; i < rows.length; i++) {
+				const row = rows[i];
+				result += `${row} |${i === rows.length - 1 ? "" : "\n"}`;
 			}
 		}
-		return result + "\n";
+		return result;
 	}
-	// ========================================================================== //
-	//  Todo                                                                      //
-	// ========================================================================== //
-	todo(checked = false, text) {
+
+	/**
+	 * Formats a task list item.
+	 * @param {boolean|string} [status=false] - The task status (true, "x", or "done" for checked).
+	 * @param {string} text - The task description.
+	 * @returns {string} - Formatted task list item string.
+	 */
+	todo(status = false, text) {
 		if (!text) return "";
-		return checked ? `- [x] ${text}\n` : `- [ ] ${text}\n`;
+		let checked = status;
+		if (typeof status === "string") {
+			const s = status.trim().toLowerCase();
+			checked = s === "x" || s === "done";
+		}
+		return checked ? `- [x] ${text}` : `- [ ] ${text}`;
+	}
+
+	/**
+	 * Formats an unordered Markdown list.
+	 * @param {Array<string>} items - The list items.
+	 * @param {number} [depth=0] - The nesting depth for indentation.
+	 * @param {string} [marker="-"] - The bullet point character.
+	 * @returns {string} - Formatted unordered list string.
+	 */
+	unorderedList(items, depth = 0, marker = "-") {
+		if (!Array.isArray(items)) return "";
+		const indent = "  ".repeat(depth);
+		return items.map(item => `${indent}${marker} ${item.replace(/\n/g, "\n" + indent + "  ")}`).join("\n");
+	}
+
+	/**
+	 * Formats an ordered Markdown list.
+	 * @param {Array<string>} items - The list items.
+	 * @param {number} [depth=0] - The nesting depth for indentation.
+	 * @returns {string} - Formatted ordered list string.
+	 */
+	orderedList(items, depth = 0) {
+		if (!Array.isArray(items)) return "";
+		const indent = "  ".repeat(depth);
+		return items.map((item, i) => `${indent}${i + 1}. ${item.replace(/\n/g, "\n" + indent + "  ")}`).join("\n");
+	}
+
+	/**
+	 * Formats text as a Markdown blockquote or GFM alert (admonition).
+	 * @param {string} content - The content to quote.
+	 * @param {string} [type=""] - The alert type ("note", "tip", "important", "caution", "warning").
+	 * @returns {string} - Formatted blockquote string.
+	 */
+	/**
+	 * Formats text as a Markdown blockquote or GFM alert (admonition).
+	 * @param {string} content - The content to quote.
+	 * @param {string} [type=""] - The alert type ("note", "tip", "important", "caution", "warning").
+	 * @returns {string} - Formatted blockquote string.
+	 */
+	quote(content, type = "") {
+		if (!content) return "";
+
+		const alertTypes = ["note", "tip", "important", "caution", "warning"];
+		const alertType = type ? type.toLowerCase().trim() : "";
+		const isAlert = alertTypes.includes(alertType);
+
+		const cleanContent = content.trim();
+
+		const prefix = isAlert ? `[!${alertType.toUpperCase()}]\n` : "";
+
+		const fullText = prefix + cleanContent;
+		const lines = fullText.split(/\r?\n/);
+
+		return lines.map(line => `> ${line}`).join("\n");
 	}
 }
 export default MarkdownBuilder;

package/formatter/tag.js

@@ -1,28 +1,45 @@
 import escapeHTML from "../helpers/escapeHTML.js";
+import kebabize from "../helpers/kebabize.js";
+import { HTML_PROPS } from "../constants/html_props.js";
+import { VOID_ELEMENTS } from "../constants/void_elements.js";
+
+/**
+ * TagBuilder - A builder pattern utility for programmatic HTML/XML tag generation.
+ * Handles attributes, body content, and self-closing tags with high-fidelity escaping.
+ */
 class TagBuilder {
 	#children;
 	#attr;
 	#is_self_close;
-	// ========================================================================== //
-	//  Constructor                                                               //
-	// ========================================================================== //
+
+	/**
+	 * Creates a new TagBuilder instance.
+	 * @param {string} tagName - The name of the tag (e.g., 'div', 'span').
+	 */
 	constructor(tagName) {
 		this.tagName = tagName;
 		this.#children = "";
 		this.#attr = [];
 		this.#is_self_close = false;
 	}
-	// ========================================================================== //
-	//  Attributes                                                                //
-	// ========================================================================== //
-	attributes(obj, ...arr) {
+
+	/**
+	 * Adds attributes to the tag.
+	 * @param {Object} obj - Key-value pair of attributes.
+	 * @param {boolean} [strict=false] - If true, boolean true values render as key="true".
+	 * @param {...string} arr - Optional list of boolean attributes (e.g., 'disabled', 'required').
+	 * @returns {TagBuilder} - Returns this instance for chaining.
+	 */
+	attributes(obj, strict = false, ...arr) {
 		if (obj && obj instanceof Object) {
 			Object.entries(obj).forEach(([key, value]) => {
+				if (!isNaN(parseInt(key))) return; // Skip numeric positional arguments
 				if (value === true) {
-					this.#attr.push(`${key}`);
+					this.#attr.push(strict ? `${key}="true"` : `${key}`);
 				} else if (value !== false) {
 					let val = value ?? "";
 					if (key === "style" && typeof val === "string") {
+						// V4 DYNAMIC CSS: Automatically wrap CSS variables in var()
 						val = val.replace(/(^|[^\w\-_$])(--[\w\-_$]+)(?![\w\-_$]|:)/g, "$1var($2)");
 					}
 					this.#attr.push(`${key}="${escapeHTML(val)}"`);
@@ -36,30 +53,174 @@ class TagBuilder {
 		}
 		return this;
 	}
-	// ========================================================================== //
-	//  Props                                                                     //
-	// ========================================================================== //
+
+	/**
+	 * Adds attributes with project-certified smart handling (kebabization, styling fallback).
+	 * Implements the V4 "Smart Styling Fallback" strategy.
+	 * 
+	 * @param {Object} args - Key-value pair of Smark arguments/attributes.
+	 * @param {Set<string>} [customProps=new Set()] - Set of project-certified custom properties.
+	 * @param {Object} [options={}] - Configuration flags (e.g., skipSmartHandling).
+	 * @returns {TagBuilder} - Returns this instance for chaining.
+	 */
+	smartAttributes(args, customProps = new Set(), options = {}) {
+		if (!args || typeof args !== "object") return this;
+
+		const id = this.tagName.toLowerCase();
+		const isCodeStyleOrScript = ["style", "script"].includes(id);
+		let inline_style = "";
+
+		// 1. Initial CSS Variable/Style processing
+		if (!isCodeStyleOrScript && args.style) {
+			if (typeof args.style === "object") {
+				inline_style = Object.entries(args.style)
+					.map(([k, v]) => `${kebabize(k)}:${v}`)
+					.join(";") + (Object.keys(args.style).length > 0 ? ";" : "");
+			} else if (typeof args.style === "string") {
+				inline_style = args.style.endsWith(";") ? args.style : args.style + ";";
+			} else {
+				inline_style = String(args.style) + ";";
+			}
+		}
+
+		// 2. Attribute Dispatching
+		const keys = Object.keys(args).filter(arg => isNaN(parseInt(arg)));
+		keys.forEach(key => {
+			if (!isNaN(parseInt(key))) return; // Skip numeric positional arguments
+			if (key === "style") return;
+			if (isCodeStyleOrScript && key === "scoped") return;
+
+			const isDimensionAttributeSupported = ["img", "video", "svg", "canvas", "iframe", "object", "embed"].includes(id);
+			const isWidthOrHeight = key === "width" || key === "height";
+			const isEvent = key.toLowerCase().startsWith("on");
+			const isNative = HTML_PROPS.has(key);
+			const isCustom = customProps.has(key) || customProps.has(kebabize(key));
+			const isDataOrAria = kebabize(key).startsWith("data-") || kebabize(key).startsWith("aria-");
+
+			const k = isEvent ? key.toLowerCase() : (isNative || isCustom) ? key : kebabize(key);
+
+			if (isCodeStyleOrScript) {
+				// Specialized tags: only render standard attributes, no styling fallback
+				this.#attr.push(`${k}="${escapeHTML(String(args[key]))}"`);
+			} else {
+				// Standard elements: process smart styling fallbacks for non-native props
+				if (isEvent || ((isNative || isCustom) && (!isWidthOrHeight || isDimensionAttributeSupported)) || isDataOrAria) {
+					const val = typeof args[key] === "object" ? JSON.stringify(args[key]) : args[key];
+					this.#attr.push(`${k}="${escapeHTML(String(val))}"`);
+				} else {
+					const val = typeof args[key] === "object" ? JSON.stringify(args[key]) : args[key];
+					inline_style += `${k}:${val};`;
+				}
+			}
+		});
+
+		if (inline_style) {
+			// V4 DYNAMIC CSS: Automatically wrap CSS variables in var()
+			const processedStyle = inline_style.replace(/(^|[^\w\-_$])(--[\w\-_$]+)(?![\w\-_$]|:)/g, "$1var($2)");
+			this.#attr.push(`style="${escapeHTML(processedStyle)}"`);
+		}
+
+		return this;
+	}
+
+	/**
+	 * Converts SomMark arguments into JSX props and applies them to the tag.
+	 * Implements smart handling for className, style objects, and automated JSX expression wrapping.
+	 * 
+	 * @param {Object} args - The list of arguments.
+	 * @returns {TagBuilder} - Returns this instance for chaining.
+	 */
+	jsxProps(args) {
+		if (!args || typeof args !== "object") return this;
+
+		const jsxProps = [];
+		const styleObj = {};
+
+		const keys = Object.keys(args).filter(arg => isNaN(parseInt(arg)));
+		keys.forEach(key => {
+			let val = args[key];
+
+			let k = key;
+			if (k === "class") k = "className";
+
+			// Strip quotes from string literals if they were passed raw
+			if (typeof val === "string" && ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'")))) {
+				val = val.slice(1, -1);
+			}
+
+			if (k === "style") {
+				// Convert CSS strings to React-style objects
+				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 {
+				// Detect if it should be wrapped in {} (JSX Expression)
+				const isObject = typeof val === "object" && val !== null;
+				const isBoolean = typeof val === "boolean" || val === "true" || val === "false";
+				const isNumeric = typeof val === "number" || (typeof val === "string" && val !== "" && !isNaN(val));
+				const isWrappedInBraces = typeof val === "string" && val.startsWith("{") && val.endsWith("}");
+
+				const shouldBeJSXExpression = isObject || isBoolean || isNumeric || isWrappedInBraces;
+
+				let finalVal = val;
+				if (val === "true") finalVal = true;
+				if (val === "false") finalVal = false;
+				if (typeof val === "string" && isNumeric) finalVal = Number(val);
+
+				if (isWrappedInBraces) {
+					// Strip outer braces: {theme} -> theme
+					finalVal = val.slice(1, -1);
+				} else if (isObject) {
+					// Clean JS string for JSX: { a: 1 } instead of {"a":1}
+					finalVal = JSON.stringify(val).replace(/"([^"]+)":/g, "$1:");
+				}
+
+				jsxProps.push({
+					__type__: shouldBeJSXExpression ? "other" : "string",
+					[k]: finalVal
+				});
+			}
+		});
+
+		if (Object.keys(styleObj).length > 0) {
+			const styleStr = JSON.stringify(styleObj).replace(/"([^"]+)":/g, "$1:");
+			jsxProps.push({ __type__: "other", style: styleStr });
+		}
+
+		// Use the legacy props helper to apply the generated list
+		this.props(jsxProps);
+		return this;
+	}
+
+	/**
+	 * Internal helper to apply MDX-style property entries.
+	 * Note: This method no longer returns 'this' and is removed from the chain.
+	 * Use .jsxProps(args) instead.
+	 * 
+	 * @param {Object|Array} propsList - The property entries to add.
+	 */
 	props(propsList) {
 		const list = Array.isArray(propsList) ? propsList : [propsList];
 		if (list.length > 0) {
 			for (const propEntry of list) {
-				if (typeof propEntry !== "object" || propEntry === null) {
-					throw new TypeError("prop expects an object with property { __type__ }");
-				}
-
-				if (!Object.prototype.hasOwnProperty.call(propEntry, "__type__")) {
-					throw new TypeError("prop expects an object with property { __type__ }");
+				if (typeof propEntry !== "object" || propEntry === null || !Object.prototype.hasOwnProperty.call(propEntry, "__type__")) {
+					continue;
 				}
 
 				const { __type__, ...rest } = propEntry;
 				const entries = Object.entries(rest);
-
-				if (entries.length === 0) {
-					continue;
-				}
+				if (entries.length === 0) continue;
 
 				const [key, value] = entries[0];
-
 				switch (__type__) {
 					case "string":
 						this.#attr.push(`${key}="${escapeHTML(String(value))}"`);
@@ -70,11 +231,14 @@ class TagBuilder {
 				}
 			}
 		}
-		return this;
 	}
-	// ========================================================================== //
-	//  Body                                                                      //
-	// ========================================================================== //
+
+	/**
+	 * Sets the body content of the tag. 
+	 * Note: Calling this method finalizes the builder state by returning the generated string.
+	 * @param {string|Array} nodes - The inner content of the tag.
+	 * @returns {string} - The generated HTML string.
+	 */
 	body(nodes) {
 		if (nodes) {
 			let space = this.#children ? " " : "";
@@ -82,16 +246,22 @@ class TagBuilder {
 		}
 		return this.builder();
 	}
-	// ========================================================================== //
-	//  Self Close                                                                //
-	// ========================================================================== //
+
+	/**
+	 * Marks the tag as self-closing (e.g., <img />).
+	 * Note: Calling this method finalizes the builder state by returning the generated string.
+	 * @returns {string} - The generated HTML string.
+	 */
 	selfClose() {
 		this.#is_self_close = true;
 		return this.builder();
 	}
-	// ========================================================================== //
-	//  Builder                                                                   //
-	// ========================================================================== //
+
+	/**
+	 * Internal method to construct the final tag string.
+	 * @private
+	 * @returns {string} - The generated HTML string.
+	 */
 	builder() {
 		const props = this.#attr.length > 0 ? " " + this.#attr.join(" ") : "";
 		if (this.#is_self_close) {