Merge pull request #903 from streamich/peritext-block-attributes

Peritext formatting event and API improvements

Author: streamich

package.json

@@ -66,7 +66,7 @@
     "bench:json-ot:ot-string:apply": "cd src/json-ot/__bench__ && yarn && yarn bench:ot-string:apply",
     "bench:json-ot:ot-string:compose-and-transform": "yarn build && cd src/json-ot/__bench__ && yarn && yarn bench:ot-string:compose-and-transform",
     "coverage": "yarn test --collectCoverage",
-    "typedoc": "npx typedoc@0.25.13 --tsconfig tsconfig.build.json",
+    "typedoc": "npx typedoc@0.28.5 --tsconfig tsconfig.build.json",
     "build:pages": "npx rimraf@5.0.5 gh-pages && mkdir -p gh-pages && cp -r typedocs/* gh-pages && cp -r coverage gh-pages/coverage",
     "deploy:pages": "gh-pages -d gh-pages",
     "publish-coverage-and-typedocs": "yarn typedoc && yarn coverage && yarn build:pages && yarn deploy:pages",
@@ -96,7 +96,7 @@
     "sonic-forest": "^1.2.0",
     "thingies": "^2.1.1",
     "tree-dump": "^1.0.2",
-    "very-small-parser": "^1.12.0"
+    "very-small-parser": "^1.13.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",

src/json-crdt-diff/JsonCrdtDiff.ts

@@ -1,6 +1,6 @@
 import {deepEqual} from '@jsonjoy.com/util/lib/json-equal/deepEqual';
 import {cmpUint8Array} from '@jsonjoy.com/util/lib/buffers/cmpUint8Array';
-import {type ITimespanStruct, type ITimestampStruct, type Patch, PatchBuilder, Timespan} from '../json-crdt-patch';
+import {type ITimespanStruct, type ITimestampStruct, type Patch, PatchBuilder} from '../json-crdt-patch';
 import {ArrNode, BinNode, ConNode, ObjNode, StrNode, ValNode, VecNode, type JsonNode} from '../json-crdt/nodes';
 import * as str from '../util/diff/str';
 import * as bin from '../util/diff/bin';

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

@@ -19,11 +19,12 @@ import {updateRga} from '../../json-crdt/hash';
 import type {ITimestampStruct} from '../../json-crdt-patch/clock';
 import type {Printable} from 'tree-dump/lib/types';
 import type {MarkerSlice} from './slice/MarkerSlice';
-import type {SliceSchema, SliceType} from './slice/types';
+import type {SliceSchema, SliceTypeSteps} from './slice/types';
 import type {SchemaToJsonNode} from '../../json-crdt/schema/types';
 import type {AbstractRga} from '../../json-crdt/nodes/rga';
 import type {ChunkSlice} from './util/ChunkSlice';
 import type {Stateful} from './types';
+import type {PersistedSlice} from './slice/PersistedSlice';
 
 const EXTRA_SLICES_SCHEMA = s.vec(s.arr<SliceSchema>([]));
 const LOCAL_DATA_SCHEMA = EXTRA_SLICES_SCHEMA;
