[pickers] Add new method onToggleOpening to usePickerContext()

[flaviendelangle]

While working on #15671, I started to duplicate a lot the handleTogglePicker method.
WDYT about exposing both onOpen / onClose / open AND the onToggleOpening method.
It cleans our doc demos a bit to focus on the interesting part and I guess most people would prefer to use the shortcut anyway.

[flaviendelangle]

It could be an action exposed by usePickerValue but it has more implications (all actions are forwarded to PickersPopper for now.
Until the actions are always accessed through the state, I propose to keep it here to avoid problems.

[mui-bot]

Deploy preview: https://deploy-preview-15701--material-ui-x.netlify.app/

Generated by 🚫 dangerJS against aeddc0d

[LukasTy]

I think we were discussing this exact topic when we were initially introducing the other methods. 😃
I can't think of any harm providing it, if we already feel that it is cleaner in most regular cases. 👌

[LukasTy]

WDYT about naming the method (renaming onOpen and onClose accordingly) a bit differently to have a usual onClick={handleClick} scenario? 🤔

• handleOpenToggle
• handleToggleOpen
• toggleOpenState
• togglePickerOpen

[flaviendelangle]

onOpen and onClose are present in v7 so it's a small BC.
But if you think it's cleaner I'm fine doing it.

I'm not a fan of the handleXXX when they are provided by a hook (or as a prop).
I use them when creating variables like:

const handleTogglePicker = () => { ... }

return <button onClick={handleTogglePicker}>Open me</button>

But when it comes from a button it feels off to me:

const { handleTogglePicker } = usePickerFakeContext();

return <button onClick={handleTogglePicker}>Open me</button>

Not sure why 😆
Maybe because handleXXX is a nomenclature used only for event handler and nothing prevents the user to use the methods from the hook in something else (in an effect, when a server request loads etc...).

For this kind of hook, if we don't want to onXXX, I would take to prefer a naming like openPicker, closePicker and togglePickerOpening for example.

[LukasTy]

Great insights, especially regarding the possibility of this function being called in other places than the even handler. 👌

onOpen and onClose are present in v7 so it's a small BC.

They are and didn't even cross my eyes until you started working on this change, then it became a bit more clear, that we can improve clarity here. 🙈
But they are present in the valueResponse.
Couldn't we update the naming only in the context? 🤔

I would not mind having openPicker, closePicker, and togglePickerOpen(ing) (the opening word here sounds slightly strange 🙈 🤷 ).
P.S. Have we explored going for setPickerOpen instead of onOpen and onClose?
Noticed such an approch here:
https://github.com/adobe/react-spectrum/blob/e94e36431149b6d3e9ed5900de30b538c0110584/packages/%40react-stately/datepicker/src/useDatePickerState.ts#L55-L56

[flaviendelangle]

Couldn't we update the naming only in the context? 🤔

But the context was introduced in a later v7 release I think 😬
So renaming them is a BC
But probably almost nobody is using it for now, if we want to break it, let's do it before we document it.

[flaviendelangle]

P.S. Have we explored going for setPickerOpen instead of onOpen and onClose?

That's yet another nomenclature indeed.

[flaviendelangle]

WDYT about the following:

• setOpen
• openPicker
• closePicker

We keep the 3 methods for maximal flexibility, we don't have any "handle" or "on" prefix.
And IMHO setOpen is cleared that it's like a setState that takes the new state, setPickerOpen is slightly less clear to me (I would expect it to just open the picker).

[LukasTy]

But the context was introduced in a later v7 release I think 😬
So renaming them is a BC

Oh shoot, I forgot that we introduced it in v7 as well. 🙈 🥷
Yeah, I'm all for refining the naming and not documenting too much on v7.
Maybe we can also skimp on having a codemod for the renaming. 😆

• setOpen
• openPicker
• closePicker

Didn't we plan to add a togglePickerOpen function to ease the simple use-case examples?
I had in mind if we considered having setOpen instead of openPicker and closePicker combination. 🤔

[flaviendelangle]

Oh right, I got mixed up with my needs on the composition API here...

So if we start from the beginning, to modify the opening state of the picker, there are 4 potential methods:

1. Open
2. Closes
3. Toggles
4. Sets the provided value

Right now the context has 1. and 2.
I'm proposing to add 3. because it makes all the demos of custom fields easier to read.
And we will need 4. in the composition API because most modal / popover component take a prop like onOpenChange (Base UI and React Aria both do).

I had in mind if we considered having setOpen instead of openPicker and closePicker combination. 🤔

So if I understand your comment correctly, you are proposing having 3 and 4 and dropping 1 and 2.
In which case maybe toggleOpen and setOpen would be good names.

[LukasTy]

Yes, your great summary is exactly what I had in mind. 👍
WDYT about it? 🤔
Is it worth the slight BC?
Does it make sense from the PoV of demos?

[flaviendelangle]

I think it's a good approach.
Having 1, 2, 3 and 4 seems a bit overkill.

And IMHO it's better for the user to rebuild 1 and 2 with 4:

const openPicker = () => setOpen(true);
const closePicker = () => setOpen(false);

Than rebuild 3 and 4 with 1 and 2:

const togglePicker = () => open ? openPicker() : closePicker();
const setPicker = (newOpen) => newOpen ? openPicker() : closePicker();

So I agree that we probably want to expose 3 and 4 and let the user build 1 and 2 if they want to.

[flaviendelangle]

I think we were discussing this exact topic when we were initially introducing the other methods. 😃

Yes, we were debating between an onToggleXXX and onOpen + onClose.
I think we did the right move to provide onOpen + onClose, but now I think providing both is even better 😆