miki-template 1.2.0 → 1.3.6

package/docs/installation.md

@@ -1,106 +1,106 @@
-# Installation
-
-## npm
-```bash
-npm install miki-template
-```
-
-## Prerequisites
-- **Node.js** >= 14 (ES6+ support)
-- **npm** (or **yarn**) for package management
-
-## Optional dependencies
-- **express** – for server‑side rendering integration (recommended).
-- **eslint** – for linting your project (dev dependency).
-
-## Module System Support
-
-`miki-template` supports both **CommonJS** (`require`) and **ESM** (`import`).
-
-### CommonJS (CJS)
-
-```js
-const { render, compile, __express, SafeString, markSafe } = require('miki-template');
-```
-
-### ES Modules (ESM)
-
-```js
-// Named imports
-import { render, compile, __express, SafeString, markSafe } from 'miki-template';
-
-// Default import (all exports)
-import miki from 'miki-template';
-const result = miki.render('Hello {{ name }}', { name: 'World' });
-```
-
-> **Note:** When using ESM in Node.js, either name your files `.mjs` or set `"type": "module"` in your `package.json`.
-
-## Publishing to npm
-
-This project is configured for automatic npm publishing via GitHub Actions. When you push to `main`, the CI workflow runs tests and, if they pass, publishes the package to npm.
-
-### Prerequisites for publishing
-
-1. You must have an npm account and be a maintainer of the `miki-template` package on npm.
-2. In your GitHub repository, go to **Settings → Secrets and variables → Actions**.
-3. Add a new repository secret named `NPM_TOKEN` with your npm automation token.
-   - Generate it at https://www.npmjs.com/settings/YOUR_USERNAME/tokens
-   - Select **Automation** as the token type.
-
-The CI workflow will then automatically publish on every push to `main`.
-
-### Manual publishing
-
-```bash
-npm version patch   # or minor/major
-npm publish --access public
-```
-
----
-
-## Quick Start
-
-### 1. Add the engine to your project
-
-**CJS:**
-```js
-const { render, compile } = require('miki-template');
-```
-
-**ESM:**
-```js
-import { render, compile } from 'miki-template';
-```
-
-### 2. (Express) Register the view engine
-
-**CJS:**
-```js
-const express = require('express');
-const { __express: renderDtpl } = require('miki-template');
-const app = express();
-app.engine('html', renderDtpl);
-app.set('view engine', 'html');
-app.set('views', './views');
-```
-
-**ESM:**
-```js
-import express from 'express';
-import { __express as renderDtpl } from 'miki-template';
-
-const app = express();
-app.engine('html', renderDtpl);
-app.set('view engine', 'html');
-app.set('views', './views');
-```
-
-### 3. Run the test suite to verify
-
-```bash
-npm test
-```
-
----
-
+# Installation
+
+## npm
+```bash
+npm install miki-template
+```
+
+## Prerequisites
+- **Node.js** >= 14 (ES6+ support)
+- **npm** (or **yarn**) for package management
+
+## Optional dependencies
+- **express** – for server‑side rendering integration (recommended).
+- **eslint** – for linting your project (dev dependency).
+
+## Module System Support
+
+`miki-template` supports both **CommonJS** (`require`) and **ESM** (`import`).
+
+### CommonJS (CJS)
+
+```js
+const { render, compile, __express, SafeString, markSafe } = require('miki-template');
+```
+
+### ES Modules (ESM)
+
+```js
+// Named imports
+import { render, compile, __express, SafeString, markSafe } from 'miki-template';
+
+// Default import (all exports)
+import miki from 'miki-template';
+const result = miki.render('Hello {{ name }}', { name: 'World' });
+```
+
+> **Note:** When using ESM in Node.js, either name your files `.mjs` or set `"type": "module"` in your `package.json`.
+
+## Publishing to npm
+
+This project is configured for automatic npm publishing via GitHub Actions. When you push to `main`, the CI workflow runs tests and, if they pass, publishes the package to npm.
+
+### Prerequisites for publishing
+
+1. You must have an npm account and be a maintainer of the `miki-template` package on npm.
+2. In your GitHub repository, go to **Settings → Secrets and variables → Actions**.
+3. Add a new repository secret named `NPM_TOKEN` with your npm automation token.
+   - Generate it at https://www.npmjs.com/settings/YOUR_USERNAME/tokens
+   - Select **Automation** as the token type.
+
+The CI workflow will then automatically publish on every push to `main`.
+
+### Manual publishing
+
+```bash
+npm version patch   # or minor/major
+npm publish --access public
+```
+
+---
+
+## Quick Start
+
+### 1. Add the engine to your project
+
+**CJS:**
+```js
+const { render, compile } = require('miki-template');
+```
+
+**ESM:**
+```js
+import { render, compile } from 'miki-template';
+```
+
+### 2. (Express) Register the view engine
+
+**CJS:**
+```js
+const express = require('express');
+const { __express: renderDtpl } = require('miki-template');
+const app = express();
+app.engine('html', renderDtpl);
+app.set('view engine', 'html');
+app.set('views', './views');
+```
+
+**ESM:**
+```js
+import express from 'express';
+import { __express as renderDtpl } from 'miki-template';
+
+const app = express();
+app.engine('html', renderDtpl);
+app.set('view engine', 'html');
+app.set('views', './views');
+```
+
+### 3. Run the test suite to verify
+
+```bash
+npm test
+```
+
+---
+

