Adds browser support info (#117)

Adds browser support info to Build > Requirements

Author: Steve Orvell

packages/lit-dev-content/.eleventy.js

@@ -266,7 +266,10 @@ ${content}
     ).filter(
       // TODO(aomarks) This is brittle, we need a way to annotate inside an md
       // file that a page shouldn't be generated.
-      (file) => !file.includes('why-lit') && !file.includes('getting-started')
+      (file) =>
+        !file.includes('why-lit') &&
+        !file.includes('getting-started') &&
+        !file.includes('browser-support')
     );
     await Promise.all(emptyDocsIndexFiles.map((path) => fs.unlink(path)));
 

packages/lit-dev-content/site/guide/getting-started.md

@@ -323,9 +323,7 @@ If you already have a dev server that works with your build system, it should wo
 
 ### Supporting older browsers
 
-To support older browsers that don't support ES6 and the web components specifications, you'll need to take a few extra steps to produce code that will run on the older browsers.
-
-See [Build for production](build) for more information.
+For older browsers like Internet Explorer 11 that don't support ES2020 and web components natively, see [Tools and Workflows](/guide/tools/overview) for information about setting up Lit to work for testing, development, building, and publishing.
 
 ### Next steps
 

packages/lit-dev-content/site/guide/platform-support/index.md

