mancha 0.17.0 → 0.17.4

package/.github/workflows/ci.yml

@@ -5,12 +5,12 @@ on:
     branches:
       - main
     tags:
-      - 'v*'
+      - "v*"
 
 permissions:
   contents: read
   pages: write
-  id-token: write
+  id-token: write # Required for GitHub Pages and npm OIDC trusted publishing
 
 concurrency:
   group: "pages"
@@ -27,8 +27,8 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '22'
-          registry-url: 'https://registry.npmjs.org'
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
 
       - name: Install dependencies
         run: npm ci
@@ -77,6 +77,9 @@ jobs:
     runs-on: ubuntu-latest
     name: Publish to NPM
     if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: read
+      id-token: write # Required for npm OIDC trusted publishing
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -84,8 +87,8 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '22'
-          registry-url: 'https://registry.npmjs.org'
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
 
       - name: Install dependencies
         run: npm ci
@@ -96,7 +99,5 @@ jobs:
           name: build-artifacts
           path: dist/
 
-      - name: Publish to NPM
-        run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Publish to NPM with provenance
+        run: npm publish --provenance --access public

package/.prettierrc

@@ -1,3 +1,3 @@
 {
-    "printWidth": 100
-}
+	"printWidth": 100
+}

package/.vscode/extensions.json

@@ -1,3 +1,3 @@
 {
-  "recommendations": ["github.copilot"]
+	"recommendations": ["github.copilot"]
 }

package/.vscode/launch.json

@@ -1,44 +1,34 @@
 {
-    // Use IntelliSense to learn about possible attributes.
-    // Hover to view descriptions of existing attributes.
-    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-    "version": "0.2.0",
-    "configurations": [
-        {
-            "name": "Mocha All",
-            "type": "node",
-            "request": "launch",
-            "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
-            "args": [
-                "-r",
-                "ts-node/register",
-                "--no-timeouts",
-                "--colors",
-                "${workspaceFolder}/dist/**/*.test.ts"
-            ],
-            "console": "integratedTerminal",
-            "internalConsoleOptions": "neverOpen",
-            "skipFiles": [
-                "<node_internals>/**/*.js"
-            ]
-        },
-        {
-            "name": "Mocha Current File",
-            "type": "node",
-            "request": "launch",
-            "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
-            "args": [
-                "-r",
-                "ts-node/register",
-                "--no-timeouts",
-                "--colors",
-                "${file}"
-            ],
-            "console": "integratedTerminal",
-            "internalConsoleOptions": "neverOpen",
-            "skipFiles": [
-                "<node_internals>/**/*.js"
-            ]
-        }
-    ]
-}
+	// Use IntelliSense to learn about possible attributes.
+	// Hover to view descriptions of existing attributes.
+	// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+	"version": "0.2.0",
+	"configurations": [
+		{
+			"name": "Mocha All",
+			"type": "node",
+			"request": "launch",
+			"program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
+			"args": [
+				"-r",
+				"ts-node/register",
+				"--no-timeouts",
+				"--colors",
+				"${workspaceFolder}/dist/**/*.test.ts"
+			],
+			"console": "integratedTerminal",
+			"internalConsoleOptions": "neverOpen",
+			"skipFiles": ["<node_internals>/**/*.js"]
+		},
+		{
+			"name": "Mocha Current File",
+			"type": "node",
+			"request": "launch",
+			"program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
+			"args": ["-r", "ts-node/register", "--no-timeouts", "--colors", "${file}"],
+			"console": "integratedTerminal",
+			"internalConsoleOptions": "neverOpen",
+			"skipFiles": ["<node_internals>/**/*.js"]
+		}
+	]
+}

package/README.md

@@ -11,25 +11,25 @@ Here's a small sample of the things that you can do with `mancha`:
 
 <!-- Scoped variables using the `:data` attribute. -->
 <main class="p-4" :data="{count: 0, name: 'Stranger'}">
