[Button] Custom variant

docs/pages/api-docs/button.md

@@ -41,7 +41,7 @@ The `MuiButton` name can be used for providing [default props](/customization/gl
 | <span class="prop-name">href</span> | <span class="prop-type">string</span> |  | The URL to link to when the button is clicked. If defined, an `a` element will be used as the root node. |
 | <span class="prop-name">size</span> | <span class="prop-type">'large'<br>&#124;&nbsp;'medium'<br>&#124;&nbsp;'small'</span> | <span class="prop-default">'medium'</span> | The size of the button. `small` is equivalent to the dense button styling. |
 | <span class="prop-name">startIcon</span> | <span class="prop-type">node</span> |  | Element placed before the children. |
-| <span class="prop-name">variant</span> | <span class="prop-type">'contained'<br>&#124;&nbsp;'outlined'<br>&#124;&nbsp;'text'</span> | <span class="prop-default">'text'</span> | The variant to use. |
+| <span class="prop-name">variant</span> | <span class="prop-type">'contained'<br>&#124;&nbsp;'outlined'<br>&#124;&nbsp;'text'<br>&#124;&nbsp;string</span> | <span class="prop-default">'text'</span> | The variant to use. |
 
 The `ref` is forwarded to the root element.
 

docs/src/pages/customization/components/GlobalThemeVariants.js

@@ -0,0 +1,73 @@
+import React from 'react';
+import {
+  createMuiTheme,
+  makeStyles,
+  ThemeProvider,
+} from '@material-ui/core/styles';
+import Button from '@material-ui/core/Button';
+
+const useStyles = makeStyles((theme) => ({
+  root: {
+    '& > *': {
+      margin: theme.spacing(1),
+    },
+  },
+}));
+
+const defaultTheme = createMuiTheme();
+
+const inputTheme = createMuiTheme({
+  variants: {
+    MuiButton: [
+      {
+        props: { variant: 'dashed' },
+        styles: {
+          padding: '5px 15px',
+          border: `3px dashed ${defaultTheme.palette.primary.main}`,
+        },
+      },
+      {
+        props: { variant: 'dashed', color: 'secondary' },
+        styles: {
+          border: `3px dashed ${defaultTheme.palette.secondary.main}`,
+        },
+      },
+      {
+        props: { variant: 'dashed', size: 'large' },
+        styles: {
+          borderWidth: 5,
+        },
+      },
+      {
+        props: { variant: 'dashed', color: 'primary', size: 'large' },
+        styles: {
+          fontWeight: 600,
+        },
+      },
+    ],
+  },
+});
+
+export default function GlobalThemeVariants() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <ThemeProvider theme={inputTheme}>
+        <Button variant="dashed">Default</Button>
+        <Button variant="dashed" color="secondary">
+          Secondary
+        </Button>
+        <Button variant="dashed" color="primary">
+          Primary
+        </Button>
+        <Button variant="dashed" color="secondary" size="large">
+          Secondary large
+        </Button>
+        <Button variant="dashed" color="primary" size="large">
+          Primary large
+        </Button>
+      </ThemeProvider>
+    </div>
+  );
+}

docs/src/pages/customization/components/GlobalThemeVariants.tsx

