@samitouri / QOS-React-2 / commits / 0faf4b752f

Update some more docs for package split

Ben Alpert committed Oct 6, 2015 at 17:25 UTC 0faf4b752f43a18598dcac3541dda257a2a656af

12 files changed +137 -149

docs/docs/10-addons.md

+2 -4

@@ -6,7 +6,7 @@ prev: tooling-integration.html

6 next: animation.html

7 ---

9 -`React.addons` is where we park some useful utilities for building React apps. **These should be considered experimental** but will eventually be rolled into core or a blessed utilities library:

9 +The React add-ons are a collection of useful utility modules for building React apps. **These should be considered experimental** and tend to change more often than the core.

11 - [`TransitionGroup` and `CSSTransitionGroup`](animation.html), for dealing with animations and transitions that are usually not simple to implement, such as before a component's removal.

12 - [`LinkedStateMixin`](two-way-binding-helpers.html), to simplify the coordination between user's form input data and the component's state.

@@ -20,6 +20,4 @@ The add-ons below are in the development (unminified) version of React only:

20 - [`TestUtils`](test-utils.html), simple helpers for writing test cases (unminified build only).

21 - [`Perf`](perf.html), for measuring performance and giving you hint where to optimize.

23 -To get the add-ons, use `react-with-addons.js` (and its minified counterpart) rather than the common `react.js`.

24 -

25 -When using the react package from npm, simply `require('react/addons')` instead of `require('react')` to get React with all of the add-ons.

23 +To get the add-ons, install them individually from npm (e.g., `npm install react-addons-pure-render-mixin`). We don't support using the addons if you're not using npm.

docs/docs/10.1-animation.md

+4 -8

@@ -17,7 +17,7 @@ React provides a `ReactTransitionGroup` addon component as a low-level API for a

17 `ReactCSSTransitionGroup` is the interface to `ReactTransitions`. This is a simple element that wraps all of the components you are interested in animating. Here's an example where we fade list items in and out.

19 ```javascript{28-30}

20 -var ReactCSSTransitionGroup = React.addons.CSSTransitionGroup;

20 +var ReactCSSTransitionGroup = require('react-addons-css-transition-group');

22 var TodoList = React.createClass({

23 getInitialState: function() {

@@ -173,7 +173,7 @@ In order for it to apply transitions to its children, the `ReactCSSTransitionGro

173 In the example above, we rendered a list of items into `ReactCSSTransitionGroup`. However, the children of `ReactCSSTransitionGroup` can also be one or zero items. This makes it possible to animate a single element entering or leaving. Similarly, you can animate a new element replacing the current element. For example, we can implement a simple image carousel like this:

174

175 ```javascript{10-12}

176 -var ReactCSSTransitionGroup = React.addons.CSSTransitionGroup;

176 +var ReactCSSTransitionGroup = require('react-addons-css-transition-group');

177

178 var ImageCarousel = React.createClass({

179 propTypes: {

@@ -201,7 +201,7 @@ You can disable animating `enter` or `leave` animations if you want. For example

201

202 ## Low-level API: `ReactTransitionGroup`

203

204 -`ReactTransitionGroup` is the basis for animations. It is accessible as `React.addons.TransitionGroup`. When children are declaratively added or removed from it (as in the example above) special lifecycle hooks are called on them.

204 +`ReactTransitionGroup` is the basis for animations. It is accessible from `require('react-addons-transition-group')`. When children are declaratively added or removed from it (as in the example above) special lifecycle hooks are called on them.

205

206 ### `componentWillAppear(callback)`

207

@@ -237,11 +237,7 @@ By default `ReactTransitionGroup` renders as a `span`. You can change this behav

237 </ReactTransitionGroup>

238 ```

239

240 -Every DOM component that React can render is available for use. However, `component` does not need to be a DOM component. It can be any React component you want; even ones you've written yourself!

241 -

242 -> Note:

243 ->

244 -> Prior to v0.12, when using DOM components, the `component` prop needed to be a reference to `React.DOM.*`. Since the component is simply passed to `React.createElement`, it must now be a string. Composite components must pass the factory.

