zettcode-tui 0.4.0__py3-none-any.whl

zettcode/tui/core/events.py

@@ -0,0 +1,134 @@
+"""Input events consumed by widgets, independent from the agent runtime."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import ClassVar, TypeAlias
+
+from .._compat import StrEnum
+
+
+class EventKind(StrEnum):
+    """The finite set of input a widget can receive."""
+
+    KEY = "key"
+    TEXT = "text"
+    PASTE = "paste"
+    MOUSE = "mouse"
+    RESIZE = "resize"
+    FOCUS = "focus"
+
+
+class MouseAction(StrEnum):
+    """The gesture a mouse event describes."""
+
+    DOWN = "down"
+    UP = "up"
+    MOVE = "move"
+    SCROLL_UP = "scroll_up"
+    SCROLL_DOWN = "scroll_down"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Event:
+    """Base class carrying the modifiers shared by every input event.
+
+    Attributes:
+        shift: Shift was held, where the terminal reports it.
+        alt: Alt was held; a terminal may instead fold this into ``key``.
+        control: Ctrl was held; a terminal may instead fold this into ``key``.
+        meta: Meta was held.
+    """
+
+    shift: bool = False
+    alt: bool = False
+    control: bool = False
+    meta: bool = False
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class KeyEvent(Event):
+    """A named key press, such as ``enter``, ``ctrl_c``, or ``escape``.
+
+    Attributes:
+        key: Canonical key name, already lower-cased; a modifier may be folded
+            into it (``"ctrl_c"``) or reported through the flags above.
+        repeat: The terminal repeated the key while it was held down.
+    """
+
+    kind: ClassVar[EventKind] = EventKind.KEY
+    key: str = ""
+    repeat: bool = False
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TextEvent(Event):
+    """One printable character or grapheme cluster.
+
+    Attributes:
+        text: The printable text, with no newline.
+    """
+
+    kind: ClassVar[EventKind] = EventKind.TEXT
+    text: str = ""
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PasteEvent(Event):
+    """A whole bracketed-paste payload delivered as one event.
+
+    Attributes:
+        text: The pasted payload, newlines included.
+    """
+
+    kind: ClassVar[EventKind] = EventKind.PASTE
+    text: str = ""
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class MouseEvent(Event):
+    """A pointer gesture at an absolute cell coordinate.
+
+    Attributes:
+        x: Column, zero-based from the left edge of the terminal.
+        y: Row, zero-based from the top edge of the terminal.
+        button: Button index reported by the terminal; 0 is the primary button.
+            Wheel events keep the index they arrived with, so read ``action``
+            rather than ``button`` to tell scrolling apart from clicking.
+        action: Gesture this event describes.
+    """
+
+    kind: ClassVar[EventKind] = EventKind.MOUSE
+    x: int = 0
+    y: int = 0
+    button: int = 0
+    action: MouseAction = MouseAction.MOVE
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ResizeEvent(Event):
+    """The terminal changed size to the given cell dimensions.
+
+    Attributes:
+        width: New width in cells.
+        height: New height in cells.
+    """
+
+    kind: ClassVar[EventKind] = EventKind.RESIZE
+    width: int = 0
+    height: int = 0
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class FocusEvent(Event):
+    """The terminal gained or lost focus.
+
+    Attributes:
+        focused: ``True`` when the terminal gained focus.
+    """
+
+    kind: ClassVar[EventKind] = EventKind.FOCUS
+    focused: bool = True
+
+
+AnyEvent: TypeAlias = KeyEvent | TextEvent | PasteEvent | MouseEvent | ResizeEvent | FocusEvent

zettcode/tui/core/focus.py

@@ -0,0 +1,85 @@
+"""Focus ownership and Tab traversal over a widget tree."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from .widget import Widget
+
+
+def walk(widget: Widget) -> Iterator[Widget]:
+    """Yield a widget and its descendants in depth-first paint order.
+
+    Args:
+        widget: Subtree root; it is yielded before its children.
+    """
+    yield widget
+    for child in widget.children:
+        yield from walk(child)
+
+
+class FocusManager:
+    """Track the focused widget and move focus through the tree."""
+
+    def __init__(self) -> None:
+        """Start with nothing focused."""
+        self._focused: Widget | None = None
+
+    @property
+    def focused(self) -> Widget | None:
+        """Return the widget that currently owns focus, if any."""
+        return self._focused
+
+    def focus(self, widget: Widget | None) -> None:
+        """Move focus, running the blur and focus hooks on a real change.
+
+        Args:
+            widget: New focus target, or ``None`` to clear focus. Re-focusing the
+                current widget is a no-op, so the hooks never fire twice.
+        """
+        if widget is self._focused:
+            return
+        previous, self._focused = self._focused, widget
+        if previous is not None:
+            previous.focused = False
+            previous.on_blur()
+        if widget is not None:
+            widget.focused = True
+            widget.on_focus()
+
+    def focusables(self, root: Widget) -> list[Widget]:
+        """Return every Tab-reachable widget under root, in traversal order.
+
+        Args:
+            root: Subtree to scan; the root itself is included when it opts in
+                through ``focusable``.
+        """
+        return [widget for widget in walk(root) if widget.focusable]
+
+    def first(self, root: Widget) -> Widget | None:
+        """Return the first Tab-reachable widget, or the root as a fallback.
+
+        Args:
+            root: Subtree to scan.
+        """
+        candidates = self.focusables(root)
+        return candidates[0] if candidates else root
+
+    def move(self, root: Widget, direction: int = 1) -> Widget | None:
+        """Move focus by one stop, wrapping at either end.
+
+        Args:
+            root: Subtree that defines the Tab scope, usually the top screen.
+            direction: Positive moves forward, negative moves backward. When the
+                current widget is outside the scope, forward starts at the first
+                stop and backward at the last.
+        """
+        candidates = self.focusables(root)
+        if not candidates:
+            return None
+        if self._focused in candidates:
+            index = (candidates.index(self._focused) + direction) % len(candidates)
+        else:
+            index = 0 if direction > 0 else len(candidates) - 1
+        self.focus(candidates[index])
+        return candidates[index]

