console-window 2.0.0.10__tar.gz → 2.0.2__tar.gz

{console_window-2.0.0.10 → console_window-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: console-window
-Version: 2.0.0.10
+Version: 2.0.2
 Summary: A robust curses wrapper for creating Text User Interfaces (TUIs).
 Author-email: Joe Defen <joedef@duck.com>
 Requires-Python: >=3.10
@@ -210,6 +210,36 @@ finally:
 Only keys the context actually added are removed on exit, so a pre-existing
 binding is left in place and nested uses are safe.
 
+### Taking navigation keys for the application
+
+Navigation keys are reserved by default, but an app may take specific ones for
+itself without monkeypatching the module global. Declare them on the window's
+options; the mapping value is the label the help screen shows:
+
+```python
+import curses
+from console_window import ConsoleWindowOpts, OptionSpinner
+
+opts = ConsoleWindowOpts(
+    taken_nav_keys={
+        curses.KEY_LEFT: 'prev page',
+        curses.KEY_RIGHT: 'next page',
+    },
+)
+win = ConsoleWindow(opts=opts)
+spin = OptionSpinner(stack=stack, nav_keys=opts.nav_keys)  # accept them in add_key()
+spin.add_key('prev', '← - previous', genre='action', keys=[curses.KEY_LEFT])
+```
+
+A taken key is withdrawn from navigation dispatch for that window only: it no
+longer scrolls, it is no longer advertised as navigation, and it takes the
+normal `handled_keys`/`relax_handled_keys` path on return. Text editing is
+unchanged — dialogs and widgets still use LEFT/RIGHT/HOME/END for the caret.
+Because ownership lives in `ConsoleWindowOpts`, two windows in one process can
+have different bindings; `NAVIGATION_KEYS` itself is never mutated. Taking every
+vertical key is allowed (and logged as "reduced navigation"), since the
+application is then responsible for its own scrolling.
+
 `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.10 → console_window-2.0.2}/README.md

@@ -191,6 +191,36 @@ finally:
 Only keys the context actually added are removed on exit, so a pre-existing
 binding is left in place and nested uses are safe.
 
+### Taking navigation keys for the application
+
+Navigation keys are reserved by default, but an app may take specific ones for
+itself without monkeypatching the module global. Declare them on the window's
+options; the mapping value is the label the help screen shows:
+
+```python
+import curses
+from console_window import ConsoleWindowOpts, OptionSpinner
+
+opts = ConsoleWindowOpts(
+    taken_nav_keys={
+        curses.KEY_LEFT: 'prev page',
+        curses.KEY_RIGHT: 'next page',
+    },
+)
+win = ConsoleWindow(opts=opts)
+spin = OptionSpinner(stack=stack, nav_keys=opts.nav_keys)  # accept them in add_key()
+spin.add_key('prev', '← - previous', genre='action', keys=[curses.KEY_LEFT])
+```
+
+A taken key is withdrawn from navigation dispatch for that window only: it no
+longer scrolls, it is no longer advertised as navigation, and it takes the
+normal `handled_keys`/`relax_handled_keys` path on return. Text editing is
+unchanged — dialogs and widgets still use LEFT/RIGHT/HOME/END for the caret.
+Because ownership lives in `ConsoleWindowOpts`, two windows in one process can
+have different bindings; `NAVIGATION_KEYS` itself is never mutated. Taking every
+vertical key is allowed (and logged as "reduced navigation"), since the
+application is then responsible for its own scrolling.
+
 `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.10 → console_window-2.0.2}/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.10"
+__version__ = "2.0.2"
 
 from .context import Context
 from .header import HeaderLine, Span

