ready for review

Author: oliviertassinari

docs/src/pages/css-in-js/advanced/advanced.md

@@ -58,7 +58,7 @@ const DeepChild = withTheme(DeepChildRaw);
 ### Theme nesting
 
 You can nest multiple theme providers.
-This can be really useful when dealing with different area of your application that have distinct appearance from each other.
+This can be really useful when dealing with different areas of your application that have distinct appearance from each other.
 
 ```jsx
 <ThemeProvider theme={outerTheme}>
@@ -85,10 +85,10 @@ You can extend the outer theme by providing a function:
 
 ## JSS plugins
 
-JSS uses plugins to extend its core, allowing you to cherry-pick the features you need, 
+JSS uses plugins to extend its core, allowing you to cherry-pick the features you need,
 and only pay the performance overhead for what you are using.
 
-Not all the plugins are available in Material-UI by default. The following (which is a subset of 
+Not all the plugins are available in Material-UI by default. The following (which is a subset of
 [jss-preset-default](https://cssinjs.org/jss-preset-default/)) are included:
 
 - [jss-plugin-rule-value-function](https://cssinjs.org/jss-plugin-rule-value-function/)
@@ -140,7 +140,7 @@ const useStyles = makeStyles({
 });
 ```
 
-Note that this doesn't support selectors, or nested rules.
+Note that this doesn't support selectors or nested rules.
 
 {{"demo": "pages/css-in-js/advanced/StringTemplates.js"}}
 
