@skyscanner/backpack-web 17.1.0-beta.1 → 17.1.0

package/bpk-react-utils/README.md

@@ -0,0 +1,249 @@
+# bpk-react-utils
+
+> Miscellaneous React based utilities for use in Backpack components.
+
+## Installation
+
+Check the main [Readme](https://github.com/skyscanner/backpack#usage) for a complete installation guide.
+
+## Portal.js
+
+Render's children into a new component tree and appends it to `document.body`. Useful for Modals, Popovers, Tooltips etc where
+it's necessary in overcoming z-index issues when absolutely positioning elements.
+
+### Usage
+
+```js
+import { Portal } from '@skyscanner/backpack-web/bpk-react-utils';
+import BpkButton from '@skyscanner/backpack-web/bpk-component-button';
+import { BpkCode } from '@skyscanner/backpack-web/bpk-component-code';
+import React, { Component } from 'react';
+
+class MyComponent extends Component {
+  constructor() {
+    super();
+
+    this.state = {
+      isOpen: false,
+    };
+
+  }
+
+  onOpen = () => {
+    this.setState({
+      isOpen: true,
+    });
+  }
+
+  onClose = () => {
+    this.setState({
+      isOpen: false,
+    });
+  }
+
+  render() {
+    return (
+      <div>
+        <BpkButton onClick={this.onOpen}>Open portal</BpkButton>
+        <Portal
+          isOpen={this.state.isOpen}
+          onClose={this.onClose}
+        >
+          <div>I'm now appended to <BpkCode>document.body</BpkCode></div>
+        </Portal>
+      </div>
+    );
+  }
+}
+```
+
+### Props
+
+| Property              | PropType                | Required | Default Value |
+| --------------------- | ----------------------- | -------- | ------------- |
+| children              | node                    | true     | -             |
+| isOpen                | bool                    | true     | -             |
+| beforeClose           | func                    | false    | null          |
+| onClose               | func                    | false    | noop          |
+| onOpen                | func                    | false    | noop          |
+| onRender              | func                    | false    | noop          |
+| renderTarget          | func                    | false    | null          |
+| target                | oneOf([function, node]) | false    | null          |
+| closeOnEscPressed     | bool                    | false    | true          |
+
+## `cssModules.js`
+
+A helpful utility which permits backwards compatibility with hard coded classes and [CSS modules](https://github.com/css-modules/css-modules).
+
+### Usage
+
+```js
+import React from 'react';
+import { cssModules } from '@skyscanner/backpack-web/bpk-react-utils';
+
+import STYLES from './MyComponent.scss';
+
+const getClassName = cssModules(STYLES);
+
+const MyComponent = (props) => (
+  <div className={getClassName('MyComponent')}>
+    <div className={getClassName('MyComponent__inner')}>
+      {props.children}
+    </div>
+  </div>
+);
+```
+
+With CSS modules:
+
+```html
+<div class="_35WloynrPDta8fhSfoHEgE">
+  <div class="_1ghNYY7jOYzUneVCT4piQ9">
+    Some text.
+  </div>
+</div>
+```
+
+Without CSS modules:
+
+```html
+<div class="MyComponent">
+  <div class="MyComponent__inner">
+    Some text.
+  </div>
+</div>
+```
+
+The returned function accepts multiple class names and ignores values other than strings. e.g:
+
+```js
+import { cssModules } from '@skyscanner/backpack-web/bpk-react-utils';
+
+import STYLES from './MyComponent.scss';
+
+const getClassNames = cssModules(STYLES);
+
+const MyComponent = (props) => (
+  <div className={getClassName('MyComponent', props.disabled && 'MyComponent--disabled')}>
+   {props.children}
+  </div>
+);
+```
+
+Will result in `MyComponent MyComponent--disabled` if `props.disabled` is true or `MyComponent` otherwise.
+
+## `TransitionInitialMount.js`
+
+A wrapper around `react-transition-group` which makes it easy to transition a
+components initial mount. All you need to provide is two class names and a timeout.
+
+### Usage
+
+```js
+import React from 'react';
+import { TransitionInitialMount } from '@skyscanner/backpack-web/bpk-react-utils';
+
+const MyComponent = (props) => (
+  <TransitionInitialMount
+    appearClassName="my-transition-class--appear"
+    appearActiveClassName="my-transition-class--appear-active"
+    transitionTimeout={300}
+  >
+    <div>Some text.</div>
+  </TransitionInitialMount>
+);
+```
+
+```scss
+@import '~bpk-mixins/index.scss';
+
+.my-transition-class {
+  transition: opacity $bpk-duration-sm ease-in-out;
+  opacity: 1;
+
+  &--appear {
+    opacity: 0;
+  }
+
+  &--appear-active {
+    opacity: 1;
+  }
+}
+```
+
+### Props
+
+| Property              | PropType | Required | Default Value |
+| --------------------- | -------- | -------- | ------------- |
+| children              | node     | true     | -             |
+| appearClassName       | string   | true     | -             |
+| appearActiveClassName | string   | true     | -             |
+| transitionTimeout     | number   | true     | -             |
+
+## `isRTL`
+
+Returns true if the browser is showing content right-to-left.
+
+### Usage
+
+```js
+import React from 'react';
+import { isRTL } from '@skyscanner/backpack-web/bpk-react-utils';
+
+if (isRTL()) {
+  // do RTL stuff
+} else {
+  // do LTR stuff
+}
+```
+
+## `isDeviceIphone`
+
+Returns true if the device is an iPhone.
+
+### Usage
+
+```js
+import React from 'react';
+import { isDeviceIphone } from '@skyscanner/backpack-web/bpk-react-utils';
+
+if (isDeviceIphone()) {
+  // do iPhone specific stuff
+} else {
+  // do other browser/device stuff
+}
+```
+
+## `isDeviceIpad`
+
+Returns true if the device is an iPad.
+
+### Usage
+
+```js
+import React from 'react';
+import { isDeviceIpad } from '@skyscanner/backpack-web/bpk-react-utils';
+
+if (isDeviceIpad()) {
+  // do iPad specific stuff
+} else {
+  // do other browser/device stuff
+}
+```
+
+## `isDeviceIos`
+
+Returns true if the platform is iOS (iPhone/iPad).
+
+### Usage
+
+```js
+import React from 'react';
+import { isDeviceIos } from '@skyscanner/backpack-web/bpk-react-utils';
+
+if (isDeviceIos()) {
+  // do iOS specific stuff
+} else {
+  // do other browser/device stuff
+}
+```

package/bpk-react-utils/index.js

@@ -1,78 +1,3 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "Portal", {
-  enumerable: true,
-  get: function () {
-    return _Portal.default;
-  }
-});
-Object.defineProperty(exports, "TransitionInitialMount", {
-  enumerable: true,
-  get: function () {
-    return _TransitionInitialMount.default;
-  }
-});
-Object.defineProperty(exports, "cssModules", {
-  enumerable: true,
-  get: function () {
-    return _cssModules.default;
-  }
-});
-exports.default = void 0;
-Object.defineProperty(exports, "deprecated", {
-  enumerable: true,
-  get: function () {
-    return _deprecated.default;
-  }
-});
-Object.defineProperty(exports, "isDeviceIos", {
-  enumerable: true,
-  get: function () {
-    return _deviceDetection.isDeviceIos;
-  }
-});
-Object.defineProperty(exports, "isDeviceIpad", {
-  enumerable: true,
-  get: function () {
-    return _deviceDetection.isDeviceIpad;
-  }
-});
-Object.defineProperty(exports, "isDeviceIphone", {
-  enumerable: true,
-  get: function () {
-    return _deviceDetection.isDeviceIphone;
-  }
-});
-Object.defineProperty(exports, "isRTL", {
-  enumerable: true,
-  get: function () {
-    return _isRTL.default;
-  }
-});
-Object.defineProperty(exports, "withDefaultProps", {
-  enumerable: true,
-  get: function () {
-    return _withDefaultProps.default;
-  }
-});
-Object.defineProperty(exports, "wrapDisplayName", {
-  enumerable: true,
-  get: function () {
-    return _wrapDisplayName.default;
-  }
-});
-var _wrapDisplayName = _interopRequireDefault(require("./src/wrapDisplayName"));
-var _Portal = _interopRequireDefault(require("./src/Portal"));
-var _TransitionInitialMount = _interopRequireDefault(require("./src/TransitionInitialMount"));
-var _cssModules = _interopRequireDefault(require("./src/cssModules"));
-var _deprecated = _interopRequireDefault(require("./src/deprecated"));
-var _deviceDetection = require("./src/deviceDetection");
-var _withDefaultProps = _interopRequireDefault(require("./src/withDefaultProps"));
-var _isRTL = _interopRequireDefault(require("./src/isRTL"));
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 /*
  * Backpack - Skyscanner's Design System
  *
@@ -90,16 +15,43 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-var _default = {
-  Portal: _Portal.default,
-  TransitionInitialMount: _TransitionInitialMount.default,
-  cssModules: _cssModules.default,
-  deprecated: _deprecated.default,
-  withDefaultProps: _withDefaultProps.default,
-  wrapDisplayName: _wrapDisplayName.default,
-  isDeviceIphone: _deviceDetection.isDeviceIphone,
-  isDeviceIpad: _deviceDetection.isDeviceIpad,
-  isDeviceIos: _deviceDetection.isDeviceIos,
-  isRTL: _isRTL.default
+
+/* @flow strict */
+
+import wrapDisplayName from './src/wrapDisplayName';
+import Portal from './src/Portal';
+import TransitionInitialMount from './src/TransitionInitialMount';
+import cssModules from './src/cssModules';
+import deprecated from './src/deprecated';
+import {
+  isDeviceIphone,
+  isDeviceIpad,
+  isDeviceIos,
+} from './src/deviceDetection';
+import withDefaultProps from './src/withDefaultProps';
+import isRTL from './src/isRTL';
+
+export {
+  Portal,
+  TransitionInitialMount,
+  cssModules,
+  deprecated,
+  withDefaultProps,
+  wrapDisplayName,
+  isDeviceIphone,
+  isDeviceIpad,
+  isDeviceIos,
+  isRTL,
+};
+export default {
+  Portal,
+  TransitionInitialMount,
+  cssModules,
+  deprecated,
+  withDefaultProps,
+  wrapDisplayName,
+  isDeviceIphone,
+  isDeviceIpad,
+  isDeviceIos,
+  isRTL,
 };
-exports.default = _default;

package/bpk-react-utils/src/Portal.js

@@ -1,14 +1,3 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-var _react = require("react");
-var _reactDom = require("react-dom");
-var _objectAssign = _interopRequireDefault(require("object-assign"));
-var _propTypes = _interopRequireDefault(require("prop-types"));
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 /*
  * Backpack - Skyscanner's Design System
  *
@@ -27,20 +16,29 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  * limitations under the License.
  */
 
+import { Component } from 'react';
+import { createPortal } from 'react-dom';
+import assign from 'object-assign';
+import PropTypes from 'prop-types';
+
 const KEYCODES = {
-  ESCAPE: 'Escape'
+  ESCAPE: 'Escape',
 };
-class Portal extends _react.Component {
+
+class Portal extends Component {
   constructor() {
     super();
+
     this.portalElement = null;
+
     this.state = {
-      isVisible: false
+      isVisible: false,
     };
 
     // shouldClose is used to keep track of the user's mouse-down events in order to
     // prevent the dialog closing if the mouse leaves / enters the portal during the click
     this.shouldClose = false;
+
     this.close = this.close.bind(this);
     this.onDocumentMouseUp = this.onDocumentMouseUp.bind(this);
     this.onDocumentMouseDown = this.onDocumentMouseDown.bind(this);
@@ -49,10 +47,12 @@ class Portal extends _react.Component {
     this.getClickEventProperties = this.getClickEventProperties.bind(this);
     this.supportsPassiveEvents = this.supportsPassiveEvents.bind(this);
   }
+
   componentDidMount() {
     if (this.props.isOpen) {
       this.open();
     }
+
     if (this.props.targetRef) {
       this.props.targetRef(this.getTargetElement());
     }
@@ -76,110 +76,161 @@ class Portal extends _react.Component {
       }
     }
   }
+
   componentWillUnmount() {
     this.close();
   }
+
   onDocumentMouseDown(event) {
     const clickEventProperties = this.getClickEventProperties(event);
-    if (clickEventProperties.isNotLeftClick || clickEventProperties.isTargetClick || clickEventProperties.isPortalClick) {
+    if (
+      clickEventProperties.isNotLeftClick ||
+      clickEventProperties.isTargetClick ||
+      clickEventProperties.isPortalClick
+    ) {
       this.shouldClose = false;
       return;
     }
+
     this.shouldClose = true;
   }
+
   onDocumentMouseUp(event) {
     const clickEventProperties = this.getClickEventProperties(event);
-    if (clickEventProperties.isNotLeftClick || clickEventProperties.isTargetClick || clickEventProperties.isPortalClick) {
+
+    if (
+      clickEventProperties.isNotLeftClick ||
+      clickEventProperties.isTargetClick ||
+      clickEventProperties.isPortalClick
+    ) {
       this.shouldClose = false;
       return;
     }
+
     if (this.shouldClose) {
       // `onClose` tells the consumer that they should change `isOpen` to false.
       // Once the consumer has responded to `onClose`, `beforeClose` and `close` will be called.
-      this.props.onClose(event, {
-        source: 'DOCUMENT_CLICK'
-      });
+      this.props.onClose(event, { source: 'DOCUMENT_CLICK' });
     }
   }
+
   onDocumentKeyDown(event) {
-    if (event.key === KEYCODES.ESCAPE && this.props.isOpen && this.props.closeOnEscPressed) {
+    if (
+      event.key === KEYCODES.ESCAPE &&
+      this.props.isOpen &&
+      this.props.closeOnEscPressed
+    ) {
       // `onClose` tells the consumer that they should change `isOpen` to false.
       // Once the consumer has responded to `onClose`, `beforeClose` and `close` will be called.
-      this.props.onClose(event, {
-        source: 'ESCAPE'
-      });
+      this.props.onClose(event, { source: 'ESCAPE' });
     }
   }
+
   onDocumentMouseMove() {
     this.shouldClose = false;
   }
+
   getClickEventProperties(event) {
     const isNotLeftClick = event.button && event.button !== 0;
+
     const targetElement = this.getTargetElement();
-    const isTargetClick = targetElement && event.target instanceof Node && (event.target === targetElement || targetElement.contains(event.target));
-    const isPortalClick = this.portalElement && event.target instanceof Node && (event.target === this.portalElement || this.portalElement.contains(event.target));
+    const isTargetClick =
+      targetElement &&
+      event.target instanceof Node &&
+      (event.target === targetElement || targetElement.contains(event.target));
+
+    const isPortalClick =
+      this.portalElement &&
+      event.target instanceof Node &&
+      (event.target === this.portalElement ||
+        this.portalElement.contains(event.target));
+
     return {
       isNotLeftClick: !!isNotLeftClick,
       isTargetClick: !!isTargetClick,
-      isPortalClick: !!isPortalClick
+      isPortalClick: !!isPortalClick,
     };
   }
+
   getTargetElement() {
-    return typeof this.props.target === 'function' ? this.props.target() : this.props.target?.ref.current;
+    return typeof this.props.target === 'function'
+      ? this.props.target()
+      : this.props.target?.ref.current;
   }
+
   getRenderTarget() {
-    const target = typeof this.props.renderTarget === 'function' ? this.props.renderTarget() : this.props.renderTarget;
+    const target =
+      typeof this.props.renderTarget === 'function'
+        ? this.props.renderTarget()
+        : this.props.renderTarget;
+
     if (target) {
       return target;
     }
     if (document.body) {
       return document.body;
     }
+
     throw new Error('Render target and fallback unavailable');
   }
+
   open() {
     if (this.portalElement) {
       return;
     }
+
     this.portalElement = document.createElement('div');
     this.getRenderTarget().appendChild(this.portalElement);
-    const passiveArgs = this.supportsPassiveEvents() ? {
-      passive: true
-    } : false;
-    document.addEventListener('touchstart', this.onDocumentMouseDown, passiveArgs);
-    document.addEventListener('touchmove', this.onDocumentMouseMove, passiveArgs);
+
+    const passiveArgs = this.supportsPassiveEvents()
+      ? { passive: true }
+      : false;
+    document.addEventListener(
+      'touchstart',
+      this.onDocumentMouseDown,
+      passiveArgs,
+    );
+    document.addEventListener(
+      'touchmove',
+      this.onDocumentMouseMove,
+      passiveArgs,
+    );
     document.addEventListener('touchend', this.onDocumentMouseUp, passiveArgs);
     document.addEventListener('mousedown', this.onDocumentMouseDown, false);
     document.addEventListener('mouseup', this.onDocumentMouseUp, false);
     document.addEventListener('keydown', this.onDocumentKeyDown, false);
+
     if (this.props.style) {
-      (0, _objectAssign.default)(this.portalElement.style, this.props.style);
+      assign(this.portalElement.style, this.props.style);
     }
+
     if (this.props.className) {
       this.portalElement.className = this.props.className;
     }
-    this.setState({
-      isVisible: true
-    }, () => this.props.onOpen(this.portalElement, this.getTargetElement()));
+    this.setState({ isVisible: true }, () =>
+      this.props.onOpen(this.portalElement, this.getTargetElement()),
+    );
   }
+
   close() {
     if (!this.portalElement) {
       return;
     }
+
     const renderTarget = this.getRenderTarget();
     if (renderTarget) {
       renderTarget.removeChild(this.portalElement);
     }
+
     document.removeEventListener('touchstart', this.onDocumentMouseDown);
     document.removeEventListener('touchmove', this.onDocumentMouseMove);
     document.removeEventListener('touchend', this.onDocumentMouseUp);
     document.removeEventListener('mousedown', this.onDocumentMouseDown);
     document.removeEventListener('mouseup', this.onDocumentMouseUp);
     document.removeEventListener('keydown', this.onDocumentKeyDown);
+
     this.portalElement = null;
-    this.setState({
-      isVisible: false
-    });
+    this.setState({ isVisible: false });
   }
 
   // This function is taken from modernizr
@@ -192,7 +243,7 @@ class Portal extends _react.Component {
         // eslint-disable-next-line getter-return
         get() {
           supportsPassiveOption = true;
-        }
+        },
       });
       window.addEventListener('test', null, opts);
     } catch (e) {
@@ -200,37 +251,37 @@ class Portal extends _react.Component {
     }
     return supportsPassiveOption;
   }
+
   render() {
     const {
       portalElement,
-      props: {
-        children
-      },
-      state: {
-        isVisible
-      }
+      props: { children },
+      state: { isVisible },
     } = this;
+
     if (!isVisible || !portalElement) {
       return null;
     }
-    return /*#__PURE__*/(0, _reactDom.createPortal)(children, portalElement);
+
+    return createPortal(children, portalElement);
   }
 }
+
 Portal.propTypes = {
-  children: _propTypes.default.node.isRequired,
-  isOpen: _propTypes.default.bool.isRequired,
-  beforeClose: _propTypes.default.func,
-  className: _propTypes.default.string,
-  onClose: _propTypes.default.func,
-  onOpen: _propTypes.default.func,
-  onRender: _propTypes.default.func,
-  style: _propTypes.default.object,
-  // eslint-disable-line react/forbid-prop-types
-  renderTarget: _propTypes.default.func,
-  target: _propTypes.default.oneOfType([_propTypes.default.func, _propTypes.default.node]),
-  targetRef: _propTypes.default.func,
-  closeOnEscPressed: _propTypes.default.bool
+  children: PropTypes.node.isRequired,
+  isOpen: PropTypes.bool.isRequired,
+  beforeClose: PropTypes.func,
+  className: PropTypes.string,
+  onClose: PropTypes.func,
+  onOpen: PropTypes.func,
+  onRender: PropTypes.func,
+  style: PropTypes.object, // eslint-disable-line react/forbid-prop-types
+  renderTarget: PropTypes.func,
+  target: PropTypes.oneOfType([PropTypes.func, PropTypes.node]),
+  targetRef: PropTypes.func,
+  closeOnEscPressed: PropTypes.bool,
 };
+
 Portal.defaultProps = {
   beforeClose: null,
   className: null,
@@ -241,7 +292,7 @@ Portal.defaultProps = {
   renderTarget: null,
   target: null,
   targetRef: null,
-  closeOnEscPressed: true
+  closeOnEscPressed: true,
 };
-var _default = Portal;
-exports.default = _default;
+
+export default Portal;