feat: implement efficient modal stacking and automatic z-index management

[Agbasimere]

Closes #364

Description

This PR implements proper dialog/modal stacking with automatic z-index management. It resolves modal layering issues (especially prominent on React Native Web) and coordinate multiple modals opened simultaneously.

Fixes #364

Key Changes

1. Stacking Manager & Hook

• ModalStackManager (singleton): Maintains a global order of active modals.
• Auto-Assigned z-index: Auto-calculates unique, ascending z-indices starting from 10000 with a step size of 10 (10000, 10010, 10020, etc.).
• Duplicate Handling: Automatically moves already registered modals to the top of the stack.
• useModalStack(id, visible) Hook: Handles visibility-based registration and supplies reactive zIndex and isTop variables.

2. ModalPortal Integration

• Introduced ModalPortalWrapper: Subscribes to the stack manager's z-index updates.
• Updated ModalPortalHost: Automatically wraps all portalled components inside ModalPortalWrapper to ensure correct layering styles.

3. AccessibleModal Stack Enforcement

• Added an optional id prop for explicit identification.
• Pauses focus trapping for background/lower modals in the stack (visible && isTop parameter passed to useFocusTrap). This prevents multiple focus traps from conflicts.
• Restricts backdrop overlay click dismissals and hardware back/Escape key closures to the top-most modal (isTop).
• Automatically applies the calculated zIndex style to the modal backdrop overlay.

4. Documentation

• Documented the stacking architecture, hook usages, and stack rules in docs/modal-portal-pattern.md.

---

Verification Results

Automated Tests

Created a new test suite in src/__tests__/components/ModalStackManager.test.tsx containing 8 tests covering stack management, auto-assigned z-index sequences, top-most modal checks, duplicate resolution, and reactive hook updates.

Ran the test suite successfully (all 16 tests passed):

npx jest src/__tests__/components/ModalPortal.test.tsx src/__tests__/components/ModalStackManager.test.tsx tests/components/AccessibleModal.test.tsx

[drips-wave]

@Agbasimere Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[RUKAYAT-CODER]

Thank you for contributing to the project