chore(compiler): mark extras.shadowDomShim as a deprecated field (#3898)

This marks the `shadowDomShim` field as deprecated and adds TODO comments around the codebase where code that references the field will need to be removed in the future. BREAKING CHANGES: the `shadowDomShim` field is now deprecated. Support for IE 11, non-Chromium Edge, and Safari 10 has been dropped.
ionic-team · Jan 25, 2023 · f67fc6c · f67fc6c
1 parent 45f90ef
commit f67fc6c
Show file tree

Hide file tree

Showing 19 changed files with 53 additions and 4 deletions.
diff --git a/BREAKING_CHANGES.md b/BREAKING_CHANGES.md
@@ -17,6 +17,7 @@ This is a comprehensive list of the breaking changes introduced in the major ver
   * [Legacy Browser Support Fields Deprecated](#legacy-browser-support-fields-deprecated)
     * [`dynamicImportShim`](#dynamicimportshim)
     * [`cssVarShim`](#cssvarshim)
+    * [`shadowDomShim`](#shadowdomshim)
   * [Deprecated `assetsDir` Removed from `@Component()` decorator](#deprecated-assetsdir-removed-from-component-decorator)
   * [Drop Node 12 Support](#drop-node-12-support)
   * [Strongly Typed Inputs](#strongly-typed-inputs)
@@ -118,6 +119,26 @@ export const config: Config = {
 };
 ```
 
+##### `shadowDomShim`
+
+If `extras.shadowDomShim` is set to `true` the Stencil runtime will check
+whether a shim for [shadow
+DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM)
+is needed in the current browser, and include one if so. For Stencil v3.0.0
+this field is renamed to `__deprecated__shadowDomShim`. To retain the previous
+behavior the new option can be set in your project's `stencil.config.ts`:
+
+```ts
+// stencil.config.ts
+import { Config } from '@stencil/core';
+
+export const config: Config = {
+  extras: {
+    __deprecated__shadowDomShim: true
+  }
+};
+```
+
 #### Deprecated `assetsDir` Removed from `@Component()` decorator
 The `assetsDir` field was [deprecated in Stencil v2.0.0](#componentassetsdir), but some backwards compatibility was retained with a warning message.
 It has been fully removed in Stencil v3.0.0 in favor of `assetsDirs`.

diff --git a/src/app-data/index.ts b/src/app-data/index.ts
@@ -66,6 +66,7 @@ export const BUILD: BuildConditionals = {
   safari10: false,
   scriptDataOpts: false,
   scopedSlotTextContentFix: false,
+  // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
   shadowDomShim: false,
   slotChildNodesFix: false,
   invisiblePrehydration: true,

diff --git a/src/client/client-window.ts b/src/client/client-window.ts
@@ -32,6 +32,7 @@ export const setPlatformHelpers = (helpers: {
 };
 
 export const supportsShadow =
+  // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
   BUILD.shadowDomShim && BUILD.shadowDom
     ? /*@__PURE__*/ (() => (doc.head.attachShadow + '').indexOf('[native') > -1)()
     : true;

diff --git a/src/compiler/app-core/app-data.ts b/src/compiler/app-core/app-data.ts
@@ -155,9 +155,11 @@ export const updateBuildConditionals = (config: Config, b: BuildConditionals) =>
   b.safari10 = config.extras.safari10;
   b.scopedSlotTextContentFix = !!config.extras.scopedSlotTextContentFix;
   b.scriptDataOpts = config.extras.scriptDataOpts;
-  b.shadowDomShim = config.extras.shadowDomShim;
+  // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
+  b.shadowDomShim = config.extras.__deprecated__shadowDomShim;
   b.attachStyles = true;
   b.invisiblePrehydration = typeof config.invisiblePrehydration === 'undefined' ? true : config.invisiblePrehydration;
+  // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
   if (b.shadowDomShim) {
     b.slotRelocation = b.slot;
   }

diff --git a/src/compiler/config/test/validate-config.spec.ts b/src/compiler/config/test/validate-config.spec.ts
@@ -361,7 +361,8 @@ describe('validation', () => {
     expect(config.extras.lifecycleDOMEvents).toBe(false);
     expect(config.extras.safari10).toBe(false);
     expect(config.extras.scriptDataOpts).toBe(false);
-    expect(config.extras.shadowDomShim).toBe(false);
+    // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
+    expect(config.extras.__deprecated__shadowDomShim).toBe(false);
     expect(config.extras.slotChildNodesFix).toBe(false);
     expect(config.extras.initializeNextTick).toBe(false);
     expect(config.extras.tagNameTransform).toBe(false);

diff --git a/src/compiler/config/validate-config.ts b/src/compiler/config/validate-config.ts
@@ -78,7 +78,8 @@ export const validateConfig = (
   validatedConfig.extras.lifecycleDOMEvents = !!validatedConfig.extras.lifecycleDOMEvents;
   validatedConfig.extras.safari10 = !!validatedConfig.extras.safari10;
   validatedConfig.extras.scriptDataOpts = !!validatedConfig.extras.scriptDataOpts;
-  validatedConfig.extras.shadowDomShim = !!validatedConfig.extras.shadowDomShim;
+  // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
+  validatedConfig.extras.__deprecated__shadowDomShim = !!validatedConfig.extras.__deprecated__shadowDomShim;
   validatedConfig.extras.slotChildNodesFix = !!validatedConfig.extras.slotChildNodesFix;
   validatedConfig.extras.initializeNextTick = !!validatedConfig.extras.initializeNextTick;
   validatedConfig.extras.tagNameTransform = !!validatedConfig.extras.tagNameTransform;

diff --git a/src/compiler/output-targets/dist-hydrate-script/generate-hydrate-app.ts b/src/compiler/output-targets/dist-hydrate-script/generate-hydrate-app.ts
@@ -137,6 +137,7 @@ const getHydrateBuildConditionals = (config: d.ValidatedConfig, cmps: d.Componen
   build.appendChildSlotFix = false;
   build.slotChildNodesFix = false;
   build.safari10 = false;
+  // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
   build.shadowDomShim = false;
 
   return build;

diff --git a/src/compiler/output-targets/dist-hydrate-script/hydrate-build-conditionals.ts b/src/compiler/output-targets/dist-hydrate-script/hydrate-build-conditionals.ts
@@ -25,6 +25,7 @@ export const getHydrateBuildConditionals = (cmps: d.ComponentCompilerMeta[]) =>
   build.slotChildNodesFix = false;
   build.cloneNodeFix = false;
   build.cssAnnotations = true;
+  // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
   build.shadowDomShim = true;
   build.safari10 = false;
   build.hydratedAttribute = false;

diff --git a/src/compiler/transformers/component-hydrate/hydrate-runtime-cmp-meta.ts b/src/compiler/transformers/component-hydrate/hydrate-runtime-cmp-meta.ts
@@ -17,6 +17,7 @@ export const addHydrateRuntimeCmpMeta = (classMembers: ts.ClassElement[], cmp: d
   };
   // We always need shadow-dom shim in hydrate runtime
   if (cmpMeta.$flags$ & CMP_FLAGS.shadowDomEncapsulation) {
+    // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
     cmpMeta.$flags$ |= CMP_FLAGS.needsShadowDomShim;
   }
   const staticMember = createStaticGetter('cmpMeta', convertValueToLiteral(cmpMeta));

diff --git a/src/declarations/stencil-private.ts b/src/declarations/stencil-private.ts
@@ -183,6 +183,7 @@ export interface BuildConditionals extends Partial<BuildFeatures> {
   initializeNextTick?: boolean;
   safari10?: boolean;
   scriptDataOpts?: boolean;
+  // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
   shadowDomShim?: boolean;
   asyncQueue?: boolean;
   transformTagName?: boolean;

diff --git a/src/declarations/stencil-public-compiler.ts b/src/declarations/stencil-public-compiler.ts
@@ -320,13 +320,17 @@ export interface ConfigExtras {
    */
   scopedSlotTextContentFix?: boolean;
 
+  // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
   /**
    * If enabled `true`, the runtime will check if the shadow dom shim is required. However,
    * if it's determined that shadow dom is already natively supported by the browser then
    * it does not request the shim. When set to `false` it will avoid all shadow dom tests.
    * Defaults to `false`.
+   *
+   * @deprecated Since Stencil v3.0.0. IE 11, Edge <= 18, and old Safari versions
+   * are no longer supported.
    */
-  shadowDomShim?: boolean;
+  __deprecated__shadowDomShim?: boolean;
 
   /**
    * When a component is first attached to the DOM, this setting will wait a single tick before

diff --git a/src/runtime/bootstrap-custom-element.ts b/src/runtime/bootstrap-custom-element.ts
@@ -32,6 +32,7 @@ export const proxyCustomElement = (Cstr: any, compactMeta: d.ComponentRuntimeMet
     cmpMeta.$attrsToReflect$ = [];
   }
   if (BUILD.shadowDom && !supportsShadow && cmpMeta.$flags$ & CMP_FLAGS.shadowDomEncapsulation) {
+    // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
     cmpMeta.$flags$ |= CMP_FLAGS.needsShadowDomShim;
   }
 

diff --git a/src/runtime/bootstrap-lazy.ts b/src/runtime/bootstrap-lazy.ts
@@ -72,6 +72,7 @@ export const bootstrapLazy = (lazyBundles: d.LazyBundlesRuntimeData, options: d.
         cmpMeta.$watchers$ = {};
       }
       if (BUILD.shadowDom && !supportsShadow && cmpMeta.$flags$ & CMP_FLAGS.shadowDomEncapsulation) {
+        // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
         cmpMeta.$flags$ |= CMP_FLAGS.needsShadowDomShim;
       }
       const tagName =

diff --git a/src/runtime/connected-callback.ts b/src/runtime/connected-callback.ts
@@ -47,6 +47,7 @@ export const connectedCallback = (elm: d.HostElement) => {
         if (
           BUILD.hydrateServerSide ||
           ((BUILD.slot || BUILD.shadowDom) &&
+            // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
             cmpMeta.$flags$ & (CMP_FLAGS.hasSlotRelocation | CMP_FLAGS.needsShadowDomShim))
         ) {
           setContentReference(elm);

diff --git a/src/runtime/dom-extras.ts b/src/runtime/dom-extras.ts
@@ -125,6 +125,7 @@ export const patchChildSlotNodes = (elm: any, cmpMeta: d.ComponentRuntimeMeta) =
       return this[n];
     }
   }
+  // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
   if (cmpMeta.$flags$ & CMP_FLAGS.needsShadowDomShim) {
     const childNodesFn = elm.__lookupGetter__('childNodes');
 

diff --git a/src/runtime/initialize-component.ts b/src/runtime/initialize-component.ts
@@ -105,6 +105,7 @@ export const initializeComponent = async (
         if (
           !BUILD.hydrateServerSide &&
           BUILD.shadowDom &&
+          // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
           BUILD.shadowDomShim &&
           cmpMeta.$flags$ & CMP_FLAGS.needsShadowDomShim
         ) {

diff --git a/src/runtime/styles.ts b/src/runtime/styles.ts
@@ -63,6 +63,7 @@ export const addStyle = (
               hostElm,
               scopeId,
               style,
+              // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
               !!(cmpMeta.$flags$ & CMP_FLAGS.needsScopedEncapsulation)
             );
             const newScopeId = (styleElm as any)['s-sc'];
@@ -115,6 +116,7 @@ export const attachStyles = (hostRef: d.HostRef) => {
     elm
   );
 
+  // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
   if ((BUILD.shadowDom || BUILD.scoped) && BUILD.cssAnnotations && flags & CMP_FLAGS.needsScopedEncapsulation) {
     // only required when we're NOT using native shadow dom (slot)
     // or this browser doesn't support native shadow dom

diff --git a/src/testing/spec-page.ts b/src/testing/spec-page.ts
@@ -128,6 +128,7 @@ export async function newSpecPage(opts: NewSpecPageOptions): Promise<SpecPage> {
     BUILD.hydrateClientSide = false;
   }
   BUILD.cloneNodeFix = false;
+  // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
   BUILD.shadowDomShim = false;
   BUILD.safari10 = false;
   BUILD.attachStyles = !!opts.attachStyles;

diff --git a/src/utils/constants.ts b/src/utils/constants.ts
@@ -59,9 +59,15 @@ export const enum CMP_FLAGS {
   shadowDomEncapsulation = 1 << 0,
   scopedCssEncapsulation = 1 << 1,
   hasSlotRelocation = 1 << 2,
+  // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
+  // Note that when we remove this field we should consider whether we need to
+  // retain a placeholder here, since if we want to have compatability between
+  // different versions of the runtime then we'll need to not shift the values
+  // of the other higher flags down
   needsShadowDomShim = 1 << 3,
   shadowDelegatesFocus = 1 << 4,
   hasMode = 1 << 5,
+  // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
   needsScopedEncapsulation = scopedCssEncapsulation | needsShadowDomShim,
 }