zettcode/tui/core/geometry.py

@@ -0,0 +1,212 @@
+"""Geometry primitives shared by layout and widgets."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Point:
+    """One absolute terminal coordinate measured in cells."""
+
+    x: int = 0
+    y: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class Size:
+    """A width and height measured in terminal cells."""
+
+    width: int = 0
+    height: int = 0
+
+    @property
+    def area(self) -> int:
+        """Return the number of cells, treating a negative extent as empty."""
+        return max(0, self.width) * max(0, self.height)
+
+
+@dataclass(frozen=True, slots=True)
+class EdgeInsets:
+    """Spacing applied to the four sides of a rectangle."""
+
+    top: int = 0
+    right: int = 0
+    bottom: int = 0
+    left: int = 0
+
+    @classmethod
+    def all(cls, value: int = 0) -> EdgeInsets:
+        """Return equal spacing on every side.
+
+        Args:
+            value: Cells applied to top, right, bottom, and left.
+        """
+        return cls(value, value, value, value)
+
+    @classmethod
+    def symmetric(cls, *, vertical: int = 0, horizontal: int = 0) -> EdgeInsets:
+        """Return spacing mirrored across both axes.
+
+        Args:
+            vertical: Cells for the top and bottom together.
+            horizontal: Cells for the left and right together.
+        """
+        return cls(vertical, horizontal, vertical, horizontal)
+
+    @property
+    def vertical(self) -> int:
+        """Return the top and bottom spacing combined."""
+        return self.top + self.bottom
+
+    @property
+    def horizontal(self) -> int:
+        """Return the left and right spacing combined."""
+        return self.left + self.right
+
+
+@dataclass(frozen=True, slots=True)
+class Rect:
+    """An absolute rectangle clamped to the terminal canvas."""
+
+    x: int
+    y: int
+    width: int
+    height: int
+
+    @property
+    def right(self) -> int:
+        """Return the exclusive right edge."""
+        return self.x + self.width
+
+    @property
+    def bottom(self) -> int:
+        """Return the exclusive bottom edge."""
+        return self.y + self.height
+
+    @property
+    def size(self) -> Size:
+        """Return the rectangle's extent as a Size."""
+        return Size(self.width, self.height)
+
+    @property
+    def empty(self) -> bool:
+        """Return whether the rectangle covers no cells."""
+        return self.width <= 0 or self.height <= 0
+
+    def contains(self, x: int, y: int) -> bool:
+        """Return whether one cell falls inside this rectangle."""
+        return self.x <= x < self.right and self.y <= y < self.bottom
+
+    def inset(self, edges: EdgeInsets | int) -> Rect:
+        """Shrink the rectangle by the given spacing, never below empty.
+
+        Args:
+            edges: Spacing removed on each side; an int is applied to all four,
+                and the result is clamped so width and height never go negative.
+        """
+        if isinstance(edges, int):
+            edges = EdgeInsets.all(edges)
+        return Rect(
+            self.x + edges.left,
+            self.y + edges.top,
+            max(0, self.width - edges.horizontal),
+            max(0, self.height - edges.vertical),
+        )
+
+    def translate(self, dx: int, dy: int) -> Rect:
+        """Move the rectangle without resizing it.
+
+        Args:
+            dx: Cells to move right; negative moves left.
+            dy: Cells to move down; negative moves up.
+        """
+        return Rect(self.x + dx, self.y + dy, self.width, self.height)
+
+    def intersection(self, other: Rect) -> Rect:
+        """Return the overlapping area, or an empty rectangle."""
+        x = max(self.x, other.x)
+        y = max(self.y, other.y)
+        width = max(0, min(self.right, other.right) - x)
+        height = max(0, min(self.bottom, other.bottom) - y)
+        return Rect(x, y, width, height)
+
+    def union(self, other: Rect) -> Rect:
+        """Return the smallest rectangle covering both inputs."""
+        if self.empty:
+            return other
+        if other.empty:
+            return self
+        x = min(self.x, other.x)
+        y = min(self.y, other.y)
+        return Rect(x, y, max(self.right, other.right) - x, max(self.bottom, other.bottom) - y)
+
+
+@dataclass(frozen=True, slots=True)
+class Constraints:
+    """The size range a widget may choose from during measurement."""
+
+    min_width: int = 0
+    max_width: int | None = None
+    min_height: int = 0
+    max_height: int | None = None
+
+    @classmethod
+    def tight(cls, size: Size) -> Constraints:
+        """Return constraints that force exactly one size.
+
+        Args:
+            size: The only size a child may report.
+        """
+        return cls(size.width, size.width, size.height, size.height)
+
+    @classmethod
+    def loose(cls, size: Size) -> Constraints:
+        """Return constraints that allow anything up to one size.
+
+        Args:
+            size: Upper bound per axis; both minimums stay at zero.
+        """
+        return cls(0, size.width, 0, size.height)
+
+    @classmethod
+    def unbounded(cls) -> Constraints:
+        """Return constraints with no upper bound."""
+        return cls()
+
+    def constrain(self, size: Size) -> Size:
+        """Clamp a desired size into the allowed range.
+
+        Args:
+            size: Size a child asked for; each axis is clamped independently.
+        """
+        return Size(
+            self._clamp(size.width, self.min_width, self.max_width),
+            self._clamp(size.height, self.min_height, self.max_height),
+        )
+
+    def deflate(self, edges: EdgeInsets) -> Constraints:
+        """Remove space reserved for padding from every bound.
+
+        Args:
+            edges: Space taken by a padding or border, subtracted from the
+                minimum and the maximum on each axis; bounds stop at zero and an
+                unbounded maximum stays unbounded.
+        """
+        return Constraints(
+            max(0, self.min_width - edges.horizontal),
+            self._shrink(self.max_width, edges.horizontal),
+            max(0, self.min_height - edges.vertical),
+            self._shrink(self.max_height, edges.vertical),
+        )
+
+    @staticmethod
+    def _clamp(value: int, minimum: int, maximum: int | None) -> int:
+        """Clamp a value into ``minimum..maximum``, where None means unbounded."""
+        value = max(value, minimum)
+        return value if maximum is None else min(value, max(minimum, maximum))
+
+    @staticmethod
+    def _shrink(value: int | None, amount: int) -> int | None:
+        """Subtract an amount from an optional upper bound."""
+        return None if value is None else max(0, value - amount)

