Matt review

mui · Apr 24, 2019 · 8811cce · 8811cce
1 parent 5c711e4
commit 8811cce
Show file tree

Hide file tree

Showing 3 changed files with 40 additions and 42 deletions.
diff --git a/docs/src/pages/css-in-js/advanced/advanced.md b/docs/src/pages/css-in-js/advanced/advanced.md
@@ -83,9 +83,9 @@ You can extend the outer theme by providing a function:
 </ThemeProvider>
 ```
 
-## `classes` prop
+## Overriding styles - `classes` prop
 
-The `makeStyles` and `withStyles` APIs allow the creation of multiple style rules per style sheet. Each style rule has its own class name.
+The `makeStyles` (hook generator) and `withStyles` (HOC) APIs allow the creation of multiple style rules per style sheet. Each style rule has its own class name.
 The class names are provided to the component with the `classes` variable.
 The is particularly useful when styling nested elements in a component.
 
@@ -96,42 +96,42 @@ const useStyles = makeStyles({
   label: {}, // a nested style rule
 });
 
-export default function Nested(props) {
-  const classes = useStyles(props); // { root: 'jss1', label: 'jss2' }
+function Nested(props) {
+  const classes = useStyles();
   return (
-    <button className={classes.root}>
-      <span className={classes.label}>
+    <button className={classes.root}> // 'jss1'
+      <span className={classes.label}> // 'jss2'
         nested
       </span>
     </button>
   );
 }
 
-export default function Parent() {
-  return <Nested classes={{ label: 'my-label' }} />
+function Parent() {
+  return <Nested />
 }
 ```
 
 However, the class names are often non-deterministic. How can a parent component override the style of a nested element?
 
 ### withStyles
 
-This is the simplest case, the wrapped component accepts a `classes` prop.
-It simply merge the class names provided.
+This is the simplest case. the wrapped component accepts a `classes` prop,
+it simply merges the class names provided with the style sheet.
 
 ```jsx
-const useStyles = withStyles({
-  root: {},
-  label: {},
-})(props => (
-  <button className={props.classes.root}>
-    <span className={props.classes.label}> // 'jss2 my-label'
-      nested
+const Nested = withStyles({
+  root: {}, // a style rule
+  label: {}, // a nested style rule
+})({ classes }) => (
+  <button className={classes.root}>
+    <span className={classes.label}> // 'jss2 my-label'
+      Nested
     </span>
   </button>
 ));
 
-export default function Parent() {
+function Parent() {
   return <Nested classes={{ label: 'my-label' }} />
 }
 ```
@@ -142,11 +142,11 @@ The hook API requires a bit more work. You have to forward the parent props to t
 
 ```jsx
 const useStyles = makeStyles({
-  root: {},
-  label: {},
+  root: {}, // a style rule
+  label: {}, // a nested style rule
 });
 
-export default function Nested(props) {
+function Nested(props) {
   const classes = useStyles(props);
   return (
     <button className={classes.root}>
@@ -157,7 +157,7 @@ export default function Nested(props) {
   );
 }
 
-export default function Parent() {
+function Parent() {
   return <Nested classes={{ label: 'my-label' }} />
 }
 ```
@@ -219,7 +219,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"}}
 
@@ -414,9 +414,9 @@ Refer to [this example project](https://github.com/mui-org/material-ui/blob/next
 
 The class names are generated by [the class name generator](/css-in-js/api/#creategenerateclassname-options-class-name-generator).
 
-### Without a name
+### Default
 
-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:
+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({
@@ -428,7 +428,7 @@ const useStyles = makeStyles({
 
 This will generate a class name such as `makeStyles-root-123`.
 
-You have to use the `classes` property of a component to override the styles.
+You have to use the `classes` prop of a component to override the styles.
 The non-deterministic nature of the class names enables style isolation.
 
 - In **development**, the class name is: `.makeStyles-root-123`, following this logic:
@@ -453,15 +453,14 @@ const className = `${productionPrefix}-${identifier}`;
 ### With `@material-ui/core`
 
 The generated class names of the `@material-ui/core` components behave differently.
-As soon as these conditions are met, the class names are **deterministic**.
+When the following conditions are met, the class names are **deterministic**:
 
-- Only one theme provider is used: **no theme nesting**.
-- The style sheet has a name and starts with `Mui`: all the Material-UI components.
-- The `disableGlobal` option of the [class name generator](/css-in-js/api/#creategenerateclassname-options-class-name-generator) is `false`: the default.
+- Only one theme provider is used (**No theme nesting**)
+- The style sheet has a name that starts with `Mui`. (All Material-UI components)
+- The `disableGlobal` option of the [class name generator](/css-in-js/api/#creategenerateclassname-options-class-name-generator) is `false`. (The default)
 
 These conditions are met with the most common use cases of `@material-ui/core`.
-It's almost like we were providing default values for the `classes` API.
-For instance, this style sheet generates the following class names you can override:
+For instance, this style sheet:
 
 ```jsx
 const useStyles = makeStyles({
@@ -479,7 +478,7 @@ const useStyles = makeStyles({
 }, { name: 'MuiButton' });
 ```
 
-The CSS output:
+generates the following class names you that can override:
 
 ```css
 .MuiButton { /* … */ }
@@ -492,8 +491,7 @@ The CSS output:
 
 *This is a simplification of the `@material-ui/core/Button` component's style sheet.*
 
-The customization the TextField can be cumbersome with the [`classes` API](#classes-prop)
-when you have to provide each class name value manually.
+Customization of the TextField can be cumbersome with the [`classes` API](#overriding-styles-classes-prop), where you have to define the the classes prop.
 It's easier to use the default values, as described above. For example:
 
 ```jsx
@@ -524,7 +522,8 @@ const StyledTextField = styled(TextField)`
 
 ### `jss-plugin-global`
 
-The [`jss-plugin-global`](#jss-plugins) plugin is installed in the default preset. You can use it to define global class names.
+The [`jss-plugin-global`](#jss-plugins) plugin is installed in the default preset.
+You can use it to define global class names.
 
 {{"demo": "pages/css-in-js/advanced/GlobalCss.js"}}
 

diff --git a/docs/src/pages/css-in-js/api/api.md b/docs/src/pages/css-in-js/api/api.md
@@ -214,7 +214,7 @@ It should preferably be used at **the root of your component tree**.
 | 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. |
+| injectFirst | bool | false | By default, the styles are injected last in the <head> element of the page. As a result, they gain more specificity than any other style sheet. If you want to override Material-UI's styles, set this prop. |
 | jss | object | | JSS's instance. |
 
 #### Examples

diff --git a/packages/material-ui-styles/src/StylesProvider/StylesProvider.js b/packages/material-ui-styles/src/StylesProvider/StylesProvider.js
@@ -69,18 +69,17 @@ StylesProvider.propTypes = {
    * 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.
+   * the queries made by the interface server-side - you can significantly speed up the traversal with this prop.
    */
   disableGeneration: PropTypes.bool,
   /**
    * JSS's class name generator.
    */
   generateClassName: PropTypes.func,
   /**
-   * 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.
+   * By default, the styles are injected last in the <head> element of the page.
+   * As a result, they gain more specificity than any other style sheet.
+   * If you want to override Material-UI's styles, set this prop.
    */
   injectFirst: PropTypes.bool,
   /**