@khanacademy/perseus 2.1.0 → 4.0.0

package/src/__tests__/tex-wrangler.test.ts

@@ -0,0 +1,82 @@
+import TexWrangler from "../tex-wrangler";
+
+const {parseTex, modifyTex} = TexWrangler;
+
+const whitespaceRegex = /\s/g;
+
+const assertWrangled = (toWrangle: string, check: string) => {
+    // We ignore whitespace when comparing
+    const wrangled = modifyTex(toWrangle).replace(whitespaceRegex, "");
+    const checkNoSpace = check.replace(whitespaceRegex, "");
+    expect(wrangled).toBe(checkNoSpace);
+};
+
+const assertParsed = (toParse: undefined | string, check: string) => {
+    // We ignore whitespace when comparing
+    // @ts-expect-error [FEI-5003] - TS2345 - Argument of type 'string | undefined' is not assignable to parameter of type 'string'.
+    const parsed = parseTex(toParse).replace(whitespaceRegex, "");
+    const checkNoSpace = check.replace(whitespaceRegex, "");
+    expect(parsed).toBe(checkNoSpace);
+};
+
+describe("modifyTex", () => {
+    it("should not touch single fractions", () => {
+        assertWrangled("\\frac{3}{4}", "\\frac{3}{4}");
+    });
+
+    it("should make big single fractions small", () => {
+        assertWrangled("\\dfrac{3}{4}", "\\frac{3}{4}");
+    });
+
+    it("should make outer fractions big", () => {
+        assertWrangled("\\frac{1}{\\frac{2}{3}}", "\\dfrac{1}{\\frac{2}{3}}");
+        assertWrangled("\\frac{\\frac{1}{2}}{3}", "\\dfrac{\\frac{1}{2}}{3}");
+    });
+
+    it("should make inner fractions small", () => {
+        assertWrangled("\\dfrac{1}{\\dfrac{2}{3}}", "\\dfrac{1}{\\frac{2}{3}}");
+        assertWrangled("\\dfrac{\\dfrac{1}{2}}{3}", "\\dfrac{\\frac{1}{2}}{3}");
+    });
+
+    it("should parse mutliple fractions", () => {
+        assertWrangled(
+            "\\dfrac{1}{2} + \\dfrac{3}{4}",
+            "\\frac{1}{2} + \\frac{3}{4}",
+        );
+    });
+
+    it("shouldn't touch things before fractions", () => {
+        assertWrangled("1 + \\dfrac{2}{3}", "1 + \\frac{2}{3}");
+    });
+
+    it("shouldn't touch things after fractions", () => {
+        assertWrangled("\\dfrac{1}{2} + 3", "\\frac{1}{2} + 3");
+    });
+
+    it("shouldn't touch things that wrap fractions", () => {
+        assertWrangled("\\sqrt{\\dfrac{1}{2}}", "\\sqrt{\\frac{1}{2}}");
+    });
+
+    it("should have sane failure modes", () => {
+        assertWrangled("\\dfrac{3}{4", "\\frac{3}{4}");
+        // This could maybe be better, but if someone gives us this and it
+        // doesn't work then that's their fault. :)
+        assertWrangled("\\dfrac{3}{4}}", "\\frac{3}{4}}");
+    });
+});
+
+describe("parseTex", () => {
+    it("should replace single fractions", () => {
+        assertParsed("\\dfrac{3}{4}", "3 / 4");
+    });
+
+    it("should remove blackslash-escapes for percent signs", () => {
+        assertParsed("3\\%", "3%");
+        assertParsed("3.5\\%", "3.5%");
+        assertParsed("\\dfrac{3\\%}{4}", "3% / 4");
+    });
+
+    it("should not throw error when input is undefined", () => {
+        assertParsed(undefined, "");
+    });
+});

package/src/__tests__/util.test.ts

@@ -0,0 +1,40 @@
+import Util from "../util";
+
+describe("#constrainedTickStepsFromTickSteps", () => {
+    it("should not changes the tick steps if there are fewer than (or exactly) 10 steps", () => {
+        const result = Util.constrainedTickStepsFromTickSteps(
+            [1, 1],
+            [
+                [0, 10],
+                [0, 10],
+            ],
+        );
+
+        expect(result).toEqual([1, 1]);
+    });
+
+    it("should should double the tick step size if there are more than 10 but fewer than (or exactly) 20 steps", () => {
+        const result = Util.constrainedTickStepsFromTickSteps(
+            [1, 1],
+            [
+                [0, 20],
+                [0, 20],
+            ],
+        );
+
+        expect(result).toEqual([2, 2]);
+    });
+
+    it("should use the value returned by tickStepFromNumTicks", () => {
+        jest.spyOn(Util, "tickStepFromNumTicks").mockReturnValue(5);
+        const result = Util.constrainedTickStepsFromTickSteps(
+            [1, 1],
+            [
+                [0, 50],
+                [0, 50],
+            ],
+        );
+
+        expect(result).toEqual([5, 5]);
+    });
+});

