Find alternative drawer solution for EntityBrowser

[fx]

Context

Issue #136 requested replacing FullscreenModal with a drawer for non-camera dialogs. We attempted to implement this using Vaul (https://vaul.emilkowal.ski/), which is based on Radix Dialog primitives.

Problem

While Vaul works well in development, it has significant compatibility issues with the test environment:

• The library tries to access DOM properties (transform, style.transform) that aren't properly available in jsdom
• Mocking the library proved complex due to its internal state management
• The errors occur during pointer event handling, making it difficult to test user interactions

Requirements

We need a drawer solution that:

1. Works seamlessly in both development and test environments
2. Provides smooth slide-in animations from any edge (left, right, top, bottom)
3. Integrates well with Radix UI Theme components
4. Supports proper accessibility features
5. Handles click-outside-to-close and ESC key interactions

Potential Solutions

1. Radix UI Dialog with custom CSS - Use the standard Radix Dialog with CSS transforms for drawer behavior
2. React Aria Components - Adobe's React Aria has a drawer component that might be more test-friendly
3. Custom implementation - Build a simple drawer using React Portal and CSS transitions
4. Alternative libraries - Research other drawer libraries with better test compatibility

Related

• Original issue: Fullscreen modal should only be used for CameraCard #136
• Failed PR: fix: replace FullscreenModal with Drawer for non-camera dialogs #142

[fx]

Implementation Plan: Find alternative drawer solution for EntityBrowser

Overview

Replace the FullscreenModal with a drawer component for EntityBrowser that is compatible with both development and test environments (jsdom). The solution will use Radix UI Dialog primitive with custom CSS transitions to create a drawer effect, avoiding the jsdom compatibility issues encountered with the Vaul library.

Technical Approach

Architecture

• Drawer Component: Built on Radix UI Dialog.Root primitive with CSS-based sliding animations
• Portal Rendering: Uses Radix Dialog's built-in portal to escape shadow DOM
• CSS Transitions: Pure CSS transforms for slide animations (no JavaScript calculations)
• Test-Friendly: No dependency on unsupported DOM APIs (visualViewport, setPointerCapture)

Technology Stack

• Radix UI Dialog: Base primitive for modal behavior and portal rendering
• CSS Transitions: For smooth slide animations
• React Portal: Built into Radix Dialog for proper z-index management
• TypeScript: Full type safety for drawer props and configurations

Design Patterns

• Composition Pattern: Drawer built as a wrapper around Dialog.Root
• CSS State Classes: Animation states managed via CSS classes, not dynamic transforms
• Progressive Enhancement: Basic functionality works without animations in test environment

Implementation Steps

Phase 1: Create the Drawer Component

1. Task 1.1: Create base Drawer component

   • Details: Create /workspace/src/components/ui/Drawer.tsx with Radix Dialog wrapper
   • Files: src/components/ui/Drawer.tsx
   • Dependencies: None
   • Testing: Unit tests for open/close states and prop handling

2. Task 1.2: Implement CSS-based slide animations

   • Details: Add CSS classes for slide-in/slide-out from all directions (left, right, top, bottom)
   • Files: src/components/ui/Drawer.tsx, src/styles/drawer.css
   • Dependencies: Task 1.1
   • Testing: Visual testing in browser, class-based testing in jsdom

3. Task 1.3: Add drawer interaction handlers

   • Details: Implement click-outside, ESC key, and touch gesture support
   • Files: src/components/ui/Drawer.tsx
   • Dependencies: Tasks 1.1, 1.2
   • Testing: Interaction tests using Testing Library events

4. Task 1.4: Export Drawer from ui index

   • Details: Add Drawer export to /workspace/src/components/ui/index.ts
   • Files: src/components/ui/index.ts
   • Dependencies: Task 1.1
   • Testing: Import/export verification

Phase 2: Update EntityBrowser Implementation

5. Task 2.1: Replace FullscreenModal with Drawer in EntityBrowser

   • Details: Update EntityBrowser to use Drawer component with right-side positioning
   • Files: src/components/EntityBrowser.tsx
   • Dependencies: Phase 1 completion
   • Testing: Ensure all existing EntityBrowser tests pass

6. Task 2.2: Adjust EntityBrowser layout for drawer format

   • Details: Optimize Card dimensions and content layout for drawer presentation
   • Files: src/components/EntityBrowser.tsx
   • Dependencies: Task 2.1
   • Testing: Visual testing, responsive behavior

