[Modal] Expose the component to the public API (#9038)

package.json

@@ -151,7 +151,7 @@
     "nprogress": "^0.2.0",
     "nyc": "^11.3.0",
     "phantomjs-prebuilt": "^2.1.16",
-    "prettier": "^1.8.0",
+    "prettier": "^1.8.1",
     "prismjs": "^1.8.4",
     "random-words": "0.0.1",
     "raw-loader": "^0.5.1",
@@ -162,16 +162,16 @@
     "react-dom": "^16.0.0",
     "react-number-format": "^3.0.1",
     "react-redux": "^5.0.6",
-    "react-swipeable-views": "^0.12.9",
+    "react-swipeable-views": "^0.12.10",
     "react-test-renderer": "^16.0.0",
     "react-text-mask": "^5.0.2",
     "recast": "^0.12.8",
     "recursive-readdir-sync": "^1.0.6",
     "redux": "^3.7.2",
     "redux-logger": "^3.0.6",
     "rimraf": "^2.6.2",
-    "sinon": "^4.1.1",
-    "size-limit": "^0.12.1",
+    "sinon": "^4.1.2",
+    "size-limit": "^0.13.1",
     "typescript": "2.5.3",
     "url-loader": "^0.6.2",
     "vrtest": "^0.2.0",

pages/api/dialog.md

@@ -54,6 +54,10 @@ If using the `overrides` key of the theme as documented
 [here](/customization/themes#customizing-all-instances-of-a-component-type),
 you need to use the following style sheet name: `MuiDialog`.
 
+## Inheritance
+
+The properties of the [<Modal />](/api/modal) component are also available.
+
 ## Demos
 
 - [Dialogs](/demos/dialogs)

pages/api/drawer.md

@@ -50,6 +50,10 @@ If using the `overrides` key of the theme as documented
 [here](/customization/themes#customizing-all-instances-of-a-component-type),
 you need to use the following style sheet name: `MuiDrawer`.
 
+## Inheritance
+
+The properties of the [<Modal />](/api/modal) component are also available.
+
 ## Demos
 
 - [Drawers](/demos/drawers)

pages/api/modal.js

@@ -0,0 +1,12 @@
+// @flow
+
+import React from 'react';
+import withRoot from 'docs/src/modules/components/withRoot';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import markdown from './modal.md';
+
+function Page() {
+  return <MarkdownDocs markdown={markdown} />;
+}
+
+export default withRoot(Page);

pages/api/modal.md

@@ -0,0 +1,64 @@
+---
+filename: /src/Modal/Modal.js
+---
+
+<!--- This documentation is automatically generated, do not try to edit it. -->
+
+# Modal
+
+The modal component provides a solid foundation for creating dialogs,
+popovers, or whatever else.
+The component renders its `children` node in front of a backdrop component.
+
+The `Modal` offers a few helpful features over using just a `Portal` component and some styles:
+- Manages dialog stacking when one-at-a-time just isn't enough.
+- Creates a backdrop, for disabling interaction below the modal.
+- It properly manages focus; moving to the modal content,
+  and keeping it there until the modal is closed.
+- It disables scrolling of the page content while open.
+- Adds the appropriate ARIA roles are automatically.
+
+This component shares many concepts with [react-overlays](https://react-bootstrap.github.io/react-overlays/#modals).
+
+## Props
+
+| Name | Type | Default | Description |
+|:-----|:-----|:--------|:------------|
+| BackdropClassName | string |  | The CSS class name of the backdrop element. |
+| BackdropComponent | ElementType | Backdrop | Pass a component class to use as the backdrop. |
+| BackdropInvisible | boolean | false | If `true`, the backdrop is invisible. |
+| BackdropTransitionDuration | TransitionDuration | 300 | The duration for the backdrop transition, in milliseconds. You may specify a single timeout for all transitions, or individually with an object. |
+| children | Element |  | A single child content element. |
+| classes | Object |  | Useful to extend the style applied to components. |
+| disableBackdrop | boolean | false | If `true`, the backdrop is disabled. |
+| ignoreBackdropClick | boolean | false | If `true`, clicking the backdrop will not fire the `onRequestClose` callback. |
+| ignoreEscapeKeyUp | boolean | false | If `true`, hitting escape will not fire the `onRequestClose` callback. |
+| keepMounted | boolean | false | Always keep the children in the DOM. This property can be useful in SEO situation or when you want to maximize the responsiveness of the Modal. |
+| onBackdropClick | Function |  | Callback fires when the backdrop is clicked on. |
+| onEnter | TransitionCallback |  | Callback fired before the modal is entering. |
+| onEntered | TransitionCallback |  | Callback fired when the modal has entered. |
+| onEntering | TransitionCallback |  | Callback fired when the modal is entering. |
+| onEscapeKeyUp | Function |  | Callback fires when the escape key is pressed and the modal is in focus. |
+| onExit | TransitionCallback |  | Callback fired before the modal is exiting. |
+| onExited | TransitionCallback |  | Callback fired when the modal has exited. |
+| onExiting | TransitionCallback |  | Callback fired when the modal is exiting. |
+| onRequestClose | Function |  | Callback fired when the component requests to be closed.<br><br>**Signature:**<br>`function(event: object) => void`<br>*event:* The event source of the callback |
+| <span style="color: #31a148">show *</span> | boolean |  | If `true`, the Modal is visible. |
+
+Any other properties supplied will be [spread to the root element](/customization/api#spread).
+
+## CSS API
+
+You can override all the class names injected by Material-UI thanks to the `classes` property.
+This property accepts the following keys:
+- `root`
+- `hidden`
+
+Have a look at [overriding with classes](/customization/overrides#overriding-with-classes) section
+and the [implementation of the component](https://github.com/callemall/material-ui/tree/v1-beta/src/Modal/Modal.js)
+for more detail.
+
+If using the `overrides` key of the theme as documented
+[here](/customization/themes#customizing-all-instances-of-a-component-type),
+you need to use the following style sheet name: `MuiModal`.
+

pages/api/popover.md

@@ -15,7 +15,7 @@ filename: /src/Popover/Popover.js
 | PaperProps | Object |  | Properties applied to the `Paper` element. |
 | anchorEl | HTMLElement |  | This is the DOM element that may be used to set the position of the popover. |
 | anchorOrigin | signature | {  vertical: 'top',  horizontal: 'left',} | This is the point on the anchor where the popover's `anchorEl` will attach to. This is not used when the anchorReference is 'anchorPosition'.<br>Options: vertical: [top, center, bottom]; horizontal: [left, center, right]. |
-| anchorPosition | signature | {  top: 0,  left: 0,} | This is the position that may be used to set the position of the popover. The coordinates are relative to the application's client area. |
+| anchorPosition | signature |  | This is the position that may be used to set the position of the popover. The coordinates are relative to the application's client area. |
 | anchorReference | union:&nbsp;'anchorEl'&nbsp;&#124;<br>&nbsp;'anchorPosition'<br> | 'anchorEl' |  |
 | <span style="color: #31a148">children *</span> | Node |  | The content of the component. |
 | classes | Object |  | Useful to extend the style applied to components. |
@@ -50,6 +50,10 @@ If using the `overrides` key of the theme as documented
 [here](/customization/themes#customizing-all-instances-of-a-component-type),
 you need to use the following style sheet name: `MuiPopover`.
 
+## Inheritance
+
+The properties of the [&lt;Modal /&gt;](/api/modal) component are also available.
+
 ## Demos
 
 - [Popovers](/demos/popovers)

src/Dialog/Dialog.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { StandardProps } from '..';
-import { ModalProps, ModalClassKey } from '../internal/Modal';
+import { ModalProps, ModalClassKey } from '../Modal';
 import { TransitionDuration } from '../internal/transition';
 
 export interface DialogProps extends StandardProps<

src/Dialog/Dialog.js

@@ -1,11 +1,12 @@
 // @flow
+// @inheritedComponent Modal
 
 import React from 'react';
 import type { ComponentType, Node } from 'react';
 import classNames from 'classnames';
 import withStyles from '../styles/withStyles';
 import { capitalizeFirstLetter } from '../utils/helpers';
-import Modal from '../internal/Modal';
+import Modal from '../Modal';
 import Fade from '../transitions/Fade';
 import { duration } from '../styles/transitions';
 import Paper from '../Paper';

src/Drawer/Drawer.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { StandardProps } from '..';
-import { ModalProps, ModalClassKey } from '../internal/Modal';
+import { ModalProps, ModalClassKey } from '../Modal';
 import { TransitionDuration } from '../internal/transition';
 import { SlideProps } from '../transitions/Slide';
 import { Theme } from '../styles/createMuiTheme';

src/Drawer/Drawer.js

@@ -1,9 +1,10 @@
 // @flow
+// @inheritedComponent Modal
 
 import React from 'react';
 import type { Node } from 'react';
 import classNames from 'classnames';
-import Modal from '../internal/Modal';
+import Modal from '../Modal';
 import withStyles from '../styles/withStyles';
 import Slide from '../transitions/Slide';
 import Paper from '../Paper';

src/Drawer/Drawer.spec.js

@@ -5,7 +5,7 @@ import { assert } from 'chai';
 import { createShallow, getClasses } from '../test-utils';
 import Slide from '../transitions/Slide';
 import createMuiTheme from '../styles/createMuiTheme';
-import Modal from '../internal/Modal';
+import Modal from '../Modal';
 import Paper from '../Paper';
 import Drawer from './Drawer';
 

src/internal/Modal.d.ts → src/Modal/Modal.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { StandardProps } from '..';
 import { BackdropProps } from './Backdrop';
-import { TransitionDuration, TransitionHandlers } from './transition';
+import { TransitionDuration, TransitionHandlers } from '../internal/transition';
 
 export interface ModalProps extends StandardProps<
   React.HtmlHTMLAttributes<HTMLDivElement> & Partial<TransitionHandlers>,

src/internal/Modal.js → src/Modal/Modal.js

@@ -16,7 +16,7 @@ import Fade from '../transitions/Fade';
 import withStyles from '../styles/withStyles';
 import createModalManager from './modalManager';
 import Backdrop from './Backdrop';
-import Portal from './Portal';
+import Portal from '../internal/Portal';
 import type { TransitionDuration, TransitionCallback } from '../internal/transition';
 
 // Modals don't open on the server so this won't break concurrency.
@@ -42,7 +42,6 @@ type ProvidedProps = {
   BackdropComponent: ElementType,
   classes: Object,
   modalManager: Object,
-  show: boolean,
 };
 
 export type Props = {
@@ -138,15 +137,27 @@ export type Props = {
   /**
    * If `true`, the Modal is visible.
    */
-  show?: boolean,
+  show: boolean,
 };
 
 type State = {
   exited: boolean,
 };
 
 /**
- * @ignore - internal component.
+ * The modal component provides a solid foundation for creating dialogs,
+ * popovers, or whatever else.
+ * The component renders its `children` node in front of a backdrop component.
+ *
+ * The `Modal` offers a few helpful features over using just a `Portal` component and some styles:
+ * - Manages dialog stacking when one-at-a-time just isn't enough.
+ * - Creates a backdrop, for disabling interaction below the modal.
+ * - It properly manages focus; moving to the modal content,
+ *   and keeping it there until the modal is closed.
+ * - It disables scrolling of the page content while open.
+ * - Adds the appropriate ARIA roles are automatically.
+ *
+ * This component shares many concepts with [react-overlays](https://react-bootstrap.github.io/react-overlays/#modals).
  */
 class Modal extends React.Component<ProvidedProps & Props, State> {
   static defaultProps = {
@@ -158,7 +169,6 @@ class Modal extends React.Component<ProvidedProps & Props, State> {
     ignoreBackdropClick: false,
     ignoreEscapeKeyUp: false,
     modalManager,
-    show: false,
   };
 
   state = {

src/internal/Modal.spec.js → src/Modal/Modal.spec.js

@@ -21,7 +21,7 @@ describe('<Modal />', () => {
 
   before(() => {
     shallow = createShallow({ dive: true, disableLifecycleMethods: true });
-    classes = getClasses(<Modal />);
+    classes = getClasses(<Modal show={false} />);
     mount = createMount();
     mockPortal.init();
   });
@@ -33,7 +33,7 @@ describe('<Modal />', () => {
 
   it('should render null by default', () => {
     const wrapper = shallow(
-      <Modal>
+      <Modal show={false}>
         <p>Hello World</p>
       </Modal>,
     );
@@ -194,7 +194,7 @@ describe('<Modal />', () => {
 
       before(() => {
         wrapper = mount(
-          <Modal id="modal">
+          <Modal show={false} id="modal">
             <div id="container">
               <h1 id="heading">Hello</h1>
             </div>
@@ -336,7 +336,7 @@ describe('<Modal />', () => {
     let instance;
 
     before(() => {
-      wrapper = shallow(<Modal />);
+      wrapper = shallow(<Modal show={false} />);
       instance = wrapper.instance();
     });
 

src/Modal/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './Modal';
+export * from './Modal';

src/Modal/index.js

@@ -0,0 +1,3 @@
+// @flow
+
+export { default } from './Modal';

src/internal/modalManager.spec.js → src/Modal/modalManager.spec.js

@@ -4,7 +4,7 @@ import { assert } from 'chai';
 import getScrollbarSize from 'dom-helpers/util/scrollbarSize';
 import createModalManager from './modalManager';
 
-describe('internal/modalManager', () => {
+describe('modalManager', () => {
   let modalManager;
 
   before(() => {

src/Popover/Popover.d.ts

@@ -2,7 +2,7 @@ import * as React from 'react';
 import { StandardProps } from '..';
 import { PaperProps } from '../Paper';
 import { TransitionDuration, TransitionHandlers } from '../internal/transition';
-import { ModalProps, ModalClassKey } from '../internal/Modal';
+import { ModalProps, ModalClassKey } from '../Modal';
 
 export interface Origin {
   horizontal: 'left' | 'center' | 'right' | number;

src/Popover/Popover.js

@@ -1,4 +1,5 @@
 // @flow
+// @inheritedComponent Modal
 
 import React from 'react';
 import type { Node } from 'react';
@@ -8,7 +9,7 @@ import contains from 'dom-helpers/query/contains';
 import debounce from 'lodash/debounce';
 import EventListener from 'react-event-listener';
 import withStyles from '../styles/withStyles';
-import Modal from '../internal/Modal';
+import Modal from '../Modal';
 import type { TransitionCallback, TransitionClasses } from '../internal/transition';
 import Grow from '../transitions/Grow';
 import Paper from '../Paper';

src/index.d.ts

@@ -85,6 +85,7 @@ export {
   ListSubheader,
 } from './List';
 export { default as Menu, MenuItem, MenuList } from './Menu';
+export { default as Modal } from './Modal';
 export { default as Paper } from './Paper';
 export { default as Popover } from './Popover';
 export { CircularProgress, LinearProgress } from './Progress';

src/index.js

@@ -36,6 +36,7 @@ export {
   ListSubheader,
 } from './List';
 export { default as Menu, MenuItem, MenuList } from './Menu';
+export { default as Modal } from './Modal';
 export { default as Paper } from './Paper';
 export { default as Popover } from './Popover';
 export { CircularProgress, LinearProgress } from './Progress';