🛠️ Hooks Reference

VibeDev Motion hooks offer low-level access to the physics engine and interaction system, allowing you to build highly custom, physical UI experiences.

---

🧲 useGravityUI()

The core hook for binding magnetic fields to elements. It makes UI elements pull towards the user's cursor with configurable intensity and range.

🔌 Usage

const { bind } = useGravityUI({ 
  strength: 0.6, 
  range: 300 
});

<motion.div {...bind} />

🧠 Logic

• Spring Mapping: Uses a synchronized spring from Framer Motion.
• Vector Math: Calculates the 2D vector between the cursor and the element's center on every mouse move.
• Normalization: Applies a normalized pull factor based on distance, falling off as it reaches the range boundary.

---

🪄 useAutoExperience()

A "Zero-Config" tool that automatically enhances all matching elements (buttons, links, cards) with magnetic micro-interactions.

🔌 Usage

useAutoExperience({
  selectors: ['button', 'a', '.vibe-card'],
  intensity: 15
});

🧠 Logic

• DOM Scanner: Scans the document for matching elements and attaches global window listeners.
• Retrofitting: The fastest way to add "vibe" to a legacy project without modifying individual components.

---

☀️ useEnvironmentalLight()

Treats the cursor as a physical point light source in 2D space, creating dynamic perspective-based shadows.

🔌 Usage

useEnvironmentalLight({ intensity: 0.8, color: '#ffffff' });

<div className="vibe-cast-shadow" />

🧠 Logic

• Global Variables: Sets --vibe-light-x and --vibe-light-y CSS variables on the document root.
• Shadow Leaning: Elements with the .vibe-cast-shadow class calculate box-shadow offsets that "lean" away from the cursor.

---

🖱️ usePhysicalDrag()

Bridges the gap between React gestures and the WASM physics simulation, allowing you to "throw" elements into the physical world.

🔌 Usage

const body = useBody(); // Access Rapier body
usePhysicalDrag(body, { stiffness: 400, damping: 15 });

🧠 Logic

• Impulse Mapping: Converts drag deltas into continuous physical impulses.
• Momentum: On release, it sets a physical linear velocity (setLinvel), allowing the object to maintain its "toss" momentum and bounce off other objects.

---

📐 useVibeLayout()

Custom FLIP-based layout animation hook enhanced by physical spring resistance.

🔌 Usage

const layoutRef = useVibeLayout(); 

<div ref={layoutRef} className={isActive ? "w-full" : "w-1/2"} />

🧠 Logic

• FLIP Technique: Captures the First/Last states, Inverts the delta, and plays back the motion via a physical spring simulation.
• Physical Resistance: Unlike standard easing, it uses real mass and tension to calculate the motion path, preventing robotic "tween" looks.