iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/behaviors/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Reusable TUI interaction behaviors."""

chrys/app/tui/behaviors/click_outside_dismiss.py

@@ -0,0 +1,90 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Mixin that dismisses a ModalScreen when the user clicks the backdrop."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from textual import events
+from textual.await_complete import AwaitComplete
+from textual.errors import NoWidget
+
+if TYPE_CHECKING:
+    from textual.screen import Screen
+
+    _ClickOutsideDismissBase = Screen[Any]
+else:
+    _ClickOutsideDismissBase = object
+
+
+class ClickOutsideDismissMixin(_ClickOutsideDismissBase):
+    """Mixin for ``ModalScreen`` that dismisses on backdrop click.
+
+    When a left-click lands on the screen itself (the dimmed overlay area
+    outside any child widget), ``dismiss()`` is called.  This mirrors the
+    common UX convention where clicking outside a dialog closes it.
+
+    Put this mixin before ``ModalScreen`` in the class bases::
+
+        class MyScreen(ClickOutsideDismissMixin, ModalScreen[None]): ...
+
+    Compatible with ``RightClickScreenCopyMixin`` — that mixin intercepts
+    right-click via ``_forward_event``; this one uses ``on_click`` for
+    left-click only.
+
+    Subclasses can customise backdrop-dismiss via three hooks:
+
+    * ``_allow_click_outside_dismiss()`` — return ``False`` to suppress
+      dismiss in certain states.
+    * ``_default_dismiss_result()`` — a *pure* getter for the value passed
+      to ``dismiss()`` (e.g. ``ConfirmDialog`` returns ``False``).
+    * ``_dismiss_clicked_outside()`` — override the whole dismiss action
+      when a backdrop cancel needs side effects (e.g. ``ThemesScreen``
+      restores its previewed theme); reuse the screen's existing cancel
+      path here rather than mutating state inside the value getter.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        self._chrys_dismiss_await_complete: AwaitComplete | None = None
+        super().__init__(*args, **kwargs)
+
+    def dismiss(self, result: object | None = None) -> AwaitComplete:
+        """Dismiss once.
+
+        Textual completes a modal result future inside ``dismiss()`` and
+        raises if a later event tries to complete that same modal again.
+        Most modal close paths are fed by queued UI messages, so make the
+        operation idempotent for every modal using this mixin.
+        """
+        existing = self._chrys_dismiss_await_complete
+        if existing is not None:
+            return existing
+        await_complete = super().dismiss(result)  # type: ignore[misc]
+        self._chrys_dismiss_await_complete = await_complete
+        return await_complete
+
+    def on_click(self, event: events.Click) -> None:
+        # Only left-click (button 1).
+        if event.button != 1:
+            return
+        try:
+            widget, _ = self.get_widget_at(event.screen_x, event.screen_y)  # type: ignore[attr-defined]
+        except NoWidget:
+            return
+        # If the topmost widget under the cursor is the screen itself,
+        # the click landed on the backdrop — dismiss.
+        if widget is self and self._allow_click_outside_dismiss():
+            self._dismiss_clicked_outside()
+
+    def _allow_click_outside_dismiss(self) -> bool:
+        """Hook for subclasses to conditionally suppress dismiss."""
+        return True
+
+    def _dismiss_clicked_outside(self) -> None:
+        """Perform the dismissal. Override for cancel paths with side effects."""
+        self.dismiss(self._default_dismiss_result())  # type: ignore[attr-defined]
+
+    def _default_dismiss_result(self):
+        """Pure getter for the dismiss value; override to customise."""
+        return

chrys/app/tui/behaviors/insert_clipboard.py

