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

cjm_fasthtml_card_stack/routes/router.py

@@ -0,0 +1,150 @@
+"""Convenience router factory that wires up standard card stack routes (Tier 2 API)."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/routes/router.ipynb.
+
+# %% auto #0
+__all__ = ['init_card_stack_router']
+
+# %% ../../nbs/routes/router.ipynb #r1000003
+from typing import Any, Callable, List, Optional, Tuple
+
+from fasthtml.common import APIRouter
+
+from ..core.config import CardStackConfig
+from ..core.html_ids import CardStackHtmlIds
+from ..core.models import CardStackState, CardStackUrls
+from cjm_fasthtml_card_stack.routes.handlers import (
+    card_stack_navigate,
+    card_stack_navigate_to_index,
+    card_stack_update_viewport,
+    card_stack_save_width,
+    card_stack_save_scale,
+)
+
+# %% ../../nbs/routes/router.ipynb #r1000005
+def init_card_stack_router(
+    config: CardStackConfig,  # Card stack configuration
+    state_getter: Callable[[], CardStackState],  # Function to get current state
+    state_setter: Callable[[CardStackState], None],  # Function to save state
+    get_items: Callable[[], List[Any]],  # Function to get current items list
+    render_card: Callable,  # Card renderer callback: (item, CardRenderContext) -> FT
+    route_prefix: str = "/card-stack",  # Route prefix for all card stack routes
+    progress_label: str = "Item",  # Label for progress indicator
+) -> Tuple[APIRouter, CardStackUrls]:  # (router, urls) tuple
+    """Initialize an APIRouter with all standard card stack routes."""
+    router = APIRouter(prefix=route_prefix)
+    ids = CardStackHtmlIds(prefix=config.prefix)
+
+    # -----------------------------------------------------------------
+    # Navigation Routes
+    # -----------------------------------------------------------------
+
+    def _nav(direction: str) -> Any:
+        """Shared navigation handler."""
+        state = state_getter()
+        items = get_items()
+        result = card_stack_navigate(
+            direction=direction, card_items=items, state=state,
+            config=config, ids=ids, urls=urls,
+            render_card=render_card, progress_label=progress_label,
+        )
+        state_setter(state)
+        return result
+
+    @router
+    def nav_up() -> Any:
+        """Navigate to previous item."""
+        return _nav("up")
+
+    @router
+    def nav_down() -> Any:
+        """Navigate to next item."""
+        return _nav("down")
+
+    @router
+    def nav_first() -> Any:
+        """Navigate to first item."""
+        return _nav("first")
+
+    @router
+    def nav_last() -> Any:
+        """Navigate to last item."""
+        return _nav("last")
+
+    @router
+    def nav_page_up() -> Any:
+        """Navigate up by page."""
+        return _nav("page_up")
+
+    @router
+    def nav_page_down() -> Any:
+        """Navigate down by page."""
+        return _nav("page_down")
+
+    @router
+    def nav_to_index(target_index: int) -> Any:
+        """Navigate to a specific item index (click-to-focus)."""
+        state = state_getter()
+        items = get_items()
+        result = card_stack_navigate_to_index(
+            target_index=target_index, card_items=items, state=state,
+            config=config, ids=ids, urls=urls,
+            render_card=render_card, progress_label=progress_label,
+        )
+        state_setter(state)
+        return result
+
+    # -----------------------------------------------------------------
+    # Viewport Route
+    # -----------------------------------------------------------------
+
+    @router
+    def update_viewport(visible_count: int) -> Any:
+        """Update viewport with new card count (full outerHTML swap)."""
+        state = state_getter()
+        items = get_items()
+        result = card_stack_update_viewport(
+            visible_count=visible_count, card_items=items, state=state,
+            config=config, ids=ids, urls=urls, render_card=render_card,
+        )
+        state_setter(state)
+        return result
+
+    # -----------------------------------------------------------------
+    # Preference Persistence Routes
+    # -----------------------------------------------------------------
+
+    @router
+    def save_width(card_width: int) -> Any:
+        """Save card stack width to server state."""
+        state = state_getter()
+        card_stack_save_width(state, card_width, config)
+        state_setter(state)
+        return ""
+
+    @router
+    def save_scale(card_scale: int) -> Any:
+        """Save card stack scale to server state."""
+        state = state_getter()
+        card_stack_save_scale(state, card_scale, config)
+        state_setter(state)
+        return ""
+
+    # -----------------------------------------------------------------
+    # Build URL bundle from registered routes
+    # -----------------------------------------------------------------
+
+    urls = CardStackUrls(
+        nav_up=nav_up.to(),
+        nav_down=nav_down.to(),
+        nav_first=nav_first.to(),
+        nav_last=nav_last.to(),
+        nav_page_up=nav_page_up.to(),
+        nav_page_down=nav_page_down.to(),
+        nav_to_index=nav_to_index.to(),
+        update_viewport=update_viewport.to(),
+        save_width=save_width.to(),
+        save_scale=save_scale.to(),
+    )
+
+    return router, urls

{cjm_fasthtml_card_stack-0.0.1.dist-info → cjm_fasthtml_card_stack-0.0.2.dist-info}/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,36 @@
+cjm_fasthtml_card_stack/__init__.py,sha256=QvlVh4JTl3JL7jQAja76yKtT-IvF4631ASjWY1wS6AQ,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=ikb35mGEUP2RpC-1B6F-JeGBrNaT6wpXv_op5T7zbgA,11699
+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
+cjm_fasthtml_card_stack/core/constants.py,sha256=MaVTAInPk66VTHzmMtGkxvAgr4R2c7HEWvKDNvmv7hM,1673
+cjm_fasthtml_card_stack/core/html_ids.py,sha256=N5ut7EkEMt2ynjnYv5naE_22gviPzLccGbWU29VsJWg,3099
+cjm_fasthtml_card_stack/core/models.py,sha256=soivwLNBbSNQmcCb9EpFz09gaDhb9HesXbwfq9t_MTY,2448
+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/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.2.dist-info/licenses/LICENSE,sha256=xV8xoN4VOL0uw9X8RSs2IMuD_Ss_a9yAbtGNeBWZwnw,11337
+demos/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+demos/basic.py,sha256=o93t_7O3PCnn-aGGCVKSVt09xcgs1oy-yAW2EDdPsY8,3813
+demos/bottom.py,sha256=ylyYqUXhv97noIQF1-kdFeVM6E40POKd45r0WM0cabo,3339
+demos/data.py,sha256=8yVV_E0nLcr0L1PcrTG-DaT-V36apF74ALKNIZuSQ70,4471
+demos/shared.py,sha256=8AMZhgjyobY0pnt_7lmZ91gxb8X1UA1biK0KPfherjo,5384
+cjm_fasthtml_card_stack-0.0.2.dist-info/METADATA,sha256=kMYvuotFt_cCjJf1TJa-g8YBRAQBbt4IeOoUCZW8Sxw,36832
+cjm_fasthtml_card_stack-0.0.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+cjm_fasthtml_card_stack-0.0.2.dist-info/entry_points.txt,sha256=qTw6qaijkEUH1AcPQhpTqJ8TPiUSMnpn0Cvg4hXoX90,68
+cjm_fasthtml_card_stack-0.0.2.dist-info/top_level.txt,sha256=ydBTJsY2ONaDryp85HkjhdGHEuuUOoMGdrOgFA2ddyg,30
+cjm_fasthtml_card_stack-0.0.2.dist-info/RECORD,,

{cjm_fasthtml_card_stack-0.0.1.dist-info → cjm_fasthtml_card_stack-0.0.2.dist-info}/top_level.txt

@@ -1 +1,2 @@
 cjm_fasthtml_card_stack
+demos

demos/basic.py

@@ -0,0 +1,115 @@
+"""Basic centered card stack demo."""
+
+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
+from cjm_fasthtml_daisyui.utilities.semantic_colors import bg_dui, text_dui
+from cjm_fasthtml_tailwind.utilities.spacing import m
+from cjm_fasthtml_tailwind.utilities.sizing import w
+from cjm_fasthtml_tailwind.utilities.typography import font_size, font_weight
+from cjm_fasthtml_tailwind.utilities.flexbox_and_grid import flex_display, items, gap
+from cjm_fasthtml_tailwind.utilities.effects import opacity
+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 index badge and text content."""
+    is_focused = context.card_role == "focused"
+
+    index_badge = Span(
+        f"#{context.index + 1}",
+        cls=combine_classes(
+            badge,
+            badge_colors.primary if is_focused else badge_colors.neutral,
+        )
+    )
+
+    text = P(
+        f'"{item}"',
+        cls=combine_classes(
+            font_weight.medium if is_focused else font_weight.normal,
+            text_dui.base_content,
+        ),
+        style="font-size: calc(1rem * var(--card-stack-scale, 100) / 100)",
+    )
+
+    return Div(
+        Div(
+            Div(
+                index_badge,
+                Span(
+                    f"Item {context.index + 1} of {context.total_items}",
+                    cls=combine_classes(font_size.xs, text_dui.base_content, str(opacity(60))),
+                ),
+                cls=combine_classes(flex_display, items.center, gap(2), m.b(2)),
+            ),
+            text,
+            cls=card_body,
+        ),
+        cls=combine_classes(
+            card,
+            bg_dui.base_100 if is_focused else bg_dui.base_200,
+            w.full,
+        ),
+    )
+
+
+def setup(route_prefix="/basic"):
+    """Set up the basic centered card stack demo.
+
+    Returns dict with config, ids, btn_ids, router, urls, state management,
+    and page rendering dependencies.
+    """
+    config = CardStackConfig(prefix="basic", click_to_focus=True)
+    ids = CardStackHtmlIds(prefix=config.prefix)
+    btn_ids = CardStackButtonIds(prefix=config.prefix)
+
+    state = CardStackState(visible_count=5, card_width=60)
+
+    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="basic-demo-container",
+        title="Basic Card Stack",
+        description="Centered focus. Navigate with arrow keys, scroll wheel, or click any card.",
+        progress_label="Item",
+    )

