[2.19] Document future-proof JS-interop

[parlough]

What information is missing?

JS interop is currently evolving, partially to prepare for dart2wasm. It looks like there is a subset and suggested set of functionality to prepare for the future state of JS-interop and support all three web compilers.

While we don't really have any JS-interop docs, we should consider documenting what is "future-proof" to best prepare for the future.

Context: dart-lang/sdk#50721 has some more context and a list of things that currently work.

Related: #4331

[MaryaBelanger]

Thanks for mapping all this out @parlough !

I'm taking these comments from the sdk issue as kind of the summary of the work that needs to be done here:

....mentioning (alongside 2.19) in JS Interop that Dart's JS interop story is currently evolving and to stick to this set of functionality to help ease the transition

....a disclaimer that this is really meant for people eagerly interested in making dart2wasm work, and we'll codify better syntax in Dart 3.

I'm imagining adding a "Future proof" section to the JavaScript Interoperability page, something like:

JS interop is undergoing preparations for future major Dart versions and features.
(maybe specify dart2wasm)
(maybe some of the "this is better because..." content from the spec)
To get a head start, you can...
(maybe two subsections for @JSExport and @staticinterop)

Questions: (@parlough, @srujzs, maybe @kevmoo, whoever)

1. What action can they take exactly? Is it along the lines of "implement these features" / "refactor your code like this" / "configure these options" / etc.?

2. By "stick to this set of functionality", are we're talking about the list in this comment?

• Is it sufficient to just put that list on the page?
• Is it worth it to define / explain each one?
• Should it be more practical? We could provide examples for each, like how-you're-doing-it-now >> how-to-update?

3. Could I just paraphrase the spec for each?

[srujzs]

I think a future-proof section could be fairly minimal for now, as it's really intended for the subset of people who are really interested in integrating with dart2wasm before inline classes/Dart 3 comes around.

1. Mostly refactoring their code to conform to the new syntax and semantics of @staticInterop. "If you're interested in interop that will work with dart2wasm when Dart 3 is released, you can try out static interop. Currently, this is implemented using package:js' @staticInterop. When Dart 3 is released, static interop will be supported with inline classes." This also means using the latest package:js version.
2. Yes, essentially. For the package:js stuff, I think it's worth briefly just mentioning the individual types of members. For the js_util stuff, I think just mentioning the library is sufficient and then pointing to that list for more specifics if people want. When we're documenting for Dart 3, we can perhaps offer a @staticInterop-way and an inline class-way when we have all the pieces for that. For the future-proof interop, I think it makes sense to just focus on what parts people can use. For the Dart 3 interop documentation, we can go in-depth on how they can use them to accomplish what they want.
3. Sure! I'm happy to work with you on this too if you have questions on it.