From c46c3a2f9c8b66ac7687457a0d82a123b22021e4 Mon Sep 17 00:00:00 2001 From: daniel-c-harvey Date: Thu, 11 Jun 2026 10:23:25 -0400 Subject: [PATCH] feat(parallax): aspect-ratio-aware auto height via WindowHeightFraction + ResizeObserver, drop DotNetObjectReference round-trip --- .../Components/ParallaxImage.razor.cs | 43 +++++++--------- .../Interop/parallax/parallax.ts | 51 +++++++++++-------- 2 files changed, 49 insertions(+), 45 deletions(-) diff --git a/DeepDrftShared.Client/Components/ParallaxImage.razor.cs b/DeepDrftShared.Client/Components/ParallaxImage.razor.cs index 2ced165..76b9d11 100644 --- a/DeepDrftShared.Client/Components/ParallaxImage.razor.cs +++ b/DeepDrftShared.Client/Components/ParallaxImage.razor.cs @@ -12,8 +12,9 @@ namespace DeepDrftShared.Client.Components; /// /// 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 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 ), 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. /// public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable @@ -32,9 +33,17 @@ public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable /// 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 and recomputes to naturalHeight/2. + /// 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; } + /// + /// 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"; @@ -57,7 +66,6 @@ public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable protected string WindowHeightValue { get; private set; } = "300px"; private IJSObjectReference? _module; - private DotNetObjectReference? _dotNetRef; private string? _handle; protected override void OnParametersSet() @@ -75,28 +83,16 @@ public abstract class ParallaxImageBase : ComponentBase, IAsyncDisposable _module = await JS.InvokeAsync( "import", "./_content/DeepDrftShared.Client/js/parallax/parallax.js"); - var reportNaturalHeight = WindowHeight == null; - if (reportNaturalHeight) - { - _dotNetRef = DotNetObjectReference.Create(this); - } - _handle = await _module.InvokeAsync( "register", WindowRef, - new { speed = ParallaxSpeed, invertDirection = InvertDirection, onNaturalHeight = reportNaturalHeight, image1 = Image1 }, - _dotNetRef); - } - - /// - /// Invoked by the JS module once the background image decodes, when the consumer left - /// null. Sets the window height to half the image's natural height. - /// - [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); } } diff --git a/DeepDrftShared.Client/Interop/parallax/parallax.ts b/DeepDrftShared.Client/Interop/parallax/parallax.ts index 2cb06af..5a708d1 100644 --- a/DeepDrftShared.Client/Interop/parallax/parallax.ts +++ b/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 - image1?: string; // primary image URL, used by reportNaturalHeight probe -} - -interface DotNetObjectReference { - invokeMethodAsync(methodName: string, ...args: unknown[]): Promise; + heightFraction?: number; // null/absent = use whatever CSS sets; present = auto-compute height + image1?: string; // primary image URL, used by the auto-height probe } 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(); @@ -79,21 +75,36 @@ function detachScrollListener(handle: Handle): void { } } -function reportNaturalHeight(handle: Handle): void { - if (!handle.dotNetRef || !handle.options.image1) return; +function setupAutoHeight(handle: Handle): void { + 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( - element: HTMLElement, - options: RegisterOptions, - dotNetRef?: DotNetObjectReference, -): string { +export function register(element: HTMLElement, options: RegisterOptions): 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) { - reportNaturalHeight(handle); - } + setupAutoHeight(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); }