[material-ui] Reexport styles from stylesOptimized to improve TS performance

docs/data/material/guides/typescript/typescript.md

@@ -66,3 +66,48 @@ const CustomButton = styled(Button)({
   // your custom styles go here
 }) as typeof Button;
 ```
+
+## Performance optimizations
+
+When building a custom theme, Material UI provides automatic autocompletion and type checking for all tokens and components.
+However, this comes at the cost of some performance overhead because TypeScript has to instantiate types for all components and their variants. This can lead to slower compilation times, especially in large codebase with intensive theme customization.
+
+Starting from v7.4.0, Material UI offers an optimized path that significantly reduces the type instantiation overhead.
+This path mirrors the exports from `@mui/material/styles` without the automatic inclusion of all component types.
+
+Follow the steps below to enable the optimized path in your project:
+
+1. Update all of the imports in your codebase from.
+
+```diff
+-'@mui/material/styles';
++'@mui/material/stylesOptimized';
+```
+
+:::warning
+The optimization will not take effect if there is a single import from the `@mui/material/styles`.
+:::
+
+2. Use module augmentation to explicitly include the component types to the theme.
+
+```ts
+import { createTheme } from '@mui/material/stylesOptimized';
+
+import { ButtonTheme } from '@mui/material/Button';
+import { TextFieldTheme } from '@mui/material/TextField';
+
+declare module '@mui/material/stylesOptimized' {
+  interface ThemeComponents extends ButtonTheme, TextFieldTheme {}
+}
+
+const theme = createTheme({
+  components: {
+    MuiButton: {
+      // type-safe and autocompletion enabled
+    },
+    MuiTextField: {
+      // type-safe and autocompletion enabled
+    },
+  },
+});
+```

package.json

@@ -86,7 +86,7 @@
     "nx_test_regressions_run": "mocha --config test/regressions/.mocharc.js --delay 'test/regressions/**/*.test.js'",
     "nx_test_regressions_pigment_css_run": "mocha --config apps/pigment-css-vite-app/.mocharc.cjs --delay 'apps/pigment-css-vite-app/**/*.test.js'",
     "clean": "pnpm -r exec rm -rf build",
-    "nx_test_unit": "cross-env NODE_ENV=test mocha \"packages/**/*.test.?(c|m)[jt]s?(x)\" \"packages-internal/**/*.test.?(c|m)[jt]s?(x)\" \"docs/**/*.test.?(c|m)[jt]s?(x)\""
+    "nx_test_unit": "cross-env NODE_ENV=test mocha \"packages/**/*.test.?(c|m)[jt]s?(x)\" \"packages-internal/**/*.test.?(c|m)[jt]s?(x)\" \"docs/**/*.test.?(c|m)[jt]s?(x)\" \"test/ts-performance/**/*.test.?(c|m)[jt]s?(x)\""
   },
   "dependencies": {
     "@netlify/functions": "^4.3.0",

packages/mui-lab/src/Masonry/Masonry.d.ts

@@ -1,7 +1,7 @@
 import { ResponsiveStyleValue, SxProps } from '@mui/system';
 import { OverridableComponent, OverrideProps } from '@mui/material/OverridableComponent';
-import { Theme } from '@mui/material/styles';
-import { MasonryClasses } from './masonryClasses';
+import { Theme, CreateThemeComponent } from '@mui/material/stylesOptimized';
+import { MasonryClasses, MasonryClassKey } from './masonryClasses';
 
 export interface MasonryOwnProps {
   /**
@@ -69,4 +69,6 @@ export type MasonryProps<
   AdditionalProps = {},
 > = OverrideProps<MasonryTypeMap<AdditionalProps, RootComponent>, RootComponent>;
 
+export type MasonryTheme = CreateThemeComponent<MasonryClassKey, MasonryProps>;
+
 export default Masonry;

packages/mui-lab/src/TabPanel/TabPanel.d.ts

@@ -1,8 +1,8 @@
 import * as React from 'react';
 import { InternalStandardProps as StandardProps } from '@mui/material/internal';
-import { Theme } from '@mui/material/styles';
+import { CreateThemeComponent, Theme } from '@mui/material/stylesOptimized';
 import { SxProps } from '@mui/system';
-import { TabPanelClasses } from './tabPanelClasses';
+import { TabPanelClasses, TabPanelClassKey } from './tabPanelClasses';
 
 export interface TabPanelProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>> {
   /**
@@ -29,6 +29,8 @@ export interface TabPanelProps extends StandardProps<React.HTMLAttributes<HTMLDi
   keepMounted?: boolean;
 }
 
+export type TabPanelTheme = CreateThemeComponent<TabPanelClassKey, TabPanelProps>;
+
 /**
  *
  * Demos:

packages/mui-material/src/Accordion/Accordion.d.ts

@@ -1,8 +1,8 @@
 import * as React from 'react';
 import { SxProps } from '@mui/system';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import { TransitionProps } from '../transitions/transition';
-import { AccordionClasses } from './accordionClasses';
+import { AccordionClasses, AccordionClassKey } from './accordionClasses';
 import { OverridableComponent, OverrideProps } from '../OverridableComponent';
 import { ExtendPaperTypeMap, PaperProps } from '../Paper/Paper';
 import { CreateSlotsAndSlotProps, SlotComponentProps, SlotProps } from '../utils/types';
@@ -157,4 +157,8 @@ export type AccordionProps<
 
 export interface AccordionOwnerState extends AccordionProps {}
 
+export type AccordionTheme = {
+  MuiAccordion?: CreateThemeComponent<AccordionClassKey, AccordionProps>;
+};
+
 export default Accordion;

packages/mui-material/src/AccordionActions/AccordionActions.d.ts

@@ -1,8 +1,8 @@
 import * as React from 'react';
 import { SxProps } from '@mui/system';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import { InternalStandardProps as StandardProps } from '../internal';
-import { AccordionActionsClasses } from './accordionActionsClasses';
+import { AccordionActionsClasses, AccordionActionsClassKey } from './accordionActionsClasses';
 
 export interface AccordionActionsProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>> {
   /**
@@ -35,3 +35,7 @@ export interface AccordionActionsProps extends StandardProps<React.HTMLAttribute
  * - [AccordionActions API](https://mui.com/material-ui/api/accordion-actions/)
  */
 export default function AccordionActions(props: AccordionActionsProps): React.JSX.Element;
+
+export type AccordionActionsTheme = {
+  MuiAccordionActions?: CreateThemeComponent<AccordionActionsClassKey, AccordionActionsProps>;
+};

packages/mui-material/src/AccordionDetails/AccordionDetails.d.ts

@@ -1,8 +1,8 @@
 import * as React from 'react';
 import { SxProps } from '@mui/system';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import { InternalStandardProps as StandardProps } from '../internal';
-import { AccordionDetailsClasses } from './accordionDetailsClasses';
+import { AccordionDetailsClasses, AccordionDetailsClassKey } from './accordionDetailsClasses';
 
 export interface AccordionDetailsProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>> {
   /**
@@ -30,3 +30,7 @@ export interface AccordionDetailsProps extends StandardProps<React.HTMLAttribute
  * - [AccordionDetails API](https://mui.com/material-ui/api/accordion-details/)
  */
 export default function AccordionDetails(props: AccordionDetailsProps): React.JSX.Element;
+
+export type AccordionDetailsTheme = {
+  MuiAccordionDetails?: CreateThemeComponent<AccordionDetailsClassKey, AccordionDetailsProps>;
+};

packages/mui-material/src/AccordionSummary/AccordionSummary.d.ts

@@ -3,8 +3,8 @@ import { SxProps } from '@mui/system';
 import { ButtonBaseProps, ExtendButtonBase, ExtendButtonBaseTypeMap } from '../ButtonBase';
 import { OverrideProps } from '../OverridableComponent';
 import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';
-import { Theme } from '../styles';
-import { AccordionSummaryClasses } from './accordionSummaryClasses';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
+import { AccordionSummaryClasses, AccordionSummaryClassKey } from './accordionSummaryClasses';
 
 export interface AccordionSummarySlots {
   /**
@@ -108,4 +108,8 @@ export type AccordionSummaryProps<
   component?: React.ElementType;
 };
 
+export type AccordionSummaryTheme = {
+  MuiAccordionSummary?: CreateThemeComponent<AccordionSummaryClassKey, AccordionSummaryProps>;
+};
+
 export default AccordionSummary;

packages/mui-material/src/Alert/Alert.d.ts

@@ -2,11 +2,11 @@ import * as React from 'react';
 import { OverridableStringUnion } from '@mui/types';
 import { SxProps } from '@mui/system';
 import { SvgIconProps } from '../SvgIcon';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import { InternalStandardProps as StandardProps } from '../internal';
 import { IconButtonProps } from '../IconButton';
 import { PaperProps } from '../Paper';
-import { AlertClasses } from './alertClasses';
+import { AlertClasses, AlertClassKey } from './alertClasses';
 import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';
 
 export type AlertColor = 'success' | 'info' | 'warning' | 'error';
@@ -203,3 +203,7 @@ export interface AlertOwnerState extends AlertProps {}
  * - inherits [Paper API](https://mui.com/material-ui/api/paper/)
  */
 export default function Alert(props: AlertProps): React.JSX.Element;
+
+export type AlertTheme = {
+  MuiAlert?: CreateThemeComponent<AlertClassKey, AlertProps>;
+};

packages/mui-material/src/AlertTitle/AlertTitle.d.ts

@@ -1,8 +1,8 @@
 import * as React from 'react';
 import { SxProps } from '@mui/system';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import { TypographyProps } from '../Typography';
-import { AlertTitleClasses } from './alertTitleClasses';
+import { AlertTitleClasses, AlertTitleClassKey } from './alertTitleClasses';
 
 export interface AlertTitleProps extends TypographyProps<'div'> {
   /**
@@ -31,3 +31,7 @@ export interface AlertTitleProps extends TypographyProps<'div'> {
  * - inherits [Typography API](https://mui.com/material-ui/api/typography/)
  */
 export default function AlertTitle(props: AlertTitleProps): React.JSX.Element;
+
+export type AlertTitleTheme = {
+  MuiAlertTitle?: CreateThemeComponent<AlertTitleClassKey, AlertTitleProps>;
+};

packages/mui-material/src/AppBar/AppBar.d.ts

@@ -2,8 +2,8 @@ import * as React from 'react';
 import { SxProps } from '@mui/system';
 import { OverridableStringUnion } from '@mui/types';
 import { OverridableComponent, OverrideProps } from '../OverridableComponent';
-import { PropTypes, Theme } from '../styles';
-import { AppBarClasses } from './appBarClasses';
+import { CreateThemeComponent, PropTypes, Theme } from '../stylesOptimized';
+import { AppBarClasses, AppBarClassKey } from './appBarClasses';
 import { ExtendPaperTypeMap } from '../Paper/Paper';
 
 export interface AppBarPropsColorOverrides {}
@@ -73,4 +73,8 @@ export type AppBarProps<
   component?: React.ElementType;
 };
 
+export type AppBarTheme = {
+  MuiAppBar?: CreateThemeComponent<AppBarClassKey, AppBarProps>;
+};
+
 export default AppBar;

packages/mui-material/src/Autocomplete/Autocomplete.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { SxProps } from '@mui/system';
 import { OverridableStringUnion } from '@mui/types';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import { InternalStandardProps as StandardProps } from '../internal';
 import { IconButtonProps } from '../IconButton';
 import { ChipProps, ChipTypeMap } from '../Chip';
@@ -17,7 +17,7 @@ import useAutocomplete, {
   UseAutocompleteProps,
   AutocompleteFreeSoloValueMapping,
 } from '../useAutocomplete';
-import { AutocompleteClasses } from './autocompleteClasses';
+import { AutocompleteClasses, AutocompleteClassKey } from './autocompleteClasses';
 import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';
 
 export interface AutocompletePaperSlotPropsOverrides {}
@@ -421,3 +421,10 @@ export default function Autocomplete<
 >(
   props: AutocompleteProps<Value, Multiple, DisableClearable, FreeSolo, ChipComponent>,
 ): React.JSX.Element;
+
+export type AutocompleteTheme = {
+  MuiAutocomplete?: CreateThemeComponent<
+    AutocompleteClassKey,
+    AutocompleteProps<any, any, any, any>
+  >;
+};

packages/mui-material/src/Avatar/Avatar.d.ts

@@ -1,9 +1,9 @@
 import * as React from 'react';
 import { SxProps } from '@mui/system';
 import { OverridableStringUnion } from '@mui/types';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import { OverridableComponent, OverrideProps } from '../OverridableComponent';
-import { AvatarClasses } from './avatarClasses';
+import { AvatarClasses, AvatarClassKey } from './avatarClasses';
 import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';
 import { SvgIconProps } from '../SvgIcon';
 
@@ -130,4 +130,8 @@ export type AvatarProps<
   component?: React.ElementType;
 };
 
+export type AvatarTheme = {
+  MuiAvatar?: CreateThemeComponent<AvatarClassKey, AvatarProps>;
+};
+
 export default Avatar;

packages/mui-material/src/AvatarGroup/AvatarGroup.d.ts

@@ -6,8 +6,8 @@ import {
   PartiallyRequired,
 } from '@mui/types';
 import { SxProps } from '@mui/system';
-import { Theme } from '../styles';
-import { AvatarGroupClasses } from './avatarGroupClasses';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
+import { AvatarGroupClasses, AvatarGroupClassKey } from './avatarGroupClasses';
 import Avatar from '../Avatar';
 import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';
 
@@ -125,4 +125,8 @@ export type AvatarGroupProps<
 export interface AvatarGroupOwnerState
   extends PartiallyRequired<AvatarGroupProps, 'max' | 'spacing' | 'component' | 'variant'> {}
 
+export type AvatarGroupTheme = {
+  MuiAvatarGroup?: CreateThemeComponent<AvatarGroupClassKey, AvatarGroupProps>;
+};
+
 export default AvatarGroup;

packages/mui-material/src/Backdrop/Backdrop.d.ts

@@ -2,8 +2,8 @@ import * as React from 'react';
 import { SxProps } from '@mui/system';
 import { FadeProps } from '../Fade';
 import { TransitionProps } from '../transitions/transition';
-import { Theme } from '../styles';
-import { BackdropClasses } from './backdropClasses';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
+import { BackdropClasses, BackdropClassKey } from './backdropClasses';
 import { OverridableComponent, OverrideProps } from '../OverridableComponent';
 import { CreateSlotsAndSlotProps, SlotComponentProps, SlotProps } from '../utils/types';
 
@@ -142,4 +142,8 @@ export type BackdropProps<
 
 export interface BackdropOwnerState extends BackdropProps {}
 
+export type BackdropTheme = {
+  MuiBackdrop?: CreateThemeComponent<BackdropClassKey, BackdropProps>;
+};
+
 export default Backdrop;

packages/mui-material/src/Badge/Badge.d.ts

@@ -2,9 +2,9 @@ import * as React from 'react';
 import { SxProps } from '@mui/system';
 import { OverridableStringUnion, Simplify } from '@mui/types';
 import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import { OverridableComponent, OverrideProps } from '../OverridableComponent';
-import { BadgeClasses } from './badgeClasses';
+import { BadgeClasses, BadgeClassKey } from './badgeClasses';
 
 export interface BadgePropsVariantOverrides {}
 export interface BadgePropsColorOverrides {}
@@ -182,4 +182,8 @@ export type BadgeProps<
   component?: React.ElementType;
 };
 
+export type BadgeTheme = {
+  MuiBadge?: CreateThemeComponent<BadgeClassKey, BadgeProps>;
+};
+
 export default Badge;

packages/mui-material/src/BottomNavigation/BottomNavigation.d.ts

@@ -1,8 +1,8 @@
 import * as React from 'react';
 import { SxProps } from '@mui/system';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import { OverridableComponent, OverrideProps } from '../OverridableComponent';
-import { BottomNavigationClasses } from './bottomNavigationClasses';
+import { BottomNavigationClasses, BottomNavigationClassKey } from './bottomNavigationClasses';
 
 export interface BottomNavigationOwnProps {
   /**
@@ -62,4 +62,8 @@ export type BottomNavigationProps<
   component?: React.ElementType;
 };
 
+export type BottomNavigationTheme = {
+  MuiBottomNavigation?: CreateThemeComponent<BottomNavigationClassKey, BottomNavigationProps>;
+};
+
 export default BottomNavigation;

packages/mui-material/src/BottomNavigationAction/BottomNavigationAction.d.ts

@@ -1,15 +1,18 @@
 import * as React from 'react';
 import { SxProps } from '@mui/system';
 import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';
-import { Theme } from '../styles';
+import { CreateThemeComponent, Theme } from '../stylesOptimized';
 import {
   ButtonBaseProps,
   ButtonBaseTypeMap,
   ExtendButtonBase,
   ExtendButtonBaseTypeMap,
 } from '../ButtonBase';
 import { OverrideProps } from '../OverridableComponent';
-import { BottomNavigationActionClasses } from './bottomNavigationActionClasses';
+import {
+  BottomNavigationActionClasses,
+  BottomNavigationActionClassKey,
+} from './bottomNavigationActionClasses';
 
 export interface BottomNavigationActionSlots {
   /**
@@ -109,4 +112,11 @@ export type BottomNavigationActionProps<
 export interface BottomNavigationActionOwnerState
   extends Omit<BottomNavigationActionProps, 'slots' | 'slotProps'> {}
 
+export type BottomNavigationActionTheme = {
+  MuiBottomNavigationAction?: CreateThemeComponent<
+    BottomNavigationActionClassKey,
+    BottomNavigationActionProps
+  >;
+};
+
 export default BottomNavigationAction;