Fix typo in README

When model.HideFor or model.MinimumLifetime is present, we won't draw
the spinner in cases where model.Visibe() returns false.

README.md

@@ -1,6 +1,10 @@
 Bubbles
 =======
 
+<p>
+  <img src="https://stuff.charm.sh/bubbles/bubbles-github.png" width="233" alt="The Bubbles Logo">
+</p>
+
 [![Latest Release](https://img.shields.io/github/release/charmbracelet/bubbles.svg)](https://github.com/charmbracelet/bubbles/releases)
 [![GoDoc](https://godoc.org/github.com/golang/gddo?status.svg)](https://pkg.go.dev/github.com/charmbracelet/bubbles)
 [![Build Status](https://github.com/charmbracelet/bubbles/workflows/build/badge.svg)](https://github.com/charmbracelet/bubbles/actions)
@@ -36,6 +40,17 @@ the common, and many customization options.
 * [Example code, many fields](https://github.com/charmbracelet/tea/tree/master/examples/textinputs/main.go)
 
 
+## Progress
+
+<img src="https://stuff.charm.sh/bubbles-examples/progress.gif" width="800" alt="Progressbar Example">
+
+A simple, customizable progress meter. Supports solid and gradient fills. The
+empty and filled runes can be set to whatever you'd like. The percentage readout
+is customizable and can also be omitted entirely.
+
+* [Example code](https://github.com/charmbracelet/bubbletea/blob/master/examples/progress/main.go)
+
+
 ## Paginator
 
 <img src="https://stuff.charm.sh/bubbles-examples/pagination.gif" width="200" alt="Paginator Example">
@@ -55,7 +70,7 @@ browse SSH keys.
 
 A viewport for vertically scrolling content. Optionally includes standard
 pager keybindings and mouse wheel support. A high performance mode is available
-for applications which make use of the alterate screen buffer.
+for applications which make use of the alternate screen buffer.
 
 * [Example code](https://github.com/charmbracelet/tea/tree/master/examples/pager/main.go)
 
@@ -74,7 +89,6 @@ indenting and text wrapping.
 
 Part of [Charm](https://charm.sh).
 
-<a href="https://charm.sh/"><img alt="the Charm logo" src="https://stuff.charm.sh/charm-badge.jpg" width="400"></a>
+<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge-unrounded.jpg" width="400"></a>
 
 Charm热爱开源! / Charm loves open source!
-

go.mod

@@ -5,7 +5,9 @@ go 1.13
 require (
 	github.com/atotto/clipboard v0.1.2
 	github.com/charmbracelet/bubbletea v0.12.2
+	github.com/lucasb-eyer/go-colorful v1.0.3
 	github.com/mattn/go-runewidth v0.0.9
+	github.com/muesli/reflow v0.2.0
 	github.com/muesli/termenv v0.7.4
 	golang.org/x/crypto v0.0.0-20201016220609-9e8e0b390897 // indirect
 	golang.org/x/sys v0.0.0-20201020230747-6e5568b54d1a // indirect

go.sum

@@ -12,6 +12,8 @@ github.com/mattn/go-isatty v0.0.12 h1:wuysRhFDzyxgEmMf5xjvJ2M9dZoWAXNNr5LSBS7uHX
 github.com/mattn/go-isatty v0.0.12/go.mod h1:cbi8OIDigv2wuxKPP5vlRcQ1OAZbq2CE4Kysco4FUpU=
 github.com/mattn/go-runewidth v0.0.9 h1:Lm995f3rfxdpd6TSmuVCHVb/QhupuXlYr8sCI/QdE+0=
 github.com/mattn/go-runewidth v0.0.9/go.mod h1:H031xJmbD/WCDINGzjvQ9THkh0rPKHF+m2gUSrubnMI=
+github.com/muesli/reflow v0.2.0 h1:2o0UBJPHHH4fa2GCXU4Rg4DwOtWPMekCeyc5EWbAQp0=
+github.com/muesli/reflow v0.2.0/go.mod h1:qT22vjVmM9MIUeLgsVYe/Ye7eZlbv9dZjL3dVhUqLX8=
 github.com/muesli/termenv v0.7.2 h1:r1raklL3uKE7rOvWgSenmEm2px+dnc33OTisZ8YR1fw=
 github.com/muesli/termenv v0.7.2/go.mod h1:ct2L5N2lmix82RaY3bMWwVu/jUFc9Ule0KGDCiKYPh8=
 github.com/muesli/termenv v0.7.4 h1:/pBqvU5CpkY53tU0vVn+xgs2ZTX63aH5nY+SSps5Xa8=

progress/progress.go

@@ -0,0 +1,192 @@
+package progress
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/lucasb-eyer/go-colorful"
+	"github.com/muesli/reflow/ansi"
+	"github.com/muesli/termenv"
+)
+
+const defaultWidth = 40
+
+var color func(string) termenv.Color = termenv.ColorProfile().Color
+
+// Option is used to set options in NewModel. For example:
+//
+//     progress := NewModel(
+//	       WithRamp("#ff0000", "#0000ff"),
+//	       WithoutPercentage(),
+//     )
+type Option func(*Model) error
+
+// WithDefaultGradient sets a gradient fill with default colors.
+func WithDefaultGradient() Option {
+	return WithGradient("#5A56E0", "#EE6FF8")
+}
+
+// WithGradient sets a gradient fill blending between two colors.
+func WithGradient(colorA, colorB string) Option {
+	return func(m *Model) error {
+		return m.setRamp(colorA, colorB, false)
+	}
+}
+
+// WithDefaultScaledGradient sets a gradient with default colors, and scales the
+// gradient to fit the filled portion of the ramp.
+func WithDefaultScaledGradient() Option {
+	return WithScaledGradient("#5A56E0", "#EE6FF8")
+}
+
+// WithScaledGradient scales the gradient to fit the width of the filled portion of
+// the progress bar.
+func WithScaledGradient(colorA, colorB string) Option {
+	return func(m *Model) error {
+		return m.setRamp(colorA, colorB, true)
+	}
+}
+
+// WithSolidFill sets the progress to use a solid fill with the given color.
+func WithSolidFill(color string) Option {
+	return func(m *Model) error {
+		m.FullColor = color
+		m.useRamp = false
+		return nil
+	}
+}
+
+// WithoutPercentage hides the numeric percentage.
+func WithoutPercentage() Option {
+	return func(m *Model) error {
+		m.ShowPercentage = false
+		return nil
+	}
+}
+
+// WithWidth sets the initial width of the progress bar. Note that you can also
+// set the width via the Width property, which can come in handy if you're
+// waiting for a tea.WindowSizeMsg.
+func WithWidth(w int) Option {
+	return func(m *Model) error {
+		m.Width = w
+		return nil
+	}
+}
+
+// Model stores values we'll use when rendering the progress bar.
+type Model struct {
+
+	// Total width of the progress bar, including percentage, if set.
+	Width int
+
+	// "Filled" sections of the progress bar
+	Full      rune
+	FullColor string
+
+	// "Empty" sections of progress bar
+	Empty      rune
+	EmptyColor string
+
+	// Settings for rendering the numeric percentage
+	ShowPercentage  bool
+	PercentFormat   string // a fmt string for a float
+	PercentageStyle *termenv.Style
+
+	useRamp    bool
+	rampColorA colorful.Color
+	rampColorB colorful.Color
+
+	// When true, we scale the gradient to fit the width of the filled section
+	// of the progress bar. When false, the width of the gradient will be set
+	// to the full width of the progress bar.
+	scaleRamp bool
+}
+
+// NewModel returns a model with default values.
+func NewModel(opts ...Option) (*Model, error) {
+	m := &Model{
+		Width:          defaultWidth,
+		Full:           '█',
+		FullColor:      "#7571F9",
+		Empty:          '░',
+		EmptyColor:     "#606060",
+		ShowPercentage: true,
+		PercentFormat:  " %3.0f%%",
+	}
+
+	for _, opt := range opts {
+		if err := opt(m); err != nil {
+			return nil, err
+		}
+	}
+
+	return m, nil
+}
+
+// View renders the progress bar as a given percentage.
+func (m Model) View(percent float64) string {
+	b := strings.Builder{}
+	if m.ShowPercentage {
+		percentage := fmt.Sprintf(m.PercentFormat, percent*100)
+		if m.PercentageStyle != nil {
+			percentage = m.PercentageStyle.Styled(percentage)
+		}
+		m.bar(&b, percent, ansi.PrintableRuneWidth(percentage))
+		b.WriteString(percentage)
+	} else {
+		m.bar(&b, percent, 0)
+	}
+	return b.String()
+}
+
+func (m Model) bar(b *strings.Builder, percent float64, textWidth int) {
+	var (
+		tw = m.Width - textWidth        // total width
+		fw = int(float64(tw) * percent) // filled width
+		p  float64
+	)
+
+	if m.useRamp {
+		// Gradient fill
+		for i := 0; i < fw; i++ {
+			if m.scaleRamp {
+				p = float64(i) / float64(fw)
+			} else {
+				p = float64(i) / float64(tw)
+			}
+			c := m.rampColorA.BlendLuv(m.rampColorB, p).Hex()
+			b.WriteString(termenv.
+				String(string(m.Full)).
+				Foreground(color(c)).
+				String(),
+			)
+		}
+	} else {
+		// Solid fill
+		s := termenv.String(string(m.Full)).Foreground(color(m.FullColor)).String()
+		b.WriteString(strings.Repeat(s, fw))
+	}
+
+	// Empty fill
+	e := termenv.String(string(m.Empty)).Foreground(color(m.EmptyColor)).String()
+	b.WriteString(strings.Repeat(e, tw-fw))
+}
+
+func (m *Model) setRamp(colorA, colorB string, scaled bool) error {
+	a, err := colorful.Hex(colorA)
+	if err != nil {
+		return err
+	}
+
+	b, err := colorful.Hex(colorB)
+	if err != nil {
+		return err
+	}
+
+	m.useRamp = true
+	m.scaleRamp = scaled
+	m.rampColorA = a
+	m.rampColorB = b
+	return nil
+}

spinner/spinner.go

@@ -1,42 +1,60 @@
 package spinner
 
 import (
+	"strings"
 	"time"
 
 	tea "github.com/charmbracelet/bubbletea"
+	"github.com/muesli/reflow/ansi"
 	"github.com/muesli/termenv"
 )
 
 const defaultFPS = time.Second / 10
 
 // Spinner is a set of frames used in animating the spinner.
-type Spinner = []string
+type Spinner struct {
+	Frames []string
+	FPS    time.Duration
+}
 
 var (
 	// Some spinners to choose from. You could also make your own.
-	Line   = Spinner{"|", "/", "-", "\\"}
-	Dot    = Spinner{"⣾ ", "⣽ ", "⣻ ", "⢿ ", "⡿ ", "⣟ ", "⣯ ", "⣷ "}
-	Globe  = Spinner{"🌍 ", "🌎 ", "🌏 "}
-	Moon   = Spinner{"🌑 ", "🌒 ", "🌓 ", "🌔 ", "🌕 ", "🌖 ", "🌗 ", "🌘 "}
-	Monkey = Spinner{"🙈 ", "🙈 ", "🙉 ", "🙊 "}
-	Jump   = Spinner{"⢄", "⢂", "⢁", "⡁", "⡈", "⡐", "⡠"}
-	Bit8   = Spinner{
-		"⠀", "⠁", "⠂", "⠃", "⠄", "⠅", "⠆", "⠇", "⡀", "⡁", "⡂", "⡃", "⡄", "⡅", "⡆", "⡇",
-		"⠈", "⠉", "⠊", "⠋", "⠌", "⠍", "⠎", "⠏", "⡈", "⡉", "⡊", "⡋", "⡌", "⡍", "⡎", "⡏",
-		"⠐", "⠑", "⠒", "⠓", "⠔", "⠕", "⠖", "⠗", "⡐", "⡑", "⡒", "⡓", "⡔", "⡕", "⡖", "⡗",
-		"⠘", "⠙", "⠚", "⠛", "⠜", "⠝", "⠞", "⠟", "⡘", "⡙", "⡚", "⡛", "⡜", "⡝", "⡞", "⡟",
-		"⠠", "⠡", "⠢", "⠣", "⠤", "⠥", "⠦", "⠧", "⡠", "⡡", "⡢", "⡣", "⡤", "⡥", "⡦", "⡧",
-		"⠨", "⠩", "⠪", "⠫", "⠬", "⠭", "⠮", "⠯", "⡨", "⡩", "⡪", "⡫", "⡬", "⡭", "⡮", "⡯",
-		"⠰", "⠱", "⠲", "⠳", "⠴", "⠵", "⠶", "⠷", "⡰", "⡱", "⡲", "⡳", "⡴", "⡵", "⡶", "⡷",
-		"⠸", "⠹", "⠺", "⠻", "⠼", "⠽", "⠾", "⠿", "⡸", "⡹", "⡺", "⡻", "⡼", "⡽", "⡾", "⡿",
-		"⢀", "⢁", "⢂", "⢃", "⢄", "⢅", "⢆", "⢇", "⣀", "⣁", "⣂", "⣃", "⣄", "⣅", "⣆", "⣇",
-		"⢈", "⢉", "⢊", "⢋", "⢌", "⢍", "⢎", "⢏", "⣈", "⣉", "⣊", "⣋", "⣌", "⣍", "⣎", "⣏",
-		"⢐", "⢑", "⢒", "⢓", "⢔", "⢕", "⢖", "⢗", "⣐", "⣑", "⣒", "⣓", "⣔", "⣕", "⣖", "⣗",
-		"⢘", "⢙", "⢚", "⢛", "⢜", "⢝", "⢞", "⢟", "⣘", "⣙", "⣚", "⣛", "⣜", "⣝", "⣞", "⣟",
-		"⢠", "⢡", "⢢", "⢣", "⢤", "⢥", "⢦", "⢧", "⣠", "⣡", "⣢", "⣣", "⣤", "⣥", "⣦", "⣧",
-		"⢨", "⢩", "⢪", "⢫", "⢬", "⢭", "⢮", "⢯", "⣨", "⣩", "⣪", "⣫", "⣬", "⣭", "⣮", "⣯",
-		"⢰", "⢱", "⢲", "⢳", "⢴", "⢵", "⢶", "⢷", "⣰", "⣱", "⣲", "⣳", "⣴", "⣵", "⣶", "⣷",
-		"⢸", "⢹", "⢺", "⢻", "⢼", "⢽", "⢾", "⢿", "⣸", "⣹", "⣺", "⣻", "⣼", "⣽", "⣾", "⣿"}
+	Line = Spinner{
+		Frames: []string{"|", "/", "-", "\\"},
+		FPS:    time.Second / 10,
+	}
+	Dot = Spinner{
+		Frames: []string{"⣾ ", "⣽ ", "⣻ ", "⢿ ", "⡿ ", "⣟ ", "⣯ ", "⣷ "},
+		FPS:    time.Second / 10,
+	}
+	MiniDot = Spinner{
+		Frames: []string{"⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"},
+		FPS:    time.Second / 12,
+	}
+	Jump = Spinner{
+		Frames: []string{"⢄", "⢂", "⢁", "⡁", "⡈", "⡐", "⡠"},
+		FPS:    time.Second / 10,
+	}
+	Pulse = Spinner{
+		Frames: []string{"█", "▓", "▒", "░"},
+		FPS:    time.Second / 8,
+	}
+	Points = Spinner{
+		Frames: []string{"∙∙∙", "●∙∙", "∙●∙", "∙∙●"},
+		FPS:    time.Second / 7,
+	}
+	Globe = Spinner{
+		Frames: []string{"🌍", "🌎", "🌏"},
+		FPS:    time.Second / 4,
+	}
+	Moon = Spinner{
+		Frames: []string{"🌑", "🌒", "🌓", "🌔", "🌕", "🌖", "🌗", "🌘"},
+		FPS:    time.Second / 8,
+	}
+	Monkey = Spinner{
+		Frames: []string{"🙈", "🙉", "🙊"},
+		FPS:    time.Second / 3,
+	}
 
 	color = termenv.ColorProfile().Color
 )
@@ -45,22 +63,19 @@ var (
 // rather than using Model as a struct literal.
 type Model struct {
 
-	// Type is the set of frames to use. See Spinner.
-	Frames Spinner
+	// Spinner settings to use. See type Spinner.
+	Spinner Spinner
 
-	// FPS is the speed at which the ticker should tick.
-	FPS time.Duration
-
-	// ForegroundColor sets the background color of the spinner. It can be a
-	// hex code or one of the 256 ANSI colors. If the terminal emulator can't
-	// doesn't support the color specified it will automatically degrade
-	// (per github.com/muesli/termenv).
+	// ForegroundColor sets the background color of the spinner. It can be
+	// a hex code or one of the 256 ANSI colors. If the terminal emulator can't
+	// support the color specified it will automatically degrade (per
+	// github.com/muesli/termenv).
 	ForegroundColor string
 
-	// BackgroundColor sets the background color of the spinner. It can be a
-	// hex code or one of the 256 ANSI colors. If the terminal emulator can't
-	// doesn't support the color specified it will automatically degrade
-	// (per github.com/muesli/termenv).
+	// BackgroundColor sets the background color of the spinner. It can be
+	// a hex code or one of the 256 ANSI colors. If the terminal emulator can't
+	// support the color specified it will automatically degrade (per
+	// github.com/muesli/termenv).
 	BackgroundColor string
 
 	// MinimumLifetime is the minimum amount of time the spinner can run. Any
@@ -86,17 +101,49 @@ type Model struct {
 
 	frame     int
 	startTime time.Time
+	tag       int
 }
 
 // Start resets resets the spinner start time. For use with MinimumLifetime and
 // MinimumStartTime. Optional.
 //
+// This function is optional and generally considered for advanced use only.
+// Most of the time your application logic will obviate the need for this
+// method.
+//
 // This is considered experimental and may not appear in future versions of
 // this library.
 func (m *Model) Start() {
 	m.startTime = time.Now()
 }
 
+// Finish sets the internal timer to a completed state so long as the spinner
+// isn't flagged to be showing. If it is showing, finish has no effect. The
+// idea here is that you call Finish if your operation has completed and, if
+// the spinner isn't showing yet (by virtue of HideFor) then Visible() doesn't
+// show the spinner at all.
+//
+// This is intended to work in conjunction with MinimumLifetime and
+// MinimumStartTime, is completely optional.
+//
+// This function is optional and generally considered for advanced use only.
+// Most of the time your application logic will obviate the need for this
+// method.
+//
+// This is considered experimental and may not appear in future versions of
+// this library.
+func (m *Model) Finish() {
+	if m.hidden() {
+		m.startTime = time.Time{}
+	}
+}
+
+// advancedMode returns whether or not the user is making use of HideFor and
+// MinimumLifetime properties.
+func (m Model) advancedMode() bool {
+	return m.HideFor > 0 && m.MinimumLifetime > 0
+}
+
 // hidden returns whether or not Model.HideFor is in effect.
 func (m Model) hidden() bool {
 	if m.startTime.IsZero() {
@@ -108,12 +155,10 @@ func (m Model) hidden() bool {
 	return m.startTime.Add(m.HideFor).After(time.Now())
 }
 
-// finished returns whether Model.MinimumLifetimeReached has been met.
+// finished returns whether the minimum lifetime of this spinner has been
+// exceeded.
 func (m Model) finished() bool {
-	if m.startTime.IsZero() {
-		return true
-	}
-	if m.MinimumLifetime == 0 {
+	if m.startTime.IsZero() || m.MinimumLifetime == 0 {
 		return true
 	}
 	return m.startTime.Add(m.HideFor).Add(m.MinimumLifetime).Before(time.Now())
@@ -121,13 +166,13 @@ func (m Model) finished() bool {
 
 // Visible returns whether or not the view should be rendered. Works in
 // conjunction with Model.HideFor and Model.MinimumLifetimeReached. You should
-// use this message directly to determine whether or not to render this view in
+// use this method directly to determine whether or not to render this view in
 // the parent view and whether to continue sending spin messaging in the
 // parent update function.
 //
-// Also note that using this function is optional and generally considered for
-// advanced use only. Most of the time your application logic will determine
-// whether or not this view should be used.
+// This function is optional and generally considered for advanced use only.
+// Most of the time your application logic will obviate the need for this
+// method.
 //
 // This is considered experimental and may not appear in future versions of
 // this library.
@@ -137,32 +182,36 @@ func (m Model) Visible() bool {
 
 // NewModel returns a model with default values.
 func NewModel() Model {
-	return Model{
-		Frames: Line,
-		FPS:    defaultFPS,
-	}
+	return Model{Spinner: Line}
 }
 
 // TickMsg indicates that the timer has ticked and we should render a frame.
 type TickMsg struct {
 	Time time.Time
+	tag  int
 }
 
-type startTick struct{}
-
 // Update is the Tea update function. This will advance the spinner one frame
 // every time it's called, regardless the message passed, so be sure the logic
 // is setup so as not to call this Update needlessly.
 func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
-	switch msg.(type) {
-	case startTick:
-		return m, m.tick()
+	switch msg := msg.(type) {
 	case TickMsg:
+
+		// If a tag is set, and it's not the one we expect, reject the message.
+		// This prevents the spinner from receiving too many messages and
+		// this spinning too fast.
+		if msg.tag > 0 && msg.tag != m.tag {
+			return m, nil
+		}
+
 		m.frame++
-		if m.frame >= len(m.Frames) {
+		if m.frame >= len(m.Spinner.Frames) {
 			m.frame = 0
 		}
-		return m, m.tick()
+
+		m.tag++
+		return m, m.tick(m.tag)
 	default:
 		return m, nil
 	}
@@ -170,11 +219,18 @@ func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
 
 // View renders the model's view.
 func (m Model) View() string {
-	if m.frame >= len(m.Frames) {
-		return "error"
+	if m.frame >= len(m.Spinner.Frames) {
+		return "(error)"
 	}
 
-	frame := m.Frames[m.frame]
+	frame := m.Spinner.Frames[m.frame]
+
+	// If we're using the fine-grained hide/show spinner rules and those rules
+	// deem that the spinner should be hidden, draw an empty space in place of
+	// the spinner.
+	if m.advancedMode() && !m.Visible() {
+		frame = strings.Repeat(" ", ansi.PrintableRuneWidth(frame))
+	}
 
 	if m.ForegroundColor != "" || m.BackgroundColor != "" {
 		return termenv.
@@ -187,15 +243,17 @@ func (m Model) View() string {
 	return frame
 }
 
-// Tick is the command used to advance the spinner one frame.
+// Tick is the command used to advance the spinner one frame. Use this command
+// to effectively start the spinner.
 func Tick() tea.Msg {
-	return startTick{}
+	return TickMsg{Time: time.Now()}
 }
 
-func (m Model) tick() tea.Cmd {
-	return tea.Tick(m.FPS, func(t time.Time) tea.Msg {
+func (m Model) tick(tag int) tea.Cmd {
+	return tea.Tick(m.Spinner.FPS, func(t time.Time) tea.Msg {
 		return TickMsg{
 			Time: t,
+			tag:  tag,
 		}
 	})
 }