cjm-fasthtml-interactions 0.0.13

Reusable user interaction patterns for FastHTML applications including multi-step wizards, master-detail views, modal workflows, and other stateful UI orchestration patterns.

cjm-fasthtml-interactions

Install

pip install cjm_fasthtml_interactions

Project Structure

nbs/
├── core/ (2)
│   ├── context.ipynb   # Context management for interaction patterns providing access to state, request, and custom data
│   └── html_ids.ipynb  # Centralized HTML ID constants for interaction pattern components
└── patterns/ (4)
    ├── async_loading.ipynb     # Pattern for asynchronous content loading with skeleton loaders and loading indicators
    ├── master_detail.ipynb     # Responsive sidebar navigation pattern with master list and detail content area. On mobile devices, the sidebar is hidden in a drawer that can be toggled. On desktop (lg+ screens), the sidebar is always visible.
    ├── step_flow.ipynb         # Multi-step wizard pattern with state management, navigation, and route generation
    └── tabbed_interface.ipynb  # Multi-tab interface pattern with automatic routing, state management, and DaisyUI styling

Total: 6 notebooks across 2 directories

Module Dependencies

graph LR
    core_context[core.context<br/>Interaction Context]
    core_html_ids[core.html_ids<br/>HTML IDs]
    patterns_async_loading[patterns.async_loading<br/>Async Loading Container]
    patterns_master_detail[patterns.master_detail<br/>Master-Detail]
    patterns_step_flow[patterns.step_flow<br/>Step Flow]
    patterns_tabbed_interface[patterns.tabbed_interface<br/>Tabbed Interface]

    patterns_master_detail --> core_html_ids
    patterns_master_detail --> core_context
    patterns_step_flow --> core_html_ids
    patterns_step_flow --> core_context
    patterns_tabbed_interface --> core_html_ids
    patterns_tabbed_interface --> core_context

6 cross-module dependencies detected

CLI Reference

No CLI commands found in this project.

Module Overview

Detailed documentation for each module in the project:

Async Loading Container (async_loading.ipynb)

Pattern for asynchronous content loading with skeleton loaders and loading indicators

Import

from cjm_fasthtml_interactions.patterns.async_loading import (
    LoadingType,
    AsyncLoadingContainer
)

Functions

def AsyncLoadingContainer(
    container_id: str,  # HTML ID for the container
    load_url: str,  # URL to fetch content from
    loading_type: LoadingType = LoadingType.SPINNER,  # Type of loading indicator
    loading_size: str = "lg",  # Size of loading indicator (xs, sm, md, lg)
    loading_message: Optional[str] = None,  # Optional message to display while loading
    skeleton_content: Optional[Any] = None,  # Optional skeleton/placeholder content
    trigger: str = "load",  # HTMX trigger event (default: load on page load)
    swap: str = "outerHTML",  # HTMX swap method (default: replace entire container)
    container_cls: Optional[str] = None,  # Additional CSS classes for container
    **kwargs  # Additional attributes for the container
) -> FT:  # Div element with async loading configured
    """
    Create a container that asynchronously loads content from a URL.
    
    The container displays a loading indicator initially and uses HTMX to load
    content when triggered. Once loaded, the entire container is replaced with
    the fetched content (by default using outerHTML swap).
    
    Examples:
        # Simple spinner loader
        AsyncLoadingContainer(
            container_id="my-content",
            load_url="/api/get-content"
        )
        
        # With loading message
        AsyncLoadingContainer(
            container_id="dashboard-stats",
            load_url="/api/stats",
            loading_message="Loading statistics..."
        )
        
        # With skeleton content
        AsyncLoadingContainer(
            container_id="user-card",
            load_url="/api/user/123",
            loading_type=LoadingType.NONE,
            skeleton_content=Div("User profile skeleton...", cls="skeleton")
        )
        
        # Delayed load (triggered by intersection)
        AsyncLoadingContainer(
            container_id="lazy-image",
            load_url="/api/image/456",
            trigger="intersect once"
        )
    """

Classes

class LoadingType(Enum):
    "Types of loading indicators for async content."

Interaction Context (context.ipynb)

Context management for interaction patterns providing access to state, request, and custom data

Import

from cjm_fasthtml_interactions.core.context import (
    InteractionContext
)

Classes

