Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

JS/Web interop follow up #5721

Open
MaryaBelanger opened this issue Apr 15, 2024 · 9 comments
Open

JS/Web interop follow up #5721

MaryaBelanger opened this issue Apr 15, 2024 · 9 comments
Assignees
Labels
dev.io Relates to feature developments for IO e3-weeks Complete in < 4 weeks of normal, not dedicated, work meta.umbrella Collects multiple related issues p1-high Major but not urgent concern: Resolve in months. Update each month. st.triage.ltw Indicates Lead Tech Writer has triaged

Comments

@MaryaBelanger
Copy link
Contributor

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:

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
@MaryaBelanger MaryaBelanger added the dev.io Relates to feature developments for IO label Apr 15, 2024
@MaryaBelanger MaryaBelanger self-assigned this Apr 15, 2024
@projektorius96
Copy link

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
Copy link

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
Copy link
Contributor Author

MaryaBelanger commented Apr 17, 2024

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
Copy link

projektorius96 commented Apr 17, 2024

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

@atsansone atsansone added p1-high Major but not urgent concern: Resolve in months. Update each month. e3-weeks Complete in < 4 weeks of normal, not dedicated, work meta.umbrella Collects multiple related issues st.triage.ltw Indicates Lead Tech Writer has triaged labels Apr 18, 2024
@projektorius96
Copy link

projektorius96 commented May 19, 2024

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 !

@MaryaBelanger
Copy link
Contributor Author

Hey @projektorius96! The changes referenced in the blog post are all listed in the changelog here. They're mostly incremental improvements for known issues, so nothing big to cover, just that we're making it a little better all the time!

@projektorius96
Copy link

projektorius96 commented May 21, 2024

Hey @projektorius96! The changes referenced in the blog post are all listed in the changelog here. They're mostly incremental improvements for known issues, so nothing big to cover, just that we're making it a little better all the time!

What are about the docs themselves, anything to share even though some work-in-progress tutorial ? Nearly two months passed since the request, I mean guys at least some beginner tutorial to catch the drift, I am not requesting a complete codelab. Afterall you got complete Flutter team, why when those guys do not do some Work in Progress timeline with incremental tutorials, similarly to how Manning reveals their work in progress.

It seems that in this world easier to do things by yourself, then wait for breadcrumbs. Really sad, yet not the first time Google lets people down.

@MaryaBelanger
Copy link
Contributor Author

@projektorius96 Ah I see, yes we have started work on addressing 2) described above, so a getting started tutorial on using JS interop in a new project/from scratch.

@projektorius96
Copy link

@projektorius96 Ah I see, yes we have started work on addressing 2) described above, so a getting started tutorial on using JS interop in a new project/from scratch.

Is any of the documentation planed to be published with Dart 3.5 ? Roughly another two months passed since last enquiry, just wanted to double check, see if any heads up could be given towards the process ?

Cheers !

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
dev.io Relates to feature developments for IO e3-weeks Complete in < 4 weeks of normal, not dedicated, work meta.umbrella Collects multiple related issues p1-high Major but not urgent concern: Resolve in months. Update each month. st.triage.ltw Indicates Lead Tech Writer has triaged
Projects
None yet
Development

No branches or pull requests

4 participants