package/src/a11y.ts

@@ -0,0 +1,45 @@
+/**
+ * Identifies whether or not a given perseus item requires the use of a mouse
+ * or screen, based on the widgets it contains.
+ */
+
+import _ from "underscore";
+
+import MultiItems from "./multi-items";
+import {traverse} from "./traversal";
+import * as Widgets from "./widgets";
+
+const {findContentNodesInItem, inferItemShape} = MultiItems;
+
+// Iterate over a single Perseus renderer, mutating `widgets` by appending
+// violating widget types discovered in this item.
+function traverseRenderer(itemData, widgets: Array<any>) {
+    traverse(itemData, null, function (info) {
+        if (info.type && !Widgets.isAccessible(info)) {
+            widgets.push(info.type);
+        }
+    });
+}
+
+// Returns a list of widgets that cause a given perseus item to require
+// the use of a screen or mouse.
+//
+// For now we'll just check the `accessible` field on each of the widgets
+// in the item data, but in the future we may specify accessibility on
+// each widget with higher granularity.
+export function violatingWidgets(itemData: any): any {
+    // TODO(jordan): Hints as well
+    const widgets = [];
+
+    if (itemData._multi) {
+        const shape = inferItemShape(itemData);
+        findContentNodesInItem(itemData, shape, (content) =>
+            traverseRenderer(content, widgets),
+        );
+    } else {
+        traverseRenderer(itemData.question, widgets);
+    }
+
+    // Uniquify the list of widgets (by type)
+    return _.uniq(widgets);
+}

package/src/all-widgets.ts

@@ -0,0 +1,9 @@
+import basicWidgets from "./basic-widgets";
+import extraWidgets from "./extra-widgets";
+
+import type {WidgetExports} from "./types";
+
+export default [
+    ...basicWidgets,
+    ...extraWidgets,
+] as ReadonlyArray<WidgetExports>;

package/src/article-renderer.tsx

