Search and Suggest Prompts

Purpose and Scope

Search and suggest prompts enable dynamic filtering and selection of options through closure-based option generation. Unlike static selection prompts (see page 4.2), these prompts invoke a callback function with the user's typed input to generate matching options on-demand. This category includes three prompt types:

• SearchPrompt: Single selection from dynamically filtered options (requires selection from results)
• MultiSearchPrompt: Multiple selection from dynamically filtered options (requires selection from results)
• SuggestPrompt: Autocomplete-style text input (allows free-form input or selection from suggestions)

The key distinction is that SearchPrompt and MultiSearchPrompt require the user to select from the generated options, while SuggestPrompt allows the user to type any value, using suggestions as optional completions.

For static option lists, see page 4.2. For free-form text input without suggestions, see page 4.1.

Sources: src/helpers.php109-133 src/SearchPrompt.php1-141 src/MultiSearchPrompt.php1-219

Search Prompt Type Taxonomy

The library provides three distinct search-based interaction patterns:

Prompt Type	Helper Function	Return Type	Purpose	Required Parameter
SearchPrompt	search()	int|string	Single selection from dynamically filtered options	Closure(string): array
MultiSearchPrompt	multisearch()	array<int|string>	Multiple selection from dynamically filtered options	Closure(string): array
SuggestPrompt	suggest()	string	Text input with autocomplete suggestions	array|Closure|Collection

Prompt Type Relationships

Sources: src/helpers.php97-133 src/SearchPrompt.php10-14 src/MultiSearchPrompt.php10-14

Sources: src/helpers.php97-133 src/SearchPrompt.php10 src/MultiSearchPrompt.php10

SearchPrompt (Single Selection)

SearchPrompt allows users to search through a large dataset by typing a query, with matching options generated dynamically via a closure. The user can navigate results with arrow keys and select a single option.

Class Structure

The SearchPrompt class is defined at src/SearchPrompt.php10-141 and uses three traits:

Trait	Purpose
Concerns\Scrolling	Manages list navigation with highlighted, firstVisible indices
Concerns\Truncation	Fits text within terminal width constraints
Concerns\TypedValue	Tracks keyboard input in typedValue and cursorPosition

Sources: src/SearchPrompt.php10-14

Constructor Parameters

The required parameter cannot be false for SearchPrompt - it must be true or a custom error message string. This design decision enforces that search prompts always require a selection, as indicated in src/SearchPrompt.php38-40

Sources: src/SearchPrompt.php28-40

Closure-Based Option Generation

The options parameter is a closure with signature Closure(string): array<int|string, string>. This closure receives the current search query and returns matching options:

The matches() method at src/SearchPrompt.php93-100 implements caching: results are stored in the $matches property until the search query changes. When the user types a new character, the search() method at src/SearchPrompt.php60-68 resets $matches to null, forcing a fresh closure invocation.

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

Keyboard Navigation

The constructor at src/SearchPrompt.php46-54 registers key handlers:

Key	Action	Implementation
UP, UP_ARROW, SHIFT_TAB, CTRL_P	Highlight previous option	highlightPrevious() from Scrolling trait
DOWN, DOWN_ARROW, TAB, CTRL_N	Highlight next option	highlightNext() from Scrolling trait
HOME, CTRL_A	Jump to first option	highlight(0) if options displayed
END, CTRL_E	Jump to last option	highlight(count - 1) if options displayed
ENTER	Submit if option highlighted, else search	Conditional: submit() or search()
LEFT, RIGHT, CTRL_B, CTRL_F	Edit search query	Clear highlighted, resume text editing
Any other key	Trigger new search	search()

The conditional ENTER behavior at src/SearchPrompt.php51 is notable: if an option is highlighted ($this->highlighted !== null), pressing enter submits the selection. If the user is typing in the search box ($this->highlighted === null), enter triggers a search.

Sources: src/SearchPrompt.php46-54

Value Retrieval

Two methods provide access to the selected value:

• value() (src/SearchPrompt.php123-132): Returns the array key (for associative arrays) or the value itself (for lists)
• label() (src/SearchPrompt.php137-140): Returns the display text of the selected option

