xonecas.io
70160
Ce

cel-tui / files

cel-tui / packages / core / src / keys.test.ts

15.3 KB
1import { describe, expect, test } from "bun:test";
2import {
3  decodeKeyEvents,
4  isEditingKey,
5  normalizeKey,
6  parseKey,
7} from "./keys.js";
8import { kittyEncode } from "./test-helpers.js";
9
10// ── kittyEncode helper sanity checks ────────────────────────────────────────
11
12describe("kittyEncode helper", () => {
13  test("unmodified printable → raw byte", () => {
14    expect(kittyEncode("a")).toBe("a");
15    expect(kittyEncode("1")).toBe("1");
16    expect(kittyEncode("/")).toBe("/");
17  });
18
19  test("named printable keys → raw byte when unmodified", () => {
20    expect(kittyEncode("space")).toBe(" ");
21    expect(kittyEncode("plus")).toBe("+");
22  });
23
24  test("special keys → CSI u", () => {
25    expect(kittyEncode("escape")).toBe("\x1b[27u");
26    expect(kittyEncode("enter")).toBe("\x1b[13u");
27    expect(kittyEncode("tab")).toBe("\x1b[9u");
28    expect(kittyEncode("backspace")).toBe("\x1b[127u");
29  });
30
31  test("modifier combos → CSI u with modifier param", () => {
32    // Modifier bitmask: shift=1, alt=2, ctrl=4. Param = bitmask + 1.
33    expect(kittyEncode("ctrl+c")).toBe("\x1b[99;5u"); // ctrl=4 → 5
34    expect(kittyEncode("alt+x")).toBe("\x1b[120;3u"); // alt=2 → 3
35    expect(kittyEncode("shift+enter")).toBe("\x1b[13;2u"); // shift=1 → 2
36    expect(kittyEncode("ctrl+shift+n")).toBe("\x1b[110;6u"); // ctrl+shift=5 → 6
37    expect(kittyEncode("ctrl+alt+shift+a")).toBe("\x1b[97;8u"); // all=7 → 8
38  });
39
40  test("arrow keys → CSI letter", () => {
41    expect(kittyEncode("up")).toBe("\x1b[A");
42    expect(kittyEncode("ctrl+up")).toBe("\x1b[1;5A");
43  });
44
45  test("tilde keys", () => {
46    expect(kittyEncode("delete")).toBe("\x1b[3~");
47    expect(kittyEncode("shift+delete")).toBe("\x1b[3;2~");
48  });
49
50  test("function keys", () => {
51    expect(kittyEncode("f1")).toBe("\x1b[11~");
52    expect(kittyEncode("ctrl+f5")).toBe("\x1b[15;5~");
53  });
54
55  test("named printable keys with modifiers → CSI u", () => {
56    expect(kittyEncode("ctrl+space")).toBe("\x1b[32;5u");
57    expect(kittyEncode("ctrl+plus")).toBe("\x1b[43;5u");
58  });
59});
60
61// ── parseKey ────────────────────────────────────────────────────────────────
62
63describe("parseKey", () => {
64  // --- Raw printable characters (raw bytes with baseline flags) ---
65
66  describe("raw printable characters", () => {
67    test("lowercase letters", () => {
68      expect(parseKey("a")).toBe("a");
69      expect(parseKey("z")).toBe("z");
70    });
71
72    test("uppercase letters lowercased", () => {
73      expect(parseKey("A")).toBe("a");
74      expect(parseKey("Z")).toBe("z");
75    });
76
77    test("digits", () => {
78      expect(parseKey("1")).toBe("1");
79      expect(parseKey("0")).toBe("0");
80    });
81
82    test("symbols", () => {
83      expect(parseKey("/")).toBe("/");
84      expect(parseKey("-")).toBe("-");
85      expect(parseKey("=")).toBe("=");
86      expect(parseKey("[")).toBe("[");
87    });
88
89    test("space maps to named key", () => {
90      expect(parseKey(" ")).toBe("space");
91    });
92
93    test("plus maps to named key", () => {
94      expect(parseKey("+")).toBe("plus");
95    });
96
97    test("multi-byte UTF-8 passed through", () => {
98      expect(parseKey("世")).toBe("世");
99      expect(parseKey("é")).toBe("é");
100    });
101  });
102
103  // --- Legacy bytes for unmodified special keys ---
104  // With baseline disambiguation, unmodified special keys retain their traditional
105  // encoding. Only modified variants get the CSI u treatment.
106
107  describe("legacy bytes for unmodified special keys", () => {
108    test("tab", () => {
109      expect(parseKey("\t")).toBe("tab");
110    });
111
112    test("enter", () => {
113      expect(parseKey("\r")).toBe("enter");
114    });
115
116    test("escape", () => {
117      expect(parseKey("\x1b")).toBe("escape");
118    });
119
120    test("backspace", () => {
121      expect(parseKey("\x7f")).toBe("backspace");
122    });
123  });
124
125  describe("legacy compatibility encodings", () => {
126    test("recoverable ASCII control bytes normalize to ctrl+letter", () => {
127      expect(parseKey("\x01")).toBe("ctrl+a");
128      expect(parseKey("\x08")).toBe("ctrl+h");
129      expect(parseKey("\x12")).toBe("ctrl+r");
130      expect(parseKey("\x1a")).toBe("ctrl+z");
131    });
132
133    test("ESC-prefixed Alt combinations normalize to alt+<key>", () => {
134      expect(parseKey("\x1bx")).toBe("alt+x");
135      expect(parseKey("\x1bX")).toBe("alt+x");
136      expect(parseKey("\x1b+")).toBe("alt+plus");
137    });
138  });
139
140  // --- CSI u: special keys (also valid, sent by some terminals) ---
141
142  describe("CSI u special keys", () => {
143    test("escape", () => {
144      expect(parseKey("\x1b[27u")).toBe("escape");
145    });
146
147    test("enter", () => {
148      expect(parseKey("\x1b[13u")).toBe("enter");
149    });
150
151    test("tab", () => {
152      expect(parseKey("\x1b[9u")).toBe("tab");
153    });
154
155    test("backspace", () => {
156      expect(parseKey("\x1b[127u")).toBe("backspace");
157    });
158
159    test("space via CSI u", () => {
160      expect(parseKey("\x1b[32u")).toBe("space");
161    });
162
163    test("plus via CSI u", () => {
164      expect(parseKey("\x1b[43u")).toBe("plus");
165    });
166
167    test("legacy shift+tab (CSI Z)", () => {
168      // tmux and some terminals send this instead of CSI 9;2 u
169      expect(parseKey("\x1b[Z")).toBe("shift+tab");
170    });
171
172    test("explicit modifier=1 means no modifiers", () => {
173      expect(parseKey("\x1b[27;1u")).toBe("escape");
174      expect(parseKey("\x1b[13;1u")).toBe("enter");
175    });
176
177    test("printable codepoint via CSI u (robustness)", () => {
178      // With baseline flags unmodified printable chars arrive as raw bytes,
179      // but the parser should handle CSI u for them gracefully
180      expect(parseKey("\x1b[97u")).toBe("a");
181      expect(parseKey("\x1b[65u")).toBe("a"); // uppercase A codepoint → lowercase
182    });
183  });
184
185  // --- CSI u: modifier combos ---
186
187  describe("CSI u modifier combos", () => {
188    test("ctrl+letter", () => {
189      expect(parseKey(kittyEncode("ctrl+c"))).toBe("ctrl+c");
190      expect(parseKey(kittyEncode("ctrl+s"))).toBe("ctrl+s");
191      expect(parseKey(kittyEncode("ctrl+q"))).toBe("ctrl+q");
192      expect(parseKey(kittyEncode("ctrl+a"))).toBe("ctrl+a");
193    });
194
195    test("alt+letter", () => {
196      expect(parseKey(kittyEncode("alt+x"))).toBe("alt+x");
197      expect(parseKey(kittyEncode("alt+a"))).toBe("alt+a");
198    });
199
200    test("shift+special", () => {
201      expect(parseKey(kittyEncode("shift+enter"))).toBe("shift+enter");
202      expect(parseKey(kittyEncode("shift+tab"))).toBe("shift+tab");
203    });
204
205    test("ctrl+special", () => {
206      expect(parseKey(kittyEncode("ctrl+enter"))).toBe("ctrl+enter");
207      expect(parseKey(kittyEncode("ctrl+space"))).toBe("ctrl+space");
208      expect(parseKey(kittyEncode("ctrl+plus"))).toBe("ctrl+plus");
209    });
210
211    test("multi-modifier combos", () => {
212      expect(parseKey(kittyEncode("ctrl+shift+n"))).toBe("ctrl+shift+n");
213      expect(parseKey(kittyEncode("ctrl+alt+shift+a"))).toBe(
214        "ctrl+alt+shift+a",
215      );
216      expect(parseKey(kittyEncode("ctrl+alt+x"))).toBe("ctrl+alt+x");
217    });
218  });
219
220  // --- Arrow keys ---
221
222  describe("arrow keys", () => {
223    test("unmodified arrows", () => {
224      expect(parseKey(kittyEncode("up"))).toBe("up");
225      expect(parseKey(kittyEncode("down"))).toBe("down");
226      expect(parseKey(kittyEncode("right"))).toBe("right");
227      expect(parseKey(kittyEncode("left"))).toBe("left");
228    });
229
230    test("modified arrows", () => {
231      expect(parseKey(kittyEncode("ctrl+up"))).toBe("ctrl+up");
232      expect(parseKey(kittyEncode("shift+left"))).toBe("shift+left");
233      expect(parseKey(kittyEncode("alt+down"))).toBe("alt+down");
234      expect(parseKey(kittyEncode("ctrl+shift+right"))).toBe(
235        "ctrl+shift+right",
236      );
237    });
238  });
239
240  // --- Home/End ---
241
242  describe("home/end", () => {
243    test("unmodified", () => {
244      expect(parseKey(kittyEncode("home"))).toBe("home");
245      expect(parseKey(kittyEncode("end"))).toBe("end");
246    });
247
248    test("modified", () => {
249      expect(parseKey(kittyEncode("ctrl+home"))).toBe("ctrl+home");
250      expect(parseKey(kittyEncode("shift+end"))).toBe("shift+end");
251    });
252  });
253
254  // --- Tilde keys (Delete, PageUp, PageDown) ---
255
256  describe("tilde keys", () => {
257    test("unmodified", () => {
258      expect(parseKey(kittyEncode("delete"))).toBe("delete");
259      expect(parseKey(kittyEncode("pageup"))).toBe("pageup");
260      expect(parseKey(kittyEncode("pagedown"))).toBe("pagedown");
261    });
262
263    test("modified", () => {
264      expect(parseKey(kittyEncode("shift+delete"))).toBe("shift+delete");
265      expect(parseKey(kittyEncode("ctrl+pageup"))).toBe("ctrl+pageup");
266    });
267  });
268
269  // --- Function keys ---
270
271  describe("function keys", () => {
272    test("unmodified", () => {
273      expect(parseKey(kittyEncode("f1"))).toBe("f1");
274      expect(parseKey(kittyEncode("f5"))).toBe("f5");
275      expect(parseKey(kittyEncode("f12"))).toBe("f12");
276    });
277
278    test("modified", () => {
279      expect(parseKey(kittyEncode("ctrl+f5"))).toBe("ctrl+f5");
280      expect(parseKey(kittyEncode("shift+f1"))).toBe("shift+f1");
281    });
282  });
283});
284
285describe("advanced Kitty keyboard events", () => {
286  test("decodes press, repeat, and release event types", () => {
287    const events = decodeKeyEvents(
288      "\x1b[97;1:1;97u\x1b[97;1:2;97u\x1b[97;1:3u",
289    );
290
291    expect(events.map((event) => event.eventType)).toEqual([
292      "press",
293      "repeat",
294      "release",
295    ]);
296    expect(events.map((event) => event.text)).toEqual(["a", "a", undefined]);
297  });
298
299  test("decodes alternate keys, associated text, and the full modifier state", () => {
300    const [event] = decodeKeyEvents("\x1b[97:65:99;110:2;65u");
301
302    expect(event).toMatchObject({
303      key: "ctrl+shift+super+meta+a",
304      text: "A",
305      eventType: "repeat",
306      codePoint: 97,
307      shiftedKey: "A",
308      baseLayoutKey: "c",
309      modifiers: {
310        shift: true,
311        alt: false,
312        ctrl: true,
313        super: true,
314        hyper: false,
315        meta: true,
316        capsLock: true,
317        numLock: false,
318      },
319    });
320  });
321
322  test("decodes pure associated-text events", () => {
323    const [event] = decodeKeyEvents("\x1b[0;;229u");
324
325    expect(event).toMatchObject({
326      key: "å",
327      text: "å",
328      eventType: "press",
329      codePoint: 0,
330    });
331  });
332
333  test("preserves multi-codepoint associated text as one event", () => {
334    const [event] = decodeKeyEvents("\x1b[0;;128105:8205:128187u");
335
336    expect(event).toMatchObject({
337      key: "👩‍💻",
338      text: "👩‍💻",
339      eventType: "press",
340      codePoint: 0,
341    });
342  });
343
344  test("reports every currently defined modifier and lock bit", () => {
345    const [event] = decodeKeyEvents("\x1b[97;256:2;65u");
346
347    expect(event).toMatchObject({
348      key: "ctrl+alt+shift+super+hyper+meta+a",
349      eventType: "repeat",
350      text: "A",
351      modifiers: {
352        shift: true,
353        alt: true,
354        ctrl: true,
355        super: true,
356        hyper: true,
357        meta: true,
358        capsLock: true,
359        numLock: true,
360      },
361    });
362  });
363
364  test("decodes event types on CSI letter and tilde forms", () => {
365    const events = decodeKeyEvents("\x1b[1;5:3D\x1b[3;1:2~");
366
367    expect(events.map(({ key, eventType }) => ({ key, eventType }))).toEqual([
368      { key: "ctrl+left", eventType: "release" },
369      { key: "delete", eventType: "repeat" },
370    ]);
371  });
372
373  test("names modifier-key events reported by all-keys mode", () => {
374    const [event] = decodeKeyEvents("\x1b[57442;1:3u");
375
376    expect(event).toMatchObject({
377      key: "left-control",
378      eventType: "release",
379      codePoint: 57442,
380    });
381  });
382
383  test("preserves event order in a mixed advanced and legacy stream", () => {
384    const events = decodeKeyEvents("A\x12\x1b[97;1:2;97u\x1bx");
385
386    expect(
387      events.map(({ key, eventType, text }) => ({ key, eventType, text })),
388    ).toEqual([
389      { key: "a", eventType: "press", text: "A" },
390      { key: "ctrl+r", eventType: "press", text: undefined },
391      { key: "a", eventType: "repeat", text: "a" },
392      { key: "alt+x", eventType: "press", text: undefined },
393    ]);
394  });
395
396  test("keeps malformed event metadata contained to its CSI sequence", () => {
397    const events = decodeKeyEvents(
398      "\x1b[97;1:9;97u\x1b[97;0;97u\x1b[55296;1;97uZ",
399    );
400
401    expect(events.map((event) => event.key)).toEqual([
402      "unknown:97;1:9;97u",
403      "unknown:97;0;97u",
404      "unknown:55296;1;97u",
405      "z",
406    ]);
407  });
408
409  test("never exposes control codes as associated insertable text", () => {
410    const [event] = decodeKeyEvents("\x1b[97;1:1;13u");
411
412    expect(event?.key).toBe("a");
413    expect(event?.text).toBeUndefined();
414  });
415});
416
417// ── isEditingKey ────────────────────────────────────────────────────────────
418
419describe("isEditingKey", () => {
420  test("single printable characters are editing keys", () => {
421    expect(isEditingKey("a")).toBe(true);
422    expect(isEditingKey("1")).toBe(true);
423    expect(isEditingKey("/")).toBe(true);
424  });
425
426  test("named editing keys", () => {
427    expect(isEditingKey("enter")).toBe(true);
428    expect(isEditingKey("backspace")).toBe(true);
429    expect(isEditingKey("delete")).toBe(true);
430    expect(isEditingKey("tab")).toBe(true);
431    expect(isEditingKey("space")).toBe(true);
432    expect(isEditingKey("plus")).toBe(true);
433    expect(isEditingKey("up")).toBe(true);
434    expect(isEditingKey("down")).toBe(true);
435    expect(isEditingKey("left")).toBe(true);
436    expect(isEditingKey("right")).toBe(true);
437    expect(isEditingKey("home")).toBe(true);
438    expect(isEditingKey("end")).toBe(true);
439  });
440
441  test("shift+enter is an editing key (inserts newline)", () => {
442    expect(isEditingKey("shift+enter")).toBe(true);
443  });
444
445  test("TextInput modifier editing shortcuts are editing keys", () => {
446    expect(isEditingKey("ctrl+a")).toBe(true);
447    expect(isEditingKey("ctrl+e")).toBe(true);
448    expect(isEditingKey("alt+b")).toBe(true);
449    expect(isEditingKey("alt+f")).toBe(true);
450    expect(isEditingKey("ctrl+left")).toBe(true);
451    expect(isEditingKey("ctrl+right")).toBe(true);
452    expect(isEditingKey("ctrl+w")).toBe(true);
453    expect(isEditingKey("alt+d")).toBe(true);
454  });
455
456  test("other modifier combos are NOT editing keys", () => {
457    expect(isEditingKey("ctrl+s")).toBe(false);
458    expect(isEditingKey("ctrl+r")).toBe(false);
459    expect(isEditingKey("alt+x")).toBe(false);
460    expect(isEditingKey("alt+plus")).toBe(false);
461    expect(isEditingKey("ctrl+shift+n")).toBe(false);
462    expect(isEditingKey("shift+tab")).toBe(false);
463  });
464
465  test("escape is NOT an editing key", () => {
466    expect(isEditingKey("escape")).toBe(false);
467  });
468});
469
470// ── normalizeKey ────────────────────────────────────────────────────────────
471
472describe("normalizeKey", () => {
473  test("already normalized", () => {
474    expect(normalizeKey("ctrl+s")).toBe("ctrl+s");
475  });
476
477  test("reorders modifiers to canonical order", () => {
478    expect(normalizeKey("shift+ctrl+s")).toBe("ctrl+shift+s");
479    expect(normalizeKey("alt+ctrl+shift+a")).toBe("ctrl+alt+shift+a");
480  });
481
482  test("lowercases everything", () => {
483    expect(normalizeKey("Ctrl+S")).toBe("ctrl+s");
484  });
485
486  test("orders advanced modifiers after the compatible modifiers", () => {
487    expect(normalizeKey("meta+super+shift+ctrl+hyper+a")).toBe(
488      "ctrl+shift+super+hyper+meta+a",
489    );
490  });
491});