VP Terminal - Advanced CLI UI Library

vpterm-vp is a comprehensive terminal UI library for Python CLIs, inspired by modern interfaces like Claude Code.

✨ Features

• Component System: Modular UI components with layout management
• Interactive Menus: Dropdown menus with keyboard navigation
• Tabbed Interface: Multi-tab applications with easy switching
• Rich Layouts: FlexBox and Grid layouts for responsive design
• Widget Library: Pre-built components (TextBox, Alert, Badge, etc.)
• ANSI Styling: Full color and style support with auto-detection
• Progress Bars: Visual progress indicators and spinners
• Tables & Panels: Structured data display
• Window Management: Full application window framework

🚀 Quick Start

Install:

pip install vpterm-vp

This package now focuses on terminal primitives and rendering components. For a real training logger demo with live updates and parallel workers, use the sample in morphlog-vp.

📖 Basic Usage

from vpterm import Window, TextBox, Title, Alert

# Create a window
window = Window("My App")
window.set_header(Title("Welcome to VP Terminal"))

# Add content
window.set_content(TextBox("Hello, World!"))
window.set_footer(Alert("Ready!", "success"))

# Display
window.display()

🧩 Components

Core Components

• Component: Base class for all UI elements
• Container: Groups multiple components
• FlexBox: Flexible layout container
• GridLayout: Grid-based layout

UI Widgets

• TextBox: Multi-line text display
• Title: Large, styled title
• Alert: Status messages (success/warning/error/info)
• Badge: Small status indicators
• Box: Bordered content container
• Spacer: Flexible spacing
• Divider: Visual separators

Interactive Elements

• Menu: Dropdown menu with items
• MenuBar: Horizontal menu bar
• Tab: Individual tab content
• TabBar: Tab navigation
• TabGroup: Multi-group tab management

Data Display

• Table: Columnar data display
• Panel: Bordered information panels
• KeyValue: Key=value formatted output

Application Framework

• Window: Main application window
• StatusBar: Bottom status display
• ProgressBar: Visual progress indicators

🎨 Styling

from vpterm import Style

# Colors
print(Style.red("Error message"))
print(Style.green("Success!"))
print(Style.blue("Information"))

# Styles
print(Style.bold("Important text"))
print(Style.underline("Underlined"))
print(Style.invert("Highlighted"))

# Combined
print(Style.bold(Style.red("Critical error!")))

📐 Layouts

FlexBox Layout

from vpterm import FlexBox, Direction, TextBox

layout = FlexBox(direction=Direction.VERTICAL, gap=1)
layout.add_child(TextBox("First item"))
layout.add_child(TextBox("Second item"))

Grid Layout

from vpterm import GridLayout, Box

grid = GridLayout(columns=3, gap=2)
for i in range(9):
    grid.add_child(Box(TextBox(f"Item {i+1}")))

🎯 Interactive Menus

from vpterm import MenuBar, Menu, Window

menu_bar = MenuBar()

file_menu = Menu("File")
file_menu.add_item("New", "Ctrl+N", lambda: print("New!"))
file_menu.add_item("Open", "Ctrl+O", lambda: print("Open!"))
menu_bar.add_menu(file_menu)

window = Window("My App")
window.set_menu_bar(menu_bar)

📊 Tables and Panels

from vpterm import Table, Panel

# Table
table = Table(["Name", "Age", "City"])
table.add_row(["Alice", "25", "NYC"])
table.add_row(["Bob", "30", "LA"])

# Panel
panel = Panel("User Info")
panel.add_kv("Name", "Alice")
panel.add_kv("Status", "Active")

🏗️ Architecture

vpterm/
├── core/           # Component system & layouts
├── ui/             # Widgets & interactive elements
├── rendering/      # Styling & display components
├── window/         # Application framework
├── terminal/       # Terminal interaction
└── data/           # Data formatting

🔧 Advanced Features

• Responsive Design: Automatic terminal size detection
• Keyboard Navigation: Full keyboard control for menus and tabs
• Live Updates: Progress bars and spinners for long operations
• Color Detection: Automatic ANSI color support detection
• Cross-platform: Windows, macOS, Linux support

📝 API Reference

For detailed API documentation, see the docstrings in each module.

🤝 Contributing

Contributions welcome! The library is designed to be modular and extensible.

📄 License

MIT License - see LICENSE file for details.