@@ -0,0 +1,215 @@
+/**
+ * An article renderer. Articles are long-form pieces of content,
+ * composed of multiple (Renderer) sections concatenated together.
+ */
+
+import * as PerseusLinter from "@khanacademy/perseus-linter";
+import classNames from "classnames";
+import PropTypes from "prop-types";
+import * as React from "react";
+
+import ProvideKeypad from "./mixins/provide-keypad";
+import {ClassNames as ApiClassNames, ApiOptions} from "./perseus-api";
+import Renderer from "./renderer";
+import Util from "./util";
+
+const rendererProps = PropTypes.shape({
+    content: PropTypes.string,
+    widgets: PropTypes.objectOf(PropTypes.any),
+    images: PropTypes.objectOf(PropTypes.any),
+});
+
+class ArticleRenderer extends React.Component<any, any> {
+    _currentFocus: any;
+
+    static propTypes = {
+        ...ProvideKeypad.propTypes,
+        apiOptions: PropTypes.shape({
+            onFocusChange: PropTypes.func,
+            isMobile: PropTypes.bool,
+        }),
+        json: PropTypes.oneOfType([
+            rendererProps,
+            PropTypes.arrayOf(rendererProps),
+        ]).isRequired,
+
+        // Whether to use the new Bibliotron styles for articles
+        useNewStyles: PropTypes.bool,
+        linterContext: PerseusLinter.linterContextProps,
+        legacyPerseusLint: PropTypes.arrayOf(PropTypes.string),
+    };
+
+    static defaultProps: any = {
+        apiOptions: {},
+        useNewStyles: false,
+        linterContext: PerseusLinter.linterContextDefault,
+    };
+
+    constructor(props: any) {
+        super(props);
+        this.state = ProvideKeypad.getInitialState.call(this);
+    }
+
+    componentDidMount() {
+        ProvideKeypad.componentDidMount.call(this);
+        this._currentFocus = null;
+    }
+
+    shouldComponentUpdate(nextProps: any, nextState: any): any {
+        return nextProps !== this.props || nextState !== this.state;
+    }
+
+    componentWillUnmount() {
+        ProvideKeypad.componentWillUnmount.call(this);
+    }
+
+    keypadElement: () => void = () => {
+        return ProvideKeypad.keypadElement.call(this);
+    };
+
+    _handleFocusChange: (arg1: any, arg2: any) => void = (
+        newFocusPath,
+        oldFocusPath,
+    ) => {
+        // TODO(charlie): DRY this up--some of this logic is repeated in
+        // ItemRenderer.
+        if (newFocusPath) {
+            this._setCurrentFocus(newFocusPath);
+        } else {
+            this._onRendererBlur(oldFocusPath);
+        }
+    };
+
+    _setCurrentFocus: (arg1: any) => void = (newFocusPath) => {
+        const keypadElement = this.keypadElement();
+
+        const prevFocusPath = this._currentFocus;
+        this._currentFocus = newFocusPath;
+
+        // Use the section prefix to extract the relevant Renderer's input
+        // paths, so as to check whether the focused path represents an
+        // input.
+        let didFocusInput = false;
+        if (this._currentFocus) {
+            const [sectionRef, ...focusPath] = this._currentFocus;
+            // eslint-disable-next-line react/no-string-refs
+            // @ts-expect-error [FEI-5003] - TS2339 - Property 'getInputPaths' does not exist on type 'ReactInstance'.
+            const inputPaths = this.refs[sectionRef].getInputPaths();
+            didFocusInput = inputPaths.some((inputPath) => {
+                return Util.inputPathsEqual(inputPath, focusPath);
+            });
+        }
+
+        if (this.props.apiOptions.onFocusChange != null) {
+            this.props.apiOptions.onFocusChange(
+                this._currentFocus,
+                prevFocusPath,
+                // @ts-expect-error [FEI-5003] - TS2339 - Property 'getDOMNode' does not exist on type 'never'.
+                didFocusInput && keypadElement && keypadElement.getDOMNode(),
+            );
+        }
+
+        // @ts-expect-error [FEI-5003] - TS1345 - An expression of type 'void' cannot be tested for truthiness.
+        if (keypadElement) {
+            if (didFocusInput) {
+                // @ts-expect-error [FEI-5003] - TS2339 - Property 'activate' does not exist on type 'never'.
+                keypadElement.activate();
+            } else {
+                // @ts-expect-error [FEI-5003] - TS2339 - Property 'dismiss' does not exist on type 'never'.
+                keypadElement.dismiss();
+            }
+        }
+    };
+
+    _onRendererBlur: (arg1: any) => void = (blurPath) => {
+        const blurringFocusPath = this._currentFocus;
+
+        // Failsafe: abort if ID is different, because focus probably happened
+        // before blur.
+        if (!Util.inputPathsEqual(blurPath, blurringFocusPath)) {
+            return;
+        }
+
+        // Wait until after any new focus events fire this tick before declaring
+        // that nothing is focused, since if there were a focus change across
+        // sections, we could receive the blur before the focus.
+        // TODO(jeff, CP-3128): Use Wonder Blocks Timing API
+        // eslint-disable-next-line no-restricted-syntax
+        setTimeout(() => {
+            if (Util.inputPathsEqual(this._currentFocus, blurringFocusPath)) {
+                this._setCurrentFocus(null);
+            }
+        });
+    };
+
+    blur: () => void = () => {
+        if (this._currentFocus) {
+            const [sectionRef, ...inputPath] = this._currentFocus;
+            // eslint-disable-next-line react/no-string-refs
+            // @ts-expect-error [FEI-5003] - TS2339 - Property 'blurPath' does not exist on type 'ReactInstance'.
+            this.refs[sectionRef].blurPath(inputPath);
+        }
+    };
+
+    _sections: () => any = () => {
+        return Array.isArray(this.props.json)
+            ? this.props.json
+            : [this.props.json];
+    };
+
+    render(): React.ReactNode {
+        const apiOptions = {
+            ...ApiOptions.defaults,
+            ...this.props.apiOptions,
+            isArticle: true,
+        } as const;
+
+        const classes = classNames({
+            "framework-perseus": true,
+            "perseus-article": true,
+            "bibliotron-article": this.props.useNewStyles,
+            // NOTE(charlie): For exercises, this is applied outside of Perseus
+            // (in webapp).
+            [ApiClassNames.MOBILE]: apiOptions.isMobile,
+        });
+
+        // TODO(alex): Add mobile api functions and pass them down here
+        const sections = this._sections().map((section, i) => {
+            const refForSection = `section-${i}`;
+            return (
+                <div key={i} className="clearfix">
+                    <Renderer
+                        {...section}
+                        ref={refForSection}
+                        key={i}
+                        key_={i}
+                        keypadElement={this.keypadElement()}
+                        apiOptions={{
+                            ...apiOptions,
+                            onFocusChange: (newFocusPath, oldFocusPath) => {
+                                // Prefix the paths with the relevant section,
+                                // so as to allow us to distinguish between
+                                // equivalently-named inputs across Renderers.
+                                this._handleFocusChange(
+                                    newFocusPath &&
+                                        [refForSection].concat(newFocusPath),
+                                    oldFocusPath &&
+                                        [refForSection].concat(oldFocusPath),
+                                );
+                            },
+                        }}
+                        linterContext={PerseusLinter.pushContextStack(
+                            this.props.linterContext,
+                            "article",
+                        )}
+                        legacyPerseusLint={this.props.legacyPerseusLint}
+                    />
+                </div>
+            );
+        });
+
+        return <div className={classes}>{sections}</div>;
+    }
+}
+
+export default ArticleRenderer;

