Utilities

/**
 * Convert hexadecimal color to RGB format
 * @param hex - Hexadecimal color string (e.g., '#1976d2')
 * @returns RGB color string (e.g., 'rgb(25, 118, 210)')
 */
function hexToRgb(hex: string): string;

/**
 * Convert RGB color to hexadecimal format
 * @param color - RGB color string (e.g., 'rgb(25, 118, 210)')
 * @returns Hexadecimal color string (e.g., '#1976d2')
 */
function rgbToHex(color: string): string;

/**
 * Convert HSL color to RGB format
 * @param color - HSL color string (e.g., 'hsl(210, 79%, 46%)')
 * @returns RGB color string (e.g., 'rgb(25, 118, 210)')
 */
function hslToRgb(color: string): string;

/**
 * Parse color string into type and component values
 * @param color - Color string in any supported format
 * @returns Color object with type and values
 */
function decomposeColor(color: string): ColorObject;

/**
 * Reconstruct color string from decomposed components
 * @param color - Color object with type and values
 * @returns Color string in original format
 */
function recomposeColor(color: ColorObject): string;

interface ColorObject {
  /** Color format type */
  type: ColorFormat;
  
  /** Color component values */
  values: number[];
  
  /** Color space (for color() format) */
  colorSpace?: string;
}

type ColorFormat = 'rgb' | 'rgba' | 'hsl' | 'hsla' | 'color';

/**
 * Calculate WCAG contrast ratio between two colors
 * @param foreground - Foreground color string
 * @param background - Background color string
 * @returns Contrast ratio (1-21)
 */
function getContrastRatio(foreground: string, background: string): number;

/**
 * Calculate relative luminance of a color
 * @param color - Color string in any supported format
 * @returns Relative luminance (0-1)
 */
function getLuminance(color: string): number;

/**
 * Apply alpha transparency to a color
 * @param color - Base color string
 * @param value - Alpha value (0-1)
 * @returns Color with applied alpha
 */
function alpha(color: string, value: number): string;

/**
 * Darken a color by specified amount
 * @param color - Base color string
 * @param coefficient - Darkening amount (0-1)
 * @returns Darkened color
 */
function darken(color: string, coefficient: number): string;

/**
 * Lighten a color by specified amount
 * @param color - Base color string
 * @param coefficient - Lightening amount (0-1)
 * @returns Lightened color
 */
function lighten(color: string, coefficient: number): string;

/**
 * Emphasize a color (lighten or darken based on luminance)
 * @param color - Base color string
 * @param coefficient - Emphasis amount (0-1, default: 0.15)
 * @returns Emphasized color
 */
function emphasize(color: string, coefficient?: number): string;

/**
 * Blend overlay color onto background color
 * @param background - Background color string
 * @param overlay - Overlay color string
 * @param opacity - Overlay opacity (0-1)
 * @param gamma - Gamma correction factor (default: 1.0)
 * @returns Blended color
 */
function blend(
  background: string, 
  overlay: string, 
  opacity: number, 
  gamma?: number
): string;

/**
 * Extract color channel from color string
 * @param color - Color string in any supported format
 * @returns Color channel string for CSS
 */
function colorChannel(color: string): string;

// Private/Safe variants with error handling
/**
 * Safe alpha function with error handling
 * @param color - Base color string
 * @param value - Alpha value (0-1)
 * @param warning - Optional warning message
 * @returns Color with applied alpha or fallback
 */
function private_safeAlpha(color: string, value: number, warning?: string): string;

/**
 * Safe darken function with error handling
 * @param color - Base color string
 * @param coefficient - Darkening amount (0-1)
 * @param warning - Optional warning message
 * @returns Darkened color or fallback
 */
function private_safeDarken(color: string, coefficient: number, warning?: string): string;

/**
 * Safe lighten function with error handling
 * @param color - Base color string
 * @param coefficient - Lightening amount (0-1)
 * @param warning - Optional warning message
 * @returns Lightened color or fallback
 */
function private_safeLighten(color: string, coefficient: number, warning?: string): string;

