Rephrase and reorganize

- Move Motivation to top @bvaughn
- Copy in some Motivation text from the RFC for the intro para
- Update examples
  - Remove state from simple example
  - Remove "random color" example;
  just toggle a theme variable instead
- Update highlights

content/docs/context.md

@@ -6,6 +6,9 @@ permalink: docs/context.html
 
 Context provides a way to pass data through the component tree without having to pass props down manually at every level.
 
+Typically, data in a React application is passed top-down (parent to child) via props. But sometimes it's useful to pass values through multiple levels without adding props to every intermediate component. Examples include a language preference, or a UI theme. Many components may rely on those but you don't want to have to pass a locale prop and a theme prop through every level of the tree.
+
+- [Motivation](#motivation)
 - [API](#api)
   - [React.createContext](#reactcreatecontext)
   - [Provider](#provider)
@@ -13,21 +16,26 @@ Context provides a way to pass data through the component tree without having to
 - [Examples](#examples)
   - [Static Context](#static-context)
   - [Dynamic Context](#dynamic-context)
-- [Motivation](#motivation)
 - [Legacy API](#legacy-api)
 
+
+## Motivation
+
+Context is designed to relieve the pain of passing props down through a deeply nested component tree. For example, in the code below we manually thread through a color prop in order to style the Button and Message components. Using context, we can avoid passing props through intermediate elements.
+
+`embed:context/motivation.js`
+
 ## API
 
 ### `React.createContext`
 
 ```js
-const {Provider, Consumer} = React.createContext([default]);
+const {Provider, Consumer} = React.createContext(defaultValue);
 ```
 
 Creates a `{ Provider, Consumer }` pair.
 
-Takes one argument, the default context that Consumers will receive when they don't have a matching Provider.
-
+Optionally accepts a default value to be passed to Consumers without a Provider ancestor.
 
 ### `Provider`
 
@@ -37,7 +45,7 @@ Takes one argument, the default context that Consumers will receive when they do
 
 A React component that allows Consumers to subscribe to context changes.
 
-Takes one prop, `value`, which will be passed to the [render prop](/docs/render-props.html) of child Consumers for the matching context anywhere in the component tree. One Provider can be connected to many Consumers.
+Accepts a `value` prop to be passed to Consumers that are descendants of this Provider. One Provider can be connected to many Consumers. Providers can be nested to override values deeper within the tree.
 
 ### `Consumer`
 
@@ -47,12 +55,12 @@ Takes one prop, `value`, which will be passed to the [render prop](/docs/render-
 </Consumer>
 ```
 
-A React component that subscribes to context changes. 
+A React component that subscribes to context changes.
 
-Takes a function as the `children` prop that receives the `value` prop of the matching Provider. This function will be called whenever the Provider's value is updated.
+Requires a [function as a child](/docs/render-props.html#using-props-other-than-render). This function receives the current context value and returns a React node, and will be called whenever the Provider's value is updated.
 
 > Note:
->
+> 
 > For more information about this pattern, see [render props](/docs/render-props.html).
 
 ## Examples
@@ -76,49 +84,8 @@ A more complex example with dynamic values for the theme:
 **app.js**
 `embed:context/theme-detailed-app.js`
 
-## Motivation
-
-Context is designed to relieve the pain of passing props down through a deeply nested component tree. For example, in the code below we manually thread through a color prop in order to style the Button and Message components. Using context, we can avoid passing props through intermediate elements.
-
-```js
-class Button extends React.Component {
-  render() {
-    return (
-      <button style={{background: this.props.color}}>
-        {this.props.children}
-      </button>
-    );
-  }
-}
-
-class Message extends React.Component {
-  render() {
-    return (
-      <div>
-        {/*
-          The Message component must take `color` as as prop to pass it to the
-          Button. Using context, the Button could connect to the color context
-          on its own.
-        */} 
-        {this.props.text} <Button color={this.props.color}>Delete</Button>
-      </div>
-    );
-  }
-}
-
-class MessageList extends React.Component {
-  render() {
-    const color = "purple";
-    const children = this.props.messages.map((message) =>
-      <Message text={message.text} color={color} />
-    );
-    return <div>{children}</div>;
-  }
-}
-```
-
 ## Legacy API
 
-> The legacy context API was deprecated in React 16.3
+> The legacy context API was deprecated in React 16.3 and will be removed in version 17.
 > 
 > React previously shipped with an experimental context API. The old API will be supported in all 16.x releases, but applications using it should migrate to the new version. Read the [legacy context docs here](/docs/legacy-context.html).

content/docs/legacy-context.md

@@ -4,9 +4,11 @@ title: Legacy Context
 permalink: docs/legacy-context.html
 ---
 
-> This API is deprecated as of React 16.3.
-> 
-> The API will be supported in all 16.x releases, but applications using it should migrate to the [new API](/docs/context.html). The experimental API lacked a safe mechanism to update context. Version 16.3 introduced a new context API that is more efficient and supports both static type checking and deep updates.
+> Deprecation Warning
+>
+> The legacy API has been deprecated and will be removed in version 17.
+> Use the [new context API](/docs/context.html) introduced with version 16.3.
+> The legacy API will continue working for all 16.x releases.
 
 ## How To Use Context
 

examples/context/motivation.js

@@ -0,0 +1,33 @@
+class Button extends React.Component {
+  render() {
+    return (
+      <button style={{background: this.props.color}}>
+        {this.props.children}
+      </button>
+    );
+  }
+}
+
+class Message extends React.Component {
+  render() {
+    // highlight-range{1-3}
+    // The Message component must take `color` as as prop to pass it 
+    // to the Button. Using context, the Button could connect to the 
+    // color context on its own.
+    return (
+      <div>
+        {this.props.text} <Button color={this.props.color}>Delete</Button>
+      </div>
+    );
+  }
+}
+
+class MessageList extends React.Component {
+  render() {
+    const color = "purple";
+    const children = this.props.messages.map((message) =>
+      <Message text={message.text} color={color} />
+    );
+    return <div>{children}</div>;
+  }
+}

examples/context/theme-detailed-app.js

@@ -1,34 +1,27 @@
-import ThemeContext from './theme-context';
+import ThemeContext, {themes} from './theme-context';
 import ThemedButton from './button';
 
 class App extends React.Component {
   state = {
-    theme: {
-      highlight: 'blue',
-      accent: 'purple',
-    },
+    theme: themes.light,
   };
 
-  changeHighlightColor = () => {
-    const colors = ['red', 'blue', 'green'];
-    const randomColor =
-      colors[Math.floor(Math.random() * 3)];
-    this.setState({
-      theme: {
-        ...this.state.theme,
-        highlight: randomColor,
-      },
-    });
+  toggleTheme = () => {
+    this.setState(state => ({
+      theme:
+        state.theme === themes.dark
+          ? themes.light
+          : themes.dark,
+    }));
   };
 
   render() {
+    //highlight-range{2,6}
     return (
       <ThemeContext.Provider value={this.state.theme}>
-        <div>
-          <ThemedButton onClick={this.changeHighlightColor}>
-            Change Theme
-          </ThemedButton>
-        </div>
+        <ThemedButton onClick={this.toggleTheme}>
+          Change Theme
+        </ThemedButton>
       </ThemeContext.Provider>
     );
   }

examples/context/theme-detailed-theme-context.js

@@ -1,5 +1,15 @@
-const defaultTheme = {highlight: 'blue', accent: 'purple'};
+export const themes = {
+  light: {
+    foreground: '#ffffff',
+    background: '#222222',
+  },
+  dark: {
+    foreground: '#000000',
+    background: '#eeeeee',
+  },
+};
 
-const ThemeContext = React.createContext(defaultTheme);
+// highlight-next-line
+const ThemeContext = React.createContext(themes.dark);
 
 export default ThemeContext;

examples/context/theme-detailed-themed-button.js

@@ -1,13 +1,14 @@
 import ThemeContext from './theme-context';
 
 class ThemedButton extends React.Component {
+  // highlight-range{3-10}
   render() {
     return (
       <ThemeContext.Consumer>
         {theme => (
           <button
             {...this.props}
-            style={{backgroundColor: theme.highlight}}
+            style={{backgroundColor: theme.background}}
           />
         )}
       </ThemeContext.Consumer>

examples/context/theme-example.js

@@ -1,14 +1,12 @@
-const defaultTheme = 'light';
+// Create a theme context, defaulting to light theme
 // highlight-next-line
-const ThemeContext = React.createContext(defaultTheme);
+const ThemeContext = React.createContext('light');
 
 class ThemeProvider extends React.Component {
-  state = {theme: 'light'};
-
   render() {
     // highlight-range{2-4}
     return (
-      <ThemeContext.Provider value={this.state.theme}>
+      <ThemeContext.Provider value={this.props.theme}>
         {this.props.children}
       </ThemeContext.Provider>
     );
@@ -26,17 +24,32 @@ class ThemedButton extends React.Component {
   }
 }
 
-class App extends React.Component {
+const SomeComponent = props => {
+  // The ThemedButton receives the theme from context;
+  // SomeComponent does not need to know about it
   // highlight-range{3}
-  // highlight-range{5}
-  // highlight-range{7}
+  return (
+    <div>
+      <ThemedButton />
+    </div>
+  );
+};
+
+class App extends React.Component {
   render() {
+    // The ThemedButton button inside the ThemeProvider
+    // uses the dark theme while the one outside uses the
+    // default light theme
+    // highlight-range{3-5,7}
     return (
-      <ThemeProvider>
-        <SomeComponent>
+      <div>
+        <ThemeProvider theme="dark">
+          <SomeComponent />
+        </ThemeProvider>
+        <div>
           <ThemedButton />
-        </SomeComponent>
-      </ThemeProvider>
+        </div>
+      </div>
     );
   }
 }