();
const handleTouchStart = (e: React.TouchEvent) => {
// Start long-press detection
longPressTimer.current = window.setTimeout(() => {
setIsLongPress(true);
selectWidget(widgetId);
triggerHaptic('select');
}, 350);
};
const handleTouchEnd = () => {
clearTimeout(longPressTimer.current);
if (!isLongPress) {
// Single tap - toggle selection or open
selectWidget(widgetId);
triggerHaptic('light');
}
setIsLongPress(false);
};
const handleTouchMove = () => {
// Cancel long-press if finger moves
clearTimeout(longPressTimer.current);
};
return { handleTouchStart, handleTouchEnd, handleTouchMove };
}
```
---
## CSS Responsive Patterns
### Using the Responsive CSS System
Import responsive styles in your component CSS modules:
```css
/* MyComponent.module.css */
@import '@/styles/responsive.css';
.container {
padding: var(--spacing-md);
/* Mobile-first: default is mobile */
display: flex;
flex-direction: column;
}
/* Tablet and up */
@media (min-width: 768px) {
.container {
flex-direction: row;
padding: var(--spacing-lg);
}
}
/* Desktop and up */
@media (min-width: 1024px) {
.container {
padding: var(--spacing-xl);
}
}
/* Touch-specific styles */
@media (pointer: coarse) {
.button {
min-height: 44px;
min-width: 44px;
padding: var(--spacing-md);
}
}
/* High precision pointer (mouse) */
@media (pointer: fine) {
.button {
min-height: 32px;
}
}
/* Respect reduced motion preference */
@media (prefers-reduced-motion: reduce) {
.animated {
animation: none;
transition: none;
}
}
```
### Safe Area Handling
```css
.bottom-toolbar {
position: fixed;
bottom: 0;
left: 0;
right: 0;
/* Account for iPhone notch/home indicator */
padding-bottom: env(safe-area-inset-bottom, 0);
padding-left: env(safe-area-inset-left, 0);
padding-right: env(safe-area-inset-right, 0);
}
.top-header {
padding-top: env(safe-area-inset-top, 0);
}
```
### Preventing Unwanted Touch Behaviors
```css
/* Prevent pull-to-refresh on the canvas */
.canvas-container {
overscroll-behavior: none;
}
/* Prevent zoom on double-tap for inputs */
input, textarea, select {
font-size: 16px; /* Prevents iOS zoom on focus */
}
/* Prevent text selection during interactions */
.interactive-element {
user-select: none;
-webkit-user-select: none;
-webkit-touch-callout: none;
}
/* Remove tap highlight on iOS */
.button {
-webkit-tap-highlight-color: transparent;
}
/* Proper touch action for different elements */
.scrollable {
touch-action: pan-y;
}
.zoomable {
touch-action: pinch-zoom pan-x pan-y;
}
.draggable {
touch-action: none;
}
```
---
## Mobile Accessibility Checklist
### Touch Targets
- [ ] All interactive elements are at least 44×44px
- [ ] Touch targets have 8px minimum spacing
- [ ] Resize/rotate handles are enlarged on touch devices
### Visual Feedback
- [ ] Touch states provide visual feedback (scale, color change)
- [ ] Haptic feedback on key interactions
- [ ] Loading states are visible during async operations
### Gestures
- [ ] All gestures have alternative methods (buttons)
- [ ] Gesture hints shown on first use
- [ ] Long-press doesn't conflict with scroll
### Keyboard & Screen Readers
- [ ] Virtual keyboard doesn't obscure inputs
- [ ] Focus management works with keyboard navigation
- [ ] ARIA labels on icon-only buttons
### Performance
- [ ] Animations respect `prefers-reduced-motion`
- [ ] Heavy operations don't block main thread
- [ ] Images are lazy-loaded and properly sized
---
## Step-by-Step: Adding Mobile Support to a Component
### Step 1: Add Responsive Hooks
```typescript
import { useViewport, useTouchDevice, useSafeArea } from '@/hooks/useResponsive';
function MyComponent() {
const { isMobile, isTablet } = useViewport();
const { hasTouch } = useTouchDevice();
const safeArea = useSafeArea();
```
### Step 2: Conditional Rendering
```typescript
return (
{isMobile ? (
{/* Mobile-optimized UI */}
) : (
{/* Desktop UI */}
)}
);
}
```
### Step 3: Add Touch Interactions
```typescript
const handleInteraction = (e: React.PointerEvent) => {
if (e.pointerType === 'touch') {
// Touch-specific handling
haptic.light();
}
// Common logic
};
```
### Step 4: Update CSS
```css
.my-component {
/* Mobile-first base styles */
padding: 16px;
}
@media (min-width: 768px) {
.my-component {
padding: 24px;
}
}
@media (pointer: coarse) {
.my-component .button {
min-height: 44px;
}
}
```
---
## Reference Files
### Core Mobile Infrastructure
- **Responsive Hooks**: `src/hooks/useResponsive.ts`
- **Responsive CSS**: `src/styles/responsive.css`
- **Canvas Gestures**: `src/hooks/useCanvasGestures.ts`
- **Haptic Feedback**: `src/utils/haptics.ts`
### Mobile Components
- **Mobile Navigation**: `src/components/MobileNav.tsx`
- **Responsive Layout**: `src/components/ResponsiveCanvasLayout.tsx`
### Canvas & Interactions
- **Main Canvas**: `src/canvas/Canvas2.tsx`
- **Unified Interactions**: `src/canvas/interactions/useUnifiedInteraction.ts`
- **Drag Controller**: `src/canvas/interactions/useDragController.ts`
- **Resize Controller**: `src/canvas/interactions/useResizeController.ts`
- **Coordinate Service**: `src/canvas/CoordinateService.ts`
### State Management
- **Canvas Store**: `src/state/useCanvasStore.ts`
- **Selection Store**: `src/state/useSelectionStore.ts`
### CSS Modules with Mobile Styles
- **Canvas Page**: `src/pages/CanvasPage.module.css`
- **Canvas Toolbar**: `src/canvas/CanvasToolbar.module.css`
- **Zoom Controls**: `src/components/ZoomControls.module.css`
---
## Troubleshooting
### Issue: Pinch-to-zoom zooms the entire page instead of canvas
**Cause**: Missing `touch-action: none` on canvas container
**Fix**: Add `touch-action: none` to the canvas wrapper and handle all gestures manually
### Issue: Scroll conflicts with canvas pan
**Cause**: Parent scrollable container capturing touch events
**Fix**: Use `overscroll-behavior: none` on canvas and `touch-action: pan-y` on scrollable areas only
### Issue: Touch targets too small on mobile
**Cause**: Fixed pixel sizes not accounting for touch input
**Fix**: Use `@media (pointer: coarse)` to increase sizes for touch devices
### Issue: Content hidden behind iPhone notch
**Cause**: Missing safe area insets
**Fix**: Apply `env(safe-area-inset-*)` padding to edge-positioned elements
### Issue: Virtual keyboard covers input
**Cause**: Fixed positioning doesn't account for keyboard
**Fix**: Use `useKeyboardVisible()` hook to adjust layout when keyboard is open
### Issue: Gestures trigger during text selection
**Cause**: Missing prevention of default behaviors
**Fix**: Add `user-select: none` and `-webkit-touch-callout: none` to gesture areas
### Issue: Animations cause jank on mobile
**Cause**: Expensive animations or not using GPU acceleration
**Fix**: Use `transform` and `opacity` for animations, add `will-change` hints, respect `prefers-reduced-motion`
---
## Advanced: Implementing Swipe Gestures
For swipe gestures not covered by `useCanvasGestures`:
```typescript
// src/hooks/useSwipeGesture.ts
import { useRef, useCallback } from 'react';
interface SwipeConfig {
threshold?: number; // Minimum distance for swipe (default: 50)
velocity?: number; // Minimum velocity (default: 0.3)
direction?: 'horizontal' | 'vertical' | 'both';
onSwipeLeft?: () => void;
onSwipeRight?: () => void;
onSwipeUp?: () => void;
onSwipeDown?: () => void;
}
export function useSwipeGesture(config: SwipeConfig) {
const startPos = useRef({ x: 0, y: 0 });
const startTime = useRef(0);
const handleTouchStart = useCallback((e: React.TouchEvent) => {
const touch = e.touches[0];
startPos.current = { x: touch.clientX, y: touch.clientY };
startTime.current = Date.now();
}, []);
const handleTouchEnd = useCallback((e: React.TouchEvent) => {
const touch = e.changedTouches[0];
const deltaX = touch.clientX - startPos.current.x;
const deltaY = touch.clientY - startPos.current.y;
const elapsed = Date.now() - startTime.current;
const velocityX = Math.abs(deltaX) / elapsed;
const velocityY = Math.abs(deltaY) / elapsed;
const threshold = config.threshold ?? 50;
const minVelocity = config.velocity ?? 0.3;
// Detect horizontal swipe
if (Math.abs(deltaX) > threshold && velocityX > minVelocity) {
if (deltaX > 0) {
config.onSwipeRight?.();
} else {
config.onSwipeLeft?.();
}
}
// Detect vertical swipe
if (Math.abs(deltaY) > threshold && velocityY > minVelocity) {
if (deltaY > 0) {
config.onSwipeDown?.();
} else {
config.onSwipeUp?.();
}
}
}, [config]);
return { handleTouchStart, handleTouchEnd };
}
```
---
## Testing Mobile on Desktop
### Chrome DevTools
1. Open DevTools (F12)
2. Toggle device toolbar (Ctrl+Shift+M)
3. Select device preset or set custom dimensions
4. Enable touch simulation in device toolbar
### Testing Gestures
- Use touch simulation in DevTools
- Test on actual devices for accurate gesture behavior
- Use BrowserStack or similar for device matrix testing
### Common Test Scenarios
1. Pinch zoom on canvas - verify smooth zoom at cursor position
2. Two-finger pan - verify momentum continues after release
3. Double-tap zoom - verify toggles between 1x and 2x
4. Long-press widget - verify selection with haptic feedback
5. Rotate device - verify layout adapts correctly
6. Open keyboard - verify content remains visible
7. Scroll content - verify no conflicts with canvas gestures