miki-template 2.0.1 → 2.2.3

package/docs/guide/context-processors.md

@@ -0,0 +1,257 @@
+# Context Processors
+
+Context processors are functions that automatically inject variables into every template render. This follows Django's context processor pattern — ideal for injecting global settings, user data, or feature flags.
+
+## Table of Contents
+
+- [How Context Processors Work](#how-context-processors-work)
+- [Register a Context Processor](#register-a-context-processor)
+- [Context Processor Signature](#context-processor-signature)
+- [Overriding Behavior](#overriding-behavior)
+- [Real-World Examples](#real-world-examples)
+- [Clearing Processors](#clearing-processors)
+
+---
+
+## How Context Processors Work
+
+Context processors run on **every render** (both `render()` and `compile().render()`). They return an object of key/value pairs that are merged into the rendering context **before** your template's local context is applied.
+
+```mermaid
+graph LR
+A[Your Context] --> B[Apply Processors]
+B --> C[Processor adds global vars]
+C --> D[Your Context wins]
+D --> E[Template renders]
+```
+
+**Key behavior:** Your explicit context values **always win** over processor values. This means you can override global defaults per-render without fighting the processor.
+
+## Register a Context Processor
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerContextProcessor } = require('miki-template');
+
+    registerContextProcessor((context) => {
+      return {
+        siteName: 'My App',
+        currentYear: new Date().getFullYear(),
+        debug: process.env.NODE_ENV !== 'production'
+      };
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerContextProcessor } from 'miki-template';
+
+    registerContextProcessor((context) => {
+      return {
+        siteName: 'My App',
+        currentYear: new Date().getFullYear(),
+        debug: process.env.NODE_ENV !== 'production'
+      };
+    });
+    ```
+
+### Multiple Processors
+
+You can register multiple processors. They run in order — later processors can overwrite earlier ones:
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerContextProcessor } = require('miki-template');
+
+    registerContextProcessor(() => ({ siteName: 'My App' }));
+    registerContextProcessor(() => ({ version: '2.0.0' }));
+    registerContextProcessor(() => ({
+      footerText: '© 2024 My App. All rights reserved.'
+    }));
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerContextProcessor } from 'miki-template';
+
+    registerContextProcessor(() => ({ siteName: 'My App' }));
+    registerContextProcessor(() => ({ version: '2.0.0' }));
+    registerContextProcessor(() => ({
+      footerText: '© 2024 My App. All rights reserved.'
+    }));
+    ```
+
+## Context Processor Signature
+
+The processor function receives the rendering `context` as an argument and must return a plain object:
+
+```javascript
+registerContextProcessor((context) => {
+  // context is the full Context object — you can inspect contextObj
+  // but don't mutate it
+  return {
+    key: 'value'
+  };
+});
+```
+
+**Important:** If a processor returns `null`, `undefined`, or nothing, it's treated as returning an empty object `{}`. Processors must **not** return a Promise — if you need async data, compute it before rendering and pass it as context.
+
+## Overriding Behavior
+
+Since your explicit context always wins, you can override global defaults per-render:
+
+=== "CommonJS"
+
+    ```javascript
+    const { render } = require('miki-template');
+
+    // processor sets debug: false
+    // but this render overrides it:
+    render(template, { debug: true });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { render } from 'miki-template';
+
+    render(template, { debug: true });
+    ```
+
+## Real-World Examples
+
+### App-wide Settings
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerContextProcessor } = require('miki-template');
+
+    registerContextProcessor(() => ({
+      appName: process.env.APP_NAME || 'MyApp',
+      appVersion: require('./package.json').version,
+      environment: process.env.NODE_ENV || 'development',
+      apiUrl: process.env.API_URL || 'http://localhost:3000/api',
+      assetsUrl: process.env.ASSETS_URL || '/assets'
+    }));
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerContextProcessor } from 'miki-template';
+    import pkg from './package.json' with { type: 'json' };
+
+    registerContextProcessor(() => ({
+      appName: process.env.APP_NAME || 'MyApp',
+      appVersion: pkg.version,
+      environment: process.env.NODE_ENV || 'development',
+      apiUrl: process.env.API_URL || 'http://localhost:3000/api',
+      assetsUrl: process.env.ASSETS_URL || '/assets'
+    }));
+    ```
+
+### User Authentication
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerContextProcessor } = require('miki-template');
+
+    registerContextProcessor((context) => {
+      const user = context.get('user');
+      if (!user) return {};
+      return {
+        user_name: user.name,
+        user_avatar: user.avatar || '/default-avatar.png',
+        user_is_admin: user.isAdmin || false
+      };
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerContextProcessor } from 'miki-template';
+
+    registerContextProcessor((context) => {
+      const user = context.get('user');
+      if (!user) return {};
+      return {
+        user_name: user.name,
+        user_avatar: user.avatar || '/default-avatar.png',
+        user_is_admin: user.isAdmin || false
+      };
+    });
+    ```
+
+### Feature Flags
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerContextProcessor } = require('miki-template');
+
+    registerContextProcessor(() => ({
+      flags: {
+        newDashboard: process.env.FEATURE_NEW_DASHBOARD === 'true',
+        betaFeature: process.env.FEATURE_BETA === 'true',
+        darkModeDefault: process.env.FEATURE_DARK_MODE === 'true'
+      }
+    }));
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerContextProcessor } from 'miki-template';
+
+    registerContextProcessor(() => ({
+      flags: {
+        newDashboard: process.env.FEATURE_NEW_DASHBOARD === 'true',
+        betaFeature: process.env.FEATURE_BETA === 'true',
+        darkModeDefault: process.env.FEATURE_DARK_MODE === 'true'
+      }
+    }));
+    ```
+
+Template usage:
+
+```html
+{% if flags.newDashboard %}
+  <a href="/new-dashboard">New Dashboard</a>
+{% else %}
+  <a href="/dashboard">Classic Dashboard</a>
+{% endif %}
+```
+
+## Clearing Processors
+
+Clear all registered processors (useful in tests or dynamic configuration):
+
+=== "CommonJS"
+
+    ```javascript
+    const { clearContextProcessors } = require('miki-template');
+
+    clearContextProcessors();
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { clearContextProcessors } from 'miki-template';
+
+    clearContextProcessors();
+    ```
+
+## Next Steps
+
+- [Advanced Usage: Context Processors](./advanced-usage)
+- [Async Rendering](./async-rendering)
+- [API Reference: Context Processors](../api/context-processors)

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)