[POC] Improve TypeScript Theme Components Performance

docs/types/theme-augment.d.ts

@@ -0,0 +1,6 @@
+import type { Theme } from '@mui/material/styles';
+import type { Components } from '@mui/material/stylesDeprecated';
+
+declare module '@mui/material/styles' {
+  interface ThemeComponents extends Components<Theme> {}
+}

packages/mui-docs/src/branding/brandingTheme.ts

@@ -2,12 +2,15 @@ import type { CSSObject } from '@mui/system';
 import type {} from '@mui/material/themeCssVarsAugmentation';
 import ArrowDropDownRounded from '@mui/icons-material/ArrowDropDownRounded';
 import { createTheme, ThemeOptions, Theme, alpha } from '@mui/material/styles';
+import { Components } from '@mui/material/stylesDeprecated';
 
 interface ApplyDarkStyles {
   (scheme: CSSObject): CSSObject;
 }
 
 declare module '@mui/material/styles' {
+  interface ThemeComponents extends Components<Theme> {}
+
   interface Theme {
     applyDarkStyles: ApplyDarkStyles;
   }

packages/mui-lab/src/themeAugmentation/components.ts

@@ -2,8 +2,8 @@ import {
   ComponentsProps,
   ComponentsOverrides,
   ComponentsVariants,
-  Theme as MuiTheme,
-} from '@mui/material/styles';
+} from '@mui/material/stylesDeprecated';
+import { Theme as MuiTheme } from '@mui/material/styles';
 
 type Theme = Omit<MuiTheme, 'components'>;
 
@@ -68,6 +68,6 @@ export interface LabComponents {
   };
 }
 
