Zeba Academy Annotations

A production‑ready reusable Flutter annotation engine built by Zeba Academy for modern reading applications.

zeba_academy_annotations provides a flexible system to add highlights, underlines, notes, and exportable annotations for:

  • 📚 eBook applications
  • 📄 PDF readers
  • 🎓 Educational platforms
  • 🕌 Religious reading apps
  • 🧠 Learning & research tools

✨ Features

  • ✅ Text Highlight
  • ✅ Underline annotations
  • ✅ Custom color markers
  • ✅ Add notes to highlights
  • ✅ Annotation history (Undo support)
  • ✅ JSON export
  • ✅ Cloud‑sync ready data models
  • ✅ Lightweight & extensible architecture
  • ✅ Flutter‑native rendering

📦 Installation

Add dependency in pubspec.yaml:

dependencies:
  zeba_academy_annotations: ^1.0.0

Then run:

flutter pub get

🚀 Quick Start

1️⃣ Import Package

import 'package:zeba_academy_annotations/zeba_academy_annotations.dart';

2️⃣ Create Controller

final controller = AnnotationController();

3️⃣ Add Annotation

controller.addAnnotation(
  text: "Hello World Example",
  start: 0,
  end: 5,
  type: AnnotationType.highlight,
  color: Colors.yellow,
);

4️⃣ Display Annotated Text

HighlightText(
  text: "Hello World Example",
  controller: controller,
)

🧠 Annotation Types

enum AnnotationType {
  highlight,
  underline,
  marker,
}
Type Description
highlight Background colored text
underline Underlined text
marker Custom colored marking

📝 Adding Notes

controller.addAnnotation(
  text: "Sample",
  start: 0,
  end: 6,
  type: AnnotationType.highlight,
  color: Colors.yellow,
  note: "Important concept",
);

↩️ Undo Support

controller.undo();

The engine uses a history stack to restore previous annotation states.

📤 Export Annotations (JSON)

final json = AnnotationExporter.export(
  controller.annotations,
);

Example Output:

[
  {
    "id": "uuid",
    "text": "Hello",
    "start": 0,
    "end": 5,
    "type": "highlight",
    "color": 4294967040,
    "note": "Important",
    "createdAt": "2026-01-01T10:00:00.000"
  }
]

☁️ Cloud Sync Ready

Annotation models are designed for direct storage in:

  • Firebase Firestore
  • Supabase
  • REST APIs
  • Local databases

Use:

annotation.toJson();

and

Annotation.fromJson(json);

🏗 Architecture Overview

lib/
 ├── controller/
 ├── models/
 ├── widgets/
 ├── services/
 └── history/

Core Components

Component Responsibility
AnnotationController State & logic engine
Annotation Model Cloud-ready data
HighlightText Rendering annotations
AnnotationExporter JSON export
AnnotationHistory Undo system

🧪 Testing

Run tests using:

flutter test

The package includes unit tests for:

  • Annotation creation
  • Removal
  • Undo functionality
  • Export validation

⚡ Performance

  • Lightweight rendering
  • Immutable annotation models
  • Efficient span rebuilding
  • Optimized ChangeNotifier updates

🔮 Roadmap

Planned upgrades:

  • Text selection gestures
  • Annotation toolbar UI
  • Multi‑page document support
  • Persistent storage adapters
  • Realtime cloud sync helpers
  • PDF coordinate mapping

🤝 Contributing

Contributions are welcome from the community.

  1. Fork the repository
  2. Create a feature branch
  3. Commit changes
  4. Open a Pull Request

📄 License

GPL License

🏫 About Zeba Academy

Zeba Academy builds production‑grade Flutter learning tools, UI systems, and reusable developer packages focused on education and reading experiences.

⭐ Support

If this package helps you, consider giving it a ⭐ on GitHub and sharing it with the Flutter community.

Libraries

zeba_academy_annotations