npm package: @oikihome/react-photo-gallery
Description: React component library for photo gallery UI.
Latest version: 0.4.0

# @react-photo-gallery/ui

A Tailwind + shadcn/ui powered component library exposing a responsive `PhotoGallery` alongside foundational UI primitives (`Button`, `Card`, `cn` helper, etc.).

## Installation

```bash
pnpm add @react-photo-gallery/ui
```

## Setup

### 1. Install Dependencies

```bash
npm install @oikihome/react-photo-gallery
# or
pnpm add @oikihome/react-photo-gallery
# or
yarn add @oikihome/react-photo-gallery
```

### 2. Tailwind Configuration

Add the package to your Tailwind content globs so class names authored inside the library are preserved during tree-shaking (ensure `tailwindcss` and `tailwindcss-animate` are installed in your app):

```ts
// tailwind.config.ts
export default {
  content: [
    "./src/**/*.{ts,tsx}",
    "./node_modules/@oikihome/react-photo-gallery/dist/**/*.{js,jsx}"
  ],
  plugins: [require("tailwindcss-animate")],
};
```

### 3. CSS Setup

**Option A: Import the provided CSS file (Recommended)**

```tsx
// In your main CSS file or index.tsx
import '@oikihome/react-photo-gallery/styles.css';
```

**Option B: Copy CSS custom properties to your CSS**

Copy the CSS custom properties from the package's `styles.css` file to your main CSS file:

```css
/* Add these CSS custom properties to your main CSS file */
:root {
  --background: 0 0% 100%;
  --foreground: 224 71.4% 4.1%;
  --card: 0 0% 100%;
  --card-foreground: 224 71.4% 4.1%;
  --popover: 0 0% 100%;
  --popover-foreground: 224 71.4% 4.1%;
  --primary: 220.9 39.3% 11%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96.1%;
  --secondary-foreground: 222.2 47.4% 11.2%;
  --muted: 210 40% 96.1%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --accent: 210 40% 96.1%;
  --accent-foreground: 222.2 47.4% 11.2%;
  --destructive: 0 84.2% 60.2%;
  --destructive-foreground: 210 40% 98%;
  --border: 214.3 31.8% 91.4%;
  --input: 214.3 31.8% 91.4%;
  --ring: 222.2 84% 4.9%;
  --radius: 0.75rem;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  --card: 222.2 41% 9.2%;
  --card-foreground: 210 40% 98%;
  --popover: 222.2 41% 9.2%;
  --popover-foreground: 210 40% 98%;
  --primary: 221.2 83.2% 53.3%;
  --primary-foreground: 210 40% 98%;
  --secondary: 217.2 32.6% 17.5%;
  --secondary-foreground: 210 40% 96.1%;
  --muted: 217.2 32.6% 17.5%;
  --muted-foreground: 215 20.2% 65.1%;
  --accent: 217.2 32.6% 17.5%;
  --accent-foreground: 210 40% 98%;
  --destructive: 0 62.8% 49.6%;
  --destructive-foreground: 210 40% 98%;
  --border: 217.2 32.6% 17.5%;
  --input: 217.2 32.6% 17.5%;
  --ring: 224.3 76.3% 48%;
  --radius: 0.75rem;
}
```

### 4. Troubleshooting Overlay Issues

If the photo gallery overlay (Showcase component) is not appearing properly or is not overlapping correctly with your UI:

1. **Ensure CSS is imported**: Make sure you've imported the CSS file as described in step 3
2. **Check z-index conflicts**: The overlay uses `z-index: 999999`. If you have elements with higher z-index values, they may appear above the overlay
3. **Verify Tailwind configuration**: Ensure your Tailwind config includes the package's content paths
4. **Check for CSS resets**: Some CSS resets might interfere with the component's positioning

## Usage

```tsx
import { Button, Card, CardContent, CardHeader, CardTitle, PhotoGallery } from "@oikihome/react-photo-gallery";

export function DemoGallery() {
  const photos = [
    { id: "sunset", src: "https://example.com/sunset.jpg", alt: "Sunset" },
    { id: "forest", src: "https://example.com/forest.jpg", alt: "Forest" },
  ];

  return (
    <Card>
      <CardHeader>
        <CardTitle>Latest Shots</CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <PhotoGallery photos={photos} columns={2} gap={16} />
        <Button variant="secondary">View all</Button>
      </CardContent>
    </Card>
  );
}
```

## Development scripts

```bash
pnpm turbo run dev --filter=@react-photo-gallery/ui   # tsup in watch mode
pnpm turbo run build --filter=@react-photo-gallery/ui # produce dist/ outputs
pnpm lint --filter=@react-photo-gallery/ui            # Biome checks
pnpm format --filter=@react-photo-gallery/ui          # Biome formatting
```

Tsup emits CommonJS, ESM, and type declarations to `dist/`, ready for publication.