@khanacademy/wonder-blocks-clickable 2.1.2

package/dist/es/index.js

@@ -0,0 +1,712 @@
+import _objectWithoutPropertiesLoose from '@babel/runtime/helpers/objectWithoutPropertiesLoose';
+import _extends from '@babel/runtime/helpers/extends';
+import { Component, createElement } from 'react';
+import { StyleSheet } from 'aphrodite';
+import { any } from 'prop-types';
+import { withRouter, Link } from 'react-router-dom';
+import { addStyle } from '@khanacademy/wonder-blocks-core';
+import Color from '@khanacademy/wonder-blocks-color';
+
+const getAppropriateTriggersForRole = role => {
+  switch (role) {
+    // Triggers on ENTER, but not SPACE
+    case "link":
+      return {
+        triggerOnEnter: true,
+        triggerOnSpace: false
+      };
+    // Triggers on SPACE, but not ENTER
+
+    case "checkbox":
+    case "radio":
+    case "listbox":
+    case "option":
+      return {
+        triggerOnEnter: false,
+        triggerOnSpace: true
+      };
+    // Triggers on both ENTER and SPACE
+
+    case "button":
+    case "menuitem":
+    case "menu":
+    default:
+      return {
+        triggerOnEnter: true,
+        triggerOnSpace: true
+      };
+  }
+};
+
+const disabledHandlers = {
+  onClick: () => void 0,
+  onMouseEnter: () => void 0,
+  onMouseLeave: () => void 0,
+  onMouseDown: () => void 0,
+  onMouseUp: () => void 0,
+  onDragStart: () => void 0,
+  onTouchStart: () => void 0,
+  onTouchEnd: () => void 0,
+  onTouchCancel: () => void 0,
+  onKeyDown: () => void 0,
+  onKeyUp: () => void 0,
+  onFocus: () => void 0,
+  onBlur: () => void 0,
+  tabIndex: -1
+};
+const keyCodes = {
+  enter: 13,
+  space: 32
+};
+const startState = {
+  hovered: false,
+  focused: false,
+  pressed: false,
+  waiting: false
+};
+/**
+ * Add hover, focus, and active status updates to a clickable component.
+ *
+ * Via mouse:
+ *
+ * 1. Hover over button -> hover state
+ * 2. Mouse down -> active state
+ * 3. Mouse up -> default state
+ * 4. Press tab -> focus state
+ *
+ * Via touch:
+ *
+ * 1. Touch down -> press state
+ * 2. Touch up -> default state
+ *
+ * Via keyboard:
+ *
+ * 1. Tab to focus -> focus state
+ * 2. Keydown (spacebar/enter) -> active state
+ * 3. Keyup (spacebar/enter) -> focus state
+ *
+ * Warning: The event handlers returned (onClick, onMouseEnter, onMouseLeave,
+ * onMouseDown, onMouseUp, onDragStart, onTouchStart, onTouchEnd, onTouchCancel, onKeyDown,
+ * onKeyUp, onFocus, onBlur, tabIndex) should be passed on to the component
+ * that has the ClickableBehavior. You cannot override these handlers without
+ * potentially breaking the functionality of ClickableBehavior.
+ *
+ * There are internal props triggerOnEnter and triggerOnSpace that can be set
+ * to false if one of those keys shouldn't count as a click on this component.
+ * Be careful about setting those to false -- make certain that the component
+ * shouldn't process that key.
+ *
+ * See [this document](https://docs.google.com/document/d/1DG5Rg2f0cawIL5R8UqnPQpd7pbdObk8OyjO5ryYQmBM/edit#)
+ * for a more thorough explanation of expected behaviors and potential cavaets.
+ *
+ * `ClickableBehavior` accepts a function as `children` which is passed state
+ * and an object containing event handlers and some other props. The `children`
+ * function should return a clickable React Element of some sort.
+ *
+ * Example:
+ *
+ * ```js
+ * class MyClickableComponent extends React.Component<Props> {
+ *     render(): React.Node {
+ *         const ClickableBehavior = getClickableBehavior();
+ *         return <ClickableBehavior
+ *             disabled={this.props.disabled}
+ *             onClick={this.props.onClick}
+ *         >
+ *             {({hovered}, childrenProps) =>
+ *                 <RoundRect
+ *                      textcolor='white'
+ *                      backgroundColor={hovered ? 'red' : 'blue'}}
+ *                      {...childrenProps}
+ *                 >
+ *                      {this.props.children}
+ *                 </RoundRect>
+ *             }
+ *         </ClickableBehavior>
+ *     }
+ * }
+ * ```
+ *
+ * This follows a pattern called [Function as Child Components]
+ * (https://medium.com/merrickchristensen/function-as-child-components-5f3920a9ace9).
+ *
+ * WARNING: Do not use this component directly, use getClickableBehavior
+ * instead. getClickableBehavior takes three arguments (href, directtNav, and
+ * router) and returns either the default ClickableBehavior or a react-router
+ * aware version.
+ *
+ * The react-router aware version is returned if `router` is a react-router-dom
+ * router, `skipClientNav` is not `true`, and `href` is an internal URL.
+ *
+ * The `router` can be accessed via this.context.router from a component
+ * rendered as a descendant of a BrowserRouter.
+ * See https://reacttraining.com/react-router/web/guides/basic-components.
+ */
+
+class ClickableBehavior extends Component {
+  static getDerivedStateFromProps(props, state) {
+    // If new props are disabled, reset the hovered/focused/pressed states
+    if (props.disabled) {
+      return startState;
+    } else {
+      // Cannot return undefined
+      return null;
+    }
+  }
+
+  constructor(props) {
+    super(props);
+
+    this.handleClick = e => {
+      const {
+        onClick = undefined,
+        beforeNav = undefined,
+        safeWithNav = undefined
+      } = this.props;
+
+      if (this.enterClick) {
+        return;
+      }
+
+      if (onClick || beforeNav || safeWithNav) {
+        this.waitingForClick = false;
+      }
+
+      this.runCallbackAndMaybeNavigate(e);
+    };
+
+    this.handleMouseEnter = e => {
+      // When the left button is pressed already, we want it to be pressed
+      if (e.buttons === 1) {
+        this.dragging = true;
+        this.setState({
+          pressed: true
+        });
+      } else if (!this.waitingForClick) {
+        this.setState({
+          hovered: true
+        });
+      }
+    };
+
+    this.handleMouseLeave = () => {
+      if (!this.waitingForClick) {
+        this.dragging = false;
+        this.setState({
+          hovered: false,
+          pressed: false,
+          focused: false
+        });
+      }
+    };
+
+    this.handleMouseDown = () => {
+      this.setState({
+        pressed: true
+      });
+    };
+
+    this.handleMouseUp = e => {
+      if (this.dragging) {
+        this.dragging = false;
+        this.handleClick(e);
+      }
+
+      this.setState({
+        pressed: false,
+        focused: false
+      });
+    };
+
+    this.handleDragStart = e => {
+      this.dragging = true;
+      e.preventDefault();
+    };
+
+    this.handleTouchStart = () => {
+      this.setState({
+        pressed: true
+      });
+    };
+
+    this.handleTouchEnd = () => {
+      this.setState({
+        pressed: false
+      });
+      this.waitingForClick = true;
+    };
+
+    this.handleTouchCancel = () => {
+      this.setState({
+        pressed: false
+      });
+      this.waitingForClick = true;
+    };
+
+    this.handleKeyDown = e => {
+      const {
+        onKeyDown,
+        role
+      } = this.props;
+
+      if (onKeyDown) {
+        onKeyDown(e);
+      }
+
+      const keyCode = e.which || e.keyCode;
+      const {
+        triggerOnEnter,
+        triggerOnSpace
+      } = getAppropriateTriggersForRole(role);
+
+      if (triggerOnEnter && keyCode === keyCodes.enter || triggerOnSpace && keyCode === keyCodes.space) {
+        // This prevents space from scrolling down. It also prevents the
+        // space and enter keys from triggering click events. We manually
+        // call the supplied onClick and handle potential navigation in
+        // handleKeyUp instead.
+        e.preventDefault();
+        this.setState({
+          pressed: true
+        });
+      } else if (!triggerOnEnter && keyCode === keyCodes.enter) {
+        // If the component isn't supposed to trigger on enter, we have to
+        // keep track of the enter keydown to negate the onClick callback
+        this.enterClick = true;
+      }
+    };
+
+    this.handleKeyUp = e => {
+      const {
+        onKeyUp,
+        role
+      } = this.props;
+
+      if (onKeyUp) {
+        onKeyUp(e);
+      }
+
+      const keyCode = e.which || e.keyCode;
+      const {
+        triggerOnEnter,
+        triggerOnSpace
+      } = getAppropriateTriggersForRole(role);
+
+      if (triggerOnEnter && keyCode === keyCodes.enter || triggerOnSpace && keyCode === keyCodes.space) {
+        this.setState({
+          pressed: false,
+          focused: true
+        });
+        this.runCallbackAndMaybeNavigate(e);
+      } else if (!triggerOnEnter && keyCode === keyCodes.enter) {
+        this.enterClick = false;
+      }
+    };
+
+    this.handleFocus = e => {
+      this.setState({
+        focused: true
+      });
+    };
+
+    this.handleBlur = e => {
+      this.setState({
+        focused: false,
+        pressed: false
+      });
+    };
+
+    this.state = startState;
+    this.waitingForClick = false;
+    this.enterClick = false;
+    this.dragging = false;
+  }
+
+  navigateOrReset(shouldNavigate) {
+    if (shouldNavigate) {
+      const {
+        history,
+        href,
+        skipClientNav,
+        target = undefined
+      } = this.props;
+
+      if (href) {
+        if (target === "_blank") {
+          window.open(href, "_blank");
+          this.setState({
+            waiting: false
+          });
+        } else if (history && !skipClientNav) {
+          history.push(href);
+          this.setState({
+            waiting: false
+          });
+        } else {
+          window.location.assign(href); // We don't bother clearing the waiting state, the full page
+          // load navigation will do that for us by loading a new page.
+        }
+      }
+    } else {
+      this.setState({
+        waiting: false
+      });
+    }
+  }
+
+  handleSafeWithNav(safeWithNav, shouldNavigate) {
+    const {
+      skipClientNav,
+      history
+    } = this.props;
+
+    if (history && !skipClientNav || this.props.target === "_blank") {
+      // client-side nav
+      safeWithNav();
+      this.navigateOrReset(shouldNavigate);
+      return Promise.resolve();
+    } else {
+      if (!this.state.waiting) {
+        // We only show the spinner for safeWithNav when doing
+        // a full page load navigation since since the spinner is
+        // indicating that we're waiting for navigation to occur.
+        this.setState({
+          waiting: true
+        });
+      }
+
+      return safeWithNav().then(() => {
+        if (!this.state.waiting) {
+          // We only show the spinner for safeWithNav when doing
+          // a full page load navigation since since the spinner is
+          // indicating that we're waiting for navigation to occur.
+          this.setState({
+            waiting: true
+          });
+        }
+
+        return;
+      }).catch(error => {// We ignore the error here so that we always
+        // navigate when using safeWithNav regardless of
+        // whether we're doing a client-side nav or not.
+      }).finally(() => {
+        this.navigateOrReset(shouldNavigate);
+      });
+    }
+  }
+
+  runCallbackAndMaybeNavigate(e) {
+    const {
+      onClick = undefined,
+      beforeNav = undefined,
+      safeWithNav = undefined,
+      href,
+      type
+    } = this.props;
+    let shouldNavigate = true;
+    let canSubmit = true;
+
+    if (onClick) {
+      onClick(e);
+    } // If onClick() has called e.preventDefault() then we shouldn't
+    // navigate.
+
+
+    if (e.defaultPrevented) {
+      shouldNavigate = false;
+      canSubmit = false;
+    }
+
+    e.preventDefault();
+
+    if (!href && type === "submit" && canSubmit) {
+      let target = e.currentTarget;
+
+      while (target) {
+        if (target instanceof window.HTMLFormElement) {
+          // This event must be marked as cancelable otherwise calling
+          // e.preventDefault() on it won't do anything in Firefox.
+          // Chrome and Safari allow calling e.preventDefault() on
+          // non-cancelable events, but really they shouldn't.
+          const event = new window.Event("submit", {
+            cancelable: true
+          });
+          target.dispatchEvent(event);
+          break;
+        } // All events should be typed as SyntheticEvent<HTMLElement>.
+        // Updating all of the places will take some time so I'll do
+        // this later
+        // $FlowFixMe[prop-missing]
+
+
+        target = target.parentElement;
+      }
+    }
+
+    if (beforeNav) {
+      this.setState({
+        waiting: true
+      });
+      beforeNav().then(() => {
+        if (safeWithNav) {
+          return this.handleSafeWithNav(safeWithNav, shouldNavigate);
+        } else {
+          return this.navigateOrReset(shouldNavigate);
+        }
+      }).catch(() => {});
+    } else if (safeWithNav) {
+      return this.handleSafeWithNav(safeWithNav, shouldNavigate);
+    } else {
+      this.navigateOrReset(shouldNavigate);
+    }
+  }
+
+  render() {
+    const childrenProps = this.props.disabled ? disabledHandlers : {
+      onClick: this.handleClick,
+      onMouseEnter: this.handleMouseEnter,
+      onMouseLeave: this.handleMouseLeave,
+      onMouseDown: this.handleMouseDown,
+      onMouseUp: this.handleMouseUp,
+      onDragStart: this.handleDragStart,
+      onTouchStart: this.handleTouchStart,
+      onTouchEnd: this.handleTouchEnd,
+      onTouchCancel: this.handleTouchCancel,
+      onKeyDown: this.handleKeyDown,
+      onKeyUp: this.handleKeyUp,
+      onFocus: this.handleFocus,
+      onBlur: this.handleBlur,
+      // We set tabIndex to 0 so that users can tab to clickable
+      // things that aren't buttons or anchors.
+      tabIndex: 0
+    }; // When the link is set to open in a new window, we want to set some
+    // `rel` attributes. This is to ensure that the links we're sending folks
+    // to can't hijack the existing page.  These defaults can be overriden
+    // by passing in a different value for the `rel` prop.
+    // More info: https://www.jitbit.com/alexblog/256-targetblank---the-most-underestimated-vulnerability-ever/
+
+    childrenProps.rel = this.props.rel || (this.props.target === "_blank" ? "noopener noreferrer" : undefined);
+    const {
+      children
+    } = this.props;
+    return children && children(this.state, childrenProps);
+  }
+
+}
+ClickableBehavior.defaultProps = {
+  disabled: false
+};
+
+/**
+ * Returns:
+ * - false for hrefs staring with http://, https://, //.
+ * - false for '#', 'javascript:...', 'mailto:...', 'tel:...', etc.
+ * - true for all other values, e.g. /foo/bar
+ */
+const isClientSideUrl = href => {
+  if (typeof href !== "string") {
+    return false;
+  }
+
+  return !/^(https?:)?\/\//i.test(href) && !/^([^#]*#[\w-]*|[\w\-.]+:)/.test(href);
+};
+
+/**
+ * Returns either the default ClickableBehavior or a react-router aware version.
+ *
+ * The react-router aware version is returned if `router` is a react-router-dom
+ * router, `skipClientNav` is not `true`, and `href` is an internal URL.
+ *
+ * The `router` can be accessed via this.context.router from a component rendered
+ * as a descendant of a BrowserRouter.
+ * See https://reacttraining.com/react-router/web/guides/basic-components.
+ */
+const ClickableBehaviorWithRouter = withRouter(ClickableBehavior);
+function getClickableBehavior(
+/**
+ * The URL to navigate to.
+ */
+href,
+/**
+ * Should we skip using the react router and go to the page directly.
+ */
+skipClientNav,
+/**
+ * router object added to the React context object by react-router-dom.
+ */
+router) {
+  if (router && skipClientNav !== true && href && isClientSideUrl(href)) {
+    // We cast to `any` here since the type of ClickableBehaviorWithRouter
+    // is slightly different from the return type of this function.
+    // TODO(WB-1037): Always return the wrapped version once all routes have
+    // been ported to the app-shell in webapp.
+    return ClickableBehaviorWithRouter;
+  }
+
+  return ClickableBehavior;
+}
+
+const _excluded = ["href", "onClick", "skipClientNav", "beforeNav", "safeWithNav", "style", "target", "testId", "onKeyDown", "onKeyUp", "hideDefaultFocusRing", "light", "disabled"];
+const StyledAnchor = addStyle("a");
+const StyledButton = addStyle("button");
+const StyledLink = addStyle(Link);
+/**
+ * A component to turn any custom component into a clickable one.
+ *
+ * Works by wrapping ClickableBehavior around the child element and styling the
+ * child appropriately and encapsulates routing logic which can be customized.
+ * Expects a function which returns an element as it's child.
+ *
+ * Example usage:
+ * ```jsx
+ * <Clickable onClick={() => alert("You clicked me!")}>
+ *     {({hovered, focused, pressed}) =>
+ *         <div
+ *             style={[
+ *                 hovered && styles.hovered,
+ *                 focused && styles.focused,
+ *                 pressed && styles.pressed,
+ *             ]}
+ *         >
+ *             Click Me!
+ *         </div>
+ *     }
+ * </Clickable>
+ * ```
+ */
+
+class Clickable extends Component {
+  constructor(...args) {
+    super(...args);
+
+    this.getCorrectTag = (clickableState, commonProps) => {
+      const activeHref = this.props.href && !this.props.disabled;
+      const useClient = this.context.router && !this.props.skipClientNav && isClientSideUrl(this.props.href || ""); // NOTE: checking this.props.href here is redundant, but flow
+      // needs it to refine this.props.href to a string.
+
+      if (activeHref && useClient && this.props.href) {
+        return /*#__PURE__*/createElement(StyledLink, _extends({}, commonProps, {
+          to: this.props.href,
+          role: this.props.role,
+          target: this.props.target || undefined,
+          "aria-disabled": this.props.disabled ? "true" : undefined
+        }), this.props.children(clickableState));
+      } else if (activeHref && !useClient) {
+        return /*#__PURE__*/createElement(StyledAnchor, _extends({}, commonProps, {
+          href: this.props.href,
+          role: this.props.role,
+          target: this.props.target || undefined,
+          "aria-disabled": this.props.disabled ? "true" : undefined
+        }), this.props.children(clickableState));
+      } else {
+        return /*#__PURE__*/createElement(StyledButton, _extends({}, commonProps, {
+          type: "button",
+          disabled: this.props.disabled
+        }), this.props.children(clickableState));
+      }
+    };
+  }
+
+  render() {
+    const _this$props = this.props,
+          {
+      href,
+      onClick,
+      skipClientNav,
+      beforeNav = undefined,
+      safeWithNav = undefined,
+      style,
+      target = undefined,
+      testId,
+      onKeyDown,
+      onKeyUp,
+      hideDefaultFocusRing,
+      light,
+      disabled
+    } = _this$props,
+          restProps = _objectWithoutPropertiesLoose(_this$props, _excluded);
+
+    const ClickableBehavior = getClickableBehavior(href, skipClientNav, this.context.router);
+
+    const getStyle = state => [styles.reset, styles.link, !hideDefaultFocusRing && state.focused && (light ? styles.focusedLight : styles.focused), style];
+
+    if (beforeNav) {
+      return /*#__PURE__*/createElement(ClickableBehavior, {
+        href: href,
+        onClick: onClick,
+        beforeNav: beforeNav,
+        safeWithNav: safeWithNav,
+        onKeyDown: onKeyDown,
+        onKeyUp: onKeyUp,
+        disabled: disabled
+      }, (state, childrenProps) => this.getCorrectTag(state, _extends({}, restProps, {
+        "data-test-id": testId,
+        style: getStyle(state)
+      }, childrenProps)));
+    } else {
+      return /*#__PURE__*/createElement(ClickableBehavior, {
+        href: href,
+        onClick: onClick,
+        safeWithNav: safeWithNav,
+        onKeyDown: onKeyDown,
+        onKeyUp: onKeyUp,
+        target: target,
+        disabled: disabled
+      }, (state, childrenProps) => this.getCorrectTag(state, _extends({}, restProps, {
+        "data-test-id": testId,
+        style: getStyle(state)
+      }, childrenProps)));
+    }
+  }
+
+} // Source:  https://gist.github.com/MoOx/9137295
+
+Clickable.contextTypes = {
+  router: any
+};
+Clickable.defaultProps = {
+  light: false,
+  disabled: false,
+  "aria-label": ""
+};
+const styles = StyleSheet.create({
+  reset: {
+    border: "none",
+    margin: 0,
+    padding: 0,
+    width: "auto",
+    overflow: "visible",
+    background: "transparent",
+    textDecoration: "none",
+
+    /* inherit font & color from ancestor */
+    color: "inherit",
+    font: "inherit",
+    boxSizing: "border-box",
+    // This removes the 300ms click delay on mobile browsers by indicating that
+    // "double-tap to zoom" shouldn't be used on this element.
+    touchAction: "manipulation",
+    userSelect: "none",
+    // This is usual frowned upon b/c of accessibility.  We expect users of Clickable
+    // to define their own focus styles.
+    outline: "none",
+
+    /* Normalize `line-height`. Cannot be changed from `normal` in Firefox 4+. */
+    lineHeight: "normal",
+
+    /* Corrects font smoothing for webkit */
+    WebkitFontSmoothing: "inherit",
+    MozOsxFontSmoothing: "inherit"
+  },
+  link: {
+    cursor: "pointer"
+  },
+  focused: {
+    outline: `solid 2px ${Color.blue}`
+  },
+  focusedLight: {
+    outline: `solid 2px ${Color.white}`
+  }
+});
+
+export default Clickable;
+export { ClickableBehavior, getClickableBehavior, isClientSideUrl };