/**
 * Safe emphasize function with error handling
 * @param color - Base color string
 * @param coefficient - Emphasis amount (0-1)
 * @param warning - Optional warning message
 * @returns Emphasized color or fallback
 */
function private_safeEmphasize(color: string, coefficient?: number, warning?: string): string;

/**
 * Safe color channel extraction with error handling
 * @param color - Color string
 * @param warning - Optional warning message
 * @returns Color channel string or fallback
 */
function private_safeColorChannel(color: string, warning?: string): string;

import { 
  alpha, 
  darken, 
  lighten, 
  getContrastRatio,
  hexToRgb 
} from "@mui/system";

// Color manipulation
const primaryColor = '#1976d2';
const lightPrimary = lighten(primaryColor, 0.2);
const darkPrimary = darken(primaryColor, 0.2);
const transparentPrimary = alpha(primaryColor, 0.5);

// Contrast checking
const contrastRatio = getContrastRatio('#000000', '#ffffff'); // 21
const isAccessible = contrastRatio >= 4.5; // true

// Color conversion
const rgbColor = hexToRgb('#1976d2'); // 'rgb(25, 118, 210)'

// Theme usage
const theme = createTheme({
  palette: {
    primary: {
      main: '#1976d2',
      light: lighten('#1976d2', 0.2),
      dark: darken('#1976d2', 0.2),
    },
  },
});

/**
 * Handle responsive prop values across breakpoints
 * @param prop - Responsive prop value or object
 * @param transform - Value transformation function
 * @param breakpoints - Breakpoints object
 * @returns Processed breakpoint styles
 */
function handleBreakpoints<T>(
  prop: T | Partial<Record<Breakpoint, T>>,
  transform: (value: T) => any,
  breakpoints?: Breakpoints
): any;

/**
 * Merge breakpoint-specific styles in correct order
 * @param breakpoints - Breakpoints object
 * @param styles - Array of style objects with breakpoint keys
 * @returns Merged styles object
 */
function mergeBreakpointsInOrder(
  breakpoints: Breakpoints,
  styles: Array<Record<string, any>>
): Record<string, any>;

/**
 * Resolve responsive values to specific breakpoint values
 * @param values - Responsive values object
 * @param breakpoints - Breakpoints to resolve
 * @returns Resolved values for each breakpoint
 */
function unstable_resolveBreakpointValues<T>(
  values: T | Partial<Record<Breakpoint, T>>,
  breakpoints?: Breakpoint[]
): Partial<Record<Breakpoint, T>>;

/**
 * Responsive breakpoint style function
 */
const breakpoints: StyleFunction<{
  [key in Breakpoint]?: any;
}>;

import { handleBreakpoints, createTheme } from "@mui/system";

const theme = createTheme();

// Handle responsive prop
const responsiveStyles = handleBreakpoints(
  { xs: 1, md: 2, lg: 3 },
  (value) => ({ padding: theme.spacing(value) }),
  theme.breakpoints
);

// Results in:
// {
//   padding: '8px',
//   '@media (min-width: 900px)': { padding: '16px' },
//   '@media (min-width: 1200px)': { padding: '24px' }
// }

/**
 * Add container queries support to theme
 * @param theme - Base theme object
 * @returns Theme with container queries
 */
function cssContainerQueries<T extends Theme>(theme: T): T & CssContainerQueries;

interface CssContainerQueries {
  /** Container queries helper methods */
  containerQueries: ContainerQueries;
}

interface ContainerQueries {
  /** Generate container query for minimum width */
  up(key: string | number): string;
  
  /** Generate container query for maximum width */
  down(key: string | number): string;
  
  /** Generate container query between two sizes */
  between(start: string | number, end: string | number): string;
  
  /** Generate container query for specific size only */
  only(key: string): string;
}

/**
 * Sort container queries by size
 * @param queries - Container query objects
 * @returns Sorted queries array
 */
function sortContainerQueries(queries: Array<{ key: string; value: number }>): Array<{ key: string; value: number }>;

/**
 * Get container query string from shorthand
 * @param shorthand - Container query shorthand
 * @returns Full container query string
 */
