Merge pull request #84 from foundersandcoders/feat/help-overlay

Add a Global Help Overlay

Author: JasonWarrenUK

docs/roadmaps/v5a-2606/enhanced.md

@@ -265,9 +265,28 @@ registry, and a header breadcrumb.
 
 ## Phase C — Signature UX features
 
-- [ ] **TR.C1** `feat/add-help-overlay` — *(roadmap 2TI.12)* Global `?` overlay
+- [x] **TR.C1** `feat/add-help-overlay` — *(roadmap 2TI.12)* Global `?` overlay
       rendered from the keymap registry, on a z-index layer over the current
-      screen.
+      screen. **Done:** the `Keymap` now owns the overlay lifecycle rather than
+      screens wiring it individually — the previously-scaffolded `onHelp` option
+      is removed from `KeymapOptions` and replaced with an always-on internal
+      `?` binding, so all 12 screens get help for free (suppressible per screen
+      via `disableGlobals: ['?']`). New `helpOverlay()` component
+      (`src/tui/components/helpOverlay.ts`) renders a centred `panel` card over
+      a full-screen backdrop, mounted on `renderer.root` (a sibling of each
+      screen's shell root) at `zIndex: 100`. `Keymap.toHelp()` exposes
+      display-ready rows from the live, `when`-passing bindings. `?`/ESC close
+      the overlay; every other key (including `q`) is swallowed while open, with
+      no fall-through to `onQuit`/`onBack`. **Bug found and fixed along the way:**
+      `renderer.keyInput` and the focused renderable's own key handler
+      (e.g. `SelectRenderable`) share the same underlying `InternalKeyHandler` —
+      a plain `dispatch()` return of `null` was not enough to stop arrow/enter
+      keys reaching the focused renderable underneath the overlay; fixed by
+      calling `key.stopPropagation()` while help is open, which the
+      `InternalKeyHandler`'s priority ordering (global listeners before
+      renderable handlers) then honours. Covered by regression tests in
+      `tests/tui/utils/keymap.test.ts` and `tests/tui/components/helpOverlay.test.ts`,
+      plus manual `tmux`-driven verification across Dashboard, About, and History.
 - [ ] **TR.C2** `feat/add-toast-and-confirm-overlays` — Transient toasts
       (success/info/error) + a real confirm modal; **replace the double-press
       deletes** in history & mapping-builder.

src/tui/components/helpOverlay.ts

