@khanacademy/wonder-blocks-tooltip 1.3.0

package/src/components/tooltip-anchor.js

@@ -0,0 +1,330 @@
+// @flow
+/**
+ * This component turns the given content into an accessible anchor for
+ * positioning and displaying tooltips.
+ */
+import * as React from "react";
+import * as ReactDOM from "react-dom";
+
+import {Text as WBText} from "@khanacademy/wonder-blocks-core";
+import type {IIdentifierFactory} from "@khanacademy/wonder-blocks-core";
+
+import ActiveTracker from "../util/active-tracker.js";
+import {
+    TooltipAppearanceDelay,
+    TooltipDisappearanceDelay,
+} from "../util/constants.js";
+
+import type {IActiveTrackerSubscriber} from "../util/active-tracker.js";
+
+type Props = {|
+    /**
+     * The content for anchoring the tooltip.
+     * This element will be used to position the tooltip.
+     * If a string is passed as children we wrap it in a Text element.
+     * We allow children to be a string so that we can add tooltips to
+     * words within a large block of text easily.
+     */
+    children: React.Element<any> | string,
+
+    /**
+     * Callback to be invoked when the anchored content is mounted.
+     * This provides a reference to the anchored content, which can then be
+     * used for calculating tooltip bubble positioning.
+     */
+    anchorRef: (?Element) => mixed,
+
+    /**
+     * When true, if a tabindex attribute is not already present on the element
+     * wrapped by the anchor, the element will be given tabindex=0 to make it
+     * keyboard focusable; otherwise, does not attempt to change the ability to
+     * focus the anchor element.
+     *
+     * Defaults to true.
+     *
+     * One might set this to false in circumstances where the wrapped component
+     * already can receive focus or contains an element that can.
+     * Use good judgement when overriding this value, the tooltip content should
+     * be accessible via keyboard in all circumstances where the tooltip would
+     * appear using the mouse, so verify those use-cases.
+     */
+    forceAnchorFocusivity?: boolean,
+
+    /**
+     * Callback to pass active state back to Tooltip.
+     *
+     * `active` will be true whenever the anchor is hovered or focused and false
+     * otherwise.
+     */
+    onActiveChanged: (active: boolean) => mixed,
+
+    /**
+     * Optional unique id factory.
+     */
+    ids?: IIdentifierFactory,
+|};
+
+type DefaultProps = {|
+    forceAnchorFocusivity: $PropertyType<Props, "forceAnchorFocusivity">,
+|};
+
+type State = {|
+    /** Is the anchor active or not? */
+    active: boolean,
+|};
+
+const TRACKER = new ActiveTracker();
+
+export default class TooltipAnchor
+    extends React.Component<Props, State>
+    implements IActiveTrackerSubscriber {
+    _weSetFocusivity: ?boolean;
+    _anchorNode: ?Element;
+    _focused: boolean;
+    _hovered: boolean;
+    _stolenFromUs: boolean;
+    _unsubscribeFromTracker: ?() => void;
+    _timeoutID: ?TimeoutID;
+
+    static defaultProps: DefaultProps = {
+        forceAnchorFocusivity: true,
+    };
+
+    constructor(props: Props) {
+        super(props);
+
+        this._focused = false;
+        this._hovered = false;
+        this.state = {
+            active: false,
+        };
+    }
+
+    componentDidMount() {
+        const anchorNode = ReactDOM.findDOMNode(this);
+
+        // This should never happen, but we have this check here to make flow
+        // happy and ensure that if this does happen, we'll know about it.
+        if (anchorNode instanceof Text) {
+            throw new Error(
+                "TooltipAnchor must be applied to an Element. Text content is not supported.",
+            );
+        }
+
+        this._unsubscribeFromTracker = TRACKER.subscribe(this);
+        this._anchorNode = anchorNode;
+        this._updateFocusivity();
+        if (anchorNode) {
+            /**
+             * TODO(somewhatabstract): Work out how to allow pointer to go over
+             * the tooltip content to keep it active. This likely requires
+             * pointer events but that would break the obscurement checks we do.
+             * So, careful consideration required. See WB-302.
+             */
+            anchorNode.addEventListener("focusin", this._handleFocusIn);
+            anchorNode.addEventListener("focusout", this._handleFocusOut);
+            anchorNode.addEventListener("mouseenter", this._handleMouseEnter);
+            anchorNode.addEventListener("mouseleave", this._handleMouseLeave);
+
+            this.props.anchorRef(this._anchorNode);
+        }
+    }
+
+    componentDidUpdate(prevProps: Props) {
+        if (
+            prevProps.forceAnchorFocusivity !==
+                this.props.forceAnchorFocusivity ||
+            prevProps.children !== this.props.children
+        ) {
+            this._updateFocusivity();
+        }
+    }
+
+    componentWillUnmount() {
+        if (this._unsubscribeFromTracker) {
+            this._unsubscribeFromTracker();
+        }
+        this._clearPendingAction();
+
+        const anchorNode = this._anchorNode;
+        if (anchorNode) {
+            anchorNode.removeEventListener("focusin", this._handleFocusIn);
+            anchorNode.removeEventListener("focusout", this._handleFocusOut);
+            anchorNode.removeEventListener(
+                "mouseenter",
+                this._handleMouseEnter,
+            );
+            anchorNode.removeEventListener(
+                "mouseleave",
+                this._handleMouseLeave,
+            );
+        }
+        if (this.state.active) {
+            document.removeEventListener("keyup", this._handleKeyUp);
+        }
+    }
+
+    static ariaContentId: string = "aria-content";
+
+    activeStateStolen: () => void = () => {
+        // Something wants the active state.
+        // Do we have it? If so, let's remember that.
+        // If we are already active, or we're inactive but have a timeoutID,
+        // then it was stolen from us.
+        this._stolenFromUs = this.state.active || !!this._timeoutID;
+        // Let's first tell ourselves we're not focused (otherwise the tooltip
+        // will be sticky on the next hover of this anchor and that just looks
+        // weird).
+        this._focused = false;
+        // Now update our actual state.
+        this._setActiveState(false, true);
+    };
+
+    _updateFocusivity() {
+        const anchorNode = this._anchorNode;
+        if (!anchorNode) {
+            return;
+        }
+        const {forceAnchorFocusivity} = this.props;
+        const currentTabIndex = anchorNode.getAttribute("tabindex");
+
+        if (forceAnchorFocusivity && !currentTabIndex) {
+            // Ensure that the anchor point is keyboard focusable so that
+            // we can show the tooltip for visually impaired users that don't
+            // use pointer devices nor assistive technology like screen readers.
+            anchorNode.setAttribute("tabindex", "0");
+            this._weSetFocusivity = true;
+        } else if (!forceAnchorFocusivity && currentTabIndex) {
+            // We may not be forcing it, but we also want to ensure that if we
+            // did before, we remove it.
+            if (this._weSetFocusivity) {
+                anchorNode.removeAttribute("tabindex");
+                this._weSetFocusivity = false;
+            }
+        }
+    }
+
+    _updateActiveState(hovered: boolean, focused: boolean) {
+        // Update our stored values.
+        this._hovered = hovered;
+        this._focused = focused;
+
+        this._setActiveState(hovered || focused);
+    }
+
+    _clearPendingAction() {
+        if (this._timeoutID) {
+            clearTimeout(this._timeoutID);
+            this._timeoutID = null;
+        }
+    }
+
+    _setActiveState(active: boolean, instant?: boolean) {
+        if (
+            this._stolenFromUs ||
+            active !== this.state.active ||
+            (!this.state.active && this._timeoutID)
+        ) {
+            // If we are about to lose active state or change it, we need to
+            // cancel any pending action to show ourselves.
+            // So, if active is stolen from us, we are changing active state,
+            // or we are inactive and have a timer, clear the action.
+            this._clearPendingAction();
+        } else if (active === this.state.active && !this._timeoutID) {
+            // Nothing to do if we're already active.
+            return;
+        }
+
+        // Determine if we are doing things immediately or not.
+        instant = instant || (active && TRACKER.steal(this));
+
+        if (instant) {
+            if (active) {
+                document.addEventListener("keyup", this._handleKeyUp);
+            } else {
+                document.removeEventListener("keyup", this._handleKeyUp);
+            }
+            this.setState({active});
+            this.props.onActiveChanged(active);
+            if (!this._stolenFromUs && !active) {
+                // Only the very last thing going inactive will giveup
+                // the stolen active state.
+                TRACKER.giveup();
+            }
+            this._stolenFromUs = false;
+        } else {
+            const delay = active
+                ? TooltipAppearanceDelay
+                : TooltipDisappearanceDelay;
+            this._timeoutID = setTimeout(() => {
+                this._timeoutID = null;
+                this._setActiveState(active, true);
+            }, delay);
+        }
+    }
+
+    _handleFocusIn: () => void = () => {
+        this._updateActiveState(this._hovered, true);
+    };
+
+    _handleFocusOut: () => void = () => {
+        this._updateActiveState(this._hovered, false);
+    };
+
+    _handleMouseEnter: () => void = () => {
+        this._updateActiveState(true, this._focused);
+    };
+
+    _handleMouseLeave: () => void = () => {
+        this._updateActiveState(false, this._focused);
+    };
+
+    _handleKeyUp: (e: KeyboardEvent) => void = (e) => {
+        // We check the key as that's keyboard layout agnostic and also avoids
+        // the minefield of deprecated number type properties like keyCode and
+        // which, with the replacement code, which uses a string instead.
+        if (e.key === "Escape" && this.state.active) {
+            // Stop the event going any further.
+            // For cancellation events, like the Escape key, we generally should
+            // air on the side of caution and only allow it to cancel one thing.
+            // So, it's polite for us to stop propagation of the event.
+            // Otherwise, we end up with UX where one Escape key press
+            // unexpectedly cancels multiple things.
+            //
+            // For example, using Escape to close a tooltip or a dropdown while
+            // displaying a modal and having the modal close as well. This would
+            // be annoyingly bad UX.
+            e.preventDefault();
+            e.stopPropagation();
+            this._updateActiveState(false, false);
+        }
+    };
+
+    _renderAnchorableChildren(): React.Element<any> {
+        const {children} = this.props;
+        return typeof children === "string" ? (
+            <WBText>{children}</WBText>
+        ) : (
+            children
+        );
+    }
+
+    _renderAccessibleChildren(ids: IIdentifierFactory): React.Node {
+        const anchorableChildren = this._renderAnchorableChildren();
+
+        return React.cloneElement(anchorableChildren, {
+            "aria-describedby": ids.get(TooltipAnchor.ariaContentId),
+        });
+    }
+
+    render(): React.Node {
+        // We need to make sure we can anchor on our content.
+        // If the content is just a string, we wrap it in a Text element
+        // so as not to affect styling or layout but still have an element
+        // to anchor to.
+        if (this.props.ids) {
+            return this._renderAccessibleChildren(this.props.ids);
+        }
+        return this._renderAnchorableChildren();
+    }
+}

