miki-template 2.0.0 → 2.2.2

package/docs/api/filters.md

@@ -0,0 +1,217 @@
+# Filters API
+
+## registerFilter
+
+Register a custom filter callable from templates as `{{ value|filter_name:arg }}`.
+
+=== "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('');
+    });
+    ```
+
+### Filter Signature
+
+Filters receive `(value, argument, context)` and must return a string (or `SafeString`):
+
+```javascript
+registerFilter('greet', (val, greeting, context) => {
+  return `${greeting}, ${val}!`;
+});
+```
+
+### Async Filters
+
+Filters that return a Promise are awaited automatically when using `asyncRender()`:
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerFilter, asyncRender } = require('miki-template');
+
+    registerFilter('fetch_data', async (url) => {
+      const res = await fetch(url);
+      return res.text();
+    });
+
+    const html = await asyncRender('{{ endpoint|fetch_data }}', {
+      endpoint: 'https://api.example.com/data'
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerFilter, asyncRender } from 'miki-template';
+
+    registerFilter('fetch_data', async (url) => {
+      const res = await fetch(url);
+      return res.text();
+    });
+
+    const html = await asyncRender('{{ endpoint|fetch_data }}', {
+      endpoint: 'https://api.example.com/data'
+    });
+    ```
+
+## getFilter
+
+Retrieve a registered filter by name.
+
+=== "CommonJS"
+
+    ```javascript
+    const { getFilter } = require('miki-template);
+
+    const reverseFilter = getFilter('reverse');
+    console.log(reverseFilter('hello')); // 'olleh'
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { getFilter } from 'miki-template';
+
+    const reverseFilter = getFilter('reverse');
+    ```
+
+## Built-in Filters
+
+### Text Filters
+
+| Filter | Description |
+|--------|-------------|
+| `upper` | Uppercase |
+| `lower` | Lowercase |
+| `title` | Title case |
+| `capfirst` | Capitalize first character |
+| `truncatewords:N` | Truncate to N words |
+| `truncatechars:N` | Truncate to N characters (ellipsis) |
+| `truncatechars_html:N` | Truncate to N chars, preserving HTML |
+| `wordcount` | Count words |
+| `striptags` | Remove HTML tags |
+| `slugify` | Convert to URL-friendly slug |
+| `linebreaks` | Convert newlines to `<br>` and `<p>` |
+| `linebreaksbr` | Convert newlines to `<br>` |
+| `length_is:N` | Return length if equals N, else empty |
+
+### HTML Filters
+
+| Filter | Description |
+|--------|-------------|
+| `safe` | Mark as safe (no escaping) |
+| `escape` | Force HTML escaping |
+
+### List Filters
+
+| Filter | Description |
+|--------|-------------|
+| `length` | Number of items |
+| `join:sep` | Join items with separator |
+| `slice:"start:end"` | Slice a list/string |
+| `dictsort:"key"` | Sort by key (ascending) |
+| `dictsortreversed:"key"` | Sort by key (descending) |
+| `sort` | Sort items |
+| `unique` | Remove duplicates |
+| `random` | Random item |
+| `reverse` | Reverse order |
+| `split:sep` | Split string into list |
+| `replace:"old,new"` | Replace occurrences |
+
+### Default Filters
+
+| Filter | Description |
+|--------|-------------|
+| `default:"fallback"` | Show fallback if value is falsy |
+| `default_if_none:"fallback"` | Show fallback if value is `null`/`undefined` |
+| `firstof:v1 v2 v3` | First non-empty value |
+
+### Date/Time Filters
+
+| Filter | Description |
+|--------|-------------|
+| `date:"Y-m-d"` | Django-style date format |
+| `time:"H:i"` | Django-style time format |
+| `date_format:"yyyy-MM-dd"` | Intl-style date format |
+| `strftime:"PPPP"` | Intl-style time format |
+| `timesince` | Time since date ("2 hours ago") |
+| `timeuntil` | Time until date |
+| `ago` | Short time-ago ("2m", "3h") |
+| `until` | Short time-until |
+| `time_diff:other_date` | Difference between two dates |
+
+### Numeric Filters
+
+| Filter | Description |
+|--------|-------------|
+| `add:N` | Add N |
+| `sub:N` | Subtract N |
+| `mult:N` | Multiply by N |
+| `divisibleby:N` | Check divisibility |
+| `mod:N` | Modulo |
+| `floatformat:N` | Format float with N decimals |
+| `square` | Square a number |
+| `sqrt` | Square root |
+| `abs` | Absolute value |
+| `round:N` | Round to N decimals |
+| `floor` | Floor |
+| `ceil` | Ceiling |
+| `min:N` | Minimum of value and N |
+| `max:N` | Maximum of value and N |
+| `sum` | Sum of list |
+| `average` | Average of list |
+
+### Currency and Data Formatting
+
+| Filter | Description |
+|--------|-------------|
+| `currency:"$"` | Format as currency |
+| `phone_number` | Format phone number |
+| `email` | Format as email link |
+| `url` | Format as URL link |
+| `mask:"*"` | Mask sensitive data |
+| `whatsapp_link:"msg"` | Generate WhatsApp link |
+| `credit_card` | Format credit card number |
+| `ssn` | Format SSN |
+| `ip_address` | Format IP address |
+| `uuid` | Format UUID |
+| `filesizeformat` | Human-readable file size |
+| `yesno:"yes,no,maybe"` | Yes/no based on boolean |
+| `pluralize:"s"` | Add plural suffix if needed |
+| `urlencode` | URL-encode |
+| `escapeuri` | Escape URI component |
+| `stringformat:"%s"` | String format |
+| `cut:"text"` | Remove occurrences |
+| `addslashes` | Add slashes |
+| `removetags:"p,div"` | Remove specified tags |
+| `trans:"key"` | Translate key |
+| `regroup:"attr"` | Regroup list by attribute |
+| `json` | Serialize to JSON |
+| `urlize` | Auto-link URLs in text |
+
+### Encoding Filters
+
+| Filter | Description |
+|--------|-------------|
+| `base64_encode` | Base64 encode |
+| `base64_decode` | Base64 decode |
+
+## Next Steps
+
+- [Filters Guide](../guide/filters)
+- [Custom Filters](../guide/custom-filters)
+- [API Reference](../)

