Display Components

Purpose and Scope

This document provides an overview of the Display Components in the hypervel/prompts library - non-interactive components that present information to the user without collecting input. Display components include tables, progress indicators, spinners, styled messages, and terminal utilities.

This page covers the overall architecture and common patterns. For detailed documentation:

• Tables: See page 6.1
• Progress Bars and Spinners: See page 6.2
• Notes and Messages: See page 6.3

For interactive input collection, see page 5.

---

Overview

Display components serve informational and visual purposes in CLI applications. Unlike interactive prompts (page 5) that wait for user input, display components render immediately and return control to the application, or execute alongside operations to provide visual feedback.

The library provides five primary component types:

Component	Helper Function(s)	Class	Purpose	Subsection
Table	table()	Table	Display tabular data with headers and rows	6.1
Progress Bar	progress()	Progress	Show progress for iterative operations	6.2
Spinner	spin()	Spinner	Display loading indicator during callback execution	6.2
Styled Messages	note(), error(), warning(), alert(), info(), intro(), outro()	Note	Display semantic messages with type-based styling	6.3
Clear Screen	clear()	Clear	Clear terminal screen	6.3

Sources: src/helpers.php87-254

---

Class Hierarchy

Display components extend the base Prompt class, inheriting lifecycle management, theme rendering, and terminal control capabilities. The following diagram shows the inheritance structure:

Sources: src/Table.php9

---

Helper Function API

Display components are accessed via helper functions in src/helpers.php. The following diagram maps each helper function to its corresponding class constructor:

Key patterns:

• Single helper per component: table(), progress(), spin(), clear()
• Multiple helpers for Note: Seven semantic variants (note(), error(), warning(), alert(), info(), intro(), outro()) all instantiate Note with different $type values
• Direct instantiation: All helpers use new ClassName(...) followed by method call
• Consistent parameter passing: Most helpers use get_defined_vars() to forward all parameters

Sources: src/helpers.php87-95 src/helpers.php135-148 src/helpers.php150-218 src/helpers.php220-231 src/helpers.php233-254

---

Component Overview by Type

Table

The Table class renders tabular data with optional column headers.

Constructor signature: Table::__construct(array|Collection $headers = [], array|Collection|null $rows = null)

Invocation: table() helper at src/helpers.php220-231

Detailed documentation: See page 6.1

Sources: src/Table.php9-73 src/helpers.php220-231

---

Progress Bar

The Progress class displays a progress bar for iterative operations. Supports two operational modes:

Automatic mode: Pass a callback to progress() - executes callback for each step and returns array of results

Manual mode: Call progress() without callback - returns Progress instance for application-controlled advancement via advance() and finish() methods

Constructor signature: Progress::__construct(string $label, int|iterable $steps, string $hint = '')

Invocation: progress() helper at src/helpers.php233-254

Detailed documentation: See page 6.2

Sources: src/helpers.php233-254

---

Spinner

The Spinner class displays an animated loading indicator while executing a callback. Returns the callback's return value.

Constructor signature: Spinner::__construct(string $message)

Invocation: spin() helper at src/helpers.php135-148

Detailed documentation: See page 6.2

Sources: src/helpers.php135-148

---

Note (Styled Messages)

The Note class displays styled messages with semantic type variants. Single class supports seven presentation types:

Helper Function	Type Parameter	Use Case
note()	null (custom)	Generic styled message
error()	'error'	Error messages
warning()	'warning'	Warning messages
alert()	'alert'	Alert messages
info()	'info'	Informational messages
intro()	'intro'	Application start messages
outro()	'outro'	Application end messages

Constructor signature: Note::__construct(string $message, ?string $type = null)

Invocation: Seven helper functions at src/helpers.php150-218

Detailed documentation: See page 6.3

Sources: src/helpers.php150-218

---

Clear

The Clear class clears the terminal screen. Used to reset display state in interactive workflows.

Invocation: clear() helper at src/helpers.php87-95

Detailed documentation: See page 6.3

Sources: src/helpers.php87-95

---

Rendering Pipeline

All display components follow a consistent rendering flow from helper function invocation to terminal output:

Execution flow:

1. Helper function - Application calls helper (e.g., table(), note(), spin())
2. Instantiation - Helper creates component instance: new Table($headers, $rows)
3. Display method - Helper calls display() or prompt() on instance
4. Theme rendering - Component calls renderTheme() inherited from Prompt base class
5. Renderer delegation - Theme system routes to appropriate renderer (see page 8)
6. Terminal output - Rendered content written to terminal via Symfony Console

Sources: src/Table.php47-64 src/helpers.php220-231

---

Return Value Patterns

Display components exhibit three distinct return value patterns:

Pattern	Components	Return Type	Purpose
Immediate void	table(), note(), error(), warning(), alert(), info(), intro(), outro(), clear()	void	Display information and return control
Callback result	spin()	mixed	Return the wrapped callback's return value
Conditional	progress()	array | Progress	Return array when callback provided, else return Progress instance for manual control

Progress conditional logic:

Sources: src/helpers.php135-148 src/helpers.php233-254

---

Differences from Interactive Prompts

Display components extend Prompt (see page 4) but exhibit distinct behavioral characteristics:

Shared Infrastructure (via Prompt base class)

• Theme rendering: Access to renderTheme() for consistent styling (see page 8)
• Output handling: Standardized terminal output via static::output()
• State management: Common $state property for component lifecycle
• Event system: Ability to emit events via Events trait (see page 9.5)

Sources: src/Table.php9

Key Differences

Aspect	Interactive Prompts (page 5)	Display Components
Input loop	Implement input reading and processing	No input loop - render and return
User interaction	Wait for keyboard input	Immediate execution
Validation	Validate and transform user input	No validation - display only
Return values	Return user-provided data	Return void, callback results, or control objects
State transitions	Multiple states (active, error, submit, cancel)	Single state (submit)

Example from Table class:

The Table::prompt() method at src/Table.php55-64 demonstrates immediate rendering:

1. Sets $state = 'submit' without waiting for input
2. Writes rendered output via static::output()->write($this->renderTheme())
3. Returns true immediately

Sources: src/Table.php9 src/Table.php55-64

---

Summary

Display components provide essential informational and visual feedback capabilities for CLI applications:

• Table: Structured data presentation
• Progress: Visual feedback for iterative operations
• Spinner: Loading indicators for async operations
• Note: Semantic message display with multiple variants
• Clear: Terminal screen reset

All components follow the facade pattern through helper functions, integrate with the theme system for consistent styling, and extend the base Prompt class for infrastructure support while remaining non-interactive.

For building multi-step forms that combine display components with interactive prompts, see Multi-Step Forms.