[Typography] Improve the upgrade story (#13214)

* [Typography] Improve the upgrade story

* [core] Use documented direct propTypes call

* let's complete the effort

.size-limit.js

@@ -16,13 +16,13 @@ module.exports = [
     name: 'The initial cost paid for using one component',
     webpack: true,
     path: 'packages/material-ui/build/Paper/index.js',
-    limit: '18.2 KB',
+    limit: '17.6 KB',
   },
   {
     name: 'The size of all the material-ui modules.',
     webpack: true,
     path: 'packages/material-ui/build/index.js',
-    limit: '93.2 KB',
+    limit: '92.7 KB',
   },
   {
     name: 'The main docs bundle',

CHANGELOG.md

@@ -35,8 +35,6 @@ This change updates the variant wording to match the one used in the Material De
 +<Button variant="contained" />
 ```
 
-You can suppress the warnings with the environment variable `MUI_SUPPRESS_DEPRECATION_WARNINGS` set to a truthy value.
-
 #### Changes
 
 - [TextField] Ensure labelWidth is set (#13077) @evanstern

docs/scripts/buildApi.js

@@ -3,7 +3,7 @@
 import { mkdir, readFileSync, writeFileSync } from 'fs';
 import path from 'path';
 import kebabCase from 'lodash/kebabCase';
-import * as reactDocgen from 'react-docgen';
+import { parse as docgenParse } from 'react-docgen';
 import generateMarkdown from '../src/modules/utils/generateMarkdown';
 import { findPagesMarkdown, findComponents } from '../src/modules/utils/find';
 import { getHeaders } from '../src/modules/utils/parseMarkdown';
@@ -39,7 +39,7 @@ if (args.length < 4) {
 
 const rootDirectory = path.resolve(__dirname, '../../');
 const docsApiDirectory = path.resolve(rootDirectory, args[3]);
-const theme = createMuiTheme();
+const theme = createMuiTheme({ typography: { useNextVariants: true } });
 
 const inheritedComponentRegexp = /\/\/ @inheritedComponent (.*)/;
 
@@ -123,7 +123,7 @@ function buildDocs(options) {
 
   let reactAPI;
   try {
-    reactAPI = reactDocgen.parse(src);
+    reactAPI = docgenParse(src);
   } catch (err) {
     console.log('Error parsing src for', componentObject.filename);
     throw err;
@@ -134,7 +134,7 @@ function buildDocs(options) {
   reactAPI.pagesMarkdown = pagesMarkdown;
   reactAPI.src = src;
 
-  // if (reactAPI.name !== 'Snackbar') {
+  // if (reactAPI.name !== 'Button') {
   //   return;
   // }
 

docs/src/modules/utils/generateMarkdown.js

@@ -2,6 +2,7 @@
 
 import { parse as parseDoctrine } from 'doctrine';
 import recast from 'recast';
+import { parse as docgenParse } from 'react-docgen';
 import { _rewriteUrlForNextExport } from 'next/router';
 import { pageToTitle } from './helpers';
 
@@ -23,20 +24,39 @@ function generateHeader(reactAPI) {
 }
 
 function getDeprecatedInfo(type) {
-  const deprecatedPropType = 'deprecated(PropTypes.';
-
-  const indexStart = type.raw.indexOf(deprecatedPropType);
+  const marker = 'deprecated(PropTypes.';
+  const indexStart = type.raw.indexOf(marker);
 
   if (indexStart !== -1) {
     return {
-      propTypes: type.raw.substring(indexStart + deprecatedPropType.length, type.raw.indexOf(',')),
+      propTypes: type.raw.substring(indexStart + marker.length, type.raw.indexOf(',')),
       explanation: recast.parse(type.raw).program.body[0].expression.arguments[1].value,
     };
   }
 
   return false;
 }
 
+function getChained(type) {
+  const marker = 'chainPropTypes';
+  const indexStart = type.raw.indexOf(marker);
+
+  if (indexStart !== -1) {
+    const parsed = docgenParse(`
+      import PropTypes from 'prop-types';
+      const Foo = () => <div />
+      Foo.propTypes = {
+        bar: ${recast.print(recast.parse(type.raw).program.body[0].expression.arguments[0]).code}
+      }
+      export default Foo
+    `);
+
+    return parsed.props.bar.type;
+  }
+
+  return false;
+}
+
 function escapeCell(value) {
   // As the pipe is use for the table structure
   return value
@@ -50,7 +70,6 @@ function generatePropDescription(description, type) {
 
   if (type.name === 'custom') {
     const deprecatedInfo = getDeprecatedInfo(type);
-
     if (deprecatedInfo) {
       deprecated = `*Deprecated*. ${deprecatedInfo.explanation}<br><br>`;
     }
@@ -123,13 +142,17 @@ function generatePropType(type) {
   switch (type.name) {
     case 'custom': {
       const deprecatedInfo = getDeprecatedInfo(type);
-
       if (deprecatedInfo !== false) {
         return generatePropType({
           name: deprecatedInfo.propTypes,
         });
       }
 
+      const chained = getChained(type);
+      if (chained !== false) {
+        return generatePropType(chained);
+      }
+
       return type.raw;
     }
 

docs/src/pages/demos/buttons/CustomizedButtons.js

@@ -60,6 +60,9 @@ const theme = createMuiTheme({
   palette: {
     primary: green,
   },
+  typography: {
+    useNextVariants: true,
+  },
 });
 
 function CustomizedInputs(props) {

docs/src/pages/style/icons/icons.md

@@ -29,7 +29,7 @@ Optionally, you can set the icon color using one of the theme color properties:
 ### SVG Material icons
 
 It's interesting to have the building blocks needed to implement custom icons, but what about presets?
-We provide a separate NPM package,
+We provide a separate npm package,
 [@material-ui/icons](https://www.npmjs.com/package/@material-ui/icons),
 that includes the 1,000+ official [Material icons](https://material.io/tools/icons/?style=baseline) converted to `SvgIcon` components.
 

docs/src/pages/style/typography/DeprecatedTypes.js

@@ -14,7 +14,6 @@ function typographyV1Theme(theme) {
   return createMuiTheme({
     ...theme,
     typography: {
-      suppressDeprecationWarnings: true,
       useNextVariants: false,
     },
   });

docs/src/pages/style/typography/typography.md

@@ -57,15 +57,15 @@ Hopefully, you might be able to take advantage of the [`typography`](/customizat
 
 ## Migration to typography v2
 
-The material design specification changed concerning variant names and styles. To allow
-a smooth transition we kept old variants and restyled variants for backwards compatibility
-but will log deprecation warnings. We will remove the old variants with our next
-major release.
+The material design specification changed concerning variant names and styles.
+To allow a smooth transition we kept old variants and restyled variants for backwards compatibility but we log deprecation warnings.
+We will remove the old typography variants in the next major release v4.0.0 (Q1 2019).
 
 ### Strategies
 
 To make an immediate switch to typography v2 you can simply pass `useNextVariants: true` when
 calling `createMuiTheme`:
+
 ```js
 const theme = createMuiTheme({
   typography: {
@@ -74,9 +74,11 @@ const theme = createMuiTheme({
 });
 ```
 
+or set `window.__MUI_USE_NEXT_TYPOGRAPHY_VARIANTS__ = true;` if you don't use the theme.
+
 This will use new variants instead of old variants according to the following mapping:
 
-```json
+```sh
 display4 => h1
 display3 => h2
 display2 => h3
@@ -88,24 +90,6 @@ body2 => body1
 body1 (default) => body2 (default)
 ```
 
-Please note that this will still log deprecation warnings if you use one of the variants.
+Please note that this will log deprecation warnings if you use one of the old variants.
 We recommend you replace those old variants with the recommended variants to be prepared
-for the next major release.
-
-See [Themes](/customization/themes/) for more information about how to use a global theme.
-
-### Deprecation warnings for v4.0.0
-
-Deprecation warnings are logged when:
-- `NODE_ENV` is not strictly equal to `production`
-- Regardless of whether you directly use the `Typography` component with a deprecated variant or another component
-  has a `Typography` component with a deprecated variant
-- You override the style of a deprecated variant with `createMuiTheme`
-- You override the style of a restyled variant without `useNextVariants` with `createMuiTheme`
-- Variants are considered deprecated if:
-  - They will be removed in the next major release. This includes: display4, display3, display2, display1, headline, title, subheading
-  - They will be restyled and `useNextVariants` is falsy. This includes: body2, body1, caption, button
-
-In some cases the deprecation warnings can break your test suite which might be inconvenient.
-In those cases you can set the environment variable `MUI_SUPPRESS_DEPRECATION_WARNINGS` to a truthy value.
-Passing `suppressDeprecationWarnings: true` to the typography options in `createMuiTheme` is equivalent.
+for the next major release. See [Themes](/customization/themes/) for more information about how to use a global theme.

examples/cdn/index.html

@@ -43,6 +43,9 @@
       dark: colors.green[700],
     },
   },
+  typography: {
+    useNextVariants: true,
+  },
 });
 
 const styles = theme => ({

examples/create-react-app-with-flow/src/withRoot.js

@@ -22,6 +22,9 @@ const theme = createMuiTheme({
       dark: green[700],
     },
   },
+  typography: {
+    useNextVariants: true,
+  },
 });
 
 function withRoot(Component: ComponentType<*>) {

examples/create-react-app-with-jss/src/withRoot.js

@@ -18,6 +18,9 @@ const theme = createMuiTheme({
     primary: purple,
     secondary: green,
   },
+  typography: {
+    useNextVariants: true,
+  },
 });
 
 // Create a JSS instance with the default preset of plugins.

examples/create-react-app-with-typescript/src/withRoot.tsx

@@ -11,6 +11,9 @@ const theme = createMuiTheme({
     primary: purple,
     secondary: green,
   },
+  typography: {
+    useNextVariants: true,
+  },
 });
 
 function withRoot<P>(Component: React.ComponentType<P>) {

examples/create-react-app/src/withRoot.js

@@ -19,6 +19,9 @@ const theme = createMuiTheme({
       dark: green[700],
     },
   },
+  typography: {
+    useNextVariants: true,
+  },
 });
 
 function withRoot(Component) {

examples/gatsby/src/getPageContext.js

@@ -20,6 +20,9 @@ const theme = createMuiTheme({
       dark: green[700],
     },
   },
+  typography: {
+    useNextVariants: true,
+  },
 });
 
 function createPageContext() {

examples/nextjs/src/getPageContext.js

@@ -20,6 +20,9 @@ const theme = createMuiTheme({
       dark: green[700],
     },
   },
+  typography: {
+    useNextVariants: true,
+  },
 });
 
 function createPageContext() {

examples/parcel/src/withRoot.js

@@ -19,6 +19,9 @@ const theme = createMuiTheme({
       dark: green[700],
     },
   },
+  typography: {
+    useNextVariants: true,
+  },
 });
 
 function withRoot(Component) {

examples/ssr/client.js

@@ -31,6 +31,9 @@ const theme = createMuiTheme({
     accent: red,
     type: 'light',
   },
+  typography: {
+    useNextVariants: true,
+  },
 });
 
 // Create a new class name generator.