package/docs/api/finder.md

@@ -0,0 +1,94 @@
+# Finder API
+
+## findTemplateInViews
+
+Find a template file by name in the provided views directories.
+
+=== "CommonJS"
+
+    ```javascript
+    const { findTemplateInViews } = require('miki-template');
+
+    const found = findTemplateInViews('home', ['./views', './app/templates']);
+    console.log(found);
+    // Output: /absolute/path/to/home.html
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { findTemplateInViews } from 'miki-template';
+
+    const found = findTemplateInViews('home', ['./views', './app/templates']);
+    console.log(found);
+    ```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `templateName` | `string` | Template name to search for (with or without extension) |
+| `viewsDirs` | `string[]` | Array of views directories to search |
+
+### Returns
+
+`string | null` — Absolute path to the template file, or `null` if not found.
+
+### Behavior
+
+- Searches recursively through subdirectories for bare template names (no `/` in name).
+- Tries `.html` and `.miki` extensions when no extension is provided.
+- Also searches app-style `templates/` directories nested inside the views root.
+- Returns the **first match found**.
+
+## setAppTemplateDirNames
+
+Configure which directory names are treated as app-style template directories.
+
+=== "CommonJS"
+
+    ```javascript
+    const { setAppTemplateDirNames } = require('miki-template');
+
+    setAppTemplateDirNames(['templates', 'views', 'pages']);
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { setAppTemplateDirNames } from 'miki-template';
+
+    setAppTemplateDirNames(['templates', 'views', 'pages']);
+    ```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `names` | `string \| string[]` | Directory name(s) to recognize |
+
+## getAppTemplateDirNames
+
+Get the current app template directory names.
+
+=== "CommonJS"
+
+    ```javascript
+    const { getAppTemplateDirNames } = require('miki-template');
+
+    console.log(getAppTemplateDirNames());
+    // ['templates']
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { getAppTemplateDirNames } from 'miki-template';
+
+    console.log(getAppTemplateDirNames());
+    ```
+
+## Next Steps
+
+- [Guide: Smart Template Discovery](../guide/template-discovery)
+- [API Reference](../)

