[docs] AppBar and Textfield demos in TypeScript

.circleci/config.yml

@@ -161,6 +161,12 @@ jobs:
       - *restore_yarn_offline_mirror
       - *restore_yarn_cache
       - *install_js
+      - run:
+          name: Transpile TypeScript demos
+          command: yarn docs:typescript:formatted
+      - run:
+          name: Are the compiled TypeScript demos equivalent to the JavaScript demos?
+          command: git diff --exit-code
       - run:
           name: Can we generate the @material-ui/core build?
           command: cd packages/material-ui && yarn build

.eslintignore

@@ -6,6 +6,7 @@
 /examples/create-react-app-with-flow/flow
 /examples/create-react-app-with-flow/flow-typed
 /examples/gatsby/public
+/packages/babel-plugin-unwrap-createStyles/test/__fixtures__/
 /packages/material-ui-codemod/lib
 /packages/material-ui-codemod/src/*/*.test
 /packages/material-ui-codemod/src/*/*.test.js

.size-limit.js

@@ -74,7 +74,7 @@ module.exports = [
     name: 'The main docs bundle',
     webpack: false,
     path: main.path,
-    limit: '191 KB',
+    limit: '193 KB',
   },
   {
     name: 'The docs home page',

CONTRIBUTING.md

@@ -50,6 +50,8 @@ We will only accept a pull request for which all tests pass. Make sure the follo
 - If API documentation is being changed in the source, `yarn docs:api` was run.
 - If prop types were changed, the TypeScript declarations were updated.
 - If TypeScript declarations were changed, `yarn typescript` passed.
+- If demos were changed, make sure `yarn docs:typescript:formatted` does not introduce changes.
+  See [About TypeScript demos](#about-typescript-demos).
 - The PR title follows the pattern `[Component] Imperative commit message`. (See: [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/#imperative) for a great explanation)
 
 ## Getting started
@@ -80,6 +82,8 @@ yarn
 yarn docs:dev
 ```
 You can now access the documentation site [locally](http://localhost:3000).
+Changes to the docs will hot reload the site. If you make changes to TypeScript files
+in the docs run `yarn docs:typescript --watch` in a separate terminal.
 
 Test coverage is limited at present, but where possible, please add tests for any changes you make. Tests can be run with `yarn test`.
 
@@ -118,6 +122,14 @@ docs/src/pages/demos/buttons/
 ```
 And let's give it a name: `SuperButtons.js`.
 
+We try to also document how to use this library with TypeScript. If you are familiar with
+that language try writing that demo in TypeScript in a *.tsx file. When you're done
+run `yarn docs:typescript:formatted` to automatically add a JavaScript version.
+
+Apart from the inherent pros and cons of TypeScript the demos are also used to test our
+type declarations. This helps a lot in catching regressions when updating our type
+declarations.
+
 #### 2. Edit the page Markdown file.
 
 The Markdown file is the source for the website documentation. So, whatever you wrote there will be reflected on the website.
@@ -155,6 +167,20 @@ Then, you will need to add the following code:
 
 In case you missed something, [we have a real example that can be used as a summary report]((https://github.com/mui-org/material-ui/pull/8922/files)).
 
+### About TypeScript demos
+
+To help people use this library with TypeScript we try to provide equivalent demos
+in TypeScript. 
+
+Changing demos in JavaScript requires a manual update of the TypeScript
+version. If you are not familiar with this language you can add the filepath
+of the TS demo to `docs/ts-demo-ignore.json`. See `docs/babel.config.ts.js` for more
+information. Otherwise our CI will fail the `test_build` job. 
+A contributor can later update the TypeScript version of that demo.
+
+If you are already familiar with TypeScript you can simply write the demo in TypeScript.
+`yarn docs:typescript:formatted` will transpile it down to JavaScript.
+
 ## How do I use my local distribution of material-ui in any project?
 
 Sometimes it is good to test your changes in a real world scenario, in order to do that you can install your local distribution of Material-UI in any project with [yarn link](https://yarnpkg.com/lang/en/docs/cli/link/).

docs/babel.config.ts.js

@@ -0,0 +1,24 @@
+const path = require('path');
+const ignoredDemos = require('./ts-demo-ignore.json');
+
+/**
+ * babel config to transpile tsx demos to js
+ *
+ * Can be used to spot differences between ts and js demos which might indicate that they
+ * do different things at runtime.
+ *
+ * Demos listed in ts-demo-ignore are not transpiled. Their path should be relative
+ * to `${workspaceRoot}/docs/src/pages/demos`.
+ */
+
+const workspaceRoot = path.join(__dirname, '../');
+const ignore = ignoredDemos.map(demoPath =>
+  path.join(workspaceRoot, 'docs/src/pages/demos', `${demoPath}.tsx`),
+);
+
+module.exports = {
+  presets: ['@babel/preset-typescript'],
+  plugins: ['unwrap-createStyles'],
+  ignore,
+  generatorOpts: { retainLines: true },
+};

docs/scripts/formattedTSDemos.js

@@ -0,0 +1,55 @@
+/**
+ * Transpiles and formats TS demos.
+ * Can be used to verify that JS and TS demos are equivalent. No introduced change
+ * would indicate equivalence.
+ */
+const childProcess = require('child_process');
+const fse = require('fs-extra');
+const path = require('path');
+const prettier = require('prettier');
+const util = require('util');
+
+const exec = util.promisify(childProcess.exec);
+
+async function getUnstagedGitFiles() {
+  const { stdout } = await exec('git diff --name-only');
+  const list = stdout.trim();
+
+  if (list === '') {
+    // "".split(" ") => [""]
+    return [];
+  }
+
+  return list.split('\n');
+}
+
+function fixBabelGeneratorIssues(source) {
+  return source.replace(/,\n\n/g, ',\n');
+}
+
+exec('yarn docs:typescript')
+  .then(() => {
+    const prettierConfigPath = path.join(__dirname, '../../prettier.config.js');
+    const prettierConfig = prettier.resolveConfig(process.cwd(), { config: prettierConfigPath });
+
+    return Promise.all([getUnstagedGitFiles(), prettierConfig]);
+  })
+  .then(([changedDemos, prettierConfig]) =>
+    Promise.all(
+      changedDemos.map(filename => {
+        const filepath = path.join(process.cwd(), filename);
+
+        return fse.readFile(filepath).then(source => {
+          const prettified = prettier.format(source.toString(), { ...prettierConfig, filepath });
+          const formatted = fixBabelGeneratorIssues(prettified);
+
+          return fse.writeFile(filepath, formatted);
+        });
+      }),
+    ),
+  )
+  .catch(err => {
+    // eslint-disable-next-line no-console
+    console.error(err);
+    process.exit(1);
+  });