feat: allow to suspend bubbletea programs

closes #497
closes #1053

exec.go

@@ -98,6 +98,17 @@ func (c *osExecCommand) SetStderr(w io.Writer) {
 	}
 }
 
+func (p *Program) suspend() {
+	if err := p.ReleaseTerminal(); err != nil {
+		// If we can't release input, abort.
+		return
+	}
+
+	suspendProcess()
+
+	_ = p.RestoreTerminal()
+}
+
 // exec runs an ExecCommand and delivers the results to the program as a Msg.
 func (p *Program) exec(c ExecCommand, fn ExecCallback) {
 	if err := p.ReleaseTerminal(); err != nil {

tea.go

@@ -177,10 +177,22 @@ func Quit() Msg {
 	return QuitMsg{}
 }
 
+// Quit is a special command that tells the Bubble Tea program to suspend.
+func Suspend() Msg {
+	return SuspendMsg{}
+}
+
 // QuitMsg signals that the program should quit. You can send a QuitMsg with
 // Quit.
 type QuitMsg struct{}
 
+// SuspendMsg signals the program should suspend.
+// This usually happens when ctrl+z is pressed on common programs, but since
+// bubbletea puts the terminal in raw mode, we need to handle it in a
+// per-program basis.
+// You can send this message with Suspend.
+type SuspendMsg struct{}
+
 // NewProgram creates a new Program.
 func NewProgram(model Model, opts ...ProgramOption) *Program {
 	p := &Program{
@@ -327,6 +339,11 @@ func (p *Program) eventLoop(model Model, cmds chan Cmd) (Model, error) {
 			case QuitMsg:
 				return model, nil
 
+			case SuspendMsg:
+				if suspendSupported {
+					p.suspend()
+				}
+
 			case clearScreenMsg:
 				p.renderer.clearScreen()
 

tty_unix.go

@@ -6,6 +6,7 @@ package tea
 import (
 	"fmt"
 	"os"
+	"syscall"
 
 	"github.com/charmbracelet/x/term"
 )
@@ -34,3 +35,10 @@ func openInputTTY() (*os.File, error) {
 	}
 	return f, nil
 }
+
+var suspendSupported = true
+
+// Send SIGTSTP to the entire process group.
+func suspendProcess() {
+	_ = syscall.Kill(0, syscall.SIGTSTP)
+}

tty_windows.go

@@ -62,3 +62,7 @@ func openInputTTY() (*os.File, error) {
 	}
 	return f, nil
 }
+
+var suspendSupported = false
+
+func suspendProcess() {}