cjm-fasthtml-app-core 0.0.1

Core utilities and reusable patterns for FastHTML applications including page layouts, HTMX request handling, alerts, and navbar components.

cjm-fasthtml-app-core

Install

pip install cjm_fasthtml_app_core

Project Structure

nbs/
├── components/ (2)
│   ├── alerts.ipynb  # Alert components for displaying success, error, warning, and info messages
│   └── navbar.ipynb  # Responsive navigation bar components with mobile support
└── core/ (3)
    ├── html_ids.ipynb  # Base HTML ID constants for FastHTML applications
    ├── htmx.ipynb      # Utilities for handling HTMX requests and responses
    └── layout.ipynb    # Page layout utilities for wrapping content with common page structure

Total: 5 notebooks across 2 directories

Module Dependencies

graph LR
    components_alerts[components.alerts<br/>Alerts]
    components_navbar[components.navbar<br/>Navbar]
    core_html_ids[core.html_ids<br/>HTML IDs]
    core_htmx[core.htmx<br/>HTMX Utilities]
    core_layout[core.layout<br/>Layout]

    components_alerts --> core_html_ids
    components_navbar --> core_html_ids
    core_layout --> core_html_ids

3 cross-module dependencies detected

CLI Reference

No CLI commands found in this project.

Module Overview

Detailed documentation for each module in the project:

Alerts (alerts.ipynb)

Alert components for displaying success, error, warning, and info messages

Import

from cjm_fasthtml_app_core.components.alerts import (
    create_success_alert,
    create_error_alert,
    create_warning_alert,
    create_info_alert
)

Functions

def _create_auto_dismiss_script(
    timeout_ms: int = 3000  # Time in milliseconds before auto-dismiss
) -> Script:  # Script element for auto-dismissing alerts
    "Create a script that auto-dismisses the alert after a timeout."

def create_success_alert(
    message: str,  # The success message to display
    timeout_ms: int = 3000  # Time in milliseconds before auto-dismiss
) -> Div:  # Div element containing the success alert
    "Create a success alert that auto-dismisses."

def create_error_alert(
    message: str,  # The error message to display
    details: Optional[str] = None  # Optional additional details text
) -> Div:  # Div element containing the error alert
    "Create an error alert with optional details."

def create_warning_alert(
    message: str,  # The warning message to display
    details: Optional[str] = None  # Optional additional details text
) -> Div:  # Div element containing the warning alert
    "Create a warning alert with optional details."

def create_info_alert(
    message: str,  # The info message to display
    details: Optional[str] = None  # Optional additional details text
) -> Div:  # Div element containing the info alert
    "Create an info alert with optional details."

HTML IDs (html_ids.ipynb)

Base HTML ID constants for FastHTML applications

Import

from cjm_fasthtml_app_core.core.html_ids import (
    AppHtmlIds
)

Classes

class AppHtmlIds:
    """
    Base HTML ID constants for FastHTML applications.
    
    This class provides centralized HTML ID constants that are commonly used
    across FastHTML applications. All IDs are defined as class attributes
    for IDE autocomplete and type checking.
    
    For IDE Support:
        IDEs like VS Code with Pylance will autocomplete these attributes and warn
        if you try to access non-existent attributes. To add app-specific IDs,
        extend this class:
        
        ```python
        class MyAppHtmlIds(AppHtmlIds):
            CUSTOM_SECTION = "custom-section"
            SIDEBAR = "sidebar"
        ```
    
    Note:
        The typing.Final annotation indicates these are constants that shouldn't
        be reassigned at runtime.
    """
    
    def as_selector(id_str: str) -> str
        "Convert an ID to a CSS selector format (with #)."

HTMX Utilities (htmx.ipynb)

Utilities for handling HTMX requests and responses

Import

from cjm_fasthtml_app_core.core.htmx import (
    is_htmx_request,
    handle_htmx_request
)

Functions

def is_htmx_request(
    request  # FastHTML request object
) -> bool:  # True if request is from HTMX
    """
    Check if a request is an HTMX request.
    
    HTMX requests include the 'HX-Request' header set to 'true'.
    This is useful for conditionally returning partial HTML vs full pages.
    """

