zettcode-tui 0.4.0__py3-none-any.whl

zettcode/tui/core/keymap.py

@@ -0,0 +1,218 @@
+"""Named commands and the contextual key bindings that trigger them."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TypeAlias
+
+from .events import AnyEvent, KeyEvent, TextEvent
+from .host import Host
+
+CommandRun: TypeAlias = Callable[[AnyEvent, Host], bool]
+BindingPriority: TypeAlias = str
+
+_PRIORITIES = ("capture", "bubble")
+_SEPARATORS = re.compile(r"[-+\s]+")
+
+
+def normalize_key(value: str) -> str:
+    """Fold every common spelling of a key into one canonical name."""
+    return _SEPARATORS.sub("_", value.strip().lower())
+
+
+def key_id(event: KeyEvent) -> str:
+    """Return the binding name for a key event, including its modifiers.
+
+    Args:
+        event: Named key press; a modifier already folded into ``key`` is not
+            repeated in the returned name.
+    """
+    name = normalize_key(event.key)
+    prefixes = [
+        modifier
+        for modifier, active in (
+            ("ctrl", event.control),
+            ("alt", event.alt),
+            ("shift", event.shift),
+            ("meta", event.meta),
+        )
+        if active and not name.startswith(f"{modifier}_")
+    ]
+    return "_".join([*prefixes, name]) if prefixes else name
+
+
+def event_key(event: AnyEvent) -> str | None:
+    """Return the binding name an event resolves to, if it can be bound.
+
+    Args:
+        event: Any input event. A terminal delivers a printable character as
+            text rather than as a named key, so a binding such as ``"q"`` has to
+            be matched from that path as well; only single-character text
+            qualifies, which keeps a paste from tripping a binding.
+    """
+    if isinstance(event, KeyEvent):
+        return key_id(event)
+    if isinstance(event, TextEvent) and len(event.text) == 1:
+        return normalize_key(event.text)
+    return None
+
+
+@dataclass(frozen=True, slots=True)
+class Command:
+    """One named action a keymap or a command palette can invoke.
+
+    Attributes:
+        name: Unique lookup key, e.g. ``"interrupt"``.
+        run: Receives the event and the host; returns whether it handled it.
+        description: Human-readable text for a palette or a help screen.
+    """
+
+    name: str
+    run: CommandRun
+    description: str = ""
+
+
+class CommandRegistry:
+    """Look up commands by name and run them against the live host."""
+
+    def __init__(self) -> None:
+        """Start with no registered commands."""
+        self._commands: dict[str, Command] = {}
+
+    def register(self, command: Command) -> Command:
+        """Add or replace a command and return it."""
+        if not command.name:
+            raise ValueError("Command name cannot be empty")
+        self._commands[command.name] = command
+        return command
+
+    def add(self, name: str, run: CommandRun, *, description: str = "") -> Command:
+        """Build a command from a name and a run function, then register it.
+
+        Args:
+            name: Lookup key; an existing command with the same name is replaced.
+            run: Receives the event and the host, and reports whether it handled
+                the event.
+            description: Human-readable text for a palette or a help screen.
+        """
+        return self.register(Command(name, run, description))
+
+    def get(self, name: str) -> Command | None:
+        """Return a command by name, or None when it is not registered."""
+        return self._commands.get(name)
+
+    @property
+    def names(self) -> tuple[str, ...]:
+        """Return every registered command name, sorted."""
+        return tuple(sorted(self._commands))
+
+    def run(self, name: str, event: AnyEvent, host: Host) -> bool:
+        """Run one command by name, reporting whether it handled the event."""
+        command = self._commands.get(name)
+        if command is None:
+            return False
+        return bool(command.run(event, host))
+
+
+@dataclass(frozen=True, slots=True)
+class Binding:
+    """One key-to-command mapping, optionally limited to a live context.
+
+    Attributes:
+        command: Name resolved through the command registry.
+        priority: ``"capture"`` runs before the widget tree sees the event,
+            ``"bubble"`` only after the focused widget declines it.
+        when: Predicate re-checked on every matching key; ``None`` always allows.
+        description: Human-readable text for a palette or a help screen.
+    """
+
+    command: str
+    priority: BindingPriority = "bubble"
+    when: Callable[[], bool] | None = None
+    description: str = ""
+
+    def matches(self) -> bool:
+        """Return whether the binding's predicate currently allows it."""
+        return self.when is None or self.when()
+
+
+class Keymap:
+    """Contextual bindings split into capture and bubble priorities.
+
+    Capture bindings run before the widget tree sees the event, so an
+    application can reserve keys such as ``ctrl_c``. Bubble bindings run only
+    after the focused widget declines the event, which lets a composer keep
+    keys like ``tab`` for completion.
+    """
+
+    def __init__(self) -> None:
+        """Start with no bindings."""
+        self._bindings: dict[str, list[Binding]] = {}
+
+    def bind(
+        self,
+        key: str,
+        command: str,
+        *,
+        when: Callable[[], bool] | None = None,
+        priority: BindingPriority = "bubble",
+        description: str = "",
+    ) -> Binding:
+        """Bind a key spelling to a command at one priority.
+
+        Args:
+            key: Any spelling ``normalize_key`` folds, e.g. ``"Ctrl-C"``.
+            command: Name looked up in the command registry when the key fires.
+            when: Extra predicate sampled on every key press; the binding is
+                skipped while it returns False.
+            priority: ``"capture"`` or ``"bubble"``.
+            description: Human-readable text for a palette or a help screen.
+
+        Returns:
+            The stored binding, so callers can keep it for a later unbind.
+        """
+        if priority not in _PRIORITIES:
+            raise ValueError(f"Unknown binding priority: {priority!r}")
+        if not command:
+            raise ValueError("Binding command cannot be empty")
+        binding = Binding(command, priority, when, description)
+        self._bindings.setdefault(normalize_key(key), []).append(binding)
+        return binding
+
+    def unbind(self, key: str, command: str | None = None) -> int:
+        """Remove bindings for one key and return how many were dropped.
+
+        Args:
+            key: Any spelling ``normalize_key`` folds.
+            command: Only drop the binding that names this command; ``None``
+                removes every binding registered for the key.
+        """
+        name = normalize_key(key)
+        existing = self._bindings.get(name)
+        if not existing:
+            return 0
+        if command is None:
+            self._bindings.pop(name, None)
+            return len(existing)
+        kept = [binding for binding in existing if binding.command != command]
+        if kept:
+            self._bindings[name] = kept
+        else:
+            self._bindings.pop(name, None)
+        return len(existing) - len(kept)
+
+    def bindings_for(self, key: str) -> tuple[Binding, ...]:
+        """Return the bindings registered for one key spelling, in order."""
+        return tuple(self._bindings.get(normalize_key(key), ()))
+
+    def resolve(self, event: AnyEvent, *, priority: BindingPriority = "bubble") -> str | None:
+        """Return the first matching command name, if any binding applies."""
+        name = event_key(event)
+        if name is None:
+            return None
+        for binding in self._bindings.get(name, ()):
+            if binding.priority == priority and binding.matches():
+                return binding.command
+        return None

