magus-cli 7.3.1 → 7.4.1

package/src/__tests__/blind/c4-key-dispatch.test.ts

@@ -0,0 +1,397 @@
+/**
+ * Blind tests — contract C4 (requirements R4.1–R4.4, R4.6–R4.8).
+ *
+ * Written from requirements.md and architecture.md only. Layers are stubs that
+ * record every handle() call, so "a lower layer never sees the key" is
+ * observed directly rather than inferred.
+ */
+import { describe, expect, test } from "bun:test";
+
+const load = () => import("../../ui/input/key-dispatch.js");
+
+type LayerId = "system" | "modal" | "input" | "screen" | "scroll" | "global";
+
+interface Key {
+	name: string;
+	sequence: string;
+	ctrl: boolean;
+	meta: boolean;
+	shift: boolean;
+}
+
+const ORDER: LayerId[] = [
+	"system",
+	"modal",
+	"input",
+	"screen",
+	"scroll",
+	"global",
+];
+
+const SEQ: Record<string, string> = {
+	space: " ",
+	return: "\r",
+	escape: "\x1b",
+	backspace: "\x7f",
+	up: "\x1b[A",
+	down: "\x1b[B",
+	pageup: "\x1b[5~",
+	pagedown: "\x1b[6~",
+	tab: "\t",
+};
+
+/** A KeyPress as OpenTUI names it. Printable keys use their own char as sequence. */
+function key(name: string, mods: Partial<Omit<Key, "name">> = {}): Key {
+	let sequence = SEQ[name] ?? name;
+	if (mods.ctrl && /^[a-z]$/.test(name)) {
+		sequence = String.fromCharCode(name.charCodeAt(0) - 96);
+	}
+	if (name === "tab" && mods.shift) sequence = "\x1b[Z";
+	return { name, sequence, ctrl: false, meta: false, shift: false, ...mods };
+}
+
+const ctrl = (c: string) => key(c, { ctrl: true });
+/** OpenTUI reports "U" as name "u", shift true, sequence "U". */
+const upper = (c: string) =>
+	key(c.toLowerCase(), { shift: true, sequence: c.toUpperCase() });
+
+const DIGITS = "1234567890".split("").map((d) => key(d));
+const SCROLL_KEYS = [key("pageup"), key("pagedown"), ctrl("u"), ctrl("d")];
+
+interface Recorder {
+	calls: LayerId[];
+	layers: { id: LayerId; active: boolean; handle(k: Key): boolean }[];
+}
+
+/** Build one layer per id. `consumes[id]` decides; absent means "never consumes". */
+function stack(
+	consumes: Partial<Record<LayerId, (k: Key) => boolean>>,
+	active: Partial<Record<LayerId, boolean>> = {},
+	order: LayerId[] = ORDER,
+): Recorder {
+	const calls: LayerId[] = [];
+	const layers = order.map((id) => ({
+		id,
+		active: active[id] ?? true,
+		handle(k: Key): boolean {
+			calls.push(id);
+			return consumes[id]?.(k) ?? false;
+		},
+	}));
+	return { calls, layers };
+}
+
+const all = () => true;
+
+describe("C4 — LAYER_ORDER", () => {
+	test("R4 layers run top first: system, modal, input, screen, scroll, global", async () => {
+		const { LAYER_ORDER } = await load();
+		expect([...LAYER_ORDER]).toEqual(ORDER);
+	});
+});
+
+describe("C4 — dispatchKey: one keypress, one handler", () => {
+	for (const [i, consumer] of ORDER.entries()) {
+		test(`R4.1 when ${consumer} consumes, dispatchKey returns "${consumer}" and no lower layer is called`, async () => {
+			const { dispatchKey } = await load();
+			// Every layer from the consumer down would also consume — only order
+			// decides who gets it.
+			const consumes: Partial<Record<LayerId, (k: Key) => boolean>> = {};
+			for (const id of ORDER.slice(i)) consumes[id] = all;
+			const r = stack(consumes);
+			expect(dispatchKey(r.layers, key("x"))).toBe(consumer);
+			expect(r.calls).toEqual(ORDER.slice(0, i + 1));
+		});
+	}
+
+	test("R4.1 layers are visited in LAYER_ORDER regardless of array order", async () => {
+		const { dispatchKey } = await load();
+		const shuffled: LayerId[] = [
+			"global",
+			"screen",
+			"system",
+			"scroll",
+			"input",
+			"modal",
+		];
+		const r = stack({}, {}, shuffled);
+		expect(dispatchKey(r.layers, key("x"))).toBeNull();
+		expect(r.calls).toEqual(ORDER);
+	});
+
+	test("R4.1 with every layer consuming in reversed array order, system wins alone", async () => {
+		const { dispatchKey } = await load();
+		const r = stack(
+			{
+				system: all,
+				modal: all,
+				input: all,
+				screen: all,
+				scroll: all,
+				global: all,
+			},
+			{},
+			[...ORDER].reverse(),
+		);
+		expect(dispatchKey(r.layers, key("x"))).toBe("system");
+		expect(r.calls).toEqual(["system"]);
+	});
+
+	test("R4.1 inactive layers are skipped: their handle() is never called", async () => {
+		const { dispatchKey } = await load();
+		const r = stack(
+			{ modal: all, input: all, global: all },
+			{ modal: false, input: false },
+		);
+		expect(dispatchKey(r.layers, key("x"))).toBe("global");
+		expect(r.calls).toEqual(["system", "screen", "scroll", "global"]);
+	});
+
+	test("R4.1 dispatchKey returns null when no layer consumes, calling each active layer once", async () => {
+		const { dispatchKey } = await load();
+		const r = stack({});
+		expect(dispatchKey(r.layers, key("x"))).toBeNull();
+		expect(r.calls).toEqual(ORDER);
+	});
+
+	test("R4.1 missing layers are fine: a stack of only screen and global", async () => {
+		const { dispatchKey } = await load();
+		const calls: LayerId[] = [];
+		const layers = (["global", "screen"] as LayerId[]).map((id) => ({
+			id,
+			active: true,
+			handle: () => {
+				calls.push(id);
+				return id === "global";
+			},
+		}));
+		expect(dispatchKey(layers, key("1"))).toBe("global");
+		expect(calls).toEqual(["screen", "global"]);
+	});
+});
+
+describe("C4 — system and modal layers", () => {
+	test("R4.2 Ctrl+C is consumed by system even while a modal that eats every key is open", async () => {
+		const { dispatchKey } = await load();
+		const r = stack({
+			system: (k) => k.ctrl && k.name === "c",
+			modal: all,
+			global: all,
+		});
+		expect(dispatchKey(r.layers, ctrl("c"))).toBe("system");
+		expect(r.calls).toEqual(["system"]);
+	});
+
+	const MODAL_KEYS = [
+		...DIGITS,
+		key("q"),
+		key("?"),
+		key("escape"),
+		key("return"),
+		key("tab"),
+		key("tab", { shift: true }),
+		key("up"),
+		key("down"),
+		key("j"),
+		key("k"),
+		...SCROLL_KEYS,
+	];
+
+	for (const k of MODAL_KEYS) {
+		const label = `${k.ctrl ? "ctrl+" : ""}${k.shift ? "shift+" : ""}${k.name}`;
+		test(`R4.3 with a modal open, ${label} reaches no input/screen/scroll/global handler`, async () => {
+			const { dispatchKey } = await load();
+			const r = stack({
+				modal: all,
+				input: all,
+				screen: all,
+				scroll: all,
+				global: all,
+			});
+			expect(dispatchKey(r.layers, k)).toBe("modal");
+			expect(r.calls).toEqual(["system", "modal"]);
+		});
+	}
+
+	test("R4.8 Enter in a confirm modal confirms the modal only; the screen never sees it", async () => {
+		const { dispatchKey } = await load();
+		let confirmed = 0;
+		let screenActed = 0;
+		const r = stack({
+			modal: (k) => {
+				if (k.name === "return") confirmed++;
+				return true;
+			},
+			screen: (k) => {
+				if (k.name === "return") screenActed++;
+				return true;
+			},
+		});
+		expect(dispatchKey(r.layers, key("return"))).toBe("modal");
+		expect(confirmed).toBe(1);
+		expect(screenActed).toBe(0);
+	});
+});
+
+describe("C4 — input layer (a focused search box) wired through inputLayerConsumes", () => {
+	/**
+	 * A realistic stack: input consumes exactly what inputLayerConsumes says,
+	 * the screen moves the selection on up/down, scroll takes isScrollKey, and
+	 * global would act on anything that reaches it.
+	 */
+	async function focusedStack() {
+		const { dispatchKey, inputLayerConsumes, isScrollKey } = await load();
+		const r = stack({
+			input: (k) => inputLayerConsumes(k),
+			screen: (k) => k.name === "up" || k.name === "down",
+			scroll: (k) => isScrollKey(k),
+			global: all,
+		});
+		return { dispatch: (k: Key) => dispatchKey(r.layers, k), calls: r.calls };
+	}
+
+	for (const d of DIGITS) {
+		test(`R4.4 digit ${d.name} typed into search does not switch tabs`, async () => {
+			const s = await focusedStack();
+			expect(s.dispatch(d)).toBe("input");
+			expect(s.calls).not.toContain("global");
+		});
+	}
+
+	for (const [name, k] of [
+		["j", key("j")],
+		["k", key("k")],
+		["q", key("q")],
+		["?", key("?")],
+		["? (with shift)", key("?", { shift: true })],
+		["space", key("space")],
+		["backspace", key("backspace")],
+		["Enter", key("return")],
+	] as const) {
+		test(`R4.4 ${name} with search focused is handled by the input layer only`, async () => {
+			const s = await focusedStack();
+			expect(s.dispatch(k)).toBe("input");
+			expect(s.calls).toEqual(["system", "modal", "input"]);
+		});
+	}
+
+	test("R4.4 Esc with search focused never reaches global (never quits or changes screen)", async () => {
+		const s = await focusedStack();
+		expect(s.dispatch(key("escape"))).toBe("input");
+		expect(s.calls).not.toContain("global");
+	});
+
+	for (const dir of ["up", "down"]) {
+		test(`R4.4 ${dir} passes through the focused input to the screen (moves the selection)`, async () => {
+			const s = await focusedStack();
+			expect(s.dispatch(key(dir))).toBe("screen");
+			expect(s.calls).toEqual(["system", "modal", "input", "screen"]);
+		});
+	}
+
+	for (const k of SCROLL_KEYS) {
+		const label = `${k.ctrl ? "ctrl+" : ""}${k.name}`;
+		test(`R4.6 ${label} scrolls the panel while a search box has focus`, async () => {
+			const s = await focusedStack();
+			expect(s.dispatch(k)).toBe("scroll");
+			expect(s.calls).not.toContain("global");
+		});
+	}
+
+	test("R4.7 without a focused input, a digit reaches the global layer (switches tab)", async () => {
+		const { dispatchKey, inputLayerConsumes, isScrollKey } = await load();
+		const r = stack(
+			{
+				input: (k) => inputLayerConsumes(k),
+				screen: () => false,
+				scroll: (k) => isScrollKey(k),
+				global: all,
+			},
+			{ input: false },
+		);
+		expect(dispatchKey(r.layers, key("3"))).toBe("global");
+	});
+
+	test("R4.7 Tab is not consumed by a focused input, so it can reach global", async () => {
+		const s = await focusedStack();
+		expect(s.dispatch(key("tab"))).toBe("global");
+	});
+});
+
+describe("C4 — inputLayerConsumes", () => {
+	const printable: Key[] = [
+		..."abcdefghijklmnopqrstuvwxyz".split("").map((c) => key(c)),
+		..."ABCDEFGHIJKLMNOPQRSTUVWXYZ".split("").map((c) => upper(c)),
+		...DIGITS,
+		...["?", "/", "-", "_", ".", ",", ":", "@", "!", "#", "=", "+", "*"].map(
+			(c) => key(c),
+		),
+		key("?", { shift: true }),
+		key("space"),
+	];
+
+	for (const k of printable) {
+		test(`R4.4 printable ${JSON.stringify(k.sequence)} (name ${k.name}${k.shift ? ", shift" : ""}) is consumed by the input layer`, async () => {
+			const { inputLayerConsumes } = await load();
+			expect(inputLayerConsumes(k)).toBe(true);
+		});
+	}
+
+	for (const name of ["backspace", "return", "escape"]) {
+		test(`R4.4 ${name} is consumed by the input layer`, async () => {
+			const { inputLayerConsumes } = await load();
+			expect(inputLayerConsumes(key(name))).toBe(true);
+		});
+	}
+
+	const notConsumed: [string, Key][] = [
+		["up", key("up")],
+		["down", key("down")],
+		["tab", key("tab")],
+		["shift+tab", key("tab", { shift: true })],
+		["pageup", key("pageup")],
+		["pagedown", key("pagedown")],
+		["ctrl+u", ctrl("u")],
+		["ctrl+d", ctrl("d")],
+		["ctrl+c", ctrl("c")],
+		["ctrl+a", ctrl("a")],
+		["ctrl+k", ctrl("k")],
+		["meta+x", key("x", { meta: true, sequence: "\x1bx" })],
+		["meta+1", key("1", { meta: true, sequence: "\x1b1" })],
+	];
+
+	for (const [label, k] of notConsumed) {
+		test(`R4.4/R4.6 ${label} is NOT consumed by the input layer`, async () => {
+			const { inputLayerConsumes } = await load();
+			expect(inputLayerConsumes(k)).toBe(false);
+		});
+	}
+});
+
+describe("C4 — isScrollKey", () => {
+	for (const k of SCROLL_KEYS) {
+		const label = `${k.ctrl ? "ctrl+" : ""}${k.name}`;
+		test(`R4.6 ${label} is a scroll key`, async () => {
+			const { isScrollKey } = await load();
+			expect(isScrollKey(k)).toBe(true);
+		});
+	}
+
+	for (const [label, k] of [
+		["u", key("u")],
+		["d", key("d")],
+		["U", upper("U")],
+		["D", upper("D")],
+		["up", key("up")],
+		["down", key("down")],
+		["space", key("space")],
+		["return", key("return")],
+		["ctrl+c", ctrl("c")],
+		["tab", key("tab")],
+	] as [string, Key][]) {
+		test(`R4.6 ${label} is not a scroll key`, async () => {
+			const { isScrollKey } = await load();
+			expect(isScrollKey(k)).toBe(false);
+		});
+	}
+});