Files
MeshTerm/meshterm/ui/tui/fkeys.py
T
Jean-Pierre MartineauandClaude Opus 5.5 b6e7cd5c16 The handhelds are named for their variant: picocalc-lyra and cardputer-zero
M5Stack makes three Cardputers and only the Zero runs Linux; the PicoCalc
takes several cores and only the Luckfox Lyra runs MeshTerm. So the bare
names were ambiguous, and every reference to the two devices now carries
the variant: the --platform values and MESHTERM_PLATFORM, the Platform
constants (PICOCALC_LYRA, CARDPUTER_ZERO), their lane decks and every
screen's picocalc_lyra_lane / cardputer_zero_lane, the font inventories,
the lane chips' theme styles, the scripts/ folders, the two chrome test
files, and the docs and CLAUDE.md that name them.

There is no alias: --platform picocalc is refused with the three real
choices listed, rather than falling back to the desktop layout. The
PicoCalc is auto-detected from its device tree, so it needs nothing.
What names hardware or a user's data keeps its name: the PicoCalc
keyboard's input-device name, its battery's sysfs supply, and the serial
profile the Lyra setup script writes. .gitignore follows the firmware's
folder, and the changelog keeps the words each release used.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-04 11:52:41 -04:00

421 lines
20 KiB
Python

