@khanacademy/wonder-blocks-tooltip 1.3.0

package/src/components/tooltip.js

@@ -0,0 +1,235 @@
+// @flow
+/**
+ * The Tooltip component provides the means to anchor some additional
+ * information to some content. The additional information is shown in a
+ * callout that hovers above the page content. This additional information is
+ * invoked by hovering over the anchored content, or focusing all or part of the
+ * anchored content.
+ *
+ * This component is structured as follows:
+ *
+ * Tooltip (this component)
+ * - TooltipAnchor (provides hover/focus behaviors on anchored content)
+ *   - TooltipPortalMounter (creates portal into which the callout is rendered)
+ * --------------------------- [PORTAL BOUNDARY] ------------------------------
+ * - TooltipPopper (provides positioning for the callout using react-popper)
+ *   - TooltipBubble (renders the callout borders, background and shadow)
+ *     - TooltipContent (renders the callout content; the actual information)
+ *     - TooltipTail (renders the callout tail and shadow that points from the
+ *                     callout to the anchor content)
+ */
+import * as React from "react";
+import * as ReactDOM from "react-dom";
+
+import {
+    UniqueIDProvider,
+    type IIdentifierFactory,
+} from "@khanacademy/wonder-blocks-core";
+import {maybeGetPortalMountedModalHostElement} from "@khanacademy/wonder-blocks-modal";
+import type {Typography} from "@khanacademy/wonder-blocks-typography";
+import type {AriaProps} from "@khanacademy/wonder-blocks-core";
+
+import TooltipAnchor from "./tooltip-anchor.js";
+import TooltipBubble from "./tooltip-bubble.js";
+import TooltipContent from "./tooltip-content.js";
+import TooltipPopper from "./tooltip-popper.js";
+import type {Placement} from "../util/types.js";
+
+type Props = {|
+    ...AriaProps,
+
+    /**
+     * The content for anchoring the tooltip.
+     * This component will be used to position the tooltip.
+     */
+    children: React.Element<any> | string,
+
+    /**
+     * The title of the tooltip.
+     * Optional.
+     */
+    title?: string | React.Element<Typography>,
+
+    /**
+     * The content to render in the tooltip.
+     */
+    content: string | React.Element<typeof TooltipContent>,
+
+    /**
+     * The unique identifier to give to the tooltip. Provide this in cases where
+     * you want to override the default accessibility solution. This identifier
+     * will be applied to the tooltip bubble content.
+     *
+     * By providing this identifier, the children that this tooltip anchors to
+     * will not be automatically given the aria-desribedby attribute. Instead,
+     * the accessibility solution is the responsibility of the caller.
+     *
+     * If this is not provided, the aria-describedby attribute will be added
+     * to the children with a unique identifier pointing to the tooltip bubble
+     * content.
+     */
+    id?: string,
+
+    /**
+     * 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.
+     *
+     * Also, note that the aria-describedby attribute is attached to the root
+     * anchor element, so you may need to implement an additional accessibility
+     * solution when overriding anchor focusivity.
+     */
+    forceAnchorFocusivity?: boolean,
+
+    /**
+     * Where the tooltip should appear in relation to the anchor element.
+     * Defaults to "top".
+     */
+    placement: Placement,
+
+    /**
+     * Test ID used for e2e testing.
+     */
+    testId?: string,
+|};
+
+type State = {|
+    /**
+     * Whether the tooltip is open by hovering/focusing on the anchor element.
+     */
+    active: boolean,
+    /**
+     * Whether the tooltip is open by hovering on the tooltip bubble.
+     */
+    activeBubble: boolean,
+    /**
+     * The element that activates the tooltip.
+     */
+    anchorElement: ?HTMLElement,
+|};
+
+type DefaultProps = {|
+    forceAnchorFocusivity: $PropertyType<Props, "forceAnchorFocusivity">,
+    placement: $PropertyType<Props, "placement">,
+|};
+
+export default class Tooltip extends React.Component<Props, State> {
+    static defaultProps: DefaultProps = {
+        forceAnchorFocusivity: true,
+        placement: "top",
+    };
+
+    state: State = {
+        active: false,
+        activeBubble: false,
+        anchorElement: null,
+    };
+    static ariaContentId: string = "aria-content";
+
+    _updateAnchorElement(ref: ?Element) {
+        if (ref && ref !== this.state.anchorElement) {
+            this.setState({anchorElement: ((ref: any): HTMLElement)});
+        }
+    }
+
+    _renderBubbleContent(): React.Element<typeof TooltipContent> {
+        const {title, content} = this.props;
+        if (typeof content === "string") {
+            return <TooltipContent title={title}>{content}</TooltipContent>;
+        } else if (title) {
+            return React.cloneElement(content, {title});
+        } else {
+            return content;
+        }
+    }
+
+    _renderPopper(ids?: IIdentifierFactory): React.Node {
+        const {id} = this.props;
+        const bubbleId = ids ? ids.get(Tooltip.ariaContentId) : id;
+        if (!bubbleId) {
+            throw new Error("Did not get an identifier factory nor a id prop");
+        }
+
+        const {placement} = this.props;
+        return (
+            <TooltipPopper
+                anchorElement={this.state.anchorElement}
+                placement={placement}
+            >
+                {(props) => (
+                    <TooltipBubble
+                        id={bubbleId}
+                        style={props.style}
+                        tailOffset={props.tailOffset}
+                        isReferenceHidden={props.isReferenceHidden}
+                        placement={props.placement}
+                        updateTailRef={props.updateTailRef}
+                        updateBubbleRef={props.updateBubbleRef}
+                        onActiveChanged={(active) =>
+                            this.setState({activeBubble: active})
+                        }
+                    >
+                        {this._renderBubbleContent()}
+                    </TooltipBubble>
+                )}
+            </TooltipPopper>
+        );
+    }
+
+    _getHost(): ?Element {
+        const {anchorElement} = this.state;
+
+        return (
+            maybeGetPortalMountedModalHostElement(anchorElement) ||
+            document.body
+        );
+    }
+
+    _renderTooltipAnchor(ids?: IIdentifierFactory): React.Node {
+        const {children, forceAnchorFocusivity} = this.props;
+        const {active, activeBubble} = this.state;
+
+        const popperHost = this._getHost();
+
+        // TODO(kevinb): update to use ReactPopper's React 16-friendly syntax
+        return (
+            <React.Fragment>
+                <TooltipAnchor
+                    forceAnchorFocusivity={forceAnchorFocusivity}
+                    anchorRef={(r) => this._updateAnchorElement(r)}
+                    onActiveChanged={(active) => this.setState({active})}
+                    ids={ids}
+                >
+                    {children}
+                </TooltipAnchor>
+                {popperHost &&
+                    (active || activeBubble) &&
+                    ReactDOM.createPortal(this._renderPopper(ids), popperHost)}
+            </React.Fragment>
+        );
+    }
+
+    render(): React.Node {
+        const {id} = this.props;
+        if (id) {
+            // Let's bypass the extra weight of an id provider since we don't
+            // need it.
+            return this._renderTooltipAnchor();
+        } else {
+            return (
+                <UniqueIDProvider scope="tooltip" mockOnFirstRender={true}>
+                    {(ids) => this._renderTooltipAnchor(ids)}
+                </UniqueIDProvider>
+            );
+        }
+    }
+}

