chore: merge pull request #300 from charmbracelet/x/input2

input: expose reader, parser, and update events

ansi/mouse.go

@@ -4,14 +4,141 @@ import (
 	"fmt"
 )
 
+// MouseButton represents the button that was pressed during a mouse message.
+type MouseButton byte
+
+// Mouse event buttons
+//
+// This is based on X11 mouse button codes.
+//
+//	1 = left button
+//	2 = middle button (pressing the scroll wheel)
+//	3 = right button
+//	4 = turn scroll wheel up
+//	5 = turn scroll wheel down
+//	6 = push scroll wheel left
+//	7 = push scroll wheel right
+//	8 = 4th button (aka browser backward button)
+//	9 = 5th button (aka browser forward button)
+//	10
+//	11
+//
+// Other buttons are not supported.
+const (
+	MouseNone MouseButton = iota
+	MouseLeft
+	MouseMiddle
+	MouseRight
+	MouseWheelUp
+	MouseWheelDown
+	MouseWheelLeft
+	MouseWheelRight
+	MouseBackward
+	MouseForward
+	MouseButton10
+	MouseButton11
+
+	MouseRelease = MouseNone
+)
+
+var mouseButtons = map[MouseButton]string{
+	MouseNone:       "none",
+	MouseLeft:       "left",
+	MouseMiddle:     "middle",
+	MouseRight:      "right",
+	MouseWheelUp:    "wheelup",
+	MouseWheelDown:  "wheeldown",
+	MouseWheelLeft:  "wheelleft",
+	MouseWheelRight: "wheelright",
+	MouseBackward:   "backward",
+	MouseForward:    "forward",
+	MouseButton10:   "button10",
+	MouseButton11:   "button11",
+}
+
+// String returns a string representation of the mouse button.
+func (b MouseButton) String() string {
+	return mouseButtons[b]
+}
+
+// Button returns a byte representing a mouse button.
+// The button is a bitmask of the following leftmost values:
+//
+//   - The first two bits are the button number:
+//     0 = left button, wheel up, or button no. 8 aka (backwards)
+//     1 = middle button, wheel down, or button no. 9 aka (forwards)
+//     2 = right button, wheel left, or button no. 10
+//     3 = release event, wheel right, or button no. 11
+//
+//   - The third bit indicates whether the shift key was pressed.
+//
+//   - The fourth bit indicates the alt key was pressed.
+//
+//   - The fifth bit indicates the control key was pressed.
+//
+//   - The sixth bit indicates motion events. Combined with button number 3, i.e.
+//     release event, it represents a drag event.
+//
+//   - The seventh bit indicates a wheel event.
+//
+//   - The eighth bit indicates additional buttons.
+//
+// If button is [MouseRelease], and motion is false, this returns a release
+// event. If button is undefined, this function returns 0xff.
+func (b MouseButton) Button(motion, shift, alt, ctrl bool) (m byte) {
+	// mouse bit shifts
+	const (
+		bitShift  = 0b0000_0100
+		bitAlt    = 0b0000_1000
+		bitCtrl   = 0b0001_0000
+		bitMotion = 0b0010_0000
+		bitWheel  = 0b0100_0000
+		bitAdd    = 0b1000_0000 // additional buttons 8-11
+
+		bitsMask = 0b0000_0011
+	)
+
+	if b == MouseRelease {
+		m = bitsMask
+	} else if b >= MouseLeft && b <= MouseRight {
+		m = byte(b - MouseLeft)
+	} else if b >= MouseWheelUp && b <= MouseWheelRight {
+		m = byte(b - MouseWheelUp)
+		m |= bitWheel
+	} else if b >= MouseBackward && b <= MouseButton11 {
+		m = byte(b - MouseBackward)
+		m |= bitAdd
+	} else {
+		m = 0xff // invalid button
+	}
+
+	if shift {
+		m |= bitShift
+	}
+	if alt {
+		m |= bitAlt
+	}
+	if ctrl {
+		m |= bitCtrl
+	}
+	if motion {
+		m |= bitMotion
+	}
+
+	return
+}
+
+// x10Offset is the offset for X10 mouse events.
+// See https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#Mouse%20Tracking
+const x10Offset = 32
+
 // MouseX10 returns an escape sequence representing a mouse event in X10 mode.
 // Note that this requires the terminal support X10 mouse modes.
 //
 //	CSI M Cb Cx Cy
 //
 // See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#Mouse%20Tracking
 func MouseX10(b byte, x, y int) string {
-	const x10Offset = 32
 	return "\x1b[M" + string(b+x10Offset) + string(byte(x)+x10Offset+1) + string(byte(y)+x10Offset+1)
 }
 
