diff --git a/README.md b/README.md index 4aa2b91c..165e0336 100644 --- a/README.md +++ b/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 ( + + ) + } +} + +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 ( - ... - ); + + + + + React Native Web + + + Build high quality web apps using React + + + + ) + }, +}) + +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 diff --git a/docs/Component.md b/docs/Component.md deleted file mode 100644 index c7183bf0..00000000 --- a/docs/Component.md +++ /dev/null @@ -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 ( - - ); - } -} -``` diff --git a/docs/View.spec.md b/docs/View.spec.md index 12c39fcc..74fa4947 100644 --- a/docs/View.spec.md +++ b/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', diff --git a/docs/Image.spec.md b/docs/components/Image.md similarity index 100% rename from docs/Image.spec.md rename to docs/components/Image.md diff --git a/docs/Text.spec.md b/docs/components/Text.md similarity index 100% rename from docs/Text.spec.md rename to docs/components/Text.md diff --git a/docs/TextInput.spec.md b/docs/components/TextInput.md similarity index 100% rename from docs/TextInput.spec.md rename to docs/components/TextInput.md diff --git a/docs/components/View.md b/docs/components/View.md new file mode 100644 index 00000000..12c39fcc --- /dev/null +++ b/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 +``` diff --git a/docs/StyleProp.spec.md b/docs/react-native-web-style/style-props.md similarity index 100% rename from docs/StyleProp.spec.md rename to docs/react-native-web-style/style-props.md diff --git a/docs/styling-strategy.md b/docs/react-native-web-style/styling.md similarity index 99% rename from docs/styling-strategy.md rename to docs/react-native-web-style/styling.md index 2949bd75..dfec005b 100644 --- a/docs/styling-strategy.md +++ b/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. diff --git a/docs/sdk-components.png b/docs/static/components.png similarity index 100% rename from docs/sdk-components.png rename to docs/static/components.png diff --git a/docs/sdk-styling-strategy.png b/docs/static/styling-strategy.png similarity index 100% rename from docs/sdk-styling-strategy.png rename to docs/static/styling-strategy.png