@@ -0,0 +1,73 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Ctrl+Insert / Shift+Insert clipboard fallbacks shared by the app and modal screens.
+
+Chrys editors bind the Insert clipboard keys themselves so image paste and
+Vim mode gating run first. These fallbacks serve everything else: text
+selected on a screen and stock Textual controls. They are non-priority
+bindings, so they only run after the focused widget declined the key.
+
+Textual stops the non-priority binding chain at a ``ModalScreen``, which
+hides the application-level copy of these bindings from every modal dialog.
+Modal roots therefore spread :data:`INSERT_CLIPBOARD_BINDINGS` into their own
+``BINDINGS`` and mix in :class:`InsertClipboardScreenMixin` for the actions.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Final
+
+from textual import events
+from textual.binding import Binding
+from textual.widgets import Input, TextArea
+
+from chrys.app.tui.binding_display import COPY_BINDING, PASTE_BINDING, localized_binding
+from chrys.app.tui.clipboard import copy_text_to_clipboards, paste_text_from_clipboards
+
+if TYPE_CHECKING:
+    from textual.app import App
+    from textual.screen import Screen
+
+COPY_WITH_INSERT_ACTION: Final = "copy_with_insert"
+PASTE_WITH_INSERT_ACTION: Final = "paste_with_insert"
+
+INSERT_CLIPBOARD_BINDINGS: Final[tuple[Binding, ...]] = (
+    localized_binding("ctrl+insert", COPY_WITH_INSERT_ACTION, COPY_BINDING, show=False),
+    localized_binding("shift+insert", PASTE_WITH_INSERT_ACTION, PASTE_BINDING, show=False),
+)
+"""Non-priority bindings every binding namespace repeats to reach the fallbacks."""
+
+
+def copy_with_insert(app: App[Any]) -> None:
+    """Copy the focused editor selection, then fall back to the screen selection."""
+    focused = app.focused
+    selected = focused.selected_text if isinstance(focused, Input | TextArea) else ""
+    if not selected:
+        selected = app.screen.get_selected_text() or ""
+    if selected:
+        copy_text_to_clipboards(app, selected)
+
+
+def paste_with_insert(app: App[Any]) -> None:
+    """Route clipboard text through the same Paste event the terminal driver posts."""
+    if text := paste_text_from_clipboards(app):
+        app.post_message(events.Paste(text))
+
+
+_InsertClipboardScreenBase = Screen[Any] if TYPE_CHECKING else object
+
+
+class InsertClipboardScreenMixin(_InsertClipboardScreenBase):
+    """Screen actions backing :data:`INSERT_CLIPBOARD_BINDINGS`.
+
+    Textual only merges ``BINDINGS`` declared on ``DOMNode`` subclasses, so a
+    mixin cannot contribute the bindings themselves. Each modal root spreads
+    :data:`INSERT_CLIPBOARD_BINDINGS` into its own ``BINDINGS`` alongside
+    this mixin; the modal-screen structure test enforces the pairing.
+    """
+
+    def action_copy_with_insert(self) -> None:
+        copy_with_insert(self.app)
+
+    def action_paste_with_insert(self) -> None:
+        paste_with_insert(self.app)

chrys/app/tui/behaviors/right_click_copy.py

