diff --git a/plugins/ui/DESIGN.md b/plugins/ui/DESIGN.md index ee91b496e..b98d40b30 100644 --- a/plugins/ui/DESIGN.md +++ b/plugins/ui/DESIGN.md @@ -1310,6 +1310,131 @@ 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 is controlled by these specific props, in the following order of precedence: +1. `value` or `default_value` +2. `placeholder_value` + +```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's date at midnight. | +| `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. | +| `**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: @@ -1828,6 +1953,8 @@ PickerItem = Stringable | ItemElement Key = Stringable Selection = Sequence[Key] ListViewItem = Stringable | ItemElement +Date = Instant | LocalDate | LocalDateTime +Granularity = Literal["DAY", "HOUR", "MINUTE", "SECOND"] T = TypeVar("T") Combination: TypeAlias = T | set[T] | Sequence[T]