@zzish/math-rich-input

MathRichInput

This project is a MathRichInput component that allows users to edit a "text area" with the following key features:

• Ability to render, insert and edit mathematical equations in the input field
• A toolbar that appears on focus with:

• Five buttons for bold, italic, underline, subscript and superscript
• A button for accents and other special characters
• A button to bring up a WYSIWIG equation editor and insert equations

Usage

Basic usage

export default class App extends Component {

  constructor(props) {
    super(props);
    this.state = {
      value:"", // Set this to an initial value if known
    };
  }

  handleInputChange = (content, options) => {
    this.setState({
        value: content.value, // Note the field value on the returned content
      }
    )
  } 
  
  <MathRichInput
    value={this.state.value}
    onChange={this.handleInputChange}
  />
}

Normal usage

export default class App extends Component {

  constructor(props) {
    super(props);
    this.state = {
      value:"", // Set this to an initial value if known
      mimeType:"", // Set this to the initial mime type of the text in value if known
      options: {
        useExpertMode:false,
        selectedTab: null
      }
    };
  }

  handleInputChange = (content, options) => {
    this.setState({
        value: content.value,
        mimeType: content.mimeType
        options: options
      }
    )
  } 
  
  <MathRichInput
    value={this.state.value}
    mimeType={this.state.mimeType}
    options={this.state.options}
    onChange={this.handleInputChange}
  />
}

Legacy usage

By default the MathRichInput will output content in html via the onChange callback method. You can force it to output tex and plain text instead using the outputTex and outputPlainText properties as follows:

  <MathRichInput
    outputTex={true}
    outputPlainText={true}
    value={this.state.value}
    mimeType={this.state.mimeType}
    options={this.state.options}
    onChange={this.handleInputChange}
  />

Rendering content created using MathRichInput with MathRichArea

  <MathRichArea mimeType={this.state.mimeType}>
    {this.state.value}
  </MathRichArea>

See the section on MathRichArea below for more information and alternative ways to render.

Mime types

In basic usage, the MathRichInput will attempt to work out the appropriate mime type for the inital value property if not supplied. However, it is good practice to explicitly set the initial mime type when it is known. For normal usage of MathRichInput using default settings, you can simply set the mime type to application/x-zzish-html-math. You only need to read further if you have preexisting content in text/plain or application/x-tex mime types.

The four supported mime types are:

• text/plain
• application/x-tex
• text/html
• application/x-zzish-html-math

2 and 4 support math equations.

Content in the application/x-tex mime type contains maths in tex equation format between a pair of $ symbols, or pairs of escaped round or square brackets, \( \) or \[ \].

Content in the application/x-zzish-html-math contains maths in tex equation format between a pair of <math></math> tags.

Here are examples of content in the two types:

• "Find all solutions for $x$ when $x^2 + 4x - 2 = \sqrt{9}$"
• "Find <b>all</b> solutions for <math>x</math> when <math>x^2 + 4x - 2 = \sqrt{9}</math>"

Note that the application/x-zzish-html-math mime type allows for text with full html formatting richness including <p></p>,<b></b>,<i></i>,<u></u>,<sup></sup> and <sub></sub> tags.

The MathRichInput supports the four mime types above, but the key consideration for developers is choosing witheter to set the mime-type initially to one of plain/text, application/x-tex or application/x-zzish-html-math.

If your content is only ever created using this MathRichInput component with default settings, then you can safely always set the mimeType to application/x-zzish-html-math. This is because, by default, the component will only ever output content as text/html or application/x-zzish-html-math and the application/x-zzish-html-math mime type is a superset of the text/html mime type.

If, however, you have some legacy content in plain text or tex/latex format, you should ideally set the mimeType as appropriate. If you are unsure as to the type of your content, then you can leave the mime type unset and the MathRichInput will choose the best mime-type automatically. It will generally make good choices, but it will make the wrong choice on plain text such as the following:

• "To bold text in html you should put the text betweeen <b> and <\b> tags"

In this example, the automatic detection will assume this is html, as it will identify the bold html tags. It will thus bold the word 'and'. It is not possible for the automatic detection to determine that this was in fact plain text.

Whatever the value and mime type of any initial content provided, the input field will always return the content in one of the two html mime types by default (via the onChange callback method):

• text/html
• application/x-zzish-html-math

These mime types should ideally be stored along with the value and supplied back to the MathRichInput and MathRichArea in future.

If you desire the output to be tex\latex, then pass the parameter outputTex={true}. When you choose to output in tex, font styling (eg. bold) and multiline are disabled for users.

By default, any output content that does not contain multiple lines (i.e. <p></p> tags), any html font styling (e.g. <b></b>), or any math elements will still be returned as text\html and any special html characters will be converted to their html codings (for example < will be converted to >). If required you can choose to have content that does not need any html or math formatting returned as plain text using outputPlainText={true}.

In general, unless you have a very good reason to, you should not set outputTex={true} or outputPlainText={true} and you should have your content returned as html (text/html) or html math (application/x-zzish-html-math) as happens with the default settings.

Options

The options property is used to return the current state of the equation editor so that if the user closes and reopens the equation editor, the state is remembered. In particular it allows you to store whether the user:

• Is using the equation editor in expert mode
• Has selected a specific symbols tab

Note that normally options should be a global object with the same options used across all input fields. This is so that the user does not need to reselect expert mode and/or select the same tab each time they reopen the equation editor.

The options property can be initialised to null rather than set explicitly as above. The options can be saved against the user's persistent user settings if desired.

Other properties

enableFontStyling

Set enableFontStyling={false} to:

• Disable the bold, italic, underline, subscript and superscript buttons on the toolbar
• Disalbe CTRL-B and other font styling hot keys

enableMultiline

Set enableMultiline={false} to:

• Disable new lines being entered by pressing the return key

enableMath

Set enableMath={false} to:

• Disable the equation editor button on the toolbar

outputTex

Set outputTex={true} to:

• Force output to be in tex (math equations are enclosed in a pair of $ symbols)

As a side effect, this also implicitly sets enableMultiline and enableFontStyling to false (see above).

outputPlainText

Set outputPlainText={true} to:

• Force output to be in plain text when the input text contains no html and no maths

Note that this does not disable multiline or font styling

editable

(not yet implemented)

Set editable={false} to purely render the value and not allow it to be edited by the user. Note that normally you would use the non-editable MathRichArea component to purely render values (it is a much lighter component).

MathRichArea

MathRichArea is a lightweight component for rendering content created with MathRichInput.

Normal usage is as follows:

  <MathRichArea mimeType={this.state.mimeType}>
    {this.state.value}
  </MathRichArea>

However, if you want to update legacy code that is rendering plain text or tex/latex content and don't want to go through your code updating all the fields to use the MathRichArea component, you can cheat and use the MathRichArea.renderMathInNode method in componentDidUpdate and componentDidMount.

For example, assuming that you had a page containing some content:

  <div className="question">{this.state.questionText}</div>
  <div className="answer">{this.state.answerText}</div>

where the question and answer text was simple text in any one of the four supported mime types.

Simply add the following code:

  componentDidMount() {
    renderMathInNode(document)
  }

  componentDidUpdate() {
    renderMathInNode(document)
  }

The renderMathInNode method will then:

• Search through all nodes including the supplied node and all its descendent nodes for text nodes
• Analyse the text to determine if it is text/html, application/x-zzish-html-math or application/x-tex
• If so convert the text for display

For short pages, the root document can be supplied as the starting node. For longer pages you may first want to select one or more nodes for processing to improve efficiency

  componentDidMount() {
    renderMathInNode(document.getElementById("render-this-text"))
    renderMathInNode(document.getElementById("render-this-text-too"))
  }

  componentDidUpdate() {
    renderMathInNode(document.getElementById("render-this-text"))
    renderMathInNode(document.getElementById("render-this-text-too"))
  }

ToDo

The following items need to be done before moving to production

• Automatically open Expert mode if unable to render in MathQuill.
• Warn if switching from Expert mode to normal mode
• Ensure try catch round all events and check best practice for react component error handling

The following items should be done before moving to production

• Bug: Deleting first equation when characters to the left, offset incorrect
• Bug: Deleting selected text when equation immediatly to left deletes the equation incorrectly
• Refactor button areas in the modal to be their own fixed components
• Generally refactor MathRichInput.js to move code out of file

Other things that should be done

• Expert mode: [Text] mathrm
• Mobile: Have tab list behave appropriately on smaller width screens (eg. convert )
• Mobile: Fix css grow effect for symbol buttons on mobile
• Tidy up equationEditorButtonsHelper.js
• Have tab underline match scollview position in modal
• Expert mode: fraction command (and all commands with ##) need to look back to find whole element to include
• Expert mode: Enable inserting of symbols into pure text (currently blocks as it thinks it is a tag)
• Expert mode: Smart fix of typying x_12 into x_{12} or x_min into x_{min}
• Expert mode: Inserting into prettified text does not work when first switching to expert mode

New features

• History: show matching previously entered equations as you type an equation.
• Common combos: for example, add extra buttons for 2 pi r and pi r^2 on hover over pi button