package/docs/overview.md

@@ -1,57 +1,57 @@
-# Overview
-
-Welcome to **miki-template** – a production‑ready, Django‑style template engine for Node.js and Express. This documentation mirrors the layout of popular open‑source libraries (e.g., Django, Jinja2, Mustache) and provides a clear, hierarchical guide for developers of all skill levels.
-
-- **Project structure** – quick glance at the repository layout.
-- **Feature list** – exhaustive rundown of supported tags, filters, security helpers, and the new `partialdef` system.
-- **Getting started** – installation, basic rendering, and Express integration.
-- **Advanced usage** – inheritance, block rendering, custom tags/filters, and performance tips.
-
----
-
-## Repository layout
-
-```
-📦 miki-template/
-├─ 📁 src/               # Core engine source files
-│  ├─ index.js           # Entry point, compile/render APIs
-│  ├─ lexer.js           # Tokenizer
-│  ├─ parser.js          # AST builder
-│  ├─ context.js         # Scope & partial registry
-│  └─ tags/              # Built‑in tag parsers (control, inheritance, util)
-│     ├─ control.js      # if, for, with, cycle, partialdef, …
-│     ├─ inheritance.js # extends, block, super
-│     └─ util.js         # comment, verbatim, etc.
-├─ 📁 filters/           # Built‑in filter implementations
-├─ 📁 tests/             # Jest‑style test suite
-├─ 📁 docs/              # 📖 Documentation (this folder)
-├─ README.md            # Project landing page (high‑level intro)
-├─ AGENT.md             # Agent guardrails (internal)
-├─ ROADMAP.md           # Future roadmap & milestones
-└─ package.json         # npm package definition
-```
-
-Each module is deliberately **single‑responsibility** and fully typed via JSDoc comments, making it easy to extend.
-
----
-
-## Where to start
-
-- **Installation** – see `docs/installation.md`.
-- **Basic rendering** – see `docs/usage.md`.
-- **Tag reference** – see `docs/tags.md`.
-- **Filter reference** – see `docs/filters.md`.
-- **Partial definitions** – see `docs/partialdef.md`.
-- **Security considerations** – see `docs/security.md`.
-
-For API‑level details (e.g., `compile().renderPartial`) check `docs/api.md`.
-
----
-
-## Contributing
-
-We follow the standard open‑source workflow. Details are in `docs/contributing.md`.
-
----
-
-> **Tip**: All documentation files are located under `c:/Users/Coder Miki/Desktop/miki-template/docs/`.
+# Overview
+
+Welcome to **miki-template** – a production‑ready, Django‑style template engine for Node.js and Express. This documentation mirrors the layout of popular open‑source libraries (e.g., Django, Jinja2, Mustache) and provides a clear, hierarchical guide for developers of all skill levels.
+
+- **Project structure** – quick glance at the repository layout.
+- **Feature list** – exhaustive rundown of supported tags, filters, security helpers, and the new `partialdef` system.
+- **Getting started** – installation, basic rendering, and Express integration.
+- **Advanced usage** – inheritance, block rendering, custom tags/filters, and performance tips.
+
+---
+
+## Repository layout
+
+```
+📦 miki-template/
+├─ 📁 src/               # Core engine source files
+│  ├─ index.js           # Entry point, compile/render APIs
+│  ├─ lexer.js           # Tokenizer
+│  ├─ parser.js          # AST builder
+│  ├─ context.js         # Scope & partial registry
+│  └─ tags/              # Built‑in tag parsers (control, inheritance, util)
+│     ├─ control.js      # if, for, with, cycle, partialdef, …
+│     ├─ inheritance.js # extends, block, super
+│     └─ util.js         # comment, verbatim, etc.
+├─ 📁 filters/           # Built‑in filter implementations
+├─ 📁 tests/             # Jest‑style test suite
+├─ 📁 docs/              # 📖 Documentation (this folder)
+├─ README.md            # Project landing page (high‑level intro)
+├─ AGENT.md             # Agent guardrails (internal)
+├─ ROADMAP.md           # Future roadmap & milestones
+└─ package.json         # npm package definition
+```
+
+Each module is deliberately **single‑responsibility** and fully typed via JSDoc comments, making it easy to extend.
+
+---
+
+## Where to start
+
+- **Installation** – see `docs/installation.md`.
+- **Basic rendering** – see `docs/usage.md`.
+- **Tag reference** – see `docs/tags.md`.
+- **Filter reference** – see `docs/filters.md`.
+- **Partial definitions** – see `docs/partialdef.md`.
+- **Security considerations** – see `docs/security.md`.
+
+For API‑level details (e.g., `compile().renderPartial`) check `docs/api.md`.
+
+---
+
+## Contributing
+
+We follow the standard open‑source workflow. Details are in `docs/contributing.md`.
+
+---
+
+> **Tip**: All documentation files are located under `c:/Users/Coder Miki/Desktop/miki-template/docs/`.

