react-sway 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.4.0
+
+- Added horizontal and vertical axis semantics with page-safe touch behavior.
+- Added bounded edge-hover acceleration, configurable zone geometry, and public defaults.
+- Added external pointer and wheel routing through `ReactSwayHandle`.
+- Added axis-aware and full-capture wheel ownership modes.
+- Added a consumer `className` hook and stricter numeric input normalization.
+- Corrected the peer contract to React 17 or newer, matching the published JSX runtime imports.
+- Improved loop measurement, listener cleanup, reduced-motion behavior, accessibility, and regression coverage.
+
+## 0.3.1
+
+- Updated development dependencies without changing the package runtime contract.
+
+## 0.3.0
+
+- Established the previous public ReactSway package contract.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lafitte Mehdy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,26 +4,30 @@ A React component for smooth, infinite, and interactive content scrolling on the
 
 ## 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. 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.
+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. Edge-hover speed ramps from idle to a bounded multiple of the configured speed as the pointer moves deeper into the boundary zone.
 
-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.
+It works by duplicating your content to create a seamless loop and uses CSS transforms for smooth animation. The duplicated content is wrapped in inert `<aside>` elements with `aria-hidden="true"` and `role="presentation"` so assistive technology, pointer input, and search crawlers keep treating the original group as canonical.
 
 ### Core Features
 
 *   **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.
+*   **Edge Hover:** Use `edgeHoverScroll` to keep auto-scroll idle until the pointer enters the active axis boundary zone, with speed scaled smoothly by boundary depth and capped by `edgeHoverSpeedMultiplier`.
 *   **User Friendly Interactions:**
     *   Click and drag to scroll.
     *   Swipe on touch devices.
     *   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.
+*   **External Input Bridge:** Use `ref` with `ReactSwayHandle` to route wheel and edge-hover intent from a parent drag/drop surface into Sway.
+*   **Idle-Safe Listeners:** Global drag listeners are attached only during active drag or touch gestures and cleaned up on release, cancel, blur, and unmount.
 *   **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.
 
 ## Installation
 
+React Sway supports React and React DOM 17 or newer. Its published ESM and CommonJS artifacts use React's modern JSX runtime.
+
 ```bash
 npm install react-sway
 # or
@@ -36,54 +40,121 @@ pnpm add react-sway
 
 ```tsx
 import { ReactSway } from 'react-sway';
