Dynamic Date Picker Comparison Options

 - Allow user create their own comparison option
 - Provide default comparison options [previous period, previous year, custom]
 - New interface “SupportedComparisonOptions“ for MaterialDateRangePickerComponent
 - New interface “Disabled” for DateRangeInput

▶ Screencast - with default setting
  go/screencastlink/NTE2NzAyNTYwMTExODIwOHxkMjA3MjQ5My0wMw

▶ Screencast - with new option and no custom
  go/screencastlink/NTE0MzkwMTQ5NzE5NjU0NHxkNWY5MmY2Yy02YQ

(Demo code is not checked in, this is just showing how it looks like)

▶ Design doc: go/date-picker-comparison-options

PiperOrigin-RevId: 202718417

Author: Googler

lib/material_datepicker/comparison.dart

@@ -2,7 +2,7 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-import 'package:intl/intl.dart';
+import 'package:angular_components/material_datepicker/comparison_option.dart';
 import 'package:angular_components/material_datepicker/range.dart';
 import 'package:angular_components/model/date/date.dart';
 
@@ -15,14 +15,17 @@ class DatepickerComparison implements DateRangeComparison {
   /// The selected comparison range, if any.
   final DatepickerDateRange comparison;
 
+  DatepickerComparison(DatepickerDateRange range, ComparisonOption option)
+      : this.custom(range, option.computeComparisonRange(range));
+
   DatepickerComparison.noComparison(DatepickerDateRange range)
       : this.custom(range, null);
 
   DatepickerComparison.previousPeriod(DatepickerDateRange range)
-      : this.custom(range, _getPreviousRange(range));
+      : this(range, ComparisonOption.previousPeriod);
 
   DatepickerComparison.samePeriodLastYear(DatepickerDateRange range)
-      : this.custom(range, _getSamePeriodLastYearRange(range));
+      : this(range, ComparisonOption.samePeriodLastYear);
 
   /// Construct a copy of `original` clamped to the given `min`/`max` dates.
   /// Existing clamping is removed before the new clamping is applied.
@@ -34,12 +37,19 @@ class DatepickerComparison implements DateRangeComparison {
 
   bool get isComparisonEnabled => comparison != null;
 
+  @Deprecated('use comparesTo instead')
   bool comparesToPreviousPeriod() =>
-      comparison != null && rangeEqual(comparison, _getPreviousRange(range));
+      comparesTo(ComparisonOption.previousPeriod);
 
+  @Deprecated('use comparesTo instead')
   bool comparesToSamePeriodLastYear() =>
+      comparesTo(ComparisonOption.samePeriodLastYear);
+
+  /// Checks the comparison date range has same logic as given comparisonOption.
+  bool comparesTo(ComparisonOption option) =>
       comparison != null &&
-      comparison.unclamped() == _getSamePeriodLastYearRange(range);
+      comparison.unclamped() ==
+          option.computeComparisonRange(range.unclamped());
 
   bool operator ==(o) =>
       o is DatepickerComparison &&
@@ -49,32 +59,4 @@ class DatepickerComparison implements DateRangeComparison {
       ? rangeHash(range) ^ rangeHash(comparison)
       : rangeHash(range);
   String toString() => 'DatepickerComparison -- $range / $comparison';
-
-  /// If the previous date range has an interesting title like '3 weeks ago',
-  /// keep it; if it's the generic 'Custom' title, replace it with 'Previous
-  /// period'.
-  static DatepickerDateRange _getPreviousRange(DatepickerDateRange range) {
-    var prev = range.prev;
-    if (prev != null && !prev.isPredefined) {
-      return new DatepickerDateRange(_prevPeriodMsg(), prev.start, prev.end);
-    }
-    return prev;
-  }
-
-  static DatepickerDateRange _getSamePeriodLastYearRange(
-          DatepickerDateRange range) =>
-      new DatepickerDateRange(
-          _lastYearMsg(), range.start.add(years: -1), range.end.add(years: -1));
-
-  static String _prevPeriodMsg() => Intl.message('Previous period',
-      name: '_prevPeriodMsg',
-      meaning: 'Name of a date range',
-      desc: 'Generic name for the period before a time range. E.g. if someone '
-          'has selected the last 30 days, this represents the 30 days previous.');
-  static String _lastYearMsg() => Intl.message('Same period last year',
-      name: '_lastYearMsg',
-      meaning: 'Name of a date range',
-      desc: 'Generic name for a time period matching a selected date range, '
-          'but one year prior. E.g. if someone has selected Feb 2015, this '
-          'represents Feb 2014.');
 }

lib/material_datepicker/comparison_option.dart

@@ -0,0 +1,75 @@
+// Copyright (c) 2016, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:intl/intl.dart';
+import 'package:angular_components/material_datepicker/range.dart';
+
+/// Converts current date range to comparison date range.
+///
+/// Return null if this is a "custom".
+typedef DatepickerDateRange ComparisonFn(DatepickerDateRange range);
+
+/// The [ComparisonOption]s the component provides to the user by default.
+List<ComparisonOption> defaultComparisonOptions = [
+  ComparisonOption.previousPeriod,
+  ComparisonOption.samePeriodLastYear,
+  ComparisonOption.custom
+];
+
+/// Comparison option for comparing [DatepickerDateRange].
+class ComparisonOption {
+  /// The label to display for the preset (e.g. "Previous period").
+  final String displayName;
+
+  /// Get date shifting base on the given date range.
+  final ComparisonFn computeComparisonRange;
+
+  const ComparisonOption(this.displayName, this.computeComparisonRange);
+
+  static final ComparisonOption previousPeriod =
+      new ComparisonOption(_prevPeriodMsg, (DatepickerDateRange range) {
+    var prev = range.prev;
+    if (prev != null && !prev.isPredefined) {
+      return new DatepickerDateRange(_prevPeriodMsg, prev.start, prev.end);
+    }
+    return prev;
+  });
+
+  static final ComparisonOption samePeriodLastYear = new ComparisonOption(
+      _previousYearMsg,
+      (DatepickerDateRange range) => new DatepickerDateRange(_previousYearMsg,
+          range.start.add(years: -1), range.end.add(years: -1)));
+
+  static final ComparisonOption custom =
+      new ComparisonOption(_customMsg, (DatepickerDateRange range) => null);
+
+  static final String _prevPeriodMsg = Intl.message('Previous period',
+      name: '_prevPeriodMsg',
+      meaning: 'An option name, the date range before the selected date '
+          'range',
+      desc: 'Setting to compare the selected date range with the previous '
+          'period. E.g. if the selected range were May, this would be April'
+          '.');
+  static final String _previousYearMsg = Intl.message('Previous year',
+      name: '_previousYearMsg',
+      meaning: 'An option name, the same date range in the last year',
+      desc: 'Setting to compare the selected date range with the same range '
+          'last year. E.g. if the selected range were May 2015, this would'
+          ' be May 2014.');
+
+  static final String _customMsg = Intl.message('Custom',
+      name: '_customMsg',
+      meaning: 'An option name, user could enter the date range they want',
+      desc: 'Setting to compare the selected date range with another '
+          'arbitrary user-selected date range.');
+
+  bool operator ==(o) =>
+      o is ComparisonOption &&
+      this.displayName == o.displayName &&
+      this.computeComparisonRange == o.computeComparisonRange;
+
+  int get hashCode => displayName.hashCode ^ computeComparisonRange.hashCode;
+
+  String toString() => displayName;
+}

lib/material_datepicker/date_range_editor.dart

@@ -109,6 +109,9 @@ class DateRangeEditorComponent implements OnInit, AfterViewInit, Focusable {
 
   bool _supportsComparison = true;
 
+  /// Checks if custom comparison is a valid option.
+  bool get isCustomComparisonValid => model.isCustomComparisonValid;
+
   static final comparisonHeaderMsg = Intl.message('Compare',
       name: 'comparisonHeaderMsg',
       desc: 'Label for a toggle that turns time comparison on/off.');

lib/material_datepicker/date_range_editor.html

@@ -125,7 +125,8 @@
                       [isClearRangeSelected]="isClearRangeSelected"
                       [rangeId]="model.comparisonId"
                       [(state)]="model.calendar.value"
-                      [(range)]="model.comparison.value">
+                      [(range)]="model.comparison.value"
+                      [disabled]="!isCustomComparisonValid">
     </date-range-input>
   </div>
 

lib/material_datepicker/date_range_input.dart

@@ -39,6 +39,7 @@ import 'package:angular_components/model/observable/observable.dart';
                 [class.active]="isStartActive"
                 [(date)]="start"
                 (focus)="onStartFocused()"
+                [disabled]="disabled"
                 class="start date-input">
 </material-input>
 <span class="separator">—</span>
@@ -52,6 +53,7 @@ import 'package:angular_components/model/observable/observable.dart';
                 [(date)]="end"
                 [rangeEnd]="true"
                 (focus)="onEndFocused()"
+                [disabled]="disabled"
                 class="end date-input">
 </material-input>
 ''',
@@ -64,6 +66,17 @@ class DateRangeInputComponent implements OnInit, OnDestroy {
 
   DateRangeInputComponent(this._changeDetector);
 
+  /// Whether the input field is disabled.
+  ///
+  /// If true, the component disable both start and end input field.
+  @Input()
+  set disabled(bool isDisabled) {
+    _disabled = isDisabled;
+  }
+
+  bool get disabled => _disabled;
+  bool _disabled = false;
+
   @override
   void ngOnInit() {
     _calendarStream = _model.stream.listen(_onCalendarChange);
@@ -79,12 +92,18 @@ class DateRangeInputComponent implements OnInit, OnDestroy {
   }
 
   void onStartFocused() {
+    if (_disabled) {
+      return;
+    }
     if (state.currentSelection == rangeId && !state.previewAnchoredAtStart)
       return;
     _model.value = state.select(rangeId, previewAnchoredAtStart: false);
   }
 
   void onEndFocused() {
+    if (_disabled) {
+      return;
+    }
     if (state.currentSelection == rangeId && state.previewAnchoredAtStart)
       return;
     _model.value = state.select(rangeId, previewAnchoredAtStart: true);

lib/material_datepicker/material_date_range_picker.dart

@@ -18,6 +18,7 @@ import 'package:angular_components/laminate/enums/alignment.dart';
 import 'package:angular_components/laminate/popup/popup.dart';
 import 'package:angular_components/material_button/material_button.dart';
 import 'package:angular_components/material_datepicker/comparison.dart';
+import 'package:angular_components/material_datepicker/comparison_option.dart';
 import 'package:angular_components/material_datepicker/date_range_editor.dart';
 import 'package:angular_components/material_datepicker/module.dart';
 import 'package:angular_components/material_datepicker/next_prev_buttons.dart';
@@ -84,7 +85,12 @@ import 'package:angular_components/utils/disposer/disposer.dart';
   ],
 )
 class MaterialDateRangePickerComponent extends KeyboardHandlerMixin
-    implements HasDisabled, OnInit, OnDestroy, DateRangeEditorHost {
+    implements
+        HasDisabled,
+        OnInit,
+        AfterChanges,
+        OnDestroy,
+        DateRangeEditorHost {
   DateRangeEditorComponent _dateRangeEditor;
   bool _focusOnDateRangeEditorInit = false;
 
@@ -286,6 +292,22 @@ class MaterialDateRangePickerComponent extends KeyboardHandlerMixin
   String get placeHolderMsg => _customPlaceHolderMsg ?? _placeHolderMsg;
   String _customPlaceHolderMsg;
 
+  /// [ComparisonOption]s the user can choose from.
+  ///
+  /// By default, this is "Previous period", "Previous year", and "Custom".
+  /// This can only be set once. Null or empty values are ignored.
+  @Input()
+  set comparisonOptions(List<ComparisonOption> options) {
+    if (options != null && options.isNotEmpty) {
+      // User cannot change this value after setting it.
+      assert(_comparisonOptions == null || _comparisonOptions == options);
+      _comparisonOptions = options;
+      model.supportedComparisonOptions = _comparisonOptions;
+    }
+  }
+
+  List<ComparisonOption> _comparisonOptions;
+
   @ViewChild('focusOnClose')
   KeyboardOnlyFocusIndicatorDirective focusOnClose;
 
@@ -381,6 +403,19 @@ class MaterialDateRangePickerComponent extends KeyboardHandlerMixin
           .listen((v) => selection.value = v.date));
   }
 
+  @override
+  void ngAfterChanges() {
+    // Checks the edge case if user enter a wrong comparison range that
+    // is not supported.
+    if (supportsComparison &&
+        _comparisonOptions != null &&
+        selection.value != null &&
+        !_isComparisonOptionsSupported(selection.value)) {
+      throw UnsupportedError('Your comparisonOptions don\'t support your'
+          ' input datePickerComparison: ${selection.value}');
+    }
+  }
+
   @override
   void ngOnDestroy() => _disposer.dispose();
 
@@ -550,6 +585,13 @@ class MaterialDateRangePickerComponent extends KeyboardHandlerMixin
     }
   }
 
+  /// Whether the given [DatepickerComparison] is supported by this picker's
+  /// current configuration.
+  bool _isComparisonOptionsSupported(DatepickerComparison cmp) =>
+      !cmp.isComparisonEnabled ||
+      _comparisonOptions.contains(ComparisonOption.custom) ||
+      _comparisonOptions.any((option) => cmp.comparesTo(option));
+
   static final cancelButtonMsg = Intl.message('Cancel',
       meaning: 'Button in a date picker',
       desc: 'Label for a "cancel" button -- abandon the current date selection '

lib/src/material_datepicker/comparison_range_editor.dart

@@ -2,9 +2,13 @@
 // for details. 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:core';
+
 import 'package:angular/angular.dart';
 import 'package:intl/intl.dart';
+import 'package:angular_components/material_datepicker/comparison_option.dart';
 import 'package:angular_components/material_datepicker/date_range_input.dart';
+import 'package:angular_components/material_datepicker/range.dart';
 import 'package:angular_components/src/material_datepicker/date_range_editor_model.dart';
 import 'package:angular_components/material_list/material_list.dart';
 import 'package:angular_components/material_list/material_list_item.dart';
@@ -41,53 +45,27 @@ class ComparisonRangeEditorComponent {
   /// non-test implementation is [DateRangeEditorModel].
   @Input()
   HasComparisonRange model;
+  Map<ComparisonOption, String> _optionMsgCache = {};
+  DatepickerDateRange _primaryDateRange;
 
-  final List<ComparisonOption> options = [
-    ComparisonOption.previousPeriod,
-    ComparisonOption.samePeriodLastYear,
-    ComparisonOption.custom
-  ];
-
-  static final comparisonHeaderMsg = Intl.message('Compare',
+  String get comparisonHeaderMsg => Intl.message('Compare',
       name: 'comparisonHeaderMsg',
       desc: 'Label for a toggle that turns time comparison on/off.');
 
-  String get previousPeriodMsg {
-    // If we have a nice title ("3 weeks ago"), use that. Otherwise fall back
-    // to "Previous period".
-    var prev = model.prevRange;
-    return prev?.isPredefined == true ? prev.title : _previousPeriodMsg;
+  /// Gets display message from given option.
+  String comparisonOptionMsg(ComparisonOption option) {
+    if (_primaryDateRange != model.primaryRange) {
+      _updateOptionMsg();
+      _primaryDateRange = model.primaryRange;
+    }
+    return _optionMsgCache[option];
   }
 
-  static final _previousPeriodMsg = Intl.message('Previous period',
-      name: '_previousPeriodMsg',
-      meaning: 'Name for a time comparison option',
-      desc: 'Setting to compare the selected date range with the previous '
-          'period. E.g. if the selected range were May, this would be April.');
-
-  static final samePeriodLastYearMsg = Intl.message('Previous year',
-      name: 'samePeriodLastYearMsg',
-      meaning: 'Name for a time comparison option',
-      desc: 'Setting to compare the selected date range with the same range '
-          'last year. E.g. if the selected range were May 2015, this would be '
-          'May 2014.');
-
-  static final customMsg = Intl.message('Custom',
-      name: 'customMsg',
-      meaning: 'Name for a time comparison option',
-      desc: 'Setting to compare the selected date range with another arbitrary '
-          'user-selected date range.');
-
-  String comparisonOptionMsg(ComparisonOption option) {
-    switch (option) {
-      case ComparisonOption.previousPeriod:
-        return previousPeriodMsg;
-      case ComparisonOption.samePeriodLastYear:
-        return samePeriodLastYearMsg;
-      case ComparisonOption.custom:
-        return customMsg;
-      default:
-        return '<unknown comparison option>';
+  void _updateOptionMsg() {
+    for (var option in model.validComparisonOptions) {
+      _optionMsgCache[option] =
+          option.computeComparisonRange(model.primaryRange)?.title ??
+              option.displayName;
     }
   }
 }