feat: Add stopPropagation and event access support to useHover hook

[Cherryga]

🎯 Fixes Issue

Resolves streamich/react-use#2481

📋 Problem

I encountered a use case where I have multiple nested hoverable elements, and hovering over a child element triggers the hover on the parent as well due to event bubbling. I also needed access to the actual mouse events for more advanced hover interactions.

🔧 Solution

I've enhanced the useHover hook with optional configuration options that solve both issues while maintaining 100% backward compatibility.

1. stopPropagation Option

Prevents hover events from bubbling to parent elements: jsx const [childHoverable] = useHover( (hovered) =>

Child

, { stopPropagation: true } );

2. Event Access

Provides access to mouse events for advanced use cases: jsx const [hoverable] = useHover( (hovered) =>

Element

, { onMouseEnter: (event) => console.log('Mouse at:', event.clientX, event.clientY), onMouseLeave: (event) => console.log('Mouse left') } );

3. Combined Usage

You can use both options together: jsx const [element] = useHover( (hovered) =>

Interactive Element

, { stopPropagation: true, onMouseEnter: (event) => trackHoverStart(event), onMouseLeave: (event) => trackHoverEnd(event) } );

✅ Features

• ✅ 100% Backward Compatible - All existing code continues to work unchanged
• ✅ TypeScript Support - Full type safety with UseHoverOptions interface
• ✅ Event Propagation Control - Optional stopPropagation parameter
• ✅ Event Access - onMouseEnter/onMouseLeave callbacks with full event objects
• ✅ Preserves Original Handlers - Existing element handlers are maintained
• ✅ Production Ready - Comprehensive tests, documentation, and examples

📁 Files Changed

• src/useHover.ts - Enhanced hook implementation with new options
• src/index.ts - Updated TypeScript exports
• docs/useHover.md - Updated documentation with usage examples
• stories/useHover.story.tsx - Added comprehensive demo stories showing nested behavior
• tests/useHover.test.tsx - Added 17 comprehensive tests covering all scenarios

🧪 Testing

I've added comprehensive test coverage:

• ✅ Backward compatibility tests (no breaking changes)
• ✅ stopPropagation functionality tests
• ✅ Event callback access tests
• ✅ Combined options tests
• ✅ Edge case handling tests
• ✅ All 17 tests pass
• ✅ TypeScript compilation successful
• ✅ ESLint passes

📝 Type Definition

typescript interface UseHoverOptions { /** Prevents hover events from bubbling to parent elements / stopPropagation?: boolean; /* Callback when mouse enters - provides access to mouse event / onMouseEnter?: (event: React.MouseEvent) => void; /* Callback when mouse leaves - provides access to mouse event */ onMouseLeave?: (event: React.MouseEvent) => void; }

const useHover = ( element: Element, options?: UseHoverOptions ): [React.ReactElement, boolean]

This enhancement makes useHover much more powerful for complex interactive UIs while maintaining the simplicity that makes react-use great.