miki-template 2.0.1 → 2.2.2

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

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)