@khanacademy/perseus 0.0.1 → 0.2.1

package/src/components/visibility-observer/visibility-observer.jsx

@@ -0,0 +1,123 @@
+// @flow
+/**
+ * This is a wrapper component for the visibility-observer.js utility which
+ * abstracts the native or polyfilled IntersectionObserver utility.  The
+ * primary purpose of this comonent is to tell you whether the children of
+ * the component are visibile within a scrollable ancestor.  It will notify
+ * you via an onChange event when the visibility changes, and whether the
+ * children are below or above the scroll.
+ */
+import * as React from "react";
+import ReactDOM from "react-dom";
+
+import {getScrollParent} from "./get-scroll-parent.js";
+import {createVisibilityObserver} from "./visibility-observer.js";
+
+import type {VisibilityObserver as IVisibilityObserver} from "./visibility-observer.js";
+
+export type ScrollVisibility =
+    | "hidden-above"
+    | "hidden-below"
+    | "visible"
+    | "unknown";
+
+type Props = {|
+    children: React.Node,
+    rootMargin?: string,
+
+    // In most cases, the scroll parent we want to compare against is the body.  Sometimes,
+    // there will be a scroll parent which scrolls independant of the body.  In that case,
+    // the math is different and we need to be told to find the scroll parent.
+    scrollParentIsNotBody?: boolean,
+
+    onChange: (visibility: ScrollVisibility) => void,
+|};
+
+function findPositionInScrollContainer(
+    childNode: HTMLElement,
+    bounds: DOMRectReadOnly,
+    scrollParentIsNotBody: boolean,
+): ScrollVisibility {
+    try {
+        const scrollParent = getScrollParent(childNode);
+        if (!scrollParent) {
+            return "unknown";
+        }
+
+        const parentRect = scrollParent.getBoundingClientRect();
+        const childRect = childNode.getBoundingClientRect();
+
+        const isAbove =
+            !scrollParentIsNotBody || scrollParent === document.body
+                ? childRect.bottom < bounds.top
+                : childRect.bottom < parentRect.top;
+
+        return isAbove ? "hidden-above" : "hidden-below";
+    } catch (e) {
+        return "unknown";
+    }
+}
+
+class VisibilityObserver extends React.Component<Props> {
+    _observer: IVisibilityObserver;
+    _node: HTMLElement;
+
+    static defaultProps: {|onChange: () => void|} = {
+        onChange: () => {},
+    };
+
+    componentDidMount() {
+        this._node = ((ReactDOM.findDOMNode(this): any): HTMLElement);
+
+        this.registerVisibilityObserver();
+    }
+
+    componentWillUnmount() {
+        this.unregisterVisibilityObserver();
+    }
+
+    handleVisibilityChange: (
+        isVisible: boolean,
+        rootBounds: DOMRectReadOnly,
+    ) => void = (isVisible: boolean, rootBounds: DOMRectReadOnly) => {
+        const {scrollParentIsNotBody, onChange} = this.props;
+
+        if (isVisible) {
+            onChange("visible");
+        } else {
+            const visibility = findPositionInScrollContainer(
+                this._node,
+                rootBounds,
+                !!scrollParentIsNotBody,
+            );
+            onChange(visibility);
+        }
+    };
+
+    registerVisibilityObserver() {
+        const {rootMargin} = this.props;
+        if (!this._node) {
+            return;
+        }
+
+        this._observer = createVisibilityObserver(
+            null,
+            this.handleVisibilityChange,
+            rootMargin,
+        );
+
+        this._observer.setTargetElement(this._node);
+    }
+
+    unregisterVisibilityObserver() {
+        if (this._observer) {
+            this._observer.disconnect();
+        }
+    }
+
+    render(): React.Node {
+        return this.props.children;
+    }
+}
+
+export default VisibilityObserver;

package/src/components/zoomable-tex.jsx

