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

New JS interop docs #4578

Merged
merged 35 commits into from
Feb 15, 2024
Merged

New JS interop docs #4578

merged 35 commits into from
Feb 15, 2024

Conversation

MaryaBelanger
Copy link
Contributor

@MaryaBelanger MaryaBelanger commented Feb 6, 2023

Fixes #5438

WIP (lots of notes interspersed on the pages)

Adds new pages and content to cover static, inline-class based, JS interop.

Staged: https://dart-dev--pr4578-js-interop-jct9fv7o.web.app/interop/js-interop

New pages:

  • JavaScript interoperability (Overview) (web/js-interop)
  • JS Interop Reference (web/js-interop/reference)
  • How to interop with DOM APIs (web/js-interop/dom)
  • How to interop with JavaScript libraries and apps (web/js-interop/js-app)
  • How to test and mock JavaScript interop in Dart (web/js-interop/test-and-mock)
  • Non-static JS interop (web/js-interop/past-js-interop)
  • Migration (web/js-interop/migration)
  • FAQ / Troubleshooting (web/js-interop/faq-troubleshooting)

@MaryaBelanger MaryaBelanger linked an issue Feb 6, 2023 that may be closed by this pull request
@MaryaBelanger
Copy link
Contributor Author

commit 9895fb6 :

  • Remove migration and troubleshooting pages
  • Remove “Others” section from annotations reference
  • Remove mentions of static interop from any titles
  • Write “why static interop” notes into actual paragraph
  • Add meeting notes to all tutorials
    • didn't end up doing this, didn't really have enough good info to elaborate in any useful way
  • Separate dart:js_util to its own page
  • Create a top level tutorials page, manually link individual tutorials on the page with a summary for each
    • Doesnt need to expand in the left nav
  • Change “non-static” page to just “past” or “other”, etc
  • Elaborate on @js reference that it was also a part of the old package:js library, link to the “old” page

@srujzs That was the last of my input, you can take this over any time now! Let me know if you need anything else.
Good idea about the tutorials, btw, this looks much better!
image

@srujzs
Copy link
Contributor

srujzs commented Feb 8, 2023

Nice, thanks for the help! Just a quick question when I iterate in the future: is there a way to see the web page after uploading a new commit? I tried the previous links but I don't think they use the newer commits.

@MaryaBelanger
Copy link
Contributor Author

@srujzs Normally it's supposed to generate a few minutes after a commit and pop up on its own, but I think because the build / stage check is not passing, it's not doing it. I tried to fix the link issues it's pointing to... not sure why they're still popping up...

Anyways to generate the shareable staging link yourself, follow these steps https://github.com/dart-lang/site-www#deploying-to-a-staging-site . It's what I always do when my builds failing for whatever reason. The only out-of-terminal part is creating a project in the firebase console site, after that you can keep reusing the same project every time you want to restage.

I think @parlough is out for a little while, but when he's back he might have better advice.

@MaryaBelanger
Copy link
Contributor Author

Fyi: I just came across these two DOM tutorials, pretty sure they're not related to this work but just in case check them out:

@srujzs
Copy link
Contributor

srujzs commented Feb 10, 2023

Fyi: I just came across these two DOM tutorials, pretty sure they're not related to this work but just in case check them out:

Oooh, I either forgot or didn't know these existed. These are good candidates for a tutorial using interop instead of dart:html.

@MaryaBelanger
Copy link
Contributor Author

These are good candidates for a tutorial using interop instead of dart:html