@@ -0,0 +1,80 @@
+import React from 'react';
+import {
+  createMuiTheme,
+  makeStyles,
+  Theme,
+  ThemeProvider,
+} from '@material-ui/core/styles';
+import Button from '@material-ui/core/Button';
+
+declare module '@material-ui/core/Button/Button' {
+  interface ButtonPropsVariantOverrides {
+    dashed: true;
+  }
+}
+
+const useStyles = makeStyles((theme: Theme) => ({
+  root: {
+    '& > *': {
+      margin: theme.spacing(1),
+    },
+  },
+}));
+
+const defaultTheme = createMuiTheme();
+
+const inputTheme = createMuiTheme({
+  variants: {
+    MuiButton: [
+      {
+        props: { variant: 'dashed' },
+        styles: {
+          padding: '5px 15px',
+          border: `3px dashed ${defaultTheme.palette.primary.main}`,
+        },
+      },
+      {
+        props: { variant: 'dashed', color: 'secondary' },
+        styles: {
+          border: `3px dashed ${defaultTheme.palette.secondary.main}`,
+        },
+      },
+      {
+        props: { variant: 'dashed', size: 'large' },
+        styles: {
+          borderWidth: 5,
+        },
+      },
+      {
+        props: { variant: 'dashed', color: 'primary', size: 'large' },
+        styles: {
+          fontWeight: 600,
+        },
+      },
+    ],
+  },
+});
+
+export default function GlobalThemeVariants() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <ThemeProvider theme={inputTheme}>
+        <Button variant="dashed">Default</Button>
+        <Button variant="dashed" color="secondary">
+          Secondary
+        </Button>
+        <Button variant="dashed" color="primary">
+          Primary
+        </Button>
+        <Button variant="dashed" color="secondary" size="large">
+          Secondary large
+        </Button>
+        <Button variant="dashed" color="primary" size="large">
+          Primary large
+        </Button>
+      </ThemeProvider>
+    </div>
+  );
+}

docs/src/pages/customization/components/components.md

@@ -319,3 +319,41 @@ const theme = createMuiTheme({
 ```
 
 {{"demo": "pages/customization/components/GlobalThemeOverride.js"}}
+
+### Adding new component variants
+
+You can take advantage of the `variants` key of the `theme` to add new variants to Material-UI components.
+
+```jsx
+const theme = createMuiTheme({
+  variants: {
+    MuiButton: [
+      {
+        props: { variant: 'dashed' },
+        styles: {
+          padding: '5px 15px',
+          border: `5px dashed grey${blue[500]}`,
+        },
+      },
+      {
+        props: { variant: 'dashed', color: 'secondary' },
+        styles: {
+          border: `5px dashed ${red[500]}`,
+        },
+      },
+    ],
+  },
+});
+```
+
+If you are using TypeScript, you will need to specify your new variants/colors, using module augmentation.
+
+```tsx
+declare module '@material-ui/core/Button/Button' {
+  interface ButtonPropsVariantOverrides {
+    dashed: true;
+  }
+}
+```
+
+{{"demo": "pages/customization/components/GlobalThemeVariants.js"}}

packages/material-ui-styles/src/getStylesCreator/getStylesCreator.js

@@ -1,4 +1,5 @@
 import { deepmerge } from '@material-ui/utils';
+import propsToClassKey from '../propsToClassKeys';
 import noopTheme from './noopTheme';
 
 export default function getStylesCreator(stylesOrCreator) {
@@ -36,11 +37,15 @@ export default function getStylesCreator(stylesOrCreator) {
         throw err;
       }
 
-      if (!name || !theme.overrides || !theme.overrides[name]) {
+      if (
+        !name ||
+        ((!theme.overrides || !theme.overrides[name]) && (!theme.variants || !theme.variants[name]))
+      ) {
         return styles;
       }
 
-      const overrides = theme.overrides[name];
+      const overrides = (theme.overrides && theme.overrides[name]) || {};
+      const variants = (theme.variants && theme.variants[name]) || [];
       const stylesWithOverrides = { ...styles };
 
       Object.keys(overrides).forEach((key) => {
@@ -50,12 +55,22 @@ export default function getStylesCreator(stylesOrCreator) {
               [
                 'Material-UI: You are trying to override a style that does not exist.',
                 `Fix the \`${key}\` key of \`theme.overrides.${name}\`.`,
+                '',
+                'If you intentionally wanted to add a new key, please use the theme.variants option.',
               ].join('\n'),
             );
           }
         }
 
-        stylesWithOverrides[key] = deepmerge(stylesWithOverrides[key], overrides[key]);
+        stylesWithOverrides[key] = deepmerge(stylesWithOverrides[key] || {}, overrides[key]);
+      });
+
+      variants.forEach((definition) => {
+        const classKey = propsToClassKey(definition.props);
+        stylesWithOverrides[classKey] = deepmerge(
+          stylesWithOverrides[classKey] || {},
+          definition.styles,
+        );
       });
 
       return stylesWithOverrides;

packages/material-ui-styles/src/makeStyles/makeStyles.js

