feat: implement management folder architecture, hover-only tool sliders, grain transform animation, and prominent upload studio

This commit is contained in:
2026-11-04 12:28:32 +05:30
parent ad9a3ab000
commit 3cb202399f
56 changed files with 2339 additions and 466 deletions
@@ -0,0 +1,90 @@
# Management Folder Architecture & Refined Visual UX Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
This plan resolves four core user requirements:
1. **Centralized Management Folder (`management/`)**: Modular, page-by-page folder architecture housing all JSON configs and media (before/after images, banners, videos), allowing direct file-drop replacement for live website updates.
2. **Tool Page Re-engineering (`/tools/[slug]`)**: Spacious prominent upload studio, borderless result-focused display stage, typography placed outside cards, and a generative latent grain transformation animation.
3. **Homepage Tool Stack Cards Hover-Only Slide**: Eliminate simultaneous chaotic auto-sliding across all 8 cards; only animate the card that is actively hovered, and allow click/drag to manually inspect.
4. **Fluid, Seamless Horizontal Scroll**: Fix sticky overflow constraints (`overflow-x: clip`), smooth scroll conflicts, and ensure frictionless progression from vertical -> horizontal -> vertical.
---
## File Structure & Responsibilities
```
management/
├── pages/
│ ├── home/
│ │ ├── page.config.json # Home page section configuration & copy
│ │ └── media/ # Media assets used on home page
│ └── tools/
│ ├── cartoon-avatar/
│ │ ├── tool.config.json # Tool metadata, copy, displayType ("beforeAfter" | "banner")
│ │ └── media/ # before.jpg, after.jpg, sample-*.jpg
│ ├── blemish-remover/
│ ├── background-remover/
│ ├── colorization/
│ ├── old-photo-restorer/
│ ├── photo-enhancer/
│ ├── polaroid-maker/
│ └── teeth-whitener/
public/
└── management -> symlink or synced to ../management
src/
├── components/
│ ├── ui/
│ │ ├── NeuralGrainOverlay.tsx # Generative AI latent grain transform animation
│ │ ├── CardBeforeAfterSlider.tsx # Tool stack card slider (hover-only slide, click-drag)
│ ├── sections/
│ │ ├── HeroSection.tsx # Redesigned tool hero (prominent upload, result-focused display)
│ │ ├── TryItWidget.tsx # Spacious, beautiful upload studio
│ │ ├── CinematicHorizontalScrollSection.tsx # Frictionless horizontal showcase
├── lib/
│ ├── config/
│ │ ├── loader.ts # Loads configurations and media paths from management/
```
---
## Tasks
### Task 1: Create Centralized `management/` Folder Architecture
- [ ] Create `management/pages/tools/[slug]/` directories for all 8 tools with `tool.config.json` and `media/` subdirectories.
- [ ] Copy or generate high-res before/after assets into `management/pages/tools/[slug]/media/before.jpg` and `after.jpg`.
- [ ] Create `management/pages/home/` with `page.config.json` and `media/`.
- [ ] Ensure Next.js can serve assets from `management/` via symlink in `public/management` or Next route so replacing any file immediately updates the live site.
- [ ] Update `src/lib/config/loader.ts` to source tool data and media paths from `management/`.
- [ ] Verify `npm test` and build compile cleanly.
### Task 2: Home Page Tool Stack Cards — Hover-Only Sliding
- [ ] Update `src/components/ui/CardBeforeAfterSlider.tsx`:
- Static 50% rest state when not hovered.
- Start smooth, gentle slide animation **only when cursor is hovering over the card**.
- Clicking/dragging allows manual scrub.
- Reset to rest on mouse leave.
- [ ] Verify all cards remain calm and static until hovered.
### Task 3: Tool Landing Page (`/tools/[slug]`) Visual Redesign & Grain Transform Animation
- [ ] Create `src/components/ui/NeuralGrainOverlay.tsx`:
- Authentic generative AI latent grain / noise sweep animation representing neural model synthesis.
- Canvas/SVG-based high-frequency grain texture with customizable intensity and scan sweep.
- [ ] Redesign `src/components/sections/HeroSection.tsx` (`variant === 'toolHero'`):
- Typography placed outside cards: Large editorial headline, category badge, and descriptive copy directly on page background.
- **Left / Display Stage**: Focus 100% on actual transformation results with minimal border chrome, integrated Before/After slider, and the Neural Grain transformation effect.
- **Right / Upload Studio**: Spacious, prominent, high-end upload dropzone with glowing borders, clear specs, and sample presets.
- [ ] Update `src/components/sections/TryItWidget.tsx` to match the spacious, beautiful studio layout.
### Task 4: Fix Horizontal Showcase Scroll Fluidity
- [ ] Fix `body` overflow in `src/app/globals.css`: replace `overflow-x: hidden` with `overflow-x: clip` so `position: sticky` is never disabled.
- [ ] In `CinematicHorizontalScrollSection.tsx`, ensure synchronous DOM transform updates on scroll with liquid GPU hardware acceleration.
- [ ] Ensure arrow navigation, wheel scrolling, and trackpad swipe glide seamlessly through all cards and transition cleanly to the next section.
### Task 5: Verification & End-to-End Testing
- [ ] Run `npm test` to verify all unit tests pass.
- [ ] Run headless browser script verifying:
- Tool cards in "Find the right tool fast" slide ONLY on hover.
- Tool specific page renders prominent upload studio + grain transformation display + typography outside cards.
- Horizontal scroll glides seamlessly.
- Replacing an image in `management/` updates the live page.
- [ ] Commit all changes to git.
@@ -0,0 +1,60 @@
# 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`
@@ -0,0 +1,64 @@
# Design: Interactive Model Showcase Vertical Scroll Translation & Side Navigation Arrows
**Date:** 2026-11-04
**Status:** Approved (Option 1 selected by user)
**Target File:** `src/components/sections/CinematicHorizontalScrollSection.tsx`
---
## 1. Intent & Purpose
Enable visitors to navigate the flagship transformation models in the **Interactive Model Showcase** using natural vertical wheel/trackpad scrolling and dedicated tactile Left/Right side arrow buttons, making horizontal exploration effortless on both desktop and mobile.
---
## 2. Goals, Non-Goals, and Anti-Goals
### Goals
- **Vertical-to-Horizontal Translation**: Vertical mouse wheel and trackpad scroll gestures (`deltaY`) over the showcase rail directly translate into horizontal scrolling.
- **Natural Boundary Pass-Through**: When the rail reaches its horizontal start (scrolling up) or end (scrolling down), vertical page scrolling naturally resumes so users never get trapped.
- **Side Navigation Arrows**: Sleek, accessible, liquid-glass Left and Right arrow buttons floating on either side of the rail that slide card-by-card on click.
- **Dynamic State**: Arrow buttons automatically update their disabled/opacity state based on current scroll position.
- **Zero Regressions**: Maintain high-contrast light creamy theme, mobile touch-swipe, and WCAG AA accessibility standards.
### Non-Goals
- Full viewport height pinning (Option 2 was declined in favor of in-place wheel translation).
- Modifying the underlying data schemas in `content/pages/home.json` or `SectionRenderer.tsx`.
### Anti-Goals
- Trapping vertical scroll permanently or blocking scroll when at the edges.
- Obscuring before/after comparison interactive sliders with arrow buttons.
---
## 3. Approaches Considered
1. **Option 1: In-Place Wheel & Trackpad Translation + Floating Side Arrows (Selected)**
- Translates `deltaY` to `scrollLeft` on non-passive wheel events when hovering the showcase section.
- Bails out when at the boundary edges to allow standard vertical document scroll.
- Adds floating, accessible `ChevronLeft` and `ChevronRight` buttons on the left and right flanks.
- **Trade-off:** Retains clean layout flow without modifying page scroll height.
2. **Option 2: Sticky Pinned Viewport Track (Rejected)**
- Pins the section to the viewport for 300vh of vertical scroll distance.
- **Trade-off:** High layout footprint, can feel disruptive on shorter viewports.
---
## 4. Implementation Details
- **File:** `src/components/sections/CinematicHorizontalScrollSection.tsx`
- **State & Refs:**
- `railRef = useRef<HTMLDivElement>(null)`: Reference to the horizontal scrolling rail.
- `canScrollLeft`: boolean state, default false.
- `canScrollRight`: boolean state, default true.
- **Wheel Listener (`passive: false`):**
- Attached via `useEffect` with clean cleanup.
- Only intercepts when vertical delta is dominant (`Math.abs(e.deltaY) > Math.abs(e.deltaX)`).
- Calls `e.preventDefault()` only if the rail has remaining scroll distance in the scroll direction.
- **Arrow Navigation:**
- Left button with `ChevronLeft` icon, right button with `ChevronRight` icon.
- `scrollBy({ left: +/- scrollDistance, behavior: 'smooth' })`, calculating step based on card width + gap.
- High z-index, styled with `bg-white/90`, `backdrop-blur-md`, `shadow-cream-md`, and smooth hover scale.
- Hidden or opacity-0 when disabled to maintain a clean aesthetic at boundaries.
- **Snap Polish:**
- Uses `snap-x snap-proximity` for smooth wheel translation without abrasive snap fighting, locking neatly onto cards when resting.