@dataclass
class InteractionContext:
    "Context for interaction patterns providing access to state, request, and custom data."
    
    state: Dict[str, Any] = field(...)  # Workflow state
    request: Optional[Any]  # FastHTML request object
    session: Optional[Any]  # FastHTML session object
    data: Dict[str, Any] = field(...)  # Custom data from data loaders
    metadata: Dict[str, Any] = field(...)  # Additional metadata
    
    def get(self,
                key: str,  # Key to retrieve from state
                default: Any = None  # Default value if key not found
               ) -> Any:  # Value from state or default
        "Get value from workflow state."
    
    def get_data(self,
                     key: str,  # Key to retrieve from data
                     default: Any = None  # Default value if key not found
                    ) -> Any:  # Value from data or default
        "Get value from custom data."
    
    def has(self,
                key: str  # Key to check in state
               ) -> bool:  # True if key exists in state
        "Check if key exists in workflow state."
    
    def set(self,
                key: str,  # Key to set in state
                value: Any  # Value to store
               ) -> None
        "Set value in workflow state."
    
    def get_all_state(self) -> Dict[str, Any]:  # All workflow state
            """Get all workflow state as dictionary."""
            return self.state.copy()
        
        def update_state(self, 
                         updates: Dict[str, Any]  # State updates to apply
                        ) -> None
        "Get all workflow state as dictionary."
    
    def update_state(self,
                         updates: Dict[str, Any]  # State updates to apply
                        ) -> None
        "Update multiple state values at once."

HTML IDs (html_ids.ipynb)

Centralized HTML ID constants for interaction pattern components

Import

from cjm_fasthtml_interactions.core.html_ids import (
    InteractionHtmlIds
)

Classes

class InteractionHtmlIds(AppHtmlIds):
    """
    HTML ID constants for interaction pattern components.
    
    Inherits from AppHtmlIds:
        - MAIN_CONTENT = "main-content"
        - ALERT_CONTAINER = "alert-container"
        - as_selector(id_str) - static method
    """
    
    def step_content(step_id: str  # Step identifier
                        ) -> str:  # HTML ID for step content
        "Generate HTML ID for a specific step's content."
    
    def step_indicator(step_id: str  # Step identifier
                          ) -> str:  # HTML ID for step indicator
        "Generate HTML ID for a specific step's progress indicator."
    
    def tab_radio(tab_id: str  # Tab identifier
                     ) -> str:  # HTML ID for tab radio input
        "Generate HTML ID for a specific tab's radio input."
    
    def tab_content(tab_id: str  # Tab identifier
                       ) -> str:  # HTML ID for tab content
        "Generate HTML ID for a specific tab's content."
    
    def master_item(item_id: str  # Item identifier
                       ) -> str:  # HTML ID for master list item
        "Generate HTML ID for a master list item."
    
    def master_group(group_id: str  # Group identifier
                        ) -> str:  # HTML ID for master list group
        "Generate HTML ID for a master list group."
    
    def detail_content(item_id: str  # Item identifier
                          ) -> str:  # HTML ID for detail content
        "Generate HTML ID for detail content area."

Master-Detail (master_detail.ipynb)

Responsive sidebar navigation pattern with master list and detail content area. On mobile devices, the sidebar is hidden in a drawer that can be toggled. On desktop (lg+ screens), the sidebar is always visible.

Import

from cjm_fasthtml_interactions.patterns.master_detail import (
    DetailItem,
    DetailItemGroup,
    MasterDetail
)

Functions

@patch
def get_item(self:MasterDetail, 
             item_id: str  # Item identifier
            ) -> Optional[DetailItem]:  # DetailItem or None
    "Get item by ID."

@patch
def create_context(self:MasterDetail, 
                   request: Any,  # FastHTML request object
                   sess: Any,  # FastHTML session object
                   item: DetailItem  # Current item
                  ) -> InteractionContext:  # Interaction context for rendering
    "Create interaction context for an item."

@patch
def render_master(self:MasterDetail,
                  active_item_id: str,  # Currently active item ID
                  item_route_func: Callable[[str], str],  # Function to generate item route
                  include_wrapper: bool = True  # Whether to include outer wrapper div
                 ) -> FT:  # Master list element
    "Render master list (sidebar) with items and groups."

@patch
def _render_menu_items(self:MasterDetail,
                       active_item_id: str,  # Currently active item ID
                       item_route_func: Callable[[str], str]  # Function to generate item route
                      ) -> List[FT]:  # List of menu item elements
    "Render menu items and groups (internal helper)."

@patch
def render_master_oob(self:MasterDetail,
                      active_item_id: str,  # Currently active item ID
                      item_route_func: Callable[[str], str]  # Function to generate item route
                     ) -> FT:  # Master list with OOB swap attribute
    "Render master list with OOB swap attribute for coordinated updates."

