From b18e7784aa81d800273be72f4defbdee57aec0d3 Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Tue, 14 Nov 2023 12:28:16 -0800 Subject: [PATCH 1/9] RFC: Shadow DOM migration mode --- text/0000-synthetic-shadow-migrate.md | 140 ++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 text/0000-synthetic-shadow-migrate.md diff --git a/text/0000-synthetic-shadow-migrate.md b/text/0000-synthetic-shadow-migrate.md new file mode 100644 index 00000000..774de5c9 --- /dev/null +++ b/text/0000-synthetic-shadow-migrate.md @@ -0,0 +1,140 @@ +--- +title: Shadow DOM migration mode +status: DRAFTED +created_at: 2023-11-14 +updated_at: 2023-11-14 +pr: (leave this empty until the PR is created) +--- + +# Shadow DOM migration mode + +## Summary + +This RFC introduces a new `shadowSupportMode` designed to ease the transition from synthetic shadow DOM +to native shadow DOM. + +## Basic example + +```js +export default class extends LightningElement { + static shadowSupportMode = 'migrate' +} +``` + +```html + +``` + +The above component will be styled as an [SLDS branded button](https://www.lightningdesignsystem.com/components/buttons/), +if SLDS CSS is loaded in the `document`'s ``. However, the component uses native shadow DOM under the hood. + +[Proof-of-concept demo](https://stackblitz.com/edit/salesforce-lwc-foclkc?file=src%2Fmodules%2Fx%2Fapp%2Fapp.html&title=LWC%20playground) + +## Motivation + +Now that [mixed shadow DOM mode](https://developer.salesforce.com/docs/platform/lwc/guide/create-mixed-shadow.html) is released, component authors can switch from synthetic shadow to native shadow DOM: + +```js +export default class extends LightningElement { + static shadowSupportMode = 'native' +} +``` + +However, there are several incompatibilities between native and synthetic shadow, due to limitations of the polyfill itself. Authors of existing components may not see a compelling reason to switch from synthetic to native shadow, since switching has the major downside of potentially breaking their components, with no perceivable upside (except a small performance win). + +The most serious incompatibility between native and synthetic shadow DOM is the lack of global styling for native shadow components. In synthetic shadow, any global stylesheets still affect elements inside the shadow root. As such, many component authors have taken dependencies on global stylesheets, notably on [SLDS](https://www.lightningdesignsystem.com/) in Lightning Experience. In fact, the Salesforce documentation explicitly [encourages this](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-slds.html) in "getting started" guides, and community-authored content also frequently promotes `slds-*` classes as well. + +This RFC proposes a new mode to help ease this migration, and to encourage more component authors to move from synthetic to native shadow, by emulating synthetic shadow's styling behavior on top of native shadow DOM. + +## Detailed design + +`shadowSupportMode` has two options – `'reset'` (synthetic) or `'native'` (native). Currently on Lightning Experience, +`'reset'` is the default, but developers may opt into `'native'`, which 1) uses native shadow DOM, and 2) cascades native +shadow DOM down into any descendants of the component. + +This RFC proposes a third mode: `'migrate'`: + +```js +static shadowSupportMode = 'migrate' +``` + +"Migrate" mode (ala [jquery-migrate](https://github.com/jquery/jquery-migrate)) has the following behaviors: + +- Native shadow DOM is used (like `'native'`). +- The mode cascades to all descendants (like `'native'`). +- Unlike `'native'`, however, "migrate" mode copies global `