Theming and Rendering System

Purpose and Scope

This document explains the rendering architecture of hypervel/prompts: how prompt classes delegate visual presentation to themed renderers, enabling separation of business logic from presentation. The system implements state-based rendering through match expressions, trait composition for reusable visual components, and a fluent API for accumulating terminal output.

For details about specific renderer implementations, see Prompt-Specific Renderers. For information about the Renderer base class API, see The Base Renderer. For Termwind styling integration, see Termwind Integration.

---

Architecture Overview

The rendering system separates prompt logic from visual presentation through a delegation pattern. Each prompt class has a corresponding renderer that implements state-based rendering logic. This architecture allows:

1. Theming: Multiple visual presentations of the same prompt logic
2. Testability: Prompts can be tested independently of rendering
3. Maintainability: Visual changes don't affect prompt behavior
4. Composability: Renderers use traits for reusable visual components

Rendering Architecture Diagram

Sources: src/Themes/Default/Renderer.php1-104 src/Themes/Default/SelectPromptRenderer.php1-96

---

Prompt-to-Renderer Delegation

Prompts delegate rendering to theme-specific renderer classes through the renderTheme() method called during the prompt lifecycle. The base Prompt class instantiates the appropriate renderer and invokes it with the prompt instance as an argument.

Delegation Pattern

Each prompt type has a corresponding renderer class that implements an __invoke() method accepting the prompt instance. The renderer reads the prompt's state and properties to generate appropriate terminal output.

Prompt Class	Renderer Class	Location
SelectPrompt	SelectPromptRenderer	src/Themes/Default/SelectPromptRenderer.php
MultiSelectPrompt	MultiSelectPromptRenderer	src/Themes/Default/MultiSelectPromptRenderer.php
SearchPrompt	SearchPromptRenderer	src/Themes/Default/SearchPromptRenderer.php
TextPrompt	TextPromptRenderer	src/Themes/Default/TextPromptRenderer.php
TextareaPrompt	TextareaPromptRenderer	src/Themes/Default/TextareaPromptRenderer.php

Renderer Invocation Flow

Sources: src/Themes/Default/Renderer.php25-27 src/Themes/Default/SelectPromptRenderer.php18-56

---

State-Based Rendering

Renderers implement state-based rendering using PHP's match expressions. Each prompt has a state property that transitions through lifecycle phases: 'initial', 'active', 'error', 'submit', and 'cancel'. The renderer generates different output for each state.

State Rendering in SelectPromptRenderer

The SelectPromptRenderer::__invoke() method demonstrates state-based rendering:

src/Themes/Default/SelectPromptRenderer.php18-56

State Rendering Characteristics

State	Visual Treatment	Purpose
'submit'	Dimmed label, final value shown	Display confirmed selection
'cancel'	Red box, strikethrough options, error icon	Show cancellation
'error'	Yellow box, warning message below	Display validation failure
default (active)	Cyan box, interactive options, hint text	Active user interaction

State-Specific Rendering Diagram

Sources: src/Themes/Default/SelectPromptRenderer.php22-55 src/Themes/Default/Renderer.php52-77

---

The Renderer Base Class

The abstract Renderer class at src/Themes/Default/Renderer.php12-104 provides foundational rendering utilities used by all prompt renderers.

Core Responsibilities

1. Output Accumulation: Maintains a $output property that accumulates text incrementally
2. Text Formatting: Provides methods for common message types (warnings, errors, hints)
3. Trait Composition: Composes Colors and Truncation traits for styling and text fitting
4. String Conversion: Implements Stringable interface for final output generation

Key Methods

Method	Purpose	Return Type
line(string)	Append a line with newline	self
newLine(int)	Append blank lines	self
warning(string)	Render warning message with ⚠ icon	self
error(string)	Render error message with ⚠ icon (red)	self
hint(string)	Render hint text in gray	self
when(mixed, callable, ?callable)	Conditional rendering	self
__toString()	Convert accumulated output to final string	string

