feat: Add overlap detection plugin with visual helpers and performance optimizations

[sheryianscodingschool]

🎯 Overview

This PR introduces a new overlap detection plugin that enables real-time detection when draggable elements intersect with other elements on the page. The plugin provides comprehensive event callbacks, visual debugging helpers, and performance optimizations for smooth user experiences.

✨ Features Added

Core Functionality

• Real-time overlap detection with configurable threshold sensitivity
• Multiple target selection via CSS selectors, element arrays, or mixed formats
• Event system with onOverlapStart, onOverlapEnd, and onOverlapUpdate callbacks
• Flexible frequency control with frame-based or interval-based checking

Visual Debugging

• Visual helpers with customizable border colors for drag, target, and overlap states
• Development-friendly visual feedback system that can be disabled in production
• Color theming support for different use cases (game-style, professional, etc.)

Performance Optimizations

• Intersection Observer integration for viewport-based optimizations
• Resize Observer for efficient element size/position tracking
• Element caching with smart cache invalidation
• Overlay pooling for reusing visual indicator elements
• Optimized collision detection with fast intersection checks

🚀 Usage Examples

Basic Implementation

overlap({
  targets: '.drop-zone',
  threshold: 0.1,
  onOverlapUpdate: (targets) => {
    console.log('Overlapping with:', targets.length, 'elements');
  }
})

Advanced Configuration

overlap({
  targets: ['.folder', '.trash-bin', '#upload-area'],
  threshold: 0.4,
  checkFrequency: 'frame',
  showOverlap: {
    enabled: true,
    dragColor: '#00ff88',
    targetColor: '#0088ff',
    overlapColor: '#ff0000'
  },
  onOverlapStart: (target) => target.classList.add('highlight'),
  onOverlapEnd: (target) => target.classList.remove('highlight')
})

📋 Implementation Details

📚 Documentation

• Comprehensive documentation added to /docs/src/content/plugin/13-overlap/+page.mdx
• Interactive examples for all supported frameworks
• Visual helper demonstrations with customization options
• Performance tips and best practices
• Real-world use cases (file managers, games, collision detection)

🎮 Demo Integration

• Added overlap detection example to the Kitchen Sink Demo
• Demonstrates visual helpers with toggle control
• Shows real-time overlap counting
• Integrates seamlessly with existing examples

🛠 Technical Highlights

Observer-Based Optimization

// Intersection Observer for viewport optimization
intersectionObserver = new IntersectionObserver((entries) => {
  // Only track elements in viewport
}, { rootMargin: '50px', threshold: 0 });

// Resize Observer for efficient size tracking
resizeObserver = new ResizeObserver((entries) => {
  // Update element caches on size changes
});

Ultra-Fast Collision Detection

const getOverlapPercentage = (a: DOMRect, b: DOMRect) => {
  const intersection = Math.max(0, Math.min(a.right, b.right) - Math.max(a.left, b.left)) *
                     Math.max(0, Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top));
  return intersection / (a.width * a.height || 1);
};

🔧 Configuration Options

Option	Type	Default	Description
targets	string | string[] | HTMLElement[]	undefined	Elements to check for overlaps
threshold	number	0.01	Minimum overlap percentage (0.01 = 1%)
oncePerTarget	boolean	true	Fire start/end events once per element
checkFrequency	number | 'frame'	'frame'	Detection frequency
showOverlap	ShowOverlapConfig	{ enabled: false }	Visual debugging options

🎯 Use Cases

• Drag & Drop interfaces with visual drop zone feedback
• File management systems with folder/trash interactions
• Game development with collision detection and proximity zones
• Interactive dashboards with widget placement validation
• Form builders with component organization

✅ Testing

• Tested across all supported frameworks
• Performance validated with multiple elements
• Visual helpers verified in different scenarios
• Memory leak prevention confirmed
• Cross-browser compatibility ensured

🏗 Future Enhancements

• Potential for multi-directional overlap detection
• Advanced collision shapes (circles, polygons)
• Overlap percentage callbacks for gradual effects
• Integration with physics engines

---

Developed and maintained by Sheryians
Author: Aayush Chouhan

[changeset-bot]

🦋 Changeset detected

Latest commit: 5dae68f

The changes in this PR will be included in the next version bump.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

@aayushchouhan24 is attempting to deploy a commit to the Purus Projects Team on Vercel.

A member of the Team first needs to authorize it.

[sheryianscodingschool]

Hi @PuruVJ ,

I hope you're doing well! Just wanted to follow up on the overlap detection plugin PR.

I've put significant effort into this feature and believe it would be a valuable addition to neodrag. Would you be able to review it when you have a moment?

If any changes are needed, I'm available to make adjustments quickly.

Thanks for your time!

Best regards,
Aayush Chouhan

[PuruVJ]

Hey Ayush, thanks for contributing. I work on Open source stuff like this in my free time and in cycles, and am not focusing on neodrag for the current cycle. I will gladly review and merge this into core after a thorough inspection, which might take some time. Please have some patience :) Thanks!

[sheryianscodingschool]

Hi @PuruVJ ,

Thank you for getting back to me! I completely understand open source work takes time, and priorities can shift. I appreciate you letting me know, and I’m happy to wait for your review whenever your schedule allows.

If you have any questions or need further info when you get to it, feel free to tag me. Thanks again for maintaining neodrag and for your openness!

Best,
Aayush

[sheryianscodingschool]

Hi @PuruVJ ,

Hope you’re doing well! I wanted to follow up on the overlap detection plugin PR. I know open source work often happens in cycles, but I’m really excited about this feature and believe it could bring a lot of value to neodrag users.

If it helps, I can provide additional examples, benchmarks, or documentation to make the review process quicker. My goal is to make this as easy as possible for you so it can be reviewed and merged when feasible.

Thanks again for your time and for all the effort you put into maintaining neodrag — it’s greatly appreciated!

Best regards,
Aayush