@khanacademy/perseus 0.0.1 → 0.2.1

package/src/multi-items/shapes.js

@@ -0,0 +1,53 @@
+// @flow
+/**
+ * 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.js";
+
+/**
+ * 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.js

@@ -0,0 +1,42 @@
+// @flow
+/**
+ * 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.
+export type ArrayNode<C, H, T> = Tree<C, H, T>;
+export type ObjectNode<C, H, T> = {[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.
+ */
+export type Tree<C, H, T> =
+    | C
+    | H
+    | T
+    | ArrayNode<C, H, T>
+    | ObjectNode<C, H, T>;

package/src/multi-items/trees.js

@@ -0,0 +1,345 @@
+// @flow
+/**
+ * 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.js";
+import {PerseusError} from "../perseus-error.js";
+
+import type {
+    Shape,
+    ContentShape,
+    HintShape,
+    TagsShape,
+    ArrayShape,
+} from "./shape-types.js";
+import type {Tree, ArrayNode, ObjectNode} from "./tree-types.js";
+
+/**
+ * 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> = (
+    mappedArray: ArrayNode<CO, HO, TO>,
+    originalArray: ArrayNode<CI, HI, TI>,
+    shape: ArrayShape,
+    path: Path,
+) => 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>;
+    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,
+        );
+    }
+
+    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,
+        );
+    }
+
+    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.
+ */
+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>(
+    tree: Tree<CI, HI, TI>,
+    shape: Shape,
+    path: Path,
+    mappers: TreeMapper<CI, CO, HI, HO, TI, TO>,
+): 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: any);
+        return mappers.content(content, shape, path);
+    }
+    if (shape.type === "hint") {
+        const hint: HI = (tree: any);
+        return mappers.hint(hint, shape, path);
+    }
+    if (shape.type === "tags") {
+        const tags: TI = (tree: any);
+        return mappers.tags(tags, shape, path);
+    }
+    if (shape.type === "array") {
+        const array: ArrayNode<CI, HI, TI> = (tree: any);
+
+        if (!Array.isArray(array)) {
+            throw new PerseusError(
+                `Invalid object of type "${typeof array}" found at path ` +
+                    `${["<root>"].concat(path).join(".")}. Expected array.`,
+                Errors.Internal,
+            );
+        }
+
+        const elementShape = shape.elementShape;
+        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: any);
+
+        if (object && typeof object !== "object") {
+            throw new PerseusError(
+                `Invalid object of type "${typeof object}" found at ` +
+                    `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 ` +
+                    `${["<root>"].concat(path).join(".")}.`,
+                Errors.InvalidInput,
+            );
+        }
+        const newObject = {};
+        Object.keys(valueShapes).forEach((key) => {
+            if (!(key in object)) {
+                throw new PerseusError(
+                    `Key "${key}" is missing from shape at path ` +
+                        `${["<root>"].concat(path).join(".")}.`,
+                    Errors.InvalidInput,
+                );
+            }
+
+            newObject[key] = mapTree(
+                object[key],
+                valueShapes[key],
+                path.concat(key),
+                mappers,
+            );
+        });
+        return newObject;
+    }
+    throw new PerseusError(
+        `unexpected shape type ${shape.type}`,
+        Errors.InvalidInput,
+    );
+}

package/src/multi-items.js

@@ -0,0 +1,76 @@
+// @flow
+/**
+ * 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.js";
+import MultiRenderer from "./multi-items/multi-renderer.jsx";
+import {buildPropTypeForShape} from "./multi-items/prop-type-builders.js";
+import shapes from "./multi-items/shapes.js";
+
+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,
+};

package/src/not-gorgon.js

@@ -0,0 +1,129 @@
+// @flow
+import {debounce} from "underscore";
+
+import Rule from "./gorgon/rule.js";
+
+/**
+ * NotGorgon asynchronously calls Khan Academy's poentry linter.
+ *
+ * The poentry linter checks for issues that prevent content from being
+ * translated. This linter is KA-specific and so NotGorgon does not do anything
+ * in non-KA environments.
+ *
+ * NotGorgon is named as such because it is not Gorgon, Perseus' built-in
+ * linter.
+ */
+
+// A LintCB is called once the linter has been run.
+type LintCB = (errors: $ReadOnlyArray<string>) => void;
+
+// msec to wait before we actually call the linter after receiving the
+// last call. The timer is reset if the lint is called during the wait.
+const DEBOUNCE_TIMEOUT = 1000;
+
+export default class NotGorgon {
+    // To avoid linting when nothing has changed.
+    previousContent: ?string = null;
+
+    /**
+     * Runs the poentry linter on the given perseus string asynchronously.
+     *
+     * It doesn't do anything unless we're in a KA environment.
+     *
+     * onLintErrorsGenerated is called even if there are no errors. It is not
+     * called if perseusStr is unchanged from the last call.
+     *
+     * Linting is relatively expensive -- so we debounce linting each instance
+     * for some amount of time.
+     */
+    runLinter: any = debounce(
+        (perseusStr: string, onLintErrorsGenerated: LintCB) => {
+            // $FlowFixMe[cannot-resolve-name] -- TODO(joshuan): use an api flag instead?
+            if (typeof KA === "undefined") {
+                return;
+            }
+
+            if (perseusStr === this.previousContent) {
+                return;
+            }
+
+            this.previousContent = perseusStr;
+
+            if (perseusStr === "") {
+                onLintErrorsGenerated([]);
+                return;
+            }
+
+            fetch("/api/internal/translations/lint_poentry?preview=1&lang=en", {
+                headers: {"Content-Type": "application/json"},
+                body: JSON.stringify({
+                    // The poentry linter verifies that the translation from
+                    // the original text to the translated text is sane. We
+                    // want to ensure that the translation from English to
+                    // English is sane, so msgid === mstr.
+                    msgid: perseusStr, // msgid is the original text
+                    msgstr: perseusStr, // msgstr is the translated text
+                    format: "perseus_text",
+                    filename: "",
+                }),
+                method: "POST",
+            })
+                .then(
+                    (response) => {
+                        if (response.status >= 400) {
+                            return {
+                                status: "error",
+                                message: "Could not run i18n linter.",
+                            };
+                        }
+                        return response.json();
+                    },
+                    (rejection) => {
+                        return {
+                            status: "error",
+                            message: "Could not run i18n linter.",
+                        };
+                    },
+                )
+                .then((json) => {
+                    if (json.status === "error") {
+                        onLintErrorsGenerated([
+                            "Some part of this text makes it untranslatable. " +
+                                "The specific message from the i18n linter was: " +
+                                json.message.replace(/\n/g, " "),
+                        ]);
+                    } else {
+                        onLintErrorsGenerated([]);
+                    }
+                });
+        },
+        DEBOUNCE_TIMEOUT,
+    );
+
+    /**
+     * Applies an array of errors generated by linters without position
+     * information (NotGorgon and the legacy getSaveWarnings()) to the top
+     * of a Perseus tree.
+     */
+    applyLintErrors(
+        parsedMarkdown: any,
+        notGorgonLintErrors: $ReadOnlyArray<string>,
+    ) {
+        // These lint errors do not have position data associated with
+        // them, so we just plop them at the top.
+        if (notGorgonLintErrors.length) {
+            const errorText = notGorgonLintErrors.join("\n\n");
+            parsedMarkdown.unshift({
+                content: {
+                    type: "text",
+                    content: "",
+                },
+                insideTable: false,
+                message: errorText,
+                ruleName: "legacy-error",
+                severity: Rule.Severity.ERROR,
+                type: "lint",
+            });
+        }
+    }
+}