Adds documentation for PathRef (#4740)

docs/api/locations/README.md

@@ -8,6 +8,7 @@ type Location = Path | Point | Range
 
 - [Location](./location.md)
 - [Path](./path.md)
+- [PathRef](./path-ref.md)
 - [Point](./point.md)
 - [PointEntry](./pointe-entry.md)
 - [Range](./range.md)

docs/api/locations/path-ref.md

@@ -0,0 +1,24 @@
+# PathRef API
+
+`PathRef` objects keep a specific path in a document synced over time as new operations are applied to the editor. You can access their property `current` at any time for the up-to-date `Path` value.
+When you no longer need to track this location, call `unref()` to free the resources.
+
+```typescript
+interface PathRef {
+  current: Path | null
+  affinity: 'forward' | 'backward' | null
+  unref(): Path | null
+}
+```
+
+- [Static methods](path-ref.md#static-methods)
+  - [Transform methods](path-ref.md#trasnform-methods)
+
+## Static methods
+
+### Transform methods
+
+#### `PathRef.transform(ref: PathRef, op: Operation)`
+
+Transform the path refs current value by an `op`.
+The editor calls this as needed, so normally you won't need to.

docs/api/locations/point-ref.md

@@ -1,6 +1,7 @@
 # PointRef API
 
 `PointRef` objects keep a specific point in a document synced over time as new operations are applied to the editor. You can access their property `current` at any time for the up-to-date `Point` value.
+When you no longer need to track this location, call `unref()` to free the resources.
 
 ```typescript
 interface PointRef {
@@ -28,4 +29,4 @@ It also returns the current value.
 #### `PointRef.transform(ref: PointRef, op: Operation)`
 
 Transform the point refs current value by an `op`.
-Rarely needed, as the PointRef is updated when the editor is updated.
+The editor calls this as needed, so normally you won't need to.

docs/api/locations/range-ref.md

@@ -1,6 +1,7 @@
 # RangeRef API
 
 `RangeRef` objects keep a specific range in a document synced over time as new operations are applied to the editor. You can access their property `current` at any time for the up-to-date `Range` value.
+When you no longer need to track this location, call `unref()` to free the resources.
 
 ```typescript
 interface RangeRef {
@@ -38,5 +39,5 @@ It also returns the current value.
 
 #### `RangeRef.transform(ref: RangeRef, op: Operation)`
 
-Transform the range refs current value by an `op`.  
-Rarely needed, as the RangeRef is updated when the editor is updated.
+Transform the range refs current value by an `op`.
+The editor calls this as needed, so normally you won't need to.

site/examples/paste-html.tsx

@@ -226,7 +226,7 @@ const initialValue: Descendant[] = [
       { text: "'text/plain'", code: true },
       {
         text:
-          " data. That's okay for some use cases, but sometimes you want users to be able to paste in content and have it maintaing its formatting. To do this, your editor needs to handle ",
+          " data. That's okay for some use cases, but sometimes you want users to be able to paste in content and have it maintain its formatting. To do this, your editor needs to handle ",
       },
       { text: "'text/html'", code: true },
       { text: ' data. ' },