JS/Web interop follow up

[MaryaBelanger]

A few things to improve the recently added JS interop docs based on feedback

1) Conceptual overview of the two new layers

Request: from @mit-mit

...more high-level conceptual information on the Overview page, especially around explaining each of the two new layers (package:web and dart:js_interop) in an overview fashion

Where: https://dart.dev/interop/js-interop

2) Getting started walkthrough / tutorial

Request: #5674

...More beginner friendly step by step examples

Where: https://dart.dev/interop/js-interop/tutorials (getting-started)

Notes:

• NOT migration-centric, but starting from scratch.
  • Getting more asks for just getting started with JS interop vs just migration help (3)
• Replace the current/old web getting started page
  • Start by just translating to package:web
  • Highlight important package:web stuff
    • Might require the doc to be significantly expanded on, not just updated.
  • Include how to run and debug with webdev, connect with devtools
• Next (another doc, probably), "now we have this js library that we want to use in our web app..."
  • Use new JS interop to incopoprate JS APIs
  • How to use JS types, or external APIs that use JS types
• Call out differences between JS and Wasm throughout the doc for certain things like casting and stuff
  • Incorporate numbers somehow, show how Wasm and JS use numbers differently
• Note at the end "try this out with experimental Wasm"
  • (will have to do their own hookups)

Related:

• Rewrite dart:html library page for package:web #5525

3) Expanded migration guidance

Request: dart-lang/sdk#55352

...concrete side by side examples of old vs new

Where: https://dart.dev/interop/js-interop/tutorials (migration)

Notes:

For existing Dart package maintainers, expanding on examples and references is more useful than tutorial-style content.

• Walkthrough of a package migration
  • "Migrating to Wasm" angle (which is just js interop and package:web migration)
• Cover holistic pov: tooling, workflow changes, tests, "everything"
• Focus on 1:1 migration code examples for specific changes in JS types, areas most problematic for users
• Crafted examples with numbers changes, other semantics differences sprinkled in (Lean heavily on existing jsinterop docs for reference)
  • Target more common use cases (rather than trying to base it on a real example).
• Nice to have: a list of real migration examples, with different types of migrations/migrations that cover different things

[projektorius96]

It's really nice to see the iceberg has finally moved. Way to go ♥

As a JavaScript to Dart developer I'd love to see more beginner friendly examples, especially the ones oriented towards HTML Canvas API using package:web/web.dart, actually I have just tried to ask Gemini for help making a starter template (entry-point) that I subsequently have tried to compile using dart compile js <entry-point>, yet the compiling stage itself has failed, perhaps due to inconsistencies provided for my metaphorical <entry-point> by the Gemini AI : the AI is aware of newest Dart VM as well as dart:js_interop, so keeping in mind I could not glue up things with a AI help, the docs is the only source-of-true to make it happen otherwise. Looking forward to see some updates, hopefully soon !

[bivens-dev]

This may not be the right place too but wanted to call out I found it very difficult how to handle working with things like WebWorkers in the new package and pass messages back and forth.

[MaryaBelanger]

This is the right place to call out things you'd like to see documented, or things you wish had been documented (even if you've already moved on or figured it out). Thank you both @bivens-dev and @projektorius96!

[projektorius96]

Just to recap, I guess when it comes about HTML specification and beyond most of developers peoples , layman like me, would love to see more of easy-to-grasp "from scratch" examples for the following:

• A boilerplate for Web Component, how to set up, register and instantiate;
• A boilerplate for HTML Canvas or SVG, again how to set up, register and instantiate for each specification respectively;

To follow up, more beginner friendly boilerplates working with Web APIs, just to name a few IndexedDB for in-browser state management, simple Web Workers setup as per @bivens-dev remark or even communication examples, as per issue etc.

Cheers !

P.S. Sorry for repeating myself again and again, just cannot wait for changes coming, really excited and appreciate the feedback Dart communitive give us ! To name a few @MaryaBelanger, @parlough

[projektorius96]

Hi, just curious, what's the current status of dart:js_interop ? Is it work in progress at all ? I've just stumbled upon @mit-mit blog post on Medium for Dart 3.4 that also mentions improvements made on the dart:js_interop, perhaps source code itself, and not the docs.

Cheers !