@khanacademy/perseus 3.0.0 → 4.0.0

package/src/styles/shared.ts

@@ -0,0 +1,130 @@
+import {StyleSheet} from "aphrodite";
+
+import * as constants from "./constants";
+import mediaQueries from "./media-queries";
+
+import type {StyleDeclaration} from "aphrodite";
+
+const {
+    zIndexAboveScratchpad,
+    zIndexInteractiveComponent,
+    radioBorderColor,
+    checkedColor,
+    circleSize,
+    radioMarginWidth,
+} = constants;
+
+export default StyleSheet.create({
+    perseusInteractive: {
+        zIndex: zIndexInteractiveComponent,
+        position: "relative",
+    },
+
+    aboveScratchpad: {
+        position: "relative",
+        zIndex: zIndexAboveScratchpad,
+    },
+
+    blankBackground: {
+        // TODO(emily): Use KhanUtil._BACKGROUND?
+        backgroundColor: "#FDFDFD",
+    },
+
+    perseusSrOnly: {
+        border: 0,
+        clip: "rect(0,0,0,0)",
+        height: 1,
+        margin: -1,
+        overflow: "hidden",
+        padding: 0,
+        position: "absolute",
+        width: 1,
+    },
+
+    responsiveLabel: {
+        // NOTE(charlie): The values used here should be kept in sync with the
+        // caption text sizing in Perseus' articles.less.
+        // TODO(charlie): Migrate the captions over to using this style.
+        [mediaQueries.smOrSmaller]: {
+            fontSize: 14,
+            lineHeight: 1.3,
+        },
+        [mediaQueries.md]: {
+            fontSize: 17,
+            lineHeight: 1.4,
+        },
+        [mediaQueries.lgOrLarger]: {
+            fontSize: 20,
+            lineHeight: 1.4,
+        },
+    },
+
+    responsiveInput: {
+        display: "inline-block",
+        WebkitAppearance: "none",
+        appearance: "none",
+
+        "::-ms-check": {
+            display: "none",
+        },
+
+        backgroundColor: "#fff",
+        border: "2px solid #fff",
+        boxShadow: `0 0px 0px 1px ${radioBorderColor}`,
+        outline: "none",
+
+        boxSizing: "border-box",
+        flexShrink: 0,
+        marginBottom: 1,
+        marginLeft: 1,
+        marginRight: 1,
+        marginTop: 1,
+
+        height: circleSize - 2,
+        width: circleSize - 2,
+    },
+
+    responsiveRadioInput: {
+        borderRadius: "50%",
+
+        ":checked": {
+            backgroundColor: checkedColor,
+            border: "none",
+            borderRadius: "50%",
+            boxShadow:
+                `inset 0px 0px 0px 2px white, ` +
+                `0 0px 0px 2px ${checkedColor}`,
+
+            marginTop: radioMarginWidth,
+            marginBottom: radioMarginWidth,
+            marginLeft: radioMarginWidth,
+            marginRight: radioMarginWidth,
+
+            height: circleSize - 2 * radioMarginWidth,
+            width: circleSize - 2 * radioMarginWidth,
+        },
+    },
+
+    responsiveRadioInputActive: {
+        backgroundColor: "#fff",
+        border: "2px solid #fff",
+        borderRadius: "50%",
+        boxShadow: `0 0px 0px 2px ${checkedColor}`,
+
+        marginTop: radioMarginWidth,
+        marginBottom: radioMarginWidth,
+        marginLeft: radioMarginWidth,
+        marginRight: radioMarginWidth,
+
+        height: circleSize - 2 * radioMarginWidth,
+        width: circleSize - 2 * radioMarginWidth,
+
+        ":checked": {
+            backgroundColor: "#fff",
+        },
+    },
+
+    disableTextSelection: {
+        userSelect: "none",
+    },
+}) as StyleDeclaration;

package/src/tex-wrangler.ts

