gallery-tour/README.md

A modern, responsive, Airbnb-style gallery component for React.

# Airbnb Gallery React Library

A modern, responsive, Airbnb-style gallery component for React. Features a beautiful grid, sectioned view, and modal/lightbox with swipe, fade, and thumbnail navigation. Built with React, Tailwind CSS, and Embla Carousel.

---

## ✨ Features
- Responsive Airbnb-style grid (first image large, others small)
- Sectioned view for grouped images
- Modal/lightbox with swipe (mobile) and fade (desktop)
- Keyboard navigation, thumbnails, and custom modal buttons
- TypeScript support
- Easily theme with Tailwind CSS

---

## 🚀 Installation

```bash
npm install @your-org/airbnb-gallery embla-carousel-react
```

> **Peer dependencies:**
> - `react` (>=17)
> - `react-dom` (>=17)
> - `embla-carousel-react` (>=8)

---

## 🛠 Usage

```tsx
import { Gallery } from '@your-org/airbnb-gallery'

const images = [
  'https://images.unsplash.com/photo-1.jpg',
  'https://images.unsplash.com/photo-2.jpg',
  'https://images.unsplash.com/photo-3.jpg',
  // ...
]

function App() {
  return <Gallery images={images} />
}
```

### Sectioned View Example

```tsx
import { Gallery, GalleryImage } from '@your-org/airbnb-gallery'

const sectionedImages: GalleryImage[] = [
  { url: '...', label: 'Living Room', section: 'Living' },
  { url: '...', label: 'Kitchen', section: 'Kitchen' },
  // ...
]

<Gallery images={sectionedImages} mode="sections" sectionsTitle="Tour" />
```

---

## 📦 API

### `Gallery` Props
| Prop              | Type                              | Default              | Description                                 |
|-------------------|-----------------------------------|----------------------|---------------------------------------------|
| images            | `string[] \| GalleryImage[]`      | **required**         | Array of image URLs or objects              |
| mode              | `'grid' \| 'sections'`            | `'grid'`             | Display mode                                |
| buttonLabel       | `string`                          | `'Show all photos'`  | Text for the grid overlay button            |
| customModalButtons| `React.ReactNode`                 | `undefined`          | Custom buttons in modal (e.g. share, save)  |
| sectionsTitle     | `string`                          | `'Photos'`           | Title for sectioned view                    |

### `GalleryImage` Type
```ts
type GalleryImage = {
  url: string;
  label?: string;
  section?: string;
}
```

---

## 🎨 Customization
- Style with Tailwind CSS classes (override or extend as needed)
- Pass custom buttons (e.g. share, save) to the modal
- Use your own section/grouping logic with `GalleryImage[]`

---

## 🧪 Testing

This library is fully tested with Vitest and React Testing Library. To run tests:

```bash
npm test
```

---

## 📄 License

MIT