zettcode-tui 0.4.0__py3-none-any.whl

zettcode/tui/input/reader.py

@@ -0,0 +1,147 @@
+"""Asynchronous bridge from the TTY file descriptor into decoded events."""
+
+from __future__ import annotations
+
+import asyncio
+import signal
+import threading
+from collections.abc import Callable
+from typing import Any
+
+from ..terminal import Terminal
+from .decoder import InputDecoder
+from .events import EventType, InputEvent
+
+#: How often a platform without a resize signal asks the console for its size.
+RESIZE_POLL_SECONDS = 0.25
+
+#: How long the reader thread waits for input before checking whether to stop.
+POLL_SECONDS = 0.1
+
+
+class AsyncInput:
+    """Publish decoded terminal input into one application queue."""
+
+    def __init__(self, terminal: Terminal, publish: Callable[[InputEvent], None]) -> None:
+        """Store the terminal, the publish sink, and a fresh decoder.
+
+        Args:
+            terminal: Owns the input file descriptor.
+            publish: Called synchronously on the event loop for every decoded
+                event, including the synthetic resize.
+        """
+        self.terminal = terminal
+        self.publish = publish
+        self.decoder = InputDecoder()
+        self.loop: asyncio.AbstractEventLoop | None = None
+        self._previous_resize_handler: Any = None
+        self._escape_handle: asyncio.TimerHandle | None = None
+        self._thread: threading.Thread | None = None
+        self._stopping = threading.Event()
+        self._resize_handle: asyncio.TimerHandle | None = None
+        self._size: tuple[int, int] | None = None
+
+    def start(self) -> None:
+        """Attach the reader and the resize handler to the running loop."""
+        self.loop = asyncio.get_running_loop()
+        if self.terminal.console.watches_descriptor:
+            self.loop.add_reader(self.terminal.input_fd, self._read_ready)
+            if hasattr(signal, "SIGWINCH"):
+                self._previous_resize_handler = signal.getsignal(signal.SIGWINCH)
+                self.loop.add_signal_handler(signal.SIGWINCH, self._resize)
+            return
+        # A Windows console handle is not something the loop can watch, so a
+        # thread does the blocking read and hands chunks back to the loop; with
+        # no SIGWINCH either, the size is polled on the same loop.
+        self._stopping.clear()
+        self._thread = threading.Thread(target=self._pump, name="zettcode-input", daemon=True)
+        self._thread.start()
+        self._size = self.terminal.size
+        self._resize_handle = self.loop.call_later(RESIZE_POLL_SECONDS, self._poll_resize)
+
+    def close(self) -> None:
+        """Detach every loop hook and restore the previous resize handler."""
+        if self.loop is None:
+            return
+        if self.terminal.console.watches_descriptor:
+            self.loop.remove_reader(self.terminal.input_fd)
+        if self._thread is not None:
+            self._stopping.set()
+            self._thread.join(timeout=1.0)
+            self._thread = None
+        if self._resize_handle is not None:
+            self._resize_handle.cancel()
+            self._resize_handle = None
+        if hasattr(signal, "SIGWINCH") and self.terminal.console.watches_descriptor:
+            self.loop.remove_signal_handler(signal.SIGWINCH)
+        if self._escape_handle is not None:
+            self._escape_handle.cancel()
+            self._escape_handle = None
+        if (
+            self.terminal.console.watches_descriptor
+            and hasattr(signal, "SIGWINCH")
+            and callable(self._previous_resize_handler)
+        ):
+            signal.signal(signal.SIGWINCH, self._previous_resize_handler)
+        self.loop = None
+
+    def _read_ready(self) -> None:
+        """Read one chunk on the loop thread, when the loop watches the descriptor."""
+        try:
+            data = self.terminal.console.read()
+        except OSError:
+            return
+        self._feed(data)
+
+    def _feed(self, data: bytes) -> None:
+        """Publish whatever one chunk decodes, and arm the escape timer."""
+        if self._escape_handle is not None:
+            self._escape_handle.cancel()
+            self._escape_handle = None
+        for event in self.decoder.feed(data):
+            self.publish(event)
+        # A trailing ESC may still be growing into a control sequence, so give
+        # it a moment (30 ms, the usual terminal timeout) before reporting the
+        # Escape key itself.
+        if self.decoder.buffer.startswith(b"\x1b") and self.loop is not None:
+            self._escape_handle = self.loop.call_later(0.03, self._flush_escape)
+
+    def _pump(self) -> None:
+        """Read the console from a thread and hand each chunk to the loop."""
+        while not self._stopping.is_set():
+            try:
+                if not self.terminal.console.wait_readable(POLL_SECONDS):
+                    continue
+                data = self.terminal.console.read()
+            except OSError:
+                return
+            if not data:
+                continue
+            loop = self.loop
+            if loop is not None:
+                loop.call_soon_threadsafe(self._feed, data)
+
+    def _poll_resize(self) -> None:
+        """Publish a resize when the console's size changed.
+
+        Windows raises no SIGWINCH, so the loop asks instead of being told; the
+        probe is one console call, cheap enough for the frame interval.
+        """
+        self._resize_handle = None
+        size = self.terminal.size
+        if self._size is not None and size != self._size:
+            self._size = size
+            self.publish(InputEvent(EventType.RESIZE))
+        if self.loop is not None:
+            self._resize_handle = self.loop.call_later(RESIZE_POLL_SECONDS, self._poll_resize)
+
+    def _resize(self) -> None:
+        """Publish the resize the terminal raised through SIGWINCH."""
+        self.publish(InputEvent(EventType.RESIZE))
+
+    def _flush_escape(self) -> None:
+        """Resolve a lone escape that never grew into a control sequence."""
+        self._escape_handle = None
+        # One event per call, so a run of escapes is reported press by press.
+        while (event := self.decoder.flush_escape()) is not None:
+            self.publish(event)

