[Proposal] [Typescript] Generate Typescript definition files dynamically

Hi,

material-ui has become my favorite opensource project since early this year. The community is really active and responsive, thanking to all the contributors and members, especially @oliviertassinari for maintaining the repo and developing new features, and @pelotom for maintaining the Typescript definition files, and most importantly, it implements the Material Design so well.

Recently I’ve been taking a deep look at devextreme-reactive’s work on the material-ui grid, and they support Typescript projects by dynamically generating the .d.ts files. Those type definition files are generated with each release by parsing the .md files that define the types for all the components across the project. I think this approach is really appealing for two reasons.

1. It completely eliminates the need to proactively maintain the type definition files, except for occasional type fixes in the .md files.
2. Defining types in .md files will not only be beneficial for generating the type definition files, but it’s also great as a documentation because that’s what .md files are for. In the future, if we need to add new features or components, we just need to remember to also include them and their types correctly in the corresponding .md files, and boom, the type definition files will automatically be generated in the next release. One stone, two birds.

FYI - this is their .d.ts file generating script - https://github.com/DevExpress/devextreme-reactive/blob/master/scripts/ts-generator.js

I know this would be some work if we ever want to go on this path, because we need to write the .md file for each component and then write the script to parse them into .d.ts files, but it would definitely pay off.

[rosskevin]

This is the last progress update on prototyping typescript: https://github.com/mui-org/material-ui/pull/9561

• istanbul issue is now fixed
• nextjs issue is now fixed

I believe it to be possible now to accomplish the incremental switch.

There may be one or two issues with the way we stub/replace methods in testing, but otherwise the PR mentioned above is the right direction with babel 7. We need to use babel 7 for the optimizations for a bundled build, but we do not if we are going to just build/release ES modules.

Regardless, I worked out a lot of kinks in the build/test process that could be referenced easily from the old fork and applied to a new effort. I don’t a rebase will have any use, but eyeballing a merge against v1-beta might be interesting.

As you might expect - I am in support of moving to typescript.

[pelotom]

Hi @franklixuefei, thanks for the kind words. I confess I’m a little confused by this approach… to me it’s counterintuitive to start with a completely free text format like .md and then parse it to generate type files, rather than start with the well-constrained form of TypeScript files and generate .md documentation from them. We already had that technique working with the old Flow typings, and there exist similar tools to do it in TypeScript. I’m not sure what sort of types can be expressed in this .md DSL, but I feel confident that TypeScript types are best written in TypeScript itself. As far as stones and birds, it seems to me there are 3 birds:

1. Implementation code - currently written in .js files
2. Typings - currently written in .d.ts files
3. Documentation - currently generated from the Flow comments in .js files?

I believe we can kill all these birds with one stone: write the implementation in .ts, and generate docs for them using typedoc. @rosskevin made an attempt to achieve this convergence but it stalled at some point, maybe he can remind us of where that stands and what the difficulties are.