def handle_htmx_request(
    request,  # FastHTML request object
    content_fn: Callable,  # Function to generate content
    *args,  # Positional arguments for content_fn
    wrap_fn: Optional[Callable] = None,  # Optional wrapper function for full page requests
    **kwargs  # Keyword arguments for content_fn
):  # Content or wrapped content based on request type
    """
    Handle HTMX vs full page response pattern.
    
    This is a common pattern where HTMX requests return just the content,
    while full page requests wrap the content with page layout.
    
    Args:
        request: FastHTML request object
        content_fn: Function to generate the main content
        *args: Positional arguments passed to content_fn
        wrap_fn: Optional function to wrap content for full page requests
        **kwargs: Keyword arguments passed to content_fn
    
    Returns:
        Content (for HTMX requests) or wrapped content (for full page requests)
    
    Example:
        ```python
        @app.get("/dashboard")
        def dashboard(request):
            return handle_htmx_request(
                request,
                dashboard_content,
                wrap_fn=wrap_with_layout
            )
        ```
    """

Layout (layout.ipynb)

Page layout utilities for wrapping content with common page structure

Import

from cjm_fasthtml_app_core.core.layout import (
    wrap_with_layout
)

Functions

def wrap_with_layout(
    content: Any,  # The main content to display
    navbar: Optional[Any] = None,  # Optional navbar component
    footer: Optional[Any] = None,  # Optional footer component
    container_id: str = AppHtmlIds.MAIN_CONTENT,  # ID for the main content container
    container_tag: str = "div"  # HTML tag for the container (div, main, section, etc.)
) -> Any:  # Main element with navbar and content
    """
    Wrap content with the full page layout including optional navbar and footer.
    
    This utility provides a consistent page structure across your application.
    It wraps your content with optional navbar and footer components.
    
    Args:
        content: The main page content
        navbar: Optional navbar component (typically from create_navbar)
        footer: Optional footer component
        container_id: HTML ID for the main content container
        container_tag: HTML tag to use for the container
    
    Returns:
        Main element containing navbar, content, and footer
    
    Example:
        ```python
        from cjm_fasthtml_app_core.components.navbar import create_navbar
        from cjm_fasthtml_app_core.core.layout import wrap_with_layout
        
        my_navbar = create_navbar(title="My App", nav_items=[...])
        page = wrap_with_layout(my_content, navbar=my_navbar)
        ```
    """

Navbar (navbar.ipynb)

Responsive navigation bar components with mobile support

Import

from cjm_fasthtml_app_core.components.navbar import (
    create_nav_link,
    create_navbar
)

Functions

def create_nav_link(
    label: str,  # Link text to display
    route,  # FastHTML route object with .to() method
    target_id: str = AppHtmlIds.MAIN_CONTENT  # HTMX target container ID
) -> A:  # Anchor element with HTMX attributes
    """
    Create a navigation link with HTMX attributes for SPA-like behavior.
    
    Creates an anchor element that uses HTMX to load content without full page reload.
    
    Args:
        label: Text to display for the link
        route: FastHTML route object (should have .to() method)
        target_id: HTML ID of the container to update (without #)
    
    Returns:
        Anchor element configured for HTMX navigation
    
    Example:
        ```python
        from fasthtml.common import *
        app, rt = fast_app()
        
        @rt("/about")
        def about(): ...
        
        link = create_nav_link("About", about)
        ```
    """

def create_navbar(
    title: str,  # Application title
    nav_items: List[Tuple[str, Any]],  # List of (label, route) tuples
    home_route: Optional[Any] = None,  # Optional home route for title link
    theme_selector: bool = True,  # Whether to include theme selector
    target_id: str = AppHtmlIds.MAIN_CONTENT,  # HTMX target container ID
    **navbar_kwargs  # Additional kwargs for navbar styling
) -> Div:  # Navbar component
    """
    Create a responsive navigation bar with mobile dropdown menu.
    
    Creates a DaisyUI navbar with:
    - Responsive design (mobile dropdown, desktop horizontal menu)
    - Optional theme selector
    - HTMX-enabled navigation links
    - Clickable title that links to home
    
    Args:
        title: Application title displayed in navbar
        nav_items: List of (label, route) tuples for navigation links
        home_route: Optional route for title click (defaults to first nav item)
        theme_selector: Whether to show DaisyUI theme selector
        target_id: HTML ID of the content container to update
        **navbar_kwargs: Additional styling classes/attributes for navbar
    
    Returns:
        Complete navbar component wrapped in Div
    
    Example:
        ```python
        navbar = create_navbar(
            title="My App",
            nav_items=[
                ("Home", home_route),
                ("About", about_route),
                ("Settings", settings_route)
            ],
            theme_selector=True
        )
        ```
    """