From f7cf140607438481237e41feb0b7bc019ec9b6d4 Mon Sep 17 00:00:00 2001
From: Dan Abramov <dan.abramov@gmail.com>
Date: Wed, 4 Apr 2018 15:21:15 +0100
Subject: [PATCH] Tweak context docs (#766)

---
 .../context/forwarding-refs-fancy-button.js   |  2 +-
 .../context/higher-order-component-usage.js   |  2 -
 examples/context/motivation-problem.js        | 23 +++++----
 examples/context/motivation-solution.js       | 49 +++++++++++--------
 examples/context/multiple-contexts.js         | 45 ++++++++++-------
 .../context/reference-caveats-solution.js     |  1 +
 6 files changed, 68 insertions(+), 54 deletions(-)

diff --git a/examples/context/forwarding-refs-fancy-button.js b/examples/context/forwarding-refs-fancy-button.js
index 9e8f6d86..f3be5da8 100644
--- a/examples/context/forwarding-refs-fancy-button.js
+++ b/examples/context/forwarding-refs-fancy-button.js
@@ -8,7 +8,7 @@ class FancyButton extends React.Component {
 
 // Use context to pass the current "theme" to FancyButton.
 // Use forwardRef to pass refs to FancyButton as well.
-// highlight-range{1,3}
+// highlight-range{1,4}
 export default React.forwardRef((props, ref) => (
   <ThemeContext.Consumer>
     {theme => (
diff --git a/examples/context/higher-order-component-usage.js b/examples/context/higher-order-component-usage.js
index e9ebb22d..6f2757de 100644
--- a/examples/context/higher-order-component-usage.js
+++ b/examples/context/higher-order-component-usage.js
@@ -1,7 +1,5 @@
 function Button({theme, ...rest}) {
-  // highlight-next-line
   return <button className={theme} {...rest} />;
 }
 
-// highlight-next-line
 const ThemedButton = withTheme(Button);
diff --git a/examples/context/motivation-problem.js b/examples/context/motivation-problem.js
index e3c5b3f2..dd6ad9c9 100644
--- a/examples/context/motivation-problem.js
+++ b/examples/context/motivation-problem.js
@@ -1,13 +1,15 @@
-function ThemedButton(props) {
-  //highlight-range{1}
-  return <Button theme={props.theme} />;
+class App extends React.Component {
+  render() {
+    return <Toolbar theme="dark" />;
+  }
 }
 
-// An intermediate component
 function Toolbar(props) {
-  // highlight-range{1-2,5}
-  // The Toolbar component must take an extra theme prop
-  // and pass it to the ThemedButton
+  // highlight-range{1-4,7}
+  // The Toolbar component must take an extra "theme" prop
+  // and pass it to the ThemedButton. This can become painful
+  // if every single button in the app needs to know the theme
+  // because it would have to be passed through all components.
   return (
     <div>
       <ThemedButton theme={props.theme} />
@@ -15,9 +17,6 @@ function Toolbar(props) {
   );
 }
 
-class App extends React.Component {
-  render() {
-    // highlight-range{1}
-    return <Toolbar theme="dark" />;
-  }
+function ThemedButton(props) {
+  return <Button theme={props.theme} />;
 }
diff --git a/examples/context/motivation-solution.js b/examples/context/motivation-solution.js
index bfed9193..097b904f 100644
--- a/examples/context/motivation-solution.js
+++ b/examples/context/motivation-solution.js
@@ -1,18 +1,26 @@
-// Create a theme context, defaulting to light theme
-// highlight-next-line
+// highlight-range{1-4}
+// Context lets us pass a value deep into the component tree
+// without explicitly threading it through every component.
+// Create a context for the current theme (with "light" as the default).
 const ThemeContext = React.createContext('light');
 
-function ThemedButton(props) {
-  // highlight-range{1,3-5}
-  // The ThemedButton receives the theme from context
-  return (
-    <ThemeContext.Consumer>
-      {theme => <Button {...props} theme={theme} />}
-    </ThemeContext.Consumer>
-  );
+class App extends React.Component {
+  render() {
+    // highlight-range{1-3,5}
+    // Use a Provider to pass the current theme to the tree below.
+    // Any component can read it, no matter how deep it is.
+    // In this example, we're passing "dark" as the current value.
+    return (
+      <ThemeContext.Provider value="dark">
+        <Toolbar />
+      </ThemeContext.Provider>
+    );
+  }
 }
 
-// An intermediate component
+// highlight-range{1,2}
+// A component in the middle doesn't have to
+// pass the theme down explicitly anymore.
 function Toolbar(props) {
   return (
     <div>
@@ -21,13 +29,14 @@ function Toolbar(props) {
   );
 }
 
-class App extends React.Component {
-  render() {
-    // highlight-range{2,4}
-    return (
-      <ThemeContext.Provider value="dark">
-        <Toolbar />
-      </ThemeContext.Provider>
-    );
-  }
+function ThemedButton(props) {
+  // highlight-range{1-3,6}
+  // Use a Consumer to read the current theme context.
+  // React will find the closest theme Provider above and use its value.
+  // In this example, the current theme is "dark".
+  return (
+    <ThemeContext.Consumer>
+      {theme => <Button {...props} theme={theme} />}
+    </ThemeContext.Consumer>
+  );
 }
diff --git a/examples/context/multiple-contexts.js b/examples/context/multiple-contexts.js
index 236e45e7..3afeac78 100644
--- a/examples/context/multiple-contexts.js
+++ b/examples/context/multiple-contexts.js
@@ -1,27 +1,9 @@
 // Theme context, default to light theme
-// highlight-next-line
 const ThemeContext = React.createContext('light');
 
 // Signed-in user context
-// highlight-next-line
 const UserContext = React.createContext();
 
-// An intermediate component that depends on both contexts
-function Toolbar(props) {
-  // highlight-range{2-10}
-  return (
-    <ThemeContext.Consumer>
-      {theme => (
-        <UserContext.Consumer>
-          {user => (
-            <ProfilePage user={user} theme={theme} />
-          )}
-        </UserContext.Consumer>
-      )}
-    </ThemeContext.Consumer>
-  );
-}
-
 class App extends React.Component {
   render() {
     const {signedInUser, theme} = this.props;
@@ -31,9 +13,34 @@ class App extends React.Component {
     return (
       <ThemeContext.Provider value={theme}>
         <UserContext.Provider value={signedInUser}>
-          <Toolbar />
+          <Layout />
         </UserContext.Provider>
       </ThemeContext.Provider>
     );
   }
 }
+
+function Layout() {
+  return (
+    <div>
+      <Sidebar />
+      <Content />
+    </div>
+  );
+}
+
+// A component may consume multiple contexts
+function Content() {
+  // highlight-range{2-10}
+  return (
+    <ThemeContext.Consumer>
+      {theme => (
+        <UserContext.Consumer>
+          {user => (
+            <ProfilePage user={user} theme={theme} />
+          )}
+        </UserContext.Consumer>
+      )}
+    </ThemeContext.Consumer>
+  );
+}
diff --git a/examples/context/reference-caveats-solution.js b/examples/context/reference-caveats-solution.js
index 9196a4c7..deefabd4 100644
--- a/examples/context/reference-caveats-solution.js
+++ b/examples/context/reference-caveats-solution.js
@@ -1,5 +1,6 @@
 class App extends React.Component {
   constructor(props) {
+    super(props);
     // highlight-range{2}
     this.state = {
       value: {something: 'something'},