Custom Text Index Offset

The annotated-text library supports custom text indexing offsets to align with different scholarly and editorial workflows. By default, text uses zero-based indexing (starting at 0), but you can configure it to start at 1 or any other value.

The Problem

Zero-based indexing is standard in programming, but many academic and editorial contexts reference text positions starting from 1. For example:

• FileMaker uses 1-based indexing (documentation)
• Scholarly editions often reference character or word positions starting from 1
• Editorial workflows may use 1-based positions for manuscript annotations
• Other markup standards often use 1-based counting

This mismatch requires constant mental translation and can lead to errors when creating or validating annotations.

Solution: Text Offset Configuration

Configure a custom offset for text character indexing using the textOffset option:

createAnnotatedText(id, {
  text: {
    textOffset: 1  // Start indexing at 1 instead of 0
  },
})
  .setText(text)
  .setAnnotations(annotations);

How It Works

When you set a textOffset:

• Display layer: Text positions are shown with the offset applied (e.g., first character is position 1)
• Internal layer: Zero-based indexing is maintained internally for processing
• Annotations: Use the offset-adjusted positions when defining start/end values

Basic Usage

1-based indexing (most common for scholarly work):

const text = "Hello world";

const annotations = [
  {
    start: 1,    // First character 'H'
    end: 5,      // Last character 'o'
  },
  {
    start: 7,    // First character 'w'
    end: 11,     // Last character 'd'
  }
];

createAnnotatedText(id, {
  text: { textOffset: 1 },
})
  .setText(text)
  .setAnnotations(annotations);

Default behavior (0-based indexing):

// Without textOffset, or with textOffset: 0
const annotations = [
  {
    start: 0,    // First character 'H'
    end: 4,      // Last character 'o'
  }
];

createAnnotatedText(id)
  .setText(text)
  .setAnnotations(annotations);

Use Cases

FileMaker Integration

Align with FileMaker's Position function:

// Match FileMaker's 1-based Position() function
createAnnotatedText("filemaker-text", {
  text: { textOffset: 1 },
});

Custom Offsets

Support arbitrary starting positions:

// Start at position 100 (e.g., continuing from a previous section)
createAnnotatedText("section-2", {
  text: { textOffset: 100 },
});

Important Considerations

1. Consistency: Use the same offset throughout your application or clearly document when offsets change
2. Data Import/Export: When importing annotations from external sources, ensure their indexing matches your configured offset
3. API Responses: If your backend uses 0-based indexing, convert positions when setting annotations
4. Documentation: Clearly communicate the indexing convention to users and collaborators

Default Behavior

When textOffset is not specified or set to 0:

• Text indexing starts at 0
• Standard zero-based indexing is used throughout
• This is the default behavior and matches most programming conventions

Configuration Options

interface TextConfig {
  textOffset?: number;  // Default: 0
}

createAnnotatedText(id, {
  text: {
    textOffset: 1,  // or any integer value
  },
});

Example

In this example, we demonstrate three different text offsets: 0, 1, and 10. For each offset, the same annotation array is applied, to demonstrate how the starting index affects the annotation positions.

Plain text

Offset of 0

Offset of 1

Offset of 10

Wordsnapper

Offset of 0

Offset of 1

Offset of 10

TextLineAdapter

Offset of 0

Offset of 1

Offset of 10