Prompt-Specific Renderers

Purpose and Scope

This document details the concrete renderer implementations for specific prompt types in the hypervel/prompts library. These renderers are responsible for converting prompt state into formatted terminal output using state-based rendering patterns.

Covered in this document:

• SelectPromptRenderer - Renders single-selection prompts
• MultiSelectPromptRenderer - Renders multi-selection prompts with checkbox indicators
• SearchPromptRenderer - Renders dynamic search prompts with input field

For information about the base rendering infrastructure and utilities, see The Base Renderer. For Termwind styling integration used by these renderers, see Termwind Integration. For the prompts themselves, see Selection Prompts and Search and Suggest Prompts.

---

Renderer Architecture

Prompt-specific renderers implement a consistent architecture pattern that separates visual presentation from prompt business logic. Each renderer is invoked by its corresponding prompt during the rendering phase of the prompt lifecycle.

Class Structure and Composition

Sources: src/Themes/Default/SelectPromptRenderer.php1-96 src/Themes/Default/MultiSelectPromptRenderer.php1-122 src/Themes/Default/SearchPromptRenderer.php1-135

Renderer	Extends	Implements	Uses Traits
SelectPromptRenderer	Renderer	Scrolling	DrawsBoxes, DrawsScrollbars
MultiSelectPromptRenderer	Renderer	Scrolling	DrawsBoxes, DrawsScrollbars
SearchPromptRenderer	Renderer	Scrolling	DrawsBoxes, DrawsScrollbars

---

The Invocation Pattern

All prompt-specific renderers implement a callable interface through the __invoke() magic method, which receives the corresponding prompt instance and returns a formatted string for terminal output.

Method Signature

This design enables renderers to act as invokable objects, allowing prompts to call them directly:

State-Based Rendering with Match Expressions

Each renderer uses PHP's match expression to implement state-based rendering, producing different visual representations for each prompt state:

State	Description	Visual Treatment
'submit'	User completed prompt	Dimmed label, final value displayed
'cancel'	User cancelled (Ctrl+C)	Red border, strikethrough, error message
'error'	Validation failed	Yellow border, warning message
'active'/default	Currently interacting	Cyan highlights, hint text

Sources: src/Themes/Default/SelectPromptRenderer.php18-55 src/Themes/Default/MultiSelectPromptRenderer.php18-56 src/Themes/Default/SearchPromptRenderer.php18-66

---

SelectPromptRenderer

The SelectPromptRenderer renders single-selection prompts with radio button-style indicators (● filled circle, ○ empty circle).

Invocation Method Structure

Sources: src/Themes/Default/SelectPromptRenderer.php18-55

State Rendering Details

Submit State

src/Themes/Default/SelectPromptRenderer.php23-27

Displays the finalized selection in a minimal format:

• Label is dimmed using $this->dim()
• Label is truncated to $prompt->terminal()->cols() - 6
• Selected option label displayed via $prompt->label()
• Wrapped in a box with $this->box()

Cancel State

src/Themes/Default/SelectPromptRenderer.php29-35

Indicates cancellation with visual emphasis:

• Red border color applied to box
• Options rendered with strikethrough styling
• Error message appended with ->error($prompt->cancelMessage)

Error State

src/Themes/Default/SelectPromptRenderer.php37-43

Shows validation failure:

• Yellow border color on box
• Options remain visible
• Warning message displayed with truncated error text

Active State

src/Themes/Default/SelectPromptRenderer.php45-54

The default interactive state:

• Cyan-colored label
• Full option list rendered
• Conditional hint or newline for error spacing

Option Rendering

The renderOptions() method src/Themes/Default/SelectPromptRenderer.php61-87 handles the display of individual options:

Option Indicator Logic:

Condition	Indicator	Color	Example
Highlighted (active)	› ●	Cyan	› ● Option 1
Not highlighted	○	Dim	○ Option 2
Cancelled & highlighted	› ●	Dim + strikethrough	› ● ~~Option 1~~
Cancelled & not highlighted	○	Dim + strikethrough	○ ~~Option 2~~

