deprecation instead of breaking change

docs/src/pages/css-in-js/basics/NestedStylesHook.js

@@ -0,0 +1,29 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/styles';
+import Paper from '@material-ui/core/Paper';
+
+const useStyles = makeStyles({
+  root: {
+    padding: 16,
+    color: 'red',
+    '& p': {
+      color: 'green',
+      '& span': {
+        color: 'blue',
+      },
+    },
+  },
+});
+
+export default function NestedStylesHook() {
+  const classes = useStyles();
+  return (
+    <Paper className={classes.root}>
+      This is red since it is inside the paper.
+      <p>
+        This is green since it is inside the paragraph{' '}
+        <span>and this is blue since it is inside the span</span>
+      </p>
+    </Paper>
+  );
+}

docs/src/pages/css-in-js/basics/NestedStylesHook.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/styles';
+import Paper from '@material-ui/core/Paper';
+
+const useStyles = makeStyles({
+  root: {
+    padding: 16,
+    color: 'red',
+    '& p': {
+      color: 'green',
+      '& span': {
+        color: 'blue',
+      },
+    },
+  },
+});
+
+export default function NestedStylesHook() {
+  const classes = useStyles();
+  return (
+    <Paper className={classes.root}>
+      This is red since it is inside the paper.
+      <p>
+        This is green since it is inside the paragraph{' '}
+        <span>and this is blue since it is inside the span</span>
+      </p>
+    </Paper>
+  );
+}

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

@@ -126,6 +126,28 @@ export default withStyles(styles)(HigherOrderComponent);
 
 {{"demo": "pages/css-in-js/basics/HigherOrderComponent.js"}}
 
+## Nesting selectors
+
+You can nest selectors to target elements inside the current class or component.
+The following example is powered by the Hook API, it works the same way with the other APIs.
+
+```js
+const useStyles = makeStyles({
+  root: {
+    padding: 16,
+    color: 'red',
+    '& p': {
+      color: 'green',
+      '& span': {
+        color: 'blue'
+      }
+    }
+  },
+});
+```
+
+{{"demo": "pages/css-in-js/basics/NestedStylesHook.js"}}
+
 ## Adapting based on props
 
 You can pass a function ("interpolations") to a style property to adapt it based on its props.

docs/src/pages/demos/bottom-navigation/LabelBottomNavigation.tsx

@@ -0,0 +1,34 @@
+import React from 'react';
+import { makeStyles, Theme, createStyles } from '@material-ui/core/styles';
+import BottomNavigation from '@material-ui/core/BottomNavigation';
+import BottomNavigationAction from '@material-ui/core/BottomNavigationAction';
+import Icon from '@material-ui/core/Icon';
+import RestoreIcon from '@material-ui/icons/Restore';
+import FavoriteIcon from '@material-ui/icons/Favorite';
+import LocationOnIcon from '@material-ui/icons/LocationOn';
+
+const useStyles = makeStyles({
+  root: {
+    width: 500,
+  },
+});
+
+function LabelBottomNavigation() {
+  const classes = useStyles();
+  const [value, setValue] = React.useState('recents');
+
+  function handleChange(event: React.ChangeEvent<{}>, newValue: string) {
+    setValue(newValue);
+  }
+
+  return (
+    <BottomNavigation value={value} onChange={handleChange} className={classes.root}>
+      <BottomNavigationAction label="Recents" value="recents" icon={<RestoreIcon />} />
+      <BottomNavigationAction label="Favorites" value="favorites" icon={<FavoriteIcon />} />
+      <BottomNavigationAction label="Nearby" value="nearby" icon={<LocationOnIcon />} />
+      <BottomNavigationAction label="Folder" value="folder" icon={<Icon>folder</Icon>} />
+    </BottomNavigation>
+  );
+}
+
+export default LabelBottomNavigation;

docs/src/pages/demos/bottom-navigation/SimpleBottomNavigation.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { makeStyles, Theme, createStyles } from '@material-ui/core/styles';
+import BottomNavigation from '@material-ui/core/BottomNavigation';
+import BottomNavigationAction from '@material-ui/core/BottomNavigationAction';
+import RestoreIcon from '@material-ui/icons/Restore';
+import FavoriteIcon from '@material-ui/icons/Favorite';
+import LocationOnIcon from '@material-ui/icons/LocationOn';
+
+const useStyles = makeStyles({
+  root: {
+    width: 500,
+  },
+});
+
+function SimpleBottomNavigation() {
+  const classes = useStyles();
+  const [value, setValue] = React.useState(0);
+
+  return (
+    <BottomNavigation
+      value={value}
+      onChange={(event, newValue) => {
+        setValue(newValue);
+      }}
+      showLabels
+      className={classes.root}
+    >
+      <BottomNavigationAction label="Recents" icon={<RestoreIcon />} />
+      <BottomNavigationAction label="Favorites" icon={<FavoriteIcon />} />
+      <BottomNavigationAction label="Nearby" icon={<LocationOnIcon />} />
+    </BottomNavigation>
+  );
+}
+
+export default SimpleBottomNavigation;

docs/src/pages/utils/popper/popper.md

@@ -14,8 +14,10 @@ Some important features of the `Popper` component:
 - 📦 Less than [10 KB gzipped](/size-snapshot).
 - The children is [`Portal`](/utils/portal/) to the body of the document to avoid rendering problems.
 You can disable this behavior with `disablePortal`.
-- The scroll and click away aren't blocked like with the [`Popover`](/utils/popover/) component.
+- The scroll isn't blocked like with the [`Popover`](/utils/popover/) component.
 The placement of the popper updates with the available area in the viewport.