@@ -0,0 +1,146 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Shared right-click copy helpers for selectable TUI surfaces."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+from textual.errors import NoWidget
+from textual.events import Event, MouseDown, MouseMove
+from textual.screen import Screen
+from textual.widgets import TextArea
+
+from chrys.app.tui.clipboard import copy_text_to_clipboards
+
+_RightClickScreenCopyBase = Screen[Any] if TYPE_CHECKING else object
+
+
+def copy_screen_selection(screen: Screen, *, clear: bool = False) -> bool:
+    """Copy the screen-level selected text and optionally clear it."""
+    selected = screen.get_selected_text()
+    if selected is None:
+        return False
+    copy_text_to_clipboards(screen.app, selected)
+    if clear:
+        screen.clear_selection()
+    return True
+
+
+def cancel_textual_mouse_chain(screen: Screen) -> None:
+    """Cancel Textual's private mouse bookkeeping after right-click copy."""
+    # Textual internals: these private fields drive mouse-up selection
+    # clearing and synthetic Click generation. Keep this aligned with
+    # Textual's App.on_event / Screen._forward_event during upgrades.
+    screen.app._mouse_down_widget = None
+    screen._mouse_down_offset = None
+    screen._selecting = False
+
+
+def discard_detached_selection_hit(screen: Screen, event: Event) -> bool:
+    """Consume mouse selection events whose content widget was just detached."""
+    if event.is_forwarded or not isinstance(event, (MouseDown, MouseMove)):
+        return False
+    if not screen.selections and not screen._selecting:
+        return False
+
+    select_widget, _select_offset = screen.get_widget_and_offset_at(event.x, event.y)
+    if select_widget is None:
+        return False
+    if select_widget.is_attached:
+        return False
+
+    screen.clear_selection()
+    cancel_textual_mouse_chain(screen)
+    event.prevent_default()
+    event.stop()
+    return True
+
+
+def right_click_targets_text_area(screen: Screen, event: MouseDown) -> bool:
+    """Return true when a right-click should be handled by a text editor."""
+    try:
+        widget, _region = screen.get_widget_at(event.screen_x, event.screen_y)
+    except NoWidget:
+        return False
+    return any(isinstance(ancestor, TextArea) for ancestor in widget.ancestors_with_self)
+
+
+class RightClickScreenCopyMixin(_RightClickScreenCopyBase):
+    """Mixin for screens whose right-click should copy screen-selected text.
+
+    Windows Terminal's native right-click copy is unavailable while Textual
+    owns mouse reporting, so Chrys mirrors that workflow for selectable UI.
+    Put this mixin before ``Screen`` / ``ModalScreen`` in the class bases so
+    ``super()._forward_event`` resolves to Textual's screen implementation.
+    """
+
+    def on_mouse_down(self, event: MouseDown) -> None:
+        """Copy selected screen text on right-click."""
+        if event.button != 3:
+            return
+        if self._right_click_targets_text_area(event):
+            return
+        self._handle_right_click_copy(event)
+
+    def _handle_right_click_copy(self, event: MouseDown) -> bool:
+        if event.button != 3:
+            return False
+        screen = cast(Screen, self)
+        if not copy_screen_selection(screen, clear=True):
+            return False
+        cancel_textual_mouse_chain(screen)
+        event.prevent_default()
+        event.stop()
+        return True
+
+    def _right_click_targets_text_area(self, event: MouseDown) -> bool:
+        return right_click_targets_text_area(cast(Screen, self), event)
+
+    def _forward_event(self, event: Event) -> None:
+        """Intercept right-click copy before Textual mutates selection state."""
+        screen = cast(Screen, self)
+        if discard_detached_selection_hit(screen, event):
+            return
+        if (
+            isinstance(event, MouseDown)
+            and not event.is_forwarded
+            and event.button == 3
+            and not self._right_click_targets_text_area(event)
+            and self._handle_right_click_copy(event)
+        ):
+            return
+        super()._forward_event(event)
+
+    def _copy_selected_text(self, *, clear: bool = False) -> bool:
+        return copy_screen_selection(cast(Screen, self), clear=clear)
+
+
+def copy_text_area_or_screen_selection(text_area: TextArea, *, clear: bool = False) -> bool:
+    """Copy a text-area selection, falling back to the owning screen selection."""
+    selected = text_area.selected_text
+    if selected:
+        copy_text_to_clipboards(text_area.app, selected)
+        if clear:
+            _, end = text_area.selection
+            text_area.selection = type(text_area.selection).cursor(end)
+        return True
+    screen_selected = text_area.screen.get_selected_text()
+    if not screen_selected:
+        return False
+    copy_text_to_clipboards(text_area.app, screen_selected)
+    if clear:
+        text_area.screen.clear_selection()
+    return True
+
+
+def handle_text_area_right_click_copy(text_area: TextArea, event: MouseDown) -> bool:
+    """Copy selected text for a text-area right-click and consume the event."""
+    if event.button != 3:
+        return False
+    if not copy_text_area_or_screen_selection(text_area, clear=True):
+        return False
+    cancel_textual_mouse_chain(text_area.screen)
+    event.prevent_default()
+    event.stop()
+    return True

chrys/app/tui/binding_display.py

