cjm-fasthtml-card-stack 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

cjm_fasthtml_card_stack/js/scroll.py

@@ -0,0 +1,76 @@
+"""JavaScript generator for scroll-to-nav conversion."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/js/scroll.ipynb.
+
+# %% auto #0
+__all__ = ['generate_scroll_nav_js']
+
+# %% ../../nbs/js/scroll.ipynb #js000003
+from typing import Tuple
+
+from ..core.html_ids import CardStackHtmlIds
+from ..core.button_ids import CardStackButtonIds
+from ..core.constants import SCROLL_THRESHOLD, NAVIGATION_COOLDOWN
+
+# %% ../../nbs/js/scroll.ipynb #js000005
+def generate_scroll_nav_js(
+    ids: CardStackHtmlIds,  # HTML IDs for this card stack instance
+    button_ids: CardStackButtonIds,  # Button IDs for navigation triggers
+    disable_in_modes: Tuple[str, ...] = (),  # Mode names where scroll nav is suppressed
+) -> str:  # JavaScript code fragment for scroll navigation
+    """Generate JS for scroll wheel to navigation conversion."""
+    # Build mode check
+    if disable_in_modes:
+        modes_array = ', '.join(f"'{m}'" for m in disable_in_modes)
+        mode_check = f"""
+        function isScrollDisabled() {{
+            if (typeof window.kbNav !== 'undefined') {{
+                const state = window.kbNav.getState();
+                const disabledModes = [{modes_array}];
+                return state && disabledModes.includes(state.currentMode);
+            }}
+            return false;
+        }}
+        """
+        mode_guard = "if (isScrollDisabled()) return;"
+    else:
+        mode_check = ""
+        mode_guard = ""
+
+    return f"""
+        // === Scroll Navigation ===
+        const _scrollState = {{ accumulatedDelta: 0, lastNavTime: 0 }};
+        const _SCROLL_THRESHOLD = {SCROLL_THRESHOLD};
+        const _NAV_COOLDOWN = {NAVIGATION_COOLDOWN};
+        {mode_check}
+        function setupScrollNavigation() {{
+            const cardStack = document.getElementById('{ids.card_stack}');
+            if (!cardStack || cardStack._scrollNavSetup) return;
+            cardStack._scrollNavSetup = true;
+
+            cardStack.addEventListener('wheel', function(evt) {{
+                {mode_guard}
+                evt.preventDefault();
+
+                const now = Date.now();
+                if (now - _scrollState.lastNavTime > _NAV_COOLDOWN * 2) {{
+                    _scrollState.accumulatedDelta = 0;
+                }}
+                _scrollState.accumulatedDelta += evt.deltaY;
+
+                if (Math.abs(_scrollState.accumulatedDelta) >= _SCROLL_THRESHOLD) {{
+                    if (now - _scrollState.lastNavTime >= _NAV_COOLDOWN) {{
+                        const btnId = _scrollState.accumulatedDelta > 0
+                            ? '{button_ids.nav_down}' : '{button_ids.nav_up}';
+                        _scrollState.accumulatedDelta = 0;
+                        _scrollState.lastNavTime = now;
+                        const btn = document.getElementById(btnId);
+                        if (btn) btn.click();
+                    }}
+                }}
+            }}, {{ passive: false }});
+        }}
+
+        // Expose for master coordinator to re-setup after swaps
+        ns._setupScrollNav = setupScrollNavigation;
+    """

cjm_fasthtml_card_stack/js/viewport.py

@@ -0,0 +1,124 @@
+"""JavaScript generator for dynamic viewport height calculation."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/js/viewport.ipynb.
+
+# %% auto #0
+__all__ = ['generate_viewport_height_js']
+
+# %% ../../nbs/js/viewport.ipynb #jv000003
+from ..core.html_ids import CardStackHtmlIds
+
+# %% ../../nbs/js/viewport.ipynb #jv000005
+def generate_viewport_height_js(
+    ids: CardStackHtmlIds,  # HTML IDs for this card stack instance
+    container_id: str = "",  # Consumer's parent container ID (empty = use card stack parent)
+) -> str:  # JavaScript code fragment for viewport height calculation
+    """Generate JS for dynamic viewport height calculation.
+    
+    Uses the browser's layout engine to measure the space consumed by sibling
+    elements rather than summing individual heights. This naturally handles
+    margin collapsing regardless of the container's display type.
+    
+    Strategy: temporarily collapse the card stack to 0 height, measure how
+    much vertical space the remaining content occupies, then set the card
+    stack height to fill the remaining viewport space.
+    """
+    # Build container resolution logic — guarded against null for SPA navigation
+    if container_id:
+        container_resolution = f"""
+            const container = document.getElementById('{container_id}');"""
+    else:
+        container_resolution = f"""
+            const _csEl = document.getElementById('{ids.card_stack}');
+            if (!_csEl) return 400;
+            const container = _csEl.parentElement;"""
+
+    return f"""
+        // === Viewport Height Calculation ===
+
+        function calculateSpaceBelowContainer(container) {{
+            let spaceUsedBelow = 0;
+            let currentElement = container;
+            let parent = container.parentElement;
+            while (parent && parent !== document.documentElement) {{
+                const parentStyles = getComputedStyle(parent);
+                spaceUsedBelow += parseFloat(parentStyles.paddingBottom) || 0;
+                spaceUsedBelow += parseFloat(parentStyles.borderBottomWidth) || 0;
+                let foundCurrent = false;
+                for (const sibling of parent.children) {{
+                    if (sibling === currentElement) {{ foundCurrent = true; continue; }}
+                    if (!foundCurrent) continue;
+                    if (sibling.nodeType !== Node.ELEMENT_NODE) continue;
+                    const tag = sibling.tagName;
+                    if (tag === 'SCRIPT' || tag === 'STYLE') continue;
+                    if (tag === 'INPUT' && sibling.type === 'hidden') continue;
+                    const s = getComputedStyle(sibling);
+                    if (s.display === 'none') continue;
+                    const mt = parseFloat(s.marginTop) || 0;
+                    const mb = parseFloat(s.marginBottom) || 0;
+                    spaceUsedBelow += sibling.getBoundingClientRect().height + mt + mb;
+                }}
+                currentElement = parent;
+                parent = parent.parentElement;
+            }}
+            return spaceUsedBelow;
+        }}
+
+        function calculateAndSetViewportHeight() {{
+            {container_resolution}
+            const cardStack = document.getElementById('{ids.card_stack}');
+            const cardStackInner = document.getElementById('{ids.card_stack_inner}');
+            if (!container || !cardStack) return 400;
+
+            // Temporarily collapse the card stack to measure sibling space.
+            // Save current values to restore if something goes wrong.
+            const prevHeight = cardStack.style.height;
+            const prevMinHeight = cardStack.style.minHeight;
+            const prevMaxHeight = cardStack.style.maxHeight;
+            
+            cardStack.style.height = '0px';
+            cardStack.style.minHeight = '0px';
+            cardStack.style.maxHeight = '0px';
+
+            // Now measure: with the card stack collapsed, the container's
+            // height is driven entirely by the sibling content + padding.
+            // The browser handles margin collapsing for us.
+            const containerRect = container.getBoundingClientRect();
+            const siblingSpace = containerRect.height;
+
+            // Restore immediately (before any repaint)
+            cardStack.style.height = prevHeight;
+            cardStack.style.minHeight = prevMinHeight;
+            cardStack.style.maxHeight = prevMaxHeight;
+
+            const windowHeight = window.innerHeight;
+            const containerTop = containerRect.top;
+            const spaceBelow = calculateSpaceBelowContainer(container);
+
+            const viewportHeight = Math.floor(Math.max(200,
+                windowHeight - containerTop - siblingSpace - spaceBelow
+            ));
+
+            cardStack.style.height = viewportHeight + 'px';
+            cardStack.style.maxHeight = viewportHeight + 'px';
+            cardStack.style.minHeight = viewportHeight + 'px';
+            if (cardStackInner) cardStackInner.style.height = viewportHeight + 'px';
+
+            return viewportHeight;
+        }}
+
+        function _debounce(fn, delay) {{
+            let tid;
+            return function(...args) {{ clearTimeout(tid); tid = setTimeout(() => fn.apply(this, args), delay); }};
+        }}
+
+        const _debouncedResize = _debounce(calculateAndSetViewportHeight, 100);
+
+        if (!window._csResizeListener_{ids.prefix.replace('-', '_')}) {{
+            window._csResizeListener_{ids.prefix.replace('-', '_')} = true;
+            window.addEventListener('resize', _debouncedResize);
+        }}
+
+        // Expose on namespace
+        ns.recalculateHeight = calculateAndSetViewportHeight;
+    """