package/src/components/tooltip.md

@@ -0,0 +1,194 @@
+### Text anchor & text tooltip & placement right
+
+```js
+import Tooltip from "@khanacademy/wonder-blocks-tooltip";
+
+<Tooltip content="This is a text tooltip on the right" placement="right">
+    Some text
+</Tooltip>
+```
+
+### Complex anchor & title tooltip & placement default (top)
+
+In this example, we're no longer forcing the anchor root to be focusable, since the text input can take focus. However, that needs a custom accessibility implementation too (for that, we should use `UniqueIDProvider`, but we'll cheat here and give our own identifier).
+
+```js
+import {View} from "@khanacademy/wonder-blocks-core";
+import Tooltip from "@khanacademy/wonder-blocks-tooltip";
+
+<Tooltip
+    id="my-a11y-tooltip"
+    forceAnchorFocusivity={false}
+    title="This tooltip has a title"
+    content="I'm at the top!"
+>
+    <View>
+        Some text
+        <input aria-describedby="my-a11y-tooltip" />
+    </View>
+</Tooltip>
+```
+
+### Substring anchor in scrollable parent & placement bottom
+In this example, we have the anchor in a scrollable parent. Notice how, when the anchor is focused but scrolled out of bounds, the tooltip disappears.
+
+```js
+import {StyleSheet} from "aphrodite";
+
+import {View} from "@khanacademy/wonder-blocks-core";
+import {Body} from "@khanacademy/wonder-blocks-typography";
+import Tooltip from "@khanacademy/wonder-blocks-tooltip";
+
+const styles = StyleSheet.create({
+    scrollbox: {
+        height: 100,
+        overflow: "auto",
+        border: "1px solid black",
+        margin: 10,
+    },
+    hostbox: {
+        minHeight: "200vh",
+    },
+});
+
+<View>
+    <View style={styles.scrollbox}>
+        <View style={styles.hostbox}>
+            <Body>
+                This is a big long piece of text with a
+                <Tooltip content="This tooltip will disappear when scrolled out of bounds" placement="bottom">
+                    [tooltip]
+                </Tooltip>
+                <span> </span>in the middle.
+            </Body>
+        </View>
+    </View>
+</View>
+```
+
+### Tooltip in a modal & placement left
+This checks that the tooltip works how we want inside a modal. Click the button to take a look.
+
+```js
+import {StyleSheet} from "aphrodite";
+
+import {View, Text} from "@khanacademy/wonder-blocks-core";
+import {OnePaneDialog, ModalLauncher} from "@khanacademy/wonder-blocks-modal";
+import Button from "@khanacademy/wonder-blocks-button";
+import Tooltip from "@khanacademy/wonder-blocks-tooltip";
+
+const styles = StyleSheet.create({
+    scrollbox: {
+        height: 100,
+        overflow: "auto",
+        border: "1px solid black",
+        margin: 10,
+    },
+    hostbox: {
+        minHeight: "200vh",
+    },
+    modalbox: {
+        height: "200vh",
+    },
+});
+
+const scrollyContent = (
+     <View style={styles.scrollbox}>
+        <View style={styles.hostbox}>
+            <Tooltip content="I'm on the left!" placement="left">
+                tooltip
+            </Tooltip>
+        </View>
+     </View>
+);
+
+const modalContent = (
+    <View style={styles.modalbox}>
+        {scrollyContent}
+    </View>
+);
+
+const modal = (
+    <OnePaneDialog
+        title="My modal"
+        footer="Still my modal"
+        content={modalContent} />
+);
+
+<ModalLauncher modal={modal}>
+    {({openModal}) => <Button onClick={openModal}>Click here!</Button>}
+</ModalLauncher>
+```
+
+### Tooltips side-by-side
+
+```js
+import {StyleSheet} from "aphrodite";
+
+import {View} from "@khanacademy/wonder-blocks-core";
+import {LabelSmall} from "@khanacademy/wonder-blocks-typography";
+import Tooltip from "@khanacademy/wonder-blocks-tooltip";
+
+const styles = StyleSheet.create({
+    "block": {
+        border: "solid 1px steelblue",
+        width: 32,
+        height: 32,
+        alignItems: "center",
+        justifyContent: "center",
+    }
+});
+
+<View>
+    <LabelSmall>Here, we can see that the first tooltip shown has an initial delay before it appears, as does the last tooltip shown, yet when moving between tooltipped items, the transition from one to another is instantaneous.</LabelSmall>
+
+    <View style={{flexDirection: "row"}}>
+        <Tooltip content="Tooltip A" placement="bottom">
+            <View style={styles.block}>A</View>
+        </Tooltip>
+        <Tooltip content="Tooltip B" placement="bottom">
+            <View style={styles.block}>B</View>
+        </Tooltip>
+        <Tooltip content="Tooltip C" placement="bottom">
+            <View style={styles.block}>C</View>
+        </Tooltip>
+        <Tooltip content="Tooltip D" placement="bottom">
+            <View style={styles.block}>D</View>
+        </Tooltip>
+    </View>
+</View>
+```
+
+### Tooltips on buttons
+
+```js
+import {StyleSheet} from "aphrodite";
+
+import Button from "@khanacademy/wonder-blocks-button";
+import IconButton from "@khanacademy/wonder-blocks-icon-button";
+import {icons} from "@khanacademy/wonder-blocks-icon";
+import {View} from "@khanacademy/wonder-blocks-core";
+import {Strut} from "@khanacademy/wonder-blocks-layout";
+import Tooltip from "@khanacademy/wonder-blocks-tooltip";
+
+const styles = {
+    container: {
+        flexDirection: "row",
+        alignItems: "center",
+    },
+};
+
+<View style={styles.container}>
+    <Tooltip content="I'm a little tooltip">
+        <Button>Click me!</Button>
+    </Tooltip>
+    <Strut size={16} />
+    <Tooltip content="Short and stout">
+        <IconButton
+            icon={icons.search}
+            aria-label="search"
+            onClick={(e) => console.log("hello")}
+        />
+    </Tooltip>
+</View>
+```

