Add docs for new Context API #665

alexkrolick · 2018-03-06T08:17:03Z

Rendered

reactjs-bot · 2018-03-06T08:20:28Z

Deploy preview for reactjs ready!

Built with commit b49f99b

https://deploy-preview-665--reactjs.netlify.com

bvaughn

Some high-level thoughts about organization.

Thanks for kicking off this effort!

bvaughn · 2018-03-20T20:46:30Z

content/docs/context.md


-If you aren't familiar with state management libraries like [Redux](https://github.com/reactjs/redux) or [MobX](https://github.com/mobxjs/mobx), don't use context. For many practical applications, these libraries and their React bindings are a good choice for managing state that is relevant to many components. It is far more likely that Redux is the right solution to your problem than that context is the right solution.
+## Experimental API (Deprecated in React 16.3)


Maybe this could be broken out into its own "Legacy context" page (e.g. content/docs/legacy-context.md) that we link to from this page- but we don't show on the side bar anywhere?

bvaughn · 2018-03-20T20:47:11Z

content/docs/context.md

+
+## Using Context
+
+Here is an example illustrating how you might inject a "theme" using context:


I prefer the introductory sequence from the old "How to Use Context" section more because of how it setup the problem. "Let's say you have this code and you want to do X. Here's how you could use the context API to do this." rather than "Here's a code snippet"

I would also suggesting putting this down under the "Typical Usage" header. I think the API should be first on this page.

I think it's confusing how the old example leads with a large codeblock illustrating non-context APIs. Maybe we can invert the order to highlight the context way before the prop-drilling way?

Moving the API section to the top makes sense.

I think we could maybe make the initial code block shorter, but I think it's useful to present APIs in the form of "Here is a scenario. How would you solve it? You can solve it using this API."

Also reduce spacing between ul/li tags

alexkrolick · 2018-03-21T01:18:42Z

src/theme.js