console_window-2.0.2/console_window/keys.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import curses
+
+# Keys reserved for cursor movement and scrolling.  By default
+# OptionSpinner.add_key rejects these with ValueError and demo-mode
+# highlighting ignores them.  An application may take specific keys for its own
+# use through ``ConsoleWindowOpts(taken_nav_keys=...)``; that withdraws them
+# from navigation dispatch for that window only.
+#
+# The set is a plain ``set`` for 2.0 compatibility, but the library never
+# mutates it.  Per-window ownership lives in ``ConsoleWindowOpts``: pass
+# ``taken_nav_keys`` to withdraw a key from *that* window's navigation
+# dispatch, and read ``opts.nav_keys`` for the effective (immutable) set.
+# Never monkeypatch this module global; two windows with different bindings
+# would contaminate each other.
+NAVIGATION_KEYS: set[int] = {
+    curses.KEY_UP, curses.KEY_DOWN, curses.KEY_LEFT, curses.KEY_RIGHT,
+    curses.KEY_HOME, curses.KEY_END, curses.KEY_PPAGE, curses.KEY_NPAGE,
+    ord('j'), ord('k'),            # Vi-style up / down
+    ord('0'), ord('$'),            # First / last row
+    ord('H'), ord('M'), ord('L'),  # Top / middle / bottom of page
+    ord('\x15'),  # Ctrl-U (half page up)
+    ord('\x04'),  # Ctrl-D (half page down)
+    ord('\x02'),  # Ctrl-B (page up)
+    ord('\x06'),  # Ctrl-F (page down)
+}
+
+# The subset of NAVIGATION_KEYS that moves the viewport vertically.  When an
+# application takes all of them (often to implement its own scrolling), the
+# window still constructs, but "reduced navigation" deserves a warning.
+VERTICAL_NAV_KEYS: frozenset[int] = frozenset({
+    curses.KEY_UP, curses.KEY_DOWN,
+    curses.KEY_HOME, curses.KEY_END, curses.KEY_PPAGE, curses.KEY_NPAGE,
+    ord('j'), ord('k'), ord('0'), ord('$'), ord('H'), ord('M'), ord('L'),
+    ord('\x15'), ord('\x04'), ord('\x02'), ord('\x06'),
+})

{console_window-2.0.0.10 → console_window-2.0.2}/console_window/opts.py

@@ -2,15 +2,62 @@ from __future__ import annotations
 
 import curses
 import difflib
+import logging
+from collections.abc import Iterable, Mapping
 from typing import Any, Callable
 
+from .keys import NAVIGATION_KEYS, VERTICAL_NAV_KEYS
+
+logger = logging.getLogger(__name__)
+
+
+def _normalize_taken_nav_keys(raw: object) -> dict[int, str]:
+    """Normalize ``taken_nav_keys`` to ``{key_code: app_label}``.
+
+    A mapping gives the help screen an app-facing label per key; a bare
+    iterable of key codes is accepted too and normalizes to an empty label.
+    Non-integer entries are rejected (they cannot be dispatched), and duplicate
+    entries collapse to one binding (the last label wins).  Keys that are not in
+    ``NAVIGATION_KEYS`` are kept but warned about: they subtract nothing, so
+    silently accepting them would hide a typo.
+    """
+    if raw is None:
+        return {}
+    if isinstance(raw, Mapping):
+        items: Iterable[tuple[object, object]] = raw.items()
+    elif isinstance(raw, Iterable) and not isinstance(raw, (str, bytes)):
+        items = ((key, '') for key in raw)
+    else:
+        raise TypeError(
+            'taken_nav_keys must be a mapping of {key_code: label} or an '
+            f'iterable of key codes, got {type(raw).__name__}'
+        )
+
+    normalized: dict[int, str] = {}
+    for key, label in items:
+        # bool is an int subclass; a True/False key code is always a mistake.
+        if isinstance(key, bool) or not isinstance(key, int):
+            raise ValueError(
+                f'taken_nav_keys entries must be integer key codes, got {key!r}'
+            )
+        normalized[key] = '' if label is None else str(label)
+
+    unknown = sorted(set(normalized) - NAVIGATION_KEYS)
+    if unknown:
+        logger.warning(
+            'taken_nav_keys: %s not a navigation key; these entries have no effect',
+            ', '.join(str(key) for key in unknown),
+        )
+    return normalized
+
 
 class ConsoleWindowOpts:
     __slots__ = ['answer_show_redraws', 'body_cols', 'body_rows', 'ctrl_c_terminates',
                  'demo_mode', 'dialog_abort', 'dialog_return', 'head_line', 'head_rows',
-                 'keys', 'max_rows', 'min_cols_rows', 'mod_pick', 'pick_attr', 'pick_mode',
-                 'pick_range', 'pick_size', 'relax_handled_keys', 'return_if_pos_change',
-                 'single_cell_scroll_indicator', 'strip_attrs_in_pick_mode', 'theme']
+                 'keys', 'max_rows', 'min_cols_rows', 'mod_pick', 'nav_keys', 'pick_attr',
+                 'pick_mode', 'pick_range', 'pick_size', 'relax_handled_keys',
+                 'return_if_pos_change', 'single_cell_scroll_indicator',
+                 'strip_attrs_in_pick_mode', 'taken_nav_keys', 'theme']
 
     # Explicit attribute types: assignments below come from **kwargs, so without
     # these every option would be typed as ``object`` and every read would need a
@@ -29,6 +76,11 @@ class ConsoleWindowOpts:
     keys: set | list | None
     min_cols_rows: tuple[int, int]
     mod_pick: Callable[[str], str] | None
+    # Effective navigation set for this window: ``NAVIGATION_KEYS`` minus the
+    # keys the application took.  Computed, never passed in.
+    nav_keys: frozenset[int]
+    # App-owned navigation keys: {key_code: label shown on the help screen}.
+    taken_nav_keys: dict[int, str]
     pick_attr: int
     pick_mode: bool
     pick_range: list[int] | None