@@ -0,0 +1,182 @@
+/*
+ * In this file, an `expression` is some portion of valid TeX enclosed in
+ * curly brackets.
+ */
+
+/*
+ * Find the index at which an expression ends, i.e., has an unmatched
+ * closing curly bracket. This method assumes that we start with a non-open
+ * bracket character and end when we've seen more left than right brackets
+ * (rather than assuming that we start with a bracket character and wait for
+ * bracket equality).
+ */
+function findEndpoint(tex, currentIndex: number) {
+    let bracketDepth = 0;
+
+    for (let i = currentIndex, len = tex.length; i < len; i++) {
+        const c = tex[i];
+
+        if (c === "{") {
+            bracketDepth++;
+        } else if (c === "}") {
+            bracketDepth--;
+        }
+
+        if (bracketDepth < 0) {
+            return i;
+        }
+    }
+    // If we never see unbalanced curly brackets, default to the
+    // entire string
+    return tex.length;
+}
+
+/*
+ * Parses an individual set of curly brackets into TeX.
+ */
+function parseNextExpression(
+    tex: string,
+    currentIndex: number,
+    handler: (exp1: string, exp2: string) => string,
+) {
+    // Find the first '{' and grab subsequent TeX
+    // Ex) tex: '{3}{7}', and we want the '3'
+    const openBracketIndex = tex.indexOf("{", currentIndex);
+    const nextExpIndex = openBracketIndex + 1;
+
+    // Truncate to only contain remaining TeX
+    const endpoint = findEndpoint(tex, nextExpIndex);
+    const expressionTeX = tex.substring(nextExpIndex, endpoint);
+    const parsedExp = walkTex(expressionTeX, handler);
+
+    return {
+        endpoint: endpoint,
+        expression: parsedExp,
+    };
+}
+
+function getNextFracIndex(tex: string, currentIndex: number) {
+    const dfrac = "\\dfrac";
+    const frac = "\\frac";
+
+    const nextFrac = tex.indexOf(frac, currentIndex);
+    const nextDFrac = tex.indexOf(dfrac, currentIndex);
+
+    if (nextFrac > -1 && nextDFrac > -1) {
+        return Math.min(nextFrac, nextDFrac);
+    }
+    if (nextFrac > -1) {
+        return nextFrac;
+    }
+    if (nextDFrac > -1) {
+        return nextDFrac;
+    }
+    return -1;
+}
+
+function walkTex(
+    tex: string,
+    handler: (exp1: string, exp2: string) => string,
+): string {
+    if (!tex) {
+        return "";
+    }
+
+    // Ex) tex: '2 \dfrac {3}{7}'
+    let parsedString = "";
+    let currentIndex = 0;
+    let nextFrac = getNextFracIndex(tex, currentIndex);
+
+    // For each \dfrac, find the two expressions (wrapped in {}) and recur
+    while (nextFrac > -1) {
+        // Gather first fragment, preceding \dfrac
+        // Ex) parsedString: '2 '
+        parsedString += tex.substring(currentIndex, nextFrac);
+
+        // Remove everything preceding \dfrac, which has been parsed
+        currentIndex = nextFrac;
+
+        // Parse first expression and move index past it
+        // Ex) firstParsedExpression.expression: '3'
+        const firstParsedExpression = parseNextExpression(
+            tex,
+            currentIndex,
+            handler,
+        );
+        currentIndex = firstParsedExpression.endpoint + 1;
+
+        // Parse second expression
+        // Ex) secondParsedExpression.expression: '7'
+        const secondParsedExpression = parseNextExpression(
+            tex,
+            currentIndex,
+            handler,
+        );
+        currentIndex = secondParsedExpression.endpoint + 1;
+
+        // Add expressions to running total of parsed expressions
+        if (parsedString.length) {
+            parsedString += " ";
+        }
+
+        // Apply a custom handler based on the parsed subexpressions
+        parsedString += handler(
+            firstParsedExpression.expression,
+            secondParsedExpression.expression,
+        );
+
+        // Find next DFrac, relative to currentIndex
+        nextFrac = getNextFracIndex(tex, currentIndex);
+    }
+
+    // Add remaining TeX, which is \dfrac-free
+    parsedString += tex.slice(currentIndex);
+
+    return parsedString;
+}
+
+/*
+ * Modify a TeX expression, returning another TeX expression. The resulting
+ * expression will have its innermost fractions stubbed out with \fracs
+ * (as opposed to \dfracs). All other content will remain untouched.
+ */
+function modifyTex(tex: string): string {
+    function isNestedFraction(tex: string) {
+        return tex.indexOf("\\frac") > -1 || tex.indexOf("\\dfrac") > -1;
+    }
+    const handler = function (exp1: string, exp2: string) {
+        let prefix;
+        if (isNestedFraction(exp1) || isNestedFraction(exp2)) {
+            prefix = "\\dfrac";
+        } else {
+            prefix = "\\frac";
+        }
+        return prefix + " {" + exp1 + "}{" + exp2 + "}";
+    };
+    return walkTex(tex, handler);
+}
+
+/*
+ * Parse a TeX expression into something interpretable by input-number.
+ * The process is concerned with: (1) parsing fractions, i.e., \dfracs; and
+ * (2) removing backslash-escaping from certain characters (right now, only
+ * percent signs).
+ *
+ * The basic algorithm for handling \dfracs splits on \dfracs and then recurs
+ * on the subsequent "expressions", i.e., the {} pairs that follow \dfrac. The
+ * recursion is to allow for nested \dfrac elements.
+ *
+ * Backslash-escapes are removed with a simple search-and-replace.
+ */
+function parseTex(tex: string): string {
+    const handler = function (exp1: string, exp2: string) {
+        return exp1 + "/" + exp2;
+    };
+    const texWithoutFracs = walkTex(tex, handler);
+    return texWithoutFracs.replace("\\%", "%");
+}
+
+export default {
+    parseTex,
+    modifyTex,
+};

