[docs] Radio docs are incorrect/lacking

[benface]

Docs feedback

How can we improve Base UI documentation?

The docs for the Radio.Root component mention:

Represents the radio button itself. Renders a element and a hidden beside.

But that's incorrect; the hidden <input> seems to be rendered as a sibling of the <button> element rather than inside it.

Which begs the question... why can't <Radio.Root> actually render a <label> that contains both the <button> and the <input>? Seems strange to have to wrap it in a <label> ourselves, as per the example... it's not really documented so maybe that's optional, but if we don't wrap it in a <label>, how is the radio going to be labelled?

[benface]

Another issue: Radio.Root's value prop apparently has a default value of undefined, which makes it look like that prop is optional (not to mention that native <input type="radio" /> work just fine without a value), but it's actually required. Maybe required props should have no default value specified, or maybe it could be even more explicit and show "(required)" or something?

[atomiks]

But that's incorrect; the hidden seems to be rendered as a sibling of the element rather than inside it.

It says "beside" not "inside"

Which begs the question... why can't <Radio.Root> actually render a that contains both the and the ?

For form controls specifically, we recommend using the Field (Field.Label), which provides labelling for them (along with validation). If it's not a form control that's focusable, then it gets its own Label part (e.g. Progress)

Another issue: Radio.Root's value prop apparently has a default value of undefined, which makes it look like that prop is optional (not to mention that native work just fine without a value), but it's actually required. Maybe required props should have no default value specified, or maybe it could be even more explicit and show "(required)" or something?

Makes sense, the docs in this case can be better

[benface]

It says "beside" not "inside"

Oops, my bad. I should read what I copy/paste more carefully. 😄

For form controls specifically, we recommend using the Field (Field.Label), which provides labelling for them (along with validation). If it's not a form control that's focusable, then it gets its own Label part (e.g. Progress)

Awesome, thanks for the tip!

[benface]

Another issue: Radio.Root's value prop apparently has a default value of undefined, which makes it look like that prop is optional (not to mention that native work just fine without a value), but it's actually required. Maybe required props should have no default value specified, or maybe it could be even more explicit and show "(required)" or something?

Makes sense, the docs in this case can be better

Note: I noticed the exact same issue with the Menu.RadioItem component.