@@ -333,45 +333,36 @@ Refer to [this example](https://github.com/mui-org/material-ui/blob/next/example
 
 ## Class names
 
-You may have noticed that the class names generated by `@material-ui/styles` are **non-deterministic**,
-so you can't rely on them to stay the same.
 The class names are generated by [the class name generator](/css-in-js/api/#creategenerateclassname-options-class-name-generator).
 
-Let's take the following style as an example:
+### Without a name
 
-```jsx
+By default, the class names generated by `@material-ui/styles` are **non-deterministic**, you can't rely on them to stay the same. Let's take the following style as an example:
+
+```js
 const useStyles = makeStyles({
   root: {
     opacity: 1,
   },
-}, {
-  name: 'AppBar',
 });
 ```
 
-This will generate a class name such as `AppBar-root-123`. However, the following CSS won't work:
-
-```css
-.AppBar-root-123 {
-  opacity: 0.6;
-}
-```
+This will generate a class name such as `makeStyles-root-123`.
 
-You have to use the `classes` property of a component to override them.
-The non-deterministic nature of the class names enables optimization for development and production –
-they are easy to debug in development, and as short as possible in production:
+You have to use the `classes` property of a component to override the class names.
+The non-deterministic nature of the class names enables style isolation.
 
-- In **development**, the class name will be: `.AppBar-root-123`, following this logic:
+- In **development**, the class name is: `.makeStyles-root-123`, following this logic:
 
 ```js
-const sheetName = 'AppBar';
+const sheetName = 'makeStyles';
 const ruleName = 'root';
 const identifier = 123;
 
 const className = `${sheetName}-${ruleName}-${identifier}`;
 ```
 
-- In **production**, the class name will be: `.jss123`, following this logic:
+- In **production**, the class name is: `.jss123`, following this logic:
 
 ```js
 const productionPrefix = 'jss';
@@ -380,8 +371,18 @@ const identifier = 123;
 const className = `${productionPrefix}-${identifier}`;
 ```
 
-If you don't like this default behavior, you can change it.
-JSS allows you to supply a [custom class name generator](https://cssinjs.org/jss-api/#generate-your-class-names).
+### With `@material-ui/core`
+
+The generated class names of the `@material-ui/core` components behave differently.
+The logic simplifies the style overrides.
+As soon as these conditions are met, the class names are **deterministic**:
+
+- Only one theme provider is used (no theme nesting).
+- The style sheet name starts with `Mui`.
+- The style rule is fully static (no style function).
+- The `disableGlobal` option of the class name generator is false (default).
+
+These conditions are with the most common use cases of `@material-ui/core`.
 
 ## Global CSS
 
@@ -397,32 +398,6 @@ You can also combine JSS generated class names with global ones.
 
 {{"demo": "pages/css-in-js/advanced/HybridGlobalCss.js"}}
 
-### Deterministic class names
-
-We provide an option to make the class names **deterministic** with the [`dangerouslyUseGlobalCSS`](/css-in-js/api/#creategenerateclassname-options-class-name-generator) option. When turned on, the class names will look like this:
-
-- development: `.AppBar-root`
-- production: `.AppBar-root`
-
-⚠️ **Be cautious when using `dangerouslyUseGlobalCSS`.**
-Relying on it for code running in production has the following implications:
-
-- It's harder to keep track of `classes` API changes between major releases.
-- Global CSS is inherently fragile.
-
-⚠️ When using `dangerouslyUseGlobalCSS` standalone (without Material-UI), you should name your style sheets using the `options` parameter:
-
-```jsx
-// Hook
-const useStyles = makeStyles(styles, { name: 'button' });
-
-// Styled-components
-const Button = styled(styles, { name: 'button' })(ButtonBase);
-
-// Higher-order component
-const Button = withStyles(styles, { name: 'button' })(ButtonBase);
-```
-
 ## CSS prefixes
 
 JSS uses feature detection to apply the correct prefixes.

docs/src/pages/css-in-js/api/api.md

@@ -9,9 +9,9 @@ A function which returns [a class name generator function](http://cssinjs.org/js
 #### Arguments
 
 1. `options` (*Object* [optional]):
-  - `options.dangerouslyUseGlobalCSS` (*Boolean* [optional]): Defaults to `false`. Makes the Material-UI class names deterministic.
-  - `options.productionPrefix` (*String* [optional]): Defaults to `'jss'`. The string used to prefix the class names in production.
-  - `options.seed` (*String* [optional]): Defaults to `''`. The string used to uniquely identify the generator. It can be used to avoid class name collisions when using multiple generators.
+  - `options.disableGlobal` (*Boolan* [optional]): Default to `false`. Disable the generation of deterministic class names.
+  - `options.productionPrefix` (*String* [optional]): Defaults to `'jss'`. The string used to prefix the class names in production. You can disable the minification in production by providing an empty string.
+  - `options.seed` (*String* [optional]): Defaults to `''`. The string used to uniquely identify the generator. It can be used to avoid class name collisions when using multiple generators in the same document.
 
 #### Returns
 
@@ -24,7 +24,6 @@ import React from 'react';
 import { StylesProvider, createGenerateClassName } from '@material-ui/styles';
 
 const generateClassName = createGenerateClassName({
-  dangerouslyUseGlobalCSS: true,
   productionPrefix: 'c',
 });
 
@@ -212,11 +211,11 @@ It should preferably be used at **the root of your component tree**.
 
 | Name | Type | Default | Description |
 |:-----|:-----|:--------|:------------|
-| <span class="prop-name required">children&nbsp;*</span> | <span class="prop-type">node</span> | | Your component tree. |
-| <span class="prop-name">disableGeneration</span> | <span class="prop-type">bool</span> | false | You can disable the generation of the styles with this option. It can be useful when traversing the React tree outside of the HTML rendering step on the server. Let's say you are using react-apollo to extract all the queries made by the interface server-side. You can significantly speed up the traversal with this property. |
-| <span class="prop-name">generateClassName</span> | <span class="prop-type">func</span> | | JSS's class name generator. |
-| <span class="prop-name">injectFirst</span> | <span class="prop-type">bool</span> | false | By default, the styles are injected last in the <head> element of your page. They gain more specificity than any other style sheet on your page e.g. CSS modules, styled components. If you want to override the Material-UI's styles, set this prop. |
-| <span class="prop-name">jss</span> | <span class="prop-type">object</span> | | JSS's instance. |
+| children&nbsp;* | node | | Your component tree. |
+| disableGeneration | bool | false | You can disable the generation of the styles with this option. It can be useful when traversing the React tree outside of the HTML rendering step on the server. Let's say you are using react-apollo to extract all the queries made by the interface server-side. You can significantly speed up the traversal with this property. |
+| generateClassName | func | | JSS's class name generator. |
+| injectFirst | bool | false | By default, the styles are injected last in the <head> element of your page. They gain more specificity than any other style sheet on your page e.g. CSS modules, styled components. If you want to override the Material-UI's styles, set this prop. |
+| jss | object | | JSS's instance. |
 
 #### Examples
 
@@ -243,8 +242,8 @@ It should preferably be used at **the root of your component tree**.
 
 | Name | Type | Default | Description |
 |:-----|:-----|:--------|:------------|
-| <span class="prop-name required">children&nbsp;*</span> | <span class="prop-type">node</span> | | Your component tree. |
-| <span class="prop-name required">theme&nbsp;*</span> | <span class="prop-type">union:&nbsp;object&nbsp;&#124;&nbsp;func</span> | | A theme object. You can provide a function to extend the outer theme. |
+| children&nbsp;* | node | | Your component tree. |
+| theme&nbsp;* | union:&nbsp;object&nbsp;&#124;&nbsp;func | | A theme object. You can provide a function to extend the outer theme. |
 
 #### Examples
 

docs/src/pages/demos/badges/CustomizedBadge.js

@@ -1,10 +1,10 @@
 import React from 'react';
 import IconButton from '@material-ui/core/IconButton';
 import Badge from '@material-ui/core/Badge';
-import { makeStyles } from '@material-ui/core/styles';
+import { withStyles } from '@material-ui/core/styles';
 import ShoppingCartIcon from '@material-ui/icons/ShoppingCart';
 
-const useStyles = makeStyles(theme => ({
+const StyledBadge = withStyles(theme => ({
   badge: {
     top: '50%',
     right: -3,
@@ -13,16 +13,14 @@ const useStyles = makeStyles(theme => ({
       theme.palette.type === 'light' ? theme.palette.grey[200] : theme.palette.grey[900]
     }`,
   },
-}));
+}))(Badge);
 
 function CustomizedBadge() {
-  const classes = useStyles();
-
   return (
     <IconButton aria-label="Cart">
-      <Badge badgeContent={4} color="primary" classes={{ badge: classes.badge }}>
+      <StyledBadge badgeContent={4} color="primary">
         <ShoppingCartIcon />
-      </Badge>
+      </StyledBadge>
     </IconButton>
   );
 }

