[system] Enable configuring the sx prop in the theme

docs/data/material/customization/theme-components/GlobalThemeOverrideSx.js

@@ -1,30 +1,28 @@
 import * as React from 'react';
-import {
-  ThemeProvider,
-  createTheme,
-  experimental_sx as sx,
-} from '@mui/material/styles';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
 import Chip from '@mui/material/Chip';
 import Check from '@mui/icons-material/Check';
 
 const finalTheme = createTheme({
   components: {
     MuiChip: {
       styleOverrides: {
-        root: sx({
-          // https://mui.com/system/getting-started/the-sx-prop/#spacing
-          px: 1,
-          py: 0.25,
-          // https://mui.com/system/borders/#border-radius
-          borderRadius: 1, // 4px as default.
-        }),
+        root: ({ theme }) =>
+          theme.unstable_sx({
+            // https://mui.com/system/getting-started/the-sx-prop/#spacing
+            px: 1,
+            py: 0.25,
+            // https://mui.com/system/borders/#border-radius
+            borderRadius: 1, // 4px as default.
+          }),
         label: {
           padding: 'initial',
         },
-        icon: sx({
-          mr: 0.5,
-          ml: '-2px',
-        }),
+        icon: ({ theme }) =>
+          theme.unstable_sx({
+            mr: 0.5,
+            ml: '-2px',
+          }),
       },
     },
   },

docs/data/material/customization/theme-components/GlobalThemeOverrideSx.tsx

@@ -1,30 +1,28 @@
 import * as React from 'react';
-import {
-  ThemeProvider,
-  createTheme,
-  experimental_sx as sx,
-} from '@mui/material/styles';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
 import Chip from '@mui/material/Chip';
 import Check from '@mui/icons-material/Check';
 
 const finalTheme = createTheme({
   components: {
     MuiChip: {
       styleOverrides: {
-        root: sx({
-          // https://mui.com/system/getting-started/the-sx-prop/#spacing
-          px: 1,
-          py: 0.25,
-          // https://mui.com/system/borders/#border-radius
-          borderRadius: 1, // 4px as default.
-        }),
+        root: ({ theme }) =>
+          theme.unstable_sx({
+            // https://mui.com/system/getting-started/the-sx-prop/#spacing
+            px: 1,
+            py: 0.25,
+            // https://mui.com/system/borders/#border-radius
+            borderRadius: 1, // 4px as default.
+          }),
         label: {
           padding: 'initial',
         },
-        icon: sx({
-          mr: 0.5,
-          ml: '-2px',
-        }),
+        icon: ({ theme }) =>
+          theme.unstable_sx({
+            mr: 0.5,
+            ml: '-2px',
+          }),
       },
     },
   },

docs/data/system/experimental-api/extend-sx-prop/ChangeTheBehaviorSxProp.js

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import { createTheme, ThemeProvider, Box, Stack } from '@mui/system';
+
+// Retain type safety.
+
+const theme = createTheme({
+  unstable_sxConfig: {
+    // You can now use the background key in sx
+    // by providing direct values from the palette
+    borderRadius: {
+      themeKey: 'shape',
+    },
+  },
+  shape: {
+    sm: 4,
+    md: 8,
+    lg: 12,
+  },
+});
+
+export default function ExtendSxProp() {
+  return (
+    <ThemeProvider theme={theme}>
+      <Stack direction="row" gap={1}>
+        <Box sx={{ borderRadius: 'sm', bgcolor: '#007FFF', color: '#FFF', p: 1 }}>
+          sm border radius
+        </Box>
+        <Box sx={{ borderRadius: 'md', bgcolor: '#007FFF', color: '#FFF', p: 1 }}>
+          md border radius
+        </Box>
+        <Box sx={{ borderRadius: 'lg', bgcolor: '#007FFF', color: '#FFF', p: 1 }}>
+          lg border radius
+        </Box>
+      </Stack>
+    </ThemeProvider>
+  );
+}

docs/data/system/experimental-api/extend-sx-prop/ChangeTheBehaviorSxProp.tsx

@@ -0,0 +1,44 @@
+import * as React from 'react';
+import { createTheme, ThemeProvider, Box, Stack } from '@mui/system';
+
+// Retain type safety.
+declare module '@mui/system' {
+  interface Shape {
+    sm: number;
+    md: number;
+    lg: number;
+  }
+}
+
+const theme = createTheme({
+  unstable_sxConfig: {
+    // You can now use the background key in sx
+    // by providing direct values from the palette
+    borderRadius: {
+      themeKey: 'shape',
+    },
+  },
+  shape: {
+    sm: 4,
+    md: 8,
+    lg: 12,
+  },
+});
+
+export default function ExtendSxProp() {
+  return (
+    <ThemeProvider theme={theme}>
+      <Stack direction="row" gap={1}>
+        <Box sx={{ borderRadius: 'sm', bgcolor: '#007FFF', color: '#FFF', p: 1 }}>
+          sm border radius
+        </Box>
+        <Box sx={{ borderRadius: 'md', bgcolor: '#007FFF', color: '#FFF', p: 1 }}>
+          md border radius
+        </Box>
+        <Box sx={{ borderRadius: 'lg', bgcolor: '#007FFF', color: '#FFF', p: 1 }}>
+          lg border radius
+        </Box>
+      </Stack>
+    </ThemeProvider>
+  );
+}

docs/data/system/experimental-api/extend-sx-prop/ChangeTheBehaviorSxProp.tsx.preview

@@ -0,0 +1,13 @@
+<ThemeProvider theme={theme}>
+  <Stack direction="row" gap={1}>
+    <Box sx={{ borderRadius: 'sm', bgcolor: '#007FFF', color: '#FFF', p: 1 }}>
+      sm border radius
+    </Box>
+    <Box sx={{ borderRadius: 'md', bgcolor: '#007FFF', color: '#FFF', p: 1 }}>
+      md border radius
+    </Box>
+    <Box sx={{ borderRadius: 'lg', bgcolor: '#007FFF', color: '#FFF', p: 1 }}>
+      lg border radius
+    </Box>
+  </Stack>
+</ThemeProvider>

docs/data/system/experimental-api/extend-sx-prop/ExtendTheSxProp.js

@@ -0,0 +1,35 @@
+import * as React from 'react';
+import { createTheme, ThemeProvider, Box } from '@mui/system';
+
+const theme = createTheme({
+  unstable_sxConfig: {
+    // You can now use the background key in sx
+    // by providing direct values from the palette
+    background: {
+      themeKey: 'palette',
+    },
+  },
+  palette: {
+    primary: {
+      main: '#007FFF',
+      contrastText: '#FFFFFF',
+    },
+  },
+});
+
+export default function ExtendSxProp() {
+  return (
+    <ThemeProvider theme={theme}>
+      <Box
+        sx={{
+          background: 'primary.main',
+          color: 'primary.contrastText',
+          p: 1,
+          borderRadius: 2,
+        }}
+      >
+        Primary main background
+      </Box>
+    </ThemeProvider>
+  );
+}

docs/data/system/experimental-api/extend-sx-prop/ExtendTheSxProp.tsx

@@ -0,0 +1,35 @@
+import * as React from 'react';
+import { createTheme, ThemeProvider, Box } from '@mui/system';
+
+const theme = createTheme({
+  unstable_sxConfig: {
+    // You can now use the background key in sx
+    // by providing direct values from the palette
+    background: {
+      themeKey: 'palette',
+    },
+  },
+  palette: {
+    primary: {
+      main: '#007FFF',
+      contrastText: '#FFFFFF',
+    },
+  },
+});
+
+export default function ExtendSxProp() {
+  return (
+    <ThemeProvider theme={theme}>
+      <Box
+        sx={{
+          background: 'primary.main',
+          color: 'primary.contrastText',
+          p: 1,
+          borderRadius: 2,
+        }}
+      >
+        Primary main background
+      </Box>
+    </ThemeProvider>
+  );
+}

docs/data/system/experimental-api/extend-sx-prop/ExtendTheSxProp.tsx.preview

@@ -0,0 +1,12 @@
+<ThemeProvider theme={theme}>
+  <Box
+    sx={{
+      background: 'primary.main',
+      color: 'primary.contrastText',
+      p: 1,
+      borderRadius: 2,
+    }}
+  >
+    Primary main background
+  </Box>
+</ThemeProvider>

docs/data/system/experimental-api/extend-sx-prop/extend-sx-prop.md

@@ -0,0 +1,24 @@
+# Extend the `sx` prop
+
+<p class="description">Learn about the experimental API for extending or changing the behavior of the `sx` prop.</p>
+
+## Extend the `sx` prop
+
+If you wish to add new keys that would be processed by the `sx` prop, you can do that by extending the `unstable_sxConfig` option inside the theme.
+
+{{"demo": "ExtendTheSxProp.js" }}
+
+## Override some of the existing behavior
+
+There is also a possibility to change some of the existing behavior. You can simply provide a custom config in the for the specific key.
+
+{{"demo": "ChangeTheBehaviorSxProp.js" }}
+
+## API
+
+Each key in the `unstable_sx` config can define the following properties:
+
+- `cssProperty` (_string_ [optional]): Indicates the css property, if it is different than the key
+- `themeKey` (_string_ [optional]): The path of the theme mapping.
+- `transform` (_(cssValue: unknown, userValue: unknown) => number | string | React.CSSProperties | CSSObject_ [optional]): Allows users to define a function that can transform the value before it is returned
+- `style` (_(props: any) => CSSObject_ [optional]): Offers maximum customizability. Note that you need to make sure that the breakpoints values can be processed

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

@@ -157,9 +157,9 @@ It works with both Emotion and styled-components.
   | Benchmark case                    | Code snippet          | Time normalized |
   | :-------------------------------- | :-------------------- | --------------- |
   | a. Render 1,000 primitives        | `<div className="…">` | 100ms           |
-  | b. Render 1,000 components        | `<Div>`               | 120ms           |
-  | c. Render 1,000 styled components | `<StyledDiv>`         | 160ms           |
-  | d. Render 1,000 Box               | `<Box sx={…}>`        | 370ms           |
+  | b. Render 1,000 components        | `<Div>`               | 112ms           |
+  | c. Render 1,000 styled components | `<StyledDiv>`         | 181ms           |
+  | d. Render 1,000 Box               | `<Box sx={…}>`        | 296ms           |
 
 <!-- #default-branch-switch -->
 

docs/data/system/pages.ts

@@ -63,6 +63,17 @@ const pages = [
     icon: 'CodeIcon',
     children: pagesApi,
   },
+  {
+    pathname: '/system/experimental-api',
+    title: 'Experimental APIs',
+    icon: 'ExperimentIcon',
+    children: [
+      {
+        pathname: '/system/experimental-api/extend-sx-prop',
+        title: 'Extend the `sx` prop',
+      },
+    ],
+  },
   {
     pathname: '/system/styles',
     title: 'Styles',

docs/data/system/styled/UsingWithSx.js

@@ -1,10 +1,5 @@
 import * as React from 'react';
-import {
-  styled,
-  createTheme,
-  ThemeProvider,
-  experimental_sx as sx,
-} from '@mui/system';
+import { styled, createTheme, ThemeProvider } from '@mui/system';
 
 const customTheme = createTheme({
   palette: {
@@ -15,8 +10,8 @@ const customTheme = createTheme({
   },
 });
 
-const MyThemeComponent = styled('div')(
-  sx({
+const MyThemeComponent = styled('div')(({ theme }) =>
+  theme.unstable_sx({
     color: 'primary.contrastText',
     backgroundColor: 'primary.main',
     padding: 1,

docs/data/system/styled/UsingWithSx.tsx

@@ -1,10 +1,5 @@
 import * as React from 'react';
-import {
-  styled,
-  createTheme,
-  ThemeProvider,
-  experimental_sx as sx,
-} from '@mui/system';
+import { styled, createTheme, ThemeProvider } from '@mui/system';
 
 const customTheme = createTheme({
   palette: {
@@ -15,8 +10,8 @@ const customTheme = createTheme({
   },
 });
 
-const MyThemeComponent = styled('div')(
-  sx({
+const MyThemeComponent = styled('div')(({ theme }) =>
+  theme.unstable_sx({
     color: 'primary.contrastText',
     backgroundColor: 'primary.main',
     padding: 1,

docs/data/system/styled/styled.md

@@ -208,13 +208,13 @@ const MyStyledButton = (props) => (
 
 ### How can I use the `sx` syntax with the `styled()` utility?
 
-If you are one of those who prefers the `sx` syntax and wants to use it in both the `sx` prop and the `styled()` utility, you can use the `experimental_sx` utility from the `@mui/system`:
+If you are one of those who prefers the `sx` syntax and wants to use it in both the `sx` prop and the `styled()` utility, you can use the `unstable_sx` utility from the `theme`:
 
 {{"demo": "UsingWithSx.js", "defaultCodeOpen": true}}
 
-The overhead added by using the `experimental_sx` utility is the same as if you were to use the `sx` prop on the component.
+The overhead added by using the `unstable_sx` utility is the same as if you were to use the `sx` prop on the component.
 
-> Note: You can use `experimental_sx` outside of the `styled()` utility, too; e.g., for defining `variants` in your custom theme.
+> Note: You can use `unstable_sx` outside of the `styled()` utility, too; e.g., for defining `variants` in your custom theme.
 
 ## How to use components selector API