zettcode-tui 0.4.0__py3-none-any.whl

zettcode/tui/widgets/progress.py

@@ -0,0 +1,166 @@
+"""Transient activity widgets: a spinner and a determinate bar."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from time import monotonic
+
+from ..core.geometry import Constraints, Size
+from ..core.widget import Widget
+from ..glyphs import BAR_EMPTY, BAR_FULL, SPINNER
+from ..render import Canvas, Style
+from ..render.text import display_width, truncate
+
+DEFAULT_FRAMES = SPINNER
+
+
+class Spinner(Widget):
+    """An animated glyph that keeps the frame loop alive while it runs.
+
+    Shape::
+
+        <glyph> working                   <- braille frames, cycled every interval
+
+    The glyph is derived from the clock at paint time rather than advanced by a
+    tick, so it never drifts or speeds up when frames are dropped. What keeps
+    frames coming is the scheduler token registered in ``start``; with
+    ``app.reduced_motion`` the token is skipped and the first frame stays put.
+    """
+
+    def __init__(
+        self,
+        label: str = "",
+        *,
+        frames: Sequence[str] = DEFAULT_FRAMES,
+        interval: float = 0.12,
+        clock=monotonic,
+    ) -> None:
+        """Configure the glyph cycle, the interval between frames, and the label.
+
+        Args:
+            label: Text drawn after the glyph; omit it for a bare spinner.
+            frames: Glyphs cycled in order; an empty sequence falls back to
+                ``DEFAULT_FRAMES``.
+            interval: Seconds each glyph is held, floored at 0.01.
+            clock: Time source, injectable so tests can step the animation.
+        """
+        super().__init__()
+        self.label = label
+        self.frames = tuple(frames) or DEFAULT_FRAMES
+        self.interval = max(0.01, interval)
+        self.clock = clock
+        self._started = 0.0
+        self._active = False
+        self._token = f"spinner:{id(self)}"
+
+    @property
+    def active(self) -> bool:
+        """Return whether the spinner is registered for animation."""
+        return self._active
+
+    def start(self) -> None:
+        """Start animating, unless reduced motion is in effect."""
+        self._active = True
+        self._started = self.clock()
+        if self.app is not None and not self.app.reduced_motion:
+            self.app.scheduler.animate(self._token)
+
+    def stop(self) -> None:
+        """Stop animating and release the scheduler token."""
+        self._active = False
+        if self.app is not None:
+            self.app.scheduler.animate(self._token, active=False)
+
+    def on_mount(self) -> None:
+        """Resume the animation when an already running spinner is mounted."""
+        if self._active:
+            self.start()
+
+    def on_unmount(self) -> None:
+        """Release the token so a detached spinner stops costing frames."""
+        self.stop()
+
+    @property
+    def frame(self) -> str:
+        """Return the glyph for the current time, or the first frame when idle."""
+        if not self._active or (self.app is not None and self.app.reduced_motion):
+            return self.frames[0]
+        step = int((self.clock() - self._started) / self.interval)
+        return self.frames[step % len(self.frames)]
+
+    def measure(self, constraints: Constraints) -> Size:
+        """Ask for one row and the glyph plus label."""
+        return constraints.constrain(Size(1 + (1 + display_width(self.label) if self.label else 0), 1))
+
+    def render(self, canvas: Canvas) -> None:
+        """Paint the current glyph and label."""
+        if self.rect.empty:
+            return
+        theme = self.theme
+        text = f"{self.frame} {self.label}" if self.label else self.frame
+        canvas.draw_text(
+            self.rect.x,
+            self.rect.y,
+            truncate(text, self.rect.width),
+            Style(foreground=theme.accent, bold=True),
+            max_width=self.rect.width,
+        )
+
+
+class ProgressBar(Widget):
+    """A determinate bar with an optional label.
+
+    Shape::
+
+        build ##########------------      <- label, filled, empty
+              |<-- width * value -->|
+
+    ``value`` is clamped into 0..1; filled cells use U+2588 and empty ones
+    U+2591. The label is truncated first and always keeps one cell for the bar;
+    if nothing is left, only the label is drawn.
+    """
+
+    def __init__(self, value: float = 0.0, *, label: str = "", filled: str = BAR_FULL, empty: str = BAR_EMPTY) -> None:
+        """Store the value and the glyphs used for the filled and empty parts.
+
+        Args:
+            value: Completion ratio; clamped into ``0.0..1.0`` at paint time.
+            label: Text drawn before the bar, followed by one space.
+            filled: Glyph repeated for the completed portion of the bar.
+            empty: Glyph repeated for the remaining portion.
+        """
+        super().__init__()
+        self.value = value
+        self.label = label
+        self.filled = filled
+        self.empty = empty
+
+    def measure(self, constraints: Constraints) -> Size:
+        """Ask for one row and the label plus one cell of bar."""
+        return constraints.constrain(Size(1 + display_width(self.label) + (1 if self.label else 0), 1))
+
+    def render(self, canvas: Canvas) -> None:
+        """Paint the label and the bar, clamping the value into 0..1."""
+        if self.rect.empty:
+            return
+        theme = self.theme
+        width = self.rect.width
+        prefix = ""
+        if self.label:
+            prefix = truncate(f"{self.label} ", max(0, width - 1))
+            width -= display_width(prefix)
+        if width <= 0:
+            canvas.draw_text(self.rect.x, self.rect.y, prefix, Style(foreground=theme.text), max_width=self.rect.width)
+            return
+        ratio = min(1.0, max(0.0, self.value))
+        filled = min(width, int(round(width * ratio)))
+        canvas.draw_text(self.rect.x, self.rect.y, prefix, Style(foreground=theme.text), max_width=self.rect.width)
+        x = self.rect.x + display_width(prefix)
+        canvas.draw_text(x, self.rect.y, self.filled * filled, Style(foreground=theme.accent), max_width=filled)
+        canvas.draw_text(
+            x + filled,
+            self.rect.y,
+            self.empty * (width - filled),
+            Style(foreground=theme.border),
+            max_width=width - filled,
+        )

zettcode/tui/widgets/rich_text.py

@@ -0,0 +1,84 @@
+"""A retained widget for small styled text blocks."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import TypeAlias, cast
+
+from ..core.geometry import Constraints, Size
+from ..core.widget import Widget
+from ..render import Canvas, Span, Style, TextLine
+from ..render.rich_text import Alignment, layout_rich_lines
+from ..render.text import display_width
+
+RichContent: TypeAlias = str | Span | TextLine | Sequence[Span] | Sequence[TextLine]
+RichValue: TypeAlias = RichContent | Callable[[], RichContent]
+
+
+class RichText(Widget):
+    """Draw a small block of styled lines, with optional wrapping and alignment.
+
+    A value may be a string, a Span, a TextLine, a sequence of spans or
+    lines, or a callable evaluated at paint time. Long histories instead
+    use a LineSource and the same ``layout_rich_lines`` function, without
+    mounting a widget for each message.
+
+    Args:
+        value: Text or lines to show, optionally computed on each paint.
+        wrap: Wrap within the given width; otherwise clip with an ellipsis.
+        align: ``"left"``, ``"center"``, or ``"right"``.
+    """
+
+    def __init__(self, value: RichValue = "", *, wrap: bool = True, align: Alignment = "left") -> None:
+        super().__init__()
+        if align not in ("left", "center", "right"):
+            raise ValueError(f"Unknown alignment: {align!r}")
+        self.value = value
+        self.wrap = wrap
+        self.align = align
+
+    def set_content(self, value: RichValue) -> None:
+        """Replace the content and ask the parent to measure it again."""
+        self.value = value
+        self.request_layout()
+        if self.app is not None:
+            self.app.request_layout()
+
+    def _lines(self) -> tuple[TextLine, ...]:
+        """Resolve the current value into immutable styled lines."""
+        value = self.value() if callable(self.value) else self.value
+        if isinstance(value, str):
+            style = Style(foreground=self.theme.text)
+            return tuple(TextLine((Span(line, style),)) for line in value.split("\n"))
+        if isinstance(value, Span):
+            return (TextLine((value,)),)
+        if isinstance(value, TextLine):
+            return (value,)
+        items: tuple[Span | TextLine, ...] = tuple(value)
+        if not items:
+            return ()
+        if isinstance(items[0], TextLine):
+            if not all(isinstance(item, TextLine) for item in items):
+                raise TypeError("RichText content cannot mix TextLine and Span")
+            return cast(tuple[TextLine, ...], items)
+        if not all(isinstance(item, Span) for item in items):
+            raise TypeError("RichText content must be Span or TextLine values")
+        return (TextLine(cast(tuple[Span, ...], items)),)
+
+    def measure(self, constraints: Constraints) -> Size:
+        """Measure the text by visible columns and wrapped line count."""
+        lines = self._lines()
+        if not lines:
+            return constraints.constrain(Size(0, 0))
+        natural = max(display_width(line.text) for line in lines)
+        width = min(natural, constraints.max_width) if constraints.max_width is not None else natural
+        height = len(layout_rich_lines(lines, max(1, width), wrap=self.wrap, align=self.align))
+        return constraints.constrain(Size(width, height))
+
+    def render(self, canvas: Canvas) -> None:
+        """Paint only rows inside the assigned rectangle."""
+        if self.rect.empty:
+            return
+        rows = layout_rich_lines(self._lines(), self.rect.width, wrap=self.wrap, align=self.align)
+        for offset, row in enumerate(rows[: self.rect.height]):
+            canvas.draw_spans(self.rect.x, self.rect.y + offset, row.spans, max_width=self.rect.width)

