@khanacademy/wonder-blocks-tooltip 1.3.0

package/src/components/tooltip-popper.js

@@ -0,0 +1,101 @@
+// @flow
+/**
+ * This component is a light wrapper for react-popper, allowing us to position
+ * and control the tooltip bubble location and visibility as we need.
+ */
+import * as React from "react";
+import {Popper} from "react-popper";
+import type {PopperChildrenProps} from "react-popper";
+
+import RefTracker from "../util/ref-tracker.js";
+import type {Placement} from "../util/types.js";
+import type {PopperElementProps} from "./tooltip-bubble.js";
+
+type Props = {|
+    /**
+     * This uses the children-as-a-function approach, mirroring react-popper's
+     * implementation.
+     *
+     * TODO(WB-624): figure out to only allow TooltipBubble and PopoverDialog
+     */
+    children: (PopperElementProps) => React.Element<any>,
+
+    /**
+     * The element that anchors the tooltip bubble.
+     * This is used to position the bubble.
+     */
+    anchorElement: ?HTMLElement,
+
+    /** Where should the bubble try to go with respect to its anchor. */
+    placement: Placement,
+|};
+
+export default class TooltipPopper extends React.Component<Props> {
+    _bubbleRefTracker: RefTracker = new RefTracker();
+    _tailRefTracker: RefTracker = new RefTracker();
+
+    _renderPositionedContent(popperProps: PopperChildrenProps): React.Node {
+        const {children} = this.props;
+
+        // We'll hide some complexity from the children here and ensure
+        // that our placement always has a value.
+        const placement: Placement =
+            // We know that popperProps.placement will only be one of our
+            // supported values, so just cast it.
+            (popperProps.placement: any) || this.props.placement;
+
+        // Just in case the callbacks have changed, let's update our reference
+        // trackers.
+        this._bubbleRefTracker.setCallback(popperProps.ref);
+        this._tailRefTracker.setCallback(popperProps.arrowProps.ref);
+
+        // Here we translate from the react-popper's PropperChildrenProps
+        // to our own TooltipBubbleProps.
+        const bubbleProps = {
+            placement,
+            style: {
+                // NOTE(jeresig): We can't just use `popperProps.style` here
+                // as the Flow type doesn't match Aphrodite's CSS flow props
+                // (as it doesn't camelCase props). So we just copy over the
+                // props that we need, instead.
+                top: popperProps.style.top,
+                left: popperProps.style.left,
+                bottom: popperProps.style.bottom,
+                right: popperProps.style.right,
+                position: popperProps.style.position,
+                transform: popperProps.style.transform,
+            },
+            updateBubbleRef: this._bubbleRefTracker.updateRef,
+            tailOffset: {
+                bottom: popperProps.arrowProps.style.bottom,
+                right: popperProps.arrowProps.style.right,
+                top: popperProps.arrowProps.style.top,
+                left: popperProps.arrowProps.style.left,
+                transform: popperProps.arrowProps.style.transform,
+            },
+            updateTailRef: this._tailRefTracker.updateRef,
+            isReferenceHidden: popperProps.isReferenceHidden,
+        };
+        return children(bubbleProps);
+    }
+
+    render(): React.Node {
+        const {anchorElement, placement} = this.props;
+        return (
+            <Popper
+                referenceElement={anchorElement}
+                placement={placement}
+                modifiers={[
+                    {
+                        name: "preventOverflow",
+                        options: {
+                            rootBoundary: "document",
+                        },
+                    },
+                ]}
+            >
+                {(props) => this._renderPositionedContent(props)}
+            </Popper>
+        );
+    }
+}

package/src/components/tooltip-tail.js

