Files
webb/docs/superpowers/plans/2026-11-04-showcase-vertical-wheel-and-arrows.md
T

3.1 KiB

Interactive Model Showcase Vertical Wheel Translation & Side Arrows Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Enable visitors to navigate the flagship transformation models in the Interactive Model Showcase via vertical wheel/trackpad scrolling and dedicated Left/Right side arrow buttons.

Architecture: Client-side React hooks (useRef, useState, useEffect) in CinematicHorizontalScrollSection.tsx with non-passive wheel event interception, edge boundary pass-through, smooth card stepping via scrollBy, and floating accessible arrow buttons.

Tech Stack: Next.js 14 App Router, React 18, TypeScript, Tailwind CSS, Lucide React (ChevronLeft, ChevronRight).

Spec: docs/superpowers/specs/2026-11-04-showcase-vertical-wheel-and-arrows-design.md

Global Constraints

  • Preserve existing data interfaces and Mustache binding resolution.
  • Never trap user scroll: when rail is at the left boundary and scrolling up, or right boundary and scrolling down, let vertical scroll bubble to page.
  • Accessible: aria-label attributes on both buttons, keyboard operable.
  • Responsive: Floating arrows styled to fit both mobile and wide screens without obscuring critical interactive elements.

Review Focus

  1. Wheel listener must use { passive: false } so preventDefault() functions cleanly without console warnings.
  2. Left and Right arrows calculate proper scroll distance (card width + gap) and smoothly animate.
  3. Clean boundary detection prevents stutter when reaching start/end of the rail.
  4. Touch swipe functionality on mobile devices is preserved intact.

Task 1: Enhance CinematicHorizontalScrollSection.tsx with Wheel & Arrow Controls

Files:

  • Modify: src/components/sections/CinematicHorizontalScrollSection.tsx

  • Step 1: Add state and refs for rail, scroll boundaries, and wheel interaction

    • Define railRef = useRef<HTMLDivElement>(null)
    • Define canScrollLeft and canScrollRight states
    • Define isHovered or rail event listener for wheel with { passive: false }
  • Step 2: Implement boundary-aware vertical wheel translation

    • Intercept vertical deltaY when dominant over deltaX
    • Translate e.deltaY into rail.scrollLeft
    • Allow natural page scroll if already at leftmost or rightmost boundary
  • Step 3: Implement floating Left and Right navigation buttons

    • Place Left and Right arrow buttons vertically centered on the carousel flanks
    • Implement scrollDirection('left') and scrollDirection('right') using rail.scrollBy({ left: +/- step, behavior: 'smooth' })
    • Add aria-label and visual disabled/faded states
  • Step 4: Update scroll snap style to snap-proximity

    • Prevent harsh snapping conflict during continuous wheel scrolling

Task 2: Build Verification & Regression Check

Files:

  • Run test and build commands

  • Step 1: Run unit test suite

    • npm test
  • Step 2: Run production Next.js build

    • npm run build