[system] Add applyStyles() to theme

docs/src/modules/brandingTheme.ts

@@ -403,21 +403,7 @@ export const getDesignTokens = (mode: 'light' | 'dark') =>
      *  ]
      */
     applyDarkStyles(css: Parameters<ApplyDarkStyles>[0]) {
-      if ((this as Theme).vars) {
-        // If CssVarsProvider is used as a provider,
-        // returns ':where([data-mui-color-scheme="light|dark"]) &'
-        const selector = (this as Theme)
-          .getColorSchemeSelector('dark')
-          .replace(/(\[[^\]]+\])/, ':where($1)');
-        return {
-          [selector]: css,
-        };
-      }
-      if ((this as Theme).palette.mode === 'dark') {
-        return css;
-      }
-
-      return undefined;
+      return (this as Theme).applyStyles('dark', css);
     },
   } as ThemeOptions);
 

packages/mui-joy/src/styles/defaultTheme.test.js

@@ -31,7 +31,7 @@ describe('defaultTheme', () => {
         'unstable_sx',
         'shouldSkipGeneratingVar',
         'generateCssVars',
-        'applyDarkStyles',
+        'applyStyles',
       ]).to.includes(field);
     });
   });

packages/mui-joy/src/styles/extendTheme.test.js

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { expect } from 'chai';
 import { createRenderer } from '@mui-internal/test-utils';
-import { extendTheme, useTheme, CssVarsProvider } from '@mui/joy/styles';
+import { extendTheme, useTheme, CssVarsProvider, styled } from '@mui/joy/styles';
 
 describe('extendTheme', () => {
   it('the output contains required fields', () => {
@@ -31,7 +31,7 @@ describe('extendTheme', () => {
         'unstable_sx',
         'shouldSkipGeneratingVar',
         'generateCssVars',
-        'applyDarkStyles',
+        'applyStyles',
       ]).to.includes(field);
     });
   });
@@ -177,5 +177,28 @@ describe('extendTheme', () => {
         borderRadius: 'var(--joy-radius-md)',
       });
     });
+
+    it('applyStyles', () => {
+      const attribute = 'data-custom-color-scheme';
+      let darkStyles = {};
+      const Test = styled('div')(({ theme }) => {
+        darkStyles = theme.applyStyles('dark', {
+          backgroundColor: 'rgba(0, 0, 0, 0)',
+        });
+        return null;
+      });
+
+      render(
+        <CssVarsProvider attribute={attribute}>
+          <Test />
+        </CssVarsProvider>,
+      );
+
+      expect(darkStyles).to.deep.equal({
+        [`*:where([${attribute}="dark"]) &`]: {
+          backgroundColor: 'rgba(0, 0, 0, 0)',
+        },
+      });
+    });
   });
 });

packages/mui-joy/src/styles/extendTheme.ts

@@ -9,8 +9,8 @@ import {
   unstable_createGetCssVar as systemCreateGetCssVar,
   unstable_styleFunctionSx as styleFunctionSx,
   SxConfig,
-  CSSObject,
 } from '@mui/system';
+import { unstable_applyStyles as applyStyles } from '@mui/system/createTheme';
 import defaultSxConfig from './sxConfig';
 import colors from '../colors';
 import defaultShouldSkipGeneratingVar from './shouldSkipGeneratingVar';