Sources: src/Themes/Default/SelectPromptRenderer.php61-87

Reserved Lines

The reservedLines() method src/Themes/Default/SelectPromptRenderer.php92-95 returns 5, indicating the number of terminal lines reserved for non-scrollable content (label, box borders, hint/error).

---

MultiSelectPromptRenderer

The MultiSelectPromptRenderer extends selection rendering with checkbox indicators (◼ checked, ◻ unchecked) and displays a selection count.

Key Differences from SelectPromptRenderer

Aspect	SelectPromptRenderer	MultiSelectPromptRenderer
Indicator	Radio (●/○)	Checkbox (◼/◻)
Selection tracking	Single highlighted	Array of selected values
Info display	None	Selection count when scrolling
Method calls	$prompt->label()	$prompt->labels() (plural)

State Rendering Variations

Submit State

src/Themes/Default/MultiSelectPromptRenderer.php21-25

Calls renderSelectedOptions() instead of $prompt->label() to display all selected items:

The method src/Themes/Default/MultiSelectPromptRenderer.php103-113 iterates over selected labels, truncating each to terminal width minus 6 characters. If no selections, displays "None" in gray.

Error and Active States with Selection Count

src/Themes/Default/MultiSelectPromptRenderer.php40-48

Both states conditionally display selection count in the box info area:

This appears only when options exceed scroll limit, providing feedback on hidden selections.

Option Rendering with Checkboxes

The renderOptions() method src/Themes/Default/MultiSelectPromptRenderer.php61-98 implements more complex logic to handle both highlighting and selection states:

Four-State Rendering Logic:

src/Themes/Default/MultiSelectPromptRenderer.php85-90

Active	Selected	Render
✓	✓	{cyan('› ◼')} {label}
✓	✗	{cyan('›')} ◻ {label}
✗	✓	{cyan('◼')} {dim($label)}
✗	✗	{dim('◻')} {dim($label)}

Sources: src/Themes/Default/MultiSelectPromptRenderer.php1-122

---

SearchPromptRenderer

The SearchPromptRenderer is the most complex renderer, handling dynamic search input, asynchronous search states, and result display.

Unique State: 'searching'

Unlike other renderers, SearchPromptRenderer includes a special 'searching' state src/Themes/Default/SearchPromptRenderer.php46-52 that displays while search operations are in progress:

Input Field Rendering

The renderer must display the current search input with cursor positioning:

Active State Input

src/Themes/Default/SearchPromptRenderer.php57

Uses $prompt->valueWithCursor($maxWidth) to render the input field with a visible cursor indicator.

Searching State Input

src/Themes/Default/SearchPromptRenderer.php49

Uses valueWithCursorAndSearchIcon() src/Themes/Default/SearchPromptRenderer.php72-79 which adds a cyan ellipsis (…) indicator:

This provides visual feedback that search is actively processing.

Dynamic Option Rendering

The renderOptions() method src/Themes/Default/SearchPromptRenderer.php105-126 handles three distinct scenarios:

Rendering Logic:

src/Themes/Default/SearchPromptRenderer.php107-109

When matches exist, renders them with scrollbar similar to SelectPromptRenderer, but with simpler formatting (no radio buttons).

Dropdown Spacing

The spaceForDropdown() method src/Themes/Default/SearchPromptRenderer.php84-100 manages vertical spacing to prevent UI jumping when search results appear:

This pre-allocates space when the search field is empty, ensuring consistent positioning.

Reserved Lines

Returns 7 src/Themes/Default/SearchPromptRenderer.php131-134 accounting for the additional input field row compared to simple selection prompts.

Sources: src/Themes/Default/SearchPromptRenderer.php1-135

---

Common Patterns

Trait Composition

All three renderers use identical trait composition src/Themes/Default/SelectPromptRenderer.php12-13:

