@khanacademy/perseus 3.0.0 → 4.0.0

package/src/util/katex-preprocess.ts

@@ -0,0 +1,14 @@
+/**
+ * Preprocess TeX code to convert things that KaTeX doesn't know how to handle
+ * to things is does.
+ */
+
+export default (texCode: string): string =>
+    texCode
+        // Replace uses of \begin{align}...\end{align} which KaTeX doesn't
+        // support (yet) with \begin{aligned}...\end{aligned} which renders
+        // the same is supported by KaTeX.  It does the same for align*.
+        // TODO(kevinb) update content to use aligned instead of align.
+        .replace(/\{align[*]?\}/g, "{aligned}")
+        // Replace non-breaking spaces with regular spaces.
+        .replace(/[\u00a0]/g, " ");

package/src/util/math.ts

@@ -0,0 +1,289 @@
+import {number as knumber} from "@khanacademy/kmath";
+import $ from "jquery";
+import _ from "underscore";
+
+import type {MathFormat} from "../perseus-types";
+
+const KhanMath = {
+    // Simplify formulas before display
+    cleanMath: function (expr: string): string {
+        return typeof expr === "string"
+            ? expr
+                  .replace(/\+\s*-/g, "- ")
+                  .replace(/-\s*-/g, "+ ")
+                  .replace(/\^1/g, "")
+            : expr;
+    },
+
+    // Bound a number by 1e-6 and 1e20 to avoid exponents after toString
+    bound: function (num: number): number {
+        if (num === 0) {
+            return num;
+        }
+        if (num < 0) {
+            return -KhanMath.bound(-num);
+        }
+        return Math.max(1e-6, Math.min(num, 1e20));
+    },
+
+    factorial: function (x: number): number {
+        if (x <= 1) {
+            return x;
+        }
+        return x * KhanMath.factorial(x - 1);
+    },
+
+    getGCD: function (a: number, b: number): number {
+        if (arguments.length > 2) {
+            // TODO(kevinb): rewrite using rest args instead of arguments
+            // eslint-disable-next-line prefer-rest-params
+            const rest = [].slice.call(arguments, 1);
+            // @ts-expect-error [FEI-5003] - TS2556 - A spread argument must either have a tuple type or be passed to a rest parameter.
+            return KhanMath.getGCD(a, KhanMath.getGCD(...rest));
+        }
+        let mod;
+
+        a = Math.abs(a);
+        b = Math.abs(b);
+
+        while (b) {
+            mod = a % b;
+            a = b;
+            b = mod;
+        }
+
+        return a;
+    },
+
+    getLCM: function (a: number, b: number): number {
+        if (arguments.length > 2) {
+            // TODO(kevinb): rewrite using rest args instead of arguments
+            // eslint-disable-next-line prefer-rest-params
+            const rest = [].slice.call(arguments, 1);
+            // @ts-expect-error [FEI-5003] - TS2556 - A spread argument must either have a tuple type or be passed to a rest parameter.
+            return KhanMath.getLCM(a, KhanMath.getLCM(...rest));
+        }
+        return Math.abs(a * b) / KhanMath.getGCD(a, b);
+    },
+
+    primes: [
+        2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67,
+        71, 73, 79, 83, 89, 97,
+    ],
+
+    isPrime: function (n: number): boolean {
+        if (n <= 1) {
+            return false;
+        }
+        if (n < 101) {
+            return !!$.grep(KhanMath.primes, function (p, i) {
+                return Math.abs(p - n) <= 0.5;
+            }).length;
+        }
+        if (n <= 1 || (n > 2 && n % 2 === 0)) {
+            return false;
+        }
+        for (let i = 3, sqrt = Math.sqrt(n); i <= sqrt; i += 2) {
+            if (n % i === 0) {
+                return false;
+            }
+        }
+
+        return true;
+    },
+
+    // $FlowFixMe[incompatible-return]
+    // @ts-expect-error [FEI-5003] - TS2366 - Function lacks ending return statement and return type does not include 'undefined'.
+    getPrimeFactorization: function (number: number): ReadonlyArray<number> {
+        if (number === 1) {
+            return [];
+        }
+        if (KhanMath.isPrime(number)) {
+            return [number];
+        }
+
+        const maxf = Math.sqrt(number);
+        for (let f = 2; f <= maxf; f++) {
+            if (number % f === 0) {
+                return $.merge(
+                    KhanMath.getPrimeFactorization(f),
+                    KhanMath.getPrimeFactorization(number / f),
+                );
+            }
+        }
+    },
+
+    // Round a number to the nearest increment
+    // E.g., if increment = 30 and num = 40, return 30. if increment = 30 and
+    //     num = 45, return 60.
+    roundToNearest: function (increment: number, num: number): number {
+        return Math.round(num / increment) * increment;
+    },
+
+    // Round a number to a certain number of decimal places
+    roundTo: function (precision: number, num: number): number {
+        const factor = Math.pow(10, precision).toFixed(5);
+        // @ts-expect-error [FEI-5003] - TS2345 - Argument of type 'string' is not assignable to parameter of type 'number'. | TS2363 - The right-hand side of an arithmetic operation must be of type 'any', 'number', 'bigint' or an enum type. | TS2363 - The right-hand side of an arithmetic operation must be of type 'any', 'number', 'bigint' or an enum type.
+        return Math.round((num * factor).toFixed(5)) / factor;
+    },
+
+    /**
+     * Return a string of num rounded to a fixed precision decimal places,
+     * with an approx symbol if num had to be rounded, and trailing 0s
+     */
+    toFixedApprox: function (num: number, precision: number): string {
+        // TODO(aria): Make this locale-dependent like KhanUtil.localeToFixed
+        const fixedStr = num.toFixed(precision);
+        if (knumber.equal(+fixedStr, num)) {
+            return fixedStr;
+        }
+        return "\\approx " + fixedStr;
+    },
+
+    /**
+     * Return a string of num rounded to precision decimal places, with an
+     * approx symbol if num had to be rounded, but no trailing 0s if it was
+     * not rounded.
+     */
+    roundToApprox: function (num: number, precision: number): string {
+        const fixed = KhanMath.roundTo(precision, num);
+        if (knumber.equal(fixed, num)) {
+            return String(fixed);
+        }
+        return KhanMath.toFixedApprox(num, precision);
+    },
+
+    // toFraction(4/8) => [1, 2]
+    // toFraction(0.666) => [333, 500]
+    // toFraction(0.666, 0.001) => [2, 3]
+    //
+    // tolerance can't be bigger than 1, sorry
+    toFraction: function (
+        decimal: number,
+        // $FlowFixMe[incompatible-return]
+        tolerance?: number,
+    ): [number, number] {
+        if (tolerance == null) {
+            tolerance = Math.pow(2, -46);
+        }
+
+        if (decimal < 0 || decimal > 1) {
+            let fract = decimal % 1;
+            fract += fract < 0 ? 1 : 0;
+
+            const nd = KhanMath.toFraction(fract, tolerance);
+            nd[0] += Math.round(decimal - fract) * nd[1];
+            return nd;
+        }
+        if (Math.abs(Math.round(Number(decimal)) - decimal) <= tolerance) {
+            return [Math.round(decimal), 1];
+        }
+        let loN = 0;
+        let loD = 1;
+        let hiN = 1;
+        let hiD = 1;
+        let midN = 1;
+        let midD = 2;
+
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            if (Math.abs(Number(midN / midD) - decimal) <= tolerance) {
+                return [midN, midD];
+            }
+            if (midN / midD < decimal) {
+                loN = midN;
+                loD = midD;
+            } else {
+                hiN = midN;
+                hiD = midD;
+            }
+
+            midN = loN + hiN;
+            midD = loD + hiD;
+        }
+    },
+
+    // Returns the format (string) of a given numeric string
+    // Note: purposively more inclusive than answer-types' predicate.forms
+    // That is, it is not necessarily true that interpreted input are numeric
+    getNumericFormat: function (text: string): MathFormat | null | undefined {
+        text = $.trim(text);
+        text = text.replace(/\u2212/, "-").replace(/([+-])\s+/g, "$1");
+        if (text.match(/^[+-]?\d+$/)) {
+            return "integer";
+        }
+        if (text.match(/^[+-]?\d+\s+\d+\s*\/\s*\d+$/)) {
+            return "mixed";
+        }
+        const fraction = text.match(/^[+-]?(\d+)\s*\/\s*(\d+)$/);
+        if (fraction) {
+            return parseFloat(fraction[1]) > parseFloat(fraction[2])
+                ? "improper"
+                : "proper";
+        }
+        if (text.replace(/[,. ]/g, "").match(/^\d+$/)) {
+            return "decimal";
+        }
+        if (text.match(/(pi?|\u03c0|t(?:au)?|\u03c4|pau)/)) {
+            return "pi";
+        }
+        return null;
+    },
+
+    // Returns a string of the number in a specified format
+    toNumericString: function (number: number, format?: MathFormat): string {
+        if (number == null) {
+            return "";
+        }
+        if (number === 0) {
+            return "0"; // otherwise it might end up as 0% or 0pi
+        }
+
+        if (format === "percent") {
+            return number * 100 + "%";
+        }
+
+        if (format === "pi") {
+            const fraction = knumber.toFraction(number / Math.PI);
+            const numerator = Math.abs(fraction[0]);
+            const denominator = fraction[1];
+            if (knumber.isInteger(numerator)) {
+                const sign = number < 0 ? "-" : "";
+                const pi = "\u03C0";
+                return (
+                    sign +
+                    (numerator === 1 ? "" : numerator) +
+                    pi +
+                    (denominator === 1 ? "" : "/" + denominator)
+                );
+            }
+        }
+
+        if (_(["proper", "improper", "mixed", "fraction"]).contains(format)) {
+            const fraction = knumber.toFraction(number);
+            const numerator = Math.abs(fraction[0]);
+            const denominator = fraction[1];
+            const sign = number < 0 ? "-" : "";
+            if (denominator === 1) {
+                return sign + numerator; // for integers, irrational, d > 1000
+            }
+            if (format === "mixed") {
+                const modulus = numerator % denominator;
+                const integer = (numerator - modulus) / denominator;
+                return (
+                    sign +
+                    (integer ? integer + " " : "") +
+                    modulus +
+                    "/" +
+                    denominator
+                );
+            } // otherwise proper, improper, or fraction
+            return sign + numerator + "/" + denominator;
+        }
+
+        // otherwise (decimal, float, long long)
+        return String(number);
+    },
+} as const;
+
+export default KhanMath;

