@khanacademy/perseus 19.1.5 → 19.1.7

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

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

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

@@ -1,47 +0,0 @@
-/**
- * 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 - 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 - 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 TypeScript can track its refinement and appropriate use.
- * It's messy.
- */
-// @ts-expect-error - 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 - TS2315 - Type 'ArrayNode' is not generic.
-    | ArrayNode<C, H, T>
-    | ObjectNode<C, H, T>;

package/src/multi-items/trees.ts

@@ -1,360 +0,0 @@
-/**
- * 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 - TS2315 - Type 'ArrayNode' is not generic.
-    mappedArray: ArrayNode<CO, HO, TO>,
-    // @ts-expect-error - TS2315 - Type 'ArrayNode' is not generic.
-    originalArray: ArrayNode<CI, HI, TI>,
-    shape: ArrayShape,
-    path: Path,
-    // @ts-expect-error - 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 - 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 - 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 - 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 - 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 - 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 - 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 - 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 - TS2769 - No overload matches this call.
-                    `${["<root>"].concat(path).join(".")}. Expected array.`,
-                Errors.Internal,
-            );
-        }
-
-        const elementShape = shape.elementShape;
-        // @ts-expect-error - 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 - 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 - 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 - 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 - TS2339 - Property 'type' does not exist on type 'never'.
-        `unexpected shape type ${shape.type}`,
-        Errors.InvalidInput,
-    );
-}

package/src/multi-items.ts

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