function getContainerQuery(shorthand: string): string;

/**
 * Check if value is container query shorthand
 * @param value - Value to check
 * @returns True if container query shorthand
 */
function isCqShorthand(value: any): boolean;

/**
 * Hook for responsive breakpoint matching
 * @param queryInput - Media query string or function
 * @param options - Hook configuration options
 * @returns Boolean indicating if query matches
 */
function useMediaQuery<Theme = Theme>(
  queryInput: string | ((theme: Theme) => string),
  options?: UseMediaQueryOptions
): boolean;

interface UseMediaQueryOptions {
  /** Default match state (used during SSR) */
  defaultMatches?: boolean;
  
  /** Custom matchMedia implementation */
  matchMedia?: (query: string) => MediaQueryList;
  
  /** Disable server-side rendering hydration mismatch */
  noSsr?: boolean;
  
  /** Server-side media query matcher */
  ssrMatchMedia?: (query: string) => { matches: boolean };
}

/**
 * Factory for creating custom useMediaQuery hook
 * @param matchMedia - Custom matchMedia implementation
 * @returns Custom useMediaQuery hook
 */
function unstable_createUseMediaQuery(
  matchMedia: (query: string) => MediaQueryList
): typeof useMediaQuery;

import { useMediaQuery, useTheme } from "@mui/system";

function ResponsiveComponent() {
  const theme = useTheme();
  const isMobile = useMediaQuery(theme.breakpoints.down('sm'));
  const isDesktop = useMediaQuery('(min-width: 1200px)');
  
  return (
    <div>
      {isMobile ? 'Mobile view' : 'Desktop view'}
      {isDesktop && <div>Large screen content</div>}
    </div>
  );
}

// With options
function SSRComponent() {
  const matches = useMediaQuery('(min-width: 600px)', {
    defaultMatches: true, // Assume match during SSR
    noSsr: false,
  });
  
  return <div>{matches ? 'Wide' : 'Narrow'}</div>;
}

/**
 * Get value from theme using dot notation path
 * @param theme - Theme object
 * @param path - Dot notation path (e.g., 'palette.primary.main')
 * @returns Value at theme path
 */
function unstable_getThemeValue(theme: Theme, path: string): any;

/**
 * Memoize theme object for performance optimization
 * @param theme - Theme object to memoize
 * @returns Memoized theme object
 */
function unstable_memoTheme<T extends Theme>(theme: T): T;

/**
 * PropTypes validator for responsive props
 */
const responsivePropType: any;

/**
 * Provider for RTL (right-to-left) support
 */
declare const RtlProvider: React.ComponentType<RtlProviderProps>;

interface RtlProviderProps {
  /** Child components */
  children: React.ReactNode;
  
  /** RTL value (true for RTL, false for LTR) */
  value: boolean;
}

/**
 * Hook to access RTL context
 * @returns RTL boolean value
 */
function useRtl(): boolean;

/**
 * Legacy sx function (deprecated, throws error)
 * @deprecated Use theme.unstable_sx instead
 */
function experimental_sx(): never;

/**
 * Create CSS variables provider component
 * @param options - Provider configuration
 * @returns CSS variables provider result
 */
function unstable_createCssVarsProvider<Theme extends Record<string, any>>(
  options: CssVarsProviderConfig<Theme>
): CreateCssVarsProviderResult<Theme>;

interface CssVarsProviderConfig<Theme> {
  /** Theme creation function */
  theme: Theme | ((colorScheme: string) => Theme);
  
  /** Default color scheme */
  defaultColorScheme?: string;
  
  /** Storage key for color scheme preference */
  storageKey?: string;
  
  /** Available color schemes */
  colorSchemes?: string[];
  
  /** CSS variable prefix */
  prefix?: string;
}

interface CreateCssVarsProviderResult<Theme> {
  /** CSS variables provider component */
  CssVarsProvider: React.ComponentType<any>;
  
  /** Hook to access theme with CSS variables */
  useTheme: () => Theme;
  
  /** Hook to access color scheme context */
  useColorScheme: () => ColorSchemeContextValue;
}

