Script Generators

Generate complete keyboard navigation JavaScript from configuration.

Zone State Management

source

js_zone_state


def js_zone_state(
    
)->str: # JavaScript state and getter/setter code

Generate JavaScript code for zone state management.

Focus Management

source

js_focus_management


def js_focus_management(
    
)->str: # JavaScript focus management code

Generate JavaScript code for focus management.

Zone Switching

source

js_zone_switching


def js_zone_switching(
    
)->str: # JavaScript zone switching code

Generate JavaScript code for zone switching.

Mode Management

source

js_mode_management


def js_mode_management(
    
)->str: # JavaScript mode management code

Generate JavaScript code for mode management.

Action Dispatch

source

js_action_dispatch


def js_action_dispatch(
    
)->str: # JavaScript action dispatch code

Generate JavaScript code for action dispatch.

Keyboard Handler

source

js_keyboard_handler


def js_keyboard_handler(
    
)->str: # JavaScript keyboard handler code

Generate JavaScript code for keyboard event handling.

State Notification

source

js_state_notification


def js_state_notification(
    
)->str: # JavaScript state notification code

Generate JavaScript code for state change notification.

Initialization

After HTMX swaps, the DOM changes but our state (focus indices) may be stale. The initialization function: 1. Reads the hidden input values (set before the swap) 2. Finds items with matching data attributes in the new DOM 3. Updates focus indices to follow moved/reordered items 4. Falls back to clamping if item not found (deleted)

source

js_initialization


def js_initialization(
    
)->str: # JavaScript initialization code

Generate JavaScript code for initialization with focus recovery.

Global API

Expose mode control functions globally for programmatic access from external code (e.g., HTMX responses that need to sync mode state).

source

js_global_api


def js_global_api(
    
)->str: # JavaScript global API exposure code

Generate JavaScript code to expose control functions globally.

source

generate_keyboard_script


def generate_keyboard_script(
    manager:ZoneManager, # the zone manager configuration
)->str: # complete JavaScript code wrapped in IIFE

Generate complete keyboard navigation JavaScript from ZoneManager.

# Test complete script generation
from cjm_fasthtml_keyboard_navigation.core.focus_zone import FocusZone
from cjm_fasthtml_keyboard_navigation.core.actions import KeyAction

browser = FocusZone(
    id="browser",
    item_selector="tr.item",
    data_attributes=("job-id",)
)
queue = FocusZone(
    id="queue",
    item_selector="li.item"
)

manager = ZoneManager(
    zones=(browser, queue),
    actions=(
        KeyAction(key=" ", htmx_trigger="toggle-btn"),
        KeyAction(key="Delete", htmx_trigger="delete-btn"),
    )
)

script = generate_keyboard_script(manager)

# Verify coordinator is included
assert "window.kbCoordinator" in script
assert "register" in script

# Verify key parts are present
assert "(function()" in script
assert "const cfg" in script
assert '"systemId"' in script
assert "isInputFocused" in script
assert "handleKeydown" in script
assert "initialize" in script
assert "window.kbNav" in script
assert "})();" in script

# Verify coordinator registration replaces direct listener
assert "kbCoordinator.register(cfg.systemId" in script
# Verify direct listener is NOT used
assert "document.addEventListener('keydown', handleKeydown)" not in script

# Verify handleKeydown returns result objects
assert "NOT_HANDLED" in script
assert "handled: true" in script
assert "handled: false" in script

# Verify Escape-to-deactivate
assert "deactivateChild" in script
assert "hasParent" in script

# Verify per-system API
assert "window.kbNav[cfg.systemId]" in script