(v2) Bubble Tea API

README.md

@@ -69,7 +69,7 @@ import (
     "fmt"
     "os"
 
-    tea "github.com/charmbracelet/bubbletea"
+    tea "github.com/charmbracelet/bubbletea/v2"
 )
 ```
 
@@ -93,34 +93,27 @@ type model struct {
 }
 ```
 
-### Initialization
+## Initialization
 
-Next, we’ll define our application’s initial state. In this case, we’re defining
-a function to return our initial model, however, we could just as easily define
-the initial model as a variable elsewhere, too.
+Next, we’ll define our application’s initial state in the `Init` method. `Init`
+can return a `Cmd` that could perform some initial I/O. For now, we don't need
+to do any I/O, so for the command, we'll just return `nil`, which translates to
+"no command."
 
 ```go
-func initialModel() model {
-	return model{
+func (m model) Init() (tea.Model, tea.Cmd) {
+	m = {
 		// Our to-do list is a grocery list
 		choices:  []string{"Buy carrots", "Buy celery", "Buy kohlrabi"},
 
 		// A map which indicates which choices are selected. We're using
-		// the  map like a mathematical set. The keys refer to the indexes
+		// the map like a mathematical set. The keys refer to the indexes
 		// of the `choices` slice, above.
 		selected: make(map[int]struct{}),
 	}
-}
-```
-
-Next, we define the `Init` method. `Init` can return a `Cmd` that could perform
-some initial I/O. For now, we don't need to do any I/O, so for the command,
-we'll just return `nil`, which translates to "no command."
 
-```go
-func (m model) Init() tea.Cmd {
     // Just return `nil`, which means "no I/O right now, please."
-    return nil
+    return m, nil
 }
 ```
 
@@ -141,15 +134,15 @@ tick, or a response from a server.
 We usually figure out which type of `Msg` we received with a type switch, but
 you could also use a type assertion.
 
