@microsoft/fast-html 1.0.0-alpha.43 → 1.0.0-alpha.45

package/README.md

@@ -243,18 +243,38 @@ Event bindings must include the `()` as well as being preceeded by `@` in keepin
 <button @click="{handleClick()}"></button>
 ```
 
-In addition you may include an event or attribute or observable, events are denoted with `e` as a reserved letter.
+You can pass the DOM event object, the execution context, or both as arguments. Any other argument is treated as a binding expression and resolved against the current data source.
 
-Event:
+**`$e` — DOM event object (preferred):**
 ```html
-<button @click="{handleClick(e)}"></button>
+<button @click="{handleClick($e)}"></button>
 ```
 
-Attribute/Observable:
+**`$c` — execution context:**
 ```html
-<button @click="{handleClick(foo)}"></button>
+<button @click="{handleClick($c)}"></button>
 ```
 
+**`$c.somePath` — a property of the execution context (e.g. `$c.parent`, `$c.event`):**
+```html
+<button @click="{handleClick($c.parent)}"></button>
+```
+
+**Multiple arguments:**
+```html
+<button @click="{handleClick($e, $c)}"></button>
+```
+
+**Arbitrary binding expressions** — any token that is not `$e`, `$c`, or `e` is resolved as a binding path on the data source:
+```html
+<button @click="{handleClick(user.id)}"></button>
+```
+
+> **Deprecated:** The bare `e` token still works but will emit a console warning. Migrate to `$e`.
+> ```html
+> <button @click="{handleClick(e)}"></button>
+> ```
+
 #### Directives
 
 Directives are assumed to be either an attribute directive or a directive that also serves a template. Both are prepended by `f-`. The logic of these directives and what their use cases are is explained in the [FAST html documentation](https://fast.design/docs/getting-started/html-directives).

package/dist/dts/components/syntax.d.ts

@@ -1,4 +1,4 @@
 /**
  * Default syntax for FAST declarative templates
  */
-export declare const attributeDirectivePrefix: string, clientSideCloseExpression: string, clientSideOpenExpression: string, closeExpression: string, executionContextAccessor: string, openExpression: string, repeatDirectiveClose: string, repeatDirectiveOpen: string, unescapedCloseExpression: string, unescapedOpenExpression: string, whenDirectiveClose: string, whenDirectiveOpen: string;
+export declare const attributeDirectivePrefix: string, clientSideCloseExpression: string, clientSideOpenExpression: string, closeExpression: string, deprecatedEventArgAccessor: string, eventArgAccessor: string, executionContextAccessor: string, openExpression: string, repeatDirectiveClose: string, repeatDirectiveOpen: string, unescapedCloseExpression: string, unescapedOpenExpression: string, whenDirectiveClose: string, whenDirectiveOpen: string;

package/dist/dts/components/template.d.ts

@@ -1,4 +1,4 @@
-import { FASTElement, HydrationControllerCallbacks, TemplateLifecycleCallbacks } from "@microsoft/fast-element";
+import { FASTElement, type HydrationControllerCallbacks, type TemplateLifecycleCallbacks } from "@microsoft/fast-element";
 import "@microsoft/fast-element/install-hydratable-view-templates.js";
 /**
  * Values for the observerMap element option.

package/dist/dts/components/utilities.d.ts

@@ -1,4 +1,5 @@
 import { type JSONSchema, type JSONSchemaDefinition, Schema } from "./schema.js";
+import { deprecatedEventArgAccessor, eventArgAccessor, executionContextAccessor } from "./syntax.js";
 type BehaviorType = "dataBinding" | "templateDirective";
 type TemplateDirective = "when" | "repeat";
 export type AttributeDirective = "children" | "slotted" | "ref";
@@ -41,6 +42,34 @@ export interface ChildrenMap {
     attributeName: string;
 }
 export declare const contextPrefixDot: string;
+export { deprecatedEventArgAccessor, eventArgAccessor, executionContextAccessor };
+/**
+ * The type of a parsed event handler argument.
+ */
+export type EventArgType = "event" | "deprecated-event" | "context" | "binding";
+/**
+ * A parsed event handler argument descriptor.
+ */
+export interface ParsedEventArg {
+    type: EventArgType;
+    /** The raw argument string, present only when `type` is `"binding"`. */
+    rawArg?: string;
+}
+/**
+ * Parses the arguments string of an event handler binding into an array of
+ * typed argument descriptors. Unrecognised tokens are returned as `"binding"`
+ * type with their raw string preserved.
+ *
+ * Special arguments:
+ * - `$e` — resolves to the DOM event object
+ * - `e` — resolves to the DOM event object (deprecated, use `$e`)
+ * - `$c` — resolves to the full execution context object
+ *
+ * @param argsString - The raw arguments string from between the parentheses,
+ *   e.g. `""`, `"$e"`, `"$c"`, or `"$e, $c"`.
+ * @returns An array of {@link ParsedEventArg} descriptors.
+ */
+export declare function parseEventArgs(argsString: string): ParsedEventArg[];
 declare const LogicalOperator: {
     AND: string;
     OR: string;
@@ -190,4 +219,3 @@ export declare function isPlainObject(value: any): value is Record<string, any>;
  * @returns boolean indicating whether changes were made
  */
 export declare function deepMerge(target: any, source: any): boolean;
-export {};

package/dist/esm/components/syntax.js

@@ -1,11 +1,13 @@
 /**
  * Default syntax for FAST declarative templates
  */
-export const { attributeDirectivePrefix, clientSideCloseExpression, clientSideOpenExpression, closeExpression, executionContextAccessor, openExpression, repeatDirectiveClose, repeatDirectiveOpen, unescapedCloseExpression, unescapedOpenExpression, whenDirectiveClose, whenDirectiveOpen, } = {
+export const { attributeDirectivePrefix, clientSideCloseExpression, clientSideOpenExpression, closeExpression, deprecatedEventArgAccessor, eventArgAccessor, executionContextAccessor, openExpression, repeatDirectiveClose, repeatDirectiveOpen, unescapedCloseExpression, unescapedOpenExpression, whenDirectiveClose, whenDirectiveOpen, } = {
     attributeDirectivePrefix: "f-",
     clientSideCloseExpression: "}",
     clientSideOpenExpression: "{",
     closeExpression: "}}",
+    deprecatedEventArgAccessor: "e",
+    eventArgAccessor: "$e",
     executionContextAccessor: "$c",
     openExpression: "{{",
     unescapedCloseExpression: "}}}",

package/dist/esm/components/template.js

@@ -3,7 +3,7 @@ import { attr, children, elements, FAST, FASTElement, FASTElementDefinition, fas
 import "@microsoft/fast-element/install-hydratable-view-templates.js";
 import { ObserverMap } from "./observer-map.js";
 import { Schema } from "./schema.js";
-import { bindingResolver, contextPrefixDot, getBooleanBinding, getExpressionChain, getNextBehavior, getRootPropertyName, transformInnerHTML, } from "./utilities.js";
+import { bindingResolver, contextPrefixDot, eventArgAccessor, getBooleanBinding, getExpressionChain, getNextBehavior, getRootPropertyName, parseEventArgs, transformInnerHTML, } from "./utilities.js";
 /**
  * Values for the observerMap element option.
  */
@@ -226,7 +226,7 @@ class TemplateElement extends FASTElement {
                             1);
                         const type = "event";
                         rootPropertyName = getRootPropertyName(rootPropertyName, propName, parentContext, type);
-                        const arg = bindingHTML.slice(openingParenthesis + 1, closingParenthesis);
+                        const argsString = bindingHTML.slice(openingParenthesis + 1, closingParenthesis);
                         const binding = bindingResolver(strings.join(""), rootPropertyName, propName, parentContext, type, schema, parentContext, level);
                         const isContextPath = propName.startsWith(contextPrefixDot);
                         const getOwner = isContextPath
@@ -235,11 +235,23 @@ class TemplateElement extends FASTElement {
                                 return ownerPath.reduce((prev, item) => prev === null || prev === void 0 ? void 0 : prev[item], c);
                             }
                             : (x, _c) => x;
-                        attributeBinding = (x, c) => binding(x, c).bind(getOwner(x, c))(...(arg === "e" ? [c.event] : []), ...(arg !== "e" && arg !== ""
-                            ? [
-                                bindingResolver(strings.join(""), rootPropertyName, arg, parentContext, type, schema, parentContext, level)(x, c),
-                            ]
-                            : []));
+                        const parsedArgs = parseEventArgs(argsString);
+                        if (parsedArgs.some(a => a.type === "deprecated-event")) {
+                            console.warn(`[fast-html] Using "e" as an event argument is deprecated. ` +
+                                `Use "${eventArgAccessor}" instead.`);
+                        }
+                        const argResolvers = parsedArgs.map((parsedArg) => {
+                            switch (parsedArg.type) {
+                                case "event":
+                                case "deprecated-event":
+                                    return (_x, c) => c.event;
+                                case "context":
+                                    return (_x, c) => c;
+                                case "binding":
+                                    return bindingResolver(strings.join(""), rootPropertyName, parsedArg.rawArg, parentContext, type, schema, parentContext, level);
+                            }
+                        });
+                        attributeBinding = (x, c) => binding(x, c).bind(getOwner(x, c))(...argResolvers.map(resolve => resolve(x, c)));
                         break;
                     }
                     case "?": {

package/dist/esm/components/utilities.js

@@ -1,7 +1,42 @@
 import { Observable } from "@microsoft/fast-element/observable.js";
 import { defsPropertyName, fastContextMetaData, refPropertyName, Schema, } from "./schema.js";
-import { attributeDirectivePrefix, clientSideCloseExpression, clientSideOpenExpression, closeExpression, executionContextAccessor, openExpression, repeatDirectiveClose, repeatDirectiveOpen, unescapedCloseExpression, unescapedOpenExpression, whenDirectiveClose, whenDirectiveOpen, } from "./syntax.js";
+import { attributeDirectivePrefix, clientSideCloseExpression, clientSideOpenExpression, closeExpression, deprecatedEventArgAccessor, eventArgAccessor, executionContextAccessor, openExpression, repeatDirectiveClose, repeatDirectiveOpen, unescapedCloseExpression, unescapedOpenExpression, whenDirectiveClose, whenDirectiveOpen, } from "./syntax.js";
 export const contextPrefixDot = `${executionContextAccessor}.`;
+export { deprecatedEventArgAccessor, eventArgAccessor, executionContextAccessor };
+/**
+ * Parses the arguments string of an event handler binding into an array of
+ * typed argument descriptors. Unrecognised tokens are returned as `"binding"`
+ * type with their raw string preserved.
+ *
+ * Special arguments:
+ * - `$e` — resolves to the DOM event object
+ * - `e` — resolves to the DOM event object (deprecated, use `$e`)
+ * - `$c` — resolves to the full execution context object
+ *
+ * @param argsString - The raw arguments string from between the parentheses,
+ *   e.g. `""`, `"$e"`, `"$c"`, or `"$e, $c"`.
+ * @returns An array of {@link ParsedEventArg} descriptors.
+ */
+export function parseEventArgs(argsString) {
+    if (argsString.trim() === "")
+        return [];
+    return argsString
+        .split(",")
+        .map(arg => arg.trim())
+        .filter(arg => arg !== "")
+        .map((arg) => {
+        switch (arg) {
+            case eventArgAccessor:
+                return { type: "event" };
+            case deprecatedEventArgAccessor:
+                return { type: "deprecated-event" };
+            case executionContextAccessor:
+                return { type: "context" };
+            default:
+                return { type: "binding", rawArg: arg };
+        }
+    });
+}
 const startInnerHTMLDiv = `<div :innerHTML="{{`;
 const startInnerHTMLDivLength = startInnerHTMLDiv.length;
 const endInnerHTMLDiv = `}}"></div>`;
