From 8da6a7e849513e1cb63410d95b121df729260d0c Mon Sep 17 00:00:00 2001
From: Anders Betts <anders.betts@gmail.com>
Date: Sat, 19 Sep 2026 23:05:44 +0200
Subject: tui: themes, pager markup, menu sections; merge Bokslut and year info

---
 docs/TUI-GUIDELINES.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 52 insertions(+), 3 deletions(-)

(limited to 'docs/TUI-GUIDELINES.md')

diff --git a/docs/TUI-GUIDELINES.md b/docs/TUI-GUIDELINES.md
index e02fade..631a516 100644
--- a/docs/TUI-GUIDELINES.md
+++ b/docs/TUI-GUIDELINES.md
@@ -51,6 +51,12 @@ written compactly as `^N`, `^A`, `^C`, `^R` to save width.
 - Digits move the highlight; only Enter activates. Menus are the exception:
   digits activate directly (they are shortcuts).
 - Empty lists are never a dead end: show a message or keep the add-row.
+- Menus may be split into sections: an item whose text starts with
+  `\x01` (`TUI_MARK_HEADING`) is a non-selectable header, drawn dim and
+  without a number. Numbering, `1`–`9` and `g` count only the selectable
+  items and continue across sections; arrows/PgUp/PgDn/Home/End skip the
+  headers. A cursor that points at a header snaps to the next selectable
+  item.
 
 ## Forms
 
@@ -122,8 +128,48 @@ written compactly as `^N`, `^A`, `^C`, `^R` to save width.
 - Columns are padded with `pad_field()` (UTF-8 display width) and truncated to
   their column; amounts right-aligned via `kr_format()`; never pad with `%s`
   widths directly on user text.
-- Selection = reverse video, headers = bold, derived data = dim.
-- All user-visible TUI text is Swedish; server messages are English.
+- Selection = reverse video, headers = bold, derived data = dim. Drawing uses
+  the semantic styles below, never raw `A_BOLD`/`A_DIM`.
+
+## Theme and styles
+
+`clients/tui.c` owns the theme. The widget layer (and only the widget layer)
+calls `tui_style(enum tui_style)` to set a semantic style and
+`tui_style_reset()` to return to the terminal default:
+
+| Style | Meaning |
+|---|---|
+| `TUI_TITLE` | screen title in the frame |
+| `TUI_HEADING` | headings, column headers, form labels |
+| `TUI_SUBHEADING` | secondary headings |
+| `TUI_DIM` | derived/secondary data, section headers |
+| `TUI_ACCENT` | interactive prompts (goto) |
+| `TUI_POS` / `TUI_NEG` | positive/negative amounts |
+| `TUI_RULE` | full-width rules |
+| `TUI_STATUS` | status line, hints, footers |
+
+Colours are initialised in `tui_keys_setup()`: a small set of pairs (cyan
+headings, yellow accent, green/red amounts, blue rules) on the default
+background. If the terminal has no colour support or `NO_COLOR` is set in the
+environment, every style falls back to attributes (bold/dim) via the pure
+`tui_style_attrs(style, colours_ok, no_color)`; reverse video for the
+selection is kept in both modes.
+
+## Pager markup
+
+Pager text may carry a one-byte leading marker per line (set by the report
+formatters, interpreted by `tui_markup`):
+
+| Marker | Effect |
+|---|---|
+| `\x01` | line is a heading (`TUI_HEADING`) |
+| `\x02` | line is dimmed (`TUI_DIM`) |
+| `\x03` | full-width `ACS_HLINE` rule (`TUI_RULE`); the rest of the line is ignored |
+
+Report formatters mark headings, sums/derived lines and rules before the
+text reaches `tui_pager`; the markers never change column widths. Anything
+that saves pager text to a file strips the markers first
+(`strip_markup()` in `bokftui.c`).
 
 ## Widget layer (`clients/tui.[ch]`)
 
@@ -143,7 +189,10 @@ only place that touches ncurses. Rules:
   `TUI_HOOK_*` codes are all distinct.
 - `tui_pager_hook` takes `TUI_PAGER_SAVE` to enable the `s` save action; the
   `extra_hint` is shown in the footer. Plain `tui_pager` keeps `s` on when a
-  save hint is passed.
+  save hint is passed. Pager lines go through `tui_markup` (see below).
+- Styles come from `tui_style`/`tui_style_attrs`; report markup and menu
+  sections from `tui_markup`/`TUI_MARK_HEADING`. Their fallbacks and the
+  navigation over section headers are unit-tested in `tests/test_tui.c`.
 - `tui_redraw` flushes a `tui_frame`/`tui_set_status` pair drawn by the
   application outside a widget loop (startup/reconnect messages).
 - The application supplies input, frame/hints and quit through
-- 
cgit v1.3