textual-vim-textarea 1.1.0__py3-none-any.whl

textual_vim_textarea/__init__.py

@@ -0,0 +1,11 @@
+from .vim_textarea import VimTextArea, Mode
+
+__all__ = ["VimTextArea", "Mode"]
+
+# VimTextAreaPlus is intentionally NOT imported here. It requires
+# textual-textarea (the 'textarea-plus' extra), and importing it
+# unconditionally would force that dependency on every install of this
+# package, even for people only using plain VimTextArea. Import it
+# explicitly if you need it:
+#
+#     from textual_vim_textarea.textarea_plus import VimTextAreaPlus

textual_vim_textarea/_modal.py

@@ -0,0 +1,605 @@
+"""
+_modal.py
+
+All of the actual vim-editing logic, factored out of any specific base
+class. This is the piece VimTextArea (built on plain Textual TextArea)
+and VimTextAreaPlus (built on textual-textarea's TextAreaPlus) share --
+motions, operators, counts, registers, visual mode, the command line
+state machine.
+
+VimModalMixin deliberately does NOT hook on_key or _on_key, and does NOT
+define any Message subclasses. Both of those have to live on the
+*concrete* class (VimTextArea / VimTextAreaPlus), not here, for two
+reasons:
+
+  1. Key routing genuinely differs between the two bases. Plain TextArea
+     only has `_on_key`, so entering INSERT mode there means manually
+     falling through to `super()._on_key(event)`. TextAreaPlus builds
+     its own features (autocomplete, bracket-closing, smart indent)
+     through the public `on_key` handler instead, and Textual calls
+     every class in the MRO that defines its own `_on_key`/`on_key` in
+     turn (see textual_vim_textarea.textarea_plus's module docstring for
+     the full mechanics) -- so VimTextAreaPlus has to hook `on_key` and
+     do nothing at all in INSERT mode, letting the event cascade through
+     TextAreaPlus's own handler naturally. Folding both strategies into
+     one method here would mean neither works correctly.
+
+  2. Textual derives a message's handler method name from the class it's
+     *nested inside* (`VimTextArea.StatusChanged` -> handler name
+     `on_vim_text_area_status_changed`), not from where the logic that
+     posts it happens to live. If `StatusChanged` were defined on this
+     mixin instead, every consumer's handler name would become
+     `on_vim_modal_mixin_status_changed` regardless of which concrete
+     class they're actually using -- and worse, it would've silently
+     changed already-shipped handler names for existing VimTextArea
+     users. So each concrete class defines its own copy of the Message
+     classes (a few lines of boilerplate); this mixin only ever
+     *references* them dynamically via `self.ModeChanged(...)` etc.,
+     which Python resolves against the instance's real class.
+
+Any class mixing this in is expected to also provide (transitively, via
+its other base) TextArea's own API: `.document`, `.selection`,
+`.cursor_location`, `.get_line()`, `.get_text_range()`, `.delete()`,
+`.insert()`, `.move_cursor()`, `.undo()`, `.redo()`,
+`.get_cursor_line_start_location()`. It's also expected to define, on
+itself, nested `ModeChanged`, `StatusChanged`, `CommandEntered`, and
+`QuitRequested` Message classes, plus a `_do_save()` (async) and
+`_do_quit()` method -- see VimTextArea / VimTextAreaPlus for the concrete
+shape.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+from typing import Optional, Tuple
+
+from textual import events
+from textual.reactive import reactive
+from textual.widgets.text_area import Selection
+
+Location = Tuple[int, int]
+
+# A "word" for w/b/e purposes: a run of keyword characters, OR a run of
+# punctuation characters. Whitespace is always a separator. This mirrors
+# vim's default (non-WORD) motion closely enough for everyday use.
+_TOKEN_RE = re.compile(r"\w+|[^\w\s]+")
+
+
+class Mode(str, Enum):
+    NORMAL = "NORMAL"
+    INSERT = "INSERT"
+    VISUAL = "VISUAL"
+    VISUAL_LINE = "V-LINE"
+    COMMAND = "COMMAND"
+
+
+class VimModalMixin:
+    """Shared vim state machine: motions, operators, counts, registers,
+    visual mode, and the command line. See the module docstring for what
+    a concrete class mixing this in still has to provide itself.
+    """
+
+    mode: reactive[Mode] = reactive(Mode.NORMAL)
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._count: str = ""
+        self._pending_op: Optional[str] = None
+        self._pending_g: bool = False
+        self._register: str = ""
+        self._register_linewise: bool = False
+        self._command_buffer: str = ""
+        self._pending_op_count: int = 1
+
+    # ------------------------------------------------------------------
+    # status line helper -- host apps can poll this to render e.g. a
+    # bottom bar that looks like vim's own mode/command line.
+    # ------------------------------------------------------------------
+    @property
+    def status_text(self) -> str:
+        if self.mode is Mode.COMMAND:
+            return f":{self._command_buffer}"
+        labels = {
+            Mode.NORMAL: "NORMAL",
+            Mode.INSERT: "-- INSERT --",
+            Mode.VISUAL: "-- VISUAL --",
+            Mode.VISUAL_LINE: "-- VISUAL LINE --",
+        }
+        pending = f"{self._count}{self._pending_op or ''}"
+        text = labels[self.mode]
+        return f"{text} {pending}".rstrip()
+
+    def watch_mode(self, mode: Mode) -> None:
+        self.post_message(self.ModeChanged(mode))
+
+    # ------------------------------------------------------------------
+    # mode transitions
+    # ------------------------------------------------------------------
+    def _enter_insert(self) -> None:
+        self.mode = Mode.INSERT
+
+    def _enter_normal_mode(self, shift_cursor_left: bool = False) -> None:
+        self._pending_op = None
+        self._pending_g = False
+        self._count = ""
+        if shift_cursor_left:
+            row, col = self.cursor_location
+            if col > 0:
+                self.move_cursor((row, col - 1))
+        else:
+            self.move_cursor(self.selection.end)
+        self.mode = Mode.NORMAL
+
+    def _enter_visual(self, linewise: bool) -> None:
+        self.mode = Mode.VISUAL_LINE if linewise else Mode.VISUAL
+        if linewise:
+            row, _ = self.cursor_location
+            self.selection = Selection((row, 0), (row, len(str(self.get_line(row)))))
+
+    # ------------------------------------------------------------------
+    # command line (":w", ":q", ":wq", ":n", or anything else). Concrete
+    # classes plug in what "save" and "quit" actually mean by overriding
+    # _do_save()/_do_quit() -- see their docstrings.
+    # ------------------------------------------------------------------
+    async def _handle_command_key(self, event: events.Key) -> None:
+        if event.key == "escape":
+            self._command_buffer = ""
+            self.mode = Mode.NORMAL
+            return
+        if event.key == "enter":
+            command = self._command_buffer
+            self._command_buffer = ""
+            self.mode = Mode.NORMAL
+            await self._dispatch_command(command)
+            return
+        if event.key == "backspace":
+            self._command_buffer = self._command_buffer[:-1]
+            return
+        if event.character and event.is_printable:
+            self._command_buffer += event.character
+
+    async def _dispatch_command(self, command: str) -> None:
+        stripped = command.strip()
+        if stripped in ("w", "write"):
+            await self._do_save()
+        elif stripped in ("q", "q!", "quit"):
+            self._do_quit()
+        elif stripped in ("wq", "x"):
+            await self._do_save()
+            self._do_quit()
+        elif stripped.isdigit():
+            # ":n" -- jump to line n (1-indexed, like vim)
+            target_row = max(0, min(int(stripped) - 1, self.document.line_count - 1))
+            self.move_cursor((target_row, 0))
+        elif stripped:
+            self.post_message(self.CommandEntered(stripped))
+
+    async def _do_save(self) -> None:
+        """Default ':w' behavior: post SaveRequested for a host app to
+        handle. Override this if your base class has a real, directly
+        callable save action to trigger instead (see VimTextAreaPlus)."""
+        self.post_message(self.SaveRequested())
+
+    def _do_quit(self) -> None:
+        """Default ':q' behavior: post QuitRequested. Deliberately just a
+        message, not a direct app.exit() call -- what ':q' should mean
+        (close a buffer? close the whole app?) is a host-app decision."""
+        self.post_message(self.QuitRequested())
+
+    async def _trigger_ancestor_action(self, action_name: str) -> bool:
+        """Find the nearest ancestor with an `action_<name>` method and
+        call it directly. Returns True if one was found and called.
+
+        Deliberately NOT `self.run_action(action_name)` -- Textual
+        resolves an un-prefixed action name against the *calling* widget
+        by default, not an ancestor, so it would silently look for the
+        action on this widget itself and do nothing if the action
+        actually lives on a parent container (verified by reading
+        `App._parse_action` -- there's no ancestor fallback there).
+        """
+        import inspect
+
+        for node in self.ancestors:
+            method = getattr(node, f"action_{action_name}", None)
+            if callable(method):
+                result = method()
+                if inspect.isawaitable(result):
+                    await result
+                return True
+        return False
+
+    # ------------------------------------------------------------------
+    # NORMAL / VISUAL dispatch
+    # ------------------------------------------------------------------
+    def _handle_normal_key(self, event: events.Key) -> None:
+        key = event.key
+        char = event.character
+
+        # -- numeric count prefix (leading 0 is a motion, not a count) --
+        if char is not None and char.isdigit() and (char != "0" or self._count):
+            self._count += char
+            return
+
+        count = int(self._count) if self._count else 1
+        had_count = bool(self._count)
+        self._count = ""
+
+        if key == "escape":
+            if self.mode in (Mode.VISUAL, Mode.VISUAL_LINE):
+                self._enter_normal_mode()
+            else:
+                self._pending_op = None
+                self._pending_g = False
+            return
+
+        if char == ":":
+            self.mode = Mode.COMMAND
+            self._command_buffer = ""
+            self._pending_op = None
+            return
+
+        # -- "gg" two-key sequence (also combines with a pending
+        #    operator, e.g. "dgg") --
+        if self._pending_g:
+            self._pending_g = False
+            if char == "g":
+                target_row = (
+                    min(count - 1, self.document.line_count - 1) if had_count else 0
+                )
+                row, _ = self.cursor_location
+                if self._pending_op:
+                    op = self._pending_op
+                    self._pending_op = None
+                    self._apply_operator_range(op, (row, 0), (target_row, 0), linewise=True)
+                else:
+                    select = self.mode in (Mode.VISUAL, Mode.VISUAL_LINE)
+                    self.move_cursor((target_row, 0), select=select)
+                    if self.mode is Mode.VISUAL_LINE:
+                        self._sync_visual_line_selection()
+            return
+        if char == "g":
+            self._pending_g = True
+            return
+
+        # -- resolve an already-pending operator (d/c/y + motion) --
+        if self._pending_op:
+            op = self._pending_op
+            self._pending_op = None
+            # counts before the operator and before the motion multiply,
+            # e.g. "3dd" -> 3, "d3w" -> 3, "2d3w" -> 6
+            combined_count = self._pending_op_count * count
+            self._pending_op_count = 1
+            if char == op:  # dd / cc / yy
+                row, _ = self.cursor_location
+                end_row = min(row + combined_count - 1, self.document.line_count - 1)
+                self._apply_operator_range(op, (row, 0), (end_row, 0), linewise=True)
+                return
+            # vim quirk: "cw"/"cW" act like "ce" -- they stop at the end
+            # of the current word rather than swallowing trailing
+            # whitespace the way "dw" does.
+            motion_char = "e" if (op == "c" and char == "w") else char
+            motion = self._resolve_motion(key, motion_char, combined_count, had_count)
+            if motion is None:
+                return
+            target, linewise, inclusive = motion
+            self._apply_operator_range(
+                op, self.cursor_location, target, linewise=linewise, inclusive=inclusive
+            )
+            return
+
+        # -- visual mode: d/x/c/y act on the current selection --
+        if self.mode in (Mode.VISUAL, Mode.VISUAL_LINE) and char in ("d", "x", "c", "y"):
+            self._visual_operator(char)
+            return
+
+        # -- start a new operator --
+        if char in ("d", "c", "y") and self.mode is Mode.NORMAL:
+            self._pending_op = char
+            self._pending_op_count = count
+            return
+
+        # -- D / C / X: line-end / char shorthand operators --
+        if char == "D":
+            row, col = self.cursor_location
+            self._apply_operator_range("d", (row, col), self._end_of_line(row), inclusive=True)
+            return
+        if char == "C":
+            row, col = self.cursor_location
+            self._apply_operator_range("c", (row, col), self._end_of_line(row), inclusive=True)
+            return
+        if char == "X":
+            row, col = self.cursor_location
+            start_col = max(0, col - count)
+            if start_col < col:
+                self._apply_operator_range("d", (row, start_col), (row, col))
+            return
+        if char == "x":
+            row, col = self.cursor_location
+            line_len = len(str(self.get_line(row)))
+            end_col = min(col + count, line_len)
+            if end_col > col:
+                self._apply_operator_range("d", (row, col), (row, end_col))
+            return
+
+        # -- enter insert mode --
+        if char == "i":
+            self._enter_insert()
+            return
+        if char == "a":
+            row, col = self.cursor_location
+            line_len = len(str(self.get_line(row)))
+            self.move_cursor((row, min(line_len, col + 1)))
+            self._enter_insert()
+            return
+        if char == "I":
+            self.move_cursor(self.get_cursor_line_start_location(smart_home=True))
+            self._enter_insert()
+            return
+        if char == "A":
+            row, _ = self.cursor_location
+            self.move_cursor(self._end_of_line(row))
+            self._enter_insert()
+            return
+        if char == "o":
+            row, _ = self.cursor_location
+            end = self._end_of_line(row)
+            self.insert("\n", location=end)
+            self.move_cursor((row + 1, 0))
+            self._enter_insert()
+            return
+        if char == "O":
+            row, _ = self.cursor_location
+            self.insert("\n", location=(row, 0))
+            self.move_cursor((row, 0))
+            self._enter_insert()
+            return
+
+        # -- visual mode toggles --
+        if char == "v":
+            if self.mode is Mode.VISUAL:
+                self._enter_normal_mode()
+            else:
+                self._enter_visual(linewise=False)
+            return
+        if char == "V":
+            if self.mode is Mode.VISUAL_LINE:
+                self._enter_normal_mode()
+            else:
+                self._enter_visual(linewise=True)
+            return
+
+        # -- paste --
+        if char == "p":
+            self._paste(after=True)
+            return
+        if char == "P":
+            self._paste(after=False)
+            return
+
+        # -- undo / redo --
+        if char == "u":
+            for _ in range(count):
+                self.undo()
+            return
+        if key == "ctrl+r":
+            for _ in range(count):
+                self.redo()
+            return
+
+        # -- plain motions (also extend selection in visual modes) --
+        motion = self._resolve_motion(key, char, count, had_count)
+        if motion is not None:
+            target, _linewise, _inclusive = motion
+            select = self.mode in (Mode.VISUAL, Mode.VISUAL_LINE)
+            self.move_cursor(target, select=select)
+            if self.mode is Mode.VISUAL_LINE:
+                self._sync_visual_line_selection()
+
+    # ------------------------------------------------------------------
+    # motions -- return (target_location, linewise, inclusive) or None
+    # ------------------------------------------------------------------
+    def _end_of_line(self, row: int) -> Location:
+        return (row, len(str(self.get_line(row))))
+
+    def _resolve_motion(
+        self, key: str, char: Optional[str], count: int, had_count: bool
+    ) -> Optional[Tuple[Location, bool, bool]]:
+        row, col = self.cursor_location
+        line_count = self.document.line_count
+
+        if char == "h" or key == "left":
+            return (row, max(0, col - count)), False, False
+        if char == "l" or key == "right":
+            line_len = len(str(self.get_line(row)))
+            return (row, min(line_len, col + count)), False, False
+        if char == "j" or key == "down":
+            end_row = min(row + count, line_count - 1)
+            return (end_row, col), True, False
+        if char == "k" or key == "up":
+            end_row = max(row - count, 0)
+            return (end_row, col), True, False
+        if char == "0":
+            return (row, 0), False, False
+        if char == "^":
+            return self.get_cursor_line_start_location(smart_home=True), False, False
+        if char == "$" or key == "end":
+            end_row = min(row + count - 1, line_count - 1)
+            return self._end_of_line(end_row), False, True
+        if char == "w":
+            return self._word_forward_location(count), False, False
+        if char == "b":
+            return self._word_backward_location(count), False, False
+        if char == "e":
+            return self._word_end_location(count), False, True
+        if char == "G":
+            target_row = min(count - 1, line_count - 1) if had_count else line_count - 1
+            return (target_row, 0), True, False
+        return None
+
+    def _tokens(self, row: int):
+        text = str(self.get_line(row))
+        return [(m.start(), m.end()) for m in _TOKEN_RE.finditer(text)]
+
+    def _word_forward_location(self, count: int) -> Location:
+        row, col = self.cursor_location
+        for _ in range(count):
+            row, col = self._single_word_forward(row, col)
+        return row, col
+
+    def _single_word_forward(self, row: int, col: int) -> Location:
+        line_count = self.document.line_count
+        for start, _end in self._tokens(row):
+            if start > col:
+                return row, start
+        r = row
+        while r + 1 < line_count:
+            r += 1
+            toks = self._tokens(r)
+            if toks:
+                return r, toks[0][0]
+            return r, 0  # blank line is itself a word-stop
+        return self.document.end
+
+    def _word_backward_location(self, count: int) -> Location:
+        row, col = self.cursor_location
+        for _ in range(count):
+            row, col = self._single_word_backward(row, col)
+        return row, col
+
+    def _single_word_backward(self, row: int, col: int) -> Location:
+        r = row
+        while True:
+            if r == row:
+                candidates = [start for start, _end in self._tokens(r) if start < col]
+            else:
+                candidates = [start for start, _end in self._tokens(r)]
+            if candidates:
+                return r, candidates[-1]
+            if r == 0:
+                return 0, 0
+            r -= 1
+            toks = self._tokens(r)
+            if toks:
+                return r, toks[-1][0]
+            return r, 0
+
+    def _word_end_location(self, count: int) -> Location:
+        row, col = self.cursor_location
+        for _ in range(count):
+            row, col = self._single_word_end(row, col)
+        return row, col
+
+    def _single_word_end(self, row: int, col: int) -> Location:
+        line_count = self.document.line_count
+        r, c = row, col
+        while True:
+            for start, end in self._tokens(r):
+                if end - 1 > c:
+                    return r, end - 1
+            if r + 1 >= line_count:
+                last_len = len(str(self.get_line(r)))
+                return r, max(0, last_len - 1)
+            r += 1
+            c = -1
+
+    # ------------------------------------------------------------------
+    # visual-line selection upkeep
+    # ------------------------------------------------------------------
+    def _sync_visual_line_selection(self) -> None:
+        start, end = self.selection
+        row_a, row_b = start[0], end[0]
+        lo, hi = min(row_a, row_b), max(row_a, row_b)
+        if row_a <= row_b:
+            new_start = (lo, 0)
+            new_end = (hi, len(str(self.get_line(hi))))
+        else:
+            new_start = (hi, len(str(self.get_line(hi))))
+            new_end = (lo, 0)
+        self.selection = Selection(new_start, new_end)
+
+    # ------------------------------------------------------------------
+    # operators
+    # ------------------------------------------------------------------
+    def _apply_operator_range(
+        self,
+        op: str,
+        a: Location,
+        b: Location,
+        linewise: bool = False,
+        inclusive: bool = False,
+    ) -> None:
+        start, end = (a, b) if a <= b else (b, a)
+
+        if linewise:
+            start_row, end_row = start[0], end[0]
+            if op == "c":
+                content_start = (start_row, 0)
+                content_end = self._end_of_line(end_row)
+                text = self.get_text_range(content_start, content_end)
+                self.delete(content_start, content_end)
+                self._register, self._register_linewise = text, True
+                self.move_cursor((start_row, 0))
+                self._enter_insert()
+                return
+
+            full_text = self.get_text_range((start_row, 0), self._end_of_line(end_row))
+            self._register, self._register_linewise = full_text, True
+            if op == "d":
+                line_count = self.document.line_count
+                if end_row + 1 < line_count:
+                    self.delete((start_row, 0), (end_row + 1, 0))
+                    new_row = min(start_row, self.document.line_count - 1)
+                elif start_row > 0:
+                    prev_end = self._end_of_line(start_row - 1)
+                    self.delete(prev_end, self._end_of_line(end_row))
+                    new_row = start_row - 1
+                else:
+                    self.delete((start_row, 0), self._end_of_line(end_row))
+                    new_row = 0
+                self.move_cursor((new_row, 0))
+            self._enter_normal_mode()
+            return
+
+        # charwise
+        if inclusive:
+            end = (end[0], end[1] + 1)
+        text = self.get_text_range(start, end)
+        self._register, self._register_linewise = text, False
+        if op in ("d", "c"):
+            self.delete(start, end)
+            self.move_cursor(start)
+        if op == "c":
+            self._enter_insert()
+        else:
+            self._enter_normal_mode()
+
+    def _visual_operator(self, char: str) -> None:
+        op = "d" if char == "x" else char
+        start, end = self.selection
+        start, end = (start, end) if start <= end else (end, start)
+        if self.mode is Mode.VISUAL_LINE:
+            self._apply_operator_range(op, (start[0], 0), (end[0], 0), linewise=True)
+        else:
+            self._apply_operator_range(op, start, end, inclusive=True)
+
+    # ------------------------------------------------------------------
+    # paste
+    # ------------------------------------------------------------------
+    def _paste(self, after: bool) -> None:
+        if not self._register:
+            return
+        row, col = self.cursor_location
+        if self._register_linewise:
+            text = self._register
+            if not text.endswith("\n"):
+                text += "\n"
+            insert_row = row + 1 if after else row
+            self.insert(text, location=(insert_row, 0))
+            self.move_cursor((insert_row, 0))
+        else:
+            line_len = len(str(self.get_line(row)))
+            insert_col = min(col + 1, line_len) if after else col
+            self.insert(self._register, location=(row, insert_col))
+            new_col = insert_col + len(self._register)
+            self.move_cursor((row, max(insert_col, new_col - 1)))

textual_vim_textarea/textarea_plus.py

@@ -0,0 +1,154 @@
+"""
+textarea_plus.py
+
+Vim-modal editing for apps built on `textual-textarea`'s `TextEditor` /
+`TextAreaPlus` rather than plain
+Textual `TextArea`. Requires the `textarea-plus` extra:
+
+    pip install textual-vim-textarea[textarea-plus]
+
+All the actual vim logic is shared with `vim_textarea.VimTextArea` via
+`_modal.VimModalMixin`. This file only has what's specific to
+TextAreaPlus: how keys get intercepted (genuinely different from plain
+TextArea -- see below), the Message classes, and how ':w' triggers a
+real save.
+
+Why this isn't just VimTextArea reused
+---------------------------------------
+`TextAreaPlus(TextArea, inherit_bindings=False)` adds real editing
+features on top of base TextArea through the *public* `on_key` handler,
+not the *private* `_on_key` base TextArea itself uses for default
+character insertion: bracket/quote auto-closing, smart enter (auto-
+indent, jump inside brackets), tab/shift+tab indent handling, and an
+autocomplete dropdown.
+
+I verified Textual's actual dispatch order by reading
+`MessagePump._get_dispatch_methods` / `_on_message` directly
+(textual/message_pump.py), not by guessing from behavior:
+
+  - For a Key event, Textual walks the widget's class MRO from most-
+    derived to least-derived. For each class that defines its own
+    `_on_key` or `on_key` (checked via `cls.__dict__`, private preferred
+    over public *within that same class*), it calls that handler, then
+    moves on to the next class in the MRO -- unless prevented.
+  - `event.prevent_default()` sets `message._no_default_action = True`,
+    which makes that walk `break` -- so calling it stops every *later*
+    (more-base) class's handler from running at all.
+  - `event.stop()` is a separate mechanism -- it only stops the event
+    from *bubbling to the parent widget* afterwards (which is how
+    some TUI's ctrl+s / ctrl+f / ctrl+g bindings on the outer
+    TextEditor container end up firing even though the inner
+    TextAreaPlus has actual focus).
+
+TextAreaPlus.on_key handles special keys (enter, tab, brackets, escape)
+by calling prevent_default() itself, fully replacing default TextArea
+behavior for those keys. For plain printable characters it does NOT
+prevent_default -- it just triggers autocomplete side effects and lets
+the event keep falling through to base TextArea._on_key, which does the
+actual insert.
+
+So the correct way to layer vim modes on top is to also hook `on_key`
+(matching TextAreaPlus's own handler name, so we sit earlier in the
+MRO): in INSERT mode, do nothing at all for any key other than Escape --
+let the event fall through exactly as if this class didn't exist, so
+every TextAreaPlus feature keeps working untouched. In NORMAL / VISUAL /
+COMMAND mode, prevent_default() + stop() immediately, exactly like
+VimTextArea does, so TextAreaPlus never sees the key while not
+inserting. (VimTextArea's `super()._on_key()` approach would NOT work
+here -- it's a direct Python method call via `super()`, which completely
+bypasses Textual's own per-class MRO dispatch loop and would skip
+TextAreaPlus.on_key's side effects entirely.)
+
+A real maintenance risk worth knowing about: `TextAreaPlus` is NOT part
+of textual_textarea's public API (only `TextEditor` is exported from
+`textual_textarea/__init__.py`). Importing it means reaching into
+`textual_textarea.text_editor`, a private module path. If a future
+textual-textarea release restructures that file, this import breaks with
+no deprecation warning. Pin your textual-textarea version and re-check
+this import on every upgrade.
+"""
+
+from __future__ import annotations
+
+from textual import events
+from textual.message import Message
+
+from ._modal import Mode, VimModalMixin
+
+try:
+    from textual_textarea.text_editor import TextAreaPlus
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "VimTextAreaPlus requires the 'textarea-plus' extra: "
+        "pip install textual-vim-textarea[textarea-plus]"
+    ) from exc
+
+__all__ = ["VimTextAreaPlus", "Mode"]
+
+
+class VimTextAreaPlus(VimModalMixin, TextAreaPlus):
+    """TextAreaPlus with vim modes layered on top via `on_key`, so every
+    TextAreaPlus feature -- autocomplete, bracket/quote auto-closing,
+    smart enter/tab indent -- keeps working exactly as before while in
+    INSERT mode, and is fully bypassed while in NORMAL / VISUAL /
+    COMMAND mode.
+    """
+
+    class ModeChanged(Message):
+        def __init__(self, mode: Mode) -> None:
+            self.mode = mode
+            super().__init__()
+
+    class StatusChanged(Message):
+        def __init__(self, status: str) -> None:
+            self.status = status
+            super().__init__()
+
+    class QuitRequested(Message):
+        """Posted on ':q'. Deliberately NOT wired to anything by
+        default -- closing a buffer vs. quitting the whole app is a real
+        host-app product decision, not this widget's call to make."""
+
+    class CommandEntered(Message):
+        """Posted for any ':' command this widget doesn't itself handle."""
+
+        def __init__(self, command: str) -> None:
+            self.command = command
+            super().__init__()
+
+    # ------------------------------------------------------------------
+    # key routing -- see the module docstring for exactly why this is
+    # structured the way it is.
+    # ------------------------------------------------------------------
+    async def on_key(self, event: events.Key) -> None:
+        if self.mode is Mode.INSERT:
+            if event.key == "escape":
+                # side effect only -- do NOT prevent_default/stop, so
+                # TextAreaPlus's own escape handler (hide completion
+                # list, collapse selection) still runs right after this
+                self._enter_normal_mode(shift_cursor_left=True)
+            return
+
+        if self.mode is Mode.COMMAND:
+            event.stop()
+            event.prevent_default()
+            await self._handle_command_key(event)
+            self.post_message(self.StatusChanged(self.status_text))
+            return
+
+        # NORMAL / VISUAL / VISUAL_LINE: we own every key, TextAreaPlus
+        # never sees it.
+        event.stop()
+        event.prevent_default()
+        self._handle_normal_key(event)
+        self.post_message(self.StatusChanged(self.status_text))
+
+    # ------------------------------------------------------------------
+    # ':w' triggers TextEditor's real save flow (the same
+    # footer path-input ctrl+s opens) by walking up to the TextEditor
+    # ancestor and calling its action_save directly -- see
+    # VimModalMixin._trigger_ancestor_action's docstring for why plain
+    # run_action() doesn't work for this.
+    # ------------------------------------------------------------------
+    async def _do_save(self) -> None:
+        await self._trigger_ancestor_action("save")

textual_vim_textarea/vim_textarea.py

@@ -0,0 +1,103 @@
+"""
+vim_textarea.py
+
+Modal (vim-style) editing on top of plain Textual `TextArea`. All the
+actual vim logic (motions, operators, counts, registers, visual mode,
+command line) lives in `_modal.VimModalMixin`, shared with
+`textarea_plus.VimTextAreaPlus`. This file only has what's genuinely
+specific to a plain `TextArea` base: how keys get intercepted, and the
+Message classes host apps listen for.
+
+Key routing
+-----------
+TextArea's default `_on_key` treats every printable key as "insert this
+character". To get modal editing we override `_on_key`: in INSERT mode
+we fall through to the default behavior via `super()._on_key(event)`,
+and in NORMAL / VISUAL / COMMAND modes we swallow the event
+(`event.stop()` + `event.prevent_default()`) and route it through the
+shared dispatcher instead.
+
+(If you're using `textual-textarea`'s `TextEditor`/`TextAreaPlus` instead
+of plain `TextArea` -- use `textarea_plus.VimTextAreaPlus` instead. Its key
+routing is different on purpose; see that module's docstring for why
+this file's `super()._on_key()` approach would silently break
+TextAreaPlus's own features.)
+"""
+
+from __future__ import annotations
+
+from textual import events
+from textual.message import Message
+from textual.widgets import TextArea
+
+from ._modal import Mode, VimModalMixin
+
+__all__ = ["VimTextArea", "Mode"]
+
+
+class VimTextArea(VimModalMixin, TextArea):
+    """A TextArea with modal vim-style editing bound on top.
+
+    Drop-in replacement for `textual.widgets.TextArea`. Subclass it the
+    same way you would subclass TextArea; all of TextArea's own API
+    (text, document, selection, themes, syntax highlighting, etc.)
+    continues to work unchanged -- this class only intercepts key
+    handling while not in INSERT mode.
+    """
+
+    class ModeChanged(Message):
+        """Posted whenever the vim mode changes."""
+
+        def __init__(self, mode: Mode) -> None:
+            self.mode = mode
+            super().__init__()
+
+    class StatusChanged(Message):
+        """Posted after every NORMAL/VISUAL/COMMAND keystroke this widget
+        handles -- covers pending counts, pending operators, and the
+        command-line buffer changing, none of which necessarily change
+        `mode` itself. A host app's status bar should listen for this
+        (in addition to, or instead of, ModeChanged) to stay accurate."""
+
+        def __init__(self, status: str) -> None:
+            self.status = status
+            super().__init__()
+
+    class SaveRequested(Message):
+        """Posted on ':w' or ':wq'."""
+
+    class QuitRequested(Message):
+        """Posted on ':q' or ':wq'."""
+
+    class CommandEntered(Message):
+        """Posted for any ':' command this widget doesn't itself handle."""
+
+        def __init__(self, command: str) -> None:
+            self.command = command
+            super().__init__()
+
+    # ------------------------------------------------------------------
+    # key routing
+    # ------------------------------------------------------------------
+    async def _on_key(self, event: events.Key) -> None:
+        if self.mode is Mode.INSERT:
+            if event.key == "escape":
+                event.stop()
+                event.prevent_default()
+                self._enter_normal_mode(shift_cursor_left=True)
+                return
+            await super()._on_key(event)
+            return
+
+        if self.mode is Mode.COMMAND:
+            event.stop()
+            event.prevent_default()
+            await self._handle_command_key(event)
+            self.post_message(self.StatusChanged(self.status_text))
+            return
+
+        # NORMAL / VISUAL / VISUAL_LINE: we own every key.
+        event.stop()
+        event.prevent_default()
+        self._handle_normal_key(event)
+        self.post_message(self.StatusChanged(self.status_text))

textual_vim_textarea-1.1.0.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: textual-vim-textarea
+Version: 1.1.0
+Summary: A Vim-style textarea widget for Textual
+Project-URL: Homepage, https://github.com/Dking08/textual-vim-textarea
+Project-URL: Repository, https://github.com/Dking08/textual-vim-textarea
+Project-URL: Issues, https://github.com/Dking08/textual-vim-textarea/issues
+Author-email: Dking08 <dastageer_foss@yahoo.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: editor,textarea,textual,tui,vim
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Terminals
+Requires-Python: >=3.10
+Requires-Dist: textual>=6.4.0
+Provides-Extra: textarea-plus
+Requires-Dist: textual-textarea<0.18,>=0.17; extra == 'textarea-plus'
+Description-Content-Type: text/markdown
+
+# textual-vim-textarea
+
+vim-style editing built on top of Textual's built-in `TextArea`. This is just a subclass that intercepts keys before they hit the default "every keypress inserts a character" behavior.
+
+Built this to eventually wire vim keybindings into a TUI app, but split it out as its own module first so it could be tested properly on its own before touching real app code.
+
+## Two flavors
+
+- **`VimTextArea`** - for plain Textual `TextArea`. Zero extra dependencies beyond `textual` itself.
+- **`VimTextAreaPlus`** - for apps built on [`textual-textarea`](https://github.com/tconbeer/textual-textarea)'s `TextEditor`/`TextAreaPlus` instead of plain `TextArea`. 
+
+Both share the same underlying vim logic (`_modal.VimModalMixin`) - same motions, operators, counts, everything. They only differ in how they hook into their respective base widget's key handling, because the two bases genuinely work differently under the hood (see `textarea_plus.py`'s module docstring if you're curious exactly why).
+
+## What you get
+
+- Modes: `NORMAL`, `INSERT`, `VISUAL`, `VISUAL LINE`, `COMMAND`
+- Motions: `h j k l`, `0`, `^`, `$`, `w`, `b`, `e`, `gg`, `G` (arrow keys work too)
+- Insert entry: `i a I A o O`
+- Editing: `x X`, `dd dw db de`, `d$ / D`, `cc cw cb ce`, `c$ / C`,
+  `yy yw yb ye`, `y$`, `p P`, `u`, `ctrl+r`
+- Visual mode: `v` (charwise) / `V` (linewise), then `d x c y` act on the selection
+- Counts: `3j`, `3dd`, `2dw`, even `2d3w` (counts multiply, like real vim)
+- Command line: `:w`, `:q`, `:wq`, `:n` to jump to line `n` - anything else
+  gets posted as a message so your app can handle its own commands
+- Line numbers - this one's actually just `TextArea`'s built-in
+  `show_line_numbers=True`, not something this module adds
+
+**Not** currently implemented: registers beyond the default one, macros, marks, `:s///` regex substitution, folds, splits.
+
+> If you want to more vim features, you can contribute!
+
+## Project layout
+
+- `src/textual_vim_textarea/_modal.py` - shared vim logic, not meant to be used directly
+- `src/textual_vim_textarea/vim_textarea.py` - `VimTextArea`, built on plain `TextArea`. Primary file.
+- `src/textual_vim_textarea/textarea_plus.py` - `VimTextAreaPlus`, built on `textual-textarea`'s `TextAreaPlus`.
+
+- `examples/dummy_app.py` - standalone playground for `VimTextArea`
+- `examples/dummy_app_plus.py` + `examples/vim_text_editor.py` - standalone playground for `VimTextAreaPlus`, and the `TextEditor` subclass pattern to copy into a real app
+
+- `tests/test_vim_textarea.py`, `tests/test_textarea_plus.py` - headless tests using Textual's `Pilot`
+
+## Try it
+
+```bash
+uv sync
+python examples/dummy_app.py
+```
+
+> Bottom bar shows the mode/pending-command line, same idea as vim's own.
+> `:q` quits, `:w` just fires a notification since there's no real file
+> backing the dummy app.
+
+For the `TextAreaPlus` flavor (needs the extra) - OPTIONAL:
+
+```bash
+uv sync --extra textarea-plus
+python examples/dummy_app_plus.py
+```
+
+## Using it in your own TUI
+
+It's a drop-in replacement for `TextArea`. Use it exactly like you'd use `TextArea`, and listen for a couple of extra messages to keep a status bar in sync and to hook up `:w` / `:q`:
+
+```python
+from textual_vim_textarea import VimTextArea
+
+class MyApp(App):
+    def compose(self):
+        yield VimTextArea("some text", language="python", show_line_numbers=True, id="editor")
+
+    def on_vim_text_area_status_changed(self, message: VimTextArea.StatusChanged):
+        # fires on every NORMAL/VISUAL/COMMAND keystroke it handles -
+        # pending counts, pending operators, the command buffer, etc.
+        self.query_one("#status").update(message.status)
+
+    def on_vim_text_area_mode_changed(self, message: VimTextArea.ModeChanged):
+        # fires only when the mode itself actually changes
+        ...
+
+    def on_vim_text_area_save_requested(self, message: VimTextArea.SaveRequested):
+        # ':w' or ':wq' - do your actual file save here
+        ...
+
+    def on_vim_text_area_quit_requested(self, message: VimTextArea.QuitRequested):
+        # ':q' or ':wq'
+        self.exit()
+
+    def on_vim_text_area_command_entered(self, message: VimTextArea.CommandEntered):
+        # any ':' command that isn't w/q/wq/n - bring your own command palette
+        ...
+```
+
+**Everything else - `.text`, `.document`, `.selection`, themes, syntax highlighting, `language=`, etc. - is untouched `TextArea` API, works exactly as it does normally. This class only takes over key handling while you're not in INSERT mode.**
+
+### One gotcha if you're subclassing further
+
+`VimTextArea` uses `_on_key` as its extension point. If you need to add your own key handling on top, don't fight the binding system - override `_on_key`, check mode, and either fall through to `super()._on_key(event)` or handle it yourself and call `event.stop()` + `event.prevent_default()`. Same pattern this module already uses internally.
+
+`VimTextAreaPlus` is different on purpose - it hooks `on_key`, not `_on_key`, and in INSERT mode does **nothing at all** (not even calling `super()`) so the event cascades naturally through `TextAreaPlus`'s own `on_key` and then base `TextArea`'s `_on_key`. If you're subclassing `VimTextAreaPlus` further, match that: don't call `super().on_key()` manually, just decide whether to `prevent_default()`+`stop()` or leave the event alone entirely. See `textarea_plus.py`'s module docstring for the actual Textual dispatch mechanics this depends on - it's worth reading before you touch it, the ordering isn't obvious from the outside.
+
+### Using VimTextAreaPlus
+
+Same idea, but you also get to decide what `:w`/`:q` actually do, since `TextAreaPlus`'s real save flow lives on an ancestor `TextEditor` widget, not on the text area itself:
+
+```python
+from textual_vim_textarea.textarea_plus import VimTextAreaPlus
+
+class MyCodeEditor(TextEditor):  # from textual_textarea
+    def compose(self):
+        self.text_input = VimTextAreaPlus(language="sql", text=self._initial_text)
+        ...  # rest of TextEditor's own compose() body, unchanged
+
+    def on_vim_text_area_plus_quit_requested(self, message):
+        # ':q' - deliberately just a message. Closing a buffer/tab vs.
+        # quitting the whole app is your call, not this widget's.
+        ...
+```
+
+`:w` already works out of the box - it walks up to whatever ancestor has `action_save` (the real `TextEditor` action ctrl+s also triggers) and calls it directly, since Textual's own `run_action()` won't resolve an un-prefixed action name against an ancestor by default (verified this the hard way, see the integration guide).
+
+## Known rough edges
+
+- Word motions (`w b e`) use a simplified vim "word" definition (keyword run vs punctuation run vs whitespace). Covers the common case, isn't byte-for-byte identical to vim in every corner case.
+- `cw` intentionally behaves like `ce` (doesn't eat trailing whitespace).
+- Only one register (the unnamed one). `dd` then `yy` then `p` pastes whatever you yanked/deleted most recently, same register for everything.
+
+## Running the tests
+
+```bash
+uv run pytest tests -v --asyncio-mode=auto
+```
+
+39 tests, all green as of this writing - 25 for `VimTextArea`, 14 for `VimTextAreaPlus`

textual_vim_textarea-1.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+textual_vim_textarea/__init__.py,sha256=sM4D3P8kYLcSyZA70SRrCJcMDTRDzunPAFWIyna6Z10,460
+textual_vim_textarea/_modal.py,sha256=9SVlGvGhfZOtpNFmaLPOR4lUKUdflVlW1Y612W6Mjac,24868
+textual_vim_textarea/textarea_plus.py,sha256=LPRHmbDTIiN4NUJw1zy1Le3HKk8bNvexZkriSHxiww0,6961
+textual_vim_textarea/vim_textarea.py,sha256=nMGpKU10krY8aqT0ahn8zlcyzx-yFiK-lfRcgqT4Xjk,3896
+textual_vim_textarea-1.1.0.dist-info/METADATA,sha256=U0tHNaooAfBZmrpeI-PIza5W7xDhEfCqpnGh_z7R8-8,8112
+textual_vim_textarea-1.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+textual_vim_textarea-1.1.0.dist-info/licenses/LICENSE,sha256=jwVsOs8SK3I2qbYI4Dv5XerasO-we-d5HmPQC95O3wI,1096
+textual_vim_textarea-1.1.0.dist-info/RECORD,,

textual_vim_textarea-1.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

textual_vim_textarea-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dastageer Siddiqui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.