diff --git a/.github/ISSUE_TEMPLATE/Bug_report.md b/.github/ISSUE_TEMPLATE/Bug_report.md index 06c30ad266..473bff3028 100644 --- a/.github/ISSUE_TEMPLATE/Bug_report.md +++ b/.github/ISSUE_TEMPLATE/Bug_report.md @@ -42,7 +42,7 @@ versions < 0.17: "lwc-engine": "0.16.8" versions >= 0.17: "lwc-engine": "0.17.2" --> -- LWC: x.x.x +- LWC: x.x.x **Possible Solution** diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index bed6b52116..0c80cbb5b2 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -13,8 +13,8 @@ Remove the incorrect item for the list. --> -- 😮‍💨 No, it does not introduce a breaking change. -- 💔 Yes, it does introduce a breaking change. +- 😮‍💨 No, it does not introduce a breaking change. +- 💔 Yes, it does introduce a breaking change. @@ -33,8 +33,8 @@ Remove the incorrect item from the list. --> -- 🤞 No, it does not introduce an observable change. -- 🔬 Yes, it does include an observable change. +- 🤞 No, it does not introduce an observable change. +- 🔬 Yes, it does include an observable change. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index b5d6ac7cc0..7f547bd236 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -35,23 +35,23 @@ socioeconomic status, or other similar personal characteristics. Examples of behavior that contributes to creating a positive environment include: -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Gracefully accepting constructive criticism -- Focusing on what is best for the community -- Showing empathy toward other community members +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy toward other community members Examples of unacceptable behavior by participants include: -- The use of sexualized language or imagery and unwelcome sexual attention or - advances -- Personal attacks, insulting/derogatory comments, or trolling -- Public or private harassment -- Publishing, or threatening to publish, others' private information—such as - a physical or electronic address—without explicit permission -- Other conduct which could reasonably be considered inappropriate in a - professional setting -- Advocating for or encouraging any of the above behaviors +- The use of sexualized language or imagery and unwelcome sexual attention or + advances +- Personal attacks, insulting/derogatory comments, or trolling +- Public or private harassment +- Publishing, or threatening to publish, others' private information—such as + a physical or electronic address—without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting +- Advocating for or encouraging any of the above behaviors ## Our Responsibilities diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 58aafb8e94..764d8ed5e6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,18 +2,18 @@ We want to encourage the developer community to contribute to Lightning Web Components. This guide has instructions to install, build, test and contribute to the framework. -- [Requirements](#requirements) -- [Installation](#installation) -- [Building LWC](#building-lwc) -- [Testing](#testing) -- [Git Workflow](#git-workflow) +- [Requirements](#requirements) +- [Installation](#installation) +- [Building LWC](#building-lwc) +- [Testing](#testing) +- [Git Workflow](#git-workflow) Before you start, familiarize yourself with [Lightning Web Components](https://lwc.dev/guide/introduction). ## Requirements -- [Node](https://nodejs.org/) -- [Yarn](https://yarnpkg.com/) +- [Node](https://nodejs.org/) +- [Yarn](https://yarnpkg.com/) This project uses [Volta](https://volta.sh/) to ensure that all the contributors share the same version of `Node` and `Yarn` for development. If you are considering making frequent contributions to this project, we recommend installing this tool as well. Otherwise, check the `volta` field in `package.json` to see which versions to use. @@ -94,8 +94,8 @@ Test fixtures are file-based tests that are executed using a helper called [`tes When developing LWC, use integration testing to ensure functionality is correctly reflected in the browser. This repo has two integration test suites. -- @lwc/integration-karma: Contains all integration tests that can run with javascript only. For information about usage and contribution, refer to this [documentation][integration-karma-readme]. -- @lwc/integration-tests: Contains all other integration tests that require web driver API support (e.g., focus, keyboard navigation). For information about usage and contribution, refer to this [documentation][integration-test-readme]. +- @lwc/integration-karma: Contains all integration tests that can run with javascript only. For information about usage and contribution, refer to this [documentation][integration-karma-readme]. +- @lwc/integration-tests: Contains all other integration tests that require web driver API support (e.g., focus, keyboard navigation). For information about usage and contribution, refer to this [documentation][integration-test-readme]. To run the Karma tests from the root: @@ -132,7 +132,7 @@ This will check that the minified bundle sizes don't exceed our thresholds. Our LWC relies on type annotations. -- Make sure your editor supports [typescript](https://www.typescriptlang.org/). +- Make sure your editor supports [typescript](https://www.typescriptlang.org/). ### ESLint @@ -297,17 +297,17 @@ If the commit reverts a previous commit, it should begin with `revert: `, follow Must be one of the following: -- **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) -- **chore**: Other changes that don't modify src or test files -- **ci**: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) -- **docs**: Documentation only changes -- **feat**: A new feature -- **fix**: A bug fix -- **perf**: A code change that improves performance -- **refactor**: A code change that neither fixes a bug nor adds a feature -- **revert**: Reverts a previous commit -- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) -- **test**: Adding missing tests or correcting existing tests +- **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) +- **chore**: Other changes that don't modify src or test files +- **ci**: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) +- **docs**: Documentation only changes +- **feat**: A new feature +- **fix**: A bug fix +- **perf**: A code change that improves performance +- **refactor**: A code change that neither fixes a bug nor adds a feature +- **revert**: Reverts a previous commit +- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) +- **test**: Adding missing tests or correcting existing tests #### Commit Scope @@ -315,18 +315,18 @@ The scope should be the name of the npm package affected, as perceived by the pe There are currently a few exceptions to the "use package name" rule: -- **packaging**: used for changes that change the npm package layout in all of our packages, e.g. public path changes, package.json changes done to all packages, d.ts file/format changes, changes to bundles, etc. -- **changelog**: used for updating the release notes in CHANGELOG.md -- **lwc docs**: used for docs related changes within the lwc/docs directory of the repo -- none/empty string: useful for `style`, `test` and `refactor` changes that are done across all packages (e.g. `style: add missing semicolons`) +- **packaging**: used for changes that change the npm package layout in all of our packages, e.g. public path changes, package.json changes done to all packages, d.ts file/format changes, changes to bundles, etc. +- **changelog**: used for updating the release notes in CHANGELOG.md +- **lwc docs**: used for docs related changes within the lwc/docs directory of the repo +- none/empty string: useful for `style`, `test` and `refactor` changes that are done across all packages (e.g. `style: add missing semicolons`) #### Commit Subject The subject contains a succinct description of the change: -- use the imperative, present tense: "change" not "changed" nor "changes" -- don't capitalize first letter -- no dot (.) at the end +- use the imperative, present tense: "change" not "changed" nor "changes" +- don't capitalize first letter +- no dot (.) at the end #### Commit Body @@ -350,17 +350,17 @@ The footer should contain any information about **Breaking Changes** and is also **Potential pitfalls:** When submitting changes to the LWC framework, there are several important considerations to keep in mind to ensure that your changes are reviewed & accepted. -- The LWC framework makes strong guarantees about backwards compatibility to those that use our framework. Any changes that compromise these guarantees are unlikely to be accepted as-is. -- If your change causes a test to fail in unit or integration tests, it is unlikely that your submission will be accepted as-is. -- Certain parts of the codebase are particularly susceptible to breaking changes. This includes the browser runtime (`engine-core` and `engine-dom`), as well as the compiler (`compiler`, `style-compiler`, `template-compiler`). -- Some areas of the codebase are less mature and undergoing active development. Areas related to SSR, including the server-side runtime (`engine-server`), fall under this category. +- The LWC framework makes strong guarantees about backwards compatibility to those that use our framework. Any changes that compromise these guarantees are unlikely to be accepted as-is. +- If your change causes a test to fail in unit or integration tests, it is unlikely that your submission will be accepted as-is. +- Certain parts of the codebase are particularly susceptible to breaking changes. This includes the browser runtime (`engine-core` and `engine-dom`), as well as the compiler (`compiler`, `style-compiler`, `template-compiler`). +- Some areas of the codebase are less mature and undergoing active development. Areas related to SSR, including the server-side runtime (`engine-server`), fall under this category. **Definition of done:** Especially when making large changes to the codebase, certain complementary work must be undertaken for the desired changes to be considered. When making a submission please adhere to the following: -- All pre-existing unit- & integration- tests must pass. -- If you modify a pre-existing test to accommodate your changes, a thorough reasoning must be proactively provided in the PR. -- Test coverage should not decline – if you add code paths, add corresponding tests. -- If your tests have the potential to negatively impact performance, provide a before & after comparison of performance using the test collateral provided in the repo. +- All pre-existing unit- & integration- tests must pass. +- If you modify a pre-existing test to accommodate your changes, a thorough reasoning must be proactively provided in the PR. +- Test coverage should not decline – if you add code paths, add corresponding tests. +- If your tests have the potential to negatively impact performance, provide a before & after comparison of performance using the test collateral provided in the repo. It's also worth noting that not all submissions will be accepted, even if all the above criteria are met. There may be constraints in the larger Salesforce ecosystem that prevent certain changes. If your submission is likely to change large parts of the codebase, please open an issue preemptively so that the design can be discussed. diff --git a/package.json b/package.json index dff35cd3bd..5bdb8ae6d8 100644 --- a/package.json +++ b/package.json @@ -34,10 +34,10 @@ }, "devDependencies": { "@commitlint/cli": "^19.6.0", - "@eslint/js": "9.15.0", + "@eslint/js": "9.16.0", "@lwc/eslint-plugin-lwc-internal": "link:./scripts/eslint-plugin", "@lwc/test-utils-lwc-internals": "link:./scripts/test-utils", - "@nx/js": "20.1.3", + "@nx/js": "20.1.4", "@rollup/plugin-commonjs": "^28.0.1", "@rollup/plugin-inject": "^5.0.5", "@rollup/plugin-node-resolve": "^15.3.0", @@ -47,31 +47,31 @@ "@swc/core": "~1.9.3", "@swc/helpers": "~0.5.15", "@types/babel__core": "^7.20.5", - "@types/node": "^22.9.3", - "@vitest/coverage-v8": "^2.1.5", - "@vitest/eslint-plugin": "^1.1.10", - "@vitest/ui": "^2.1.5", + "@types/node": "^22.10.1", + "@vitest/coverage-v8": "^2.1.7", + "@vitest/eslint-plugin": "^1.1.14", + "@vitest/ui": "^2.1.7", "bytes": "^3.1.2", "es-module-lexer": "^1.5.4", - "eslint": "9.15.0", + "eslint": "9.16.0", "eslint-config-flat-gitignore": "^0.3.0", "eslint-plugin-header": "^3.1.1", "eslint-plugin-import": "^2.31.0", "glob": "^11.0.0", - "globals": "^15.12.0", + "globals": "^15.13.0", "husky": "^9.1.7", "isbinaryfile": "^5.0.4", "jsdom": "^25.0.1", "lint-staged": "^15.2.10", - "magic-string": "^0.30.13", - "nx": "20.1.3", - "prettier": "^3.3.3", - "rollup": "^4.27.4", + "magic-string": "^0.30.14", + "nx": "20.1.4", + "prettier": "^3.4.1", + "rollup": "^4.28.0", "terser": "^5.36.0", "tslib": "^2.8.1", "typescript": "5.4.5", - "typescript-eslint": "8.15.0", - "vitest": "^2.1.5" + "typescript-eslint": "8.16.0", + "vitest": "^2.1.7" }, "lint-staged": { "*.{js,mjs,ts}": "eslint", diff --git a/packages/@lwc/babel-plugin-component/README.md b/packages/@lwc/babel-plugin-component/README.md index 8d71abb48d..dd1404bbac 100644 --- a/packages/@lwc/babel-plugin-component/README.md +++ b/packages/@lwc/babel-plugin-component/README.md @@ -4,15 +4,15 @@ This babel plugin does the following transform: -- Global decorator transform: - - Transform `@api` decorator to `publicProperties` and `publicMethods` static properties. - - Transform `@wire` decorator to `wire` static property. - - Transform `@track` decorator to `track` static property. -- LWC component class sugar syntax: - - Check for misspelled lifecycle hooks. - - Import and inject `render` from a collocated template if a component class doesn't already implement a `render` method. -- Optimization: - - If the compiler inject the default template a component, it will also wire the template style to the component. +- Global decorator transform: + - Transform `@api` decorator to `publicProperties` and `publicMethods` static properties. + - Transform `@wire` decorator to `wire` static property. + - Transform `@track` decorator to `track` static property. +- LWC component class sugar syntax: + - Check for misspelled lifecycle hooks. + - Import and inject `render` from a collocated template if a component class doesn't already implement a `render` method. +- Optimization: + - If the compiler inject the default template a component, it will also wire the template style to the component. ## Installation @@ -42,11 +42,11 @@ const { code } = babel.transformSync(source, { ## Options -- `name` (type: `string`, optional) - name of the component, e.g. `foo` in `x/foo`. -- `namespace` (type: `string`, optional) - namepace of the component, e.g. `x` in `x/foo`. -- `isExplicitImport` (type: `boolean`, optional) - true if this is an explicit import. -- `dynamicImports` (type: `object`, optional) - see below: - - `loader` (type: `string`, optional) - loader to use at runtime. - - `strictSpecifier` (type: `boolean`, optional) - true if a strict specifier should be used. -- `instrumentation` (type: `InstrumentationObject`, optional) - instrumentation object to gather metrics and non-error logs for internal use. See the `@lwc/errors` package for details on the interface. -- `apiVersion` (type: `number`, optional) - API version to associate with the compiled component. +- `name` (type: `string`, optional) - name of the component, e.g. `foo` in `x/foo`. +- `namespace` (type: `string`, optional) - namepace of the component, e.g. `x` in `x/foo`. +- `isExplicitImport` (type: `boolean`, optional) - true if this is an explicit import. +- `dynamicImports` (type: `object`, optional) - see below: + - `loader` (type: `string`, optional) - loader to use at runtime. + - `strictSpecifier` (type: `boolean`, optional) - true if a strict specifier should be used. +- `instrumentation` (type: `InstrumentationObject`, optional) - instrumentation object to gather metrics and non-error logs for internal use. See the `@lwc/errors` package for details on the interface. +- `apiVersion` (type: `number`, optional) - API version to associate with the compiled component. diff --git a/packages/@lwc/compiler/README.md b/packages/@lwc/compiler/README.md index 5bc815b4e2..18ad26a7d6 100644 --- a/packages/@lwc/compiler/README.md +++ b/packages/@lwc/compiler/README.md @@ -36,36 +36,36 @@ const { code } = transformSync(source, filename, options); **Parameters:** -- `source` (string, required) - the source to be transformed. Can be the content of a JavaScript, HTML, or CSS file. -- `filename` (string, required) - the source filename with extension. -- `options` (object, required) - the transformation options. The `name` and the `namespace` of the component is a minimum required for transformation. - - `name` (type: `string`, required) - name of the component, e.g. `foo` in `x/foo`. - - `namespace` (type: `string`, required) - namespace of the component, e.g. `x` in `x/foo`. - - `stylesheetConfig` (type: `object`, default: `{}`) - Deprecated. Ignored by compiler. - - `experimentalDynamicComponent` (type: `DynamicImportConfig`, default: `null`) - The configuration to pass to `@lwc/compiler`. - - `experimentalDynamicDirective` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/template-compiler` to enable deprecated dynamic components. - - `enableDynamicComponents` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/template-compiler` to enable dynamic components. - - `outputConfig` (type: `object`, optional) - see below: - - `sourcemap` (type: `boolean` | `'inline'`, optional) - if `true`, a sourcemap is generated for the transformed file. If `'inline'`, an inline sourcemap is generated and appended to the transformed file. - - `minify` (type: `boolean`, optional, deprecated) - this option has no effect. - - `experimentalComplexExpressions` (type: `boolean`, optional) - set to true to enable use of (a subset of) JavaScript expressions in place of template bindings. Passed to `@lwc/template-compiler`. - - `isExplicitImport` (type: `boolean`, optional) - true if this is an explicit import, passed to `@lwc/babel-plugin-component`. - - `preserveHtmlComments` (type: `boolean`, default: `false`) - The configuration to pass to the `@lwc/template-compiler`. - - `scopedStyles` (type: `boolean`, optional) - True if the CSS file being compiled is a scoped stylesheet. Passed to `@lwc/style-compiler`. - - `enableStaticContentOptimization` (type: `boolean`, optional) - True if the static content optimization should be enabled. Passed to `@lwc/template-compiler`. - - `customRendererConfig` (type: `object`, optional) - custom renderer config to pass to `@lwc/template-compiler`. See that package's README for details. - - `enableLightningWebSecurityTransforms` (type: `boolean`, default: `false`) - The configuration to enable Lighting Web Security specific transformations. - - `enableLwcSpread` (boolean, optional, `true` by default) - Deprecated. Ignored by compiler. `lwc:spread` is always enabled. - - `disableSyntheticShadowSupport` (type: `boolean`, default: `false`) - Set to true if synthetic shadow DOM support is not needed, which can result in smaller/faster output. - - `instrumentation` (type: `InstrumentationObject`, optional) - instrumentation object to gather metrics and non-error logs for internal use. See the `@lwc/errors` package for details on the interface. - - `apiVersion` (type: `number`, optional) - API version to associate with the compiled module. +- `source` (string, required) - the source to be transformed. Can be the content of a JavaScript, HTML, or CSS file. +- `filename` (string, required) - the source filename with extension. +- `options` (object, required) - the transformation options. The `name` and the `namespace` of the component is a minimum required for transformation. + - `name` (type: `string`, required) - name of the component, e.g. `foo` in `x/foo`. + - `namespace` (type: `string`, required) - namespace of the component, e.g. `x` in `x/foo`. + - `stylesheetConfig` (type: `object`, default: `{}`) - Deprecated. Ignored by compiler. + - `experimentalDynamicComponent` (type: `DynamicImportConfig`, default: `null`) - The configuration to pass to `@lwc/compiler`. + - `experimentalDynamicDirective` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/template-compiler` to enable deprecated dynamic components. + - `enableDynamicComponents` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/template-compiler` to enable dynamic components. + - `outputConfig` (type: `object`, optional) - see below: + - `sourcemap` (type: `boolean` | `'inline'`, optional) - if `true`, a sourcemap is generated for the transformed file. If `'inline'`, an inline sourcemap is generated and appended to the transformed file. + - `minify` (type: `boolean`, optional, deprecated) - this option has no effect. + - `experimentalComplexExpressions` (type: `boolean`, optional) - set to true to enable use of (a subset of) JavaScript expressions in place of template bindings. Passed to `@lwc/template-compiler`. + - `isExplicitImport` (type: `boolean`, optional) - true if this is an explicit import, passed to `@lwc/babel-plugin-component`. + - `preserveHtmlComments` (type: `boolean`, default: `false`) - The configuration to pass to the `@lwc/template-compiler`. + - `scopedStyles` (type: `boolean`, optional) - True if the CSS file being compiled is a scoped stylesheet. Passed to `@lwc/style-compiler`. + - `enableStaticContentOptimization` (type: `boolean`, optional) - True if the static content optimization should be enabled. Passed to `@lwc/template-compiler`. + - `customRendererConfig` (type: `object`, optional) - custom renderer config to pass to `@lwc/template-compiler`. See that package's README for details. + - `enableLightningWebSecurityTransforms` (type: `boolean`, default: `false`) - The configuration to enable Lighting Web Security specific transformations. + - `enableLwcSpread` (boolean, optional, `true` by default) - Deprecated. Ignored by compiler. `lwc:spread` is always enabled. + - `disableSyntheticShadowSupport` (type: `boolean`, default: `false`) - Set to true if synthetic shadow DOM support is not needed, which can result in smaller/faster output. + - `instrumentation` (type: `InstrumentationObject`, optional) - instrumentation object to gather metrics and non-error logs for internal use. See the `@lwc/errors` package for details on the interface. + - `apiVersion` (type: `number`, optional) - API version to associate with the compiled module. **Return** -- `code` (string) - the compiled source code. -- `map` (object) - the generated source map. -- `warnings` (array, optional) - the array of diagnostic warnings, if any. -- `cssScopeTokens` (array, optional) - String tokens used for style scoping in synthetic shadow DOM and `*.scoped.css` (as either attributes or classes), if any. +- `code` (string) - the compiled source code. +- `map` (object) - the generated source map. +- `warnings` (array, optional) - the array of diagnostic warnings, if any. +- `cssScopeTokens` (array, optional) - String tokens used for style scoping in synthetic shadow DOM and `*.scoped.css` (as either attributes or classes), if any. ### `transform` (deprecated) @@ -81,4 +81,4 @@ console.log(version); **Return** -- `version` (string) - the current version of the compiler ex: `0.25.1`. +- `version` (string) - the current version of the compiler ex: `0.25.1`. diff --git a/packages/@lwc/engine-core/src/libs/mutation-tracker/README.md b/packages/@lwc/engine-core/src/libs/mutation-tracker/README.md index e27f38b60f..4fae4d1aaa 100644 --- a/packages/@lwc/engine-core/src/libs/mutation-tracker/README.md +++ b/packages/@lwc/engine-core/src/libs/mutation-tracker/README.md @@ -63,7 +63,7 @@ Create a new reactive observer instance. **Parameters** -- `callback` [function] The callback function to be called once a qualifying mutation notification is received by code calling `valueMutated(...)`. +- `callback` [function] The callback function to be called once a qualifying mutation notification is received by code calling `valueMutated(...)`. ### `ReactiveObserver.prototype.observe(job)` @@ -71,7 +71,7 @@ Method on a `ReactiveObserver` instance to invoke the job and link any invocatio **Parameters** -- `job` [function] The function to be immediately invoked to track any invocation of `valueObserved(...)` during the execution of this function. +- `job` [function] The function to be immediately invoked to track any invocation of `valueObserved(...)` during the execution of this function. ### `ReactiveObserver.prototype.reset()` @@ -83,8 +83,8 @@ Public function from this library that can be used by any function to notify tha **Parameters** -- `obj` [Object] Any javascript object other than `null`. -- `key` [PropertyKey] A PropertyKey of the `obj` that was accessed. +- `obj` [Object] Any javascript object other than `null`. +- `key` [PropertyKey] A PropertyKey of the `obj` that was accessed. ### `valueMutated(obj, key)` @@ -92,5 +92,5 @@ Public function from this library that can be used by any function to notify tha **Parameters** -- `obj` [Object] Any javascript object other than `null`. -- `key` [PropertyKey] A PropertyKey of the `obj` that was mutated. +- `obj` [Object] Any javascript object other than `null`. +- `key` [PropertyKey] A PropertyKey of the `obj` that was mutated. diff --git a/packages/@lwc/integration-karma/README.md b/packages/@lwc/integration-karma/README.md index 4da07a7af6..1a47da0f29 100644 --- a/packages/@lwc/integration-karma/README.md +++ b/packages/@lwc/integration-karma/README.md @@ -30,16 +30,16 @@ Every time the test suite runs with the `COVERAGE=1` environment variable it pro This set of environment variables applies to the `start` and `test` commands: -- **`LEGACY_BROWSERS=1`:** Run SauceLabs tests in legacy browsers. -- **`DISABLE_SYNTHETIC=1`:** Run without any synthetic shadow polyfill patches. -- **`FORCE_NATIVE_SHADOW_MODE_FOR_TEST=1`:** Force tests to run in native shadow mode with synthetic shadow polyfill patches. -- **`ENABLE_ARIA_REFLECTION_GLOBAL_POLYFILL=1`:** ARIA string reflection as a global polyfill. -- **`NODE_ENV_FOR_TEST`**: Set the `NODE_ENV` to be used for the tests (at runtime, in the browser). -- **`COVERAGE=1`:** Gather engine code coverage, and store it in the `coverage` folder. -- **`GREP="pattern"`:** Filter the spec to run based on the pattern. -- **`API_VERSION=`:** API version to use when compiling. -- **`DISABLE_SYNTHETIC_SHADOW_SUPPORT_IN_COMPILER=1`:** Disable synthetic shadow in the compiler itself. -- **`DISABLE_STATIC_CONTENT_OPTIMIZATION=1`:** Disable static content optimization by setting `enableStaticContentOptimization` to `false`. +- **`LEGACY_BROWSERS=1`:** Run SauceLabs tests in legacy browsers. +- **`DISABLE_SYNTHETIC=1`:** Run without any synthetic shadow polyfill patches. +- **`FORCE_NATIVE_SHADOW_MODE_FOR_TEST=1`:** Force tests to run in native shadow mode with synthetic shadow polyfill patches. +- **`ENABLE_ARIA_REFLECTION_GLOBAL_POLYFILL=1`:** ARIA string reflection as a global polyfill. +- **`NODE_ENV_FOR_TEST`**: Set the `NODE_ENV` to be used for the tests (at runtime, in the browser). +- **`COVERAGE=1`:** Gather engine code coverage, and store it in the `coverage` folder. +- **`GREP="pattern"`:** Filter the spec to run based on the pattern. +- **`API_VERSION=`:** API version to use when compiling. +- **`DISABLE_SYNTHETIC_SHADOW_SUPPORT_IN_COMPILER=1`:** Disable synthetic shadow in the compiler itself. +- **`DISABLE_STATIC_CONTENT_OPTIMIZATION=1`:** Disable static content optimization by setting `enableStaticContentOptimization` to `false`. ## Examples @@ -59,9 +59,9 @@ In another console tab, start the tests using `yarn start`. In another console tab, export the following env vars: -- `SAUCE_USERNAME` -- `SAUCE_KEY` -- `SAUCE_TUNNEL_ID` – this is actually your tunnel _name_, not the ID. Copy it from the `sc` command you just ran. +- `SAUCE_USERNAME` +- `SAUCE_KEY` +- `SAUCE_TUNNEL_ID` – this is actually your tunnel _name_, not the ID. Copy it from the `sc` command you just ran. Run: @@ -81,13 +81,13 @@ In the hydration tests, you can create an empty `.only` file alongside an `index ## Contributing -- The test suite uses jasmine for test runner. You can find more details about jasmine here: https://jasmine.github.io/api/3.3/global -- On top of the standard [jasmine matchers](https://jasmine.github.io/api/edge/matchers.html), the test suite also register custom matchers: - - `toLogErrorDev(message)`: `expect` a function to log an error with a specific message in DEV only. - - `toThrowErrorDev(Error, message)`: `expect` a function to throw an error with a specific Error constructor and a specific message. -- Some of the test command options are available in the test suite on the global `process.env` object: - - `process.env.DISABLE_SYNTHETIC`: is set to `false` by default and `true` if the - `DISABLE_SYNTHETIC` environment variable is set. - - `FORCE_NATIVE_SHADOW_MODE_FOR_TEST`: is set to `false` by default and `true` if the - `FORCE_NATIVE_SHADOW_MODE_FOR_TEST` environment variable is set. -- The test setup file (`test-setup.js`) will automatically clean up the DOM before and after each test. So you don't have to do anything to clean up. However, you should use `beforeEach()` rather than `beforeAll()` to add DOM elements for your test, so that the cleanup code can properly clean up the DOM. +- The test suite uses jasmine for test runner. You can find more details about jasmine here: https://jasmine.github.io/api/3.3/global +- On top of the standard [jasmine matchers](https://jasmine.github.io/api/edge/matchers.html), the test suite also register custom matchers: + - `toLogErrorDev(message)`: `expect` a function to log an error with a specific message in DEV only. + - `toThrowErrorDev(Error, message)`: `expect` a function to throw an error with a specific Error constructor and a specific message. +- Some of the test command options are available in the test suite on the global `process.env` object: + - `process.env.DISABLE_SYNTHETIC`: is set to `false` by default and `true` if the + `DISABLE_SYNTHETIC` environment variable is set. + - `FORCE_NATIVE_SHADOW_MODE_FOR_TEST`: is set to `false` by default and `true` if the + `FORCE_NATIVE_SHADOW_MODE_FOR_TEST` environment variable is set. +- The test setup file (`test-setup.js`) will automatically clean up the DOM before and after each test. So you don't have to do anything to clean up. However, you should use `beforeEach()` rather than `beforeAll()` to add DOM elements for your test, so that the cleanup code can properly clean up the DOM. diff --git a/packages/@lwc/integration-karma/package.json b/packages/@lwc/integration-karma/package.json index 2159279dcf..35b5bb94f5 100644 --- a/packages/@lwc/integration-karma/package.json +++ b/packages/@lwc/integration-karma/package.json @@ -22,7 +22,7 @@ "@lwc/engine-server": "8.11.0", "@lwc/rollup-plugin": "8.11.0", "@lwc/synthetic-shadow": "8.11.0", - "@types/jasmine": "^5.1.4", + "@types/jasmine": "^5.1.5", "chokidar": "^4.0.1", "istanbul-lib-coverage": "^3.2.2", "istanbul-lib-report": "^3.0.1", diff --git a/packages/@lwc/integration-tests/README.md b/packages/@lwc/integration-tests/README.md index 566ce7123b..6bbb81b130 100644 --- a/packages/@lwc/integration-tests/README.md +++ b/packages/@lwc/integration-tests/README.md @@ -153,6 +153,6 @@ Note that `.spec.js` should always be at the top level under `te ### Pro tips -- `browser.keys(['Shift', 'Tab'])` keeps you in a state where the shift key is toggled so you may run into unexpected results unless you explicitly untoggle the shift key. The recommendation is to use the command `browser.keys(['Shift', 'Tab', 'Shift'])` which toggles and untoggles the shift key in a single command. +- `browser.keys(['Shift', 'Tab'])` keeps you in a state where the shift key is toggled so you may run into unexpected results unless you explicitly untoggle the shift key. The recommendation is to use the command `browser.keys(['Shift', 'Tab', 'Shift'])` which toggles and untoggles the shift key in a single command. -- On top of the [commands](https://webdriver.io/docs/api.html) already provided by WebdriverIO, this project also provides [custom command](scripts/commands) for common operation like shadow tree query selection and focus. +- On top of the [commands](https://webdriver.io/docs/api.html) already provided by WebdriverIO, this project also provides [custom command](scripts/commands) for common operation like shadow tree query selection and focus. diff --git a/packages/@lwc/integration-tests/package.json b/packages/@lwc/integration-tests/package.json index e6441814f3..76bfca2fda 100644 --- a/packages/@lwc/integration-tests/package.json +++ b/packages/@lwc/integration-tests/package.json @@ -19,10 +19,10 @@ }, "devDependencies": { "@lwc/rollup-plugin": "8.11.0", - "@wdio/cli": "^9.3.1", - "@wdio/local-runner": "^9.3.1", + "@wdio/cli": "^9.4.1", + "@wdio/local-runner": "^9.4.1", "@wdio/mocha-framework": "^9.2.8", - "@wdio/sauce-service": "^9.3.1", + "@wdio/sauce-service": "^9.4.1", "@wdio/spec-reporter": "^9.2.14", "@wdio/static-server-service": "^9.2.2", "deepmerge": "^4.3.1", diff --git a/packages/@lwc/integration-types/package.json b/packages/@lwc/integration-types/package.json index 611f7253ab..880fd7b4c1 100644 --- a/packages/@lwc/integration-types/package.json +++ b/packages/@lwc/integration-types/package.json @@ -15,7 +15,7 @@ "devDependencies": { "@rollup/plugin-replace": "^6.0.1", "@rollup/plugin-typescript": "^12.1.1", - "rollup": "^4.27.4", + "rollup": "^4.28.0", "rollup-plugin-livereload": "^2.0.5", "rollup-plugin-serve": "^3.0.0" } diff --git a/packages/@lwc/module-resolver/README.md b/packages/@lwc/module-resolver/README.md index 0a4c4aad06..6acdfe532b 100644 --- a/packages/@lwc/module-resolver/README.md +++ b/packages/@lwc/module-resolver/README.md @@ -44,27 +44,27 @@ console.log(result); **Parameters:** -- `specifier` (string, required): The module specifier to resolve. -- `importer` (string, required): The file from where the resolution starts. -- `options` (object, optional): - - `modules` (ModuleRecord[], optional, default: `[]`): Injects module records to the resolved configuration. - - `rootDir` (string, optional, default: `process.cwd()`): Use only when the `modules` option is set. Modules overrides are resolved from this directory. +- `specifier` (string, required): The module specifier to resolve. +- `importer` (string, required): The file from where the resolution starts. +- `options` (object, optional): + - `modules` (ModuleRecord[], optional, default: `[]`): Injects module records to the resolved configuration. + - `rootDir` (string, optional, default: `process.cwd()`): Use only when the `modules` option is set. Modules overrides are resolved from this directory. **Return value:** A `RegistryEntry` representing the resolved module with the following properties: -- `entry` (string): The absolute path of the module entry point. -- `specifier` (string): The resolved module specifier. -- `scope` (string): The absolute path from where the module has been resolved. +- `entry` (string): The absolute path of the module entry point. +- `specifier` (string): The resolved module specifier. +- `scope` (string): The absolute path from where the module has been resolved. ## Module resolution The LWC compiler uses a custom resolution algorithm to resolve LWC modules. To configure module resolution, use the `lwc.config.json` file or the `lwc` key in the `package.json` file. The `modules` key accepts an array of module records. The resolver iterates through the `modules` array and returns the first module that matches the requested module specifier. There are three types of module record: -- [Alias module record](#alias-module-record): A file path where an LWC module can be resolved. -- [Directory module record](#directory-module-record): A folder path where LWC modules can be resolved. -- [NPM package module record](#npm-package-module-record): An NPM package that exposes one or more LWC modules. +- [Alias module record](#alias-module-record): A file path where an LWC module can be resolved. +- [Directory module record](#directory-module-record): A folder path where LWC modules can be resolved. +- [NPM package module record](#npm-package-module-record): An NPM package that exposes one or more LWC modules. ```json // lwc.config.json @@ -90,8 +90,8 @@ The LWC compiler uses a custom resolution algorithm to resolve LWC modules. To c An alias module record maps a module specifier to a file path. An alias module record is defined by two keys: -- `name` (string, required): The LWC module specifier. -- `path` (string, required): The file path to resolve. +- `name` (string, required): The LWC module specifier. +- `path` (string, required): The file path to resolve. In this example, the `ui/button` LWC module specifier is resolved from the `src/modules/ui/button/button.js` path. @@ -110,7 +110,7 @@ In this example, the `ui/button` LWC module specifier is resolved from the `src/ A directory module record specifies a folder path where LWC modules are resolved. A directory module record is defined by one key: -- `dir` (string, required): The directory path containing the modules. +- `dir` (string, required): The directory path containing the modules. ```json { @@ -144,7 +144,7 @@ src An NPM package module record tells the resolver that a given NPM package exposes resolvable LWC modules. More details about how to expose LWC modules out of an NPM package can be found in [this section](#exposing-lwc-modules-via-npm-packages). An NPM package module record is defined by one key: -- `npm` (string, required): The NPM package name exposing the LWC modules. +- `npm` (string, required): The NPM package name exposing the LWC modules. In this example, the resolver is told to look into the `@ui/components` NPM package to look up LWC modules. diff --git a/packages/@lwc/perf-benchmarks/README.md b/packages/@lwc/perf-benchmarks/README.md index 9e19674a5f..92f5b13043 100644 --- a/packages/@lwc/perf-benchmarks/README.md +++ b/packages/@lwc/perf-benchmarks/README.md @@ -34,9 +34,9 @@ This will print out the URLs you can use to test manually. When analyzing with the Chrome DevTools Performance tab, pay special attention to the following performance measures in the "Timing" section: -- `benchmark-before` -- `benchmark-run` -- `benchmark-after` +- `benchmark-before` +- `benchmark-run` +- `benchmark-after` `benchmark-run` is what's actually measured, whereas the `-before` and `-after` measures are just the setup and teardown code. diff --git a/packages/@lwc/rollup-plugin/README.md b/packages/@lwc/rollup-plugin/README.md index 6faded0ac6..e145f8092b 100644 --- a/packages/@lwc/rollup-plugin/README.md +++ b/packages/@lwc/rollup-plugin/README.md @@ -22,20 +22,20 @@ export default { ## Options -- `include` (type: `string | string[]`, default: `null`) - A [minimatch pattern](https://github.com/isaacs/minimatch), or array of patterns, which specifies the files in the build the plugin should transform on. By default all files are targeted. -- `exclude` (type: `string | string[]`, default: `null`) - A [minimatch pattern](https://github.com/isaacs/minimatch), or array of patterns, which specifies the files in the build the plugin should not transform. By default no files are ignored. -- `rootDir` (type: `string`, default: rollup `input` directory) - The LWC root module directory. -- `sourcemap` (type: `boolean`, default: `false`) - If `true` the plugin will produce source maps. -- `modules` (type: `ModuleRecord[]`, default: `[]`) - The [module resolution](https://lwc.dev/guide/es_modules#module-resolution) overrides passed to the `@lwc/module-resolver`. -- `stylesheetConfig` (type: `object`, default: `{}`) - Deprecated. Ignored by compiler. -- `preserveHtmlComments` (type: `boolean`, default: `false`) - The configuration to pass to the `@lwc/template-compiler`. -- `experimentalDynamicComponent` (type: `DynamicImportConfig`, default: `null`) - The configuration to pass to `@lwc/compiler`. -- `experimentalDynamicDirective` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/template-compiler` to enable deprecated dynamic components. -- `enableDynamicComponents` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/template-compiler` to enable dynamic components. -- `enableLightningWebSecurityTransforms` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/compiler`. -- `enableLwcSpread` (type: `boolean`, default: `false`) - The configuration to pass to the `@lwc/template-compiler`. -- `disableSyntheticShadowSupport` (type: `boolean`, default: `false`) - Set to true if synthetic shadow DOM support is not needed, which can result in smaller output. -- `apiVersion` (type: `number`, default: `undefined`) - Set to a valid API version such as 58, 59, etc. This will be overriden if the component itself overrides the version with a `*.js-meta.xml` file. -- `enableStaticContentOptimization` (type: `boolean`, optional) - True if the static content optimization should be enabled. Passed to `@lwc/template-compiler`. True by default. -- `targetSSR` (type: `boolean`) - Utilize the experimental SSR compilation mode. False by default. Do not use unless you know what you're doing. -- `ssrMode` (type: `string`): The variety of SSR code that should be generated when using experimental SSR compilation mode. Should be one of `sync`, `async` or `asyncYield`. +- `include` (type: `string | string[]`, default: `null`) - A [minimatch pattern](https://github.com/isaacs/minimatch), or array of patterns, which specifies the files in the build the plugin should transform on. By default all files are targeted. +- `exclude` (type: `string | string[]`, default: `null`) - A [minimatch pattern](https://github.com/isaacs/minimatch), or array of patterns, which specifies the files in the build the plugin should not transform. By default no files are ignored. +- `rootDir` (type: `string`, default: rollup `input` directory) - The LWC root module directory. +- `sourcemap` (type: `boolean`, default: `false`) - If `true` the plugin will produce source maps. +- `modules` (type: `ModuleRecord[]`, default: `[]`) - The [module resolution](https://lwc.dev/guide/es_modules#module-resolution) overrides passed to the `@lwc/module-resolver`. +- `stylesheetConfig` (type: `object`, default: `{}`) - Deprecated. Ignored by compiler. +- `preserveHtmlComments` (type: `boolean`, default: `false`) - The configuration to pass to the `@lwc/template-compiler`. +- `experimentalDynamicComponent` (type: `DynamicImportConfig`, default: `null`) - The configuration to pass to `@lwc/compiler`. +- `experimentalDynamicDirective` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/template-compiler` to enable deprecated dynamic components. +- `enableDynamicComponents` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/template-compiler` to enable dynamic components. +- `enableLightningWebSecurityTransforms` (type: `boolean`, default: `false`) - The configuration to pass to `@lwc/compiler`. +- `enableLwcSpread` (type: `boolean`, default: `false`) - The configuration to pass to the `@lwc/template-compiler`. +- `disableSyntheticShadowSupport` (type: `boolean`, default: `false`) - Set to true if synthetic shadow DOM support is not needed, which can result in smaller output. +- `apiVersion` (type: `number`, default: `undefined`) - Set to a valid API version such as 58, 59, etc. This will be overriden if the component itself overrides the version with a `*.js-meta.xml` file. +- `enableStaticContentOptimization` (type: `boolean`, optional) - True if the static content optimization should be enabled. Passed to `@lwc/template-compiler`. True by default. +- `targetSSR` (type: `boolean`) - Utilize the experimental SSR compilation mode. False by default. Do not use unless you know what you're doing. +- `ssrMode` (type: `string`): The variety of SSR code that should be generated when using experimental SSR compilation mode. Should be one of `sync`, `async` or `asyncYield`. diff --git a/packages/@lwc/style-compiler/README.md b/packages/@lwc/style-compiler/README.md index cab84a517a..3eb1bdf493 100644 --- a/packages/@lwc/style-compiler/README.md +++ b/packages/@lwc/style-compiler/README.md @@ -4,12 +4,12 @@ Transform style sheet to be consumed by the LWC engine. ## Features -- Shadow DOM style scoping: - - transform `:host` pseudo-class selectors - - scope all the other selectors using CSS attribute selectors -- Custom Properties: inline replacement of `var()` CSS function -- Right-to-left: transform the `:dir` pseudo class selector to `[dir]` attribute selectors -- CSS import: resolve imports via static ES module imports +- Shadow DOM style scoping: + - transform `:host` pseudo-class selectors + - scope all the other selectors using CSS attribute selectors +- Custom Properties: inline replacement of `var()` CSS function +- Right-to-left: transform the `:dir` pseudo class selector to `[dir]` attribute selectors +- CSS import: resolve imports via static ES module imports ## Installation @@ -41,27 +41,27 @@ const { code } = transform(source, 'example.css'); **Options:** -- `source` (string, required) - the css source file to compiler -- `id` (string, required) - the css source file path, used by the compiler to produce errors with the file name -- `options` (object, optional) - - `customProperties` (object, optional) - - `resolverModule` (boolean, optional) - module name for the custom properties resolve - - `scoped` (boolean, optional) - true if the styles are scoped (via Light DOM style scoping) - - `disableSyntheticShadowSupport` (boolean, optional) - true if synthetic shadow DOM support is not needed, which can result in smaller output - - `apiVersion` (number, optional) - API version to associate with the compiled stylesheet. +- `source` (string, required) - the css source file to compiler +- `id` (string, required) - the css source file path, used by the compiler to produce errors with the file name +- `options` (object, optional) + - `customProperties` (object, optional) + - `resolverModule` (boolean, optional) - module name for the custom properties resolve + - `scoped` (boolean, optional) - true if the styles are scoped (via Light DOM style scoping) + - `disableSyntheticShadowSupport` (boolean, optional) - true if synthetic shadow DOM support is not needed, which can result in smaller output + - `apiVersion` (number, optional) - API version to associate with the compiled stylesheet. **Return:** -- `code` - the generated code +- `code` - the generated code Note: The LWC style compiler doesn't preserve the authored format, and always produce compressed code. ## Selector scoping caveats -- No support for [`::slotted`](https://drafts.csswg.org/css-scoping/#slotted-pseudo) pseudo-element. -- No support for [`>>>`](https://drafts.csswg.org/css-scoping/#deep-combinator) deep combinator (spec still under consideration: [issue](https://github.com/w3c/webcomponents/issues/78)). -- No support for [`:host-context`](https://drafts.csswg.org/css-scoping/#selectordef-host-context) pseudo-selector (browser vendors are not able to agree: [webkit](https://bugs.webkit.org/show_bug.cgi?id=160038), [gecko](https://bugzilla.mozilla.org/show_bug.cgi?id=1082060)) -- This transform duplicates the `:host` selector to able to use the generated style in both the synthetic and native shadow DOM. The duplication is necessary to support the functional form of `:host()`, `:host(.foo, .bar) {}` needs to get transformed into `.foo[x-btn-host], .bar[x-btn-host] {}` to work in the synthetic shadow DOM. -- Scoped CSS has a non-negligeable performance impact: - - Each selector chain is scoped and each compound expression passed to the `:host()` need to be spread into multiple selectors. This transformation greatly increases the overall size and complexity of the generated CSS, leading to more bits on the wire, longer parsing time and longer style recalculation. - - In order to ensure CSS encapsulation, each element needs to add an extra attribute. This increases the actual rendering time. +- No support for [`::slotted`](https://drafts.csswg.org/css-scoping/#slotted-pseudo) pseudo-element. +- No support for [`>>>`](https://drafts.csswg.org/css-scoping/#deep-combinator) deep combinator (spec still under consideration: [issue](https://github.com/w3c/webcomponents/issues/78)). +- No support for [`:host-context`](https://drafts.csswg.org/css-scoping/#selectordef-host-context) pseudo-selector (browser vendors are not able to agree: [webkit](https://bugs.webkit.org/show_bug.cgi?id=160038), [gecko](https://bugzilla.mozilla.org/show_bug.cgi?id=1082060)) +- This transform duplicates the `:host` selector to able to use the generated style in both the synthetic and native shadow DOM. The duplication is necessary to support the functional form of `:host()`, `:host(.foo, .bar) {}` needs to get transformed into `.foo[x-btn-host], .bar[x-btn-host] {}` to work in the synthetic shadow DOM. +- Scoped CSS has a non-negligeable performance impact: + - Each selector chain is scoped and each compound expression passed to the `:host()` need to be spread into multiple selectors. This transformation greatly increases the overall size and complexity of the generated CSS, leading to more bits on the wire, longer parsing time and longer style recalculation. + - In order to ensure CSS encapsulation, each element needs to add an extra attribute. This increases the actual rendering time. diff --git a/packages/@lwc/synthetic-shadow/README.md b/packages/@lwc/synthetic-shadow/README.md index a854bf58e5..d32de19f70 100644 --- a/packages/@lwc/synthetic-shadow/README.md +++ b/packages/@lwc/synthetic-shadow/README.md @@ -6,6 +6,6 @@ This is a polyfill for ShadowRoot that was tailor-made for LWC in order to meet ## Compromises -- Default content for `` elements is always empty. -- `slotchange` is only available directly on the `` (it doesn't bubble as in the case of the native implementation). This restriction is in place because implementing `slotchange` requires using `MutationObserver` which is expensive at runtime. By only supporting `slotchange` event applied directly on the `` element, the LWC engine receives a clear signal that the component author is interested in listening to this event. This avoids spending unnecessary CPU time when the `slotchange` event is never consumed. -- If you use `MutationObserver` to watch changes in a DOM tree, disconnect it or you will cause a memory leak. Note that a component can observe mutations only in its own template. It can't observe mutations within the shadow tree of other custom elements. +- Default content for `` elements is always empty. +- `slotchange` is only available directly on the `` (it doesn't bubble as in the case of the native implementation). This restriction is in place because implementing `slotchange` requires using `MutationObserver` which is expensive at runtime. By only supporting `slotchange` event applied directly on the `` element, the LWC engine receives a clear signal that the component author is interested in listening to this event. This avoids spending unnecessary CPU time when the `slotchange` event is never consumed. +- If you use `MutationObserver` to watch changes in a DOM tree, disconnect it or you will cause a memory leak. Note that a component can observe mutations only in its own template. It can't observe mutations within the shadow tree of other custom elements. diff --git a/packages/@lwc/synthetic-shadow/src/polyfills/document-shadow/README.md b/packages/@lwc/synthetic-shadow/src/polyfills/document-shadow/README.md index 42635601c6..360f81033a 100644 --- a/packages/@lwc/synthetic-shadow/src/polyfills/document-shadow/README.md +++ b/packages/@lwc/synthetic-shadow/src/polyfills/document-shadow/README.md @@ -2,15 +2,15 @@ This polyfill contains all the patched methods we need to work with our Synthetic Shadow. -- Patched methods will only return root node(s) from the LWC trees. -- Polyfill works correctly in both Synthetic and Native Shadow Dom modes -- Methods patched: - - `document.activeElement` - - `document.elementFromPoint` - - `Document.prototype.getElementsByClassName` - - `Document.prototype.getElementById` - - `Document.prototype.getElementsByTagName` - - `Document.prototype.getElementsByTagNameNS` - - `Document.prototype.getElementsByName` - - `Document.prototype.querySelector` - - `Document.prototype.querySelectorAll` +- Patched methods will only return root node(s) from the LWC trees. +- Polyfill works correctly in both Synthetic and Native Shadow Dom modes +- Methods patched: + - `document.activeElement` + - `document.elementFromPoint` + - `Document.prototype.getElementsByClassName` + - `Document.prototype.getElementById` + - `Document.prototype.getElementsByTagName` + - `Document.prototype.getElementsByTagNameNS` + - `Document.prototype.getElementsByName` + - `Document.prototype.querySelector` + - `Document.prototype.querySelectorAll` diff --git a/packages/@lwc/template-compiler/README.md b/packages/@lwc/template-compiler/README.md index 8bc0c143c8..0d47223f53 100644 --- a/packages/@lwc/template-compiler/README.md +++ b/packages/@lwc/template-compiler/README.md @@ -45,26 +45,26 @@ const { code, warnings } = compile(``, **Parameters:** -- `source` (string, required) - the HTML template source to compile. -- `filename` (string, required) - the source filename with extension. -- `options` (object, required) - the options to used to compile the HTML template source. +- `source` (string, required) - the HTML template source to compile. +- `filename` (string, required) - the source filename with extension. +- `options` (object, required) - the options to used to compile the HTML template source. **Options:** -- `name` (type: `string`, optional, `undefined` by default) - name of the component, e.g. `foo` in `x/foo`. -- `namespace` (type: `string`, optional, `undefined` by default) - namespace of the component, e.g. `x` in `x/foo`. -- `experimentalComputedMemberExpression` (boolean, optional, `false` by default) - set to `true` to enable computed member expression in the template, eg: `{list[0].name}`. -- `experimentalComplexExpressions` (boolean, optional, `false` by default) - set to `true` to enable use of (a subset of) JavaScript expressions in place of template bindings. -- `experimentalDynamicDirective` (boolean, optional, `false` by default) - set to `true` to allow the usage of `lwc:dynamic` directives in the template. -- `enableDynamicComponents` (boolean, optional, `false` by default) - set to `true` to enable `lwc:is` directive in the template. -- `preserveHtmlComments` (boolean, optional, `false` by default) - set to `true` to disable the default behavior of stripping HTML comments. -- `enableStaticContentOptimization` (boolean, optional, `true` by default) - set to `false` to disable static content optimizations. -- `enableLwcSpread` (boolean, optional, `true` by default) - Deprecated. Ignored by template-compiler. `lwc:spread` is always enabled. -- `customRendererConfig` (CustomRendererConfig, optional) - specifies a configuration to use to match elements. Matched elements will get a custom renderer hook in the generated template. -- `instrumentation` (InstrumentationObject, optional) - instrumentation object to gather metrics and non-error logs for internal use. See the `@lwc/errors` package for details on the interface. -- `disableSyntheticShadowSupport` (type: `boolean`, default: `false`) - Set to true if synthetic shadow DOM support is not needed, which can result in smaller/faster output. - - - Example 1: Config to match `` elements under the `svg` namespace and have `href` attribute set. +- `name` (type: `string`, optional, `undefined` by default) - name of the component, e.g. `foo` in `x/foo`. +- `namespace` (type: `string`, optional, `undefined` by default) - namespace of the component, e.g. `x` in `x/foo`. +- `experimentalComputedMemberExpression` (boolean, optional, `false` by default) - set to `true` to enable computed member expression in the template, eg: `{list[0].name}`. +- `experimentalComplexExpressions` (boolean, optional, `false` by default) - set to `true` to enable use of (a subset of) JavaScript expressions in place of template bindings. +- `experimentalDynamicDirective` (boolean, optional, `false` by default) - set to `true` to allow the usage of `lwc:dynamic` directives in the template. +- `enableDynamicComponents` (boolean, optional, `false` by default) - set to `true` to enable `lwc:is` directive in the template. +- `preserveHtmlComments` (boolean, optional, `false` by default) - set to `true` to disable the default behavior of stripping HTML comments. +- `enableStaticContentOptimization` (boolean, optional, `true` by default) - set to `false` to disable static content optimizations. +- `enableLwcSpread` (boolean, optional, `true` by default) - Deprecated. Ignored by template-compiler. `lwc:spread` is always enabled. +- `customRendererConfig` (CustomRendererConfig, optional) - specifies a configuration to use to match elements. Matched elements will get a custom renderer hook in the generated template. +- `instrumentation` (InstrumentationObject, optional) - instrumentation object to gather metrics and non-error logs for internal use. See the `@lwc/errors` package for details on the interface. +- `disableSyntheticShadowSupport` (type: `boolean`, default: `false`) - Set to true if synthetic shadow DOM support is not needed, which can result in smaller/faster output. + + - Example 1: Config to match `` elements under the `svg` namespace and have `href` attribute set. ``` { @@ -81,7 +81,7 @@ const { code, warnings } = compile(``, } ``` - - Example 2: Config to match `