docs: add comprehensive mobile implementation documentation

MOBILE_IMPLEMENTATION.md

@@ -0,0 +1,156 @@
+# Mobile Implementation Summary
+
+## Overview
+Boris is now mobile-friendly! The app now works seamlessly on mobile devices with a responsive design that includes:
+- Auto-collapsing sidebar that opens as an overlay drawer on small screens
+- Touch-optimized UI with proper touch target sizes (44x44px minimum)
+- Safe area insets for notched devices (iPhone X+, etc.)
+- Focus trap and keyboard navigation in the mobile sidebar
+- Mobile-optimized modals, toasts, and other UI elements
+
+## Changes Made
+
+### 1. Viewport & Base Setup
+**File: `index.html`**
+- Updated viewport meta tag to include `viewport-fit=cover` for proper safe area handling
+
+### 2. Media Query Hooks
+**File: `src/hooks/useMediaQuery.ts` (NEW)**
+- `useMediaQuery(query)` - Generic hook for any media query
+- `useIsMobile()` - Detects mobile viewport (≤768px)
+- `useIsTablet()` - Detects tablet viewport (≤1024px)
+- `useIsCoarsePointer()` - Detects touch devices
+
+### 3. Mobile CSS Styles
+**File: `src/index.css`**
+- Added CSS custom properties for mobile breakpoints and safe areas
+- Mobile-specific three-pane layout that stacks into single column
+- Overlay sidebar with backdrop and transitions
+- Touch target improvements (44x44px minimum)
+- Disabled hover effects on touch devices
+- Mobile-optimized modals (full-screen sheet style)
+- Mobile-optimized toasts (bottom position with safe area)
+- Dynamic viewport height support (`100dvh`)
+- Overscroll behavior and body scroll locking
+
+### 4. Sidebar State Management
+**File: `src/hooks/useBookmarksUI.ts`**
+- Added `isMobile` state from media query
+- Added `isSidebarOpen` state for mobile overlay
+- Added `toggleSidebar()` function
+- Auto-collapse logic based on `autoCollapseSidebarOnMobile` setting
+- Mobile sidebar defaults to closed, desktop defaults to open
+
+### 5. Three-Pane Layout Mobile Support
+**File: `src/components/ThreePaneLayout.tsx`**
+- Mobile hamburger button (visible only on mobile)
+- Mobile backdrop for closing sidebar
+- Body scroll locking when sidebar is open
+- ESC key handler to close sidebar
+- Focus trap in sidebar (Tab navigation stays within sidebar)
+- Focus restoration when closing sidebar
+- Accessibility attributes (`aria-hidden`, `aria-expanded`, etc.)
+
+### 6. Sidebar Header Mobile Controls
+**File: `src/components/SidebarHeader.tsx`**
+- Close button (X) visible on mobile instead of collapse chevron
+- Hamburger button hidden in header (shown in layout instead)
+
+### 7. Bookmark List Mobile Props
+**File: `src/components/BookmarkList.tsx`**
+- Added `isMobile` prop support
+- Passes mobile state to SidebarHeader
+
+### 8. Main Bookmarks Component
+**File: `src/components/Bookmarks.tsx`**
+- Uses mobile state from `useBookmarksUI`
+- Auto-closes sidebar when selecting bookmark on mobile
+- Closes sidebar when opening settings on mobile
+- Proper desktop/mobile toggle behavior
+
+### 9. Icon Button Enhancement
+**File: `src/components/IconButton.tsx`**
+- Added optional `className` prop for additional styling
+
+### 10. Mobile Settings
+**File: `src/services/settingsService.ts`**
+- Added `autoCollapseSidebarOnMobile?: boolean` setting (default: true)
+
+**File: `src/components/Settings/StartupPreferencesSettings.tsx`**
+- Added UI toggle for "Auto-collapse sidebar on small screens"
+
+## Accessibility Features
+- Focus trap in mobile sidebar (Tab key navigation stays within drawer)
+- ESC key closes mobile sidebar
+- Backdrop click closes mobile sidebar
+- Proper ARIA attributes (`aria-hidden`, `aria-expanded`, `aria-controls`)
+- Touch target minimum size enforcement (44x44px)
+- Focus restoration when closing sidebar
+
+## Mobile Behaviors
+1. **Sidebar**: Slides in from left as overlay drawer with backdrop
+2. **Hamburger Menu**: Fixed position top-left when sidebar closed
+3. **Selecting Content**: Auto-closes sidebar on mobile
+4. **Opening Settings**: Auto-closes sidebar on mobile
+5. **Highlights Panel**: Hidden on mobile (content takes full width)
+6. **Modals**: Full-screen sheet style from bottom
+7. **Toasts**: Bottom position with safe area padding
+
+## Responsive Breakpoints
+- **Mobile**: ≤768px (sidebar overlay, single column)
+- **Tablet**: ≤1024px (defined but not actively used yet)
+- **Desktop**: >768px (three-pane layout as before)
+
+## Browser Support
+- Modern browsers with CSS Grid support
+- iOS Safari (including safe area insets)
+- Chrome for Android
+- Firefox Mobile
+- Safari on iPadOS
+
+## Safe Area Support
+The app respects device safe areas (notches, home indicators) through CSS environment variables:
+- `env(safe-area-inset-top)`
+- `env(safe-area-inset-bottom)`
+- `env(safe-area-inset-left)`
+- `env(safe-area-inset-right)`
+
+## Future Enhancements
+Potential improvements for future iterations:
+- Swipe gesture to open/close sidebar
+- Pull-to-refresh on mobile
+- Bottom sheet for highlights panel on mobile
+- Optimized font sizes for mobile reading
+- Mobile-specific view mode (perhaps auto-switch to compact on mobile)
+- Haptic feedback on interactions (iOS/Android)
+- Share sheet integration
+- Install prompt for PWA
+
+## Testing Checklist
+- [x] Sidebar opens/closes on mobile
+- [x] Hamburger button visible on mobile
+- [x] Backdrop closes sidebar
+- [x] ESC key closes sidebar
+- [x] Focus trap works in sidebar
+- [x] Selecting bookmark closes sidebar
+- [x] No horizontal scroll
+- [x] Touch targets ≥ 44px
+- [x] Modals are full-screen on mobile
+- [x] Toasts appear at bottom with safe area
+- [x] Build completes without errors
+- [ ] Test on actual iOS device (iPhone)
+- [ ] Test on actual Android device
+- [ ] Test with keyboard navigation
+- [ ] Test with screen reader
+- [ ] Test landscape orientation
+- [ ] Test on various screen sizes (320px, 375px, 414px, 768px)
+
+## Commit History
+1. `feat: update viewport meta for mobile support`
+2. `feat: add media query hooks for responsive design`
+3. `feat: add mobile sidebar state management to useBookmarksUI`
+4. `feat: add mobile-responsive CSS with breakpoints and safe areas`
+5. `feat: implement mobile overlay sidebar with focus trap and ESC handling`
+6. `feat: add mobile auto-collapse setting`
+7. `fix: resolve TypeScript errors for mobile implementation`
+