miki-template 2.0.1 → 2.2.3

package/docs/guide/getting-started.md

@@ -0,0 +1,102 @@
+# Getting Started
+
+Get up and running with miki-template in under a minute.
+
+## Prerequisites
+
+- **Node.js** 18.x or 20.x (or later, including Bun)
+- **npm** 9+, **pnpm**, or **yarn**
+
+## Installation
+
+=== "npm"
+
+    ```bash
+    npm install miki-template
+    ```
+
+=== "pnpm"
+
+    ```bash
+    pnpm add miki-template
+    ```
+
+=== "yarn"
+
+    ```bash
+    yarn add miki-template
+    ```
+
+## Quick Example: Render a Template String
+
+The simplest way to use miki-template is the `render()` convenience function. It compiles the template, applies any registered context processors, and returns the HTML — all in one call.
+
+=== "CommonJS (require)"
+
+    ```javascript
+    const { render } = require('miki-template');
+
+    const html = render('Hello {{ name|title }}!', { name: 'alice' });
+    console.log(html); // "Hello Alice!"
+    ```
+
+=== "ES Modules (import)"
+
+    ```javascript
+    import { render } from 'miki-template';
+
+    const html = render('Hello {{ name|title }}!', { name: 'alice' });
+    console.log(html); // "Hello Alice!"
+    ```
+
+## Quick Example: Express App
+
+The real power of miki-template comes with `setupExpress()` — a single function that registers the view engine, configures the views directory, and patches `res.render` so you can render partials with the `view#partial` syntax.
+
+=== "CommonJS (require)"
+
+    ```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.listen(3000, () => console.log('Listening on :3000'));
+    ```
+
+=== "ES Modules (import)"
+
+    ```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.listen(3000, () => console.log('Listening on :3000'));
+    ```
+
+=== "Bun"
+
+    ```typescript
+    import { setupExpress } from 'miki-template';
+    import express from 'express';
+
+    const app = express();
+    // Named import works; default import also works (`import miki from ...`)
+    setupExpress(app, { extension: 'html', views: './views' });
+    ```
+
+## Next Steps
+
+- [What is miki-template?](./what-is-miki-template)
+- [Why miki-template?](./why-miki-template)
+- [Installation Guide](./installation)
+- [Quick Start](./quick-start)
+- [Template Syntax & Tags](./tags)
+- [Filters](./filters)

package/docs/guide/installation.md

@@ -0,0 +1,95 @@
+# Installation
+
+Complete guide to installing and verifying miki-template in different environments.
+
+## Requirements
+
+- **Node.js** 18.x or 20.x (Node 18+ required for `URL`, `fetch`, and other Web API globals used by the engine)
+- **npm** 9+, **pnpm**, or **yarn**
+- **Bun** (optional) — miki-template is fully compatible with Bun
+
+## Install via npm
+
+```bash
+npm install miki-template
+```
+
+## Install via pnpm
+
+```bash
+pnpm add miki-template
+```
+
+## Install via yarn
+
+```bash
+yarn add miki-template
+```
+
+## Install via Bun
+
+```bash
+bun add miki-template
+```
+
+## Package.json `"type"` Considerations
+
+miki-template ships a dual CommonJS/ESM package:
+
+- **CommonJS** entry: `src/index.js` — importable via `require('miki-template')` or `import` (Node auto-detects the `import` condition).
+- **ESM** entry: `src/esm.mjs` — importable via `import ... from 'miki-template'`.
+
+| Your project uses | How to import |
+|---|---|
+| CommonJS (`"type": "commonjs"` or no `type` field) | `const miki = require('miki-template')` |
+| ES Modules (`"type": "module"`) | `import miki from 'miki-template'` or `import { render } from 'miki-template'` |
+| TypeScript /Bun | Same as ESM — `import` syntax works directly |
+
+> **Tip:** If your project is ESM-only (no `"type"` field but using `.mjs` files), use named imports: `import { render, compile } from 'miki-template'`.
+
+## Verifying the Installation
+
+=== "CommonJS"
+
+    ```javascript
+    const miki = require('miki-template');
+    console.log(miki.render('Hello {{ name }}!', { name: 'World' }));
+    // Output: Hello World!
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { render } from 'miki-template';
+    console.log(render('Hello {{ name }}!', { name: 'World' }));
+    // Output: Hello World!
+    ```
+
+=== "Bun / TypeScript"
+
+    ```typescript
+    import { render } from 'miki-template';
+    console.log(render('Hello {{ name }}!', { name: 'World' }));
+    // Output: Hello World!
+    ```
+
+## Troubleshooting
+
+### "Cannot find module 'miki-template'"
+
+Ensure the package is installed in the correct `node_modules` directory. If you're working in a monorepo, run `npm install` from the package root.
+
+### Auto-escaping produces `&` where you expect `&`
+
+This is by design — miki-template escapes all variables by default to prevent XSS. Use `|safe` or `markSafe()` for trusted HTML:
+
+```html
+{{ htmlContent|safe }}
+```
+
+See [Security](./security) for details.
+
+## Next Steps
+
+- [Quick Start](./quick-start)
+- [What is miki-template?](./what-is-miki-template)