@@ -59,6 +111,21 @@ class ConsoleWindowOpts:
         self.max_rows = kwargs.get('max_rows', 32767)
         self.body_cols = kwargs.get('body_cols', 200)
         self.keys = kwargs.get('keys')
+        if 'nav_keys' in kwargs:
+            raise TypeError(
+                'ConsoleWindowOpts() computes nav_keys from taken_nav_keys; '
+                'pass taken_nav_keys={key: label} instead of nav_keys.'
+            )
+        self.taken_nav_keys = _normalize_taken_nav_keys(kwargs.get('taken_nav_keys'))
+        self.nav_keys = frozenset(NAVIGATION_KEYS - set(self.taken_nav_keys))
+        if self.taken_nav_keys and not (self.nav_keys & VERTICAL_NAV_KEYS):
+            # Explicit user choice, not an error: the app has taken over
+            # scrolling.  Still worth a diagnostic, because "the arrow keys do
+            # nothing" is otherwise indistinguishable from a bug.
+            logger.warning(
+                'taken_nav_keys removes every vertical navigation key; this '
+                'window has reduced (custom) navigation'
+            )
         self.pick_mode = kwargs.get('pick_mode', False)
         self.pick_size = kwargs.get('pick_size', 1)
         self.mod_pick = kwargs.get('mod_pick')

{console_window-2.0.0.10 → console_window-2.0.2}/console_window/spinner.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import curses
+from collections.abc import Iterable
 from types import SimpleNamespace
 from typing import TYPE_CHECKING
 
@@ -12,9 +13,18 @@ if TYPE_CHECKING:  # pragma: no cover - typing only
 
 
 class OptionSpinner:
-    def __init__(self, stack: ScreenStack | None = None) -> None:
+    def __init__(self, stack: ScreenStack | None = None,
+                 nav_keys: Iterable[int] | None = None) -> None:
         self.options: list[SimpleNamespace] = []
         self.keys: set[int] = set()
+        # The navigation set this spinner validates against.  Pass the owning
+        # window's ``opts.nav_keys`` when the window takes navigation keys for
+        # the app; otherwise the process default applies.  Keeping this
+        # per-spinner (rather than reading/mutating the module global) lets two
+        # windows with different bindings coexist.
+        self.nav_keys: frozenset[int] = frozenset(
+            NAVIGATION_KEYS if nav_keys is None else nav_keys
+        )
         self.margin = 4 # + actual width (1st column right pos)
         self.align = self.margin # + actual width (1st column right pos)
         self._default_obj: object = SimpleNamespace() # if not given one (private)
@@ -125,7 +135,7 @@ class OptionSpinner:
         return chr(key) if 32 <= key < 127 else f'<{key}>'
 
     def _reject_navigation_key(self, key: int) -> None:
-        if key in NAVIGATION_KEYS:
+        if key in self.nav_keys:
             raise ValueError(
                 f'Key {self._key_label(key)} ({key}) conflicts with a navigation key. '
                 f'Navigation keys are reserved for cursor movement and scrolling.'
@@ -253,9 +263,9 @@ class OptionSpinner:
 
     @staticmethod
     def show_help_nav_keys(win: ConsoleWindow) -> None:
-        # Late import to avoid a circular import at module load time.
-        from .window import ConsoleWindow
-        for line in ConsoleWindow.get_nav_key_lines():
+        # Render from the live window so its own opts.taken_nav_keys are
+        # honoured: keys the app owns are not advertised as navigation.
+        for line in win.nav_help_lines():
             win.add_header(line)
 
     def show_help_body(self, win: ConsoleWindow, screen_filter: int | list | set | None = None) -> None:

{console_window-2.0.0.10 → console_window-2.0.2}/console_window/window.py

@@ -40,23 +40,116 @@ if TYPE_CHECKING:  # pragma: no cover - typing only
 
 logger = logging.getLogger(__name__)
 
-# Navigation help is stored as complete lines, not a dedented triple-quoted
-# string: editing the indentation can no longer change what the help screen
-# renders.  ``ConsoleWindow.nav_keys`` remains the joined string for callers
-# that want the whole blurb at once.
-NAV_KEY_LINES: tuple[str, ...] = (
-    'Navigation:      H/M/L:      top/middle/end-of-page',
-    '  k, UP:  up one row             0, HOME:  first row',
-    'j, DOWN:  down one row           $, END:  last row',
-    '  Ctrl-u:  half-page up     Ctrl-b, PPAGE:  page up',
-    '  Ctrl-d:  half-page down     Ctrl-f, NPAGE:  page down',
-)
-
 # Control keys that drive the same movements as the page keys.  They live here
-# rather than inside `prompt()` so the navigation map and the help text above
+# rather than inside `prompt()` so the navigation map and the help text below
 # cannot drift apart silently.
 _CTRL_PAGE_UP, _CTRL_HALF_DOWN, _CTRL_PAGE_DOWN, _CTRL_HALF_UP = 2, 4, 6, 21
 
+# Display labels for the keys that can appear in the navigation help.  Arrow
+# keys are listed too even though the default rows do not use them: an app that
+# takes LEFT/RIGHT gets `←`/`→` on the "App:" line without supplying a label.
+NAV_KEY_LABELS: dict[int, str] = {
+    curses.KEY_UP: 'UP',
+    curses.KEY_DOWN: 'DOWN',
+    curses.KEY_LEFT: '←',
+    curses.KEY_RIGHT: '→',
+    curses.KEY_HOME: 'HOME',
+    curses.KEY_END: 'END',
+    curses.KEY_PPAGE: 'PPAGE',
+    curses.KEY_NPAGE: 'NPAGE',
+    ord('j'): 'j',
+    ord('k'): 'k',
+    ord('0'): '0',
+    ord('$'): '$',
+    ord('H'): 'H',
+    ord('M'): 'M',
+    ord('L'): 'L',
+    _CTRL_HALF_UP: 'Ctrl-u',
+    _CTRL_HALF_DOWN: 'Ctrl-d',
+    _CTRL_PAGE_UP: 'Ctrl-b',
+    _CTRL_PAGE_DOWN: 'Ctrl-f',
+}
+
+# Structured navigation help: (key codes, description).  The rendered lines are
+# generated from this table and the window's effective key set, so a key the
+# application took disappears from the help instead of being advertised and
+# doing nothing.  Keep this table in step with `_navigation_target()`; the two
+# are the single sources of truth for "what scrolls" and "what we say scrolls".
+NAV_HELP_ROWS: tuple[tuple[tuple[int, ...], str], ...] = (
+    ((ord('k'), curses.KEY_UP), 'up one row'),
+    ((ord('j'), curses.KEY_DOWN), 'down one row'),
+    ((ord('0'), curses.KEY_HOME), 'first row'),
+    ((ord('$'), curses.KEY_END), 'last row'),
+    ((_CTRL_HALF_UP,), 'half-page up'),
+    ((_CTRL_HALF_DOWN,), 'half-page down'),
+    ((_CTRL_PAGE_UP, curses.KEY_PPAGE), 'page up'),
+    ((_CTRL_PAGE_DOWN, curses.KEY_NPAGE), 'page down'),
+    ((ord('H'), ord('M'), ord('L')), 'top/middle/end-of-page'),
+)
+
+_NAV_HELP_COLUMN = 38
+_NAV_HELP_PREFIX = 'Navigation:  '
+_NAV_APP_PREFIX = 'App:         '
+
+
+def _nav_key_label(key: int) -> str:
+    label = NAV_KEY_LABELS.get(key)
+    if label is not None:
+        return label
+    return chr(key) if 32 <= key < 127 else f'<{key}>'
+
+
+def _pair_nav_entries(entries: list[str], prefix: str) -> list[str]:
+    """Render two entries per line under a fixed-width prefix."""
+    lines = []
+    pad = ' ' * len(prefix)
+    for index in range(0, len(entries), 2):
+        left = entries[index]
+        right = entries[index + 1] if index + 1 < len(entries) else ''
+        head = prefix if index == 0 else pad
+        lines.append(f'{head}{left:<{_NAV_HELP_COLUMN}}{right}'.rstrip())
+    return lines
+
+
+def render_nav_help(effective: Iterable[int],
+                    taken: dict[int, str] | None = None) -> tuple[str, ...]:
+    """Render the navigation help for one window's effective key set.
+
+    ``effective`` is the set of key codes still dispatched as navigation;
+    ``taken`` maps the app-owned keys to the label the app wants shown.  The
+    default (no taken keys) output is the public ``NAV_KEY_LINES`` text.
+    """
+    effective = frozenset(effective)
+    entries = []
+    for keys, label in NAV_HELP_ROWS:
+        shown = [_nav_key_label(key) for key in keys if key in effective]
+        if shown:
+            entries.append(f'{", ".join(shown)}: {label}')
+
+    if entries:
+        lines = _pair_nav_entries(entries, _NAV_HELP_PREFIX)
+    else:
+        lines = [
+            _NAV_HELP_PREFIX
+            + '(no navigation keys: all are bound by the application)'
+        ]
+
+    app_entries = []
+    for key, label in (taken or {}).items():
+        name = _nav_key_label(key)
+        app_entries.append(f'{name}: {label}' if label else name)
+    if app_entries:
+        lines.extend(_pair_nav_entries(app_entries, _NAV_APP_PREFIX))
+    return tuple(lines)
+
+
+# Navigation help for the default key set.  Stored as complete lines, not a
+# dedented triple-quoted string: editing the indentation can no longer change
+# what the help screen renders.  ``ConsoleWindow.nav_keys`` remains the joined
+# string for callers that want the whole blurb at once; live windows render
+# through ``nav_help_lines()`` so their own ``taken_nav_keys`` are honoured.
+NAV_KEY_LINES: tuple[str, ...] = render_nav_help(NAVIGATION_KEYS)
+
 # 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
@@ -577,6 +670,10 @@ class ConsoleWindow:
     def get_nav_key_lines() -> tuple[str, ...]:
         return NAV_KEY_LINES
 
+    def nav_help_lines(self) -> tuple[str, ...]:
+        """Navigation help for *this* window's effective key set."""
+        return render_nav_help(self.opts.nav_keys, self.opts.taken_nav_keys)
+
     def _set_screen_dims(self) -> bool:
         rows, cols = self.scr.getmaxyx()
         same = bool(rows == self.rows and cols == self.cols)
@@ -2304,7 +2401,9 @@ class ConsoleWindow:
         return None
 
     def _record_demo_key(self, key: int) -> None:
-        if self.opts.demo_mode and key not in NAVIGATION_KEYS:
+        # Taken navigation keys are app-owned, so demo mode highlights them
+        # just like any other application key.
+        if self.opts.demo_mode and key not in self.opts.nav_keys:
             self.last_demo_key = self._format_key_for_demo(key)
 
     def _clear_demo_indicator(self) -> None:
@@ -2313,7 +2412,8 @@ class ConsoleWindow:
 
     def _is_passthrough_key(self, key: int) -> bool:
         return (32 <= key <= 126 or key in _PASSTHROUGH_EDITING_KEYS
-                or key in NAVIGATION_KEYS or key in self.handled_keys)
+                or key in NAVIGATION_KEYS or key in self.opts.taken_nav_keys
+                or key in self.handled_keys)
 
     def _passthrough_result(self, key: int) -> int | None:
         if not self.passthrough_mode or not self._is_passthrough_key(key):
