miki-template 1.2.0

package/docs/usage.md

@@ -0,0 +1,599 @@
+# Usage Guide
+
+This guide covers all usage patterns for **miki-template**, from basic variable rendering to advanced Express integration.
+
+---
+
+## Quick Reference
+
+### One-off Rendering
+
+**CommonJS:**
+```javascript
+const { render } = require('miki-template');
+
+const output = render('Hello {{ name }}!', { name: 'World' });
+// → "Hello World!"
+```
+
+**ESM:**
+```javascript
+import { render } from 'miki-template';
+
+const output = render('Hello {{ name }}!', { name: 'World' });
+// → "Hello World!"
+```
+
+### Compiled Templates (recommended for repeated use)
+
+**CommonJS:**
+```javascript
+const { compile } = require('miki-template');
+
+const template = compile('Welcome, {{ user.name }}!');
+
+// Render 1
+console.log(template.render({ user: { name: 'Alice' } }));
+// → "Welcome, Alice!"
+
+// Render 2
+console.log(template.render({ user: { name: 'Bob' } }));
+// → "Welcome, Bob!"
+```
+
+**ESM:**
+```javascript
+import { compile } from 'miki-template';
+
+const template = compile('Welcome, {{ user.name }}!');
+
+console.log(template.render({ user: { name: 'Alice' } }));
+// → "Welcome, Alice!"
+
+console.log(template.render({ user: { name: 'Bob' } }));
+// → "Welcome, Bob!"
+```
+
+---
+
+## Variables and Lookups
+
+### Basic Variables
+
+```html
+<p>Hello, {{ name }}!</p>
+```
+
+### Dotted Lookups (nested properties)
+
+```html
+<p>{{ user.profile.displayName }}</p>
+<p>{{ config.site.title }}</p>
+```
+
+### Array Indexing
+
+```html
+<p>First item: {{ items.0 }}</p>
+<p>Third item: {{ items.2 }}</p>
+```
+
+### Function Call
+
+If a resolved value is a function, it is called automatically with zero arguments:
+
+```javascript
+// Context: { user: { getName: () => 'Miki' } }
+{{ user.getName }}  // → "Miki"
+```
+
+---
+
+## Filters
+
+Filters transform variable output. Apply them with the pipe `|` character:
+
+```html
+{{ name|upper }}                    → "MIKI"
+{{ title|slugify }}                  → "hello-world"
+{{ text|truncatewords:20 }}          → truncated to 20 words
+{{ date|date:"Y-m-d" }}             → "2026-08-31"
+{{ user.name|default:"Anonymous" }}  → "Miki" or "Anonymous"
+```
+
+### Filter Chaining
+
+Filters apply left-to-right:
+
+```html
+{{ name|lower|capfirst }}            → "miki" → "Miki"
+{{ bio|striptags|truncatewords:50 }} → strip HTML, then truncate
+{{ price|floatformat:2|add:10 }}     → format, then add 10
+```
+
+### Filter Arguments
+
+Most filters accept optional arguments after a colon:
+
+```html
+{{ items|join:", " }}               → "a, b, c"
+{{ text|truncatewords:10 }}         → 10 words max
+{{ date|date:"F j, Y" }}           → "August 31, 2026"
+{{ value|default:"N/A" }}          → fallback if falsy
+```
+
+---
+
+## Control Flow Tags
+
+### `{% if %} / {% elif %} / {% else %} / {% endif %}`
+
+```html
+{% if user.is_active %}
+  <p>Welcome back!</p>
+{% elif user.is_pending %}
+  <p>Please verify your email.</p>
+{% else %}
+  <p>Contact support.</p>
+{% endif %}
+```
+
+Supported operators: `==`, `!=`, `<`, `<=`, `>`, `>=`, `and`, `or`, `not`, `in`, `not in`
+
+```html
+{% if user.role == 'admin' or user.is_staff %}
+  <a href="/admin">Admin Panel</a>
+{% endif %}
+
+{% if item in cart_items %}
+  <span>In cart</span>
+{% endif %}
+
+{% if not user.is_banned %}
+  <p>You may post.</p>
+{% endif %}
+```
+
+### `{% for %} / {% empty %} / {% endfor %}`
+
+Loop over arrays:
+
+```html
+<ul>
+  {% for item in items %}
+    <li>{{ item }}</li>
+  {% empty %}
+    <li>No items found.</li>
+  {% endfor %}
+</ul>
+```
+
+Loop with unpacking (arrays):
+
+```html
+{% for name, index in items %}
+  {{ forloop.counter }}. {{ name }}
+{% endfor %}
+```
+
+Loop over objects (key, value):
+
+```html
+{% for key, value in config %}
+  <tr>
+    <td>{{ key }}</td>
+    <td>{{ value }}</td>
+  </tr>
+{% endfor %}
+```
+
+Loop metadata (`forloop`):
+
+```html
+{% for item in items %}
+  {% if forloop.first %}<ul>{% endif %}
+  <li>{% if forloop.last %}last!{% else %}{{ item }}{% endif %}</li>
+  {% if forloop.last %}</ul>{% endif %}
+{% endfor %}
+```
+
+Available `forloop` properties:
+| Property | Description |
+|----------|-------------|
+| `forloop.counter` | 1-indexed position |
+| `forloop.counter0` | 0-indexed position |
+| `forloop.revcounter` | Countdown from end (1-indexed) |
+| `forloop.revcounter0` | Countdown from end (0-indexed) |
+| `forloop.first` | `true` on first iteration |
+| `forloop.last` | `true` on last iteration |
+| `forloop.parentloop` | Reference to parent loop's metadata |
+
+Nested loops:
+
+```html
+{% for group in groups %}
+  {% for item in group.items %}
+    {{ forloop.parentloop.counter }}.{{ forloop.counter }}: {{ item }}
+  {% endfor %}
+{% endfor %}
+```
+
+### `{% with %} / {% endwith %}`
+
+Create scoped aliases:
+
+```html
+{% with user.profile.address as addr %}
+  <p>{{ addr.city }}, {{ addr.country }}</p>
+{% endwith %}
+
+{% with a=x b=y c=z %}
+  {{ a }} + {{ b }} + {{ c }}
+{% endwith %}
+```
+
+### `{% cycle %}`
+
+Cycle through values on each iteration:
+
+```html
+{% for row in rows %}
+  <tr class="{% cycle 'row-even' 'row-odd' %}">
+    <td>{{ row.name }}</td>
+  </tr>
+{% endfor %}
+```
+
+Cycle with named state:
+
+```html
+{% for item in items %}
+  {% cycle 'row1' 'row2' as row_class %}
+  <tr class="{{ row_class }}">{{ item }}</tr>
+{% endfor %}
+```
+
+### `{% firstof %}`
+
+Return the first truthy value:
+
+```html
+{% firstof user.display_name user.username "Guest" %}
+<!-- Returns first non-falsy value -->
+```
+
+---
+
+## Template Inheritance
+
+### Base Template
+
+```html
+<!-- base.html -->
+<html>
+<head>
+  <title>{% block title %}Default Title{% endblock %}</title>
+  {% block extra_head %}{% endblock %}
+</head>
+<body>
+  <header>{% block header %}Site Header{% endblock %}</header>
+  <main>{% block content %}{% endblock %}</main>
+  <footer>{% block footer %}{% endblock %}</footer>
+</body>
+</html>
+```
+
+### Child Template
+
+```html
+<!-- home.html -->
+{% extends "base.html" %}
+
+{% block title %}Home Page{% endblock %}
+
+{% block content %}
+  <h1>Welcome!</h1>
+  {{ block.super }}  <!-- renders parent's block content -->
+{% endblock %}
+```
+
+`{{ block.super }}` renders the parent template's block content within the override.
+
+### Multi-level Inheritance
+
+```
+base.html
+  └── base_blog.html   {% extends "base.html" %}
+        └── post.html {% extends "base_blog.html" %}
+```
+
+---
+
+## Include and Partials
+
+### `{% include %}`
+
+Include another template file:
+
+```html
+{% include "header.html" %}
+{% include "sidebar.html" with active="home" %}
+{% include user.theme|add:".html" %}  <!-- dynamic template name -->
+```
+
+Path traversal is blocked for security.
+
+### `{% partialdef %} / {% partial %}`
+
+Define and render reusable partial snippets within a template:
+
+```html
+{% partialdef card %}
+  <div class="card">
+    <h3>{{ title }}</h3>
+    <p>{{ description }}</p>
+  </div>
+{% endpartialdef %}
+
+{% partial card with title="Hello" description="World" %}
+{% partial card with title="Foo" description="Bar" %}
+```
+
+Inline partials render immediately:
+
+```html
+{% partialdef greeting inline %}
+  Hello {{ name }}!
+{% endpartialdef %}
+<!-- Output: "Hello !" (name not yet defined) -->
+```
+
+### Programmatic Partial Rendering
+
+```javascript
+const { compile } = require('miki-template');
+
+const template = `{% partialdef my_partial %}Hello {{ who }}!{% endpartialdef %}`;
+const compiled = compile(template);
+
+console.log(compiled.renderPartial('my_partial', { who: 'World' }));
+// → "Hello World!"
+```
+
+---
+
+## Block Partial Rendering (HTMX / AJAX)
+
+Render a specific block from a compiled template for AJAX responses:
+
+```javascript
+const { compile } = require('miki-template');
+
+const template = compile(`
+  {% extends "base.html" %}
+  {% block main %}
+    <h1>{{ title }}</h1>
+    <div class="content">{{ content }}</div>
+  {% endblock %}
+`, { views: './templates' });
+
+// Full page render
+res.send(template.render({ title: 'Home', content: '...' }));
+
+// Partial render — only the 'main' block
+res.send(template.renderBlock('main', { title: 'Home', content: '...' }));
+```
+
+---
+
+## Async Rendering
+
+For templates with async helpers (database lookups, API calls):
+
+```javascript
+const { asyncRender, registerHelper } = require('miki-template');
+
+registerHelper('fetch-user', async (content, ctx) => {
+  const userId = content.trim();
+  const user = await db.users.findById(userId);
+  return `User: ${user.name}`;
+});
+
+// Template: {% fetch-user %}123{% endfetch-user %}
+const html = await asyncRender(template, { db });
+```
+
+---
+
+## Express Integration
+
+### Basic Setup
+
+```javascript
+const express = require('express');
+const { __express } = require('miki-template');
+
+const app = express();
+
+app.engine('html', __express);
+app.set('view engine', 'html');
+app.set('views', './views');
+
+app.get('/', (req, res) => {
+  res.render('home', {
+    title: 'My Site',
+    user: req.user,
+    items: ['a', 'b', 'c']
+  });
+});
+
+app.listen(3000);
+```
+
+### Async Express Views
+
+Express 5+ supports async route handlers natively:
+
+```javascript
+app.get('/user/:id', async (req, res) => {
+  const user = await User.findById(req.params.id);
+  if (!user) return res.status(404).send('Not found');
+  res.render('user-profile', { user });
+});
+```
+
+---
+
+## Context Processors
+
+Context processors inject variables into every template render, like Django's custom context processors.
+
+```javascript
+const { registerContextProcessor } = require('miki-template');
+
+// Inject site-wide variables
+registerContextProcessor(() => ({
+  site_name: 'MyApp',
+  current_year: new Date().getFullYear()
+}));
+
+// Access request-specific data
+registerContextProcessor((ctx) => ({
+  is_authenticated: ctx.user !== null,
+  user_display: ctx.user ? ctx.user.name : 'Guest'
+}));
+```
+
+Now `{{ site_name }}` and `{{ current_year }}` are available in every template automatically.
+
+---
+
+## Security
+
+### Auto-escaping
+
+HTML auto-escaping is **enabled by default**. All variable output is escaped:
+
+```html
+{{ user_input }}  → &lt;script&gt;alert()&lt;/script&gt;
+```
+
+### Marking Values as Safe
+
+Use `|safe` for trusted HTML content:
+
+```html
+{{ trusted_html|safe }}
+```
+
+In JavaScript:
+
+```javascript
+const { markSafe } = require('miki-template');
+
+res.render('email', {
+  body: markSafe('<b>Welcome!</b>')  // Won't be escaped
+});
+```
+
+### CSRF Protection
+
+```html
+<form method="post">
+  {% csrf_token %}
+  <!-- renders: <input type="hidden" name="csrfmiddlewaretoken" value="..."> -->
+  ...
+</form>
+```
+
+Provide `csrf_token` in context:
+
+```javascript
+res.render('form', { csrf_token: req.csrfToken() });
+```
+
+### CSP Nonce
+
+```html
+<script {% csp_nonce %} src="/app.js"></script>
+```
+
+Provide `csp_nonce` in context:
+
+```javascript
+res.render('page', { csp_nonce: res.locals.nonce });
+```
+
+---
+
+## Static Files and URLs
+
+Configure the static URL prefix:
+
+```javascript
+compile(template, { staticUrl: '/static/assets/' });
+```
+
+Then in templates:
+
+```html
+<img src="{% static "images/logo.png" %}" alt="Logo">
+<!-- → /static/assets/images/logo.png -->
+
+<script src="{% static "js/app.js" %}"></script>
+```
+
+### URL Resolution
+
+```javascript
+compile(template, {
+  urlHelper: (routeName, ...args) => {
+    const routes = {
+      'home': '/',
+      'user-profile': (id) => `/users/${id}`
+    };
+    const handler = routes[routeName];
+    return typeof handler === 'function' ? handler(...args) : handler;
+  }
+});
+```
+
+```html
+<a href="{% url "home" %}">Home</a>
+<a href="{% url "user-profile" user.id %}">Profile</a>
+```
+
+---
+
+## Error Handling
+
+### Unclosed Tags
+
+Unclosed block tags produce an error:
+
+```html
+{% if user.is_active %}
+  <p>Active</p>
+<!-- Missing {% endif %} → throws "Unexpected end of template"
+```
+
+### Missing Partial
+
+```html
+{% partial missing_name %}
+<!-- throws: Partial 'missing_name' not found -->
+```
+
+### Missing Block
+
+```javascript
+template.renderBlock('nonexistent', {});
+// throws: Block 'nonexistent' not found in template
+```
+
+### Path Traversal Protection
+
+```html
+{% include "../etc/passwd" %}
+<!-- throws: Include tag attempted path traversal outside allowed views -->
+```

package/eslint.config.mjs

@@ -0,0 +1,34 @@
+export default [
+  {
+    files: ['src/**/*.js'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'commonjs',
+      globals: {
+        Buffer: 'readonly',
+        console: 'readonly',
+        exports: 'readonly',
+        module: 'readonly',
+        process: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        require: 'readonly',
+        setTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearTimeout: 'readonly',
+        clearInterval: 'readonly',
+        setImmediate: 'readonly',
+        clearImmediate: 'readonly',
+        global: 'readonly'
+      }
+    },
+    rules: {
+      'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+      'no-console': 'off',
+      'no-undef': 'error',
+      'semi': ['error', 'always'],
+      'quotes': ['error', 'single'],
+      'indent': ['error', 2]
+    }
+  }
+];

package/miki-template-extension/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 miki-template contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.