Merge branch 'master' into jssToTssReact

.codesandbox/ci.json

@@ -28,6 +28,7 @@
     "@mui/styled-engine-sc": "packages/mui-styled-engine-sc/build",
     "@mui/system": "packages/mui-system/build",
     "@mui/private-theming": "packages/mui-private-theming/build",
+    "@mui/private-classnames": "packages/mui-private-classnames/build",
     "@mui/types": "packages/mui-types/build",
     "@mui/utils": "packages/mui-utils/build",
     "@mui/base": "packages/mui-base/build",

CHANGELOG.md

@@ -1,5 +1,106 @@
 # [Versions](https://mui.com/versions/)
 
+## 5.7.0
+
+<!-- generated comparing v5.6.4..master -->
+
+_May 10, 2022_
+
+A big thanks to the 27 contributors who made this release possible. Here are some highlights ✨:
+
+🛠 This release is all about supporting CSS variables in many Material UI components.
+Kudos to all contributors!
+
+### `@mui/[email protected]`
+
+- [StepLabel, StepIcon] Add support for CSS variables (#32609) @vicasas
+- [Table, TableRow] Add support for CSS variables (#32614) @vicasas
+- [AppBar] Add a logo component for the responsive app bar demo (#32374) @ameetmadan
+- [Autocomplete] Fix clearing single array values (#32626) @mikepricedev
+- [Autocomplete] Fix keep listbox open on left/right keys when inputValue is not empty (#31407) @alisasanib
+- [Autocomplete] Add support for CSS variables (#32598) @ZeeshanTamboli
+- [Autocomplete] Render `endAdornment` only when necessary (#32386) @g1eny0ung
+- [ButtonGroup] Add support for CSS variables (#32498) @vicasas
+- [CardActionArea] Add support for CSS variables (#32554) @vicasas
+- [ClickAwayListener] Allow pointer up/down events to event handler (#32264) @vladjerca
+- [CssBaseline] Add support for CSS vars (#32618) @haneenmahd
+- [Dialog] Add support for CSS variables (#32555) @vicasas
+- [Divider] Add support for CSS variables (#32519) @vicasas
+- [Drawer] Add support for CSS variables (#32565) @nghiamvt
+- [Fab] Add support for CSS variables (#32564) @alisasanib
+- [FormControlLabel] Add support for CSS variables (#32588) @elliefoote
+- [FormHelperText] Add support for CSS variables (#32596) @ZeeshanTamboli
+- [FormLabel] Add support for CSS variables (#32602) @ZeeshanTamboli
+- [Icon] Add support for CSS variables (#32595) @Jamaalwbrown
+- [IconButton] Add support for CSS variables (#32590) @Ariyapong
+- [ImageListItemBar] Add support for CSS variables (#32578) @vicasas
+- [Input] Support CSS variables (#32128) @ivan-ngchakming
+- [InputAdornment] Add support CSS variables (#32607) @vicasas
+- [Link] Fix style overrides color prop (#32653) @siriwatknp
+- [ListItem] Add support for CSS variables (#32580) @dan-mba
+- [ListItemButton] Add support for CSS variables (#32582) @dan-mba
+- [ListItemIcon] Add support for CSS variables (#32583) @dan-mba
+- [ListSubheader] Add support for CSS variables (#32584) @dan-mba
+- [MenuItem] Add support for CSS variables (#32561) @nghiamvt
+- [MobileStepper] Add support for CSS vars (#32606) @haneenmahd
+- [Modal] Add support for CSS variables (#32605) @haneenmahd
+- [PaginationItem] Add support for CSS vars (#32612) @haneenmahd
+- [Rating] Add support for CSS variables (#32556) @vicasas
+- [Snackbar] Add support for CSS variables (#32603) @gin1314
+- [SpeedDial] Add support for CSS variables (#32613) @alisasanib
+- [Stepper] Export useStepperContext (#31398) @pzi
+- [SvgIcon] Add support for CSS variables (#32610) @vicasas
+- [TablePagination] Add support for CSS variables (#32615) @haneenmahd
+- [TableSortLabel]: Add support for CSS vars (#32616) @haneenmahd
+- [Tabs] Add support for CSS variables (#32547) @ZeeshanTamboli
+- [ToggleButton] Add support for CSS variables (#32600) @Ariyapong
+- [ToggleButtonGroup] Add support for CSS variables (#32617) @haneenmahd
+- [Tooltip] Add support for CSS variables (#32594) @gin1314
+
+### `@mui/[email protected]`
+
+- [System] Support CSS variables for iframes & custom nodes (#32496) @siriwatknp
+
+### `@mui/[email protected]`
+
+- [ButtonUnstyled] Fix keyboard navigation on customized elements (#32204) @michaldudak
+
+### `@mui/[email protected]`
+
+- [classnames] Add new package for classnames utils (#32502) @mnajdova
+
+### Docs
+
+- [docs] Correct links to prevent 301 redirects (#32692) @michaldudak
+- [docs] Move, split, and revise "Unstyled components" page (#32562) @samuelsycamore
+- [docs] Nest `ListItemButton` in `ListItem` in the Drawer examples (#31987) @stefanprobst
+- [docs] Apply callouts in the Material UI docs (#32567) @danilo-leal
+- [docs] Show product identifier on new X pages (#32657) @cherniavskii
+- [docs] Fix copy button childNode not found (#32652) @siriwatknp
+- [docs] Split install commands in isolated code blocks (#32566) @danilo-leal
+- [docs] Base Switch style revisions and final review (#32376) @samuelsycamore
+- [docs] Adds Badge link to Base doc nav (#32619) @samuelsycamore
+- [docs] Base Installation style revisions and final review (#32483) @samuelsycamore
+- [docs] Fix broken redirection (#32581) @oliviertassinari
+- [docs] Allows to use `import '<library name>'` in demonstrations (#32492) @alexfauquette
+- [docs] Hide copy button on search icon dialog (#32577) @siriwatknp
+- [docs] Use full API link for ThemeProvider (#32549) @jcvidiri
+- [Joy] Add principles page (#32648) @siriwatknp
+- [Joy] Add Button page (#32576) @siriwatknp
+- [Joy] Add "Quick start" and "Tutorial" pages (#32383) @siriwatknp
+- [website] Add store to the footer and "hiring" chip adjustment (#32650) @danilo-leal
+- [website] Optimize conversion to store (#32646) @oliviertassinari
+- [website] Remove copy button on marketing pages (#32649) @siriwatknp
+- [website] Add missing space in copy label (#32638) @flaviendelangle
+
+### Core
+
+- [core] Security updates (#32636) @michaldudak
+- [core] Fix `docs:dev` not working after upgrading `next` to 12.1.0 (#32552) @cherniavskii
+- [core] Update minimist to fix security vulnerability (#32575) @michaldudak
+
+All contributors of this release in alphabetical order: @alexfauquette, @alisasanib, @ameetmadan, @Ariyapong, @cherniavskii, @dan-mba, @danilo-leal, @elliefoote, @flaviendelangle, @g1eny0ung, @gin1314, @haneenmahd, @ivan-ngchakming, @Jamaalwbrown, @jcvidiri, @michaldudak, @mikepricedev, @mnajdova, @nghiamvt, @oliviertassinari, @pzi, @samuelsycamore, @siriwatknp, @stefanprobst, @vicasas, @vladjerca, @ZeeshanTamboli
+
 ## 5.6.4
 
 <!-- generated comparing v5.6.3..master -->

babel.config.js

@@ -18,6 +18,7 @@ const defaultAlias = {
   '@mui/styles': resolveAliasPath('./packages/mui-styles/src'),
   '@mui/system': resolveAliasPath('./packages/mui-system/src'),
   '@mui/private-theming': resolveAliasPath('./packages/mui-private-theming/src'),
+  '@mui/private-classnames': resolveAliasPath('./packages/mui-private-classnames/src'),
   '@mui/base': resolveAliasPath('./packages/mui-base/src'),
   '@mui/utils': resolveAliasPath('./packages/mui-utils/src'),
   '@mui/material-next': resolveAliasPath('./packages/mui-material-next/src'),

benchmark/package.json

@@ -15,9 +15,9 @@
     "@emotion/react": "^11.9.0",
     "@emotion/styled": "^11.8.1",
     "@mdx-js/react": "^2.1.1",
-    "@mui/material": "^5.6.4",
-    "@mui/styles": "^5.6.2",
-    "@mui/system": "^5.6.4",
+    "@mui/material": "^5.7.0",
+    "@mui/styles": "^5.7.0",
+    "@mui/system": "^5.7.0",
     "@styled-system/css": "^5.1.5",
     "benchmark": "^2.1.4",
     "playwright": "^1.17.1",

docs/babel.config.js

@@ -25,6 +25,7 @@ const alias = {
   // '@mui/styled-engine': '../packages/mui-styled-engine-sc/src',
   '@mui/system': '../packages/mui-system/src',
   '@mui/private-theming': '../packages/mui-private-theming/src',
+  '@mui/private-classnames': '../packages/mui-private-classnames/src',
   '@mui/utils': '../packages/mui-utils/src',
   '@mui/base': '../packages/mui-base/src',
   '@mui/material-next': '../packages/mui-material-next/src',

docs/data/base/components/button/button.md

@@ -49,7 +49,7 @@ Instead, `aria-disabled` is used, which makes the button focusable.
 
 This should be used whenever the disabled button needs to be read by screen readers.
 
-MUI Base uses this prop internally in [menu items](/base/react-menu), making it possible to use the keyboard to navigate to disabled items (in compliance with [ARIA guidelines](https://www.w3.org/TR/wai-aria-practices-1.2/#h-note-17)).
+MUI Base uses this prop internally in [menu items](/base/react-menu/), making it possible to use the keyboard to navigate to disabled items (in compliance with [ARIA guidelines](https://www.w3.org/TR/wai-aria-practices-1.2/#h-note-17)).
 
 {{"demo": "UnstyledButtonsDisabledFocus.js"}}
 

docs/data/base/components/trap-focus/trap-focus.md

@@ -10,7 +10,7 @@ packageName: '@mui/base'
 
 <p class="description">The <code>TrapFocus</code> component prevents the user's focus from escaping its children components.</p>
 
-`TrapFocus` is a utility component that is useful when implementing an overlay such as a [modal dialog](/base/react-modal), which should block all interactions outside of it while open.
+`TrapFocus` is a utility component that is useful when implementing an overlay such as a [modal dialog](/base/react-modal/), which should block all interactions outside of it while open.
 
 {{"component": "modules/components/ComponentLinkHeader.js", "design": false}}
 

docs/data/base/getting-started/customization/customization.md

@@ -0,0 +1,83 @@
+# Customizing MUI Base components
+
+<p class="description">There are several ways to customize MUI Base components, from applying custom CSS rules to building fully custom components using hooks.</p>
+
+With MUI Base, you have the freedom to decide how much you want to customize a component's structure and style.
+
+This document reviews the three levels of customization that are available: applying custom CSS rules, overriding default subcomponent slots, and using hooks to build fully custom components.
+
+## Applying custom CSS rules
+
+If you're happy with the default structure of a component's rendered HTML, you can apply custom styles to the component's classes.
+
+Each component has its own set of classes.
+Some classes are **static**, which is to say that they are always present on the component.
+Others are applied **conditionally**—like `Mui-disabled`, for example, which is only present when a component is disabled.
+
+Each component's API documentation lists all classes that the component uses.
+Additionally, you can import a `[componentName]Classes` object that describes all the classes a given component uses, as the following demo illustrates:
+
+{{"demo": "StylingCustomCss.js", "defaultCodeOpen": true}}
+
+## Overriding subcomponent slots
+
+If you want to make changes to a component's rendered HTML structure, you can override the default subcomponents ("slots") using the `components` and/or `component` prop—see ["Shared props" on the Base Usage page](/base/getting-started/usage/#shared-props) for more details.
+
+The following demo uses [SwitchUnstyled](/base/react-switch/) to show how to create a styled component by applying styles to three of its subcomponent slots: `Root`, `Thumb`, and `Input`.
+
+Note that although this demo uses [MUI System](/system/styled/) as a styling solution, you are free to choose any alternative.
+
+{{"demo": "StylingSlots.js"}}
+
+The components you pass in the `components` prop receive the `ownerState` prop from the top-level component (the "owner").
+By convention, it contains all props passed to the owner, merged with its rendering state.
+
+For example:
+
+```jsx
+<SwitchUnstyled components={{ Thumb: MyCustomThumb }} data-foo="42" />
+```
+
+In this case, `MyCustomThumb` component receives the `ownerState` object with the following data:
+
+```ts
+{
+  checked: boolean;
+  disabled: boolean;
+  focusVisible: boolean;
+  readOnly: boolean;
+  'data-foo': string;
+}
+```
+
+You can use this object to style your component.
+
+## Creating custom components using hooks
+
+If you need complete control over a component's rendered HTML structure, you can build it with hooks.
+
+Hooks give you access to the _logic_ that a component uses, but without any default structure.
+See ["Components vs. hooks" on the Base Usage page](http://localhost:3000/base/getting-started/usage/#components-vs-hooks) for more details.
+
+Hooks return the current state of the component (e.g. `checked`, `disabled`, `open`, etc.) and provide functions that return props you can apply to your fully custom components.
+
+In the case of [SwitchUnstyled](/base/react-switch), the component is accompanied by the `useSwitch` hook which gives you all of the functionality without any structure.
+
+It returns the following object:
+
+```ts
+{
+  checked: Readonly<boolean>;
+  disabled: Readonly<boolean>;
+  readOnly: Readonly<boolean>;
+  focusVisible: Readonly<boolean>;
+  getInputProps: (otherProps?: object) => SwitchInputProps;
+}
+```
+
+The `checked`, `disabled`, `readOnly`, and `focusVisible` fields represent the state of the switch.
+Use them to apply styling to your HTML elements.
+
+The `getInputProps` function can be used to get the props to place on an HTML `<input>` to make the switch accessible.
+
+{{"demo": "StylingHooks.js", "defaultCodeOpen": true}}

docs/data/base/getting-started/usage/Usage.js

@@ -0,0 +1,16 @@
+import * as React from 'react';
+
+export default function Usage() {
+  return (
+    <iframe
+      title="codesandbox"
+      src="https://codesandbox.io/embed/base-usage-7km2h7?hidenavigation=1&fontsize=14&view=preview"
+      style={{
+        width: '100%',
+        height: 350,
+        border: 0,
+      }}
+      sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"
+    />
+  );
+}

docs/data/base/getting-started/usage/usage.md

@@ -0,0 +1,125 @@
+# MUI Base - Usage
+
+<p class="description">Learn the basics of working with MUI Base components.</p>
+
+## Getting started
+
+The following code snippet demonstrates a simple app that uses the MUI Base [`ButtonUnstyled`](/base/react-button) component:
+
+```jsx
+import * as React from 'react';
+import ReactDOM from 'react-dom';
+import ButtonUnstyled from '@mui/base/ButtonUnstyled';
+
+function App() {
+  return (
+    <div>
+      <ButtonUnstyled>Hello World</ButtonUnstyled>
+    </div>
+  );
+}
+```
+
+You can play around with this code in the interactive Code Sandbox demo below.
+Try importing an `InputUnstyled` component and adding it to the `<div>`:
+
+{{"demo": "Usage.js", "hideToolbar": true, "bg": true}}
+
+## Shared props
+
+Base components are self-supporting and fully functional in isolation.
+
+Each component has its own unique API, but all components accept the following shared props:
+
+### components
+
+The `components` prop is an object that lets you override any interior subcomponents ("slots") of the base component itself.
+
+:::info
+Each component contains a `Root` slot, and many complex components (such as [`BadgeUnstyled`](/base/react-badge)) are composed of additional subcomponents that can be customized.
+:::
+
+You can use the `components` prop to replace subcomponents with either custom components or HTML elements.
+
+For example, the [`BadgeUnstyled`](/base/react-badge) component renders a `<span>` by default.
+The code snippet below shows how to override this by assigning a `<div>` to the `Root` element:
+
+```jsx
+<BadgeUnstyled components={{ Root: 'div' }} />
+```
+
+### component
+
+The (singular) `component` prop provides a shortcut to `components.Root`.
+This is useful if you are only overriding the `Root` element of the component.
+
+The code snippet below shows how to override the `Root` element of the [`BadgeUnstyled`](/base/react-badge) component using the `component` prop:
+
+```jsx
+<BadgeUnstyled component="div" />
+```
+
+:::warning
+**Note**: if both `components.Root` and `component` are specified, `component` takes precedence.
+:::
+
+### componentsProps
+
+The `componentsProps` prop is an object that contains the props for all slots within a component.
+You can use it to define additional custom props for a component's interior elements.
+
+For example, the code snippet below shows how to add a custom CSS class to the `input` slot of the `BadgeUnstyled` component:
+
+```jsx
+<BadgeUnstyled componentsProps={{ input: { className: 'my-badge' } }} />
+```
+
+All additional props placed on the primary component are also propagated into the `Root` slot (just as if they were placed in `componentsProps.root`).
+
+These two examples are equivalent:
+
+```jsx
+<BadgeUnstyled id="badge1">
+```
+
+```jsx
+<BadgeUnstyled componentsProps={{ root: { id: 'badge1' } }}>
+```
+
+## Components vs. hooks
+
+MUI Base includes two kinds of building blocks: **components** and **hooks**.
+
+:::info
+💡 Hooks encapsulate _logic_; components provide _structure_.
+:::
+
+Many Base components are implemented with the help of hooks.
+(Visit the [React documentation on hooks](https://reactjs.org/docs/hooks-intro.html) to get up to speed on this concept.)
+
+You can use components or hooks—or a combination thereof—when building custom components.
+Each option has its own trade-offs:
+
+### Components
+
+#### Pros
+
+- Usually require less code to implement
+- Equipped with accessibility features by default
+
+#### Cons
+
+- Less control over the structure of the rendered HTML
+
+### Hooks
+
+#### Pros
+
+- Complete control over rendered HTML structure
+
+#### Cons
+
+- Usually require more code to implement
+- Extra steps necessary to make the resulting component accessible
+
+Details on usage of hooks can be found in their corresponding component docs.

docs/data/base/pages.ts

@@ -7,6 +7,8 @@ const pages = [
     children: [
       { pathname: '/base/getting-started/overview', title: 'Overview' },
       { pathname: '/base/getting-started/installation', title: 'Installation' },
+      { pathname: '/base/getting-started/usage', title: 'Usage' },
+      { pathname: '/base/getting-started/customization', title: 'Customization' },
     ],
   },
   {