[dart:js_interop] Add JSArray.add

Fixes #59830

Migration from Lists to JSArray sometimes involve usages
of List.add. In the migration, if List.add was used, it would
become JSAnyOperationExtension.add, which is the JS + operator.
This then leads to bugs where users mistakenly assumed that
something similar to List.add was occurring.

CoreLibraryReviewExempt: Wasm and JS backends only.
Change-Id: I2bb6684316725167a8fa65fd51483f2717788dad
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/443182
Reviewed-by: Lasse Nielsen <[email protected]>
Commit-Queue: Srujan Gaddam <[email protected]>
Reviewed-by: Stephen Adams <[email protected]>

Author: srujzs

CHANGELOG.md

@@ -29,6 +29,14 @@
 
 [#56468]: https://github.com/dart-lang/sdk/issues/56468
 
+#### `dart:js_interop`
+
+- `JSArray.add` is added to avoid cases where during migration from `List` to
+  `JSArray`, `JSAnyOperatorExtension.add` is accidentally used. See [#59830][]
+  for more details.
+
+[#59830]: https://github.com/dart-lang/sdk/issues/59830
+
 ## 3.9.0
 
 **Released on:** Unreleased

sdk/lib/js_interop/js_interop.dart

@@ -184,6 +184,14 @@ extension type JSArray<T extends JSAny?>._(JSArrayRepType _jsArray)
   /// Sets the [value] at [position] in this `Array`.
   @Since('3.6')
   external void operator []=(int position, T value);
+
+  /// Adds [value] to the end of this `Array`, extending the length by one.
+  // This maps to `List.add` to avoid accidental usage of
+  // `JSAnyOperatorExtension.add` when migrating `List`s to `JSArray`s. See
+  // https://github.com/dart-lang/sdk/issues/59830.
+  @Since('3.10')
+  @JS('push')
+  external void add(T value);
 }
 
 /// A JavaScript `Promise` or a promise-like object.

tests/lib/js/static_interop_test/js_types_test.dart

@@ -246,6 +246,9 @@ void syncTests() {
   arrN = JSArray.from<JSNumber>(arrN);
   Expect.equals(1, arrN.length);
   Expect.equals(1, arrN[0].toDartInt);
+  arrN.add(0.toJS);
+  Expect.equals(2, arrN.length);
+  Expect.equals(0, arrN[1].toDartInt);
   final typedArray = JSArray.from<JSNumber>(JSUint8Array.withLength(4));
   Expect.equals(4, typedArray.length);
   Expect.equals(0, typedArray[0].toDartInt);