feat: support xterm modifyOtherKeys keyboard protocol

commands.go

@@ -214,3 +214,25 @@ func WindowSize() Cmd {
 		return windowSizeMsg{}
 	}
 }
+
+// setEnhancedKeyboardMsg is a message to enable/disable enhanced keyboard
+// features.
+type setEnhancedKeyboardMsg bool
+
+// EnableEnhancedKeyboard is a command to enable enhanced keyboard features.
+// This unambiguously reports more key combinations than traditional terminal
+// keyboard sequences. This might also enable reporting of release key events
+// depending on the terminal emulator supporting it.
+//
+// This is equivalent to calling EnablieKittyKeyboard(3) and
+// EnableModifyOtherKeys(1).
+func EnableEnhancedKeyboard() Msg {
+	return setEnhancedKeyboardMsg(true)
+}
+
+// DisableEnhancedKeyboard is a command to disable enhanced keyboard features.
+//
+// This is equivalent to calling DisableKittyKeyboard() and DisableModifyOtherKeys().
+func DisableEnhancedKeyboard() Msg {
+	return setEnhancedKeyboardMsg(false)
+}

examples/go.mod

@@ -22,7 +22,7 @@ require (
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/aymanbagabas/go-udiff v0.2.0 // indirect
 	github.com/aymerick/douceur v0.2.0 // indirect
-	github.com/charmbracelet/x/ansi v0.1.4 // indirect
+	github.com/charmbracelet/x/ansi v0.1.5-0.20240814160751-e2dc8b53b604 // indirect
 	github.com/charmbracelet/x/exp/golden v0.0.0-20240715153702-9ba8adf781c4 // indirect
 	github.com/charmbracelet/x/input v0.1.0 // indirect
 	github.com/charmbracelet/x/term v0.1.1 // indirect

examples/go.sum

@@ -20,8 +20,8 @@ github.com/charmbracelet/harmonica v0.2.0 h1:8NxJWRWg/bzKqqEaaeFNipOu77YR5t8aSwG
 github.com/charmbracelet/harmonica v0.2.0/go.mod h1:KSri/1RMQOZLbw7AHqgcBycp8pgJnQMYYT8QZRqZ1Ao=
 github.com/charmbracelet/lipgloss v0.12.1 h1:/gmzszl+pedQpjCOH+wFkZr/N90Snz40J/NR7A0zQcs=
 github.com/charmbracelet/lipgloss v0.12.1/go.mod h1:V2CiwIuhx9S1S1ZlADfOj9HmxeMAORuz5izHb0zGbB8=
-github.com/charmbracelet/x/ansi v0.1.4 h1:IEU3D6+dWwPSgZ6HBH+v6oUuZ/nVawMiWj5831KfiLM=
-github.com/charmbracelet/x/ansi v0.1.4/go.mod h1:dk73KoMTT5AX5BsX0KrqhsTqAnhZZoCBjs7dGWp4Ktw=
+github.com/charmbracelet/x/ansi v0.1.5-0.20240814160751-e2dc8b53b604 h1:UBOeE/UdmNlTa7KVGdCdYGYpOBZPD0LMMw0Bcp6fCj4=
+github.com/charmbracelet/x/ansi v0.1.5-0.20240814160751-e2dc8b53b604/go.mod h1:dk73KoMTT5AX5BsX0KrqhsTqAnhZZoCBjs7dGWp4Ktw=
 github.com/charmbracelet/x/exp/golden v0.0.0-20240715153702-9ba8adf781c4 h1:6KzMkQeAF56rggw2NZu1L+TH7j9+DM1/2Kmh7KUxg1I=
 github.com/charmbracelet/x/exp/golden v0.0.0-20240715153702-9ba8adf781c4/go.mod h1:wDlXFlCrmJ8J+swcL/MnGUuYnqgQdW9rhSD61oNMb6U=
 github.com/charmbracelet/x/exp/teatest v0.0.0-20240521184646-23081fb03b28 h1:sOWKNRjt8uOEVgPiJVIJCse1+mUDM2F/vYY6W0Go640=

examples/print-key/main.go

@@ -0,0 +1,36 @@
+package main
+
+import (
+	"log"
+
+	tea "github.com/charmbracelet/bubbletea"
+)
+
+type model struct{}
+
+func (m model) Init() tea.Cmd {
+	return nil
+}
+
+func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+	switch msg := msg.(type) {
+	case tea.KeyPressMsg:
+		switch msg.String() {
+		case "ctrl+c":
+			return m, tea.Quit
+		}
+		return m, tea.Printf("You pressed: %s\n", msg.String())
+	}
+	return m, nil
+}
+
+func (m model) View() string {
+	return "Press any key to see it printed to the terminal. Press 'ctrl+c' to quit."
+}
+
+func main() {
+	p := tea.NewProgram(model{}, tea.WithEnhancedKeyboard())
+	if _, err := p.Run(); err != nil {
+		log.Printf("Error running program: %v", err)
+	}
+}