@@ -0,0 +1,462 @@
+// @flow
+import * as React from "react";
+import {css, StyleSheet} from "aphrodite";
+
+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 type {getRefFn, Placement, Offset} from "../util/types.js";
+
+export type Props = {|
+    /**
+     * Whether we should use the default white background color or switch to a
+     * different bg color.
+     *
+     * NOTE: Added to support custom popovers
+     * @ignore
+     */
+    color: $Keys<typeof Colors>,
+
+    /** The offset of the tail indicating where it should be positioned. */
+    offset?: Offset,
+
+    /** The placement of the tail with respect to the tooltip anchor. */
+    placement: Placement,
+
+    /** A callback to update the ref of the tail element. */
+    updateRef?: getRefFn,
+|};
+
+type DefaultProps = {|
+    color: $PropertyType<Props, "color">,
+|};
+
+type Dimensions = {|
+    trimlinePoints: [string, string],
+    points: [string, string, string],
+    height: number,
+    width: number,
+|};
+
+type FilterPosition = {|
+    y: string,
+    x: string,
+    offsetShadowX: number,
+|};
+
+// TODO(somewhatabstract): Replace this really basic unique ID work with
+// something SSR-friendly and more robust.
+let tempIdCounter = 0;
+
+export default class TooltipTail extends React.Component<Props> {
+    static defaultProps: DefaultProps = {
+        color: "white",
+    };
+
+    _calculateDimensionsFromPlacement(): Dimensions {
+        const {placement} = this.props;
+
+        // The trimline, which we draw to make the tail flush to the bubble,
+        // has a thickness of 1. Since the line is drawn centered to the
+        // coordinates, we use an offset of 0.5 so that it properly covers what
+        // we want it to.
+        const trimlineOffset = 0.5;
+
+        // Calculate the three points of the arrow. Depending on the tail's
+        // direction (i.e., the tooltip's "side"), we choose different points,
+        // and set our SVG's bounds differently.
+        //
+        // Note that when the tail points to the left or right, the width/height
+        // are inverted.
+        switch (placement) {
+            case "top":
+                return {
+                    trimlinePoints: [
+                        `0,-${trimlineOffset}`,
+                        `${ARROW_WIDTH},-${trimlineOffset}`,
+                    ],
+                    points: [
+                        "0,0",
+                        `${ARROW_WIDTH / 2},${ARROW_HEIGHT}`,
+                        `${ARROW_WIDTH},0`,
+                    ],
+                    height: ARROW_HEIGHT,
+                    width: ARROW_WIDTH,
+                };
+
+            case "right":
+                return {
+                    trimlinePoints: [
+                        `${ARROW_HEIGHT + trimlineOffset},0`,
+                        `${ARROW_HEIGHT + trimlineOffset},${ARROW_WIDTH}`,
+                    ],
+                    points: [
+                        `${ARROW_HEIGHT},0`,
+                        `0,${ARROW_WIDTH / 2}`,
+                        `${ARROW_HEIGHT},${ARROW_WIDTH}`,
+                    ],
+                    width: ARROW_HEIGHT,
+                    height: ARROW_WIDTH,
+                };
+
+            case "bottom":
+                return {
+                    trimlinePoints: [
+                        `0, ${ARROW_HEIGHT + trimlineOffset}`,
+                        `${ARROW_WIDTH},${ARROW_HEIGHT + trimlineOffset}`,
+                    ],
+                    points: [
+                        `0, ${ARROW_HEIGHT}`,
+                        `${ARROW_WIDTH / 2},0`,
+                        `${ARROW_WIDTH},${ARROW_HEIGHT}`,
+                    ],
+                    width: ARROW_WIDTH,
+                    height: ARROW_HEIGHT,
+                };
+
+            case "left":
+                return {
+                    trimlinePoints: [
+                        `-${trimlineOffset},0`,
+                        `-${trimlineOffset},${ARROW_WIDTH}`,
+                    ],
+                    points: [
+                        `0,0`,
+                        `${ARROW_HEIGHT},${ARROW_WIDTH / 2}`,
+                        `0,${ARROW_WIDTH}`,
+                    ],
+                    width: ARROW_HEIGHT,
+                    height: ARROW_WIDTH,
+                };
+
+            default:
+                throw new Error(`Unknown placement: ${placement}`);
+        }
+    }
+
+    _getFilterPositioning(): ?FilterPosition {
+        const {placement} = this.props;
+        switch (placement) {
+            case "top":
+                return {
+                    y: "-50%",
+                    x: "-50%",
+                    offsetShadowX: 0,
+                };
+
+            case "bottom":
+                // No shadow on the arrow as it falls "under" the bubble.
+                return null;
+
+            case "left":
+                return {
+                    y: "-50%",
+                    x: "0%",
+                    offsetShadowX: 1,
+                };
+
+            case "right":
+                return {
+                    y: "-50%",
+                    x: "-100%",
+                    offsetShadowX: -1,
+                };
+
+            default:
+                throw new Error(`Unknown placement: ${placement}`);
+        }
+    }
+
+    /**
+     * Create an SVG filter that applies a blur to an element.
+     * We'll apply it to a dark shape outlining the tooltip, which
+     * will produce the overall effect of a drop-shadow.
+     *
+     * Also, scope its ID by side, so that tooltips with other
+     * "side" values don't end up using the wrong filter from
+     * elsewhere in the document. (The `height` value depends on
+     * which way the arrow is turned!)
+     */
+    _maybeRenderDropshadow(points: [string, string, string]): React.Node {
+        const position = this._getFilterPositioning();
+        if (!position) {
+            return null;
+        }
+        const {placement} = this.props;
+        const {y, x, offsetShadowX} = position;
+        const dropShadowFilterId = `tooltip-dropshadow-${placement}-${tempIdCounter++}`;
+        return [
+            <filter
+                key="filter"
+                id={dropShadowFilterId}
+                // Height and width tell the filter how big of a canvas to
+                // draw based on its parent size. i.e. 2 times bigger.
+                // This is so that the diffuse gaussian blur has space to
+                // bleed into.
+                width="200%"
+                height="200%"
+                // The x and y values tell the filter where, relative to its
+                // parent, it should begin showing its canvas. Without these
+                // the filter would clip at 0,0, which would look really
+                // strange.
+                x={x}
+                y={y}
+            >
+                {/* Here we provide a nice blur that will be our shadow
+                 * The stdDeviation is the spread of the blur. We don't want it
+                 * too diffuse.
+                 */}
+                <feGaussianBlur
+                    in="SourceAlpha"
+                    stdDeviation={Spacing.xxSmall_6 / 2}
+                />
+
+                {/* Here we adjust the alpha (feFuncA) linearly so as to blend
+                 * the shadow to match the rest of the tooltip bubble shadow.
+                 * It is a combination of the diffuse blur and this alpha
+                 * value that will make it look right.
+                 *
+                 * The value of 0.3. was arrived at from trial and error.
+                 */}
+                <feComponentTransfer>
+                    <feFuncA type="linear" slope="0.3" />
+                </feComponentTransfer>
+            </filter>,
+            /**
+             * Draw the tooltip arrow and apply the blur filter we created
+             * above, to produce a drop shadow effect.
+             * We move it down a bit with a translation, so that it is what
+             * we want.
+             *
+             * We offset the shadow on the X-axis because for left/right
+             * tails, we move the tail 1px toward the bubble. If we didn't
+             * offset the shadow, it would crash the bubble outline.
+             *
+             * See styles below for why we offset the arrow.
+             */
+            <g key="dropshadow" transform={`translate(${offsetShadowX},5.5)`}>
+                <polyline
+                    fill={Colors.offBlack16}
+                    points={points.join(" ")}
+                    stroke={Colors.offBlack32}
+                    filter={`url(#${dropShadowFilterId})`}
+                />
+            </g>,
+        ];
+    }
+
+    _minDistanceFromCorners(placement: Placement): number {
+        const minDistanceFromCornersForTopBottom = Spacing.medium_16;
+        const minDistanceFromCornersForLeftRight = 7;
+
+        switch (placement) {
+            case "top":
+            case "bottom":
+                return minDistanceFromCornersForTopBottom;
+
+            case "left":
+            case "right":
+                return minDistanceFromCornersForLeftRight;
+
+            default:
+                throw new Error(`Unknown placement: ${placement}`);
+        }
+    }
+
+    _getFullTailWidth(): number {
+        return ARROW_WIDTH + 2 * MIN_DISTANCE_FROM_CORNERS;
+    }
+
+    _getFullTailHeight(): number {
+        return ARROW_HEIGHT + DISTANCE_FROM_ANCHOR;
+    }
+
+    _getContainerStyle(): StyleType {
+        const {placement} = this.props;
+        /**
+         * Ensure the container is sized properly for us to be placed correctly
+         * by the Popper.js code.
+         *
+         * Here we offset the arrow 1px toward the bubble. This ensures the arrow
+         * outline meets the bubble outline and allows the arrow to erase the bubble
+         * outline between the ends of the arrow outline. We do this so that the
+         * arrow outline and bubble outline create a single, seamless outline of
+         * the callout.
+         *
+         * NOTE: The widths and heights refer to the downward-pointing tail
+         * (i.e. placement="top"). When the tail points to the left or right
+         * instead, the width/height are inverted.
+         */
+        const fullTailWidth = this._getFullTailWidth();
+        const fullTailHeight = this._getFullTailHeight();
+
+        switch (placement) {
+            case "top":
+                return {
+                    top: -1,
+                    width: fullTailWidth,
+                    height: fullTailHeight,
+                };
+
+            case "right":
+                return {
+                    left: 1,
+                    width: fullTailHeight,
+                    height: fullTailWidth,
+                };
+
+            case "bottom":
+                return {
+                    top: 1,
+                    width: fullTailWidth,
+                    height: fullTailHeight,
+                };
+
+            case "left":
+                return {
+                    left: -1,
+                    width: fullTailHeight,
+                    height: fullTailWidth,
+                };
+
+            default:
+                throw new Error(`Unknown placement: ${placement}`);
+        }
+    }
+
+    _getArrowStyle(): StyleType {
+        const {placement} = this.props;
+        switch (placement) {
+            case "top":
+                return {
+                    marginLeft: MIN_DISTANCE_FROM_CORNERS,
+                    marginRight: MIN_DISTANCE_FROM_CORNERS,
+                    paddingBottom: DISTANCE_FROM_ANCHOR,
+                };
+
+            case "right":
+                return {
+                    marginTop: MIN_DISTANCE_FROM_CORNERS,
+                    marginBottom: MIN_DISTANCE_FROM_CORNERS,
+                    paddingLeft: DISTANCE_FROM_ANCHOR,
+                };
+
+            case "bottom":
+                return {
+                    marginLeft: MIN_DISTANCE_FROM_CORNERS,
+                    marginRight: MIN_DISTANCE_FROM_CORNERS,
+                    paddingTop: DISTANCE_FROM_ANCHOR,
+                };
+
+            case "left":
+                return {
+                    marginTop: MIN_DISTANCE_FROM_CORNERS,
+                    marginBottom: MIN_DISTANCE_FROM_CORNERS,
+                    paddingRight: DISTANCE_FROM_ANCHOR,
+                };
+
+            default:
+                throw new Error(`Unknown placement: ${placement}`);
+        }
+    }
+
+    _renderArrow(): React.Node {
+        const {
+            trimlinePoints,
+            points,
+            height,
+            width,
+        } = this._calculateDimensionsFromPlacement();
+
+        const {color} = this.props;
+
+        return (
+            <svg
+                className={css(styles.arrow)}
+                style={this._getArrowStyle()}
+                width={width}
+                height={height}
+            >
+                {this._maybeRenderDropshadow(points)}
+
+                {/**
+                 * Draw the actual background of the tooltip arrow.
+                 *
+                 * We draw the outline in white too so that when we draw the
+                 * outline, it draws over white and not the dropshadow behind.
+                 */}
+                <polyline
+                    fill={Colors[color]}
+                    stroke={Colors[color]}
+                    points={points.join(" ")}
+                />
+
+                {/* Draw the tooltip outline around the tooltip arrow. */}
+                <polyline
+                    // Redraw the stroke on top of the background color,
+                    // so that the ends aren't extra dark where they meet
+                    // the border of the tooltip.
+                    fill={Colors[color]}
+                    points={points.join(" ")}
+                    stroke={Colors.offBlack16}
+                />
+
+                {/* Draw a trimline to make the arrow appear flush */}
+                <polyline
+                    stroke={Colors[color]}
+                    points={trimlinePoints.join(" ")}
+                />
+            </svg>
+        );
+    }
+
+    render(): React.Node {
+        const {offset, placement, updateRef} = this.props;
+        return (
+            <View
+                style={[
+                    styles.tailContainer,
+                    {...offset},
+                    this._getContainerStyle(),
+                ]}
+                data-placement={placement}
+                ref={updateRef}
+            >
+                {this._renderArrow()}
+            </View>
+        );
+    }
+}
+
+/**
+ * Some constants to make style generation easier to understand.
+ * NOTE: The widths and heights refer to the downward-pointing tail
+ * (i.e. placement="top"). When the tail points to the left or right instead,
+ * the width/height are inverted.
+ */
+const DISTANCE_FROM_ANCHOR = Spacing.xSmall_8;
+
+const MIN_DISTANCE_FROM_CORNERS = Spacing.xSmall_8;
+
+const ARROW_WIDTH = Spacing.large_24;
+const ARROW_HEIGHT = Spacing.small_12;
+
+const styles = StyleSheet.create({
+    /**
+     * Container
+     */
+    tailContainer: {
+        position: "relative",
+        pointerEvents: "none",
+    },
+
+    /**
+     * Arrow
+     */
+    arrow: {
+        // Ensure the dropshadow bleeds outside our bounds.
+        overflow: "visible",
+    },
+});

