document postEditor.setRange and change edit methods to use it

[bantic]

#248 added postEditor.setRange (and editor.selectRange). More of the edit methods in postEditor should be updated to use setRange where applicable, and write documentation to describe how to use this API

[mixonic]

Things that need to be figured out:

• editor.cursor.clearSelection() How to migrate off
• editor.cursor should have a deprecation message added. Cursor should become private API and no longer have offsets on it?
• editor.cursor.hasCursor() How to migrate off

[rlivsey]

Some way of getting the current cursor position & setting it again later would be useful if cursor itself is to become private.

I'm currently using the following functions to stash & restore a cursor position when a document is updated externally:

function stashCursor(editor) {
  if (!editor || !editor.cursor.hasCursor()) {
    return;
  }

  const { offset, section } = editor.cursor.offsets.head;
  const index = editor.post.sections.toArray().indexOf(section);
  return { index, offset };
}

function reapplyCursor(editor, selection) {
  if (!editor || !selection) {
    return;
  }

  const { index, offset } = selection;

  const section = editor.post.sections.objectAt(index);
  if (!section) {
    return;
  }

  const position = new Position(section, offset);
  const range    = new Range(position, position);

  editor.cursor.selectRange(range);

  editor._reportSelectionState(); // TODO - should we have to do this?
}

[mixonic]

@rlivsey so what we're doing is moving away from editor.cursor.offsets to a new API, editor.range.

editor.cursor.offsets always reads the cursor position from actual DOM. Once you've done something to modify the abstract post, that position may no longer be coupled to any existing section.

editor.range, as you set it, memoizes the range. So after setting, if you ask you'll get back the stored range. This allows us to change the range (and query it) several times during postEditing and flush the position once after rendering.

Some APIs:

• Range, which is a head and tail position
• Position
• setting and getting range
• renderRange is called to flush and render the range, for example after reparsing

So we're definitely going to keep a cursor range, but it should settle around editor.range and not the cursor API. Still questions to answer though.

[bantic]

released in v0.10.4