react-sway 0.2.0 → 0.2.2

package/README.md

@@ -15,7 +15,7 @@ It works by duplicating your content to create a seamless loop and uses CSS tran
 *   **User Friendly Interactions:**
     *   Click and drag to scroll.
     *   Swipe on touch devices.
-    *   Mouse wheel support with velocity capping.
+    *   Mouse wheel support with delta-mode normalization and velocity capping.
     *   Keyboard controls: Spacebar to pause/resume, ArrowUp/ArrowDown to scroll, Home/End to jump.
 *   **Responsive:** Adjusts to window resizing with debounced recalculation.
 *   **Lazy Visibility Detection:** Add a `content-item` class to your child elements, and `react-sway` automatically uses an IntersectionObserver to add a `.visible` class when they enter the viewport. Useful for triggering CSS animations or deferred rendering. Configurable via `lazy`, `lazyRootMargin`, and `lazyThreshold` props.

package/dist/index.cjs

@@ -39,7 +39,37 @@ var MAX_VELOCITY = 150;
 var MS_PER_FRAME_60FPS = 16.667;
 var REDUCED_MOTION_SPEED_FACTOR = 0.25;
 var RESIZE_DEBOUNCE_MS = 150;
-var WHEEL_VELOCITY_MULTIPLIER = 0.3;
+var WHEEL_LINE_HEIGHT_FALLBACK_PX = 16;
+var WHEEL_MODE_LINE = 1;
+var WHEEL_MODE_PAGE = 2;
+var WHEEL_PIXEL_MIN_DELTA_PX = 48;
+var WHEEL_VELOCITY_MULTIPLIER = 0.14;
+var WHEEL_IMMEDIATE_DELTA_FACTOR = 0.14;
+var WHEEL_LEGACY_NOTCH_DELTA = 120;
+function getLegacyWheelPixelDeltaY(event) {
+  const { wheelDelta, wheelDeltaY } = event;
+  const legacyWheelDelta = typeof wheelDeltaY === "number" ? wheelDeltaY : wheelDelta;
+  if (typeof legacyWheelDelta !== "number" || !Number.isFinite(legacyWheelDelta)) {
+    return 0;
+  }
+  return -(legacyWheelDelta / WHEEL_LEGACY_NOTCH_DELTA) * WHEEL_PIXEL_MIN_DELTA_PX;
+}
+function normalizeWheelDeltaY(event, container) {
+  if (event.deltaMode === WHEEL_MODE_LINE) {
+    const computedLineHeight = Number.parseFloat(window.getComputedStyle(container).lineHeight);
+    const lineHeight = Number.isFinite(computedLineHeight) ? computedLineHeight : WHEEL_LINE_HEIGHT_FALLBACK_PX;
+    return event.deltaY * lineHeight;
+  }
+  if (event.deltaMode === WHEEL_MODE_PAGE) {
+    const pageHeight = Math.max(container.clientHeight, window.innerHeight, 1);
+    return event.deltaY * pageHeight;
+  }
+  const legacyWheelPixelDeltaY = getLegacyWheelPixelDeltaY(event);
+  if (Math.abs(event.deltaY) < WHEEL_PIXEL_MIN_DELTA_PX && Math.abs(legacyWheelPixelDeltaY) >= WHEEL_PIXEL_MIN_DELTA_PX) {
+    return legacyWheelPixelDeltaY;
+  }
+  return event.deltaY;
+}
 function ReactSway({
   autoScroll = true,
   children,
@@ -292,12 +322,18 @@ function ReactSway({
   }, [draggable, pauseAutoScroll]);
   const handleWheel = (0, import_react.useCallback)((e) => {
     if (!wheelEnabled) return;
+    const currentContainer = e.currentTarget instanceof HTMLElement ? e.currentTarget : containerRef.current;
+    if (!currentContainer) return;
     e.preventDefault();
-    velocityRef.current -= e.deltaY * WHEEL_VELOCITY_MULTIPLIER;
+    const normalizedDeltaY = normalizeWheelDeltaY(e, currentContainer);
+    const wheelDelta = -normalizedDeltaY;
+    const nextPosition = wrapPosition(positionRef.current + wheelDelta * WHEEL_IMMEDIATE_DELTA_FACTOR);
+    commitPosition(nextPosition);
+    velocityRef.current += wheelDelta * WHEEL_VELOCITY_MULTIPLIER;
     velocityRef.current = Math.max(-MAX_VELOCITY, Math.min(MAX_VELOCITY, velocityRef.current));
     pauseAutoScroll();
     scheduleAutoScrollResume();
-  }, [pauseAutoScroll, scheduleAutoScrollResume, wheelEnabled]);
+  }, [commitPosition, pauseAutoScroll, scheduleAutoScrollResume, wheelEnabled, wrapPosition]);
   (0, import_react.useEffect)(() => {
     const currentContainer = containerRef.current;
     if (!currentContainer) return;

package/dist/index.js

@@ -13,7 +13,37 @@ var MAX_VELOCITY = 150;
 var MS_PER_FRAME_60FPS = 16.667;
 var REDUCED_MOTION_SPEED_FACTOR = 0.25;
 var RESIZE_DEBOUNCE_MS = 150;
-var WHEEL_VELOCITY_MULTIPLIER = 0.3;
+var WHEEL_LINE_HEIGHT_FALLBACK_PX = 16;
+var WHEEL_MODE_LINE = 1;
+var WHEEL_MODE_PAGE = 2;
+var WHEEL_PIXEL_MIN_DELTA_PX = 48;
+var WHEEL_VELOCITY_MULTIPLIER = 0.14;
+var WHEEL_IMMEDIATE_DELTA_FACTOR = 0.14;
+var WHEEL_LEGACY_NOTCH_DELTA = 120;
+function getLegacyWheelPixelDeltaY(event) {
+  const { wheelDelta, wheelDeltaY } = event;
+  const legacyWheelDelta = typeof wheelDeltaY === "number" ? wheelDeltaY : wheelDelta;
+  if (typeof legacyWheelDelta !== "number" || !Number.isFinite(legacyWheelDelta)) {
+    return 0;
+  }
+  return -(legacyWheelDelta / WHEEL_LEGACY_NOTCH_DELTA) * WHEEL_PIXEL_MIN_DELTA_PX;
+}
+function normalizeWheelDeltaY(event, container) {
+  if (event.deltaMode === WHEEL_MODE_LINE) {
+    const computedLineHeight = Number.parseFloat(window.getComputedStyle(container).lineHeight);
+    const lineHeight = Number.isFinite(computedLineHeight) ? computedLineHeight : WHEEL_LINE_HEIGHT_FALLBACK_PX;
+    return event.deltaY * lineHeight;
+  }
+  if (event.deltaMode === WHEEL_MODE_PAGE) {
+    const pageHeight = Math.max(container.clientHeight, window.innerHeight, 1);
+    return event.deltaY * pageHeight;
+  }
+  const legacyWheelPixelDeltaY = getLegacyWheelPixelDeltaY(event);
+  if (Math.abs(event.deltaY) < WHEEL_PIXEL_MIN_DELTA_PX && Math.abs(legacyWheelPixelDeltaY) >= WHEEL_PIXEL_MIN_DELTA_PX) {
+    return legacyWheelPixelDeltaY;
+  }
+  return event.deltaY;
+}
 function ReactSway({
   autoScroll = true,
   children,
@@ -266,12 +296,18 @@ function ReactSway({
   }, [draggable, pauseAutoScroll]);
   const handleWheel = useCallback((e) => {
     if (!wheelEnabled) return;
+    const currentContainer = e.currentTarget instanceof HTMLElement ? e.currentTarget : containerRef.current;
+    if (!currentContainer) return;
     e.preventDefault();
-    velocityRef.current -= e.deltaY * WHEEL_VELOCITY_MULTIPLIER;
+    const normalizedDeltaY = normalizeWheelDeltaY(e, currentContainer);
+    const wheelDelta = -normalizedDeltaY;
+    const nextPosition = wrapPosition(positionRef.current + wheelDelta * WHEEL_IMMEDIATE_DELTA_FACTOR);
+    commitPosition(nextPosition);
+    velocityRef.current += wheelDelta * WHEEL_VELOCITY_MULTIPLIER;
     velocityRef.current = Math.max(-MAX_VELOCITY, Math.min(MAX_VELOCITY, velocityRef.current));
     pauseAutoScroll();
     scheduleAutoScrollResume();
-  }, [pauseAutoScroll, scheduleAutoScrollResume, wheelEnabled]);
+  }, [commitPosition, pauseAutoScroll, scheduleAutoScrollResume, wheelEnabled, wrapPosition]);
   useEffect(() => {
     const currentContainer = containerRef.current;
     if (!currentContainer) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "author": {
-    "name": "Mehdy Lafitte",
+    "name": "Lafitte Mehdy",
     "url": "https://github.com/lafittemehdy"
   },
   "bugs": {
@@ -8,19 +8,21 @@
   },
   "description": "A React component for smooth infinite scrolling, designed for creating engaging, continuous content streams with minimal configuration.",
   "devDependencies": {
+    "@emnapi/core": "^1.10.0",
+    "@emnapi/runtime": "^1.10.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "eslint": "^9.39.4",
     "eslint-plugin-react": "^7.37.5",
-    "eslint-plugin-react-hooks": "^7.0.1",
-    "jsdom": "^28.1.0",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.0"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
   },
   "files": [
     "dist",
@@ -49,7 +51,8 @@
     "react-dom": ">=16.8.0"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "repository": {
     "type": "git",
@@ -65,5 +68,5 @@
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.2.0"
+  "version": "0.2.2"
 }

package/src/ReactSway.tsx

@@ -36,8 +36,74 @@ const REDUCED_MOTION_SPEED_FACTOR = 0.25;
 /** Debounce delay in milliseconds for ResizeObserver callbacks. */
 const RESIZE_DEBOUNCE_MS = 150;
 
+/** Fallback pixel height for wheel events reported in line units. */
+const WHEEL_LINE_HEIGHT_FALLBACK_PX = 16;
+
+/** WheelEvent deltaMode value for line-based deltas. */
+const WHEEL_MODE_LINE = 1;
+
+/** WheelEvent deltaMode value for page-based deltas. */
+const WHEEL_MODE_PAGE = 2;
+
+/** Minimum pixel impulse for discrete wheel hardware reporting tiny pixel deltas. */
+const WHEEL_PIXEL_MIN_DELTA_PX = 48;
+
 /** Multiplier applied to wheel deltaY to convert to scroll velocity. */
-const WHEEL_VELOCITY_MULTIPLIER = 0.3;
+const WHEEL_VELOCITY_MULTIPLIER = 0.14;
+
+/** Small immediate wheel movement used to keep input responsive without jumping. */
+const WHEEL_IMMEDIATE_DELTA_FACTOR = 0.14;
+
+/** Legacy wheelDelta magnitude that usually represents one physical wheel notch. */
+const WHEEL_LEGACY_NOTCH_DELTA = 120;
+
+interface WheelEventWithLegacyDelta extends globalThis.WheelEvent {
+  wheelDelta?: number;
+  wheelDeltaY?: number;
+}
+
+function getLegacyWheelPixelDeltaY(event: globalThis.WheelEvent) {
+  const { wheelDelta, wheelDeltaY } = event as WheelEventWithLegacyDelta;
+  const legacyWheelDelta = typeof wheelDeltaY === 'number' ? wheelDeltaY : wheelDelta;
+
+  if (typeof legacyWheelDelta !== 'number' || !Number.isFinite(legacyWheelDelta)) {
+    return 0;
+  }
+
+  return -(legacyWheelDelta / WHEEL_LEGACY_NOTCH_DELTA) * WHEEL_PIXEL_MIN_DELTA_PX;
+}
+
+/**
+ * Converts wheel deltas to pixels so mouse wheels, touchpads, and page-wheel
+ * devices feed the same Sway velocity system.
+ */
+function normalizeWheelDeltaY(event: globalThis.WheelEvent, container: HTMLElement) {
+  if (event.deltaMode === WHEEL_MODE_LINE) {
+    const computedLineHeight = Number.parseFloat(window.getComputedStyle(container).lineHeight);
+    const lineHeight = Number.isFinite(computedLineHeight)
+      ? computedLineHeight
+      : WHEEL_LINE_HEIGHT_FALLBACK_PX;
+
+    return event.deltaY * lineHeight;
+  }
+
+  if (event.deltaMode === WHEEL_MODE_PAGE) {
+    const pageHeight = Math.max(container.clientHeight, window.innerHeight, 1);
+
+    return event.deltaY * pageHeight;
+  }
+
+  const legacyWheelPixelDeltaY = getLegacyWheelPixelDeltaY(event);
+
+  if (
+    Math.abs(event.deltaY) < WHEEL_PIXEL_MIN_DELTA_PX &&
+    Math.abs(legacyWheelPixelDeltaY) >= WHEEL_PIXEL_MIN_DELTA_PX
+  ) {
+    return legacyWheelPixelDeltaY;
+  }
+
+  return event.deltaY;
+}
 
 /**
  * Props for the ReactSway infinite scrolling component.
@@ -382,12 +448,19 @@ function ReactSway({
 
   const handleWheel = useCallback((e: globalThis.WheelEvent) => {
     if (!wheelEnabled) return;
+    const currentContainer = e.currentTarget instanceof HTMLElement ? e.currentTarget : containerRef.current;
+    if (!currentContainer) return;
+
     e.preventDefault();
-    velocityRef.current -= e.deltaY * WHEEL_VELOCITY_MULTIPLIER;
+    const normalizedDeltaY = normalizeWheelDeltaY(e, currentContainer);
+    const wheelDelta = -normalizedDeltaY;
+    const nextPosition = wrapPosition(positionRef.current + wheelDelta * WHEEL_IMMEDIATE_DELTA_FACTOR);
+    commitPosition(nextPosition);
+    velocityRef.current += wheelDelta * WHEEL_VELOCITY_MULTIPLIER;
     velocityRef.current = Math.max(-MAX_VELOCITY, Math.min(MAX_VELOCITY, velocityRef.current));
     pauseAutoScroll();
     scheduleAutoScrollResume();
-  }, [pauseAutoScroll, scheduleAutoScrollResume, wheelEnabled]);
+  }, [commitPosition, pauseAutoScroll, scheduleAutoScrollResume, wheelEnabled, wrapPosition]);
 
   // Event listener registration
   useEffect(() => {

package/src/__tests__/ReactSway.test.tsx

@@ -1,7 +1,7 @@
 /**
  * Behavioral and regression tests for ReactSway.
  */
-import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { ReactSway } from '../index';
@@ -276,6 +276,25 @@ describe('ReactSway', () => {
   });
 
   describe('wheel events', () => {
+    const expectMinimumScroll = async (onScroll: ReturnType<typeof vi.fn>, minimumDistance: number) => {
+      await waitFor(() => {
+        const positions = onScroll.mock.calls.map(([position]) => position as number);
+        expect(Math.min(...positions)).toBeLessThanOrEqual(-minimumDistance);
+      });
+    };
+
+    const renderWheelHarness = () => {
+      const onScroll = vi.fn();
+      const { container } = render(
+        <ReactSway autoScroll={false} friction={1} onScroll={onScroll}>
+          <div>Content</div>
+        </ReactSway>
+      );
+      const swayContainer = container.querySelector('.react-sway-container') as HTMLElement;
+
+      return { onScroll, swayContainer };
+    };
+
     it('applies wheel delta to velocity (fires onPause)', () => {
       const onPause = vi.fn();
       const { container } = render(
@@ -289,6 +308,52 @@ describe('ReactSway', () => {
       expect(onPause).toHaveBeenCalledOnce();
     });
 
+    it('normalizes line-based wheel deltas before applying velocity', async () => {
+      const { onScroll, swayContainer } = renderWheelHarness();
+      fireEvent.wheel(swayContainer, { deltaMode: 1, deltaY: 3 });
+
+      await expectMinimumScroll(onScroll, 14);
+    });
+
+    it('normalizes page-based wheel deltas before applying velocity', async () => {
+      const { onScroll, swayContainer } = renderWheelHarness();
+      fireEvent.wheel(swayContainer, { deltaMode: 2, deltaY: 1 });
+
+      await expectMinimumScroll(onScroll, 100);
+    });
+
+    it('normalizes tiny pixel deltas from discrete wheel hardware', async () => {
+      const { onScroll, swayContainer } = renderWheelHarness();
+      const wheelEvent = new WheelEvent('wheel', {
+        bubbles: true,
+        cancelable: true,
+        deltaMode: 0,
+        deltaY: 1,
+      });
+      Object.defineProperty(wheelEvent, 'wheelDelta', {
+        value: -120,
+      });
+      swayContainer.dispatchEvent(wheelEvent);
+
+      await expectMinimumScroll(onScroll, 10);
+    });
+
+    it('falls back to legacy wheel deltas when pixel delta is zero', async () => {
+      const { onScroll, swayContainer } = renderWheelHarness();
+      const wheelEvent = new WheelEvent('wheel', {
+        bubbles: true,
+        cancelable: true,
+        deltaMode: 0,
+        deltaY: 0,
+      });
+      Object.defineProperty(wheelEvent, 'wheelDeltaY', {
+        value: -120,
+      });
+      swayContainer.dispatchEvent(wheelEvent);
+
+      await expectMinimumScroll(onScroll, 10);
+    });
+
     it('caps velocity at MAX_VELOCITY', () => {
       const onPause = vi.fn();
       const { container } = render(