chore: use verbs in background, foreground, and window request cmd na…

…mes (#1205)

* chore: use verbs in background, foreground, and window request cmd names

This renames a few existing commands to make it clearer that the user is
firing off a task.

* WindowSize -> RequestWindowSize
* ForegroundColor -> RequestForegroundColor
* BackgroundColor -> RequestBackgroundColor

It also expands on a few comments, and provides examples.

* fix: screen tests

* fix(examples): use RequestWindowSize instead of WindowSize

---------

Co-authored-by: Ayman Bagabas <[email protected]>

color.go

@@ -11,24 +11,24 @@ import (
 // backgroundColorMsg is a message that requests the terminal background color.
 type backgroundColorMsg struct{}
 
-// BackgroundColor is a command that requests the terminal background color.
-func BackgroundColor() Msg {
+// 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{}
 
-// ForegroundColor is a command that requests the terminal foreground color.
-func ForegroundColor() Msg {
+// 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{}
 
-// CursorColor is a command that requests the terminal cursor color.
-func CursorColor() Msg {
+// RequestCursorColor is a command that requests the terminal cursor color.
+func RequestCursorColor() Msg {
 	return cursorColorMsg{}
 }
 
@@ -62,9 +62,9 @@ func SetCursorColor(c color.Color) Cmd {
 	}
 }
 
-// ForegroundColorMsg represents a foreground color message.
-// This message is emitted when the program requests the terminal foreground
-// color.
+// 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.
@@ -77,9 +77,25 @@ func (e ForegroundColorMsg) IsDark() bool {
 	return isDarkColor(e.Color)
 }
 
-// BackgroundColorMsg represents a background color message.
-// This message is emitted when the program requests the terminal background
-// color.
+// 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.
@@ -92,8 +108,8 @@ func (e BackgroundColorMsg) IsDark() bool {
 	return isDarkColor(e.Color)
 }
 
-// CursorColorMsg represents a cursor color change message.
-// This message is emitted when the program requests the terminal cursor color.
+// 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.

commands.go

@@ -176,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{}
 	}

examples/window-size/main.go

@@ -28,7 +28,7 @@ func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			return m, tea.Quit
 		}
 
-		return m, tea.WindowSize()
+		return m, tea.RequestWindowSize()
 
 	case tea.WindowSizeMsg:
 		return m, tea.Printf("%dx%d", msg.Width, msg.Height)

screen_test.go

@@ -66,7 +66,7 @@ func TestClearMsg(t *testing.T) {
 		},
 		{
 			name:     "bg_fg_cur_color",
-			cmds:     []Cmd{ForegroundColor, BackgroundColor, CursorColor},
+			cmds:     []Cmd{RequestForegroundColor, RequestBackgroundColor, RequestCursorColor},
 			expected: "\x1b[?25l\x1b[?2004h\x1b]10;?\a\x1b]11;?\a\x1b]12;?\a\rsuccess\r\n\x1b[D\x1b[2K\r\x1b[?2004l\x1b[?25h",
 		},
 		{