refactor: keyboard enhancements api improvements (#1534)

This commit is contained in:
Ayman Bagabas 2025-11-06 12:22:22 -05:00 committed by GitHub
parent d9f7210a9e
commit f03c467c1b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 123 additions and 75 deletions

View file

@ -120,16 +120,11 @@ func (s *cursedRenderer) start() {
if s.lastView.ProgressBar != nil {
setProgressBar(s, s.lastView.ProgressBar)
}
if !s.lastView.DisableKeyEnhancements {
kittyFlags := ansi.KittyDisambiguateEscapeCodes
if s.lastView.KeyReleases {
kittyFlags |= ansi.KittyReportEventTypes
}
if s.lastView.UniformKeyLayout {
kittyFlags |= ansi.KittyReportAlternateKeys | ansi.KittyReportAllKeysAsEscapeCodes
}
_, _ = s.scr.WriteString(ansi.KittyKeyboard(kittyFlags, 1))
kittyFlags := ansi.KittyDisambiguateEscapeCodes
if s.lastView.KeyboardEnhancements.ReportEventTypes {
kittyFlags |= ansi.KittyReportEventTypes
}
_, _ = s.scr.WriteString(ansi.KittyKeyboard(kittyFlags, 1))
}
// close implements renderer.
@ -193,10 +188,8 @@ func (s *cursedRenderer) close() (err error) {
_, _ = s.scr.WriteString(ansi.ResetProgressBar)
}
if s.lastView != nil && !s.lastView.DisableKeyEnhancements {
// NOTE: This needs to happen after we exit the alt screen.
_, _ = s.scr.WriteString(ansi.KittyKeyboard(0, 1))
}
// NOTE: This needs to happen after we exit the alt screen.
_, _ = s.scr.WriteString(ansi.KittyKeyboard(0, 1))
}
if err := s.scr.Flush(); err != nil {
@ -287,26 +280,16 @@ func (s *cursedRenderer) flush(closing bool) error {
}
// kitty keyboard protocol
//nolint:nestif
if s.lastView == nil || view.DisableKeyEnhancements != s.lastView.DisableKeyEnhancements ||
view.KeyReleases != s.lastView.KeyReleases ||
view.UniformKeyLayout != s.lastView.UniformKeyLayout ||
if s.lastView == nil || view.KeyboardEnhancements != s.lastView.KeyboardEnhancements ||
view.AltScreen != s.lastView.AltScreen {
// NOTE: We need to reset the keyboard protocol when switching
// between main and alt screen. This is because the specs specify
// two different states for the main and alt screen.
if view.DisableKeyEnhancements {
_, _ = s.scr.WriteString(ansi.KittyKeyboard(0, 1))
} else {
kittyFlags := ansi.KittyDisambiguateEscapeCodes // always enable basic key disambiguation
if view.KeyReleases {
kittyFlags |= ansi.KittyReportEventTypes
}
if view.UniformKeyLayout {
kittyFlags |= ansi.KittyReportAlternateKeys | ansi.KittyReportAllKeysAsEscapeCodes
}
_, _ = s.scr.WriteString(ansi.KittyKeyboard(kittyFlags, 1))
kittyFlags := ansi.KittyDisambiguateEscapeCodes // always enable basic key disambiguation
if view.KeyboardEnhancements.ReportEventTypes {
kittyFlags |= ansi.KittyReportEventTypes
}
_, _ = s.scr.WriteString(ansi.KittyKeyboard(kittyFlags, 1))
if !closing {
// Request keyboard enhancements when they change
_, _ = s.scr.WriteString(ansi.RequestKittyKeyboard)

View file

@ -17,8 +17,8 @@ type styles struct {
}
type model struct {
supportsRelease bool
supportsDisambiguation bool
supportsEventTypes bool
styles styles
}
@ -28,14 +28,24 @@ func (m model) Init() tea.Cmd {
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
// When tea.RequestKeyboardEnhancements is called, the program will receive
// a tea.KeyboardEnhancementsMsg message. This means that an attempt to
// enable keyboard enhancements was made, however it doesn't guarantee that
// it was successful.
// Bubble Tea will send a [tea.KeyboardEnhancementsMsg] on startup if the
// terminal supports keyboard enhancements features.
//
// These features extend the capabilities of keyboard input beyond the basic legacy
// support found in most terminals. This includes features like:
// - Key disambiguation: Improved ability to distinguish between certain key presses
// like "enter" and "shift+enter" or "tab" and "ctrl+i".
// - Key event types: The ability to report different types of key events such as
// key presses and key releases.
//
// This allows for more nuanced input handling in terminal applications.
// You can ask Bubble Tea to request additional keyboard enhancements
// features by setting fields on the [tea.View.KeyboardEnhancements] struct
// in your [tea.View] method.
case tea.KeyboardEnhancementsMsg:
// Check which features were able to be enabled.
m.supportsRelease = msg.SupportsKeyReleases()
m.supportsDisambiguation = msg.SupportsKeyDisambiguation()
m.supportsDisambiguation = true // This is always enabled when this msg is received.
m.supportsEventTypes = msg.SupportsEventTypes()
case tea.KeyPressMsg:
switch msg.String() {
@ -58,15 +68,16 @@ func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
func (m model) View() tea.View {
var v tea.View
var b strings.Builder
fmt.Fprintf(&b, "Terminal supports key releases: %v\n", m.supportsRelease)
fmt.Fprintf(&b, "Terminal supports key releases: %v\n", m.supportsEventTypes)
fmt.Fprintf(&b, "Terminal supports key disambiguation: %v\n", m.supportsDisambiguation)
fmt.Fprint(&b, "This demo logs key events. Press ctrl+c to quit.")
v.SetContent(b.String() + "\n")
// Attempt to enable keyboard enhancements. By default, this just
// enables key disabiguation. For key releases, you'll need to opt-in
// to that feature.
v.KeyReleases = true
// Attempt to enable reporting key event types (key presses and key
// releases). By default, only key disambiguation is enabled which improves
// the ability to distinguish between certain key presses like "enter" and
// "shift+enter" or "tab" and "ctrl+i".
v.KeyboardEnhancements.ReportEventTypes = true
return v
}

View file

@ -15,10 +15,8 @@ func (m model) Init() tea.Cmd {
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
case tea.KeyboardEnhancementsMsg:
return m, tea.Printf("Keyboard enhancements: Disambiguation: %v, ReleaseKeys: %v, Uniform keys: %v\n",
msg.SupportsKeyDisambiguation(),
msg.SupportsKeyReleases(),
msg.SupportsUniformKeyLayout())
return m, tea.Printf("Keyboard enhancements: EventTypes: %v\n",
msg.SupportsEventTypes())
case tea.KeyMsg:
key := msg.Key()
switch msg := msg.(type) {
@ -41,8 +39,7 @@ func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
func (m model) View() tea.View {
v := tea.NewView("Press any key to see its details printed to the terminal. Press 'ctrl+c' to quit.")
v.KeyReleases = true
v.UniformKeyLayout = true
v.KeyboardEnhancements.ReportEventTypes = true
return v
}

View file

@ -7,25 +7,27 @@ import (
// KeyboardEnhancementsMsg is a message that gets sent when the terminal
// supports keyboard enhancements.
type KeyboardEnhancementsMsg struct {
// Flags is a bitmask of supported keyboard enhancement features.
// See [ansi.KittyReportEventTypes] and other constants for details.
//
// Example:
//
// ```go
// // The hard way
// if msg.Flags&ansi.KittyReportEventTypes != 0 {
// // Terminal supports reporting different key event types
// }
//
// // The easy way
// if msg.SupportsEventTypes() {
// // Terminal supports reporting different key event types
// }
// ```
Flags int
}
// SupportsKeyDisambiguation returns whether the terminal supports reporting
// disambiguous keys as escape codes.
func (k KeyboardEnhancementsMsg) SupportsKeyDisambiguation() bool {
return k.Flags&ansi.KittyDisambiguateEscapeCodes != 0
}
// SupportsKeyReleases returns whether the terminal supports key release
// events.
func (k KeyboardEnhancementsMsg) SupportsKeyReleases() bool {
// SupportsEventTypes returns whether the terminal supports reporting
// different types of key events (press, release, and repeat).
func (k KeyboardEnhancementsMsg) SupportsEventTypes() bool {
return k.Flags&ansi.KittyReportEventTypes != 0
}
// SupportsUniformKeyLayout returns whether the terminal supports reporting key
// events as though they were on a PC-101 layout.
func (k KeyboardEnhancementsMsg) SupportsUniformKeyLayout() bool {
return k.SupportsKeyDisambiguation() &&
k.Flags&ansi.KittyReportAlternateKeys != 0 &&
k.Flags&ansi.KittyReportAllKeysAsEscapeCodes != 0
}

79
tea.go
View file

@ -168,20 +168,75 @@ type View struct {
// [MouseModeNone], [MouseModeCellMotion], or [MouseModeAllMotion].
MouseMode MouseMode
// DisableKeyEnhancements disables all key enhancements for this view.
DisableKeyEnhancements bool
// KeyboardEnhancements describes what keyboard enhancement features Bubble
// Tea should request from the terminal.
//
// Bubble Tea supports requesting the following keyboard enhancement features:
// - ReportEventTypes: requests the terminal to report key repeat and
// release events.
//
// If the terminal supports any of these features, your program will
// receive a [KeyboardEnhancementsMsg] that indicates which features are
// available.
KeyboardEnhancements KeyboardEnhancements
}
// KeyReleases enables support for reporting key release events. This is
// useful for terminals that support the Kitty keyboard protocol "Report
// event types" progressive enhancement feature.
KeyReleases bool
// KeyboardEnhancements describes the requested keyboard enhancement features.
// If the terminal supports any of them, it will respond with a
// [KeyboardEnhancementsMsg] that indicates which features are supported.
// UniformKeyLayout enables support for reporting key events as though they
// were on a PC-101 layout. This is useful for uniform key event reporting
// across different keyboard layouts. This is equivalent to the Kitty
// keyboard protocol "Report alternate keys" and "Report all keys as escape
// codes" progressive enhancement features.
UniformKeyLayout bool
// KeyboardEnhancements defines different keyboard enhancement features that
// can be requested from the terminal.
// KeyboardEnhancements defines different keyboard enhancement features that
// can be requested from the terminal.
//
// By default, Bubble Tea requests basic key disambiguation features from the
// terminal. If the terminal supports keyboard enhancements, or any of its
// additional features, it will respond with a [KeyboardEnhancementsMsg] that
// indicates which features are supported.
//
// Example:
//
// ```go
// func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
// switch msg := msg.(type) {
// case tea.KeyboardEnhancementsMsg:
// // We have basic key disambiguation support.
// // We can handle "shift+enter", "ctrl+i", etc.
// m.keyboardEnhancements = msg
// if msg.ReportEventTypes {
// // Even better! We can now handle key repeat and release events.
// }
// case tea.KeyPressMsg:
// switch msg.String() {
// case "shift+enter":
// // Handle shift+enter
// // This would not be possible without keyboard enhancements.
// case "ctrl+j":
// // Handle ctrl+j
// }
// case tea.KeyReleaseMsg:
// // Whoa! A key was released!
// }
//
// return m, nil
// }
//
// func (m model) View() tea.View {
// v := tea.NewView("Press some keys!")
// // Request reporting key repeat and release events.
// v.KeyboardEnhancements.ReportEventTypes = true
// return v
// }
// ```
type KeyboardEnhancements struct {
// ReportEventTypes requests the terminal to report key repeat and release
// events.
// If supported, your program will receive [KeyReleaseMsg]s and
// [KeyPressMsg] with the [Key.IsRepeat] field set indicating that this is
// a it's part of a key repeat sequence.
ReportEventTypes bool
}
// SetContent sets the content of the view to the value.