json-joy
Version:
Collection of libraries for building collaborative editing apps.
203 lines (202 loc) • 8.24 kB
TypeScript
import { type ITimestampStruct } from '../../../json-crdt-patch/clock';
import { Anchor } from './constants';
import { ChunkSlice } from '../util/ChunkSlice';
import type { AbstractRga, Chunk } from '../../../json-crdt/nodes/rga';
import type { Stateful } from '../types';
import type { Printable } from 'tree-dump/lib/types';
/**
* A "point" in a rich-text Peritext document. It is a combination of a
* character ID and an anchor. Anchor specifies the side of the character to
* which the point is attached. For example, a point with an anchor "before" .▢
* points just before the character, while a point with an anchor "after" ▢.
* points just after the character. Points attached to string characters are
* referred to as *relative* points, while points attached to the beginning or
* end of the string are referred to as *absolute* points.
*
* The *absolute* points are reference the string itself, by using the string's
* ID as the character ID. The *absolute (abs) start* references the very start
* of the string, before the first character, and even before any deleted
* characters. The *absolute (abs) end* references the very end of the string,
* after the last character, and even after any deleted characters at the end
* of the string.
*/
export declare class Point<T = string> implements Pick<Stateful, 'refresh'>, Printable {
protected readonly rga: AbstractRga<T>;
id: ITimestampStruct;
anchor: Anchor;
constructor(rga: AbstractRga<T>, id: ITimestampStruct, anchor: Anchor);
/**
* Overwrites the internal state of this point with the state of the given
* point.
*
* @param point Point to copy.
*/
set(point: Point<T>): void;
/**
* Creates a copy of this point.
*
* @returns Returns a new point with the same ID and anchor as this point.
*/
clone(): Point<T>;
copy(mutate: (copy: Point<T>) => void): Point<T>;
/**
* Compares two points by their character IDs and anchors. First, the character
* IDs are compared. If they are equal, the anchors are compared. The anchor
* "before" is considered less than the anchor "after".
*
* @param other The other point to compare to.
* @returns Returns 0 if the two points are equal, -1 if this point is less
* than the other point, and 1 if this point is greater than the other
* point.
*/
cmp(other: Point<T>): -1 | 0 | 1;
/**
* Compares two points by their spatial (view) location in the string. Takes
* into account not only the character position in the view, but also handles
* deleted characters, attachment anchors, and absolute points.
*
* @param other The other point to compare to.
* @returns Returns 0 if the two points are equal, negative if this point is
* less than the other point, and positive if this point is greater
* than the other point.
*/
cmpSpatial(other: Point<T>): number;
private _chunk;
/**
* @returns Returns the chunk that contains the character referenced by the
* point, or `undefined` if the chunk is not found.
*/
chunk(): Chunk<T> | undefined;
/**
* @returns Returns position of the character referenced by the point.
*/
pos(): number;
/**
* @returns Returns the view position of the point, as if it is a caret in
* the text pointing between characters (0 is before the first
* character, 1 is after the first character, etc.).
*/
viewPos(): number;
/**
* @returns Returns `true` if the point is at the very start of the string, i.e.
* there are no visible characters before it.
*/
isStart(): boolean;
/**
* Goes to the next visible character in the string. The `move` parameter
* specifies how many characters to move the cursor by. If the cursor reaches
* the end of the string, it will return `undefined`.
*
* @param skip How many characters to move by.
* @returns Next visible ID in string.
*/
nextId(skip?: number): ITimestampStruct | undefined;
/**
* @returns ID of the character that is `move` characters before the
* character referenced by the point, or `undefined` if there is no
* such character.
*/
prevId(skip?: number): ITimestampStruct | undefined;
/**
* Returns one character to the left of the point, or `undefined` if there
* is no such character. Skips any deleted characters. Handles absolute points.
*
* @returns A character slice to the left of the point.
*/
leftChar(): ChunkSlice<T> | undefined;
/**
* Returns one character to the right of the point, or `undefined` if there
* is no such character. Skips any deleted characters. Handles absolute points.
*
* @returns A character slice to the right of the point.
*/
rightChar(): ChunkSlice<T> | undefined;
char(): ChunkSlice<T> | undefined;
/**
* Checks if the point is an absolute point. An absolute point is a point that
* references the string itself, rather than a character in the string. It can
* be either the very start or the very end of the string.
*
* @returns Returns `true` if the point is an absolute point.
*/
isAbs(): boolean;
/**
* @returns Returns `true` if the point is an absolute point and is anchored
* before the first character in the string.
*/
isAbsStart(): boolean;
/**
* @returns Returns `true` if the point is an absolute point and is anchored
* after the last character in the string.
*/
isAbsEnd(): boolean;
/**
* @returns Returns `true` if the point is exactly the relative start, i.e.
* it is attached to the first visible character in the string and
* anchored "before".
*/
isRelStart(): boolean;
/**
* @returns Returns `true` if the point is exactly the relative end, i.e. it
* is attached to the last visible character in the string and
* anchored "after".
*/
isRelEnd(): boolean;
/**
* Sets the point to the absolute start of the string.
*/
refAbsStart(): void;
/**
* Sets the point to the absolute end of the string.
*/
refAbsEnd(): void;
/**
* Sets the point to the relative start of the string.
*/
refStart(): this;
/**
* Sets the point to the relative end of the string.
*/
refEnd(): this;
/**
* Modifies the location of the point, such that the view location remains
* the same, but ensures that it is anchored before a character. Skips any
* deleted characters (chunks), attaching the point to the next visible
* character.
*/
refBefore(): void;
/**
* Modifies the location of the point, such that the view location remains
* the same, but ensures that it is anchored after a character. Skips any
* deleted characters (chunks), attaching the point to the next visible
* character.
*/
refAfter(): void;
/**
* Modifies the location of the point, such that the spatial location remains
* the same and tries to preserve anchor location, but ensures that the point
* references a visible (not deleted) character.
*/
refVisible(): void;
/**
* Moves point past given number of visible characters. Accepts positive
* and negative distances.
*
* @param length How many characters to move by. Positive number moves the
* point to the right, negative number moves the point to the left.
* @returns Returns `true` if the absolute end of the string is reached.
*/
step(length: number): boolean;
/**
* Moves the to the next point, which does not necessarily result in a visible
* character skip.
*
* @param length How many points to move by.
* @returns Returns `true` if the absolute end of the string is reached.
*/
halfstep(length: number): boolean;
key(): number;
refresh(): number;
toStringName(): string;
toString(tab?: string, lite?: boolean): string;
}