@patch
def render_detail(self:MasterDetail,
                  item: DetailItem,  # Item to render
                  ctx: InteractionContext  # Interaction context
                 ) -> FT:  # Detail content
    "Render detail content for an item."

@patch
def render_full_interface(self:MasterDetail,
                         active_item_id: str,  # Currently active item ID
                         item_route_func: Callable[[str], str],  # Function to generate item route
                         request: Any,  # FastHTML request object
                         sess: Any  # FastHTML session object
                        ) -> FT:  # Complete master-detail interface
    "Render complete responsive master-detail interface with drawer for mobile."

@patch
def create_router(self:MasterDetail,
                  prefix: str = ""  # URL prefix for routes (e.g., "/media")
                 ) -> APIRouter:  # APIRouter with generated routes
    "Create FastHTML router with generated routes for this master-detail interface."

Classes

@dataclass
class DetailItem:
    "Definition of a single item in the master-detail pattern."
    
    id: str  # Unique identifier
    label: str  # Display text in master list
    render: Callable[[InteractionContext], Any]  # Function to render detail view
    badge_text: Optional[str]  # Optional badge text (e.g., "configured", "3 items")
    badge_color: Optional[str]  # Badge color class (e.g., badge_colors.success)
    icon: Optional[Any]  # Optional icon element
    data_loader: Optional[Callable[[Any], Dict[str, Any]]]  # Data loading function
    load_on_demand: bool = True  # Whether to load content only when item is selected

@dataclass
class DetailItemGroup:
    "Group of related detail items in a collapsible section."
    
    id: str  # Group identifier
    title: str  # Group display title
    items: List[DetailItem]  # Items in this group
    default_open: bool = True  # Whether group is expanded by default
    icon: Optional[Any]  # Optional group icon
    badge_text: Optional[str]  # Optional badge for the group
    badge_color: Optional[str]  # Badge color for the group

class MasterDetail:
    def __init__(
        self,
        interface_id: str,  # Unique identifier for this interface
        items: List[Union[DetailItem, DetailItemGroup]],  # List of items/groups
        default_item: Optional[str] = None,  # Default item ID (defaults to first item)
        container_id: str = InteractionHtmlIds.MASTER_DETAIL_CONTAINER,  # HTML ID for container
        master_id: str = InteractionHtmlIds.MASTER_DETAIL_MASTER,  # HTML ID for master list
        detail_id: str = InteractionHtmlIds.MASTER_DETAIL_DETAIL,  # HTML ID for detail area
        master_width: str = "w-64",  # Tailwind width class for master list
        master_title: Optional[str] = None,  # Optional title for master list
        show_on_htmx_only: bool = False  # Whether to show full interface for non-HTMX requests
    )
    "Manage master-detail interfaces with sidebar navigation and detail content area."
    
    def __init__(
            self,
            interface_id: str,  # Unique identifier for this interface
            items: List[Union[DetailItem, DetailItemGroup]],  # List of items/groups
            default_item: Optional[str] = None,  # Default item ID (defaults to first item)
            container_id: str = InteractionHtmlIds.MASTER_DETAIL_CONTAINER,  # HTML ID for container
            master_id: str = InteractionHtmlIds.MASTER_DETAIL_MASTER,  # HTML ID for master list
            detail_id: str = InteractionHtmlIds.MASTER_DETAIL_DETAIL,  # HTML ID for detail area
            master_width: str = "w-64",  # Tailwind width class for master list
            master_title: Optional[str] = None,  # Optional title for master list
            show_on_htmx_only: bool = False  # Whether to show full interface for non-HTMX requests
        )
        "Initialize master-detail manager."

Step Flow (step_flow.ipynb)

Multi-step wizard pattern with state management, navigation, and route generation

Import

from cjm_fasthtml_interactions.patterns.step_flow import (
    Step,
    StepFlow
)

Functions

@patch
def get_step(self:StepFlow, 
             step_id: str  # Step identifier
            ) -> Optional[Step]:  # Step object or None
    "Get step by ID."

@patch
def get_step_index(self:StepFlow, 
                   step_id: str  # Step identifier
                  ) -> Optional[int]:  # Step index or None
    "Get step index by ID."

@patch
def get_current_step_id(self:StepFlow, 
                        sess: Any  # FastHTML session object
                       ) -> str:  # Current step ID
    "Get current step ID from session."

@patch
def set_current_step(self:StepFlow, 
                     sess: Any,  # FastHTML session object
                     step_id: str  # Step ID to set as current
                    ) -> None
    "Set current step in session."

