feat: add ParallaxImage scroll-parallax component to DeepDrftShared.Client

DeepDrftShared.Client/Components/ParallaxImage.razor

@@ -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>

DeepDrftShared.Client/Components/ParallaxImage.razor.cs

@@ -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);
+    }
+}

DeepDrftShared.Client/Components/ParallaxImage.razor.css

@@ -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;
+    }
+}

DeepDrftShared.Client/DeepDrftShared.Client.csproj

@@ -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>

DeepDrftShared.Client/Interop/parallax/parallax.ts

@@ -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);
+}

DeepDrftShared.Client/tsconfig.json

@@ -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/**/*"
+  ]
+}