interface ColorSchemeContextValue {
  /** Current color scheme */
  colorScheme: string;
  
  /** Set color scheme */
  setColorScheme: (scheme: string) => void;
}

/**
 * Create CSS variable getter function
 * @param prefix - CSS variable prefix
 * @returns CSS variable getter function
 */
function unstable_createGetCssVar(prefix?: string): (field: string) => string;

/**
 * Parse theme values into CSS custom properties
 * @param theme - Theme object
 * @param options - Parsing options
 * @returns CSS variables object
 */
function unstable_cssVarsParser<Theme>(
  theme: Theme,
  options?: { prefix?: string }
): Record<string, string>;

/**
 * Prepare theme for CSS custom properties
 * @param theme - Theme object
 * @param options - Preparation options
 * @returns Theme with CSS variables support
 */
function unstable_prepareCssVars<Theme>(
  theme: Theme,
  options?: { prefix?: string }
): Theme & { cssVars: Record<string, string> };

/**
 * Create theme optimized for CSS custom properties
 * @param options - Theme options with CSS variables support
 * @returns CSS variables-enabled theme
 */
function unstable_createCssVarsTheme<Theme>(
  options: any
): Theme & { cssVars: Record<string, string> };

/**
 * Inline script for color scheme initialization
 * @param options - Configuration options
 * @returns Script element for color scheme initialization
 */
function InitColorSchemeScript(options?: InitColorSchemeScriptProps): React.ReactElement;

interface InitColorSchemeScriptProps {
  /** Default mode when storage is empty */
  defaultMode?: 'system' | 'light' | 'dark';
  
  /** Default color scheme for light mode */
  defaultLightColorScheme?: string;
  
  /** Default color scheme for dark mode */
  defaultDarkColorScheme?: string;
  
  /** DOM node for color scheme attribute */
  colorSchemeNode?: string;
  
  /** localStorage key for mode */
  modeStorageKey?: string;
  
  /** localStorage key for color scheme */
  colorSchemeStorageKey?: string;
  
  /** DOM attribute for color scheme */
  attribute?: 'class' | 'data' | string;
  
  /** CSP nonce for inline script */
  nonce?: string;
}

// Constants for default storage keys
const DEFAULT_MODE_STORAGE_KEY: string;
const DEFAULT_COLOR_SCHEME_STORAGE_KEY: string;
const DEFAULT_ATTRIBUTE: string;

import { InitColorSchemeScript } from "@mui/system";

// In your _document.js (Next.js) or index.html
function Document() {
  return (
    <html>
      <head>
        <InitColorSchemeScript />
      </head>
      <body>
        <Main />
      </body>
    </html>
  );
}

// With custom configuration
<InitColorSchemeScript
  defaultMode="system"
  defaultLightColorScheme="blue"
  defaultDarkColorScheme="dark-blue"
  attribute="data-color-scheme"
  modeStorageKey="my-mode"
/>

// For class-based color scheme
<InitColorSchemeScript
  attribute="class"
  defaultLightColorScheme="light-theme"
  defaultDarkColorScheme="dark-theme"
/>

/**
 * Current package version string
 */
const version: string;

import { version } from "@mui/system";

console.log(`MUI System version: ${version}`); // "7.3.2"

// Conditional logic based on version
if (version.startsWith('7.')) {
  // Version 7.x specific code
}

/**
 * RTL context provider component
 * @param props - RTL provider props
 * @returns Provider component
 */
declare const RtlProvider: React.ComponentType<RtlProviderProps>;

interface RtlProviderProps {
  /** Child components */
  children?: React.ReactNode;
  
  /** Whether RTL mode is enabled (default: false) */
  value?: boolean;
}

/**
 * Hook to access current RTL state
 * @returns Boolean indicating if RTL mode is active
 */
function useRtl(): boolean;

import { RtlProvider, useRtl } from "@mui/system";

