Overview

This document provides a high-level introduction to the hypervel/prompts library. It covers the library's purpose, architectural design, core concepts, and how the major systems interconnect. For installation instructions, see Getting Started. For specific prompt types and features, see Interactive Prompts and Display Components.

Purpose and Scope

The hypervel/prompts library is a PHP library designed to add interactive, user-friendly prompts and forms to command-line applications. It provides a comprehensive set of tools for capturing user input, displaying information, and building complex multi-step forms in the terminal environment.

Sources: composer.json1-39

What is hypervel/prompts?

hypervel/prompts is a library that enables developers to create beautiful CLI interactions through:

• Interactive Prompts: Text input, single/multiple selection, search, and confirmation prompts
• Display Components: Tables, progress bars, spinners, and styled messages
• Multi-Step Forms: Wizard-like forms with navigation and conditional logic via FormBuilder
• Flexible Rendering: Pluggable theme system with HTML-like terminal styling via Termwind

The library exposes its functionality primarily through a set of helper functions defined in src/helpers.php, providing a simple, functional API for CLI interactions.

Sources: composer.json4 composer.json13-19

Core Requirements

Requirement	Version/Constraint	Purpose
PHP	^8.2	Core language runtime
ext-mbstring	*	Multibyte string support for Unicode handling
symfony/console	^6.2 | ^7.0	CLI infrastructure and terminal I/O
nunomaduro/termwind	^2.0	HTML-like terminal output styling
composer-runtime-api	^2.2	Composer integration

Sources: composer.json21-26

Architectural Layers

The library follows a layered architecture where each layer builds upon the foundation below it:

Sources: composer.json13-19 composer.json21-26

Component Taxonomy

The library organizes its functionality into distinct component categories:

This taxonomy maps the functional API (helper functions) to their corresponding implementation classes. Each helper function instantiates and executes the appropriate prompt component.

Sources: composer.json17-18

Core Design Patterns

Trait-Based Composition

The library uses PHP traits extensively to compose reusable functionality:

Trait/Concern	Namespace Pattern	Purpose
Scrolling	Concerns\Scrolling	Enables keyboard navigation through long lists
TypedValue	Concerns\TypedValue	Manages text input and cursor positioning
Colors	Concerns\Colors	Provides ANSI color and styling capabilities
Truncation	Concerns\Truncation	Handles text fitting within terminal width
Themes	Concerns\Themes	Enables pluggable renderer selection
Events	Concerns\Events	Event system for prompt lifecycle hooks
Cursor	Concerns\Cursor	Direct terminal cursor manipulation
Erase	Concerns\Erase	Terminal screen clearing operations

Components mix in these traits as needed. For example:

• SelectPrompt uses Scrolling and Themes
• SearchPrompt uses Scrolling, TypedValue, and Truncation
• TextPrompt uses TypedValue

This pattern promotes code reuse and separation of concerns. For details on individual traits, see Reusable Traits and Concerns.

Pluggable Rendering

The theme system allows components to delegate rendering logic to specialized renderer classes. The Themes trait provides the getRenderer() method that resolves the appropriate renderer based on configuration. The Default Renderer handles standard output formatting using Termwind for HTML-like styling.

For more on customization, see Theming and Rendering System.

Data Flow Architecture

The following diagram illustrates how data flows through the system from user invocation to terminal output:

Key Components:

• Helper functions: Entry point that instantiates prompt classes
• Prompt classes: Business logic for interaction and validation
• Base class: Common infrastructure using Symfony Console
• Renderers: Format output via theme system
• Symfony Console: Terminal I/O abstraction

Sources: composer.json13-26

Package Metadata

The library is distributed as a Composer package with the following characteristics:

Property	Value
Package Name	hypervel/prompts
Type	library
License	MIT
Namespace	Hypervel\Prompts\
Autoloading	PSR-4 + global helpers
Branch Alias	0.3-dev for dev-main
Stability	dev (minimum), stable (preferred)

The package includes both namespaced classes under Hypervel\Prompts\ and global helper functions loaded from src/helpers.php. This dual approach provides flexibility: developers can use the clean functional API (helper functions) or instantiate prompt classes directly for more control.

Sources: composer.json1-39

Navigation Guide

This wiki is organized into the following sections:

• Getting Started: Installation and first prompt
• Helper Functions: Complete API reference
• Interactive Prompts: Input capture components
• Display Components: Information presentation
• Multi-Step Forms: Complex form workflows
• Theming and Rendering: Visual customization
• Traits and Concerns: Reusable functionality
• Testing and Advanced Features: Testing strategies and advanced topics