docs/src/pages/demos/badges/CustomizedBadge.tsx

@@ -1,30 +1,26 @@
 import React from 'react';
 import IconButton from '@material-ui/core/IconButton';
 import Badge from '@material-ui/core/Badge';
-import { makeStyles, Theme, createStyles } from '@material-ui/core/styles';
+import { withStyles, Theme } from '@material-ui/core/styles';
 import ShoppingCartIcon from '@material-ui/icons/ShoppingCart';
 
-const useStyles = makeStyles((theme: Theme) =>
-  createStyles({
-    badge: {
-      top: '50%',
-      right: -3,
-      // The border color match the background color.
-      border: `2px solid ${
-        theme.palette.type === 'light' ? theme.palette.grey[200] : theme.palette.grey[900]
-      }`,
-    },
-  }),
-);
+const StyledBadge = withStyles((theme: Theme) => ({
+  badge: {
+    top: '50%',
+    right: -3,
+    // The border color match the background color.
+    border: `2px solid ${
+      theme.palette.type === 'light' ? theme.palette.grey[200] : theme.palette.grey[900]
+    }`,
+  },
+}))(Badge);
 
 function CustomizedBadge() {
-  const classes = useStyles();
-
   return (
     <IconButton aria-label="Cart">
-      <Badge badgeContent={4} color="primary" classes={{ badge: classes.badge }}>
+      <StyledBadge badgeContent={4} color="primary">
         <ShoppingCartIcon />
-      </Badge>
+      </StyledBadge>
     </IconButton>
   );
 }

docs/src/pages/demos/breadcrumbs/CustomizedBreadcrumbs.js

@@ -1,6 +1,5 @@
 import React from 'react';
-import PropTypes from 'prop-types';
-import { withStyles } from '@material-ui/core/styles';
+import { withStyles, makeStyles } from '@material-ui/core/styles';
 import { emphasize } from '@material-ui/core/styles/colorManipulator';
 import Paper from '@material-ui/core/Paper';
 import Breadcrumbs from '@material-ui/core/Breadcrumbs';
@@ -9,11 +8,8 @@ import Avatar from '@material-ui/core/Avatar';
 import HomeIcon from '@material-ui/icons/Home';
 import ExpandMoreIcon from '@material-ui/icons/ExpandMore';
 
-const styles = theme => ({
+const StyledBreadcrumb = withStyles(theme => ({
   root: {
-    padding: theme.spacing(1),
-  },
-  chip: {
     backgroundColor: theme.palette.grey[100],
     height: 24,
     color: theme.palette.grey[800],
@@ -26,30 +22,25 @@ const styles = theme => ({
       backgroundColor: emphasize(theme.palette.grey[300], 0.12),
     },
   },
-  avatar: {
-    background: 'none',
-    marginRight: -theme.spacing(1.5),
-  },
-});
+}))(props => <Chip {...props} />);
 
 function handleClick(event) {
   event.preventDefault();
   alert('You clicked a breadcrumb.'); // eslint-disable-line no-alert
 }
 
-function CustomBreadcrumb(props) {
-  const { classes, ...rest } = props;
-  return <Chip className={classes.chip} {...rest} />;
-}
-
-CustomBreadcrumb.propTypes = {
-  classes: PropTypes.object.isRequired,
-};
-
-const StyledBreadcrumb = withStyles(styles)(CustomBreadcrumb);
+const useStyles = makeStyles(theme => ({
+  root: {
+    padding: theme.spacing(1),
+  },
+  avatar: {
+    background: 'none',
+    marginRight: -theme.spacing(1.5),
+  },
+}));
 
-function CustomizedBreadcrumbs(props) {
-  const { classes } = props;
+function CustomizedBreadcrumbs() {
+  const classes = useStyles();
 
   return (
     <Paper elevation={0} className={classes.root}>
@@ -77,8 +68,4 @@ function CustomizedBreadcrumbs(props) {
   );
 }
 
-CustomizedBreadcrumbs.propTypes = {
-  classes: PropTypes.object.isRequired,
-};
-
-export default withStyles(styles)(CustomizedBreadcrumbs);
+export default CustomizedBreadcrumbs;