• DrawsBoxes: Provides box() method for framed containers with optional title, info, and color
• DrawsScrollbars: Provides scrollbar() method for viewport management with scroll indicators

Scrolling Interface Implementation

Each renderer implements Scrolling interface src/Themes/Default/SelectPromptRenderer.php10 requiring:

This method informs the scrolling system how many lines are consumed by non-scrollable content:

Renderer	Reserved Lines	Components
SelectPromptRenderer	5	Box (3) + hint/error (1) + margin (1)
MultiSelectPromptRenderer	5	Box (3) + hint/error (1) + margin (1)
SearchPromptRenderer	7	Box (4) + input field (1) + hint/error (1) + margin (1)

Terminal Width Awareness

All renderers calculate a consistent maximum width for content:

This reserves 6 columns for box borders, indicators, and padding. Content is truncated using $this->truncate($text, $maxWidth) inherited from the base Renderer class.

Option List Processing Pipeline

Each renderer follows this pipeline:

1. Get visible options from prompt's scrolling viewport
2. Map over options to format with indicators
3. Wrap in scrollbar decorations
4. Join with newlines

Sources: src/Themes/Default/SelectPromptRenderer.php63-86 src/Themes/Default/MultiSelectPromptRenderer.php63-97 src/Themes/Default/SearchPromptRenderer.php111-125

---

State Machine for Rendering

The rendering state machine is consistent across all renderers, with SearchPromptRenderer adding an additional intermediate state:

Sources: src/Themes/Default/SelectPromptRenderer.php22-54 src/Themes/Default/MultiSelectPromptRenderer.php20-55 src/Themes/Default/SearchPromptRenderer.php22-66

---

Code Entity Map

Mapping natural language concepts to concrete code entities:

Concept	Code Entity	Location
Select renderer	SelectPromptRenderer	src/Themes/Default/SelectPromptRenderer.php10
Multi-select renderer	MultiSelectPromptRenderer	src/Themes/Default/MultiSelectPromptRenderer.php10
Search renderer	SearchPromptRenderer	src/Themes/Default/SearchPromptRenderer.php10
Render method	__invoke(Prompt $prompt): string	src/Themes/Default/SelectPromptRenderer.php18
State branching	match ($prompt->state)	src/Themes/Default/SelectPromptRenderer.php22
Option list	renderOptions(Prompt): string	src/Themes/Default/SelectPromptRenderer.php61
Selected items	renderSelectedOptions(MultiSelectPrompt): string	src/Themes/Default/MultiSelectPromptRenderer.php103
Box drawing	$this->box()	Via DrawsBoxes trait
Scrollbar	$this->scrollbar()	Via DrawsScrollbars trait
Radio indicator	'●' / '○'	src/Themes/Default/SelectPromptRenderer.php78-79
Checkbox indicator	'◼' / '◻'	src/Themes/Default/MultiSelectPromptRenderer.php86-89
Line reservation	reservedLines(): int	src/Themes/Default/SelectPromptRenderer.php92
Search state	'searching'	src/Themes/Default/SearchPromptRenderer.php46
Search input	valueWithCursor()	Called from prompt
Dropdown spacing	spaceForDropdown()	src/Themes/Default/SearchPromptRenderer.php84

---

Summary

Prompt-specific renderers implement a consistent architecture pattern:

1. Invokable Objects: __invoke() method receives prompt instance, returns formatted string
2. State-Based Rendering: match expressions handle submit/cancel/error/active states
3. Trait Composition: DrawsBoxes and DrawsScrollbars provide visual primitives
4. Scrolling Integration: Implement Scrolling interface with reservedLines()
5. Option Rendering: Protected methods format visible options with appropriate indicators
6. Terminal Awareness: Truncation and width calculations respect terminal dimensions

The separation of rendering from business logic allows themes to customize visual presentation without modifying prompt behavior, while the consistent pattern across renderers ensures maintainability and predictable behavior.