package/src/util/mobile-native-utils.test.ts

@@ -0,0 +1,22 @@
+import {isFileProtocol} from "./mobile-native-utils";
+
+describe("isFileProtocol", () => {
+    it("If protocol is falsy, returns false", () => {
+        expect(isFileProtocol(undefined)).toEqual(false);
+        expect(isFileProtocol(null)).toEqual(false);
+        expect(isFileProtocol("")).toEqual(false);
+    });
+
+    it("If protocol is file, returns true", () => {
+        expect(isFileProtocol("file:")).toEqual(true);
+        expect(isFileProtocol("File:")).toEqual(true);
+        expect(isFileProtocol("FILE:")).toEqual(true);
+    });
+
+    it("If protocol is not file, returns false", () => {
+        expect(isFileProtocol("ftp:")).toEqual(false);
+        expect(isFileProtocol("http:")).toEqual(false);
+        expect(isFileProtocol("https:")).toEqual(false);
+        expect(isFileProtocol("mailto:")).toEqual(false);
+    });
+});

package/src/util/mobile-native-utils.ts

@@ -0,0 +1,12 @@
+/**
+ * Helps us detect that we are running in a mobile native environment for
+ * any js that is bundled in the mobile app (e.g. Perseus).
+ *
+ * @param {*} protocol protocol portion of a URL. Generally: window.location.protocol
+ */
+export const isFileProtocol = (protocol?: string | null): boolean => {
+    if (protocol && protocol.toLowerCase() === "file:") {
+        return true;
+    }
+    return false;
+};

