Metadata-Version: 2.2
Name: cjm-fasthtml-viewport-fit
Version: 0.0.2
Summary: Reusable viewport height measurement utility for FastHTML applications that dynamically fits element height to remaining viewport space with resize and HTMX integration.
Home-page: https://github.com/cj-mills/cjm-fasthtml-viewport-fit
Author: Christian J. Mills
Author-email: 9126128+cj-mills@users.noreply.github.com
License: Apache-2.0
Keywords: nbdev jupyter notebook python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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
Requires-Dist: python-fasthtml
Provides-Extra: dev
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# cjm-fasthtml-viewport-fit


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

## Install

``` bash
pip install cjm_fasthtml_viewport_fit
```

## Project Structure

    nbs/
    ├── components.ipynb # FastHTML component for rendering the viewport-fit measurement script
    ├── js.ipynb         # JavaScript generation functions for viewport height measurement
    └── models.ipynb     # Configuration dataclass for viewport-fit measurement instances

Total: 3 notebooks

## Module Dependencies

``` mermaid
graph LR
    components[components<br/>components]
    js[js<br/>js]
    models[models<br/>models]

    components --> models
    components --> js
    js --> models
```

*3 cross-module dependencies detected*

## CLI Reference

No CLI commands found in this project.

## Module Overview

Detailed documentation for each module in the project:

### components (`components.ipynb`)

> FastHTML component for rendering the viewport-fit measurement script

#### Import

``` python
from cjm_fasthtml_viewport_fit.components import (
    render_viewport_fit_script
)
```

#### Functions

``` python
def render_viewport_fit_script(
    config: ViewportFitConfig,  # Instance configuration
) -> Any:  # Script element with complete viewport-fit JS
    "Render a Script element with the complete viewport-fit measurement JS."
```

### js (`js.ipynb`)

> JavaScript generation functions for viewport height measurement

#### Import

``` python
from cjm_fasthtml_viewport_fit.js import (
    generate_debug_helpers_js,
    generate_space_below_js,
    generate_calculate_height_js,
    generate_resize_handler_js,
    generate_htmx_settle_js,
    generate_sibling_observer_js,
    generate_init_js,
    generate_viewport_fit_js
)
```

#### Functions

``` python
def generate_debug_helpers_js(
    config: ViewportFitConfig,  # Instance configuration
) -> str:  # JS debug helper closures
    "Generate debug logging helpers conditional on a window flag."
```

``` python
def generate_space_below_js(
    config: ViewportFitConfig,  # Instance configuration
) -> str:  # JS function for DOM-walking space measurement
    "Generate JS that walks the DOM tree to measure space below a target element."
```

``` python
def generate_calculate_height_js(
    config: ViewportFitConfig,  # Instance configuration
) -> str:  # JS function for collapse-measure-apply height calculation
    "Generate JS that measures and applies viewport-fitted height to the target element."
```

``` python
def generate_resize_handler_js(
    config: ViewportFitConfig,  # Instance configuration
) -> str:  # JS for debounced resize listener with cleanup
    "Generate debounced window resize handler with HTMX-safe cleanup."
```

``` python
def generate_htmx_settle_js(
    config: ViewportFitConfig,  # Instance configuration
) -> str:  # JS for HTMX afterSettle recalculation (empty if disabled)
    "Generate HTMX afterSettle handler for recalculation on SPA navigation."
```

``` python
def generate_sibling_observer_js(
    config: ViewportFitConfig,  # Instance configuration
) -> str:  # JS for ResizeObserver on target siblings (empty if disabled)
    "Generate ResizeObserver that watches target's siblings for size changes."
```

``` python
def generate_init_js(
    config: ViewportFitConfig,  # Instance configuration
) -> str:  # JS initialization block
    "Generate JS for initial measurement on script execution."
```

``` python
def generate_viewport_fit_js(
    config: ViewportFitConfig,  # Instance configuration
) -> str:  # Complete JS code as a self-contained IIFE
    "Generate the complete viewport-fit JS as a self-contained IIFE."
```

### models (`models.ipynb`)

> Configuration dataclass for viewport-fit measurement instances

#### Import

``` python
from cjm_fasthtml_viewport_fit.models import (
    ViewportFitConfig
)
```

#### Classes

``` python
@dataclass
class ViewportFitConfig:
    "Configuration for a viewport-fit measurement instance."
    
    namespace: str  # Unique prefix for JS isolation (e.g., "source_select")
    target_id: str  # HTML ID of the element to fit to viewport height
    inner_id: str = ''  # Optional child element that also receives the calculated height
    min_height: int = 200  # Minimum height in pixels
    debounce_ms: int = 100  # Resize debounce delay in milliseconds
    scroll_to_top: bool = True  # Scroll to (0,0) before measuring (for HTMX SPAs)
    enable_htmx_settle: bool = True  # Remeasure on htmx:afterSettle events
    observe_siblings: bool = True  # Watch sibling elements for size changes via ResizeObserver
    resize_callback: str = ''  # Optional JS expression called after resize
    debug: bool = False  # Enable debug console logging by default
    
    def ns(self) -> str:  # Capitalized namespace for JS function names
            """Capitalized namespace for JS function names."""
            return "".join(p.capitalize() for p in self.namespace.split("_"))
    
        @property
        def handler_key(self) -> str:  # Window-level key for resize handler cleanup
        "Capitalized namespace for JS function names."
    
    def handler_key(self) -> str:  # Window-level key for resize handler cleanup
            """Window-level key for resize handler cleanup."""
            return f"_vfResizeHandler_{self.namespace.replace('-', '_')}"
    
        @property
        def settle_handler_key(self) -> str:  # Window-level key for HTMX settle handler
        "Window-level key for resize handler cleanup."
    
    def settle_handler_key(self) -> str:  # Window-level key for HTMX settle handler
            """Window-level key for HTMX settle handler cleanup."""
            return f"_vfSettleHandler_{self.namespace.replace('-', '_')}"
    
        @property
        def observer_key(self) -> str:  # Window-level key for ResizeObserver cleanup
        "Window-level key for HTMX settle handler cleanup."
    
    def observer_key(self) -> str:  # Window-level key for ResizeObserver cleanup
            """Window-level key for sibling ResizeObserver cleanup."""
            return f"_vfSiblingObserver_{self.namespace.replace('-', '_')}"
    
        @property
        def debug_flag(self) -> str:  # JS window debug flag name
        "Window-level key for sibling ResizeObserver cleanup."
    
    def debug_flag(self) -> str:  # JS window debug flag name
            """Window-level debug flag name."""
            return f"viewportFitDebug_{self.namespace.replace('-', '_')}"
    
        @property
        def log_prefix(self) -> str:  # Console log prefix string
        "Window-level debug flag name."
    
    def log_prefix(self) -> str:  # Console log prefix string
            """Console log prefix string."""
            return f"vf:{self.namespace}"
    
        @property
        def recalc_fn(self) -> str:  # Global function name for manual recalculation
        "Console log prefix string."
    
    def recalc_fn(self) -> str:  # Global function name for manual recalculation
        "Global function name for manual recalculation."
```