@@ -565,23 +565,6 @@ export default function extendTheme(themeOptions?: CssVarsThemeOptions): Theme {
     cssVarPrefix,
     getCssVar,
     spacing: createSpacing(spacing),
-    applyDarkStyles(css: CSSObject) {
-      if ((this as Theme).vars) {
-        // If CssVarsProvider is used as a provider,
-        // returns ':where([data-mui-color-scheme="light|dark"]) &'
-        const selector = (this as Theme)
-          .getColorSchemeSelector('dark')
-          .replace(/(\[[^\]]+\])/, ':where($1)');
-        return {
-          [selector]: css,
-        };
-      }
-      if ((this as Theme).palette.mode === 'dark') {
-        return css;
-      }
-
-      return {};
-    },
   } as unknown as Theme; // Need type casting due to module augmentation inside the repo
 
   /**
@@ -680,6 +663,7 @@ export default function extendTheme(themeOptions?: CssVarsThemeOptions): Theme {
   };
 
   theme.shouldSkipGeneratingVar = shouldSkipGeneratingVar;
+  theme.applyStyles = applyStyles;
 
   return theme;
 }

packages/mui-joy/src/styles/types/theme.ts

@@ -6,6 +6,7 @@ import {
   SystemProps as SystemSystemProps,
   CSSObject,
   SxConfig,
+  ApplyStyles,
 } from '@mui/system';
 import { DefaultColorScheme, ExtendedColorScheme } from './colorScheme';
 import { ColorSystem } from './colorSystem';
@@ -118,7 +119,7 @@ export interface Theme extends ThemeScales, RuntimeColorSystem {
   shouldSkipGeneratingVar: (keys: string[], value: string | number) => boolean;
   unstable_sxConfig: SxConfig;
   unstable_sx: (props: SxProps) => CSSObject;
-  applyDarkStyles: (css: CSSObject) => CSSObject;
+  applyStyles: ApplyStyles<DefaultColorScheme | ExtendedColorScheme>;
 }
 
 export type SxProps = SystemSxProps<Theme>;

packages/mui-material/src/Avatar/Avatar.js

@@ -69,7 +69,7 @@ const AvatarRoot = styled('div', {
             }
           : {
               backgroundColor: theme.palette.grey[400],
-              ...theme.applyDarkStyles({ backgroundColor: theme.palette.grey[600] }),
+              ...theme.applyStyles('dark', { backgroundColor: theme.palette.grey[600] }),
             }),
       },
     },

packages/mui-material/src/styles/createTheme.d.ts

@@ -45,7 +45,6 @@ export interface Theme extends BaseTheme {
   components?: Components<BaseTheme>;
   unstable_sx: (props: SxProps<Theme>) => CSSObject;
   unstable_sxConfig: SxConfig;
-  applyDarkStyles: (css: CSSObject) => CSSObject;
 }
 
 /**

packages/mui-material/src/styles/createTheme.js

@@ -43,21 +43,6 @@ function createTheme(options = {}, ...args) {
     typography: createTypography(palette, typographyInput),
     transitions: createTransitions(transitionsInput),
     zIndex: { ...zIndex },
-    applyDarkStyles(css) {
-      if (this.vars) {
-        // If CssVarsProvider is used as a provider,
-        // returns ':where([data-mui-color-scheme="light|dark"]) &'
-        const selector = this.getColorSchemeSelector('dark').replace(/(\[[^\]]+\])/, ':where($1)');
-        return {
-          [selector]: css,
-        };
-      }
-      if (this.palette.mode === 'dark') {
-        return css;
-      }
-
-      return {};
-    },
   });
 
   muiTheme = deepmerge(muiTheme, other);

packages/mui-material/src/styles/createTheme.test.js

@@ -251,7 +251,7 @@ describe('createTheme', () => {
     });
   });
 
-  it('should apply dark styles when using applyDarkStyles if mode="dark"', function test() {
+  it('should apply dark styles when using applyStyles if mode="dark"', function test() {
     const darkTheme = createTheme({
       palette: {
         mode: 'dark',
@@ -260,7 +260,7 @@ describe('createTheme', () => {
 
     const Test = styled('div')(({ theme }) => ({
       backgroundColor: 'rgb(255, 255, 255)',
-      ...theme.applyDarkStyles({
+      ...theme.applyStyles('dark', {
         backgroundColor: 'rgb(0, 0, 0)',
       }),
     }));
@@ -276,12 +276,12 @@ describe('createTheme', () => {
     });
   });
 
-  it('should apply dark styles when using applyDarkStyles if mode="light"', function test() {
+  it('should not apply dark styles when using applyStyles if mode="light"', function test() {
     const lightTheme = createTheme();
 
     const Test = styled('div')(({ theme }) => ({
       backgroundColor: 'rgb(255, 255, 255)',
-      ...theme.applyDarkStyles({
+      ...theme.applyStyles('dark', {
         backgroundColor: 'rgb(0, 0, 0)',
       }),
     }));

packages/mui-material/src/styles/experimental_extendTheme.d.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/naming-convention */
 import { OverridableStringUnion } from '@mui/types';
-import { SxConfig, SxProps, CSSObject } from '@mui/system';
+import { SxConfig, SxProps, CSSObject, ApplyStyles } from '@mui/system';
 import { ThemeOptions, Theme } from './createTheme';
 import { Palette, PaletteOptions } from './createPalette';
 import { Shadows } from './shadows';