-  <!-- Custom HTML tag element registration. -->
-  <template is="counter">
-    <div>
-      <slot></slot>
-      <button :on:click="count = count + 1">Counter: {{ count }}</button>
-    </div>
-  </template>
-
-  <!-- Custom HTML tag element usage. -->
-  <counter class="my-2">Click me:</counter>
-
-  <!-- Reactive data binding. -->
-  <p>Enter your name: <input type="text" :bind="name" /></p>
-  <p>Hello, <span class="underline">{{ name }}</span>!</p>
-
-  <!-- Include HTML partials. -->
-  <footer class="text-xs">
-    <include src="html/partial/footer.tpl.html"></include>
-  </footer>
+	<!-- Custom HTML tag element registration. -->
+	<template is="counter">
+		<div>
+			<slot></slot>
+			<button :on:click="count = count + 1">Counter: {{ count }}</button>
+		</div>
+	</template>
+
+	<!-- Custom HTML tag element usage. -->
+	<counter class="my-2">Click me:</counter>
+
+	<!-- Reactive data binding. -->
+	<p>Enter your name: <input type="text" :bind="name" /></p>
+	<p>Hello, <span class="underline">{{ name }}</span>!</p>
+
+	<!-- Include HTML partials. -->
+	<footer class="text-xs">
+		<include src="html/partial/footer.tpl.html"></include>
+	</footer>
 </main>
 ```
 
@@ -79,12 +79,12 @@ preprocessing consist of:
 
   <!-- ./index.html -->
   <div>
-    <include src="button.tpl.html"></include>
+  	<include src="button.tpl.html"></include>
   </div>
 
   <!-- Result after rendering `index.html`. -->
   <div>
-    <button>Click Me</button>
+  	<button>Click Me</button>
   </div>
   ```
 
@@ -93,15 +93,15 @@ preprocessing consist of:
   ```html
   <!-- Use <template is="my-component-name"> to register a component. -->
   <template is="my-red-button">
-    <button style="background-color: red;">
-      <slot></slot>
-    </button>
+  	<button style="background-color: red;">
+  		<slot></slot>
+  	</button>
   </template>
 
   <!-- Any node traversed after registration can use the component. -->
   <my-red-button :on:click="console.log('clicked')">
-    <!-- The contents within will replace the `<slot></slot>` tag. -->
-    Click Me
+  	<!-- The contents within will replace the `<slot></slot>` tag. -->
+  	Click Me
   </my-red-button>
   ```
 
@@ -138,7 +138,7 @@ element tag or attributes match a specific criteria. Here's the list of attribut
 - `: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" />
+  	<input type="text" :bind="name" />
   </div>
   ```
 - `:on:{event}` adds an event listener for `event` to the node
@@ -157,6 +157,17 @@ element tag or attributes match a specific criteria. Here's the list of attribut
   ```html
   <video :prop:src="buildSrc()"></video>
   ```
+- `:render` links an element to a JavaScript ES module for initialization
+  ```html
+  <canvas :render="./chart-init.js"></canvas>
+  ```
+  The module's default export is called with the element and renderer:
+  ```js
+  // chart-init.js
+  export default function (elem, renderer) {
+  	new Chart(elem, { type: "bar" });
+  }
+  ```
 - `{{ value }}` replaces `value` in text nodes
   ```html
   <button :data="{label: 'Click Me'}">{{ label }}</button>
@@ -164,7 +175,7 @@ element tag or attributes match a specific criteria. Here's the list of attribut
 - `:types` **(experimental)** declares TypeScript types for static type checking
   ```html
   <div :types='{"user": "@import:./types/user.ts:User"}'>
-    <span>{{ user.name.toUpperCase() }}</span>
+  	<span>{{ user.name.toUpperCase() }}</span>
   </div>
   ```
   The value of `:types` is parsed with `jexpr` during static analysis. It must evaluate to a plain
@@ -184,51 +195,51 @@ operator, and arrow functions. For example:
 ```html
 <!-- Valid expression: string concatenation -->
 <body :data="{ pos: 1 }">
-  <p :text="'you are number ' + pos + ' in the queue'"></p>
+	<p :text="'you are number ' + pos + ' in the queue'"></p>
 </body>
 
 <!-- Valid expression: optional chaining -->
 <body :data="{ user: null }">
-  <p :text="user?.name ?? 'Anonymous'"></p>
+	<p :text="user?.name ?? 'Anonymous'"></p>
 </body>
 
 <!-- Valid expression: spread operator -->
 <body :data="{ list: [1, 2], extra: 3 }">
-  <div :for="item in [...list, extra]">{{ item }}</div>
+	<div :for="item in [...list, extra]">{{ item }}</div>
 </body>
 
 <!-- Valid expression: arrow functions (e.g. in map) -->
 <body :data="{ items: [1, 2, 3] }">
