Reorganize docs; rewrite README

README.md

@@ -1,101 +1,123 @@
-# react-web-sdk
+# React Native for Web
 
-**Experimental / Proof of concept**
+[![Build Status][travis-image]][travis-url]
+[![npm version][npm-image]][npm-url] (14 KB gzipped)
 
-A React SDK (~9KB gzipped) for creating web applications and toolkits. Inspired by `react-native`.
+The core [React Native][react-native-url] components built for the web, backed
+by a precomputed CSS library.
 
-It includes the following components:
+## Table of contents
 
-* `Image`: an image primitive
-* `Text`: a text primitive
-* `TextInput`: a text input primitive
-* `View`: a flexbox primitive
+* [Install](#install)
+* [Use](#use)
+* [Components](#components)
+* [Styling](#styling)
+* [Contributing](#contributing)
+* [Thanks](#thanks)
+* [License](#license)
 
-And uses a [styling strategy](docs/styling-strategy.md) that maps inline styles
-to single-purpose CSS rules.
+## Install
 
-This proof of concept uses a CSS bundle (~4.5KB gzipped) of 300+ precomputed
-declarations. A more sophisticated implementation is likely to produce a
-slightly larger CSS file and fewer inline styles.
+```
+npm install --save react react-native-web
+```
+
+## Use
+
+React Native for Web exports its components and a reference to the `React`
+installation. Styles are authored in JavaScript as plain objects.
+
+```js
+import React, { View } from 'react-native-web'
+
+class MyComponent extends React.Component {
+  render() {
+    return (
+      <View style={styles.root} />
+    )
+  }
+}
+
+const styles = {
+  root: {
+    borderColor: 'currentcolor'
+    borderWidth: '5px',
+    flexDirection: 'row'
+    height: '5em'
+  }
+}
+```
 
 ## Components
 
-All components define explicit `style` PropTypes according to the [`StyleProp`
-spec](docs/StyleProp.spec.md).
+Partial implementations of…
 
-### View
-
-TODO
-
-A flexbox container; foundational layout building block.
-
-[`View` spec](docs/View.spec.md)
-
-See this [guide to flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/).
-
-### Text
-
-TODO
-
-[`Text` spec](docs/Text.spec.md)
-
-### TextInput
-
-TODO
-
-[`Text` spec](docs/TextInput.spec.md)
-
-### Image
-
-TODO
-
-[`Image` spec](docs/Image.spec.md)
+* [`Image`](docs/components/Image.md)
+* [`Text`](docs/components/Text.md)
+* [`TextInput`](docs/components/TextInput.md)
+* [`View`](docs/components/View.md)
 
 ## Styling
 
+React Native Web provides a mechanism to declare all your styles and layout
+inline with the components that use them. The `View` component makes it easy
+to build common layouts with flexbox, such as stacked and nested boxes with
+margin and padding.
+
 Styling is identical to using inline styles in React, but most inline styles
-are converted to unique CSS classes.
+are converted to single-purpose classes. The current implementation includes
+300+ precomputed CSS declarations (~4.5KB gzipped) that cover a large
+proportion of common styles. A more sophisticated build-time implementation may
+produce a slightly larger CSS file for large apps, and fall back to fewer
+inline styles.  Read more about the [styling
+strategy](docs/react-native-web-style/styling.md).
 
-The companion stylesheet can be referenced as an external resource, inlined, or
-injected by JS.
-
-See the [styling strategy docs](docs/styling-strategy.md) for more details.
-
-### Use plain JavaScript objects
-
-Use JavaScript to write style definitions in React components:
+See this [guide to flexbox][flexbox-guide-url].
 
 ```js
-const style = {
-  common: {
-    backgroundColor: 'white',
-    borderRadius: '1em'
-  },
-  root: {
-    flexDirection: 'row',
-    justifyContent: 'space-between'
-  },
-  image: {
-    opacity: 0.5
-  },
-  text: {
-    fontWeight: '300'
-  }
-};
-```
+import React, { Image, Text, View } from 'react-native-web'
 
-### Use the `style` attribute
-
-The `style` attribute is a simple API for creating element-scoped styles.
-
-```js
-import { View } from 'react-web-sdk';
-
-class Example extends React.Component {
+class App extends React.Component {
   render() {
     return (
-      <View style={style.root}>...</View>
-    );
+      <View style={styles.row}>
+        <Image
+          source={{ uri: 'http://facebook.github.io/react/img/logo_og.png' }}
+          style={styles.image}
+        />
+        <View style={styles.text}>
+          <Text style={styles.title}>
+            React Native Web
+          </Text>
+          <Text style={styles.subtitle}>
+            Build high quality web apps using React
+          </Text>
+        </View>
+      </View>
+    )
+  },
+})
+
+const styles = {
+  row: {
+    flexDirection: 'row',
+    margin: 40
+  },
+  image: {
+    height: 40,
+    marginRight: 10,
+    width: 40,
+  },
+  text: {
+    flex: 1,
+    justifyContent: 'center'
+  },
+  title: {
+    fontSize: '1.25rem',
+    fontWeight: 'bold'
+  },
+  subtitle: {
+    fontSize: '1rem'
   }
 }
 ```
@@ -103,7 +125,7 @@ class Example extends React.Component {
 Combine and override style objects:
 
 ```js
-import baseStyle from './baseStyle';
+import baseStyle from './baseStyle'
 
 const buttonStyle = {
   ...baseStyle,
@@ -112,10 +134,25 @@ const buttonStyle = {
 }
 ```
 
-## Development
+## Contributing
 
-```
-npm install
-npm run build:example:watch
-open example/index.html
-```
+Please read the [contribution guidelines][contributing-url]. Contributions are
+welcome!
+
+## Thanks
+
+Thanks to current and past members of the React and React Native teams (in
+particular Vjeux and Pete Hunt), and Tobias Koppers for Webpack and CSS loader.
+
+## License
+
+Copyright (c) 2015 Nicolas Gallagher. Released under the [MIT
+license](http://www.opensource.org/licenses/mit-license.php).
+
+[contributing-url]: https://github.com/necolas/react-native-web/blob/master/CONTRIBUTING.md
+[flexbox-guide]: https://css-tricks.com/snippets/css/a-guide-to-flexbox/
+[npm-image]: https://img.shields.io/npm/v/react-native-web.svg
+[npm-url]: https://npmjs.org/package/react-native-web
+[react-native-url]: https://facebook.github.io/react-native/
+[travis-image]: https://travis-ci.org/necolas/react-native-web.svg?branch=master
+[travis-url]: https://travis-ci.org/necolas/react-native-web

docs/Component.md

@@ -1,44 +0,0 @@
-# `Component`
-
-This component is part of the implementation for managing styles across the
-`className` and `style` properties. It is the building block upon which all
-other components in `react-web-sdk` are built.
-
-## PropTypes
-
-All other props are transferred directly to the `element`.
-
-+ `element`: `func` or `string`
-+ `style`: `object`
-
-#### Examples
-
-```js
-import {Component, pickProps} from 'react-web-sdk';
-import React, {PropTypes} from 'react';
-
-const ExampleStylePropTypes = { opacity: PropTypes.number };
-const ExampleStyleDefaultProps = { opacity: 1 };
-
-class Example extends React.Component {
-  static propTypes = {
-    style: PropTypes.shape(ExampleStylePropTypes)
-  }
-
-  render() {
-    const { style, ...other } = this.props;
-    // only apply supported styles
-    const supportedStyle = pickProps(style, ExampleStylePropTypes);
-    // merge with default styles
-    const mergedStyle = { ...ExampleStyleDefaultProps, ...supportedStyle }
-
-    return (
-      <Component
-        ...other
-        element="main"
-        style={mergedStyle}
-      />
-    );
-  }
-}
-```

docs/View.spec.md

@@ -1,4 +1,4 @@
-# View spec
+# View
 
 `View` is a flexbox container and the fundamental building block for UI. It is
 designed to be nested inside other `View`'s and to have 0-to-many children of
@@ -8,7 +8,7 @@ any type.
 
 All other props are transferred directly to the `element`.
 
-+ `element`: `func` or `string` (default `"div"`)
++ `component`: `func` or `string` (default `"div"`)
 + `pointerEvents`: `oneOf('all', 'box-only', 'box-none', 'none')`
 + `style`: `ViewStylePropTypes`
 
@@ -43,7 +43,7 @@ Implements the default styles from
    `right`, `bottom` do something when not specifying `position:absolute`.
 
 ```js
-const ViewStyleDefaultProps = {
+const ViewDefaultStyle = {
   alignItems: 'stretch', // 1
   borderWidth: 0,
   borderStyle: 'solid',

docs/components/View.md

@@ -0,0 +1,66 @@
+# View spec
+
+`View` is a flexbox container and the fundamental building block for UI. It is
+designed to be nested inside other `View`'s and to have 0-to-many children of
+any type.
+
+## PropTypes
+
+All other props are transferred directly to the `element`.
+
++ `element`: `func` or `string` (default `"div"`)
++ `pointerEvents`: `oneOf('all', 'box-only', 'box-none', 'none')`
++ `style`: `ViewStylePropTypes`
+
+## ViewStylePropTypes
+
++ BackgroundPropTypes
++ BorderThemePropTypes
++ LayoutPropTypes
++ `boxShadow`: `string`
++ `color`: `string`
++ `opacity`: `number`
+
+## ViewStyleDefaultProps
+
+Implements the default styles from
+[facebook/css-layout](https://github.com/facebook/css-layout).
+
+1. All the flex elements are oriented from top-to-bottom, left-to-right and do
+   not shrink. This is how things are laid out using the default CSS settings
+   and what you'd expect.
+
+2. The most convenient way to express the relation between width and other
+   box-model properties.
+
+3. Everything is `display:flex` by default. All the behaviors of `block` and
+   `inline-block` can be expressed in term of flex but not the opposite.
+
+4. Everything is `position:relative`. This makes `position:absolute` target the
+   direct parent and not some parent which is either relative or absolute. If
+   you want to position an element relative to something else, you should move
+   it in the DOM instead of relying of CSS. It also makes `top`, `left`,
+   `right`, `bottom` do something when not specifying `position:absolute`.
+
+```js
+const ViewStyleDefaultProps = {
+  alignItems: 'stretch', // 1
+  borderWidth: 0,
+  borderStyle: 'solid',
+  boxSizing: 'border-box', // 2
+  display: 'flex', // 3
+  flexBasis: 'auto', // 1
+  flexDirection: 'column', // 1
+  flexShrink: 0, // 1
+  listStyle: 'none',
+  margin: 0,
+  padding: 0,
+  position: 'relative' // 4
+};
+```
+
+## Examples
+
+```js
+// TODO
+```

docs/react-native-web-style/styling.md

@@ -49,7 +49,7 @@ const styles = Stylesheet.create({
 One strategy for converting styles from JS to CSS is to map style objects to
 CSS rules. Another strategy is to map declarations to declarataions.
 
-![](sdk-styling-strategy.png)
+![](../static/styling-strategy.png)
 
 Mapping entire `style` objects to CSS rules can lead to increasingly large CSS
 files. Each new component adds new rules to the stylesheet.