Merge branch 'master' into next

Author: streamich

src/json-crdt-extensions/peritext/Peritext.ts

@@ -1,17 +1,18 @@
-import {Anchor, SliceBehavior} from './constants';
-import {Point} from './point/Point';
-import {Range} from './slice/Range';
+import {Anchor} from './rga/constants';
+import {Point} from './rga/Point';
+import {Range} from './rga/Range';
 import {Editor} from './editor/Editor';
 import {printTree} from '../../util/print/printTree';
 import {ArrNode, StrNode} from '../../json-crdt/nodes';
 import {Slices} from './slice/Slices';
 import {type ITimestampStruct} from '../../json-crdt-patch/clock';
 import type {Model} from '../../json-crdt/model';
 import type {Printable} from '../../util/print/types';
-import type {SliceType} from './types';
-import type {PersistedSlice} from './slice/PersistedSlice';
-import {CONST} from '../../json-hash';
 
+/**
+ * Context for a Peritext instance. Contains all the data and methods needed to
+ * interact with the text.
+ */
 export class Peritext implements Printable {
   public readonly slices: Slices;
   public readonly editor: Editor;
@@ -25,48 +26,117 @@ export class Peritext implements Printable {
     this.editor = new Editor(this);
   }
 
-  public point(id: ITimestampStruct, anchor: Anchor = Anchor.After): Point {
-    return new Point(this, id, anchor);
+  public strApi() {
+    return this.model.api.wrap(this.str);
   }
 
+  // ------------------------------------------------------------------- Points
+
+  /**
+   * Creates a point at a character ID.
+   *
+   * @param id Character ID to which the point should be attached.
+   * @param anchor Whether the point should be before or after the character.
+   * @returns The point.
+   */
+  public point(id: ITimestampStruct = this.str.id, anchor: Anchor = Anchor.After): Point {
+    return new Point(this.str, id, anchor);
+  }
+
+  /**
+   * Creates a point at a view position in the text. The `pos` argument specifies
+   * the position of the character, not the gap between characters.
+   *
+   * @param pos Position of the character in the text.
+   * @param anchor Whether the point should attach before or after a character.
+   * @returns The point.
+   */
   public pointAt(pos: number, anchor: Anchor = Anchor.Before): Point {
+    // TODO: Provide ability to attach to the beginning of the text?
+    // TODO: Provide ability to attach to the end of the text?
     const str = this.str;
     const id = str.find(pos);
     if (!id) return this.point(str.id, Anchor.After);
     return this.point(id, anchor);
   }
 
-  public pointAtStart(): Point {
+  /**
+   * Creates a point which is attached to the start of the text, before the
+   * first character.
+   *
+   * @returns A point at the start of the text.
+   */
+  public pointAbsStart(): Point {
     return this.point(this.str.id, Anchor.After);
   }
 
-  public pointAtEnd(): Point {
+  /**
+   * Creates a point which is attached to the end of the text, after the last
+   * character.
+   *
+   * @returns A point at the end of the text.
+   */
+  public pointAbsEnd(): Point {
     return this.point(this.str.id, Anchor.Before);
   }
 
+  // ------------------------------------------------------------------- Ranges
+
+  /**
+   * Creates a range from two points. The points can be in any order.
+   *
+   * @param p1 Point
+   * @param p2 Point
+   * @returns A range with points in correct order.
+   */
+  public rangeFromPoints(p1: Point, p2: Point): Range {
+    return Range.from(this.str, p1, p2);
+  }
+
+  /**
+   * Creates a range from two points, the points have to be in the correct order.
+   *
+   * @param start Start point of the range, must be before or equal to end.
+   * @param end End point of the range, must be after or equal to start.
+   * @returns A range with the given start and end points.
+   */
   public range(start: Point, end: Point): Range {
-    return new Range(this, start, end);
+    return new Range(this.str, start, end);
   }
 
+  /**
+   * A convenience method for creating a range from a view position and a length.
+   * See {@link Range.at} for more information.
+   *
+   * @param start Position in the text.
+   * @param length Length of the range.
+   * @returns A range from the given position with the given length.
+   */
   public rangeAt(start: number, length: number = 0): Range {
-    const str = this.str;
-    if (!length) {
-      const startId = !start ? str.id : str.find(start - 1) || str.id;
-      const point = this.point(startId, Anchor.After);
-      return this.range(point, point);
-    }
-    const startId = str.find(start) || str.id;
-    const endId = str.find(start + length - 1) || startId;
-    const startEndpoint = this.point(startId, Anchor.Before);
-    const endEndpoint = this.point(endId, Anchor.After);
-    return this.range(startEndpoint, endEndpoint);
+    return Range.at(this.str, start, length);
   }
 
+  // --------------------------------------------------------------- Insertions
+
+  /**
+   * Insert plain text at a view position in the text.
+   *
+   * @param pos View position in the text.
+   * @param text Text to insert.
+   */
   public insAt(pos: number, text: string): void {
-    const str = this.model.api.wrap(this.str);
+    const str = this.strApi();
     str.ins(pos, text);
   }
 
+  /**
+   * Insert plain text after a character referenced by its ID and return the
+   * ID of the insertion operation.
+   *
+   * @param after Character ID after which the text should be inserted.
+   * @param text Text to insert.
+   * @returns ID of the insertion operation.
+   */
   public ins(after: ITimestampStruct, text: string): ITimestampStruct {
     if (!text) throw new Error('NO_TEXT');
     const api = this.model.api;
@@ -75,22 +145,6 @@ export class Peritext implements Printable {
     return textId;
   }
 
-  public insSlice(
-    range: Range,
-    behavior: SliceBehavior,
-    type: SliceType,
-    data?: unknown | ITimestampStruct,
-  ): PersistedSlice {
-    // if (range.isCollapsed()) throw new Error('INVALID_RANGE');
-    // TODO: If range is not collapsed, check if there are any visible characters in the range.
-    const slice = this.slices.ins(range, behavior, type, data);
-    return slice;
-  }
-
-  public delSlice(sliceId: ITimestampStruct): void {
-    this.slices.del(sliceId);
-  }
-
   /** Select a single character before a point. */
   public findCharBefore(point: Point): Range | undefined {
     if (point.anchor === Anchor.After) {

src/json-crdt-extensions/peritext/editor/Editor.ts

@@ -1,11 +1,12 @@
 import {Cursor} from '../slice/Cursor';
-import {Anchor, SliceBehavior} from '../constants';
+import {Anchor} from '../rga/constants';
+import {SliceBehavior} from '../slice/constants';
 import {tick, type ITimestampStruct} from '../../../json-crdt-patch/clock';
 import {PersistedSlice} from '../slice/PersistedSlice';
-import type {Range} from '../slice/Range';
+import type {Range} from '../rga/Range';
 import type {Peritext} from '../Peritext';
 import type {Printable} from '../../../util/print/types';
-import type {Point} from '../point/Point';
+import type {Point} from '../rga/Point';
 import type {SliceType} from '../types';
 
 export class Editor implements Printable {
@@ -54,8 +55,8 @@ export class Editor implements Printable {
       const api = model.api;
       api.builder.del(str.id, range);
       api.apply();
-      if (start.anchor === Anchor.After) cursor.setCaret(start.id);
-      else cursor.setCaret(start.prevId() || str.id);
+      if (start.anchor === Anchor.After) cursor.setAfter(start.id);
+      else cursor.setAfter(start.prevId() || str.id);
     }
     return cursor.start.id;
   }
@@ -68,7 +69,8 @@ export class Editor implements Printable {
     if (!text) return;
     const after = this.collapseSelection();
     const textId = this.txt.ins(after, text);
-    this.cursor.setCaret(textId, text.length - 1);
+    const shift = text.length - 1;
+    this.cursor.setAfter(shift ? tick(textId, shift) : textId);
   }
 
   /**
@@ -120,6 +122,14 @@ export class Editor implements Printable {
   }
 
   public insertSlice(type: SliceType, data?: unknown | ITimestampStruct): PersistedSlice {
-    return this.txt.insSlice(this.cursor, SliceBehavior.Stack, type, data);
+    return this.txt.slices.ins(this.cursor, SliceBehavior.Stack, type, data);
+  }
+
+  public insertOverwriteSlice(type: SliceType, data?: unknown | ITimestampStruct): PersistedSlice {
+    return this.txt.slices.ins(this.cursor, SliceBehavior.Overwrite, type, data);
+  }
+
+  public insertEraseSlice(type: SliceType, data?: unknown | ITimestampStruct): PersistedSlice {
+    return this.txt.slices.ins(this.cursor, SliceBehavior.Erase, type, data);
   }
 }