Refactor scroll-based components: implement debouncing for scroll event handlers in logo-scroll-rotate, scroll-rotate binder, and dfw-scroll-visibility components to improve performance. Enhance dfw-background-gears component with resizing transitions and update dfw-contact-map to utilize a new scroll positioning utility for better user experience.

Author: JumpLink

src/ts/binders/scroll-rotate.binder.ts

@@ -1,4 +1,5 @@
 import { Binder } from "@ribajs/core";
+import { debounceF } from "@ribajs/utils/src/control.js";
 
 /**
  * Rotates an element based on the window scroll position.
@@ -10,9 +11,9 @@ export class ScrollRotateBinder extends Binder<number, HTMLElement> {
 
   private scrollHandler: (() => void) | null = null;
   private speed = 0.15;
-  private animationFrameId: number | null = null;
 
   private applyRotation() {
+    if (!this.el.isConnected) return;
     const scrollY = window.scrollY || window.pageYOffset;
     const degrees = scrollY * this.speed;
     this.el.style.transform = `rotate(${degrees}deg)`;
@@ -26,15 +27,8 @@ export class ScrollRotateBinder extends Binder<number, HTMLElement> {
   }
 
   bind(el: HTMLElement) {
-    this.scrollHandler = () => {
-      if (this.animationFrameId) {
-        cancelAnimationFrame(this.animationFrameId);
-      }
-      this.animationFrameId = requestAnimationFrame(() => {
-        this.applyRotation();
-        this.animationFrameId = null;
-      });
-    };
+    const debouncedApply = debounceF(() => this.applyRotation());
+    this.scrollHandler = () => debouncedApply();
 
     window.addEventListener('scroll', this.scrollHandler, { passive: true });
 
@@ -47,9 +41,5 @@ export class ScrollRotateBinder extends Binder<number, HTMLElement> {
       window.removeEventListener('scroll', this.scrollHandler);
       this.scrollHandler = null;
     }
-    if (this.animationFrameId) {
-      cancelAnimationFrame(this.animationFrameId);
-      this.animationFrameId = null;
-    }
   }
 }

src/ts/components/dfw-background-gears/dfw-background-gears.component.scss

@@ -1,3 +1,9 @@
 dfw-background-gears {
   display: block;
+  transition: opacity 0.15s ease-out;
+
+  &.dfw-background-gears--resizing {
+    opacity: 0;
+    pointer-events: none;
+  }
 }

src/ts/components/dfw-background-gears/dfw-background-gears.component.ts

@@ -1,5 +1,6 @@
 import { Component } from "@ribajs/core";
 import { EventDispatcher } from "@ribajs/events";
+import { debounceCb, debounceF } from "@ribajs/utils/src/control.js";
 import { hasChildNodesTrim } from "@ribajs/utils/src/dom.js";
 
 import templateHtml from "./dfw-background-gears.component.html?raw";
@@ -34,13 +35,16 @@ export class DfwBackgroundGearsComponent extends Component {
 
   protected autobind = true;
 
-  private shineRafId: number | null = null;
   private resizeObserver: ResizeObserver | null = null;
+  private static readonly RESIZE_DEBOUNCE_MS = 450;
   private routerUnsubscribe: (() => void) | null = null;
-  private readonly boundUpdateShineFromScroll = () => this.updateShineFromScroll();
+  private debouncedShineFromScroll!: () => void;
+  private debouncedShineFromPointer!: (e: MouseEvent) => void;
+  private readonly boundUpdateShineFromScroll = () => this.debouncedShineFromScroll();
   private readonly boundUpdateShineFromPointer = (e: MouseEvent) =>
-    this.updateShineFromPointer(e);
-  private readonly boundUpdateHeightToPage = () => this.updateHeightToPage();
+    this.debouncedShineFromPointer(e);
+  private readonly boundOnResize = () => this.onResize();
+  private debouncedResizeDone!: () => void;
   private readonly boundOnTransitionCompleted = () => this.onTransitionCompleted();
   private readonly boundOnInitStateChange = (
     _viewId: string,
@@ -59,15 +63,30 @@ export class DfwBackgroundGearsComponent extends Component {
     { src: gear2Url, speed: 0.32, class: "bg-gear--5", maskStyle: { "--gear-mask": `url("${gear2Url}")` } },
   ] as const;
 
-  /** Set gears container height to full page height so gear positions (top: X%) distribute along the page. */
+  /** Hide gears and schedule debounced repositioning when viewport size changes. */
+  private onResize(): void {
+    (this as unknown as HTMLElement).classList.add("dfw-background-gears--resizing");
+    this.debouncedResizeDone();
+  }
+
+  /** Set gears container height to content height so gear positions (top: X%) distribute along the page.
+   * Height is read while gears container is collapsed to avoid the gears contributing to document height. */
   private updateHeightToPage(): void {
+    const container = this.parentElement as HTMLElement | null;
+    const self = this as unknown as HTMLElement;
+
+    if (container?.classList.contains("background-gears")) {
+      container.style.height = "0";
+    }
+    self.style.height = "0";
+
     const h = document.documentElement.scrollHeight;
     const px = `${h}px`;
-    const container = this.parentElement;
+
     if (container?.classList.contains("background-gears")) {
-      (container as HTMLElement).style.height = px;
+      container.style.height = px;
     }
-    (this as unknown as HTMLElement).style.height = px;
+    self.style.height = px;
   }
 
   /** Collapse gears container and remove gear nodes so document height is not preserved on page change. */
