0.13.0

🎉 What's New

Embla Carousel Integration

This release implements Embla Carousel's official Thumbnails pattern for the Album components, providing smooth, accessible photo navigation with proper API-to-API synchronization.

✨ Features

AlbumViewer Enhancements

• 🎠 Embla Carousel Integration - Replaced custom navigation with Embla carousel
• 👆 Swipe Gestures - Native touch/swipe support for photo navigation
• 🔄 API Synchronization - Proper carousel sync between main viewer and thumbnails
• 📭 Empty State Support - New hideWhenEmpty and emptyStateContent props
• ⌨️ Enhanced Keyboard Navigation - Arrow keys and Escape integrated with Embla API

FilmStrip Improvements

• 🎠 Vertical Carousel - Converted to Embla carousel with vertical axis
• 🖱️ Mouse-Wheel Support - Added embla-carousel-wheel-gestures plugin for desktop accessibility
• 🎯 Drag-Free Scrolling - Natural, momentum-based thumbnail navigation
• 🔄 Smart Synchronization - API-to-API sync with main photo carousel
• 🎨 Vertical Centering - Better UX with centered thumbnail layout

Responsive Design

• 📱 3-Breakpoint System - Progressive enhancement across mobile (< 640px), tablet (≥ 640px), and desktop-wide (≥ 1024px)
• 📐 Adaptive Padding - 8px mobile → 16px tablet → 24px desktop-wide
• 👁️ Consistent Breakpoints - Sidebar visibility aligned with padding at 640px

🐛 Bug Fixes

Critical UX Issues Resolved

1. hideWhenEmpty Effects Issue

   • Problem: Body scroll lock and keyboard listeners mounted before early return, freezing page scroll when component returned null
   • Solution: Added isViewerVisible flag to conditionally run effects only when viewer is rendered
   • Impact: Prevents UX regression in "Hide When Empty" story

2. FilmStrip Thumbnail Clicks

   • Problem: Thumbnail clicks no-op when mainApi undefined/null, breaking standalone use and early clicks
   • Solution: Always call onSelect first, then conditionally scroll mainApi if available
   • Impact: Enables standalone FilmStrip use and handles early clicks gracefully

3. Mouse-Wheel Scrolling

   • Problem: FilmStrip used Embla with overflow:hidden, removing mouse-wheel scrolling for desktop users
   • Solution: Added embla-carousel-wheel-gestures plugin
   • Impact: Restored desktop accessibility with proper mouse-wheel support

📚 Documentation

• 📖 Comprehensive Responsive Docs - Added detailed responsive behavior section to Album pattern docs
• 🎯 Breakpoint Documentation - All three breakpoints and their behaviors fully documented
• 💡 Feature Descriptions - Updated with Embla carousel integration details

📦 Dependencies

• ➕ Added: embla-carousel-wheel-gestures@^8.1.0 - Mouse-wheel support for carousels

🔧 Technical Details

New Props

• AlbumViewer.hideWhenEmpty?: boolean - Hide viewer completely when album has no photos
• AlbumViewer.emptyStateContent?: React.ReactNode - Custom empty state content
• FilmStrip.mainApi?: EmblaCarouselType | null - Main carousel API for synchronization

Breaking Changes

None - This release is fully backward compatible.

🚀 Installation

npm install @ainativekit/ui@0.13.0

🙏 Acknowledgments

Thanks to the Embla Carousel team for their excellent carousel library and comprehensive documentation!
Full Changelog: v0.12.0...v0.13.0