# 3D Hero Carousel Implementation Guide

## Overview
Successfully implemented a 3D rotating carousel with automatic image resizing and upload capabilities for the Vineyard Schools hero section.

## Features Implemented

### 1. **3D Carousel Component** (`resources/js/components/hero-carousel.tsx`)
- ✨ Smooth 3D rotation effect using CSS transforms
- 🔄 Auto-rotating carousel with configurable speed (default 5 seconds)
- ⏱️ Manual navigation with previous/next buttons
- 📍 Dot indicators to jump to specific slides
- 📊 Image counter (e.g., "1 / 3")
- 🎨 Professional UI with glassmorphism buttons

### 2. **Image Resizing** (`resources/js/lib/image-resize.ts`)
- 📦 Client-side image resizing before upload
- 🎯 Automatic aspect ratio preservation
- ⚙️ Configurable quality (default 80%)
- 📐 Configurable dimensions (default 1920x1080)
- 🔄 Support for multiple formats (JPEG, PNG, WebP)
- 📊 Image dimension detection

### 3. **Upload Hook** (`resources/js/hooks/use-image-upload.ts`)
- 📤 Custom React hook for image uploads
- ✅ Automatic image validation
- 🔍 File type and size checking
- 📲 FormData handling for multipart uploads
- ⚠️ Error handling and user feedback
- 🎯 Success callback support

### 4. **Backend Integration**
- **Model**: `app/Models/HeroImage.php`
  - Stores image metadata (path, dimensions, MIME type)
  - Scoped queries for ordered display
  - Getter for public URL

- **Controller**: `app/Http/Controllers/HeroImageController.php`
  - `store()`: Handles multipart image uploads with validation
  - `index()`: Returns all hero images ordered for display
  - `destroy()`: Deletes images from storage and database
  - `updateOrder()`: Allows reordering carousel slides

- **Migration**: Creates `hero_images` table with columns:
  - `id` (primary key)
  - `path` (storage path)
  - `original_name` (uploaded filename)
  - `alt` (accessibility text)
  - `width`, `height` (dimensions)
  - `file_size` (bytes)
  - `order` (display order)
  - `mime_type`
  - `timestamps`

- **Routes**: 
  - `POST /hero-images` - Upload images
  - `GET /hero-images` - Get all images
  - `DELETE /hero-images/{heroImage}` - Delete image
  - `POST /hero-images/order` - Update image order

### 5. **Home Page Integration** (`resources/js/pages/school/home.tsx`)
- Carousel positioned with responsive layout
- Text content alongside carousel
- Upload button integrated into carousel
- Automatic state management for uploaded images
- Graceful fallback when no images exist

### 6. **Controller Enhancement** (`app/Http/Controllers/PageController.php`)
- Passes hero images to home view
- Orders images for consistent display
- Maps image data to carousel format

## How to Use

### Uploading Images

1. **Via Carousel UI**:
   - Visit the home page
   - Click the upload button (camera icon) in the carousel
   - Select one or more images
   - Images are automatically resized and uploaded
   - New images appear in the carousel

2. **Programmatically**:
   ```javascript
   const { uploadImages } = useImageUpload({
       resizeOptions: {
           maxWidth: 1920,
           maxHeight: 1080,
           quality: 0.8
       }
   });

   const files = [/* File objects */];
   const uploaded = await uploadImages(files);
   ```

### Image Resizing

**Client-side (before upload)**:
```typescript
import { resizeImage } from '@/lib/image-resize';

const file = /* File object */;
const resized = await resizeImage(file, {
    maxWidth: 1920,
    maxHeight: 1080,
    quality: 0.8,
    format: 'jpeg'
});
```

### Testing

1. **Seeding sample data**:
   ```bash
   php artisan tinker
   App\Models\HeroImage::factory()->count(4)->create()
   exit
   ```

2. **Uploading images**:
   - Visit home page
   - Click upload button in hero carousel
   - Select images from your computer
   - Images are automatically resized and displayed

3. **Database**:
   ```bash
   php artisan tinker
   App\Models\HeroImage::all()
   ```

## File Structure

```
resources/
├── js/
│   ├── components/
│   │   └── hero-carousel.tsx         # Carousel component
│   ├── hooks/
│   │   └── use-image-upload.ts       # Upload hook
│   ├── lib/
│   │   └── image-resize.ts           # Image processing
│   └── pages/school/
│       └── home.tsx                  # Home page with carousel
├── css/
│   └── app.css                       # Carousel styles
└── ...

app/
├── Http/
│   └── Controllers/
│       ├── HeroImageController.php   # Image upload handler
│       └── PageController.php        # Home page controller
├── Models/
│   └── HeroImage.php                 # Hero image model
└── ...

database/
├── migrations/
│   └── *_create_hero_images_table.php
├── factories/
│   └── HeroImageFactory.php          # Sample data factory
└── ...

routes/
└── web.php                           # API routes for images
```

## Configuration

### Image Resizing Defaults
- **Max Width**: 1920px
- **Max Height**: 1080px
- **Quality**: 0.8 (80%)
- **Format**: JPEG

### Carousel Defaults
- **Auto-rotate**: Enabled
- **Rotation Speed**: 5000ms (5 seconds)
- **Storage Disk**: `public`
- **Upload Directory**: `hero-images/`

### Upload Validation
- **Max File Size**: 10MB per image
- **Allowed Types**: Images only
- **Multiple Files**: Supported

## Performance Optimizations

✅ **Client-side Image Resizing**: Reduces server bandwidth
✅ **GPU-accelerated Transforms**: Smooth 3D carousel animation
✅ **Lazy Image Loading**: Browser image optimization
✅ **Efficient Storage**: Single directory for hero images
✅ **Indexed Queries**: Fast image retrieval with `order` index

## Security Features

🔒 **File Type Validation**: Only images accepted
🔒 **Size Limits**: 10MB per image
🔒 **Path Sanitization**: Stored in dedicated directory
🔒 **CSRF Protection**: CSRF token in upload form
🔒 **Access Control**: Can add authorization checks

## Browser Support

- ✅ Chrome/Edge (transform, Canvas API)
- ✅ Firefox (transform, Canvas API)
- ✅ Safari (transform, Canvas API)
- ✅ Mobile browsers (iOS Safari, Chrome Mobile)

## Accessibility Features

♿ **Alt Text**: All images have alt text
♿ **Keyboard Navigation**: Arrow buttons accessible
♿ **ARIA Labels**: Dot indicators have aria-labels
♿ **Focus States**: Clear focus indicators
♿ **Reduced Motion**: Respects `prefers-reduced-motion`

## Next Steps

### Optional Enhancements
1. **Admin Dashboard**:
   - Manage hero images
   - Reorder carousel slides
   - Set alt text
   - Delete images

2. **Image Optimization**:
   - WebP format conversion
   - Lazy loading with Intersection Observer
   - Responsive image srcset

3. **Advanced Features**:
   - Image cropping interface
   - Filters/effects
   - Video background support
   - Parallax scrolling

4. **Analytics**:
   - Track carousel interactions
   - Click-through rates
   - User engagement metrics

## Troubleshooting

### Images not appearing
- Check storage is linked: `php artisan storage:link`
- Verify images uploaded to `storage/app/public/hero-images/`
- Check file permissions

### Upload failing
- Check max upload size in php.ini
- Verify write permissions on storage directory
- Check error logs: `tail -f storage/logs/laravel.log`

### Carousel not rotating
- Enable auto-rotate in HeroCarousel props
- Check for JavaScript errors in browser console
- Verify images are loaded

## Migrating from Old Hero Section

The old static hero image has been replaced. To restore it:

1. Comment out carousel in home page
2. Add fallback image display
3. Update CSS if needed

Current implementation provides much better UX with auto-resizing and management!