Files
MeshTerm/meshterm/ui/tui/screen.py
T
Jean-Pierre MartineauandClaude Opus 5 8a80d47815 F-key lane: a jump rides the Shift half of the page it follows
Home and End are on the PicoCalc's keyboard. Paging is not. So the
jump-to-either-end pair was never the unreachable thing that earned it
F1/F2 -- it only ever wanted a chip for consistency with the pager it
belongs to. Now it rides that pager: Shift+F5 is Top because F5 is
Page up, Shift+F4 is Bottom because F4 is Page down. One axis, one pair
of keys, the second-grade verb sitting behind the first.

That frees F1-F3 on every screen, and the lane is the only place the
device can advertise anything -- there is no hint line to read a chord
off. So the freed slots went to the affordances that were invisible
there:

  select lists  Sect down/up, the section jumps. Ctrl+PgUp on a
                keyboard with no PgUp is the one binding in the app
                that was physically unreachable. Plus Delete, lit on
                exactly the rows the key acts on.
  map           Region (Home, renamed -- it frames the ground the mesh
                covers, it does not "reset" anything), You (new: Ctrl+L,
                recentre on our own node at the zoom you chose), and
                Frame for the find matches.
  node page     the tab it would switch you to.
  time machine  the window span it would take you to -- w was
                undiscoverable on the device.

The map is the one exception to the new rule: Region answers "where
should I be looking", not "how far down the body am I", so it keeps F1
beside the other two destinations rather than hiding behind a pager it
has nothing to do with.

Screens that never scroll (every dialog, the busy splash, the reorder
list) now say so with an empty lane instead of offering a pager that
does nothing. Screens whose Home/End mean something else say what:
Latest/Oldest in a chat, Newest/Oldest in the packet viewer, You on the
walk (where End is bound to nothing, so its slot stays blank).

The map's hint line finally fits 72: its basemap status was never a key
hint, so it moved to the title's status chain where the standards put
those -- which is what took the map off the gallery's pre-existing
overflow list.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-08 14:56:42 -04:00

