 |
VOOZH | about |
|
VOOZH | about |
The Scrolling trait provides viewport management for prompts that display long lists of options. When the number of options exceeds the visible viewport size, this trait enables keyboard navigation through the list while maintaining a sliding window of visible items.
This trait is used by three interactive prompt types:
SelectPrompt - single-selection from a list (see 5.2)MultiSelectPrompt - multi-selection from a list (see 5.2)SearchPrompt - dynamic search with result navigation (see 5.3)For information about the keyboard input handling that drives navigation, see 10.3. For the visual rendering of scrollbars, see the DrawsScrollbars trait used by renderers (see 8.2).
The scrolling system maintains two critical indices that work together to provide a viewport into a potentially large list:
| Property | Type | Purpose |
|---|---|---|
$highlighted | int|null | The index of the currently focused item in the full list |
$firstVisible | int | The index of the first item shown in the current viewport |
$scroll | int | The maximum number of items visible at once (viewport size) |
The viewport is a sliding window that shows a subset of the total options. As the user navigates, the viewport automatically adjusts to keep the highlighted item visible.
Example: Viewport Calculation
For a list with 20 options and $scroll = 5:
$firstVisible = 6$highlighted = 8Sources: src/MultiSelectPrompt.php100 src/SelectPrompt.php98 src/SearchPrompt.php109
The Scrolling trait (located at src/Concerns/Scrolling.php) provides the following interface:
Initializes the scrolling state with an optional initial highlighted index. Called in the constructor of prompts using scrolling.
Usage Examples:
| Prompt Type | Initialization | Purpose |
|---|---|---|
SelectPrompt | initializeScrolling(0) or with default match | Start at first item or default value |
MultiSelectPrompt | initializeScrolling(0) | Always start at first item |
SearchPrompt | initializeScrolling(null) | No initial highlight (user is typing) |
Sources: src/SelectPrompt.php45-52 src/MultiSelectPrompt.php55 src/SearchPrompt.php44
Moves the highlight up by one item. If $allowWrap is false and already at the first item, no change occurs. The viewport automatically scrolls if necessary.
Moves the highlight down by one item. If $allowWrap is false and already at the last item, no change occurs. The viewport automatically scrolls if necessary.
Directly sets the highlighted index to a specific position. Used for HOME/END key handling to jump to start/end of list.
Adjusts $firstVisible to ensure the currently highlighted item is within the viewport. Used when setting a default value that may be outside the initial viewport.
Sources: src/SelectPrompt.php56-59 src/MultiSelectPrompt.php58-61 src/SearchPrompt.php47-50
Key Features:
visible() method returns the current viewport slice for rendering src/SelectPrompt.php96-99Sources: src/SelectPrompt.php1-109
Key Features:
$highlighted index (from scrolling) is independent of the $values array (selected items) src/MultiSelectPrompt.php29-33$values is initialized with defaults src/MultiSelectPrompt.php53-55Sources: src/MultiSelectPrompt.php1-153
Key Features:
highlighted = null since the user begins by typing src/SearchPrompt.php44search() is called, both matches and firstVisible are reset src/SearchPrompt.php60-68true to highlightPrevious() and highlightNext() to allow wrapping from bottom to top src/SearchPrompt.php47-48highlighted = null, returning to typing mode src/SearchPrompt.php52Sources: src/SearchPrompt.php1-142
All scrolling-enabled prompts share a common set of keyboard navigation bindings:
| Key | Action | Used By |
|---|---|---|
↑ UP_ARROW | Move highlight up | All three prompts |
↓ DOWN_ARROW | Move highlight down | All three prompts |
← LEFT_ARROW | Move highlight up (SelectPrompt/MultiSelectPrompt) or exit navigation (SearchPrompt) | Context-dependent |
→ RIGHT_ARROW | Move highlight down (SelectPrompt/MultiSelectPrompt) or exit navigation (SearchPrompt) | Context-dependent |
Tab | Move highlight down | All three prompts |
Shift+Tab | Move highlight up | All three prompts |
HOME | Jump to first item | All three prompts |
END | Jump to last item | All three prompts |
| Key | Action | Vim Equivalent |
|---|---|---|
Ctrl+P | Previous item | k (up) |
Ctrl+N | Next item | j (down) |
Ctrl+B | Previous item | h (left) |
Ctrl+F | Next item | l (right) |
Ctrl+A | Jump to first (Select) / Toggle all (MultiSelect) | HOME equivalent |
Ctrl+E | Jump to last | END equivalent |
| Key | Action |
|---|---|
k | Move up |
j | Move down |
h | Move up |
l | Move down |
Implementation Note: The key handlers use Key::oneOf() to match multiple keys to the same action src/SelectPrompt.php58-59 allowing flexible binding patterns without code duplication.
Sources: src/SelectPrompt.php55-62 src/MultiSelectPrompt.php57-66 src/SearchPrompt.php46-54
Each scrolling prompt provides a visible() method that calculates the current viewport slice:
Key Points:
preserve_keys: true parameter maintains the original array keys, which is essential for identifying options by their keys rather than viewport-relative positions src/SelectPrompt.php98visible() signature, allowing renderers to use a uniform approach src/MultiSelectPrompt.php98-101 src/SearchPrompt.php107-110SearchPrompt, visible() slices from matches() rather than options, reflecting the filtered results src/SearchPrompt.php107-110Sources: src/SelectPrompt.php96-99 src/MultiSelectPrompt.php98-101 src/SearchPrompt.php107-110
The scrolling trait automatically adjusts $firstVisible when the highlighted item would move outside the viewport:
| User Action | Current State | Result |
|---|---|---|
| Highlight moves down | highlighted >= firstVisible + scroll | firstVisible increments by 1 |
| Highlight moves up | highlighted < firstVisible | firstVisible decrements by 1 |
| Jump to HOME | highlighted = 0 | firstVisible = 0 |
| Jump to END | highlighted = count - 1 | firstVisible = max(0, count - scroll) |
| Set default (SelectPrompt) | Default outside initial viewport | scrollToHighlighted() adjusts viewport |
Example Flow:
Options: 15 items (indices 0-14)
Scroll: 5 items per viewport
Initial: highlighted=0, firstVisible=0
User presses DOWN 5 times:
highlighted=1, firstVisible=0 (still in viewport)
highlighted=2, firstVisible=0
highlighted=3, firstVisible=0
highlighted=4, firstVisible=0
highlighted=5, firstVisible=1 (viewport shifts!)
Viewport now shows indices 1-5, with 5 highlighted
This automatic adjustment ensures the user never scrolls the highlight out of view, maintaining a smooth navigation experience.
Sources: Inferred from usage in src/SelectPrompt.php50 src/MultiSelectPrompt.php58-61 src/SearchPrompt.php47-50
Refresh this wiki