docs: date picker spec (#388)

Fixes #349

Adds the spec for date picker. 
I attempted to emulate React Spectrum's date type specific rendering but
with deephaven date types.

plugins/ui/DESIGN.md

@@ -1354,6 +1354,135 @@ list_view7 = ui.list_view(
 )
 ```
 
+###### ui.date_picker
+A date picker that can be used to select a date. 
+
+There are three types that can be passed in to the props that control the date format:
+1. `LocalDate`: A LocalDate is a date without a time zone in the ISO-8601 system, such as "2007-12-03" or "2057-01-28".
+This will create a date picker with a granularity of days.
+2. `Instant`: An Instant represents an unambiguous specific point on the timeline, such as 2021-04-12T14:13:07 UTC.
+This will create a date picker with a granularity of seconds in UTC.
+3. `ZonedDateTime`: A ZonedDateTime represents an unambiguous specific point on the timeline with an associated time zone, such as 2021-04-12T14:13:07 America/New_York.
+This will create a date picker with a granularity of seconds in the specified time zone.
+
+The format of the date picker and the type of the value passed to the `on_change` handler 
+is determined by the type of the following props in order of precedence:
+1. `value` 
+2. `default_value`
+3. `placeholder_value`
+
+If none of these are provided, the `on_change` handler will be passed an `Instant`.
+
+```py
+import deephaven.ui as ui
+ui.date_picker(
+    placeholder_value: Date | None = None,
+    value: Date | None = None,
+    default_value: Date | None = None,
+    min_value: Date | None = None,
+    max_value: Date | None = None,
+    unavailable_values: Sequence[Date] | None = None,
+    granularity: Granularity | None = None,
+    on_change: Callable[[Date], None] | None = None,
+    **props: Any
+) -> ListViewElement
+```
+
+###### Parameters
+| Parameter            | Type                             | Description                                                                                                                                                                               |
+|----------------------|----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `placeholder_value`  | `Date \| None`                   | A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to today at midnight in the user's timezone.                                   |
+| `value`              | `Date \| None`                   | The current value (controlled).                                                                                                                                                           |
+| `default_value`      | `Date \| None`                   | The default value (uncontrolled).                                                                                                                                                         |
+| `min_value`          | `Date \| None`                   | The minimum allowed date that a user may select.                                                                                                                                          |
+| `max_value`          | `Date \| None`                   | The maximum allowed date that a user may select.                                                                                                                                          |
+| `unavailable_values` | `Sequence[Date] \| None`         | A list of dates that cannot be selected.                                                                                                                                                  |
+| `granularity`        | `Granularity \| None`            | Determines the smallest unit that is displayed in the date picker. By default, this is `"DAY"` for `LocalDate`, and `"SECOND"` otherwise.                                                 |
+| `on_change`          | `Callable[[Date], None] \| None` | Handler that is called when the value changes. The exact `Date` type will be the same as the type passed to `value`, `default_value` or `placeholder_value`, in that order of precedence. |
+| `**props`            | `Any`                            | Any other [DatePicker](https://react-spectrum.adobe.com/react-spectrum/DatePicker.html) prop, with the exception of `isDateUnavailable`, `validate`, and `errorMessage` (as a callback)   |
+
+```py
+
+import deephaven.ui as ui
+from deephaven.time import to_j_local_date, dh_today, to_j_instant, to_j_zdt
+
+zoned_date_time = to_j_zdt("1995-03-22T11:11:11.23142 UTC")
+instant = to_j_instant("2022-01-01T00:00:00 ET")
+local_date = to_j_local_date(dh_today())
+
+# simple date picker that takes ui.items and is uncontrolled
+# this creates a date picker with a granularity of days with a default value of today
+date_picker1 = ui.date_picker(
+    default_value=local_date
+)
+
+# simple date picker that takes list view items directly and is controlled
+# this creates a date picker with a granularity of seconds in UTC
+# the on_change handler is passed an instant
+date, set_date = ui.use_state(instant)
+
+date_picker2 = ui.date_picker(
+    value=date,
+    on_change=set_date
+)
+
+# this creates a date picker with a granularity of seconds in the specified time zone
+# the on_change handler is passed a zoned date time
+date, set_date = ui.use_state(None)
+
+date_picker3 = ui.date_picker(
+    placeholder_value=zoned_date_time,
+    on_change=set_date
+)
+
+# this creates a date picker with a granularity of seconds in UTC
+# the on_change handler is passed an instant
+date, set_date = ui.use_state(None)
+
+date_picker4 = ui.date_picker(
+    placeholder_value=instant,
+    on_change=set_date
+)
+
+# this creates a date picker with a granularity of days
+# the on_change handler is passed a local date
+date, set_date = ui.use_state(None)
+
+date_picker5 = ui.date_picker(
+    placeholder_value=local_date,
+    on_change=set_date
+)
+
+# this creates a date picker with a granularity of days, but the on_change handler is still passed an instant
+date, set_date = ui.use_state(None)
+
+date_picker6 = ui.date_picker(
+    placeholder_value=instant,
+    granularity="day",
+    on_change=set_date
+)
+
+# this creates a date picker with a granularity of seconds and the on_change handler is passed an instant
+date, set_date = ui.use_state(None)
+
+date_picker7 = ui.date_picker(
+    on_change=set_date
+)
+
+# this create a date picker with a granularity of days, a min and max value, and unavailable dates
+min_value = to_j_local_date("2022-01-01")
+max_value = to_j_local_date("2022-12-31")
+unavailable_dates = [to_j_local_date("2022-03-15"), to_j_local_date("2022-03-17")]
+date, set_date = ui.use_state(to_j_local_date("2022-03-16"))
+date_picker8 = ui.date_picker(
+    value=date,
+    min_value=min_value,
+    max_value=max_value,
+    unavailable_values=unavailable_dates,
+    on_change=set_date
+)
+```
+
 #### ui.table
 
 `ui.table` is a wrapper for a Deephaven `Table` object that allows you to add UI customizations or callbacks. The basic syntax for creating a `UITable` is:
@@ -1873,6 +2002,11 @@ Key = Stringable
 ActionKey = Key
 Selection = Sequence[Key]
 ListViewItem = Stringable | ItemElement
+LocalDateConvertible = Union[None, LocalDate, str, datetime.date, datetime.datetime, numpy.datetime64, pandas.Timestamp]
+InstantConvertible = Union[None, Instant, int, str, datetime.datetime, numpy.datetime64, pandas.Timestamp]
+ZonedDateTimeConvertible = Union[None, ZonedDateTime, str, datetime.datetime, numpy.datetime64, pandas.Timestamp]
+Date = Instant | LocalDate | ZonedDateTime | LocalDateConvertible | InstantConvertible | ZonedDateTimeConvertible 
+Granularity = Literal["DAY", "HOUR", "MINUTE", "SECOND"]
 
 T = TypeVar("T")
 Combination: TypeAlias = T | set[T] | Sequence[T]