[RFC] Consolidate orientation, row and direction props

[siriwatknp]

Motivation

1. We currently have 2 ways of changing the direction of the component, via literal options and via a boolean:

Component	Signature	Link	Comment
Tabs	orientation: 'horizontal' | 'vertical'	https://mui.com/material-ui/react-tabs/#vertical-tabs
Slider	orientation: 'horizontal' | 'vertical'	https://mui.com/material-ui/react-slider/#vertical-sliders
Stepper	orientation: 'horizontal' | 'vertical'	https://mui.com/material-ui/react-stepper/#vertical-stepper
Collapse	orientation: 'horizontal' | 'vertical'	https://mui.com/material-ui/transitions/#collapse
Divider	orientation: 'horizontal' | 'vertical'	https://mui.com/material-ui/react-divider/#vertical-divider
Stack	direction: 'row' | 'row-reverse' | ... | 'column-reverse'	https://mui.com/system/react-stack/#direction	Based after flex-direction
PopperUnstyled	direction: 'ltr' | 'rtl'	https://mui.com/base/api/popper-unstyled/#props	Based after dir
Slide	direction: 'left' | ... | 'down'	https://mui.com/material-ui/transitions/#slide
SpeedDial	direction: 'left' | ... | 'down'	https://mui.com/material-ui/react-speed-dial/#playground
RadioGroup (built on FormGroup)	row: boolean	https://mui.com/material-ui/react-radio-button/#direction
List	row: boolean	https://mui.com/joy-ui/react-list/#horizontal-list

I have a hard time deciding which prop I should follow when developing new components for Joy UI.

3. The orientation prop is not intuitive for me, here is my experience of using it in Slider component:

• I want to render a vertical Slider, so I guess I need to add either column or vertical prop.
• I use autocomplete in VS code but could not find the related prop
• In the end, I need to open the doc to see what prop I have to use which is orientation

It is not intuitive because what I want (the vertical value) should be the thing that I type first, but now I need to know what prop that makes the slider vertical 🤔.

Proposal

It would be easier if I could just use vertical: boolean on the component:

<Slider vertical />

Another reason is there are only 2 values for the orientation (which is the same as true | false), so why don't we use boolean?

Note that some component is worth using horizontal: boolean instead based on their default behavior, for example, the List component:

<List horizontal>...</List>

[oliviertassinari]

Regarding the cons of the proposal, I can think of these we could weight in the decision:

1. The prop name from one component to another to change the orientation would be different, meaning that as a developer you can't learn once: use the orientation prop. He would have to try each if he doesn't know what's the default value is.
2. It's a breaking change. Are the pros clear enough to be worth teaching it to the community?
3. The platform is not using the proposed terminology, e.g. https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation

so why don't we use boolean?

What would be the output of <Stack vertical={false}>? Would the rendered direction be horizontal or a different angel? Most likely horizontal, but it open room for confusion.

[danilo-leal]

The proposal sounds good and simple enough for me! It sounds more straightforward than row and column, even though these definitely ring a bell due to being values for flex or grid containers. I also appreciate the reduced verbosity of not having to write orientation all the time!

Should we then assume that every component is going to render horizontally unless vertical is added?

[siriwatknp]

I guess not. It should depend on the common layout of the component. For example:

• List is usually vertical by default, so it needs horizontal prop to change the flow.
• Tabs is usually horizontal by default, so it needs vertical prop to change the flow.

<List horizontal>
<Tabs vertical>

[danilo-leal]

Ah, yes. That makes total sense. I'm definitely in for horizontal and vertical 👌

[raajnadar]

What if some one send both props by mistake?

[siriwatknp]

What if some one send both props by mistake?

That's not possible. Each component receives either vertical or horizontal. For example, List receives only horizontal

<List horizontal>...</List>

[siriwatknp]

@danilo-leal would love to have your opinion about this so that we can make it consistent for Joy UI.

[oliviertassinari]

@siriwatknp Would it be possible to update the initial description to have an improved benchmark of all the existing different prop and prop types used for this :)?

What I think we could improve in the description: 1. have a single list, there are two lists 2. Cover the Divider, 3. Stack is mentioned twice

[siriwatknp]

updated.

[oliviertassinari]

Thanks! And I did another pass

[oliviertassinari]

Personally, I would vote for:

1. Use "direction" terminology in the prop and docs when:
   a. It's a reference to the CSS flexbox specifications. https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction. Why? It would get us closer to how developers would write code without MUI, hence I think make the API easier to learn. e.g. Stack is a great use case for it. Chakra is another example of the application of this idea https://chakra-ui.com/docs/components/stack/usage#responsive-direction.
   b. It's a reference to the dir attribute for RTL/LTR. Why? To not introduce a new terminology
   c. When there is a notion of movement. Why? https://english.stackexchange.com/a/85632/370968
2. Use "orientation" terminology in the prop and docs for everything else. It would match https://chakra-ui.com/docs/components/slider/usage#changing-the-slider-orientation, https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-orientation, https://reach.tech/slider#slider-orientation, https://www.radix-ui.com/docs/primitives/components/slider#vertical-orientation Why? So developers can learn it once. So, they don't have to try to type row and then vertical, then horizontal to find if it's possible to change the orientation of the component, depending on what's the default value.

[danilo-leal]

Why not skip direction and orientation altogether and just go with a boolean horizontal or vertical? As @siriwatknp was explaining, some components will render with one or the other by default and in those that are horizontal, for example, by default, there would be a vertical prop, and vice-versa.

[oliviertassinari]

The cons I see:

1. Developers have to try both props to figure out the one that works. Or maybe developers won't try horizontal/vertical but row/column.
2. horizontal and vertical can't replace direction. The direction prop often have 4 values
3. We have taught most developers about direction and orientation so far, so have other libraries. The minimum path of resistance to maximize consistency seems to replace the row prop with the orientation.
4. An orientation is in theory not binary, there are 90 degrees to consider (for a direction: 360 degrees)

[siriwatknp]

Developers have to try both props to figure out the one that works. Or maybe developers won't try horizontal/vertical but row/column.

Either way, developers need to remember how to use it anyway. Let's compare the 2 given all components are consistent. The difference between orientation=".." and vertical/horizontal is the number of characters to type (8 vs 20). If you use IDE autocomplete, you need 2 tabs instead of 1.

horizontal and vertical can't replace direction. The direction prop often have 4 values

Correct, I have no objection to the direction prop. My point is the orientation prop that has 2 values.

We have taught most developers about direction and orientation so far, so have other libraries. The minimum path of resistance to maximize consistency seems to replace the row prop with the orientation.

Yes, we should consider this point. changing from row to orientation might benefit developers the most.

An orientation is in theory not binary, there are 90 degrees to consider (for a direction: 360 degrees)

But in practice, there are only 2 choices.

[siriwatknp]

I guess Joy will follow Material UI for now and once we have the decision, let's break both of them and create a codemod.

[danilo-leal]

That sounds reasonable!