240 +Every DOM component that React can render is available for use. However, `component` does not need to be a DOM component. It can be any React component you want; even ones you've written yourself! Just write `component={List}` and your component will receive `this.props.children`.

241

242 Any additional, user-defined, properties will become properties of the rendered component. For example, here's how you would render a `<ul>` with CSS class:

243

docs/docs/10.2-form-input-binding-sugar.md

+6 -2

@@ -46,8 +46,10 @@ var NoLink = React.createClass({

46 This works really well and it's very clear how data is flowing, however, with a lot of form fields it could get a bit verbose. Let's use `ReactLink` to save us some typing:

48 ```javascript{2,7}

49 +var LinkedStateMixin = require('react-addons-linked-state-mixin');

50 +

51 var WithLink = React.createClass({

50 - mixins: [React.addons.LinkedStateMixin],

52 + mixins: [LinkedStateMixin],

53 getInitialState: function() {

54 return {message: 'Hello!'};

55 },

@@ -96,8 +98,10 @@ As you can see, `ReactLink` objects are very simple objects that just have a `va

98 ### ReactLink Without valueLink

100 ```javascript

101 +var LinkedStateMixin = require('react-addons-linked-state-mixin');

102 +

103 var WithoutLink = React.createClass({

100 - mixins: [React.addons.LinkedStateMixin],

104 + mixins: [LinkedStateMixin],

105 getInitialState: function() {

106 return {message: 'Hello!'};

107 },

docs/docs/10.3-class-name-manipulation.md

+1 -52

@@ -8,55 +8,4 @@ next: test-utils.html

9 > NOTE:

10 >

11 -> This module now exists independently at [JedWatson/classnames](https://github.com/JedWatson/classnames) and is React-agnostic. The add-on here will thus be removed in the future.

12 -

13 -`classSet()` is a neat utility for easily manipulating the DOM `class` string.

14 -

15 -Here's a common scenario and its solution without `classSet()`:

16 -

17 -```javascript

18 -// inside some `<Message />` React component

19 -render: function() {

20 - var classString = 'message';

21 - if (this.props.isImportant) {

22 - classString += ' message-important';

23 - }

24 - if (this.props.isRead) {

25 - classString += ' message-read';

26 - }

27 - // 'message message-important message-read'

28 - return <div className={classString}>Great, I'll be there.</div>;

29 -}

30 -```

31 -

32 -This can quickly get tedious, as assigning class name strings can be hard to read and error-prone. `classSet()` solves this problem:

33 -

34 -```javascript

35 -render: function() {

36 - var cx = React.addons.classSet;

37 - var classes = cx({

38 - 'message': true,

39 - 'message-important': this.props.isImportant,

40 - 'message-read': this.props.isRead

41 - });

42 - // same final string, but much cleaner

43 - return <div className={classes}>Great, I'll be there.</div>;

44 -}

45 -```

46 -

47 -When using `classSet()`, pass an object with keys of the CSS class names you might or might not need. Truthy values will result in the key being a part of the resulting string.

48 -

49 -`classSet()` also lets you pass class names in as arguments that are then concatenated for you:

50 -

51 -```javascript

52 -render: function() {

53 - var cx = React.addons.classSet;

54 - var importantModifier = 'message-important';

55 - var readModifier = 'message-read';

56 - var classes = cx('message', importantModifier, readModifier);

57 - // Final string is 'message message-important message-read'

58 - return <div className={classes}>Great, I'll be there.</div>;

59 -}

60 -```

61 -

62 -No more hacky string concatenations!

11 +> This module has been deprecated; use [JedWatson/classnames](https://github.com/JedWatson/classnames) instead.

docs/docs/10.4-test-utils.md

+8 -4

@@ -6,7 +6,11 @@ prev: two-way-binding-helpers.html

6 next: clone-with-props.html

7 ---

9 -`React.addons.TestUtils` makes it easy to test React components in the testing framework of your choice (we use [Jest](https://facebook.github.io/jest/)).

9 +`ReactTestUtils` makes it easy to test React components in the testing framework of your choice (we use [Jest](https://facebook.github.io/jest/)).

10 +

11 +```

12 +var ReactTestUtils = require('react-addons-test-utils');

13 +```

15 ### Simulate

@@ -23,7 +27,7 @@ Simulate an event dispatch on a DOM node with optional `eventData` event data. *

28 ```javascript

29 var node = ReactDOM.findDOMNode(this.refs.button);

26 -React.addons.TestUtils.Simulate.click(node);

30 +ReactTestUtils.Simulate.click(node);

31 ```

33 **Changing the value of an input field and then pressing ENTER**

@@ -31,8 +35,8 @@ React.addons.TestUtils.Simulate.click(node);

35 ```javascript

36 var node = ReactDOM.findDOMNode(this.refs.input);

37 node.value = 'giraffe'

34 -React.addons.TestUtils.Simulate.change(node);

35 -React.addons.TestUtils.Simulate.keyDown(node, {key: "Enter", keyCode: 13, which: 13});

38 +ReactTestUtils.Simulate.change(node);

39 +ReactTestUtils.Simulate.keyDown(node, {key: "Enter", keyCode: 13, which: 13});

40 ```

42 *note that you will have to provide any event property that you're using in your component (e.g. keyCode, which, etc...) as React is not creating any of these for you*

docs/docs/10.5-clone-with-props.md

+3 -1

@@ -12,8 +12,10 @@ next: create-fragment.html

12 In rare situations, you may want to create a copy of a React element with different props from those of the original element. One example is cloning the elements passed into `this.props.children` and rendering them with different props:

14 ```js

15 +var cloneWithProps = require('react-addons-clone-with-props');

16 +

17 var _makeBlue = function(element) {

16 - return React.addons.cloneWithProps(element, {style: {color: 'blue'}});

18 + return cloneWithProps(element, {style: {color: 'blue'}});

19 };

21 var Blue = React.createClass({

docs/docs/10.6-create-fragment.md

+6 -4

@@ -33,20 +33,22 @@ var Swapper = React.createClass({

34 The children will unmount and remount as you change the `swapped` prop because there aren't any keys marked on the two sets of children.

36 -To solve this problem, you can use `React.addons.createFragment` to give keys to the sets of children.

36 +To solve this problem, you can use the `createFragment` add-on to give keys to the sets of children.

38 -#### `ReactFragment React.addons.createFragment(object children)`

38 +#### `Array<ReactNode> createFragment(object children)`

40 Instead of creating arrays, we write:

42 ```js

43 +var createFragment = require('react-addons-create-fragment');

44 +

45 if (this.props.swapped) {

44 - children = React.addons.createFragment({

46 + children = createFragment({

47 right: this.props.rightChildren,

48 left: this.props.leftChildren

49 });

50 } else {

49 - children = React.addons.createFragment({

51 + children = createFragment({

52 left: this.props.leftChildren,

53 right: this.props.rightChildren

54 });

docs/docs/10.7-update.md

+3 -1

@@ -44,7 +44,9 @@ While this is fairly performant (since it only makes a shallow copy of `log n` o

44 `update()` provides simple syntactic sugar around this pattern to make writing this code easier. This code becomes:

46 ```js

47 -var newData = React.addons.update(myData, {

47 +var update = require('react-addons-update');

48 +

49 +var newData = update(myData, {

50 x: {y: {z: {$set: 7}}},

51 a: {b: {$push: [9]}}

52 });

docs/docs/10.9-perf.md

+4 -4

@@ -10,14 +10,14 @@ React is usually quite fast out of the box. However, in situations where you nee

11 In addition to giving you an overview of your app's overall performance, ReactPerf is a profiling tool that tells you exactly where you need to put these hooks.

13 +## General API

14 +

15 +The `Perf` object documented here is exposed as `require('react-addons-perf')` and can be used with React in development mode only. You should not include this bundle when building your app for production.

16 +

17 > Note:

18 >

19 > The dev build of React is slower than the prod build, due to all the extra logic for providing, for example, React's friendly console warnings (stripped away in the prod build). Therefore, the profiler only serves to indicate the _relatively_ expensive parts of your app.

17 -## General API

18 -

19 -The `Perf` object documented here is exposed as `React.addons.Perf` when using the `react-with-addons.js` build in development mode.

20 -

21 ### `Perf.start()` and `Perf.stop()`

22 Start/stop the measurement. The React operations in-between are recorded for analyses below. Operations that took an insignificant amount of time are ignored.

docs/docs/getting-started.md

+27 -7

@@ -12,9 +12,31 @@ The easiest way to start hacking on React is using the following JSFiddle Hello

12 * **[React JSFiddle](https://jsfiddle.net/reactjs/69z2wepo/)**

13 * [React JSFiddle without JSX](https://jsfiddle.net/reactjs/5vjqabv3/)

15 -## Starter Kit

15 +## Using React from npm

17 -Download the starter kit to get started.

17 +We recommend using React with a CommonJS module system like [browserify](http://browserify.org/) or [webpack](https://webpack.github.io/). Use the [`react`](https://www.npmjs.com/package/react) and [`react-dom`](https://www.npmjs.com/package/react-dom) npm packages.

18 +

19 +```js

20 +// main.js

21 +var React = require('react');

22 +var ReactDOM = require('react-dom');

23 +

24 +ReactDOM.render(

25 + <h1>Hello, world!</h1>,

26 + document.getElementById('example')

27 +);

28 +```

29 +

30 +To install React DOM and build your bundle after installing browserify:

31 +

32 +```sh

33 +$ npm install --save react react-dom

34 +$ browserify -t babelify main.js -o bundle.js

35 +```

36 +

37 +## Quick Start Without npm

38 +

39 +If you're not ready to use npm yet, you can download the starter kit which includes prebuilt copies of React and React DOM.

41 <div class="buttons-unit downloads">

42 <a href="/react/downloads/react-{{site.react_version}}.zip" class="button">

@@ -31,6 +53,7 @@ In the root directory of the starter kit, create a `helloworld.html` with the fo

53 <meta charset="UTF-8" />

54 <title>Hello React!</title>

55 <script src="build/react.js"></script>

56 + <script src="build/react-dom.js"></script>

57 <script src="https://cdnjs.cloudflare.com/ajax/libs/babel-core/5.8.23/browser.min.js"></script>

58 </head>

59 <body>

@@ -93,13 +116,14 @@ ReactDOM.render(

116

117 Update your HTML file as below:

118

96 -```html{7,11}

119 +```html{8,12}

120 <!DOCTYPE html>

121 <html>

122 <head>

123 <meta charset="UTF-8" />

124 <title>Hello React!</title>

125 <script src="build/react.js"></script>

126 + <script src="build/react-dom.js"></script>

127

128 </head>

129 <body>

@@ -109,10 +133,6 @@ Update your HTML file as below:

133 </html>

134 ```

135

112 -## Want CommonJS?

113 -

114 -If you want to use React with [browserify](http://browserify.org/), [webpack](https://webpack.github.io/), or another CommonJS-compatible module system, just use the [`react` npm package](https://www.npmjs.com/package/react). In addition, the `jsx` build tool can be integrated into most packaging systems (not just CommonJS) quite easily.

115 -

136 ## Next Steps

137

138 Check out [the tutorial](/react/docs/tutorial.html) and the other examples in the starter kit's `examples` directory to learn more.

docs/docs/ref-01-top-level-api.md

+68 -61

@@ -71,6 +71,65 @@ the type argument can be either an html tag name string (eg. 'div', 'span', etc)

71 `ReactClass`.

74 +### React.isValidElement

75 +

76 +```javascript

77 +boolean isValidElement(* object)

78 +```

79 +

80 +Verifies the object is a ReactElement.

81 +

82 +

83 +### React.DOM

84 +

85 +`React.DOM` provides convenience wrappers around `React.createElement` for DOM components. These should only be used when not using JSX. For example, `React.DOM.div(null, 'Hello World!')`

86 +

87 +

88 +### React.PropTypes

89 +

90 +`React.PropTypes` includes types that can be used with a component's `propTypes` object to validate props being passed to your components. For more information about `propTypes`, see [Reusable Components](/react/docs/reusable-components.html).

91 +

92 +

93 +### React.Children

94 +

95 +`React.Children` provides utilities for dealing with the `this.props.children` opaque data structure.

96 +

97 +#### React.Children.map

98 +

99 +```javascript

100 +object React.Children.map(object children, function fn [, object thisArg])

101 +```

102 +

103 +Invoke `fn` on every immediate child contained within `children` with `this` set to `thisArg`. If `children` is a nested object or array it will be traversed: `fn` will never be passed the container objects. If children is `null` or `undefined` returns `null` or `undefined` rather than an empty object.

104 +

105 +#### React.Children.forEach

106 +

107 +```javascript

108 +React.Children.forEach(object children, function fn [, object thisArg])

109 +```

110 +

111 +Like `React.Children.map()` but does not return an object.

112 +

113 +#### React.Children.count

114 +

115 +```javascript

116 +number React.Children.count(object children)

117 +```

118 +

119 +Return the total number of components in `children`, equal to the number of times that a callback passed to `map` or `forEach` would be invoked.

120 +

121 +#### React.Children.only

122 +

123 +```javascript

124 +object React.Children.only(object children)

125 +```

126 +

127 +Return the only child in `children`. Throws otherwise.

128 +

129 +## ReactDOM

130 +

131 +The `react-dom` package provides DOM-specific methods that can be used at the top level of your app and as an escape hatch to get outside of the React model if you need to.

132 +

133 ### ReactDOM.render

134

135 ```javascript

@@ -107,35 +166,6 @@ boolean unmountComponentAtNode(DOMElement container)

166 Remove a mounted React component from the DOM and clean up its event handlers and state. If no component was mounted in the container, calling this function does nothing. Returns `true` if a component was unmounted and `false` if there was no component to unmount.

167

168

110 -### ReactDOM.renderToString

111 -

112 -```javascript

113 -string renderToString(ReactElement element)

114 -```

115 -

116 -Render a ReactElement to its initial HTML. This should only be used on the server. React will return an HTML string. You can use this method to generate HTML on the server and send the markup down on the initial request for faster page loads and to allow search engines to crawl your pages for SEO purposes.

117 -

118 -If you call `ReactDOM.render()` on a node that already has this server-rendered markup, React will preserve it and only attach event handlers, allowing you to have a very performant first-load experience.

119 -

120 -

121 -### ReactDOM.renderToStaticMarkup

122 -

123 -```javascript

124 -string renderToStaticMarkup(ReactElement element)

125 -```

126 -

127 -Similar to `renderToString`, except this doesn't create extra DOM attributes such as `data-react-id`, that React uses internally. This is useful if you want to use React as a simple static page generator, as stripping away the extra attributes can save lots of bytes.

128 -

129 -

130 -### ReactDOM.isValidElement

131 -

132 -```javascript

133 -boolean isValidElement(* object)

134 -```

135 -

136 -Verifies the object is a ReactElement.

137 -

138 -

169 ### ReactDOM.findDOMNode

170

171 ```javascript

@@ -150,48 +180,25 @@ If this component has been mounted into the DOM, this returns the corresponding

180 >

181 > `findDOMNode()` only works on mounted components (that is, components that have been placed in the DOM). If you try to call this on a component that has not been mounted yet (like calling `findDOMNode()` in `render()` on a component that has yet to be created) an exception will be thrown.

182

153 -### React.DOM

154 -

155 -`React.DOM` provides convenience wrappers around `React.createElement` for DOM components. These should only be used when not using JSX. For example, `React.DOM.div(null, 'Hello World!')`

183 +## ReactDOMServer

184

185 +The `react-dom/server` package allows you to render your components on the server.

186

158 -### React.PropTypes

159 -

160 -`React.PropTypes` includes types that can be used with a component's `propTypes` object to validate props being passed to your components. For more information about `propTypes`, see [Reusable Components](/react/docs/reusable-components.html).

161 -

162 -

163 -### React.Children

164 -

165 -`React.Children` provides utilities for dealing with the `this.props.children` opaque data structure.

166 -

167 -#### React.Children.map

187 +### ReactDOMServer.renderToString

188

189 ```javascript

170 -object React.Children.map(object children, function fn [, object thisArg])

171 -```

172 -

173 -Invoke `fn` on every immediate child contained within `children` with `this` set to `thisArg`. If `children` is a nested object or array it will be traversed: `fn` will never be passed the container objects. If children is `null` or `undefined` returns `null` or `undefined` rather than an empty object.

174 -

175 -#### React.Children.forEach

176 -

177 -```javascript

178 -React.Children.forEach(object children, function fn [, object thisArg])

190 +string renderToString(ReactElement element)

191 ```

192

181 -Like `React.Children.map()` but does not return an object.

182 -

183 -#### React.Children.count

193 +Render a ReactElement to its initial HTML. This should only be used on the server. React will return an HTML string. You can use this method to generate HTML on the server and send the markup down on the initial request for faster page loads and to allow search engines to crawl your pages for SEO purposes.

194

185 -```javascript

186 -number React.Children.count(object children)

187 -```

195 +If you call `ReactDOM.render()` on a node that already has this server-rendered markup, React will preserve it and only attach event handlers, allowing you to have a very performant first-load experience.

196

189 -Return the total number of components in `children`, equal to the number of times that a callback passed to `map` or `forEach` would be invoked.

197

191 -#### React.Children.only

198 +### ReactDOMServer.renderToStaticMarkup

199

200 ```javascript

194 -object React.Children.only(object children)

201 +string renderToStaticMarkup(ReactElement element)

202 ```

203

197 -Return the only child in `children`. Throws otherwise.

204 +Similar to `renderToString`, except this doesn't create extra DOM attributes such as `data-react-id`, that React uses internally. This is useful if you want to use React as a simple static page generator, as stripping away the extra attributes can save lots of bytes.

docs/docs/tutorial.md

+5 -1

@@ -41,6 +41,7 @@ For this tutorial, we're going to make it as easy as possible. Included in the s

41 <meta charset="utf-8" />

42 <title>React Tutorial</title>

43 <script src="https://cdnjs.cloudflare.com/ajax/libs/react/{{site.react_version}}/react.js"></script>

44 + <script src="https://cdnjs.cloudflare.com/ajax/libs/react/{{site.react_version}}/react-dom.js"></script>

45 <script src="https://cdnjs.cloudflare.com/ajax/libs/babel-core/5.8.23/browser.min.js"></script>

46 <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>

47 </head>

@@ -126,6 +127,8 @@ You do not have to return basic HTML. You can return a tree of components that y

127

128 `ReactDOM.render()` instantiates the root component, starts the framework, and injects the markup into a raw DOM element, provided as the second argument.

129

130 +The `ReactDOM` module exposes DOM-specific methods, while `React` has the core tools shared by React on different platforms (e.g., [React Native](http://facebook.github.io/react-native/)).

131 +

132 ## Composing components

133

134 Let's build skeletons for `CommentList` and `CommentForm` which will, again, be simple `<div>`s. Add these two components to your file, keeping the existing `CommentBox` declaration and `ReactDOM.render` call:

@@ -220,12 +223,13 @@ Markdown is a simple way to format your text inline. For example, surrounding te

223

224 First, add the third-party library **marked** to your application. This is a JavaScript library which takes Markdown text and converts it to raw HTML. This requires a script tag in your head (which we have already included in the React playground):

225

223 -```html{8}

226 +```html{9}

227

228 <head>

229 <meta charset="utf-8" />

230 <title>React Tutorial</title>

231 <script src="https://cdnjs.cloudflare.com/ajax/libs/react/{{site.react_version}}/react.js"></script>

232 + <script src="https://cdnjs.cloudflare.com/ajax/libs/react/{{site.react_version}}/react-dom.js"></script>

233 <script src="https://cdnjs.cloudflare.com/ajax/libs/babel-core/5.8.23/browser.min.js"></script>

234 <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>

235 <script src="https://cdnjs.cloudflare.com/ajax/libs/marked/0.3.2/marked.min.js"></script>