mikel 0.32.0 → 0.33.0

package/README.md

@@ -237,19 +237,6 @@ Partial metadata can be accessed using the `@partial` variable inside the partia
 - `@partial.attributes`: the custom data provided to the partial (if any).
 - `@partial.context`: the current rendering context.
 
-### Inline partials
-
-> Added in `v0.28.0`.
-
-Inline partials allows you to define partials directly in your template. Use `>*` followed by the partial name to start the partial definition, and end the partial definition with a slash `/` followed by the partial name. For example, `{{>*foo}}` begins a partial definition called `foo`, and `{{/foo}}` ends it.
-
-Example:
-
-```javascript
-const result = m(`{{>*foo}}Hello {{name}}!{{/foo}}{{>foo name="Bob"}}`, {});
-// Output: 'Hello Bob!'
-```
-
 ### Helpers
 
 > Added in `v0.4.0`.
@@ -407,6 +394,78 @@ The `raw` helper allows to render the content of the block without evaluating it
 console.log(m("{{#raw}}Hello {{name}}!{{/raw}}", {name: "Bob"})); // --> 'Hello {{name}}!'
 ```
 
+#### slot
+
+> Added in `v0.33.0`.
+
+The `slot` helper allows you to capture a block of template content and store it under a named key. Captured slots become available through the special `@slot` state variable.
+    
+```javascript
+const template = `
+{{#slot "name"}}Bob{{/slot}}
+
+Hello {{@slot.name}}!
+`;
+
+console.log(m(template, {})); // --> 'Hello Bob!'
+```
+
+Slots are evaluated at render time, so they can contain variables, helpers, or any other template expressions. If the same slot name is defined more than once, **the last definition wins**.
+
+#### macro
+
+> Added in `v0.33.0`.
+
+The `macro` helper allows you to register reusable chunks of content. Use `#macro` followed by the name of the reusable chunk.
+
+Example:
+
+```javascript
+const template = `
+{{#macro "foo"}}
+Hello {{name}}!
+{{/macro}}
+
+{{#call name="Bob"}}{{/call}}
+`;
+
+console.log(m(template, {})); // --> 'Hello Bob!'
+```
+
+Macros can be executed using the `#call` helper.
+
+#### call
+
+> Added in `v0.33.0`.
+
+The `call` helper allows you to execute registered macros. Key-value arguments will be passed as a data to the content inside the macro:
+
+```javascript
+const template = `
+{{#macro "sayHello"}}
+Hello {{this.name}}!!
+{{/macro}}
+
+{{#call "sayHello" name="Bob"}}{{/call}}
+`;
+
+console.log(m(template, {})); // --> 'Hello Bob!!'
+```
+
+Content inside the `#call` tag will be passed to the macro content in a `@content` state variable, similar as block partials.
+
+```javascript
+const template = `
+{{#macro "foo"}}
+Hello {{@content}}!!
+{{/macro}}
+
+{{#call "foo"}}Bob{{/call}}
+`;
+
+console.log(m(template, {})); // --> 'Hello Bob!!'
+```
+
 ### Custom Helpers
 
 > Added in `v0.5.0`.
@@ -438,7 +497,7 @@ Custom helper functions receive a single `params` object as argument, containing
 - `args`: an array containing the variables with the helper is called in the template.
 - `options`: an object containing the keyword arguments provided to the helper.
 - `data`: the current data where the helper has been executed.
-- `variables`: an object containing the runtime variables available in the current context (e.g., `@root`, `@index`, etc.).
+- `state`: an object containing the state variables available in the current context (e.g., `@root`, `@index`, etc.).
 - `fn`: a function that executes the template provided in the helper block and returns a string with the evaluated template in the provided context.
 
 The helper function must return a string, which will be injected into the result string. Example:
@@ -501,11 +560,11 @@ Inside any helper block, you can access metadata about the current invocation th
 - `@helper.options`: an object containing named (key-value) arguments.
 - `@helper.context`: the current rendering context.
 
-### Runtime Variables
+### State Variables
 
 > Added in `v0.4.0`.
 
-Runtime Variables in Mikel provide convenient access to special values within your templates. These variables, denoted by the `@` symbol, allow users to interact with specific data contexts or values at runtime. Runtime variables are usually generated by helpers like `#each`.
+State Variables in Mikel provide convenient access to special values within your templates. These variables, denoted by the `@` symbol, allow users to interact with specific data contexts or values at runtime. State variables are usually generated by helpers like `#each`.
 
 #### @root
 
@@ -567,7 +626,7 @@ Functions will receive a single `params` object as argument, containing the foll
 - `args`: an array containing the variables with the function is called in the template.
 - `options`: an object containing the keyword arguments provided to the function.
 - `data`: the current data object where the function has been executed.
-- `variables`: an object containing the runtime variables available in the current context (e.g., `@root`, `@index`, etc.).
+- `state`: an object containing the state variables available in the current context (e.g., `@root`, `@index`, etc.).
 
 Example:
 

package/index.d.ts

@@ -1,11 +1,15 @@
+export type MikelHelperCallback = (
+    data?: Record<string, any>,
+    state?: Record<string, any>,
+) => string;
+
 export type MikelHelper = (params: {
     args: any[];
-    opt?: Record<string, any>;
     options: Record<string, any>;
     tokens: string[];
     data: Record<string, any>;
-    variables: Record<string, any>;
-    fn: (blockData?: Record<string, any>, blockVars?: Record<string, any>, blockOutput?: string[]) => string;
+    state: Record<string, any>;
+    fn: MikelHelperCallback;
 }) => string;
 
 export type MikelPartial = {
@@ -15,29 +19,24 @@ export type MikelPartial = {
 
 export type MikelFunction = (params: {
     args: any[];
-    opt?: Record<string, any>;
     options: Record<string,any>;
     data: Record<string, any>;
-    variables: Record<string, any>;
+    state: Record<string, any>;
 }) => string | void;
 
-export type MikelContext = {
-    helpers: Record<string, MikelHelper>;
-    partials: Record<string, string | MikelPartial>;
-    functions: Record<string, MikelFunction>;
-    variables: Record<string, any>;
-};
-
 export type MikelOptions = {
     helpers?: Record<string, MikelHelper>;
     partials?: Record<string, string | MikelPartial>;
     functions?: Record<string, MikelFunction>;
-    variables?: Record<string, any>;
+};
+
+export type MikelUseOptions = MikelOptions & {
+    initialState?: Record<string, any>;
 };
 
 export type Mikel = {
     (template: string, data?: any): string;
-    use(options: Partial<MikelOptions> | ((ctx: MikelContext) => void)): Mikel;
+    use(options: Partial<MikelUseOptions>): void;
     addHelper(name: string, fn: MikelHelper): void;
     removeHelper(name: string): void;
     addFunction(name: string, fn: MikelFunction): void;

package/index.js

@@ -64,31 +64,31 @@ const tokenizeArgs = (str = "", tokens = [], strings = []) => {
 };
 
 // @description parse string arguments
-const parseArgs = (str = "", data = {}, vars = {}, fns = {}, argv = [], opt = {}) => {
+const parseArgs = (str = "", data = {}, state = {}, fns = {}, argv = [], opt = {}) => {
     const [t, ...args] = tokenizeArgs(str.trim());
     args.forEach(argStr => {
         if (argStr.includes("=") && !argStr.startsWith(`"`)) {
             const [k, v] = argStr.split("=");
-            opt[k] = parse(v, data, vars, fns);
+            opt[k] = parse(v, data, state, fns);
         }
         else if (argStr.startsWith("...")) {
-            const value = parse(argStr.replace(/^\.{3}/, ""), data, vars, fns);
+            const value = parse(argStr.replace(/^\.{3}/, ""), data, state, fns);
             if (!!value && typeof value === "object") {
                 Array.isArray(value) ? argv.push(...value) : Object.assign(opt, value);
             }
         }
         else {
-            argv.push(parse(argStr, data, vars, fns));
+            argv.push(parse(argStr, data, state, fns));
         }
     });
     return [t, argv, opt];
 };
 
 // @description evaluate an expression
-const evaluateExpression = (str = "", data = {}, vars = {}, fns = {}) => {
-    const [ fnName, args, opt ] = parseArgs(str, data, vars, fns);
+const evaluateExpression = (str = "", data = {}, state = {}, fns = {}) => {
+    const [fnName, args, options] = parseArgs(str, data, state, fns);
     if (typeof fns[fnName] === "function") {
-        return fns[fnName]({args, opt, options: opt, data, variables: vars});
+        return fns[fnName]({ args, options, data, state });
     }
     // if no function has been found with this name
     // throw new Error(`Unknown function '${fnName}'`);
@@ -96,14 +96,14 @@ const evaluateExpression = (str = "", data = {}, vars = {}, fns = {}) => {
 };
 
 // @description parse a string value to a native type
-const parse = (v, data = {}, vars = {}, fns = {}) => {
+const parse = (v, data = {}, state = {}, fns = {}) => {
     if (v.startsWith("(") && v.endsWith(")")) {
-        return evaluateExpression(v.slice(1, -1).trim(), data, vars, fns);
+        return evaluateExpression(v.slice(1, -1).trim(), data, state, fns);
     }
     if ((v.startsWith(`"`) && v.endsWith(`"`)) || /^-?\d+\.?\d*$/.test(v) || v === "true" || v === "false" || v === "null") {
         return JSON.parse(v);
     }
-    return (v || "").startsWith("@") ? get(vars, v.slice(1)) : get(data, v || ".");
+    return (v || "").startsWith("@") ? get(state, v.slice(1)) : get(data, v || ".");
 };
 
 // @description find the index of the closing token
@@ -122,6 +122,104 @@ const findClosingToken = (tokens, i, token) => {
     throw new Error(`Unmatched section end: {{${token}}}`);
 };
 
+// @description internal method to compile the template
+const compile = (ctx, tokens, output, data, state, index = 0, section = "") => {
+    let i = index;
+    while (i < tokens.length) {
+        if (i % 2 === 0) {
+            output.push(tokens[i]);
+        }
+        else if (tokens[i].startsWith("#") && typeof ctx.helpers[tokens[i].slice(1).trim().split(" ")[0]] === "function") {
+            const [t, args, opt] = parseArgs(tokens[i].slice(1), data, state);
+            const j = i + 1;
+            i = findClosingToken(tokens, j, t);
+            output.push(ctx.helpers[t]({
+                args: args,
+                options: opt,
+                tokens: tokens.slice(j, i),
+                data: data,
+                state: state,
+                fn: (blockData = {}, customBlockState = {}, blockOutput = []) => {
+                    const blockState = {
+                        ...state,
+                        ...customBlockState,
+                        helper: {
+                            name: t,
+                            options: opt || {},
+                            args: args || [],
+                            context: blockData,
+                        },
+                        parent: data,
+                        root: state.root,
+                    };
+                    compile(ctx, tokens, blockOutput, blockData, blockState, j, t);
+                    return blockOutput.join("");
+                },
+            }));
+        }
+        else if (tokens[i].startsWith("#") || tokens[i].startsWith("^")) {
+            const t = tokens[i].slice(1).trim();
+            const value = get(data, t);
+            const negate = tokens[i].startsWith("^");
+            if (!negate && value && Array.isArray(value)) {
+                const j = i + 1;
+                (value.length > 0 ? value : [""]).forEach(item => {
+                    i = compile(ctx, tokens, value.length > 0 ? output : [], item, state, j, t);
+                });
+            }
+            else {
+                const includeOutput = (!negate && !!value) || (negate && !!!value);
+                i = compile(ctx, tokens, includeOutput ? output : [], data, state, i + 1, t);
+            }
+        }
+        else if (tokens[i].startsWith(">")) {
+            const [t, args, opt] = parseArgs(tokens[i].replace(/^>{1,2}/, ""), data, state);
+            const blockContent = []; // to store partial block content
+            if (tokens[i].startsWith(">>")) {
+                i = compile(ctx, tokens, blockContent, data, state, i + 1, t);
+            }
+            if (typeof ctx.partials[t] === "string" || typeof ctx.partials[t]?.body === "string") {
+                const partialBody = ctx.partials[t]?.body || ctx.partials[t];
+                const partialData = args.length > 0 ? args[0] : (Object.keys(opt).length > 0 ? opt : data);
+                const partialState = {
+                    ...state,
+                    content: blockContent.join(""),
+                    partial: {
+                        name: t,
+                        attributes: ctx.partials[t]?.attributes || ctx.partials[t]?.data || {},
+                        args: args || [],
+                        options: opt || {},
+                        context: partialData,
+                    },
+                };
+                compile(ctx, tokenize(partialBody), output, partialData, partialState, 0, "");
+            }
+        }
+        else if (tokens[i].startsWith("=")) {
+            output.push(evaluateExpression(tokens[i].slice(1), data, state, ctx.functions) ?? "");
+        }
+        else if (tokens[i].startsWith("/")) {
+            if (tokens[i].slice(1).trim() !== section) {
+                throw new Error(`Unmatched section end: {{${tokens[i]}}}`);
+            }
+            break;
+        }
+        else {
+            const t = tokens[i].split("||").map(v => {
+                // check if the returned value should not be escaped
+                if (v.trim().startsWith("!")) {
+                    return parse(v.trim().slice(1).trim(), data, state);
+                }
+                // escape the returned value
+                return escape(parse(v.trim(), data, state));
+            });
+            output.push(t.find(v => !!v) ?? "");
+        }
+        i = i + 1;
+    }
+    return i;
+};
+
 // @description default helpers
 const defaultHelpers = {
     "each": p => {
@@ -146,140 +244,52 @@ const defaultHelpers = {
     "with": p => p.fn(p.args[0]),
     "escape": p => escape(p.fn(p.data)),
     "raw": p => untokenize(p.tokens),
+    "slot": params => {
+        if (typeof params.state.slot === "undefined") {
+            params.state.slot = {};
+        }
+        params.state.slot[params.args[0].trim()] = params.fn(params.data);
+        return "";
+    },
+    "macro": params => {
+        if (typeof params.state.macro === "undefined") {
+            params.state.macro = {};
+        }
+        params.state.macro[params.args[0].trim()] = untokenize(params.tokens).trim();
+        return "";
+    },
+    "call": params => {
+        const result = [];
+        const name = (params.args[0] || "").trim();
+        if (!!name && typeof params.state?.macro?.[name] === "string") {
+            compile(params.context, tokenize(params.state.macro[name]), result, params.options, {
+                ...params.state,
+                content: params.fn(params.data),
+            });
+        }
+        return result.join("");
+    },
 };
 
 // @description create a new instance of mikel
 const create = (options = {}) => {
-    const ctx = {
+    const ctx = Object.freeze({
         helpers: Object.assign({}, defaultHelpers, options?.helpers || {}),
         partials: Object.assign({}, options?.partials || {}),
-        functions: options?.functions || {},
-        variables: {},
-    };
-    // internal method to compile the template
-    const compile = (tokens, output, data, vars, index = 0, section = "") => {
-        let i = index;
-        while (i < tokens.length) {
-            if (i % 2 === 0) {
-                output.push(tokens[i]);
-            }
-            else if (tokens[i].startsWith("#") && typeof ctx.helpers[tokens[i].slice(1).trim().split(" ")[0]] === "function") {
-                const [t, args, opt] = parseArgs(tokens[i].slice(1), data, vars);
-                const j = i + 1;
-                i = findClosingToken(tokens, j, t);
-                output.push(ctx.helpers[t]({
-                    args: args,
-                    opt: opt, // deprecated
-                    options: opt,
-                    tokens: tokens.slice(j, i),
-                    data: data,
-                    variables: vars,
-                    fn: (blockData = {}, blockVars = {}, blockOutput = []) => {
-                        const helperVars = {
-                            ...vars,
-                            ...blockVars,
-                            helper: {
-                                name: t,
-                                options: opt || {},
-                                args: args || [],
-                                context: blockData,
-                            },
-                            parent: data,
-                            root: vars.root,
-                        };
-                        compile(tokens, blockOutput, blockData, helperVars, j, t);
-                        return blockOutput.join("");
-                    },
-                }));
-            }
-            else if (tokens[i].startsWith("#") || tokens[i].startsWith("^")) {
-                const t = tokens[i].slice(1).trim();
-                const value = get(data, t);
-                const negate = tokens[i].startsWith("^");
-                if (!negate && value && Array.isArray(value)) {
-                    const j = i + 1;
-                    (value.length > 0 ? value : [""]).forEach(item => {
-                        i = compile(tokens, value.length > 0 ? output : [], item, vars, j, t);
-                    });
-                }
-                else {
-                    const includeOutput = (!negate && !!value) || (negate && !!!value);
-                    i = compile(tokens, includeOutput ? output : [], data, vars, i + 1, t);
-                }
-            }
-            else if (tokens[i].startsWith(">*")) {
-                const t = tokens[i].slice(2).trim(), partialTokens = tokens.slice(i + 1);
-                const lastIndex = partialTokens.findIndex((token, j) => {
-                    return j % 2 !== 0 && token.trim().startsWith("/") && token.trim().endsWith(t);
-                });
-                if (typeof ctx.partials[t] === "undefined") {
-                    ctx.partials[t] = untokenize(partialTokens.slice(0, lastIndex));
-                }
-                i = i + lastIndex + 1;
-            }
-            else if (tokens[i].startsWith(">")) {
-                const [t, args, opt] = parseArgs(tokens[i].replace(/^>{1,2}/, ""), data, vars);
-                const blockContent = []; // to store partial block content
-                if (tokens[i].startsWith(">>")) {
-                    i = compile(tokens, blockContent, data, vars, i + 1, t);
-                }
-                if (typeof ctx.partials[t] === "string" || typeof ctx.partials[t]?.body === "string") {
-                    const newData = args.length > 0 ? args[0] : (Object.keys(opt).length > 0 ? opt : data);
-                    const newVars = {
-                        ...vars,
-                        content: blockContent.join(""),
-                        partial: {
-                            name: t,
-                            attributes: ctx.partials[t]?.attributes || ctx.partials[t]?.data || {},
-                            args: args || [],
-                            options: opt || {},
-                            context: newData,
-                        },
-                    };
-                    compile(tokenize(ctx.partials[t]?.body || ctx.partials[t]), output, newData, newVars, 0, "");
-                }
-            }
-            else if (tokens[i].startsWith("=")) {
-                output.push(evaluateExpression(tokens[i].slice(1), data, vars, ctx.functions) ?? "");
-            }
-            else if (tokens[i].startsWith("/")) {
-                if (tokens[i].slice(1).trim() !== section) {
-                    throw new Error(`Unmatched section end: {{${tokens[i]}}}`);
-                }
-                break;
-            }
-            else {
-                const t = tokens[i].split("||").map(v => {
-                    // check if the returned value should not be escaped
-                    if (v.trim().startsWith("!")) {
-                        return parse(v.trim().slice(1).trim(), data, vars);
-                    }
-                    // escape the returned value
-                    return escape(parse(v.trim(), data, vars));
-                });
-                output.push(t.find(v => !!v) ?? "");
-            }
-            i = i + 1;
-        }
-        return i;
-    };
+        functions: Object.assign({}, options?.functions || {}),
+        initialState: {}, // Object.assign({}, options?.initialState || {}),
+    });
     // entry method to compile the template with the provided data object
     const compileTemplate = (template, data = {}, output = []) => {
-        compile(tokenize(template), output, data, {root: data, ...ctx.variables}, 0, "");
+        compile(ctx, tokenize(template), output, data, { ...ctx.initialState, root: data }, 0, "");
         return output.join("");
     };
     // assign api methods and return method to compile the template
     return Object.assign(compileTemplate, {
-        use: newOptions => {
-            if (typeof newOptions === "function") {
-                newOptions(ctx);
-            }
-            else if (!!newOptions && typeof newOptions === "object") {
-                ["helpers", "functions", "partials", "variables"].forEach(field => {
-                    Object.assign(ctx[field], newOptions?.[field] || {});
-                });
-            }
-            return compileTemplate;
+        use: (newOptions = {}) => {
+            ["helpers", "functions", "partials", "initialState"].forEach(field => {
+                Object.assign(ctx[field], newOptions?.[field] || {});
+            });
         },
         addHelper: (name, fn) => ctx.helpers[name] = fn,
         removeHelper: name => delete ctx.helpers[name],

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "mikel",
     "description": "Micro templating library with zero dependencies",
-    "version": "0.32.0",
+    "version": "0.33.0",
     "type": "module",
     "author": {
         "name": "Josemi Juanes",