rebase

docs/scripts/buildApi.js

@@ -1,14 +1,18 @@
 /* eslint-disable no-console */
+import * as babel from '@babel/core';
+import traverse from '@babel/traverse';
 import { mkdir, readFileSync, writeFileSync } from 'fs';
 import { getLineFeed } from './helpers';
 import path from 'path';
 import kebabCase from 'lodash/kebabCase';
+import uniqBy from 'lodash/uniqBy';
 import { defaultHandlers, parse as docgenParse } from 'react-docgen';
 import muiDefaultPropsHandler from '../src/modules/utils/defaultPropsHandler';
 import generateMarkdown from '../src/modules/utils/generateMarkdown';
 import { findPagesMarkdown, findComponents } from '../src/modules/utils/find';
 import { getHeaders } from '../src/modules/utils/parseMarkdown';
 import parseTest from '../src/modules/utils/parseTest';
+import { pageToTitle } from '../src/modules/utils/helpers';
 import createMuiTheme from '../../packages/material-ui/src/styles/createMuiTheme';
 import getStylesCreator from '../../packages/material-ui-styles/src/getStylesCreator';
 import createGenerateClassName from '../../packages/material-ui-styles/src/createGenerateClassName';
@@ -80,6 +84,80 @@ function getInheritance(testInfo, src) {
   };
 }
 
