@mui/system 5.0.3 → 5.1.0

package/createStyled.d.ts

@@ -1,208 +1,34 @@
 import * as React from 'react';
-import * as CSS from 'csstype';
+import {
+  CreateMUIStyled as CreateMUIStyledStyledEngine,
+  CSSInterpolation,
+} from '@mui/styled-engine';
 import { SxProps } from './styleFunctionSx';
 import { Theme as DefaultTheme } from './createTheme';
 
-export interface SerializedStyles {
-  name: string;
-  styles: string;
-  map?: string;
-  next?: SerializedStyles;
-}
-
-export type CSSProperties = CSS.PropertiesFallback<number | string>;
-export type CSSPropertiesWithMultiValues = {
-  [K in keyof CSSProperties]: CSSProperties[K] | Array<Extract<CSSProperties[K], string>>;
-};
-export type CSSPseudos = { [K in CSS.Pseudos]?: unknown | CSSObject };
-
-export interface CSSOthersObject {
-  [propertiesName: string]: unknown | CSSInterpolation;
-}
-export type CSSPseudosForCSSObject = { [K in CSS.Pseudos]?: CSSObject };
-
-export interface ArrayCSSInterpolation extends Array<CSSInterpolation> {}
-
-export interface CSSOthersObjectForCSSObject {
-  [propertiesName: string]: CSSInterpolation;
-}
-
-export interface CSSObject extends CSSPropertiesWithMultiValues, CSSPseudos, CSSOthersObject {}
-
-export interface ComponentSelector {
-  __emotion_styles: any;
-}
-
-export type Keyframes = {
-  name: string;
-  styles: string;
-  anim: number;
-  toString: () => string;
-} & string;
-
-export type Equal<A, B, T, F> = A extends B ? (B extends A ? T : F) : F;
-
-export type InterpolationPrimitive =
-  | null
-  | undefined
-  | boolean
-  | number
-  | string
-  | ComponentSelector
-  | Keyframes
-  | SerializedStyles
-  | CSSObject;
-
-export type CSSInterpolation = InterpolationPrimitive | ArrayCSSInterpolation;
-
-export interface FunctionInterpolation<Props> {
-  (props: Props): Interpolation<Props>;
-}
-
-export interface ArrayInterpolation<Props> extends Array<Interpolation<Props>> {}
-
-export type Interpolation<Props> =
-  | InterpolationPrimitive
-  | ArrayInterpolation<Props>
-  | FunctionInterpolation<Props>;
-
-/**
- * @desc Utility type for getting props type of React component.
- * It takes `defaultProps` into an account - making props with defaults optional.
- */
-export type PropsOf<C extends keyof JSX.IntrinsicElements | React.JSXElementConstructor<any>> =
-  JSX.LibraryManagedAttributes<C, React.ComponentProps<C>>;
-
-export type Overwrapped<T, U> = Pick<T, Extract<keyof T, keyof U>>;
-
-export interface StyledComponent<InnerProps, OwnerState, Theme extends object>
-  extends React.FunctionComponent<InnerProps & OwnerState & { theme?: Theme }>,
-    ComponentSelector {}
+export function shouldForwardProp(propName: PropertyKey): boolean;
 
