@khanacademy/perseus 3.0.0 → 4.0.0

package/src/components/tooltip.tsx

@@ -0,0 +1,392 @@
+/**
+ * A generic tooltip library for React.js
+ *
+ * This should eventually end up in react-components
+ *
+ * Interface: ({a, b} means one of a or b)
+ * import Tooltip from "./tooltip";
+ * <Tooltip
+ *     className="class-for-tooltip-contents"
+ *     horizontalPosition="left" // one of "left", "right"
+ *     horizontalAlign="left" // one of "left", "right"
+ *     verticalPosition="bottom" // one of "top", "bottom"
+ *     arrowSize={10} // arrow size in pixels
+ *     borderColor="#ccc" // color of the border for the tooltip
+ *     show={true} // whether the tooltip should currently be visible
+ *     targetContainerStyle={targetContainerStyle}
+ * >
+ *     <TargetElementOfTheTooltip />
+ *     <TooltipContents1 />
+ *     <TooltipContents2 />
+ * </Tooltip>
+ *
+ * To show/hide the tooltip, the parent component should call the
+ * .show() and .hide() methods of the tooltip when appropriate.
+ * (These are usually set up as handlers of events on the target element.)
+ *
+ * Notes:
+ *     className should not specify a border; that is handled by borderColor
+ *     so that the arrow and tooltip match
+ */
+
+//          __,,--``\\
+//  _,,-''``         \\     ,
+// '----------_.------'-.___|\__
+//    _.--''``    `)__   )__   @\__
+//   (  .. ''---/___,,E/__,E'------`
+//    `-''`''
+// Here be dragons.
+
+// TODO(joel/aria) fix z-index issues https://s3.amazonaws.com/uploads.hipchat.com/6574/29028/yOApjwmgiMhEZYJ/Screen%20Shot%202014-05-30%20at%203.34.18%20PM.png
+// z-index: 3 on perseus-formats-tooltip seemed to work
+
+import createReactClass from "create-react-class";
+import PropTypes from "prop-types";
+import * as React from "react";
+import ReactDOM from "react-dom";
+
+const zIndex = 10;
+
+const Triangle = createReactClass({
+    propTypes: {
+        color: PropTypes.string.isRequired,
+        left: PropTypes.number.isRequired,
+        top: PropTypes.number.isRequired,
+        width: PropTypes.number.isRequired,
+        height: PropTypes.number.isRequired,
+        horizontalDirection: PropTypes.oneOf(["left", "right"]).isRequired,
+        verticalDirection: PropTypes.oneOf(["top", "bottom"]).isRequired,
+    },
+
+    render: function () {
+        let borderLeft;
+        let borderRight;
+        let borderTop;
+        let borderBottom;
+
+        const hBorder = `${this.props.width}px solid transparent`;
+        if (this.props.horizontalDirection === "right") {
+            borderLeft = hBorder;
+        } else {
+            borderRight = hBorder;
+        }
+
+        const vBorder = `${this.props.height}px solid ${this.props.color}`;
+        if (this.props.verticalDirection === "top") {
+            borderTop = vBorder;
+        } else {
+            borderBottom = vBorder;
+        }
+
+        return (
+            <div
+                style={{
+                    display: "block",
+                    height: 0,
+                    width: 0,
+                    position: "absolute",
+                    left: this.props.left,
+                    top: this.props["top"],
+                    borderLeft: borderLeft,
+                    borderRight: borderRight,
+                    borderTop: borderTop,
+                    borderBottom: borderBottom,
+                }}
+            />
+        );
+    },
+});
+
+const TooltipArrow = createReactClass({
+    propTypes: {
+        position: PropTypes.string,
+        visibility: PropTypes.string,
+        left: PropTypes.number,
+        top: PropTypes.number,
+        color: PropTypes.string.isRequired, // a css color
+        border: PropTypes.string.isRequired, // a css color
+        width: PropTypes.number.isRequired,
+        height: PropTypes.number.isRequired,
+        horizontalDirection: PropTypes.oneOf(["left", "right"]).isRequired,
+        verticalDirection: PropTypes.oneOf(["top", "bottom"]).isRequired,
+    },
+
+    getDefaultProps: function () {
+        return {
+            position: "relative",
+            visibility: "visible",
+            left: 0,
+            top: 0,
+        };
+    },
+
+    // TODO(aria): Think about adding a box-shadow to the triangle here
+    // See http://css-tricks.com/triangle-with-shadow/
+    render: function () {
+        //const isRight = (this.props.horizontalDirection === "right");
+        const isTop = this.props.verticalDirection === "top";
+
+        const frontTopOffset = isTop ? 0 : 1;
+        const borderTopOffset = isTop ? 0 : -1;
+
+        return (
+            <div
+                style={{
+                    display: "block",
+                    position: this.props.position,
+                    visibility: this.props.visibility,
+                    left: this.props.left,
+                    top: this.props["top"],
+                    width: this.props.width + 2,
+                    height: this.props.height + 1,
+                    marginTop: -1,
+                    marginBottom: -2,
+                    zIndex: zIndex,
+                }}
+            >
+                {/* The background triangle used to create the effect of a
+                border around the foreground triangle*/}
+                <Triangle
+                    horizontalDirection={this.props.horizontalDirection}
+                    verticalDirection={this.props.verticalDirection}
+                    color={this.props.border}
+                    left={0}
+                    top={borderTopOffset}
+                    width={this.props.width + 2} // one extra for the diagonal
+                    height={this.props.height + 2}
+                />
+                {/* The foreground triangle covers all but the left/right edges
+                of the background triangle */}
+                <Triangle
+                    horizontalDirection={this.props.horizontalDirection}
+                    verticalDirection={this.props.verticalDirection}
+                    color={this.props.color}
+                    left={1}
+                    top={frontTopOffset}
+                    width={this.props.width}
+                    height={this.props.height}
+                />
+            </div>
+        );
+    },
+});
+
+const VERTICAL_CORNERS = {
+    top: {
+        top: "-100%",
+    },
+    bottom: {
+        top: 0,
+    },
+} as const;
+
+const HORIZONTAL_CORNERS = {
+    left: {
+        targetLeft: 0,
+    },
+
+    right: {
+        targetLeft: "100%",
+    },
+} as const;
+
+const HORIZONTAL_ALIGNMNENTS = {
+    left: {
+        tooltipLeft: 0,
+        arrowLeft: (arrowSize) => 0,
+    },
+    right: {
+        tooltipLeft: "-100%",
+        arrowLeft: (arrowSize) => -arrowSize - 2,
+    },
+} as const;
+
+// eslint-disable-next-line react/no-unsafe
+const Tooltip = createReactClass({
+    propTypes: {
+        show: PropTypes.bool.isRequired,
+        className: PropTypes.string,
+        arrowSize: PropTypes.number,
+        borderColor: PropTypes.string,
+        verticalPosition: PropTypes.oneOf(Object.keys(VERTICAL_CORNERS)),
+        horizontalPosition: PropTypes.oneOf(Object.keys(HORIZONTAL_CORNERS)),
+        horizontalAlign: PropTypes.oneOf(Object.keys(HORIZONTAL_ALIGNMNENTS)),
+        children: PropTypes.arrayOf(PropTypes.element).isRequired,
+        targetContainerStyle: PropTypes.any, // style object
+    },
+
+    getDefaultProps: function () {
+        return {
+            className: "",
+            arrowSize: 10,
+            borderColor: "#ccc",
+            verticalPosition: "bottom",
+            horizontalPosition: "left",
+            horizontalAlign: "left",
+            targetContainerStyle: {},
+        };
+    },
+
+    getInitialState: function () {
+        return {
+            height: null, // used for offsetting "top" positioned tooltips
+        };
+    },
+
+    componentDidMount: function () {
+        this._updateHeight();
+    },
+
+    UNSAFE_componentWillReceiveProps: function () {
+        // If the contents have changed, reset our measure of the height
+        this.setState({height: null});
+    },
+
+    componentDidUpdate: function () {
+        this._updateHeight();
+    },
+
+    _renderToolTipDiv: function (isTooltipAbove) {
+        const settings = Object.assign(
+            {},
+            HORIZONTAL_CORNERS[this.props.horizontalPosition],
+            HORIZONTAL_ALIGNMNENTS[this.props.horizontalAlign],
+            VERTICAL_CORNERS[this.props.verticalPosition],
+        );
+
+        let arrowAbove;
+        let arrowBelow;
+
+        if (isTooltipAbove) {
+            // We put an absolutely positioned arrow in the correct place
+            arrowAbove = (
+                <TooltipArrow
+                    verticalDirection="top"
+                    horizontalDirection={this.props.horizontalAlign}
+                    position="absolute"
+                    color="white"
+                    border={this.props.borderColor}
+                    left={settings.arrowLeft(this.props.arrowSize)}
+                    top={-this.props.arrowSize + 2}
+                    width={this.props.arrowSize}
+                    height={this.props.arrowSize}
+                    zIndex={zIndex}
+                />
+            );
+
+            // And we use a visibility: hidden arrow below to shift up the
+            // content by the correct amount
+            arrowBelow = (
+                <TooltipArrow
+                    verticalDirection="top"
+                    horizontalDirection={this.props.horizontalAlign}
+                    visibility="hidden"
+                    color="white"
+                    border={this.props.borderColor}
+                    left={settings.arrowLeft(this.props.arrowSize)}
+                    top={-1}
+                    width={this.props.arrowSize}
+                    height={this.props.arrowSize}
+                    zIndex={zIndex}
+                />
+            );
+        } else {
+            arrowAbove = (
+                <TooltipArrow
+                    verticalDirection="bottom"
+                    horizontalDirection={this.props.horizontalAlign}
+                    color="white"
+                    border={this.props.borderColor}
+                    left={settings.arrowLeft(this.props.arrowSize)}
+                    top={-1}
+                    width={this.props.arrowSize}
+                    height={this.props.arrowSize}
+                    zIndex={zIndex}
+                />
+            );
+
+            arrowBelow = null;
+        }
+
+        /* A positioned div below the input to be the parent for our
+            tooltip */
+        return (
+            <div
+                style={{
+                    position: "relative",
+                    height: 0,
+                    display: this.props.show ? "block" : "none",
+                }}
+            >
+                <div
+                    // eslint-disable-next-line react/no-string-refs
+                    ref="tooltipContainer"
+                    className="tooltipContainer"
+                    style={{
+                        position: "absolute",
+                        // height must start out undefined, not null, so that
+                        // we can measure the actual height with jquery.
+                        // This is used to position the tooltip with top: -100%
+                        // when in verticalPosition: "top" mode
+                        height: this.state.height || undefined,
+                        left: settings.targetLeft,
+                    }}
+                >
+                    {arrowAbove}
+
+                    {/* The contents of the tooltip */}
+                    <div
+                        className={this.props.className}
+                        // eslint-disable-next-line react/no-string-refs
+                        ref="tooltipContent"
+                        style={{
+                            position: "relative",
+                            top: settings["top"],
+                            left: settings.tooltipLeft,
+                            border: "1px solid " + this.props.borderColor,
+                            boxShadow: "0 1px 3px " + this.props.borderColor,
+                            zIndex: zIndex - 1,
+                        }}
+                    >
+                        {this.props.children.slice(1)}
+                    </div>
+
+                    {arrowBelow}
+                </div>
+            </div>
+        );
+    },
+
+    _updateHeight: function () {
+        const tooltipContainer = ReactDOM.findDOMNode(
+            // eslint-disable-next-line react/no-string-refs
+            this.refs.tooltipContainer,
+        ) as HTMLDivElement;
+        const height = tooltipContainer.offsetHeight;
+        if (height !== this.state.height) {
+            this.setState({height});
+        }
+    },
+
+    render: function () {
+        const isTooltipAbove = this.props.verticalPosition === "top";
+
+        /* We wrap the entire output in a span so that it displays inline */
+        return (
+            <span>
+                {isTooltipAbove && this._renderToolTipDiv(isTooltipAbove)}
+
+                {/* We wrap our input in a div so that we can put the tooltip in a
+                div above/below it */}
+                <div style={this.props.targetContainerStyle}>
+                    {this.props.children[0]}
+                </div>
+
+                {!isTooltipAbove && this._renderToolTipDiv()}
+            </span>
+        );
+    },
+});
+
+// Sorry.  // Apology-Oriented-Programming
+export default Tooltip;