package/docs/guide/partial-templates.md

@@ -0,0 +1,367 @@
+# Partial Templates
+
+Partial templates let you define reusable UI chunks once and render them anywhere. This is especially powerful with HTMX, Turbo, or any AJAX-style partial response pattern.
+
+## Table of Contents
+
+- [Defining Partials](#defining-partials)
+- [Rendering Partials by Name](#rendering-partials-by-name)
+- [Nested Partials](#nested-partials)
+- [Partials with Context](#partials-with-context)
+- [Partials with Include](#partials-with-include)
+- [Rendering Partials Programmatically](#rendering-partials-programmatically)
+- [Express Partial Rendering](#express-partial-rendering)
+- [Common Pitfalls](#common-pitfalls)
+
+---
+
+## Defining Partials
+
+Use `{% partialdef %}` to define a named partial inside any template:
+
+```html
+<!-- views/home.html -->
+{% partialdef card %}
+  <div class="card">
+    <h3>{{ title|default:"Untitled" }}</h3>
+    <p>{{ body|truncatewords:30 }}</p>
+    {% if featured %}<em>Featured</em>{% endif %}
+  </div>
+{% endpartialdef %}
+
+{% for entry in entries %}
+  {% partial card with title=entry.title body=entry.body featured=entry.featured %}
+{% endfor %}
+```
+
+### Inline Partials
+
+A `{% partialdef %}` block renders its body inline where it is defined **and** registers itself for later use:
+
+```html
+{% partialdef notice %}
+  <div class="alert">{{ message }}</div>
+{% endpartialdef %}
+```
+
+This means you get immediate output and a reusable partial in one declaration.
+
+Use the `inline` option explicitly:
+
+```html
+{% partialdef greeting inline %}
+  Hello {{ name }}!
+{% endpartialdef %}
+<!-- Above line ALSO outputs "Hello World!" when rendered -->
+```
+
+## Rendering Partials by Name
+
+Once defined, you can render a partial by name from your routes using the `view#partial` syntax:
+
+=== "CommonJS"
+
+    ```javascript
+    const express = require('express');
+    const miki = require('miki-template');
+
+    const app = express();
+    miki.setupExpress(app, { extension: 'html', views: './views' });
+
+    app.get('/card/:id', (req, res) =>
+      res.render(`home#card`, { title: 'Hello', body: 'World...', featured: true })
+    );
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import express from 'express';
+    import miki from 'miki-template';
+
+    const app = express();
+    miki.setupExpress(app, { extension: 'html', views: './views' });
+
+    app.get('/card/:id', (req, res) =>
+      res.render(`home#card`, { title: 'Hello', body: 'World...', featured: true })
+    );
+    ```
+
+The syntax is `viewName#partialName`. The engine resolves the file, extracts the named partial, and renders only that block.
+
+**Real-world HTMX example:**
+
+```html
+<!-- views/products.html -->
+{% partialdef product_card %}
+  <div class="product-card" id="product-{{ product.id }}">
+    <img src="{{ product.image|static }}" alt="{{ product.name }}">
+    <h3>{{ product.name|capfirst }}</h3>
+    <p class="price">${{ product.price|floatformat:2 }}</p>
+    <button hx-post="/cart/add/{{ product.id }}" hx-swap="outerHTML">
+      Add to Cart
+    </button>
+  </div>
+{% endpartialdef %}
+
+{% for product in products %}
+  {% partial product_card with product=product %}
+{% endfor %}
+```
+
+```javascript
+// The entire page renders all cards
+app.get('/shop', (req, res) =>
+  res.render('products', { products: catalog })
+);
+
+// HTMX swaps just one card after an action
+app.post('/cart/add/:id', (req, res) =>
+  res.render('products#product_card', {
+    product: catalog.find(p => p.id == req.params.id)
+  })
+);
+```
+
+## Nested Partials
+
+Partials can call other partials:
+
+```html
+{% partialdef header %}
+  <div class="card-header">
+    <h3>{{ title }}</h3>
+  </div>
+{% endpartialdef %}
+
+{% partialdef card %}
+  <div class="card">
+    {% partial header with title=title %}
+    <p>{{ body }}</p>
+  </div>
+{% endpartialdef %}
+```
+
+## Partials with Context
+
+By default, partials inherit the parent context. Use `with` to pass explicit values:
+
+```html
+{% partial card with title="Hello" body="World" %}
+```
+
+You can also pass context variables:
+
+```html
+{% partial card with title=entry.title body=entry.body %}
+```
+
+## Partials with Include
+
+You can include a partial from another template file using the `#partialName` syntax:
+
+```html
+{% include "header.html#partial_name" %}
+```
+
+This loads `header.html`, registers all its partials, and renders only the named one.
+
+**Real-world navigation include:**
+
+```html
+<!-- views/nav.html -->
+{% partialdef navigation %}
+  <nav>
+    {% for link in links %}
+      <a href="{{ link.url }}" class="{% if link.active %}current{% endif %}">{{ link.label }}</a>
+    {% endfor %}
+  </nav>
+{% endpartialdef %}
+```
+
+```html
+<!-- In any template -->
+{% include "nav.html#navigation" with links=nav_links %}
+```
+
+## Rendering Partials Programmatically
+
+### renderPartialFromSource
+
+Render a named partial from a template source string:
+
+=== "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' });
+    ```
+
+### renderPartialFromFile
+
+Render a named partial from a template file:
+
+=== "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' });
+    ```
+
+### compiled.renderPartial
+
+Render a partial from a compiled template:
+
+=== "CommonJS"
+
+    ```javascript
+    const { compile } = require('miki-template');
+
+    const compiled = compile('<h1>{{ title }}</h1>', { views: './templates' });
+    const html = compiled.renderPartial('card', { title: 'Hello' });
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { compile } from 'miki-template';
+
+    const compiled = compile('<h1>{{ title }}</h1>', { views: './templates' });
+    const html = compiled.renderPartial('card', { title: 'Hello' });
+    ```
+
+### compiled.renderBlock
+
+Render a single block from a compiled template — useful for AJAX responses:
+
+=== "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);
+    ```
+
+## Express Partial Rendering
+
+### res.render with `#partial`
+
+When using `setupExpress()`, you can render partials directly:
+
+=== "CommonJS"
+
+    ```javascript
+    app.get('/card/:id', (req, res) =>
+      res.render(`home#card`, { title: 'Hello', body: '...' })
+    );
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    app.get('/card/:id', (req, res) =>
+      res.render(`home#card`, { title: 'Hello', body: '...' })
+    );
+    ```
+
+### res.renderPartial middleware
+
+If you don't want to patch `res.render`, add the partial renderer middleware instead:
+
+=== "CommonJS"
+
+    ```javascript
+    const express = require('express');
+    const miki = require('miki-template');
+
+    const app = express();
+    app.use(miki.expressPartialRenderer());
+
+    app.get('/card', (req, res) =>
+      res.renderPartial('home#card', { user: req.user })
+    );
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import express from 'express';
+    import miki from 'miki-template';
+
+    const app = express();
+    app.use(miki.expressPartialRenderer());
+
+    app.get('/card', (req, res) =>
+      res.renderPartial('home#card', { user: req.user })
+    );
+    ```
+
+## Partial API Reference
+
+### renderPartialFromSource(fileContent, partialName, contextObj, options, filePath?)
+
+Render a named partial from a template source string.
+
+| 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 |
+
+### renderPartialFromFile(fileName, partialName, contextObj, options)
+
+Render a named partial from a template file.
+
+| 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 |
+
+## Common Pitfalls
+
+| Issue | Symptom | Fix |
+|-------|---------|-----|
+| Missing partial name | `{% partial %}` renders nothing | Ensure the name matches a defined `partialdef`. |
+| Variable not found | Appears empty | Variables are resolved in the current context; use `with` to pass explicit values. |
+| Inline vs non-inline confusion | Duplicate output | Use `inline` only when you want immediate rendering at the declaration site. |
+| Partial leaks across includes | Unexpected partials available | `include "file#partial"` isolates partials; `include "file"` (full) makes all partials available. |
+
+## Next Steps
+
+- [Template Inheritance](./template-inheritance)
+- [Tags: partialdef and partial](./tags#partial-tags)
+- [API Reference: renderPartial](../api/render-partial)