Keyboard Actions

Keyboard navigation library integration factories for token selector mode, actions, URL maps, and hidden action buttons.

Token Selector Mode

---

create_token_selector_mode

def create_token_selector_mode(
    config:TokenSelectorConfig, # config for this instance
    mode_name:str='token-select', # mode name for the keyboard nav system
    indicator_text:str='Token Select', # mode indicator text
    exit_key:str='', # exit key (empty = programmatic only via Escape KeyAction)
    exit_on_zone_change:bool=False, # whether to exit on zone change
)->KeyboardMode: # configured keyboard mode

Create a keyboard mode that activates/deactivates the token selector.

from cjm_fasthtml_token_selector.core.config import _reset_prefix_counter

_reset_prefix_counter()
cfg = TokenSelectorConfig(prefix="ts0")

mode = create_token_selector_mode(cfg)
assert mode.name == "token-select"
assert mode.on_enter == "ts0_activate"
assert mode.on_exit == "ts0_deactivate"
assert mode.indicator_text == "Token Select"
assert mode.exit_key == ""

# Custom mode name
mode2 = create_token_selector_mode(cfg, mode_name="split", indicator_text="Split Mode")
assert mode2.name == "split"
assert mode2.indicator_text == "Split Mode"

_reset_prefix_counter()
print("create_token_selector_mode tests passed!")

create_token_selector_mode tests passed!

Navigation Actions

Non-movement keyboard actions (Confirm/Cancel/Home/End) plus documentation-only entries for the client-side movement keys (Left/Right). The movement keys are handled by the token selector’s own key repeat engine (NOT by KeyAction); the documentation-only entries exist purely so the movement keys surface in the cjm-fasthtml-keyboard-navigation 0.0.22+ hints modal. Their prevent_default=False behavior (baked into KeyAction.documentation_only) lets the client-side handler receive the events uninterrupted.

---

create_token_nav_actions

def create_token_nav_actions(
    config:TokenSelectorConfig, # config for this instance
    zone_id:str, # focus zone ID
    mode_name:str='token-select', # mode name (must match the mode)
    confirm_button_id:str='', # HTMX button ID for confirm action
    cancel_button_id:str='', # HTMX button ID for cancel action
)->Tuple: # non-movement keyboard actions + documentation-only movement

Create keyboard actions for the token selector.

Includes: - Handler-firing actions: Confirm (Enter), Cancel (Escape), Home, End. These use htmx_trigger or js_callback to invoke the corresponding behavior. - Documentation-only actions: ArrowLeft/ArrowRight for caret movement. These appear in the hints modal but fire NO handler — caret movement is handled client-side by the token-selector’s key repeat engine. Requires cjm-fasthtml-keyboard-navigation 0.0.22+ for KeyAction.documentation_only.

_reset_prefix_counter()
cfg = TokenSelectorConfig(prefix="ts0")

actions = create_token_nav_actions(
    cfg, zone_id="my-zone",
    confirm_button_id="confirm-btn",
    cancel_button_id="cancel-btn",
)

# Should have: Enter, Space, Escape, Home, End + ArrowLeft, ArrowRight = 7 actions
assert len(actions) == 7

# All five active keys present
keys = {a.key for a in actions}
assert "Enter" in keys
assert "Escape" in keys
assert "Home" in keys
assert "End" in keys
# Documentation-only movement keys NOW present in the action set
assert "ArrowLeft" in keys
assert "ArrowRight" in keys

# Home uses js_callback (handler-firing)
home_action = [a for a in actions if a.key == "Home"][0]
assert home_action.js_callback == "ts0_moveToFirst"

# ArrowLeft/ArrowRight are documentation-only — no handler paths set,
# prevent_default disabled so the token-selector's client-side key repeat
# engine receives the event unaltered.
arrow_left = [a for a in actions if a.key == "ArrowLeft"][0]
arrow_right = [a for a in actions if a.key == "ArrowRight"][0]
assert arrow_left.is_documentation_only()
assert arrow_right.is_documentation_only()
assert arrow_left.prevent_default is False
assert arrow_right.prevent_default is False
assert arrow_left.description == "Move caret left"
assert arrow_right.description == "Move caret right"
assert arrow_left.hint_group == "Token Select"
assert arrow_left.mode_names == ("token-select",)
assert arrow_left.zone_ids == ("my-zone",)

# Without confirm/cancel: still emits Home/End + documentation-only L/R = 4
actions_min = create_token_nav_actions(cfg, zone_id="z")
assert len(actions_min) == 4
min_keys = {a.key for a in actions_min}
assert min_keys == {"Home", "End", "ArrowLeft", "ArrowRight"}

_reset_prefix_counter()
print("create_token_nav_actions tests passed (incl. documentation-only ArrowLeft/Right)!")

URL Map and Action Buttons

---

build_token_selector_url_map

def build_token_selector_url_map(
    confirm_button_id:str, # button ID for confirm action
    cancel_button_id:str, # button ID for cancel action
    confirm_url:str, # URL for confirm action
    cancel_url:str, # URL for cancel action
)->Dict: # button ID -> URL mapping

Build URL map for keyboard system with token selector action buttons.

---

render_token_action_buttons

def render_token_action_buttons(
    confirm_button_id:str, # button ID for confirm
    cancel_button_id:str, # button ID for cancel
    confirm_url:str, # URL for confirm action
    cancel_url:str, # URL for cancel action
    ids:TokenSelectorHtmlIds, # HTML IDs (for hx_include)
    extra_include:str='', # additional hx_include selectors
)->Any: # Div containing hidden action buttons

Render hidden HTMX buttons for confirm/cancel actions.

ids = TokenSelectorHtmlIds(prefix="ts0")

url_map = build_token_selector_url_map("confirm-btn", "cancel-btn", "/confirm", "/cancel")
assert url_map["confirm-btn"] == "/confirm"
assert url_map["cancel-btn"] == "/cancel"
print("build_token_selector_url_map test passed!")

btns = render_token_action_buttons("confirm-btn", "cancel-btn", "/confirm", "/cancel", ids)
assert btns is not None
print("render_token_action_buttons test passed!")

build_token_selector_url_map test passed!
render_token_action_buttons test passed!