chore(config): mark cssVarShim as deprecated (#3894)

This marks the `extras.cssVarsShim` field on the Stencil configuration
interface as deprecated, and introduces TODO comments for removing all
of the relevant code.

BREAKING CHANGES: the `cssVarsShim` field is now deprecated. Support for
IE 11, non-Chromium Edge, and Safari 10 has been dropped.

BREAKING_CHANGES.md

@@ -16,6 +16,7 @@ This is a comprehensive list of the breaking changes introduced in the major ver
     * [`dist-custom-elements` Type Declarations](#dist-custom-elements-type-declarations)
   * [Legacy Browser Support Fields Deprecated](#legacy-browser-support-fields-deprecated)
     * [`dynamicImportShim`](#dynamicimportshim)
+    * [`cssVarShim`](#cssvarshim)
   * [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)
@@ -98,6 +99,25 @@ export const config: Config = {
 };
 ```
 
+##### `cssVarShim`
+
+`extras.cssVarShim` causes Stencil to include a polyfill for [CSS
+variables](https://developer.mozilla.org/en-US/docs/Web/CSS/--*). For Stencil
+v3.0.0 this field is renamed to `__deprecated__cssVarsShim`. 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__cssVarsShim: 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`.

src/app-data/index.ts

@@ -72,6 +72,7 @@ export const BUILD: BuildConditionals = {
   propBoolean: true,
   propNumber: true,
   propString: true,
+  // TODO(STENCIL-659): Remove code implementing the CSS variable shim
   cssVarShim: false,
   constructableCSS: true,
   cmpShouldUpdate: true,

src/client/client-patch-browser.ts

@@ -10,8 +10,10 @@ export const patchBrowser = (): Promise<d.CustomElementsDefineOptions> => {
     consoleDevInfo('Running in development mode.');
   }
 
+  // TODO(STENCIL-659): Remove code implementing the CSS variable shim
   if (BUILD.cssVarShim) {
     // shim css vars
+    // TODO(STENCIL-659): Remove code implementing the CSS variable shim
     plt.$cssShim$ = (win as any).__cssshim;
   }
 

src/client/client-patch-esm.ts

@@ -3,11 +3,13 @@ import { CSS, plt, promiseResolve, win } from '@platform';
 
 export const patchEsm = () => {
   // NOTE!! This fn cannot use async/await!
+  // TODO(STENCIL-659): Remove code implementing the CSS variable shim
   // @ts-ignore
   if (BUILD.cssVarShim && !(CSS && CSS.supports && CSS.supports('color', 'var(--c)'))) {
     // @ts-ignore
     return import(/* webpackChunkName: "polyfills-css-shim" */ './polyfills/css-shim.js').then(() => {
       if ((plt.$cssShim$ = (win as any).__cssshim)) {
+        // TODO(STENCIL-659): Remove code implementing the CSS variable shim
         return plt.$cssShim$.i();
       } else {
         // for better minification

src/client/client-window.ts

@@ -4,6 +4,7 @@ import type * as d from '../declarations';
 
 export const win = typeof window !== 'undefined' ? window : ({} as Window);
 
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 export const CSS = BUILD.cssVarShim ? (win as any).CSS : null;
 
 export const doc = win.document || ({ head: {} } as Document);

src/client/polyfills/css-shim/css-parser.ts

@@ -1,3 +1,4 @@
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 /*
 Extremely simple css parser. Intended to be not more than what we need
 and definitely not necessarily correct =).

src/client/polyfills/css-shim/custom-style.ts

@@ -1,10 +1,12 @@
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 import { CssVarShim } from '../../../declarations';
 import { CSSScope } from './interfaces';
 import { addGlobalLink, loadDocument, startWatcher } from './load-link-styles';
 import { addGlobalStyle, parseCSS, reScope, updateGlobalScopes } from './scope';
 import { getActiveSelectors, resolveValues } from './selectors';
 import { executeTemplate } from './template';
 
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 export class CustomStyle implements CssVarShim {
   private count = 0;
   private hostStyleMap = new WeakMap<HTMLElement, HTMLStyleElement>();

src/client/polyfills/css-shim/index.ts

@@ -1,3 +1,4 @@
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 import { CustomStyle } from './custom-style';
 
 (function (win: any) {

src/client/polyfills/css-shim/interfaces.ts

@@ -1,3 +1,4 @@
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 export type CSSVariables = { [prop: string]: string };
 export type CSSEval = (p: CSSVariables) => string;
 export type CSSSegment = string | CSSEval;

src/client/polyfills/css-shim/load-link-styles.ts

@@ -1,3 +1,4 @@
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 import { CSSScope } from './interfaces';
 import { addGlobalStyle, updateGlobalScopes } from './scope';
 

src/client/polyfills/css-shim/regex.ts

@@ -1,3 +1,4 @@
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 export const VAR_USAGE_START = /\bvar\(/;
 export const VAR_ASSIGN_START = /\B--[\w-]+\s*:/;
 

src/client/polyfills/css-shim/scope.ts

@@ -1,3 +1,4 @@
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 import { parse } from './css-parser';
 import { CSSScope } from './interfaces';
 import { getSelectors, getSelectorsForScopes, resolveValues } from './selectors';

src/client/polyfills/css-shim/selectors.ts

@@ -1,3 +1,4 @@
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 import { StyleNode, types } from './css-parser';
 import { CSSScope, CSSSelector, CSSTemplate, Declaration } from './interfaces';
 import { compileTemplate, executeTemplate } from './template';

src/client/polyfills/css-shim/template.ts

@@ -1,3 +1,4 @@
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 import { CSSTemplate, CSSVariables } from './interfaces';
 import { COMMENTS, TRAILING_LINES, VAR_ASSIGN_START, VAR_USAGE_START } from './regex';
 import { findRegex } from './utils';

src/client/polyfills/css-shim/test/compiler.spec.ts

@@ -1,3 +1,4 @@
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 import { compileTemplate, compileVar, executeTemplate, findVarEndIndex, parseVar } from '../template';
 
 describe('compiler', () => {

src/client/polyfills/css-shim/test/css-shim.spec.ts

@@ -1,3 +1,4 @@
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 import { mockWindow } from '@stencil/core/testing';
 
 import { CustomStyle } from '../custom-style';

src/client/polyfills/css-shim/test/init-css-shim.spec.ts

@@ -1,3 +1,4 @@
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 import { fixRelativeUrls, hasCssVariables, hasRelativeUrls } from '../load-link-styles';
 
 describe('hasCssVariables', () => {

src/client/polyfills/css-shim/test/utils.spec.ts

@@ -1,3 +1,4 @@
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 import { CSSSelector, Declaration } from '../interfaces';
 import { parseCSS } from '../scope';
 import { getDeclarations, normalizeValue, resolveValues } from '../selectors';

src/client/polyfills/css-shim/utils.ts

@@ -1,3 +1,4 @@
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 export const GLOBAL_SCOPE = ':root';
 
 export function findRegex(regex: RegExp, cssText: string, offset: number) {

src/compiler/app-core/app-polyfills.ts

@@ -19,7 +19,8 @@ export const getAppBrowserCorePolyfills = async (config: d.Config, compilerCtx:
   // read all the polyfill content, in this particular order
   const polyfills = INLINE_POLYFILLS.slice();
 
-  if (config.extras.cssVarsShim) {
+  // TODO(STENCIL-659): Remove code implementing the CSS variable shim
+  if (config.extras.__deprecated__cssVarsShim) {
     polyfills.push(INLINE_CSS_SHIM);
   }
 

src/compiler/config/test/validate-config.spec.ts

@@ -354,7 +354,8 @@ describe('validation', () => {
     const { config } = validateConfig(userConfig, bootstrapConfig);
     expect(config.extras.appendChildSlotFix).toBe(false);
     expect(config.extras.cloneNodeFix).toBe(false);
-    expect(config.extras.cssVarsShim).toBe(false);
+    // TODO(STENCIL-659): Remove code implementing the CSS variable shim
+    expect(config.extras.__deprecated__cssVarsShim).toBe(false);
     // TODO(STENCIL-661): Remove code related to the dynamic import shim
     expect(config.extras.__deprecated__dynamicImportShim).toBe(false);
     expect(config.extras.lifecycleDOMEvents).toBe(false);

src/compiler/config/validate-config.ts

@@ -71,7 +71,8 @@ export const validateConfig = (
   validatedConfig.extras = validatedConfig.extras || {};
   validatedConfig.extras.appendChildSlotFix = !!validatedConfig.extras.appendChildSlotFix;
   validatedConfig.extras.cloneNodeFix = !!validatedConfig.extras.cloneNodeFix;
-  validatedConfig.extras.cssVarsShim = !!validatedConfig.extras.cssVarsShim;
+  // TODO(STENCIL-659): Remove code implementing the CSS variable shim
+  validatedConfig.extras.__deprecated__cssVarsShim = !!validatedConfig.extras.__deprecated__cssVarsShim;
   // TODO(STENCIL-661): Remove code related to the dynamic import shim
   validatedConfig.extras.__deprecated__dynamicImportShim = !!validatedConfig.extras.__deprecated__dynamicImportShim;
   validatedConfig.extras.lifecycleDOMEvents = !!validatedConfig.extras.lifecycleDOMEvents;

src/compiler/output-targets/dist-hydrate-script/hydrate-build-conditionals.ts

@@ -7,6 +7,7 @@ export const getHydrateBuildConditionals = (cmps: d.ComponentCompilerMeta[]) =>
   build.slotRelocation = true;
   build.lazyLoad = true;
   build.hydrateServerSide = true;
+  // TODO(STENCIL-659): Remove code implementing the CSS variable shim
   build.cssVarShim = false;
   build.hydrateClientSide = true;
   build.isDebug = false;

src/compiler/output-targets/dist-lazy/lazy-build-conditionals.ts

@@ -10,7 +10,8 @@ export const getLazyBuildConditionals = (
 
   build.lazyLoad = true;
   build.hydrateServerSide = false;
-  build.cssVarShim = config.extras.cssVarsShim;
+  // TODO(STENCIL-659): Remove code implementing the CSS variable shim
+  build.cssVarShim = config.extras.__deprecated__cssVarsShim;
   build.transformTagName = config.extras.tagNameTransform;
   build.asyncQueue = config.taskQueue === 'congestionAsync';
   build.taskQueue = config.taskQueue !== 'immediate';

src/declarations/stencil-private.ts

@@ -169,6 +169,7 @@ export interface BuildConditionals extends Partial<BuildFeatures> {
   cssAnnotations?: boolean;
   lazyLoad?: boolean;
   profile?: boolean;
+  // TODO(STENCIL-659): Remove code implementing the CSS variable shim
   cssVarShim?: boolean;
   constructableCSS?: boolean;
   appendChildSlotFix?: boolean;
@@ -1079,6 +1080,7 @@ export interface HostRuleHeader {
   value?: string;
 }
 
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 export interface CssVarShim {
   i(): Promise<any>;
   addLink(linkEl: HTMLLinkElement): Promise<any>;
@@ -1694,6 +1696,7 @@ export interface HostRef {
 }
 
 export interface PlatformRuntime {
+  // TODO(STENCIL-659): Remove code implementing the CSS variable shim
   $cssShim$?: CssVarShim;
   $flags$: number;
   $orgLocNodes$?: Map<string, RenderNode>;

src/declarations/stencil-public-compiler.ts

@@ -267,11 +267,15 @@ export interface ConfigExtras {
    */
   cloneNodeFix?: boolean;
 
+  // TODO(STENCIL-659): Remove code implementing the CSS variable shim
   /**
    * Include the CSS Custom Property polyfill/shim for legacy browsers. ESM builds will
    * not include the css vars shim. Defaults to `false`
+   *
+   * @deprecated Since Stencil v3.0.0. IE 11, Edge <= 18, and old Safari
+   * versions are no longer supported.
    */
-  cssVarsShim?: boolean;
+  __deprecated__cssVarsShim?: boolean;
 
   // TODO(STENCIL-661): Remove code related to the dynamic import shim
   /**

src/runtime/disconnected-callback.ts

@@ -18,7 +18,9 @@ export const disconnectedCallback = (elm: d.HostElement) => {
     }
 
     // clear CSS var-shim tracking
+    // TODO(STENCIL-659): Remove code implementing the CSS variable shim
     if (BUILD.cssVarShim && plt.$cssShim$) {
+      // TODO(STENCIL-659): Remove code implementing the CSS variable shim
       plt.$cssShim$.removeHost(elm);
     }
 

src/runtime/styles.ts

@@ -56,7 +56,9 @@ export const addStyle = (
           // This is only happening on native shadow-dom, do not needs CSS var shim
           styleElm.innerHTML = style;
         } else {
+          // TODO(STENCIL-659): Remove code implementing the CSS variable shim
           if (BUILD.cssVarShim && plt.$cssShim$) {
+            // TODO(STENCIL-659): Remove code implementing the CSS variable shim
             styleElm = plt.$cssShim$.createHostStyle(
               hostElm,
               scopeId,

src/runtime/update-component.ts

@@ -87,7 +87,9 @@ const updateComponent = async (hostRef: d.HostRef, instance: any, isInitialLoad:
   } else {
     callRender(hostRef, instance, elm);
   }
+  // TODO(STENCIL-659): Remove code implementing the CSS variable shim
   if (BUILD.cssVarShim && plt.$cssShim$) {
+    // TODO(STENCIL-659): Remove code implementing the CSS variable shim
     plt.$cssShim$.updateHost(elm);
   }
   if (BUILD.isDev) {

src/testing/platform/testing-platform.ts

@@ -26,6 +26,7 @@ export const setPlatformHelpers = (helpers: {
   Object.assign(plt, helpers);
 };
 
+// TODO(STENCIL-659): Remove code implementing the CSS variable shim
 export const cssVarShim: d.CssVarShim = false as any;
 export const supportsListenerOptions = true;
 export const supportsConstructableStylesheets = false;