536 lines
24 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""The screen abstraction: one layer in the TUI's window stack.
A :class:`Screen` knows how to render its body (as Rich, converted to ANSI lines by
:mod:`~meshterm.ui.tui.render`) and how to react to normalized key *actions* dispatched by
the :class:`~meshterm.ui.tui.session.TuiSession`. Screens never touch prompt_toolkit or the
terminal directly, so they stay small, uniform, and testable.
Interactive screens (select, text, confirm) resolve an :class:`asyncio.Future` when the user
commits or cancels; the session awaits that future and then pops the screen, giving the
push/await/pop model behind ``await session.select(...)`` and friends.
"""
from __future__ import annotations
import asyncio
from typing import Any, Optional, Sequence
from rich.console import RenderableType
from rich.text import Text
from .render import render_lines
from .spinner import Spinner
#: Sentinel a screen resolves with when the user presses Esc to cancel, distinct from a
#: legitimately selected ``None`` value.
CANCEL = object()
class Screen:
"""Base class for every TUI layer.
Attributes:
title: Heading shown at the top of the screen/dialog.
footer_hint: One-line key hint shown in the footer.
scroll: Current vertical scroll offset into the body's rendered lines.
future: Resolved with the screen's result (or :data:`CANCEL`) when it commits.
floating: Whether the session should draw this screen as a centered dialog over
the dimmed screen beneath it (deeper layers float; the base does not).
grow_only: Whether a floating dialog may only ever grow. Its box is sized to the
tallest body — and, for a natural-width dialog, the widest — it has shown, not
the current one, so a screen whose content swings as it changes (the packet
viewer paging between packets, the path composer's shifting suggestions) keeps
a steady, centred box — blank-padded when the current body is shorter — instead
of resizing on every change.
chrome: Whether, as the base screen, this layer is wrapped in the session's
persistent header/footer frame. A startup splash sets this ``False`` so the
session instead centers it under the :attr:`banner` with no status bars.
banner: Block-glyph art (one string per row) drawn, centered, above a chromeless
base screen. Ignored while ``chrome`` is ``True``.
footnote: A short line drawn muted and centered *below* a chromeless base screen's
box (e.g. a copyright notice). Ignored while ``chrome`` is ``True``.
"""
title: str = ""
footer_hint: str = "Esc back"
floating: bool = True
grow_only: bool = False
chrome: bool = True
banner: Optional[Sequence[str]] = None
footnote: Optional[str] = None
@property
def fkey_lane(self):
"""The screen's F-key lane (the PicoCalc footer; see :mod:`~meshterm.ui.tui.fkeys`).
Five slots, F1–F5, each with an optional F6–F10 Shift-bank companion. A slot is
for functionality that is otherwise hard to reach — Enter/Esc never appear, since
both keys are already close at hand. The default puts paging (no physical key at
all) on the prime F4/F5 pair and the jump-to-top/end pair behind Shift on those
same two keys, since Home and End *are* on this keyboard and only ever wanted a
chip for consistency with the pager they belong to. F1–F3 are left free: they are
where a screen's own verbs go, and a screen with none leaves them blank. A screen
overrides this property for its own verbs; the lane may differ screen to screen.
Read fresh every paint, so an override dims the slots whose action would do
nothing right now rather than advertising a dead key — the lane's standing rule
(see :mod:`~meshterm.ui.tui.fkeys`). Screens whose nav keys only scroll gate the
shared slots on :attr:`content_overflows`; this base can't assume that much,
since a nav key elsewhere moves a cursor, a pick, or the map's zoom.
"""
from .fkeys import DEFAULT_LANE
return DEFAULT_LANE
def __init__(self) -> None:
"""Initialize scroll state and the (later-assigned) result future."""
self.scroll = 0
self.future: Optional[asyncio.Future] = None
# (body-line index, rendered ANSI lines) for each section landmark eligible to be
# pinned to the top rows once it scrolls off. A block is usually one line — a section
# heading, a day divider — but may carry the rows that belong with it (a heading and
# the description under it), which pin together as they scroll off, in order. A screen
# that wants sticky headers rebuilds this list while rendering its body (see
# :meth:`sticky_block`); the default is no landmarks.
self._sticky_headers: list[tuple[int, list[str]]] = []
# The one header that pins for the *whole* list rather than for its section — a
# table's column header, which means nothing scrolled off (see :meth:`sticky_rows`).
# Recorded the same way, as (body-line index, rendered line); ``None`` for none.
self._pinned_header: Optional[tuple[int, str]] = None
# The last render's body height and viewport, recorded by the frame (:meth:`note_metrics`)
# so the shared scroll helpers can page by a screenful of the *current* terminal and
# clamp to the content without every caller threading the sizes through.
self._scroll_total = 1
self._scroll_viewport = 1
# A grow-only screen's high-water body height and natural width: the tallest and
# widest it has rendered into a dialog, so its box can be held at that size once
# reached (see :meth:`ratchet_viewport` / :meth:`ratchet_width`). Zero until the
# first paint; irrelevant while not :attr:`grow_only`.
self._viewport_floor = 0
self._width_floor = 0
# --- rendering -----------------------------------------------------------
def render_body(self, width: int) -> list[str]:
"""Return the body's ANSI lines at ``width`` columns (unclipped).
Args:
width: Inner content width in columns.
Returns:
One ANSI string per body line; the session slices these to the viewport.
"""
raise NotImplementedError
def ratchet_viewport(self, body_h: int) -> int:
"""The body height a :attr:`grow_only` dialog is sized to: its running maximum.
The frame calls this each paint with the current body's height. A grow-only
screen returns the tallest height it has yet shown — so its box never shrinks,
and the frame blank-pads a now-shorter body to fill it — while an ordinary
screen returns the height unchanged and is sized to each body as it comes.
"""
if not self.grow_only:
return body_h
self._viewport_floor = max(self._viewport_floor, body_h)
return self._viewport_floor
def ratchet_width(self, natural: int) -> int:
"""The natural width a :attr:`grow_only` dialog is sized to: its running maximum.
The width-side twin of :meth:`ratchet_viewport`, applied by the frame to a
dialog's requested ``dialog_width`` before the terminal cap — so a grow-only
box holds its widest extent as its content narrows, but a shrinking terminal
still clips it. Full-cap dialogs (no ``dialog_width``) never reach here.
"""
if not self.grow_only:
return natural
self._width_floor = max(self._width_floor, natural)
return self._width_floor
def cursor_line(self) -> Optional[int]:
"""Return a body line that must stay visible, or ``None`` for free scrolling.
Selection/text screens return the active row so the session can keep it in view;
plain scroll screens return ``None``.
"""
return None
def consume_edge_scrub(self) -> int:
"""Right-edge columns the session should force-repaint on the next paint (0 = none).
The default is 0 — no screen needs this. A screen whose body can emit glyphs the
terminal renders at an unexpected width (the map's braille) overrides this to have the
session redraw just the smeared edge cells, which prompt_toolkit's differential paint
would otherwise never rewrite (see :class:`~meshterm.ui.map_screen.MapScreen`).
"""
return 0
def sticky_block(self, scroll: int) -> list[str]:
"""The already-rendered body lines to pin as ``scroll`` moves past a section landmark.
Lets a grouped list keep its current section overhead after the section's own rows have
scrolled off — a select screen's ``Channels``/``Direct`` divider, the Trophy case's
discipline heading *and the description under it*, the chat transcript's
``── Wed Jul 8 ──`` day divider. ``scroll`` is the offset the body is about to be
sliced at; the returned lines are drawn as top rows, under any whole-list header pinned
over them (:meth:`sticky_rows` composes them for the frame).
The shared rule: among the blocks a screen recorded in :attr:`_sticky_headers` while
rendering, find the last one starting at or above ``scroll`` (the one *governing* the
top visible row) and pin exactly the rows of it that ``scroll`` has passed. So a block
hands its rows over one at a time as they leave — the heading pins while its
description is still the top content row, and the two pin together once both are gone —
and the pinned rows always continue seamlessly into the body below. A screen opts in
simply by populating :attr:`_sticky_headers`; the empty default means no pinning.
A block never takes more than half the viewport: the rows are given up from the *end*,
so the heading — the row that says which section this is — is the last thing dropped on
a short terminal.
"""
governing: Optional[tuple[int, list[str]]] = None
for entry in self._sticky_headers:
if entry[0] <= scroll:
governing = entry
else:
break # blocks are recorded in body order; nothing past here can govern
if governing is None:
return [] # no landmark above the top visible row
at, rows = governing
keep = max(1, self._scroll_viewport // 2)
return rows[: min(scroll - at, keep)]
def sticky_rows(self, scroll: int) -> list[str]:
"""Every already-rendered line to pin above the body sliced at ``scroll``.
What the frame actually draws, top-down: the whole-list header from
:attr:`_pinned_header` (a table's column header — the lane names, which mean the
same everywhere in the list) once it has scrolled off, then the governing section
block from :meth:`sticky_block`. A screen with only section headings pins one
line; a grouped table pins both, so a scrolled row can still be read off its lanes
*and* placed in its group.
Args:
scroll: The offset the body is about to be sliced at.
Returns:
The lines to pin, in draw order (empty for nothing to pin). Each one costs the
body a row, so the frame reserves exactly as many as come back.
"""
rows: list[str] = []
if self._pinned_header is not None and self._pinned_header[0] < scroll:
rows.append(self._pinned_header[1])
rows.extend(self.sticky_block(scroll))
return rows
# --- input ---------------------------------------------------------------
def handle(self, action: str, data: str = "") -> None:
"""React to a normalized key action from the session.
Args:
action: One of ``up``, ``down``, ``pageup``, ``pagedown``, ``home``, ``end``,
``ctrl_home``, ``ctrl_end``, ``ctrl_pageup``, ``ctrl_pagedown``, ``left``,
``right``, ``ctrl_left``, ``ctrl_right``, ``ctrl_up``, ``ctrl_down``,
``shift_up``, ``shift_down``,
``shift_left``, ``shift_right``, ``enter``, ``escape``, ``backspace``,
``delete``, ``space``, ``tab``, ``shift_tab``, or ``text`` (with ``data``
set to the character).
data: The typed character when ``action`` is ``text``.
"""
if action == "escape":
self.resolve(CANCEL)
def resolve(self, value: Any) -> None:
"""Resolve this screen's future, committing ``value`` (or :data:`CANCEL`).
Args:
value: The result to hand back to the awaiting caller.
"""
if self.future is not None and not self.future.done():
self.future.set_result(value)
# --- scrolling helpers (shared) ------------------------------------------
def note_metrics(self, total: int, viewport: int) -> None:
"""Record the last render's body height and viewport (the frame calls this each paint).
The shared scroll/section jumps below size themselves from these, so a PageDown moves
by a screenful of the current terminal rather than a fixed constant, and the top/bottom
clamps track the real content height without the caller passing the sizes in.
"""
self._scroll_total = max(1, total)
self._scroll_viewport = max(1, viewport)
def note_viewport(self, viewport: int) -> None:
"""Record just the viewport height (for callers that don't know the body total)."""
self._scroll_viewport = max(1, viewport)
@property
def _page_step(self) -> int:
"""Lines a PageUp/PageDown moves: a screenful, bar one row kept for continuity."""
return max(1, self._scroll_viewport - 1)
@property
def content_overflows(self) -> bool:
"""Whether the last-rendered body is taller than its viewport — i.e. it can scroll.
The reusable gate for the app-wide rule that a footer only advertises a key that
would do something: a screen whose body fits has nothing to scroll, so it drops its
``↑↓ PgUp/PgDn scroll`` atom (see :attr:`DashboardScreen.footer_hint`). Reads the
metrics the frame recorded on the *previous* paint (:meth:`note_metrics`), so it is
honest one frame after a resize — the frame repaints again immediately.
"""
return self._scroll_total > self._scroll_viewport
def scroll_by(self, delta: int, total: int, viewport: int) -> None:
"""Adjust :attr:`scroll` by ``delta`` lines, clamped to the given content bounds."""
self.scroll = _clamp_scroll(self.scroll + delta, total, viewport)
def scroll_lines(self, delta: int) -> None:
"""Scroll by ``delta`` lines, clamped to the last-recorded content bounds."""
self.scroll = _clamp_scroll(
self.scroll + delta, self._scroll_total, self._scroll_viewport
)
def scroll_pages(self, pages: int) -> None:
"""Scroll by ``pages`` screenfuls (negative scrolls up)."""
self.scroll_lines(pages * self._page_step)
def scroll_to_top(self) -> None:
"""Jump the view to the first line."""
self.scroll = 0
def scroll_to_bottom(self) -> None:
"""Jump the view to the last screenful."""
self.scroll = max(0, self._scroll_total - self._scroll_viewport)
def scroll_to_section_start(self) -> None:
"""Move to the top of the section holding the top visible line.
Sections are delimited by the recorded :attr:`_sticky_headers` (a select list's group
dividers, the chat transcript's day dividers). If that heading is already the top line,
move to the *previous* section instead — so repeated presses walk up section by section,
the way a text editor's paragraph jump does. Falls back to the very top with no sections.
"""
offsets = [idx for idx, _ in self._sticky_headers]
governing = max((o for o in offsets if o <= self.scroll), default=None)
if governing is None:
target = 0
elif governing < self.scroll:
target = governing # up to the top of the section we're inside
else:
target = max((o for o in offsets if o < self.scroll), default=0)
self.scroll = _clamp_scroll(target, self._scroll_total, self._scroll_viewport)
def scroll_to_next_section(self) -> None:
"""Move to the start of the next section below the top visible line (else the bottom)."""
offsets = [idx for idx, _ in self._sticky_headers]
nxt = min((o for o in offsets if o > self.scroll), default=None)
target = nxt if nxt is not None else self._scroll_total
self.scroll = _clamp_scroll(target, self._scroll_total, self._scroll_viewport)
class ListWindow:
"""Scroll state for a list that scrolls *inside* a fixed screen.
The app-wide windowed-list pattern (established by the mesh walk's link list): the
screen sizes its fixed chrome — headings, charts, action rows — to the frame's
viewport (see :meth:`Screen.note_viewport`; the frame records it before
``render_body`` runs) and hands the leftover rows here; only the list's rows
scroll within them. Faint ``↑ n more`` / ``↓ n more`` markers (see
:meth:`marker`) take the window's edge rows exactly when rows are hidden on
that side, and the settled content capacity is remembered as :attr:`page`, the
stride a PgUp/PgDn should move by.
Attributes:
top: First list row the window shows (clamped by :meth:`fit` each paint).
page: Rows the window carried on the last :meth:`fit` — the paging stride.
"""
def __init__(self) -> None:
"""Start at the top with a conservative pre-first-paint stride."""
self.top = 0
self.page = 6
def fit(self, n: int, win: int, index: Optional[int] = None) -> tuple[int, int]:
"""Settle the window over ``n`` rows into ``win`` lines: ``(top, count)``.
The edge markers eat the window's boundary rows exactly when rows hide
beyond them, so the content capacity shifts as the window slides; a few
passes settle top, capacity, and the highlight clamp together.
Args:
n: Total list rows.
win: Lines the window may spend — on content and markers alike.
index: A highlighted row that must stay visible, or ``None`` when the
window scrolls free (a cursor-less log; ``top`` is just clamped).
Returns:
The first visible row and how many rows to draw. Rows hidden above
number ``top``; below, ``n - top - count`` — each side non-zero exactly
when its marker row should be drawn.
"""
if n <= win:
self.top = 0
self.page = max(1, win)
return 0, n
top = max(0, min(self.top, n - 1))
count = 1
for _ in range(4):
above = 1 if top > 0 else 0
below = 1 if n - top > win - above else 0
count = max(1, win - above - below)
if index is not None:
if index < top:
top = index
elif index >= top + count:
top = index - count + 1
top = max(0, min(top, n - count))
self.top = top
self.page = count
return top, count
def to_end(self) -> None:
"""Slide the window to the list's tail on the next :meth:`fit`.
The overshoot is deliberate — the caller rarely knows the list length at
keypress time, and :meth:`fit` clamps to the last windowful either way.
"""
self.top = 10**9
@staticmethod
def marker(hidden: int, direction: str) -> Text:
"""The faint edge row counting rows hidden ``"above"`` or ``"below"``."""
arrow = "↑" if direction == "above" else "↓"
return Text(f" {arrow} {hidden} more", style="faint")
def _clamp_scroll(scroll: int, total: int, viewport: int) -> int:
"""Clamp a scroll offset to the valid range for the content and viewport.
Args:
scroll: Proposed offset.
total: Total line count.
viewport: Visible height in lines.
Returns:
The offset clamped to ``0 .. max(0, total - viewport)``.
"""
return max(0, min(scroll, max(0, total - viewport)))
class ScrollScreen(Screen):
"""A read-only screen that shows a Rich renderable in a scrollable viewport.
Used for tool result windows and any long list. Content taller than the viewport scrolls
with the arrows / PageUp / PageDown (a screenful) / Home / End (or Ctrl+Home / Ctrl+End);
Esc dismisses it. Result windows carry no sections, so Ctrl+PageUp/PageDown just reach the
top/bottom.
"""
@property
def fkey_lane(self):
"""The shared lane, its nav slots dimmed when the content already fits.
Every nav key here scrolls and nothing else, so a result window short enough to
read whole has four inert slots — the same gate the footer hint uses on the other
platform (:attr:`Screen.content_overflows`).
"""
from .fkeys import default_lane
return default_lane(nav=self.content_overflows)
def __init__(
self,
renderable: RenderableType,
*,
title: str = "",
footer_hint: str = "↑↓ PgUp/PgDn scroll · Esc close",
floating: bool = True,
) -> None:
"""Wrap a renderable in a dismissable, scrollable screen.
Args:
renderable: The Rich content to display.
title: Heading for the screen/dialog.
footer_hint: Footer key hint.
floating: Whether to draw as a centered dialog over the parent.
"""
super().__init__()
self._renderable = renderable
self.title = title
self.footer_hint = footer_hint
self.floating = floating
def render_body(self, width: int) -> list[str]:
"""Render the wrapped content to ANSI lines and remember the total count."""
lines = render_lines(self._renderable, width)
self._scroll_total = max(1, len(lines))
return lines
def handle(self, action: str, data: str = "") -> None:
"""Scroll the viewport (by line, page, or to an edge) or dismiss the screen."""
if action == "up":
self.scroll_lines(-1)
elif action == "down":
self.scroll_lines(1)
elif action == "pageup":
self.scroll_pages(-1)
elif action in ("pagedown", "space"):
self.scroll_pages(1)
elif action in ("home", "ctrl_home"):
self.scroll_to_top()
elif action in ("end", "ctrl_end"):
self.scroll_to_bottom()
elif action == "ctrl_pageup":
self.scroll_to_section_start()
elif action == "ctrl_pagedown":
self.scroll_to_next_section()
elif action in ("escape", "enter"):
self.resolve(None)
class BusyScreen(Screen):
"""A non-interactive splash body: an animated spinner beside a message.
Used to keep the startup splash on screen — its wordmark and box unchanged — while a
short async task runs (e.g. smoke-testing a chosen companion device). It set as a
chromeless base so it redraws the same centered-under-the-wordmark splash, only swapping
the box's contents. It resolves nothing and ignores every key; the session pops it when
the awaited task completes. The animation itself is the reusable
:class:`~meshterm.ui.tui.spinner.Spinner`.
"""
footer_hint = "working…"
floating = False
@property
def fkey_lane(self):
"""No lane at all: this screen swallows every key, so none of them do anything."""
from .fkeys import EMPTY_LANE
return EMPTY_LANE
def __init__(self, message: str, *, title: str = "") -> None:
"""Start a busy splash showing ``message`` under an optional ``title``."""
super().__init__()
self.title = title
self._message = message
self._spinner = Spinner()
def tick(self) -> None:
"""Advance the spinner to its next frame (driven by the session's animation timer)."""
self._spinner.tick()
def render_body(self, width: int) -> list[str]:
"""Render the current spinner frame followed by the message."""
line = self._spinner.text()
line.append(" ")
line.append(self._message)
return render_lines(line, width)
def handle(self, action: str, data: str = "") -> None:
"""Swallow all keys: the splash dismisses itself when the task finishes."""
return