-declare module '@mui/material/styles' {
+declare module '@mui/material/stylesDeprecated' {
   interface Components extends LabComponents {}
 }

packages/mui-lab/src/themeAugmentation/overrides.ts

@@ -25,7 +25,7 @@ export interface LabComponentNameToClassKey {
   MuiTimelineSeparator: TimelineSeparatorClassKey;
 }
 
-declare module '@mui/material/styles' {
+declare module '@mui/material/stylesDeprecated' {
   interface ComponentNameToClassKey extends LabComponentNameToClassKey {}
 }
 

packages/mui-lab/src/themeAugmentation/props.ts

@@ -24,7 +24,7 @@ export interface LabComponentsPropsList {
   MuiTimelineSeparator: TimelineSeparatorProps;
 }
 
-declare module '@mui/material/styles' {
+declare module '@mui/material/stylesDeprecated' {
   interface ComponentsPropsList extends LabComponentsPropsList {}
 }
 

packages/mui-material/perf-test/README.md

@@ -0,0 +1,61 @@
+# TypeScript Performance Test
+
+Run TypeScript performance diagnostics for `createTheme` to measure type instantiation costs.
+
+## Prerequisites
+
+```bash
+npm install -g @typescript/analyze-trace
+```
+
+## Run Performance Test
+
+```bash
+cd packages/mui-material/perf-test
+```
+
+### 1. Run Basic Diagnostics
+
+```bash
+npx tsc --noEmit --diagnostics
+```
+
+Key metrics to note:
+
+- `Instantiations` (target: < 500,000)
+- `Memory used` (target: < 300MB)
+- `Check time` (lower is better)
+
+### 2. Generate Trace
+
+```bash
+npx tsc --noEmit --generateTrace trace-output --incremental false
+```
+
+### 3. Analyze Trace
+
+```bash
+analyze-trace trace-output
+```
+
+Look for:
+
+- Top instantiated types
+- Hottest files
+- Memory allocation patterns
+
+### 4. Visual Analysis (Optional)
+
+1. Open Chrome: `chrome://tracing`
+2. Load `trace-output/trace.json`
+3. Find repeated `Components<Omit<Theme, 'components'>>` instantiations
+
+## Files
+
+- `test-createTheme.ts` - Test file that triggers the circular dependency
+- `tsconfig.json` - TypeScript configuration
+- `trace-output/` - Generated trace files
+
+## More Details
+
+See `.claude/typescript-performance-diagnosis.md` for comprehensive guide.

packages/mui-material/perf-test/test-createTheme.ts

@@ -0,0 +1,16 @@
+import { ButtonTheme } from '@mui/material/Button';
+import { createTheme } from '../src/styles';
+
+declare module '@mui/material/styles' {
+  interface ThemeComponents extends ButtonTheme {}
+}
+
+export default createTheme({
+  components: {
+    MuiButton: {
+      defaultProps: {
+        disableElevation: true,
+      },
+    },
+  },
+});

packages/mui-material/perf-test/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../../tsconfig.json",
+  "include": ["test-createTheme.ts"],
+  "compilerOptions": {
+    "moduleResolution": "Bundler"
+  }
+}

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

@@ -1,10 +1,10 @@
 import * as React from 'react';
 import { DistributiveOmit, OverridableStringUnion } from '@mui/types';
 import { SxProps } from '@mui/system';
-import { Theme } from '../styles';
+import { Theme, CreateThemeComponent } from '../styles';
 import { ExtendButtonBase, ExtendButtonBaseTypeMap } from '../ButtonBase';
 import { OverrideProps, OverridableComponent, OverridableTypeMap } from '../OverridableComponent';
-import { ButtonClasses } from './buttonClasses';
+import { ButtonClasses, ButtonClassKey } from './buttonClasses';
 
 export interface ButtonPropsVariantOverrides {}
 
@@ -146,4 +146,8 @@ export type ButtonProps<
   component?: React.ElementType;
 };
 
+export type ButtonTheme = {
+  MuiButton: CreateThemeComponent<ButtonClassKey, ButtonProps>;
+};
+
 export default Button;

packages/mui-material/src/DefaultPropsProvider/DefaultPropsProvider.tsx

@@ -4,7 +4,7 @@ import PropTypes from 'prop-types';
 import SystemDefaultPropsProvider, {
   useDefaultProps as useSystemDefaultProps,
 } from '@mui/system/DefaultPropsProvider';
-import type { ComponentsPropsList } from '../styles/props';
+import type { ComponentsPropsList } from '../stylesDeprecated/props';
 
 function DefaultPropsProvider(
   props: React.PropsWithChildren<{

packages/mui-material/src/locale/utils/LocaleTextApi.ts

@@ -1,4 +1,4 @@
-import { ComponentsPropsList } from '../../styles/props';
+import { ComponentsPropsList } from '../../stylesDeprecated/props';
 
 export interface Localization {
   components?: {

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

@@ -11,7 +11,8 @@ import createThemeNoVars, {
   ThemeOptions as ThemeNoVarsOptions,
 } from './createThemeNoVars';
 
-export type { Theme, CssThemeVariables } from './createThemeNoVars';
+export type { Theme, CssThemeVariables, CreateThemeComponent } from './createThemeNoVars';
+export type { ThemeComponents } from './createThemeFoundation';
 
 type CssVarsOptions = CssThemeVariables extends {
   enabled: true;

packages/mui-material/src/styles/createThemeFoundation.ts

@@ -33,6 +33,11 @@ export type ExtendedColorScheme = OverridableStringUnion<never, ColorSchemeOverr
  */
 export type SupportedColorScheme = DefaultColorScheme | ExtendedColorScheme;
 
+export interface ThemeComponents {
+  mergeClassNameAndStyles?: boolean;
+  [componentName: string]: any;
+}
+
 export interface Opacity {
   inputPlaceholder: number;
   inputUnderline: number;

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

@@ -1,6 +1,7 @@
 import {
   ThemeOptions as SystemThemeOptions,
   Theme as SystemTheme,
+  Interpolation,
   SxProps,
   CSSObject,
   SxConfig,
@@ -11,8 +12,12 @@ import { TypographyVariants, TypographyVariantsOptions } from './createTypograph
 import { Shadows } from './shadows';
 import { Transitions, TransitionsOptions } from './createTransitions';
 import { ZIndex, ZIndexOptions } from './zIndex';
-import { Components } from './components';
-import { CssVarsTheme, CssVarsPalette, ColorSystemOptions } from './createThemeFoundation';
+import {
+  CssVarsTheme,
+  CssVarsPalette,
+  ColorSystemOptions,
+  ThemeComponents,
+} from './createThemeFoundation';
 
 /**
  * To disable custom properties, use module augmentation
@@ -34,7 +39,7 @@ type CssVarsOptions = CssThemeVariables extends {
 
 export interface ThemeOptions extends Omit<SystemThemeOptions, 'zIndex'>, CssVarsOptions {
   mixins?: MixinsOptions;
-  components?: Components<Omit<Theme, 'components'>>;
+  components?: ThemeComponents;
   palette?: PaletteOptions;
   shadows?: Shadows;
   transitions?: TransitionsOptions;
@@ -82,14 +87,41 @@ type CssVarsProperties = CssThemeVariables extends { enabled: true }
  */
 export interface Theme extends BaseTheme, CssVarsProperties {
   cssVariables?: false;
-  components?: Components<BaseTheme>;
+  components?: ThemeComponents;
   unstable_sx: (props: SxProps<Theme>) => CSSObject;
   unstable_sxConfig: SxConfig;
   alpha: (color: string, value: number | string) => string;
   lighten: (color: string, coefficient: number | string) => string;
   darken: (color: string, coefficient: number | string) => string;
 }
 
+export type CreateThemeComponent<SlotNames extends string, Props, OwnerState = Props> = {
+  defaultProps?: Partial<Props>;
+  styleOverrides?: Record<
+    SlotNames,
+    Interpolation<
+      // Record<string, unknown> is for other props that the slot receive internally
+      // Documenting all ownerStates could be a huge work, let's wait until we have a real needs from developers.
+      Props &
+        Record<string, unknown> & {
+          ownerState: OwnerState & Record<string, unknown>;
+        } & {
+          theme: Theme;
+        } & Record<string, unknown>
+    >
+  >;
+  variants?: Array<{
+    props:
+      | Partial<Props>
+      | ((
+          props: Partial<Props> & {
+            ownerState: Partial<OwnerState>;
+          },
+        ) => boolean);
+    style: Interpolation<{ theme: Theme }>;
+  }>;
+};
+
 /**
  * Generate a theme base on the options received.
  * @param options Takes an incomplete theme object and adds the missing parts.

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

@@ -1,5 +1,4 @@
 import { ThemeOptions, Theme } from './createThemeNoVars';
-import { Components } from './components';
 import {
   DefaultColorScheme,
   ColorSchemeOverrides,
@@ -31,10 +30,10 @@ import {
   ColorSystemOptions,
   CssVarsPalette,
   ColorSystem,
+  CssVarsTheme,
   ThemeVars,
   ThemeCssVarOverrides,
   ThemeCssVar,
-  CssVarsTheme,
 } from './createThemeFoundation';
 
 // Re-export all types from foundation to maintain backward compatibility
@@ -75,7 +74,7 @@ export type {
   CssVarsTheme,
 };
 
-export interface CssVarsThemeOptions extends Omit<ThemeOptions, 'palette' | 'components'> {
+export interface CssVarsThemeOptions extends Omit<ThemeOptions, 'palette'> {
   /**
    * The strategy to generate CSS variables
    *
@@ -123,10 +122,6 @@ export interface CssVarsThemeOptions extends Omit<ThemeOptions, 'palette' | 'com
    * @default 'light'
    */
   defaultColorScheme?: SupportedColorScheme;
-  /**
-   * Theme components
-   */
-  components?: Components<Omit<Theme, 'components' | 'palette'> & CssVarsTheme>;
   /**
    * Color schemes configuration
    */

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

@@ -6,9 +6,10 @@ export {
   default as unstable_createMuiStrictModeTheme,
   ThemeOptions,
   Theme,
+  ThemeComponents,
   CssThemeVariables,
+  CreateThemeComponent,
 } from './createTheme';
-export { default as adaptV4Theme, DeprecatedThemeOptions } from './adaptV4Theme';
 export { Shadows } from './shadows';
 export { ZIndex } from './zIndex';
 export {
@@ -80,10 +81,6 @@ export { default as useThemeProps } from './useThemeProps';
 export * from './useThemeProps';
 export { default as styled } from './styled';
 export { default as ThemeProvider, ThemeProviderProps } from './ThemeProvider';
-export { ComponentsProps, ComponentsPropsList } from './props';
-export { ComponentsVariants } from './variants';
-export { ComponentsOverrides, ComponentNameToClassKey } from './overrides';
-export { Components } from './components';
 export { getUnit as unstable_getUnit, toUnitless as unstable_toUnitless } from './cssUtils';
 
 export type ClassNameMap<ClassKey extends string = string> = Record<ClassKey, string>;

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

@@ -1,5 +1,4 @@
 export { default as THEME_ID } from './identifier';
-export { default as adaptV4Theme } from './adaptV4Theme';
 export {
   hexToRgb,
   rgbToHex,

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

@@ -1,8 +1,7 @@
-import { Theme } from './createTheme';
-import { Components } from './components';
+import { ThemeComponents } from './createThemeFoundation';
 
 export interface ThemeWithProps {
-  components?: Components<Omit<Theme, 'components'>>;
+  components?: ThemeComponents;
 }
 
 export type ThemedProps<Theme, Name extends keyof any> = Theme extends {

packages/mui-material/src/styles/adaptV4Theme.d.ts → packages/mui-material/src/stylesDeprecated/adaptV4Theme.d.ts

@@ -1,14 +1,14 @@
 import { BreakpointsOptions, ShapeOptions, SpacingOptions } from '@mui/system';
-import { MixinsOptions } from './createMixins';
-import { Palette, PaletteOptions } from './createPalette';
-import { TypographyVariantsOptions } from './createTypography';
-import { Shadows } from './shadows';
-import { TransitionsOptions } from './createTransitions';
-import { ZIndexOptions } from './zIndex';
+import { MixinsOptions } from '../styles/createMixins';
+import { Palette, PaletteOptions } from '../styles/createPalette';
+import { TypographyVariantsOptions } from '../styles/createTypography';
+import { Shadows } from '../styles/shadows';
+import { TransitionsOptions } from '../styles/createTransitions';
+import { ZIndexOptions } from '../styles/zIndex';
 import { ComponentsOverrides } from './overrides';
 import { ComponentsVariants } from './variants';
 import { ComponentsProps } from './props';
-import { Theme } from './createTheme';
+import { Theme } from '../styles/createTheme';
 
 export type Direction = 'ltr' | 'rtl';
 

packages/mui-material/src/stylesDeprecated/index.ts

@@ -0,0 +1,6 @@
+export { default as adaptV4Theme } from './adaptV4Theme';
+export { DeprecatedThemeOptions } from './adaptV4Theme';
+export { ComponentsProps, ComponentsPropsList } from './props';
+export { ComponentsVariants } from './variants';
+export { ComponentsOverrides, ComponentNameToClassKey } from './overrides';
+export { Components } from './components';