zettcode/tui/widgets/status.py

@@ -0,0 +1,106 @@
+"""One-line status bar with left and right segments."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypeAlias
+
+from ..core.geometry import Constraints, Size
+from ..core.widget import Widget
+from ..render import DEFAULT_STYLE, Canvas, Span, Style, TextLine, truncate_spans
+
+Text: TypeAlias = str | TextLine | Callable[[], str | TextLine]
+
+
+#: Columns kept empty between the two segments. Without it a long left segment runs into the right one and the
+#: row reads as a single run of words; the gap is what says which part belongs to which side.
+GAP = 2
+
+
+class StatusBar(Widget):
+    """Render a left-aligned and a right-aligned segment on one row.
+
+    Shape::
+
+        zettcode              openai/gpt-5 <- right segment, flush to the edge
+        ^^^^^^^^^^^^^^^^^^^^^^                ^^^^^^^^^^^^^
+        left segment                          never truncated
+
+    The right segment wins when space runs out: it keeps its width and the left
+    one is cut instead. A right segment wider than the whole row is drawn alone.
+    Either segment may be a callable, read once per paint.
+
+    At least :data:`GAP` columns are left empty between the two. A left segment
+    with no room for even one character next to that gap is dropped rather than
+    drawn as a stray ellipsis against the right segment, so a narrow row says
+    what the row is about and nothing half-written.
+
+    A segment can be a styled :class:`~zettcode.tui.render.TextLine`; its spans
+    keep their own colours and attributes. A span that sets no style of its own
+    is painted with the bar's muted style, so a plain ``str``, an unstyled line,
+    and the golden default all look the same.
+    """
+
+    def __init__(self, left: Text = "", right: Text = "") -> None:
+        """Store both segments; either may be a callback evaluated at paint time.
+
+        Args:
+            left: Drawn at the left edge, truncated when the right segment wins.
+            right: Drawn flush to the right edge; it is never truncated, so it
+                keeps the width it asks for even at the left segment's expense.
+        """
+        super().__init__()
+        self.left = left
+        self.right = right
+
+    def measure(self, constraints: Constraints) -> Size:
+        """Ask for one row and the combined width of both segments."""
+        wanted = self._line(self.left).width + self._line(self.right).width
+        return constraints.constrain(Size(wanted, 1))
+
+    def render(self, canvas: Canvas) -> None:
+        """Draw both segments, letting the right one win when space runs out."""
+        if self.rect.empty:
+            return
+        left = self._line(self.left)
+        right = self._line(self.right)
+        right_width = right.width
+        if right_width >= self.rect.width:
+            canvas.draw_spans(
+                self.rect.x,
+                self.rect.y,
+                truncate_spans(right.spans, self.rect.width),
+                max_width=self.rect.width,
+            )
+            return
+        room = self.rect.width - right_width
+        if room <= GAP:
+            # Less than one column beside the gap: the right segment is the whole row.
+            canvas.draw_spans(
+                self.rect.x + self.rect.width - right_width,
+                self.rect.y,
+                right.spans,
+                max_width=right_width,
+            )
+            return
+        room -= GAP
+        canvas.draw_spans(self.rect.x, self.rect.y, truncate_spans(left.spans, room), max_width=room)
+        canvas.draw_spans(
+            self.rect.x + self.rect.width - right_width,
+            self.rect.y,
+            right.spans,
+            max_width=right_width,
+        )
+
+    def _line(self, text: Text) -> TextLine:
+        """Resolve a segment to a styled line, applying the bar style to bare spans."""
+        value = text() if callable(text) else text
+        fallback = Style(foreground=self.theme.muted)
+        if isinstance(value, TextLine):
+            return TextLine(tuple(self._tint(span, fallback) for span in value.spans), metadata=value.metadata)
+        return TextLine((Span(value, fallback),))
+
+    @staticmethod
+    def _tint(span: Span, fallback: Style) -> Span:
+        """Give an unstyled span the bar's style, leaving designed spans alone."""
+        return span if span.style != DEFAULT_STYLE else Span(span.text, fallback)

