Api Samples and Diagrams for 10 more classes / functions (#45603)

* Api Samples and Diagrams for the following classes and methods:

  - AlertDialog
  - SimpleDialog
  - SingleChildScrollView
  - showDatePicker
  - RichText
  - InputDecoration
  - Divider
  - StreamBuilder
  - DataTable
  - BottomSheet
    - showBottomSheet
    - showModalBottomSheet

* Update packages/flutter/lib/src/material/divider.dart
Co-Authored-By: Kate Lovett <katelovett@google.com>

* Update packages/flutter/lib/src/widgets/basic.dart
Co-Authored-By: Kate Lovett <katelovett@google.com>

* Update packages/flutter/lib/src/material/data_table.dart
Co-Authored-By: Kate Lovett <katelovett@google.com>

* Update packages/flutter/lib/src/material/bottom_sheet.dart
Co-Authored-By: Kate Lovett <katelovett@google.com>

* Update packages/flutter/lib/src/material/scaffold.dart
Co-Authored-By: Kate Lovett <katelovett@google.com>

* Move animation out of sample

* Remove "widget.size", replace with "60"

packages/flutter/lib/src/material/bottom_sheet.dart

@@ -442,6 +442,49 @@ class _ModalBottomSheetRoute<T> extends PopupRoute<T> {
 /// Returns a `Future` that resolves to the value (if any) that was passed to
 /// [Navigator.pop] when the modal bottom sheet was closed.
 ///
+/// {@animation 350 622 https://flutter.github.io/assets-for-api-docs/assets/material/show_modal_bottom_sheet.mp4}
+///
+/// {@tool snippet --template=stateless_widget_scaffold}
+///
+/// This example demonstrates how to use `showModalBottomSheet` to display a
+/// bottom sheet that obscures the content behind it when a user taps a button.
+/// It also demonstrates how to close the bottom sheet using the [Navigator]
+/// when a user taps on a button inside the bottom sheet.
+///
+/// ```dart
+/// Widget build(BuildContext context) {
+///   return Center(
+///     child: RaisedButton(
+///       child: const Text('showModalBottomSheet'),
+///       onPressed: () {
+///         showModalBottomSheet<void>(
+///           context: context,
+///           builder: (BuildContext context) {
+///             return Container(
+///               height: 200,
+///               color: Colors.amber,
+///               child: Center(
+///                 child: Column(
+///                   mainAxisAlignment: MainAxisAlignment.center,
+///                   mainAxisSize: MainAxisSize.min,
+///                   children: <Widget>[
+///                     const Text('Modal BottomSheet'),
+///                     RaisedButton(
+///                       child: const Text('Close BottomSheet'),
+///                       onPressed: () => Navigator.pop(context),
+///                     )
+///                   ],
+///                 ),
+///               ),
+///             );
+///           },
+///         );
+///       },
+///     ),
+///   );
+/// }
+/// ```
+/// {@end-tool}
 /// See also:
 ///
 ///  * [BottomSheet], which becomes the parent of the widget returned by the

packages/flutter/lib/src/material/data_table.dart

@@ -224,6 +224,67 @@ class DataCell {
 /// target device), it is suggested that you use a
 /// [PaginatedDataTable] which automatically splits the data into
 /// multiple pages.
+///
+/// {@tool snippet --template=stateless_widget_scaffold}
+///
+/// This sample shows how to display a [DataTable] with three columns: name, age, and
+/// role. The columns are defined by three [DataColumn] objects. The table
+/// contains three rows of data for three example users, the data for which
+/// is defined by three [DataRow] objects.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/data_table.png)
+///
+/// ```dart
+/// Widget build(BuildContext context) {
+///   return DataTable(
+///     columns: const <DataColumn>[
+///       DataColumn(
+///         label: Text(
+///           'Name',
+///           style: TextStyle(fontStyle: FontStyle.italic),
+///         ),
+///       ),
+///       DataColumn(
+///         label: Text(
+///           'Age',
+///           style: TextStyle(fontStyle: FontStyle.italic),
+///         ),
+///       ),
+///       DataColumn(
+///         label: Text(
+///           'Role',
+///           style: TextStyle(fontStyle: FontStyle.italic),
+///         ),
+///       ),
+///     ],
+///     rows: const <DataRow>[
+///       DataRow(
+///         cells: <DataCell>[
+///           DataCell(Text('Sarah')),
+///           DataCell(Text('19')),
+///           DataCell(Text('Student')),
+///         ],
+///       ),
+///       DataRow(
+///         cells: <DataCell>[
+///           DataCell(Text('Janine')),
+///           DataCell(Text('43')),
+///           DataCell(Text('Professor')),
+///         ],
+///       ),
+///       DataRow(
+///         cells: <DataCell>[
+///           DataCell(Text('William')),
+///           DataCell(Text('27')),
+///           DataCell(Text('Associate Professor')),
+///         ],
+///       ),
+///     ],
+///   );
+/// }
+/// ```
+///
+/// {@end-tool}
 // TODO(ianh): Also suggest [ScrollingDataTable] once we have it.
 ///
 /// See also:

packages/flutter/lib/src/material/date_picker.dart

@@ -1092,6 +1092,8 @@ typedef SelectableDayPredicate = bool Function(DateTime day);
 /// The [builder] parameter can be used to wrap the dialog widget
 /// to add inherited widgets like [Theme].
 ///
+/// {@animation 350 622 https://flutter.github.io/assets-for-api-docs/assets/material/show_date_picker.mp4}
+///
 /// {@tool sample}
 /// Show a date picker with the dark theme.
 ///

packages/flutter/lib/src/material/dialog.dart

@@ -154,30 +154,32 @@ class Dialog extends StatelessWidget {
 /// Typically passed as the child widget to [showDialog], which displays the
 /// dialog.
 ///
+/// {@animation 350 622 https://flutter.github.io/assets-for-api-docs/assets/material/alert_dialog.mp4}
+///
 /// {@tool sample}
 ///
 /// This snippet shows a method in a [State] which, when called, displays a dialog box
 /// and returns a [Future] that completes when the dialog is dismissed.
 ///
 /// ```dart
-/// Future<void> _neverSatisfied() async {
+/// Future<void> _showMyDialog() async {
 ///   return showDialog<void>(
 ///     context: context,
 ///     barrierDismissible: false, // user must tap button!
 ///     builder: (BuildContext context) {
 ///       return AlertDialog(
-///         title: Text('Rewind and remember'),
+///         title: Text('AlertDialog Title'),
 ///         content: SingleChildScrollView(
 ///           child: ListBody(
 ///             children: <Widget>[
-///               Text('You will never be satisfied.'),
-///               Text('You\’re like me. I’m never satisfied.'),
+///               Text('This is a demo alert dialog.'),
+///               Text('Would you like to approve of this message?'),
 ///             ],
 ///           ),
 ///         ),
 ///         actions: <Widget>[
 ///           FlatButton(
-///             child: Text('Regret'),
+///             child: Text('Approve'),
 ///             onPressed: () {
 ///               Navigator.of(context).pop();
 ///             },
@@ -452,6 +454,8 @@ class SimpleDialogOption extends StatelessWidget {
 /// Typically passed as the child widget to [showDialog], which displays the
 /// dialog.
 ///
+/// {@animation 350 622 https://flutter.github.io/assets-for-api-docs/assets/material/simple_dialog.mp4}
+///
 /// {@tool sample}
 ///
 /// In this example, the user is asked to select between two options. These

packages/flutter/lib/src/material/divider.dart

@@ -22,6 +22,49 @@ import 'theme.dart';
 /// The box's total height is controlled by [height]. The appropriate
 /// padding is automatically computed from the height.
 ///
+/// {@tool snippet --template=stateless_widget_scaffold}
+///
+/// This sample shows how to display a Divider between an orange and blue box
+/// inside a column. The Divider is 20 logical pixels in height and contains a
+/// vertically centered black line that is 5 logical pixels thick. The black
+/// line is indented by 20 logical pixels.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/divider.png)
+///
+/// ```dart
+/// Widget build(BuildContext context) {
+///   return Center(
+///     child: Column(
+///       children: <Widget>[
+///         Expanded(
+///           child: Container(
+///             color: Colors.amber,
+///             child: const Center(
+///               child: Text('Above'),
+///             ),
+///           ),
+///         ),
+///         const Divider(
+///           color: Colors.black,
+///           height: 20,
+///           thickness: 5,
+///           indent: 20,
+///           endIndent: 0,
+///         ),
+///         Expanded(
+///           child: Container(
+///             color: Colors.blue,
+///             child: const Center(
+///               child: Text('Below'),
+///             ),
+///           ),
+///         ),
+///       ],
+///     ),
+///   );
+/// }
+/// ```
+/// {@end-tool}
 /// See also:
 ///
 ///  * [PopupMenuDivider], which is the equivalent but for popup menus.

packages/flutter/lib/src/material/input_decorator.dart

@@ -2304,6 +2304,94 @@ class _InputDecoratorState extends State<InputDecorator> with TickerProviderStat
 /// to describe their decoration. (In fact, this class is merely the
 /// configuration of an [InputDecorator], which does all the heavy lifting.)
 ///
+/// {@tool snippet --template=stateless_widget_scaffold}
+///
+/// This sample shows how to style a `TextField` using an `InputDecorator`. The
+/// TextField displays a "send message" icon to the left of the input area,
+/// which is surrounded by a border an all sides. It displays the `hintText`
+/// inside the input area to help the user understand what input is required. It
+/// displays the `helperText` and `counterText` below the input area.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/input_decoration.png)
+///
+/// ```dart
+/// Widget build(BuildContext context) {
+///   return TextField(
+///     decoration: InputDecoration(
+///       icon: Icon(Icons.send),
+///       hintText: 'Hint Text',
+///       helperText: 'Helper Text',
+///       counterText: '0 characters',
+///       border: const OutlineInputBorder(),
+///     ),
+///   );
+/// }
+/// ```
+/// {@end-tool}
+///
+/// {@tool snippet --template=stateless_widget_scaffold}
+///
+/// This sample shows how to style a "collapsed" `TextField` using an
+/// `InputDecorator`. The collapsed `TextField` surrounds the hint text and
+/// input area with a border, but does not add padding around them.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/input_decoration_collapsed.png)
+///
+/// ```dart
+/// Widget build(BuildContext context) {
+///   return TextField(
+///     decoration: InputDecoration.collapsed(
+///       hintText: 'Hint Text',
+///       border: OutlineInputBorder(),
+///     ),
+///   );
+/// }
+/// ```
+/// {@end-tool}
+///
+/// {@tool snippet --template=stateless_widget_scaffold}
+///
+/// This sample shows how to create a `TextField` with hint text, a red border
+/// on all sides, and an error message. To display a red border and error
+/// message, provide `errorText` to the `InputDecoration` constructor.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/input_decoration_error.png)
+///
+/// ```dart
+/// Widget build(BuildContext context) {
+///   return TextField(
+///     decoration: InputDecoration(
+///       hintText: 'Hint Text',
+///       errorText: 'Error Text',
+///       border: OutlineInputBorder(),
+///     ),
+///   );
+/// }
+/// ```
+/// {@end-tool}
+///
+/// {@tool snippet --template=stateless_widget_scaffold}
+///
+/// This sample shows how to style a `TextField` with a round border and
+/// additional text before and after the input area. It displays "Prefix" before
+/// the input area, and "Suffix" after the input area.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/material/input_decoration_prefix_suffix.png)
+///
+/// ```dart
+/// Widget build(BuildContext context) {
+///   return TextFormField(
+///     initialValue: 'abc',
+///     decoration: const InputDecoration(
+///       prefix: Text('Prefix'),
+///       suffix: Text('Suffix'),
+///       border: OutlineInputBorder(),
+///     ),
+///   );
+/// }
+/// ```
+/// {@end-tool}
+///
 /// See also:
 ///
 ///  * [TextField], which is a text input widget that uses an

packages/flutter/lib/src/material/scaffold.dart

@@ -1815,6 +1815,47 @@ class ScaffoldState extends State<Scaffold> with TickerProviderStateMixin {
   /// of the app. Modal bottom sheets can be created and displayed with the
   /// [showModalBottomSheet] function.
   ///
+  /// {@animation 350 622 https://flutter.github.io/assets-for-api-docs/assets/material/show_bottom_sheet.mp4}
+  ///
+  /// {@tool snippet --template=stateless_widget_scaffold}
+  ///
+  /// This example demonstrates how to use `showBottomSheet` to display a
+  /// bottom sheet when a user taps a button. It also demonstrates how to
+  /// close a bottom sheet using the Navigator.
+  ///
+  /// ```dart
+  /// Widget build(BuildContext context) {
+  ///   return Center(
+  ///     child: RaisedButton(
+  ///       child: const Text('showBottomSheet'),
+  ///       onPressed: () {
+  ///         Scaffold.of(context).showBottomSheet<void>(
+  ///           (BuildContext context) {
+  ///             return Container(
+  ///               height: 200,
+  ///               color: Colors.amber,
+  ///               child: Center(
+  ///                 child: Column(
+  ///                   mainAxisAlignment: MainAxisAlignment.center,
+  ///                   mainAxisSize: MainAxisSize.min,
+  ///                   children: <Widget>[
+  ///                     const Text('BottomSheet'),
+  ///                     RaisedButton(
+  ///                       child: const Text('Close BottomSheet'),
+  ///                       onPressed: () => Navigator.pop(context),
+  ///                     )
+  ///                   ],
+  ///                 ),
+  ///               ),
+  ///             );
+  ///           },
+  ///         );
+  ///       },
+  ///     ),
+  ///   );
+  /// }
+  /// ```
+  /// {@end-tool}
   /// See also:
   ///
   ///  * [BottomSheet], which becomes the parent of the widget returned by the

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

@@ -337,27 +337,112 @@ typedef AsyncWidgetBuilder<T> = Widget Function(BuildContext context, AsyncSnaps
 /// as the builder will always be called before the stream listener has a chance
 /// to be processed.
 ///
-/// {@tool sample}
+/// {@animation 200 150 https://flutter.github.io/assets-for-api-docs/assets/widgets/stream_builder.mp4}
 ///
-/// This sample shows a [StreamBuilder] configuring a text label to show the
-/// latest bid received for a lot in an auction. Assume the `_lot` field is
-/// set by a selector elsewhere in the UI.
+/// {@animation 200 150 https://flutter.github.io/assets-for-api-docs/assets/widgets/stream_builder_error.mp4}
+///
+/// {@tool snippet --template=stateful_widget_material}
+///
+/// This sample shows a [StreamBuilder] that listens to a Stream that emits bids
+/// for an auction. Every time the StreamBuilder receives a bid from the Stream,
+/// it will display the price of the bid below an icon. If the Stream emits an
+/// error, the error is displayed below an error icon. When the Stream finishes
+/// emitting bids, the final price is displayed.
 ///
 /// ```dart
-/// StreamBuilder<int>(
-///   stream: _lot?.bids, // a Stream<int> or null
-///   builder: (BuildContext context, AsyncSnapshot<int> snapshot) {
-///     if (snapshot.hasError)
-///       return Text('Error: ${snapshot.error}');
-///     switch (snapshot.connectionState) {
-///       case ConnectionState.none: return Text('Select lot');
-///       case ConnectionState.waiting: return Text('Awaiting bids...');
-///       case ConnectionState.active: return Text('\$${snapshot.data}');
-///       case ConnectionState.done: return Text('\$${snapshot.data} (closed)');
-///     }
-///     return null; // unreachable
-///   },
-/// )
+/// Stream<int> _bids = (() async* {
+///   await Future<void>.delayed(Duration(seconds: 1));
+///   yield 1;
+///   await Future<void>.delayed(Duration(seconds: 1));
+/// })();
+///
+/// Widget build(BuildContext context) {
+///   return Container(
+///     alignment: FractionalOffset.center,
+///     color: Colors.white,
+///     child: StreamBuilder<int>(
+///       stream: _bids,
+///       builder: (BuildContext context, AsyncSnapshot<int> snapshot) {
+///         List<Widget> children;
+///
+///         if (snapshot.hasError) {
+///           children = <Widget>[
+///             Icon(
+///               Icons.error_outline,
+///               color: Colors.red,
+///               size: 60,
+///             ),
+///             Padding(
+///               padding: const EdgeInsets.only(top: 16),
+///               child: Text('Error: ${snapshot.error}'),
+///             )
+///           ];
+///         } else {
+///           switch (snapshot.connectionState) {
+///             case ConnectionState.none:
+///               children = <Widget>[
+///                 Icon(
+///                   Icons.info,
+///                   color: Colors.blue,
+///                   size: 60,
+///                 ),
+///                 const Padding(
+///                   padding: EdgeInsets.only(top: 16),
+///                   child: Text('Select a lot'),
+///                 )
+///               ];
+///               break;
+///             case ConnectionState.waiting:
+///               children = <Widget>[
+///                 SizedBox(
+///                   child: const CircularProgressIndicator(),
+///                   width: 60,
+///                   height: 60,
+///                 ),
+///                 const Padding(
+///                   padding: EdgeInsets.only(top: 16),
+///                   child: Text('Awaiting bids...'),
+///                 )
+///               ];
+///               break;
+///             case ConnectionState.active:
+///               children = <Widget>[
+///                 Icon(
+///                   Icons.check_circle_outline,
+///                   color: Colors.green,
+///                   size: 60,
+///                 ),
+///                 Padding(
+///                   padding: const EdgeInsets.only(top: 16),
+///                   child: Text('\$${snapshot.data}'),
+///                 )
+///               ];
+///               break;
+///             case ConnectionState.done:
+///               children = <Widget>[
+///                 Icon(
+///                   Icons.info,
+///                   color: Colors.blue,
+///                   size: 60,
+///                 ),
+///                 Padding(
+///                   padding: const EdgeInsets.only(top: 16),
+///                   child: Text('\$${snapshot.data} (closed)'),
+///                 )
+///               ];
+///               break;
+///           }
+///         }
+///
+///         return Column(
+///           mainAxisAlignment: MainAxisAlignment.center,
+///           crossAxisAlignment: CrossAxisAlignment.center,
+///           children: children,
+///         );
+///       },
+///     ),
+///   );
+/// }
 /// ```
 /// {@end-tool}
 ///

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

@@ -4994,6 +4994,12 @@ class Flow extends MultiChildRenderObjectWidget {
 ///
 /// {@tool sample}
 ///
+/// This sample demonstrates how to mix and match text with different text
+/// styles using the [RichText] Widget. It displays the text "Hello bold world,"
+/// emphasizing the word "bold" using a bold font weight.
+///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/widgets/rich_text.png)
+///
 /// ```dart
 /// RichText(
 ///   text: TextSpan(

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

@@ -88,6 +88,8 @@ import 'scrollable.dart';
 /// in both cases the "available space" is infinite (since this is in a viewport).
 /// The next section describes a technique for providing a maximum height constraint.
 ///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/widgets/single_child_scroll_view_fixed.png)
+///
 /// ```dart
 /// Widget build(BuildContext context) {
 ///   return LayoutBuilder(
@@ -151,6 +153,8 @@ import 'scrollable.dart';
 /// In this example, the column becomes either as big as viewport, or as big as
 /// the contents, whichever is biggest.
 ///
+/// ![](https://flutter.github.io/assets-for-api-docs/assets/widgets/single_child_scroll_view_expanded.png)
+///
 /// ```dart
 /// Widget build(BuildContext context) {
 ///   return LayoutBuilder(