refactor: migrate event based store

[jungpaeng]

Description

This PR resolves issues with component unmounting caused by conflicts between useSyncExternalStore (uSES) and React's scheduler.

We've replaced the useSyncExternalStore-based state management with a useReducer and event-based system to stabilize component lifecycle management.

Related Issue: Fixes #148

Changes

• Removed useSyncExternalStore-related logic
• Introduced reducer pattern for overlay state management
• Implemented external event system (createUseExternalEvents)
• Improved state management during component mount/unmount cycles
• Enhanced overlay action processing sequence (ADD -> OPEN, REMOVE, etc.)

Motivation and Context

The previous implementation had several issues:

1. When unmounting overlay components, the REMOVE action was executed, but the final state showed a sequence of REMOVE action -> ADD action, causing the isOpen prop to incorrectly change from true to false
2. The OPEN action was designed to run after component mounting (since components typically mount after ADD is executed), but it was being interpreted as a simple prop change, preventing the OPEN action from executing
3. useEffect return callbacks were not executing properly

These issues stemmed from differences between React's scheduling and how useSyncExternalStore works. This PR addresses these fundamental problems by changing the state management approach.

How Has This Been Tested?

• Tested overlay component mount/unmount scenarios
• Verified useEffect cleanup function execution
• Added tests for the following scenario:

  unmount('target-overlay');
  open(..., { overlayId: 'target-overlay' });

• Validated component lifecycle event sequence
• Verified prop updates according to state changes

Screenshots (if appropriate):

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have performed a self-review of my own code.
• My code is commented, particularly in hard-to-understand areas.
• I have made corresponding changes to the documentation.
• My changes generate no new warnings.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• Any dependent changes have been merged and published in downstream modules.

Further Comments

This change addresses fundamental issues with React scheduling and state management, overcoming the limitations of the useSyncExternalStore-based implementation to provide more stable component lifecycle management. Key improvements include:

• Removal of useSyncExternalStore: Resolves conflicts between unmounting and remounting timing
• React scheduler: Allows for response optimization
• Component perspective: Ensures proper lifecycle event handling rather than just prop changes

The critical insight was that we needed to abandon useSyncExternalStore (which doesn't work well even with flushSync) and implement our own queue management system that works independently from React's scheduler.

[changeset-bot]

🦋 Changeset detected

Latest commit: 59b56ff

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

This PR includes changesets to release 1 package

Name	Type
overlay-kit	Minor

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]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
overlay-kit	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 1, 2025 3:31am

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 95.23810% with 6 lines in your changes missing coverage. Please review.

Project coverage is 94.32%. Comparing base (f0f878c) to head (59b56ff).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #149      +/-   ##
==========================================
- Coverage   95.84%   94.32%   -1.52%     
==========================================
  Files          12       12              
  Lines         289      335      +46     
  Branches       73       86      +13     
==========================================
+ Hits          277      316      +39     
- Misses         10       18       +8     
+ Partials        2        1       -1     

Components	Coverage Δ
overlay-kit	94.32% <95.23%> (-1.52%)	⬇️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.