Expand documentation

* Add more information about styling CSS classes and transitions
* Add section on accessibility, including app element details (addresses reactjs#576)
* Create missing `examples/README.md` and `contributing/README.md`
* Reorganize initial book section (with subsection labels)

docs/README.md

@@ -4,7 +4,7 @@
 
 We maintain that accessibility is a key component of any modern web application.  As such, we have created this modal in such a way that it fulfills the accessibility requirements of the modern web.  We seek to keep the focus on accessibility while providing a functional, capable modal component for general use.
 
-## Installation
+## Installation {#installation}
 
 To install the stable version you can use [npm](https://npmjs.org/) or [yarn](https://yarnpkg.com):
 
@@ -13,7 +13,7 @@ To install the stable version you can use [npm](https://npmjs.org/) or [yarn](ht
     $ yarn add react-modal
 
 
-## General Usage
+## General Usage {#usage}
 
 The following is an example of using react-modal specifying all the possible props and options:
 
@@ -88,7 +88,7 @@ import ReactModal from 'react-modal';
     Boolean indicating if the modal should restore focus to the element that
     had focus prior to its display.
   */
-  shouldReturnFocusAfterClose={true}  
+  shouldReturnFocusAfterClose={true}
   /*
     String indicating the role of the modal, allowing the 'dialog' role to be applied if desired.
   */
@@ -104,17 +104,17 @@ import ReactModal from 'react-modal';
     labelledby: "heading",
     describedby: "full_description"
   }}
-  /* 
+  /*
     Overlay ref callback.
   */
   overlayRef={setOverlayRef}
-  /* 
+  /*
     Content ref callback.
   */
   contentRef={setContentRef}
 />
 ```
 
-## License
+## License {#license}
 
 MIT

docs/SUMMARY.md

@@ -1,12 +1,18 @@
 # Summary
 
-* [Read Me](/README.md)
+* [Overview](/README.md)
+  * [Installation](/README.md#installation)
+  * [Usage](/README.md#usage)
+  * [License](/README.md#license)
 
-* [Development](dev/README.md)
+* [Accessibility](accessibility/README.md)
+  * [The app element](accessibility/README.md#app-element)
+  * [Keyboard navigation](accessibility/README.md#keyboard)
+  * [Custom ARIA attributes](accessibility/README.md#aria)
 
 * [Styles](styles/README.md)
   * [Using CSS Classes](styles/classes.md)
-  * [Overriding Defaults](styles/defaults.md)
+  * [Transitions](styles/transitions.md)
 
 * [Testing](testing/README.md)
 
@@ -20,3 +26,4 @@
   * [Using Global Style Overrides](examples/global_overrides.md)
 
 * [Contributing](contributing/README.md)
+  * [Development setup](contributing/development.md)

docs/accessibility/README.md

@@ -0,0 +1,66 @@
+## Accessibility
+
+react-modal aims to be fully accessible, using the
+[WAI-ARIA](https://www.w3.org/WAI/intro/aria) guidelines to support users of
+assistive technologies.  This page describes some of react-modal's
+accessibility-oriented features, along with their configuration options.
+
+### The app element {#app-element}
+
+It is important for users of screenreaders that other page content be hidden
+(via the `aria-hidden` attribute) while the modal is open.  To allow
+react-modal to do this, you should call `Modal.setAppElement` with a query
+selector identifying the root of your app.  For example, if your app content is
+located inside an element with the ID `root`, you could place the following
+call somewhere in your code before any modals are opened:
+
+```js
+Modal.setAppElement('#root');
+```
+
+You can also pass a DOM element directly, so that the above example could be
+rewritten:
+
+```js
+Modal.setAppElement(document.getElementById('root'));
+```
+
+If you are already applying the `aria-hidden` attribute to your app content
+through other means, you can pass the `ariaHideApp={false}` prop to your modal
+to avoid getting a warning that your app element is not specified.
+
+### Keyboard navigation {#keyboard}
+
+When the modal is opened, it restricts keyboard navigation using the tab key to
+elements within the modal content.  This ensures that elements outside the
+modal (which are not visible while the modal is open) do not receive focus
+unexpectedly.
+
+By default, when the modal is closed, focus will be restored to the element
+that was focused before the modal was opened.  To disable this behavior, you
+can pass the `shouldReturnFocusAfterClose={false}` prop to your modal.
+
+The modal can be closed using the escape key, unless the
+`shouldCloseOnEsc={false}` prop is passed.  Disabling this behavior may cause
+accessibility issues for keyboard users, however, so it is not recommended.
+
+### Custom ARIA attributes {#aria}
+
+To pass custom ARIA attributes to your modal, you can use the `aria` prop,
+which accepts an object whose keys are the attributes you want to set (without
+the leading `aria-` prefix).  For example, you could have an alert modal with a
+title as well as a longer description:
+
+```jsx
+<Modal
+  isOpen={modalIsOpen}
+  aria={{
+    labelledby: "heading",
+    describedby: "full_description"
+  }}>
+  <h1 id="heading">Alert</h1>
+  <div id="full_description">
+    <p>Description goes here.</p>
+  </div>
+</Modal>
+```

docs/contributing/README.md

@@ -0,0 +1,42 @@
+## Contributing
+
+### Commit Subjects
+
+If your patch **changes the API or fixes a bug** please use one of the
+following prefixes in your commit subject:
+
+- `[fixed] ...`
+- `[changed] ...`
+- `[added] ...`
+- `[removed] ...`
+
+That ensures the subject line of your commit makes it into the
+auto-generated changelog. Do not use these tags if your change doesn't
+fix a bug and doesn't change the public API.
+
+Commits with changed, added, or removed, must be reviewed by another
+collaborator.
+
+#### When using `[changed]` or `[removed]`...
+
+Please include an upgrade path with example code in the commit message.
+If it doesn't make sense to do this, then it doesn't make sense to use
+`[changed]` or `[removed]` :)
+
+### Docs
+
+Please update the README with any API changes, the code and docs should
+always be in sync.
+
+### Development
+
+- `npm start` runs the dev server to run/develop examples
+- `npm test` will run the tests.
+- `scripts/test` same as `npm test` but keeps karma running and watches
+  for changes
+
+### Build
+
+Please do not include the output of `scripts/build` in your commits, we
+only do this when we release. (Also, you probably don't need to build
+anyway unless you are fixing something around our global build.)

docs/dev/README.md → docs/contributing/development.md

@@ -1,4 +1,4 @@
-# Development
+### Development setup
 
 `react-modal` uses `make` to build and publish new versions and documentation.
 
@@ -7,21 +7,21 @@ It works as a checklist for the future releases to keep everything updated such
 
 The minimun works as a normal `npm script`.
 
-## Usage
+#### Usage
 
 Once you clone `react-modal`, you can run `sh bootstrap.sh` to check
 and download dependencies not managed by `react-modal` such as `gitbook-cli`.
 
 It will also show information about the current versions of `node`, `npm`,
 `yarn` and `jq` available.
 
-## List of `npm` commands:
+#### List of `npm` commands:
 
     $ npm start -s or yarn start  # to run examples
     $ npm run tests
     $ npm run lint
 
-## List of `make` commands:
+#### List of `make` commands:
 
     $ make help           # show all make commands available
     $ make deps           # npm install, gitbook plugins...

docs/examples/README.md

@@ -0,0 +1,20 @@
+## Examples
+
+The following sub-sections contain several examples of basic usage, hosted on
+[CodePen](https://codepen.io).
+
+The `examples` directory in the project root also contains some examples which
+you can run locally.  To build and run those examples using a local development
+server, run either
+
+```
+$ npm start
+```
+
+or
+
+```
+$ yarn run start
+```
+
+and then point your browser to `localhost:8080`.

docs/styles/README.md

@@ -1,6 +1,8 @@
 ## Styles
 
-Styles passed into the Modal via the `style` prop are merged with the defaults.  The default styles are:
+Styles passed into the Modal via the `style` prop are merged with the defaults.
+The default styles are defined in the `Modal.defaultStyles` object and are
+shown below.
 
 ```jsx
 <Modal
@@ -32,3 +34,7 @@ Styles passed into the Modal via the `style` prop are merged with the defaults.
   ...
 >
 ```
+
+You can change the default styles by modifying `Modal.defaultStyles`.  Please
+note that specifying a [CSS class](classes.md) for the overlay or the content
+will disable the default styles for that component.

docs/styles/classes.md

@@ -1,22 +1,58 @@
 ### CSS Classes
 
 Sometimes it may be preferable to use CSS classes rather than inline styles.
+react-modal can be configured to use CSS classes to style the modal content and
+overlay, as well as the document body and the portal within which the modal is
+mounted.
 
-You can use the `className` and `overlayClassName` props to specify a given CSS
-class for each of those.
+#### For the content and overlay
+
+You can use the `className` and `overlayClassName` props to control the CSS
+classes that are applied to the modal content and the overlay, respectively.
+Each of these props may be a single string containing the class name to apply
+to the component.
+
+Alternatively, you may pass an object with the `base`, `afterOpen` and
+`beforeClose` keys, where the value corresponding to each key is a class name.
+The `base` class will always be applied to the component, the `afterOpen` class
+will be applied after the modal has been opened and the `beforeClose` class
+will be applied after the modal has requested to be closed (e.g. when the user
+presses the escape key or clicks on the overlay).
+
+Please note that the `beforeClose` class will have no effect unless the
+`closeTimeoutMS` prop is set to a non-zero value, since otherwise the modal
+will be closed immediately when requested.  Thus, if you are using the
+`afterOpen` and `beforeClose` classes to provide transitions, you may want to
+set `closeTimeoutMS` to the length (in milliseconds) of your closing
+transition.
+
+If you specify `className`, the [default content styles](README.md) will not be
+applied.  Likewise, if you specify `overlayClassName`, the default overlay
+styles will not be applied.
+
+If no class names are specified for the overlay, the default classes
+`ReactModal__Overlay`, `ReactModal__Overlay--after-open` and
+`ReactModal__Overlay--before-close` will be applied; the default classes for
+the content use the analogous prefix `ReactModal__Content`.  Please note that
+any styles applied using these default classes will not override the default
+styles as they would if specified using the `className` or `overlayClassName`
+props.
+
+#### For the document body
 
 You can override the default class that is added to `document.body` when the
 modal is open by defining a property `bodyOpenClassName`.
 
-It's required that `bodyOpenClassName` must be `constant string`, otherwise we
-would end up with a complex system to manage which class name should appear or
-be removed from `document.body` from which modal (if using multiple modals
+The `bodyOpenClassName` prop must be a *constant string*; otherwise, we would
+require a complex system to manage which class name should be added to or
+removed from `document.body` from which modal (if using multiple modals
 simultaneously).
 
 `bodyOpenClassName` can support adding multiple classes to `document.body` when
 the modal is open. Add as many class names as you desire, delineated by spaces.
 
-Note: If you provide those props all default styles will not be applied, leaving
-all styles under control of the CSS class.
+#### For the entire portal
 
-The `portalClassName` can also be used however there are no styles by default applied
+To specify a class to be applied to the entire portal, you may use the
+`portalClassName` prop.  By default, there are no styles applied to the portal
+itself.

docs/styles/transitions.md

@@ -0,0 +1,30 @@
+### Transitions
+
+Using [CSS classes](classes.md), it is possible to implement transitions for
+when the modal is opened or closed.  By placing the following CSS somewhere in
+your project's styles, you can make the modal content fade in when it is opened
+and fade out when it is closed:
+
+```css
+.ReactModal__Content {
+  opacity: 0;
+}
+
+.ReactModal__Content--after-open {
+  opacity: 1;
+  transition: opacity 150ms;
+}
+
+.ReactModal__Content--before-close {
+  opacity: 0;
+}
+```
+
+In order for the close transition to take effect, you will also need to pass
+the `closeTimeoutMS={150}` prop to each of your modals.
+
+The above example will apply the fade transition globally, affecting all modals
+whose `afterOpen` and `beforeClose` classes have not been set via the
+`className` prop.  To apply the transition to one modal only, you can change
+the above class names and pass an object to your modal's `className` prop as
+described in the [previous section](classes.md).