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

cjm_fasthtml_card_stack/core/config.py

@@ -0,0 +1,48 @@
+"""Configuration dataclass for card stack initialization."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/core/config.ipynb.
+
+# %% auto #0
+__all__ = ['CardStackConfig']
+
+# %% ../../nbs/core/config.ipynb #b1000003
+from dataclasses import dataclass, field
+from typing import Tuple
+
+# %% ../../nbs/core/config.ipynb #b1000005
+_prefix_counter: int = 0
+
+def _auto_prefix() -> str:  # Unique prefix string (e.g., "cs0", "cs1")
+    """Generate an auto-incrementing unique prefix."""
+    global _prefix_counter
+    p = f"cs{_prefix_counter}"
+    _prefix_counter += 1
+    return p
+
+def _reset_prefix_counter() -> None:
+    """Reset the prefix counter (for testing only)."""
+    global _prefix_counter
+    _prefix_counter = 0
+
+# %% ../../nbs/core/config.ipynb #b1000008
+@dataclass
+class CardStackConfig:
+    """Initialization-time settings for a card stack instance."""
+    prefix: str = field(default_factory=_auto_prefix)  # HTML ID prefix (auto-generated if omitted)
+
+    # Card count selector options
+    visible_count_options: Tuple[int, ...] = (1, 3, 5, 7, 9)  # Choices for card count dropdown
+
+    # Width slider bounds
+    card_width_min: int = 30    # Width slider minimum (rem)
+    card_width_max: int = 120   # Width slider maximum (rem)
+    card_width_step: int = 5    # Width slider step (rem)
+
+    # Scale slider bounds
+    card_scale_min: int = 50    # Scale slider minimum (%)
+    card_scale_max: int = 200   # Scale slider maximum (%)
+    card_scale_step: int = 10   # Scale slider step (%)
+
+    # Interaction
+    click_to_focus: bool = False  # Whether context cards get transparent click overlay
+    disable_scroll_in_modes: Tuple[str, ...] = ()  # Mode names where scroll-to-nav is suppressed

cjm_fasthtml_card_stack/core/constants.py

@@ -0,0 +1,41 @@
+"""CSS class constants, type aliases, and default values for the card stack library."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/core/constants.ipynb.
+
+# %% auto #0
+__all__ = ['CardRole', 'SCROLL_THRESHOLD', 'NAVIGATION_COOLDOWN', 'DEFAULT_VISIBLE_COUNT', 'DEFAULT_CARD_WIDTH',
+           'DEFAULT_CARD_SCALE', 'width_storage_key', 'scale_storage_key', 'card_count_storage_key']
+
+# %% ../../nbs/core/constants.ipynb #e1000003
+from typing import Literal
+
+# %% ../../nbs/core/constants.ipynb #e1000005
+CardRole = Literal["focused", "context"]
+
+# %% ../../nbs/core/constants.ipynb #e1000008
+SCROLL_THRESHOLD: int = 50      # Pixels of wheel delta to trigger navigation
+NAVIGATION_COOLDOWN: int = 100  # Milliseconds between scroll-triggered navigations
+
+# %% ../../nbs/core/constants.ipynb #e1000011
+def width_storage_key(
+    prefix: str  # Card stack instance prefix
+) -> str:  # localStorage key for card width
+    """Generate localStorage key for card width."""
+    return f"{prefix}-card-width"
+
+def scale_storage_key(
+    prefix: str  # Card stack instance prefix
+) -> str:  # localStorage key for card scale
+    """Generate localStorage key for card scale."""
+    return f"{prefix}-card-scale"
+
+def card_count_storage_key(
+    prefix: str  # Card stack instance prefix
+) -> str:  # localStorage key for card count
+    """Generate localStorage key for card count."""
+    return f"{prefix}-card-count"
+
+# %% ../../nbs/core/constants.ipynb #e1000014
+DEFAULT_VISIBLE_COUNT: int = 3  # Default number of cards visible in viewport
+DEFAULT_CARD_WIDTH: int = 80    # Default card stack width in rem
+DEFAULT_CARD_SCALE: int = 100   # Default card scale percentage

