From 4c1e59014061fb963740bcb0e5624b9a6c0e9972 Mon Sep 17 00:00:00 2001 From: Ian Johnson Date: Sun, 18 Feb 2018 09:08:13 -0500 Subject: [PATCH] Expand documentation * Add more information about styling CSS classes and transitions * Add section on accessibility, including app element details (addresses #576) * Create missing `examples/README.md` and `contributing/README.md` * Reorganize initial book section (with subsection labels) --- docs/README.md | 12 ++-- docs/SUMMARY.md | 13 +++- docs/accessibility/README.md | 66 +++++++++++++++++++ docs/contributing/README.md | 42 ++++++++++++ .../README.md => contributing/development.md} | 8 +-- docs/examples/README.md | 20 ++++++ docs/styles/README.md | 8 ++- docs/styles/classes.md | 52 ++++++++++++--- docs/styles/defaults.md | 3 - docs/styles/transitions.md | 30 +++++++++ 10 files changed, 229 insertions(+), 25 deletions(-) create mode 100644 docs/accessibility/README.md create mode 100644 docs/contributing/README.md rename docs/{dev/README.md => contributing/development.md} (91%) create mode 100644 docs/examples/README.md delete mode 100644 docs/styles/defaults.md create mode 100644 docs/styles/transitions.md diff --git a/docs/README.md b/docs/README.md index e474eb2f..49bb3f6a 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 1ed99909..9b68fbe1 100644 --- a/docs/SUMMARY.md +++ b/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) diff --git a/docs/accessibility/README.md b/docs/accessibility/README.md new file mode 100644 index 00000000..dd5d8321 --- /dev/null +++ b/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 + +

Alert

+
+

Description goes here.

+
+ +``` diff --git a/docs/contributing/README.md b/docs/contributing/README.md new file mode 100644 index 00000000..e14949ac --- /dev/null +++ b/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.) diff --git a/docs/dev/README.md b/docs/contributing/development.md similarity index 91% rename from docs/dev/README.md rename to docs/contributing/development.md index cd22decd..bedf4e5b 100644 --- a/docs/dev/README.md +++ b/docs/contributing/development.md @@ -1,4 +1,4 @@ -# Development +### Development setup `react-modal` uses `make` to build and publish new versions and documentation. @@ -7,7 +7,7 @@ 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`. @@ -15,13 +15,13 @@ 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... diff --git a/docs/examples/README.md b/docs/examples/README.md new file mode 100644 index 00000000..b0313c09 --- /dev/null +++ b/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`. diff --git a/docs/styles/README.md b/docs/styles/README.md index 3a6cd3db..02464875 100644 --- a/docs/styles/README.md +++ b/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 ``` + +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. diff --git a/docs/styles/classes.md b/docs/styles/classes.md index 43214245..3ec161c0 100644 --- a/docs/styles/classes.md +++ b/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. diff --git a/docs/styles/defaults.md b/docs/styles/defaults.md deleted file mode 100644 index 2bdf9903..00000000 --- a/docs/styles/defaults.md +++ /dev/null @@ -1,3 +0,0 @@ -### Global Overrides - -If you'd like to override all instances of modals you can make changes to `Modal.defaultStyles`. diff --git a/docs/styles/transitions.md b/docs/styles/transitions.md new file mode 100644 index 00000000..790bb4a9 --- /dev/null +++ b/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).