Merge branch 'master' into add-docs-for-multiple-select

.babelrc

@@ -1,4 +1,41 @@
 {
-  "presets": ['react', 'es2015', 'stage-1'],
-  "plugins": ['add-module-exports']
-}
+  "presets": [
+    [
+      "@babel/preset-env",
+      {
+        "loose": true,
+        "modules": false,
+        "useBuiltIns": "usage",
+        "shippedProposals": true,
+        "targets": {
+          "browsers": [">0.25%", "not dead"],
+        }
+      }
+    ],
+    [
+      "@babel/preset-react",
+      {
+        "useBuiltIns": true,
+        "pragma": "React.createElement",
+      }
+    ],
+    "@babel/flow"
+  ],
+  "plugins": [
+    [
+      "@babel/plugin-proposal-class-properties",
+      {
+        "loose": true
+      }
+    ],
+    "@babel/plugin-syntax-dynamic-import",
+    "babel-plugin-macros",
+    [
+      "@babel/plugin-transform-runtime",
+      {
+        "helpers": true,
+        "regenerator": true
+      }
+    ]
+  ]
+}

.circleci/config.yml

@@ -2,21 +2,19 @@ version: 2
 jobs:
   build:
     docker:
-      - image: circleci/node:latest
+      - image: circleci/node:8
     steps:
       - checkout
       - restore_cache:
           keys:
-          - dependencies-{{ checksum "package.json" }}
-          # fallback to using the latest cache if no exact match is found
-          - dependencies-
+          - dependencies-{{ checksum "yarn.lock" }}
       - run:
           name: Install
-          command: yarn install
+          command: yarn install --pure-lockfile
       - save_cache:
           paths:
             - node_modules
-          key: dependencies-{{ checksum "package.json" }}
+          key: dependencies-{{ checksum "yarn.lock" }}
       - run:
           name: Check Prettier, ESLint, Flow
           command: yarn ci-check

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,9 +1,13 @@
+
+
+<!--
+
 Thank you for the PR! Contributors like you keep React awesome!
 
 Please see the Contribution Guide for guidelines:
 
 https://github.com/reactjs/reactjs.org/blob/master/CONTRIBUTING.md
 
-If your PR references an existing issue, please add the issue number below:
+If your PR references an existing issue, please add the issue number below
 
-#<Issue>
+-->

.gitignore

@@ -3,3 +3,4 @@
 .idea
 node_modules
 public
+yarn-error.log

.nvmrc

@@ -1 +1 @@
-8.4
+lts/carbon

CONTRIBUTING.md

@@ -14,13 +14,15 @@ so that you can understand what actions will and will not be tolerated.
 
 The documentation is divided into sections to cater to different learning styles and use cases. When editing an article, try to match the surrounding text in tone and style. When creating a new article, try to match the tone of the other articles in the same section. Learn about the motivation behind each section below.
 
