Merge pull request #321 from desmosinc/mike/allow-set-selection

Allow setting selection

Author: mikehaverstock

docs/Api_Methods.md

@@ -173,10 +173,33 @@ If the cursor is before the plus this method would return:
 {
   latex: 'a+b',
   startIndex: 1,
-  endIndex: 1
+  endIndex: 1,
+  opaqueSnapshot: {...}
 }
 ```
 
+You can pass the result of `.selection()` back into `.selection()` to restore a cursor / selection. This works by taking a snapshot of the selection you currently have and recording
+enough information to restore it within `opaqueSnapshot`. You should not peek inside of `opaqueSnapshot` or permanently store it. This is valid only for this version of MathQuill. This selection is also only valid if the MQ's latex is identical. The MQ can go through changes, but when you try to restore the selection the current latex must match the latex when the selection snapshot was created.
+
+```js
+// this would work
+mq.latex('abc');
+mq.select();
+const selection = mq.selection(); // takes a snapshot of the selection
+mq.latex('123');
+mq.latex('abc');
+mq.selection(selection); // will restore the selection
+```
+
+```js
+// this would not work
+mq.latex('abc');
+mq.select();
+const selection = mq.selection(); // takes a snapshot of the selection
+mq.latex('123');
+mq.selection(selection); // will restore the selection
+```
+
 # Editable MathField methods
 
 Editable math fields have all of the [above](#mathquill-base-methods) methods in addition to the ones listed here.

src/mathquill.d.ts

@@ -19,6 +19,17 @@ declare namespace MathQuill {
       handlers?: HandlerOptions;
     };
 
+    type ExportedLatexSelection = {
+      latex: string;
+      startIndex: number;
+      endIndex: number;
+      opaqueSnapshot: {
+        uncleanedLatex: string;
+        cursorInsertPath: string;
+        signedSelectionSize: number;
+      };
+    };
+
     interface BaseMathQuill {
       id: number;
       data: { [key: string]: any };
@@ -29,12 +40,8 @@ declare namespace MathQuill {
       html: () => string;
       mathspeak: () => string;
       text(): string;
-      selection(): {
-        latex: string;
-        startIndex: number;
-        endIndex: number;
-      };
-
+      selection(selection: ExportedLatexSelection): this;
+      selection(): ExportedLatexSelection;
       //chainable methods
       config(opts: Config): this;
       latex(latex: string): this;

src/publicapi.ts

@@ -338,7 +338,14 @@ function getInterface(v: number): MathQuill.v3.API | MathQuill.v1.API {
       return this.__controller.exportLatex();
     }
 
-    selection() {
+    selection(selection: ExportedLatexSelection): this;
+    selection(): ExportedLatexSelection;
+    selection(selection?: ExportedLatexSelection) {
+      if (selection) {
+        this.__controller.restoreLatexSelection(selection);
+        return this;
+      }
+
       return this.__controller.exportLatexSelection();
     }
     html() {

src/services/latex.ts

@@ -4,6 +4,17 @@ class TempSingleCharNode extends MQNode {
   }
 }
 
+type ExportedLatexSelection = {
+  latex: string;
+  startIndex: number;
+  endIndex: number;
+  opaqueSnapshot: {
+    uncleanedLatex: string;
+    cursorInsertPath: string;
+    signedSelectionSize: number;
+  };
+};
+
 // Parser MathBlock
 var latexMathParser = (function () {
   function commandToBlock(cmd: MQNode | Fragment): MathBlock {
@@ -116,18 +127,140 @@ class Controller_latex extends Controller_keystroke {
 
     return this;
   }
-  exportLatexSelection() {
+
+  // this traces up from the node to the root by first going left as much as possible
+  // then going up one parent. Then going left as much as possible then going up on parent.
+  // It continues this pattern until it finds the root. The "path" that this algorithm
+  // constructs is from the root back down to this node. So it will output the path in
+  // reverse traversal order and will replace lefts with rights and ups with downs.
+  private findPathFromRootToNode(node: MQNode | Cursor | Anticursor): string {
+    let path = '';
+    do {
+      while (node[L]) {
+        path = 'R' + path;
+        node = node[L];
+      }
+
+      if (node.parent) {
+        node = node.parent;
+        path = 'D' + path;
+      } else {
+        return path;
+      }
+    } while (true);
+  }
+
+  private insertCursorAtPath(path: string): boolean {
+    if (!path) return false;
+
+    let node: MQNode = this.root;
+
+    // We generate the path starting from the node working up to the root.
+    // So we need to work backwards when following the path. The very last instruction
+    // we encounter does not point to a node. It points to a space where a cursor could
+    // be inserted: either just to the right of the current node ("R") or just to the
+    // left of the current node's children ("D")
+    const lastInstructionI = path.length - 1;
+    for (let i = 0; i < lastInstructionI; i++) {
+      const instruction = path[i];
+
+      if (instruction === 'D') {
+        const end = node.children().getEnd(L);
+        if (!end) return false;
+        node = end;
+      } else if (instruction === 'R') {
+        const end = node[R];
+        if (!end) return false;
+        node = end;
+      } else {
+        return false;
+      }
+    }
+
+    const lastInstruction = path[lastInstructionI];
+    if (lastInstruction === 'D') {
+      this.cursor.clearSelection().endSelection();
+      this.cursor.insAtLeftEnd(node);
+      return true;
+    } else if (lastInstruction === 'R') {
+      this.cursor.clearSelection().endSelection();
+      this.cursor.insRightOf(node);
+      return true;
+    } else {
+      return false;
+    }
+  }
+
+  restoreLatexSelection(data: ExportedLatexSelection) {
+    const currentUncleanedLatex =
+      this.exportLatexSelection().opaqueSnapshot.uncleanedLatex;
+    const { cursorInsertPath, signedSelectionSize, uncleanedLatex } =
+      data.opaqueSnapshot;
+
+    // verify the uncleanedLatex are identical. We need the trees to be identical so that the
+    // path instructions are relative to an identical tree structure
+    if (currentUncleanedLatex !== uncleanedLatex) return;
+
+    if (!this.insertCursorAtPath(cursorInsertPath)) return;
+
+    if (signedSelectionSize) {
+      this.withIncrementalSelection((selectDir) => {
+        const dir = signedSelectionSize < 0 ? L : R;
+        const count = Math.abs(signedSelectionSize);
+        for (let i = 0; i < count; i += 1) {
+          selectDir(dir);
+        }
+      });
+    }
+  }
+
+  // any time there's a selection there is a cursor and anticursor. The
+  // anticursor is the anchor, and the cursor is the head. It should be
+  // true that these are siblings. If you trace right or left far enough
+  // you will reach the other one. This returns the direction and magnitude
+  // of how many hops it takes to find the cursor from the anticursor. Otherwise
+  // returns 0. The idea is to try this both with L and R and use the one, if any,
+  // that comes back with a non-zero answer.
+  private findSignedSelectionSizeInDir(dir: L | R) {
+    const cursor = this.cursor;
+    const anticursor = cursor.anticursor;
+    if (!anticursor) return 0;
+
+    let count = 0;
+    let node = anticursor[dir];
+    while (node !== cursor[dir]) {
+      if (!node) return 0;
+
+      count += dir;
+      node = node[dir];
+    }
+
+    return count;
+  }
+
+  exportLatexSelection(): ExportedLatexSelection {
     var ctx: LatexContext = {
       latex: '',
       startIndex: -1,
       endIndex: -1
     };
 
+    let cursorInsertPath: string = '';
+    let signedSelectionSize: number = 0;
+
     var selection = this.cursor.selection;
-    if (selection) {
+    if (selection && this.cursor.anticursor) {
+      cursorInsertPath = this.findPathFromRootToNode(this.cursor.anticursor);
+
       ctx.startSelectionBefore = selection.getEnd(L);
       ctx.endSelectionAfter = selection.getEnd(R);
+
+      signedSelectionSize =
+        this.findSignedSelectionSizeInDir(L) ||
+        this.findSignedSelectionSizeInDir(R);
     } else {
+      cursorInsertPath = this.findPathFromRootToNode(this.cursor);
+
       var cursorL = this.cursor[L];
       if (cursorL) {
         ctx.startSelectionAfter = cursorL;
@@ -146,26 +279,26 @@ class Controller_latex extends Controller_keystroke {
     this.root.latexRecursive(ctx);
 
     // need to clean the latex
-    var originalLatex = ctx.latex;
-    var cleanLatex = this.cleanLatex(originalLatex);
+    var uncleanedLatex = ctx.latex;
+    var cleanLatex = this.cleanLatex(uncleanedLatex);
     var startIndex = ctx.startIndex;
     var endIndex = ctx.endIndex;
 
     // assumes that the cleaning process will only remove characters. We
-    // run through the originalLatex and cleanLatex to find differences.
+    // run through the uncleanedLatex and cleanLatex to find differences.
     // when we find differences we see how many characters are dropped until
     // we sync back up. While detecting missing characters we decrement the
     // startIndex and endIndex if appropriate.
     var j = 0;
     for (var i = 0; i < ctx.endIndex; i++) {
-      if (originalLatex[i] !== cleanLatex[j]) {
+      if (uncleanedLatex[i] !== cleanLatex[j]) {
         if (i < ctx.startIndex) {
           startIndex -= 1;
         }
         endIndex -= 1;
 
         // do not increment j. We wan to keep looking at this same
-        // cleanLatex character until we find it in the originalLatex
+        // cleanLatex character until we find it in the uncleanedLatex
       } else {
         j += 1; //move to next cleanLatex character
       }
@@ -174,7 +307,12 @@ class Controller_latex extends Controller_keystroke {
     return {
       latex: cleanLatex,
       startIndex: startIndex,
-      endIndex: endIndex
+      endIndex: endIndex,
+      opaqueSnapshot: {
+        uncleanedLatex,
+        cursorInsertPath,
+        signedSelectionSize
+      }
     };
   }