[Material] Create a Navigation Rail component and theme (#49574)

packages/flutter/lib/material.dart

@@ -81,6 +81,8 @@ export 'src/material/material_button.dart';
 export 'src/material/material_localizations.dart';
 export 'src/material/material_state.dart';
 export 'src/material/mergeable_material.dart';
+export 'src/material/navigation_rail.dart';
+export 'src/material/navigation_rail_theme.dart';
 export 'src/material/outline_button.dart';
 export 'src/material/page.dart';
 export 'src/material/page_transitions_theme.dart';

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

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:ui' show lerpDouble;
+
+import 'package:flutter/foundation.dart';
+import 'package:flutter/rendering.dart';
+import 'package:flutter/widgets.dart';
+
+import 'navigation_rail.dart';
+import 'theme.dart';
+import 'theme_data.dart';
+
+/// Defines default property values for descendant [NavigationRail]
+/// widgets.
+///
+/// Descendant widgets obtain the current [NavigationRailThemeData] object
+/// using `NavigationRailTheme.of(context)`. Instances of
+/// [NavigationRailThemeData] can be customized with
+/// [NavigationRailThemeData.copyWith].
+///
+/// Typically a [NavigationRailThemeData] is specified as part of the
+/// overall [Theme] with [ThemeData.navigationRailTheme].
+///
+/// All [NavigationRailThemeData] properties are `null` by default.
+/// When null, the [NavigationRail] will use the values from [ThemeData]
+/// if they exist, otherwise it will provide its own defaults based on the
+/// overall [Theme]'s textTheme and colorScheme. See the individual
+/// [NavigationRail] properties for details.
+///
+/// See also:
+///
+///  * [ThemeData], which describes the overall theme information for the
+///    application.
+class NavigationRailThemeData with Diagnosticable {
+  /// Creates a theme that can be used for [ThemeData.navigationRailTheme].
+  const NavigationRailThemeData({
+    this.backgroundColor,
+    this.elevation,
+    this.unselectedLabelTextStyle,
+    this.selectedLabelTextStyle,
+    this.unselectedIconTheme,
+    this.selectedIconTheme,
+    this.groupAlignment,
+    this.labelType,
+  });
+
+  /// Color to be used for the [NavigationRail]'s background.
+  final Color backgroundColor;
+
+  /// The z-coordinate to be used for the [NavigationRail]'s elevation.
+  final double elevation;
+
+  /// The style to merge with the default text style for
+  /// [NavigationRailDestination] labels, when the destination is not selected.
+  final TextStyle unselectedLabelTextStyle;
+
+  /// The style to merge with the default text style for
+  /// [NavigationRailDestination] labels, when the destination is selected.
+  final TextStyle selectedLabelTextStyle;
+
+  /// The theme to merge with the default icon theme for
+  /// [NavigationRailDestination] icons, when the destination is not selected.
+  final IconThemeData unselectedIconTheme;
+
+  /// The theme to merge with the default icon theme for
+  /// [NavigationRailDestination] icons, when the destination is selected.
+  final IconThemeData selectedIconTheme;
+
+  /// The alignment for the [NavigationRailDestination]s as they are positioned
+  /// within the [NavigationRail].
+  final double groupAlignment;
+
+  /// The type that defines the layout and behavior of the labels in the
+  /// [NavigationRail].
+  final NavigationRailLabelType labelType;
+
+  /// Creates a copy of this object with the given fields replaced with the
+  /// new values.
+  NavigationRailThemeData copyWith({
+    Color backgroundColor,
+    double elevation,
+    TextStyle unselectedLabelTextStyle,
+    TextStyle selectedLabelTextStyle,
+    IconThemeData unselectedIconTheme,
+    IconThemeData selectedIconTheme,
+    double groupAlignment,
+    NavigationRailLabelType labelType,
+  }) {
+    return NavigationRailThemeData(
+      backgroundColor: backgroundColor ?? this.backgroundColor,
+      elevation: elevation ?? this.elevation,
+      unselectedLabelTextStyle: unselectedLabelTextStyle ?? this.unselectedLabelTextStyle,
+      selectedLabelTextStyle: selectedLabelTextStyle ?? this.selectedLabelTextStyle,
+      unselectedIconTheme: unselectedIconTheme ?? this.unselectedIconTheme,
+      selectedIconTheme: selectedIconTheme ?? this.selectedIconTheme,
+      groupAlignment: groupAlignment ?? this.groupAlignment,
+      labelType: labelType ?? this.labelType,
+    );
+  }
+
+  /// Linearly interpolate between two navigation rail themes.
+  ///
+  /// If both arguments are null then null is returned.
+  ///
+  /// {@macro dart.ui.shadow.lerp}
+  static NavigationRailThemeData lerp(NavigationRailThemeData a, NavigationRailThemeData b, double t) {
+    assert(t != null);
+    if (a == null && b == null)
+      return null;
+    return NavigationRailThemeData(
+      backgroundColor: Color.lerp(a?.backgroundColor, b?.backgroundColor, t),
+      elevation: lerpDouble(a?.elevation, b?.elevation, t),
+      unselectedLabelTextStyle: TextStyle.lerp(a?.unselectedLabelTextStyle, b?.unselectedLabelTextStyle, t),
+      selectedLabelTextStyle: TextStyle.lerp(a?.selectedLabelTextStyle, b?.selectedLabelTextStyle, t),
+      unselectedIconTheme: IconThemeData.lerp(a?.unselectedIconTheme, b?.unselectedIconTheme, t),
+      selectedIconTheme: IconThemeData.lerp(a?.selectedIconTheme, b?.selectedIconTheme, t),
+      groupAlignment: lerpDouble(a?.groupAlignment, b?.groupAlignment, t),
+      labelType: t < 0.5 ? a?.labelType : b?.labelType,
+    );
+  }
+
+  @override
+  int get hashCode {
+    return hashValues(
+      backgroundColor,
+      elevation,
+      unselectedLabelTextStyle,
+      selectedLabelTextStyle,
+      unselectedIconTheme,
+      selectedIconTheme,
+      groupAlignment,
+      labelType,
+    );
+  }
+
+  @override
+  bool operator ==(Object other) {
+    if (identical(this, other))
+      return true;
+    if (other.runtimeType != runtimeType)
+      return false;
+    return other is NavigationRailThemeData
+        && other.backgroundColor == backgroundColor
+        && other.elevation == elevation
+        && other.unselectedLabelTextStyle == unselectedLabelTextStyle
+        && other.selectedLabelTextStyle == selectedLabelTextStyle
+        && other.unselectedIconTheme == unselectedIconTheme
+        && other.selectedIconTheme == selectedIconTheme
+        && other.groupAlignment == groupAlignment
+        && other.labelType == labelType;
+  }
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    const NavigationRailThemeData defaultData = NavigationRailThemeData();
+
+    properties.add(ColorProperty('backgroundColor', backgroundColor, defaultValue: defaultData.backgroundColor));
+    properties.add(DoubleProperty('elevation', elevation, defaultValue: defaultData.elevation));
+    properties.add(DiagnosticsProperty<TextStyle>('unselectedLabelTextStyle', unselectedLabelTextStyle, defaultValue: defaultData.unselectedLabelTextStyle));
+    properties.add(DiagnosticsProperty<TextStyle>('selectedLabelTextStyle', selectedLabelTextStyle, defaultValue: defaultData.selectedLabelTextStyle));
+    properties.add(DiagnosticsProperty<IconThemeData>('unselectedIconTheme', unselectedIconTheme, defaultValue: defaultData.unselectedIconTheme));
+    properties.add(DiagnosticsProperty<IconThemeData>('selectedIconTheme', selectedIconTheme, defaultValue: defaultData.selectedIconTheme));
+    properties.add(DoubleProperty('groupAlignment', groupAlignment, defaultValue: defaultData.groupAlignment));
+    properties.add(DiagnosticsProperty<NavigationRailLabelType>('labelType', labelType, defaultValue: defaultData.labelType));
+  }
+}
+
+/// An inherited widget that defines visual properties for [NavigationRail]s and
+/// [NavigationRailDestination]s in this widget's subtree.
+///
+/// Values specified here are used for [NavigationRail] properties that are not
+/// given an explicit non-null value.
+class NavigationRailTheme extends InheritedTheme {
+  /// Creates a navigation rail theme that controls the
+  /// [NavigationRailThemeData] properties for a [NavigationRail].
+  ///
+  /// The data argument must not be null.
+  const NavigationRailTheme({
+    Key key,
+    @required this.data,
+    Widget child,
+  }) : assert(data != null), super(key: key, child: child);
+
+  /// Specifies the background color, elevation, label text style, icon theme,
+  /// group alignment, and label type and border values for descendant
+  /// [NavigationRail] widgets.
+  final NavigationRailThemeData data;
+
+  /// The closest instance of this class that encloses the given context.
+  ///
+  /// If there is no enclosing [NavigationRailTheme] widget, then
+  /// [ThemeData.navigationRailTheme] is used.
+  ///
+  /// Typical usage is as follows:
+  ///
+  /// ```dart
+  /// NavigationRailTheme theme = NavigationRailTheme.of(context);
+  /// ```
+  static NavigationRailThemeData of(BuildContext context) {
+    final NavigationRailTheme navigationRailTheme = context.dependOnInheritedWidgetOfExactType<NavigationRailTheme>();
+    return navigationRailTheme?.data ?? Theme.of(context).navigationRailTheme;
+  }
+
+  @override
+  Widget wrap(BuildContext context, Widget child) {
+    final NavigationRailTheme ancestorTheme = context.findAncestorWidgetOfExactType<NavigationRailTheme>();
+    return identical(this, ancestorTheme) ? child : NavigationRailTheme(data: data, child: child);
+  }
+
+  @override
+  bool updateShouldNotify(NavigationRailTheme oldWidget) => data != oldWidget.data;
+}

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

