miki-template 2.0.1 → 2.2.2

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)

package/docs/api/tags.md

@@ -0,0 +1,134 @@
+# Tags API
+
+## registerTag
+
+Register a custom tag callable from templates as `{% tag_name content %}...{% endtag_name %}`.
+
+=== "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!'
+      };
+    });
+    ```
+
+### Tag Parser Signature
+
+- `tagContent` — The full text after the tag name, as a string.
+- `parser` — The Parser instance, providing `parser.parse()`, `parser.peek()`, `parser.skipTag()`.
+
+Returns a **Node** object with a `render(context)` method. The render method receives the `Context` object and returns a string.
+
+## Built-in Tags
+
+### Control Flow
+
+| Tag | Description |
+|-----|-------------|
+| `if / elif / else / endif` | Conditional blocks |
+| `for / empty / endfor` | Loop over arrays/objects |
+| `with / endwith` | Create a scoped context |
+| `cycle` | Cycle through values |
+| `firstof` | Output first non-empty value |
+| `ifchanged / endifchanged` | Only output if value changed |
+
+### Variable Assignment
+
+| Tag | Description |
+|-----|-------------|
+| `set var = expr` | Inline variable assignment |
+| `set var %}...{% endset` | Capture block output into a variable |
+
+### Date and Time
+
+| Tag | Description |
+|-----|-------------|
+| `now "Y-m-d H:i:s"` | Output current date/time |
+
+### Utility
+
+| Tag | Description |
+|-----|-------------|
+| `static "path"` | Resolve static asset path |
+| `url 'route.name' arg1 arg2` | Generate URL by route name |
+| `regroup list by attr as name` | Regroup a list by an attribute |
+| `spaceless / endspaceless` | Remove whitespace between HTML tags |
+| `widthratio value max max_width` | Calculate CSS width ratio |
+| `debug` | Output debugging context information |
+
+### Security
+
+| Tag | Description |
+|-----|-------------|
+| `csrf_token` | Output CSRF hidden input |
+| `csp_nonce_attr` | Output `nonce` attribute for CSP |
+
+### Comments and Raw Output
+
+| Tag | Description |
+|-----|-------------|
+| `comment / endcomment` | Comment out content |
+| `verbatim / endverbatim` | Disable tag parsing within |
+
+### Autoescape
+
+| Tag | Description |
+|-----|-------------|
+| `autoescape on / off / endautoescape` | Toggle HTML escaping |
+
+### Library Loading
+
+| Tag | Description |
+|-----|-------------|
+| `load library_name` | Load a registered library |
+
+### Template Tags
+
+| Tag | Description |
+|-----|-------------|
+| `templatetag token` | Output a template syntax character (e.g. `{% templatetag openpercentblock %}`) |
+
+### Inheritance
+
+| Tag | Description |
+|-----|-------------|
+| `extends "parent.html"` | Inherit from a parent template |
+| `block name / endblock` | Define/overriding inheritable block |
+| `include "file.html"` | Include another template |
+
+### Partials
+
+| Tag | Description |
+|-----|-------------|
+| `partialdef name / endpartialdef` | Define a named partial |
+| `partial name with k=v` | Render a defined partial |
+
+### i18n
+
+| Tag | Description |
+|-----|-------------|
+| `trans "key"` | Translate a string |
+| `blocktrans / endblocktrans` | Translate with variables |
+| `language "xx" / endlanguage` | Switch language for a block |
+
+## Next Steps
+
+- [Tags Guide](../guide/tags)
+- [Custom Tags](../guide/custom-tags)
+- [API Reference](../)