# SPDX-License-Identifier: Apache-2.0
"""The F-key lane: a handheld's fixed footer row of coloured chips, one per function key.
**Each platform deals its own lane** (JP, 2026-09-30). What a lane *is* — slots of
:class:`FPair`, dimmed or live, stripped from a dialog's hint — is shared; everything that
belongs to one keyboard is a :class:`LaneDeck`, named by ``Platform.lane_deck``: which
keycodes drive the slots, where the chips sit on the row, how they are drawn, and which of
a screen's lane definitions it reads. A screen states its lane per deck —
``Screen.picocalc_lyra_lane``, ``Screen.cardputer_zero_lane`` — and the Cardputer's follows the
PicoCalc's until a screen says otherwise. Both decks having five slots is a coincidence of
two keyboards, not a rule, and nothing here assumes it: a deck's slot count is its keys.
The rest of this docstring is the PicoCalc deck's design, which the Cardputer's deals for
now. The PicoCalc keyboard has five dedicated function keys; its MCU translates Shift+F1..F5
into plain F6-F10 keycodes (measured in P0), so "Shift+key = the opposite action" is
literal hardware behaviour and the app simply binds all ten.
By JP's spec (2026-08-01): a lane slot is for functionality that would otherwise be
*hard to reach* — not a shortcut to a key that is already close at hand. Enter and Esc
sit right on the keyboard and are already the easiest keys to hit, so they never occupy
a slot. Paging has no physical key at all, so a screen that scrolls earns it the prime
F4/F5 pair. Ctrl+letter chords (Ctrl+P for message paths, Ctrl+arrows for a sort column,
…) are fiddly to hold on this keyboard, so a screen promotes its own onto the free
F1-F3 bank. The five *plain* keys carry a screen's most-used, otherwise-awkward actions
— reachable with no Shift at all — and the Shift bank (F6-F10) holds each slot's
*opposite number*, not unrelated overflow. A lane can, and does, differ from screen to
screen.
**Second-grade keys ride their own pair's Shift half** (JP, 2026-08-08). Home and End
*are* on this keyboard, so jumping to either end of a body was never the unreachable
thing paging is — it only ever wanted a chip for consistency with the pager it belongs
to. So it rides that pager: Shift+F5 (``F10``) is Top because F5 is Page ↑, Shift+F4
(``F9``) is Bottom because F4 is Page ↓. One axis, one pair of slots, the jump sitting
behind the page on the very same key. That leaves **F1-F3 free on every screen** for the
verbs a screen actually has to offer, which is where the interesting work goes.
**A chip names an action, never a key** (JP, 2026-08-07). ``PgUp``, ``End`` and their
kin are the names of keys this keyboard doesn't even have; what the slot is for is the
thing it does *here* — ``Page ↑`` through a body, ``Latest`` on a transcript, ``Reset``
on the map, whose Home key refits the view and whose paging keys zoom. A screen that
repurposes a shared action relabels it; a screen the action means nothing on leaves the
slot **empty** rather than filling the lane out. Empty and dim are different claims:
empty says *not a thing here* (Retry in a channel, where nothing is ever acknowledged),
dim says *a thing here, just not right now* (Retry in a direct chat with everything
delivered).
A screen describes its lane as five :class:`FPair` slots (``None`` = unassigned); the
session resolves a pressed F-key to the slot's action string and dispatches it through
the normal action funnel, so screens gain F-key support without any key handling of
their own. An :class:`FPair` need not carry a Shift-bank action at all — a "lone" slot
(``opp_label=""``) simply renders blank in the shifted bank and F(n+5) does nothing.
**A slot never advertises a key that would do nothing.** The lane is the PicoCalc's whole
footer — it stands in for the hint line the other platform draws, and that line has always
dropped an atom whose key is inert (see :attr:`~meshterm.ui.tui.screen.Screen.content_overflows`).
So a screen rebuilds its lane each paint and clears :attr:`FPair.enabled` /
:attr:`FPair.opp_enabled` on whatever is out of reach right now: the chat's *Paths* with
no message picked, its *Retry* with nothing unacknowledged, the shared nav slots on a
screen with nothing to move (:func:`default_lane`). A dimmed slot keeps its label — muted,
unfilled, like an unassigned slot — so the key still reads as *what it would do*, it just
plainly isn't live. The dimming is presentational: the screen's own ``handle`` stays the
authority on what an action does (it no-ops), so a lane built from one-paint-stale metrics
can never swallow a key that would have worked.
"""
from __future__ import annotations
from collections.abc import Callable, Sequence
from dataclasses import dataclass, replace
from operator import attrgetter
from typing import Any
from rich.text import Text
from ...platforms import Platform, on_platform
#: A chip's label budget: every lane label is written to fit six cells.
_DESC_WIDTH = 6
@dataclass(frozen=True, slots=True)
class FPair:
"""One F-key slot: the plain-key action and its optional Shift-bank companion.
Attributes:
label: Verb-phrase hint for the plain key, e.g. ``"Zoom +"`` — what the key
*does* on this screen, never the key's own name (``"PgUp"``). Clipped/padded
to 6 cells.
action: The screen action the plain key dispatches (``"home"``, ``"enter"``, …).
opp_label: Hint for the Shift-bank companion, or ``""`` for a lone slot with no
companion — the shifted bank then renders that chip blank and the
corresponding F(n+5) does nothing.
opp_action: The action the Shift-bank companion dispatches, or ``""``.
enabled: Whether the plain key's action is available *right now*. ``False`` draws
the chip dimmed — label kept, fill dropped — rather than pretending (see the
module docstring).
opp_enabled: The same, for the Shift-bank companion.
"""
label: str
action: str
opp_label: str = ""
opp_action: str = ""
enabled: bool = True
opp_enabled: bool = True
#: A lane is five slots, F1..F5 left to right; ``None`` leaves a slot unassigned.
Lane = Sequence[FPair | None]
#: The default lane, in the vocabulary of a screen that is one scrolling body: move
#: through it a page at a time (F4/F5), or — behind Shift, on those same two keys — jump
#: to the end each pager heads for (F9/F10). No Enter or Esc slot: both keys sit right on
#: the keyboard already. F1-F3 stay free for the screen's own verbs; a screen that has
#: none leaves them blank rather than filling the lane out. A screen whose body is not one
#: scrolling column says so in its own words (see :class:`ChatScreen`, ``MapScreen``).
#:
#: **A directional pair rises toward its outer key** (JP, 2026-08-08): wherever two
#: adjacent chips are opposite ends of one axis, the *up · in · more* end takes the slot
#: nearer the lane's own edge. On the right-hand F4/F5 pair that is F5 — the pager here,
#: the map's zoom, ``Zoom -`` then ``Zoom +``, a rocker — and on a left-hand F1/F2 pair it
#: is F1, so a select list reads ``Sect ↑`` then ``Sect ↓``: ergonomically the hand
#: anchors on the lane's edge and rocks inward, whichever side the pair lives on. A slot's
#: own Shift companion follows the same rule *along its slot*: the jump behind ``Page ↑``
#: is the one Page ↑ is heading for, so F10 is Top and F9 Bottom. A screen relabelling a
#: pair keeps its order (a chat's ``Latest``/``Oldest``).
DEFAULT_LANE: tuple[FPair | None, ...] = (
None,
None,
None,
FPair("Page ↓", "pagedown", "Bottom", "end"),
FPair("Page ↑", "pageup", "Top", "home"),
)
#: The lane of a screen with no lane at all: a confirm dialog, a busy spinner, a text
#: prompt. Nothing there pages or jumps, so the shared pager is not dim-but-real, it is
#: simply *not a thing here* — the distinction the module docstring draws — and every slot
#: renders as a bare, unfilled key number.
EMPTY_LANE: tuple[FPair | None, ...] = (None, None, None, None, None)
def default_lane(*, nav: bool = True) -> tuple[FPair | None, ...]:
""":data:`DEFAULT_LANE`, with its pager slots dimmed unless ``nav``.
Both shared slots *move* something — the page, and the jump behind it — so on a screen
with nothing to move (a body that fits its viewport, a transcript with no messages)
both banks are inert and say so. Screens that repurpose the nav actions for something
always live (the map's zoom) build from :data:`DEFAULT_LANE` instead, relabelling as
they go.
Args:
nav: Whether the nav keys would do anything on this paint — typically
:attr:`~meshterm.ui.tui.screen.Screen.content_overflows`.
Returns:
The five slots, ready for a screen to overwrite the ones it claims.
"""
if nav:
return DEFAULT_LANE
return tuple(
None if pair is None else replace(pair, enabled=False, opp_enabled=False)
for pair in DEFAULT_LANE
)
@dataclass(frozen=True, slots=True)
class LaneDeck:
"""One platform's F-key lane: the keys that drive it, where it draws, whose lanes it reads.
The slots are left to right, and every per-slot tuple here has one entry per slot.
Attributes:
name: What ``Platform.lane_deck`` calls this deck.
keys: The F-key number each slot's plain key arrives as.
shift_keys: The F-key number each slot's Shift companion arrives as.
captions: How each slot's plain key is named on the row: leading a captioned
chip, and standing alone, muted, in a slot with nothing assigned.
shift_captions: The same, for the Shift bank.
columns: The column each chip starts at.
chip_width: Cells per chip.
captioned: Whether a live chip leads with its key's caption (``F1 Zoom +``) or
is its label alone, centred — for a keyboard whose key sits right under the
chip, where naming it again only costs the label cells.
fill: The theme style of a live chip in the plain bank.
shift_fill: The same, while the Shift watcher reports Shift held.
read_lane: Reads a screen's lane for this deck.
"""
name: str
keys: tuple[int, ...]
shift_keys: tuple[int, ...]
captions: tuple[str, ...]
shift_captions: tuple[str, ...]
columns: tuple[int, ...]
chip_width: int
captioned: bool
fill: str
shift_fill: str
read_lane: Callable[[Any], Lane]
def is_shift_key(self, number: int) -> bool:
"""Whether F-key ``number`` is one of this deck's Shift-bank keys."""
return number in self.shift_keys
def action_for(self, lane: Lane, number: int) -> str | None:
"""The action F-key ``number`` resolves to on this lane, or ``None``.
A plain key takes its slot's action, a Shift-bank key its companion — or nothing,
where the slot has none (a lone slot, or an unassigned one), and where the key is
not one of this deck's at all. A *dimmed* slot still resolves: dimming is how the
lane draws an action the screen would no-op anyway, and resolving it regardless
keeps a lane built from stale metrics from ever swallowing a key that works (see
the module docstring).
"""
if number in self.keys:
index, shifted = self.keys.index(number), False
elif number in self.shift_keys:
index, shifted = self.shift_keys.index(number), True
else:
return None
pair = lane[index] if index < len(lane) else None
if pair is None:
return None
if shifted:
return pair.opp_action or None
return pair.action
def lane_text(self, lane: Lane, *, shifted: bool = False) -> Text:
"""Render the lane as this deck's chips: coloured fill, white text, each at its column.
Args:
lane: The slots; any past this deck's last are not drawn.
shifted: Show the Shift bank, in :attr:`shift_fill`; the plain bank renders
in :attr:`fill`.
Returns:
A one-line :class:`Text`, ending with the last chip.
"""
fill = self.shift_fill if shifted else self.fill
captions = self.shift_captions if shifted else self.captions
row = Text()
for index, column in enumerate(self.columns):
row.append(" " * (column - row.cell_len))
pair = lane[index] if index < len(lane) else None
label = (pair.opp_label if shifted else pair.label) if pair else ""
if not label:
# Unassigned (no slot, or a lone slot's empty Shift bank): the bare key
# caption, unfilled — nothing to press here.
row.append(self._body(captions[index]), style="muted")
continue
live = pair.opp_enabled if shifted else pair.enabled
body = f"{captions[index]} {label[:_DESC_WIDTH]:<{_DESC_WIDTH}}"
# A dimmed slot drops the fill and keeps the label, landing in the same muted
# "nothing to press" class as an unassigned one — while still saying what the
# key is for once it becomes available.
row.append(
self._body(body if self.captioned else label[:_DESC_WIDTH]),
style=fill if live else "muted",
)
return row
def _body(self, text: str) -> str:
"""``text`` padded to exactly one chip: left-aligned when captioned, else centred."""
if self.captioned:
return f"{text:<{self.chip_width}}"
return f"{text:^{self.chip_width}}"
#: The PicoCalc's five dedicated function keys. Its keyboard MCU sends Shift+F1..F5 as
#: plain F6-F10, so the Shift bank is keys of its own. Every chip is a 2-cell key caption,
#: a space and a 6-cell label; five chips and four 2-cell gaps sum to exactly 53, the
#: console's width, with nothing left over.
PICOCALC_LYRA_DECK = LaneDeck(
name="picocalc-lyra",
keys=(1, 2, 3, 4, 5),
shift_keys=(6, 7, 8, 9, 10),
captions=("F1", "F2", "F3", "F4", "F5"),
shift_captions=("F6", "F7", "F8", "F9", "10"),
columns=(0, 11, 22, 33, 44),
chip_width=9,
captioned=True,
fill="fkey.chip",
shift_fill="fkey.chip.shift",
read_lane=attrgetter("picocalc_lyra_lane"),
)
#: The Cardputer Zero's number keys 4-8, which sit right under the display: Fn+4..8 are
#: F4-F8, never the bare digits, since a digit must stay a digit on a screen that takes
#: typing (JP, 2026-09-30). The keyboard driver sends Shift as a key of its own, and the
#: console host encodes Shift+Fn+4..8 the way xterm encodes Shift+F4..F8, which
#: prompt_toolkit reads as F16-F20 — so a desktop terminal with ``--platform cardputer-zero``
#: drives the same bank. The chips are laid out exactly as the PicoCalc's — the key's
#: caption leading a 6-cell label, nine cells a chip, two between (JP, 2026-09-30) — and
#: the Shift bank keeps the same captions, since it is the same keys with Shift held; its
#: blue fill is what says so. It reads the PicoCalc's lanes for now (see
#: :meth:`~meshterm.ui.tui.screen.Screen.cardputer_zero_lane`).
CARDPUTER_ZERO_DECK = LaneDeck(
name="cardputer-zero",
keys=(4, 5, 6, 7, 8),
shift_keys=(16, 17, 18, 19, 20),
captions=("F4", "F5", "F6", "F7", "F8"),
shift_captions=("F4", "F5", "F6", "F7", "F8"),
columns=PICOCALC_LYRA_DECK.columns,
chip_width=PICOCALC_LYRA_DECK.chip_width,
captioned=True,
fill="fkey.chip.cardputer_zero",
shift_fill="fkey.chip.cardputer_zero.shift",
read_lane=attrgetter("cardputer_zero_lane"),
)
#: Every deck, by the name ``Platform.lane_deck`` gives it.
DECKS: dict[str, LaneDeck] = {deck.name: deck for deck in (PICOCALC_LYRA_DECK, CARDPUTER_ZERO_DECK)}
_DECK: LaneDeck | None = None
def active_deck() -> LaneDeck | None:
"""The active platform's deck, or ``None`` where its footer is a hint line instead."""
return _DECK
@on_platform
def _bind(platform: Platform) -> None:
"""Deal the platform's deck (see :attr:`~meshterm.platforms.Platform.lane_deck`)."""
global _DECK
_DECK = DECKS[platform.lane_deck] if platform.lane_deck else None
#: The screen action each key notation in a footer hint dispatches — the vocabulary the
#: hint line and the lane have in common, and the only place the two can say the same
#: thing twice. Arrows, Enter, Esc and the letter chords are absent deliberately: no lane
#: slot ever claims them (Enter and Esc are barred outright), so an atom naming one can
#: never be a duplicate of a chip.
_HINT_KEY_ACTIONS: dict[str, str] = {
"PgUp": "pageup",
"PgDn": "pagedown",
"Home": "home",
"End": "end",
"^PgUp": "ctrl_pageup",
"^PgDn": "ctrl_pagedown",
"^Home": "ctrl_home",
"^End": "ctrl_end",
"Tab": "tab",
}
#: Marks a word as *some* key notation even where it isn't one this module can map: a
#: chord (``^Y``), a shifted key (``⇧Tab``), or a bare glyph key (``⌫``). An atom whose
#: verb half carries one of these names more than the keys it opened with, so it is never
#: dropped on the strength of the ones it did name (the map's ``Home/^Y region/you``).
_KEYISH = ("^", "⇧", "⌫", "↑", "↓", "←", "→")
def _hint_keys(atom: str) -> tuple[str, ...]:
"""The key notations ``atom`` opens with, or ``()`` where it names something else too.
A hint atom is *keys then verb* — ``PgUp/PgDn scroll``, ``Home/End ends`` — so the
keys are the leading run of words whose every ``/``-separated part this module knows.
The run stops at the verb, and the answer is empty (meaning "keep this atom") both
when the atom opens with a key we can't map (``↑↓ PgUp/PgDn scroll`` documents the
arrows too) and when anything after the run still looks like a key notation
(:data:`_KEYISH`) — dropping such an atom would take an unrepresented key with it.
"""
keys: list[str] = []
verb = False # past the leading key run: everything from here is the atom's verb half
for word in atom.split():
parts = word.split("/")
mappable = all(part in _HINT_KEY_ACTIONS for part in parts)
if not verb and mappable:
keys.extend(parts)
continue
verb = True
if mappable or any(mark in word for mark in _KEYISH):
return () # a second key rides in the verb half — the atom says more than these
return tuple(keys)
def strip_lane_atoms(hint: str, lane: Lane) -> str:
"""``hint`` with every atom the lane already advertises removed.
Where both a hint line and the lane are drawn at once — a floating dialog on the
PicoCalc, whose box carries the hint in its border while the frame's footer row below
carries *its* lane — an atom whose keys are all chips is the same statement twice, in
two notations, and the cells are the dialog's to spend on what the lane doesn't say.
An atom survives unless **every** key it names is a slot's action: a lane covering
only half of ``Home/End ends`` leaves the whole atom standing rather than telling half
a truth.
Dimmed slots count as covering. A dim chip keeps its label and means *a thing here,
just not right now* (see the module docstring) — the reader has been told where the
action lives either way, which is all the hint atom was for.
Runs per paint, never once at construction: a screen rewrites its hint as its content
changes (the packet viewer drops to a bare ``Esc close`` on a single packet) and reads
its lane fresh on every frame, so the overlap between the two is a property of *this*
paint.
Args:
hint: The screen's footer hint, in the standard ``a · b · Esc x`` grammar.
lane: The lane drawn on the same frame.
Returns:
The kept atoms, rejoined in order; ``""`` when the lane says all of it.
"""
covered = {
action
for pair in lane
if pair is not None
for action in (pair.action, pair.opp_action)
if action
}
kept = []
for raw in hint.split("·"):
atom = raw.strip()
if not atom:
continue
keys = _hint_keys(atom)
if keys and all(_HINT_KEY_ACTIONS[key] in covered for key in keys):
continue
kept.append(atom)
return " · ".join(kept)