Metadata-Version: 2.4
Name: cjm-fasthtml-app-core
Version: 0.0.15
Summary: Core utilities and reusable patterns for FastHTML applications including page layouts, HTMX request handling, navbar, and confirm modal components.
Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
License: Apache-2.0
Project-URL: Repository, https://github.com/cj-mills/cjm-fasthtml-app-core
Project-URL: Documentation, https://cj-mills.github.io/cjm-fasthtml-app-core
Keywords: nbdev,jupyter,notebook,python
Classifier: Natural Language :: English
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cjm_fasthtml_daisyui
Requires-Dist: cjm_fasthtml_design_system>=0.0.9
Requires-Dist: cjm_fasthtml_lucide_icons
Dynamic: license-file

# cjm-fasthtml-app-core


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Install

``` bash
pip install cjm_fasthtml_app_core
```

## Project Structure

    nbs/
    ├── components/ (2)
    │   ├── confirm_modal.ipynb  # Generic destructive-confirm modal &mdash; Cancel-on-left, Confirm-on-right, with backdrop click-to-dismiss and defensive form-submission guards. Codifies **Convention V12 (Destructive-confirm composition)** as running code.
    │   └── navbar.ipynb         # Responsive navigation bar components with mobile support
    └── core/ (4)
        ├── 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
        └── routing.ipynb   # Routing utilities for FastHTML applications

Total: 6 notebooks across 2 directories

## Module Dependencies

``` mermaid
graph LR
    components_confirm_modal[components.confirm_modal<br/>Confirm Modal]
    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]
    core_routing[core.routing<br/>routing]

    components_navbar --> core_html_ids
    core_layout --> core_html_ids
```

*2 cross-module dependencies detected*

## CLI Reference

No CLI commands found in this project.

## Module Overview

Detailed documentation for each module in the project:

### Confirm Modal (`confirm_modal.ipynb`)

> Generic destructive-confirm modal — Cancel-on-left, Confirm-on-right,
> with backdrop click-to-dismiss and defensive form-submission guards.
> Codifies **Convention V12 (Destructive-confirm composition)** as
> running code.

#### Import

``` python
from cjm_fasthtml_app_core.components.confirm_modal import (
    render_confirm_modal
)
```

#### Functions

``` python
def render_confirm_modal(
    modal_id:str, # HTML id for the <dialog> element
    body_id:str, # HTML id for the inner Div HTMX targets for message text
    title:str="Confirm Action?", # Modal title (rendered in <h3>)
    confirm_label:str="Confirm", # Right-button label
    confirm_icon:Optional[str]=None, # Optional Lucide icon name (e.g. "trash-2") prefixed to the confirm label
    cancel_label:str="Cancel", # Left-button label
    confirm_attrs:Optional[Dict[str, Any]]=None, # Caller-supplied attrs for the confirm button (hx_post / hx_vals / hx_swap / etc.)
) -> FT: # Dialog element implementing V12
    "Render a destructive-confirm modal (V12). Cancel-LEFT, Confirm-RIGHT, backdrop click-to-dismiss, defensive type=button. Body populated via HTMX swap into body_id."
```

### HTML IDs (`html_ids.ipynb`)

> Base HTML ID constants for FastHTML applications

#### Import

``` python
from cjm_fasthtml_app_core.core.html_ids import (
    AppHtmlIds
)
```

#### Classes

``` python
class AppHtmlIds:
    "Base HTML ID constants for FastHTML applications."
    
    def as_selector(
            id_str:str # The HTML ID to convert
        ) -> str: # CSS selector with # prefix
        "Convert an ID to a CSS selector format."
```

### HTMX Utilities (`htmx.ipynb`)

> Utilities for handling HTMX requests and responses

#### Import

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

#### Functions

``` python
def is_htmx_request(
    request # FastHTML request object
) -> bool: # True if request is from HTMX
    "Check if a request is an HTMX request."
```

``` python
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."
```

### Layout (`layout.ipynb`)

> Page layout utilities for wrapping content with common page structure

#### Import

``` python
from cjm_fasthtml_app_core.core.layout import (
    wrap_with_layout
)
```

#### Functions

``` python
def wrap_with_layout(
    content:FT, # The main content to display
    navbar:Optional[FT]=None, # Optional navbar component
    footer:Optional[FT]=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
) -> FT: # Main element with navbar and content
    "Wrap content with the full page layout including optional navbar and footer."
```

### Navbar (`navbar.ipynb`)

> Responsive navigation bar components with mobile support

#### Import

``` python
from cjm_fasthtml_app_core.components.navbar import (
    create_navbar
)
```

#### Functions

``` python
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
) -> FT: # Anchor element with HTMX attributes
    "Create a navigation link with HTMX attributes for SPA-like behavior. Internal helper for `create_navbar`."
```

``` python
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
) -> FT: # Navbar component
    "Create a responsive navigation bar with mobile dropdown menu."
```

### routing (`routing.ipynb`)

> Routing utilities for FastHTML applications

#### Import

``` python
from cjm_fasthtml_app_core.core.routing import (
    register_routes
)
```

#### Functions

``` python
def register_routes(
    app,  # FastHTML app instance
    *routers  # One or more APIRouter instances to register
) -> None:  # No return value
    "Register multiple APIRouter instances to a FastHTML app at once."
```
