Introduce Button Component

Summary:
Button is an important component to help the community get onboarded with RN quickly, so the first few minutes of a developer's experience is not spent formatting a simple button component.

In my opinion, `<Button />` should be seen as a "lowest common demoniator" component, rather than "the one button to rule them all". In other words, we should only support features in Button that will work on any platform. We should encourage people to fork Button if they need to add specific features to it, rather than trying to twist and bloat this component until it supports everything.

These platform imitations may not have the perfect constants just yet, but they are good enough to make a user feel at home in the app, without any modification. The community can help tweak the final formatting to make them look just right- PRs are welcome!

Reviewed By: frantic

Differential Revision: D3929041

fbshipit-source-id: 3785fb67472a7614eeee0a9aef504c0bdf62ede7

Examples/UIExplorer/js/ButtonExample.js

@@ -0,0 +1,96 @@
+/**
+ * Copyright (c) 2013-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree. An additional grant
+ * of patent rights can be found in the PATENTS file in the same directory.
+ *
+ * The examples provided by Facebook are for non-commercial testing and
+ * evaluation purposes only.
+ *
+ * Facebook reserves all rights not expressly granted.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL
+ * FACEBOOK BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+ * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * @flow
+ */
+'use strict';
+
+const React = require('react');
+const ReactNative = require('react-native');
+const {
+  Alert,
+  Button,
+  View,
+} = ReactNative;
+
+const onButtonPress = () => {
+  Alert.alert('Button has been pressed!');
+};
+
+exports.displayName = 'ButtonExample';
+exports.framework = 'React';
+exports.title = '<Button>';
+exports.description = 'Simple React Native button component.';
+
+exports.examples = [
+  {
+    title: 'Simple Button',
+    description: 'The title and onPress handler are required. It is ' +
+      'recommended to set accessibilityLabel to help make your app usable by ' +
+      'everyone.',
+    render: function() {
+      return (
+        <Button
+          onPress={onButtonPress}
+          title="Press Me"
+          accessibilityLabel="See an informative alert"
+        />
+      );
+    },
+  },
+  {
+    title: 'Adjusted color',
+    description: 'Adjusts the color in a way that looks standard on each ' +
+      'platform. On iOS, the color prop controls the color of the text. On ' +
+      'Android, the color adjusts the background color of the button.',
+    render: function() {
+      return (
+        <Button
+          onPress={onButtonPress}
+          title="Press Purple"
+          color="#841584"
+          accessibilityLabel="Learn more about purple"
+        />
+      );
+    },
+  },
+  {
+    title: 'Fit to text layout',
+    description: 'This layout strategy lets the title define the width of ' +
+      'the button',
+    render: function() {
+      return (
+        <View style={{flexDirection: 'row', justifyContent: 'space-between'}}>
+          <Button
+            onPress={onButtonPress}
+            title="This looks great!"
+            accessibilityLabel="This sounds great!"
+          />
+          <Button
+            onPress={onButtonPress}
+            title="Ok!"
+            color="#841584"
+            accessibilityLabel="Ok, Great!"
+          />
+        </View>
+      );
+    },
+  },
+];

Examples/UIExplorer/js/UIExplorerList.android.js

@@ -32,6 +32,10 @@ const ComponentExamples: Array<UIExplorerExample> = [
     key: 'ActivityIndicatorExample',
     module: require('./ActivityIndicatorExample'),
   },
