Text Truncation

This page documents the Truncation trait, which provides terminal width-aware text fitting functionality. The trait ensures text content doesn't exceed terminal boundaries by intelligently truncating strings and managing cursor position within truncated text.

For information about terminal cursor control (hide/show/move operations), see Terminal Control - Cursor and Erase. For ANSI color and styling capabilities, see ANSI Colors and Styling.

---

Purpose and Scope

The Truncation trait addresses a fundamental challenge in CLI applications: text content must fit within the physical constraints of the terminal window. Unlike web interfaces with automatic wrapping and scrolling, terminal applications must explicitly handle text overflow to prevent visual corruption and ensure readable output.

This trait provides two primary capabilities:

1. Simple Truncation: Cutting text to fit within a specified width
2. Cursor-Aware Truncation: Managing cursor position within truncated text for interactive input

The trait is used by both rendering components (to fit display text) and interactive prompts (to manage user input with cursor positioning).

Sources: src/Themes/Default/Renderer.php1-104 src/SearchPrompt.php1-142

---

Architecture Overview

The following diagram shows how the Truncation trait integrates into the system's component hierarchy:

Key Components:

Component	Role	Truncation Usage
Renderer (base class)	Theme rendering foundation	Uses truncate() for hint messages to fit terminal width
SearchPrompt	Interactive search with autocomplete	Uses truncate() and addCursor() for input display with cursor
Terminal::cols()	Terminal width detection	Provides maximum width for truncation calculations

Sources: src/Themes/Default/Renderer.php14-15 src/SearchPrompt.php12-14

---

Trait Composition Pattern

The Truncation trait follows the system's trait-based architecture for cross-cutting concerns. Classes compose multiple traits to gain specific capabilities:

In src/Themes/Default/Renderer.php14-15 the base renderer uses both Colors and Truncation traits:

In src/SearchPrompt.php12-14 SearchPrompt composes three traits including Truncation:

Sources: src/Themes/Default/Renderer.php14-15 src/SearchPrompt.php12-14

---

Simple Text Truncation

The primary method provided by the trait is truncate(), which fits text within a specified width. This is demonstrated in the renderer's hint display logic:

Renderer Hint Method Implementation

In src/Themes/Default/Renderer.php68-77 hint messages are truncated to fit the terminal width:

Width Calculation Pattern:

• $this->prompt->terminal()->cols() retrieves the terminal width in columns
• Subtract padding (6 characters: 2 spaces prefix + 4 character buffer)
• Pass resulting width to truncate() method

This ensures hint text never exceeds terminal boundaries, preventing line wrapping that would corrupt the display.

Sources: src/Themes/Default/Renderer.php68-77

---

Cursor-Aware Truncation in Interactive Prompts

Interactive prompts with text input require more sophisticated truncation that maintains cursor position visibility. The SearchPrompt demonstrates this with its valueWithCursor() method.

SearchPrompt Value Display

The following diagram shows how SearchPrompt handles text display with cursor positioning:

Implementation in Code

From src/SearchPrompt.php73-86:

Behavior Matrix:

Condition	Method Used	Purpose
Option highlighted + empty input	truncate(placeholder)	Show dimmed placeholder for selected option
Option highlighted + has input	truncate(typedValue)	Show typed search query (cursor hidden)
Typing mode + empty input	addCursor(placeholder, 0)	Show cursor at start of placeholder
Typing mode + has input	addCursor(typedValue, cursorPosition)	Show cursor at current position in input

The addCursor() method (from the Truncation trait) intelligently positions a visual cursor within truncated text, ensuring the cursor remains visible even when text exceeds the maximum width.

Sources: src/SearchPrompt.php73-86

---

Terminal Width Integration

Both truncation scenarios integrate with the terminal width detection system to calculate appropriate truncation boundaries:

Example Width Calculations:

Context	Terminal Width	Padding	Max Text Width	Calculation
Renderer hints	80 cols	6 chars	74 chars	cols() - 6
Search input	100 cols	Variable	Depends on prompt width	Passed by renderer
Multi-line text	120 cols	Varies by theme	Theme-dependent	Calculated per line

The $maxWidth parameter passed to truncation methods is dynamically calculated based on:

1. Current terminal dimensions via terminal()->cols()
2. UI element padding and margins
3. Theme-specific layout requirements

Sources: src/Themes/Default/Renderer.php74 src/SearchPrompt.php73-86

---

Usage Patterns Across Components

The following table summarizes how different components utilize the Truncation trait:

Component	File	Usage Pattern	Purpose
Base Renderer	src/Themes/Default/Renderer.php	truncate() in hint() method (line 74)	Fit hint messages within terminal width
SearchPrompt	src/SearchPrompt.php	truncate() in valueWithCursor() (lines 77-78)	Display search input without cursor
SearchPrompt	src/SearchPrompt.php	addCursor() in valueWithCursor() (lines 82, 85)	Display input with visible cursor
Placeholder handling	src/SearchPrompt.php	Combined with dim() styling (lines 77, 82)	Show dimmed placeholder text

Common Patterns:

1. Renderer Pattern: Calculate maxWidth = terminal()->cols() - padding, then truncate
2. Interactive Pattern: Use addCursor() when cursor must be visible, truncate() when cursor is hidden
3. Placeholder Pattern: Combine truncation with color styling for visual hierarchy

Sources: src/Themes/Default/Renderer.php68-77 src/SearchPrompt.php73-86

---

Integration with Other Traits

The Truncation trait frequently works alongside other traits to achieve complete functionality:

Trait Collaboration Examples:

1. TypedValue + Truncation: In src/SearchPrompt.php73-86 cursorPosition from TypedValue trait is passed to addCursor() from Truncation trait

2. Colors + Truncation: In src/SearchPrompt.php77-82 dim() from Colors trait styles the result of truncate() and addCursor()

3. Scrolling + Truncation: While Scrolling manages vertical viewport boundaries, Truncation manages horizontal width constraints

Sources: src/SearchPrompt.php12-14 src/SearchPrompt.php73-86 src/Themes/Default/Renderer.php14-15

---

Summary

The Truncation trait provides essential terminal width-aware text fitting for the prompts library:

Core Capabilities:

• truncate(text, maxWidth): Simple text truncation to fit width
• addCursor(text, cursorPosition, maxWidth): Cursor-aware truncation for interactive input

Primary Use Cases:

1. Renderers: Truncate display text (hints, messages) to prevent overflow
2. Interactive Prompts: Manage user input display with cursor visibility

Integration Points:

• Works with Terminal::cols() for dynamic width detection
• Collaborates with Colors trait for styled truncated text
• Complements TypedValue trait for cursor position management
• Coordinates with Scrolling trait for complete viewport control

The trait exemplifies the library's composition-based architecture, providing focused functionality that combines with other traits to deliver complex interactive experiences while maintaining clean separation of concerns.

Sources: src/Themes/Default/Renderer.php1-104 src/SearchPrompt.php1-142