Uses new WindowEvent component for Flyout "close on ESC" (#1127)

* Adds new EuiWindowEvent component

* Switches flyout close on ESC to window event

* Removes old event listener on Flyout

* Adds EuiWindowEvent example to docs

* Updates changelog for EuiWindowEvent and Flyout changes

* Adds more clarification to WindowEvent example

* Moves WindowEvent to services folder

* Updates changelog to group changes correctly

* Adds more about how to use the EuiWindowEvent in example docs

* Rewrites examples for WindowEvent docs

* Adds EuiWindowEvent props to docs

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 - Added `zIndexAdjustment` to `EuiPopover` which allows tweaking the popover content's `z-index` ([#1097](https://github.com/elastic/eui/pull/1097))
 - Added new `EuiSuperSelect` component and `hasArrow` prop to `EuiPopover` ([#921](https://github.com/elastic/eui/pull/921))
+- Added a new `EuiWindowEvent` component for declarative, safe management of `window` event listeners ([#1127](https://github.com/elastic/eui/pull/1127))
+- Changed `Flyout` component to close on ESC keypress even if the flyout does not have focus, using new Window Event component ([#1127](https://github.com/elastic/eui/pull/1127))
 
 **Bug fixes**
 

src-docs/src/routes.js

@@ -216,6 +216,9 @@ import { ToolTipExample }
 import { ToggleExample }
   from './views/toggle/toggle_example';
 
+import { WindowEventExample }
+  from './views/window_event/window_event_example';
+
 import { XYChartExample }
   from './views/series_chart/series_chart_example';
 
@@ -395,6 +398,7 @@ const navigation = [{
     ToggleExample,
     UtilityClassesExample,
     MutationObserverExample,
+    WindowEventExample,
   ].map(example => createExample(example)),
 }, {
   name: 'Package',

src-docs/src/views/window_event/basic_window_event.js

@@ -0,0 +1,31 @@
+import React from 'react';
+
+import {
+  EuiModal,
+  EuiModalBody,
+  EuiModalHeader,
+  EuiModalHeaderTitle,
+  EuiOverlayMask
+} from '../../../../src/components';
+
+import { ModalExample } from './modal_example_container';
+
+const BasicModal = ({ onClose }) => (
+  <EuiOverlayMask>
+    <EuiModal
+      onClose={onClose}
+      style={{ width: '800px' }}
+    >
+      <EuiModalHeader>
+        <EuiModalHeaderTitle >
+          Example modal
+        </EuiModalHeaderTitle>
+      </EuiModalHeader>
+      <EuiModalBody>
+        <p>This modal closes when you press ESC, using a window event listener.</p>
+      </EuiModalBody>
+    </EuiModal>
+  </EuiOverlayMask>
+);
+
+export const BasicWindowEvent = () => <ModalExample modal={BasicModal} />;

src-docs/src/views/window_event/modal_example_container.js

@@ -0,0 +1,50 @@
+import React, { Component } from 'react';
+import {
+  EuiButton,
+} from '../../../../src/components';
+
+import {
+  EuiWindowEvent,
+} from '../../../../src/services';
+
+export class ModalExample extends Component {
+  constructor(props) {
+    super(props);
+
+    this.state = {
+      open: false
+    };
+
+    this.open = this.open.bind(this);
+    this.close = this.close.bind(this);
+    this.closeOnEscape = this.closeOnEscape.bind(this);
+  }
+
+  open() {
+    this.setState({ open: true });
+  }
+
+  close() {
+    if (this.state.open) {
+      this.setState({ open: false });
+    }
+  }
+
+  closeOnEscape({ key }) {
+    if (key === 'Escape') {
+      this.close();
+    }
+  }
+
+  render() {
+    const { modal: Modal, buttonText = 'Open Modal' } = this.props;
+    const button = <EuiButton onClick={this.open}>{buttonText}</EuiButton>;
+
+    return (
+      <div>
+        <EuiWindowEvent event="keydown" handler={this.closeOnEscape} />
+        {this.state.open ? <Modal onClose={this.close} /> : button}
+      </div>
+    );
+  }
+}

src-docs/src/views/window_event/mouse_position.js

@@ -0,0 +1,43 @@
+import React, { Component } from 'react';
+
+import {
+  EuiSwitch,
+  EuiDescriptionList,
+  EuiSpacer
+} from '../../../../src/components';
+
+import {
+  EuiWindowEvent,
+} from '../../../../src/services';
+
+export class MousePosition extends Component {
+
+  state = {
+    tracking: false,
+    coordinates: {}
+  };
+
+  onSwitchChange = () => this.setState((state) => ({ tracking: !state.tracking }));
+
+  onMouseMove = ({ clientX, clientY }) => this.setState({ coordinates: { clientX, clientY } });
+
+  render() {
+    const listItems = [
+      { title: 'Position X', description: this.state.coordinates.clientX || '??' },
+      { title: 'Position Y', description: this.state.coordinates.clientY || '??' }
+    ];
+    return (
+      <div>
+        <EuiSwitch
+          label="Track mouse position"
+          checked={this.state.tracking}
+          onChange={this.onSwitchChange}
+        />
+        {this.state.tracking ? <EuiWindowEvent event="mousemove" handler={this.onMouseMove} /> : null}
+        <EuiSpacer size="l" />
+        <EuiDescriptionList listItems={listItems} />
+        <EuiSpacer size="xxl" />
+      </div>
+    );
+  }
+}

src-docs/src/views/window_event/window_event_conflict.js

@@ -0,0 +1,65 @@
+import React from 'react';
+
+import {
+  EuiModal,
+  EuiModalBody,
+  EuiModalHeader,
+  EuiModalHeaderTitle,
+  EuiOverlayMask,
+  EuiFieldText,
+  EuiSpacer
+} from '../../../../src/components';
+
+import { ModalExample } from './modal_example_container';
+
+class ConflictModal extends React.Component {
+
+  constructor(props) {
+    super(props);
+
+    this.state = {
+      inputValue: ''
+    };
+  }
+
+  updateInputValue = e => this.setState({ inputValue: e.target.value });
+
+  clearInputValueOnEscape = e => {
+    if (e.key === 'Escape') {
+      this.setState({ inputValue: '' });
+      e.stopPropagation();
+    }
+  }
+
+  render() {
+    return (
+      <EuiOverlayMask>
+        <EuiModal
+          onClose={this.props.onClose}
+          style={{ width: '800px' }}
+        >
+          <EuiModalHeader>
+            <EuiModalHeaderTitle >
+              Example modal
+            </EuiModalHeaderTitle>
+          </EuiModalHeader>
+          <EuiModalBody>
+            <EuiFieldText
+              value={this.state.inputValue}
+              onChange={this.updateInputValue}
+              onKeyDown={this.clearInputValueOnEscape}
+            />
+            <EuiSpacer size="s" />
+            <p>While typing in this field, ESC will clear the field.</p>
+            <EuiSpacer size="l" />
+            <p>Otherwise, the event bubbles up to the window and ESC closes the modal.</p>
+          </EuiModalBody>
+        </EuiModal>
+      </EuiOverlayMask>
+    );
+  }
+}
+
+export const WindowEventConflict = () => (
+  <ModalExample modal={ConflictModal} buttonText="Open Modal with Conflicting Listener" />
+);

src-docs/src/views/window_event/window_event_example.js

@@ -0,0 +1,117 @@
+import React from 'react';
+
+import { renderToHtml } from '../../services';
+
+import {
+  GuideSectionTypes,
+} from '../../components';
+
+import {
+  EuiWindowEvent
+} from '../../../../src/services';
+
+import {
+  EuiCode,
+  EuiCallOut,
+  EuiSpacer
+} from '../../../../src/components';
+
+import { BasicWindowEvent } from './basic_window_event';
+const basicSource = require('!!raw-loader!./basic_window_event');
+const basicHtml = renderToHtml(BasicWindowEvent);
+
+import { WindowEventConflict } from './window_event_conflict';
+const conflictSource = require('!!raw-loader!./window_event_conflict');
+const conflictHtml = renderToHtml(WindowEventConflict);
+
+import { MousePosition } from './mouse_position';
+const mousePositionSource = require('!!raw-loader!./mouse_position');
+const mousePositionHtml = renderToHtml(MousePosition);
+
+export const WindowEventExample = {
+  title: 'Window Events',
+  sections: [
+    {
+      title: 'Basic example: closing a modal on escape',
+      source: [{
+        type: GuideSectionTypes.JS,
+        code: basicSource,
+      }, {
+        type: GuideSectionTypes.HTML,
+        code: basicHtml,
+      }],
+      text: (
+        <div>
+          <p>
+            Use an <EuiCode>EuiWindowEvent</EuiCode> to safely and declaratively manage adding and auto-removing event listeners
+            to the <EuiCode>window</EuiCode>. This is preferable to setting up your own window event listeners because it will remove
+            old listeners when your component unmounts, preventing you from accidentally leaving them around forever.
+          </p>
+          <p>
+            This modal example registers a listener on the <EuiCode>keydown</EuiCode> event and listens for ESC key presses,
+            which closes the open modal.
+          </p>
+        </div>
+      ),
+      components: { EuiWindowEvent },
+      props: { EuiWindowEvent },
+      demo: <BasicWindowEvent />,
+    },
+    {
+      title: 'Avoiding event conflicts',
+      source: [{
+        type: GuideSectionTypes.JS,
+        code: conflictSource,
+      }, {
+        type: GuideSectionTypes.HTML,
+        code: conflictHtml,
+      }],
+      text: (
+        <div>
+          <EuiCallOut
+            title="Be careful with global listeners"
+            color="warning"
+            iconType="alert"
+          >
+            <p>
+              Since window event listeners are global, they can conflict with other event listeners if you aren&apos;t careful.
+            </p>
+          </EuiCallOut>
+          <EuiSpacer />
+          <p>
+            The safest and best way to avoid these conflicts is to use <EuiCode>event.stopPropagation()</EuiCode> at the
+            lowest, most specific level where you are responding to a DOM event. This will prevent the event from bubbling
+            up to the window, and the <EuiCode>WindowEvent</EuiCode> listener will never be triggered, avoiding the conflict.
+          </p>
+        </div>
+      ),
+      components: { EuiWindowEvent },
+      demo: <WindowEventConflict />,
+    },
+    {
+      title: 'Tracking mouse position',
+      source: [{
+        type: GuideSectionTypes.JS,
+        code: mousePositionSource,
+      }, {
+        type: GuideSectionTypes.HTML,
+        code: mousePositionHtml,
+      }],
+      text: (
+        <div>
+          <p>
+            For some DOM events, you have to listen on the window. One example of this is tracking <em>mouse position</em>. Below,
+            when you click the toggle switch, your mouse position is tracked. When you toggle off, tracking stops.
+          </p>
+          <p>
+            If you were manually attaching window listeners, you might forget to remove the listener and be silently
+            responding to mouse events in the background for the life of your app. The <EuiCode>WindowEvent</EuiCode> component
+            manages that unmount/unregister process for you.
+          </p>
+        </div>
+      ),
+      components: { EuiWindowEvent },
+      demo: <MousePosition />,
+    }
+  ],
+};

src/components/flyout/flyout.js

@@ -3,7 +3,7 @@ import classnames from 'classnames';
 import PropTypes from 'prop-types';
 import FocusTrap from 'focus-trap-react';
 
-import { keyCodes } from '../../services';
+import { keyCodes, EuiWindowEvent } from '../../services';
 
 import { EuiOverlayMask } from '../overlay_mask';
 import { EuiButtonIcon } from '../button';
@@ -20,7 +20,6 @@ export class EuiFlyout extends Component {
   onKeyDown = event => {
     if (event.keyCode === keyCodes.ESCAPE) {
       event.preventDefault();
-      event.stopPropagation();
       this.props.onClose();
     }
   };
@@ -72,7 +71,6 @@ export class EuiFlyout extends Component {
         }}
         className={classes}
         tabIndex={0}
-        onKeyDown={this.onKeyDown}
         style={newStyle || style}
         {...rest}
       >
@@ -90,6 +88,7 @@ export class EuiFlyout extends Component {
 
     return (
       <span>
+        <EuiWindowEvent event="keydown" handler={this.onKeyDown} />
         {optionalOverlay}
         {/* Trap focus even when ownFocus={false}, otherwise closing the flyout won't return focus
         to the originating button */}

src/services/index.js

@@ -67,3 +67,7 @@ export {
   calculatePopoverPosition,
   findPopoverPosition,
 } from './popover';
+
+export {
+  EuiWindowEvent
+} from './window_event';

src/services/window_event/index.js

@@ -0,0 +1 @@
+export { default as EuiWindowEvent } from './window_event';