From 74ef265d838681975e4e2072b5d7e3af0c265d99 Mon Sep 17 00:00:00 2001
From: Nicolas Gallagher <nicolasgallagher@gmail.com>
Date: Wed, 30 Dec 2015 14:04:00 -0800
Subject: [PATCH] [chore] update documentation

---
 README.md                    | 197 ++++++++++++-------------------
 docs/apis/StyleSheet.md      | 124 +-------------------
 docs/guides/accessibility.md |  31 +++++
 docs/guides/style.md         | 220 +++++++++++++++++++++++++++++++++++
 4 files changed, 329 insertions(+), 243 deletions(-)
 create mode 100644 docs/guides/accessibility.md
 create mode 100644 docs/guides/style.md

diff --git a/README.md b/README.md
index 3013485b..d2ae5cbe 100644
--- a/README.md
+++ b/README.md
@@ -2,93 +2,65 @@
 
 [![Build Status][travis-image]][travis-url]
 [![npm version][npm-image]][npm-url]
-![gzipped size](https://img.shields.io/badge/gzipped-~18.9k-blue.svg)
+![gzipped size](https://img.shields.io/badge/gzipped-~19.3k-blue.svg)
 
-[React Native][react-native-url] components and APIs for the Web.
-
-Try it out in the [React Native for Web
-Playground](http://codepen.io/necolas/pen/PZzwBR) on CodePen.
+[React Native][react-native-url] components and APIs for the Web. Flexbox
+layout and JavaScript styling.
 
 * [Discord: #react-native-web on reactiflux][discord-url]
 * [Gitter: react-native-web][gitter-url]
 
 ## Table of contents
 
-* [Install](#install)
+* [Quick start](#quick-start)
+* [Overview](#overview)
 * [Example](#example)
 * [APIs](#apis)
 * [Components](#components)
-* [Styling](#styling)
-* [Accessibility](#accessibility)
 * [Contributing](#contributing)
 * [Thanks](#thanks)
 * [License](#license)
 
-## Install
+## Quick start
+
+You can [try the latest version on CodePen](http://codepen.io/necolas/pen/PZzwBR).
+
+To install in your app:
 
 ```
-npm install --save react react-dom react-native-web
+npm install --save react@0.14 react-dom@0.14 react-native-web
 ```
 
-## Example
+## Overview
 
-React Native for Web exports its components, a reference to the `react`
-installation, and the `react-dom` methods (customized for Web). Styles are defined
-with, and used as JavaScript objects.
+### Importing
 
-Component:
+All API's, components, and a Web-specific `React` are provided by the
+`react-native-web` module:
 
 ```js
 import React, { Image, StyleSheet, Text, View } from 'react-native-web'
-
-const Title = ({ children }) => <Text style={styles.title}>{children}</Text>
-
-const Summary = ({ children }) => (
-  <View style={styles.text}>
-    <Text style={styles.subtitle}>{children}</Text>
-  </View>
-)
-
-class App extends React.Component {
-  render() {
-    return (
-      <View style={styles.row}>
-        <Image
-          source={{ uri: 'http://facebook.github.io/react/img/logo_og.png' }}
-          style={styles.image}
-        />
-        <Title>React Native Web</Title>
-        <Summary>Build high quality web apps using React</Summary>
-      </View>
-    )
-  },
-})
-
-const styles = StyleSheet.create({
-  row: {
-    flexDirection: 'row',
-    margin: 40
-  },
-  image: {
-    height: 40,
-    marginRight: 10,
-    width: 40,
-  },
-  text: {
-    flexGrow: 1,
-    justifyContent: 'center'
-  },
-  title: {
-    fontSize: '1.25rem',
-    fontWeight: 'bold'
-  },
-  subtitle: {
-    fontSize: '1rem'
-  }
-})
 ```
 
-Pre-rendering on the server automatically includes your app styles:
+### Client-side rendering
+
+Client-side rendering requires that you use the module's `React` export.
+`React.render` is a thin wrapper around `ReactDOM.render` that renders your
+application and the style sheet. Styles are updated if new bundles are loaded
+asynchronously.
+
+```js
+// client.js
+import App from './components/App'
+import React from 'react-native-web'
+
+React.render(<App />, document.getElementById('react-root'))
+```
+
+### Server-side rendering
+
+Server-side rendering is done by calling `React.renderToString` or
+`React.renderToStaticMarkup`, the output of both includes the style sheet.
 
 ```js
 // server.js
@@ -110,15 +82,49 @@ const Html = () => (
 )
 ```
 
-Rendering on the client automatically includes your app styles and supports
-progressive app loading (i.e. code-splitting / lazy bundle loading):
+### Styling
+
+React Native for Web allows you to [define styles using
+JavaScript](docs/guides/style.md), either with inline styles or
+[`StyleSheet.create`](docs/apis/StyleSheet.md).
+
+The `View` component makes it easy to build common layouts with flexbox, such
+as stacked and nested boxes with margin and padding. See this [guide to
+flexbox][flexbox-guide-url].
+
+### Accessibility
+
+The most common and best supported [accessibility
+features](docs/guides/accessibility.md) of the Web are leveraged through 4
+props available on most components: `accessible`, `accessibilityLabel`,
+`accessibilityLiveRegion`, and `accessibilityRole`.
+
+## Example
+
+More examples can be found in the [`examples` directory](examples).
 
 ```js
-// client.js
-import App from './components/App'
-import React from 'react-native-web'
+import React, { Image, StyleSheet, Text, View } from 'react-native-web'
 
-React.render(<App />, document.getElementById('react-root'))
+const Card = ({ children }) => <View style={styles.card}>{children}</View>
+const Title = ({ children }) => <Text style={styles.title}>{children}</Text>
+const Photo = ({ uri }) => <Image source={{ uri }} style={styles.image} />
+
+const styles = StyleSheet.create({
+  card: {
+    flexGrow: 1,
+    justifyContent: 'center'
+  },
+  title: {
+    fontSize: '1.25rem',
+    fontWeight: 'bold'
+  },
+  image: {
+    height: 40,
+    marginRight: 10,
+    width: 40
+  }
+})
 ```
 
 ## APIs
@@ -160,58 +166,6 @@ Touch bindings for press and long press.
 
 The fundamental UI building block using flexbox for layout.
 
-## Styling
-
-React Native for Web relies on styles being defined in JavaScript. Styling
-components can be achieved with inline styles or the use of
-[StyleSheet](docs/apis/StyleSheet.md).
-
-The `View` component makes it easy to build common layouts with flexbox, such
-as stacked and nested boxes with margin and padding. See this [guide to
-flexbox][flexbox-guide-url].
-
-### Media Queries, pseudo-classes, and pseudo-elements
-
-Changing styles and/or the render tree in response to device adaptation can be
-controlled in JavaScript, e.g.,
-[react-media-queries](https://github.com/bloodyowl/react-media-queries),
-[media-query-fascade](https://github.com/tanem/media-query-facade), or
-[react-responsive](https://github.com/contra/react-responsive). This has the
-benefit of co-locating breakpoint-specific DOM and style changes.
-
-Pseudo-classes like `:hover` and `:focus` can be implemented with the `onHover`
-and `onFocus` events.
-
-Pseudo-elements are not supported; elements can be used instead.
-
-## Accessibility
-
-On the Web, assistive technologies derive useful information about the
-structure, purpose, and interactivity of apps from their [HTML
-elements][html-accessibility-url], attributes, and [ARIA in
-HTML][aria-in-html-url].
-
-The most common and best supported accessibility features of the Web are
-exposed as the props: `accessible`, `accessibilityLabel`,
-`accessibilityLiveRegion`, and `accessibilityRole`.
-
-React Native for Web does not provide a way to directly control the rendered
-HTML element. The `accessibilityRole` prop is used to infer an [analogous HTML
-element][html-aria-url] to use in addition, where possible. While this may
-contradict some ARIA recommendations, it also helps avoid certain HTML5
-conformance errors and accessibility anti-patterns (e.g., giving a `heading`
-role to a `button` element).
-
-For example:
-
-* `<View accessibilityRole='article' />` => `<article role='article' />`.
-* `<View accessibilityRole='banner' />` => `<header role='banner' />`.
-* `<View accessibilityRole='button' />` => `<button type='button' role='button' />`.
-* `<Text accessibilityRole='link' href='/' />` => `<a role='link' href='/' />`.
-* `<View accessibilityRole='main' />` => `<main role='main' />`.
-
-See the component documentation for more details.
-
 ## Contributing
 
 Please read the [contribution guidelines][contributing-url]. Contributions are
@@ -230,13 +184,10 @@ backing the current implementation of `Touchable`.
 Copyright (c) 2015 Nicolas Gallagher. Released under the [MIT
 license](http://www.opensource.org/licenses/mit-license.php).
 
-[aria-in-html-url]: https://w3c.github.io/aria-in-html/
 [contributing-url]: https://github.com/necolas/react-native-web/blob/master/CONTRIBUTING.md
 [discord-url]: http://join.reactiflux.com
 [flexbox-guide-url]: https://css-tricks.com/snippets/css/a-guide-to-flexbox/
 [gitter-url]: https://gitter.im/necolas/react-native-web
-[html-accessibility-url]: http://www.html5accessibility.com/
-[html-aria-url]: http://www.w3.org/TR/html-aria/
 [npm-image]: https://badge.fury.io/js/react-native-web.svg
 [npm-url]: https://npmjs.org/package/react-native-web
 [react-native-url]: https://facebook.github.io/react-native/
diff --git a/docs/apis/StyleSheet.md b/docs/apis/StyleSheet.md
index b0b96c8e..7d1c042f 100644
--- a/docs/apis/StyleSheet.md
+++ b/docs/apis/StyleSheet.md
@@ -1,9 +1,9 @@
 # StyleSheet
 
-React Native for Web will automatically vendor-prefix styles applied to the
-library's components. The `StyleSheet` abstraction converts predefined styles
-to CSS without a compile-time step. Some styles cannot be resolved outside of
-the render loop and are applied as inline styles.
+The `StyleSheet` abstraction converts predefined styles to (vendor-prefixed)
+CSS without requiring a compile-time step. Some styles cannot be resolved
+outside of the render loop and are applied as inline styles. Read more about to
+[how style your application](docs/guides/style).
 
 Create a new StyleSheet:
 
@@ -40,119 +40,3 @@ Use styles:
 ## Methods
 
 **create**(obj: {[key: string]: any})
-
-## About
-
-### Strategy
-
-React Native for Web uses a `style`-to-`className` conversion strategy that is
-designed to avoid issues arising from the [7 deadly sins of
-CSS](https://speakerdeck.com/vjeux/react-css-in-js):
-
-1. Global namespace
-2. Dependency hell
-3. Dead code elimination
-4. Code minification
-5. Sharing constants
-6. Non-deterministic resolution
-7. Breaking isolation
-
-The strategy minimizes the amount of generated CSS, making it viable to inline
-the style sheet when pre-rendering pages on the server. There is one unique
-selector per unique style _declaration_.
-
-```js
-// definition
-{
-  heading: {
-    color: 'gray',
-    fontSize: '2rem'
-  },
-  text: {
-    color: 'gray',
-    fontSize: '1.25rem'
-  }
-}
-
-// css output
-//
-// .a { color: gray; }
-// .b { font-size: 2rem; }
-// .c { font-size: 1.25rem; }
-```
-
-For example:
-
-```js
-<View style={styles.root}>...</View>
-
-const styles = StyleSheet.create({
-  root: {
-    background: 'transparent',
-    display: 'flex',
-    flexGrow: 1,
-    justifyContent: 'center'
-  }
-})
-```
-
-Yields (in development):
-
-```html
-<div className="background:transparent display:flex flexGrow:1 justifyContent:center">...</div>
-```
-
-And is backed by the following CSS:
-
-```css
-.background\:transparent {background:transparent;}
-.display\:flex {display:flex;}
-.flexGrow\:1 {flex-grow:1;}
-.justifyContext\:center {justify-content:center;}
-```
-
-In production the class names are obfuscated.
-
-(CSS libraries like [Atomic CSS](http://acss.io/),
-[Basscss](http://www.basscss.com/), [SUIT CSS](https://suitcss.github.io/), and
-[tachyons](http://tachyons.io/) are attempts to limit style scope and limit
-style sheet growth in a similar way. But they're CSS utility libraries, each
-with a particular set of classes and features to learn. And all of them require
-developers to manually connect CSS classes for given styles.)
-
-### Reset
-
-React Native for Web includes a very small CSS reset taken from
-[normalize.css](https://necolas.github.io/normalize.css/) – **you do not need
-to include normalize.css**. It removes unwanted User Agent styles from
-(pseudo-)elements beyond the reach of React (e.g., `html`, `body`) or inline
-styles (e.g., `::-moz-focus-inner`).
-
-```css
-html {
-  font-family: sans-serif;
-  -ms-text-size-adjust: 100%;
-  -webkit-text-size-adjust: 100%;
-}
-
-body {
-  margin: 0;
-}
-
-button::-moz-focus-inner,
-input::-moz-focus-inner {
-  border: 0;
-  padding: 0;
-}
-
-input[type="search"]::-webkit-search-cancel-button,
-input[type="search"]::-webkit-search-decoration {
-  -webkit-appearance: none;
-}
-
-ol,
-ul,
-li {
-  list-style:none
-}
-```
diff --git a/docs/guides/accessibility.md b/docs/guides/accessibility.md
new file mode 100644
index 00000000..ac45d4fd
--- /dev/null
+++ b/docs/guides/accessibility.md
@@ -0,0 +1,31 @@
+# Accessibility
+
+On the Web, assistive technologies derive useful information about the
+structure, purpose, and interactivity of apps from their [HTML
+elements][html-accessibility-url], attributes, and [ARIA in
+HTML][aria-in-html-url].
+
+The most common and best supported accessibility features of the Web are
+exposed as the props: `accessible`, `accessibilityLabel`,
+`accessibilityLiveRegion`, and `accessibilityRole`.
+
+React Native for Web does not provide a way to directly control the rendered
+HTML element. The `accessibilityRole` prop is used to infer an [analogous HTML
+element][html-aria-url] to use in addition, where possible. While this may
+contradict some ARIA recommendations, it also helps avoid certain HTML5
+conformance errors and accessibility anti-patterns (e.g., giving a `heading`
+role to a `button` element).
+
+For example:
+
+* `<View accessibilityRole='article' />` => `<article role='article' />`.
+* `<View accessibilityRole='banner' />` => `<header role='banner' />`.
+* `<View accessibilityRole='button' />` => `<button type='button' role='button' />`.
+* `<Text accessibilityRole='link' href='/' />` => `<a role='link' href='/' />`.
+* `<View accessibilityRole='main' />` => `<main role='main' />`.
+
+See the component documentation for more details.
+
+[aria-in-html-url]: https://w3c.github.io/aria-in-html/
+[html-accessibility-url]: http://www.html5accessibility.com/
+[html-aria-url]: http://www.w3.org/TR/html-aria/
diff --git a/docs/guides/style.md b/docs/guides/style.md
new file mode 100644
index 00000000..bae3273e
--- /dev/null
+++ b/docs/guides/style.md
@@ -0,0 +1,220 @@
+# Style
+
+React Native for Web relies on JavaScript to let you style your application.
+Along with a novel JS-to-CSS conversion strategy, this allows you to avoid
+issues arising from the [7 deadly sins of
+CSS](https://speakerdeck.com/vjeux/react-css-in-js):
+
+1. Global namespace
+2. Dependency hell
+3. No dead code elimination
+4. No code minification
+5. No sharing of constants
+6. Non-deterministic resolution
+7. Lack of isolation
+
+## Defining styles
+
+Styles should be defined outside of the component:
+
+```js
+class Example extends React.Component {}
+
+const styles = StyleSheet.create({
+  heading: {
+    color: 'gray',
+    fontSize: '2rem'
+  },
+  text: {
+    color: 'gray',
+    fontSize: '1.25rem'
+  }
+})
+```
+
+Using `StyleSheet.create` is optional but provides some key advantages: styles
+are immutable in development, styles are converted to CSS rather than applied
+as inline styles, and styles are only created once for the application and not
+on every render.
+
+The attribute names and values are a subset of CSS. See the `style`
+documentation of individual components.
+
+## Using styles
+
+All the core components accept a `style` attribute.
+
+```js
+<Text style={styles.text} />
+<View style={styles.view} />
+```
+
+A common pattern is to conditionally add style based on a condition:
+
+```js
+<View style={{
+  ...styles.base,
+  ...(this.state.active && styles.active)
+}} />
+```
+
+## Composing styles
+
+In order to let a call site customize the style of your component children, you
+can pass styles around. Use `View.propTypes.style` and `Text.propTypes.style` in
+order to make sure only styles are being passed.
+
+```js
+export default class List extends React.Component {
+  static propTypes = {
+    style: View.propTypes.style,
+    elementStyle: View.propTypes.style,
+  }
+
+  render() {
+    return (
+      <View style={this.props.style}>
+        {elements.map((element) =>
+          <View style={{ ...styles.element, this.props.elementStyle }} />
+        )}
+      </View>
+    );
+  }
+}
+```
+
+In another file:
+
+```js
+<List style={styles.list} elementStyle={styles.listElement} />
+```
+
+You also have much greater control over how styles are composed when compared
+to using class names. For example, you may choose to accept a limited subset
+of style props in the component's API, and control when they are applied:
+
+```js
+class List extends React.Component {
+  static propTypes = {
+    children: React.PropTypes.any,
+    // limit which styles are accepted
+    style: React.PropTypes.shape({
+      borderColor: View.propTypes.borderColor,
+      borderWidth: View.propTypes.borderWidth
+    })
+  }
+
+  render() {
+    return (
+      <View
+        children={children}
+        style={{
+          ...this.props.style,
+          // override border-color when scrolling
+          ...(isScrolling && { borderColor: 'transparent' })
+       }}
+      />
+    )
+  }
+}
+```
+
+## Media Queries
+
+`StyleSheet.create` is a way of defining the styles your application requires;
+it does not concern itself with _where_ or _when_ those styles are applied to
+elements.
+
+Changing styles in response to device adaptation can be controlled using
+JavaScript Media Query API's. There are several React libraries that provide a
+means to do this, e.g.,
+[react-media-queries](https://github.com/bloodyowl/react-media-queries),
+[media-query-fascade](https://github.com/tanem/media-query-facade), or
+[react-responsive](https://github.com/contra/react-responsive). This approach
+has the benefit of co-locating breakpoint-specific DOM and style changes.
+
+## Pseudo-classes and pseudo-elements
+
+Pseudo-classes like `:hover` and `:focus` can be implemented with the `onHover`
+and `onFocus` events. Pseudo-elements are not supported; elements should be
+used instead.
+
+## How it works
+
+Every call to `StyleSheet.create` extracts the unique _declarations_ and
+converts them to a unique CSS rule. This is sometimes referred to as "atomic
+CSS". All the core components map their `style` property-value pairs to the
+corresponding `className`'s.
+
+By doing this, the total size of the generated CSS is determined by the
+total number of unique declarations (rather than the total number of rules in
+the application), making it viable to inline the style sheet when pre-rendering
+on the server.
+
+JavaScript definition:
+
+```js
+const styles = StyleSheet.create({
+  heading: {
+    color: 'gray',
+    fontSize: '2rem'
+  },
+  text: {
+    color: 'gray',
+    fontSize: '1.25rem'
+  }
+})
+```
+
+CSS output:
+
+```css
+._s1 { color: gray; }
+._s2 { font-size: 2rem; }
+._s3 { font-size: 1.25rem; }
+```
+
+Rendered HTML:
+
+```html
+<span className="_s1 _s2">Heading</span>
+<span className="_s1 _s3">Text</span>
+```
+
+### Reset
+
+You **do not** need to include a CSS reset or
+[normalize.css](https://necolas.github.io/normalize.css/).
+
+React Native for Web includes a very small CSS reset taken from normalize.css.
+It removes unwanted User Agent styles from (pseudo-)elements beyond the reach
+of React (e.g., `html`, `body`) or inline styles (e.g., `::-moz-focus-inner`).
+
+```css
+html {
+  font-family: sans-serif;
+  -ms-text-size-adjust: 100%;
+  -webkit-text-size-adjust: 100%;
+}
+
+body {
+  margin: 0;
+}
+
+button::-moz-focus-inner,
+input::-moz-focus-inner {
+  border: 0;
+  padding: 0;
+}
+
+input[type="search"]::-webkit-search-cancel-button,
+input[type="search"]::-webkit-search-decoration {
+  -webkit-appearance: none;
+}
+
+ol,
+ul,
+li {
+  list-style:none
+}
+```