Keyboard Hints Modal

Modal-based keyboard shortcut reference with scannable grouped layout and ? key trigger.

Key Display

from fasthtml.common import to_xml

# Single key
html = to_xml(_render_key_combo("Space"))
assert "kbd" in html
assert "Space" in html
assert "+" not in html.split("kbd")[0]  # no plus before first kbd

# Multi-key combo
html = to_xml(_render_key_combo("Ctrl+Shift+\u2191"))
assert html.count("kbd") >= 3  # 3 kbd elements (tag appears in open+close)
assert "Ctrl" in html
assert "Shift" in html
assert "\u2191" in html
print("Key display tests passed")

Key display tests passed

Hint Row & Group

# Test hint row
row_html = to_xml(_render_hint_row("Ctrl+Z", "Undo last action"))
assert "Ctrl" in row_html
assert "Z" in row_html
assert "Undo last action" in row_html

# Test modal group
group_html = to_xml(_render_modal_group("Editing", [
    ("Enter", "Enter split mode"),
    ("Escape", "Exit split mode"),
]))
assert "Editing" in group_html
assert "Enter split mode" in group_html
assert "Exit split mode" in group_html
print("Hint row and group tests passed")

Hint row and group tests passed

Modal Body

from cjm_fasthtml_keyboard_navigation.core.focus_zone import FocusZone
from cjm_fasthtml_keyboard_navigation.core.actions import KeyAction
from cjm_fasthtml_keyboard_navigation.core.manager import ZoneManager

# Build a test manager with two zones and some actions
z1 = FocusZone(id="seg")
z2 = FocusZone(id="align")
test_manager = ZoneManager(
    zones=(z1, z2),
    actions=(
        KeyAction(key="Enter", js_callback="x", description="Enter split mode", hint_group="Editing"),
        KeyAction(key="Escape", js_callback="x", description="Exit split mode", hint_group="Editing"),
        KeyAction(key="Backspace", htmx_trigger="x", description="Merge with previous", hint_group="Editing"),
        KeyAction(key="z", modifiers=frozenset({"ctrl"}), htmx_trigger="x", description="Undo", hint_group="Editing"),
        KeyAction(key=" ", js_callback="x", description="Play audio", hint_group="Audio"),
    ),
    prev_zone_key="ArrowLeft",
    next_zone_key="ArrowRight",
)

body_html = to_xml(_render_modal_body(test_manager))
assert "Navigation" in body_html
assert "Navigate items" in body_html
assert "Switch panel" in body_html
assert "Editing" in body_html
assert "Enter split mode" in body_html
assert "Audio" in body_html
assert "Play audio" in body_html
print("Modal body tests passed")

Modal body tests passed

Trigger Button

---

source

render_keyboard_hints_trigger

def render_keyboard_hints_trigger(
    modal_id:str='kb-hints-modal', # ID of the modal dialog to open
    icon_size:int=4, # lucide icon size
)->Button: # ghost button with keyboard icon

Render a keyboard icon button that opens the hints modal.

trigger = render_keyboard_hints_trigger()
html = to_xml(trigger)
assert "keyboard" in html.lower() or "svg" in html  # has icon
assert "showModal" in html
assert "kb-hints-modal" in html
assert 'title="Keyboard shortcuts (?)"' in html
print("Trigger button tests passed")

Trigger button tests passed

Question Mark Key Listener

listener = _render_question_mark_listener("kb-hints-modal")
html = to_xml(listener)
assert "keydown" in html
assert "e.key === '?'" in html
assert "showModal" in html
assert "INPUT" in html  # skips input fields
assert "TEXTAREA" in html
assert "isContentEditable" in html
print("Question mark listener tests passed")

Question mark listener tests passed

Full Modal Component

---

source

render_keyboard_hints_modal

def render_keyboard_hints_modal(
    manager:ZoneManager, # keyboard zone manager with actions configured
    modal_id:str='kb-hints-modal', # HTML ID for the modal dialog
    include_navigation:bool=True, # include \u2191/\u2193 navigation hint
    include_zone_switch:bool=True, # include zone switch hint (auto-hidden for single zone)
    enable_question_mark_key:bool=True, # add global `?` key listener
    title:str='Keyboard Shortcuts', # modal title text
)->tuple[FT, FT, FT]: # (modal_dialog, trigger_button, question_mark_script)

Render a modal-based keyboard shortcut reference.

Returns three components: - modal_dialog: The Dialog element (place anywhere in page) - trigger_button: Small keyboard icon button (place in step header) - question_mark_script: Global ? key listener Script (place in page)

If enable_question_mark_key is False, question_mark_script is an empty Div.

# Test with the dual-zone manager from above
modal_dialog, trigger, qm_script = render_keyboard_hints_modal(test_manager)

modal_html = to_xml(modal_dialog)
trigger_html = to_xml(trigger)
script_html = to_xml(qm_script)

# Modal structure
assert 'id="kb-hints-modal"' in modal_html
assert 'modal-box' in modal_html
assert 'modal-backdrop' in modal_html
assert 'Keyboard Shortcuts' in modal_html
assert 'Navigation' in modal_html
assert 'Editing' in modal_html
assert 'Audio' in modal_html
assert '\u2715' in modal_html  # close button

# Trigger
assert 'showModal' in trigger_html
assert 'kb-hints-modal' in trigger_html

# Question mark listener
assert 'keydown' in script_html
assert "e.key === '?'" in script_html

# Test with question mark key disabled
_, _, no_qm = render_keyboard_hints_modal(test_manager, enable_question_mark_key=False)
no_qm_html = to_xml(no_qm)
assert 'keydown' not in no_qm_html  # no listener
assert 'display:none' in no_qm_html  # empty placeholder

# Test single-zone manager (no zone switch hint)
single_manager = ZoneManager(
    zones=(z1,),
    actions=(KeyAction(key=" ", js_callback="x", description="Select", hint_group="Actions"),),
)
single_modal, _, _ = render_keyboard_hints_modal(single_manager)
single_html = to_xml(single_modal)
assert 'Switch panel' not in single_html  # no zone switch for single zone
assert 'Navigate items' in single_html
assert 'Select' in single_html

print("Full modal component tests passed")

Full modal component tests passed