feat: add ParallaxImage scroll-parallax component to DeepDrftShared.Client
This commit is contained in:
daniel-c-harvey
@@ -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;
|
||||
}
|
||||
}
|
||||
@@ -19,4 +19,28 @@
|
||||
<ProjectReference Include="..\DeepDrftModels\DeepDrftModels.csproj" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<PackageReference Include="Microsoft.TypeScript.MSBuild" Version="5.9.3">
|
||||
<PrivateAssets>all</PrivateAssets>
|
||||
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
|
||||
</PackageReference>
|
||||
<Folder Include="wwwroot\js\" />
|
||||
</ItemGroup>
|
||||
|
||||
<!-- TypeScript configuration following Microsoft recommendations -->
|
||||
<PropertyGroup>
|
||||
<TypeScriptCompileOnSaveEnabled>false</TypeScriptCompileOnSaveEnabled>
|
||||
<TypeScriptToolsVersion>Latest</TypeScriptToolsVersion>
|
||||
<TypeScriptESModuleInterop>true</TypeScriptESModuleInterop>
|
||||
<TypeScriptAllowSyntheticDefaultImports>true</TypeScriptAllowSyntheticDefaultImports>
|
||||
</PropertyGroup>
|
||||
|
||||
<!-- Prevent tsconfig.json from being copied to output directories -->
|
||||
<ItemGroup>
|
||||
<None Update="tsconfig.json">
|
||||
<CopyToOutputDirectory>Never</CopyToOutputDirectory>
|
||||
<CopyToPublishDirectory>Never</CopyToPublishDirectory>
|
||||
</None>
|
||||
</ItemGroup>
|
||||
|
||||
</Project>
|
||||
|
||||
@@ -0,0 +1,137 @@
|
||||
/**
|
||||
* parallax - scroll-driven background-position panning for ParallaxImage.
|
||||
*
|
||||
* Single Responsibility: own the parallax math and scroll/observer lifecycle.
|
||||
* Blazor owns the component lifecycle and calls register/unregister; this module
|
||||
* writes only the `--parallax-pos` CSS custom property — never concrete style.
|
||||
*/
|
||||
|
||||
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<unknown>;
|
||||
}
|
||||
|
||||
interface Handle {
|
||||
element: HTMLElement;
|
||||
options: RegisterOptions;
|
||||
observer: IntersectionObserver;
|
||||
scrollListener: (() => void) | null;
|
||||
rafId: number | null;
|
||||
dotNetRef: DotNetObjectReference | null;
|
||||
}
|
||||
|
||||
const handles = new Map<string, Handle>();
|
||||
|
||||
let _handleCounter = 0;
|
||||
|
||||
const reducedMotion = (): boolean =>
|
||||
window.matchMedia('(prefers-reduced-motion: reduce)').matches;
|
||||
|
||||
function clamp(value: number, min: number, max: number): number {
|
||||
return Math.max(min, Math.min(max, value));
|
||||
}
|
||||
|
||||
function applyParallax(handle: Handle): void {
|
||||
const { element, options } = handle;
|
||||
const rect = element.getBoundingClientRect();
|
||||
const viewportH = window.innerHeight;
|
||||
|
||||
let progress = options.invertDirection
|
||||
? rect.top / viewportH
|
||||
: 1 - rect.top / viewportH;
|
||||
progress = clamp(progress, 0, 1);
|
||||
|
||||
const pos = progress * clamp(options.speed, 0, 1) * 100;
|
||||
element.style.setProperty('--parallax-pos', `${pos}%`);
|
||||
}
|
||||
|
||||
function attachScrollListener(handle: Handle): void {
|
||||
if (handle.scrollListener || reducedMotion()) return;
|
||||
|
||||
const listener = (): void => {
|
||||
if (handle.rafId !== null) return;
|
||||
handle.rafId = requestAnimationFrame(() => {
|
||||
handle.rafId = null;
|
||||
applyParallax(handle);
|
||||
});
|
||||
};
|
||||
|
||||
handle.scrollListener = listener;
|
||||
window.addEventListener('scroll', listener, { passive: true });
|
||||
// Prime position immediately so entry isn't a frame behind the first scroll.
|
||||
applyParallax(handle);
|
||||
}
|
||||
|
||||
function detachScrollListener(handle: Handle): void {
|
||||
if (handle.scrollListener) {
|
||||
window.removeEventListener('scroll', handle.scrollListener);
|
||||
handle.scrollListener = null;
|
||||
}
|
||||
if (handle.rafId !== null) {
|
||||
cancelAnimationFrame(handle.rafId);
|
||||
handle.rafId = null;
|
||||
}
|
||||
}
|
||||
|
||||
function reportNaturalHeight(handle: Handle): void {
|
||||
if (!handle.dotNetRef || !handle.options.image1) return;
|
||||
|
||||
const probe = new Image();
|
||||
probe.onload = (): void => {
|
||||
handle.dotNetRef?.invokeMethodAsync('SetNaturalHeight', probe.naturalHeight);
|
||||
};
|
||||
probe.src = handle.options.image1;
|
||||
}
|
||||
|
||||
export function register(
|
||||
element: HTMLElement,
|
||||
options: RegisterOptions,
|
||||
dotNetRef?: DotNetObjectReference,
|
||||
): string {
|
||||
const id = `parallax-${++_handleCounter}`;
|
||||
|
||||
const realObserver = new IntersectionObserver((entries) => {
|
||||
for (const entry of entries) {
|
||||
if (entry.isIntersecting) {
|
||||
attachScrollListener(handle);
|
||||
} else {
|
||||
detachScrollListener(handle);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
const handle: Handle = {
|
||||
element,
|
||||
options: { ...options, speed: clamp(options.speed, 0, 1) },
|
||||
observer: realObserver,
|
||||
scrollListener: null,
|
||||
rafId: null,
|
||||
dotNetRef: dotNetRef ?? null,
|
||||
};
|
||||
|
||||
handle.observer.observe(element);
|
||||
|
||||
handles.set(id, handle);
|
||||
|
||||
if (options.onNaturalHeight) {
|
||||
reportNaturalHeight(handle);
|
||||
}
|
||||
|
||||
return id;
|
||||
}
|
||||
|
||||
export function unregister(handleId: string): void {
|
||||
const handle = handles.get(handleId);
|
||||
if (!handle) return;
|
||||
|
||||
detachScrollListener(handle);
|
||||
handle.observer.disconnect();
|
||||
handle.dotNetRef = null;
|
||||
handles.delete(handleId);
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ESNext",
|
||||
"module": "ESNext",
|
||||
"esModuleInterop": true,
|
||||
"allowSyntheticDefaultImports": true,
|
||||
"forceConsistentCasingInFileNames": true,
|
||||
"strict": true,
|
||||
"skipLibCheck": true,
|
||||
"noEmitOnError": true,
|
||||
"removeComments": false,
|
||||
"sourceMap": true,
|
||||
"rootDir": "Interop",
|
||||
"outDir": "wwwroot/js",
|
||||
"sourceRoot": "/Interop",
|
||||
"mapRoot": "/js"
|
||||
},
|
||||
"include": [
|
||||
"Interop/**/*.ts"
|
||||
],
|
||||
"exclude": [
|
||||
"node_modules",
|
||||
"bin/**/*",
|
||||
"obj/**/*",
|
||||
"publish/**/*"
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user