package/src/components/tooltip.stories.js

@@ -0,0 +1,76 @@
+// @flow
+import * as React from "react";
+import {StyleSheet} from "aphrodite";
+import {View} from "@khanacademy/wonder-blocks-core";
+import {TextField} from "@khanacademy/wonder-blocks-form";
+import Tooltip from "@khanacademy/wonder-blocks-tooltip";
+
+import type {Placement} from "@khanacademy/wonder-blocks-tooltip";
+import type {StoryComponentType} from "@storybook/react";
+
+export default {
+    title: "Tooltip",
+};
+
+const BaseTooltipExample = ({placement}: {|placement: Placement|}) => {
+    const inputRef = React.useRef<null | HTMLElement>(null);
+    React.useEffect(() => {
+        if (inputRef.current) {
+            inputRef.current.focus();
+        }
+    }, []);
+
+    return (
+        <View style={styles.centered}>
+            <View>
+                <Tooltip
+                    content={`This is a text tooltip on the ${placement}`}
+                    placement={placement}
+                >
+                    <TextField
+                        id="tf-1"
+                        type="text"
+                        value=""
+                        placeholder="Text"
+                        onChange={() => {}}
+                        ref={inputRef}
+                    />
+                </Tooltip>
+            </View>
+        </View>
+    );
+};
+
+export const tooltipRight: StoryComponentType = () => (
+    <BaseTooltipExample placement="right" />
+);
+
+export const tooltipLeft: StoryComponentType = () => (
+    <BaseTooltipExample placement="left" />
+);
+
+export const tooltipTop: StoryComponentType = () => (
+    <BaseTooltipExample placement="top" />
+);
+
+export const tooltipBottom: StoryComponentType = () => (
+    <BaseTooltipExample placement="bottom" />
+);
+
+const styles = StyleSheet.create({
+    row: {
+        flexDirection: "row",
+    },
+    fullBleed: {
+        width: "100%",
+    },
+    wrapper: {
+        height: "800px",
+        width: "1200px",
+    },
+    centered: {
+        alignItems: "center",
+        justifyContent: "center",
+        height: `calc(100vh - 16px)`,
+    },
+});