package/src/util/react-render.tsx

@@ -0,0 +1,27 @@
+import {RenderStateRoot} from "@khanacademy/wonder-blocks-core";
+import * as React from "react";
+import ReactDOM from "react-dom";
+
+export default function render<ElementType extends React.ElementType>(
+    element: React.ReactNode,
+    container: HTMLElement,
+    callback?: () => void,
+): React.ElementRef<ElementType> {
+    // TODO(LP-11406): Replace this, or callers, with React Portal
+    // @ts-expect-error [FEI-5003] - TS2322 - Type 'void' is not assignable to type 'ElementRef<ElementType>'.
+    // eslint-disable-next-line no-restricted-syntax
+    return ReactDOM.render(
+        /**
+         * `RenderStateRoot` is responsible for tracking whether it's
+         * the initial render or subsequent renders.  It's used by
+         * `useUniqueId` and will be used by `UniqueIDProvider` and
+         * `WithSSRPlaceholder` in the future.  We're placing it as
+         * high up in the render tree as possible to ensure that any
+         * components using that hook or those components will function
+         * correctly.
+         */
+        <RenderStateRoot throwIfNested={false}>{element}</RenderStateRoot>,
+        container,
+        callback,
+    );
+}

package/src/util/register-all-widgets-for-testing.ts

