npm - mancha - Versions diffs - 0.16.7 → 0.17.3 - Mend

mancha 0.16.7 → 0.17.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (85) hide show

package/.github/workflows/ci.yml +8 -7
package/README.md +88 -25
package/dist/browser.d.ts +42 -3
package/dist/browser.js +1 -1
package/dist/browser.js.map +1 -1
package/dist/css_gen_utils.js +323 -412
package/dist/css_gen_utils.js.map +1 -1
package/dist/dome.d.ts +2 -2
package/dist/dome.js +17 -0
package/dist/dome.js.map +1 -1
package/dist/expressions/ast.d.ts +79 -0
package/dist/expressions/ast.js +6 -0
package/dist/expressions/ast.js.map +1 -0
package/dist/expressions/ast.test.d.ts +1 -0
package/dist/expressions/ast.test.js +122 -0
package/dist/expressions/ast.test.js.map +1 -0
package/dist/expressions/ast_factory.d.ts +37 -0
package/dist/expressions/ast_factory.js +119 -0
package/dist/expressions/ast_factory.js.map +1 -0
package/dist/expressions/ast_factory.test.d.ts +1 -0
package/dist/expressions/ast_factory.test.js +88 -0
package/dist/expressions/ast_factory.test.js.map +1 -0
package/dist/expressions/constants.d.ts +6 -0
package/dist/expressions/constants.js +72 -0
package/dist/expressions/constants.js.map +1 -0
package/dist/expressions/constants.test.d.ts +1 -0
package/dist/expressions/constants.test.js +84 -0
package/dist/expressions/constants.test.js.map +1 -0
package/dist/expressions/eval.d.ts +101 -0
package/dist/expressions/eval.js +375 -0
package/dist/expressions/eval.js.map +1 -0
package/dist/expressions/eval.test.d.ts +1 -0
package/dist/expressions/eval.test.js +141 -0
package/dist/expressions/eval.test.js.map +1 -0
package/dist/expressions/expressions.test.d.ts +6 -0
package/dist/expressions/expressions.test.js +7 -0
package/dist/expressions/expressions.test.js.map +1 -0
package/dist/expressions/index.d.ts +6 -0
package/dist/expressions/index.js +7 -0
package/dist/expressions/index.js.map +1 -0
package/dist/expressions/parser.d.ts +32 -0
package/dist/expressions/parser.js +341 -0
package/dist/expressions/parser.js.map +1 -0
package/dist/expressions/parser.test.d.ts +1 -0
package/dist/expressions/parser.test.js +176 -0
package/dist/expressions/parser.test.js.map +1 -0
package/dist/expressions/tokenizer.d.ts +49 -0
package/dist/expressions/tokenizer.js +253 -0
package/dist/expressions/tokenizer.js.map +1 -0
package/dist/expressions/tokenizer.test.d.ts +1 -0
package/dist/expressions/tokenizer.test.js +99 -0
package/dist/expressions/tokenizer.test.js.map +1 -0
package/dist/index.d.ts +2 -0
package/dist/index.js +1 -0
package/dist/index.js.map +1 -1
package/dist/interfaces.d.ts +1 -1
package/dist/mancha.d.ts +1 -1
package/dist/mancha.js +1 -1
package/dist/mancha.js.map +1 -1
package/dist/plugins.js +94 -23
package/dist/plugins.js.map +1 -1
package/dist/renderer.d.ts +5 -2
package/dist/renderer.js +6 -2
package/dist/renderer.js.map +1 -1
package/dist/safe_browser.d.ts +4 -3
package/dist/safe_browser.js +1 -1
package/dist/safe_browser.js.map +1 -1
package/dist/store.d.ts +59 -13
package/dist/store.js +112 -38
package/dist/store.js.map +1 -1
package/dist/test_utils.d.ts +2 -0
package/dist/test_utils.js +14 -1
package/dist/test_utils.js.map +1 -1
package/dist/trusted_attributes.js +2 -0
package/dist/trusted_attributes.js.map +1 -1
package/dist/type_checker.d.ts +1 -0
package/dist/type_checker.js +113 -41
package/dist/type_checker.js.map +1 -1
package/dist/worker.d.ts +2 -0
package/dist/worker.js +1 -0
package/dist/worker.js.map +1 -1
package/docs/quickstart.md +200 -0
package/gulpfile.js +5 -1
package/package.json +19 -6
package/tsec_exemptions.json +1 -1

package/.github/workflows/ci.yml CHANGED Viewed

@@ -10,7 +10,7 @@ on:
 permissions:
   contents: read
   pages: write
-  id-token: write
+  id-token: write  # Required for GitHub Pages and npm OIDC trusted publishing
 concurrency:
   group: "pages"
@@ -27,7 +27,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '22'
+          node-version: '24'
           registry-url: 'https://registry.npmjs.org'
       - name: Install dependencies
@@ -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,7 +87,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '22'
+          node-version: '24'
           registry-url: 'https://registry.npmjs.org'
       - name: Install dependencies
@@ -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/README.md CHANGED Viewed

@@ -47,7 +47,7 @@ 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       | ✔️     | ❌     | ❌       | ❌     | ✔️         | ✔️        |
-| < 15kb compressed     | ✔️     | ❌     | ❌       | ❌     | ✔️         | ❌        |
+| < 16kb compressed     | ✔️     | ✔️     | ❌       | ❌     | ✔️         | ❌        |
 | Custom web components | ✔️     | ✔️     | ✔️       | ✔️     | ❌         | ❌        |
 | Client-side rendering | ✔️     | ❌     | ❌       | ✔️     | ✔️         | ✔️        |
 | Server-side rendering | ✔️     | ✔️     | ✔️       | ✔️     | ❌         | ❌        |