-  <div :for="n in items.map((x) => x * 2)">{{ n }}</div>
+	<div :for="n in items.map((x) => x * 2)">{{ n }}</div>
 </body>
 
 <!-- Valid expression: boolean logic -->
 <body :data="{ pos: 1, finished: false }">
-  <p :show="pos >= 1 && !finished">you are number {{ pos }} in the queue</p>
+	<p :show="pos >= 1 && !finished">you are number {{ pos }} in the queue</p>
 </body>
 
 <!-- Valid expression: ternary operators -->
 <body :data="{ pos: 1 }">
-  <p :text="pos % 2 == 0 ? 'even' : 'odd'"></p>
+	<p :text="pos % 2 == 0 ? 'even' : 'odd'"></p>
 </body>
 
 <!-- Valid expression: function calling -->
 <body :data="{ pos : 1 }">
-  <p :text="buildQueueMessage()"></p>
-  <script>
-    const { $ } = Mancha;
-    $.buildQueueMessage = function () {
-      return "you are number " + this.pos + " in the queue";
-    };
-    // Alternatively, anonymous functions without `this`:
-    // $.buildQueueMessage = () => 'you are number ' + $.pos + ' in the queue';
-  </script>
+	<p :text="buildQueueMessage()"></p>
+	<script>
+		const { $ } = Mancha;
+		$.buildQueueMessage = function () {
+			return "you are number " + this.pos + " in the queue";
+		};
+		// Alternatively, anonymous functions without `this`:
+		// $.buildQueueMessage = () => 'you are number ' + $.pos + ' in the queue';
+	</script>
 </body>
 
 <!-- Valid expression: simple assignment -->
 <body :data="{ pos: 1 }">
-  <p :text="'you are number ' + pos + ' in the queue'"></p>
-  <button :on:click="pos = pos + 1">Click to get there faster</button>
+	<p :text="'you are number ' + pos + ' in the queue'"></p>
+	<button :on:click="pos = pos + 1">Click to get there faster</button>
 </body>
 
 <!-- Invalid expression: multiple statements -->
@@ -236,7 +247,7 @@ operator, and arrow functions. For example:
 
 <!-- Invalid expression: function definition (top-level) -->
 <body :data="{ foo: function() { return 'yes'; } }">
-  <p :text="foo()"></p>
+	<p :text="foo()"></p>
 </body>
 ```
 
@@ -247,24 +258,26 @@ illustrated with an example:
 
 ```html
 <body :data="{ name: 'stranger', key: '1234' }">
-  <!-- Hello, stranger -->
-  <h1>Hello, {{ name }}</h1>
+	<!-- Hello, stranger -->
+	<h1>Hello, {{ name }}</h1>
 
-  <!-- undefined -->
-  <span>{{ message }}</span>
+	<!-- Initially "undefined", but reactive to later changes -->
+	<span>{{ message }}</span>
 
-  <!-- How are you, danger? The secret message is "secret" and the key is "1234" -->
-  <p :data="{ name: 'danger', message: 'secret' }">
-    How are you, {{ name }}? The secret message is "{{ message }}" and the key is "{{ key }}"
-  </p>
+	<!-- How are you, danger? The secret message is "secret" and the key is "1234" -->
+	<p :data="{ name: 'danger', message: 'secret' }">
+		How are you, {{ name }}? The secret message is "{{ message }}" and the key is "{{ key }}"
+	</p>
 </body>
 ```
 
 By default, the target root element is the `body` tag. So, any variables defined in the body's
 `:data` attribute are available to the main renderer.
 
-In the example above, the variable `message` is only available to the `<p>` tag and all elements
-under that tag, if any. Since the variables are not accessible via the global object, you'll need
+In the example above, the `<span>` references `message` which is not defined in the body's `:data`.
+This auto-initializes `message` to `undefined` and attaches an observer, so setting `$.message`
+later will update the `<span>` content. The `<p>` tag has its own local `message` variable which
+shadows any parent value. Since the variables are not accessible via the global object, you'll need
 to retrieve the renderer from the element's properties:
 
 ```js
@@ -275,8 +288,9 @@ await $.mount(document.body);
 // This modifies the `name` variable in all the renderer contexts.
 $.name = "world";
 
-// This has no effect in the output, because the content of the `<p>` tag is
-// bound to its local variable and `message` was undefined at rendering time.
+// This updates the `<span>` content to "bandit" because `message` was
+// auto-initialized when the template referenced it. However, the `<p>` tag
+// still shows "secret" because it has its own local `message` variable.
 $.message = "bandit";
 
 // We extract the subrenderer from the element's properties. Only elements
