@khanacademy/perseus 3.0.0 → 4.0.0

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

@@ -1,543 +0,0 @@
-/* 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

@@ -1,105 +0,0 @@
-// @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

@@ -1,47 +0,0 @@
-// @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;