feat: add lwc:on directive (#5344)

* test(integration-karma): add integration tests for lwc:on directive

* feat(engine-core): add optional dynamicOn property to VNodeData interface

* feat(engine-core): add patching utilities for dynamic event listeners

* feat(engine-core): update hydration and rendering to patch dynamic event listeners

* feat(shared): export Detached Object.prototype.propertyIsEnumerable from language.ts

* fix(engine-core): use propertyIsEnumerable from @lwc/shared

* feat(template-compiler): add type and helper functions for OnDirective AST node

* feat: throw error when lwc:on is used on a non-root <template> element

* feat: add parsing of lwc:on directive

* feat: throw error when declarative event listeners are  used alongside lwc:on

* feat(template-compiler): add code generation for lwc:on directive

* feat(engine-core): add basic implementation of freeze render API

* docs(engine-core): add comment in patchDynamicEventListeners regarding freezing assumption

* Apply suggestions from code review

Add comments, improve readability of statements, correct copyright year

Co-authored-by: Dale Bustad <[email protected]>
Co-authored-by: Will Harney <[email protected]>

* test(integration-karma): fix ignored properties and event type case tests

* test(integration-karma): add tests to verify re-rendering behaviour

* test(integration-karma): add a seperate test for object passed as public property

add a seperate test for object passed as public property and refactors other tests to be independent

* fix: fix @api issues by removing freeze api and adding copy api

* style: apply suggestion from code review - consistent error names

* test(integration-karma): add missing test component x/publicProp

* style(engine-core): rename variables related to patching and add comments for better readability

* fix(engine-core): add missing negation operator in patchDynamicEventListener

* docs(template-compiler): add comment explaining the check used to know lwc:on is used with onfoo

* docs(template-compiler): add comment explaining onDirective codegen in databag

* fix(engine-core): change prevInp to prevOut in comparision

* test(integration-karma): expand re-render tests to include the case when object is mutated

* test(template-compiler): add snapshot tests for template-compiler

* test(integration-karma): move catchUnhandledRejectionsAndError inside the specific describe

Having in top-level may cause false success

* test(integration-karma): add re-render tests for lwc:on used inside for:each loop

* test(integration-karma): correct 'this' in rerenderLoop.js

* fix: move copy api's work to codeGen and patching

* refactor: remove dead code

* fix: Apply suggestions from code review - <> in error message

Co-authored-by: Will Harney <[email protected]>

* feat: add template-compiler flag enableLwcOn

* test(integration-karma): modify test to include <> in error message

* test(integration-karma): remove console log spy

* perf(engine-core): change delete obj[x] to obj[x] = undefined

* test(integration-karma): simplify tests by re-using spies

* chore: increase allowed bundlesize limit

* test(template-compiler): fix error codes in snapshots

* fix: change throw new Error to logError

* docs(engine-core): add comments explaining dynamicOn has null proto and own enumerbale props

* test(integration-karma): add tests for objects with computed key

* fix(engine-core): modify patch logic to differentiate prop value = undefined and prop not existing

* test(integration-karma): add tests where arg has property with value non-function/ whose eval throws

* test(integration-karma): simplify value evaluation throws tests

* chore: bump CI

* fix: integration tests in Firefox

---------

Co-authored-by: Gaurav Kochar <[email protected]>
Co-authored-by: Will Harney <[email protected]>

Author: 3 people

packages/@lwc/compiler/src/options.ts

@@ -125,6 +125,8 @@ export interface TransformOptions {
     customRendererConfig?: CustomRendererConfig;
     /** @deprecated Ignored by compiler. `lwc:spread` is always enabled. */
     enableLwcSpread?: boolean;
+    /** Flag to enable usage of dynamic event listeners (lwc:on) directive in HTML template */
+    enableLwcOn?: boolean;
     /** Set to true if synthetic shadow DOM support is not needed, which can result in smaller/faster output. */
     disableSyntheticShadowSupport?: boolean;
     /**
@@ -148,6 +150,7 @@ type OptionalTransformKeys =
     | 'scopedStyles'
     | 'customRendererConfig'
     | 'enableLwcSpread'
+    | 'enableLwcOn'
     | 'enableLightningWebSecurityTransforms'
     | 'enableDynamicComponents'
     | 'experimentalDynamicDirective'

packages/@lwc/compiler/src/transformers/template.ts

@@ -40,6 +40,7 @@ export default function templateTransform(
         customRendererConfig,
         enableDynamicComponents,
         experimentalDynamicDirective: deprecatedDynamicDirective,
+        enableLwcOn,
         instrumentation,
         namespace,
         name,
@@ -61,6 +62,7 @@ export default function templateTransform(
             enableStaticContentOptimization,
             customRendererConfig,
             enableDynamicComponents,
+            enableLwcOn,
             instrumentation,
             apiVersion,
             disableSyntheticShadowSupport,

packages/@lwc/engine-core/src/framework/hydration.ts

@@ -50,6 +50,7 @@ import { VNodeType, isVStaticPartElement } from './vnodes';
 
 import { patchProps } from './modules/props';
 import { applyEventListeners } from './modules/events';
+import { patchDynamicEventListeners } from './modules/dynamic-events';
 import { hydrateStaticParts, traverseAndSetElements } from './modules/static-parts';
 import { getScopeTokenClass } from './stylesheet';
 import { renderComponent } from './component';
@@ -522,6 +523,7 @@ function handleMismatch(node: Node, vnode: VNode, renderer: RendererAPI): Node |
 
 function patchElementPropsAndAttrsAndRefs(vnode: VBaseElement, renderer: RendererAPI) {
     applyEventListeners(vnode, renderer);
+    patchDynamicEventListeners(null, vnode, renderer, vnode.owner);
     patchProps(null, vnode, renderer);
     // The `refs` object is blown away in every re-render, so we always need to re-apply them
     applyRefs(vnode, vnode.owner);

packages/@lwc/engine-core/src/framework/modules/dynamic-events.ts

@@ -0,0 +1,105 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import { isUndefined } from '@lwc/shared';
+import { EmptyObject } from '../utils';
+import { invokeEventListener } from '../invoker';
+import { logError } from '../../shared/logger';
+import type { VM } from '../vm';
+import type { VBaseElement } from '../vnodes';
+import type { RendererAPI } from '../renderer';
+
+export function patchDynamicEventListeners(
+    oldVnode: VBaseElement | null,
+    vnode: VBaseElement,
+    renderer: RendererAPI,
+    owner: VM
+) {
+    const {
+        elm,
+        data: { dynamicOn, dynamicOnRaw },
+        sel,
+    } = vnode;
+
+    // dynamicOn : A cloned version of the object passed to lwc:on, with null prototype and only its own enumerable properties.
+    const oldDynamicOn = oldVnode?.data?.dynamicOn ?? EmptyObject;
+    const newDynamicOn = dynamicOn ?? EmptyObject;
+
+    // dynamicOnRaw : object passed to lwc:on
+    // Compare dynamicOnRaw to check if same object is passed to lwc:on
+    const isObjectSame = oldVnode?.data?.dynamicOnRaw === dynamicOnRaw;
+
+    const { addEventListener, removeEventListener } = renderer;
+    const attachedEventListeners = getAttachedEventListeners(owner, elm!);
+
+    // Properties that are present in 'oldDynamicOn' but not in 'newDynamicOn'
+    for (const eventType in oldDynamicOn) {
+        if (!(eventType in newDynamicOn)) {
+            // log error if same object is passed
+            if (isObjectSame && process.env.NODE_ENV !== 'production') {
+                logError(
+                    `Detected mutation of property '${eventType}' in the object passed to lwc:on for <${sel}>. Reusing the same object with modified properties is prohibited. Please pass a new object instead.`,
+                    owner
+                );
+            }
+
+            // Remove listeners that were attached previously but don't have a corresponding property in `newDynamicOn`
+            const attachedEventListener = attachedEventListeners[eventType];
+            removeEventListener(elm, eventType, attachedEventListener!);
+            attachedEventListeners[eventType] = undefined;
+        }
+    }
+
+    // Ensure that the event listeners that are attached match what is present in `newDynamicOn`
+    for (const eventType in newDynamicOn) {
+        const typeExistsInOld = eventType in oldDynamicOn;
+        const newCallback = newDynamicOn[eventType];
+
+        // Skip if callback hasn't changed
+        if (typeExistsInOld && oldDynamicOn[eventType] === newCallback) {
+            continue;
+        }
+
+        // log error if same object is passed
+        if (isObjectSame && process.env.NODE_ENV !== 'production') {
+            logError(
+                `Detected mutation of property '${eventType}' in the object passed to lwc:on for <${sel}>. Reusing the same object with modified properties is prohibited. Please pass a new object instead.`,
+                owner
+            );
+        }
+
+        // Remove listener that was attached previously
+        if (typeExistsInOld) {
+            const attachedEventListener = attachedEventListeners[eventType];
+            removeEventListener(elm, eventType, attachedEventListener!);
+        }
+
+        // Bind new callback to owner component and add it as listener to element
+        const newBoundEventListener = bindEventListener(owner, newCallback);
+        addEventListener(elm, eventType, newBoundEventListener);
+
+        // Store the newly added eventListener
+        attachedEventListeners[eventType] = newBoundEventListener;
+    }
+}
+
+function getAttachedEventListeners(
+    vm: VM,
+    elm: Element
+): Record<string, EventListener | undefined> {
+    let attachedEventListeners = vm.attachedEventListeners.get(elm);
+    if (isUndefined(attachedEventListeners)) {
+        attachedEventListeners = {};
+        vm.attachedEventListeners.set(elm, attachedEventListeners);
+    }
+    return attachedEventListeners;
+}
+
+function bindEventListener(vm: VM, fn: EventListener): EventListener {
+    return function (event: Event) {
+        invokeEventListener(vm, fn, vm.component, event);
+    };
+}

packages/@lwc/engine-core/src/framework/rendering.ts

@@ -53,6 +53,7 @@ import { patchProps } from './modules/props';
 import { patchClassAttribute } from './modules/computed-class-attr';
 import { patchStyleAttribute } from './modules/computed-style-attr';
 import { applyEventListeners } from './modules/events';
+import { patchDynamicEventListeners } from './modules/dynamic-events';
 import { applyStaticClassAttribute } from './modules/static-class-attr';
 import { applyStaticStyleAttribute } from './modules/static-style-attr';
 import { applyRefs } from './modules/refs';
@@ -586,6 +587,7 @@ function patchElementPropsAndAttrsAndRefs(
     }
 
     const { owner } = vnode;
+    patchDynamicEventListeners(oldVnode, vnode, renderer, owner);
     // Attrs need to be applied to element before props IE11 will wipe out value on radio inputs if
     // value is set before type=radio.
     patchClassAttribute(oldVnode, vnode, renderer);

packages/@lwc/engine-core/src/framework/vm.ts

@@ -135,6 +135,8 @@ export interface VM<N = HostNode, E = HostElement> {
     readonly owner: VM<N, E> | null;
     /** References to elements rendered using lwc:ref (template refs) */
     refVNodes: RefVNodes | null;
+    /** event listeners added to elements corresponding to functions provided by lwc:on */
+    attachedEventListeners: WeakMap<Element, Record<string, EventListener | undefined>>;
     /** Whether or not the VM was hydrated */
     readonly hydrated: boolean;
     /** Rendering operations associated with the VM */
@@ -344,6 +346,7 @@ export function createVM<HostNode, HostElement>(
         mode,
         owner,
         refVNodes: null,
+        attachedEventListeners: new WeakMap(),
         children: EmptyArray,
         aChildren: EmptyArray,
         velements: EmptyArray,

packages/@lwc/engine-core/src/framework/vnodes.ts

@@ -153,6 +153,8 @@ export interface VNodeData {
     readonly styleDecls?: ReadonlyArray<[string, string, boolean]>;
     readonly context?: Readonly<Record<string, Readonly<Record<string, any>>>>;
     readonly on?: Readonly<Record<string, (event: Event) => any>>;
+    readonly dynamicOn?: Readonly<Record<string, (event: Event) => any>>; // clone of object passed to lwc:on, used to patch event listeners
+    readonly dynamicOnRaw?: Readonly<Record<string, (event: Event) => any>>; // object passed to lwc:on, used to verify whether object reference has changed
     readonly svg?: boolean;
     readonly renderer?: RendererAPI;
 }

packages/@lwc/errors/src/compiler/error-info/index.ts

@@ -5,7 +5,7 @@
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
  */
 /**
- * Next error code: 1203
+ * Next error code: 1207
  */
 
 export * from './compiler';

packages/@lwc/errors/src/compiler/error-info/template-transform.ts

@@ -947,4 +947,36 @@ export const ParserDiagnostics = {
         level: DiagnosticLevel.Warning,
         url: '',
     },
+
+    INVALID_LWC_ON_ELEMENT: {
+        code: 1203,
+        message:
+            'Invalid lwc:on usage on element "{0}". The directive can\'t be used on a template element.',
+        level: DiagnosticLevel.Error,
+        url: '',
+    },
+
+    INVALID_LWC_ON_LITERAL_PROP: {
+        code: 1204,
+        message:
+            'Invalid lwc:on usage on element "{0}". The directive binding must be an expression.',
+        level: DiagnosticLevel.Error,
+        url: '',
+    },
+
+    INVALID_LWC_ON_WITH_DECLARATIVE_LISTENERS: {
+        code: 1205,
+        message:
+            'Invalid lwc:on usage on element "{0}". It is not permitted to use declarative event listeners alongside lwc:on',
+        level: DiagnosticLevel.Error,
+        url: '',
+    },
+
+    INVALID_LWC_ON_OPTS: {
+        code: 1206,
+        message:
+            'Invalid lwc:on usage. The `lwc:on` directive must be enabled in order to use this feature.',
+        level: DiagnosticLevel.Error,
+        url: '',
+    },
 };

packages/@lwc/integration-karma/scripts/karma-plugins/lwc.js

@@ -58,6 +58,7 @@ function createPreprocessor(config, emitter, logger) {
                     strict: true,
                 },
                 enableDynamicComponents: true,
+                enableLwcOn: true,
                 experimentalComplexExpressions,
                 enableStaticContentOptimization: !DISABLE_STATIC_CONTENT_OPTIMIZATION,
                 disableSyntheticShadowSupport: DISABLE_SYNTHETIC_SHADOW_SUPPORT_IN_COMPILER,