feat: add ParallaxImage scroll-parallax component to DeepDrftShared.Client

2026-06-11 09:23:34 -04:00
parent 81b8796ba5
commit 4d9505c341
6 changed files with 380 additions and 0 deletions
@@ -0,0 +1,20 @@
+@inherits ParallaxImageBase
+
+<div @ref="WindowRef"
+     class="parallax-window @(FullWidth ? "full-width" : "") @Class"
+     role="@(Alt1 != null ? "img" : "presentation")"
+     aria-label="@Alt1"
+     aria-hidden="@(Alt1 == null ? "true" : null)"
+     style="--window-height: @WindowHeightValue; --parallax-pos: 0%;">
+
+    <div class="layer layer-1"
+         style="background-image: url('@Image1'); background-size: @ImageWidth @ImageHeight;">
+    </div>
+
+    @if (Image2 != null)
+    {
+        <div class="layer layer-2"
+             style="background-image: url('@Image2'); background-size: @ImageWidth @ImageHeight;">
+        </div>
+    }
+</div>
@@ -0,0 +1,124 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.JSInterop;
+
+namespace DeepDrftShared.Client.Components;
+
+/// <summary>
+/// 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 <see cref="FullWidth"/> flag breaks the container out
+/// of parent padding to span the viewport.
+/// </summary>
+/// <remarks>
+/// Progressive enhancement: renders a static framed image at SSR; the parallax attaches after
+/// interactive boot via <c>OnAfterRenderAsync(firstRender)</c>. When <see cref="WindowHeight"/>
+/// is left null, the window renders at 300px and recomputes to naturalHeight/2 once the image
+/// decodes — this can cause a one-time layout shift on first paint. Pass an explicit
+/// <see cref="WindowHeight"/> for above-the-fold hero usage to avoid the shift.
+/// </remarks>
+public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable
+{
+    [Inject] private IJSRuntime JS { get; set; } = default!;
+
+    /// <summary>Primary image URL, shown at rest.</summary>
+    [Parameter, EditorRequired] public string Image1 { get; set; } = default!;
+
+    /// <summary>Optional hover image (assumed same dimensions as <see cref="Image1"/>).</summary>
+    [Parameter] public string? Image2 { get; set; }
+
+    /// <summary>Accessible name for <see cref="Image1"/>. When null, the window is decorative.</summary>
+    [Parameter] public string? Alt1 { get; set; }
+
+    /// <summary>Accessible name for <see cref="Image2"/> (only relevant if it adds semantic meaning).</summary>
+    [Parameter] public string? Alt2 { get; set; }
+
+    /// <summary>CSS height of the parallax window. When null, renders at 300px and recomputes to naturalHeight/2.</summary>
+    [Parameter] public string? WindowHeight { get; set; }
+
+    /// <summary><c>background-size</c> width.</summary>
+    [Parameter] public string ImageWidth { get; set; } = "auto";
+
+    /// <summary><c>background-size</c> height.</summary>
+    [Parameter] public string ImageHeight { get; set; } = "auto";
+
+    /// <summary>When true, stretches the container to 100vw via a negative-margin breakout.</summary>
+    [Parameter] public bool FullWidth { get; set; }
+
+    /// <summary>Speed multiplier, clamped to [0,1] in the JS module.</summary>
+    [Parameter] public double ParallaxSpeed { get; set; } = 0.5;
+
+    /// <summary>When false: top-on-entry to bottom-at-top. When true: inverted.</summary>
+    [Parameter] public bool InvertDirection { get; set; }
+
+    /// <summary>Extra CSS classes on the outer element.</summary>
+    [Parameter] public string? Class { get; set; }
+
+    protected ElementReference WindowRef;
+    protected string WindowHeightValue { get; private set; } = "300px";
+
+    private IJSObjectReference? _module;
+    private DotNetObjectReference<ParallaxImageBase>? _dotNetRef;
+    private string? _handle;
+
+    protected override void OnParametersSet()
+    {
+        WindowHeightValue = WindowHeight ?? "300px";
+    }
+
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        if (!firstRender)
+        {
+            return;
+        }
+
+        _module = await JS.InvokeAsync<IJSObjectReference>(
+            "import", "./_content/DeepDrftShared.Client/js/parallax/parallax.js");
+
+        var reportNaturalHeight = WindowHeight == null;
+        if (reportNaturalHeight)
+        {
+            _dotNetRef = DotNetObjectReference.Create(this);
+        }
+
+        _handle = await _module.InvokeAsync<string>(
+            "register",
+            WindowRef,
+            new { speed = ParallaxSpeed, invertDirection = InvertDirection, onNaturalHeight = reportNaturalHeight, image1 = Image1 },
+            _dotNetRef);
+    }
+
+    /// <summary>
+    /// Invoked by the JS module once the background image decodes, when the consumer left
+    /// <see cref="WindowHeight"/> null. Sets the window height to half the image's natural height.
+    /// </summary>
+    [JSInvokable]
+    public void SetNaturalHeight(double naturalHeightPx)
+    {
+        WindowHeightValue = $"{(int)(naturalHeightPx / 2)}px";
+        StateHasChanged();
+    }
+
+    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.
+            }
+        }
+
+        _dotNetRef?.Dispose();
+        GC.SuppressFinalize(this);
+    }
+}
@@ -0,0 +1,48 @@
+.parallax-window {
+    position: relative;
+    overflow: hidden;
+    height: var(--window-height, 300px);
+    width: 100%;
+}
+
+.parallax-window.full-width {
+    width: 100vw;
+    position: relative;
+    left: 50%;
+    right: 50%;
+    margin-left: -50vw;
+    margin-right: -50vw;
+}
+
+.layer {
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    background-repeat: no-repeat;
+    background-position: 50% var(--parallax-pos, 50%);
+}
+
+.layer-1 {
+    opacity: 1;
+}
+
+.layer-2 {
+    opacity: 0;
+    transition: opacity 400ms ease;
+}
+
+.parallax-window:hover .layer-2 {
+    opacity: 1;
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .parallax-window {
+        --parallax-pos: 0%;
+    }
+
+    .layer-2 {
+        transition-duration: 0ms;
+    }
+}