[New API] MDC Date Picker APIs should accept java.time equivalents

[EdricChan03]

Is there an existing issue for this?

• I have searched the existing issues

Library name

Material Components for Android extensions

Problem

Material Components for Android's Date Picker currently expects a long to be used, which isn't very intuitive as to what you should pass to their APIs, especially when their parameters don't have a suffix that tells you what the unit should be:

@NonNull
@CanIgnoreReturnValue
public Builder<S> setSelection(S selection) {
  this.selection = selection;
  return this;
}

The datePicker static method for MaterialDatePicker.Builder returns a Builder<Long>, so it would look like such:

@NonNull
@CanIgnoreReturnValue
public Builder<Long> setSelection(Long selection) {
  this.selection = selection;
  return this;
}

Which is still confusing as to what unit to pass the selection as (milliseconds? seconds? etc).

Description

There should be extension functions to accept the more suitable java.time APIs first introduced in Java 8, and are designed to resolve the issue Java developers have with dates (and any existing bugs in the old Calendar/Date APIs).

I believe, however, that the Material Components for Android devs didn't go with this as it was only first introduced in Android Oreo (which first brought Java 8 support), so without core library desugaring it isn't possible.

Anyways, here's some proposed APIs:

• MaterialDatePicker.Builder.setSelection should take an Instant, or a Pair<Instant, Instant> for a single date/date-range picker respectively. This would proxy to calling its toEpochMilli method to get its milliseconds representation:

  fun MaterialSingleDatePickerBuilder.setSelection(instant: Instant) = setSelection(instant.toEpochMilli())
  fun MaterialDateRangePickerBuilder.setSelection(instants: Pair<Instant, Instant>) = setSelection(...)

• CalendarConstraints.Builder should take an Instant for its respective APIs that take a long:

  • setStart
  • setEnd
  • setOpenAt

• CalendarConstraints.Builder.setDayOfWeek should take a DayOfWeek

Alternatives?

Using the appropriate methods in the java.time APIs to retrieve its raw representation to then be passed to the existing Java API.

There are also already some example code snippets in some of the Javadocs for java.time.

Additional info

See EdricChan03/studybuddy-android@657c551 for context