Merge branch 'releases/fast-element-v3' into users/janechu/remove-shared-kernel

Author: janechu

change/@microsoft-fast-element-a3210470-66d1-4f88-a4e9-009f116b41fc.json

@@ -0,0 +1,7 @@
+{
+  "type": "major",
+  "comment": "remove deprecated declarative event e support",
+  "packageName": "@microsoft/fast-element",
+  "email": "7559015+janechu@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

packages/fast-element/DECLARATIVE_DESIGN.md

@@ -154,7 +154,6 @@ All delimiters used by the parser are defined in a single `Syntax` interface and
 | `whenDirectiveOpen` / `whenDirectiveClose` | `<f-when` / `</f-when>` | When directive |
 | `attributeDirectivePrefix` | `f-` | Attribute directive prefix |
 | `eventArgAccessor` | `$e` | DOM event argument |
-| `deprecatedEventArgAccessor` | `e` | Deprecated DOM event argument (emits a deduplicated warning once per component) |
 | `executionContextAccessor` | `$c` | Execution context argument |
 
 ---
@@ -351,7 +350,6 @@ sequenceDiagram
 |---|---|---|
 | `parse()` | public | Entry point: parses declarative HTML into `{ strings, values }`. |
 | `createTemplate()` | public | Creates a `ViewTemplate` from resolved strings and values. |
-| `hasDeprecatedEventSyntax` | public | Getter indicating whether the last parse encountered deprecated `e` event syntax. |
 | `resolveStringsAndValues()` | private | Creates `strings`/`values` arrays and delegates to `resolveInnerHTML()`. |
 | `resolveInnerHTML()` | private | Recursive HTML parser that dispatches to data binding or template directive handlers. |
 | `resolveDataBinding()` | private | Thin dispatcher that routes to `resolveContentBinding()`, `resolveAttributeBinding()`, or `resolveAttributeDirectiveBinding()`. |

packages/fast-element/DECLARATIVE_HTML.md

@@ -358,15 +358,12 @@ You can pass the DOM event object, the execution context, or both as arguments.
 <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:
+**Arbitrary binding expressions** — any token that is not `$e` or `$c` 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 once per component. The warning includes the component name to help locate usage. Migrate to `$e`.
-> ```html
-> <button @click="{handleClick(e)}"></button>
-> ```
+Use `$e` for the DOM event object.
 
 ### Directives
 

packages/fast-element/DECLARATIVE_RENDERING.md

@@ -325,7 +325,7 @@ Event bindings such as `@keydown` and `@click` can be represented with hydration
 
 Example event binding:
 ```html
-<button @click="{handleClick(e)}">Button</button>
+<button @click="{handleClick($e)}">Button</button>
 ```
 
 Should result in:

packages/fast-element/MIGRATION.md

@@ -55,10 +55,30 @@ removed `@microsoft/fast-html` package.
 2. Update declarative utility imports such as `deepMerge` to
    `@microsoft/fast-element/declarative/utilities.js`.
 3. Keep importing core FAST Element APIs (for example `FASTElement`, `attr`,
-   `observable`) from `@microsoft/fast-element`.
+    `observable`) from `@microsoft/fast-element`.
 4. Do not switch to the root `@microsoft/fast-element` barrel for declarative
-   APIs; the declarative entrypoint owns the debug-message and hydratable-view
-   side effects.
+    APIs; the declarative entrypoint owns the debug-message and hydratable-view
+    side effects.
+
+## Declarative event handler `e` removal (v3)
+
+### Removed behavior
+
+| Removed | Replacement |
+|---|---|
+| Bare `e` event arguments in declarative event handlers | `$e` |
+| `TemplateParser.hasDeprecatedEventSyntax` | No replacement |
+
+Only `$e` and `$c` are reserved event handler arguments in declarative
+templates. Bare `e` now resolves like any other binding path on the current
+data source.
+
+### Migration steps
+
+1. Replace declarative event bindings such as
+   `@click="{handleClick(e)}"` with `@click="{handleClick($e)}"`.
+2. Remove any `TemplateParser.hasDeprecatedEventSyntax` checks or warnings from
+   custom tooling.
 
 ## Prerendered Content Optimization (v2 → v3)
 

packages/fast-element/README.md

@@ -102,6 +102,8 @@ TemplateElement.define({ name: "f-template" });
 Declarative utilities such as `deepMerge` are available from
 `@microsoft/fast-element/declarative/utilities.js`. See
 [`DECLARATIVE_HTML.md`](./DECLARATIVE_HTML.md) for declarative usage details.
+Declarative event bindings use `$e` for the DOM event object and `$c` for the
+execution context.
 
 ## Prerendered Content Optimization
 

