react-sway 0.2.6 → 0.3.0

package/README.md

@@ -1,22 +1,23 @@
 # react-sway
 
-A React component for smooth, infinite, and interactive content scrolling. It duplicates content to create a seamless looping effect, controllable via touch, mouse drag, wheel, and keyboard.
+A React component for smooth, infinite, and interactive content scrolling on the vertical or horizontal axis. It duplicates content to create a seamless looping effect, controllable via touch, mouse drag, wheel, keyboard, or edge hover.
 
 ## What is `react-sway`?
 
-React Sway takes your list of items and makes them scroll endlessly. It's designed to be easy to use and performant, with auto-scrolling that pauses when users interact.
+React Sway takes your list of items and makes them scroll endlessly. It's designed to be easy to use and performant, with auto-scrolling that pauses when users interact. Edge-hover layouts can also be configured to scroll only while the pointer hovers the active axis boundary: top/bottom for vertical loops or left/right for horizontal loops.
 
 It works by duplicating your content to create a seamless loop and uses CSS transforms for smooth animation. The duplicated content is wrapped in `<aside>` elements with `aria-hidden="true"` and `role="presentation"` to ensure good accessibility and helps search engines understand the content structure.
 
 ### Core Features
 
-*   **Smooth Infinite Scroll:** Content loops continuously.
+*   **Smooth Infinite Scroll:** Content loops continuously on the vertical or horizontal axis.
 *   **Auto-Scroll:** Scrolls automatically, with configurable speed and direction.
+*   **Edge Hover:** Use `edgeHoverScroll` to keep auto-scroll idle until the pointer enters the active axis boundary zone.
 *   **User Friendly Interactions:**
     *   Click and drag to scroll.
     *   Swipe on touch devices.
-    *   Mouse wheel support with delta-mode normalization and velocity capping.
-    *   Keyboard controls: Spacebar to pause/resume, ArrowUp/ArrowDown to scroll, Home/End to jump.
+    *   Mouse wheel support with axis-aware intent detection, delta-mode normalization, and velocity capping.
+    *   Keyboard controls: Spacebar to pause/resume, Arrow keys 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.
 *   **Reduced Motion Support:** Respects `prefers-reduced-motion: reduce` by lowering auto-scroll speed and disabling momentum effects.