For list arrays like ['John', 'Jane'], both methods return the same value. For associative arrays like ['user_1' => 'John', 'user_2' => 'Jane'], value() returns the key ('user_1') while label() returns the display text ('John').

Sources: src/SearchPrompt.php123-140

MultiSearchPrompt (Multiple Selection)

MultiSearchPrompt extends the search pattern to support multiple selections using the spacebar. It maintains a $values array tracking all selected options.

Differences from SearchPrompt

Key differences implemented in src/MultiSearchPrompt.php1-219:

1. Selection State: Uses $values array (src/MultiSearchPrompt.php33) instead of single highlighted index
2. Toggle Operations: Spacebar toggles individual items (src/MultiSearchPrompt.php59), CTRL_A toggles all visible matches (src/MultiSearchPrompt.php60)
3. List Detection: Tracks $isList flag (src/MultiSearchPrompt.php26) to handle both list and associative arrays correctly
4. Required Behavior: Can be false, allowing submission with no selections

Sources: src/MultiSearchPrompt.php26-66

Selection Management

The toggleHighlighted() method at src/MultiSearchPrompt.php167-182 adds or removes items from $values:

The toggleAll() method at src/MultiSearchPrompt.php144-162 provides bulk selection:

• If all visible matches are selected, deselect them
• If any visible match is unselected, select all visible matches

Sources: src/MultiSearchPrompt.php144-182

Dynamic Match Ordering

When the search query is empty, matches() at src/MultiSearchPrompt.php104-129 reorders results to show selected items first:

This behavior at src/MultiSearchPrompt.php122-128 improves UX by keeping selected items visible when the user clears the search box.

Sources: src/MultiSearchPrompt.php104-129

SuggestPrompt (Autocomplete)

While SuggestPrompt is not detailed in the provided files, the helper function at src/helpers.php97-107 reveals its interface:

• Options: Accepts array|Closure|Collection, allowing both static and dynamic suggestions
• Return Type: string (text input with suggestions, not selection)
• Behavior: Likely provides autocomplete dropdown while user types, but allows custom input

This differs from SearchPrompt which requires selecting from the generated options.

Sources: src/helpers.php97-107

State Management

Search prompts use a $state property to coordinate rendering during asynchronous operations:

The state transition at src/SearchPrompt.php62-67 prevents flickering by setting state to 'searching', triggering a render, clearing cached matches, then returning to 'active' state. The renderer can display different UI based on this state.

Sources: src/SearchPrompt.php60-68

Visible Window Management

The Scrolling trait provides visible() method used at src/SearchPrompt.php107-110:

This method returns only the options currently visible in the scrollable window, controlled by $firstVisible (starting index) and $scroll (window size). As the user navigates with arrow keys, highlightPrevious() and highlightNext() adjust these indices automatically.

Sources: src/SearchPrompt.php107-110

Value with Cursor Display

The valueWithCursor() method at src/SearchPrompt.php73-86 handles cursor rendering in different states:

Condition	Display Behavior
Option highlighted	Show typed value without cursor (user navigating results)
Empty input, no highlight	Show placeholder with cursor at position 0 (dimmed)
Input present, no highlight	Show input with cursor at current position (editing)

This method is called by renderers to display the search input field with appropriate visual feedback.

Sources: src/SearchPrompt.php73-86

Helper Function Signatures

The search helper functions follow the standard instantiation pattern:

Both helpers use get_defined_vars() to capture all function parameters and spread them into the constructor, then immediately call prompt() to execute the interaction.

Sources: src/helpers.php109-133

Common Usage Patterns

Search prompts excel at scenarios requiring dynamic filtering:

1. Database Queries: Invoke closure performs SQL LIKE query based on user input
2. API Searches: Closure makes HTTP request to search endpoint
3. Large Static Datasets: Closure filters large in-memory array to show matching results
4. Lazy Loading: Generate options on-demand to avoid loading entire dataset upfront

The closure pattern enables these use cases without requiring the prompt itself to know about databases, APIs, or specific filtering logic.

Sources: src/SearchPrompt.php28-37 src/helpers.php109-120