Update documentation for IntrinsicWidth & IntrinsicHeight (#61502)

https://github.com/flutter/flutter/issues/61496

packages/flutter/lib/src/rendering/proxy_box.dart

@@ -537,21 +537,38 @@ class RenderAspectRatio extends RenderProxyBox {
   }
 }
 
-/// Sizes its child to the child's intrinsic width.
-///
-/// Sizes its child's width to the child's maximum intrinsic width. If
-/// [stepWidth] is non-null, the child's width will be snapped to a multiple of
-/// the [stepWidth]. Similarly, if [stepHeight] is non-null, the child's height
-/// will be snapped to a multiple of the [stepHeight].
+/// Sizes its child to the child's maximum intrinsic width.
 ///
 /// This class is useful, for example, when unlimited width is available and
 /// you would like a child that would otherwise attempt to expand infinitely to
 /// instead size itself to a more reasonable width.
 ///
+/// The constraints that this object passes to its child will adhere to the
+/// parent's constraints, so if the constraints are not large enough to satisfy
+/// the child's maximum intrinsic width, then the child will get less width
+/// than it otherwise would. Likewise, if the minimum width constraint is
+/// larger than the child's maximum intrinsic width, the child will be given
+/// more width than it otherwise would.
+///
+/// If [stepWidth] is non-null, the child's width will be snapped to a multiple
+/// of the [stepWidth]. Similarly, if [stepHeight] is non-null, the child's
+/// height will be snapped to a multiple of the [stepHeight].
+///
 /// This class is relatively expensive, because it adds a speculative layout
 /// pass before the final layout phase. Avoid using it where possible. In the
 /// worst case, this render object can result in a layout that is O(N²) in the
 /// depth of the tree.
