feat: remove annotations-related concepts; introduce "Special Node Types" for enhanced clarity and consistency in documentation and API structuring

pavanpodila · pavanpodila · commit d1c1fb841c08 · 2025-12-29T08:21:04.000+05:30
diff --git a/website/.vitepress/config.ts b/website/.vitepress/config.ts
@@ -121,7 +121,7 @@ export default defineConfig({
             { text: 'NodeWidget', link: '/docs/components/node-widget' },
             { text: 'PortWidget', link: '/docs/components/port-widget' },
             { text: 'ConnectionsLayer', link: '/docs/components/connections-layer' },
-            { text: 'Annotations', link: '/docs/components/annotations' },
+            { text: 'Special Node Types', link: '/docs/components/special-node-types' },
             { text: 'Minimap', link: '/docs/components/minimap' },
           ],
         },
@@ -144,7 +144,8 @@ export default defineConfig({
         {
           text: 'Advanced',
           items: [
-            { text: 'Annotations', link: '/docs/advanced/annotations' },
+            { text: 'Special Node Types', link: '/docs/advanced/special-node-types' },
+            { text: 'Level of Detail (LOD)', link: '/docs/advanced/lod' },
             { text: 'Events', link: '/docs/advanced/events' },
             { text: 'Serialization', link: '/docs/advanced/serialization' },
             { text: 'Keyboard Shortcuts', link: '/docs/advanced/keyboard-shortcuts' },
diff --git a/website/docs/advanced/events.md b/website/docs/advanced/events.md
@@ -6,10 +6,10 @@ description: Handle user interactions with nodes, connections, and the canvas
 # Event System
 
 ::: details 🖼️ Event System Overview
-Diagram showing event flow architecture: NodeFlowEvents container with five event groups (NodeEvents, PortEvents, ConnectionEvents, ViewportEvents, AnnotationEvents) plus top-level callbacks (onSelectionChange, onInit, onError). Arrows showing event propagation from user interactions.
+Diagram showing event flow architecture: NodeFlowEvents container with four event groups (NodeEvents, PortEvents, ConnectionEvents, ViewportEvents) plus top-level callbacks (onSelectionChange, onInit, onError). Arrows showing event propagation from user interactions.
 :::
 
-The event system provides comprehensive callbacks for all user interactions. Events are organized into logical groups for nodes, ports, connections, viewport, and annotations.
+The event system provides comprehensive callbacks for all user interactions. Events are organized into logical groups for nodes (including GroupNode and CommentNode), ports, connections, and viewport.
 
 ## Event Structure
 
@@ -19,11 +19,10 @@ Events are passed via the `events` parameter on `NodeFlowEditor`:
 NodeFlowEditor<MyData>(
   controller: controller,
   events: NodeFlowEvents(
-    node: NodeEvents(...),
+    node: NodeEvents(...),      // Includes GroupNode & CommentNode
     port: PortEvents(...),
     connection: ConnectionEvents(...),
     viewport: ViewportEvents(...),
-    annotation: AnnotationEvents(...),
     onSelectionChange: (state) => ...,
     onInit: () => ...,
     onError: (error) => ...,
@@ -267,23 +266,6 @@ Canvas positions are in **graph coordinates**, not screen coordinates. They acco
 
 :::
 
-## Annotation Events
-
-Handle interactions with sticky notes, groups, and markers.
-
-```dart
-AnnotationEvents(
-  onCreated: (annotation) => print('Created: ${annotation.id}'),
-  onDeleted: (annotation) => print('Deleted: ${annotation.id}'),
-  onSelected: (annotation) => _showAnnotationTools(annotation),
-  onTap: (annotation) => _selectAnnotation(annotation),
-  onDoubleTap: (annotation) => _editAnnotation(annotation),
-  onContextMenu: (annotation, position) => _showMenu(annotation, position),
-  onMouseEnter: (annotation) => _highlight(annotation),
-  onMouseLeave: (annotation) => _unhighlight(annotation),
-)
-```
-
 ## Selection State
 
 Track the complete selection state across all element types:
@@ -293,7 +275,6 @@ NodeFlowEvents<MyData>(
   onSelectionChange: (state) {
     print('Selected nodes: ${state.nodes.length}');
     print('Selected connections: ${state.connections.length}');
-    print('Selected annotations: ${state.annotations.length}');
 
     // Update toolbar based on selection
     if (state.hasSelection) {
@@ -309,14 +290,21 @@ The `SelectionState` object provides:
 
 ```dart
 class SelectionState<T> {
+  /// Currently selected nodes (includes GroupNode and CommentNode)
   final List<Node<T>> nodes;
+
+  /// Currently selected connections
   final List<Connection> connections;
-  final List<Annotation> annotations;
 
-  bool get hasSelection; // True if anything is selected
+  /// True if anything is selected
+  bool get hasSelection;
 }
 ```
 
+::: info
+GroupNode and CommentNode are included in the `nodes` list since they extend Node.
+:::
+
 ## Top-Level Events
 
 ```dart
diff --git a/website/docs/advanced/special-node-types.md b/website/docs/advanced/special-node-types.md
diff --git a/website/docs/api-reference/events.md b/website/docs/api-reference/events.md
@@ -17,7 +17,6 @@ NodeFlowEvents<T>({
   PortEvents<T>? port,
   ConnectionEvents<T>? connection,
   ViewportEvents? viewport,
-  AnnotationEvents? annotation,
   ValueChanged<SelectionState<T>>? onSelectionChange,
   VoidCallback? onInit,
   ValueChanged<FlowError>? onError,
@@ -26,11 +25,10 @@ NodeFlowEvents<T>({
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `node` | `NodeEvents<T>?` | Node interaction events |
+| `node` | `NodeEvents<T>?` | Node interaction events (includes GroupNode & CommentNode) |
 | `port` | `PortEvents<T>?` | Port interaction events |
 | `connection` | `ConnectionEvents<T>?` | Connection lifecycle events |
 | `viewport` | `ViewportEvents?` | Canvas pan/zoom events |
-| `annotation` | `AnnotationEvents?` | Annotation events |
 | `onSelectionChange` | `ValueChanged<SelectionState<T>>?` | Selection state changes |
 | `onInit` | `VoidCallback?` | Editor initialization |
 | `onError` | `ValueChanged<FlowError>?` | Error handling |
@@ -295,48 +293,27 @@ ViewportEvents(
 )
 ```
 
-## AnnotationEvents
-
-Events for annotation interactions (sticky notes, groups).
-
-```dart
-AnnotationEvents({
-  ValueChanged<Annotation>? onCreated,
-  ValueChanged<Annotation>? onDeleted,
-  ValueChanged<Annotation?>? onSelected,
-  ValueChanged<Annotation>? onTap,
-  ValueChanged<Annotation>? onDoubleTap,
-  void Function(Annotation, Offset)? onContextMenu,
-  ValueChanged<Annotation>? onMouseEnter,
-  ValueChanged<Annotation>? onMouseLeave,
-})
-```
-
-| Event | Trigger | Signature |
-|-------|---------|-----------|
-| `onCreated` | Annotation created | `ValueChanged<Annotation>` |
-| `onDeleted` | Annotation deleted | `ValueChanged<Annotation>` |
-| `onSelected` | Selection changes | `ValueChanged<Annotation?>` |
-| `onTap` | Single tap | `ValueChanged<Annotation>` |
-| `onDoubleTap` | Double tap | `ValueChanged<Annotation>` |
-| `onContextMenu` | Right-click | `(Annotation, Offset)` |
-| `onMouseEnter` | Mouse enters bounds | `ValueChanged<Annotation>` |
-| `onMouseLeave` | Mouse leaves bounds | `ValueChanged<Annotation>` |
-
 ## SelectionState
 
 Provided to `onSelectionChange` when selection changes.
 
 ```dart
 class SelectionState<T> {
+  /// Currently selected nodes (includes GroupNode and CommentNode)
   final List<Node<T>> nodes;
+
+  /// Currently selected connections
   final List<Connection> connections;
-  final List<Annotation> annotations;
 
+  /// Whether anything is selected
   bool get hasSelection;
 }
 ```
 
+::: info
+GroupNode and CommentNode are included in the `nodes` list since they extend Node.
+:::
+
 **Example:**
 ```dart
 onSelectionChange: (state) {
diff --git a/website/docs/api-reference/theme.md b/website/docs/api-reference/theme.md
@@ -19,12 +19,13 @@ NodeFlowTheme({
   Duration connectionAnimationDuration = const Duration(seconds: 2),
   required PortTheme portTheme,
   required LabelTheme labelTheme,
-  required AnnotationTheme annotationTheme,
   required GridTheme gridTheme,
   required SelectionTheme selectionTheme,
   required CursorTheme cursorTheme,
+  required MinimapTheme minimapTheme,
+  required ResizerTheme resizerTheme,
   Color backgroundColor = Colors.white,
-  bool debugMode = false,
+  DebugMode debugMode = DebugMode.none,
   DebugTheme debugTheme = DebugTheme.light,
 })
 ```
@@ -44,12 +45,13 @@ Most theme properties are **required**. Use `NodeFlowTheme.light` or `NodeFlowTh
 | `connectionAnimationDuration` | `Duration` | No | Animation cycle duration |
 | `portTheme` | `PortTheme` | Yes | Port appearance |
 | `labelTheme` | `LabelTheme` | Yes | Connection label styling |
-| `annotationTheme` | `AnnotationTheme` | Yes | Annotation appearance |
 | `gridTheme` | `GridTheme` | Yes | Grid background |
 | `selectionTheme` | `SelectionTheme` | Yes | Selection rectangle styling |
 | `cursorTheme` | `CursorTheme` | Yes | Mouse cursor styles |
+| `minimapTheme` | `MinimapTheme` | Yes | Minimap appearance |
+| `resizerTheme` | `ResizerTheme` | Yes | Resize handle styling |
 | `backgroundColor` | `Color` | No | Canvas background |
-| `debugMode` | `bool` | No | Enable debug overlays |
+| `debugMode` | `DebugMode` | No | Debug overlay mode |
 | `debugTheme` | `DebugTheme` | No | Debug visualization styling |
 
 ::: code-group
@@ -371,24 +373,6 @@ SelectionTheme.light
 SelectionTheme.dark
 ```
 
-## AnnotationTheme
-
-Style configuration for annotations (sticky notes, groups).
-
-```dart
-AnnotationTheme({
-  required Color selectionColor,
-  required double selectionBorderWidth,
-  // Additional properties for sticky notes, groups, markers
-})
-```
-
-**Preset themes:**
-```dart
-AnnotationTheme.light
-AnnotationTheme.dark
-```
-
 ## CursorTheme
 
 Mouse cursor styles for different interactions.
diff --git a/website/docs/components/special-node-types.md b/website/docs/components/special-node-types.md
@@ -77,7 +77,7 @@ For complete documentation including:
 - Complete examples
 - Serialization
 
-See **[Special Node Types (Advanced)](/docs/advanced/annotations)**.
+See **[Special Node Types (Advanced)](/docs/advanced/special-node-types)**.
 
 ## See Also
 
diff --git a/website/docs/core-concepts/architecture.md b/website/docs/core-concepts/architecture.md
@@ -28,10 +28,11 @@ The main widget that renders the interactive flow editor.
 The controller manages the graph state and provides APIs for manipulation:
 
 ```dart
-class NodeFlowController<T extends NodeData> {
+class NodeFlowController<T> {
   // Core graph data
-  final Graph<T> graph;
-  final Viewport viewport;
+  final Map<String, Node<T>> nodes;
+  final Map<String, Connection> connections;
+  final GraphViewport viewport;
 
   // APIs
   void addNode(Node<T> node);
@@ -41,12 +42,12 @@ class NodeFlowController<T extends NodeData> {
 
   // Selection
   Set<String> get selectedNodeIds;
-  void selectNode(String nodeId, {bool multiSelect = false});
+  void selectNode(String nodeId, {bool toggle = false});
 
   // Viewport management
   void panTo(Offset position);
   void zoomTo(double zoom);
-  void fitToScreen();
+  void fitToView();
 
   // And many more...
 }
@@ -67,12 +68,11 @@ management is handled by the NodeFlowController:
 
 ```dart
 class NodeGraph<T> {
+  /// All nodes including GroupNode and CommentNode
   final List<Node<T>> nodes;
   final List<Connection> connections;
-  final List<Annotation> annotations;
   final GraphViewport viewport;
   final Map<String, dynamic> metadata;
-
 }
 ```
 
@@ -118,24 +118,20 @@ class Port {
   final String id;
   final String name;
   final PortPosition position; // left, right, top, bottom
-  final PortType type; // source, target, both
+  final PortType type; // input or output
   final Offset offset;
   final bool multiConnections;
   final int? maxConnections;
   final PortShape shape;
   final double size;
   final String? tooltip;
   final bool isConnectable;
-
-  // Computed properties
-  bool get isSource;
-  bool get isTarget;
 }
 ```
 
 **Key Features:**
 
-- Configurable as source (output), target (input), or bidirectional
+- Configurable as input or output port type
 - Custom shapes via `PortShape` (default: capsule half)
 - Multi-connection support with optional max limit
 - Tooltips and connectable state
@@ -233,10 +229,10 @@ The architecture provides several extension points:
 
 ### Core Customization
 
-1. **Custom Node Data**: Extend `NodeData` for your domain
+1. **Custom Node Data**: Use any type for your node's `data` field
 2. **Node Builders**: Provide custom node widgets for building the content as
    well as the container
-3. **Annotations**: Add custom overlays and markers
+3. **Special Nodes**: Use `GroupNode` for visual grouping and `CommentNode` for annotations
 4. **Validators**: Add connection validation logic
 
 ### Theming
