Factor out BorderSide creation for dividers (#15403)

This allows other code to get the same style without having to know exactly it is computed.

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

@@ -11,6 +11,7 @@ import 'package:flutter/widgets.dart';
 import 'checkbox.dart';
 import 'colors.dart';
 import 'debug.dart';
+import 'divider.dart';
 import 'dropdown.dart';
 import 'icons.dart';
 import 'ink_well.dart';
@@ -500,12 +501,12 @@ class DataTable extends StatelessWidget {
 
     final ThemeData theme = Theme.of(context);
     final BoxDecoration _kSelectedDecoration = new BoxDecoration(
-      border: new Border(bottom: new BorderSide(color: theme.dividerColor)),
+      border: new Border(bottom: Divider.createBorderSide(context, width: 1.0)),
       // The backgroundColor has to be transparent so you can see the ink on the material
       color: (Theme.of(context).brightness == Brightness.light) ? _kGrey100Opacity : _kGrey300Opacity,
     );
     final BoxDecoration _kUnselectedDecoration = new BoxDecoration(
-      border: new Border(bottom: new BorderSide(color: theme.dividerColor)),
+      border: new Border(bottom: Divider.createBorderSide(context, width: 1.0)),
     );
 
     final bool showCheckboxColumn = rows.any((DataRow row) => row.onSelectChanged != null);

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

@@ -52,13 +52,47 @@ class Divider extends StatelessWidget {
   /// Defaults to the current theme's divider color, given by
   /// [ThemeData.dividerColor].
   ///
+  /// ## Sample code
+  ///
   /// ```dart
-  ///  new Divider(
-  ///    color: Colors.deepOrange,
-  ///  ),
+  /// new Divider(
+  ///   color: Colors.deepOrange,
+  /// )
   /// ```
   final Color color;
 
+  /// Computes the [BorderSide] that represents a divider of the specified
+  /// color, or, if there is no specified color, of the default
+  /// [ThemeData.dividerColor] specified in the ambient [Theme].
+  ///
+  /// The `width` argument can be used to override the default width of the
+  /// divider border, which is usually 0.0 (a hairline border).
+  ///
+  /// ## Sample code
+  ///
+  /// This example uses this method to create a box that has a divider above and
+  /// below it. This is sometimes useful with lists, for instance, to separate a
+  /// scrollable section from the rest of the interface.
+  ///
+  /// ```dart
+  /// new DecoratedBox(
+  ///   decoration: new BoxDecoration(
+  ///     border: new Border(
+  ///       top: Divider.createBorderSide(context),
+  ///       bottom: Divider.createBorderSide(context),
+  ///     ),
+  ///   ),
+  ///   // child: ...
+  /// )
+  /// ```
+  static BorderSide createBorderSide(BuildContext context, { Color color, double width: 0.0 }) {
+    assert(width != null);
+    return new BorderSide(
+      color: color ?? Theme.of(context).dividerColor,
+      width: width,
+    );
+  }
+
   @override
   Widget build(BuildContext context) {
     return new SizedBox(
@@ -69,10 +103,7 @@ class Divider extends StatelessWidget {
           margin: new EdgeInsetsDirectional.only(start: indent),
           decoration: new BoxDecoration(
             border: new Border(
-              bottom: new BorderSide(
-                color: color ?? Theme.of(context).dividerColor,
-                width: 0.0,
-              ),
+              bottom: createBorderSide(context, color: color),
             ),
           ),
         ),

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

@@ -6,6 +6,7 @@ import 'package:flutter/foundation.dart';
 import 'package:flutter/widgets.dart';
 
 import 'debug.dart';
+import 'divider.dart';
 import 'theme.dart';
 
 const double _kDrawerHeaderHeight = 160.0 + 1.0; // bottom edge
@@ -82,10 +83,7 @@ class DrawerHeader extends StatelessWidget {
       margin: margin,
       decoration: new BoxDecoration(
         border: new Border(
-          bottom: new BorderSide(
-            color: theme.dividerColor,
-            width: 0.0,
-          ),
+          bottom: Divider.createBorderSide(context),
         ),
       ),
       child: new AnimatedContainer(

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

@@ -8,6 +8,7 @@ import 'package:flutter/widgets.dart';
 import 'colors.dart';
 import 'constants.dart';
 import 'debug.dart';
+import 'divider.dart';
 import 'ink_well.dart';
 import 'theme.dart';
 
@@ -284,19 +285,20 @@ class ListTile extends StatelessWidget {
     assert(tiles != null);
     assert(color != null || context != null);
 
-    final Color dividerColor = color ?? Theme.of(context).dividerColor;
     final Iterator<Widget> iterator = tiles.iterator;
     final bool isNotEmpty = iterator.moveNext();
 
+    final Decoration decoration = new BoxDecoration(
+      border: new Border(
+        bottom: Divider.createBorderSide(context, color: color),
+      ),
+    );
+
     Widget tile = iterator.current;
     while (iterator.moveNext()) {
       yield new DecoratedBox(
         position: DecorationPosition.foreground,
-        decoration: new BoxDecoration(
-          border: new Border(
-            bottom: new BorderSide(color: dividerColor, width: 0.0),
-          ),
-        ),
+        decoration: decoration,
         child: tile,
       );
       tile = iterator.current;

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

@@ -8,6 +8,7 @@ import 'package:flutter/foundation.dart';
 import 'package:flutter/rendering.dart';
 import 'package:flutter/widgets.dart';
 
+import 'divider.dart';
 import 'material.dart';
 import 'shadows.dart';
 import 'theme.dart';
@@ -553,9 +554,9 @@ class _MergeableMaterialState extends State<MergeableMaterial> with TickerProvid
           final bool hasBottomDivider = _willNeedDivider(i + 1);
 
           Border border;
-          final BorderSide divider = new BorderSide(
-            color: Theme.of(context).dividerColor,
-            width: 0.5
+          final BorderSide divider = Divider.createBorderSide(
+            context,
+            width: 0.5, // TODO(ianh): This probably looks terrible when the dpr isn't a power of two.
           );
 
           if (i == 0) {

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

@@ -14,6 +14,7 @@ import 'app_bar.dart';
 import 'bottom_sheet.dart';
 import 'button_bar.dart';
 import 'button_theme.dart';
+import 'divider.dart';
 import 'drawer.dart';
 import 'flexible_space_bar.dart';
 import 'material.dart';
@@ -1181,9 +1182,7 @@ class ScaffoldState extends State<Scaffold> with TickerProviderStateMixin {
         new Container(
           decoration: new BoxDecoration(
             border: new Border(
-              top: new BorderSide(
-                color: themeData.dividerColor
-              ),
+              top: Divider.createBorderSide(context, width: 1.0),
             ),
           ),
           child: new SafeArea(

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

@@ -362,6 +362,9 @@ class ThemeData extends Diagnosticable {
 
   /// The color of [Divider]s and [PopupMenuDivider]s, also used
   /// between [ListTile]s, between rows in [DataTable]s, and so forth.
+  ///
+  /// To create an appropriate [BorderSide] that uses this color, consider
+  /// [Divider.createBorderSide].
   final Color dividerColor;
 
   /// The highlight color used during ink splash animations or to