miki-template 2.0.1 → 2.2.3

package/docs/api/compile.md

@@ -0,0 +1,128 @@
+# compile()
+
+Compile a template string into a reusable renderable object.
+
+## Signature
+
+```javascript
+compile(templateStr, options = {})
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `templateStr` | `string` | Template source string |
+| `options` | `object` | Options including `views` directories |
+
+## Returns
+
+An object with these render methods:
+
+| Method | Description |
+|--------|-------------|
+| `render(contextObj, callOptions)` | Synchronous render |
+| `renderWith(contextObj, callOptions)` | Render with options override |
+| `asyncRender(contextObj)` | Asynchronous render (supports async filters/tags) |
+| `asyncRenderWith(contextObj, callOptions)` | Async render with options override |
+| `renderBlock(blockName, contextObj)` | Render a single `{% block %}` |
+| `renderPartial(partialName, contextObj)` | Render a named `{% partialdef %}` |
+
+## Examples
+
+### Basic compile
+
+=== "CommonJS"
+
+    ```javascript
+    const { compile } = require('miki-template');
+
+    const compiled = compile('<h1>{{ title }}</h1>');
+
+    const html = compiled.render({ title: 'Hello' });
+    // Output: <h1>Hello</h1>
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { compile } from 'miki-template';
+
+    const compiled = compile('<h1>{{ title }}</h1>');
+
+    const html = compiled.render({ title: 'Hello' });
+    // Output: <h1>Hello</h1>
+    ```
+
+### Render with options override
+
+=== "CommonJS"
+
+    ```javascript
+    const { compile } = require('miki-template');
+
+    const compiled = compile(template, { views: './templates' });
+    const html = compiled.renderWith({ title: 'Hello' }, { views: './other-views' });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { compile } from 'miki-template';
+
+    const compiled = compile(template, { views: './templates' });
+    const html = compiled.renderWith({ title: 'Hello' }, { views: './other-views' });
+    ```
+
+### Render a Block (template inheritance)
+
+=== "CommonJS"
+
+    ```javascript
+    const { compile } = require('miki-template');
+
+    const compiled = compile(childTemplate, { views: './templates' });
+    const html = compiled.renderBlock('content', context);
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { compile } from 'miki-template';
+
+    const compiled = compile(childTemplate, { views: './templates' });
+    const html = compiled.renderBlock('content', context);
+    ```
+
+### Render a Partial
+
+=== "CommonJS"
+
+    ```javascript
+    const { compile } = require('miki-template');
+
+    const compiled = compile(`
+      {% partialdef card %}
+        <div class="card">{{ title }}</div>
+      {% endpartialdef %}
+    `);
+    const html = compiled.renderPartial('card', { title: 'Hello' });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { compile } from 'miki-template';
+
+    const compiled = compile(`
+      {% partialdef card %}
+        <div class="card">{{ title }}</div>
+      {% endpartialdef %}
+    `);
+    const html = compiled.renderPartial('card', { title: 'Hello' });
+    ```
+
+## Related
+
+- [render()](./render)
+- [asyncRender()](./async-render)

package/docs/api/context-processors.md

@@ -0,0 +1,77 @@
+# Context Processors API
+
+## registerContextProcessor
+
+Register a context processor function that runs before every render. The returned object is merged into the rendering context, with explicit context values always winning.
+
+=== "CommonJS"
+
+    ```javascript
+    const { registerContextProcessor } = require('miki-template');
+
+    registerContextProcessor((context) => {
+      return {
+        siteName: 'My App',
+        currentYear: new Date().getFullYear()
+      };
+    });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { registerContextProcessor } from 'miki-template';
+
+    registerContextProcessor((context) => {
+      return {
+        siteName: 'My App',
+        currentYear: new Date().getFullYear()
+      };
+    });
+    ```
+
+### Signature
+
+```typescript
+type ContextProcessor = (context: Context) => Record<string, any> | null
+```
+
+- Receives the `Context` object, allowing inspection of existing values via `context.get('key')`.
+- Must return a plain object. Returning `null` or `undefined` is treated as `{}`.
+- Must be synchronous — no async/await or Promises.
+
+## clearContextProcessors
+
+Clear all registered context processors. Useful in tests or when re-configuring.
+
+=== "CommonJS"
+
+    ```javascript
+    const { clearContextProcessors } = require('miki-template');
+
+    clearContextProcessors();
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { clearContextProcessors } from 'miki-template';
+
+    clearContextProcessors();
+    ```
+
+## Precedence Rules
+
+1. **Context processors run first** — their key/value pairs are added to the context.
+2. **Your explicit context is applied last** — explicit values always override processor values.
+
+```javascript
+// Processor sets: { siteName: 'My App', theme: 'dark' }
+// You render with: { theme: 'light' }
+// Result: { siteName: 'My App', theme: 'light' }
+```
+
+## Next Steps
+
+- [Context Processors Guide](../guide/context-processors)
+- [API Reference](../)

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](../)