feat(parallax): aspect-ratio-aware auto height via WindowHeightFraction + ResizeObserver, drop DotNetObjectReference round-trip

DeepDrftShared.Client/Components/ParallaxImage.razor.cs

@@ -12,8 +12,9 @@ namespace DeepDrftShared.Client.Components;
 /// <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
+/// is left null, the window renders at 300px and the JS module recomputes height from the
+/// container width and image aspect ratio (see <see cref="WindowHeightFraction"/>), tracking
+/// container resizes — this may cause a layout shift on first paint or on orientation change. Pass an explicit
 /// <see cref="WindowHeight"/> for above-the-fold hero usage to avoid the shift.
 /// </remarks>
 public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable
@@ -32,9 +33,17 @@ public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable
     /// <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>
+    /// <summary>CSS height of the parallax window. When null, renders at 300px then recomputes from container width, image aspect ratio, and <see cref="WindowHeightFraction"/>.</summary>
     [Parameter] public string? WindowHeight { get; set; }
 
+    /// <summary>
+    /// Fraction of the aspect-ratio-correct image height to use as the parallax window height.
+    /// Only active when <see cref="WindowHeight"/> 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).
+    /// </summary>
+    [Parameter] public double WindowHeightFraction { get; set; } = 0.5;
+
     /// <summary><c>background-size</c> width.</summary>
     [Parameter] public string ImageWidth { get; set; } = "auto";
 
@@ -57,7 +66,6 @@ public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable
     protected string WindowHeightValue { get; private set; } = "300px";
 
     private IJSObjectReference? _module;
-    private DotNetObjectReference<ParallaxImageBase>? _dotNetRef;
     private string? _handle;
 
     protected override void OnParametersSet()
@@ -75,28 +83,16 @@ public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable
         _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();
+            new
+            {
+                speed = ParallaxSpeed,
+                invertDirection = InvertDirection,
+                heightFraction = WindowHeight == null ? (double?)WindowHeightFraction : null,
+                image1 = Image1
+            });
     }
 
     public async ValueTask DisposeAsync()
@@ -118,7 +114,6 @@ public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable
             }
         }
 
-        _dotNetRef?.Dispose();
         GC.SuppressFinalize(this);
     }
 }