From 0616a5eddbbc8f4a12c71ef01b76e44adf4b7968 Mon Sep 17 00:00:00 2001
From: Philipp Spiess <hello@philippspiess.com>
Date: Mon, 3 Sep 2018 21:22:37 +0200
Subject: [PATCH] Document event bubble order

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.
---
 .../src/__tests__/ReactDOMComponent-test.js   | 57 +++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/packages/react-dom/src/__tests__/ReactDOMComponent-test.js b/packages/react-dom/src/__tests__/ReactDOMComponent-test.js
index b83ce5d5e1f36..a9dc6fdc915de 100644
--- a/packages/react-dom/src/__tests__/ReactDOMComponent-test.js
+++ b/packages/react-dom/src/__tests__/ReactDOMComponent-test.js
@@ -2603,4 +2603,61 @@ 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);
+    }
+  });
 });