package/src/components/visibility-observer/__stories__/visibility-observer.stories.tsx

@@ -0,0 +1,143 @@
+import * as React from "react";
+
+// eslint-disable-next-line import/no-named-as-default
+import VisibilityObserver from "../visibility-observer";
+
+import type {ScrollVisibility} from "../visibility-observer";
+
+type StoryArgs = Record<any, any>;
+
+type Story = {
+    title: string;
+};
+
+export default {
+    title: "Perseus/Components/Visibility Observer",
+} as Story;
+
+type Props = Record<any, any>;
+type State = {
+    sectionVisibility: ScrollVisibility;
+};
+
+class VisibilityTest extends React.Component<Props, State> {
+    state: State = {
+        sectionVisibility: "unknown",
+    };
+
+    handleVisibilityChanged = (visibility: ScrollVisibility) => {
+        this.setState({sectionVisibility: visibility});
+    };
+
+    render(): React.ReactNode {
+        const {sectionVisibility} = this.state;
+
+        const visibleText =
+            sectionVisibility === "visible" ? "Visible" : "Not Visible";
+
+        return (
+            <div>
+                <p>Visibility: {visibleText}</p>
+
+                <p>
+                    {sectionVisibility === "hidden-above"
+                        ? "The Section IS UP HERE!!!"
+                        : "---"}
+                </p>
+
+                <div
+                    style={{
+                        height: 150,
+                        width: 800,
+                        overflow: "scroll",
+                        backgroundColor: "white",
+                        // @ts-expect-error [FEI-5003] - TS2322 - Type '{ height: number; width: number; overflow: "scroll"; backgroundColor: "white"; scrollbars: string; }' is not assignable to type 'Properties<string | number, string & {}>'.
+                        scrollbars: "visible",
+                    }}
+                >
+                    <p>
+                        Ocicat american shorthair. Egyptian mau himalayan or
+                        grimalkin maine coon cheetah lion but himalayan.
+                        American bobtail lion kitten. Kitty bombay puma.
+                        Savannah scottish fold for tabby but sphynx for bombay
+                        kitten ragdoll. Puma russian blue yet singapura birman
+                        and kitty russian blue. Egyptian mau cheetah, donskoy
+                        for himalayan singapura abyssinian . Singapura
+                        himalayan. Malkin abyssinian but balinese but bobcat.
+                        Leopard puma, norwegian forest mouser and turkish
+                        angora. Lynx bengal tiger. American shorthair. Donskoy
+                        ragdoll. Siberian turkish angora cougar and russian
+                        blue. Burmese savannah and siamese norwegian forest yet
+                        cheetah himalayan lion. Ocelot kitten or munchkin but
+                        kitten savannah. Cougar manx or russian blue american
+                        shorthair so jaguar but havana brown. Cheetah havana
+                        brown manx. Tiger thai american bobtail. Ragdoll bengal
+                        yet kitten, bengal grimalkin scottish fold. Abyssinian
+                        jaguar. Turkish angora bengal but kitty sphynx.{" "}
+                    </p>
+
+                    <VisibilityObserver
+                        scrollParentIsNotBody={true}
+                        onChange={this.handleVisibilityChanged}
+                    >
+                        <p
+                            style={{
+                                backgroundColor: "#eeddee",
+                                fontWeight: "bold",
+                            }}
+                        >
+                            American shorthair devonshire rex but cheetah and
+                            ragdoll but bombay. Kitty. Tomcat cornish rex
+                            donskoy but tom donskoy havana brown. Jaguar sphynx.
+                            Cheetah kitty for kitty, but balinese . British
+                            shorthair cheetah devonshire rex birman panther.
+                            Kitten tabby but siamese, sphynx. Bombay maine coon
+                            so lynx and donskoy kitten, but cougar. Sphynx
+                            sphynx, so american bobtail or mouser or puma.
+                            Mouser munchkin and ragdoll yet mouser cheetah
+                            balinese . Egyptian mau siamese mouser, cougar
+                            ragdoll. Persian birman tabby. Norwegian forest
+                            norwegian forest cornish rex bengal. Panther bombay.
+                            Kitty siamese ragdoll and egyptian mau. Tabby.
+                            Cheetah havana brown, kitty for havana brown.
+                            Cornish rex siberian russian blue so persian but
+                            thai burmese. Maine coon puma. Lynx.
+                        </p>
+                    </VisibilityObserver>
+
+                    <p>
+                        Jaguar tom but himalayan birman. Turkish angora balinese
+                        grimalkin but birman or kitty or munchkin. American
+                        shorthair bobcat. Donskoy cornish rex malkin. Ocicat
+                        tabby or siamese, birman. Devonshire rex tomcat yet thai
+                        jaguar mouser and donskoy, lynx. Grimalkin bombay.{" "}
+                    </p>
+                    <p>
+                        Eat grass, throw it back up mice and cats are fats i
+                        like to pets them they like to meow back, cough furball
+                        into food bowl then scratch owner for a new one purr as
+                        loud as possible, be the most annoying cat that you can,
+                        and, knock everything off the table, lick the other
+                        cats. Furrier and even more furrier hairball cat is
+                        love, cat is life so ooh, are those your $250 dollar
+                        sandals? lemme use that as my litter box. Lick arm hair
+                        love to play with owner's hair tie hunt anything that
+                        moves. Destroy couch as revenge when in doubt, wash.
+                    </p>
+                </div>
+
+                <p>
+                    {sectionVisibility === "hidden-below"
+                        ? "The Section IS DOWN HERE!!!"
+                        : "---"}
+                </p>
+            </div>
+        );
+    }
+}
+
+export const AlertWhenNotVisible: React.FC<StoryArgs> = (
+    args,
+): React.ReactElement => {
+    return <VisibilityTest />;
+};

