using Microsoft.AspNetCore.Components; using Microsoft.JSInterop; namespace DeepDrftShared.Client.Components; /// /// Scroll-driven parallax image window. As the component scrolls up through the viewport, /// the image pans through the window faster than the page scrolls. An optional second image /// crossfades in on hover (pure CSS). A flag breaks the container out /// of parent padding to span the viewport. /// /// /// Progressive enhancement: renders a static framed image at SSR; the parallax attaches after /// interactive boot via OnAfterRenderAsync(firstRender). When /// is left null, the window renders at 300px and the JS module recomputes height from the /// container width and image aspect ratio (see ), tracking /// container resizes — this may cause a layout shift on first paint or on orientation change. Pass an explicit /// for above-the-fold hero usage to avoid the shift. /// When and are provided, height is set /// via CSS aspect-ratio at render time — no layout shift occurs on any render mode. /// public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable { [Inject] private IJSRuntime JS { get; set; } = default!; /// Primary image URL, shown at rest. [Parameter, EditorRequired] public string Image1 { get; set; } = default!; /// Optional hover image (assumed same dimensions as ). [Parameter] public string? Image2 { get; set; } /// Accessible name for . When null, the window is decorative. [Parameter] public string? Alt1 { get; set; } /// Accessible name for (only relevant if it adds semantic meaning). [Parameter] public string? Alt2 { get; set; } /// CSS height of the parallax window. When null, renders at 300px then recomputes from container width, image aspect ratio, and . [Parameter] public string? WindowHeight { get; set; } /// /// Natural pixel width of . When provided together with /// , the window height is set via CSS aspect-ratio /// at render time — eliminating the SSR/hydration layout shift that occurs when /// dimensions are unknown. Has no effect when is set. /// [Parameter] public int? NaturalWidth { get; set; } /// /// Natural pixel height of . See . /// [Parameter] public int? NaturalHeight { get; set; } /// /// Fraction of the aspect-ratio-correct image height to use as the parallax window height. /// Only active when is null. /// E.g. 0.5 (default) = window is half the height the image would be if displayed at full container width. /// Recalculates on container resize (orientation change, responsive layout shift). /// [Parameter] public double WindowHeightFraction { get; set; } = 0.5; /// background-size width. [Parameter] public string ImageWidth { get; set; } = "auto"; /// background-size height. [Parameter] public string ImageHeight { get; set; } = "auto"; /// When true, stretches the container to 100vw via a negative-margin breakout. [Parameter] public bool FullWidth { get; set; } /// Speed multiplier, clamped to [0,1] in the JS module. [Parameter] public double ParallaxSpeed { get; set; } = 0.5; /// When false: top-on-entry to bottom-at-top. When true: inverted. [Parameter] public bool InvertDirection { get; set; } /// Extra CSS classes on the outer element. [Parameter] public string? Class { get; set; } protected ElementReference WindowRef; protected string WindowStyle { get; private set; } = "--window-height: 300px; --parallax-pos: 0%;"; private bool AspectRatioMode => WindowHeight is null && NaturalWidth is > 0 && NaturalHeight is > 0; private IJSObjectReference? _module; private string? _handle; protected override void OnParametersSet() { if (WindowHeight != null) { WindowStyle = $"--window-height: {WindowHeight}; --parallax-pos: 0%;"; } else if (AspectRatioMode) { // Aspect-ratio mode: height: auto lets aspect-ratio take effect; // the inline height: auto overrides the CSS --window-height rule. // aspect-ratio: W / (H * fraction) → window is WindowHeightFraction // of the image's full display height at container width. var h = Math.Max(1, (int)Math.Round(NaturalHeight!.Value * WindowHeightFraction)); WindowStyle = $"height: auto; aspect-ratio: {NaturalWidth!.Value} / {h}; --parallax-pos: 0%;"; } else { WindowStyle = "--window-height: 300px; --parallax-pos: 0%;"; } } protected override async Task OnAfterRenderAsync(bool firstRender) { if (!firstRender) { return; } _module = await JS.InvokeAsync( "import", "./_content/DeepDrftShared.Client/js/parallax/parallax.js"); _handle = await _module.InvokeAsync( "register", WindowRef, new { speed = ParallaxSpeed, invertDirection = InvertDirection, // heightFraction is null in explicit-height and aspect-ratio modes; // JS auto-height only runs in the fallback (no dimensions provided). heightFraction = (WindowHeight == null && !AspectRatioMode) ? (double?)WindowHeightFraction : null, image1 = Image1 }); } public async ValueTask DisposeAsync() { if (_module != null) { try { if (_handle != null) { await _module.InvokeVoidAsync("unregister", _handle); } await _module.DisposeAsync(); } catch (JSDisconnectedException) { // Circuit already torn down (e.g. browser navigated away) — nothing to clean up. } } GC.SuppressFinalize(this); } }