@@ -289,15 +303,61 @@ subrenderer.$.message = "banana";
 
 When accessing variables, `mancha` searches the current renderer first, then the parent, the
 parent's parent, and so forth until the root renderer is reached. If the requested variable is not
-found in the current renderer or any of the ancestor renderers, then `null` is returned:
+found in the current renderer or any of the ancestor renderers, then `undefined` is returned:
 
 ```html
 <body :data="{ name: 'stranger' }">
-  <!-- Hello, stranger! -->
-  <p :data="{}">Hello, {{ name }}!</p>
+	<!-- Hello, stranger! -->
+	<p :data="{}">Hello, {{ name }}!</p>
+</body>
+```
+
+### Reactive Undefined Variables
+
+When a variable is referenced in a template expression but not yet defined, `mancha` automatically
+initializes it to `undefined` and attaches an observer. This means you can set the variable later
+using the same renderer (or a subrenderer) and the template will reactively update:
+
+```html
+<body>
+	<!-- Initially shows "undefined", but updates reactively when `message` is set -->
+	<p>{{ message }}</p>
 </body>
+<script type="module">
+	const { $ } = Mancha;
+	await $.mount(document.body);
+
+	// The template initially renders with `message` as undefined.
+	// Setting it now will trigger a reactive update.
+	$.message = "Hello, World!";
+</script>
+```
+
+This behavior is particularly useful with the `:render` attribute, where a JavaScript module can
+set variables that are already referenced in the template:
+
+```html
+<div :render="./init.js">
+	<!-- These variables are set by the :render callback -->
+	<span>{{ title }}</span>
+	<ul :for="item in items">
+		<li>{{ item }}</li>
+	</ul>
+</div>
+```
+
+```js
+// init.js
+export default async function (elem, renderer) {
+	await renderer.set("title", "My List");
+	await renderer.set("items", ["a", "b", "c"]);
+}
 ```
 
+The auto-initialization only happens when variables are accessed during an effect (such as template
+rendering). Accessing a variable outside of an effect context will return `undefined` without
+creating an observer.
+
 When setting a variable, there are 3 possible cases:
 
 1. The variable has already been defined in the current renderer. Then it gets updated in the
@@ -333,12 +393,12 @@ This allows you to react to URL changes declaratively within your components:
 
 ```html
 <body :data="{ $$search: '' }">
-  <input type="text" :bind="$$search" placeholder="Search..." />
-  <div :show="$$search">Searching for: {{ $$search }}</div>
+	<input type="text" :bind="$$search" placeholder="Search..." />
+	<div :show="$$search">Searching for: {{ $$search }}</div>
 </body>
 <script type="module">
-  import { Mancha } from "//unpkg.com/mancha";
-  await Mancha.mount(document.body);
+	import { Mancha } from "//unpkg.com/mancha";
+	await Mancha.mount(document.body);
 </script>
 ```
 
@@ -363,7 +423,7 @@ To use `mancha` on the client (browser), use the `mancha` bundled file available
 
 ```html
 <body :data="{ name: 'John' }">
-  <span>Hello, {{ name }}!</span>
+	<span>Hello, {{ name }}!</span>
 </body>
 
 <script src="//unpkg.com/mancha" target="body" css="basic+utils" init></script>
@@ -415,16 +475,16 @@ import vars from "./vars.json";
 const app = express();
 
 app.get("/", async (req, res) => {
-  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);
+	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);
 });
 
 app.listen(process.env.PORT || 8080);
@@ -443,14 +503,14 @@ import htmlIndex from "./index.html";
 import vars from "./vars.json";
 
 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" } }));
+	// 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" } }));
 });
 ```
 

package/dist/browser.d.ts

@@ -1,6 +1,8 @@
 import { IRenderer } from "./renderer.js";
 import type { StoreState } from "./store.js";
 import type { ParserParams, RenderParams } from "./interfaces.js";
+export { IRenderer } from "./renderer.js";
+export type { ParserParams, RenderParams, RendererPlugin } from "./interfaces.js";
 export { default as basicCssRules } from "./css_gen_basic.js";
 export { default as utilsCssRules } from "./css_gen_utils.js";
 export declare class Renderer<T extends StoreState = StoreState> extends IRenderer<T> {