@net7/annotator

A framework-agnostic TypeScript library for anchoring and highlighting text in web documents with intelligent fallback strategies.

✨ Features

• 🎯 Multiple anchoring strategies with automatic fallback
• 📝 Text highlighting with customizable styles
• 🌐 Framework-agnostic - works with any JavaScript framework
• 🔧 TypeScript support with full type definitions
• 📱 PDF document support for complex layouts
• ⚡ Event-driven architecture for reactive applications
• 🎨 Context-aware filtering for multi-document apps

🚀 Quick Start

Installation

npm install @net7/annotator
# or
yarn add @net7/annotator

Basic Usage

import { Annotator } from '@net7/annotator';

// Create annotator instance
const annotator = new Annotator();

// Set document context
annotator.setContext({ documentId: 'doc-123' });

// Create annotation from user selection
const selection = window.getSelection();
if (selection && selection.rangeCount > 0) {
  const result = annotator.createAnnotation({
    root: document.body,
    range: selection.getRangeAt(0),
    context: { documentId: 'doc-123' },
    color: '#FFFF00',
    metadata: { comment: 'Important note' },
  });

  console.log('Annotation created:', result);
}

📖 API Reference

Annotator Class

Constructor

new Annotator(options?: { allowWhitespace?: boolean })

Key Methods

| Method | Description | | -------------------------- | -------------------------------------- | | setContext(context) | Set document context for filtering | | createAnnotation(params) | Create annotation from DOM range | | load(annotations, root) | Load multiple annotations | | remove(annotationId) | Remove annotation by ID | | getEvents() | Get event emitter for highlight events |

Event Handling

// Listen to highlight events
annotator.getEvents().on('highlight', (event) => {
  console.log('Highlight event:', event.type, event.payload);
});

🏗️ Architecture

The library uses a smart anchoring system with automatic fallback:

1. RangeSelector (Most precise) - DOM node references
2. TextPositionSelector (Reliable) - Character offsets
3. TextQuoteSelector (Robust) - Text content matching

When one strategy fails, it automatically tries the next one, ensuring maximum reliability across different document states.

📊 Advanced Usage

Loading Multiple Annotations

// Load existing annotations
const annotations = await fetchAnnotations();
annotator.load(annotations, document.body);

// Context-aware filtering
annotator.setContext({
  documentId: 'doc-123',
  pageNumber: 5,
  userId: 'user-456',
});

Custom Event Handling

const annotator = new Annotator({ allowWhitespace: true });

annotator.getEvents().on('highlight', (event) => {
  if (event.type === 'click') {
    showAnnotationDetails(event.payload);
  }
});

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass (npm test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

🧪 Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build library
npm run build

# Lint code
npm run lint

📚 Examples

Check out the docs/ directory for:

• Basic usage examples
• Advanced demo with full UI
• TypeScript integration examples

📄 License

This project is licensed under the BSD-2-Clause License - see the LICENSE file for details.

Third-Party Attributions

This library incorporates code from:

• Hypothesis Client (BSD-2-Clause)
• dom-anchor-text-quote (MIT)
• dom-anchor-text-position (MIT)

See NOTICE for complete attribution details.