cjm-fasthtml-card-stack 0.0.3__py3-none-any.whl → 0.0.4__py3-none-any.whl

cjm_fasthtml_card_stack/__init__.py

@@ -1 +1 @@
-__version__ = "0.0.3"
+__version__ = "0.0.4"

cjm_fasthtml_card_stack/components/viewport.py

@@ -210,19 +210,17 @@ def render_all_slots_oob(
 
 # %% ../../nbs/components/viewport.ipynb #v1000031
 def _grid_template_rows(
-    focus_slot: int,  # Resolved focus slot position
-    visible_count: int,  # Number of visible slots
+    focus_position: Optional[int] = None,  # Focus slot offset (None=center, -1=bottom, 0=top)
 ) -> str:  # CSS grid-template-rows value
-    """Compute CSS grid-template-rows based on focus slot position."""
-    slots_before = focus_slot
-    slots_after = visible_count - focus_slot - 1
-
-    if slots_before == 0:
-        return "auto 1fr"  # No before section
-    elif slots_after == 0:
-        return "1fr auto"  # No after section
+    """Compute CSS grid-template-rows based on focus position intent."""
+    if focus_position is None:
+        return "1fr auto 1fr"  # Center: always 3-section
+    elif focus_position == 0:
+        return "auto 1fr"  # Top: focused first
+    elif focus_position < 0:
+        return "1fr auto"  # Bottom: focused last
     else:
-        return "1fr auto 1fr"  # Standard 3-section
+        return "1fr auto 1fr"  # Custom positive: always 3-section
 
 # %% ../../nbs/components/viewport.ipynb #v1000041
 def render_viewport(
@@ -285,8 +283,8 @@ def render_viewport(
         cls=section_cls(justify.start)
     )
 
-    # Grid template adapts to focus position
-    grid_rows = _grid_template_rows(focus_slot, state.visible_count)
+    # Grid template based on focus position intent (stable across count changes)
+    grid_rows = _grid_template_rows(state.focus_position)
 
     inner_cls = combine_classes(grid_display, w.full, h.full, m.x.auto, gap(4))
     inner_style = f"grid-template-rows: {grid_rows}; max-width: {state.card_width}rem"

cjm_fasthtml_card_stack/js/core.py

@@ -6,7 +6,7 @@
 __all__ = ['global_callback_name', 'generate_card_stack_js']
 
 # %% ../../nbs/js/core.ipynb #jc000003
-from typing import Any, Tuple
+from typing import Any, Optional, Tuple
 
 from fasthtml.common import Script
 
@@ -166,7 +166,7 @@ def _generate_card_count_mgmt_js(
             if ('{urls.update_viewport}') {{
                 htmx.ajax('POST', '{urls.update_viewport}', {{
                     target: '#' + '{ids.card_stack}',
-                    swap: 'outerHTML',
+                    swap: 'none',
                     values: {{ visible_count: count }}
                 }});
             }}
@@ -184,15 +184,36 @@ def _generate_card_count_mgmt_js(
 def _generate_coordinator_js(
     ids: CardStackHtmlIds,  # HTML IDs for this instance
     config: CardStackConfig,  # Config for prefix-unique listener guards
+    focus_position: Optional[int] = None,  # Focus slot offset (None=center, -1=bottom, 0=top)
 ) -> str:  # JS code fragment for master coordinator
     """Generate JS for the master coordinator and HTMX listener."""
     guard_var = f"_csMasterListener_{config.prefix.replace('-', '_')}"
+    js_focus_pos = "null" if focus_position is None else str(focus_position)
     return f"""
+        // === Grid Template Management ===
+        ns.applyGridTemplate = function() {{
+            const inner = document.getElementById('{ids.card_stack_inner}');
+            if (!inner) return;
+            const focusPosRaw = {js_focus_pos};
+            let tmpl;
+            if (focusPosRaw === null) {{
+                tmpl = '1fr auto 1fr';
+            }} else if (focusPosRaw === 0) {{
+                tmpl = 'auto 1fr';
+            }} else if (focusPosRaw < 0) {{
+                tmpl = '1fr auto';
+            }} else {{
+                tmpl = '1fr auto 1fr';
+            }}
+            inner.style.gridTemplateRows = tmpl;
+        }};
+
         // === Master Coordinator ===
         ns.applyAllViewportSettings = function() {{
             requestAnimationFrame(function() {{
                 if (ns.applyWidth) ns.applyWidth();
                 if (ns.applyScale) ns.applyScale();
+                if (ns.applyGridTemplate) ns.applyGridTemplate();
                 if (ns.recalculateHeight) ns.recalculateHeight();
 
                 const cs = document.getElementById('{ids.card_stack}');
@@ -272,6 +293,7 @@ def generate_card_stack_js(
     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
+    focus_position: Optional[int] = None,  # Focus slot offset (None=center, -1=bottom, 0=top)
 ) -> Any:  # Script element with all card stack JavaScript
     """Compose all card stack JS into a single namespaced IIFE."""
     prefix = config.prefix
@@ -285,7 +307,7 @@ def generate_card_stack_js(
     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)
+    coordinator_js = _generate_coordinator_js(ids, config, focus_position)
 
     return Script(f"""(function() {{
         window.cardStacks = window.cardStacks || {{}};

cjm_fasthtml_card_stack/routes/handlers.py

@@ -127,17 +127,17 @@ def card_stack_update_viewport(
     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."""
+) -> Tuple:  # OOB section elements (3 viewport sections)
+    """Update viewport with new card count via OOB section swaps. Mutates state.visible_count in place."""
     state.visible_count = visible_count
-    return render_viewport(
+    return tuple(build_slots_response(
         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(

cjm_fasthtml_card_stack/routes/router.py

@@ -100,7 +100,7 @@ def init_card_stack_router(
 
     @router
     def update_viewport(visible_count: int) -> Any:
-        """Update viewport with new card count (full outerHTML swap)."""
+        """Update viewport with new card count (OOB section swaps)."""
         state = state_getter()
         items = get_items()
         result = card_stack_update_viewport(

{cjm_fasthtml_card_stack-0.0.3.dist-info → cjm_fasthtml_card_stack-0.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cjm-fasthtml-card-stack
-Version: 0.0.3
+Version: 0.0.4
 Summary: A fixed-viewport card stack component for FastHTML with keyboard navigation, scroll-to-nav, configurable focus position, and HTMX-driven OOB updates.
 Home-page: https://github.com/cj-mills/cjm-fasthtml-card-stack
 Author: Christian J. Mills
@@ -102,38 +102,38 @@ graph LR
     components_states --> core_html_ids
     components_viewport --> core_config
     components_viewport --> core_html_ids
-    components_viewport --> components_states
-    components_viewport --> core_constants
     components_viewport --> core_models
     components_viewport --> helpers_focus
+    components_viewport --> core_constants
+    components_viewport --> components_states
     helpers_focus --> core_html_ids
     js_core --> core_constants
     js_core --> core_config
     js_core --> core_html_ids
-    js_core --> js_viewport
-    js_core --> js_navigation
-    js_core --> js_scroll
     js_core --> core_models
+    js_core --> js_scroll
+    js_core --> js_navigation
+    js_core --> js_viewport
     js_core --> core_button_ids
     js_navigation --> core_button_ids
     js_scroll --> core_constants
-    js_scroll --> core_button_ids
     js_scroll --> core_html_ids
+    js_scroll --> core_button_ids
     js_viewport --> core_html_ids
+    keyboard_actions --> js_core
     keyboard_actions --> core_config
     keyboard_actions --> core_html_ids
-    keyboard_actions --> js_core
     keyboard_actions --> core_models
     keyboard_actions --> core_button_ids
-    routes_handlers --> core_models
     routes_handlers --> core_config
     routes_handlers --> core_html_ids
-    routes_handlers --> components_progress
-    routes_handlers --> helpers_focus
+    routes_handlers --> core_models
     routes_handlers --> components_viewport
+    routes_handlers --> helpers_focus
+    routes_handlers --> components_progress
+    routes_router --> routes_handlers
     routes_router --> core_config
     routes_router --> core_html_ids
-    routes_router --> routes_handlers
     routes_router --> core_models
 ```
 
@@ -514,6 +514,7 @@ def _generate_card_count_mgmt_js(
 def _generate_coordinator_js(
     ids: CardStackHtmlIds,  # HTML IDs for this instance
     config: CardStackConfig,  # Config for prefix-unique listener guards
+    focus_position: Optional[int] = None,  # Focus slot offset (None=center, -1=bottom, 0=top)
 ) -> str:  # JS code fragment for master coordinator
     "Generate JS for the master coordinator and HTMX listener."
 ```
@@ -670,8 +671,8 @@ def card_stack_update_viewport(
     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."
+) -> Tuple:  # OOB section elements (3 viewport sections)
+    "Update viewport with new card count via OOB section swaps. Mutates state.visible_count in place."
 ```
 
 ``` python
@@ -1082,10 +1083,9 @@ def render_all_slots_oob(
 
 ``` python
 def _grid_template_rows(
-    focus_slot: int,  # Resolved focus slot position
-    visible_count: int,  # Number of visible slots
+    focus_position: Optional[int] = None,  # Focus slot offset (None=center, -1=bottom, 0=top)
 ) -> str:  # CSS grid-template-rows value
-    "Compute CSS grid-template-rows based on focus slot position."
+    "Compute CSS grid-template-rows based on focus position intent."
 ```
 
 ``` python

{cjm_fasthtml_card_stack-0.0.3.dist-info → cjm_fasthtml_card_stack-0.0.4.dist-info}/RECORD

@@ -1,10 +1,10 @@
-cjm_fasthtml_card_stack/__init__.py,sha256=4GZKi13lDTD25YBkGakhZyEQZWTER_OWQMNPoH_UM2c,22
+cjm_fasthtml_card_stack/__init__.py,sha256=1mptEzQihbdyqqzMgdns_j5ZGK9gz7hR2bsgA_TnjO4,22
 cjm_fasthtml_card_stack/_modidx.py,sha256=jYNj6LPbD5I8yDghD3Lx9XWsDnWqc_oNCESguSF8blA,25105
 cjm_fasthtml_card_stack/components/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cjm_fasthtml_card_stack/components/controls.py,sha256=C3iRvaiRe0ti8S7ogTSKRRRdw-z6vz77mkuvKVmIz-Y,4093
 cjm_fasthtml_card_stack/components/progress.py,sha256=BBeR4EWEikA54bVG41iLdlyyGRFwMJtEh8-cX9L9QLI,1500
 cjm_fasthtml_card_stack/components/states.py,sha256=ClgpdS3e19ccO6VHU6ajulU_yb7c1bQVZf9nSsd5QPc,3797
-cjm_fasthtml_card_stack/components/viewport.py,sha256=vLH9oTbSXlkWZEDHTTKWs38Shd9_ajvSpq1mrvcuOGU,11741
+cjm_fasthtml_card_stack/components/viewport.py,sha256=LOocpEh4V_pkTqpdOyWBX50ctil5rf6l7NQl8QBNcGs,11794
 cjm_fasthtml_card_stack/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cjm_fasthtml_card_stack/core/button_ids.py,sha256=elKKLBrt-Hu6vgWhrcVlCXgdUeYXHQyfn3NyhhEmxW4,2123
 cjm_fasthtml_card_stack/core/config.py,sha256=XYaptNnzZ8sRcCdxWA_RB1FwBiXU8Ko6mEsNSbxhtb0,1714
@@ -14,23 +14,24 @@ cjm_fasthtml_card_stack/core/models.py,sha256=soivwLNBbSNQmcCb9EpFz09gaDhb9HesXb
 cjm_fasthtml_card_stack/helpers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cjm_fasthtml_card_stack/helpers/focus.py,sha256=PTbsZagutEM8pwpLUKvM8Gjhv7rVNMbNbO27x5uC3YM,2626
 cjm_fasthtml_card_stack/js/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cjm_fasthtml_card_stack/js/core.py,sha256=fs6mwNOoqxw4K_Wo5X5zKEAXVz6ed7lvg95nYkE9XuQ,12485
+cjm_fasthtml_card_stack/js/core.py,sha256=k6s4sYMz19-5FzFk7MqmrrR8SUHtJnslqm_sfXE6qVs,13486
 cjm_fasthtml_card_stack/js/navigation.py,sha256=471F3NDxdH-BQPLPQuUvtyACqi6g6EOcELYs_sP1hyk,1288
 cjm_fasthtml_card_stack/js/scroll.py,sha256=X6j5JMOjzgH57sDK1fazNRyGYH2GGEDQeZ0dURFEjC4,3062
 cjm_fasthtml_card_stack/js/viewport.py,sha256=hFWr3zt9odyuaYdRdJmhKJcS_vsJyLRhz-HlZPvGh54,5653
 cjm_fasthtml_card_stack/keyboard/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cjm_fasthtml_card_stack/keyboard/actions.py,sha256=rfCD8lLVXXVPrML-8dj48bT_zOKN7g8VmPMNE21IAJI,7573
 cjm_fasthtml_card_stack/routes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cjm_fasthtml_card_stack/routes/handlers.py,sha256=GX1h_9t4-2G59IaDyzWTeWUaDFjrXYCqaaUT4UZ_Viw,6823
-cjm_fasthtml_card_stack/routes/router.py,sha256=w6mTQGb-OE0X7t-6dIz7bXg5A0U4llSzNsec-PTkacs,5131
-cjm_fasthtml_card_stack-0.0.3.dist-info/licenses/LICENSE,sha256=xV8xoN4VOL0uw9X8RSs2IMuD_Ss_a9yAbtGNeBWZwnw,11337
+cjm_fasthtml_card_stack/routes/handlers.py,sha256=Rnfie_QcvyIA5P4PqXOX8FjZFA1ohzbLga4k9HoUGhY,6861
+cjm_fasthtml_card_stack/routes/router.py,sha256=88a0NEnPX5agS_VsNUcxZ8pC8c0P-eaFy0ZZoIn0UP4,5129
+cjm_fasthtml_card_stack-0.0.4.dist-info/licenses/LICENSE,sha256=xV8xoN4VOL0uw9X8RSs2IMuD_Ss_a9yAbtGNeBWZwnw,11337
 demos/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 demos/basic.py,sha256=8GVV7eSWOzcz67L6XiPqwKFy886AT5y7Ok-T2ZPX32Q,3815
 demos/bottom.py,sha256=ZLpgpUfOvCzM3rVf3ufvZnSAxuzOQ5gND7RsSUgNpJo,3341
+demos/custom_position.py,sha256=wra57olAq-RuzcEIl4Jwl_-EeXHx0LW0YLqFB8-w-BI,3613
 demos/data.py,sha256=8yVV_E0nLcr0L1PcrTG-DaT-V36apF74ALKNIZuSQ70,4471
-demos/shared.py,sha256=8AMZhgjyobY0pnt_7lmZ91gxb8X1UA1biK0KPfherjo,5384
-cjm_fasthtml_card_stack-0.0.3.dist-info/METADATA,sha256=mv8IdrvEVlWeuYLBn5BKQBZpH8rlUXo9GQeRdhQEvds,36832
-cjm_fasthtml_card_stack-0.0.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-cjm_fasthtml_card_stack-0.0.3.dist-info/entry_points.txt,sha256=qTw6qaijkEUH1AcPQhpTqJ8TPiUSMnpn0Cvg4hXoX90,68
-cjm_fasthtml_card_stack-0.0.3.dist-info/top_level.txt,sha256=ydBTJsY2ONaDryp85HkjhdGHEuuUOoMGdrOgFA2ddyg,30
-cjm_fasthtml_card_stack-0.0.3.dist-info/RECORD,,
+demos/shared.py,sha256=88vNOVODcauWHoswzsZt9vQhEPsam8uWGujSgisVxhU,5433
+cjm_fasthtml_card_stack-0.0.4.dist-info/METADATA,sha256=xHG3PiHNzISON6yxr3paljb6d1yLWFYF06oUyztc8CM,36946
+cjm_fasthtml_card_stack-0.0.4.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+cjm_fasthtml_card_stack-0.0.4.dist-info/entry_points.txt,sha256=qTw6qaijkEUH1AcPQhpTqJ8TPiUSMnpn0Cvg4hXoX90,68
+cjm_fasthtml_card_stack-0.0.4.dist-info/top_level.txt,sha256=ydBTJsY2ONaDryp85HkjhdGHEuuUOoMGdrOgFA2ddyg,30
+cjm_fasthtml_card_stack-0.0.4.dist-info/RECORD,,

demos/custom_position.py

@@ -0,0 +1,114 @@
+"""Custom focus position demo (focus at slot 1)."""
+
+from fasthtml.common import Div, P, Span
+
+from cjm_fasthtml_daisyui.components.data_display.card import card, card_body
+from cjm_fasthtml_daisyui.components.data_display.badge import badge, badge_colors, badge_styles
+from cjm_fasthtml_daisyui.utilities.semantic_colors import bg_dui, text_dui
+from cjm_fasthtml_tailwind.utilities.spacing import p, m
+from cjm_fasthtml_tailwind.utilities.sizing import w
+from cjm_fasthtml_tailwind.core.base import combine_classes
+
+from cjm_fasthtml_card_stack.core.config import CardStackConfig
+from cjm_fasthtml_card_stack.core.models import CardStackState, CardRenderContext
+from cjm_fasthtml_card_stack.core.html_ids import CardStackHtmlIds
+from cjm_fasthtml_card_stack.core.button_ids import CardStackButtonIds
+from cjm_fasthtml_card_stack.routes.router import init_card_stack_router
+
+from demos.data import SAMPLE_ITEMS
+
+
+def render_card(item, context: CardRenderContext):
+    """Render a card with position info for the custom focus demo."""
+    is_focused = context.card_role == "focused"
+
+    index_badge = Span(
+        f"#{context.index + 1}",
+        cls=combine_classes(
+            badge,
+            badge_colors.accent if is_focused else badge_colors.neutral,
+        )
+    )
+
+    distance_label = Span(
+        f"slot offset: {context.distance_from_focus:+d}",
+        cls=combine_classes(
+            badge, badge_styles.ghost,
+        )
+    ) if not is_focused else Span(
+        "focused",
+        cls=combine_classes(badge, badge_colors.accent),
+    )
+
+    return Div(
+        Div(
+            Div(index_badge, distance_label, cls=combine_classes(m.b(1))),
+            P(
+                item,
+                cls=combine_classes(text_dui.base_content),
+                style="font-size: calc(0.875rem * var(--card-stack-scale, 100) / 100)",
+            ),
+            cls=combine_classes(card_body, p(3)),
+        ),
+        cls=combine_classes(
+            card,
+            bg_dui.base_100,
+            w.full,
+        ),
+    )
+
+
+def setup(route_prefix="/custom"):
+    """Set up the custom focus position demo.
+
+    Returns dict with config, ids, btn_ids, router, urls, state management,
+    and page rendering dependencies.
+    """
+    config = CardStackConfig(prefix="custom", click_to_focus=True)
+    ids = CardStackHtmlIds(prefix=config.prefix)
+    btn_ids = CardStackButtonIds(prefix=config.prefix)
+
+    state = CardStackState(
+        visible_count=5,
+        card_width=60,
+        focus_position=1,  # Second slot from top
+    )
+
+    def get_state():
+        return state
+
+    def set_state(s):
+        nonlocal state
+        state.focused_index = s.focused_index
+        state.visible_count = s.visible_count
+        state.card_width = s.card_width
+        state.card_scale = s.card_scale
+        state.active_mode = s.active_mode
+        state.focus_position = s.focus_position
+
+    def get_items():
+        return SAMPLE_ITEMS
+
+    router, urls = init_card_stack_router(
+        config=config,
+        state_getter=get_state,
+        state_setter=set_state,
+        get_items=get_items,
+        render_card=render_card,
+        route_prefix=route_prefix,
+    )
+
+    return dict(
+        config=config,
+        ids=ids,
+        btn_ids=btn_ids,
+        router=router,
+        urls=urls,
+        get_state=get_state,
+        get_items=get_items,
+        render_card=render_card,
+        container_id="custom-demo-container",
+        title="Custom Focus Position",
+        description="Focus at slot 1 (second from top). One context card above, rest below.",
+        progress_label="Item",
+    )

demos/shared.py

@@ -79,6 +79,7 @@ def render_demo_page(
             config=config,
             urls=urls,
             container_id=container_id,
+            focus_position=state.focus_position,
         )
 
         return Div(