# Tumbler — Technical Details Deep-dive into the drum geometry, the motion-value architecture, every input path, the snap physics, all tunable knobs, and recipes for changing it. --- ## 1. Overview A 3D cylinder value picker. Options ride a virtual drum that rotates about its X axis; the centered row faces you (selected). You spin it by **scroll, drag/throw, or arrow keys**, and it **spring-snaps** to the nearest row on release. The architecture is the interesting part: - **One `y` motion value (px)** is the single source of truth — "where am I on the drum?" Positive `y` = scrolled down. - **Every row computes its own transform from `y`** via `useTransform`, so the whole spin runs **without React re-renders**. - React state holds only `selectedIndex` (rounded from `y`), for the readout and ARIA — updated through `useMotionValueEvent`. ``` Tumbler (section) — owns useTumbler(); renders header + wheel + readout └── TumblerWheel(tumbler) — pure view, no state ├── container role=listbox, focus/keydown/wheel, height=WHEEL_HEIGHT │ └── mask layer mask-image top/bottom fade │ └── perspective layer perspective:1100 (separate from mask!) │ └── motion.ul preserve-3d, onPan/onPanEnd │ └── TumblerItem × N — absolute

, transform from y └── ``` --- ## 2. File map | File | Role | | --- | --- | | `tumbler.tsx` | Section shell. Creates `useTumbler`, renders header, wheel, readout. | | `tumbler-wheel.tsx` | The 3-layer viewport; wires pan + a11y; renders rows. | | `tumbler-item.tsx` | One row; derives `transform`/`opacity` from shared `y`. | | `use-tumbler.ts` | Driver hook: `y`, wheel/drag/keyboard, snap, entrance, clamp. | | `tumbler-config.ts` | Geometry + motion constants; `angleFor`/`scaleFor`/`opacityFor`. | | `data.ts` | `tumblerItems`, `DEFAULT_INDEX`. | | `index.ts` | `export { Tumbler }`. | --- ## 3. Geometry (`tumbler-config.ts`) ```ts export const ITEM_HEIGHT = 46; // row height = snap unit export const VISIBLE_RADIUS = 3; // rows above & below centre export const WHEEL_HEIGHT = ITEM_HEIGHT * (VISIBLE_RADIUS * 2 + 1); // 322 export const STEP_DEG = 22; // angle between rows export const MAX_VISIBLE_DEG = STEP_DEG * (VISIBLE_RADIUS + 0.5); // 77 → hidden past here export const RADIUS_PX = ITEM_HEIGHT / 2 / Math.tan((STEP_DEG * Math.PI) / 360); // ≈118.25 ``` **Why that `RADIUS_PX`?** Two rows `STEP_DEG` apart on a cylinder of radius `R` are separated vertically (along the surface, near the front) by `2·R·tan(STEP_DEG/2)`. Setting that equal to `ITEM_HEIGHT` and solving: ``` R = ITEM_HEIGHT / (2 · tan(STEP_DEG/2)) ``` This keeps the centered row at its natural, unscaled size and makes neighbors sit exactly one row-height apart at the front of the drum. ### Per-row functions of distance `d` (item units from centre) ```ts // Negative sign so list order matches visual order: earlier items (negative d) // tilt UP and sit above centre; later items (positive d) tilt down. export const angleFor = (d) => -d * STEP_DEG; // Gentle "lift": centre is full size, far rows shrink, floored at 0.7. export const scaleFor = (d) => Math.max(0.7, 1 - Math.abs(d) * 0.05); // Cosine falloff matches the physical turn; fully hidden past MAX_VISIBLE_DEG. export const opacityFor = (d) => { const angle = angleFor(d); if (Math.abs(angle) >= MAX_VISIBLE_DEG) return 0; return Math.max(0, Math.cos((angle * Math.PI) / 180)); }; ``` ### Snap & entrance constants ```ts export const SNAP_SPRING = { type: 'spring', stiffness: 380, damping: 38, mass: 0.7 }; export const ENTRANCE_OFFSET = 2; // start this many rows back export const ENTRANCE_DURATION = 1.05; // s ``` --- ## 4. One row (`tumbler-item.tsx`) ```tsx export function TumblerItem({ id, item, index, y, isSelected }) { const distance = useTransform(y, latest => index - latest / ITEM_HEIGHT); const transform = useTransform(distance, d => { const angle = angleFor(d); const s = scaleFor(d); return `translateY(-50%) rotateX(${angle}deg) translateZ(${RADIUS_PX}px) scale(${s})`; }); const opacity = useTransform(distance, opacityFor); const Icon = item.Icon; return ( ); } ``` ### Transform order (right-to-left application) `translateY(-50%) rotateX(angle) translateZ(RADIUS_PX) scale(s)` 1. `scale(s)` — size in the row's own plane. 2. `translateZ(RADIUS_PX)` — push out to the drum *surface* (becomes the rotation arm). 3. `rotateX(angle)` — rotate around the drum axis; combined with the prior translateZ this places the row on the cylinder at its angle. 4. `translateY(-50%)` — the row is anchored at `top:50%`; this lifts it by half its height so it's centered on that line. Because each row subscribes to `y` through `useTransform`, dragging the drum updates these styles on the compositor with **no React render** — only the motion values tick. --- ## 5. The viewport (`tumbler-wheel.tsx`) ```tsx ``` > ⚠️ **The mask and perspective must be on different elements.** A `mask-image` > establishes a stacking context that *flattens* 3D-transformed descendants. If > you put `perspective` on the masked element, the drum collapses to a flat list. > Mask on the outer layer, `perspective` on the inner one, `preserve-3d` on the > `

