# Responsive Design Documentation

## Overview

Karibeo está completamente optimizado para funcionar en dispositivos móviles, tablets y escritorio. Esta documentación detalla las estrategias de diseño responsivo implementadas.

## Breakpoints

El proyecto utiliza breakpoints estándar de Tailwind CSS:

```typescript
const BREAKPOINTS = {
  mobile: 768,    // < 768px
  tablet: 1024,   // 768px - 1023px
  desktop: 1280,  // 1024px - 1279px
  largeDesktop: 1280+ // >= 1280px
}
```

## Hooks Personalizados

### useResponsive

Hook para detectar el breakpoint actual:

```typescript
import { useResponsive } from '@/hooks/useResponsive';

const { isMobile, isTablet, isDesktop, width } = useResponsive();
```

### useOrientation

Hook para detectar orientación del dispositivo:

```typescript
import { useOrientation } from '@/hooks/useResponsive';

const orientation = useOrientation(); // 'portrait' | 'landscape'
```

## Frontend Responsive

### Dashboard Layout

- **Sidebar**: Oculto en móvil, colapsable en desktop
- **Top Navigation**: Componentes adaptados según tamaño de pantalla
- **Content Area**: Padding responsive (3 en móvil, 6 en desktop)

```tsx
// Ejemplo de uso
<div className="p-3 md:p-6">
  {/* Content adapts padding based on screen size */}
</div>
```

### Grid Layouts

Todos los grids utilizan configuración responsive:

```tsx
// ExploreSection
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4 md:gap-6">
  {/* Cards automatically adjust */}
</div>

// PlacesSection
<div className="grid grid-cols-1 md:grid-cols-12 gap-0">
  {/* Stacks vertically on mobile, side-by-side on desktop */}
</div>
```

### Typography

Tamaños de texto adaptados:

```tsx
<h1 className="text-lg md:text-2xl font-bold">
  {/* Smaller on mobile, larger on desktop */}
</h1>
```

### Images

Alturas responsive en tarjetas:

```tsx
<div className="h-[350px] sm:h-[400px] lg:h-[458px]">
  {/* Image height scales with screen size */}
</div>
```

## Backend Responsive

### Middleware API

El archivo `src/middleware/responsiveAPI.ts` proporciona funciones para optimizar las respuestas del backend:

#### detectDevice

Detecta tipo de dispositivo desde User-Agent:

```typescript
import { detectDevice } from '@/middleware/responsiveAPI';

const deviceType = detectDevice(userAgent, width);
// Returns: 'mobile' | 'tablet' | 'desktop'
```

#### optimizePayload

Optimiza payload para dispositivos móviles:

```typescript
import { optimizePayload } from '@/middleware/responsiveAPI';

const optimized = optimizePayload(data, deviceType);
// Reduces image quality, limits array sizes for mobile
```

#### addDeviceHeaders

Añade headers de dispositivo a requests:

```typescript
import { addDeviceHeaders } from '@/middleware/responsiveAPI';

const headers = addDeviceHeaders();
// Adds: X-Device-Type, X-Screen-Width, X-User-Agent
```

#### getAdaptivePagination

Paginación adaptativa según dispositivo:

```typescript
import { getAdaptivePagination } from '@/middleware/responsiveAPI';

const { limit, offset } = getAdaptivePagination(deviceType);
// mobile: 10, tablet: 20, desktop: 50
```

## Utilities

### responsive.ts

Funciones útiles para comportamiento responsive:

```typescript
import { 
  responsiveClass,
  getResponsiveValue,
  isTouchDevice,
  formatTextForMobile 
} from '@/utils/responsive';

// Clases responsive
const classes = responsiveClass('base', 'mobile-class', 'tablet-class', 'desktop-class');

// Valores responsive
const value = getResponsiveValue(10, 20, 50, width);

// Detectar touch
const isTouch = isTouchDevice();

// Formatear texto
const text = formatTextForMobile(longText, 100, isMobile);
```

## Mejores Prácticas

### 1. Mobile-First

Siempre diseñar primero para móvil:

```tsx
// ✅ Correcto
<div className="p-3 md:p-6">

// ❌ Incorrecto
<div className="p-6 md:p-3">
```

### 2. Ocultar Elementos

Usar clases de Tailwind para ocultar:

```tsx
// Oculto en móvil
<div className="hidden md:block">

// Solo visible en móvil
<div className="block md:hidden">
```

### 3. Espaciado Responsive

Adaptar gaps, padding y margin:

```tsx
<div className="gap-2 md:gap-4 lg:gap-6">
  {/* Spacing increases with screen size */}
</div>
```

### 4. Touch Targets

Asegurar áreas táctiles suficientes en móvil (mínimo 44x44px):

```tsx
<button className="w-10 h-10 md:w-12 md:h-12">
  {/* Adequate touch area on mobile */}
</button>
```

### 5. Overflow Handling

Prevenir overflow horizontal:

```tsx
<div className="overflow-x-auto">
  <div className="min-w-max">
    {/* Wide content scrolls horizontally */}
  </div>
</div>
```

## Testing

### Breakpoints de Prueba

Probar en estos anchos mínimos:

- **Mobile**: 320px, 375px, 414px
- **Tablet**: 768px, 834px
- **Desktop**: 1024px, 1280px, 1920px

### Orientación

Probar tanto portrait como landscape en móvil/tablet.

### Touch Events

Verificar que todos los elementos interactivos funcionen con touch.

## Rendimiento

### Lazy Loading

Implementar lazy loading para imágenes:

```tsx
<img loading="lazy" src={image} alt={alt} />
```

### Code Splitting

React.lazy para componentes pesados:

```typescript
const HeavyComponent = lazy(() => import('./HeavyComponent'));
```

### Responsive Images

Usar srcset para diferentes resoluciones:

```tsx
<img 
  src="image-mobile.jpg"
  srcSet="image-mobile.jpg 375w, image-tablet.jpg 768w, image-desktop.jpg 1920w"
  sizes="(max-width: 768px) 100vw, (max-width: 1024px) 50vw, 33vw"
/>
```

## Accesibilidad

### Viewport Meta Tag

Ya incluido en index.html:

```html
<meta name="viewport" content="width=device-width, initial-scale=1.0">
```

### Focus States

Asegurar estados de focus visibles:

```tsx
<button className="focus:ring-2 focus:ring-primary focus:outline-none">
```

### ARIA Labels

Usar labels descriptivos para lectores de pantalla:

```tsx
<button aria-label="Open menu">
  <Menu />
</button>
```

## Mantenimiento

### Auditorías Regulares

- Ejecutar Lighthouse para móvil y desktop
- Verificar responsive en DevTools
- Probar en dispositivos reales

### Actualización de Breakpoints

Si se necesitan breakpoints custom, actualizar en:

1. `tailwind.config.ts`
2. `src/hooks/useResponsive.tsx`
3. Documentación

## Recursos

- [Tailwind Responsive Design](https://tailwindcss.com/docs/responsive-design)
- [MDN Media Queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries)
- [Web.dev Responsive Images](https://web.dev/responsive-images/)