Update decorators doc to stage 3, update babel config.

packages/lit-dev-content/site/docs/components/decorators.md

@@ -10,10 +10,20 @@ versionLinks:
 
 Decorators are special functions that can modify the behavior of classes, class methods, and class fields. Lit uses decorators to provide declarative APIs for things like registering elements, reactive properties, and queries.
 
-Decorators are a [stage 2 proposal](https://github.com/tc39/proposal-decorators) for addition to the ECMAScript standard, which means they're neither finalized nor implemented in browsers yet. Compilers like [Babel](https://babeljs.io/) and [TypeScript](https://www.typescriptlang.org/) provide support for proposed features like decorators by compiling them into standard JavaScript a browser can run.
+Decorators are a [stage 3 proposal](https://github.com/tc39/proposal-decorators) for addition to the ECMAScript standard. Currently no browsers implement decorators, but compilers like [Babel](https://babeljs.io/) and [TypeScript](https://www.typescriptlang.org/) provide support for an earlier version of the decorators proposal. Lit decorators work with Babel and TypeScript, and will be updated to work with the final specification when it's implemented in browsers.
 
 See the [Enabling decorators](#enabling-decorators) section for more information.
 
+{% aside "info" %}
+
+What does stage 3 mean?
+
+Stage 3 means that the specification text is complete, and ready for browsers to implement. Once the specification has been implemented in multiple browsers, it can move to the final stage, stage 4, and be added to the ECMAScript standard. A stage 3 proposal can still change, but only if critical issues are discovered during implementation.
+
+{% endaside %}
+
+
+
 Lit supplies a set of decorators that reduce the amount of boilerplate code you need to write when defining a component. For example, the `@customElement` and `@property` decorators make a basic element definition more compact:
 
 ```ts
@@ -59,7 +69,7 @@ You can import all the lit decorators via the `lit/decorators.js` module:
 import {customElement, property, eventOptions, query} from 'lit/decorators.js';
 ```
 
-To reduce the amount of code needed to run the component, decorators can be imported individually into component code. All decorators are available at `lit/decorators/<decorator-name>`. For example,
+To reduce the amount of code needed to run the component, decorators can be imported individually into component code. All decorators are available at `lit/decorators/<decorator-name>.js`. For example,
 
 ```js
 import {customElement} from 'lit/decorators/custom-element.js';
@@ -96,36 +106,43 @@ Note, the `@babel/plugin-proposal-class-properties` may not be required with the
 
 To set up the plugins, add code like this to your Babel configuration:
 
-```js
-assumptions = {
+```json
+"assumptions": {
   "setPublicClassFields": true
-};
-
-plugins = [
-  ['@babel/plugin-proposal-decorators', {decoratorsBeforeExport: true}],
-  ["@babel/plugin-proposal-class-properties"],
-];
+},
+"plugins": [
+  ["@babel/plugin-proposal-decorators", {
+    "version": "2018-09",
+    "decoratorsBeforeExport": true
+  }],
+  ["@babel/plugin-proposal-class-properties"]
+]
 ```
 
 <div class="alert alert-info">
 
-Currently the older `legacy` mode of Babel decorators is not supported, but this may change as Babel evolves. See the [Babel documentation](https://babeljs.io/docs/en/babel-plugin-proposal-decorators#legacy) if you want to experiment.
+Babel decorator support has been tested with `version: '2018-09'`. This is currently the default, but we recommend setting the version explicitly in case the default changes. Other versions ('2021-12' or 'legacy') are not supported, but this may change as Babel evolves. See the [Babel documentation](https://babeljs.io/docs/en/babel-plugin-proposal-decorators#options) if you want to experiment.
 
 </div>
 
 ### Using decorators with TypeScript and Babel
 
 When using TypeScript with Babel, it's important to order the TypeScript transform before the decorators transform in your Babel config as follows:
 
-```js
+```json
 {
   "assumptions": {
     "setPublicClassFields": true
   },
-  "plugins":[
-    ["@babel/plugin-transform-typescript", {"allowDeclareFields": true}],
-    ["@babel/plugin-proposal-decorators", {"decoratorsBeforeExport": true}],
-    ["@babel/plugin-proposal-class-properties"],
+  "plugins": [
+    ["@babel/plugin-transform-typescript", {
+      "allowDeclareFields": true
+    }],
+    ["@babel/plugin-proposal-decorators", {
+      "version": "2018-09",
+      "decoratorsBeforeExport": true
+    }],
+    ["@babel/plugin-proposal-class-properties"]
   ]
 }
 ```