@patch
def get_next_step_id(self:StepFlow, 
                     current_step_id: str  # Current step ID
                    ) -> Optional[str]:  # Next step ID or None if last step
    "Get the ID of the next step."

@patch
def get_previous_step_id(self:StepFlow, 
                         current_step_id: str  # Current step ID
                        ) -> Optional[str]:  # Previous step ID or None if first step
    "Get the ID of the previous step."

@patch
def is_last_step(self:StepFlow, 
                 step_id: str  # Step ID to check
                ) -> bool:  # True if this is the last step
    "Check if step is the last step."

@patch
def is_first_step(self:StepFlow, 
                  step_id: str  # Step ID to check
                 ) -> bool:  # True if this is the first step
    "Check if step is the first step."

@patch
def get_workflow_state(self:StepFlow, 
                       sess: Any  # FastHTML session object
                      ) -> Dict[str, Any]:  # All workflow state
    "Get all workflow state from session."

@patch
def update_workflow_state(self:StepFlow, 
                          sess: Any,  # FastHTML session object
                          updates: Dict[str, Any]  # State updates
                         ) -> None
    "Update workflow state with new values."

@patch
def clear_workflow(self:StepFlow, 
                   sess: Any  # FastHTML session object
                  ) -> None
    "Clear all workflow state."

@patch
def create_context(self:StepFlow, 
                   request: Any,  # FastHTML request object
                   sess: Any,  # FastHTML session object
                   step: Step  # Current step
                  ) -> InteractionContext:  # Interaction context for rendering
    "Create interaction context for a step."

@patch
def render_progress(self:StepFlow, 
                    sess: Any  # FastHTML session object
                   ) -> FT:  # Progress indicator or empty Div
    "Render progress indicator showing all steps."

@patch
def render_step_content(self:StepFlow,
                        step_obj: Step,  # Step to render
                        ctx: InteractionContext,  # Interaction context
                        next_route: str,  # Route for next/submit
                        back_route: Optional[str] = None,  # Route for back
                        cancel_route: Optional[str] = None  # Route for cancel
                       ) -> FT:  # Complete step content with optional progress and navigation
    "Render step content with optional progress indicator and navigation."

@patch
def render_navigation(self:StepFlow,
                      step_id: str,  # Current step ID
                      next_route: str,  # Route for next/submit action
                      back_route: Optional[str] = None,  # Route for back action
                      cancel_route: Optional[str] = None,  # Route for cancel action
                     ) -> FT:  # Navigation button container
    "Render navigation buttons for a step."

@patch
def create_router(self:StepFlow,
                  prefix: str = ""  # URL prefix for routes (e.g., "/transcription")
                 ) -> APIRouter:  # APIRouter with generated routes
    "Create FastHTML router with generated routes for this flow."

Classes

@dataclass
class Step:
    "Definition of a single step in a multi-step workflow."
    
    id: str  # Unique step identifier (used in URLs)
    title: str  # Display title for the step
    render: Callable[[InteractionContext], Any]  # Function to render step UI
    validate: Optional[Callable[[Dict[str, Any]], bool]]  # Validation function
    data_loader: Optional[Callable[[Any], Dict[str, Any]]]  # Data loading function
    data_keys: List[str] = field(...)  # State keys managed by this step
    can_skip: bool = False  # Whether this step can be skipped
    show_back: bool = True  # Whether to show back button
    show_cancel: bool = True  # Whether to show cancel button
    next_button_text: str = 'Continue'  # Text for next/submit button
    
    def is_valid(self, state: Dict[str, Any]  # Current workflow state
                    ) -> bool:  # True if step is complete and valid
        "Check if step has valid data in state."

class StepFlow:
    def __init__(
        self,
        flow_id: str,  # Unique identifier for this workflow
        steps: List[Step],  # List of step definitions
        container_id: str = InteractionHtmlIds.STEP_FLOW_CONTAINER,  # HTML ID for content container
        on_complete: Optional[Callable[[Dict[str, Any], Any], Any]] = None,  # Completion handler
        show_progress: bool = False,  # Whether to show progress indicator
        wrap_in_form: bool = True  # Whether to wrap content + navigation in a form
    )
    "Manage multi-step workflows with automatic route generation and state management."
    
    def __init__(
            self,
            flow_id: str,  # Unique identifier for this workflow
            steps: List[Step],  # List of step definitions
            container_id: str = InteractionHtmlIds.STEP_FLOW_CONTAINER,  # HTML ID for content container
            on_complete: Optional[Callable[[Dict[str, Any], Any], Any]] = None,  # Completion handler
            show_progress: bool = False,  # Whether to show progress indicator
            wrap_in_form: bool = True  # Whether to wrap content + navigation in a form
        )
        "Initialize step flow manager."

