diff --git a/meshterm/ui/records_screen.py b/meshterm/ui/records_screen.py index dcc1d82..abb9339 100644 --- a/meshterm/ui/records_screen.py +++ b/meshterm/ui/records_screen.py @@ -58,6 +58,7 @@ from .tui.screen import Screen from .widgets import ( NodeResolver, TypeOf, + body_heading, name_rgb, node_marker, node_type_legend, @@ -88,14 +89,16 @@ _GRAPH_ROWS = 3 #: colour, so the shape reads as one flat silhouette rather than two brightnesses. _AREA_TONE: RGB = (148, 163, 184) -#: The area drawing's cell box, a block of its own under the stats: as wide as the page up -#: to a cap (proportions are kept, so past it a shape only gains blank canvas), a fixed -#: number of rows, and a floor of columns below which it is dropped rather than squeezed -#: into illegibility. It used to ride beside the stats in a third of the width, which left -#: no room for a label on any pin. -_AREA_MAX_W = 40 +#: The area drawing's cell box, a block of its own under the stats: the page's whole width +#: (proportions are kept, so a wider page is a bigger shape, never a padded one), rows in +#: step with the width — a quarter of the columns, which in braille dots is a box half as +#: tall as it is wide — with a floor on the rows, and a width below which the drawing is +#: dropped rather than squeezed into illegibility. Rows a flat shape leaves blank are +#: trimmed (:func:`_drawn_rows`), so a tall box costs a flat shape nothing. It used to ride +#: beside the stats in a third of the width, which left no room for a label on any pin. _AREA_MIN_W = 16 -_AREA_ROWS = 8 +_AREA_MIN_ROWS = 8 +_AREA_ROWS_PER_COL = 4 #: Dots kept clear inside the box's edges — wider on the sides than above and below, so a #: pin at the eastern or western extreme still has the cells its hash-byte label needs. _AREA_PAD_X = 8.0 @@ -438,17 +441,18 @@ class RecordScreen(Screen): """The walk's ground, as a block of its own between the stats and the route graph. Empty when there is no drawable shape, or the page is too narrow for one to be - legible. Otherwise a blank line, the drawing trimmed to the rows something landed - on (:func:`_drawn_rows`), and a faint caption reading the drawing back the way the - graph's does. It used to ride beside the stats in a third of the width, which - squeezed the shape and left no cell for a label on any pin. + legible. Otherwise a blank line, the section's heading (its note reading the + drawing back the way the route graph's does), and the drawing itself — the page's + whole width, rows in step with it, trimmed to the rows something landed on + (:func:`_drawn_rows`). It used to ride beside the stats in a third of the width, + which squeezed the shape and left no cell for a label on any pin. """ if not self._shape or width < _AREA_MIN_W: return [] - lines = [""] - lines.extend(_drawn_rows(self._shape_lines(min(width, _AREA_MAX_W), _AREA_ROWS))) - caption = Text("area walked · north up · labels = hash byte", style="faint") - lines.append(render_to_ansi(caption, width, no_wrap=True)) + heading = body_heading("Area walked", "north up · labels = hash byte") + lines = ["", render_to_ansi(heading, width, no_wrap=True)] + rows = max(_AREA_MIN_ROWS, width // _AREA_ROWS_PER_COL) + lines.extend(_drawn_rows(self._shape_lines(width, rows))) return lines def _shape_lines(self, cell_w: int, cell_h: int) -> list[str]: @@ -550,18 +554,30 @@ class RecordScreen(Screen): record = self._record lines: list[str] = [] + # Three sections, each under a body heading (THE form, widgets.body_heading): the + # stats, the ground the walk covered, and the route two ways. The headings are what + # lets a page this tall be skimmed — a reader after the route scrolls to "Route" + # rather than reading down through the drawing to find it. + lines.append(render_to_ansi(body_heading("Stats"), width, no_wrap=True)) + # The record's identity leads its stats: the spec that was walked and when it was + # set, then what the walk measured. + spec = Text(record.spec, style="brand") + spec.append(f" ({record.width_bytes}-byte hops)", style="muted") + lines.extend(render_hanging(self._label("spec"), spec, width, indent=_LABEL_W)) + when = Text(record.discovered_at.astimezone().strftime("%b %d %Y %H:%M")) + when.append(f" · MeshTerm {record.app_version}", style="muted") + lines.append(render_to_ansi(self._lane("recorded", when), width, no_wrap=True)) lines.extend(render_to_ansi(lane, width, no_wrap=True) for lane in self._stat_lanes()) lines.extend(self._area_lines(width)) lines.append("") + heading = body_heading("Route", "you → … → you · labels = hash byte") + lines.append(render_to_ansi(heading, width, no_wrap=True)) lines.extend(self._graph_lines(width)) - caption = Text("you → … → you · labels = hash byte", style="faint") - lines.append(render_to_ansi(caption, width, no_wrap=True)) lines.append(render_to_ansi(node_type_legend(), width, no_wrap=True)) - lines.append("") # The walk itself, on THE path widget, across the card's whole width. No ``route`` - # label lane: the line under a route graph captioned "you → … → you" is the route, + # label lane: the line under a route graph headed "you → … → you" is the route, # and the twelve cells a label would take are hops the reader came here for. It wraps # at hop boundaries (never mid-name, never mid-chip) rather than hanging under a lane. # Our two ends stand on the app-wide ★ rather than repeating our name and key — the @@ -580,14 +596,6 @@ class RecordScreen(Screen): dim_self=False, ) lines.extend(render_to_ansi(line, width, no_wrap=True) for line in route.wrapped(width)) - spec = Text(record.spec, style="brand") - spec.append(f" ({record.width_bytes}-byte hops)", style="muted") - lines.extend(render_hanging(self._label("spec"), spec, width, indent=_LABEL_W)) - - stamp = record.discovered_at.astimezone().strftime("%b %d %Y %H:%M") - when = Text(stamp) - when.append(f" · MeshTerm {record.app_version}", style="muted") - lines.append(render_to_ansi(self._lane("recorded", when), width, no_wrap=True)) return lines diff --git a/meshterm/ui/timemachine_screen.py b/meshterm/ui/timemachine_screen.py index fdc1f7b..be02aa8 100644 --- a/meshterm/ui/timemachine_screen.py +++ b/meshterm/ui/timemachine_screen.py @@ -52,6 +52,7 @@ from .widgets import ( ContactsSort, _age_seconds, _recency_style, + body_heading, format_ago, highlighted_hash, ) @@ -211,13 +212,6 @@ def _quarter_axis(frac: float) -> str: return f"{round(frac * 24)} h" -def _heading(title: str, note: str) -> Text: - """A section heading in the dashboard's voice: accent title, muted note.""" - text = Text(title, style="accent") - text.append(f" · {note}", style="muted") - return text - - class TimeMachineScreen(Screen): """One subject's history page: scrollable sections, ``w`` cycles the window.""" @@ -363,7 +357,7 @@ def _node_sections( volume = bucketize(stamps, start, now, buckets) out: list[RenderableType] = [] - out.append(_heading("Volume", f"{len(observations)} receptions")) + out.append(body_heading("Volume", f"{len(observations)} receptions")) out.extend( axis_chart( timeline_rows(volume, rows=_CHART_ROWS), @@ -379,7 +373,7 @@ def _node_sections( lo, hi = chart_span(medians) rows = timeline_rows(medians, rows=_SNR_ROWS, style=_snr_cell_style) out.append(Text()) - out.append(_heading("SNR", "median dB per slice · grey line = 0")) + out.append(body_heading("SNR", "median dB per slice · grey line = 0")) out.extend( axis_chart( rows, @@ -393,7 +387,7 @@ def _node_sections( out.append(Text()) out.append( - _heading("Rhythm", f"receptions by local time of day · {_slice_note(slice_minutes)}") + body_heading("Rhythm", f"receptions by local time of day · {_slice_note(slice_minutes)}") ) out.extend( axis_chart( @@ -406,7 +400,7 @@ def _node_sections( ) out.append(Text()) - out.append(_heading("Record", "this window")) + out.append(body_heading("Record", "this window")) first, last = observations[0].observed_at, observations[-1].observed_at line = Text("heard ", style="muted") line.append(f"first {_when_label(first)} · last {_when_label(last)}") @@ -486,7 +480,7 @@ def _self_sections(ctx: AppContext, window: timedelta | None, width: int) -> lis volume = bucketize(stamps, start, now, buckets) out: list[RenderableType] = [] - out.append(_heading("Activity", f"{len(stamps)} sent · traces + messages")) + out.append(body_heading("Activity", f"{len(stamps)} sent · traces + messages")) out.extend( axis_chart( timeline_rows(volume, rows=_CHART_ROWS), @@ -502,7 +496,7 @@ def _self_sections(ctx: AppContext, window: timedelta | None, width: int) -> lis lo, hi = chart_span(medians) rows = timeline_rows(medians, rows=_SNR_ROWS, style=_snr_cell_style) out.append(Text()) - out.append(_heading("Reach", "trace bottleneck dB per slice · grey line = 0")) + out.append(body_heading("Reach", "trace bottleneck dB per slice · grey line = 0")) out.extend( axis_chart( rows, @@ -516,7 +510,7 @@ def _self_sections(ctx: AppContext, window: timedelta | None, width: int) -> lis out.append(Text()) out.append( - _heading("Rhythm", f"transmissions by local time of day · {_slice_note(slice_minutes)}") + body_heading("Rhythm", f"transmissions by local time of day · {_slice_note(slice_minutes)}") ) out.extend( axis_chart( @@ -529,7 +523,7 @@ def _self_sections(ctx: AppContext, window: timedelta | None, width: int) -> lis ) out.append(Text()) - out.append(_heading("Ledger", "this window")) + out.append(body_heading("Ledger", "this window")) first, last = stamps[0], stamps[-1] line = Text("active ", style="muted") line.append(f"first {_when_label(first)} · last {_when_label(last)}") @@ -996,7 +990,7 @@ def _mesh_sections( pkt_title, node_title = ( ("Packets per hour", "Nodes per hour") if hourly else ("Packets per day", "Nodes per day") ) - out.append(_heading(pkt_title, "local hours" if hourly else "local days")) + out.append(body_heading(pkt_title, "local hours" if hourly else "local days")) out.extend( axis_chart( timeline_rows(_day_columns(packets, chars), rows=_CHART_ROWS), @@ -1009,7 +1003,7 @@ def _mesh_sections( nodes = [d[2] for d in shown] out.append(Text()) - out.append(_heading(node_title, "distinct nodes heard")) + out.append(body_heading(node_title, "distinct nodes heard")) out.extend( axis_chart( timeline_rows(_day_columns(nodes, chars), rows=_CHART_ROWS), @@ -1024,7 +1018,9 @@ def _mesh_sections( # keep their own finer width but share the day charts' gutter, so this chart's left # edge lines up with the two above it. out.append(Text()) - out.append(_heading("Rhythm", f"packets by local time of day · {_slice_note(slice_minutes)}")) + out.append( + body_heading("Rhythm", f"packets by local time of day · {_slice_note(slice_minutes)}") + ) out.extend( axis_chart( timeline_rows(slots, rows=_CHART_ROWS), @@ -1040,7 +1036,7 @@ def _mesh_sections( # below (every heard node *is* a first-seen node, so the counts agree). heard = ctx.repo.heard_nodes() out.append(Text()) - out.append(_heading("Arrivals", "nodes heard for the first time ever")) + out.append(body_heading("Arrivals", "nodes heard for the first time ever")) if not arrivals: out.append(Text("none in this window", style="muted")) else: @@ -1095,7 +1091,7 @@ def _mesh_sections( total_nodes = sum(1 for n in heard if n.node) busiest = max(all_days, key=lambda d: d[1]) out.append(Text()) - out.append(_heading("Ledger", "everything ever recorded")) + out.append(body_heading("Ledger", "everything ever recorded")) out.append( Text.assemble( ("history ", "muted"), diff --git a/meshterm/ui/widgets.py b/meshterm/ui/widgets.py index 0ad0d8b..07d16cc 100644 --- a/meshterm/ui/widgets.py +++ b/meshterm/ui/widgets.py @@ -917,6 +917,28 @@ def _format_age(secs: float | None) -> str: return f"{int(secs // 604800)}w" +def body_heading(title: str, note: str = "") -> Text: + """A section heading inside a screen's body: accent title, optional muted `` · note``. + + THE form for a heading that sits *in* a page's prose or drawings (the Time Machine's + Volume / SNR / Rhythm, a record's Stats / Area walked / Route), as opposed to a grouped + list's ``── Label ──`` landmark (:func:`~meshterm.ui.menus.section_heading`), which + pins and is jumped to. The note reads the block back — its unit, its window, what its + labels mean — and is muted so the title stays the landmark. + + Args: + title: The section's name, sentence case. + note: An aside after the roomy separator, or ``""`` for none. + + Returns: + The heading as one styled line. + """ + text = Text(title, style="accent") + if note: + text.append(f" · {note}", style="muted") + return text + + def format_ago(secs: float | None) -> str: """The relative-age *phrase* — ``now``, ``5m ago``, ``never`` — for running prose. diff --git a/tests/test_records_screen.py b/tests/test_records_screen.py index eb36c9e..5c5d7fb 100644 --- a/tests/test_records_screen.py +++ b/tests/test_records_screen.py @@ -109,11 +109,13 @@ def test_record_dialog_shows_stats_route_and_the_trace_action() -> None: def test_record_dialog_draws_the_walk_as_a_route_graph() -> None: """The walk is drawn on THE route graph — us starred at both ends, over a caption.""" - body = _plain(_dialog(_record()).render_body(60)) - graph = body[: body.index("labels = hash byte")] + lines = _plain(_dialog(_record()).render_body(60)).splitlines() + heading = next(i for i, line in enumerate(lines) if line.startswith("Route")) + assert "you → … → you" in lines[heading] and "labels = hash byte" in lines[heading] + legend = next(i for i, line in enumerate(lines) if "▲ repeater" in line) + graph = "\n".join(lines[heading + 1 : legend]) # the drawing, up to its legend assert graph.count("★") == 2 # our node marks both endpoints of the round trip - assert "labels = hash byte" in body # the graph's caption - assert any("⠀" <= ch <= "⣿" for ch in body) # braille edges are drawn + assert any("⠀" <= ch <= "⣿" for ch in graph) # braille edges are drawn def test_record_graph_is_only_as_tall_as_one_lane_needs() -> None: @@ -138,17 +140,17 @@ def test_record_dialog_route_runs_unlabelled_across_the_whole_card() -> None: """ dialog = _dialog(_record(route=tuple([HUB_ID, FAR_ID] * 4))) body = _plain(dialog.render_body(60)).splitlines() - spec_at = next(i for i, line in enumerate(body) if line.startswith("spec")) - # The route's own first line: the last one before the spec that isn't a hanging fold. - route_at = next(i for i in range(spec_at - 1, 0, -1) if not body[i].startswith(" ")) - route = body[route_at:spec_at] + # The route closes the Route section: it runs from under the graph's legend to the + # blank line before the action rows. + legend_at = next(i for i, line in enumerate(body) if "▲ repeater" in line) + route = body[legend_at + 1 : body.index("", legend_at)] assert not route[0].startswith("route") # no label lane assert route[0].startswith("★") # our end opens the walk on the app-wide star… assert route[-1].endswith("★") # …and closes it on the same assert "Homestead" not in "".join(route) # never our name, and never our key assert "Hilltop-Repeater" in "".join(route) # the hops themselves are named in full assert len(route) > 1 # it folded rather than truncating… - # …every fold hanging under the step, and the labelled lanes resume at the spec. + # …every fold hanging under the step. assert all(line.startswith(" ") for line in route[1:]) @@ -310,26 +312,49 @@ def test_record_draws_the_enclosed_area_under_the_stats_with_hash_byte_pins() -> ).splitlines() first_blank = lines.index("") stats = lines[:first_blank] - assert stats[0].startswith("score") + assert stats[0] == "Stats" # under its own heading… + assert stats[1].startswith("spec") and stats[2].startswith("recorded") # …identity first + assert stats[3].startswith("score") assert not any(_is_braille(ch) for ch in "\n".join(stats)), "no drawing beside the lanes" assert "Far" in "\n".join(stats) # the far-point name is a stat, not a drawing label area = lines[first_blank + 1 : lines.index("", first_blank + 1)] - block = "\n".join(area) + assert area[0].startswith("Area walked") and "labels = hash byte" in area[0] # heading + block = "\n".join(area[1:]) assert any(_is_braille(ch) for ch in block) # the area, in braille assert "★" in block # us pinned at the origin assert "▲" in block # the repeater vertex, in its map glyph assert HUB_ID[:2] in block and FAR_ID[:2] in block # each hop's hash byte beside its pin - assert area[-1].startswith("area walked") # the caption closes the block - graph_caption = next(i for i, line in enumerate(lines) if line.startswith("you → … → you")) - assert graph_caption > lines.index(area[-1]), "the route graph follows the drawing" + assert len(area) - 1 >= 8, "the drawing spends the rows it is given" + # The three section headings, in reading order: each opens its block right after a + # blank line, so a page this tall can be skimmed by its landmarks. + at = { + name: next(i for i, line in enumerate(lines) if line.split(" · ")[0] == name) + for name in ("Stats", "Area walked", "Route") + } + assert at["Stats"] < at["Area walked"] < at["Route"] + assert all(lines[i - 1] == "" for name, i in at.items() if name != "Stats") + assert at["Route"] > lines.index(area[-1]), "the route graph follows the drawing" + + +def test_record_area_drawing_spends_the_width_it_is_given() -> None: + """The drawing is as wide as the page: a wider page is a bigger, not a padded, shape.""" + narrow = _plain(_dialog(_record(), shape=_loop_shape()).render_body(40)).splitlines() + wide = _plain(_dialog(_record(), shape=_loop_shape()).render_body(72)).splitlines() + + def drawn_width(lines: list[str]) -> int: + start = next(i for i, line in enumerate(lines) if line.startswith("Area walked")) + 1 + block = lines[start : lines.index("", start)] + return max(len(line.rstrip()) for line in block) + + assert drawn_width(wide) > drawn_width(narrow) def test_record_drops_the_area_drawing_when_too_narrow() -> None: """Below the drawing's floor the block is left out; the far name stays in the stats.""" body = _plain(_dialog(_record(), far_label="Far", shape=_loop_shape()).render_body(14)) lines = body.splitlines() - assert "area walked" not in body # no drawing, no caption for one + assert "Area walked" not in body # no drawing, no heading for one # The stats run straight into the blank line before the route graph; nothing pinned. assert "★" not in "\n".join(lines[: lines.index("")]) assert "Far" in body # the far-point name survives the drop