notificationtoast

README

Notification Toast

Stacked, dismissible notifications with level-aware coloring.

Install

glyph add notification-toast

This copies notification-toast.go (and its test file) into your repo at the path your glyph.json aliases declare. After install, the file is yours: edit it, refactor it, rename it. There is no notification-toast library to keep in sync.

Hello, world

package main

import (
	"fmt"
	"time"

	notificationtoast "github.com/truffle-dev/glyph/components/notification-toast"
	"github.com/truffle-dev/glyph/components/theme"
)

func main() {
	tray := notificationtoast.New(theme.Default).
		WithWidth(48).
		WithMaxItems(3)
	tray = tray.Push(notificationtoast.Toast{
		ID:        "build-1",
		Level:     notificationtoast.LevelSuccess,
		Title:     "Success",
		Message:   "Build complete.",
		ExpiresAt: time.Now().Add(6 * time.Second),
	})
	fmt.Println(tray.View())
}

API surface

Package: notificationtoast

Types

• Level
• Toast
• Tray

Functions and methods

• New
• WithWidth
• WithMaxItems
• Push
• Dismiss
• DismissAll
• Tick
• Toasts
• Init
• Update
• View

Dependencies

• glyph component theme (installed automatically)
• github.com/charmbracelet/bubbletea@v1.3.10
• github.com/charmbracelet/lipgloss@v1.1.0
• github.com/muesli/reflow@v0.3.0

Notes

Drive expiry from a tea.Cmd that sends a tick message every second: tr = tr.Tick(time.Now()). The tray renders nothing when empty; lay it over your main view with lipgloss.JoinVertical or .Place to position it.

See also

• examples/showcase — single-binary TUI composing the seven main surfaces
• components/notification-toast/story — runnable story binary (go run -tags glyph_story ./components/notification-toast/story/)
• registry manifest — the JSON contract glyph add reads

License

MIT, same as the rest of glyph.

Documentation

Overview

Package notificationtoast renders a stack of dismissible, level-aware notifications. Each toast carries a level, an optional title, and a message. Toasts auto-expire after a per-toast TTL or stay until the consumer explicitly dismisses them.

The tray is render-only: pump time forward by calling Tick(now) on a timer in your Update function and the tray drops expired toasts. Push adds a new toast; Dismiss removes one by ID.

Index

• type Level
• type Toast
• type Tray
  • func New(t theme.Theme) Tray
  • func (tr Tray) Dismiss(id string) Tray
  • func (tr Tray) DismissAll() Tray
  • func (tr Tray) Init() tea.Cmd
  • func (tr Tray) Push(t Toast) Tray
  • func (tr Tray) Tick(now time.Time) Tray
  • func (tr Tray) Toasts() []Toast
  • func (tr Tray) Update(_ tea.Msg) (Tray, tea.Cmd)
  • func (tr Tray) View() string
  • func (tr Tray) WithMaxItems(n int) Tray
  • func (tr Tray) WithWidth(w int) Tray

Types

type Level

type Level int

Level controls the toast's color and icon.

const (
	LevelInfo Level = iota
	LevelSuccess
	LevelWarning
	LevelError
)

type Toast

type Toast struct {
	ID        string
	Level     Level
	Title     string
	Message   string
	ExpiresAt time.Time // zero value means no auto-dismiss
}

Toast is a single notification.

type Tray

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

Tray holds the active toasts and renders them as a vertical stack.

func New

func New(t theme.Theme) Tray

New constructs an empty Tray with default width 50 and max 4 visible.

func (Tray) Dismiss

func (tr Tray) Dismiss(id string) Tray

Dismiss removes the toast with the given ID. Missing IDs are ignored.

func (Tray) DismissAll

func (tr Tray) DismissAll() Tray

DismissAll empties the tray.

func (Tray) Init

func (tr Tray) Init() tea.Cmd

Init implements tea.Model. The tray has no autonomous behavior.

func (Tray) Push

func (tr Tray) Push(t Toast) Tray

Push adds a toast. If maxItems is exceeded, the oldest drops.

func (Tray) Tick

func (tr Tray) Tick(now time.Time) Tray

Tick removes toasts whose ExpiresAt is non-zero and <= now.

func (Tray) Toasts

func (tr Tray) Toasts() []Toast

Toasts returns a copy of the current toasts.

func (Tray) Update

func (tr Tray) Update(_ tea.Msg) (Tray, tea.Cmd)

Update is a no-op. The tray is driven by external Push/Dismiss/Tick. It is implemented so the type satisfies tea.Model for composition.

func (Tray) View

func (tr Tray) View() string

View renders the tray as a vertical stack of cards separated by a blank line. Empty tray renders to empty string.

func (Tray) WithMaxItems

func (tr Tray) WithMaxItems(n int) Tray

WithMaxItems caps the number of toasts shown at once. Older toasts drop first when capacity is exceeded.

func (Tray) WithWidth

func (tr Tray) WithWidth(w int) Tray

WithWidth sets the rendered width of each toast card. Minimum 20.