@khanacademy/perseus 0.0.1 → 0.2.1

package/src/multi-items/multi-renderer.jsx

@@ -0,0 +1,543 @@
+/* eslint-disable react/no-unsafe */
+// TODO(mdr): There are some Flow errors in this file, and they're tricky, so
+//     I'm skipping Flow errors for now.
+// @flow
+/**
+ * Main entry point to the MultiRenderer render portion.
+ *
+ * This file exposes the `MultiRenderer` component which performs
+ * multi-rendering. To multi-render a question, pass in the content of the item
+ * to the `MultiRenderer` component as a props. Then, pass in a function which
+ * takes an object of renderers (in the same structure as the content), and
+ * return a render tree. The `MultiRenderer` component will allow you to
+ * combine scores, serialized state, etc. without having to manually call on
+ * each of the functions. It also handles inter-widgets requests between the
+ * different renderers.
+ *
+ * Example:
+ *
+ *   item = {_multi: {
+ *       left: <content data>,
+ *       right: [<content data>, <content data>],
+ *   }}
+ *   shape = shapes.shape({
+ *       left: shapes.content,
+ *       right: shapes.arrayOf(shapes.content),
+ *   })
+ *
+ *   <MultiRenderer item={item} shape={shape}>
+ *       {({renderers}) =>
+ *           <div>
+ *               <div id="left">{renderers.left}</div>
+ *               <ul id="right">
+ *                   {renderers.right.map(r => <li>{r}</li>)}
+ *               </ul>
+ *           </div>
+ *       }
+ *   </MultiRenderer>
+ */
+import * as i18n from "@khanacademy/wonder-blocks-i18n";
+import {StyleSheet, css} from "aphrodite";
+// eslint-disable-next-line import/no-extraneous-dependencies
+import lens from "hubble";
+import * as React from "react";
+
+import HintsRenderer from "../hints-renderer.jsx";
+import {Errors, Log} from "../logging/log.js";
+import Renderer from "../renderer.jsx";
+import Util from "../util.js";
+
+import {itemToTree} from "./items.js";
+import {buildMapper} from "./trees.js";
+
+import type {Widget} from "../renderer.jsx";
+import type {APIOptions, FilterCriterion} from "../types.js";
+import type {Item, ContentNode, HintNode, TagsNode} from "./item-types.js";
+import type {Shape, ArrayShape} from "./shape-types.js";
+import type {Tree} from "./tree-types.js";
+import type {TreeMapper, ContentMapper, HintMapper, Path} from "./trees.js";
+
+type Hint = any; // TODO(mdr)
+type Score = any; // TODO(mdr)
+type SerializedState = any; // TODO(mdr)
+
+type RendererProps = React.ElementConfig<typeof Renderer>;
+
+type ContentRendererElement = React.Element<any>;
+type HintRendererElement = React.Element<any>;
+type ContentRendererData = {|
+    makeRenderer: () => ContentRendererElement,
+    ref: ?Renderer,
+|};
+type FindWidgetsFunc = (criterion: FilterCriterion) => $ReadOnlyArray<?Widget>;
+type HintRendererData = {|
+    makeRenderer: () => HintRendererElement,
+    findExternalWidgets: ?FindWidgetsFunc,
+    ref: null,
+    hint: Hint,
+|};
+type RendererData = ContentRendererData | HintRendererData;
+type RendererDataTree = Tree<ContentRendererData, HintRendererData, null>;
+
+/**
+ * TODO(somewhatabstract, JIRA-XXXX):
+ * Some usage of this type somewhere is causing Flow to believe that these
+ * elements should be components. Don't know where that is, to fix it up
+ * properly. In reality, these types are just too hard to use and aren't
+ * really helping us out as I now have to suppress this rather than
+ * get value from the type. :(
+ */
+// $FlowFixMe[not-a-component]
+// $FlowFixMe[incompatible-type-arg]
+type RendererTree = Tree<ContentRendererElement, HintRendererElement, null>;
+type ScoreTree = Tree<Score, null, null>;
+type SerializedStateTree = Tree<SerializedState, null, null>;
+
+type Props = {|
+    item: Item,
+    shape: Shape,
+    children: (tree: {|renderers: RendererTree|}) => React.Element<any>,
+    serializedState?: ?SerializedStateTree,
+    onSerializedStateUpdated?: (state: SerializedStateTree) => void,
+    onInteractWithWidget?: (id: string) => void,
+    apiOptions?: APIOptions,
+    reviewMode?: ?boolean,
+|};
+type State = {|
+    // We cache functions to generate renderers and refs in `rendererDataTree`,
+    // and change them every time content changes. This isn't just a performance
+    // optimization; see `_makeContentRendererData` for more discussion.
+    rendererDataTree: ?RendererDataTree,
+    // But, if traversing the tree fails, we store the Error in `renderError`.
+    renderError: ?Error,
+|};
+
+class MultiRenderer extends React.Component<Props, State> {
+    rendererDataTreeMapper: TreeMapper<
+        ContentNode,
+        ContentRendererData,
+        HintNode,
+        HintRendererData,
+        TagsNode,
+        null,
+    >;
+    getRenderersMapper: TreeMapper<
+        ContentRendererData,
+        ContentRendererElement,
+        HintRendererData,
+        HintRendererElement,
+        null,
+        null,
+    >;
+
+    constructor(props: Props) {
+        super(props);
+
+        this.rendererDataTreeMapper = buildMapper()
+            .setContentMapper((c, _, p) => this._makeContentRendererData(c, p))
+            .setHintMapper((h) => this._makeHintRendererData(h))
+            .setTagsMapper((t) => null);
+
+        this.getRenderersMapper = buildMapper()
+            .setContentMapper((c) => c.makeRenderer())
+            .setHintMapper((h) => h.makeRenderer())
+            .setArrayMapper((renderers, data, shape) =>
+                this._annotateRendererArray(
+                    (renderers: $FlowFixMe),
+                    (data: $FlowFixMe),
+                    shape,
+                ),
+            );
+
+        // Keep state in sync with props.
+        this.state = this._tryMakeRendererState(this.props);
+    }
+    /* eslint-enable react/sort-comp */
+
+    UNSAFE_componentWillReceiveProps(nextProps: Props) {
+        // Keep state in sync with props.
+        if (nextProps.item !== this.props.item) {
+            this.setState(this._tryMakeRendererState(nextProps));
+        }
+    }
+
+    /**
+     * Attempt to build a State that includes a renderer tree corresponding to
+     * the item provided in props. On error, return a state with `renderError`
+     * set instead.
+     */
+    _tryMakeRendererState(props: Props): State {
+        try {
+            return {
+                rendererDataTree: this._makeRendererDataTree(
+                    props.item,
+                    props.shape,
+                ),
+                renderError: null,
+            };
+        } catch (e) {
+            Log.error("Error building tree state", Errors.Internal, {
+                cause: e,
+            });
+            return {
+                rendererDataTree: null,
+                renderError: e,
+            };
+        }
+    }
+
+    _handleSerializedStateUpdated: (path: Path, newState: any) => void = (
+        path,
+        newState,
+    ) => {
+        const {onSerializedStateUpdated} = this.props;
+
+        if (onSerializedStateUpdated) {
+            const oldState = this._getSerializedState(
+                this.props.serializedState,
+            );
+            onSerializedStateUpdated(
+                lens(oldState).set(path, newState).freeze(),
+            );
+        }
+    };
+
+    /**
+     * Props that aren't directly used by the MultiRenderer are delegated to
+     * the underlying Renderers.
+     */
+    _getRendererProps(): RendererProps {
+        // `item`, `children`, and others are unused. I'm
+        // explicitly pulling them out of `this.props` so I don't pass them to
+        // `<Renderer>`. I'm not sure how else to do this.
+        const {
+            item: _,
+            children: __,
+            shape: ___,
+            serializedState: ____,
+            onSerializedStateUpdated: _____,
+            ...otherProps
+        } = this.props;
+        return otherProps;
+    }
+
+    /**
+     * Construct a Renderer and a ref placeholder for the given ContentNode.
+     */
+    _makeContentRendererData(
+        content: ContentNode,
+        path: Path,
+    ): ContentRendererData {
+        // NOTE(emily): The `findExternalWidgets` function here is computed
+        //     inline and thus changes each time we run this function. If it
+        //     were to change every render, it would cause the Renderer to
+        //     re-render a lot more than is necessary. Don't re-compute this
+        //     element unless it is necessary!
+        // HACK(mdr): Flow can't prove that this is a ContentRendererData,
+        //     because of how we awkwardly construct it in order to obtain a
+        //     circular reference. But it is, I promise.
+        const data: any = {ref: null, makeRenderer: null};
+
+        const refFunc = (e) => (data.ref = e);
+        const findExternalWidgets = (criterion) =>
+            this._findWidgets(data, criterion);
+        const handleSerializedState = (state) =>
+            this._handleSerializedStateUpdated(path, state);
+
+        data.makeRenderer = () => (
+            /**
+             * TODO(somewhatabstract, JIRA-XXXX):
+             * `content` contains props that Renderer doesn't have. However,
+             * since the type for `content` is not exact, it's hard to know
+             * if this spread is including undocumented props so mapping
+             * one to one could introduce a bug. Need to work out the exact
+             * type for ContentNode and then fix this.
+             */
+            // $FlowFixMe[cannot-spread-inexact]
+            <Renderer
+                {...this._getRendererProps()}
+                {...content}
+                ref={refFunc}
+                findExternalWidgets={findExternalWidgets}
+                serializedState={
+                    this.props.serializedState
+                        ? lens(this.props.serializedState).get(path)
+                        : null
+                }
+                onSerializedStateUpdated={handleSerializedState}
+            />
+        );
+        return data;
+    }
+
+    /**
+     * Construct a Renderer for the given HintNode, and keep track of the hint
+     * itself for future use, too.
+     */
+    _makeHintRendererData(hint: HintNode): HintRendererData {
+        // TODO(mdr): Once HintsRenderer supports inter-widget communication,
+        //     give it a ref. Until then, leave the ref null forever, to avoid
+        //     confusing the findWidgets functions.
+        //
+        // NOTE(davidflanagan): As a partial step toward inter-widget
+        // communication we're going to pass a findExternalWidgets function
+        // (using a dummy data object). This allows passage-ref widgets in
+        // hints to use findWidget() to find the passage widgets they reference.
+        // Note that this is one-way only, however. It does not allow
+        // widgets in the question to find widgets in the hints, for example.
+        const findExternalWidgets = (criterion) =>
+            this._findWidgets(({}: any), criterion);
+
+        return {
+            hint,
+            findExternalWidgets, // _annotateRendererArray() needs this
+            ref: null,
+            makeRenderer: () => (
+                <HintsRenderer
+                    {...this._getRendererProps()}
+                    findExternalWidgets={findExternalWidgets}
+                    hints={[hint]}
+                />
+            ),
+        };
+    }
+
+    /**
+     * Construct a tree of interconnected RendererDatas, corresponding to the
+     * given item. Called in `_tryMakeRendererState`, in order to store this
+     * tree in the component state.
+     */
+    _makeRendererDataTree(item: Item, shape: Shape): RendererDataTree {
+        const itemTree = itemToTree(item);
+        return this.rendererDataTreeMapper.mapTree(itemTree, shape);
+    }
+
+    /**
+     * Return all widgets that meet the given criterion, from all Renderers
+     * except the Renderer that triggered this call.
+     *
+     * This function is provided to each Renderer's `findExternalWidgets` prop,
+     * which enables widgets in different Renderers to discover each other and
+     * communicate.
+     */
+    _findWidgets(
+        callingData: RendererData,
+        filterCriterion: FilterCriterion,
+    ): $ReadOnlyArray<?Widget> {
+        const results = [];
+
+        this._mapRenderers((data) => {
+            if (callingData !== data && data.ref) {
+                results.push(...data.ref.findInternalWidgets(filterCriterion));
+            }
+        });
+
+        return results;
+    }
+
+    /**
+     * Copy the renderer tree, apply the given transformation to the leaf nodes
+     * and the optional given transformation to the array nodes, and return the
+     * result.
+     *
+     * Used to provide structured data to the call site (the Renderer tree on
+     * `render`, the Score tree on `getScores`, etc.), and to traverse the
+     * renderer tree even when we disregard the output (like in
+     * `_findWidgets`).
+     */
+    _mapRenderers<O>(
+        // eslint-disable-next-line no-restricted-syntax
+        leafMapper: ContentMapper<RendererData, O> &
+            HintMapper<RendererData, O>,
+    ): ?Tree<O, O, null> {
+        const {rendererDataTree} = this.state;
+
+        if (!rendererDataTree) {
+            return null;
+        }
+
+        const mapper = buildMapper()
+            .setContentMapper(leafMapper)
+            .setHintMapper(leafMapper);
+        return mapper.mapTree(rendererDataTree, this.props.shape);
+    }
+
+    _scoreFromRef(ref: ?Renderer): Score {
+        if (!ref) {
+            return null;
+        }
+
+        const [guess, score] = ref.guessAndScore();
+        let state;
+        if (ref.getSerializedState) {
+            state = ref.getSerializedState();
+        }
+        return Util.keScoreFromPerseusScore(score, guess, state);
+    }
+
+    /**
+     * Return a tree in the shape of the multi-item, with scores at each of
+     * the content nodes and `null` at the other leaf nodes.
+     */
+    getScores(): ScoreTree {
+        return this._mapRenderers((data) => this._scoreFromRef(data.ref));
+    }
+
+    /**
+     * Return a single composite score for all rendered content nodes.
+     * The `guess` is a tree in the shape of the multi-item, with an individual
+     * guess at each content node and `null` at the other leaf nodes.
+     */
+    score(): Score {
+        const scores = [];
+        const state = [];
+        const guess = this._mapRenderers((data) => {
+            if (!data.ref) {
+                return null;
+            }
+
+            if (data.ref.getSerializedState) {
+                state.push(data.ref.getSerializedState());
+            }
+
+            scores.push(data.ref.score());
+            return data.ref?.getUserInput();
+        });
+
+        const combinedScore = scores.reduce(Util.combineScores);
+
+        return Util.keScoreFromPerseusScore(combinedScore, guess, state);
+    }
+
+    /**
+     * Return a tree in the shape of the multi-item, with serialized state at
+     * each of the content nodes and `null` at the other leaf nodes.
+     *
+     * If the lastSerializedState argument is supplied, this function will fill
+     * in the state of not-currently-rendered content and hint nodes with the
+     * values from the previous serialized state. If no lastSerializedState is
+     * supplied, `null` will be returned for not-currently-rendered content and
+     * hint nodes.
+     */
+    _getSerializedState(
+        lastSerializedState?: SerializedStateTree,
+    ): SerializedStateTree {
+        return this._mapRenderers((data, _, path) => {
+            if (data.ref) {
+                return data.ref.getSerializedState();
+            }
+            if (lastSerializedState) {
+                return lens(lastSerializedState).get(path);
+            }
+            return null;
+        });
+    }
+
+    /**
+     * Given a tree in the shape of the multi-item, with serialized state at
+     * each of the content nodes, restore each state to the corresponding
+     * renderer if currently mounted.
+     */
+    restoreSerializedState(
+        serializedState: SerializedState,
+        callback?: () => any,
+    ) {
+        // We want to call our async callback only once all of the childrens'
+        // callbacks have run. We add one to this counter before we call out to
+        // each renderer and decrement it when it runs our callback.
+        let numCallbacks = 0;
+        const countCallback = () => {
+            numCallbacks--;
+            if (callback && numCallbacks === 0) {
+                callback();
+            }
+        };
+
+        this._mapRenderers((data, _, path) => {
+            if (!data.ref) {
+                return;
+            }
+
+            const state = lens(serializedState).get(path);
+            if (!state) {
+                return;
+            }
+
+            numCallbacks++;
+            data.ref?.restoreSerializedState(state, countCallback);
+        });
+    }
+
+    /**
+     * Given an array of renderers, if it happens to be an array of *hint*
+     * renderers, then attach a `firstN` method to the array, which allows the
+     * layout to render the hints together in one HintsRenderer.
+     */
+    _annotateRendererArray(
+        renderers: $ReadOnlyArray<Renderer>,
+        rendererDatas: $ReadOnlyArray<RendererData>,
+        shape: ArrayShape,
+    ): $ReadOnlyArray<Renderer> {
+        if (shape.elementShape.type === "hint") {
+            // The shape says that these are HintRendererDatas, even though
+            // it's not provable at compile time, so perform a cast.
+            const hintRendererDatas: $ReadOnlyArray<HintRendererData> =
+                (rendererDatas: any);
+
+            renderers = [...renderers];
+            (renderers: any).firstN = (n) => (
+                <HintsRenderer
+                    {...this._getRendererProps()}
+                    findExternalWidgets={
+                        hintRendererDatas[0]
+                            ? hintRendererDatas[0].findExternalWidgets
+                            : undefined
+                    }
+                    hints={hintRendererDatas.map((d) => d.hint)}
+                    hintsVisible={n}
+                />
+            );
+        }
+        return renderers;
+    }
+
+    /**
+     * Return a tree in the shape of the multi-item, with a Renderer at each
+     * content node and a HintRenderer at each hint node.
+     *
+     * This is generated by running each of the `makeRenderer` functions at the
+     * leaf nodes.
+     */
+    _getRenderers(): RendererTree {
+        return this.getRenderersMapper.mapTree(
+            this.state.rendererDataTree,
+            this.props.shape,
+        );
+    }
+
+    render(): React.Node {
+        if (this.state.renderError) {
+            return (
+                <div className={css(styles.error)}>
+                    {i18n.$_("Error rendering: %(error)s", {
+                        error: String(this.state.renderError),
+                    })}
+                </div>
+            );
+        }
+
+        // Pass the renderer tree to the `children` function, which will
+        // determine the actual content of this component.
+        return this.props.children({
+            renderers: this._getRenderers(),
+        });
+    }
+}
+
+const styles = StyleSheet.create({
+    error: {
+        color: "red",
+    },
+});
+
+export default MultiRenderer;

