Files
MeshTerm/meshterm/ui/tui/overlay.py
T
Jean-Pierre MartineauandClaude Opus 4.8 19636e31e6 Float a fading ring spinner over laggy device navigations
Menu navigation over a slow link (Bluetooth especially, but serial too)
can sit on a blank frame while the companion answers — the menu screen is
popped and the tool's first prompt not yet pushed. Fill that gap with a
top-of-z-order spinner so the wait reads as work, not a hang.

- RingSpinner: a reusable, screen-agnostic braille circle with a cyan->blue
  comet chasing the rim. Plotted a quarter-arc and mirrored for exact 4-fold
  symmetry; stroked over a band of radii so it reads clearly as a circle.
- BusyOverlay + TuiSession.busy_overlay: draw the ring as the top-most float,
  centered, only in the gaps between screens (empty stack) so it never buries
  a prompt. It holds black for 200ms then fades in over 400ms, so quick work
  shows nothing and longer work never pops in. The fade restarts every time
  the ring is re-exposed (pop/reset), not just on first display.
- Wire it into menu navigation and the post-splash monitor resume for any
  real device link (mock simulator opts out); surfaced via ctx.ui.busy_overlay.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-09 21:33:43 -04:00

120 lines
4.9 KiB
Python

"""The busy overlay: a centred ring spinner floated on top of everything else.
A :class:`BusyOverlay` is the model behind :meth:`~meshterm.ui.tui.session.TuiSession.
busy_overlay` — a :class:`~meshterm.ui.tui.ring.RingSpinner` with an optional caption beneath
it. Unlike a :class:`~meshterm.ui.tui.screen.Screen`, it is *not* part of the screen stack: the session
draws it as the top-most float, so it hovers over whatever is (or is not) on screen. It owns
no input and resolves nothing; the session shows it while an operation runs and drops it when
that operation returns.
Rather than pop in, it stays fully black for a short *hold* and then *fades in from black*
over its next fraction of a second (see :attr:`brightness`): an operation that finishes within
the hold shows nothing at all, and a longer one eases up out of the black rather than appearing
suddenly — so the ring never flashes and never pops in.
"""
from __future__ import annotations
import time
from rich.cells import cell_len
from rich.text import Text
from .render import render_to_ansi
from .ring import RingSpinner, dim_color
#: The muted caption colour (the theme's ``muted``, as a hex so it can be dimmed for the fade).
_CAPTION_COLOR = "#94a3b8"
class BusyOverlay:
"""A ring spinner (plus optional caption) drawn as the top-most floating layer.
Attributes:
spinner: The animated :class:`~meshterm.ui.tui.ring.RingSpinner` at the overlay's core.
message: An optional caption drawn, muted, beneath the ring.
started_at: The monotonic time the overlay was created, from which the hold + fade run.
hold: Seconds the ring stays fully black before the fade begins.
fade: The fade-in duration in seconds, after the hold.
"""
def __init__(
self, message: str = "", *, hold: float = 0.2, fade: float = 0.4
) -> None:
"""Create a busy overlay.
Args:
message: A short caption drawn beneath the ring (empty for a bare ring).
hold: Seconds to stay fully black before fading in, so an operation that finishes
this fast shows nothing at all.
fade: Seconds over which the ring then brightens from black to full colour.
"""
self.spinner = RingSpinner()
self.message = message
self.started_at = time.monotonic()
self.hold = max(0.0, hold)
self.fade = max(0.0, fade)
@property
def brightness(self) -> float:
"""The current fade level in ``[0, 1]``: 0 through the :attr:`hold`, then easing to 1.
Stays exactly 0 for the first :attr:`hold` seconds (nothing paints), then a smoothstep
easing over :attr:`fade` gives a gentle glow up out of the black rather than a linear
ramp.
"""
elapsed = time.monotonic() - self.started_at - self.hold
if elapsed <= 0:
return 0.0
if self.fade <= 0:
return 1.0
t = min(1.0, elapsed / self.fade)
return t * t * (3 - 2 * t) # smoothstep
def tick(self) -> None:
"""Advance the ring's comet one animation step."""
self.spinner.tick()
def restart(self) -> None:
"""Restart the intro from scratch: rewind the fade ramp and the comet to their starts.
Called each time the ring is (re)exposed — its first appearance and every time it comes
back after a prompt covered it — so the black hold and fade-in play fresh every display
rather than the ring snapping back at full brightness mid-way through an operation.
"""
self.started_at = time.monotonic()
self.spinner.reset()
def render(self) -> str:
"""Render the ring, plus any caption, as a centred ANSI block, at the current fade level.
The rows are pre-padded to a common width and joined into one multi-line
:class:`~rich.text.Text`, so the session's content-sized float centres a clean
rectangle over the screen.
Returns:
An ANSI string of the ring rows and an optional centred caption line.
"""
level = self.brightness
ring = self.spinner.render(level)
rows: list[Text] = ring.split("\n")
width = max((cell_len(row.plain) for row in rows), default=0)
if self.message:
width = max(width, cell_len(self.message))
block = Text("\n").join(_center_text(row, width) for row in rows)
if self.message:
block.append("\n")
caption = Text(self.message, style=dim_color(_CAPTION_COLOR, level))
block.append_text(_center_text(caption, width))
return render_to_ansi(block, width)
def _center_text(text: Text, width: int) -> Text:
"""Return ``text`` padded with spaces so it is centred within ``width`` cells."""
pad = max(0, width - cell_len(text.plain))
left = pad // 2
out = Text(" " * left)
out.append_text(text)
out.append(" " * (pad - left))
return out