Creates a FocusZone configured for the card stack viewport. Uses ScrollOnly navigation since all navigation is handled via HTMX button triggers, not the keyboard library’s built-in item navigation.
def create_card_stack_focus_zone(
ids:CardStackHtmlIds, # HTML IDs for this card stack instance
on_focus_change:Optional=None, # JS callback name on focus change
hidden_input_prefix:Optional=None, # Prefix for keyboard nav hidden inputs
data_attributes:Tuple=(), # Data attributes to track on focused items
)->FocusZone: # Configured focus zone for the card stack
Create a focus zone for a card stack viewport.
# Test create_card_stack_focus_zone
ids = CardStackHtmlIds(prefix="cs0")
zone = create_card_stack_focus_zone(ids)
assert zone.id == "cs0-card-stack"
assert zone.item_selector == "[data-card-role='focused']"
assert isinstance(zone.navigation, ScrollOnly)
assert zone.zone_focus_classes == ()
assert zone.item_focus_classes == ()
assert zone.hidden_input_prefix == "cs0-focused"
print("Focus zone default tests passed!")Focus zone default tests passed!# Test with custom parameters
zone = create_card_stack_focus_zone(
ids,
on_focus_change="onCardFocusChange",
hidden_input_prefix="sd-decomp-focused",
data_attributes=("segment-index",),
)
assert zone.on_focus_change == "onCardFocusChange"
assert zone.hidden_input_prefix == "sd-decomp-focused"
assert zone.data_attributes == ("segment-index",)
print("Focus zone custom parameter tests passed!")Focus zone custom parameter tests passed!# Test multi-instance uniqueness
ids_a = CardStackHtmlIds(prefix="text")
ids_b = CardStackHtmlIds(prefix="vad")
zone_a = create_card_stack_focus_zone(ids_a)
zone_b = create_card_stack_focus_zone(ids_b)
assert zone_a.id != zone_b.id
assert zone_a.hidden_input_prefix != zone_b.hidden_input_prefix
print("Multi-instance focus zone tests passed!")Multi-instance focus zone tests passed!Creates the standard keyboard navigation actions for a card stack:
[/]: Narrow/widen viewport (JS callback)-/=: Decrease/increase scale (JS callback)JS callbacks use prefix-unique global names that map to the namespaced window.cardStacks[prefix] functions.
def create_card_stack_nav_actions(
zone_id:str, # Focus zone ID to restrict actions to
button_ids:CardStackButtonIds, # Button IDs for HTMX triggers
config:CardStackConfig, # Config (for prefix-unique callback names)
disable_in_modes:Tuple=(), # Mode names that disable navigation
)->Tuple: # Standard card stack navigation actions
Create standard keyboard navigation actions for a card stack.
from cjm_fasthtml_card_stack.core.config import CardStackConfig, _reset_prefix_counter
# Test create_card_stack_nav_actions returns 10 actions
_reset_prefix_counter()
config = CardStackConfig()
btn_ids = CardStackButtonIds(prefix=config.prefix)
ids = CardStackHtmlIds(prefix=config.prefix)
zone = create_card_stack_focus_zone(ids)
actions = create_card_stack_nav_actions(
zone_id=zone.id,
button_ids=btn_ids,
config=config,
)
assert len(actions) == 10
print(f"Got {len(actions)} actions")Got 10 actions# Test ArrowUp/Down actions use HTMX triggers
arrow_up = actions[0]
arrow_down = actions[1]
assert arrow_up.key == "ArrowUp"
assert arrow_up.htmx_trigger == btn_ids.nav_up
assert arrow_up.zone_ids == (zone.id,)
assert arrow_down.key == "ArrowDown"
assert arrow_down.htmx_trigger == btn_ids.nav_down
print("Arrow key action tests passed!")Arrow key action tests passed!Page jump callback tests passed!# Test Ctrl+Shift+Arrow actions use prefix-unique JS callbacks
first_item = actions[4]
last_item = actions[5]
assert first_item.js_callback == "cs0_jumpToFirstItem"
assert last_item.js_callback == "cs0_jumpToLastItem"
assert first_item.modifiers == frozenset({"ctrl", "shift"})
print("First/last callback tests passed!")First/last callback tests passed!Width adjustment callback tests passed!# Test scale adjustment actions use prefix-unique JS callbacks
scale_down = actions[8]
scale_up = actions[9]
assert scale_down.key == "-"
assert scale_down.js_callback == "cs0_decreaseScale"
assert scale_up.key == "="
assert scale_up.js_callback == "cs0_increaseScale"
print("Scale adjustment callback tests passed!")
# Test disable_in_modes filtering
actions_with_modes = create_card_stack_nav_actions(
zone_id=zone.id,
button_ids=btn_ids,
config=config,
disable_in_modes=("split", "edit"),
)
# Navigation actions should have not_modes set
assert actions_with_modes[0].not_modes == ("split", "edit")
assert actions_with_modes[1].not_modes == ("split", "edit")
assert actions_with_modes[2].not_modes == ("split", "edit")
# Width and scale actions should NOT have not_modes (available in any mode)
assert actions_with_modes[6].not_modes == None
assert actions_with_modes[7].not_modes == None
assert actions_with_modes[8].not_modes == None
assert actions_with_modes[9].not_modes == None
print("Mode filtering tests passed!")Scale adjustment callback tests passed!
Mode filtering tests passed!# Test multi-instance: different prefixes produce different callback names
config_a = CardStackConfig(prefix="text")
config_b = CardStackConfig(prefix="vad")
btn_a = CardStackButtonIds(prefix="text")
btn_b = CardStackButtonIds(prefix="vad")
ids_a = CardStackHtmlIds(prefix="text")
ids_b = CardStackHtmlIds(prefix="vad")
actions_a = create_card_stack_nav_actions(ids_a.card_stack, btn_a, config_a)
actions_b = create_card_stack_nav_actions(ids_b.card_stack, btn_b, config_b)
# HTMX triggers are different (different button IDs)
assert actions_a[0].htmx_trigger != actions_b[0].htmx_trigger
# JS callbacks are different (different prefixes)
assert actions_a[2].js_callback == "text_jumpPageUp"
assert actions_b[2].js_callback == "vad_jumpPageUp"
print("Multi-instance action tests passed!")Multi-instance action tests passed!Returns a dict mapping all card stack button IDs to their route URLs, for use as (or merged into) the url_map parameter of render_keyboard_system.
The keyboard system uses this map to create hidden HTMX buttons in the DOM. The JS callbacks (page jump, first/last) and the HTMX-triggered actions (nav up/down) both rely on these buttons existing.
Consumer merges with their own action URLs:
Build url_map for render_keyboard_system with all card stack navigation buttons.
Returns a dict mapping button IDs to URLs for all navigation actions: nav_up, nav_down, nav_first, nav_last, nav_page_up, nav_page_down.
Merge with consumer’s own action URLs when building the keyboard system: url_map = {build_card_stack_url_map(btn_ids, urls), my_action_urls}
from cjm_fasthtml_card_stack.core.models import CardStackUrls
from cjm_fasthtml_card_stack.core.config import CardStackConfig
# Test build_card_stack_url_map
_reset_prefix_counter()
config = CardStackConfig()
ids = CardStackHtmlIds(prefix=config.prefix)
btn_ids = CardStackButtonIds(prefix=config.prefix)
urls = CardStackUrls(
nav_up="/cs/nav_up", nav_down="/cs/nav_down",
nav_first="/cs/nav_first", nav_last="/cs/nav_last",
nav_page_up="/cs/nav_page_up", nav_page_down="/cs/nav_page_down",
nav_to_index="/cs/nav_to_index",
update_viewport="/cs/update_viewport",
save_width="/cs/save_width", save_scale="/cs/save_scale",
)
url_map = build_card_stack_url_map(btn_ids, urls)
# Verify all 6 navigation buttons are mapped
assert len(url_map) == 6
assert url_map[btn_ids.nav_up] == urls.nav_up
assert url_map[btn_ids.nav_down] == urls.nav_down
assert url_map[btn_ids.nav_first] == urls.nav_first
assert url_map[btn_ids.nav_last] == urls.nav_last
assert url_map[btn_ids.nav_page_up] == urls.nav_page_up
assert url_map[btn_ids.nav_page_down] == urls.nav_page_down
# Test merging with consumer urls
my_urls = {"my-split-btn": "/split", "my-merge-btn": "/merge"}
merged = {**url_map, **my_urls}
assert len(merged) == 8
print("build_card_stack_url_map tests passed!")build_card_stack_url_map tests passed!Renders hidden HTMX buttons for the JS-callback-triggered navigation actions (page jump, first/last). These are NOT created by render_keyboard_system because the corresponding KeyAction definitions use js_callback instead of htmx_trigger.
The full chain is: 1. Keyboard press → KeyAction with js_callback 2. Keyboard library calls window['cs0_jumpPageUp']() 3. Global wrapper calls window.cardStacks['cs0'].jumpPageUp() 4. JS function calls document.getElementById('cs0-btn-nav-page-up').click() 5. Hidden button fires HTMX POST to the route
Note: nav_up/nav_down buttons are created by render_keyboard_system (since those KeyActions use htmx_trigger). This function creates the remaining 4 navigation buttons that the keyboard system skips.
Render hidden HTMX buttons for JS-callback-triggered navigation actions.
Creates buttons for: page_up, page_down, first, last. These are clicked programmatically by the card stack’s JS functions. Must be included in the DOM alongside the keyboard system’s own buttons.
from fasthtml.common import to_xml
# Test render_card_stack_action_buttons
_reset_prefix_counter()
config = CardStackConfig()
ids = CardStackHtmlIds(prefix=config.prefix)
btn_ids = CardStackButtonIds(prefix=config.prefix)
buttons_div = render_card_stack_action_buttons(btn_ids, urls, ids)
html = to_xml(buttons_div)
# Verify all 4 hidden buttons are present with correct IDs
assert btn_ids.nav_page_up in html
assert btn_ids.nav_page_down in html
assert btn_ids.nav_first in html
assert btn_ids.nav_last in html
# Verify HTMX post URLs
assert urls.nav_page_up in html
assert urls.nav_page_down in html
assert urls.nav_first in html
assert urls.nav_last in html
# Verify hx-include references focused_index_input
assert ids.focused_index_input in html
# Verify hidden class (not inline style)
assert 'class="hidden"' in html
# Verify nav_up/nav_down are NOT included (keyboard system handles those)
assert btn_ids.nav_up not in html
assert btn_ids.nav_down not in html
print("render_card_stack_action_buttons tests passed!")render_card_stack_action_buttons tests passed!from cjm_fasthtml_keyboard_navigation.core.modes import KeyboardMode
from cjm_fasthtml_keyboard_navigation.core.manager import ZoneManager
# Consumer creates zone and gets library nav actions
_reset_prefix_counter()
config = CardStackConfig()
ids = CardStackHtmlIds(prefix=config.prefix)
btn_ids = CardStackButtonIds(prefix=config.prefix)
zone = create_card_stack_focus_zone(ids)
nav_actions = create_card_stack_nav_actions(
zone.id, btn_ids, config, disable_in_modes=("split",)
)
# Consumer adds their own actions
consumer_actions = (
KeyAction(
key="Enter",
htmx_trigger="my-split-btn",
not_modes=("split",),
description="Enter split mode",
),
KeyAction(
key="Backspace",
htmx_trigger="my-merge-btn",
not_modes=("split",),
description="Merge with previous",
),
)
# Consumer defines modes
split_mode = KeyboardMode(
name="split",
navigation_override=ScrollOnly(),
indicator_text="Split Mode",
)
# Consumer assembles full manager
manager = ZoneManager(
zones=(zone,),
actions=nav_actions + consumer_actions,
modes=(split_mode,),
prev_zone_key="",
next_zone_key="",
state_hidden_inputs=True,
)
assert len(manager.zones) == 1
assert len(manager.actions) == 12 # 10 library + 2 consumer
assert len(manager.modes) == 1
print(f"ZoneManager assembled: {len(manager.actions)} actions, {len(manager.modes)} modes")ZoneManager assembled: 12 actions, 1 modes