Typed Value Management

Purpose and Scope

The TypedValue trait provides real-time tracking of user text input and cursor position for interactive prompts that require character-by-character input management. This trait is primarily used by search-based prompts where the prompt needs to maintain both the current input string and the cursor's position within that string.

This document covers the TypedValue trait's functionality and its integration with prompts. For general search prompt behavior, see Search and Suggest Prompts. For cursor display control, see Terminal Control - Cursor and Erase.

---

Overview

The TypedValue trait solves the problem of maintaining synchronized state between what the user has typed and where their cursor is positioned within that text. This is essential for prompts that need to:

• Display user input as it's being typed
• Support cursor movement within the input (left/right arrow keys)
• Show a visual cursor indicator
• Allow text insertion and deletion at any position
• Provide access to the current input value for searching or validation

Sources: src/SearchPrompt.php1-141

---

Trait Composition in SearchPrompt

The SearchPrompt class uses the TypedValue trait alongside other behavioral traits to provide comprehensive search functionality:

Trait	Purpose	Properties/Methods Used
TypedValue	Text input tracking	$typedValue, $cursorPosition, trackTypedValue()
Scrolling	Viewport management	$highlighted, $firstVisible, initializeScrolling()
Truncation	Text fitting	truncate(), addCursor()

Sources: src/SearchPrompt.php10-14

---

Initialization with trackTypedValue()

The trackTypedValue() method is called during prompt construction to configure input tracking behavior. It accepts parameters that control how input events should be handled:

SearchPrompt Initialization Pattern:

src/SearchPrompt.php42

Parameters

Parameter	Type	Purpose
submit	bool	When false, Enter key triggers search instead of submission
ignore	Closure	Callback determining which keys should not affect typedValue

The ignore closure receives the pressed key and returns true if that key should be ignored for typed value tracking. In SearchPrompt, HOME/END/CTRL_A/CTRL_E are ignored when a match is highlighted, allowing these keys to navigate the results list instead of moving the cursor within the input text.

Sources: src/SearchPrompt.php42

---

Core Properties

The TypedValue trait manages two primary state properties:

typedValue

The typedValue property stores the complete string that the user has typed. This property is updated in real-time as the user enters characters, deletes text, or pastes content.

Usage in SearchPrompt:

Method	Line	Purpose
valueWithCursor()	76-78	Display logic for empty vs. non-empty input
valueWithCursor()	81-85	Cursor positioning within typed text
searchValue()	117	Public accessor for current input
matches()	99	Passed to search options closure

Sources: src/SearchPrompt.php76-86 src/SearchPrompt.php115-118 src/SearchPrompt.php99

cursorPosition

The cursorPosition property tracks the zero-based index of the cursor within the typedValue string. This enables cursor movement within the text and proper visual cursor placement.

Usage in SearchPrompt:

src/SearchPrompt.php85

The cursor position is used with the addCursor() method (from Truncation trait) to render a visual cursor at the correct location within the displayed text.

Sources: src/SearchPrompt.php85

---

Input Value Display with Cursor

The valueWithCursor() method demonstrates how typedValue and cursorPosition work together to create the visual representation of user input:

Implementation Logic:

Condition	Display Behavior	Cursor Visible
Result highlighted + empty input	Dimmed placeholder	No
Result highlighted + has input	Typed value	No
No highlight + empty input	Dimmed placeholder	Yes (position 0)
No highlight + has input	Typed value	Yes (at cursor position)

Sources: src/SearchPrompt.php73-86

---

Integration with Search Workflow

The TypedValue trait enables SearchPrompt's real-time search behavior by maintaining the search query state:

Search State Reset

When the user types (triggering the search() method), the prompt resets its search state:

src/SearchPrompt.php60-68

• Sets state to 'searching'
• Clears highlighted result ($this->highlighted = null)
• Clears matches cache ($this->matches = null)
• Resets scroll position ($this->firstVisible = 0)

Sources: src/SearchPrompt.php60-68 src/SearchPrompt.php93-100

---

Key Event Handling Pattern

The TypedValue trait integrates with SearchPrompt's key event system. The trait handles character input, while SearchPrompt's event listeners handle navigation and submission:

Key Routing Rules:

Key	Condition	Behavior	Handler
Character keys	Always	Update typedValue, trigger search	TypedValue
Backspace/Delete	Always	Update typedValue, trigger search	TypedValue
Arrow Up/Down	Always	Navigate results list	SearchPrompt
HOME/END	Highlighted ≠ null	Jump to first/last result	SearchPrompt
HOME/END	Highlighted = null	Move cursor to start/end of input	TypedValue (via ignore)
Enter	Highlighted ≠ null	Submit selected result	SearchPrompt
Enter	Highlighted = null	Trigger search	SearchPrompt
Left/Right	Always	Clear highlight, allow cursor movement	SearchPrompt → TypedValue

Sources: src/SearchPrompt.php42-54

---

Dual-Mode Behavior: Typing vs. Navigating

The TypedValue trait enables SearchPrompt's dual-mode interaction model where the prompt switches between "typing mode" and "navigation mode":

Mode Detection

The mode is determined by the highlighted property value:

Property State	Mode	typedValue Behavior	cursorPosition Behavior
highlighted = null	Typing Mode	Updates on keypress	Updates on cursor movement
highlighted ≥ 0	Navigation Mode	Frozen	Ignored for display

Sources: src/SearchPrompt.php46-54 src/SearchPrompt.php75-86

---

Public API for Value Access

SearchPrompt exposes the typed value through a public method:

searchValue()

src/SearchPrompt.php115-118

Returns the current search query string (the typedValue). This method provides read-only access to the current input state and is used by renderers to display the search query.

Usage Example in Rendering Context:

Sources: src/SearchPrompt.php115-118

---

Summary

The TypedValue trait provides essential input tracking functionality for interactive text prompts:

Feature	Property/Method	Purpose
Input Storage	typedValue	Maintains complete user input string
Cursor Tracking	cursorPosition	Tracks cursor location within input
Initialization	trackTypedValue()	Configures input handling behavior
Conditional Ignoring	ignore parameter	Allows keys to bypass input tracking

The trait integrates seamlessly with SearchPrompt's navigation system through the ignore callback mechanism, enabling context-sensitive key handling where HOME/END/CTRL_A/CTRL_E can either move the cursor within the input or navigate through results, depending on whether a result is currently highlighted.

Sources: src/SearchPrompt.php1-141