feat(config): allow suppressing reserved event name warnings (#6748)

* feat(config): add support for suppressing warnings on reserved event names

* test(parse-events): update warning message for native DOM event name check

* fix(event-decorator): correct typo in JSDoc for validateEventName function

Author: deleonio

src/compiler/config/test/validate-config.spec.ts

@@ -129,6 +129,19 @@ describe('validation', () => {
     });
   });
 
+  describe('suppressReservedEventNameWarnings', () => {
+    it.each([true, false])('sets suppressReservedEventNameWarnings to %p when provided', (bool) => {
+      userConfig.suppressReservedEventNameWarnings = bool;
+      const { config } = validateConfig(userConfig, bootstrapConfig);
+      expect(config.suppressReservedEventNameWarnings).toBe(bool);
+    });
+
+    it('defaults suppressReservedEventNameWarnings to false', () => {
+      const { config } = validateConfig(userConfig, bootstrapConfig);
+      expect(config.suppressReservedEventNameWarnings).toBe(false);
+    });
+  });
+
   describe('enableCache', () => {
     it('set enableCache true', () => {
       userConfig.enableCache = true;

src/compiler/config/validate-config.ts

@@ -212,6 +212,7 @@ export const validateConfig = (
   setBooleanConfig(validatedConfig, 'validateTypes', null, !validatedConfig._isTesting);
   setBooleanConfig(validatedConfig, 'allowInlineScripts', null, true);
   setBooleanConfig(validatedConfig, 'suppressReservedPublicNameWarnings', null, false);
+  setBooleanConfig(validatedConfig, 'suppressReservedEventNameWarnings', null, false);
 
   if (!isString(validatedConfig.taskQueue)) {
     validatedConfig.taskQueue = 'async';

src/compiler/transformers/decorators-to-static/convert-decorators.ts

@@ -148,6 +148,7 @@ const visitClassDeclaration = (
     );
     stateDecoratorsToStatic(decoratedMembers, filteredMethodsAndFields, typeChecker, importAliasMap.get('State'));
     eventDecoratorsToStatic(
+      config,
       diagnostics,
       decoratedMembers,
       typeChecker,

src/compiler/transformers/decorators-to-static/event-decorator.ts

@@ -13,6 +13,7 @@ import {
 import { getDecoratorParameters, isDecoratorNamed } from './decorator-utils';
 
 export const eventDecoratorsToStatic = (
+  config: d.ValidatedConfig,
   diagnostics: d.Diagnostic[],
   decoratedProps: ts.ClassElement[],
   typeChecker: ts.TypeChecker,
@@ -22,7 +23,7 @@ export const eventDecoratorsToStatic = (
 ) => {
   const events = decoratedProps
     .filter(ts.isPropertyDeclaration)
-    .map((prop) => parseEventDecorator(diagnostics, typeChecker, program, prop, decoratorName))
+    .map((prop) => parseEventDecorator(config, diagnostics, typeChecker, program, prop, decoratorName))
     .filter((ev) => !!ev);
 
   if (events.length > 0) {
@@ -33,6 +34,7 @@ export const eventDecoratorsToStatic = (
 /**
  * Parse a single instance of Stencil's `@Event()` decorator and generate metadata for the class member that is
  * decorated
+ * @param config a user-supplied Stencil config
  * @param diagnostics a list of diagnostics used as a part of the parsing process. Any parse errors/warnings shall be
  * added to this collection
  * @param typeChecker an instance of the TypeScript type checker, used to generate information about the `@Event()` and
@@ -43,6 +45,7 @@ export const eventDecoratorsToStatic = (
  * @returns generated metadata for the class member decorated by `@Event()`, or `null` if none could be derived
  */
 const parseEventDecorator = (
+  config: d.ValidatedConfig,
   diagnostics: d.Diagnostic[],
   typeChecker: ts.TypeChecker,
   program: ts.Program,
@@ -64,7 +67,7 @@ const parseEventDecorator = (
   const symbol = typeChecker.getSymbolAtLocation(prop.name);
   const eventName = getEventName(eventOpts, memberName);
 
-  validateEventName(diagnostics, prop.name, eventName);
+  validateEventName(config, diagnostics, prop.name, eventName);
 
   const eventMeta = {
     method: memberName,
@@ -130,12 +133,18 @@ const getEventType = (type: ts.TypeNode): ts.TypeNode | null => {
  *
  * This function assumes that the name of the event has been determined prior to calling it
  *
+ * @param config a user-supplied Stencil config
  * @param diagnostics a list of diagnostics used as a part of the validation process. Any parse errors/warnings shall be
  * added to this collection
- * @param node the node in the AT containing the class member decorated with `@Event()`
+ * @param node the node in the AST containing the class member decorated with `@Event()`
  * @param eventName the name of the event
  */
-const validateEventName = (diagnostics: d.Diagnostic[], node: ts.Node, eventName: string): void => {
+const validateEventName = (
+  config: d.ValidatedConfig,
+  diagnostics: d.Diagnostic[],
+  node: ts.Node,
+  eventName: string,
+): void => {
   // this regex checks for a string that begins with a capital letter - e.g. 'AskJeeves', 'Zoo', 'Spotify'
   if (/^[A-Z]/.test(eventName)) {
     const diagnostic = buildWarn(diagnostics);
@@ -157,7 +166,7 @@ const validateEventName = (diagnostics: d.Diagnostic[], node: ts.Node, eventName
     return;
   }
 
-  if (DOM_EVENT_NAMES.has(eventName.toLowerCase())) {
+  if (!config.suppressReservedEventNameWarnings && DOM_EVENT_NAMES.has(eventName.toLowerCase())) {
     const diagnostic = buildWarn(diagnostics);
     diagnostic.messageText = `The event name conflicts with the "${eventName}" native DOM event name.`;
     augmentDiagnosticWithNode(diagnostic, node);

src/compiler/transformers/test/parse-events.spec.ts

@@ -240,4 +240,51 @@ describe('parse events', () => {
       });
     });
   });
+
+  describe('suppressReservedEventNameWarnings', () => {
+    it('should warn when using native DOM event name and flag is unset (default)', () => {
+      expect(() => {
+        transpileModule(
+          `
+            @Component({tag: 'cmp-a'})
+            export class CmpA {
+              @Event({ eventName: 'click' })
+              clickEvent: EventEmitter<void>;
+            }
+          `,
+        );
+      }).toThrow(/"click".*native DOM event/);
+    });
+
+    it('should not warn when using native DOM event name and flag is true', () => {
+      const t = transpileModule(
+        `
+          @Component({tag: 'cmp-a'})
+          export class CmpA {
+            @Event({ eventName: 'click' })
+            clickEvent: EventEmitter<void>;
+          }
+        `,
+        { suppressReservedEventNameWarnings: true },
+      );
+
+      expect(t.event).toEqual({
+        name: 'click',
+        method: 'clickEvent',
+        bubbles: true,
+        cancelable: true,
+        composed: true,
+        internal: false,
+        complexType: {
+          original: 'void',
+          resolved: 'void',
+          references: {},
+        },
+        docs: {
+          text: '',
+          tags: [],
+        },
+      });
+    });
+  });
 });

src/declarations/stencil-public-compiler.ts

@@ -160,6 +160,10 @@ export interface StencilConfig {
    * (for example, decorating a method named `focus` with `@Method()`). Defaults to `false`.
    */
   suppressReservedPublicNameWarnings?: boolean;
+  /**
+   * When `true`, Stencil will suppress diagnostics which warn about event names conflicting with native DOM event names. Defaults to `false`.
+   */
+  suppressReservedEventNameWarnings?: boolean;
   /**
    * When `true`, we will validate a project's `package.json` based on the output target the user has designated
    * as `isPrimaryPackageOutputTarget: true` in their Stencil config.

src/testing/mocks.ts

@@ -50,6 +50,7 @@ export function mockValidatedConfig(overrides: Partial<d.ValidatedConfig> = {}):
     srcDir: '/src',
     srcIndexHtml: 'src/index.html',
     suppressReservedPublicNameWarnings: false,
+    suppressReservedEventNameWarnings: false,
     sys: createTestingSystem(),
     testing: {},
     transformAliasedImportPaths: true,
@@ -108,6 +109,7 @@ export function mockConfig(overrides: Partial<d.UnvalidatedConfig> = {}): d.Unva
     rootDir,
     sourceMap: true,
     suppressReservedPublicNameWarnings: false,
+    suppressReservedEventNameWarnings: false,
     sys,
     testing: null,
     validateTypes: false,