package/src/translation-linter.ts

@@ -0,0 +1,126 @@
+import {Rule} from "@khanacademy/perseus-linter";
+import {debounce} from "underscore";
+
+/**
+ * TranslationLinter asynchronously calls Khan Academy's poentry linter.
+ *
+ * The poentry linter checks for issues that prevent content from being
+ * translated. This linter is KA-specific and so TranslationLinter does not do
+ * anything in non-KA environments.
+ */
+
+declare const KA: any;
+
+// A LintCB is called once the linter has been run.
+type LintCB = (errors: ReadonlyArray<string>) => void;
+
+// msec to wait before we actually call the linter after receiving the
+// last call. The timer is reset if the lint is called during the wait.
+const DEBOUNCE_TIMEOUT = 1000;
+
+export default class TranslationLinter {
+    // To avoid linting when nothing has changed.
+    previousContent: string | null | undefined = null;
+
+    /**
+     * Runs the poentry linter on the given perseus string asynchronously.
+     *
+     * It doesn't do anything unless we're in a KA environment.
+     *
+     * onLintErrorsGenerated is called even if there are no errors. It is not
+     * called if perseusStr is unchanged from the last call.
+     *
+     * Linting is relatively expensive -- so we debounce linting each instance
+     * for some amount of time.
+     */
+    runLinter: any = debounce(
+        (perseusStr: string, onLintErrorsGenerated: LintCB) => {
+            // TODO(FEI-5003): Do we still need to check for 'KA'?
+            if (typeof KA === "undefined") {
+                return;
+            }
+
+            if (perseusStr === this.previousContent) {
+                return;
+            }
+
+            this.previousContent = perseusStr;
+
+            if (perseusStr === "") {
+                onLintErrorsGenerated([]);
+                return;
+            }
+
+            fetch("/api/internal/translations/lint_poentry?preview=1&lang=en", {
+                headers: {"Content-Type": "application/json"},
+                body: JSON.stringify({
+                    // The poentry linter verifies that the translation from
+                    // the original text to the translated text is sane. We
+                    // want to ensure that the translation from English to
+                    // English is sane, so msgid === mstr.
+                    msgid: perseusStr, // msgid is the original text
+                    msgstr: perseusStr, // msgstr is the translated text
+                    format: "perseus_text",
+                    filename: "",
+                }),
+                method: "POST",
+            })
+                .then(
+                    (response) => {
+                        if (response.status >= 400) {
+                            return {
+                                status: "error",
+                                message: "Could not run i18n linter.",
+                            };
+                        }
+                        return response.json();
+                    },
+                    (rejection) => {
+                        return {
+                            status: "error",
+                            message: "Could not run i18n linter.",
+                        };
+                    },
+                )
+                .then((json) => {
+                    if (json.status === "error") {
+                        onLintErrorsGenerated([
+                            "Some part of this text makes it untranslatable. " +
+                                "The specific message from the i18n linter was: " +
+                                json.message.replace(/\n/g, " "),
+                        ]);
+                    } else {
+                        onLintErrorsGenerated([]);
+                    }
+                });
+        },
+        DEBOUNCE_TIMEOUT,
+    );
+
+    /**
+     * Applies an array of errors generated by linters without position
+     * information (TranslationLinter and the legacy getSaveWarnings()) to the
+     * top of a Perseus tree.
+     */
+    applyLintErrors(
+        parsedMarkdown: any,
+        translationLintErrors: ReadonlyArray<string>,
+    ) {
+        // These lint errors do not have position data associated with
+        // them, so we just plop them at the top.
+        if (translationLintErrors.length) {
+            const errorText = translationLintErrors.join("\n\n");
+            parsedMarkdown.unshift({
+                content: {
+                    type: "text",
+                    content: "",
+                },
+                insideTable: false,
+                message: errorText,
+                ruleName: "legacy-error",
+                severity: Rule.Severity.ERROR,
+                type: "lint",
+            });
+        }
+    }
+}

package/src/traversal.ts

