take4-console 0.15.0 → 0.25.0

package/src/Screen/WindowManager.mts

@@ -1,4 +1,10 @@
-import type { Focusable, WindowManagerOptions, TerminalMouseEvent } from './types.mjs';
+import type {
+	Focusable,
+	WindowManagerOptions,
+	TerminalMouseEvent,
+	KeyContext,
+	KeyBindHandler,
+} from './types.mjs';
 import { Screen } from './Screen.mjs';
 import { Window } from './Window.mjs';
 
@@ -114,6 +120,49 @@ function parseMouseEvent(key: string): TerminalMouseEvent | null {
 	};
 }
 
+// ── Key spec parsing ──────────────────────────────────────────────────────────
+
+/** Lookup table of friendly key names → raw terminal key strings.
+ *  Used by `bindKey` so callers can write `'ctrl+s'` or `'enter'` instead
+ *  of `'\x13'` / `'\r'`. Arrow keys, function keys, etc. stay raw. */
+const KEY_ALIASES: Record<string, string> = {
+	enter:     '\r',
+	return:    '\r',
+	space:     ' ',
+	esc:       '\x1b',
+	escape:    '\x1b',
+	tab:       '\t',
+	backspace: '\x7f',
+	del:       '\x7f',
+	delete:    '\x1b[3~',
+	up:        '\x1b[A',
+	down:      '\x1b[B',
+	right:     '\x1b[C',
+	left:      '\x1b[D',
+	home:      '\x1b[H',
+	end:       '\x1b[F',
+	pageup:    '\x1b[5~',
+	pagedown:  '\x1b[6~',
+};
+
+/** Normalises a caller-provided key spec into the raw key string emitted by
+ *  the terminal. Accepts raw strings (`'\r'`, `'a'`), friendly names
+ *  (`'enter'`, `'space'`, `'up'`), and `'ctrl+<letter>'` combinations.
+ *  Everything else is returned unchanged. */
+function normaliseKeySpec(spec: string): string {
+	if (spec.length <= 1) return spec;
+	const lower = spec.toLowerCase();
+	if (lower in KEY_ALIASES) return KEY_ALIASES[lower]!;
+
+	// `ctrl+<letter>` → ASCII control code (\x01 = Ctrl+A … \x1a = Ctrl+Z).
+	const ctrlMatch = /^ctrl\+([a-z])$/.exec(lower);
+	if (ctrlMatch) {
+		const letter = ctrlMatch[1]!.charCodeAt(0);
+		return String.fromCharCode(letter - 'a'.charCodeAt(0) + 1);
+	}
+	return spec;
+}
+
 // ── WindowManager ─────────────────────────────────────────────────────────────
 
 /** Manages the application input loop, focus, and modal dialogs.
@@ -130,19 +179,39 @@ export class WindowManager {
 	private screen: Screen;
 	private exitKeys: string[];
 	private onExit?: () => void;
-	private onKey?: (key: string) => void;
+	private onKey?: (key: string, ctx: KeyContext) => boolean | void;
 	private onMouse?: (event: TerminalMouseEvent) => void;
 	private mouseEnabled: boolean;
 
+	/** Registered bindings mapped by raw key string.
+	 *  Multiple handlers for the same key fire in insertion order; the first
+	 *  one that returns `true` marks the event as consumed. */
+	private keyBindings: Map<string, KeyBindHandler[]> = new Map();
+
 	private mainEntries: FocusEntry[];
 	private mainFocusIndex: number;
 	private dialogStack: DialogLevel[];
 	private running: boolean;
+	/** True while pause() is in effect and resume() has not yet reclaimed the
+	 *  terminal. Distinct from `running`: a paused WindowManager is still
+	 *  considered running — `stop()` can finalise it, and all registered
+	 *  focus entries remain intact for resume(). */
+	private paused: boolean = false;
 
 	/** Bound reference kept so we can remove the listener in stop(). */
 	private boundHandleInput: (data: Buffer) => void;
 	/** Bound SIGTERM handler for clean shutdown. */
 	private boundSigterm: () => void;
