notify

package
v0.0.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 23, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package notify provides a notification system for the grut TUI. It supports three tiers: toasts (auto-dismiss), inline (persistent), and modal (blocking) notifications.

Index

Constants

View Source
const DefaultToastDuration = 3 * time.Second

DefaultToastDuration is the default auto-dismiss time for toasts.

Variables

This section is empty.

Functions

func SafeUpdate

func SafeUpdate(p panels.Panel, msg tea.Msg) (result panels.Panel, cmd tea.Cmd)

SafeUpdate wraps a panel's Update call in a recovery boundary. If the panel panics, the panic is caught, logged via slog, and the original (pre-panic) panel is returned along with a command that produces a ShowToastMsg with the error details.

func SafeView

func SafeView(p panels.Panel, w, h int) (content string)

SafeView wraps a panel's View call in a recovery boundary. If the panel panics, the panic is caught, logged via slog, and an error placeholder is returned instead of the panel content.

func ShowActionPicker

func ShowActionPicker(title string, actions []ActionOption) tea.Cmd

ShowActionPicker returns a tea.Cmd that produces a ShowModalMsg for an action picker dialog with a selectable list of actions.

func ShowActionPickerWithCheckbox

func ShowActionPickerWithCheckbox(title, message, checkboxLabel string, actions []ActionOption) tea.Cmd

ShowActionPickerWithCheckbox returns a tea.Cmd that produces a ShowModalMsg for an action picker dialog with a "remember this choice" checkbox.

func ShowActionPickerWithMessage

func ShowActionPickerWithMessage(title, message string, actions []ActionOption) tea.Cmd

ShowActionPickerWithMessage returns a tea.Cmd that produces a ShowModalMsg for an action picker dialog with a title, subtitle message, and selectable list of actions.

func ShowConfirm

func ShowConfirm(title, message string) tea.Cmd

ShowConfirm returns a tea.Cmd that produces a ShowModalMsg for a yes/no confirmation dialog.

func ShowConfirmWithCheckbox

func ShowConfirmWithCheckbox(title, message, checkboxLabel string) tea.Cmd

ShowConfirmWithCheckbox returns a tea.Cmd that produces a ShowModalMsg for a confirmation dialog with a "remember this choice" checkbox.

func ShowInput

func ShowInput(title, placeholder string) tea.Cmd

ShowInput returns a tea.Cmd that produces a ShowModalMsg for a text input dialog.

func ShowInputWithValue

func ShowInputWithValue(title, placeholder, value string) tea.Cmd

ShowInputWithValue returns a tea.Cmd that produces a ShowModalMsg for a text input dialog pre-filled with the given value.

Types

type ActionOption

type ActionOption struct {
	ID    string // action ID (e.g., "checkout", "copy_name")
	Label string // human-readable label (e.g., "checkout", "copy name")
}

ActionOption represents a selectable action in the action picker modal.

type Level

type Level int

Level represents the severity of a notification.

const (
	// Info is for informational messages.
	Info Level = iota
	// Warn is for warning messages that may need attention.
	Warn
	// Error is for error messages requiring user attention.
	Error
	// Success is for positive confirmation messages.
	Success
)

func (Level) String

func (l Level) String() string

String returns the human-readable name for a notification level.

type Manager

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

Manager manages active notifications across all three tiers: toasts (auto-dismiss), inline (persistent), and modals (blocking). It lives in the root app model and is not owned by individual panels.

func NewManager

func NewManager() *Manager

NewManager creates a new notification manager with no active notifications.

func (*Manager) AddInline

func (m *Manager) AddInline(id, msg string, level Level)

AddInline adds a persistent inline notification identified by the given id. If an inline notification with the same id already exists, it is replaced.

func (*Manager) AddToast

func (m *Manager) AddToast(msg string, level Level) tea.Cmd

AddToast adds an auto-dismissing toast notification with the default duration (3 seconds). The toast will be removed automatically after the duration elapses.

func (*Manager) AddToastWithDuration

