[add] StyleSheet.compose

As per the recent addition to React Native.

Author: necolas

benchmarks/index.js

@@ -29,7 +29,7 @@ const fastestTests = [
   () => renderDeepTree('styletron', styletron),
   () => renderWideTree('styletron', styletron),
   () => renderDeepTree('aphrodite', aphrodite),
-  () => renderWideTree('aphrodite', aphrodite),
+  () => renderWideTree('aphrodite', aphrodite)
 ];
 
 /**
@@ -47,7 +47,7 @@ const restTests = [
   () => renderDeepTree('reactxp', xp),
   () => renderWideTree('reactxp', xp),
   () => renderDeepTree('radium', radium),
-  () => renderWideTree('radium', radium),
+  () => renderWideTree('radium', radium)
 ];
 
 const tests = [...coreTests];

docs/storybook/2-apis/StyleSheet/StyleSheetScreen.js

@@ -21,6 +21,22 @@ const StyleSheetScreen = () => (
     </Description>
 
     <Section title="Methods">
+      <DocItem
+        description={
+          <AppText>
+            Combines two styles such that <Code>style2</Code> will override any styles in{' '}
+            <Code>style1</Code>. If either style is falsy, the other one is returned without
+            allocating an array, saving allocations and maintaining reference equality for{' '}
+            <Code>PureComponent</Code> checks.
+          </AppText>
+        }
+        example={{
+          code: 'StyleSheet.compose(style1, style2);'
+        }}
+        name="compose"
+        typeInfo="(style1, style2) => style"
+      />
+
       <DocItem
         description="Each key of the object passed to `create` must define a style object. The returned object replaces style objects with IDs"
         example={{

src/apis/StyleSheet/__tests__/index-test.js

@@ -22,6 +22,18 @@ describe('apis/StyleSheet', () => {
     expect(isPlainObject(StyleSheet.absoluteFillObject) === true).toBeTruthy();
   });
 
+  describe('compose', () => {
+    test('returns array when neither style is falsey', () => {
+      expect(StyleSheet.compose(1, 2)).toEqual([1, 2]);
+    });
+    test('returns style1 when style2 is falsey', () => {
+      expect(StyleSheet.compose(1, null)).toBe(1);
+    });
+    test('returns style2 when style1 is falsey', () => {
+      expect(StyleSheet.compose(null, 2)).toBe(2);
+    });
+  });
+
   describe('create', () => {
     test('replaces styles with numbers', () => {
       const style = StyleSheet.create({ root: { position: 'absolute' } });

src/apis/StyleSheet/index.js

@@ -36,6 +36,13 @@ const absoluteFill = StyleRegistry.register(absoluteFillObject);
 const StyleSheet = {
   absoluteFill,
   absoluteFillObject,
+  compose(style1, style2) {
+    if (style1 && style2) {
+      return [style1, style2];
+    } else {
+      return style1 || style2;
+    }
+  },
   create(styles) {
     const result = {};
     Object.keys(styles).forEach(key => {