+	/** True when run() entered the alt-screen on its own (so stop() owes it an exit). */
+	private ownsAltScreen: boolean = false;
+	/** True when run() hid the cursor on its own (so stop() owes it a restore). */
+	private ownsCursor: boolean = false;
+	/** Set by pause() when it exited the alternate screen buffer — instructs
+	 *  resume() to re-enter. Cleared after resume() or stop() uses it. */
+	private pauseRestoreAltScreen: boolean = false;
+	/** Set by pause() when it showed a previously-hidden cursor — instructs
+	 *  resume() to hide it again. Cleared after resume() or stop() uses it. */
+	private pauseRestoreCursorHidden: boolean = false;
 
 	/** Creates a WindowManager for the given Screen.
 	 *  Does not start the input loop; call run() to begin. */
@@ -193,16 +262,64 @@ export class WindowManager {
 		return idx >= 0 ? entries[idx].control : null;
 	}
 
-	/** Moves focus to the given control if it belongs to the active context and is enabled. */
+	/** Moves focus to the given control if it belongs to the active context and is
+	 *  eligible (not disabled, not hidden via setVisible(false)). */
 	public setFocus(control: Focusable & Window): void {
 		const entries = this.activeEntries();
 		const idx     = entries.findIndex(e => e.control === control);
-		if (idx === -1 || entries[idx].control.isDisabled()) return;
+		if (idx === -1) return;
+		const candidate = entries[idx].control;
+		if (candidate.isDisabled() || !candidate.isVisible()) return;
 		this.blurCurrent();
 		this.setActiveFocusIndex(idx);
 		control.setFocused(true);
 	}
 