@@ -0,0 +1,70 @@
+// @flow
+
+/**
+ * ZoomableTeX is a wrapper around TeX to be used on mobile.  Without wrapping
+ * TeX we run into issues of measuring at the incorrect time resulting in bad
+ * measurements.
+ */
+
+import * as React from "react";
+
+import AssetContext from "../asset-context.js";
+
+import TeX from "./tex.jsx";
+import Zoomable from "./zoomable.jsx";
+
+type Props = {|children: string|};
+type State = {|isRendered: boolean|};
+
+const computeMathBounds = (parentNode, parentBounds) => {
+    const textElement =
+        parentNode.querySelector(".katex-html") ||
+        parentNode.querySelector(".MathJax");
+    const textBounds = {
+        // $FlowFixMe[incompatible-use]
+        width: textElement.offsetWidth,
+        // $FlowFixMe[incompatible-use]
+        height: textElement.offsetHeight,
+    };
+
+    // HACK(benkomalo): when measuring math content, note that
+    // sometimes it actually peeks outside of the
+    // container in some cases. Just be conservative and use
+    // the maximum value of the text and the parent. :(
+    return {
+        width: Math.max(parentBounds.width, textBounds.width),
+        height: Math.max(parentBounds.height, textBounds.height),
+    };
+};
+
+export default class ZoomableTeX extends React.Component<Props, State> {
+    constructor() {
+        super();
+
+        this.state = {isRendered: false};
+    }
+
+    handleRender: () => void = () => {
+        this.setState({isRendered: true});
+    };
+
+    render(): React.Node {
+        return (
+            <Zoomable
+                readyToMeasure={this.state.isRendered}
+                computeChildBounds={computeMathBounds}
+            >
+                <AssetContext.Consumer>
+                    {({setAssetStatus}) => (
+                        <TeX
+                            onRender={this.handleRender}
+                            setAssetStatus={setAssetStatus}
+                        >
+                            {this.props.children}
+                        </TeX>
+                    )}
+                </AssetContext.Consumer>
+            </Zoomable>
+        );
+    }
+}

package/src/components/zoomable.jsx

