bubbleup

README

Welcome to BubbleUp

Float your alerts to the top of your TUI like a bubble in a soda. Integrates with BubbleTea applications seamlessly to render your status updates in style.

Getting Started

Run the following to download the module:

go get github.com/joel-sgc/BubbleUp

Then import it into your project with the following:

import (
    "github.com/joel-sgc/BubbleUp"
    tea "github.com/charmbracelet/bubbletea"
)

This is assuming you already have BubbleTea installed and available in your project. Go check out their repo here for more information!

From there, it's as simple as creating a new bubbleup.AlertModel by calling bubbleup.NewAlertModel([#], [true|false]), and embedding the returned model inside of your main model.

The first parameter is the width that you want the alerts to render at.
Note: If your message length exceeds the max width, it will wrap

The second parameter is whether or not to render the included NerdFont symbols for the included alert types, or just to use normal ASCII character prefixes. Check out Nerd Fonts here.
Note: If you override or don't use the included alert types, then this parameter doesn't matter.

Integrating Into Your BubbleTea App

Init

Be sure to return the result of the alert models' Init().
If you need to also return one or more commands, be sure to use tea.Batch() to bundle them together.

Update

This is where you'll actually spawn the alerts in, which is as easy as calling NewAlertCmd() with a key and a message. The formatting and stylings are handled by what's provided in the stored AlertDefinition types (more info below).

Example with the included Info alert type:

Be sure to pass any received messages to the alert model, and appropriately use the return values.
Reassign your stored alert with the updated alert, and return the given command, either alone or via tea.Batch().

alertCmd = m.alert.NewAlertCmd(bubbleup.InfoKey, "New info alert.") // Get the command to initiate the desired alert

outAlert, outCmd := m.alert.Update(msg)  // Pass any messages to the alert model, such as alert or tick messages
m.alert = outAlert.(bubbleup.AlertModel) // Reassign the returned alert model to the main model

return m, tea.Batch(alertCmd, outCmd)

View

You want to do all of your normal View stuff to render your output, and THEN pass that into your alert model's Render() function. This will overlay the alert onto the provided content. It is recommended to have this be the last thing you do in your View() function.

Note: The AlertModels' View() function is empty and is not intended to be called.

Creating Your Own Alert Types

You can create your own alert types by creating an instance of an AlertDefinition struct, and passing it into your model's RegisterNewAlertType() function. The AlertDefinition consists of the following parts:

• Key: (Required) Unique identifier for your alert type. What is passed into NewAlertCmd to get rendering information.
• ForeColor: (Required) A hex color string that you want to use as the foreground color of your alert type.
• Style: (Optional) A lipgloss.Style struct that will override the default one, but it's up to you to make sure your override meshes well.
• Prefix: (Optional) The symbol or strings used to prefix your message contents. Can be left empty

Example

You would declare and register your new alert type like this:

    myCustomAlert := AlertDefinition{
        Key: "CoolAlert",
        ForeColor: "#123456",
        Prefix: ":)"
    }

    m.alertModel.RegisterNewAlertType(myCustomAlert)

Note that I did not pass a style in, so it'll use the default.

Then call it later by doing:

outAlertCmd := m.alert.NewAlertCmd("CoolAlert", "My really cool alert message")

and handling it all as described in the Update section above.

Documentation

Index

• Constants
• type AlertDefinition
• type AlertModel
  • func NewAlertModel(width int, useNerdFont bool, duration time.Duration) *AlertModel
  • func (m AlertModel) Init() tea.Cmd
  • func (m AlertModel) NewAlertCmd(alertType, message string) tea.Cmd
  • func (m AlertModel) RegisterNewAlertType(definition AlertDefinition)
  • func (m AlertModel) Render(content string) string
  • func (m AlertModel) Update(msg tea.Msg) (tea.Model, tea.Cmd)
  • func (m AlertModel) View() string

Constants

const (
	InfoKey  = "Info"
	WarnKey  = "Warn"
	ErrorKey = "Error"
	DebugKey = "Debug"
)

Alert keys for the included alert types.

const (
	InfoNerdSymbol  = " "
	WarnNerdSymbol  = "󱈸 "
	ErrorNerdSymbol = "󰬅 "
	DebugNerdSymbol = "󰃤 "

	InfoUniPrefix    = "(i)"
	WarningUniPrefix = "(!)"
	ErrorUniPrefix   = "[!!]"
	DebugUniPrefix   = "(?)"
)

Symbols used by the included alert types. To use the NerdFont symbols, you must be using a NerdFont, which can be obtained from https://www.nerdfonts.com/. If you want to use the default non-NerdFont symbols, pass false into the useNerdFont parameter when creating your alert model.

const (
	InfoColor  = "#00FF00"
	WarnColor  = "#FFFF00"
	ErrorColor = "#FF0000"
	DebugColor = "#FF00FF"
)

Colors used by the included alert types.

const (
	DefaultLerpIncrement = 0.18
)

Defaults used by the notification rendering.

Types

type AlertDefinition

type AlertDefinition struct {
	// (Req) Unique key used to refer to an alert type
	Key string

	// (Req) Hex code of the color you want your alert to be
	ForeColor string

	// (Opt) lipgloss.Style used to render the alert
	Style lipgloss.Style

	// (Opt) String used to prefix the alert message
	Prefix string
}

AlertDefinition is all the information needed to register a new alert type.

type AlertModel

type AlertModel struct {
	// contains filtered or unexported fields
}

AlertModel maintains a list of alert types, and facilitates the display and clearing of alerts, as well as registering custom alerts and overrides to defaults Note: duration is measured in seconds

func NewAlertModel

func NewAlertModel(width int, useNerdFont bool, duration time.Duration) *AlertModel

NewAlertModel creates and returns a new AlertModel, initialized with default alert types

func (AlertModel) Init

func (m AlertModel) Init() tea.Cmd

Init starts the ticking command that causes alert refreshing Implemented as part of BubbleTea Model interface

func (AlertModel) NewAlertCmd

func (m AlertModel) NewAlertCmd(alertType, message string) tea.Cmd

NewAlertCmd will construct and return the tea.Cmd needed to trigger an alert. This should be called in your Update() function, and the returned tea.Cmd should be batched into your return.

func (AlertModel) RegisterNewAlertType

func (m AlertModel) RegisterNewAlertType(definition AlertDefinition)

RegisterNewAlertType will registery a new alert type based on the provided AlertDefintion. This can also be used to overwrite the provided defaults by providing an AlertDefintion with one of the default keys.

func (AlertModel) Render

func (m AlertModel) Render(content string) string

RenderAlert takes in the main view content and overlays the model's active alert. This function expects you build the entirety of your view's content before calling this function. It's recommended for this to be the final call of your model's View(). Returns a string representation of the content with overlayed alert.

func (AlertModel) Update

func (m AlertModel) Update(msg tea.Msg) (tea.Model, tea.Cmd)

Update takes in a message and returns an associated command to drive model functionality Implemented as part of BubbleTea Model interface

func (AlertModel) View

func (m AlertModel) View() string

View doesn't do anything, and it should never be called directly Implemented as part of BubbleTea Model interface