@khanacademy/perseus 2.1.0 → 4.0.0

package/dist/mixins/widget-jsonify-deprecated.js.flow

@@ -0,0 +1,11 @@
+/**
+ * Flowtype definitions for data
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+declare var WidgetJsonifyDeprecated: {|
+  +getUserInput: () => any,
+  +getUserInputFromProps: (props: any) => any,
+|};
+declare export default typeof WidgetJsonifyDeprecated;

package/dist/mixins/widget-prop-denylist.d.ts

@@ -0,0 +1,14 @@
+/**
+ * These are things that widgets should exclude when serializing themselves.
+ *
+ * The use of this list needs to die. Basically, there are codepaths that
+ * blindly serialize the "props" of a widget so that it can pass around its
+ * info. Unfortunately, props aren't guaranteed to be serializable, and
+ * automatically serializing schemaless list of attributes causes issues (e.g.
+ * circular JSON structures sometimes).
+ *
+ * This blocks things that we know don't need to be serialized.
+ */
+declare const denylist: string[];
+export declare const removeDenylistProps: (props: any) => any;
+export default denylist;

package/dist/mixins/widget-prop-denylist.js.flow

@@ -0,0 +1,20 @@
+/**
+ * Flowtype definitions for data
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+/**
+ * These are things that widgets should exclude when serializing themselves.
+ *
+ * The use of this list needs to die. Basically, there are codepaths that
+ * blindly serialize the "props" of a widget so that it can pass around its
+ * info. Unfortunately, props aren't guaranteed to be serializable, and
+ * automatically serializing schemaless list of attributes causes issues (e.g.
+ * circular JSON structures sometimes).
+ *
+ * This blocks things that we know don't need to be serialized.
+ */
+declare var denylist: string[];
+declare export var removeDenylistProps: (props: any) => any;
+declare export default typeof denylist;

package/dist/multi-items/item-types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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";
+import type { Tree, ArrayNode, ObjectNode } from "./tree-types";
+export type ContentNode = {
+    __type: "content" | "item";
+    content?: string | null | undefined;
+    images?: ImageDict | null | undefined;
+    widgets?: WidgetDict | null | undefined;
+};
+export type HintNode = {
+    __type: "hint";
+    content?: string | null | undefined;
+    images?: ImageDict | null | undefined;
+    widgets?: WidgetDict | null | undefined;
+    replace?: boolean | null | undefined;
+};
+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>;
+export type Item = {
+    _multi: ItemTree;
+};

package/dist/multi-items/items.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Utility functions for constructing and manipulating multi-items.
+ *
+ * These functions apply *specifically* to Items and ItemTrees - things that
+ * actually semantically *are* multi-items. For more general functions for
+ * traversing and manipulating *anything* shaped like a multi-item (like a
+ * renderer tree or a score tree or, well, a multi-item), see trees.js.
+ */
+import type { Item, ItemTree, ContentNode, HintNode } from "./item-types";
+import type { Shape } from "./shape-types";
+/**
+ * Return a semantically empty ItemTree that conforms to the given shape.
+ *
+ * - An empty content node has an empty content string and no widgets/images.
+ * - An empty hint node has an empty content string and no widgets/images.
+ * - An empty array node has no elements.
+ * - An empty object node has a semantically empty node for each of its keys.
+ *   (That is, we recursively call buildEmptyItemTreeForShape for each key.)
+ */
+export declare function buildEmptyItemTreeForShape(shape: Shape): ItemTree;
+/**
+ * Return a semantically empty Item that conforms to the given shape.
+ *
+ * - An empty content node has an empty content string and no widgets/images.
+ * - An empty hint node has an empty content string and no widgets/images.
+ * - An empty array node has no elements.
+ * - An empty object node has a semantically empty node for each of its keys.
+ *   (That is, we recursively call buildEmptyItemTreeForShape for each key.)
+ */
+export declare function buildEmptyItemForShape(shape: Shape): Item;
+/**
+ * Given an Item and its Shape, yield all of its content nodes to the callback.
+ */
+export declare function findContentNodesInItem(item: Item, shape: Shape, callback: (c: ContentNode) => any): void;
+/**
+ * Given an Item and its Shape, yield all of its hint nodes to the callback.
+ */
+export declare function findHintNodesInItem(item: Item, shape: Shape, callback: (h: HintNode) => any): void;
+/**
+ * Given an ItemTree, return a Shape that it conforms to.
+ *
+ * The Shape might not be complete or correct Shape that this Item was designed
+ * for. If you have access to the intended Shape, use that instead.
+ */
+export declare function inferItemShape(item: Item): Shape;
+/**
+ * Convert the given Item to an ItemTree, by unwrapping the `_multi` key.
+ */
+export declare function itemToTree(item: Item): ItemTree;
+/**
+ * Convert the given ItemTree to an Item, by wrapping it in the `_multi` key.
+ */
+export declare function treeToItem(node: ItemTree): Item;

