@khanacademy/perseus 2.1.0 → 4.0.0

package/src/widgets/video.tsx

@@ -0,0 +1,124 @@
+/**
+ * This is a video widget for embedding videos in articles.
+ */
+
+import {View} from "@khanacademy/wonder-blocks-core";
+import * as i18n from "@khanacademy/wonder-blocks-i18n";
+import * as React from "react";
+import _ from "underscore";
+
+import FixedToResponsive from "../components/fixed-to-responsive";
+import {getDependencies} from "../dependencies";
+import * as Changeable from "../mixins/changeable";
+import a11y from "../util/a11y";
+
+import VideoTranscriptLink from "./video-transcript-link";
+
+import type {PerseusVideoWidgetOptions} from "../perseus-types";
+import type {PerseusScore, WidgetExports, WidgetProps} from "../types";
+
+// Current default is 720p, based on the typical videos we upload currently
+const DEFAULT_WIDTH = 1280;
+const DEFAULT_HEIGHT = 720;
+
+const KA_EMBED = "{host}/embed_video?slug={slug}" + "&internal_video_only=1";
+const IS_URL = /^https?:\/\//;
+const IS_KA_SITE = /(khanacademy\.org|localhost)/;
+
+type UserInput = null;
+type Rubric = PerseusVideoWidgetOptions;
+type RenderProps = PerseusVideoWidgetOptions; // exports has no 'transform'
+type Props = WidgetProps<RenderProps, Rubric> & {
+    alignment: string; // Where does this get set?
+};
+
+/**
+ * Video renderer.
+ */
+class Video extends React.Component<Props> {
+    /**
+     * This is the widget's grading function.
+     * Points for videos are tallied by the embedded video itself, in the case
+     * of Khan Academy videos.
+     */
+    static validate(userInput: UserInput, rubric: Rubric): PerseusScore {
+        return {
+            type: "points",
+            earned: 0,
+            total: 0,
+            message: null,
+        };
+    }
+
+    getUserInput: () => undefined | null | undefined = () => {
+        return null;
+    };
+
+    simpleValidate: (arg1: Rubric) => PerseusScore = (rubric) => {
+        return Video.validate(null, rubric);
+    };
+
+    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);
+    };
+
+    render(): React.ReactNode {
+        const {InitialRequestUrl} = getDependencies();
+
+        const location = this.props.location;
+        if (!location) {
+            return <div />;
+        }
+
+        let url;
+
+        if (IS_URL.test(location)) {
+            url = location;
+        } else {
+            url = KA_EMBED.replace("{slug}", location);
+            let embedHostname = "https://www.khanacademy.org";
+            if (IS_KA_SITE.test(InitialRequestUrl.host)) {
+                embedHostname = InitialRequestUrl.origin;
+            }
+            url = url.replace("{host}", embedHostname);
+        }
+
+        return (
+            <View>
+                <FixedToResponsive
+                    width={DEFAULT_WIDTH}
+                    height={DEFAULT_HEIGHT}
+                    // The key is here for the benefit of the editor, to ensure that
+                    // any changes cause a re-rendering of the frame.
+                    key={location + this.props.alignment}
+                >
+                    <View style={a11y.srOnly}>
+                        {i18n._("Khan Academy video wrapper")}
+                    </View>
+
+                    <iframe
+                        // TODO(joshuan): Consider not using iframes when we're
+                        // loading this from webapp. This iframe is problematic
+                        // for screenreaders.
+                        className="perseus-video-widget"
+                        sandbox="allow-same-origin allow-scripts"
+                        width={DEFAULT_WIDTH}
+                        height={DEFAULT_HEIGHT}
+                        src={url}
+                        allowFullScreen={true}
+                    />
+                </FixedToResponsive>
+                <VideoTranscriptLink location={location} />
+            </View>
+        );
+    }
+}
+
+export default {
+    name: "video",
+    displayName: "Video",
+    defaultAlignment: "block",
+    supportedAlignments: ["block", "float-left", "float-right", "full-width"],
+    widget: Video,
+} as WidgetExports<typeof Video>;

