miki-template 1.2.0 → 1.3.6

package/dir/index.html

@@ -0,0 +1,80 @@
+{% extends 'base.html' %}
+
+{% block title %}
+  {{ siteName|default:'Home page Here'|title }} | {{ block.super }}
+{% endblock %}
+
+{% block content %}
+  {% partialdef card  inline %}
+  <div class="card">
+    <h3>{{ title|default:'No title' }}</h3>
+    <p>{{ description|default:'{% lorem 20 %}'|upper }}</p>
+  </div>
+  {% endpartialdef %}
+
+  {% partial card with title='Hello' description='World' %}
+
+  {% with a=5 %}
+    <marquee behavior="" direction="">
+      <span>some new stuff with with tag : {{ a|add:5 }}</span>
+    </marquee>
+  {% endwith %}
+
+  {{ name }}
+  {{ login.name }}
+  {{ login.email }}
+  <h1>Users table goes below</h1>
+  <table border="3">
+    <th>name</th>
+    <th>email</th>
+    <th>action</th>
+
+    {% for user in users %}
+      <tr>
+        <td>{{ user.name|title }}</td>
+        <td>{{ user.email }}</td>
+        <td>
+          <a href="">Delete user</a>
+        </td>
+      </tr>
+    {% endfor %}
+    
+  </table>
+  <h1>Data list</h1>
+  <h2>data list of data</h2>
+  {% for obj in data %}
+    {% partialdef mike inline %}
+
+    <li>{{ obj.name }}</li>
+    <li>{{ forloop.counter }}</li>
+   <li> {{ obj.email }}</li>
+    {% endpartialdef %}
+  {% endfor %}
+
+  <h2>users list of data</h2>
+  <ul style="background-color: aqua;color: blueviolet; list-style-type:upper-roman;">
+
+    {% for obj in users %}
+    {% partial mike %}
+    {% endfor %}
+  </ul>
+
+  <h3>form with crsf</h3>
+
+  <form action="">
+    {% csrf_token %}
+    <input type="text" name="" id="" title="some text"/>
+  </form>
+<h3>included content here</h3>
+  {% include 'cmpnt.html#me' %}
+
+  {{"2324"|filesizeformat}}
+  {{"224"|filesizeformat}}
+  {{ "123456789"|filesizeformat }}
+  {{ "1234567890"|filesizeformat }}
+  {{ "1234567890123"|filesizeformat }}
+  {{ "1234567890123456"|filesizeformat }}
+  {{ "1234567890123456789"|filesizeformat }}
+
+
+{% endblock %}

package/dir/navbar.html

@@ -0,0 +1,9 @@
+<header>
+    <div class="brand">
+        <img src="/path/to/logo.png" alt="Logo" width="40px">
+    </div>
+    <nav>
+        <a href="/">Home</a>
+
+    </nav>
+</header>

package/docs/README.md