@@ -83,26 +84,151 @@ function SwayUsageExample() {
 export default SwayUsageExample;
 ```
 
+### Auto-scroll and edge-hover examples
+
+React Sway can either move automatically or stay idle until the pointer reaches an axis boundary. The resulting examples are the product of two axes and two trigger modes.
+
+```tsx
+import { ReactSway } from 'react-sway';
+
+function TriggerModeExamples() {
+  const edgeOnlyProps = {
+    draggable: false,
+    keyboard: false,
+    wheelEnabled: false,
+  };
+
+  return (
+    <div className="trigger-mode-grid">
+      <div className="trigger-mode-case">
+        <ReactSway>
+          <article className="content-item">Vertical auto</article>
+          <article className="content-item">Automatic trigger</article>
+          <article className="content-item">Continuous loop</article>
+        </ReactSway>
+      </div>
+
+      <div className="trigger-mode-case">
+        <ReactSway {...edgeOnlyProps} edgeHoverScroll edgeHoverSize={96}>
+          <article className="content-item">Vertical edge</article>
+          <article className="content-item">Top boundary</article>
+          <article className="content-item">Bottom boundary</article>
+        </ReactSway>
+      </div>
+
+      <div className="trigger-mode-case trigger-mode-case-horizontal">
+        <ReactSway axis="horizontal">
+          <article className="content-item">Horizontal auto</article>
+          <article className="content-item">Automatic trigger</article>
+          <article className="content-item">Continuous loop</article>
+        </ReactSway>
+      </div>
+
+      <div className="trigger-mode-case trigger-mode-case-horizontal">
+        <ReactSway {...edgeOnlyProps} axis="horizontal" edgeHoverScroll edgeHoverSize={96}>
+          <article className="content-item">Horizontal edge</article>
+          <article className="content-item">Left boundary</article>
+          <article className="content-item">Right boundary</article>
+        </ReactSway>
+      </div>
+    </div>
+  );
+}
+```
+
+```css
+.trigger-mode-grid {
+  display: grid;
+  gap: 16px;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+.trigger-mode-case {
+  height: 320px;
+  overflow: hidden;
+  position: relative;
+}
+
+.trigger-mode-case-horizontal {
+  align-items: center;
+  display: flex;
+}
+
+.trigger-mode-case-horizontal .content-item {
+  flex: 0 0 260px;
+}
+```
+
+Automatic cases start moving immediately and keep the default drag, touch, wheel, and keyboard interactions enabled. Edge-hover cases stay idle until the pointer enters top/bottom for vertical instances or left/right for horizontal instances.
+
+### Wheel intent modes
+
+By default, React Sway treats wheel gestures as axis-aware input. A horizontal instance consumes horizontal trackpad movement and Shift+wheel, while ordinary vertical wheel movement is left to the page. This prevents horizontal showcases from trapping page scroll when the pointer is above them.
+
+Use `wheelMode="capture"` when the Sway should intentionally own every wheel event that reaches it.
+
+```tsx
+function WheelModeExamples() {
+  return (
+    <>
+      <ReactSway axis="horizontal" wheelMode="axis">
+        <article className="content-item">Horizontal intent only</article>
+        <article className="content-item">Vertical wheel still scrolls the page</article>
+      </ReactSway>
+
+      <ReactSway axis="horizontal" wheelMode="capture">
+        <article className="content-item">Full wheel capture</article>
+        <article className="content-item">Vertical wheel drives the Sway</article>
+      </ReactSway>
+    </>
+  );
+}
+```
+
+```tsx
+function MinimalEdgeHoverExamples() {
+  return (
+    <>
+      <ReactSway draggable={false} edgeHoverScroll keyboard={false} wheelEnabled={false}>
+        <article className="content-item">Project Alpha</article>
+        <article className="content-item">Project Beta</article>
+        <article className="content-item">Project Gamma</article>
+      </ReactSway>
+
+      <ReactSway axis="horizontal" draggable={false} edgeHoverScroll keyboard={false} wheelEnabled={false}>
+        <article className="content-item">Project Alpha</article>
+        <article className="content-item">Project Beta</article>
+        <article className="content-item">Project Gamma</article>
+      </ReactSway>
+    </>
+  );
+}
+```
+
 ## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `axis` | `'vertical' \| 'horizontal'` | Inferred from `direction`, otherwise `'vertical'` | Scroll axis. Use `'horizontal'` for left/right loops. |
 | `autoScroll` | `boolean` | `true` | Enable/disable auto-scrolling. |
-| `children` | `ReactNode` | — | Content elements to render in the scroll container. |
-| `direction` | `'down' \| 'up'` | `'up'` | Auto-scroll direction. |
+| `children` | `ReactNode` | - | Content elements to render in the scroll container. |
+| `direction` | `'down' \| 'left' \| 'right' \| 'up'` | `'up'` | Auto-scroll direction. `left` and `right` imply horizontal scrolling when `axis` is omitted. |
 | `draggable` | `boolean` | `true` | Enable mouse/touch drag interaction. |
-| `friction` | `number` | `0.95` | Momentum decay coefficient (0–1, lower = more friction). |
-| `keyboard` | `boolean` | `true` | Enable keyboard controls (Space, ArrowUp/Down, Home/End). |
+| `edgeHoverScroll` | `boolean` | `false` | Only auto-scroll while hovering the active axis boundary: top/bottom for vertical, left/right for horizontal. |
+| `edgeHoverSize` | `number` | `96` | Thickness in pixels of each edge-hover activation zone. |
+| `friction` | `number` | `0.95` | Momentum decay coefficient (0-1, lower = more friction). |
+| `keyboard` | `boolean` | `true` | Enable keyboard controls (Space, Arrow keys, Home/End). |
 | `lazy` | `boolean` | `true` | Enable lazy visibility detection via IntersectionObserver. |
 | `lazyRootMargin` | `string` | `'100px'` | IntersectionObserver `rootMargin` for lazy visibility detection. |
 | `lazyThreshold` | `number` | `0.01` | IntersectionObserver `threshold` for lazy visibility detection. |
-| `onPause` | `() => void` | — | Fired when scrolling pauses. |
-| `onResume` | `() => void` | — | Fired when scrolling resumes after pause. |
-| `onScroll` | `(position: number) => void` | — | Fired on every position change with the current scroll position. |
+| `onPause` | `() => void` | - | Fired when scrolling pauses. |
+| `onResume` | `() => void` | - | Fired when scrolling resumes after pause. |
+| `onScroll` | `(position: number) => void` | - | Fired on every position change with the current scroll position. |
 | `pauseOnInteraction` | `boolean` | `true` | Pause auto-scroll during user interaction. |
 | `resumeDelay` | `number` | `2000` | Milliseconds before auto-scroll resumes after interaction. |
 | `speed` | `number` | `0.5` | Auto-scroll speed in pixels per frame at 60fps. |
 | `wheelEnabled` | `boolean` | `true` | Enable mouse wheel scrolling. |
+| `wheelMode` | `'axis' \| 'capture'` | `'axis'` | Define whether wheel input only consumes gestures aligned with the Sway axis or captures every wheel event. |
 
 ## License
 

package/dist/{index.d.cts → ReactSway.d.ts}

@@ -1,21 +1,31 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
-
+/**
+ * Core ReactSway component implementing axis-aware infinite scrolling interactions.
+ */
+import { type ReactNode } from 'react';
+export type SwayAxis = 'horizontal' | 'vertical';
+export type SwayDirection = 'down' | 'left' | 'right' | 'up';
+export type SwayWheelMode = 'axis' | 'capture';
 /**
  * Props for the ReactSway infinite scrolling component.
  */
-interface ReactSwayProps {
+export interface ReactSwayProps {
+    /** Scroll axis. Horizontal directions imply `horizontal` when omitted. @default 'vertical' */
+    axis?: SwayAxis;
     /** Enable/disable auto-scrolling. @default true */
     autoScroll?: boolean;
     /** Content elements to render in the infinite scroll container. */
     children: ReactNode;
     /** Auto-scroll direction. @default 'up' */
-    direction?: 'down' | 'up';
+    direction?: SwayDirection;
     /** Enable mouse/touch drag interaction. @default true */
     draggable?: boolean;
+    /** Only auto-scroll while the pointer hovers an axis boundary. @default false */
+    edgeHoverScroll?: boolean;
+    /** Edge-hover activation thickness in pixels. @default 96 */
+    edgeHoverSize?: number;
     /** Momentum decay coefficient (0-1, lower = more friction). @default 0.95 */
     friction?: number;
-    /** Enable keyboard controls (Space, ArrowUp/Down, Home/End). @default true */
+    /** Enable keyboard controls (Space, Arrow keys, Home/End). @default true */
     keyboard?: boolean;
     /** Enable lazy visibility detection via IntersectionObserver. @default true */
     lazy?: boolean;
@@ -37,12 +47,23 @@ interface ReactSwayProps {
     speed?: number;
     /** Enable mouse wheel scrolling. @default true */
     wheelEnabled?: boolean;
+    /**
+     * Defines which wheel gestures ReactSway may cancel.
+     *
+     * `axis` only consumes wheel gestures aligned with the Sway axis, letting
+     * cross-axis page scroll pass through. `capture` preserves legacy behavior
+     * by consuming every wheel event that reaches the component.
+     *
+     * @default 'axis'
+     */
+    wheelMode?: SwayWheelMode;
 }
 /**
  * A smooth, infinite scrolling container component.
  *
  * Renders children in a continuously looping scroll area with support for
- * auto-scrolling, mouse drag, touch swipe, wheel, and keyboard interactions.
+ * auto-scrolling, mouse drag, touch swipe, wheel, keyboard interactions,
+ * and optional edge-hover scrolling.
  * Content is duplicated to create a seamless loop effect. Duplicate content
  * is wrapped in `<aside>` elements with `aria-hidden="true"` for accessibility.
  *
@@ -57,6 +78,5 @@ interface ReactSwayProps {
  * </ReactSway>
  * ```
  */
-declare function ReactSway({ autoScroll, children, direction, draggable, friction, keyboard, lazy, lazyRootMargin, lazyThreshold, onPause, onResume, onScroll, pauseOnInteraction, resumeDelay, speed, wheelEnabled, }: ReactSwayProps): react_jsx_runtime.JSX.Element;
-
-export { ReactSway, type ReactSwayProps };
+declare function ReactSway({ axis, autoScroll, children, direction, draggable, edgeHoverScroll, edgeHoverSize, friction, keyboard, lazy, lazyRootMargin, lazyThreshold, onPause, onResume, onScroll, pauseOnInteraction, resumeDelay, speed, wheelEnabled, wheelMode, }: ReactSwayProps): import("react").JSX.Element;
+export default ReactSway;