add more examples to package:web migration #7040

fsw · 2025-11-23T21:02:41Z

I think adding a few more examples and info will help with the migration process.

I’ve reviewed the contributor guide and applied the relevant portions to this PR.
This PR doesn't contain automatically generated corrections or text (Grammarly, LLMs, and similar).
This PR follows the Google Developer Documentation Style Guidelines — for example, it doesn't use i.e. or e.g., and it avoids I and we (first person).
This PR uses semantic line breaks of 80 characters or fewer.

google-cla · 2025-11-23T21:02:46Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

gemini-code-assist · 2025-11-23T21:02:56Z

Summary of Changes

Hello @fsw, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the package:web migration guide by incorporating several new examples and clarifications. The additions focus on common migration challenges related to DOM manipulation, including the handling of Element vs. HTMLElement, adapting list-like operations, and updating type checks. These updates aim to provide developers with more comprehensive and practical guidance, streamlining the transition process from dart:html to package:web.

Highlights

Element and HTMLElement Clarification: Added a new section detailing the distinction between Element and HTMLElement in package:web and demonstrating the necessary casting for querySelector results to access HTMLElement specific methods.
List Operations Migration: Provided guidance on migrating list-like operations such as querySelectorAll and children, introducing JSImmutableListWrapper for immutable use cases and a manual iteration example for mutable operations like removeWhere.
Common DOM Manipulation Examples: Included practical examples for migrating common DOM manipulation patterns, specifically for innerHtml, classes.add, and appendHtml.
Enhanced Type Test Migration: Expanded the type tests section with an additional example demonstrating how to migrate is InputElement checks to isA<HTMLInputElement>().
External Reference: Added an external reference link to MDN for the Element interface to provide further context.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request adds several useful examples for migrating from dart:html to package:web. The new sections on Element vs HTMLElement, list operations, common DOM manipulations, and type tests will be very helpful for developers. The examples are clear and cover common migration scenarios. I've found a small typo in one of the code examples and a potentially confusing link reference, for which I've left specific comments. Overall, this is a great addition to the documentation.

src/content/interop/js-interop/package-web.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

antfitch · 2025-11-25T00:21:03Z

/gcbrun

dart-github-bot · 2025-11-25T00:27:38Z

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

https://dart-dev--pr7040-fsw-patch-2-2ypygncd.web.app

kevmoo

I LOVE these additions @fsw

Let's wait for @srujzs to review before we land though.

Thanks much!

antfitch

Will review after our technical reviewers have finished first.

srujzs

Sorry for the delay, thanks!

src/content/interop/js-interop/package-web.md

srujzs · 2025-12-08T23:55:36Z

src/content/interop/js-interop/package-web.md

+```dart
+parent.children.removeWhere(test); // Remove
+
+for (var i = parent.children.length - 1; i >= 0; --i) {


Unrelated, but it might be beneficial for us (the package:web owners) to have a mutable list implementation to support things like this.

Yes, I was also thinking if it would be better to implement this instead of documenting. I will try to open a PR to package:web later and link this PR to update this example. In my code base I used an extension to fix this. I am not sure if any other method than removeWhere would be usable here though.

I will try to open a PR to package:web later

Sounds great, thank you!

if any other method than removeWhere would be usable here though.

On reflection, children was exposed as a List in dart:html but HTMLCollection is not a list-like, so we'd need something bespoke. An alternative is to have something specific for children instead. I'm also not sure if there are any examples of mutable list-likes in the browser to warrant a general mutable List implementation.

Indeed, it seems general implementation is not possible. I have worked out something like this
dart-lang/web#490 to work with children and childNodes.

src/content/interop/js-interop/package-web.md

srujzs · 2025-12-10T22:48:52Z

src/content/interop/js-interop/package-web.md

+```dart
+parent.children.removeWhere(test); // Remove
+
+for (var i = parent.children.length - 1; i >= 0; --i) {


I will try to open a PR to package:web later

Sounds great, thank you!

if any other method than removeWhere would be usable here though.

On reflection, children was exposed as a List in dart:html but HTMLCollection is not a list-like, so we'd need something bespoke. An alternative is to have something specific for children instead. I'm also not sure if there are any examples of mutable list-likes in the browser to warrant a general mutable List implementation.

src/content/interop/js-interop/package-web.md

add more examples to package:web migration

5d089ef

gemini-code-assist bot reviewed Nov 23, 2025

View reviewed changes

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

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

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

fsw and others added 2 commits November 23, 2025 22:08

Apply suggestions from code review

f24cd56

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

add some more examples for DOM manipulation

afbaa5d

antfitch requested review from antfitch and jwill November 25, 2025 00:27

antfitch requested review from kevmoo and removed request for jwill November 25, 2025 00:29

kevmoo approved these changes Nov 25, 2025

View reviewed changes

antfitch requested a review from srujzs November 26, 2025 19:07

antfitch requested changes Nov 26, 2025

View reviewed changes

IldySilva approved these changes Dec 7, 2025

View reviewed changes

srujzs reviewed Dec 9, 2025

View reviewed changes

apply review suggestions

04f4e19

fsw requested a review from srujzs December 10, 2025 08:01

srujzs approved these changes Dec 10, 2025

View reviewed changes

fsw mentioned this pull request Dec 11, 2025

Mutable List interface for children and childNodes dart-lang/web#490

Open

1 task

add more examples to package:web migration #7040

Are you sure you want to change the base?

add more examples to package:web migration #7040

Conversation

fsw commented Nov 23, 2025

Uh oh!

google-cla bot commented Nov 23, 2025

Uh oh!

gemini-code-assist bot commented Nov 23, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

antfitch commented Nov 25, 2025

Uh oh!

dart-github-bot commented Nov 25, 2025

Uh oh!

kevmoo left a comment

Choose a reason for hiding this comment

Uh oh!

antfitch left a comment

Choose a reason for hiding this comment

Uh oh!

srujzs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

srujzs Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

fsw Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

srujzs Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

fsw Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

srujzs Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants