@khanacademy/perseus 19.1.4 → 19.1.6

package/src/multi-items/__tests__/prop-type-builders.test.ts

@@ -1,133 +0,0 @@
-import {treeToItem} from "../items";
-import {buildPropTypeForShape} from "../prop-type-builders";
-import shapes from "../shapes";
-
-// TODO(emily): [PERSEUS_MERGE] Calling prop types as a function fails these
-// tests. Rewrite them once we're using the prop-types library.
-describe.skip("buildPropTypeForShape", () => {
-    // The value we're wrapping might not be a valid ItemTree - that's the
-    // point of testing this PropType - so we disable type checking by casting
-    // `value` to type `any`. The current implementation of `treeToItem` can
-    // handle that possibility.
-    const tryPropType = (propType: any, value: any) =>
-        propType({value: treeToItem(value)}, "value", "<function tryPropType>");
-
-    const assertPropTypePasses = (propType, value) =>
-        expect(null).toEqual(tryPropType(propType, value));
-
-    const assertPropTypeFails = (propType, value) =>
-        expect(tryPropType(propType, value) instanceof Error).toBeTruthy();
-
-    it("validates a content node", () => {
-        const propType = buildPropTypeForShape(shapes.content);
-
-        // Perseus has default values for all item fields, so all except the
-        // type are optional.
-        assertPropTypePasses(propType, {__type: "content"});
-        assertPropTypePasses(propType, {
-            content: "",
-            widgets: {},
-            images: {},
-            __type: "content",
-        });
-
-        // We also leave the full object optional by default, like the propType
-        // primitives.
-        assertPropTypePasses(propType, null);
-
-        // But specifying a bad type for any field will fail the propType.
-        assertPropTypeFails(propType, {content: 1, __type: "content"});
-        assertPropTypeFails(propType, {widgets: 1, __type: "content"});
-        assertPropTypeFails(propType, {images: 1, __type: "content"});
-    });
-
-    // TODO(mdr): Remove #LegacyContentNode support.
-    it("validates a legacy content node", () => {
-        const propType = buildPropTypeForShape(shapes.content);
-
-        // Perseus has default values for all item fields, so all except the
-        // type are optional.
-        assertPropTypePasses(propType, {__type: "item"});
-        assertPropTypePasses(propType, {
-            content: "",
-            widgets: {},
-            images: {},
-            __type: "item",
-        });
-
-        // We also leave the full object optional by default, like the propType
-        // primitives.
-        assertPropTypePasses(propType, null);
-
-        // But specifying a bad type for any field will fail the propType.
-        assertPropTypeFails(propType, {content: 1, __type: "item"});
-        assertPropTypeFails(propType, {widgets: 1, __type: "item"});
-        assertPropTypeFails(propType, {images: 1, __type: "item"});
-    });
-
-    it("validates a hint node", () => {
-        const propType = buildPropTypeForShape(shapes.hint);
-
-        // Perseus has default values for all hint fields, so all except the
-        // type are optional.
-        assertPropTypePasses(propType, {__type: "hint"});
-        assertPropTypePasses(propType, {
-            content: "",
-            widgets: {},
-            images: {},
-            replace: false,
-            __type: "hint",
-        });
-
-        // We also leave the full object optional by default, like the propType
-        // primitives.
-        assertPropTypePasses(propType, null);
-
-        // But specifying a bad type for any field will fail the propType.
-        assertPropTypeFails(propType, {content: 1, __type: "hint"});
-        assertPropTypeFails(propType, {widgets: 1, __type: "hint"});
-        assertPropTypeFails(propType, {images: 1, __type: "hint"});
-        assertPropTypeFails(propType, {replace: 1, __type: "hint"});
-    });
-
-    it("validates an array", () => {
-        const propType = buildPropTypeForShape(shapes.arrayOf(shapes.content));
-        const emptyItem = {__type: "content"} as const;
-
-        assertPropTypePasses(propType, []);
-        assertPropTypePasses(propType, [emptyItem, emptyItem, emptyItem]);
-
-        // While the array itself is optional, its elements are required.
-        assertPropTypePasses(propType, null);
-        assertPropTypeFails(propType, [emptyItem, null, emptyItem]);
-    });
-
-    it("validates tags", () => {
-        const propType = buildPropTypeForShape(shapes.tags);
-
-        assertPropTypePasses(propType, []);
-        assertPropTypePasses(propType, ["a", "b", "c"]);
-
-        assertPropTypePasses(propType, null);
-        assertPropTypeFails(propType, ["a", null, "b"]);
-        assertPropTypeFails(propType, [1, 2, 3]);
-    });
-
-    it("validates an object", () => {
-        const propType = buildPropTypeForShape(
-            shapes.shape({
-                a: shapes.content,
-                b: shapes.content,
-            }),
-        );
-        const emptyItem = {__type: "content"} as const;
-
-        assertPropTypePasses(propType, {a: emptyItem, b: emptyItem});
-
-        // While the object itself is optional, its fields are required.
-        assertPropTypePasses(propType, null);
-        assertPropTypeFails(propType, {});
-        assertPropTypeFails(propType, {a: emptyItem});
-        assertPropTypeFails(propType, {b: emptyItem});
-    });
-});

package/src/multi-items/__tests__/shapes.test.ts

@@ -1,43 +0,0 @@
-import shapes from "../shapes";
-
-describe("shapes.content", () => {
-    it('has type "content"', () => {
-        const shape = shapes.content;
-        expect("content").toEqual(shape.type);
-    });
-});
-
-describe("shapes.hint", () => {
-    it('has type "hint"', () => {
-        const shape = shapes.hint;
-        expect("hint").toEqual(shape.type);
-    });
-});
-
-describe("shapes.arrayOf", () => {
-    it('has type "array"', () => {
-        const shape = shapes.arrayOf(shapes.content);
-        expect("array").toEqual(shape.type);
-    });
-
-    it("has the given shape as its `elementShape` property", () => {
-        const shape = shapes.arrayOf(shapes.content);
-        expect(shapes.content).toEqual(shape.elementShape);
-    });
-});
-
-describe("shapes.shape", () => {
-    it('has type "object"', () => {
-        const shape = shapes.shape({});
-        expect("object").toEqual(shape.type);
-    });
-
-    it("has the given shapes as its `shape` property", () => {
-        const shape = shapes.shape({
-            foo: shapes.content,
-            bar: shapes.hint,
-        });
-        expect(shapes.content).toEqual(shape.shape.foo);
-        expect(shapes.hint).toEqual(shape.shape.bar);
-    });
-});

package/src/multi-items/__tests__/trees.test.ts

@@ -1,317 +0,0 @@
-import shapes from "../shapes";
-import {buildMapper} from "../trees";
-
-import type {
-    ItemTree,
-    ContentNode,
-    HintNode,
-    TagsNode,
-    ItemArrayNode,
-} from "../item-types";
-import type {TreeMapper} from "../trees";
-
-describe("buildMapper", () => {
-    function content(n): ContentNode {
-        return {
-            __type: "content",
-            content: `content ${n}`,
-        };
-    }
-
-    function hint(n: number): HintNode {
-        return {
-            __type: "hint",
-            content: `hint ${n}`,
-        };
-    }
-
-    function tags(...elements): TagsNode {
-        // This function mostly exists as a shorthand way to clarify to TypeScript
-        // that this is a TagsNode, not a confused ItemArrayNode.
-        return elements;
-    }
-
-    function array(...elements): ItemArrayNode {
-        // This function mostly exists as a shorthand way to clarify to TypeScript
-        // that this is an ItemArrayNode, not a confused TagsNode.
-        /**
-         * TODO(somewhatabstract, JIRA-XXXX):
-         * The Tree types are really hard to work with properly.
-         */
-        return elements;
-    }
-
-    const shape = shapes.shape({
-        a: shapes.content,
-        b: shapes.arrayOf(shapes.content),
-        c: shapes.shape({
-            d: shapes.content,
-            e: shapes.hint,
-        }),
-        f: shapes.hint,
-        g: shapes.tags,
-    });
-
-    const tree: ItemTree = {
-        a: content(1),
-        b: array(content(2), content(3), content(4)),
-        c: {
-            d: content(5),
-            e: hint(6),
-        },
-        f: hint(7),
-        g: tags("foo", "bar"),
-    };
-
-    it("calls the content mapper for each of the content nodes", () => {
-        const calledWith = [];
-        buildMapper()
-            // @ts-expect-error - TS2345 - Argument of type 'unknown' is not assignable to parameter of type 'never'.
-            .setContentMapper((c) => calledWith.push(c))
-            .mapTree(tree, shape);
-        calledWith.sort();
-
-        expect([
-            content(1),
-            content(2),
-            content(3),
-            content(4),
-            content(5),
-        ]).toEqual(calledWith);
-    });
-
-    it("calls the hint mapper for each of the hint nodes", () => {
-        const calledWith = [];
-        buildMapper()
-            // @ts-expect-error - TS2345 - Argument of type 'unknown' is not assignable to parameter of type 'never'.
-            .setHintMapper((h) => calledWith.push(h))
-            .mapTree(tree, shape);
-        calledWith.sort();
-
-        expect([hint(6), hint(7)]).toEqual(calledWith);
-    });
-
-    it("calls the tags mapper for each of the tags nodes", () => {
-        const calledWith: Array<TagsNode | any> = [];
-        buildMapper()
-            .setTagsMapper((t) => calledWith.push(t))
-            .mapTree(tree, shape);
-        calledWith.sort();
-
-        expect([["foo", "bar"]]).toEqual(calledWith);
-    });
-
-    it("returns a mapped tree with the correct shape", () => {
-        const mapper: TreeMapper<
-            ContentNode,
-            string,
-            HintNode,
-            string,
-            TagsNode,
-            string
-        > = buildMapper()
-            // @ts-expect-error - TS2571 - Object is of type 'unknown'.
-            .setContentMapper((c) => `mapped content: ${c.content || "<none>"}`)
-            // @ts-expect-error - TS2571 - Object is of type 'unknown'.
-            .setHintMapper((h) => `mapped hint: ${h.content || "<none>"}`)
-            .setTagsMapper((t) => `mapped tags: ${t.join(", ")}`);
-        const result = mapper.mapTree(tree, shape);
-
-        expect({
-            a: "mapped content: content 1",
-            b: [
-                "mapped content: content 2",
-                "mapped content: content 3",
-                "mapped content: content 4",
-            ],
-            c: {
-                d: "mapped content: content 5",
-                e: "mapped hint: hint 6",
-            },
-            f: "mapped hint: hint 7",
-            g: "mapped tags: foo, bar",
-        }).toEqual(result);
-    });
-
-    it("provides each node shape to the leaf mappers", () => {
-        // Return the type of the shape of the node in place of each node.
-        const result = buildMapper()
-            .setContentMapper((_, s) => s.type)
-            .setHintMapper((_, s) => s.type)
-            .setTagsMapper((_, s) => s.type)
-            .mapTree(tree, shape);
-
-        expect({
-            a: "content",
-            b: ["content", "content", "content"],
-            c: {
-                d: "content",
-                e: "hint",
-            },
-            f: "hint",
-            g: "tags",
-        }).toEqual(result);
-    });
-
-    it("provides each node path to the leaf mappers", () => {
-        // Return the path to the node in place of each node.
-        const result = buildMapper()
-            .setContentMapper((_, __, p) => p)
-            .setHintMapper((_, __, p) => p)
-            .setTagsMapper((_, __, p) => p)
-            .mapTree(tree, shape);
-
-        expect({
-            a: ["a"],
-            b: [
-                ["b", 0],
-                ["b", 1],
-                ["b", 2],
-            ],
-            c: {
-                d: ["c", "d"],
-                e: ["c", "e"],
-            },
-            f: ["f"],
-            g: ["g"],
-        }).toEqual(result);
-    });
-
-    it("handles recursive objects", () => {
-        const shape = shapes.shape({
-            a: shapes.shape({
-                b: shapes.shape({
-                    c: shapes.content,
-                }),
-            }),
-        });
-
-        const tree = {a: {b: {c: content(1)}}} as const;
-
-        // @ts-expect-error - TS2322 - Type 'TreeMapperJustForLeaves<ContentNode, string | null | undefined, unknown, unknown, unknown, unknown>' is not assignable to type 'TreeMapper<ContentNode, string | null | undefined, HintNode, HintNode, TagsNode, TagsNode>'.
-        const mapper: TreeMapper<
-            ContentNode,
-            string | null | undefined,
-            HintNode,
-            HintNode,
-            TagsNode,
-            TagsNode
-        > = buildMapper().setContentMapper((c) => c.content);
-        const result = mapper.mapTree(tree, shape);
-
-        expect({a: {b: {c: "content 1"}}}).toEqual(result);
-    });
-
-    it("handles recursive arrays", () => {
-        const shape = shapes.arrayOf(
-            shapes.arrayOf(shapes.arrayOf(shapes.content)),
-        );
-
-        const tree = array(
-            array(array(content(0)), array(content(1))),
-            array(array(content(2)), array(content(3), content(4))),
-        );
-
-        // @ts-expect-error - TS2322 - Type 'TreeMapperJustForLeaves<ContentNode, string | null | undefined, unknown, unknown, unknown, unknown>' is not assignable to type 'TreeMapper<ContentNode, string | null | undefined, HintNode, HintNode, TagsNode, TagsNode>'.
-        const mapper: TreeMapper<
-            ContentNode,
-            string | null | undefined,
-            HintNode,
-            HintNode,
-            TagsNode,
-            TagsNode
-        > = buildMapper().setContentMapper((c) => c.content);
-        const result = mapper.mapTree(tree, shape);
-
-        expect([
-            [["content 0"], ["content 1"]],
-            [["content 2"], ["content 3", "content 4"]],
-        ]).toEqual(result);
-    });
-
-    it("handles empty arrays", () => {
-        const shape = shapes.arrayOf(shapes.arrayOf(shapes.content));
-
-        const tree = array(array(), array(content(1)), array());
-
-        // @ts-expect-error - TS2322 - Type 'TreeMapperJustForLeaves<ContentNode, string | null | undefined, unknown, unknown, unknown, unknown>' is not assignable to type 'TreeMapper<ContentNode, string | null | undefined, HintNode, HintNode, TagsNode, TagsNode>'.
-        const mapper: TreeMapper<
-            ContentNode,
-            string | null | undefined,
-            HintNode,
-            HintNode,
-            TagsNode,
-            TagsNode
-        > = buildMapper().setContentMapper((c) => c.content);
-
-        // Test the outer array being empty.
-        expect([]).toEqual(mapper.mapTree(array(), shape));
-
-        // Test inner arrays being empty.
-        const result = mapper.mapTree(tree, shape);
-        expect([[], ["content 1"], []]).toEqual(result);
-    });
-
-    it("calls the array mapper for arrays", () => {
-        const shape = shapes.arrayOf(shapes.content);
-        const tree = array(content(1), content(2), content(3));
-
-        let wasCalled = false;
-        let callArgs: Record<string, any> = {};
-        // @ts-expect-error - TS2322 - Type 'TreeMapperForLeavesAndCollections<unknown, any, unknown, unknown, unknown, unknown>' is not assignable to type 'TreeMapper<ContentNode, string | null | undefined, HintNode, HintNode, TagsNode, TagsNode>'.
-        const mapper: TreeMapper<
-            ContentNode,
-            string | null | undefined,
-            HintNode,
-            HintNode,
-            TagsNode,
-            TagsNode
-        > = buildMapper()
-            // @ts-expect-error - TS2571 - Object is of type 'unknown'.
-            .setContentMapper((c) => c.content)
-            .setArrayMapper((mappedArray, originalArray, shape, path) => {
-                wasCalled = true;
-                callArgs = {mappedArray, originalArray, shape, path};
-                return mappedArray;
-            });
-        mapper.mapTree(tree, shape);
-
-        expect(wasCalled).toBeTruthy();
-
-        expect(["content 1", "content 2", "content 3"]).toEqual(
-            callArgs.mappedArray,
-        );
-        expect(tree).toEqual(callArgs.originalArray);
-        expect(shape).toEqual(callArgs.shape);
-        expect([]).toEqual(callArgs.path);
-    });
-
-    it("uses the array mapper return value to construct the new tree", () => {
-        const mapper = buildMapper()
-            // @ts-expect-error - TS2571 - Object is of type 'unknown'.
-            .setContentMapper((c) => c.content)
-            // @ts-expect-error - TS2571 - Object is of type 'unknown'.
-            .setHintMapper((h) => h.content)
-            // @ts-expect-error - TS2571 - Object is of type 'unknown'.
-            .setTagsMapper((t) => t.join(", "))
-            .setArrayMapper((mappedArray, originalArray, shape, path) => {
-                return mappedArray.map((child) => `${String(child)} in array`);
-            });
-        const result = mapper.mapTree(tree, shape);
-
-        expect({
-            a: "content 1",
-            b: [
-                "content 2 in array",
-                "content 3 in array",
-                "content 4 in array",
-            ],
-            c: {
-                d: "content 5",
-                e: "hint 6",
-            },
-            f: "hint 7",
-            g: "foo, bar",
-        }).toEqual(result);
-    });
-});

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