Tabbed Interface (tabbed_interface.ipynb)

Multi-tab interface pattern with automatic routing, state management, and DaisyUI styling

Import

from cjm_fasthtml_interactions.patterns.tabbed_interface import (
    Tab,
    TabbedInterface
)

Functions

@patch
def get_tab(self:TabbedInterface, 
            tab_id: str  # Tab identifier
           ) -> Optional[Tab]:  # Tab object or None
    "Get tab by ID."

@patch
def get_tab_index(self:TabbedInterface, 
                  tab_id: str  # Tab identifier
                 ) -> Optional[int]:  # Tab index or None
    "Get tab index by ID."

@patch
def create_context(self:TabbedInterface, 
                   request: Any,  # FastHTML request object
                   sess: Any,  # FastHTML session object
                   tab: Tab  # Current tab
                  ) -> InteractionContext:  # Interaction context for rendering
    "Create interaction context for a tab."

@patch
def render_tabs(self:TabbedInterface,
                current_tab_id: str,  # Currently active tab ID
                tab_route_func: Callable[[str], str]  # Function to generate tab route
               ) -> FT:  # Tab navigation element
    "Render tab navigation using DaisyUI radio-based tabs."

@patch
def render_tab_content(self:TabbedInterface,
                       tab_obj: Tab,  # Tab to render
                       ctx: InteractionContext  # Interaction context
                      ) -> FT:  # Tab content
    "Render tab content."

@patch
def render_full_interface(self:TabbedInterface,
                         current_tab_id: str,  # Currently active tab ID
                         tab_route_func: Callable[[str], str],  # Function to generate tab route
                         request: Any,  # FastHTML request object
                         sess: Any  # FastHTML session object
                        ) -> FT:  # Complete tabbed interface
    "Render complete tabbed interface with tabs and content area."

@patch
def create_router(self:TabbedInterface,
                  prefix: str = ""  # URL prefix for routes (e.g., "/dashboard")
                 ) -> APIRouter:  # APIRouter with generated routes
    "Create FastHTML router with generated routes for this tabbed interface."

Classes

@dataclass
class Tab:
    "Definition of a single tab in a tabbed interface."
    
    id: str  # Unique tab identifier (used in URLs)
    label: str  # Display label for the tab
    render: Callable[[InteractionContext], Any]  # Function to render tab content
    title: Optional[str]  # Optional title/tooltip for the tab
    data_loader: Optional[Callable[[Any], Dict[str, Any]]]  # Data loading function
    load_on_demand: bool = True  # Whether to load content only when tab is selected

class TabbedInterface:
    def __init__(
        self,
        interface_id: str,  # Unique identifier for this interface
        tabs_list: List[Tab],  # List of tab definitions
        default_tab: Optional[str] = None,  # Default tab ID (defaults to first tab)
        container_id: str = InteractionHtmlIds.TABBED_INTERFACE_CONTAINER,  # HTML ID for container
        tabs_id: str = InteractionHtmlIds.TABBED_INTERFACE_TABS,  # HTML ID for tabs element
        content_id: str = InteractionHtmlIds.TABBED_INTERFACE_CONTENT,  # HTML ID for content area
        tab_style: Optional[str] = None,  # DaisyUI tab style (lift, bordered, boxed)
        show_on_htmx_only: bool = False  # Whether to show full page layout for non-HTMX requests
    )
    "Manage multi-tab interfaces with automatic route generation and HTMX content loading."
    
    def __init__(
            self,
            interface_id: str,  # Unique identifier for this interface
            tabs_list: List[Tab],  # List of tab definitions
            default_tab: Optional[str] = None,  # Default tab ID (defaults to first tab)
            container_id: str = InteractionHtmlIds.TABBED_INTERFACE_CONTAINER,  # HTML ID for container
            tabs_id: str = InteractionHtmlIds.TABBED_INTERFACE_TABS,  # HTML ID for tabs element
            content_id: str = InteractionHtmlIds.TABBED_INTERFACE_CONTENT,  # HTML ID for content area
            tab_style: Optional[str] = None,  # DaisyUI tab style (lift, bordered, boxed)
            show_on_htmx_only: bool = False  # Whether to show full page layout for non-HTMX requests
        )
        "Initialize tabbed interface manager."