feat: add kitty keyboard options and settings

This adds the necessary options to enable/disable the kitty keyboard
protocol.

Needs: #1080
Fixes: #869

go.mod

@@ -3,7 +3,7 @@ module github.com/charmbracelet/bubbletea
 go 1.18
 
 require (
-	github.com/charmbracelet/x/ansi v0.1.4
+	github.com/charmbracelet/x/ansi v0.1.5-0.20240814155920-d72bfb0444d7
 	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

go.sum

@@ -1,5 +1,9 @@
 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/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=

kitty.go

@@ -7,6 +7,47 @@ import (
 	"github.com/charmbracelet/x/ansi"
 )
 
+// setKittyKeyboardFlagsMsg is a message to set Kitty keyboard progressive
+// enhancement protocol flags.
+type setKittyKeyboardFlagsMsg int
+
+// EnableKittyKeyboard is a command to enable Kitty keyboard progressive
+// enhancement protocol.
+//
+// The flags parameter is a bitmask of the following
+//
+//	0:  Disable all features
+//	1:  Disambiguate escape codes
+//	2:  Report event types
+//	4:  Report alternate keys
+//	8:  Report all keys as escape codes
+//	16: Report associated text
+//
+// See https://sw.kovidgoyal.net/kitty/keyboard-protocol/ for more information.
+func EnableKittyKeyboard(flags int) Cmd {
+	return func() Msg {
+		return setKittyKeyboardFlagsMsg(flags)
+	}
+}
+
+// DisableKittyKeyboard is a command to disable Kitty keyboard progressive
+// enhancement protocol.
+func DisableKittyKeyboard() Msg {
+	return setKittyKeyboardFlagsMsg(0)
+}
+
+// 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

@@ -234,3 +234,33 @@ func WithFPS(fps int) ProgramOption {
 		p.fps = fps
 	}
 }
+
+// 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.
+//
+// This is a syntactic sugar for WithKittyKeyboard(3).
+func WithEnhancedKeyboard() ProgramOption {
+	return WithKittyKeyboard(3)
+}
+
+// WithKittyKeyboard enables support for the Kitty keyboard protocol. This
+// protocol enables more key combinations and events than the traditional
+// ambiguous terminal keyboard sequences.
+//
+// Use flags to specify which features you want to enable.
+//
+//	0:  Disable all features
+//	1:  Disambiguate escape codes
+//	2:  Report event types
+//	4:  Report alternate keys
+//	8:  Report all keys as escape codes
+//	16: Report associated text
+//
+// See https://sw.kovidgoyal.net/kitty/keyboard-protocol/ for more information.
+func WithKittyKeyboard(flags int) ProgramOption {
+	return func(p *Program) {
+		p.kittyFlags = flags
+		p.startupOptions |= withKittyKeyboard
+	}
+}

tea.go

@@ -97,6 +97,7 @@ const (
 	// feature is on by default.
 	withoutCatchPanics
 	withoutBracketedPaste
+	withKittyKeyboard
 )
 
 // channelHandlers manages the series of channels returned by various processes.
@@ -173,6 +174,9 @@ type Program struct {
 	// fps is the frames per second we should set on the renderer, if
 	// applicable,
 	fps int
+
+	// kittyFlags stores kitty keyboard protocol progressive enhancement flags.
+	kittyFlags int
 }
 
 // Quit is a special command that tells the Bubble Tea program to exit.
@@ -392,6 +396,10 @@ func (p *Program) eventLoop(model Model, cmds chan Cmd) (Model, error) {
 				p.renderer.execute(ansi.DisableBracketedPaste)
 				p.bpActive = false
 
+			case setKittyKeyboardFlagsMsg:
+				p.kittyFlags = int(msg)
+				p.renderer.execute(ansi.PushKittyKeyboard(p.kittyFlags))
+
 			case execMsg:
 				// NB: this blocks.
 				p.exec(msg.cmd, msg.fn)
@@ -556,6 +564,9 @@ func (p *Program) Run() (Model, error) {
 		p.renderer.execute(ansi.EnableMouseAllMotion)
 		p.renderer.execute(ansi.EnableMouseSgrExt)
 	}
+	if p.startupOptions&withKittyKeyboard != 0 {
+		p.renderer.execute(ansi.PushKittyKeyboard(p.kittyFlags))
+	}
 
 	// Start the renderer.
 	p.renderer.start()
@@ -727,6 +738,9 @@ func (p *Program) RestoreTerminal() error {
 		p.renderer.hideCursor()
 		p.renderer.execute(ansi.EnableBracketedPaste)
 		p.bpActive = true
+		if p.kittyFlags != 0 {
+			p.renderer.execute(ansi.PushKittyKeyboard(p.kittyFlags))
+		}
 	}
 
 	// If the output is a terminal, it may have been resized while another

tty.go

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