@@ -0,0 +1,138 @@
+/**
+ * Traverses a {content, widgets, images} renderer props object,
+ * such as `itemData.question`
+ *
+ * This traversal is deep and handles some widget prop upgrades
+ * (TODO(aria): Handle minor prop upgrades :) )
+ *
+ * This is the right way to traverse itemData.
+ *
+ * NOTE: We should not expose this on the perseus API yet. Instead,
+ * build the traversal method you want inside perseus, and use this
+ * from that. We might eventually expose this, but I'd like to be
+ * more confident in the interface provided first.
+ */
+
+import _ from "underscore";
+
+// TODO(aria): Pull this out of interactive2 / replace with new _.mapObject
+import objective_ from "./interactive2/objective_";
+import * as Widgets from "./widgets";
+
+const noop = function () {};
+
+const deepCallbackFor = function (
+    contentCallback: (arg1: any) => void,
+    widgetCallback: (widgetInfo: any, widgetId: string) => any,
+    optionsCallback: (arg1: any) => void,
+) {
+    const deepCallback = function (widgetInfo: any, widgetId: string) {
+        // This doesn't modify the widget info if the widget info
+        // is at a later version than is supported, which is important
+        // for our latestVersion test below.
+        const upgradedWidgetInfo =
+            Widgets.upgradeWidgetInfoToLatestVersion(widgetInfo);
+        const latestVersion = Widgets.getVersion(upgradedWidgetInfo.type);
+
+        // Only traverse our children if we can understand this version
+        // of the widget props.
+        // TODO(aria): This will break if the traversal code assumes that
+        // any props that usually get defaulted in are present. That is,
+        // it can fail on minor version upgrades.
+        // For this reason, and because the upgrade code doesn't handle
+        // minor versions correctly (it doesn't report anything useful
+        // about what minor version a widget is actually at, since it
+        // doesn't have meaning in the context of upgrades), we
+        // just check the major version here.
+        // TODO(aria): This is seriously quirky and would be unpleasant
+        // to think about while writing traverseChildWidgets code. Please
+        // make all of this a little tighter.
+        // I think once we use react class defaultProps instead of relying
+        // on getDefaultProps, this will become easier.
+        let newWidgetInfo;
+        if (
+            latestVersion &&
+            upgradedWidgetInfo.version?.major === latestVersion.major
+        ) {
+            newWidgetInfo = Widgets.traverseChildWidgets(
+                upgradedWidgetInfo,
+                (rendererOptions) => {
+                    return traverseRenderer(
+                        rendererOptions,
+                        contentCallback,
+                        // so that we traverse grandchildren, too:
+                        deepCallback,
+                        optionsCallback,
+                    );
+                },
+            );
+        } else {
+            newWidgetInfo = upgradedWidgetInfo;
+        }
+
+        const userWidgetInfo = widgetCallback(newWidgetInfo, widgetId);
+        if (userWidgetInfo !== undefined) {
+            return userWidgetInfo;
+        }
+        return newWidgetInfo;
+    };
+    return deepCallback;
+};
+
+const traverseRenderer = function (
+    rendererOptions,
+    contentCallback: (arg1: any) => void,
+    deepWidgetCallback: (widgetInfo: any, widgetId: string) => any,
+    optionsCallback: (arg1: any) => void,
+) {
+    let newContent = rendererOptions.content;
+    if (rendererOptions.content != null) {
+        const modifiedContent = contentCallback(rendererOptions.content);
+        if (modifiedContent !== undefined) {
+            newContent = modifiedContent;
+        }
+    }
+
+    const newWidgets = objective_.mapObject(
+        rendererOptions.widgets || {},
+        function (widgetInfo, widgetId) {
+            // Widgets without info or a type are empty widgets, and
+            // should always be renderable. It's also annoying to write
+            // checks for this everywhere, so we just filter them out once and
+            // for all!
+            // @ts-expect-error [FEI-5003] - TS2571 - Object is of type 'unknown'.
+            if (widgetInfo == null || widgetInfo.type == null) {
+                return widgetInfo;
+            }
+            return deepWidgetCallback(widgetInfo, widgetId);
+        },
+    );
+
+    const newOptions = _.extend({}, rendererOptions, {
+        content: newContent,
+        widgets: newWidgets,
+    });
+    const userOptions = optionsCallback(newOptions);
+    if (userOptions !== undefined) {
+        return userOptions;
+    }
+    return newOptions;
+};
+
+export const traverse = function (
+    rendererOptions: any,
+    contentCallback?: ((arg1: any) => any) | null,
+    widgetCallback?: ((widgetInfo: any, widgetId: string) => any) | null,
+    optionsCallback?: (arg1: any) => void,
+): any {
+    contentCallback = contentCallback || noop;
+    widgetCallback = widgetCallback || noop;
+    optionsCallback = optionsCallback || noop;
+
+    return traverseRenderer(
+        rendererOptions,
+        contentCallback,
+        deepCallbackFor(contentCallback, widgetCallback, optionsCallback),
+        optionsCallback,
+    );
+};