@@ -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>
@@ -177,8 +188,9 @@ element tag or attributes match a specific criteria. Here's the list of attribut
 ## Evaluation
 To avoid violation of Content Security Policy (CSP) that forbids the use of `eval()`, `Mancha`
-evaluates all expressions using [`jexpr`][jexpr]. This means that only simple expressions are
-allowed, and spaces must be used to separate different expression tokens. For example:
+evaluates all expressions using a safe expression parser. This means that only simple expressions are
+allowed, but it supports many modern JavaScript features, including optional chaining, the spread
+operator, and arrow functions. For example:
 ```html
 <!-- Valid expression: string concatenation -->
@@ -186,6 +198,21 @@ allowed, and spaces must be used to separate different expression tokens. For ex
   <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>
+</body>
+<!-- Valid expression: spread operator -->
+<body :data="{ list: [1, 2], extra: 3 }">
+  <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>
+</body>
 <!-- Valid expression: boolean logic -->
 <body :data="{ pos: 1, finished: false }">
   <p :show="pos >= 1 && !finished">you are number {{ pos }} in the queue</p>
@@ -215,24 +242,13 @@ allowed, and spaces must be used to separate different expression tokens. For ex
   <button :on:click="pos = pos + 1">Click to get there faster</button>
 </body>
-<!-- Invalid expression: missing spaces -->
-<body :data="{ pos: 1 }">
-  <p :text="'you are number '+pos+' in the queue'"></p>
-</body>
 <!-- Invalid expression: multiple statements -->
 <button :on:click="console.log('yes'); answer = 'no'"></button>
-<!-- Invalid expression: function definition -->
-<body :data="{ foo: () => 'yes' }">
+<!-- Invalid expression: function definition (top-level) -->
+<body :data="{ foo: function() { return 'yes'; } }">
   <p :text="foo()"></p>
 </body>
-<!-- Invalid expression: complex assignment -->
-<body :data="{ pos: 1 }">
-  <p :text="'you are number ' + pos + ' in the queue'"></p>
-  <button :on:click="pos++">Click to get there faster</button>
-</body>
 ```
 ## Variable Scoping
@@ -245,7 +261,7 @@ illustrated with an example:
   <!-- Hello, stranger -->
   <h1>Hello, {{ name }}</h1>
-  <!-- undefined -->
+  <!-- Initially "undefined", but reactive to later changes -->
   <span>{{ message }}</span>
   <!-- How are you, danger? The secret message is "secret" and the key is "1234" -->
@@ -258,8 +274,10 @@ illustrated with an example:
 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
@@ -270,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
@@ -284,7 +303,7 @@ 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' }">
@@ -293,6 +312,52 @@ found in the current renderer or any of the ancestor renderers, then `null` is r
 </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
@@ -457,7 +522,5 @@ For a more complete example, see [examples/wrangler](./examples/wrangler).
 ## Dependencies
-The browser bundle contains a single external dependency, [`jexpr`][jexpr]. The unbundled version
+The browser bundle contains no external dependencies. The unbundled version
 can use `htmlparser2`, which is compatible with web workers, or `jsdom`.
-[jexpr]: https://github.com/justinfagnani/jexpr

package/dist/browser.d.ts CHANGED Viewed

@@ -1,8 +1,11 @@
 import { IRenderer } from "./renderer.js";
-import { ParserParams, RenderParams } from "./interfaces.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 extends IRenderer {
+export declare class Renderer<T extends StoreState = StoreState> extends IRenderer<T> {
     readonly impl = "browser";
     protected readonly dirpath: string;
     parseHTML(content: string, params?: ParserParams): Document | DocumentFragment;
@@ -11,4 +14,40 @@ export declare class Renderer extends IRenderer {
     createElement(tag: string, owner?: Document | null): Element;
     textContent(node: Node, content: string): void;
 }
-export declare const Mancha: Renderer;
+export declare const Mancha: Renderer<StoreState>;
+/** Options for CSS injection. */
+export type CssName = "basic" | "utils";
+/**
+ * Injects CSS rules into the document head.
+ * @param names - Array of CSS names to inject ("basic", "utils").
+ */
+export declare function injectCss(names: CssName[]): void;
+/**
+ * Injects the basic CSS rules into the document head.
+ */
+export declare function injectBasicCss(): void;
+/**
+ * Injects the utils CSS rules into the document head.
+ */
+export declare function injectUtilsCss(): void;
+/** Options for initializing Mancha. */
+export interface InitManchaOptions {
+    /** CSS styles to inject before mounting. */
+    css?: CssName[];
+    /** Target selector(s) to mount the renderer to. */
+    target?: string | string[];
+    /** Enable debug mode. */
+    debug?: boolean;
+    /** Cache policy for fetch requests. */
+    cache?: RequestCache;
+    /** Initial state to set before mounting. */
+    state?: Record<string, unknown>;
+}
+/**
+ * Initializes Mancha with the provided options.
+ * This is a convenience function for bundled environments.
+ *
+ * @param options - Initialization options.
+ * @returns A promise that resolves to the Renderer instance.
+ */
+export declare function initMancha<T extends StoreState = StoreState>(options?: InitManchaOptions): Promise<Renderer<T>>;