[docs] Document how to chain in createTheme

When using createMuiTheme, along with overrides, we lose the context of the theme we customizing. Here’s a quick codesandbox which demonstrates the issue and also the desired (optional) solution: https://codesandbox.io/s/jolly-aryabhata-8q37p

const theme = createMuiTheme({
  shape: {
    borderRadius: 4
  },
  overrides: {
    MuiChip: {
      root: {
        borderRadius: 4
      }
    }
  }
  // this is what I would want
  // overrides: (theme) => ({
  //   MuiChip: {
  //     root: {
  //       borderRadius: theme.shape.borderRadius
  //     }
  //   }
  // })
});

• The issue is present in the latest release.
• I have searched the issues of this repository and believe that this is not a duplicate.

[oliviertassinari]

Ok, so unless somebody wants to bring in new arguments, the best option we have identified is:

import { createMuiTheme } from '@material-ui/core/styles'
import { grey } from '@material-ui/core/colors'

const basicBlue = '#0052cc' // Nathan's blue

let theme = createMuiTheme({
  palette: {
    primary: {
      main: basicBlue,
      dark: '#002b9a',
    },
    secondary: {
      main: '#edf2ff',
      dark: '#dee7fd',
      contrastText: basicBlue,
    },
    error: {
      main: '#ff001f',
    },
    text: {
      primary: '#262626',
      secondary: grey[600],
      disabled: grey[500],
    },
    action: {
      active: grey[600],
      disabledBackground: 'rgba(0, 0, 0, 0.06)',
    },
  },
  typography: {
    fontFamily: '"Roboto", "Helvetica Neue", "Arial", sans-serif',
    fontSize: 14,
    fontWeightRegular: 400,
    fontWeightMedium: 500,
    fontWeightBold: 700,
    useNextVariants: true,
  },
  shape: {
    borderRadius: 2,
  },
  breakpoints: {
    values: {
      sm: 750,
      md: 950,
      lg: 1250,
    },
  },
  props: {
    MuiTypography: {
      headlineMapping: {
        h1: 'h1',
        h2: 'h1',
        h3: 'h1',
        body1: 'p',
      },
    },
  },
})

theme = createMuiTheme(theme, {
  palette: {
    background: {
      default: theme.palette.common.white,
      placeholder: grey[100],
    },
    success: {
      background: '#d6ffd3',
      text: '#389543',
    },
    warning: {
      background: '#fff2df',
      text: '#ca7700',
    },
    info: {
      background: theme.palette.secondary.main,
      text: theme.palette.primary.main,
    },
    error: {
      background: '#ffe7e7',
      text: theme.palette.error.main,
    },
  },
  typography: {
    h1: {
      fontWeight: theme.typography.fontWeightBold,
      fontSize: 42,
      lineHeight: 1.1,
      color: '#000',
      [theme.breakpoints.down('xs')]: {
        fontSize: 26,
      },
    },
    h2: {
      fontWeight: theme.typography.fontWeightMedium,
      fontSize: 28,
      color: '#000',
      [theme.breakpoints.down('xs')]: {
        fontSize: 22,
      },
    },
    h3: {
      fontWeight: theme.typography.fontWeightBold,
      fontSize: 22,
      [theme.breakpoints.down('xs')]: {
        fontSize: 18,
      },
    },
    subtitle1: {
      fontWeight: theme.typography.fontWeightMedium,
      fontSize: 15,
    },
    button: {
      fontSize: 16,
      lineHeight: 1.2,
    },
    caption: {
      fontSize: 11,
      color: theme.palette.text.secondary,
    },
  },
  nprogress: {
    color: theme.palette.primary.light,
  },
})

I think that we should document it.

For instance, we use it here: https://github.com/mui-org/material-ui/blob/HEAD/docs/src/modules/branding/BrandingRoot.tsx.

TODO

• Document how to compose the theme in multiple steps
• Document how the extra arguments are merged, leverage confusion raised in #27203

[eps1lon]

it makes sense that it will have the context of the theme

Not to me. Going with “make senses” or “common sense” is usually a fallacy because it requires some knowledge. For a new user it’s unclear why some key in an object should be treated differently. Maybe it never will. Requiring that insight to make sense of an API does not make for a good API.

The example doesn’t require any special API or type overloading:

Variant A

const borderRadius = 4;
const theme = createMuiTheme({
  shape: {
    borderRadius,
  },
}, {
  overrides: {
    MuiChip: {
      root: {
        borderRadius,
      },
    },
  },
});

Variant B

const theme = createMuiTheme({
  shape: {
    borderRadius: 4,
  },
});
theme.overrides.MuiChip.root = {
  borderRadius: theme.shape.borderRadius
}

Convenience API should have a very high barrier to implement because it’s just convenience.