Clean up and fixes for dart:html usages in code excerpts (#6378)

- Migrated some usages to `package:web`
- Added deprecation ignores to a few usages
- Removed the excerpts for a few other usages

examples/create_libraries/lib/src/hw_web.dart

@@ -0,0 +1,7 @@
+import 'package:web/web.dart' as web;
+
+void alarm([String? text]) {
+  web.window.alert(text ?? message);
+}
+
+String get message => 'Hello world from the web!';

examples/create_libraries/pubspec.yaml

@@ -6,5 +6,8 @@ resolution: workspace
 environment:
   sdk: ^3.6.1
 
+dependencies:
+  web: ^1.1.0
+
 dev_dependencies:
   test: ^1.25.8

examples/html/README.md

@@ -1,2 +1,5 @@
-This package is not an app, it is a collection of code excerpts and associated
-tests used in the `dart:html` library tour.
+**Deprecated** collection of code excerpts used
+in the now-historical `dart:html` library tour.
+
+All usages of `dart:html` should migrate to `dart:js_interop` and `package:web`.
+To learn more, check out [Dart JS interop](https://dart.dev/interop/js-interop).

examples/html/lib/html.dart

@@ -1,4 +1,4 @@
-// ignore_for_file: unused_element, unused_local_variable
+// ignore_for_file: unused_element, unused_local_variable, deprecated_member_use
 // #docregion import
 import 'dart:html';
 // #enddocregion import

examples/html/pubspec.yaml

@@ -1,5 +1,5 @@
-name: html_library_examples
-description: dart.dev example code.
+name: deprecated_html_library_examples
+description: Deprecated dart.dev example code.
 version: 0.0.1
 
 resolution: workspace

examples/html/test/html_test.dart

@@ -1,3 +1,5 @@
+// ignore_for_file: deprecated_member_use
+
 @Tags(['browser'])
 @TestOn('browser')
 library;

examples/misc/bin/cheatsheet/cascades.dart

@@ -1,6 +1,6 @@
 // ignore_for_file: avoid_single_cascade_in_expression_statements
 
-import 'dart:html';
+import 'package:web/web.dart' as web;
 
 void main() {
   final myObject = SomeObject();
@@ -14,18 +14,18 @@ void main() {
   // #enddocregion uses-cascade
 
   // #docregion query-without-cascades
-  var button = querySelector('#confirm');
-  button?.text = 'Confirm';
-  button?.classes.add('important');
-  button?.onClick.listen((e) => window.alert('Confirmed!'));
+  final button = web.document.querySelector('#confirm');
+  button?.textContent = 'Confirm';
+  button?.classList.add('important');
+  button?.onClick.listen((e) => web.window.alert('Confirmed!'));
   button?.scrollIntoView();
   // #enddocregion query-without-cascades
 
   // #docregion query-with-cascades
-  querySelector('#confirm')
-    ?..text = 'Confirm'
-    ..classes.add('important')
-    ..onClick.listen((e) => window.alert('Confirmed!'))
+  web.document.querySelector('#confirm')
+    ?..textContent = 'Confirm'
+    ..classList.add('important')
+    ..onClick.listen((e) => web.window.alert('Confirmed!'))
     ..scrollIntoView();
   // #enddocregion query-with-cascades
 }

examples/misc/lib/effective_dart/style_lib_good.dart

@@ -14,7 +14,7 @@ import 'package:examples/effective_dart/bar.dart' as js;
 
 // #docregion dart-import-first
 import 'dart:async';
-import 'dart:html';
+import 'dart:collection';
 
 // #docregion pkg-import-before-local, sorted
 import 'package:examples/effective_dart/bar/bar.dart';

examples/misc/pubspec.yaml

@@ -10,6 +10,7 @@ dependencies:
   characters: ^1.3.0
   examples_util: { path: ../util }
   http: ^1.2.2
+  web: ^1.1.0
 
 dev_dependencies:
   test: ^1.25.8

examples/misc/test/language_tour/browser_test.dart

@@ -1,45 +1,43 @@
-// ignore_for_file: unused_import
-
 @Tags(['browser'])
 @TestOn('browser')
 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
+import 'package:web/web.dart';
 
 void main() {
   test('cascade-operator', () {
     final div = '<button id="confirm"></button>';
-    document.body?.appendHtml(div);
+    document.body?.insertAdjacentHTML('beforeend', div.toJS);
 
     // #docregion cascade-operator
-    querySelector('#confirm') // Get an object.
-      ?..text = 'Confirm' // Use its members.
-      ..classes.add('important')
+    document.querySelector('#confirm') // Get an object.
+      ?..textContent = 'Confirm' // Use its members.
+      ..classList.add('important')
       ..onClick.listen((e) => window.alert('Confirmed!'))
       ..scrollIntoView();
     // #enddocregion cascade-operator
 
-    expect(document.querySelector('#confirm')?.text, 'Confirm');
+    expect(document.querySelector('#confirm')?.textContent, 'Confirm');
   });
 
   test('cascade-operator-example-expanded', () {
     final div = '<button id="confirm"></button>';
-    document.body?.appendHtml(div);
+    document.body?.insertAdjacentHTML('beforeend', div.toJS);
 
     // #docregion cascade-operator-example-expanded
-    var button = querySelector('#confirm');
-    button?.text = 'Confirm';
-    button?.classes.add('important');
+    final button = document.querySelector('#confirm');
+    button?.textContent = 'Confirm';
+    button?.classList.add('important');
     button?.onClick.listen((e) => window.alert('Confirmed!'));
     button?.scrollIntoView();
     // #enddocregion cascade-operator-example-expanded
 
-    expect(document.querySelector('#confirm')?.text, 'Confirm');
+    expect(document.querySelector('#confirm')?.textContent, 'Confirm');
   });
 }

examples/type_system/lib/common_fixes_analysis.dart

@@ -1,6 +1,6 @@
 // NOTE: Declarations in this file are analyzed but not tested.
 // ignore_for_file: unused_element, unused_local_variable, one_member_abstracts, use_super_parameters
-// ignore_for_file: prefer_function_declarations_over_variables, unused_field, strict_raw_type
+// ignore_for_file: prefer_function_declarations_over_variables, unused_field, strict_raw_type, deprecated_member_use
 
 import 'dart:html';
 

src/content/effective-dart/style.md

@@ -355,7 +355,7 @@ A single linter rule handles all the ordering guidelines:
 <?code-excerpt "style_lib_good.dart (dart-import-first)" replace="/\w+\/effective_dart\///g"?>
 ```dart tag=good
 import 'dart:async';
-import 'dart:html';
+import 'dart:collection';
 
 import 'package:bar/bar.dart';
 import 'package:foo/foo.dart';

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

@@ -205,7 +205,7 @@ A value of type '...' can't be assigned to a variable of type 'JSFunction?'
 
 ### Conditional imports
 
-It is common for code to use a conditional import based on whether `dart:html`
+It's common for code to use a conditional import based on whether `dart:html`
 is supported to differentiate between native and web:
 
 ```dart
@@ -214,14 +214,15 @@ export 'src/hw_none.dart'
     if (dart.library.html) 'src/hw_html.dart';
 ```
 
-However, since `dart:html` is not supported when compiling to Wasm, the correct
-alternative now is to use `dart.library.js_interop` to differentiate between
-native and web:
+However, since `dart:html` is deprecated and not supported when
+compiling to Wasm, the correct alternative now is to
+use `dart.library.js_interop` to differentiate between native and web:
 
+<?code-excerpt "create_libraries/lib/hw_mp.dart (export)"?>
 ```dart
-export 'src/hw_none.dart'
-    if (dart.library.io) 'src/hw_io.dart'
-    if (dart.library.js_interop) 'src/hw_web.dart';
+export 'src/hw_none.dart' // Stub implementation
+    if (dart.library.io) 'src/hw_io.dart' // dart:io implementation
+    if (dart.library.js_interop) 'src/hw_web.dart'; // package:web implementation
 ```
 
 ### Virtual dispatch and mocking
@@ -263,7 +264,7 @@ automatically do this.
 ## Helpers
 
 The core of `package:web` contains `external` interop members,
-but does not provide other functionality that `dart:html` provided by default.
+but doesn't provide other functionality that `dart:html` provided by default.
 To mitigate these differences, `package:web` contains [`helpers`][helpers]
 for additional support in handling a number of use cases
 that aren't directly available through the core interop.
@@ -275,12 +276,12 @@ event listeners. Instead, you can use [stream helpers][] that makes it easy to
 subscribe to events with Dart `Stream`s without writing that code yourself.
 
 ```dart
-// dart:html version
-InputElement htmlInput = InputElement();
+// Original dart:html version:
+final htmlInput = InputElement();
 await htmlInput.onBlur.first;
 
-// package:web version
-HTMLInputElement webInput = document.createElement('input') as HTMLInputElement;
+// Migrated package:web version:
+final webInput = HTMLInputElement();
 await webInput.onBlur.first;
 ```
 

src/content/language/operators.md

@@ -448,24 +448,20 @@ are attempted on that null object.
 
 <?code-excerpt "misc/test/language_tour/browser_test.dart (cascade-operator)"?>
 ```dart
-querySelector('#confirm') // Get an object.
-  ?..text = 'Confirm' // Use its members.
-  ..classes.add('important')
+document.querySelector('#confirm') // Get an object.
+  ?..textContent = 'Confirm' // Use its members.
+  ..classList.add('important')
   ..onClick.listen((e) => window.alert('Confirmed!'))
   ..scrollIntoView();
 ```
 
-:::version-note
-The `?..` syntax requires a [language version][] of at least 2.12.
-:::
-
 The previous code is equivalent to the following:
 
 <?code-excerpt "misc/test/language_tour/browser_test.dart (cascade-operator-example-expanded)"?>
 ```dart
-var button = querySelector('#confirm');
-button?.text = 'Confirm';
-button?.classes.add('important');
+final button = document.querySelector('#confirm');
+button?.textContent = 'Confirm';
+button?.classList.add('important');
 button?.onClick.listen((e) => window.alert('Confirmed!'));
 button?.scrollIntoView();
 ```

src/content/libraries/async/zones.md

@@ -792,7 +792,7 @@ The source code for the stack_trace package
   You can find the stack_trace source code in the
   [stack_trace GitHub project]({{site.repo.dart.org}}/stack_trace).
 
-The source code for dart:html and dart:async
+The source code for dart:async
 : These two SDK libraries implement APIs featuring asynchronous callbacks,
   and thus they deal with zones.
   You can browse or download their source code under the

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.
-  Along with `package:web`,`dart:js_interop` replaces `dart:html`.
+  Along with `package:web`, `dart:js_interop` replaces `dart:html`.
 
 
 As mentioned, these pages are just an overview;

src/content/resources/dart-cheatsheet.md

@@ -619,10 +619,10 @@ to read properties of `button` if it isn't `null`:
 
 <?code-excerpt "misc/bin/cheatsheet/cascades.dart (query-without-cascades)"?>
 ```dart
-var button = querySelector('#confirm');
-button?.text = 'Confirm';
-button?.classes.add('important');
-button?.onClick.listen((e) => window.alert('Confirmed!'));
+final button = web.document.querySelector('#confirm');
+button?.textContent = 'Confirm';
+button?.classList.add('important');
+button?.onClick.listen((e) => web.window.alert('Confirmed!'));
 button?.scrollIntoView();
 ```
 
@@ -635,10 +635,10 @@ and makes the `button` variable unnecessary:
 
 <?code-excerpt "misc/bin/cheatsheet/cascades.dart (query-with-cascades)"?>
 ```dart
-querySelector('#confirm')
-  ?..text = 'Confirm'
-  ..classes.add('important')
-  ..onClick.listen((e) => window.alert('Confirmed!'))
+web.document.querySelector('#confirm')
+  ?..textContent = 'Confirm'
+  ..classList.add('important')
+  ..onClick.listen((e) => web.window.alert('Confirmed!'))
   ..scrollIntoView();
 ```
 

src/content/tutorials/server/cmdline.md

@@ -285,7 +285,8 @@ import 'dart:io';
 ```
 
 :::note
-Web apps (apps that depend on `dart:html`) can't use the `dart:io` library.
+Apps that run on the [web platform](/overview#platform)
+can't use the `dart:io` library.
 :::
 
 ### stdout

src/content/tutorials/server/fetch-data.md

@@ -148,10 +148,8 @@ for making composable HTTP requests,
 with optional fine-grained control.
 
 :::note
-You should avoid directly using `dart:io` or `dart:html`
-to make HTTP requests.
-Those libraries are platform-dependent
-and tied to a single implementation.
+Avoid directly using `dart:io` or `dart:html` to make HTTP requests.
+Those libraries are platform-dependent and tied to a single implementation.
 :::
 
 To add a dependency on `package:http`,