16.3 release blog draft

content/blog/2018-03-20-react-v-16-3.md

@@ -0,0 +1,96 @@
+---
+title: "React v16.3.0: New lifecycles and context API"
+author: [bvaughn]
+---
+
+This release includes a new class component lifecycle (`getDerivedStateFromProps`), a new `StrictMode` component, an official context API, a new ergonomic ref API, and a ref-forwarding API!
+
+For the past few months, the React team has been working on support for [asynchronous rendering](/blog/2018/03/01/sneak-peek-beyond-react-16.html). We are excited about the new features it will enable.
+
+We've also learned that some long-term changes will be required to the way we write React components. However, we respect [semver](https://semver.org/) and **will not ship breaking changes in a minor version**!
+
+Read on to learn more about the release.
+
+## Official Context API
+
+For many years, React has offered an experimental API for context. Although it was a powerful tool, its use was discouraged because of inherent problems in the API, and because we always intended to replace the experimental API with a better one.
+
+Version 16.3 introduces a new context API that is more efficient and supports both static type checking and deep updates.
+
+> **Note**
+>
+> The old context API will keep working for all React 16.x releases, so you will have time to migrate.
+
+Here is an example illustrating how you might inject a "theme" using the new context API:
+`embed:16-3-release-blog-post/context-example.js`
+
+[Learn more about the new context API here.](/docs/context.html#api)
+
+## `createRef` API
+
+Previously, React provided two ways of managing refs: the legacy string ref API and the callback API. Although the string ref API was the more convenient of the two, it had [several downsides](https://github.com/facebook/react/issues/1373) and so our official recommendation was to use the callback form instead.
+
+Version 16.3 adds a new option for managing refs that offers the convenience of a string ref without any of the downsides:
+`embed:16-3-release-blog-post/create-ref-example.js`
+
+> **Note:**
+>
+> Callback refs will continue to be supported in addition to the new `createRef` API.
+>
+> You don't need to replace callback refs in your components. They are slightly more flexible, so they will remain as an advanced feature.
+
+[Learn more about the new `createRef` API here.](/docs/refs-and-the-dom.html)
+
+## `forwardRef` API
+
+[Higher-order components](/docs/higher-order-components.html) (or HOCs) are a common way to reuse code between components. Building on the theme context example from above, we might create an HOC that injects the current "theme" as a prop:
+
+`embed:16-3-release-blog-post/hoc-theme-example.js`
+
+We can use the above HOC to wire components up to the theme context without having to use `ThemeContext` directly. For example:
+
+`embed:16-3-release-blog-post/fancy-button-example.js`
+
+HOCs typically [pass props through](/docs/higher-order-components.html#convention-pass-unrelated-props-through-to-the-wrapped-component) to the components they wrap. Unfortunately, [refs are not passed through](/docs/higher-order-components.html#refs-arent-passed-through). This means that we can't attach a ref to `FancyButton` if we use `FancyThemedButton`- so there's no way for us to call `focus()`.
+
+The new `forwardRef` API solves this problem by providing a way for us to intercept a `ref` and forward it as a normal prop:
+`embed:16-3-release-blog-post/forward-ref-example.js`
+
+## Component Lifecycle Changes
+
+React's class component API has been around for years with little change. However, as we add support for more advanced features (such as [error boundaries](/docs/react-component.html#componentdidcatch) and the upcoming [async rendering mode](/blog/2018/03/01/sneak-peek-beyond-react-16.html)) we stretch this model in ways that it was not originally intended.
+
+For example, with the current API, it is too easy to block the initial render with non-essential logic. In part this is because there are too many ways to accomplish a given task, and it can be unclear which is best. We've observed that the interrupting behavior of error handling is often not taken into consideration and can result in memory leaks (something that will also impact the upcoming async rendering mode). The current class component API also complicates other efforts, like our work on [prototyping a React compiler](https://twitter.com/trueadm/status/944908776896978946).
+
+Many of these issues are exacerbated by a subset of the component lifecycles (`componentWillMount`, `componentWillReceiveProps`, and `componentWillUpdate`). These also happen to be the lifecycles that cause the most confusion within the React community. For these reasons, we are going to deprecate those methods in favor of better alternatives.
+
+We recognize that this change will impact many existing components. (At Facebook, we maintain more than 50,000 React components, and we can't tell our engineers to rewrite them either.) Because of this, the migration path will be as gradual as possible, and will provide escape hatches.
+
+> **Note:**
+>
+> Deprecation warnings will be enabled in version 16.4, **but the legacy lifecycles will continue to work until version 17**.
+>
+> Even in version 17, it will still be possible to use them, but they will be aliased with an "UNSAFE_" prefix to indicate that they might cause issues. We have also prepared an [automated script to rename them](https://github.com/reactjs/react-codemod#rename-unsafe-lifecycles) in existing code.
+
+We are also adding a new static lifecycle, `getDerivedStateFromProps`, as a safer alternative to the legacy `componentWillReceiveProps`.
+
+[Learn more about these lifecycle changes here.](#TODO)
+
+## `StrictMode` Component
+
+`StrictMode` is a tool for highlighting potential problems in an application. Like `Fragment`, `StrictMode` does not render any visible UI. It activates additional checks and warnings for its descendants.
+
+> **Note:**
+>
+> `StrictMode` checks are run in development mode only; _they do not impact the production build_.
+
+Although it is not possible for strict mode to catch all problems (e.g. certain types of mutation), it can help with many. If you see warnings in strict mode, those things will likely cause bugs for async rendering.
+
+In version 16.3, `StrictMode` helps with:
+* Identifying components with unsafe lifecycles
+* Warning about legacy string ref API usage
+* Detecting unexpected side effects
+
+Additional functionality will be added with future releases of React.
+
+[Learn more about the `StrictMode` component here.](/docs/strict-mode.html)

content/docs/forwarding-refs.md

@@ -0,0 +1,22 @@
+---
+id: forwarding-refs
+title: Forwarding Refs
+permalink: docs/forwarding-refs.html
+---
+
+Ref forwarding is a technique for passing a [ref](/docs/refs-and-the-dom.html) through a component to one of its descendants. This technique can be particularly useful with [higher-order components](/docs/higher-order-components.html) (also known as HOCs).
+
+Let's start with an example HOC that logs component props to the console:
+`embed:forwarding-refs/log-props-before.js`
+
+The "logProps" HOC passes all `props` through to the component it wraps, so the rendered output will be the same. For example, we can use this HOC to log all props that get passed to our "fancy button" component:
+`embed:forwarding-refs/fancy-button.js`
+
+There is one caveat to the above example: refs will not get passed through. That's because `ref` is not a prop. Like `key`, it's handled differently by React. If you add a ref to a HOC, the ref will refer to the outermost container component, not the wrapped component.
+
+This means that refs intended for our `FancyButton` component will actually be attached to the `LogProps` component:
+`embed:forwarding-refs/fancy-button-ref.js`
+
+Fortunately, we can explicitly forward refs to the inner `FancyButton` component using the `React.forwardRef` API. `React.forwardRef` accepts a render function that receives `props` and `ref` parameters and returns a React node. For example:
+`embed:forwarding-refs/log-props-after.js`
+

content/docs/higher-order-components.md

@@ -394,30 +394,6 @@ import MyComponent, { someFunction } from './MyComponent.js';
 
 ### Refs Aren't Passed Through
 
-While the convention for higher-order components is to pass through all props to the wrapped component, it's not possible to pass through refs. That's because `ref` is not really a prop — like `key`, it's handled specially by React. If you add a ref to an element whose component is the result of a HOC, the ref refers to an instance of the outermost container component, not the wrapped component.
+While the convention for higher-order components is to pass through all props to the wrapped component, this does not work for refs. That's because `ref` is not really a prop — like `key`, it's handled specially by React. If you add a ref to an element whose component is the result of a HOC, the ref refers to an instance of the outermost container component, not the wrapped component.
 
-If you find yourself facing this problem, the ideal solution is to figure out how to avoid using `ref` at all. Occasionally, users who are new to the React paradigm rely on refs in situations where a prop would work better.
-
-That said, there are times when refs are a necessary escape hatch — React wouldn't support them otherwise. Focusing an input field is an example where you may want imperative control of a component. In that case, one solution is to pass a ref callback as a normal prop, by giving it a different name:
-
-```js
-function Field({ inputRef, ...rest }) {
-  return <input ref={inputRef} {...rest} />;
-}
-
-// Wrap Field in a higher-order component
-const EnhancedField = enhance(Field);
-
-// Inside a class component's render method...
-<EnhancedField
-  inputRef={(inputEl) => {
-    // This callback gets passed through as a regular prop
-    this.inputEl = inputEl
-  }}
-/>
-
-// Now you can call imperative methods
-this.inputEl.focus();
-```
-
-This is not a perfect solution by any means. We prefer that refs remain a library concern, rather than require you to manually handle them. We are exploring ways to solve this problem so that using a HOC is unobservable.
+The solution for this problem is to use the `React.forwardRef` API (introduced with React 16.3). [Learn more about it in the forwarding refs section](/docs/forwarding-refs.html).

content/docs/nav.yml

@@ -66,6 +66,8 @@
       title: Web Components
     - id: higher-order-components
       title: Higher-Order Components
+    - id: forwarding-refs
+      title: Forwarding Refs
     - id: render-props
       title: Render Props
     - id: integrating-with-other-libraries
@@ -74,6 +76,8 @@
       title: Accessibility
     - id: code-splitting
       title: Code-Splitting
+    - id: strict-mode
+      title: StrictMode
 - title: Reference
   items:
     - id: react-api

content/docs/reference-react.md

@@ -49,6 +49,10 @@ See [Using React without JSX](/docs/react-without-jsx.html) for more information
 
 - [`React.Fragment`](#reactfragment)
 
+### Other
+
+- [`React.forwardRef`](#reactforwardref)
+
 * * *
 
 ## Reference
@@ -217,3 +221,10 @@ render() {
 ```
 
 You can also use it with the shorthand `<></>` syntax. For more information, see [React v16.2.0: Improved Support for Fragments](/blog/2017/11/28/react-v16.2.0-fragment-support.html).
+
+### `React.forwardRef`
+
+`React.forwardRef` accepts a render function that receives `props` and `ref` parameters and returns a React node. Ref forwarding is a technique for passing a [ref](/docs/refs-and-the-dom.html) through a component to one of its descendants. This technique can be particularly useful with [higher-order components](/docs/higher-order-components.html):
+`embed:reference-react-forward-ref.js`
+
+For more information, see [forwarding refs](/docs/forwarding-refs.html).