@@ -2334,12 +2434,18 @@ class ConsoleWindow:
         if key in self.handled_keys and not self.relax_handled_keys:
             self._record_demo_key(key)
             return True, key  # return for handling
-        if key in NAVIGATION_KEYS:
+        if key in self.opts.nav_keys:
             self._clear_demo_indicator()
         return False, None
 
     def _navigation_target(self, key: int) -> int | None:
         """Map a navigation key to the row it asks for, or None if it is not one."""
+        # A key the application took is withdrawn from navigation dispatch.
+        # This guard must come before the moves table: removing the key from
+        # NAVIGATION_KEYS alone would still let UP/DOWN/page keys scroll,
+        # because the table is what actually dispatches.
+        if key in self.opts.taken_nav_keys:
+            return None
         pos = self.pick_pos if self.pick_mode else self.scroll_pos
         delta = self.pick_size if self.pick_mode else 1
         half = self.scroll_view_size // 2

{console_window-2.0.0.10 → console_window-2.0.2/tests}/CHANGELOG.md

@@ -3,6 +3,53 @@
 All notable changes to `console-window` are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [2.0.2]
+
+### Added
+- `ConsoleWindowOpts(taken_nav_keys=...)`: hand specific navigation keys to the
+  application on a per-window basis. The value is a mapping of
+  `{key_code: help_label}` (a bare iterable of key codes is also accepted and
+  normalizes to empty labels), so the help screen can show what the app bound
+  them to (`←: prev`). The normalized mapping is available as
+  `opts.taken_nav_keys`, and the effective set as `opts.nav_keys` (a
+  `frozenset` of `NAVIGATION_KEYS` minus the taken keys).
+- `OptionSpinner(nav_keys=...)`: the spinner validates `add_key()` against the
+  supplied set instead of the module global, so
+  `OptionSpinner(nav_keys=opts.nav_keys)` accepts a key the window took.
+- `ConsoleWindow.nav_help_lines()`: renders navigation help for the window's
+  effective key set and appends a separate `App:` line for taken keys with
+  their labels. `OptionSpinner.show_help_nav_keys(win)` now uses it.
+
+### Changed
+- Navigation help is generated from the structured `NAV_HELP_ROWS` table, so a
+  key the app took disappears from the rendered help instead of being
+  advertised and doing nothing. `NAV_KEY_LINES`, `get_nav_key_lines()` and
+  `get_nav_keys_blurb()` remain the static default output, and the default
+  rendering is unchanged.
+- `_navigation_target()` refuses a taken key before consulting its movement
+  table. Subtracting from `NAVIGATION_KEYS` alone was not enough: UP/DOWN,
+  page and HOME/END movements are dispatched by that hardcoded table, so a
+  taken key would still have scrolled.
+- Demo-mode highlighting and passthrough classification treat taken keys as
+  application keys, and `_handle_prompt_app_key()` no longer treats them as
+  navigation.
+- `NAVIGATION_KEYS` is still a `set` for 2.0 compatibility, but the library no
+  longer mutates it. Applications should pass `taken_nav_keys` (and can delete
+  their `NAVIGATION_KEYS.remove(...)` monkeypatches); two windows with
+  different bindings no longer contaminate each other.
+
+### Notes
+- A taken key is withdrawn from *navigation dispatch* only. Text editing
+  (`_DIALOG_SIMPLE_MOVES`, widget carets, dialogs) still uses
+  LEFT/RIGHT/HOME/END normally.
+- Return behaviour follows the existing `handled_keys`/`relax_handled_keys`
+  rules: a taken key bound through the spinner is returned; with
+  `relax_handled_keys=False` and no binding it may still be swallowed.
+- Invalid entries (non-integer key codes) raise `ValueError`; duplicate codes
+  collapse to one binding. Codes that are not navigation keys are kept but
+  logged as having no effect, and taking every vertical key logs a
+  "reduced navigation" warning instead of failing.
+
 ## [Unreleased]
 
 ### Added