+///
+/// See also:
+///
+///  * [Align], a widget that aligns its child within itself. This can be used
+///    to loosen the constraints passed to the [RenderIntrinsicWidth],
+///    allowing the [RenderIntrinsicWidth]'s child to be smaller than that of
+///    its parent.
+///  * [Row], which when used with [CrossAxisAlignment.stretch] can be used
+///    to loosen just the width constraints that are passed to the
+///    [RenderIntrinsicWidth], allowing the [RenderIntrinsicWidth]'s child's
+///    width to be smaller than that of its parent.
 class RenderIntrinsicWidth extends RenderProxyBox {
   /// Creates a render object that sizes itself to its child's intrinsic width.
   ///
@@ -670,10 +687,28 @@ class RenderIntrinsicWidth extends RenderProxyBox {
 /// you would like a child that would otherwise attempt to expand infinitely to
 /// instead size itself to a more reasonable height.
 ///
+/// The constraints that this object passes to its child will adhere to the
+/// parent's constraints, so if the constraints are not large enough to satisfy
+/// the child's maximum intrinsic height, then the child will get less height
+/// than it otherwise would. Likewise, if the minimum height constraint is
+/// larger than the child's maximum intrinsic height, the child will be given
+/// more height than it otherwise would.
+///
 /// This class is relatively expensive, because it adds a speculative layout
 /// pass before the final layout phase. Avoid using it where possible. In the
 /// worst case, this render object can result in a layout that is O(N²) in the
 /// depth of the tree.
+///
+/// See also:
+///
+///  * [Align], a widget that aligns its child within itself. This can be used
+///    to loosen the constraints passed to the [RenderIntrinsicHeight],
+///    allowing the [RenderIntrinsicHeight]'s child to be smaller than that of
+///    its parent.
+///  * [Column], which when used with [CrossAxisAlignment.stretch] can be used
+///    to loosen just the height constraints that are passed to the
+///    [RenderIntrinsicHeight], allowing the [RenderIntrinsicHeight]'s child's
+///    height to be smaller than that of its parent.
 class RenderIntrinsicHeight extends RenderProxyBox {
   /// Creates a render object that sizes itself to its child's intrinsic height.
   RenderIntrinsicHeight({

packages/flutter/lib/src/widgets/basic.dart

@@ -2793,17 +2793,23 @@ class AspectRatio extends SingleChildRenderObjectWidget {
   }
 }
 
-/// A widget that sizes its child to the child's intrinsic width.
-///
-/// Sizes its child's width to the child's maximum intrinsic width. If
-/// [stepWidth] is non-null, the child's width will be snapped to a multiple of
-/// the [stepWidth]. Similarly, if [stepHeight] is non-null, the child's height
-/// will be snapped to a multiple of the [stepHeight].
+/// A widget that sizes its child to the child's maximum intrinsic width.
 ///
 /// This class is useful, for example, when unlimited width is available and
 /// you would like a child that would otherwise attempt to expand infinitely to
 /// instead size itself to a more reasonable width.
 ///
+/// The constraints that this widget passes to its child will adhere to the
+/// parent's constraints, so if the constraints are not large enough to satisfy
+/// the child's maximum intrinsic width, then the child will get less width
+/// than it otherwise would. Likewise, if the minimum width constraint is
+/// larger than the child's maximum intrinsic width, the child will be given
+/// more width than it otherwise would.
+///
+/// If [stepWidth] is non-null, the child's width will be snapped to a multiple
+/// of the [stepWidth]. Similarly, if [stepHeight] is non-null, the child's
+/// height will be snapped to a multiple of the [stepHeight].
+///
 /// This class is relatively expensive, because it adds a speculative layout
 /// pass before the final layout phase. Avoid using it where possible. In the
 /// worst case, this widget can result in a layout that is O(N²) in the depth of
@@ -2811,6 +2817,14 @@ class AspectRatio extends SingleChildRenderObjectWidget {
 ///
 /// See also:
 ///
+///  * [Align], a widget that aligns its child within itself. This can be used
+///    to loosen the constraints passed to the [RenderIntrinsicWidth],
+///    allowing the [RenderIntrinsicWidth]'s child to be smaller than that of
+///    its parent.
+///  * [Row], which when used with [CrossAxisAlignment.stretch] can be used
+///    to loosen just the width constraints that are passed to the
+///    [RenderIntrinsicWidth], allowing the [RenderIntrinsicWidth]'s child's
+///    width to be smaller than that of its parent.
 ///  * [The catalog of layout widgets](https://flutter.dev/widgets/layout/).
 class IntrinsicWidth extends SingleChildRenderObjectWidget {
   /// Creates a widget that sizes its child to the child's intrinsic width.
@@ -2863,6 +2877,13 @@ class IntrinsicWidth extends SingleChildRenderObjectWidget {
 /// you would like a child that would otherwise attempt to expand infinitely to
 /// instead size itself to a more reasonable height.
 ///
+/// The constraints that this widget passes to its child will adhere to the
+/// parent's constraints, so if the constraints are not large enough to satisfy
+/// the child's maximum intrinsic height, then the child will get less height
+/// than it otherwise would. Likewise, if the minimum height constraint is
+/// larger than the child's maximum intrinsic height, the child will be given
+/// more height than it otherwise would.
+///
 /// This class is relatively expensive, because it adds a speculative layout
 /// pass before the final layout phase. Avoid using it where possible. In the
 /// worst case, this widget can result in a layout that is O(N²) in the depth of
@@ -2870,6 +2891,14 @@ class IntrinsicWidth extends SingleChildRenderObjectWidget {
 ///
 /// See also:
 ///
+///  * [Align], a widget that aligns its child within itself. This can be used
+///    to loosen the constraints passed to the [RenderIntrinsicHeight],
+///    allowing the [RenderIntrinsicHeight]'s child to be smaller than that of
+///    its parent.
+///  * [Column], which when used with [CrossAxisAlignment.stretch] can be used
+///    to loosen just the height constraints that are passed to the
+///    [RenderIntrinsicHeight], allowing the [RenderIntrinsicHeight]'s child's
+///    height to be smaller than that of its parent.
 ///  * [The catalog of layout widgets](https://flutter.dev/widgets/layout/).
 class IntrinsicHeight extends SingleChildRenderObjectWidget {
   /// Creates a widget that sizes its child to the child's intrinsic height.

packages/flutter/test/rendering/intrinsic_width_test.dart

@@ -59,6 +59,8 @@ void main() {
     );
     expect(parent.size.width, equals(100.0));
     expect(parent.size.height, equals(110.0));
+    expect(child.size.width, equals(100));
+    expect(child.size.height, equals(110));
 
     expect(parent.getMinIntrinsicWidth(0.0), equals(100.0));
     expect(parent.getMaxIntrinsicWidth(0.0), equals(100.0));
@@ -128,6 +130,8 @@ void main() {
     );
     expect(parent.size.width, equals(3.0 * 47.0));
     expect(parent.size.height, equals(110.0));
+    expect(child.size.width, equals(3 * 47));
+    expect(child.size.height, equals(110));
 
     expect(parent.getMinIntrinsicWidth(0.0), equals(3.0 * 47.0));
     expect(parent.getMaxIntrinsicWidth(0.0), equals(3.0 * 47.0));
@@ -220,6 +224,57 @@ void main() {
     expect(parent.getMaxIntrinsicHeight(double.infinity), equals(5.0 * 47.0));
   });
 
+  test('RenderIntrinsicWidth when parent is given loose constraints smaller than intrinsic width of child', () {
+    final RenderBox child = RenderTestBox(const BoxConstraints(minWidth: 10.0, maxWidth: 100.0, minHeight: 20.0, maxHeight: 200.0));
+    final RenderBox parent = RenderIntrinsicWidth(child: child);
+    layout(parent,
+      constraints: const BoxConstraints(
+        minWidth: 50.0,
+        minHeight: 8.0,
+        maxWidth: 70.0,
+        maxHeight: 800.0,
+      ),
+    );
+    expect(parent.size.width, equals(70));
+    expect(parent.size.height, equals(110));
+    expect(child.size.width, equals(70));
+    expect(child.size.height, equals(110));
+  });
+
+  test('RenderIntrinsicWidth when parent is given tight constraints larger than intrinsic width of child', () {
+    final RenderBox child = RenderTestBox(const BoxConstraints(minWidth: 10.0, maxWidth: 100.0, minHeight: 20.0, maxHeight: 200.0));
+    final RenderBox parent = RenderIntrinsicWidth(child: child);
+    layout(parent,
+      constraints: const BoxConstraints(
+        minWidth: 500.0,
+        minHeight: 8.0,
+        maxWidth: 500.0,
+        maxHeight: 800.0,
+      ),
+    );
+    expect(parent.size.width, equals(500));
+    expect(parent.size.height, equals(110));
+    expect(child.size.width, equals(500));
+    expect(child.size.height, equals(110));
+  });
+
+  test('RenderIntrinsicWidth when parent is given tight constraints smaller than intrinsic width of child', () {
+    final RenderBox child = RenderTestBox(const BoxConstraints(minWidth: 10.0, maxWidth: 100.0, minHeight: 20.0, maxHeight: 200.0));
+    final RenderBox parent = RenderIntrinsicWidth(child: child);
+    layout(parent,
+      constraints: const BoxConstraints(
+        minWidth: 50.0,
+        minHeight: 8.0,
+        maxWidth: 50.0,
+        maxHeight: 800.0,
+      ),
+    );
+    expect(parent.size.width, equals(50));
+    expect(parent.size.height, equals(110));
+    expect(child.size.width, equals(50));
+    expect(child.size.height, equals(110));
+  });
+
   test('Shrink-wrapping height', () {
     final RenderBox child = RenderTestBox(const BoxConstraints(minWidth: 10.0, maxWidth: 100.0, minHeight: 20.0, maxHeight: 200.0));
     final RenderBox parent = RenderIntrinsicHeight(child: child);
@@ -289,6 +344,57 @@ void main() {
     expect(parent.getMaxIntrinsicHeight(double.infinity), equals(0.0));
   });
 
+  test('RenderIntrinsicHeight when parent is given loose constraints smaller than intrinsic height of child', () {
+    final RenderBox child = RenderTestBox(const BoxConstraints(minWidth: 10.0, maxWidth: 100.0, minHeight: 20.0, maxHeight: 200.0));
+    final RenderBox parent = RenderIntrinsicHeight(child: child);
+    layout(parent,
+      constraints: const BoxConstraints(
+        minWidth: 5.0,
+        minHeight: 8.0,
+        maxWidth: 500.0,
+        maxHeight: 80.0,
+      ),
+    );
+    expect(parent.size.width, equals(55));
+    expect(parent.size.height, equals(80));
+    expect(child.size.width, equals(55));
+    expect(child.size.height, equals(80));
+  });
+
+  test('RenderIntrinsicHeight when parent is given tight constraints larger than intrinsic height of child', () {
+    final RenderBox child = RenderTestBox(const BoxConstraints(minWidth: 10.0, maxWidth: 100.0, minHeight: 20.0, maxHeight: 200.0));
+    final RenderBox parent = RenderIntrinsicHeight(child: child);
+    layout(parent,
+      constraints: const BoxConstraints(
+        minWidth: 5.0,
+        minHeight: 400.0,
+        maxWidth: 500.0,
+        maxHeight: 400.0,
+      ),
+    );
+    expect(parent.size.width, equals(55));
+    expect(parent.size.height, equals(400));
+    expect(child.size.width, equals(55));
+    expect(child.size.height, equals(400));
+  });
+
+  test('RenderIntrinsicHeight when parent is given tight constraints smaller than intrinsic height of child', () {
+    final RenderBox child = RenderTestBox(const BoxConstraints(minWidth: 10.0, maxWidth: 100.0, minHeight: 20.0, maxHeight: 200.0));
+    final RenderBox parent = RenderIntrinsicHeight(child: child);
+    layout(parent,
+      constraints: const BoxConstraints(
+        minWidth: 5.0,
+        minHeight: 80.0,
+        maxWidth: 500.0,
+        maxHeight: 80.0,
+      ),
+    );
+    expect(parent.size.width, equals(55));
+    expect(parent.size.height, equals(80));
+    expect(child.size.width, equals(55));
+    expect(child.size.height, equals(80));
+  });
+
   test('Padding and boring intrinsics', () {
     final RenderBox box = RenderPadding(
       padding: const EdgeInsets.all(15.0),