demos/bottom.py

@@ -0,0 +1,104 @@
+"""Bottom-anchored card stack demo (chat-style)."""
+
+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
+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 compact chat-style message card."""
+    is_focused = context.card_role == "focused"
+
+    index_badge = Span(
+        f"#{context.index + 1}",
+        cls=combine_classes(
+            badge,
+            badge_colors.secondary if is_focused else badge_colors.neutral,
+        )
+    )
+
+    return Div(
+        Div(
+            Div(index_badge, 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 if is_focused else bg_dui.base_200,
+            w.full,
+        ),
+    )
+
+
+def setup(route_prefix="/bottom"):
+    """Set up the bottom-anchored card stack demo.
+
+    Returns dict with config, ids, btn_ids, router, urls, state management,
+    and page rendering dependencies.
+    """
+    config = CardStackConfig(prefix="bottom", 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,  # Bottom-anchored
+    )
+
+    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="bottom-demo-container",
+        title="Bottom-Anchored Card Stack",
+        description="Chat-style layout with focused card at the bottom. Context cards appear above.",
+        progress_label="Message",
+    )

demos/data.py

@@ -0,0 +1,29 @@
+"""Sample data for card stack demos."""
+
+SAMPLE_ITEMS = [
+    "Machine learning is a subset of artificial intelligence that enables systems to learn and improve from experience without being explicitly programmed.",
+    "The core idea is to feed data into an algorithm, let it find patterns, and then use those patterns to make predictions or decisions on new, unseen data.",
+    "There are three main paradigms: supervised learning, unsupervised learning, and reinforcement learning. Each addresses a fundamentally different type of problem.",
+    "In supervised learning, the algorithm is trained on labeled examples — input-output pairs where the correct answer is known. The goal is to learn a mapping from inputs to outputs.",
+    "Classification and regression are the two primary supervised learning tasks. Classification predicts discrete categories, while regression predicts continuous numerical values.",
+    "Common supervised algorithms include linear regression, logistic regression, decision trees, random forests, support vector machines, and neural networks.",
+    "Unsupervised learning works with unlabeled data. The algorithm must discover hidden structure, groupings, or patterns without any guidance about what the correct output should be.",
+    "Clustering is the most common unsupervised task — grouping similar data points together. K-means, DBSCAN, and hierarchical clustering are widely used approaches.",
+    "Dimensionality reduction is another key unsupervised technique. Methods like PCA and t-SNE compress high-dimensional data into fewer dimensions while preserving important structure.",
+    "Reinforcement learning trains an agent to make sequences of decisions by interacting with an environment. The agent receives rewards or penalties and learns to maximize cumulative reward.",
+    "The training process in supervised learning involves minimizing a loss function — a measure of how far the model's predictions are from the true values.",
+    "Gradient descent is the optimization algorithm most commonly used to minimize the loss. It iteratively adjusts model parameters in the direction that reduces the error.",
+    "Overfitting occurs when a model learns the training data too well, including its noise and outliers, and performs poorly on new data. It is one of the central challenges in machine learning.",
+    "Regularization techniques like L1, L2, and dropout help prevent overfitting by adding constraints that discourage overly complex models.",
+    "The bias-variance tradeoff is a fundamental concept. High bias means the model is too simple and underfits; high variance means it is too complex and overfits.",
+    "Cross-validation is a technique for evaluating model performance by splitting data into multiple train-test folds, reducing the risk of evaluation bias from a single split.",
+    "Feature engineering — the process of creating, selecting, and transforming input variables — often has more impact on model performance than the choice of algorithm.",
+    "Neural networks are composed of layers of interconnected nodes. Each connection has a learnable weight, and each node applies a nonlinear activation function to its inputs.",
+    "Deep learning refers to neural networks with many layers. These architectures can automatically learn hierarchical feature representations from raw data.",
+    "Convolutional neural networks (CNNs) are specialized for grid-like data such as images. They use learnable filters that detect local patterns like edges, textures, and shapes.",
+    "Recurrent neural networks (RNNs) and their variants like LSTMs are designed for sequential data. They maintain hidden state that carries information across time steps.",
+    "Transformers replaced RNNs for most sequence tasks by using self-attention mechanisms that can relate any position in a sequence to any other position in parallel.",
+    "Large language models like GPT and Claude are transformer-based models trained on massive text corpora. They learn to predict the next token and develop broad language understanding.",
+    "Transfer learning allows a model pretrained on a large dataset to be fine-tuned on a smaller, task-specific dataset. This dramatically reduces the data and compute needed for new tasks.",
+    "The field continues to evolve rapidly, with active research in areas like multimodal learning, efficient architectures, alignment, interpretability, and learning from human feedback.",
+]

demos/shared.py

@@ -0,0 +1,153 @@
+"""Shared utilities for card stack demos."""
+
+from fasthtml.common import Div, H1, P, Span
+
+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 container, max_w
+from cjm_fasthtml_tailwind.utilities.typography import font_size, font_weight
+from cjm_fasthtml_tailwind.utilities.flexbox_and_grid import (
+    flex_display, items, justify, gap
+)
+from cjm_fasthtml_tailwind.utilities.borders import rounded
+from cjm_fasthtml_tailwind.core.base import combine_classes
+
+from cjm_fasthtml_keyboard_navigation.core.manager import ZoneManager
+from cjm_fasthtml_keyboard_navigation.components.system import render_keyboard_system
+
+from cjm_fasthtml_card_stack.components.viewport import render_viewport
+from cjm_fasthtml_card_stack.components.controls import (
+    render_width_slider, render_scale_slider, render_card_count_select
+)
+from cjm_fasthtml_card_stack.components.progress import render_progress_indicator
+from cjm_fasthtml_card_stack.js.core import generate_card_stack_js
+from cjm_fasthtml_card_stack.keyboard.actions import (
+    create_card_stack_focus_zone, create_card_stack_nav_actions,
+    build_card_stack_url_map, render_card_stack_action_buttons
+)
+
+
+def build_keyboard_system(config, btn_ids, ids, urls):
+    """Build keyboard navigation system for a card stack."""
+    zone = create_card_stack_focus_zone(ids)
+    nav_actions = create_card_stack_nav_actions(zone.id, btn_ids, config)
+    manager = ZoneManager(zones=(zone,), actions=nav_actions)
+
+    url_map = build_card_stack_url_map(btn_ids, urls)
+    target_map = {btn_id: f"#{ids.card_stack}" for btn_id in url_map}
+    swap_map = {btn_id: "none" for btn_id in url_map}
+    include_map = {btn_id: f"#{ids.focused_index_input}" for btn_id in url_map}
+
+    return render_keyboard_system(
+        manager,
+        url_map=url_map,
+        target_map=target_map,
+        swap_map=swap_map,
+        include_map=include_map,
+        show_hints=False,
+        include_state_inputs=True,
+    )
+
+
+def render_demo_page(
+    title,
+    description,
+    state_getter,
+    items_getter,
+    render_card,
+    config,
+    ids,
+    btn_ids,
+    urls,
+    container_id,
+    progress_label="Item",
+):
+    """Render a standard card stack demo page.
+
+    Returns a page_content() callable for use with handle_htmx_request.
+    """
+
+    def page_content():
+        state = state_getter()
+        card_items = items_getter()
+
+        kb_system = build_keyboard_system(config, btn_ids, ids, urls)
+
+        js_script = generate_card_stack_js(
+            ids=ids,
+            button_ids=btn_ids,
+            config=config,
+            urls=urls,
+            container_id=container_id,
+        )
+
+        return Div(
+            # Visual content container (used for viewport height calculation)
+            Div(
+                # Header
+                Div(
+                    H1(title, cls=combine_classes(font_size._2xl, font_weight.bold)),
+                    P(description,
+                      cls=combine_classes(text_dui.base_content, font_size.sm, m.b(4))),
+                    cls=m.b(2)
+                ),
+
+                # Controls row
+                Div(
+                    Div(
+                        render_card_count_select(config, ids, state.visible_count),
+                        cls=combine_classes(flex_display, items.center, gap(2)),
+                    ),
+                    Div(
+                        Span("Width:", cls=combine_classes(font_size.sm, text_dui.base_content)),
+                        render_width_slider(config, ids, state.card_width),
+                        cls=combine_classes(flex_display, items.center, gap(2)),
+                    ),
+                    Div(
+                        Span("Scale:", cls=combine_classes(font_size.sm, text_dui.base_content)),
+                        render_scale_slider(config, ids, state.card_scale),
+                        cls=combine_classes(flex_display, items.center, gap(2)),
+                    ),
+                    cls=combine_classes(
+                        flex_display, items.center, justify.between,
+                        gap(4), m.b(2), p(2),
+                        bg_dui.base_200, rounded.lg,
+                    )
+                ),
+
+                # Viewport
+                render_viewport(
+                    card_items=card_items,
+                    state=state,
+                    config=config,
+                    render_card=render_card,
+                    ids=ids,
+                    urls=urls,
+                ),
+
+                # Footer
+                Div(
+                    render_progress_indicator(
+                        state.focused_index, len(card_items), ids, label=progress_label
+                    ),
+                    cls=combine_classes(flex_display, justify.center, m.t(2))
+                ),
+
+                id=container_id,
+            ),
+
+            # Keyboard system
+            kb_system.script,
+            kb_system.hidden_inputs,
+            kb_system.action_buttons,
+
+            # Hidden buttons for JS-callback-triggered actions
+            render_card_stack_action_buttons(btn_ids, urls, ids),
+
+            # Card stack JS
+            js_script,
+
+            cls=combine_classes(container, max_w._6xl, m.x.auto, p(4))
+        )
+
+    return page_content

cjm_fasthtml_card_stack-0.0.1.dist-info/RECORD

@@ -1,8 +0,0 @@
-cjm_fasthtml_card_stack/__init__.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
-cjm_fasthtml_card_stack/_modidx.py,sha256=jYNj6LPbD5I8yDghD3Lx9XWsDnWqc_oNCESguSF8blA,25105
-cjm_fasthtml_card_stack-0.0.1.dist-info/licenses/LICENSE,sha256=xV8xoN4VOL0uw9X8RSs2IMuD_Ss_a9yAbtGNeBWZwnw,11337
-cjm_fasthtml_card_stack-0.0.1.dist-info/METADATA,sha256=PDmhCLd0lgo4dGhsEojEvH6TV0bguLQDC9YnRA3Zwzg,36798
-cjm_fasthtml_card_stack-0.0.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-cjm_fasthtml_card_stack-0.0.1.dist-info/entry_points.txt,sha256=qTw6qaijkEUH1AcPQhpTqJ8TPiUSMnpn0Cvg4hXoX90,68
-cjm_fasthtml_card_stack-0.0.1.dist-info/top_level.txt,sha256=y6h84kPxytZIWTD4ITK2Gsi40KivBsEfSe8131fIoR4,24
-cjm_fasthtml_card_stack-0.0.1.dist-info/RECORD,,