+- Clicking away does not hide the `Popper` component. 
+  If you need this behavior, you can use [`ClickAwayListener`](utils/click-away-listener/) - see the example in the [menu documentation section](/demos/menus/#menulist-composition).
 - The `anchorEl` is passed as the reference object to create a new `Popper.js` instance.
 
 ## Simple Popper

packages/material-ui/src/FilledInput/FilledInput.js

@@ -97,7 +97,6 @@ export const styles = theme => {
     /* Styles applied to the root element if `multiline={true}`. */
     multiline: {
       padding: '27px 12px 10px',
-      boxSizing: 'border-box', // Prevent padding issue with fullWidth.
     },
     /* Styles applied to the `input` element. */
     input: {

packages/material-ui/src/GridList/GridList.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import { StandardProps } from '..';
+
+export interface GridListProps
+  extends StandardProps<React.HTMLAttributes<HTMLUListElement>, GridListClassKey> {
+  cellHeight?: number | 'auto';
+  cols?: number;
+  component?: React.ElementType<GridListProps>;
+  spacing?: number;
+}
+
+export type GridListClassKey = 'root';
+
+declare const GridList: React.ComponentType<GridListProps>;
+
+export default GridList;

packages/material-ui/src/GridList/GridList.js

@@ -0,0 +1,17 @@
+import React from 'react';
+import warning from 'warning';
+import ImageList from '../ImageList';
+
+/**
+ * Deprecated, use ImageList instead.
+ */
+export default function GridList(props) {
+  warning(
+    false,
+    [
+      'Material-UI: the GridList component is deprecated.',
+      'The component was renamed to ImageList.',
+    ].join('\n'),
+  );
+  return <ImageList {...props} />;
+}

packages/material-ui/src/GridList/index.d.ts

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

packages/material-ui/src/GridList/index.js

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

packages/material-ui/src/GridListTile/GridListTile.d.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+import { StandardProps } from '..';
+
+export interface GridListTileProps
+  extends StandardProps<React.HTMLAttributes<HTMLLIElement>, GridListTileClassKey> {
+  cols?: number;
+  component?: React.ElementType<GridListTileProps>;
+  rows?: number;
+}
+
+export type GridListTileClassKey = 'root' | 'tile' | 'imgFullHeight' | 'imgFullWidth';
+
+declare const GridListTile: React.ComponentType<GridListTileProps>;
+
+export default GridListTile;

packages/material-ui/src/GridListTile/GridListTile.js

@@ -0,0 +1,17 @@
+import React from 'react';
+import warning from 'warning';
+import ImageListTile from '../ImageListTile';
+
+/**
+ * Deprecated, use ImageListTile instead.
+ */
+export default function GridListTile(props) {
+  warning(
+    false,
+    [
+      'Material-UI: the GridListTile component is deprecated.',
+      'The component was renamed to ImageListTile.',
+    ].join('\n'),
+  );
+  return <ImageListTile {...props} />;
+}

packages/material-ui/src/GridListTile/index.d.ts

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

packages/material-ui/src/GridListTile/index.js

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

packages/material-ui/src/GridListTileBar/GridListTileBar.d.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import { StandardProps } from '..';
+
+export interface GridListTileBarProps extends StandardProps<{}, GridListTileBarClassKey> {
+  actionIcon?: React.ReactNode;
+  actionPosition?: 'left' | 'right';
+  subtitle?: React.ReactNode;
+  title?: React.ReactNode;
+  titlePosition?: 'top' | 'bottom';
+}
+
+export type GridListTileBarClassKey =
+  | 'root'
+  | 'titlePositionBottom'
+  | 'titlePositionTop'
+  | 'rootSubtitle'
+  | 'titleWrap'
+  | 'titleWrapActionPosLeft'
+  | 'titleWrapActionPosRight'
+  | 'title'
+  | 'subtitle'
+  | 'actionIcon'
+  | 'actionIconActionPosLeft';
+
+declare const GridListTileBar: React.ComponentType<GridListTileBarProps>;
+
+export default GridListTileBar;

packages/material-ui/src/GridListTileBar/GridListTileBar.js

@@ -0,0 +1,17 @@
+import React from 'react';
+import warning from 'warning';
+import ImageListTileBar from '../ImageListTileBar';
+
+/**
+ * Deprecated, use ImageListTileBar instead.
+ */
+export default function GridListTileBar(props) {
+  warning(
+    false,
+    [
+      'Material-UI: the GridListTileBar component is deprecated.',
+      'The component was renamed to ImageListTileBar.',
+    ].join('\n'),
+  );
+  return <ImageListTileBar {...props} />;
+}

packages/material-ui/src/GridListTileBar/index.d.ts

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

packages/material-ui/src/GridListTileBar/index.js

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

packages/material-ui/src/InputBase/InputBase.js

@@ -37,6 +37,7 @@ export const styles = theme => {
       color: theme.palette.text.primary,
       fontSize: theme.typography.pxToRem(16),
       lineHeight: '1.1875em', // Reset (19px), match the native input line-height
+      boxSizing: 'border-box', // Prevent padding issue with fullWidth.
       cursor: 'text',
       display: 'inline-flex',
       alignItems: 'center',

packages/material-ui/src/OutlinedInput/OutlinedInput.js

@@ -53,7 +53,6 @@ export const styles = theme => {
     /* Styles applied to the root element if `multiline={true}`. */
     multiline: {
       padding: '18.5px 14px',
-      boxSizing: 'border-box', // Prevent padding issue with fullWidth.
     },
     /* Styles applied to the `NotchedOutline` element. */
     notchedOutline: {},