sommark 4.0.3 → 4.2.0

package/core/validator.js

@@ -18,11 +18,40 @@ import { transpilerError } from "./errors.js";
 const runValidations = (node, target, instance) => {
 	if (!target || !target.options) return;
 	const rules = target.options.rules || {};
-	const id = (target.id) ? (Array.isArray(target.id) ? target.id.join(" | ") : target.id) : "Unknown";
-	const context = instance ? { src: instance.src, range: node.range, filename: instance.filename } : null;
+	const id = (target.id) ? (Array.isArray(target.id) ? target.id.join(" | ") : target.id) : (node.id || "Unknown");
+	const errorRange = node.range ? {
+		start: node.range.start,
+		end: {
+			line: node.range.start.line,
+			character: node.range.start.character + (node.id || "").length + 2
+		}
+	} : null;
+	const context = instance ? { src: instance.src, range: errorRange, filename: instance.filename } : null;
+
+	// -- Structural Integrity (Empty Body / Self-Closing) ----------------- //
+	const isEmptyBodyTarget = rules.is_empty_body || rules.is_self_closing;
+
+	// -- Node Type Validation --------------------------------------------- //
+	if (target.options.type) {
+		const allowedTypes = Array.isArray(target.options.type) ? target.options.type : [target.options.type];
+		const hasAny = allowedTypes.includes("any");
+		if (!hasAny && !allowedTypes.includes(node.structure)) {
+			const isReserved = ["import", "$use-module", "slot", "for-each"].includes(id.toLowerCase());
+			const msg = isReserved
+				? `<$yellow:Reserved keyword$> <$blue:'${id}'$> <$yellow:is strictly defined as a [${allowedTypes.join(", ")}] structure node, but was used as a [${node.structure}] structure node.$>`
+				: `<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:is defined as type(s) [${allowedTypes.join(", ")}], but was used as a [${node.structure}] structure node.$>`;
+
+			transpilerError(
+				[
+					"{N}",
+					msg
+				],
+				context
+			);
+		}
+	}
 
-	// -- Structural Integrity (Self-Closing) ------------------------------ //
-	if (rules.is_self_closing && node.type === "Block" && node.body) {
+	if (isEmptyBodyTarget && node.type === "Block" && !node.isSelfClosing && node.body) {
 		const hasContent = node.body.some(child => {
 			if (child.type === "Text") {
 				return (child.text || "").trim().length > 0;
@@ -33,8 +62,32 @@ const runValidations = (node, target, instance) => {
 		if (hasContent) {
 			transpilerError(
 				[
-					"<$red:Validation Error:$> ",
-					`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:is self-closing and cannot have children (body).$>`
+					"{N}",
+					"<$red:[Validation Error]:$>{N}",
+					`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:is defined as an empty-body component and cannot have children.$>`
+				],
+				context
+			);
+		}
+	}
+
+	// -- Arguments Validation (Required Args) ----------------------------- //
+	const isStructural = node.type === "Block" || node.type === "AtBlock";
+	if (isStructural && rules.required_args && Array.isArray(rules.required_args)) {
+		const missingArgs = rules.required_args.filter(arg => {
+			// Check if the argument exists in named args or as a positional arg (if arg is a number)
+			if (typeof arg === "number") {
+				return node.args[arg] === undefined;
+			}
+			return node.args[arg] === undefined;
+		});
+
+		if (missingArgs.length > 0) {
+			transpilerError(
+				[
+					"{N}",
+					`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:is missing required arguments:$> <$red:${missingArgs.join(", ")}$>{N}`,
+					`<$blue:Please ensure these arguments are provided in the template usage.$>`
 				],
 				context
 			);
@@ -69,7 +122,17 @@ export function validateAST(ast, mapperFile, instance) {
 
 		// 1. Identify Target
 		if (node.id) {
-			const target = mapperFile.get(node.id) || (mapperFile.getUnknownTag ? mapperFile.getUnknownTag(node) : null);
+			let target = null;
+			const lowerId = node.id.toLowerCase();
+			if (["import", "$use-module", "slot", "for-each"].includes(lowerId)) {
+				target = {
+					id: lowerId,
+					options: { type: "Block" }
+				};
+			} else {
+				target = mapperFile.get(node.id) || (mapperFile.getUnknownTag ? mapperFile.getUnknownTag(node) : null);
+			}
+
 			if (target) {
 				runValidations(node, target, instance);
 			}

package/formatter/tag.js

@@ -69,6 +69,8 @@ class TagBuilder {
 		const id = this.tagName.toLowerCase();
 		const isCodeStyleOrScript = ["style", "script"].includes(id);
 		let inline_style = "";
+		const useClassFallback = options.fallbackTarget === "class";
+		const classSet = new Set();
 
 		// 1. Initial CSS Variable/Style processing
 		if (!isCodeStyleOrScript && args.style) {
@@ -83,12 +85,20 @@ class TagBuilder {
 			}
 		}
 
-		// 2. Attribute Dispatching
+		// 2. Pre-collect native classes if using class fallback
+		if (useClassFallback) {
+			if (args.class) {
+				String(args.class).split(/\s+/).filter(Boolean).forEach(c => classSet.add(c));
+			}
+		}
+
+		// 3. 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;
+			if (useClassFallback && key === "class") return;
 
 			const isDimensionAttributeSupported = ["img", "video", "svg", "canvas", "iframe", "object", "embed"].includes(id);
 			const isWidthOrHeight = key === "width" || key === "height";
@@ -99,21 +109,35 @@ class TagBuilder {
 
 			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]))}"`);
+			if (isCodeStyleOrScript || options.fallbackTarget === false) {
+				// Specialized tags or fallback disabled: render standard attributes, no styling fallback
+				const val = typeof args[key] === "object" ? JSON.stringify(args[key]) : args[key];
+				this.#attr.push(`${k}="${escapeHTML(String(val))}"`);
 			} else {
-				// Standard elements: process smart styling fallbacks for non-native props
+				// Standard elements: process smart fallbacks
 				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 (useClassFallback) {
+						const val = args[key];
+						if (val === true || val === "true") {
+							classSet.add(k);
+						} else if (val !== false && val !== "false" && val !== null && val !== undefined) {
+							classSet.add(`${k}-${val}`);
+						}
+					} else {
+						const val = typeof args[key] === "object" ? JSON.stringify(args[key]) : args[key];
+						inline_style += `${k}:${val};`;
+					}
 				}
 			}
 		});
 
+		if (useClassFallback && classSet.size > 0) {
+			this.#attr.push(`class="${escapeHTML([...classSet].join(" "))}"`);
+		}
+
 		if (inline_style) {
 			// V4 DYNAMIC CSS: Automatically wrap CSS variables in var()
 			const processedStyle = inline_style.replace(/(^|[^\w\-_$])(--[\w\-_$]+)(?![\w\-_$]|:)/g, "$1var($2)");

package/grammar.ebnf

@@ -18,18 +18,28 @@ EscapeChar     = "\", ? any character except WhiteSpace ?;
 
 (* "Junk" refers to whitespace and comments which the parser skips in headers *)
 Comment        = "#", { ? any character except "\n" ? }, "\n";
-Junk           = { WhiteSpace | Comment };
+CommentBlock   = "###", { ? any character ? }, "###";
+Junk           = { WhiteSpace | Comment | CommentBlock };
 
 (* Prefix Layers for Dynamic Data *)
 PrefixJS       = "js{", { ? any character ? }, "}";
 PrefixP        = "p{", { ? any character ? }, "}";
-PrefixLayer    = PrefixJS | PrefixP;
+PrefixV        = "v{", { ? any character ? }, "}";
+PrefixLayer    = PrefixJS | PrefixP | PrefixV;
+
+(* Static / Runtime Logic Blocks *)
+LogicBlock     = ( "static" | "runtime" ), [ " " ], "${", { ? any character ? }, "}$";
 
 (* ========================================== *)
 (* Block Syntax (Containers)                  *)
 (* ========================================== *)
 
-Block          = BlockOpen, BlockBody, BlockEnd;
+Block          = StandardBlock | SelfClosingBlock;
+
+StandardBlock  = BlockOpen, BlockBody, BlockEnd;
+
+(* Self-Closing Blocks end with an exclamation mark (!) *)
+SelfClosingBlock = "[", Junk, BlockID, Junk, [ "=", Junk, BlockArgs, Junk ], "!", Junk, "]";
 
 (* Flexible Header with Junk-Skipping. Blocks allow colons in ID. *)
 BlockOpen      = "[", Junk, BlockID, Junk, [ "=", Junk, BlockArgs, Junk ], "]";
@@ -41,7 +51,7 @@ BlockArgs      = BlockArg, { Junk, ",", Junk, BlockArg };
 BlockArg       = [ BlockKey, Junk, ":", Junk ], Value;
 
 BlockKey       = BlockID | QuotedString;
-Value          = QuotedString | PrefixLayer | RawValue;
+Value          = QuotedString | PrefixLayer | LogicBlock | RawValue;
 
 QuotedString   = ("'" | '"'), { ? any character ? | EscapeChar }, ("'" | '"');
 RawValue       = { ? any char except ",", Junk, "]" ? | EscapeChar };
@@ -50,15 +60,16 @@ RawValue       = { ? any char except ",", Junk, "]" ? | EscapeChar };
 (* Inline Statement Syntax                    *)
 (* ========================================== *)
 
-(* Inlines use SimpleID (NO COLONS allowed in ID) *)
-InlineStatement = "(", InlineContent, ")", Junk, "->", Junk, "(", SimpleID, [ Junk, ":", Junk, InlineArgs ], ")";
+(* Inlines use SimpleID (NO COLONS allowed in ID unless key-value) *)
+InlineStatement = "(", InlineContent, ")", Junk, "->", Junk, "(", SimpleID, [ Junk, ( "=" | ":" ), Junk, InlineArgs ], ")";
 
 (* Content allows balanced parentheses and placeholders *)
-InlineContent   = { ? any char except ")" ? | BalancedParen | EscapeChar | PrefixP };
+InlineContent   = { ? any char except ")" ? | BalancedParen | EscapeChar | PrefixP | PrefixV };
 BalancedParen   = "(", InlineContent, ")";
 
-(* Inline Arguments: Positional Only *)
-InlineArgs      = Value, { Junk, ",", Junk, Value };
+(* Inline Arguments: Positional and Named support *)
+InlineArgs      = InlineArg, { Junk, ",", Junk, InlineArg };
+InlineArg       = [ SimpleID, Junk, ":", Junk ], Value;
 
 (* ========================================== *)
 (* At-Block Syntax (Raw Containers)           *)
@@ -83,4 +94,4 @@ AtBody         = { ? any character ? | EscapeChar };
 Document       = { Block | InlineStatement | AtBlock | TextContent | Comment | WhiteSpace };
 
 (* Text Content: Plain text with fallback behavior for symbols *)
-TextContent    = { ? any char except "[", "@_", "(", "#" ? | EscapeChar | PrefixP };
+TextContent    = { ? any char except "[", "@_", "(", "#" ? | EscapeChar | PrefixP | PrefixV | LogicBlock };

package/helpers/fetch-fs.js

@@ -0,0 +1,37 @@
+export class FetchFS {
+    constructor(baseURL) {
+        this.baseURL = baseURL.endsWith("/") ? baseURL : baseURL + "/";
+        this._cache = new Map();
+    }
+
+    _resolve(p) {
+        if (p.startsWith("http://") || p.startsWith("https://")) return p;
+        return this.baseURL + p.replace(/^\//, "");
+    }
+
+    async readFile(p, encoding) {
+        const url = this._resolve(p);
+        if (this._cache.has(url)) return this._cache.get(url);
+        const res = await fetch(url);
+        if (!res.ok) throw new Error(`File not found: ${p} (${res.status})`);
+        const text = await res.text();
+        this._cache.set(url, text);
+        return text;
+    }
+
+    async exists(p) {
+        try { await this.readFile(p); return true; }
+        catch { return false; }
+    }
+
+    // Sync versions — backed by cache, only valid after readFile has been called for that path
+    existsSync(p) {
+        return this._cache.has(this._resolve(p));
+    }
+
+    readFileSync(p, encoding) {
+        const cached = this._cache.get(this._resolve(p));
+        if (cached !== undefined) return cached;
+        throw new Error(`Not in cache: ${p}. Call readFile first.`);
+    }
+}

package/helpers/safeDataParser.js

@@ -28,7 +28,7 @@ export function safeDataParse(str) {
         if (char === '{') return parseObject();
         if (char === '[') return parseArray();
         if (char === '"' || char === "'") return parseString();
-        
+
         // Primitives or Unquoted identifiers
         return parsePrimitiveOrIdentifier();
     }
@@ -97,12 +97,12 @@ export function safeDataParse(str) {
             index++;
         }
         const token = s.slice(start, index);
-        
+
         if (token === "true") return true;
         if (token === "false") return false;
         if (token === "null") return null;
         if (!isNaN(Number(token))) return Number(token);
-        
+
         return token; // Fallback to string if it looks like an identifier
     }
 

package/helpers/spinner.js

@@ -0,0 +1,97 @@
+// Premium, dependency-free interactive terminal spinner for compilation feedback
+const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+let spinnerIndex = 0;
+let activeSpinner = null;
+let spinnerDepth = 0;
+
+let originalStdoutWrite = null;
+let originalStderrWrite = null;
+let redrawTimeout = null;
+
+export function startSpinner() {
+	if (typeof process === "undefined" || !process.stdout?.isTTY) {
+		spinnerDepth++;
+		return;
+	}
+	if (!activeSpinner) {
+		// Hide terminal cursor for a clean premium visual feel
+		process.stdout.write("\x1b[?25l");
+
+		// Print the first frame immediately
+		const frame = spinnerFrames[spinnerIndex];
+		process.stdout.write(`\r\x1b[38;5;39m${frame}\x1b[0m \x1b[1mSomMark:\x1b[0m \x1b[38;5;208mCompiling template...\x1b[0m`);
+		spinnerIndex = (spinnerIndex + 1) % spinnerFrames.length;
+
+		// Intercept stdout and stderr writes to keep the spinner on the very bottom line
+		originalStdoutWrite = process.stdout.write;
+		process.stdout.write = function(chunk, encoding, callback) {
+			originalStdoutWrite.call(process.stdout, "\r\x1b[K");
+			const res = originalStdoutWrite.call(process.stdout, chunk, encoding, callback);
+			if (activeSpinner) {
+				if (redrawTimeout) clearTimeout(redrawTimeout);
+				redrawTimeout = setTimeout(() => {
+					if (activeSpinner && originalStdoutWrite) {
+						const f = spinnerFrames[spinnerIndex];
+						originalStdoutWrite.call(process.stdout, `\r\x1b[38;5;39m${f}\x1b[0m \x1b[1mSomMark:\x1b[0m \x1b[38;5;208mCompiling template...\x1b[0m`);
+					}
+				}, 0);
+			}
+			return res;
+		};
+
+		originalStderrWrite = process.stderr.write;
+		process.stderr.write = function(chunk, encoding, callback) {
+			if (originalStdoutWrite) {
+				originalStdoutWrite.call(process.stdout, "\r\x1b[K");
+			}
+			const res = originalStderrWrite.call(process.stderr, chunk, encoding, callback);
+			if (activeSpinner) {
+				if (redrawTimeout) clearTimeout(redrawTimeout);
+				redrawTimeout = setTimeout(() => {
+					if (activeSpinner && originalStdoutWrite) {
+						const f = spinnerFrames[spinnerIndex];
+						originalStdoutWrite.call(process.stdout, `\r\x1b[38;5;39m${f}\x1b[0m \x1b[1mSomMark:\x1b[0m \x1b[38;5;208mCompiling template...\x1b[0m`);
+					}
+				}, 0);
+			}
+			return res;
+		};
+
+		activeSpinner = setInterval(() => {
+			const frame = spinnerFrames[spinnerIndex];
+			if (originalStdoutWrite) {
+				originalStdoutWrite.call(process.stdout, `\r\x1b[38;5;39m${frame}\x1b[0m \x1b[1mSomMark:\x1b[0m \x1b[38;5;208mCompiling template...\x1b[0m`);
+			} else {
+				process.stdout.write(`\r\x1b[38;5;39m${frame}\x1b[0m \x1b[1mSomMark:\x1b[0m \x1b[38;5;208mCompiling template...\x1b[0m`);
+			}
+			spinnerIndex = (spinnerIndex + 1) % spinnerFrames.length;
+		}, 80);
+	}
+	spinnerDepth++;
+}
+
+export function stopSpinner() {
+	spinnerDepth--;
+	if (spinnerDepth <= 0) {
+		spinnerDepth = 0;
+		if (activeSpinner) {
+			clearInterval(activeSpinner);
+			activeSpinner = null;
+
+			// Restore original writes
+			if (originalStdoutWrite) {
+				process.stdout.write = originalStdoutWrite;
+				originalStdoutWrite = null;
+			}
+			if (originalStderrWrite) {
+				process.stderr.write = originalStderrWrite;
+				originalStderrWrite = null;
+			}
+
+		if (typeof process !== "undefined" && process.stdout) {
+			// Clear the spinner line and restore the terminal cursor
+			process.stdout.write("\r\x1b[K\x1b[?25h");
+		}
+		}
+	}
+}

package/helpers/utils.js

@@ -168,3 +168,49 @@ export function levenshtein(a, b) {
         }
         return matrix[b.length][a.length];
 }
+
+// -- Unresolved Placeholder Helpers ---------------------------------------- //
+
+export const UNRESOLVED_PREFIX = "SOMMARK_UNRESOLVED";
+export const UNRESOLVED_SUFFIX = "SOMMARK";
+
+/**
+ * Official method to get the unique envelope for an unresolved prefix value.
+ * @param {string} prefix - The layer ('p' or 'v').
+ * @param {string} expectedValue - The placeholder key.
+ * @returns {string} - The unique envelope string.
+ */
+export function getPrefixValue(prefix, expectedValue) {
+	if (!prefix || (prefix !== "p" && prefix !== "v")) {
+		sommarkError([
+			`<$red:getPrefixValue Error:$> {N}`,
+			`<$yellow:prefix must be 'p' or 'v'. Received:$> <$cyan:'${prefix}'$>`
+		]);
+	}
+
+	if (!expectedValue || typeof expectedValue !== "string" || expectedValue.trim() === "") {
+		sommarkError([
+			`<$red:getPrefixValue Error:$> {N}`,
+			`<$yellow:expectedValue must be a non-empty string. Received:$> <$cyan:'${expectedValue}'$>`
+		]);
+	}
+
+	return `${UNRESOLVED_PREFIX}_${prefix}_${expectedValue}_${UNRESOLVED_SUFFIX}`;
+}
+
+/**
+ * Performs a final pass on a string to clean up any remaining unresolved envelopes.
+ * @param {string} content - The content to clean.
+ * @param {string|null} [fallback] - The format to use for missing keys (e.g., "$layer{$key}" or "").
+ * @returns {string} - The cleaned content.
+ */
+export function cleanUnresolved(content, fallback = null) {
+	const pattern = new RegExp(`${UNRESOLVED_PREFIX}_(p|v)_(.+?)_${UNRESOLVED_SUFFIX}`, "g");
+	return content.replace(pattern, (match, layer, key) => {
+		if (fallback !== null) {
+			return fallback.replace("$layer", layer).replace("$key", key);
+		}
+		// Default: Keep as is or restore classic
+		return `${layer}{${key}}`;
+	});
+}

package/helpers/virtual-fs.js

@@ -0,0 +1,29 @@
+import path from "pathe";
+
+/**
+ * Avoids any dependency on Node.js built-in modules (like buffer, path, stream).
+ */
+export class VirtualFS {
+    constructor(files = {}) {
+        this.files = {};
+        for (const [key, value] of Object.entries(files)) {
+            this.files[path.normalize(key)] = value;
+        }
+    }
+
+    existsSync(p) {
+        const normalized = path.normalize(p);
+        return normalized in this.files;
+    }
+
+    readFileSync(p, encoding) {
+        const normalized = path.normalize(p);
+        if (normalized in this.files) {
+            return this.files[normalized];
+        }
+        throw new Error(`File not found: ${p}`);
+    }
+
+    async exists(p) { return this.existsSync(p); }
+    async readFile(p, encoding) { return this.readFileSync(p, encoding); }
+}

package/index.browser.js

@@ -0,0 +1,87 @@
+import SomMark, { setDefaultFs, setDefaultCwd } from "./index.shared.js";
+export * from "./index.shared.js";
+
+setDefaultFs(null);
+setDefaultCwd("/");
+
+/**
+ * Resolves a relative path into a full URL using the current document location.
+ * Use this to set `baseDir` when loading .smark modules via fetch in the browser.
+ *
+ * @param {string} relativePath - Path relative to the HTML document (e.g. "./templates/").
+ * @returns {string} Absolute URL string suitable for use as `baseDir`.
+ *
+ * @example
+ * import SomMark, { resolveBaseDir } from "sommark/browser";
+ * const engine = new SomMark({ src, format: "html", baseDir: resolveBaseDir("./templates/") });
+ */
+export function resolveBaseDir(relativePath = "./") {
+    if (typeof document === "undefined") {
+        throw new Error(
+            "[SomMark] resolveBaseDir() can only be called in a browser environment.\n" +
+            "In Node.js, pass a file path directly as 'baseDir' instead."
+        );
+    }
+
+    if (typeof relativePath !== "string" || relativePath.trim() === "") {
+        throw new Error(
+            "[SomMark] resolveBaseDir() expects a non-empty string path, " +
+            `but received: ${JSON.stringify(relativePath)}`
+        );
+    }
+
+    try {
+        return new URL(relativePath, document.baseURI).href;
+    } catch (err) {
+        throw new Error(
+            `[SomMark] resolveBaseDir() could not resolve path '${relativePath}' ` +
+            `against document URL '${document.baseURI}'.\n${err.message}`
+        );
+    }
+}
+
+/**
+ * Injects compiled HTML into a container and activates any <script> tags inside it.
+ * Browsers intentionally skip scripts inserted via innerHTML — this re-creates each
+ * one as a live DOM element so they execute normally.
+ *
+ * @param {HTMLElement} container - The element to render into.
+ * @param {string} html - The compiled HTML string.
+ *
+ * @example
+ * import SomMark, { renderCompiledHTML } from "sommark/browser";
+ * const html = await new SomMark({ src, format: "html" }).transpile();
+ * renderCompiledHTML(document.getElementById("output"), html);
+ */
+export function renderCompiledHTML(container, html) {
+    if (typeof document === "undefined") {
+        throw new Error(
+            "[SomMark] renderCompiledHTML() can only be called in a browser environment."
+        );
+    }
+    if (!(container instanceof HTMLElement)) {
+        throw new TypeError(
+            "[SomMark] renderCompiledHTML() expects an HTMLElement as the first argument, " +
+            `but received: ${Object.prototype.toString.call(container)}`
+        );
+    }
+    if (typeof html !== "string") {
+        throw new TypeError(
+            "[SomMark] renderCompiledHTML() expects a string as the second argument, " +
+            `but received: ${Object.prototype.toString.call(html)}`
+        );
+    }
+
+    container.innerHTML = html;
+
+    for (const inertScript of container.querySelectorAll("script")) {
+        const liveScript = document.createElement("script");
+        for (const { name, value } of inertScript.attributes) {
+            liveScript.setAttribute(name, value);
+        }
+        liveScript.textContent = inertScript.textContent;
+        inertScript.replaceWith(liveScript);
+    }
+}
+
+export default SomMark;