@@ -336,7 +336,7 @@ const sharedStyles = {
      },

      '& li': {
-        marginTop: 20,
+        marginTop: 10,


Reduces spacing between list elements:

After:

Before:

Don't need to merge this, but probably would want to kill the table of contents links if we keep the larger padding.

I think it looks nice.

alexkrolick · 2018-03-21T01:20:32Z

@bvaughn broke out legacy-context.md and reintroduced the props drilling example under "Motivation"

bvaughn

Left some thoughts! Some nits and some suggestions.

Thanks!

bvaughn · 2018-03-21T05:07:23Z

content/docs/context.md

+### `React.createContext`
+
+```js
+const {Provider, Consumer} = React.createContext([default]);


Why [default] ? (Why the array syntax?) Suggestion:

const {Provider, Consumer} = React.createContext(defaultValue);

I was thinking [] indicated optional arguments. Replacing it with a text note is fine; it's not a real type signature or anything.

Gotcha. I don't think thats' what "[]" implies to me. 👍

bvaughn · 2018-03-21T05:08:16Z

content/docs/context.md

+
+Creates a `{ Provider, Consumer }` pair.
+
+Takes one argument, the default context that Consumers will receive when they don't have a matching Provider.


Suggestion:

Accepts an optional default value to be passed to Consumers without a Provider ancestor.

bvaughn · 2018-03-21T05:11:04Z

content/docs/context.md

+
+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.


Suggestion:

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.

bvaughn · 2018-03-21T05:14:28Z

content/docs/context.md

-You can do this directly in React with the powerful "context" API.
+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.


Suggestion:

Requires a function as a child. This function receives the current context value and returns a React node. This function will be called whenever the Provider's value is updated.

bvaughn · 2018-03-21T05:16:26Z

examples/context/theme-example.js

@@ -0,0 +1,42 @@
+const defaultTheme = 'light';
+// highlight-next-line
+const ThemeContext = React.createContext(defaultTheme);


Nit: Maybe get rid of defaultTheme variable in favor of a comment?

// Initial context with a default value of "light" (theme) const ThemeContext = React.createContext('light');

bvaughn · 2018-03-21T05:19:16Z

examples/context/theme-detailed-app.js

+  state = {
+    theme: {
+      highlight: 'blue',
+      accent: 'purple',


nit: It's also a little weird that we have a default value and state with the same value. People might not understand why default value exists if we always do this.

What's a good application use case for the default value? The RFC example just says "to ensure type correctness".

That's a good observation. I wasn't considering the type-correctness angle. 👍

I was thinking it would be nice for the docs to highlight, in one of the examples, that the default value gets passed to a Consumer if there is no Provider ancestor.

bvaughn · 2018-03-21T05:20:15Z

content/docs/context.md

+          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 block comment within JSX does not read very well. Move it into the render function as just inline comments?

bvaughn · 2018-03-21T05:21:10Z

content/docs/context.md


-Suppose you have a structure like:
+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.


I'm still not a fan of this sequencing. We show motivation after we show usage examples. That feels backwards to me. I think it would be better to present a problem, and then how to solve it using Context. Step by step.

bvaughn · 2018-03-21T05:22:57Z

content/docs/legacy-context.md

+permalink: docs/legacy-context.html
+---
+
+> This API is deprecated as of React 16.3.


This should clarify that the feature will be removed in 17.

Suggestion>

The legacy API has been deprecated and will be removed in version 17. Instead, use the new context API introduced with version 16.3.

The legacy API will continue working for all 16.x releases.

bvaughn · 2018-03-21T05:24:15Z

content/docs/legacy-context.md

+
+## How To Use Context
+
+> This section documents a deprecated API. See the [new API](/docs/context.html).


I think these notes are pretty redundant with the one at the head of the page. Probably can remove them?

Probably so. My concern is that it's a long page and someone might get a direct link to a section without noticing the deprecation warning.

It's possible. Definitely seems redundant for the first section though, since the two notes are only like 50 pixels apart. I don't feel as strongly about the following sections.

@bvaughn

- 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

bvaughn · 2018-03-21T14:30:15Z

Looks like CI is saying Prettier needs to be run.

bvaughn

Left some more thoughts. Overall I'm digging the changes.

WRT the redundant deprecation notices on the legacy context page, I don't mind them as much at a second glance. They're probably fine.

bvaughn · 2018-03-21T14:40:00Z

content/docs/context.md


-## Why Not To Use Context
+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.


This paragraph feels like it ends a bit prematurely. Maybe we can close by reiterating the opening line?

Wording suggestions:

In a typical React application, data is passed top-down (parent to child) via props, but this can be cumbersome for certain types of props (e.g. locale preference, UI theme) that are required by many components within an application. Context provides a way to share values like this between components without having to explicitly pass a prop through every level of the tree.

bvaughn · 2018-03-21T14:40:22Z

content/docs/context.md

+- [Examples](#examples)
+  - [Static Context](#static-context)
+  - [Dynamic Context](#dynamic-context)
+- [Legacy API](#legacy-api)


I like this table of contents 👍

bvaughn · 2018-03-21T14:41:28Z

content/docs/context.md


-If you're still learning React, don't use context. There is usually a better way to implement functionality just using props and state.
+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.


nit: I would move the "Using context, we can avoid passing props through intermediate elements." sentence to below the coding example, so it's clear that the example isn't showing what context can do.

bvaughn · 2018-03-21T14:42:41Z

content/docs/context.md


-If you insist on using context despite these warnings, try to isolate your use of context to a small area and avoid using the context API directly when possible so that it's easier to upgrade when the API changes.
+`embed:context/motivation.js`


It still feels wrong to me to have a "motivation" section that does not show how to "fix" the problem we introduce.

bvaughn · 2018-03-21T14:44:55Z

content/docs/context.md

- [`componentWillReceiveProps(nextProps, nextContext)`](/docs/react-component.html#componentwillreceiveprops)
- [`shouldComponentUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#shouldcomponentupdate)
- [`componentWillUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#componentwillupdate)
+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.


I think the last sentence is a bit too long. Suggestion:

Requires a function as a child. This function receives the current context value and returns a React node. It will be called whenever the Provider's value is updated.

bvaughn · 2018-03-21T14:45:34Z

examples/context/theme-example.js

+  render() {
+    // The ThemedButton button inside the ThemeProvider
+    // uses the dark theme while the one outside uses the
+    // default light theme


I like the changes to this example 👍

bvaughn · 2018-03-21T14:47:24Z

examples/context/theme-detailed-app.js

@@ -0,0 +1,30 @@
+import ThemeContext, {themes} from './theme-context';


I don't think we should show a mixed import like this.

Maybe we can import themes from a separate themes.js file? Or change theme-context to remove the default export.

bvaughn · 2018-03-21T14:47:43Z

examples/context/theme-detailed-app.js

+      </ThemeContext.Provider>
+    );
+  }
+}


I like the changes to the theme example as well.

bvaughn · 2018-03-21T14:48:26Z

src/theme.js

@@ -336,7 +336,7 @@ const sharedStyles = {
      },

      '& li': {
-        marginTop: 20,
+        marginTop: 10,


I think it looks nice.

alexkrolick · 2018-03-21T17:14:25Z

Thanks for the review @bvaughn. Added the solution to the motivation problem. I think the highlights emphasize the benefits pretty well.

bvaughn · 2018-03-22T00:31:20Z

You're welcome, @alexkrolick. Thanks for owning this change! It's a big help for the upcoming release.

bvaughn · 2018-03-22T00:32:16Z

I'd like to merge this branch into the bvaughn:16.3-release-blog-post branch (PR #587) so these docs can be released with the other 16.3 stuff. That cool with you?

alexkrolick · 2018-03-22T02:27:06Z

Yep: bvaughn#3

bvaughn · 2018-03-22T04:23:09Z

Thanks!

…nto Chinese (reactjs#665) * fix: correct some spelling mistakes in handling-events.md * [Beta]: docs(cn): translate learn/manipulating-the-dom-with-refs.md * Update beta/src/pages/learn/manipulating-the-dom-with-refs.md Co-authored-by: ZhangDaZongWei <[email protected]> * Update beta/src/pages/learn/manipulating-the-dom-with-refs.md Co-authored-by: ZhangDaZongWei <[email protected]> * resolve review suggestions from ZhangDaZongWei * change some strange translations * Update beta/src/content/learn/manipulating-the-dom-with-refs.md Co-authored-by: TimLi <[email protected]> * Update beta/src/content/learn/manipulating-the-dom-with-refs.md Co-authored-by: TimLi <[email protected]> * Update beta/src/content/learn/manipulating-the-dom-with-refs.md Co-authored-by: TimLi <[email protected]> * Update beta/src/content/learn/manipulating-the-dom-with-refs.md Co-authored-by: TimLi <[email protected]> * Update beta/src/content/learn/manipulating-the-dom-with-refs.md Co-authored-by: TimLi <[email protected]> * Update beta/src/content/learn/manipulating-the-dom-with-refs.md Co-authored-by: TimLi <[email protected]> * Update beta/src/content/learn/manipulating-the-dom-with-refs.md Co-authored-by: TimLi <[email protected]> * Update beta/src/content/learn/manipulating-the-dom-with-refs.md Co-authored-by: TimLi <[email protected]> * Update beta/src/content/learn/manipulating-the-dom-with-refs.md Co-authored-by: TimLi <[email protected]> * remove extra spaces --------- Co-authored-by: ZhangDaZongWei <[email protected]> Co-authored-by: Xavi Lee <[email protected]> Co-authored-by: TimLi <[email protected]>

alexkrolick added 16.3 next release: don't merge labels Mar 6, 2018

facebook-github-bot added the CLA Signed label Mar 6, 2018

alexkrolick force-pushed the new-context-api branch from 9310e12 to b413178 Compare March 6, 2018 08:26

alexkrolick mentioned this pull request Mar 6, 2018

16.3 release blog draft #587

Merged

alexkrolick force-pushed the new-context-api branch from b413178 to 81c1910 Compare March 6, 2018 09:06

Add docs for new Context API (R16.3)

566406e

alexkrolick force-pushed the new-context-api branch from 81c1910 to 566406e Compare March 6, 2018 09:07

bvaughn reviewed Mar 20, 2018

View reviewed changes

alexkrolick added 2 commits March 20, 2018 18:14

Reorganize examples & legacy docs

0780f72

Add in-page TOC

a5022da

Also reduce spacing between ul/li tags

alexkrolick commented Mar 21, 2018

View reviewed changes

Typo

fe3d0a4

bvaughn reviewed Mar 21, 2018

View reviewed changes

Rephrase and reorganize

808e5bd

- 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

bvaughn reviewed Mar 21, 2018

View reviewed changes

alexkrolick added 3 commits March 21, 2018 09:50

Syntax tweaks

de22379

Wording tweaks

291b2fd

Add solution to motivation problem

6aa1995

alexkrolick added 2 commits March 21, 2018 10:16

Highlight createContext()

7c6688c

Highlight whole createContext() call

b49f99b

alexkrolick closed this Mar 22, 2018


		If you aren't familiar with state management libraries like [Redux](https://github.com/reactjs/redux) or [MobX](https://github.com/mobxjs/mobx), don't use context. For many practical applications, these libraries and their React bindings are a good choice for managing state that is relevant to many components. It is far more likely that Redux is the right solution to your problem than that context is the right solution.
		## Experimental API (Deprecated in React 16.3)


		## Using Context

		Here is an example illustrating how you might inject a "theme" using context:


		Creates a `{ Provider, Consumer }` pair.

		Takes one argument, the default context that Consumers will receive when they don't have a matching Provider.


		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.


		Suppose you have a structure like:
		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.


		## How To Use Context

		> This section documents a deprecated API. See the [new API](/docs/context.html).


		## Why Not To Use Context
		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.


		If you're still learning React, don't use context. There is usually a better way to implement functionality just using props and state.
		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.


		If you insist on using context despite these warnings, try to isolate your use of context to a small area and avoid using the context API directly when possible so that it's easier to upgrade when the API changes.
		`embed:context/motivation.js`

		@@ -0,0 +1,30 @@
		import ThemeContext, {themes} from './theme-context';

Add docs for new Context API #665

Add docs for new Context API #665

Conversation

alexkrolick commented Mar 6, 2018 • edited Loading

reactjs-bot commented Mar 6, 2018 • edited Loading

bvaughn left a comment

Choose a reason for hiding this comment

bvaughn Mar 20, 2018 • edited Loading

Choose a reason for hiding this comment

bvaughn Mar 20, 2018 • edited Loading

Choose a reason for hiding this comment

alexkrolick Mar 20, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexkrolick Mar 21, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexkrolick commented Mar 21, 2018

bvaughn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bvaughn commented Mar 21, 2018

bvaughn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexkrolick commented Mar 21, 2018

bvaughn commented Mar 22, 2018

bvaughn commented Mar 22, 2018

alexkrolick commented Mar 22, 2018

bvaughn commented Mar 22, 2018

alexkrolick commented Mar 6, 2018 •

edited

Loading

reactjs-bot commented Mar 6, 2018 •

edited

Loading

bvaughn Mar 20, 2018 •

edited

Loading

bvaughn Mar 20, 2018 •

edited

Loading

alexkrolick Mar 20, 2018 •

edited

Loading

alexkrolick Mar 21, 2018 •

edited

Loading