package/src/multi-items/prop-type-builders.js

@@ -0,0 +1,105 @@
+// @flow
+/**
+ * Utility functions to build React PropTypes for multi-items and shapes.
+ *
+ * If you're writing new components, though, consider using the Item and Shape
+ * Flow types instead.
+ */
+/* instanbul ignore file */
+
+import PropTypes from "prop-types";
+
+import {Errors} from "../logging/log.js";
+import {PerseusError} from "../perseus-error.js";
+
+import type {Shape} from "./shape-types.js";
+
+/**
+ * A recursive PropType that accepts Shape objects, and rejects other objects.
+ *
+ * Usage: `propTypes: {shape: shapePropType}`.
+ */
+export function shapePropType(...args: $ReadOnlyArray<any>): $FlowFixMe {
+    const itemShape = PropTypes.oneOfType([
+        PropTypes.shape({
+            type: PropTypes.oneOf(["content"]).isRequired,
+        }).isRequired,
+        PropTypes.shape({
+            type: PropTypes.oneOf(["hint"]).isRequired,
+        }).isRequired,
+        PropTypes.shape({
+            type: PropTypes.oneOf(["tags"]).isRequired,
+        }).isRequired,
+        PropTypes.shape({
+            type: PropTypes.oneOf(["object"]).isRequired,
+            shape: PropTypes.objectOf(shapePropType),
+        }).isRequired,
+        PropTypes.shape({
+            type: PropTypes.oneOf(["array"]).isRequired,
+            elementShape: shapePropType,
+        }).isRequired,
+    ]);
+
+    return itemShape(...args);
+}
+
+/**
+ * Return a PropType that accepts Items of the given shape, and rejects other
+ * objects.
+ *
+ * Usage: `propTypes: {item: buildPropTypeForShape(myShape)}`
+ */
+export function buildPropTypeForShape(shape: Shape): $FlowFixMe {
+    return PropTypes.oneOfType([
+        PropTypes.shape({
+            _multi: buildTreePropTypeForShape(shape),
+        }),
+        PropTypes.oneOf([null, undefined]),
+    ]);
+}
+
+/**
+ * Return a PropType that accepts ItemTrees of the given shape, and rejects
+ * other objects.
+ */
+function buildTreePropTypeForShape(shape: Shape): $FlowFixMe {
+    if (shape.type === "content") {
+        return PropTypes.shape({
+            // TODO(mdr): Remove #LegacyContentNode support.
+            __type: PropTypes.oneOf(["content", "item"]).isRequired,
+            content: PropTypes.string,
+            images: PropTypes.objectOf(PropTypes.any),
+            widgets: PropTypes.objectOf(PropTypes.any),
+        });
+    }
+    if (shape.type === "hint") {
+        return PropTypes.shape({
+            __type: PropTypes.oneOf(["hint"]).isRequired,
+            content: PropTypes.string,
+            images: PropTypes.objectOf(PropTypes.any),
+            widgets: PropTypes.objectOf(PropTypes.any),
+            replace: PropTypes.bool,
+        });
+    }
+    if (shape.type === "tags") {
+        return PropTypes.arrayOf(PropTypes.string.isRequired);
+    }
+    if (shape.type === "array") {
+        const elementPropType = buildTreePropTypeForShape(shape.elementShape);
+        return PropTypes.arrayOf(elementPropType.isRequired);
+    }
+    if (shape.type === "object") {
+        const valueShapes = shape.shape;
+        const propTypeShape = {};
+        Object.keys(valueShapes).forEach((key) => {
+            propTypeShape[key] = buildTreePropTypeForShape(
+                valueShapes[key],
+            ).isRequired;
+        });
+        return PropTypes.shape(propTypeShape);
+    }
+    throw new PerseusError(
+        `unexpected shape type ${shape.type}`,
+        Errors.InvalidInput,
+    );
+}

