Keyboard Modes

Configuration for keyboard modes that change navigation and action behavior.

KeyboardMode

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

---

source

KeyboardMode

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.

# 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"]

# 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.

# 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.

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"
)