miki-template 2.0.0 → 2.2.2

package/docs/api/libraries.md

@@ -0,0 +1,207 @@
+# Libraries API
+
+## registerLibrary
+
+Register a library — a named bundle of filters, tags, and helpers.
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerLibrary } = require('miki-template');
+
+    registerLibrary('mylib', {
+      filters: {
+        shout: (val) => String(val).toUpperCase() + '!'
+      },
+      tags: {
+        hello: (tagContent, parser) => ({
+          render: (context) => 'Hello!'
+        })
+      },
+      helpers: {
+        bold: (inner, context) => `<b>${inner}</b>`
+      }
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerLibrary } from 'miki-template';
+
+    registerLibrary('mylib', {
+      filters: {
+        shout: (val) => String(val).toUpperCase() + '!'
+      },
+      tags: {
+        hello: (tagContent, parser) => ({
+          render: (context) => 'Hello!'
+        })
+      },
+      helpers: {
+        bold: (inner, context) => `<b>${inner}</b>`
+      }
+    });
+    ```
+
+## activateLibrary
+
+Activate a library so its filters and tags become available.
+
+=== "CommonJS"
+
+    ```javascript
+    const { activateLibrary } = require('miki-template');
+
+    activateLibrary('mylib');
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { activateLibrary } from 'miki-template';
+
+    activateLibrary('mylib');
+    ```
+
+Built-in libraries (`humanize`, `cache`, `lorem`, `markdown`, `i18n`) are auto-activated on import.
+
+## unregisterLibrary
+
+=== "CommonJS"
+
+    ```javascript
+    const { unregisterLibrary } = require('miki-template');
+
+    // Unregister specific library
+    unregisterLibrary('mylib');
+
+    // Unregister all libraries
+    unregisterLibrary();
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { unregisterLibrary } from 'miki-template';
+
+    unregisterLibrary('mylib');
+    ```
+
+## hasLibrary
+
+=== "CommonJS"
+
+    ```javascript
+    const { hasLibrary } = require('miki-template');
+
+    if (hasLibrary('humanize')) {
+      // library is registered
+    }
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { hasLibrary } from 'miki-template';
+
+    if (hasLibrary('humanize')) {
+      // library is registered
+    }
+    ```
+
+## getLibrary
+
+Retrieve a library by name.
+
+=== "CommonJS"
+
+    ```javascript
+    const { getLibrary } = require('miki-template');
+
+    const lib = getLibrary('humanize');
+    console.log(Object.keys(lib.filters));
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { getLibrary } from 'miki-template';
+
+    const lib = getLibrary('humanize');
+    ```
+
+## getLibraryNames
+
+=== "CommonJS"
+
+    ```javascript
+    const { getLibraryNames } = require('miki-template');
+
+    console.log(getLibraryNames());
+    // ['humanize', 'cache', 'lorem']
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { getLibraryNames } from 'miki-template';
+
+    console.log(getLibraryNames());
+    ```
+
+## registerLibraryFromPath
+
+Load a library from a JavaScript file on disk. The file must export `{ tags, filters, helpers }`.
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerLibraryFromPath } = require('miki-template');
+
+    registerLibraryFromPath('mylib', './libs/mylib.js');
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerLibraryFromPath } from 'miki-template';
+
+    await registerLibraryFromPath('mylib', './libs/mylib.mjs');
+    ```
+
+## Built-in Libraries
+
+### humanize
+
+Provides natural formatting filters: `intcomma`, `intword`, `ordinal`, `naturalday`, `naturaltime`.
+
+| Filter | Description |
+|--------|-------------|
+| `intcomma` | `1234567` → `1,234,567` |
+| `intword` | `1234567` → `1.2M` |
+| `ordinal` | `1` → `1st`, `2` → `2nd` |
+| `naturalday` | Format dates as "today", "yesterday" |
+| `naturaltime` | Format times as "just now", "2 hours ago" |
+| `ordinal` | Convert numbers to ordinal (1st, 2nd, 3rd) |
+
+### cache
+
+Provides `{% cache timeout key %}...{% endcache %}` tag for caching template fragments.
+
+### lorem
+
+Provides `{% lorem count random_words %}` tag and `lorem` filter for placeholder text.
+
+### markdown
+
+Provides `markdown` filter for Markdown→HTML conversion.
+
+### i18n
+
+Provides `{% trans %}`, `{% blocktrans %}`, `{% language %}` tags and translation functions.
+
+## Next Steps
+
+- [Advanced Usage: Libraries](../guide/advanced-usage#library-system)
+- [API Reference](../)

package/docs/api/render-partial.md

@@ -0,0 +1,81 @@
+# renderPartialFromFile / renderPartialFromSource
+
+Render a named partial from a template file or source string.
+
+## renderPartialFromFile
+
+Render a named partial from a template file.
+
+```javascript
+renderPartialFromFile(fileName, partialName, contextObj, options)
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fileName` | `string` | Template file name (without extension) |
+| `partialName` | `string` | Name of the partial to render |
+| `contextObj` | `object` | Variables to inject |
+| `options` | `object` | Options including `views` directories |
+
+### Example
+
+=== "CommonJS"
+
+    ```javascript
+    const { renderPartialFromFile } = require('miki-template');
+
+    const html = renderPartialFromFile('home', 'card', { title: 'Hello' }, { views: './views' });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { renderPartialFromFile } from 'miki-template';
+
+    const html = renderPartialFromFile('home', 'card', { title: 'Hello' }, { views: './views' });
+    ```
+
+## renderPartialFromSource
+
+Render a named partial from a template source string.
+
+```javascript
+renderPartialFromSource(fileContent, partialName, contextObj, options, filePath?)
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fileContent` | `string` | Template source string |
+| `partialName` | `string` | Name of the partial to render |
+| `contextObj` | `object` | Variables to inject |
+| `options` | `object` | Options |
+| `filePath` | `string?` | Optional file path for error messages |
+
+### Example
+
+=== "CommonJS"
+
+    ```javascript
+    const { renderPartialFromSource } = require('miki-template');
+
+    const source = `{% partialdef card %}<div>{{ title }}</div>{% endpartialdef %}`;
+    const html = renderPartialFromSource(source, 'card', { title: 'Hello' });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { renderPartialFromSource } from 'miki-template';
+
+    const source = `{% partialdef card %}<div>{{ title }}</div>{% endpartialdef %}`;
+    const html = renderPartialFromSource(source, 'card', { title: 'Hello' });
+    ```
+
+## Related
+
+- [render()](./render)
+- [compile()](./compile)

package/docs/api/render.md

@@ -0,0 +1,92 @@
+# render()
+
+Render a template string or file partial.
+
+## Signature
+
+```javascript
+render(templateStr, contextObj = {}, options = {})
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `templateStr` | `string` | Template string or file path with `#partial` suffix |
+| `contextObj` | `object` | Variables to inject into the template |
+| `options` | `object` | Options including `views` directories and custom settings |
+
+## Returns
+
+`string` — The rendered HTML.
+
+## Examples
+
+### Render a template string
+
+=== "CommonJS"
+
+    ```javascript
+    const { render } = require('miki-template');
+
+    const html = render('Hello {{ name }}!', { name: 'World' });
+    // Output: Hello World!
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { render } from 'miki-template';
+
+    const html = render('Hello {{ name }}!', { name: 'World' });
+    // Output: Hello World!
+    ```
+
+### Render a partial from file
+
+=== "CommonJS"
+
+    ```javascript
+    const { render } = require('miki-template');
+
+    const html = render('home#card', { title: 'Hello' }, { views: './views' });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { render } from 'miki-template';
+
+    const html = render('home#card', { title: 'Hello' }, { views: './views' });
+    ```
+
+### Render with options
+
+=== "CommonJS"
+
+    ```javascript
+    const { render } = require('miki-template');
+
+    const html = render(template, context, {
+      views: ['./views', './app/templates'],
+      staticUrl: '/static',
+      urlHelper: (name, ...args) => '/' + name + '/' + args.join('/')
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { render } from 'miki-template';
+
+    const html = render(template, context, {
+      views: ['./views', './app/templates'],
+      staticUrl: '/static',
+      urlHelper: (name, ...args) => '/' + name + '/' + args.join('/')
+    });
+    ```
+
+## Related
+
+- [compile()](./compile)
+- [asyncRender()](./async-render)

package/docs/api/security.md

@@ -0,0 +1,145 @@
+# Security API
+
+## markSafe
+
+Mark a string as safe (bypass auto-escaping).
+
+=== "CommonJS"
+
+    ```javascript
+    const { markSafe } = require('miki-template');
+
+    const html = markSafe('<b>ok</b>');
+    // Will not be escaped
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { markSafe } from 'miki-template';
+
+    const html = markSafe('<b>ok</b>');
+    ```
+
+## isSafe
+
+Check if a value is marked safe.
+
+=== "CommonJS"
+
+    ```javascript
+    const { isSafe } = require('miki-template');
+
+    if (isSafe(value)) {
+      // value is marked safe
+    }
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { isSafe } from 'miki-template';
+
+    if (isSafe(value)) {
+      // value is marked safe
+    }
+    ```
+
+## escapeHtml
+
+Escape HTML special characters (`&`, `<`, `>`, `"`, `'`, `` ` ``).
+
+=== "CommonJS"
+
+    ```javascript
+    const { escapeHtml } = require('miki-template');
+
+    const escaped = escapeHtml('<script>');
+    // Output: &lt;script&gt;
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { escapeHtml } from 'miki-template';
+
+    const escaped = escapeHtml('<script>');
+    ```
+
+### Force-Escape SafeString
+
+Pass `true` as the second argument to force-escape a `SafeString` (matching Django's `|escape` filter behavior):
+
+=== "CommonJS"
+
+    ```javascript
+    const { escapeHtml, SafeString } = require('miki-template');
+
+    const safe = new SafeString('<b>bold</b>');
+    const forced = escapeHtml(safe, true);
+    // Output: &lt;b&gt;bold&lt;/b&gt;
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { escapeHtml, SafeString } from 'miki-template';
+
+    const safe = new SafeString('<b>bold</b>');
+    const forced = escapeHtml(safe, true);
+    ```
+
+## stripExpressContext
+
+Strip Express-specific framework keys (`_`, `settings`, `cache`) from a context object.
+
+=== "CommonJS"
+
+    ```javascript
+    const { stripExpressContext } = require('miki-template');
+
+    const cleanCtx = stripExpressContext(expressOptions);
+    // Removes: _locals, settings, cache, and other _ prefixed keys
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { stripExpressContext } from 'miki-template';
+
+    const cleanCtx = stripExpressContext(expressOptions);
+    ```
+
+## SafeString Class
+
+Create a SafeString instance directly.
+
+=== "CommonJS"
+
+    ```javascript
+    const { SafeString } = require('miki-template');
+
+    const safe = new SafeString('<b>ok</b>');
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { SafeString } from 'miki-template';
+
+    const safe = new SafeString('<b>ok</b>');
+    ```
+
+## Path Traversal Protection
+
+The `extends` and `include` tags validate that resolved template paths stay within configured views directories. Attempting to traverse outside throws an error:
+
+```html
+{% extends "../../etc/passwd" %}  <!-- throws -->
+{% include "../../secrets" %}     <!-- throws -->
+```
+
+## Next Steps
+
+- [Security Guide](../guide/security)
+- [API Reference](../)

package/docs/api/setup-express.md

@@ -0,0 +1,76 @@
+# setupExpress()
+
+One-line Express integration that wires the view engine, views directory, and partial responses.
+
+## Signature
+
+```javascript
+setupExpress(app, options = {})
+```
+
+## Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `extension` | `string` | View file extension, default `'html'` |
+| `views` | `string\|string[]` | Views directory path(s) |
+| `async` | `boolean` | Use async engine (`__expressAsync`) for Express 5+ |
+
+## What It Does
+
+- Calls `app.engine()` with the miki view engine.
+- Sets `app.set('view engine', extension)` if not already set.
+- Sets `app.set('views', views)` if `options.views` is provided.
+- Expands `views` to include nested template directories (app-style `templates/` folders).
+- Patches `res.render` to support `view#partial` syntax for HTMX responses.
+
+## Example
+
+=== "CommonJS"
+
+    ```javascript
+    const express = require('express');
+    const miki = require('miki-template');
+
+    const app = express();
+    miki.setupExpress(app, { extension: 'html', views: './views' });
+
+    app.get('/', (req, res) => res.render('home', { user: req.user }));
+    app.get('/card/:id', (req, res) =>
+      res.render(`home#card`, { title: 'Hello' })
+    );
+
+    app.listen(3000);
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import express from 'express';
+    import miki from 'miki-template';
+
+    const app = express();
+    miki.setupExpress(app, { extension: 'html', views: './views' });
+
+    app.get('/', (req, res) => res.render('home', { user: req.user }));
+    app.get('/card/:id', (req, res) =>
+      res.render(`home#card`, { title: 'Hello' })
+    );
+
+    app.listen(3000);
+    ```
+
+## Partial Responses
+
+`setupExpress()` patches `res.render` so that any view name containing `#` renders only the named partial:
+
+```javascript
+// Renders only the "card" partialdef from home.html
+res.render('home#card', { title: 'Hello' });
+```
+
+This is ideal for HTMX where you only need to update a portion of the page.
+
+## Related
+
+- [Integrations: Express](../integrations/express)