Reusable Traits and Concerns

Purpose and Scope

This page provides an overview of the trait-based architecture used throughout the hypervel/prompts library. The library employs PHP traits, organized in the Hypervel\Prompts\Concerns namespace, to provide reusable functionality that prompt components and display elements can compose as needed.

This page introduces the architectural pattern and catalogs the available traits. For detailed documentation of specific traits, see the following pages:

• 9.1 Scrolling Lists - Navigation through long option lists
• 9.2 ANSI Colors and Styling - Terminal text styling
• 9.3 Terminal Control - Cursor and Erase - Direct terminal manipulation
• 9.4 Text Truncation - Fitting text within display constraints
• 9.5 Event System - Event handling and keyboard input
• 9.6 Typed Value Management - Text input and cursor positioning

For testing-related traits, see 10.1 Testing with Mocked Terminal I/O. For fallback mechanisms, see 10.2 Fallback Implementations.

Trait-Based Composition Architecture

The library follows a composition-over-inheritance design pattern. Instead of deep class hierarchies, prompt components and display elements mix in traits to acquire specific capabilities. This approach provides:

• Modularity: Each trait encapsulates a single concern
• Reusability: Multiple components share the same trait implementations
• Flexibility: Components include only the traits they need
• Testability: Traits can be tested independently

The base Prompt class provides core functionality, while traits extend specific components with additional capabilities.

Trait Composition in Components

Sources: src/SelectPrompt.php13 src/Concerns/Colors.php1-208

Trait Catalog

The following traits are available in the Hypervel\Prompts\Concerns namespace:

Trait	Purpose	Primary Users	Page
Scrolling	Navigate through paginated lists with keyboard controls	SelectPrompt, MultiSelectPrompt, SearchPrompt, MultiSearchPrompt, SuggestPrompt	9.1
Colors	Apply ANSI color codes and text styling	Renderer, various components	9.2
Cursor	Control terminal cursor positioning	Prompt base class	9.3
Erase	Clear terminal screen or lines	Prompt base class	9.3
Truncation	Truncate and wrap text to fit terminal width	SearchPrompt, Renderer	9.4
Events	Event-driven interaction and keyboard input handling	Prompt base class (inherited by all prompts)	9.5
TypedValue	Track typed input and cursor position	TextPrompt, TextareaPrompt, PasswordPrompt, SearchPrompt, SuggestPrompt, MultiSearchPrompt	9.6
DrawsBoxes	Render framed containers with borders	Theme renderers	8.2
DrawsScrollbars	Render scrollbar indicators for viewports	Theme renderers	8.2
Themes	Select and instantiate renderers	Prompt components	8
Termwind	Render HTML-like markup to terminal	Renderer base class	8.3
Interactivity	Detect interactive terminal mode	Prompt base class	10.2
FakesInputOutput	Mock terminal I/O for testing	Test utilities	10.1
Fallback	Provide alternative implementations	Various components	10.2

Sources: src/SelectPrompt.php13 src/Concerns/Colors.php1-208

Trait Categories

Traits can be grouped into functional categories based on their primary purpose:

Behavioral Traits

Traits: Scrolling, TypedValue, Events, Fallback

These traits manage how users interact with prompts and how prompts respond to input.

• Scrolling: Manages highlighted, firstVisible indices for navigable lists (SelectPrompt, MultiSelectPrompt, SearchPrompt)
• TypedValue: Tracks user input and cursor position in text-based prompts (TextPrompt, SearchPrompt)
• Events: Observer pattern with on(), emit(), clearListeners() methods (used by Prompt base class)
• Fallback: Conditional alternative implementations for non-interactive environments

Behavioral Trait Usage

Sources: src/SelectPrompt.php13 src/Concerns/Colors.php1-208

Visual Traits

Traits: Colors, Truncation, Cursor, Erase, DrawsBoxes, DrawsScrollbars

These traits control how content is visually formatted and displayed in the terminal.

