Another one! Bubble Tea Beta 3!

This is a fairly small update that makes key enhancements support even better. Let's get into it.

go get github.com/charmbracelet/bubbletea/v2@v2.0.0-beta.3

Keys

Better Keys by Default

Key disambiguation is now enabled by default, when supported. This means that ctrl+i, which would normally send a tab will now send an actual ctrl+i in supporting terminals. To check for support listen for tea.KeyboardEnhancementsMsg in your update:

switch msg := msg.(type) {
case tea.KeyboardEnhancementsMsg:
    if msg.SupportsKeyDisambiguation() {
           // Yay!
    }
}

Note that on Windows key disambiguation is always supported.

Does the terminal support key disambigation?

While we suggest designing your application in a way that gracefully upgrades when key disambiguation is available, you could detect for lack of support with a simple timeout:

// queryTimeoutMsg is a message that will get sent after a certain timeout.
type queryTimeoutMsg struct{}

// queryTimeout is a Bubble Tea command that waits for a timeout before sending a [queryTimeoutMsg].
func queryTimeout(d time.Duration) tea.Msg {
  time.Sleep(200*time.Millisecond) // 200 ms is purly arbitrary
  return queryTimeoutMsg{}
}

func (m model) Init() tea.Cmd {
  return tea.Batch(
    tea.RequestKeyboardEnhancements(),
    queryTimout,
  )
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
  switch msg := msg.(type) {
  case tea.KeyboardEnhancementsMsg:
    // We have more keys, heh
    m.hasEnhancements = true
  case queryTimeoutMsg:
    if !m.hasEnhancements {
      // Terminal doesn't support keyboard enhancements :'(
      m.quit = true
    }
  }
}

Changelog

Bug fixes

• 0ed7727: fix(examples): we don't need to wait for background color query (#1407) (@aymanbagabas)
• 825e109: fix: always enable basic keyboard enhancements to disambiguate keys (@aymanbagabas)
• 07fa6f6: fix: don't send keyboard enhancements message on startup (@aymanbagabas)
• cb090c0: fix: lint: use isWindows() helper function (@aymanbagabas)
• 7aa6fec: fix: only request default key enhancements on non-windows platforms (@aymanbagabas)

Thoughts? Questions? We love hearing from you. Feel free to reach out on Twitter, The Fediverse, or on Discord.

Extra! Extra! Bubble Tea Beta 2!

We're honing in on v2! This update is fairly minor and makes some adjustments based on the awesome community feedback we've received. Let’s jump into it.

go get github.com/charmbracelet/bubbletea/v2@v2.0.0-beta.2

Keys

Easier Mappings

Thanks to some feedback from our beta users (thank you! ❤️), key events now always return the textual value when using key.String(). You can use key.Keystroke() to get the keystroke string representation of the event. For example, pressing shift+h would give you k.String() == "H" and k.Keystroke() == "shift+h" when keyboard enhancements is on. We believe this will make input handling closer to the good parts of v1 and avoid some gotchas with international keyboards.

// Imagine the user pressed shift+h and key is a KeyMsg
key.String () == "H"
key.Keytroke() == "shift+h"

// Now imagine the user entered a "?"
key.String() == "?"
key.Keytroke() == "shift+/ on an American keyboard, shift+, on a French keyboard"

Other Stuff

• We reverted the new trailing newline character on program exit. We found that while it's a nice touch that simplifies many programs, it can cause issues for others. This brings rendering in-line with v1, so there will be no action needed migrating from v1
• Fix concurrency and add deadlock prevention (courtesy @desertwitch)
• Fixed some examples

Thanks again to @desertwitch for his amazing work on concurrency and deadlock prevention 🤘

Changelog

New Features