@@ -0,0 +1,304 @@
+// @flow
+/**
+ * Zooms child to fit with tap-to-zoom behavior.
+ */
+
+import * as React from "react";
+import ReactDOM from "react-dom";
+
+type Bounds = {|
+    width: number,
+    height: number,
+|};
+
+type Props = {|
+    children: React.Node,
+    animateHeight: boolean,
+
+    /**
+     * Optional function that allows customizations in zooming.
+     *
+     * Defaults to just using the bounding client rect of the first DOM
+     * element of this component.
+     */
+    computeChildBounds: (
+        parentNode: HTMLElement,
+        parentBounds: Bounds,
+    ) => Bounds,
+
+    /**
+     * Optional boolean specifying whether the component is ready to measure
+     * or not.  Defaults to true for synchronous components like tables.
+     */
+    readyToMeasure: boolean,
+|};
+
+type DefaultProps = {|
+    animateHeight: Props["animateHeight"],
+    computeChildBounds: Props["computeChildBounds"],
+    readyToMeasure: Props["readyToMeasure"],
+|};
+
+type State = {|
+    visible: boolean,
+    marginBottomPx: number,
+    compactHeight?: ?number,
+    expandedHeight?: ?number,
+    scale?: ?number,
+    zoomed: boolean,
+|};
+
+class Zoomable extends React.Component<Props, State> {
+    _isMounted: boolean;
+    _observer: MutationObserver;
+    _measuringInitialized: boolean;
+    _originalWidth: ?number;
+    _node: HTMLElement;
+
+    static defaultProps: DefaultProps = {
+        animateHeight: false,
+        readyToMeasure: true,
+        computeChildBounds: (parentNode) => {
+            const firstChild = parentNode.firstElementChild;
+
+            return {
+                // $FlowFixMe[incompatible-use]
+                // $FlowFixMe[prop-missing]
+                width: firstChild.offsetWidth,
+                // $FlowFixMe[incompatible-use]
+                // $FlowFixMe[prop-missing]
+                height: firstChild.offsetHeight,
+            };
+        },
+    };
+
+    state: State = {
+        visible: false,
+        marginBottomPx: 0,
+        zoomed: true,
+    };
+
+    componentDidMount() {
+        this._isMounted = true;
+        this.maybeInitializeMeasuring();
+    }
+
+    componentDidUpdate() {
+        this.maybeInitializeMeasuring();
+    }
+
+    componentWillUnmount() {
+        window.removeEventListener("resize", this.reset);
+        if (this._observer) {
+            this._observer.disconnect();
+        }
+
+        this._isMounted = false;
+    }
+
+    reset: () => void = (): void => {
+        if (!this._isMounted) {
+            return;
+        }
+        if (!this.state.visible) {
+            return;
+        }
+        this._originalWidth = null;
+        this.setState(
+            {
+                visible: false,
+                compactHeight: null,
+                expandedHeight: null,
+                zoomed: true,
+            },
+            () => {
+                this.measureAndScaleChildToFit(false);
+            },
+        );
+    };
+
+    /**
+     * Calls measureAndScaleChildToFit and sets up a MutationObserver
+     * to call measureAndScaleChildToFit if Zoomable's children change.
+     *
+     * If the readyToMeasure prop isn't true or if measuring has already
+     * been initialized this method does nothing.
+     */
+    maybeInitializeMeasuring() {
+        const shouldInitialize =
+            this.props.readyToMeasure && !this._measuringInitialized;
+
+        if (this._isMounted && shouldInitialize) {
+            this._measuringInitialized = true;
+            // $FlowFixMe[incompatible-type] - this is our root node, it won't be text
+            this._node = ReactDOM.findDOMNode(this);
+
+            // We call measureAndScaleChildToFit asynchronously so that the browser
+            // can apply CSS styles so that we get an accurate measurement.
+            // TODO(jeff, CP-3128): Use Wonder Blocks Timing API
+            // eslint-disable-next-line no-restricted-syntax
+            setTimeout(() => this.measureAndScaleChildToFit(false), 0);
+
+            if (window.MutationObserver) {
+                this._observer = new MutationObserver((mutations) => {
+                    if (this._isMounted) {
+                        for (const mutation of mutations) {
+                            if (mutation.target !== this._node) {
+                                // Only act on mutations of children
+                                this.measureAndScaleChildToFit(
+                                    this.state.zoomed,
+                                );
+                                break;
+                            }
+                        }
+                    }
+                });
+
+                this._observer.observe(this._node, {
+                    childList: true,
+                    subtree: true,
+                    attributes: true,
+                });
+            }
+            window.addEventListener("resize", this.reset);
+        }
+    }
+
+    stopPropagationIfZoomed: (e: SyntheticTouchEvent<>) => void = (
+        e: SyntheticTouchEvent<>,
+    ) => {
+        if (!this.state.zoomed) {
+            // We only allow touch events (which trigger interactive elements)
+            // to be propagated to children if we are already zoomed.
+            e.stopPropagation();
+        }
+    };
+
+    // TODO(benkomalo): call this on viewport width changes?
+    // https://github.com/Khan/math-input/blob/master/src/components/math-keypad.js#L43
+    measureAndScaleChildToFit(zoomed: boolean) {
+        if (!this._isMounted) {
+            return;
+        }
+        const parentBounds = {
+            width: this._node.offsetWidth,
+            height: this._node.offsetHeight,
+        };
+        const childBounds = this.props.computeChildBounds(
+            this._node,
+            parentBounds,
+        );
+
+        // The +1 is a fudge factor to make sure any border on the
+        // content isn't clipped by the the container it's in.
+        const childWidth = childBounds.width + 1;
+        const childHeight = childBounds.height + 1;
+
+        if (childWidth > parentBounds.width) {
+            const scale = parentBounds.width / childWidth;
+
+            this.setState({
+                scale,
+                zoomed,
+
+                compactHeight: Math.ceil(scale * childHeight),
+                expandedHeight: childHeight,
+            });
+
+            // TODO(charlie): Do this as a callback to `setState`. Something is
+            // going wrong with that approach in initial testing.
+            // TODO(jeff, CP-3128): Use Wonder Blocks Timing API
+            // eslint-disable-next-line no-restricted-syntax
+            setTimeout(() => {
+                // Only show it after the next paint, to allow for CSS
+                // transitions to fade it in.
+                if (this._isMounted) {
+                    this.setState({
+                        visible: true,
+                    });
+                }
+            });
+        } else {
+            this.setState({
+                visible: true,
+            });
+        }
+    }
+
+    handleClickIfZoomed: (e: SyntheticMouseEvent<>) => void = (
+        e: SyntheticMouseEvent<>,
+    ) => {
+        if (!this.state.zoomed) {
+            e.stopPropagation();
+            this.handleClick();
+        }
+    };
+
+    handleClick: () => void = () => {
+        this.setState({
+            zoomed: !this.state.zoomed,
+        });
+    };
+
+    render(): React.Node {
+        const {visible, scale, compactHeight, expandedHeight, zoomed} =
+            this.state;
+        const {animateHeight} = this.props;
+
+        const property = animateHeight
+            ? "opacity transform height"
+            : "opacity transform";
+
+        // Since we're not using aphrodite, we have to prefix ourselves.
+        const transitionStyle = visible
+            ? {
+                  transitionProperty: property,
+                  WebkitTransitionProperty: property,
+                  msTransitionProperty: property,
+                  transitionDuration: "0.3s",
+                  WebkitTransitionDuration: "0.3s",
+                  msTransitionDuration: "0.3s",
+                  transitionTimingFunction: "ease-out",
+                  WebkitTransitionTimingfunction: "ease-out",
+                  msTransitionTmingFunction: "ease-out",
+              }
+            : {};
+
+        // Do a fancy little slide as we fade the contents in the first time.
+        const translateOffset = visible ? "" : " translate(0, 8px)";
+        const scaleString = (scale ?? 1).toString();
+        const transform = zoomed
+            ? `scale(1, 1) ${translateOffset}`
+            : `scale(${scaleString}, ${scaleString}) ${translateOffset}`;
+
+        const style = {
+            display: "block",
+            width: "100%",
+            height: zoomed ? expandedHeight : compactHeight,
+            transform: transform,
+            WebkitTransform: transform,
+            msTransform: transform,
+            transformOrigin: "0 0",
+            WebkitTransformOrigin: "0 0",
+            msTransformOrigin: "0 0",
+            opacity: visible ? 1 : 0,
+            WebkitTapHighlightColor: "transparent",
+            ...transitionStyle,
+        };
+
+        return (
+            <span
+                onClick={this.handleClick}
+                onClickCapture={this.handleClickIfZoomed}
+                onTouchCancelCapture={this.stopPropagationIfZoomed}
+                onTouchEndCapture={this.stopPropagationIfZoomed}
+                onTouchStartCapture={this.stopPropagationIfZoomed}
+                style={style}
+            >
+                {this.props.children}
+            </span>
+        );
+    }
+}
+
+export default Zoomable;

