refactor(website): extract shared math, media and rAF helpers

Author: heyradcode

website/src/components/common/SpotlightGroup/SpotlightGroup.tsx

@@ -2,6 +2,9 @@
 
 import { useEffect, useRef, type HTMLAttributes } from 'react';
 
+import { hasFinePointer } from '@/lib/media';
+import { rafThrottle } from '@/lib/rafThrottle';
+
 /**
  * Publishes the pointer's position over the hovered `[data-spotlight]` descendant
  * as `--mx` / `--my`, in px relative to that element's own box.
@@ -25,9 +28,8 @@ export default function SpotlightGroup({
     if (!root) return;
 
     // A spotlight is a hover affordance; a coarse pointer has nothing to track.
-    if (!window.matchMedia('(hover: hover) and (pointer: fine)').matches) return;
+    if (!hasFinePointer()) return;
 
-    let frame = 0;
     let target: HTMLElement | null = null;
     let clientX = 0;
     let clientY = 0;
@@ -37,13 +39,12 @@ export default function SpotlightGroup({
       el?.style.removeProperty('--my');
     };
 
-    const apply = () => {
-      frame = 0;
+    const apply = rafThrottle(() => {
       if (!target) return;
       const rect = target.getBoundingClientRect();
       target.style.setProperty('--mx', `${clientX - rect.left}px`);
       target.style.setProperty('--my', `${clientY - rect.top}px`);
-    };
+    });
 
     const onMove = (event: PointerEvent) => {
       const next = (event.target as Element | null)?.closest<HTMLElement>('[data-spotlight]') ?? null;
@@ -56,7 +57,7 @@ export default function SpotlightGroup({
 
       clientX = event.clientX;
       clientY = event.clientY;
-      if (!frame) frame = requestAnimationFrame(apply);
+      apply();
     };
 
     const onLeave = () => {
@@ -70,7 +71,7 @@ export default function SpotlightGroup({
     return () => {
       root.removeEventListener('pointermove', onMove);
       root.removeEventListener('pointerleave', onLeave);
-      if (frame) cancelAnimationFrame(frame);
+      apply.cancel();
     };
   }, []);
 

website/src/components/landing/Roadmap/index.tsx

@@ -5,6 +5,7 @@ import Image from 'next/image';
 
 import { ROADMAP, ROADMAP_STATUS_LABEL, SECTION_COPY } from '@/content/landing';
 import useScrollScene from '@/hooks/useScrollScene';
+import { clamp01 } from '@/lib/math';
 import './Roadmap.css';
 
 const { title: sectionTitle, subtitle } = SECTION_COPY.roadmap;
@@ -23,8 +24,6 @@ const PASS_FADE = 0.28;
     Kept shallow so the overshoot never balloons over the header strip. */
 const PASS_OVERSHOOT = 0.18;
 
-const clamp01 = (n: number) => (n < 0 ? 0 : n > 1 ? 1 : n);
-
 const Roadmap = () => {
   const gates = useRef<(HTMLElement | null)[]>([]);
   const stages = useRef<(HTMLElement | null)[]>([]);

website/src/components/landing/Stats/index.tsx

@@ -3,6 +3,7 @@
 import { useEffect, useRef } from 'react';
 
 import { STATS, type Stat } from '@/content/landing';
+import { prefersReducedMotion } from '@/lib/media';
 import './Stats.css';
 
 const COUNT_MS = 1500;
@@ -28,7 +29,7 @@ const Stats = () => {
       });
     };
 
-    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return;
+    if (prefersReducedMotion()) return;
 
     let frame = 0;
     let startedAt = 0;

website/src/components/layout/SiteHeader/SiteHeader.tsx

@@ -8,6 +8,7 @@ import { NAV_LINKS, SITE } from '@/content/landing';
 import useActiveSection from '@/hooks/useActiveSection';
 import useHashLanding from '@/hooks/useHashLanding';
 import useHeaderScroll from '@/hooks/useHeaderScroll';
+import { prefersReducedMotion } from '@/lib/media';
 import { openApp } from '@/lib/openApp';
 import { findSection, scrollToSection } from '@/lib/scrollToSection';
 import './SiteHeader.css';
@@ -51,8 +52,7 @@ export default function SiteHeader({ title }: SiteHeaderProps) {
       close();
       if (fromDrawer) toggleRef.current?.focus();
 
-      const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
-      scrollToSection(target, { smooth: !reduced });
+      scrollToSection(target, { smooth: !prefersReducedMotion() });
       window.history.pushState(null, '', href);
     },
     [close],

website/src/hooks/useHeaderScroll.ts

@@ -2,6 +2,8 @@
 
 import { useEffect, useRef, useState } from 'react';
 
+import { rafThrottle } from '@/lib/rafThrottle';
+
 /** Distance scrolled before the header condenses, in px. */
 const CONDENSE_AT = 24;
 
