Class: WordSnapper

About 2 min

Class: WordSnapper

Defined in: libs/core/src/lib/adapter/text/snapper/word-snapper/WordSnapper.ts:23

WordSnapper ensures text annotations align to word boundaries.

When users create annotations (highlights, comments, etc.) in text, they might select partial words or whitespace. WordSnapper "snaps" these selections to the nearest complete word boundaries for consistency.

Example

const snapper = new WordSnapper();
snapper.setText("Hello world, how are you?");

// User selects "llo wor" (partial words)
const result = snapper.fixOffset('drag', { start: 2, end: 9 });
// result: { start: 0, end: 11, modified: true, valid: true }
// Snaps to "Hello world"

Implements

Snapper

Constructors

Constructor

new WordSnapper(tokenizer?): WordSnapper

Defined in: libs/core/src/lib/adapter/text/snapper/word-snapper/WordSnapper.ts:45

Parameters

tokenizer?

Tokenizer

Returns

WordSnapper

Properties

mapStartCharIndexToToken

protected mapStartCharIndexToToken: object = {}

Defined in: libs/core/src/lib/adapter/text/snapper/word-snapper/WordSnapper.ts:30

Maps character indices to the start position of their containing token. All characters within a token map to the token's start position.

Index Signature

[index: number]: number

Example

For "Hello world": { 0→0, 1→0, 2→0, 3→0, 4→0, 5→0, 6→6, 7→6... }

mapStopCharIndexToToken

protected mapStopCharIndexToToken: object = {}

Defined in: libs/core/src/lib/adapter/text/snapper/word-snapper/WordSnapper.ts:38

Maps character indices to the end position of their containing token. All characters within a token map to the token's end position.

Index Signature

[index: number]: number

Example

For "Hello world": { 0→5, 1→5, 2→5, 3→5, 4→5, 5→5, 6→11, 7→11... }

textLength

protected textLength: number = 0

Defined in: libs/core/src/lib/adapter/text/snapper/word-snapper/WordSnapper.ts:40

tokenizerFn

protected tokenizerFn: Tokenizer = tokenize

Defined in: libs/core/src/lib/adapter/text/snapper/word-snapper/WordSnapper.ts:42

Methods

fixEnd()

protected fixEnd(annotation): SnapperResult

Defined in: libs/core/src/lib/adapter/text/snapper/word-snapper/WordSnapper.ts:128

Snaps the end position to the nearest token boundary. Falls back to start position's token if end position has no mapping.

Parameters

annotation

Pick<TextAnnotation, "end" | "start">

Annotation with start and end positions

Returns

SnapperResult

Result with adjusted end position

fixOffset()

fixOffset(action, annotation): SnapperResult

Defined in: libs/core/src/lib/adapter/text/snapper/word-snapper/WordSnapper.ts:163

Adjusts annotation boundaries to align with complete word boundaries.

Parameters

action

SnapperAction

The user action that triggered the snap (e.g., 'drag', 'click')

annotation

The annotation to adjust

color?

{ background?: string; backgroundActive?: string; border?: string; borderActive?: string; color?: string; gutterColor?: string; tagBackground?: string; tagColor?: string; } = ...

color.background?

string = ...

color.backgroundActive?

string = ...

color.border?

string = ...

color.borderActive?

string = ...

color.color?

string = ...

color.gutterColor?

string = ...

color.tagBackground?

string = ...

color.tagColor?

string = ...

end

number = ...

id?

string | number = annotationIdSchema

isGutter

boolean = ...

label?

string = ...

start

number = ...

target?

"text" | "gutter" = ...

textSelection?

string = ...

weight?

number = ...

Returns

SnapperResult

The adjusted annotation with word-aligned boundaries

Remarks

The algorithm:

Snaps start position to the beginning of its containing word
Snaps end position to the end of its containing word
If snapping produces an invalid range (start >= end), incrementally extends the end position until a valid range is found
Returns the final boundaries with validity and modification flags

This ensures annotations always encompass complete words, improving consistency and readability of highlights and selections.