Skip to content

v2.0.0

Choose a tag to compare

View all tags
@w8r w8r released this 02 Feb 13:36
· 149 commits to develop since this release
v2.0.0
2df13ac
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Highlights

🆕 Three New Annotation Types

Comments — A full-featured commenting system designed for collaborative graph analysis:

  • Expandable/collapsible display modes with automatic zoom-based transitions
  • Fixed screen-space sizing (always readable regardless of zoom level)
  • Built-in support for scrollable content
  • Auto-connected arrows that link comments to graph elements

Polygons — Freeform region annotations:

  • Interactive point-by-point drawing
  • Smooth polygon rendering with full rotation support
  • Arrow linking support from polygon edges

Boxes — Rectangular region annotations:

  • Drag-to-size creation with intuitive handles
  • Full rotation and resizing capabilities
  • Edge and corner manipulation

⚡ New State Management Architecture

The internal architecture has been completely rebuilt using Zustand + Zundo:

  • Built-in Undo/Redo — Full history management with undo(), redo(), canUndo(), canRedo() methods
  • 50-100x faster state equality checks with optimized comparison functions
  • Reactive subscriptions — Efficient state change detection with minimal re-renders

🎯 Simplified Drawing API

New "enable" methods provide a streamlined experience for interactive annotation creation:

// New recommended API (v2.0)
control.enableArrowDrawing(style?)
control.enableTextDrawing(style?)
control.enableBoxDrawing(style?)
control.enablePolygonDrawing(style?)
control.enableCommentDrawing(options?)

These methods handle all interaction setup automatically—just call and let users click to create.

New Features

Smart Snapping System

  • Edge snapping — Arrows intelligently snap to polygon and box edges
  • Node snapping — Snap annotations to graph nodes
  • Real-time feedback — Smooth visual snapping indicators during drawing

Enhanced Text Editing

  • Full textarea support with placeholder text
  • Auto-grow text boxes that expand with content
  • Proper cursor positioning in rotated annotations
  • Fixed-size and auto-size modes

Advanced Geometry

  • Full rotation support for all annotation types
  • Counter-rotation for UI elements (handles remain upright)
  • Proper coordinate transformation for rotated shapes
  • Screen-space positioning for comments

Expanded Event System

New events for comprehensive lifecycle management:

  • EVT_HISTORY — History state changes (canUndo/canRedo)
  • EVT_LINK — Arrow linked to target
  • EVT_COMPLETE_DRAWING / EVT_CANCEL_DRAWING — Drawing lifecycle
  • EVT_DRAG_START / EVT_DRAG_END — Drag operations

API Reference

History Management

control.undo(): boolean
control.redo(): boolean
control.canUndo(): boolean
control.canRedo(): boolean
control.clearHistory()

Selection Management

control.select(id | id[])
control.unselect(id? | id[])

Type Guards

isArrow(annotation)
isText(annotation)
isBox(annotation)
isPolygon(annotation)
isComment(annotation)
isCommentArrow(arrow)

Breaking Changes & Migration

Package Structure

The monorepo now provides two packages:

  • @linkurious/ogma-annotations — Core TypeScript package
  • @linkurious/ogma-annotations-react — React integration (requires core package as peer dependency)

Annotation Data Format

Annotations use strict GeoJSON-compatible format:

  • id is at the feature level (not in properties)
  • Mandatory type field in properties
  • Strict coordinate typing

React Package

  • Now requires @linkurious/ogma-annotations@2.0.0 as a peer dependency
  • React >=17 required (unchanged)

Drawing API

The original startArrow() and startText() methods still work, but we recommend migrating to the new enable*Drawing() methods for a simpler integration.

Dependencies

Added

  • zustand@5.0.7 — State management
  • zundo@2.3.0 — Undo/redo support
  • rbush@4.0.1 — Spatial indexing for hit detection
  • @borgar/textbox@1.8.0 — Text measurement and layout
  • eventemitter3@5.0.1 — Event system

Updated

  • Ogma peer dependency: >=4.5.6 || ^5.0.0

Bug Fixes

  • Fixed arrow detachment from rotated polygons
  • Fixed link snapping after polygon drag operations
  • Fixed comment editing when re-entering edit mode
  • Fixed rendering culling for viewport optimization
  • Fixed z-index management for overlapping annotations
  • Resolved edge cases in undo/redo for various annotation types
  • Removed broken canvas dependency that caused compatibility issues

Documentation

This release includes comprehensive new documentation:

  • Complete TypeScript API reference (auto-generated via TypeDoc)
  • React integration guides with hooks documentation
  • Interactive creation tutorials
  • Styling guides for all annotation types
  • Live demos for both vanilla TypeScript and React

Visit the documentation site for the full guides.

Compatibility

Dependency Version
Ogma >=4.5.6 or ^5.0.0
React (for React package) >=17
@linkurious/ogma-react >=5

Upgrading

# Core package
npm install @linkurious/ogma-annotations@2.0.0

# React integration
npm install @linkurious/ogma-annotations-react@2.0.0

What's Next

We're continuing to improve the annotation experience. Planned enhancements include:

  • Background color selector for text annotations
  • Font face dropdown for text and comment annotations
  • Full React implementation of the annotation panel

Full Changelog: v1.1.27...v2.0.0

Assets 2
Loading