@@ -0,0 +1,11 @@
+/**
+ * Some tests require some or all of the widgets and editors to be registered
+ * in order for them to work. Requiring this file will register all of the
+ * widgets and editors.
+ */
+import allWidgets from "../all-widgets";
+import * as Widgets from "../widgets";
+
+export const registerAllWidgetsForTesting = () => {
+    Widgets.registerWidgets(allWidgets);
+};

package/src/util/scroll-utils.ts

@@ -0,0 +1,155 @@
+/**
+ * A small collection of useful scrolling utility functions.
+ */
+
+// Polyfill scrollTo if it doesn't exist
+if (typeof HTMLElement !== "undefined" && !HTMLElement.prototype.scrollTo) {
+    // @ts-expect-error [FEI-5003] - TS2322 - Type '(left: number, top: any) => void' is not assignable to type '{ (options?: ScrollToOptions | undefined): void; (x: number, y: number): void; }'.
+    HTMLElement.prototype.scrollTo = function (left, top: any) {
+        this.scrollLeft = left;
+        this.scrollTop = top;
+    };
+}
+
+/**
+ * Handles applying a given scroll object to either the window object,
+ * or an HTML element.
+ * NOTE: SIDE EFFECTS. This method touches the DOM.
+ */
+const applyUniversalScrollOffset = (
+    elementOrWindow: HTMLElement | WindowProxy,
+    amount: number,
+) => {
+    // Window objects need to be scrolled by using the `.scrollTo()` function.
+    // Elements in MODERN browsers also have this method, but a safer x-browser
+    // solution is to use the `.scrollTop` property setter.
+    if (typeof elementOrWindow.scrollTo === "function") {
+        elementOrWindow.scrollTo(0, amount);
+    } else if ("scrollTop" in elementOrWindow) {
+        elementOrWindow.scrollTop = amount;
+    }
+};
+
+/**
+ * Smoothly scroll the given element to the given offset.
+ *
+ * This assumes that element.scrollHeight > element.clientHeight.
+ */
+const scrollElementToOffset = (
+    elementOrWindow: HTMLElement | WindowProxy,
+    offset: number,
+    duration = 0,
+    callback?: any,
+) => {
+    const startPosition =
+        elementOrWindow === window
+            ? window.pageYOffset
+            : // @ts-expect-error [FEI-5003] - TS2551 - Property 'scrollTop' does not exist on type 'HTMLElement | Window'. Did you mean 'scrollTo'?
+              elementOrWindow.scrollTop;
+    const endPosition = offset;
+    const scrollDistance = endPosition - startPosition;
+
+    // Aim for ~60 FPS
+    const tickLength = 17;
+    const numberOfSteps = duration / tickLength;
+    let step = 0;
+
+    // TODO (josh): Rewrite this using window.requestAnimationFrame
+    // TODO(jeff, WEB-1378): Use Wonder Blocks Timing API
+    // eslint-disable-next-line no-restricted-syntax
+    const scrollInterval = setInterval(function () {
+        if (step < numberOfSteps) {
+            const x = step / numberOfSteps; // Domain: [0, 1]
+            const y = (-Math.cos(Math.PI * x) + 1) / 2; // Range: [0, 1]
+
+            const newPosition = startPosition + scrollDistance * y;
+            applyUniversalScrollOffset(elementOrWindow, newPosition);
+
+            step += 1;
+        } else {
+            // Account for non-integer numberOfSteps
+            applyUniversalScrollOffset(elementOrWindow, endPosition);
+
+            // TODO(jeff, WEB-1378): Use Wonder Blocks Timing API
+            // eslint-disable-next-line no-restricted-syntax
+            clearInterval(scrollInterval);
+            callback && callback();
+        }
+    }, tickLength);
+};
+
+/**
+ * Returns the closest ancestor that is scrollable.
+ *
+ * If the container is document.body we return window b/c scrollTo() doesn't
+ * work on document.body in some browsers.
+ */
+const getScrollContainer = (element?: Element | null): any | Element => {
+    if (element === document.body) {
+        return window;
+    }
+    if (element == null) {
+        return window;
+    }
+    if (element.scrollHeight > element.clientHeight) {
+        return element;
+    }
+    return getScrollContainer(element.parentElement);
+};
+
+const SCROLL_ANIMATION_DURATION = 750; // ms
+
+/**
+ * Scroll the given element into view.
+ *
+ * This works with elements inside scroll containers, but may fail in scenarios
+ * involving multiple nested scroll containers.
+ */
+export const scrollElementIntoView = (element: Element, callback?: any) => {
+    // Often times we scroll an element into with in reaction to some change in
+    // the DOM.  Since we need to measure things, we wait a tick for the DOM to
+    // settle before computing the distance to scroll and beginning the scroll
+    // animation.
+    // TODO(jeff, WEB-1378): Use Wonder Blocks Timing API
+    // eslint-disable-next-line no-restricted-syntax
+    setTimeout(() => {
+        const scrollContainer = getScrollContainer(element);
+
+        const childBounds = element.getBoundingClientRect();
+        const containerBounds =
+            scrollContainer === window
+                ? {
+                      top: 0,
+                      bottom: window.innerHeight,
+                  }
+                : scrollContainer.getBoundingClientRect();
+
+        let offset = 0;
+        const currentScrollTop =
+            scrollContainer === window
+                ? window.scrollY
+                : scrollContainer.scrollTop;
+
+        if (childBounds.bottom > containerBounds.bottom) {
+            let distanceToScroll = childBounds.bottom - containerBounds.bottom;
+
+            // Ensure that we see the top of the component we're scrolling.
+            if (childBounds.top + distanceToScroll < containerBounds.top) {
+                distanceToScroll = childBounds.top - containerBounds.top;
+            }
+
+            offset = currentScrollTop + distanceToScroll;
+        } else if (childBounds.top < containerBounds.top) {
+            const distanceToScroll = childBounds.top - containerBounds.top;
+
+            offset = currentScrollTop + distanceToScroll;
+        }
+
+        scrollElementToOffset(
+            scrollContainer,
+            offset,
+            SCROLL_ANIMATION_DURATION,
+            callback,
+        );
+    }, 0);
+};