• Colors: 26 methods for ANSI text/background colors (red, green, blue, etc.), plus styles (bold, dim, underline, strikethrough)
• Truncation: Terminal width-aware text fitting with cursor placement
• Cursor: Hide/show/move cursor operations (hideCursor, showCursor, moveCursor)
• Erase: Line and screen clearing operations (eraseDown, eraseLine)
• DrawsBoxes: Framed containers with titles and borders
• DrawsScrollbars: Viewport scrolling indicators for long lists

Visual Trait Usage

Sources: src/Concerns/Colors.php1-208

Integration Traits

Traits: Themes, Termwind, Interactivity, FakesInputOutput

These traits integrate with external systems and frameworks.

• Themes: Renderer selection and instantiation via getRenderer() method
• Termwind: HTML-like styling via Termwind library integration
• Interactivity: Detects if terminal supports interactive mode via interactive() static property
• FakesInputOutput: Mockery-based testing infrastructure for mocking terminal I/O

Sources: src/SelectPrompt.php13 src/Concerns/Colors.php1-208

Trait Composition Patterns

Components typically use multiple traits together to achieve their functionality. Here are common composition patterns:

Pattern 1: List-Based Selection Prompts

Components that display scrollable lists use the Scrolling trait. Example: SelectPrompt

SelectPrompt Trait Composition

The SelectPrompt constructor at src/SelectPrompt.php55-62 registers key handlers that call methods from the Scrolling trait:

• Key::UP → highlightPrevious()
• Key::DOWN → highlightNext()
• Key::HOME → highlight(0)
• Key::END → highlight(count - 1)
• Key::ENTER → submit()

Sources: src/SelectPrompt.php13-62

Pattern 2: Text Input Prompts

Components that capture typed text use the TypedValue trait. This trait provides properties and methods for managing user text input.

TypedValue Trait Composition

The TypedValue trait's trackTypedValue() method registers comprehensive keyboard handlers for text manipulation, cursor movement, and text deletion. These handlers update the typedValue and cursorPosition properties as the user types.

Sources: src/SelectPrompt.php13

Pattern 3: Search Prompts (Multiple Traits)

Search prompts combine multiple traits for complex interaction: text input, list navigation, and text formatting.

SearchPrompt Multi-Trait Composition

The SearchPrompt class demonstrates trait composition for complex functionality:

1. User types query → TypedValue trait manages input
2. Input triggers filtering → Updates available options
3. User navigates results → Scrolling trait manages selection
4. Options displayed → Truncation trait fits text to terminal width

Sources: src/SelectPrompt.php13

Key Properties and Methods

Each trait exposes properties and methods that become part of the using class. Here are the key interfaces:

Scrolling Trait Interface

The Scrolling trait provides list navigation with viewport management. Used by: SelectPrompt, MultiSelectPrompt, SearchPrompt, MultiSearchPrompt, SuggestPrompt.

Public Properties:

Property	Type	Description
$scroll	int	Number of visible items in viewport
$highlighted	?int	Index of currently highlighted option
$firstVisible	int	Index of first visible item in viewport

Public Methods:

Method	Purpose
initializeScrolling(?int $highlighted)	Initialize scrolling state with optional starting position
highlight(?int $index)	Set highlighted index and adjust viewport
highlightPrevious(int $total, bool $allowNull)	Move highlight up, wrapping if needed
highlightNext(int $total, bool $allowNull)	Move highlight down, wrapping if needed
scrollToHighlighted(int $total)	Adjust viewport to show highlighted item

See src/SelectPrompt.php55-62 for usage example where these methods are called from key event handlers.

Sources: src/SelectPrompt.php13-62

TypedValue Trait Interface

The TypedValue trait manages text input with cursor positioning. Used by: TextPrompt, TextareaPrompt, PasswordPrompt, SearchPrompt, SuggestPrompt, MultiSearchPrompt.

Public Properties:

Property	Type	Description
$typedValue	string	Current typed text content
$cursorPosition	int	Cursor position (0-based index)

Public Methods:

Method	Purpose
trackTypedValue(string $default, bool $submit, ?callable $ignore, bool $allowNewLine)	Initialize input tracking with default value and register key handlers
value()	Return current typed value
addCursor(string $value, int $cursorPosition, ?int $maxWidth)	Insert visual cursor indicator at position

Sources: src/SelectPrompt.php13

Colors Trait Interface

