@khanacademy/perseus 3.0.0 → 4.0.0

package/src/perseus-api.jsx

@@ -1,214 +0,0 @@
-// @flow
-/**
- * [Most of] the Perseus client API.
- *
- * If making a change to this file, or otherwise to the perseus
- * API, you should increment:
- *  * the perseus api major version if it is a breaking change
- *  * the perseus api minor version if it is an additive-only change
- *  * nothing if it is purely a bug fix.
- *
- * Callbacks passed to Renderer/ItemRenderer:
- *  * onInputError:
- *    Called when there is an error grading a widget
- *  * onFocusChange: (newFocusPath, oldFocusPath, keypadDOMNode)
- *    Called when the user focus changes. The first two parameters are `path`
- *    arrays uniquely identifying the respect inputs. The third parameter,
- *    `keypadDOMNode`, is the DOM node of the custom keypad, or `null` if the
- *    keypad is disabled, which can be used by clients to accommodate for the
- *    appearance of the keypad on the screen.
- *    When focus changes to or from nothing being selected, `path` will be null.
- *  * interactionCallback: Called when the user interacts with a widget.
- *  * answerableCallback: Called with the current `answerability` of the
- *    problem, e.g. whether all required fields have input.
- *  * getAnotherHint: If provided, a button is rendered at the bottom of the
- *    hints (only when at least one hint has been shown, and not all hints
- *    have been shown) allowing the user to take another hint. This function
- *    is then called when the user clicks the button.
- *
- * Stable CSS ClassNames:
- * These are css class names that will continue to preserve their
- * semantic meaning across the same perseus api major version.
- */
-import PropTypes from "prop-types";
-import * as React from "react";
-
-import StubTagEditor from "./components/stub-tag-editor.jsx";
-
-import type {APIOptionsWithDefaults} from "./types.js";
-
-export const ApiOptions = {
-    propTypes: (PropTypes.shape({
-        isArticle: PropTypes.bool.isRequired,
-
-        onInputError: PropTypes.func.isRequired,
-        onFocusChange: PropTypes.func.isRequired,
-        GroupMetadataEditor: PropTypes.func.isRequired,
-        showAlignmentOptions: PropTypes.bool.isRequired,
-        readOnly: PropTypes.bool.isRequired,
-
-        answerableCallback: PropTypes.func,
-        getAnotherHint: PropTypes.func,
-        interactionCallback: PropTypes.func,
-
-        // A function that takes in the relative problem number (starts at
-        // 0 and is incremented for each group widget), and the ID of the
-        // group widget, then returns a react component that will be added
-        // immediately above the renderer in the group widget. If the
-        // function returns null, no annotation will be added.
-        groupAnnotator: PropTypes.func.isRequired,
-
-        // If imagePlaceholder or widgetPlaceholder are set, perseus will
-        // render the placeholder instead of the image or widget node.
-        imagePlaceholder: PropTypes.node,
-        widgetPlaceholder: PropTypes.node,
-
-        // Base React elements that can be used in place of the standard DOM
-        // DOM elements. For example, when provided, <Link /> will be used
-        // in place of <a />. This allows clients to provide pre-styled
-        // components or components with custom behavior.
-        baseElements: PropTypes.shape({
-            // The <Link /> component provided here must adhere to the same
-            // interface as React's base <a /> component.
-            Link: PropTypes.func,
-        }),
-
-        // Function that takes dimensions and returns a React component
-        // to display while an image is loading
-        imagePreloader: PropTypes.func,
-
-        // Function that takes an object argument. The object should
-        // include type and id, both strings, at least and can optionally
-        // include a boolean "correct" value. This is used for keeping
-        // track of widget interactions.
-        trackInteraction: PropTypes.func,
-
-        // A boolean that indicates whether or not a custom keypad is
-        // being used.  For mobile web this will be the ProvidedKeypad
-        // component.  In this situation we use the MathInput component
-        // from the math-input repo instead of the existing perseus math
-        // input components.
-        customKeypad: PropTypes.bool,
-
-        // If this is provided, it is called instead of appending an instance
-        // of `math-input`'s keypad to the body. This is used by the native
-        // apps so they can have the keypad be defined on the native side.
-        // It is called with an function that, when called, blurs the input,
-        // and is expected to return an object of the shape
-        // keypadElementPropType from math-input/src/prop-types.js.
-        nativeKeypadProxy: PropTypes.func,
-
-        // Indicates whether or not to use mobile styling.
-        isMobile: PropTypes.bool,
-
-        // A function, called with a bool indicating whether use of the
-        // drawing area (scratchpad) should be allowed/disallowed.
-        // Previously handled by `Khan.scratchpad.enable/disable`
-        setDrawingAreaAvailable: PropTypes.func,
-
-        // Whether to use the Draft.js editor or the legacy textarea
-        useDraftEditor: PropTypes.bool,
-
-        // The color used for the hint progress indicator (eg. 1 / 3)
-        hintProgressColor: PropTypes.string,
-
-        // Whether this Renderer is allowed to auto-scroll the rest of the
-        // page. For example, if this is enabled, the most recently used
-        // radio widget will attempt to keep the "selected" answer in view
-        // after entering review mode.
-        //
-        // Defaults to `false`.
-        canScrollPage: PropTypes.bool,
-
-        // Whether or not we are rendering content inside of a modal.
-        inModal: PropTypes.bool,
-
-        // Whether to enable the cross-out feature on multiple-choice radio
-        // widgets. This allows users to note which answers they believe to
-        // be incorrect, to find the answer by process of elimination.
-        //
-        // We plan to roll this out to all call sites eventually, but for
-        // now we have this flag, to add it to Generalized Test Prep first.
-        crossOutEnabled: PropTypes.bool,
-
-        // The value in milliseconds by which the local state of content
-        // in a editor is delayed before propagated to a prop. For example,
-        // when text is typed in the text area of an Editor component,
-        // there will be a delay equal to the value of `editorChangeDelay`
-        // before the change is propagated. This is added for better
-        // responsiveness of the editor when used in certain contexts such
-        // as StructuredItem exercises where constant re-rendering for each
-        // keystroke caused text typed in the text area to appear in it
-        // only after a good few seconds.
-        editorChangeDelay: PropTypes.number,
-    }).isRequired: React$PropType$Primitive$Required<{
-        GroupMetadataEditor: (...a: $ReadOnlyArray<any>) => mixed,
-        answerableCallback?: (...a: $ReadOnlyArray<any>) => mixed,
-        baseElements?: {Link?: (...a: $ReadOnlyArray<any>) => mixed, ...},
-        canScrollPage?: boolean,
-        crossOutEnabled?: boolean,
-        customKeypad?: boolean,
-        editorChangeDelay?: number,
-        getAnotherHint?: (...a: $ReadOnlyArray<any>) => mixed,
-        groupAnnotator: (...a: $ReadOnlyArray<any>) => mixed,
-        hintProgressColor?: string,
-        imagePlaceholder?: any,
-        imagePreloader?: (...a: $ReadOnlyArray<any>) => mixed,
-        inModal?: boolean,
-        interactionCallback?: (...a: $ReadOnlyArray<any>) => mixed,
-        isArticle: boolean,
-        isMobile?: boolean,
-        nativeKeypadProxy?: (...a: $ReadOnlyArray<any>) => mixed,
-        onFocusChange: (...a: $ReadOnlyArray<any>) => mixed,
-        onInputError: (...a: $ReadOnlyArray<any>) => mixed,
-        readOnly: boolean,
-        setDrawingAreaAvailable?: (...a: $ReadOnlyArray<any>) => mixed,
-        showAlignmentOptions: boolean,
-        trackInteraction?: (...a: $ReadOnlyArray<any>) => mixed,
-        useDraftEditor?: boolean,
-        widgetPlaceholder?: any,
-        ...
-    }>),
-
-    defaults: ({
-        isArticle: false,
-        isMobile: false,
-        onInputError: function () {},
-        onFocusChange: function () {},
-        GroupMetadataEditor: StubTagEditor,
-        showAlignmentOptions: false,
-        readOnly: false,
-        groupAnnotator: function (): null {
-            return null;
-        },
-        baseElements: {
-            Link: (props: any): React.Element<"a"> => {
-                return <a {...props} />;
-            },
-        },
-        setDrawingAreaAvailable: function () {},
-        useDraftEditor: false,
-        canScrollPage: false,
-        inModal: false,
-        crossOutEnabled: false,
-        editorChangeDelay: 0,
-    }: APIOptionsWithDefaults),
-};
-
-export const ClassNames = {
-    RENDERER: "perseus-renderer",
-    TWO_COLUMN_RENDERER: "perseus-renderer-two-columns",
-    RESPONSIVE_RENDERER: "perseus-renderer-responsive",
-    INPUT: "perseus-input",
-    FOCUSED: "perseus-focused",
-    RADIO: {
-        OPTION: "perseus-radio-option",
-        SELECTED: "perseus-radio-selected",
-        OPTION_CONTENT: "perseus-radio-option-content",
-    },
-    INTERACTIVE: "perseus-interactive",
-    CORRECT: "perseus-correct",
-    INCORRECT: "perseus-incorrect",
-    UNANSWERED: "perseus-unanswered",
-    MOBILE: "perseus-mobile",
-};