package/src/widgets.ts

@@ -0,0 +1,444 @@
+import * as React from "react";
+import _ from "underscore";
+
+import {Errors, Log} from "./logging/log";
+import {PerseusError} from "./perseus-error";
+
+import type {
+    Alignment,
+    Tracking,
+    Version,
+    WidgetExports,
+    WidgetInfo,
+    WidgetTransform,
+} from "./types";
+
+const DEFAULT_ALIGNMENT = "block";
+// NOTE(kevinb): "default" is not one in `validAlignments`.
+const DEFAULT_SUPPORTED_ALIGNMENTS = ["default"];
+const DEFAULT_STATIC = false;
+const DEFAULT_TRACKING = "";
+const DEFAULT_LINTABLE = false;
+
+type Editor = any;
+
+const widgets: {
+    [key: string]: WidgetExports;
+} = {};
+const editors: Record<string, any> = {};
+
+// Widgets must be registered to avoid circular dependencies with the
+// core Editor and Renderer components.
+// TODO(jeremy): The widget name is already embedded in the WidgetExports type
+// so could we drop the `name` parameter here?
+export const registerWidget = (name: string, widget: WidgetExports) => {
+    widgets[name] = widget;
+};
+
+export const registerWidgets = (widgets: ReadonlyArray<WidgetExports>) => {
+    widgets.forEach((widget) => {
+        registerWidget(widget.name, widget);
+    });
+
+    validateAlignments();
+};
+
+export const registerEditors = (editorsToRegister: ReadonlyArray<Editor>) => {
+    editorsToRegister.forEach((editor) => {
+        if (!editor.widgetName) {
+            throw new PerseusError(
+                `Editor ${editor.displayName} doesn't have a widgetName property`,
+                Errors.Internal,
+            );
+        }
+        editors[editor.widgetName] = editor;
+    });
+};
+
+export const getWidget = (
+    name: string,
+): React.ComponentType<any> | null | undefined => {
+    // TODO(alex): Consider referring to these as renderers to avoid
+    // overloading "widget"
+    if (!_.has(widgets, name)) {
+        return null;
+    }
+
+    // Allow widgets to specify a widget directly or via a function
+    if (widgets[name].getWidget) {
+        // @ts-expect-error [FEI-5003] - TS2722 - Cannot invoke an object which is possibly 'undefined'.
+        return widgets[name].getWidget();
+    }
+    return widgets[name].widget;
+};
+
+export const getEditor = (name: string): Editor | null | undefined => {
+    return _.has(editors, name) ? editors[name] : null;
+};
+
+export const getTransform = (
+    name: string,
+): WidgetTransform | null | undefined => {
+    return _.has(widgets, name) ? widgets[name].transform || _.identity : null;
+};
+
+export const getVersion = (name: string): Version | null | undefined => {
+    const widgetInfo = widgets[name];
+    if (widgetInfo) {
+        return widgets[name].version || {major: 0, minor: 0};
+    }
+    return null;
+};
+
+export const getVersionVector = (): {
+    [key: string]: Version;
+} => {
+    const version: Record<string, any> = {};
+    _.each(_.keys(widgets), function (name) {
+        version[name] = getVersion(name);
+    });
+    return version;
+};
+
+export const getPublicWidgets = (): ReadonlyArray<WidgetExports> => {
+    // TODO(alex): Update underscore.js so that _.pick can take a function.
+    // @ts-expect-error [FEI-5003] - TS2740 - Type 'Pick<{ [key: string]: Readonly<{ name: string; displayName: string; getWidget?: (() => ComponentType<any>) | undefined; accessible?: boolean | ((props: any) => boolean) | undefined; hidden?: boolean | undefined; ... 10 more ...; widget: ComponentType<...>; }>; }, string>' is missing the following properties from type 'readonly Readonly<{ name: string; displayName: string; getWidget?: (() => ComponentType<any>) | undefined; accessible?: boolean | ((props: any) => boolean) | undefined; hidden?: boolean | undefined; ... 10 more ...; widget: ComponentType<...>; }>[]': length, concat, join, slice, and 18 more.
+    return _.pick(
+        widgets,
+        // @ts-expect-error [FEI-5003] - TS2345 - Argument of type '(name: string) => boolean | undefined' is not assignable to parameter of type 'Iteratee<string[], boolean, string>'.
+        _.reject(_.keys(widgets), function (name) {
+            return widgets[name].hidden;
+        }),
+    );
+};
+
+export const isAccessible = (widgetInfo: WidgetInfo): boolean => {
+    const accessible = widgets[widgetInfo.type].accessible;
+    if (typeof accessible === "function") {
+        return accessible(widgetInfo.options);
+    }
+    return !!accessible;
+};
+
+export const getAllWidgetTypes = (): ReadonlyArray<string> => {
+    return _.keys(widgets);
+};
+
+export const upgradeWidgetInfoToLatestVersion = (
+    oldWidgetInfo: WidgetInfo,
+): WidgetInfo => {
+    const type = oldWidgetInfo.type;
+    // TODO(LP-10707): Remove unnecessary type checking (`type` is a string)
+    if (!_.isString(type)) {
+        throw new PerseusError(
+            "widget type must be a string, but was: " + type,
+            Errors.Internal,
+        );
+    }
+    const widgetExports = widgets[type];
+
+    if (widgetExports == null) {
+        // If we have a widget that isn't registered, we can't upgrade it
+        // TODO(aria): Figure out what the best thing to do here would be
+        return oldWidgetInfo;
+    }
+
+    // Unversioned widgets (pre-July 2014) are all implicitly 0.0
+    const initialVersion = oldWidgetInfo.version || {major: 0, minor: 0};
+    const latestVersion = widgetExports.version || {major: 0, minor: 0};
+
+    // If the widget version is later than what we understand (major
+    // version is higher than latest, or major versions are equal and minor
+    // version is higher than latest), don't perform any upgrades.
+    if (
+        initialVersion.major > latestVersion.major ||
+        (initialVersion.major === latestVersion.major &&
+            initialVersion.minor > latestVersion.minor)
+    ) {
+        return oldWidgetInfo;
+    }
+
+    // We do a clone here so that it's safe to mutate the input parameter
+    // in propUpgrades functions (which I will probably accidentally do at
+    // some point, and we would like to not break when that happens).
+    let newEditorProps = _.clone(oldWidgetInfo.options) || {};
+
+    const upgradePropsMap = widgetExports.propUpgrades || {};
+
+    // Empty props usually mean a newly created widget by the editor,
+    // and are always considerered up-to-date.
+    // Mostly, we'd rather not run upgrade functions on props that are
+    // not complete.
+    if (_.keys(newEditorProps).length !== 0) {
+        // We loop through all the versions after the current version of
+        // the loaded widget, up to and including the latest version of the
+        // loaded widget, and run the upgrade function to bring our loaded
+        // widget's props up to that version.
+        // There is a little subtlety here in that we call
+        // upgradePropsMap[1] to upgrade *to* version 1,
+        // (not from version 1).
+        for (
+            let nextVersion = initialVersion.major + 1;
+            nextVersion <= latestVersion.major;
+            nextVersion++
+        ) {
+            if (upgradePropsMap[String(nextVersion)]) {
+                newEditorProps =
+                    upgradePropsMap[String(nextVersion)](newEditorProps);
+            } else {
+                // This is a Log.error because it is unlikely to be hit in
+                // local testing, and a Log.error is slightly less scary in
+                // prod than a `throw new Error`
+                Log.error(
+                    "No upgrade found for widget. Cannot render.",
+                    Errors.Internal,
+                    {
+                        loggedMetadata: {
+                            type,
+                            fromMajorVersion: nextVersion - 1,
+                            toMajorVersion: nextVersion,
+                        },
+                    },
+                );
+                // But try to keep going anyways (yolo!)
+                // (Throwing an error here would just break the page
+                // silently anyways, so that doesn't seem much better
+                // than a halfhearted attempt to continue, however
+                // shallow...)
+            }
+        }
+    }
+
+    // Minor version upgrades (eg. new optional props) don't have
+    // transform functions. Instead, we fill in the new props with their
+    // defaults.
+    const defaultProps = type in editors ? editors[type].defaultProps : {};
+    newEditorProps = {
+        ...defaultProps,
+        ...newEditorProps,
+    };
+
+    let alignment = oldWidgetInfo.alignment;
+
+    // Widgets that support multiple alignments will "lock in" the
+    // alignment to the alignment that would be listed first in the
+    // select box. If the widget only supports one alignment, the
+    // alignment value will likely just end up as "default".
+    if (alignment == null || alignment === "default") {
+        alignment = getSupportedAlignments(type)[0];
+    }
+
+    let widgetStatic = oldWidgetInfo.static;
+
+    if (widgetStatic == null) {
+        widgetStatic = DEFAULT_STATIC;
+    }
+
+    return _.extend({}, oldWidgetInfo, {
+        // maintain other info, like type
+        // After upgrading we guarantee that the version is up-to-date
+        version: latestVersion,
+        // Default graded to true (so null/undefined becomes true):
+        graded: oldWidgetInfo.graded != null ? oldWidgetInfo.graded : true,
+        alignment: alignment,
+        static: widgetStatic,
+        options: newEditorProps,
+    });
+};
+
+export const getRendererPropsForWidgetInfo = (
+    widgetInfo: WidgetInfo,
+    problemNum?: number,
+): any => {
+    const type = widgetInfo.type;
+    const widgetExports = widgets[type];
+    if (widgetExports == null) {
+        // The widget is not a registered widget
+        // It shouldn't matter what we return here, but for consistency
+        // we return the untransformed options, as if the widget did
+        // not have a transform defined.
+        return widgetInfo.options;
+    }
+    let transform;
+    if (widgetInfo.static) {
+        // There aren't a lot of real places where we'll have to default to
+        // _.identity, but it's theoretically possible if someone changes
+        // the JSON manually / we have to back out static support for a
+        // widget.
+        transform = getStaticTransform(type) || _.identity;
+    } else {
+        transform = widgetExports.transform || _.identity;
+    }
+    // widgetInfo.options are the widgetEditor's props:
+    return transform(widgetInfo.options, problemNum);
+};
+
+export const traverseChildWidgets = (
+    widgetInfo: WidgetInfo,
+    traverseRenderer: any,
+): WidgetInfo => {
+    if (!traverseRenderer) {
+        throw new PerseusError(
+            "traverseRenderer must be provided, but was not",
+            Errors.Internal,
+        );
+    }
+
+    if (!widgetInfo || !widgetInfo.type || !widgets[widgetInfo.type]) {
+        return widgetInfo;
+    }
+
+    const widgetExports = widgets[widgetInfo.type];
+    const props = widgetInfo.options;
+
+    if (widgetExports.traverseChildWidgets && props) {
+        const newProps = widgetExports.traverseChildWidgets(
+            props,
+            traverseRenderer,
+        );
+        return _.extend({}, widgetInfo, {options: newProps});
+    }
+    return widgetInfo;
+};
+
+/**
+ * Handling for the optional alignments for widgets
+ * See widget-container.jsx for details on how alignments are implemented.
+ */
+
+/**
+ * Returns the list of supported alignments for the given (string) widget
+ * type. This is used primarily at editing time to display the choices
+ * for the user.
+ *
+ * Supported alignments are given as an array of strings in the exports of
+ * a widget's module.
+ */
+export const getSupportedAlignments = (
+    type: string,
+): ReadonlyArray<Alignment> => {
+    const widgetExport = widgets[type];
+    // @ts-expect-error [FEI-5003] - TS2322 - Type 'string[] | readonly Alignment[]' is not assignable to type 'readonly Alignment[]'.
+    return (
+        (widgetExport && widgetExport.supportedAlignments) ||
+        DEFAULT_SUPPORTED_ALIGNMENTS
+    );
+};
+
+/**
+ * For the given (string) widget type, determine the default alignment for
+ * the widget. This is used at rendering time to go from "default" alignment
+ * to the actual alignment displayed on the screen.
+ *
+ * The default alignment is given either as a string (called
+ * `defaultAlignment`) or a function (called `getDefaultAlignment`) on
+ * the exports of a widget's module.
+ */
+export const getDefaultAlignment = (type: string): Alignment => {
+    const widgetExports = widgets[type];
+    let alignment;
+    if (!widgetExports) {
+        return DEFAULT_ALIGNMENT;
+    }
+
+    if (widgetExports.getDefaultAlignment) {
+        alignment = widgetExports.getDefaultAlignment();
+    } else {
+        alignment = widgetExports.defaultAlignment;
+    }
+    return alignment || DEFAULT_ALIGNMENT;
+};
+
+const validAlignments: ReadonlyArray<Alignment> = [
+    "block",
+    "inline-block",
+    "inline",
+    "float-left",
+    "float-right",
+    "full-width",
+];
+
+/**
+ * Used at startup to fail fast if an alignment given by a widget is
+ * invalid.
+ */
+// TODO(alex): Change this to run as a testcase (vs. being run at runtime)
+// TODO(LP-10707): I think this can be completely removed because our Flow types
+// enforce this!
+export const validateAlignments = () => {
+    _.each(widgets, function (widgetInfo) {
+        if (
+            widgetInfo.defaultAlignment &&
+            !_.contains(validAlignments, widgetInfo.defaultAlignment)
+        ) {
+            throw new PerseusError(
+                "Widget '" +
+                    widgetInfo.displayName +
+                    "' has an invalid defaultAlignment value: " +
+                    widgetInfo.defaultAlignment,
+                Errors.InvalidInput,
+            );
+        }
+
+        if (widgetInfo.supportedAlignments) {
+            const unknownAlignments = _.difference(
+                widgetInfo.supportedAlignments,
+                validAlignments,
+            );
+
+            if (unknownAlignments.length) {
+                throw new PerseusError(
+                    "Widget '" +
+                        widgetInfo.displayName +
+                        "' has an invalid value for supportedAlignments: " +
+                        unknownAlignments.join(" "),
+                    Errors.InvalidInput,
+                );
+            }
+        }
+    });
+};
+
+/**
+ * Handling for static mode for widgets that support it.
+ */
+
+/**
+ * Returns true iff the widget supports static mode.
+ * A widget implicitly supports static mode if it exports a
+ * staticTransform function.
+ */
+export const supportsStaticMode = (type: string): boolean => {
+    const widgetInfo = widgets[type];
+    return widgetInfo && widgetInfo.staticTransform != null;
+};
+
+/**
+ * Return the staticTransform function used to convert the editorProps to
+ * the rendered widget state.
+ */
+export const getStaticTransform = (
+    type: string,
+): WidgetTransform | null | undefined => {
+    const widgetInfo = widgets[type];
+    return widgetInfo && widgetInfo.staticTransform;
+};
+
+/**
+ * Returns the tracking option for the widget. The default is "",
+ * which means simply to track interactions once. The other available
+ * option is "all" which means to track all interactions.
+ */
+export const getTracking = (type: string): Tracking => {
+    const widgetExport = widgets[type];
+    return (widgetExport && widgetExport.tracking) || DEFAULT_TRACKING;
+};
+
+/**
+ * Returns true if this widget can include lintable markdown text
+ * and supports a highlightLint prop, or false otherwise.
+ */
+export const isLintable = (type: string): boolean => {
+    const widgetExports = widgets[type];
+    return (widgetExports && widgetExports.isLintable) || DEFAULT_LINTABLE;
+};