package/docs/partialdef.md

@@ -1,41 +1,70 @@
-# Partial Definition (`partialdef`)
-
-`partialdef` is the cornerstone feature that brings Django‑style **named template fragments** to Node.js. It allows you to define a reusable block once and render it multiple times, optionally **inline** for immediate output.
-
-## Syntax
-```html
-{% partialdef name [inline] %}
-  ...template code...
-{% endpartialdef %}
-```
-- `name` – identifier used with `{% partial name %}`.
-- Optional `inline` – if present, the block is rendered **where it is defined**; no separate `{% partial %}` call is required.
-
-## Rendering a Partial
-```html
-{% partial greeting %}
-```
-The engine looks up the definition in the current rendering **Context** (`context.partialDefs`) and injects the rendered output.
-
-## API Usage
-```js
-const tpl = `{% partialdef api %}API {{ data }}{% endpartialdef %}`;
-const compiled = compile(tpl);
-const out = compiled.renderPartial('api', { data: 123 }); // "API 123"
-```
-
-## Features
-- **Full tag parity** – conditionals (`if`), loops (`for`), variable scoping (`with`) work inside a `partialdef`.
-- **Nested partials** – you can define a partial inside another; inner definitions are registered first and can be used by the outer.
-- **Scope isolation** – each rendering of a partial receives its own scope, mirroring Django’s behavior.
-- **Inline rendering** – render inline without an extra `{% partial %}` tag (`{% partialdef foo inline %}…{% endpartialdef %}`).
-- **Performance** – partials are compiled once per template; subsequent renders reuse the compiled AST.
-
-## 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 %}` inside the partial if you need a local alias. |
-| Inline vs non‑inline confusion | Duplicate output | Use `inline` only when you want immediate rendering. |
-
-> Implementation lives in `src/tags/control.js` (class `PartialDefNode` and `PartialNode`).
+# Partial Definition (`partialdef`)
+
+`partialdef` is the cornerstone feature that brings Django‑style **named template fragments** to Node.js. It allows you to define a reusable block once and render it multiple times, optionally **inline** for immediate output. Combined with the `setupExpress` helper, partials can be served as standalone HTTP responses for HTMX-style UIs.
+
+## Syntax
+```html
+{% partialdef name [inline] %}
+  ...template code...
+{% endpartialdef %}
+```
+- `name` – identifier used with `{% partial name %}`.
+- Optional `inline` – if present, the block is rendered **where it is defined**; no separate `{% partial %}` call is required.
+
+## Rendering a Partial
+```html
+{% partial greeting %}
+```
+The engine looks up the definition in the current rendering **Context** (`context.partialDefs`) and injects the rendered output.
+
+## Including a Partial From Another File
+Use the `file#partial` syntax to include just a single named partial:
+```html
+{% include "home.html#card" with title="Hi" %}
+```
+
+## API Usage
+```js
+const tpl = `{% partialdef api %}API {{ data }}{% endpartialdef %}`;
+const compiled = compile(tpl);
+const out = compiled.renderPartial('api', { data: 123 }); // "API 123"
+```
+
+`renderPartialFromSource` and `renderPartialFromFile` are also exported at the top level:
+```js
+const miki = require('miki-template');
+miki.renderPartialFromFile('views/home.html', 'card', { user: req.user });
+miki.renderPartialFromSource(src, 'card', { user: req.user }, { views: 'views' });
+```
+
+## Serving a Partial Over HTTP (HTMX)
+With `miki.setupExpress(app, { extension: 'html', views: './views' })`, the same `res.render(...)` call you use for full pages also serves a single partial by appending `#partialName` to the view name:
+
+```javascript
+app.get('/partials/:name', (req, res) =>
+  res.render(`home#${req.params.name}`, { user: req.user })
+);
+```
+
+The same effect can be obtained via the lighter `expressPartialRenderer()` middleware:
+```javascript
+app.use(miki.expressPartialRenderer());
+app.get('/card', (req, res) => res.renderPartial('home#card', { user: req.user }));
+```
+
+## Features
+- **Full tag parity** – conditionals (`if`), loops (`for`), variable scoping (`with`) work inside a `partialdef`.
+- **Nested partials** – you can define a partial inside another; inner definitions are registered first and can be used by the outer.
+- **Scope isolation** – each rendering of a partial receives its own scope, mirroring Django’s behavior.
+- **Inline rendering** – render inline without an extra `{% partial %}` tag (`{% partialdef foo inline %}…{% endpartialdef %}`).
+- **`with` arguments** – bind extra context values when rendering: `{% partial card with title="Hello" description="World" %}`.
+- **Performance** – partials are compiled once per template; subsequent renders reuse the compiled AST.
+
+## 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 %}` inside the partial if you need a local alias. |
+| Inline vs non‑inline confusion | Duplicate output | Use `inline` only when you want immediate rendering. |
+
+> Implementation lives in `src/tags/control.js` (class `PartialDefNode` and `PartialNode`).