@@ -1,18 +1,18 @@
-# Documentation Index
-
-Welcome to the **miki-template** documentation hub. Below is a quick navigation guide to all docs.
-
-| Document | Description |
-|---|---|
-| [overview.md](overview.md) | High‑level project overview and repository layout |
-| [installation.md](installation.md) | How to install the package and prerequisites |
-| [usage.md](usage.md) | Basic API usage, rendering, compilation, and block rendering |
-| [tags.md](tags.md) | Reference for every built‑in tag (`if`, `for`, `partialdef`, etc.) |
-| [filters.md](filters.md) | Comprehensive list of built‑in filters with examples |
-| [partialdef.md](partialdef.md) | Detailed guide for the `partialdef` feature (including inline, nesting, API) |
-| [security.md](security.md) | Security considerations (auto‑escaping, CSP, CSRF) |
-| [api.md](api.md) | Low‑level API surface – `compile`, `renderPartial`, `registerTag`, etc. |
-| [contributing.md](contributing.md) | Guidelines for contributing, pull‑request flow, and code style |
-| [roadmap.md](roadmap.md) | Future milestones and release schedule |
-
-All files are located under `c:/Users/Coder Miki/Desktop/miki-template/docs/`.
+# Documentation Index
+
+Welcome to the **miki-template** documentation hub. Below is a quick navigation guide to all docs.
+
+| Document | Description |
+|---|---|
+| [overview.md](overview.md) | High‑level project overview and repository layout |
+| [installation.md](installation.md) | How to install the package and prerequisites |
+| [usage.md](usage.md) | Basic API usage, rendering, compilation, and block rendering |
+| [tags.md](tags.md) | Reference for every built‑in tag (`if`, `for`, `partialdef`, etc.) |
+| [filters.md](filters.md) | Comprehensive list of built‑in filters with examples |
+| [partialdef.md](partialdef.md) | Detailed guide for the `partialdef` feature (including inline, nesting, API) |
+| [security.md](security.md) | Security considerations (auto‑escaping, CSP, CSRF) |
+| [api.md](api.md) | Low‑level API surface – `compile`, `renderPartial`, `registerTag`, etc. |
+| [contributing.md](contributing.md) | Guidelines for contributing, pull‑request flow, and code style |
+| [roadmap.md](roadmap.md) | Future milestones and release schedule |
+
+All files are located under `c:/Users/Coder Miki/Desktop/miki-template/docs/`.

package/docs/advanced_usage.md

@@ -1,71 +1,71 @@
-# Advanced Usage
-
-This document showcases real‑world examples of the **miki‑template** engine.
-
-## 1. Partial Definition & Inclusion
-```django
-{% partialdef "header" %}
-<header>
-  <h1>{{ site.title }}</h1>
-</header>
-{% endpartialdef %}
-
-{% include "header" %}
-```
-*Result:* Renders a reusable header component.
-
----
-## 2. Custom Tag Helper – Markdown
-```js
-const { registerHelper } = require('./src/tags/helpers');
-const markdownIt = require('markdown-it')();
-registerHelper('markdown', (content) => markdownIt.render(content));
-```
-```django
-{% markdown %}
-# Hello World
-* Item 1
-* Item 2
-{% endmarkdown %}
-```
-*Result:* Converts markdown to HTML on‑the‑fly.
-
----
-## 3. Async Rendering with a Sleep Helper
-```js
-registerHelper('sleep', async (content) => {
-  await new Promise(r => setTimeout(r, 50));
-  return `Awake after ${content}`;
-});
-```
-```django
-{% sleep %}50ms{% endsleep %}
-```
-```js
-const { asyncRender } = require('./src');
-asyncRender(template, {} ).then(console.log);
-```
-*Result:* `Awake after 50ms`
-
----
-## 4. Extended Date Formatting
-```django
-{{ now|date_format:"yyyy-MM-dd HH:mm:ss" }}
-```
-*Result:* `2026-08-29 13:48:07`
-### Additional Date Filter Examples
-
-```django
-{{ now|strftime:"PPpp" }}          {# Full date-fns pattern #}
-{{ now|date:"Y-m-d H:i:s" }}        {# Django style with seconds #}
-{{ now|time:"H:i:s" }}              {# Time only #}
-```
-
-*Result:* Example outputs will appear when rendered.
-
----
-## 5. Performance Benchmark (see `benchmarks/run.js`)
-The benchmark renders three template sizes (small, medium, large) synchronously and asynchronously, reporting average render time and cache hit ratio.
-
----
-> **Tip:** All examples work with the default Express integration via `app.engine('dtpl', require('miki-template').__express);`
+# Advanced Usage
+
+This document showcases real‑world examples of the **miki‑template** engine.
+
+## 1. Partial Definition & Inclusion
+```django
+{% partialdef "header" %}
+<header>
+  <h1>{{ site.title }}</h1>
+</header>
+{% endpartialdef %}
+
+{% include "header" %}
+```
+*Result:* Renders a reusable header component.
+
+---
+## 2. Custom Tag Helper – Markdown
+```js
+const { registerHelper } = require('./src/tags/helpers');
+const markdownIt = require('markdown-it')();
+registerHelper('markdown', (content) => markdownIt.render(content));
+```
+```django
+{% markdown %}
+# Hello World
+* Item 1
+* Item 2
+{% endmarkdown %}
+```
+*Result:* Converts markdown to HTML on‑the‑fly.
+
+---
+## 3. Async Rendering with a Sleep Helper
+```js
+registerHelper('sleep', async (content) => {
+  await new Promise(r => setTimeout(r, 50));
+  return `Awake after ${content}`;
+});
+```
+```django
+{% sleep %}50ms{% endsleep %}
+```
+```js
+const { asyncRender } = require('./src');
+asyncRender(template, {} ).then(console.log);
+```
+*Result:* `Awake after 50ms`
+
+---
+## 4. Extended Date Formatting
+```django
+{{ now|date_format:"yyyy-MM-dd HH:mm:ss" }}
+```
+*Result:* `2026-08-29 13:48:07`
+### Additional Date Filter Examples
+
+```django
+{{ now|strftime:"PPpp" }}          {# Full date-fns pattern #}
+{{ now|date:"Y-m-d H:i:s" }}        {# Django style with seconds #}
+{{ now|time:"H:i:s" }}              {# Time only #}
+```
+
+*Result:* Example outputs will appear when rendered.
+
+---
+## 5. Performance Benchmark (see `benchmarks/run.js`)
+The benchmark renders three template sizes (small, medium, large) synchronously and asynchronously, reporting average render time and cache hit ratio.
+
+---
+> **Tip:** All examples work with the default Express integration via `app.engine('dtpl', require('miki-template').__express);`

