# Navigation Patterns
## Direction Type
Navigation directions supported by the framework.
## NavigationPattern Protocol
The base protocol that all navigation patterns must implement.
------------------------------------------------------------------------
source
### NavigationPattern
``` python
def NavigationPattern(
args:VAR_POSITIONAL, kwargs:VAR_KEYWORD
):
```
*Protocol for navigation within a focus zone.*
## LinearVertical
Up/Down navigation through a vertical list of items. This is the most
common pattern.
------------------------------------------------------------------------
source
### LinearVertical
``` python
def LinearVertical(
wrap:bool=False
)->None:
```
*Up/Down navigation through a vertical list.*
``` python
# Test LinearVertical
nav = LinearVertical()
assert nav.name == "linear_vertical"
assert nav.get_supported_directions() == ("up", "down")
assert nav.get_next_index(0, "down", 5) == 1
assert nav.get_next_index(4, "down", 5) == 4 # no wrap
assert nav.get_next_index(0, "up", 5) == 0 # no wrap
# Test with wrap
nav_wrap = LinearVertical(wrap=True)
assert nav_wrap.get_next_index(4, "down", 5) == 0 # wraps to start
assert nav_wrap.get_next_index(0, "up", 5) == 4 # wraps to end
```
## LinearHorizontal
Left/Right navigation through a horizontal list. Useful for word tokens
in split mode, tabs, etc.
------------------------------------------------------------------------
source
### LinearHorizontal
``` python
def LinearHorizontal(
wrap:bool=False
)->None:
```
*Left/Right navigation through a horizontal list.*
``` python
# Test LinearHorizontal
nav = LinearHorizontal()
assert nav.name == "linear_horizontal"
assert nav.get_supported_directions() == ("left", "right")
assert nav.get_next_index(0, "right", 5) == 1
assert nav.get_next_index(4, "right", 5) == 4 # no wrap
assert nav.get_next_index(0, "left", 5) == 0 # no wrap
# Test with wrap
nav_wrap = LinearHorizontal(wrap=True)
assert nav_wrap.get_next_index(4, "right", 5) == 0 # wraps
assert nav_wrap.get_next_index(0, "left", 5) == 4 # wraps
```
## ScrollOnly
A navigation pattern for zones that are scrollable but don’t have
selectable items (e.g., a preview panel).
------------------------------------------------------------------------
source
### ScrollOnly
``` python
def ScrollOnly(
)->None:
```
*No item navigation, zone is scrollable content only.*
``` python
# Test ScrollOnly
nav = ScrollOnly()
assert nav.name == "scroll_only"
assert nav.get_supported_directions() == ()
assert nav.get_next_index(2, "down", 5) == 2 # unchanged
```
## Grid (Placeholder)
2D grid navigation for use in media galleries and similar UIs. Marked as
placeholder for future implementation.
------------------------------------------------------------------------
source
### Grid
``` python
def Grid(
columns:int=4, wrap_horizontal:bool=True, wrap_vertical:bool=False
)->None:
```
*2D grid navigation (placeholder for future implementation).*
``` python
# Test Grid navigation
# Grid with 4 columns, 10 items:
# [0, 1, 2, 3]
# [4, 5, 6, 7]
# [8, 9]
grid = Grid(columns=4)
assert grid.name == "grid"
assert grid.get_supported_directions() == ("up", "down", "left", "right")
# Horizontal navigation
assert grid.get_next_index(0, "right", 10) == 1
assert grid.get_next_index(3, "right", 10) == 0 # wraps
assert grid.get_next_index(0, "left", 10) == 3 # wraps
# Vertical navigation
assert grid.get_next_index(1, "down", 10) == 5
assert grid.get_next_index(5, "up", 10) == 1
assert grid.get_next_index(9, "down", 10) == 9 # no vertical wrap by default
```
## Protocol Verification
``` python
# Verify all implementations satisfy the protocol
assert isinstance(LinearVertical(), NavigationPattern)
assert isinstance(LinearHorizontal(), NavigationPattern)
assert isinstance(ScrollOnly(), NavigationPattern)
assert isinstance(Grid(), NavigationPattern)
```