[docs][joy-ui] Provide better documentation on overwriting substyles

[Studio384]

Duplicates

• I have searched the existing issues

Related page

n/a

Kind of issue

Missing information

Issue description

The theme providers a variable ownerState to change the styling of a component based on its current state. As such, when a list item button was selected, I expected this to work:

JoyListItemButton: {
  styleOverrides: {
    root: ({ ownerState }: { ownerState: ListItemButtonOwnerState }) => ({
      borderRadius: 8,
      gap: 12,
      '--ListItemDecorator-size': '1rem',
      ...(ownerState.selected && {
        '--Icon-color': 'var(--joy-palette-primary-main)',
        backgroundColor: 'rgba(var(--joy-palette-primary-mainChannel) / .15)',
        fontWeight: 400
      }),
    })
  }
},

But it doesn't. The background color and font weight only gets applies when !important is added behind it (which isn't ideal anyways) because these styles are directly applied to .MuiListItemButton-root instead of .MuiListItemButton-root.Mui-selected and changing the --Icon-color for the selected state is completely impossible this way.

Instead, these customization have to be applied as follows for them to properly work:

JoyListItemButton: {
  styleOverrides: {
    root: {
      borderRadius: 8,
      gap: 12,
      '--ListItemDecorator-size': '1rem',
      '&.Mui-selected': {
        backgroundColor: 'rgba(var(--joy-palette-primary-mainChannel) / .15)',
        fontWeight: 400,
        '& .MuiListItemDecorator-root': {
          // As far as I can tell, even setting --Icon-color here has not the desired effect
          color: 'var(--joy-palette-primary-plainColor)',
        }
      }
    }
  }
},

If there is a better way for this, I'd love to hear it.

Regardless, my primary concern is that this entire thing isn't documented anywhere. As far as I can tell, the docs only ever mention ownerState to say "hey, this exists" and never actually talk about what it is. I learned this was a thing only from a random example on the docs that used it and I still don't really know what is all included in there, nor how it exactly behaves (because from the example, I'd assumed that it could overwrite the style for .Mui-selected, but it clearly isn't that simple (but it kinda feels like it should)).

It feels like extendTheme() is severly under-documented. Like the ownerState API within it, as far as I can tell extendTheme and its functionalities are nowhere properly documented for developers.

Context 🔦

Other examples of this are the various hooks in MUI, like useColorScheme.

Why is useMediaQuery the only hook that has an actual proper documentation page including a description of its API?

[danilo-leal]

Thanks for opening this issue up! I agree with the sentiment ⎯ there is "assumed" knowledge in all product docs that we don't entirely introduce to readers upfront as well and clearly as we should, and then we end up using them in demo examples and it just ends up looking like extra stuff that I'm not sure why it's there, scaring those who don't have prior context/experience. Talking from a development sort of beginner mindset, I have felt the same with literally the ownerState thing and what it meant/does while trying to make sense of the source file for a Joy UI component.

cc @samuelsycamore big opportunity here. 😬
cc @zanivan to keep you in the loop.