package/src/asset-context.ts

@@ -0,0 +1,30 @@
+/**
+ * A React context for keeping track of whether an component is fully
+ * loaded.  This is used to know when SvgImage and (Zoomable)TeX are finished
+ * renderering.
+ */
+
+import * as React from "react";
+
+type Context = {
+    // A dictionary of asset statues.  See server-item-renderer.jsx for
+    // an example of its definition.
+    assetStatuses: {
+        [assetKey: string]: boolean;
+    };
+    // setAssetStatus(key, false) must be called in the constructor of
+    // any component which isn't fully rendered on initial render.  This
+    // adds the asset key to asssetStatuses, see server-item-renderer.jsx.
+    // setAssetStatus(key, true) must be called when the component has
+    // fully rendered itself.  See svg-image.jsx and tex.jsx.
+    setAssetStatus: (assetKey: string, loaded: boolean) => void;
+};
+
+const defaultContext: Context = {
+    assetStatuses: {},
+    setAssetStatus: (assetKey: string, loaded: boolean) => {},
+};
+
+const context: React.Context<Context> = React.createContext(defaultContext);
+
+export default context;

package/src/basic-widgets.ts

@@ -0,0 +1,16 @@
+/* eslint-disable import/no-named-as-default */
+// 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 Expression from "./widgets/expression";
+import InputNumber from "./widgets/input-number";
+import NumericInput from "./widgets/numeric-input";
+import Radio from "./widgets/radio";
+
+import type {WidgetExports} from "./types";
+
+export default [
+    Radio,
+    InputNumber,
+    NumericInput,
+    Expression,
+] as ReadonlyArray<WidgetExports>;

package/src/components/__stories__/button-group.stories.tsx

@@ -0,0 +1,59 @@
+import * as React from "react";
+
+import ButtonGroup from "../button-group";
+
+type StoryArgs = Record<any, any>;
+
+type Story = {
+    title: string;
+};
+
+export default {
+    title: "Perseus/Components/Button Group",
+} as Story;
+
+const HarnassedButtonGroup = (
+    props: Pick<React.ComponentProps<typeof ButtonGroup>, "buttons">,
+) => {
+    const [value, updateValue] = React.useState(
+        null as string | null | undefined,
+    );
+
+    return (
+        <ButtonGroup
+            buttons={props.buttons}
+            value={value}
+            onChange={(newValue) => {
+                updateValue(newValue);
+            }}
+        />
+    );
+};
+
+export const ButtonsWithNoTitles: React.FC<StoryArgs> = (
+    args,
+): React.ReactElement => {
+    return (
+        <HarnassedButtonGroup
+            buttons={[
+                {value: "One", content: "Item #1"},
+                {value: "Two", content: "Item #2"},
+                {value: "Three", content: "Item #3"},
+            ]}
+        />
+    );
+};
+
+export const ButtonsWithTitles: React.FC<StoryArgs> = (
+    args,
+): React.ReactElement => {
+    return (
+        <HarnassedButtonGroup
+            buttons={[
+                {value: "One", content: "Item #1", title: "The first item"},
+                {value: "Two", content: "Item #2", title: "The second item"},
+                {value: "Three", content: "Item #3", title: "The third item"},
+            ]}
+        />
+    );
+};

package/src/components/__stories__/fixed-to-responsive.stories.tsx