package/src/components/tooltip-tail.md

@@ -0,0 +1,143 @@
+The `TooltipTail` renders the tail, including appropriate padding from the anchor location and corners of the tooltip bubble (so as space out the bubble corners).
+
+Each example is shown next to a bar that indicates the padding either side of the tail and the tail width itself. The bar also indicates how far away from the anchor element the tail will render.
+
+### Placement top
+
+```jsx
+import {StyleSheet} from "aphrodite";
+import {View} from "@khanacademy/wonder-blocks-core";
+import {Spring} from "@khanacademy/wonder-blocks-layout";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+
+const styles = StyleSheet.create({
+    guideContainer: {
+        flexDirection: "row",
+        height: Spacing.xxxSmall_4,
+    },
+    padding: {
+        backgroundColor: "bisque",
+        width: Spacing.xSmall_8,
+    },
+    tail: {
+        backgroundColor: "green",
+        width: Spacing.large_24,
+    },
+});
+
+<View>
+    <TooltipTail placement="top" />
+    <View style={styles.guideContainer}>
+        <View key="padleft" style={styles.padding} />
+        <View key="tail" style={styles.tail} />
+        <View key="padright" style={styles.padding} />
+        <Spring key="spring" />
+    </View>
+</View>
+```
+
+### Placement right
+
+```jsx
+import {StyleSheet} from "aphrodite";
+import {View} from "@khanacademy/wonder-blocks-core";
+import {Spring} from "@khanacademy/wonder-blocks-layout";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+
+const styles = StyleSheet.create({
+    exampleContainer: {
+        flexDirection: "row",
+    },
+    guideContainer: {
+        width: Spacing.xxxSmall_4,
+    },
+    padding: {
+        backgroundColor: "bisque",
+        height: Spacing.xSmall_8,
+    },
+    tail: {
+        backgroundColor: "green",
+        height: Spacing.large_24,
+    },
+});
+
+<View style={styles.exampleContainer}>
+    <View style={styles.guideContainer}>
+        <View key="padleft" style={styles.padding} />
+        <View key="tail" style={styles.tail} />
+        <View key="padright" style={styles.padding} />
+        <Spring key="spring" />
+    </View>
+    <TooltipTail placement="right" />
+</View>
+```
+
+### Placement bottom
+
+```jsx
+import {StyleSheet} from "aphrodite";
+import {View} from "@khanacademy/wonder-blocks-core";
+import {Spring} from "@khanacademy/wonder-blocks-layout";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+
+const styles = StyleSheet.create({
+    guideContainer: {
+        flexDirection: "row",
+        height: Spacing.xxxSmall_4,
+    },
+    padding: {
+        backgroundColor: "bisque",
+        width: Spacing.xSmall_8,
+    },
+    tail: {
+        backgroundColor: "green",
+        width: Spacing.large_24,
+    },
+});
+
+<View>
+    <View style={styles.guideContainer}>
+        <View key="padleft" style={styles.padding} />
+        <View key="tail" style={styles.tail} />
+        <View key="padright" style={styles.padding} />
+        <Spring key="spring" />
+    </View>
+    <TooltipTail placement="bottom" />
+</View>
+```
+
+### Placement left
+
+```jsx
+import {StyleSheet} from "aphrodite";
+import {View} from "@khanacademy/wonder-blocks-core";
+import {Spring} from "@khanacademy/wonder-blocks-layout";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+
+const styles = StyleSheet.create({
+    exampleContainer: {
+        flexDirection: "row",
+    },
+    guideContainer: {
+        width: Spacing.xxxSmall_4,
+    },
+    padding: {
+        backgroundColor: "bisque",
+        height: Spacing.xSmall_8,
+    },
+    tail: {
+        backgroundColor: "green",
+        height: Spacing.large_24,
+    },
+});
+
+<View style={styles.exampleContainer}>
+    <TooltipTail placement="left" />
+    <View style={styles.guideContainer}>
+        <View key="padleft" style={styles.padding} />
+        <View key="tail" style={styles.tail} />
+        <View key="padright" style={styles.padding} />
+        <Spring key="spring" />
+    </View>
+</View>
+```