From 4aacb487d292b25b80d87d9e0b5aed612b6872fb Mon Sep 17 00:00:00 2001
From: Kevin Jahns <kevin.jahns@protonmail.com>
Date: Thu, 7 Apr 2022 22:11:10 +0200
Subject: [PATCH] complete documentation about relative positions
---
README.md | 50 +++++++++++++++++++++++++++++++++++++++++++-------
1 file changed, 43 insertions(+), 7 deletions(-)
diff --git a/README.md b/README.md
index 2d3589ac..719bea95 100644
--- a/README.md
+++ b/README.md
@@ -791,6 +791,21 @@ Convert V2 update format to the V1 update format.
### Relative Positions
+When working with collaborative documents, we often need to work with positions.
+Positions may represent cursor locations, selection ranges, or even assign a
+comment to a range of text. Normal index-positions (expressed as integers) are
+not convenient to use because the index-range is invalidated as soon as a remote
+change manipulates the document. Relative positions give you a powerful API to
+express positions.
+
+A relative position is fixated to an element in the shared document and is not
+affected by remote changes. I.e. given the document `"a|c"`, the relative
+position is attached to `c`. When a remote user modifies the document by
+inserting a character before the cursor, the cursor will stay attached to the
+character `c`. `insert(1, 'x')("a|c") = "ax|c"`. When the relative position is
+set to the end of the document, it will stay attached to the end of the
+document.
+
#### Example: Transform to RelativePosition and back
```js
@@ -825,14 +840,35 @@ pos.index === 2 // => true
```
<dl>
- <b><code>Y.createRelativePositionFromTypeIndex(Uint8Array|Y.Type, number)</code></b>
- <dd></dd>
- <b><code>Y.createAbsolutePositionFromRelativePosition(RelativePosition, Y.Doc)</code></b>
- <dd></dd>
- <b><code>Y.encodeRelativePosition(RelativePosition):Uint8Array</code></b>
- <dd></dd>
+ <b><code>
+Y.createRelativePositionFromTypeIndex(type:Uint8Array|Y.Type, index: number
+[, assoc=0])
+ </code></b>
+ <dd>
+Create a relative position fixated to the i-th element in any sequence-like
+shared type (if <code>assoc >= 0</code>). By default, the position associates
+with the character that comes after the specified index position. If
+<code>assoc < 0</code>, then the relative position associates with the character
+before the specified index position.
+ </dd>
+ <b><code>
+Y.createAbsolutePositionFromRelativePosition(RelativePosition, Y.Doc):
+{ type: Y.AbstractType, index: number, assoc: number } | null
+ </code></b>
+ <dd>
+Create an absolute position from a relative position. If the relative position
+cannot be referenced, or the type is deleted, then the result is null.
+ </dd>
+ <b><code>
+Y.encodeRelativePosition(RelativePosition):Uint8Array
+ </code></b>
+ <dd>
+Encode a relative position to an Uint8Array. Binary data is the preferred
+encoding format for document updates. If you prefer JSON encoding, you can
+simply JSON.stringify / JSON.parse the relative position instead.
+ </dd>
<b><code>Y.decodeRelativePosition(Uint8Array):RelativePosition</code></b>
- <dd></dd>
+ <dd>Decode a binary-encoded relative position to a RelativePositon object.</dd>
</dl>
### Y.UndoManager