@@ -1,56 +0,0 @@
-/**
- * Type definitions for multi-item types, including:
- *
- * - Item: A multi-item tree wrapped in a `_multi` key, to help us recognize it
- *         as a multi-item in other contexts and avoid misinterpreting its
- *         other properties.
- * - ItemTree: A multi-item without the `_multi` key. Conforms to the Tree
- *             interface, so it's compatible with our tree traversal functions.
- * - And the various types of nodes that compose a tree.
- */
-import type {Tree, ArrayNode, ObjectNode} from "./tree-types";
-import type {WidgetDict, ImageDict} from "../types";
-
-export type ContentNode = {
-    // TODO(mdr): When we first drafted the multi-item feature, we named
-    //     content nodes "item" nodes, and later decided the term was
-    //     ambiguous and switched to "content". But we're temporarily keeping
-    //     support for the "item" string when inferring item shape, so that we
-    //     don't crash on multi-items we've already created - but all new
-    //     content nodes will be generated with the "content" string.
-    //
-    //     Code blocks that enable this legacy support are greppable with the
-    //     keyword #LegacyContentNode.
-    __type: "content" | "item";
-    // Perseus has default values for these fields, so they're all optional.
-    content?: string | null | undefined;
-    images?: ImageDict | null | undefined;
-    widgets?: WidgetDict | null | undefined;
-};
-export type HintNode = {
-    __type: "hint";
-    // Perseus has default values for these fields, so they're all optional.
-    content?: string | null | undefined;
-    images?: ImageDict | null | undefined;
-    widgets?: WidgetDict | null | undefined;
-    replace?: boolean | null | undefined;
-};
-export type TagsNode = ReadonlyArray<string>;
-
-// @ts-expect-error - TS2315 - Type 'ArrayNode' is not generic.
-export type ItemArrayNode = ArrayNode<ContentNode, HintNode, TagsNode>;
-export type ItemObjectNode = ObjectNode<ContentNode, HintNode, TagsNode>;
-// @ts-expect-error - TS2315 - Type 'Tree' is not generic.
-export type ItemTree = Tree<ContentNode, HintNode, TagsNode>;
-
-// TODO(jeremy): I think we could refine this root type for multi items. Right
-// now a _multi's value can be _anything_ including "primitive" node types such
-// as "type: content" or "type: hint". That doesn't seem to match the shapes
-// that are in use to date. We could also move to a strict type at that point
-// because it appears that we _never_ add other root keys to an item that
-// specifies the `_multi` key. I think we'd be safe to restrict this root
-// object type to something like the following:
-// export type Item = {|_multi: ItemArrayNode | ItemObjectNode|};
-export type Item = {
-    _multi: ItemTree;
-};