restructure

src/_data/side-nav.yml

@@ -155,18 +155,19 @@
             permalink: /web/js-interop
           - title: Reference
             permalink: /web/js-interop/reference
-          - title: How to interop with DOM APIs
-            permalink: /web/js-interop/dom
-          - title: How to interop with JavaScript libraries and apps
-            permalink: /web/js-interop/js-app
-          - title: How to test and mock JavaScript interop in Dart
-            permalink: /web/js-interop/test-and-mock
-          - title: Non-static JS interop
+          - title: Tutorials
+            permalink: /web/js-interop/tutorials
+            children:
+              - title: How to interop with DOM APIs
+                permalink: /web/js-interop/dom
+              - title: How to interop with JavaScript libraries and apps
+                permalink: /web/js-interop/js-app
+              - title: How to test and mock JavaScript interop in Dart
+                permalink: /web/js-interop/test-and-mock
+          - title: Past JS interop
             permalink: /web/js-interop/past-js-interop
-          - title: Migration
-            permalink: /web/js-interop/migration
-          - title: FAQ & troubleshooting
-            permalink: /web/js-interop/faq-troubleshooting
+          - title: dart:js_util
+            permalink: /web/js-interop/js-util
     - title: Google APIs
       permalink: /guides/google-apis
     - title: Multi-platform apps

src/web/js-interop/dom.md

@@ -4,7 +4,7 @@ description:
 ---
 
 {{site.why.learn}}
-  * 
+  * How to...
 {{site.why.end}}
 
 // *Introdcution paragraphs*
@@ -35,4 +35,4 @@ Step subsections should be actionalble, like "Build...", "Retrieve...", "Configu
 
 ## What next?
 
-Point to JS tutorial, testing and mocking tutorial
+Point to other tutorials, reference, etc.

src/web/js-interop/index.md

@@ -1,7 +1,7 @@
 ---
 title: JavaScript interoperability
 short-title: JS interop
