@khanacademy/perseus 3.0.0 → 4.0.1

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

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

package/src/multi-items/shapes.ts

@@ -0,0 +1,52 @@
+/**
+ * Utility functions for constructing and inferring 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. See shape-types.js
+ * for further discussion.
+ *
+ * This module allows you to construct arbitrary Shape trees, by combining
+ * leaf node shapes like `content` and `hint` into composite shapes like
+ * `arrayOf(shape({foo: content, bar: hint}))`.
+ */
+import type {
+    Shape,
+    ContentShape,
+    HintShape,
+    TagsShape,
+    ArrayShape,
+    ObjectShape,
+} from "./shape-types";
+
+/**
+ * These tools allow you to construct arbirtary shapes, by combining simple
+ * leaf shapes like `content` and `hint` into composite shapes like
+ * `arrayOf(shape({question: content, hints: arrayOf(hint)}))`.
+ */
+const contentShape: ContentShape = {
+    type: "content",
+};
+const hintShape: HintShape = {
+    type: "hint",
+};
+const tagsShape: TagsShape = {
+    type: "tags",
+};
+const buildArrayShape = (elementShape: Shape): ArrayShape => ({
+    type: "array",
+    elementShape,
+});
+const buildObjectShape = (shape: {[k: string]: Shape}): ObjectShape => ({
+    type: "object",
+    shape,
+});
+const hintsShape: ArrayShape = buildArrayShape(hintShape);
+
+export default {
+    content: contentShape,
+    hint: hintShape,
+    hints: hintsShape,
+    tags: tagsShape,
+    arrayOf: buildArrayShape,
+    shape: buildObjectShape,
+};

package/src/multi-items/tree-types.ts

@@ -0,0 +1,47 @@
+/**
+ * Type definitions for generic trees that are shaped like multi-items.
+ *
+ * Multi-items are trees! But we also often have other trees that are shaped
+ * like multi-items - for example, if we map a multi-item tree into a tree of
+ * renderer info and state, and then map that again into a tree of just the
+ * renderer nodes, like we do in MultiRenderer.
+ *
+ * Therefore, we provide the type Tree<C, H>, which represents a tree that's
+ * shaped like a multi-item, but the data that lives at each type of leaf could
+ * be anything.
+ *
+ * So, in a Tree<C, H>, content leaf nodes have type C, and hint leaf nodes
+ * have type H. An ItemTree is a Tree<ContentNode, HintNode>.
+ *
+ * That is, we still preserve the distinction between node types, and thereby
+ * enforce the Tree's adherence to some multi-item Shape, but we're flexible
+ * about exactly what type of data the tree contains at its leaves.
+ *
+ * This enables us to write generic tree-traversal and tree-mapping functions,
+ * as you'll see in trees.js.
+ */
+
+// TODO(jeremy): We lost "arrayness" in D69450. It'd be nice to restore that
+// because right now ArrayNode doesn't add anything.
+// @ts-expect-error [FEI-5003] - TS2456 - Type alias 'ArrayNode' circularly references itself. | TS2315 - Type 'Tree' is not generic.
+export type ArrayNode<C, H, T> = Tree<C, H, T>;
+export type ObjectNode<C, H, T> = {
+    // @ts-expect-error [FEI-5003] - TS2315 - Type 'Tree' is not generic.
+    [k: string]: Tree<C, H, T>;
+};
+
+/**
+ * TODO(somewhatabstract, JIRA-XXXX):
+ * We should ditch this type or create some helpers for working with it.
+ * As it stands, consumers have to check each node's type before using it
+ * in order to ensure that flow can track its refinement and appropriate use.
+ * It's messy.
+ */
+// @ts-expect-error [FEI-5003] - TS2456 - Type alias 'Tree' circularly references itself. | TS2315 - Type 'ArrayNode' is not generic.
+export type Tree<C, H, T> =
+    | C
+    | H
+    | T
+    // @ts-expect-error [FEI-5003] - TS2315 - Type 'ArrayNode' is not generic.
+    | ArrayNode<C, H, T>
+    | ObjectNode<C, H, T>;

package/src/multi-items/trees.ts

