react-sway 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.5.0 - 2026-11-09
+
+- Add perspective depth scrolling with toward/away directions and configurable camera distance and plane spacing.
+- Mount each depth child once and recycle only at zero opacity without crossing the camera.
+- Share wheel, drag, touch, keyboard, pause, and lifecycle behavior across all three axes.
+- Add `active` and `reducedMotion` for host lifecycle and accessibility integration; preserve React 17/18/19 and existing planar behavior.
+- Add responsive depth documentation and browser coverage, plus geometry and lifecycle regressions.
+- Make the ESM build directly importable in Node with React 17, and verify packed ESM/CJS/SSR consumers on React 17/18/19.
+- Update development dependencies and npm, test Node 22/24/26, and resolve all known dependency audit findings. Keep TypeScript 6.0.3 for ESLint parser compatibility.
+
+## 0.4.3 - 2026-10-21
+
+- Preserve browser zoom gestures, nested controls, and secondary mouse clicks.
+- Stop external edge-hover motion when edge-hover mode is disabled.
+- Preserve inert duplicate groups on React 17 and 18 as well as React 19.
+- Update the development toolchain; keep TypeScript 6 for parser compatibility.
+
 ## 0.4.0
 
 - Added horizontal and vertical axis semantics with page-safe touch behavior.

package/README.md

@@ -1,22 +1,23 @@
 # react-sway
 
-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.
+A React component for smooth, infinite, and interactive content scrolling on vertical, horizontal, or perspective depth axes, controllable via touch, mouse drag, wheel, keyboard, or edge hover. React 17, 18, and 19 are supported without runtime dependencies beyond React and React DOM.
 
 ## 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. 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 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.
+Vertical and horizontal modes duplicate content into inert `<aside>` elements with `aria-hidden="true"` and `role="presentation"`. Depth mode mounts each direct child once and recycles its 3D plane at zero opacity, keeping every plane behind the perspective camera.
 
 ### Core Features
 
-*   **Smooth Infinite Scroll:** Content loops continuously on the vertical or horizontal axis.
+*   **Smooth Infinite Scroll:** Content loops continuously on vertical, horizontal, or depth axes.
 *   **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, 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.
+    *   Mouse wheel support with axis-aware intent detection, delta-mode normalization, and velocity capping. Browser zoom gestures pass through.
+    *   Nested buttons, links, and editable fields retain their native interactions.
     *   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.
@@ -276,30 +277,66 @@ function MinimalEdgeHoverExamples() {
 }
 ```
 
+### Perspective depth scrolling
+
+```tsx
+import { ReactSway } from 'react-sway';
+
+function DepthGallery({ active = true }: { active?: boolean }) {
+  return (
+    <div className="depth-viewport">
+      <ReactSway active={active} ariaLabel="Photo gallery" axis="depth" direction="toward">
+        <img alt="Mountain landscape" className="depth-image" src="/mountain.jpg" />
+        <img alt="Modern architecture" className="depth-image depth-image-offset" src="/building.jpg" />
+        <img alt="Coastal landscape" className="depth-image" src="/coast.jpg" />
+      </ReactSway>
+    </div>
+  );
+}
+```
+
+```css
+.depth-viewport { height: 600px; overflow: hidden; position: relative; }
+.depth-image { display: block; height: 200px; max-width: none; object-fit: cover; transform: translate(-50%, -50%); width: 160px; }
+.depth-image-offset { margin-left: 50px; margin-top: -80px; width: 200px; }
+```
+
+Each **direct child** is one plane anchored at the viewport center. A fragment or a list wrapper is one plane; pass separate children for independent motion. Give children explicit sizes and use their CSS for composition, offsets, and tilt. The positioned parent supplies viewport dimensions and clipping. Keep `overflow: hidden` on that parent so the internal 3D scene retains depth.
+
+`direction="toward"` approaches the camera; `"away"` recedes. Either direction infers `axis="depth"` when the axis is omitted. `depthPerspective` defaults to 800 CSS pixels and `depthSpacing` to 420; both must be finite and positive. Invalid values use their defaults, positive values below 1 are clamped to 1, and larger values are bounded by `Number.MAX_SAFE_INTEGER`. The exported `DEFAULT_DEPTH_PERSPECTIVE` and `DEFAULT_DEPTH_SPACING` constants share those defaults.
+
+The loop period is the direct-child count times `depthSpacing`. Automatic movement and manual wheel/drag/keyboard input use the same periodic phase; vertical gestures and up/down arrows control depth. Set `autoScroll={false}` for manual exploration, or `active={false}` to suspend Sway's animation and input while preserving the current position. Empty depth scenes stay idle. Host applications can request reduced motion with `reducedMotion`; the system preference always takes precedence. Depth auto-scroll and momentum stop under reduced motion, while deliberate manual steps remain available. Existing planar loops retain their reduced speed behavior.
+
+For decorative backgrounds, disable `keyboard`, `draggable`, and `wheelEnabled`, use empty image alt text, and put stationary application controls outside the Sway region. Automatic motion should have an accessible pause control. Inspect the [live depth example](https://lafittemehdy.github.io/sway/) for a responsive composition.
+
 ## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `active` | `boolean` | `true` | Suspend Sway animation and input when false, retaining content and position. Nested native controls remain usable. |
 | `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. |