package/src/index.js

@@ -0,0 +1,12 @@
+// @flow
+import type {Placement} from "./util/types.js";
+import type {PopperElementProps} from "./components/tooltip-bubble.js";
+
+import Tooltip from "./components/tooltip.js";
+import TooltipContent from "./components/tooltip-content.js";
+import TooltipPopper from "./components/tooltip-popper.js";
+import TooltipTail from "./components/tooltip-tail.js";
+
+export {Tooltip as default, TooltipContent, TooltipPopper, TooltipTail};
+
+export type {Placement, PopperElementProps};

package/src/util/__tests__/__snapshots__/active-tracker.test.js.snap

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`ActiveTracker #subscribe if already subscribed, throws 1`] = `"Already subscribed."`;

package/src/util/__tests__/__snapshots__/ref-tracker.test.js.snap

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`RefTracker #setCallback called with non-function, throws 1`] = `"targetFn must be a function"`;

package/src/util/__tests__/active-tracker.test.js

@@ -0,0 +1,142 @@
+// @flow
+import ActiveTracker, {IActiveTrackerSubscriber} from "../active-tracker.js";
+
+class MockSubscriber implements IActiveTrackerSubscriber {
+    activeStateStolen = jest.fn();
+}
+
+describe("ActiveTracker", () => {
+    describe("#subscribe", () => {
+        test("subscribes to notifications", () => {
+            // Arrange
+            const tracker = new ActiveTracker();
+            const subscriber = new MockSubscriber();
+            const thief = new MockSubscriber();
+
+            // Act
+            tracker.subscribe(subscriber);
+            tracker.steal(thief);
+
+            // Assert
+            expect(subscriber.activeStateStolen).toHaveBeenCalledTimes(1);
+        });
+
+        test("if already subscribed, throws", () => {
+            // Arrange
+            const tracker = new ActiveTracker();
+            const subscriber = new MockSubscriber();
+            tracker.subscribe(subscriber);
+
+            // Act
+            const underTest = () => tracker.subscribe(subscriber);
+
+            // Assert
+            expect(underTest).toThrowErrorMatchingSnapshot();
+        });
+
+        test("returns a function", () => {
+            // Arrange
+            const tracker = new ActiveTracker();
+            const subscriber = new MockSubscriber();
+
+            // Act
+            const result = tracker.subscribe(subscriber);
+
+            // Assert
+            expect(result).toBeInstanceOf(Function);
+        });
+
+        test("returned function unsubscribes from notifications", () => {
+            // Arrange
+            const tracker = new ActiveTracker();
+            const subscriber1 = new MockSubscriber();
+            const testCase = new MockSubscriber();
+            const subscriber3 = new MockSubscriber();
+            const subscriber4 = new MockSubscriber();
+            tracker.subscribe(subscriber1);
+            const unsubscribe = tracker.subscribe(testCase);
+            tracker.subscribe(subscriber3);
+
+            // Act
+            unsubscribe();
+            tracker.steal(subscriber4);
+
+            // Assert
+            expect(testCase.activeStateStolen).not.toHaveBeenCalled();
+            expect(subscriber1.activeStateStolen).toHaveBeenCalledTimes(1);
+            expect(subscriber3.activeStateStolen).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe("#steal", () => {
+        test("notifies subscribers of theft attempt", () => {
+            // Arrange
+            const tracker = new ActiveTracker();
+            const thief = new MockSubscriber();
+            const subscriber = new MockSubscriber();
+            tracker.subscribe(subscriber);
+
+            // Act
+            tracker.steal(thief);
+
+            // Assert
+            expect(subscriber.activeStateStolen).toHaveBeenCalledTimes(1);
+        });
+
+        test("does not notifier thief of their own theft attempt", () => {
+            // Arrange
+            const tracker = new ActiveTracker();
+            const thief = new MockSubscriber();
+            tracker.subscribe(thief);
+
+            // Act
+            tracker.steal(thief);
+
+            // Assert
+            expect(thief.activeStateStolen).not.toHaveBeenCalledTimes(1);
+        });
+
+        test("returns falsy if active state was not stolen", () => {
+            // Arrange
+            const tracker = new ActiveTracker();
+            const thief = new MockSubscriber();
+
+            // Act
+            const result = tracker.steal(thief);
+
+            // Assert
+            expect(result).toBeFalsy();
+        });
+
+        test("returns truthy if active state was stolen", () => {
+            // Arrange
+            const tracker = new ActiveTracker();
+            const thief = new MockSubscriber();
+            const owner = new MockSubscriber();
+            tracker.steal(owner);
+
+            // Act
+            const result = tracker.steal(thief);
+
+            // Assert
+            expect(result).toBeTruthy();
+        });
+    });
+
+    describe("#giveup", () => {
+        test("marks the active state as false", () => {
+            // Arrange
+            const tracker = new ActiveTracker();
+            const owner = new MockSubscriber();
+            tracker.steal(owner);
+
+            // Act
+            expect(tracker.steal(owner)).toBeTruthy();
+            tracker.giveup();
+            const result = tracker.steal(owner);
+
+            // Assert
+            expect(result).toBeFalsy();
+        });
+    });
+});