• 60b6f30: feat: add keystroke representation to Key struct (#1399) (@aymanbagabas)

Bug fixes

• 929ff5a: Revert "fix: ensure terminal prompt is on a new line after program shutdown" (@aymanbagabas)
• f4c8567: fix(examples): credit-card-form: use VirtualCursor in inputs (@aymanbagabas)
• 551bf9c: fix(examples): textarea: remove debug log (@aymanbagabas)
• 62ca063: fix(key): windows: recognize function keys on Windows (#1405) (@aymanbagabas)
• 0f9cd5b: fix(panics): fix race condition and false nil error return (@desertwitch)
• a79ab3f: fix(tests): account for multiple p.Wait() (@desertwitch)
• ed4fde7: fix: lint issues (@caarlos0)
• 1b5fc27: fix: prevent deadlock on ctx cancel during msg processing (@desertwitch)
• aa7a240: fix: release p.Wait() on p.Kill() to prevent external deadlocks (@desertwitch)
• 1923181: fix: report only external ctx cancel as ctx error (@desertwitch)
• c56f776: fix: resolve race conditions caused by p.Kill() (@desertwitch)
• d67e48a: fix: windows: remove broken key_windows.go (@aymanbagabas)

Documentation updates

• 5eee00a: docs(examples): add keyboard enhancements demo (@meowgorithm)
• 35334b9: docs(examples): remove extraneous lines in query-term example (@meowgorithm)
• 3797acb: docs(readme): fix header image mis-caching (@meowgorithm)
• 4e7ab6c: docs(viewport): update for viewport left gutter API changes (@meowgorithm)

Other work

• 7858a14: ci: fix lint issues (@andreynering)
• 1a0062b: ci: fix lint issues (@andreynering)
• 0b18d1f: ci: sync dependabot config (#1403) (@charmcli)
• a46d16d: ci: sync golangci-lint config (#1379) (@github-actions[bot])
• 5a360c9: ci: sync golangci-lint config (#1394) (@github-actions[bot])
• bf33130: refactor(examples): use glamour/v2 (@aymanbagabas)

Thoughts? Questions? We love hearing from you. Feel free to reach out on Twitter, The Fediverse, or on Discord.

This release fixes an important bug on Windows where function keys (F1..F20) don't get recognized and sent to the program. It also fixes multiple concurrency bugs related to using external context and p.Wait() and p.Kill().

Also, huge thank you to @desertwitch who went in and just crushed a handful of deadlocks.

Happy hacking!

Changelog

Bug fixes

• 62ca063: fix(key): windows: recognize function keys on Windows (#1405) (@aymanbagabas)
• 0f9cd5b: fix(panics): fix race condition and false nil error return (@desertwitch)
• a79ab3f: fix(tests): account for multiple p.Wait() (@desertwitch)
• 1b5fc27: fix: prevent deadlock on ctx cancel during msg processing (@desertwitch)
• aa7a240: fix: release p.Wait() on p.Kill() to prevent external deadlocks (@desertwitch)
• 1923181: fix: report only external ctx cancel as ctx error (@desertwitch)
• c56f776: fix: resolve race conditions caused by p.Kill() (@desertwitch)

Documentation updates

• 3797acb: docs(readme): fix header image mis-caching (@meowgorithm)
• 8508131: docs(readme): header art adjustments (@meowgorithm)
• b3150e1: docs(readme): update header art (@meowgorithm)

Other work

• b224818: ci(lint): fix all lint issues on main (#1342) (@andreynering)
• 1a0062b: ci: fix lint issues (@andreynering)
• d0c4b65: ci: fix linting on windows-only files (#1361) (@andreynering)
• 0b18d1f: ci: sync dependabot config (#1403) (@charmcli)
• 0e49efb: ci: sync golangci-lint config (#1354) (@github-actions[bot])
• a46d16d: ci: sync golangci-lint config (#1379) (@github-actions[bot])
• 5a360c9: ci: sync golangci-lint config (#1394) (@github-actions[bot])

Thoughts? Questions? We love hearing from you. Feel free to reach out on Twitter, The Fediverse, or on Discord.

It’s time for Bubble Tea v2 Beta

We're very excited to announce the first beta release of Bubble Tea v2! This release includes a number of improvements and features over the last alpha 2 release.

🍔 New to v2? Looking to upgrade? Check out the full Bubble Tea v2 guide.

Changes Since Alpha 2

Since the last alpha 2 release, we've made a few changes and added some new features. Including restoring old Init behavior, actual cursor support, and some minor API name changes.

Init and Model Changes

We restored the old tea.Model interface and Init method changes. Now, Init returns a tea.Cmd as what it was before. The thought here is that it's more ergonomic and returning a tea.Model doesn't make much sense because during Init you already have a newly created model.

type Model struct
	// My model fields
}

func newModel() Model {
	return Model{
		// Initialize your model here
	}
}

// Before in alpha 2
func (m Model) Init() (tea.Model, tea.Cmd) {
	// But we already have a model, so why return a new one?
	return m, nil
}

// After in beta 1
func (m Model) Init() tea.Cmd {
	// Same as original Bubble Tea
	return nil
}

Cursor Support and View Interfaces

Yes, finally, you can control the cursor! We've added a new tea.CursorView interface that you can implement to control the cursor position and style. This is a long-awaited feature, and we're excited to see what you do with it.

Originally, tea.Model implemented a View method that returned a string. We changed this to be in its own tea.ViewModel interface and took it out of tea.Model. Now tea.Model only has Update and Init methods. Not implementing a View method is equivalent to disabling rendering. Both new interfaces are optional. The difference is that tea.CursorModel returns a tea.Cursor along with a string to control the cursor.

// Before
func (m Model) View() string {
	// How can I move the cursor?
	return "My awesome program! █" // <- fake cursor 😛
}

// After
func (m Model) View() (string, *tea.Cursor) {
	var c *tea.Cursor
	// Nil cursor means a hidden cursor
	if m.showCursor {
		// Move the cursor to the 21nd column right after the text
		c := tea.NewCursor(20, 0) // X: 20, Y: 0
		c.Style = tea.CursorBlock // 😎
		c.Blink = false
	}
	return "My awesome program!", c
}

Enhanced Keyboard Support

Terminologies matter. Previously, we introduced tea.EnableKeyboardEnhancements to request different keyboard enhancement features. We've renamed this to tea.RequestKeyboardEnhancement to signal that the program is requesting keyboard enhancements from the terminal and the terminal may or may not support them.

// Before in alpha 2
func (m Model) Init() (tea.Model, tea.Cmd) {
	return m, tea.EnableKeyboardEnhancements(
		tea.WithKeyReleases,
		tea.WithUniformKeyLayout,
	)
}

// After in beta 1
func (m Model) Init() tea.Cmd {
	return tea.RequestKeyboardEnhancement(
		tea.WithKeyReleases,
		tea.WithUniformKeyLayout,
	)
}

Like details?

Here’s the full changelog since v2.0.0-alpha.2

🌈 Feedback

Have thoughts on Bubble Tea v2 Alpha? We’d love to hear about it. Let us know on…

• Discord
• Matrix
• Email

Part of Charm.

Charm热爱开源 • Charm loves open source • نحنُ نحب المصادر المفتوحة.

This release fixes an issue on Windows where the mouse is always enabled even if it wasn't requested. Now, using mouse options such as tea.WithAllMouseMotion() and commands such as tea.EnableMouseAllMotion and tea.DisableMouse turns the mouse on/off as expected.

Changelog

New Features

• e817654: feat(ci): move from goveralls to codecov (#1332) (@aymanbagabas)

Bug fixes

• bf1216d: fix: windows: enable mouse mode on demand (#1340) (@aymanbagabas)

Other work

• 00e3ef4: ci: sync dependabot config (#1328) (@charmcli)
• 4a30f3f: ci: sync dependabot config (#1329) (@charmcli)

Thoughts? Questions? We love hearing from you. Feel free to reach out on Twitter, The Fediverse, or on Discord.

This release restore the program options that were deprecated in the previous releases.

Changelog

Full Changelog: v1.3.2...v1.3.3

Thoughts? Questions? We love hearing from you. Feel free to reach out on Twitter, The Fediverse, or on Discord.

Fix canceling terminal input reads on Windows.

Changelog

Bug fixes

• b0186ad: fix: windows: handle cancel io error (@aymanbagabas)

Thoughts? Questions? We love hearing from you. Feel free to reach out on Twitter, The Fediverse, or on Discord.

This release introduces some important bug fixes when it comes to cursor movements while rendering, and properly handle Windows AltGr key on non-English keyboards.

Changelog

Bug fixes

• 771a101: fix: renderer: use newline instead of cud1 to move cursor down (#1323) (@aymanbagabas)
• c66daf9: fix: windows: AltGr maps to LEFT_CTRL+RIGHT_ALT (#1162) (@aymanbagabas)

Other work

• 439398b: Remove irrelevant option comments (@nervo)

Thoughts? Questions? We love hearing from you. Feel free to reach out on Twitter, The Fediverse, or on Discord.

Sorry to interrupt: it's time for Bubble Tea v1.3.0!

Bubble Tea now ships with refined interrupt handling, courtesy @caarlos0. Now, you can throw your terminal a ctrl+c or an interrupt signal, Bubble Tea will take it with grace and poise. Switch any ol’ run-of-the-mill tea.Quit command with tea.Interrupt for seamless interruptions.

Bug Fixes

• 2556e01: The last rendered line count now includes those sneaky alt screen lines, thanks to @semihbkgr's keen eye (#1254)
• c8d6005: Windows users rejoice! @awoodbeck has managed to cancel those unruly threads like an expert party planner using CancelIoEx (#1305)

New Contributors

Special thanks to the following new contributors:

• @awoodbeck, for totally fixing input on Windows
• @Bilogweb3, for help with the docs
• @simonnordberg, for catching some outdated typos

Thoughts? Questions? We love hearing from you. Feel free to reach out on Twitter, The Fediverse, or on Discord.

A few little rendering fixes

This release fixes a couple rendering bugs. Quality rendering in Bubble Tea is paramount!

Changelog

Bug fixes

• 4ad0792: fix: cursor position adjustment after exiting alt screen (#1241) (@semihbkgr)
• ede8caa: fix: renderer: keep a separate count of lines rendered in the alt screen (@aymanbagabas)

Other work

• 76b0f81: ci: fix goreleaser config (#1238) (@caarlos0)

Thoughts? Questions? We love hearing from you. Feel free to reach out on Twitter, The Fediverse, or on Discord.