Skip to main content

Module gpui_chord

lattice_ui_gpui

Module gpui_chord 

Source
Expand description

GPUI Keystroke → KeyChord adapter.

Phase 5.7.B.3: mirrors the role of lattice-ui-tui::chord for the crossterm side — turns the renderer’s native key event shape into the canonical, renderer-neutral KeyChord that the host’s keymap trie + translate path both consume.

§Why a string-typed adapter (no gpui dep)

The lib of this crate must build (and its tests must run) in headless CI without the window Cargo feature so the host-substrate-reusable claim from 5.7’s scaffold slice remains provable on every host. Taking a &gpui::Keystroke would link the whole lattice-ui-gpui lib against gpui = "0.2.2" and the X11 / Wayland / Cocoa / Windows display libs it pulls in transitively.

Instead from_keystroke takes the shape of GPUI’s Keystroke as primitives: key: &str for the key id, plus four bools for the modifier set. The binary’s GPUI event handler is the thin glue that destructures KeyDownEvent.keystroke into those primitives and calls this adapter; the adapter itself is pure data.

§Normalisation rules

Match what lattice-ui-tui::chord::from_event produces so the keymap trie sees identical KeyChords regardless of which renderer originated the keystroke:

  • Letters with Ctrl / Alt: case folded to lowercase (Ctrl-C and Ctrl-c collapse).
  • Letters without modifiers: case preserved (a and A are distinct chords by vim convention).
  • Letters with shift only: shift folded into the case when GPUI reports the lowercase letter (some backends do); the redundant KeyMods::SHIFT is stripped.
  • Non-letter chars with shift only: shift stripped (the key string already encodes the shifted symbol — Shift-4 arrives as "$").
  • Specials with shift: shift preserved (<S-Tab> is distinct from <Tab>).
  • Space: bare space becomes KeyKind::Char(' '); with a modifier (<C-Space>) it stays a SpecialKey::Space so the trie has a distinct entry. GPUI’s "space" key string is accepted alongside the literal " " char.

Key-string vocabulary (case-insensitive, follows GPUI’s lowercase convention):

  • Specials: "escape" | "esc", "enter" | "return", "tab", "backspace", "space", "up", "down", "left", "right", "home", "end", "pageup", "pagedown", "insert", "delete".
  • Function keys: "f1".."f24" (out-of-range returns None).
  • Anything else of length 1 is treated as a printable character; longer strings that don’t match a special key id return None (GPUI may report compound names this adapter doesn’t recognise yet).

Functions§

from_keystroke
Normalise a GPUI Keystroke-shaped input into a canonical KeyChord.