cjm-fasthtml-viewport-fit 0.0.5

Reusable viewport height measurement utility for FastHTML applications that dynamically fits element height to remaining viewport space with resize and HTMX integration.

cjm-fasthtml-viewport-fit

Install

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

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

from cjm_fasthtml_viewport_fit.components import (
    render_viewport_fit_script
)

Functions

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

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

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

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

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

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

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

def generate_sibling_observer_js(
    config: ViewportFitConfig,  # Instance configuration
) -> str:  # JS for ResizeObserver on ancestor-level siblings (empty if disabled)
    "Generate ResizeObserver that walks the DOM tree and watches visible siblings at all ancestor levels."

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

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

from cjm_fasthtml_viewport_fit.models import (
    ViewportFitConfig
)

Classes

@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."