@khanacademy/perseus 3.0.0 → 4.0.0

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

@@ -0,0 +1,564 @@
+/* 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.
+/**
+ * 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";
+import {Errors, Log} from "../logging/log";
+import Renderer from "../renderer";
+import Util from "../util";
+
+import {itemToTree} from "./items";
+import {buildMapper} from "./trees";
+
+import type {Widget} from "../renderer";
+import type {APIOptions, FilterCriterion, PerseusScore} from "../types";
+import type {Item, ContentNode, HintNode, TagsNode} from "./item-types";
+import type {Shape, ArrayShape} from "./shape-types";
+import type {Tree} from "./tree-types";
+import type {TreeMapper, ContentMapper, HintMapper, Path} from "./trees";
+
+type Hint = any; // TODO(mdr)
+type Score = any; // TODO(mdr)
+type SerializedState = any; // TODO(mdr)
+
+type RendererProps = JSX.LibraryManagedAttributes<
+    typeof Renderer,
+    // @ts-expect-error [FEI-5003] - TS2344 - Type 'typeof Renderer' does not satisfy the constraint 'keyof IntrinsicElements | JSXElementConstructor<any>'.
+    React.ComponentProps<typeof Renderer>
+>;
+
+type ContentRendererElement = React.ReactElement<any>;
+type HintRendererElement = React.ReactElement<any>;
+type ContentRendererData = {
+    makeRenderer: () => ContentRendererElement;
+    ref: Renderer | null | undefined;
+};
+type FindWidgetsFunc = (
+    criterion: FilterCriterion,
+) => ReadonlyArray<Widget | null | undefined>;
+type HintRendererData = {
+    makeRenderer: () => HintRendererElement;
+    findExternalWidgets: FindWidgetsFunc | null | undefined;
+    ref: null;
+    hint: Hint;
+};
+type RendererData = ContentRendererData | HintRendererData;
+// @ts-expect-error [FEI-5003] - TS2315 - Type 'Tree' is not generic.
+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. :(
+ */
+// @ts-expect-error [FEI-5003] - TS2315 - Type 'Tree' is not generic.
+type RendererTree = Tree<ContentRendererElement, HintRendererElement, null>;
+// @ts-expect-error [FEI-5003] - TS2315 - Type 'Tree' is not generic.
+type ScoreTree = Tree<Score, null, null>;
+// @ts-expect-error [FEI-5003] - TS2315 - Type 'Tree' is not generic.
+type SerializedStateTree = Tree<SerializedState, null, null>;
+
+type Props = {
+    item: Item;
+    shape: Shape;
+    children: (tree: {renderers: RendererTree}) => React.ReactElement<any>;
+    serializedState?: SerializedStateTree | null | undefined;
+    onSerializedStateUpdated?: (state: SerializedStateTree) => void;
+    onInteractWithWidget?: (id: string) => void;
+    apiOptions?: APIOptions;
+    reviewMode?: boolean | null | undefined;
+};
+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 | null | undefined;
+    // But, if traversing the tree fails, we store the Error in `renderError`.
+    renderError: Error | null | undefined;
+};
+
+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()
+            // @ts-expect-error [FEI-5003] - TS2345 - Argument of type 'unknown' is not assignable to parameter of type 'ContentNode'.
+            .setContentMapper((c, _, p) => this._makeContentRendererData(c, p))
+            // @ts-expect-error [FEI-5003] - TS2345 - Argument of type 'unknown' is not assignable to parameter of type 'HintNode'.
+            .setHintMapper((h) => this._makeHintRendererData(h))
+            .setTagsMapper((t) => null);
+
+        // @ts-expect-error [FEI-5003] - TS2322 - Type 'TreeMapperForLeavesAndCollections<unknown, any, unknown, any, unknown, unknown>' is not assignable to type 'TreeMapper<ContentRendererData, ContentRendererElement, HintRendererData, HintRendererElement, null, null>'.
+        this.getRenderersMapper = buildMapper()
+            // @ts-expect-error [FEI-5003] - TS2571 - Object is of type 'unknown'.
+            .setContentMapper((c) => c.makeRenderer())
+            // @ts-expect-error [FEI-5003] - TS2571 - Object is of type 'unknown'.
+            .setHintMapper((h) => h.makeRenderer())
+            .setArrayMapper((renderers, data, shape) =>
+                this._annotateRendererArray(
+                    renderers as any,
+                    data as any,
+                    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: any) {
+            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: any) => (data.ref = e);
+        const findExternalWidgets = (criterion: any) =>
+            this._findWidgets(data, criterion);
+        const handleSerializedState = (state: any) =>
+            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]
+            // @ts-expect-error [FEI-5003] - TS2322 - Type '{ ref: (e: any) => any; findExternalWidgets: (criterion: any) => readonly (Widget | null | undefined)[]; serializedState: any; onSerializedStateUpdated: (state: any) => void; __type: "content" | "item"; ... 9 more ...; reviewMode?: boolean | ... 1 more ... | undefined; }' is not assignable to type 'InexactPartial<Pick<Readonly<Props> & Readonly<{ children?: ReactNode; }>, "content" | "images" | "onRender" | "linterContext" | "widgets" | "alwaysUpdate" | ... 6 more ... | "serializedState">>'.
+            <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({} as any, criterion);
+
+        return {
+            hint,
+            findExternalWidgets, // _annotateRendererArray() needs this
+            ref: null,
+            makeRenderer: () => (
+                <HintsRenderer
+                    {...this._getRendererProps()}
+                    // @ts-expect-error [FEI-5003] - TS2769 - No overload matches this call.
+                    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 | null | undefined> {
+        const results: Array<Widget | null | undefined> = [];
+
+        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>,
+        // @ts-expect-error [FEI-5003] - TS2315 - Type 'Tree' is not generic.
+    ): Tree<O, O, null> | null | undefined {
+        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 | null): 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: Array<PerseusScore> = [];
+        const state: Array<
+            | any
+            | {
+                  [id: string]: any;
+              }
+        > = [];
+        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 as any;
+
+            renderers = [...renderers];
+            (renderers as any).firstN = (n: any) => (
+                <HintsRenderer
+                    {...this._getRendererProps()}
+                    // @ts-expect-error [FEI-5003] - TS2769 - No overload matches this call.
+                    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.ReactNode {
+        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.ts

@@ -0,0 +1,106 @@
+/**
+ * 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";
+import {PerseusError} from "../perseus-error";
+
+import type {Shape} from "./shape-types";
+
+/**
+ * A recursive PropType that accepts Shape objects, and rejects other objects.
+ *
+ * Usage: `propTypes: {shape: shapePropType}`.
+ */
+export function shapePropType(...args: ReadonlyArray<any>): any {
+    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,
+    ]);
+
+    // @ts-expect-error [FEI-5003] - TS2556 - A spread argument must either have a tuple type or be passed to a rest parameter.
+    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): any {
+    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): any {
+    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: Record<string, any> = {};
+        Object.keys(valueShapes).forEach((key) => {
+            propTypeShape[key] = buildTreePropTypeForShape(
+                valueShapes[key],
+            ).isRequired;
+        });
+        return PropTypes.shape(propTypeShape);
+    }
+    throw new PerseusError(
+        // @ts-expect-error [FEI-5003] - TS2339 - Property 'type' does not exist on type 'never'.
+        `unexpected shape type ${shape.type}`,
+        Errors.InvalidInput,
+    );
+}