"use strict"; /** * For math rendered using KaTex and/or MathJax. Use me like 2x + 3. */ /* global MathJax */ const PureRenderMixin = require("react-addons-pure-render-mixin"); const React = require("react"); const ReactDOM = require("react-dom"); const createReactClass = require("create-react-class"); const PropTypes = require("prop-types"); const katex = require("katex"); const katexA11y = require("./katex-a11y.js"); let pendingScripts = []; let pendingCallbacks = []; let needsProcess = false; // For creating unique element ids required by the aria-describedby attribute let describedByIdCounter = 0; const process = (script, callback) => { pendingScripts.push(script); pendingCallbacks.push(callback); if (!needsProcess) { needsProcess = true; setTimeout(doProcess, 0); } }; const unProcess = script => { const scriptIndex = pendingScripts.indexOf(script); pendingScripts.splice(scriptIndex, 1); pendingCallbacks.splice(scriptIndex, 1); }; const loadMathJax = callback => { if (typeof MathJax !== "undefined") { callback(); } else { /** * We can either... * * A) Reach up and out of `third_party` folder into our core webapp * code to include this `load-mathjax` file that, well, loads MathJax * or... * * B) Move this file into the KateX package next to `load-mathjax` and * then update everything that calls for this file to point at that * path instead. * * There is no easy or obvious solution. I am choosing A. * * - Jesse */ const loadMathJax = require("../../../../javascript/katex-package/load-mathjax.js"); loadMathJax.then(callback); } }; const doProcess = () => { loadMathJax(() => { MathJax.Hub.Queue(function() { const oldElementScripts = MathJax.Hub.elementScripts; MathJax.Hub.elementScripts = element => pendingScripts; try { return MathJax.Hub.Process(null, () => { // Trigger all of the pending callbacks before clearing them // out. for (const callback of pendingCallbacks) { callback(); } pendingScripts = []; pendingCallbacks = []; needsProcess = false; }); } catch (e) { // IE8 requires `catch` in order to use `finally` throw e; } finally { MathJax.Hub.elementScripts = oldElementScripts; } }); }); }; // Make content only visible to screen readers. // Both collegeboard.org and Bootstrap 3 use this exact implementation. const srOnly = { border: 0, clip: "rect(0,0,0,0)", height: "1px", margin: "-1px", overflow: "hidden", padding: 0, position: "absolute", width: "1px", }; const TeX = createReactClass({ propTypes: { children: PropTypes.node, katexOptions: PropTypes.any, onClick: PropTypes.func, onRender: PropTypes.func, style: PropTypes.any, }, mixins: [PureRenderMixin], getDefaultProps: function() { return { katexOptions: { // There was a breaking change in the behavior of \color{} // in KaTeX 0.8.0. KA content relies on the old behavior // so we set this option to retain that old behavior even // though it is not purely compatible with LaTeX. // See https://github.com/Khan/KaTeX/blob/master/README.md // for details on this option. colorIsTextColor: true, }, // Called after math is rendered or re-rendered onRender: function() {}, onClick: null, }; }, // TODO(joshuan): Once we are using React 16.3+, // migrate to getDerivedStateFromProps getInitialState: function() { return { mounted: false, katexHtml: this.getKatexHtml(this.props), }; }, componentDidMount: function() { this._root = ReactDOM.findDOMNode(this); // Needed so that the initial client render matches SSR. // eslint-disable-next-line react/no-did-mount-set-state this.setState({ mounted: true, }); if (this.refs.katex.childElementCount > 0) { // If we already rendered katex in the render function, we don't // need to render anything here. this.props.onRender(this._root); return; } const text = this.props.children; this.setScriptText(text); this.process(() => this.props.onRender(this._root)); }, // TODO(joshuan): If you are updating to React 16.3+, migrate to // getDerivedStateFromProps componentWillReceiveProps: function(nextProps) { if ( nextProps.children !== this.props.children || JSON.stringify(nextProps.katexOptions) !== JSON.stringify(this.props.katexOptions) ) { this.setState({ katexHtml: this.getKatexHtml(nextProps), }); } }, componentDidUpdate: function(prevProps, prevState) { if (this.props.children !== prevProps.children) { this.maybeUnprocess(); // If we already rendered katex in the render function, we don't // need to render anything here. if (this.refs.katex.childElementCount > 0) { if (this.script) { // If we successfully rendered KaTeX, check if there's // lingering MathJax from the last render, and if so remove it. loadMathJax(() => { const jax = MathJax.Hub.getJaxFor(this.script); if (jax) { jax.Remove(); } }); } this.props.onRender(); return; } const newText = this.props.children; if (this.script) { loadMathJax(() => { MathJax.Hub.Queue(() => { const jax = MathJax.Hub.getJaxFor(this.script); if (jax) { return jax.Text(newText, this.props.onRender); } else { this.setScriptText(newText); this.process(this.props.onRender); } }); }); } else { this.setScriptText(newText); this.process(this.props.onRender); } } }, componentWillUnmount: function() { this.maybeUnprocess(); if (this.script) { loadMathJax(() => { const jax = MathJax.Hub.getJaxFor(this.script); if (jax) { jax.Remove(); } }); } }, getKatexHtml(props) { // Try to render the math content with KaTeX. // If this fails, componentDidUpdate() will notice and // use MathJAX instead. try { return { __html: katex.renderToString( props.children, props.katexOptions, ), }; } catch (e) { // By catching the exception here and returning null // we will fall back to asyncronously rendering with // MathJAX. // // NOTE: formerly we only returned null if the error // was a parse error from Katex and re-threw any other errors. // But https://khanacademy.atlassian.net/browse/CP-879 and // https://khanacademy.atlassian.net/browse/CP-1742 were caused // by regular TypeError exceptions in Katex, so we might as // well fall back to MathJAX in that case as well. (The Katex // bug is fixed in the latest version and will stop happening // when we upgrade webapp to use Katex 1.0.) // // TODO: We could use Raven.captureMessage() to send a message // to Sentry when these errors occur if we want to get serious // about eliminating them. Such a message should include // window.location, props.children (the string of katex source) // and the error itself. return null; } }, process: function(callback) { this.hasProcessed = false; process(this.script, () => { this.hasProcessed = true; callback && callback(); }); }, maybeUnprocess: function() { // Sometimes, we end up rendering this component with some MathJax-only // math before very quickly switching over to some other math, before // MathJax has had a time to render. We want to remove the previously // queued render so that we don't accidentally render some math that we // don't want displayed. if (this.script && !this.hasProcessed) { unProcess(this.script); } }, setScriptText: function(text) { if (!this.script) { this.script = document.createElement("script"); this.script.type = "math/tex"; ReactDOM.findDOMNode(this.refs.mathjax).appendChild(this.script); } if ("text" in this.script) { // IE8, etc this.script.text = text; } else { this.script.textContent = text; } }, render: function() { const {katexHtml} = this.state; // If we successfully parsed with KaTeX, then try parse the // same math text to an english rendering that can be read // by screen readers. Our katexA11y module is out of date and // not well maintained, so it can not always transform math // into readable english. We ignore any exceptions it throws. let katexA11yHtml = null; let describedById = null; if (katexHtml) { try { katexA11yHtml = { __html: katexA11y.renderString(this.props.children), }; // The server and the client will not necessarily use the same // ID, and the initial client markup must match the server // markup. Thus, we only add an ID once we've rendered once. if (this.state.mounted) { describedById = `katex-${++describedByIdCounter}`; } } catch (e) { // Nothing } } return ( {/* MathJAX output goes here if KaTeX parsing fails */} {/* * KaTeX output goes here. If we successfully converted the * math to readable english, then we hide all of this from * screen readers with aria-hidden. */} {/* * If we generated readable english text, it goes here. * The srOnly styles will prevent it from being displayed * visually. */} ); }, }); module.exports = TeX;