react-sway 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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.

package/README.md

@@ -1,16 +1,16 @@
 # 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:**
@@ -277,16 +277,51 @@ 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. |
@@ -301,6 +336,7 @@ function MinimalEdgeHoverExamples() {
 | `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. |
@@ -374,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;
+};

package/dist/index.cjs

@@ -1,10 +1,48 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+// \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
 let react = require("react");
-let react_jsx_runtime = require("react/jsx-runtime");
-//#region src/edge-hover-velocity.ts
-/**
-* Defines the bounded spatial mapping from edge-hover depth to Sway velocity.
-*/
+react = __toESM(react, 1);
+// src/depth-position.ts
+var DEFAULT_DEPTH_PERSPECTIVE = 800;
+var DEFAULT_DEPTH_SPACING = 420;
+/** Bounds pixel lengths so periods and fade denominators remain finite and nonzero. */
+function normalizeDepthLength(value, fallback) {
+	return Number.isFinite(value) && value > 0 ? Math.min(Number.MAX_SAFE_INTEGER, Math.max(1, value)) : fallback;
+}
+function getDepthItemState(position, index, count, perspective = 800, spacing = 420) {
+	if (count <= 0) return {
+		opacity: 0,
+		z: 0
+	};
+	const period = count * spacing;
+	const phase = ((index * spacing + position) % period + period) % period;
+	const fade = Math.min(1, Math.min(phase, period - phase) / (spacing * .45));
+	return {
+		opacity: fade * fade * (3 - 2 * fade),
+		z: perspective * .7 - phase
+	};
+}
+// src/edge-hover-velocity.ts
 /** Default edge-hover activation thickness in pixels. */
 var DEFAULT_EDGE_HOVER_SIZE = 96;
 /** Default maximum edge-hover speed relative to the configured base speed. */
@@ -79,9 +117,7 @@ function getEdgeHoverIntensity(pointerPosition, visibleInterval, edgeHoverSize)
 	}
 	return 0;
 }
-//#endregion
-//#region src/wheel-input.ts
-/** Fallback pixel height for wheel events reported in line units. */
+// src/wheel-input.ts
 var WHEEL_LINE_HEIGHT_FALLBACK_PX = 16;
 /** WheelEvent deltaMode value for line-based deltas. */
 var WHEEL_MODE_LINE = 1;
@@ -128,11 +164,7 @@ function getOwnedWheelDelta(event, container, isHorizontal, wheelMode) {
 	if (wheelMode === "axis" && absDeltaX > absDeltaY) return null;
 	return deltaY;
 }
-//#endregion
-//#region src/ReactSway.tsx
-/**
-* Core ReactSway component implementing axis-aware infinite scrolling interactions.
-*/
+// src/ReactSway.tsx
 /** Velocity applied per arrow key press (pixels). */
 var ARROW_KEY_VELOCITY = 15;
 /** Default friction coefficient applied to velocity each frame. */
@@ -186,11 +218,11 @@ function getVisibleEdgeInterval(rect, isHorizontal) {
 * 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
@@ -200,8 +232,14 @@ function getVisibleEdgeInterval(rect, isHorizontal) {
 * </ReactSway>
 * ```
 */
-var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollable content", axis, autoScroll = true, children, className, direction = "up", draggable = true, edgeHoverInputMode = "hybrid", edgeHoverScroll = false, edgeHoverSize = 96, edgeHoverSpeedMultiplier = 6, friction = DEFAULT_FRICTION, keyboard = true, lazy = true, lazyRootMargin = DEFAULT_LAZY_ROOT_MARGIN, lazyThreshold = DEFAULT_LAZY_THRESHOLD, onPause, onResume, onScroll, pauseOnInteraction = true, resumeDelay = DEFAULT_RESUME_DELAY, speed = DEFAULT_SPEED, wheelEnabled = true, wheelMode = "axis" }, ref) {
-	const isHorizontal = (0, react.useMemo)(() => axis ?? (direction === "left" || direction === "right" ? "horizontal" : "vertical"), [axis, direction]) === "horizontal";
+var ReactSway = (0, react.forwardRef)(function ReactSway({ active = true, ariaLabel = "Scrollable content", axis, autoScroll = true, children, className, depthPerspective = 800, depthSpacing = 420, direction = "up", draggable = true, edgeHoverInputMode = "hybrid", edgeHoverScroll = false, edgeHoverSize = 96, edgeHoverSpeedMultiplier = 6, friction = DEFAULT_FRICTION, keyboard = true, lazy = true, lazyRootMargin = DEFAULT_LAZY_ROOT_MARGIN, lazyThreshold = DEFAULT_LAZY_THRESHOLD, onPause, onResume, onScroll, pauseOnInteraction = true, reducedMotion = false, resumeDelay = DEFAULT_RESUME_DELAY, speed = DEFAULT_SPEED, wheelEnabled = true, wheelMode = "axis" }, ref) {
+	const scrollAxis = (0, react.useMemo)(() => axis ?? (direction === "toward" || direction === "away" ? "depth" : direction === "left" || direction === "right" ? "horizontal" : "vertical"), [axis, direction]);
+	const isHorizontal = scrollAxis === "horizontal";
+	const isDepth = scrollAxis === "depth";
+	const depthChildren = (0, react.useMemo)(() => react.Children.toArray(children), [children]);
+	const enabled = active && (!isDepth || depthChildren.length > 0);
+	const normalizedDepthPerspective = normalizeDepthLength(depthPerspective, 800);
+	const normalizedDepthSpacing = normalizeDepthLength(depthSpacing, 420);
 	const normalizedEdgeHoverSize = (0, react.useMemo)(() => Number.isFinite(edgeHoverSize) ? Math.max(1, edgeHoverSize) : 96, [edgeHoverSize]);
 	const normalizedEdgeHoverSpeedMultiplier = (0, react.useMemo)(() => normalizeEdgeHoverSpeedMultiplier(edgeHoverSpeedMultiplier), [edgeHoverSpeedMultiplier]);
 	const normalizedFriction = (0, react.useMemo)(() => Number.isFinite(friction) ? Math.min(Math.max(friction, 0), 1) : DEFAULT_FRICTION, [friction]);
@@ -209,17 +247,22 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 	const normalizedResumeDelay = (0, react.useMemo)(() => Number.isFinite(resumeDelay) ? Math.max(0, resumeDelay) : DEFAULT_RESUME_DELAY, [resumeDelay]);
 	const normalizedSpeed = (0, react.useMemo)(() => Number.isFinite(speed) ? Math.max(0, speed) : DEFAULT_SPEED, [speed]);
 	const touchAction = (0, react.useMemo)(() => {
-		if (!draggable) return "auto";
+		if (!enabled || !draggable) return "auto";
 		return isHorizontal ? "pan-y" : "pan-x";
-	}, [draggable, isHorizontal]);
-	const overscrollBehavior = wheelEnabled && wheelMode === "capture" ? "contain" : "auto";
+	}, [
+		draggable,
+		enabled,
+		isHorizontal
+	]);
+	const overscrollBehavior = enabled && wheelEnabled && wheelMode === "capture" ? "contain" : "auto";
 	const [isPaused, setIsPaused] = (0, react.useState)(false);
 	const [isTabActive, setIsTabActive] = (0, react.useState)(() => typeof document === "undefined" || !document.hidden);
 	const [loopSegmentCount, setLoopSegmentCount] = (0, react.useState)(MIN_LOOP_SEGMENTS);
-	const [prefersReducedMotion, setPrefersReducedMotion] = (0, react.useState)(() => {
+	const [systemReducedMotion, setSystemReducedMotion] = (0, react.useState)(() => {
 		if (typeof window === "undefined") return false;
 		return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 	});
+	const prefersReducedMotion = systemReducedMotion || reducedMotion;
 	const animationFrameRef = (0, react.useRef)(null);
 	const animationLoopRef = (0, react.useRef)(null);
 	const autoScrollRef = (0, react.useRef)({
@@ -266,7 +309,7 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		if (typeof window === "undefined") return;
 		const mediaQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
 		const handleChange = (e) => {
-			setPrefersReducedMotion(e.matches);
+			setSystemReducedMotion(e.matches);
 		};
 		mediaQuery.addEventListener("change", handleChange);
 		return () => {
@@ -306,11 +349,28 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 	}, [isHorizontal]);
 	const renderPosition = (0, react.useCallback)((rawPosition) => {
 		if (!containerRef.current) return;
+		if (isDepth) {
+			containerRef.current.style.transform = "translate3d(0, 0, 0)";
+			const items = originalGroupRef.current?.children;
+			if (!items) return;
+			Array.from(items).forEach((item, index) => {
+				const { opacity, z } = getDepthItemState(rawPosition, index, items.length, normalizedDepthPerspective, normalizedDepthSpacing);
+				const element = item;
+				element.style.transform = `translate3d(0, 0, ${z}px)`;
+				element.style.opacity = String(opacity);
+			});
+			return;
+		}
 		const currentLoopPoint = loopPointRef.current;
 		let visualPosition = rawPosition % (currentLoopPoint || 1);
 		if (visualPosition > 0 && currentLoopPoint > 0) visualPosition -= currentLoopPoint;
 		containerRef.current.style.transform = isHorizontal ? `translate3d(${visualPosition}px, 0, 0)` : `translate3d(0, ${visualPosition}px, 0)`;
-	}, [isHorizontal]);
+	}, [
+		isDepth,
+		isHorizontal,
+		normalizedDepthPerspective,
+		normalizedDepthSpacing
+	]);
 	const commitPosition = (0, react.useCallback)((nextPosition) => {
 		if (positionRef.current === nextPosition) return;
 		positionRef.current = nextPosition;
@@ -331,11 +391,14 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 	}, [draggable]);
 	const recalculateLoopPoint = (0, react.useCallback)(() => {
 		if (!containerRef.current || !originalGroupRef.current) return;
-		const originalContentSize = isHorizontal ? originalGroupRef.current.scrollWidth : originalGroupRef.current.scrollHeight;
-		if (originalContentSize <= 0) return;
+		const originalContentSize = isDepth ? depthChildren.length * normalizedDepthSpacing : isHorizontal ? originalGroupRef.current.scrollWidth : originalGroupRef.current.scrollHeight;
+		if (originalContentSize <= 0) {
+			if (isDepth) loopPointRef.current = 0;
+			return;
+		}
 		const viewport = containerRef.current.parentElement ?? containerRef.current;
 		const viewportSize = isHorizontal ? Math.max(viewport.clientWidth, 1) : Math.max(viewport.clientHeight, 1);
-		const nextLoopSegmentCount = Math.max(MIN_LOOP_SEGMENTS, Math.ceil(viewportSize / originalContentSize) + 1);
+		const nextLoopSegmentCount = isDepth ? 1 : Math.max(MIN_LOOP_SEGMENTS, Math.ceil(viewportSize / originalContentSize) + 1);
 		const nextLoopPoint = originalContentSize;
 		const previousMeasurement = lastLoopMeasurementRef.current;
 		const nextMeasurement = {
@@ -348,7 +411,13 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		setLoopSegmentCount((previousLoopSegmentCount) => previousLoopSegmentCount === nextLoopSegmentCount ? previousLoopSegmentCount : nextLoopSegmentCount);
 		loopPointRef.current = nextLoopPoint;
 		renderPosition(positionRef.current);
-	}, [isHorizontal, renderPosition]);
+	}, [
+		depthChildren.length,
+		isDepth,
+		isHorizontal,
+		normalizedDepthSpacing,
+		renderPosition
+	]);
 	(0, react.useEffect)(() => {
 		autoScrollRef.current.desired = autoScroll;
 		if (!autoScroll) {
@@ -373,6 +442,7 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		scheduleLoopPointRecalculation();
 	}, [
 		children,
+		isDepth,
 		isHorizontal,
 		scheduleLoopPointRecalculation
 	]);
@@ -427,7 +497,14 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		touchDragListenerCleanupRef.current = null;
 	}, []);
 	const handleKeyDown = (0, react.useCallback)((e) => {
-		if (!keyboard || isInteractiveTarget(e.target)) return;
+		if (!enabled || !keyboard || isInteractiveTarget(e.target)) return;
+		const arrowDelta = isHorizontal ? e.key === "ArrowLeft" ? ARROW_KEY_VELOCITY : e.key === "ArrowRight" ? -15 : 0 : e.key === "ArrowUp" ? ARROW_KEY_VELOCITY : e.key === "ArrowDown" ? -15 : 0;
+		if (prefersReducedMotion && arrowDelta !== 0) {
+			e.preventDefault();
+			commitPosition(wrapPosition(positionRef.current + arrowDelta));
+			velocityRef.current = 0;
+			return;
+		}
 		switch (e.key) {
 			case " ":
 				e.preventDefault();
@@ -478,12 +555,15 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		startAnimationLoop();
 	}, [
 		commitPosition,
+		enabled,
 		isHorizontal,
 		keyboard,
 		pauseAutoScroll,
+		prefersReducedMotion,
 		scheduleAutoScrollResume,
 		startAnimationLoop,
-		togglePause
+		togglePause,
+		wrapPosition
 	]);
 	const handleMouseMove = (0, react.useCallback)((e) => {
 		if (!isDraggingRef.current) return;
@@ -541,7 +621,7 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		handleMouseUp
 	]);
 	const handleMouseDown = (0, react.useCallback)((e) => {
-		if (!draggable || e.button !== 0 || isInteractiveTarget(e.target)) return;
+		if (!enabled || !draggable || e.button !== 0 || isInteractiveTarget(e.target)) return;
 		e.preventDefault();
 		containerRef.current?.focus();
 		setDraggingState(true);
@@ -554,6 +634,7 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 	}, [
 		attachMouseDragListeners,
 		draggable,
+		enabled,
 		pauseAutoScroll,
 		setDraggingState,
 		startAnimationLoop
@@ -577,6 +658,7 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		if (touchInteractionStateRef.current === "idle" || touchInteractionStateRef.current === "ignored") return;
 		if (e.touches.length !== 1) return;
 		const touch = e.touches[0];
+		if (!touch) return;
 		if (touchInteractionStateRef.current === "pending") {
 			const totalDeltaX = touch.clientX - touchStartXRef.current;
 			const totalDeltaY = touch.clientY - touchStartYRef.current;
@@ -621,18 +703,24 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		handleTouchMove
 	]);
 	const handleTouchStart = (0, react.useCallback)((e) => {
-		if (!draggable || e.touches.length !== 1 || isInteractiveTarget(e.target)) return;
+		if (!enabled || !draggable || e.touches.length !== 1 || isInteractiveTarget(e.target)) return;
+		const touch = e.touches[0];
+		if (!touch) return;
 		containerRef.current?.focus();
 		touchInteractionStateRef.current = "pending";
-		lastTouchXRef.current = e.touches[0].clientX;
-		lastTouchYRef.current = e.touches[0].clientY;
-		touchStartXRef.current = e.touches[0].clientX;
-		touchStartYRef.current = e.touches[0].clientY;
+		lastTouchXRef.current = touch.clientX;
+		lastTouchYRef.current = touch.clientY;
+		touchStartXRef.current = touch.clientX;
+		touchStartYRef.current = touch.clientY;
 		velocityRef.current = 0;
 		attachTouchDragListeners();
-	}, [attachTouchDragListeners, draggable]);
+	}, [
+		attachTouchDragListeners,
+		draggable,
+		enabled
+	]);
 	const handleWheel = (0, react.useCallback)((e) => {
-		if (!wheelEnabled || e.defaultPrevented) return false;
+		if (!enabled || !wheelEnabled || e.defaultPrevented) return false;
 		const currentContainer = e.currentTarget instanceof HTMLElement ? e.currentTarget : containerRef.current;
 		if (!currentContainer) return false;
 		const ownedDelta = getOwnedWheelDelta(e, currentContainer, isHorizontal, wheelMode);
@@ -649,6 +737,7 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		return true;
 	}, [
 		commitPosition,
+		enabled,
 		isHorizontal,
 		pauseAutoScroll,
 		scheduleAutoScrollResume,
@@ -658,7 +747,7 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		wrapPosition
 	]);
 	const applyEdgeHoverPoint = (0, react.useCallback)((point) => {
-		if (!edgeHoverScroll) return false;
+		if (!enabled || !edgeHoverScroll) return false;
 		const viewport = containerRef.current?.parentElement ?? containerRef.current;
 		if (!viewport) return false;
 		const visibleInterval = readVisibleEdgeInterval(viewport);
@@ -671,6 +760,7 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		return true;
 	}, [
 		edgeHoverScroll,
+		enabled,
 		isHorizontal,
 		normalizedEdgeHoverSize,
 		readVisibleEdgeInterval,
@@ -707,7 +797,7 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 	}, [setEdgeHoverIntensity]);
 	(0, react.useEffect)(() => {
 		const currentContainer = containerRef.current;
-		if (!currentContainer) return;
+		if (!currentContainer || !enabled) return;
 		if (draggable) {
 			currentContainer.addEventListener("mousedown", handleMouseDown);
 			currentContainer.addEventListener("touchstart", handleTouchStart, { passive: true });
@@ -745,6 +835,7 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		detachMouseDragListeners,
 		detachTouchDragListeners,
 		draggable,
+		enabled,
 		edgeHoverScroll,
 		edgeHoverInputMode,
 		clearEdgeHover,
@@ -755,6 +846,24 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		handleWheel,
 		wheelEnabled
 	]);
+	(0, react.useEffect)(() => {
+		if (enabled) return;
+		clearInactivityTimer();
+		clearEdgeHover();
+		detachMouseDragListeners();
+		detachTouchDragListeners();
+		touchInteractionStateRef.current = "idle";
+		setDraggingState(false);
+		velocityRef.current = 0;
+		autoScrollRef.current.active = autoScrollRef.current.desired;
+	}, [
+		clearEdgeHover,
+		clearInactivityTimer,
+		detachMouseDragListeners,
+		detachTouchDragListeners,
+		enabled,
+		setDraggingState
+	]);
 	(0, react.useEffect)(() => {
 		window.addEventListener("resize", scheduleLoopPointRecalculation);
 		return () => {
@@ -803,7 +912,7 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		};
 	}, [clearInactivityTimer]);
 	(0, react.useEffect)(() => {
-		if (!isTabActive || isPaused) {
+		if (!enabled || !isTabActive || isPaused) {
 			if (animationFrameRef.current !== null) {
 				cancelAnimationFrame(animationFrameRef.current);
 				animationFrameRef.current = null;
@@ -812,7 +921,7 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 			return;
 		}
 		lastFrameTimeRef.current = 0;
-		const directionMultiplier = direction === "down" || direction === "right" ? 1 : -1;
+		const directionMultiplier = direction === "away" || direction === "down" || direction === "right" ? 1 : -1;
 		const animate = (currentTime) => {
 			let deltaTime = lastFrameTimeRef.current ? (currentTime - lastFrameTimeRef.current) / MS_PER_FRAME_60FPS : 1;
 			deltaTime = Math.min(deltaTime, MAX_DELTA_TIME);
@@ -823,7 +932,7 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 			let nextPosition = positionRef.current;
 			const effectiveSpeed = prefersReducedMotion ? normalizedSpeed * REDUCED_MOTION_SPEED_FACTOR : normalizedSpeed;
 			const edgeHoverMultiplier = edgeHoverScroll ? getEdgeHoverVelocityScale(edgeHoverIntensityRef.current, normalizedEdgeHoverSpeedMultiplier) : directionMultiplier;
-			const shouldAutoScroll = (autoScrollRef.current.desired && autoScrollRef.current.active || externalEdgeHoverLeaseRef.current) && !isDraggingRef.current && (!edgeHoverScroll || edgeHoverMultiplier !== 0);
+			const shouldAutoScroll = (autoScrollRef.current.desired && autoScrollRef.current.active || externalEdgeHoverLeaseRef.current) && !isDraggingRef.current && !(isDepth && prefersReducedMotion) && (!edgeHoverScroll || edgeHoverMultiplier !== 0);
 			if (shouldAutoScroll) {
 				const autoScrollDeltaTime = edgeHoverScroll ? Math.min(deltaTime, MAX_EDGE_HOVER_DELTA_TIME) : deltaTime;
 				nextPosition += edgeHoverMultiplier * effectiveSpeed * autoScrollDeltaTime;
@@ -852,6 +961,8 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		commitPosition,
 		direction,
 		edgeHoverScroll,
+		enabled,
+		isDepth,
 		isPaused,
 		isTabActive,
 		normalizedFriction,
@@ -884,56 +995,77 @@ var ReactSway = (0, react.forwardRef)(function ReactSway({ ariaLabel = "Scrollab
 		lazyRootMargin,
 		normalizedLazyThreshold
 	]);
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", {
+	return /* @__PURE__ */ react.default.createElement("section", {
 		"aria-label": ariaLabel,
 		className: `react-sway-container scroller-content${className ? ` ${className}` : ""}`,
 		ref: containerRef,
 		style: {
-			cursor: draggable ? isDraggingRef.current ? "grabbing" : "grab" : "default",
+			cursor: enabled && draggable ? isDraggingRef.current ? "grabbing" : "grab" : "default",
 			display: isHorizontal ? "flex" : void 0,
 			flexDirection: isHorizontal ? "row" : void 0,
-			height: isHorizontal ? "100%" : "max-content",
+			height: isHorizontal || isDepth ? "100%" : "max-content",
 			MozUserSelect: "none",
 			msUserSelect: "none",
 			minHeight: isHorizontal ? void 0 : "100%",
-			overflow: "hidden",
+			overflow: isDepth ? "visible" : "hidden",
+			perspective: isDepth ? normalizedDepthPerspective : void 0,
 			overscrollBehavior,
 			pointerEvents: "auto",
 			position: "absolute",
 			touchAction,
 			transform: "translate3d(0, 0, 0)",
+			transformStyle: isDepth ? "preserve-3d" : void 0,
 			userSelect: "none",
 			WebkitUserSelect: "none",
 			width: isHorizontal ? "max-content" : "100%",
-			willChange: "transform",
+			willChange: isDepth ? void 0 : "transform",
 			zIndex: 1
 		},
 		onKeyDown: keyboard ? handleKeyDown : void 0,
-		tabIndex: keyboard ? 0 : void 0,
-		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-			className: "content-group original",
-			ref: originalGroupRef,
-			style: isHorizontal ? {
-				display: "flex",
-				flex: "0 0 auto"
-			} : void 0,
-			children
-		}), Array.from({ length: loopSegmentCount - 1 }, (_, duplicateIndex) => /* @__PURE__ */ (0, react.createElement)("aside", {
-			"aria-hidden": "true",
-			className: "content-group duplicate",
-			"data-duplicate": "true",
-			...INERT_ATTRIBUTE,
-			key: `duplicate-${duplicateIndex}`,
-			role: "presentation",
-			style: isHorizontal ? {
-				display: "flex",
-				flex: "0 0 auto",
-				pointerEvents: "none"
-			} : { pointerEvents: "none" }
-		}, children))]
-	});
+		tabIndex: enabled && keyboard ? 0 : void 0
+	}, /* @__PURE__ */ react.default.createElement("div", {
+		className: "content-group original",
+		ref: originalGroupRef,
+		style: isDepth ? {
+			height: "100%",
+			position: "relative",
+			transformStyle: "preserve-3d"
+		} : isHorizontal ? {
+			display: "flex",
+			flex: "0 0 auto"
+		} : void 0
+	}, isDepth ? depthChildren.map((child, index) => {
+		const { opacity, z } = getDepthItemState(0, index, depthChildren.length, normalizedDepthPerspective, normalizedDepthSpacing);
+		return /* @__PURE__ */ react.default.createElement("div", {
+			className: "react-sway-depth-item",
+			key: typeof child === "object" && "key" in child ? child.key : index,
+			style: {
+				height: 0,
+				left: "50%",
+				opacity,
+				position: "absolute",
+				top: "50%",
+				transform: `translate3d(0, 0, ${z}px)`,
+				width: 0,
+				willChange: "transform, opacity"
+			}
+		}, child);
+	}) : children), Array.from({ length: isDepth ? 0 : loopSegmentCount - 1 }, (_, duplicateIndex) => /* @__PURE__ */ react.default.createElement("aside", {
+		"aria-hidden": "true",
+		className: "content-group duplicate",
+		"data-duplicate": "true",
+		...INERT_ATTRIBUTE,
+		key: `duplicate-${duplicateIndex}`,
+		role: "presentation",
+		style: isHorizontal ? {
+			display: "flex",
+			flex: "0 0 auto",
+			pointerEvents: "none"
+		} : { pointerEvents: "none" }
+	}, children)));
 });
-//#endregion
+exports.DEFAULT_DEPTH_PERSPECTIVE = DEFAULT_DEPTH_PERSPECTIVE;
+exports.DEFAULT_DEPTH_SPACING = DEFAULT_DEPTH_SPACING;
 exports.DEFAULT_EDGE_HOVER_SIZE = DEFAULT_EDGE_HOVER_SIZE;
 exports.DEFAULT_EDGE_HOVER_SPEED_MULTIPLIER = DEFAULT_EDGE_HOVER_SPEED_MULTIPLIER;
 exports.ReactSway = ReactSway;

package/dist/index.d.ts

@@ -2,5 +2,6 @@
  * Public package entrypoint for ReactSway exports.
  */
 export { default as ReactSway } from './ReactSway';
+export { DEFAULT_DEPTH_PERSPECTIVE, DEFAULT_DEPTH_SPACING, } from './depth-position';
 export { DEFAULT_EDGE_HOVER_SIZE, DEFAULT_EDGE_HOVER_SPEED_MULTIPLIER, } from './edge-hover-velocity';
 export type { ReactSwayHandle, ReactSwayProps, SwayAxis, SwayDirection, SwayEdgeHoverInputMode, SwayWheelMode, } from './ReactSway';

package/dist/index.js

@@ -1,9 +1,25 @@
-import { createElement, forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState, version } from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
-//#region src/edge-hover-velocity.ts
-/**
-* Defines the bounded spatial mapping from edge-hover depth to Sway velocity.
-*/
+import React, { Children, forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState, version } from "react";
+// src/depth-position.ts
+var DEFAULT_DEPTH_PERSPECTIVE = 800;
+var DEFAULT_DEPTH_SPACING = 420;
+/** Bounds pixel lengths so periods and fade denominators remain finite and nonzero. */
+function normalizeDepthLength(value, fallback) {
+	return Number.isFinite(value) && value > 0 ? Math.min(Number.MAX_SAFE_INTEGER, Math.max(1, value)) : fallback;
+}
+function getDepthItemState(position, index, count, perspective = 800, spacing = 420) {
+	if (count <= 0) return {
+		opacity: 0,
+		z: 0
+	};
+	const period = count * spacing;
+	const phase = ((index * spacing + position) % period + period) % period;
+	const fade = Math.min(1, Math.min(phase, period - phase) / (spacing * .45));
+	return {
+		opacity: fade * fade * (3 - 2 * fade),
+		z: perspective * .7 - phase
+	};
+}
+// src/edge-hover-velocity.ts
 /** Default edge-hover activation thickness in pixels. */
 var DEFAULT_EDGE_HOVER_SIZE = 96;
 /** Default maximum edge-hover speed relative to the configured base speed. */
@@ -78,9 +94,7 @@ function getEdgeHoverIntensity(pointerPosition, visibleInterval, edgeHoverSize)
 	}
 	return 0;
 }
