Merge branch 'p7-w3-parallax-ssr' into dev

DeepDrftShared.Client/Components/ParallaxImage.razor

@@ -5,7 +5,7 @@
      role="@(Alt1 != null ? "img" : "presentation")"
      aria-label="@Alt1"
      aria-hidden="@(Alt1 == null ? "true" : null)"
-     style="--window-height: @WindowHeightValue; --parallax-pos: 0%;">
+     style="@WindowStyle">
 
     <div class="layer layer-1"
          style="background-image: url('@Image1'); background-size: @ImageWidth @ImageHeight;">

DeepDrftShared.Client/Components/ParallaxImage.razor.cs

@@ -16,6 +16,8 @@ namespace DeepDrftShared.Client.Components;
 /// 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.
+/// When <see cref="NaturalWidth"/> and <see cref="NaturalHeight"/> are provided, height is set
+/// via CSS <c>aspect-ratio</c> at render time — no layout shift occurs on any render mode.
 /// </remarks>
 public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable
 {
@@ -36,6 +38,19 @@ public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable
     /// <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>
+    /// Natural pixel width of <see cref="Image1"/>. When provided together with
+    /// <see cref="NaturalHeight"/>, the window height is set via CSS <c>aspect-ratio</c>
+    /// at render time — eliminating the SSR/hydration layout shift that occurs when
+    /// dimensions are unknown. Has no effect when <see cref="WindowHeight"/> is set.
+    /// </summary>
+    [Parameter] public int? NaturalWidth { get; set; }
+
+    /// <summary>
+    /// Natural pixel height of <see cref="Image1"/>. See <see cref="NaturalWidth"/>.
+    /// </summary>
+    [Parameter] public int? NaturalHeight { 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.
@@ -63,14 +78,33 @@ public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable
     [Parameter] public string? Class { get; set; }
 
     protected ElementReference WindowRef;
-    protected string WindowHeightValue { get; private set; } = "300px";
+    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()
     {
-        WindowHeightValue = WindowHeight ?? "300px";
+        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)
@@ -90,7 +124,11 @@ public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable
             {
                 speed = ParallaxSpeed,
                 invertDirection = InvertDirection,
-                heightFraction = WindowHeight == null ? (double?)WindowHeightFraction : null,
+                // 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
             });
     }