@zzish/math-rich-input 0.1.0

package/README.md

@@ -0,0 +1,253 @@
+# MathRichInput
+
+This project is a math rich input component that allows users to edit a "text area" with the following key features:
+
+1. Ability to render, insert and edit equations in the input field
+2. A toolbar that appears on focus:
+  - Buttons for bold, italic, underline, subscript and superscript
+  - Button for accents
+  - Button for inserting equations
+
+
+## Usage
+
+### Basic usage
+
+```js
+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
+
+```js
+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}
+  />
+}
+```
+
+### Rendering content created using MathRichInput with MathRichArea
+
+```js
+  <MathRichArea mimeType={this.state.mimeType}>
+    {this.state.value}
+  </MathRichArea>
+```
+
+See the section on MathRichArea below for more information and alternative ways to render.
+
+#### Mime type
+
+In basic usage, the MathRichInput will attempt to work out the appropriate mime type for the inital value property if supplied. However, it is good practice to explicitly set the initial mime type when it is known. For normal usage 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 application/x-tex format.
+
+The four supported mime types are:
+
+1. text/plain
+2. text/html
+3. application/x-zzish-html-math 
+4. application/x-tex
+
+The latter two mime types support math equations. Content in the application/x-tex mime type contains maths in tex equation format between a pair of $ symbols. 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 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 application/x-tex or application/x-zzish-html-math.
+
+If your content is only ever created using this MathRichInput component, 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 in one of the first three mime types and the application/x-zzish-html-math mime type is a superset of the text/plain and text/html formats.
+
+If, however, you have some legacy content in tex/latex format, you should set the mimeType to application/x-tex when the legacy content is known to be in tex/latex format.  If you are unsure whether the content is tex or not, then you can not set a mime type and the MathRichInput will determine the best mime-type. 99% of the time the MathRichInput will choose the correct mime type.
+
+Whatever the value and mime type of any initial content provided, the input field will always return the content in one of the first three mime types by default (via the onChange callback method):
+
+1. text/plain
+2. text/html
+3. application/x-zzish-html-math 
+
+These mime types should ideally be stored along with the value and supplied to the MathRichInput and MathRichArea in future.
+
+If you desire the output to be in 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. Unless you have a good reason to output in tex, you should not use this settting.
+
+#### 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 synbols 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 initialed to null rather than set explicitly as above. The options can be saved against the users persistent settings if desired.
+
+#### Other properties
+
+##### enableFontStyling
+
+(not yet implemented) 
+
+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
+
+(not yet implemented) 
+
+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
+
+(not yet implemented) 
+
+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).
+
+##### 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:
+
+```js
+  <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:
+
+```js
+  <div className="question">{this.state.questionText}</div>
+  <div className="answer">{this.state.answerText}</div>
+```
+where the question and answer text was simple text in the legacy codebase, but is not the content.value returned from a MathRichInput (and thus may - or may not - contain html or maths).
+
+Simply add the following code:
+
+```js
+  componentDidMount() {
+    renderMathInNode(document)
+  }
+
+  componentDidUpdate() {
+    renderMathInNode(document)
+  }
+```
+The renderMathInNode method will then:
+
+1. Search through all nodes including the supplied node and all its descendent nodes for text nodes
+2. Analyse the text to determine if it is text/html, application/x-zzish-html-math or application/x-tex
+3. 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
+
+```js
+  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
+
+1. Automatically open Expert mode if unable to render in MathQuill.
+2. Warn if switching from Expert mode to normal mode
+3. 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
+
+1. Bug: Deleting first equation when characters to the left, offset incorrect
+2. Bug: Deleting selected text when equation immediatly to left deletes the equation incorrectly
+3. Refactor button areas in the modal to be their own fixed components
+4. 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

package/babel.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+    presets: [
+        "@babel/env",
+        "@babel/react",
+    ],
+};