miki-template 2.0.0 → 2.2.2

package/docs/guide/custom-filters.md

@@ -0,0 +1,311 @@
+# Custom Filters
+
+Add your own filters to transform values in templates. miki-template's filter API mirrors Django's — filters are simply functions that receive a value and optional argument, and return the transformed value.
+
+## Table of Contents
+
+- [Register a Simple Filter](#register-a-simple-filter)
+- [Filters with Arguments](#filters-with-arguments)
+- [Multiple Arguments](#multiple-arguments)
+- [Context-Aware Filters](#context-aware-filters)
+- [SafeString Filters](#safestring-filters)
+- [Async Filters](#async-filters)
+- [Filter Registration Best Practices](#filter-registration-best-practices)
+- [Chaining Custom Filters](#chaining-custom-filters)
+
+---
+
+## Register a Simple Filter
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerFilter } = require('miki-template');
+
+    registerFilter('reverse', (val) => {
+      return String(val).split('').reverse().join('');
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerFilter } from 'miki-template';
+
+    registerFilter('reverse', (val) => {
+      return String(val).split('').reverse().join('');
+    });
+    ```
+
+Use it in templates:
+
+```html
+{{ name|reverse }}
+```
+
+## Filters with Arguments
+
+Filters can accept arguments after a colon:
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerFilter } = require('miki-template');
+
+    registerFilter('multiply', (val, factor) => {
+      return Number(val) * Number(factor);
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerFilter } from 'miki-template';
+
+    registerFilter('multiply', (val, factor) => {
+      return Number(val) * Number(factor);
+    });
+    ```
+
+Usage:
+
+```html
+{{ price|multiply:1.2 }}
+```
+
+## Multiple Arguments
+
+Pass multiple arguments separated by commas:
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerFilter } = require('miki-template');
+
+    registerFilter('format', (val, prefix, suffix) => {
+      return `${prefix}${val}${suffix}`;
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerFilter } from 'miki-template';
+
+    registerFilter('format', (val, prefix, suffix) => {
+      return `${prefix}${val}${suffix}`;
+    });
+    ```
+
+Usage:
+
+```html
+{{ name|format:"<b>","</b>" }}
+<!-- → "<b>Alice</b>" -->
+```
+
+### Real-World Example: Dynamic Currency Filter
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerFilter, markSafe } = require('miki-template');
+
+    registerFilter('currency_dynamic', (val, code, locale = 'en-US') => {
+      const num = Number(val);
+      if (isNaN(num)) return '';
+      return new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency: code
+      }).format(num);
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerFilter } from 'miki-template';
+
+    registerFilter('currency_dynamic', (val, code, locale = 'en-US') => {
+      const num = Number(val);
+      if (isNaN(num)) return '';
+      return new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency: code
+      }).format(num);
+    });
+    ```
+
+Template usage:
+
+```html
+<!-- €1,234.56 -->
+{{ 1234.5|currency_dynamic:"EUR", "de-DE" }}
+
+<!-- $1,234.56 -->
+{{ 1234.5|currency_dynamic:"USD" }}
+```
+
+## Context-Aware Filters
+
+Filters receive the rendering `context` as the third argument, enabling context-aware transformations:
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerFilter } = require('miki-template');
+
+    registerFilter('currency', (val, symbol, ctx) => {
+      const num = Number(val);
+      if (isNaN(num)) return '';
+      const sym = symbol || ctx.currencySymbol || '$';
+      return sym + num.toFixed(2);
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerFilter } from 'miki-template';
+
+    registerFilter('currency', (val, symbol, ctx) => {
+      const num = Number(val);
+      if (isNaN(num)) return '';
+      const sym = symbol || ctx.currencySymbol || '$';
+      return sym + num.toFixed(2);
+    });
+    ```
+
+Usage:
+
+```html
+{{ price|currency:"€" }}
+<!-- The filter can also read ctx.currencySymbol for a default -->
+```
+
+**Real-world locale-aware formatter:**
+
+```javascript
+registerFilter('datetime', (val, format, ctx) => {
+  const locale = ctx.locale || 'en-US';
+  const d = new Date(val);
+  return new Intl.DateTimeFormat(locale, {
+    dateStyle: format === 'short' ? 'short' : 'full',
+    timeStyle: format === 'short' ? 'short' : undefined
+  }).format(d);
+});
+```
+
+```html
+{{ post.created_at|datetime:"full" }}
+```
+
+## SafeString Filters
+
+Filters can return `SafeString` to prevent escaping — useful when generating HTML:
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerFilter, markSafe } = require('miki-template');
+
+    registerFilter('badge', (val) => {
+      const color = val === 'active' ? 'green' : 'gray';
+      return markSafe(`<span class="badge badge-${color}">${val}</span>`);
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerFilter, markSafe } from 'miki-template';
+
+    registerFilter('badge', (val) => {
+      const color = val === 'active' ? 'green' : 'gray';
+      return markSafe(`<span class="badge badge-${color}">${val}</span>`);
+    });
+    ```
+
+Usage:
+
+```html
+{{ user.status|badge }}
+```
+
+## Async Filters
+
+Filters can be async by returning a Promise. Use `asyncRender()` to render templates with async filters:
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerFilter } = require('miki-template');
+
+    registerFilter('fetch_user', async (val) => {
+      const res = await fetch(`https://api.example.com/users/${val}`);
+      const data = await res.json();
+      return data.display_name;
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerFilter } from 'miki-template';
+
+    registerFilter('fetch_user', async (val) => {
+      const res = await fetch(`https://api.example.com/users/${val}`);
+      const data = await res.json();
+      return data.display_name;
+    });
+    ```
+
+Usage:
+
+=== "CommonJS (asyncRender)"
+
+    ```javascript
+    const { asyncRender } = require('miki-template');
+
+    const html = await asyncRender('Author: {{ user.id|fetch_user }}', { user: { id: 42 } });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { asyncRender } from 'miki-template';
+
+    const html = await asyncRender('Author: {{ user.id|fetch_user }}', { user: { id: 42 } });
+    ```
+
+> **Note:** Async filters only work with `asyncRender()` or `compiled.asyncRender()`. Using them with `render()` or `compiled.render()` will throw.
+
+## Filter Registration Best Practices
+
+1. **Handle null/undefined gracefully** — Return empty string or a fallback value.
+2. **Return strings** — Filters should generally return string representations for template output.
+3. **Don't mutate the input** — Treat values as immutable.
+4. **Use `markSafe()` for HTML output** — Prevent auto-escaping when returning HTML.
+5. **Validate arguments** — Coerce numeric arguments with `Number()` and handle `NaN`.
+
+## Chaining Custom Filters
+
+Custom filters chain the same way as built-in filters:
+
+```html
+{{ text|trim|highlight:"important"|safe }}
+```
+
+```javascript
+registerFilter('trim', (val) => String(val || '').trim());
+registerFilter('highlight', (val, term) => {
+  const re = new RegExp(`(${term})`, 'gi');
+  return markSafe(String(val).replace(re, '<mark>$1</mark>'));
+});
+```
+
+## Next Steps
+
+- [Custom Tags](./custom-tags)
+- [Advanced Usage](./advanced-usage)
+- [API Reference: Filters](../api/filters)

package/docs/guide/custom-tags.md

@@ -0,0 +1,271 @@
+# Custom Tags
+
+Create your own template tags by registering a parser function. miki-template's tag API mirrors Django's — a tag is a parser that returns a Node object with a `render(context)` method.
+
+## Table of Contents
+
+- [Register a Simple Tag](#register-a-simple-tag)
+- [Async Custom Tags](#async-custom-tags)
+- [Parsing Complex Tags](#parsing-complex-tags)
+- [Accessing the Parser](#accessing-the-parser)
+- [Tag Registration Best Practices](#tag-registration-best-practices)
+
+---
+
+## Register a Simple Tag
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerTag } = require('miki-template');
+
+    registerTag('hello', (tagContent, parser) => {
+      return {
+        render: (context) => 'Hello World!'
+      };
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerTag } from 'miki-template';
+
+    registerTag('hello', (tagContent, parser) => {
+      return {
+        render: (context) => 'Hello World!'
+      };
+    });
+    ```
+
+Usage in templates:
+
+```html
+{% hello %}
+```
+
+### Passing Arguments
+
+```javascript
+registerTag('greet', (tagContent, parser) => {
+  // tagContent is the full text after the tag name: "user.name"
+  const varName = tagContent.trim();
+  return {
+    render: (context) => {
+      const value = context.get(varName);
+      return `Hello, ${value}!`;
+    }
+  };
+});
+```
+
+```html
+{% greet user.name %}
+```
+
+## Returning a Node Class
+
+For more complex tags, return a Node class instance:
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerTag } = require('miki-template');
+
+    class GreetNode {
+      constructor(varName) {
+        this.varName = varName;
+      }
+      render(context) {
+        const value = context.get(this.varName);
+        return `Hello, ${value || 'Guest'}!`;
+      }
+    }
+
+    registerTag('greet', (tagContent, parser) => {
+      const varName = tagContent.trim();
+      return new GreetNode(varName);
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerTag } from 'miki-template';
+
+    class GreetNode {
+      constructor(varName) {
+        this.varName = varName;
+      }
+      render(context) {
+        const value = context.get(this.varName);
+        return `Hello, ${value || 'Guest'}!`;
+      }
+    }
+
+    registerTag('greet', (tagContent, parser) => {
+      const varName = tagContent.trim();
+      return new GreetNode(varName);
+    });
+    ```
+
+## Async Custom Tags
+
+If your `render()` method returns a Promise, the template must be rendered with `asyncRender()`:
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerTag, asyncRender } = require('miki-template');
+
+    registerTag('fetch_greeting', (tagContent, parser) => {
+      const urlVar = tagContent.trim();
+      return {
+        async render(context) {
+          const url = context.get(urlVar);
+          const res = await fetch(url);
+          const data = await res.json();
+          return data.message;
+        }
+      };
+    });
+
+    // Must use asyncRender
+    const html = await asyncRender('{% fetch_greeting api_url %}', { api_url: 'https://...' });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerTag, asyncRender } from 'miki-template';
+
+    registerTag('fetch_greeting', (tagContent, parser) => {
+      const urlVar = tagContent.trim();
+      return {
+        async render(context) {
+          const url = context.get(urlVar);
+          const res = await fetch(url);
+          const data = await res.json();
+          return data.message;
+        }
+      };
+    });
+
+    const html = await asyncRender('{% fetch_greeting api_url %}', { api_url: 'https://...' });
+    ```
+
+## Parsing Complex Tags
+
+Use the `parser` object to consume tokens and build multi-part tags:
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerTag } = require('miki-template');
+
+    registerTag('panel', (tagContent, parser) => {
+      const classes = tagContent.trim() || '';
+      const nodelist = parser.parse(['endpanel']);
+      parser.skipTag(); // consume endpanel
+
+      return {
+        render: (context) => {
+          const body = nodelist.map(n => n.render(context)).join('');
+          return `<div class="panel ${classes}">${body}</div>`;
+        }
+      };
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerTag } from 'miki-template';
+
+    registerTag('panel', (tagContent, parser) => {
+      const classes = tagContent.trim() || '';
+      const nodelist = parser.parse(['endpanel']);
+      parser.skipTag();
+
+      return {
+        render: (context) => {
+          const body = nodelist.map(n => n.render(context)).join('');
+          return `<div class="panel ${classes}">${body}</div>`;
+        }
+      };
+    });
+    ```
+
+Usage with nested content:
+
+```html
+{% panel "card" %}
+  <h2>{{ title }}</h2>
+  <p>{{ description }}</p>
+{% endpanel %}
+```
+
+### Real-World Example: Cache Tag
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerTag } = require('miki-template');
+
+    registerTag('cache_block', (tagContent, parser) => {
+      const [key, ...rest] = tagContent.trim().split(/\s+/);
+      const nodelist = parser.parse(['endcache_block']);
+      parser.skipTag();
+
+      return {
+        render: (context) => {
+          const cacheKey = key;
+          const cache = context.get('cache') || global.__cache__;
+          if (!cache) return nodelist.map(n => n.render(context)).join('');
+          if (cache.has(cacheKey)) return cache.get(cacheKey);
+          const output = nodelist.map(n => n.render(context)).join('');
+          cache.set(cacheKey, output, rest[0] || 300);
+          return output;
+        }
+      };
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerTag } from 'miki-template';
+
+    registerTag('cache_block', (tagContent, parser) => {
+      const [key, ...rest] = tagContent.trim().split(/\s+/);
+      const nodelist = parser.parse(['endcache_block']);
+      parser.skipTag();
+
+      return {
+        render: (context) => {
+          const cacheKey = key;
+          const cache = context.get('cache') || global.__cache__;
+          if (!cache) return nodelist.map(n => n.render(context)).join('');
+          if (cache.has(cacheKey)) return cache.get(cacheKey);
+          const output = nodelist.map(n => n.render(context)).join('');
+          cache.set(cacheKey, output, rest[0] || 300);
+          return output;
+        }
+      };
+    });
+    ```
+
+## Tag Registration Best Practices
+
+1. **Return objects with `render(context)`** — the render signature must accept a context object.
+2. **Use `parser.parse([...terminators])`** for tags with bodies — this lets the parser consume nested content correctly.
+3. **Always call `parser.skipTag()`** after `parser.parse` to consume the end tag.
+4. **Handle whitespace** — `tagContent.trim()` for single-argument tags.
+5. **Async tags need asyncRender** — return a Promise from `render()` and use `asyncRender()` to render.
+6. **Access context values** — use `context.get('key')` or `context.resolve('expr')`.
+
+## Next Steps
+
+- [Built-in Tags Reference](../api/tags)
+- [Custom Filters](./custom-filters)
+- [Guide: Tags](./tags)