@@ -789,7 +824,29 @@ function assignObservablesToArray(proxiedData, schema, rootSchema, target, rootP
             });
         },
     });
-    return data;
+    if (schemaProperties !== null) {
+        return data;
+    }
+    // For primitive arrays, wrap in a Proxy so that direct index assignment
+    // (e.g. arr[0] = value) triggers FAST's splice-based change tracking and
+    // keeps repeat directives in sync. Object arrays are not wrapped because
+    // their items are individually proxied, and FAST's own push/splice/etc.
+    // already carry splice records — double-wrapping would produce duplicate
+    // splice notifications.
+    return new Proxy(data, {
+        set: (arr, prop, value) => {
+            const idx = typeof prop === "string" ? Number(prop) : NaN;
+            if (typeof prop !== "symbol" && Number.isInteger(idx) && idx >= 0) {
+                // splice() replaces the item in-place and creates the splice
+                // record that FAST's ArrayObserver delivers to repeat directives.
+                Array.prototype.splice.call(arr, idx, 1, value);
+            }
+            else {
+                arr[prop] = value;
+            }
+            return true;
+        },
+    });
 }
 /**
  * Extracts the definition name from a JSON Schema $ref property
@@ -866,6 +923,12 @@ export function assignObservables(schema, rootSchema, data, target, rootProperty
                     }));
                 }
             }
+            else {
+                // Primitive array (items have no schema $ref): wrap in a proxy so that
+                // direct index assignments (e.g. arr[0] = value) use FAST's splice-based
+                // change tracking and keep repeat directives in sync.
+                proxiedData = assignObservablesToArray(proxiedData, schema, rootSchema, target, rootProperty);
+            }
             break;
         }
         case "object": {

package/dist/esm/components/utilities.spec.js

@@ -1,6 +1,6 @@
 import { expect, test } from "@playwright/test";
 import { refPropertyName, Schema } from "./schema.js";
-import { extractPathsFromChainedExpression, findDef, getBooleanBinding, getChildrenMap, getExpressionChain, getIndexOfNextMatchingTag, getNextBehavior, pathResolver, transformInnerHTML, } from "./utilities.js";
+import { eventArgAccessor, extractPathsFromChainedExpression, findDef, getBooleanBinding, getChildrenMap, getExpressionChain, getIndexOfNextMatchingTag, getNextBehavior, parseEventArgs, pathResolver, transformInnerHTML, } from "./utilities.js";
 test.describe("utilities", async () => {
     test.describe("content", async () => {
         test("get the next content binding", async () => {
@@ -592,4 +592,55 @@ test.describe("utilities", async () => {
             });
         });
     });
+    test.describe("parseEventArgs", async () => {
+        test("should return an empty array for an empty string", async () => {
+            expect(parseEventArgs("")).toEqual([]);
+        });
+        test("should parse $e as an event argument", async () => {
+            expect(parseEventArgs(eventArgAccessor)).toEqual([{ type: "event" }]);
+        });
+        test("should parse e (no $) as a deprecated-event argument", async () => {
+            expect(parseEventArgs("e")).toEqual([{ type: "deprecated-event" }]);
+        });
+        test("should parse $c as a context argument", async () => {
+            expect(parseEventArgs("$c")).toEqual([{ type: "context" }]);
+        });
+        test("should return a binding type for unrecognised tokens", async () => {
+            expect(parseEventArgs("foo")).toEqual([{ type: "binding", rawArg: "foo" }]);
+        });
+        test("should return a binding type for $c.path tokens", async () => {
+            expect(parseEventArgs("$c.eventDetail")).toEqual([
+                { type: "binding", rawArg: "$c.eventDetail" },
+            ]);
+        });
+        test("should return a binding type for $c.event", async () => {
+            expect(parseEventArgs("$c.event")).toEqual([
+                { type: "binding", rawArg: "$c.event" },
+            ]);
+        });
+        test("should parse multiple arguments: $e, $c", async () => {
+            expect(parseEventArgs("$e, $c")).toEqual([
+                { type: "event" },
+                { type: "context" },
+            ]);
+        });
+        test("should parse multiple arguments without spaces", async () => {
+            expect(parseEventArgs("$e,$c")).toEqual([
+                { type: "event" },
+                { type: "context" },
+            ]);
+        });
+        test("should parse e (deprecated) mixed with $c", async () => {
+            expect(parseEventArgs("e, $c")).toEqual([
+                { type: "deprecated-event" },
+                { type: "context" },
+            ]);
+        });
+        test("should return a binding type for unrecognised tokens in a mixed list", async () => {
+            expect(parseEventArgs("$e, foo")).toEqual([
+                { type: "event" },
+                { type: "binding", rawArg: "foo" },
+            ]);
+        });
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/fast-html",
-  "version": "1.0.0-alpha.43",
+  "version": "1.0.0-alpha.45",
   "type": "module",
   "author": {
     "name": "Microsoft",
@@ -23,6 +23,7 @@
   "scripts": {
     "build:tsc": "tsc -p ./tsconfig.json",
     "build": "npm run build:tsc && npm run doc",
+    "build:fixtures": "node scripts/build-fixtures.js",
     "clean": "clean dist temp test-results",
     "dev:full": "concurrently -k -n fast-element,fast-html,server \"npm run dev --workspace=@microsoft/fast-element\" \"npm:watch\" \"npm:test-server\"",
     "dev": "concurrently -k -n tsc,server \"npm run watch\" \"npm run test-server\"",
@@ -59,6 +60,7 @@
     "@microsoft/fast-element": "^2.10.2"
   },
   "devDependencies": {
+    "@microsoft/fast-build": "^0.1.2",
     "@microsoft/fast-element": "^2.10.2"
   },
   "beachball": {