# Keyboard Modes


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## KeyboardMode

A named state that changes keyboard behavior. Modes can override
navigation patterns, have their own key bindings, and trigger callbacks
on entry/exit.

------------------------------------------------------------------------

<a
href="https://github.com/cj-mills/cjm-fasthtml-keyboard-navigation/blob/main/cjm_fasthtml_keyboard_navigation/core/modes.py#L17"
target="_blank" style="float:right; font-size:smaller">source</a>

### KeyboardMode

``` python

def KeyboardMode(
    name:str, enter_key:Optional[str]=None, enter_modifiers:frozenset[str]=<factory>, exit_key:str='Escape',
    exit_modifiers:frozenset[str]=<factory>, zone_ids:Optional[tuple[str, ...]]=None,
    navigation_override:Optional[NavigationPattern]=None, on_enter:Optional[str]=None, on_exit:Optional[str]=None,
    indicator_text:Optional[str]=None, exit_on_zone_change:bool=True
)->None:

```

*A named mode that changes keyboard behavior.*

``` python
# Test basic KeyboardMode
mode = KeyboardMode(
    name="split",
    enter_key="Enter",
    exit_key="Escape",
    zone_ids=("card-list",),
    on_enter="enterSplitMode",
    on_exit="exitSplitMode",
    indicator_text="Split Mode"
)

assert mode.name == "split"
assert mode.is_available_in_zone("card-list") == True
assert mode.is_available_in_zone("other-zone") == False

config = mode.to_js_config()
assert config["name"] == "split"
assert config["enterKey"] == "Enter"
assert config["zoneIds"] == ["card-list"]
```

``` python
# Test mode available in all zones
global_mode = KeyboardMode(
    name="help",
    enter_key="?",
    zone_ids=None  # available everywhere
)

assert global_mode.is_available_in_zone("any-zone") == True
assert global_mode.to_js_config()["zoneIds"] is None
```

## Default Navigation Mode

The default mode that’s always active when no other mode is entered.

``` python
# Test default mode
assert NAVIGATION_MODE.name == "navigation"
assert NAVIGATION_MODE.enter_key is None
assert NAVIGATION_MODE.is_available_in_zone("any") == True
```

## Example Modes

Common mode patterns for reference.

``` python
from cjm_fasthtml_keyboard_navigation.core.navigation import LinearHorizontal

# Split mode for text segmentation (Phase 2 style)
split_mode_example = KeyboardMode(
    name="split",
    enter_key="Enter",
    exit_key="Escape",
    navigation_override=LinearHorizontal(),  # left/right for caret
    on_enter="enterSplitMode",
    on_exit="exitSplitMode",
    indicator_text="Split Mode"
)

# Audition mode for audio preview (Phase 3 style)
audition_mode_example = KeyboardMode(
    name="audition",
    enter_key=None,  # entered by switching to VAD zone
    zone_ids=("vad-timeline",),
    on_enter="startAudition",
    indicator_text="Audition"
)

# Edit mode for inline editing
edit_mode_example = KeyboardMode(
    name="edit",
    enter_key="e",
    exit_key="Escape",
    on_enter="startEditing",
    on_exit="finishEditing",
    indicator_text="Edit"
)
```