Two rows renamed, and the rename carried into the screens they open — the config editor's table title and its staged-count header, the support page's own title (it comes from the tool, so it followed on its own). "Support this project" never said which project; the menu is MeshTerm's and the section above it is already About MeshTerm, so the name is the useful half of that phrase. "Device configuration" was the longest label in the list and set the width of the whole name column: at 19 cells instead of 23, every description now gets 51 and the widest row is 68. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
172 lines
7.1 KiB
Python
172 lines
7.1 KiB
Python
"""The About MeshTerm pages: the app, the person who wrote it, and how to help it along.
|
|
|
|
Three read-only pages hung under the main menu's *About MeshTerm* section — the one
|
|
section that names a subject rather than a doing, because "what is this thing, and who
|
|
made it" is a question the other five can't answer. Each opens as a full screen, scrolls
|
|
if the terminal is short, and is left with Esc; nothing here touches the radio or the
|
|
database, so a page reads the same with no device attached at all.
|
|
|
|
Unlike every other screen in the app, these are **written** rather than composed: their
|
|
content is markdown, living beside the wordmark in ``meshterm/assets/pages``, drawn
|
|
through :mod:`meshterm.ui.markdown` in the app's own visual language (see that module
|
|
for what each construct becomes). Filling a page in means editing its ``.md`` file —
|
|
no screen, menu row, or CLI face has to follow — and everything markdown offers is
|
|
available while doing it: sections, sub-headings, lists, quotes, links, tables.
|
|
|
|
Every page is **scaffolding** today. The headings are the real shape — that is the part
|
|
worth settling first — and each carries one lowercase muted ``placeholder — …`` line
|
|
where its prose will go, in the same empty-state voice the rest of the app uses, so an
|
|
unwritten page reads as deliberately unwritten rather than as a screen that failed to
|
|
load.
|
|
|
|
What is *not* written into those files: the version, the author, and the copyright span.
|
|
Each page names them with a ``{version}`` / ``{author}`` / ``{copyright}`` placeholder
|
|
that is filled from :mod:`meshterm` itself (:func:`~meshterm.copyright_notice`) as the
|
|
page is opened, so the About page can never drift from the package it describes.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from pathlib import Path
|
|
from typing import TYPE_CHECKING
|
|
|
|
from .. import __author__, __version__, copyright_notice
|
|
from .markdown import MarkdownDoc, render_markdown
|
|
from .tui import ScrollScreen
|
|
from .tui.render import render_lines
|
|
|
|
if TYPE_CHECKING:
|
|
from ..context import AppContext
|
|
|
|
#: Where the written pages live — beside the wordmark, in the package's assets, so they
|
|
#: ship with the wheel and can be edited without touching Python.
|
|
_PAGES = Path(__file__).resolve().parent.parent / "assets" / "pages"
|
|
|
|
|
|
def _page(name: str) -> MarkdownDoc:
|
|
"""Load ``assets/pages/<name>.md``, fill in the live package facts, and render it.
|
|
|
|
Args:
|
|
name: The page file's stem.
|
|
|
|
Returns:
|
|
The rendered page.
|
|
"""
|
|
source = (_PAGES / f"{name}.md").read_text(encoding="utf-8")
|
|
for token, value in (
|
|
("{version}", __version__),
|
|
("{author}", __author__),
|
|
("{copyright}", copyright_notice()),
|
|
):
|
|
source = source.replace(token, value)
|
|
return render_markdown(source)
|
|
|
|
|
|
def about_meshterm() -> MarkdownDoc:
|
|
"""The *About MeshTerm* page: what the app is, where it came from, its terms."""
|
|
return _page("about")
|
|
|
|
|
|
def about_author() -> MarkdownDoc:
|
|
"""The *About the author* page: the person behind MeshTerm, on the mesh and off it."""
|
|
return _page("author")
|
|
|
|
|
|
def support_project() -> MarkdownDoc:
|
|
"""The *Support MeshTerm* page: what keeps it going, and how to chip in.
|
|
|
|
Deliberately two-sided — money is one way to help and not the only one, so the page
|
|
keeps a section for the other kind rather than folding it into a donate link.
|
|
"""
|
|
return _page("support")
|
|
|
|
|
|
class AboutPage(ScrollScreen):
|
|
"""One written page: a read-only body, drawn full-screen, left with Esc.
|
|
|
|
Nearly all of it is the shared read-only screen — the pager, the derived footer hint
|
|
that only names the pager when there *is* something to page, the PicoCalc F-key lane
|
|
that dims on the same gate — with two things added, both of which come from the body
|
|
being a *document* rather than a block:
|
|
|
|
* It renders block by block and records where each ``##`` section starts, so a
|
|
heading pins to the top row while its prose scrolls under it and ``^PgUp``/``^PgDn``
|
|
step section by section (the same landmark machinery a grouped select list uses).
|
|
* Its lane claims the left-hand ``Sect ↑`` / ``Sect ↓`` pair once the page has more
|
|
than one section, because on the console the lane is the only place a chord can
|
|
advertise itself.
|
|
|
|
Only the framing differs from a result window: these are full screens rather than
|
|
floating views, so Esc reads *back*.
|
|
"""
|
|
|
|
def __init__(self, title: str, doc: MarkdownDoc) -> None:
|
|
"""Show ``doc`` as the page under ``title``.
|
|
|
|
Args:
|
|
title: The page's heading — sentence case, no icon (icons live in the menu
|
|
rows that open these pages, never in a title).
|
|
doc: The rendered page, from one of the builders above.
|
|
"""
|
|
super().__init__(doc, title=title, floating=False)
|
|
self._doc = doc
|
|
|
|
@property
|
|
def fkey_lane(self):
|
|
"""The shared pager lane, plus the section step on a page that has sections.
|
|
|
|
A left-hand pair rises toward F1, so ``Sect ↑`` sits outside ``Sect ↓`` — the
|
|
order a grouped select list uses on the same two keys, dispatching the same two
|
|
actions. Both are lit only while the page actually scrolls: with the whole page
|
|
on screen there is no section to step *to*.
|
|
"""
|
|
from .tui.fkeys import FPair, default_lane
|
|
|
|
lane = list(default_lane(nav=self.content_overflows))
|
|
if len(self._doc.sections) >= 2:
|
|
lane[0] = FPair("Sect ↑", "ctrl_pageup", enabled=self.content_overflows)
|
|
lane[1] = FPair("Sect ↓", "ctrl_pagedown", enabled=self.content_overflows)
|
|
return lane
|
|
|
|
def render_body(self, width: int) -> list[str]:
|
|
"""Render the page a block at a time, noting where its section headings land."""
|
|
lines: list[str] = []
|
|
self._sticky_headers = []
|
|
for block in self._doc.blocks:
|
|
# A blank separator renders to no lines at all on its own (it is one empty
|
|
# Text, and an empty render has nothing to split); inside the document's
|
|
# Group it would be the empty line it is meant to be, so it stays one here.
|
|
rendered = render_lines(block.renderable, width) or [""]
|
|
if block.heading:
|
|
self._sticky_headers.append((len(lines), rendered))
|
|
lines.extend(rendered)
|
|
self._scroll_total = max(1, len(lines))
|
|
return lines
|
|
|
|
|
|
async def open_about_page(ctx: "AppContext", title: str, doc: MarkdownDoc) -> None:
|
|
"""Open one About page full-screen and hold it until the reader backs out.
|
|
|
|
Args:
|
|
ctx: The shared application context (must be running the interactive TUI).
|
|
title: The page's heading.
|
|
doc: The page's content.
|
|
|
|
Raises:
|
|
RuntimeError: If called outside the interactive menu (no full-screen session).
|
|
"""
|
|
from .surface import TuiUi
|
|
|
|
if not isinstance(ctx.ui, TuiUi): # pragma: no cover - guarded by the menu-only caller
|
|
raise RuntimeError("the About pages are only available in the menu")
|
|
await ctx.ui.session.run_screen(AboutPage(title, doc))
|
|
|
|
|
|
__all__ = [
|
|
"AboutPage",
|
|
"about_author",
|
|
"about_meshterm",
|
|
"open_about_page",
|
|
"support_project",
|
|
]
|