package/dist/multi-items/items.js.flow

@@ -0,0 +1,66 @@
+/**
+ * Flowtype definitions for data
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+import type { Item, ItemTree, ContentNode, HintNode } from "./item-types";
+import type { Shape } from "./shape-types";
+
+/**
+ * Return a semantically empty ItemTree that conforms to the given shape.
+ *
+ * - An empty content node has an empty content string and no widgets/images.
+ * - An empty hint node has an empty content string and no widgets/images.
+ * - An empty array node has no elements.
+ * - An empty object node has a semantically empty node for each of its keys.
+ *   (That is, we recursively call buildEmptyItemTreeForShape for each key.)
+ */
+declare export function buildEmptyItemTreeForShape(shape: Shape): ItemTree;
+
+/**
+ * Return a semantically empty Item that conforms to the given shape.
+ *
+ * - An empty content node has an empty content string and no widgets/images.
+ * - An empty hint node has an empty content string and no widgets/images.
+ * - An empty array node has no elements.
+ * - An empty object node has a semantically empty node for each of its keys.
+ *   (That is, we recursively call buildEmptyItemTreeForShape for each key.)
+ */
+declare export function buildEmptyItemForShape(shape: Shape): Item;
+
+/**
+ * Given an Item and its Shape, yield all of its content nodes to the callback.
+ */
+declare export function findContentNodesInItem(
+  item: Item,
+  shape: Shape,
+  callback: (c: ContentNode) => any
+): void;
+
+/**
+ * Given an Item and its Shape, yield all of its hint nodes to the callback.
+ */
+declare export function findHintNodesInItem(
+  item: Item,
+  shape: Shape,
+  callback: (h: HintNode) => any
+): void;
+
+/**
+ * Given an ItemTree, return a Shape that it conforms to.
+ *
+ * The Shape might not be complete or correct Shape that this Item was designed
+ * for. If you have access to the intended Shape, use that instead.
+ */
+declare export function inferItemShape(item: Item): Shape;
+
+/**
+ * Convert the given Item to an ItemTree, by unwrapping the `_multi` key.
+ */
+declare export function itemToTree(item: Item): ItemTree;
+
+/**
+ * Convert the given ItemTree to an Item, by wrapping it in the `_multi` key.
+ */
+declare export function treeToItem(node: ItemTree): Item;

package/dist/multi-items/multi-renderer.d.ts

