console-window 2.0.0.9__tar.gz → 2.0.1__tar.gz

{console_window-2.0.0.9 → console_window-2.0.1}/CHANGELOG.md

@@ -65,8 +65,27 @@ This project follows [Semantic Versioning](https://semver.org/).
   without a TTY. Coverage of `window.py` rises from 55% to 84% (missing
   statements 444 → 161), so the half of the engine users actually feel is now
   smoke-tested in CI (AUDIT.md §3.2).
+- `InlineConfirmation` is now a real line editor, matching the
+  `IncrementalSearchBar` beside it: `start(..., initial='')` seeds the buffer
+  with the caret at the end, and `LEFT`/`RIGHT`/`HOME`/`END` (also Ctrl-A/
+  Ctrl-E), `KEY_DC` and Backspace edit at the caret instead of only appending.
+  `cursor_pos` exposes the string index, `cursor_cell` the terminal column
+  (measured with `textwidth`), and `get_display_string(prompt='',
+  cursor_char='│')` renders the prompt plus the caret for a body row.
+  Movement, insertion and deletion use the `textwidth` helpers so wide
+  characters and combining marks cannot split a grapheme.
+- `ConsoleWindow.temp_handled_keys(*keys)`: a context manager that adds keys to
+  `handled_keys` for one prompt and removes only the keys it actually added, so
+  an application key can be forwarded reversibly and nested uses leave existing
+  bindings intact.
 
 ### Changed
+- Passthrough mode now forwards ESC (`27`) and Delete (`curses.KEY_DC`) as
+  editing keys, in addition to printable characters, Backspace, the arrow keys
+  and Home/End. This closes the gap that forced every `InlineConfirmation`
+  caller to discover `win.handled_keys.add(27)` to receive the cancel key; the
+  resize-abort path already treated `27` as an application key when bound, so
+  the behaviour is consistent rather than a silent widening.
 - Every `pylint` warning now states why it is deliberate (AUDIT.md §3.3), taking
   `pylint --disable=C,R` from 9.94/10 to **10.00/10**. Protected-access and
   protocol-signature findings carry scoped disables with an adjacent reason,

{console_window-2.0.0.9 → console_window-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: console-window
-Version: 2.0.0.9
+Version: 2.0.1
 Summary: A robust curses wrapper for creating Text User Interfaces (TUIs).
 Author-email: Joe Defen <joedef@duck.com>
 Requires-Python: >=3.10
@@ -105,7 +105,8 @@ demonstrates:
 * **`IncrementalSearchBar`** — `/` filters the list as you type, using
   `passthrough_mode` to hand keys to the bar.
 * **`InlineConfirmation`** — `SPACE` asks you to confirm with `y` before
-  "processing" the picked row.
+  "processing" the picked row. The widget is also a curses-free line editor
+  (`initial=''`, caret movement, Delete, and `get_display_string()`).
 * **Themes** — a `THEMES` screen of colour samples backed by
   `Theme.list_all()` / `get_current()` / `set()`. The active theme is now
   per-window state: `ConsoleWindowOpts(theme=...)` seeds `window.theme`,
@@ -182,6 +183,33 @@ For anything beyond a single list, subclass `Screen` and drive it with
 `ScreenStack` — that is what the sample app does, and it is the paradigm the
 library is designed around.
 
+### Inline editing and key forwarding
+
+`InlineConfirmation` is a curses-free line editor. `start(..., initial='x')`
+seeds the buffer with the caret at the end; `LEFT`/`RIGHT`, Home/End (and
+Ctrl-A/Ctrl-E), Backspace and Delete edit at the caret. The
+`get_display_string(prompt='…')` method returns the prompt plus the buffer and
+caret glyph, so wording and layout stay in the application, while `cursor_pos`
+(string index) and `cursor_cell` (terminal column, measured with `textwidth`)
+are available to callers that need them.
+
+Passthrough widgets receive printable ASCII, navigation keys, Backspace,
+Delete, Home/End, ESC and the keys in `handled_keys` while
+`passthrough_mode` is `True`. For any additional application key, use the
+reversible context manager rather than mutating `handled_keys` by hand:
+
+```python
+win.passthrough_mode = True
+try:
+    with win.temp_handled_keys(27):
+        key = win.prompt(seconds=0.5)
+finally:
+    win.passthrough_mode = False
+```
+
+Only keys the context actually added are removed on exit, so a pre-existing
+binding is left in place and nested uses are safe.
+
 `ScreenStack.perform_actions()` is the normal router: it walks the spinner
 options, honours their scopes, and calls the matching `<attr>_ACTION` method.
 For apps that dispatch an action themselves, `ScreenStack.act_in(action,

{console_window-2.0.0.9 → console_window-2.0.1}/README.md

@@ -86,7 +86,8 @@ demonstrates:
 * **`IncrementalSearchBar`** — `/` filters the list as you type, using
   `passthrough_mode` to hand keys to the bar.
 * **`InlineConfirmation`** — `SPACE` asks you to confirm with `y` before
-  "processing" the picked row.
+  "processing" the picked row. The widget is also a curses-free line editor
+  (`initial=''`, caret movement, Delete, and `get_display_string()`).
 * **Themes** — a `THEMES` screen of colour samples backed by
   `Theme.list_all()` / `get_current()` / `set()`. The active theme is now
   per-window state: `ConsoleWindowOpts(theme=...)` seeds `window.theme`,
@@ -163,6 +164,33 @@ For anything beyond a single list, subclass `Screen` and drive it with
 `ScreenStack` — that is what the sample app does, and it is the paradigm the
 library is designed around.
 
+### Inline editing and key forwarding
+
+`InlineConfirmation` is a curses-free line editor. `start(..., initial='x')`
+seeds the buffer with the caret at the end; `LEFT`/`RIGHT`, Home/End (and
+Ctrl-A/Ctrl-E), Backspace and Delete edit at the caret. The
+`get_display_string(prompt='…')` method returns the prompt plus the buffer and
+caret glyph, so wording and layout stay in the application, while `cursor_pos`
+(string index) and `cursor_cell` (terminal column, measured with `textwidth`)
+are available to callers that need them.
+
+Passthrough widgets receive printable ASCII, navigation keys, Backspace,
+Delete, Home/End, ESC and the keys in `handled_keys` while
+`passthrough_mode` is `True`. For any additional application key, use the
+reversible context manager rather than mutating `handled_keys` by hand:
+
+```python
+win.passthrough_mode = True
+try:
+    with win.temp_handled_keys(27):
+        key = win.prompt(seconds=0.5)
+finally:
+    win.passthrough_mode = False
+```
+
+Only keys the context actually added are removed on exit, so a pre-existing
+binding is left in place and nested uses are safe.
+
 `ScreenStack.perform_actions()` is the normal router: it walks the spinner
 options, honours their scopes, and calls the matching `<attr>_ACTION` method.
 For apps that dispatch an action themselves, `ScreenStack.act_in(action,

{console_window-2.0.0.9 → console_window-2.0.1}/SampleApp.py

@@ -303,17 +303,19 @@ class MainScreen(DemoScreen):
             ctx = Context(genre='item', item=item)
             app.win.add_body(line, attr=attr, context=ctx)
 
-            # Show inline confirmation if active for this item
+            # Show inline confirmation if active for this item.  The wording and
+            # the warning glyph stay here (product decisions); the widget owns
+            # the buffer/caret composition.
             if app.confirmation.active and \
                app.confirmation.identity == username:
-                msg = f'    ⚠️  Process {username}?'
+                prompt = f'    ⚠️  Process {username}?'
                 if app.confirmation.mode == 'y':
-                    msg += " - Press 'y' or ESC"
+                    prompt += " - Press 'y' or ESC"
                 elif app.confirmation.mode == 'Y':
-                    msg += " - Press 'Y' or ESC"
+                    prompt += " - Press 'Y' or ESC"
 
                 app.win.add_body(
-                    msg,
+                    app.confirmation.get_display_string(prompt=prompt),
                     attr=cs.color_pair(Theme.WARNING) | cs.A_BOLD,
                     context=Context(genre='DECOR')
                 )

{console_window-2.0.0.9 → console_window-2.0.1}/console_window/__init__.py

@@ -1,6 +1,6 @@
 # Single source of truth for the package version: pyproject.toml declares
 # ``dynamic = ["version"]``, so flit reads this value instead of duplicating it.
-__version__ = "2.0.0.9"
+__version__ = "2.0.1"
 
 from .context import Context
 from .header import HeaderLine, Span

{console_window-2.0.0.9 → console_window-2.0.1}/console_window/widgets.py

@@ -4,6 +4,7 @@ import curses
 from typing import Callable, ClassVar
 
 from .header import HeaderLine
+from .textwidth import cell_to_index, char_width, string_width
 
 # Keys treated as backspace (all terminal variants).  Shared by both widgets so
 # the list cannot drift between them.
@@ -18,20 +19,23 @@ class InlineConfirmation:
         self.action_type: str | None = None  # e.g., 'wipe' or 'verify'
         self.identity: str | None = None     # e.g., 'sda1'
         self.choices: list[str] | None = None
-        self.input_buffer: str = ''
+        self._input_buffer: str = ''
+        self._cursor_pos: int = 0
         self.mode: str | None = None
         self.min_abbrev_chars: int | None = min_abbrev_chars
         self._calculated_min_abbrev: int | None = None  # Cached calculated value
 
     def start(self, action_type: str | None = None, identity: str | None = None,
               choices: str | list[str] | tuple[str, ...] | None = None,
-              mode: str | None = None, min_abbrev_chars: int | None = None) -> None:
+              mode: str | None = None, min_abbrev_chars: int | None = None,
+              initial: str = '') -> None:
         self.active = True
         self.action_type = action_type
         self.identity = identity
         self.choices = (list(choices) if isinstance(choices, (list, tuple))
                     else [choices] if isinstance(choices, str) else None)
-        self.input_buffer = ''
+        self._input_buffer = initial
+        self._cursor_pos = len(initial)
 
         # Override min_abbrev_chars if provided
         if min_abbrev_chars is not None:
@@ -52,7 +56,86 @@ class InlineConfirmation:
         self.active = False
         self.action_type = None
         self.choices = None
-        self.input_buffer = ''
+        self._input_buffer = ''
+        self._cursor_pos = 0
+
+    @property
+    def input_buffer(self) -> str:
+        return self._input_buffer
+
+    @input_buffer.setter
+    def input_buffer(self, value: str) -> None:
+        # Callers and older code seed the buffer by assignment; keeping the
+        # caret at the end means the next key appends where a reader expects.
+        self._input_buffer = value
+        self._cursor_pos = len(value)
+
+    @property
+    def cursor_pos(self) -> int:
+        return self._cursor_pos
+
+    @property
+    def cursor_cell(self) -> int:
+        """Caret column in terminal cells (wide chars occupy two)."""
+        pos = self._snap_index(self._cursor_pos)
+        return string_width(self._input_buffer[:pos])
+
+    def _snap_index(self, index: int) -> int:
+        # The caret is a string index, but a display-cell split must not land
+        # between a base character and its combining marks.  textwidth maps the
+        # index's cell back to a safe code-point boundary.
+        index = max(0, min(index, len(self._input_buffer)))
+        return cell_to_index(self._input_buffer,
+                             string_width(self._input_buffer[:index]))
+
+    def _move_cursor_left(self) -> None:
+        pos = self._snap_index(self._cursor_pos)
+        if pos <= 0:
+            self._cursor_pos = 0
+            return
+        pos -= 1
+        while pos > 0 and char_width(self._input_buffer[pos]) == 0:
+            pos -= 1
+        self._cursor_pos = pos
+
+    def _move_cursor_right(self) -> None:
+        pos = self._snap_index(self._cursor_pos)
+        end = len(self._input_buffer)
+        if pos >= end:
+            self._cursor_pos = end
+            return
+        pos += 1
+        while pos < end and char_width(self._input_buffer[pos]) == 0:
+            pos += 1
+        self._cursor_pos = pos
+
+    def _insert_text(self, text: str) -> None:
+        pos = self._snap_index(self._cursor_pos)
+        self._input_buffer = (self._input_buffer[:pos] + text
+                              + self._input_buffer[pos:])
+        self._cursor_pos = pos + len(text)
+
+    def _delete_backward(self) -> None:
+        end = self._snap_index(self._cursor_pos)
+        if end <= 0:
+            self._cursor_pos = 0
+            return
+        self._cursor_pos = end
+        self._move_cursor_left()
+        self._input_buffer = (self._input_buffer[:self._cursor_pos]
+                              + self._input_buffer[end:])
+
+    def _delete_forward(self) -> None:
+        start = self._snap_index(self._cursor_pos)
+        end = len(self._input_buffer)
+        if start >= end:
+            self._cursor_pos = start
+            return
+        pos = start + 1
+        while pos < end and char_width(self._input_buffer[pos]) == 0:
+            pos += 1
+        self._input_buffer = self._input_buffer[:start] + self._input_buffer[pos:]
+        self._cursor_pos = start
 
     def _calculate_min_abbrev_chars(self) -> int:
         choices = self.choices
@@ -136,9 +219,19 @@ class InlineConfirmation:
 
         # Handle buffered input
         if 32 <= key <= 126:
-            self.input_buffer += chr(key)
+            self._insert_text(chr(key))
         elif key in _BACKSPACE_KEYS:  # Backspace (all variants)
-            self.input_buffer = self.input_buffer[:-1]
+            self._delete_backward()
+        elif key == curses.KEY_DC:
+            self._delete_forward()
+        elif key == curses.KEY_LEFT:
+            self._move_cursor_left()
+        elif key == curses.KEY_RIGHT:
+            self._move_cursor_right()
+        elif key in (curses.KEY_HOME, 1):  # Home / Ctrl-A
+            self._cursor_pos = 0
+        elif key in (curses.KEY_END, 5):  # End / Ctrl-E
+            self._cursor_pos = len(self._input_buffer)
         elif key in (10, 13):  # Enter
             return self._handle_enter()
 
@@ -176,6 +269,24 @@ class InlineConfirmation:
         # 'yes' or other permissive modes
         return self.input_buffer if self.input_buffer.lower() == 'yes' else None
 
+    def get_display_string(self, prompt: str = '', cursor_char: str = '│') -> str:
+        """Return the prompt and editable buffer with a caret glyph.
+
+        The caret index is split on a textwidth cell boundary, so a pasted
+        wide character or combining mark cannot put the glyph mid-grapheme.
+        Single-key modes (``Y``/``y``) have no editable text and return the
+        prompt unchanged; an inactive widget returns ``''`` so a caller can
+        decide when the row should disappear.
+        """
+        if not self.active:
+            return ''
+        if self.mode in ('Y', 'y'):
+            return prompt
+        pos = self._snap_index(self._cursor_pos)
+        before = self._input_buffer[:pos]
+        after = self._input_buffer[pos:]
+        return f'{prompt}{before}{cursor_char}{after}'
+
     #: Hints whose text does not depend on runtime state.
     _STATIC_HINTS: ClassVar[dict[str, str]] = {
         'YES': 'Type YES + ENTER or ESC',

{console_window-2.0.0.9 → console_window-2.0.1}/console_window/window.py

@@ -14,7 +14,8 @@ import sys
 import time
 import warnings
 import weakref
-from collections.abc import Iterable
+from collections.abc import Iterable, Iterator
+from contextlib import contextmanager
 from curses.textpad import rectangle
 from types import SimpleNamespace
 from typing import TYPE_CHECKING, Callable, ClassVar, cast
@@ -58,8 +59,13 @@ _CTRL_PAGE_UP, _CTRL_HALF_DOWN, _CTRL_PAGE_DOWN, _CTRL_HALF_UP = 2, 4, 6, 21
 
 # Editing keys that passthrough mode hands to the application unchanged, in
 # addition to printable characters, navigation keys and `handled_keys`.
+# ESC and DELETE are editing keys too: an in-place widget such as
+# InlineConfirmation must be able to cancel and rub out at the caret, and
+# callers should not have to discover `handled_keys` to make that work.
 _PASSTHROUGH_EDITING_KEYS = frozenset({
     curses.KEY_BACKSPACE, 127, 8, 263,  # backspace variants
+    curses.KEY_DC,                      # delete at the caret
+    27,                                 # ESC: cancel an in-place edit
     curses.KEY_LEFT, curses.KEY_RIGHT,
     curses.KEY_HOME, curses.KEY_END,
     1, 5,  # Ctrl-A, Ctrl-E
@@ -391,6 +397,30 @@ class ConsoleWindow:
         else:
             self.handled_keys = set()
 
+    @contextmanager
+    def temp_handled_keys(self, *keys: int) -> Iterator[ConsoleWindow]:
+        """Temporarily add key codes to ``handled_keys``.
+
+        ``prompt()`` only returns a key that is in ``handled_keys`` (or one of
+        the built-in passthrough editing keys).  This context manager makes
+        that forwarding reversible by construction: only the keys it actually
+        added are removed on exit, so nested uses leave a pre-existing binding
+        intact.
+
+        Example: forwarding an application key for one inline edit::
+
+            win.passthrough_mode = True
+            with win.temp_handled_keys(27):
+                key = win.prompt(seconds=0.5)
+            win.passthrough_mode = False
+        """
+        added = {key for key in keys if key not in self.handled_keys}
+        self.handled_keys.update(added)
+        try:
+            yield self
+        finally:
+            self.handled_keys.difference_update(added)
+
     def set_demo_mode(self, enabled: bool | None) -> bool:
         if enabled is None: # toggle if not explicit
             self.opts.demo_mode = not (self.opts.demo_mode)

{console_window-2.0.0.9 → console_window-2.0.1}/tests/test_interactive.py

@@ -95,6 +95,49 @@ def test_prompt_passthrough_records_demo_indicator(make):
     assert win.last_demo_key == ' p '
 
 
+def test_prompt_passthrough_forwards_escape_without_handled_keys(make):
+    # The gap that forced every InlineConfirmation caller to discover
+    # handled_keys: ESC must reach a passthrough editor as a normal key.
+    win, backend = make()
+    win.passthrough_mode = True
+    backend.queue_keys(27)
+    assert win.prompt(seconds=0.5) == 27
+
+
+def test_prompt_passthrough_forwards_delete(make):
+    win, backend = make()
+    win.passthrough_mode = True
+    backend.queue_keys(curses.KEY_DC)
+    assert win.prompt(seconds=0.5) == curses.KEY_DC
+
+
+def test_temp_handled_keys_is_reversible(make):
+    win, backend = make(relax_handled_keys=False)
+    with win.temp_handled_keys(ord('x')) as scoped:
+        assert scoped is win
+        assert ord('x') in win.handled_keys
+        backend.queue_keys(ord('x'))
+        assert win.prompt(seconds=0.5) == ord('x')
+    assert ord('x') not in win.handled_keys
+
+
+def test_temp_handled_keys_preserves_preexisting_binding(make):
+    win, _backend = make(keys={ord('q')}, relax_handled_keys=False)
+    with win.temp_handled_keys(ord('q'), ord('x')):
+        assert ord('q') in win.handled_keys
+        assert ord('x') in win.handled_keys
+    assert ord('q') in win.handled_keys
+    assert ord('x') not in win.handled_keys
+
+
+def test_temp_handled_keys_restores_on_exception(make):
+    win, _backend = make()
+    with pytest.raises(RuntimeError):
+        with win.temp_handled_keys(27):
+            raise RuntimeError('boom')
+    assert 27 not in win.handled_keys
+
+
 # --- prompt(): Ctrl-C as an application key --------------------------------
 
 def test_prompt_returns_etx_when_ctrl_c_is_handled(monkeypatch, make):

{console_window-2.0.0.9 → console_window-2.0.1}/tests/test_widgets.py

@@ -182,3 +182,106 @@ def test_searchbar_display_string_inactive():
 def test_searchbar_display_string_empty():
     bar = IncrementalSearchBar()
     assert bar.get_display_string() == ''
+
+
+# --- InlineConfirmation: caret and line editing ----------------------------
+
+def test_inline_start_seeds_buffer_and_caret():
+    c = InlineConfirmation()
+    c.start(mode='text', initial='hello')
+    assert c.input_buffer == 'hello'
+    assert c.cursor_pos == 5
+    c.handle_key(ord('!'))
+    assert c.input_buffer == 'hello!'
+    assert c.cursor_pos == 6
+    assert c.handle_key(10) == 'confirmed'
+
+
+def test_inline_cursor_movement_and_insertion():
+    c = InlineConfirmation()
+    c.start(mode='text', initial='abc')
+    c.handle_key(curses.KEY_LEFT)
+    c.handle_key(curses.KEY_LEFT)
+    c.handle_key(ord('X'))
+    assert c.input_buffer == 'aXbc'
+    assert c.cursor_pos == 2
+
+
+def test_inline_home_end_and_delete_at_caret():
+    c = InlineConfirmation()
+    c.start(mode='text', initial='abc')
+    c.handle_key(curses.KEY_HOME)
+    assert c.cursor_pos == 0
+    c.handle_key(curses.KEY_DC)
+    assert c.input_buffer == 'bc'
+    assert c.cursor_pos == 0
+    c.handle_key(curses.KEY_END)
+    assert c.cursor_pos == 2
+    c.handle_key(curses.KEY_DC)  # at end: no-op
+    assert c.input_buffer == 'bc'
+
+
+def test_inline_ctrl_a_and_ctrl_e_move_the_caret():
+    c = InlineConfirmation()
+    c.start(mode='text', initial='abc')
+    c.handle_key(1)
+    assert c.cursor_pos == 0
+    c.handle_key(5)
+    assert c.cursor_pos == 3
+
+
+def test_inline_backspace_deletes_before_the_caret():
+    c = InlineConfirmation()
+    c.start(mode='text', initial='abcd')
+    c.handle_key(curses.KEY_LEFT)  # caret before 'd'
+    c.handle_key(curses.KEY_BACKSPACE)
+    assert c.input_buffer == 'abd'
+    assert c.cursor_pos == 2
+
+
+def test_inline_input_buffer_assignment_keeps_caret_in_range():
+    c = InlineConfirmation()
+    c.start(mode='text', initial='abc')
+    c.input_buffer = 'z'
+    assert c.cursor_pos == 1
+
+
+def test_inline_display_string_has_prompt_and_caret():
+    c = InlineConfirmation()
+    c.start(mode='text', initial='abc')
+    c.handle_key(curses.KEY_LEFT)
+    assert c.get_display_string(prompt='> ', cursor_char='|') == '> ab|c'
+
+
+def test_inline_display_string_inactive_is_empty():
+    c = InlineConfirmation()
+    c.start(mode='text', initial='abc')
+    c.cancel()
+    assert c.get_display_string(prompt='> ') == ''
+
+
+def test_inline_display_string_single_key_mode_has_no_caret():
+    c = InlineConfirmation()
+    c.start(mode='y')
+    assert c.get_display_string(prompt='Process?') == 'Process?'
+
+
+def test_inline_wide_and_combining_caret_uses_cell_width():
+    c = InlineConfirmation()
+    c.start(mode='text', initial='a\u0301界')
+    assert c.cursor_pos == 3
+    assert c.cursor_cell == 3  # 'a' + combining mark = 1 cell, '界' = 2
+    c.handle_key(curses.KEY_LEFT)  # skip the whole wide character
+    assert c.cursor_cell == 1
+    c.handle_key(curses.KEY_LEFT)  # skip the base + combining mark
+    assert c.cursor_pos == 0
+
+
+def test_inline_display_split_never_splits_a_grapheme():
+    c = InlineConfirmation()
+    c.start(mode='text')
+    # Place the caret between the base character and its combining mark; the
+    # display split snaps forward so the glyph stays after the whole grapheme.
+    c._input_buffer = 'a\u0301'
+    c._cursor_pos = 1
+    assert c.get_display_string(cursor_char='|') == 'a\u0301|'