@@ -0,0 +1,96 @@
+/** ====== Help Overlay Component ======
+ * Full-screen z-index layer listing the current screen's live key bindings.
+ * Owned and driven by Keymap (TR.C1) — mounted on renderer.root (a sibling of
+ * each screen's shell.root) so its zIndex stacks it above the whole screen.
+ */
+import { BoxRenderable, TextRenderable, t, fg } from '@opentui/core';
+import type { Renderer } from '../types';
+import { theme } from '../../../assets/brand/theme';
+import { panel, type Panel } from './panel';
+
+/** One display-ready shortcut row for the overlay. */
+export interface HelpRow {
+	/** Pre-rendered key glyph(s), e.g. "↑↓" or "ENTER". */
+	keys: string;
+	/** Human-readable action label. */
+	label: string;
+}
+
+export interface HelpOverlayOptions {
+	/** Overlay id, used for renderer.root.remove(). Default 'help-overlay-root'. */
+	id?: string;
+	/** Paint order among renderer.root siblings — must exceed screen roots. Default 100. */
+	zIndex?: number;
+	/** Card title. Default 'Keyboard Shortcuts'. */
+	title?: string;
+}
+
+export interface HelpOverlay {
+	/** Full-screen backdrop box — add to renderer.root (sibling of the screen shell). */
+	readonly root: BoxRenderable;
+	/** Replace the listed shortcut rows in place. */
+	setRows(rows: HelpRow[]): void;
+	/** Show/hide without remounting. */
+	setVisible(visible: boolean): void;
+	/** Current visibility. */
+	isVisible(): boolean;
+}
+
+const FOOTER_HINT = '? or ESC to close';
+
+export function helpOverlay(renderer: Renderer, opts: HelpOverlayOptions = {}): HelpOverlay {
+	const root = new BoxRenderable(renderer, {
+		id: opts.id ?? 'help-overlay-root',
+		position: 'absolute',
+		top: 0,
+		left: 0,
+		width: '100%',
+		height: '100%',
+		zIndex: opts.zIndex ?? 100,
+		backgroundColor: theme.background,
+		flexDirection: 'column',
+		justifyContent: 'center',
+		alignItems: 'center',
+		visible: false,
+	});
+
+	// Explicit width — the panel would otherwise size to its (initially empty)
+	// rowsBox content and clip a title longer than the placeholder row width.
+	const card: Panel = panel(renderer, { title: opts.title ?? 'Keyboard Shortcuts', width: 42 });
+
+	const rowsBox = new BoxRenderable(renderer, { flexDirection: 'column' });
+	card.add(rowsBox);
+
+	const footer = new TextRenderable(renderer, { content: FOOTER_HINT, fg: theme.textMuted });
+	card.add(footer);
+
+	root.add(card.box);
+
+	let rowIds: string[] = [];
+
+	return {
+		root,
+		setRows(rows) {
+			for (const id of rowIds) rowsBox.remove(id);
+			rowIds = [];
+
+			const maxKeysWidth = rows.reduce((max, row) => Math.max(max, row.keys.length), 0);
+
+			rows.forEach((row, index) => {
+				const padding = ' '.repeat(Math.max(1, maxKeysWidth - row.keys.length + 2));
+				const rowText = new TextRenderable(renderer, {
+					id: `help-overlay-row-${index}`,
+					content: t`${fg(theme.accent)(`${row.keys}${padding}`)}${fg(theme.text)(row.label)}`,
+				});
+				rowIds.push(rowText.id);
+				rowsBox.add(rowText);
+			});
+		},
+		setVisible(visible) {
+			root.visible = visible;
+		},
+		isVisible() {
+			return root.visible ?? false;
+		},
+	};
+}

src/tui/components/index.ts

@@ -2,3 +2,5 @@ export { panel } from './panel';
 export type { Panel, PanelOptions } from './panel';
 export { appShell } from './appShell';
 export type { AppShell, AppShellOptions } from './appShell';
+export { helpOverlay } from './helpOverlay';
+export type { HelpOverlay, HelpOverlayOptions, HelpRow } from './helpOverlay';

src/tui/utils/keymap.ts

@@ -7,6 +7,7 @@
 import type { KeyEvent } from '@opentui/core';
 import { symbols } from '../../../assets/brand/theme';
 import type { Renderer } from '../types';
