Handlers

Response builder functions for card stack operations (Tier 1 API).

Response Builders

Composable functions that build HTMX response parts. Consumers can use these directly or call the higher-level card_stack_navigate functions.

---

source

build_slots_response

def build_slots_response(
    card_items:List, # All data items
    state:CardStackState, # Current card stack state
    config:CardStackConfig, # Card stack configuration
    ids:CardStackHtmlIds, # HTML IDs for this instance
    urls:CardStackUrls, # URL bundle for navigation
    render_card:Callable, # Card renderer callback
)->List: # OOB slot elements (3 viewport sections)

Build OOB slot updates for the viewport sections only.

---

source

build_nav_response

def build_nav_response(
    card_items:List, # All data items
    state:CardStackState, # Current card stack state
    config:CardStackConfig, # Card stack configuration
    ids:CardStackHtmlIds, # HTML IDs for this instance
    urls:CardStackUrls, # URL bundle for navigation
    render_card:Callable, # Card renderer callback
    progress_label:str='Item', # Label for progress indicator
    form_input_name:str='focused_index', # Name for the focused index hidden input
)->Tuple: # OOB elements (slots + progress + focus + scrollbar)

Build full OOB response for navigation: slots + progress + focus inputs + scrollbar.

Navigation

---

source

card_stack_navigate

def card_stack_navigate(
    direction:str, # "up", "down", "first", "last", "page_up", "page_down"
    card_items:List, # All data items
    state:CardStackState, # Current card stack state (mutated in place)
    config:CardStackConfig, # Card stack configuration
    ids:CardStackHtmlIds, # HTML IDs for this instance
    urls:CardStackUrls, # URL bundle for navigation
    render_card:Callable, # Card renderer callback
    progress_label:str='Item', # Label for progress indicator
    form_input_name:str='focused_index', # Name for the focused index hidden input
)->Tuple: # OOB elements (slots + progress + focus)

Navigate to a different item. Mutates state.focused_index in place.

---

source

card_stack_navigate_to_index

def card_stack_navigate_to_index(
    target_index:int, # Target item index to navigate to
    card_items:List, # All data items
    state:CardStackState, # Current card stack state (mutated in place)
    config:CardStackConfig, # Card stack configuration
    ids:CardStackHtmlIds, # HTML IDs for this instance
    urls:CardStackUrls, # URL bundle for navigation
    render_card:Callable, # Card renderer callback
    progress_label:str='Item', # Label for progress indicator
    form_input_name:str='focused_index', # Name for the focused index hidden input
)->Tuple: # OOB elements (slots + progress + focus)

Navigate to a specific item index. Mutates state.focused_index in place.

Viewport Update

---

source

card_stack_update_viewport

def card_stack_update_viewport(
    visible_count:int, # New number of visible cards
    card_items:List, # All data items
    state:CardStackState, # Current card stack state (mutated in place)
    config:CardStackConfig, # Card stack configuration
    ids:CardStackHtmlIds, # HTML IDs for this instance
    urls:CardStackUrls, # URL bundle for navigation
    render_card:Callable, # Card renderer callback
    is_auto:bool=True, # Whether this update came from auto-adjust mode
)->Tuple: # OOB section elements (3 viewport sections + scrollbar)

Update viewport with new card count via OOB section swaps. Mutates state in place.

Preference Persistence

---

source

card_stack_save_width

def card_stack_save_width(
    state:CardStackState, # Current card stack state (mutated in place)
    card_width:int, # Card stack width in rem
    config:CardStackConfig, # Card stack configuration (for clamping bounds)
)->None: # No response (swap=none on client)

Save card stack width. Mutates state.card_width in place.

---

source

card_stack_save_scale

def card_stack_save_scale(
    state:CardStackState, # Current card stack state (mutated in place)
    card_scale:int, # Card stack scale percentage
    config:CardStackConfig, # Card stack configuration (for clamping bounds)
)->None: # No response (swap=none on client)

