Termwind Integration

Purpose and Scope

This document explains how the hypervel/prompts library integrates with the Termwind library to provide advanced terminal styling capabilities. It covers the Termwind trait implementation, the HTML-like styling syntax, and escape sequence handling mechanisms.

For information about the base rendering infrastructure, see The Base Renderer. For details on how specific prompt renderers use these styling capabilities, see Prompt-Specific Renderers.

---

Overview

Termwind is a third-party library that allows developers to style terminal output using HTML-like syntax. The hypervel/prompts library integrates Termwind as a core dependency to enable rich terminal formatting beyond basic ANSI color codes.

Dependency Declaration

The library declares Termwind as a required dependency with version ^2.0:

Dependency Specification

Package	Version	Purpose
nunomaduro/termwind	^2.0	HTML-like terminal styling

Sources: composer.json26

---

Architecture Overview

The following diagram illustrates how Termwind integrates into the rendering pipeline:

Termwind Integration in Rendering Pipeline

Sources: src/Concerns/Termwind.php1-27 src/Themes/Default/Renderer.php1-104

---

The Termwind Trait

The Termwind trait is located at src/Concerns/Termwind.php and provides two methods for working with Termwind styling.

Trait Structure

Sources: src/Concerns/Termwind.php12-27

Namespace and Imports

The trait is defined in the Hypervel\Prompts\Concerns namespace and imports two functions from the Termwind library:

• Termwind\render() - Renders HTML-like markup to the configured output
• Termwind\renderUsing() - Configures the output destination for rendering

Sources: src/Concerns/Termwind.php5-10

---

The termwind() Method

The termwind() method is the primary interface for rendering HTML-like markup to ANSI-styled terminal output.

Method Signature

protected function termwind(string $html): string

Rendering Flow

The following diagram shows the complete rendering flow through the termwind() method:

Termwind Rendering Flow

protected function restoreEscapeSequences(string $string): string

This method uses a regular expression to convert bracket-only escape sequences back to proper ANSI format:

| Input Format | Output Format | Description |
|--------------|---------------|-------------|
| `[32m` | `\e[32m` | Bracket-only notation → Proper ANSI |
| `[1;32m` | `\e[1;32m` | Multi-parameter sequences |
| `[0m` | `\e[0m` | Reset sequences |

**Conversion Process**

```mermaid
graph LR
 Input["Input String<br/>[32mGreen[0m"]
 Regex["Regex Pattern<br/>/\[(\d+)m/"]
 Replace["Replace with<br/>\e[\1m"]
 Output["Output String<br/>\e[32mGreen\e[0m"]
 
 Input --> Regex
 Regex --> Replace
 Replace --> Output

Sources: src/Concerns/Termwind.php23-26

Regular Expression Breakdown

The pattern /\<FileRef file-url="https://github.com/hypervel/prompts/blob/2e218156/(\\d+)m/ matches#LNaN-LNaN" NaN file-path="(\d+)m/` matches">Hii

---

BufferedConsoleOutput

The BufferedConsoleOutput class is a custom output implementation that captures Termwind's rendered output in memory rather than writing directly to the terminal.

BufferedConsoleOutput Usage Pattern

This approach allows the trait to:

1. Capture rendered output as a string
2. Post-process escape sequences
3. Return the final styled string to the caller

Sources: src/Concerns/Termwind.php16

---

HTML-like Styling Syntax

While the trait itself doesn't define the HTML syntax, it enables the use of Termwind's extensive styling capabilities. The Termwind library supports:

Common Styling Constructs

Syntax Example	Purpose
<div class="text-green">	Green text color
<div class="bg-red">	Red background
<div class="font-bold">	Bold text weight
<div class="underline">	Underlined text
<span class="px-2">	Padding and spacing
<div class="ml-2">	Margin and layout

Advantages Over ANSI Codes

Termwind's HTML-like syntax provides several benefits:

1. Readability - HTML-like markup is more intuitive than raw ANSI codes
2. Composition - Styles can be easily combined through CSS-like classes
3. Abstraction - Decouples style intent from terminal implementation details
4. Consistency - Provides a unified styling language across the application

---

Integration with the Renderer System

The Termwind trait is designed to be used by renderer classes, though the provided base Renderer class at src/Themes/Default/Renderer.php uses the Colors trait instead for simpler ANSI color application.

Typical Usage Pattern

Comparison with Colors Trait

The base Renderer class uses both Colors and Truncation traits but not Termwind:

Trait	Purpose	Used in Base Renderer
Colors	Simple ANSI color methods	✓ Yes
Truncation	Text width management	✓ Yes
Termwind	HTML-like styling	✗ No

This suggests that Termwind is available for custom renderer implementations that need more sophisticated styling capabilities beyond basic colors.

Sources: src/Themes/Default/Renderer.php14-15

---

Usage Scenarios

When to Use the Termwind Trait

The Termwind trait is appropriate when:

1. Complex Layouts - Building multi-column or grid-based terminal UIs
2. Rich Formatting - Combining multiple style attributes (bold + underline + color)
3. Responsive Design - Using Termwind's built-in responsive classes
4. Consistent Styling - Maintaining a unified design system across components

When to Use Direct ANSI Codes

Direct ANSI codes (via the Colors trait) are sufficient when:

1. Simple Styling - Basic color changes without complex layout
2. Performance Critical - Avoiding the overhead of HTML parsing
3. Fine Control - Precise character-by-character positioning

---

Implementation File Reference

Component	File Path	Lines
Termwind trait	src/Concerns/Termwind.php	12-27
termwind() method	src/Concerns/Termwind.php	14-21
restoreEscapeSequences() method	src/Concerns/Termwind.php	23-26
Base Renderer	src/Themes/Default/Renderer.php	12-104
Dependency declaration	composer.json	26

---

Summary

The Termwind trait provides a clean integration layer between the hypervel/prompts rendering system and the Termwind library. It encapsulates the complexity of HTML-to-ANSI conversion and escape sequence handling, allowing renderer implementations to use expressive HTML-like markup for terminal styling.

Key takeaways:

• The termwind() method converts HTML-like strings to ANSI escape sequences
• BufferedConsoleOutput captures rendered output for post-processing
• restoreEscapeSequences() fixes escape character encoding
• The trait enables sophisticated terminal styling beyond basic ANSI colors

Sources: src/Concerns/Termwind.php1-27 composer.json21-27