package/src/components.js

@@ -0,0 +1,17 @@
+// @flow
+export {default as ButtonGroup} from "./components/button-group.jsx";
+export {default as Graph} from "./components/graph.jsx";
+export {default as Graphie} from "./components/graphie.jsx";
+export {default as HUD} from "./components/hud.jsx";
+export {default as Icon} from "./components/icon.jsx";
+export {default as InfoTip} from "./components/info-tip.jsx";
+export {default as InlineIcon} from "./components/inline-icon.jsx";
+export {default as MathInput} from "./components/math-input.jsx";
+export {default as MultiButtonGroup} from "./components/multi-button-group.jsx";
+export {default as NumberInput} from "./components/number-input.jsx";
+export {default as PropCheckBox} from "./components/prop-check-box.jsx";
+export {default as RangeInput} from "./components/range-input.jsx";
+export {default as SvgImage} from "./components/svg-image.jsx";
+export {default as TextInput} from "./components/text-input.jsx";
+export {default as TexButtons} from "./components/tex-buttons.jsx";
+export {default as TextListEditor} from "./components/text-list-editor.jsx";

package/src/dependencies.js

@@ -0,0 +1,22 @@
+// @flow
+import type {PerseusDependencies} from "./types.js";
+
+let _dependencies: ?PerseusDependencies = null;
+
+export const setDependencies = (dependencies: PerseusDependencies) => {
+    _dependencies = dependencies;
+};
+
+export const getDependencies = (): PerseusDependencies => {
+    if (_dependencies) {
+        return _dependencies;
+    }
+
+    throw new Error(
+        [
+            "Perseus has not been provided required dependencies.",
+            "setDependencies(dependencies) must be called first.",
+            "Make sure Perseus is being imported from javascript/perseus/perseus.js.",
+        ].join("\n"),
+    );
+};

package/src/error-boundary.jsx