package/src/components/tooltip-bubble.js

@@ -0,0 +1,150 @@
+// @flow
+import {StyleSheet} from "aphrodite";
+import * as React from "react";
+import Colors from "@khanacademy/wonder-blocks-color";
+import {View} from "@khanacademy/wonder-blocks-core";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+
+import type {StyleType} from "@khanacademy/wonder-blocks-core";
+import typeof TooltipContent from "./tooltip-content.js";
+import TooltipTail from "./tooltip-tail.js";
+
+import type {getRefFn, Offset, Placement} from "../util/types.js";
+
+export type PopperElementProps = {|
+    /** The placement of the bubble with respect to the anchor. */
+    placement: Placement,
+
+    /** Whether the bubble is out of bounds or not. */
+    isReferenceHidden?: ?boolean,
+
+    /** A callback for updating the ref of the bubble itself. */
+    updateBubbleRef?: getRefFn,
+
+    /** A callback for updating the ref of the bubble's tail. */
+    updateTailRef?: getRefFn,
+
+    /** Where the tail is to be rendered. */
+    tailOffset?: Offset,
+
+    /** Additional styles to be applied by the bubble. */
+    style?: StyleType,
+|};
+
+export type Props = {|
+    /** The unique identifier for this component. */
+    id: string,
+
+    /** The `TooltipContent` element that will be rendered in the bubble. */
+    children: React.Element<TooltipContent>,
+
+    onActiveChanged: (active: boolean) => mixed,
+
+    // TODO(somewhatabstract): Update react-docgen to support spread operators
+    // (v3 beta introduces this)
+    ...PopperElementProps,
+|};
+
+type State = {|
+    active: boolean,
+|};
+
+export default class TooltipBubble extends React.Component<Props, State> {
+    state: State = {
+        active: false,
+    };
+
+    _setActiveState(active: boolean) {
+        this.setState({active});
+        this.props.onActiveChanged(active);
+    }
+
+    handleMouseEnter: () => void = () => {
+        this._setActiveState(true);
+    };
+
+    handleMouseLeave: () => void = () => {
+        this.props.onActiveChanged(false);
+    };
+
+    render(): React.Node {
+        const {
+            id,
+            children,
+            updateBubbleRef,
+            placement,
+            isReferenceHidden,
+            style,
+            updateTailRef,
+            tailOffset,
+        } = this.props;
+
+        return (
+            <View
+                id={id}
+                role="tooltip"
+                data-placement={placement}
+                onMouseEnter={this.handleMouseEnter}
+                onMouseLeave={this.handleMouseLeave}
+                ref={updateBubbleRef}
+                style={[
+                    isReferenceHidden && styles.hide,
+                    styles.bubble,
+                    styles[`content-${placement}`],
+                    style,
+                ]}
+            >
+                <View style={styles.content}>{children}</View>
+                <TooltipTail
+                    updateRef={updateTailRef}
+                    placement={placement}
+                    offset={tailOffset}
+                />
+            </View>
+        );
+    }
+}
+
+const styles = StyleSheet.create({
+    bubble: {
+        position: "absolute",
+    },
+
+    /**
+     * The hide style ensures that the bounds of the bubble stay unchanged.
+     * This is because popper.js calculates the bubble position based off its
+     * bounds and if we stopped rendering it entirely, it wouldn't know where to
+     * place it when it reappeared.
+     */
+    hide: {
+        pointerEvents: "none",
+        opacity: 0,
+        backgroundColor: "transparent",
+        color: "transparent",
+    },
+
+    /**
+     * Ensure the content and tail are properly arranged.
+     */
+    "content-top": {
+        flexDirection: "column",
+    },
+    "content-right": {
+        flexDirection: "row-reverse",
+    },
+    "content-bottom": {
+        flexDirection: "column-reverse",
+    },
+    "content-left": {
+        flexDirection: "row",
+    },
+
+    content: {
+        maxWidth: 472,
+        borderRadius: Spacing.xxxSmall_4,
+        border: `solid 1px ${Colors.offBlack16}`,
+        backgroundColor: Colors.white,
+        boxShadow: `0 ${Spacing.xSmall_8}px ${Spacing.xSmall_8}px 0 ${Colors.offBlack8}`,
+        justifyContent: "center",
+    },
+});