cjm_fasthtml_card_stack/core/html_ids.py

@@ -0,0 +1,94 @@
+"""Prefix-based HTML ID generator for card stack DOM elements."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/core/html_ids.ipynb.
+
+# %% auto #0
+__all__ = ['CardStackHtmlIds']
+
+# %% ../../nbs/core/html_ids.ipynb #c1000003
+from dataclasses import dataclass
+
+# %% ../../nbs/core/html_ids.ipynb #c1000005
+@dataclass
+class CardStackHtmlIds:
+    """Prefix-based HTML ID generator for card stack DOM elements."""
+    prefix: str  # ID prefix for this card stack instance
+
+    # --- Outer containers ---
+
+    @property
+    def card_stack(self) -> str:  # Full-width scroll capture container
+        """Outer card stack container."""
+        return f"{self.prefix}-card-stack"
+
+    @property
+    def card_stack_inner(self) -> str:  # Width-constrained CSS Grid container
+        """Inner grid container for 3-section layout."""
+        return f"{self.prefix}-card-stack-inner"
+
+    @property
+    def card_stack_empty(self) -> str:  # Empty state placeholder
+        """Empty state container."""
+        return f"{self.prefix}-card-stack-empty"
+
+    # --- Viewport sections ---
+
+    @property
+    def viewport_section_before(self) -> str:  # Cards before focused (1fr, justify-end)
+        """Viewport section for context cards before focused card."""
+        return f"{self.prefix}-viewport-section-before"
+
+    @property
+    def viewport_section_focused(self) -> str:  # Focused card (auto)
+        """Viewport section for the focused card."""
+        return f"{self.prefix}-viewport-section-focused"
+
+    @property
+    def viewport_section_after(self) -> str:  # Cards after focused (1fr, justify-start)
+        """Viewport section for context cards after focused card."""
+        return f"{self.prefix}-viewport-section-after"
+
+    # --- Dynamic slot IDs ---
+
+    def viewport_slot(
+        self,
+        index: int  # Slot index within the viewport
+    ) -> str:  # Slot element ID
+        """ID for an individual viewport slot container."""
+        return f"{self.prefix}-viewport-slot-{index}"
+
+    # --- Controls ---
+
+    @property
+    def card_count_select(self) -> str:  # Card count dropdown
+        """Card count selector dropdown."""
+        return f"{self.prefix}-card-count-select"
+
+    @property
+    def width_slider(self) -> str:  # Width range slider
+        """Card stack width slider."""
+        return f"{self.prefix}-width-slider"
+
+    @property
+    def scale_slider(self) -> str:  # Scale range slider
+        """Card stack scale slider."""
+        return f"{self.prefix}-scale-slider"
+
+    # --- Status elements ---
+
+    @property
+    def progress(self) -> str:  # Progress indicator
+        """Progress indicator element."""
+        return f"{self.prefix}-progress"
+
+    @property
+    def loading(self) -> str:  # Loading state container
+        """Loading state container."""
+        return f"{self.prefix}-loading"
+
+    # --- Hidden inputs ---
+
+    @property
+    def focused_index_input(self) -> str:  # Hidden input for keyboard nav focus recovery
+        """Hidden input storing the focused index for HTMX submissions."""
+        return f"{self.prefix}-focused-index"

cjm_fasthtml_card_stack/core/models.py

@@ -0,0 +1,53 @@
+"""Core dataclasses for card stack state, render context, and URL routing."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/core/models.ipynb.
+
+# %% auto #0
+__all__ = ['CardStackState', 'CardRenderContext', 'CardStackUrls']
+
+# %% ../../nbs/core/models.ipynb #a1000003
+from dataclasses import dataclass
+from typing import Optional
+
+# %% ../../nbs/core/models.ipynb #a1000005
+@dataclass
+class CardStackState:
+    """Viewport state for a card stack instance."""
+    focused_index: int = 0              # Index of focused item in the items list
+    visible_count: int = 3              # Number of card slots visible in viewport
+    card_width: int = 80               # Max width of card stack inner container in rem
+    card_scale: int = 100              # Content scale percentage (50-200)
+    active_mode: Optional[str] = None  # Current interaction mode name (consumer-defined)
+    focus_position: Optional[int] = None  # Slot offset for focused card (None=center, -1=bottom)
+
+# %% ../../nbs/core/models.ipynb #a1000010
+@dataclass
+class CardRenderContext:
+    """Context passed to the consumer's render_card callback."""
+    card_role: str                     # "focused" or "context"
+    index: int                         # Item's position in the full items list
+    total_items: int                   # Total item count
+    is_first: bool                     # Whether this is the first item
+    is_last: bool                      # Whether this is the last item
+    active_mode: Optional[str]         # Current interaction mode
+    card_scale: int                    # Scale percentage (50-200)
+    distance_from_focus: int           # Signed slot offset from focused card (0=focused)
+
+# %% ../../nbs/core/models.ipynb #a1000015
+@dataclass
+class CardStackUrls:
+    """URL bundle for card stack navigation and viewport operations."""
+
+    # Navigation URLs
+    nav_up: str = ""        # Navigate to previous item
+    nav_down: str = ""      # Navigate to next item
+    nav_first: str = ""     # Navigate to first item
+    nav_last: str = ""      # Navigate to last item
+    nav_page_up: str = ""   # Page jump up
+    nav_page_down: str = "" # Page jump down
+    nav_to_index: str = ""  # Navigate to specific index (click-to-focus)
+
+    # Viewport URLs
+    update_viewport: str = ""  # Change visible_count (full viewport re-render)
+    save_width: str = ""       # Persist card_width
+    save_scale: str = ""       # Persist card_scale