-//#endregion
-//#region src/wheel-input.ts
-/** Fallback pixel height for wheel events reported in line units. */
+// src/wheel-input.ts
 var WHEEL_LINE_HEIGHT_FALLBACK_PX = 16;
 /** WheelEvent deltaMode value for line-based deltas. */
 var WHEEL_MODE_LINE = 1;
@@ -127,11 +141,7 @@ function getOwnedWheelDelta(event, container, isHorizontal, wheelMode) {
 	if (wheelMode === "axis" && absDeltaX > absDeltaY) return null;
 	return deltaY;
 }
-//#endregion
-//#region src/ReactSway.tsx
-/**
-* Core ReactSway component implementing axis-aware infinite scrolling interactions.
-*/
+// src/ReactSway.tsx
 /** Velocity applied per arrow key press (pixels). */
 var ARROW_KEY_VELOCITY = 15;
 /** Default friction coefficient applied to velocity each frame. */
@@ -185,11 +195,11 @@ function getVisibleEdgeInterval(rect, isHorizontal) {
 * 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
@@ -199,8 +209,14 @@ function getVisibleEdgeInterval(rect, isHorizontal) {
 * </ReactSway>
 * ```
 */
-var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content", axis, autoScroll = true, children, className, direction = "up", draggable = true, edgeHoverInputMode = "hybrid", edgeHoverScroll = false, edgeHoverSize = 96, edgeHoverSpeedMultiplier = 6, friction = DEFAULT_FRICTION, keyboard = true, lazy = true, lazyRootMargin = DEFAULT_LAZY_ROOT_MARGIN, lazyThreshold = DEFAULT_LAZY_THRESHOLD, onPause, onResume, onScroll, pauseOnInteraction = true, resumeDelay = DEFAULT_RESUME_DELAY, speed = DEFAULT_SPEED, wheelEnabled = true, wheelMode = "axis" }, ref) {
-	const isHorizontal = useMemo(() => axis ?? (direction === "left" || direction === "right" ? "horizontal" : "vertical"), [axis, direction]) === "horizontal";
+var ReactSway = forwardRef(function ReactSway({ active = true, ariaLabel = "Scrollable content", axis, autoScroll = true, children, className, depthPerspective = 800, depthSpacing = 420, direction = "up", draggable = true, edgeHoverInputMode = "hybrid", edgeHoverScroll = false, edgeHoverSize = 96, edgeHoverSpeedMultiplier = 6, friction = DEFAULT_FRICTION, keyboard = true, lazy = true, lazyRootMargin = DEFAULT_LAZY_ROOT_MARGIN, lazyThreshold = DEFAULT_LAZY_THRESHOLD, onPause, onResume, onScroll, pauseOnInteraction = true, reducedMotion = false, resumeDelay = DEFAULT_RESUME_DELAY, speed = DEFAULT_SPEED, wheelEnabled = true, wheelMode = "axis" }, ref) {
+	const scrollAxis = useMemo(() => axis ?? (direction === "toward" || direction === "away" ? "depth" : direction === "left" || direction === "right" ? "horizontal" : "vertical"), [axis, direction]);
+	const isHorizontal = scrollAxis === "horizontal";
+	const isDepth = scrollAxis === "depth";
+	const depthChildren = useMemo(() => Children.toArray(children), [children]);
+	const enabled = active && (!isDepth || depthChildren.length > 0);
+	const normalizedDepthPerspective = normalizeDepthLength(depthPerspective, 800);
+	const normalizedDepthSpacing = normalizeDepthLength(depthSpacing, 420);
 	const normalizedEdgeHoverSize = useMemo(() => Number.isFinite(edgeHoverSize) ? Math.max(1, edgeHoverSize) : 96, [edgeHoverSize]);
 	const normalizedEdgeHoverSpeedMultiplier = useMemo(() => normalizeEdgeHoverSpeedMultiplier(edgeHoverSpeedMultiplier), [edgeHoverSpeedMultiplier]);
 	const normalizedFriction = useMemo(() => Number.isFinite(friction) ? Math.min(Math.max(friction, 0), 1) : DEFAULT_FRICTION, [friction]);
@@ -208,17 +224,22 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 	const normalizedResumeDelay = useMemo(() => Number.isFinite(resumeDelay) ? Math.max(0, resumeDelay) : DEFAULT_RESUME_DELAY, [resumeDelay]);
 	const normalizedSpeed = useMemo(() => Number.isFinite(speed) ? Math.max(0, speed) : DEFAULT_SPEED, [speed]);
 	const touchAction = useMemo(() => {
-		if (!draggable) return "auto";
+		if (!enabled || !draggable) return "auto";
 		return isHorizontal ? "pan-y" : "pan-x";
-	}, [draggable, isHorizontal]);
-	const overscrollBehavior = wheelEnabled && wheelMode === "capture" ? "contain" : "auto";
+	}, [
+		draggable,
+		enabled,
+		isHorizontal
+	]);
+	const overscrollBehavior = enabled && wheelEnabled && wheelMode === "capture" ? "contain" : "auto";
 	const [isPaused, setIsPaused] = useState(false);
 	const [isTabActive, setIsTabActive] = useState(() => typeof document === "undefined" || !document.hidden);
 	const [loopSegmentCount, setLoopSegmentCount] = useState(MIN_LOOP_SEGMENTS);
-	const [prefersReducedMotion, setPrefersReducedMotion] = useState(() => {
+	const [systemReducedMotion, setSystemReducedMotion] = useState(() => {
 		if (typeof window === "undefined") return false;
 		return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 	});
+	const prefersReducedMotion = systemReducedMotion || reducedMotion;
 	const animationFrameRef = useRef(null);
 	const animationLoopRef = useRef(null);
 	const autoScrollRef = useRef({
@@ -265,7 +286,7 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		if (typeof window === "undefined") return;
 		const mediaQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
 		const handleChange = (e) => {
-			setPrefersReducedMotion(e.matches);
+			setSystemReducedMotion(e.matches);
 		};
 		mediaQuery.addEventListener("change", handleChange);
 		return () => {
@@ -305,11 +326,28 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 	}, [isHorizontal]);
 	const renderPosition = useCallback((rawPosition) => {
 		if (!containerRef.current) return;
+		if (isDepth) {
+			containerRef.current.style.transform = "translate3d(0, 0, 0)";
+			const items = originalGroupRef.current?.children;
+			if (!items) return;
+			Array.from(items).forEach((item, index) => {
+				const { opacity, z } = getDepthItemState(rawPosition, index, items.length, normalizedDepthPerspective, normalizedDepthSpacing);
+				const element = item;
+				element.style.transform = `translate3d(0, 0, ${z}px)`;
+				element.style.opacity = String(opacity);
+			});
+			return;
+		}
 		const currentLoopPoint = loopPointRef.current;
 		let visualPosition = rawPosition % (currentLoopPoint || 1);
 		if (visualPosition > 0 && currentLoopPoint > 0) visualPosition -= currentLoopPoint;
 		containerRef.current.style.transform = isHorizontal ? `translate3d(${visualPosition}px, 0, 0)` : `translate3d(0, ${visualPosition}px, 0)`;
-	}, [isHorizontal]);
+	}, [
+		isDepth,
+		isHorizontal,
+		normalizedDepthPerspective,
+		normalizedDepthSpacing
+	]);
 	const commitPosition = useCallback((nextPosition) => {
 		if (positionRef.current === nextPosition) return;
 		positionRef.current = nextPosition;
@@ -330,11 +368,14 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 	}, [draggable]);
 	const recalculateLoopPoint = useCallback(() => {
 		if (!containerRef.current || !originalGroupRef.current) return;
-		const originalContentSize = isHorizontal ? originalGroupRef.current.scrollWidth : originalGroupRef.current.scrollHeight;
-		if (originalContentSize <= 0) return;
+		const originalContentSize = isDepth ? depthChildren.length * normalizedDepthSpacing : isHorizontal ? originalGroupRef.current.scrollWidth : originalGroupRef.current.scrollHeight;
+		if (originalContentSize <= 0) {
+			if (isDepth) loopPointRef.current = 0;
+			return;
+		}
 		const viewport = containerRef.current.parentElement ?? containerRef.current;
 		const viewportSize = isHorizontal ? Math.max(viewport.clientWidth, 1) : Math.max(viewport.clientHeight, 1);
-		const nextLoopSegmentCount = Math.max(MIN_LOOP_SEGMENTS, Math.ceil(viewportSize / originalContentSize) + 1);
+		const nextLoopSegmentCount = isDepth ? 1 : Math.max(MIN_LOOP_SEGMENTS, Math.ceil(viewportSize / originalContentSize) + 1);
 		const nextLoopPoint = originalContentSize;
 		const previousMeasurement = lastLoopMeasurementRef.current;
 		const nextMeasurement = {
@@ -347,7 +388,13 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		setLoopSegmentCount((previousLoopSegmentCount) => previousLoopSegmentCount === nextLoopSegmentCount ? previousLoopSegmentCount : nextLoopSegmentCount);
 		loopPointRef.current = nextLoopPoint;
 		renderPosition(positionRef.current);
-	}, [isHorizontal, renderPosition]);
+	}, [
+		depthChildren.length,
+		isDepth,
+		isHorizontal,
+		normalizedDepthSpacing,
+		renderPosition
+	]);
 	useEffect(() => {
 		autoScrollRef.current.desired = autoScroll;
 		if (!autoScroll) {
@@ -372,6 +419,7 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		scheduleLoopPointRecalculation();
 	}, [
 		children,
+		isDepth,
 		isHorizontal,
 		scheduleLoopPointRecalculation
 	]);
@@ -426,7 +474,14 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		touchDragListenerCleanupRef.current = null;
 	}, []);
 	const handleKeyDown = useCallback((e) => {
-		if (!keyboard || isInteractiveTarget(e.target)) return;
+		if (!enabled || !keyboard || isInteractiveTarget(e.target)) return;
+		const arrowDelta = isHorizontal ? e.key === "ArrowLeft" ? ARROW_KEY_VELOCITY : e.key === "ArrowRight" ? -15 : 0 : e.key === "ArrowUp" ? ARROW_KEY_VELOCITY : e.key === "ArrowDown" ? -15 : 0;
+		if (prefersReducedMotion && arrowDelta !== 0) {
+			e.preventDefault();
+			commitPosition(wrapPosition(positionRef.current + arrowDelta));
+			velocityRef.current = 0;
+			return;
+		}
 		switch (e.key) {
 			case " ":
 				e.preventDefault();
@@ -477,12 +532,15 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		startAnimationLoop();
 	}, [
 		commitPosition,
+		enabled,
 		isHorizontal,
 		keyboard,
 		pauseAutoScroll,
+		prefersReducedMotion,
 		scheduleAutoScrollResume,
 		startAnimationLoop,
-		togglePause
+		togglePause,
+		wrapPosition
 	]);
 	const handleMouseMove = useCallback((e) => {
 		if (!isDraggingRef.current) return;
@@ -540,7 +598,7 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		handleMouseUp
 	]);
 	const handleMouseDown = useCallback((e) => {
-		if (!draggable || e.button !== 0 || isInteractiveTarget(e.target)) return;
+		if (!enabled || !draggable || e.button !== 0 || isInteractiveTarget(e.target)) return;
 		e.preventDefault();
 		containerRef.current?.focus();
 		setDraggingState(true);
@@ -553,6 +611,7 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 	}, [
 		attachMouseDragListeners,
 		draggable,
+		enabled,
 		pauseAutoScroll,
 		setDraggingState,
 		startAnimationLoop
@@ -576,6 +635,7 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		if (touchInteractionStateRef.current === "idle" || touchInteractionStateRef.current === "ignored") return;
 		if (e.touches.length !== 1) return;
 		const touch = e.touches[0];
+		if (!touch) return;
 		if (touchInteractionStateRef.current === "pending") {
 			const totalDeltaX = touch.clientX - touchStartXRef.current;
 			const totalDeltaY = touch.clientY - touchStartYRef.current;
@@ -620,18 +680,24 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		handleTouchMove
 	]);
 	const handleTouchStart = useCallback((e) => {
-		if (!draggable || e.touches.length !== 1 || isInteractiveTarget(e.target)) return;
+		if (!enabled || !draggable || e.touches.length !== 1 || isInteractiveTarget(e.target)) return;
+		const touch = e.touches[0];
+		if (!touch) return;
 		containerRef.current?.focus();
 		touchInteractionStateRef.current = "pending";
-		lastTouchXRef.current = e.touches[0].clientX;
-		lastTouchYRef.current = e.touches[0].clientY;
-		touchStartXRef.current = e.touches[0].clientX;
-		touchStartYRef.current = e.touches[0].clientY;
+		lastTouchXRef.current = touch.clientX;
+		lastTouchYRef.current = touch.clientY;
+		touchStartXRef.current = touch.clientX;
+		touchStartYRef.current = touch.clientY;
 		velocityRef.current = 0;
 		attachTouchDragListeners();
-	}, [attachTouchDragListeners, draggable]);
+	}, [
+		attachTouchDragListeners,
+		draggable,
+		enabled
+	]);
 	const handleWheel = useCallback((e) => {
-		if (!wheelEnabled || e.defaultPrevented) return false;
+		if (!enabled || !wheelEnabled || e.defaultPrevented) return false;
 		const currentContainer = e.currentTarget instanceof HTMLElement ? e.currentTarget : containerRef.current;
 		if (!currentContainer) return false;
 		const ownedDelta = getOwnedWheelDelta(e, currentContainer, isHorizontal, wheelMode);
@@ -648,6 +714,7 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		return true;
 	}, [
 		commitPosition,
+		enabled,
 		isHorizontal,
 		pauseAutoScroll,
 		scheduleAutoScrollResume,
@@ -657,7 +724,7 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		wrapPosition
 	]);
 	const applyEdgeHoverPoint = useCallback((point) => {
-		if (!edgeHoverScroll) return false;
+		if (!enabled || !edgeHoverScroll) return false;
 		const viewport = containerRef.current?.parentElement ?? containerRef.current;
 		if (!viewport) return false;
 		const visibleInterval = readVisibleEdgeInterval(viewport);
@@ -670,6 +737,7 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		return true;
 	}, [
 		edgeHoverScroll,
+		enabled,
 		isHorizontal,
 		normalizedEdgeHoverSize,
 		readVisibleEdgeInterval,
@@ -706,7 +774,7 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 	}, [setEdgeHoverIntensity]);
 	useEffect(() => {
 		const currentContainer = containerRef.current;
-		if (!currentContainer) return;
+		if (!currentContainer || !enabled) return;
 		if (draggable) {
 			currentContainer.addEventListener("mousedown", handleMouseDown);
 			currentContainer.addEventListener("touchstart", handleTouchStart, { passive: true });
@@ -744,6 +812,7 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		detachMouseDragListeners,
 		detachTouchDragListeners,
 		draggable,
+		enabled,
 		edgeHoverScroll,
 		edgeHoverInputMode,
 		clearEdgeHover,
@@ -754,6 +823,24 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		handleWheel,
 		wheelEnabled
 	]);
+	useEffect(() => {
+		if (enabled) return;
+		clearInactivityTimer();
+		clearEdgeHover();
+		detachMouseDragListeners();
+		detachTouchDragListeners();
+		touchInteractionStateRef.current = "idle";
+		setDraggingState(false);
+		velocityRef.current = 0;
+		autoScrollRef.current.active = autoScrollRef.current.desired;
+	}, [
+		clearEdgeHover,
+		clearInactivityTimer,
+		detachMouseDragListeners,
+		detachTouchDragListeners,
+		enabled,
+		setDraggingState
+	]);
 	useEffect(() => {
 		window.addEventListener("resize", scheduleLoopPointRecalculation);
 		return () => {
@@ -802,7 +889,7 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		};
 	}, [clearInactivityTimer]);
 	useEffect(() => {
-		if (!isTabActive || isPaused) {
+		if (!enabled || !isTabActive || isPaused) {
 			if (animationFrameRef.current !== null) {
 				cancelAnimationFrame(animationFrameRef.current);
 				animationFrameRef.current = null;
@@ -811,7 +898,7 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 			return;
 		}
 		lastFrameTimeRef.current = 0;
-		const directionMultiplier = direction === "down" || direction === "right" ? 1 : -1;
+		const directionMultiplier = direction === "away" || direction === "down" || direction === "right" ? 1 : -1;
 		const animate = (currentTime) => {
 			let deltaTime = lastFrameTimeRef.current ? (currentTime - lastFrameTimeRef.current) / MS_PER_FRAME_60FPS : 1;
 			deltaTime = Math.min(deltaTime, MAX_DELTA_TIME);
@@ -822,7 +909,7 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 			let nextPosition = positionRef.current;
 			const effectiveSpeed = prefersReducedMotion ? normalizedSpeed * REDUCED_MOTION_SPEED_FACTOR : normalizedSpeed;
 			const edgeHoverMultiplier = edgeHoverScroll ? getEdgeHoverVelocityScale(edgeHoverIntensityRef.current, normalizedEdgeHoverSpeedMultiplier) : directionMultiplier;
-			const shouldAutoScroll = (autoScrollRef.current.desired && autoScrollRef.current.active || externalEdgeHoverLeaseRef.current) && !isDraggingRef.current && (!edgeHoverScroll || edgeHoverMultiplier !== 0);
+			const shouldAutoScroll = (autoScrollRef.current.desired && autoScrollRef.current.active || externalEdgeHoverLeaseRef.current) && !isDraggingRef.current && !(isDepth && prefersReducedMotion) && (!edgeHoverScroll || edgeHoverMultiplier !== 0);
 			if (shouldAutoScroll) {
 				const autoScrollDeltaTime = edgeHoverScroll ? Math.min(deltaTime, MAX_EDGE_HOVER_DELTA_TIME) : deltaTime;
 				nextPosition += edgeHoverMultiplier * effectiveSpeed * autoScrollDeltaTime;
@@ -851,6 +938,8 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		commitPosition,
 		direction,
 		edgeHoverScroll,
+		enabled,
+		isDepth,
 		isPaused,
 		isTabActive,
 		normalizedFriction,
@@ -883,54 +972,73 @@ var ReactSway = forwardRef(function ReactSway({ ariaLabel = "Scrollable content"
 		lazyRootMargin,
 		normalizedLazyThreshold
 	]);
-	return /* @__PURE__ */ jsxs("section", {
+	return /* @__PURE__ */ React.createElement("section", {
 		"aria-label": ariaLabel,
 		className: `react-sway-container scroller-content${className ? ` ${className}` : ""}`,
 		ref: containerRef,
 		style: {
-			cursor: draggable ? isDraggingRef.current ? "grabbing" : "grab" : "default",
+			cursor: enabled && draggable ? isDraggingRef.current ? "grabbing" : "grab" : "default",
 			display: isHorizontal ? "flex" : void 0,
 			flexDirection: isHorizontal ? "row" : void 0,
-			height: isHorizontal ? "100%" : "max-content",
+			height: isHorizontal || isDepth ? "100%" : "max-content",
 			MozUserSelect: "none",
 			msUserSelect: "none",
 			minHeight: isHorizontal ? void 0 : "100%",
-			overflow: "hidden",
+			overflow: isDepth ? "visible" : "hidden",
+			perspective: isDepth ? normalizedDepthPerspective : void 0,
 			overscrollBehavior,
 			pointerEvents: "auto",
 			position: "absolute",
 			touchAction,
 			transform: "translate3d(0, 0, 0)",
+			transformStyle: isDepth ? "preserve-3d" : void 0,
 			userSelect: "none",
 			WebkitUserSelect: "none",
 			width: isHorizontal ? "max-content" : "100%",
-			willChange: "transform",
+			willChange: isDepth ? void 0 : "transform",
 			zIndex: 1
 		},
 		onKeyDown: keyboard ? handleKeyDown : void 0,
-		tabIndex: keyboard ? 0 : void 0,
-		children: [/* @__PURE__ */ jsx("div", {
-			className: "content-group original",
-			ref: originalGroupRef,
-			style: isHorizontal ? {
-				display: "flex",
-				flex: "0 0 auto"
-			} : void 0,
-			children
-		}), Array.from({ length: loopSegmentCount - 1 }, (_, duplicateIndex) => /* @__PURE__ */ createElement("aside", {
-			"aria-hidden": "true",
-			className: "content-group duplicate",
-			"data-duplicate": "true",
-			...INERT_ATTRIBUTE,
-			key: `duplicate-${duplicateIndex}`,
-			role: "presentation",
-			style: isHorizontal ? {
-				display: "flex",
-				flex: "0 0 auto",
-				pointerEvents: "none"
-			} : { pointerEvents: "none" }
-		}, children))]
-	});
+		tabIndex: enabled && keyboard ? 0 : void 0
+	}, /* @__PURE__ */ React.createElement("div", {
+		className: "content-group original",
+		ref: originalGroupRef,
+		style: isDepth ? {
+			height: "100%",
+			position: "relative",
+			transformStyle: "preserve-3d"
+		} : isHorizontal ? {
+			display: "flex",
+			flex: "0 0 auto"
+		} : void 0
+	}, isDepth ? depthChildren.map((child, index) => {
+		const { opacity, z } = getDepthItemState(0, index, depthChildren.length, normalizedDepthPerspective, normalizedDepthSpacing);
+		return /* @__PURE__ */ React.createElement("div", {
+			className: "react-sway-depth-item",
+			key: typeof child === "object" && "key" in child ? child.key : index,
+			style: {
+				height: 0,
+				left: "50%",
+				opacity,
+				position: "absolute",
+				top: "50%",
+				transform: `translate3d(0, 0, ${z}px)`,
+				width: 0,
+				willChange: "transform, opacity"
+			}
+		}, child);
+	}) : children), Array.from({ length: isDepth ? 0 : loopSegmentCount - 1 }, (_, duplicateIndex) => /* @__PURE__ */ React.createElement("aside", {
+		"aria-hidden": "true",
+		className: "content-group duplicate",
+		"data-duplicate": "true",
+		...INERT_ATTRIBUTE,
+		key: `duplicate-${duplicateIndex}`,
+		role: "presentation",
+		style: isHorizontal ? {
+			display: "flex",
+			flex: "0 0 auto",
+			pointerEvents: "none"
+		} : { pointerEvents: "none" }
+	}, children)));
 });
-//#endregion
-export { DEFAULT_EDGE_HOVER_SIZE, DEFAULT_EDGE_HOVER_SPEED_MULTIPLIER, ReactSway };
+export { DEFAULT_DEPTH_PERSPECTIVE, DEFAULT_DEPTH_SPACING, DEFAULT_EDGE_HOVER_SIZE, DEFAULT_EDGE_HOVER_SPEED_MULTIPLIER, ReactSway };

package/package.json

@@ -6,7 +6,7 @@
   "bugs": {
     "url": "https://github.com/lafittemehdy/sway/issues"
   },
-  "description": "A React component for smooth infinite scrolling, designed for creating engaging, continuous content streams with minimal configuration.",
+  "description": "Infinite horizontal, vertical, and perspective depth scrolling for React, with automatic motion and accessible manual interactions.",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -20,14 +20,14 @@
     "@testing-library/react": "^16.3.3",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
-    "eslint": "^10.13.0",
+    "eslint": "^10.14.0",
     "eslint-plugin-react-hooks": "^7.1.1",
-    "jsdom": "^30.1.3",
+    "jsdom": "^31.0.0",
     "react": "^19.3.1",
     "react-dom": "^19.3.1",
-    "typescript": "^6.0.3",
-    "vite": "^8.3.4",
-    "vitest": "^5.0.5"
+    "typescript": "~6.0.3",
+    "vite": "^8.3.6",
+    "vitest": "^5.1.0"
   },
   "files": [
     "CHANGELOG.md",
@@ -37,9 +37,11 @@
   "keywords": [
     "content-stream",
     "continuous-scroll",
+    "depth-scroll",
     "frontend",
     "infinite-scroll",
     "javascript",
+    "perspective",
     "react",
     "react-component",
     "scroller",
@@ -74,5 +76,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.4.3"
+  "version": "0.5.0"
 }