feat: restructure library and improve maintainability, modularize and reorganize editor package structure, extract graph events and extensions

feat: remove `AnnotationTheme` and related utilities, simplify theming by consolidating into `NodeTheme`
feat: remove `ShortcutsViewerDialog` and related utilities in favor of simplified, customizable implementation in examples

Author: pavanpodila

packages/demo/lib/examples/advanced/shortcuts.dart

@@ -91,12 +91,13 @@ class _ShortcutsExampleState extends State<ShortcutsExample> {
   }
 
   void _showShortcutsDialog() {
+    final shortcuts = _controller.shortcuts.keyMap;
+    final actions = _controller.shortcuts.actions;
+
     showDialog(
       context: context,
-      builder: (context) => ShortcutsViewerDialog(
-        shortcuts: _controller.shortcuts.shortcuts,
-        actions: _controller.shortcuts.actions,
-      ),
+      builder: (context) =>
+          _SimpleShortcutsDialog(shortcuts: shortcuts, actions: actions),
     );
   }
 
@@ -389,3 +390,177 @@ class _CustomExportAction extends NodeFlowAction<Map<String, dynamic>> {
     return true;
   }
 }
+
+/// A simple shortcuts dialog built by the demo.
+///
+/// This demonstrates how external code can build its own shortcuts UI
+/// using the data from controller.shortcuts.keyMap and controller.shortcuts.actions.
+class _SimpleShortcutsDialog extends StatelessWidget {
+  const _SimpleShortcutsDialog({
+    required this.shortcuts,
+    required this.actions,
+  });
+
+  final Map<LogicalKeySet, String> shortcuts;
+  final Map<String, NodeFlowAction> actions;
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = Theme.of(context);
+
+    // Group shortcuts by category
+    final categorized = <String, List<MapEntry<LogicalKeySet, String>>>{};
+    for (final entry in shortcuts.entries) {
+      final action = actions[entry.value];
+      final category = action?.category ?? 'General';
+      categorized.putIfAbsent(category, () => []).add(entry);
+    }
+
+    return Dialog(
+      shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(12)),
+      child: Container(
+        width: 500,
+        constraints: BoxConstraints(
+          maxHeight: MediaQuery.of(context).size.height * 0.7,
+        ),
+        padding: const EdgeInsets.all(24),
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            Row(
+              mainAxisAlignment: MainAxisAlignment.spaceBetween,
+              children: [
+                Text(
+                  'Keyboard Shortcuts',
+                  style: theme.textTheme.headlineSmall?.copyWith(
+                    fontWeight: FontWeight.bold,
+                  ),
+                ),
+                IconButton(
+                  icon: const Icon(Icons.close),
+                  onPressed: () => Navigator.of(context).pop(),
+                ),
+              ],
+            ),
+            const SizedBox(height: 16),
+            Flexible(
+              child: ListView(
+                shrinkWrap: true,
+                children: [
+                  for (final category in categorized.keys) ...[
+                    Container(
+                      padding: const EdgeInsets.symmetric(
+                        horizontal: 8,
+                        vertical: 4,
+                      ),
+                      decoration: BoxDecoration(
+                        color: theme.colorScheme.primaryContainer.withValues(
+                          alpha: 0.3,
+                        ),
+                        borderRadius: BorderRadius.circular(4),
+                      ),
+                      child: Text(
+                        category.toUpperCase(),
+                        style: theme.textTheme.labelSmall?.copyWith(
+                          fontWeight: FontWeight.bold,
+                          color: theme.colorScheme.primary,
+                        ),
+                      ),
+                    ),
+                    const SizedBox(height: 8),
+                    for (final entry in categorized[category]!)
+                      Padding(
+                        padding: const EdgeInsets.only(bottom: 8, left: 8),
+                        child: Row(
+                          children: [
+                            SizedBox(
+                              width: 150,
+                              child: Text(
+                                _formatKeySet(entry.key),
+                                style: theme.textTheme.bodySmall?.copyWith(
+                                  fontFamily: 'monospace',
+                                  fontWeight: FontWeight.w500,
+                                ),
+                              ),
+                            ),
+                            Expanded(
+                              child: Text(
+                                actions[entry.value]?.label ?? entry.value,
+                                style: theme.textTheme.bodySmall,
+                              ),
+                            ),
+                          ],
+                        ),
+                      ),
+                    const SizedBox(height: 12),
+                  ],
+                ],
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  String _formatKeySet(LogicalKeySet keySet) {
+    final keys = keySet.keys.toList();
+    // Sort modifiers first
+    keys.sort((a, b) {
+      final aIsModifier = _isModifier(a);
+      final bIsModifier = _isModifier(b);
+      if (aIsModifier && !bIsModifier) return -1;
+      if (!aIsModifier && bIsModifier) return 1;
+      return 0;
+    });
+    return keys.map(_keyLabel).join(' + ');
+  }
+
+  bool _isModifier(LogicalKeyboardKey key) {
+    return key == LogicalKeyboardKey.meta ||
+        key == LogicalKeyboardKey.metaLeft ||
+        key == LogicalKeyboardKey.metaRight ||
+        key == LogicalKeyboardKey.control ||
+        key == LogicalKeyboardKey.controlLeft ||
+        key == LogicalKeyboardKey.controlRight ||
+        key == LogicalKeyboardKey.shift ||
+        key == LogicalKeyboardKey.shiftLeft ||
+        key == LogicalKeyboardKey.shiftRight ||
+        key == LogicalKeyboardKey.alt ||
+        key == LogicalKeyboardKey.altLeft ||
+        key == LogicalKeyboardKey.altRight;
+  }
+
+  String _keyLabel(LogicalKeyboardKey key) {
+    if (key == LogicalKeyboardKey.meta ||
+        key == LogicalKeyboardKey.metaLeft ||
+        key == LogicalKeyboardKey.metaRight) {
+      return '⌘';
+    }
+    if (key == LogicalKeyboardKey.control ||
+        key == LogicalKeyboardKey.controlLeft ||
+        key == LogicalKeyboardKey.controlRight) {
+      return 'Ctrl';
+    }
+    if (key == LogicalKeyboardKey.shift ||
+        key == LogicalKeyboardKey.shiftLeft ||
+        key == LogicalKeyboardKey.shiftRight) {
+      return '⇧';
+    }
+    if (key == LogicalKeyboardKey.alt ||
+        key == LogicalKeyboardKey.altLeft ||
+        key == LogicalKeyboardKey.altRight) {
+      return '⌥';
+    }
+    if (key == LogicalKeyboardKey.arrowUp) return '↑';
+    if (key == LogicalKeyboardKey.arrowDown) return '↓';
+    if (key == LogicalKeyboardKey.arrowLeft) return '←';
+    if (key == LogicalKeyboardKey.arrowRight) return '→';
+    if (key == LogicalKeyboardKey.escape) return 'Esc';
+    if (key == LogicalKeyboardKey.delete) return 'Del';
+    if (key == LogicalKeyboardKey.backspace) return '⌫';
+    if (key.keyLabel.length == 1) return key.keyLabel.toUpperCase();
+    return key.keyLabel;
+  }
+}

packages/demo/lib/examples/advanced/workbench.dart

@@ -394,13 +394,6 @@ class _WorkbenchExampleState extends State<WorkbenchExample> {
         ),
       ]),
       _buildGridSection('UI Tools', [
-        GridButton(
-          label: 'Shortcuts',
-          icon: Icons.keyboard,
-          onPressed: () {
-            _controller.showShortcutsDialog(context);
-          },
-        ),
         GridButton(
           label: 'Toggle Minimap',
           icon: Icons.map,

packages/vyuh_node_flow/CHANGELOG.md

@@ -1,92 +1,131 @@
 ## 0.16.0
 
- - Added the GraphPosition to the connection end callback
+- Added the GraphPosition to the connection end callback
 
- - **FIX**: replace `setEvents` with `internalUpdateEvents` across tests for consistency.
+- **FIX**: replace `setEvents` with `updateEvents` across tests for consistency.
 
 ## 0.15.1
 
- - **REFACTOR**: replace static `fromJsonMap` methods with unified factory constructors and improve `CommentNode` color observability.
- - **REFACTOR**: remove unused imports and redundant test node creation in controller_init_test.
- - **FEAT**: add EditorInitApi for unified initialization, improve spatial index diagnostics, and update render layer prioritization.
+- **REFACTOR**: replace static `fromJsonMap` methods with unified factory
+  constructors and improve `CommentNode` color observability.
+- **REFACTOR**: remove unused imports and redundant test node creation in
+  controller_init_test.
+- **FEAT**: add EditorInitApi for unified initialization, improve spatial index
+  diagnostics, and update render layer prioritization.
 
 ## 0.15.0
 
- - **FEAT**: refactor test factory and add unit tests for constructor initialization.
+- **FEAT**: refactor test factory and add unit tests for constructor
+  initialization.
 
 ## 0.14.1
 
- - **FEAT**: simplify drag operations across nodes, connections and resizers.
- - **FEAT**: refactor context menu callbacks to use `ScreenPosition`, enhance port interaction APIs, and simplify node constructor parameters.
+- **FEAT**: simplify drag operations across nodes, connections and resizers.
+- **FEAT**: refactor context menu callbacks to use `ScreenPosition`, enhance
+  port interaction APIs, and simplify node constructor parameters.
 
 ## 0.14.0
 
- - **FEAT**: unify Nodes and Annotations.
+- **FEAT**: unify Nodes and Annotations.
 
 ## 0.13.3
 
- - **FEAT**: remove debug logs, simplify null checks in viewport animation, and add lifecycle unit tests for animation handlers.
+- **FEAT**: remove debug logs, simplify null checks in viewport animation, and
+  add lifecycle unit tests for animation handlers.
 
 ## 0.13.2
 
- - **FEAT**: streamline port retrieval across nodes and improve viewport animation handling with token-based race condition prevention.
+- **FEAT**: streamline port retrieval across nodes and improve viewport
+  animation handling with token-based race condition prevention.
 
 ## 0.13.1
 
- - **FEAT**: initial set of tests for API, nodes, ports, graph, annotations, connections, rendering and performance.
+- **FEAT**: initial set of tests for API, nodes, ports, graph, annotations,
+  connections, rendering and performance.
 
 ## 0.13.0
 
- - **FEAT**: enhance AutoPan and Viewport Animations, add debug mode with overlays for better visualization, and integrate configurable AutoPan presets. `debugMode` is now moved into `NodeFlowConfig`.
+- **FEAT**: enhance AutoPan and Viewport Animations, add debug mode with
+  overlays for better visualization, and integrate configurable AutoPan presets.
+  `debugMode` is now moved into `NodeFlowConfig`.
 
 ## 0.12.0
 
- - **FEAT**: introducing Auto-Pan behavior which allows the elements (nodes, annotations, connections) to move freely and go past the edges, while keeping the viewport panning in place. It also does some interesting calculations for avoiding drift, so that the element stays relative to the mouse pointer. This is all implemented on the `ElementScope` with an `AutoPanMixin`.
+- **FEAT**: introducing Auto-Pan behavior which allows the elements (nodes,
+  annotations, connections) to move freely and go past the edges, while keeping
+  the viewport panning in place. It also does some interesting calculations for
+  avoiding drift, so that the element stays relative to the mouse pointer. This
+  is all implemented on the `ElementScope` with an `AutoPanMixin`.
 
 ## 0.11.0
 
- - **FEAT**: add ViewportAnimationMixin for smooth viewport animations, integrate animation methods into NodeFlowController and NodeFlowEditor, and provide API for animating to nodes, positions, bounds, and zoom levels.
+- **FEAT**: add ViewportAnimationMixin for smooth viewport animations, integrate
+  animation methods into NodeFlowController and NodeFlowEditor, and provide API
+  for animating to nodes, positions, bounds, and zoom levels.
 
 ## 0.10.9
 
- - **FEAT**: replace custom gesture implementation with ElementScope for streamlined gesture handling, lifecycle management, and drag state cleanup; enhance interaction robustness and trackpad compatibility.
+- **FEAT**: replace custom gesture implementation with ElementScope for
+  streamlined gesture handling, lifecycle management, and drag state cleanup;
+  enhance interaction robustness and trackpad compatibility.
 
 ## 0.10.8
 
- - **FIX**: reset connection hit flag on pointer up to prevent interaction conflicts in subsequent actions, refine hit testing hierarchy and annotation handling for consistent z-order interaction, enhance drag/selection behaviors for annotations and nodes.
- - **FEAT**: centralize pan state management in NodeFlowEditor for consistent interaction handling during drag, resize, and connection operations, add escape key handling to cancel annotation edits and enhance focus behaviors, add annotation editing cancellation, keyboard shortcuts, and selection clearing enhancements.
- - **FEAT**: centralize pan state management in NodeFlowEditor for consistent interaction handling during drag, resize, and connection operations.
- - **FEAT**: add escape key handling to cancel annotation edits and enhance focus behaviors.
- - **FEAT**: add annotation editing cancellation, keyboard shortcuts, and selection clearing enhancements.
+- **FIX**: reset connection hit flag on pointer up to prevent interaction
+  conflicts in subsequent actions, refine hit testing hierarchy and annotation
+  handling for consistent z-order interaction, enhance drag/selection behaviors
+  for annotations and nodes.
+- **FEAT**: centralize pan state management in NodeFlowEditor for consistent
+  interaction handling during drag, resize, and connection operations, add
+  escape key handling to cancel annotation edits and enhance focus behaviors,
+  add annotation editing cancellation, keyboard shortcuts, and selection
+  clearing enhancements.
+- **FEAT**: centralize pan state management in NodeFlowEditor for consistent
+  interaction handling during drag, resize, and connection operations.
+- **FEAT**: add escape key handling to cancel annotation edits and enhance focus
+  behaviors.
+- **FEAT**: add annotation editing cancellation, keyboard shortcuts, and
+  selection clearing enhancements.
 
 ## 0.10.7
 
- - **FEAT**: centralize pan state management in NodeFlowEditor for consistent interaction handling during drag, resize, and connection operations.
- - **FEAT**: add escape key handling to cancel annotation edits and enhance focus behaviors.
- - **FEAT**: add annotation editing cancellation, keyboard shortcuts, and selection clearing enhancements.
+- **FEAT**: centralize pan state management in NodeFlowEditor for consistent
+  interaction handling during drag, resize, and connection operations.
+- **FEAT**: add escape key handling to cancel annotation edits and enhance focus
+  behaviors.
+- **FEAT**: add annotation editing cancellation, keyboard shortcuts, and
+  selection clearing enhancements.
 
 ## 0.10.6
 
- - **FEAT**: implement inline editing for annotation titles, add keyboard shortcut for editing, and improve canvas focus handling.
- - **FEAT**: add editing state support for annotations and implement auto-grow for sticky notes.
+- **FEAT**: implement inline editing for annotation titles, add keyboard
+  shortcut for editing, and improve canvas focus handling.
+- **FEAT**: add editing state support for annotations and implement auto-grow
+  for sticky notes.
 
 ## 0.10.5
 
- - **REFACTOR**: remove short-distance temporary line drawing logic for consistent connection styling.
- - **FEAT**: replace `ConnectionControlPointsLayer` with custom gesture recognition, improve touch and trackpad interaction handling across nodes, ports, and annotations.
+- **REFACTOR**: remove short-distance temporary line drawing logic for
+  consistent connection styling.
+- **FEAT**: replace `ConnectionControlPointsLayer` with custom gesture
+  recognition, improve touch and trackpad interaction handling across nodes,
+  ports, and annotations.
 
 ## 0.10.4
 
- - **FEAT**: add transformation listener for authoritative viewport syncing and improve interaction accuracy.
+- **FEAT**: add transformation listener for authoritative viewport syncing and
+  improve interaction accuracy.
 
 ## 0.10.3
 
- - **FEAT**: add selection mode tracking with cursor feedback and shift key interaction.
+- **FEAT**: add selection mode tracking with cursor feedback and shift key
+  interaction.
 
 ## 0.10.2
 
- - **FIX**: hit testing outside the bounds of resizer and group-annotation.
- - **FEAT**: introduce `coordinates.dart` to enforce type safety in coordinate transformations and refactor usage across the package.
+- **FIX**: hit testing outside the bounds of resizer and group-annotation.
+- **FEAT**: introduce `coordinates.dart` to enforce type safety in coordinate
+  transformations and refactor usage across the package.
 
 ## 0.10.1