packages/fast-element/docs/declarative/api-report.api.md

@@ -138,7 +138,6 @@ export class TemplateElement extends FASTElement {
 export class TemplateParser {
     // Warning: (ae-forgotten-export) The symbol "ViewTemplate" needs to be exported by the entry point declarative.d.ts
     createTemplate(strings: Array<string>, values: Array<any>): ViewTemplate<any, any>;
-    get hasDeprecatedEventSyntax(): boolean;
     parse(innerHTML: string, schema: Schema): ResolvedStringsAndValues;
 }
 

packages/fast-element/src/declarative/syntax.ts

@@ -6,7 +6,6 @@ interface Syntax {
     clientSideCloseExpression: string;
     executionContextAccessor: string;
     eventArgAccessor: string;
-    deprecatedEventArgAccessor: string;
     openExpression: string;
     closeExpression: string;
     unescapedOpenExpression: string;
@@ -26,7 +25,6 @@ export const {
     clientSideCloseExpression,
     clientSideOpenExpression,
     closeExpression,
-    deprecatedEventArgAccessor,
     eventArgAccessor,
     executionContextAccessor,
     openExpression,
@@ -41,7 +39,6 @@ export const {
     clientSideCloseExpression: "}",
     clientSideOpenExpression: "{",
     closeExpression: "}}",
-    deprecatedEventArgAccessor: "e",
     eventArgAccessor: "$e",
     executionContextAccessor: "$c",
     openExpression: "{{",

packages/fast-element/src/declarative/template-parser.ts

@@ -72,37 +72,18 @@ class StringsAccumulator {
  *
  * This class is intentionally stateless across invocations — all mutable
  * parsing state lives on the call stack or in the `TemplateResolutionContext`.
- * The only per-parse state is `_hasDeprecatedEventSyntax`, which is reset at
- * the start of each `parse()` call.
  *
  * The parsing pipeline is fully synchronous — no promises are allocated
  * during template resolution.
  */
 export class TemplateParser {
-    /**
-     * Whether the template contains deprecated "e" event argument usage.
-     * Set during template processing; checked after parsing to emit a
-     * single warning per template.
-     */
-    // TODO: remove per https://github.com/microsoft/fast/issues/7314
-    private _hasDeprecatedEventSyntax = false;
-
-    /**
-     * Whether the last parsed template contained deprecated "e" event syntax.
-     */
-    public get hasDeprecatedEventSyntax(): boolean {
-        return this._hasDeprecatedEventSyntax;
-    }
-
     /**
      * Parse declarative HTML into strings and values for ViewTemplate creation.
      * @param innerHTML - The transformed innerHTML to parse.
      * @param schema - The Schema instance for property tracking.
      * @returns The resolved strings and values.
      */
     public parse(innerHTML: string, schema: Schema): ResolvedStringsAndValues {
-        this._hasDeprecatedEventSyntax = false;
-
         return this.resolveStringsAndValues(null, innerHTML, {
             parentContext: null,
             level: 0,
@@ -370,14 +351,9 @@ export class TemplateParser {
 
         const parsedArgs = parseEventArgs(argsString);
 
-        if (parsedArgs.some(a => a.type === "deprecated-event")) {
-            this._hasDeprecatedEventSyntax = true;
-        }
-
         const argResolvers = parsedArgs.map((parsedArg): ((x: any, c: any) => any) => {
             switch (parsedArg.type) {
                 case "event":
-                case "deprecated-event":
                     return (_x, c) => c.event;
                 case "context":
                     return (_x, c) => c;

packages/fast-element/src/declarative/template.ts

@@ -16,7 +16,7 @@ import { Message } from "./interfaces.js";
 import { ObserverMap, type ObserverMapOption } from "./observer-map.js";
 import { Schema } from "./schema.js";
 import { TemplateParser } from "./template-parser.js";
-import { eventArgAccessor, transformInnerHTML } from "./utilities.js";
+import { transformInnerHTML } from "./utilities.js";
 
 /**
  * Checks whether a map option (observerMap or attributeMap) is enabled.
@@ -253,14 +253,6 @@ class TemplateElement extends FASTElement {
 
                 const { strings, values } = parser.parse(innerHTML, schema);
 
-                if (parser.hasDeprecatedEventSyntax) {
-                    console.warn(
-                        `[fast-element/declarative] Using "e" as an event argument is deprecated` +
-                            ` in component "${name}".` +
-                            ` Use "${eventArgAccessor}" instead.`,
-                    );
-                }
-
                 // Define the root properties cached in the observer map as observable (only if observerMap exists)
                 this.observerMap?.defineProperties();