🌀 Transition & Orchestration Reference

VibeDev Motion introduces a "Dual-Core" transition system. Unlike standard animation libraries that only interpolate numbers, VibeDev converts transition parameters into real-time physical forces.

---

💎 Core Transition Parameters

1. The Designer API (Spring)

Instead of manual stiffness/damping, use the modern timing-based API:

• visualDuration (number): The total time in seconds the animation takes to settle.
• bounce (number, 0-1): The amount of physical overshoot. 0 is a silk-smooth settle; 0.5 is a lively bounce.

<vibe.div 
  animate={{ x: 100 }}
  transition={{ 
    type: "spring", 
    visualDuration: 0.8, 
    bounce: 0.3 
  }}
/>

2. Physical Orchestration

Sequence multiple physical bodies using standard orchestration props:

• delay: Time to wait before starting the simulation.
• staggerChildren: Delays the start of child physics.
• stagger utility: Advanced sequencing patterns (center, last, index-based).

import { vibe, stagger } from 'vibedev-motion';

const listTransition = {
  // Stagger children from the center outwards
  delayChildren: stagger(0.1, { from: 'center' })
};

---

🚀 Top 3 High-End Use Cases

USE CASE 1: The Elastic Layout Shift

Scenario: A sidebar collapses, and the main content expands. The Vibe Edge: Instead of a linear sliding effect, the main content "bumps" into its new position using Impulse-FLIP.

<vibe.div 
  layout="physics" 
  transition={{ visualDuration: 0.6, bounce: 0.2 }}
>
  {/* The content will physically drift to its new layout position */}
</vibe.div>

USE CASE 2: Kinetic Grid Entry (Stagger + Mass)

Scenario: A grid of 20 items appears on page load. The Vibe Edge: Use stagger to make items "pop" in sequence. Each item has its own weight, so the grid feels like a physical tray being filled.

const gridTransition = {
  type: "spring",
  visualDuration: 0.5,
  bounce: 0.4,
  delayChildren: stagger(0.05)
};

return (
  <vibe.div transition={gridTransition}>
    {items.map(i => (
      <vibe.div key={i} whileInView={{ scale: 1, physics: true }} initial={{ scale: 0 }} />
    ))}
  </vibe.div>
);

USE CASE 3: Momentum-Aware Shared Elements

Scenario: A thumbnail in a list expands into a full-screen image. The Vibe Edge: Using layoutId, the physical momentum of the thumbnail (if it was being dragged or scrolled) is transferred seamlessly to the full-screen view.

<vibe.img 
  layoutId={`image-${id}`} 
  transition={{ type: "spring", visualDuration: 1, bounce: 0.1 }}
/>

---

🛠️ Internal Functionality: Sync-Sync Logic

VibeDev Motion doesn't just "move" the element. When a transition starts:

1. Target Calculation: The engine identifies the "Target Position" in the DOM.
2. Spring Solver: It maps your visualDuration and bounce to physical constants:
   • Stiffness = (2 * PI / visualDuration)^2
   • Damping = 4 * PI * (1 - bounce) / visualDuration
3. Sim-Sync Loop: A 60Hz loop applies a continuous corrective force (F = -kx - cv) to the Rapier rigid body until it reaches the target.
4. Collision Check: If the element hits another vibe component during its transition, they will physically collide and bounce off each other.

---

🏆 Summary Table

| Feature | Standard Motion | VibeDev Motion | Emotional Impact | | :--- | :--- | :--- | :--- | | Springs | Numerical LERP | Integrated Physics | Tactile & "Heavy" | | Layouts | Visual Tween | Physical Impulse | Real-world momentum | | Stagger | Time offsets | Sequential Force | Satisfying "Ripple" | | Repeats | Reverse curves | Physical Oscillation | Rhythmic resonance |