sommark 4.0.3 → 4.1.0

package/README.md

@@ -1,4 +1,4 @@
-# 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)
 [![license](https://img.shields.io/npm/l/sommark.svg)](https://github.com/Adam-Elmi/SomMark/blob/master/LICENSE)
@@ -9,126 +9,327 @@ SomMark uses explicit structural boundaries to ensure your document remains stab
 
 ---
 
-## Simple Showcase
+## Install
 
-SomMark uses blocks for structure. A block starts with `[identifier]` and must end with `[end]`.
+#### 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
+```
+
+---
+
+## Features
+
+### 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";`).
 
-### JSON
-SomMark can represent complex data structures through its specialized mappers.
 ```ini
-[object]
-  [string = key: "name"]Adam Elmi[end]
-  [number = key: "age"]25[end]
-  [array = key: "skills"]
-    [string]JavaScript[end]
-    [string]SomMark[end]
-  [end]
+# Blocks (using '=')
+[div = "container", class: "flex"][end]
+
+# Inline Elements (using '=' or ':')
+(Visit Website)->(link = "https://sommark.org", target: "_blank")
+
+# At-Blocks (using ':' and terminated with ';')
+@_code: lang: "js", active: js{true}, user: v{userId};
+  console.log("Hello World");
+@_end_@
+
+# Passing static logic to props
+[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
 
-[Gallery = 
-  images: js{["nature.jpg", "tech.jpg"]}, 
-  active: js{true}
-]
-  This block uses native JS arrays and booleans.
+Split your project into reusable `.smark` files. Import them, pass props, and inject body content through slots.
+
+**`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
+## Output Formats
 
-SomMark is an extensible language that processes content through a four-stage pipeline:
+Write once, compile to any of these:
 
-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.
-
-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
+```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>
 ```
 
 ---
 
+## 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)             |
+| 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",