magus-cli 7.3.1 → 7.4.0

package/src/ui/input/key-dispatch.ts

@@ -0,0 +1,149 @@
+/**
+ * One keypress, one handler.
+ *
+ * OpenTUI's `useKeyboard` is a broadcast: every subscriber receives every key,
+ * with no way for one to stop the next. magus used to have a dozen subscribers
+ * — the global keys, the panel scroll keys, each screen, each modal — and each
+ * one guessed from render-time flags (`modal`, `isSearching`, `detailActive`)
+ * whether the key was meant for it. The guesses disagreed: Esc that cleared a
+ * filter also ran the global Esc and quit, Enter in a confirm dialog also acted
+ * on the row underneath, and `j`/`k` moved the cursor before a search box could
+ * type them.
+ *
+ * This module replaces the guessing with an order. Every key is offered to the
+ * layers top first, and the first layer that consumes it is the only one that
+ * acts:
+ *
+ *   system → modal → input → screen → scroll → global
+ *
+ * - system: Ctrl+C. Taken in `src/tui.tsx` on the renderer itself, before the
+ *   React tree sees any key, so it quits even under a modal or a crashed screen.
+ * - modal:  an open dialog (or the help overlay) takes every key.
+ * - input:  a focused search box takes what it types — see `inputLayerConsumes`.
+ * - screen: the current screen's bindings, from `ui/keymap.ts`.
+ * - scroll: PgUp / PgDn / Ctrl+U / Ctrl+D scroll the detail panel.
+ * - global: tab digits, Tab, `q`, `?`, Esc.
+ *
+ * Pure: no React, no OpenTUI. `KeyRouter.tsx` feeds it the live layers.
+ */
+
+/**
+ * A keypress, named the way OpenTUI names it: "a", "1", "?", "space",
+ * "return", "escape", "backspace", "up", "down", "pageup", "pagedown", "tab".
+ * A shifted letter keeps its lowercase name with `shift` set (Shift+U is
+ * `{ name: "u", shift: true, sequence: "U" }`); Ctrl+U is `{ name: "u", ctrl: true }`.
+ */
+export interface KeyPress {
+	name: string;
+	sequence: string;
+	ctrl: boolean;
+	meta: boolean;
+	shift: boolean;
+}
+
+export type KeyLayerId =
+	| "system"
+	| "modal"
+	| "input"
+	| "screen"
+	| "scroll"
+	| "global";
+
+/** Top first. A layer only sees a key every layer above it declined. */
+export const LAYER_ORDER: readonly KeyLayerId[] = [
+	"system",
+	"modal",
+	"input",
+	"screen",
+	"scroll",
+	"global",
+];
+
+export interface KeyLayer {
+	id: KeyLayerId;
+	/** An inactive layer is skipped without its handler being called. */
+	active: boolean;
+	/** True when the layer consumed the key; nothing below it will see it. */
+	handle(key: KeyPress): boolean;
+}
+
+/**
+ * Offer `key` to the active layers in LAYER_ORDER — whatever order the array is
+ * in — and stop at the first that consumes it. Returns that layer's id, or null
+ * when no layer wanted the key. Layers below the consumer are never called.
+ *
+ * Several layers may share an id (two components can each register a screen
+ * layer); within one id they are asked in array order.
+ */
+export function dispatchKey(
+	layers: readonly KeyLayer[],
+	key: KeyPress,
+): KeyLayerId | null {
+	for (const id of LAYER_ORDER) {
+		for (const layer of layers) {
+			if (layer.id !== id || !layer.active) continue;
+			if (layer.handle(key)) return id;
+		}
+	}
+	return null;
+}
+
+/** PgUp, PgDn, Ctrl+U, Ctrl+D — the keys that scroll the detail panel. */
+export function isScrollKey(key: KeyPress): boolean {
+	if (key.meta) return false;
+	if (key.name === "pageup" || key.name === "pagedown") return true;
+	return key.ctrl && (key.name === "u" || key.name === "d");
+}
+
+/** True for a single printable character: no control bytes, no escape sequences. */
+function isPrintable(text: string): boolean {
+	const chars = [...text];
+	if (chars.length !== 1) return false;
+	const code = chars[0]?.codePointAt(0) ?? 0;
+	return code >= 0x20 && code !== 0x7f;
+}
+
+/**
+ * The character a keypress types, or null when it types nothing.
+ *
+ * `sequence` first: it is the literal text for a plain key, and under the kitty
+ * keyboard protocol OpenTUI puts the produced text there too. `name` is the
+ * fallback for a printable key whose sequence is an escape (kitty's Space).
+ */
+export function typedCharacter(key: KeyPress): string | null {
+	if (key.ctrl || key.meta) return null;
+	if (isPrintable(key.sequence)) return key.sequence;
+	if (key.name === "space") return " ";
+	if (isPrintable(key.name)) {
+		return key.shift && /^[a-z]$/.test(key.name)
+			? key.name.toUpperCase()
+			: key.name;
+	}
+	return null;
+}
+
+/** The editing keys a focused box owns besides the characters it types. */
+const INPUT_EDIT_KEYS = new Set([
+	"backspace",
+	"delete",
+	"return",
+	"enter",
+	"escape",
+]);
+
+/**
+ * Does a focused search/edit box take this key?
+ *
+ * Yes: any printable character — letters, digits, punctuation including `?`,
+ * space — plus Backspace, Enter and Esc. They are typed or edit the box; they
+ * do not switch tab, move the selection, quit or open help.
+ *
+ * No: Up/Down (the screen moves the selection), Tab (the global layer cycles
+ * tabs), the scroll keys (the panel keeps scrolling while you type), Ctrl+C,
+ * and any other Ctrl or Meta chord.
+ */
+export function inputLayerConsumes(key: KeyPress): boolean {
+	if (key.ctrl || key.meta) return false;
+	if (INPUT_EDIT_KEYS.has(key.name)) return true;
+	return typedCharacter(key) !== null;
+}