@khanacademy/perseus 0.0.1 → 0.2.1

package/src/multi-items/__tests__/prop-type-builders_test.js

@@ -0,0 +1,134 @@
+// @flow
+import {treeToItem} from "../items.js";
+import {buildPropTypeForShape} from "../prop-type-builders.js";
+import shapes from "../shapes.js";
+
+// 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 Flow checking by casting
+    // `value` to type `any`. The current implementation of `treeToItem` can
+    // handle that possibility.
+    const tryPropType = (propType, 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"};
+
+        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"};
+
+        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.js

@@ -0,0 +1,44 @@
+// @flow
+import shapes from "../shapes.js";
+
+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.js

@@ -0,0 +1,316 @@
+// @flow
+import shapes from "../shapes.js";
+import {buildMapper} from "../trees.js";
+
+import type {
+    ItemTree,
+    ContentNode,
+    HintNode,
+    TagsNode,
+    ItemArrayNode,
+} from "../item-types.js";
+import type {TreeMapper} from "../trees.js";
+
+describe("buildMapper", () => {
+    function content(n): ContentNode {
+        return {
+            __type: "content",
+            content: `content ${n}`,
+        };
+    }
+
+    function hint(n): HintNode {
+        return {
+            __type: "hint",
+            content: `hint ${n}`,
+        };
+    }
+
+    function tags(...elements): TagsNode {
+        // This function mostly exists as a shorthand way to clarify to Flow
+        // 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 Flow
+        // that this is an ItemArrayNode, not a confused TagsNode.
+        /**
+         * TODO(somewhatabstract, JIRA-XXXX):
+         * The Tree types are really hard to work with properly.
+         */
+        // $FlowFixMe[incompatible-return]
+        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()
+            .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()
+            .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 = [];
+        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()
+            .setContentMapper((c) => `mapped content: ${c.content || "<none>"}`)
+            .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)}}};
+
+        const mapper: TreeMapper<
+            ContentNode,
+            ?string,
+            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))),
+        );
+
+        const mapper: TreeMapper<
+            ContentNode,
+            ?string,
+            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());
+
+        const mapper: TreeMapper<
+            ContentNode,
+            ?string,
+            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 = {};
+        const mapper: TreeMapper<
+            ContentNode,
+            ?string,
+            HintNode,
+            HintNode,
+            TagsNode,
+            TagsNode,
+        > = buildMapper()
+            .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()
+            // $FlowFixMe[not-a-function]
+            // $FlowFixMe[prop-missing]
+            // $FlowFixMe[incompatible-use]
+            .setContentMapper((c) => c.content)
+            // $FlowFixMe[not-a-function]
+            // $FlowFixMe[prop-missing]
+            // $FlowFixMe[incompatible-use]
+            .setHintMapper((h) => h.content)
+            // $FlowFixMe[not-a-function]
+            // $FlowFixMe[prop-missing]
+            .setTagsMapper((t) => t.join(", "))
+            .setArrayMapper((mappedArray, originalArray, shape, path) => {
+                // $FlowFixMe[prop-missing]
+                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.js

@@ -0,0 +1,55 @@
+// @flow
+/**
+ * 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 {WidgetDict, ImageDict} from "../types.js";
+import type {Tree, ArrayNode, ObjectNode} from "./tree-types.js";
+
+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,
+    images?: ?ImageDict,
+    widgets?: ?WidgetDict,
+    ...
+};
+export type HintNode = {
+    __type: "hint",
+    // Perseus has default values for these fields, so they're all optional.
+    content?: ?string,
+    images?: ?ImageDict,
+    widgets?: ?WidgetDict,
+    replace?: ?boolean,
+    ...
+};
+export type TagsNode = $ReadOnlyArray<string>;
+
+export type ItemArrayNode = ArrayNode<ContentNode, HintNode, TagsNode>;
+export type ItemObjectNode = ObjectNode<ContentNode, HintNode, TagsNode>;
+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, ...};