zettcode/tui/widgets/table.py

@@ -0,0 +1,101 @@
+"""A table widget that paints the same shape as a Markdown table."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from ..core.geometry import Constraints, Size
+from ..core.widget import Widget
+from ..render import Canvas
+from ..render.text import display_width
+from .markdown import render_table
+
+ALIGNMENTS = ("left", "center", "right")
+
+
+@dataclass(frozen=True, slots=True)
+class Column:
+    """One table column and how its cells line up.
+
+    Attributes:
+        title: Header text; an empty title on every column hides the header row.
+        align: One of ``ALIGNMENTS``; anything else is rejected.
+        width: Pins the column to a fixed cell count. It is still raised to the
+            renderer's minimum and shrunk when the width budget is tight;
+            ``None`` lets the column take its natural width.
+    """
+
+    title: str = ""
+    align: str = "left"
+    width: int | None = None
+
+    def __post_init__(self) -> None:
+        """Reject alignments the table renderer does not know."""
+        if self.align not in ALIGNMENTS:
+            raise ValueError(f"Unknown alignment: {self.align!r}")
+
+
+class Table(Widget):
+    """Lay rows out in columns that always fit the widget rectangle.
+
+    Rendering is delegated to the Markdown table renderer so a table looks the
+    same wherever it comes from: a header, one rule per column, and cells that
+    wrap instead of being cut. ``Column.width`` pins a column when needed.
+
+    Shape::
+
+        Name       Files   State
+        ---------  -----   -----          <- one rule per column, dim
+        parser        12   done           <- per-column alignment
+        renderer       7    wip
+
+    The rule is U+2500. Columns are dropped from the right when they cannot fit,
+    and the header row disappears when every title is empty.
+    """
+
+    def __init__(
+        self,
+        columns: Sequence[Column],
+        rows: Sequence[Sequence[str]] = (),
+        *,
+        header: bool = True,
+    ) -> None:
+        """Store the columns and rows; a header hides itself when no title is set.
+
+        Args:
+            columns: Column definitions, left to right.
+            rows: Cell text, padded and truncated to the column count.
+            header: Draw the title row; ignored when every title is empty.
+        """
+        super().__init__()
+        self.columns = tuple(columns)
+        self.rows = tuple(tuple(row) for row in rows)
+        self.header = header and any(column.title for column in self.columns)
+
+    @property
+    def body_height(self) -> int:
+        """Return how many body rows the table holds."""
+        return len(self.rows)
+
+    def measure(self, constraints: Constraints) -> Size:
+        """Estimate the natural width from the titles and one row per entry."""
+        widest = sum(display_width(column.title) + 3 for column in self.columns)
+        return constraints.constrain(Size(widest, len(self.rows) + int(self.header)))
+
+    def render(self, canvas: Canvas) -> None:
+        """Delegate to the Markdown renderer, dropping the header when it is hidden."""
+        if not self.columns or self.rect.empty:
+            return
+        lines = render_table(
+            [column.title for column in self.columns],
+            [column.align for column in self.columns],
+            [list(row) for row in self.rows],
+            self.rect.width,
+            self.theme,
+            fixed=[column.width for column in self.columns],
+        )
+        if not self.header:
+            lines = lines[2:]
+        for index, line in enumerate(lines[: self.rect.height]):
+            canvas.draw_spans(self.rect.x, self.rect.y + index, line.spans, max_width=self.rect.width)

zettcode/tui/widgets/tasks.py

@@ -0,0 +1,130 @@
+"""A compact panel of ordered tasks with one of them in progress."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from zettcode.tui import DONE, MARKER, PENDING, RULE
+
+from ..core.geometry import Constraints, Size
+from ..core.widget import Widget
+from ..render import Canvas, Style, truncate
+from ..render.text import display_width
+
+MARKERS = {
+    "completed": DONE,
+    "in_progress": MARKER,
+    "pending": PENDING,
+}
+
+
+class TaskPanel(Widget):
+    """Show ordered tasks; a panel with no tasks occupies no space.
+
+    The widget only knows about a state name and a label, which keeps the
+    framework free of any particular task vocabulary.
+
+    Shape::
+
+                                           <- blank row, so the box is not glued
+        \u250c Plan \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510      to the transcript above
+        \u2502 \u2713 read the renderer      \u2502   <- completed: muted, struck out
+        \u2502 \u25b8 preview widgets        \u2502   <- in_progress: accent, bold, U+25B8
+        \u2502 \u00b7 run make check         \u2502   <- pending: body text, U+00B7
+        \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+
+    An unknown state falls back to the pending dot, and ``preferred_height()``
+    is the slot size an owner passes to keep the panel exactly as tall as its
+    contents (zero rows when there is nothing to show). A panel too narrow for a
+    frame drops it and keeps the rows.
+    """
+
+    #: Frame glyphs; the title rides in the top edge to save a row.
+    TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT = "\u250c", "\u2510", "\u2514", "\u2518"
+    HORIZONTAL, VERTICAL = RULE, "\u2502"
+    #: Cells of frame around the rows, and the blank row above the frame.
+    FRAME_COLUMNS = 4
+    SEPARATOR_ROWS = 1
+
+    def __init__(self, title: str = "Plan") -> None:
+        """Start empty; the panel occupies no space until tasks arrive.
+
+        Args:
+            title: Heading drawn above the rows, indented by two spaces.
+        """
+        super().__init__()
+        self.title = title
+        self.tasks: tuple[tuple[str, str], ...] = ()
+
+    @property
+    def visible(self) -> bool:
+        """Return whether the panel has anything to show."""
+        return bool(self.tasks)
+
+    def set_tasks(self, tasks: Sequence[tuple[str, str]]) -> bool:
+        """Replace the list and report whether anything actually changed.
+
+        Args:
+            tasks: ``(state, label)`` pairs in display order. ``state`` is looked
+                up in ``MARKERS`` for the glyph and for the colour; an unknown
+                state falls back to a neutral dot.
+        """
+        updated = tuple((state, label) for state, label in tasks)
+        if updated == self.tasks:
+            return False
+        self.tasks = updated
+        self.invalidate()
+        return True
+
+    def preferred_height(self) -> int:
+        """Return the rows needed for the separator, the frame, and the tasks."""
+        return len(self.tasks) + 3 if self.tasks else 0
+
+    def measure(self, constraints: Constraints) -> Size:
+        """Ask for the widest task label plus the marker and the frame."""
+        width = max((display_width(label) for _, label in self.tasks), default=0) + self.FRAME_COLUMNS
+        return constraints.constrain(Size(width, self.preferred_height()))
+
+    def render(self, canvas: Canvas) -> None:
+        """Paint the frame, one row per task, and the heading in the top edge."""
+        if not self.tasks or self.rect.empty:
+            return
+        theme = self.theme
+        frame = Style(foreground=theme.border)
+        heading = Style(foreground=theme.muted, bold=True)
+        # The separator row is outside the frame, so the box never sits flush
+        # against the transcript it follows.
+        top = self.rect.y + self.SEPARATOR_ROWS
+        width = self.rect.width
+        label = f" {self.title} "
+        framed = width >= 4 + display_width(label) and self.rect.height > self.SEPARATOR_ROWS + 2
+        if framed:
+            rule = self.HORIZONTAL * max(0, width - 2 - display_width(label))
+            canvas.draw_text(self.rect.x, top, self.TOP_LEFT, frame)
+            canvas.draw_text(self.rect.x + 1, top, label, heading, max_width=display_width(label))
+            canvas.draw_text(self.rect.x + 1 + display_width(label), top, f"{rule}{self.TOP_RIGHT}", frame)
+        for offset, (state, text) in enumerate(self.tasks):
+            row = top + offset + (1 if framed else 0)
+            if row >= self.rect.y + self.rect.height:
+                return
+            marker = MARKERS.get(state, PENDING)
+            if state == "completed":
+                # A finished task is struck out as well as dimmed, so a long
+                # plan shows what is left at a glance.
+                style = Style(foreground=theme.muted, strike=True)
+            elif state == "in_progress":
+                style = Style(foreground=theme.accent, bold=True)
+            else:
+                style = Style(foreground=theme.text)
+            if not framed:
+                canvas.draw_text(self.rect.x, row, truncate(f"  {marker} {text}", width), style, max_width=width)
+                continue
+            canvas.draw_text(self.rect.x, row, self.VERTICAL, frame)
+            room = max(0, width - self.FRAME_COLUMNS)
+            canvas.draw_text(self.rect.x + 2, row, truncate(f"{marker} {text}", room), style, max_width=room)
+            canvas.draw_text(self.rect.x + width - 1, row, self.VERTICAL, frame)
+        if framed:
+            row = top + len(self.tasks) + 1
+            if row < self.rect.y + self.rect.height:
+                floor = f"{self.BOTTOM_LEFT}{self.HORIZONTAL * max(0, width - 2)}{self.BOTTOM_RIGHT}"
+                canvas.draw_text(self.rect.x, row, floor, frame, max_width=width)