@@ -0,0 +1,143 @@
+import * as React from "react";
+
+import {getDependencies} from "../../dependencies";
+import FixedToResponsive from "../fixed-to-responsive";
+
+type StoryArgs = Record<any, any>;
+
+type Story = {
+    title: string;
+};
+
+const svgUrl = "https://www.khanacademy.org/images/ohnoes-concerned.svg";
+const imgUrl = "https://www.khanacademy.org/images/hand-tree.new.png";
+
+const sizeSmall = 200;
+const sizeMedium = 600;
+const sizeLarge = 1024;
+const width = 1024;
+
+export default {
+    title: "Perseus/Components/Fixed to Responsive",
+} as Story;
+
+export const SmallImageWithSmallContainer: React.FC<StoryArgs> = (
+    args,
+): React.ReactElement => {
+    return (
+        <FixedToResponsive width={width} height={sizeSmall}>
+            <img
+                alt=""
+                width={sizeSmall}
+                height={sizeSmall}
+                src={getDependencies().staticUrl(svgUrl)}
+            />
+        </FixedToResponsive>
+    );
+};
+
+export const SmallImageWithMediumContainer: React.FC<StoryArgs> = (
+    args,
+): React.ReactElement => {
+    return (
+        <FixedToResponsive width={width} height={sizeMedium}>
+            <img
+                alt=""
+                width={sizeMedium}
+                height={sizeMedium}
+                src={getDependencies().staticUrl(svgUrl)}
+            />
+        </FixedToResponsive>
+    );
+};
+
+export const LargeImageWithLargeContainer: React.FC<StoryArgs> = (
+    args,
+): React.ReactElement => {
+    return (
+        <FixedToResponsive width={width} height={sizeLarge}>
+            <img
+                alt=""
+                width={sizeLarge}
+                height={sizeLarge}
+                src={getDependencies().staticUrl(svgUrl)}
+            />
+        </FixedToResponsive>
+    );
+};
+
+export const LargeImageWithSmallerContainer: React.FC<StoryArgs> = (
+    args,
+): React.ReactElement => {
+    return (
+        <FixedToResponsive width={width} height={sizeSmall}>
+            <img
+                alt=""
+                width={sizeLarge}
+                height={sizeLarge}
+                src={getDependencies().staticUrl(svgUrl)}
+            />
+        </FixedToResponsive>
+    );
+};
+
+export const TwoOverlayedImagesInsteadOneResponsiveContainer: React.FC<
+    StoryArgs
+> = (args): React.ReactElement => {
+    return (
+        <FixedToResponsive width={width} height={sizeSmall}>
+            <img
+                alt=""
+                key={1}
+                width={sizeSmall}
+                height={sizeSmall}
+                src={imgUrl}
+            />
+            <img
+                alt=""
+                key={2}
+                width={sizeSmall}
+                height={sizeSmall}
+                src={getDependencies().staticUrl(svgUrl)}
+            />
+        </FixedToResponsive>
+    );
+};
+
+export const HeightConstrainingAnImage: React.FC<StoryArgs> = (
+    args,
+): React.ReactElement => {
+    return (
+        <FixedToResponsive
+            width={width}
+            height={sizeLarge}
+            constrainHeight={true}
+        >
+            <img
+                alt=""
+                width={sizeLarge}
+                height={sizeLarge}
+                src={getDependencies().staticUrl(svgUrl)}
+            />
+        </FixedToResponsive>
+    );
+};
+
+export const AllowingFullBleed: React.FC<StoryArgs> = (
+    args,
+): React.ReactElement => {
+    return (
+        <FixedToResponsive
+            width={width}
+            height={sizeMedium}
+            allowFullBleed={true}
+        >
+            <img
+                alt=""
+                width={sizeMedium}
+                height={sizeMedium}
+                src={getDependencies().staticUrl(svgUrl)}
+            />
+        </FixedToResponsive>
+    );
+};

package/src/components/__stories__/graph.stories.tsx

@@ -0,0 +1,30 @@
+import * as React from "react";
+
+import Graph from "../graph";
+// TODO(scottgrant): Katex is unavailable here. Fix!
+
+type StoryArgs = Record<any, any>;
+
+type Story = {
+    title: string;
+};
+
+const size = 200;
+
+export default {
+    title: "Perseus/Components/Graph",
+} as Story;
+
+export const SquareBoxSizeAndOtherwiseEmpty: React.FC<StoryArgs> = (
+    args,
+): React.ReactElement => {
+    return <Graph box={[size, size]} />;
+};
+
+export const LabeledSquaredBox: React.FC<StoryArgs> = (
+    args,
+): React.ReactElement => {
+    return (
+        <Graph box={[size, size]} labels={["First label", "Second label"]} />
+    );
+};