@@ -446,4 +493,5 @@ fully backward compatible (`from console_window import ...` and
 - `Development Status` classifier aligned with the release; version bumped to
   `2.0.1`.
 
+[2.0.2]: https://github.com/joedefen/console-window
 [2.0.1]: https://github.com/joedefen/console-window

console_window-2.0.2/tests/test_taken_nav_keys.py

@@ -0,0 +1,251 @@
+"""Per-window navigation-key ownership (``opts.taken_nav_keys``).
+
+The trap these tests exist for: subtracting a key from ``NAVIGATION_KEYS`` is
+not enough, because movement is dispatched by a separate hardcoded table in
+``_navigation_target()``.  UP/DOWN, the page keys and HOME/END must therefore
+be tested specifically: they are the keys that would still scroll if only the
+reservation set were changed.
+"""
+
+import curses
+import logging
+
+import pytest
+
+import console_window.window as window_mod
+from console_window import ConsoleWindow, ConsoleWindowOpts, OptionSpinner
+from console_window.backend import HeadlessBackend
+from console_window.keys import NAVIGATION_KEYS, VERTICAL_NAV_KEYS
+from console_window.window import NAV_KEY_LINES
+
+_ACS_STANDINS = {
+    'ACS_HLINE': '-',
+    'ACS_VLINE': '|',
+    'ACS_ULCORNER': '+',
+    'ACS_URCORNER': '+',
+    'ACS_LLCORNER': '+',
+    'ACS_LRCORNER': '+',
+}
+
+
+@pytest.fixture(autouse=True)
+def _headless_curses(monkeypatch):
+    for name, value in _ACS_STANDINS.items():
+        if not hasattr(window_mod.curses, name):
+            monkeypatch.setattr(window_mod.curses, name, value, raising=False)
+
+
+@pytest.fixture
+def make():
+    created = []
+
+    def _make(backend=None, **opts):
+        backend = backend if backend is not None else HeadlessBackend(rows=24, cols=80)
+        win = ConsoleWindow(opts=ConsoleWindowOpts(**opts), backend=backend,
+                            singleton=False)
+        created.append(win)
+        return win, backend
+
+    yield _make
+    for win in created:
+        if win.scr is not None:
+            win.stop_curses()
+
+
+# --- opts normalization and validation --------------------------------------
+
+def test_default_opts_keeps_every_navigation_key():
+    opts = ConsoleWindowOpts()
+    assert opts.taken_nav_keys == {}
+    assert opts.nav_keys == frozenset(NAVIGATION_KEYS)
+
+
+def test_mapping_labels_are_preserved_and_iterables_normalize_to_empty():
+    opts = ConsoleWindowOpts(taken_nav_keys={
+        curses.KEY_LEFT: 'prev',
+        curses.KEY_RIGHT: 'next',
+    })
+    assert opts.taken_nav_keys == {
+        curses.KEY_LEFT: 'prev',
+        curses.KEY_RIGHT: 'next',
+    }
+    assert curses.KEY_LEFT not in opts.nav_keys
+
+    bare = ConsoleWindowOpts(taken_nav_keys=[curses.KEY_UP, curses.KEY_DOWN])
+    assert bare.taken_nav_keys == {curses.KEY_UP: '', curses.KEY_DOWN: ''}
+
+
+def test_duplicate_keys_collapse_to_the_last_label():
+    opts = ConsoleWindowOpts(taken_nav_keys={curses.KEY_LEFT: 'a',
+                                             curses.KEY_LEFT: 'b'})
+    assert opts.taken_nav_keys == {curses.KEY_LEFT: 'b'}
+
+
+def test_non_integer_keys_are_rejected():
+    with pytest.raises(ValueError, match='integer key codes'):
+        ConsoleWindowOpts(taken_nav_keys={'LEFT': 'prev'})
+    with pytest.raises(ValueError, match='integer key codes'):
+        ConsoleWindowOpts(taken_nav_keys={True: 'yes'})
+
+
+def test_nav_keys_is_computed_not_passed():
+    with pytest.raises(TypeError, match='taken_nav_keys'):
+        ConsoleWindowOpts(nav_keys=[ord('j')])
+
+
+def test_unknown_key_is_kept_but_logged(caplog):
+    with caplog.at_level(logging.WARNING, logger='console_window.opts'):
+        opts = ConsoleWindowOpts(taken_nav_keys={ord('z'): 'zoom'})
+    assert opts.taken_nav_keys == {ord('z'): 'zoom'}
+    assert opts.nav_keys == frozenset(NAVIGATION_KEYS)  # nothing was subtracted
+    assert any('not a navigation key' in record.message for record in caplog.records)
+
+
+def test_taking_every_vertical_key_warns_but_constructs(caplog, make):
+    with caplog.at_level(logging.WARNING, logger='console_window.opts'):
+        win, _backend = make(taken_nav_keys=dict.fromkeys(VERTICAL_NAV_KEYS, ''))
+    assert not (win.opts.nav_keys & VERTICAL_NAV_KEYS)
+    assert any('reduced' in record.message for record in caplog.records)
+    # The help screen reports the reduced navigation instead of lying.
+    assert 'no navigation keys' in win.nav_help_lines()[0]
+
+
+# --- dispatch: taken keys must not scroll -----------------------------------
+
+@pytest.mark.parametrize('key', [
+    curses.KEY_UP, curses.KEY_DOWN,
+    curses.KEY_PPAGE, curses.KEY_NPAGE,
+    curses.KEY_HOME, curses.KEY_END,
+    ord('j'), ord('k'), ord('0'), ord('$'), ord('H'), ord('M'), ord('L'),
+    2, 4, 6, 21,
+])
+def test_taken_key_never_scrolls_and_is_returned_to_the_app(make, key):
+    win, backend = make(backend=HeadlessBackend(rows=12, cols=80),
+                        body_rows=60, head_rows=2, taken_nav_keys={key: 'app'})
+    for i in range(40):
+        win.add_body(f'row {i}')
+    win.fix_positions()
+    win.scroll_pos = min(10, win.max_scroll_pos)
+    win.fix_positions()
+    before = win.scroll_pos
+
+    backend.queue_keys(key)
+    assert win.prompt(seconds=0.5) == key  # relax_handled_keys default: app gets it
+    assert win.scroll_pos == before
+
+
+def test_taken_key_without_binding_may_be_swallowed_when_not_relaxed(make):
+    # Existing handled_keys/relax_handled_keys rules apply; ownership does not
+    # implicitly add the key to handled_keys.
+    win, backend = make(relax_handled_keys=False, taken_nav_keys={curses.KEY_DOWN: ''})
+    for i in range(40):
+        win.add_body(f'row {i}')
+    win.fix_positions()
+    before = win.scroll_pos
+    backend.queue_keys(curses.KEY_DOWN)
+    assert win.prompt(seconds=0.02) is None
+    assert win.scroll_pos == before
+
+
+def test_spinner_accepts_a_taken_key_and_the_action_fires(make):
+    opts = ConsoleWindowOpts(
+        taken_nav_keys={curses.KEY_RIGHT: 'next'},
+        relax_handled_keys=False,
+    )
+    win, backend = make(taken_nav_keys=opts.taken_nav_keys,
+                        relax_handled_keys=False)
+    spin = OptionSpinner(nav_keys=opts.nav_keys)
+    spin.add_key('next', '→ - next', genre='action', keys=[curses.KEY_RIGHT])
+    win.set_handled_keys(spin)
+
+    backend.queue_keys(curses.KEY_RIGHT)
+    assert win.prompt(seconds=0.5) == curses.KEY_RIGHT
+    assert win.scroll_pos == 0
+
+    spin.do_key(curses.KEY_RIGHT, win)
+    assert spin.default_obj.next is True
+
+
+def test_spinner_still_rejects_a_retained_navigation_key():
+    opts = ConsoleWindowOpts(taken_nav_keys={curses.KEY_LEFT: 'prev'})
+    spin = OptionSpinner(nav_keys=opts.nav_keys)
+    with pytest.raises(ValueError, match='navigation key'):
+        spin.add_key('jump', 'UP - reserved', genre='action', keys=[curses.KEY_UP])
+
+
+# --- isolation --------------------------------------------------------------
+
+def test_two_windows_with_different_bindings_do_not_affect_each_other(make):
+    global_keys = frozenset(NAVIGATION_KEYS)
+
+    left, _left_backend = make(taken_nav_keys={curses.KEY_LEFT: 'prev'})
+    for i in range(40):
+        left.add_body(f'row {i}')
+    left.fix_positions()
+
+    right, right_backend = make()
+    for i in range(40):
+        right.add_body(f'row {i}')
+    right.fix_positions()
+    right.scroll_pos = min(5, right.max_scroll_pos)
+    right.fix_positions()
+    before = right.scroll_pos
+
+    assert left.opts.nav_keys == global_keys - {curses.KEY_LEFT}
+    assert right.opts.nav_keys == global_keys
+    # The untouched window still navigates normally.
+    right_backend.queue_keys(curses.KEY_DOWN)
+    right.prompt()
+    assert right.scroll_pos == before + 1
+    # And the module global was never mutated.
+    assert frozenset(NAVIGATION_KEYS) == global_keys
+    assert left.opts.taken_nav_keys == {curses.KEY_LEFT: 'prev'}
+
+
+# --- dialogs and help -------------------------------------------------------
+
+def test_dialogs_still_edit_with_taken_arrow_and_home_end_keys(make):
+    win, backend = make(taken_nav_keys={
+        curses.KEY_LEFT: '', curses.KEY_RIGHT: '',
+        curses.KEY_HOME: '', curses.KEY_END: '',
+    })
+    backend.queue_keys(ord('h'), ord('i'), curses.KEY_LEFT,
+                       curses.KEY_BACKSPACE, 10)
+    assert win.answer() == 'i'
+
+    backend.queue_keys(curses.KEY_HOME, curses.KEY_DC, 10)
+    assert win.answer(seed='ab') == 'b'
+
+
+def test_default_help_is_generated_from_the_structured_table():
+    opts = ConsoleWindowOpts()
+    lines = window_mod.render_nav_help(opts.nav_keys, opts.taken_nav_keys)
+    assert lines == NAV_KEY_LINES
+    assert 'k, UP: up one row' in lines[0]
+
+
+def test_help_omits_taken_nav_keys_and_shows_app_labels(make):
+    win, _backend = make(taken_nav_keys={
+        curses.KEY_UP: 'app up',
+        curses.KEY_LEFT: 'prev',
+        curses.KEY_RIGHT: 'next',
+    })
+    lines = win.nav_help_lines()
+    joined = '\n'.join(lines)
+
+    # UP is gone from the navigation rows, but its sibling k remains.
+    assert 'k, UP' not in joined
+    assert 'k: up one row' in joined
+    # Taken keys are advertised under App: with the caller's labels.
+    assert '←: prev' in joined
+    assert '→: next' in joined
+    assert 'UP: app up' in joined
+    assert lines[-2].startswith('App:') or lines[-1].startswith('App:')
+
+
+def test_spinner_help_renders_from_the_window(make):
+    win, _backend = make(taken_nav_keys={curses.KEY_LEFT: 'prev'})
+    spin = OptionSpinner(nav_keys=win.opts.nav_keys)
+    spin.show_help_nav_keys(win)
+    header_text = '\n'.join(win.head.texts)
+    assert '←: prev' in header_text

console_window-2.0.0.10/console_window/keys.py

@@ -1,18 +0,0 @@
-from __future__ import annotations
-
-import curses
-
-# Keys reserved for cursor movement and scrolling.  Applications cannot bind
-# these: OptionSpinner.add_key rejects them with ValueError, and demo-mode
-# highlighting ignores them.
-NAVIGATION_KEYS: set[int] = {
-    curses.KEY_UP, curses.KEY_DOWN, curses.KEY_LEFT, curses.KEY_RIGHT,
-    curses.KEY_HOME, curses.KEY_END, curses.KEY_PPAGE, curses.KEY_NPAGE,
-    ord('j'), ord('k'),            # Vi-style up / down
-    ord('0'), ord('$'),            # First / last row
-    ord('H'), ord('M'), ord('L'),  # Top / middle / bottom of page
-    ord('\x15'),  # Ctrl-U (half page up)
-    ord('\x04'),  # Ctrl-D (half page down)
-    ord('\x02'),  # Ctrl-B (page up)
-    ord('\x06'),  # Ctrl-F (page down)
-}