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});