[docs] Document the CSS API (#12174)

* [docs] Document the CSS API

* Attempt to document the Slider props, add exception for Select

Author: mbrookes

docs/scripts/buildApi.js

@@ -83,9 +83,11 @@ function buildDocs(options) {
 
   // eslint-disable-next-line global-require, import/no-dynamic-require
   const component = require(componentObject.filename);
+  const name = path.parse(componentObject.filename).name;
   const styles = {
     classes: [],
     name: null,
+    descriptions: {},
   };
 
   if (component.styles && component.default.options) {
@@ -94,6 +96,29 @@ function buildDocs(options) {
       className => !className.match(/^(@media|@keyframes)/),
     );
     styles.name = component.default.options.name;
+
+    let styleSrc = src;
+    // Exception for Select where the classes are imported from NativeSelect
+    if (name === 'Select') {
+      styleSrc = readFileSync(
+        componentObject.filename.replace('Select/Select', 'NativeSelect/NativeSelect'),
+        'utf8',
+      );
+    }
+
+    /**
+     * Collect classes comments from the source
+     */
+    const stylesRegexp = /export const styles.*\n(.*\n)*};\n\n/;
+    const styleRegexp = /\/\* (.*) \*\/\n\s*(\w*)/g;
+    // Extract the styles section from the source
+    const stylesSrc = stylesRegexp.exec(styleSrc);
+    if (stylesSrc) {
+      // Extract individual classes and descriptions
+      stylesSrc[0].replace(styleRegexp, (match, desc, key) => {
+        styles.descriptions[key] = desc;
+      });
+    }
   }
 
   let reactAPI;
@@ -104,7 +129,7 @@ function buildDocs(options) {
     throw err;
   }
 
-  reactAPI.name = path.parse(componentObject.filename).name;
+  reactAPI.name = name;
   reactAPI.styles = styles;
   reactAPI.pagesMarkdown = pagesMarkdown;
   reactAPI.src = src;
@@ -147,7 +172,7 @@ export default withRoot(Page);
 `,
     );
 
-    console.log('Built markdown docs for', componentObject.filename);
+    console.log('Built markdown docs for', reactAPI.name);
   });
 }
 

docs/src/modules/utils/generateMarkdown.js

@@ -239,11 +239,29 @@ function generateClasses(reactAPI) {
     throw new Error(`Missing styles name on ${reactAPI.name} component`);
   }
 
+  let text = '';
+  if (Object.keys(reactAPI.styles.descriptions).length) {
+    text = `
+| Name | Description |
+|:-----|:------------|\n`;
+    text += reactAPI.styles.classes
+      .map(
+        className =>
+          `| <span class="prop-name">${className}</span> | ${
+            reactAPI.styles.descriptions[className] ? reactAPI.styles.descriptions[className] : ''
+          }`,
+      )
+      .join('\n');
+  } else {
+    text = reactAPI.styles.classes.map(className => `- \`${className}\``).join('\n');
+  }
+
   return `## CSS API
 
 You can override all the class names injected by Material-UI thanks to the \`classes\` property.
 This property accepts the following keys:
-${reactAPI.styles.classes.map(className => `- \`${className}\``).join('\n')}
+
+${text}
 
 Have a look at [overriding with classes](/customization/overrides#overriding-with-classes) section
 and the [implementation of the component](${SOURCE_CODE_ROOT_URL}${normalizePath(

packages/material-ui-lab/src/Slider/Slider.js

@@ -8,7 +8,7 @@ import ButtonBase from '@material-ui/core/ButtonBase';
 import { fade } from '@material-ui/core/styles/colorManipulator';
 import clamp from '../utils/clamp';
 
-export const style = theme => {
+export const styles = theme => {
   const commonTransitionsOptions = {
     duration: theme.transitions.duration.short,
     easing: theme.transitions.easing.easeOut,
@@ -29,7 +29,7 @@ export const style = theme => {
   };
 
   return {
-    // /* Styles for root node */
+    /* Styles applied to the root element. */
     root: {
       position: 'relative',
       width: '100%',
@@ -50,13 +50,14 @@ export const style = theme => {
         transform: 'scaleY(-1)',
       },
     },
+    /* Styles applied to the container element. */
     container: {
       position: 'relative',
       '&$vertical': {
         height: '100%',
       },
     },
-    /* Tracks styles */
+    /* Styles applied to the track elements. */
     track: {
       position: 'absolute',
       transform: 'translate(0, -50%)',
@@ -79,6 +80,7 @@ export const style = theme => {
         backgroundColor: colors.focused,
       },
     },
+    /* Styles applied to the track element before the thumb. */
     trackBefore: {
       zIndex: 1,
       left: 0,
@@ -88,6 +90,7 @@ export const style = theme => {
         backgroundColor: colors.primary,
       },
     },
+    /* Styles applied to the track element after the thumb. */
     trackAfter: {
       right: 0,
       backgroundColor: colors.secondary,
@@ -96,7 +99,7 @@ export const style = theme => {
         bottom: 0,
       },
     },
-    /* Thumb styles  */
+    /* Styles applied to the thumb element. */
     thumb: {
       position: 'absolute',
       zIndex: 2,
@@ -137,13 +140,20 @@ export const style = theme => {
         height: 17,
       },
     },
+    /* Class applied to the root element to trigger JSS nested styles if `reverse={true}` . */
+    reverse: {},
+    /* Class applied to the track and thumb elements to trigger JSS nested styles if `disabled`. */
+    disabled: {},
+    /* Class applied to the track and thumb elements to trigger JSS nested styles if `jumped`. */
+    jumped: {},
+    /* Class applied to the track and thumb elements to trigger JSS nested styles if `focused`. */
     focused: {},
+    /* Class applied to the track and thumb elements to trigger JSS nested styles if `activated`. */
     activated: {},
-    disabled: {},
-    zero: {},
+    /* Class applied to the root, track and container to trigger JSS nested styles if `vertical`. */
     vertical: {},
-    reverse: {},
-    jumped: {},
+    /* Class applied to the thumb to trigger nested styles if `value` = `min` . */
+    zero: {},
   };
 };
 
@@ -417,7 +427,7 @@ class Slider extends React.Component {
       [classes.activated]: !disabled && currentState === 'activated',
     };
 
-    const rootClasses = classNames(
+    const className = classNames(
       classes.root,
       {
         [classes.vertical]: vertical,
@@ -452,7 +462,7 @@ class Slider extends React.Component {
     return (
       <Component
         role="slider"
-        className={rootClasses}
+        className={className}
         aria-valuenow={value}
         aria-valuemin={min}
         aria-valuemax={max}
@@ -555,4 +565,4 @@ Slider.defaultProps = {
   component: 'div',
 };
 
-export default withStyles(style, { name: 'MuiSlider', withTheme: true })(Slider);
+export default withStyles(styles, { name: 'MuiSlider', withTheme: true })(Slider);

packages/material-ui-lab/src/SpeedDial/SpeedDial.js

@@ -10,17 +10,20 @@ import { duration } from '@material-ui/core/styles/transitions';
 import Button from '@material-ui/core/Button';
 import { isMuiElement } from '@material-ui/core/utils/reactHelpers';
 
-const styles = {
+export const styles = {
+  /* Styles applied to the root element. */
   root: {
     zIndex: 1050,
     display: 'flex',
     flexDirection: 'column-reverse', // Place the Actions above the FAB.
   },
+  /* Styles applied to the actions (`children` wrapper) element. */
   actions: {
     display: 'flex',
     flexDirection: 'column-reverse', // Display the first action at the bottom.
     marginBottom: 16,
   },
+  /* Styles applied to the actions (`children` wrapper) element if `open={false}`. */
   actionsClosed: {
     transition: 'top 0s linear 0.2s',
   },
@@ -51,8 +54,9 @@ class SpeedDial extends React.Component {
         actions.firstChild.firstChild.focus();
 
         // This determines which key focuses the next / previous action.
-        // For example, if a visually impaired user presses down to select the first action
-        // (i.e. following DOM ordering), down will select the next action, and up the previous.
+        // For example, if a user presses down to select the first action
+        // (i.e. following DOM ordering rather than visual ordering),
+        // down will select the next action, and up the previous.
         if (nextKey == null) {
           this.setState({ nextKey: key });
           this.setState({ prevKey: key === 'up' ? 'down' : 'up' });
@@ -268,4 +272,4 @@ SpeedDial.defaultProps = {
   },
 };
 
-export default withStyles(styles)(SpeedDial);
+export default withStyles(styles, { name: 'MuiSpeedDial' })(SpeedDial);

packages/material-ui-lab/src/SpeedDialAction/SpeedDialAction.js

@@ -5,10 +5,12 @@ import { withStyles } from '@material-ui/core/styles';
 import Button from '@material-ui/core/Button';
 import Tooltip from '@material-ui/core/Tooltip';
 
-const styles = theme => ({
+export const styles = theme => ({
+  /* Styles applied to the root (`Tooltip`) component. */
   root: {
     position: 'relative',
   },
+  /* Styles applied to the `Button` component. */
   button: {
     margin: 8,
     color: theme.palette.text.secondary,
@@ -17,6 +19,7 @@ const styles = theme => ({
     })}, opacity 0.8s`,
     opacity: 1,
   },
+  /* Styles applied to the `Button` component if `open={false}`. */
   buttonClosed: {
     opacity: 0,
     transform: 'scale(0)',
@@ -127,4 +130,4 @@ SpeedDialAction.defaultProps = {
   open: false,
 };
 
-export default withStyles(styles)(SpeedDialAction);
+export default withStyles(styles, { name: 'MuiSpeedDialAction' })(SpeedDialAction);

packages/material-ui-lab/src/SpeedDialIcon/SpeedDialIcon.js

@@ -4,22 +4,26 @@ import classNames from 'classnames';
 import { withStyles } from '@material-ui/core/styles';
 import AddIcon from '../internal/svg-icons/Add';
 
-const styles = theme => ({
+export const styles = theme => ({
+  /* Styles applied to the root element. */
   root: {
     height: 24,
   },
+  /* Styles applied to the icon component. */
   icon: {
     transition: theme.transitions.create(['transform', 'opacity'], {
       duration: theme.transitions.duration.short,
     }),
   },
+  /* Styles applied to the icon component if `open={true}`. */
   iconOpen: {
     transform: 'rotate(45deg)',
   },
-  // Style applied to the icon if there is an openIcon, when the SpeedDial is open
+  /* Styles applied to the icon when and `openIcon` is provided & if `open={true}`. */
   iconWithOpenIconOpen: {
     opacity: 0,
   },
+  /* Styles applied to the `openIcon` if provided. */
   openIcon: {
     position: 'absolute',
     transition: theme.transitions.create(['transform', 'opacity'], {
@@ -28,6 +32,7 @@ const styles = theme => ({
     opacity: 0,
     transform: 'rotate(-45deg)',
   },
+  /* Styles applied to the `openIcon` if provided & if `open={true}` */
   openIconOpen: {
     transform: 'rotate(0deg)',
     opacity: 1,
@@ -81,4 +86,4 @@ SpeedDialIcon.propTypes = {
 
 SpeedDialIcon.muiName = 'SpeedDialIcon';
 
-export default withStyles(styles)(SpeedDialIcon);
+export default withStyles(styles, { name: 'MuiSpeedDialIcon' })(SpeedDialIcon);

packages/material-ui-lab/src/ToggleButton/ToggleButton.js

@@ -8,6 +8,7 @@ import { fade } from '@material-ui/core/styles/colorManipulator';
 import ButtonBase from '@material-ui/core/ButtonBase';
 
 export const styles = theme => ({
+  /* Styles applied to the root element. */
   root: {
     ...theme.typography.button,
     height: 32,
@@ -28,26 +29,20 @@ export const styles = theme => ({
         backgroundColor: 'transparent',
       },
     },
-
     '&:not(:first-child)': {
       borderTopLeftRadius: 0,
       borderBottomLeftRadius: 0,
     },
-
     '&:not(:last-child)': {
       borderTopRightRadius: 0,
       borderBottomRightRadius: 0,
     },
   },
-  label: {
-    width: '100%',
-    display: 'inherit',
-    alignItems: 'inherit',
-    justifyContent: 'inherit',
-  },
+  /* Styles applied to the root element if `disabled={true}`. */
   disabled: {
     color: fade(theme.palette.action.disabled, 0.12),
   },
+  /* Styles applied to the root element if `selected={true}`. */
   selected: {
     color: theme.palette.action.active,
     '&:after': {
@@ -65,7 +60,6 @@ export const styles = theme => ({
       backgroundColor: 'currentColor',
       opacity: 0.38,
     },
-
     '& + &:before': {
       content: '""',
       display: 'block',
@@ -81,6 +75,13 @@ export const styles = theme => ({
       opacity: 0.12,
     },
   },
+  /* Styles applied to the `label` wrapper element. */
+  label: {
+    width: '100%',
+    display: 'inherit',
+    alignItems: 'inherit',
+    justifyContent: 'inherit',
+  },
 });
 
 class ToggleButton extends React.Component {

packages/material-ui-lab/src/ToggleButton/ToggleButtonGroup.js

@@ -6,13 +6,14 @@ import hasValue from './hasValue';
 import isValueSelected from './isValueSelected';
 
 export const styles = theme => ({
+  /* Styles applied to the root element. */
   root: {
     transition: theme.transitions.create('background,box-shadow'),
     background: 'transparent',
     borderRadius: 2,
     overflow: 'hidden',
   },
-
+  /* Styles applied to the root element if `selected={true}` or `selected="auto" and `value` set. */
   selected: {
     background: theme.palette.background.paper,
     boxShadow: theme.shadows[2],