gh-aperepel-textual-tui-skill/skill/assets/README.md

Example Textual Applications

Complete, working example applications demonstrating various Textual patterns and features.

Running the Examples

Each example is a standalone Python file. To run:

# Install dependencies
pip install textual textual-dev psutil

# Run any example
python todo_app.py
python dashboard_app.py
python data_viewer.py
python worker_demo.py

# Or with hot reload during development
textual run --dev todo_app.py

Examples

todo_app.py - Todo List Application

A fully functional todo list demonstrating:

• Input handling and form validation
• List view with custom list items
• State management with reactive attributes
• Keyboard shortcuts and bindings
• Custom styling and theming
• Toggle states and visual feedback

Key Features:

• Add/delete/toggle todos
• Mark items as complete
• Statistics tracking
• Keyboard shortcuts (Ctrl+N, Space, Ctrl+D, etc.)

Patterns Demonstrated:

• Custom widget creation (TodoItem)
• Reactive state updates
• Event handling (button press, input submit)
• Keyboard bindings
• CSS styling with pseudo-classes

dashboard_app.py - System Monitor Dashboard

A real-time system monitoring dashboard demonstrating:

• Grid layouts for dashboard design
• Reactive data updates
• Custom composite widgets
• Data visualization with Sparkline and ProgressBar
• Real-time monitoring with intervals
• Metric cards and charts

Key Features:

• Live CPU and memory monitoring
• Historical CPU usage chart
• System metrics (cores, frequency, processes, uptime)
• Auto-refresh every second
• Manual refresh with 'R' key

Patterns Demonstrated:

• Grid-based layouts
• Custom widget composition (MetricCard, CPUChart, MemoryChart)
• Timed updates with set_interval()
• Reactive attributes for live updates
• Data visualization components

data_viewer.py - JSON/CSV Data Viewer

A file browser and data viewer demonstrating:

• File system navigation with DirectoryTree
• Multiple view modes (Table, Tree, Info) with tabs
• DataTable for tabular data
• Tree widget for hierarchical data
• Modal dialogs for errors
• Search and filter functionality

Key Features:

• Browse and select files from file system
• Load and display JSON and CSV files
• View data as table or tree structure
• File information panel
• Search functionality
• Error handling with modal dialogs

Patterns Demonstrated:

• Horizontal split layout (sidebar + content)
• Tabbed content interface
• Modal screen dialogs
• File I/O and data parsing
• Dynamic data loading
• Event handling across multiple widgets

worker_demo.py - Background Task Processing

A comprehensive worker pattern demonstration with two apps:

FileProcessor App:

• Single long-running worker with progress updates
• Worker cancellation
• Real-time statistics (speed, time elapsed)
• Progress bar updates from worker
• Error handling and state management

MultiWorkerDemo App:

• Multiple concurrent workers
• Group-based worker management
• Batch cancellation
• Independent progress tracking per worker

Key Features:

• Simulated file processing with 100 files
• Real-time progress updates
• Worker state change monitoring
• Cancellation support
• Statistics tracking (files/sec, elapsed time)

Patterns Demonstrated:

• run_worker() for background tasks
• Worker lifecycle management
• Thread-safe UI updates
• Progress reporting from workers
• Worker cancellation and cleanup
• Multiple concurrent workers
• Worker groups and batch operations
• Error handling in workers

Common Patterns

All examples demonstrate these fundamental patterns:

• Proper app structure with compose() method
• Header and Footer usage
• Keyboard bindings
• CSS styling with Textual's CSS system
• Event handling with on_* methods
• Reactive state management
• Widget querying with query_one() and query()

Learning Path

1. Start with todo_app.py - Learn basic input, lists, and state management
2. Move to dashboard_app.py - Understand layouts, custom widgets, and real-time updates
3. Try worker_demo.py - Master background tasks and worker patterns (IMPORTANT!)
4. Explore data_viewer.py - Master complex layouts, tabs, and data handling

Extending the Examples

Feel free to modify these examples:

• Add persistence to todo_app (save/load from file)
• Add network monitoring to dashboard_app
• Add export functionality to data_viewer
• Add real file processing to worker_demo (use actual files)
• Customize the styling and themes
• Add new features and widgets

Resources

• Textual Documentation: https://textual.textualize.io/
• Widget Gallery: See references/widgets.md
• Layout Patterns: See references/layouts.md
• Styling Guide: See references/styling.md