From 9f8c4cef7b60cdd1b8bc70d5c9a08623533faf50 Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Mon, 12 Mar 2018 02:19:45 -0700
Subject: [PATCH 01/22] Introduce the RFC for the reparenting API

---
 text/0000-reparenting.md | 351 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 351 insertions(+)
 create mode 100644 text/0000-reparenting.md

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
new file mode 100644
index 00000000..8e452b5a
--- /dev/null
+++ b/text/0000-reparenting.md
@@ -0,0 +1,351 @@
+- Start Date: 2018-03-11
+- RFC PR: (leave this empty)
+- React Issue: (leave this empty)
+
+# Summary
+
+When writing a component that contains a set of large subtrees that stay relatively the same, but are simply moved around such that React's virtual DOM diffing can't detect the movement, React will end up recreating huge trees it should simply be moving.
+
+The goal of this RFC is to introduce a "Reparent" API that allows portions of the React tree to be marked in a way that allows React to know when to move them from one part of the tree to another instead of deleting and recreating the DOM and component instances.
+
+# Basic example
+
+## Layout
+Using reparents to render a page layout that can change structure between desktop and mobile without causing the page contents and sidebar to be recreated from scratch.
+```js
+class Layout extends PureComponent {
+    header = React.createReparent(this);
+    content = React.createReparent(this);
+    sidebar = React.createReparent(this);
+
+    render() {
+        const {isMobile, children} = this.props;
+
+        const header = this.header(
+            <div className='header'>
+                <Logo />
+                <NavigationBar />
+            </div>
+        );
+
+        const sidebar = this.sidebar(
+            <div className='sidebar'>
+                <SidebarContent />
+            </div>
+        );
+
+        const content = this.content(
+            <Fragment>
+                children
+            </Fragment>
+        );
+
+        if ( isMobile ){
+            return (
+                <div>
+                    {header}
+                    {content}
+                    {sidebar}
+                </div>
+            );
+        } else {
+            return (
+                <div>
+                    {header}
+                    <div>
+                        {content}
+                        {sidebar}
+                    </div>
+                </div>
+            );
+        }
+    }
+}
+```
+
+## Dynamic template
+Using reparents in a dynamic template/widget structure to avoid recreating widgets from scratch when they are move from one section of the template to another.
+
+```js
+const TemplateWidgetReparentContext = React.createContext({});
+
+class ReparentableTemplateWidget extends PureComponent {
+    static getDerivedStateFromProps(nextProps, prevState) {
+        if ( !prevState.widget || prevState.widgetType !== nextProps.widget ) {
+            const WidgetClass = getWidgetClassOfType(nextProps.widget);
+            return {
+                widgetType: nextProps.widget,
+                widget: new WidgetClass(),
+            };
+        }
+    }
+
+    render() {
+        const {widget} = this.state;
+
+        return (
+            <div>
+                {widget.render()}
+            </div>
+        );
+    }
+}
+
+/**
+ * This wrapper uses reparents from Template and the widget's own id
+ * to ensure that when a widget is moved from one section to another
+ * it is moved by react instead of recreated.
+ *
+ * This could be turned into an HOC
+ */
+class TemplateWidget extends Component {
+    render() {
+        const {id} = this.props;
+
+        return (
+            <TemplateWidgetReparentContext.Consumer>
+                {templateWidgetReparents => templateWidgetReparents[id](
+                    <ReparentableTemplateWidget {...this.props} />
+                )}
+            </TemplateWidgetReparentContext.Consumer>
+        );
+    }
+}
+
+class Section extends PureComponent {
+    render() {
+        const {title, widgets} = this.props;
+
+        return (
+            <div>
+                <h2>{title}</h2>
+                {widgets.map(widget => (
+                    <TemplateWidget {...widget} key={widget.id} />
+                ))}
+            </div>
+        );
+    }
+}
+
+class Template extends PureComponent {
+    static getDerivedStateFromProps(nextProps, prevState) {
+        if ( nextProps.sections === prevState.sections ) return;
+
+        let templateWidgetReparents = prevState.templateWidgetReparents;
+
+        const widgetIds = new Set();
+        nextProps.sections.forEach(section => section.widgets.forEach(widget => widgetIds.add(widget.id)));
+
+        return {
+            widgetIds: widgetIds.toArray(),
+        };
+    }
+
+    templateWidgetReparents = {};
+
+    render() {
+        const {sections} = this.props;
+        const {widgetIds} = this.state;
+
+        for ( const id of widgetIds ) {
+            if ( !(id in templateWidgetReparents) ) {
+                this.templateWidgetReparents = Object.assign(this.templateWidgetReparents, {
+                    [id]: React.createReparent(this),
+                });
+            }
+        }
+
+        for ( const id in this.templateWidgetReparents ) {
+            if ( !widgetIds.has(id) ) {
+                this.templateWidgetReparents[id].unmount();
+                this.templateWidgetReparents = omit(this.templateWidgetReparents, id);
+            }
+        }
+
+        return (
+            <TemplateWidgetReparentContext.Provider value={this.templateWidgetReparents}>
+                {sections.map(section => {
+                    <Section {...section} key={section.id} />
+                })}
+            </TemplateWidgetReparentContext.Provider>
+        );
+    }
+}
+
+let templateData = {
+    sections: [
+        {
+            id: 's-1',
+            title: 'Untitled 1',
+            widgets: [
+                {
+                    id: 'w-1',
+                    widget: 'paragraph',
+                    props: {
+                        text: 'Lorem ipsum...'
+                    }
+                }
+            ]
+        },
+        {
+            id: 's-2',
+            title: 'Lorem ipsum',
+            widgets: []
+        }
+    ]
+};
+
+ReactDOM.render(<Template {...templateData} />, app);
+
+// Modify the template to move widget:w-1 to section s-2, it should not be necessary to re-create widget w-1 from scratch
+templateData = {
+    sections: [
+        {
+            ...templateData.sections[0],
+            widgets: []
+        },
+        {
+            ...templateData.sections[1],
+            widgets: [
+                templateData.sections[0].widgets[0]
+            ]
+        }
+    ]
+};
+ReactDOM.render(<Template {...templateData} />, app);
+```
+
+# Motivation
+
+Up till now the only way to handle reparenting has been using `ReactDOM.unstable_renderIntoContainer` or Portals to separate a dom node from react rendering and allow that node to be moved around. However this is a complex hack that only works with ReactDOM, it does not work with isomorphic React web apps or other environments like React Native.
+
+This reparenting issue have been left alone for awhile. We have an RFC process now. An RFC for a new context API has made an unstable feature of React stable. And accepted RFCs like createRef have given suggestions on what APIs fitting of React might look like. I think now is a good time to try tackling reparenting.
+
+More motivation can be found in past discussions on reparenting:
+
+- [Support for reparenting (facebook/react#3965)](https://github.com/facebook/react/issues/3965)
+- [A gist that has hosted a lot of reparenting discussion](https://gist.github.com/chenglou/34b155691a6f58091953)
+
+# Detailed design
+
+This proposal introduces a `React.createReparent(component)` function. It accepts a component instance (typically `this`) and returns a *Reparent*. The "Reparent" naming is open to better name proposals.
+
+A Reparent is tied to a component, when this component is unmounted the reparent is unmounted and the detached tree is discarded. This allows reparents to hold detached trees without doing so in a permanent way that would leak memory.
+
+A Reparent has an additional `.unmount()` method, this can be used to force the reparent to unmount and discard its tree like it would when the component it is tied to unmounts. This allows reparents to be hoisted upwards and used for dynamic content and explicitly unmounted when necessary.
+
+The Reparent itself is a function that accepts children for the reparent. The return value is a special Fragment used to render the reparent and its contents somewhere in the React tree.
+
+When React intends to remove the dom/native tree rendered from this special fragment because it is not present in a later render, React instead detaches the tree and holds a reference to it in the Reparent instead of purging it. If a fragment returned by the reparent later is rendered by a component the detached dom/native tree is re-used.
+
+In addition to retaining the dom/native tree for future use React Component instances present in a Reparent are not unmounted until the Reparent is rendered without them, the Reparent is unmounted via .unmount(), or the Reparent is implicitly unmounted when its owner unmounts.
+
+Unlike a normal fragment the fragment returned by a reparent may only be used once in a react tree. If a fragment returned by a Reparent is used multiple times only the latest one will be rendered (they will not be duplicated as normal in React) and during development React may emit warnings that a reparent is used in multiple spots like the warnings when a duplicate key is found.
+
+The fragment returned has an implicit key which is unique to the Reparent. A Reparent itself is like a key that is unique beyond just a single element's children so there is no need for the user to specify an additional key to use its contents in an array.
+
+Naively, createReparent without the reparenting and unmount behaviour behaves similar to the following implementation:
+```js
+React.createReparent = function() {
+    const key = generateUniqueKey();
+
+    const Reparent = function(children) {
+        return React.createElement(Fragment, {key}, children);
+    };
+    Reparent.unmount = () => {
+        throw new Error('Not implemented');
+    };
+
+    return Reparent;
+};
+```
+
+And conforms to the following types/interface:
+```js
+type ReparentFunction = (Component) => ReactFragment;
+type ReparentObject = {
+    unmount(): void;
+};
+type Reparent = ReparentFunction & ReparentObject;
+
+interface React {
+    createReparent(): Reparent;
+}
+```
+
+# Drawbacks
+
+The `.unmount()` method is not necessarily perfect in identifying when a tree is detached but kept or discarded and to be unmounted. If someone chooses to use createReparent dynamically and forgets to call `.unmount()` they will leak memory.
+
+# Alternatives
+
+## createKey
+
+@gaearon proposed [a createKey API](https://gist.github.com/chenglou/34b155691a6f58091953#gistcomment-1460942)
+
+```js
+class MyComponent extends Component {
+    contentKey = React.createKey(this);
+
+    render() {
+        const {isB, children} = this.props;
+
+        const content = <Fragment key={this.contentKey}>{children}</Fragment>;
+
+        return (
+            <div>
+                {isB && content}
+                <div>{!isB && content}</div>
+            </div>
+        );
+    }
+}
+```
+
+The createKey API could work, however it has some limitations that createReparent does not:
+
+- While createKey and createReparent shares the same advantage that unmounting of its host results in unmounting of the reparentable root. contentKey does not have a secondary method of unmounting/discarding the tree. React cannot differentiate between a detached tree and a discarded/unmountable tree. As a result it cannot be used for varying numbers of reparentable roots as trees for discarded keys remain in memory as leaks.
+- createKey adds alternative behaviour using just the `key`, createReparent gives React internals more control in how it they decide to handle the link between the tree and the reparent.
+
+## DetatchedTree
+
+If `.unmount()` proves to be too complex it may be possible to make detached trees work with createReparent, createKey, or other global key methods by using a Fragment-like `<DetatchedTree />` component which holds a reference to the detached tree in the React tree but omits it from the DOM. Then React knows it may unmount components and trees if it is not used as part of the live tree or in a DetatchedTree.
+
+```js
+class MyComponent extends Component {
+    contentKey = React.createKey();
+
+    render() {
+        const {show, children} = this.props;
+
+        const content = <Fragment key={this.contentKey}>{children}</Fragment>;
+
+        return (
+            <div>
+                <DetatchedTree>
+                    {!show && content}
+                </DetatchedTree>
+                {show && content}
+            </div>
+        );
+    }
+}
+```
+
+# Adoption strategy
+
+Reparents can be released in a feature release of React, there are no breaking changes.
+
+If people are still using some experimental 3rd party libraries like [react-teleporter](https://github.com/jaredly/react-teleporter) that use `ReactDOM.unstable_renderIntoContainer` or Portals to hack reparenting into React DOM, we may wish to provide migration guides to the Reparent API or update these libraries to make use of the Reparent API.
+
+# How we teach this
+
+"Reparents" may not be the best terminology, some terminology including "root" in the name to refer to the segment of the tree created by a reparent that can be moved.
+
+We may need a new documentation page to explain reparenting as one was added for portals. Like portals this is an advanced feature that does not need to be part of the main tutorials.
+
+# Unresolved questions
+
+- How do reparent instances interact with hydration?
+  - Perhaps when hydrating the dom tree, portions of the dom tree that match up with portions of the virtual dom belonging to a reparent will be given to the Reparent to hydrate as its dom tree.
+- Should the Reparent function just accept a single children argument, or should it accept ...children rest and pass it on to createElement to behave similar to createElement.

From 93103d51055c8058706f7365089d29d2d34b1df9 Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Thu, 15 Mar 2018 10:53:22 -0700
Subject: [PATCH 02/22] Fix interface definition.

---
 text/0000-reparenting.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index 8e452b5a..a837cf20 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -262,14 +262,14 @@ React.createReparent = function() {
 
 And conforms to the following types/interface:
 ```js
-type ReparentFunction = (Component) => ReactFragment;
+type ReparentFunction = (ReactNodeList) => ReactFragment;
 type ReparentObject = {
     unmount(): void;
 };
 type Reparent = ReparentFunction & ReparentObject;
 
 interface React {
-    createReparent(): Reparent;
+    createReparent(Component): Reparent;
 }
 ```
 

From 3f87f950789382b714247ae1d8e127a044b8c22c Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Thu, 15 Mar 2018 10:55:06 -0700
Subject: [PATCH 03/22] Add a glossary and improve clarity of the design docs

Also add unresolved question about rendering the children of a detached dom tree.
---
 text/0000-reparenting.md | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index a837cf20..e92a30f5 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -226,21 +226,26 @@ More motivation can be found in past discussions on reparenting:
 - [Support for reparenting (facebook/react#3965)](https://github.com/facebook/react/issues/3965)
 - [A gist that has hosted a lot of reparenting discussion](https://gist.github.com/chenglou/34b155691a6f58091953)
 
+# Glossary
+
+- **state tree**: The state tree refers to both the tree of DOM nodes or other tree of native elements React is rendering to (for React Native and 3rd party environments) and the tree of React Components that allows React to reuse an instance of a Component on a future render.
+- **Reparent owner**: A reparent owner is the component passed to the `React.createReparent(component)` function. The owner does not have to be the one rendering the Reparent, you can pass the reparent down for a descendant to render, but it cannot be passed upwards to be rendered by a parent or cousin of the Reparent owner (notwithstanding use of Portals).
+
 # Detailed design
 
-This proposal introduces a `React.createReparent(component)` function. It accepts a component instance (typically `this`) and returns a *Reparent*. The "Reparent" naming is open to better name proposals.
+This proposal introduces a `React.createReparent(component)` function. It accepts a component instance (typically `this`) which is the reparent owner and returns a *Reparent*. The "Reparent" naming is open to better name proposals.
 
-A Reparent is tied to a component, when this component is unmounted the reparent is unmounted and the detached tree is discarded. This allows reparents to hold detached trees without doing so in a permanent way that would leak memory.
+A Reparent is tied to its owner, when its owner is unmounted the reparent is also unmounted and the detached state tree is discarded. This allows reparents to hold detached state trees without doing so in a permanent way that would leak memory.
 
-A Reparent has an additional `.unmount()` method, this can be used to force the reparent to unmount and discard its tree like it would when the component it is tied to unmounts. This allows reparents to be hoisted upwards and used for dynamic content and explicitly unmounted when necessary.
+A Reparent has an additional `.unmount()` method, this can be used to force the reparent to unmount and discard its state tree like it would when it's owner unmounts, even when the owner is not unmounting. This allows reparents to be hoisted upwards by registering the Reparent in a parent Component and then passing the Reparent down to children through props or context for a descendant to render. And allows them to be used for dynamic content and explicitly unmounted when necessary (the descendant no longer needs the Reparent but the Reparent owner will not be unmounting). See the "Dynamic template" example.
 
-The Reparent itself is a function that accepts children for the reparent. The return value is a special Fragment used to render the reparent and its contents somewhere in the React tree.
+The Reparent itself is a function that accepts children for the reparent. The return value is a special Fragment used to render the reparent and its contents somewhere in the state tree.
 
 When React intends to remove the dom/native tree rendered from this special fragment because it is not present in a later render, React instead detaches the tree and holds a reference to it in the Reparent instead of purging it. If a fragment returned by the reparent later is rendered by a component the detached dom/native tree is re-used.
 
-In addition to retaining the dom/native tree for future use React Component instances present in a Reparent are not unmounted until the Reparent is rendered without them, the Reparent is unmounted via .unmount(), or the Reparent is implicitly unmounted when its owner unmounts.
+In addition to retaining the dom/native tree for future use the rest of the state tree belonging to the Reparent is also retained. Such that React Component instances present in a Reparent are not unmounted until the Reparent is rendered without them (explicitly discarding the component), the Reparent is unmounted via `.unmount()` (explicitly destroying the Reparent and its whole tree), or the Reparent is implicitly unmounted when its owner unmounts (implicitly destroying the Reparent and its whole tree).
 
-Unlike a normal fragment the fragment returned by a reparent may only be used once in a react tree. If a fragment returned by a Reparent is used multiple times only the latest one will be rendered (they will not be duplicated as normal in React) and during development React may emit warnings that a reparent is used in multiple spots like the warnings when a duplicate key is found.
+Unlike a normal fragment the fragment returned by a reparent may only be used once in the entire state tree. If a fragment returned by a Reparent is used multiple times only the latest one will be rendered (they will not be duplicated as normal in React) and during development React may emit warnings that a reparent is used in multiple spots like the warnings when a duplicate key is found.
 
 The fragment returned has an implicit key which is unique to the Reparent. A Reparent itself is like a key that is unique beyond just a single element's children so there is no need for the user to specify an additional key to use its contents in an array.
 
@@ -340,7 +345,7 @@ If people are still using some experimental 3rd party libraries like [react-tele
 
 # How we teach this
 
-"Reparents" may not be the best terminology, some terminology including "root" in the name to refer to the segment of the tree created by a reparent that can be moved.
+"Reparents" may not be the best terminology, some terminology including "root" in the name to refer to the segment of the state tree created by a reparent that can be moved.
 
 We may need a new documentation page to explain reparenting as one was added for portals. Like portals this is an advanced feature that does not need to be part of the main tutorials.
 
@@ -349,3 +354,4 @@ We may need a new documentation page to explain reparenting as one was added for
 - How do reparent instances interact with hydration?
   - Perhaps when hydrating the dom tree, portions of the dom tree that match up with portions of the virtual dom belonging to a reparent will be given to the Reparent to hydrate as its dom tree.
 - Should the Reparent function just accept a single children argument, or should it accept ...children rest and pass it on to createElement to behave similar to createElement.
+- If a Reparent is detached and it's DOM tree is detached from the document, should it render the children it is passed in the Reparent function; or should it save the most recent children value passed to it and wait till it is re-mounted before actually rendering those children?

From bfc4430013bf776be1a718d9cd1a93bbe6914e8f Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Thu, 15 Mar 2018 11:23:35 -0700
Subject: [PATCH 04/22] Add a limitations section and a request to avoid
 removeChild when moving dom nodes

---
 text/0000-reparenting.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index e92a30f5..304ae488 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -247,6 +247,8 @@ In addition to retaining the dom/native tree for future use the rest of the stat
 
 Unlike a normal fragment the fragment returned by a reparent may only be used once in the entire state tree. If a fragment returned by a Reparent is used multiple times only the latest one will be rendered (they will not be duplicated as normal in React) and during development React may emit warnings that a reparent is used in multiple spots like the warnings when a duplicate key is found.
 
+When React DOM intends to detach a DOM node (because the Reparent from a previous call to render is no longer returned in the virtual DOM for a later render), it may use `removeChild` to detach the DOM node, but must retain a reference to it so it may be re-inserted later if the Reparent is rendered in a future render. However when React DOM intends to move a DOM node (because the Reparent from a previous calls to render has a different parent in the virtual DOM on a later render) React DOM should avoid using `removeChild` and instead just call `appendChild`/`insertChild` without first calling `removeChild` (unless it detects some sort of situation like a reference cycle that would make this impossible). This is an attempt to avoid some of the side effects of Reparenting, in particular it is to avoid IE11's behaviour of pausing a `<video>` when you `removeChild` then `appendChild` instead of just using `appendChild`.
+
 The fragment returned has an implicit key which is unique to the Reparent. A Reparent itself is like a key that is unique beyond just a single element's children so there is no need for the user to specify an additional key to use its contents in an array.
 
 Naively, createReparent without the reparenting and unmount behaviour behaves similar to the following implementation:
@@ -278,6 +280,16 @@ interface React {
 }
 ```
 
+# Limitations
+
+Some DOM nodes have quirks they exhibit when they are moved from one parent DOM node to another parent DOM node. These quirks are unavoidable and solving them is not part of the reparenting RFC. The benefits of having the option to reparent nodes if desired is still significant even given the limitations. Some of these quirks may be fixed by either making the state controlled (see [registered prop as ref](https://github.com/reactjs/rfcs/pull/28) for a possible solution for this) or by storing the state before the reparent and restoring it afterwards (see [getSnapshotBeforeUpdate](https://github.com/reactjs/rfcs/pull/33) for a possible solution).
+
+- `<video>`/`<audio>` elements may pause (Chrome exhibits this behaviour; IE11 only exhibits this behaviour if you `removeChild` before you `appendChild`/`insertChild`; Firefox and Safari do not exhibit this quirk)
+- `<iframe>` elements will refresh, completely losing their state. This is unavoidable. However, iframes have very limited use cases so those making use of iframes should be aware that they cannot move their iframes around unless they accept that it will refresh when they do.
+- `.swf` Flash players will reload. (*unconfirmed*)
+- The currently focused element may lose its focus if it is being moved. (*unconfirmed*)
+- Scrollable containers will lose their scroll position and reset to the initial scroll position when they are moved.
+
 # Drawbacks
 
 The `.unmount()` method is not necessarily perfect in identifying when a tree is detached but kept or discarded and to be unmounted. If someone chooses to use createReparent dynamically and forgets to call `.unmount()` they will leak memory.

From b947e8dd18c814e87b84ce3439ff115d15be4931 Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Wed, 28 Mar 2018 02:06:45 -0700
Subject: [PATCH 05/22] Confirm that focus is lost when reparenting

Tested in Chrome, Firefox, Safari, and IE11. All browsers lose focus on basic appendChild.
https://dantman.github.io/dom-reparent-tests/focus.html
---
 text/0000-reparenting.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index 304ae488..90b9f46f 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -287,7 +287,7 @@ Some DOM nodes have quirks they exhibit when they are moved from one parent DOM
 - `<video>`/`<audio>` elements may pause (Chrome exhibits this behaviour; IE11 only exhibits this behaviour if you `removeChild` before you `appendChild`/`insertChild`; Firefox and Safari do not exhibit this quirk)
 - `<iframe>` elements will refresh, completely losing their state. This is unavoidable. However, iframes have very limited use cases so those making use of iframes should be aware that they cannot move their iframes around unless they accept that it will refresh when they do.
 - `.swf` Flash players will reload. (*unconfirmed*)
-- The currently focused element may lose its focus if it is being moved. (*unconfirmed*)
+- The currently focused element will lose its focus if it is being moved.
 - Scrollable containers will lose their scroll position and reset to the initial scroll position when they are moved.
 
 # Drawbacks

From 5fe5fcd324d3dd2a53e3c4af0bd9a45ecccc8d12 Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Wed, 28 Mar 2018 13:35:56 -0700
Subject: [PATCH 06/22] Add some more detail on the goals of reparenting from
 the perspective of this RFC

---
 text/0000-reparenting.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index 90b9f46f..0d9c3c8b 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -221,6 +221,17 @@ Up till now the only way to handle reparenting has been using `ReactDOM.unstable
 
 This reparenting issue have been left alone for awhile. We have an RFC process now. An RFC for a new context API has made an unstable feature of React stable. And accepted RFCs like createRef have given suggestions on what APIs fitting of React might look like. I think now is a good time to try tackling reparenting.
 
+## Goals of reparenting
+
+1. Ensure that react instance state (`state` and `this.*`) is not destroyed when reparenting.
+2. Avoid the high cost of re-render when React could just move a component from one parent to another.
+3. Where posible, retain the state of the underlying element external to React: like video buffers, state contained in custom-element instances, 3rd party library annotations (e.g. jQuery's `data` storage), and other native state.
+
+1 and 2 have a high enough value that it's ok for 3 to not function completely, where incomplete means:
+
+- The platform is non-dom and may not actually have a dom-like concept of moving a view from one parent to another.
+- Some of the state in the native element is lost when we use appenChild like focus, scroll, playing state (see [Limitations](#Limitations)).
+
 More motivation can be found in past discussions on reparenting:
 
 - [Support for reparenting (facebook/react#3965)](https://github.com/facebook/react/issues/3965)

From 843514728b2927eb7d09e6e3c061c1d716e21cd9 Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Wed, 28 Mar 2018 13:38:28 -0700
Subject: [PATCH 07/22] Update link to getSnapshotBeforeUpdate

---
 text/0000-reparenting.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index 0d9c3c8b..fb83b465 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -293,7 +293,7 @@ interface React {
 
 # Limitations
 
-Some DOM nodes have quirks they exhibit when they are moved from one parent DOM node to another parent DOM node. These quirks are unavoidable and solving them is not part of the reparenting RFC. The benefits of having the option to reparent nodes if desired is still significant even given the limitations. Some of these quirks may be fixed by either making the state controlled (see [registered prop as ref](https://github.com/reactjs/rfcs/pull/28) for a possible solution for this) or by storing the state before the reparent and restoring it afterwards (see [getSnapshotBeforeUpdate](https://github.com/reactjs/rfcs/pull/33) for a possible solution).
+Some DOM nodes have quirks they exhibit when they are moved from one parent DOM node to another parent DOM node. These quirks are unavoidable and solving them is not part of the reparenting RFC. The benefits of having the option to reparent nodes if desired is still significant even given the limitations. Some of these quirks may be fixed by either making the state controlled (see [registered prop as ref](https://github.com/reactjs/rfcs/pull/28) for a possible solution for this) or by storing the state before the reparent and restoring it afterwards (see [getSnapshotBeforeUpdate](https://github.com/reactjs/rfcs/blob/master/text/0033-new-commit-phase-lifecycles.md) for a possible solution).
 
 - `<video>`/`<audio>` elements may pause (Chrome exhibits this behaviour; IE11 only exhibits this behaviour if you `removeChild` before you `appendChild`/`insertChild`; Firefox and Safari do not exhibit this quirk)
 - `<iframe>` elements will refresh, completely losing their state. This is unavoidable. However, iframes have very limited use cases so those making use of iframes should be aware that they cannot move their iframes around unless they accept that it will refresh when they do.

From e6011c94b7d186b38fd917c31d90a1c6589ec314 Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Wed, 28 Mar 2018 14:16:57 -0700
Subject: [PATCH 08/22] Fix spelling and markdown line break mistakes

---
 text/0000-reparenting.md | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index fb83b465..063b7698 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -11,7 +11,9 @@ The goal of this RFC is to introduce a "Reparent" API that allows portions of th
 # Basic example
 
 ## Layout
+
 Using reparents to render a page layout that can change structure between desktop and mobile without causing the page contents and sidebar to be recreated from scratch.
+
 ```js
 class Layout extends PureComponent {
     header = React.createReparent(this);
@@ -64,6 +66,7 @@ class Layout extends PureComponent {
 ```
 
 ## Dynamic template
+
 Using reparents in a dynamic template/widget structure to avoid recreating widgets from scratch when they are move from one section of the template to another.
 
 ```js
@@ -225,12 +228,12 @@ This reparenting issue have been left alone for awhile. We have an RFC process n
 
 1. Ensure that react instance state (`state` and `this.*`) is not destroyed when reparenting.
 2. Avoid the high cost of re-render when React could just move a component from one parent to another.
-3. Where posible, retain the state of the underlying element external to React: like video buffers, state contained in custom-element instances, 3rd party library annotations (e.g. jQuery's `data` storage), and other native state.
+3. Where possible, retain the state of the underlying element external to React: like video buffers, state contained in custom-element instances, 3rd party library annotations (e.g. jQuery's `data` storage), and other native state.
 
 1 and 2 have a high enough value that it's ok for 3 to not function completely, where incomplete means:
 
 - The platform is non-dom and may not actually have a dom-like concept of moving a view from one parent to another.
-- Some of the state in the native element is lost when we use appenChild like focus, scroll, playing state (see [Limitations](#Limitations)).
+- Some of the state in the native element is lost when we use appendChild like focus, scroll, playing state (see [Limitations](#Limitations)).
 
 More motivation can be found in past discussions on reparenting:
 
@@ -263,6 +266,7 @@ When React DOM intends to detach a DOM node (because the Reparent from a previou
 The fragment returned has an implicit key which is unique to the Reparent. A Reparent itself is like a key that is unique beyond just a single element's children so there is no need for the user to specify an additional key to use its contents in an array.
 
 Naively, createReparent without the reparenting and unmount behaviour behaves similar to the following implementation:
+
 ```js
 React.createReparent = function() {
     const key = generateUniqueKey();
@@ -279,6 +283,7 @@ React.createReparent = function() {
 ```
 
 And conforms to the following types/interface:
+
 ```js
 type ReparentFunction = (ReactNodeList) => ReactFragment;
 type ReparentObject = {
@@ -335,9 +340,9 @@ The createKey API could work, however it has some limitations that createReparen
 - While createKey and createReparent shares the same advantage that unmounting of its host results in unmounting of the reparentable root. contentKey does not have a secondary method of unmounting/discarding the tree. React cannot differentiate between a detached tree and a discarded/unmountable tree. As a result it cannot be used for varying numbers of reparentable roots as trees for discarded keys remain in memory as leaks.
 - createKey adds alternative behaviour using just the `key`, createReparent gives React internals more control in how it they decide to handle the link between the tree and the reparent.
 
-## DetatchedTree
+## DetachedTree
 
-If `.unmount()` proves to be too complex it may be possible to make detached trees work with createReparent, createKey, or other global key methods by using a Fragment-like `<DetatchedTree />` component which holds a reference to the detached tree in the React tree but omits it from the DOM. Then React knows it may unmount components and trees if it is not used as part of the live tree or in a DetatchedTree.
+If `.unmount()` proves to be too complex it may be possible to make detached trees work with createReparent, createKey, or other global key methods by using a Fragment-like `<DetachedTree />` component which holds a reference to the detached tree in the React tree but omits it from the DOM. Then React knows it may unmount components and trees if it is not used as part of the live tree or in a DetachedTree.
 
 ```js
 class MyComponent extends Component {
@@ -350,9 +355,9 @@ class MyComponent extends Component {
 
         return (
             <div>
-                <DetatchedTree>
+                <DetachedTree>
                     {!show && content}
-                </DetatchedTree>
+                </DetachedTree>
                 {show && content}
             </div>
         );

From f0808a71e61f4d8ad3c9e907e15cbb98772fb867 Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Wed, 28 Mar 2018 15:47:47 -0700
Subject: [PATCH 09/22] Add explanation of the requirements of any sufficent
 reparenting api

---
 text/0000-reparenting.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index 063b7698..da95814d 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -240,10 +240,42 @@ More motivation can be found in past discussions on reparenting:
 - [Support for reparenting (facebook/react#3965)](https://github.com/facebook/react/issues/3965)
 - [A gist that has hosted a lot of reparenting discussion](https://gist.github.com/chenglou/34b155691a6f58091953)
 
+# Requirements
+
+There are a variety of use cases for reparenting. Some of them have certain requirements of the API that not all suggestions cover.
+
+1. It must not rely on user-provided strings.
+
+   We already use string keys for local key comparisons. This works fine for local keys, but guaranteeing the application wide uniqueness of a string should not be a requirement of using a reparent. No other React API works this way and it adds difficulty to usage of reparents within libraries.
+
+2. It must be possible to detach a tree and reuse it later.
+
+   Sometimes you want to detach a tree and hold on to it instead of just moving it around. For example, it may be beneficial to remove a modal's contents when not in use. Or the detached nature may simply be a side effect of complex application logic, perhaps involving async and nested components, which results in it being difficult to guarantee that a reparent is present somewhere in the react state tree. Thus any implementation must provide enough information for React to differentiate between when a reparent is not present in a tree but has just been detached; and when a reparent is no longer in use by its owner and should be unmounted.
+
+3. It must be possible to create reparents dynamically.
+
+   Sometimes instead of a reparent being used for a known tree that you just want to move, it is instead used for dynamic content that comes from some store/database. You need to be able to move the content generated from this from one part of the state tree to another. But any number of these may exist at once.
+
+   Thus it must not be a requirement that reparents be known ahead of time. Additionally, because reparents for dynamic content can be removed dynamically it must be possible to unmount any reparent no longer in use, without the owner of the reparent itself having to unmount.
+
+4. It must be possible to use a reparent in the render method of a component that is a descendent of the actual owner.
+
+   Special use cases the dynamic template example and common use cases like Drag & Drop often may involve moving a reparent from one React component to another React component. Thus it must be possible for the reparent's owner to be a React component higher up in the state tree that is able to pass its reparents down to children (through props or context) and have those children render the reparent.
+
+5. Requirements 2, 3, and 4 interact specially and a proper reparent implementation must satisfy all of them at the same time.
+
+   - Unmounting in React involves the calling of lifecycle methods that may involve cleanup of possible global subscriptions (event listeners, data observers, etc) which may leak if not done. As a result we cannot simply store a reference to the state tree in a reparent and let the state tree be GCd when the reparent is no longer being referenced by the code that created it. React must hold a reference to the state tree and explicitly unmount it when not in use.
+   - Reparents may be created/destroyed dynamically and be owned by a component that may never unmount. So we need to know when we can unmount a reparent, separate from just when its owner unmounts.
+   - We need detached trees, so we cannot simply unmount any reparent that is no longer present in the state tree.
+   - A reparent may be rendered in a component other than its owner. Thus we cannot simply unmount a reparent when it has not been used in the render method of its owner.
+
+   As a result, in addition to implementing the global-ishly unique key behaviour needed to move reparents any implementation also needs to provide an explicit declaration that can be used to differentiate detached from unused reparents.
+
 # Glossary
 
 - **state tree**: The state tree refers to both the tree of DOM nodes or other tree of native elements React is rendering to (for React Native and 3rd party environments) and the tree of React Components that allows React to reuse an instance of a Component on a future render.
 - **Reparent owner**: A reparent owner is the component passed to the `React.createReparent(component)` function. The owner does not have to be the one rendering the Reparent, you can pass the reparent down for a descendant to render, but it cannot be passed upwards to be rendered by a parent or cousin of the Reparent owner (notwithstanding use of Portals).
+- **global-ish key**: The global-ish key nature of reparents refers to how normally in react the string `key="..."` is only locally unique within its parent, but a reparent must be unique within any parent. Generally this would be though of as "globally unique", however because reparents have an owner they only actually need to be unique within the portion of the state tree under their owner.
 
 # Detailed design
 

From 2dae0e925ab32bf58829f68aca44ed31eb288e7b Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Wed, 28 Mar 2018 15:48:37 -0700
Subject: [PATCH 10/22] Add unresolved question about reparents being sent
 upwards

---
 text/0000-reparenting.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index da95814d..1a29ceed 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -415,3 +415,30 @@ We may need a new documentation page to explain reparenting as one was added for
   - Perhaps when hydrating the dom tree, portions of the dom tree that match up with portions of the virtual dom belonging to a reparent will be given to the Reparent to hydrate as its dom tree.
 - Should the Reparent function just accept a single children argument, or should it accept ...children rest and pass it on to createElement to behave similar to createElement.
 - If a Reparent is detached and it's DOM tree is detached from the document, should it render the children it is passed in the Reparent function; or should it save the most recent children value passed to it and wait till it is re-mounted before actually rendering those children?
+- Sometimes a pattern like this exists:
+
+  ```js
+  class Foo extends Component {
+    state = {
+      dialog: undefined,
+    };
+    setDialog = dialog => this.setState({dialog});
+    render() {
+      return (
+        <div>
+          <Bar setDialog={this.setDialog} />
+          {this.state.dialog}
+        </div>
+      );
+    }
+  }
+  class Bar extends Component {
+    componentDidMount() {
+      this.props.setDialog(<Baz />);
+    }
+    // ...
+  }
+  // ...
+  ```
+
+  If Bar were to create a reparent and use it as part of the tree passed to setDialog then technically the reparent would be used above its owner. Should we relax the wording of this RFC to permit this?
\ No newline at end of file

From 02957e6a830a7fcc8658766c8b9c22befa11bf61 Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Wed, 28 Mar 2018 16:21:02 -0700
Subject: [PATCH 11/22] Add a table cell example

This demonstrates the usage of dynamic reparent creation and removal, without the complex multi-component handling of the dynamic template example.
---
 text/0000-reparenting.md | 122 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 122 insertions(+)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index 1a29ceed..b6094a0c 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -65,6 +65,128 @@ class Layout extends PureComponent {
 }
 ```
 
+## Table with movable cells
+
+Using dynamic reparents within a table to ensure that cells are not recreated from scratch when moved from one row to another.
+
+```js
+class TableWidget extends PureComponent {
+    state = {
+        table: {
+            cols: 4,
+            rows: 0,
+            cells: [],
+        },
+    };
+
+    addRow() {
+        this.setState(state => ({
+            table: update(state.table, {
+                rows: state.table.rows + 1,
+                cells: {
+                    [state.table.rows + 1]: {
+                        $set: new Array(state.table.cols).fill(null),
+                    },
+                },
+            })
+        }));
+    }
+
+    addData(row, col, data) {
+        this.setState(state => ({
+            table: update(state.table, {
+                cells: {
+                    [row]: {
+                        [col]: {
+                            $set: {
+                                id: uuid(),
+                                data,
+                            },
+                        },
+                    },
+                },
+            })
+        }));
+    }
+
+    moveData(from, to) {
+        this.setState(state => {
+            let {table} = state;
+            // Set the to cell to the from cell's data
+            table = update(table, {
+                cells: {
+                    [to.row]: {
+                        [to.col]: {
+                            $set: table.cells[from.row][from.col],
+                        },
+                    },
+                },
+            });
+            // Set the from cell to null
+            table = update(table, {
+                cells: {
+                    [from.row]: {
+                        [from.col]: {
+                            $set: null,
+                        },
+                    },
+                },
+            });
+            return {table};
+        });
+    }
+
+    removeData(row, col) {
+        this.setState(state => {
+            // Unmount the reparent so we don't leak memory
+            const cell = table.cells[from.row][from.col];
+            if ( this.cells[cell.id] ) {
+                this.cells[cell.id].unmount();
+                delete this.cells[cell.id];
+            }
+
+            // Set the cell to null
+            let {table} = state;
+            table = update(table, {
+                cells: {
+                    [row]: {
+                        [col]: {
+                            $set: null,
+                        },
+                    },
+                },
+            });
+            return {table};
+        });
+    }
+
+    // Dynamic store for reparents, the reparents are created as-needed for cells in the table
+    cells = Object.create(null);
+    getCell = (cell, row, col) => {
+        this.cells[cell.id] = this.cells[cell.id] || React.createReparent(this);
+        return this.cells[cell.id](<Cell row={row} col={col} cell={cell} />);
+    };
+
+    render() {
+        const {table} = this.props
+
+        return (
+            <table>
+                {table.cells.map((cols, row) => (
+                    <tr key={row}>
+                        {row.cols.map((cell, column) => (
+                            <td key={column}>
+                                {this.getCell(cell, row, column)}
+                            </td>
+                        ))}
+                    </tr>
+                ))}
+            </table>
+        );
+    }
+}
+```
+
 ## Dynamic template
 
 Using reparents in a dynamic template/widget structure to avoid recreating widgets from scratch when they are move from one section of the template to another.

From 6ece6018605748a9f22aba4ca68f05abc79bfc24 Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Wed, 28 Mar 2018 17:00:48 -0700
Subject: [PATCH 12/22] Add a simple example of detachable trees

---
 text/0000-reparenting.md | 62 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index b6094a0c..72f1bef7 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -10,6 +10,68 @@ The goal of this RFC is to introduce a "Reparent" API that allows portions of th
 
 # Basic example
 
+## Detach trees of dom nodes / components
+
+```js
+class Foo extends Component {
+    componentDidMount() {
+        console.log('Mounted');
+    }
+    componmentWillUnmount() {
+        console.log('Unmounted');
+    }
+    render() {
+        return null;
+    }
+}
+
+class DetachableTree extends Component {
+    reparent = React.createReparent(this);
+
+    render() {
+        const content = this.reparent(this.props.children);
+        return this.props.show && content;
+    }
+}
+
+ReactDOM.render(
+    <DetachableTree show={true}>
+        <Foo key={1} />
+    </DetachableTree>,
+    container);
+// log: Mounted
+
+// Children can be detached from the dom tree with `show = false`
+ReactDOM.render(
+    <DetachableTree show={false}>
+        <Foo key={1} />
+    </DetachableTree>,
+    container);
+// But they will not actually be unmounted
+
+// If you set `show = true` later, the previously rendered state tree will be re-inserted
+ReactDOM.render(
+    <DetachableTree show={true}>
+        <Foo key={1} />
+    </DetachableTree>,
+    container);
+
+// The state tree of the reparent is what is retained, not the contents. So if you change the contents of the DetachableTree, then components unmount as normal
+ReactDOM.render(
+    <DetachableTree show={true}>
+        <Foo key={2} />
+    </DetachableTree>,
+    container);
+// log: Unmounted
+// log: Mounted
+
+// But if you unmount the DetachableTree the reparent will unmount and all of the normal react elements inside will also unmount.
+ReactDOM.render(
+    <div />,
+    container);
+// log: Unmounted
+```
+
 ## Layout
 
 Using reparents to render a page layout that can change structure between desktop and mobile without causing the page contents and sidebar to be recreated from scratch.

From b4562d632c69ebfb97ae87be49abbdd78030f75e Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Wed, 28 Mar 2018 17:01:11 -0700
Subject: [PATCH 13/22] Add requirement that Portals are not the way reparents
 are used

---
 text/0000-reparenting.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index 72f1bef7..a10d4998 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -455,6 +455,10 @@ There are a variety of use cases for reparenting. Some of them have certain requ
 
    As a result, in addition to implementing the global-ishly unique key behaviour needed to move reparents any implementation also needs to provide an explicit declaration that can be used to differentiate detached from unused reparents.
 
+6. It cannot require React DOM's Portals.
+
+   Portals only work in the client side DOM code. They don't work on the server, if you render something isomorphic and then put it into a portal on the client it will be recreated from scratch. And Portals are not available in non-dom environments like React Native. While native doesn't necessarily need reparenting for native views, reparenting itself is still useful as a way of keeping the state of React components without resorting to moving absolutely everything into Flux/Redux.
+
 # Glossary
 
 - **state tree**: The state tree refers to both the tree of DOM nodes or other tree of native elements React is rendering to (for React Native and 3rd party environments) and the tree of React Components that allows React to reuse an instance of a Component on a future render.

From 71397fc0e19737c2a760b086a1064f361a59212e Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Wed, 28 Mar 2018 17:21:00 -0700
Subject: [PATCH 14/22] Add an alternatives section on a `.keep()` signal
 instead of explicit `.unmount()`.

Also fix mistakes in the original Dynamic template example.
---
 text/0000-reparenting.md | 51 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index a10d4998..4efc4dd1 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -318,8 +318,6 @@ class Template extends PureComponent {
     static getDerivedStateFromProps(nextProps, prevState) {
         if ( nextProps.sections === prevState.sections ) return;
 
-        let templateWidgetReparents = prevState.templateWidgetReparents;
-
         const widgetIds = new Set();
         nextProps.sections.forEach(section => section.widgets.forEach(widget => widgetIds.add(widget.id)));
 
@@ -335,7 +333,7 @@ class Template extends PureComponent {
         const {widgetIds} = this.state;
 
         for ( const id of widgetIds ) {
-            if ( !(id in templateWidgetReparents) ) {
+            if ( !(id in this.templateWidgetReparents) ) {
                 this.templateWidgetReparents = Object.assign(this.templateWidgetReparents, {
                     [id]: React.createReparent(this),
                 });
@@ -585,6 +583,53 @@ class MyComponent extends Component {
 }
 ```
 
+## .keep()
+
+Another alternative to the imperative `.unmount()` would be to have a `.keep()` signal. Instead of explicitly unmounting a dynamic reparent, for a reparent to be retained, either the ReparentFunction must be called with contents during render or `.keep()` must be called during render. If neither of them happens React considers the reparent unused and unmounts its contents. The reparent can later be re-used, but a new state tree will be created.
+
+```js
+class Template extends PureComponent {
+    static getDerivedStateFromProps(nextProps, prevState) {
+        if ( nextProps.sections === prevState.sections ) return;
+
+        let templateWidgetReparents = Object.create(null);
+
+        nextProps.sections.forEach(section => {
+            section.widgets.forEach(widget => {
+                templateWidgetReparents[widget.id] = prevState.templateWidgetReparents[id][widget.id] || React.createReparent(this);
+            });
+        });
+
+        return {
+            templateWidgetReparents,
+        };
+    }
+
+    render() {
+        const {sections} = this.props;
+        const {templateWidgetReparents} = this.state;
+
+        // Explicitly keep all the reparents we are using
+        // - Even if a reparent kept here isn't used in a TemplateComponent is is still not unmounted
+        // - If a reparent from a previous render isn't kept here, then React knows we don't have a reference to it anymore so it can be unmounted and allowed to be garbage collected
+        for ( const id in templateWidgetReparents ) {
+            templateWidgetReparents[id].keep();
+        }
+
+        return (
+            <TemplateWidgetReparentContext.Provider value={templateWidgetReparents}>
+                {sections.map(section => {
+                    <Section {...section} key={section.id} />
+                })}
+            </TemplateWidgetReparentContext.Provider>
+        );
+    }
+}
+```
+
+- Is calling `reparent(content)`/`reparent.keep()` in a child's `render()` enough? Or do we require that the owner itself must explicitly `.keep()` all reparents it intends to pass to children?
+- Perhaps we could keep a note in the state tree that a reparent is in use by a child component when it calls `reparent(content)` or `reparent.keep(this)` (this could be optional if we are fine with implicitly detecting the instance of the currently executing `render()`, but `this` is an option if we want to avoid that (string refs all over again). This would then ensure that the simple use case of passing a reparent to a child and moving it to another component is done in a way that ensures there is always a child component noted as using the reparent. And for unreliable dynamic use and detachable use the owner can explicitly `.keep()` all the reparents that is still has a reference to.
+
 # Adoption strategy
 
 Reparents can be released in a feature release of React, there are no breaking changes.

From 3645e2e025dd22d0250051c174677d41373a2429 Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Wed, 28 Mar 2018 17:27:39 -0700
Subject: [PATCH 15/22] Fix anchor link

---
 text/0000-reparenting.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index 4efc4dd1..4531578f 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -415,7 +415,7 @@ This reparenting issue have been left alone for awhile. We have an RFC process n
 1 and 2 have a high enough value that it's ok for 3 to not function completely, where incomplete means:
 
 - The platform is non-dom and may not actually have a dom-like concept of moving a view from one parent to another.
-- Some of the state in the native element is lost when we use appendChild like focus, scroll, playing state (see [Limitations](#Limitations)).
+- Some of the state in the native element is lost when we use appendChild like focus, scroll, playing state (see [Limitations](#limitations)).
 
 More motivation can be found in past discussions on reparenting:
 

From d7dd61d1721a41b365e0cb8e6ee8e9f08b783ed9 Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Wed, 28 Mar 2018 17:27:53 -0700
Subject: [PATCH 16/22] Line wrap comments

---
 text/0000-reparenting.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index 4531578f..9a62b1a7 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -56,7 +56,8 @@ ReactDOM.render(
     </DetachableTree>,
     container);
 
-// The state tree of the reparent is what is retained, not the contents. So if you change the contents of the DetachableTree, then components unmount as normal
+// The state tree of the reparent is what is retained, not the contents.
+// So if you change the contents of the DetachableTree, then components unmount as normal
 ReactDOM.render(
     <DetachableTree show={true}>
         <Foo key={2} />
@@ -65,7 +66,8 @@ ReactDOM.render(
 // log: Unmounted
 // log: Mounted
 
-// But if you unmount the DetachableTree the reparent will unmount and all of the normal react elements inside will also unmount.
+// But if you unmount the DetachableTree the reparent will unmount
+// and all of the normal react elements inside will also unmount.
 ReactDOM.render(
     <div />,
     container);
@@ -382,7 +384,8 @@ let templateData = {
 
 ReactDOM.render(<Template {...templateData} />, app);
 
-// Modify the template to move widget:w-1 to section s-2, it should not be necessary to re-create widget w-1 from scratch
+// Modify the template to move widget:w-1 to section s-2,
+// it should not be necessary to re-create widget w-1 from scratch
 templateData = {
     sections: [
         {
@@ -611,7 +614,8 @@ class Template extends PureComponent {
 
         // Explicitly keep all the reparents we are using
         // - Even if a reparent kept here isn't used in a TemplateComponent is is still not unmounted
-        // - If a reparent from a previous render isn't kept here, then React knows we don't have a reference to it anymore so it can be unmounted and allowed to be garbage collected
+        // - If a reparent from a previous render isn't kept here, then React knows we don't have a reference to it anymore
+        //   so it can be unmounted and allowed to be garbage collected
         for ( const id in templateWidgetReparents ) {
             templateWidgetReparents[id].keep();
         }

From 425c5ee59b9c23b8ac954c72f49c07b8f854d6b0 Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Thu, 29 Mar 2018 13:08:19 -0700
Subject: [PATCH 17/22] Fix small coding mistake in the layout example

---
 text/0000-reparenting.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index 9a62b1a7..54715c85 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -102,7 +102,7 @@ class Layout extends PureComponent {
 
         const content = this.content(
             <Fragment>
-                children
+                {children}
             </Fragment>
         );
 

From 0a3b7d893b5af1b26d65c03423e6ec7f8c2784dd Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Thu, 29 Mar 2018 13:09:11 -0700
Subject: [PATCH 18/22] Move the simple layout example to the top of the list
 of examples

---
 text/0000-reparenting.md | 110 +++++++++++++++++++--------------------
 1 file changed, 55 insertions(+), 55 deletions(-)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index 54715c85..d191012a 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -10,6 +10,61 @@ The goal of this RFC is to introduce a "Reparent" API that allows portions of th
 
 # Basic example
 
+## Layout
+
+Using reparents to render a page layout that can change structure between desktop and mobile without causing the page contents and sidebar to be recreated from scratch.
+
+```js
+class Layout extends PureComponent {
+    header = React.createReparent(this);
+    content = React.createReparent(this);
+    sidebar = React.createReparent(this);
+
+    render() {
+        const {isMobile, children} = this.props;
+
+        const header = this.header(
+            <div className='header'>
+                <Logo />
+                <NavigationBar />
+            </div>
+        );
+
+        const sidebar = this.sidebar(
+            <div className='sidebar'>
+                <SidebarContent />
+            </div>
+        );
+
+        const content = this.content(
+            <Fragment>
+                {children}
+            </Fragment>
+        );
+
+        if ( isMobile ){
+            return (
+                <div>
+                    {header}
+                    {content}
+                    {sidebar}
+                </div>
+            );
+        } else {
+            return (
+                <div>
+                    {header}
+                    <div>
+                        {content}
+                        {sidebar}
+                    </div>
+                </div>
+            );
+        }
+    }
+}
+```
+
 ## Detach trees of dom nodes / components
 
 ```js
@@ -74,61 +129,6 @@ ReactDOM.render(
 // log: Unmounted
 ```
 
-## Layout
-
-Using reparents to render a page layout that can change structure between desktop and mobile without causing the page contents and sidebar to be recreated from scratch.
-
-```js
-class Layout extends PureComponent {
-    header = React.createReparent(this);
-    content = React.createReparent(this);
-    sidebar = React.createReparent(this);
-
-    render() {
-        const {isMobile, children} = this.props;
-
-        const header = this.header(
-            <div className='header'>
-                <Logo />
-                <NavigationBar />
-            </div>
-        );
-
-        const sidebar = this.sidebar(
-            <div className='sidebar'>
-                <SidebarContent />
-            </div>
-        );
-
-        const content = this.content(
-            <Fragment>
-                {children}
-            </Fragment>
-        );
-
-        if ( isMobile ){
-            return (
-                <div>
-                    {header}
-                    {content}
-                    {sidebar}
-                </div>
-            );
-        } else {
-            return (
-                <div>
-                    {header}
-                    <div>
-                        {content}
-                        {sidebar}
-                    </div>
-                </div>
-            );
-        }
-    }
-}
-```
-
 ## Table with movable cells
 
 Using dynamic reparents within a table to ensure that cells are not recreated from scratch when moved from one row to another.

From c137d412a0212ff136efb252779682c5ea4d56b2 Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Fri, 30 Mar 2018 20:43:29 -0700
Subject: [PATCH 19/22] Update RFC to propose .keep() instead of .unmount()

---
 text/0000-reparenting.md | 115 ++++++++-------------------------------
 1 file changed, 23 insertions(+), 92 deletions(-)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index d191012a..e3b19882 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -463,26 +463,29 @@ There are a variety of use cases for reparenting. Some of them have certain requ
 # Glossary
 
 - **state tree**: The state tree refers to both the tree of DOM nodes or other tree of native elements React is rendering to (for React Native and 3rd party environments) and the tree of React Components that allows React to reuse an instance of a Component on a future render.
-- **Reparent owner**: A reparent owner is the component passed to the `React.createReparent(component)` function. The owner does not have to be the one rendering the Reparent, you can pass the reparent down for a descendant to render, but it cannot be passed upwards to be rendered by a parent or cousin of the Reparent owner (notwithstanding use of Portals).
 - **global-ish key**: The global-ish key nature of reparents refers to how normally in react the string `key="..."` is only locally unique within its parent, but a reparent must be unique within any parent. Generally this would be though of as "globally unique", however because reparents have an owner they only actually need to be unique within the portion of the state tree under their owner.
 
 # Detailed design
 
-This proposal introduces a `React.createReparent(component)` function. It accepts a component instance (typically `this`) which is the reparent owner and returns a *Reparent*. The "Reparent" naming is open to better name proposals.
+This proposal introduces a `React.createReparent()` function which returns a new *Reparent*. The "Reparent" naming is open to better name proposals.
 
-A Reparent is tied to its owner, when its owner is unmounted the reparent is also unmounted and the detached state tree is discarded. This allows reparents to hold detached state trees without doing so in a permanent way that would leak memory.
+The Reparent itself is a function that accepts children for the reparent. The return value is a special Fragment used to render the reparent and its contents somewhere in the state tree.
 
-A Reparent has an additional `.unmount()` method, this can be used to force the reparent to unmount and discard its state tree like it would when it's owner unmounts, even when the owner is not unmounting. This allows reparents to be hoisted upwards by registering the Reparent in a parent Component and then passing the Reparent down to children through props or context for a descendant to render. And allows them to be used for dynamic content and explicitly unmounted when necessary (the descendant no longer needs the Reparent but the Reparent owner will not be unmounting). See the "Dynamic template" example.
+A Reparent has an additional `.keep()` method that acts like calling the Reparent function but without modifying children or returning the fragment. This function is used to allow components to tell reparents to hold references to state trees without actually rendering them and without doing so in a permanent way that would leak memory. This allows reparents to be hoisted upwards by registering the Reparent in a parent Component and then passing the Reparent down to children through props or context for a descendant to render. And allows them to be used for dynamic and async content where the reparent may not be rendered for a moment. See the "Dynamic template" example.
 
-The Reparent itself is a function that accepts children for the reparent. The return value is a special Fragment used to render the reparent and its contents somewhere in the state tree.
+When the Reparent function or its `.keep()` is called in a `render()` React notes that the component the `render()` belongs to "has a reference" to the reparent.
 
-When React intends to remove the dom/native tree rendered from this special fragment because it is not present in a later render, React instead detaches the tree and holds a reference to it in the Reparent instead of purging it. If a fragment returned by the reparent later is rendered by a component the detached dom/native tree is re-used.
+At the end of a render if no `render()` "has a reference" to the reparent then React will discard the state tree and unmount any components inside the reparent's children as normal.
 
-In addition to retaining the dom/native tree for future use the rest of the state tree belonging to the Reparent is also retained. Such that React Component instances present in a Reparent are not unmounted until the Reparent is rendered without them (explicitly discarding the component), the Reparent is unmounted via `.unmount()` (explicitly destroying the Reparent and its whole tree), or the Reparent is implicitly unmounted when its owner unmounts (implicitly destroying the Reparent and its whole tree).
+At the end of a render if at least one `render()` "has a reference" to the reparent but a fragment created by the reparent function is not present in the the result of any `render()` instead of discarding the state tree React will *detach* the state tree and keep a reference to it. React components in the children will not be unmounted. If the native tree can reasonably detached the renderer should make an effort to detach the tree. If the native tree does not have a concept of being detached and re-attached it is acceptable for the native tree to be removed and recreated later.
 
-Unlike a normal fragment the fragment returned by a reparent may only be used once in the entire state tree. If a fragment returned by a Reparent is used multiple times only the latest one will be rendered (they will not be duplicated as normal in React) and during development React may emit warnings that a reparent is used in multiple spots like the warnings when a duplicate key is found.
+For react-dom this means using `removeChild` to detach the dom tree and keeping a reference to it in memory to re-insert into the dom later with `appendChild`/`insertChild`. When React DOM intends to move a DOM node (because the Reparent from a previous calls to render has a different parent in the virtual DOM on a later render) React DOM should avoid using `removeChild` and instead just call `appendChild`/`insertChild` without first calling `removeChild` (unless it detects some sort of situation like a reference cycle that would make this impossible). This is an attempt to avoid some of the side effects of Reparenting, in particular it is to avoid IE11's behaviour of pausing a `<video>` when you `removeChild` then `appendChild` instead of just using `appendChild`.
+
+When a reparent is being moved or being detached and later reattached `getSnapshotBeforeUpdate` should be called before the component is moved or detached and `componentDidUpdate` should be called with the snapshot after the component is moved or re-attached. This will allow users to save and restore state that may be discarded by the native implementation when native trees are moved. See [Limitations](#limitations).
 
-When React DOM intends to detach a DOM node (because the Reparent from a previous call to render is no longer returned in the virtual DOM for a later render), it may use `removeChild` to detach the DOM node, but must retain a reference to it so it may be re-inserted later if the Reparent is rendered in a future render. However when React DOM intends to move a DOM node (because the Reparent from a previous calls to render has a different parent in the virtual DOM on a later render) React DOM should avoid using `removeChild` and instead just call `appendChild`/`insertChild` without first calling `removeChild` (unless it detects some sort of situation like a reference cycle that would make this impossible). This is an attempt to avoid some of the side effects of Reparenting, in particular it is to avoid IE11's behaviour of pausing a `<video>` when you `removeChild` then `appendChild` instead of just using `appendChild`.
+When a reparent's children are changed React removes and unmounts unused components as normal. References to children no longer used by the reparent are not retained unless the children are reparents that are themself still referenced by a `render()`.
+
+Unlike a normal fragment the fragment returned by a reparent may only be used once in the entire state tree. If a fragment returned by a Reparent is used multiple times only the latest one will be rendered (they will not be duplicated as normal in React) and during development React may emit warnings that a reparent is used in multiple spots like the warnings when a duplicate key is found.
 
 The fragment returned has an implicit key which is unique to the Reparent. A Reparent itself is like a key that is unique beyond just a single element's children so there is no need for the user to specify an additional key to use its contents in an array.
 
@@ -493,10 +496,11 @@ React.createReparent = function() {
     const key = generateUniqueKey();
 
     const Reparent = function(children) {
+        this.keep();
         return React.createElement(Fragment, {key}, children);
     };
-    Reparent.unmount = () => {
-        throw new Error('Not implemented');
+    Reparent.keep = () => {
+        console.warning('keep: Not implemented');
     };
 
     return Reparent;
@@ -508,7 +512,7 @@ And conforms to the following types/interface:
 ```js
 type ReparentFunction = (ReactNodeList) => ReactFragment;
 type ReparentObject = {
-    unmount(): void;
+    keep(): void;
 };
 type Reparent = ReparentFunction & ReparentObject;
 
@@ -527,10 +531,6 @@ Some DOM nodes have quirks they exhibit when they are moved from one parent DOM
 - The currently focused element will lose its focus if it is being moved.
 - Scrollable containers will lose their scroll position and reset to the initial scroll position when they are moved.
 
-# Drawbacks
-
-The `.unmount()` method is not necessarily perfect in identifying when a tree is detached but kept or discarded and to be unmounted. If someone chooses to use createReparent dynamically and forgets to call `.unmount()` they will leak memory.
-
 # Alternatives
 
 ## createKey
@@ -561,6 +561,12 @@ The createKey API could work, however it has some limitations that createReparen
 - While createKey and createReparent shares the same advantage that unmounting of its host results in unmounting of the reparentable root. contentKey does not have a secondary method of unmounting/discarding the tree. React cannot differentiate between a detached tree and a discarded/unmountable tree. As a result it cannot be used for varying numbers of reparentable roots as trees for discarded keys remain in memory as leaks.
 - createKey adds alternative behaviour using just the `key`, createReparent gives React internals more control in how it they decide to handle the link between the tree and the reparent.
 
+## .unmount()
+
+Originally this RFC proposed an imperative `.unmount()` in place of `.keep()`. `React.createReparent` would be called with `this` to give the reparent an owner. The reparent would unmount when its owner unmounts or could be explicitly unmounted with `.unmount()`.
+
+This proposal was replaced as `.keep()` has the advantage of not holding on to detached trees if the user forgot to unmount a dynamic reparent. And `.keep()` is compatible with more techniques and use cases.
+
 ## DetachedTree
 
 If `.unmount()` proves to be too complex it may be possible to make detached trees work with createReparent, createKey, or other global key methods by using a Fragment-like `<DetachedTree />` component which holds a reference to the detached tree in the React tree but omits it from the DOM. Then React knows it may unmount components and trees if it is not used as part of the live tree or in a DetachedTree.
@@ -586,54 +592,6 @@ class MyComponent extends Component {
 }
 ```
 
-## .keep()
-
-Another alternative to the imperative `.unmount()` would be to have a `.keep()` signal. Instead of explicitly unmounting a dynamic reparent, for a reparent to be retained, either the ReparentFunction must be called with contents during render or `.keep()` must be called during render. If neither of them happens React considers the reparent unused and unmounts its contents. The reparent can later be re-used, but a new state tree will be created.
-
-```js
-class Template extends PureComponent {
-    static getDerivedStateFromProps(nextProps, prevState) {
-        if ( nextProps.sections === prevState.sections ) return;
-
-        let templateWidgetReparents = Object.create(null);
-
-        nextProps.sections.forEach(section => {
-            section.widgets.forEach(widget => {
-                templateWidgetReparents[widget.id] = prevState.templateWidgetReparents[id][widget.id] || React.createReparent(this);
-            });
-        });
-
-        return {
-            templateWidgetReparents,
-        };
-    }
-
-    render() {
-        const {sections} = this.props;
-        const {templateWidgetReparents} = this.state;
-
-        // Explicitly keep all the reparents we are using
-        // - Even if a reparent kept here isn't used in a TemplateComponent is is still not unmounted
-        // - If a reparent from a previous render isn't kept here, then React knows we don't have a reference to it anymore
-        //   so it can be unmounted and allowed to be garbage collected
-        for ( const id in templateWidgetReparents ) {
-            templateWidgetReparents[id].keep();
-        }
-
-        return (
-            <TemplateWidgetReparentContext.Provider value={templateWidgetReparents}>
-                {sections.map(section => {
-                    <Section {...section} key={section.id} />
-                })}
-            </TemplateWidgetReparentContext.Provider>
-        );
-    }
-}
-```
-
-- Is calling `reparent(content)`/`reparent.keep()` in a child's `render()` enough? Or do we require that the owner itself must explicitly `.keep()` all reparents it intends to pass to children?
-- Perhaps we could keep a note in the state tree that a reparent is in use by a child component when it calls `reparent(content)` or `reparent.keep(this)` (this could be optional if we are fine with implicitly detecting the instance of the currently executing `render()`, but `this` is an option if we want to avoid that (string refs all over again). This would then ensure that the simple use case of passing a reparent to a child and moving it to another component is done in a way that ensures there is always a child component noted as using the reparent. And for unreliable dynamic use and detachable use the owner can explicitly `.keep()` all the reparents that is still has a reference to.
-
 # Adoption strategy
 
 Reparents can be released in a feature release of React, there are no breaking changes.
@@ -651,31 +609,4 @@ We may need a new documentation page to explain reparenting as one was added for
 - How do reparent instances interact with hydration?
   - Perhaps when hydrating the dom tree, portions of the dom tree that match up with portions of the virtual dom belonging to a reparent will be given to the Reparent to hydrate as its dom tree.
 - Should the Reparent function just accept a single children argument, or should it accept ...children rest and pass it on to createElement to behave similar to createElement.
-- If a Reparent is detached and it's DOM tree is detached from the document, should it render the children it is passed in the Reparent function; or should it save the most recent children value passed to it and wait till it is re-mounted before actually rendering those children?
-- Sometimes a pattern like this exists:
-
-  ```js
-  class Foo extends Component {
-    state = {
-      dialog: undefined,
-    };
-    setDialog = dialog => this.setState({dialog});
-    render() {
-      return (
-        <div>
-          <Bar setDialog={this.setDialog} />
-          {this.state.dialog}
-        </div>
-      );
-    }
-  }
-  class Bar extends Component {
-    componentDidMount() {
-      this.props.setDialog(<Baz />);
-    }
-    // ...
-  }
-  // ...
-  ```
-
-  If Bar were to create a reparent and use it as part of the tree passed to setDialog then technically the reparent would be used above its owner. Should we relax the wording of this RFC to permit this?
\ No newline at end of file
+- If a Reparent is detached and it's DOM tree is detached from the document, should it render the children it is passed in the Reparent function; or should it save the most recent children value passed to it and wait till it is re-mounted before actually rendering those children?
\ No newline at end of file

From 965ffaf4ac02b1b7103580df8af2e8ba79cffc6d Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Sun, 22 Apr 2018 22:12:16 -0700
Subject: [PATCH 20/22] Update getSnapshotBeforeUpdate reference to link to the
 React documentation

---
 text/0000-reparenting.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index e3b19882..3ddc40fc 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -523,7 +523,7 @@ interface React {
 
 # Limitations
 
-Some DOM nodes have quirks they exhibit when they are moved from one parent DOM node to another parent DOM node. These quirks are unavoidable and solving them is not part of the reparenting RFC. The benefits of having the option to reparent nodes if desired is still significant even given the limitations. Some of these quirks may be fixed by either making the state controlled (see [registered prop as ref](https://github.com/reactjs/rfcs/pull/28) for a possible solution for this) or by storing the state before the reparent and restoring it afterwards (see [getSnapshotBeforeUpdate](https://github.com/reactjs/rfcs/blob/master/text/0033-new-commit-phase-lifecycles.md) for a possible solution).
+Some DOM nodes have quirks they exhibit when they are moved from one parent DOM node to another parent DOM node. These quirks are unavoidable and solving them is not part of the reparenting RFC. The benefits of having the option to reparent nodes if desired is still significant even given the limitations. Some of these quirks may be fixed by either making the state controlled (see [registered prop as ref](https://github.com/reactjs/rfcs/pull/28) for a possible solution for this) or by storing the state before the reparent and restoring it afterwards using [getSnapshotBeforeUpdate](https://reactjs.org/docs/react-component.html#getsnapshotbeforeupdate) and `componentDidUpdate`'s `snapshot` argument.
 
 - `<video>`/`<audio>` elements may pause (Chrome exhibits this behaviour; IE11 only exhibits this behaviour if you `removeChild` before you `appendChild`/`insertChild`; Firefox and Safari do not exhibit this quirk)
 - `<iframe>` elements will refresh, completely losing their state. This is unavoidable. However, iframes have very limited use cases so those making use of iframes should be aware that they cannot move their iframes around unless they accept that it will refresh when they do.

From 323de7bb12f2d3c16267bd9eda7cad8d1e2f34ee Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Sun, 22 Apr 2018 22:44:15 -0700
Subject: [PATCH 21/22] Refactor code examples to use .keep() instead of
 .unmount()

---
 text/0000-reparenting.md | 43 ++++++++++++++++------------------------
 1 file changed, 17 insertions(+), 26 deletions(-)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index 3ddc40fc..7266b7cb 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -202,13 +202,6 @@ class TableWidget extends PureComponent {
 
     removeData(row, col) {
         this.setState(state => {
-            // Unmount the reparent so we don't leak memory
-            const cell = table.cells[from.row][from.col];
-            if ( this.cells[cell.id] ) {
-                this.cells[cell.id].unmount();
-                delete this.cells[cell.id];
-            }
-
             // Set the cell to null
             let {table} = state;
             table = update(table, {
@@ -323,34 +316,32 @@ class Template extends PureComponent {
         const widgetIds = new Set();
         nextProps.sections.forEach(section => section.widgets.forEach(widget => widgetIds.add(widget.id)));
 
+        const templateWidgetReparents = {};
+
+        for ( const id of widgetIds ) {
+            if ( prevState.templateWidgetReparents && prevState.templateWidgetReparents[id] ) {
+                templateWidgetReparents[id] = prevState.templateWidgetReparents[id];
+            } else {
+                templateWidgetReparents[id] = React.createReparent(this);
+            }
+        }
+
         return {
-            widgetIds: widgetIds.toArray(),
+            sections: nextProps.sections,
+            templateWidgetReparents,
         };
     }
 
-    templateWidgetReparents = {};
-
     render() {
-        const {sections} = this.props;
-        const {widgetIds} = this.state;
-
-        for ( const id of widgetIds ) {
-            if ( !(id in this.templateWidgetReparents) ) {
-                this.templateWidgetReparents = Object.assign(this.templateWidgetReparents, {
-                    [id]: React.createReparent(this),
-                });
-            }
-        }
+        const {sections, templateWidgetReparents} = this.state;
 
-        for ( const id in this.templateWidgetReparents ) {
-            if ( !widgetIds.has(id) ) {
-                this.templateWidgetReparents[id].unmount();
-                this.templateWidgetReparents = omit(this.templateWidgetReparents, id);
-            }
+        // Make sure React detaches trees for reparents we are still using instead of unmounting them
+        for ( const reparent of Object.values(templateWidgetReparents) ) {
+            reparent.keep();
         }
 
         return (
-            <TemplateWidgetReparentContext.Provider value={this.templateWidgetReparents}>
+            <TemplateWidgetReparentContext.Provider value={templateWidgetReparents}>
                 {sections.map(section => {
                     <Section {...section} key={section.id} />
                 })}

From 1201e2db27872560c3dab82f50201a1c763104e6 Mon Sep 17 00:00:00 2001
From: Daniel Friesen <daniel@nadir-seen-fire.com>
Date: Sat, 16 Jun 2018 11:37:54 -0700
Subject: [PATCH 22/22] Fix examples and protocols to remove the this:Component

this:Component was part of the `.unmount()` API, it's no longer used in the `.keep()` api.
---
 text/0000-reparenting.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/text/0000-reparenting.md b/text/0000-reparenting.md
index 7266b7cb..78aa8e69 100644
--- a/text/0000-reparenting.md
+++ b/text/0000-reparenting.md
@@ -16,9 +16,9 @@ Using reparents to render a page layout that can change structure between deskto
 
 ```js
 class Layout extends PureComponent {
-    header = React.createReparent(this);
-    content = React.createReparent(this);
-    sidebar = React.createReparent(this);
+    header = React.createReparent();
+    content = React.createReparent();
+    sidebar = React.createReparent();
 
     render() {
         const {isMobile, children} = this.props;
@@ -81,7 +81,7 @@ class Foo extends Component {
 }
 
 class DetachableTree extends Component {
-    reparent = React.createReparent(this);
+    reparent = React.createReparent();
 
     render() {
         const content = this.reparent(this.props.children);
@@ -220,7 +220,7 @@ class TableWidget extends PureComponent {
     // Dynamic store for reparents, the reparents are created as-needed for cells in the table
     cells = Object.create(null);
     getCell = (cell, row, col) => {
-        this.cells[cell.id] = this.cells[cell.id] || React.createReparent(this);
+        this.cells[cell.id] = this.cells[cell.id] || React.createReparent();
         return this.cells[cell.id](<Cell row={row} col={col} cell={cell} />);
     };
 
@@ -322,7 +322,7 @@ class Template extends PureComponent {
             if ( prevState.templateWidgetReparents && prevState.templateWidgetReparents[id] ) {
                 templateWidgetReparents[id] = prevState.templateWidgetReparents[id];
             } else {
-                templateWidgetReparents[id] = React.createReparent(this);
+                templateWidgetReparents[id] = React.createReparent();
             }
         }
 
@@ -508,7 +508,7 @@ type ReparentObject = {
 type Reparent = ReparentFunction & ReparentObject;
 
 interface React {
-    createReparent(Component): Reparent;
+    createReparent(): Reparent;
 }
 ```