Added example for updating nested context consumer (#776)

* Added an example showing how to update the context from inside a (deeply) nested component

* Wrap comments

* Wrap comments

* Tweak wording

* Prettier

* Prettier

* Typo: "funtion" -> "function"

content/docs/context.md

@@ -15,6 +15,7 @@ In a typical React application, data is passed top-down (parent to child) via pr
   - [Consumer](#consumer)
 - [Examples](#examples)
   - [Dynamic Context](#dynamic-context)
+  - [Updating Context from a Nested Component](#updating-context-from-a-nested-component)
   - [Consuming Multiple Contexts](#consuming-multiple-contexts)
   - [Accessing Context in Lifecycle Methods](#accessing-context-in-lifecycle-methods)
   - [Consuming Context with a HOC](#consuming-context-with-a-hoc)
@@ -92,6 +93,16 @@ A more complex example with dynamic values for the theme:
 **app.js**
 `embed:context/theme-detailed-app.js`
 
+### Updating Context from a Nested Component
+
+It is often necessary to update the context from a component that is nested somewhere deeply in the component tree. In this case you can pass a function down through the context to allow consumers to update the context:
+
+**theme-toggler-button.js**
+`embed:context/updating-nested-context-theme-toggler-button.js`
+
+**app.js**
+`embed:context/updating-nested-context-app.js`
+
 ### Consuming Multiple Contexts
 
 To keep context re-rendering fast, React needs to make each context consumer a separate node in the tree. 

examples/context/updating-nested-context-app.js

@@ -0,0 +1,45 @@
+import {ThemeContext, themes} from './theme-context';
+import ThemeTogglerButton from './theme-toggler-button';
+
+class App extends React.Component {
+  constructor(props) {
+    super(props);
+
+    this.toggleTheme = () => {
+      this.setState(state => ({
+        theme:
+          state.theme === themes.dark
+            ? themes.light
+            : themes.dark,
+      }));
+    };
+
+    // highlight-range{1-2,5}
+    // State also contains the updater function so it will
+    // be passed down into the context provider
+    this.state = {
+      theme: themes.light,
+      toggleTheme: this.toggleTheme,
+    };
+  }
+
+  render() {
+    // highlight-range{1,3}
+    // The entire state is passed to the provider
+    return (
+      <ThemeContext.Provider value={this.state}>
+        <Content />
+      </ThemeContext.Provider>
+    );
+  }
+}
+
+function Content() {
+  return (
+    <div>
+      <ThemeTogglerButton />
+    </div>
+  );
+}
+
+ReactDOM.render(<App />, document.root);

examples/context/updating-nested-context-theme-toggler-button.js

@@ -0,0 +1,20 @@
+import {ThemeContext} from './theme-context';
+
+function ThemeTogglerButton() {
+  // highlight-range{1-2,5}
+  // The Theme Toggler Button receives not only the theme
+  // but also a toggleTheme function from the context
+  return (
+    <ThemeContext.Consumer>
+      {({theme, toggleTheme}) => (
+        <button
+          onClick={toggleTheme}
+          style={{backgroundColor: theme.background}}>
+          Toggle Theme
+        </button>
+      )}
+    </ThemeContext.Consumer>
+  );
+}
+
+export default ThemeTogglerButton;