sommark 4.0.3 → 4.2.0

package/README.md

@@ -1,134 +1,365 @@
-# SomMark v4 <img src="assets/smark.logo.png" width="80" align="right">
+# SomMark <img src="assets/smark.logo.png" width="80" align="right">
 
 [![npm version](https://img.shields.io/npm/v/sommark.svg)](https://www.npmjs.com/package/sommark)
+[![Browser Support](https://img.shields.io/badge/browser-supported-brightgreen)](https://www.npmjs.com/package/sommark)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 [![license](https://img.shields.io/npm/l/sommark.svg)](https://github.com/Adam-Elmi/SomMark/blob/master/LICENSE)
 
 SomMark is a high-performance markup language designed for structured content. It acts as an extensible source language that can be transformed into multiple formats like HTML, JSON, MDX, XML, and Markdown.
 
 SomMark uses explicit structural boundaries to ensure your document remains stable and predictable. It enables infinite nesting and provides total control over your contents.
 
+> **v4.2.0 — Browser Support**: SomMark now compiles templates directly in the browser with no Node.js dependencies. Use the `sommark/browser` entry point with any bundler (Vite, Webpack, Rollup, esbuild). See [Browser API docs](docs/api/Browser/) for `resolveBaseDir` and `renderCompiledHTML`.
+
+---
+
+## Install
+
+#### 1. Global (Command Line)
+Install SomMark globally to use the `sommark` command.
+```bash
+npm install -g sommark
+```
+
+To verify it is working, check the version:
+```bash
+sommark --version
+```
+
+#### 2. Local (Project API)
+Add SomMark to your project as a dependency:
+```bash
+npm install sommark
+```
+
 ---
 
-## Simple Showcase
+## Features
 
-SomMark uses blocks for structure. A block starts with `[identifier]` and must end with `[end]`.
+### Blocks
+
+Blocks are the primary containers in SomMark, used to group, style, and organize structural content. A block starts with `[identifier]` and closes with a matching `[end]` or self-closing `!` if the block does not have any content, for example `[br!]` or `[img = src: "logo.png" !]`. 
 
-### HTML
 ```ini
-[h1]Welcome to SomMark[end]
+[div = class: "container"]
+  [h1]Welcome to SomMark[end]
+  [p]Structured content, zero guesswork.[end]
+  [hr = class: "divider" !]
+[end]
+```
+[Read more about blocks](./docs/syntax/block.md)
 
-[div = class: "main"]
-  This is content inside a container block.
-  [p]
-    Blocks are the most important part of SomMark.
-    (This is a span-like inline statement)->(css: "color: green")
-  [end]
+### Self-Closing Blocks
+
+Blocks that carry no body content close instantly with `!`.
+
+```ini
+[br!]
+[hr = class: "divider" !]
+[img = src: "logo.png", alt: "SomMark Logo" !]
+```
+[Read more about self-closing blocks](./docs/syntax/self-closing.md)
+
+### Inline Elements
+
+Apply styling or formatting to specific spans of text within a block using `(inline text)->(identifier = args)` or `(inline text)->(identifier: args)`. Internal newlines and duplicate spaces are automatically collapsed into a single space.
+
+```ini
+[p]
+  This is (important text)->(bold).
+  Visit the (SomMark Website)->(link = "https://sommark.org", target: "_blank").
 [end]
 ```
+[Read more about inline elements](./docs/syntax/inline.md)
+
+### Props (Properties)
+
+Pass metadata (called **Props**, similar to component properties in React/Vue) to Blocks, Inline Elements, and At-Blocks. SomMark supports positional, named, and mixed props with multiple value types (JS data, placeholders, and variables).
+
+> [!NOTE]
+> In the current major version, SomMark passes these properties under the **`args`** key to custom JavaScript `render` functions for backward compatibility. This will be renamed to `props` in the next major version.
+
+* **Blocks**: Passed after `=` (e.g., `[div = "container"][end]`).
+* **Inline Elements**: Passed after `=` or `:` inside the identifier parenthesis (e.g., `(text)->(link = "url")`).
+* **At-Blocks**: Passed after `:` and terminated with `;` (e.g., `@_code: lang: "js";`).
+
+**Blocks** — props come after `=`, separated by commas. Positional args have no key; named args use `key: value`.
+```ini
+[div = "container", class: "flex"][end]
+#      ↑ positional   ↑ named
+```
 
-### JSON
-SomMark can represent complex data structures through its specialized mappers.
+**Inline Elements** — same prop syntax, after `=` or `:` inside the identifier.
 ```ini
-[object]
-  [string = key: "name"]Adam Elmi[end]
-  [number = key: "age"]25[end]
-  [array = key: "skills"]
-    [string]JavaScript[end]
-    [string]SomMark[end]
-  [end]
+(Visit Website)->(link = "https://sommark.org", target: "_blank")
+#                       ↑ positional url         ↑ named prop
+```
+
+**At-Blocks** — props follow `:` on the opening line and are terminated with `;`. The body is captured as raw text.
+```ini
+@_code: lang: "js", active: js{true}, user: v{userId};
+#               ↑ string   ↑ native JS value  ↑ local variable
+  console.log("Hello World");
+@_end_@
+```
+
+**Static logic as a prop value** — any prop value can be a compile-time expression.
+```ini
+[Date = year: static ${ new Date().getFullYear() }$][end]
+```
+
+### At-Blocks -- Raw Content
+
+At-blocks capture raw text. Brackets, tags, and comments inside them are treated as literal characters and never parsed.
+
+```ini
+@_code_@: lang: "javascript";
+  const items = [1, 2, 3];
+  // This [div] won't be parsed
+@_end_@
+```
+
+### Comments
+
+Single-line and multi-line. Completely removed from the compiled output.
+
+```ini
+# This is a single-line comment
+
+###
+  This is a multi-line comment.
+  Nothing here reaches the output.
+###
+```
+
+### Static Logic -- Compile-Time JavaScript
+
+Run JavaScript during compilation inside a sandboxed QuickJS VM. The result replaces the block inline.
+
+```ini
+[footer]
+  Copyright static ${ new Date().getFullYear() }$
 [end]
 ```
 
-### XML
-SomMark produces clean, structured XML ideal for configuration and data manifests.
+Use it in props too:
+
 ```ini
-[xml = version: "1.0"][end]
-[project = name: "SomMark-App"]
-  [metadata]
-    [author]Adam Elmi[end]
-    [version]4.0.0[end]
-  [end]
-  [settings]
-    [database = type: "postgres"]
-      [host]localhost[end]
-      [port]5432[end]
-    [end]
-  [end]
+[Date = year: static ${ new Date().getFullYear() }$][end]
+```
+
+### Runtime Logic -- Client-Side JavaScript
+
+Preserve JavaScript in the compiled output. It runs in the browser, not during compilation.
+
+```ini
+[button]
+  runtime ${
+    self.addEventListener("click", () => alert("Hello from SomMark"))
+  }$
+  Click Me
 [end]
 ```
 
-### MDX
-Use the JavaScript data layer to pass native data to your components.
+### For-Each Loop
+
+Iterate over arrays and render blocks for each item. Access the current item and its index.
+
 ```ini
-[h1]MDX Portfolio[end]
+[for-each = static ${ [{name: "Adam"}, {name: "Hawa"}, {name: "Ilham"}] }$, as: "user"]
+  [li]static ${ user.name }$ -- position static ${ user_index }$[end]
+[end]
+```
+
+### Modules and Components
+
+Split your project into reusable `.smark` files. Import them, pass props, and inject body content through slots.
 
-[Gallery = 
-  images: js{["nature.jpg", "tech.jpg"]}, 
-  active: js{true}
-]
-  This block uses native JS arrays and booleans.
+**`components/Card.smark`**
+```ini
+[div = class: "card"]
+  [h2]v{title}[end]
+  [div = class: "card-body"]
+    [slot][end]
+  [end]
 [end]
 ```
 
-### Markdown
-Use placeholders to inject dynamic text into your templates.
+**`page.smark`**
 ```ini
-[h1]Hello p{username}[end]
+[import = Card: "./components/Card.smark"][end]
 
-[quote]
-  You are reading documentation on p{siteName}.
-  SomMark is an extensible language.
+[Card = title: "Featured Product"]
+  This content fills the slot inside the card.
 [end]
+```
+
+You can also inject a module without passing body content:
 
-[hr][end]
+```ini
+[import = Card: "./components/Card.smark"][end]
+[$use-module = Card][end]
 ```
 
 ---
 
-## How It Works
-
-SomMark is an extensible language that processes content through a four-stage pipeline:
+## Output Formats
 
-1.  **Lexing**: The engine scans the source and converts it into a stream of tokens.
-2.  **Parsing**: Tokens are organized into a hierarchical tree called an **AST** (Abstract Syntax Tree).
-3.  **Mapping**: This is the translation layer. You define how identifiers (like `[h1]`) look in the target language.
-4.  **Transpilation**: The engine walks the AST and uses the Mapper to generate the final string output.
+Write once, compile to any of these:
 
-The **Module System** enables a "Declare-then-Inject" pattern, allowing you to import mappers and create scalable projects with full recursive support.
+| Format   | CLI Flag     | Extension |
+|----------|--------------|-----------|
+| HTML     | `--html`     | `.html`   |
+| Markdown | `--markdown` | `.md`     |
+| MDX      | `--mdx`      | `.mdx`    |
+| JSON     | `--json`     | `.json`   |
+| JSONC    | `--jsonc`    | `.jsonc`  |
+| XML      | `--xml`      | `.xml`    |
+| Text     | `--text`     | `.txt`    |
 
 ---
 
-## Installation
-
-Install the SomMark CLI globally:
+## CLI
 
-```bash
-npm install -g sommark
+```
+sommark init                           Create a smark.config.js file
+sommark --html <file>                  Compile to HTML
+sommark --markdown <file>              Compile to Markdown
+sommark --html <file> -o <name> <dir>  Set output filename and directory
+sommark --html --print <file>          Print compiled output to terminal
+sommark --lex <file>                   Show the token stream
+sommark --parse <file>                 Show the syntax tree
+sommark show config [file]             Show the resolved configuration
+sommark -v                             Show version
+sommark -h                             Show help
 ```
 
 ---
 
-## Usage in Node.js
+## Programmatic Usage
 
-```javascript
+**Node.js**
+```js
 import SomMark from "sommark";
 
-const sm = new SomMark({
-  src: "[h1]Hello World[end]",
-  format: "html"
+const engine = new SomMark({
+  src: '[h1]Hello World[end]',
+  format: "html",
 });
 
-const output = await sm.transpile();
+const output = await engine.transpile();
 // <h1>Hello World</h1>
 ```
 
+**Browser** (v4.2.0+)
+```js
+import SomMark, { resolveBaseDir, renderCompiledHTML } from "sommark/browser";
+
+const src = await fetch("./main.smark").then(r => r.text());
+
+const engine = new SomMark({
+  src,
+  format: "html",
+  baseDir: resolveBaseDir("./templates/"), // resolves imports via fetch
+});
+
+renderCompiledHTML(document.getElementById("output"), await engine.transpile());
+```
+
+---
+
+## Configuration
+
+Run `sommark init` to generate a `smark.config.js` with all available settings:
+
+```js
+export default {
+  format: "html",
+  removeComments: true,
+  generateRuntimeOutput: false,
+  hideRuntimeOutput: false,
+  customProps: [],
+  placeholders: {},
+  importAliases: { "@": "./" },
+  fallbackTarget: "style",
+  outputValidator: null,
+  baseDir: null,
+  showSpinner: true,
+  security: {
+    allowRaw: true,
+    maxDepth: 5,
+    timeout: 5000,
+    allowFetch: true,
+    allowHttp: false,
+    allowedOrigins: [],
+    allowedExtensions: [],
+    sanitize: null,
+  },
+  outputDir: "./",
+  outputFile: "output",
+};
+```
+
+---
+
+## Security
+
+All embedded JavaScript runs inside a **QuickJS sandbox** with strict restrictions:
+
+| Setting             | Default | What it does                                 |
+|---------------------|---------|----------------------------------------------|
+| `allowRaw`          | `true`  | Allow raw code in static blocks              |
+| `maxDepth`          | `5`     | Maximum import nesting depth                 |
+| `timeout`           | `5000`  | Script execution time limit (ms)             |
+| `allowFetch`        | `true`  | Allow network requests from scripts          |
+| `allowHttp`         | `false` | Block insecure HTTP (HTTPS only by default)  |
+| `allowedOrigins`    | `null`  | Restrict fetch to specific domains           |
+| `allowedExtensions` | `null`  | Restrict which file types can be imported    |
+| `sanitize`          | `null`  | Custom function to sanitize HTML output      |
+
+---
+
+## Custom Output Rules
+
+Define your own tags and rendering logic with the Mapper API:
+
+```js
+import SomMark, { Mapper } from "sommark";
+
+const mapper = new Mapper("custom");
+
+mapper.register("alert", (node) => {
+  return `<div class="alert">${node.body}</div>`;
+});
+
+const engine = new SomMark({
+  src: '[alert]Check your configuration.[end]',
+  format: "html",
+  mapperFile: mapper,
+});
+
+const output = await engine.transpile();
+```
+
+Full reference in [`docs/api/Mapper`](docs/api/Mapper).
+
 ---
 
 ## Documentation
 
-Read the full guides in the `docs/` folder:
+| Topic            | Location                                      |
+|------------------|-----------------------------------------------|
+| Syntax Reference | [`docs/syntax/`](docs/syntax)                 |
+| Core API         | [`docs/api/Core/`](docs/api/Core)             |
+| Browser API      | [`docs/api/Browser/`](docs/api/Browser)       |
+| Mapper API       | [`docs/api/Mapper/`](docs/api/Mapper)         |
+| Sandbox API      | [`docs/api/Sandbox/`](docs/api/Sandbox)       |
+| Output Formats   | [`docs/languages/`](docs/languages)           |
+| CLI Guide        | [`docs/cli/`](docs/cli)                       |
+| Configuration    | [`docs/cli/config.md`](docs/cli/config.md)    |
+
+---
+
+## License
 
-*   **[Syntax Guide](docs/syntax/syntax.md)**: Rules for writing Blocks, At-Blocks, and Inlines.
-*   **[Core Logic](docs/core/core.md)**: Deep dive into the engine architecture.
-*   **[Mapper API](docs/core/mapper.md)**: How to create your own translation layers.
-*   **[Module System](docs/core/module-system.md)**: Managing multi-file projects.
+[MIT](LICENSE) -- Adam Elmi

package/cli/cli.mjs

@@ -70,7 +70,7 @@ async function main() {
 		runColor(args[1]);
 		return;
 	}
-	
+
 
 	// 6. Lex
 	if (command === "--lex") {

package/cli/commands/build.js

@@ -5,7 +5,9 @@ import HTML from "../../mappers/languages/html.js";
 import MARKDOWN from "../../mappers/languages/markdown.js";
 import MDX from "../../mappers/languages/mdx.js";
 import Json from "../../mappers/languages/json.js";
+import Jsonc from "../../mappers/languages/jsonc.js";
 import XML from "../../mappers/languages/xml.js";
+import TEXT from "../../mappers/languages/text.js";
 import { extensions } from "../constants.js";
 import { isExist, readContent, createFile } from "../helpers/file.js";
 import { loadConfig } from "../helpers/config.js";
@@ -78,7 +80,7 @@ export async function runBuild(format_option, sourcePath, outputFlag, outputFile
                 let mapperFile = config.mapperFile || config.mappingFile;
 
                 if (!mapperFile) {
-                    mapperFile = format === "html" ? HTML : format === "markdown" ? MARKDOWN : format === "mdx" ? MDX : format === "json" ? Json : format === "xml" ? XML : null;
+                    mapperFile = format === "html" ? HTML : format === "markdown" ? MARKDOWN : format === "mdx" ? MDX : format === "json" ? Json : format === "jsonc" ? Jsonc : format === "xml" ? XML : format === "text" ? TEXT : null;
                 }
 
                 // CLI Overrides

package/cli/commands/help.js

@@ -28,7 +28,9 @@ export function getHelp(unknown_option = true) {
 		"{N}  <$green:--html$>         <$cyan: Transpile to HTML$>",
 		"{N}  <$green:--markdown$>     <$cyan: Transpile to Markdown$>",
 		"{N}  <$green:--mdx$>          <$cyan: Transpile to MDX$>",
+		"{N}  <$green:--xml$>          <$cyan: Transpile to XML$>",
 		"{N}  <$green:--json$>         <$cyan: Transpile to JSON$>",
+		"{N}  <$green:--jsonc$>        <$cyan: Transpile to JSON with Comments (JSONC)$>",
 		"{N}  <$green:--text$>         <$cyan: Transpile to plain text$>",
 		"{N}  <$green:--lex$>          <$cyan: Print lexer tokens to console$>",
 		"{N}  <$green:--parse$>        <$cyan: Print parser AST to console$>",

package/cli/commands/init.js

@@ -19,12 +19,31 @@ export async function runInit() {
  * Generated by 'smark init'
  */
 export default {
-    format: "html",           // Target output format (html, markdown, mdx, json, xml)
-    removeComments: true,    // Strip SomMark comments from the final output
-    customProps: [],         // Whitelisted HTML attributes (prevents CSS hijacking)
-    placeholders: {},        // Global p{key} variables for content injection
-    outputDir: "./",         // Where to save the transpiled files
-    outputFile: "output",    // Default output filename
+    format: "html",              // Target output format (html, markdown, mdx, json, xml, jsonc, text)
+    removeComments: true,       // Strip SomMark comments from the final output
+    generateRuntimeOutput: false, // Generate only VM script bundles, ignoring markup layouts
+    hideRuntimeOutput: false,     // Strip all <script> tags from final compiled HTML outputs
+    customProps: [],            // Whitelisted HTML attributes
+    placeholders: {},           // Global p{key} placeholders for content injection
+    importAliases: {            // Custom path aliases for modules (e.g. { "@": "./src/components" })
+        "@": "./"
+    },
+    fallbackTarget: "style",    // Where unrecognized attributes go: "style", "class", or false to disable
+    outputValidator: null,      // Custom callback function: async (transpiledOutput) => { ... }
+    baseDir: null,              // Base directory for resolving relative module imports
+    showSpinner: true,          // Display a dynamic spinner in the terminal during transpilation
+    security: {                 // Sandbox and security restrictions for module execution
+        allowRaw: true,         // Permit raw code blocks in static logic blocks
+        maxDepth: 5,            // Maximum allowed import nesting depth
+        timeout: 5000,          // Timeout in milliseconds for scripts to execute
+        allowFetch: true,       // Allow fetch queries inside runtime logic block execution
+        allowHttp: false,       // Disallow http requests (highly recommended to keep false)
+        allowedOrigins: [],     // Whitelisted HTTP origins/domains for fetch requests (e.g. ["api.github.com"])
+        allowedExtensions: [],  // Whitelisted file extensions for local module imports (e.g. [".smark", ".json"])
+        sanitize: null,         // Custom output HTML string sanitization function: (html) => { ... }
+    },
+    outputDir: "./",            // Where to save the transpiled files
+    outputFile: "output",       // Default output filename
 };
 `;
 

package/cli/constants.js

@@ -4,7 +4,7 @@
  */
 
 /** @type {Array<string>} List of recognized CLI flags and commands. */
-export const options = ["-v", "--version", "-h", "--help", "--html", "--markdown", "--mdx", "--json", "--text", "--xml", "--print", "-p", "--lex", "--parse", "list"];
+export const options = ["-v", "--version", "-h", "--help", "--html", "--markdown", "--mdx", "--json", "--jsonc", "--text", "--xml", "--print", "-p", "--lex", "--parse", "list"];
 
 /** @type {Object<string, string>} Map of output formats to their respective file extensions. */
 export const extensions = {
@@ -13,5 +13,6 @@ export const extensions = {
 	markdown: "md",
 	mdx: "mdx",
 	json: "json",
+	jsonc: "jsonc",
 	xml: "xml"
 };

package/cli/helpers/transpile.js

@@ -6,11 +6,13 @@ import HTML from "../../mappers/languages/html.js";
 import MARKDOWN from "../../mappers/languages/markdown.js";
 import MDX from "../../mappers/languages/mdx.js";
 import Json from "../../mappers/languages/json.js";
+import Jsonc from "../../mappers/languages/jsonc.js";
+import XML from "../../mappers/languages/xml.js";
 import { isExist } from "./file.js";
 import { loadConfig } from "./config.js";
-import { htmlFormat, markdownFormat, mdxFormat, jsonFormat, textFormat } from "../../core/formats.js";
+import { htmlFormat, markdownFormat, mdxFormat, jsonFormat, jsoncFormat, xmlFormat, textFormat } from "../../core/formats.js";
 
-const default_mapperFiles = { [htmlFormat]: HTML, [markdownFormat]: MARKDOWN, [mdxFormat]: MDX, [jsonFormat]: Json, [textFormat]: null };
+const default_mapperFiles = { [htmlFormat]: HTML, [markdownFormat]: MARKDOWN, [mdxFormat]: MDX, [jsonFormat]: Json, [jsoncFormat]: Jsonc, [xmlFormat]: XML, [textFormat]: null };
 
 // ========================================================================== //
 //  Transpile Function                                                        //
@@ -50,6 +52,7 @@ export async function transpile({ src, format, filename = null, mapperFile = "",
         format,
         filename,
         mapperFile: finalMapper,
+        showSpinner: finalConfig.showSpinner !== false
     });
 
     return await smark.transpile();

package/constants/html_props.js

@@ -36,6 +36,7 @@ export const HTML_PROPS = new Set([
 	"decoding",
 	"crossorigin",
 	"charset",
+	"content",
 	"action",
 	"method",
 	"enctype",