Output Accumulation Pattern

src/Themes/Default/Renderer.php32-46

This fluent API allows chaining method calls to build output incrementally:

Sources: src/Themes/Default/Renderer.php12-104

---

Trait Composition for Visual Components

Renderers use trait composition to implement reusable visual components. This avoids code duplication and allows mix-and-match composition of rendering capabilities.

Rendering Traits Architecture

Trait Usage in SelectPromptRenderer

src/Themes/Default/SelectPromptRenderer.php10-13

Rendering Trait Responsibilities

Trait	Location	Purpose	Key Methods
Colors	Base renderer	ANSI color codes	cyan(), red(), yellow(), dim(), gray()
Truncation	Base renderer	Terminal width-aware text fitting	truncate(string, width)
DrawsBoxes	Prompt renderers	Framed visual containers	box(title, body, color)
DrawsScrollbars	List-based renderers	Scrollbar indicators for lists	scrollbar(items, first, scroll, total, width, color)

Sources: src/Themes/Default/Renderer.php14-15 src/Themes/Default/SelectPromptRenderer.php12-13

---

Rendering Pipeline Execution

The complete rendering pipeline flows from prompt state through the renderer to terminal output, with multiple transformation and styling steps.

Complete Rendering Pipeline

Sources: src/Themes/Default/SelectPromptRenderer.php18-86 src/Themes/Default/Renderer.php98-103

---

Theme Organization

The rendering system is organized by theme, allowing multiple visual presentations. The default theme resides at src/Themes/Default/ and provides the standard visual style for all prompts.

Default Theme Structure

src/Themes/Default/
├── Concerns/
│ ├── DrawsBoxes.php # box() method implementation
│ └── DrawsScrollbars.php # scrollbar() method implementation
├── Renderer.php # Abstract base class
├── SelectPromptRenderer.php
├── MultiSelectPromptRenderer.php
├── SearchPromptRenderer.php
├── MultiSearchPromptRenderer.php
├── TextPromptRenderer.php
├── TextareaPromptRenderer.php
├── PasswordPromptRenderer.php
├── ConfirmPromptRenderer.php
├── SuggestPromptRenderer.php
├── PausePromptRenderer.php
├── ProgressRenderer.php
└── TableRenderer.php

Renderer Naming Convention

Renderer classes follow the pattern: {PromptName}Renderer where {PromptName} matches the corresponding prompt class name. For example:

• SelectPrompt → SelectPromptRenderer
• MultiSelectPrompt → MultiSelectPromptRenderer
• TextPrompt → TextPromptRenderer

Implementing Custom Themes

To implement a custom theme:

1. Create a new directory: src/Themes/CustomName/
2. Extend the base Renderer class from Default/Renderer.php
3. Implement renderer classes for each prompt type
4. Override __invoke() methods with custom rendering logic
5. Configure the prompt system to use the custom theme

Sources: src/Themes/Default/SelectPromptRenderer.php5-10 src/Themes/Default/Renderer.php5-12

---

Integration with Prompt Lifecycle

Renderers are invoked during specific phases of the prompt lifecycle. The base Prompt class manages when rendering occurs, typically during the main input loop and state transitions.

Rendering Invocation Points

1. Initial Render: When prompt first displays
2. Input Loop: After each keystroke or state change
3. Validation: When errors occur
4. Submission: When user confirms input
5. Cancellation: When user cancels prompt

The renderer has access to all prompt properties and methods, allowing it to read current state, options, user input, and terminal dimensions to generate appropriate output.

Terminal-Aware Rendering

Renderers use $prompt->terminal()->cols() to obtain terminal width for responsive text truncation:

src/Themes/Default/SelectPromptRenderer.php20-26

This ensures output fits within the terminal viewport and handles window resizing gracefully.

Sources: src/Themes/Default/SelectPromptRenderer.php20-86 src/Themes/Default/Renderer.php74-76