zettcode/tui/layout/__init__.py

@@ -0,0 +1,24 @@
+"""Layout containers: boxes, spacing, anchored overlays, and scrolling."""
+
+from .box import HBox, Slot, VBox
+from .overlay import Anchor, Overlay, OverlaySlot, centered
+from .scroll import LineSource, ScrollView, StaticLines
+from .solver import Track, resolve_tracks
+from .spacing import Border, Padding
+
+__all__ = [
+    "Anchor",
+    "Border",
+    "HBox",
+    "LineSource",
+    "Overlay",
+    "OverlaySlot",
+    "Padding",
+    "ScrollView",
+    "Slot",
+    "StaticLines",
+    "Track",
+    "VBox",
+    "centered",
+    "resolve_tracks",
+]

zettcode/tui/layout/box.py

@@ -0,0 +1,153 @@
+"""Vertical and horizontal box containers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+from ..core.geometry import Constraints, Point, Rect, Size
+from ..core.widget import Widget
+from ..render import Canvas
+from .solver import Track, resolve_tracks
+
+
+@dataclass(frozen=True, slots=True)
+class Slot:
+    """One child of a box, with its own sizing policy on the main axis.
+
+    Attributes:
+        widget: The child laid out in this slot.
+        size: Fixed cell count on the main axis, or a callable receiving the
+            box's extent on the cross axis (the width of a ``VBox``, the height
+            of an ``HBox``) and returning main-axis cells. ``None`` contributes
+            nothing to the fixed budget, leaving the slot to ``flex``.
+        flex: Share of the leftover space; zero means the slot never grows.
+        min_size: Floor applied to the main-axis extent.
+    """
+
+    widget: Widget
+    size: int | Callable[[int], int] | None = None
+    flex: int = 0
+    min_size: int = 0
+
+    def track(self) -> Track:
+        """Describe this slot to the track solver on the main axis."""
+        return Track(self.size, self.flex, self.min_size)
+
+
+class _Box(Widget):
+    """Shared behavior for the two box directions."""
+
+    def __init__(self, slots: Sequence[Slot]) -> None:
+        """Store the slots in paint order."""
+        super().__init__()
+        self.slots = tuple(slots)
+
+    @property
+    def children(self) -> tuple[Widget, ...]:
+        """Expose one child per slot."""
+        return tuple(slot.widget for slot in self.slots)
+
+    @property
+    def _vertical(self) -> bool:
+        """Return whether children stack vertically; subclasses decide."""
+        raise NotImplementedError
+
+    def render(self, canvas: Canvas) -> None:
+        """Paint every child in slot order; the box itself draws nothing."""
+        for slot in self.slots:
+            slot.widget.render(canvas)
+
+    def cursor(self) -> Point | None:
+        """Return the first cursor any child asks for, in slot order."""
+        for slot in self.slots:
+            cursor = slot.widget.cursor()
+            if cursor is not None:
+                return cursor
+        return None
+
+    def _cross_constraints(self, constraints: Constraints) -> Constraints:
+        """Leave the main axis open and bound the cross axis by the parent."""
+        if self._vertical:
+            return Constraints(0, constraints.max_width, 0, None)
+        return Constraints(0, None, 0, constraints.max_height)
+
+    def measure(self, constraints: Constraints) -> Size:
+        """Sum the main-axis sizes and take the largest cross-axis child."""
+        inner = self._cross_constraints(constraints)
+        total = 0
+        widest = 0
+        tallest = 0
+        for slot in self.slots:
+            child = slot.widget.measure(inner)
+            natural = child.height if self._vertical else child.width
+            main = natural if slot.size is None or callable(slot.size) else slot.size
+            total += max(slot.min_size, main)
+            widest = max(widest, child.width)
+            tallest = max(tallest, child.height)
+        size = Size(widest, total) if self._vertical else Size(total, tallest)
+        return constraints.constrain(size)
+
+
+class VBox(_Box):
+    """Stack children top to bottom, sharing leftover height by flex.
+
+    Shape::
+
+        +-------------------+  <- the box's own rectangle
+        | header  (size=1)  |  <- fixed rows keep their height
+        +-------------------+
+        | body    (flex=1)  |  <- flexible rows share what is left
+        |                   |
+        +-------------------+
+        | status  (size=1)  |
+        +-------------------+
+
+    A fixed size may be a callable, which receives the box's *width* — a
+    wrapping child's height depends on the space across, not along. When the
+    fixed rows alone overflow, every row is scaled down proportionally so the
+    box never paints outside its rectangle.
+    """
+
+    @property
+    def _vertical(self) -> bool:
+        """Stack children top to bottom."""
+        return True
+
+    def layout(self, rect: Rect) -> None:
+        """Split the height across the slots and stack them from the top."""
+        super().layout(rect)
+        y = rect.y
+        measured = resolve_tracks(rect.height, [s.track() for s in self.slots], cross=rect.width)
+        for slot, extent in zip(self.slots, measured, strict=True):
+            slot.widget.layout(Rect(rect.x, y, rect.width, extent))
+            y += extent
+
+
+class HBox(_Box):
+    """Place children left to right, sharing leftover width by flex.
+
+    Shape::
+
+        +--------+---------------------------+
+        | left   | right                     |  <- size=8, then flex=1
+        +--------+---------------------------+
+                  ^ the callable form receives the box's *height*
+
+    The horizontal mirror of `VBox`: same track solver, same proportional
+    shrink when the fixed columns do not fit.
+    """
+
+    @property
+    def _vertical(self) -> bool:
+        """Place children left to right."""
+        return False
+
+    def layout(self, rect: Rect) -> None:
+        """Split the width across the slots and place them from the left."""
+        super().layout(rect)
+        x = rect.x
+        measured = resolve_tracks(rect.width, [s.track() for s in self.slots], cross=rect.height)
+        for slot, extent in zip(self.slots, measured, strict=True):
+            slot.widget.layout(Rect(x, rect.y, extent, rect.height))
+            x += extent

zettcode/tui/layout/overlay.py

@@ -0,0 +1,164 @@
+"""Anchored placement of children inside their parent's rectangle."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from ..core.geometry import Constraints, Rect, Size
+from ..core.widget import Widget
+from ..render import Canvas
+
+HORIZONTAL = ("start", "center", "end", "stretch")
+VERTICAL = ("start", "center", "end", "stretch")
+
+
+@dataclass(frozen=True, slots=True)
+class Anchor:
+    """Where a child sits inside its parent's bounds.
+
+    Attributes:
+        horizontal: One of ``HORIZONTAL``. ``"stretch"`` fills the parent width,
+            ``"center"`` and ``"end"`` offset the child inside the parent, and an
+            explicit ``width`` overrides both.
+        vertical: One of ``VERTICAL``, with the same meanings on the other axis.
+        offset_x: Cells added to the resolved left edge, after alignment.
+        offset_y: Cells added to the resolved top edge, after alignment.
+        width: Fixed width in cells; ``None`` uses the child's measured width.
+            Either way the value is capped to the parent's width.
+        height: Fixed height in cells; ``None`` uses the measured height.
+    """
+
+    horizontal: str = "start"
+    vertical: str = "start"
+    offset_x: int = 0
+    offset_y: int = 0
+    width: int | None = None
+    height: int | None = None
+
+    def __post_init__(self) -> None:
+        """Reject anchor names the resolver does not know."""
+        if self.horizontal not in HORIZONTAL:
+            raise ValueError(f"Unknown horizontal anchor: {self.horizontal!r}")
+        if self.vertical not in VERTICAL:
+            raise ValueError(f"Unknown vertical anchor: {self.vertical!r}")
+
+    def resolve(self, bounds: Rect, measured: Size) -> Rect:
+        """Return the child rectangle this anchor picks inside bounds.
+
+        Args:
+            bounds: Parent rectangle the child is placed inside.
+            measured: Size the child asked for; unused on an axis the anchor
+                stretches, and used otherwise when ``width``/``height`` is unset.
+                The result is capped to ``bounds`` either way.
+        """
+        width = self._extent(self.horizontal, bounds.width, measured.width, self.width)
+        height = self._extent(self.vertical, bounds.height, measured.height, self.height)
+        x = bounds.x + self._offset(self.horizontal, bounds.width, width) + self.offset_x
+        y = bounds.y + self._offset(self.vertical, bounds.height, height) + self.offset_y
+        return Rect(x, y, max(0, width), max(0, height))
+
+    @staticmethod
+    def _extent(axis: str, available: int, measured: int, pinned: int | None) -> int:
+        """Return one axis extent, letting an explicit pin beat the anchor.
+
+        Args:
+            axis: Anchor name for this axis.
+            available: Cells the parent offers on the axis.
+            measured: Size the child asked for.
+            pinned: Explicit width or height; ``None`` defers to the anchor, and
+                a pin is still capped to ``available``.
+        """
+        if pinned is not None:
+            return min(pinned, available)
+        if axis == "stretch":
+            return available
+        return min(measured, available)
+
+    @staticmethod
+    def _offset(axis: str, available: int, extent: int) -> int:
+        """Return the leading offset for one axis and placement mode."""
+        if axis == "center":
+            return max(0, (available - extent) // 2)
+        if axis == "end":
+            return max(0, available - extent)
+        return 0
+
+
+@dataclass(frozen=True, slots=True)
+class OverlaySlot:
+    """One anchored child.
+
+    Attributes:
+        widget: The child to place.
+        anchor: Where inside the overlay's rectangle the child goes.
+    """
+
+    widget: Widget
+    anchor: Anchor = Anchor()
+
+
+class Overlay(Widget):
+    """Stack children on top of each other at anchored positions.
+
+    Shape::
+
+        parent rectangle
+        +---------------------------+
+        |          +--------+       |
+        |          | child  |       |  <- measured, then placed by its anchor
+        |          +--------+       |
+        +---------------------------+
+
+    Later slots paint over earlier ones. Each child is measured against the full
+    rectangle first, so an anchor can align by the child's own size; the result
+    is always capped to the parent, and ``"stretch"`` fills it.
+    """
+
+    def __init__(self, slots: Sequence[OverlaySlot]) -> None:
+        """Store the slots in paint order, so later slots sit on top.
+
+        Args:
+            slots: Children to place; each is measured against the full overlay
+                rectangle before its anchor resolves the final position.
+        """
+        super().__init__()
+        self.slots = tuple(slots)
+
+    @property
+    def children(self) -> tuple[Widget, ...]:
+        """Expose the anchored widgets in paint order."""
+        return tuple(slot.widget for slot in self.slots)
+
+    def measure(self, constraints: Constraints) -> Size:
+        """Report the smallest rectangle that fits every child."""
+        widest = 0
+        tallest = 0
+        for slot in self.slots:
+            child = slot.widget.measure(constraints)
+            widest = max(widest, child.width)
+            tallest = max(tallest, child.height)
+        return constraints.constrain(Size(widest, tallest))
+
+    def layout(self, rect: Rect) -> None:
+        """Measure each child, then place it at its anchored rectangle."""
+        super().layout(rect)
+        for slot in self.slots:
+            measured = slot.widget.measure(Constraints.loose(rect.size))
+            slot.widget.layout(slot.anchor.resolve(rect, measured))
+
+    def render(self, canvas: Canvas) -> None:
+        """Paint the children in slot order, so later slots cover earlier ones."""
+        for slot in self.slots:
+            slot.widget.render(canvas)
+
+
+def centered(widget: Widget, *, horizontal: str = "center", vertical: str = "center") -> Overlay:
+    """Wrap one widget in a full-rect overlay anchored at the given edges.
+
+    Args:
+        widget: The single child to place.
+        horizontal: Horizontal anchor name, from ``"start"`` to ``"stretch"``.
+        vertical: Vertical anchor name, from ``"start"`` to ``"stretch"``.
+    """
+    return Overlay([OverlaySlot(widget, Anchor(horizontal=horizontal, vertical=vertical))])