@multiplatform.one/components 6.1.0 → 6.4.0

package/src/Wheel/index.tsx

@@ -1,7 +1,862 @@
-export {
-  Wheel,
-  type WheelProps,
-  type WheelItem,
-  type WheelContainerProps,
-  type WheelItemProps,
-} from "@multiplatform.one/forms";
+import type { ReactNode } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import type { GetProps, SizeTokens } from "tamagui";
+import { View, getTokens, isWeb, styled, Text } from "tamagui";
+
+// ── Types ─────────────────────────────────────────────────────
+
+export interface WheelItem<T = string | number> {
+  value: T;
+  label?: string;
+}
+
+export interface WheelProps<T = string | number> {
+  /** Array of items to display */
+  items: (T | WheelItem<T>)[];
+  /** Currently selected value */
+  value?: T;
+  /** Called when selection changes */
+  onChange?: (value: T) => void;
+  /** Number of visible items (should be odd for center alignment) */
+  visibleItems?: 3 | 5 | 7;
+  /** Height of each item */
+  itemHeight?: number;
+  /** Custom render function for items */
+  renderItem?: (item: T, index: number, isSelected: boolean) => ReactNode;
+  /** Whether the wheel is disabled */
+  disabled?: boolean;
+  /** Size token for text */
+  size?: SizeTokens;
+  /**
+   * When true (and there are at least 2 items), scrolling wraps at the ends
+   * instead of rubber-banding. Uses virtual rows with modulo item indexing.
+   */
+  loop?: boolean;
+  /** Accessible name for the picker (web renders role="slider"). */
+  "aria-label"?: string;
+}
+
+// ── iOS Physics Constants ─────────────────────────────────────
+// Based on Apple's UIScrollView deceleration behavior
+
+const friction = 0.95; // Apple's PKScrollViewDecelerationFrictionFactor
+const minVelocity = 0.5; // Minimum velocity before snapping
+const momentumMultiplier = 0.8; // Velocity multiplier for momentum feel
+const rubberBandConstant = 0.55; // Apple's rubber-banding constant
+
+/** Durations for discrete snaps (mirrors theme animationConfig). */
+const transitionDurationsMs: Record<string, number> = {
+  bouncy: 200,
+  lazy: 600,
+  slow: 500,
+  medium: 250,
+  quick: 100,
+  tooltip: 400,
+  snappy: 80,
+  gentle: 450,
+};
+
+// The interactive wrapper is a raw <div>, so the non-removable focus-visible
+// ring (W12 / DG-A11Y-01 contract: 2px solid $outlineColor, offset 2) has to
+// come from an injected stylesheet — inline styles cannot express
+// :focus-visible. Same one-shot pattern as the forms Spinner motion styles.
+const WHEEL_FOCUS_STYLE_ID = "mp1-wheel-focus";
+function ensureWheelFocusStyles() {
+  if (!isWeb || typeof document === "undefined") return;
+  if (document.getElementById(WHEEL_FOCUS_STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = WHEEL_FOCUS_STYLE_ID;
+  style.textContent =
+    ".mp1-wheel-wrapper:focus-visible { outline: 2px solid var(--outlineColor, rgba(0,0,0,0.5)); outline-offset: 2px; }";
+  document.head.appendChild(style);
+}
+
+// ── Styled components ─────────────────────────────────────────
+
+const WheelContainer = styled(View, {
+  name: "Wheel",
+  position: "relative",
+  overflow: "hidden",
+  userSelect: "none",
+  width: 80, // Default width for wheel column
+});
+
+const WheelItemContainer = styled(View, {
+  name: "WheelItem",
+  position: "absolute",
+  left: 0,
+  right: 0,
+  alignItems: "center",
+  justifyContent: "center",
+  userSelect: "none",
+});
+
+const SelectionIndicator = styled(View, {
+  name: "WheelSelectionIndicator",
+  position: "absolute",
+  left: 0,
+  right: 0,
+  borderTopWidth: 1,
+  borderBottomWidth: 1,
+  borderColor: "$borderColor",
+  backgroundColor: "$color3",
+  opacity: 0.3,
+  pointerEvents: "none",
+});
+
+const FadeOverlay = styled(View, {
+  name: "WheelFadeOverlay",
+  position: "absolute",
+  left: 0,
+  right: 0,
+  pointerEvents: "none",
+  variants: {
+    edge: {
+      top: { top: 0 },
+      bottom: { bottom: 0 },
+    },
+  } as const,
+});
+
+// ── Helper functions ──────────────────────────────────────────
+
+function normalizeItem<T>(item: T | WheelItem<T>): WheelItem<T> {
+  if (typeof item === "object" && item !== null && "value" in item) {
+    return item as WheelItem<T>;
+  }
+  return { value: item as T, label: String(item) };
+}
+
+function getItemLabel<T>(item: T | WheelItem<T>): string {
+  const normalized = normalizeItem(item);
+  return normalized.label ?? String(normalized.value);
+}
+
+function getItemValue<T>(item: T | WheelItem<T>): T {
+  const normalized = normalizeItem(item);
+  return normalized.value;
+}
+
+/** Non-negative modulo (JavaScript % can be negative for negative lhs). */
+function modIndex(row: number, n: number): number {
+  if (n <= 0) return 0;
+  return ((row % n) + n) % n;
+}
+
+/**
+ * Scroll offset that shows the same item as `targetOffset` (same row mod n), chosen so its
+ * value is closest to `referenceOffset` — shortest motion when animating from `referenceOffset`.
+ */
+function equivalentOffsetNear(
+  referenceOffset: number,
+  targetOffset: number,
+  n: number,
+  itemHeight: number,
+): number {
+  if (n <= 0 || itemHeight <= 0) return targetOffset;
+  const rT = Math.round(targetOffset / itemHeight);
+  const m = modIndex(rT, n);
+  const span = n * itemHeight;
+  const base = m * itemHeight;
+  const k = Math.round((referenceOffset - base) / span);
+  return base + k * span;
+}
+
+/** Shortest steps on the item circle from current row to target data index. */
+function nearestRowForDataIndex(currentRow: number, targetDataIndex: number, n: number): number {
+  const currentMod = modIndex(currentRow, n);
+  let delta = targetDataIndex - currentMod;
+  if (delta > n / 2) delta -= n;
+  if (delta < -n / 2) delta += n;
+  return currentRow + delta;
+}
+
+// Rubber-band effect for over-scrolling (iOS style)
+function rubberBand(offset: number, dimension: number): number {
+  const c = rubberBandConstant;
+  const x = Math.abs(offset);
+  const result = (x * dimension * c) / (dimension + c * x);
+  return offset < 0 ? -result : result;
+}
+
+// Calculate 3D transform for wheel effect
+function getItemTransform(
+  index: number,
+  scrollOffset: number,
+  itemHeight: number,
+  containerHeight: number,
+): { translateY: number; rotateX: number; scale: number; opacity: number } {
+  const centerY = containerHeight / 2;
+  // Rows are laid out so the row at `scrollOffset / itemHeight` sits under the
+  // selection indicator (which is centered at `containerHeight / 2`), hence the
+  // `(containerHeight - itemHeight) / 2` padding shift.
+  const itemCenterY =
+    index * itemHeight + itemHeight / 2 - scrollOffset + (containerHeight - itemHeight) / 2;
+  const distanceFromCenter = itemCenterY - centerY;
+  const normalizedDistance = distanceFromCenter / (containerHeight / 2);
+
+  // Rotation: items rotate on X-axis as they move away from center
+  // Max rotation is about 70 degrees at the edges
+  const rotateX = normalizedDistance * -70;
+
+  // Scale: items get smaller as they rotate away
+  const scale = 1 - Math.abs(normalizedDistance) * 0.3;
+
+  // Opacity: keep visible rows at full alpha so $color11/$color12 clear WCAG AA
+  // (≥4.5:1). Depth cue comes from rotateX/scale + edge fades, not text alpha.
+  const opacity = 1;
+
+  // Y position adjusted for 3D perspective effect
+  // Items appear to curve back
+  const curveOffset = Math.abs(normalizedDistance) * normalizedDistance * itemHeight * 0.5;
+  const translateY = itemCenterY - itemHeight / 2 + curveOffset;
+
+  return {
+    translateY,
+    rotateX: Math.max(-85, Math.min(85, rotateX)),
+    scale: Math.max(0.5, Math.min(1, scale)),
+    opacity,
+  };
+}
+
+// ── Wheel Component ───────────────────────────────────────────
+
+export function Wheel<T = string | number>({
+  items,
+  value,
+  onChange,
+  visibleItems = 5,
+  itemHeight: itemHeightProp,
+  renderItem,
+  disabled = false,
+  size: sizeProp,
+  loop = false,
+  "aria-label": ariaLabel,
+}: WheelProps<T>) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+  // Row text and row geometry derive from the size knob (spec Wheel:
+  // rows consume sizeToken, SP-FIXED); explicit props eject.
+  const size = sizeProp ?? (knobProps.sizeToken as SizeTokens);
+  const itemHeight = itemHeightProp ?? (getTokens().size as any)?.[knobProps.sizeToken]?.val ?? 40;
+  ensureWheelFocusStyles();
+  // LC-25: discrete snaps (keyboard / controlled value) tween; drag stays 1:1.
+  const motionTransition = (knobProps.transition as string | undefined) || "quick";
+  const snapDurationMs = transitionDurationsMs[motionTransition] ?? 100;
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [scrollOffset, setScrollOffset] = useState(0);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  const n = items.length;
+  const loopEnabled = Boolean(loop && n > 1);
+
+  // Keep a ref in sync with scrollOffset to avoid stale closures
+  const scrollOffsetRef = useRef(scrollOffset);
+  scrollOffsetRef.current = scrollOffset;
+
+  // Animation state
+  const animationRef = useRef<number | null>(null);
+  const isAnimatingRef = useRef(false);
+  const hasMountedRef = useRef(false);
+  const selectedIndexRef = useRef(selectedIndex);
+  selectedIndexRef.current = selectedIndex;
+
+  // Drag state
+  const isDraggingRef = useRef(false);
+  const lastYRef = useRef(0);
+  const lastTimeRef = useRef(0);
+  const dragVelocitiesRef = useRef<number[]>([]);
+
+  const containerHeight = itemHeight * visibleItems;
+  const paddingItems = Math.floor(visibleItems / 2);
+  const minOffset = 0;
+  const maxOffset = n > 0 ? (n - 1) * itemHeight : 0;
+
+  const runSnapComplete = useCallback(
+    (finalOffset: number, dataIndex: number) => {
+      const safeIdx = Math.max(0, Math.min(dataIndex, n - 1));
+      const settled =
+        loopEnabled && n > 0 ? equivalentOffsetNear(0, finalOffset, n, itemHeight) : finalOffset;
+      scrollOffsetRef.current = settled;
+      setScrollOffset(settled);
+      setSelectedIndex(safeIdx);
+      onChange?.(getItemValue(items[safeIdx]));
+      isAnimatingRef.current = false;
+    },
+    [items, n, onChange, loopEnabled, itemHeight],
+  );
+
+  const animateToOffset = useCallback(
+    (targetOffset: number, dataIndex: number, animated: boolean) => {
+      const startOffset = scrollOffsetRef.current;
+      const goal =
+        loopEnabled && n > 0
+          ? equivalentOffsetNear(startOffset, targetOffset, n, itemHeight)
+          : targetOffset;
+
+      if (!animated || snapDurationMs <= 0) {
+        runSnapComplete(goal, dataIndex);
+        return;
+      }
+
+      const distance = goal - startOffset;
+      if (Math.abs(distance) < 0.5) {
+        runSnapComplete(goal, dataIndex);
+        return;
+      }
+      const duration = snapDurationMs;
+      const startTime = performance.now();
+
+      const animate = (currentTime: number) => {
+        const elapsed = currentTime - startTime;
+        const progress = Math.min(elapsed / duration, 1);
+        const eased = 1 - Math.pow(1 - progress, 3);
+        const newOffset = startOffset + distance * eased;
+        scrollOffsetRef.current = newOffset;
+        setScrollOffset(newOffset);
+
+        if (progress < 1) {
+          animationRef.current = requestAnimationFrame(animate);
+        } else {
+          runSnapComplete(goal, dataIndex);
+        }
+      };
+
+      isAnimatingRef.current = true;
+      if (animationRef.current) cancelAnimationFrame(animationRef.current);
+      animationRef.current = requestAnimationFrame(animate);
+    },
+    [loopEnabled, n, itemHeight, runSnapComplete, snapDurationMs],
+  );
+
+  /** Snap selection to a data index (0..n-1). */
+  const snapToIndex = useCallback(
+    (targetIndex: number, animated = true) => {
+      if (n === 0) return;
+      const clampedData = Math.max(0, Math.min(targetIndex, n - 1));
+
+      if (!loopEnabled) {
+        const targetOffset = clampedData * itemHeight;
+        animateToOffset(targetOffset, clampedData, animated);
+        return;
+      }
+
+      const currentR = Math.round(scrollOffsetRef.current / itemHeight);
+      const targetR = nearestRowForDataIndex(currentR, clampedData, n);
+      const targetOffset = targetR * itemHeight;
+      const dataIdx = modIndex(targetR, n);
+      animateToOffset(targetOffset, dataIdx, animated);
+    },
+    [n, itemHeight, loopEnabled, animateToOffset],
+  );
+
+  // Sync from controlled value — LC-25: discrete jumps animate; drag stays live.
+  useEffect(() => {
+    if (value === undefined) return;
+    const index = items.findIndex((item) => getItemValue(item) === value);
+    if (index === -1) return;
+
+    // First paint: land instantly (no entrance tween from 0).
+    if (!hasMountedRef.current) {
+      hasMountedRef.current = true;
+      setSelectedIndex(index);
+      const raw = index * itemHeight;
+      const settled = loopEnabled && n > 1 ? equivalentOffsetNear(0, raw, n, itemHeight) : raw;
+      scrollOffsetRef.current = settled;
+      setScrollOffset(settled);
+      return;
+    }
+
+    // Continuous drag owns the offset — don't fight the pointer.
+    if (isDraggingRef.current) {
+      setSelectedIndex(index);
+      return;
+    }
+
+    if (index === selectedIndexRef.current && !isAnimatingRef.current) {
+      // Already settled on this value (e.g. onChange echo) — keep offset.
+      return;
+    }
+
+    snapToIndex(index, true);
+  }, [value, items, itemHeight, loopEnabled, n, snapToIndex]);
+
+  /** After free scroll, land on the nearest row (drag / wheel / momentum). */
+  const snapToNearestRow = useCallback(
+    (animated = true) => {
+      if (n === 0) return;
+      const r = Math.round(scrollOffsetRef.current / itemHeight);
+      if (loopEnabled) {
+        const targetOffset = r * itemHeight;
+        const dataIdx = modIndex(r, n);
+        animateToOffset(targetOffset, dataIdx, animated);
+      } else {
+        const dataIdx = Math.max(0, Math.min(r, n - 1));
+        animateToOffset(dataIdx * itemHeight, dataIdx, animated);
+      }
+    },
+    [n, itemHeight, loopEnabled, animateToOffset],
+  );
+
+  // Momentum animation (iOS-style deceleration)
+  const startMomentum = useCallback(
+    (initialVelocity: number) => {
+      let velocity = initialVelocity * momentumMultiplier;
+      let offset = scrollOffsetRef.current;
+
+      const animate = () => {
+        velocity *= friction;
+        offset += velocity;
+
+        if (!loopEnabled) {
+          if (offset < minOffset) {
+            offset = minOffset + rubberBand(offset - minOffset, containerHeight);
+            velocity *= 0.5;
+          } else if (offset > maxOffset) {
+            offset = maxOffset + rubberBand(offset - maxOffset, containerHeight);
+            velocity *= 0.5;
+          }
+        }
+
+        setScrollOffset(offset);
+
+        if (Math.abs(velocity) > minVelocity) {
+          animationRef.current = requestAnimationFrame(animate);
+        } else {
+          scrollOffsetRef.current = offset;
+          snapToNearestRow(true);
+        }
+      };
+
+      isAnimatingRef.current = true;
+      if (animationRef.current) cancelAnimationFrame(animationRef.current);
+      animationRef.current = requestAnimationFrame(animate);
+    },
+    [loopEnabled, minOffset, maxOffset, containerHeight, itemHeight, snapToNearestRow],
+  );
+
+  // Handle pointer/mouse down
+  const handlePointerDown = useCallback(
+    (e: React.PointerEvent | PointerEvent) => {
+      if (disabled) return;
+
+      // Stop any ongoing animation
+      if (animationRef.current) {
+        cancelAnimationFrame(animationRef.current);
+        isAnimatingRef.current = false;
+      }
+
+      isDraggingRef.current = true;
+      lastYRef.current = e.clientY;
+      lastTimeRef.current = performance.now();
+      dragVelocitiesRef.current = [];
+
+      // Capture pointer for drag outside element
+      if (isWeb && containerRef.current) {
+        containerRef.current.setPointerCapture(e.pointerId);
+      }
+    },
+    [disabled],
+  );
+
+  // Handle pointer/mouse move
+  const handlePointerMove = useCallback(
+    (e: React.PointerEvent | PointerEvent) => {
+      if (!isDraggingRef.current || disabled) return;
+
+      const currentY = e.clientY;
+      const currentTime = performance.now();
+      const deltaY = lastYRef.current - currentY;
+      const deltaTime = currentTime - lastTimeRef.current;
+
+      // Calculate velocity
+      if (deltaTime > 0) {
+        const velocity = (deltaY / deltaTime) * 16; // Normalize to ~60fps
+        dragVelocitiesRef.current.push(velocity);
+        // Keep only last 5 velocities for averaging
+        if (dragVelocitiesRef.current.length > 5) {
+          dragVelocitiesRef.current.shift();
+        }
+      }
+
+      let newOffset = scrollOffsetRef.current + deltaY;
+      if (!loopEnabled) {
+        if (newOffset < minOffset) {
+          newOffset = minOffset + rubberBand(newOffset - minOffset, containerHeight);
+        } else if (newOffset > maxOffset) {
+          newOffset = maxOffset + rubberBand(newOffset - maxOffset, containerHeight);
+        }
+      }
+
+      // Update ref immediately so subsequent pointer events use the correct base offset
+      // (React 18 may batch multiple setScrollOffset calls, leaving scrollOffsetRef stale)
+      scrollOffsetRef.current = newOffset;
+      setScrollOffset(newOffset);
+      lastYRef.current = currentY;
+      lastTimeRef.current = currentTime;
+    },
+    [disabled, loopEnabled, minOffset, maxOffset, containerHeight],
+  );
+
+  // Handle pointer/mouse up
+  const handlePointerUp = useCallback(
+    (e: React.PointerEvent | PointerEvent) => {
+      if (!isDraggingRef.current) return;
+
+      isDraggingRef.current = false;
+
+      // Release pointer capture
+      if (isWeb && containerRef.current) {
+        containerRef.current.releasePointerCapture(e.pointerId);
+      }
+
+      // Calculate average velocity for momentum
+      const velocities = dragVelocitiesRef.current;
+      if (velocities.length > 0) {
+        const avgVelocity = velocities.reduce((a, b) => a + b, 0) / velocities.length;
+
+        if (Math.abs(avgVelocity) > minVelocity * 2) {
+          startMomentum(avgVelocity);
+        } else {
+          snapToNearestRow(true);
+        }
+      } else {
+        snapToNearestRow(true);
+      }
+    },
+    [snapToNearestRow, startMomentum],
+  );
+
+  // Handle mouse wheel
+  const handleWheel = useCallback(
+    (e: React.WheelEvent | WheelEvent) => {
+      if (disabled) return;
+      e.preventDefault();
+
+      // Stop any ongoing animation
+      if (animationRef.current) {
+        cancelAnimationFrame(animationRef.current);
+        isAnimatingRef.current = false;
+      }
+
+      // Use deltaY for scrolling
+      const delta = e.deltaY;
+      const currentOffset = scrollOffsetRef.current;
+      let newOffset = currentOffset + delta;
+
+      if (!loopEnabled) {
+        if (newOffset < minOffset) {
+          newOffset = minOffset;
+        } else if (newOffset > maxOffset) {
+          newOffset = maxOffset;
+        }
+      }
+
+      setScrollOffset(newOffset);
+
+      if (animationRef.current) cancelAnimationFrame(animationRef.current);
+      animationRef.current = requestAnimationFrame(() => {
+        setTimeout(() => {
+          if (!isDraggingRef.current && !isAnimatingRef.current) {
+            snapToNearestRow(true);
+          }
+        }, 100);
+      });
+    },
+    [disabled, loopEnabled, minOffset, maxOffset, itemHeight, snapToNearestRow],
+  );
+
+  // Handle keyboard
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent | KeyboardEvent) => {
+      if (disabled) return;
+
+      let delta = 0;
+      switch (e.key) {
+        case "ArrowUp":
+        case "k":
+          delta = -1;
+          break;
+        case "ArrowDown":
+        case "j":
+          delta = 1;
+          break;
+        case "PageUp":
+          delta = -visibleItems;
+          break;
+        case "PageDown":
+          delta = visibleItems;
+          break;
+        case "Home":
+          snapToIndex(0);
+          e.preventDefault();
+          return;
+        case "End":
+          snapToIndex(n - 1);
+          e.preventDefault();
+          return;
+        default:
+          return;
+      }
+
+      e.preventDefault();
+      if (loopEnabled) {
+        const newIndex = modIndex(selectedIndex + delta, n);
+        snapToIndex(newIndex);
+      } else {
+        const newIndex = Math.max(0, Math.min(selectedIndex + delta, n - 1));
+        snapToIndex(newIndex);
+      }
+    },
+    [disabled, selectedIndex, n, visibleItems, snapToIndex, loopEnabled],
+  );
+
+  // Set up event listeners for web
+  useEffect(() => {
+    if (!isWeb) return;
+
+    const container = containerRef.current;
+    if (!container) return;
+
+    // Wheel event with passive: false to allow preventDefault
+    const wheelHandler = (e: WheelEvent) => handleWheel(e);
+    container.addEventListener("wheel", wheelHandler, { passive: false });
+
+    return () => {
+      container.removeEventListener("wheel", wheelHandler);
+    };
+  }, [handleWheel]);
+
+  // Cleanup animation on unmount
+  useEffect(() => {
+    return () => {
+      if (animationRef.current) {
+        cancelAnimationFrame(animationRef.current);
+      }
+    };
+  }, []);
+
+  const renderRows = useMemo(() => {
+    if (n === 0) return [];
+    if (loopEnabled) {
+      const centerRow = Math.round(scrollOffset / itemHeight);
+      const rowBuffer = paddingItems + 5;
+      const list: { virtualRow: number; dataIndex: number }[] = [];
+      for (let vr = centerRow - rowBuffer; vr <= centerRow + rowBuffer; vr++) {
+        list.push({ virtualRow: vr, dataIndex: modIndex(vr, n) });
+      }
+      return list;
+    }
+    const start = Math.max(0, Math.floor(scrollOffset / itemHeight) - paddingItems - 1);
+    const end = Math.min(
+      n - 1,
+      Math.ceil((scrollOffset + containerHeight) / itemHeight) + paddingItems + 1,
+    );
+    return Array.from({ length: end - start + 1 }, (_, i) => {
+      const virtualRow = start + i;
+      return { virtualRow, dataIndex: virtualRow };
+    });
+  }, [n, loopEnabled, scrollOffset, itemHeight, paddingItems, containerHeight]);
+
+  const itemColor = (isSelected: boolean) =>
+    disabled ? "$color10" : isSelected ? "$color12" : "$color11";
+
+  return (
+    <WheelContainer
+      height={containerHeight}
+      {...knobProps.borderRadius}
+      data-testid="wheel"
+      data-disabled={disabled ? true : undefined}
+      aria-disabled={disabled || undefined}
+      opacity={1}
+    >
+      {/* Selection indicator */}
+      <SelectionIndicator top={paddingItems * itemHeight} height={itemHeight} />
+
+      {/* Subtle edge cue only — strong fades washed numerals below AA visually */}
+      <FadeOverlay
+        edge="top"
+        height={paddingItems * itemHeight}
+        {...(isWeb
+          ? {
+              style: {
+                background:
+                  "linear-gradient(to bottom, color-mix(in srgb, var(--background) 18%, transparent) 0%, transparent 100%)",
+              } as React.CSSProperties,
+            }
+          : {})}
+      />
+      <FadeOverlay
+        edge="bottom"
+        height={paddingItems * itemHeight}
+        {...(isWeb
+          ? {
+              style: {
+                background:
+                  "linear-gradient(to top, color-mix(in srgb, var(--background) 18%, transparent) 0%, transparent 100%)",
+              } as React.CSSProperties,
+            }
+          : {})}
+      />
+
+      {/* Interactive container */}
+      {isWeb ? (
+        <div
+          ref={containerRef}
+          className="mp1-wheel-wrapper"
+          tabIndex={disabled ? -1 : 0}
+          role="slider"
+          aria-label={ariaLabel ?? t("Value picker")}
+          aria-orientation="vertical"
+          aria-valuemin={0}
+          aria-valuemax={Math.max(0, n - 1)}
+          aria-valuenow={selectedIndex}
+          aria-valuetext={
+            items[selectedIndex] !== undefined ? getItemLabel(items[selectedIndex]) : undefined
+          }
+          aria-disabled={disabled || undefined}
+          data-disabled={disabled ? true : undefined}
+          style={{
+            width: "100%",
+            height: containerHeight,
+            position: "relative",
+            perspective: "1000px",
+            perspectiveOrigin: "center center",
+            overflow: "hidden",
+            userSelect: "none",
+            touchAction: "none",
+            cursor: disabled ? "not-allowed" : "grab",
+          }}
+          onPointerDown={handlePointerDown as any}
+          onPointerMove={handlePointerMove as any}
+          onPointerUp={handlePointerUp as any}
+          onPointerCancel={handlePointerUp as any}
+          onKeyDown={handleKeyDown as any}
+          data-testid="wheel-wrapper"
+        >
+          {renderRows.map(({ virtualRow, dataIndex }) => {
+            const item = items[dataIndex];
+            const isSelected = dataIndex === selectedIndex;
+            const itemValue = getItemValue(item);
+            const transform = getItemTransform(
+              virtualRow,
+              scrollOffset,
+              itemHeight,
+              containerHeight,
+            );
+
+            if (Math.abs(transform.rotateX) > 85) return null;
+
+            const rowKey = loopEnabled ? `${dataIndex}-${virtualRow}` : String(itemValue);
+
+            return (
+              <div
+                key={rowKey}
+                data-testid="wheel-item"
+                data-index={dataIndex}
+                data-selected={isSelected}
+                aria-hidden={isSelected ? undefined : true}
+                style={{
+                  position: "absolute",
+                  left: 0,
+                  right: 0,
+                  height: itemHeight,
+                  display: "flex",
+                  alignItems: "center",
+                  justifyContent: "center",
+                  transform: `translateY(${transform.translateY}px) rotateX(${transform.rotateX}deg) scale(${transform.scale})`,
+                  opacity: transform.opacity,
+                  pointerEvents: "none",
+                  transformOrigin: "center center",
+                  transformStyle: "preserve-3d",
+                  backfaceVisibility: "hidden",
+                }}
+              >
+                {renderItem ? (
+                  renderItem(itemValue, dataIndex, isSelected)
+                ) : (
+                  <Text
+                    {...knobProps.body}
+                    fontSize={size}
+                    fontWeight={isSelected && !disabled ? "600" : "400"}
+                    color={itemColor(isSelected)}
+                  >
+                    {getItemLabel(item)}
+                  </Text>
+                )}
+              </div>
+            );
+          })}
+        </div>
+      ) : (
+        <View
+          width="100%"
+          height={containerHeight}
+          position="relative"
+          overflow="hidden"
+          cursor={disabled ? "not-allowed" : "grab"}
+          data-disabled={disabled ? true : undefined}
+          aria-disabled={disabled || undefined}
+          onPointerDown={handlePointerDown as any}
+          onPointerMove={handlePointerMove as any}
+          onPointerUp={handlePointerUp as any}
+          onPointerCancel={handlePointerUp as any}
+        >
+          {renderRows.map(({ virtualRow, dataIndex }) => {
+            const item = items[dataIndex];
+            const isSelected = dataIndex === selectedIndex;
+            const itemValue = getItemValue(item);
+            const transform = getItemTransform(
+              virtualRow,
+              scrollOffset,
+              itemHeight,
+              containerHeight,
+            );
+
+            if (Math.abs(transform.rotateX) > 85) return null;
+
+            const rowKey = loopEnabled ? `${dataIndex}-${virtualRow}` : String(itemValue);
+
+            return (
+              <View
+                key={rowKey}
+                position="absolute"
+                left={0}
+                right={0}
+                height={itemHeight}
+                alignItems="center"
+                justifyContent="center"
+                opacity={transform.opacity}
+                pointerEvents="none"
+                y={transform.translateY}
+                scale={transform.scale}
+              >
+                {renderItem ? (
+                  renderItem(itemValue, dataIndex, isSelected)
+                ) : (
+                  <Text
+                    {...knobProps.body}
+                    fontSize={size}
+                    fontWeight={isSelected && !disabled ? "600" : "400"}
+                    color={itemColor(isSelected)}
+                  >
+                    {getItemLabel(item)}
+                  </Text>
+                )}
+              </View>
+            );
+          })}
+        </View>
+      )}
+    </WheelContainer>
+  );
+}
+
+// ── Sub-components for composition ────────────────────────────
+
+Wheel.Item = WheelItemContainer;
+
+export type WheelContainerProps = GetProps<typeof WheelContainer>;
+export type WheelItemProps = GetProps<typeof WheelItemContainer>;