Clearly define future-proof JS-interop

[kevmoo]

Update: all js interop is tracked in #49353 and https://github.com/orgs/dart-lang/projects/65/views/1

---

Working with @srujzs on this. Some combination of SDK constraint, pkg:js version, and @staticInterop

See also

• proposal: legacy_js_interop linter#3892
• Add --warn-on-legacy-js-interop flag to JS compilers (dart2js & DDC) #50665
• [Eval] Update to @staticInterop docs site-www#4331
• [2.19] Document future-proof JS-interop site-www#4450
• Migrate all web (js) libraries to use pkg:web and dart:js_interop firebase/flutterfire#10118
• ☂️ Migrate all (web) plugins/packages to use package:web (instead of dart:html) flutter/flutter#117022

[srujzs]

Below are the set of features we expect to work across both the JS and Wasm compilers for JS interop. Inline classes will be in this list, but they don't exist yet. :)

Disclaimer: The following should work, but none of this necessarily works performantly on dart2wasm. In fact, it's quite slow today. That's a longer-term project involving JS types that will need further work and significant user migration.

Dart SDK Constraint: >= 2.19
package:js constraint >= 0.6.6

• Subset of package:js
  • @staticInterop interfaces
    • External factory constructors with and without @anonymous
    • External static class members
    • External non-static extension members on a @staticInterop class (fields, getters, setters, methods)
    • Non-external extension members on a @staticInterop class
  • Top-level external members
  • @JSExport to do mocking and exports
• Subset of dart:js_util (these are just the current ones that work, we may add more before Dart 3 for dart2wasm)
  • jsify
  • dartify
  • getProperty
  • hasProperty
  • setProperty
  • callMethod
  • callConstructor
  • instanceof
  • promiseToFuture
  • globalThis
  • newObject
  • createStaticInteropMock
  • createDartExport
  • allowInterop

[kevmoo]

Awesome, @srujzs – thanks!

RE package:js – are we going to publish 0.6.6 along with Dart 2.19?

[parlough]

We don't really have any JS interop docs on dart.dev right now, but would it be worth 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?

\cc @MaryaBelanger

[kevmoo]

We should absolutely create a tracking issue in https://github.com/dart-lang/site-www/ and put it in my list at the top, @parlough

I don't think this is super urgent to get landed the day 2.19 launches – but early-ish in 2023 would be great.

I swear I chatted with @atsansone about this, too – but maybe not.

[parlough]

We have a tracking issue for general @staticInterop docs: dart-lang/site-www#4331

I've created a new issue to track the possibility of documenting the defined "future-proof" JS-interop outlined here: dart-lang/site-www#4450

[eernstg]

Inline classes will be in this list, but they don't exist yet. :)

They can exist now: https://github.com/dart-lang/language/blob/master/accepted/future-releases/inline-classes/feature-specification.md.

[srujzs]

RE package:js – are we going to publish 0.6.6 along with Dart 2.19?

Yeah, I think we should. Mocking is useful - I'll plan on publishing today.

Re: documentation - In the tracking issue, we originally thought of having a polished syntax for @staticInterop for Dart 3, but it's looking very likely we can get interop with inline classes out instead, making that unneeded.

As for whether it's worth documenting future-proof interop, I think it's worth it, with a disclaimer that this is really meant for people eagerly interested in making dart2wasm work, and we'll codify better syntax in Dart 3.

[srujzs]

I think this is resolved. There is some other stuff that was proposed for this but we haven't done, and we might not do for the context of this bug. @kevmoo , any objections?

[sigmundch]

sgtm, I was about to ask too. Based on @itsjustkevin proposal this week for improving our tracking, seems like we could move any remaining work to individual tasks in our project page, and potentially use a different issue for all future discussions of the feature. Do we have the canonical bug for that yet?

[srujzs]

We have the project here: https://github.com/orgs/dart-lang/projects/65, but I don't think we have a bug to keep track of all future discussions on next-gen interop. I think you had one that labeled work for Dart 3 (before we decided to add JS types), but I can't seem to find it. We could repurpose/update that.

[itsjustkevin]

sgtm, I was about to ask too. Based on @itsjustkevin proposal this week for improving our tracking, seems like we could move any remaining work to individual tasks in our project page, and potentially use a different issue for all future discussions of the feature. Do we have the canonical bug for that yet?

I created #52684 last month based on some prior conversation we had. Could this be used as the discussion issue?

[ditman]

This doc page was very handy responding to a customer, and I had no idea it existed. 🙏

[sigmundch]

... I created #52684 last month based on some prior conversation we had. Could this be used as the discussion issue?

I fear that issue may be more for inline classes and not necessarily the right place for interop related discussions.

Searching for previous issues we have used for this purpose, I came across this other issue:
#49353

Seems like potentially a good candidate (and looks like we'll want to transfer all of the subissues to our project too)

[sigmundch]

I'm going to go ahead and close this issue in favor of #49353