[system] Add createTheme util

docs/src/pages/customization/breakpoints/breakpoints.md

@@ -105,7 +105,7 @@ If you are using TypeScript, you would also need to use [module augmentation](/g
 <!-- Tested with packages/material-ui/test/typescript/breakpointsOverrides.augmentation.tsconfig.json -->
 
 ```ts
-declare module '@material-ui/core/styles' {
+declare module '@material-ui/system' {
   interface BreakpointOverrides {
     xs: false; // removes the `xs` breakpoint
     sm: false;

docs/src/pages/guides/migration-v4/migration-v4.md

@@ -1810,6 +1810,27 @@ You can use the [`collapse-rename-collapsedheight` codemod](https://github.com/m
 
 - This HOC was removed. There's an alternative using the `useMediaQuery` hook on [this page](/components/use-media-query/#migrating-from-withwidth).
 
+#### Breakpoints overrides
+
+If you are using TypeScript, and you were using [module augmentation](/guides/typescript/#customization-of-theme) for the theme to accept custom breakpoints values, you need to update the path to the `BreakpointsOverrides` interface.
+
+```diff
++declare module '@material-ui/system' {
+-declare module '@material-ui/core/styles' {
+   interface BreakpointOverrides {
+     xs: false; // removes the `xs` breakpoint
+     sm: false;
+     md: false;
+     lg: false;
+     xl: false;
+     mobile: true; // adds the `mobile` breakpoint
+     tablet: true;
+     laptop: true;
+     desktop: true;
+   }
+ }
+```
+
 ### `@material-ui/types`
 
 - Rename the exported `Omit` type in `@material-ui/types`. The module is now called `DistributiveOmit`. The change removes the confusion with the built-in `Omit` helper introduced in TypeScript v3.5. The built-in `Omit`, while similar, is non-distributive. This leads to differences when applied to union types. [See this StackOverflow answer for further details](https://stackoverflow.com/a/57103940/1009797).

packages/material-ui-lab/tsconfig.build.json

@@ -11,5 +11,8 @@
   },
   "include": ["src/**/*.ts*"],
   "exclude": ["src/**/*.d.ts", "src/**/*.test.*", "./**/*.spec.*", "**/test-utils.tsx"],
-  "references": [{ "path": "../material-ui/tsconfig.build.json" }]
+  "references": [
+    { "path": "../material-ui/tsconfig.build.json" },
+    { "path": "../material-ui-system/tsconfig.build.json" }
+  ]
 }

packages/material-ui-system/src/Box/Box.d.ts

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import { OverridableComponent, OverrideProps } from '@material-ui/types';
+import { Theme } from '../createTheme';
 import {
   SxProps,
   StandardCSSProperties,
@@ -170,8 +171,6 @@ export type SystemProps = {
 } &
   CustomSystemProps;
 
-export interface Theme {}
-
 export interface BoxTypeMap<P = {}, D extends React.ElementType = 'div'> {
   props: P &
     SystemProps & {

packages/material-ui-system/src/createBox.js

@@ -3,6 +3,7 @@ import PropTypes from 'prop-types';
 import clsx from 'clsx';
 import styled, { ThemeContext } from '@material-ui/styled-engine';
 import styleFunctionSx, { extendSxProp } from './styleFunctionSx';
+import createTheme from './createTheme';
 
 function isEmpty(obj) {
   return Object.keys(obj).length === 0;
@@ -13,7 +14,9 @@ const useTheme = (defaultTheme) => {
   return isEmpty(contextTheme) ? defaultTheme : contextTheme;
 };
 
-export default function createBox(defaultTheme = {}) {
+export const systemDefaultTheme = createTheme();
+
+export default function createBox(defaultTheme = systemDefaultTheme) {
   const BoxRoot = styled('div')(styleFunctionSx);
 
   const Box = React.forwardRef(function Box(inProps, ref) {

packages/material-ui-system/src/createStyled.d.ts

@@ -1,8 +1,7 @@
 import * as React from 'react';
 import * as CSS from 'csstype';
 import { SxProps } from './styleFunctionSx';
-
-export interface DefaultTheme {}
+import { Theme as DefaultTheme } from './createTheme';
 
 export interface SerializedStyles {
   name: string;

packages/material-ui-system/src/createStyled.js

@@ -1,4 +1,5 @@
 import styledEngineStyled from '@material-ui/styled-engine';
+import createTheme from './createTheme';
 import styleFunctionSx from './styleFunctionSx';
 import propsToClassKey from './propsToClassKey';
 
@@ -54,25 +55,7 @@ const variantsResolver = (props, styles, theme, name) => {
 export const shouldForwardProp = (prop) =>
   prop !== 'styleProps' && prop !== 'theme' && prop !== 'isRtl' && prop !== 'sx' && prop !== 'as';
 
-export const systemDefaultTheme = {
-  breakpoints: {
-    values: {},
-  },
-  direction: 'ltr',
-  mixins: {},
-  components: {},
-  palette: {
-    mode: 'light',
-  },
-  shadows: {},
-  typography: {},
-  spacing: 8,
-  shape: {
-    borderRadius: 4,
-  },
-  transitions: {},
-  zIndex: {},
-};
+export const systemDefaultTheme = createTheme();
 
 const lowercaseFirstLetter = (string) => {
   return string.charAt(0).toLowerCase() + string.slice(1);
@@ -95,7 +78,7 @@ export default function createStyled(input = {}) {
       ...options
     } = inputOptions;
 
-    // if skipVariantsResolver option is defined, take the value, otherwise, true for root and false for other slots
+    // if skipVariantsResolver option is defined, take the value, otherwise, true for root and false for other slots.
     const skipVariantsResolver =
       inputSkipVariantsResolver !== undefined
         ? inputSkipVariantsResolver
@@ -170,11 +153,11 @@ export default function createStyled(input = {}) {
 
       if (Array.isArray(styleArg) && numOfCustomFnsApplied > 0) {
         const placeholders = new Array(numOfCustomFnsApplied).fill('');
-        // If the type is array, than we need to add placeholders in the template for the overrides, variants and the sx styles
+        // If the type is array, than we need to add placeholders in the template for the overrides, variants and the sx styles.
         transformedStyleArg = [...styleArg, ...placeholders];
         transformedStyleArg.raw = [...styleArg.raw, ...placeholders];
       } else if (typeof styleArg === 'function') {
-        // If the type is function, we need to define the default theme
+        // If the type is function, we need to define the default theme.
         transformedStyleArg = ({ theme: themeInput, ...other }) =>
           styleArg({ theme: isEmpty(themeInput) ? defaultTheme : themeInput, ...other });
       }

packages/material-ui/src/styles/createMixins.spec.ts → packages/material-ui-system/src/createTheme/createMixins.spec.ts

@@ -1,4 +1,4 @@
-import { createTheme, experimentalStyled as styled } from '@material-ui/core/styles';
+import { createTheme, styled } from '@material-ui/system';
 
 {
   const theme = createTheme({

packages/material-ui/src/styles/createMixins.test.js → packages/material-ui-system/src/createTheme/createMixins.test.js

@@ -1,6 +1,6 @@
 import { expect } from 'chai';
 import createMixins from './createMixins';
-import createTheme from './createTheme';
+import createTheme from './index';
 
 describe('createMixins', () => {
   it('should be able add other mixins', () => {

packages/material-ui/src/styles/createSpacing.ts → packages/material-ui-system/src/createTheme/createSpacing.ts

@@ -1,4 +1,4 @@
-import { createUnarySpacing } from '@material-ui/system';
+import { createUnarySpacing } from '../spacing';
 
 export type SpacingOptions =
   | number
@@ -33,7 +33,7 @@ export default function createSpacing(spacingInput: SpacingOptions = 8): Spacing
   }
 
   // Material Design layouts are visually balanced. Most measurements align to an 8dp grid, which aligns both spacing and the overall layout.
-  // Smaller components, such as icons and type, can align to a 4dp grid.
+  // Smaller components, such as icons, can align to a 4dp grid.
   // https://material.io/design/layout/understanding-layout.html#usage
   const transform = createUnarySpacing({
     spacing: spacingInput,

packages/material-ui-system/src/createTheme/createTheme.d.ts

@@ -0,0 +1,40 @@
+import { Breakpoints, BreakpointsOptions } from './createBreakpoints';
+import { Mixins, MixinsOptions } from './createMixins';
+import { Shadows } from './shadows';
+import { Shape, ShapeOptions } from './shape';
+import { Spacing, SpacingOptions } from './createSpacing';
+import { Transitions, TransitionsOptions } from './createTransitions';
+
+export { Breakpoint, BreakpointOverrides } from './createBreakpoints';
+
+export type Direction = 'ltr' | 'rtl';
+
+export interface ThemeOptions {
+  shape?: ShapeOptions;
+  breakpoints?: BreakpointsOptions;
+  direction?: Direction;
+  mixins?: MixinsOptions;
+  palette?: Record<string, any>;
+  shadows?: Shadows;
+  spacing?: SpacingOptions;
+  transitions?: TransitionsOptions;
+}
+
+export interface Theme {
+  shape: Shape;
+  breakpoints: Breakpoints;
+  direction: Direction;
+  mixins: Mixins;
+  palette: Record<string, any> & { mode: 'light' | 'dark' };
+  shadows: Shadows;
+  spacing: Spacing;
+  transitions: Transitions;
+}
+
+/**
+ * Generate a theme base on the options received.
+ * @param options Takes an incomplete theme object and adds the missing parts.
+ * @param args Deep merge the arguments with the about to be returned theme.
+ * @returns A complete, ready to use theme object.
+ */
+export default function createTheme(options?: ThemeOptions, ...args: object[]): Theme;

packages/material-ui-system/src/createTheme/createTheme.js

@@ -0,0 +1,44 @@
+import { deepmerge } from '@material-ui/utils';
+import createBreakpoints from './createBreakpoints';
+import createMixins from './createMixins';
+import shadows from './shadows';
+import shape from './shape';
+import createSpacing from './createSpacing';
+import createTransitions from './createTransitions';
+
+function createTheme(options = {}, ...args) {
+  const {
+    breakpoints: breakpointsInput = {},
+    mixins: mixinsInput = {},
+    palette: paletteInput = {},
+    spacing: spacingInput,
+    transitions: transitionsInput = {},
+    shape: shapeInput = {},
+    ...other
+  } = options;
+
+  const breakpoints = createBreakpoints(breakpointsInput);
+  const spacing = createSpacing(spacingInput);
+
+  let muiTheme = deepmerge(
+    {
+      breakpoints,
+      direction: 'ltr',
+      mixins: createMixins(breakpoints, spacing, mixinsInput),
+      components: {}, // Inject component definitions.
+      palette: { mode: 'light', ...paletteInput },
+      // Don't use [...shadows] until you've verified its transpiled code is not invoking the iterator protocol.
+      shadows: shadows.slice(),
+      spacing,
+      shape: { ...shape, shapeInput },
+      transitions: createTransitions(transitionsInput),
+    },
+    other,
+  );
+
+  muiTheme = args.reduce((acc, argument) => deepmerge(acc, argument), muiTheme);
+
+  return muiTheme;
+}
+
+export default createTheme;

packages/material-ui-system/src/createTheme/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './createTheme';
+export * from './createTheme';

packages/material-ui-system/src/createTheme/index.js

@@ -0,0 +1 @@
+export { default } from './createTheme';

packages/material-ui-system/src/index.d.ts

@@ -1,5 +1,3 @@
-import * as React from 'react';
-import { CSSObject } from './createStyled';
 import {
   ComposedStyleFunction,
   StyleFunction,
@@ -13,7 +11,6 @@ import {
   positions,
   shadows,
   sizing,
-  spacing,
   typography,
 } from './Box';
 // disable automatic export
@@ -82,69 +79,6 @@ export const sizeHeight: SimpleStyleFunction<'sizeHeight'>;
 export const boxSizing: SimpleStyleFunction<'boxSizing'>;
 export type SizingProps = PropsFor<typeof sizing>;
 
-// spacing.js
-export type SpacingProps = PropsFor<typeof spacing>;
-export function createUnarySpacing<Spacing>(theme: { spacing: Spacing }): Spacing extends number
-  ? (abs: number | string) => number | number
-  : Spacing extends any[]
-  ? <Index extends number>(abs: Index | string) => Spacing[Index] | string
-  : Spacing extends (...args: unknown[]) => unknown
-  ? Spacing
-  : // warns in Dev
-    () => undefined;
-
-export const margin: SimpleStyleFunction<
-  | 'm'
-  | 'mt'
-  | 'mr'
-  | 'mb'
-  | 'ml'
-  | 'mx'
-  | 'my'
-  | 'margin'
-  | 'marginTop'
-  | 'marginRight'
-  | 'marginBottom'
-  | 'marginLeft'
-  | 'marginX'
-  | 'marginY'
->;
-
-export type MarginProps = PropsFor<typeof margin>;
-
-export const padding: SimpleStyleFunction<
-  | 'p'
-  | 'pt'
-  | 'pr'
-  | 'pb'
-  | 'pl'
-  | 'px'
-  | 'py'
-  | 'padding'
-  | 'paddingTop'
-  | 'paddingRight'
-  | 'paddingBottom'
-  | 'paddingLeft'
-  | 'paddingX'
-  | 'paddingY'
->;
-
-export type PaddingProps = PropsFor<typeof padding>;
-
-// style.js
-export interface StyleOptions<PropKey> {
-  cssProperty?: PropKey | keyof React.CSSProperties | false;
-  prop: PropKey;
-  /**
-   * dot access in `Theme`
-   */
-  themeKey?: string;
-  transform?: (cssValue: unknown) => number | string | React.CSSProperties | CSSObject;
-}
-export function style<PropKey extends string, Theme extends object>(
-  options: StyleOptions<PropKey>,
-): StyleFunction<{ [K in PropKey]?: unknown } & { theme: Theme }>;
-
 // typography.js
 export const typographyVariant: SimpleStyleFunction<'typography'>;
 export const fontFamily: SimpleStyleFunction<'fontFamily'>;
@@ -166,6 +100,9 @@ export function unstable_getThemeValue(prop: string, value: any, theme: object):
  */
 export type ResponsiveStyleValue<T> = T | Array<T | null> | { [key: string]: T | null };
 
+export * from './style';
+export * from './spacing';
+
 export {
   default as unstable_styleFunctionSx,
   extendSxProp as unstable_extendSxProp,
@@ -183,3 +120,28 @@ export * from './createStyled';
 
 export { default as styled } from './styled';
 export * from './styled';
+
+export { default as createTheme } from './createTheme';
+export * from './createTheme';
+
+export { default as createBreakpoints } from './createTheme/createBreakpoints';
+export * from './createTheme/createBreakpoints';
+
+export { Mixins, MixinsOptions } from './createTheme/createMixins';
+
+export {
+  duration,
+  easing,
+  Duration,
+  Easing,
+  Transitions,
+  TransitionsOptions,
+} from './createTheme/createTransitions';
+
+export { SpacingOptions } from './createTheme/createSpacing';
+
+export { default as themeShadows } from './createTheme/shadows';
+export * from './createTheme/shadows';
+
+export { default as shape } from './createTheme/shape';
+export * from './createTheme/shape';

packages/material-ui-system/src/index.js

@@ -30,3 +30,8 @@ export { default as createBox } from './createBox';
 export { default as createStyled } from './createStyled';
 export * from './createStyled';
 export { default as styled } from './styled';
+export { default as createTheme } from './createTheme';
+export { default as createBreakpoints } from './createTheme/createBreakpoints';
+export { duration, easing } from './createTheme/createTransitions';
+export { default as themeShadows } from './createTheme/shadows';
+export { default as shape } from './createTheme/shape';