@@ -22,15 +149,15 @@ func MouseX10(b byte, x, y int) string {
 //
 // See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#Mouse%20Tracking
 func MouseSgr(b byte, x, y int, release bool) string {
-	s := "M"
+	s := 'M'
 	if release {
-		s = "m"
+		s = 'm'
 	}
 	if x < 0 {
 		x = -x
 	}
 	if y < 0 {
 		y = -y
 	}
-	return fmt.Sprintf("\x1b[<%d;%d;%d%s", b, x+1, y+1, s)
+	return fmt.Sprintf("\x1b[<%d;%d;%d%c", b, x+1, y+1, s)
 }

ansi/mouse_test.go

@@ -0,0 +1,237 @@
+package ansi
+
+import (
+	"fmt"
+	"testing"
+)
+
+func TestMouseButton(t *testing.T) {
+	type test struct {
+		name                     string
+		btn                      MouseButton
+		motion, shift, alt, ctrl bool
+		want                     byte
+	}
+
+	cases := []test{
+		{
+			name: "mouse release",
+			btn:  MouseRelease,
+			want: 0b0000_0011,
+		},
+		{
+			name: "mouse left",
+			btn:  MouseLeft,
+			want: 0b0000_0000,
+		},
+		{
+			name: "mouse right",
+			btn:  MouseRight,
+			want: 0b0000_0010,
+		},
+		{
+			name: "mouse wheel up",
+			btn:  MouseWheelUp,
+			want: 0b0100_0000,
+		},
+		{
+			name: "mouse wheel right",
+			btn:  MouseWheelRight,
+			want: 0b0100_0011,
+		},
+		{
+			name: "mouse backward",
+			btn:  MouseBackward,
+			want: 0b1000_0000,
+		},
+		{
+			name: "mouse forward",
+			btn:  MouseForward,
+			want: 0b1000_0001,
+		},
+		{
+			name: "mouse button 10",
+			btn:  MouseButton10,
+			want: 0b1000_0010,
+		},
+		{
+			name: "mouse button 11",
+			btn:  MouseButton11,
+			want: 0b1000_0011,
+		},
+		{
+			name:   "mouse middle with motion",
+			btn:    MouseMiddle,
+			motion: true,
+			want:   0b0010_0001,
+		},
+		{
+			name:  "mouse middle with shift",
+			btn:   MouseMiddle,
+			shift: true,
+			want:  0b0000_0101,
+		},
+		{
+			name:   "mouse middle with motion and alt",
+			btn:    MouseMiddle,
+			motion: true,
+			alt:    true,
+			want:   0b0010_1001,
+		},
+		{
+			name:  "mouse right with shift, alt, and ctrl",
+			btn:   MouseRight,
+			shift: true,
+			alt:   true,
+			ctrl:  true,
+			want:  0b0001_1110,
+		},
+		{
+			name:   "mouse button 10 with motion, shift, alt, and ctrl",
+			btn:    MouseButton10,
+			motion: true,
+			shift:  true,
+			alt:    true,
+			ctrl:   true,
+			want:   0b1011_1110,
+		},
+		{
+			name:   "mouse left with motion, shift, and ctrl",
+			btn:    MouseLeft,
+			motion: true,
+			shift:  true,
+			ctrl:   true,
+			want:   0b0011_0100,
+		},
+		{
+			name: "invalid mouse button",
+			btn:  MouseButton(0xff),
+			want: 0b1111_1111,
+		},
+		{
+			name:   "mouse wheel down with motion",
+			btn:    MouseWheelDown,
+			motion: true,
+			want:   0b0110_0001,
+		},
+		{
+			name:  "mouse wheel down with shift and ctrl",
+			btn:   MouseWheelDown,
+			shift: true,
+			ctrl:  true,
+			want:  0b0101_0101,
+		},
+		{
+			name: "mouse wheel left with alt",
+			btn:  MouseWheelLeft,
+			alt:  true,
+			want: 0b0100_1010,
+		},
+		{
+			name:   "mouse middle with all modifiers",
+			btn:    MouseMiddle,
+			motion: true,
+			shift:  true,
+			alt:    true,
+			ctrl:   true,
+			want:   0b0011_1101,
+		},
+	}
+
+	for i, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := tc.btn.Button(tc.motion, tc.shift, tc.alt, tc.ctrl)
+			if got != tc.want {
+				t.Errorf("test %d: got %08b; want %08b", i+1, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestMouseSgr(t *testing.T) {
+	type test struct {
+		name    string
+		btn     byte
+		x, y    int
+		release bool
+	}
+
+	cases := []test{
+		{
+			name: "mouse left",
+			btn:  MouseLeft.Button(false, false, false, false),
+			x:    0,
+			y:    0,
+		},
+		{
+			name: "wheel down",
+			btn:  MouseWheelDown.Button(false, false, false, false),
+			x:    1,
+			y:    10,
+		},
+		{
+			name: "mouse right with shift, alt, and ctrl",
+			btn:  MouseRight.Button(false, true, true, true),
+			x:    10,
+			y:    1,
+		},
+		{
+			name:    "mouse release",
+			btn:     MouseRelease.Button(false, false, false, false),
+			x:       5,
+			y:       5,
+			release: true,
+		},
+		{
+			name: "mouse button 10 with motion, shift, alt, and ctrl",
+			btn:  MouseButton10.Button(true, true, true, true),
+			x:    10,
+			y:    10,
+		},
+		{
+			name: "mouse wheel up with motion",
+			btn:  MouseWheelUp.Button(true, false, false, false),
+			x:    15,
+			y:    15,
+		},
+		{
+			name: "mouse middle with all modifiers",
+			btn:  MouseMiddle.Button(true, true, true, true),
+			x:    20,
+			y:    20,
+		},
+		{
+			name: "mouse wheel left at max coordinates",
+			btn:  MouseWheelLeft.Button(false, false, false, false),
+			x:    223,
+			y:    223,
+		},
+		{
+			name:    "mouse forward release",
+			btn:     MouseForward.Button(false, false, false, false),
+			x:       100,
+			y:       100,
+			release: true,
+		},
+		{
+			name: "mouse backward with shift and ctrl",
+			btn:  MouseBackward.Button(false, true, false, true),
+			x:    50,
+			y:    50,
+		},
+	}
+
+	for i, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			m := MouseSgr(tc.btn, tc.x, tc.y, tc.release)
+			action := 'M'
+			if tc.release {
+				action = 'm'
+			}
+			want := fmt.Sprintf("\x1b[<%d;%d;%d%c", tc.btn, tc.x+1, tc.y+1, action)
+			if m != want {
+				t.Errorf("test %d: got %q; want %q", i+1, m, want)
+			}
+		})
+	}
+}