miki-template 2.0.0 → 2.2.2

package/docs/installation.md

@@ -1,106 +0,0 @@
-# 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,79 +0,0 @@
-# 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`.
-
-## Recursive and app-style template discovery
-
-`miki-template` now supports Django-style recursive template discovery. When you configure your views directory (via `miki.setupExpress(app, { views: './views' })` or by passing `views` to `render()`), the engine will:
-
-- Resolve direct paths like `nested/index` relative to each `views` directory.
-- If a bare template name (e.g. `card`) is used, recursively scan subfolders of the configured `views` directories to find `card.html` or `card.miki`.
-- Discover app-style `templates` directories located under application packages (e.g. `project/apps/product/templates/...`) and include them in the search.
-
-Configuration:
-
-- Programmatically set which folder names should be treated as app template roots via the API:
-
-	- `setAppTemplateDirNames(['templates', 'site_templates'])` — sets the list of folder names that will be discovered under the views root.
-	- `getAppTemplateDirNames()` — returns the current list.
-
-Examples:
-
-	- `render('home#card', ctx, { views: './views' })` will search `./views` and any `templates/` subfolders for `home.html` or `home.miki`, and render the `card` partial.
-	- If your project places templates under `packages/product/templates/detail.html`, `render('detail', ..., { views: './views' })` will find it automatically.
-
-This behavior is opt‑out by simply clearing the app-dir names: `setAppTemplateDirNames([])` will disable app-style discovery.
-
-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,70 +0,0 @@
-# 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 +0,0 @@
-# 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`.