-description: "Use package:js to integrate JavaScript code into your Dart web app."
+description: Integrate JavaScript code into your Dart web app.
 ---
 
 The [Dart web platform](/overview#web-platform) supports communication with
@@ -10,12 +10,6 @@ package, also known as `dart:js_interop`.
 Web developers can benefit from using external JS libraries in their Dart code, without
 having to rewrite anything in Dart.
 
-// *Not sure if we want to actually put this on the page, but to summarize:*
-
-This page introduces our JS interop model, walks through a brief example showing
-just how easy JS interop with Dart is, highlights the major features of our JS interop strategy,
-and then summarizes the rest of our docs on JS interop so you know where to go next.
-
 ## Static interop
 
 The principal model of JS interop in Dart is **static interop**.
@@ -29,10 +23,24 @@ without the overhead of a traditional class, enabling zero cost wrapping.
 
 ### Why static interop?
 
-Desire to decouple core of dart from where it’s embedded
-Rather just provide the capabilities to access the embedder
-Past renditions of js interop had us owning too much of the process of writing everything from the bindings to the browser
-Capabilities of past options were not primed to handle that decoupling, had limitations around using the DOM, typing, etc., so static interop was developed to solve those shortcomings
+Static interop represents the desire to decouple Dart's "core" from the platform
+where it's embedded
+(*maybe definition of "embedded" or examples here, like the browser, Flutter, etc.?*).
+
+Our [previous iterations of JS interop][] provided the capabillity
+to access the embedder, but were not primed to handle that decoupling.
+Too much of the process was entwined into the Dart side,
+like writing all the bindings to the browser
+(*not sure if I understood that note correctly*). 
+They also had limitations around using the DOM,
+typing (which is a cornerstone of Dart),
+and expanding to new interop types
+(*this is me trying to refer to wasm without actually saying, idk if "interop types" is the right term*). 
+
+Static interop addresses all of the shortcomings of Dart's previous JS interop solutions.
+Check out the [Features](#features) section for a summary of improvements. 
+
+[previous iterations of JS interop]: /web/js-interop/past-js-interop
 
 ## Usage
 
@@ -96,24 +104,22 @@ For tutorials and help:
 * [How to interop with DOM APIs][]
 * [How to interop with JavaScript libraries and apps][]
 * [How to test and mock JavaScript interop in Dart][]
-* [JS interop FAQ & troubleshooting][]
 
 For additonal types of documentation on `js_interop`:
   * [pub.dev site page][]
   * [API reference][]
 
 For information on other iterations of JS interop in Dart:
-  * [Previous offerings/comparison page][]
-  * [migrating from old to new][]
+  * [`dart:js_util`][]
+  * [Past JS interop][]
 
 
 [inline classes]: /
 [static interop reference]: /web/js-interop/reference
 [How to interop with DOM APIs]: /web/js-interop/dom
 [How to interop with JavaScript libraries and apps]: /web/js-interop/js-app
 [How to test and mock JavaScript interop in Dart]: /web/js-interop/test-and-mock
-[JS interop FAQ & troubleshooting]: /web/js-interop/faq-troubleshooting
 [pub.dev site page]: /
 [API reference]: /
-[Previous offerings/comparison page]: /web/js-interop/past-js-interop
-[migrating from old to new]: /web/js-interop/migration
+[`dart:js_util`]: /web/js-interop/js-util
+[Past JS interop]: /web/js-interop/past-js-interop

src/web/js-interop/js-app.md

@@ -1,4 +1,38 @@
 ---
 title: How to interop with JavaScript libraries and apps
 description: 
----
+---
+
+{{site.why.learn}}
+  * How to...
+{{site.why.end}}
+
+// *Introdcution paragraphs*
+
+## Background concepts
+
+The following sections provide some extra background and information
+around the technologies and concepts used in the tutorial.
+To skip directly to the tutorial content,
+go to [Steps](#steps).
+
+### Topic/concept 1
+
+### Topic/concept..n
+
+## Steps
+
+### Prerequisites
+
+Before you begin, you'll need...
+* 
+
+### Actionable step 1
+
+Step subsections should be actionalble, like "Build...", "Retrieve...", "Configure...", etc.
+
+### Actionable step...n
+
+## What next?
+
+Point to other tutorials, reference, etc.

src/web/js-interop/past-js-interop.md

@@ -1,73 +1,23 @@
 ---
-title: Non-static JS interop
-description: Archive of previous JS interop offerings
+title: Past JS interop
+description: Archive of past JS interop implementations
 ---
 
 This page addresses previous iterations of JS interop for Dart:
-* `dart:js_util`
 * `package:js`
 * `dart:js`
 
 **We do not recommend using any JS interop solution other than [static interop][].**
 
-Each of these tools still exist and are usable. However, the static interop model
+Each of these tools still exist and are usable.
+However, the static interop model
 is more performant, provides more capabilities,
 and will continue to be supported and developed.
 If you are just starting out with JS interop in Dart,
 please start with the static interop library, [`js_interop`][].
-If you have existing JS interop code implementing one of these tools,
-please [refactor your code][] to use the static interop model.
 
 [static interop]: /web/js-interop
 [`js_interop`]: {{site.dart-api}}/js_interop
-[refactor your code]: /web/js-interop/migration
-
-## `dart:js_util`
-
-[**`dart:js_util` API docs**][]
-
-**We will continue to support `dart:js_util` alongside static interop.**
-
-The `dart:js_util` library, or just `js_util`, is a low-level utility library
-for performing JS interop. Because `js_util` is so low-level,
-it could potentially be able to provide more flexibility than static interop,
-for example, in rare edge cases where `js_interop` is not expressive enough.
-This is an exception to the rule;
-**please always use static, inline-class based interop by default**.
-
-The `js_util` library is supported by the JS and `dart2wasm` backends.
-It is slower and less ergonomic than `js_interop`.
-
-The best example of the difference in ergonomics between `js_interop` and
-`js_util` is calling equivalent [`external`][] methods. 
-Each interop solution generates JavaScript code upon calling an `external` method:
-
-```dart
-// js_util external call:
-...
-
-// javascript generated:
-...
-```
-
-The JavaScript code `external` generates for `js_util` is very verbose,
-compared to the efficient, compact generation for `js_interop`:
-
-```dart
-// js_interop external call:
-...
-
-// javascript generated:
-...
-```
-
-For optimal JS interop, only use `js_util` over static interop if you encounter
-a use case that `js_interop` cannot address
-(and please [let us know][] if you encounter such a use case).
-
-[**`dart:js_util` API docs**]: {{site.dart-api}}/dart-js_util/dart-js_util-library.html
-[`external`]: /web/js-interop/reference#external
-[let us know]: https://github.com/dart-lang/sdk/issues/new?assignees=&labels=web-js-interop&template=1_issue_template.md&title=Create+an+issue
 
 ## `package:js`
 

src/web/js-interop/reference.md

@@ -1,6 +1,6 @@
 ---
-title: Static interop reference
-description: A glossary of key terms and concepts in JS interop and static interop.
+title: JS interop reference
+description: A glossary of key terms and concepts in JS interop.
 ---
 
 ## Members
@@ -120,9 +120,12 @@ Just write an extension and add members.
 
 ### `@JS`
 
-The `@JS` annotation indicates any kind of JavaScript interop. It provides the bindings
-between a JavaScript API and your Dart API. The use of `@JS` interop, combined with
-[inline classes](#inline-classes), is what makes static interop possible. 
+The `@JS` annotation belongs to the `dart:js_interop` library.
+It specifies that you're using JavaScript interop,
+as opposed to any other kind of interop.
+It provides the bindings between a JavaScript API and your Dart API.
+The use of `@JS` interop, combined with [inline classes](#inline-classes),
+is what makes static interop possible. 
 
 #### Usage:
 
@@ -134,6 +137,11 @@ between a JavaScript API and your Dart API. The use of `@JS` interop, combined w
 // specify `external` declaration is JS
 ```
 
+The `@JS` annotation was also a member of one of Dart's past JS interop solutions,
+`package:js`. You can read more about that on the [Past JS interop][] page.
+
+[Past JS interop]: /web/js-interop/past-js-interop
+
 ### `@staticInterop`
 
 The `@staticInterop` annotation of `package:js` was an intermeditate static interop
@@ -150,9 +158,5 @@ Inline classes and the `@JS` annotations replace the functionality of `@staticIn
 ...
 ```
 
-### others?
-
-// *anything that can still be used with static interop should be added here,*
-*but if they're not going to be used anymore let's keep that all on the "Past" page*
 
 

src/web/js-interop/test-and-mock.md

@@ -2,3 +2,44 @@
 title: How to test and mock JavaScript interop in Dart
 description: 
 ---
+
+{{site.why.learn}}
+  * How to...
+{{site.why.end}}
+
+// *Introdcution paragraphs*
+
+## Background concepts
+
+The following sections provide some extra background and information
+around the technologies and concepts used in the tutorial.
+To skip directly to the tutorial content,
+go to [Steps](#steps).
+
+### Topic/concept 1
+
+### Topic/concept..n
+
+## Export steps
+
+// *make sure to link to this content: https://pub.dev/packages/js/versions/0.6.6#jsexport-and-js_utilcreatedartexport*
+
+### Actionable step 1
+
+Step subsections should be actionalble, like "Build...", "Retrieve...", "Configure...", etc.
+
+### Actionable step...n
+
+## Test/mock steps 
+
+// *make sure to link to this content: https://pub.dev/packages/js/versions/0.6.6#js_utilcreatestaticinteropmock
+
+### Actionable step 1
+
+...
+
+### Actionable step...n
+
+## What next?
+
+Point to other tutorials, reference, etc.