@@ -241,6 +241,23 @@ export default function makeStyles(stylesOrCreator, options = {}) {
       // eslint-disable-next-line react-hooks/rules-of-hooks
       React.useDebugValue(classes);
     }
+    if (process.env.NODE_ENV !== 'production') {
+      const whitelistedComponents = ['MuiButton'];
+
+      if (
+        name &&
+        whitelistedComponents.indexOf(name) >= 0 &&
+        props.variant &&
+        !classes[props.variant]
+      ) {
+        console.error(
+          [
+            `Material-UI: You are using a variant value [${props.variant}] for which you didn't define styles.`,
+            `Please use the \`theme.variants.${name}\` to define a new entry for this variant.`,
+          ].join('\n'),
+        );
+      }
+    }
 
     return classes;
   };

packages/material-ui-styles/src/propsToClassKeys/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './propsToClassKeys';
+export * from './propsToClassKeys';

packages/material-ui-styles/src/propsToClassKeys/index.js

@@ -0,0 +1 @@
+export { default } from './propsToClassKeys';

packages/material-ui-styles/src/propsToClassKeys/propsToClassKeys.d.ts

@@ -0,0 +1 @@
+export default function propsToClassKeys(props: object): string;

packages/material-ui-styles/src/propsToClassKeys/propsToClassKeys.js

@@ -0,0 +1,32 @@
+import MuiError from '@material-ui/utils/macros/MuiError.macro';
+
+// TODO: remove this once the capitalize method is moved to the @material-ui/utils package
+export function capitalize(string) {
+  if (typeof string !== 'string') {
+    throw new MuiError('Material-UI: capitalize(string) expects a string argument.');
+  }
+
+  return string.charAt(0).toUpperCase() + string.slice(1);
+}
+
+function isEmpty(string) {
+  return string.length === 0;
+}
+
+export default function propsToClassKey(props) {
+  const { variant, ...rest } = props;
+
+  let classKey = variant || '';
+
+  Object.keys(rest)
+    .sort()
+    .forEach((key) => {
+      if (key === 'color') {
+        classKey += isEmpty(classKey) ? props[key] : capitalize(props[key]);
+      } else {
+        classKey += `${isEmpty(classKey) ? key : capitalize(key)}${capitalize(props[key])}`;
+      }
+    });
+
+  return classKey;
+}

packages/material-ui-styles/src/withStyles/withStyles.js

@@ -5,6 +5,7 @@ import { chainPropTypes, getDisplayName } from '@material-ui/utils';
 import makeStyles from '../makeStyles';
 import getThemeProps from '../getThemeProps';
 import useTheme from '../useTheme';
+import propsToClassKey from '../propsToClassKeys';
 
 // Link a style sheet with a component.
 // It does not modify the component passed to it;
@@ -48,7 +49,7 @@ const withStyles = (stylesOrCreator, options = {}) => (Component) => {
     // The wrapper receives only user supplied props, which could be a subset of
     // the actual props Component might receive due to merging with defaultProps.
     // So copying it here would give us the same result in the wrapper as well.
-    const classes = useStyles({ ...Component.defaultProps, ...props });
+    let classes = useStyles({ ...Component.defaultProps, ...props });
 
     let theme;
     let more = other;
@@ -67,6 +68,25 @@ const withStyles = (stylesOrCreator, options = {}) => (Component) => {
       if (withTheme && !more.theme) {
         more.theme = theme;
       }
+
+      if (theme && theme.variants && theme.variants[name]) {
+        let variantsClasses = '';
+        const themeVariants = theme.variants[name];
+
+        themeVariants.forEach((themeVariant) => {
+          let isMatch = true;
+          Object.keys(themeVariant.props).forEach((key) => {
+            if (more[key] !== themeVariant.props[key]) {
+              isMatch = false;
+            }
+          });
+          if (isMatch) {
+            variantsClasses = `${variantsClasses} ${classes[propsToClassKey(themeVariant.props)]}`;
+          }
+        });
+
+        classes = { ...classes, root: `${classes.root} ${variantsClasses}` };
+      }
     }
 
     return <Component ref={innerRef || ref} classes={classes} {...more} />;