Key Actions

Declarative keyboard action bindings supporting HTMX triggers and JS callbacks.

KeyAction

Declares a keyboard shortcut and its associated action. Actions can trigger HTMX requests, call JS functions, or switch modes.

---

source

KeyAction

def KeyAction(
    key:str, modifiers:frozenset[str]=<factory>, htmx_trigger:Optional[str]=None, js_callback:Optional[str]=None,
    mode_enter:Optional[str]=None, mode_exit:bool=False, prevent_default:bool=True, stop_propagation:bool=False,
    zone_ids:Optional[tuple[str, ...]]=None, mode_names:Optional[tuple[str, ...]]=None,
    not_modes:Optional[tuple[str, ...]]=None, custom_condition:Optional[str]=None, description:str='',
    hint_group:str='General', show_in_hints:bool=True
)->None:

A keyboard shortcut binding.

# Test basic KeyAction
action = KeyAction(
    key=" ",  # Space
    htmx_trigger="toggle-btn",
    description="Toggle selection",
    hint_group="Selection"
)

assert action.key == " "
assert action.htmx_trigger == "toggle-btn"
assert action.get_display_key() == "Space"
assert action.matches_context("any-zone", "any-mode") == True

# Test action with modifiers
shift_action = KeyAction(
    key="ArrowUp",
    modifiers=frozenset({"shift"}),
    htmx_trigger="reorder-up",
    zone_ids=("queue",),
    description="Move item up"
)

assert shift_action.get_display_key() == "Shift+↑"
assert shift_action.matches_context("queue", "navigation") == True
assert shift_action.matches_context("browser", "navigation") == False

# Test mode-specific action
split_action = KeyAction(
    key="Enter",
    htmx_trigger="execute-split",
    mode_names=("split",),
    description="Split at caret"
)

assert split_action.matches_context("any", "split") == True
assert split_action.matches_context("any", "navigation") == False

# Test action with not_modes
nav_only_action = KeyAction(
    key="Enter",
    mode_enter="split",
    not_modes=("split",),  # don't enter split if already in split
    description="Enter split mode"
)

assert nav_only_action.matches_context("zone", "navigation") == True
assert nav_only_action.matches_context("zone", "split") == False

# Test JS callback action
audition_action = KeyAction(
    key="ArrowDown",
    js_callback="auditionCurrent",
    zone_ids=("vad-timeline",),
    description="Navigate and audition"
)

config = audition_action.to_js_config()
assert config["jsCallback"] == "auditionCurrent"
assert config["htmxTrigger"] is None
assert config["zoneIds"] == ["vad-timeline"]

Common Action Patterns

# Example: Toggle selection (common for browser/list UIs)
toggle_space = KeyAction(
    key=" ",
    htmx_trigger="toggle-btn",
    description="Toggle selection",
    hint_group="Selection"
)

toggle_enter = KeyAction(
    key="Enter",
    htmx_trigger="toggle-btn",
    not_modes=("split", "edit"),  # don't toggle in edit modes
    description="Toggle selection",
    hint_group="Selection",
    show_in_hints=False  # don't duplicate in hints since Space is shown
)

# Example: Delete/Remove actions
delete_action = KeyAction(
    key="Delete",
    htmx_trigger="delete-btn",
    description="Delete item",
    hint_group="Actions"
)

backspace_delete = KeyAction(
    key="Backspace",
    htmx_trigger="delete-btn",
    description="Delete item",
    hint_group="Actions",
    show_in_hints=False  # alternative key
)