package/docs/api/helpers.md

@@ -0,0 +1,53 @@
+# Helpers API
+
+## registerHelper
+
+Register a helper function that can be called from templates.
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerHelper } = require('miki-template');
+
+    registerHelper('bold', (inner, context) => `<b>${inner}</b>`);
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerHelper } from 'miki-template';
+
+    registerHelper('bold', (inner, context) => `<b>${inner}</b>`);
+    ```
+
+### Helper Signature
+
+Helpers receive `(content, context)` where `content` is the rendered inner content of the tag:
+
+```javascript
+registerHelper('panel', (content, context) => {
+  return `<div class="panel">${content}</div>`;
+});
+```
+
+Usage in templates:
+
+```html
+{% panel %}
+  <h2>{{ title }}</h2>
+  <p>{{ description }}</p>
+{% endpanel %}
+```
+
+## Built-in Helpers
+
+miki-template includes built-in helpers for common formatting tasks:
+
+- `bold` — Wrap content in `<b>` tags
+- `italic` — Wrap content in `<i>` tags
+- `underline` — Wrap content in `<u>` tags
+
+## Next Steps
+
+- [Custom Tags](../guide/custom-tags)
+- [API Reference](../)

package/docs/api/i18n.md

@@ -0,0 +1,157 @@
+# i18n API
+
+## registerTranslation
+
+Register translations for a language. Keys match the `{% trans "text" %}` source string.
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerTranslation } = require('miki-template');
+
+    registerTranslation('en', {
+      hello: 'Hello',
+      goodbye: 'Goodbye'
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerTranslation } from 'miki-template';
+
+    registerTranslation('en', {
+      hello: 'Hello',
+      goodbye: 'Goodbye'
+    });
+    ```
+
+You can also register nested keys for `blocktrans` with variables:
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerTranslation, setLanguage } = require('miki-template');
+
+    setLanguage('en');
+    registerTranslation('en', {
+      'Welcome, {name}!': 'Welcome, {name}!',
+      'Goodbye, {name}!': 'Goodbye, {name}!'
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerTranslation, setLanguage } from 'miki-template';
+
+    setLanguage('en');
+    registerTranslation('en', {
+      'Welcome, {name}!': 'Welcome, {name}!',
+      'Goodbye, {name}!': 'Goodbye, {name}!'
+    });
+    ```
+
+## unregisterTranslation
+
+=== "CommonJS"
+
+    ```javascript
+    const { unregisterTranslation } = require('miki-template');
+
+    // Unregister a specific key
+    unregisterTranslation('en', 'hello');
+
+    // Unregister entire language
+    unregisterTranslation('en');
+
+    // Unregister all translations
+    unregisterTranslation();
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { unregisterTranslation } from 'miki-template';
+
+    unregisterTranslation('en', 'hello');
+    ```
+
+## setLanguage / getLanguage
+
+Set or get the active language.
+
+=== "CommonJS"
+
+    ```javascript
+    const { setLanguage, getLanguage } = require('miki-template');
+
+    setLanguage('fr');
+    console.log(getLanguage()); // 'fr'
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { setLanguage, getLanguage } from 'miki-template';
+
+    setLanguage('fr');
+    console.log(getLanguage()); // 'fr'
+    ```
+
+## setFallbackLanguage / getFallbackLanguage
+
+Set or get the fallback language (used when a key is missing from the active language).
+
+=== "CommonJS"
+
+    ```javascript
+    const { setFallbackLanguage, getFallbackLanguage } = require('miki-template');
+
+    setFallbackLanguage('en');
+    console.log(getFallbackLanguage()); // 'en'
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { setFallbackLanguage, getFallbackLanguage } from 'miki-template';
+
+    setFallbackLanguage('en');
+    ```
+
+## getAvailableLanguages
+
+List all registered languages.
+
+=== "CommonJS"
+
+    ```javascript
+    const { getAvailableLanguages } = require('miki-template');
+
+    console.log(getAvailableLanguages());
+    // ['en', 'fr', 'es']
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { getAvailableLanguages } from 'miki-template';
+
+    console.log(getAvailableLanguages());
+    ```
+
+## Template Tags
+
+The `{% trans %}` and `{% blocktrans %}` tags are provided by the auto-activated `i18n` library:
+
+```html
+{% trans "Hello" %}
+{% blocktrans %}Welcome, {{ name }}!{% endblocktrans %}
+{% language "fr" %}...{% endlanguage %}
+```
+
+## Next Steps
+
+- [Advanced Usage: i18n](../guide/advanced-usage#i18n--internationalization)
+- [API Reference](../)

package/docs/api/index.md

@@ -0,0 +1,54 @@
+# API Reference
+
+## Core Functions
+
+- [render()](./render) — Render a template string or file partial
+- [compile()](./compile) — Compile a template into a reusable object with `render()`, `asyncRender()`, `renderBlock()`, `renderPartial()`
+- [asyncRender()](./async-render) — Asynchronous rendering (supports async filters/tags)
+- [renderPartialFromFile()](./render-partial) — Render a named partial from a file
+- [renderPartialFromSource()](./render-partial) — Render a named partial from source
+- [setupExpress()](./setup-express) — One-line Express integration
+
+## Tag and Filter Registration
+
+- [registerFilter()](./filters) — Register a custom filter
+- [getFilter()](./filters) — Retrieve a registered filter
+- [registerTag()](./tags) — Register a custom tag
+- [registerHelper()](./helpers) — Register a custom helper
+
+## Utilities
+
+- [findTemplateInViews()](./finder) — Locate a template in views directories
+- [setAppTemplateDirNames()](./finder) — Configure app-style template directory names
+- [clearCache()](./cache) — Clear the compiled template cache
+- [registerContextProcessor()](./context-processors) — Register a global context processor
+- [clearContextProcessors()](./context-processors) — Clear all context processors
+
+## Security
+
+- [markSafe()](./security) — Mark a string as safe (bypass escaping)
+- [isSafe()](./security) — Check if a value is marked safe
+- [escapeHtml()](./security) — Escape HTML special characters
+- [SafeString](./security) — SafeString class
+
+## Express Engine Functions
+
+- `__express(filePath, options, callback)` — Express-compatible sync view engine
+- `__expressAsync(filePath, options)` — Express 5 async view engine (returns Promise)
+- `express(options)` — Returns a view engine function for `app.engine()`
+- `expressPartialRenderer()` — Express middleware adding `res.renderPartial()`
+- `stripExpressContext(options)` — Remove Express framework keys from context
+
+## i18n
+
+- [registerTranslation()](./i18n) — Register translations for a language
+- [unregisterTranslation()](./i18n) — Unregister translations
+- [setLanguage()](./i18n) / [getLanguage()](./i18n) — Set/get active language
+- [setFallbackLanguage()](./i18n) / [getFallbackLanguage()](./i18n) — Set/get fallback language
+- [getAvailableLanguages()](./i18n) — List registered languages
+
+## Libraries
+
+- [registerLibrary()](./libraries) — Register a named library (filters, tags, helpers)
+- [activateLibrary()](./libraries) / [registerLibraryFromPath()](./libraries) — Activate or load from file
+- [unregisterLibrary()](./libraries) / [hasLibrary()](./libraries) / [getLibraryNames()](./libraries) — Library management