@@ -25,6 +25,7 @@ import 'floating_action_button_theme.dart';
 import 'ink_splash.dart';
 import 'ink_well.dart' show InteractiveInkFeatureFactory;
 import 'input_decorator.dart';
+import 'navigation_rail_theme.dart';
 import 'page_transitions_theme.dart';
 import 'popup_menu_theme.dart';
 import 'slider_theme.dart';
@@ -256,6 +257,7 @@ class ThemeData with Diagnosticable {
     ColorScheme colorScheme,
     DialogTheme dialogTheme,
     FloatingActionButtonThemeData floatingActionButtonTheme,
+    NavigationRailThemeData navigationRailTheme,
     Typography typography,
     CupertinoThemeData cupertinoOverrideTheme,
     SnackBarThemeData snackBarTheme,
@@ -364,6 +366,7 @@ class ThemeData with Diagnosticable {
     );
     dialogTheme ??= const DialogTheme();
     floatingActionButtonTheme ??= const FloatingActionButtonThemeData();
+    navigationRailTheme ??= const NavigationRailThemeData();
     cupertinoOverrideTheme = cupertinoOverrideTheme?.noDefault();
     snackBarTheme ??= const SnackBarThemeData();
     bottomSheetTheme ??= const BottomSheetThemeData();
@@ -428,6 +431,7 @@ class ThemeData with Diagnosticable {
       colorScheme: colorScheme,
       dialogTheme: dialogTheme,
       floatingActionButtonTheme: floatingActionButtonTheme,
+      navigationRailTheme: navigationRailTheme,
       typography: typography,
       cupertinoOverrideTheme: cupertinoOverrideTheme,
       snackBarTheme: snackBarTheme,
@@ -505,6 +509,7 @@ class ThemeData with Diagnosticable {
     @required this.colorScheme,
     @required this.dialogTheme,
     @required this.floatingActionButtonTheme,
+    @required this.navigationRailTheme,
     @required this.typography,
     @required this.cupertinoOverrideTheme,
     @required this.snackBarTheme,
@@ -566,6 +571,7 @@ class ThemeData with Diagnosticable {
        assert(colorScheme != null),
        assert(dialogTheme != null),
        assert(floatingActionButtonTheme != null),
+       assert(navigationRailTheme != null),
        assert(typography != null),
        assert(snackBarTheme != null),
        assert(bottomSheetTheme != null),
@@ -982,6 +988,10 @@ class ThemeData with Diagnosticable {
   /// [FloatingActionButton].
   final FloatingActionButtonThemeData floatingActionButtonTheme;
 
+  /// A theme for customizing the background color, elevation, text style, and
+  /// icon themes of a [NavigationRail].
+  final NavigationRailThemeData navigationRailTheme;
+
   /// The color and geometry [TextTheme] values used to configure [textTheme],
   /// [primaryTextTheme], and [accentTextTheme].
   final Typography typography;
@@ -1072,6 +1082,7 @@ class ThemeData with Diagnosticable {
     ColorScheme colorScheme,
     DialogTheme dialogTheme,
     FloatingActionButtonThemeData floatingActionButtonTheme,
+    NavigationRailThemeData navigationRailTheme,
     Typography typography,
     CupertinoThemeData cupertinoOverrideTheme,
     SnackBarThemeData snackBarTheme,
@@ -1138,6 +1149,7 @@ class ThemeData with Diagnosticable {
       colorScheme: colorScheme ?? this.colorScheme,
       dialogTheme: dialogTheme ?? this.dialogTheme,
       floatingActionButtonTheme: floatingActionButtonTheme ?? this.floatingActionButtonTheme,
+      navigationRailTheme: navigationRailTheme ?? this.navigationRailTheme,
       typography: typography ?? this.typography,
       cupertinoOverrideTheme: cupertinoOverrideTheme ?? this.cupertinoOverrideTheme,
       snackBarTheme: snackBarTheme ?? this.snackBarTheme,
@@ -1282,6 +1294,7 @@ class ThemeData with Diagnosticable {
       colorScheme: ColorScheme.lerp(a.colorScheme, b.colorScheme, t),
       dialogTheme: DialogTheme.lerp(a.dialogTheme, b.dialogTheme, t),
       floatingActionButtonTheme: FloatingActionButtonThemeData.lerp(a.floatingActionButtonTheme, b.floatingActionButtonTheme, t),
+      navigationRailTheme: NavigationRailThemeData.lerp(a.navigationRailTheme, b.navigationRailTheme, t),
       typography: Typography.lerp(a.typography, b.typography, t),
       cupertinoOverrideTheme: t < 0.5 ? a.cupertinoOverrideTheme : b.cupertinoOverrideTheme,
       snackBarTheme: SnackBarThemeData.lerp(a.snackBarTheme, b.snackBarTheme, t),
@@ -1354,6 +1367,7 @@ class ThemeData with Diagnosticable {
         && other.colorScheme == colorScheme
         && other.dialogTheme == dialogTheme
         && other.floatingActionButtonTheme == floatingActionButtonTheme
+        && other.navigationRailTheme == navigationRailTheme
         && other.typography == typography
         && other.cupertinoOverrideTheme == cupertinoOverrideTheme
         && other.snackBarTheme == snackBarTheme
@@ -1425,6 +1439,7 @@ class ThemeData with Diagnosticable {
       colorScheme,
       dialogTheme,
       floatingActionButtonTheme,
+      navigationRailTheme,
       typography,
       cupertinoOverrideTheme,
       snackBarTheme,
@@ -1492,6 +1507,7 @@ class ThemeData with Diagnosticable {
     properties.add(DiagnosticsProperty<ColorScheme>('colorScheme', colorScheme, defaultValue: defaultData.colorScheme, level: DiagnosticLevel.debug));
     properties.add(DiagnosticsProperty<DialogTheme>('dialogTheme', dialogTheme, defaultValue: defaultData.dialogTheme, level: DiagnosticLevel.debug));
     properties.add(DiagnosticsProperty<FloatingActionButtonThemeData>('floatingActionButtonThemeData', floatingActionButtonTheme, defaultValue: defaultData.floatingActionButtonTheme, level: DiagnosticLevel.debug));
+    properties.add(DiagnosticsProperty<NavigationRailThemeData>('navigationRailThemeData', navigationRailTheme, defaultValue: defaultData.navigationRailTheme, level: DiagnosticLevel.debug));
     properties.add(DiagnosticsProperty<Typography>('typography', typography, defaultValue: defaultData.typography, level: DiagnosticLevel.debug));
     properties.add(DiagnosticsProperty<CupertinoThemeData>('cupertinoOverrideTheme', cupertinoOverrideTheme, defaultValue: defaultData.cupertinoOverrideTheme, level: DiagnosticLevel.debug));
     properties.add(DiagnosticsProperty<SnackBarThemeData>('snackBarTheme', snackBarTheme, defaultValue: defaultData.snackBarTheme, level: DiagnosticLevel.debug));

packages/flutter/test/material/theme_data_test.dart

@@ -256,6 +256,7 @@ void main() {
       colorScheme: const ColorScheme.light(),
       dialogTheme: const DialogTheme(backgroundColor: Colors.black),
       floatingActionButtonTheme: const FloatingActionButtonThemeData(backgroundColor: Colors.black),
+      navigationRailTheme: const NavigationRailThemeData(backgroundColor: Colors.black),
       typography: Typography.material2018(platform: TargetPlatform.android),
       cupertinoOverrideTheme: null,
       snackBarTheme: const SnackBarThemeData(backgroundColor: Colors.black),
@@ -335,6 +336,7 @@ void main() {
       colorScheme: const ColorScheme.light(),
       dialogTheme: const DialogTheme(backgroundColor: Colors.white),
       floatingActionButtonTheme: const FloatingActionButtonThemeData(backgroundColor: Colors.white),
+      navigationRailTheme: const NavigationRailThemeData(backgroundColor: Colors.white),
       typography: Typography.material2018(platform: TargetPlatform.iOS),
       cupertinoOverrideTheme: ThemeData.light().cupertinoOverrideTheme,
       snackBarTheme: const SnackBarThemeData(backgroundColor: Colors.white),
@@ -400,6 +402,7 @@ void main() {
       colorScheme: otherTheme.colorScheme,
       dialogTheme: otherTheme.dialogTheme,
       floatingActionButtonTheme: otherTheme.floatingActionButtonTheme,
+      navigationRailTheme: otherTheme.navigationRailTheme,
       typography: otherTheme.typography,
       cupertinoOverrideTheme: otherTheme.cupertinoOverrideTheme,
       snackBarTheme: otherTheme.snackBarTheme,
@@ -466,6 +469,7 @@ void main() {
     expect(themeDataCopy.colorScheme, equals(otherTheme.colorScheme));
     expect(themeDataCopy.dialogTheme, equals(otherTheme.dialogTheme));
     expect(themeDataCopy.floatingActionButtonTheme, equals(otherTheme.floatingActionButtonTheme));
+    expect(themeDataCopy.navigationRailTheme, equals(otherTheme.navigationRailTheme));
     expect(themeDataCopy.typography, equals(otherTheme.typography));
     expect(themeDataCopy.cupertinoOverrideTheme, equals(otherTheme.cupertinoOverrideTheme));
     expect(themeDataCopy.snackBarTheme, equals(otherTheme.snackBarTheme));