zettcode/tui/core/host.py

@@ -0,0 +1,66 @@
+"""Services a running widget tree exposes to the widgets inside it."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .widget import Widget
+
+
+class Host(ABC):
+    """The application-side capabilities widgets may call.
+
+    Widgets never reach for the terminal directly. Everything they need from
+    the outside world, from moving focus to requesting a repaint, arrives
+    through this interface so the same tree can run headless in tests.
+
+    This is an abstract base class rather than a protocol: an implementation is
+    expected to subclass it and answer every method, which is what `TuiApp`
+    does, and what keeps a missing implementation a loud error instead of a
+    class that merely looks compatible.
+    """
+
+    @abstractmethod
+    def focus(self, widget: Widget | None) -> None:
+        """Move keyboard focus to a widget, or clear it with ``None``."""
+
+    @abstractmethod
+    def focused_widget(self) -> Widget | None:
+        """Return the widget that currently receives keyboard input."""
+
+    @abstractmethod
+    def invalidate(self) -> None:
+        """Ask for a repaint on the next frame."""
+
+    @abstractmethod
+    def request_layout(self) -> None:
+        """Ask for a fresh measure before the next paint."""
+
+    @abstractmethod
+    def copy(self, text: str) -> None:
+        """Place text on the clipboard."""
+
+    def screen_selection_text(self) -> str:
+        """Return the text a drag has marked on the frame, if any.
+
+        The default is nothing: a host that does not select the frame itself
+        still answers, so a widget can ask without knowing which host it has.
+        """
+        return ""
+
+    def clear_screen_selection(self) -> None:
+        """Drop the frame selection a drag left behind, if the host keeps one.
+
+        The default does nothing, which suits a host that never had one.
+        """
+        return None
+
+    @abstractmethod
+    def refresh(self) -> None:
+        """Repaint from scratch, discarding any retained frame."""
+
+    @abstractmethod
+    def exit(self) -> None:
+        """Stop the application loop."""