Feat vim mode

documentation/vim-mode.md

@@ -0,0 +1,77 @@
+# Vim Mode
+
+Vim mode is not meant to emulate all the vim functionality but instead provide partial emulation.
+The editor was not built to have vim mode from the beginning. However this mode allows some functionality to be used.
+
+## Why not leverage on the existing shortcuts system?
+
+Leveraging on the shortcuts system was the inital solution however that showed its limitations.
+In some cases if the vim shortcut did not recognize the key input as a vim command, it will treat it as regular input this would result in printing letters onto the editor.
+Which is not meant to be the case with Vim. 'Normal Mode' does not allow any text input besides the known shortcuts/commands.
+The proposed idea was to instead capture keyboard events directly without modifying the core editor itself.
+
+
+### So how does it work?
+
+Inside the `keyboard_service_widget.dart` is where the keyboard capture is happening. Below is the snippet that is used specifically for vim mode.
+
+```dart
+    if (editorState.vimMode) {
+      if (editorState.mode == VimModes.normalMode) {
+        final VimCommandShortcutEvent vimCommandShortcutEvent =
+            VimCommandShortcutEvent();
+        final vimResult = vimCommandShortcutEvent.handleKey(event, editorState);
+        if (vimResult == KeyEventResult.handled) {
+          return KeyEventResult.handled;
+        }
+      }
+    }
+```
+
+We only execute the block inside the if statement if the Vim Mode was enabled from the beginning. Vim Mode can be activated from the main AppFlowy constructor.
+
+```dart
+AppFlowyEditor(
+          vimMode: true,
+          editorState: editorState,
+          // Other AppFlowy Commands
+          ...
+        )
+```
+
+## Technical Details
+
+The `VimCommandShortcutEvent` value being used in `keyboard_service_widget.dart` does extend the CommandShortcut class but its not entirely used.
+Instead its more of a wrapper for the actual vim handler. This was done so the vim keys can be registered in AppFlowy and not break anything else in the process.
+
+
+```dart
+class VimCommandShortcutEvent extends CommandShortcutEvent {
+  final VimFSM vimFSM = VimFSM();
+  VimCommandShortcutEvent()
+      : super(
+          key: 'Vim FSM Handler',
+          command: '',
+          handler: _dummyHandler,
+          getDescription: () => 'Handles multi-key vim commands using an FSM',
+        );
+  KeyEventResult handleKey(KeyEvent event, EditorState editorState) {
+    return vimFSM.processKey(event, editorState);
+  }
+
+  static KeyEventResult _dummyHandler(EditorState editorState) {
+    return KeyEventResult.ignored;
+  }
+}
+```
+
+### Vim Shortcuts handling
+
+There are known keys for Vim to at least get around the document, such as `[h, j, k, l]` any other keys would be either extensions of the mentioned keys or new ones entirely.
+Currently there are hard-coded keys which the Vim keyboard handler will check with for every key press. If the pressed keys are within the list of known keys they will trigger an action.
+Any other key that is not known will just be ignored.
+
+
+In Vim there is the concept of doing key combinations or awaiting key presses. For example `4j` means jump 4 lines down from the current position.
+Normally `4` and `j` are registered as separate keys, however with VimMode we hold the keys in a buffer before we release them.
+So if `4j` matches then an action is triggered however if we try `10m` that will not trigger anything because `m` is not a known key, so the buffer will be cleared.

example/lib/pages/desktop_editor.dart