cjm_fasthtml_card_stack/keyboard/actions.py

@@ -0,0 +1,200 @@
+"""Keyboard navigation focus zone and action factories for the card stack."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/keyboard/actions.ipynb.
+
+# %% auto #0
+__all__ = ['create_card_stack_focus_zone', 'create_card_stack_nav_actions', 'build_card_stack_url_map',
+           'render_card_stack_action_buttons']
+
+# %% ../../nbs/keyboard/actions.ipynb #ka000003
+from typing import Optional, Tuple, Dict
+
+from fasthtml.common import Button, Div, FT
+from cjm_fasthtml_tailwind.utilities.layout import display_tw
+
+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.navigation import ScrollOnly
+
+from ..core.config import CardStackConfig
+from ..core.html_ids import CardStackHtmlIds
+from ..core.button_ids import CardStackButtonIds
+from ..core.models import CardStackUrls
+from ..js.core import global_callback_name
+
+# %% ../../nbs/keyboard/actions.ipynb #ka000005
+def create_card_stack_focus_zone(
+    ids: CardStackHtmlIds,  # HTML IDs for this card stack instance
+    on_focus_change: Optional[str] = None,  # JS callback name on focus change
+    hidden_input_prefix: Optional[str] = None,  # Prefix for keyboard nav hidden inputs
+    data_attributes: Tuple[str, ...] = (),  # Data attributes to track on focused items
+) -> FocusZone:  # Configured focus zone for the card stack
+    """Create a focus zone for a card stack viewport."""
+    return FocusZone(
+        id=ids.card_stack,
+        item_selector="[data-card-role='focused']",
+        navigation=ScrollOnly(),
+        data_attributes=data_attributes,
+        zone_focus_classes=(),
+        item_focus_classes=(),
+        on_focus_change=on_focus_change or "",
+        hidden_input_prefix=hidden_input_prefix or f"{ids.prefix}-focused",
+    )
+
+# %% ../../nbs/keyboard/actions.ipynb #ka000010
+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[str, ...] = (),  # Mode names that disable navigation
+) -> Tuple[KeyAction, ...]:  # Standard card stack navigation actions
+    """Create standard keyboard navigation actions for a card stack."""
+    zone_ids = (zone_id,)
+    not_modes = disable_in_modes if disable_in_modes else ()
+    prefix = config.prefix
+
+    return (
+        # --- Item navigation (HTMX triggers) ---
+        KeyAction(
+            key="ArrowUp",
+            htmx_trigger=button_ids.nav_up,
+            zone_ids=zone_ids,
+            not_modes=not_modes,
+            description="Previous item",
+            hint_group="Navigation",
+        ),
+        KeyAction(
+            key="ArrowDown",
+            htmx_trigger=button_ids.nav_down,
+            zone_ids=zone_ids,
+            not_modes=not_modes,
+            description="Next item",
+            hint_group="Navigation",
+        ),
+
+        # --- Page jump (JS callbacks, prefix-unique) ---
+        KeyAction(
+            key="ArrowUp",
+            modifiers=frozenset({"ctrl"}),
+            js_callback=global_callback_name(prefix, "jumpPageUp"),
+            zone_ids=zone_ids,
+            not_modes=not_modes,
+            description="Page up",
+            hint_group="Navigation",
+        ),
+        KeyAction(
+            key="ArrowDown",
+            modifiers=frozenset({"ctrl"}),
+            js_callback=global_callback_name(prefix, "jumpPageDown"),
+            zone_ids=zone_ids,
+            not_modes=not_modes,
+            description="Page down",
+            hint_group="Navigation",
+        ),
+
+        # --- First/last item (JS callbacks, prefix-unique) ---
+        KeyAction(
+            key="ArrowUp",
+            modifiers=frozenset({"ctrl", "shift"}),
+            js_callback=global_callback_name(prefix, "jumpToFirstItem"),
+            zone_ids=zone_ids,
+            not_modes=not_modes,
+            description="First item",
+            hint_group="Navigation",
+        ),
+        KeyAction(
+            key="ArrowDown",
+            modifiers=frozenset({"ctrl", "shift"}),
+            js_callback=global_callback_name(prefix, "jumpToLastItem"),
+            zone_ids=zone_ids,
+            not_modes=not_modes,
+            description="Last item",
+            hint_group="Navigation",
+        ),
+
+        # --- Width adjustment (available in any mode) ---
+        KeyAction(
+            key="[",
+            js_callback=global_callback_name(prefix, "decreaseWidth"),
+            zone_ids=zone_ids,
+            description="Narrower",
+            hint_group="View",
+        ),
+        KeyAction(
+            key="]",
+            js_callback=global_callback_name(prefix, "increaseWidth"),
+            zone_ids=zone_ids,
+            description="Wider",
+            hint_group="View",
+        ),
+
+        # --- Scale adjustment (available in any mode) ---
+        KeyAction(
+            key="-",
+            js_callback=global_callback_name(prefix, "decreaseScale"),
+            zone_ids=zone_ids,
+            description="Smaller",
+            hint_group="View",
+        ),
+        KeyAction(
+            key="=",
+            js_callback=global_callback_name(prefix, "increaseScale"),
+            zone_ids=zone_ids,
+            description="Larger",
+            hint_group="View",
+        ),
+    )
+
+# %% ../../nbs/keyboard/actions.ipynb #q6nqfsne4vf
+def build_card_stack_url_map(
+    button_ids: CardStackButtonIds,  # Button IDs for this card stack instance
+    urls: CardStackUrls,  # URL bundle for routing
+) -> Dict[str, str]:  # Mapping of button ID -> route URL
+    """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}
+    """
+    return {
+        button_ids.nav_up: urls.nav_up,
+        button_ids.nav_down: urls.nav_down,
+        button_ids.nav_first: urls.nav_first,
+        button_ids.nav_last: urls.nav_last,
+        button_ids.nav_page_up: urls.nav_page_up,
+        button_ids.nav_page_down: urls.nav_page_down,
+    }
+
+# %% ../../nbs/keyboard/actions.ipynb #m9cf824czm
+def render_card_stack_action_buttons(
+    button_ids: CardStackButtonIds,  # Button IDs for this card stack instance
+    urls: CardStackUrls,  # URL bundle for routing
+    ids: CardStackHtmlIds,  # HTML IDs (for hx-include of focused_index_input)
+) -> 'FT':  # Div containing hidden action buttons
+    """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.
+    """
+    include_selector = f"#{ids.focused_index_input}"
+    hidden_cls = str(display_tw.hidden)
+
+    def _btn(btn_id, url):
+        return Button(
+            id=btn_id,
+            hx_post=url,
+            hx_swap="none",
+            hx_include=include_selector,
+            cls=hidden_cls,
+        )
+
+    return Div(
+        _btn(button_ids.nav_page_up, urls.nav_page_up),
+        _btn(button_ids.nav_page_down, urls.nav_page_down),
+        _btn(button_ids.nav_first, urls.nav_first),
+        _btn(button_ids.nav_last, urls.nav_last),
+        cls=hidden_cls,
+    )

cjm_fasthtml_card_stack/routes/handlers.py

@@ -0,0 +1,158 @@
+"""Response builder functions for card stack operations (Tier 1 API)."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/routes/handlers.ipynb.
+
+# %% auto #0
+__all__ = ['build_slots_response', 'build_nav_response', 'card_stack_navigate', 'card_stack_navigate_to_index',
+           'card_stack_update_viewport', 'card_stack_save_width', 'card_stack_save_scale']
+
+# %% ../../nbs/routes/handlers.ipynb #h1000003
+from typing import Any, Callable, List, Optional, Tuple
+
+from ..core.config import CardStackConfig
+from ..core.html_ids import CardStackHtmlIds
+from ..core.models import CardStackState, CardStackUrls
+from ..components.viewport import render_all_slots_oob, render_viewport
+from ..components.progress import render_progress_indicator
+from ..helpers.focus import render_focus_oob
+
+# %% ../../nbs/routes/handlers.ipynb #h1000005
+def build_slots_response(
+    card_items: List[Any],  # 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[Any]:  # OOB slot elements (3 viewport sections)
+    """Build OOB slot updates for the viewport sections only."""
+    return render_all_slots_oob(
+        card_items=card_items,
+        state=state,
+        config=config,
+        ids=ids,
+        urls=urls,
+        render_card=render_card,
+    )
+
+# %% ../../nbs/routes/handlers.ipynb #h1000006
+def build_nav_response(
+    card_items: List[Any],  # 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
+) -> Tuple:  # OOB elements (slots + progress + focus)
+    """Build full OOB response for navigation: slots + progress + focus inputs."""
+    slots_oob = build_slots_response(
+        card_items=card_items, state=state, config=config,
+        ids=ids, urls=urls, render_card=render_card,
+    )
+    progress_oob = render_progress_indicator(
+        state.focused_index, len(card_items), ids,
+        label=progress_label, oob=True,
+    )
+    focus_oob = render_focus_oob(state.focused_index, ids)
+    return (*slots_oob, progress_oob, *focus_oob)
+
+# %% ../../nbs/routes/handlers.ipynb #h1000008
+def card_stack_navigate(
+    direction: str,  # "up", "down", "first", "last", "page_up", "page_down"
+    card_items: List[Any],  # 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
+) -> Tuple:  # OOB elements (slots + progress + focus)
+    """Navigate to a different item. Mutates state.focused_index in place."""
+    total = len(card_items)
+    if total == 0:
+        return build_slots_response(
+            card_items, state, config, ids, urls, render_card
+        )
+
+    # Page jump = visible_count - 1 (one overlap card), minimum 1
+    page_jump = max(1, state.visible_count - 1)
+
+    direction_map = {
+        "up": max(0, state.focused_index - 1),
+        "down": min(total - 1, state.focused_index + 1),
+        "first": 0,
+        "last": total - 1,
+        "page_up": max(0, state.focused_index - page_jump),
+        "page_down": min(total - 1, state.focused_index + page_jump),
+    }
+    state.focused_index = direction_map.get(direction, state.focused_index)
+
+    return build_nav_response(
+        card_items, state, config, ids, urls, render_card,
+        progress_label=progress_label,
+    )
+
+# %% ../../nbs/routes/handlers.ipynb #h1000009
+def card_stack_navigate_to_index(
+    target_index: int,  # Target item index to navigate to
+    card_items: List[Any],  # 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
+) -> Tuple:  # OOB elements (slots + progress + focus)
+    """Navigate to a specific item index. Mutates state.focused_index in place."""
+    total = len(card_items)
+    if total == 0:
+        return build_slots_response(
+            card_items, state, config, ids, urls, render_card
+        )
+
+    state.focused_index = max(0, min(total - 1, target_index))
+
+    return build_nav_response(
+        card_items, state, config, ids, urls, render_card,
+        progress_label=progress_label,
+    )
+
+# %% ../../nbs/routes/handlers.ipynb #h1000011
+def card_stack_update_viewport(
+    visible_count: int,  # New number of visible cards
+    card_items: List[Any],  # 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
+) -> Any:  # Full viewport component (outerHTML swap)
+    """Update viewport with new card count. Mutates state.visible_count in place."""
+    state.visible_count = visible_count
+    return render_viewport(
+        card_items=card_items,
+        state=state,
+        config=config,
+        ids=ids,
+        urls=urls,
+        render_card=render_card,
+    )
+
+# %% ../../nbs/routes/handlers.ipynb #h1000013
+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."""
+    state.card_width = max(config.card_width_min, min(config.card_width_max, card_width))
+
+# %% ../../nbs/routes/handlers.ipynb #h1000014
+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."""
+    state.card_scale = max(config.card_scale_min, min(config.card_scale_max, card_scale))