☂️ JS/web static interop overview, docs, and tutorials

[parlough]

This issue outlines the doc plan for new Dart web interop features in 3.3. The outline that follows is authored by Marya, not Parker :)

JS interop

Static JS interop is a new design for consuming JavaScript APIs in Dart that uses a combination of extension types, external members, annotations (like @JS), JS types, and conversions.

Evaluation

This will be added as a new drop-down "JS interop" category under "Interoperability" in the sidenav, and be found at /interop/js/....

• Overview

  • What is static interop / when to use it
  • Features / benefits
    • zero-cost wrapping
    • stronger typing
    • mixing external and non-external members
    • interop with DOM types
    • compatibility with Wasm
    • @JS renaming
    • Limitations:
      • Static, so runtime mechanisms won’t work
      • No virtual dispatch
      • is and as don’t work as expected
        • (this should be covered in extension types docs, maybe just point there)
  • How it interacts with JS
  • Implications for different web backends (including dart2wasm)
  • Differences with the old dart: and package: libraries
    • Existing libraries <> New static interop libraries table

• Syntax / usage

  • Quick usage code example
    • Example covers the following, text explains:
      • Annotations
        • Interfaces with @JS annotations OR top-level functions in the global context
      • external
        • External members are limited to primitives plus static interop types
        • Restricted types for external members and callbacks
  • Maybe covered in usage overview, maybe saved for more in depth coverage on JS types page (below):
    • Defining interop types with extension types
      • Representation type must be JS type or other interop types
      • Show how each external member transforms to their JS equivalent
      • Named arg factories for object literal creation
    • Conversion functions
      • toDart and toJS
      • Go between the Dart type and the JS type

• JS Types page

  • Why we need them
  • The type hierarchy + ties to JS type hierarchy
  • Dart types to JS types (table?)
    • Primitive types
    • List
    • Callbacks
    • JSAny
    • Compatibility, types representation between dart2wasm / dart2js
    • null vs undefined, and null-checks on an external member

• Tutorials

  • How to interop with the DOM/browser
    • see package:web section below
  • How to interop with JavaScript libraries and apps
    • nice-to-have
  • How to test and mock JavaScript interop in Dart
    • nice-to-have

• Past JS Interop page

  • package:js
    • annotations to enable writing external interfaces
    • non-@staticInterop types
    • @staticInterop types (still supported in dart:js_interop)
      • experimental annotation to enable extension type-like features
    • unsupported in dart2wasm 3.3 onwards
  • dart:js_util
    • utility functions that couldn’t be expressed with interfaces
    • everything in this library will now go in dart:js_interop and dart:js_interop_unsafe
    • unsupported in dart2wasm 3.3 onwards
  • dart:js
    • original iteration of JS interop, deprecated and soon to be removed

• FAQ/Troubleshooting page

Resources

