[NumberField] onChange API / API convention?

[oliviertassinari]

Steps to reproduce

Link to live example: (required)

Steps:

1. https://master--base-ui.netlify.app/components/react-number-field/

Current behavior

New API structure for the onValueChange prop.

Expected behavior

The onValueChange API signature looks different from what we used to have. I'm missing the rationale/the value for it to be different.

1. The prop name:

base-ui/packages/mui-base/src/NumberField/Root/useNumberFieldRoot.ts

Line 67 in 78d4abd

onValueChange: onValueChangeProp = () => {},

Shouldn't this be called onChange, to match with the native form fields API props?

2. The first argument, is not event. In Material UI v0, we used to do a mix of a bunch of different signatures, we always needed to expose the event, so it seemed simpler to default to expose the event first, and the value second, and optional 3rd argument, and a catch all in a 4th argument.

https://mui.com/base-ui/react-number-input/#events matches my expectations.

Overall, I think that this raises the question of API consistency. I see no reason for it to differ between MUI X, Material UI, and Base UI (the opposite, it's part of the value of doing all under a single roof, consistency in the DX). So I think it should be our aspiring goal. https://mui.com/material-ui/guides/api/#controlled-components we meant to be our source of truth up until now.

I see a few action points:

1. Base UI needs an API page like the one of Material UI. Material UI's content should ideally not exist, refer everything back to Base UI. This should help align and scale.
2. I think we should default to start from the one of Material UI as has the most adoption, so would minimize the breaking changes. And from there move toward Radix APIs with changes to it ⬇️:
3. We should see how we can evolve this convention for the best. In that discussion, I would expect that we can feedback from all product owners who depend on it since they are aware of the potential implications on their end, and since it goes beyond the scope of Base UI, it's an overall unified library stack discussion.

Context

I saw this from the difference API used between number input and autocomplete in #579 (comment).

Your environment

npx @mui/envinfo

  Don't forget to mention which browser you used.
  Output from `npx @mui/envinfo` goes here.

Search keywords: -

[atomiks]

We went with onValueChange for a few reasons:

• It matches the value prop to be consistent with other controllable properties like open and onOpenChange.
• It's more ergonomic. You can pass the setValue setter in directly with no wrapper function needed: onValueChange={setValue}.
• The event is still accessible and passed as a second argument: onValueChange(value: string, event: Event). For the most basic/simple controlled usage, you don't need to care about the event. Since it's secondary, the way to access it is also secondary for optimal DX.

[oliviertassinari]

@atomiks I was coming from the perspective that developers have to learn the API convention of the native fields:
<input value={} onChange={(event) => event.target.value}>, so the closer the API of Base UI is, the less they will need to learn / change their habits.