@khanacademy/perseus 2.1.0 → 4.0.0

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

@@ -0,0 +1,124 @@
+/**
+ * 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 {createVisibilityObserver} from "./create-visibility-observer";
+import {getScrollParent} from "./get-scroll-parent";
+
+import type {VisibilityObserver as IVisibilityObserver} from "./create-visibility-observer";
+
+export type ScrollVisibility =
+    | "hidden-above"
+    | "hidden-below"
+    | "visible"
+    | "unknown";
+
+type Props = {
+    children: React.ReactNode;
+    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> {
+    // @ts-expect-error [FEI-5003] - TS2564 - Property '_observer' has no initializer and is not definitely assigned in the constructor.
+    _observer: IVisibilityObserver;
+    // @ts-expect-error [FEI-5003] - TS2564 - Property '_node' has no initializer and is not definitely assigned in the constructor.
+    _node: HTMLElement;
+
+    static defaultProps: {onChange: () => void} = {
+        onChange: () => {},
+    };
+
+    componentDidMount() {
+        this._node = ReactDOM.findDOMNode(this) as unknown as 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.ReactNode {
+        return this.props.children;
+    }
+}
+
+export default VisibilityObserver;

package/src/components/zoomable-tex.tsx

@@ -0,0 +1,78 @@
+/**
+ * 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";
+
+import TeX from "./tex";
+import Zoomable from "./zoomable";
+
+type Props = {
+    children: string;
+};
+type State = {
+    isRendered: boolean;
+};
+
+const computeMathBounds = (
+    parentNode: HTMLElement,
+    parentBounds: {width: number; height: number},
+) => {
+    const textElement =
+        parentNode.querySelector(".katex-html") ||
+        parentNode.querySelector(".MathJax");
+    const textBounds = {
+        // $FlowFixMe[incompatible-use]
+        // @ts-expect-error [FEI-5003] - TS2531 - Object is possibly 'null'. | TS2339 - Property 'offsetWidth' does not exist on type 'Element'.
+        width: textElement.offsetWidth,
+        // $FlowFixMe[incompatible-use]
+        // @ts-expect-error [FEI-5003] - TS2531 - Object is possibly 'null'. | TS2339 - Property 'offsetHeight' does not exist on type 'Element'.
+        height: textElement.offsetHeight,
+    } as const;
+
+    // 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() {
+        // @ts-expect-error [FEI-5003] - TS2554 - Expected 1-2 arguments, but got 0.
+        super();
+
+        this.state = {isRendered: false};
+    }
+
+    handleRender: () => void = () => {
+        this.setState({isRendered: true});
+    };
+
+    render(): React.ReactNode {
+        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.tsx

@@ -0,0 +1,300 @@
+/**
+ * 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.ReactNode;
+    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 | null | undefined;
+    expandedHeight?: number | null | undefined;
+    scale?: number | null | undefined;
+    zoomed: boolean;
+};
+
+class Zoomable extends React.Component<Props, State> {
+    // @ts-expect-error [FEI-5003] - TS2564 - Property '_isMounted' has no initializer and is not definitely assigned in the constructor.
+    _isMounted: boolean;
+    // @ts-expect-error [FEI-5003] - TS2564 - Property '_observer' has no initializer and is not definitely assigned in the constructor.
+    _observer: MutationObserver;
+    // @ts-expect-error [FEI-5003] - TS2564 - Property '_measuringInitialized' has no initializer and is not definitely assigned in the constructor.
+    _measuringInitialized: boolean;
+    _originalWidth: number | null | undefined;
+    // @ts-expect-error [FEI-5003] - TS2564 - Property '_node' has no initializer and is not definitely assigned in the constructor.
+    _node: HTMLElement;
+
+    static defaultProps: DefaultProps = {
+        animateHeight: false,
+        readyToMeasure: true,
+        computeChildBounds: (parentNode) => {
+            const firstChild = parentNode.firstElementChild;
+
+            return {
+                // $FlowFixMe[incompatible-use]
+                // $FlowFixMe[prop-missing]
+                // @ts-expect-error [FEI-5003] - TS2531 - Object is possibly 'null'. | TS2339 - Property 'offsetWidth' does not exist on type 'Element'.
+                width: firstChild.offsetWidth,
+                // $FlowFixMe[incompatible-use]
+                // $FlowFixMe[prop-missing]
+                // @ts-expect-error [FEI-5003] - TS2531 - Object is possibly 'null'. | TS2339 - Property 'offsetHeight' does not exist on type 'Element'.
+                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;
+            // @ts-expect-error [FEI-5003] - TS2322 - Type 'Element | Text | null' is not assignable to type 'HTMLElement'.
+            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: Array<MutationRecord>) => {
+                        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: React.TouchEvent) => void = (
+        e: React.TouchEvent,
+    ) => {
+        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,
+        } as const;
+        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: React.MouseEvent) => void = (
+        e: React.MouseEvent,
+    ) => {
+        if (!this.state.zoomed) {
+            e.stopPropagation();
+            this.handleClick();
+        }
+    };
+
+    handleClick: () => void = () => {
+        this.setState({
+            zoomed: !this.state.zoomed,
+        });
+    };
+
+    render(): React.ReactNode {
+        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,
+                  transitionDuration: "0.3s",
+                  transitionTimingFunction: "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,
+            transformOrigin: "0 0",
+            opacity: visible ? 1 : 0,
+            WebkitTapHighlightColor: "transparent",
+            ...transitionStyle,
+        } as const;
+
+        return (
+            <span
+                onClick={this.handleClick}
+                onClickCapture={this.handleClickIfZoomed}
+                onTouchCancelCapture={this.stopPropagationIfZoomed}
+                onTouchEndCapture={this.stopPropagationIfZoomed}
+                onTouchStartCapture={this.stopPropagationIfZoomed}
+                // @ts-expect-error [FEI-5003] - TS2322 - Type '{ readonly transitionProperty: string; readonly transitionDuration: string; readonly transitionTimingFunction: string; readonly display: "block"; readonly width: "100%"; readonly height: number | ... 1 more ... | undefined; readonly transform: string; readonly transformOrigin: "0 0"; readonly opacity: 0 | 1; readonl...' is not assignable to type 'CSSProperties | undefined'.
+                style={style}
+            >
+                {this.props.children}
+            </span>
+        );
+    }
+}
+
+export default Zoomable;

package/src/components.ts

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

package/src/definition-context.tsx

@@ -0,0 +1,60 @@
+/**
+ * A React context for ensuring there is one and only one definition showing at a time
+ */
+
+import * as React from "react";
+
+type DefintionContext = {
+    activeDefinitionId: string | null | undefined;
+    setActiveDefinitionId: (arg1?: string | null | undefined) => void;
+};
+
+const defaultContext: DefintionContext = {
+    activeDefinitionId: null,
+    setActiveDefinitionId: () => {},
+};
+
+const DefinitionContext: React.Context<DefintionContext> =
+    React.createContext(defaultContext);
+
+type ProviderState = {
+    activeDefinitionId: string | null | undefined;
+};
+
+export type ProviderProps = {
+    children: any;
+};
+export class DefinitionProvider extends React.Component<
+    ProviderProps,
+    ProviderState
+> {
+    // Context state
+    state: ProviderState = {
+        activeDefinitionId: null,
+    };
+
+    // Method to update state
+    // $FlowFixMe[signature-verification-failure]
+    setActiveDefinitionId = (activeDefinitionId?: string | null): void => {
+        this.setState((prevState: ProviderState) => ({activeDefinitionId}));
+    };
+
+    render(): React.ReactNode {
+        const {children} = this.props;
+        const {activeDefinitionId} = this.state;
+        const {setActiveDefinitionId} = this;
+
+        return (
+            <DefinitionContext.Provider
+                value={{
+                    activeDefinitionId,
+                    setActiveDefinitionId,
+                }}
+            >
+                {children}
+            </DefinitionContext.Provider>
+        );
+    }
+}
+
+export const DefinitionConsumer = DefinitionContext.Consumer;

package/src/dependencies.ts

@@ -0,0 +1,21 @@
+import type {PerseusDependencies} from "./types";
+
+let _dependencies: PerseusDependencies | null | undefined = 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.tsx

@@ -0,0 +1,50 @@
+import * as React from "react";
+
+import {Errors, Log} from "./logging/log";
+
+type ErrorBoundaryProps = {
+    children: React.ReactNode;
+};
+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.ReactNode {
+        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;