package/src/components/tooltip-bubble.md

@@ -0,0 +1,92 @@
+This is an internal component that we use to render the stuff that appears when a tooltip shows.
+
+Note that without explicit positioning, the tail will not be centered.
+
+### Placement top
+
+```jsx
+import {View} from "@khanacademy/wonder-blocks-core";
+import {TooltipContent} from "@khanacademy/wonder-blocks-tooltip";
+
+<View>
+    <TooltipBubble placement="top" style={{position: "relative"}}>
+        <TooltipContent>I'm on the top!</TooltipContent>
+    </TooltipBubble>
+</View>
+```
+
+### Placement right
+
+```jsx
+import {View} from "@khanacademy/wonder-blocks-core";
+import {TooltipContent} from "@khanacademy/wonder-blocks-tooltip";
+
+<View style={{alignItems: "flex-start"}}>
+    <TooltipBubble placement="right" style={{position: "relative"}}>
+        <TooltipContent>I'm on the right!</TooltipContent>
+    </TooltipBubble>
+</View>
+```
+
+### Placement bottom
+
+```jsx
+import {View} from "@khanacademy/wonder-blocks-core";
+import {TooltipContent} from "@khanacademy/wonder-blocks-tooltip";
+
+<View>
+    <TooltipBubble placement="bottom" style={{position: "relative"}}>
+        <TooltipContent>I'm on the bottom!</TooltipContent>
+    </TooltipBubble>
+</View>
+```
+
+### Placement left
+
+```jsx
+import {View} from "@khanacademy/wonder-blocks-core";
+import {TooltipContent} from "@khanacademy/wonder-blocks-tooltip";
+
+<View>
+    <TooltipBubble placement="left" style={{position: "relative"}}>
+        <TooltipContent>I'm on the left!</TooltipContent>
+    </TooltipBubble>
+</View>
+```
+
+### Positioning the tail
+Here we tell the tail that it's lefthand side is at 50px.
+
+```jsx
+import {View} from "@khanacademy/wonder-blocks-core";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+import {TooltipContent} from "@khanacademy/wonder-blocks-tooltip";
+
+<View>
+    <TooltipBubble
+        placement="bottom"
+        tailOffset={{left: 50, top: 0}}
+        style={{position: "relative"}}
+    >
+        <TooltipContent>I'm on the bottom with a tail 50px in!</TooltipContent>
+    </TooltipBubble>
+</View>
+```
+
+### Hidden because isReferenceHidden is true
+
+```jsx
+import {View} from "@khanacademy/wonder-blocks-core";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+import {TooltipContent} from "@khanacademy/wonder-blocks-tooltip";
+
+<View>
+    <TooltipBubble
+        placement="top"
+        isReferenceHidden={true}
+        style={{position: "relative"}}
+    >
+        <TooltipContent>I'm hidden. So hidden. Shhhhh!</TooltipContent>
+    </TooltipBubble>
+</View>
+```

