Merge branch 'main' of https://github.com/babel/website into sync-8f4…

…b541f

docs/assumptions.md

@@ -26,6 +26,10 @@ For example:
 This is advanced functionality. Please be careful when enabling assumptions, because they are not spec-compliant and may break your code in unexpected ways.
 :::
 
+:::tip
+Are you migrating from `@babel/preset-env`'s `loose` and `spec` options to granular assumptions? Check ["Migrating from `@babel/preset-env`'s `"loose"` and `"spec"` modes"](#migrating-from-babelpreset-envs-loose-and-spec-modes) for the equivalent assumptions-based configuration, ready to be copied and pasted as a starting point.
+:::
+
 ## `arrayLikeIsIterable`
 
 When spreading or iterating an array-like object, assume that it implements a `[Symbol.iterator]` method with the same behavior of the native `Array.prototype[Symbol.iterator]`, and thus directly iterate over its element by index.
@@ -381,3 +385,44 @@ class Child extends Parent {
 ```
 
 </div>
+
+## Migrating from `@babel/preset-env`'s `"loose"` and `"spec"` modes
+
+`@babel/preset-env`'s `loose` option is equivalent to the following configuration:
+```json title="JSON"
+{
+  "presets": [
+    ["@babel/preset-env", { "exclude": ["transform-typeof-symbol"] }]
+  ],
+  "assumptions": {
+    "arrayLikeIsIterable": true,
+    "constantReexports": true,
+    "ignoreFunctionLength": true,
+    "ignoreToPrimitiveHint": true,
+    "mutableTemplateObject": true,
+    "noClassCalls": true,
+    "noDocumentAll": true,
+    "noObjectSuper": true,
+    "noUndeclaredVariablesCheck": true,
+    "objectRestNoSymbols": true,
+    "privateFieldsAsProperties": true,
+    "pureGetters": true,
+    "setClassMethods": true,
+    "setComputedProperties": true,
+    "setPublicClassFields": true,
+    "setSpreadProperties": true,
+    "skipForOfIteratorClosing": true,
+    "superIsCallableConstructor": true
+  }
+}
+```
+
+`@babel/preset-env`'s `spec` option is equivalent to the following configuration:
+```json title="JSON"
+{
+  "presets": ["@babel/preset-env"],
+  "assumptions": {
+    "noNewArrows": false,
+  }
+}
+```

docs/preset-env.md

@@ -98,9 +98,9 @@ Added in: `v7.9.0`
 
 :::babel7
 
-:::note
-This option will be enabled by default in Babel 8
-:::
+::::note
+This option will be enabled by default in Babel 8.
+::::
 
 :::
 
@@ -114,14 +114,18 @@ When this option is enabled, `@babel/preset-env` tries to compile the broken syn
 
 Enable more spec compliant, but potentially slower, transformations for any plugins in this preset that support them.
 
+:::caution
+Consider migrating to the top level [`assumptions`](assumptions.md) available since Babel 7.13. See ["Migrating from `@babel/preset-env`'s `"loose"` and `"spec"` modes"](assumptions.md#migrating-from-babelpreset-envs-loose-and-spec-modes) for the equivalent assumptions-based configuration, ready to be copied and pasted as a starting point.
+:::
+
 ### `loose`
 
 `boolean`, defaults to `false`.
 
 Enable ["loose" transformations](http://2ality.com/2015/12/babel6-loose-mode.html) for any plugins in this preset that allow them.
 
 :::caution
-Consider migrating to the top level [`assumptions`](assumptions.md) available since Babel 7.13.
+Consider migrating to the top level [`assumptions`](assumptions.md) available since Babel 7.13. See ["Migrating from `@babel/preset-env`'s `"loose"` and `"spec"` modes"](assumptions.md#migrating-from-babelpreset-envs-loose-and-spec-modes) for the equivalent assumptions-based configuration, ready to be copied and pasted as a starting point.
 :::
 
 ### `modules`
@@ -158,14 +162,27 @@ An array of plugins to always include.
 
 Valid options include any:
 
+:::babel7
+
 - [Babel plugins](https://github.com/babel/babel/blob/main/packages/babel-compat-data/scripts/data/plugin-features.js) - both full and shorthand names are supported, for example the following are functionally equivalent:
   * `@babel/plugin-transform-spread`
   * `@babel/transform-spread`
   * `babel-transform-spread`
   * `transform-spread`
-
 - Built-ins (both for [core-js@2](https://github.com/babel/babel/blob/master/packages/babel-preset-env/src/polyfills/corejs2/built-in-definitions.js) and [core-js@3](https://github.com/babel/babel/blob/master/packages/babel-preset-env/src/polyfills/corejs3/built-in-definitions.js), such as `es.map`, `es.set`, or `es.object.assign`.
 
+:::
+
+:::babel8
+
+- [Babel plugins](https://github.com/babel/babel/blob/main/packages/babel-compat-data/scripts/data/plugin-features.js) - both full and shorthand names are supported, for example the following are functionally equivalent:
+  * `@babel/plugin-transform-optional-chaining`
+  * `@babel/transform-optional-chaining`
+  * `transform-optional-chaining`
+- [core-js@3](https://github.com/babel/babel/blob/master/packages/babel-preset-env/src/polyfills/corejs3/built-in-definitions.js) polyfills, such as `es.map`, `es.set`, or `es.object.assign`.
+
+:::
+
 Plugin names can be fully or partially specified (or using `RegExp`).
 
 Acceptable inputs:
@@ -192,7 +209,7 @@ An array of plugins to always exclude/remove.
 
 The possible options are the same as the `include` option.
 
-This option is useful for excluding a transform like `@babel/plugin-transform-regenerator` if you don't use generators and don't want to include `regeneratorRuntime` (when using `useBuiltIns`) or for using another plugin like [fast-async](https://github.com/MatAtBread/fast-async) instead of [Babel's async-to-gen](plugin-transform-async-generator-functions.md).
+This option is useful for excluding a transform like `@babel/plugin-transform-regenerator`, for example if you are using another plugin like [fast-async](https://github.com/MatAtBread/fast-async) instead of [Babel's async-to-gen](plugin-transform-async-generator-functions.md).
 
 ### `useBuiltIns`
 
@@ -202,6 +219,8 @@ This option configures how `@babel/preset-env` handles polyfills.
 
 When either the `usage` or `entry` options are used, `@babel/preset-env` will add direct references to `core-js` modules as bare imports (or requires). This means `core-js` will be resolved relative to the file itself and needs to be accessible.
 
+:::babel7
+
 Since `@babel/polyfill` was deprecated in 7.4.0, we recommend directly adding `core-js` and setting the version via the [`corejs`](#corejs) option.
 
 ```shell npm2yarn
@@ -212,6 +231,18 @@ npm install core-js@3 --save
 npm install core-js@2 --save
 ```
 
+:::
+
+:::babel8
+
+When auto-injecting polyfills using `@babel/preset-env`, you must add `core-js` to your dependencies:
+
+```shell npm2yarn
+npm install core-js
+```
+
+:::
+
 #### `useBuiltIns: 'entry'`
 
 <details>
@@ -223,12 +254,18 @@ npm install core-js@2 --save
 | `v7.0.0` | It replaces `"@babel/polyfill"` entry imports |
 </details>
 
-:::tip
+::::tip
 Only use `import "core-js";` once in your whole app.
+
+:::babel7
+
 If you are using `@babel/polyfill`, it already includes `core-js`: importing it twice will throw an error.
+
+:::
+
 Multiple imports or requires of those packages might cause global collisions and other issues that are hard to trace.
 We recommend creating a single entry file that only contains the `import` statements.
-:::
+::::
 
 This option enables a new plugin that replaces the `import "core-js/stable";` and `require("core-js");` statements with individual imports to different `core-js` entry points based on environment.
 
@@ -270,9 +307,13 @@ import "core-js/modules/esnext.math.scale";
 
 You can read [core-js](https://github.com/zloirock/core-js)'s documentation for more information about the different entry points.
 
-:::note
+:::babel7
+
+::::note
 When using `core-js@2` (either explicitly using the [`corejs: "2"`](#corejs) option or implicitly), `@babel/preset-env` will also transform imports and requires of `@babel/polyfill`.
 This behavior is deprecated because it isn't possible to use `@babel/polyfill` with different `core-js` versions.
+::::
+
 :::
 
 #### `useBuiltIns: 'usage'`
@@ -319,8 +360,17 @@ Don't add polyfills automatically per file, and don't transform `import "core-js
 
 Added in: `v7.4.0`
 
-`string` or `{ version: string, proposals: boolean }`, defaults to `"2.0"`. The `version` string can be any
-supported `core-js` versions. For example, `"3.8"` or `"2.0"`.
+:::babel7
+
+`string` or `{ version: string, proposals: boolean }`, defaults to `"2.0"`. The `version` string can be any supported `core-js` versions. For example, `"3.8"` or `"2.0"`.
+
+:::
+
+:::babel8
+
+`string` or `{ version: string, proposals: boolean }`, defaults to `"3.0"`. The `version` string can be any supported `core-js` versions. For example, `"3.8"`.
+
+:::
 
 This option only has an effect when used alongside `useBuiltIns: usage` or `useBuiltIns: entry`, and ensures `@babel/preset-env` injects the polyfills supported by your `core-js` version. It is recommended to specify the minor
 version otherwise `"3"` will be interpreted as `"3.0"` which may not include polyfills for the latest features.

website/docusaurus.config.js

@@ -96,12 +96,16 @@ toolsMD.forEach(tool => {
  * @returns md-ast transformer
  */
 function remarkDirectiveBabel8Plugin({ renderBabel8 }) {
-  return async function transformer(root) {
+  return function transformer(root) {
     const children = root.children;
     const deleteBatches = [];
     for (let index = 0; index < children.length; index++) {
       const node = children[index];
-      if (node.type !== "paragraph") continue;
+      if (node.type === "admonitionHTML") { // for support inside ::tip, etc
+        transformer(node);
+      } else if (node.type !== "paragraph") {
+        continue;
+      }
       const directiveLabel = node.children?.[0].value;
       if (directiveLabel === ":::babel8" || directiveLabel === ":::babel7") {
         let containerEnd = index + 1,