package/src/components/visibility-observer/create-visibility-observer.ts

@@ -0,0 +1,108 @@
+/**
+ * VisibilityObserver watches a target element for changes to visibility,
+ * relative to a given root node.
+ *
+ * When the target element entirely disappears, or partially reappears, the
+ * caller is notified via the `onVisibilityChange` callback.
+ *
+ * Potential visibility changes include:
+ *   - Being scrolled out of view, by any scroll container between the target
+ *         and the root.
+ *   - Style changes to the target element or an ancestor, like `display: none`.
+ *
+ * The VisibilityObserver relies on the IntersectionObserver, which does not
+ * exist on Safari and is buggy on Edge.  Instead, we will polyfill the
+ * IntersectionObserver on those platforms.
+ *
+ * TODO(mdr): Currently, we emulate the API of IntersectionObserver. It might
+ *     be nicer to instead use a more React-y API: let `targetElement` be a
+ *     required prop, and render the element only when it's present. Then, we
+ *     can use React lifecycle methods to set-up/tear-down handlers. Not sure
+ *     that's _actually_ a net win, though, in complexity or performance - but
+ *     worth thinking about if this API is causing too much entanglement!
+ */
+// NOTE(jeresig): As of 2021-03-02 there are still a non-trivial number of
+// pre-Safari 12.1 users and they need a polyfill for IntersectionObserver
+// eslint-disable-next-line import/no-unassigned-import
+import "intersection-observer";
+
+export interface VisibilityObserver {
+    // Set the element whose visibility we're observing.
+    setTargetElement(targetElement: HTMLElement): void;
+    // Stop observing the previously-set target element, if any.
+    //
+    // When the target element unmounts, please call this method to clean up!
+    disconnect(): void;
+}
+
+type VisibilityChangeCallback = (
+    isVisible: boolean,
+    rootBounds: DOMRectReadOnly,
+) => void;
+
+/**
+ * Create a new VisibilityObserver.
+ */
+export function createVisibilityObserver(
+    rootElement: HTMLElement | null | undefined,
+    onVisibilityChange: VisibilityChangeCallback,
+    rootMargin?: string,
+): VisibilityObserver {
+    return new NativeVisibilityObserver(
+        rootElement,
+        onVisibilityChange,
+        rootMargin,
+    );
+}
+
+/**
+ * A VisibilityObserver that uses IntersectionObserver to leverage the
+ * browser's native ability to determine how much of an element is visible.
+ * https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API
+ */
+class NativeVisibilityObserver implements VisibilityObserver {
+    _intersectionObserver: IntersectionObserver;
+    _onVisibilityChange: VisibilityChangeCallback;
+
+    constructor(
+        rootElement: HTMLElement | null | undefined,
+        onVisibilityChange: VisibilityChangeCallback,
+        rootMargin?: string,
+    ) {
+        // Create an IntersectionObserver with a threshold of "epsilon", the
+        // smallest positive non-zero number. This means that, whenever the
+        // target element enters or exits total invisibility, the handler will
+        // be called.
+        this._intersectionObserver = new IntersectionObserver(
+            this._handleIntersection,
+            {
+                root: rootElement,
+                threshold: Number.EPSILON,
+                rootMargin,
+            },
+        );
+        this._onVisibilityChange = onVisibilityChange;
+    }
+
+    _handleIntersection = (
+        entries: ReadonlyArray<IntersectionObserverEntry>,
+    ) => {
+        // There should be exactly one entry, but let's be defensive and loop.
+        //
+        for (const entry of entries) {
+            // @ts-expect-error [FEI-5003] - TS2345 - Argument of type 'DOMRectReadOnly | null' is not assignable to parameter of type 'DOMRectReadOnly'.
+            this._onVisibilityChange(entry.isIntersecting, entry.rootBounds);
+        }
+    };
+
+    setTargetElement(targetElement: HTMLElement) {
+        // Because this class only watches one element at a time, we disconnect
+        // from all other observed elements first, just in case.
+        this._intersectionObserver.disconnect();
+        this._intersectionObserver.observe(targetElement);
+    }
+
+    disconnect() {
+        this._intersectionObserver.disconnect();
+    }
+}