7. Task 2.3: Update EntityBrowser tests if needed

   • Details: Verify and update tests to work with drawer implementation
   • Files: src/components/__tests__/EntityBrowser.test.tsx
   • Dependencies: Task 2.1
   • Testing: Run full test suite, ensure no regressions

Phase 3: Verification and Polish

8. Task 3.1: Cross-browser testing

   • Details: Test drawer behavior in Chrome, Firefox, Safari, and mobile browsers
   • Files: None (testing only)
   • Dependencies: Phase 2 completion
   • Testing: Manual testing across browsers

9. Task 3.2: Performance optimization

   • Details: Ensure smooth animations and no layout thrashing
   • Files: May update src/components/ui/Drawer.tsx
   • Dependencies: Phase 2 completion
   • Testing: Performance profiling in DevTools

10. Task 3.3: Accessibility audit

    • Details: Verify ARIA attributes, focus management, and keyboard navigation
    • Files: May update src/components/ui/Drawer.tsx
    • Dependencies: Phase 2 completion
    • Testing: Accessibility testing tools and keyboard navigation

Testing Strategy

1. Unit Tests:

   • Drawer component props and state management
   • CSS class application based on props
   • Event handler functionality
   • Portal rendering behavior

2. Integration Tests:

   • EntityBrowser with drawer implementation
   • Entity selection workflow
   • Keyboard navigation through drawer content
   • Focus trap behavior

3. E2E Tests:

   • Full user flow: open drawer → select entities → add to grid
   • Animation smoothness (visual regression tests)
   • Mobile touch interactions

Risk Assessment

• Risk 1: CSS animations may have different behavior across browsers

  • Mitigation: Use well-supported CSS properties, provide fallbacks

• Risk 2: Focus management complexity with Radix Dialog

  • Mitigation: Leverage Radix's built-in focus management, test thoroughly

• Risk 3: Performance issues with large entity lists in drawer

  • Mitigation: EntityBrowser already uses virtualization, ensure it works in drawer

• Risk 4: Drawer may not provide enough space on mobile devices

  • Mitigation: Make drawer full-width on small screens, test responsive behavior

Success Criteria Checklist

• Drawer component created with support for all four directions
• EntityBrowser updated to use drawer instead of FullscreenModal
• All existing EntityBrowser tests pass without modification
• No jsdom-specific errors or warnings in test output
• Smooth animations in development environment
• Click-outside and ESC key functionality working
• Proper accessibility attributes implemented
• Performance is comparable to current FullscreenModal
• CameraCard continues to use FullscreenModal unchanged
• Code follows Radix UI styling best practices

Estimated Timeline

• Phase 1: 2-3 hours (Drawer component creation)
• Phase 2: 1-2 hours (EntityBrowser integration)
• Phase 3: 1-2 hours (Testing and polish)
• Total: 4-7 hours

Additional Notes

The implementation will prioritize test compatibility while maintaining a smooth user experience. By using CSS-based animations and Radix Dialog's built-in features, we avoid the jsdom issues that plagued the Vaul implementation while still delivering a polished drawer component.

---

This plan was automatically generated and will be used for implementation.

[fx]

📊 Status Update

Current Status: Completed
Branch: refactor/143-vaul-removal
Progress:

• ✅ Removed Vaul dependency
• ✅ Replaced with Radix UI Dialog + custom animations
• ✅ All tests passing
• ✅ Smooth drawer animations maintained
• ✅ Pull request created

Pull Request: #144

The drawer functionality has been successfully reimplemented using Radix UI Dialog with custom CSS animations. This solution provides the same smooth drawer experience while being fully compatible with the test environment.

---

Updated on 2025-07-29 02:35:27

[fx]

📊 Status Update - Correction

Current Status: Completed ✅
Branch: refactor/143-vaul-removal
Progress:

• ✅ Removed Vaul dependency
• ✅ Replaced with custom Drawer component using Radix Dialog + CSS animations
• ✅ All tests passing
• ✅ Smooth drawer animations maintained
• ✅ Pull request created and submitted

Pull Request: #145 (not #144 as previously stated)

The drawer functionality has been successfully reimplemented using a custom Drawer component built on Radix UI Dialog primitives with CSS animations. This solution provides the same smooth drawer experience while being fully compatible with the test environment.

---

Updated on 2025-07-29 02:36:13