@khanacademy/perseus 3.0.0 → 4.0.0

package/src/widgets/group.tsx

@@ -0,0 +1,196 @@
+import {linterContextDefault} from "@khanacademy/perseus-linter";
+import classNames from "classnames";
+import * as React from "react";
+
+import * as Changeable from "../mixins/changeable";
+import {ApiOptions} from "../perseus-api";
+import Renderer from "../renderer";
+
+import type {PerseusGroupWidgetOptions} from "../perseus-types";
+import type {Widget} from "../renderer";
+import type {
+    APIOptions,
+    ChangeFn,
+    FocusPath,
+    PerseusScore,
+    WidgetExports,
+    WidgetProps,
+} from "../types";
+
+type Rubric = PerseusGroupWidgetOptions;
+type RenderProps = PerseusGroupWidgetOptions; // exports has no 'transform'
+type Props = WidgetProps<RenderProps, Rubric>;
+type DefaultProps = {
+    content: Props["content"];
+    widgets: Props["widgets"];
+    images: Props["images"];
+    linterContext: Props["linterContext"];
+};
+
+class Group extends React.Component<Props> {
+    rendererRef: Renderer | null | undefined;
+
+    static defaultProps: DefaultProps = {
+        content: "",
+        widgets: {},
+        images: {},
+        linterContext: linterContextDefault,
+    };
+
+    componentDidMount() {
+        // TODO(marcia): See comment in render method about our cyclical
+        // numbering scheme. We force another render so that we can annotate
+        // the group with the correct number.
+        this.forceUpdate();
+    }
+
+    change: ChangeFn = (...args) => {
+        return Changeable.change.apply(this, args);
+    };
+
+    getUserInput: () => any = () => {
+        return this.rendererRef?.getUserInput();
+    };
+
+    getSerializedState: () => any = () => {
+        return this.rendererRef?.getSerializedState();
+    };
+
+    restoreSerializedState: (arg1: any, arg2: any) => null = (
+        state,
+        callback,
+    ) => {
+        this.rendererRef?.restoreSerializedState(state, callback);
+        // Tell our renderer that we have no props to change
+        // (all our changes were in state):
+        return null;
+    };
+
+    simpleValidate: (arg1: Rubric) => PerseusScore | null | undefined = (
+        rubric,
+    ) => {
+        return this.rendererRef?.score();
+    };
+
+    // Mobile API:
+    getInputPaths: () => ReadonlyArray<FocusPath> | null | undefined = () => {
+        return this.rendererRef?.getInputPaths();
+    };
+
+    setInputValue: (
+        arg1: FocusPath,
+        arg2: string,
+        arg3: () => unknown,
+    ) => void = (path, newValue, callback) => {
+        return this.rendererRef?.setInputValue(path, newValue, callback);
+    };
+
+    focus: () => boolean | null | undefined = () => {
+        return this.rendererRef?.focus();
+    };
+
+    focusInputPath: (arg1: FocusPath) => void = (path) => {
+        this.rendererRef?.focusPath(path);
+    };
+
+    blurInputPath: (arg1: FocusPath) => void = (path) => {
+        this.rendererRef?.blurPath(path);
+    };
+
+    showRationalesForCurrentlySelectedChoices: () => void = () => {
+        this.rendererRef?.showRationalesForCurrentlySelectedChoices();
+    };
+
+    render(): React.ReactNode {
+        const apiOptions: APIOptions = {
+            ...ApiOptions.defaults,
+            ...this.props.apiOptions,
+            // Api Rewriting to support correct onFocus/onBlur
+            // events for the mobile API
+            onFocusChange: (newFocus, oldFocus) => {
+                if (oldFocus) {
+                    this.props.onBlur(oldFocus);
+                }
+                if (newFocus) {
+                    this.props.onFocus(newFocus);
+                }
+            },
+        };
+
+        // Allow a problem number annotation to be added.
+        // This is cyclical and should probably be reconsidered. In order to
+        // render the annotation ("Question 3 of 10"), we call findWidgets to
+        // figure out our index in the list of all fellow group widgets. On
+        // first render, though, we don't exist yet in this list, and so we
+        // give ourselves number -1. To combat this, we forceUpdate in
+        // componentDidMount so that we can number ourselves properly. But,
+        // really we should have a more unidirectional flow. TODO(marcia): fix.
+        const groupWidgets: ReadonlyArray<Widget> =
+            this.props.findWidgets("group");
+        // @ts-expect-error [FEI-5003] - TS2345 - Argument of type 'this' is not assignable to parameter of type 'Widget'.
+        const number: number = groupWidgets.indexOf(this);
+        const problemNumComponent = this.props.apiOptions.groupAnnotator(
+            number,
+            this.props.widgetId,
+        );
+
+        // This is a little strange because the id of the widget that actually
+        // changed is going to be lost in favor of the group widget's id. The
+        // widgets prop also wasn't actually changed, and this only serves to
+        // alert our renderer (our parent) of the fact that some interaction
+        // has occurred.
+        const onInteractWithWidget = (id) => {
+            if (this.rendererRef) {
+                this.change("widgets", this.rendererRef.props.widgets);
+            }
+        };
+
+        const score = this.rendererRef?.score();
+        const isValid = score && score.type !== "invalid";
+        const isInvalid = score && score.type === "invalid";
+
+        // TODO(mdr): Widgets inside this Renderer are not discoverable through
+        //     the parent Renderer's `findWidgets` function.
+        return (
+            <div
+                className={classNames({
+                    "perseus-group": true,
+                    "perseus-group-valid-answer": isValid,
+                    "perseus-group-invalid-answer": isInvalid,
+                })}
+            >
+                {problemNumComponent}
+                <Renderer
+                    content={this.props.content}
+                    widgets={this.props.widgets}
+                    images={this.props.images}
+                    ref={(ref) => (this.rendererRef = ref)}
+                    apiOptions={apiOptions}
+                    findExternalWidgets={this.props.findWidgets}
+                    reviewMode={!!this.props.reviewModeRubric}
+                    onInteractWithWidget={onInteractWithWidget}
+                    linterContext={this.props.linterContext}
+                />
+                {/* $FlowFixMe[prop-missing] */}
+                {/* @ts-expect-error [FEI-5003] - TS2339 - Property 'icon' does not exist on type 'Readonly<Props> & Readonly<{ children?: ReactNode; }>'. */}
+                {this.props.icon && (
+                    // @ts-expect-error [FEI-5003] - TS2339 - Property 'icon' does not exist on type 'Readonly<Props> & Readonly<{ children?: ReactNode; }>'.
+                    <div className="group-icon">{this.props.icon}</div>
+                )}
+            </div>
+        );
+    }
+}
+
+const traverseChildWidgets = function (props: any, traverseRenderer: any): any {
+    return {...props, ...traverseRenderer(props)};
+};
+
+export default {
+    name: "group",
+    displayName: "Group (SAT only)",
+    widget: Group,
+    traverseChildWidgets: traverseChildWidgets,
+    hidden: false,
+    isLintable: true,
+} as WidgetExports<typeof Group>;

