feat: support extended keyboard enhancements (#1626)

This adds support for the Kitty keyboard protocol's extended
enhancements, allowing applications to request that the terminal report
additional information about key events, such as whether they're part of
a repeat sequence, alternate key values, and associated text.

Supersedes: https://github.com/charmbracelet/bubbletea/pull/1622
Fixes: https://github.com/charmbracelet/bubbletea/issues/1621
Fixes: https://github.com/charmbracelet/bubbletea/issues/1623
This commit is contained in:
Ayman Bagabas 2026-04-07 11:03:32 -04:00 committed by GitHub
parent ee06e98c41
commit 05df5aecf8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 56 additions and 8 deletions

View file

@ -131,10 +131,7 @@ func (s *cursedRenderer) start() {
// Both can coexist; terminals ignore what they don't support.
_, _ = s.scr.WriteString(ansi.SetModifyOtherKeys2)
kittyFlags := ansi.KittyDisambiguateEscapeCodes
if s.lastView.KeyboardEnhancements.ReportEventTypes {
kittyFlags |= ansi.KittyReportEventTypes
}
kittyFlags := keyboardEnhancementsFlags(s.lastView.KeyboardEnhancements)
_, _ = s.scr.WriteString(ansi.KittyKeyboard(kittyFlags, 1))
}
@ -379,10 +376,7 @@ func (s *cursedRenderer) flush(closing bool) error {
// Enable modifyOtherKeys and Kitty keyboard protocol.
_, _ = s.scr.WriteString(ansi.SetModifyOtherKeys2)
kittyFlags := ansi.KittyDisambiguateEscapeCodes // always enable basic key disambiguation
if view.KeyboardEnhancements.ReportEventTypes {
kittyFlags |= ansi.KittyReportEventTypes
}
kittyFlags := keyboardEnhancementsFlags(view.KeyboardEnhancements)
_, _ = s.scr.WriteString(ansi.KittyKeyboard(kittyFlags, 1))
if !closing {
// Request keyboard enhancements when they change
@ -828,3 +822,20 @@ func viewEquals(a, b *View) bool {
return true
}
func keyboardEnhancementsFlags(ke KeyboardEnhancements) int {
flags := 1 // always enable basic key disambiguation
if ke.ReportEventTypes {
flags |= ansi.KittyReportEventTypes
}
if ke.ReportAlternateKeys {
flags |= ansi.KittyReportAlternateKeys
}
if ke.ReportAllKeysAsEscapeCodes {
flags |= ansi.KittyReportAllKeysAsEscapeCodes
}
if ke.ReportAssociatedText {
flags |= ansi.KittyReportAssociatedKeys
}
return flags
}

View file

@ -39,3 +39,21 @@ func (k KeyboardEnhancementsMsg) SupportsKeyDisambiguation() bool {
func (k KeyboardEnhancementsMsg) SupportsEventTypes() bool {
return k.Flags&ansi.KittyReportEventTypes != 0
}
// SupportsAlternateKeys returns whether the terminal supports reporting
// alternate key codes.
func (k KeyboardEnhancementsMsg) SupportsAlternateKeys() bool {
return k.Flags&ansi.KittyReportAlternateKeys != 0
}
// SupportsAllKeysAsEscapeCodes returns whether the terminal supports reporting
// all keys as escape codes.
func (k KeyboardEnhancementsMsg) SupportsAllKeysAsEscapeCodes() bool {
return k.Flags&ansi.KittyReportAllKeysAsEscapeCodes != 0
}
// SupportsAssociatedText returns whether the terminal supports reporting
// associated text with key events.
func (k KeyboardEnhancementsMsg) SupportsAssociatedText() bool {
return k.Flags&ansi.KittyReportAssociatedKeys != 0
}

19
tea.go
View file

@ -245,6 +245,25 @@ type KeyboardEnhancements struct {
// [KeyPressMsg] with the [Key.IsRepeat] field set indicating that this is
// a it's part of a key repeat sequence.
ReportEventTypes bool
// ReportAlternateKeys requests the terminal to report alternate key values
// in addition to the main ones.
// Note that only key events represented as escape codes will affected by
// this enhancement.
ReportAlternateKeys bool
// ReportAllKeysAsEscapeCodes requests the terminal to report all key
// events, including plain text keys, as escape codes.
// When this is enabled, text won't be sent as plain text but instead as
// escape codes that encode the key value and modifiers.
ReportAllKeysAsEscapeCodes bool
// ReportAssociatedText requests the terminal to report the text associated
// with key events.
// Note that this is an enhancement to
// [KeyboardEnhancements.ReportAllKeysAsEscapeCodes] and only has an effect
// if that is enabled.
ReportAssociatedText bool
}
// SetContent is a helper method to set the content of a [View] with a styled