package/docs/security.md

@@ -1,27 +1,27 @@
-# Security
-
-`miki-template` is built with **secure defaults**. All variables are **auto‑escaped** unless explicitly marked safe.
-
-## Auto‑escaping
-- Every string output goes through `escapeHtml` before being concatenated.
-- Use the `|safe` filter or `markSafe(value)` to bypass escaping when you trust the data.
-
-## CSRF Protection
-- The `{% csrf_token %}` tag renders a hidden `<input>` containing the `csrf_token` value from the rendering context.
-- Example:
-  ```html
-  <form method="post">{% csrf_token %} ... </form>
-  ```
-- It is a thin wrapper; you must generate and store `csrf_token` in your Express middleware.
-
-## CSP Nonce
-- `{% csp_nonce_attr %}` injects `nonce="{{ csp_nonce }}"` when `csp_nonce` is present in the context.
-- Useful for inline scripts when you have a CSP policy with `script-src 'nonce-...';`.
-
-## SafeString Wrapper
-- Filters returning `SafeString` bypass auto‑escaping. The wrapper is applied automatically by the `safe` filter.
-
-## No `eval`
-- Template expressions are parsed into an AST and evaluated using a sandboxed evaluator that **never calls `eval` or `new Function`**.
-
-> Security‑related code lives in `src/security.js` and the tag implementations in `src/tags/control.js`.
+# Security
+
+`miki-template` is built with **secure defaults**. All variables are **auto‑escaped** unless explicitly marked safe.
+
+## Auto‑escaping
+- Every string output goes through `escapeHtml` before being concatenated.
+- Use the `|safe` filter or `markSafe(value)` to bypass escaping when you trust the data.
+
+## CSRF Protection
+- The `{% csrf_token %}` tag renders a hidden `<input>` containing the `csrf_token` value from the rendering context.
+- Example:
+  ```html
+  <form method="post">{% csrf_token %} ... </form>
+  ```
+- It is a thin wrapper; you must generate and store `csrf_token` in your Express middleware.
+
+## CSP Nonce
+- `{% csp_nonce_attr %}` injects `nonce="{{ csp_nonce }}"` when `csp_nonce` is present in the context.
+- Useful for inline scripts when you have a CSP policy with `script-src 'nonce-...';`.
+
+## SafeString Wrapper
+- Filters returning `SafeString` bypass auto‑escaping. The wrapper is applied automatically by the `safe` filter.
+
+## No `eval`
+- Template expressions are parsed into an AST and evaluated using a sandboxed evaluator that **never calls `eval` or `new Function`**.
+
+> Security‑related code lives in `src/security.js` and the tag implementations in `src/tags/control.js`.