Updated 16.3 blog post to account for getSnapshotBeforeUpdate lifecycle

Author: bvaughn

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

@@ -3,7 +3,7 @@ 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!
+This release includes an official context API, new class component lifecycles, a new `StrictMode` component, 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.
 
@@ -64,15 +64,17 @@ For example, with the current API, it is too easy to block the initial render wi
 
 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.
+We recognize that this change will impact many existing components. Because of this, the migration path will be as gradual as possible, and will provide escape hatches. (At Facebook, we maintain more than 50,000 React components. We depend on a gradual release cycle too!)
 
 > **Note:**
 >
 > Deprecation warnings will be enabled with a future 16.x release, **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`.
+In addition to deprecating unsafe lifecycles, we are also adding a couple of new lifecyles:
+* [`getDerivedStateFromProps`](/docs/react-component.html#static-getderivedstatefromprops) is being added as a safer alternative to the legacy `componentWillReceiveProps`.
+* [`getSnapshotBeforeUpdate`](/docs/react-component.html#getsnapshotbeforeupdate) is being added to support safely reading properties from e.g. the DOM before updates are made.
 
 [Learn more about these lifecycle changes here.](#TODO-link-to-update-on-async-blog-post)
 

content/docs/reference-react-component.md

@@ -295,9 +295,13 @@ If you need to update `state` in response to `props` changes, use `UNSAFE_compon
 
 ### `getSnapshotBeforeUpdate()`
 
-`getSnapshotBeforeUpdate()` is invoked right before the most recently rendered output is committed to e.g. the DOM. It enables your component to capture current values (e.g. scroll position) before they are potential changed.
+`getSnapshotBeforeUpdate()` is invoked right before the most recently rendered output is committed to e.g. the DOM. It enables your component to capture current values (e.g. scroll position) before they are potential changed. Any value returned by this lifecycle will be passed as a parameter to `componentDidUpdate()`.
 
-Any value returned by this lifecycle will be passed as a parameter to `componentDidUpdate()`.
+For example:
+
+`embed:react-component-reference/get-snapshot-before-update.js`
+
+In the above examples, it is important to read the `scrollHeight` property in `getSnapshotBeforeUpdate` rather than `componentWillUpdate` in order to support async rendering. With async rendering, there may be delays between "render" phase lifecycles (like `componentWillUpdate` and `render`) and "commit" phase lifecycles (like `getSnapshotBeforeUpdate` and `componentDidUpdate`). If a user does something like resize the browser during this time, a `scrollHeight` value read from `componentWillUpdate` will be stale.
 
 * * *
 

examples/react-component-reference/get-snapshot-before-update.js

@@ -0,0 +1,27 @@
+class ScrollingList extends React.Component {
+  listRef = React.createRef();
+
+  getSnapshotBeforeUpdate(prevProps, prevState) {
+    // Are we adding new items to the list?
+    // Capture the current height of the list so we can adjust scroll later.
+    if (prevProps.list.length < this.props.list.length) {
+      return this.listRef.current.scrollHeight;
+    }
+    return null;
+  }
+
+  componentDidUpdate(prevProps, prevState, snapshot) {
+    // If we have a snapshot value, we've just added new items.
+    // Adjust scroll so these new items don't push the old ones out of view.
+    if (snapshot !== null) {
+      this.listRef.current.scrollTop +=
+        this.listRef.current.scrollHeight - snapshot;
+    }
+  }
+
+  render() {
+    return (
+      <div ref={this.listRef}>{/* ...contents... */}</div>
+    );
+  }
+}