@khanacademy/perseus 0.4.2 → 1.0.0

package/src/widgets/passage/__tests__/passage-markdown_test.jsx

@@ -7,7 +7,6 @@ import _ from "underscore";
 import PassageMarkdown from "../passage-markdown.jsx";
 
 const parse = PassageMarkdown.parse;
-const rules = PassageMarkdown._rulesForTesting;
 
 const validateParse = (parsed, expected) => {
     if (!_.isEqual(parsed, expected)) {
@@ -352,14 +351,6 @@ describe.skip("passage markdown", () => {
         });
     });
 
-    describe("orders", () => {
-        it("should always be numbers", () => {
-            _.each(rules, (rule) => {
-                expect(typeof rule.order === "number").toBeTruthy();
-            });
-        });
-    });
-
     describe("output", () => {
         it("should output some basic formatted passage text", () => {
             assertParsesToReact(

package/src/widgets/passage/get-line-height-for-node.js

@@ -1,10 +1,9 @@
 // @flow
-
-type JQueryCollection = $FlowFixMe;
+import $ from "jquery";
 
 export const getLineHeightForNode = (
-    $line1: JQueryCollection,
-    $line2: JQueryCollection,
+    line1: HTMLDivElement,
+    line2: HTMLDivElement,
 ): number => {
-    return $line2.offset().top - $line1.offset().top;
+    return $(line2).offset().top - $(line1).offset().top;
 };

package/src/widgets/passage/passage-markdown.jsx

@@ -1,85 +1,96 @@
 /* eslint-disable react/sort-comp */
 // @flow
+
 import SimpleMarkdown from "@khanacademy/simple-markdown";
 import * as i18n from "@khanacademy/wonder-blocks-i18n";
-import PropTypes from "prop-types";
 import * as React from "react";
 import _ from "underscore";
 
-const START_REF_PREFIX = "start-ref-";
-const END_REF_PREFIX = "end-ref-";
-const REF_STYLE = {
-    display: "inline-block",
-    width: 0,
-    visibility: "hidden",
-};
+import type {
+    Capture,
+    Parser,
+    SingleASTNode,
+    State,
+} from "@khanacademy/simple-markdown";
 
-const LABEL_OUTER_STYLE = {
-    // for some reason we need these to keep the nbsp from wrapping when the
-    // inner circle/square is display: inline-block
-    display: "inline",
-    whiteSpace: "nowrap",
-};
+export type ParseState = {|
+    ...State,
+    currentRef: number[],
+    useRefs: boolean,
+    lastRef: number,
+    firstSentenceRef: ?string,
+    firstQuestionRef: ?string,
+    lastFootnote: {id: number, text: string},
+|};
 
-const SQUARE_LABEL_STYLE = {
-    display: "inline-block",
-    color: "rgb(255, 255, 255)",
-    backgroundColor: "rgb(90, 90, 90)",
-    paddingLeft: 10,
-    paddingRight: 10,
-    userSelect: "none",
-    WebkitUserSelect: "none",
-};
+type OutputFun = $FlowFixMe;
 
-const CIRCLE_LABEL_STYLE = {
-    display: "inline-block",
-    color: "rgb(255, 255, 255)",
-    backgroundColor: "rgb(90, 90, 90)",
-    userSelect: "none",
-    WebkitUserSelect: "none",
-    width: 22,
-    height: 22,
-    borderRadius: "50%",
-    textAlign: "center",
-};
+type FootnoteType = {|
+    id: number,
+    text: string,
+|};
+
+type RefStartNode = {|
+    ref: ?number,
+    refContent: React.Node,
+|};
 
-class RefStart extends React.Component<$FlowFixMe> {
-    static propTypes = {
-        refContent: PropTypes.node.isRequired,
+type RefEndNode = {|
+    ref: ?number,
+|};
+
+type LabelNode = {|
+    content: string,
+    space: boolean,
+|};
+
+type HighlightNode = {|
+    content: string,
+|};
+
+type RefStartProps = {|
+    refContent: React.Node,
+|};
+
+function getInitialParseState(): ParseState {
+    return {
+        currentRef: [],
+        useRefs: true,
+        lastRef: 0,
+        firstSentenceRef: null,
+        firstQuestionRef: null,
+        lastFootnote: {id: 0, text: ""},
     };
+}
 
+class RefStart extends React.Component<RefStartProps> {
     render(): React.Node {
         return <span style={REF_STYLE}>{i18n.doNotTranslate("_")}</span>;
     }
 
-    getRefContent = () => {
+    getRefContent: () => React.Node = () => {
         return this.props.refContent;
     };
 }
 
-class RefEnd extends React.Component<$FlowFixMe> {
+class RefEnd extends React.Component<{}> {
     render(): React.Node {
         return <span style={REF_STYLE}>{i18n.doNotTranslate("_")}</span>;
     }
 }
 
-const rules: $FlowFixMe = {
-    // $FlowFixMe[prop-missing]
-    // $FlowFixMe[incompatible-use]
+const rules = {
     newline: SimpleMarkdown.defaultRules.newline,
-    // $FlowFixMe[prop-missing]
-    // $FlowFixMe[incompatible-use]
     paragraph: SimpleMarkdown.defaultRules.paragraph,
-    // $FlowFixMe[prop-missing]
-    // $FlowFixMe[incompatible-use]
     escape: SimpleMarkdown.defaultRules.escape,
     passageFootnote: {
-        // $FlowFixMe[prop-missing]
-        // $FlowFixMe[incompatible-use]
         order: SimpleMarkdown.defaultRules.escape.order + 0.1,
-        // $FlowFixMe[prop-missing]
         match: SimpleMarkdown.inlineRegex(/^\^/),
-        parse: (capture, parse, state) => {
+        parse: (
+            capture: Capture,
+            parse: Parser,
+            state: ParseState,
+        ): FootnoteType => {
             // if no footnotes have been seen, we're id 1. otherwise,
             // we're the next subsequent id
             const id = state.lastFootnote.id + 1;
@@ -100,15 +111,13 @@ const rules: $FlowFixMe = {
             state.lastFootnote = footnote;
             return footnote;
         },
-        react: (node, output, state) => {
+        react: (node: FootnoteType, output: OutputFun, state: ParseState) => {
             return <sup key={state.key}>{node.text}</sup>;
         },
     },
     refStart: {
-        // $FlowFixMe[prop-missing]
-        // $FlowFixMe[incompatible-use]
         order: SimpleMarkdown.defaultRules.escape.order + 0.2,
-        match: function (source, state) {
+        match: function (source) {
             const capture = /^\{\{/.exec(source);
             if (capture) {
                 // We need to do extra processing here to capture the
@@ -138,15 +147,20 @@ const rules: $FlowFixMe = {
                     closeIndex++;
                 }
 
-                const refText = source.slice(2, closeIndex);
-
                 // A "magic" capture that matches the opening {{
                 // but captures the full ref text internally :D
-                return [capture[0], refText];
+                // unfortunately the "magic" makes Flow upset,
+                // so there's this questionable workaround
+                capture[1] = source.slice(2, closeIndex);
+                return capture;
             }
             return null;
         },
-        parse: (capture, parse, state) => {
+        parse: (
+            capture: Capture,
+            parse: Parser,
+            state: ParseState,
+        ): RefStartNode => {
             if (!state.useRefs) {
                 return {
                     ref: null,
@@ -169,7 +183,7 @@ const rules: $FlowFixMe = {
                         // passage, for instance!
                         useRefs: false,
                     },
-                    INITIAL_PARSE_STATE,
+                    getInitialParseState(),
                 ),
             );
 
@@ -178,8 +192,9 @@ const rules: $FlowFixMe = {
                 refContent: refContent,
             };
         },
-        react: (node, output, state) => {
-            if (node.ref == null) {
+        react: (node: RefStartNode, output: OutputFun, state: ParseState) => {
+            const ref = node.ref;
+            if (ref == null) {
                 return null;
             }
 
@@ -187,22 +202,26 @@ const rules: $FlowFixMe = {
             // and output out-of-band. We don't want to affect
             // our state by the double-output here :).
             const refContent = output(node.refContent, {});
+
+            // note(matthewc) the refs created here become the refs
+            // pulled from `this.refs` in passage.jsx
             return (
                 <RefStart
-                    ref={START_REF_PREFIX + node.ref}
-                    key={START_REF_PREFIX + node.ref}
+                    ref={START_REF_PREFIX + ref}
+                    key={START_REF_PREFIX + ref}
                     refContent={refContent}
                 />
             );
         },
     },
     refEnd: {
-        // $FlowFixMe[prop-missing]
-        // $FlowFixMe[incompatible-use]
         order: SimpleMarkdown.defaultRules.escape.order + 0.3,
-        // $FlowFixMe[prop-missing]
         match: SimpleMarkdown.inlineRegex(/^\}\}/),
-        parse: (capture, parse, state) => {
+        parse: (
+            capture: Capture,
+            parse: Parser,
+            state: ParseState,
+        ): RefEndNode => {
             if (!state.useRefs) {
                 return {
                     ref: null,
@@ -214,8 +233,10 @@ const rules: $FlowFixMe = {
                 ref: ref,
             };
         },
-        react: (node, output, state) => {
+        react: (node: RefEndNode, output: OutputFun, state: ParseState) => {
             if (node.ref != null) {
+                // note(matthewc) the refs created here become the refs
+                // pulled from `this.refs` in passage.jsx
                 return (
                     <RefEnd
                         ref={END_REF_PREFIX + node.ref}
@@ -230,12 +251,13 @@ const rules: $FlowFixMe = {
         },
     },
     squareLabel: {
-        // $FlowFixMe[prop-missing]
-        // $FlowFixMe[incompatible-use]
         order: SimpleMarkdown.defaultRules.escape.order + 0.4,
-        // $FlowFixMe[prop-missing]
         match: SimpleMarkdown.inlineRegex(/^\[\[(\w+)\]\]( *)/),
-        parse: (capture, parse, state) => {
+        parse: (
+            capture: Capture,
+            parse: Parser,
+            state: ParseState,
+        ): LabelNode => {
             if (!state.firstQuestionRef) {
                 state.firstQuestionRef = capture[1];
             }
@@ -244,7 +266,7 @@ const rules: $FlowFixMe = {
                 space: capture[2].length > 0,
             };
         },
-        react: (node, output, state) => {
+        react: (node: LabelNode, output: OutputFun, state: ParseState) => {
             return [
                 <span
                     key="visual-square"
@@ -264,18 +286,23 @@ const rules: $FlowFixMe = {
         },
     },
     circleLabel: {
-        // $FlowFixMe[prop-missing]
-        // $FlowFixMe[incompatible-use]
         order: SimpleMarkdown.defaultRules.escape.order + 0.5,
-        // $FlowFixMe[prop-missing]
         match: SimpleMarkdown.inlineRegex(/^\(\((\w+)\)\)( *)/),
-        parse: (capture, parse, state) => {
+        parse: (
+            capture: Capture,
+            parse: Parser,
+            state: ParseState,
+        ): LabelNode => {
             return {
                 content: capture[1],
                 space: capture[2].length > 0,
             };
         },
-        react: (node, output, state) => {
+        react: (
+            node: LabelNode,
+            output: OutputFun,
+            state: ParseState,
+        ): React.Node => {
             return [
                 <span
                     key="visual-circle"
@@ -295,12 +322,13 @@ const rules: $FlowFixMe = {
         },
     },
     squareBracketRef: {
-        // $FlowFixMe[prop-missing]
-        // $FlowFixMe[incompatible-use]
         order: SimpleMarkdown.defaultRules.escape.order + 0.6,
-        // $FlowFixMe[prop-missing]
         match: SimpleMarkdown.inlineRegex(/^\[(\d+)\]( *)/),
-        parse: (capture, parse, state) => {
+        parse: (
+            capture: Capture,
+            parse: Parser,
+            state: ParseState,
+        ): LabelNode => {
             if (!state.firstSentenceRef) {
                 state.firstSentenceRef = capture[1];
             }
@@ -309,7 +337,7 @@ const rules: $FlowFixMe = {
                 space: capture[2].length > 0,
             };
         },
-        react: (node, output, state) => {
+        react: (node: LabelNode, output: OutputFun, state: ParseState) => {
             return [
                 <span
                     key="visual-brackets"
@@ -326,19 +354,20 @@ const rules: $FlowFixMe = {
         },
     },
     highlight: {
-        // $FlowFixMe[prop-missing]
-        // $FlowFixMe[incompatible-use]
         order: SimpleMarkdown.defaultRules.escape.order + 0.7,
-        // $FlowFixMe[prop-missing]
         match: SimpleMarkdown.inlineRegex(
             /^{highlighting.start}(.+?){highlighting.end}/,
         ),
-        parse: (capture, parse, state) => {
+        parse: (
+            capture: Capture,
+            parse: Parser,
+            state: ParseState,
+        ): HighlightNode => {
             return {
                 content: capture[1],
             };
         },
-        react: (node, output, state) => {
+        react: (node: HighlightNode, output: OutputFun, state: ParseState) => {
             return [
                 <span key={0} className="perseus-highlight">
                     {node.content}
@@ -347,19 +376,20 @@ const rules: $FlowFixMe = {
         },
     },
     reviewHighlight: {
-        // $FlowFixMe[prop-missing]
-        // $FlowFixMe[incompatible-use]
         order: SimpleMarkdown.defaultRules.escape.order + 0.7,
-        // $FlowFixMe[prop-missing]
         match: SimpleMarkdown.inlineRegex(
             /^{review-highlighting.start}(.+?){review-highlighting.end}/,
         ),
-        parse: (capture, parse, state) => {
+        parse: (
+            capture: Capture,
+            parse: Parser,
+            state: ParseState,
+        ): HighlightNode => {
             return {
                 content: capture[1],
             };
         },
-        react: (node, output, state) => {
+        react: (node: HighlightNode, output: OutputFun, state: ParseState) => {
             return [
                 <span key={0} className="perseus-review-highlight">
                     {node.content}
@@ -367,21 +397,11 @@ const rules: $FlowFixMe = {
             ];
         },
     },
-    // $FlowFixMe[prop-missing]
-    // $FlowFixMe[incompatible-use]
     strong: SimpleMarkdown.defaultRules.strong,
-    // $FlowFixMe[prop-missing]
-    // $FlowFixMe[incompatible-use]
     u: SimpleMarkdown.defaultRules.u,
-    // $FlowFixMe[prop-missing]
-    // $FlowFixMe[incompatible-use]
     em: SimpleMarkdown.defaultRules.em,
-    // $FlowFixMe[prop-missing]
-    // $FlowFixMe[incompatible-use]
     del: SimpleMarkdown.defaultRules.del,
     text: {
-        // $FlowFixMe[prop-missing]
-        // $FlowFixMe[incompatible-use]
         ...SimpleMarkdown.defaultRules.text,
         react(node, output, state) {
             return <span key={state.key}>{node.content}</span>;
@@ -389,28 +409,64 @@ const rules: $FlowFixMe = {
     },
 };
 
-const INITIAL_PARSE_STATE = {
-    currentRef: [],
-    useRefs: true,
-    lastRef: 0,
-    lastFootnote: {id: 0, text: ""},
+const START_REF_PREFIX = "start-ref-";
+const END_REF_PREFIX = "end-ref-";
+const REF_STYLE = {
+    display: "inline-block",
+    width: 0,
+    visibility: "hidden",
+};
+
+const LABEL_OUTER_STYLE = {
+    // for some reason we need these to keep the nbsp from wrapping when the
+    // inner circle/square is display: inline-block
+    display: "inline",
+    whiteSpace: "nowrap",
 };
-// $FlowFixMe[prop-missing]
+
+const SQUARE_LABEL_STYLE = {
+    display: "inline-block",
+    color: "rgb(255, 255, 255)",
+    backgroundColor: "rgb(90, 90, 90)",
+    paddingLeft: 10,
+    paddingRight: 10,
+    userSelect: "none",
+    WebkitUserSelect: "none",
+};
+
+const CIRCLE_LABEL_STYLE = {
+    display: "inline-block",
+    color: "rgb(255, 255, 255)",
+    backgroundColor: "rgb(90, 90, 90)",
+    userSelect: "none",
+    WebkitUserSelect: "none",
+    width: 22,
+    height: 22,
+    borderRadius: "50%",
+    textAlign: "center",
+};
+
 const builtParser = SimpleMarkdown.parserFor(rules);
-const parse: (string, $FlowFixMe) => $FlowFixMe = (source, state) => {
+const parse: (string, ?ParseState) => Array<SingleASTNode> = (
+    source,
+    state,
+) => {
     state = state || {};
     const paragraphedSource = source + "\n\n";
-    return builtParser(paragraphedSource, _.extend(state, INITIAL_PARSE_STATE));
+    return builtParser(
+        paragraphedSource,
+        _.extend(state, getInitialParseState()),
+    );
 };
 
+const output: (Array<SingleASTNode>) => React.Node = SimpleMarkdown.reactFor(
+    SimpleMarkdown.ruleOutput(rules, "react"),
+);
+
 export default {
-    parse: parse,
-    // $FlowFixMe[prop-missing]
-    output: (SimpleMarkdown.reactFor(
-        // $FlowFixMe[prop-missing]
-        SimpleMarkdown.ruleOutput(rules, "react"),
-    ): $FlowFixMe),
-    START_REF_PREFIX: START_REF_PREFIX,
-    END_REF_PREFIX: END_REF_PREFIX,
-    _rulesForTesting: rules,
+    parse,
+    output,
+    START_REF_PREFIX,
+    END_REF_PREFIX,
+    getInitialParseState,
 };