@@ -432,6 +432,7 @@ export interface CssVarsTheme extends ColorSystem {
   shouldSkipGeneratingVar: (keys: string[], value: string | number) => boolean;
   unstable_sxConfig: SxConfig;
   unstable_sx: (props: SxProps<CssVarsTheme>) => CSSObject;
+  applyStyles: ApplyStyles<SupportedColorScheme>;
 }
 
 /**
@@ -443,4 +444,4 @@ export interface CssVarsTheme extends ColorSystem {
 export default function experimental_extendTheme(
   options?: CssVarsThemeOptions,
   ...args: object[]
-): Omit<Theme, 'palette'> & CssVarsTheme;
+): Omit<Theme, 'palette' | 'applyStyles'> & CssVarsTheme;

packages/mui-material/src/styles/experimental_extendTheme.test.js

@@ -505,25 +505,24 @@ describe('experimental_extendTheme', () => {
     });
   });
 
-  it('should use the right selector with applyDarkStyles', function test() {
-    const defaultTheme = extendTheme();
+  it('should use the right selector with applyStyles', function test() {
     const attribute = 'data-custom-color-scheme';
     let darkStyles = {};
     const Test = styled('div')(({ theme }) => {
-      darkStyles = theme.applyDarkStyles({
+      darkStyles = theme.applyStyles('dark', {
         backgroundColor: 'rgba(0, 0, 0, 0)',
       });
       return null;
     });
 
     render(
-      <CssVarsProvider attribute={attribute} theme={defaultTheme}>
+      <CssVarsProvider attribute={attribute}>
         <Test />
       </CssVarsProvider>,
     );
 
     expect(darkStyles).to.deep.equal({
-      [`:where([${attribute}="dark"]) &`]: {
+      [`*:where([${attribute}="dark"]) &`]: {
         backgroundColor: 'rgba(0, 0, 0, 0)',
       },
     });

packages/mui-system/src/createTheme/applyStyles.ts

@@ -0,0 +1,85 @@
+import { CSSObject } from '@mui/styled-engine';
+
+export interface ApplyStyles<K extends string> {
+  (key: K, styles: CSSObject): CSSObject;
+}
+
+/**
+ * A universal utility to style components with multiple color modes. Always use it from the theme object.
+ * It works with:
+ *  - [Basic theme](https://mui.com/material-ui/customization/dark-mode/)
+ *  - [CSS theme variables](https://mui.com/material-ui/experimental-api/css-theme-variables/overview/)
+ *  - Zero-runtime engine
+ *
+ * Tips: Use an array over object spread and place `theme.applyStyles()` last.
+ *
+ * ✅ [{ background: '#e5e5e5' }, theme.applyStyles('dark', { background: '#1c1c1c' })]
+ *
+ * 🚫 { background: '#e5e5e5', ...theme.applyStyles('dark', { background: '#1c1c1c' })}
+ *
+ * @example
+ * 1. using with `styled`:
+ * ```jsx
+ *   const Component = styled('div')(({ theme }) => [
+ *     { background: '#e5e5e5' },
+ *     theme.applyStyles('dark', {
+ *       background: '#1c1c1c',
+ *       color: '#fff',
+ *     }),
+ *   ]);
+ * ```
+ *
+ * @example
+ * 2. using with `sx` prop:
+ * ```jsx
+ *   <Box sx={theme => [
+ *     { background: '#e5e5e5' },
+ *     theme.applyStyles('dark', {
+ *        background: '#1c1c1c',
+ *        color: '#fff',
+ *      }),
+ *     ]}
+ *   />
+ * ```
+ *
+ * @example
+ * 3. theming a component:
+ * ```jsx
+ *   extendTheme({
+ *     components: {
+ *       MuiButton: {
+ *         styleOverrides: {
+ *           root: ({ theme }) => [
+ *             { background: '#e5e5e5' },
+ *             theme.applyStyles('dark', {
+ *               background: '#1c1c1c',
+ *               color: '#fff',
+ *             }),
+ *           ],
+ *         },
+ *       }
+ *     }
+ *   })
+ *```
+ */
+export default function applyStyles<K extends string>(key: K, styles: CSSObject) {
+  // @ts-expect-error this is 'any' type
+  const theme = this as {
+    palette: { mode: 'light' | 'dark' };
+    vars?: any;
+    getColorSchemeSelector?: (scheme: string) => string;
+  };
+  if (theme.vars && typeof theme.getColorSchemeSelector === 'function') {
+    // If CssVarsProvider is used as a provider,
+    // returns '* :where([data-mui-color-scheme="light|dark"]) &'
+    const selector = theme.getColorSchemeSelector(key).replace(/(\[[^\]]+\])/, '*:where($1)');
+    return {
+      [selector]: styles,
+    };
+  }
+  if (theme.palette.mode === key) {
+    return styles;
+  }
+
+  return {};
+}

packages/mui-system/src/createTheme/createTheme.d.ts

@@ -3,6 +3,7 @@ import { Breakpoints, BreakpointsOptions } from './createBreakpoints';
 import { Shape, ShapeOptions } from './shape';
 import { Spacing, SpacingOptions } from './createSpacing';
 import { SxConfig, SxProps } from '../styleFunctionSx';
+import { ApplyStyles } from './applyStyles';
 
 export { Breakpoint, BreakpointOverrides } from './createBreakpoints';
 
@@ -35,6 +36,7 @@ export interface Theme {
   mixins?: unknown;
   typography?: unknown;
   zIndex?: unknown;
+  applyStyles: ApplyStyles<'light' | 'dark'>;
   unstable_sxConfig: SxConfig;
   unstable_sx: (props: SxProps<Theme>) => CSSObject;
 }

packages/mui-system/src/createTheme/createTheme.js

@@ -4,6 +4,7 @@ import shape from './shape';
 import createSpacing from './createSpacing';
 import styleFunctionSx from '../styleFunctionSx/styleFunctionSx';
 import defaultSxConfig from '../styleFunctionSx/defaultSxConfig';
+import applyStyles from './applyStyles';
 
 function createTheme(options = {}, ...args) {
   const {
@@ -29,6 +30,8 @@ function createTheme(options = {}, ...args) {
     other,
   );
 
+  muiTheme.applyStyles = applyStyles;
+
   muiTheme = args.reduce((acc, argument) => deepmerge(acc, argument), muiTheme);
 
   muiTheme.unstable_sxConfig = {