package/src/widgets/iframe.tsx

@@ -0,0 +1,195 @@
+/* eslint-disable react/forbid-prop-types, react/sort-comp */
+/**
+ * This is an iframe widget. It is used for rendering an iframe that
+ *  then communicates its state via window.postMessage
+ * This is useful for embedding arbitrary visualizations/simulations with
+ *  completed conditions, such as the mazes and games in Algorithms.
+ * It's particularly well suited for embedding our ProcessingJS programs,
+ *  but could also be used for embedding viz's hosted elsewhere.
+ */
+
+import $ from "jquery";
+import PropTypes from "prop-types";
+import * as React from "react";
+import _ from "underscore";
+
+import {getDependencies} from "../dependencies";
+import * as Changeable from "../mixins/changeable";
+import WidgetJsonifyDeprecated from "../mixins/widget-jsonify-deprecated";
+import Util from "../util";
+
+import type {WidgetExports} from "../types";
+
+const {updateQueryString} = Util;
+
+/* This renders the iframe and handles validation via window.postMessage */
+class Iframe extends React.Component<any> {
+    static propTypes = {
+        ...Changeable.propTypes,
+        width: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+        height: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+        url: PropTypes.string,
+        settings: PropTypes.array,
+        status: PropTypes.oneOf(["incomplete", "incorrect", "correct"]),
+        message: PropTypes.string,
+        allowFullScreen: PropTypes.bool,
+        allowTopNavigation: PropTypes.bool,
+    };
+
+    static defaultProps: any = {
+        status: "incomplete",
+        // optional message
+        message: null,
+        allowFullScreen: false,
+        allowTopNavigation: false,
+    };
+
+    getUserInput: () => any = () => {
+        return WidgetJsonifyDeprecated.getUserInput.call(this);
+    };
+
+    handleMessageEvent: (arg1: any) => void = (e) => {
+        // We receive data from the iframe that contains {passed: true/false}
+        //  and use that to set the status
+        // It could also contain an optional message
+        let data: Record<string, any> = {};
+        try {
+            data = JSON.parse(e.originalEvent.data);
+        } catch (err: any) {
+            return;
+        }
+
+        if (_.isUndefined(data.testsPassed)) {
+            return;
+        }
+
+        const status = data.testsPassed ? "correct" : "incorrect";
+        this.change({
+            status: status,
+            message: data.message,
+        });
+    };
+
+    componentDidMount() {
+        $(window).on("message", this.handleMessageEvent);
+    }
+
+    componentWillUnmount() {
+        $(window).off("message", this.handleMessageEvent);
+    }
+
+    render(): React.ReactNode {
+        const style = {
+            width: String(this.props.width),
+            height: String(this.props.height),
+        } as const;
+
+        const {InitialRequestUrl} = getDependencies();
+
+        // Add "px" to unitless numbers
+        Object.entries(style).forEach(([key, value]: [any, any]) => {
+            if (!value.endsWith("%") && !value.endsWith("px")) {
+                style[key] = value + "px";
+            }
+        });
+
+        let url = this.props.url;
+
+        // If the URL doesnt start with http, it must be a program ID
+        if (url && url.length && url.indexOf("http") !== 0) {
+            url =
+                "https://www.khanacademy.org/computer-programming/program/" +
+                url +
+                "/embedded?buttons=no&embed=yes&editor=no&author=no";
+            url = updateQueryString(url, "width", this.props.width);
+            url = updateQueryString(url, "height", this.props.height);
+            // Origin is used by output.js in deciding to send messages
+            url = updateQueryString(url, "origin", InitialRequestUrl.origin);
+        }
+
+        // Turn array of [{name: "", value: ""}] into object
+        if (this.props.settings) {
+            const settings: Record<string, any> = {};
+            _.each(this.props.settings, function (setting) {
+                if (setting.name && setting.value) {
+                    settings[setting.name] = setting.value;
+                }
+            });
+            // This becomes available to programs as Program.settings()
+            url = updateQueryString(url, "settings", JSON.stringify(settings));
+        }
+
+        let sandboxProperties = "allow-same-origin allow-scripts";
+        // TODO(scottgrant): This line is an intentional hack to retain the
+        // allow-top-navigation sandbox property. Once our LearnStorm articles
+        // have this value checked and published, this line should be removed
+        // and replaced with the conditional check below that is commented out.
+        // We don't want to break LearnStorm badges, so this will be a two-part
+        // deploy.
+        sandboxProperties += " allow-top-navigation";
+        // if (this.props.allowTopNavigation === true) {
+        //     sandboxProperties += " allow-top-navigation";
+        // }
+
+        // We sandbox the iframe so that we allowlist only the functionality
+        //  that we need. This makes it a bit safer in case some content
+        //  creator "went wild".
+        // http://www.html5rocks.com/en/tutorials/security/sandboxed-iframes/
+        return (
+            <iframe
+                sandbox={sandboxProperties}
+                style={style}
+                src={url}
+                allowFullScreen={this.props.allowFullScreen}
+            />
+        );
+    }
+
+    change: (...args: ReadonlyArray<unknown>) => any = (...args) => {
+        // @ts-expect-error [FEI-5003] - TS2345 - Argument of type 'readonly unknown[]' is not assignable to parameter of type 'any[]'.
+        return Changeable.change.apply(this, args);
+    };
+
+    simpleValidate: (arg1: any) => any = (rubric) => {
+        // @ts-expect-error [FEI-5003] - TS2339 - Property 'validate' does not exist on type 'typeof Iframe'.
+        return Iframe.validate(this.getUserInput(), rubric);
+    };
+}
+
+/**
+ * This is the widget's grading function
+ */
+_.extend(Iframe, {
+    validate: function (state, rubric) {
+        // The iframe can tell us whether it's correct or incorrect,
+        //  and pass an optional message
+        if (state.status === "correct") {
+            return {
+                type: "points",
+                earned: 1,
+                total: 1,
+                message: state.message || null,
+            };
+        }
+        if (state.status === "incorrect") {
+            return {
+                type: "points",
+                earned: 0,
+                total: 1,
+                message: state.message || null,
+            };
+        }
+        return {
+            type: "invalid",
+            message: "Keep going, you're not there yet!",
+        };
+    },
+});
+
+export default {
+    name: "iframe",
+    displayName: "Iframe",
+    widget: Iframe,
+    // Let's not expose it to all content creators yet
+    hidden: true,
+} as WidgetExports<typeof Iframe>;