@@ -0,0 +1,48 @@
+// @flow
+
+import * as React from "react";
+
+import {Errors, Log} from "./logging/log.js";
+
+type ErrorBoundaryProps = {|children: React.Node|};
+type ErrorBoundaryState = {|error: string|};
+
+class ErrorBoundary extends React.Component<
+    ErrorBoundaryProps,
+    ErrorBoundaryState,
+> {
+    constructor(props: ErrorBoundaryProps) {
+        super(props);
+        this.state = {error: ""};
+    }
+
+    componentDidCatch(error: Error, info: any) {
+        this.setState({error: error.toString()});
+        Log.error("Perseus error boundary caught error", Errors.Internal, {
+            cause: error,
+            loggedMetadata: {info: info.toString()},
+        });
+    }
+
+    render(): React.Node {
+        if (this.state.error) {
+            // TODO(djf): perhaps we should have one error boundary for
+            // inline elements and one for block elements. This one uses
+            // a <span> and effectively converts block elements with
+            // errors into inline elements.
+            // TODO(michaelpolyak): Link error icon to "Report a problem".
+            return (
+                <svg height="16" width="16" viewBox="0 0 16 16">
+                    <path
+                        d="m8 16c-4.42 0-8-3.58-8-8s3.58-8 8-8 8 3.58 8 8-3.58 8-8 8zm0-3c0.55 0 1-0.45 1-1s-0.45-1-1-1-1 0.45-1 1 0.45 1 1 1zm0-9c-0.55 0-1 0.45-1 1v4c0 0.55.45 1 1 1s1-0.45 1-1v-4c0-0.55-0.45-1-1-1z"
+                        fill="#d92916"
+                        fillRule="evenodd"
+                    />
+                </svg>
+            );
+        }
+        return this.props.children;
+    }
+}
+
+export default ErrorBoundary;

package/src/extra-widgets.js

@@ -0,0 +1,75 @@
+// @flow
+// As new widgets get added here, please also make sure they get added in
+// content_internal/perseus_traversal.py so they can be properly translated.
+
+import Categorizer from "./widgets/categorizer.jsx";
+import CSProgram from "./widgets/cs-program.jsx";
+import Definition from "./widgets/definition.jsx";
+import Dropdown from "./widgets/dropdown.jsx";
+import Explanation from "./widgets/explanation.jsx";
+import GradedGroupSet from "./widgets/graded-group-set.jsx";
+import GradedGroup from "./widgets/graded-group.jsx";
+import Grapher from "./widgets/grapher.jsx";
+import Group from "./widgets/group.jsx";
+import Iframe from "./widgets/iframe.jsx";
+import Image from "./widgets/image.jsx";
+import Interactive from "./widgets/interaction.jsx";
+import InteractiveGraph from "./widgets/interactive-graph.jsx";
+import LabelImage from "./widgets/label-image.jsx";
+import LightsPuzzle from "./widgets/lights-puzzle.jsx";
+import Matcher from "./widgets/matcher.jsx";
+import Matrix from "./widgets/matrix.jsx";
+import Measurer from "./widgets/measurer.jsx";
+import Molecule from "./widgets/molecule.jsx";
+import NumberLine from "./widgets/number-line.jsx";
+import Orderer from "./widgets/orderer.jsx";
+import PassageRefTarget from "./widgets/passage-ref-target.jsx";
+import PassageRef from "./widgets/passage-ref.jsx";
+import Passage from "./widgets/passage.jsx";
+import Plotter from "./widgets/plotter.jsx";
+import ReactionDiagram from "./widgets/reaction-diagram.jsx";
+import Sequence from "./widgets/sequence.jsx";
+import Simulator from "./widgets/simulator.jsx";
+import Sorter from "./widgets/sorter.jsx";
+import Table from "./widgets/table.jsx";
+import Transformer from "./widgets/transformer.jsx";
+import Unit from "./widgets/unit.jsx";
+import Video from "./widgets/video.jsx";
+
+import type {WidgetExports} from "./types.js";
+
+export default ([
+    Categorizer,
+    CSProgram,
+    Dropdown,
+    Explanation,
+    Definition,
+    Grapher,
+    GradedGroup,
+    GradedGroupSet,
+    Group,
+    Iframe,
+    Image,
+    Interactive,
+    InteractiveGraph,
+    LabelImage,
+    LightsPuzzle,
+    Matrix,
+    Matcher,
+    Measurer,
+    Molecule,
+    NumberLine,
+    Orderer,
+    Passage,
+    PassageRef,
+    PassageRefTarget,
+    Plotter,
+    ReactionDiagram,
+    Sequence,
+    Simulator,
+    Sorter,
+    Table,
+    Transformer,
+    Unit,
+    Video,
+]: $ReadOnlyArray<WidgetExports<>>);