mikel-jsx 0.40.0

package/README.md

@@ -0,0 +1,112 @@
+# mikel-jsx
+
+> **⚠️ Experimental.** This package is a work in progress — the tag syntax, attribute rules, and public API can change at any time without notice. Not recommended for production use yet.
+
+![npm version](https://badgen.net/npm/v/mikel-jsx?labelColor=1d2734&color=21bf81)
+![license](https://badgen.net/github/license/jmjuanes/mikel?labelColor=1d2734&color=21bf81)
+
+A plugin for [mikel](https://github.com/jmjuanes/mikel) that adds a JSX-style `<m-name>` tag for calling mikel directives (helpers and partials) from HTML-ish templates, as an alternative to the usual mustache syntax (`{{# }}`).
+
+```html
+<!-- before -->
+{{#header title="Hello" /}}
+{{#if isAdmin}}Admin!{{/if}}
+
+<!-- now, also available -->
+<m-header title="Hello" />
+<m-if isAdmin>Admin!</m-if>
+```
+
+## Installation
+
+```bash
+# install using NPM
+$ npm install mikel-jsx
+
+# install using YARN
+$ yarn add mikel-jsx
+```
+
+```js
+import mikel from "mikel";
+import mikelJsx from "mikel-jsx";
+
+const mk = mikel.create({ ... });
+
+mk.use(mikelJsx());
+```
+
+## Tag syntax
+
+Only tags whose name starts exactly with `m-` are recognized; any other tag (`<div>`, `<span>`, your own custom elements) is left completely untouched.
+
+```html
+<m-header title="Hello" />
+<!-- {{#header title="Hello" /}} -->
+
+<m-card title="Hello">
+    This content is available inside the partial as {{@content}}
+</m-card>
+<!-- {{#card title="Hello"}}...{{/card}} -->
+
+<m-if isAdmin>You're an admin</m-if>
+<!-- {{#if isAdmin}}...{{/if}} -->
+
+<m-each users limit="3">{{this.name}}</m-each>
+<!-- {{#each users limit="3"}}...{{/each}} -->
+```
+
+A tag with no attributes and a self-closing slash, `<m-slot />`, becomes `{{#slot /}}` — same rule, nothing special about it.
+
+## Attributes
+
+Each attribute is translated into a mikel argument (positional or keyword). There are just two things a value can be, and they mean the same thing whether the attribute is positional or keyword:
+
+- **quoted (`"..."`)**: always a plain string literal. `"5"` and `"true"` stay strings.
+- **braced (`{...}`)**: a raw mikel value: a variable path, a number, a boolean, a subexpression, or a spread. Whatever you put inside the braces is handed straight to mikel's own parser.
+
+| Written as   | Translates to... | Resulting type                                          |
+|--------------|-------------------|----------------------------------------------------------|
+| `name`       | `name`            | positional, variable/path (dots allowed: `user.name`)     |
+| `key="text"` | `key="text"`      | keyword, string literal, always                            |
+| `key={expr}` | `key=expr`        | keyword, raw value (variable, string, number, boolean, subexpression...) |
+| `{expr}`     | `expr`            | positional, raw value (for anything that isn't a plain identifier, e.g. `{(eq a b)}`) |
+| `{...expr}`  | `...expr`         | spread                                                     |
+
+Examples:
+
+```html
+<m-each users limit="3">...</m-each>
+<!-- {{#each users limit="3"}}...{{/each}} -->
+<!-- careful: this passes the STRING "3", not the number 3 -->
+
+<m-each users limit={3} skip={pageOffset}>...</m-each>
+<!-- {{#each users limit=3 skip=pageOffset}}...{{/each}} -->
+
+<m-user {...person} />
+<!-- {{#user ...person /}} -->
+```
+
+## Nesting
+
+Tags can be nested arbitrarily deep — the transform always resolves the innermost pair first:
+
+```html
+<m-card title="Outer">
+    <m-if isAdmin>
+        <m-each users>{{this.name}} </m-each>
+    </m-if>
+</m-card>
+```
+
+## Known limitations
+
+- An unescaped `>` inside a literal attribute breaks tag recognition (no HTML-specific escaping is performed).
+- Quotes must be straight (`"`), not curly/typographic (`“` `”`) — check that your editor isn't auto-correcting them.
+- Only double quotes (`"`) are recognized for attribute values, by design — single quotes (`'...'`) are intentionally not supported.
+- Literal content inside an example `<pre>`/`<code>` block would be transformed just like any other content — there's no escape hatch.
+- The `m-` prefix is effectively reserved: if you already use real custom elements with that prefix, they will collide.
+
+## License
+
+Licensed under the [MIT License](../../LICENSE).

package/index.d.ts

@@ -0,0 +1,10 @@
+import type { MikelTransform } from "mikel";
+
+declare function mikelJsxPlugin(): {
+    transform: MikelTransform,
+};
+
+export default mikelJsxPlugin;
+
+export declare function transform(content: string): string;
+export declare function parseAttributes(raw?: string): string;

package/index.js

@@ -0,0 +1,98 @@
+//
+// Adds a single JSX-style <m-name> tag for calling mikel directives
+// (helpers and partials — both share the same `#` mechanism now, so
+// there's nothing to disambiguate). One prefix, one output shape:
+//
+//   <m-header title="Hello" />             -->  {{#header title="Hello" /}}
+//   <m-if isAdmin>...</m-if>               -->  {{#if isAdmin}}...{{/if}}
+//   <m-each users skip={1} />...</m-each>  -->  {{#each users skip=1}}...{{/each}}
+//
+// Other tags (<div>, <span>, your own custom elements) are left untouched.
+//
+// Attribute rules:
+//   name               --> positional, raw value (bare attribute, dotted paths ok)
+//   key="literal"      --> keyword, string literal, always — never auto-typed
+//   key={expr}         --> keyword, raw value (variable, string, number, boolean, subexpression...)
+//   key="{expr}"       --> same as key={expr}, quoted so HTML linters don't flag it (undocumented, but tested)
+//   {expr}             --> positional, raw value (for values that aren't identifiers)
+//   {...expr}          --> spread
+
+// @description converts a raw HTML-like attribute string into a mikel argument string.
+// Supports, in this order of precedence (order matters for correct matching):
+//   {...expr}    --> spread                                      e.g. {...user}
+//   key="{expr}" --> keyword, raw value, quoted escape hatch      e.g. limit="{pageSize}"
+//   key="text"   --> keyword, string literal, always              e.g. title="Hello"
+//   key={expr}   --> keyword, raw value                           e.g. limit={pageSize}, flag={true}
+//   {expr}       --> positional, raw value                        e.g. {(eq a b)}
+//   name         --> positional, raw value (bare attr)             e.g. isAdmin, users
+const ATTR_RE = /\{\s*\.\.\.\s*([^}]+?)\s*\}|([a-zA-Z_][\w-]*)\s*=\s*"\{\s*([^}]+?)\s*\}"|([a-zA-Z_][\w-]*)\s*=\s*"([^"]*)"|([a-zA-Z_][\w-]*)\s*=\s*\{\s*([^}]+?)\s*\}|\{\s*([^}]+?)\s*\}|([a-zA-Z_][\w.-]*)/g;
+
+export const parseAttributes = (raw = "") => {
+    const parts = [];
+    let m;
+    ATTR_RE.lastIndex = 0;
+    while ((m = ATTR_RE.exec(raw))) {
+        const [, spread, quotedBracedKey, quotedBracedExpr, literalKey, literalValue, bracedKey, bracedExpr, bareExpr, bareName] = m;
+        if (spread !== undefined) {
+            parts.push(`...${spread.trim()}`);
+        } else if (quotedBracedKey !== undefined) {
+            parts.push(`${quotedBracedKey}=${quotedBracedExpr.trim()}`);
+        } else if (literalKey !== undefined) {
+            parts.push(`${literalKey}="${literalValue}"`);
+        } else if (bracedKey !== undefined) {
+            parts.push(`${bracedKey}=${bracedExpr.trim()}`);
+        } else if (bareExpr !== undefined) {
+            parts.push(bareExpr.trim());
+        } else if (bareName !== undefined) {
+            parts.push(bareName);
+        }
+    }
+    return parts.join(" ");
+};
+
+// matches a self-closing tag: <m-name attrs />
+const SELF_CLOSING_RE = /<m-([a-zA-Z_][\w-]*)((?:\s+[^<>]*?)?)\s*\/>/;
+
+// matches an innermost paired tag: <m-name attrs>...</m-name>. The negative
+// lookahead in the content group stops the match before any nested custom
+// tag, so the innermost pair is always resolved first.
+const PAIRED_RE = /<m-([a-zA-Z_][\w-]*)((?:\s+[^<>]*?)?)\s*>((?:(?!<m-)[\s\S])*?)<\/m-\1\s*>/;
+
+// @description replaces one match at a time, re-searching after each
+// replacement (needed since nested tags only become matchable once their
+// inner tags have already been resolved)
+const replaceAll = (str, re, replacer) => {
+    let match;
+    while ((match = re.exec(str))) {
+        str = str.slice(0, match.index) + replacer(match) + str.slice(match.index + match[0].length);
+    }
+    return str;
+};
+
+// @description the actual template transform: string in, string out.
+// No lookup, no ambiguity: every <m-name> becomes {{#name ...}}, since
+// helpers and partials are now the same underlying mechanism in mikel.
+export const transform = content => {
+    // 1. self-closing tags first: no nesting to worry about
+    content = replaceAll(content, SELF_CLOSING_RE, ([, name, attrs]) => {
+        const args = parseAttributes(attrs);
+        const suffix = args ? ` ${args}` : "";
+        return `{{#${name}${suffix} /}}`;
+    });
+    // 2. paired (block) tags, innermost first, repeated until none are left
+    content = replaceAll(content, PAIRED_RE, ([, name, attrs, inner]) => {
+        const args = parseAttributes(attrs);
+        const suffix = args ? ` ${args}` : "";
+        return `{{#${name}${suffix}}}${inner}{{/${name}}}`;
+    });
+    return content;
+};
+
+// @description mikel plugin: a factory returning a plain options object for
+// mk.use(), following the same convention as mikel.SetStatePlugin — call it
+// to get the object, then pass that to use(): mk.use(mikelJsx())
+export default () => {
+    return {
+        transform: transform,
+    };
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "mikel-jsx",
+    "description": "JSX/XML style tags for mikel templating.",
+    "version": "0.40.0",
+    "type": "module",
+    "license": "MIT",
+    "author": {
+        "name": "Josemi Juanes",
+        "email": "hello@josemi.xyz"
+    },
+    "repository": {
+        "url": "https://github.com/jmjuanes/mikel",
+        "directory": "packages/mikel-jsx"
+    },
+    "bugs": "https://github.com/jmjuanes/mikel/issues",
+    "types": "index.d.ts",
+    "scripts": {
+        "test": "node test.js"
+    },
+    "exports": {
+        ".": {
+            "import": "./index.js",
+            "types": "./index.d.ts"
+        },
+        "./index.js": {
+            "import": "./index.js",
+            "types": "./index.d.ts"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "README.md",
+        "index.js",
+        "index.d.ts"
+    ],
+    "keywords": [
+        "mikel",
+        "jsx",
+        "xml",
+        "templating"
+    ]
+}