[Proposal] Change handler consistency

Here’s a quick snapshot of our change handlers:

Checkbox: onChange(evt) { console.log(evt.target.checked); } Input: onChange(evt) { console.log(evt.target.value); } Menu: onItemSelect(selectedItem: object) Modal: onClose(closeSource: string) Pagination: onPageChange?: (nextPage: number, prevPage: number) Popover: onOpen(), onClose() RadioGroup: onChange(evt) { console.log(evt.target.value); } Select: onChange(evt, params) { console.log(params.selectedOptions) } Slider: onChange(evt, value) { console.log(value) } TextArea: onChange(evt) { console.log(evt.target.value); }

As you can see, there’s a pretty significant amount of variation between components. It would probably be good for us to make these more consistent, or at least develop some guidelines around what to use when.

I’d like to make a case for gravitating towards the following API long term:

onChange(value, event, meta)

• If this is a form control with a value, just pass that directly as the first argument. This prevents people from needing to remember how to dig into the event object like evt.target.checked or evt.target.value, etc. It also works better for components like multiple Select or Slider where the event doesn’t actually have the form control value.
• Event is second. I’d argue if you have the value first, event is rarely needed. It can also be confusing for something like multiple Select, where things like removing a tag technically trigger a change event. Or for pagination where clicking back/next or selecting a page from the dropdown can both trigger page changes.
• Meta is third. This is an object that can include things like previous value (if useful), or any other metadata that may be useful to the user.

The only benefit I can think for keeping event as the first argument is that it matches what people expect when using a native html element, but in many cases our components are not native html elements and the event can come from multiple different types of dom interactions. I’d rather be consistent within our own components than consistent with native elements.

Curious to hear what folks think about this – do you agree there’s a need to standardize? Are there downsides with the api proposed in this issue?

[abmai]

Maybe controversial opinion here. If we’re building for the future anyway - and we’re not entirely trying to mimic native handlers, why not go all the way to object params i.e. onChange({value, event, meta}) so we can forgo order altogether and allow users to just pick out what they need?

I agree that we should come to some sort of standardized API for the non-native change handlers.

[schnerd]

In my recent designed components value was not popular, or it was not a primitive type (object for instance). So I would leave event as first argument. Sometimes value is found in event itself.

By the same reasoning, sometimes value is not found in the event (select, slider, pagination, datepicker, etc), so event is “not popular” in those cases. By encouraging users to use the explicit value property we’d reduce the cognitive overload they have when implementing different components.

I think Anh’s API does a pretty good job of balancing the concern of whether event or value should come first – they’re both available if necessary, it’s consistent across all components, and the value is readily available.