@@ -87,6 +87,7 @@ class _DesktopEditorState extends State<DesktopEditor> {
       child: Directionality(
         textDirection: widget.textDirection,
         child: AppFlowyEditor(
+          vimMode: true,
           editorState: editorState,
           editorScrollController: editorScrollController,
           blockComponentBuilders: blockComponentBuilders,

lib/src/editor/block_component/base_component/selection/block_selection_area.dart

@@ -92,17 +92,18 @@ class _BlockSelectionAreaState extends State<BlockSelectionArea> {
       builder: ((context, value, child) {
         final sizedBox = child ?? const SizedBox.shrink();
         final selection = value?.normalized;
-
+        final editorState = context.watch<EditorState>();
         if (selection == null) {
           return sizedBox;
         }
 
         final path = widget.node.path;
+
         if (!path.inSelection(selection)) {
           return sizedBox;
         }
 
-        final editorState = context.read<EditorState>();
+        //final editorState = context.read<EditorState>();
         if (editorState.selectionType == SelectionType.block) {
           if (!widget.supportTypes.contains(BlockSelectionType.block) ||
               !path.inSelection(selection, isSameDepth: true) ||
@@ -125,8 +126,10 @@ class _BlockSelectionAreaState extends State<BlockSelectionArea> {
             ),
           );
         }
+
         // show the cursor when the selection is collapsed
-        else if (selection.isCollapsed) {
+        else if (selection.isCollapsed &&
+            (editorState.mode == VimModes.insertMode || !editorState.vimMode)) {
           if (!widget.supportTypes.contains(BlockSelectionType.cursor) ||
               prevCursorRect == null) {
             return sizedBox;
@@ -146,6 +149,25 @@ class _BlockSelectionAreaState extends State<BlockSelectionArea> {
           // force to show the cursor
           cursorKey.currentState?.unwrapOrNull<CursorState>()?.show();
           return cursor;
+        } else if (selection.isCollapsed &&
+            editorState.mode == VimModes.normalMode &&
+            editorState.vimMode) {
+          if (!widget.supportTypes.contains(BlockSelectionType.selection) ||
+              prevSelectionRects == null) {
+            return sizedBox;
+          }
+
+          final rect = widget.delegate.getCursorRectInPosition(selection.start);
+          //NOTE: Hard coded cursor style
+          final cursor = Cursor(
+            key: cursorKey,
+            rect: rect ?? prevCursorRect!,
+            shouldBlink: false,
+            cursorStyle: CursorStyle.block,
+            color: Colors.blue,
+          );
+          cursorKey.currentState?.unwrapOrNull<CursorState>()?.show();
+          return cursor;
         } else {
           // show the selection area when the selection is not collapsed
           if (!widget.supportTypes.contains(BlockSelectionType.selection) ||

lib/src/editor/block_component/paragraph_block_component/paragraph_block_component.dart

@@ -161,6 +161,13 @@ class _ParagraphBlockComponentWidgetState
         mainAxisSize: MainAxisSize.min,
         textDirection: textDirection,
         children: [
+          /*
+          NOTE:
+        One can combine AppFlowyRichText
+        With a row then stick in the line number.
+        Only problem is the container doesnt maintain
+        its size
+         */
           AppFlowyRichText(
             key: forwardKey,
             delegate: this,

lib/src/editor/block_component/standard_block_components.dart

@@ -3,6 +3,7 @@ import 'package:appflowy_editor/src/editor/block_component/heading_block_compone
 import 'package:appflowy_editor/src/editor/util/platform_extension.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
+// import 'package:appflowy_editor/src/editor/editor_component/service/shortcuts/command/vim.dart';
 
 const standardBlockComponentConfiguration = BlockComponentConfiguration();
 
@@ -153,5 +154,6 @@ final List<CommandShortcutEvent> standardCommandShortcutEvents = [
   // copy paste and cut
   copyCommand,
   ...pasteCommands,
+  // ...vimKeyModes,
   cutCommand,
 ];

lib/src/editor/editor_component/service/editor.dart

@@ -29,6 +29,7 @@ class AppFlowyEditor extends StatefulWidget {
     List<List<ContextMenuItem>>? contextMenuItems,
     this.contentInsertionConfiguration,
     this.editable = true,
+    this.vimMode = false,
     this.autoFocus = false,
     this.focusedSelection,
     this.shrinkWrap = false,
@@ -151,6 +152,12 @@ class AppFlowyEditor extends StatefulWidget {
   /// If you want to disable the scroll service, you can set [disableScrollService] to true.
   final bool editable;
 
+  /// Set the value to false to disable Vim Mode.
+  ///
+  /// if false, the editor will work normally like any other
+  ///   without the vim motion features and keybindings.
+  final bool vimMode;
+
   /// Set the value to true to focus the editor on the start of the document.
   final bool autoFocus;
 
@@ -253,6 +260,8 @@ class _AppFlowyEditorState extends State<AppFlowyEditor> {
 
     _updateValues();
     editorState.renderer = _renderer;
+    editorState.editable = widget.editable;
+    editorState.vimMode = widget.vimMode;
 
     // auto focus
     WidgetsBinding.instance.addPostFrameCallback((timeStamp) {
@@ -274,6 +283,9 @@ class _AppFlowyEditorState extends State<AppFlowyEditor> {
   void didUpdateWidget(covariant AppFlowyEditor oldWidget) {
     super.didUpdateWidget(oldWidget);
 
+    editorState.editorStyle = widget.editorStyle;
+    editorState.editable = widget.editable;
+    editorState.vimMode = widget.vimMode;
     _updateValues();
 
     if (editorState.service != oldWidget.editorState.service) {

lib/src/editor/editor_component/service/keyboard_service_widget.dart

@@ -1,5 +1,6 @@
 import 'package:appflowy_editor/appflowy_editor.dart';
 import 'package:appflowy_editor/src/editor/editor_component/service/ime/delta_input_on_floating_cursor_update.dart';
+import 'package:appflowy_editor/src/editor/editor_component/service/shortcuts/vim_shortcut_event.dart';
 import 'package:appflowy_editor/src/editor/util/platform_extension.dart';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
@@ -168,6 +169,17 @@ class KeyboardServiceWidgetState extends State<KeyboardServiceWidget>
       return KeyEventResult.ignored;
     }
 
+    if (editorState.vimMode) {
+      if (editorState.mode == VimModes.normalMode) {
+        final VimCommandShortcutEvent vimCommandShortcutEvent =
+            VimCommandShortcutEvent();
+        final vimResult = vimCommandShortcutEvent.handleKey(event, editorState);
+        if (vimResult == KeyEventResult.handled) {
+          return KeyEventResult.handled;
+        }
+      }
+    }
+
     if ((event is! KeyDownEvent && event is! KeyRepeatEvent) ||
         !enableIMEShortcuts) {
       if (textInputService.composingTextRange != TextRange.empty) {
@@ -235,6 +247,7 @@ class KeyboardServiceWidgetState extends State<KeyboardServiceWidget>
     AppFlowyEditorLog.editor.debug(
       'keyboard service - attach text input service: $textEditingValue',
     );
+
     if (textEditingValue != null) {
       textInputService.attach(
         textEditingValue,
@@ -258,6 +271,10 @@ class KeyboardServiceWidgetState extends State<KeyboardServiceWidget>
   // This function is used to get the current text editing value of the editor
   // based on the given selection.
   TextEditingValue? _getCurrentTextEditingValue(Selection selection) {
+    // This is to avoid the attachment service from capturing some input
+    if (editorState.vimMode && editorState.mode != VimModes.insertMode) {
+      return null;
+    }
     // Get all the editable nodes in the selection.
     final editableNodes = editorState
         .getNodesInSelection(selection)

lib/src/editor/editor_component/service/selection/desktop_selection_service.dart

@@ -224,12 +224,25 @@ class _DesktopSelectionServiceWidgetState
     if (HardwareKeyboard.instance.isShiftPressed && _panStartPosition != null) {
       selection = Selection(start: _panStartPosition!, end: position);
     } else {
+
+if (editorState.mode == VimModes.normalMode && editorState.vimMode){
+        //NOTE: It throws a transaction error when I mimic the else statement for selection
+        //NOTE: So settled for a single selection
+        selection = Selection.collapsed(position);
+        editorState.prevSelection = selection;
+
+        // Reset old start offset
+        _panStartOffset = offset;
+} else {
       selection = selectable.cursorStyle == CursorStyle.verticalLine
           ? Selection.collapsed(position)
           : Selection(start: selectable.start(), end: selectable.end());
 
       // Reset old start offset
-      _panStartPosition = position;
+      _panStartOffset = offset;
+
+}
+
     }
 
     updateSelection(selection);

lib/src/editor/editor_component/service/shortcut_events.dart

@@ -2,3 +2,4 @@ export 'shortcuts/character/character_shortcut_events.dart';
 export 'shortcuts/character_shortcut_event.dart';
 export 'shortcuts/command/command_shortcut_events.dart';
 export 'shortcuts/command_shortcut_event.dart';
+export 'shortcuts/vim_shortcut_event.dart';

lib/src/editor/editor_component/service/shortcuts/command/escape_command.dart

@@ -7,6 +7,7 @@ import 'package:flutter/material.dart';
 ///   - desktop
 ///   - web
 ///
+//TODO: Allow custom escape key
 final CommandShortcutEvent exitEditingCommand = CommandShortcutEvent(
   key: 'exit the editing mode',
   getDescription: () => AppFlowyEditorL10n.current.cmdExitEditing,
@@ -15,6 +16,20 @@ final CommandShortcutEvent exitEditingCommand = CommandShortcutEvent(
 );
 
 CommandShortcutEventHandler _exitEditingCommandHandler = (editorState) {
+  if (editorState.mode == VimModes.normalMode) {
+    return KeyEventResult.handled;
+  }
+  if (editorState.vimMode == true &&
+      editorState.editable == true &&
+      editorState.mode == VimModes.insertMode) {
+    editorState.prevSelection = editorState.selection;
+    editorState.selection = null;
+    editorState.mode = VimModes.normalMode;
+    editorState.editable = false;
+    editorState.selection = editorState.prevSelection;
+    editorState.service.keyboardService?.closeKeyboard();
+    return KeyEventResult.handled;
+  }
   editorState.selection = null;
   editorState.service.keyboardService?.closeKeyboard();
   return KeyEventResult.handled;

lib/src/editor/editor_component/service/shortcuts/command/markdown_commands.dart

@@ -79,12 +79,16 @@ KeyEventResult _toggleAttribute(
   EditorState editorState,
   String key,
 ) {
-  final selection = editorState.selection;
-  if (selection == null) {
-    return KeyEventResult.ignored;
-  }
+  //NOTE: This is a fix for vim  mode. Some keys are conflicting
+  if (editorState.mode == VimModes.insertMode || editorState.vimMode == false) {
+    final selection = editorState.selection;
+    if (selection == null) {
+      return KeyEventResult.ignored;
+    }
 
-  editorState.toggleAttribute(key);
+    editorState.toggleAttribute(key);
 
-  return KeyEventResult.handled;
+    return KeyEventResult.handled;
+  }
+  return KeyEventResult.ignored;
 }