• Cross links to extension type documentation are expected, so that is a soft prerequisite for this work. (☂️ [Extension type] Language feature docs #4177)
• Outline PR (old): New JS interop docs #4578
• Existing JS interop page: https://dart.dev/interop/js-interop

---

package:web

package:web is the web interop replacement for dart:html built around static JS interop.

Evaluation

This will likely be a page under "JS interop" in the side nav, under "Interoperability". Currently unsure whether the title should be "Web interop" , "package:web", a tutorial-like title e.g. "How to interop with the DOM/browser", or something else.

Since it's built with JS interop, much of the details of its use will be covered in JS interop pages like syntax, conversions, types, etc.

• Intro

  • What is package:web / Why you would use it
    • (Q: like, instead of js interop?)
    • More bare-bones with helpers to better interact with the web (?)
    • Not required (?)
    • Talk about Web IDL (?)
  • Why it's replacing dart:html (benefits/improvements)
    • dart2wasm can't support dart:html efficiently
    • dart:html did not fit the continuously changing reality of the web
    • extensibility and ease of understanding is low in dart:html

• How to use it / Syntax

  • "How to interop with the DOM / browser" (tutorial / usage / steps)
    • Conceptual replacement for removed low-level HTML tutorials (add-elements, remove-elements)
  • From a non-migration perspective, just using the tool
  • Generating DOM bindings: readme

• Migrating from dart:html to package:web

  • Explain limitations / migration complexity, future goal for migration helper tools
  • How to migrate (steps)
    • Rename migrations:
      • Change import: dart:html to import: package:web
      • "undefined" errors - that's what you have to migrate
      • Lookup new name: use IDE or search dart:html api docs to see original declaration's @Native annotation
        • 300-400 names unchanged
        • Possibly include table of changed and removed symbols (see issue in resources)
        • eventual dart fix
    • Other migrations:
      • don't use is, use interop instead like instanceOf
        • Type stuff will all be described in JS Types page, point to JS docs a lot
      • helpers mitigate a lot of other major changes
        • point users to helpers implementation / api docs to learn more
      • Zones: in evaluation
  • Renamed objects from dart:html to package:web
    • Could make a 1:1 table, but would be very large
    • Better to teach the skill of looking up and inferring types from dart:html @Native annotations

• Update go link to point to package:web migration instructions for library docs

  • (added in Add go link redirect for package:web #5460)

Resources

• package:web repo
• https://pub.dev/packages/web
  • helpers library
  • web classes library
• Table of dart:html > package:web renames (and possible dart fix: investigate dart fix renames for this package web#139

---

dart:html treatment

Once some of the above docs are place, documentation about the old mechanisms, especially dart:html need to be directed to new functionality with deprecation notices or be removed entirely.

• Old low-level HTML guides should be removed (57857f5)
• dart:html library tour content should be deprecated and set for removal
• All snippets using dart:html for non-web goals should move away from it
• Build a web app with Dart and Web libraries & packages should be updated or partially removed
• Web deployment should be verified as up to date
• Details on implement web specific behavior in packages, such as conditional imports, should move away from dart:html.
• All other mentions should be audited for replacement or removal

Mentions of dart:html on api.dart.dev are also going to be downgraded. The sidenav will be adjusted to include / emphasize package web: dart-lang/dartdoc#3617. ToDo for @MaryaBelanger:

• Downgrade / demphasize dart:html on api.dart.dev home page: https://api.dart.dev/stable/index.html
  • Edit markdown here: https://github.com/dart-lang/sdk/blob/main/sdk/api_readme.md

[navaronbracke]

@parlough Maybe another point that could be discussed: What with definitions of Web IDL types that have a specific format in the Dart representation?

Context: In dart-lang/web#151 there was a discussion about how end-users should treat MediaTrackSettings. The proper way to interface with this type is to first query the MediaTrackCapabilities, as the JS API tells you to do. But the Dart definition of MediaTrackSettings is the full union of the base type, the audio specific type and the video specific type. Because I didn't realise that last point, I went on to file that issue. Maybe we could clarify the docs for IDL types that are such full unions?

[parlough]

@parlough Maybe another point that could be discussed:

Thanks for the suggestion @navaronbracke. I don't have the full context here, so I'll defer to those working on the documentation for these features :)

@srujzs When you get a chance could you comment on if this fits into your current thinking or docs plan?

[srujzs]

But the Dart definition of MediaTrackSettings is the full union of the base type, the audio specific type and the video specific type.

Are you referring to MediaTrackSettings being exposed as multiple partial dictionaries that we then coalesce into a single interface? I think yes that's a good idea to comment on how we combine partial interfaces into one (although we may actually undo that in the future to make non-standard spec members more obvious) in the package:web docs, either in the website or in the readme.

In this case, though, I think the definition we get to begin with is already partially conflating the video specific type: https://github.com/w3c/webref/blob/75ad858d0877099792ad531040d3725221fa8d76/tr/idl/mediacapture-streams.idl#L106. For example, aspectRatio only applies to video but is in the general definition. Vice versa with autoGainControl.

[navaronbracke]

Are you referring to MediaTrackSettings being exposed as multiple partial dictionaries that we then coalesce into a single interface?

Exactly that yes

[navaronbracke]

Also, in the WIP PR docs, we still mention dart:js_util. In my opinion, we should not show that link. Only having a "Past Iterations of JS Interop" seems fine.

If people want to use the "unsafe" API's, they should use dart:js_interop_unsafe instead?

I found the existence of dart:js|dart:js_util / package:js hard to understand (the latter just exports the former etc) when I first started working with it,
hence why I would just not mention the old libraries directly on that page.

[parlough]

Also, in the WIP PR docs...

The linked PR still has a bunch of stale changes from in-progress work from a year ago, including that index page. It will be updated and cleaned up before landing, but until its out of a draft state, I would be cautious with taking much from the PR 😄

If people want to use the "unsafe" API's, they should use dart:js_interop_unsafe instead?

My understanding is yes, but prefer using dart:js_interop and your own static JS interop interfaces where possible. Then if you need to or if it helps with migration, you can fall back to using dart:js_interop_unsafe.

[srujzs]

Yup, Parker is right here. past-js-interop refers to the previous efforts, but we haven't updated the index/overview yet.