statcard

README

Stat Card

Dashboard metric tile with label, value, trend, and sublabel.

Install

glyph add stat-card

This copies stat-card.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 stat-card library to keep in sync.

Hello, world

package main

import (
	"fmt"

	"github.com/charmbracelet/lipgloss"

	statcard "github.com/truffle-dev/glyph/components/stat-card"
)

func main() {
	merged := statcard.New().
		WithLabel("Merged PRs").
		WithValue("88").
		WithDelta("+12").
		WithTrend(statcard.TrendUp).
		WithSublabel("this month")

	revenue := statcard.New().
		WithLabel("Revenue").
		WithValue("$0").
		WithDelta("-100%").
		WithTrend(statcard.TrendDown).
		WithSublabel("since signup").
		WithEmphasis(true)

	row := lipgloss.JoinHorizontal(lipgloss.Top, merged.View(), "  ", revenue.View())
	fmt.Println(row)
}

API surface

Package: statcard

Types

• Trend
• Model

Functions and methods

• New
• NewWithTheme
• WithLabel
• WithValue
• WithDelta
• WithTrend
• WithSublabel
• WithWidth
• WithEmphasis
• Width
• Height
• Init
• Update
• View

Dependencies

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

Notes

Build cards with the immutable With… chain and compose a row using lipgloss.JoinHorizontal(lipgloss.Top, c1.View(), c2.View()). WithWidth(0) auto-sizes the tile to its widest row; a positive value fixes outer width and truncates long content with an ellipsis. WithEmphasis(true) swaps in a rounded border over a stronger surface background — reserve it for one or two primary tiles per row.

The stat-card has no state and ignores every message in Update. Embed the Model in the parent's struct and rebuild it on each tick by pointing the builders at fresh data.

See also

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

License

MIT, same as the rest of glyph.

Documentation

Overview

Package statcard renders a dashboard metric tile: a single bordered card with a small uppercase label, a big bold value, and an optional trend row (glyph + delta + italic sublabel). Compose multiple cards in a horizontal row with lipgloss.JoinHorizontal to open any agent surface — engagements, PRs, revenue, latency.

Stat-cards are stateless from a TUI perspective: every Update is a no-op. The Bubble Tea Init/Update/View shape is still exposed so a parent model can drop a Model into its struct, re-render on every tick, and rebuild cards by chaining the immutable builders.

Index

• type Model
  • func New() Model
  • func NewWithTheme(t theme.Theme) Model
  • func (m Model) Height() int
  • func (m Model) Init() tea.Cmd
  • func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)
  • func (m Model) View() string
  • func (m Model) Width() int
  • func (m Model) WithDelta(s string) Model
  • func (m Model) WithEmphasis(on bool) Model
  • func (m Model) WithLabel(s string) Model
  • func (m Model) WithSublabel(s string) Model
  • func (m Model) WithTrend(t Trend) Model
  • func (m Model) WithValue(s string) Model
  • func (m Model) WithWidth(w int) Model
• type Trend

Types

type Model

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

Model is the immutable stat-card. Each With… builder returns a new Model so callers can compose cards inline in their View().

func New

func New() Model

New constructs a Model bound to theme.Default. Set fields with the chain-builders before calling View().

func NewWithTheme

func NewWithTheme(t theme.Theme) Model

NewWithTheme is the same as New but lets the parent inject a non-default palette (light theme, alt theme, etc.).

func (Model) Height

func (m Model) Height() int

Height returns the rendered outer height in cells. 6 for a label+value card, 7 with a delta or sublabel.

func (Model) Init

func (m Model) Init() tea.Cmd

Init implements tea.Model. Stat-cards do not animate, so no command is issued; this exists so a parent embedding a Model can call Init in its own Init chain without a special case.

func (Model) Update

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

Update implements tea.Model. Stat-cards do not respond to messages — the parent owns the data and rebuilds the card on every tick. Update returns the receiver unchanged. WindowSizeMsg in particular is a no-op: composing cards into a layout is the parent's responsibility.

func (Model) View

func (m Model) View() string

View renders the card. Safe to call repeatedly; no side effects.

func (Model) Width

func (m Model) Width() int

Width returns the rendered outer width in cells.

func (Model) WithDelta

func (m Model) WithDelta(s string) Model

WithDelta sets the small colored change indicator on line 3, e.g. "+3", "-12%", "0". The trend chooses the color.

func (Model) WithEmphasis

func (m Model) WithEmphasis(on bool) Model

WithEmphasis bumps the card to "primary tile" styling: rounded border over the default normal border, SurfaceStrong over Surface, and a brighter border color. Use sparingly — one or two per row.

func (Model) WithLabel

func (m Model) WithLabel(s string) Model

WithLabel sets the small uppercase label on line 1. Conventionally a noun phrase like "Open issues" or "Revenue".

func (Model) WithSublabel

func (m Model) WithSublabel(s string) Model

WithSublabel sets the italic muted line under the value, e.g. "since last week", "across 24 repos".

func (Model) WithTrend

func (m Model) WithTrend(t Trend) Model

WithTrend chooses the trend glyph and color: up=success, down=error, neutral=muted.

func (Model) WithValue

func (m Model) WithValue(s string) Model

WithValue sets the big bold value on line 2. Free-form string — "12", "$499/mo", "1.2k", "00:42". No internal formatting; pass the already-formatted display string.

func (Model) WithWidth

func (m Model) WithWidth(w int) Model

WithWidth fixes the outer width in cells. 0 means auto-size to the widest of label/value/(delta+sublabel) plus padding and borders. Values smaller than the minimum viable card (chromeCells+1 = 5) clamp up so the card always renders something.

type Trend

type Trend int

Trend chooses the glyph and color of the delta row.

const (
	// TrendNeutral renders an em-dash glyph in muted text.
	TrendNeutral Trend = iota
	// TrendUp renders an upward triangle in success color.
	TrendUp
	// TrendDown renders a downward triangle in error color.
	TrendDown
)