@@ -0,0 +1,152 @@
+import * as React from "react";
+import Renderer from "../renderer";
+import type { Widget } from "../renderer";
+import type { APIOptions, FilterCriterion } from "../types";
+import type { Item, ContentNode, HintNode, TagsNode } from "./item-types";
+import type { Shape, ArrayShape } from "./shape-types";
+import type { Tree } from "./tree-types";
+import type { TreeMapper, ContentMapper, HintMapper, Path } from "./trees";
+type Hint = any;
+type Score = any;
+type SerializedState = any;
+type RendererProps = JSX.LibraryManagedAttributes<typeof Renderer, React.ComponentProps<typeof Renderer>>;
+type ContentRendererElement = React.ReactElement<any>;
+type HintRendererElement = React.ReactElement<any>;
+type ContentRendererData = {
+    makeRenderer: () => ContentRendererElement;
+    ref: Renderer | null | undefined;
+};
+type FindWidgetsFunc = (criterion: FilterCriterion) => ReadonlyArray<Widget | null | undefined>;
+type HintRendererData = {
+    makeRenderer: () => HintRendererElement;
+    findExternalWidgets: FindWidgetsFunc | null | undefined;
+    ref: null;
+    hint: Hint;
+};
+type RendererData = ContentRendererData | HintRendererData;
+type RendererDataTree = Tree<ContentRendererData, HintRendererData, null>;
+/**
+ * TODO(somewhatabstract, JIRA-XXXX):
+ * Some usage of this type somewhere is causing Flow to believe that these
+ * elements should be components. Don't know where that is, to fix it up
+ * properly. In reality, these types are just too hard to use and aren't
+ * really helping us out as I now have to suppress this rather than
+ * get value from the type. :(
+ */
+type RendererTree = Tree<ContentRendererElement, HintRendererElement, null>;
+type ScoreTree = Tree<Score, null, null>;
+type SerializedStateTree = Tree<SerializedState, null, null>;
+type Props = {
+    item: Item;
+    shape: Shape;
+    children: (tree: {
+        renderers: RendererTree;
+    }) => React.ReactElement<any>;
+    serializedState?: SerializedStateTree | null | undefined;
+    onSerializedStateUpdated?: (state: SerializedStateTree) => void;
+    onInteractWithWidget?: (id: string) => void;
+    apiOptions?: APIOptions;
+    reviewMode?: boolean | null | undefined;
+};
+type State = {
+    rendererDataTree: RendererDataTree | null | undefined;
+    renderError: Error | null | undefined;
+};
+declare class MultiRenderer extends React.Component<Props, State> {
+    rendererDataTreeMapper: TreeMapper<ContentNode, ContentRendererData, HintNode, HintRendererData, TagsNode, null>;
+    getRenderersMapper: TreeMapper<ContentRendererData, ContentRendererElement, HintRendererData, HintRendererElement, null, null>;
+    constructor(props: Props);
+    UNSAFE_componentWillReceiveProps(nextProps: Props): void;
+    /**
+     * Attempt to build a State that includes a renderer tree corresponding to
+     * the item provided in props. On error, return a state with `renderError`
+     * set instead.
+     */
+    _tryMakeRendererState(props: Props): State;
+    _handleSerializedStateUpdated: (path: Path, newState?: any) => void;
+    /**
+     * Props that aren't directly used by the MultiRenderer are delegated to
+     * the underlying Renderers.
+     */
+    _getRendererProps(): RendererProps;
+    /**
+     * Construct a Renderer and a ref placeholder for the given ContentNode.
+     */
+    _makeContentRendererData(content: ContentNode, path: Path): ContentRendererData;
+    /**
+     * Construct a Renderer for the given HintNode, and keep track of the hint
+     * itself for future use, too.
+     */
+    _makeHintRendererData(hint: HintNode): HintRendererData;
+    /**
+     * Construct a tree of interconnected RendererDatas, corresponding to the
+     * given item. Called in `_tryMakeRendererState`, in order to store this
+     * tree in the component state.
+     */
+    _makeRendererDataTree(item: Item, shape: Shape): RendererDataTree;
+    /**
+     * Return all widgets that meet the given criterion, from all Renderers
+     * except the Renderer that triggered this call.
+     *
+     * This function is provided to each Renderer's `findExternalWidgets` prop,
+     * which enables widgets in different Renderers to discover each other and
+     * communicate.
+     */
+    _findWidgets(callingData: RendererData, filterCriterion: FilterCriterion): ReadonlyArray<Widget | null | undefined>;
+    /**
+     * Copy the renderer tree, apply the given transformation to the leaf nodes
+     * and the optional given transformation to the array nodes, and return the
+     * result.
+     *
+     * Used to provide structured data to the call site (the Renderer tree on
+     * `render`, the Score tree on `getScores`, etc.), and to traverse the
+     * renderer tree even when we disregard the output (like in
+     * `_findWidgets`).
+     */
+    _mapRenderers<O>(leafMapper: ContentMapper<RendererData, O> & HintMapper<RendererData, O>): Tree<O, O, null> | null | undefined;
+    _scoreFromRef(ref?: Renderer | null): Score;
+    /**
+     * Return a tree in the shape of the multi-item, with scores at each of
+     * the content nodes and `null` at the other leaf nodes.
+     */
+    getScores(): ScoreTree;
+    /**
+     * Return a single composite score for all rendered content nodes.
+     * The `guess` is a tree in the shape of the multi-item, with an individual
+     * guess at each content node and `null` at the other leaf nodes.
+     */
+    score(): Score;
+    /**
+     * Return a tree in the shape of the multi-item, with serialized state at
+     * each of the content nodes and `null` at the other leaf nodes.
+     *
+     * If the lastSerializedState argument is supplied, this function will fill
+     * in the state of not-currently-rendered content and hint nodes with the
+     * values from the previous serialized state. If no lastSerializedState is
+     * supplied, `null` will be returned for not-currently-rendered content and
+     * hint nodes.
+     */
+    _getSerializedState(lastSerializedState?: SerializedStateTree): SerializedStateTree;
+    /**
+     * Given a tree in the shape of the multi-item, with serialized state at
+     * each of the content nodes, restore each state to the corresponding
+     * renderer if currently mounted.
+     */
+    restoreSerializedState(serializedState: SerializedState, callback?: () => any): void;
+    /**
+     * Given an array of renderers, if it happens to be an array of *hint*
+     * renderers, then attach a `firstN` method to the array, which allows the
+     * layout to render the hints together in one HintsRenderer.
+     */
+    _annotateRendererArray(renderers: ReadonlyArray<Renderer>, rendererDatas: ReadonlyArray<RendererData>, shape: ArrayShape): ReadonlyArray<Renderer>;
+    /**
+     * Return a tree in the shape of the multi-item, with a Renderer at each
+     * content node and a HintRenderer at each hint node.
+     *
+     * This is generated by running each of the `makeRenderer` functions at the
+     * leaf nodes.
+     */
+    _getRenderers(): RendererTree;
+    render(): React.ReactNode;
+}
+export default MultiRenderer;

package/dist/multi-items/multi-renderer.js.flow

@@ -0,0 +1,213 @@
+/**
+ * Flowtype definitions for data
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+import * as React from "react";
+import Renderer from "../renderer";
+import type { Widget } from "../renderer";
+import type { APIOptions, FilterCriterion } from "../types";
+import type { Item, ContentNode, HintNode, TagsNode } from "./item-types";
+import type { Shape, ArrayShape } from "./shape-types";
+import type { Tree } from "./tree-types";
+import type { TreeMapper, ContentMapper, HintMapper, Path } from "./trees";
+declare type Hint = any;
+declare type Score = any;
+declare type SerializedState = any;
+declare type RendererProps = React.ElementConfig<typeof Renderer>;
+declare type ContentRendererElement = React.Element<any>;
+declare type HintRendererElement = React.Element<any>;
+declare type ContentRendererData = {|
+  makeRenderer: () => ContentRendererElement,
+  ref: Renderer | null | void,
+|};
+declare type FindWidgetsFunc = (
+  criterion: FilterCriterion
+) => $ReadOnlyArray<Widget | null | void>;
+declare type HintRendererData = {|
+  makeRenderer: () => HintRendererElement,
+  findExternalWidgets: FindWidgetsFunc | null | void,
+  ref: null,
+  hint: Hint,
+|};
+declare type RendererData = ContentRendererData | HintRendererData;
+declare type RendererDataTree = Tree<
+  ContentRendererData,
+  HintRendererData,
+  null
+>;
+/**
+ * TODO(somewhatabstract, JIRA-XXXX):
+ * Some usage of this type somewhere is causing Flow to believe that these
+ * elements should be components. Don't know where that is, to fix it up
+ * properly. In reality, these types are just too hard to use and aren't
+ * really helping us out as I now have to suppress this rather than
+ * get value from the type. :(
+ */
+declare type RendererTree = Tree<
+  ContentRendererElement,
+  HintRendererElement,
+  null
+>;
+declare type ScoreTree = Tree<Score, null, null>;
+declare type SerializedStateTree = Tree<SerializedState, null, null>;
+declare type Props = {|
+  item: Item,
+  shape: Shape,
+  children: (tree: {|
+    renderers: RendererTree,
+  |}) => React.Element<any>,
+  serializedState?: SerializedStateTree | null | void,
+  onSerializedStateUpdated?: (state: SerializedStateTree) => void,
+  onInteractWithWidget?: (id: string) => void,
+  apiOptions?: APIOptions,
+  reviewMode?: boolean | null | void,
+|};
+declare type State = {|
+  rendererDataTree: RendererDataTree | null | void,
+  renderError: Error | null | void,
+|};
+declare class MultiRenderer extends React.Component<Props, State> {
+  rendererDataTreeMapper: TreeMapper<
+    ContentNode,
+    ContentRendererData,
+    HintNode,
+    HintRendererData,
+    TagsNode,
+    null
+  >;
+  getRenderersMapper: TreeMapper<
+    ContentRendererData,
+    ContentRendererElement,
+    HintRendererData,
+    HintRendererElement,
+    null,
+    null
+  >;
+  constructor(props: Props): this;
+  UNSAFE_componentWillReceiveProps(nextProps: Props): void;
+
+  /**
+   * Attempt to build a State that includes a renderer tree corresponding to
+   * the item provided in props. On error, return a state with `renderError`
+   * set instead.
+   */
+  _tryMakeRendererState(props: Props): State;
+  _handleSerializedStateUpdated: (path: Path, newState?: any) => void;
+
+  /**
+   * Props that aren't directly used by the MultiRenderer are delegated to
+   * the underlying Renderers.
+   */
+  _getRendererProps(): RendererProps;
+
+  /**
+   * Construct a Renderer and a ref placeholder for the given ContentNode.
+   */
+  _makeContentRendererData(
+    content: ContentNode,
+    path: Path
+  ): ContentRendererData;
+
+  /**
+   * Construct a Renderer for the given HintNode, and keep track of the hint
+   * itself for future use, too.
+   */
+  _makeHintRendererData(hint: HintNode): HintRendererData;
+
+  /**
+   * Construct a tree of interconnected RendererDatas, corresponding to the
+   * given item. Called in `_tryMakeRendererState`, in order to store this
+   * tree in the component state.
+   */
+  _makeRendererDataTree(item: Item, shape: Shape): RendererDataTree;
+
+  /**
+   * Return all widgets that meet the given criterion, from all Renderers
+   * except the Renderer that triggered this call.
+   *
+   * This function is provided to each Renderer's `findExternalWidgets` prop,
+   * which enables widgets in different Renderers to discover each other and
+   * communicate.
+   */
+  _findWidgets(
+    callingData: RendererData,
+    filterCriterion: FilterCriterion
+  ): $ReadOnlyArray<Widget | null | void>;
+
+  /**
+   * Copy the renderer tree, apply the given transformation to the leaf nodes
+   * and the optional given transformation to the array nodes, and return the
+   * result.
+   *
+   * Used to provide structured data to the call site (the Renderer tree on
+   * `render`, the Score tree on `getScores`, etc.), and to traverse the
+   * renderer tree even when we disregard the output (like in
+   * `_findWidgets`).
+   */
+  _mapRenderers<O>(leafMapper: {|
+    ...ContentMapper<RendererData, O>,
+    ...HintMapper<RendererData, O>,
+  |}): Tree<O, O, null> | null | void;
+  _scoreFromRef(ref?: Renderer | null): Score;
+
+  /**
+   * Return a tree in the shape of the multi-item, with scores at each of
+   * the content nodes and `null` at the other leaf nodes.
+   */
+  getScores(): ScoreTree;
+
+  /**
+   * Return a single composite score for all rendered content nodes.
+   * The `guess` is a tree in the shape of the multi-item, with an individual
+   * guess at each content node and `null` at the other leaf nodes.
+   */
+  score(): Score;
+
+  /**
+   * Return a tree in the shape of the multi-item, with serialized state at
+   * each of the content nodes and `null` at the other leaf nodes.
+   *
+   * If the lastSerializedState argument is supplied, this function will fill
+   * in the state of not-currently-rendered content and hint nodes with the
+   * values from the previous serialized state. If no lastSerializedState is
+   * supplied, `null` will be returned for not-currently-rendered content and
+   * hint nodes.
+   */
+  _getSerializedState(
+    lastSerializedState?: SerializedStateTree
+  ): SerializedStateTree;
+
+  /**
+   * Given a tree in the shape of the multi-item, with serialized state at
+   * each of the content nodes, restore each state to the corresponding
+   * renderer if currently mounted.
+   */
+  restoreSerializedState(
+    serializedState: SerializedState,
+    callback?: () => any
+  ): void;
+
+  /**
+   * Given an array of renderers, if it happens to be an array of *hint*
+   * renderers, then attach a `firstN` method to the array, which allows the
+   * layout to render the hints together in one HintsRenderer.
+   */
+  _annotateRendererArray(
+    renderers: $ReadOnlyArray<Renderer>,
+    rendererDatas: $ReadOnlyArray<RendererData>,
+    shape: ArrayShape
+  ): $ReadOnlyArray<Renderer>;
+
+  /**
+   * Return a tree in the shape of the multi-item, with a Renderer at each
+   * content node and a HintRenderer at each hint node.
+   *
+   * This is generated by running each of the `makeRenderer` functions at the
+   * leaf nodes.
+   */
+  _getRenderers(): RendererTree;
+  render(): React.Node;
+}
+declare export default typeof MultiRenderer;