package/src/components/tooltip-content.js

@@ -0,0 +1,76 @@
+// @flow
+import * as React from "react";
+import {StyleSheet} from "aphrodite";
+
+import {View} from "@khanacademy/wonder-blocks-core";
+import {Strut} from "@khanacademy/wonder-blocks-layout";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+import {HeadingSmall, LabelMedium} from "@khanacademy/wonder-blocks-typography";
+
+import type {Typography} from "@khanacademy/wonder-blocks-typography";
+
+type Props = {|
+    /**
+     * The title for the tooltip content.
+     * Optional.
+     */
+    title?: string | React.Element<Typography>,
+
+    /**
+     * The main content for a tooltip.
+     */
+    children:
+        | string
+        | React.Element<Typography>
+        | Array<React.Element<Typography>>,
+|};
+
+/**
+ * This component is used to provide the content that is to be rendered in the
+ * tooltip bubble.
+ */
+export default class TooltipContent extends React.Component<Props> {
+    _renderTitle(): React.Node {
+        const {title} = this.props;
+        if (title) {
+            if (typeof title === "string") {
+                return <HeadingSmall>{title}</HeadingSmall>;
+            } else {
+                return title;
+            }
+        }
+        return null;
+    }
+
+    _renderChildren(): React.Node {
+        const {children} = this.props;
+        if (typeof children === "string") {
+            return <LabelMedium>{children}</LabelMedium>;
+        } else {
+            return children;
+        }
+    }
+
+    render(): React.Node {
+        const title = this._renderTitle();
+        const children = this._renderChildren();
+        const containerStyle = title ? styles.withTitle : styles.withoutTitle;
+        return (
+            <View style={containerStyle}>
+                {title}
+                {title && children && <Strut size={Spacing.xxxSmall_4} />}
+                {children}
+            </View>
+        );
+    }
+}
+
+const styles = StyleSheet.create({
+    withoutTitle: {
+        padding: `10px ${Spacing.medium_16}px`,
+    },
+
+    withTitle: {
+        padding: Spacing.medium_16,
+    },
+});

package/src/components/tooltip-content.md

@@ -0,0 +1,34 @@
+The `TooltipContent` component is provided for situations where the `Tooltip` needs to be customized beyond the default stylings. `TooltipContent` supports all `wonder-blocks-typography` components.
+
+### Only text content
+
+This shows the default which is text rendered using `LabelMedium`.
+
+```jsx
+<TooltipContent>
+    Only the content
+</TooltipContent>
+```
+
+### Titled content
+
+This shows the default with a title; the title is rendered using `HeadingSmall`.
+
+```jsx
+<TooltipContent title="Title text!">
+    Some content in my content
+</TooltipContent>
+```
+
+### Custom title and custom content
+
+This shows how we can customize both the title and the content.
+
+```jsx
+const {Body, LabelSmall} = require("@khanacademy/wonder-blocks-typography");
+
+<TooltipContent title={<Body>Body text title!</Body>}>
+    <Body>Body text content!</Body>
+    <LabelSmall>And LabelSmall!</LabelSmall>
+</TooltipContent>
+```