Save card stack scale. Mutates state.card_scale in place.

Tests

from cjm_fasthtml_card_stack.core.config import _reset_prefix_counter
from cjm_fasthtml_card_stack.core.models import CardStackState, CardRenderContext, CardStackUrls
from cjm_fasthtml_card_stack.core.html_ids import CardStackHtmlIds

# Simple render_card for testing
from fasthtml.common import Div, Span

def _test_render_card(item, context: CardRenderContext):
    return Div(Span(f"Item {context.index}: {item}"), cls=f"card-{context.card_role}")

# Setup test fixtures
_reset_prefix_counter()
_test_config = CardStackConfig(prefix="test")
_test_ids = CardStackHtmlIds(prefix="test")
_test_urls = CardStackUrls(
    nav_up="/nav_up", nav_down="/nav_down",
    nav_first="/nav_first", nav_last="/nav_last",
    nav_page_up="/nav_page_up", nav_page_down="/nav_page_down",
    nav_to_index="/nav_to_index",
    update_viewport="/update_viewport",
    save_width="/save_width", save_scale="/save_scale",
)
_test_items = [f"Item {i}" for i in range(20)]

print("Test fixtures ready.")

Test fixtures ready.

# Test card_stack_navigate — basic down navigation
state = CardStackState(focused_index=5, visible_count=3)
result = card_stack_navigate(
    "down", _test_items, state, _test_config, _test_ids, _test_urls, _test_render_card
)
assert state.focused_index == 6  # Mutated in place
assert len(result) > 0  # Returns OOB elements
print("Navigate down test passed!")

Navigate down test passed!

# Test card_stack_navigate — boundary clamping
state = CardStackState(focused_index=0, visible_count=3)
card_stack_navigate("up", _test_items, state, _test_config, _test_ids, _test_urls, _test_render_card)
assert state.focused_index == 0  # Can't go below 0

state = CardStackState(focused_index=19, visible_count=3)
card_stack_navigate("down", _test_items, state, _test_config, _test_ids, _test_urls, _test_render_card)
assert state.focused_index == 19  # Can't go above total-1
print("Navigate boundary clamping tests passed!")

Navigate boundary clamping tests passed!

# Test card_stack_navigate — first/last
state = CardStackState(focused_index=10, visible_count=3)
card_stack_navigate("first", _test_items, state, _test_config, _test_ids, _test_urls, _test_render_card)
assert state.focused_index == 0

card_stack_navigate("last", _test_items, state, _test_config, _test_ids, _test_urls, _test_render_card)
assert state.focused_index == 19
print("Navigate first/last tests passed!")

Navigate first/last tests passed!

# Test card_stack_navigate — page jump uses visible_count - 1
state = CardStackState(focused_index=10, visible_count=5)
card_stack_navigate("page_down", _test_items, state, _test_config, _test_ids, _test_urls, _test_render_card)
assert state.focused_index == 14  # 10 + (5-1) = 14

state = CardStackState(focused_index=10, visible_count=3)
card_stack_navigate("page_up", _test_items, state, _test_config, _test_ids, _test_urls, _test_render_card)
assert state.focused_index == 8  # 10 - (3-1) = 8

# Single card: page jump = 1
state = CardStackState(focused_index=10, visible_count=1)
card_stack_navigate("page_down", _test_items, state, _test_config, _test_ids, _test_urls, _test_render_card)
assert state.focused_index == 11  # 10 + max(1, 1-1) = 10 + 1 = 11
print("Page jump tests passed!")

Page jump tests passed!

# Test card_stack_navigate — empty items
state = CardStackState(focused_index=0, visible_count=3)
result = card_stack_navigate(
    "down", [], state, _test_config, _test_ids, _test_urls, _test_render_card
)
assert state.focused_index == 0  # Unchanged
assert len(result) > 0  # Still returns elements (empty viewport sections)
print("Empty items navigate test passed!")