@@ -0,0 +1,360 @@
+/**
+ * Utility functions for manipulating multi-item-shaped trees.
+ *
+ * Multi-items are trees! But we also often have other trees that are shaped
+ * like multi-items - for example, if we map a multi-item tree into a tree of
+ * renderer info and state, and then map that again into a tree of just the
+ * renderer nodes, like we do in MultiRenderer. See tree-types.js for further
+ * discussion.
+ *
+ * These functions enable us to manipulate generic multi-item-shaped trees,
+ * regardless of what type of data they contain at their leaves. You can use
+ * the mapper functions to transform a tree into another tree of the same
+ * shape, or to discover all the nodes of a particular type.
+ *
+ * We expose two simple mapper functions (mapContentNodes and mapHintNodes),
+ * and also a more complex interface for creating a mapping over all of a
+ * tree's node types simultaneously:
+ *
+ * `buildMapper()` returns a TreeMapper object that allows you to build your
+ * mapper object one node type at a time. Then, you can execute your mapping by
+ * calling the `mapTree` method.
+ *
+ * For example:
+ *     const renderers = buildMapper()
+ *         .setContentMapper(this.renderContentNode)
+ *         .setHintMapper(this.renderHintNode)
+ *         .setTagsMapper(this.renderTagsNode)
+ *         .setArrayMapper(this.hideSkippedQuestions)
+ *         .mapTree(tree, shape);
+ *
+ * This will copy the given tree, apply the given transformations to the
+ * content, hint, and array nodes respectively, and return the resulting tree.
+ *
+ * For node types whose mappers aren't specified, we default to the identity
+ * function. (This builder interface enables us to implement that default
+ * behavior in a provably type-safe way, while not requiring the call site to
+ * be aware of all the node types. Hooray!)
+ *
+ * The call to `setArrayMapper` must come last, because the array mapper's
+ * argument types depend on the other mappers' types. See ArrayMapper for more
+ * details.
+ *
+ * WARNING: These functions trust that the provided tree conforms to the
+ * provided shape. If not, behavior is undefined and may not respect the type
+ * signatures specified here.
+ */
+
+import {Errors} from "../logging/log";
+import {PerseusError} from "../perseus-error";
+
+import type {
+    Shape,
+    ContentShape,
+    HintShape,
+    TagsShape,
+    ArrayShape,
+} from "./shape-types";
+import type {Tree, ArrayNode, ObjectNode} from "./tree-types";
+
+/**
+ * The sequence of edges that lead to a particular node in a Tree.
+ * Elements can be `string` to correspond to an ObjectNode key, or `number` to
+ * correspond to an ArrayNode index.
+ */
+export type Path = ReadonlyArray<string | number>;
+
+/**
+ * These are function interfaces for mapping over various types of tree nodes.
+ *
+ * ArrayMapper is a bit more complicated than the leaf node mappers. It's
+ * executed in the context of a `mapTree` call, after we've finished mapping
+ * its child nodes, so the function has access to both the resulting array
+ * (with mapped elements) and the original array (with the original untouched
+ * elements).
+ *
+ * The ArrayMapper then has the opportunity to apply a final transformation to
+ * the resulting array, like filtering certain elements or (in the hacky
+ * MultiRenderer case) attaching a `renderHints` method to arrays of hint
+ * renderers :)
+ *
+ * This is why `TreeMapper#setArrayMapper` must be called last: ArrayMapper's
+ * types depend on the ContentMapper and HintMapper's types. And, since you can
+ * only specify one mapper at a time in this builder interface (which is
+ * necessary to provide default mappers in a type-safe way), you need your
+ * dependencies to already be in place by the time you call `setArrayMapper`.
+ * Otherwise, we'd have to set the ArrayMapper and *hope* that you *eventually*
+ * provide a compatible ContentMapper and HintMapper, which is difficult to
+ * prove at compile time.
+ *
+ * There's no ObjectMapper here, but not for any particular reason. We just
+ * don't have a use case for it yet, so we haven't built it yet.
+ */
+export type ContentMapper<CI, CO> = (
+    content: CI,
+    shape: ContentShape,
+    path: Path,
+) => CO;
+export type HintMapper<HI, HO> = (hint: HI, shape: HintShape, path: Path) => HO;
+export type TagsMapper<TI, TO> = (tag: TI, shape: TagsShape, path: Path) => TO;
+export type ArrayMapper<CI, CO, HI, HO, TI, TO> = (
+    // @ts-expect-error [FEI-5003] - TS2315 - Type 'ArrayNode' is not generic.
+    mappedArray: ArrayNode<CO, HO, TO>,
+    // @ts-expect-error [FEI-5003] - TS2315 - Type 'ArrayNode' is not generic.
+    originalArray: ArrayNode<CI, HI, TI>,
+    shape: ArrayShape,
+    path: Path,
+    // @ts-expect-error [FEI-5003] - TS2315 - Type 'ArrayNode' is not generic.
+) => ArrayNode<CO, HO, TO>;
+
+/**
+ * A TreeMapper is a collection of node mappers, which, together, compose the
+ * behavior for mapping over an entire tree.
+ *
+ * This serves as the interface for the two TreeMapper classes, including both
+ * the internal mapper properties that we care about, and the `mapTree`
+ * function that the call site will use.
+ */
+export interface TreeMapper<CI, CO, HI, HO, TI, TO> {
+    content: ContentMapper<CI, CO>;
+    hint: HintMapper<HI, HO>;
+    tags: TagsMapper<TI, TO>;
+    array: ArrayMapper<CI, CO, HI, HO, TI, TO>;
+    // @ts-expect-error [FEI-5003] - TS2315 - Type 'Tree' is not generic. | TS2315 - Type 'Tree' is not generic.
+    mapTree(tree: Tree<CI, HI, TI>, shape: Shape): Tree<CO, HO, TO>;
+}
+
+/**
+ * This is a TreeMapper that only has mappers specified for its leaf nodes; its
+ * array mapper is the identity function.
+ *
+ * This is the TreeMapper initially returned by `buildMapper`. It allows you to
+ * change the types of your ContentMapper and HintMapper, which is safe because
+ * none of the other mappers that depend on those types (aka ArrayMapper) have
+ * been specified yet. (Or, more specifically, the ArrayMapper is currently
+ * `identity`, which can trivially vary with the ContentMapper and HintMapper's
+ * types.)
+ *
+ * Once you call `setArrayMapper`, however, we move to the other class:
+ * TreeMapperForLeavesAndCollections.
+ */
+class TreeMapperJustForLeaves<CI, CO, HI, HO, TI, TO> {
+    content: ContentMapper<CI, CO>;
+    hint: HintMapper<HI, HO>;
+    tags: TagsMapper<TI, TO>;
+    array: ArrayMapper<CI, CO, HI, HO, TI, TO>;
+
+    constructor(
+        content: ContentMapper<CI, CO>,
+        hint: HintMapper<HI, HO>,
+        tags: TagsMapper<TI, TO>,
+    ) {
+        this.content = content;
+        this.hint = hint;
+        this.tags = tags;
+        this.array = identity;
+    }
+
+    setContentMapper<CI2, CO2>(
+        newContentMapper: ContentMapper<CI2, CO2>,
+    ): TreeMapperJustForLeaves<CI2, CO2, HI, HO, TI, TO> {
+        return new TreeMapperJustForLeaves(
+            newContentMapper,
+            this.hint,
+            this.tags,
+        );
+    }
+
+    setHintMapper<HI2, HO2>(
+        newHintMapper: HintMapper<HI2, HO2>,
+    ): TreeMapperJustForLeaves<CI, CO, HI2, HO2, TI, TO> {
+        return new TreeMapperJustForLeaves(
+            this.content,
+            newHintMapper,
+            this.tags,
+        );
+    }
+
+    setTagsMapper<TI2, TO2>(
+        newTagsMapper: TagsMapper<TI2, TO2>,
+    ): TreeMapperJustForLeaves<CI, CO, HI, HO, TI2, TO2> {
+        return new TreeMapperJustForLeaves(
+            this.content,
+            this.hint,
+            newTagsMapper,
+        );
+    }
+
+    setArrayMapper(
+        newArrayMapper: ArrayMapper<CI, CO, HI, HO, TI, TO>,
+    ): TreeMapperForLeavesAndCollections<CI, CO, HI, HO, TI, TO> {
+        return new TreeMapperForLeavesAndCollections(
+            this.content,
+            this.hint,
+            this.tags,
+            newArrayMapper,
+        );
+    }
+
+    // @ts-expect-error [FEI-5003] - TS2315 - Type 'Tree' is not generic. | TS2315 - Type 'Tree' is not generic.
+    mapTree(tree: Tree<CI, HI, TI>, shape: Shape): Tree<CO, HO, TO> {
+        return mapTree(tree, shape, [], this);
+    }
+}
+
+/**
+ * This is a TreeMapper that already has an ArrayMapper specified, so its
+ * ContentMapper and HintMapper are now locked in.
+ */
+class TreeMapperForLeavesAndCollections<CI, CO, HI, HO, TI, TO> {
+    content: ContentMapper<CI, CO>;
+    hint: HintMapper<HI, HO>;
+    tags: TagsMapper<TI, TO>;
+    array: ArrayMapper<CI, CO, HI, HO, TI, TO>;
+
+    constructor(
+        content: ContentMapper<CI, CO>,
+        hint: HintMapper<HI, HO>,
+        tags: TagsMapper<TI, TO>,
+        array: ArrayMapper<CI, CO, HI, HO, TI, TO>,
+    ) {
+        this.content = content;
+        this.hint = hint;
+        this.tags = tags;
+        this.array = array;
+    }
+
+    setArrayMapper(
+        newArrayMapper: ArrayMapper<CI, CO, HI, HO, TI, TO>,
+    ): TreeMapperForLeavesAndCollections<CI, CO, HI, HO, TI, TO> {
+        return new TreeMapperForLeavesAndCollections(
+            this.content,
+            this.hint,
+            this.tags,
+            newArrayMapper,
+        );
+    }
+
+    // @ts-expect-error [FEI-5003] - TS2315 - Type 'Tree' is not generic. | TS2315 - Type 'Tree' is not generic.
+    mapTree(tree: Tree<CI, HI, TI>, shape: Shape): Tree<CO, HO, TO> {
+        return mapTree(tree, shape, [], this);
+    }
+}
+
+function identity<T>(x: T): T {
+    return x;
+}
+
+/**
+ * Return a new TreeMapper that will perform a no-op transformation on an input
+ * tree. To make it useful, chain any combination of `setContentMapper`,
+ * `setHintMapper`, `setTagMapper`, and `setArrayMapper` to specify
+ * transformations for the individual node types.
+ */
+// @ts-expect-error [FEI-5003] - TS2300 - Duplicate identifier 'C'. | TS2300 - Duplicate identifier 'H'. | TS2300 - Duplicate identifier 'T'.
+export function buildMapper<C, C, H, H, T, T>(): TreeMapperJustForLeaves<
+    C,
+    C,
+    H,
+    H,
+    T,
+    T
+> {
+    return new TreeMapperJustForLeaves(identity, identity, identity);
+}
+
+/**
+ * Copy the given tree, apply the corresponding transformation specified in the
+ * TreeMapper to each node, and return the resulting tree.
+ */
+function mapTree<CI, CO, HI, HO, TI, TO>(
+    // @ts-expect-error [FEI-5003] - TS2315 - Type 'Tree' is not generic.
+    tree: Tree<CI, HI, TI>,
+    shape: Shape,
+    path: Path,
+    mappers: TreeMapper<CI, CO, HI, HO, TI, TO>,
+    // @ts-expect-error [FEI-5003] - TS2315 - Type 'Tree' is not generic.
+): Tree<CO, HO, TO> {
+    // We trust the shape of the multi-item to match the shape provided at
+    // runtime. Therefore, in each shape branch, we cast the node to `any` and
+    // reinterpret it as the expected node type.
+    if (shape.type === "content") {
+        const content: CI = tree as any;
+        return mappers.content(content, shape, path);
+    }
+    if (shape.type === "hint") {
+        const hint: HI = tree as any;
+        return mappers.hint(hint, shape, path);
+    }
+    if (shape.type === "tags") {
+        const tags: TI = tree as any;
+        return mappers.tags(tags, shape, path);
+    }
+    if (shape.type === "array") {
+        // @ts-expect-error [FEI-5003] - TS2315 - Type 'ArrayNode' is not generic.
+        const array: ArrayNode<CI, HI, TI> = tree as any;
+
+        if (!Array.isArray(array)) {
+            throw new PerseusError(
+                `Invalid object of type "${typeof array}" found at path ` +
+                    // @ts-expect-error [FEI-5003] - TS2769 - No overload matches this call.
+                    `${["<root>"].concat(path).join(".")}. Expected array.`,
+                Errors.Internal,
+            );
+        }
+
+        const elementShape = shape.elementShape;
+        // @ts-expect-error [FEI-5003] - TS2315 - Type 'ArrayNode' is not generic.
+        const mappedElements: ArrayNode<CO, HO, TO> = array.map((inner, i) =>
+            mapTree(inner, elementShape, path.concat(i), mappers),
+        );
+        return mappers.array(mappedElements, array, shape, path);
+    }
+    if (shape.type === "object") {
+        const object: ObjectNode<CI, HI, TI> = tree as any;
+
+        if (object && typeof object !== "object") {
+            throw new PerseusError(
+                `Invalid object of type "${typeof object}" found at ` +
+                    // @ts-expect-error [FEI-5003] - TS2769 - No overload matches this call.
+                    `path ${["<root>"].concat(path).join(".")}. Expected ` +
+                    `"object" type.`,
+                Errors.InvalidInput,
+            );
+        }
+
+        const valueShapes = shape.shape;
+        if (!valueShapes) {
+            throw new PerseusError(
+                `Unexpected shape ${JSON.stringify(shape)} at path ` +
+                    // @ts-expect-error [FEI-5003] - TS2769 - No overload matches this call.
+                    `${["<root>"].concat(path).join(".")}.`,
+                Errors.InvalidInput,
+            );
+        }
+        const newObject: Record<string, any> = {};
+        Object.keys(valueShapes).forEach((key) => {
+            if (!(key in object)) {
+                throw new PerseusError(
+                    `Key "${key}" is missing from shape at path ` +
+                        // @ts-expect-error [FEI-5003] - TS2769 - No overload matches this call.
+                        `${["<root>"].concat(path).join(".")}.`,
+                    Errors.InvalidInput,
+                );
+            }
+
+            newObject[key] = mapTree(
+                object[key],
+                valueShapes[key],
+                path.concat(key),
+                mappers,
+            );
+        });
+        return newObject;
+    }
+    throw new PerseusError(
+        // @ts-expect-error [FEI-5003] - TS2339 - Property 'type' does not exist on type 'never'.
+        `unexpected shape type ${shape.type}`,
+        Errors.InvalidInput,
+    );
+}