@@ -130,39 +149,44 @@ export class DfwBackgroundGearsComponent extends Component {
     document.documentElement.style.setProperty("--shine-y", y);
   }
 
-  private updateShineFromScroll(): void {
-    if (this.shineRafId !== null) return;
-    this.shineRafId = requestAnimationFrame(() => {
-      this.shineRafId = null;
-      const scrollY = window.scrollY ?? document.documentElement.scrollTop;
-      const innerHeight = window.innerHeight;
-      const scrollHeight = document.documentElement.scrollHeight;
-      const maxScroll = Math.max(0, scrollHeight - innerHeight);
-      const progress = maxScroll > 0 ? scrollY / maxScroll : 0;
-      const cycles = 3;
-      const phase = (progress * cycles) % 1;
-      const yPercent =
-        phase <= 0.5 ? phase * 200 : (1 - phase) * 200;
-      this.setShine(this.shineX, `${Math.min(100, Math.max(0, yPercent))}%`);
-    });
+  private doUpdateShineFromScroll(): void {
+    if (!this.isConnected) return;
+    const scrollY = window.scrollY ?? document.documentElement.scrollTop;
+    const innerHeight = window.innerHeight;
+    const scrollHeight = document.documentElement.scrollHeight;
+    const maxScroll = Math.max(0, scrollHeight - innerHeight);
+    const progress = maxScroll > 0 ? scrollY / maxScroll : 0;
+    const cycles = 3;
+    const phase = (progress * cycles) % 1;
+    const yPercent =
+      phase <= 0.5 ? phase * 200 : (1 - phase) * 200;
+    this.setShine(this.shineX, `${Math.min(100, Math.max(0, yPercent))}%`);
   }
 
-  private updateShineFromPointer(e: MouseEvent): void {
-    if (this.shineRafId !== null) return;
-    this.shineRafId = requestAnimationFrame(() => {
-      this.shineRafId = null;
-      const xPercent = (e.clientX / window.innerWidth) * 100;
-      this.setShine(`${xPercent}%`, this.shineY);
-    });
+  private doUpdateShineFromPointer(e: MouseEvent): void {
+    if (!this.isConnected) return;
+    const xPercent = (e.clientX / window.innerWidth) * 100;
+    this.setShine(`${xPercent}%`, this.shineY);
   }
 
   protected connectedCallback() {
     super.connectedCallback();
     this.init(DfwBackgroundGearsComponent.observedAttributes);
 
+    this.debouncedResizeDone = debounceCb(() => {
+      if (!this.isConnected) return;
+      (this as unknown as HTMLElement).classList.remove("dfw-background-gears--resizing");
+      this.updateHeightToPage();
+      this.scope.backgroundGears = this.buildGearsWithRandomLayout();
+      this.view?.update(this.scope);
+    }, DfwBackgroundGearsComponent.RESIZE_DEBOUNCE_MS);
+
+    this.debouncedShineFromScroll = debounceF(() => this.doUpdateShineFromScroll());
+    this.debouncedShineFromPointer = debounceF((e: MouseEvent) => this.doUpdateShineFromPointer(e));
+
     this.scope.backgroundGears = this.buildGearsWithRandomLayout();
     this.updateHeightToPage();
-    this.updateShineFromScroll();
+    this.debouncedShineFromScroll();
 
     const dispatcher = EventDispatcher.getInstance(ROUTER_VIEW_ID);
     dispatcher.on("initStateChange", this.boundOnInitStateChange);
@@ -176,8 +200,8 @@ export class DfwBackgroundGearsComponent extends Component {
       passive: true,
     });
     window.addEventListener("resize", this.boundUpdateShineFromScroll);
-    window.addEventListener("resize", this.boundUpdateHeightToPage);
-    this.resizeObserver = new ResizeObserver(() => this.updateHeightToPage());
+    window.addEventListener("resize", this.boundOnResize);
+    this.resizeObserver = new ResizeObserver(this.boundOnResize);
     this.resizeObserver.observe(document.body);
     if (window.matchMedia("(pointer: fine)").matches) {
       window.addEventListener("mousemove", this.boundUpdateShineFromPointer);
@@ -187,15 +211,11 @@ export class DfwBackgroundGearsComponent extends Component {
   protected disconnectedCallback(): void {
     this.routerUnsubscribe?.();
     this.routerUnsubscribe = null;
-    if (this.shineRafId !== null) {
-      cancelAnimationFrame(this.shineRafId);
-      this.shineRafId = null;
-    }
     this.resizeObserver?.disconnect();
     this.resizeObserver = null;
     window.removeEventListener("scroll", this.boundUpdateShineFromScroll);
     window.removeEventListener("resize", this.boundUpdateShineFromScroll);
-    window.removeEventListener("resize", this.boundUpdateHeightToPage);
+    window.removeEventListener("resize", this.boundOnResize);
     window.removeEventListener("mousemove", this.boundUpdateShineFromPointer);
     super.disconnectedCallback();
   }

src/ts/components/dfw-contact-map/dfw-contact-map.component.ts

@@ -1,24 +1,6 @@
 import { Component } from "@ribajs/core";
-import { hasChildNodesTrim } from "@ribajs/utils/src/dom.js";
-
-function debounce<T extends (...args: unknown[]) => void>(
-  fn: T,
-  ms: number
-): (...args: Parameters<T>) => void {
-  let timeoutId: ReturnType<typeof setTimeout>;
-  return (...args: Parameters<T>) => {
-    clearTimeout(timeoutId);
-    timeoutId = setTimeout(() => fn(...args), ms);
-  };
-}
-
-/**
- * Scrolls the map wrapper so the image is centered (like mm-map in markus-morische-rechtsanwalt-website).
- */
-function scrollToCenter(wrapper: HTMLElement): void {
-  wrapper.scrollLeft = (wrapper.scrollWidth - wrapper.clientWidth) / 2;
-  wrapper.scrollTop = (wrapper.scrollHeight - wrapper.clientHeight) / 2;
-}
+import { debounceCb } from "@ribajs/utils/src/control.js";
+import { hasChildNodesTrim, scrollToPosition } from "@ribajs/utils/src/dom.js";
 
 export interface DfwContactMapScope {
   scrollWrapperEl: HTMLDivElement | null;
@@ -39,7 +21,7 @@ export class DfwContactMapComponent extends Component {
     center: this.center.bind(this),
   };
 
-  private boundCenter = debounce(this.center.bind(this), 100);
+  private boundCenter = debounceCb(this.center.bind(this), 100);
 
   protected connectedCallback() {
     super.connectedCallback();
@@ -64,7 +46,7 @@ export class DfwContactMapComponent extends Component {
   public center(): void {
     const wrapper = this.scope.scrollWrapperEl;
     if (wrapper) {
-      scrollToCenter(wrapper);
+      scrollToPosition(wrapper, "center", "both", "auto");
     }
   }
 

src/ts/components/dfw-scroll-visibility/dfw-scroll-visibility.component.ts

@@ -1,4 +1,5 @@
 import { Component } from "@ribajs/core";
+import { debounceF } from "@ribajs/utils/src/control.js";
 import { hasChildNodesTrim } from "@ribajs/utils/src/dom.js";
 
 const VISIBLE_SCROLL_START = 0.1; // show after 10% from top
@@ -19,42 +20,36 @@ export class DfwScrollVisibilityComponent extends Component {
     return [];
   }
 
-  private rafId: number | null = null;
-  private readonly boundUpdateVisibility = () => this.updateVisibility();
+  private debouncedUpdateVisibility!: () => void;
+  private readonly boundUpdateVisibility = () => this.debouncedUpdateVisibility();
 
   protected connectedCallback() {
     super.connectedCallback();
     this.setAttribute("data-visible", "false");
     this.init(DfwScrollVisibilityComponent.observedAttributes);
+
+    this.debouncedUpdateVisibility = debounceF(() => {
+      if (!this.isConnected) return;
+      const maxScroll = document.documentElement.scrollHeight - window.innerHeight;
+      const visible =
+        maxScroll <= 0 ||
+        (window.scrollY >= maxScroll * VISIBLE_SCROLL_START &&
+         window.scrollY <= maxScroll * VISIBLE_SCROLL_END);
+      this.setAttribute("data-visible", visible ? "true" : "false");
+    });
   }
 
   protected async afterBind() {
     await super.afterBind();
-    this.updateVisibility();
+    this.debouncedUpdateVisibility();
     window.addEventListener("scroll", this.boundUpdateVisibility, { passive: true });
   }
 
   protected disconnectedCallback() {
     window.removeEventListener("scroll", this.boundUpdateVisibility);
-    if (this.rafId !== null) {
-      cancelAnimationFrame(this.rafId);
-    }
     super.disconnectedCallback();
   }
 
-  private updateVisibility(): void {
-    if (this.rafId !== null) return;
-    this.rafId = requestAnimationFrame(() => {
-      this.rafId = null;
-      const maxScroll = document.documentElement.scrollHeight - window.innerHeight;
-      const visible =
-        maxScroll <= 0 ||
-        (window.scrollY >= maxScroll * VISIBLE_SCROLL_START &&
-         window.scrollY <= maxScroll * VISIBLE_SCROLL_END);
-      this.setAttribute("data-visible", visible ? "true" : "false");
-    });
-  }
-
   protected requiredAttributes(): string[] {
     return [];
   }

src/ts/logo-scroll-rotate.ts

@@ -1,3 +1,5 @@
+import { debounceF } from "@ribajs/utils/src/control.js";
+
 /**
  * Applies scroll-based rotation to static elements with data-scroll-rotate (e.g. .logo-gear).
  * Same behavior as ScrollRotateBinder; used for static Pug-rendered logo so no Riba component is needed.
@@ -18,16 +20,9 @@ function updateAll() {
   });
 }
 
-let rafId: number | null = null;
-function onScroll() {
-  if (rafId !== null) return;
-  rafId = requestAnimationFrame(() => {
-    rafId = null;
-    updateAll();
-  });
-}
-
 export function initLogoScrollRotate(): void {
+  const onScroll = debounceF(updateAll);
+
   updateAll();
-  window.addEventListener("scroll", onScroll, { passive: true });
+  window.addEventListener("scroll", () => onScroll(), { passive: true });
 }