docs: Improvements to the documentation

README.md

@@ -21,7 +21,7 @@ Run the [example app](https://exp.host/@satya164/react-native-paper-example) wit
 Open a Terminal in your project's folder and run,
 
 ```sh
-npm install --save react-native-paper react-native-vector-icons
+yarn add react-native-paper react-native-vector-icons
 ```
 
 After installation, you'll need to link [react-native-vector-icons](https://github.com/oblador/react-native-vector-icons).

docs/pages/1.getting-started.md

@@ -8,15 +8,19 @@ permalink: getting-started
 Open a Terminal in your project's folder and run,
 
 ```sh
-npm install --save react-native-paper react-native-vector-icons
+yarn add react-native-paper
 ```
 
-After installation, you'll need to link [react-native-vector-icons](https://github.com/oblador/react-native-vector-icons).
+If you're on a vanilla React Native project, you also need to install and link [react-native-vector-icons](https://github.com/oblador/react-native-vector-icons). If you use CRNA or Expo, you don't need this step.
 
+```sh
+yarn add react-native-vector-icons
+react-native link react-native-vector-icons
+```
 
 ## Usage
 
-Wrap your root component in `Provider` from `react-native-paper`. It's a good idea to wrap the component which is passed to `AppRegistry.registerComponent`.
+Wrap your root component in `Provider` from `react-native-paper`. If you have a vanilla React Native project, it's a good idea to add it in the component which is passed to `AppRegistry.registerComponent`. This will usually be in the `index.js` file. If you have a CRNA or Expo project, you can do this inside the exported component in the `App.js` file.
 
 Example:
 
@@ -26,7 +30,7 @@ import { AppRegistry } from 'react-native';
 import { Provider as PaperProvider } from 'react-native-paper';
 import App from './src/App';
 
-function Main() {
+export default function Main() {
   return (
     <PaperProvider>
       <App />
@@ -39,6 +43,25 @@ AppRegistry.registerComponent('main', () => Main);
 
 The `PaperProvider` component provides the theme to all the components in the framework. It also acts as a portal to components which need to be rendered at the top level.
 
+If you have another provider (such as `Redux`), wrap it outside `PaperProvider` so that the context is available to components rendered inside a `Modal` from the library:
+
+```js
+import * as React from 'react';
+import { Provider as PaperProvider } from 'react-native-paper';
+import { Provider as StoreProvider } from 'redux';
+import App from './src/App';
+import store from './store';
+
+export default function Main() {
+  return (
+    <StoreProvider store={store}>
+      <PaperProvider>
+        <App />
+      </PaperProvider>
+    </StoreProvider>
+  );
+}
+```
 
 ## Customization
 
@@ -48,7 +71,6 @@ Example:
 
 ```js
 import * as React from 'react';
-import { AppRegistry } from 'react-native';
 import { DefaultTheme, Provider as PaperProvider } from 'react-native-paper';
 import color from 'color';
 import App from './src/App';
@@ -63,7 +85,7 @@ const theme = {
   },
 };
 
-function Main() {
+export default function Main() {
   return (
     <PaperProvider theme={theme}>
       <App />

docs/pages/2.theming.md

@@ -7,21 +7,31 @@ title: Theming
 To support custom themes, paper exports a `Provider` component. You need to wrap your root component with the provider to be able to support themes.
 
 ```js
+import * as React from 'react';
+import { Provider as PaperProvider } from 'react-native-paper';
+import App from './src/App';
+
 export default function Main() {
   return (
-    <Provider>
+    <PaperProvider>
       <App />
-    </Provider>
+    </PaperProvider>
   );
 }
 ```
 
-If no prop is specified, this will apply the [default theme](https://github.com/callstack/react-native-paper/blob/master/src/styles/DefaultTheme.js) to the components. You can also provide a `theme` prop with a theme object with same properties as the default theme. The theme will be merged into the default theme.
+If no prop is specified, this will apply the [default theme](https://github.com/callstack/react-native-paper/blob/master/src/styles/DefaultTheme.js) to the components. You can also provide a `theme` prop with a theme object with same properties as the default theme:
 
 ```js
+import * as React from 'react';
+import { DefaultTheme, Provider as PaperProvider } from 'react-native-paper';
+import App from './src/App';
+
 const theme = {
+  ...DefaultTheme,
   roundness: 2,
   colors: {
+    ...DefaultTheme.colors,
     primary: '#3498db',
     accent: '#f1c40f',
   }
@@ -29,9 +39,9 @@ const theme = {
 
 export default function Main() {
   return (
-    <Provider theme={theme}>
+    <PaperProvider theme={theme}>
       <App />
-    </Provider>
+    </PaperProvider>
   );
 }
 ```
@@ -43,6 +53,9 @@ You can change the theme prop dynamically and all the components will automatica
 If you want to change the theme for a certain component from the library, you can directly pass the `theme` prop to the component. The theme passed as the prop is merged with the theme from the `Provider`.
 
 ```js
+import * as React from 'react';
+import { Button } from 'react-native-paper';
+
 export default function ButtonExample() {
   return (
     <Button raised theme={{ roundness: 3 }}>
@@ -57,6 +70,9 @@ export default function ButtonExample() {
 To access the theme in your own components, you can use the `withTheme` HOC exported from the library. If you wrap your component with the HOC, you'll receive the theme as a prop.
 
 ```js
+import * as React from 'react';
+import { withTheme } from 'react-native-paper';
+
 function MyComponent(props) {
   const { colors } = props.theme;
   return <Text style={{ color: colors.primary }}>Yo!</Text>;

docs/pages/3.icons.md

@@ -0,0 +1,62 @@
+---
+title: Icons
+---
+
+## Configuring icons
+
+Many of the components require the [react-native-vector-icons](https://github.com/oblador/react-native-vector-icons) library to render correctly. If you're using CRNA or Expo, you don't need to do anything extra, but if it's vanilla React Native project, you need link the library as described in the getting started guide.
+
+## Using the `icon` prop
+
+Many components such as `Button` accept an `icon` prop which is used to display an icon. The `icon` prop supports the following type of values:
+
+### 1. An icon name
+
+You can pass the name of an icon from [`MaterialIcon`](https://material.io/icons/). This will use the [`react-native-vector-icons`](https://github.com/oblador/react-native-vector-icons) library to display the icon.
+
+Example:
+
+```js
+<Button icon="add-a-photo">
+  Press me
+</Button>
+```
+
+### 2. An image source
+
+You can pass an image source, such as an object of shape `{ uri: 'https://path.to' }` or a local image: `require('../path/to/image.png')` to use as an icon. The image might be rendered with a different color than the one provided depending on the component. If don't want this behavior, see the next example to pass an `Image` element.
+
+Remote image:
+
+```js
+<Button icon={{ uri: 'https://avatars0.githubusercontent.com/u/17571969?v=3&s=400' }}>
+  Press me
+</Button>
+```
+
+Local image:
+
+```js
+<Button icon={require('../assets/chameleon.jpg')}>
+  Press me
+</Button>
+```
+
+### 3. A React element
+
+You can pass any react element to be used an icon. The element is used as is without any modification. However, it might get clipped if the provided element's size are bigger than what the component renders. It's upto you to make sure that the size of the element is correct.
+
+Example:
+
+```js
+<Button
+  icon={
+    <Image
+     source={require('../assets/chameleon.jpg')}
+     style={{ width: 16, height: 16, borderRadius: 10 }}
+    />
+  }
+>
+  Press me
+</Button>
+```

example/src/ButtonExample.js

@@ -21,11 +21,6 @@ class ButtonExample extends React.Component<Props, State> {
   };
 
   render() {
-    const uri = {
-      // Callstack company avatar from github.
-      uri: 'https://avatars0.githubusercontent.com/u/17571969?v=3&s=400',
-    };
-    const source = require('../assets/chameleon.jpg');
     const { theme: { colors: { background } } } = this.props;
     return (
       <View style={[styles.container, { backgroundColor: background }]}>
@@ -74,16 +69,27 @@ class ButtonExample extends React.Component<Props, State> {
           </Button>
         </View>
         <View style={styles.row}>
-          <Button raised icon={uri} onPress={() => {}}>
+          <Button
+            raised
+            icon={{
+              uri:
+                'https://avatars0.githubusercontent.com/u/17571969?v=3&s=400',
+            }}
+            onPress={() => {}}
+          >
             Remote image
           </Button>
-          <Button raised icon={source} onPress={() => {}}>
+          <Button
+            raised
+            icon={require('../assets/chameleon.jpg')}
+            onPress={() => {}}
+          >
             Required asset
           </Button>
           <Button
             icon={
               <Image
-                source={source}
+                source={require('../assets/chameleon.jpg')}
                 style={{ width: 16, height: 16, borderRadius: 10 }}
               />
             }

example/src/Dialogs/DialogWithCustomColors.js

@@ -19,7 +19,7 @@ const DialogWithCustomColors = ({
   close: Function,
 }) => (
   <Dialog
-    onRequestClose={close}
+    onDismiss={close}
     style={{ backgroundColor: Colors.purple900 }}
     visible={visible}
   >

example/src/Dialogs/DialogWithLoadingIndicator.js

@@ -19,7 +19,7 @@ const DialogWithLoadingIndicator = ({
   visible: boolean,
   close: Function,
 }) => (
-  <Dialog onRequestClose={close} visible={visible}>
+  <Dialog onDismiss={close} visible={visible}>
     <DialogTitle>Progress Dialog</DialogTitle>
     <DialogContent>
       <View style={{ flexDirection: 'row', alignItems: 'center' }}>

example/src/Dialogs/DialogWithLongText.js

@@ -18,7 +18,7 @@ const DialogWithLongText = ({
   visible: boolean,
   close: Function,
 }) => (
-  <Dialog onRequestClose={close} visible={visible}>
+  <Dialog onDismiss={close} visible={visible}>
     <DialogTitle>Alert</DialogTitle>
     <DialogScrollArea style={{ maxHeight: 220, paddingHorizontal: 0 }}>
       <ScrollView contentContainerStyle={{ paddingHorizontal: 24 }}>

example/src/Dialogs/DialogWithRadioBtns.js

@@ -33,7 +33,7 @@ export default class extends React.Component<Props, State> {
     const { checked } = this.state;
     const { visible, close } = this.props;
     return (
-      <Dialog onRequestClose={close} visible={visible}>
+      <Dialog onDismiss={close} visible={visible}>
         <DialogTitle>Choose an option</DialogTitle>
         <DialogScrollArea style={{ maxHeight: 170, paddingHorizontal: 0 }}>
           <ScrollView contentContainerStyle={{ paddingHorizontal: 24 }}>

example/src/Dialogs/UndismissableDialog.js

@@ -18,7 +18,7 @@ const DialogWithLongText = ({
   visible: boolean,
   close: Function,
 }) => (
-  <Dialog onRequestClose={close} visible={visible} dismissable={false}>
+  <Dialog onDismiss={close} visible={visible} dismissable={false}>
     <DialogTitle>Alert</DialogTitle>
     <DialogContent>
       <Paragraph>This is an undismissable dialog!!</Paragraph>

scripts/validate-commit-message.js

@@ -15,7 +15,7 @@ const TYPES = {
   test: true,
   chore: true,
   revert: true,
-  breaking: true
+  BREAKING: true
 };
 
 function printError(...args) {

src/components/Button.js

@@ -16,7 +16,7 @@ const AnimatedPaper = Animated.createAnimatedComponent(Paper);
 
 type Props = {
   /**
-   * Disable the button.
+   * Whether the button is disabled. A disabled button is greyed out and `onPress` is not called on touch.
    */
   disabled?: boolean,
   /**
@@ -24,11 +24,11 @@ type Props = {
    */
   compact?: boolean,
   /**
-   * Add elevation to button, as opposed to default flat appearance.
+   * Add elevation to button, as opposed to default flat appearance. Typically used on a flat surface.
    */
   raised?: boolean,
   /**
-   * Use to primary color from theme.
+   * Use to primary color from theme. Typically used to emphasize an action.
    */
   primary?: boolean,
   /**
@@ -70,7 +70,7 @@ type State = {
 };
 
 /**
- * Buttons communicate the action that will occur when the user touches them.
+ * A button is component that the user can press to trigger an action.
  *
  * <div class="screenshots">
  *   <img src="screenshots/button-raised.png" />

src/components/Dialog/Dialog.js

@@ -21,7 +21,7 @@ type Props = {
   /**
    * Callback that is called when the user dismisses the dialog.
    */
-  onRequestClose: Function,
+  onDismiss: Function,
   /**
    * Determines Whether the dialog is visible.
    */
@@ -57,7 +57,7 @@ type Props = {
  *         <Button onPress={this._showDialog}>Show Dialog</Button>
  *         <Dialog
  *            visible={visible}
- *            onRequestClose={this._hideDialog}
+ *            onDismiss={this._hideDialog}
  *         >
  *           <DialogTitle>Alert</DialogTitle>
  *           <DialogContent>
@@ -83,7 +83,7 @@ class Dialog extends React.Component<Props, void> {
     const {
       children,
       dismissable,
-      onRequestClose,
+      onDismiss,
       visible,
       style,
       theme,
@@ -119,11 +119,7 @@ class Dialog extends React.Component<Props, void> {
       });
     }
     return (
-      <Modal
-        dismissable={dismissable}
-        onRequestClose={onRequestClose}
-        visible={visible}
-      >
+      <Modal dismissable={dismissable} onDismiss={onDismiss} visible={visible}>
         <AnimatedPaper style={[styles.container, { backgroundColor }, style]}>
           {title}
           {restOfChildrenWithoutTitle}

src/components/Dialog/DialogActions.js

@@ -27,7 +27,7 @@ type Props = {
  *     return (
  *       <Dialog
  *         visible={this.state.visible}
- *         onRequestClose={this._hideDialog}>
+ *         onDismiss={this._hideDialog}>
  *         <DialogActions>
  *           <Button onPress={() => console.log("Cancel"))}>Cancel</Button>
  *           <Button onPress={() => console.log("Ok")}>Ok</Button>

src/components/Dialog/DialogContent.js

@@ -27,7 +27,7 @@ type Props = {
  *     return (
  *       <Dialog
  *         visible={this.state.visible}
- *         onRequestClose={this._hideDialog}>
+ *         onDismiss={this._hideDialog}>
  *         <DialogContent>
  *           <Paragraph>This is simple dialog</Paragraph>
  *         </DialogContent>

src/components/Dialog/DialogScrollArea.js

@@ -12,7 +12,8 @@ type Props = {
 };
 
 /**
- * A component to show a scrollable content in a Dialog.
+ * A component to show a scrollable content in a Dialog. The component only provides appropriate styling.
+ * For the scrollable content you can use `ScrollView`, `FlatList` etc. depending on your requirement.
  *
  * ## Usage
  * ```js
@@ -27,7 +28,7 @@ type Props = {
  *     return (
  *       <Dialog
  *         visible={this.state.visible}
- *         onRequestClose={this._hideDialog}>
+ *         onDismiss={this._hideDialog}>
  *         <DialogScrollArea>
  *           <ScrollView contentContainerStyle={{ paddingHorizontal: 24 }}>
  *             This is a scrollable area

src/components/Dialog/DialogTitle.js

@@ -34,7 +34,7 @@ type Props = {
  *     return (
  *       <Dialog
  *         visible={this.state.visible}
- *         onRequestClose={this._hideDialog}>
+ *         onDismiss={this._hideDialog}>
  *         <DialogTitle>This is a title</DialogTitle>
  *         <DialogContent>
  *           <Paragraph>This is simple dialog</Paragraph>

src/components/Divider.js

@@ -20,7 +20,7 @@ type Props = {
 };
 
 /**
- * A divider is a thin, lightweight rule that groups content in lists and page layouts.
+ * A divider is a thin, lightweight separator that groups content in lists and page layouts.
  *
  * ## Usage
  * ```js
@@ -41,7 +41,7 @@ const Divider = (props: Props) => {
     <View
       {...props}
       style={[
-        isDarkTheme ? styles.dividerDarkTheme : styles.dividerDefaultTheme,
+        isDarkTheme ? styles.dark : styles.light,
         inset && styles.inset,
         style,
       ]}
@@ -50,14 +50,14 @@ const Divider = (props: Props) => {
 };
 
 const styles = StyleSheet.create({
-  dividerDefaultTheme: {
+  light: {
     backgroundColor: color(black)
       .alpha(0.12)
       .rgb()
       .string(),
     height: StyleSheet.hairlineWidth,
   },
-  dividerDarkTheme: {
+  dark: {
     backgroundColor: color(white)
       .alpha(0.12)
       .rgb()

src/components/DrawerItem.js

@@ -41,7 +41,7 @@ type Props = {
 };
 
 /**
- * Item from drawer's list which navigates to specific location.
+ * DrawerItem is a component used to show an action item with an icon and a label in a navigation drawer.
  *
  * ## Usage
  * ```js

src/components/DrawerSection.js

@@ -23,7 +23,7 @@ type Props = {
 };
 
 /**
- * Drawer container slides in from the left and contains the navigation destinations for your app.
+ * A DrawerSection groups content inside a navigation drawer.
  *
  * ## Usage
  * ```js
@@ -35,7 +35,7 @@ type Props = {
  *   render() {
  *     const { active } = this.state;
  *     return (
- *       <DrawerSection title="Subheader">
+ *       <DrawerSection title="Some title">
  *         <DrawerItem
  *           label="First Item"
  *           active={this.state.active === 'First Item'}

src/components/GridView.js

@@ -39,7 +39,7 @@ type State = {
 };
 
 /**
- * Grid lists are an alternative to standard list views.
+ * A GridView can display items in a grid as opposed to the columnar layout of the ListView.
  *
  * ## Usage
  * ```js

src/components/Icon.js

@@ -30,6 +30,7 @@ const Icon = ({ name, ...props }: Props) => {
           {
             width: props.size,
             height: props.size,
+            tintColor: props.color,
           },
           props.style,
         ]}

src/components/Modal.js

@@ -19,7 +19,7 @@ type Props = {
   /**
    * Callback that is called when the user dismisses the modal.
    */
-  onRequestClose: Function,
+  onDismiss: Function,
   /**
    * Determines Whether the modal is visible.
    */
@@ -119,8 +119,8 @@ export default class Modal extends React.Component<Props, State> {
       duration: 280,
       easing: Easing.ease,
     }).start(() => {
-      if (this.props.visible && this.props.onRequestClose) {
-        this.props.onRequestClose();
+      if (this.props.visible && this.props.onDismiss) {
+        this.props.onDismiss();
       }
       if (this.props.visible) {
         this._showModal();

src/components/ProgressBar.js

@@ -33,7 +33,7 @@ const ProgressBarComponent = Platform.select({
 });
 
 /**
- * Progress bar is an indicator used to present some activity in the app.
+ * Progress bar is an indicator used to present progress of some activity in the app.
  *
  * <div class="screenshots">
  *   <img src="screenshots/progress-bar.png" />

src/components/RadioButton.ios.js

@@ -32,7 +32,7 @@ type Props = {
 };
 
 /**
- * Radio buttons allow the selection of multiple options from a set
+ * Radio buttons allow the selection a single option from a set
  */
 class RadioButton extends React.Component<Props> {
   render() {

src/components/RadioButton.js

@@ -38,7 +38,7 @@ type State = {
 const BORDER_WIDTH = 2;
 
 /**
- * Radio buttons allow the selection of a single option from a set.
+ * Radio buttons allow the selection a single option from a set
  *
  * ## Usage
  * ```js

src/components/Switch.js

@@ -32,7 +32,7 @@ type Props = {
 };
 
 /**
- * Switch is a visual toggle between two mutually exclusive states—on and off.
+ * Switch is a visual toggle between two mutually exclusive states — on and off.
  *
  * <div class="screenshots">
  *   <div>

src/components/Toolbar/Toolbar.js

@@ -31,7 +31,8 @@ type Props = {
 };
 
 /**
- *  Toolbar is a generalization of action bars for use within application layouts.
+ * Toolbar is usually used as a header placed at the top of the screen.
+ * It can contain the screen title, controls such as navigation buttons, menu button etc.
  *
  * ## Usage
  * ```js

src/components/Toolbar/ToolbarAction.js

@@ -31,6 +31,9 @@ type Props = {
   style?: any,
 };
 
+/**
+ * The ToolbarAction component is used for displaying an action item in the toolbar.
+ */
 export default class ToolbarAction extends React.Component<Props> {
   render() {
     const { dark, icon, onPress, size, style, ...rest } = this.props;

src/components/Toolbar/ToolbarBackAction.js

@@ -20,6 +20,9 @@ type Props = {
   style?: any,
 };
 
+/**
+ * The ToolbarBackAction component is used for displaying a back button in the toolbar.
+ */
 const ToolbarBackAction = (props: Props) => {
   const { dark, onPress, style } = props;
 

src/components/Toolbar/ToolbarContent.js

@@ -39,6 +39,9 @@ type Props = {
   theme: Theme,
 };
 
+/**
+ * The ToolbarContent component is used for displaying a title and optional subtitle in a toolbar.
+ */
 class ToolbarContent extends React.Component<Props> {
   render() {
     const {