Home

Welcome to the Espresso Wiki

Espresso is a lightweight, declarative terminal UI framework for Python inspired by Charm's Bubble Tea, Lip Gloss, and Bubbles.

Built purely with the Python standard library (zero external dependencies), Espresso brings deterministic state transitions, rich TrueColor terminal styling, and a modular component ecosystem to Python developers.

---

📚 Table of Contents

Section	Description
Getting Started	Requirements, installation (pip install espressoTUI), standalone .pyz runner, first TEA application, and CLI commands.
The Elm Architecture	Model-Update-View triad, Cmd async isolation, mouse gesture tracking, alt-screen line-diffing engine, and sub-model composition.
Crema Styling Guide	Declarative styles, TrueColor linear/multi-gradients, border titles, ANSI word wrapping, FlexBox, and responsive multi-column Grid.
Beans Component Catalog	Comprehensive reference for all 39 standard UI beans with full code examples, keyboard controls, and configuration options.
Release & Packaging	Package distribution formats (Wheel, sdist, universal zipapp, standalone native binaries), PyPI Trusted Publishing, and ./scripts/release.py.

---

🏛️ Ecosystem Architecture at a Glance

Layer	Charm Equivalent	Description
espresso	bubbletea	The Strong Base: Core TEA framework, runtime event loop, raw terminal driver, command primitives, flicker-free line-diffing alt-screen renderer, SGR mouse tracking, and desktop gesture engine (MouseGestureTracker).
espresso.crema	lipgloss	The Smooth Crema: Declarative styling, box model, TrueColor (24-bit RGB), ANSI 256, borders, border titles, TrueColor linear gradients, ANSI word-wrapping, 2D layout alignment, FlexBox, and responsive Grid.
espresso.beans	bubbles	The Flavorful Beans: 39 reusable UI components including TextArea, GitTree, CommandPalette, BarChart, Splitter, Sliders, Form, DiffViewer, SortableList, Confetti, CodeViewer, MarkdownViewer, Tables, Viewports, and more.
espresso CLI	—	The Toolkit: Standalone developer executable for listing built-in examples, launching the interactive gallery, running scripts, and scaffolding new applications.

---

🧩 39 Standard UI Beans

Component	Description
Spinner	Animated activity indicators (DOTS, LINE, PULSE, POINTS, COFFEE, GLOBE, MOON).
TextInput	Interactive text field with cursor blinking, navigation, and password masking.
Progress	Smooth percentage progress bars with custom styles and dynamic width scaling.
Viewport	Scrollable viewport for long terminal content with mouse wheel support.
Table	Column-formatted interactive table with row selection, headers, and pagination.
TextArea	Multi-line text editor with line numbering, cursor navigation, and viewport scrolling.
Help	Adaptive keybinding helper rendering compact single-line or full multi-column hotkey lists.
Timer	High-precision countdown timer driven by tick commands with formatted duration.
Stopwatch	High-precision stopwatch tracking elapsed time with split-second hundredths display.
Paginator	Pagination controller supporting bullet dots, numeric counters, and compact ranges.
Dialog	Modal dialog confirmation box with custom button actions and backdrop dimming.
List	Filterable list with real-time search query filtering, badges, and cursor selection.
FilePicker	Terminal filesystem browser with human-readable file sizes and extension filtering.
Prompt	Interactive CLI prompt suite: SelectPrompt, MultiSelectPrompt, ConfirmPrompt.
ToastManager	Transient toast notification manager with severity levels (INFO, SUCCESS, WARN, ERROR).
Tabs	Tab bar navigation header with styles (PILL, LINE, BRACKET) and numeric hotkeys.
Tree	Hierarchical collapsible tree view with Unicode connectors and node selection.
StatusBar	Responsive multi-section status bar with Left, Center, and Right priority clusters.
Metric / MetricGroup	KPI stat cards and tags with trend indicators (UP, DOWN, NEUTRAL) and delta metrics.
NavStack	Hierarchical view router with push/pop transitions, breadcrumbs, and message routing.
DatePicker	Interactive calendar date picker with month/year navigation and date clamping.
PipelineProgress	Multi-stage task execution pipeline with live status badges and execution times.
MarkdownViewer	Pure Python GitHub-flavored markdown viewer with code blocks, tables, and scrolling.
CodeViewer	Syntax-highlighted code viewer (Python, JS, Go, Rust, SQL, JSON) with cursor highlighting.
QuickFix	Diagnostic bottom drawer for linter issues with severity badges and view compositing.
DetailSelector	Dual-pane master-detail list selector with real-time preview panel.
ImageViewer	Terminal graphics viewer rendering TrueColor half-blocks (▀) and ASCII grayscale.
Splitter	Dual-pane container (Left | Right or Top / Bottom) with draggable divider bar.
Slider / RangeSlider	Direct-manipulation numeric slider and dual-thumb range bar with mouse dragging.
Sparkline	High-resolution Unicode Braille curves (4× vertical resolution) and 1D block bars.
Marquee	Smoothly scrolling animated text ticker with loop and bounce physics.
SortableList	Reorderable list supporting mouse drag-and-drop and keyboard Space+Arrows.
Spring	Physical damped harmonic oscillator simulation with analytical differential equation solver.
Confetti	2D celebratory particle physics emitter (radial bursts, cannons, rain) with drag & gravity.
DiffViewer	Git diff visualizer with Unified and Split dual-pane views and intra-line word diffs.
Form / FormBuilder	Multi-field form container with validation, inline error badges, and Tab cycling.
CommandPalette	Spotlight search runner (Ctrl+P / Cmd+P) with recents tracking and modal overlay.
GitTree	Collapsible Git file tree with status badges ([M], [A], [D], [?]) and branch header.
BarChart	Horizontal and vertical bar charts with sub-character precision and TrueColor gradients.