>; }; export const tumblerItems: TumblerItem[] = [ /* ~10 KYC steps, distinct pastel tiles */ ]; export const DEFAULT_INDEX = 3; // Identity verification centred on load ``` Each item gets a `tile`/`glyph` pair (e.g. `bg-rose-100 dark:bg-rose-500/15` + `text-rose-500 dark:text-rose-300`) so the little icon chips read in both themes. --- ## 8. The shell (`tumbler.tsx`) - Owns the hook so the readout shares `selectedIndex`: ```ts const tumbler = useTumbler({ itemCount: tumblerItems.length, defaultIndex: DEFAULT_INDEX }); const selected = tumblerItems[tumbler.selectedIndex]; ``` - Rounded section, `bg-gradient-to-b from-zinc-50 to-zinc-100/80` (dark inverse), a faint top `radial-gradient` glow (`-z-10`, `aria-hidden`). - Header: uppercase eyebrow "Onboarding" + heading "Pick a step to verify". - ``. - Readout pill: "Selected" ↔ `{selected?.label}`. - Header / wheel / readout each fade+rise with delays `0 / 0.15 / 0.35`. --- ## 9. Reduced motion | Path | Behaviour | | --- | --- | | Initial `y` / `selectedIndex` | Start at `defaultIndex` (no offset). | | Entrance | Skipped (jump to rest), after the `null` guard resolves. | | Snap | `y.set(target)` instantly, no spring. | | Throw physics | Velocity still projected, but snap is instant. | The `reduce === null` guard is the subtle bit: without it, the entrance can fire for one frame before `matchMedia` resolves. --- ## 10. Performance - **Spinning is render-free.** `y` + per-row `useTransform` update styles off the React tree; only `selectedIndex` triggers a render, once per row crossing. - `willChange: transform, opacity` hints the compositor. - Wheel listener is registered **non-passive** (`{ passive: false }`) so it can `preventDefault`; everything else stays cheap. - N is small (~10 rows), all simple nodes. --- ## 11. Tuning recipes | Want to… | Change | | --- | --- | | Taller/shorter rows | `ITEM_HEIGHT` (re-derives `WHEEL_HEIGHT` + `RADIUS_PX`). | | Show more rows | `VISIBLE_RADIUS` (taller viewport, more visible). | | Tighter/looser curve | `STEP_DEG` (also changes `RADIUS_PX` + `MAX_VISIBLE_DEG`). | | Stronger centre "lift" | the `0.05` slope / `0.7` floor in `scaleFor`. | | Fade more/less aggressively | `MAX_VISIBLE_DEG` factor (`VISIBLE_RADIUS + 0.5`). | | Snappier/looser snap | `SNAP_SPRING` stiffness/damping/mass. | | Longer/shorter throw | `VELOCITY_PROJECTION_S` (0.18). | | Wheel snap timing | `WHEEL_IDLE_MS` (130). | | Page-key jump size | `PAGE_STEP` (5). | | Entrance feel | `ENTRANCE_OFFSET` / `ENTRANCE_DURATION`. | | Rubber-band give | the `0.35` factor in `clampSoft`. | | Edge fade size | the `22% / 78%` stops in the `mask-image`. | | Default selection | `DEFAULT_INDEX`. | --- ## 12. Gotchas (the ones that cost real time) 1. **Mask flattens 3D.** Put `mask-image` and `perspective` on *separate* layers, with `preserve-3d` on the list, or the drum renders flat. 2. **Wheel must be non-passive.** `addEventListener('wheel', h, { passive:false })` — you cannot `preventDefault` a passive listener; React's `onWheel` is passive. 3. **Don't trap page scroll.** Early-return (no `preventDefault`) when at the bound in the wheel's direction, or the page feels stuck over the widget. 4. **`reduce === null` guard.** `useReducedMotion()` is `null` pre-resolution; gate the entrance on a definite value. 5. **Drag sign.** `y` decreases as you drag down (`-delta.y` / `-velocity.y`); getting the sign wrong inverts the whole control. 6. **Single source of truth.** Don't mirror `y` into React state for the transforms — derive with `useTransform`, or you reintroduce per-frame renders and lose the whole performance win. 7. **`touch-action: none`** on the list so touch drags pan the drum instead of scrolling the page. 8. **Create the hook in the parent.** If the wheel owned the hook and reported selection up via callback, you'd get a setState round-trip and a mount-time flicker between the parent's initial value and the hook's.