Empty items navigate test passed!

# Test card_stack_navigate_to_index
state = CardStackState(focused_index=0, visible_count=3)
result = card_stack_navigate_to_index(
    15, _test_items, state, _test_config, _test_ids, _test_urls, _test_render_card
)
assert state.focused_index == 15

# Clamps out-of-range
card_stack_navigate_to_index(
    100, _test_items, state, _test_config, _test_ids, _test_urls, _test_render_card
)
assert state.focused_index == 19  # Clamped to total-1

card_stack_navigate_to_index(
    -5, _test_items, state, _test_config, _test_ids, _test_urls, _test_render_card
)
assert state.focused_index == 0  # Clamped to 0
print("Navigate to index tests passed!")

Navigate to index tests passed!

# Test form_input_name is passed through navigation
from fasthtml.common import to_xml

state = CardStackState(focused_index=5, visible_count=3)
result = card_stack_navigate(
    "down", _test_items, state, _test_config, _test_ids, _test_urls, _test_render_card,
    form_input_name="segment_index"
)
# Find the Hidden input in the result tuple
hidden_found = False
for el in result:
    html = to_xml(el)
    if 'name="segment_index"' in html:
        hidden_found = True
        assert 'value="6"' in html  # focused_index after nav down from 5
        break
assert hidden_found, "Hidden input with custom form_input_name not found in response"
print("form_input_name passthrough test passed!")

form_input_name passthrough test passed!

# Test card_stack_update_viewport returns OOB section tuple + scrollbar
from fasthtml.common import to_xml

state = CardStackState(focused_index=5, visible_count=3)
result = card_stack_update_viewport(
    7, _test_items, state, _test_config, _test_ids, _test_urls, _test_render_card
)
assert state.visible_count == 7  # Mutated in place
assert state.is_auto_mode == True  # Default is_auto=True
assert isinstance(result, tuple)
assert len(result) == 4  # 3 viewport sections + scrollbar OOB

# Verify each viewport section has OOB swap attribute
for section in result[:3]:
    html = to_xml(section)
    assert 'hx-swap-oob="innerHTML"' in html

# Verify section IDs
assert f'id="{_test_ids.viewport_section_before}"' in to_xml(result[0])
assert f'id="{_test_ids.viewport_section_focused}"' in to_xml(result[1])
assert f'id="{_test_ids.viewport_section_after}"' in to_xml(result[2])

# Verify scrollbar OOB
scrollbar_html = to_xml(result[3])
assert 'hx-swap-oob="outerHTML"' in scrollbar_html
assert 'test-scrollbar-track' in scrollbar_html

# Test is_auto=False saves to state
state2 = CardStackState(focused_index=0, visible_count=1)
card_stack_update_viewport(
    5, _test_items, state2, _test_config, _test_ids, _test_urls, _test_render_card,
    is_auto=False
)
assert state2.visible_count == 5
assert state2.is_auto_mode == False
print("Update viewport OOB test passed!")

Update viewport OOB test passed!

# Test card_stack_save_width
state = CardStackState(card_width=80)
card_stack_save_width(state, 60, _test_config)
assert state.card_width == 60

# Clamping above max
card_stack_save_width(state, 200, _test_config)
assert state.card_width == _test_config.card_width_max  # 120

# Clamping below min
card_stack_save_width(state, 10, _test_config)
assert state.card_width == _test_config.card_width_min  # 30
print("Save width tests passed!")

Save width tests passed!

# Test card_stack_save_scale
state = CardStackState(card_scale=100)
card_stack_save_scale(state, 150, _test_config)
assert state.card_scale == 150

# Clamping above max
card_stack_save_scale(state, 300, _test_config)
assert state.card_scale == _test_config.card_scale_max  # 200

# Clamping below min
card_stack_save_scale(state, 10, _test_config)
assert state.card_scale == _test_config.card_scale_min  # 50
print("Save scale tests passed!")

Save scale tests passed!