+import { helpOverlay, type HelpOverlay, type HelpRow } from '../components/helpOverlay';
 
 /** A single declarative key binding. */
 export interface Binding {
@@ -66,29 +67,54 @@ export function eventToKey(key: KeyEvent): string {
 export interface KeymapOptions {
 	/** Per-screen bindings. Screen bindings take priority over globals. */
 	bindings: Binding[];
-	/** Canonical key strings to suppress from the auto-generated globals. */
+	/** Canonical key strings to suppress from the auto-generated globals.
+	 *  Include "?" to opt a screen out of the help overlay entirely. */
 	disableGlobals?: string[];
-	/** Handler for "?" — wired to the help overlay (TR.C1). No-op if omitted. */
-	onHelp?: () => void;
 	/** Handler for "q" — typically resolves quit. Omit on screens where q means back. */
 	onQuit?: () => void;
 	/** Handler for "escape" — typically resolves pop/back. */
 	onBack?: () => void;
 }
 
+const HELP_OVERLAY_ID = 'help-overlay-root';
+
 export class Keymap {
 	private readonly bindings: Binding[];
+	private readonly helpEnabled: boolean;
 	private attachedHandler?: (key: KeyEvent) => void;
+	private helpOverlay?: HelpOverlay;
+	private helpOpen = false;
 
 	constructor(opts: KeymapOptions) {
-		this.bindings = [...opts.bindings, ...buildGlobals(opts)];
+		this.helpEnabled = !(opts.disableGlobals ?? []).includes('?');
+		this.bindings = [
+			...opts.bindings,
+			...buildGlobals(opts),
+			...(this.helpEnabled
+				? [{ keys: ['?'], hint: '?', label: 'Help', handler: () => this.toggleHelp() } as Binding]
+				: []),
+		];
 	}
 
 	/** Find the first matching, when-passing binding and run its handler.
 	 *  Returns the binding that fired, or null if none matched.
-	 *  Pure and synchronous — useful for unit testing dispatch logic. */
+	 *  Pure and synchronous — useful for unit testing dispatch logic.
+	 *  While the help overlay is open, every key is swallowed except "?"/"escape"
+	 *  (which close it) — no fall-through to other bindings (e.g. "q" won't quit).
+	 *  stopPropagation() is load-bearing here: this handler runs as a "global"
+	 *  listener on the shared InternalKeyHandler, ahead of the focused
+	 *  renderable's own keypress handler (e.g. SelectRenderable's arrow-key
+	 *  navigation) — without it, arrow/enter keys would still reach the
+	 *  renderable underneath the overlay even though dispatch() ignored them. */
 	dispatch(key: KeyEvent): Binding | null {
 		const k = eventToKey(key);
+
+		if (this.helpOpen) {
+			key.stopPropagation?.();
+			if (k === '?' || k === 'escape') this.closeHelp();
+			return null;
+		}
+
 		for (const binding of this.bindings) {
 			if (
 				(binding.when?.() ?? true) &&
@@ -111,20 +137,54 @@ export class Keymap {
 			.join('  ');
 	}
 
+	/** Display-ready shortcut rows for the help overlay: visible, when-passing
+	 *  bindings, excluding the Help entry itself. */
+	toHelp(): HelpRow[] {
+		return this.bindings
+			.filter((b) => !b.hidden && (b.when?.() ?? true) && !b.keys.includes('?'))
+			.map((b) => ({ keys: b.hint ?? prettyKey(b.keys[0]), label: b.label }));
+	}
+
+	private toggleHelp(): void {
+		if (this.helpOpen) this.closeHelp();
+		else this.openHelp();
+	}
+
+	private openHelp(): void {
+		if (!this.helpOverlay) return;
+		this.helpOverlay.setRows(this.toHelp());
+		this.helpOverlay.setVisible(true);
+		this.helpOpen = true;
+	}
+
+	private closeHelp(): void {
+		this.helpOverlay?.setVisible(false);
+		this.helpOpen = false;
+	}
+
 	/** Register the keypress listener on the renderer. Call inside render().
 	 *  Idempotent — a prior listener is removed before registering the new one. */
 	attach(renderer: Renderer): void {
 		if (this.attachedHandler) this.detach(renderer);
+		if (this.helpEnabled && !this.helpOverlay) {
+			this.helpOverlay = helpOverlay(renderer, { id: HELP_OVERLAY_ID });
+			renderer.root.add(this.helpOverlay.root);
+		}
 		this.attachedHandler = (key) => this.dispatch(key);
 		renderer.keyInput.on('keypress', this.attachedHandler);
 	}
 
-	/** Remove the keypress listener. Call inside cleanup(). */
+	/** Remove the keypress listener and the help overlay. Call inside cleanup(). */
 	detach(renderer: Renderer): void {
 		if (this.attachedHandler) {
 			renderer.keyInput.off('keypress', this.attachedHandler);
 			this.attachedHandler = undefined;
 		}
+		if (this.helpOverlay) {
+			renderer.root.remove(HELP_OVERLAY_ID);
+			this.helpOverlay = undefined;
+			this.helpOpen = false;
+		}
 	}
 }
 
@@ -138,10 +198,8 @@ function buildGlobals(opts: KeymapOptions): Binding[] {
 	if (opts.onQuit && !suppressed.has('q')) {
 		globals.push({ keys: ['q'], hint: 'q', label: 'Quit', handler: opts.onQuit });
 	}
-	if (opts.onHelp && !suppressed.has('?')) {
-		globals.push({ keys: ['?'], hint: '?', label: 'Help', handler: opts.onHelp });
-	}
 	// Ctrl+C deliberately omitted — createCliRenderer({ exitOnCtrlC: true }) handles it.
+	// "?" Help is appended separately in the constructor (self-wired, TR.C1).
 
 	return globals;
 }