examples/ssr/server.js

@@ -42,6 +42,9 @@ function handleRender(req, res) {
       accent: red,
       type: 'light',
     },
+    typography: {
+      useNextVariants: true,
+    },
   });
 
   // Create a new class name generator.

package.json

@@ -44,10 +44,10 @@
     "size:why": "size-limit --why packages/material-ui/build/index.js",
     "size:overhead:why": "size-limit --why ./test/size/overhead.js",
     "test": "yarn lint && yarn typescript && yarn test:coverage",
-    "test:unit": "cross-env NODE_ENV=test MUI_SUPPRESS_DEPRECATION_WARNINGS=true mocha packages/material-ui/test/**/*.test.js packages/material-ui/src/{,**/}*.test.js docs/src/**/*.test.js",
+    "test:unit": "cross-env NODE_ENV=test mocha packages/material-ui/test/**/*.test.js packages/material-ui/src/{,**/}*.test.js docs/src/**/*.test.js",
     "test:watch": "yarn test:unit --watch",
-    "test:coverage": "cross-env NODE_ENV=test BABEL_ENV=coverage MUI_SUPPRESS_DEPRECATION_WARNINGS=true nyc mocha packages/material-ui/test/**/*.test.js packages/material-ui/src/{,**/}*.test.js && nyc report -r lcovonly",
-    "test:coverage:html": "cross-env NODE_ENV=test BABEL_ENV=coverage MUI_SUPPRESS_DEPRECATION_WARNINGS=true nyc mocha packages/material-ui/test/**/*.test.js packages/material-ui/src/{,**/}*.test.js && nyc report --reporter=html",
+    "test:coverage": "cross-env NODE_ENV=test BABEL_ENV=coverage nyc mocha packages/material-ui/test/**/*.test.js packages/material-ui/src/{,**/}*.test.js && nyc report -r lcovonly",
+    "test:coverage:html": "cross-env NODE_ENV=test BABEL_ENV=coverage nyc mocha packages/material-ui/test/**/*.test.js packages/material-ui/src/{,**/}*.test.js && nyc report --reporter=html",
     "test:karma": "cross-env NODE_ENV=test karma start test/karma.conf.js --single-run",
     "test:regressions": "webpack --config test/regressions/webpack.config.js && rimraf test/regressions/screenshots/chrome/* && vrtest run --config test/vrtest.config.js --record",
     "typescript": "tslint -p tsconfig.json \"packages/*/{src,test}/**/*.{ts,tsx}\"",