@@ -0,0 +1,139 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Stable display metadata for localized Textual bindings."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import Any
+
+from textual.binding import Binding
+
+from chrys.foundation.i18n import MessageDef, msg
+
+logger = logging.getLogger(__name__)
+
+CLOSE_BINDING = msg("tui.binding.close", fallback="Close")
+CANCEL_BINDING = msg("tui.binding.cancel", fallback="Cancel")
+COPY_BINDING = msg("tui.binding.copy", fallback="Copy")
+DELETE_BINDING = msg("tui.binding.delete", fallback="Delete")
+PASTE_BINDING = msg("tui.binding.paste", fallback="Paste")
+QUIT_BINDING = msg("tui.binding.quit", fallback="Quit")
+TOGGLE_VIEW_BINDING = msg("tui.binding.toggle_view", fallback="Toggle view")
+
+_SHARED_BINDING_DISPLAY_IDS = frozenset(
+    {
+        CLOSE_BINDING.key,
+        CANCEL_BINDING.key,
+        COPY_BINDING.key,
+        DELETE_BINDING.key,
+        PASTE_BINDING.key,
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class BindingDisplaySpec:
+    """Extractable display definitions associated with one stable binding id."""
+
+    description: MessageDef
+    tooltip: MessageDef | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class _BindingDisplayRegistration:
+    spec: BindingDisplaySpec
+    actions: frozenset[str]
+
+
+_BINDING_DISPLAY_REGISTRY: dict[str, _BindingDisplayRegistration] = {}
+
+
+def _register_binding_display(binding_id: str, spec: BindingDisplaySpec, action: str) -> None:
+    registration = _BindingDisplayRegistration(spec, frozenset({action}))
+    current = _BINDING_DISPLAY_REGISTRY.get(binding_id)
+    if current is None:
+        _BINDING_DISPLAY_REGISTRY[binding_id] = registration
+    elif current.spec != spec:
+        raise ValueError(f"Conflicting binding display registration for {binding_id!r}.")
+    elif action not in current.actions:
+        if binding_id not in _SHARED_BINDING_DISPLAY_IDS:
+            raise ValueError(f"Conflicting binding display registration for {binding_id!r}.")
+        _BINDING_DISPLAY_REGISTRY[binding_id] = _BindingDisplayRegistration(spec, current.actions | {action})
+
+
+def localized_binding(
+    key: str,
+    action: str,
+    definition: MessageDef,
+    *,
+    tooltip: MessageDef | None = None,
+    **binding_kwargs: Any,
+) -> Binding:
+    """Build a Binding and atomically register its stable display metadata."""
+    spec = BindingDisplaySpec(description=definition, tooltip=tooltip)
+    binding = Binding(
+        key,
+        action,
+        definition.fallback,
+        tooltip=tooltip.fallback if tooltip is not None else "",
+        id=definition.key,
+        **binding_kwargs,
+    )
+    _register_binding_display(definition.key, spec, action)
+    return binding
+
+
+def get_binding_display_spec(binding_id: str) -> BindingDisplaySpec | None:
+    """Return the display spec registered under *binding_id*, if any."""
+    registration = _BINDING_DISPLAY_REGISTRY.get(binding_id)
+    return registration.spec if registration is not None else None
+
+
+def get_binding_display_provenance(binding_id: str, action: str | None = None) -> str | None:
+    """Return the action recorded alongside *binding_id*, if registered."""
+    registration = _BINDING_DISPLAY_REGISTRY.get(binding_id)
+    if registration is None:
+        return None
+    if action is not None:
+        return action if action in registration.actions else None
+    if len(registration.actions) == 1:
+        return next(iter(registration.actions))
+    return None
+
+
+def resolve_binding_display(binding: Binding) -> BindingDisplaySpec | None:
+    """Resolve display metadata when id and action provenance both agree."""
+    if binding.id is None:
+        return None
+    registration = _BINDING_DISPLAY_REGISTRY.get(binding.id)
+    if registration is None:
+        return None
+    if binding.action not in registration.actions:
+        logger.warning("Binding display provenance mismatch; using literal display text.")
+        return None
+    return registration.spec
+
+
+def iter_binding_display_specs() -> Iterator[BindingDisplaySpec]:
+    """Iterate a stable snapshot of the exact registered display specs."""
+    return iter(tuple(registration.spec for registration in _BINDING_DISPLAY_REGISTRY.values()))
+
+
+__all__ = [
+    "CANCEL_BINDING",
+    "CLOSE_BINDING",
+    "COPY_BINDING",
+    "DELETE_BINDING",
+    "PASTE_BINDING",
+    "QUIT_BINDING",
+    "TOGGLE_VIEW_BINDING",
+    "BindingDisplaySpec",
+    "get_binding_display_provenance",
+    "get_binding_display_spec",
+    "iter_binding_display_specs",
+    "localized_binding",
+    "resolve_binding_display",
+]

chrys/app/tui/buddy_messages.py

@@ -0,0 +1,17 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Shared semantic messages for Buddy toast presentation."""
+
+from chrys.foundation.i18n import msg
+
+BUDDY_TITLE = msg("tui.buddy.title", fallback="Buddy")
+
+_TILTS_HEAD = msg("tui.buddy.thinking.tilts_head", fallback="💭 {name} tilts its head...")
+_CHOOSES_WORDS = msg("tui.buddy.thinking.chooses_words", fallback="💭 {name} is choosing its words...")
+_GLANCES = msg("tui.buddy.thinking.glances", fallback="💭 {name} looks at you, then at the screen...")
+_ABOUT_TO_SPEAK = msg("tui.buddy.thinking.about_to_speak", fallback="💭 {name} is about to say something...")
+
+# Shown while an answer to a pet is being written; one is picked at random.
+THINKING_LINES = (_TILTS_HEAD, _CHOOSES_WORDS, _GLANCES, _ABOUT_TO_SPEAK)
+
+__all__ = ["BUDDY_TITLE", "THINKING_LINES"]

chrys/app/tui/buddy_reply.py

@@ -0,0 +1,86 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Petting the buddy from any TUI surface: a thinking toast now, its answer when the model has one."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import random
+from typing import TYPE_CHECKING
+
+from chrys.app.features.buddy.replies import pet_reply, reply_gate
+from chrys.app.tui.buddy_messages import THINKING_LINES
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from chrys.app.features.buddy.model import Buddy
+    from chrys.foundation.i18n import MessageRef
+
+logger = logging.getLogger(__name__)
+
+_THINKING_TOAST_SECONDS = 5
+_ANSWER_TOAST_SECONDS = 10
+
+
+class PetReplyFlow:
+    """One surface's share of the process-wide reply gate, and the task answering through it."""
+
+    def __init__(self, toast: Callable[[MessageRef | str, float], None], *, on_answered: Callable[[], None]) -> None:
+        self._toast = toast
+        self._on_answered = on_answered
+        self._task: asyncio.Task[None] | None = None
+        self._holds_gate = False
+
+    @property
+    def task(self) -> asyncio.Task[None] | None:
+        """The answer being waited for, if any."""
+        return self._task
+
+    @property
+    def answering(self) -> bool:
+        """Whether an answer is on its way, from here or anywhere else."""
+        return self._task is not None or reply_gate.locked()
+
+    def start(self, buddy: Buddy) -> bool:
+        """Ask *buddy* for an answer. False when one is already on its way, from here or anywhere else."""
+        if not reply_gate.acquire(blocking=False):
+            return False
+        self._holds_gate = True
+        try:
+            self._toast(random.choice(THINKING_LINES).bind(name=buddy.display_name), _THINKING_TOAST_SECONDS)  # noqa: S311
+            self._task = asyncio.create_task(self._answer(buddy))
+        except BaseException:
+            self._release_gate()
+            raise
+        return True
+
+    async def _answer(self, buddy: Buddy) -> None:
+        try:
+            self._toast(await pet_reply(buddy), _ANSWER_TOAST_SECONDS)
+            self._on_answered()
+        except Exception:
+            # Nobody awaits this task, and a surface that went away mid-answer is not worth a traceback.
+            logger.debug("Buddy answer could not be shown", exc_info=True)
+        finally:
+            self._task = None
+            self._release_gate()
+
+    async def shutdown(self) -> None:
+        """Stop waiting for the answer."""
+        task, self._task = self._task, None
+        if task is not None and not task.done():
+            task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+        # A task cancelled before its first step never reaches its own cleanup. A new answer that was
+        # started while the old one was being awaited holds the gate in its own right.
+        if self._task is None:
+            self._release_gate()
+
+    def _release_gate(self) -> None:
+        if self._holds_gate:
+            self._holds_gate = False
+            reply_gate.release()