@@ -21,7 +23,6 @@ export default function useHeaderScroll<T extends HTMLElement>() {
 
   useEffect(() => {
     const header = ref.current;
-    let frame = 0;
 
     /**
      * Publishes the header's real height so anchor offsets cannot drift from
@@ -48,7 +49,6 @@ export default function useHeaderScroll<T extends HTMLElement>() {
     };
 
     const update = () => {
-      frame = 0;
       const y = window.scrollY;
 
       header?.style.setProperty(
@@ -58,10 +58,7 @@ export default function useHeaderScroll<T extends HTMLElement>() {
       setCondensed(y > CONDENSE_AT);
     };
 
-    const onScroll = () => {
-      if (frame) return;
-      frame = requestAnimationFrame(update);
-    };
+    const onScroll = rafThrottle(update);
 
     /* Watching the body catches the document growing as images decode and
        sections reveal, which is what actually changes the scrollable extent. */
@@ -81,7 +78,7 @@ export default function useHeaderScroll<T extends HTMLElement>() {
     return () => {
       window.removeEventListener('scroll', onScroll);
       sizeObserver.disconnect();
-      if (frame) cancelAnimationFrame(frame);
+      onScroll.cancel();
     };
   }, []);
 

website/src/hooks/useRevealObserver.ts

@@ -2,6 +2,8 @@
 
 import { useEffect } from 'react';
 
+import { prefersReducedMotion } from '@/lib/media';
+
 const VISIBLE_ATTR = 'data-reveal-visible';
 const DEFAULT_STAGGER_MS = 70;
 
@@ -23,7 +25,7 @@ export default function useRevealObserver() {
 
     // The CSS also honours the preference, but bailing here avoids installing an
     // observer that would only ever toggle attributes nothing reads.
-    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+    if (prefersReducedMotion()) {
       targets.forEach((el) => el.setAttribute(VISIBLE_ATTR, ''));
       return;
     }

website/src/hooks/useScrollScene.ts

@@ -2,7 +2,9 @@
 
 import { useEffect, useRef } from 'react';
 
-const clamp = (n: number) => (n < 0 ? 0 : n > 1 ? 1 : n);
+import { clamp01 } from '@/lib/math';
+import { REDUCED_MOTION } from '@/lib/media';
+import { rafThrottle } from '@/lib/rafThrottle';
 
 /**
  * Drives a 0-1 progress value from how far a tall section has been scrolled
@@ -45,9 +47,8 @@ export default function useScrollScene<
     if (!section || !pin) return;
 
     const narrow = window.matchMedia(fallbackQuery);
-    const reduced = window.matchMedia('(prefers-reduced-motion: reduce)');
+    const reduced = window.matchMedia(REDUCED_MOTION);
 
-    let frame = 0;
     let attached = false;
 
     /* Cached between frames. These change when the viewport does, not when the
@@ -73,18 +74,15 @@ export default function useScrollScene<
     };
 
     const update = () => {
-      frame = 0;
       if (scrollable <= 0) {
         write(1);
         return;
       }
       const travelled = stickyTop - section.getBoundingClientRect().top;
-      write(clamp(travelled / scrollable));
+      write(clamp01(travelled / scrollable));
     };
 
-    const onScroll = () => {
-      if (!frame) frame = requestAnimationFrame(update);
-    };
+    const onScroll = rafThrottle(update);
 
     /* Both elements are sized in viewport units, so this fires on viewport
        resize as well as any layout change that moves them. */
@@ -107,8 +105,7 @@ export default function useScrollScene<
       if (!attached) return;
       attached = false;
       window.removeEventListener('scroll', onScroll);
-      if (frame) cancelAnimationFrame(frame);
-      frame = 0;
+      onScroll.cancel();
     };
 
     const sync = () => {

website/src/lib/math.ts

@@ -0,0 +1,2 @@
+/** Clamps to the 0-1 range every progress value on this site is expressed in. */
+export const clamp01 = (n: number): number => (n < 0 ? 0 : n > 1 ? 1 : n);

website/src/lib/media.ts

@@ -0,0 +1,16 @@
+/**
+ * Media queries the site branches on.
+ *
+ * Named once because a mistyped query is a silent failure: it simply never
+ * matches, so the guard it was meant to be quietly stops guarding and the
+ * behaviour it protected runs for everyone.
+ */
+
+export const REDUCED_MOTION = '(prefers-reduced-motion: reduce)';
+
+/** A pointer that can hover and aim precisely — mouse or trackpad, not touch. */
+export const FINE_POINTER = '(hover: hover) and (pointer: fine)';
+
+export const prefersReducedMotion = (): boolean => window.matchMedia(REDUCED_MOTION).matches;
+
+export const hasFinePointer = (): boolean => window.matchMedia(FINE_POINTER).matches;

website/src/lib/rafThrottle.ts

@@ -0,0 +1,32 @@
+export interface RafThrottled {
+  (): void;
+  /** Drops any frame already booked. Call from effect cleanup. */
+  cancel(): void;
+}
+
+/**
+ * Collapses a burst of calls into one call per animation frame.
+ *
+ * The pattern every scroll and pointer listener here needs: events fire far
+ * faster than the screen refreshes, so running the handler per event is work
+ * thrown away before anything is painted.
+ */
+export const rafThrottle = (fn: () => void): RafThrottled => {
+  let frame = 0;
+
+  const run = () => {
+    frame = 0;
+    fn();
+  };
+
+  const throttled = (() => {
+    if (!frame) frame = requestAnimationFrame(run);
+  }) as RafThrottled;
+
+  throttled.cancel = () => {
+    if (frame) cancelAnimationFrame(frame);
+    frame = 0;
+  };
+
+  return throttled;
+};