+  {
+    key: 'ButtonExample',
+    module: require('./ButtonExample'),
+  },
   {
     key: 'ImageExample',
     module: require('./ImageExample'),

Examples/UIExplorer/js/UIExplorerList.ios.js

@@ -32,6 +32,10 @@ const ComponentExamples: Array<UIExplorerExample> = [
     key: 'ActivityIndicatorExample',
     module: require('./ActivityIndicatorExample'),
   },
+  {
+    key: 'ButtonExample',
+    module: require('./ButtonExample'),
+  },
   {
     key: 'DatePickerIOSExample',
     module: require('./DatePickerIOSExample'),

Libraries/Components/Button.js

@@ -0,0 +1,144 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree. An additional grant
+ * of patent rights can be found in the PATENTS file in the same directory.
+ *
+ * @providesModule Button
+ * @flow
+ */
+'use strict';
+
+const ColorPropType = require('ColorPropType');
+const Platform = require('Platform');
+const React = require('React');
+const StyleSheet = require('StyleSheet');
+const Text = require('Text');
+const TouchableNativeFeedback = require('TouchableNativeFeedback');
+const TouchableOpacity = require('TouchableOpacity');
+const View = require('View');
+
+const invariant = require('invariant');
+
+/**
+ * A basic button component that should render nicely on any platform. Supports
+ * a minimal level of customization.
+ *
+ * <center><img src="img/buttonExample.png"></img></center>
+ *
+ * If this button doesn't look right for your app, you can build your own
+ * button using [TouchableOpacity](https://facebook.github.io/react-native/docs/touchableopacity.html)
+ * or [TouchableNativeFeedback](https://facebook.github.io/react-native/docs/touchablenativefeedback.html).
+ * For inspiration, look at the [source code for this button component](https://github.com/facebook/react-native/blob/master/Libraries/Components/Button.js).
+ * Or, take a look at the [wide variety of button components built by the community](https://js.coach/react-native?search=button).
+ *
+ * Example usage:
+ *
+ * ```
+ * <Button
+ *   onPress={onPressLearnMore}
+ *   title="Learn More"
+ *   color="#841584"
+ *   accessibilityLabel="Learn more about this purple button"
+ * />
+ * ```
+ *
+ */
+
+class Button extends React.Component {
+
+  props: {
+    title: string,
+    onPress: () => any,
+    color?: ?string,
+    accessibilityLabel?: ?string,
+  };
+
+  static propTypes = {
+    /**
+     * Text to display inside the button
+     */
+    title: React.PropTypes.string.isRequired,
+    /**
+     * Text to display for blindness accessibility features
+     */
+    accessibilityLabel: React.PropTypes.string,
+    /**
+     * Color of the text (iOS), or background color of the button (Android)
+     */
+    color: ColorPropType,
+    /**
+     * Handler to be called when the user taps the button
+     */
+    onPress: React.PropTypes.func.isRequired,
+  };
+
+  render() {
+    const {
+      accessibilityLabel,
+      color,
+      onPress,
+      title,
+    } = this.props;
+    const buttonStyles = [styles.button];
+    const textStyles = [styles.text];
+    const Touchable = Platform.OS === 'android' ? TouchableNativeFeedback : TouchableOpacity;
+    if (color && Platform.OS === 'ios') {
+      textStyles.push({color: color});
+    } else if (color) {
+      buttonStyles.push({backgroundColor: color});
+    }
+    invariant(
+      typeof title === 'string',
+      'The title prop of a Button must be a string',
+    );
+    const formattedTitle = Platform.OS === 'android' ? title.toUpperCase() : title;
+    return (
+      <Touchable
+        accessibilityComponentType="button"
+        accessibilityLabel={accessibilityLabel}
+        accessibilityTraits={['button']}
+        onPress={onPress}>
+        <View style={buttonStyles}>
+          <Text style={textStyles}>{formattedTitle}</Text>
+        </View>
+      </Touchable>
+    );
+  }
+}
+
+// Material design blue from https://material.google.com/style/color.html#color-color-palette
+let defaultBlue = '#2196F3';
+if (Platform.OS === 'ios') {
+  // Measured default tintColor from iOS 10
+  defaultBlue = '#0C42FD';
+}
+
+const styles = StyleSheet.create({
+  button: Platform.select({
+    ios: {},
+    android: {
+      elevation: 4,
+      backgroundColor: defaultBlue,
+      borderRadius: 2,
+    },
+  }),
+  text: Platform.select({
+    ios: {
+      color: defaultBlue,
+      textAlign: 'center',
+      padding: 8,
+      fontSize: 18,
+    },
+    android: {
+      textAlign: 'center',
+      color: 'white',
+      padding: 8,
+      fontWeight: '500',
+    },
+  }),
+});
+
+module.exports = Button;

Libraries/react-native/react-native.js

@@ -30,6 +30,7 @@ const ReactNative = {
   get ActivityIndicator() { return require('ActivityIndicator'); },
   get ActivityIndicatorIOS() { return require('ActivityIndicatorIOS'); },
   get ART() { return require('ReactNativeART'); },
+  get Button() { return require('Button'); },
   get DatePickerIOS() { return require('DatePickerIOS'); },
   get DrawerLayoutAndroid() { return require('DrawerLayoutAndroid'); },
   get Image() { return require('Image'); },

website/server/extractDocs.js

@@ -10,16 +10,15 @@
 'use strict';
 
 const assert = require('assert');
-
+const babel = require('babel-core');
+const deepAssign = require('deep-assign');
 const docgen = require('react-docgen');
 const docgenHelpers = require('./docgenHelpers');
 const fs = require('fs');
 const jsDocs = require('../jsdocs/jsdocs.js');
+const jsdocApi = require('jsdoc-api');
 const path = require('path');
 const slugify = require('../core/slugify');
-const babel = require('babel-core');
-const jsdocApi = require('jsdoc-api');
-const deepAssign = require('deep-assign');
 
 const ANDROID_SUFFIX = 'android';
 const CROSS_SUFFIX = 'cross';
@@ -488,6 +487,7 @@ function renderStyle(filepath) {
 const components = [
   '../Libraries/Components/ActivityIndicator/ActivityIndicator.js',
   '../Libraries/Components/ActivityIndicator/ActivityIndicatorIOS.ios.js',
+  '../Libraries/Components/Button.js',
   '../Libraries/Components/DatePicker/DatePickerIOS.ios.js',
   '../Libraries/Components/DrawerAndroid/DrawerLayoutAndroid.android.js',
   '../Libraries/Image/Image.ios.js',