go.mod

@@ -3,11 +3,12 @@ module github.com/charmbracelet/bubbletea
 go 1.18
 
 require (
-	github.com/charmbracelet/x/ansi v0.1.5-0.20240814155920-d72bfb0444d7
+	github.com/charmbracelet/x/ansi v0.1.5-0.20240814160751-e2dc8b53b604
 	github.com/charmbracelet/x/term v0.1.1
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f
 	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6
 	github.com/muesli/cancelreader v0.2.2
+	github.com/rivo/uniseg v0.4.7
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e
 	golang.org/x/sync v0.8.0
 	golang.org/x/sys v0.24.0
@@ -17,5 +18,4 @@ require (
 	github.com/charmbracelet/x/input v0.1.0 // indirect
 	github.com/charmbracelet/x/windows v0.1.0 // indirect
 	github.com/mattn/go-runewidth v0.0.15 // indirect
-	github.com/rivo/uniseg v0.4.7 // indirect
 )

go.sum

@@ -1,9 +1,5 @@
-github.com/charmbracelet/x/ansi v0.1.4 h1:IEU3D6+dWwPSgZ6HBH+v6oUuZ/nVawMiWj5831KfiLM=
-github.com/charmbracelet/x/ansi v0.1.4/go.mod h1:dk73KoMTT5AX5BsX0KrqhsTqAnhZZoCBjs7dGWp4Ktw=
-github.com/charmbracelet/x/ansi v0.1.5-0.20240813204730-a29dab672bf2 h1:/BRVAHphENSsvuYG+iVP/qgC6Bjjc9zdOmY3pQzg7mE=
-github.com/charmbracelet/x/ansi v0.1.5-0.20240813204730-a29dab672bf2/go.mod h1:dk73KoMTT5AX5BsX0KrqhsTqAnhZZoCBjs7dGWp4Ktw=
-github.com/charmbracelet/x/ansi v0.1.5-0.20240814155920-d72bfb0444d7 h1:wcBKMnW8Fm0Oiw6b7pTXe+5eCntEuKI6s82J41nZcEY=
-github.com/charmbracelet/x/ansi v0.1.5-0.20240814155920-d72bfb0444d7/go.mod h1:dk73KoMTT5AX5BsX0KrqhsTqAnhZZoCBjs7dGWp4Ktw=
+github.com/charmbracelet/x/ansi v0.1.5-0.20240814160751-e2dc8b53b604 h1:UBOeE/UdmNlTa7KVGdCdYGYpOBZPD0LMMw0Bcp6fCj4=
+github.com/charmbracelet/x/ansi v0.1.5-0.20240814160751-e2dc8b53b604/go.mod h1:dk73KoMTT5AX5BsX0KrqhsTqAnhZZoCBjs7dGWp4Ktw=
 github.com/charmbracelet/x/input v0.1.0 h1:TEsGSfZYQyOtp+STIjyBq6tpRaorH0qpwZUj8DavAhQ=
 github.com/charmbracelet/x/input v0.1.0/go.mod h1:ZZwaBxPF7IG8gWWzPUVqHEtWhc1+HXJPNuerJGRGZ28=
 github.com/charmbracelet/x/term v0.1.1 h1:3cosVAiPOig+EV4X9U+3LDgtwwAoEzJjNdwbXDjF6yI=

key_test.go

@@ -113,6 +113,28 @@ func buildBaseSeqTests() []seqTest {
 func TestParseSequence(t *testing.T) {
 	td := buildBaseSeqTests()
 	td = append(td,
+		// Xterm modifyOtherKeys CSI 27 ; <modifier> ; <code> ~
+		seqTest{
+			[]byte("\x1b[27;3;20320~"),
+			[]Msg{KeyPressMsg{Runes: []rune{'你'}, Mod: ModAlt}},
+		},
+		seqTest{
+			[]byte("\x1b[27;3;65~"),
+			[]Msg{KeyPressMsg{Runes: []rune{'A'}, Mod: ModAlt}},
+		},
+		seqTest{
+			[]byte("\x1b[27;3;8~"),
+			[]Msg{KeyPressMsg{Type: KeyBackspace, Mod: ModAlt}},
+		},
+		seqTest{
+			[]byte("\x1b[27;3;27~"),
+			[]Msg{KeyPressMsg{Type: KeyEscape, Mod: ModAlt}},
+		},
+		seqTest{
+			[]byte("\x1b[27;3;127~"),
+			[]Msg{KeyPressMsg{Type: KeyBackspace, Mod: ModAlt}},
+		},
+
 		// Kitty keyboard / CSI u (fixterms)
 		seqTest{
 			[]byte("\x1b[1B"),

kitty.go

@@ -45,18 +45,6 @@ func KittyKeyboard() Msg {
 	return kittyKeyboardMsg{}
 }
 
-// EnableEnhancedKeyboard is a command to enable enhanced keyboard features.
-// This unambiguously reports more key combinations than traditional terminal
-// keyboard sequences. This will also enable reporting of release key events.
-func EnableEnhancedKeyboard() Msg {
-	return setKittyKeyboardFlagsMsg(3)
-}
-
-// DisableEnhancedKeyboard is a command to disable enhanced keyboard features.
-func DisableEnhancedKeyboard() Msg {
-	return setKittyKeyboardFlagsMsg(0)
-}
-
 // KittyKeyboardMsg represents Kitty keyboard progressive enhancement flags message.
 type KittyKeyboardMsg int
 

options.go

@@ -237,11 +237,15 @@
 
 // WithEnhancedKeyboard enables support for enhanced keyboard features. This
 // unambiguously reports more key combinations than traditional terminal
-// keyboard sequences. This will also enable reporting of release key events.
+// keyboard sequences. This might also enable reporting of release key events
+// depending on the terminal emulator supporting it.
 //
-// This is a syntactic sugar for WithKittyKeyboard(3).
+// This is a syntactic sugar for WithKittyKeyboard(3) and WithXtermModifyOtherKeys(1).
 func WithEnhancedKeyboard() ProgramOption {
-	return WithKittyKeyboard(3)
+	return func(p *Program) {
+		WithKittyKeyboard(3)(p)
+		WithModifyOtherKeys(1)(p)
+	}
 }
 
 // WithKittyKeyboard enables support for the Kitty keyboard protocol. This
@@ -264,3 +268,22 @@
 		p.startupOptions |= withKittyKeyboard
 	}
 }
+
+// WithModifyOtherKeys enables support for the XTerm modifyOtherKeys feature.
+// This feature allows the terminal to report ambiguous keys as escape codes.
+// This is useful for terminals that don't support the Kitty keyboard protocol.
+//
+// The mode can be one of the following:
+//
+//	0: Disable modifyOtherKeys
+//	1: Report ambiguous keys as escape codes
+//	2: Report ambiguous keys as escape codes including modified keys like Alt-<key>
+//	   and Meta-<key>
+//
+// See https://invisible-island.net/xterm/manpage/xterm.html#VT100-Widget-Resources:modifyOtherKeys
+func WithModifyOtherKeys(mode int) ProgramOption {
+	return func(p *Program) {
+		p.modifyOtherKeys = mode
+		p.startupOptions |= withModifyOtherKeys
+	}
+}

tea.go

@@ -98,6 +98,7 @@ const (
 	withoutCatchPanics
 	withoutBracketedPaste
 	withKittyKeyboard
+	withModifyOtherKeys
 )
 
 // channelHandlers manages the series of channels returned by various processes.
@@ -177,6 +178,9 @@ type Program struct {
 
 	// kittyFlags stores kitty keyboard protocol progressive enhancement flags.
 	kittyFlags int
+
+	// modifyOtherKeys stores the XTerm modifyOtherKeys mode.
+	modifyOtherKeys int
 }
 
 // Quit is a special command that tells the Bubble Tea program to exit.
@@ -407,6 +411,21 @@ func (p *Program) eventLoop(model Model, cmds chan Cmd) (Model, error) {
 			case kittyKeyboardMsg:
 				p.renderer.execute(ansi.RequestKittyKeyboard)
 
+			case setModifyOtherKeysMsg:
+				p.modifyOtherKeys = int(msg)
+				p.renderer.execute(ansi.ModifyOtherKeys(p.modifyOtherKeys))
+
+			case setEnhancedKeyboardMsg:
+				if bool(msg) {
+					p.kittyFlags = 3
+					p.modifyOtherKeys = 1
+				} else {
+					p.kittyFlags = 0
+					p.modifyOtherKeys = 0
+				}
+				p.renderer.execute(ansi.ModifyOtherKeys(p.modifyOtherKeys))
+				p.renderer.execute(ansi.PushKittyKeyboard(p.kittyFlags))
+
 			case execMsg:
 				// NB: this blocks.
 				p.exec(msg.cmd, msg.fn)
@@ -571,6 +590,9 @@ func (p *Program) Run() (Model, error) {
 		p.renderer.execute(ansi.EnableMouseAllMotion)
 		p.renderer.execute(ansi.EnableMouseSgrExt)
 	}
+	if p.startupOptions&withModifyOtherKeys != 0 {
+		p.renderer.execute(ansi.ModifyOtherKeys(p.modifyOtherKeys))
+	}
 	if p.startupOptions&withKittyKeyboard != 0 {
 		p.renderer.execute(ansi.PushKittyKeyboard(p.kittyFlags))
 	}
@@ -745,6 +767,9 @@ func (p *Program) RestoreTerminal() error {
 		p.renderer.hideCursor()
 		p.renderer.execute(ansi.EnableBracketedPaste)
 		p.bpActive = true
+		if p.modifyOtherKeys != 0 {
+			p.renderer.execute(ansi.ModifyOtherKeys(p.modifyOtherKeys))
+		}
 		if p.kittyFlags != 0 {
 			p.renderer.execute(ansi.PushKittyKeyboard(p.kittyFlags))
 		}

tty.go

@@ -37,6 +37,9 @@ func (p *Program) restoreTerminalState() error {
 		p.bpActive = false
 		p.renderer.showCursor()
 		p.disableMouse()
+		if p.modifyOtherKeys != 0 {
+			p.renderer.execute(ansi.DisableModifyOtherKeys)
+		}
 		if p.kittyFlags != 0 {
 			p.renderer.execute(ansi.DisableKittyKeyboard)
 		}

xterm.go

@@ -4,6 +4,29 @@ import (
 	"github.com/charmbracelet/x/ansi"
 )
 
+// setModifyOtherKeysMsg is a message to set XTerm modifyOtherKeys mode.
+type setModifyOtherKeysMsg int
+
+// EnableXtermModifyOtherKeys is a command to enable XTerm modifyOtherKeys mode.
+//
+// The mode can be on of the following:
+//
+//	1: Report ambiguous keys as escape codes
+//	2: Report ambiguous keys as escape codes including modified keys like Alt-<key>
+//	   and Meta-<key>
+//
+// See https://invisible-island.net/xterm/manpage/xterm.html#VT100-Widget-Resources:modifyOtherKeys
+func EnableModifyOtherKeys(mode int) Cmd {
+	return func() Msg {
+		return setModifyOtherKeysMsg(mode)
+	}
+}
+
+// DisableModifyOtherKeys is a command to disable XTerm modifyOtherKeys mode.
+func DisableModifyOtherKeys() Msg {
+	return setModifyOtherKeysMsg(0)
+}
+
 func parseXTermModifyOtherKeys(csi *ansi.CsiSequence) Msg {
 	// XTerm modify other keys starts with ESC [ 27 ; <modifier> ; <code> ~
 	mod := KeyMod(csi.Param(1) - 1)