package/src/perseus-env.js

@@ -1,26 +0,0 @@
-// @flow
-/**
- * Sets up the basic environment for running Perseus in.
- */
-
-window.KhanUtil = {
-    debugLog: function () {},
-    localeToFixed: function (num, precision) {
-        return num.toFixed(precision);
-    },
-};
-
-window.Exercises = {
-    localMode: true,
-
-    khanExercisesUrlBase: "../",
-
-    getCurrentFramework: function () {
-        return "khan-exercises";
-    },
-    PerseusBridge: {
-        cleanupProblem: function () {
-            return false;
-        },
-    },
-};

package/src/perseus-error.js

@@ -1,19 +0,0 @@
-// @flow
-
-import type {ErrorKind} from "./logging/log.js";
-import type {Metadata} from "@khanacademy/wonder-stuff-core";
-
-type Options = {|
-    metadata?: ?Metadata,
-|};
-
-export class PerseusError extends Error {
-    kind: ErrorKind;
-    metadata: ?Metadata;
-
-    constructor(message: string, kind: ErrorKind, options?: Options) {
-        super(message);
-        this.kind = kind;
-        this.metadata = options?.metadata;
-    }
-}

package/src/perseus-markdown.jsx

@@ -1,408 +0,0 @@
-/* eslint-disable no-useless-escape, no-prototype-builtins */
-// @flow
-import {pureMarkdownRules} from "@khanacademy/pure-markdown";
-import SimpleMarkdown from "@khanacademy/simple-markdown";
-import * as i18n from "@khanacademy/wonder-blocks-i18n";
-import * as React from "react";
-import _ from "underscore";
-
-import Lint from "./components/lint.jsx";
-import {getDependencies} from "./dependencies.js";
-
-const rules = {
-    ...pureMarkdownRules,
-
-    // NOTE: basically ignored by JIPT. wraps everything at the outer layer
-    columns: {
-        ...pureMarkdownRules.columns,
-        react: (node, output, state) => {
-            return (
-                <div className="perseus-two-columns" key={state.key}>
-                    <div className="perseus-column">
-                        <div className="perseus-column-content">
-                            {output(node.col1, state)}
-                        </div>
-                    </div>
-                    <div className="perseus-column">
-                        <div className="perseus-column-content">
-                            {output(node.col2, state)}
-                        </div>
-                    </div>
-                </div>
-            );
-        },
-    },
-    // Match paragraphs consisting solely of crowdin IDs
-    // (they look roughly like crwdns9238932:0), which means that
-    // crowdin is going to take the DOM node that ID is rendered into
-    // and count it as the top-level translation node. They mutate this
-    // node, so we need to make sure it is an outer node, not an inner
-    // span. So here we parse this separately and just output the
-    // raw string, which becomes the body of the <QuestionParagraph>
-    // created by the Renderer.
-    // This currently (2015-09-01) affects only articles, since
-    // for exercises the renderer just renders the crowdin id to the
-    // renderer div.
-    crowdinId: {
-        ...pureMarkdownRules.crowdinId,
-        react: (node, output, state) => node.id,
-    },
-    // Ensure that the table is focusable in sequential keyboard navigation
-    // when rendered on mobile in a modal. Specifically this is needed for
-    // Android Talkback, to enable reading/navigating tables with the swipe
-    // left/right gesture. Note, setting `tabindex` doesn't appear required for
-    // iOS 14.4, in order for VoiceOver to work.
-    table: {
-        ...pureMarkdownRules.table,
-        react: function (node, output, state) {
-            // $FlowFixMe[prop-missing]
-            // $FlowFixMe[incompatible-use]
-            const table = SimpleMarkdown.defaultRules.table.react(
-                node,
-                output,
-                state,
-            );
-
-            if (!state.isMobile) {
-                return table;
-            }
-
-            return React.cloneElement(table, {tabIndex: 0});
-        },
-    },
-    // This is pretty much horrible, but we have a regex here to capture an
-    // entire table + a title. capture[1] is the title. capture[2] of the
-    // regex is a copy of the simple-markdown nptable regex. Then we turn
-    // our capture[2] into tableCapture[0], and any further captures in
-    // our table regex into tableCapture[1..], and we pass tableCapture to
-    // our nptable regex
-    titledTable: {
-        ...pureMarkdownRules.titledTable,
-        react: (node, output, state) => {
-            let contents;
-            if (!node.table) {
-                contents = "//invalid table//";
-            } else if (node.table.type === "lint") {
-                // The `table` in this node is actually a `lint` node,
-                // not the expected `table` node. This is due to the linter
-                // implementation "reparenting" the `table` node, see
-                // perseus-linter/src/index.js
-                if (node.table.content?.type === "table") {
-                    // And the `content` of this lint node is the `table` node
-                    // which we actually want to render. Thus, we perform
-                    // surgery on the node to form the desired shape, so that
-                    // we can render a `lint` node which will then recursively
-                    // render the correctly shaped `titledTable` node.
-                    contents = rules.lint.react(
-                        {
-                            ...node.table,
-                            content: {
-                                ...node,
-                                table: node.table.content,
-                            },
-                        },
-                        output,
-                        {
-                            ...state,
-                            // Recursively render the `titledTable` node without
-                            // the wrapper div, as we'll be wrapping `contents`
-                            // ourselves below.
-                            unwrapTitledTableContents: true,
-                        },
-                    );
-                } else {
-                    // We know `node.table` is actually a `lint` node, but we
-                    // don't know how to handle its `content`. Let the lint
-                    // node renderer figure it out.
-                    contents = rules.lint.react(node.table, output, state);
-                }
-            } else {
-                // $FlowFixMe[prop-missing]
-                // $FlowFixMe[incompatible-use]
-                const tableOutput = SimpleMarkdown.defaultRules.table.react(
-                    node.table,
-                    output,
-                    state,
-                );
-
-                const caption = (
-                    <caption key="caption" className="perseus-table-title">
-                        {output(node.title, state)}
-                    </caption>
-                );
-
-                // Splice the caption into the table's children with the
-                // caption as the first child.
-                contents = React.cloneElement(tableOutput, null, [
-                    caption,
-                    ...tableOutput.props.children,
-                ]);
-            }
-
-            if (state.unwrapTitledTableContents) {
-                return contents;
-            }
-
-            // Note: if the DOM structure changes, edit the Zoomable wrapper
-            // in src/renderer.jsx.
-            return (
-                <div className="perseus-titled-table" key={state.key}>
-                    {contents}
-                </div>
-            );
-        },
-    },
-    widget: {
-        ...pureMarkdownRules.widget,
-        react: (node, output, state) => {
-            // The actual output is handled in the renderer, where
-            // we know the current widget props/state. This is
-            // just a stub for testing.
-            return (
-                <em key={state.key}>
-                    {i18n.doNotTranslate("[Widget: ", node.id, "]")}
-                </em>
-            );
-        },
-    },
-    blockMath: {
-        ...pureMarkdownRules.blockMath,
-        react: (node, output, state) => {
-            const {TeX} = getDependencies();
-            // The actual output is handled in the renderer, because
-            // it needs to pass in an `onRender` callback prop. This
-            // is just a stub for testing.
-            return <TeX key={state.key}>{node.content}</TeX>;
-        },
-    },
-    math: {
-        ...pureMarkdownRules.math,
-        react: (node, output, state) => {
-            const {TeX} = getDependencies();
-            // The actual output is handled in the renderer, because
-            // it needs to pass in an `onRender` callback prop. This
-            // is just a stub for testing.
-            return <TeX key={state.key}>{node.content}</TeX>;
-        },
-    },
-    unescapedDollar: {
-        ...pureMarkdownRules.unescapedDollar,
-        react: (node, output, state) => {
-            // Unescaped dollar signs render correctly, but result in
-            // untranslatable text after the i18n python linter flags it
-            return "$";
-        },
-    },
-    // Extend the SimpleMarkdown link parser to make the link open in a new
-    // window and handle reverse tabnapping phishing attacks
-    link: {
-        ...pureMarkdownRules.link,
-        react: function (node, output, state) {
-            // $FlowFixMe[prop-missing]
-            // $FlowFixMe[incompatible-use]
-            const link = SimpleMarkdown.defaultRules.link.react(
-                node,
-                output,
-                state,
-            );
-
-            const href = link.props.href;
-            let rel = null;
-            // The href prop should always be here, but just in case somehow the article's
-            // link was not put together properly, let's make sure it's there so we
-            // don't break the entire page.
-            const isKAUrl = href
-                ? href.match(/https?:\/\/[^\/]*khanacademy.org|^\//)
-                : false;
-            if (!isKAUrl) {
-                // Prevents "reverse tabnabbing" phishing attacks
-                rel = "noopener noreferrer";
-            }
-
-            const newProps = {...link.props, target: "_blank", href, rel};
-
-            if (state.baseElements && state.baseElements.Link) {
-                return state.baseElements.Link(newProps);
-            }
-            return React.cloneElement(link, newProps);
-        },
-    },
-    codeBlock: {
-        ...pureMarkdownRules.codeBlock,
-        react: (node, output, state) => {
-            // ideally this should be a different rule, with only an
-            // output function, but right now that breaks the parser.
-            if (node.lang === "alt") {
-                return (
-                    <div
-                        key={state.key}
-                        className="perseus-markdown-alt perseus-sr-only"
-                    >
-                        {output(node.content, state)}
-                    </div>
-                );
-            }
-            // $FlowFixMe[prop-missing]
-            // $FlowFixMe[incompatible-use]
-            return SimpleMarkdown.defaultRules.codeBlock.react(
-                node,
-                output,
-                state,
-            );
-        },
-    },
-    // The lint rule never actually matches anything.
-    // We check for lint after parsing, and, if we find any, we
-    // transform the tree to add lint nodes. This rule is here
-    // just for the react() function
-    lint: {
-        ...pureMarkdownRules.lint,
-        react: (node, output, state) => {
-            return (
-                <Lint
-                    message={node.message}
-                    ruleName={node.ruleName}
-                    inline={isInline(node.content)}
-                    blockHighlight={node.blockHighlight}
-                    insideTable={node.insideTable}
-                    severity={node.severity}
-                >
-                    {output(node.content, state)}
-                </Lint>
-            );
-        },
-    },
-};
-
-// Return true if the specified parse tree node represents inline content
-// and false otherwise. We need this so that lint nodes can figure out whether
-// they should behave as an inline wrapper or a block wrapper
-function isInline(node) {
-    // eslint-disable-next-line no-prototype-builtins
-    return !!(node && node.type && inlineNodeTypes.hasOwnProperty(node.type));
-}
-const inlineNodeTypes = {
-    text: true,
-    math: true,
-    unescapedDollar: true,
-    link: true,
-    img: true,
-    strong: true,
-    u: true,
-    em: true,
-    del: true,
-    code: true,
-};
-
-// $FlowFixMe[prop-missing]
-// $FlowFixMe[incompatible-call]
-const builtParser = SimpleMarkdown.parserFor(rules);
-const parse = (source: string, state: $FlowFixMe): $FlowFixMe => {
-    const paragraphedSource = source + "\n\n";
-
-    return builtParser(paragraphedSource, {
-        ...state,
-        inline: false,
-    });
-};
-const inlineParser = (source: string, state: $FlowFixMe): $FlowFixMe => {
-    return builtParser(source, {
-        ...state,
-        inline: true,
-    });
-};
-
-/**
- * Traverse all of the nodes in the Perseus Markdown AST. The callback is
- * called for each node in the AST.
- */
-const traverseContent = (ast: $FlowFixMe, cb: ($FlowFixMe) => mixed) => {
-    if (_.isArray(ast)) {
-        _.each(ast, (node) => traverseContent(node, cb));
-    } else if (_.isObject(ast)) {
-        cb(ast);
-        if (ast.type === "table") {
-            traverseContent(ast.header, cb);
-            traverseContent(ast.cells, cb);
-        } else if (ast.type === "list") {
-            traverseContent(ast.items, cb);
-        } else if (ast.type === "titledTable") {
-            traverseContent(ast.table, cb);
-        } else if (ast.type === "columns") {
-            traverseContent(ast.col1, cb);
-            traverseContent(ast.col2, cb);
-        } else if (_.isArray(ast.content)) {
-            traverseContent(ast.content, cb);
-        }
-    }
-};
-
-/**
- * Pull out text content from a Perseus Markdown AST.
- * Returns an array of strings.
- */
-const getContent = (ast) => {
-    // Simplify logic by dealing with a single AST node at a time
-    if (_.isArray(ast)) {
-        return _.flatten(_.map(ast, getContent));
-    }
-
-    // Base case: This is where we actually extract text content
-    if (ast.content && _.isString(ast.content)) {
-        // Collapse whitespace within content unless it is code
-        if (ast.type.toLowerCase().indexOf("code") !== -1) {
-            // In case this is the sole child of a paragraph,
-            // prevent whitespace from being trimmed later
-            return ["", ast.content, ""];
-        }
-        return [ast.content.replace(/\s+/g, " ")];
-    }
-
-    // Recurse through child AST nodes
-    // Assumptions made:
-    // 1) Child AST nodes are either direct properties or inside
-    //    arbitrarily nested lists that are direct properties.
-    // 2) Only AST nodes have a 'type' property.
-    const children = _.chain(ast)
-        .values()
-        .flatten()
-        .filter((object) => object != null && _.has(object, "type"))
-        .value();
-
-    if (!children.length) {
-        return [];
-    }
-    const nestedContent = getContent(children);
-    if (ast.type === "paragraph" && nestedContent.length) {
-        // Trim whitespace before or after a paragraph
-        nestedContent[0] = nestedContent[0].replace(/^\s+/, "");
-        const last = nestedContent.length - 1;
-        nestedContent[last] = nestedContent[last].replace(/\s+$/, "");
-    }
-    return nestedContent;
-};
-
-/**
- * Count the number of characters in Perseus Markdown source.
- * Markdown markup and widget references are ignored.
- */
-const characterCount = (source: string): number => {
-    const ast = parse(source);
-    const content = getContent(ast).join("");
-    return content.length;
-};
-
-export default {
-    characterCount: characterCount,
-    traverseContent: traverseContent,
-    parse: parse,
-    parseInline: inlineParser,
-    reactFor: SimpleMarkdown.reactFor,
-    // $FlowFixMe[incompatible-use]
-    ruleOutput: (SimpleMarkdown.ruleOutput(rules, "react"): $FlowFixMe),
-    basicOutput: (SimpleMarkdown.reactFor(
-        // $FlowFixMe[incompatible-use]
-        SimpleMarkdown.ruleOutput(rules, "react"),
-    ): $FlowFixMe),
-    sanitizeUrl: SimpleMarkdown.sanitizeUrl,
-};