[sdk/math] Mark Point, Rectangle, and MutableRectangle as legacy

These can't be deprecated for a while, at least not until 'dart:html' itself is.

In the mean time, we can at least discourage usage of it and direct developers to more appropriate, long-term solutions.

Contributes to https://github.com/dart-lang/sdk/issues/54852

CoreLibraryReviewExempt: Documentation only change that directs developers to more specific, performant, or flexible solutions.
Change-Id: I9d099a49909673f8af23eab480fdd225e56bcab2
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/351961
Reviewed-by: Nate Bosch <nbosch@google.com>
Reviewed-by: Lasse Nielsen <lrn@google.com>
Commit-Queue: Lasse Nielsen <lrn@google.com>

sdk/lib/math/point.dart

@@ -11,11 +11,35 @@ part of dart.math;
 /// var leftTop = const Point(0, 0);
 /// var rightBottom = const Point(200, 400);
 /// ```
+///
+/// **Legacy:** New usages of [Point] are discouraged.
+///
+/// - If you are using the `Point` class with `dart:html`,
+///   we recommend migrating to `package:web`.
+///   To learn how and why to migrate,
+///   check out the [migration guide](https://dart.dev/go/package-web).
+/// - If you want to combine an `x` and `y` coordinate,
+///   consider using a [record](https://dart.dev/language/records).
+///   Depending on how you will use it, this could look
+///   like `var point = (x, y)` or `var point = (x: x, y: y)`.
+/// - If you want to perform vector operations,
+///   like vector addition or scalar multiplication,
+///   consider using a dedicated vector math library,
+///   such as [`package:vector_math`](https://pub.dev/packages/vector_math).
+/// - If you are developing a Flutter application or package,
+///   consider using the
+///   [`Offset`](https://api.flutter.dev/flutter/dart-ui/Offset-class.html)
+///   type from `dart:ui`.
+// TODO: @Deprecated(
+//     'Use records or a dedicated library like package:vector_math instead.')
 class Point<T extends num> {
   final T x;
   final T y;
 
   /// Creates a point with the provided [x] and [y] coordinates.
+  ///
+  /// **Legacy:** New usages of [Point] are discouraged.
+  /// To learn more, check out the [Point] class API docs.
   const Point(T x, T y)
       : this.x = x,
         this.y = y;

sdk/lib/math/rectangle.dart

@@ -16,6 +16,9 @@ part of dart.math;
 /// The rectangle is the set of points with representable coordinates greater
 /// than or equal to left/top, and with distance to left/top no greater than
 /// width/height (to the limit of the precision of the coordinates).
+///
+/// **Legacy:** New usages of [_RectangleBase] are discouraged.
+/// To learn more, check out the [Rectangle] class API docs.
 abstract class _RectangleBase<T extends num> {
   const _RectangleBase();
 
@@ -117,6 +120,27 @@ abstract class _RectangleBase<T extends num> {
 
 /// A class for representing two-dimensional rectangles whose properties are
 /// immutable.
+///
+/// **Legacy:** New usages of [Rectangle] are discouraged.
+///
+/// - If you are using the `Rectangle` class with `dart:html`,
+///   we recommend migrating to `package:web`.
+///   To learn how and why to migrate,
+///   check out the [migration guide](https://dart.dev/go/package-web).
+/// - If you want to store the boundaries of a rectangle
+///   in some coordinate system,
+///   consider using a [record](https://dart.dev/language/records).
+///   Depending on how you will use it, this could look
+///   like `var boundaries = (mixX: x1, maxX: x2, minY: y1, maxY: y2)`.
+/// - If you need to perform intersection calculations or containment checks,
+///   consider using a dedicated library, such as
+///   [`package:vector_math`](https://pub.dev/packages/vector_math).
+/// - If you are developing a Flutter application or package,
+///   consider using the
+///   [`Rect`](https://api.flutter.dev/flutter/dart-ui/Rect-class.html)
+///   type from `dart:ui`.
+// TODO: @Deprecated(
+//     'Use records or a dedicated library like package:vector_math instead.')
 class Rectangle<T extends num> extends _RectangleBase<T> {
   final T left;
   final T top;
@@ -144,6 +168,9 @@ class Rectangle<T extends num> extends _RectangleBase<T> {
   /// print(rectangle.right); // 320
   /// print(rectangle.bottom); // 650
   /// ```
+  ///
+  /// **Legacy:** New usages of [Rectangle] are discouraged.
+  /// To learn more, check out the [Rectangle] class API docs.
   const Rectangle(this.left, this.top, T width, T height)
       : width = (width < 0)
             ? (width == double.negativeInfinity ? 0.0 : (-width * 0)) as dynamic
@@ -187,6 +214,27 @@ class Rectangle<T extends num> extends _RectangleBase<T> {
 
 /// A class for representing two-dimensional axis-aligned rectangles with
 /// mutable properties.
+///
+/// **Legacy:** New usages of [MutableRectangle] are discouraged.
+///
+/// - If you are using the `MutableRectangle` class with `dart:html`,
+///   we recommend migrating to `package:web`.
+///   To learn how and why to migrate,
+///   check out the [migration guide](https://dart.dev/go/package-web).
+/// - If you want to store the boundaries of a rectangle
+///   in some coordinate system,
+///   consider using a [record](https://dart.dev/language/records).
+///   Depending on how you will use it, this could look
+///   like `var boundaries = (mixX: x1, maxX: x2, minY: y1, maxY: y2)`.
+/// - If you need to perform intersection calculations or containment checks,
+///   consider using a dedicated library, such as
+///   [`package:vector_math`](https://pub.dev/packages/vector_math).
+/// - If you are developing a Flutter application or package,
+///   consider using the
+///   [`Rect`](https://api.flutter.dev/flutter/dart-ui/Rect-class.html)
+///   type from `dart:ui`.
+// TODO: @Deprecated(
+//     'Use records or a dedicated library like package:vector_math instead.')
 class MutableRectangle<T extends num> extends _RectangleBase<T>
     implements Rectangle<T> {
   /// The x-coordinate of the left edge.
@@ -233,6 +281,9 @@ class MutableRectangle<T extends num> extends _RectangleBase<T>
   /// print(rectangle.right); // 220
   /// print(rectangle.bottom); // 150
   /// ```
+  ///
+  /// **Legacy:** New usages of [MutableRectangle] are discouraged.
+  /// To learn more, check out the [MutableRectangle] class API docs.
   MutableRectangle(this.left, this.top, T width, T height)
       : this._width =
             (width < 0) ? _clampToZero<T>(width) : (width + 0 as dynamic),