func (m *Manager) AddToastWithDuration(msg string, level Level, d time.Duration) tea.Cmd

AddToastWithDuration adds an auto-dismissing toast notification with a custom duration.

func (*Manager) DismissInline

func (m *Manager) DismissInline(id string)

DismissInline removes a persistent inline notification by id.

func (*Manager) HasModal

func (m *Manager) HasModal() bool

HasModal returns true if a modal is currently being displayed.

func (*Manager) InlineCount

func (m *Manager) InlineCount() int

InlineCount returns the number of active inline notifications.

func (*Manager) ModalView

func (m *Manager) ModalView(width, height int) string

ModalView renders the modal overlay if one is active. Returns empty string if no modal is displayed. The caller should render this on top of the main content.

func (*Manager) SetSize

func (m *Manager) SetSize(width, height int)

SetSize stores the terminal dimensions so mouse clicks can be mapped to modal-relative coordinates. The caller (app model) must call this whenever a WindowSizeMsg is received.

func (*Manager) ToastCount

func (m *Manager) ToastCount() int

ToastCount returns the number of active toasts.

func (*Manager) Update

func (m *Manager) Update(msg tea.Msg) tea.Cmd

Update processes Bubble Tea messages relevant to the notification system (toast expiry, modal input, etc.) and returns any resulting command.

func (*Manager) View

func (m *Manager) View(width int) string

View renders all active notifications into a string suitable for overlaying on the main layout. Toasts are rendered at the top, inline notifications below them.

type ModalKind

type ModalKind int

ModalKind distinguishes between confirmation and input modals.

const (
	// ModalConfirm displays a yes/no confirmation dialog.
	ModalConfirm ModalKind = iota
	// ModalInput displays a text input dialog.
	ModalInput
	// ModalConfirmWithCheckbox displays a yes/no confirmation dialog with
	// a "remember this choice" checkbox.
	ModalConfirmWithCheckbox
	// ModalActionPicker displays a selectable list of actions.
	ModalActionPicker
	// ModalActionPickerWithCheckbox displays a selectable list of actions
	// with a "remember this choice" checkbox.
	ModalActionPickerWithCheckbox
)

type ModalResultMsg

type ModalResultMsg struct {
	Value    string
	Accept   bool
	Remember bool
}

ModalResultMsg is sent when a modal dialog is dismissed by the user. Accept is true if the user confirmed, false if they cancelled. Value holds the text input value for input modals. Remember is true when the checkbox was checked (ConfirmWithCheckbox only); it is always false when Accept is false.

type Notification

type Notification struct {
	CreatedAt time.Time
	Message   string
	Level     Level
	Duration  time.Duration
}

Notification holds the data for a single notification.

type ShowModalMsg

type ShowModalMsg struct {
	Title         string
	Message       string
	Placeholder   string         // used only for input modals
	Value         string         // initial value for input modals (pre-fill)
	CheckboxLabel string         // label for the checkbox (ConfirmWithCheckbox only)
	Actions       []ActionOption // list of actions (ModalActionPicker only)
	Kind          ModalKind      // confirm, input, confirmWithCheckbox, or actionPicker
}

ShowModalMsg is a command message that triggers a modal dialog. The root model intercepts this and routes it to the notification manager.

type ShowToastMsg

type ShowToastMsg struct {
	Message  string
	Level    Level
	Duration time.Duration // 0 means use default (3s)
}

ShowToastMsg is a command message that any panel can produce to trigger a toast notification. The root model intercepts this and routes it to the notification manager.

type ToastExpiredMsg

type ToastExpiredMsg struct {
	// ID uniquely identifies the toast that expired.
	ID int64
}

ToastExpiredMsg indicates that a specific toast has expired and should be removed from the display.

type ToastTickMsg

type ToastTickMsg struct {
	// Time is the time at which the tick fired.
	Time time.Time
}

ToastTickMsg is sent on a regular interval to drive auto-dismiss timing for active toasts.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL