Files
MeshTerm/meshterm/ui/braillechart.py
T
Jean-Pierre MartineauandClaude Fable 5 7f1d8e7d10 Day charts: even dot-split columns, packed right-first ticks, honest y-marks
Day bars now share the chart's dot columns via one floor-edge split
(_day_spans), so widths never differ by more than one dot and the wider
days interleave with the narrower ones instead of pooling on the left.
Every day at least three dots wide opens with its notch — the oldest
day's doubling as its clearance off the axis border.

Axis ticks pack as dense as two blank cells between labels allow,
claimed newest day first, oldest second, then right to left, so a
crowded axis thins from the middle-left instead of down to an evenly
spaced handful. Months are written on the calendar anchors (the oldest
day and the first of a month) rather than tracked across placed ticks.

The y-gutter's ┤ tick crosses a braille row at its third dot, so each
mark now quotes the value of a bar peaking at that dot — computed with
timeline_rows' own baseline math — instead of the row's top edge, which
sat a dot above where the glyph points.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-12 21:09:12 -04:00

598 lines
27 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.
"""Braille charts: the one way MeshTerm draws a value-over-time row or a meter.
Every timeline in the app — the header's activity pulse, the channel manager's
per-channel sparklines, the dashboard's tall packet chart, the Time Machine's
histories — renders through this module, so they all share the same three rules:
* **Time flows left → right.** The rightmost column is *now*; history trails away
to the left. Chronological (oldest-first) series feed :func:`timeline_rows`
directly; the newest-first histograms the monitor and repository keep are passed
as-is to :func:`activity_sparkline`, which reverses them into place.
* **Grey is zero.** Every chart draws a faint one-dot baseline at value zero and
bars grow *from that line*, so a silent stretch reads as a flatline, never a
hole. When a series carries negative values (an SNR history, say) the baseline
sits at zero's height inside the chart — positive readings rise above it,
negative ones hang below — rather than being nailed to the chart floor. The one
deliberate break in the line is :data:`GAP`, a column that renders *fully blank*
down to the axis, used to notch adjacent bars apart (the Time Machine's per-day
charts space one day from the next this way).
* **Two readings per cell.** Braille offers two dot columns per character cell;
every chart uses both, so each cell shows two consecutive readings and the
chart draws at twice the horizontal resolution of the cells it occupies.
The low-level cell assembly is shared: bars are expressed as inclusive dot-row
spans anchored on the baseline, and each character cell takes the bar style when
any bar dot falls in it, the faint baseline style when only the zero line does,
and stays blank braille otherwise (blank braille, not a space, so the grid stays
monospace under fonts with slightly odd braille metrics).
Beyond timelines, the module owns the app's two other braille conventions:
* :func:`meter` — the single-value horizontal bar (the dashboard's traffic
tallies, the SNR quality bars), always packing two fill steps per cell so a
``width``-cell meter resolves ``2 × width`` levels.
* :func:`axis_caption` — the ``oldest → now`` line under a timeline, which
fills in intermediate marks whenever the chart is wide enough to fit them.
* :func:`axis_chart` — frames :func:`timeline_rows` output in a mirrored
numeric y-axis (the dashboard's activity chart, the Time Machine's per-day
and rhythm charts), so a chart quotes its scale on the gutters instead of
just naming the peak in its heading.
"""
from __future__ import annotations
from bisect import bisect_right
from typing import Callable, Optional, Sequence, Union
from rich.text import Text
#: Braille dot bit for each dot row counted from the *bottom* of a cell (row 0 is
#: the cell's lowest dot), left and right columns. The Unicode braille block
#: numbers its rows top-down (dots 1,2,3,7 left / 4,5,6,8 right); these tables
#: flip that so chart math can stay in bottom-up "height" space throughout.
_LEFT_BITS = (0x40, 0x04, 0x02, 0x01)
_RIGHT_BITS = (0x80, 0x20, 0x10, 0x08)
#: How a lit cell is styled: a fixed Rich style name, or a callable given the
#: cell's present readings (one or two values) returning the style — the hook the
#: Time Machine uses to colour an SNR band by each slice's quality.
CellStyle = Union[str, Callable[[list[float]], str]]
class _Gap:
"""The type of :data:`GAP`; a private singleton, so ``value is GAP`` identifies it."""
__slots__ = ()
def __repr__(self) -> str: # pragma: no cover - a debugging aid only
return "GAP"
#: A timeline value marking a hard gap: the column renders *fully blank* — no bar and
#: no zero baseline — so it breaks the "grey is zero" flatline on purpose. ``None`` and
#: ``0`` still draw the faint zero line (a silent reading is still a reading); only
#: ``GAP`` punches a hole in it, used to notch adjacent day bars apart in the Time
#: Machine's per-day charts so same-height neighbours never fuse into one solid block.
GAP = _Gap()
def chart_span(
values: Sequence[Optional[float]], span: Optional[tuple[float, float]] = None
) -> tuple[float, float]:
"""The vertical range a chart of ``values`` draws over, zero always included.
The grey baseline *is* zero, so the span is the data's extent folded around it:
all-positive data spans ``0 → peak`` (the baseline on the floor), all-negative
data ``floor → 0`` (the baseline on the ceiling, bars hanging), mixed data both.
Callers that caption their chart's scale should quote this same span so the
label and the drawing can never disagree.
Args:
values: The chart's readings (``None`` marks an empty slot; :data:`GAP` a
hard gap — neither carries a magnitude, so both sit out the span).
span: An optional wider range to honour (it too is folded around zero).
Returns:
``(lo, hi)`` with ``lo <= 0 <= hi``; ``(0.0, 0.0)`` for an empty series.
"""
present = [v for v in values if v is not None and v is not GAP]
if span is not None:
present = [*present, *span]
lo = min([0.0, *present])
hi = max([0.0, *present])
return lo, hi
def timeline_rows(
values: Sequence[Optional[float]],
*,
rows: int = 1,
span: Optional[tuple[float, float]] = None,
style: CellStyle = "ok",
baseline_style: str = "faint",
column_styles: Optional[Sequence[str]] = None,
) -> list[Text]:
"""Render a chronological series as a braille bar chart, newest at the right.
``values`` is oldest-first, one reading per dot column (two per character
cell), scaled onto :func:`chart_span`'s zero-folded range: the series' peak
fills the space above the baseline, its floor the space below, and any
non-zero reading lights at least one dot so a lone packet never vanishes.
``None`` (no reading) and ``0`` alike draw only the faint zero baseline;
:data:`GAP` draws nothing at all, breaking the baseline into a clean notch.
Args:
values: Per-slot readings, oldest first (the rightmost is "now"). An odd
count is padded with one silent column so whole cells always render.
A :data:`GAP` slot renders fully blank (bar and baseline both).
rows: How many braille rows tall the chart is (four dot rows each).
span: A wider range to scale against (see :func:`chart_span`), so several
charts — or a chart and its caption — can share one scale.
style: Style for lit cells: a Rich style name, or a callable given each
cell's present readings (for per-slice colouring).
baseline_style: Style for the zero line where nothing covers it.
column_styles: Optional per-column styles, aligned with ``values``,
overriding ``style`` — how the activity charts dim history recorded by
an earlier session. A cell straddling two styles takes its newer
(right) lit column's.
Returns:
``rows`` :class:`Text` lines, top row first, ``ceil(len(values)/2)``
characters wide.
"""
lo, hi = chart_span(values, span)
total = rows * 4
base = _baseline_row(lo, hi, total)
up = total - base # dot rows available to a full-scale positive bar
down = base + 1 # …and to a full-scale negative one (baseline row included)
bars: list[Optional[tuple[int, int]]] = []
for value in values:
# GAP must short-circuit ahead of the numeric tests — it has no magnitude,
# so ``value == 0`` / ``value > 0`` would misfire (or raise) on the sentinel.
if value is GAP or value is None or value == 0:
bars.append(None)
elif value > 0:
height = max(1, round(value / hi * up))
bars.append((base, base + height - 1))
else:
height = max(1, round(value / lo * down))
bars.append((base - height + 1, base))
return _assemble(bars, list(values), rows, base, style, baseline_style, column_styles)
def activity_sparkline(
histogram: Sequence[int],
levels: tuple[int, ...],
buckets: int,
*,
style: str = "ok",
column_styles: Optional[Sequence[str]] = None,
) -> Text:
"""A one-row activity sparkline over a newest-first histogram, "now" rightmost.
Bar heights are absolute, stepped at ``levels`` (the count a bucket must reach
for each extra dot), so the same traffic always draws the same bar regardless
of what else is on screen and a lone packet never vanishes. The histogram
arrives newest-first — the natural order the monitor and repository keep — and
is reversed here, so the current bucket lands on the right edge and traffic
slides *left* as it ages, like every other MeshTerm timeline.
Args:
histogram: Per-bucket counts, newest first; padded/cropped to ``buckets``.
levels: Ascending count thresholds for bar heights 1..4.
buckets: How many buckets to draw (half this many characters).
style: Style for lit cells.
column_styles: Optional per-bucket styles aligned with ``histogram``
(newest first, reversed here alongside it), overriding ``style`` —
how the header pulse dims buckets recorded by an earlier session.
Returns:
A styled Rich :class:`Text` of ``buckets / 2`` braille characters.
"""
window = (tuple(histogram) + (0,) * buckets)[:buckets]
per_column: Optional[list[str]] = None
if column_styles is not None:
padded = (list(column_styles) + [style] * buckets)[:buckets]
per_column = list(reversed(padded))
bars: list[Optional[tuple[int, int]]] = []
for count in reversed(window):
height = bisect_right(levels, count)
bars.append((0, height - 1) if height else None)
return _assemble(
bars, [float(c) for c in reversed(window)], 1, 0, style, "faint", per_column
)[0]
#: The meter's fill glyphs, ``(full step, half step)``, by profile. A *full-height*
#: meter lights all four dot rows (``⣿`` both columns, ``⡇`` the left column alone),
#: reading as a solid tally bar. A *slim* meter lights only the middle two rows
#: (``⠶`` / ``⠆``), so the bar floats mid-cell and can sit over an unlit track of the
#: same glyph without turning into a solid block.
_METER_FULL = ("⣿", "⡇")
_METER_SLIM = ("⠶", "⠆")
def meter(
fraction: Optional[float],
width: int,
*,
style: str,
slim: bool = False,
track: Optional[str] = None,
) -> Text:
"""Render a single value as a horizontal braille meter, two fill steps per cell.
The one way MeshTerm draws a proportion as a bar. Both dot columns of every cell
are always exploited — a ``width``-cell meter resolves ``2 × width`` levels — and
any *reading* lights at least one half step, even one clamped to the floor of its
scale: a measured bottom is still a measurement, so it never vanishes (``None``
is how a truly empty meter is asked for). Two profiles cover the app's two cases:
* **full-height, no track** (the default): all four dot rows, unlit cells left
blank — a tally bar whose length *is* the reading (the dashboard's traffic
lanes).
* **slim, on a track** (``slim=True, track="track"``): only the middle two dot
rows, with the unlit remainder drawn in the same glyph dimmed to ``track`` — a
gauge whose reading fills in a visible background (the SNR quality bars). The
boundary half-step keeps the reading's colour, not the track's: it is still
part of what was measured.
Args:
fraction: The fill as a fraction of full scale, clamped to ``0 .. 1``;
``None`` draws an entirely unlit meter (just the track, if any).
width: The meter's full-scale span in character cells.
style: Style for the lit fill.
slim: Light only the middle two dot rows instead of all four.
track: Style for the unlit remainder, drawn in the full-step glyph; ``None``
pads with spaces instead, so the meter still occupies ``width`` cells.
Returns:
A :class:`Text` exactly ``width`` cells wide.
"""
full_glyph, half_glyph = _METER_SLIM if slim else _METER_FULL
if fraction is None:
steps = 0
else:
frac = min(1.0, max(0.0, fraction))
steps = max(1, round(frac * width * 2))
full, half = divmod(steps, 2)
bar = Text(full_glyph * full + half_glyph * half, style=style)
rest = width - full - half
if track is not None:
bar.append(full_glyph * rest, style=track)
else:
bar.append(" " * rest)
return bar
def axis_caption(
chars: int,
label_at: Callable[[float], str],
*,
style: str = "faint",
) -> tuple[Text, list[int]]:
"""The caption line under a timeline: edge labels plus whatever marks fit between.
Every chart used to caption only its ends (``oldest … now``); this asks
``label_at`` for the labels at the quarter points too and keeps the densest set
that fits — quarters, else the midpoint, else just the two ends — so a wide chart
reads its timescale without counting cells. The first label is left-aligned on the
chart's left edge, the last right-aligned on its right edge, and interior labels
are centred on the fraction they describe, each separated by at least two blank
cells so they never run together.
Args:
chars: The chart's width in character cells (the caption matches it).
label_at: Maps a position fraction (``0.0`` = the oldest column, ``1.0`` =
now) to its label.
style: Style the whole caption is drawn in.
Returns:
``(caption, tick_cells)`` — the caption :class:`Text` exactly ``chars`` cells
wide, and the chart column each placed label points at, so the axis border can
notch a ``┬`` under it (see :func:`axis_chart`).
"""
for segments in (4, 2, 1):
fractions = [i / segments for i in range(segments + 1)]
labels = [label_at(f) for f in fractions]
cells: list[str] = [" "] * chars
taken: list[tuple[int, int]] = [] # placed [start, end) spans, in order
ticks: list[int] = [] # the chart column each label points at
ok = True
for frac, label in zip(fractions, labels):
if frac == 0.0:
start = 0
ref = 0
elif frac == 1.0:
start = chars - len(label)
ref = chars - 1
else:
centre = round(frac * chars)
start = min(chars - len(label), max(0, centre - len(label) // 2))
ref = min(chars - 1, centre)
end = start + len(label)
if end > chars or any(start < e + 2 and s < end + 2 for s, e in taken):
ok = False
break
taken.append((start, end))
ticks.append(ref)
cells[start:end] = label
if ok:
return Text("".join(cells), style=style), ticks
# Even the two edge labels collide: keep the left one and let it stand alone.
label = label_at(0.0)[:chars]
return Text(label.ljust(chars), style=style), [0]
def y_axis_labels(peak: float, rows: int, *, lo: float = 0.0) -> list[str]:
"""Each chart row's ticked-dot value, top row first, dupes and zeros blanked.
The gutter's ``┤`` tick crosses a braille row at the third dot up from the
row's bottom, so each mark quotes the value of a bar peaking *at that dot* —
the reading the tick visibly points at, not the row's top edge — using the
same zero-folded scaling :func:`timeline_rows` draws bars with (baseline row
and all). A mark that would repeat the one above (a low peak makes
neighbouring dots round to the same value) or read zero is left blank, so the
scale never shows the same number twice. A signed chart passes its floor as
``lo`` (``< 0``): marks above the grey zero line quote rise heights, marks
below it hang depths, so the gutter shows both signs of a zero-crossing
series (an SNR band's ``+5 … −10 dB``) instead of only the positive peak.
"""
total = rows * 4
base = _baseline_row(lo, peak, total)
labels: list[str] = []
seen: set[int] = set()
for i in range(rows):
dot = (rows - 1 - i) * 4 + 2 # the dot row this row's ┤ tick crosses
if dot > base:
value = round(peak * (dot - base + 1) / (total - base))
elif dot < base:
value = round(lo * (base - dot + 1) / (base + 1))
else:
value = 0 # the tick sits on the zero baseline itself
if peak != lo and value and value not in seen:
labels.append(str(value))
seen.add(value)
else:
labels.append("")
return labels
#: Minimum blank cells kept between two column-axis labels, so a thinned tick row
#: reads as separate marks rather than a run of touching text.
_TICK_GAP = 2
def _tick_axis(
chars: int,
label_w: int,
ticks: Sequence[tuple[int, str]],
style: str,
) -> tuple[Text, str]:
"""Build the boxed border and its caption for a column chart with explicit ticks.
Each tick is a ``(cell, label)`` pointing at a chart column: the border draws a
``┬`` at that column and the label sits centred beneath it. Labels are placed
left to right and any that would land within :data:`_TICK_GAP` cells of the one
before it is dropped — tick and all — so a crowded axis thins to what fits
instead of overprinting. Callers pre-thin to roughly the right count (see the
Time Machine's ``_day_ticks``); this is the collision backstop.
Args:
chars: The chart's width in character cells.
label_w: The y-axis gutter width the border and caption indent past.
ticks: ``(cell, label)`` marks, any order; ``cell`` is a 0-based chart column.
style: Style for the border (and its ticks).
Returns:
``(border, caption_text)`` — the border :class:`Text` and the plain caption
string, ready to indent under the gutter.
"""
cells = [" "] * chars
marked: list[int] = []
last_end = -_TICK_GAP
for cell, label in sorted(ticks):
cell = max(0, min(chars - 1, cell))
start = max(0, min(chars - len(label), cell - len(label) // 2))
if start < last_end + _TICK_GAP:
continue # would crowd the label before it — drop this mark
cells[start : start + len(label)] = list(label)
marked.append(cell)
last_end = start + len(label)
return _tick_border(chars, label_w, marked, style), "".join(cells)
def _tick_border(chars: int, label_w: int, tick_cells: Sequence[int], style: str) -> Text:
"""The boxed bottom border, notched with a ``┬`` at each charted tick column."""
marked = {max(0, min(chars - 1, c)) for c in tick_cells}
bar = "".join("┬" if i in marked else "─" for i in range(chars))
return Text(" " * label_w + " └" + bar + "┘", style=style)
def axis_chart(
chart_rows: list[Text],
peak: float,
chars: int,
label_at: Optional[Callable[[float], str]] = None,
*,
label_w: Optional[int] = None,
style: str = "muted",
floor: float = 0.0,
ticks: Optional[Sequence[tuple[int, str]]] = None,
) -> list[Text]:
"""Frame :func:`timeline_rows` output with a mirrored y-axis and x-axis caption.
Each row's top-edge value is mirrored on both gutters (blank where it would
repeat the mark above or read zero), closed with a boxed bottom border, and
followed by an x-axis caption indented to clear the gutter.
The caption comes one of two ways. A *continuous* chart passes ``label_at`` and
the ends-plus-quarters marks of :func:`axis_caption` fill in whatever fits. A
*columnar* chart — bars of a fixed width apiece, a day or a slot each — instead
passes ``ticks``: explicit ``(cell, label)`` marks that centre a label under its
own column and notch the border with a ``┬`` beneath it (see :func:`_tick_axis`),
so a date sits under the bar it names rather than at an arbitrary fraction.
Args:
chart_rows: The chart's rows, as returned by :func:`timeline_rows`.
peak: The chart's full-scale ceiling (its tallest bar's value); each
row's gutter mark quotes the value at the dot its tick points at
(see :func:`y_axis_labels`), so the peak itself sizes the gutter
but is not necessarily printed.
chars: The chart's width in character cells.
label_at: Maps a position fraction to the x-axis caption at that point
(a continuous chart); ignored when ``ticks`` is given.
label_w: The gutter's digit width, when several stacked charts must
share one width so their gutters line up; sized from ``peak`` (and
``floor``) by default.
style: Style for the gutters, ticks, marks, and border.
floor: The value the bottom edge reads on a signed chart (``< 0``), so
the gutter quotes both extremes of a zero-crossing series (the Time
Machine's SNR band). Defaults to ``0`` — an all-positive chart whose
baseline sits on the floor, the common case.
ticks: Explicit ``(cell, label)`` column marks for a columnar chart; when
given they drive the border and caption instead of ``label_at``.
Returns:
``len(chart_rows) + 2`` :class:`Text` lines: the decorated rows, the
bottom border, and the caption.
"""
label_w = label_w or max(1, len(str(round(peak))), len(str(round(floor))))
marks = y_axis_labels(peak, len(chart_rows), lo=floor)
out: list[Text] = []
for mark, row in zip(marks, chart_rows):
line = Text(f"{mark:>{label_w}} " + ("┤" if mark else "│"), style=style)
line.append_text(row)
line.append("├" if mark else "│", style=style)
if mark:
line.append(f" {mark}", style=style)
out.append(line)
if ticks is not None:
border, caption_text = _tick_axis(chars, label_w, ticks, style)
caption = Text(" " * (label_w + 2))
caption.append(caption_text, style="faint")
else:
assert label_at is not None, "axis_chart needs label_at or ticks"
# A continuous axis notches the same ┬ ticks under its ends-and-quarters
# labels as a columnar one does under its bars — one axis grammar everywhere.
caption_body, tick_cells = axis_caption(chars, label_at)
border = _tick_border(chars, label_w, tick_cells, style)
caption = Text(" " * (label_w + 2))
caption.append_text(caption_body)
out.append(border)
out.append(caption)
return out
def _baseline_row(lo: float, hi: float, total: int) -> int:
"""The dot row (from the chart bottom) the zero baseline sits on.
All-positive data pins it to the floor, all-negative to the ceiling; a mixed
span places it proportionally, clamped one row in from either edge so both
directions keep at least one dot row to draw in.
Args:
lo: The span's floor (``<= 0``).
hi: The span's ceiling (``>= 0``).
total: The chart's height in dot rows.
Returns:
The baseline's dot row, ``0 .. total - 1``.
"""
if lo == 0:
return 0
if hi == 0:
return total - 1
return min(total - 2, max(1, round((total - 1) * -lo / (hi - lo))))
def _column_bits(bar: Optional[tuple[int, int]], floor: int, table: tuple[int, ...]) -> int:
"""The braille bits one column's bar lights within a cell row.
Args:
bar: The bar's inclusive dot-row span (chart coordinates), or ``None``.
floor: The cell row's bottom dot row in chart coordinates.
table: :data:`_LEFT_BITS` or :data:`_RIGHT_BITS`.
Returns:
The OR of the covered dots' bits (0 when the bar misses this cell row).
"""
if bar is None:
return 0
lo, hi = max(bar[0], floor), min(bar[1], floor + 3)
bits = 0
for dot in range(lo, hi + 1):
bits |= table[dot - floor]
return bits
def _assemble(
bars: list[Optional[tuple[int, int]]],
values: list[Optional[float]],
rows: int,
base: int,
style: CellStyle,
baseline_style: str,
column_styles: Optional[Sequence[str]] = None,
) -> list[Text]:
"""Assemble bar spans into styled braille rows (the shared cell walk).
Every bar span includes the baseline row by construction, so a half-silent
cell keeps the zero line continuous inside the lit character; a fully silent
cell shows just the faint baseline dots on whichever row holds them; anything
else stays blank braille to keep the grid monospace. The baseline is decided
per *dot column*, not per cell, so a :data:`GAP` column can go fully blank —
breaking the zero line into a notch — while its cell-mate keeps its own.
Args:
bars: Per-column inclusive dot-row spans (``None`` = no bar).
values: The readings behind the columns, aligned with ``bars`` (fed to a
callable ``style`` two at a time, per cell); a :data:`GAP` reading
suppresses that column's baseline so the notch reaches the axis.
rows: Chart height in braille rows.
base: The zero baseline's dot row.
style: Fixed style, or per-cell callable (see :data:`CellStyle`).
baseline_style: Style for baseline-only cells.
column_styles: Per-column style overrides aligned with ``bars``; a cell
takes its right column's style when that column is lit, else its
left's (the newer reading wins the shared cell).
Returns:
``rows`` :class:`Text` lines, top row first.
"""
if len(bars) % 2:
bars = [*bars, None]
values = [*values, None]
lines: list[Text] = []
for row in range(rows):
floor = (rows - 1 - row) * 4
base_bit_left = _LEFT_BITS[base - floor] if floor <= base <= floor + 3 else 0
base_bit_right = _RIGHT_BITS[base - floor] if floor <= base <= floor + 3 else 0
line = Text()
for i in range(0, len(bars), 2):
# A GAP column carries no baseline, so the zero line breaks there and the
# notch runs clean from the top edge down to the axis border.
bl = 0 if values[i] is GAP else base_bit_left
br = 0 if values[i + 1] is GAP else base_bit_right
left = _column_bits(bars[i], floor, _LEFT_BITS)
right = _column_bits(bars[i + 1], floor, _RIGHT_BITS)
if left or right:
mask = left | right | bl | br
if column_styles is not None and i + 1 < len(column_styles):
cell_style = column_styles[i + 1] if right else column_styles[i]
elif callable(style):
present = [
v for v in values[i : i + 2] if v is not None and v is not GAP
]
cell_style = style(present) if present else baseline_style
else:
cell_style = style
line.append(chr(0x2800 | mask), style=cell_style)
elif bl or br:
line.append(chr(0x2800 | bl | br), style=baseline_style)
else:
line.append(chr(0x2800))
lines.append(line)
return lines