From b5c8af2694dd95a9da07f6975a7868bce6ad3826 Mon Sep 17 00:00:00 2001 From: Nicolas Gallagher Date: Thu, 3 Sep 2015 23:12:17 -0700 Subject: [PATCH] Documentation fixes --- README.md | 4 +- docs/View.spec.md | 66 -------------------------- docs/components/Image.md | 17 ++++--- docs/components/Text.md | 11 +++-- docs/components/TextInput.md | 2 +- docs/components/View.md | 6 +-- docs/react-native-web-style/styling.md | 30 ++++++------ 7 files changed, 34 insertions(+), 102 deletions(-) delete mode 100644 docs/View.spec.md diff --git a/README.md b/README.md index 165e0336..1492b707 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ 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 +inline styles. Read more about the [styling strategy](docs/react-native-web-style/styling.md). See this [guide to flexbox][flexbox-guide-url]. @@ -150,7 +150,7 @@ 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/ +[flexbox-guide-url]: 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/ diff --git a/docs/View.spec.md b/docs/View.spec.md deleted file mode 100644 index 74fa4947..00000000 --- a/docs/View.spec.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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 -any type. - -## PropTypes - -All other props are transferred directly to the `element`. - -+ `component`: `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 ViewDefaultStyle = { - 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/components/Image.md b/docs/components/Image.md index 0cdf8fa6..01ddbeec 100644 --- a/docs/components/Image.md +++ b/docs/components/Image.md @@ -2,12 +2,10 @@ #### PropTypes -All other props are transferred directly to the `element`. +All other props are transferred to the resulting `img`. + `accessibilityLabel`: `string` -+ `async`: `bool` (TODO) -+ `className`: `string` -+ `source`: `string` ++ `source`: `object` + `style`: `ImageStylePropTypes` #### ImageStylePropTypes @@ -20,10 +18,11 @@ All other props are transferred directly to the `element`. #### Examples ```js -import {Image} from 'react-web-sdk'; -import React, {PropTypes} from 'react'; +import React, { Image } from 'react-native-web' -class Avatar extends React.Component { +const { Component, PropTypes } = React; + +class Avatar extends Component { static propTypes = { size: PropTypes.oneOf(['small', 'normal', 'large']), user: PropTypes.object @@ -37,10 +36,10 @@ class Avatar extends React.Component { return ( - ); + ) } } diff --git a/docs/components/Text.md b/docs/components/Text.md index 08bef696..151c345b 100644 --- a/docs/components/Text.md +++ b/docs/components/Text.md @@ -4,9 +4,9 @@ Text layout and styles. #### PropTypes -All other props are transferred directly to the `element`. +All other props are transferred directly to the `component`. -+ `element`: `func` or `string` (default `"div"`) ++ `component`: `func` or `string` (default `'div'`) + `style`: `TextStylePropTypes` #### TextStylePropTypes @@ -17,10 +17,11 @@ All other props are transferred directly to the `element`. ## Examples ```js -import {Text} from 'react-web-sdk'; -import React, {PropTypes} from 'react'; +import React, { Text } from 'react-native-web' -class PrettyText extends React.Component { +const { Component, PropTypes } = React + +class PrettyText extends Component { static propTypes = { color: PropTypes.oneOf(['white', 'gray', 'red']), size: PropTypes.oneOf(['small', 'normal', 'large']), diff --git a/docs/components/TextInput.md b/docs/components/TextInput.md index 689be3cf..7dbd296e 100644 --- a/docs/components/TextInput.md +++ b/docs/components/TextInput.md @@ -4,7 +4,7 @@ Text input layout and styles. #### PropTypes -All other props are transferred directly to the `element`. +All other props are transferred directly to the `component`. + `component`: `func` or `string` (default `"div"`) + `style`: `TextStylePropTypes` diff --git a/docs/components/View.md b/docs/components/View.md index 12c39fcc..9422cd6d 100644 --- a/docs/components/View.md +++ b/docs/components/View.md @@ -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` @@ -21,7 +21,7 @@ All other props are transferred directly to the `element`. + `color`: `string` + `opacity`: `number` -## ViewStyleDefaultProps +## ViewDefaultStyle Implements the default styles from [facebook/css-layout](https://github.com/facebook/css-layout). @@ -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/react-native-web-style/styling.md b/docs/react-native-web-style/styling.md index dfec005b..3da2d0f6 100644 --- a/docs/react-native-web-style/styling.md +++ b/docs/react-native-web-style/styling.md @@ -12,8 +12,8 @@ convert inline styles to static CSS: ## Style syntax: native vs proprietary data structure -React Web SDK (in a divergence from React Native) represents style using plain -JS objects: +React Native for Web diverges from React Native by using plain JS objects for +styles: ```js ... @@ -46,19 +46,18 @@ const styles = Stylesheet.create({ ## JS-to-CSS: conversion strategies -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. - -![](../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. -React Web SDK includes a proof-of-concept for the strategy of automatically -mapping unique declarations to declarations, via a unique selector for each -declaration. This strategy results in smaller CSS files because an application -has fewer unique declarations than total declarations. Creating a new -component with no new unique declarations results in no change to the CSS file. +![](../static/styling-strategy.png) + +One strategy for converting styles from JS to CSS is to map style objects to +CSS rules. Another strategy is to map declarations to declarations. + +React Native for Web currently includes a proof-of-concept implementation of +the latter strategy. This results in smaller CSS files because all applications +has fewer unique declarations than total declarations. Creating a new component +with no new unique declarations results in no change to the CSS file. For example: @@ -92,10 +91,9 @@ And is backed by: The current implementation uses a precomputed CSS library of single-declaration rules, with obfuscated selectors. This handles a signficant portion of possible -declarations. But a build-time implementation would produce more accurate CSS +declarations. A build-time implementation would produce more accurate CSS files and fall through to inline styles significantly less often. - (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 @@ -121,5 +119,5 @@ Query data could be accessed on `this.content`? Pseudo-classes like `:hover` and `:focus` can be handled with JavaScript. Pseudo-elements should be avoided in general, but for particular cases like -`::placeholder` it might be necessary to reimplement it in the SDK's -`TextInput` component (see React Native's API). +`::placeholder` it might be necessary to reimplement it in the `TextInput` +component (see React Native's API).