-import './index.css'; // Your global styles
+import './index.css';
 
 function SwayUsageExample() {
   return (
-    <div className="scroller-container"> {/* Style this container to define ReactSway's area (e.g., full-page, or a specific height) */}
-      <ReactSway>
-        <div className="content-item" style={{ background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)' }}>
-          <h2>Seamless Scrolling</h2>
-          <p>Experience buttery smooth infinite scrolling with no stutters or pauses.</p>
-        </div>
-
-        <div className="content-item" style={{ background: 'linear-gradient(135deg, #f093fb 0%, #f5576c 100%)' }}>
-          <h2>Touch & Mouse Support</h2>
-          <p>Interact naturally with touch gestures, mouse wheel, or click-and-drag.</p>
-        </div>
-
-        <div className="content-item" style={{ background: 'linear-gradient(135deg, #4facfe 0%, #00f2fe 100%)' }}>
-          <h2>Momentum Scrolling</h2>
-          <p>Flick to scroll with realistic physics-based momentum and friction.</p>
-        </div>
-
-        <div className="content-item" style={{ background: 'linear-gradient(135deg, #43e97b 0%, #38f9d7 100%)' }}>
-          <h2>Performance Optimized</h2>
-          <p>Using requestAnimationFrame for 60+ FPS scrolling on all devices.</p>
-        </div>
-
-        <div className="content-item" style={{ background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)' }}>
-          <h2>Responsive Design</h2>
-          <p>Adapts perfectly to any screen size and device orientation.</p>
-        </div>
-
-        <div className="content-item" style={{ background: 'linear-gradient(135deg, #f093fb 0%, #f5576c 100%)' }}>
-          <h2>No Native Scroll</h2>
-          <p>Custom implementation avoids native scroll jank and inconsistencies.</p>
-        </div>
-
-        <div className="content-item" style={{ background: 'linear-gradient(135deg, #4facfe 0%, #00f2fe 100%)' }}>
-          <h2>Continuous Loop</h2>
-          <p>Content loops seamlessly without any visible seams or jumps.</p>
-        </div>
-      </ReactSway>
-    </div>
+    <section className="composer-grid" aria-label="Selected media order">
+      <aside className="composer-cell composer-copy">
+        <p>Selected order</p>
+        <h2>Horizontal media rail</h2>
+      </aside>
+
+      <div className="composer-cell rail-cell">
+        <ReactSway
+          axis="horizontal"
+          direction="left"
+          edgeHoverScroll
+          edgeHoverSize={72}
+          keyboard={false}
+          lazy={false}
+          speed={0.8}
+          wheelMode="capture"
+        >
+          <ol className="media-rail" aria-label="Selected post media order">
+            {['Cover', 'Wide crop', 'Motion study', 'Detail frame', 'Archive still'].map((title, index) => (
+              <li className="media-card" key={title}>
+                <span>{String(index + 1).padStart(2, '0')}</span>
+                <strong>{title}</strong>
+              </li>
+            ))}
+          </ol>
+        </ReactSway>
+      </div>
+    </section>
   );
 }
 
 export default SwayUsageExample;
 ```
 
+```css
+.composer-grid {
+  --line: rgb(255 255 255 / 0.12);
+
+  background: var(--line);
+  display: grid;
+  gap: 1px;
+  grid-template-columns: minmax(12rem, 0.7fr) minmax(0, 1.3fr);
+  min-height: 18rem;
+}
+
+.composer-cell {
+  background: #050505;
+  color: white;
+  min-width: 0;
+  overflow: hidden;
+  padding: 1rem;
+  position: relative;
+}
+
+.composer-copy {
+  align-content: end;
+  display: grid;
+  gap: 0.5rem;
+}
+
+.composer-copy p {
+  color: rgb(255 255 255 / 0.58);
+  font: 700 0.72rem/1 system-ui;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.composer-copy h2 {
+  font: 400 clamp(1.6rem, 4vw, 3rem) / 0.95 Georgia, serif;
+}
+
+.rail-cell {
+  min-height: 100%;
+}
+
+.rail-cell .react-sway-container {
+  left: 0;
+  top: 0;
+}
+
+.media-rail {
+  display: flex;
+  gap: 0.7rem;
+  height: 100%;
+  list-style: none;
+  margin: 0;
+  padding: 1rem;
+}
+
+.media-card {
+  background: #0b0b0b;
+  box-shadow: inset 0 0 0 1px var(--line);
+  display: grid;
+  flex: 0 0 clamp(9rem, 22vw, 12rem);
+  grid-template-rows: auto 1fr;
+  min-width: 0;
+  padding: 0.75rem;
+}
+
+.media-card span {
+  color: rgb(255 255 255 / 0.52);
+  font: 700 0.68rem/1 system-ui;
+}
+
+.media-card strong {
+  align-self: end;
+  color: white;
+  font: 400 1.35rem/0.98 Georgia, serif;
+}
+```
+
 ### 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.
@@ -209,27 +280,104 @@ function MinimalEdgeHoverExamples() {
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `axis` | `'vertical' \| 'horizontal'` | Inferred from `direction`, otherwise `'vertical'` | Scroll axis. Use `'horizontal'` for left/right loops. |
+| `ariaLabel` | `string` | `'Scrollable content'` | Accessible name for the scrolling region. |
+| `axis` | `'horizontal' \| 'vertical'` | 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. |
+| `className` | `string` | - | Additional class name applied to the semantic scrolling region. |
 | `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. |
-| `edgeHoverScroll` | `boolean` | `false` | Only auto-scroll while hovering the active axis boundary: top/bottom for vertical, left/right for horizontal. |
+| `edgeHoverInputMode` | `'external' \| 'hybrid'` | `'hybrid'` | Use intrinsic pointer sensing plus the imperative bridge, or external imperative ownership only for composed drag surfaces. |
+| `edgeHoverScroll` | `boolean` | `false` | Only auto-scroll while hovering the active axis boundary: top/bottom for vertical, left/right for horizontal. A short ingress feather removes sensor chatter; velocity then accelerates through the physical edge and reaches its bounded cap one activation-zone width beyond it. |
 | `edgeHoverSize` | `number` | `96` | Thickness in pixels of each edge-hover activation zone. |
+| `edgeHoverSpeedMultiplier` | `number` | `6` | Maximum edge-hover velocity as a multiple of `speed`. The physical edge retains the established 3x response, then accelerates to the bounded `1`–`10` maximum beyond the viewport; set `1` for constant speed. |
 | `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. |
+| `lazyThreshold` | `number` | `0.01` | IntersectionObserver `threshold`, normalized to the inclusive `0`–`1` interval. |
+| `onPause` | `() => void` | - | Fired once when active autonomous scrolling transitions to interaction-paused. |
+| `onResume` | `() => void` | - | Fired when interaction-paused autonomous scrolling resumes. |
 | `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. |
+| `speed` | `number` | `0.5` | Baseline auto-scroll speed in pixels per frame at 60fps. Edge-hover mode preserves this baseline inside the active zone and adds bounded depth acceleration. |
 | `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. |
 
+## Imperative handle
+
+`ReactSway` supports `ref` through `ReactSwayHandle`. This is intended for composed interactions where another component owns pointer capture, such as drag-and-drop reorder rails, but Sway should still receive wheel or edge-hover intent.
+
+```tsx
+import { useEffect, useRef } from 'react';
+import {
+  DEFAULT_EDGE_HOVER_SIZE,
+  DEFAULT_EDGE_HOVER_SPEED_MULTIPLIER,
+  ReactSway,
+  type ReactSwayHandle,
+} from 'react-sway';
+
+function ExternalDragBridge() {
+  const swayRef = useRef<ReactSwayHandle | null>(null);
+  const clearEdgeHover = () => swayRef.current?.clearEdgeHover();
+
+  useEffect(() => clearEdgeHover, []);
+
+  return (
+    <div
+      onPointerCancel={clearEdgeHover}
+      onPointerMove={(event) => {
+        swayRef.current?.handleEdgeHover({
+          clientX: event.clientX,
+          clientY: event.clientY,
+        });
+      }}
+      onPointerUp={clearEdgeHover}
+      onWheel={(event) => {
+        swayRef.current?.handleWheel(event.nativeEvent);
+      }}
+    >
+      <ReactSway
+        axis="horizontal"
+        direction="left"
+        draggable={false}
+        edgeHoverInputMode="external"
+        edgeHoverScroll
+        edgeHoverSize={DEFAULT_EDGE_HOVER_SIZE}
+        edgeHoverSpeedMultiplier={DEFAULT_EDGE_HOVER_SPEED_MULTIPLIER}
+        keyboard={false}
+        ref={swayRef}
+        wheelMode="capture"
+      >
+        <ol className="media-rail">
+          <li>Cover</li>
+          <li>Detail</li>
+          <li>Motion</li>
+        </ol>
+      </ReactSway>
+    </div>
+  );
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `handleEdgeHover(point)` | Acquires or updates external edge-hover ownership and applies depth-scaled speed. Returns `true` when an enabled, visible instance accepted the sample; the pointer may still be in the inactive center. External intent can drive motion when autonomous `autoScroll` is disabled. |
+| `handleWheel(event)` | Routes an external wheel event through Sway's wheel normalization and ownership policy. Returns `true` when Sway consumed the event. |
+| `clearEdgeHover()` | Releases external ownership, clears active edge-hover intensity, and lets the animation loop sleep when there is no momentum. |
+
+External drag owners should retain pointer capture or route global pointer coordinates while held. Use `edgeHoverInputMode="external"` when the parent interaction is the sole input authority; this prevents intrinsic pointer sensing from competing with the drag owner. Always call `clearEdgeHover` on release, cancellation, lost ownership, and unmount.
+
+`DEFAULT_EDGE_HOVER_SIZE` and `DEFAULT_EDGE_HOVER_SPEED_MULTIPLIER` are public named constants. They let application-level interaction profiles inherit the package defaults without duplicating magic numbers. `edgeHoverSize` controls activation-zone geometry; `edgeHoverSpeedMultiplier` controls bounded peak velocity. The smooth acceleration curve remains package-owned so intrinsic and externally routed input share stable motion semantics.
+
+## Runtime and accessibility contract
+
+- Duplicate loop groups are inert, `aria-hidden`, presentation-only, non-interactive, and pointer-disabled.
+- Mouse and touch global listeners are installed only during active drag gestures and are removed on release, cancel, blur, unmount, or prop changes.
+- Edge-hover mode does not continuously request animation frames while idle; it wakes when the pointer enters an edge, wheel input arrives, momentum exists, or auto-scroll resumes.
+- `wheelMode="axis"` lets cross-axis page scroll pass through. `wheelMode="capture"` intentionally lets Sway own every wheel event it receives.
+
 ## License
 
 This package is licensed under the [MIT License](../../LICENSE).

package/dist/ReactSway.d.ts

@@ -2,27 +2,69 @@
  * Core ReactSway component implementing axis-aware infinite scrolling interactions.
  */
 import { type ReactNode } from 'react';
+import { type SwayWheelMode } from './wheel-input';
+export type { SwayWheelMode } from './wheel-input';
 export type SwayAxis = 'horizontal' | 'vertical';
 export type SwayDirection = 'down' | 'left' | 'right' | 'up';
-export type SwayWheelMode = 'axis' | 'capture';
+export type SwayEdgeHoverInputMode = 'external' | 'hybrid';
+export interface ReactSwayHandle {
+    /**
+     * Routes an external pointer sample through ReactSway's edge-hover policy.
+     *
+     * This is useful when another interaction owns pointer capture but still
+     * wants ReactSway to keep its boundary scrolling semantics.
+     * Returns true when an enabled, visible instance accepted the sample. A true
+     * result does not imply motion when the pointer is in the inactive center.
+     * The first accepted sample acquires an external-input lease that survives
+     * native pointer leave; consumers must call `clearEdgeHover` on termination.
+     */
+    handleEdgeHover: (point: {
+        clientX: number;
+        clientY: number;
+    }) => boolean;
+    /**
+     * Routes an external wheel event through ReactSway's normalized wheel physics.
+     *
+     * Returns true when the event was consumed by ReactSway and false when the
+     * current wheel policy leaves the event to native scroll chaining.
+     */
+    handleWheel: (event: globalThis.WheelEvent) => boolean;
+    /** Releases external edge-hover ownership and clears active intensity. */
+    clearEdgeHover: () => void;
+}
 /**
  * Props for the ReactSway infinite scrolling component.
  */
 export interface ReactSwayProps {
+    /** Accessible name for the scrolling region. */
+    ariaLabel?: string;
     /** 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;
+    /** Additional class name applied to the semantic scrolling region. */
+    className?: string;
     /** Auto-scroll direction. @default 'up' */
     direction?: SwayDirection;
     /** Enable mouse/touch drag interaction. @default true */
     draggable?: boolean;
-    /** Only auto-scroll while the pointer hovers an axis boundary. @default false */
+    /**
+     * Selects intrinsic pointer sensing plus the imperative bridge (`hybrid`),
+     * or imperative external ownership only (`external`). @default 'hybrid'
+     */
+    edgeHoverInputMode?: SwayEdgeHoverInputMode;
+    /**
+     * Only auto-scroll while the pointer hovers an axis boundary. Active motion
+     * preserves baseline speed, then accelerates toward the visible edge.
+     * @default false
+     */
     edgeHoverScroll?: boolean;
     /** Edge-hover activation thickness in pixels. @default 96 */
     edgeHoverSize?: number;
+    /** Maximum edge-hover velocity relative to the baseline `speed`. @default 6 */
+    edgeHoverSpeedMultiplier?: number;
     /** Momentum decay coefficient (0-1, lower = more friction). @default 0.95 */
     friction?: number;
     /** Enable keyboard controls (Space, Arrow keys, Home/End). @default true */
@@ -43,7 +85,7 @@ export interface ReactSwayProps {
     pauseOnInteraction?: boolean;
     /** Milliseconds before auto-scroll resumes after interaction. @default 2000 */
     resumeDelay?: number;
-    /** Auto-scroll speed in pixels per frame at 60fps. @default 0.5 */
+    /** Baseline auto-scroll speed in pixels per frame at 60fps. @default 0.5 */
     speed?: number;
     /** Enable mouse wheel scrolling. @default true */
     wheelEnabled?: boolean;
@@ -78,5 +120,5 @@ export interface ReactSwayProps {
  * </ReactSway>
  * ```
  */
-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;
+declare const ReactSway: import("react").ForwardRefExoticComponent<ReactSwayProps & import("react").RefAttributes<ReactSwayHandle>>;
 export default ReactSway;

package/dist/edge-hover-velocity.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Defines the bounded spatial mapping from edge-hover depth to Sway velocity.
+ */
+/** Default edge-hover activation thickness in pixels. */
+export declare const DEFAULT_EDGE_HOVER_SIZE = 96;
+/** Default maximum edge-hover speed relative to the configured base speed. */
+export declare const DEFAULT_EDGE_HOVER_SPEED_MULTIPLIER = 6;
+export interface VisibleEdgeInterval {
+    end: number;
+    size: number;
+    start: number;
+}
+export declare function normalizeEdgeHoverIntensity(value: number): number;
+export declare function normalizeEdgeHoverSpeedMultiplier(value: number): number;
+/**
+ * Maps signed edge depth onto a bounded velocity scale.
+ *
+ * Intensity carries direction and lies in [-1, 1]. The speed multiplier is
+ * the maximum amplification reached one activation-zone width beyond the
+ * visible edge.
+ */
+export declare function getEdgeHoverVelocityScale(intensity: number, speedMultiplier?: number): number;
+/**
+ * Computes signed edge depth using a symmetric linear ramp.
+ *
+ * The inner edge of either activation zone maps to zero, the physical edge
+ * maps to half intensity, and motion keeps accelerating outside the viewport
+ * until it reaches the cap one activation-zone width beyond the visible edge.
+ */
+export declare function getEdgeHoverIntensity(pointerPosition: number, visibleInterval: VisibleEdgeInterval, edgeHoverSize: number): number;