cjm_fasthtml_card_stack/helpers/focus.py

@@ -0,0 +1,72 @@
+"""Focus position resolution, viewport window calculation, and OOB focus sync."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/helpers/focus.ipynb.
+
+# %% auto #0
+__all__ = ['resolve_focus_slot', 'calculate_viewport_window', 'render_focus_oob']
+
+# %% ../../nbs/helpers/focus.ipynb #f1000003
+from typing import List, Optional, Tuple
+
+from fasthtml.common import Hidden
+
+from ..core.html_ids import CardStackHtmlIds
+
+# %% ../../nbs/helpers/focus.ipynb #f1000005
+def resolve_focus_slot(
+    focus_position: Optional[int],  # Slot offset (None=center, -1=bottom, 0=top)
+    visible_count: int,  # Number of visible card slots
+) -> int:  # Resolved 0-indexed slot position
+    """Resolve focus_position to an actual slot index within the viewport."""
+    if focus_position is None:
+        return visible_count // 2
+    if focus_position < 0:
+        slot = visible_count + focus_position
+    else:
+        slot = focus_position
+    return max(0, min(slot, visible_count - 1))
+
+# %% ../../nbs/helpers/focus.ipynb #f1000011
+def calculate_viewport_window(
+    focused_index: int,  # Index of the focused item
+    total_items: int,  # Total number of items
+    visible_count: int,  # Number of visible card slots
+    focus_position: Optional[int] = None,  # Focus slot (None=center)
+) -> List[Optional[int]]:  # Slot indices (None for placeholder slots)
+    """Calculate which item indices should be visible in each viewport slot."""
+    focus_slot = resolve_focus_slot(focus_position, visible_count)
+    slots_before = focus_slot
+    slots_after = visible_count - focus_slot - 1
+
+    result = []
+
+    # Slots before focused
+    for offset in range(slots_before, 0, -1):
+        idx = focused_index - offset
+        result.append(idx if idx >= 0 else None)
+
+    # Focused slot
+    result.append(focused_index if 0 <= focused_index < total_items else None)
+
+    # Slots after focused
+    for offset in range(1, slots_after + 1):
+        idx = focused_index + offset
+        result.append(idx if idx < total_items else None)
+
+    return result
+
+# %% ../../nbs/helpers/focus.ipynb #f1000019
+def render_focus_oob(
+    focused_index: int,  # The item index to focus
+    ids: CardStackHtmlIds,  # HTML IDs for this card stack instance
+    form_input_name: str = "focused_index",  # Field name for the form input
+) -> Tuple[Hidden, ...]:  # Hidden inputs with OOB swap
+    """Render OOB hidden inputs to synchronize focus after HTMX swap."""
+    return (
+        Hidden(
+            id=ids.focused_index_input,
+            name=form_input_name,
+            value=str(focused_index),
+            hx_swap_oob="true",
+        ),
+    )

cjm_fasthtml_card_stack/js/core.py

@@ -0,0 +1,303 @@
+"""Master composer for card stack JavaScript. Combines viewport height,"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/js/core.ipynb.
+
+# %% auto #0
+__all__ = ['global_callback_name', 'generate_card_stack_js']
+
+# %% ../../nbs/js/core.ipynb #jc000003
+from typing import Any, Tuple
+
+from fasthtml.common import Script
+
+from ..core.config import CardStackConfig
+from ..core.html_ids import CardStackHtmlIds
+from ..core.button_ids import CardStackButtonIds
+from ..core.models import CardStackUrls, CardStackState
+from cjm_fasthtml_card_stack.core.constants import (
+    width_storage_key, scale_storage_key, card_count_storage_key,
+    DEFAULT_CARD_WIDTH, DEFAULT_CARD_SCALE, DEFAULT_VISIBLE_COUNT,
+)
+from .viewport import generate_viewport_height_js
+from .scroll import generate_scroll_nav_js
+from .navigation import generate_page_nav_js
+
+# %% ../../nbs/js/core.ipynb #jc000005
+def _generate_width_mgmt_js(
+    ids: CardStackHtmlIds,  # HTML IDs for this instance
+    config: CardStackConfig,  # Config with slider bounds
+    urls: CardStackUrls,  # URL bundle (save_width)
+) -> str:  # JS code fragment for width management
+    """Generate JS for width slider management."""
+    storage_key = width_storage_key(config.prefix)
+    return f"""
+        // === Width Management ===
+        const _WIDTH_KEY = '{storage_key}';
+        let _saveWidthTimer = null;
+
+        function _saveWidthToServer(val) {{
+            if (!'{urls.save_width}') return;
+            clearTimeout(_saveWidthTimer);
+            _saveWidthTimer = setTimeout(function() {{
+                htmx.ajax('POST', '{urls.save_width}', {{
+                    swap: 'none', values: {{ card_width: val }}
+                }});
+            }}, 500);
+        }}
+
+        ns.updateWidth = function(value) {{
+            const inner = document.getElementById('{ids.card_stack_inner}');
+            if (!inner) return;
+            inner.style.maxWidth = value + 'rem';
+            try {{ localStorage.setItem(_WIDTH_KEY, value); }} catch (e) {{}}
+            const slider = document.getElementById('{ids.width_slider}');
+            if (slider && parseInt(slider.value) !== parseInt(value)) slider.value = value;
+            _saveWidthToServer(value);
+        }};
+
+        ns.decreaseWidth = function() {{
+            const slider = document.getElementById('{ids.width_slider}');
+            const current = slider ? parseInt(slider.value) : {DEFAULT_CARD_WIDTH};
+            ns.updateWidth(Math.max({config.card_width_min}, current - {config.card_width_step}));
+        }};
+
+        ns.increaseWidth = function() {{
+            const slider = document.getElementById('{ids.width_slider}');
+            const current = slider ? parseInt(slider.value) : {DEFAULT_CARD_WIDTH};
+            ns.updateWidth(Math.min({config.card_width_max}, current + {config.card_width_step}));
+        }};
+
+        ns.applyWidth = function() {{
+            const inner = document.getElementById('{ids.card_stack_inner}');
+            if (!inner) return;
+            let val = {DEFAULT_CARD_WIDTH};
+            try {{ const s = localStorage.getItem(_WIDTH_KEY); if (s) val = parseInt(s); }} catch (e) {{}}
+            inner.style.maxWidth = val + 'rem';
+            const slider = document.getElementById('{ids.width_slider}');
+            if (slider) slider.value = val;
+        }};
+    """
+
+# %% ../../nbs/js/core.ipynb #jc000006
+def _generate_scale_mgmt_js(
+    ids: CardStackHtmlIds,  # HTML IDs for this instance
+    config: CardStackConfig,  # Config with slider bounds
+    urls: CardStackUrls,  # URL bundle (save_scale)
+) -> str:  # JS code fragment for scale management
+    """Generate JS for scale slider management."""
+    storage_key = scale_storage_key(config.prefix)
+    return f"""
+        // === Scale Management ===
+        const _SCALE_KEY = '{storage_key}';
+        let _saveScaleTimer = null;
+
+        function _saveScaleToServer(val) {{
+            if (!'{urls.save_scale}') return;
+            clearTimeout(_saveScaleTimer);
+            _saveScaleTimer = setTimeout(function() {{
+                htmx.ajax('POST', '{urls.save_scale}', {{
+                    swap: 'none', values: {{ card_scale: val }}
+                }});
+            }}, 500);
+        }}
+
+        function _applyScaleCssProperty(val) {{
+            const cs = document.getElementById('{ids.card_stack}');
+            if (cs) cs.style.setProperty('--card-stack-scale', val);
+        }}
+
+        ns.updateScale = function(value) {{
+            _applyScaleCssProperty(value);
+            try {{ localStorage.setItem(_SCALE_KEY, value); }} catch (e) {{}}
+            const slider = document.getElementById('{ids.scale_slider}');
+            if (slider && parseInt(slider.value) !== parseInt(value)) slider.value = value;
+            _saveScaleToServer(value);
+        }};
+
+        ns.decreaseScale = function() {{
+            const slider = document.getElementById('{ids.scale_slider}');
+            const current = slider ? parseInt(slider.value) : {DEFAULT_CARD_SCALE};
+            ns.updateScale(Math.max({config.card_scale_min}, current - {config.card_scale_step}));
+        }};
+
+        ns.increaseScale = function() {{
+            const slider = document.getElementById('{ids.scale_slider}');
+            const current = slider ? parseInt(slider.value) : {DEFAULT_CARD_SCALE};
+            ns.updateScale(Math.min({config.card_scale_max}, current + {config.card_scale_step}));
+        }};
+
+        ns.applyScale = function() {{
+            let val = {DEFAULT_CARD_SCALE};
+            try {{ const s = localStorage.getItem(_SCALE_KEY); if (s) val = parseInt(s); }} catch (e) {{}}
+            _applyScaleCssProperty(val);
+            const slider = document.getElementById('{ids.scale_slider}');
+            if (slider) slider.value = val;
+        }};
+    """
+
+# %% ../../nbs/js/core.ipynb #jc000007
+def _generate_card_count_mgmt_js(
+    ids: CardStackHtmlIds,  # HTML IDs for this instance
+    config: CardStackConfig,  # Config with count options
+    urls: CardStackUrls,  # URL bundle (update_viewport)
+) -> str:  # JS code fragment for card count management
+    """Generate JS for card count selector management."""
+    storage_key = card_count_storage_key(config.prefix)
+    valid_counts = ', '.join(str(c) for c in config.visible_count_options)
+    return f"""
+        // === Card Count Management ===
+        const _COUNT_KEY = '{storage_key}';
+        const _VALID_COUNTS = [{valid_counts}];
+
+        function _getStoredCount() {{
+            try {{
+                const s = localStorage.getItem(_COUNT_KEY);
+                if (s) {{ const c = parseInt(s); if (_VALID_COUNTS.includes(c)) return c; }}
+            }} catch (e) {{}}
+            return {DEFAULT_VISIBLE_COUNT};
+        }}
+
+        ns.updateCardCount = function(value) {{
+            const count = parseInt(value);
+            if (!_VALID_COUNTS.includes(count)) return;
+            try {{ localStorage.setItem(_COUNT_KEY, count); }} catch (e) {{}}
+            const cardStack = document.getElementById('{ids.card_stack}');
+            if (cardStack) cardStack.dataset.visibleCount = count;
+            if ('{urls.update_viewport}') {{
+                htmx.ajax('POST', '{urls.update_viewport}', {{
+                    target: '#' + '{ids.card_stack}',
+                    swap: 'outerHTML',
+                    values: {{ visible_count: count }}
+                }});
+            }}
+        }};
+
+        function _syncCountDropdown() {{
+            const sel = document.getElementById('{ids.card_count_select}');
+            if (!sel) return;
+            const stored = _getStoredCount();
+            if (parseInt(sel.value) !== stored) sel.value = stored;
+        }}
+    """
+
+# %% ../../nbs/js/core.ipynb #jc000009
+def _generate_coordinator_js(
+    ids: CardStackHtmlIds,  # HTML IDs for this instance
+    config: CardStackConfig,  # Config for prefix-unique listener guards
+) -> str:  # JS code fragment for master coordinator
+    """Generate JS for the master coordinator and HTMX listener."""
+    guard_var = f"_csMasterListener_{config.prefix.replace('-', '_')}"
+    return f"""
+        // === Master Coordinator ===
+        ns.applyAllViewportSettings = function() {{
+            requestAnimationFrame(function() {{
+                if (ns.applyWidth) ns.applyWidth();
+                if (ns.applyScale) ns.applyScale();
+                if (ns.recalculateHeight) ns.recalculateHeight();
+
+                const cs = document.getElementById('{ids.card_stack}');
+                if (cs) {{
+                    cs._scrollNavSetup = false;
+                    if (ns._setupScrollNav) ns._setupScrollNav();
+                }}
+
+                requestAnimationFrame(function() {{
+                    const cs2 = document.getElementById('{ids.card_stack}');
+                    if (cs2) cs2.style.opacity = '1';
+                }});
+            }});
+        }};
+
+        // === HTMX Event Listener ===
+        if (!window.{guard_var}) {{
+            window.{guard_var} = true;
+            document.body.addEventListener('htmx:afterSettle', function(evt) {{
+                const target = evt.detail.target;
+                if (!target) return;
+                const cs = document.getElementById('{ids.card_stack}');
+                const isCSSwap = (
+                    target.id === '{ids.card_stack}' ||
+                    target.id === '{ids.card_stack_inner}' ||
+                    (cs && cs.contains(target))
+                );
+                if (isCSSwap) {{
+                    _syncCountDropdown();
+                    ns.applyAllViewportSettings();
+                }}
+            }});
+        }}
+
+        // === Initialize ===
+        requestAnimationFrame(function() {{
+            _syncCountDropdown();
+            setTimeout(function() {{ ns.applyAllViewportSettings(); }}, 50);
+        }});
+    """
+
+# %% ../../nbs/js/core.ipynb #jhgisn5noqk
+# Callback name constants — must match what create_card_stack_nav_actions uses
+_GLOBAL_CALLBACKS = (
+    "jumpPageUp",
+    "jumpPageDown",
+    "jumpToFirstItem",
+    "jumpToLastItem",
+    "decreaseWidth",
+    "increaseWidth",
+    "decreaseScale",
+    "increaseScale",
+)
+
+def global_callback_name(
+    prefix: str,  # Card stack instance prefix
+    callback: str,  # Base callback name (e.g., "jumpPageUp")
+) -> str:  # Global function name (e.g., "cs0_jumpPageUp")
+    """Generate a prefix-unique global callback name for keyboard navigation."""
+    return f"{prefix}_{callback}"
+
+def _generate_global_callbacks_js(
+    config: CardStackConfig,  # Config with prefix
+) -> str:  # JS code fragment registering global wrappers
+    """Register global wrappers for keyboard navigation system."""
+    lines = ["        // === Global Keyboard Callbacks ==="]
+    for cb in _GLOBAL_CALLBACKS:
+        global_name = global_callback_name(config.prefix, cb)
+        lines.append(f"        window['{global_name}'] = function() {{ if (ns.{cb}) ns.{cb}(); }};")
+    return "\n".join(lines)
+
+# %% ../../nbs/js/core.ipynb #jc000011
+def generate_card_stack_js(
+    ids: CardStackHtmlIds,  # HTML IDs for this instance
+    button_ids: CardStackButtonIds,  # Button IDs for keyboard triggers
+    config: CardStackConfig,  # Card stack configuration
+    urls: CardStackUrls,  # URL bundle for routing
+    container_id: str = "",  # Consumer's parent container ID (for height calc)
+    extra_scripts: Tuple[str, ...] = (),  # Additional JS to include in the IIFE
+) -> Any:  # Script element with all card stack JavaScript
+    """Compose all card stack JS into a single namespaced IIFE."""
+    prefix = config.prefix
+    extra_js = "\n".join(extra_scripts)
+
+    # Collect all fragments
+    viewport_js = generate_viewport_height_js(ids, container_id)
+    scroll_js = generate_scroll_nav_js(ids, button_ids, config.disable_scroll_in_modes)
+    page_nav_js = generate_page_nav_js(button_ids)
+    width_js = _generate_width_mgmt_js(ids, config, urls)
+    scale_js = _generate_scale_mgmt_js(ids, config, urls)
+    count_js = _generate_card_count_mgmt_js(ids, config, urls)
+    global_cbs_js = _generate_global_callbacks_js(config)
+    coordinator_js = _generate_coordinator_js(ids, config)
+
+    return Script(f"""(function() {{
+        window.cardStacks = window.cardStacks || {{}};
+        const ns = window.cardStacks['{prefix}'] = {{}};
+
+        {viewport_js}
+        {scroll_js}
+        {page_nav_js}
+        {width_js}
+        {scale_js}
+        {count_js}
+        {global_cbs_js}
+        {coordinator_js}
+        {extra_js}
+    }})();""")

