Support cursors at end of document

[miguelangel-dev]

Cursors API tracks the following character; it is the expected result in collaboration for TextEditors. Because of that, Automerge Cursors API, is not expected to accept end of document (length) as valid input. It is expected to track existing characters. It is fine, except by selection. In cursor selection, [0, length] is the valid range. Because the end of the document will define the future inputs of the user.

In that upstream PR, Automerge introduced special cases to support exactly that behaviour. Instead of introducing an alternative method into Swift bindings, I consider it an implementation detail. Cursors will be able to accept length as a valid range, and internally it will be mapped to introduced CursorPosition

[heckj]

Thanks @miguelangel-dev - back me up a second and help me understand the new functionality that's being exposed.

With this PR we're removing cursor() & cursorAt(), replacing that (if I'm reading correctly with cursorSelection and cursorSelectionAt - and then adding a cursorPosition (and cursorPositionAt). Not that the earlier names were fantastic, but the new names aren't telling me what's going on or implying any clear path of how to use these, and how and what a Cursor object represents when used in a Swift context.

I'm guessing from the parameters that the first is returning a cursor reference, and the second (new cursorPosition) takes the cursor and returns back an index position from it - so a sort of inverse. Are the Cursor types returned expected to be ephemeral, or persistent - a sort of identifier stored in the Automerge document. Can you stash this in some value/encoded form, and then reference again later, for example - when an App opens up, re-hydrating the Cursor, and then it still references a position?

Are there any mechanisms for moving the cursor around, or is this just a "position" that shifts around as document updates get applied?

@alexjg feel free to chime in here - this is just a portion of the API that I haven't really explored and used, and the use cases around it aren't super clear to me.

My only concern here is that the naming of the API presented seems really unclear, and just from reading them I wouldn't have any sense of what and how I should use them.

[miguelangel-dev]

@heckj thanks for taking the time to review the PR:

With this PR we're removing cursor() & cursorAt(), replacing that (if I'm reading correctly with cursorSelection and cursorSelectionAt- and then adding acursorPosition(andcursorPositionAt)

Thats it. PR is not modifying existing position methods. Just introducing a new case into cursor for supporting length as a valid input to set a cursor to the end of the document. Previously, accepted range was [0, length - 1]

When an App opens up, re-hydrating the Cursor, and then it still references a position?... Are there any mechanisms for moving the cursor around, or is this just a "position" that shifts around as document updates get applied?

I agree that naming is not the best one, and probably the documentation neither. In 872a39d you will notice I have made the public API more swiftly and introduced some clarifications in the documentation.

Using absolute index-based positions in a text document is unreliable, especially in collaborative environments, since any document modification can disrupt indices, requiring additional tracking. Instead, Cursor provides a reliable way to track positions over time without being affected by document changes. The cursor remains anchored to the following character. However, in some cases, retrieving the absolute index may be necessary for temporary calculations, such as updating user selections. This is where the inverse operation position comes into play.

[alexjg]

The use of "cursor" here is by analogy to it's use in the database world as a stable reference to some position in a sequence. This may actually be quite a confusing name because it's a bit different to a cursor in the world of text editing. The main difference is that the reference we return here points at a specific element of a sequence whereas a text editing cursor points at the gap between elements of the sequence (the characters).

The references returned by the cursor API are a bit like object IDs in that they are stable identifiers which can be stored or transmitted and later used to resolve to a position in the sequence they were created for. cursorPosition should probably be named something more evocative like resolveCursor.

I would be open to changing the name of the type entirely. At some point we will generalise this concept to be able to point to any part of the document so maybe a good name would be something like "stable reference".

[miguelangel-dev]

I am open to refactoring the names cursor and position in public API to whatever aligns well with future iterations in Automerge. Or to keep the consistency with the rest of the existing API. Just let me know what is preferable.

On my side, using cursor(at:) to refer to the logical reference and position(for:) to resolve the absolute index aligns well in general with the text editor's environment.

[heckj]

@miguelangel-dev sorry for the delay!

And thank you both for chiming in to help me understand. I've asked for a few changes to the documentation, and I'm happy with the updated names. I'd guess using "cursor" will still run afoul of someone being confused, as it's a fairly overloaded term, but with including the detail that it tracks a specific character through changes should help alleviate that - at least for the folks who read the docs.

I couldn't come up with any better names myself, and I think cursor and it's inverse of position work well for what this API is doing. Again, thank you for shortening to the simpler, more direct names - I think that'll help tremendously.

[heckj]

(I'd submitted the last review as "comment" when I meant to mark is at "requesting changes")

[miguelangel-dev]

I couldn't come up with any better names myself, and I think cursor and it's inverse of position work well for what this API is doing. Again, thank you for shortening to the simpler, more direct names - I think that'll help tremendously.

I've implemented your suggestions—thanks for the help with the grammar and readability improvements. The documentation now has a much more polished ❤️