Path line: flexible hop-sequence widget, powerline chips or arrows

PathLine renders PathHop sequences three ways (full line, middle-elided to
a width, hop-boundary wrap under a hanging indent) in two looks: the
app-wide muted-arrow presentation, or interlocking powerline chips filled
with each node's key hue when the terminal can draw U+E0B0 (auto mode asks
termfont). Same words in both modes; call sites migrate separately.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Fable 5 committed 2026-07-26 18:27:20 -04:00
1 parent 8992e413de
commit 13dd79018d
2 files changed
+488

No files matched your search

+336
View File
@@ -0,0 +1,336 @@
"""Path lines — the flexible hop-sequence text widget (powerline chips or arrows).
This is the successor to :func:`~meshterm.ui.widgets.path_text` as THE way a hop
sequence renders as text — a trace's walked route, a packet's ``via`` chain, a
message's delivery paths, the composer's preview, a trophy row. Where ``path_text``
is one fixed presentation (arrow-joined, one line, overflow left entirely to the
caller), a :class:`PathLine` separates *what the hops are* from *how the line is
drawn*, so every surface the survey found can eventually route through it:
* **Two separator styles.** ``plain`` joins hops with muted ``→`` arrows — today's
look, unchanged. ``powerline`` renders each hop as a colour-filled chip joined by
the solid-triangle separator U+E0B0 (foreground = previous chip's fill, background
= next's — the interlocking oh-my-posh look), the chip fill being the node's
hash-derived hue (:func:`~meshterm.ui.theme.node_style`), our own node the pure
``you`` white, a keyless hop grey. ``auto`` (the default) picks powerline exactly
when the terminal can draw it (:func:`~meshterm.ui.termfont.powerline_enabled` —
a recommended font, a glyph-capable renderer, or the user's override) and falls
back to arrows everywhere else, so no terminal ever sees tofu.
* **Three overflow answers**, matching the three patterns the surfaces already use:
:meth:`PathLine.text` is the full one-liner (for callers that ellipsize or
h-scroll it themselves), :meth:`PathLine.ellipsized` fits a width by eliding
*middle* hops behind a ``⋯`` mark — both endpoints survive, unlike a tail
truncation that amputates the destination — and :meth:`PathLine.wrapped` breaks
at hop boundaries under a hanging indent (never mid-name, never mid-chip).
* **The same hop semantics everywhere.** A :class:`PathHop` carries what the app's
conventions need: the label (a name, or a hash standing as identity), the key any
known prefix of which picks the hue, the ``you`` flag, the trace-flavour
``(3d)`` annotation, the lit-prefix width for hash labels (the
``highlighted_hash`` two-tone), the ``dim`` fade for resolved return legs, and an
explicit style override for context colourings that outrank identity. Chips keep
the exact same words as arrows — only colours and separators change — so a route
reads identically whichever mode drew it.
Existing call sites still render through ``path_text``; migrating them here is a
separate, per-surface pass. The composer's insertion cursor is the one deliberate
mode exception: a render asked for ``cursor_arrow`` always draws plain arrows, since
an insertion point lives *between* hops and chips fuse that seam shut.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Optional, Sequence
from rich.text import Text
from .termfont import powerline_enabled
from .theme import MESH_THEME, node_style
#: The powerline solid right-pointing triangle (U+E0B0) — the one glyph the widget
#: uses, deliberately the *core* set so every recommended font qualifies (the rounded
#: caps at U+E0B4+ exist only in full Nerd Font patches).
POWERLINE_SEP = "\ue0b0"
#: The plain-mode joining arrow, exactly as ``path_text`` draws it today.
_ARROW = " → "
#: Chip ink: near-black slate for readable text on every spectrum hue and on white.
_CHIP_FG = "#0f172a"
#: Chip ink, softened — annotations and a hash label's unlit tail (the two-tone).
_CHIP_FG_SOFT = "#334155"
#: Chip fill for a keyless hop — the ``faint`` grey; colour stays reserved for
#: keyed identities in chips just as it is in arrow mode.
_KEYLESS_BG = "#64748b"
#: Our own node's chip fill: the pure ``you`` white.
_YOU_BG = "#ffffff"
#: A dimmed hop's chip: dark slate fill with muted ink, receding like ``faint`` text.
_DIM_BG = "#334155"
_DIM_FG = "#94a3b8"
#: The mark standing in for elided middle hops (see :meth:`PathLine.ellipsized`) —
#: rendered as a dim pseudo-hop so it recedes in both modes.
_ELISION = "⋯"
@dataclass(frozen=True)
class PathHop:
"""One hop of a path line — the semantics, independent of how it is drawn.
Attributes:
label: What is shown — a resolved name, or a hash standing as the node's
identity (set ``lit_bytes`` for the two-tone prefix in that case).
key: Any known prefix of the node's key/hash — picks the hash-derived hue
(its first byte, so every prefix agrees). ``None`` renders muted/grey:
colour is reserved for keyed identities.
you: Our own node — pure white, in either mode.
annotation: The trace-flavour hash note, rendered ``" (3d)"`` after the
label in both modes (pass the bare ``3d``, no parentheses).
lit_bytes: For a hash label: leading *bytes* drawn in the hue (the
``highlighted_hash`` two-tone), the rest muted/soft. ``0`` for names.
dim: Fade the hop (and the arrow leading into it) — a planned route's
resolved return leg, "not yours to compose".
style: Explicit colour override — a hex style (``"#rrggbb"``, attributes
allowed) or theme name — for context colourings that outrank identity.
Plain mode uses it as the label style; powerline as the chip fill.
"""
label: str
key: Optional[str] = None
you: bool = False
annotation: Optional[str] = None
lit_bytes: int = 0
dim: bool = False
style: Optional[str] = None
def _style_hex(style: str) -> Optional[str]:
"""The ``#rrggbb`` a style string or theme name resolves to, else ``None``."""
for token in reversed(style.split()):
if token.startswith("#") and len(token) == 7:
return token
themed = MESH_THEME.styles.get(style)
if themed is not None and themed.color is not None:
try:
return "#" + themed.color.get_truecolor().hex.lstrip("#")
except Exception:
return None
return None
class PathLine:
"""A hop sequence, renderable as arrow-joined text or powerline chips.
Build one from :class:`PathHop` entries, then ask for the shape the surface
needs: :meth:`text` (full line), :meth:`ellipsized` (middle-elided to a width),
or :meth:`wrapped` (hop-boundary lines under a hanging indent).
Args:
hops: The hops in display order (the widget never reorders; a reversed or
mirrored walk is the caller's composition).
mode: ``"auto"`` (powerline when the terminal can draw it — the default),
``"powerline"``, or ``"plain"``.
separator: The plain-mode joiner. Defaults to the app-wide ``" → "``; a
surface with its own convention (the atlas trail's ``" › "``) may pass
it. Ignored by powerline mode.
empty: The muted text a hopless path reads as (``"direct"``).
"""
def __init__(
self,
hops: Sequence[PathHop],
*,
mode: str = "auto",
separator: str = _ARROW,
empty: str = "direct",
) -> None:
self._hops = list(hops)
self._mode = mode
self._separator = separator
self._empty = empty
# --- the three shapes ---------------------------------------------------------
def text(self, *, cursor_arrow: Optional[int] = None) -> Text:
"""The full one-line rendering; overflow is the caller's call, per surface.
Args:
cursor_arrow: Draw this joining gap (0-based, between hops *j* and
*j+1*) as the composer's reverse-video insertion cursor. Forces
plain mode for the render — chips fuse the seam an insertion
point needs to sit in.
Returns:
A one-line :class:`Text` (the ``empty`` note when there are no hops).
"""
if not self._hops:
return Text(self._empty, style="muted")
return self._render(self._hops, cursor_arrow=cursor_arrow)
def ellipsized(self, width: int) -> Text:
"""The line fitted to ``width`` by eliding *middle* hops behind ``⋯``.
Endpoints matter most — a route reads origin and destination first — so the
fit keeps the first hop and as much of the tail as possible, then drops the
head too if it must, and only as a last resort truncates a single over-long
hop the classic way.
Args:
width: The cell budget the returned line must fit in.
Returns:
A one-line :class:`Text` no wider than ``width``.
"""
full = self.text()
if full.cell_len <= width or not self._hops:
return full
mark = PathHop(_ELISION, dim=True)
count = len(self._hops)
for head in (1, 0):
for tail in range(count - 1 - head, 0, -1):
kept = self._hops[:head] + [mark] + self._hops[-tail:]
candidate = self._render(kept)
if candidate.cell_len <= width:
return candidate
last = self._render([mark, self._hops[-1]]) if count > 1 else full
last.truncate(width, overflow="ellipsis")
return last
def wrapped(self, width: int, *, indent: int = 0) -> list[Text]:
"""The line broken at hop boundaries, hanging under ``indent`` columns.
The hanging-indent convention: the caller lays its label lane on the first
line, so that line is returned *without* the indent prefix while every
continuation starts with ``indent`` spaces; all lines fit ``width`` and the
content column is uniformly ``width - indent`` wide. Plain-mode lines that
continue end with a trailing ``→`` (the "path goes on" cue); chip lines
always close with their pointed edge. A single hop wider than the content
column stands alone, truncated with an ellipsis.
Args:
width: The full line budget, indent included.
indent: The hanging-indent column the continuations align under.
Returns:
The lines, in order (a single ``empty`` note when there are no hops).
"""
if not self._hops:
return [Text(self._empty, style="muted")]
budget = max(1, width - indent)
plain = self._resolved_mode() != "powerline"
trail = Text.assemble((" →", "muted")) if plain else Text()
groups: list[list[PathHop]] = [[]]
for hop in self._hops:
candidate = groups[-1] + [hop]
rendered = self._render(candidate)
# Reserve the continuation cue: any line but the last will carry it.
if groups[-1] and rendered.cell_len + trail.cell_len > budget:
groups.append([hop])
else:
groups[-1] = candidate
lines: list[Text] = []
for i, group in enumerate(groups):
line = Text() if i == 0 else Text(" " * indent)
body = self._render(group)
if body.cell_len > budget:
body.truncate(budget, overflow="ellipsis")
line.append_text(body)
if plain and i < len(groups) - 1:
line.append_text(trail.copy())
lines.append(line)
return lines
# --- rendering ----------------------------------------------------------------
def _resolved_mode(self) -> str:
"""The effective mode: ``auto`` resolves against the terminal's verdict."""
if self._mode != "auto":
return self._mode
return "powerline" if powerline_enabled() else "plain"
def _render(self, hops: list[PathHop], *, cursor_arrow: Optional[int] = None) -> Text:
"""Join ``hops`` in the effective mode (plain whenever a cursor is asked)."""
if cursor_arrow is None and self._resolved_mode() == "powerline":
return self._render_chips(hops)
return self._render_plain(hops, cursor_arrow)
def _render_plain(self, hops: list[PathHop], cursor_arrow: Optional[int]) -> Text:
"""Arrow-joined hops — ``path_text``'s presentation, hop by hop."""
text = Text()
for i, hop in enumerate(hops):
if i:
if cursor_arrow is not None and i - 1 == cursor_arrow:
text.append(" ")
text.append("→", style="selected")
text.append(" ")
else:
text.append(self._separator, style="faint" if hop.dim else "muted")
text.append_text(self._plain_hop(hop))
return text
def _plain_hop(self, hop: PathHop) -> Text:
"""One arrow-mode hop: label in its identity style, annotation muted."""
note_style = "faint" if hop.dim else "muted"
text = Text()
if hop.dim:
text.append(hop.label, style="faint")
elif hop.style:
text.append(hop.label, style=hop.style)
elif hop.you:
text.append(hop.label, style="you")
elif hop.key and hop.lit_bytes > 0:
split = hop.lit_bytes * 2 # the highlighted_hash two-tone, in hex digits
text.append(hop.label[:split], style=node_style(hop.key))
text.append(hop.label[split:], style="muted")
elif hop.key:
text.append(hop.label, style=node_style(hop.key))
else:
text.append(hop.label, style="muted")
if hop.annotation:
text.append(f" ({hop.annotation})", style=note_style)
return text
def _render_chips(self, hops: list[PathHop]) -> Text:
"""Powerline chips: each hop filled with its hue, seams interlocked."""
fills = [self._chip_fill(hop) for hop in hops]
text = Text()
for i, hop in enumerate(hops):
if i:
text.append(POWERLINE_SEP, style=f"{fills[i - 1]} on {fills[i]}")
text.append_text(self._chip(hop, fills[i]))
text.append(POWERLINE_SEP, style=fills[-1]) # the pointed edge into the page
return text
def _chip_fill(self, hop: PathHop) -> str:
"""A chip's fill colour: override, white you, dim slate, hue, keyless grey."""
if hop.style:
resolved = _style_hex(hop.style)
if resolved:
return resolved
if hop.you:
return _YOU_BG
if hop.dim:
return _DIM_BG
if hop.key:
return _style_hex(node_style(hop.key)) or _KEYLESS_BG
return _KEYLESS_BG
def _chip(self, hop: PathHop, fill: str) -> Text:
"""One chip: same words as arrow mode, dark ink on the identity fill."""
ink = _DIM_FG if hop.dim else _CHIP_FG
soft = _DIM_FG if hop.dim else _CHIP_FG_SOFT
text = Text()
text.append(" ", style=f"on {fill}")
if hop.lit_bytes > 0 and not hop.dim:
split = hop.lit_bytes * 2
text.append(hop.label[:split], style=f"bold {ink} on {fill}")
text.append(hop.label[split:], style=f"{soft} on {fill}")
else:
weight = "" if hop.dim else "bold "
text.append(hop.label, style=f"{weight}{ink} on {fill}")
if hop.annotation:
text.append(f" ({hop.annotation})", style=f"{soft} on {fill}")
text.append(" ", style=f"on {fill}")
return text
+152
View File
@@ -0,0 +1,152 @@
"""Path-line widget tests: same words in both modes, three overflow shapes.
The widget's contract is exactness — plain mode must reproduce the app-wide arrow
presentation glyph for glyph, powerline mode must interlock chip fills through the
separator's foreground/background trick, and every overflow shape must respect its
cell budget — so these tests assert rendered strings and span styles, not vibes.
"""
from __future__ import annotations
import pytest
import meshterm.ui.pathline as pathline
from meshterm.ui.pathline import POWERLINE_SEP, PathHop, PathLine
from meshterm.ui.theme import node_style
def _styles(text) -> dict[str, str]: # noqa: ANN001
"""Map each styled slice of a Text to its style string, for spot checks."""
return {text.plain[s.start:s.end]: str(s.style) for s in text.spans}
def test_plain_mode_matches_the_app_wide_arrow_presentation() -> None:
"""Names in their key hue, us white, keyless muted, arrows muted — the
``path_text`` look, reproduced exactly."""
line = PathLine(
[
PathHop("Alice", key="aa"),
PathHop("77", key="77", lit_bytes=1),
PathHop("you", you=True),
],
mode="plain",
)
text = line.text()
assert text.plain == "Alice → 77 → you"
styles = _styles(text)
assert styles["Alice"] == node_style("aa")
assert styles["you"] == "you"
assert styles["77"] == node_style("77") # the lit hash prefix carries the hue
def test_plain_mode_annotation_dim_and_custom_separator() -> None:
"""The trace ``(3d)`` note rides muted; a dim hop (and the arrow into it) fades;
a surface's own separator — the atlas trail's ``›`` — passes straight through."""
line = PathLine(
[PathHop("YUL", key="3d", annotation="3d"), PathHop("home", you=True, dim=True)],
mode="plain",
)
text = line.text()
assert text.plain == "YUL (3d) → home"
styles = _styles(text)
assert styles[" (3d)"] == "muted" # the annotation note, space included
assert styles["home"] == "faint"
assert styles[" → "] == "faint" # the arrow into a dim hop fades with it
trail = PathLine(
[PathHop("a"), PathHop("b")], mode="plain", separator=" › "
).text()
assert trail.plain == "a › b"
def test_empty_path_reads_as_the_callers_word() -> None:
"""A hopless line is the muted empty note, in every shape."""
assert PathLine([], mode="plain").text().plain == "direct"
assert PathLine([], mode="powerline", empty="direct — no relays").text().plain \
== "direct — no relays"
assert PathLine([], mode="plain").wrapped(40)[0].plain == "direct"
def test_chips_interlock_fills_through_the_separator() -> None:
"""Each seam's triangle wears the previous chip's fill as foreground on the next
chip's fill as background; the last points into the page (foreground only)."""
alice_fill = node_style("aa").split()[-1]
line = PathLine(
[PathHop("Alice", key="aa"), PathHop("you", you=True)], mode="powerline"
)
text = line.text()
assert text.plain == f" Alice {POWERLINE_SEP} you {POWERLINE_SEP}"
seam_styles = [str(s.style) for s in text.spans
if text.plain[s.start:s.end] == POWERLINE_SEP]
assert seam_styles == [f"{alice_fill} on #ffffff", "#ffffff"]
def test_chips_keep_the_same_words_and_honour_style_overrides() -> None:
"""Chips change colours and separators, never the words; an explicit style
override (hex or theme name) becomes the chip fill."""
hops = [PathHop("YUL", key="3d", annotation="3d"), PathHop("you", you=True)]
plain = PathLine(hops, mode="plain").text().plain
chips = PathLine(hops, mode="powerline").text().plain
assert plain.replace(" → ", " ") == chips.replace(POWERLINE_SEP, "").replace(" ", " ").strip()
themed = PathLine([PathHop("X", style="brand")], mode="powerline").text()
assert str(themed.spans[-1].style) == "#5eead4" # the closing edge, brand-filled
hexed = PathLine([PathHop("X", style="bold #123456")], mode="powerline").text()
assert str(hexed.spans[-1].style) == "#123456"
def test_auto_mode_follows_the_terminal_verdict(monkeypatch: pytest.MonkeyPatch) -> None:
"""``auto`` renders chips exactly when the terminal can draw them."""
hops = [PathHop("a"), PathHop("b")]
monkeypatch.setattr(pathline, "powerline_enabled", lambda: True)
assert POWERLINE_SEP in PathLine(hops).text().plain
monkeypatch.setattr(pathline, "powerline_enabled", lambda: False)
assert PathLine(hops).text().plain == "a → b"
def test_cursor_arrow_forces_plain_and_reverse_videos_the_seam() -> None:
"""The composer's insertion cursor needs a seam to sit in, so a cursor render
is always arrows — even in powerline mode — with the cursor arrow selected."""
hops = [PathHop("a"), PathHop("b")]
text = PathLine(hops, mode="powerline").text(cursor_arrow=0)
assert POWERLINE_SEP not in text.plain
assert text.plain == "a → b"
assert _styles(text)["→"] == "selected"
def test_ellipsized_elides_the_middle_and_keeps_both_endpoints() -> None:
"""A route reads origin and destination first, so the fit drops middle hops
behind ``⋯`` — never the tail a right-edge truncation would amputate."""
hops = [PathHop(label) for label in ("AAAA", "BBBB", "CCCC", "DDDD", "EEEE", "FFFF")]
line = PathLine(hops, mode="plain")
assert line.ellipsized(200).plain == line.text().plain # fits → untouched
fitted = line.ellipsized(25)
assert fitted.cell_len <= 25
assert fitted.plain.startswith("AAAA")
assert fitted.plain.endswith("FFFF")
assert "⋯" in fitted.plain
def test_ellipsized_last_resort_truncates_a_single_giant_hop() -> None:
"""When even ``⋯ → last`` overflows, the classic ellipsis truncation steps in."""
line = PathLine([PathHop("AAAAAAAAAA"), PathHop("BBBBBBBBBB")], mode="plain")
fitted = line.ellipsized(8)
assert fitted.cell_len <= 8
assert fitted.plain.endswith("…")
def test_wrapped_breaks_at_hops_under_a_hanging_indent() -> None:
"""Plain lines that continue end with the ``→`` cue; continuations hang at the
indent; every line respects the full width."""
hops = [PathHop(label) for label in ("AAAA", "BBBB", "CCCC", "DDDD")]
lines = PathLine(hops, mode="plain").wrapped(16, indent=2)
assert [line.plain for line in lines] == ["AAAA → BBBB →", " CCCC → DDDD"]
assert all(line.cell_len <= 16 for line in lines)
def test_wrapped_chip_lines_each_close_their_pointed_edge() -> None:
"""Chip wrapping never splits a chip; every line ends on the pointed edge."""
hops = [PathHop(label) for label in ("AAAA", "BBBB", "CCCC", "DDDD")]
lines = PathLine(hops, mode="powerline").wrapped(16, indent=2)
assert len(lines) == 2
assert lines[1].plain.startswith(" ")
assert all(line.plain.endswith(POWERLINE_SEP) for line in lines)
assert all(line.cell_len <= 16 for line in lines)