// App with RTL support
function App() {
  const [isRtl, setIsRtl] = useState(false);
  
  return (
    <div dir={isRtl ? 'rtl' : 'ltr'}>
      <RtlProvider value={isRtl}>
        <MyComponent />
        <button onClick={() => setIsRtl(!isRtl)}>
          Toggle RTL
        </button>
      </RtlProvider>
    </div>
  );
}

// Component using RTL state
function DirectionalComponent() {
  const isRtl = useRtl();
  
  return (
    <Box
      sx={{
        marginLeft: isRtl ? 0 : 2,
        marginRight: isRtl ? 2 : 0,
        textAlign: isRtl ? 'right' : 'left',
      }}
    >
      Directional content
    </Box>
  );
}

// Styled component with RTL support
const StyledBox = styled(Box)(({ theme }) => {
  const isRtl = useRtl();
  
  return {
    paddingLeft: isRtl ? 0 : theme.spacing(2),
    paddingRight: isRtl ? theme.spacing(2) : 0,
    borderLeftWidth: isRtl ? 0 : 1,
    borderRightWidth: isRtl ? 1 : 0,
  };
});

/**
 * CSS container queries theme extension
 * @param theme - Theme object to extend
 * @returns Theme with container query support
 */
function cssContainerQueries<T extends Theme>(theme: T): T & CssContainerQueries;

interface CssContainerQueries {
  /** Container query methods */
  containerQueries: ((name: string) => ContainerQueries) & ContainerQueries;
}

interface ContainerQueries {
  /** Generate min-width container query */
  up(key: string | number): string;
  
  /** Generate max-width container query */
  down(key: string | number): string;
  
  /** Generate container query between two breakpoints */
  between(start: string | number, end: string | number): string;
  
  /** Generate container query for specific breakpoint only */
  only(key: string): string;
  
  /** Generate container query excluding specific breakpoint */
  not(key: string): string;
}

/**
 * Sort container queries from low to high for consistent CSS order
 * @param theme - Theme with container queries
 * @param css - CSS object with container queries
 * @returns Sorted CSS object
 */
function sortContainerQueries(
  theme: Partial<CssContainerQueries>,
  css: Record<string, any>
): Record<string, any>;

/**
 * Check if value is a container query shorthand
 * @param breakpointKeys - Available breakpoint keys
 * @param value - Value to check
 * @returns Boolean indicating if value is CQ shorthand
 */
function isCqShorthand(breakpointKeys: string[], value: string): boolean;

/**
 * Get container query string for breakpoint
 * @param theme - Theme with container queries
 * @param breakpoint - Breakpoint key or value
 * @param container - Container name (optional)
 * @returns Container query string
 */
function getContainerQuery(
  theme: CssContainerQueries,
  breakpoint: string | number,
  container?: string
): string;

import { cssContainerQueries, createTheme } from "@mui/system";

// Create theme with container queries
const theme = createTheme();
const themeWithCq = cssContainerQueries(theme);

// Using container queries in sx prop
<Box
  sx={{
    padding: 1,
    [themeWithCq.containerQueries.up('md')]: {
      padding: 2,
    },
    [themeWithCq.containerQueries.between('sm', 'lg')]: {
      backgroundColor: 'grey.100',
    },
  }}
>
  Container-responsive content
</Box>

// Named container queries
<Box
  sx={{
    containerType: 'inline-size',
    containerName: 'sidebar',
  }}
>
  <Box
    sx={{
      fontSize: '14px',
      [themeWithCq.containerQueries('sidebar').up('300px')]: {
        fontSize: '16px',
      },
      [themeWithCq.containerQueries('sidebar').up('500px')]: {
        fontSize: '18px',
      },
    }}
  >
    Sidebar content
  </Box>
</Box>

// Styled component with container queries
const ResponsiveCard = styled(Box)(({ theme }) => {
  const cqTheme = cssContainerQueries(theme);
  
  return {
    padding: theme.spacing(1),
    [cqTheme.containerQueries.up('200px')]: {
      padding: theme.spacing(2),
    },
    [cqTheme.containerQueries.up('400px')]: {
      padding: theme.spacing(3),
      display: 'grid',
      gridTemplateColumns: '1fr 1fr',
    },
  };
});