New JS interop docs (#4578)

Fixes #5438 
---------

Co-authored-by: Srujan Gaddam <srujzs@google.com>
Co-authored-by: Parker Lougheed <parlough@gmail.com>
Co-authored-by: sigmundch <sigmund@google.com>

examples/create_libraries/lib/hw_mp.dart

@@ -4,4 +4,4 @@ library hw_mp;
 // #docregion export
 export 'src/hw_none.dart' // Stub implementation
     if (dart.library.io) 'src/hw_io.dart' // dart:io implementation
-    if (dart.library.html) 'src/hw_html.dart'; // dart:html implementation
+    if (dart.library.js_interop) 'src/hw_web.dart'; // package:web implementation

firebase.json

@@ -172,11 +172,11 @@
       { "source": "/go/non-promo-this", "destination": "/tools/non-promotion-reasons#this", "type": 301 },
       { "source": "/go/non-promo-write", "destination": "/tools/non-promotion-reasons#write", "type": 301 },
 
-      { "source": "/go/next-gen-js-interop", "destination": "/interop/js-interop#next-generation-js-interop-preview", "type": 301 },
+      { "source": "/go/next-gen-js-interop", "destination": "/interop/js-interop", "type": 301 },
       { "source": "/go/null-safety-migration", "destination": "/null-safety/migration-guide", "type": 301 },
       { "source": "/go/package-discontinue", "destination": "/tools/pub/publishing#discontinue", "type": 301 },
       { "source": "/go/package-retraction", "destination": "/tools/pub/publishing#retract", "type": 301 },
-      { "source": "/go/package-web", "destination": "https://pub.dev/packages/web", "type": 301 },
+      { "source": "/go/package-web", "destination": "/interop/js-interop/package-web", "type": 301 },
       { "source": "/go/pub-cache", "destination": "/tools/pub/cmd/pub-cache", "type": 301 },
       { "source": "/go/pubignore", "destination": "/tools/pub/publishing#what-files-are-published", "type": 301 },
       { "source": "/go/publishing-from-github", "destination": "/tools/pub/automated-publishing#publishing-packages-using-github-actions", "type": 301 },

src/_data/side-nav.yml

@@ -247,7 +247,21 @@
   - title: Java & Kotlin interop
     permalink: /interop/java-interop
   - title: JavaScript interop
-    permalink: /interop/js-interop
+    children:
+      - title: Overview
+        permalink: /interop/js-interop
+        match-page-url-exactly: true
+      - title: Usage
+        permalink: /interop/js-interop/usage
+      - title: JS types
+        permalink: /interop/js-interop/js-types
+      - title: Tutorials
+        permalink: /interop/js-interop/tutorials
+      - title: Past JS interop
+        permalink: /interop/js-interop/past-js-interop
+      - divider
+      - title: Web interop
+        permalink: /interop/js-interop/package-web
 
 - title: Tools & techniques
   expanded: false

src/content/guides/libraries/create-packages.md

@@ -72,7 +72,7 @@ by importing a single file.
 
 The lib directory might also include other importable, non-src, libraries.
 For example, perhaps your main library works across platforms, but
-you create separate libraries that rely on `dart:io` or `dart:html`.
+you create separate libraries that rely on `dart:io` or `dart:js_interop`.
 Some packages have separate libraries that are meant to be imported
 with a prefix, when the main library is not.
 
@@ -151,23 +151,23 @@ A common use case is a library that supports both web and native platforms.
 To conditionally import or export,
 you need to check for the presence of `dart:*` libraries.
 Here's an example of conditional export code that
-checks for the presence of `dart:io` and `dart:html`:
+checks for the presence of `dart:io` and `dart:js_interop`:
 
 <?code-excerpt "create_libraries/lib/hw_mp.dart (export)"?>
 ```dart title="lib/hw_mp.dart"
 export 'src/hw_none.dart' // Stub implementation
     if (dart.library.io) 'src/hw_io.dart' // dart:io implementation
-    if (dart.library.html) 'src/hw_html.dart'; // dart:html implementation
+    if (dart.library.js_interop) 'src/hw_web.dart'; // package:web implementation
 ```
 
 Here's what that code does:
 
 * In an app that can use `dart:io`
   (for example, a command-line app),
   export `src/hw_io.dart`.
-* In an app that can use `dart:html`
+* In an app that can use `dart:js_interop`
   (a web app),
-  export `src/hw_html.dart`.
+  export `src/hw_web.dart`.
 * Otherwise, export `src/hw_none.dart`.
 
 To conditionally import a file, use the same code as above,

src/content/guides/whats-new.md

@@ -219,7 +219,7 @@ we made the following changes:
 [source descriptor]: /tools/pub/cmd/pub-add#source-descriptor
 [SDK archive]: /get-dart/archive
 [glossary]: /resources/glossary
-[JS static interop support]: /interop/js-interop#next-generation-js-interop-preview
+[JS static interop support]: /interop/js-interop
 [analyzer plugins]: /tools/analysis#plugins
 
 ### Articles added to the Dart blog {:.no_toc}

src/content/interop/js-interop/index.md

@@ -0,0 +1,44 @@
+---
+title: JavaScript interoperability
+short-title: JS interop
+description: Integrate JavaScript code into your Dart web app.
+---
+
+The [Dart web platform](/overview#web-platform) supports communication with
+JavaScript apps and libraries, as well as browser APIs, using `dart:js_interop`.
+
+Web developers can benefit from using external JS libraries in their Dart code,
+without having to rewrite anything in Dart.
+
+{% comment %}
+## Why use JS interop?
+
+TODO: Should we have a paragraph here explaining the benefits of using interop?
+{% endcomment %}
+
+## Overview
+
+For information on how to write and use JavaScript interop:
+  * [Usage reference]
+  * [JS types reference]
+
+For information on interacting with web APIs:
+  * [`package:web` and migration]
+
+For tutorials and help:
+  * [How to mock JavaScript interop objects]
+
+For information on previous JavaScript interop libraries:
+  * [Past JS interop]
+
+For additional documentation on JavaScript interop:
+  * [`dart:js_interop` API reference]
+  * [`dart:js_interop_unsafe` API reference]
+
+[Usage reference]: /interop/js-interop/usage
+[JS types reference]: /interop/js-interop/js-types
+[`package:web` and migration]: /interop/js-interop/package-web
+[How to mock JavaScript interop objects]: /interop/js-interop/mock
+[Past JS interop]: /interop/js-interop/past-js-interop
+[`dart:js_interop` API reference]: https://api.dart.dev/dev/dart-js_interop/dart-js_interop-library.html
+[`dart:js_interop_unsafe` API reference]: https://api.dart.dev/dev/dart-js_interop_unsafe/dart-js_interop_unsafe-library.html