@@ -36,26 +37,6 @@ export type LocalModel = Model<SchemaToJsonNode<typeof LOCAL_DATA_SCHEMA>>;
  * interact with the text.
  */
 export class Peritext<T = string> implements Printable, Stateful {
-  /**
-   * *Slices* are rich-text annotations that appear in the text. The "saved"
-   * slices are the ones that are persisted in the document.
-   */
-  public readonly savedSlices: Slices<T>;
-
-  /**
-   * *Extra slices* are slices that are not persisted in the document. However,
-   * they are still shared across users, i.e. they are ephemerally persisted
-   * during the editing session.
-   */
-  public readonly extraSlices: Slices<T>;
-
-  /**
-   * *Local slices* are slices that are not persisted in the document and are
-   * not shared with other users. They are used only for local annotations for
-   * the current user.
-   */
-  public readonly localSlices: Slices<T>;
-
   public readonly editor: Editor<T>;
   public readonly overlay = new Overlay<T>(this);
   public readonly blocks: Fragment<T>;
@@ -98,17 +79,6 @@ export class Peritext<T = string> implements Printable, Stateful {
     throw new Error('INVALID_STR');
   }
 
-  /** Select a single character before a point. */
-  public findCharBefore(point: Point<T>): Range<T> | undefined {
-    if (point.anchor === Anchor.After) {
-      const chunk = point.chunk();
-      if (chunk && !chunk.del) return this.range(this.point(point.id, Anchor.Before), point);
-    }
-    const id = point.prevId();
-    if (!id) return;
-    return this.range(this.point(id, Anchor.Before), this.point(id, Anchor.After));
-  }
-
   // ------------------------------------------------------------------- points
 
   /**
@@ -307,12 +277,38 @@ export class Peritext<T = string> implements Printable, Stateful {
     return deleted;
   }
 
+  // ------------------------------------------------------------------- slices
+
+  /**
+   * *Slices* are rich-text annotations that appear in the text. The "saved"
+   * slices are the ones that are persisted in the document.
+   */
+  public readonly savedSlices: Slices<T>;
+
+  /**
+   * *Extra slices* are slices that are not persisted in the document. However,
+   * they are still shared across users, i.e. they are ephemerally persisted
+   * during the editing session.
+   */
+  public readonly extraSlices: Slices<T>;
+
+  /**
+   * *Local slices* are slices that are not persisted in the document and are
+   * not shared with other users. They are used only for local annotations for
+   * the current user.
+   */
+  public readonly localSlices: Slices<T>;
+
+  public getSlice(id: ITimestampStruct): PersistedSlice<T> | undefined {
+    return this.savedSlices.get(id) || this.localSlices.get(id) || this.extraSlices.get(id);
+  }
+
   // ------------------------------------------------------------------ markers
 
   /** @deprecated Use the method in `Editor` and `Cursor` instead. */
   public insMarker(
     after: ITimestampStruct,
-    type: SliceType,
+    type: SliceTypeSteps,
     data?: unknown,
     char: string = Chars.BlockSplitSentinel,
   ): MarkerSlice<T> {

src/json-crdt-extensions/peritext/block/Block.ts

@@ -1,7 +1,7 @@
 import {printTree} from 'tree-dump/lib/printTree';
 import {CONST, updateJson, updateNum} from '../../../json-hash/hash';
 import {MarkerOverlayPoint} from '../overlay/MarkerOverlayPoint';
-import {UndefEndIter, type UndefIterator} from '../../../util/iterator';
+import {UndEndIterator, type UndEndNext} from '../../../util/iterator';
 import {Inline} from './Inline';
 import {formatType, getTag} from '../slice/util';
 import {Range} from '../rga/Range';
@@ -60,7 +60,7 @@ export class Block<T = string, Attr = unknown> extends Range<T> implements IBloc
    * Iterate through all overlay points of this block, until the next marker
    * (regardless if that marker is a child or not).
    */
-  public points0(withMarker: boolean = false): UndefIterator<OverlayPoint<T>> {
+  public points0(withMarker: boolean = false): UndEndNext<OverlayPoint<T>> {
     const txt = this.txt;
     const overlay = txt.overlay;
     const iterator = overlay.points0(this.marker);
@@ -82,10 +82,10 @@ export class Block<T = string, Attr = unknown> extends Range<T> implements IBloc
   }
 
   public points(withMarker?: boolean): IterableIterator<OverlayPoint<T>> {
-    return new UndefEndIter(this.points0(withMarker));
+    return new UndEndIterator(this.points0(withMarker));
   }
 
-  protected tuples0(): UndefIterator<OverlayTuple<T>> {
+  protected tuples0(): UndEndNext<OverlayTuple<T>> {
     const overlay = this.txt.overlay;
     const marker = this.marker;
     const iterator = overlay.tuples0(marker);
@@ -103,7 +103,7 @@ export class Block<T = string, Attr = unknown> extends Range<T> implements IBloc
   /**
    * @todo Consider moving inline-related methods to {@link LeafBlock}.
    */
-  public texts0(): UndefIterator<Inline<T>> {
+  public texts0(): UndEndNext<Inline<T>> {
     const txt = this.txt;
     const overlay = txt.overlay;
     const iterator = this.tuples0();
@@ -114,7 +114,7 @@ export class Block<T = string, Attr = unknown> extends Range<T> implements IBloc
     let isFirst = true;
     let next = iterator();
     let closed = false;
-    const newIterator: UndefIterator<Inline<T>> = () => {
+    const newIterator: UndEndNext<Inline<T>> = () => {
       if (closed) return;
       const pair = next;
       next = iterator();
@@ -146,7 +146,7 @@ export class Block<T = string, Attr = unknown> extends Range<T> implements IBloc
    * @todo Consider moving inline-related methods to {@link LeafBlock}.
    */
   public texts(): IterableIterator<Inline<T>> {
-    return new UndefEndIter(this.texts0());
+    return new UndEndIterator(this.texts0());
   }
 
   public text(): string {

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

@@ -11,7 +11,7 @@ import {CommonSliceType, type SliceTypeSteps, type SliceType, type SliceTypeStep
 import {isLetter, isPunctuation, isWhitespace, stepsEqual} from './util';
 import {ValueSyncStore} from '../../../util/events/sync-store';
 import {MarkerOverlayPoint} from '../overlay/MarkerOverlayPoint';
-import {UndefEndIter, type UndefIterator} from '../../../util/iterator';
+import {UndEndIterator, type UndEndNext} from '../../../util/iterator';
 import {tick, Timespan, type ITimespanStruct} from '../../../json-crdt-patch';
 import {CursorAnchor, SliceStacking, SliceHeaderMask, SliceHeaderShift, SliceTypeCon} from '../slice/constants';
 import type {Point} from '../rga/Point';
@@ -114,7 +114,7 @@ export class Editor<T = string> implements Printable {
     return cursor ?? this.addCursor();
   }
 
-  public cursors0(): UndefIterator<Cursor<T>> {
+  public cursors0(): UndEndNext<Cursor<T>> {
     const iterator = this.txt.localSlices.iterator0();
     return () => {
       while (true) {
@@ -130,7 +130,7 @@ export class Editor<T = string> implements Printable {
   }
 
   public cursors() {
-    return new UndefEndIter(this.cursors0());
+    return new UndEndIterator(this.cursors0());
   }
 
   public forCursor(callback: (cursor: Cursor<T>) => void): void {
@@ -777,7 +777,7 @@ export class Editor<T = string> implements Printable {
    * @param type The type of the marker.
    * @returns The inserted marker slice.
    */
-  public insStartMarker(type: SliceType): MarkerSlice<T> {
+  public insStartMarker(type: SliceTypeSteps): MarkerSlice<T> {
     const txt = this.txt;
     const start = txt.pointStart() ?? txt.pointAbsStart();
     start.refAfter();
@@ -794,7 +794,7 @@ export class Editor<T = string> implements Printable {
    * @param type The new block type.
    * @returns The marker slice at the point, or a new marker slice if there is none.
    */
-  public setBlockType(point: Point<T>, type: SliceType): MarkerSlice<T> {
+  public setBlockType(point: Point<T>, type: SliceTypeSteps): MarkerSlice<T> {
     const marker = this.getMarker(point);
     if (marker) {
       marker.update({type});
@@ -894,16 +894,15 @@ export class Editor<T = string> implements Printable {
     }
   }
 
-  public setStartMarker(type: SliceType, data?: unknown, slices: EditorSlices<T> = this.saved): MarkerSlice<T> {
+  public setStartMarker(type: SliceTypeSteps, data?: unknown, slices: EditorSlices<T> = this.saved): MarkerSlice<T> {
     const after = this.txt.pointStart() ?? this.txt.pointAbsStart();
     after.refAfter();
-    if (Array.isArray(type) && type.length === 1) type = type[0];
     return slices.slices.insMarkerAfter(after.id, type, data);
   }
 
   public tglMarkerAt(
     point: Point<T>,
-    type: SliceType,
+    type: SliceTypeSteps,
     data?: unknown,
     slices: EditorSlices<T> = this.saved,
     def: SliceTypeStep = SliceTypeCon.p,
@@ -912,21 +911,24 @@ export class Editor<T = string> implements Printable {
     const markerPoint = overlay.getOrNextLowerMarker(point);
     if (markerPoint) {
       const marker = markerPoint.marker;
-      const tag = marker.tag();
-      if (!Array.isArray(type)) type = [type];
-      const typeTag = type[type.length - 1];
-      if (tag === typeTag) type = [...type.slice(0, -1), def];
-      if (Array.isArray(type) && type.length === 1) type = type[0];
+      const markerTag = marker.tag();
+      const tagStep = type[type.length - 1];
+      const tag = Array.isArray(tagStep) ? tagStep[0] : tagStep;
+      if (markerTag === tag) type = [...type.slice(0, -1), def];
       marker.update({type});
     } else this.setStartMarker(type, data, slices);
   }
 
-  public updMarkerAt(point: Point<T>, type: SliceType, data?: unknown, slices: EditorSlices<T> = this.saved): void {
+  public updMarkerAt(
+    point: Point<T>,
+    type: SliceTypeSteps,
+    data?: unknown,
+    slices: EditorSlices<T> = this.saved,
+  ): void {
     const overlay = this.txt.overlay;
     const markerPoint = overlay.getOrNextLowerMarker(point);
     if (markerPoint) {
       const marker = markerPoint.marker;
-      if (Array.isArray(type) && type.length === 1) type = type[0];
       marker.update({type});
     } else this.setStartMarker(type, data, slices);
   }
@@ -939,7 +941,7 @@ export class Editor<T = string> implements Printable {
    * @param data Custom data of the slice.
    */
   public tglMarker(
-    type: SliceType,
+    type: SliceTypeSteps,
     data?: unknown,
     selection: Range<T>[] | IterableIterator<Range<T>> = this.cursors(),
     slices: EditorSlices<T> = this.saved,
@@ -957,7 +959,7 @@ export class Editor<T = string> implements Printable {
    *     of the document.
    */
   public updMarker(
-    type: SliceType,
+    type: SliceTypeSteps,
     data?: unknown,
     selection: Range<T>[] | IterableIterator<Range<T>> = this.cursors(),
     slices: EditorSlices<T> = this.saved,
@@ -1103,7 +1105,7 @@ export class Editor<T = string> implements Printable {
         const [, , , type, data] = split;
         const after = txt.pointAt(curr);
         after.refAfter();
-        txt.savedSlices.insMarkerAfter(after.id, type, data);
+        txt.savedSlices.insMarkerAfter(after.id, type as SliceTypeSteps, data);
         curr += 1;
       }
     }

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

@@ -1,11 +1,11 @@
-import type {UndefIterator} from '../../../util/iterator';
+import type {UndEndNext} from '../../../util/iterator';
 import type {Point} from '../rga/Point';
 import type {Range} from '../rga/Range';
 import type {SliceType} from '../slice';
 import type {SliceStacking} from '../slice/constants';
 import type {ChunkSlice} from '../util/ChunkSlice';
 
-export type CharIterator<T> = UndefIterator<ChunkSlice<T>>;
+export type CharIterator<T> = UndEndNext<ChunkSlice<T>>;
 export type CharPredicate<T> = (char: T) => boolean;
 
 export type EditorPosition<T = string> = Point<T> | number | [at: number, anchor: 0 | 1];

src/json-crdt-extensions/peritext/events/__tests__/cursor.spec.ts

@@ -12,6 +12,26 @@ const testSuite = (getKit: () => Kit) => {
     return {...kit, et};
   };
 
+  describe('clearing all cursors', () => {
+    test('can remove a single caret cursor', () => {
+      const kit = setup();
+      kit.et.cursor({at: [2]});
+      expect(kit.editor.cursorCount()).toBe(1);
+      kit.et.cursor({clear: true});
+      expect(kit.editor.cursorCount()).toBe(0);
+    });
+
+    test('can remove multiple cursors', () => {
+      const kit = setup();
+      kit.et.cursor({at: [2]});
+      expect(kit.editor.cursorCount()).toBe(1);
+      kit.et.cursor({at: [3, 5], add: true});
+      expect(kit.editor.cursorCount()).toBe(2);
+      kit.et.cursor({clear: true});
+      expect(kit.editor.cursorCount()).toBe(0);
+    });
+  });
+
   describe('with absolute position ("at" property set)', () => {
     describe('caret', () => {
       test('can set the caret at the document start', () => {