+async function annotateComponentDefinition(component, api) {
+  const typesFilename = component.filename.replace(/\.js$/, '.d.ts');
+  const typesSource = readFileSync(typesFilename, { encoding: 'utf8' });
+  const typesAST = await babel.parseAsync(typesSource, {
+    configFile: false,
+    filename: typesFilename,
+    presets: [require.resolve('@babel/preset-typescript')],
+  });
+
+  let start = null;
+  let end = null;
+  traverse(typesAST, {
+    ExportDefaultDeclaration(babelPath) {
+      // export default function Menu() {}
+      let node = babelPath.node;
+      if (node.declaration.type === 'Identifier') {
+        // declare const Menu: {};
+        // export default Menu;
+        const bindingId = babelPath.node.declaration.name;
+        const binding = babelPath.scope.bindings[bindingId];
+        node = binding.path.parentPath.node;
+      }
+
+      const { leadingComments = [] } = node;
+      const [jsdocBlock, ...rest] = leadingComments;
+      if (rest.length > 0) {
+        throw new Error('Should only have a single leading jsdoc block');
+      }
+      if (jsdocBlock !== undefined) {
+        start = jsdocBlock.start;
+        end = jsdocBlock.end;
+      } else {
+        start = node.start - 1;
+        end = start;
+      }
+    },
+  });
+
+  if (end === null || start === 0) {
+    throw new TypeError(
+      "Don't know where to insert the jsdoc block. Probably no `default export` found",
+    );
+  }
+
+  const demos = api.pagesMarkdown.reduce((accumulator, page) => {
+    if (page.components.includes(api.name)) {
+      accumulator.push(page);
+    }
+
+    return accumulator;
+  }, []);
+
+  const jsdoc = `/**
+ * ${api.description}
+ *
+ * Demos:
+ * - ${uniqBy(demos, page => page.pathname)
+   .map(page => `{@link https://material-ui.com${page.pathname} ${pageToTitle(page)}}`)
+   .join('\n * - ')}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/${api.name} ${api.name} API}
+ * ${
+   api.inheritance !== null
+     ? `- inherits {@link https://material-ui.com/api/${api.inheritance.pathname} ${
+         api.inheritance.component
+       } API}`
+     : ''
+ }
+ */`;
+  const typesSourceNew = typesSource.slice(0, start) + jsdoc + typesSource.slice(end);
+  writeFileSync(typesFilename, typesSourceNew, { encoding: 'utf8' });
+}
+
 async function buildDocs(options) {
   const { component: componentObject, pagesMarkdown } = options;
   const src = readFileSync(componentObject.filename, 'utf8');
@@ -209,6 +287,8 @@ export default function Page() {
 
     console.log('Built markdown docs for', reactAPI.name);
   });
+
+  await annotateComponentDefinition(componentObject, reactAPI);
 }
 
 function run() {

packages/material-ui-lab/src/Alert/Alert.d.ts

@@ -69,5 +69,14 @@ export type AlertClassKey =
   | 'icon'
   | 'message'
   | 'action';
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/alert Alert}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/Alert Alert API}
+ * - inherits {@link https://material-ui.com/api//api/paper Paper API}
+ */
 export default function Alert(props: AlertProps): JSX.Element;

packages/material-ui-lab/src/AlertTitle/AlertTitle.d.ts

@@ -5,5 +5,14 @@ export interface AlertTitleProps
   extends StandardProps<React.HTMLAttributes<HTMLDivElement>, AlertTitleClassKey> {}
 
 export type AlertTitleClassKey = 'root';
-
+/**
+ * 
+ *
+ * Demos:
+ * - 
+ *
+ * API:
+ * - {@link https://material-ui.com/api/AlertTitle AlertTitle API}
+ * 
+ */
 export default function AlertTitle(props: AlertTitleProps): JSX.Element;

packages/material-ui-lab/src/Autocomplete/Autocomplete.d.ts

@@ -183,7 +183,16 @@ export type AutocompleteClassKey =
   | 'option'
   | 'groupLabel'
   | 'groupUl';
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/autocomplete Autocomplete}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/Autocomplete Autocomplete API}
+ * 
+ */
 export default function Autocomplete<T>(
   props: AutocompleteProps<T> & UseAutocompleteProps<T>,
 ): JSX.Element;

packages/material-ui-lab/src/AvatarGroup/AvatarGroup.d.ts

@@ -18,5 +18,14 @@ export interface AvatarGroupProps
 }
 
 export type AvatarGroupClassKey = 'root' | 'avatar';
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/avatars Avatars}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/AvatarGroup AvatarGroup API}
+ * 
+ */
 export default function AvatarGroup(props: AvatarGroupProps): JSX.Element;

packages/material-ui-lab/src/Pagination/Pagination.d.ts

@@ -46,5 +46,14 @@ export interface PaginationProps
 }
 
 export type PaginationClassKey = 'root' | 'ul';
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/pagination Pagination}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/Pagination Pagination API}
+ * 
+ */
 export default function Pagination(props: PaginationProps): JSX.Element;

packages/material-ui-lab/src/PaginationItem/PaginationItem.d.ts

@@ -40,7 +40,16 @@ export interface PaginationItemTypeMap<P = {}, D extends React.ElementType = 'di
   defaultComponent: D;
   classKey: PaginationItemClassKey;
 }
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/pagination Pagination}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/PaginationItem PaginationItem API}
+ * 
+ */
 declare const PaginationItem: OverridableComponent<PaginationItemTypeMap>;
 
 export type PaginationItemClassKey =

packages/material-ui-lab/src/Rating/Rating.d.ts

@@ -40,7 +40,16 @@ export type RatingClassKey =
   | 'iconFocus'
   | 'iconActive'
   | 'decimal';
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/rating Rating}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/Rating Rating API}
+ * 
+ */
 declare const Rating: React.ComponentType<RatingProps>;
 
 export default Rating;

packages/material-ui-lab/src/Skeleton/Skeleton.d.ts

@@ -11,7 +11,16 @@ export interface SkeletonTypeMap<P = {}, D extends React.ElementType = 'span'> {
   defaultComponent: 'div';
   classKey: SkeletonClassKey;
 }
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/skeleton Skeleton}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/Skeleton Skeleton API}
+ * 
+ */
 declare const Skeleton: OverridableComponent<SkeletonTypeMap>;
 
 export type SkeletonClassKey = 'root' | 'text' | 'rect' | 'circle' | 'pulse' | 'wave';

packages/material-ui-lab/src/SpeedDial/SpeedDial.d.ts

@@ -86,5 +86,14 @@ export type SpeedDialClassKey =
   | 'directionRight'
   | 'actions'
   | 'actionsClosed';
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/speed-dial Speed Dial}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/SpeedDial SpeedDial API}
+ * 
+ */
 export default function SpeedDial(props: SpeedDialProps): JSX.Element;

packages/material-ui-lab/src/SpeedDialAction/SpeedDialAction.d.ts

@@ -42,5 +42,14 @@ export type SpeedDialActionClassKey =
   | 'staticTooltipClosed'
   | 'staticTooltipLabel'
   | 'tooltipPlacementLeft';
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/speed-dial Speed Dial}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/SpeedDialAction SpeedDialAction API}
+ * - inherits {@link https://material-ui.com/api//api/tooltip Tooltip API}
+ */
 export default function SpeedDialAction(props: SpeedDialActionProps): JSX.Element;

packages/material-ui-lab/src/SpeedDialIcon/SpeedDialIcon.d.ts

@@ -25,5 +25,14 @@ export type SpeedDialIconClassKey =
   | 'iconWithOpenIconOpen'
   | 'openIcon'
   | 'openIconOpen';
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/speed-dial Speed Dial}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/SpeedDialIcon SpeedDialIcon API}
+ * 
+ */
 export default function SpeedDialIcon(props: SpeedDialIconProps): JSX.Element;

packages/material-ui-lab/src/ToggleButton/ToggleButton.d.ts

@@ -18,7 +18,16 @@ export type ToggleButtonTypeMap<
   defaultComponent: D;
   classKey: ToggleButtonClassKey;
 }>;
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/toggle-button Toggle Button}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/ToggleButton ToggleButton API}
+ * - inherits {@link https://material-ui.com/api//api/button-base ButtonBase API}
+ */
 declare const ToggleButton: ExtendButtonBase<ToggleButtonTypeMap>;
 
 export type ToggleButtonProps<

packages/material-ui-lab/src/ToggleButtonGroup/ToggleButtonGroup.d.ts

@@ -41,5 +41,14 @@ export type ToggleButtonGroupClassKey =
   | 'grouped'
   | 'groupedSizeSmall'
   | 'groupedSizeLarge';
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/toggle-button Toggle Button}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/ToggleButtonGroup ToggleButtonGroup API}
+ * 
+ */
 export default function ToggleButtonGroup(props: ToggleButtonGroupProps): JSX.Element;

packages/material-ui-lab/src/TreeItem/TreeItem.d.ts

@@ -47,5 +47,14 @@ export type TreeItemClassKey =
   | 'content'
   | 'iconContainer'
   | 'label';
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/tree-view Tree View}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/TreeItem TreeItem API}
+ * 
+ */
 export default function TreeItem(props: TreeItemProps): JSX.Element;

packages/material-ui-lab/src/TreeView/TreeView.d.ts

@@ -95,5 +95,14 @@ export interface SingleSelectTreeViewProps extends TreeViewPropsBase {
 export type TreeViewProps = SingleSelectTreeViewProps | MultiSelectTreeViewProps;
 
 export type TreeViewClassKey = 'root';
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/tree-view Tree View}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/TreeView TreeView API}
+ * 
+ */
 export default function TreeView(props: TreeViewProps): JSX.Element;

packages/material-ui/src/AppBar/AppBar.d.ts

@@ -24,5 +24,14 @@ export type AppBarClassKey =
   | 'colorDefault'
   | 'colorPrimary'
   | 'colorSecondary';
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/app-bar App Bar}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/AppBar AppBar API}
+ * - inherits {@link https://material-ui.com/api//api/paper Paper API}
+ */
 export default function AppBar(props: AppBarProps): JSX.Element;

packages/material-ui/src/Avatar/Avatar.d.ts

@@ -13,7 +13,16 @@ export interface AvatarTypeMap<P = {}, D extends React.ElementType = 'div'> {
   defaultComponent: D;
   classKey: AvatarClassKey;
 }
-
+/**
+ * 
+ *
+ * Demos:
+ * - {@link https://material-ui.com/components/avatars Avatars}
+ *
+ * API:
+ * - {@link https://material-ui.com/api/Avatar Avatar API}
+ * 
+ */
 declare const Avatar: OverridableComponent<AvatarTypeMap>;
 
 export type AvatarClassKey =