feat(types): update types for v7 (#4186)

Co-authored-by: Nolan Lawson <nlawson@salesforce.com>

Author: wjhsf

.eslintrc

@@ -176,7 +176,7 @@
         },
         {
             // Not covered by any tsconfig, so typed rules won't work, but we don't need them anyway
-            "files": ["jest.config.js"],
+            "files": ["jest.config.js", "**/rollup.config.js"],
             "extends": ["plugin:@typescript-eslint/disable-type-checked"]
         },
         {

.github/workflows/unit.yml

@@ -62,6 +62,8 @@ jobs:
               run: yarn lint
             - name: Check the size of the LWC bundle
               run: yarn bundlesize
+            - name: Check types
+              run: yarn test:types
             - name: Run Jest tests
               run: yarn test:ci
             - name: Upload Jest coverage report

.gitignore

@@ -2,7 +2,6 @@
 -local-*
 .DS_Store
 dist/
-types/
 node_modules/
 coverage/
 .idea/

package.json

@@ -26,6 +26,7 @@
         "test:performance": "nx test @lwc/perf-benchmarks",
         "test:performance:best": "nx test:best @lwc/perf-benchmarks",
         "test:performance:best:ci": "nx test:best:ci @lwc/perf-benchmarks",
+        "test:types": "nx test @lwc/integration-types",
         "release:version": "./scripts/release/version.js"
     },
     "//": {

packages/@lwc/engine-core/src/framework/base-lightning-element.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, 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
@@ -56,7 +56,7 @@ import { getVMBeingRendered, isUpdatingTemplate, Template } from './template';
 import { HTMLElementConstructor } from './base-bridge-element';
 import { updateComponentValue } from './update-component-value';
 import { markLockerLiveObject } from './membrane';
-import { TemplateStylesheetFactories } from './stylesheet';
+import { Stylesheets } from './stylesheet';
 import { instrumentInstance } from './runtime-instrumentation';
 import { applyShadowMigrateMode } from './shadow-migration-mode';
 
@@ -143,7 +143,7 @@ export interface LightningElementConstructor {
     renderMode?: 'light' | 'shadow';
     formAssociated?: boolean;
     shadowSupportMode?: ShadowSupportMode;
-    stylesheets: TemplateStylesheetFactories;
+    stylesheets: Stylesheets;
 }
 
 type HTMLElementTheGoodParts = { toString: () => string } & Pick<
@@ -192,9 +192,17 @@ type RefNodes = { [name: string]: Element };
 
 const refsCache: WeakMap<RefVNodes, RefNodes> = new WeakMap();
 
+/**
+ * A `LightningElement` will always be attached to an [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement),
+ * rather than the more broad `Element` used by the generic shadow root interface.
+ */
+export interface LightningElementShadowRoot extends ShadowRoot {
+    readonly host: HTMLElement;
+}
+
 export interface LightningElement extends HTMLElementTheGoodParts, AccessibleElementProperties {
     constructor: LightningElementConstructor;
-    template: ShadowRoot | null;
+    template: LightningElementShadowRoot | null;
     refs: RefNodes | undefined;
     hostElement: Element;
     render(): Template;
@@ -273,7 +281,7 @@ export const LightningElement: LightningElementConstructor = function (
     return this;
 };
 
-function doAttachShadow(vm: VM): ShadowRoot {
+function doAttachShadow(vm: VM): LightningElementShadowRoot {
     const {
         elm,
         mode,
@@ -531,7 +539,7 @@ function warnIfInvokedDuringConstruction(vm: VM, methodOrPropName: string) {
         return getClassList(elm);
     },
 
-    get template(): ShadowRoot | null {
+    get template(): LightningElementShadowRoot | null {
         const vm = getAssociatedVM(this);
 
         if (process.env.NODE_ENV !== 'production') {

packages/@lwc/engine-core/src/framework/check-version-mismatch.ts

@@ -9,7 +9,7 @@ import { isNull, LWC_VERSION, LWC_VERSION_COMMENT_REGEX } from '@lwc/shared';
 import { logError } from '../shared/logger';
 
 import { Template } from './template';
-import { StylesheetFactory } from './stylesheet';
+import { Stylesheet } from './stylesheet';
 import { LightningElementConstructor } from './base-lightning-element';
 import { report, ReportingEventId } from './reporting';
 
@@ -30,10 +30,10 @@ if (process.env.NODE_ENV === 'test-karma-lwc') {
  * @param type
  */
 export function checkVersionMismatch(func: Template, type: 'template'): void;
-export function checkVersionMismatch(func: StylesheetFactory, type: 'stylesheet'): void;
+export function checkVersionMismatch(func: Stylesheet, type: 'stylesheet'): void;
 export function checkVersionMismatch(func: LightningElementConstructor, type: 'component'): void;
 export function checkVersionMismatch(
-    func: Template | StylesheetFactory | LightningElementConstructor,
+    func: Template | Stylesheet | LightningElementConstructor,
     type: 'template' | 'stylesheet' | 'component'
 ) {
     const versionMatcher = func.toString().match(LWC_VERSION_COMMENT_REGEX);

packages/@lwc/engine-core/src/framework/decorators/api.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, 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
@@ -13,15 +13,16 @@ import { getAssociatedVM } from '../vm';
 import { isUpdatingTemplate, getVMBeingRendered } from '../template';
 
 /**
- * The @api decorator marks public fields and public methods in
+ * The `@api` decorator marks public fields and public methods in
  * LWC Components. This function implements the internals of this
  * decorator.
- * @param target
- * @param propertyKey
- * @param descriptor
  */
-export default function api(target: any, propertyKey: string, descriptor: PropertyDescriptor): void;
-export default function api() {
+export default function api(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    value: unknown,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    context: ClassMemberDecoratorContext | string | symbol
+): void {
     if (process.env.NODE_ENV !== 'production') {
         assert.fail(`@api decorator can only be used as a decorator function.`);
     }

packages/@lwc/engine-core/src/framework/decorators/register.ts

@@ -59,19 +59,13 @@ interface RegisterDecoratorMeta {
     readonly fields?: string[];
 }
 
-const enum DescriptorType {
-    Method = 'method',
-    Accessor = 'accessor',
-    Field = 'field',
-}
-
-function getClassDescriptorType(descriptor: PropertyDescriptor): DescriptorType {
+function getClassDescriptorType(descriptor: PropertyDescriptor): string {
     if (isFunction(descriptor.value)) {
-        return DescriptorType.Method;
+        return 'method';
     } else if (isFunction(descriptor.set) || isFunction(descriptor.get)) {
-        return DescriptorType.Accessor;
+        return 'accessor';
     } else {
-        return DescriptorType.Field;
+        return 'field';
     }
 }
 

packages/@lwc/engine-core/src/framework/decorators/track.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, 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
@@ -15,19 +15,15 @@ import { updateComponentValue } from '../update-component-value';
 import { logError } from '../../shared/logger';
 
 /**
- * The @track decorator function marks field values as reactive in
+ * The `@track` decorator function marks field values as reactive in
  * LWC Components. This function can also be invoked directly
  * with any value to obtain the trackable version of the value.
- * @param target
- * @param propertyKey
- * @param descriptor
  */
 export default function track(
-    target: any,
-    propertyKey: string,
-    descriptor: PropertyDescriptor
-): any;
-export default function track(target: any): any {
+    value: unknown,
+    context: ClassMemberDecoratorContext | string | symbol
+): void;
+export default function track<T>(target: T): T {
     if (arguments.length === 1) {
         return getReactiveProxy(target);
     }

packages/@lwc/engine-core/src/framework/decorators/wire.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, 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
@@ -12,16 +12,22 @@ import { WireAdapterConstructor } from '../wiring';
 import { updateComponentValue } from '../update-component-value';
 
 /**
- * The @wire decorator wires fields and methods to a wire adapter in
- * LWC Components. This function implements the internals of this
- * decorator.
- * @param _adapter
- * @param _config
+ * Decorator factory to wire a property or method to a wire adapter data source.
+ * @param adapter the adapter used to provision data
+ * @param config configuration object for the adapter
+ * @returns A decorator function
+ * @example
+ * export default class WireExample extends LightningElement {
+ *   \@api bookId;
+ *   \@wire(getBook, { id: '$bookId'}) book;
+ * }
  */
 export default function wire(
-    _adapter: WireAdapterConstructor,
-    _config?: Record<string, any>
-): PropertyDecorator | MethodDecorator {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    adapter: WireAdapterConstructor,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    config?: Record<string, any>
+): (value: unknown, context: ClassMemberDecoratorContext | string | symbol) => void {
     if (process.env.NODE_ENV !== 'production') {
         assert.fail('@wire(adapter, config?) may only be used as a decorator.');
     }

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

@@ -123,17 +123,17 @@ function createComponentDef(Ctor: LightningElementConstructor): ComponentDef {
 
         if (
             !isUndefined(ctorShadowSupportMode) &&
-            ctorShadowSupportMode !== ShadowSupportMode.Any &&
-            ctorShadowSupportMode !== ShadowSupportMode.Default &&
-            ctorShadowSupportMode !== ShadowSupportMode.Native
+            ctorShadowSupportMode !== 'any' &&
+            ctorShadowSupportMode !== 'reset' &&
+            ctorShadowSupportMode !== 'native'
         ) {
             logError(
                 `Invalid value for static property shadowSupportMode: '${ctorShadowSupportMode}'`
             );
         }
 
         // TODO [#3971]: Completely remove shadowSupportMode "any"
-        if (ctorShadowSupportMode === ShadowSupportMode.Any) {
+        if (ctorShadowSupportMode === 'any') {
             logWarn(
                 `Invalid value 'any' for static property shadowSupportMode. 'any' is deprecated and will be removed in a future release--use 'native' instead.`
             );
@@ -202,8 +202,7 @@ function createComponentDef(Ctor: LightningElementConstructor): ComponentDef {
 
         if (
             isReportingEnabled() &&
-            (shadowSupportMode === ShadowSupportMode.Any ||
-                shadowSupportMode === ShadowSupportMode.Native)
+            (shadowSupportMode === 'any' || shadowSupportMode === 'native')
         ) {
             report(ReportingEventId.ShadowSupportModeUsage, {
                 tagName: Ctor.name,
@@ -342,21 +341,17 @@ const lightingElementDef: ComponentDef = {
     propsConfig: EmptyObject,
     methods: EmptyObject,
     renderMode: RenderMode.Shadow,
-    shadowSupportMode: ShadowSupportMode.Default,
+    shadowSupportMode: 'reset',
     formAssociated: undefined,
     wire: EmptyObject,
     bridge: BaseBridgeElement,
     template: defaultEmptyTemplate,
     render: LightningElement.prototype.render,
 };
 
-const enum PropDefType {
-    any = 'any',
-}
-
 interface PropDef {
     config: number;
-    type: PropDefType;
+    type: 'any';
     attr: string;
 }
 type PublicMethod = (...args: any[]) => any;
@@ -384,7 +379,7 @@ export function getComponentDef(Ctor: any): PublicComponentDef {
         // avoid leaking the reference to the public props descriptors
         publicProps[key] = {
             config: propsConfig[key] || 0, // a property by default
-            type: PropDefType.any, // no type inference for public services
+            type: 'any', // no type inference for public services
             attr: htmlPropertyToAttribute(key),
         };
     }

packages/@lwc/engine-core/src/framework/freeze-template.ts

@@ -22,7 +22,7 @@ import {
 } from '@lwc/shared';
 import { logWarnOnce } from '../shared/logger';
 import { Template } from './template';
-import { StylesheetFactory, TemplateStylesheetFactories } from './stylesheet';
+import { Stylesheet, Stylesheets } from './stylesheet';
 import { onReportingEnabled, report, ReportingEventId } from './reporting';
 
 // See @lwc/engine-core/src/framework/template.ts
@@ -111,7 +111,7 @@ function reportStylesheetViolation(prop: StylesheetProp) {
 
 // Warn if the user tries to mutate a stylesheets array, e.g.:
 // `tmpl.stylesheets.push(someStylesheetFunction)`
-function warnOnArrayMutation(stylesheets: TemplateStylesheetFactories) {
+function warnOnArrayMutation(stylesheets: Stylesheets) {
     // We can't handle users calling Array.prototype.slice.call(tmpl.stylesheets), but
     // we can at least warn when they use the most common mutation methods.
     for (const prop of ARRAY_MUTATION_METHODS) {
@@ -126,7 +126,7 @@ function warnOnArrayMutation(stylesheets: TemplateStylesheetFactories) {
 
 // Warn if the user tries to mutate a stylesheet factory function, e.g.:
 // `stylesheet.$scoped$ = true`
-function warnOnStylesheetFunctionMutation(stylesheet: StylesheetFactory) {
+function warnOnStylesheetFunctionMutation(stylesheet: Stylesheet) {
     for (const prop of STYLESHEET_PROPS) {
         let value = (stylesheet as any)[prop];
         defineProperty(stylesheet, prop, {
@@ -144,7 +144,7 @@ function warnOnStylesheetFunctionMutation(stylesheet: StylesheetFactory) {
 }
 
 // Warn on either array or stylesheet (function) mutation, in a deeply-nested array
-function trackStylesheetsMutation(stylesheets: TemplateStylesheetFactories) {
+function trackStylesheetsMutation(stylesheets: Stylesheets) {
     traverseStylesheets(stylesheets, (subStylesheets) => {
         if (isArray(subStylesheets)) {
             warnOnArrayMutation(subStylesheets);
@@ -155,16 +155,16 @@ function trackStylesheetsMutation(stylesheets: TemplateStylesheetFactories) {
 }
 
 // Deeply freeze the entire array (of arrays) of stylesheet factory functions
-function deepFreeze(stylesheets: TemplateStylesheetFactories) {
+function deepFreeze(stylesheets: Stylesheets) {
     traverseStylesheets(stylesheets, (subStylesheets) => {
         freeze(subStylesheets);
     });
 }
 
 // Deep-traverse an array (of arrays) of stylesheet factory functions, and call the callback for every array/function
 function traverseStylesheets(
-    stylesheets: TemplateStylesheetFactories,
-    callback: (subStylesheets: TemplateStylesheetFactories | StylesheetFactory) => void
+    stylesheets: Stylesheets,
+    callback: (subStylesheets: Stylesheets | Stylesheet) => void
 ) {
     callback(stylesheets);
     for (let i = 0; i < stylesheets.length; i++) {