package/dist/multi-items/prop-type-builders.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Utility functions to build React PropTypes for multi-items and shapes.
+ *
+ * If you're writing new components, though, consider using the Item and Shape
+ * Flow types instead.
+ */
+import type { Shape } from "./shape-types";
+/**
+ * A recursive PropType that accepts Shape objects, and rejects other objects.
+ *
+ * Usage: `propTypes: {shape: shapePropType}`.
+ */
+export declare function shapePropType(...args: ReadonlyArray<any>): any;
+/**
+ * Return a PropType that accepts Items of the given shape, and rejects other
+ * objects.
+ *
+ * Usage: `propTypes: {item: buildPropTypeForShape(myShape)}`
+ */
+export declare function buildPropTypeForShape(shape: Shape): any;

package/dist/multi-items/prop-type-builders.js.flow

@@ -0,0 +1,22 @@
+/**
+ * Flowtype definitions for data
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+import type { Shape } from "./shape-types";
+
+/**
+ * A recursive PropType that accepts Shape objects, and rejects other objects.
+ *
+ * Usage: `propTypes: {shape: shapePropType}`.
+ */
+declare export function shapePropType(...args: $ReadOnlyArray<any>): any;
+
+/**
+ * Return a PropType that accepts Items of the given shape, and rejects other
+ * objects.
+ *
+ * Usage: `propTypes: {item: buildPropTypeForShape(myShape)}`
+ */
+declare export function buildPropTypeForShape(shape: Shape): any;

package/dist/multi-items/shape-types.d.ts

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