zettcode/tui/core/scheduler.py

@@ -0,0 +1,105 @@
+"""Frame scheduling that keeps animation cost inside a fixed budget."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from time import monotonic
+
+
+class Scheduler:
+    """Decide when the application should paint its next frame.
+
+    Repaints are requested explicitly, while animations run on a bounded
+    interval so a busy widget cannot drive the loop at full speed.
+    """
+
+    def __init__(self, *, max_fps: float = 120.0, clock: Callable[[], float] = monotonic) -> None:
+        """Configure the frame budget and the clock used to time frames.
+
+        Args:
+            max_fps: Ceiling for animated frames per second; must be positive.
+            clock: Monotonic time source, injectable so tests can step time.
+        """
+        if max_fps <= 0:
+            raise ValueError("max_fps must be positive")
+        self.max_fps = max_fps
+        self.interval = 1.0 / max_fps
+        self.clock = clock
+        self.on_request: Callable[[], None] | None = None
+        self._last_frame = float("-inf")
+        self._dirty = True
+        #: Whether the frame the last :meth:`poll` returned was asked for, as opposed to
+        #: falling due on an animation's interval alone.
+        self.requested = True
+        self._animations: set[str] = set()
+
+    @property
+    def animating(self) -> bool:
+        """Return whether any animation token is registered."""
+        return bool(self._animations)
+
+    @property
+    def pending(self) -> bool:
+        """Return whether a repaint has been requested and not yet taken."""
+        return self._dirty
+
+    @property
+    def animations(self) -> tuple[str, ...]:
+        """Return the registered animation tokens, sorted."""
+        return tuple(sorted(self._animations))
+
+    def request_repaint(self) -> None:
+        """Mark the frame as stale even if no animation is running."""
+        self._dirty = True
+        self._notify()
+
+    def animate(self, token: str, *, active: bool = True) -> None:
+        """Register or release one animation token.
+
+        Args:
+            token: Stable identity for one animation source, e.g.
+                ``f"spinner:{id(self)}"``; registering the same token twice is
+                harmless because the set collapses duplicates.
+            active: ``True`` keeps the frame loop alive for this token, ``False``
+                releases it without disturbing any other animation.
+        """
+        if not token:
+            raise ValueError("Animation token cannot be empty")
+        if active:
+            self._animations.add(token)
+            self._notify()
+        else:
+            self._animations.discard(token)
+
+    def poll(self, *, now: float | None = None) -> bool:
+        """Return whether a frame is due, recording it as painted.
+
+        Args:
+            now: Overrides the clock; tests use it to pin the frame time.
+        """
+        moment = self.clock() if now is None else now
+        if not self._dirty:
+            if not self._animations or moment - self._last_frame < self.interval:
+                return False
+        self.requested = self._dirty
+        self._dirty = False
+        self._last_frame = moment
+        return True
+
+    def delay(self, *, now: float | None = None) -> float | None:
+        """Return seconds until the next frame, or None when fully idle.
+
+        Args:
+            now: Overrides the clock, matching ``poll``.
+        """
+        moment = self.clock() if now is None else now
+        if self._dirty:
+            return 0.0
+        if not self._animations:
+            return None
+        return max(0.0, self.interval - (moment - self._last_frame))
+
+    def _notify(self) -> None:
+        """Wake a sleeping driver, which would otherwise miss a late request."""
+        if self.on_request is not None:
+            self.on_request()

zettcode/tui/core/screen.py

@@ -0,0 +1,80 @@
+"""Layers of the application: a widget subtree plus its focus policy."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+
+from .widget import Widget
+
+
+@dataclass(slots=True)
+class Screen:
+    """One stacked layer of the application.
+
+    Attributes:
+        widget: Root of this layer's subtree.
+        name: Debug label such as ``"approval"``; the base layer is ``"main"``.
+        modal: Block input from every layer below this one.
+        interactive: Whether the layer may receive input at all. A paint-only
+            layer (a toast, a status flash) still draws over the shell but lets
+            clicks, wheel, and keys fall through to the layer below.
+        remembered_focus: Focus to restore when this layer is uncovered again;
+            the app writes it when a new layer is pushed on top.
+    """
+
+    widget: Widget
+    name: str = ""
+    modal: bool = False
+    interactive: bool = True
+    remembered_focus: Widget | None = field(default=None)
+
+
+class ScreenStack:
+    """The ordered screen layers, oldest first and topmost last."""
+
+    def __init__(self, base: Screen) -> None:
+        """Start a stack whose base layer can never be popped.
+
+        Args:
+            base: The permanent bottom layer, named ``"main"`` by ``TuiApp``.
+        """
+        self._screens: list[Screen] = [base]
+
+    def __iter__(self) -> Iterator[Screen]:
+        """Iterate from the oldest layer to the newest."""
+        return iter(self._screens)
+
+    def __reversed__(self) -> Iterator[Screen]:
+        """Iterate from the newest layer to the oldest."""
+        return reversed(self._screens)
+
+    def __len__(self) -> int:
+        """Return the number of stacked layers."""
+        return len(self._screens)
+
+    @property
+    def base(self) -> Screen:
+        """Return the permanent bottom layer."""
+        return self._screens[0]
+
+    @property
+    def top(self) -> Screen:
+        """Return the layer that currently receives input."""
+        return self._screens[-1]
+
+    def push(self, screen: Screen) -> Screen:
+        """Add a layer on top and return it.
+
+        Args:
+            screen: The new topmost layer; it becomes the only one that can
+                receive input until it is popped or a modal layer covers it.
+        """
+        self._screens.append(screen)
+        return screen
+
+    def pop(self) -> Screen | None:
+        """Remove the topmost layer, refusing to drop the base screen."""
+        if len(self._screens) == 1:
+            return None
+        return self._screens.pop()

