From 587a5ec7bdb426b0d37f546721509642e7580cb4 Mon Sep 17 00:00:00 2001 From: Marya Belanger Date: Tue, 21 Jan 2025 10:08:25 -0800 Subject: [PATCH 1/8] remove html page from sidenav, replace with js_interop. add prev/next to js interop pages --- src/_data/side-nav.yml | 5 +++-- src/content/interop/js-interop/index.md | 3 +++ src/content/interop/js-interop/js-types.md | 6 ++++++ src/content/interop/js-interop/package-web.md | 3 +++ src/content/interop/js-interop/past-js-interop.md | 6 ++++++ src/content/interop/js-interop/tutorials.md | 6 ++++++ src/content/interop/js-interop/usage.md | 6 ++++++ src/content/libraries/dart-html.md | 7 +++---- src/content/libraries/dart-io.md | 4 ++-- src/content/libraries/index.md | 4 ++-- 10 files changed, 40 insertions(+), 10 deletions(-) diff --git a/src/_data/side-nav.yml b/src/_data/side-nav.yml index 143e3050ed..5cd0d4809a 100644 --- a/src/_data/side-nav.yml +++ b/src/_data/side-nav.yml @@ -118,8 +118,9 @@ permalink: /libraries/dart-convert - title: dart:io permalink: /libraries/dart-io - - title: dart:html - permalink: /libraries/dart-html + - title: dart:js_interop + permalink: /interop/js-interop + match-page-url-exactly: true - divider - title: Iterable collections permalink: /libraries/collections/iterables diff --git a/src/content/interop/js-interop/index.md b/src/content/interop/js-interop/index.md index 5bc3a815e2..79bed4f41b 100644 --- a/src/content/interop/js-interop/index.md +++ b/src/content/interop/js-interop/index.md @@ -2,6 +2,9 @@ title: JavaScript interoperability short-title: JS interop description: Integrate JavaScript code into your Dart web app. +nextpage: + url: /interop/js-interop/usage + title: Usage --- The [Dart web platform](/overview#web-platform) supports communication with diff --git a/src/content/interop/js-interop/js-types.md b/src/content/interop/js-interop/js-types.md index f6e716d370..e644b46755 100644 --- a/src/content/interop/js-interop/js-types.md +++ b/src/content/interop/js-interop/js-types.md @@ -1,6 +1,12 @@ --- title: JS types description: Usage information about the core types in JS interop. +prevpage: + url: /interop/js-interop/usage + title: Usage +nextpage: + url: /interop/js-interop/tutorials + title: JS interop tutorials --- Dart values and JS values belong to separate language domains. When compiling to diff --git a/src/content/interop/js-interop/package-web.md b/src/content/interop/js-interop/package-web.md index f6c196a931..23c9d6238c 100644 --- a/src/content/interop/js-interop/package-web.md +++ b/src/content/interop/js-interop/package-web.md @@ -1,6 +1,9 @@ --- title: Migrate to package:web description: How to migrate web interop code from dart:html to package:web. +prevpage: + url: /interop/js-interop/past-js-interop + title: Past JS interop --- Dart's [`package:web`][] exposes access to browser APIs, diff --git a/src/content/interop/js-interop/past-js-interop.md b/src/content/interop/js-interop/past-js-interop.md index 43db9523a3..78846ac722 100644 --- a/src/content/interop/js-interop/past-js-interop.md +++ b/src/content/interop/js-interop/past-js-interop.md @@ -1,6 +1,12 @@ --- title: Past JS interop description: Archive of Dart's previous JS interop support. +prevpage: + url: /interop/js-interop/tutorials + title: JS interop tutorials +nextpage: + url: /interop/js-interop/package-web/ + title: Migrate to package:web --- :::warning diff --git a/src/content/interop/js-interop/tutorials.md b/src/content/interop/js-interop/tutorials.md index 693de43872..58c12fd195 100644 --- a/src/content/interop/js-interop/tutorials.md +++ b/src/content/interop/js-interop/tutorials.md @@ -1,6 +1,12 @@ --- title: JS interop tutorials description: Tutorials for common JavaScript interop use cases in Dart. +prevpage: + url: /interop/js-interop/js-types + title: JS types +nextpage: + url: /interop/js-interop/past-js-interop + title: Past JS interop --- ## Tutorials diff --git a/src/content/interop/js-interop/usage.md b/src/content/interop/js-interop/usage.md index 8a7ad08a5a..8432f76315 100644 --- a/src/content/interop/js-interop/usage.md +++ b/src/content/interop/js-interop/usage.md @@ -1,6 +1,12 @@ --- title: Usage description: How to declare and use JS interop members. +prevpage: + url: /interop/js-interop/ + title: JS interop +nextpage: + url: /interop/js-interop/js-types + title: JS types --- JS interop provides the mechanisms to interact with JavaScript APIs from Dart. diff --git a/src/content/libraries/dart-html.md b/src/content/libraries/dart-html.md index 94414eceb2..c04db66e99 100644 --- a/src/content/libraries/dart-html.md +++ b/src/content/libraries/dart-html.md @@ -7,10 +7,8 @@ prevpage: --- :::warning -`dart:html` is being replaced with [`package:web`][]. -Package maintainers should migrate to `package:web` as -soon as possible to be compatible with Wasm. -Read the [Migrate to package:web][] page for guidance. +The `dart:html` library is deprecated. +Instead, use [`dart:js_interop`][] or [`package:web`][]. ::: Use the [dart:html][] library to program the browser, manipulate objects and @@ -449,6 +447,7 @@ Dart has additional libraries for more specialized web APIs, such as For more information about Dart web libraries, see the [web library overview.][web library overview] +[`dart:js_interop`]: /interop/js-interop [AnchorElement]: {{site.dart-api}}/dart-html/AnchorElement-class.html [dart:html]: {{site.dart-api}}/dart-html/dart-html-library.html [Fetch data from the internet]: /tutorials/server/fetch-data diff --git a/src/content/libraries/dart-io.md b/src/content/libraries/dart-io.md index 18d32c64ca..c1251e50f8 100644 --- a/src/content/libraries/dart-io.md +++ b/src/content/libraries/dart-io.md @@ -5,8 +5,8 @@ prevpage: url: /libraries/dart-convert title: dart:convert nextpage: - url: /libraries/dart-html - title: dart:html + url: /interop/js-interop/ + title: dart:js_interop --- diff --git a/src/content/libraries/index.md b/src/content/libraries/index.md index 35e1e8194c..b0f45f3703 100644 --- a/src/content/libraries/index.md +++ b/src/content/libraries/index.md @@ -46,9 +46,9 @@ consult the [Dart API reference.][Dart API] : I/O for programs that can use the Dart VM, including Flutter apps, servers, and command-line scripts. -[dart:html](/libraries/dart-html) +[dart:js_interop](/interop/js-interop) : DOM and other APIs for browser-based apps. - We now recommend using `package:web` over `dart:html`. + `dart:js_interop` replaces `dart:html`. As mentioned, these pages are just an overview; From de38f6a65332027266bf581841d6a0a804c30591 Mon Sep 17 00:00:00 2001 From: Marya Belanger Date: Tue, 21 Jan 2025 11:27:45 -0800 Subject: [PATCH 2/8] html redirects to pkg:web --- firebase.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/firebase.json b/firebase.json index 1dce8b46f1..edc58c255f 100644 --- a/firebase.json +++ b/firebase.json @@ -140,14 +140,14 @@ { "source": "/docs/spec/deferred-loading", "destination": "/language/libraries#lazily-loading-a-library", "type": 301 }, { "source": "/docs/spec{,/**}", "destination": "/resources/language/spec", "type": 301 }, { "source": "/docs/technical-overview{,/**}", "destination": "/overview", "type": 301 }, - { "source": "/docs/tutorials/add-elements", "destination": "/library/dart-html", "type": 301 }, + { "source": "/docs/tutorials/add-elements", "destination": "/interop/js-interop/package-web", "type": 301 }, { "source": "/docs/tutorials/cmdline", "destination": "/tutorials/server/cmdline", "type": 301 }, - { "source": "/docs/tutorials/connect-dart-html", "destination": "/library/dart-html", "type": 301 }, + { "source": "/docs/tutorials/connect-dart-html", "destination": "/interop/js-interop/package-web", "type": 301 }, { "source": "/docs/tutorials/fetchdata", "destination": "/tutorials/server/fetch-data", "type": 301 }, { "source": "/docs/tutorials/futures", "destination": "/libraries/async/async-await", "type": 301 }, { "source": "/docs/tutorials/get-started", "destination": "/tutorials/server/get-started", "type": 301 }, { "source": "/docs/tutorials/httpserver", "destination": "/tutorials/server/httpserver", "type": 301 }, - { "source": "/docs/tutorials/remove-elements", "destination": "/library/dart-html", "type": 301 }, + { "source": "/docs/tutorials/remove-elements", "destination": "/interop/js-interop/package-web", "type": 301 }, { "source": "/docs/tutorials/shared-pkgs", "destination": "/tools/pub/packages", "type": 301 }, { "source": "/docs/tutorials/streams", "destination": "/libraries/async/using-streams", "type": 301 }, { "source": "/docs/tutorials{,/**}", "destination": "/tutorials", "type": 301 }, @@ -436,7 +436,7 @@ { "source": "/tutorials/web/fetch-data", "destination": "/tutorials/server/fetch-data", "type": 301 }, { "source": "/tutorials/web/get-started", "destination": "/web/get-started", "type": 301 }, { "source": "/tutorials/web/low-level-html", "destination": "/web/get-started", "type": 301 }, - { "source": "/tutorials/web/low-level-html/:rest*", "destination": "/libraries/dart-html", "type": 301 }, + { "source": "/tutorials/web/low-level-html/:rest*", "destination": "/interop/js-interop/package-web", "type": 301 }, { "source": "/web/dart-2", "destination": "/tools/webdev", "type": 301 }, { "source": "/web/js-interop", "destination": "/interop/js-interop", "type": 301 }, { "source": "/{docs,tools}/{pub-package-manager,pub/cmd,pub/tools/pub}/glossary", "destination": "/tools/pub/glossary", "type": 301 } From 7f722d1bbda09c206ae81ef82374cb0f1406905a Mon Sep 17 00:00:00 2001 From: Marya Belanger Date: Tue, 21 Jan 2025 12:03:30 -0800 Subject: [PATCH 3/8] replace more html mentions --- examples/misc/test/language_tour/browser_test.dart | 6 +++--- src/content/language/libraries.md | 8 ++++---- src/content/overview.md | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/examples/misc/test/language_tour/browser_test.dart b/examples/misc/test/language_tour/browser_test.dart index a2bff59c72..3498b71194 100644 --- a/examples/misc/test/language_tour/browser_test.dart +++ b/examples/misc/test/language_tour/browser_test.dart @@ -2,9 +2,9 @@ @TestOn('browser') library; -// #docregion dart-html-import -import 'dart:html'; -// #enddocregion dart-html-import +// #docregion dart-js-interop-import +import 'dart:js_interop'; +// #enddocregion dart-js-interop-import // #docregion package-import import 'package:test/test.dart'; // #enddocregion package-import diff --git a/src/content/language/libraries.md b/src/content/language/libraries.md index 897dcd415a..b9345e8930 100644 --- a/src/content/language/libraries.md +++ b/src/content/language/libraries.md @@ -31,12 +31,12 @@ like `public` or `private`, consult Use `import` to specify how a namespace from one library is used in the scope of another library. -For example, Dart web apps generally use the [dart:html][] +For example, Dart web apps generally use the [dart:js_interop][] library, which they can import like this: - + ```dart -import 'dart:html'; +import 'dart:js_interop'; ``` The only required argument to `import` is a URI specifying the @@ -173,6 +173,6 @@ for advice on how to implement a package, including: * How to use conditional imports and exports to implement a library that supports multiple platforms. -[dart:html]: {{site.dart-api}}/dart-html +[dart:js_interop]: {{site.dart-api}}/dart-js_interop/dart-js_interop-library.html [doc comments]: /effective-dart/documentation#consider-writing-a-library-level-doc-comment [metadata annotations]: /language/metadata diff --git a/src/content/overview.md b/src/content/overview.md index 9b158ce79d..e489b39475 100644 --- a/src/content/overview.md +++ b/src/content/overview.md @@ -148,7 +148,7 @@ providing essentials for many everyday programming tasks: (`dart:isolate`) * HTML elements and other resources for web-based applications that need to interact with the browser and the Document Object Model (DOM) - (`dart:html`) + (`dart:js_interop` and `package:web`) Beyond the core libraries, many APIs are provided through a comprehensive set of packages. From 4c6b47446feaf078eaa7e69b73ae354339ac2e93 Mon Sep 17 00:00:00 2001 From: Marya Belanger Date: Tue, 21 Jan 2025 12:23:54 -0800 Subject: [PATCH 4/8] code excerpt --- examples/misc/test/language_tour/browser_test.dart | 1 + 1 file changed, 1 insertion(+) diff --git a/examples/misc/test/language_tour/browser_test.dart b/examples/misc/test/language_tour/browser_test.dart index 3498b71194..3aa4f742dc 100644 --- a/examples/misc/test/language_tour/browser_test.dart +++ b/examples/misc/test/language_tour/browser_test.dart @@ -5,6 +5,7 @@ library; // #docregion dart-js-interop-import import 'dart:js_interop'; // #enddocregion dart-js-interop-import +import 'dart:html'; // #docregion package-import import 'package:test/test.dart'; // #enddocregion package-import From 19ad55b71d7efcbe6d3af6b050fb781a8823c08a Mon Sep 17 00:00:00 2001 From: Marya Belanger Date: Tue, 21 Jan 2025 12:27:46 -0800 Subject: [PATCH 5/8] ignore arbitrary import --- examples/misc/test/language_tour/browser_test.dart | 2 ++ 1 file changed, 2 insertions(+) diff --git a/examples/misc/test/language_tour/browser_test.dart b/examples/misc/test/language_tour/browser_test.dart index 3aa4f742dc..e2f07cb54e 100644 --- a/examples/misc/test/language_tour/browser_test.dart +++ b/examples/misc/test/language_tour/browser_test.dart @@ -1,3 +1,5 @@ +// ignore_for_file: unused_import + @Tags(['browser']) @TestOn('browser') library; From e4e424b5e42820ad08392fba9dd28d617bf57bb4 Mon Sep 17 00:00:00 2001 From: Marya <111139605+MaryaBelanger@users.noreply.github.com> Date: Tue, 21 Jan 2025 14:16:12 -0800 Subject: [PATCH 6/8] Apply suggestions from parlough Co-authored-by: Parker Lougheed --- src/content/libraries/dart-html.md | 2 +- src/content/libraries/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/libraries/dart-html.md b/src/content/libraries/dart-html.md index c04db66e99..9f411e31d2 100644 --- a/src/content/libraries/dart-html.md +++ b/src/content/libraries/dart-html.md @@ -8,7 +8,7 @@ prevpage: :::warning The `dart:html` library is deprecated. -Instead, use [`dart:js_interop`][] or [`package:web`][]. +Instead, use [`dart:js_interop`][] and [`package:web`][]. ::: Use the [dart:html][] library to program the browser, manipulate objects and diff --git a/src/content/libraries/index.md b/src/content/libraries/index.md index b0f45f3703..64858ba0e2 100644 --- a/src/content/libraries/index.md +++ b/src/content/libraries/index.md @@ -47,7 +47,7 @@ consult the [Dart API reference.][Dart API] including Flutter apps, servers, and command-line scripts. [dart:js_interop](/interop/js-interop) -: DOM and other APIs for browser-based apps. +: APIs for interop with the web platform. `dart:js_interop` replaces `dart:html`. From 62f8d74574ad8c6fa5f12e91a98a8cd2f402716e Mon Sep 17 00:00:00 2001 From: Marya Belanger Date: Tue, 21 Jan 2025 14:18:51 -0800 Subject: [PATCH 7/8] code font --- src/content/language/libraries.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/language/libraries.md b/src/content/language/libraries.md index b9345e8930..e1f3d7dfd7 100644 --- a/src/content/language/libraries.md +++ b/src/content/language/libraries.md @@ -31,7 +31,7 @@ like `public` or `private`, consult Use `import` to specify how a namespace from one library is used in the scope of another library. -For example, Dart web apps generally use the [dart:js_interop][] +For example, Dart web apps generally use the [`dart:js_interop`][] library, which they can import like this: @@ -173,6 +173,6 @@ for advice on how to implement a package, including: * How to use conditional imports and exports to implement a library that supports multiple platforms. -[dart:js_interop]: {{site.dart-api}}/dart-js_interop/dart-js_interop-library.html +[`dart:js_interop`]: {{site.dart-api}}/dart-js_interop/dart-js_interop-library.html [doc comments]: /effective-dart/documentation#consider-writing-a-library-level-doc-comment [metadata annotations]: /language/metadata From b17fba6b55200d1b9aa407149622b1905d48d865 Mon Sep 17 00:00:00 2001 From: Marya Belanger Date: Wed, 22 Jan 2025 11:28:45 -0800 Subject: [PATCH 8/8] include pkg:web, move link --- src/content/libraries/dart-html.md | 2 +- src/content/libraries/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/libraries/dart-html.md b/src/content/libraries/dart-html.md index 9f411e31d2..552482c188 100644 --- a/src/content/libraries/dart-html.md +++ b/src/content/libraries/dart-html.md @@ -34,6 +34,7 @@ To use the HTML library in your web app, import dart:html: import 'dart:html'; ``` +[`dart:js_interop`]: /interop/js-interop [`package:web`]: {{site.pub-pkg}}/web [Migrate to package:web]: /interop/js-interop/package-web @@ -447,7 +448,6 @@ Dart has additional libraries for more specialized web APIs, such as For more information about Dart web libraries, see the [web library overview.][web library overview] -[`dart:js_interop`]: /interop/js-interop [AnchorElement]: {{site.dart-api}}/dart-html/AnchorElement-class.html [dart:html]: {{site.dart-api}}/dart-html/dart-html-library.html [Fetch data from the internet]: /tutorials/server/fetch-data diff --git a/src/content/libraries/index.md b/src/content/libraries/index.md index 64858ba0e2..a268bf7aa7 100644 --- a/src/content/libraries/index.md +++ b/src/content/libraries/index.md @@ -48,7 +48,7 @@ consult the [Dart API reference.][Dart API] [dart:js_interop](/interop/js-interop) : APIs for interop with the web platform. - `dart:js_interop` replaces `dart:html`. + Along with `package:web`,`dart:js_interop` replaces `dart:html`. As mentioned, these pages are just an overview;