package/src/components/visibility-observer/get-scroll-parent.ts

@@ -0,0 +1,46 @@
+// Utility for finding the scroll parent of a chile
+// Taken and updated to our standards from
+// https://github.com/olahol/scrollparent.js
+
+const getParents = function (node: Node, parents): ReadonlyArray<Node> {
+    if (!node.parentNode) {
+        return parents;
+    }
+
+    return getParents(node.parentNode, parents.concat([node]));
+};
+
+const style = function (node: Element, prop) {
+    return getComputedStyle(node).getPropertyValue(prop);
+};
+
+const overflow = function (node: Element) {
+    return (
+        style(node, "overflow") +
+        style(node, "overflow-y") +
+        style(node, "overflow-x")
+    );
+};
+
+const scroll = function (node: Element) {
+    return /(auto|scroll)/.test(overflow(node));
+};
+
+export const getScrollParent = function (
+    node: Element,
+): Element | null | undefined {
+    if (!(node instanceof HTMLElement)) {
+        return;
+    }
+
+    const parents = node.parentNode ? getParents(node.parentNode, []) : [];
+
+    for (let i = 0; i < parents.length; i += 1) {
+        const element = parents[i] as Element;
+        if (scroll(element)) {
+            return element;
+        }
+    }
+
+    return document.documentElement;
+};