cjm-fasthtml-card-stack 0.0.1__tar.gz → 0.0.2__tar.gz

{cjm_fasthtml_card_stack-0.0.1/cjm_fasthtml_card_stack.egg-info → cjm_fasthtml_card_stack-0.0.2}/PKG-INFO

@@ -1,19 +1,17 @@
 Metadata-Version: 2.4
 Name: cjm-fasthtml-card-stack
-Version: 0.0.1
+Version: 0.0.2
 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
-Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
+Author-email: 9126128+cj-mills@users.noreply.github.com
 License: Apache-2.0
-Project-URL: Repository, https://github.com/cj-mills/cjm-fasthtml-card-stack
-Project-URL: Documentation, https://cj-mills.github.io/cjm-fasthtml-card-stack
-Keywords: nbdev,jupyter,notebook,python
-Classifier: Natural Language :: English
+Keywords: nbdev jupyter notebook python
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: Development Status :: 3 - Alpha
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -21,10 +19,20 @@ Requires-Dist: python-fasthtml
 Requires-Dist: cjm-fasthtml-tailwind
 Requires-Dist: cjm-fasthtml-daisyui
 Requires-Dist: cjm-fasthtml-keyboard-navigation
+Provides-Extra: dev
 Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
 Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
 Dynamic: requires-python
+Dynamic: summary
 
 # cjm-fasthtml-card-stack
 

cjm_fasthtml_card_stack-0.0.2/cjm_fasthtml_card_stack/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.2"

cjm_fasthtml_card_stack-0.0.2/cjm_fasthtml_card_stack/components/controls.py