@srujzs Great, if you end up deciding to rewrite those pages themselves (I guess if their contents are no longer relevant with static interop, or if they're just not practices we want to promote anymore), or if you just create new pages. Just so I can move/remove the old ones (this can be decided at the very end so rush)

@sigmundch re: this comment.
I think starting to populate a FAQ now is a good idea.

This makes me wonder, though, should these docs come out with the .0 release or the .1 release? I assumed that we wouldn't release these docs until static interop comes out (.1), but if users are already using and getting errors maybe we can just publish this stuff as soon as its ready, and just note on every page, maybe with a banner, that this is not in stable yet?

@srujzs
Copy link
Contributor

srujzs commented Feb 14, 2023

The content is still relevant in those pages as it's modifying the DOM in a simple, core way. We'd likely want to rewrite that using package:web in the future. This is further in the future though, as we'd want the pieces to all be ready before we make package:web the goto place for interacting with the browser/DOM instead of dart:html.

Re: versioning, agreed we want both. We can make the docs reflect the current status when it's time to release 3.0, and once issues have been resolved and we're ready for a more stable release, we can edit them then.

The above issues is relevant to JS interop in general so I don't think versioning there matters much. We can add a FAQ section for stuff like that whenever since the issue already exists.

@atsansone atsansone added the st.WIP Issue in progress label Sep 1, 2023
@MaryaBelanger MaryaBelanger changed the title New static interop docs New JS interop docs Nov 16, 2023
remove broken link

add tutorial outline

restructure

new pages left out of last commit
@dart-github-bot
Copy link
Collaborator

dart-github-bot commented Jan 10, 2024

Visit the preview URL for this PR (updated for commit 9dadda6):

https://dart-dev--pr4578-js-interop-jct9fv7o.web.app

@parlough
Copy link
Member

Note I merged main which had significant changes into this PR and updated syntax usage where necessary. Let me know if you have any issues!

@MaryaBelanger
Copy link
Contributor Author

MaryaBelanger commented Feb 14, 2024

TODO

  • change firebase.json go/next-gen-interop to point to the main index/overview page
  • delete or hide the pages that won't be used for this release
    • my bad, looks like this one is already taken care of!

Fyi @srujzs I'm sure you're in the middle of some commits so you can throw these in if you want, or I can take care of it after you land your next commit/whenever your done. Just lmk!

Edit: the go link is here: https://github.com/dart-lang/site-www/blob/main/firebase.json#L175
change:

-      { "source": "/go/next-gen-js-interop", "destination": "/interop/js-interop#next-generation-js-interop-preview", "type": 301 },
+      { "source": "/go/next-gen-js-interop", "destination": "/interop/js-interop", "type": 301 },

@MaryaBelanger
Copy link
Contributor Author

The extension types page is merged, so you can uncomment any links to /language/extension-types

Also cleans up some TODOs.
@srujzs
Copy link
Contributor

srujzs commented Feb 15, 2024

The extension types page is merged, so you can uncomment any links to /language/extension-types

Done! The failure in links is expected because we link to package-web.md which won't exist until #5524 is landed.

We also should remove dom.md and change the index once that PR is landed.

parlough and others added 2 commits February 15, 2024 09:53
Co-authored-by: Parker Lougheed <[email protected]>
Co-authored-by: Srujan Gaddam <[email protected]>
Co-authored-by: sigmundch <[email protected]>
@MaryaBelanger MaryaBelanger marked this pull request as ready for review February 15, 2024 16:12
@MaryaBelanger MaryaBelanger dismissed kevmoo’s stale review February 15, 2024 16:12

Changes have been addressed

@parlough parlough removed the st.WIP Issue in progress label Feb 15, 2024
@MaryaBelanger MaryaBelanger merged commit 4a2fd1b into main Feb 15, 2024
8 checks passed
@parlough
Copy link
Member

parlough commented Feb 15, 2024

Congrats to you both on landing this and thanks so much for working on it! It's super exciting, and more + better JS-interop documentation than we've ever had. Developers will appreciate and benefit greatly from it!

Sorry I haven't been able to give it too close of a look yet, but I promise I will.

atsansone pushed a commit to atsansone/site-www that referenced this pull request Mar 22, 2024
Fixes dart-lang#5438 
---------

Co-authored-by: Srujan Gaddam <[email protected]>
Co-authored-by: Parker Lougheed <[email protected]>
Co-authored-by: sigmundch <[email protected]>
@kevmoo kevmoo deleted the js-interop branch August 20, 2024 22:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: Done
Development

Successfully merging this pull request may close these issues.

☂️ JS/web static interop overview, docs, and tutorials [Eval] Update to @staticInterop docs
8 participants