@microsoft/fast-html 1.0.0-alpha.44 → 1.0.0-alpha.46

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/schema.js

@@ -44,6 +44,7 @@ export class Schema {
                     else {
                         if (!((_a = schema[defsPropertyName]) === null || _a === void 0 ? void 0 : _a[splitPath[0]])) {
                             schema[defsPropertyName] = {
+                                ...schema[defsPropertyName],
                                 [splitPath[0]]: {},
                             };
                         }

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

@@ -481,4 +481,47 @@ test.describe("Schema", async () => {
         expect((_h = schemaA.$defs) === null || _h === void 0 ? void 0 : _h["user"].properties["a"].properties["b"].anyOf).toHaveLength(1);
         expect((_j = schemaA.$defs) === null || _j === void 0 ? void 0 : _j["user"].properties["a"].properties["b"].anyOf[0][refPropertyName]).toEqual("https://fast.design/schemas/my-custom-element-2/c.json");
     });
+    test("should preserve existing $defs when adding a new dotted path inside a repeat context", async () => {
+        var _a, _b, _c, _d, _e;
+        // Regression test: Schema.addPath replaced $defs instead of merging
+        // when a dotted path (e.g. "entry.title") with a NEW context name was
+        // used after a prior context already populated $defs, destroying the
+        // first context's $defs entry.
+        // Real-world trigger: history_btr template with multiple repeat
+        // contexts where accessing a dotted path on a later context
+        // overwrites $defs.
+        const schema = new Schema("my-element");
+        // First repeat: creates $defs.group
+        schema.addPath({
+            rootPropertyName: "data",
+            pathConfig: {
+                type: "repeat",
+                path: "data.displayedGroups",
+                currentContext: "group",
+                parentContext: null,
+            },
+            childrenMap: null,
+        });
+        // Access a dotted path that targets a context NOT yet in $defs.
+        // splitPath = ["entry", "title"], and $defs["entry"] doesn't exist,
+        // so the code creates $defs = { entry: {} }, which SHOULD be
+        // $defs = { ...existing, entry: {} } to preserve "group".
+        schema.addPath({
+            rootPropertyName: "data",
+            pathConfig: {
+                type: "access",
+                path: "entry.title",
+                currentContext: "entry",
+                parentContext: "group",
+            },
+            childrenMap: null,
+        });
+        const schemaData = schema.getSchema("data");
+        expect(schemaData).toBeDefined();
+        // Both $defs entries must survive — the bug was that "group" was lost
+        expect((_a = schemaData.$defs) === null || _a === void 0 ? void 0 : _a["group"]).toBeDefined();
+        expect((_b = schemaData.$defs) === null || _b === void 0 ? void 0 : _b["entry"]).toBeDefined();
+        expect((_c = schemaData.$defs) === null || _c === void 0 ? void 0 : _c["group"].$fast_context).toEqual("displayedGroups");
+        expect((_e = (_d = schemaData.$defs) === null || _d === void 0 ? void 0 : _d["entry"].properties) === null || _e === void 0 ? void 0 : _e["title"]).toBeDefined();
+    });
 });

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>`;

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.44",
+  "version": "1.0.0-alpha.46",
   "type": "module",
   "author": {
     "name": "Microsoft",
@@ -23,13 +23,14 @@
   "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\"",
     "doc:ci": "api-extractor run",
     "doc": "npm run doc:ci -- --local",
-    "lint": "biome lint .",
-    "lint:fix": "biome lint --fix .",
+    "lint": "biome-changed",
+    "lint:fix": "biome-changed -- --fix",
     "install-playwright-browsers": "npm run playwright install",
     "prepublishOnly": "npm run clean && npm run build",
     "test-server": "npx vite test/ --clearScreen false",
@@ -56,10 +57,11 @@
     "./dist/esm/index.js"
   ],
   "peerDependencies": {
-    "@microsoft/fast-element": "^2.10.2"
+    "@microsoft/fast-element": "^2.10.3"
   },
   "devDependencies": {
-    "@microsoft/fast-element": "^2.10.2"
+    "@microsoft/fast-build": "^0.3.0",
+    "@microsoft/fast-element": "^2.10.3"
   },
   "beachball": {
     "disallowedChangeTypes": [