feat: Javascript DatePicker Implementation

plugins/ui/DESIGN.md

@@ -1020,11 +1020,12 @@ A tabs component can be used to organize content in a collection of tabs, allowi
 
 ###### Parameters
 
-| Parameter               | Type                                  | Description                                                                                                                                                    |
-| ----------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `*children`             | `Tab \| TabList \| TabPanels`        | The tab panels to render within the tabs component.                                                                                                                                                                                               |
-| `on_change`             | `Callable[[Key], None] \| None` | Alias of `on_selection_change`. Handler that is called when the tab selection changes.                                                                            |
-| `**props`               | `Any`                                 | Any other [Tabs](https://react-spectrum.adobe.com/react-spectrum/Tabs.html#tabs-props) prop 
+| Parameter   | Type                            | Description                                                                                 |
+| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------- |
+| `*children` | `Tab \| TabList \| TabPanels`   | The tab panels to render within the tabs component.                                         |
+| `on_change` | `Callable[[Key], None] \| None` | Alias of `on_selection_change`. Handler that is called when the tab selection changes.      |
+| `**props`   | `Any`                           | Any other [Tabs](https://react-spectrum.adobe.com/react-spectrum/Tabs.html#tabs-props) prop |
+
 |
 
 |
@@ -1340,7 +1341,6 @@ ui.date_picker(
     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
@@ -1349,17 +1349,16 @@ ui.date_picker(
 
 ###### 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)   |
+| 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.                                                                                                                                          |     |
+| `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
 

plugins/ui/docs/components/date_picker.md

@@ -0,0 +1,131 @@
+# Date Picker
+
+Date Pickers allow users to select a Date and Time from a pop up Calendar.
+
+## Example
+
+```python
+from deephaven import ui
+
+dp = ui.date_picker(
+    label="Date Picker",
+    value="2024-01-02T10:30:00 UTC",
+    on_change=print,
+)
+```
+
+## Date types
+
+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. No time zone will be displayed.
+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. The date picker will render the time zone from the user settings.
+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 date picker will render 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`.
+
+## UI recommendations
+
+Recommendations for creating clear and effective date pickers:
+
+1. Using the Date Type `Instant` will be most compatible with other Deephaven components.
+
+## Events
+
+Date Pickers accept a value to display and can trigger actions based on events such as setting state when changed. See the [API Reference](#api-reference) for a full list of available events.
+
+```python
+from deephaven import 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())
+
+
+@ui.component
+def date_picker_test(value):
+    date, set_date = ui.use_state(value)
+    return [ui.date_picker(on_change=set_date, value=date), ui.text(str(date))]
+
+
+zoned_date_picker = date_picker_test(zoned_date_time)
+instant_date_picker = date_picker_test(instant)
+local_date_picker = date_picker_test(local_date)
+```
+
+## Variants
+
+Date Pickers can have different variants to indicate their purpose.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def date_picker_variants():
+    return [
+        ui.date_picker(description="description"),
+        ui.date_picker(error_message="error", validation_state="valid"),
+        ui.date_picker(error_message="error", validation_state="invalid"),
+        ui.date_picker(min_value="2024-01-01", max_value="2024-01-5"),
+        ui.date_picker(value="2024-07-27T16:10:10 America/New_York", hour_cycle=24),
+        ui.date_picker(granularity="YEAR"),
+        ui.date_picker(granularity="MONTH"),
+        ui.date_picker(granularity="DAY"),
+        ui.date_picker(granularity="HOUR"),
+        ui.date_picker(granularity="MINUTE"),
+        ui.date_picker(granularity="SECOND"),
+    ]
+
+
+date_picker_variants_example = date_picker_variants()
+```
+
+## Time table filtering
+
+Date Pickers can be used to filter tables with time columns.
+
+```python
+from deephaven.time import dh_now
+from deephaven import time_table, ui
+
+
+@ui.component
+def date_table_filter(table, start_date, end_date, time_col="Timestamp"):
+    after_date, set_after_date = ui.use_state(start_date)
+    before_date, set_before_date = ui.use_state(end_date)
+    return [
+        ui.date_picker(
+            label="Start Date", value=after_date, on_change=set_after_date
+        ),
+        ui.date_picker(
+            label="End Date", value=before_date, on_change=set_before_date
+        ),
+        table.where(f"{time_col} >= after_date  && {time_col} < before_date"),
+    ]
+
+
+SECONDS_IN_DAY = 86400
+today = dh_now()
+_table = time_table("PT1s").update_view(
+    ["Timestamp=today.plusSeconds(SECONDS_IN_DAY*i)", "Row=i"]
+)
+date_filter = date_table_filter(_table, today, today.plusSeconds(SECONDS_IN_DAY * 10))
+```
+
+## API Reference
+
+```{eval-rst}
+.. dhautofunction:: deephaven.ui.date_picker
+```

plugins/ui/src/deephaven/ui/_internal/utils.py

@@ -5,6 +5,7 @@
 import sys
 from functools import partial
 from deephaven.time import to_j_instant, to_j_zdt, to_j_local_date
+from deephaven.dtypes import ZonedDateTime, Instant
 
 from ..types import Date, JavaDate
 
@@ -18,6 +19,8 @@
     "java.time.LocalDate": to_j_local_date,
 }
 
+_LOCAL_DATE = "java.time.LocalDate"
+
 
 def get_component_name(component: Any) -> str:
     """
@@ -211,6 +214,19 @@ def create_props(args: dict[str, Any]) -> tuple[tuple[Any, ...], dict[str, Any]]
     return children, props
 
 
+def _is_instant_string(value: str) -> bool:
+    """
+    Check if a string should parse as an Instant.
+
+    Args:
+        value: The string to check.
+
+    Returns:
+        Whether the string should parse as an Instant.
+    """
+    return value.endswith("Z") or value.endswith("UTC")
+
+
 def _convert_to_java_date(
     date: Date,
 ) -> JavaDate:
@@ -225,6 +241,15 @@ def _convert_to_java_date(
     Returns:
         The Java date type.
     """
+    # For strings, parseInstant and parseZonedDateTime both succeed for the same strings
+    # To differentiate, we check if the string looks like an Instant otherwise we default to ZonedDateTime
+    if isinstance(date, str) and not _is_instant_string(date):
+        try:
+            return to_j_zdt(date)  # type: ignore
+        except Exception:
+            # ignore, try next
+            pass
+
     try:
         return to_j_instant(date)  # type: ignore
     except Exception:
@@ -288,7 +313,16 @@ def _wrap_date_callable(
     Returns:
         The wrapped callable.
     """
-    return lambda date: wrap_callable(date_callable)(converter(date))
+    # When the user is typing a date, they may enter a value that does not parse
+    # This will skip those errors rather than printing them to the screen
+    def no_error_date_callable(date: Date) -> None:
+        wrapped_date_callable = wrap_callable(date_callable)
+        try:
+            wrapped_date_callable(converter(date))
+        except Exception:
+            pass
+
+    return no_error_date_callable
 
 
 def _get_first_set_key(props: dict[str, Any], sequence: Sequence[str]) -> str | None:
@@ -341,7 +375,7 @@ def _prioritized_callable_converter(
 def convert_list_prop(
     key: str,
     value: list[Date] | None,
-) -> list[JavaDate] | None:
+) -> list[str] | None:
     """
     Convert a list of Dates to Java date types.
 
@@ -357,14 +391,15 @@ def convert_list_prop(
 
     if not isinstance(value, list):
         raise TypeError(f"{key} must be a list of Dates")
-    return [_convert_to_java_date(date) for date in value]
+    return [str(_convert_to_java_date(date)) for date in value]
 
 
 def convert_date_props(
     props: dict[str, Any],
     simple_date_props: set[str],
     callable_date_props: set[str],
     priority: Sequence[str],
+    granularity_key: str,
     default_converter: Callable[[Date], Any] = to_j_instant,
 ) -> None:
     """
@@ -376,6 +411,7 @@ def convert_date_props(
         callable_date_props: A set of callable date keys to convert.
             The prop value should be a callable that takes a Date.
         priority: The priority of the props to check.
+        granularity_key: The key for the granularity
         default_converter: The default converter to use if none of the priority props are present.
 
     Returns:
@@ -388,6 +424,16 @@ def convert_date_props(
     # the simple props must be converted before this to simplify the callable conversion
     converter = _prioritized_callable_converter(props, priority, default_converter)
 
+    # based on the convert set the granularity if it is not set
+    # Local Dates will default to DAY but we need to default to SECOND for the other types
+    if props.get(granularity_key) is None and converter != to_j_local_date:
+        props[granularity_key] = "SECOND"
+
+    # now that the converter is set, we can convert simple props to strings
+    for key in simple_date_props:
+        if props.get(key) is not None:
+            props[key] = str(props[key])
+
     for key in callable_date_props:
         if props.get(key) is not None:
             if not callable(props[key]):