package/src/multi-items.ts

@@ -0,0 +1,75 @@
+/**
+ * This library provides support for Perseus multi-items: structured Perseus
+ * content that content creators can easily create, and that applications can
+ * easily render into different parts of the layout.
+ *
+ * For more details about application and motivation, see:
+ * https://sites.google.com/a/khanacademy.org/forge/for-developers/perseus-items-and-multi-items
+ *
+ * This file primarily 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.
+ * For more details, see `multi-items/multi-renderer.jsx`.
+ *
+ * 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>
+ *
+ * This file also exposes `shapes`, which helps you construct a runtime type
+ * declaration for your particular class of multi-item. This can then be used
+ * to create a MultirendererEditor for your multi-item shape, and to validate
+ * that a multi-item conforms to the shape via `buildPropTypeForShape`.
+ * For more details, see `multi-items/shapes.js`.
+ *
+ * This file also exposes some utility functions for working with generic
+ * multi-items, like `findContentNodesInItem`, `findHintNodesInItem`,
+ * `inferItemShape`, and `buildEmptyItemForShape`.
+ * For more details, see `multi-items/items.js`.
+ */
+import {
+    buildEmptyItemForShape,
+    findContentNodesInItem,
+    findHintNodesInItem,
+    inferItemShape,
+} from "./multi-items/items";
+import MultiRenderer from "./multi-items/multi-renderer";
+import {buildPropTypeForShape} from "./multi-items/prop-type-builders";
+import shapes from "./multi-items/shapes";
+
+export default {
+    // Tools for rendering your multi-items
+    MultiRenderer,
+
+    // Tools for declaring your multi-item shapes
+    shapes,
+    buildPropTypeForShape,
+
+    // Tools for generically manipulating multi-items
+    buildEmptyItemForShape,
+    findContentNodesInItem,
+    findHintNodesInItem,
+    inferItemShape,
+};