[docs] AppBar and Textfield demos in TypeScript (mui#13229)

* Squashed commit of the following: commit 2035e6daa1ceba1c78d3e8740af8d5f3066bc898 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Mon Nov 5 10:16:31 2018 +0100 [docs] Fix undefined raw js commit 9ab3761e49d8682530543f1e6808d46cd955f32a Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Mon Nov 5 10:07:38 2018 +0100 [docs] Enable textfield ts demos commit 8271f5cff4b3f6fe31b564a3f98ed69d8c09f3d6 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 30 11:58:29 2018 +0100 [docs] Port mui#13428 to typescript commit 8b808886235a3690b01335a5d3a6132209b87483 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Fri Oct 26 17:55:02 2018 +0200 [docs] Add typescript demos for TextField Takeaway: - inputProps, inputComponent is badly typed (needs generics though) - computed property keys support is bad in typescript commit 5ab9c988d259cd039e5b2735a47c1c89c9761eec Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 23 13:36:56 2018 +0200 [docs] Use esModuleInterop import conistently commit c9bca0824c0f81fe114f8976bc10464de94306b2 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 23 13:35:32 2018 +0200 [docs] Fix IE 11 compat issues commit b4dd772ee990dd0f9a042a8721aa7a665ded7fce Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 23 13:33:44 2018 +0200 [docs] Remove dead code commit f0a23cffb7a8e2c4faf5c2b4182919efb74d4bdd Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 23 08:21:07 2018 +0200 [ci] Fix job order Running git diff after yarn build will exit with 1 because the size snapshot was updated. commit 114022bd6d1ac98af330f6e7b57ba03062d120ff Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Mon Oct 22 21:32:54 2018 +0200 [docs] Disabled stackblitz for TS demos commit 7995d67cd09f08541f388124d535452054518d75 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Mon Oct 22 17:47:14 2018 +0200 [docs] Add guide about ts demos commit 0c65724f14c4de21ced8ce4e8ff91b2edce3b6d5 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Mon Oct 22 17:09:39 2018 +0200 [docs] Sync demo changes from 06967ec commit 7a0861d855d15bf281fde271e0028d0b1ba9dbb1 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Mon Oct 22 15:35:03 2018 +0200 [docs] Allow require default interop for ts demos Seems like codesandbox still has issues with this. Gonna investigate if we can fix this upstream commit c8a143e20735be14f692477fab40cd3d4a3040df Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Mon Oct 22 15:34:10 2018 +0200 [docs] Support types for scoped packages commit 48a425d19a53e77fa97692980e364f503491a91b Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Sat Oct 20 18:02:05 2018 +0200 [babel-plugin-unwrap-createStyles] Fix fixtures being transpiled with workspace config commit 03c1ac9d7575c9dc79e8253578dda60f39e33375 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Fri Oct 19 12:21:59 2018 +0200 [docs] Create ts specific codesandbox - needs babel plugin for synthetic default imports commit cdc393185a823bb684ff34be23f20d4897db8962 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Thu Oct 18 18:39:40 2018 +0200 [docs] Fire analytics event when clicking codeLanguage commit 6865f6488c27c1353cae108410d94a165343414b Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Thu Oct 18 18:15:05 2018 +0200 [docs] Add ts version for all app bar demos - Fixes menu not closing in PrimarySearchAppBar - removes some dead code from undefined classnames commit a189a173a371e785916b8797283798e45d4743d8 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Thu Oct 18 17:12:44 2018 +0200 [ci] Check compiled ts demos are equal to js demos commit 95706fdaaa1b6a56da239250b515a36459c87b8b Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Wed Oct 17 20:51:02 2018 +0200 [docs] Remove debug config commit a90c76a322104787837c1646fc400e84cdc77e6c Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Wed Oct 17 20:48:56 2018 +0200 [docs] github link and copy code depending on selected code language commit fafa284f397e66b0075a29823debc1c8dbd6b1fb Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Wed Oct 17 18:14:49 2018 +0200 [docs] Add feature flag for language switch Enabled on a per-component basis. commit 9ef68446d7e42347d30fc796d34f23f15eaf4405 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Wed Oct 17 18:10:20 2018 +0200 [docs] Add the ability to mark ts demos as outdated This should be used in-sync with ignored demos in transpilation. commit a7033f203278d6e462a016190790a3609aabded5 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Wed Oct 17 17:18:10 2018 +0200 [docs] Add the ability to ignore ts demos from transpilation This can be useful to defer syncing them upwards from js. commit e7c19cb1f264bf9ec9b6884650b4e3ad8e6942f8 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Wed Oct 17 16:22:36 2018 +0200 Fix formatting errors commit ea9a6de935394d0c61eff974a8575165ae0ed1aa Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Wed Oct 17 10:33:23 2018 +0200 [docs] Disable ts switch if not ts version is available commit 5a58595c26108e8ccd18eacf3b16ae2ed40de0a5 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Wed Oct 17 09:19:53 2018 +0200 [docs] Remove global code language switch Revisit this if we reach critical mass on ts docs commit aecb12fdf96aa761e543ba284d55ffd11a7970f1 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Wed Oct 17 09:15:52 2018 +0200 [docs] Improve code language switch commit 0a587ec8b0f97dfc05352856f7dec1c081e5275e Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 16 23:37:40 2018 +0200 Fix CI errors commit 82921d138f21272cef11c040ea7a578584563120 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 16 23:20:36 2018 +0200 [docs] Add local language switch and add language logos - color needs rework: it looks a little bit out of place, bad contrast commit 49861e54f5b5d2e54cac672c4f5a3377731e6255 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 16 20:45:25 2018 +0200 [docs] Language switch via redux It's pretty slow at the app level. While it is nice to have ts permanently enabled while browsing docs a switch at demo level might be better suited. commit 6a06a060ad17f44dab0d1cc49996455b37f8a2fc Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 16 19:14:55 2018 +0200 [docs] Another whitespace fix attempt commit fffed851504e587f2abadd6353318eaab9791fdb Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 16 18:46:46 2018 +0200 [docs] revert to function declaration propTypes in typescript are to strict commit ccb62823cbbacb5da109eb5275277a4ebf797533 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 16 18:32:38 2018 +0200 [core] Bump @types/react commit d3ac480d1966485b1c3d22672797110c26a82ef5 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 16 18:25:06 2018 +0200 [babel-plugin-unwrap-createStyles] Fix lint errors commit 1998640e939bfb57e27c265c2e338ef6707bae5a Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 16 18:21:45 2018 +0200 [docs] Remove diff in trailing whitespace commit 912c2a8d060ff3de9a70eaefa62c011f2bdbc90d Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 16 18:20:13 2018 +0200 [docs] Write formatted js from ts demos commit 4dcd51f50252823ee5f40dd9e53bfd6821786d5f Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 16 17:28:08 2018 +0200 [core] Sync tslint with eslint concerning trailing-whitespace commit 05f3f3d78e333ed740f447a2e20724cc1624c363 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 16 13:59:47 2018 +0200 [core] docuent babel-plugin vs. ts-transformer commit 691a036456486b4cea411d435392746ad714817d Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Tue Oct 16 11:03:08 2018 +0200 [docs] Add babel plugin to unwrap createStyles calls This essentially strips them from the bundle commit a02ffd64a1defb4298030fd2d162c4a71c65b09a Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Sat Oct 13 16:02:11 2018 +0200 Move ts files next to js files commit 32a301a8eb2d0ed5e3b902313d5895dabcfbca32 Author: Sebastian Silbermann <silbermann.sebastian@gmail.com> Date: Sat Oct 13 14:35:14 2018 +0200 Working example without type checking and bad folder structure * removed the babel-generator-prettier plugin See eps1lon#1 * removed the babel-generator-prettier plugin in favor of running prettier after building the docs * Restore yarn integrity fields * [core] use link protocol for babel-plugin-unwrap-createStyles * [babel-plugin-unwrap-createStyles] Improve code docs * [docs] Sync ts and js demos * [ci] Use proper docs:ts:check command * [docs] Improve TS demo workflow * [docs] Cleanup merge commit * [docs] Cleanup TS demo testing * [docs] Furhter merge commit cleanup * [docs} Fix codesandbox demos * [docs] remove unused lint directives * [docs] Add analytics event to source switches * [core] cleanup tslint diff * [babel-plugin-unwrapCreateStyles] Cleanup package.json * [docs] fix bundle size limit * remove blank line * remove blank lines * Update README.md * [docs] exit with non-zero if ts scripts fail * [docs] Fix failing TS script * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Revert "remove blank lines" Fixes build * [docs] Update Hooks / JS / TS icons, remove code icon * [docs] Format code * [docs] Port mui#14266 to TS * [docs] Port mui#14281 to TS * [docs] Port mui#14023 to TS * [docs] Adjust bundle size * WIP dropdown WIP ToggleButtons * Add a transition, highlight the correct toggle-button when preferred code style not available * Remove comment Tooltips * docs bundle size * [docs] Update contributing with updated formatting ts demo task * [docs] Remove commented code * [docs] Update outdated API docs * [docs] Remove unnecessary fragment * [docs] Replace string literals with enum values * [docs] Removed explicit property initialization
Cu50 · Jan 31, 2019 · 4422ce8 · 4422ce8
1 parent 5572b13
commit 4422ce8
Show file tree

Hide file tree

Showing 68 changed files with 3,506 additions and 232 deletions.
diff --git a/.circleci/config.yml b/.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

diff --git a/.eslintignore b/.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

diff --git a/.size-limit.js b/.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',

diff --git a/CONTRIBUTING.md b/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/).

diff --git a/docs/babel.config.ts.js b/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 },
+};
diff --git a/docs/scripts/formattedTSDemos.js b/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);
+  });