-For now, we'll just deal with `tea.KeyMsg` messages, which are automatically
-sent to the update function when keys are pressed.
+For now, we'll just deal with `tea.KeyPressMsg` messages, which are
+automatically sent to the update function when keys are pressed.
 
 ```go
 func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
     switch msg := msg.(type) {
 
     // Is it a key press?
-    case tea.KeyMsg:
+    case tea.KeyPressMsg:
 
         // Cool, what was the actual key pressed?
         switch msg.String() {
@@ -170,9 +163,9 @@ func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
                 m.cursor++
             }
 
-        // The "enter" key and the spacebar (a literal space) toggle
-        // the selected state for the item that the cursor is pointing at.
-        case "enter", " ":
+        // The "enter" key and the space bar (a literal space) toggle the
+        // selected state for the item that the cursor is pointing at.
+        case "enter", "space":
             _, ok := m.selected[m.cursor]
             if ok {
                 delete(m.selected, m.cursor)

clipboard.go

@@ -0,0 +1,69 @@
+package tea
+
+// ClipboardMsg is a clipboard read message event. This message is emitted when
+// a terminal receives an OSC52 clipboard read message event.
+type ClipboardMsg string
+
+// String returns the string representation of the clipboard message.
+func (e ClipboardMsg) String() string {
+	return string(e)
+}
+
+// PrimaryClipboardMsg is a primary clipboard read message event. This message
+// is emitted when a terminal receives an OSC52 primary clipboard read message
+// event. Primary clipboard selection is a feature present in X11 and Wayland
+// only.
+type PrimaryClipboardMsg string
+
+// String returns the string representation of the primary clipboard message.
+func (e PrimaryClipboardMsg) String() string {
+	return string(e)
+}
+
+// setClipboardMsg is an internal message used to set the system clipboard
+// using OSC52.
+type setClipboardMsg string
+
+// SetClipboard produces a command that sets the system clipboard using OSC52.
+// Note that OSC52 is not supported in all terminals.
+func SetClipboard(s string) Cmd {
+	return func() Msg {
+		return setClipboardMsg(s)
+	}
+}
+
+// readClipboardMsg is an internal message used to read the system clipboard
+// using OSC52.
+type readClipboardMsg struct{}
+
+// ReadClipboard produces a command that reads the system clipboard using OSC52.
+// Note that OSC52 is not supported in all terminals.
+func ReadClipboard() Msg {
+	return readClipboardMsg{}
+}
+
+// setPrimaryClipboardMsg is an internal message used to set the primary
+// clipboard using OSC52.
+type setPrimaryClipboardMsg string
+
+// SetPrimaryClipboard produces a command that sets the primary clipboard using
+// OSC52. Primary clipboard selection is a feature present in X11 and Wayland
+// only.
+// Note that OSC52 is not supported in all terminals.
+func SetPrimaryClipboard(s string) Cmd {
+	return func() Msg {
+		return setPrimaryClipboardMsg(s)
+	}
+}
+
+// readPrimaryClipboardMsg is an internal message used to read the primary
+// clipboard using OSC52.
+type readPrimaryClipboardMsg struct{}
+
+// ReadPrimaryClipboard produces a command that reads the primary clipboard
+// using OSC52. Primary clipboard selection is a feature present in X11 and
+// Wayland only.
+// Note that OSC52 is not supported in all terminals.
+func ReadPrimaryClipboard() Msg {
+	return readPrimaryClipboardMsg{}
+}

color.go

@@ -0,0 +1,121 @@
+package tea
+
+import (
+	"image/color"
+
+	"github.com/charmbracelet/x/input"
+)
+
+// backgroundColorMsg is a message that requests the terminal background color.
+type backgroundColorMsg struct{}
+
+// RequestBackgroundColor is a command that requests the terminal background color.
+func RequestBackgroundColor() Msg {
+	return backgroundColorMsg{}
+}
+
+// foregroundColorMsg is a message that requests the terminal foreground color.
+type foregroundColorMsg struct{}
+
+// RequestForegroundColor is a command that requests the terminal foreground color.
+func RequestForegroundColor() Msg {
+	return foregroundColorMsg{}
+}
+
+// cursorColorMsg is a message that requests the terminal cursor color.
+type cursorColorMsg struct{}
+
+// RequestCursorColor is a command that requests the terminal cursor color.
+func RequestCursorColor() Msg {
+	return cursorColorMsg{}
+}
+
+// setBackgroundColorMsg is a message that sets the terminal background color.
+type setBackgroundColorMsg struct{ color.Color }
+
+// SetBackgroundColor is a command that sets the terminal background color.
+func SetBackgroundColor(c color.Color) Cmd {
+	return func() Msg {
+		return setBackgroundColorMsg{c}
+	}
+}
+
+// setForegroundColorMsg is a message that sets the terminal foreground color.
+type setForegroundColorMsg struct{ color.Color }
+
+// SetForegroundColor is a command that sets the terminal foreground color.
+func SetForegroundColor(c color.Color) Cmd {
+	return func() Msg {
+		return setForegroundColorMsg{c}
+	}
+}
+
+// setCursorColorMsg is a message that sets the terminal cursor color.
+type setCursorColorMsg struct{ color.Color }
+
+// SetCursorColor is a command that sets the terminal cursor color.
+func SetCursorColor(c color.Color) Cmd {
+	return func() Msg {
+		return setCursorColorMsg{c}
+	}
+}
+
+// ForegroundColorMsg represents a foreground color message. This message is
+// emitted when the program requests the terminal foreground color with the
+// [RequestForegroundColor] Cmd.
+type ForegroundColorMsg struct{ color.Color }
+
+// String returns the hex representation of the color.
+func (e ForegroundColorMsg) String() string {
+	return input.ForegroundColorEvent(e).String()
+}
+
+// IsDark returns whether the color is dark.
+func (e ForegroundColorMsg) IsDark() bool {
+	return input.ForegroundColorEvent(e).IsDark()
+}
+
+// BackgroundColorMsg represents a background color message. This message is
+// emitted when the program requests the terminal background color with the
+// [RequestBackgroundColor] Cmd.
+//
+// This is commonly used in [Update.Init] to get the terminal background color
+// for style definitions. For that you'll want to call
+// [BackgroundColorMsg.IsDark] to determine if the color is dark or light. For
+// example:
+//
+//	func (m Model) Init() (Model, Cmd) {
+//	  return m, RequestBackgroundColor()
+//	}
+//
+//	func (m Model) Update(msg Msg) (Model, Cmd) {
+//	  switch msg := msg.(type) {
+//	  case BackgroundColorMsg:
+//	      m.styles = newStyles(msg.IsDark())
+//	  }
+//	}
+type BackgroundColorMsg struct{ color.Color }
+
+// String returns the hex representation of the color.
+func (e BackgroundColorMsg) String() string {
+	return input.BackgroundColorEvent(e).String()
+}
+
+// IsDark returns whether the color is dark.
+func (e BackgroundColorMsg) IsDark() bool {
+	return input.BackgroundColorEvent(e).IsDark()
+}
+
+// CursorColorMsg represents a cursor color change message. This message is
+// emitted when the program requests the terminal cursor color.
+type CursorColorMsg struct{ color.Color }
+
+// String returns the hex representation of the color.
+func (e CursorColorMsg) String() string {
+	return input.CursorColorEvent(e).String()
+}
+
+// IsDark returns whether the color is dark.
+func (e CursorColorMsg) IsDark() bool {
+	return input.CursorColorEvent(e).IsDark()
+}

commands.go

@@ -9,8 +9,8 @@ import (
 //
 // Example:
 //
-//	    func (m model) Init() Cmd {
-//		       return tea.Batch(someCommand, someOtherCommand)
+//	    func (m model) Init() (Model, Cmd) {
+//		       return m, tea.Batch(someCommand, someOtherCommand)
 //	    }
 func Batch(cmds ...Cmd) Cmd {
 	var validCmds []Cmd //nolint:prealloc
@@ -78,9 +78,9 @@ type sequenceMsg []Cmd
 //	    })
 //	}
 //
-//	func (m model) Init() Cmd {
+//	func (m model) Init() (Model, Cmd) {
 //	    // Start ticking.
-//	    return tickEvery()
+//	    return m, tickEvery()
 //	}
 //
 //	func (m model) Update(msg Msg) (Model, Cmd) {
@@ -132,9 +132,9 @@ func Every(duration time.Duration, fn func(time.Time) Msg) Cmd {
 //	    })
 //	}
 //
-//	func (m model) Init() Cmd {
+//	func (m model) Init() (Model, Cmd) {
 //	    // Start ticking.
-//	    return doTick()
+//	    return m, doTick()
 //	}
 //
 //	func (m model) Update(msg Msg) (Model, Cmd) {
@@ -157,44 +157,16 @@ func Tick(d time.Duration, fn func(time.Time) Msg) Cmd {
 	}
 }
 
-// Sequentially produces a command that sequentially executes the given
-// commands.
-// The Msg returned is the first non-nil message returned by a Cmd.
-//
-//	func saveStateCmd() Msg {
-//	   if err := save(); err != nil {
-//	       return errMsg{err}
-//	   }
-//	   return nil
-//	}
-//
-//	cmd := Sequentially(saveStateCmd, Quit)
-//
-// Deprecated: use Sequence instead.
-func Sequentially(cmds ...Cmd) Cmd {
-	return func() Msg {
-		for _, cmd := range cmds {
-			if cmd == nil {
-				continue
-			}
-			if msg := cmd(); msg != nil {
-				return msg
-			}
-		}
-		return nil
-	}
-}
-
 // setWindowTitleMsg is an internal message used to set the window title.
 type setWindowTitleMsg string
 
 // SetWindowTitle produces a command that sets the terminal title.
 //
 // For example:
 //
-//	func (m model) Init() Cmd {
+//	func (m model) Init() (Model, Cmd) {
 //	    // Set title.
-//	    return tea.SetWindowTitle("My App")
+//	    return m, tea.SetWindowTitle("My App")
 //	}
 func SetWindowTitle(title string) Cmd {
 	return func() Msg {
@@ -204,12 +176,12 @@ func SetWindowTitle(title string) Cmd {
 
 type windowSizeMsg struct{}
 
-// WindowSize is a command that queries the terminal for its current size. It
-// delivers the results to Update via a [WindowSizeMsg]. Keep in mind that
-// WindowSizeMsgs will automatically be delivered to Update when the [Program]
-// starts and when the window dimensions change so in many cases you will not
-// need to explicitly invoke this command.
-func WindowSize() Cmd {
+// RequestWindowSize is a command that queries the terminal for its current
+// size. It delivers the results to Update via a [WindowSizeMsg]. Keep in mind
+// that WindowSizeMsgs will automatically be delivered to Update when the
+// [Program] starts and when the window dimensions change so in many cases you
+// will not need to explicitly invoke this command.
+func RequestWindowSize() Cmd {
 	return func() Msg {
 		return windowSizeMsg{}
 	}