+	// ── Global key bindings (P0-4) ─────────────────────────────────────────────
+
+	/** Registers a global shortcut handler.
+	 *
+	 *  The handler fires **before** the focused control receives the key; if it
+	 *  returns `true`, the key is marked as consumed (no dispatch to the
+	 *  focused control, no exit-key check, no focus navigation). Return
+	 *  `false`/`void` to let the key continue through the pipeline — useful
+	 *  for observer-only handlers that want to track keys without blocking.
+	 *
+	 *  `keySpec` accepts friendly names (`'enter'`, `'space'`, `'esc'`,
+	 *  `'ctrl+s'`, arrow names) as well as raw terminal strings
+	 *  (`'\r'`, `'q'`, `'\x1b[A'`). Multiple handlers can be bound to the same
+	 *  key — they fire in insertion order until one consumes the event.
+	 *
+	 *  Returns an unbind function that removes *this particular* registration. */
+	public bindKey(keySpec: string, handler: KeyBindHandler): () => void {
+		const key = normaliseKeySpec(keySpec);
+		const list = this.keyBindings.get(key);
+		if (list) list.push(handler);
+		else this.keyBindings.set(key, [handler]);
+
+		return () => this.unbindKey(keySpec, handler);
+	}
+
+	/** Removes a handler previously registered with `bindKey`. When `handler`
+	 *  is omitted, all handlers for the given key are removed. Returns `true`
+	 *  when at least one handler was removed. */
+	public unbindKey(keySpec: string, handler?: KeyBindHandler): boolean {
+		const key = normaliseKeySpec(keySpec);
+		const list = this.keyBindings.get(key);
+		if (!list) return false;
+
+		if (handler === undefined) {
+			this.keyBindings.delete(key);
+			return true;
+		}
+
+		const idx = list.indexOf(handler);
+		if (idx === -1) return false;
+		list.splice(idx, 1);
+		if (list.length === 0) this.keyBindings.delete(key);
+		return true;
+	}
+
 	// ── Dialog ─────────────────────────────────────────────────────────────────
 
 	/** Opens a modal dialog: blurs the current context, adds the dialog Window to
@@ -270,41 +387,152 @@ export class WindowManager {
 		process.stdin.on('data', this.boundHandleInput);
 		process.once('SIGTERM', this.boundSigterm);
 
-		process.stdout.write('\x1b[?1049h'); // switch to alternate screen buffer
+		// Defer alt-screen / cursor hiding to Screen so consumers using
+		// ScreenOptions don't get them double-toggled. We only "own" the toggle
+		// (and therefore have to undo it in stop()) when the Screen wasn't
+		// already in that state — for instance because the user constructed it
+		// with `altScreen: true`, in which case the alt buffer should outlive
+		// stop() until Screen.dispose() runs.
+		if (!this.screen.isAltScreenActive()) {
+			this.screen.enterAltScreen();
+			this.ownsAltScreen = true;
+		}
 		if (this.mouseEnabled) {
 			// Enable button-press tracking + SGR extended coordinates.
 			process.stdout.write('\x1b[?1000h\x1b[?1006h');
 		}
-		process.stdout.write('\x1b[?25l'); // hide cursor
+		if (!this.screen.isCursorHidden()) {
+			this.screen.hideHardwareCursor();
+			this.ownsCursor = true;
+		}
 
 		this.initializeFocus();
 		this.renderFrame();
 	}
 
 	/** Stops the input loop, restores terminal state, and fires the onExit callback.
-	 *  Safe to call even when the loop was not started (skips terminal teardown). */
+	 *  Safe to call even when the loop was not started (skips terminal teardown).
+	 *  When called while paused, the parts that pause() already released
+	 *  (stdin listener, raw mode, mouse tracking) are not re-teardown'd — only
+	 *  the remaining owned state (alt-screen, cursor, SIGTERM listener) is
+	 *  finalised. */
 	public stop(): void {
 		const wasRunning = this.running;
+		const wasPaused  = this.paused;
 		this.running     = false;
+		this.paused      = false;
 
 		if (wasRunning) {
-			process.stdin.off('data', this.boundHandleInput);
-			if (process.stdin.isTTY) {
-				process.stdin.setRawMode(false);
+			if (!wasPaused) {
+				process.stdin.off('data', this.boundHandleInput);
+				if (process.stdin.isTTY) {
+					process.stdin.setRawMode(false);
+				}
+				process.stdin.pause();
+				if (this.mouseEnabled) {
+					process.stdout.write('\x1b[?1006l\x1b[?1000l');
+				}
 			}
-			process.stdin.pause();
 			process.off('SIGTERM', this.boundSigterm);
 
-			if (this.mouseEnabled) {
-				process.stdout.write('\x1b[?1006l\x1b[?1000l');
+			if (this.ownsCursor) {
+				this.screen.showHardwareCursor();
+				this.ownsCursor = false;
+			}
+			if (this.ownsAltScreen) {
+				this.screen.exitAltScreen();
+				this.ownsAltScreen = false;
 			}
-			process.stdout.write('\x1b[?25h'); // show cursor
-			process.stdout.write('\x1b[?1049l'); // restore normal screen buffer
+			// Drop any latent pause-restore intents so a future run() starts fresh.
+			this.pauseRestoreAltScreen    = false;
+			this.pauseRestoreCursorHidden = false;
 		}
 
 		this.onExit?.();
 	}
 
+	/** Suspends the input loop without tearing down the focus tree. Releases the
+	 *  terminal ownership the WindowManager needs for interactive mode:
+	 *
+	 *  - detaches the stdin 'data' listener, leaves raw mode, pauses stdin;
+	 *  - disables mouse tracking when it was enabled;
+	 *  - restores the hardware cursor when it was hidden (so an external
+	 *    process has a visible cursor);
+	 *  - optionally exits the alternate screen buffer
+	 *    (`{ leaveAltScreen: true }`).
+	 *
+	 *  The typical use is spawning `$EDITOR` or a shell: pause, exec, resume.
+	 *  All registered focus entries, dialog stack, and the onKey/bindKey
+	 *  bindings are preserved, so `resume()` brings the UI back without a
+	 *  full re-registration. No-op when the manager is not running or is
+	 *  already paused. */
+	public pause(options?: { leaveAltScreen?: boolean }): void {
+		if (!this.running || this.paused) return;
+		this.paused = true;
+
+		process.stdin.off('data', this.boundHandleInput);
+		if (process.stdin.isTTY) {
+			process.stdin.setRawMode(false);
+		}
+		process.stdin.pause();
+
+		if (this.mouseEnabled) {
+			process.stdout.write('\x1b[?1006l\x1b[?1000l');
+		}
+
+		this.pauseRestoreCursorHidden = this.screen.isCursorHidden();
+		if (this.pauseRestoreCursorHidden) {
+			this.screen.showHardwareCursor();
+		}
+
+		this.pauseRestoreAltScreen = false;
+		if (options?.leaveAltScreen && this.screen.isAltScreenActive()) {
+			this.screen.exitAltScreen();
+			this.pauseRestoreAltScreen = true;
+		}
+	}
+
+	/** Resumes the input loop after pause(). Re-enters the alternate screen if
+	 *  pause() left it, re-enables mouse tracking, re-hides the cursor when
+	 *  pause() showed it, restores raw mode + stdin listener, and re-renders
+	 *  the current frame unless `{ rerender: false }` is passed. No-op when
+	 *  the manager is not currently paused. */
+	public resume(options?: { rerender?: boolean }): void {
+		if (!this.paused) return;
+		this.paused = false;
+
+		if (this.pauseRestoreAltScreen) {
+			this.screen.enterAltScreen();
+			this.pauseRestoreAltScreen = false;
+		}
+
+		if (this.mouseEnabled) {
+			process.stdout.write('\x1b[?1000h\x1b[?1006h');
+		}
+
+		if (this.pauseRestoreCursorHidden) {
+			this.screen.hideHardwareCursor();
+			this.pauseRestoreCursorHidden = false;
+		}
+
+		if (process.stdin.isTTY) {
+			process.stdin.setRawMode(true);
+		}
+		process.stdin.resume();
+		process.stdin.on('data', this.boundHandleInput);
+
+		if (options?.rerender !== false) {
+			this.renderFrame();
+		}
+	}
+
+	/** Returns true while pause() is active and resume() has not yet been
+	 *  called. A paused manager still has its `run()` context (focus
+	 *  registrations, dialog stack, exit keys) intact. */
+	public isPaused(): boolean {
+		return this.paused;
+	}
+
 	// ── Input handling ─────────────────────────────────────────────────────────
 
 	/** Processes a raw stdin Buffer. Exposed as public so tests can drive it directly
@@ -323,7 +551,22 @@ export class WindowManager {
 				}
 			}
 
-			this.onKey?.(key);
+			// Build a KeyContext snapshot for global handlers. The focused
+			// control is captured before any handler fires so handlers see a
+			// consistent view even when they mutate focus.
+			const ctx: KeyContext = {
+				focusedControl: this.getFocused(),
+				inDialog:       this.dialogStack.length > 0,
+				dialogDepth:    this.dialogStack.length,
+			};
+
+			// Fire global shortcut handlers first (P0-4). Any handler returning
+			// `true` marks the key as consumed — exit-key check, focus
+			// navigation, and dispatch to the focused control are all skipped.
+			if (this.dispatchGlobalKey(key, ctx)) {
+				this.renderFrame();
+				continue;
+			}
 
 			// Exit keys.
 			if (this.exitKeys.includes(key)) {
@@ -332,12 +575,17 @@ export class WindowManager {
 			}
 
 			// Focus navigation – moveFocus handles index -1 correctly.
+			// Controls that want Tab to flow into handleKey (e.g. TextArea with
+			// insertTabAsSpaces) opt in via Focusable.capturesTab().
 			if (key === '\t') {
-				this.moveFocus(1);
-				this.renderFrame();
-				continue;
-			}
-			if (key === '\x1b[Z') { // Shift-Tab
+				const focused = ctx.focusedControl;
+				if (!focused?.capturesTab?.()) {
+					this.moveFocus(1);
+					this.renderFrame();
+					continue;
+				}
+				// Fall through — let the focused control's handleKey see Tab.
+			} else if (key === '\x1b[Z') { // Shift-Tab — always cycles focus.
 				this.moveFocus(-1);
 				this.renderFrame();
 				continue;
@@ -358,6 +606,23 @@ export class WindowManager {
 		}
 	}
 
+	/** Runs registered `bindKey` handlers and the global `onKey` callback
+	 *  for the given key. Returns `true` when the event was consumed. */
+	private dispatchGlobalKey(key: string, ctx: KeyContext): boolean {
+		const bound = this.keyBindings.get(key);
+		if (bound) {
+			// Copy before iterating so an unbindKey() call from within a handler
+			// doesn't skip the next handler in the list.
+			for (const handler of bound.slice()) {
+				if (handler(ctx) === true) return true;
+			}
+		}
+		if (this.onKey) {
+			if (this.onKey(key, ctx) === true) return true;
+		}
+		return false;
+	}
+
 	// ── Private helpers ────────────────────────────────────────────────────────
 
 	/** Returns the FocusEntry array for the active context (topmost dialog or main). */
@@ -394,22 +659,28 @@ export class WindowManager {
 		}
 	}
 
-	/** Finds the first already-focused (or first non-disabled) control and focuses it. */
+	/** Returns true when the control is eligible to receive focus in the current
+	 *  context — neither disabled nor hidden via `Window.setVisible(false)`. */
+	private isFocusable(control: Focusable & Window): boolean {
+		return !control.isDisabled() && control.isVisible();
+	}
+
+	/** Finds the first already-focused (or first eligible) control and focuses it. */
 	private initializeFocus(): void {
 		const entries = this.activeEntries();
 		if (entries.length === 0) return;
 
 		// Prefer a control that is already marked as focused.
 		for (let i = 0; i < entries.length; i++) {
-			if (entries[i].control.isFocused() && !entries[i].control.isDisabled()) {
+			if (entries[i].control.isFocused() && this.isFocusable(entries[i].control)) {
 				this.setActiveFocusIndex(i);
 				return;
 			}
 		}
 
-		// Otherwise focus the first enabled control.
+		// Otherwise focus the first eligible control.
 		for (let i = 0; i < entries.length; i++) {
-			if (!entries[i].control.isDisabled()) {
+			if (this.isFocusable(entries[i].control)) {
 				this.setActiveFocusIndex(i);
 				entries[i].control.setFocused(true);
 				return;
@@ -417,7 +688,8 @@ export class WindowManager {
 		}
 	}
 
-	/** Moves focus by delta (+1 for Tab, -1 for Shift-Tab), skipping disabled controls. */
+	/** Moves focus by delta (+1 for Tab, -1 for Shift-Tab), skipping disabled
+	 *  and hidden controls. */
 	private moveFocus(delta: number): void {
 		const entries = this.activeEntries();
 		if (entries.length === 0) return;
@@ -435,9 +707,9 @@ export class WindowManager {
 		do {
 			next = ((next + delta) % count + count) % count;
 			attempts++;
-		} while (entries[next].control.isDisabled() && attempts <= count);
+		} while (!this.isFocusable(entries[next].control) && attempts <= count);
 
-		if (!entries[next].control.isDisabled()) {
+		if (this.isFocusable(entries[next].control)) {
 			this.setActiveFocusIndex(next);
 			entries[next].control.setFocused(true);
 		}
@@ -450,7 +722,7 @@ export class WindowManager {
 		const entries = this.activeEntries();
 		for (let i = 0; i < entries.length; i++) {
 			const { control, absX, absY } = entries[i];
-			if (control.isDisabled()) continue;
+			if (!this.isFocusable(control)) continue;
 			const { width, height } = control.getSize();
 			if (
 				event.x >= absX && event.x < absX + width &&