cjm_fasthtml_card_stack/js/navigation.py

@@ -0,0 +1,37 @@
+"""JavaScript generator for page jump and first/last navigation helpers."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/js/navigation.ipynb.
+
+# %% auto #0
+__all__ = ['generate_page_nav_js']
+
+# %% ../../nbs/js/navigation.ipynb #jn000003
+from ..core.button_ids import CardStackButtonIds
+
+# %% ../../nbs/js/navigation.ipynb #jn000005
+def generate_page_nav_js(
+    button_ids: CardStackButtonIds,  # Button IDs for navigation triggers
+) -> str:  # JavaScript code fragment for page navigation
+    """Generate JS for page-based and first/last navigation functions."""
+    return f"""
+        // === Page Navigation ===
+        ns.jumpPageUp = function() {{
+            const btn = document.getElementById('{button_ids.nav_page_up}');
+            if (btn) btn.click();
+        }};
+
+        ns.jumpPageDown = function() {{
+            const btn = document.getElementById('{button_ids.nav_page_down}');
+            if (btn) btn.click();
+        }};
+
+        ns.jumpToFirstItem = function() {{
+            const btn = document.getElementById('{button_ids.nav_first}');
+            if (btn) btn.click();
+        }};
+
+        ns.jumpToLastItem = function() {{
+            const btn = document.getElementById('{button_ids.nav_last}');
+            if (btn) btn.click();
+        }};
+    """