@@ -0,0 +1,115 @@
+"""Width slider, scale slider, and card count selector components."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/components/controls.ipynb.
+
+# %% auto #0
+__all__ = ['render_width_slider', 'render_scale_slider', 'render_card_count_select']
+
+# %% ../../nbs/components/controls.ipynb #ct000003
+from typing import Any
+
+from fasthtml.common import Div, Span, Input, Select, Option
+
+# DaisyUI components
+from cjm_fasthtml_daisyui.components.data_input.range_slider import range_dui, range_sizes
+from cjm_fasthtml_daisyui.components.data_input.select import select, select_sizes
+from cjm_fasthtml_daisyui.utilities.semantic_colors import text_dui
+
+# Tailwind utilities
+from cjm_fasthtml_tailwind.utilities.flexbox_and_grid import (
+    flex_display, items, gap, grow
+)
+from cjm_fasthtml_tailwind.utilities.sizing import w
+from cjm_fasthtml_tailwind.utilities.typography import font_size
+from cjm_fasthtml_tailwind.core.base import combine_classes
+
+# Local imports
+from ..core.config import CardStackConfig
+from ..core.html_ids import CardStackHtmlIds
+
+# %% ../../nbs/components/controls.ipynb #ct000005
+def render_width_slider(
+    config: CardStackConfig,  # Card stack configuration
+    ids: CardStackHtmlIds,  # HTML IDs for this instance
+    card_width: int = 80,  # Current card width in rem
+) -> Any:  # Width slider component
+    """Render the card stack width slider control."""
+    js_fn = f"window.cardStacks['{config.prefix}'].updateWidth(this.value)"
+
+    return Div(
+        Span(
+            "Narrow",
+            cls=combine_classes(font_size.xs, text_dui.base_content.opacity(50))
+        ),
+        Input(
+            type="range",
+            id=ids.width_slider,
+            min=str(config.card_width_min),
+            max=str(config.card_width_max),
+            step=str(config.card_width_step),
+            value=str(card_width),
+            cls=combine_classes(range_dui, range_sizes.xs, grow()),
+            oninput=js_fn
+        ),
+        Span(
+            "Wide",
+            cls=combine_classes(font_size.xs, text_dui.base_content.opacity(50))
+        ),
+        cls=combine_classes(flex_display, items.center, gap(3), w.full)
+    )
+
+# %% ../../nbs/components/controls.ipynb #ct000008
+def render_scale_slider(
+    config: CardStackConfig,  # Card stack configuration
+    ids: CardStackHtmlIds,  # HTML IDs for this instance
+    card_scale: int = 100,  # Current scale percentage
+) -> Any:  # Scale slider component
+    """Render the card stack scale slider control."""
+    js_fn = f"window.cardStacks['{config.prefix}'].updateScale(this.value)"
+
+    return Div(
+        Span(
+            "Smaller",
+            cls=combine_classes(font_size.xs, text_dui.base_content.opacity(50))
+        ),
+        Input(
+            type="range",
+            id=ids.scale_slider,
+            min=str(config.card_scale_min),
+            max=str(config.card_scale_max),
+            step=str(config.card_scale_step),
+            value=str(card_scale),
+            cls=combine_classes(range_dui, range_sizes.xs, grow()),
+            oninput=js_fn
+        ),
+        Span(
+            "Larger",
+            cls=combine_classes(font_size.xs, text_dui.base_content.opacity(50))
+        ),
+        cls=combine_classes(flex_display, items.center, gap(3), w.full)
+    )
+
+# %% ../../nbs/components/controls.ipynb #ct000011
+def render_card_count_select(
+    config: CardStackConfig,  # Card stack configuration
+    ids: CardStackHtmlIds,  # HTML IDs for this instance
+    current_count: int = 3,  # Currently selected card count
+) -> Any:  # Card count dropdown component
+    """Render the card count dropdown selector."""
+    js_fn = f"window.cardStacks['{config.prefix}'].updateCardCount(this.value)"
+
+    options = [
+        Option(
+            f"{count} card{'s' if count > 1 else ''}",
+            value=str(count),
+            selected=(count == current_count)
+        )
+        for count in config.visible_count_options
+    ]
+
+    return Select(
+        *options,
+        id=ids.card_count_select,
+        cls=combine_classes(select, select_sizes.sm),
+        onchange=js_fn
+    )

cjm_fasthtml_card_stack-0.0.2/cjm_fasthtml_card_stack/components/progress.py

@@ -0,0 +1,44 @@
+"""Progress indicator showing the current position within the card stack."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/components/progress.ipynb.
+
+# %% auto #0
+__all__ = ['render_progress_indicator']
+
+# %% ../../nbs/components/progress.ipynb #p1000003
+from typing import Any
+
+from fasthtml.common import Div, Span
+
+# DaisyUI utilities
+from cjm_fasthtml_daisyui.utilities.semantic_colors import text_dui
+
+# Tailwind utilities
+from cjm_fasthtml_tailwind.utilities.typography import font_size, font_family
+from cjm_fasthtml_tailwind.core.base import combine_classes
+
+# Local imports
+from ..core.html_ids import CardStackHtmlIds
+
+# %% ../../nbs/components/progress.ipynb #p1000005
+def render_progress_indicator(
+    focused_index: int,  # Currently focused item index (0-based)
+    total_items: int,  # Total number of items
+    ids: CardStackHtmlIds,  # HTML IDs for this card stack instance
+    label: str = "Item",  # Label prefix (e.g., "Item", "Segment", "Card")
+    oob: bool = False,  # Whether to render as OOB swap
+) -> Any:  # Progress indicator component
+    """Render position indicator showing current item in the collection."""
+    current = focused_index + 1
+
+    return Div(
+        Span(
+            f"{label} {current:,} of {total_items:,}",
+            cls=combine_classes(
+                font_size.sm, font_family.mono,
+                text_dui.base_content.opacity(70)
+            )
+        ),
+        id=ids.progress,
+        hx_swap_oob="true" if oob else None
+    )

cjm_fasthtml_card_stack-0.0.2/cjm_fasthtml_card_stack/components/states.py

