diff --git a/docs/apis/StyleSheet.md b/docs/apis/StyleSheet.md index fe6869a9..caadf7cb 100644 --- a/docs/apis/StyleSheet.md +++ b/docs/apis/StyleSheet.md @@ -1,21 +1,13 @@ # StyleSheet React Native for Web will automatically vendor-prefix styles applied to the -libraries components. The `StyleSheet` abstraction converts predefined styles +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 `style`-to-`className` conversion strategy is optimized to minimize the -amount of CSS required. Unique declarations are defined using "atomic" CSS – a -unique class name for a unique declaration. - -React Native for Web includes a CSS reset to remove unwanted user agent styles -from elements and pseudo-elements beyond the reach of React (e.g., `html` and -`body`). - Create a new StyleSheet: -``` +```js const styles = StyleSheet.create({ container: { borderRadius: 4, @@ -55,17 +47,53 @@ StyleSheet.renderToString() **create**(obj: {[key: string]: any}) +**destroy**() + +Clears all style information. + **renderToString**() -## Strategy +Renders a CSS Style Sheet. -Mapping entire `style` objects to CSS rules can lead to increasingly large CSS -files. Each new component adds new rules to the stylesheet. +## About -![](../static/styling-strategy.png) +### Strategy -React Native for Web uses an alternative strategy: mapping declarations to -declarations. +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 also minimizes the amount of generated CSS, making it more 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 +// +// .a { color: gray; } +// .b { font-size: 2rem; } +// .c { font-size: 1.25rem; } +``` For example: @@ -102,11 +130,11 @@ 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 -stylesheet growth in a similar way. But they're CSS utility libraries, each with a +style sheet growth in a similar way. But they're CSS utility libraries, each with a particular set of classes and features to learn. All of them require developers to manually connect CSS classes for given styles.) -## Media Queries, pseudo-classes, and pseudo-elements +### Media Queries, pseudo-classes, and pseudo-elements Media Queries in JavaScript can be used to modify the render tree and styles. This has the benefit of co-locating breakpoint-specific DOM and style changes. @@ -115,3 +143,33 @@ Pseudo-classes like `:hover` and `:focus` can be replaced with JavaScript events. Pseudo-elements are not supported. + +### Reset + +React Native for Web includes a very small CSS reset taken from +[normalize.css](https://necolas.github.io/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; +} +```