docs: date picker spec

[jnumainville]

Fixes #349

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

[dsmmcken]

I think this looks right, but I am not super familiar with our DateTime methods. Adding @alexpeters1208 in case he has any commentary.

[dsmmcken]

What is the return type of on_change and how is that controlled?

[alexpeters1208]

I am surprised that this doesn't support a parameter combination like ui.date_picker(table: Table, date_col: str). I would expect to be able to pass a table in along with a column name for a column containing one of the valid types, and have the picker automatically provide the allowable date ranges accordingly. Not sure what the right default would be, maybe the entire date range?

[jnumainville]

@mofojed @dsmmcken thoughts?
I was thinking about a table source but thought it didn't make much sense due to differing resolutions. I suppose making the column an alternative to min_value or max_value is possible, but seems to be a lot of work for something that could be done through a combination of table operations and use_cell_data hooks.

[mofojed]

Yea @alexpeters1208 for that case, wouldn't a ui.picker make more sense instead when selecting a date from a table? As for a range, yea I think use_cell_data would work fine for that case... we should mock out an example though.

[dsmmcken]

https://react-spectrum.adobe.com/react-spectrum/DateRangePicker.html is a different thing, but also maybe relevant to the discussion.

[alexpeters1208]

@mofojed My understanding is that date_picker gives you a kind of calendar pop-up, while picker is a drop-down list. I don't think I'd want to use a drop down list for dates, seems like that list gets really long really quick. Or maybe I'm not understanding?

[jnumainville]

This is a fairly contrived and simplified example but represents how you could derive a value from a table for a range already. It's not difficult to do the end range too but I wanted to show that there is lots of flexibility that might be desired that I think is best achieved outside of the date_picker itself.

table = time_table(period="PT2S")
start = table.head(1)

min_value = ui.use_cell_data(start)
max_value = "2024-29-03"

date_picker = ui.date_picker(min_value=min_value, max_value=max_value)

[dsmmcken]

I know you've excluded it, but the isDateUnavailable prop feels kinda like something that could be a column.

[jnumainville]

I had the same thought but quickly ran into trouble when considering how exactly that would be implemented. It doesn't make much sense as a separate boolean column because you would have to check the boolean + date column.
This brings me to the possibility of having a table for unavailable_values with a date column (which I basically emulate with a list of dates at the moment) but is it worth implementing table backing for that?

[jnumainville]

What is the return type of on_change and how is that controlled?

It is the same type that is passed to value, default_value, placeholder_value, or Instant if none of those are specified. My thought was the type would be checked on the python side, serialized, then the callback would be wrapped with a type conversion so that the value passed to the user-specified callback is the same as the input type passed in.

[dsmmcken]

the same type that is passed in

makes sense, and what I expected.

Instant if none of those are specified

Record that decision in your spec.

[mofojed]

Crap, I never posted my pending review. Posting now.

[bmingles]

LGTM

[jnumainville]

Going to go ahead and merge with the note that BusinessCalendar could prove useful in the future but will add to spec if needed.