+| `axis` | `'depth' \| 'horizontal' \| 'vertical'` | Inferred from `direction`, otherwise `'vertical'` | Scroll axis; depth assigns each direct child a 3D plane. |
 | `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. |
+| `depthPerspective` | `number` | `800` | Perspective camera distance in CSS pixels, depth mode only. |
+| `depthSpacing` | `number` | `420` | Distance between consecutive depth planes in CSS pixels. |
+| `direction` | `'away' \| 'down' \| 'left' \| 'right' \| 'toward' \| 'up'` | `'up'` | `left`/`right` infer horizontal; `toward`/`away` infer depth. Explicit `axis` takes precedence. |
 | `draggable` | `boolean` | `true` | Enable mouse/touch drag interaction. |
 | `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. |
+| `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`, normalized to the inclusive `0`–`1` interval. |
+| `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. |
+| `reducedMotion` | `boolean` | `false` | Request reduced motion in addition to the OS preference. Stops depth auto-scroll and momentum. |
 | `resumeDelay` | `number` | `2000` | Milliseconds before auto-scroll resumes after interaction. |
 | `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. |
@@ -373,11 +410,12 @@ External drag owners should retain pointer capture or route global pointer coord
 
 ## Runtime and accessibility contract
 
-- Duplicate loop groups are inert, `aria-hidden`, presentation-only, non-interactive, and pointer-disabled.
+- Planar duplicate loop groups are inert, `aria-hidden`, presentation-only, non-interactive, and pointer-disabled. Depth children are never duplicated.
+- Hidden pages pause animation and resume without consuming elapsed hidden time. Inactive instances also relinquish gesture ownership and discard momentum.
 - 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).
+This package is licensed under the [MIT License](https://github.com/lafittemehdy/sway/blob/main/LICENSE).

package/dist/ReactSway.d.ts

@@ -4,8 +4,8 @@
 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 SwayAxis = 'depth' | 'horizontal' | 'vertical';
+export type SwayDirection = 'away' | 'down' | 'left' | 'right' | 'toward' | 'up';
 export type SwayEdgeHoverInputMode = 'external' | 'hybrid';
 export interface ReactSwayHandle {
     /**
@@ -36,9 +36,11 @@ export interface ReactSwayHandle {
  * Props for the ReactSway infinite scrolling component.
  */
 export interface ReactSwayProps {
+    /** Suspend Sway animation and input while keeping content and scroll position mounted. @default true */
+    active?: boolean;
     /** Accessible name for the scrolling region. */
     ariaLabel?: string;
-    /** Scroll axis. Horizontal directions imply `horizontal` when omitted. @default 'vertical' */
+    /** Scroll axis. Left/right imply horizontal; toward/away imply depth. @default 'vertical' */
     axis?: SwayAxis;
     /** Enable/disable auto-scrolling. @default true */
     autoScroll?: boolean;
@@ -46,6 +48,10 @@ export interface ReactSwayProps {
     children: ReactNode;
     /** Additional class name applied to the semantic scrolling region. */
     className?: string;
+    /** Camera distance in CSS pixels for depth mode. Invalid lengths use the default. @default 800 */
+    depthPerspective?: number;
+    /** Distance in CSS pixels between depth planes. Invalid lengths use the default. @default 420 */
+    depthSpacing?: number;
     /** Auto-scroll direction. @default 'up' */
     direction?: SwayDirection;
     /** Enable mouse/touch drag interaction. @default true */
@@ -83,6 +89,8 @@ export interface ReactSwayProps {
     onScroll?: (position: number) => void;
     /** Pause auto-scroll during user interaction. @default true */
     pauseOnInteraction?: boolean;
+    /** Request reduced motion in addition to the system preference; false never overrides the system. @default false */
+    reducedMotion?: boolean;
     /** Milliseconds before auto-scroll resumes after interaction. @default 2000 */
     resumeDelay?: number;
     /** Baseline auto-scroll speed in pixels per frame at 60fps. @default 0.5 */
@@ -106,11 +114,11 @@ export interface ReactSwayProps {
  * Renders children in a continuously looping scroll area with support for
  * 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
+ * Planar content is duplicated to create a seamless loop effect. Duplicate content
  * is wrapped in `<aside>` elements with `aria-hidden="true"` for accessibility.
  *
- * Respects `prefers-reduced-motion: reduce` by lowering auto-scroll speed
- * and disabling momentum effects.
+ * Reduced motion stops depth auto-scroll, lowers planar auto-scroll speed,
+ * and disables momentum effects.
  *
  * @example
  * ```tsx

package/dist/depth-position.d.ts

@@ -0,0 +1,9 @@
+/** Maps one scroll phase onto periodic depth planes without crossing the perspective camera. */
+export declare const DEFAULT_DEPTH_PERSPECTIVE = 800;
+export declare const DEFAULT_DEPTH_SPACING = 420;
+/** Bounds pixel lengths so periods and fade denominators remain finite and nonzero. */
+export declare function normalizeDepthLength(value: number, fallback: number): number;
+export declare function getDepthItemState(position: number, index: number, count: number, perspective?: number, spacing?: number): {
+    opacity: number;
+    z: number;
+};