+**[Installation](https://reactjs.org/docs/getting-started.html)** gives an overview of the docs, and demonstrates two different ways to use it: either as a simple `<script>` tag on the page, or as part of a complex JavaScript toolchain.
+
 **[Tutorial](https://reactjs.org/tutorial/tutorial.html)** is relatively informal, and is designed for people who prefer a hands-on approach to learning, and can tolerate skipping theory in favor of practice. Its goal is to give the reader a feel for a typical React workflow rather than to explain fundamentals in detail. Here we focus on *what* to do and spend less time on *how* or *why* we did it. It is extremely important to do a lot of hand-holding and unambiguously describe every single change. It should be possible for a beginner to mechanically follow every instruction, and still get to a working tic-tac-toe game.
 
-**[Quick Start](https://reactjs.org/docs/hello-world.html)** is designed to introduce fundamental concepts in a step-by-step way. Each individual article in Quick Start builds on the knowledge from the previous ones, so make sure not to add any "cyclical dependencies" between them. It is important that the reader can start with the first article and work their way to the last Quick Start article without ever having to "look ahead" for a definition. This explains some ordering choices (e.g. that state is explained before events, or that "thinking in React" doesn't use refs). Quick Start also serves as a reference manual for React concepts, so it is important to be very strict about their definitions and relationships between them. This is, for example, why we introduce elements before components. Resist adding too much detail to Quick Start articles. They intentionally don't cover all corner cases, and focus on establishing firm foundations.
+**[Main Concepts](https://reactjs.org/docs/hello-world.html)** is designed to introduce fundamental concepts in a step-by-step way. Each individual article in Main Concepts builds on the knowledge from the previous ones, so make sure not to add any "cyclical dependencies" between them. It is important that the reader can start with the first article and work their way to the last Main Concepts article without ever having to "look ahead" for a definition. This explains some ordering choices (e.g. that state is explained before events, or that "thinking in React" doesn't use refs). Main Concepts also serves as a reference manual for React concepts, so it is important to be very strict about their definitions and relationships between them. This is, for example, why we introduce elements before components. Resist adding too much detail to Main Concepts articles. They intentionally don't cover all corner cases, and focus on establishing firm foundations.
 
 **[Advanced Guides](https://reactjs.org/docs/jsx-in-depth.html)** are deep dives into topics that aren't essential for a beginner developer but that everyone bumps into sooner or later. They don't have a specific order, and target more experienced developers. If you have a set of recipes fitting a particular use case, and those recipes aren't opinionated (most React users would agree on them), this is the place to add them.
 
-**[Reference](https://reactjs.org/docs/react-api.html)** is organized by APIs rather than concepts. It is intended to be exhaustive. Any corner cases or recommendations that were skipped for brevity in Quick Start or Advanced Guides should be mentioned in the reference documentation for the corresponding APIs.
+**[Reference](https://reactjs.org/docs/react-api.html)** is organized by APIs rather than concepts. It is intended to be exhaustive. Any corner cases or recommendations that were skipped for brevity in Main Concepts or Advanced Guides should be mentioned in the reference documentation for the corresponding APIs.
 
 **[Contributing](https://reactjs.org/docs/how-to-contribute.html)** should stay up-to-date and be friendly to relatively experienced developers.
 

README.md

@@ -7,10 +7,10 @@ This repo contains the source code and documentation powering [reactjs.org](http
 ### Prerequisites
 
 1. Git
-1. Node: install version 8.4 or greater
+1. Node: any 8.x version starting with 8.4.0 or greater
 1. Yarn: See [Yarn website for installation instructions](https://yarnpkg.com/lang/en/docs/install/)
-1. A clone of the [reactjs.org repo](https://github.com/reactjs/reactjs.org) on your local machine
 1. A fork of the repo (for any contributions)
+1. A clone of the [reactjs.org repo](https://github.com/reactjs/reactjs.org) on your local machine
 
 ### Installation
 
@@ -24,6 +24,10 @@ This repo contains the source code and documentation powering [reactjs.org](http
 
 ## Contributing
 
+### Guidelines
+
+The documentation is divided into several sections with a different tone and purpose. If you plan to write more than a few sentences, you might find it helpful to get familiar with the [contributing guidelines](https://github.com/reactjs/reactjs.org/blob/master/CONTRIBUTING.md#guidelines-for-text) for the appropriate sections.
+
 ### Create a branch
 
 1. `git checkout master` from any folder in your local `reactjs.org` repository
@@ -51,6 +55,12 @@ This repo contains the source code and documentation powering [reactjs.org](http
 1. Follow GitHub's instructions.
 1. If possible, include screenshots of visual changes. A Netlify build will also be automatically created once you make your PR so other people can see your change.
 
+## Translation
+
+If you are interesting in translating `reactjs.org`, please join the Crowdin.
+
+* [Crowdin - React](https://crowdin.com/project/react)
+
 ## Troubleshooting
 
 - `yarn reset` to clear the local cache

content/authors.yml

@@ -69,7 +69,7 @@ sebmarkbage:
   url: https://twitter.com/sebmarkbage
 sophiebits:
   name: Sophie Alpert
-  url: https://sophiealpert.com
+  url: https://sophiebits.com/
 steveluscher:
   name: Steven Luscher
   url: https://twitter.com/steveluscher

content/blog/2013-06-05-why-react.md

@@ -80,7 +80,7 @@ some pretty cool things with it:
   (including IE8) and automatically use
   [event delegation](http://davidwalsh.name/event-delegate).
 
-Head on over to https://reactjs.org to check out what we have
+Head on over to [https://reactjs.org](https://reactjs.org) to check out what we have
 built. Our documentation is geared towards building apps with the framework,
 but if you are interested in the nuts and bolts
 [get in touch](/support.html) with us!

content/blog/2014-10-14-introducing-react-elements.md

@@ -1,7 +1,8 @@
 ---
 title: "Introducing React Elements"
 author: [sebmarkbage]
-redirect_from: "blog/2014/10/14/introducting-react-elements.html"
+redirect_from:
+  - "blog/2014/10/14/introducting-react-elements.html"
 ---
 
 The upcoming React 0.12 tweaks some APIs to get us close to the final 1.0 API. This release is all about setting us up for making the `ReactElement` type really FAST, [jest unit testing](https://facebook.github.io/jest/) easier, making classes simpler (in preparation for ES6 classes) and better integration with third-party languages!

content/blog/2015-12-16-ismounted-antipattern.md

@@ -43,7 +43,7 @@ If you use ES6 promises, you may need to wrap your promise in order to make it c
 
 ```js
 const cancelablePromise = makeCancelable(
-  new Promise(r => component.setState({...}}))
+  new Promise(r => component.setState({...}))
 );
 
 cancelablePromise

content/blog/2016-07-11-introducing-reacts-error-code-system.md

@@ -13,6 +13,6 @@ In order to make debugging in production easier, we're introducing an Error Code
 
 While we hope you don't see errors often, you can see how it works [here](/docs/error-decoder.html?invariant=109&args[]=Foo). This is what the same error from above will look like:
 
-> Minified React error #109; visit https://reactjs.org/docs/error-decoder.html?invariant=109&args[]=Foo for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
+> Minified React error #109; visit [https://reactjs.org/docs/error-decoder.html?invariant=109&args[]=Foo](/docs/error-decoder.html?invariant=109&args[]=Foo) for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
 
 We do this so that the developer experience is as good as possible, while also keeping the production bundle size as small as possible. This feature shouldn't require any changes on your side — use the `min.js` files in production or bundle your application code with `process.env.NODE_ENV === 'production'` and you should be good to go!

content/blog/2017-09-25-react-v15.6.2.md

@@ -34,7 +34,7 @@ In case you don't use a bundler, we also provide pre-built bundles in the npm pa
   Minified build for production: [react/dist/react.min.js](https://unpkg.com/react@15.6.2/dist/react.min.js)<br/>
 * **React with Add-Ons**<br/>
   Dev build with warnings: [react/dist/react-with-addons.js](https://unpkg.com/react@15.6.2/dist/react-with-addons.js)<br/>
-  Minified build for production: [react/dist/react-with-addons.min.js](https://unpkg.com/react@15.5.0/dist/react-with-addons.min.js)<br/>
+  Minified build for production: [react/dist/react-with-addons.min.js](https://unpkg.com/react@15.6.2/dist/react-with-addons.min.js)<br/>
 * **React DOM** (include React in the page before React DOM)<br/>
   Dev build with warnings: [react-dom/dist/react-dom.js](https://unpkg.com/react-dom@15.6.2/dist/react-dom.js)<br/>
   Minified build for production: [react-dom/dist/react-dom.min.js](https://unpkg.com/react-dom@15.6.2/dist/react-dom.min.js)<br/>

content/blog/2017-11-28-react-v16.2.0-fragment-support.md

@@ -50,7 +50,7 @@ render() {
 }
 ```
 
-To address this limitation, React 16.0 added support for [returning an array of elements from a component's `render` method](https://reactjs.org/blog/2017/09/26/react-v16.0.html#new-render-return-types-fragments-and-strings). Instead of wrapping the children in a DOM element, you can put them into an array:
+To address this limitation, React 16.0 added support for [returning an array of elements from a component's `render` method](/blog/2017/09/26/react-v16.0.html#new-render-return-types-fragments-and-strings). Instead of wrapping the children in a DOM element, you can put them into an array:
 
 ```jsx
 render() {
@@ -67,7 +67,7 @@ render() {
 However, this has some confusing differences from normal JSX:
 
 - Children in an array must be separated by commas.
-- Children in an array must have a key to prevent React's [key warning](https://reactjs.org/docs/lists-and-keys.html#keys).
+- Children in an array must have a key to prevent React's [key warning](/docs/lists-and-keys.html#keys).
 - Strings must be wrapped in quotes.
 
 To provide a more consistent authoring experience for fragments, React now provides a first-class `Fragment` component that can be used in place of arrays.
@@ -225,7 +225,7 @@ to update Flow to the latest version.
 
 ### Prettier
 
-[Prettier](https://github.com/prettier/prettier) will have support for fragments in their upcoming [1.9 release](https://github.com/prettier/prettier/pull/3237).
+[Prettier](https://github.com/prettier/prettier) added support for fragments in their [1.9 release](https://prettier.io/blog/2017/12/05/1.9.0.html#jsx-fragment-syntax-3237-https-githubcom-prettier-prettier-pull-3237-by-duailibe-https-githubcom-duailibe).
 
 ### ESLint
 
@@ -263,7 +263,7 @@ It may take a while for fragment syntax to be supported in your text editor. Ple
 
 #### TypeScript Editor Support
 
-If you're a TypeScript user -- great news! Editor support for JSX fragments is already available in [Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48593), [Visual Studio 2017](https://www.microsoft.com/en-us/download/details.aspx?id=55258), and [Sublime Text via Package Control](https://packagecontrol.io/packages/TypeScript). Visual Studio Code will be updated soon, but [can be configured to use TypeScript 2.6.2 and later](https://code.visualstudio.com/Docs/languages/typescript#_using-newer-typescript-versions).
+If you're a TypeScript user -- great news! Editor support for JSX fragments is already available in [Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48593), [Visual Studio 2017](https://www.microsoft.com/en-us/download/details.aspx?id=55258), [Visual Studio Code](https://code.visualstudio.com/updates/v1_19#_jsx-fragment-syntax) and [Sublime Text via Package Control](https://packagecontrol.io/packages/TypeScript).
 
 ### Other Tools
 

content/blog/2018-03-01-sneak-peek-beyond-react-16.md

@@ -0,0 +1,24 @@
+---
+title: "Sneak Peek: Beyond React 16"
+author: [sophiebits]
+---
+
+[Dan Abramov](https://twitter.com/dan_abramov) from our team just spoke at [JSConf Iceland 2018](https://2018.jsconf.is/) with a preview of some new features we've been working on in React. The talk opens with a question: "With vast differences in computing power and network speed, how do we deliver the best user experience for everyone?"
+
+Here's the video courtesy of JSConf Iceland:
+
+<br>
+
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/nLF0n9SACd4?rel=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
+
+I think you'll enjoy the talk more if you stop reading here and just watch the video. If you don't have time to watch, a (very) brief summary follows.
+
+## About the Two Demos
+
+On the first demo, Dan says: "We've built a generic way to ensure that high-priority updates don't get blocked by a low-priority update, called **time slicing**. If my device is fast enough, it feels almost like it's synchronous; if my device is slow, the app still feels responsive. It adapts to the device thanks to the [requestIdleCallback](https://developers.google.com/web/updates/2015/08/using-requestidlecallback) API. Notice that only the final state was displayed; the rendered screen is always consistent and we don't see visual artifacts of slow rendering causing a janky user experience."
+
+On the second demo, Dan explains: "We've built a generic way for components to suspend rendering while they load async data, which we call **suspense**. You can pause any state update until the data is ready, and you can add async loading to any component deep in the tree without plumbing all the props and state through your app and hoisting the logic. On a fast network, updates appear very fluid and instantaneous without a jarring cascade of spinners that appear and disappear. On a slow network, you can intentionally design which loading states the user should see and how granular or coarse they should be, instead of showing spinners based on how the code is written. The app stays responsive throughout."
+
+"Importantly, this is still the React you know. This is still the declarative component paradigm that you probably like about React."
+
+We can't wait to release these new async rendering features later this year. Follow this blog and [@reactjs on Twitter](https://twitter.com/reactjs) for updates.