Merge branch 'p7-w2-parallax-aspect-ratio' into dev

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
+/// is left null, the window renders at 300px and the JS module recomputes height from the
-/// decodes — this can cause a one-time layout shift on first paint. Pass an explicit
+/// 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 },
+            new
-            _dotNetRef);
+            {
-    }
+                speed = ParallaxSpeed,
-
+                invertDirection = InvertDirection,
-    /// <summary>
+                heightFraction = WindowHeight == null ? (double?)WindowHeightFraction : null,
-    /// Invoked by the JS module once the background image decodes, when the consumer left
+                image1 = Image1
-    /// <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()
@@ -118,7 +114,6 @@ public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable
             }
         }
 
-        _dotNetRef?.Dispose();
         GC.SuppressFinalize(this);
     }
 }

DeepDrftShared.Client/Interop/parallax/parallax.ts

@@ -9,21 +9,17 @@
 interface RegisterOptions {
     speed: number;            // ParallaxSpeed, clamped [0,1]
     invertDirection: boolean; // selects the formula branch
-    onNaturalHeight?: boolean; // if true, report natural height via dotNetRef callback
+    heightFraction?: number;  // null/absent = use whatever CSS sets; present = auto-compute height
-    image1?: string;          // primary image URL, used by reportNaturalHeight probe
+    image1?: string;          // primary image URL, used by the auto-height probe
-}
-
-interface DotNetObjectReference {
-    invokeMethodAsync(methodName: string, ...args: unknown[]): Promise<unknown>;
 }
 
 interface Handle {
     element: HTMLElement;
     options: RegisterOptions;
-    observer: IntersectionObserver;
+    observer: IntersectionObserver;        // scroll gating
+    resizeObserver: ResizeObserver | null; // height recalc on resize
     scrollListener: (() => void) | null;
     rafId: number | null;
-    dotNetRef: DotNetObjectReference | null;
 }
 
 const handles = new Map<string, Handle>();
@@ -79,21 +75,36 @@ function detachScrollListener(handle: Handle): void {
     }
 }
 
-function reportNaturalHeight(handle: Handle): void {
+function setupAutoHeight(handle: Handle): void {
-    if (!handle.dotNetRef || !handle.options.image1) return;
+    if (!handle.options.heightFraction || !handle.options.image1) return;
+
+    const fraction = handle.options.heightFraction;
+    const element = handle.element;
+
+    const applyHeight = (naturalW: number, naturalH: number): void => {
+        const containerW = element.offsetWidth;
+        if (containerW === 0 || naturalW === 0) return;
+        const h = Math.round(containerW * (naturalH / naturalW) * fraction);
+        element.style.setProperty('--window-height', `${h}px`);
+    };
 
     const probe = new Image();
     probe.onload = (): void => {
-        handle.dotNetRef?.invokeMethodAsync('SetNaturalHeight', probe.naturalHeight);
+        const nw = probe.naturalWidth;
+        const nh = probe.naturalHeight;
+
+        applyHeight(nw, nh);
+
+        // Watch container width changes (orientation, responsive layout, etc.)
+        handle.resizeObserver = new ResizeObserver(() => {
+            applyHeight(nw, nh);
+        });
+        handle.resizeObserver.observe(element);
     };
     probe.src = handle.options.image1;
 }
 
-export function register(
+export function register(element: HTMLElement, options: RegisterOptions): string {
-    element: HTMLElement,
-    options: RegisterOptions,
-    dotNetRef?: DotNetObjectReference,
-): string {
     const id = `parallax-${++_handleCounter}`;
 
     const realObserver = new IntersectionObserver((entries) => {
@@ -110,18 +121,16 @@ export function register(
         element,
         options: { ...options, speed: clamp(options.speed, 0, 1) },
         observer: realObserver,
+        resizeObserver: null,
         scrollListener: null,
         rafId: null,
-        dotNetRef: dotNetRef ?? null,
     };
 
     handle.observer.observe(element);
 
     handles.set(id, handle);
 
-    if (options.onNaturalHeight) {
+    setupAutoHeight(handle);
-        reportNaturalHeight(handle);
-    }
 
     return id;
 }
@@ -132,6 +141,6 @@ export function unregister(handleId: string): void {
 
     detachScrollListener(handle);
     handle.observer.disconnect();
-    handle.dotNetRef = null;
+    handle.resizeObserver?.disconnect();
     handles.delete(handleId);
 }