@@ -0,0 +1,107 @@
+"""Loading, empty, and placeholder card components for the card stack viewport."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/components/states.ipynb.
+
+# %% auto #0
+__all__ = ['render_placeholder_card', 'render_loading_state', 'render_empty_state']
+
+# %% ../../nbs/components/states.ipynb #s1000003
+from typing import Any, Literal
+
+from fasthtml.common import Div, P, Span
+
+# DaisyUI components
+from cjm_fasthtml_daisyui.components.data_display.card import card, card_body
+from cjm_fasthtml_daisyui.components.feedback.loading import loading, loading_styles, loading_sizes
+from cjm_fasthtml_daisyui.utilities.semantic_colors import bg_dui, text_dui
+
+# Tailwind utilities
+from cjm_fasthtml_tailwind.utilities.borders import border, border_color
+from cjm_fasthtml_tailwind.utilities.effects import shadow
+from cjm_fasthtml_tailwind.utilities.flexbox_and_grid import (
+    flex_display, flex_direction, items, justify, grow
+)
+from cjm_fasthtml_tailwind.utilities.spacing import p, m
+from cjm_fasthtml_tailwind.utilities.sizing import w
+from cjm_fasthtml_tailwind.utilities.typography import font_size, italic, text_align
+from cjm_fasthtml_tailwind.core.base import combine_classes
+
+# Local imports
+from ..core.html_ids import CardStackHtmlIds
+
+# %% ../../nbs/components/states.ipynb #s1000005
+def render_placeholder_card(
+    placeholder_type: Literal["start", "end"],  # Which edge of the list
+) -> Any:  # Placeholder card component
+    """Render a placeholder card for viewport edges."""
+    text = "Beginning" if placeholder_type == "start" else "End"
+
+    return Div(
+        Div(
+            P(
+                text,
+                cls=combine_classes(
+                    font_size.lg, italic,
+                    text_dui.base_content.opacity(30),
+                    p.y(4)
+                )
+            ),
+            cls=combine_classes(card_body, p(4))
+        ),
+        cls=combine_classes(
+            card, "placeholder-card",
+            bg_dui.base_100.opacity(50), shadow.none,
+            border(2), border_color.transparent
+        ),
+        data_placeholder_type=placeholder_type
+    )
+
+# %% ../../nbs/components/states.ipynb #s1000008
+def render_loading_state(
+    ids: CardStackHtmlIds,  # HTML IDs for this card stack instance
+    message: str = "Loading...",  # Loading message text
+) -> Any:  # Loading component
+    """Render loading state with spinner and message."""
+    return Div(
+        Div(
+            Span(cls=combine_classes(loading, loading_styles.spinner, loading_sizes.lg)),
+            P(
+                message,
+                cls=combine_classes(m.t(4), text_dui.base_content.opacity(60))
+            ),
+            cls=combine_classes(
+                flex_display, flex_direction.col, items.center, justify.center,
+                p(16)
+            )
+        ),
+        id=ids.loading
+    )
+
+# %% ../../nbs/components/states.ipynb #s1000011
+def render_empty_state(
+    ids: CardStackHtmlIds,  # HTML IDs for this card stack instance
+    title: str = "No items available",  # Main empty state message
+    subtitle: str = "",  # Optional subtitle text
+) -> Any:  # Empty state component
+    """Render empty state when no items exist."""
+    return Div(
+        P(
+            title,
+            cls=combine_classes(
+                text_dui.base_content.opacity(40),
+                text_align.center, font_size.lg
+            )
+        ),
+        P(
+            subtitle,
+            cls=combine_classes(
+                text_dui.base_content.opacity(30),
+                text_align.center, font_size.sm, m.t(2)
+            )
+        ) if subtitle else None,
+        id=ids.card_stack_empty,
+        cls=combine_classes(
+            flex_display, flex_direction.col, items.center, justify.center,
+            p(16), grow()
+        )
+    )

cjm_fasthtml_card_stack-0.0.2/cjm_fasthtml_card_stack/components/viewport.py

@@ -0,0 +1,320 @@
+"""Card stack viewport with 3-section CSS Grid layout, slot rendering,"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/components/viewport.ipynb.
+
+# %% auto #0
+__all__ = ['render_slot_card', 'render_all_slots_oob', 'render_viewport']
+
+# %% ../../nbs/components/viewport.ipynb #v1000003
+from typing import Any, Callable, List, Optional
+
+from fasthtml.common import Div, Script, A, Hidden
+
+# DaisyUI utilities
+from cjm_fasthtml_daisyui.utilities.semantic_colors import ring_dui
+from cjm_fasthtml_daisyui.utilities.border_radius import border_radius
+
+# Tailwind utilities
+from cjm_fasthtml_tailwind.utilities.effects import ring
+from cjm_fasthtml_tailwind.utilities.flexbox_and_grid import (
+    flex_display, flex_direction, justify, items, gap, grid_display
+)
+from cjm_fasthtml_tailwind.utilities.layout import overflow, position, inset, z
+from cjm_fasthtml_tailwind.utilities.interactivity import cursor
+from cjm_fasthtml_tailwind.utilities.sizing import w, h
+from cjm_fasthtml_tailwind.utilities.spacing import p, m
+from cjm_fasthtml_tailwind.core.base import combine_classes
+
+# Local imports
+from ..core.config import CardStackConfig
+from ..core.html_ids import CardStackHtmlIds
+from ..core.models import CardStackState, CardRenderContext, CardStackUrls
+from ..core.constants import CardRole
+from ..helpers.focus import resolve_focus_slot, calculate_viewport_window
+from .states import render_placeholder_card
+
+# %% ../../nbs/components/viewport.ipynb #v1000005
+def _render_mode_sync_script(
+    active_mode: Optional[str] = None,  # Active keyboard mode name (None = navigation)
+) -> Any:  # Script element that syncs keyboard mode state
+    """Generate script to sync keyboard navigation mode with rendered UI state."""
+    target_mode = active_mode if active_mode else "navigation"
+
+    return Script(f"""
+        (function() {{
+            if (typeof window.kbNav !== 'undefined') {{
+                const state = window.kbNav.getState();
+                const currentMode = state ? state.currentMode : 'navigation';
+                const targetMode = '{target_mode}';
+                if (targetMode !== 'navigation' && currentMode !== targetMode) {{
+                    window.kbNav.enterMode(targetMode);
+                }} else if (targetMode === 'navigation' && currentMode !== 'navigation') {{
+                    window.kbNav.exitMode();
+                }}
+            }}
+        }})();
+    """)
+
+# %% ../../nbs/components/viewport.ipynb #v1000007
+def _render_click_overlay(
+    item_index: int,  # Index of the item this slot represents
+    urls: CardStackUrls,  # URL bundle for navigation
+) -> Any:  # Transparent click overlay element
+    """Render transparent click-to-focus overlay for a context card slot."""
+    return A(
+        cls=combine_classes(
+            position.absolute, inset(0), z(10),
+            cursor.pointer
+        ),
+        hx_post=urls.nav_to_index,
+        hx_vals=f'{{"target_index": {item_index}}}',
+        hx_swap="none"
+    )
+
+# %% ../../nbs/components/viewport.ipynb #v1000009
+def render_slot_card(
+    slot_index: int,  # Index of this slot in the viewport (0-based)
+    focus_slot: int,  # Which slot is the focused position
+    card_items: List[Any],  # Full items list
+    item_index: Optional[int],  # Item index for this slot (None for placeholder)
+    render_card: Callable,  # Callback: (item, CardRenderContext) -> FT
+    state: CardStackState,  # Current card stack state
+    config: CardStackConfig,  # Card stack configuration
+    ids: CardStackHtmlIds,  # HTML IDs for this instance
+    urls: CardStackUrls,  # URL bundle for navigation
+    oob: bool = False,  # Whether to render as OOB swap
+) -> Any:  # Slot content wrapper
+    """Render a single card for a viewport slot."""
+    slot_id = ids.viewport_slot(slot_index)
+    is_focused = slot_index == focus_slot
+    card_role: CardRole = "focused" if is_focused else "context"
+    total_items = len(card_items)
+    distance = slot_index - focus_slot
+
+    # Determine placeholder type based on position relative to focus
+    placeholder_type = "start" if slot_index < focus_slot else "end"
+
+    # Render content
+    if item_index is None:
+        content = render_placeholder_card(placeholder_type)
+    else:
+        context = CardRenderContext(
+            card_role=card_role,
+            index=item_index,
+            total_items=total_items,
+            is_first=(item_index == 0),
+            is_last=(item_index == total_items - 1),
+            active_mode=state.active_mode,
+            card_scale=state.card_scale,
+            distance_from_focus=distance,
+        )
+        content = render_card(card_items[item_index], context)
+
+    # Focus ring styling for focused slot
+    focus_cls = combine_classes(
+        ring(3), ring_dui.primary, border_radius.box
+    ) if is_focused else ""
+
+    # Mode sync script in focused slot OOB updates
+    mode_sync = _render_mode_sync_script(state.active_mode) if (oob and is_focused) else None
+
+    # Click-to-focus overlay for context cards
+    click_overlay = None
+    if config.click_to_focus and not is_focused and item_index is not None:
+        click_overlay = _render_click_overlay(item_index, urls)
+
+    # Slot container
+    slot_cls = combine_classes(
+        "viewport-slot",
+        p(1) if not is_focused else "",
+        w.full,
+        focus_cls,
+        position.relative if click_overlay else ""
+    )
+
+    return Div(
+        content,
+        click_overlay,
+        mode_sync,
+        id=slot_id,
+        cls=slot_cls,
+        tabindex="0" if is_focused else "-1",
+        hx_swap_oob="innerHTML" if oob else None
+    )
+
+# %% ../../nbs/components/viewport.ipynb #v1000021
+def render_all_slots_oob(
+    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]:  # List of OOB elements (3 sections)
+    """Render all viewport sections with OOB swap for granular updates."""
+    total_items = len(card_items)
+    focus_slot = resolve_focus_slot(state.focus_position, state.visible_count)
+
+    viewport_indices = calculate_viewport_window(
+        state.focused_index, total_items, state.visible_count, state.focus_position
+    )
+
+    before_cards = []
+    focused_card = None
+    after_cards = []
+
+    for slot_index, item_index in enumerate(viewport_indices):
+        card_el = render_slot_card(
+            slot_index=slot_index, focus_slot=focus_slot,
+            card_items=card_items, item_index=item_index,
+            render_card=render_card, state=state,
+            config=config, ids=ids, urls=urls, oob=False,
+        )
+
+        if slot_index < focus_slot:
+            before_cards.append(card_el)
+        elif slot_index == focus_slot:
+            focused_card = card_el
+        else:
+            after_cards.append(card_el)
+
+    # Section styling
+    section_cls = lambda alignment: combine_classes(
+        flex_display, flex_direction.col, alignment, items.center,
+        w.full, gap(4), overflow.hidden
+    )
+
+    before_section = Div(
+        *before_cards,
+        id=ids.viewport_section_before,
+        cls=section_cls(justify.end),
+        hx_swap_oob="innerHTML"
+    )
+
+    mode_sync = _render_mode_sync_script(state.active_mode)
+    focused_section = Div(
+        focused_card, mode_sync,
+        id=ids.viewport_section_focused,
+        cls=combine_classes(flex_display, justify.center, items.center, w.full),
+        hx_swap_oob="innerHTML"
+    )
+
+    after_section = Div(
+        *after_cards,
+        id=ids.viewport_section_after,
+        cls=section_cls(justify.start),
+        hx_swap_oob="innerHTML"
+    )
+
+    return [before_section, focused_section, after_section]
+
+# %% ../../nbs/components/viewport.ipynb #v1000031
+def _grid_template_rows(
+    focus_slot: int,  # Resolved focus slot position
+    visible_count: int,  # Number of visible slots
+) -> 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
+    else:
+        return "1fr auto 1fr"  # Standard 3-section
+
+# %% ../../nbs/components/viewport.ipynb #v1000041
+def render_viewport(
+    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
+    form_input_name: str = "focused_index",  # Name for the focused index hidden input
+) -> Any:  # Viewport component with 3-section layout
+    """Render the card stack viewport with 3-section CSS Grid layout."""
+    total_items = len(card_items)
+    focus_slot = resolve_focus_slot(state.focus_position, state.visible_count)
+
+    viewport_indices = calculate_viewport_window(
+        state.focused_index, total_items, state.visible_count, state.focus_position
+    )
+
+    before_cards = []
+    focused_card = None
+    after_cards = []
+
+    for slot_index, item_index in enumerate(viewport_indices):
+        card_el = render_slot_card(
+            slot_index=slot_index, focus_slot=focus_slot,
+            card_items=card_items, item_index=item_index,
+            render_card=render_card, state=state,
+            config=config, ids=ids, urls=urls, oob=False,
+        )
+
+        if slot_index < focus_slot:
+            before_cards.append(card_el)
+        elif slot_index == focus_slot:
+            focused_card = card_el
+        else:
+            after_cards.append(card_el)
+
+    # Section styling helper
+    section_cls = lambda alignment: combine_classes(
+        flex_display, flex_direction.col, alignment, items.center,
+        w.full, gap(4), overflow.hidden
+    )
+
+    before_section = Div(
+        *before_cards,
+        id=ids.viewport_section_before,
+        cls=section_cls(justify.end)
+    )
+
+    focused_section = Div(
+        focused_card,
+        id=ids.viewport_section_focused,
+        cls=combine_classes(flex_display, justify.center, items.center, w.full)
+    )
+
+    after_section = Div(
+        *after_cards,
+        id=ids.viewport_section_after,
+        cls=section_cls(justify.start)
+    )
+
+    # Grid template adapts to focus position
+    grid_rows = _grid_template_rows(focus_slot, state.visible_count)
+
+    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"
+
+    outer_cls = combine_classes(w.full, p.x(2), p.y(2), overflow.hidden)
+
+    # Hidden input for focused index (needed for keyboard nav hx-include and OOB updates)
+    focused_input = Hidden(
+        id=ids.focused_index_input,
+        name=form_input_name,
+        value=str(state.focused_index),
+    )
+
+    return Div(
+        Div(
+            before_section,
+            focused_section,
+            after_section,
+            id=ids.card_stack_inner,
+            cls=inner_cls,
+            style=inner_style
+        ),
+        _render_mode_sync_script(state.active_mode),
+        focused_input,
+        id=ids.card_stack,
+        cls=outer_cls,
+        style="opacity: 0; transition: opacity 150ms ease-in",
+        data_focused_index=str(state.focused_index),
+        data_total_items=str(total_items),
+        data_visible_count=str(state.visible_count)
+    )