diff --git a/text/0000-synthetic-shadow-migrate.md b/text/0000-synthetic-shadow-migrate.md new file mode 100644 index 00000000..de7f51e7 --- /dev/null +++ b/text/0000-synthetic-shadow-migrate.md @@ -0,0 +1,154 @@ +--- +title: Shadow DOM migration mode +status: DRAFTED +created_at: 2023-11-14 +updated_at: 2023-11-14 +pr: https://github.com/salesforce/lwc-rfcs/pull/83 +--- + +# 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' +} +``` + +Removing synthetic shadow DOM entirely would bring several benefits, including improved performance and debuggability, better compatibility with other web component frameworks, access to new native features such as `::part`, fewer bugs, and less risk of breakage as browser standards evolve. + +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. After all, switching has the major downside of potentially breaking these components, with only a small marginal upside for the component author (mostly in terms of performance and new features such as `::part`). + +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 `