package/src/multi-items/shape-types.js

@@ -0,0 +1,47 @@
+// @flow
+/**
+ * Type definitions for multi-item shapes.
+ *
+ * A shape is an object that serves as a runtime type declaration: it specifies
+ * a tree structure for a particular class of multi-item.
+ *
+ * We use shapes instead static compile-time typing because the CMS needs to
+ * understand the shape of our content library's multi-items at runtime, and
+ * it's not always possible to infer the full shape from an example multi-item.
+ *
+ * Shapes also enable us to traverse a multi-item-shaped tree with confidence,
+ * even when we can't infer the shape from the tree alone.
+ *
+ * We *could* go all-in on a more general library to make certain Flow types
+ * runtime-inspectable, in order to DRY some things up, but that's probably a
+ * big ol' infrastructural magic mess, and the narrower scope of Shapes makes
+ * it easier to be confident that we've covered all cases rather than having to
+ * deal with all possible Javascript types.
+ */
+export type ContentShape = {type: "content", ...};
+export type HintShape = {type: "hint", ...};
+export type TagsShape = {type: "tags", ...};
+export type ArrayShape = {
+    type: "array",
+    /**
+     * Each element of an ArrayNode has the same shape, which is specified by
+     * the `elementShape` property.
+     */
+    elementShape: Shape,
+    ...
+};
+export type ObjectShape = {
+    type: "object",
+    /**
+     * Each property of an ObjectNode has its own shape, which is specified
+     * under the corresponding key in the `shape` property.
+     */
+    shape: {[k: string]: Shape, ...},
+    ...
+};
+export type Shape =
+    | ContentShape
+    | HintShape
+    | TagsShape
+    | ArrayShape
+    | ObjectShape;