Document event bubble order (#13546)

This is documenting the current order in which events are dispatched
when interacting with native document listeners and other React apps.

For more context, check out #12919.

Author: philipp-spiess

packages/react-dom/src/__tests__/ReactDOMComponent-test.js

@@ -2603,4 +2603,60 @@ describe('ReactDOMComponent', () => {
       expect(node.getAttribute('onx')).toBe('bar');
     });
   });
+
+  it('receives events in specific order', () => {
+    let eventOrder = [];
+    let track = tag => () => eventOrder.push(tag);
+    let outerRef = React.createRef();
+    let innerRef = React.createRef();
+
+    function OuterReactApp() {
+      return (
+        <div
+          ref={outerRef}
+          onClick={track('outer bubble')}
+          onClickCapture={track('outer capture')}
+        />
+      );
+    }
+
+    function InnerReactApp() {
+      return (
+        <div
+          ref={innerRef}
+          onClick={track('inner bubble')}
+          onClickCapture={track('inner capture')}
+        />
+      );
+    }
+
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+
+    try {
+      ReactDOM.render(<OuterReactApp />, container);
+      ReactDOM.render(<InnerReactApp />, outerRef.current);
+
+      document.addEventListener('click', track('document bubble'));
+      document.addEventListener('click', track('document capture'), true);
+
+      innerRef.current.click();
+
+      // The order we receive here is not ideal since it is expected that the
+      // capture listener fire before all bubble listeners. Other React apps
+      // might depend on this.
+      //
+      // @see https://github.com/facebook/react/pull/12919#issuecomment-395224674
+      expect(eventOrder).toEqual([
+        'document capture',
+        'inner capture',
+        'inner bubble',
+        'outer capture',
+        'outer bubble',
+        'document bubble',
+      ]);
+    } finally {
+      document.body.removeChild(container);
+    }
+  });
 });