npm package: @hekimcan/react-sticky-stepper
Description: Apple-style sticky scroll storytelling for React & Next.js powered by GSAP + ScrollTrigger.
Author: Hekimcan Aktaş
Latest version: 1.1.0

# @hekimcan/react-sticky-stepper

Apple-style sticky scroll storytelling for React & Next.js — powered by GSAP + ScrollTrigger.

## ✨ Features

- 🍎 **Apple-inspired design** - Smooth scroll-driven storytelling like Apple product pages
- ⚡ **High performance** - Built with GSAP and ScrollTrigger for buttery smooth animations
- 🎨 **Multiple animation presets** - Fade, slide, scale, or create custom animations
- 📱 **Fully responsive** - Desktop split-layout, mobile single-column (text-only)
- 🔧 **TypeScript ready** - Fully typed with excellent developer experience
- 🌐 **SSR compatible** - Works with Next.js 14+ and other SSR frameworks
- 🎯 **Zero config** - Works out of the box with sensible defaults
- 📦 **GSAP included** - No need to install GSAP separately

## 📦 Installation

```bash
npm install @hekimcan/react-sticky-stepper
```

## 🧠 Usage Example

```tsx
import { StickyStepper, Step } from '@hekimcan/react-sticky-stepper'

export default function AppleScrollDemo() {
  return (
    <StickyStepper height="500vh" animation="slide" layout="split">
      {/* Apple-style split layout */}
      <Step
        leftContent={
          <div>
            <h1>Introducing the Future</h1>
            <p>Revolutionary technology that changes everything.</p>
            <ul>
              <li>✨ Smooth animations</li>
              <li>📱 Responsive design</li>
              <li>🎯 TypeScript ready</li>
            </ul>
          </div>
        }
        rightContent={
          <img src="/product-hero.jpg" alt="Product" />
        }
      />
      
      <Step
        leftContent={
          <div>
            <h1>Performance Beyond Limits</h1>
            <p>Experience the power of next-generation technology.</p>
          </div>
        }
        rightContent={
          <video src="/performance-demo.mp4" autoPlay muted loop />
        }
      />
      
      {/* Fullscreen step */}
      <Step>
        <div style={{ textAlign: 'center' }}>
          <h1>Experience the Magic</h1>
          <p>Full-screen immersive experience</p>
        </div>
      </Step>
    </StickyStepper>
  )
}
```

## ⚙️ Props & Options

### StickyStepper Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `height` | `string` | `"400vh"` | Total scroll height for the stepper section |
| `pinOffset` | `number` | `0` | Offset from top when pinning starts |
| `animation` | `'fade' \| 'slide' \| 'scale' \| 'none'` | `'fade'` | Animation preset for step transitions |
| `layout` | `'split' \| 'fullscreen'` | `'split'` | Layout mode: split for left-right content, fullscreen for centered |
| `onStepChange` | `(index: number) => void` | `undefined` | Callback fired when active step changes |
| `children` | `ReactNode` | - | Step components |

### Step Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `leftContent` | `ReactNode` | - | Left side content (text, descriptions) for split layout |
| `rightContent` | `ReactNode` | - | Right side content (images, videos) for split layout |
| `children` | `ReactNode` | - | Content for fullscreen layout |
| `className` | `string` | `""` | Optional className for custom styling |
| `contentSide` | `'left' \| 'right'` | `'left'` | Content alignment side for split layout |

## 🧩 Animation Presets

### Fade
Smooth opacity transition between steps.

```tsx
<StickyStepper animation="fade">
  {/* Your steps */}
</StickyStepper>
```

### Slide
Steps slide up from bottom with fade effect.

```tsx
<StickyStepper animation="slide">
  {/* Your steps */}
</StickyStepper>
```

### Scale
Steps scale up from 80% with bounce effect.

```tsx
<StickyStepper animation="scale">
  {/* Your steps */}
</StickyStepper>
```

### None
No animation, just opacity changes.

```tsx
<StickyStepper animation="none">
  {/* Your steps */}
</StickyStepper>
```

## 🧰 TypeScript Support

The package includes full TypeScript definitions:

```tsx
import type { 
  StickyStepperProps, 
  StepProps, 
  AnimationFunction 
} from '@hekimcan/react-sticky-stepper'

// Custom animation function
const customAnimation: AnimationFunction = (element) => {
  return gsap.fromTo(element, 
    { rotateY: 90, opacity: 0 }, 
    { rotateY: 0, opacity: 1, duration: 1 }
  )
}
```

## 📱 Responsive Design

The component automatically adapts to different screen sizes:

**Desktop (>768px):**
- Split layout with left content (text) and right content (visuals)
- Progress dots on the right side
- Full Apple-style experience

**Mobile (≤768px):**
- Single column layout showing only left content (text)
- Right content (visuals) hidden for better mobile UX
- Smaller progress dots
- Centered text alignment

```tsx
<Step
  leftContent={
    <div>
      <h1>Always Visible</h1>
      <p>This content shows on both desktop and mobile</p>
    </div>
  }
  rightContent={
    <img src="visual.jpg" alt="Hidden on mobile" />
  }
/>
```

## 🎯 Advanced Usage

### Step Change Tracking

```tsx
const [currentStep, setCurrentStep] = useState(0)

return (
  <StickyStepper 
    onStepChange={(index) => {
      setCurrentStep(index)
      console.log(`Now viewing step: ${index}`)
    }}
  >
    {/* Your steps */}
  </StickyStepper>
)
```

### Custom Styling

```tsx
<Step className="my-custom-step">
  <div style={{ 
    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    padding: '2rem',
    borderRadius: '20px',
    color: 'white'
  }}>
    <h1>Custom Styled Step</h1>
  </div>
</Step>
```

## 🌐 Next.js Integration

The component works seamlessly with Next.js:

```tsx
// pages/index.tsx or app/page.tsx
import dynamic from 'next/dynamic'

const StickyStepper = dynamic(
  () => import('@hekimcan/react-sticky-stepper').then(mod => mod.StickyStepper),
  { ssr: false }
)

export default function HomePage() {
  return (
    <StickyStepper height="500vh">
      {/* Your steps */}
    </StickyStepper>
  )
}
```

## 🚀 Development

```bash
# Clone the repository
git clone https://github.com/hekimcanaktas/react-sticky-stepper.git

# Install dependencies
npm install

# Run development server
npm run dev

# Build the package
npm run build
```

## 🧑‍💻 Author

**Hekimcan Aktaş**

## 📜 License

MIT License - see the [LICENSE](LICENSE) file for details.

---

Made with ❤️ for the React community