[docs] Document the CSS API (#12174)

* [docs] Document the CSS API

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

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],