package/src/widgets/image.tsx

@@ -0,0 +1,309 @@
+/* eslint-disable react/prop-types */
+/* eslint-disable react/sort-comp */
+import {linterContextDefault} from "@khanacademy/perseus-linter";
+import {StyleSheet, css} from "aphrodite";
+import classNames from "classnames";
+import * as React from "react";
+import _ from "underscore";
+
+import SvgImage from "../components/svg-image";
+import * as Changeable from "../mixins/changeable";
+import Renderer from "../renderer";
+import {baseUnitPx} from "../styles/constants";
+import mediaQueries from "../styles/media-queries";
+
+import type {PerseusImageWidgetOptions} from "../perseus-types";
+import type {
+    ChangeFn,
+    PerseusScore,
+    WidgetExports,
+    WidgetProps,
+} from "../types";
+
+const defaultBoxSize = 400;
+const defaultRange = [0, 10];
+const defaultBackgroundImage = {
+    url: null,
+    width: 0,
+    height: 0,
+} as const;
+
+const editorAlignments = ["block", "full-width"];
+
+const DEFAULT_ALIGNMENT = "block";
+
+type RenderProps = PerseusImageWidgetOptions; // there is no transform as part of exports
+type Rubric = PerseusImageWidgetOptions;
+type UserInput = null;
+
+type ExternalProps = WidgetProps<RenderProps, Rubric>;
+
+type Props = ExternalProps & {
+    alignment: NonNullable<ExternalProps["alignment"]>;
+    title: NonNullable<ExternalProps["title"]>;
+    range: NonNullable<ExternalProps["range"]>;
+    box: NonNullable<ExternalProps["box"]>;
+    backgroundImage: NonNullable<ExternalProps["backgroundImage"]>;
+    labels: NonNullable<ExternalProps["labels"]>;
+    alt: NonNullable<ExternalProps["alt"]>;
+    caption: NonNullable<ExternalProps["caption"]>;
+    linterContext: NonNullable<ExternalProps["linterContext"]>;
+};
+
+type DefaultProps = {
+    alignment: Props["alignment"];
+    title: Props["title"];
+    range: Props["range"];
+    box: Props["box"];
+    backgroundImage: Props["backgroundImage"];
+    labels: Props["labels"];
+    alt: Props["alt"];
+    caption: Props["caption"];
+    linterContext: Props["linterContext"];
+};
+
+class ImageWidget extends React.Component<Props> {
+    static defaultProps: DefaultProps = {
+        alignment: DEFAULT_ALIGNMENT,
+        title: "",
+        range: [defaultRange, defaultRange],
+        box: [defaultBoxSize, defaultBoxSize],
+        backgroundImage: defaultBackgroundImage,
+        labels: [],
+        alt: "",
+        caption: "",
+        linterContext: linterContextDefault,
+    };
+
+    change: ChangeFn = (...args) => {
+        return Changeable.change.apply(this, args);
+    };
+
+    getUserInput: () => UserInput = () => {
+        return null;
+    };
+
+    simpleValidate: (arg1: Rubric) => PerseusScore = (rubric) => {
+        return ImageWidget.validate(this.getUserInput(), rubric);
+    };
+
+    focus: () => void = () => {}; // no-op
+
+    render(): React.ReactNode {
+        let image;
+        let alt;
+        const {apiOptions} = this.props;
+
+        const backgroundImage = this.props.backgroundImage;
+
+        if (backgroundImage.url) {
+            image = (
+                <SvgImage
+                    src={backgroundImage.url}
+                    alt={
+                        /* alt text is formatted in a sr-only
+                               div next to the image in addition to
+                               the alt attribute.
+                               If there is no alt text at all,
+                               we don't put an alt attribute on
+                               the image, so that screen readers
+                               know there's something they can't
+                               read there :(.
+                               NOTE: React <=0.13 (maybe later)
+                               has a bug where it won't ever
+                               remove an attribute, so if this
+                               alt node is ever defined it's
+                               not removed. This is sort of
+                               dangerous, but we usually re-key
+                               new renderers so that they're
+                               rendered from scratch anyways,
+                               so this shouldn't be a problem
+                               in practice right now, although
+                               it will exhibit weird behaviour
+                               while editing. */
+                        this.props.alt
+                    }
+                    overrideAriaHidden={true}
+                    width={backgroundImage.width}
+                    height={backgroundImage.height}
+                    preloader={apiOptions.imagePreloader}
+                    extraGraphie={{
+                        box: this.props.box,
+                        range: this.props.range,
+                        labels: this.props.labels,
+                    }}
+                    trackInteraction={this.props.trackInteraction}
+                    zoomToFullSizeOnMobile={apiOptions.isMobile}
+                    constrainHeight={apiOptions.isMobile}
+                    allowFullBleed={apiOptions.isMobile}
+                />
+            );
+        }
+
+        if (this.props.alt) {
+            alt = (
+                <span className="perseus-sr-only">
+                    <Renderer
+                        content={this.props.alt}
+                        apiOptions={apiOptions}
+                        linterContext={this.props.linterContext}
+                    />
+                </span>
+            );
+        }
+
+        // For mobile we combine an image's title and caption.
+        if (apiOptions.isMobile) {
+            let titleAndCaption;
+
+            if (this.props.title || this.props.caption) {
+                let title = this.props.title;
+
+                // Bold the title, and make it the first sentence of the
+                // caption.
+                if (title) {
+                    // We add a period to separate the title from the caption
+                    // (if it exists), unless the title already ends with a
+                    // punctuation symbol (whitespace ignored). Copied from
+                    // webapp: https://github.com/Khan/webapp/blob/6e930637edb65696d0749ea0f7558214aee32b4e/javascript/tutorial-shared-package/components/content-description.jsx#L80
+                    // TODO(charlie): Internationalize this check, and the
+                    // delimiter that is being inserted.
+                    if (this.props.caption && !/[.?!"']\s*$/.test(title)) {
+                        title += ".";
+                    }
+
+                    title = `**${title}** `;
+                }
+
+                const className = classNames({
+                    "perseus-image-caption": true,
+                    "has-title": !!title,
+                });
+
+                // Caption is left-aligned within a container that's centered
+                // below the image, with these width constraints:
+                //
+                // 1. Size caption to width of the image on-screen.
+                // 2. ... but constrain its width to a range based on the
+                //    device to optimize readability - e.g. [320px, 450px] for
+                //    phones.
+                // 3. ... unless the image is floated, in which case we don't
+                //    want the caption to overflow the image size.
+                //
+                // TODO(david): If caption is only 1 line long, center-align
+                //     the text.
+                const alignment = this.props.alignment;
+                const isImageFullWidth =
+                    alignment === "block" || alignment === "full-width";
+
+                // This minWidth takes precedence over minWidth applied via
+                // Aphrodite.
+                const minWidth = isImageFullWidth ? null : "0 !important";
+
+                titleAndCaption = (
+                    <div className={className}>
+                        <div
+                            className={css(styles.caption)}
+                            style={{
+                                // @ts-expect-error [FEI-5003] - TS2322 - Type 'string | null' is not assignable to type 'MinWidth<string | number> | undefined'.
+                                minWidth: minWidth,
+                            }}
+                        >
+                            <Renderer
+                                content={title + this.props.caption}
+                                apiOptions={apiOptions}
+                                linterContext={this.props.linterContext}
+                            />
+                        </div>
+                    </div>
+                );
+            }
+
+            return (
+                <div className="perseus-image-widget">
+                    {image}
+                    {alt}
+                    {titleAndCaption}
+                </div>
+            );
+        }
+        let title;
+        let caption;
+
+        if (this.props.title) {
+            title = (
+                <div className="perseus-image-title">
+                    <Renderer
+                        content={this.props.title}
+                        apiOptions={apiOptions}
+                        linterContext={this.props.linterContext}
+                    />
+                </div>
+            );
+        }
+
+        if (this.props.caption) {
+            caption = (
+                <div className="perseus-image-caption">
+                    <Renderer
+                        content={this.props.caption}
+                        apiOptions={apiOptions}
+                        linterContext={this.props.linterContext}
+                    />
+                </div>
+            );
+        }
+
+        return (
+            <div className="perseus-image-widget">
+                {title}
+                {image}
+                {alt}
+                {caption}
+            </div>
+        );
+    }
+
+    static validate(userInput: UserInput, rubric: Rubric): PerseusScore {
+        return {
+            type: "points",
+            earned: 0,
+            total: 0,
+            message: null,
+        };
+    }
+}
+
+const styles = StyleSheet.create({
+    caption: {
+        display: "inline-block",
+        marginTop: baseUnitPx,
+        maxWidth: 640,
+
+        [mediaQueries.lgOrSmaller]: {
+            // TODO(david): This maxWidth is not being used because
+            //     it's overriden by the 512px max-width we have on
+            //     paragraphs.
+            maxWidth: 540,
+        },
+
+        [mediaQueries.smOrSmaller]: {
+            maxWidth: 450,
+        },
+    },
+});
+
+export default {
+    name: "image",
+    // This widget's accessibility depends on its contents: if the image has
+    // has a background but no alt text, it is not accessible
+    accessible: (widgetOptions: PerseusImageWidgetOptions): boolean => {
+        const bgImage = widgetOptions.backgroundImage;
+        return !(bgImage && bgImage.url && !widgetOptions.alt);
+    },
+    defaultAlignment: DEFAULT_ALIGNMENT,
+    supportedAlignments: editorAlignments,
+    displayName: "Image",
+    widget: ImageWidget,
+    isLintable: true,
+} as WidgetExports<typeof ImageWidget>;