mancha 0.6.4 → 0.6.6

package/README.md

@@ -1,80 +1,182 @@
 # mancha
 
-`mancha` is an HTML rendering library. It can work as a command-line tool, imported as a Javascript
-function, or as a `Gulp` plugin.
+`mancha` is a simple HTML templating and rendering library for simple people. It works on the
+browser or the server. It can be used as a command-line tool, imported as a Javascript module, or as
+a plugin for [`Gulp`](https://gulpjs.com).
 
-## Examples
-
-Here are some of the things you can use `mancha` for.
-
-### Replace simple variables using `{{ value }}` format
-
-index.html:
-
-```html
-<span>Hello {{ name }}</span>
-```
-
-Command:
-
-```bash
-npx mancha --input="./index.html" --vars='{"name": "World"}'
-```
-
-Result:
-
-```html
-<div>Hello World</div>
-```
-
-### Include files from a relative path using the `<include>` tag
-
-hello-name.html:
-
-```html
-<span>Hello {{ name }}</span>
-```
-
-index.html:
+Here's a small sample of the things that you can do with `mancha`:
 
 ```html
-<div>
-  <include src="./hello-name.html" data-name="World"></include>
-</div>
+<!-- Use the bundled file from `unkpg`. -->
+<script src="//unpkg.com/mancha" target="main" init></script>
+
+<!-- Scoped variables using the `:data` attribute. -->
+<main :data="{count: 0, name: 'Stranger'}">
+  <!-- Custom HTML tag element registration. -->
+  <template is="counter">
+    <div>
+      <slot></slot>
+      <button @click="count++">Counter: {{ count }}</button>
+    </div>
+  </template>
+
+  <!-- Custom HTML tag element usage. -->
+  <counter>Click me:</counter>
+
+  <!-- Reactive data binding. -->
+  <p>Enter your name: <input type="text" :bind="name" /></p>
+  <p>Hello, {{ name }}!</p>
+
+  <!-- Include HTML partials. -->
+  <include src="html/partial/footer.tpl.html"></include>
+</main>
 ```
 
-Command:
-
-```bash
-npx mancha --input="./index.html"
-```
-
-Result:
-
-```html
-<div>
-  <span>Hello World</span>
-</div>
-```
+## Why another front-end Javascript library?
+
+There are plenty of other front-end Javascript libraries, many of them of great quality, including:
+
+- [Google's Svelte](https://svelte.dev)
+- [Meta's React](https://react.dev)
+- [Vue.js](https://vuejs.org) and [petite-vue](https://github.com/vuejs/petite-vue)
+- [Alpine.js](https://alpinejs.dev)
+
+None of them have all the key features that make `mancha` unique:
+
+| Feature               | mancha | Svelte | React.js | Vue.js | petite-vue | Alpine.js |
+| --------------------- | ------ | ------ | -------- | ------ | ---------- | --------- |
+| Simple to learn       | ✔️     | ❌     | ❌       | ❌     | ✔️         | ✔️        |
+| < 10kb compressed     | ✔️     | ❌     | ❌       | ❌     | ✔️         | ❌        |
+| Custom web components | ✔️     | ✔️     | ✔️       | ✔️     | ❌         | ❌        |
+| Client-side rendering | ✔️     | ❌     | ❌       | ✔️     | ✔️         | ✔️        |
+| Server-side rendering | ✔️     | ✔️     | ✔️       | ✔️     | ❌         | ❌        |
+
+`mancha` is great for:
+
+- **prototyping**, just plop a script tag in your HTML and off you go
+- **testing**, individual components can be rendered and tested outside the browser
+- **progressive enhancement**, from simple templating and basic reactivity to a full-blown app
+
+A core benefit of using `mancha` is that it allows you to compartmentalize the complexity of
+front-end development. Whether you decide to break up your app into reusable partial sections via
+`<include>` or create custom web components, you can write HTML as if your mother was watching.
+
+`mancha` implements its own reactivity engine, so the bundled browser module contains no external
+dependencies.
+
+## Preprocessing
+
+As part of the rendering lifecycle, `mancha` first preprocesses the HTML. The two main stages of
+preprocessing consist of:
+
+- Resolution of `<include>` tags
+
+  ```html
+  <!-- ./button.tpl.html -->
+  <button>Click Me</button>
+
+  <!-- ./index.html -->
+  <div>
+    <include src="button.tpl.html"></include>
+  </div>
+
+  <!-- Result after rendering `index.html`. -->
+  <div>
+    <button>Click Me</button>
+  </div>
+  ```
+
+- Registration and resolution of all custom web components
+
+  ```html
+  <!-- Use <template is="my-component-name"> to register a component. -->
+  <template is="my-red-button">
+    <button style="background-color: red;">
+      <slot></slot>
+    </button>
+  </template>
+
+  <!-- Any node traversed after registration can use the component. -->
+  <my-red-button @click="console.log('clicked')">
+    <!-- The contents within will replace the `<slot></slot>` tag. -->
+    Click Me
+  </my-red-button>
+  ```
+
+## Rendering
+
+Once the HTML has been preprocessed, it is rendered by traversing every node in the DOM and applying
+a series of plugins. Each plugin is only applied if specific conditions are met such as the HTML
+element tag or attributes match a specific criteria. Here's the list of attributes handled:
+
+- `:data` provides scoped variables to all subnodes
+  ```html
+  <div :data="{name: 'Stranger'}"></div>
+  ```
+- `:for` clones the node and repeats it
+  ```html
+  <div :for="item in ['a', 'b', 'c']">{{ item }}</div>
+  ```
+- `$text` sets the `textContent` value of a node
+  ```html
+  <div :data="{foo: 'bar'}" $text="foo"></div>
+  ```
+- `$html` sets the `innerHTML` value of a node
+  ```html
+  <div $html="<span>Hello World</span>"></div>
+  ```
+- `:show` toggles `$elem.style.display` to `none`
+  ```html
+  <div :data="{foo: false}" :show="foo"></div>
+  ```
+- `@watch` executes an expression anytime its dependencies change
+  ```html
+  <div :data="{foo: 'bar'}" @watch="console.log('foo changed:', foo)"></div>
+  ```
+- `:bind` binds (two-way) a variable to the `value` or `checked` property of the element.
+  ```html
+  <div :data="{name: 'Stranger'}">
+    <input type="text" :bind="name" />
+  </div>
+  ```
+- `${prop}` binds (one-way) the node property `prop` with the given expression
+  ```html
+  <div :data="{foo: false}">
+    <input type="submit" $disabled="foo" />
+  </div>
+  ```
+- `:{attr}` binds (one-way) the node attribute `attr` with the given expression
+  ```html
+  <div :data="{foo: 'bar'}">
+    <input type="text" :placeholder="foo" />
+  </div>
+  ```
+- `@{event}` adds an event listener for `event` to the node
+  ```html
+  <button @click="console.log('clicked')"></button>
+  ```
+- `{{ value }}` replaces `value` in text nodes
+  ```html
+  <button :data="{label: 'Click Me'}">{{ label }}</button>
+  ```
 
 ## Usage
 
 ### Client Side Rendering (CSR)
 
-To use `mancha` on the client (browser), use the `mancha.js` bundled file available via `unpkg`.
+To use `mancha` on the client (browser), use the `mancha` bundled file available via `unpkg`.
 
 ```html
-<body>
+<body :data="{ name: 'John' }">
   <span>Hello, {{ name }}!</span>
 </body>
 
-<script src="//unpkg.com/mancha" data-name="John" target="body" init></script>
+<script src="//unpkg.com/mancha" target="body" defer init></script>
 ```
 
 Script tag attributes:
 
 - `init`: whether to automatically render upon script load
-- `data-name`: dataset atribute, where `data-{{key}}` will be replaced with the attribute's value
 - `target`: comma-separated document elements to render e.g. "body" or "head,body" (defaults to "body")
 
 For a more complete example, see [examples/browser](./examples/browser).
@@ -109,13 +211,20 @@ the HTML code on demand for each incoming request:
 
 ```js
 import express from "express";
-import { renderLocalPath } from "mancha";
+import { Renderer } from "mancha";
 import vars from "./vars.json";
 
 const app = express();
 
 app.get("/", async (req, res) => {
-  const html = await renderLocalPath("src/index.html", vars);
+  const name = req.query.name || "Stranger";
+  // Instantiate a new renderer.
+  const renderer = new Renderer({ name, ...vars });
+  // Preprocess input HTML from a local file path.
+  const fragment = await renderer.preprocessLocal("src/index.html");
+  // Render and serialize output HTML.
+  const html = renderer.serializeHTML(await renderer.renderNode(fragment));
+  // Send it to the client.
   res.set("Content-Type", "text/html");
   res.send(html);
 });
@@ -123,50 +232,56 @@ app.get("/", async (req, res) => {
 app.listen(process.env.PORT || 8080);
 ```
 
-For a more complete example, see [examples/rendered](./examples/rendered).
+For a more complete example, see [examples/express](./examples/express).
 
 ### Web Worker Runtime Server Side Rendering (SSR)
 
 For servers hosted as worker runtimes, such as `Cloudflare Workers`, you will need to import a
-stripped down version of `mancha` that does not have the ability to read local files. Any HTML files
-will need to be separately hosted by a static server, although you can also generate strings
-containing HTML on demand.
+stripped down version of `mancha` that does not have the ability to read local files or evaluate
+expressions. The contents of any `{{ value }}` must be an existing variable in the renderer
+instance, since string evaluation is not permitted in some runtimes.
 
 ```js
-import { renderRemotePath } from "mancha/dist/core"
-
-const VARS = {...};
-const HTML_ROOT = "https://example.com/html";
+import { Renderer } from "mancha/dist/worker";
+import htmlIndex from "./index.html";
+import vars from "./vars.json";
 
-self.addEventListener('fetch', async event => {
-  const content = await renderRemotePath(`${HTML_ROOT}/index.html`, VARS);
-  event.respondWith(new Response(content, { headers: {"Content-Type": "text/html"} }))
+self.addEventListener("fetch", async (event) => {
+  // Instantiate a new renderer.
+  const renderer = new Renderer({ ...vars });
+  // Preprocess input HTML from a string.
+  const fragment = await renderer.preprocessString(htmlIndex);
+  // Render and serialize output HTML.
+  const html = renderer.serializeHTML(await renderer.renderNode(fragment));
+  // Send it to the client.
+  event.respondWith(new Response(content, { headers: { "Content-Type": "text/html" } }));
 });
 ```
 
+To meet the size requirements of popular worker runtimes, the worker version of `mancha` uses
+`htmlparser2` instead of `jsdom` for the underlying HTML and DOM manipulation. This keeps the
+footprint of `mancha` under 100kb.
+
 For a more complete example, see [examples/wrangler](./examples/wrangler).
 
-## Compile Time `gulpfile` Scripts
+## Compile Time `Gulp` Plugin
 
-To use `mancha` in your `gulpfile`, you can do the following:
+To use `mancha` as a `Gulp` plugin in `gulpfile.js`, you can do the following:
 
 ```js
+import GulpClient from "gulp";
 import { mancha } from "mancha/dist/gulp";
-gulp.src(...).pipe(mancha({"myvar": "myval"})).pipe(...)
-```
-
-The first argument consists of a dictionary of `<key, value>` pairs of literal string replacements.
-`key` will become `{{ key }}` before replacing it with `value` in the processed files. For example,
-if we passed `{"name": "World"}` as the argument:
-
-Source:
-
-```html
-<div>Hello {{ name }}</div>
-```
-
-Result:
+import vars from "./vars.json";
 
-```html
-<div>Hello World</div>
+GulpClient.task("build", function () {
+  return (
+    GulpClient
+      // Inlcude all HTML files, but exclude all partials (ending in .tpl.html).
+      .src(["src/**/*.html", "!src/**/*.tpl/html"])
+      // Render the HTML content using `mancha`.
+      .pipe(mancha(vars))
+      // Pipe the output to the destination folder.
+      .pipe(GulpClient.dest("public"))
+  );
+});
 ```

package/dist/browser.js

@@ -1,8 +1,8 @@
 import { dirname, IRenderer } from "./core.js";
 class Renderer extends IRenderer {
     dirpath = dirname(self.location.href);
-    parseHTML(content, params = { root: false }) {
-        if (params.root) {
+    parseHTML(content, params = { rootDocument: false }) {
+        if (params.rootDocument) {
             return new DOMParser().parseFromString(content, "text/html");
         }
         else {
@@ -15,7 +15,7 @@ class Renderer extends IRenderer {
         return new XMLSerializer().serializeToString(root).replace(/\s?xmlns="[^"]+"/gm, "");
     }
     preprocessLocal(fpath, params) {
-        // In the browser, "local" paths (i.e., relative) can still be fetched.
+        // In the browser, "local" paths (i.e., relative paths) can still be fetched.
         return this.preprocessRemote(fpath, params);
     }
 }

package/dist/core.d.ts

@@ -1,10 +1,30 @@
 import { ReactiveProxyStore } from "./reactive.js";
 import { ParserParams, RenderParams } from "./interfaces.js";
 export type EvalListener = (result: any, dependencies: string[]) => any;
-export declare function traverse(root: Node | DocumentFragment | Document, skip?: Set<Node>): Generator<ChildNode>;
+/**
+ * Returns the directory name from a given file path.
+ * @param fpath - The file path.
+ * @returns The directory name.
+ */
 export declare function dirname(fpath: string): string;
+/**
+ * Checks if a given file path is a relative path.
+ *
+ * @param fpath - The file path to check.
+ * @returns A boolean indicating whether the file path is relative or not.
+ */
 export declare function isRelativePath(fpath: string): boolean;
+/**
+ * Creates an evaluation function based on the provided code and arguments.
+ * @param code The code to be evaluated.
+ * @param args The arguments to be passed to the evaluation function. Default is an empty array.
+ * @returns The evaluation function.
+ */
 export declare function makeEvalFunction(code: string, args?: string[]): Function;
+/**
+ * Represents an abstract class for rendering and manipulating HTML content.
+ * Extends the `ReactiveProxyStore` class.
+ */
 export declare abstract class IRenderer extends ReactiveProxyStore {
     protected debugging: boolean;
     protected readonly dirpath: string;
@@ -15,22 +35,115 @@ export declare abstract class IRenderer extends ReactiveProxyStore {
     readonly _customElements: Map<string, Node>;
     abstract parseHTML(content: string, params?: ParserParams): DocumentFragment;
     abstract serializeHTML(root: DocumentFragment | Node): string;
+    /**
+     * Sets the debugging flag for the current instance.
+     *
+     * @param flag - The flag indicating whether debugging is enabled or disabled.
+     * @returns The current instance of the class.
+     */
     debug(flag: boolean): this;
+    /**
+     * Fetches the remote file at the specified path and returns its content as a string.
+     * @param fpath - The path of the remote file to fetch.
+     * @param params - Optional parameters for the fetch operation.
+     * @returns A promise that resolves to the content of the remote file as a string.
+     */
     fetchRemote(fpath: string, params?: RenderParams): Promise<string>;
+    /**
+     * Fetches a local path and returns its content as a string.
+     *
+     * @param fpath - The file path of the resource.
+     * @param params - Optional render parameters.
+     * @returns A promise that resolves to the fetched resource as a string.
+     */
     fetchLocal(fpath: string, params?: RenderParams): Promise<string>;
+    /**
+     * Preprocesses a string content with optional rendering and parsing parameters.
+     *
+     * @param content - The string content to preprocess.
+     * @param params - Optional rendering and parsing parameters.
+     * @returns A promise that resolves to a DocumentFragment representing the preprocessed content.
+     */
     preprocessString(content: string, params?: RenderParams & ParserParams): Promise<DocumentFragment>;
-    preprocessLocal(fpath: string, params?: RenderParams & ParserParams): Promise<DocumentFragment>;
+    /**
+     * Preprocesses a remote file by fetching its content and applying preprocessing steps.
+     * @param fpath - The path to the remote file.
+     * @param params - Optional parameters for rendering and parsing.
+     * @returns A Promise that resolves to a DocumentFragment representing the preprocessed content.
+     */
     preprocessRemote(fpath: string, params?: RenderParams & ParserParams): Promise<DocumentFragment>;
+    /**
+     * Preprocesses a local file by fetching its content and applying preprocessing steps.
+     * @param fpath - The path to the local file.
+     * @param params - Optional parameters for rendering and parsing.
+     * @returns A promise that resolves to the preprocessed document fragment.
+     */
+    preprocessLocal(fpath: string, params?: RenderParams & ParserParams): Promise<DocumentFragment>;
+    /**
+     * Creates a deep copy of the current renderer instance.
+     * @returns A new instance of the renderer with the same state as the original.
+     */
     clone(): IRenderer;
+    /**
+     * Logs the provided arguments if debugging is enabled.
+     * @param args - The arguments to be logged.
+     */
     log(...args: any[]): void;
+    /**
+     * Retrieves or creates a cached expression function based on the provided expression.
+     * @param expr - The expression to retrieve or create a cached function for.
+     * @returns The cached expression function.
+     */
     private cachedExpressionFunction;
+    /**
+     * Evaluates an expression and returns the result along with its dependencies.
+     * If the expression is already stored, it returns the stored value directly.
+     * Otherwise, it performs the expression evaluation using the cached expression function.
+     * @param expr - The expression to evaluate.
+     * @param args - Optional arguments to be passed to the expression function.
+     * @returns A promise that resolves to the result and the dependencies of the expression.
+     */
     eval(expr: string, args?: {
         [key: string]: any;
     }): Promise<[any, string[]]>;
+    /**
+     * This function is intended for internal use only.
+     *
+     * Executes the given expression and invokes the provided callback whenever the any of the
+     * dependencies change.
+     *
+     * @param expr - The expression to watch for changes.
+     * @param args - The arguments to be passed to the expression during evaluation.
+     * @param callback - The callback function to be invoked when the dependencies change.
+     * @returns A promise that resolves when the initial evaluation is complete.
+     */
     watchExpr(expr: string, args: {
         [key: string]: any;
     }, callback: EvalListener): Promise<void>;
+    /**
+     * Preprocesses a node by applying all the registered preprocessing plugins.
+     *
+     * @template T - The type of the input node.
+     * @param {T} root - The root node to preprocess.
+     * @param {RenderParams} [params] - Optional parameters for preprocessing.
+     * @returns {Promise<T>} - A promise that resolves to the preprocessed node.
+     */
     preprocessNode<T extends Document | DocumentFragment | Node>(root: T, params?: RenderParams): Promise<T>;
+    /**
+     * Renders the node by applies all the registered rendering plugins.
+     *
+     * @template T - The type of the root node (Document, DocumentFragment, or Node).
+     * @param {T} root - The root node to render.
+     * @param {RenderParams} [params] - Optional parameters for rendering.
+     * @returns {Promise<T>} - A promise that resolves to the fully rendered root node.
+     */
     renderNode<T extends Document | DocumentFragment | Node>(root: T, params?: RenderParams): Promise<T>;
+    /**
+     * Mounts the Mancha application to a root element in the DOM.
+     *
+     * @param root - The root element to mount the application to.
+     * @param params - Optional parameters for rendering the application.
+     * @returns A promise that resolves when the mounting process is complete.
+     */
     mount(root: Document | DocumentFragment | Node, params?: RenderParams): Promise<void>;
 }