Translates termbox NIF events into Raxol.Core.Events.Event structs.
Keycode source of truth
key_code values below are the REAL TB_KEY_* constants vendored at
packages/raxol_terminal/lib/termbox2_nif/c_src/termbox2/termbox2.h, not
assumed. Two earlier bugs, found by review, are fixed here:
- Arrow keys were mapped from 65/66/67/68 -- the ANSI CSI final
bytes for
A/B/C/D-- instead of the realTB_KEY_ARROW_{UP,DOWN,LEFT,RIGHT}values (0xffff - {18,19,20,21}= 65517/65516/65515/65514). - F1/F2 were mapped from 265/266 -- ncurses'
KEY_F(1)/KEY_F(2)(KEY_F0 + n,KEY_F0 = 264) -- instead of the realTB_KEY_F1/TB_KEY_F2(0xffff - {0,1}= 65535/65534).
Both bugs meant a REAL termbox event for an arrow key or F1/F2 would
have normalized to key: :unknown while the ANSI parser
(input_parser.ex) correctly produced :up/:down/.../:f1/:f2 for
the same physical keypress -- exactly the cross-shape divergence
Raxol.UI.Harness.InputEvent's normalizer is supposed to make
impossible. See @key_codes below for the full corrected table
(nav keys, F1-F12) plus the control-key-code handling for
Enter/Tab/Escape/Backspace.
Control keys (Enter/Tab/Escape/Backspace) share their numeric value with
a plain ASCII control byte (TB_KEY_ENTER = 0x0d, same as a raw \r).
Since it is not settled by inspection alone whether a real termbox
integration reports these via char_code (raw byte) or key_code
(TB_KEY_* constant, numerically identical for these), translate_key/3
checks BOTH: char_code is checked for a known control byte before the
generic "printable char" branch (so a control byte can never leak
through as char: on a kind: :char event), and key_code is checked
against the same values as a fallback. Either wiring convention lands on
the correct special-key atom.
Summary
Functions
Translates a termbox event map into an Event struct. Returns {:ok, event}, :ignore, or {:error, reason}.