package/src/util/sizing-utils.ts

@@ -0,0 +1,46 @@
+import * as constants from "../styles/constants";
+
+const {interactiveSizes} = constants;
+
+// Note: these size cutoffs represent content-width cutoffs as specified in
+// http://zpl.io/1mVmvU (broken link - we no longer use Zeplin)
+// TODO(benkomalo): these values aren't used in JS outside of this file, but
+// are coupled to the values in styles/articles.less - DRY it up at some point
+const smMax = constants.articleMaxWidthTableInPx;
+const mdMax = constants.articleMaxWidthInPx;
+
+export const containerSizeClass = {
+    SMALL: "small" as const,
+    MEDIUM: "medium" as const,
+    LARGE: "large" as const,
+    XLARGE: "xlarge" as const,
+} as const;
+
+export type SizeClass =
+    typeof containerSizeClass[keyof typeof containerSizeClass];
+
+export const getClassFromWidth = (width: number): SizeClass => {
+    if (!width) {
+        return containerSizeClass.MEDIUM;
+    }
+
+    if (width <= smMax) {
+        return containerSizeClass.SMALL;
+    }
+    if (width <= mdMax) {
+        return containerSizeClass.MEDIUM;
+    }
+    return containerSizeClass.LARGE;
+};
+
+export const getInteractiveBoxFromSizeClass = (
+    sizeClass: SizeClass,
+): [number, number] => {
+    if (sizeClass === containerSizeClass.SMALL) {
+        return [
+            interactiveSizes.defaultBoxSizeSmall,
+            interactiveSizes.defaultBoxSizeSmall,
+        ];
+    }
+    return [interactiveSizes.defaultBoxSize, interactiveSizes.defaultBoxSize];
+};