The Colors trait provides ANSI escape sequences for terminal styling. Used by: Renderer base class and various components.

Text Color Methods: black(), red(), green(), yellow(), blue(), magenta(), cyan(), white(), gray()

Background Color Methods: bgBlack(), bgRed(), bgGreen(), bgYellow(), bgBlue(), bgMagenta(), bgCyan(), bgWhite()

Style Methods: reset(), bold(), dim(), italic(), underline(), inverse(), hidden(), strikethrough()

All methods accept a string $text parameter and return the text wrapped in ANSI escape codes. For example:

• $this->red('error') returns "\e<FileRef file-url="https://github.com/hypervel/prompts/blob/2e218156/31merror\\e[39m\"\n- $this->bold('title') returns \"\\e[1mtitle\\e[22m\"\n\nSee [src/Concerns/Colors.php#L12-L207" min=12 max=207 file-path="31merror\e[39m"\n- $this->bold('title')returns"\e[1mtitle\e[22m"`\n\nSee [src/Concerns/Colors.php">Hii for the complete implementation.

Sources: src/Concerns/Colors.php1-208

Trait Dependencies and Method Requirements

Traits may require specific methods to exist on the using class. These dependencies are typically satisfied by the Prompt base class or other traits.

Trait Dependency Graph

Dependency Details:

Trait	Required Methods	Provided By	Purpose
Scrolling	terminal()	Prompt	Access terminal dimensions for viewport calculations
TypedValue	on(), submit()	Events trait, Prompt	Register key handlers and submit on Enter
DrawsBoxes	None	-	Self-contained rendering utilities
DrawsScrollbars	None	-	Self-contained rendering utilities
Colors	None	-	Pure ANSI escape code generation
Cursor	None	-	Pure ANSI escape code generation
Erase	None	-	Pure ANSI escape code generation

The Prompt base class uses the Events, Cursor, Erase, Fallback, and Interactivity traits, making these capabilities available to all prompt subclasses.

Sources: src/SelectPrompt.php11-62 src/Concerns/Colors.php1-208

Code Example: SelectPrompt Trait Usage

The SelectPrompt class demonstrates practical trait composition. It uses the Scrolling trait to manage list navigation.

Class Declaration with Trait:

Initializing Scrolling State: The constructor at src/SelectPrompt.php43-53 initializes the Scrolling trait:

• If a default value is provided, finds its index and calls initializeScrolling($index)
• Calls scrollToHighlighted() to adjust the viewport
• Otherwise calls initializeScrolling(0) to start at the first item

Registering Key Handlers: The constructor at src/SelectPrompt.php55-62 registers key event handlers that call Scrolling trait methods:

Accessing Scrolling Properties: The visible() method at src/SelectPrompt.php96-99 uses $this->firstVisible and $this->scroll properties provided by the trait:

Sources: src/SelectPrompt.php13-99

Design Principles

The trait system follows these design principles:

1. Single Responsibility: Each trait handles one specific concern
2. No State Coupling: Traits don't depend on each other's state directly
3. Method Contracts: Traits may require specific methods on the using class
4. Property Exposure: Traits expose public properties that renderers can access
5. Event-Driven: Interaction traits integrate with the Events system
6. Terminal-Aware: Traits respect terminal dimensions and capabilities

Renderer Integration

Traits often expose properties that renderers consume to format output. The theme system provides renderer contracts that expect specific trait properties:

Renderer Contract	Expected Properties	Source Trait
ScrollingRenderer	highlighted, firstVisible, scroll	Scrolling
Theme methods	Color and styling preferences	Colors
Various renderers	typedValue, cursorPosition	TypedValue

Sources: src/Concerns/Scrolling.php7-8

Next Steps

For detailed documentation of each trait:

• 8.1 Scrolling Lists - List navigation implementation
• 8.2 Typed Value Management - Text input handling
• 8.3 ANSI Colors and Styling - Terminal styling
• 8.4 Text Truncation and Wrapping - Text fitting algorithms
• 8.5 Terminal Control - Cursor and Erase - Low-level terminal operations
• 8.6 Event System and Interactivity - Event-driven architecture

For information on creating components that use these traits, see Interactive Prompts and Display Components.