New JS interop docs #4578

MaryaBelanger · 2023-02-06T20:15:37Z

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 · 2023-02-07T19:25:51Z

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!

srujzs · 2023-02-08T17:52:41Z

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 · 2023-02-08T18:01:23Z

@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 · 2023-02-08T23:19:59Z

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 · 2023-02-10T01:29:54Z

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:

https://dart.dev/tutorials/web/low-level-html/add-elements

https://dart.dev/tutorials/web/low-level-html/remove-elements

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

MaryaBelanger · 2023-02-13T19:29:42Z

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 · 2023-02-14T01:07:06Z

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.

src/web/js-interop/reference.md

src/web/js-interop/index.md

remove broken link add tutorial outline restructure new pages left out of last commit

dart-github-bot · 2024-01-10T22:11:44Z

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

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

parlough · 2024-02-11T23:00:46Z

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!

Also addresses some review comments and removes old pages that are irrelevant now.

Needed for the site index for now.

MaryaBelanger · 2024-02-14T16:19:06Z

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 · 2024-02-14T22:33:50Z

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

Also cleans up some TODOs.

srujzs · 2024-02-15T01:54:20Z

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.

Co-authored-by: Parker Lougheed <[email protected]> Co-authored-by: Srujan Gaddam <[email protected]> Co-authored-by: sigmundch <[email protected]>

Changes have been addressed

…st documentation

parlough · 2024-02-15T18:50:30Z

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.

Fixes dart-lang#5438 --------- Co-authored-by: Srujan Gaddam <[email protected]> Co-authored-by: Parker Lougheed <[email protected]> Co-authored-by: sigmundch <[email protected]>

MaryaBelanger linked an issue Feb 6, 2023 that may be closed by this pull request

[Eval] Update to @staticInterop docs #4331

Closed

MaryaBelanger assigned MaryaBelanger and srujzs and unassigned MaryaBelanger Feb 7, 2023

atsansone added the st.WIP Issue in progress label Sep 1, 2023

MaryaBelanger changed the title ~~New static interop docs~~ New JS interop docs Nov 16, 2023

MaryaBelanger mentioned this pull request Nov 16, 2023

Update next-generation JS interop discussion #5285

Closed

MaryaBelanger commented Nov 20, 2023

View reviewed changes

src/web/js-interop/reference.md Outdated Show resolved Hide resolved

MaryaBelanger commented Nov 20, 2023

View reviewed changes

src/web/js-interop/reference.md Outdated Show resolved Hide resolved

MaryaBelanger commented Nov 20, 2023

View reviewed changes

src/web/js-interop/reference.md Outdated Show resolved Hide resolved

MaryaBelanger commented Nov 20, 2023

View reviewed changes

src/web/js-interop/index.md Outdated Show resolved Hide resolved

MaryaBelanger mentioned this pull request Jan 9, 2024

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

Closed

8 tasks

MaryaBelanger changed the base branch from v3.0 to main January 10, 2024 18:23

outline and first drafts for some pages

b6ddf73

remove broken link add tutorial outline restructure new pages left out of last commit

MaryaBelanger force-pushed the js-interop branch from 6e989f3 to b6ddf73 Compare January 10, 2024 18:48

add descriptions to fix liquid errors

c6c417c

MaryaBelanger and others added 6 commits January 10, 2024 16:51

readd sidenav after rebase, move files under interop

2d7c606

update web/js-interop links to interop/js-interop

bc2347e

remove broken anchors

7e629dd

typo in link

902703b

Add a section for JS types and reference it in the nav

3ce781f

Merge branch 'main' into js-interop

0fe4c69

Merge branch 'main' into js-interop

fe2ad47

srujzs added 6 commits February 12, 2024 14:21

Update index, overview, and mocking tutorial

1b3ca1c

Also addresses some review comments and removes old pages that are irrelevant now.

Add back dom.md

ab0fc8d

Needed for the site index for now.

Fix links in sections

95a885a

Fix links to restrictions

ee822fd

Added missing hyphen in link to restrictions in JS types section

51ab02f

Cleanup wording to be clearer

83a613f

Link to extension types sections

1510117

Also cleans up some TODOs.

parlough and others added 2 commits February 15, 2024 09:53

Merge branch 'main' into js-interop

d000a22

package:web migration page (#5524)

3f52a4b

Co-authored-by: Parker Lougheed <[email protected]> Co-authored-by: Srujan Gaddam <[email protected]> Co-authored-by: sigmundch <[email protected]>

MaryaBelanger marked this pull request as ready for review February 15, 2024 16:12

MaryaBelanger and others added 4 commits February 15, 2024 08:22

fix some broken links, hide why section in index

481f0e7

Merge branch 'main' into js-interop

4402946

go link, fix index api links, remove old learn directive

01c64bc

more minor link fixes

efb81a2

srujzs approved these changes Feb 15, 2024

View reviewed changes

srujzs and others added 4 commits February 15, 2024 09:02

Move dart:js_interop and dart:js_interop_unsafe links to dev for late…

202b626

…st documentation

Small fixes to code snippets and external functions link

33f8d05

minor fixes

7e1eb3f

Merge branch 'main' into js-interop

9dadda6

parlough removed the st.WIP Issue in progress label Feb 15, 2024

MaryaBelanger merged commit 4a2fd1b into main Feb 15, 2024
8 checks passed

kevmoo deleted the js-interop branch August 20, 2024 22:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New JS interop docs #4578

New JS interop docs #4578

MaryaBelanger commented Feb 6, 2023 •

edited

Loading

MaryaBelanger commented Feb 7, 2023

srujzs commented Feb 8, 2023

MaryaBelanger commented Feb 8, 2023

MaryaBelanger commented Feb 8, 2023

srujzs commented Feb 10, 2023

MaryaBelanger commented Feb 13, 2023

srujzs commented Feb 14, 2023

dart-github-bot commented Jan 10, 2024 •

edited

Loading

parlough commented Feb 11, 2024

MaryaBelanger commented Feb 14, 2024 •

edited

Loading

MaryaBelanger commented Feb 14, 2024

srujzs commented Feb 15, 2024 •

edited

Loading

parlough commented Feb 15, 2024 •

edited

Loading

New JS interop docs #4578

New JS interop docs #4578

Conversation

MaryaBelanger commented Feb 6, 2023 • edited Loading

MaryaBelanger commented Feb 7, 2023

srujzs commented Feb 8, 2023

MaryaBelanger commented Feb 8, 2023

MaryaBelanger commented Feb 8, 2023

srujzs commented Feb 10, 2023

MaryaBelanger commented Feb 13, 2023

srujzs commented Feb 14, 2023

dart-github-bot commented Jan 10, 2024 • edited Loading

parlough commented Feb 11, 2024

MaryaBelanger commented Feb 14, 2024 • edited Loading

MaryaBelanger commented Feb 14, 2024

srujzs commented Feb 15, 2024 • edited Loading

parlough commented Feb 15, 2024 • edited Loading

MaryaBelanger commented Feb 6, 2023 •

edited

Loading

dart-github-bot commented Jan 10, 2024 •

edited

Loading

MaryaBelanger commented Feb 14, 2024 •

edited

Loading

srujzs commented Feb 15, 2024 •

edited

Loading

parlough commented Feb 15, 2024 •

edited

Loading