-export interface StyledOptions {
-  label?: string;
-  shouldForwardProp?(propName: PropertyKey): boolean;
-  target?: string;
+export interface MUIStyledCommonProps<Theme extends object = DefaultTheme> {
+  theme?: Theme;
+  as?: React.ElementType;
+  sx?: SxProps<Theme>;
 }
 
 export interface MuiStyledOptions {
   name?: string;
   slot?: string;
+  // The difference between Interpolation and CSSInterpolation is that the former supports functions based on props
+  // If we want to support props in the overrides, we will need to change the CSSInterpolation to Interpolation<Props>
   overridesResolver?: (props: any, styles: Record<string, CSSInterpolation>) => CSSInterpolation;
   skipVariantsResolver?: boolean;
   skipSx?: boolean;
 }
 
-/** Same as StyledOptions but shouldForwardProp must be a type guard */
-export interface FilteringStyledOptions<Props, ForwardedProps extends keyof Props = keyof Props> {
-  label?: string;
-  shouldForwardProp?(propName: PropertyKey): propName is ForwardedProps;
-  target?: string;
-}
-
-/**
- * @typeparam ComponentProps  Props which will be included when withComponent is called
- * @typeparam SpecificComponentProps  Props which will *not* be included when withComponent is called
- */
-export interface CreateStyledComponent<
-  ComponentProps extends {},
-  SpecificComponentProps extends {} = {},
-  JSXProps extends {} = {},
-> {
-  /**
-   * @typeparam AdditionalProps  Additional props to add to your styled component
-   */
-  <AdditionalProps extends {} = {}>(
-    ...styles: Array<
-      Interpolation<
-        ComponentProps & SpecificComponentProps & AdditionalProps & { theme: DefaultTheme }
-      >
-    >
-  ): StyledComponent<ComponentProps & AdditionalProps, SpecificComponentProps, JSXProps>;
-
-  (
-    template: TemplateStringsArray,
-    ...styles: Array<
-      Interpolation<ComponentProps & SpecificComponentProps & { theme: DefaultTheme }>
-    >
-  ): StyledComponent<ComponentProps, SpecificComponentProps, JSXProps>;
-
-  /**
-   * @typeparam AdditionalProps  Additional props to add to your styled component
-   */
-  <AdditionalProps extends {}>(
-    template: TemplateStringsArray,
-    ...styles: Array<
-      Interpolation<
-        ComponentProps & SpecificComponentProps & AdditionalProps & { theme: DefaultTheme }
-      >
-    >
-  ): StyledComponent<ComponentProps & AdditionalProps, SpecificComponentProps, JSXProps>;
-}
-
-export interface MUIStyledCommonProps<Theme extends object = DefaultTheme> {
-  theme?: Theme;
-  as?: React.ElementType;
-  sx?: SxProps<Theme>;
-}
-
-export interface CreateMUIStyled<Theme extends object = DefaultTheme> {
-  <
-    C extends React.ComponentClass<React.ComponentProps<C>>,
-    ForwardedProps extends keyof React.ComponentProps<C> = keyof React.ComponentProps<C>,
-  >(
-    component: C,
-    options: FilteringStyledOptions<React.ComponentProps<C>, ForwardedProps> & MuiStyledOptions,
-  ): CreateStyledComponent<
-    Pick<PropsOf<C>, ForwardedProps> & MUIStyledCommonProps<Theme>,
-    {},
-    {
-      ref?: React.Ref<InstanceType<C>>;
-    }
-  >;
-
-  <C extends React.ComponentClass<React.ComponentProps<C>>>(
-    component: C,
-    options?: StyledOptions & MuiStyledOptions,
-  ): CreateStyledComponent<
-    PropsOf<C> & MUIStyledCommonProps<Theme>,
-    {},
-    {
-      ref?: React.Ref<InstanceType<C>>;
-    }
-  >;
-
-  <
-    C extends React.JSXElementConstructor<React.ComponentProps<C>>,
-    ForwardedProps extends keyof React.ComponentProps<C> = keyof React.ComponentProps<C>,
-  >(
-    component: C,
-    options: FilteringStyledOptions<React.ComponentProps<C>, ForwardedProps> & MuiStyledOptions,
-  ): CreateStyledComponent<Pick<PropsOf<C>, ForwardedProps> & MUIStyledCommonProps<Theme>>;
-
-  <C extends React.JSXElementConstructor<React.ComponentProps<C>>>(
-    component: C,
-    options?: StyledOptions & MuiStyledOptions,
-  ): CreateStyledComponent<PropsOf<C> & MUIStyledCommonProps<Theme>>;
-
-  <
-    Tag extends keyof JSX.IntrinsicElements,
-    ForwardedProps extends keyof JSX.IntrinsicElements[Tag] = keyof JSX.IntrinsicElements[Tag],
-  >(
-    tag: Tag,
-    options: FilteringStyledOptions<JSX.IntrinsicElements[Tag], ForwardedProps> & MuiStyledOptions,
-  ): CreateStyledComponent<
-    MUIStyledCommonProps<Theme>,
-    Pick<JSX.IntrinsicElements[Tag], ForwardedProps>
-  >;
-
-  <Tag extends keyof JSX.IntrinsicElements>(
-    tag: Tag,
-    options?: StyledOptions & MuiStyledOptions,
-  ): CreateStyledComponent<MUIStyledCommonProps<Theme>, JSX.IntrinsicElements[Tag]>;
-}
-
-export function shouldForwardProp(propName: PropertyKey): boolean;
+export type CreateMUIStyled<T extends object = DefaultTheme> = CreateMUIStyledStyledEngine<
+  MUIStyledCommonProps<T>,
+  MuiStyledOptions,
+  T
+>;
 
 export default function createStyled<T extends object = DefaultTheme>(options?: {
   defaultTheme?: T;

package/createStyled.js

@@ -5,8 +5,8 @@ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefau
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.shouldForwardProp = shouldForwardProp;
 exports.default = createStyled;
+exports.shouldForwardProp = shouldForwardProp;
 exports.systemDefaultTheme = void 0;
 
 var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
@@ -134,7 +134,11 @@ function createStyled(input = {}) {
 
     const muiStyledResolver = (styleArg, ...expressions) => {
       const expressionsWithDefaultTheme = expressions ? expressions.map(stylesArg => {
-        return typeof stylesArg === 'function' ? _ref => {
+        // On the server emotion doesn't use React.forwardRef for creating components, so the created
+        // component stays as a function. This condition makes sure that we do not interpolate functions
+        // which are basically components used as a selectors.
+        // eslint-disable-next-line no-underscore-dangle
+        return typeof stylesArg === 'function' && stylesArg.__emotion_real !== stylesArg ? _ref => {
           let {
             theme: themeInput
           } = _ref,

package/createTheme/createBreakpoints.d.ts

@@ -8,20 +8,67 @@ export type Breakpoint = OverridableStringUnion<
 >;
 export const keys: Breakpoint[];
 
+// Keep in sync with docs/src/pages/customization/breakpoints/breakpoints.md
+// #default-branch-switch
 export interface Breakpoints {
   keys: Breakpoint[];
+  /**
+   * Each breakpoint (a key) matches with a fixed screen width (a value).
+   * @default {
+   *    // extra-small
+   *    xs: 0,
+   *    // small
+   *    sm: 600,
+   *    // medium
+   *    md: 900,
+   *    // large
+   *    lg: 1200,
+   *    // extra-large
+   *    xl: 1536,
+   * }
+   */
   values: { [key in Breakpoint]: number };
+  /**
+   * @param key - A breakpoint key (`xs`, `sm`, etc.) or a screen width number in px.
+   * @returns A media query string ready to be used with most styling solutions, which matches screen widths greater than the screen size given by the breakpoint key (inclusive).
+   * @see [API documentation](https://mui.com/customization/breakpoints/#theme-breakpoints-up-key-media-query)
+   */
   up: (key: Breakpoint | number) => string;
+  /**
+   * @param key - A breakpoint key (`xs`, `sm`, etc.) or a screen width number in px.
+   * @returns A media query string ready to be used with most styling solutions, which matches screen widths less than the screen size given by the breakpoint key (exclusive).
+   * @see [API documentation](https://mui.com/customization/breakpoints/#theme-breakpoints-down-key-media-query)
+   */
   down: (key: Breakpoint | number) => string;
+  /**
+   * @param start - A breakpoint key (`xs`, `sm`, etc.) or a screen width number in px.
+   * @param end - A breakpoint key (`xs`, `sm`, etc.) or a screen width number in px.
+   * @returns A media query string ready to be used with most styling solutions, which matches screen widths greater than
+   *          the screen size given by the breakpoint key in the first argument (inclusive) and less than the screen size given by the breakpoint key in the second argument (exclusive).
+   * @see [API documentation](https://mui.com/customization/breakpoints/#theme-breakpoints-between-start-end-media-query)
+   */
   between: (start: Breakpoint | number, end: Breakpoint | number) => string;
+  /**
+   * @param key - A breakpoint key (`xs`, `sm`, etc.) or a screen width number in px.
+   * @returns A media query string ready to be used with most styling solutions, which matches screen widths starting from
+   *          the screen size given by the breakpoint key (inclusive) and stopping at the screen size given by the next breakpoint key (exclusive).
+   * @see [API documentation](https://mui.com/customization/breakpoints/#theme-breakpoints-only-key-media-query)
+   */
   only: (key: Breakpoint) => string;
 }
 
-export type BreakpointsOptions = Partial<
-  {
-    unit: string;
-    step: number;
-  } & Breakpoints
->;
+export interface BreakpointsOptions extends Partial<Breakpoints> {
+  /**
+   * The increment divided by 100 used to implement exclusive breakpoints.
+   * For example, `step: 5` means that `down(500)` will result in `'(max-width: 499.95px)'`.
+   * @default 5
+   */
+  step?: number | undefined;
+  /**
+   * The unit used for the breakpoint's values.
+   * @default 'px'
+   */
+  unit?: string | undefined;
+}
 
 export default function createBreakpoints(options: BreakpointsOptions): Breakpoints;

package/createTheme/createBreakpoints.js

@@ -5,8 +5,8 @@ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefau
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = createBreakpoints;
 exports.breakpointKeys = void 0;
+exports.default = createBreakpoints;
 
 var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
 
@@ -27,12 +27,12 @@ function createBreakpoints(breakpoints) {
       xs: 0,
       // phone
       sm: 600,
-      // tablets
+      // tablet
       md: 900,
       // small laptop
       lg: 1200,
       // desktop
-      xl: 1536 // large screens
+      xl: 1536 // large screen
 
     },
     unit = 'px',

package/cssVars/createCssVarsProvider.d.ts

@@ -0,0 +1,131 @@
+import * as React from 'react';
+import { Result, Mode } from './useCurrentColorScheme';
+
+type RequiredDeep<T> = {
+  [K in keyof T]-?: RequiredDeep<T[K]>;
+};
+
+export type BuildCssVarsTheme<ThemeInput> = ThemeInput extends {
+  colorSchemes: Record<string, infer ColorSystems>;
+}
+  ? Omit<ThemeInput, 'colorSchemes'> &
+      ColorSystems & { vars: Omit<ThemeInput, 'colorSchemes'> & ColorSystems }
+  : never;
+
+/**
+ * DesignSystemColorScheme: is what a design system provide by default. Mostly, `light` and `dark`
+ * ApplicationColorScheme: is what developer can extend from a design system. Ex, `comfort` `trueDark` ...any name that they want
+ *
+ * This type enhance customization experience by checking if developer has extended the colorScheme or not (usually via module augmentation)
+ * If yes, they must provide the palette of the extended colorScheme. Otherwise `theme` is optional.
+ */
+type DecideTheme<
+  DesignSystemTheme extends { colorSchemes: Record<DesignSystemColorScheme, any> },
+  DesignSystemColorScheme extends string,
+  ApplicationTheme extends { colorSchemes: Record<ApplicationColorScheme, any> },
+  ApplicationColorScheme extends string | never,
+> = [ApplicationColorScheme] extends [never]
+  ? { theme?: DesignSystemTheme }
+  : {
+      theme: Omit<ApplicationTheme, 'colorSchemes'> & {
+        colorSchemes: Partial<
+          Record<
+            DesignSystemColorScheme,
+            DesignSystemTheme['colorSchemes'][DesignSystemColorScheme]
+          >
+        > &
+          RequiredDeep<
+            Record<ApplicationColorScheme, ApplicationTheme['colorSchemes'][ApplicationColorScheme]>
+          >;
+      };
+    };
+
+export interface ColorSchemeContextValue<SupportedColorScheme extends string>
+  extends Result<SupportedColorScheme> {
+  allColorSchemes: SupportedColorScheme[];
+}
+
+export default function createCssVarsProvider<
+  DesignSystemThemeInput extends {
+    colorSchemes: Record<DesignSystemColorScheme, any>;
+  },
+  DesignSystemColorScheme extends string,
+  ApplicationThemeInput extends {
+    colorSchemes: Record<ApplicationColorScheme, any>;
+  } = never,
+  ApplicationColorScheme extends string = never,
+>(options: {
+  /**
+   * Design system default theme
+   */
+  theme: DesignSystemThemeInput;
+  /**
+   * Design system default color scheme
+   */
+  defaultColorScheme:
+    | DesignSystemColorScheme
+    | { light: DesignSystemColorScheme; dark: DesignSystemColorScheme };
+  /**
+   * Design system default mode
+   * @default 'light'
+   */
+  defaultMode?: Mode;
+  /**
+   * CSS variable prefix
+   * @default ''
+   */
+  prefix?: string;
+  /**
+   * A function to determine if the key, value should be attached as CSS Variable
+   * `keys` is an array that represents the object path keys.
+   *  Ex, if the theme is { foo: { bar: 'var(--test)' } }
+   *  then, keys = ['foo', 'bar']
+   *        value = 'var(--test)'
+   */
+  shouldSkipGeneratingVar?: (keys: string[], value: string | number) => boolean;
+}): {
+  CssVarsProvider: (
+    props: React.PropsWithChildren<
+      {
+        /**
+         * Application default mode (overrides design system `defaultMode` if specified)
+         */
+        defaultMode?: Mode;
+        /**
+         * Application default colorScheme (overrides design system `defaultColorScheme` if specified)
+         */
+        defaultColorScheme?:
+          | DesignSystemColorScheme
+          | ApplicationColorScheme
+          | {
+              light: DesignSystemColorScheme | ApplicationColorScheme;
+              dark: DesignSystemColorScheme | ApplicationColorScheme;
+            };
+        /**
+         * localStorage key used to store application `mode`
+         * @default 'mui-mode'
+         */
+        modeStorageKey?: string;
+        /**
+         * DOM attribute for applying color scheme
+         * @default 'data-mui-color-scheme'
+         */
+        attribute?: string;
+        /**
+         * CSS variable prefix (overrides design system `prefix` if specified)
+         */
+        prefix?: string;
+      } & DecideTheme<
+        DesignSystemThemeInput,
+        DesignSystemColorScheme,
+        ApplicationThemeInput,
+        ApplicationColorScheme
+      >
+    >,
+  ) => React.ReactElement;
+  useColorScheme: () => ColorSchemeContextValue<DesignSystemColorScheme | ApplicationColorScheme>;
+  getInitColorSchemeScript: () => React.ReactElement;
+};
+
+// disable automatic export
+export {};