@@ -30,7 +30,7 @@ There are many development servers that can deal with module specifiers. If you
 
 If you need a dev server, we recommend [Web Dev Server](https://modern-web.dev/docs/dev-server/overview/).
 
-### Web Dev Server
+### Web Dev Server { #web-dev-server }
 
 [Web Dev Server](https://modern-web.dev/docs/dev-server/overview/) is an open-source dev server that enables a build-free development process.
 

packages/lit-dev-content/site/guide/platform-support/overview.md

@@ -31,6 +31,17 @@ Webpack automatically handles bare module specifiers; for Rollup, you'll need a
 
 **Why bare module specifiers?** Bare module specifiers let you import modules without knowing exactly where the package manager has installed them. A standards proposal called [Import maps](https://github.com/WICG/import-maps) is [starting to ship](https://chromestatus.com/feature/5315286962012160), which will let let browsers support bare module specifiers. In the meantime, bare import specifiers can easily be transformed as a build step. There are also some polyfills and module loaders that support import maps.
 
+### Modern browser breakdown
+
+All modern browsers update automatically and users are highly likely to have a recent version. The following table lists the minimum version of each major browser that natively supports ES2020 and web components, the key features on which Lit relies.
+
+| Browser	| Supports ES2020 & web components |
+|:--------|:--------------------------------:|
+| Chrome  |	>=80                             |
+| Safari  |	>=13                             |
+|	Firefox |	>=72                             |
+|	Edge    |	>=80                             |
+
 ## Requirements for legacy browsers {#building-for-legacy-browsers}
 
 Supporting older browsers (specifically Internet Explorer 11, but also older versions of evergreen browsers), requires a number of extra steps:
@@ -39,6 +50,19 @@ Supporting older browsers (specifically Internet Explorer 11, but also older ver
 *   Transforming ES modules to another module system.
 *   Loading polyfills.
 
+### Legacy browser breakdown
+
+The following table lists supported browser versions that require transpiling Javascript and loading polyfills:
+
+| Browser           | Transpile JS | Transpile JS & load polyfills |
+|:------------------|:------------:|:-----------------------------:|
+| Chrome            | 67-79        | <67                           |
+| Safari            | 10-12        | <10                           |
+| Firefox           | 63-71        | <63                           |
+| Edge              | 79           |                               |
+| Edge "classic"    |              | <=18                         |
+| Internet Explorer |              | 11                            |
+
 ### Transpiling to ES5 {#transpiling-to-es5}
 
 Rollup, webpack and other build tools have plugins to support transpiling modern JavaScript for older browsers. [Babel](https://babeljs.io/) is the most commonly used transpiler.
@@ -79,7 +103,7 @@ The IIFE format works fine if all of your code can be bundled into a single file
 
 ## Polyfills {#polyfills}
 
-Using Lit on older browsers will require loading polyfills for standard JavaScript features like Promises and async/await, the Web Components polyfills, as well as a `polyfill-support` script provided in the Lit package for interfacing Lit with the Web Components polyfills.
+Using Lit on older browsers will require loading polyfills for standard JavaScript features like Promises and async/await, the web components polyfills, as well as a `polyfill-support` script provided in the Lit package for interfacing Lit with the Web Components polyfills.
 
 These are the recommended polyfills:
 
@@ -91,12 +115,71 @@ These are the recommended polyfills:
   * [`requirejs`](https://www.npmjs.com/package/requirejs) - AMD module loader
 * Polyfills for Web Components:
   * [`@webcomponents/webcomponentsjs`](https://www.npmjs.com/package/@webcomponents/webcomponentsjs) - Polyfills for custom elements, shadow DOM, template, and some newer DOM APIs
-  * `lit/platform-support.js` - A file that ships in the `lit` package that must be loaded when using `webcomponentsjs`
+  * `lit/polyfill-support.js` - A file that ships in the `lit` package that must be loaded when using `webcomponentsjs`
+
+Note that you may need other polyfills depending on the features your application uses.
+
+### Loading polyfills
 
-<div class="alert alert-info">
+The Javascript polyfills should be bundled separately from the application bundle, and loaded before the web components polyfills, since those polyfills rely on modern JS like `Promise`. Putting it all together, the page should load code as follows:
 
-Note that the Javascript polyfills should be bundled separately from the application bundle, and loaded before the Web Components polyfills, since those polyfills rely on modern JS like `Promise`.
+```html
+<script src="path/to/js/polyfills/you/need.js"></script>
+<script src="node_modules/lit/polyfill-support.js"></script>
+<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
+<!-- Load application code here -->
+```
 
-</div>
+### Web components polyfills
 
-Note that you may need other polyfills depending on the features your application uses.
+For detailed information about loading and configuring the web components polyfills, see the [webcomponentsjs documentation](https://github.com/webcomponents/polyfills/tree/master/packages/webcomponentsjs). The following is a summary of some of the key points.
+
+#### Loading options
+
+There are two main ways to load the web components polyfills:
+
+- `webcomponents-bundle.js` includes all of the polyfills necessary to run on any of the supported browsers. Because all browsers receive all polyfills, this results in extra bytes being sent to browsers that support one or more feature.
+- `webcomponents-loader.js` performs client-side feature-detection and loads just the required polyfills. This requires an extra round-trip to the server, but saves bandwidth for browsers that support one or more features.
+
+#### Loading the ES5 adapter
+
+It's best to serve a modern build to modern browsers to avoid sending the extra code needed for older browsers. However, it can be convenient to serve just a single set of files. If you do this, there is one extra required step. In order for ES5 transpiled code to work with native web components and specifically custom elements, a small adapter is needed. For a detailed explanation, see the [webcomponentsjs documentation](https://github.com/webcomponents/polyfills/tree/master/packages/webcomponentsjs#custom-elements-es5-adapterjs).
+
+Load the `custom-elements-es5-adapter.js` after any Babel polyfills and before web components, like this:
+
+```html
+<script src="path/to/js/polyfills/you/need.js"></script>
+<script src="node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>
+<script src="node_modules/lit/polyfill-support.js"></script>
+<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
+<!-- Load application code here -->
+```
+
+#### Setting web components polyfill options
+
+By default, the individual polyfill for a given feature is disabled on browsers that natively support that feature.
+For testing purposes, you can force the polyfills on for browsers that have native support.
+
+While the web components polyfills strive to match the spec, there are some infidelities particularly around styling (see [ShadyCSS limitations](https://github.com/webcomponents/polyfills/tree/master/packages/shadycss#limitations)). We recommend ensuring you test with polyfills both on and off, either on the browsers that need them, or by forcing them on. You can force the polyfills on by adding a JavaScript snippet before you import the polyfills:
+
+```html
+<script>
+  // Force all polyfills on
+  if (window.customElements) window.customElements.forcePolyfill = true;
+  ShadyDOM = { force: true };
+  ShadyCSS = { shimcssproperties: true};
+</script>
+<script src="./node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
+```
+
+Or, you if you use the `webcomponents-bundle.js` file, you can force the polyfills on by adding query parameters to the app's URL:
+
+`https://www.example.com/my-application/view1?wc-ce&wc-shadydom&wc-shimcssproperties`
+
+The following table lists the JavaScript snippets and query parameters for each polyfill.
+
+| Polyfill    | Javascript                          | Query parameter          |
+|:------------|:------------------------------------|:-------------------------|
+| Custom Elements | `if (window.customElements) window.customElements.forcePolyfill = true;` | `wc-ce` |
+| Shadow DOM | `ShadyDOM = { force: true };` | `wc-shadydom`              |
+| CSS custom properties | `ShadyCSS = { shimcssproperties: true};` | `wc-shimcssproperties` |

packages/lit-dev-content/site/guide/tools/development.md

@@ -32,7 +32,7 @@ The test environment you use must have support for using modern Javascript, incl
 
 To test on older browsers, your test environment will need to load some polyfills, including the [web components polyfills](https://github.com/webcomponents/polyfills/tree/master/packages/webcomponentsjs) and Lit's `polyfill-support` module. See the [Browser Support](../browser-support) documentation for more details.
 
-## Using Web Test Runner
+## Using Web Test Runner { #web-test-runner }
 
 We recommend using [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/) since it is specifically designed to test modern web libraries like Lit using modern web features like custom elements and shadow DOM. See the [Getting Started](https://modern-web.dev/guides/test-runner/getting-started) documentation for Web Test Runner.