package/docs/api.md

@@ -1,102 +1,119 @@
-# API Reference
-
-This document lists the public API exported by **miki-template** for developers to integrate the engine into their projects.
-
-| Function / Export | Signature | Description | Example |
-|---|---|---|---|
-| `compile(templateStr, options?)` | `compile(string, object?) → { render, asyncRender, renderBlock, renderPartial }` | Compiles a template string into a renderable object. Optional `options` can include `views` directories, custom tags/filters, etc. | `const tpl = compile('Hello {{ name }}');` |
-| `render(templateStr, context?, options?)` | `render(string, object?, object?) → string` | One‑off rendering of a template string with the provided context. | `render('Hello {{ name }}', { name: 'World' });` |
-| `asyncRender(templateStr, context?, options?)` | `asyncRender(string, object?, object?) → Promise<string>` | Asynchronous rendering (useful with async helpers). | `await asyncRender(tpl, ctx);` |
-| `__express(filePath, options, callback)` | `__express(string, object, function)` | Express view engine adapter – reads the file at `filePath` and renders it. | `app.set('view engine', 'miki');` |
-| `__expressAsync(filePath, options)` | `__expressAsync(string, object) → Promise<string>` | Async Express 5+ view engine adapter. Returns a Promise that resolves to rendered HTML. | `app.engine('html', miki.__expressAsync);` |
-| `stripExpressContext(options)` | `stripExpressContext(object) → object` | Remove Express framework keys (`_locals`, `settings`, `cache`) from an options object. | `const ctx = stripExpressContext(res.locals);` |
-| `clearCache()` | `clearCache() → void` | Clear the in-memory compiled template cache. | `clearCache();` |
-| `registerTag(name, parserFn)` | `registerTag(string, function)` | Register a custom tag parser. Must be called before compiling templates. | `registerTag('mytag', parserFn);` |
-| `registerFilter(name, fn)` | `registerFilter(string, function)` | Register a custom filter. | `registerFilter('reverse', str => str.split('').reverse().join(''));` |
-| `getFilter(name)` | `getFilter(string) → function` | Retrieve a registered filter function by name. | `const upper = getFilter('upper');` |
-| `registerHelper(name, fn)` | `registerHelper(string, function)` | Register a helper function available inside templates. | `registerHelper('upper', s => s.toUpperCase());` |
-| `registerContextProcessor(fn)` | `registerContextProcessor(function)` | Add a context processor that mutates the rendering context before each render. | `registerContextProcessor(ctx => ({ ...ctx, csrf_token: '123' }));` |
-| `registerTranslation(lang, messages)` | `registerTranslation(string, object) → void` | Register translation messages for a language. | `registerTranslation('fr', { 'Hello': 'Bonjour' });` |
-| `setLanguage(lang)` | `setLanguage(string) → void` | Set the active language for all subsequent renders. | `setLanguage('fr');` |
-| `getLanguage()` | `getLanguage() → string` | Get the currently active language. | `const lang = getLanguage();` |
-| `setFallbackLanguage(lang)` | `setFallbackLanguage(string) → void` | Set the fallback language for missing translations. | `setFallbackLanguage('en');` |
-| `getAvailableLanguages()` | `getAvailableLanguages() → string[]` | List all registered language codes. | `const langs = getAvailableLanguages();` |
-| `registerLibrary(name, def)` | `registerLibrary(string, object) → void` | Register a plugin library of tags, filters, and helpers. | `registerLibrary('humanize', { filters: { intcomma } });` |
-| `registerLibraryFromPath(name, path)` | `registerLibraryFromPath(string, string) → object` | Load a library from a JS file on disk. | `registerLibraryFromPath('myLib', './libs/my-lib.js');` |
-| `activateLibrary(name)` | `activateLibrary(string) → void` | Activate a registered library (makes its tags/filters available). | `activateLibrary('humanize');` |
-| `SafeString` | `class SafeString` | Wrapper class for values that should bypass auto‑escaping. Returned by `markSafe`. |
-| `markSafe(value)` | `markSafe(any) → SafeString` | Marks a value as safe, preventing HTML escaping. |
-| `isSafe(value)` | `isSafe(any) → boolean` | Checks if a value is a `SafeString`. |
-| `escapeHtml(str)` | `escapeHtml(string) → string` | Escapes HTML special characters. Used internally for auto‑escaping. |
-
-All of the above are exported from `src/index.js` and can be imported via:
-
-### CommonJS
-```js
-const {
-  compile,
-  render,
-  asyncRender,
-  __express,
-  __expressAsync,
-  stripExpressContext,
-  clearCache,
-  registerTag,
-  registerFilter,
-  getFilter,
-  registerHelper,
-  registerContextProcessor,
-  registerTranslation,
-  setLanguage,
-  getLanguage,
-  setFallbackLanguage,
-  getAvailableLanguages,
-  registerLibrary,
-  registerLibraryFromPath,
-  activateLibrary,
-  SafeString,
-  markSafe,
-  isSafe,
-  escapeHtml
-} = require('miki-template');
-```
-
-### ES Modules (ESM)
-```js
-import {
-  compile,
-  render,
-  asyncRender,
-  __express,
-  __expressAsync,
-  stripExpressContext,
-  clearCache,
-  registerTag,
-  registerFilter,
-  getFilter,
-  registerHelper,
-  registerContextProcessor,
-  registerTranslation,
-  setLanguage,
-  getLanguage,
-  setFallbackLanguage,
-  getAvailableLanguages,
-  registerLibrary,
-  registerLibraryFromPath,
-  activateLibrary,
-  SafeString,
-  markSafe,
-  isSafe,
-  escapeHtml
-} from 'miki-template';
-
-// Or import all as default
-import miki from 'miki-template';
-const { render: mikiRender } = miki;
-```
-
-For detailed usage, refer to the corresponding sections in the documentation:
-- **Usage** – `docs/usage.md`
-- **Tags** – `docs/tags.md`
-- **Filters** – `docs/filters.md`
-- **Security** – `docs/security.md`
+# API Reference
+
+This document lists the public API exported by **miki-template** for developers to integrate the engine into their projects.
+
+| Function / Export | Signature | Description | Example |
+|---|---|---|---|
+| `compile(templateStr, options?)` | `compile(string, object?) → { render, asyncRender, renderBlock, renderPartial }` | Compiles a template string into a renderable object. Optional `options` can include `views` directories, custom tags/filters, etc. | `const tpl = compile('Hello {{ name }}');` |
+| `render(templateStr, context?, options?)` | `render(string, object?, object?) → string` | One‑off rendering of a template string with the provided context. | `render('Hello {{ name }}', { name: 'World' });` |
+| `asyncRender(templateStr, context?, options?)` | `asyncRender(string, object?, object?) → Promise<string>` | Asynchronous rendering (useful with async helpers). | `await asyncRender(tpl, ctx);` |
+| `__express(filePath, options, callback)` | `__express(string, object, function)` | Express view engine adapter – reads the file at `filePath` and renders it. Honors `view#partial` suffixes for HTMX-style partial responses. | `app.engine('html', miki.__express);` |
+| `__expressAsync(filePath, options)` | `__expressAsync(string, object) → Promise<string>` | Async Express 5+ view engine adapter. Returns a Promise that resolves to rendered HTML. Also honors `view#partial` suffixes. | `app.engine('html', miki.__expressAsync);` |
+| `express(options?)` | `express(object?) → function` | Factory that returns a view-engine function suitable for `app.engine(...)`. Honors `view#partial` selectors. | `app.engine('html', miki.express());` |
+| `setupExpress(app, opts?)` | `setupExpress(expressApp, object?) → void` | **One-line Express integration.** Wires `app.engine(...)`, `app.set('views')`, and patches `res.render` so `res.render('view#partial', ...)` returns just that partial. Options: `{ extension?, views?, async? }`. | `miki.setupExpress(app, { extension: 'html', views: './views' });` |
+| `expressPartialRenderer()` | `expressPartialRenderer() → function` | Express middleware that adds `res.renderPartial(view, locals)`. Useful as a drop-in HTMX helper without the full `setupExpress` shim. | `app.use(miki.expressPartialRenderer());` |
+| `renderPartialFromFile(filePath, partialName, context?, options?)` | `renderPartialFromFile(string, string, object?, object?) → string` | Load a file from disk and render only the named `{% partialdef %}`. | `miki.renderPartialFromFile('views/home.html', 'card', { user });` |
+| `renderPartialFromSource(source, partialName, context?, options?)` | `renderPartialFromSource(string, string, object?, object?) → string` | Render a single named partial directly from a template string. Walks the AST (and `extends` chain) to discover partials nested inside blocks. | `miki.renderPartialFromSource(src, 'card', ctx, { views });` |
+| `stripExpressContext(options)` | `stripExpressContext(object) → object` | Remove Express framework keys (`_locals`, `settings`, `cache`) from an options object. | `const ctx = stripExpressContext(res.locals);` |
+| `clearCache()` | `clearCache() → void` | Clear the in-memory compiled template cache. | `clearCache();` |
+| `registerTag(name, parserFn)` | `registerTag(string, function)` | Register a custom tag parser. Must be called before compiling templates. | `registerTag('mytag', parserFn);` |
+| `registerFilter(name, fn)` | `registerFilter(string, function)` | Register a custom filter. | `registerFilter('reverse', str => str.split('').reverse().join(''));` |
+| `getFilter(name)` | `getFilter(string) → function` | Retrieve a registered filter function by name. | `const upper = getFilter('upper');` |
+| `registerHelper(name, fn)` | `registerHelper(string, function)` | Register a helper function available inside templates. | `registerHelper('upper', s => s.toUpperCase());` |
+| `registerContextProcessor(fn)` | `registerContextProcessor(function)` | Add a context processor that mutates the rendering context before each render. | `registerContextProcessor(ctx => ({ ...ctx, csrf_token: '123' }));` |
+| `registerTranslation(lang, messages)` | `registerTranslation(string, object) → void` | Register translation messages for a language. | `registerTranslation('fr', { 'Hello': 'Bonjour' });` |
+| `setLanguage(lang)` | `setLanguage(string) → void` | Set the active language for all subsequent renders. | `setLanguage('fr');` |
+| `getLanguage()` | `getLanguage() → string` | Get the currently active language. | `const lang = getLanguage();` |
+| `setFallbackLanguage(lang)` | `setFallbackLanguage(string) → void` | Set the fallback language for missing translations. | `setFallbackLanguage('en');` |
+| `getAvailableLanguages()` | `getAvailableLanguages() → string[]` | List all registered language codes. | `const langs = getAvailableLanguages();` |
+| `registerLibrary(name, def)` | `registerLibrary(string, object) → void` | Register a plugin library of tags, filters, and helpers. | `registerLibrary('humanize', { filters: { intcomma } });` |
+| `registerLibraryFromPath(name, path)` | `registerLibraryFromPath(string, string) → object` | Load a library from a JS file on disk. | `registerLibraryFromPath('myLib', './libs/my-lib.js');` |
+| `activateLibrary(name)` | `activateLibrary(string) → void` | Activate a registered library (makes its tags/filters available). | `activateLibrary('humanize');` |
+| `SafeString` | `class SafeString` | Wrapper class for values that should bypass auto‑escaping. Returned by `markSafe`. |
+| `markSafe(value)` | `markSafe(any) → SafeString` | Marks a value as safe, preventing HTML escaping. |
+| `isSafe(value)` | `isSafe(any) → boolean` | Checks if a value is a `SafeString`. |
+| `escapeHtml(str)` | `escapeHtml(string) → string` | Escapes HTML special characters. Used internally for auto‑escaping. |
+
+All of the above are exported from `src/index.js` and can be imported via:
+
+### CommonJS
+```js
+const {
+  compile,
+  render,
+  asyncRender,
+  __express,
+  __expressAsync,
+  express,
+  setupExpress,
+  expressPartialRenderer,
+  renderPartialFromFile,
+  renderPartialFromSource,
+  stripExpressContext,
+  clearCache,
+  registerTag,
+  registerFilter,
+  getFilter,
+  registerHelper,
+  registerContextProcessor,
+  clearContextProcessors,
+  registerTranslation,
+  setLanguage,
+  getLanguage,
+  setFallbackLanguage,
+  getAvailableLanguages,
+  registerLibrary,
+  registerLibraryFromPath,
+  activateLibrary,
+  SafeString,
+  markSafe,
+  isSafe,
+  escapeHtml
+} = require('miki-template');
+```
+
+### ES Modules (ESM)
+```js
+import {
+  compile,
+  render,
+  asyncRender,
+  __express,
+  __expressAsync,
+  express,
+  setupExpress,
+  expressPartialRenderer,
+  renderPartialFromFile,
+  renderPartialFromSource,
+  stripExpressContext,
+  clearCache,
+  registerTag,
+  registerFilter,
+  getFilter,
+  registerHelper,
+  registerContextProcessor,
+  clearContextProcessors,
+  registerTranslation,
+  setLanguage,
+  getLanguage,
+  setFallbackLanguage,
+  getAvailableLanguages,
+  registerLibrary,
+  registerLibraryFromPath,
+  activateLibrary,
+  SafeString,
+  markSafe,
+  isSafe,
+  escapeHtml
+} from 'miki-template';
+
+// Or import all as default
+import miki from 'miki-template';
+const { render: mikiRender, setupExpress } = miki;
+```
+
+For detailed usage, refer to the corresponding sections in the documentation:
+- **Usage** – `docs/usage.md`
+- **Tags** – `docs/tags.md`
+- **Filters** – `docs/filters.md`
+- **Security** – `docs/security.md`