zettcode/tui/core/theme.py

@@ -0,0 +1,248 @@
+"""Semantic color tokens that widgets render against."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..render.code import CodeTheme
+from ..render.color import blend, parse_hex
+
+#: How much of a diff line's colour is mixed into the page to make the fill behind that line.
+DIFF_FILL_SHARE = 0.16
+
+
+@dataclass(frozen=True, slots=True)
+class ToolTheme:
+    """The colour a tool row is painted with, by what the tool did.
+
+    The built-in palettes keep to a few hues, the way editors keep their tool and
+    status colours to a few: a soft lavender for what the agent goes looking with
+    (a glob, a grep, a picture, a command, the plan), a warm yellow for reading one
+    file (and for ``read_skill``, which reads a file too), orange for what it writes, red for what
+    it deletes, teal for a delegated child agent, and mauve for talking to another session. More
+    hues than that read as noise in a transcript that is mostly tool rows, so reading is the one
+    addition: those rows are the most of any, and the warm yellow says "this is a file I read" where
+    the lavender says "this is the agent doing something". That yellow is also the warning colour in the bundled palettes whose yellow and orange differ (every one but
+    rose-pine-dawn, which the anti-collision step moved), and the overlap is accepted rather than hidden: it is the one warm hue no tool
+    row claims, a skipped row carries a glyph of its own, and the alternative — a step toward the write
+    orange — put reads within a few ΔE of writes, which are on screen just as often. The two built-in
+    palettes take their tool hues from the Catppuccin family rather than from their page (``dark``'s read
+    is mocha's yellow, ``light``'s a shade of its own beside its warning), which is how their other tool
+    colours work too. Writing is orange and not green because green is the
+    colour of an added line: the heading of an edit sits on the line above its diff, and the same
+    green on both made the heading read as one more added line (and a yellow one, close to the
+    green in hue and weight, still read as its neighbour). The roles are separate so a theme
+    file can pull them apart without touching any code. A tool the palette has never heard of, and
+    any role left unset, falls back to :attr:`Theme.accent`.
+
+    Attributes:
+        read: Reading one file, the least surprising action.
+        search: Finding paths or matches across the workspace.
+        image: Looking at a picture rather than text.
+        write: Creating a file or editing one in place.
+        delete: Removing a path; deliberately the same hue as a failure.
+        shell: Running a command in the workspace.
+        plan: Recording the task list.
+        subagent: Delegating work to an isolated child agent, which is its own
+            family rather than a file operation.
+        message: Talking to another session: ``send_message`` and ``list_sessions``, and the
+            header of a message another session's agent sent. One hue for both directions, so a
+            conversation between sessions reads as one thing.
+        web_search: A search the endpoint ran on the model's behalf (``web_search``). Its own
+            role rather than ``search``: it leaves the workspace for the open web, and a theme
+            may say so. Spelled ``web-search`` in a theme file's ``[tools]`` table.
+        ask_user: A question the model put to the reader (``ask_user``). Its own role rather than
+            ``plan``: it is the one row that waits for a person, and a theme may colour it apart.
+            Spelled ``ask-user`` in a theme file's ``[tools]`` table.
+    """
+
+    read: str = "#f9e2af"
+    search: str = "#b4befe"
+    image: str = "#b4befe"
+    write: str = "#ef9a62"
+    delete: str = "#e67e80"
+    shell: str = "#b4befe"
+    plan: str = "#b4befe"
+    subagent: str = "#94e2d5"
+    message: str = "#cba6f7"
+    web_search: str = "#b4befe"
+    ask_user: str = "#b4befe"
+
+
+@dataclass(frozen=True, slots=True)
+class Theme:
+    """One named palette expressed as semantic roles, never raw hex.
+
+    Widgets read roles such as ``accent`` or ``muted`` so a new palette is a
+    data change rather than a search-and-replace through every component.
+
+    The built-in palettes leave the page to the terminal and follow
+    Everforest's green-leaning accents
+    (``#A7C080`` green, ``#83C092`` aqua, ``#DBBC7F`` yellow, ``#E67E80`` red)
+    over the neutral greys, so a transcript can tell reasoning from tool output
+    by hue instead of drawing every row in one green.
+
+    Attributes:
+        name: Palette key used by ``/theme`` and by ``base =`` in a theme file.
+        background: Page fill behind everything; ``None`` — what both built-in
+            palettes use — leaves the terminal's own background in place, so the
+            shell blends into the profile it was started in.
+        surface: Raised panel fill.
+        surface_alt: Fill shared by the composer and submitted user messages.
+        surface_side: Fill of a side question, which is answered on screen and
+            deliberately kept out of the conversation. It stays as quiet as any
+            other background — the muted body colour has to remain readable on
+            it — but it leans a different way from the green-toned neutrals, a
+            soft slate, so an aside reads as a note beside the conversation
+            rather than as one of its turns.
+        surface_peer: Fill of a message that crossed between two sessions, in either direction. It
+            is drawn like the reader's own message (the arrow, the same text column), so only its
+            background says it is not the reader's. It is as light as ``surface_alt`` and only leans another way —
+            Catppuccin Mocha's lavender-grey ``surface0`` in the dark palette, a pale sage in the light one —
+            so it reads as a neighbour of the reader's message rather than as a hole or a banner next to it.
+        text: Body text.
+        muted: Lowest-emphasis text (hints, timestamps, disabled rows).
+        subtle: Secondary body text that must stay readable, such as a reasoning
+            body or an unchanged diff line.
+        accent: Primary highlight: running rows, list markers, the selection
+            bullet in a tool row.
+        accent_bright: Emphasised accent: the composer prompt, link targets,
+            hunk headers.
+        warning: Warning state, currently the warning toast.
+        error: Failure state: failed tool rows and the error toast.
+        diff_added: A line a change adds, and the ``+N`` beside the file. ``None`` — what both built-in
+            palettes use — means :attr:`accent`, so a theme that changes the accent changes the diff
+            with it; set it to colour additions on their own. Read it through :attr:`addition`.
+        diff_removed: A line a change removes, and the ``-N`` beside the file. ``None`` means
+            :attr:`error`. Read it through :attr:`deletion`.
+        diff_added_fill: The band behind an added line of an edit. ``None`` mixes :attr:`addition` into the page
+            (:attr:`background`, or :attr:`surface` when the page is the terminal's), so the band follows the
+            palette. Read it through :attr:`addition_fill`.
+        diff_removed_fill: The same for a removed line; read it through :attr:`deletion_fill`.
+        border: Frame glyphs and separators.
+        focus: Focus ring colour; reserved, no built-in widget draws a ring yet.
+        selection: Background of a selected or emphasised cell, used by list
+            rows and diff segments; text selection uses reverse video instead.
+        tools: Per-tool palette for agent rows; see :class:`ToolTheme`.
+        code: Per-token palette for fenced code blocks.
+    """
+
+    name: str = "dark"
+    background: str | None = None
+    surface: str = "#2d353b"
+    surface_alt: str = "#343f44"
+    surface_side: str = "#393a44"
+    surface_peer: str = "#313244"
+    text: str = "#f2f5f3"
+    muted: str = "#7a8478"
+    subtle: str = "#9da9a0"
+    accent: str = "#a7c080"
+    accent_bright: str = "#83c092"
+    warning: str = "#dbbc7f"
+    error: str = "#e67e80"
+    diff_added: str | None = None
+    diff_removed: str | None = None
+    diff_added_fill: str | None = None
+    diff_removed_fill: str | None = None
+    border: str = "#3d484d"
+    focus: str = "#83c092"
+    selection: str = "#4a5f52"
+    tools: ToolTheme = ToolTheme()
+    code: CodeTheme = CodeTheme()
+
+    @property
+    def addition_fill(self) -> str:
+        """Return the fill behind an added line: ``diff_added_fill`` if set, else the addition colour mixed into the page."""
+        return self.diff_added_fill or blend(self.background or self.surface, self.addition, DIFF_FILL_SHARE)
+
+    @property
+    def deletion_fill(self) -> str:
+        """Return the fill behind a removed line: ``diff_removed_fill`` if set, else the deletion colour mixed in."""
+        return self.diff_removed_fill or blend(self.background or self.surface, self.deletion, DIFF_FILL_SHARE)
+
+    @property
+    def addition(self) -> str:
+        """Return the colour of an added line: ``diff_added`` if set, else the accent."""
+        return self.diff_added or self.accent
+
+    @property
+    def deletion(self) -> str:
+        """Return the colour of a removed line: ``diff_removed`` if set, else the error colour."""
+        return self.diff_removed or self.error
+
+
+DARK = Theme()
+
+LIGHT = Theme(
+    name="light",
+    background=None,
+    surface="#ffffff",
+    surface_alt="#eceeec",
+    surface_side="#e5e6ee",
+    surface_peer="#e1ebe4",
+    text="#1b211d",
+    muted="#68736c",
+    subtle="#4c554e",
+    accent="#5f7a10",
+    accent_bright="#237a5c",
+    warning="#8a6314",
+    error="#b23b30",
+    border="#bdc3af",
+    focus="#237a5c",
+    selection="#cfe4d6",
+    tools=ToolTheme(
+        read="#7d5f10",
+        search="#5b3fa8",
+        image="#5b3fa8",
+        write="#b85a14",
+        delete="#b23b30",
+        shell="#5b3fa8",
+        plan="#5b3fa8",
+        subagent="#1e7f76",
+        message="#8a4a9e",
+    ),
+    code=CodeTheme(
+        name="light",
+        inline="#256b3b",
+        text="#1b211d",
+        keyword="#a3234a",
+        string="#2f7a48",
+        comment="#6d766f",
+        number="#8a6314",
+        function="#1f5f8b",
+        builtin="#5b3fa8",
+        operator="#4c554e",
+        punctuator="#4c554e",
+    ),
+)
+
+
+def scheme_named(background: str | None) -> str | None:
+    """Return ``"light"`` or ``"dark"`` for a background colour, or None without one.
+
+    Used to follow the terminal: the luminance of what it says its background is
+    picks the palette, so the shell matches the profile it was started in.
+
+    Args:
+        background: ``#rrggbb`` colour, or None when nothing was reported.
+    """
+    channels = parse_hex(background) if background else None
+    if channels is None:
+        return None
+    red, green, blue = (channel / 255 for channel in channels)
+    luminance = 0.2126 * red + 0.7152 * green + 0.0722 * blue
+    return "light" if luminance > 0.5 else "dark"
+
+
+def theme_named(name: str) -> Theme:
+    """Return the built-in theme registered under a name."""
+    if name == DARK.name:
+        return DARK
+    if name == LIGHT.name:
+        return LIGHT
+    raise ValueError(f"Unknown theme: {name!r}")
+
+
+def theme_names() -> tuple[str, ...]:
+    """Return the built-in palette keys, in the order a picker should list them."""
+    return (DARK.name, LIGHT.name)